@thierrynakoa/fire-flow 12.2.1 → 13.0.1

package/skills-library/_general/methodology/HIERARCHICAL_REVIEW_MARS.md

@@ -0,0 +1,122 @@
+---
+name: Hierarchical Review (MARS Pattern)
+category: methodology
+version: 1.0.0
+contributed: 2026-03-12
+contributor: fire-research
+last_updated: 2026-03-13
+tags: [verification, review, token-optimization, self-check, multi-tier, meta-reviewer]
+difficulty: medium
+---
+
+# Hierarchical Review (MARS) — Author Self-Check Before Expensive Review
+
+> (arXiv 2509.20502, Sep 2025) — hierarchical author→reviewer→meta-reviewer
+> cuts total verification tokens by ~50%.
+
+## Problem
+
+In AI-assisted development, verification is expensive. A full verifier + reviewer pass costs 2,000-5,000 tokens and takes significant time. But 60-70% of issues found by external review are things the author already knew about — low confidence in a section, skipped requirements, known gaps. Running expensive external review to discover what the author could have flagged is wasted computation.
+
+## Solution Pattern
+
+A 3-tier review hierarchy where each tier is a progressively more expensive filter:
+
+```
+Tier 1: AUTHOR SELF-CHECK (~100 tokens)
+  The executor checks its own work against the plan.
+  Catches: missing must-haves, low-confidence tasks, known gaps.
+  If this fails → fix BEFORE spawning external review.
+
+Tier 2: EXTERNAL REVIEW (~2,000 tokens)
+  Verifier + reviewer check the work independently.
+  Catches: logic errors, quality issues, over-engineering.
+  Receives self-check summary to avoid redundant checks.
+
+Tier 3: META-REVIEW (~500 tokens, only on disagreement)
+  Arbitrates when Tier 2 reviewers disagree.
+  Voting, weighted resolution, or fork strategy.
+```
+
+### Tier 1: Author Self-Check
+
+```
+FOR each executor's output (RECORD.md):
+  EXTRACT:
+    - files_changed list
+    - must_haves_addressed (cross-reference BLUEPRINT)
+    - known_gaps (executor's own honesty declarations)
+    - test_results (if any)
+    - confidence score (from return envelope)
+
+  QUICK VALIDATION:
+    1. Every must-have has at least one file addressing it
+    2. No must-have is marked "skipped" without documented reason
+    3. Executor's own confidence >= 60
+
+  IF self_check_fails:
+    → Route BACK to executor for fix BEFORE Tier 2
+    → Log: "Self-check failed: {reason} — re-executing"
+    → Saves ~2,000 tokens vs. external review finding the same gap
+
+  IF self_check_passes:
+    → Proceed to Tier 2
+    → Pass self_check_summary as context (reduces redundant checks)
+```
+
+### Token Economics
+
+| Scenario | Without MARS | With MARS | Savings |
+|----------|-------------|-----------|---------|
+| Clean pass (no issues) | 2,500 tokens | 2,600 tokens | -4% (overhead) |
+| Self-checkable failure | 5,000 tokens | 600 tokens | 88% |
+| External review needed | 2,500 tokens | 2,600 tokens | -4% (overhead) |
+| Disagreement arbitration | 3,000 tokens | 3,500 tokens | -17% (overhead) |
+| **Weighted average** | **3,250 tokens** | **1,825 tokens** | **~44%** |
+
+The 88% savings on self-checkable failures (which are 60-70% of cases) more than compensates for the small overhead on clean passes.
+
+## Implementation Steps
+
+1. Add self-check step BEFORE spawning external verification
+2. Extract structured data from executor output (RECORD.md, return envelope)
+3. Cross-reference against BLUEPRINT must-haves
+4. Route failures back to executor, passes forward to verification
+5. Pass self-check summary to verifier as context
+
+## When to Use
+
+- Any automated verification pipeline with expensive external review
+- Multi-phase project execution where each phase is verified
+- CI/CD pipelines where you can add a "pre-flight check" before full test suite
+- Code review workflows where author self-review precedes peer review
+
+## When NOT to Use
+
+- Single-task executions where the overhead exceeds the benefit
+- When the author's self-assessment is unreliable (new contributors, adversarial context)
+- When verification is already cheap (< 500 tokens or < 30 seconds)
+
+## Must Do
+
+- Keep Tier 1 lightweight (~100 tokens) — it's a filter, not a review
+- Pass Tier 1 results to Tier 2 as context (prevents redundant discovery)
+- Preserve the `--skip-self-check` escape hatch for debugging
+
+## Must Not Do
+
+- Do not make Tier 1 as thorough as Tier 2 (defeats the purpose)
+- Do not skip Tier 2 just because Tier 1 passes (self-assessment has blind spots)
+- Do not use Tier 1 to suppress known issues (it's for catching them, not hiding them)
+
+## Related Skills
+
+- [VOTING_VERDICT_ARBITRATION](./VOTING_VERDICT_ARBITRATION.md) — Tier 3 meta-review pattern
+- [OBSERVATION_MASKING](./OBSERVATION_MASKING.md) — reduces token cost at each tier
+- [MULTI_AGENT_COORDINATION](./MULTI_AGENT_COORDINATION.md) — parent coordination framework
+
+## References
+
+- "MARS: Meta-reviewer Arbitrated Review System" — arXiv 2509.20502, Sep 2025
+- Wired into: `fire-3-execute.md` Step 7.9 (Hierarchical Review — Author Self-Check)
+- Complementary to: `fire-3-execute.md` Step 7.85 (Execution Insights Aggregation)

package/skills-library/_general/methodology/MCP_INTER_AGENT_BRIDGE.md

@@ -0,0 +1,207 @@
+# MCP Inter-Agent Communication Bridge
+
+> Use an MCP server as a message bus between Claude Code instances for coordinated multi-agent workflows.
+
+**When to use:** When you need two or more Claude Code instances (running in separate terminals) to communicate — beyond what `.claude/agents/` subagents or Agent Teams provide. Useful for: cross-repo review, long-running monitoring, or heterogeneous agent setups.
+**Stack:** Node.js/TypeScript, MCP SDK
+
+---
+
+## When to Use This vs Alternatives
+
+| Need | Best Approach |
+|------|--------------|
+| Single reviewer in same session | `.claude/agents/` subagent file |
+| Fire-and-forget CLI review | `claude -p "prompt"` |
+| Competing reviewers that discuss | Agent Teams (experimental) |
+| Standalone review server | Agent SDK |
+| **Cross-instance communication** | **MCP bridge (this skill)** |
+| **Persistent message bus** | **MCP bridge (this skill)** |
+
+---
+
+## Architecture
+
+```
+┌─────────────────────┐     ┌─────────────────────┐
+│ Claude Code          │     │ Claude Code          │
+│ Instance A           │     │ Instance B           │
+│ (executor)           │     │ (reviewer)           │
+│                      │     │                      │
+│ MCP Client ──────────┼─────┼─▶ MCP Client         │
+│                      │     │                      │
+└──────────┬───────────┘     └──────────┬───────────┘
+           │                            │
+           │    ┌──────────────────┐    │
+           └───▶│  MCP Bridge      │◀───┘
+                │  Server          │
+                │                  │
+                │  Tools:          │
+                │  - submit_review │
+                │  - get_verdict   │
+                │  - send_message  │
+                │  - get_messages  │
+                └──────────────────┘
+```
+
+---
+
+## Simple File-Based Bridge (No Server Required)
+
+The simplest MCP-less approach — use the filesystem as a message queue:
+
+```javascript
+// Agent A writes a review request
+const request = {
+  id: crypto.randomUUID(),
+  type: 'review_request',
+  from: 'executor',
+  files: ['src/routes/payment.ts', 'src/controllers/checkout.ts'],
+  prompt: 'Review these files for security issues',
+  created_at: new Date().toISOString(),
+};
+fs.writeFileSync('.planning/.agent-inbox/review-request.json', JSON.stringify(request, null, 2));
+
+// Agent B polls for requests and writes verdict
+const verdict = {
+  id: crypto.randomUUID(),
+  request_id: request.id,
+  type: 'review_verdict',
+  from: 'reviewer',
+  verdict: 'APPROVE_WITH_FIXES',
+  issues: [{ severity: 'major', file: 'src/routes/payment.ts', line: 42, description: 'Missing auth check' }],
+  created_at: new Date().toISOString(),
+};
+fs.writeFileSync('.planning/.agent-inbox/review-verdict.json', JSON.stringify(verdict, null, 2));
+
+// Agent A reads verdict
+const result = JSON.parse(fs.readFileSync('.planning/.agent-inbox/review-verdict.json', 'utf-8'));
+```
+
+### Directory Structure
+
+```
+.planning/.agent-inbox/
+  review-request.json      # Executor → Reviewer
+  review-verdict.json      # Reviewer → Executor
+  messages.jsonl           # Append-only message log
+```
+
+---
+
+## Using claude-code-mcp (steipete)
+
+Run Claude Code itself as an MCP server that other agents can invoke:
+
+```bash
+# Install
+npx -y @anthropic-ai/claude-code mcp add claude-code-mcp -- npx -y @anthropic-ai/claude-code --dangerously-skip-permissions
+
+# Now any MCP client can call:
+# Tool: claude_code
+# Input: { "prompt": "Review src/payment.ts for security issues", "workFolder": "/path/to/project" }
+```
+
+This gives any Claude Code instance a `claude_code` tool that spawns another Claude Code instance as a one-shot tool call. The "agent in your agent" pattern.
+
+---
+
+## Custom MCP Bridge Server
+
+For more control, build a simple MCP server:
+
+```typescript
+// bridge-server.ts
+import { McpServer } from "@anthropic-ai/mcp-sdk";
+
+const messages: any[] = [];
+const verdicts: Map<string, any> = new Map();
+
+const server = new McpServer({
+  name: "agent-bridge",
+  version: "1.0.0",
+});
+
+server.tool("submit_review_request", {
+  description: "Submit code for review by another agent",
+  inputSchema: {
+    type: "object",
+    properties: {
+      files: { type: "array", items: { type: "string" } },
+      prompt: { type: "string" },
+      priority: { type: "string", enum: ["low", "medium", "high"] },
+    },
+    required: ["files", "prompt"],
+  },
+  handler: async (input) => {
+    const id = crypto.randomUUID();
+    messages.push({ id, type: "review_request", ...input, created_at: new Date() });
+    return { request_id: id, status: "queued" };
+  },
+});
+
+server.tool("get_pending_reviews", {
+  description: "Get pending review requests",
+  inputSchema: { type: "object", properties: {} },
+  handler: async () => {
+    const pending = messages.filter(m => m.type === "review_request" && !verdicts.has(m.id));
+    return { pending };
+  },
+});
+
+server.tool("submit_verdict", {
+  description: "Submit a review verdict",
+  inputSchema: {
+    type: "object",
+    properties: {
+      request_id: { type: "string" },
+      verdict: { type: "string", enum: ["APPROVE", "APPROVE_WITH_FIXES", "BLOCK"] },
+      issues: { type: "array" },
+    },
+    required: ["request_id", "verdict"],
+  },
+  handler: async (input) => {
+    verdicts.set(input.request_id, input);
+    return { status: "recorded" };
+  },
+});
+
+server.tool("get_verdict", {
+  description: "Check if a review verdict is available",
+  inputSchema: {
+    type: "object",
+    properties: { request_id: { type: "string" } },
+    required: ["request_id"],
+  },
+  handler: async (input) => {
+    const verdict = verdicts.get(input.request_id);
+    return verdict || { status: "pending" };
+  },
+});
+
+server.start();
+```
+
+---
+
+## Practical Recommendation
+
+For most Dominion Flow users, the **file-based bridge** is sufficient:
+1. No extra server to run
+2. Both agents can read/write to `.planning/.agent-inbox/`
+3. JSONL append log provides audit trail
+4. Works on all platforms
+
+Use the MCP server approach only when:
+- Agents run on different machines
+- You need real-time communication (not polling)
+- You're building a production orchestration service
+
+---
+
+## Sources
+
+- steipete/claude-code-mcp (GitHub) — Claude Code as MCP server
+- GongRzhe/ACP-MCP-Server (GitHub) — ACP-MCP bridge
+- Claude Code MCP documentation (2026)
+- Internal gap analysis: Auto-connect agents research TODO

package/skills-library/_general/methodology/MERMAID_WIZARD_DIAGRAMS.md

@@ -0,0 +1,77 @@
+---
+name: MERMAID_WIZARD_DIAGRAMS
+category: methodology
+description: Add Mermaid graph LR diagrams to wizard commands to improve LLM step adherence
+version: 1.0.0
+tags: [wizard, mermaid, step-adherence, multi-step, llm-reliability]
+---
+
+# Mermaid Wizard Diagrams
+
+## Problem
+
+Multi-step wizard commands (commands with 5+ steps) suffer from step-skipping or
+out-of-order execution when described only in prose. LLMs compress prose into summaries
+and then execute from memory, introducing gaps.
+
+**Symptom:** Wizard jumps from Step 2 to Step 5. Review panel appears before all
+information is collected. Steps are merged or reordered.
+
+## Solution
+
+Add a Mermaid `graph LR` diagram immediately after the first `## Process` heading.
+The diagram declares all steps and their sequence as machine-readable structure —
+not decoration.
+
+```markdown
+## Wizard Step Sequence
+
+```mermaid
+graph LR
+    S1[1: Describe Problem] --> S2[2: Select Category]
+    S2 --> S25[2.5: Scope Classification]
+    S25 --> S3[3: Name the Skill]
+    S3 --> S4[4: Capture Solution]
+    S4 --> S5[5: Code Example]
+    S5 --> S55[5.5: Review All Answers]
+    S55 --> S6[6: Save + Confirm]
+```
+```
+
+## Rules
+
+1. **Number every node** — `S1`, `S2`, `S25`, `S3` etc. Fractional numbers (2.5) mark
+   optional/conditional steps without renumbering the main flow.
+2. **Match node labels to section headings** — `S3[3: Name the Skill]` must match
+   `### Step 3: Name the Skill` exactly. Inconsistency defeats the purpose.
+3. **Place BEFORE the numbered step sections** — The diagram is an index. Prose sections
+   follow it in order.
+4. **Include conditional steps** — If a step is conditional (e.g., only runs for
+   advanced users), include it in the diagram with a note, not omit it.
+
+## When to Add
+
+Add this diagram to ANY command file with 4+ steps. Single-pass commands (read a file,
+do a thing, confirm) do not need it.
+
+**Existing commands updated in v12.3:**
+- `fire-1d-discuss.md`
+- `fire-add-new-skill.md`
+- `fire-scaffold.md`
+- `fire-setup.md`
+
+## Why It Works
+
+**FlowBench (EMNLP 2024):** Multi-step task benchmarks show LLMs adhere to step
+sequences significantly better when the sequence is expressed as graph structure vs.
+prose description. Mermaid is the most widely-parsed graph format in training data.
+
+**Mechanism:** Graph format creates an explicit index the LLM can refer back to.
+Prose is summarized into compressed representations; structured diagrams are parsed
+as literal sequences.
+
+## Research Basis
+
+> **FlowBench** (EMNLP 2024) — Multi-step workflow evaluation. Mermaid graph format
+> improves LLM step adherence vs. prose descriptions of the same sequence.
+> Applied: All wizard commands now open their Process section with a Mermaid step map.

package/skills-library/_general/methodology/MISSING_DIMENSION_DETECTOR.md

@@ -0,0 +1,89 @@
+---
+name: MISSING_DIMENSION_DETECTOR
+category: methodology
+description: Proactively ask what dimension hasn't been covered before advancing wizard steps
+version: 1.0.0
+tags: [wizard, proactive-questioning, requirements, information-gathering, llm-reliability]
+---
+
+# Missing-Dimension Detector
+
+## Problem
+
+Wizards collect only what they're told to ask. A user building a React component answers
+all 4 questions but never mentions authentication. The wizard generates unauthenticated
+code. The user didn't know to mention it; the wizard didn't know to ask.
+
+**Result:** Scaffolded or planned output is missing a critical dimension the user
+assumed was covered.
+
+## Solution
+
+Before advancing from an information-collection step, the LLM asks itself one internal
+question and acts on the answer:
+
+```
+Ask internally: "What dimension is commonly required for a {type} of this kind
+that hasn't been mentioned yet?"
+
+If a critical missing dimension is detected → ask ONE follow-up question.
+If nothing critical is missing → advance to next step.
+```
+
+This is a **silent gate** — it runs between every collection step and the next.
+The user only sees it if something is actually missing.
+
+## Implementation Pattern
+
+Add this block at the end of each information-collection step in wizard commands:
+
+```markdown
+**Missing-dimension check (proactive):**
+Ask internally: "What dependency is commonly required for a {type} of this kind
+that hasn't been mentioned?" If any critical dependency is missing, ask ONE follow-up.
+```
+
+### Example: fire-scaffold Step 4 (Dependencies)
+
+```markdown
+**Missing-dimension check (proactive):**
+Ask internally: "What dependency is commonly required for a {type} of this kind
+that hasn't been mentioned?" If any critical dependency is missing, ask ONE follow-up.
+```
+
+### Example: fire-1d-discuss Step 5 (Discuss Phase)
+
+```markdown
+**Step Confirmation Checkpoint:**
+After completing all questions for an area, check:
+- "Is anything missing from what the user described?"
+- "Is any dependency or constraint not yet captured?"
+If yes → ONE follow-up before advancing.
+```
+
+## Rules
+
+1. **Ask internally first** — Do not ask the user if nothing is missing. Silent gate.
+2. **ONE follow-up maximum** — Never chain missing-dimension checks. Ask the most
+   critical missing item, get the answer, then advance.
+3. **Type-specific** — The check must know the current type/context. A missing auth
+   check is critical for an API endpoint; not for a CSS utility function.
+4. **Dimension, not detail** — Check for entire missing *categories* (auth, rate-limiting,
+   database access, error handling) not missing *details* (exact field names).
+
+## Measurable Impact
+
+**Teaching LMs to Gather Information Proactively** (arXiv 2507.21389, 2025):
++18% improvement over o3-mini on proactive question quality when LLMs are explicitly
+instructed to identify missing information dimensions before asking users.
+
+**Mechanism:** Without the explicit internal check, LLMs complete collection steps
+based on what was asked, not what was needed. The self-check creates a second pass
+that catches categorical gaps.
+
+## Research Basis
+
+> **Teaching LMs to Gather Information Proactively** (arXiv 2507.21389, 2025).
+> +18% improvement over o3-mini on proactive question quality.
+> Applied: Missing-dimension check added to wizard Step 4 (Dependencies) in
+> fire-scaffold.md and Step 5 (Discuss Phase) confirmation in fire-1d-discuss.md.