specsmd 0.0.0-dev.50 → 0.0.0-dev.52

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

@@ -17,9 +17,10 @@ You are the **Builder Agent** for FIRE (Fast Intent-Run Engineering).
 When routed from Orchestrator or user invokes this agent:
 
 1. Read `.specs-fire/state.yaml` for current state
-2. Determine mode:
+2. Scan file system for intents/work-items not in state (reconcile)
+3. Determine mode:
    - **Active run exists** → Resume execution
-   - **Pending work items** → Start next work item
+   - **Pending work items** → Plan run scope, then execute
    - **No work items** → Route back to Planner
 
 ---
@@ -28,6 +29,7 @@ When routed from Orchestrator or user invokes this agent:
 
 | Command | Skill | Description |
 |---------|-------|-------------|
+| `plan` | `skills/run-plan/SKILL.md` | Plan run scope (discover work, suggest groupings) |
 | `run`, `execute` | `skills/run-execute/SKILL.md` | Execute a work item run |
 | `walkthrough` | `skills/walkthrough-generate/SKILL.md` | Generate implementation walkthrough |
 | `status` | `skills/run-status/SKILL.md` | Show current run status |
@@ -85,12 +87,22 @@ For: Security features, payments, core architecture.
 
 ## Run Lifecycle
 
+A run can contain one or multiple work items based on user's scope preference:
+
 ```yaml
 run:
   id: run-001
-  work_item: login-endpoint
-  intent: user-auth
-  mode: confirm
+  scope: batch  # single | batch | wide
+  work_items:
+    - id: login-endpoint
+      intent: user-auth
+      mode: autopilot
+      status: completed
+    - id: session-management
+      intent: user-auth
+      mode: autopilot
+      status: in_progress
+  current_item: session-management
   status: in_progress  # pending | in_progress | completed | failed
   started: 2026-01-19T10:00:00Z
   completed: null
@@ -99,6 +111,11 @@ run:
   decisions: []
 ```
 
+**Scope types:**
+- `single` — One work item per run (most controlled)
+- `batch` — Multiple items of same mode grouped together
+- `wide` — All compatible items in one run (fastest)
+
 ---
 
 ## File Tracking

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

@@ -0,0 +1,287 @@
+# Skill: Run Plan
+
+Plan the scope of a run by discovering available work items and suggesting groupings.
+
+---
+
+## Trigger
+
+- After work-item decomposition completes
+- User wants to start execution
+- Pending work items exist
+
+---
+
+## Degrees of Freedom
+
+**MEDIUM** — Present smart grouping suggestions but let user choose scope.
+
+---
+
+## Workflow
+
+```xml
+<skill name="run-plan">
+
+  <mandate>
+    DISCOVER all available work - both in state.yaml AND file system.
+    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.
+  </mandate>
+
+  <step n="1" title="Discover Available Work">
+    <action>Read state.yaml for known intents and work items</action>
+    <action>Scan .specs-fire/intents/ for intent briefs not in state</action>
+    <action>Scan .specs-fire/intents/*/work-items/ for work items not in state</action>
+
+    <reconcile>
+      <check if="file exists but not in state">
+        <action>Parse file frontmatter for metadata</action>
+        <action>Add to state.yaml as pending</action>
+        <output>Discovered: {item} from {intent} (not in state)</output>
+      </check>
+      <check if="in state but file missing">
+        <output>Warning: {item} in state but file not found</output>
+      </check>
+    </reconcile>
+  </step>
+
+  <step n="2" title="Collect Pending Work Items">
+    <action>Filter work items with status == pending</action>
+    <action>Group by intent</action>
+    <action>Note mode (after autonomy_bias applied) for each</action>
+    <action>Identify dependencies within and across intents</action>
+
+    <check if="no pending work items">
+      <output>
+        No pending work items found.
+
+        Create a new intent? [Y/n]
+      </output>
+      <check if="response == y">
+        <route-to>planner-agent (intent-capture)</route-to>
+      </check>
+      <stop/>
+    </check>
+  </step>
+
+  <step n="3" title="Analyze Groupings">
+    <action>Read workspace.autonomy_bias from state.yaml</action>
+    <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>
+    </grouping-rules>
+
+    <generate-options>
+      <option name="single">
+        Each work item in its own run
+        Total runs: {count of pending items}
+      </option>
+
+      <option name="batch">
+        Group by mode (autopilot together, confirm together)
+        Respect dependencies
+        Total runs: {count of mode groups}
+      </option>
+
+      <option name="wide">
+        All compatible items in one run
+        Only separate if dependencies require it
+        Total runs: {minimum possible}
+      </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>run_scope_preference (user's historical choice)</substep>
+    <substep>Number of pending items (few items→single is fine)</substep>
+
+    <output>
+      ## Run Planning
+
+      **Found**: {count} pending work items across {intent_count} intent(s)
+
+      {for each intent with pending items}
+      **{intent.title}**:
+      {for each pending item}
+      - {item.title} ({item.mode})
+      {/for}
+      {/for}
+
+      ---
+
+      **How would you like to execute?**
+
+      **[1] One at a time** — {single_count} separate runs
+          Most controlled, review after each
+
+      **[2] Batch by mode** — {batch_count} runs {if recommended}(Recommended){/if}
+          {for each batch}
+          Run {n}: {item_names} ({mode})
+          {/for}
+
+      **[3] All together** — {wide_count} run(s)
+          Fastest, minimal interruption
+
+      Choose [1/2/3]:
+    </output>
+  </step>
+
+  <step n="5" title="Process Choice">
+    <check if="response == 1">
+      <set>run_scope = single</set>
+      <set>work_items_for_run = [first_pending_item]</set>
+    </check>
+    <check if="response == 2">
+      <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>
+    </check>
+  </step>
+
+  <step n="6" title="Learn Preference">
+    <action>Update workspace.run_scope_preference in state.yaml</action>
+    <action>Add to workspace.run_scope_history (keep last 10)</action>
+
+    <history-entry>
+      choice: {run_scope}
+      items_count: {count}
+      timestamp: {now}
+    </history-entry>
+
+    <note>
+      After 3+ consistent choices, start pre-selecting that option
+      and ask "Proceed with {preference}? [Y/n/change]" instead
+    </note>
+  </step>
+
+  <step n="7" title="Confirm Run">
+    <output>
+      Starting run with {count} work item(s):
+
+      {for each item in work_items_for_run}
+      - {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}
+      {/if}
+
+      ---
+
+      Begin execution? [Y/n]
+    </output>
+    <check if="response == y">
+      <invoke-skill args="work_items_for_run">run-execute</invoke-skill>
+    </check>
+  </step>
+
+</skill>
+```
+
+---
+
+## State Schema Updates
+
+**workspace section additions**:
+```yaml
+workspace:
+  # ... existing fields ...
+  run_scope_preference: batch  # single | batch | wide (learned)
+  run_scope_history:
+    - choice: batch
+      items_count: 4
+      timestamp: 2026-01-19T10:00:00Z
+```
+
+**active_run with multi-item support**:
+```yaml
+active_run:
+  id: run-001
+  scope: batch  # single | batch | wide
+  work_items:
+    - id: 01-stats-data-model
+      intent: session-stats
+      mode: autopilot
+      status: completed
+    - id: 02-stats-api-endpoint
+      intent: session-stats
+      mode: autopilot
+      status: in_progress
+  current_item: 02-stats-api-endpoint
+  started: 2026-01-19T10:00:00Z
+```
+
+---
+
+## File Discovery Logic
+
+```
+.specs-fire/
+├── intents/
+│   ├── user-auth/
+│   │   ├── brief.md           ← Parse frontmatter for intent metadata
+│   │   └── work-items/
+│   │       ├── login-endpoint.md   ← Parse for work item metadata
+│   │       └── session-mgmt.md
+│   └── analytics/
+│       ├── brief.md
+│       └── work-items/
+│           └── dashboard.md
+```
+
+**Frontmatter parsing**:
+- Extract `id`, `title`, `status` from YAML frontmatter
+- If status missing, default to `pending`
+- If in file but not state.yaml, add to state
+
+---
+
+## Grouping Algorithm
+
+```
+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
+```
+
+---
+
+## Recommendation Logic
+
+```
+IF run_scope_history has 3+ same choices:
+  pre_selected = most_common_choice
+
+ELSE IF autonomy_bias == autonomous:
+  recommended = wide
+
+ELSE IF autonomy_bias == controlled:
+  recommended = single
+
+ELSE: # balanced
+  IF pending_count <= 2:
+    recommended = single
+  ELSE:
+    recommended = batch
+```

package/flows/fire/agents/orchestrator/skills/route/SKILL.md

@@ -16,8 +16,11 @@ Analyze project state and route user to the appropriate agent.
 ```xml
 <skill name="route">
 
-  <step n="1" title="Read State">
+  <step n="1" title="Discover and Read State">
     <action>Read .specs-fire/state.yaml</action>
+    <action>Scan .specs-fire/intents/ for briefs not in state</action>
+    <action>Scan .specs-fire/intents/*/work-items/ for items not in state</action>
+    <action>Reconcile: add discovered items to state as pending</action>
     <action>Parse current project state</action>
   </step>
 
@@ -25,30 +28,25 @@ Analyze project state and route user to the appropriate agent.
     <check if="active_run exists and status == in_progress">
       <output>
         Resuming active run: {active_run.id}
-        Work item: {active_run.work_item}
-        Mode: {active_run.mode}
+        Scope: {active_run.scope}
+        Current item: {active_run.current_item}
+        Progress: {completed_count}/{total_count} items
       </output>
-      <route-to>builder-agent</route-to>
+      <route-to>builder-agent (run-execute)</route-to>
       <stop/>
     </check>
   </step>
 
   <step n="3" title="Check Pending Work Items">
-    <action>Find work items with status == pending</action>
+    <action>Find work items with status == pending across all intents</action>
     <check if="pending work items exist">
       <output>
-        Ready to execute: {next_work_item.title}
-        Complexity: {next_work_item.complexity}
-        Mode: {next_work_item.mode}
+        **{pending_count} pending work items** found across {intent_count} intent(s).
 
-        Start execution? [Y/n/skip]
+        Plan run scope and start execution? [Y/n]
       </output>
       <check if="response == y">
-        <route-to>builder-agent</route-to>
-      </check>
-      <check if="response == skip">
-        <action>Mark work item as skipped</action>
-        <action>Re-evaluate next work item</action>
+        <route-to>builder-agent (run-plan)</route-to>
       </check>
       <stop/>
     </check>
@@ -94,15 +92,15 @@ Analyze project state and route user to the appropriate agent.
 ## Routing Decision Tree
 
 ```
-state.yaml
+state.yaml + file system scan
     │
-    ├── active_run? ──────────────> Builder (resume)
+    ├── active_run? ──────────────> Builder (run-execute, resume)
     │
-    ├── pending work items? ──────> Builder (execute)
+    ├── pending work items? ──────> Builder (run-plan, then execute)
     │
-    ├── intent without work items? > Planner (decompose)
+    ├── intent without work items? > Planner (work-item-decompose)
     │
-    └── no active intents ────────> Planner (capture)
+    └── no active intents ────────> Planner (intent-capture)
 ```
 
 ---
@@ -119,8 +117,7 @@ context:
 **To Builder:**
 ```yaml
 context:
-  action: execute | resume
-  work_item_id: {work item to execute}
+  action: run-plan | run-execute | resume
+  pending_items: [{list of pending work items}]  # for run-plan
   run_id: {if resuming}
-  mode: autopilot | confirm | validate
 ```

package/flows/fire/agents/planner/skills/work-item-decompose/SKILL.md

@@ -139,14 +139,14 @@ Break an intent into discrete, executable work items.
 
   <step n="8" title="Transition">
     <output>
-      {count} work items created for "{intent-title}".
+      **{count} work items created** for "{intent-title}".
 
-      First work item: {first-item.title} ({first-item.mode})
+      ---
 
-      Start execution? [Y/n]
+      Ready to plan execution scope? [Y/n]
     </output>
     <check if="response == y">
-      <route-to>builder-agent</route-to>
+      <route-to>builder-agent (run-plan)</route-to>
     </check>
   </step>
 

package/flows/fire/memory-bank.yaml

@@ -27,6 +27,8 @@ state:
       - type: "greenfield | brownfield"
       - structure: "monolith | monorepo | multi-part"
       - autonomy_bias: "autonomous | balanced | controlled"
+      - run_scope_preference: "single | batch | wide (learned from history)"
+      - run_scope_history: "List of recent scope choices for learning"
       - scanned_at: "ISO 8601 timestamp (brownfield)"
       - parts: "List of project parts (monorepo)"
     intents:
@@ -36,7 +38,9 @@ state:
       - work_items: "List of work items"
     active_run:
       - id: "Current run ID"
-      - work_item: "Work item being executed"
+      - scope: "single | batch | wide"
+      - work_items: "List of work items in this run"
+      - current_item: "Work item currently being executed"
       - started: "ISO 8601 timestamp"
 
 # Data Conventions
@@ -129,3 +133,22 @@ autonomy_bias:
       low: confirm        # shifted up
       medium: validate    # shifted up
       high: validate
+
+# Run Scope - How many work items to execute in a single run
+# Learned from user choices, stored in workspace.run_scope_preference
+run_scope:
+  single:
+    description: "One work item per run, most controlled"
+    grouping: "Each item in its own run"
+  batch:
+    description: "Group items by mode, respect dependencies"
+    grouping: "Autopilot together, confirm together, etc."
+  wide:
+    description: "Maximum items per run, minimal interruption"
+    grouping: "All compatible items together"
+
+# Run scope history entry format
+run_scope_history_entry:
+  choice: "single | batch | wide"
+  items_count: "Number of items in the run"
+  timestamp: "ISO 8601 timestamp"

package/lib/constants.js

@@ -14,7 +14,7 @@ const THEME_COLORS = {
 const FLOWS = {
     fire: {
         name: 'FIRE',
-        description: 'Rapid execution - Solo devs or small teams, brownfield, 0-2 adaptive checkpoints',
+        description: 'Rapid execution - Solo devs or small teams, brownfield/monorepo, 0-2 adaptive checkpoints',
         path: 'fire'
     },
     aidlc: {
@@ -29,7 +29,13 @@ const FLOWS = {
     }
 };
 
+const LINKS = {
+    website: 'https://specs.md',
+    flows: 'https://specs.md/flows'
+};
+
 module.exports = {
     THEME_COLORS,
-    FLOWS
+    FLOWS,
+    LINKS
 };

package/lib/installer.js

@@ -4,7 +4,7 @@ const prompts = require('prompts');
 const yaml = require('js-yaml');
 const CLIUtils = require('./cli-utils');
 const InstallerFactory = require('./InstallerFactory');
-const { FLOWS } = require('./constants');
+const { FLOWS, LINKS } = require('./constants');
 const analytics = require('./analytics');
 
 // Use theme from CLIUtils for consistent styling
@@ -125,6 +125,7 @@ async function install() {
   // Step 3: Select Flow
   console.log('');
   CLIUtils.displayStep(3, 4, 'Select SDLC flow');
+  console.log(theme.dim(`  Learn more about flows: ${LINKS.flows}\n`));
   const flowChoices = Object.entries(FLOWS).map(([key, flow]) => ({
     title: `${flow.name} - ${flow.description}${flow.message || ''}`,
     value: key,

package/package.json

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