How to Debug Story-Driven Development Workflow Failures in aios-core

Enable verbose debugging with *debug enable --verbose, inspect the workflow state file in .aios/*-state.yaml, and run the workflow in engine mode to expose hidden agent execution errors.

The aios-core repository orchestrates all development through story-driven workflows, primarily the story-development-cycle. When you need to debug story-driven development workflow failures in aios-core, systematic inspection of workflow definitions, state persistence, and agent logs will quickly isolate whether the issue stems from malformed YAML, corrupted state, or environment misconfiguration.

Verify the Workflow Definition in story-development-cycle.yaml

Workflow failures often originate in the definition file itself. The canonical configuration lives in .aios-core/development/workflows/story-development-cycle.yaml.

Check for syntax errors and structural validity:

# Quick lint using yq

yq eval '.' .aios-core/development/workflows/story-development-cycle.yaml

Confirm the file contains:

• A valid id field matching story-development-cycle
• A non-empty phases array with correctly defined steps
• Proper agent assignments for each step

If the file is missing, restore it from the repository:

curl -L https://github.com/SynkraAI/aios-core/raw/main/.aios-core/development/workflows/story-development-cycle.yaml > .aios-core/development/workflows/story-development-cycle.yaml

Inspect Workflow State Persistence

Runtime state is persisted to .aios/<instance-id>-state.yaml. Corrupted or stale state files cause workflows to stall or skip steps unexpectedly.

Examine the current state:

cat .aios/*-state.yaml | yq eval '.'

Look for these failure indicators:

• status is not active (indicates an aborted or crashed workflow)
• current_step references a non-optional step that never completed
• Missing steps entries suggesting state corruption

If the state file is unreadable or inconsistent, delete it to force a fresh start:

rm -f .aios/*-state.yaml

Enable Verbose Debugging with *debug Commands

The *debug CLI suite provides granular visibility into workflow execution. Enable verbose logging before reproducing the failure.

Activate debug mode:

*debug enable --verbose

Run the workflow and capture filtered error logs:

*run-workflow story-development-cycle continue
*debug logs error --filter "workflow"

For performance-related failures, generate and inspect a profile:

*debug show-profile

Examine the output for stack traces mentioning workflow-state-manager.js or specific agent task files like .aios-core/development/tasks/create-story.md.

Check Agent-Specific Execution Failures

Each workflow step delegates to an agent task (e.g., po-create-story, dev-create-brownfield-story). Failures here manifest as missing inputs or validation errors.

Common agent failure patterns include:

• Missing required arguments like story-title or story-file-path
• Validation errors in the task's JavaScript implementation
• Incorrect file paths passed to the agent

The state manager script at .aios-core/development/scripts/workflow-state-manager.js updates state after each agent execution. If you see the error Cannot skip non-optional step, consult the troubleshooting entry in the Workflows Guide for the specific step configuration.

Run the Workflow in Engine Mode

Engine mode executes the workflow end-to-end without interactive prompts, exposing hidden failures that might be masked by user input handling.

Execute in engine mode:

*run-workflow story-development-cycle start --mode engine

If the engine run succeeds but interactive mode fails, the issue likely involves missing prompt responses or incorrect user inputs. Re-run in guided mode and ensure all required inputs are provided.

Validate Environment and CLI Versions

Outdated CLI binaries can misinterpret newer workflow definitions or lack critical debug features.

Check current versions:

aios --version
npm list -g aios-core

Upgrade to the latest release:

npm install -g aios-core@latest

Also verify that you have the necessary permissions to read workflow definitions and write state files to the .aios/ directory.

Clear Stale State and Restart

After resolving definition errors, input issues, or environment problems, perform a clean restart to ensure no residual state interferes.

Remove stale state files:

rm -f .aios/*-state.yaml

Start fresh:

*run-workflow story-development-cycle start

Monitor the console output; each step should transition from pending to completed without errors.

Automated Validation Script

Add this Node.js validation script to your CI pipeline to catch workflow definition errors before they cause runtime failures:

// validate-story-workflow.js
import fs from 'fs';
import yaml from 'js-yaml';
import path from 'path';

const wfPath = path.resolve('.aios-core/development/workflows/story-development-cycle.yaml');

try {
  const doc = yaml.load(fs.readFileSync(wfPath, 'utf8'));

  // Basic sanity checks
  if (!doc.id || doc.id !== 'story-development-cycle') {
    throw new Error('Workflow ID mismatch');
  }
  if (!Array.isArray(doc.phases) || doc.phases.length === 0) {
    throw new Error('No phases defined');
  }
  console.log('✅ story-development-cycle workflow looks healthy');
  process.exit(0);
} catch (e) {
  console.error(`❌ Workflow validation failed: ${e.message}`);
  process.exit(1);
}

Add to package.json:

"scripts": {
  "validate:wf": "node validate-story-workflow.js"
}

Run in CI:

npm run validate:wf

Summary

• Verify the workflow definition in .aios-core/development/workflows/story-development-cycle.yaml for syntax errors and correct structure.
• Inspect state files in .aios/*-state.yaml to identify stalled steps or corruption.
• Enable verbose debugging using *debug enable --verbose and filter logs for workflow-specific errors.
• Check agent task failures in files like .aios-core/development/tasks/create-story.md for missing inputs or validation errors.
• Run in engine mode (--mode engine) to bypass interactive prompts and expose hidden failures.
• Validate environment by checking CLI versions and upgrading aios-core if necessary.
• Clear stale state and restart the workflow after fixes to ensure clean execution.

Frequently Asked Questions

What causes the "Cannot skip non-optional step" error in aios-core?

This error occurs when the workflow state manager attempts to bypass a step marked as optional: false in the workflow definition. Check the current_step field in .aios/*-state.yaml and verify that all previous non-optional steps in .aios-core/development/workflows/story-development-cycle.yaml have completed successfully.

How do I enable debug logging for story-driven workflows?

Run *debug enable --verbose before executing your workflow command. Then use *debug logs error --filter "workflow" to view filtered error logs, or *debug show-profile to inspect performance data if the workflow crashes. These commands are documented in the meta-agent commands reference.

Where does aios-core store workflow execution state?

Runtime state is persisted to .aios/<instance-id>-state.yaml files in your project root. The workflow-state-manager.js script updates these files after each step completion. If a workflow fails unexpectedly, inspect these YAML files for status fields that are not active or missing steps entries indicating corruption.

What is engine mode and when should I use it?

Engine mode (--mode engine) executes the story development workflow without interactive prompts, running all steps automatically end-to-end. Use this mode when you suspect that interactive input handling is masking underlying agent execution errors, or when running workflows in CI/CD pipelines where human interaction is not possible.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}