// Execute work items based on their assigned mode (autopilot, confirm, validate). Supports single-item and multi-item (batch/wide) runs.
| name | run-execute |
| description | Execute work items based on their assigned mode (autopilot, confirm, validate). Supports single-item and multi-item (batch/wide) runs. |
| version | 1.0.0 |
<progress_display> Show current position in workflow:
### Run Progress
- [ ] Run initialized (init-run.cjs)
- [ ] Context loaded
- [ ] Plan generated ← {current_step}
- [ ] Implementation
- [ ] Tests passing
- [ ] Code review
- [ ] Run completed (complete-run.cjs)
- [ ] Walkthrough generated
Update markers as you progress: [x] = done, ← current = active step </progress_display>
Before executing scripts, ensure required dependencies are installed: Run: npm list yaml --depth=0 2>/dev/null || echo "NOT_FOUND" Installing required dependency: yaml Run: npm install yaml| Package | Purpose | Install Command |
|---|---|---|
yaml | Parse/stringify state.yaml | npm install yaml |
<resume_detection critical="true"> Before starting execution, check if resuming an interrupted run:
Check state.yaml for runs.active[] array<check if="runs.active is empty">
<goto step="1">No active run, start fresh</goto>
</check>
<check if="runs.active has entries">
<action>Load active run from state.yaml runs.active[0]</action>
<action>Read scope (single/batch/wide) and work_items array</action>
<substep n="0a" title="Enumerate Work Item Status">
<action>For EACH work item in runs.active[0].work_items, classify by status:</action>
<action>Build status summary from state.yaml (NOT from artifact files):</action>
<format>
[DONE] {item-id} — completed
[WORKING] {item-id} (phase: {current_phase}) — in_progress
[PENDING] {item-id} — pending
</format>
<action>Count: completed={X}, in_progress={Y}, pending={Z}</action>
</substep>
<substep n="0b" title="Determine Resume Point for Current Item">
<action>Get current_item from state.yaml</action>
<action>Read current_phase from the current item's entry in work_items</action>
<determine_resume_point>
Use current_phase from state.yaml to determine resume point:
| current_phase | Resume At |
|---------------|-----------|
| plan (or unset) | Step 3 (Generate Plan) |
| execute | Step 5 (Implementation) |
| test | Step 6 (Run Tests) |
| review | Step 6b (Code Review) |
</determine_resume_point>
</substep>
<llm critical="true">
<mandate>NEVER call --complete-item for items with status "completed" — they are already done</mandate>
<mandate>NEVER re-execute steps (plan, implement, test) for completed items</mandate>
<mandate>ONLY work on the current_item identified in state.yaml</mandate>
<mandate>Use current_phase from state.yaml — do NOT infer phase from artifact file existence</mandate>
</llm>
<output>
Resuming run {run-id} ({scope}) for work item {current_item}.
Mode: {mode}
Phase: {current_phase}
Status: {completed_count} done, {in_progress_count} working, {pending_count} pending
Resuming at: Step {step_number}
</output>
</check>
<degrees_of_freedom> Varies by mode:
<artifact_timing critical="true"> Artifacts MUST be created at these points:
| Artifact | When Created | Created By |
|---|---|---|
| run.md | Start of run | init-run.cjs script |
| plan.md | BEFORE implementation (Step 4) | Agent using template |
| test-report.md | AFTER tests pass (Step 6) | Agent using template |
| review-report.md | AFTER test report (Step 6b) | code-review skill |
| walkthrough.md | After run completes (Step 8) | walkthrough-generate skill |
For batch runs: Append each work item's section to plan.md and test-report.md. </artifact_timing>
⛔ HARD GATE - SCRIPT EXECUTION REQUIRED ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ You MUST call init-run.cjs script. DO NOT use mkdir or create files directly. The script creates BOTH the folder AND run.md file. If you skip this, state.yaml will be inconsistent.<action>Prepare work items JSON array:</action>
<code>
# For single item:
node scripts/init-run.cjs {rootPath} {workItemId} {intentId} {mode}
# For batch/wide (multiple items):
node scripts/init-run.cjs {rootPath} --batch '[
{"id": "item-1", "intent": "intent-1", "mode": "autopilot"},
{"id": "item-2", "intent": "intent-1", "mode": "confirm"}
]' --scope=batch
</code>
<action>Parse script output for runId and runPath</action>
<action>Verify run.md was created in .specs-fire/runs/{run-id}/</action>
<check if="run.md not found">
<error>init-run.cjs failed to create run.md. Check script output.</error>
</check>
<action>Get current_item from state.yaml runs.active[0]</action>
<action>Load work item from .specs-fire/intents/{intent}/work-items/{id}.md</action>
<action>Read intent brief for broader context</action>
<action>Load project standards using hierarchical resolution:</action>
<standards_resolution critical="true">
<substep n="2a" title="Discover Standards Locations">
<action>Scan repository for: **/.specs-fire/standards/</action>
<action>Build list sorted by path depth (root = depth 0)</action>
<example>
depth 0: .specs-fire/standards/
depth 2: packages/api/.specs-fire/standards/
depth 2: apps/mobile/.specs-fire/standards/
</example>
</substep>
<substep n="2b" title="Load Constitution (Root Only)">
<action>Load .specs-fire/standards/constitution.md from ROOT</action>
<critical>IGNORE any constitution.md in nested directories</critical>
<critical>Constitution is ALWAYS inherited, NEVER overridden</critical>
<note>If constitution.md doesn't exist, skip gracefully</note>
</substep>
<substep n="2c" title="Resolve Module Standards">
<action>For each discovered standards location (excluding root):</action>
<resolution_algorithm>
FOR each standard_file IN [tech-stack.md, coding-standards.md,
testing-standards.md, system-architecture.md]:
IF {location}/standards/{standard_file} EXISTS:
→ USE this file for scope {location.parent_path}/**
ELSE:
→ Walk UP to find nearest ancestor with this file
→ USE ancestor's file (ultimately root if none found)
</resolution_algorithm>
</substep>
<substep n="2d" title="Present Standards with Scoping">
<action>Present loaded standards with clear path-based scoping:</action>
<output_format>
## Constitution (applies to ALL files)
[content of root constitution.md]
## Standards for {module_path}/** files
When editing files under {module_path}/, apply:
- Tech Stack: [resolved tech-stack.md for this scope]
- Coding Standards: [resolved coding-standards.md for this scope]
- Testing Standards: [resolved testing-standards.md for this scope]
## Default Standards (paths without specific scope)
For all other files, apply root standards.
</output_format>
</substep>
</standards_resolution>
<action>Determine execution mode from work item</action>
node scripts/update-checkpoint.cjs {rootPath} {runId} awaiting_approval --checkpoint=plan
<checkpoint>
<template_output section="plan">
## Implementation Plan for "{title}"
### Approach
{describe approach}
### Files to Create
{list files}
### Files to Modify
{list files}
### Tests
{list test files}
---
Approve plan? [Y/n/edit]
</template_output>
</checkpoint>
<check if="response == edit">
<ask>What changes to the plan?</ask>
<action>Adjust plan</action>
<action>Update plan.md with changes</action>
<goto step="3b"/>
</check>
<action>Mark checkpoint approved:</action>
<code>node scripts/update-checkpoint.cjs {rootPath} {runId} approved --checkpoint=plan</code>
<goto step="5"/>
node scripts/update-checkpoint.cjs {rootPath} {runId} awaiting_approval --checkpoint=plan
<checkpoint>
<template_output section="plan">
## Implementation Plan for "{title}"
Based on approved design document.
### Implementation Checklist
{from design doc}
### Files to Create
{list files}
### Files to Modify
{list files}
---
This is Checkpoint 2 of Validate mode.
Approve implementation plan? [Y/n/edit]
</template_output>
</checkpoint>
<check if="response == edit">
<ask>What changes to the plan?</ask>
<action>Adjust plan</action>
<action>Update plan.md with changes</action>
<goto step="3c"/>
</check>
<action>Mark checkpoint approved:</action>
<code>node scripts/update-checkpoint.cjs {rootPath} {runId} approved --checkpoint=plan</code>
<goto step="5"/>
<batch_handling critical="true">
<check if="batch/wide run AND plan.md already exists">
<action>Read existing plan.md content</action>
<action>Append new section for current work item:</action>
<format>
---
## Work Item: {work_item_id}
### Approach
{describe approach for this specific work item}
### Files to Create
{list files}
### Files to Modify
{list files}
### Tests
{list test files}
</format>
<action>Write updated plan.md (preserving previous sections)</action>
</check>
<check if="plan.md does not exist OR single run">
<action>Generate implementation plan</action>
<action>Save plan using template: templates/plan.md.hbs</action>
<action>Write to: .specs-fire/runs/{run-id}/plan.md</action>
</check>
</batch_handling>
<output>
Plan saved to: .specs-fire/runs/{run-id}/plan.md
(Autopilot mode - continuing without checkpoint)
</output>
<note>No checkpoint in autopilot - human can review plan.md while agent works</note>
node scripts/update-phase.cjs {rootPath} {runId} execute
<action>For each planned change:</action>
<substep n="5a">Implement the change</substep>
<substep n="5b">Track file operation (create/modify)</substep>
<substep n="5c">Record decisions made</substep>
<standards_application critical="true">
When editing a file at path X:
1. Find the LONGEST matching standards scope (most specific)
2. Apply those standards to the file
3. If no specific scope matches, apply root standards
<example>
Editing packages/api/src/handler.go
→ Apply "Standards for packages/api/**"
Editing scripts/deploy.sh
→ Apply "Default Standards" (root)
</example>
</standards_application>
<brownfield_rules>
<rule>READ existing code before modifying</rule>
<rule>MATCH existing naming conventions</rule>
<rule>FOLLOW existing patterns in the codebase</rule>
<rule>PRESERVE existing tests</rule>
<rule>USE module-specific standards when editing module files</rule>
</brownfield_rules>
node scripts/update-phase.cjs {rootPath} {runId} test
<action>Load testing standards from .specs-fire/standards/testing-standards.md</action>
<action>Write tests following testing standards:</action>
<substep>Unit tests for new/modified functions</substep>
<substep>Integration tests for API endpoints or workflows</substep>
<substep>Follow test naming and structure conventions</substep>
<action>Run test suite</action>
<check if="tests fail">
<output>Tests failed. Fixing issues...</output>
<action>Fix failing tests</action>
<action>Re-run tests</action>
</check>
<action>Validate acceptance criteria from work item</action>
<critical>Create test report AFTER tests pass</critical>
<batch_handling critical="true">
<check if="batch/wide run AND test-report.md already exists">
<action>Read existing test-report.md content</action>
<action>Append new section for current work item:</action>
<format>
---
## Work Item: {work_item_id}
### Test Results
- Passed: {passed_count}
- Failed: {failed_count}
- Skipped: {skipped_count}
### Acceptance Criteria Validation
{validation_results}
</format>
<action>Write updated test-report.md (preserving previous sections)</action>
</check>
<check if="test-report.md does not exist OR single run">
<action>Generate test report using template: templates/test-report.md.hbs</action>
<action>Write to: .specs-fire/runs/{run-id}/test-report.md</action>
</check>
</batch_handling>
<action>Include in test report:</action>
<substep>Test results summary (passed/failed/skipped)</substep>
<substep>Code coverage percentage</substep>
<substep>Acceptance criteria validation results</substep>
<substep>Any test warnings or notes</substep>
<output>Test report saved to: .specs-fire/runs/{run-id}/test-report.md</output>
node scripts/update-phase.cjs {rootPath} {runId} review
<critical>ALWAYS run code review after tests pass</critical>
<output>Running code review...</output>
<action>Invoke code-review skill with context:</action>
<code>
invoke-skill: code-review
context:
files_created: {files_created}
files_modified: {files_modified}
run_id: {run_id}
intent_id: {intent_id}
</code>
<invoke_skill>code-review</invoke_skill>
<note>
Code review skill will:
1. Review all files created/modified in this work item
2. Auto-fix no-brainer issues (unused imports, console.log, etc.)
3. Present suggestions requiring approval
4. Create review-report.md artifact
</note>
<check if="code-review returns suggestions">
<note>User interaction happens within code-review skill</note>
<action>Wait for code-review skill to complete</action>
</check>
<check if="code-review applied fixes">
<action>Re-run tests to verify fixes didn't break anything</action>
<check if="tests fail">
<output>Code review fixes caused test failure. Reverting...</output>
<action>Revert code review changes</action>
<action>Re-run tests to confirm passing</action>
</check>
</check>
<output>
Code review complete.
Review report: .specs-fire/runs/{run-id}/review-report.md
</output>
<llm critical="true">
<mandate>BATCH RUNS: You MUST loop until ALL items are done</mandate>
<mandate>NEVER call --complete-run until ALL items have artifacts</mandate>
<mandate>ALWAYS check pending count BEFORE deciding which flag to use</mandate>
</llm>
<substep n="7a" title="Check Batch Status">
<action>Read state.yaml runs.active[{runId}]</action>
<action>Get scope value: single, batch, or wide</action>
<action>Count work_items where status == "pending"</action>
<action>Store pending_count for decision</action>
</substep>
<substep n="7b" title="Route Based on Batch Status">
<check if="scope in [batch, wide] AND pending_count > 0">
<critical>DO NOT call --complete-run yet - more items remain!</critical>
<action>Call complete-run.cjs with --complete-item flag:</action>
<code>
node scripts/complete-run.cjs {rootPath} {runId} --complete-item
</code>
<action>Parse output JSON for nextItem and remainingItems</action>
<output>
Completed: {current_item}
Next item: {nextItem}
Remaining: {remainingItems} items
</output>
<goto step="2">MUST continue with next work item - loop back NOW</goto>
</check>
<check if="scope == single OR pending_count == 0">
<action>All items complete - finalize the run</action>
<action>Call complete-run.cjs with --complete-run flag:</action>
<code>
node scripts/complete-run.cjs {rootPath} {runId} --complete-run \
--files-created='[{"path":"...","purpose":"..."}]' \
--files-modified='[{"path":"...","changes":"..."}]' \
--tests=5 --coverage=85
</code>
<goto step="8"/>
</check>
</substep>
Work items completed: {count}
Files created: {count}
Files modified: {count}
Tests added: {count}
Artifacts:
- Run Log: .specs-fire/runs/{run-id}/run.md
- Plan: .specs-fire/runs/{run-id}/plan.md
- Test Report: .specs-fire/runs/{run-id}/test-report.md
- Code Review: .specs-fire/runs/{run-id}/review-report.md
- Walkthrough: .specs-fire/runs/{run-id}/walkthrough.md
</output>
<file_tracking_format>
files_created:
- path: src/auth/login.ts
purpose: Login endpoint handler
files_modified:
- path: src/routes/index.ts
changes: Added login route
decisions:
- decision: Use JWT for tokens
rationale: Stateless, works with load balancer
</file_tracking_format>
<run_folder_structure> After init-run.cjs creates a run:
.specs-fire/runs/run-fabriqa-2026-001/
├── run.md # Created by init-run.cjs, updated by complete-run.cjs
├── plan.md # Created BEFORE implementation (ALL modes - required)
├── test-report.md # Created AFTER tests pass (required)
├── review-report.md # Created by code-review skill (Step 6b)
└── walkthrough.md # Created by walkthrough-generate skill
The run.md contains:
<success_criteria> Run initialized via init-run.cjs script Standards loaded with hierarchical resolution Constitution loaded from root (if exists) Module-specific standards applied to module files plan.md created BEFORE implementation All work items implemented All tests pass test-report.md created AFTER tests pass code-review skill invoked and completed review-report.md created Run completed via complete-run.cjs script walkthrough.md generated </success_criteria>
Generate implementation walkthrough for human review after run completion. Documents decisions, changes, and verification steps.
Multi-perspective idea evaluation using Six Hats analysis, impact/feasibility scoring, and collaborative shortlisting.
Shape top ideas into actionable concept briefs using Disney Strategy — Dream, Reality, Critique.
Rapid idea generation with cross-domain diversity, anti-bias enforcement, and deep thinking.
Review code written during a run, auto-fix no-brainer issues, and suggest improvements requiring confirmation. Invoked after tests pass.
Display current run status and progress. Shows work item, mode, duration, and files changed.