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

> Debug story-driven development failures in aios-core. Use verbose debugging, inspect state files, and run in engine mode to reveal agent execution errors.

- Repository: [SynkraAI/aios-core](https://github.com/synkraai/aios-core)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/development/workflows/story-development-cycle.yaml).

Check for syntax errors and structural validity:

```bash

# 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:

```bash
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:

```bash
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:

```bash
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:

```bash
*debug enable --verbose

```

Run the workflow and capture filtered error logs:

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

```

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

```bash
*debug show-profile

```

Examine the output for stack traces mentioning [`workflow-state-manager.js`](https://github.com/SynkraAI/aios-core/blob/main/workflow-state-manager.js) or specific agent task files like [`.aios-core/development/tasks/create-story.md`](https://github.com/SynkraAI/aios-core/blob/main/.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`](https://github.com/SynkraAI/aios-core/blob/main/.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:

```bash
*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:

```bash
aios --version
npm list -g aios-core

```

Upgrade to the latest release:

```bash
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:

```bash
rm -f .aios/*-state.yaml

```

Start fresh:

```bash
*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:

```javascript
// 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`](https://github.com/SynkraAI/aios-core/blob/main/package.json):

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

```

Run in CI:

```bash
npm run validate:wf

```

## Summary

- **Verify the workflow definition** in [`.aios-core/development/workflows/story-development-cycle.yaml`](https://github.com/SynkraAI/aios-core/blob/main/.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`](https://github.com/SynkraAI/aios-core/blob/main/.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`](https://github.com/SynkraAI/aios-core/blob/main/.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`](https://github.com/SynkraAI/aios-core/blob/main/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.