aios-core
Version:
Synkra AIOS: AI-Orchestrated System for Full Stack Development - Core Framework
961 lines (753 loc) • 21.4 kB
Markdown
# Execute Subtask (Coder Agent)
> **Phase:** Execution - Subtask
> **Owner Agent:** @dev
> **Pipeline:** execution-pipeline
## Purpose
Execute a single subtask from an implementation.yaml plan following the 13-step Coder Agent workflow. Includes mandatory self-critique phases (5.5 and 6.5) to catch bugs, edge cases, and pattern violations before committing. No steps can be skipped.
## autoClaude
```yaml
autoClaude:
version: '3.0'
pipelinePhase: execution-subtask
deterministic: true
elicit: false
composable: true
selfCritique:
enabled: true
checklistRef: self-critique-checklist.md
phases:
- '5.5'
- '6.5'
recovery:
trackAttempts: true
maxRetries: 3
rollbackOnFailure: true
inputs:
- name: subtaskId
type: string
required: true
description: "Subtask ID from implementation.yaml (e.g., 'ST-1.1')"
- name: storyId
type: string
required: true
description: 'Story ID for context loading'
- name: implementationPlan
type: file
path: docs/stories/{storyId}/implementation.yaml
required: true
- name: projectContext
type: file
path: .aios/project-context.yaml
required: false
- name: filesContext
type: file
path: docs/stories/{storyId}/files-context.yaml
required: false
outputs:
- name: subtaskResult
type: object
schema:
subtaskId: string
status: completed|failed|blocked
attempt: integer
filesModified: array
testsRun: array
selfCritiqueResults: object
- name: implementationPlanUpdate
type: file
path: docs/stories/{storyId}/implementation.yaml
action: update
verification:
type: command
command: "npm run test -- --grep '{subtaskId}'"
timeout: 120
contextRequirements:
projectContext: true
filesContext: true
implementationPlan: true
spec: false
```
## Command Integration (@dev)
```yaml
command:
name: '*execute-subtask'
syntax: '*execute-subtask {subtask-id}'
agent: dev
examples:
- '*execute-subtask ST-1.1'
- '*execute-subtask ST-2.3'
aliases:
- '*subtask'
- '*exec-subtask'
```
## The 13 Steps of the Coder Agent
### CRITICAL RULE: No Step Skipping
```yaml
step_enforcement:
description: |
ALL 13 steps MUST be executed in sequence.
No skipping, no shortcuts, no "optimization" by combining steps.
Each step has a specific purpose in the quality pipeline.
violations:
- Skipping self-critique phases (5.5, 6.5)
- Combining multiple steps into one
- Skipping tests "because code is simple"
- Not running linter "because it passed before"
on_violation:
action: halt
message: 'Step {step} cannot be skipped. Execute all 13 steps.'
```
## Step-by-Step Execution Flow
### Step 1: Load Context
```yaml
step_1:
id: '1'
name: 'Load Context'
description: 'Load project-context.yaml and files-context.yaml'
actions:
- action: load_file
path: .aios/project-context.yaml
required: false
fallback: 'Use codebase defaults'
- action: load_file
path: docs/stories/{storyId}/files-context.yaml
required: false
fallback: 'Generate minimal context from implementation.yaml'
validation:
check: 'Context files loaded or fallbacks applied'
onFailure: continue # Non-blocking
output:
projectContext: object
filesContext: object
```
### Step 2: Read Implementation Plan
```yaml
step_2:
id: '2'
name: 'Read Implementation Plan'
description: 'Load and parse implementation.yaml for current subtask'
actions:
- action: load_file
path: docs/stories/{storyId}/implementation.yaml
required: true
- action: parse_yaml
extract:
- subtasks
- dependencies
- currentStatus
validation:
check: 'implementation.yaml exists and is valid YAML'
onFailure: halt
output:
plan: object
subtasks: array
dependencies: object
```
### Step 3: Understand Current Subtask
```yaml
step_3:
id: '3'
name: 'Understand Current Subtask'
description: 'Extract and comprehend the specific subtask requirements'
actions:
- action: find_subtask
subtaskId: '{subtaskId}'
in: plan.subtasks
- action: extract
fields:
- title
- description
- acceptanceCriteria
- files
- dependencies
- estimatedComplexity
- action: verify_dependencies
check: 'All dependency subtasks are completed'
validation:
check: 'Subtask found and dependencies met'
onFailure: halt
error_cases:
- condition: 'Subtask not found'
action: halt
message: 'Subtask {subtaskId} not found in implementation.yaml'
- condition: 'Dependencies not met'
action: halt
message: 'Subtask depends on incomplete subtasks: {unmet_deps}'
output:
subtask: object
dependenciesMet: boolean
```
### Step 4: Plan Approach
```yaml
step_4:
id: '4'
name: 'Plan Approach'
description: 'Create detailed implementation approach before coding'
actions:
- action: analyze_requirements
from: subtask.acceptanceCriteria
- action: identify_files
create: subtask.files.create
modify: subtask.files.modify
- action: plan_changes
for_each_file:
- what: 'What changes are needed'
- where: 'Which functions/classes to modify'
- how: 'Implementation approach'
- action: identify_tests
unit: 'Unit tests needed'
integration: 'Integration tests if applicable'
validation:
check: 'Approach documented with specific file changes'
onFailure: retry
output:
approach:
files: array
changes: array
tests: array
```
### Step 5: Write Code
```yaml
step_5:
id: '5'
name: 'Write Code'
description: 'Implement the subtask according to the plan'
actions:
- action: implement
follow: approach
style: 'Match existing codebase patterns'
- action: for_each_file
in: approach.files
do:
- create_or_modify: file
- apply_changes: approach.changes[file]
- preserve: 'Existing functionality'
validation:
check: 'Code compiles/loads without syntax errors'
onFailure: fix_immediately
output:
filesModified: array
linesAdded: integer
linesRemoved: integer
```
### Step 5.5: Self-Critique (Post-Code)
```yaml
step_5_5:
id: "5.5"
name: "Self-Critique: Post-Code Review"
description: "MANDATORY self-review before running tests"
criticality: REQUIRED
checklist:
- id: "SC-5.5.1"
question: "Are there any predicted bugs in this code?"
action: "List potential bugs and fix them"
- id: "SC-5.5.2"
question: "Have all edge cases been handled?"
action: "Review boundaries, nulls, empty arrays, etc."
- id: "SC-5.5.3"
question: "Is error handling comprehensive?"
action: "Check try/catch, error messages, recovery paths"
- id: "SC-5.5.4"
question: "Are there any security vulnerabilities?"
action: "Check input validation, injection risks, auth"
- id: "SC-5.5.5"
question: "Does the code handle failure gracefully?"
action: "Review failure modes and user feedback"
process:
1. Pause implementation
2. Re-read all code written in Step 5
3. Answer each checklist question honestly
4. If ANY issues found:
- Document the issue
- Fix immediately
- Re-run this checklist
validation:
check: "All checklist items pass"
onFailure: fix_and_retry
# AC5 Story 4.4: Persist self-critique results to JSON
persist:
action: write_json
path: docs/stories/{storyId}/plan/self-critique-{subtaskId}-5.5.json
content:
subtaskId: "{subtaskId}"
phase: "5.5"
timestamp: "{timestamp}"
passed: "{selfCritiquePost.passed}"
issuesFound: "{selfCritiquePost.issuesFound}"
issuesFixed: "{selfCritiquePost.issuesFixed}"
checklist:
- id: "SC-5.5.1"
result: "{SC-5.5.1.result}"
- id: "SC-5.5.2"
result: "{SC-5.5.2.result}"
- id: "SC-5.5.3"
result: "{SC-5.5.3.result}"
- id: "SC-5.5.4"
result: "{SC-5.5.4.result}"
- id: "SC-5.5.5"
result: "{SC-5.5.5.result}"
output:
selfCritiquePost:
passed: boolean
issuesFound: array
issuesFixed: array
```
### Step 6: Run Tests
```yaml
step_6:
id: '6'
name: 'Run Tests'
description: 'Execute all relevant tests'
actions:
- action: run_command
command: 'npm run test'
timeout: 120000
- action: run_command
command: "npm run test:unit -- --grep '{subtask-related}'"
optional: true
validation:
check: 'All tests pass'
onFailure: goto step_7
output:
testsRun: array
testsPassed: integer
testsFailed: integer
coverage: object
```
### Step 6.5: Self-Critique (Post-Test)
```yaml
step_6_5:
id: "6.5"
name: "Self-Critique: Post-Test Review"
description: "MANDATORY self-review of code quality after tests"
criticality: REQUIRED
checklist:
- id: "SC-6.5.1"
question: "Does the code follow existing patterns in the codebase?"
action: "Compare with similar files, ensure consistency"
- id: "SC-6.5.2"
question: "Are there any hardcoded values that should be configurable?"
action: "Extract to constants, config, or environment variables"
- id: "SC-6.5.3"
question: "Are tests comprehensive enough?"
action: "Check happy path, error path, edge cases covered"
- id: "SC-6.5.4"
question: "Is documentation updated where needed?"
action: "Check JSDoc, README, inline comments for complex logic"
- id: "SC-6.5.5"
question: "Are there any code smells?"
action: "Review for duplication, long functions, complex conditionals"
- id: "SC-6.5.6"
question: "Will this code be maintainable by others?"
action: "Check naming, structure, separation of concerns"
process:
1. Pause after tests pass
2. Review code against checklist
3. If ANY issues found:
- Document the issue
- Fix the code
- Return to Step 6 (re-run tests)
validation:
check: "All checklist items pass and tests still pass"
onFailure: fix_and_retry
# AC5 Story 4.4: Persist self-critique results to JSON
persist:
action: write_json
path: docs/stories/{storyId}/plan/self-critique-{subtaskId}-6.5.json
content:
subtaskId: "{subtaskId}"
phase: "6.5"
timestamp: "{timestamp}"
passed: "{selfCritiqueQuality.passed}"
issuesFound: "{selfCritiqueQuality.issuesFound}"
issuesFixed: "{selfCritiqueQuality.issuesFixed}"
checklist:
- id: "SC-6.5.1"
result: "{SC-6.5.1.result}"
- id: "SC-6.5.2"
result: "{SC-6.5.2.result}"
- id: "SC-6.5.3"
result: "{SC-6.5.3.result}"
- id: "SC-6.5.4"
result: "{SC-6.5.4.result}"
- id: "SC-6.5.5"
result: "{SC-6.5.5.result}"
- id: "SC-6.5.6"
result: "{SC-6.5.6.result}"
output:
selfCritiqueQuality:
passed: boolean
issuesFound: array
issuesFixed: array
```
### Step 7: Fix Issues
```yaml
step_7:
id: '7'
name: 'Fix Issues'
description: 'Fix any test failures'
condition: 'Execute only if Step 6 had failures'
actions:
- action: analyze_failure
for_each: failedTest
identify: 'Root cause of failure'
- action: fix
apply: 'Minimal change to fix issue'
preserve: 'Working functionality'
- action: re_run_tests
verify: 'Fix resolved the issue'
max_iterations: 3
validation:
check: 'All tests pass after fixes'
onFailure: escalate
escalation:
after: 3
action: halt
message: 'Unable to fix test failures after 3 attempts'
output:
issuesFixed: array
iterationsUsed: integer
```
### Step 8: Run Linter
```yaml
step_8:
id: '8'
name: 'Run Linter'
description: 'Execute code linting'
actions:
- action: run_command
command: 'npm run lint'
timeout: 60000
validation:
check: 'No linting errors (warnings acceptable)'
onFailure: goto step_9
output:
lintErrors: array
lintWarnings: array
```
### Step 9: Fix Lint Issues
```yaml
step_9:
id: '9'
name: 'Fix Lint Issues'
description: 'Fix any linting errors'
condition: 'Execute only if Step 8 had errors'
actions:
- action: auto_fix
command: 'npm run lint:fix'
attempt: 1
- action: manual_fix
for_each: remainingError
if: "Auto-fix didn't resolve"
- action: re_run_linter
verify: 'All errors fixed'
validation:
check: 'No linting errors'
onFailure: halt
output:
errorsFixed: array
```
### Step 10: Verify Manually (If Needed)
```yaml
step_10:
id: '10'
name: 'Verify Manually'
description: 'Manual verification for UI/UX or complex logic'
condition: 'Execute if subtask involves UI or requires manual check'
triggers:
- subtask.type == "ui"
- subtask.type == "api"
- subtask.manualVerification == true
actions:
- action: identify_verification_steps
from: subtask.acceptanceCriteria
- action: execute_verification
type: browser|api|cli
document: 'Results of each step'
validation:
check: 'Manual verification passed'
onFailure: return_to_step_5
output:
manualVerification:
performed: boolean
steps: array
results: array
```
### Step 11: Update Plan Status
```yaml
step_11:
id: '11'
name: 'Update Plan Status'
description: 'Update implementation.yaml with subtask completion'
actions:
- action: update_yaml
path: docs/stories/{storyId}/implementation.yaml
changes:
- path: subtasks[{subtaskId}].status
value: completed
- path: subtasks[{subtaskId}].completedAt
value: '{timestamp}'
- path: subtasks[{subtaskId}].attempt
value: '{attemptNumber}'
- path: subtasks[{subtaskId}].filesModified
value: '{filesModified}'
- action: record_attempt
in: recovery_system
data:
subtaskId: '{subtaskId}'
storyId: '{storyId}'
attempt: '{attemptNumber}'
status: 'completed'
timestamp: '{timestamp}'
# AC7 Story 4.6: Update status.json for dashboard integration
- action: update_dashboard_status
script: |
const { PlanTracker } = require('.aios-core/infrastructure/scripts/plan-tracker.js');
const tracker = new PlanTracker({ storyId: '{storyId}' });
tracker.load();
tracker.updateStatusJson();
description: 'Auto-update status.json after subtask completion'
validation:
check: 'implementation.yaml updated successfully'
onFailure: retry
output:
planUpdated: boolean
dashboardUpdated: boolean
```
### Step 12: Commit Changes
```yaml
step_12:
id: '12'
name: 'Commit Changes'
description: 'Commit all changes with proper message'
actions:
- action: git_add
files: '{filesModified}'
- action: git_commit
message: |
feat({storyId}): {subtask.title}
- Completed subtask {subtaskId}
- Files: {filesModified.join(', ')}
Co-Authored-By: Claude <noreply@anthropic.com>
validation:
check: 'Commit created successfully'
onFailure: retry
output:
commitHash: string
commitMessage: string
```
### Step 13: Signal Completion
```yaml
step_13:
id: '13'
name: 'Signal Completion'
description: 'Report subtask completion and provide summary'
actions:
- action: generate_summary
include:
- subtaskId
- filesModified
- testsRun
- selfCritiqueResults
- attempt
- commitHash
- action: check_next_subtask
determine: 'What subtask is next (if any)'
- action: report
format: |
## Subtask {subtaskId} Complete
**Files Modified:** {filesModified.length}
**Tests Run:** {testsRun.length} passed
**Attempt:** {attempt}
**Commit:** {commitHash}
### Self-Critique Results
- Post-Code (5.5): {selfCritiquePost.issuesFixed.length} issues found and fixed
- Post-Test (6.5): {selfCritiqueQuality.issuesFixed.length} issues found and fixed
### Next Steps
{nextSubtask ? "Next: *execute-subtask " + nextSubtask : "All subtasks complete!"}
output:
summary: string
nextSubtask: string|null
completed: true
```
## Recovery System Integration
```yaml
recovery:
description: 'Track attempts and enable rollback on failure'
attempt_tracking:
storage: .aios/recovery/{storyId}/{subtaskId}.json
schema:
subtaskId: string
attempts: array
currentAttempt: integer
maxAttempts: 3
status: in_progress|completed|failed|blocked
on_failure:
- Record attempt with error details
- If attempts < maxAttempts:
action: retry_from_step_1
- If attempts >= maxAttempts:
action: halt
status: blocked
message: 'Subtask failed after {maxAttempts} attempts'
rollback:
enabled: true
command: 'git reset --hard {lastGoodCommit}'
trigger: 'Manual or on critical failure'
attempt_record:
fields:
- attemptNumber
- startedAt
- completedAt
- status
- error (if failed)
- filesModified
- commitHash (if completed)
```
## Error Handling
```yaml
errors:
- id: subtask-not-found
condition: 'Subtask ID not in implementation.yaml'
action: halt
message: 'Subtask {subtaskId} not found. Check implementation.yaml'
blocking: true
- id: dependencies-not-met
condition: 'Required subtasks not completed'
action: halt
message: 'Complete these subtasks first: {unmetDeps}'
blocking: true
- id: tests-failing-after-retries
condition: 'Tests fail after 3 fix attempts'
action: escalate
message: 'Unable to fix test failures. Manual intervention required.'
blocking: true
- id: self-critique-infinite-loop
condition: 'Self-critique finds issues > 5 times'
action: halt
message: 'Self-critique found recurring issues. Review approach.'
blocking: true
- id: implementation-yaml-corrupt
condition: 'Cannot parse implementation.yaml'
action: halt
message: 'implementation.yaml is invalid. Fix YAML syntax.'
blocking: true
```
## Quality Gates
```yaml
quality_gates:
- id: no-skipped-steps
description: 'All 13 steps must execute'
check: 'Step execution log contains all 13 steps'
- id: self-critique-passed
description: 'Both self-critique phases must pass'
check: 'selfCritiquePost.passed && selfCritiqueQuality.passed'
- id: tests-pass
description: 'All tests must pass'
check: 'testsFailed == 0'
- id: lint-clean
description: 'No lint errors'
check: 'lintErrors.length == 0'
- id: plan-updated
description: 'implementation.yaml reflects completion'
check: 'planUpdated == true'
```
## Self-Critique Checklist Reference
The task references `self-critique-checklist.md` which should contain:
```yaml
self_critique_checklist:
post_code_5_5:
- Predicted bugs identified and fixed
- Edge cases handled (null, empty, boundary)
- Error handling comprehensive
- Security vulnerabilities addressed
- Failure modes graceful
post_test_6_5:
- Follows codebase patterns
- No hardcoded values
- Tests comprehensive
- Documentation updated
- No code smells
- Maintainable by others
```
## Examples
### Example 1: Execute Simple Subtask
```bash
*execute-subtask ST-1.1
```
**Output:**
```
## Subtask ST-1.1 Complete
**Files Modified:** 2
- src/utils/validator.ts (created)
- src/utils/index.ts (modified)
**Tests Run:** 4 passed
**Attempt:** 1
**Commit:** abc123def
### Self-Critique Results
- Post-Code (5.5): 1 issue found and fixed (missing null check)
- Post-Test (6.5): 0 issues found
### Next Steps
Next: *execute-subtask ST-1.2
```
### Example 2: Subtask with Retry
```bash
*execute-subtask ST-2.3
```
**Output (attempt 1):**
```
Step 6: Tests failed
- test/api.test.ts: Expected 200, got 404
Step 7: Fixing issues...
- Added missing route handler
Step 6 (retry): All tests pass
## Subtask ST-2.3 Complete
**Attempt:** 1 (with internal fix)
...
```
## Pipeline Integration
```yaml
pipeline:
phase: execution
previous_phase: plan-create
next_phase: plan-verify (after all subtasks)
requires:
- implementation.yaml
optional:
- project-context.yaml
- files-context.yaml
on_completion:
- Update implementation.yaml status
- Record attempt in recovery system
- Check if all subtasks complete
triggers_next:
condition: 'All subtasks in implementation.yaml completed'
action: 'Proceed to plan-verify phase'
```
## Metadata
```yaml
metadata:
story: '4.3'
epic: 'Epic 4 - Execution Pipeline'
created: '2026-01-28'
author: '@dev (Dex)'
version: '1.0.0'
tags:
- execution-pipeline
- subtask
- coder-agent
- self-critique
- development
```