specsmd 0.0.0-dev.57 → 0.0.0-dev.58

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,14 @@ 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 |
+|----------|----------|------------|
+| Plan | `.specs-fire/runs/{run-id}/plan.md` | Agent (template: `skills/run-execute/templates/plan.md.hbs`) |
+| Run Log | `.specs-fire/runs/{run-id}/run.md` | **init-run.js script** (NEVER create manually) |
+| Test Report | `.specs-fire/runs/{run-id}/test-report.md` | Agent (template: `skills/run-execute/templates/test-report.md.hbs`) |
+| Walkthrough | `.specs-fire/runs/{run-id}/walkthrough.md` | Agent (template: `skills/walkthrough-generate/templates/walkthrough.md.hbs`) |
+
+**IMPORTANT**: The run folder and run.md are created by `init-run.js`. Do NOT use mkdir or Write tool to create these.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specsmd",
-  "version": "0.0.0-dev.57",
+  "version": "0.0.0-dev.58",
   "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": {