specsmd 0.0.0-dev.57 → 0.0.0-dev.59

package/flows/fire/agents/builder/agent.md

@@ -41,11 +41,12 @@ When routed from Orchestrator or user invokes this agent:
 ### Autopilot Mode (0 checkpoints)
 
 ```text
-[1] Load work item and context
-[2] Execute implementation directly
-[3] Run tests
-[4] Generate walkthrough
-[5] Mark complete
+[1] Call init-run.js to initialize run (creates run folder + run.md)
+[2] Load work item and context
+[3] Execute implementation directly
+[4] Run tests
+[5] Generate walkthrough
+[6] Call complete-run.js to finalize (updates state.yaml + run.md)
 ```
 
 For: Bug fixes, minor updates, low-complexity tasks.
@@ -53,15 +54,16 @@ For: Bug fixes, minor updates, low-complexity tasks.
 ### Confirm Mode (1 checkpoint)
 
 ```text
-[1] Load work item and context
-[2] Generate implementation plan
-[3] CHECKPOINT: Present plan to user
+[1] Call init-run.js to initialize run (creates run folder + run.md)
+[2] Load work item and context
+[3] Generate implementation plan
+[4] CHECKPOINT: Present plan to user
     → User confirms → Continue
     → User modifies → Adjust plan, re-confirm
-[4] Execute implementation
-[5] Run tests
-[6] Generate walkthrough
-[7] Mark complete
+[5] Execute implementation
+[6] Run tests
+[7] Generate walkthrough
+[8] Call complete-run.js to finalize (updates state.yaml + run.md)
 ```
 
 For: Standard features, medium-complexity tasks.
@@ -69,16 +71,17 @@ For: Standard features, medium-complexity tasks.
 ### Validate Mode (2 checkpoints)
 
 ```text
-[1] Load work item and design doc
-[2] CHECKPOINT 1: Design doc review (already done by Planner)
-[3] Generate implementation plan
-[4] CHECKPOINT 2: Present plan to user
+[1] Call init-run.js to initialize run (creates run folder + run.md)
+[2] Load work item and design doc
+[3] CHECKPOINT 1: Design doc review (already done by Planner)
+[4] Generate implementation plan
+[5] CHECKPOINT 2: Present plan to user
     → User confirms → Continue
     → User modifies → Adjust plan, re-confirm
-[5] Execute implementation
-[6] Run tests
-[7] Generate walkthrough
-[8] Mark complete
+[6] Execute implementation
+[7] Run tests
+[8] Generate walkthrough
+[9] Call complete-run.js to finalize (updates state.yaml + run.md)
 ```
 
 For: Security features, payments, core architecture.
@@ -136,6 +139,36 @@ files_modified:
 
 ---
 
+## CRITICAL: Script Usage for State Management
+
+**NEVER edit `.specs-fire/state.yaml` or run artifacts directly.**
+
+All state changes MUST go through the scripts in `skills/run-execute/scripts/`:
+
+| Action | Script | Direct Editing |
+|--------|--------|----------------|
+| Initialize run | `node scripts/init-run.js ...` | ❌ FORBIDDEN |
+| Complete work item | `node scripts/complete-run.js ... --complete-item` | ❌ FORBIDDEN |
+| Complete run | `node scripts/complete-run.js ... --complete-run` | ❌ FORBIDDEN |
+| Create run folder | (handled by init-run.js) | ❌ NO mkdir |
+| Create run.md | (handled by init-run.js) | ❌ NO direct write |
+| Update state.yaml | (handled by scripts) | ❌ NO direct edit |
+
+**Why scripts are mandatory:**
+- Scripts atomically update both state.yaml AND run artifacts
+- Scripts track run history in `runs.completed`
+- Scripts handle batch run state transitions
+- Scripts ensure consistent state across interruptions
+
+**If you find yourself about to:**
+- `mkdir .specs-fire/runs/run-XXX` → STOP, use `init-run.js`
+- Edit `state.yaml` directly → STOP, use `complete-run.js`
+- Write `run.md` directly → STOP, use `init-run.js`
+
+See `skills/run-execute/SKILL.md` for full script documentation.
+
+---
+
 ## Brownfield Rules
 
 When working in existing codebases:
@@ -165,12 +198,25 @@ Each run creates a folder with its artifacts:
 - **test-report.md** — Test results and acceptance criteria validation
 - **walkthrough.md** — Human-readable summary after completion
 
-| Artifact | Location | Template |
-|----------|----------|----------|
-| Plan | `.specs-fire/runs/{run-id}/plan.md` | `skills/run-execute/templates/plan.md.hbs` |
-| Run Log | `.specs-fire/runs/{run-id}/run.md` | (generated by script) |
-| Test Report | `.specs-fire/runs/{run-id}/test-report.md` | `skills/run-execute/templates/test-report.md.hbs` |
-| Walkthrough | `.specs-fire/runs/{run-id}/walkthrough.md` | `skills/walkthrough-generate/templates/walkthrough.md.hbs` |
+| Artifact | Location | Created By | When |
+|----------|----------|------------|------|
+| Run Log | `.specs-fire/runs/{run-id}/run.md` | **init-run.js script** | At run START |
+| Plan | `.specs-fire/runs/{run-id}/plan.md` | Agent (template) | BEFORE implementation |
+| Test Report | `.specs-fire/runs/{run-id}/test-report.md` | Agent (template) | AFTER tests pass |
+| Walkthrough | `.specs-fire/runs/{run-id}/walkthrough.md` | Agent (template) | After run END |
+
+**CRITICAL - Artifact Timing**:
+```
+1. init-run.js → creates run.md (with all work items listed)
+2. BEFORE implementation → create plan.md (ALL modes, not just confirm/validate)
+3. AFTER tests pass → create test-report.md
+4. After run completes → create walkthrough.md via skill
+```
+
+**IMPORTANT**:
+- The run folder and run.md are created by `init-run.js`. Do NOT use mkdir or Write tool to create these.
+- plan.md is REQUIRED for ALL modes (autopilot, confirm, validate). In autopilot mode, the plan is created but no checkpoint pause occurs.
+- test-report.md is REQUIRED after tests complete.
 
 ---
 

package/flows/fire/agents/builder/skills/run-execute/SKILL.md

@@ -87,11 +87,25 @@ For runs with multiple work items:
 
   <mandate>
     USE SCRIPTS — Never bypass init-run.js or complete-run.js.
+    ALWAYS CREATE plan.md — Create plan BEFORE implementation starts (all modes).
+    ALWAYS CREATE test-report.md — Create test report AFTER tests complete.
     TRACK ALL FILE OPERATIONS — Every create, modify must be recorded.
     NEVER skip tests — Tests are mandatory, not optional.
     FOLLOW BROWNFIELD RULES — Read before write, match existing patterns.
   </mandate>
 
+  <artifact-timing critical="true">
+    Artifacts MUST be created at these points:
+    | Artifact | When Created | Created By |
+    |----------|--------------|------------|
+    | run.md | Start of run | init-run.js script |
+    | plan.md | BEFORE implementation (Step 4) | Agent using template |
+    | test-report.md | AFTER tests pass (Step 6) | Agent using template |
+    | 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>
+
   <step n="1" title="Initialize Run">
     <critical>
       MUST call init-run.js script. DO NOT use mkdir directly.
@@ -137,11 +151,16 @@ For runs with multiple work items:
       Executing in Autopilot mode (0 checkpoints).
       Work item: {title}
     </output>
-    <goto step="5"/>
+    <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>
     <checkpoint>
       <output>
         ## Implementation Plan for "{title}"
@@ -165,18 +184,21 @@ For runs with multiple work items:
     <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>
-    <check if="response == y">
-      <action>Save approved plan using template: templates/plan.md.hbs</action>
-      <action>Write to: .specs-fire/runs/{run-id}/plan.md</action>
-    </check>
     <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>
     <checkpoint>
       <output>
         ## Implementation Plan for "{title}"
@@ -200,16 +222,24 @@ For runs with multiple work items:
     <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>
-    <check if="response == y">
-      <action>Save approved plan 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>
-    </check>
     <goto step="5"/>
   </step>
 
+  <step n="4" title="Generate Plan (Autopilot Only)" if="mode == autopilot">
+    <note>Confirm and Validate modes already saved plan in Step 3b/3c</note>
+    <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>
+    <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>
+  </step>
+
   <step n="5" title="Execute Implementation">
     <action>For each planned change:</action>
     <substep n="5a">Implement the change</substep>
@@ -241,6 +271,18 @@ For runs with multiple work items:
     </check>
 
     <action>Validate acceptance criteria from work item</action>
+
+    <critical>Create test report AFTER tests pass</critical>
+    <action>Generate test report using template: templates/test-report.md.hbs</action>
+    <action>Write to: .specs-fire/runs/{run-id}/test-report.md</action>
+    <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>
   </step>
 
   <step n="7" title="Complete Current Work Item">
@@ -288,6 +330,8 @@ For runs with multiple work items:
 
       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
       - Walkthrough: .specs-fire/runs/{run-id}/walkthrough.md
     </output>
   </step>
@@ -392,10 +436,17 @@ After init-run.js creates a run:
 ```
 .specs-fire/runs/run-001/
 ├── run.md          # Created by init-run.js, updated by complete-run.js
-├── plan.md         # Created during confirm/validate mode (optional)
+├── plan.md         # Created BEFORE implementation (ALL modes - required)
+├── test-report.md  # Created AFTER tests pass (required)
 └── walkthrough.md  # Created by walkthrough-generate skill
 ```
 
+**Artifact Creation Timeline:**
+1. `run.md` — Created at run start by init-run.js
+2. `plan.md` — Created BEFORE implementation begins (Step 4)
+3. `test-report.md` — Created AFTER tests pass (Step 6)
+4. `walkthrough.md` — Created after run completes (Step 8)
+
 The run.md contains:
 - All work items with their statuses
 - Current item being executed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specsmd",
-  "version": "0.0.0-dev.57",
+  "version": "0.0.0-dev.59",
   "description": "Multi-agent orchestration system for AI-native software development. Delivers AI-DLC, Agile, and custom SDLC flows as markdown-based agent systems.",
   "main": "lib/installer.js",
   "bin": {