@thierrynakoa/fire-flow 12.2.2 → 13.0.1

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

@@ -0,0 +1,181 @@
+# Agent SDK Standalone Tooling
+
+> Build a standalone review/orchestration server using the Anthropic Claude Agent SDK for programmatic multi-agent workflows outside Claude Code sessions.
+
+**When to use:** Building CI/CD review pipelines, automated code review servers, or standalone orchestration tools that need to programmatically spawn Claude agents.
+**Stack:** TypeScript/Node.js, @anthropic-ai/claude-agent-sdk
+
+---
+
+## When to Use SDK vs Subagents vs CLI
+
+| Approach | Use Case | Complexity |
+|----------|----------|------------|
+| `.claude/agents/` subagent files | In-session review, ad-hoc tasks | Low |
+| `claude -p` CLI spawning | CI/CD, cron jobs, fire-and-forget | Low |
+| Agent SDK | Standalone servers, custom orchestration, multi-agent pipelines | High |
+
+**Use SDK when:** You need a persistent service that programmatically spawns, monitors, and coordinates agents independent of any Claude Code session.
+
+---
+
+## Installation
+
+```bash
+npm install @anthropic-ai/claude-agent-sdk
+```
+
+---
+
+## Basic Usage: Single Agent Query
+
+```typescript
+import { query } from "@anthropic-ai/claude-agent-sdk";
+
+async function reviewCode(directory: string): Promise<string> {
+  let result = '';
+
+  for await (const message of query({
+    prompt: `Review all files in ${directory} for bugs and security issues.`,
+    options: {
+      model: "sonnet",
+      allowedTools: ["Read", "Glob", "Grep"],
+      permissionMode: "bypassPermissions",
+      maxTurns: 50,
+    }
+  })) {
+    if (message.type === "assistant" && message.content) {
+      for (const block of message.content) {
+        if (block.type === "text") {
+          result += block.text;
+        }
+      }
+    }
+  }
+
+  return result;
+}
+```
+
+---
+
+## Multi-Agent Review Pipeline
+
+```typescript
+import { query, AgentDefinition } from "@anthropic-ai/claude-agent-sdk";
+
+// Define specialized reviewer agents inline
+const reviewerAgents: Record<string, AgentDefinition> = {
+  "security-reviewer": {
+    description: "Finds security vulnerabilities",
+    prompt: "You are a security expert. Find vulnerabilities in the code.",
+    tools: ["Read", "Grep", "Glob"],
+    model: "sonnet",
+  },
+  "quality-reviewer": {
+    description: "Finds code quality issues",
+    prompt: "You are a code quality expert. Find issues in the code.",
+    tools: ["Read", "Grep", "Glob"],
+    model: "haiku",
+  },
+};
+
+async function runParallelReview(directory: string) {
+  // Launch both reviewers in parallel using Promise.all
+  const reviewPromises = Object.entries(reviewerAgents).map(
+    async ([name, agent]) => {
+      let output = '';
+      for await (const msg of query({
+        prompt: `Use the ${name} agent to review code in ${directory}.`,
+        options: {
+          model: "opus",
+          agents: { [name]: agent },
+          allowedTools: ["Read", "Glob", "Grep", "Task"],
+          permissionMode: "bypassPermissions",
+          maxTurns: 100,
+        }
+      })) {
+        if (msg.type === "assistant") {
+          for (const block of msg.content || []) {
+            if (block.type === "text") output += block.text;
+          }
+        }
+      }
+      return { name, output };
+    }
+  );
+
+  return Promise.all(reviewPromises);
+}
+```
+
+---
+
+## CI/CD Integration Pattern
+
+```typescript
+// ci-review.ts — Run as a GitHub Action step
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import { execSync } from "node:child_process";
+
+async function ciReview() {
+  // Get the diff safely
+  const diffOutput = execSync(
+    'git diff origin/main...HEAD',
+    { encoding: 'utf-8', maxBuffer: 1024 * 1024 }
+  );
+
+  let verdict = '';
+  for await (const msg of query({
+    prompt: `Review this git diff for bugs and security issues.
+Return JSON: {verdict: "APPROVE"|"BLOCK", issues: [{severity, description}]}
+
+Diff:
+${diffOutput.slice(0, 50000)}`,
+    options: {
+      model: "sonnet",
+      maxTurns: 20,
+      permissionMode: "bypassPermissions",
+    }
+  })) {
+    if (msg.type === "result") {
+      verdict = msg.content
+        ?.map(b => b.type === 'text' ? b.text : '')
+        .join('') || '';
+    }
+  }
+
+  const jsonMatch = verdict.match(/\{[\s\S]*"verdict"[\s\S]*\}/);
+  if (jsonMatch) {
+    const parsed = JSON.parse(jsonMatch[0]);
+    if (parsed.verdict === 'BLOCK') {
+      console.error('Review BLOCKED:', parsed.issues);
+      process.exit(1);
+    }
+  }
+
+  console.log('Review APPROVED');
+  process.exit(0);
+}
+
+ciReview();
+```
+
+---
+
+## Key Considerations
+
+- **API key management:** Use `ANTHROPIC_API_KEY` environment variable
+- **Cost:** Each agent invocation costs full API tokens — use cheaper models for routine reviews
+- **Streaming:** Use `for await` to process streaming responses
+- **Error handling:** Wrap in try/catch — agent failures should not crash the CI pipeline
+- **Timeout:** Set `maxTurns` to prevent runaway agents
+- **Security:** Use `execSync` with explicit args, not string interpolation with user input
+
+---
+
+## Sources
+
+- Anthropic Agent SDK: TypeScript reference (2026)
+- npm: @anthropic-ai/claude-agent-sdk (1.85M+ weekly downloads)
+- Anthropic: "How we built our multi-agent research system" (2026)

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

@@ -0,0 +1,169 @@
+# Agent Teams Guide — Multi-Reviewer Coordination
+
+> Use Claude Code's experimental Agent Teams feature to spawn competing reviewers that discuss findings with each other.
+
+**When to use:** When you want deeper code review than a single reviewer provides — especially for security-critical, performance-sensitive, or architecturally complex changes.
+**Prerequisites:** Claude Code v2.0.64+ with experimental teams flag enabled
+
+---
+
+## Setup
+
+Enable the experimental feature flag:
+
+```json
+// ~/.claude/settings.json
+{
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  }
+}
+```
+
+This unlocks these tools in Claude Code:
+- `TeamCreate` — spawn a teammate agent
+- `TaskCreate` — create tasks with dependencies
+- `TaskUpdate` — update task status
+- `TaskList` — view all tasks
+- `SendMessage` — inbox-based inter-agent messaging
+
+---
+
+## Pattern 1: Competing Reviewers
+
+Spawn specialized reviewers that challenge each other's findings:
+
+```
+Create three reviewer teammates:
+
+Teammate 1: "security-reviewer"
+  Focus: Authentication bypass, injection attacks, secret exposure, CSRF,
+         input validation, authorization checks
+  Tools: Read, Grep, Glob (read-only)
+
+Teammate 2: "performance-reviewer"
+  Focus: N+1 queries, missing indexes, unnecessary re-renders, memory leaks,
+         bundle size impact, caching opportunities
+  Tools: Read, Grep, Glob, Bash (for running benchmarks)
+
+Teammate 3: "architecture-reviewer"
+  Focus: Coupling, dependency direction, abstraction levels, API design,
+         separation of concerns, DRY violations
+  Tools: Read, Grep, Glob
+
+Each reviews the files in [phase directory].
+When done, each sends their verdict to the lead via SendMessage.
+```
+
+### Anti-Conformity (FREE-MAD Pattern)
+
+To prevent reviewers from rubber-stamping each other, include in each teammate's prompt:
+
+```
+IMPORTANT: You are an INDEPENDENT reviewer. If you disagree with another
+reviewer's findings, SAY SO and explain why. Your job is to find issues
+the others missed, not to agree with them.
+
+After completing your review, read other reviewers' findings via inbox.
+If you agree: acknowledge and move on.
+If you disagree: send a rebuttal message explaining your reasoning.
+The lead will synthesize all perspectives.
+```
+
+---
+
+## Pattern 2: Research Swarm
+
+Spawn parallel researchers for `/fire-research`:
+
+```
+Create four researcher teammates:
+
+Teammate 1: "academic-researcher"
+  Task: Search arXiv, ACL, NeurIPS for papers on [topic]
+
+Teammate 2: "community-researcher"
+  Task: Search blogs, GitHub, docs from AI coding tools
+
+Teammate 3: "gap-analyst"
+  Task: Read internal workflow files, find gaps
+
+Teammate 4: "failure-miner"
+  Task: Search past handoffs for recurring failures
+
+When all complete, lead synthesizes findings.
+```
+
+---
+
+## Pattern 3: Parallel Executors
+
+For large phases with independent plans:
+
+```
+Create executor teammates (one per plan):
+
+Teammate 1: "backend-executor" — Plan 03-01 (API endpoints)
+Teammate 2: "frontend-executor" — Plan 03-02 (UI components)
+Teammate 3: "test-executor" — Plan 03-03 (test suite)
+
+Dependencies:
+  - test-executor waits for backend-executor AND frontend-executor
+  - backend and frontend run in parallel
+
+Each works in its own git worktree (isolation: worktree).
+```
+
+---
+
+## Verdict Synthesis (Lead Agent)
+
+After all teammates return:
+
+```
+1. Collect all verdicts from inbox messages
+2. Parse structured verdict envelopes (REVIEWER_VERDICT_START/END)
+3. Aggregate:
+   - UNANIMOUS APPROVE → APPROVE
+   - ANY BLOCK → BLOCK (with specific findings)
+   - MIXED → APPROVE_WITH_FIXES (merge all issues)
+4. Deduplicate findings (same file:line from multiple reviewers = higher confidence)
+5. Resolve conflicts (reviewer A says "add abstraction", B says "keep simple"):
+   - Apply the simpler solution unless the complex one has measurable benefit
+6. Present consolidated verdict
+```
+
+---
+
+## Cost Considerations
+
+| Mode | Cost | Quality | Speed |
+|------|------|---------|-------|
+| Single reviewer (current) | 1x | Good | Fast |
+| 3 specialized reviewers | 3x | Better (catches more) | Same (parallel) |
+| 3 reviewers + debate | 4-5x | Best (challenges findings) | Slower |
+
+**Recommendation:** Use single reviewer for routine changes. Use teams for:
+- Security-critical code (payment, auth, data handling)
+- Architectural decisions (new patterns, major refactors)
+- Production deployment gates
+
+---
+
+## Limitations (Experimental)
+
+- API may change — teams feature is in research preview
+- Requires tmux for terminal multiplexing on some platforms
+- Token cost scales linearly with teammate count
+- Teammates share a task list but NOT context (each has fresh window)
+- Windows support may require WSL for tmux
+
+---
+
+## Sources
+
+- Claude Code Docs: "Orchestrate teams of Claude Code sessions" (2026)
+- Anthropic: "How we built our multi-agent research system" (2026)
+- FREE-MAD paper: Anti-conformity debate (+13-16.5% reasoning accuracy)
+- ccswarm (nwiizo, GitHub): Multi-agent orchestration in Rust
+- claudefa.st: "Claude Code Agent Teams: The Complete Guide 2026"

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

@@ -0,0 +1,207 @@
+---
+name: ALAS Stateful Execution
+category: methodology
+version: 1.0.0
+contributed: 2026-03-08
+contributor: fire-research
+last_updated: 2026-03-08
+tags: [multi-agent, token-reduction, checkpoint, state-management, failure-recovery]
+difficulty: medium
+---
+
+# ALAS Stateful Execution — Checkpoint/Restore for Token-Efficient Agent Coordination
+
+> and SagaLLM: Transaction Guarantees for Multi-Agent (VLDB 2025, arXiv 2503.11951).
+> Results: 60% token reduction, 1.82x speed improvement, 83.7% task success on benchmarks.
+
+## Problem
+
+Current agent execution re-injects full context (BLUEPRINT, CONSCIENCE, skills, episodic recall) into every agent spawn and every retry. When an agent fails and restarts, it receives the entire context again — even though 90% of it hasn't changed. This wastes tokens and degrades reasoning depth as context windows fill with repeated information.
+
+Additionally, when a subtask fails, the entire pipeline restarts from scratch rather than repairing only the broken piece.
+
+## Solution Pattern
+
+### Three-Layer Architecture
+
+```
+Layer 1: EXECUTION LOG (versioned, append-only)
+  - Every agent action logged with checkpoint ID
+  - Restore point = any checkpoint in the log
+  - Failed subtask = replay from last valid checkpoint
+
+Layer 2: CONTEXT SLICING (per-agent minimal context)
+  - Each agent receives ONLY the context slice it needs
+  - Shared context referenced by ID, not copied in full
+  - Agent returns a 1-2K token summary, not full transcript
+
+Layer 3: LOCALIZED REPAIR (fix subtask, not pipeline)
+  - On failure: identify the minimal broken subtask
+  - Spawn repair agent with ONLY the failed task's context
+  - Validate repair, then resume from checkpoint
+  - Never re-run successful subtasks
+```
+
+### Execution Log Format
+
+```json
+{
+  "session_id": "fire-execute-phase-3",
+  "checkpoints": [
+    {
+      "id": "cp-001",
+      "task": "03-01-task-1",
+      "status": "completed",
+      "files_changed": ["src/auth/middleware.ts"],
+      "summary": "Added JWT validation middleware with 15-min expiry",
+      "confidence": 85,
+      "timestamp": "2026-03-08T10:30:00Z"
+    },
+    {
+      "id": "cp-002",
+      "task": "03-01-task-2",
+      "status": "failed",
+      "error_type": "LOGIC",
+      "error": "Refresh token rotation creates duplicate sessions",
+      "files_changed": ["src/auth/refresh.ts"],
+      "last_valid_checkpoint": "cp-001",
+      "timestamp": "2026-03-08T10:35:00Z"
+    }
+  ]
+}
+```
+
+### Context Slicing Rules
+
+**BEFORE (wasteful — current pattern):**
+```
+Agent spawn context = FULL BLUEPRINT (2K tokens)
+  + FULL CONSCIENCE.md (1K tokens)
+  + ALL skills_to_apply (3-5K tokens)
+  + Episodic recall results (1-2K tokens)
+  + Full playbook (500 tokens)
+  = 8-10K tokens per agent, EVERY spawn
+```
+
+**AFTER (ALAS pattern — minimal slicing):**
+```
+Agent spawn context = TASK SLICE ONLY:
+  - Task description + done criteria (200-400 tokens)
+  - Relevant file paths (50-100 tokens)
+  - Context pointer: "Read BLUEPRINT section 3.2 if needed" (30 tokens)
+  - Last checkpoint summary (100-200 tokens)
+  - Playbook (rolling 5 entries, 200-300 tokens)
+  = 600-1000 tokens per agent
+
+Full context available ON DEMAND — agent reads files only when needed,
+not pre-injected into every spawn.
+```
+
+**Token savings: ~80% per agent spawn. Across a 5-agent breath: 40-50K tokens saved.**
+
+### Localized Repair Protocol
+
+```
+ON FAILURE at checkpoint cp-N:
+  1. Read execution log → find last_valid_checkpoint (cp-N-1)
+  2. Classify failure type (from circuit breaker Step 3.5.2):
+     - TRANSIENT → retry same task with same context slice
+     - FIXATION → retry with DIFFERENT approach hint from FAILURES.md
+     - LOGIC → spawn repair agent with:
+         - Failed task description
+         - Error message
+         - Files changed since last valid checkpoint
+         - git diff from cp-N-1 to cp-N (shows exactly what broke)
+     - ARCHITECTURE → escalate to planner (not fixable locally)
+  3. Repair agent returns:
+     - Fixed files
+     - 1-2 sentence summary
+     - New checkpoint entry
+  4. Validate: run task's done criteria tests
+  5. IF pass: update checkpoint status to "repaired", continue
+  6. IF fail: escalate (max 2 repair attempts per checkpoint)
+
+NEVER re-run completed checkpoints. They stay valid.
+```
+
+### Agent Return Protocol (Summary-Only)
+
+```
+When a sub-agent completes (success or failure), it returns ONLY:
+
+{
+  "status": "completed | failed | blocked",
+  "summary": "1-2 sentences of what was done",        // MAX 200 tokens
+  "files_changed": ["path/to/file.ts"],                // list only
+  "next_agent_needs": "Brief note for downstream",     // MAX 100 tokens
+  "checkpoint_id": "cp-003"
+}
+
+The orchestrator reads this summary — NOT the agent's full transcript.
+Full transcript is available in the execution log if needed for debugging.
+```
+
+## Implementation in Dominion Flow
+
+### Where It Plugs In
+
+| Component | Change |
+|-----------|--------|
+| `fire-executor.md` Step 1 | Replace full context injection with context slice |
+| `fire-executor.md` Step 3 | Write checkpoint after each task |
+| `fire-executor.md` Step 3.5 | On circuit breaker trip → localized repair, not full restart |
+| `fire-executor.md` Step 5 | Checkpoints replace verbose handoff sections |
+| `fire-3-execute.md` Step 3.6 | Agent spawning uses minimal context slices |
+| `fire-3-execute.md` Step 4 | Breath completion reads summaries, not full transcripts |
+| `fire-autonomous.md` | Phase transitions use checkpoint logs for state transfer |
+
+### Execution Log Location
+
+```
+.planning/phases/{N}-{name}/execution-log.json
+```
+
+Written by the orchestrator. Each executor agent appends its checkpoint.
+Verifier reads the log to know what was done without re-reading all code.
+
+## When to Use
+
+- Multi-task execution with 3+ tasks per phase
+- Parallel agent spawning (SUBAGENT/SWARM modes)
+- Long-running autonomous sessions (fire-autonomous)
+- Any retry/repair scenario where full restart is wasteful
+
+## When NOT to Use
+
+- Single-task phases (overhead > savings)
+- First task in a phase (no checkpoint to restore from)
+- Tasks where the entire context truly is needed (rare — architecture decisions)
+
+## Must Do
+
+- Write checkpoint AFTER each successful task commit
+- Use context slices, not full BLUEPRINT injection for sub-agents
+- Return summaries (200 tokens max), not transcripts
+- Repair locally before restarting globally
+- Track token savings in execution log for metrics
+
+## Must Not Do
+
+- Do not skip checkpoints to "save time" — they ARE the savings
+- Do not inject full context "just in case" — agents read on demand
+- Do not retry more than 2x at the same checkpoint — escalate
+- Do not re-run completed checkpoints on failure downstream
+
+## Related Skills
+
+- [CIRCUIT_BREAKER_INTELLIGENCE](./CIRCUIT_BREAKER_INTELLIGENCE.md) — stuck-state classification feeds repair routing
+- [CONTEXT_ROTATION](./CONTEXT_ROTATION.md) — fresh-eyes pattern for FIXATION-type failures
+- [AUTONOMOUS_ORCHESTRATION](./AUTONOMOUS_ORCHESTRATION.md) — phase-level orchestration uses checkpoint logs
+
+## References
+
+- ALAS: Stateful Multi-LLM Agent Framework — [arXiv 2505.12501](https://arxiv.org/abs/2505.12501)
+- ALAS Transactional Update — [arXiv 2511.03094](https://arxiv.org/abs/2511.03094)
+- SagaLLM: Context Management and Transaction Guarantees — [VLDB 2025](https://www.vldb.org/pvldb/vol18/p4874-chang.pdf)
+- Anthropic: Effective Context Engineering — [anthropic.com/engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)
+- JetBrains Research: Efficient Context Management — [blog.jetbrains.com](https://blog.jetbrains.com/research/2025/12/efficient-context-management/)