specsmd 0.0.0-dev.51 → 0.0.0-dev.53

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

@@ -153,14 +153,21 @@ Each run creates a folder with its artifacts:
 
 ```
 .specs-fire/runs/{run-id}/
+├── plan.md          # Approved implementation plan (confirm/validate modes)
 ├── run.md           # Run log (metadata, files changed, decisions)
 └── walkthrough.md   # Implementation walkthrough (for human review)
 ```
 
+**The trio**:
+- **plan.md** — What we intended to do (approved at checkpoint)
+- **run.md** — What happened during execution
+- **walkthrough.md** — Human-readable summary after completion
+
 | Artifact | Location | Template |
 |----------|----------|----------|
-| Run Log | `.specs-fire/runs/{run-id}/run.md` | `templates/runs/run.md.hbs` |
-| Walkthrough | `.specs-fire/runs/{run-id}/walkthrough.md` | `templates/runs/walkthrough.md.hbs` |
+| 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) |
+| Walkthrough | `.specs-fire/runs/{run-id}/walkthrough.md` | `skills/walkthrough-generate/templates/walkthrough.md.hbs` |
 
 ---
 

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

@@ -105,6 +105,10 @@ Before executing scripts, ensure required dependencies are installed:
       <action>Adjust plan</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>
 
@@ -136,6 +140,11 @@ Before executing scripts, ensure required dependencies are installed:
       <action>Adjust plan</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>
 

package/flows/fire/agents/builder/skills/run-execute/templates/plan.md.hbs

@@ -0,0 +1,61 @@
+---
+run: {{run_id}}
+work_item: {{work_item_id}}
+intent: {{intent_id}}
+mode: {{mode}}
+checkpoint: {{checkpoint_type}}
+approved_at: {{approved_at}}
+---
+
+# Implementation Plan: {{title}}
+
+## Approach
+
+{{approach}}
+
+## Files to Create
+
+| File | Purpose |
+|------|---------|
+{{#each files_to_create}}
+| `{{this.path}}` | {{this.purpose}} |
+{{/each}}
+{{#unless files_to_create}}
+| (none) | |
+{{/unless}}
+
+## Files to Modify
+
+| File | Changes |
+|------|---------|
+{{#each files_to_modify}}
+| `{{this.path}}` | {{this.changes}} |
+{{/each}}
+{{#unless files_to_modify}}
+| (none) | |
+{{/unless}}
+
+{{#if tests}}
+## Tests
+
+| Test File | Coverage |
+|-----------|----------|
+{{#each tests}}
+| `{{this.path}}` | {{this.coverage}} |
+{{/each}}
+{{/if}}
+
+{{#if technical_details}}
+## Technical Details
+
+{{technical_details}}
+{{/if}}
+
+{{#if design_doc}}
+## Based on Design Doc
+
+Reference: `{{design_doc}}`
+{{/if}}
+
+---
+*Plan approved at checkpoint. Execution follows.*

package/flows/fire/agents/builder/skills/walkthrough-generate/SKILL.md

@@ -61,7 +61,7 @@ Generate implementation walkthrough for human review after run completion.
   </step>
 
   <step n="5" title="Generate Walkthrough">
-    <action script="scripts/render-walkthrough.ts">Render walkthrough from template</action>
+    <action>Generate walkthrough using template: templates/walkthrough.md.hbs</action>
     <action>Save to: .specs-fire/runs/{run-id}/walkthrough.md</action>
     <output>
       Walkthrough generated: .specs-fire/runs/{run-id}/walkthrough.md

package/flows/fire/agents/builder/skills/walkthrough-generate/templates/walkthrough.md.hbs

@@ -0,0 +1,77 @@
+---
+run: {{run_id}}
+work_item: {{work_item_id}}
+intent: {{intent_id}}
+generated: {{generated}}
+mode: {{mode}}
+---
+
+# Implementation Walkthrough: {{title}}
+
+## Summary
+
+{{summary}}
+
+## Files Changed
+
+### Created
+
+| File | Purpose |
+|------|---------|
+{{#each files_created}}
+| `{{this.path}}` | {{this.purpose}} |
+{{/each}}
+{{#unless files_created}}
+| (none) | |
+{{/unless}}
+
+### Modified
+
+| File | Changes |
+|------|---------|
+{{#each files_modified}}
+| `{{this.path}}` | {{this.changes}} |
+{{/each}}
+{{#unless files_modified}}
+| (none) | |
+{{/unless}}
+
+## Key Implementation Details
+
+{{#each implementation_details}}
+### {{@index}}. {{this.title}}
+
+{{this.description}}
+
+{{/each}}
+
+## Decisions Made
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+{{#each decisions}}
+| {{this.decision}} | {{this.choice}} | {{this.rationale}} |
+{{/each}}
+{{#unless decisions}}
+| (none) | | |
+{{/unless}}
+
+## How to Verify
+
+{{#each verification_steps}}
+{{@index}}. **{{this.title}}**
+   ```bash
+   {{this.command}}
+   ```
+   Expected: {{this.expected}}
+
+{{/each}}
+
+## Test Coverage
+
+- Tests added: {{tests_added}}
+- Coverage: {{coverage}}%
+- Status: {{test_status}}
+
+---
+*Generated by FIRE Run {{run_id}}*

package/flows/fire/agents/planner/skills/design-doc-generate/SKILL.md

@@ -119,7 +119,8 @@ Generate design documents for Validate mode work items (Checkpoint 1).
 
   <step n="9" title="Handle Response">
     <check if="response == y">
-      <action>Save design doc to .specs-fire/intents/{intent-id}/work-items/{id}-design.md</action>
+      <action>Generate design doc using template: templates/design.md.hbs</action>
+      <action>Save to: .specs-fire/intents/{intent-id}/work-items/{id}-design.md</action>
       <action>Mark checkpoint 1 as passed</action>
       <output>
         Design approved. Ready for implementation planning.

package/flows/fire/agents/planner/skills/design-doc-generate/templates/design.md.hbs

@@ -0,0 +1,76 @@
+---
+work_item: {{work_item_id}}
+intent: {{intent_id}}
+created: {{created}}
+mode: validate
+checkpoint_1: {{checkpoint_status}}
+---
+
+# Design: {{title}}
+
+## Summary
+
+{{summary}}
+
+## Key Decisions
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+{{#each decisions}}
+| {{this.decision}} | {{this.choice}} | {{this.rationale}} |
+{{/each}}
+
+{{#if domain_model}}
+## Domain Model
+
+### Entities
+{{#each domain_model.entities}}
+- **{{this.name}}**: {{this.description}}
+{{/each}}
+
+### Value Objects
+{{#each domain_model.value_objects}}
+- **{{this.name}}**: {{this.description}}
+{{/each}}
+{{/if}}
+
+## Technical Approach
+
+### Component Diagram
+
+```
+{{component_diagram}}
+```
+
+{{#if api_endpoints}}
+### API Endpoints
+
+{{#each api_endpoints}}
+- `{{this.method}} {{this.path}}` - {{this.description}}
+{{/each}}
+{{/if}}
+
+{{#if database_changes}}
+### Database Changes
+
+```sql
+{{database_changes}}
+```
+{{/if}}
+
+## Risks & Mitigations
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+{{#each risks}}
+| {{this.risk}} | {{this.impact}} | {{this.mitigation}} |
+{{/each}}
+
+## Implementation Checklist
+
+{{#each checklist}}
+- [ ] {{this}}
+{{/each}}
+
+---
+*Checkpoint 1 approved: {{approved_at}}*

package/flows/fire/agents/planner/skills/intent-capture/SKILL.md

@@ -85,7 +85,7 @@ Capture user intent through guided conversation.
 
   <step n="4" title="Generate Intent Brief">
     <action>Create intent ID from title (kebab-case)</action>
-    <action>Generate intent brief using template</action>
+    <action>Generate intent brief using template: templates/brief.md.hbs</action>
     <action>Create directory: .specs-fire/intents/{intent-id}/</action>
     <action>Save: .specs-fire/intents/{intent-id}/brief.md</action>
   </step>

package/flows/fire/agents/planner/skills/intent-capture/templates/brief.md.hbs

@@ -0,0 +1,40 @@
+---
+id: {{id}}
+title: {{title}}
+status: {{status}}
+created: {{created}}
+---
+
+# Intent: {{title}}
+
+## Goal
+
+{{goal}}
+
+## Users
+
+{{users}}
+
+## Problem
+
+{{problem}}
+
+## Success Criteria
+
+{{#each success_criteria}}
+- {{this}}
+{{/each}}
+
+## Constraints
+
+{{#each constraints}}
+- {{this}}
+{{/each}}
+
+## Notes
+
+{{#if notes}}
+{{notes}}
+{{else}}
+(none)
+{{/if}}

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

@@ -132,7 +132,8 @@ Break an intent into discrete, executable work items.
   <step n="7" title="Save Work Items">
     <check if="approved">
       <action>Create .specs-fire/intents/{intent-id}/work-items/</action>
-      <action>For each work item, save to {work-item-id}.md</action>
+      <action>For each work item, generate using template: templates/work-item.md.hbs</action>
+      <action>Save each to: .specs-fire/intents/{intent-id}/work-items/{work-item-id}.md</action>
       <action>Update state.yaml with work items list</action>
     </check>
   </step>

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

@@ -0,0 +1,40 @@
+---
+id: {{id}}
+title: {{title}}
+intent: {{intent}}
+complexity: {{complexity}}
+mode: {{mode}}
+status: {{status}}
+depends_on: [{{#each depends_on}}{{this}}{{#unless @last}}, {{/unless}}{{/each}}]
+created: {{created}}
+---
+
+# Work Item: {{title}}
+
+## Description
+
+{{description}}
+
+## Acceptance Criteria
+
+{{#each acceptance_criteria}}
+- [ ] {{this}}
+{{/each}}
+
+## Technical Notes
+
+{{#if technical_notes}}
+{{technical_notes}}
+{{else}}
+(none)
+{{/if}}
+
+## Dependencies
+
+{{#if depends_on}}
+{{#each depends_on}}
+- {{this}}
+{{/each}}
+{{else}}
+(none)
+{{/if}}

package/flows/fire/memory-bank.yaml

@@ -79,6 +79,7 @@ schema:
   work-item: ".specs-fire/intents/{intent-id}/work-items/{work-item-id}.md"
   runs: ".specs-fire/runs/"
   run-folder: ".specs-fire/runs/{run-id}/"
+  plan: ".specs-fire/runs/{run-id}/plan.md"
   run-log: ".specs-fire/runs/{run-id}/run.md"
   walkthrough: ".specs-fire/runs/{run-id}/walkthrough.md"
   standards: ".specs-fire/standards/"

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.51",
+  "version": "0.0.0-dev.53",
   "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": {