@thierrynakoa/fire-flow 12.2.1 → 13.0.1

package/agents/fire-verifier.md

@@ -30,26 +30,8 @@ allowed_references:
   - "@.planning/CONSCIENCE.md"
   - "@.planning/phases/"
   - "@validation-config.yml"
-  - "@.planning/breadcrumbs/"
 ```
 
-### Live Breadcrumb Protocol (v11.2)
-
-**After verification FAILURE:** Write the failed approach to `.planning/breadcrumbs/FAILURES.md`:
-```markdown
-### {date} — Phase {N}, Plan {M}: {what failed}
-**Approach that failed:** {brief description}
-**Why it failed:** {root cause from verification}
-**Evidence:** {specific test/check that failed}
-**Don't retry unless:** {what would need to change}
-```
-
-**Write protocol (on-demand creation):**
-- **First write:** If FAILURES.md doesn't exist (`test -f`), create it with a `# Failures` header, then add the entry.
-- **Subsequent writes:** Append to the existing file.
-
-This ensures the next planning cycle (and all future sessions) will NOT repeat the same failed approach.
-
 ### Isolation Rule
 
 **The fire-verifier MUST be spawned as a new, independent Claude instance** (via the Agent tool) — never run inline in the same context as the executor that wrote the code.
@@ -99,7 +81,7 @@ AUTONOMOUS MODE (/fire-autonomous):
 - PASS only with evidence. FAIL with specific deviation details.
 - Every PASS has proof. Every FAIL has actionable details. No skipped checks.
 - Screenshots/logs required for UI verification.
-- Log unsolvable issues to `breadcrumbs/FAILURES.md` with `[DEAD-END]` tag for next instance.
+- Log unsolvable issues clearly for the next instance to pick up.
 
 </honesty_protocol>
 
@@ -227,6 +209,31 @@ IF dod_gate.scope_respected == false:
   → This is an implied negative scenario — document it
 ```
 
+### Step 1.9: Task Completeness Validation (v12.9)
+
+> but absent from RECORD.md indicate silent execution gaps. Verifier catches what the orchestrator
+> may have missed (e.g., tasks in must-haves that were never executed).
+
+```
+FOR each task defined in BLUEPRINT.md:
+  IF task NOT found in RECORD.md tasks.completed
+     AND task NOT found in RECORD.md tasks.skipped:
+
+    → CRITICAL GAP: "Task '{task_name}' was defined in BLUEPRINT but never executed"
+    → Add to gaps_identified as CRITICAL (not minor)
+    → This PREVENTS auto-APPROVED verdict — must be addressed
+
+  IF task found in RECORD.md tasks.skipped:
+    → NOTE: "Task '{task_name}' was skipped — verify skip reason is valid"
+    → Check if skipped task affects any must-have
+
+completeness = (completed + skipped) / total_blueprint_tasks * 100
+
+IF completeness < 90%:
+  → FLAG in verification report: "Task completeness: {completeness}% — {N} tasks unaccounted"
+  → Verdict cannot be APPROVED (at best CONDITIONAL)
+```
+
 ### Step 2: must-haves Verification
 
 #### 2.1 Truths Verification
@@ -322,6 +329,59 @@ grep -n "[integration-point]" [component-a-file]
 **Status:** PASS | FAIL
 ```
 
+### Step 2.5: Specification Contract Verification (v13.0)
+
+> fire-planner Step 3.9 generates `specification:` contracts in BLUEPRINT frontmatter.
+> This step verifies implementation conforms to those contracts.
+> See: SPEC-DRIVEN-1 in references/research-improvements.md
+
+**IF BLUEPRINT has `specification:` frontmatter with contracts:**
+
+```
+FOR each contract in BLUEPRINT.specification.contracts:
+
+  contract_name = contract.name
+  contract_type = contract.type  # interface | endpoint | must-should-rules
+  definition    = contract.definition
+  verifiable_by = contract.verifiable_by
+
+  # 1. Run the verification command/check
+  IF verifiable_by is a bash command:
+    result = run(verifiable_by)
+    status = result.exit_code == 0 ? "PASS" : "FAIL"
+
+  IF verifiable_by is a grep/search check:
+    result = grep for definition patterns in implementation files
+    status = patterns_found ? "PASS" : "FAIL"
+
+  IF verifiable_by is "manual":
+    → Read implementation, compare against definition
+    → status = matches ? "PASS" : "FAIL"
+
+  # 2. Record result
+  spec_results.push({
+    contract: contract_name,
+    type: contract_type,
+    status: status,
+    evidence: result.output || "Manual check: {description}"
+  })
+
+# 3. Summary
+spec_pass_count = spec_results.filter(r => r.status == "PASS").length
+spec_total = spec_results.length
+
+IF spec_pass_count < spec_total:
+  → FLAG: "Specification contract violation: {failed contracts}"
+  → This is a verification FAILURE — implementation diverged from spec
+  → Do NOT update the spec to match implementation (specs are immutable)
+
+IF spec_pass_count == spec_total:
+  → LOG: "All {spec_total} specification contracts verified"
+```
+
+**IF BLUEPRINT has NO `specification:` field:** Skip this step.
+Log: "No specification contracts in BLUEPRINT — skipping spec verification"
+
 ### Step 3: WARRIOR Validation (Scope-Adaptive, v11.3)
 
 > **Only run sections listed in `active_sections` from Step 1.5.** Skipped sections are logged as "SKIPPED (out of scope)" — not "N/A" or "PASS". The total score denominator adjusts to match active sections (e.g., 4 active sections = X/40, not X/70).
@@ -1060,3 +1120,38 @@ Plan 03-02 (Product Pagination API) passes all must-haves and achieves 86% on WA
 
 **Recommendation:** Proceed to Phase 04. Address documentation gap in next PR.
 ```
+
+---
+
+## Structured Return Envelope (v12.5)
+At the END of your verification output, include this parseable block:
+
+```
+<!-- VERIFIER_VERDICT_START -->
+{
+  "agent": "fire-verifier",
+  "verdict": "APPROVED | CONDITIONAL | REJECTED",
+  "warrior_score": 60,
+  "warrior_max": 70,
+  "warrior_percent": 86,
+  "categories": {
+    "must_haves": "PASS | FAIL",
+    "code_quality": 9,
+    "testing": 9,
+    "security": 10,
+    "performance": 10,
+    "documentation": 8,
+    "infrastructure": 6,
+    "e2e_testing": 8
+  },
+  "gaps_count": 3,
+  "blocking_gaps": 0,
+  "blocking_summary": null
+}
+<!-- VERIFIER_VERDICT_END -->
+```
+
+The orchestrator extracts this for merge gate routing:
+- `APPROVED` → proceed to next phase
+- `CONDITIONAL` → proceed with logged gaps
+- `REJECTED` → halt or auto-fix cycle

package/bin/cli.js

@@ -2,36 +2,32 @@
 
 const fs = require('fs');
 const path = require('path');
-const { execSync } = require('child_process');
 
 // ─────────────────────────────────────────────
 //  fire-flow installer for Claude Code
 // ─────────────────────────────────────────────
 
-const PLUGIN_NAME = 'fire-flow';
 const VERSION = require('../package.json').version;
 
-// Colors for terminal output
 const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
 const green = (s) => `\x1b[32m${s}\x1b[0m`;
-const red = (s) => `\x1b[31m${s}\x1b[0m`;
 const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
 const bold = (s) => `\x1b[1m${s}\x1b[0m`;
 const dim = (s) => `\x1b[2m${s}\x1b[0m`;
 
 function banner() {
   console.log('');
-  console.log(cyan('  ╔══════════════════════════════════════════╗'));
-  console.log(cyan('  ║') + bold('     🔥 fire-flow installer              ') + cyan('║'));
-  console.log(cyan('  ║') + dim(`     v${VERSION} — Workflow Orchestration   `) + cyan('║'));
-  console.log(cyan('  ╚══════════════════════════════════════════╝'));
+  console.log(cyan('  ══════════════════════════════════════════'));
+  console.log(cyan('  ') + bold('     fire-flow installer              '));
+  console.log(cyan('  ') + dim(`     v${VERSION} — Workflow Orchestration   `));
+  console.log(cyan('  ══════════════════════════════════════════'));
   console.log('');
 }
 
 function getPluginsDir() {
   const home = process.env.HOME || process.env.USERPROFILE;
   if (!home) {
-    console.error(red('Could not determine home directory.'));
+    console.error('Could not determine home directory.');
     process.exit(1);
   }
   return path.join(home, '.claude', 'plugins');
@@ -39,13 +35,11 @@ function getPluginsDir() {
 
 function copyRecursive(src, dest) {
   if (!fs.existsSync(src)) return;
-
   const stat = fs.statSync(src);
   if (stat.isDirectory()) {
     fs.mkdirSync(dest, { recursive: true });
     for (const item of fs.readdirSync(src)) {
-      // Skip files that shouldn't be installed
-      if (item === '.git' || item === 'node_modules' || item === 'bin' || item === 'package.json' || item === 'package-lock.json' || item === '.npmignore') continue;
+      if (['.git', 'node_modules', 'bin', 'package.json', 'package-lock.json', '.npmignore', '.private-manifest', 'scripts'].includes(item)) continue;
       copyRecursive(path.join(src, item), path.join(dest, item));
     }
   } else {
@@ -57,152 +51,75 @@ function countFiles(dir, ext) {
   let count = 0;
   if (!fs.existsSync(dir)) return 0;
   for (const item of fs.readdirSync(dir, { recursive: true })) {
-    if (item.endsWith(ext)) count++;
+    if (String(item).endsWith(ext)) count++;
   }
   return count;
 }
 
 function install() {
   banner();
-
   const args = process.argv.slice(2);
 
-  // Handle --help
   if (args.includes('--help') || args.includes('-h')) {
-    console.log(`  ${bold('Usage:')} npx fire-flow [options]`);
+    console.log(`  ${bold('Usage:')} npx @thierrynakoa/fire-flow [options]`);
     console.log('');
     console.log(`  ${bold('Options:')}`);
-    console.log(`    --help, -h       Show this help message`);
+    console.log(`    --help, -h       Show this help`);
     console.log(`    --version, -v    Show version`);
     console.log(`    --uninstall      Remove fire-flow plugin`);
     console.log(`    --update         Update existing installation`);
-    console.log(`    --path <dir>     Install to custom directory`);
-    console.log('');
-    console.log(`  ${bold('Default install path:')}`);
-    console.log(`    ~/.claude/plugins/${PLUGIN_NAME}/`);
     console.log('');
     console.log(`  ${dim('GitHub: https://github.com/ThierryN/fire-flow')}`);
     process.exit(0);
   }
 
-  // Handle --version
   if (args.includes('--version') || args.includes('-v')) {
     console.log(`  fire-flow v${VERSION}`);
     process.exit(0);
   }
 
-  // Determine install path
-  let installDir;
-  const pathIdx = args.indexOf('--path');
-  if (pathIdx !== -1 && args[pathIdx + 1]) {
-    installDir = path.resolve(args[pathIdx + 1]);
-  } else {
-    installDir = path.join(getPluginsDir(), PLUGIN_NAME);
-  }
+  const installDir = path.join(getPluginsDir(), 'fire-flow');
 
-  // Handle --uninstall
   if (args.includes('--uninstall')) {
     if (fs.existsSync(installDir)) {
-      console.log(`  Removing ${yellow(installDir)}...`);
       fs.rmSync(installDir, { recursive: true, force: true });
       console.log(green('  fire-flow has been uninstalled.'));
     } else {
-      console.log(yellow('  fire-flow is not installed at ' + installDir));
+      console.log(yellow('  fire-flow is not installed.'));
     }
     process.exit(0);
   }
 
-  // Check for existing installation
   const isUpdate = args.includes('--update');
   if (fs.existsSync(installDir) && !isUpdate) {
     console.log(yellow(`  fire-flow is already installed at:`));
     console.log(`  ${installDir}`);
     console.log('');
-    console.log(`  Run ${cyan('npx fire-flow --update')} to update.`);
-    console.log(`  Run ${cyan('npx fire-flow --uninstall')} to remove.`);
+    console.log(`  Run ${cyan('npx @thierrynakoa/fire-flow --update')} to update.`);
     process.exit(0);
   }
 
-  // Source directory (the npm package root, one level up from bin/)
   const srcDir = path.join(__dirname, '..');
-
   console.log(`  Installing to: ${cyan(installDir)}`);
   console.log('');
 
-  // Create plugins directory if needed
-  const pluginsDir = path.dirname(installDir);
-  fs.mkdirSync(pluginsDir, { recursive: true });
-
-  // Copy plugin files
-  const filesToCopy = [
-    'agents',
-    'commands',
-    'hooks',
-    'skills-library',
-    'templates',
-    'references',
-    'workflows',
-    '.claude-plugin',
-    'plugin.json',
-    'validation-config.yml',
-    'version.json',
-    'README.md',
-    'QUICK-START.md',
-    'COMMAND-REFERENCE.md',
-    'DOMINION-FLOW-OVERVIEW.md',
-    'ARCHITECTURE-DIAGRAM.md',
-    'TROUBLESHOOTING.md',
-  ];
-
-  let copiedDirs = 0;
-  let copiedFiles = 0;
-
-  for (const item of filesToCopy) {
-    const src = path.join(srcDir, item);
-    const dest = path.join(installDir, item);
-
-    if (!fs.existsSync(src)) {
-      continue;
-    }
-
-    const stat = fs.statSync(src);
-    if (stat.isDirectory()) {
-      copyRecursive(src, dest);
-      copiedDirs++;
-      console.log(`  ${green('+')} ${item}/`);
-    } else {
-      fs.mkdirSync(path.dirname(dest), { recursive: true });
-      fs.copyFileSync(src, dest);
-      copiedFiles++;
-      console.log(`  ${green('+')} ${item}`);
-    }
-  }
+  fs.mkdirSync(path.dirname(installDir), { recursive: true });
+  copyRecursive(srcDir, installDir);
 
-  // Count what was installed
   const cmdCount = countFiles(path.join(installDir, 'commands'), '.md');
   const agentCount = countFiles(path.join(installDir, 'agents'), '.md');
   const skillCount = countFiles(path.join(installDir, 'skills-library'), '.md');
 
-  console.log('');
   console.log(green('  Installation complete!'));
   console.log('');
-  console.log(`  ${bold('Installed:')}`);
-  console.log(`    ${cyan(cmdCount)} commands`);
-  console.log(`    ${cyan(agentCount)} agents`);
-  console.log(`    ${cyan(skillCount)} skills`);
-  console.log('');
-  console.log(`  ${bold('Location:')}`);
-  console.log(`    ${installDir}`);
+  console.log(`  ${bold('Installed:')} ${cyan(cmdCount)} commands, ${cyan(agentCount)} agents, ${cyan(skillCount)} skills`);
+  console.log(`  ${bold('Location:')} ${installDir}`);
   console.log('');
   console.log(`  ${bold('Quick start:')}`);
   console.log(`    1. Open Claude Code in any project`);
-  console.log(`    2. Type ${cyan('/fire-0-orient')} to orient on your project`);
-  console.log(`    3. Type ${cyan('/fire-1-new')} to start a new project workflow`);
-  console.log(`    4. Type ${cyan('/fire-debug')} when you hit a bug`);
-  console.log('');
-  console.log(`  ${bold('Docs:')} ${dim('https://github.com/ThierryN/fire-flow')}`);
-  console.log(`  ${bold('Help:')} ${dim('/fire-dashboard for full command overview')}`);
+  console.log(`    2. Type ${cyan('/fire-0-orient')} to get started`);
   console.log('');
+  console.log(`  ${dim('Docs: https://github.com/ThierryN/fire-flow')}`);
 }
 
 install();

package/commands/fire-0-orient.md

@@ -185,7 +185,7 @@ Based on discovery, determine project state:
 │  └── Last Activity: {date from CONSCIENCE.md or git}                             │
 │                                                                             │
 │  Sabbath Rest (Session State):                                              │
-│  ├── fire-flow.local.md: {status}                                          │
+│  ├── dominion-flow.local.md: {status}                                          │
 │  ├── fire-debugger.local.md: {status}                                      │
 │  └── [other .local.md files]                                                │
 │                                                                             │
@@ -346,7 +346,7 @@ Based on assessment, recommend next action:
 
 > *Like humans need sleep to reset, AI agents need state files to resume after context resets.*
 
-**Create/Update:** `.claude/fire-flow.local.md`
+**Create/Update:** `.claude/dominion-flow.local.md`
 
 ```markdown
 ---

package/commands/fire-1a-new.md

@@ -102,6 +102,54 @@ Use the interview protocol from `@skills-library/_general/methodology/BACKWARD_P
 4. **The Deal-Breakers** — Yes/no: login, payments, uploads, emails, mobile, real-time
 5. **The MVP Gate** — "If you could only ship THREE features, which three?"
 
+**Template Selection (v12.3 — W2-A):**
+
+After determining Forward/Backward mode and gathering core requirements, ask:
+
+```
+PROJECT TEMPLATE
+────────────────────────────────────────────────────────────────
+Which template best matches your vision?
+
+  1. SaaS Application
+     Includes: auth, payments, multi-user accounts, subscription tiers
+     Pre-populates: user table, billing model, role-based access
+
+  2. Community / LMS Platform
+     Includes: courses, lessons, progress tracking, user groups
+     Pre-populates: content models, enrollment, progress state
+
+  3. Marketplace
+     Includes: products, sellers, orders, reviews, search
+     Pre-populates: product catalog, transaction model, seller onboarding
+
+  4. Blog / Content Site
+     Includes: posts, categories, SEO, publishing workflow
+     Pre-populates: content model, slug routing, feed generation
+
+  5. Internal Tool / Admin Dashboard
+     Includes: data views, filters, bulk actions, role-based access
+     Pre-populates: CRUD scaffolding, filter patterns, audit log
+
+  6. REST API / Microservice
+     Includes: endpoints, auth middleware, rate limiting, versioning
+     Pre-populates: route structure, error format, auth pattern
+
+  7. Custom (describe it — I'll derive the template)
+
+Select template (1-7): >
+```
+
+**If template selected (1-6):** Pre-fill known requirements in PROJECT.md and
+pre-populate phase suggestions in REQUIREMENTS.md based on the template pattern.
+Note in REQUIREMENTS.md: `Template: {name} (user-selected)`.
+
+**If Custom (7):** Proceed with standard requirements gathering — no pre-fill.
+
+> and v0.dev gallery pattern + create-t3-app (28k★). Template selection eliminates
+> the blank-page problem and pre-populates common phase structures, reducing planning
+> time for well-understood project types by 30-50%.
+
 **Timeline Questions:**
 1. Target completion date?
 2. Critical milestones?
@@ -117,19 +165,9 @@ Use the interview protocol from `@skills-library/_general/methodology/BACKWARD_P
 **Create directories:**
 
 ```bash
-mkdir -p .planning/breadcrumbs .planning/research .planning/phases
+mkdir -p .planning/research .planning/phases
 ```
 
-**Breadcrumbs are ON-DEMAND — do NOT create empty files.** Agents create breadcrumb files when they have something worth recording. The directory exists; the files don't — until earned.
-
-When agents write breadcrumbs, they use these EXACT names:
-- `breadcrumbs/LESSONS.md` — Solutions that worked
-- `breadcrumbs/FAILURES.md` — Approaches that failed
-- `breadcrumbs/PATTERNS.md` — Project conventions
-- `breadcrumbs/DEPENDENCIES.md` — Library gotchas
-
-> See `@skills-library/_general/methodology/LIVE_BREADCRUMB_PROTOCOL.md` for the full protocol.
-
 **Create CONSCIENCE.md** using template from `@templates/state.md`:
 - Project name and core value
 - Current phase: 1 of N (placeholder until ROADMAP.md exists)
@@ -144,14 +182,13 @@ When agents write breadcrumbs, they use these EXACT names:
 ├── PROJECT.md              # Step 2
 ├── REQUIREMENTS.md         # Step 2
 ├── CONSCIENCE.md           # Step 3
-├── breadcrumbs/            # Step 3 (empty dir — files created on-demand by agents)
 ├── research/               # empty, ready for /fire-1b-research
 └── phases/                 # empty, ready for /fire-2-plan
 ```
 
 **Verify before proceeding:**
 ```bash
-test -f .planning/PROJECT.md && test -f .planning/REQUIREMENTS.md && test -f .planning/CONSCIENCE.md && test -d .planning/breadcrumbs && echo "ALL FILES PRESENT" || echo "MISSING FILES — go back"
+test -f .planning/PROJECT.md && test -f .planning/REQUIREMENTS.md && test -f .planning/CONSCIENCE.md && echo "ALL FILES PRESENT" || echo "MISSING FILES — go back"
 ```
 
 ---
@@ -171,8 +208,6 @@ test -f .planning/PROJECT.md && test -f .planning/REQUIREMENTS.md && test -f .pl
 |    [x] .planning/PROJECT.md              <- requirements                     |
 |    [x] .planning/REQUIREMENTS.md         <- REQ-IDs                          |
 |    [x] .planning/CONSCIENCE.md           <- project state                    |
-|    [x] .planning/breadcrumbs/            <- on-demand memory (empty until    |
-|                                             agents record learnings)         |
 |                                                                              |
 |  Pending (created by next commands):                                         |
 |    [ ] research/SYNTHESIS.md             <- /fire-1b-research                 |

package/commands/fire-1c-setup.md

@@ -25,6 +25,7 @@ STEP 1: Validate prerequisites     → VISION.md + ROADMAP.md exist
 STEP 2: WARRIOR Handoff Init       → create handoff file
 STEP 3: Zero-Friction Tooling      → install CLIs from VISION.md, write TOOLING-LOG.md
 STEP 4: SKILLS-INDEX.md            → create empty tracking file
+STEP 4.5: Seed per-project skills/ → create skills/ folder + README.md + .gitkeep
 STEP 5: Update CONSCIENCE.md       → set status to "Ready to plan"
 STEP 6: MANDATORY FILE GATE        → verify ALL 16 files exist
 FINAL:  Completion Display          → show full project summary
@@ -129,6 +130,38 @@ Run `/fire-search [query]` to find relevant skills.
 
 ---
 
+## Step 4.5: Seed Per-Project Skills Folder
+
+**Create the project-local skills directory:**
+
+```bash
+mkdir -p {project_root}/skills
+touch {project_root}/skills/.gitkeep
+```
+
+**Create `{project_root}/skills/README.md`:**
+
+```markdown
+# Project Skills — {project_name}
+
+Project-specific patterns, workarounds, and solutions for this codebase.
+
+## Usage
+Add skills here when you discover a pattern worth preserving for this project.
+Use the skill name as the filename: `skill-name.md`
+
+## Global Skills
+Cross-project skills live in:
+`~/.claude/plugins/dominion-flow/skills-library/`
+
+Run `/fire-search` to find skills across both locations.
+```
+
+**Confirm to user:**
+> "Per-project `skills/` folder seeded. Add project-specific patterns here as you discover them."
+
+---
+
 ## Step 5: Update CONSCIENCE.md
 
 Update `.planning/CONSCIENCE.md`:
@@ -153,7 +186,6 @@ test -f .planning/VISION.md             || echo "MISSING: VISION.md"
 test -f .planning/ROADMAP.md            || echo "MISSING: ROADMAP.md"
 test -f .planning/research/ALTERNATIVES.md || echo "MISSING: ALTERNATIVES.md"
 test -f .planning/TOOLING-LOG.md        || echo "MISSING: TOOLING-LOG.md"
-test -d .planning/breadcrumbs           || echo "MISSING: breadcrumbs/"
 test -d .planning/phases                || echo "MISSING: phases/"
 echo "=== GATE COMPLETE ==="
 ```
@@ -206,10 +238,6 @@ For users who were in backward mode (beginners), save a brief DevTools orientati
 |    [x] .planning/research/SYNTHESIS.md   <- merged research + GitHub refs    |
 |    [x] .planning/research/ALTERNATIVES.md <- rejected branches               |
 |                                                                              |
-|  Memory:                                                                     |
-|    [x] .planning/breadcrumbs/            <- on-demand (agents create files   |
-|                                             when they record learnings)      |
-|                                                                              |
 |  Tooling:                                                                    |
 |    [x] .planning/TOOLING-LOG.md          <- installed CLIs                   |
 |    [x] WARRIOR handoff                   <- session continuity               |