specsmd 0.0.0-dev.56 → 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/flows/fire/agents/builder/skills/run-execute/SKILL.md

@@ -1,6 +1,7 @@
 # Skill: Run Execute
 
-Execute a work item based on its assigned mode (autopilot, confirm, validate).
+Execute work items based on their assigned mode (autopilot, confirm, validate).
+Supports both single-item and multi-item (batch/wide) runs.
 
 ---
 
@@ -33,6 +34,7 @@ Before executing scripts, ensure required dependencies are installed:
 
 - Pending work item ready for execution
 - Resumed from interrupted run
+- Batch of work items passed from run-plan
 
 ---
 
@@ -45,26 +47,82 @@ Before executing scripts, ensure required dependencies are installed:
 
 ---
 
+## Critical Requirements
+
+### MUST Use Scripts - Never Bypass
+
+**CRITICAL**: You MUST call the scripts. DO NOT use mkdir or manual file creation.
+
+| Action | CORRECT | WRONG |
+|--------|---------|-------|
+| Initialize run | `node scripts/init-run.js ...` | `mkdir .specs-fire/runs/run-001` |
+| Complete item | `node scripts/complete-run.js ... --complete-item` | Manual state editing |
+| Complete run | `node scripts/complete-run.js ... --complete-run` | Manual state editing |
+
+The scripts:
+- Create run folder AND run.md together
+- Update state.yaml atomically
+- Track run history in runs.completed
+- Handle batch run state transitions
+
+### Batch Run Execution Flow
+
+For runs with multiple work items:
+
+```
+1. Call init-run.js ONCE at start (creates run.md with ALL items)
+2. Execute each work item sequentially:
+   - Load item context
+   - Execute based on mode (autopilot/confirm/validate)
+   - Call complete-run.js --complete-item after each
+3. Call complete-run.js --complete-run after final item
+```
+
+---
+
 ## Workflow
 
 ```xml
 <skill name="run-execute">
 
   <mandate>
+    USE SCRIPTS — Never bypass init-run.js or complete-run.js.
     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>
 
   <step n="1" title="Initialize Run">
-    <action script="scripts/init-run.js">Create run record</action>
-    <action>Generate run ID: run-{NNN}</action>
-    <action>Create folder: .specs-fire/runs/{run-id}/</action>
-    <action>Set active_run in state.yaml</action>
+    <critical>
+      MUST call init-run.js script. DO NOT use mkdir directly.
+      The script creates BOTH the folder AND run.md file.
+    </critical>
+
+    <action>Prepare work items JSON array:</action>
+    <code>
+      # For single item:
+      node scripts/init-run.js {rootPath} {workItemId} {intentId} {mode}
+
+      # For batch/wide (multiple items):
+      node scripts/init-run.js {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.js failed to create run.md. Check script output.</error>
+    </check>
   </step>
 
-  <step n="2" title="Load Context">
-    <action>Read work item from .specs-fire/intents/{intent}/work-items/{id}.md</action>
+  <step n="2" title="Execute Work Items Loop">
+    <note>For batch runs, repeat steps 2-6 for each work item</note>
+
+    <action>Get current_item from state.yaml active_run</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 ALL project standards:</action>
     <substep>.specs-fire/standards/tech-stack.md — Technology choices</substep>
@@ -183,15 +241,36 @@ Before executing scripts, ensure required dependencies are installed:
     </check>
 
     <action>Validate acceptance criteria from work item</action>
-    <action>Measure coverage against target from testing-standards.md</action>
-    <action>Generate test report using template: templates/test-report.md.hbs</action>
-    <action>Save to: .specs-fire/runs/{run-id}/test-report.md</action>
   </step>
 
-  <step n="7" title="Complete Run">
-    <action script="scripts/complete-run.js">Finalize run record</action>
-    <action>Update state.yaml (clear active_run, mark work item complete)</action>
-    <action>Generate run log: .specs-fire/runs/{run-id}/run.md</action>
+  <step n="7" title="Complete Current Work Item">
+    <critical>
+      MUST call complete-run.js script. Check if more items remain.
+    </critical>
+
+    <check if="batch run with more items pending">
+      <action>Call complete-run.js with --complete-item flag:</action>
+      <code>
+        node scripts/complete-run.js {rootPath} {runId} --complete-item
+      </code>
+      <action>Parse output for nextItem</action>
+      <output>
+        Work item {current_item} complete.
+        Next: {nextItem}
+      </output>
+      <goto step="2">Continue with next work item</goto>
+    </check>
+
+    <check if="last item or single item run">
+      <action>Call complete-run.js with --complete-run flag:</action>
+      <code>
+        node scripts/complete-run.js {rootPath} {runId} --complete-run \
+          --files-created='[{"path":"...","purpose":"..."}]' \
+          --files-modified='[{"path":"...","changes":"..."}]' \
+          --tests=5 --coverage=85
+      </code>
+      <goto step="8"/>
+    </check>
   </step>
 
   <step n="8" title="Generate Walkthrough">
@@ -200,18 +279,16 @@ Before executing scripts, ensure required dependencies are installed:
 
   <step n="9" title="Report Completion">
     <output>
-      Run {run-id} completed for "{title}".
+      Run {run-id} completed.
 
+      Work items completed: {count}
       Files created: {count}
       Files modified: {count}
       Tests added: {count}
-      Coverage: {percentage}%
 
       Artifacts:
-      - Test Report: .specs-fire/runs/{run-id}/test-report.md
+      - Run Log: .specs-fire/runs/{run-id}/run.md
       - Walkthrough: .specs-fire/runs/{run-id}/walkthrough.md
-
-      Continue to next work item? [Y/n]
     </output>
   </step>
 
@@ -222,10 +299,71 @@ Before executing scripts, ensure required dependencies are installed:
 
 ## Scripts
 
-| Script | Purpose |
-|--------|---------|
-| `scripts/init-run.js` | Initialize run record and folder |
-| `scripts/complete-run.js` | Finalize run and update state |
+| Script | Purpose | Usage |
+|--------|---------|-------|
+| `scripts/init-run.js` | Initialize run record and folder | Creates run.md with all work items |
+| `scripts/complete-run.js` | Finalize run and update state | `--complete-item` or `--complete-run` |
+
+### init-run.js Usage
+
+```bash
+# Single work item
+node scripts/init-run.js /project work-item-id intent-id autopilot
+
+# Batch/wide (multiple items)
+node scripts/init-run.js /project --batch '[
+  {"id": "wi-1", "intent": "int-1", "mode": "autopilot"},
+  {"id": "wi-2", "intent": "int-1", "mode": "confirm"}
+]' --scope=batch
+```
+
+**Output:**
+```json
+{
+  "success": true,
+  "runId": "run-001",
+  "runPath": "/project/.specs-fire/runs/run-001",
+  "scope": "batch",
+  "workItems": [...],
+  "currentItem": "wi-1"
+}
+```
+
+### complete-run.js Usage
+
+```bash
+# Complete current item (batch runs - moves to next item)
+node scripts/complete-run.js /project run-001 --complete-item
+
+# Complete entire run (single runs or final item in batch)
+node scripts/complete-run.js /project run-001 --complete-run \
+  --files-created='[{"path":"src/new.ts","purpose":"New feature"}]' \
+  --files-modified='[{"path":"src/old.ts","changes":"Added import"}]' \
+  --tests=5 --coverage=85
+```
+
+**--complete-item Output:**
+```json
+{
+  "success": true,
+  "runId": "run-001",
+  "completedItem": "wi-1",
+  "nextItem": "wi-2",
+  "remainingItems": 1,
+  "allItemsCompleted": false
+}
+```
+
+**--complete-run Output:**
+```json
+{
+  "success": true,
+  "runId": "run-001",
+  "scope": "batch",
+  "workItemsCompleted": 2,
+  "completedAt": "2026-01-20T..."
+}
+```
 
 ---
 
@@ -244,3 +382,23 @@ decisions:
   - decision: Use JWT for tokens
     rationale: Stateless, works with load balancer
 ```
+
+---
+
+## Run Folder Structure
+
+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)
+└── walkthrough.md  # Created by walkthrough-generate skill
+```
+
+The run.md contains:
+- All work items with their statuses
+- Current item being executed
+- Files created/modified (after completion)
+- Decisions made (after completion)
+- Summary (after completion)

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

@@ -18,6 +18,29 @@ Plan the scope of a run by discovering available work items and suggesting group
 
 ---
 
+## Critical Clarifications
+
+### Dependencies Mean Sequential Execution, NOT Separate Runs
+
+**IMPORTANT**: When work items have dependencies:
+- They execute **sequentially within the SAME run**
+- They do **NOT** require separate runs
+- The dependent item waits for its dependency to complete before starting
+
+**Example**: If item 05 depends on item 04:
+- **CORRECT**: ONE run with both items, 04 executes first, then 05
+- **WRONG**: TWO separate runs
+
+### All Options Can Include Multiple Items Per Run
+
+| Option | Items Per Run | Execution |
+|--------|---------------|-----------|
+| Single | 1 item | One at a time, separate runs |
+| Batch | Multiple items (same mode) | Sequential within run |
+| Wide | All compatible items | Sequential within run |
+
+---
+
 ## Workflow
 
 ```xml
@@ -28,6 +51,7 @@ Plan the scope of a run by discovering available work items and suggesting group
     SUGGEST smart groupings based on mode, dependencies, and user history.
     LEARN from user choices to improve future recommendations.
     NEVER force a scope - always let user choose.
+    DEPENDENCIES = SEQUENTIAL EXECUTION, NOT SEPARATE RUNS.
   </mandate>
 
   <step n="1" title="Discover Available Work">
@@ -71,10 +95,10 @@ Plan the scope of a run by discovering available work items and suggesting group
     <action>Read workspace.run_scope_preference from state.yaml (if exists)</action>
 
     <grouping-rules>
-      <rule>Same mode items CAN be batched together</rule>
-      <rule>Items with dependencies CANNOT be in same batch</rule>
-      <rule>Cross-intent batching allowed if items are independent</rule>
-      <rule>Validate mode items should generally run alone</rule>
+      <rule>Dependencies = SEQUENTIAL execution in SAME run (NOT separate runs)</rule>
+      <rule>Different modes CAN be in same run (executed sequentially)</rule>
+      <rule>Cross-intent items allowed in same run if compatible</rule>
+      <rule>Validate mode items may benefit from running alone (more checkpoints)</rule>
     </grouping-rules>
 
     <generate-options>
@@ -84,22 +108,22 @@ Plan the scope of a run by discovering available work items and suggesting group
       </option>
 
       <option name="batch">
-        Group by mode (autopilot together, confirm together)
-        Respect dependencies
-        Total runs: {count of mode groups}
+        All pending items in ONE run
+        Execute sequentially (dependencies respected by order)
+        Checkpoints pause at confirm/validate items
+        Total runs: 1
       </option>
 
       <option name="wide">
-        All compatible items in one run
-        Only separate if dependencies require it
-        Total runs: {minimum possible}
+        Same as batch - all items in one run
+        Total runs: 1
       </option>
     </generate-options>
   </step>
 
   <step n="4" title="Present Options">
     <action>Determine recommended option based on:</action>
-    <substep>autonomy_bias (autonomous→wide, controlled→single)</substep>
+    <substep>autonomy_bias (autonomous→batch, controlled→single)</substep>
     <substep>run_scope_preference (user's historical choice)</substep>
     <substep>Number of pending items (few items→single is fine)</substep>
 
@@ -115,20 +139,24 @@ Plan the scope of a run by discovering available work items and suggesting group
       {/for}
       {/for}
 
+      {if dependencies exist}
+      **Dependencies** (determines execution order):
+      - {dependent_item} depends on {dependency_item}
+      {/if}
+
       ---
 
       **How would you like to execute?**
 
       **[1] One at a time** — {single_count} separate runs
-          Most controlled, review after each
+          Most controlled, review after each run
 
-      **[2] Batch by mode** — {batch_count} runs {if recommended}(Recommended){/if}
-          {for each batch}
-          Run {n}: {item_names} ({mode})
-          {/for}
+      **[2] Sequential chain** — 1 run with {count} items (Recommended)
+          Execute in order: {item1} → {item2} → ...
+          Checkpoints pause at confirm/validate items
 
-      **[3] All together** — {wide_count} run(s)
-          Fastest, minimal interruption
+      **[3] All together** — Same as [2]
+          1 run, sequential execution
 
       Choose [1/2/3]:
     </output>
@@ -139,13 +167,9 @@ Plan the scope of a run by discovering available work items and suggesting group
       <set>run_scope = single</set>
       <set>work_items_for_run = [first_pending_item]</set>
     </check>
-    <check if="response == 2">
+    <check if="response == 2 or response == 3">
       <set>run_scope = batch</set>
-      <set>work_items_for_run = first_batch_items</set>
-    </check>
-    <check if="response == 3">
-      <set>run_scope = wide</set>
-      <set>work_items_for_run = all_compatible_items</set>
+      <set>work_items_for_run = all_pending_items_in_dependency_order</set>
     </check>
   </step>
 
@@ -170,14 +194,12 @@ Plan the scope of a run by discovering available work items and suggesting group
       Starting run with {count} work item(s):
 
       {for each item in work_items_for_run}
-      - {item.title} ({item.mode})
+      {index}. {item.title} ({item.mode})
       {/for}
 
-      {if run_scope == batch or wide}
       Items will execute sequentially within this run.
       {if any item is confirm or validate}
-      Checkpoints will pause for approval as needed.
-      {/if}
+      Checkpoints will pause for approval at confirm/validate items.
       {/if}
 
       ---
@@ -185,7 +207,7 @@ Plan the scope of a run by discovering available work items and suggesting group
       Begin execution? [Y/n]
     </output>
     <check if="response == y">
-      <invoke-skill args="work_items_for_run">run-execute</invoke-skill>
+      <invoke-skill args="work_items_for_run, run_scope">run-execute</invoke-skill>
     </check>
   </step>
 
@@ -255,14 +277,13 @@ active_run:
 ```
 1. Collect all pending items with their modes
 2. Build dependency graph
-3. For "batch" option:
-   - Group by mode
-   - Within each mode group, check dependencies
-   - Split if dependency exists within group
-4. For "wide" option:
-   - Start with all items in one group
-   - Split only where dependencies require
-5. Return groupings with run counts
+3. Sort items in dependency order (dependencies first)
+4. For "single" option:
+   - Each item is its own run
+5. For "batch" or "wide" option:
+   - ALL items in ONE run
+   - Execution order follows dependency graph
+   - Checkpoints pause at confirm/validate items
 ```
 
 ---
@@ -274,7 +295,7 @@ IF run_scope_history has 3+ same choices:
   pre_selected = most_common_choice
 
 ELSE IF autonomy_bias == autonomous:
-  recommended = wide
+  recommended = batch (all in one run)
 
 ELSE IF autonomy_bias == controlled:
   recommended = single

package/package.json

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