fabriqaai/specs.md/run-execute

<objective> Execute work items based on their assigned mode (autopilot, confirm, validate). Supports both single-item and multi-item (batch/wide) runs. </objective>

<progress_display> Show current position in workflow:

```text ### 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>

<prerequisites> Before executing scripts, ensure required dependencies are installed:

<step n="1" title="Check yaml Package"> <action>Run: npm list yaml --depth=0 2>/dev/null || echo "NOT_FOUND"</action> <check if="output contains NOT_FOUND"> <output>Installing required dependency: yaml</output> <action>Run: npm install yaml</action> </check> </step>

</prerequisites>

<triggers>

• Pending work item ready for execution
• Resumed from interrupted run
• Batch of work items passed from run-plan

</triggers>

<resume_detection critical="true"> Before starting execution, check if resuming an interrupted run:

<step n="0" title="Check for Active Run"> <action>Check state.yaml for runs.active[] array</action>

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

</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> </step> </resume_detection>

<degrees_of_freedom> Varies by mode:

• Autopilot: LOW — Execute standard patterns decisively
• Confirm: MEDIUM — Present plan, adjust based on feedback
• Validate: LOW — Follow approved design precisely

</degrees_of_freedom>

<llm critical="true"> <mandate>USE SCRIPTS — NEVER bypass init-run.cjs or complete-run.cjs</mandate> <mandate>ALWAYS CREATE plan.md — Create plan BEFORE implementation starts (ALL modes)</mandate> <mandate>ALWAYS CREATE test-report.md — Create test report AFTER tests complete</mandate> <mandate>ALWAYS RUN code-review — Invoke code-review skill after tests pass</mandate> <mandate>TRACK ALL FILE OPERATIONS — Every create, modify MUST be recorded</mandate> <mandate>NEVER skip tests — Tests are mandatory, not optional</mandate> <mandate>FOLLOW BROWNFIELD RULES — Read before write, match existing patterns</mandate> </llm>

<artifact_timing critical="true"> Artifacts MUST be created at these points:

For batch runs: Append each work item's section to plan.md and test-report.md. </artifact_timing>

<flow> <step n="1" title="Initialize Run"> <hard_gate> ⛔ 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. </hard_gate>

<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> </step>

<step n="2" title="Load Work Item Context"> <note>For batch runs, repeat steps 2-6b for each work item</note>

<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> </step>

<step n="3a" title="Autopilot Mode" if="mode == autopilot"> <output> Executing in Autopilot mode (0 checkpoints). Work item: {title} </output> <goto step="4"/> </step>

<step n="3b" title="Confirm Mode" if="mode == confirm"> <action>Generate implementation plan</action> <action>Save plan IMMEDIATELY using template: templates/plan.md.hbs</action> <action>Write to: .specs-fire/runs/{run-id}/plan.md</action> <output>Plan saved to: .specs-fire/runs/{run-id}/plan.md</output> <action>Mark checkpoint as waiting:</action> <code>node scripts/update-checkpoint.cjs {rootPath} {runId} awaiting_approval --checkpoint=plan</code>

<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"/> </step>

<step n="3c" title="Validate Mode" if="mode == validate"> <action>Load design doc from .specs-fire/intents/{intent}/work-items/{id}-design.md</action> <action>Generate implementation plan based on design</action> <action>Save plan IMMEDIATELY using template: templates/plan.md.hbs</action> <action>Write to: .specs-fire/runs/{run-id}/plan.md</action> <action>Include reference to design doc in plan</action> <output>Plan saved to: .specs-fire/runs/{run-id}/plan.md</output> <action>Mark checkpoint as waiting:</action> <code>node scripts/update-checkpoint.cjs {rootPath} {runId} awaiting_approval --checkpoint=plan</code>

<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"/> </step>