specsmd 0.1.64 → 0.1.65

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

@@ -44,6 +44,12 @@ You are the **Builder Agent** for FIRE (Fast Intent-Run Engineering).
 
   <step n="4" title="Route by State">
     <check if="active run exists">
+      <action>Read runs.active[0] from state.yaml</action>
+      <action>Read scope (single/batch/wide) and work_items array</action>
+      <action>Count items by status: completed, in_progress, pending</action>
+      <output>Active run {id} ({scope}) — {completed_count} done, {remaining_count} remaining</output>
+      <mandate>DO NOT treat completed items as needing re-execution</mandate>
+      <mandate>ONLY work on the current_item from state.yaml</mandate>
       <action>Resume execution — invoke run-execute skill</action>
     </check>
     <check if="pending work items exist">

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

@@ -9,6 +9,24 @@ Execute work items based on their assigned mode (autopilot, confirm, validate).
 Supports both single-item and multi-item (batch/wide) runs.
 </objective>
 
+<progress_display>
+  Show current position in workflow:
+
+  ```text
+  ### Run Progress
+  - [ ] Run initialized (init-run.cjs)
+  - [ ] Context loaded
+  - [ ] Plan generated  ← {current_step}
+  - [ ] Implementation
+  - [ ] Tests passing
+  - [ ] Code review
+  - [ ] Run completed (complete-run.cjs)
+  - [ ] Walkthrough generated
+  ```
+
+  Update markers as you progress: [x] = done, ← current = active step
+</progress_display>
+
 <prerequisites>
   Before executing scripts, ensure required dependencies are installed:
 
@@ -43,28 +61,48 @@ Supports both single-item and multi-item (batch/wide) runs.
     </check>
 
     <check if="runs.active has entries">
-      <action>Load run state from .specs-fire/runs/{runs.active[0].id}/run.md</action>
-      <action>Get current_item and its status from state.yaml</action>
-      <action>Check for existing artifacts and LOAD if present:</action>
-
-      <substep>design.md → if exists, LOAD from .specs-fire/intents/{intent}/work-items/{id}-design.md</substep>
-      <substep>plan.md → if exists, LOAD from .specs-fire/runs/{run-id}/plan.md (skip plan generation)</substep>
-      <substep>test-report.md → if exists, tests already passed (skip to Step 6b)</substep>
-      <substep>review-report.md → if exists, review done (skip to Step 7)</substep>
-
-      <determine_resume_point>
-        | Artifacts Present | Resume At |
-        |-------------------|-----------|
-        | None | Step 3 (Generate Plan) |
-        | plan.md only | Step 5 (Implementation) |
-        | plan.md + test-report.md | Step 6b (Code Review) |
-        | plan.md + test-report.md + review-report.md | Step 7 (Complete Item) |
-      </determine_resume_point>
+      <action>Load active run from state.yaml runs.active[0]</action>
+      <action>Read scope (single/batch/wide) and work_items array</action>
+
+      <substep n="0a" title="Enumerate Work Item Status">
+        <action>For EACH work item in runs.active[0].work_items, classify by status:</action>
+        <action>Build status summary from state.yaml (NOT from artifact files):</action>
+        <format>
+          [DONE] {item-id} — completed
+          [WORKING] {item-id} (phase: {current_phase}) — in_progress
+          [PENDING] {item-id} — pending
+        </format>
+        <action>Count: completed={X}, in_progress={Y}, pending={Z}</action>
+      </substep>
+
+      <substep n="0b" title="Determine Resume Point for Current Item">
+        <action>Get current_item from state.yaml</action>
+        <action>Read current_phase from the current item's entry in work_items</action>
+
+        <determine_resume_point>
+          Use current_phase from state.yaml to determine resume point:
+
+          | current_phase | Resume At |
+          |---------------|-----------|
+          | plan (or unset) | Step 3 (Generate Plan) |
+          | execute | Step 5 (Implementation) |
+          | test | Step 6 (Run Tests) |
+          | review | Step 6b (Code Review) |
+        </determine_resume_point>
+      </substep>
+
+      <llm critical="true">
+        <mandate>NEVER call --complete-item for items with status "completed" — they are already done</mandate>
+        <mandate>NEVER re-execute steps (plan, implement, test) for completed items</mandate>
+        <mandate>ONLY work on the current_item identified in state.yaml</mandate>
+        <mandate>Use current_phase from state.yaml — do NOT infer phase from artifact file existence</mandate>
+      </llm>
 
       <output>
-        Resuming run {run-id} for work item {current_item}.
+        Resuming run {run-id} ({scope}) for work item {current_item}.
         Mode: {mode}
-        Loaded existing artifacts: {artifact_list}
+        Phase: {current_phase}
+        Status: {completed_count} done, {in_progress_count} working, {pending_count} pending
         Resuming at: Step {step_number}
       </output>
     </check>
@@ -105,8 +143,14 @@ Supports both single-item and multi-item (batch/wide) runs.
 
 <flow>
   <step n="1" title="Initialize Run">
-    <critical>MUST call init-run.cjs script. DO NOT use mkdir directly.</critical>
-    <note>The script creates BOTH the folder AND run.md file.</note>
+    <hard_gate>
+      ⛔ HARD GATE - SCRIPT EXECUTION REQUIRED
+      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+      You MUST call init-run.cjs script.
+      DO NOT use mkdir or create files directly.
+      The script creates BOTH the folder AND run.md file.
+      If you skip this, state.yaml will be inconsistent.
+    </hard_gate>
 
     <action>Prepare work items JSON array:</action>
     <code>
@@ -458,6 +502,16 @@ Supports both single-item and multi-item (batch/wide) runs.
   </step>
 
   <step n="7" title="Complete Current Work Item">
+    <hard_gate>
+      ⛔ HARD GATE - SCRIPT EXECUTION REQUIRED
+      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+      You MUST call complete-run.cjs script.
+      DO NOT manually update state.yaml or run.md.
+      Use --complete-item for batch runs with remaining items.
+      Use --complete-run only when ALL items are done.
+      If you skip this, state becomes inconsistent.
+    </hard_gate>
+
     <llm critical="true">
       <mandate>BATCH RUNS: You MUST loop until ALL items are done</mandate>
       <mandate>NEVER call --complete-run until ALL items have artifacts</mandate>

package/flows/fire/agents/builder/skills/run-execute/scripts/complete-run.cjs

@@ -21,6 +21,7 @@
  *   --decisions=JSON       - JSON array of {decision, choice, rationale}
  *   --tests=N              - Number of tests added
  *   --coverage=N           - Coverage percentage
+ *   --force                - Override phase guard (skip review phase check)
  */
 
 const fs = require('fs');
@@ -394,7 +395,7 @@ function updateRunLog(runLogPath, activeRun, params, completedTime, isFullComple
 // Complete Current Item (for batch runs)
 // =============================================================================
 
-function completeCurrentItem(rootPath, runId, params = {}) {
+function completeCurrentItem(rootPath, runId, params = {}, options = {}) {
   const completionParams = {
     filesCreated: params.filesCreated || [],
     filesModified: params.filesModified || [],
@@ -402,6 +403,7 @@ function completeCurrentItem(rootPath, runId, params = {}) {
     testsAdded: params.testsAdded || 0,
     coverage: params.coverage || 0,
   };
+  const force = options.force || false;
 
   validateInputs(rootPath, runId);
   const { statePath, runLogPath } = validateFireProject(rootPath, runId);
@@ -449,6 +451,16 @@ function completeCurrentItem(rootPath, runId, params = {}) {
     );
   }
 
+  // Phase guard: item must be at 'review' phase before completion
+  const currentPhase = workItems[currentItemIndex].current_phase;
+  if (!force && currentPhase !== 'review') {
+    throw fireError(
+      `Cannot complete item "${currentItemId}" — current phase is "${currentPhase || 'unknown'}", not "review".`,
+      'COMPLETE_051',
+      'The item must reach the review phase before completion. Use --force to override.'
+    );
+  }
+
   // Find next pending item
   let nextItem = null;
   for (let i = currentItemIndex + 1; i < workItems.length; i++) {
@@ -510,7 +522,7 @@ function completeCurrentItem(rootPath, runId, params = {}) {
 // Complete Entire Run
 // =============================================================================
 
-function completeRun(rootPath, runId, params = {}) {
+function completeRun(rootPath, runId, params = {}, options = {}) {
   const completionParams = {
     filesCreated: params.filesCreated || [],
     filesModified: params.filesModified || [],
@@ -518,6 +530,7 @@ function completeRun(rootPath, runId, params = {}) {
     testsAdded: params.testsAdded || 0,
     coverage: params.coverage || 0,
   };
+  const force = options.force || false;
 
   validateInputs(rootPath, runId);
   const { statePath, runLogPath } = validateFireProject(rootPath, runId);
@@ -550,6 +563,21 @@ function completeRun(rootPath, runId, params = {}) {
   const workItems = activeRun.work_items || [];
   const scope = activeRun.scope || 'single';
 
+  // Phase guard: all non-completed items must be at 'review' phase
+  if (!force) {
+    const notReady = workItems.filter(
+      item => item.status !== 'completed' && item.current_phase !== 'review'
+    );
+    if (notReady.length > 0) {
+      const list = notReady.map(i => `${i.id} (phase: ${i.current_phase || 'unknown'})`).join(', ');
+      throw fireError(
+        `Cannot complete run — ${notReady.length} item(s) have not reached review phase: ${list}.`,
+        'COMPLETE_060',
+        'All items must reach the review phase before run completion. Use --force to override.'
+      );
+    }
+  }
+
   // Mark all items as completed
   for (const item of workItems) {
     if (item.status !== 'completed') {
@@ -655,6 +683,7 @@ function parseArgs(args) {
     runId: args[1],
     completeItem: false,
     completeRunFlag: false,
+    force: false,
     filesCreated: [],
     filesModified: [],
     decisions: [],
@@ -668,6 +697,8 @@ function parseArgs(args) {
       result.completeItem = true;
     } else if (arg === '--complete-run') {
       result.completeRunFlag = true;
+    } else if (arg === '--force') {
+      result.force = true;
     } else if (arg.startsWith('--files-created=')) {
       try {
         result.filesCreated = JSON.parse(arg.substring('--files-created='.length));
@@ -709,6 +740,7 @@ function printUsage() {
   console.error('Flags:');
   console.error('  --complete-item  - Complete only the current work item (batch/wide runs)');
   console.error('  --complete-run   - Complete the entire run');
+  console.error('  --force          - Override phase guard (skip review phase check)');
   console.error('');
   console.error('Options:');
   console.error('  --files-created=JSON   - JSON array of {path, purpose}');
@@ -737,6 +769,7 @@ if (require.main === module) {
   const params = parseArgs(args);
 
   try {
+    const cliOptions = { force: params.force };
     let result;
     if (params.completeItem) {
       result = completeCurrentItem(params.rootPath, params.runId, {
@@ -745,7 +778,7 @@ if (require.main === module) {
         decisions: params.decisions,
         testsAdded: params.testsAdded,
         coverage: params.coverage,
-      });
+      }, cliOptions);
     } else {
       // Default: complete entire run
       result = completeRun(params.rootPath, params.runId, {
@@ -754,7 +787,7 @@ if (require.main === module) {
         decisions: params.decisions,
         testsAdded: params.testsAdded,
         coverage: params.coverage,
-      });
+      }, cliOptions);
     }
     console.log(JSON.stringify(result, null, 2));
     process.exit(0);

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

@@ -113,6 +113,18 @@ Plan the scope of a run by discovering available work items and suggesting group
         </action>
       </check>
 
+      <check if="state says completed but item is in runs.active[].work_items with current_phase != review">
+        <output>
+          **Suspect completion**: {work-item-id}
+          - state.yaml status: completed
+          - But current_phase: {current_phase} (not "review")
+          - Item is still in active run {run-id}
+          Resetting to in_progress — item was likely marked complete prematurely.
+        </output>
+        <action>Reset work item status to in_progress in state.yaml</action>
+        <action>Update frontmatter to match</action>
+      </check>
+
       <check if="in state.yaml but file missing">
         <output>Warning: {item} in state but file not found on disk</output>
       </check>

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

@@ -49,14 +49,28 @@ Generate implementation walkthrough for human review after run completion.
     <substep>How the pieces fit together architecturally</substep>
     <substep>Data flow or component relationships</substep>
     <substep>Keep high-level, NO CODE</substep>
+    <action>Identify architecture pattern (if multi-component):</action>
+    <substep>Pattern used (Repository, Service Layer, MVC, Clean Architecture, etc.)</substep>
+    <substep>Layer structure diagram (ASCII) if applicable</substep>
+    <action>Document domain model (if entities/models created):</action>
+    <substep>Entities with properties and business rules</substep>
+    <substep>Value objects with constraints</substep>
   </step>
 
   <step n="3" title="Document Key Details">
     <action>Extract implementation highlights:</action>
     <substep>Main flow/algorithm implemented</substep>
-    <substep>Security considerations (if applicable)</substep>
-    <substep>Performance considerations (if applicable)</substep>
     <substep>Integration points with existing code</substep>
+    <action>Document security considerations (if applicable):</action>
+    <substep>Authentication/authorization approach</substep>
+    <substep>Input validation strategy</substep>
+    <substep>Data protection measures</substep>
+    <substep>Format as table: Concern | Approach</substep>
+    <action>Document performance considerations (if applicable):</action>
+    <substep>Optimization strategies used</substep>
+    <substep>Caching, indexing, or query optimization</substep>
+    <substep>Scalability approach</substep>
+    <substep>Format as table: Requirement | Implementation</substep>
     <action>Document deviations from plan:</action>
     <substep>Compare implementation to original work item plan</substep>
     <substep>Note any changes and explain WHY they were made</substep>
@@ -74,8 +88,23 @@ Generate implementation walkthrough for human review after run completion.
     <substep>Manual test scenarios</substep>
   </step>
 
-  <step n="5" title="Generate Walkthrough">
+  <step n="5" title="Assess Ready for Review">
+    <action>Evaluate implementation completeness:</action>
+    <substep>All acceptance criteria met?</substep>
+    <substep>Tests passing?</substep>
+    <substep>No critical issues remaining?</substep>
+    <substep>Documentation updated (if applicable)?</substep>
+    <substep>Developer notes captured?</substep>
+    <action>Generate checklist with [x] for met, [ ] for unmet</action>
+  </step>
+
+  <step n="6" title="Generate Walkthrough">
     <action>Generate walkthrough using template: templates/walkthrough.md.hbs</action>
+    <action>Include all sections (conditional sections only if data exists):</action>
+    <substep>Architecture — only if multi-component with clear pattern</substep>
+    <substep>Domain Model — only if entities/value objects created</substep>
+    <substep>Security Considerations — only if security-relevant changes</substep>
+    <substep>Performance Considerations — only if performance-relevant changes</substep>
     <action>Save to: .specs-fire/runs/{run-id}/walkthrough.md</action>
     <output>
       Walkthrough generated: .specs-fire/runs/{run-id}/walkthrough.md
@@ -86,7 +115,7 @@ Generate implementation walkthrough for human review after run completion.
 <output_template>
   **Walkthrough** (`.specs-fire/runs/{run-id}/walkthrough.md`):
 
-  ```markdown
+  ````markdown
   ---
   run: {run-id}
   work_item: {work-item-id}
@@ -105,77 +134,134 @@ Generate implementation walkthrough for human review after run completion.
 
   {High-level description of how pieces fit together - NO CODE}
 
-  ## Files Changed
+  ## Architecture (if multi-component)
+
+  ### Pattern Used
+  {Pattern and rationale - e.g., Repository pattern for data access abstraction}
+
+  ### Layer Structure
+  ```text
+  ┌─────────────────────────────┐
+  │      Presentation           │
+  ├─────────────────────────────┤
+  │      Application            │
+  ├─────────────────────────────┤
+  │        Domain               │
+  ├─────────────────────────────┤
+  │     Infrastructure          │
+  └─────────────────────────────┘
+  ```
 
-  ### Created
+## Files Changed
+
+### Created
 
   | File | Purpose |
   |------|---------|
   | `{path}` | {purpose} |
 
-  ### Modified
+### Modified
 
   | File | Changes |
   |------|---------|
   | `{path}` | {changes} |
 
-  ## Key Implementation Details
+## Domain Model (if entities created)
+
+### Entities
+
+  | Entity | Properties | Business Rules |
+  |--------|------------|----------------|
+  | {name} | {props} | {rules} |
+
+### Value Objects
+
+  | Value Object | Properties | Constraints |
+  |--------------|------------|-------------|
+  | {name} | {props} | {constraints} |
+
+## Key Implementation Details
 
-  ### 1. {Detail Title}
+### 1. {Detail Title}
 
   {description of implementation approach}
 
-  ## Decisions Made
+## Security Considerations (if applicable)
+
+  | Concern | Approach |
+  |---------|----------|
+  | {concern} | {approach} |
+
+## Performance Considerations (if applicable)
+
+  | Requirement | Implementation |
+  |-------------|----------------|
+  | {requirement} | {implementation} |
+
+## Decisions Made
 
   | Decision | Choice | Rationale |
   |----------|--------|-----------|
   | {decision} | {choice} | {rationale} |
 
-  ## Deviations from Plan
+## Deviations from Plan
 
   {Changes from work item plan and why, or "None"}
 
-  ## Dependencies Added
+## Dependencies Added
 
   | Package | Why Needed |
   |---------|------------|
   | `{package}` | {reason} |
 
-  ## How to Verify
+## How to Verify
 
   1. **{Step Title}**
+
      ```bash
      {command}
      ```
+
      Expected: {expected output}
 
-  2. **{Step Title}**
-     {manual verification steps}
+## Test Coverage
+
+- Tests added: {count}
+- Coverage: {percentage}%
+- Status: {passing/failing}
 
-  ## Test Coverage
+## Ready for Review
 
-  - Tests added: {count}
-  - Coverage: {percentage}%
-  - Status: {passing/failing}
+- [x] All acceptance criteria met
+- [x] Tests passing
+- [x] No critical issues
+- [ ] Documentation updated (if applicable)
+- [x] Developer notes captured
 
-  ## Developer Notes
+## Developer Notes
 
   {Gotchas, tips, or context for future work - keep brief}
 
   ---
   *Generated by specs.md - fabriqa.ai FIRE Flow Run {run-id}*
-  ```
+
+  ````
 
 </output_template>
 
 <success_criteria>
-  <criterion>Walkthrough generated with all sections</criterion>
+  <criterion>Walkthrough generated with all applicable sections</criterion>
   <criterion>Structure overview explains architecture (NO CODE)</criterion>
+  <criterion>Architecture pattern documented (if multi-component)</criterion>
+  <criterion>Domain model documented (if entities created)</criterion>
   <criterion>Files changed documented with purposes</criterion>
+  <criterion>Security considerations documented (if security-relevant)</criterion>
+  <criterion>Performance considerations documented (if performance-relevant)</criterion>
   <criterion>Decisions recorded with rationale</criterion>
   <criterion>Deviations from plan documented (or "None")</criterion>
   <criterion>Dependencies added listed with reasons</criterion>
   <criterion>Verification steps included</criterion>
+  <criterion>Ready for Review checklist completed</criterion>
   <criterion>Developer notes capture gotchas and tips</criterion>
   <criterion>Saved to run folder</criterion>
 </success_criteria>

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

@@ -16,6 +16,22 @@ mode: {{mode}}
 
 {{structure_overview}}
 
+{{#if architecture}}
+## Architecture
+
+### Pattern Used
+
+{{architecture.pattern}}
+
+{{#if architecture.layer_diagram}}
+### Layer Structure
+
+```text
+{{architecture.layer_diagram}}
+```
+{{/if}}
+{{/if}}
+
 ## Files Changed
 
 ### Created
@@ -40,6 +56,30 @@ mode: {{mode}}
 | (none) | |
 {{/unless}}
 
+{{#if domain_model}}
+## Domain Model
+
+{{#if domain_model.entities}}
+### Entities
+
+| Entity | Properties | Business Rules |
+|--------|------------|----------------|
+{{#each domain_model.entities}}
+| {{this.name}} | {{this.properties}} | {{this.rules}} |
+{{/each}}
+{{/if}}
+
+{{#if domain_model.value_objects}}
+### Value Objects
+
+| Value Object | Properties | Constraints |
+|--------------|------------|-------------|
+{{#each domain_model.value_objects}}
+| {{this.name}} | {{this.properties}} | {{this.constraints}} |
+{{/each}}
+{{/if}}
+{{/if}}
+
 ## Key Implementation Details
 
 {{#each implementation_details}}
@@ -49,6 +89,26 @@ mode: {{mode}}
 
 {{/each}}
 
+{{#if security_considerations}}
+## Security Considerations
+
+| Concern | Approach |
+|---------|----------|
+{{#each security_considerations}}
+| {{this.concern}} | {{this.approach}} |
+{{/each}}
+{{/if}}
+
+{{#if performance_considerations}}
+## Performance Considerations
+
+| Requirement | Implementation |
+|-------------|----------------|
+{{#each performance_considerations}}
+| {{this.requirement}} | {{this.implementation}} |
+{{/each}}
+{{/if}}
+
 ## Decisions Made
 
 | Decision | Choice | Rationale |
@@ -96,6 +156,14 @@ None
 - Coverage: {{coverage}}%
 - Status: {{test_status}}
 
+## Ready for Review
+
+- [{{#if ready.acceptance_met}}x{{else}} {{/if}}] All acceptance criteria met
+- [{{#if ready.tests_passing}}x{{else}} {{/if}}] Tests passing
+- [{{#if ready.no_critical_issues}}x{{else}} {{/if}}] No critical issues
+- [{{#if ready.docs_updated}}x{{else}} {{/if}}] Documentation updated (if applicable)
+- [{{#if ready.notes_captured}}x{{else}} {{/if}}] Developer notes captured
+
 ## Developer Notes
 
 {{#if developer_notes}}

package/flows/ideation/README.md

@@ -0,0 +1,35 @@
+# Ideation Flow
+
+**Spark → Flame → Forge** — Creative ideation for AI-native thinkers.
+
+For getting started, see [quick-start.md](./quick-start.md).
+
+## Summary
+
+- **Hierarchy**: Topic → Session (Spark Bank → Flame Report → Concept Brief)
+- **Skills**: Spark (generate), Flame (evaluate), Forge (shape)
+- **Agent**: Single orchestrator with 3 skills
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/specsmd-ideation` | Main entry point (orchestrator) |
+| `/specsmd-spark` | Direct idea generation |
+| `/specsmd-flame` | Direct idea evaluation |
+| `/specsmd-forge` | Direct concept shaping |
+
+## Research Foundation
+
+This flow synthesizes insights from established creativity research. Source materials are in `/resources/brainstorming/`:
+
+| Source | Key Contribution |
+|--------|-----------------|
+| **Applied Imagination** — Alex Osborn (1953) | Deferred judgment, quantity-first, Osborn-Parnes CPS, idea prompter checklists (became SCAMPER) |
+| **Six Thinking Hats** — Edward de Bono (1985) | Parallel thinking, ego protection via hat roles, hat sequencing methodology |
+| **Enhancing Your Creative Spirit** — Dr. John Kapeleris (2009) | Creativity decline data, Wallas creative process, stimulation methods |
+| **Creative & Group Thinking Techniques** — Skillfluence | 25 practical techniques with phase-based organization |
+| **Brainstorming (Wikipedia)** | 9 variations, 6 research-backed challenges, improvement methods |
+| **Anthropic XML Guide** | State machine execution, semantic tags, skill architecture |
+
+See `/resources/brainstorming/analysis.md` for the full cross-resource synthesis.