The 13-Step Coder Agent Workflow in *execute-subtask: A Complete Technical Guide

The 13-step Coder Agent workflow is a mandatory sequential pipeline defined in .aiox-core/development/tasks/plan-execute-subtask.md that validates, tests, and commits code changes through two non-skippable self-critique checkpoints before marking any subtask complete.

The Coder Agent in SynkraAI/aiox-core orchestrates subtask execution through a rigorous 13-step workflow whenever developers invoke the *execute-subtask command. This autonomous pipeline transforms entries from implementation.yaml into production-ready code by enforcing strict quality gates, automated testing, and dual self-critique phases. Every step executes in strict sequence, with the system halting immediately if any mandatory checkpoint—particularly steps 5.5 and 6.5—is bypassed.

The 13 Steps Explained

The workflow processes each subtask from docs/stories/{storyId}/implementation.yaml through distinct phases, beginning with context loading and ending with plan updates. Each phase feeds sequentially into the next, creating an immutable execution chain.

Phase 1: Context and Planning (Steps 1–4)

Step 1: Load Context initializes the workflow by ingesting optional project-context.yaml and files-context.yaml files. These configurations provide global hints and file-level constraints, falling back to sensible defaults when absent.

Step 2: Read Implementation Plan opens the specific docs/stories/{storyId}/implementation.yaml file. The parser extracts the subtask list, dependency mappings, and current execution status to establish the work boundary.

Step 3: Understand Current Subtask locates the target {subtaskId} and verifies all declared dependencies are satisfied. If dependencies remain incomplete or the subtask identifier is invalid, the workflow terminates with a descriptive error.

Step 4: Plan Approach analyzes acceptance criteria to determine which files require creation or modification. This step generates an "approach" object documenting targeted files, change descriptions, and required test coverage.

Phase 2: Code Generation and First Critique (Steps 5–5.5)

Step 5: Write Code implements the changes defined in the approach object, ensuring all new code matches existing repository patterns and compiles without syntax errors. Files are created or edited in-place during this phase.

Step 5.5: Self-Critique (Post-Code) executes a mandatory checklist covering bug prediction, edge-case coverage, error handling, security vulnerabilities, and graceful failure modes. According to the step_enforcement block in .aiox-core/development/tasks/plan-execute-subtask.md, skipping this checkpoint aborts the entire run. Any failures force immediate fixes and a re-run of the checklist, with results persisted to self-critique-{subtaskId}-5.5.json.

Phase 3: Testing and Second Critique (Steps 6–6.5)

Step 6: Run Tests executes the full test suite via npm run test and optionally runs focused tests specific to the subtask. The workflow captures all output and immediately routes failures to the issue resolution phase.

Step 6.5: Self-Critique (Post-Test) applies a second mandatory checklist evaluating code style consistency, hard-coded values, test completeness, documentation quality, code smells, and maintainability. Results are saved to self-critique-{subtaskId}-6.5.json, and unresolved issues block progression.

Phase 4: Issue Resolution (Step 7)

Step 7: Fix Issues analyzes test failures and applies minimal surgical fixes. The workflow attempts automatic remediation up to three times, re-running tests after each iteration. If fixes fail after three attempts, the workflow escalates and halts, marking the subtask for manual inspection.

Phase 5: Quality Gates (Steps 8–9)

Step 8: Run Linter executes npm run lint to enforce style guidelines. While warnings are tolerated, any linting errors trigger the next phase.

Step 9: Fix Lint Issues first attempts automatic resolution via npm run lint:fix. If automatic fixes prove insufficient, the system falls back to manual corrections and re-runs the linter iteratively until zero errors remain.

Phase 6: Verification and Completion (Steps 10–11)

Step 10: Manual Verification (Optional) runs browser, API, or CLI checks for UI-heavy or complex subtasks. Results are recorded for audit purposes, and any failure returns the workflow to Step 5 for rework.

Step 11: Update Plan Status writes the completion status back to implementation.yaml, recording timestamps, attempt counts, and modified files. This final step also registers the attempt in the recovery system for full auditability.

How the Workflow Operates in Practice

The *execute-subtask command triggers a sophisticated orchestration mechanism defined in .aiox-core/core/execution/autonomous-build-loop.js. When a user invokes the command—documented in docs/guides/api-reference.md—the Dev agent (.aiox-core/development/agents/dev.md) receives the instruction and delegates execution to the autonomous build loop.

The loop calls executeSubtaskWithRetry, which wraps the core executeSubtask function with resilience logic. This orchestrator respects the recovery configuration—specifically maxRetries: 3 and rollbackOnFailure: true—to handle transient failures without manual intervention.

# Execute subtask ST-2.1 from story "my-feature"

*execute-subtask ST-2.1

Under the hood, the JavaScript implementation processes the command:

// From autonomous-build-loop.js
await buildLoop.executeSubtaskWithRetry({
  subtaskId: 'ST-2.1',
  storyId: 'my-feature',
  implementationPlan: `docs/stories/my-feature/implementation.yaml`,
});

The system automatically persists self-critique artifacts to:

• docs/stories/{storyId}/plan/self-critique-ST-2.1-5.5.json
• docs/stories/{storyId}/plan/self-critique-ST-2.1-6.5.json

Critical Implementation Details

The self-critique checklist defined in .aiox-core/product/checklists/self-critique-checklist.md powers the mandatory validation at steps 5.5 and 6.5. These checkpoints are not advisory—they are enforced by the step_enforcement logic that aborts execution if skipped.

The workflow strictly forbids parallel execution or step reordering. Each phase must complete successfully before the next begins, creating a deterministic pipeline that ensures code quality and traceability.

Summary

• The 13-step Coder Agent workflow executes sequentially through .aiox-core/development/tasks/plan-execute-subtask.md to process *execute-subtask commands.
• Steps 5.5 and 6.5 are mandatory self-critique checkpoints that persist JSON results and cannot be bypassed without aborting the run.
• The system enforces three retry attempts (maxRetries: 3) for issue resolution before escalating to manual intervention.
• All execution is orchestrated by executeSubtaskWithRetry in autonomous-build-loop.js, with the Dev agent handling command dispatch.
• Successful completion updates implementation.yaml and generates audit artifacts including self-critique JSON files and modified file manifests.

Frequently Asked Questions

What happens if I try to skip step 5.5 or 6.5 in the Coder Agent workflow?

The workflow immediately halts with an informative error. According to the step_enforcement block in .aiox-core/development/tasks/plan-execute-subtask.md, these self-critique checkpoints are mandatory gates that cannot be bypassed. Any attempt to skip them aborts the entire execution and prevents the subtask from reaching completion status.

How does the autonomous build loop handle test failures during the 13-step workflow?

The executeSubtaskWithRetry function in autonomous-build-loop.js captures test output from Step 6 and routes failures to Step 7 (Fix Issues). The system attempts automatic remediation up to three times, re-running tests after each fix iteration. If the subtask still fails after three attempts, the workflow marks it as failed and halts, preserving all attempt logs for manual review.

Where are the self-critique results stored after running *execute-subtask?

The workflow persists checkpoint results as JSON files within the story directory structure. Step 5.5 generates self-critique-{subtaskId}-5.5.json and Step 6.5 generates self-critique-{subtaskId}-6.5.json, both typically stored under docs/stories/{storyId}/plan/. These files contain the full checklist evaluation results for audit and debugging purposes.

Can I run manual verification steps for UI-heavy subtasks in the Coder Agent workflow?

Yes. Step 10 (Manual Verification) is specifically designed for complex or UI-heavy subtasks. While optional for simple changes, this step allows the agent to run browser, API, or CLI checks and record the results. If manual verification fails, the workflow automatically returns to Step 5 (Write Code) for rework rather than proceeding to update the implementation plan.

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