@thierrynakoa/fire-flow 12.2.1 → 13.0.1

package/CREDITS.md

@@ -0,0 +1,25 @@
+# Credits & Attribution
+
+The following skills were adapted from external Claude Code plugins and are included with attribution to their original authors.
+
+## External Plugins
+
+- **ui-ux-pro-max** — UI/UX design intelligence: 50+ styles, 97 color palettes, 57 font pairings, 9 technology stacks. (`skills-library/ui-ux-pro-max/`)
+- **excalidraw-diagrams** — Programmatic Excalidraw diagram generation for flowcharts, architecture diagrams, and system designs. (`skills-library/excalidraw-diagrams/`)
+- **awesome-claude-code** — Workflow templates for design review, debugging, session handoff, and parallel research. (`skills-library/awesome-workflows/`)
+- **complexity-metrics** — Complexity divider feedback loop pattern for development velocity gains. (`skills-library/complexity-metrics/`)
+
+## All Other Skills
+
+All other skills in the library are original work by Dominion Flow contributors.
+
+---
+
+## AGENT INSTRUCTION — DO NOT MODIFY WITHOUT APPROVAL
+
+> **This file is manually curated. Do NOT add entries to CREDITS.md without
+> explicit discussion and approval from Thierry.** This includes skill
+> contributions, project names, repository names, or any other attribution.
+> Private repository names, internal project names, and contributor details
+> must NEVER appear in this file. If you believe a credit should be added,
+> ask Thierry first — do not write it.

package/DOMINION-FLOW-OVERVIEW.md

@@ -1,8 +1,29 @@
-# Dominion Flow v12.2 -- Complete System Overview
+# Dominion Flow v13.0 -- Complete System Overview
 
 Bird's eye view of the entire Dominion Flow system.
 
-**Three Pillars:** Honesty Gate (accept mistakes, never blame) · Live Breadcrumbs (each instance smarter than the last) · Zero-Friction Tooling (ideas in, working app out)
+**Three Pillars:** Honesty Gate (accept mistakes, never blame) · Continuous Learning (each instance smarter than the last) · Zero-Friction Tooling (ideas in, working app out)
+
+**v13.0 Research-Backed Enhancements (17 changes, 3 waves, 8 files):**
+
+Wave 1 — Foundation:
+- Societies of Thought plan critique (arXiv 2601.10825 — 3 perspectives before execution)
+- Spec-Driven contract verification (arXiv 2602.00180 — machine-checkable specs)
+- SE-Agent TDD Guard validation (test execution before implementation)
+- Implied Scenario Capture (trajectory revision — detect side effects post-task)
+- Structured STUCK REPORT → fire-researcher pipeline (format for automated research)
+- Variation Injection (Manus AI — break attention loops when stuck)
+- CNCF Four Pillars taxonomy (Observability/Governance/Security/Lifecycle rule classification)
+
+Wave 2 — Intelligence:
+- FoldAgent cross-turn compression (92% reduction extending context life 40-60%)
+- Frequency-Ranked Core Learnings (most-used rules injected first — natural selection for rules)
+- Background Agent Execution (previously BLOCKED, now wired via async subagents)
+
+Wave 3 — Decision:
+- Multi-Agent Reflexion (root cause analysis of verification gaps, targeted fix instructions)
+- Adversarial Judge separation (judge agents READ-ONLY, executor agents WRITE-ONLY)
+- Magentic-UI confidence escalation (critical <20% confidence triggers human question)
 
 **v12.0 Research-Backed Enhancements:**
 - Tiered Verification (fast gate before slow gate — shift-left)
@@ -18,7 +39,7 @@ Bird's eye view of the entire Dominion Flow system.
 
 ```
 +==============================================================================+
-|                        DOMINION FLOW v12.2 -- COMPLETE SYSTEM MAP             |
+|                        DOMINION FLOW v13.0 -- COMPLETE SYSTEM MAP             |
 +==============================================================================+
 
 
@@ -43,29 +64,29 @@ Bird's eye view of the entire Dominion Flow system.
    VISION.md (LOCKED)       |                    |              +----+----+
    CONSCIENCE.md            |                    |              |  PASS?  |
    TOOLING-LOG.md           |                    |              +----+----+
-   breadcrumbs/             |                    |            yes/     \no
-         |                  |                    |           /           \
+                             |                    |            yes/     \no
+                             |                    |           /           \
   +------+------------------+--------------------+----------+   +----------------+
   |           NEXT PHASE / MILESTONE                        |   | RECOVERY LOOP  |
   |       (loop back to /fire-2-plan)                      |   | (v11.2)        |
   +--------------------------------------------------------+   |                |
                                                                 | 1. Researcher  |
-  LIVE BREADCRUMBS (v11.2) -- updated by ALL agents:            |    searches:   |
-  +------------------------------------------------------+     |    Skills DB   |
-  | breadcrumbs/LESSONS.md     -- what worked              |     |    Context7    |
-  | breadcrumbs/FAILURES.md    -- what didn't + why        |     |    Web (last)  |
-  | breadcrumbs/PATTERNS.md    -- recurring patterns       |     |                |
-  | breadcrumbs/DEPENDENCIES.md -- env, packages, gotchas  |     | 2. Returns 2-3 |
-  +------------------------------------------------------+     |    alternatives|
+                                                                |    searches:   |
+                                                                |    Skills DB   |
+                                                                |    Context7    |
+                                                                |    Web (last)  |
+                                                                |                |
+                                                                | 2. Returns 2-3 |
+                                                                |    alternatives|
                                                                 |    ranked by   |
-  DEAD ENDS (v11.3 — merged into FAILURES.md):                   |    confidence  |
-  +------------------------------------------------------+     |                |
-  | breadcrumbs/FAILURES.md [DEAD-END] tagged entries      |     | 3. Planner     |
-  |                                                        |     |    picks best  |
-  | Agent hits wall (3+ attempts) --> SHELVE & move on     |     |    alternative |
-  | Fresh Claude on /fire-6-resume --> reads shelf,        |     |    NEW blueprint|
-  |   attempts highest-priority problem with clean context |     +-------+--------+
-  +------------------------------------------------------+             |
+                                                                |    confidence  |
+                                                                |                |
+                                                                | 3. Planner     |
+                                                                |    picks best  |
+                                                                |    alternative |
+                                                                |    NEW blueprint|
+                                                                +-------+--------+
+                                                                        |
                                                                         v
                                                                   back to /fire-2-plan
                                                                   (with new approach)
@@ -80,16 +101,16 @@ Bird's eye view of the entire Dominion Flow system.
   | Dead ends shelved mid-run, solved on next session.               |
   +------------------------------------------------------------------+
 
-  PHOENIX REBUILD (v12.2):
+  RESURRECTION MODE (v12.2):
   +------------------------------------------------------------------+
-  | /fire-phoenix --source <path>                                     |
+  | /fire-resurrect --source <path>                                   |
   |                                                                  |
   | Takes a messy "vibe coded" project and rebuilds it clean:        |
   |   AUTOPSY --> INTENT --> CLARIFY --> VISION --> REBUILD --> COMPARE|
   | Source is READ-ONLY. Rebuild goes to new target folder.          |
   | Extracts INTENT (what code was trying to do), asks user about    |
   | ambiguities, then rebuilds using full Dominion Flow pipeline.    |
-  | Phoenix Score: PX-1 to PX-5 (feature parity, edge cases, etc.)  |
+  | Resurrection Score: PX-1 to PX-5 (feature parity, edge cases)   |
   +------------------------------------------------------------------+
 
   SESSION BOUNDARIES:
@@ -97,7 +118,7 @@ Bird's eye view of the entire Dominion Flow system.
   |/fire-5-hand  |  === session break ===>      |/fire-6-resum |
   |   off        |   POWER-HANDOFF-*.md         |     e        |
   | Save context |   (WARRIOR 7-step)           | Load context |
-  | + breadcrumbs|                              | + breadcrumbs|
+  |              |                              |              |
   +--------------+                              +--------------+
 
   [H] = Honesty Gate -- mandatory 3-question checkpoint at every agent
@@ -136,7 +157,7 @@ Bird's eye view of the entire Dominion Flow system.
                                 Anti-Frankenstein gate prevents
                                 incompatible stack combos.
 
-  fire-phoenix-analyst.md       Reverse-engineers developer intent    /fire-phoenix
+  fire-resurrection-analyst.md  Reverse-engineers developer intent    /fire-resurrect
                                 from messy codebases. Extracts what
                                 code was TRYING to do. Produces
                                 INTENT.md + INTENT-GRAPH.md.
@@ -152,7 +173,7 @@ Bird's eye view of the entire Dominion Flow system.
   | fire-verifier           |    Y     |       |      |  Y   |  Y   |         |          |
   | fire-reviewer           |    Y     |       |      |  Y   |  Y   |         |          |
   | fire-vision-architect   |    Y     |   Y   |      |      |  Y   |         |          | ← Forward + Backward modes
-  | fire-phoenix-analyst    |    Y     |   Y   |      |  Y   |  Y   |         |          | ← Intent extraction
+  | fire-resurrection-analyst|   Y     |   Y   |      |  Y   |  Y   |         |          | ← Intent extraction
   +-------------------------+----------+-------+------+------+------+---------+----------+
 
 
@@ -243,7 +264,7 @@ Bird's eye view of the entire Dominion Flow system.
   │  +----------------------+                           │
   │  | Write PROJECT.md     |  Core value, constraints  │
   │  | Write REQUIREMENTS   |  REQ-IDs                  │
-  │  | Create .planning/    |  breadcrumbs/ (on-demand)  │
+  │  | Create .planning/    |  project scaffold          │
   │  +----------+-----------+                           │
   │             |                                       │
   │  OUTPUT: 8 files (.planning/ scaffold)              │
@@ -367,11 +388,6 @@ Bird's eye view of the entire Dominion Flow system.
       +-- PROJECT.md                  <-- Core value, users, constraints
       +-- TOOLING-LOG.md             <-- CLI tools installed + versions (v11.2)
       |
-      +-- breadcrumbs/               <-- Live memory across agents (on-demand, v11.3)
-      |   +-- LESSONS.md              <-- What worked (created on first write)
-      |   +-- FAILURES.md             <-- What didn't + why + [DEAD-END] entries (created on first write)
-      |   +-- PATTERNS.md             <-- Recurring patterns (created on first write)
-      |   +-- DEPENDENCIES.md         <-- Env, packages, gotchas (created on first write)
       |
       +-- research/                   <-- Created by /fire-1a-new
       |   +-- STACK.md
@@ -486,7 +502,7 @@ Bird's eye view of the entire Dominion Flow system.
   /fire-1b-research          /fire-loop              /fire-discover
   /fire-1c-setup             /fire-loop-resume       /fire-map-codebase
   /fire-1d-discuss          /fire-loop-stop         /fire-0-orient
-  /fire-2-plan               /fire-phoenix           /fire-research
+  /fire-2-plan               /fire-resurrect         /fire-research
   /fire-3-execute                                    /fire-brainstorm
   /fire-4-verify
   /fire-5-handoff
@@ -537,7 +553,7 @@ Bird's eye view of the entire Dominion Flow system.
          |                     |                     |
          |     +---------------v--------------+      |
          +---->|   .planning/ STATE           |<-----+
-               |   + breadcrumbs/ (on-demand)  |
+               |   + project state             |
                |   + TOOLING-LOG.md           |
                +---------------+--------------+
                                |
@@ -548,22 +564,150 @@ Bird's eye view of the entire Dominion Flow system.
                                |
                +---------------v--------------+
                |  WARRIOR HANDOFFS            |
-               |  + breadcrumbs preserved     |
+               |  + context preserved         |
                |  + dead ends documented      |
                |  (session continuity)        |
                +------------------------------+
 ```
 
+
+===============================================================================
+ 11. v13.0 INTELLIGENCE ARCHITECTURE -- New Systems Explained
+===============================================================================
+
+  v13.0 adds 3 intelligence layers on top of the v12.0 execution pipeline.
+  Each layer operates at a different phase of the lifecycle:
+
+  PLANNING TIME (before code):
+  +-------------------------------------------------------------------+
+  |  SOCIETIES OF THOUGHT (Step 5.5 in /fire-2-plan)                   |
+  |                                                                   |
+  |  Blueprint Ready                                                  |
+  |       |                                                           |
+  |       v                                                           |
+  |  +-----------------+  +-----------------+  +-----------------+    |
+  |  | DEVIL'S         |  | DOMAIN          |  | RISK            |    |
+  |  | ADVOCATE         |  | EXPERT          |  | ASSESSOR        |    |
+  |  |                 |  |                 |  |                 |    |
+  |  | "What could go  |  | "Does this fit  |  | "What's the     |    |
+  |  |  wrong?"        |  |  the codebase?" |  |  blast radius?" |    |
+  |  +---------+-------+  +---------+-------+  +---------+-------+    |
+  |            |                    |                    |             |
+  |            v                    v                    v             |
+  |         1-3 concerns        1-3 concerns        1-3 concerns      |
+  |            |                    |                    |             |
+  |            +--------- MERGE --------+                             |
+  |                        |                                          |
+  |                   HIGH concerns --> planner addresses              |
+  |                   MED/LOW       --> logged in BLUEPRINT risks:     |
+  +-------------------------------------------------------------------+
+
+  EXECUTION TIME (during code):
+  +-------------------------------------------------------------------+
+  |  CONTEXT MANAGEMENT PIPELINE                                       |
+  |                                                                   |
+  |  Iteration 1  2  3  4  5  6  7  8  9  10 ... 25 ... 35 ... 40    |
+  |       |       |  |  |  |  |  |  |  |   |      |      |      |    |
+  |       |       |  A  |  F  A  |  A  |   F+A    A      F+A    |    |
+  |       |       |  C  |  o  C  |  C  |   C      C      C      |    |
+  |       |       |  O  |  l  O  |  O  |   O      O      O      |    |
+  |       |       |  N  |  d  N  |  N  |   N      N      N      |    |
+  |                                                                   |
+  |  ACON = within-turn compression (every 3 iters, 26-54% savings)   |
+  |  Fold = cross-turn folding (every 5 iters, 92% on old turns)      |
+  |                                                                   |
+  |  WITHOUT:  context rot at ~15 iterations                          |
+  |  +ACON:    context rot at ~25 iterations                          |
+  |  +ACON+Fold: context rot at ~35-40 iterations                    |
+  |                                                                   |
+  |  VARIATION INJECTION (when stuck):                                |
+  |                                                                   |
+  |  SPINNING ──> REFRAME or CONSTRAINT FLIP ──> retry with fresh     |
+  |  FIXATION ──> EXEMPLAR SWAP or SCALE SHIFT ──> new perspective    |
+  +-------------------------------------------------------------------+
+
+  |  CONFIDENCE ESCALATION (v13.0 — Magentic-UI):                     |
+  |                                                                   |
+  |  Score 100─────────────────────── HIGH: autonomous                 |
+  |        80─────────────────────── MEDIUM: extra validation          |
+  |        50─────────────────────── LOW: research first               |
+  |        20─────────────────────── CRITICAL: ask human (NEW v13.0)   |
+  |         0                                                         |
+  |                                                                   |
+  |  Below 20%: "I need to know X to proceed. Options: A, B, C."     |
+  |  Prevents "confident but wrong" implementations                   |
+  +-------------------------------------------------------------------+
+
+  VERIFICATION TIME (after code):
+  +-------------------------------------------------------------------+
+  |  ADVERSARIAL JUDGE SEPARATION (v13.0)                              |
+  |                                                                   |
+  |  fire-executor (WRITE)    fire-verifier (READ-ONLY)               |
+  |  ┌──────────────────┐    ┌──────────────────────┐                 |
+  |  │ Can: Edit, Write │    │ Can: Read, Grep, Bash│                 |
+  |  │ Cannot: Judge    │    │ Cannot: Edit, Write  │                 |
+  |  │ quality          │    │ Reports gaps only     │                 |
+  |  └────────┬─────────┘    └────────┬─────────────┘                 |
+  |           │                       │                               |
+  |           │        ┌──────────────┘                               |
+  |           │        │                                              |
+  |           v        v                                              |
+  |  +------------------+                                             |
+  |  | MULTI-AGENT      |   Root cause analysis of gaps:              |
+  |  | REFLEXION         |   PLANNING_GAP → re-plan                    |
+  |  | (v13.0)          |   EXECUTION_GAP → re-execute specific task   |
+  |  |                  |   SCOPE_CREEP → defer to next phase          |
+  |  +--------+---------+   TOOLING_GAP → setup infrastructure        |
+  |           │                                                       |
+  |           v                                                       |
+  |  Targeted fix instructions (not just "something failed")          |
+  +-------------------------------------------------------------------+
+
+  BEHAVIORAL INTELLIGENCE:
+  +-------------------------------------------------------------------+
+  |  CNCF FOUR PILLARS TAXONOMY                                        |
+  |                                                                   |
+  |  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌──────────┐ |
+  |  │OBSERVABILITY│  │ GOVERNANCE  │  │  SECURITY   │  │LIFECYCLE │ |
+  |  │             │  │             │  │             │  │          │ |
+  |  │ R5 R10 R11  │  │ R6 R12     │  │ R1 R2 R4   │  │ R3 R7 R8 │ |
+  |  │ AP2 AP3     │  │ AP5        │  │ AP1        │  │ R9 AP4   │ |
+  |  │ ALWAYS:tests│  │ ALWAYS:git │  │ NEVER:creds│  │ WHEN:conf│ |
+  |  └─────────────┘  └─────────────┘  └─────────────┘  └──────────┘ |
+  |                                                                   |
+  |  FREQUENCY-RANKED CORE LEARNINGS:                                 |
+  |    Top 5 rules by usage frequency → injected into every executor  |
+  |    Rules 6-12 → available via DTG lookup (on demand)              |
+  |    0 applications in 30 days → "Dormant" (candidate for retire)   |
+  +-------------------------------------------------------------------+
+
+  BACKGROUND AGENT EXECUTION (v13.0 — previously BLOCKED):
+  +-------------------------------------------------------------------+
+  |  FOREGROUND (must complete before next step):                      |
+  |    fire-executor, fire-verifier, fire-reviewer                    |
+  |                                                                   |
+  |  BACKGROUND (fire-and-forget, notification on complete):           |
+  |    Skill extraction (Step 7.7)                                    |
+  |    Research spawns from STUCK REPORT                              |
+  |    Episodic memory indexing                                       |
+  |    Test suite runs (non-gating)                                   |
+  |                                                                   |
+  |  Max 2 background agents at a time                                |
+  |  Background agents: READ-ONLY, no shared-state writes             |
+  +-------------------------------------------------------------------+
+
+
 ---
 
 ## Version History
 
 | Version | Date | Headline Features |
 |---------|------|-------------------|
-| v12.2 | 2026-03-06 | Phoenix Rebuild: `/fire-phoenix` autonomous rebuild from messy-to-clean. fire-phoenix-analyst agent (intent extraction), PHOENIX_REBUILD_METHODOLOGY skill (anti-pattern map, intent graph, edge case protocol), GOF_DESIGN_PATTERNS_FOR_AI_AGENTS skill, phoenix-comparison template, PX-1 to PX-5 verification checks |
+| v12.6 | 2026-03-12 | Dead Code Activation + Intelligence + Skill CLI: Error classification wired into task execution (5 health states), Tier 1 shift-left verification (per-task fast gate), Version Performance Registry recording, TDD Guard pre-execution enforcement (TDAD arXiv 2603.08806), Spec-Driven Development in planning (arXiv 2602.00180), Societies of Thought multi-perspective critique (arXiv 2601.10825), Decision-Time behavioral directive injection (Replit DTG), A-MEM cross-linking deferred, unified /fire-skill CLI (8 subcommands, 6 templates, 3 scripts) |
+| v12.2 | 2026-03-06 | Resurrection Mode: `/fire-resurrect` autonomous rebuild from messy-to-clean. fire-resurrection-analyst agent (intent extraction), PHOENIX_REBUILD_METHODOLOGY skill (anti-pattern map, intent graph, edge case protocol), GOF_DESIGN_PATTERNS_FOR_AI_AGENTS skill, resurrection-comparison template, PX-1 to PX-5 verification checks |
 | v12.1 | 2026-03-06 | v12.0 audit fixes: Tier naming alignment, DORA metrics in autonomous, Requirements Decomposition in discuss, researcher skill awareness, circuit breaker weight alignment |
 | v12.0 | 2026-03-06 | Research-backed upgrade: 6 new methodology skills (Reliability Prediction, Quality Gates, Circuit Breaker Intelligence, Context Rotation, Autonomous Orchestration, Requirements Decomposition), tiered verification, stuck-state classification, kill conditions, scope manifests, implied scenario detection |
-| v11.2 | 2026-03-06 | Branching Vision System + Honesty Gate + Zero-Friction CLI + Dead Ends Shelf: fire-vision-architect (Forward + Backward modes), Anti-Frankenstein gate, Visual Input fast-track (screenshots/wireframes/sketches), BACKWARD_PLANNING_INTERVIEW (10 beginner questions), ZERO_FRICTION_CLI_SETUP (auto-install all tools from VISION.md), DevTools guide for beginners, Honesty Gate universal enforcement (slim 10-line gates referencing canonical protocol), Live Breadcrumb Protocol (LESSONS/FAILURES/PATTERNS/DEPENDENCIES), Dead Ends Shelf (DEAD-ENDS.md — shelve unsolved problems, fresh instance retries on resume), Recovery Research Loop (Skills→Context7→Web), Verifier isolation (fresh instance), Playwright MCP non-negotiable |
+| v11.2 | 2026-03-06 | Branching Vision System + Honesty Gate + Zero-Friction CLI + Dead Ends Shelf: fire-vision-architect (Forward + Backward modes), Anti-Frankenstein gate, Visual Input fast-track (screenshots/wireframes/sketches), BACKWARD_PLANNING_INTERVIEW (10 beginner questions), ZERO_FRICTION_CLI_SETUP (auto-install all tools from VISION.md), DevTools guide for beginners, Honesty Gate universal enforcement (slim 10-line gates referencing canonical protocol), Dead Ends Shelf (shelve unsolved problems, fresh instance retries on resume), Recovery Research Loop (Skills→Context7→Web), Verifier isolation (fresh instance), Playwright MCP non-negotiable |
 | v9.1 | 2026-02-24 | Research-backed intelligence: ReflexTree debugging, MAKER reasoning sharing, MemP failure memory, ATLAS agent selection, CriticGPT review profiles |
 | v1.0 | 2026-01 | Initial 6-command workflow (new, plan, execute, verify, handoff, resume) |
 | v2.0 | 2026-01 | Skills library integration, breath-based parallel execution |
@@ -578,4 +722,4 @@ Bird's eye view of the entire Dominion Flow system.
 
 ---
 
-*Generated 2026-03-06 -- Dominion Flow v12.2*
+*Generated 2026-03-12 -- Dominion Flow v12.6*