@thierrynakoa/fire-flow 10.0.0

package/skills-library/methodology/SABBATH_REST_PATTERN.md

@@ -0,0 +1,267 @@
+# Sabbath Rest Pattern - AI Context Persistence
+
+> *Like humans need sleep to reset, AI agents need state files to resume after context resets.*
+
+## The Problem
+
+AI agents lose all context when:
+- Session ends or times out
+- Context window fills up and compacts
+- User closes and reopens the conversation
+- Agent crashes or errors out mid-task
+
+Without persistence, the next agent (or resumed session) starts from scratch, wasting time re-discovering context and potentially making inconsistent decisions.
+
+### Why It Was Hard
+
+- AI has no built-in memory between sessions
+- Context windows have finite limits
+- No standard pattern for what to persist
+- Easy to forget mid-task state
+
+### Impact
+
+- Hours of work lost to re-orientation
+- Inconsistent decisions across sessions
+- Repeated mistakes already solved
+- User frustration explaining same context repeatedly
+
+---
+
+## The Solution: Sabbath Rest
+
+Just as humans consolidate memory during sleep, AI agents must consolidate state to files before "sleeping" (context loss).
+
+### The Metaphor
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│ HUMAN SLEEP CYCLE                     AI SABBATH REST                       │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  Work during day                      Work during session                   │
+│       ↓                                    ↓                                │
+│  Brain consolidates to                 Agent writes to                      │
+│  long-term memory                      .local.md + CONSCIENCE.md                 │
+│       ↓                                    ↓                                │
+│  Sleep (unconscious)                   Context reset/compact                │
+│       ↓                                    ↓                                │
+│  Wake with memories intact             Resume with state files              │
+│                                                                             │
+│  Without sleep → memory loss           Without Sabbath Rest → context rot   │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Two-Layer Persistence
+
+#### Layer 1: Session State (`.claude/{plugin}.local.md`)
+
+Short-term memory for current work. Contains:
+- Current task/feature being worked on
+- Progress checkpoints
+- Resume point if interrupted
+- Temporary decisions and assumptions
+
+```markdown
+---
+last_session: 2025-01-23T14:30:00Z
+task: "Implementing user authentication"
+status: in_progress
+progress: 60%
+---
+
+# Session State
+
+## Current Work
+- Task: User authentication with JWT
+- Step: Implementing refresh tokens
+- Blocked: No (proceeding)
+
+## Progress
+- [x] Login endpoint
+- [x] Token generation
+- [ ] Refresh token logic  ← RESUME HERE
+- [ ] Logout endpoint
+
+## Decisions Made
+- Using RS256 for JWT signing (more secure)
+- 15min access token, 7day refresh token
+
+## Resume Point
+Continue from: Refresh token logic in auth.service.ts
+```
+
+#### Layer 2: Project State (`CONSCIENCE.md`)
+
+Long-term memory for project history. Contains:
+- Completed phases and milestones
+- Key decisions with rationale
+- Historical context
+- Links to detailed documentation
+
+```markdown
+## Authentication Implementation
+- **Status:** In Progress (60%)
+- **Started:** 2025-01-22
+- **Key Decisions:**
+  - RS256 signing (security requirement)
+  - Refresh token rotation enabled
+- **Session Files:** .claude/dominion-flow.local.md
+- **Last Agent:** Claude Opus 4.5, 2025-01-23
+```
+
+---
+
+## Implementation Pattern
+
+### When to Write Sabbath Rest
+
+1. **After each significant step** - Don't wait until the end
+2. **Before any risky operation** - Checkpoint before changes
+3. **When context is getting full** - Proactive save
+4. **At natural breakpoints** - End of phase/feature/task
+
+### What to Persist
+
+| Category | Examples | Where |
+|----------|----------|-------|
+| Current task | Feature name, step, progress | `.local.md` |
+| Decisions | Architectural choices, trade-offs | `CONSCIENCE.md` |
+| Blockers | What's stopping progress | `.local.md` |
+| Resume point | Exact place to continue | `.local.md` |
+| History | Completed work, timestamps | `CONSCIENCE.md` |
+| Context links | Related files, docs | Both |
+
+### Template: `.local.md` State File
+
+```markdown
+---
+# YAML frontmatter for easy parsing
+plugin: "{plugin-name}"
+last_updated: "{ISO timestamp}"
+status: "{in_progress | complete | blocked}"
+task: "{current task description}"
+---
+
+# {Plugin Name} Session State
+
+## Current Session
+- **Task:** {what you're working on}
+- **Started:** {timestamp}
+- **Status:** {in_progress | complete | blocked}
+
+## Progress Checkpoints
+- [x] Step 1: {description} - DONE
+- [x] Step 2: {description} - DONE
+- [ ] Step 3: {description} - IN PROGRESS ← CURRENT
+- [ ] Step 4: {description} - PENDING
+
+## Key Decisions This Session
+| Decision | Rationale | Alternatives Considered |
+|----------|-----------|------------------------|
+| {choice} | {why} | {what else} |
+
+## Blockers / Issues
+- {blocker description, if any}
+
+## Resume Instructions
+If this session ends, the next agent should:
+1. Read this file first
+2. Continue from: {exact step/file/line}
+3. Remember: {critical context}
+
+## Files Modified
+- `{path}` - {what changed}
+```
+
+---
+
+## Integration with Dominion Flow
+
+All Dominion Flow commands implement Sabbath Rest:
+
+| Command | State File | What's Persisted |
+|---------|------------|------------------|
+| `/fire-brainstorm` | `.claude/fire-brainstorm.local.md` | Topic, alternatives, recommendation |
+| `/fire-double-check` | `.claude/fire-double-check.local.md` | Verification results, evidence |
+| `/fire-sprint` | `.claude/fire-sprint.local.md` | Feature, iterations, tech debt |
+| `/fire-shipper` | `.claude/fire-shipper.local.md` | Version, pipeline stage, rollback info |
+| `/fire-learner` | `.claude/fire-learner.local.md` | Concepts covered, learning progress |
+| `/fire-guardian` | `.claude/fire-guardian.local.md` | Scan results, findings, fixes |
+| `/fire-iterate` | `.claude/fire-iterate.local.md` | Iteration count, completion status |
+| `/fire-debugger` | `.claude/debug-session.local.md` | Hypotheses, evidence, fix status |
+
+---
+
+## Testing the Pattern
+
+### Before (No Sabbath Rest)
+```
+Session 1: Work for 2 hours on auth
+Context resets
+Session 2: "What was I doing? Let me re-read all the files..."
+Result: 30 minutes wasted re-orienting
+```
+
+### After (With Sabbath Rest)
+```
+Session 1: Work for 2 hours on auth, write to .local.md
+Context resets
+Session 2: Read .local.md → "Continue from refresh token logic"
+Result: Resume in 2 minutes
+```
+
+---
+
+## Common Mistakes to Avoid
+
+- **Writing only at the end** - Context can reset anytime, write continuously
+- **Vague resume points** - Be specific: file, line, exact next step
+- **Forgetting decisions** - Document WHY, not just WHAT
+- **Skipping for "quick tasks"** - Even quick tasks can be interrupted
+- **Not reading state on resume** - Always check `.local.md` first
+
+---
+
+## The Philosophy
+
+```
+"Remember the Sabbath day, to keep it holy."
+
+For AI agents, the Sabbath Rest is not about worship—
+it's about the wisdom of regular, intentional pauses
+to consolidate what we've learned before we forget.
+
+Without rest, humans lose memory.
+Without Sabbath Rest, AI agents lose context.
+
+Build the rest into your workflow,
+and you'll never lose your work again.
+```
+
+---
+
+## Related Patterns
+
+- [WARRIOR Handoffs](../deployment-security/WARRIOR_HANDOFF.md) - Full session handoff
+- [CONSCIENCE.md Living Memory](./STATE_MD_PATTERN.md) - Project-level persistence
+- [Multi-Perspective Review](./MULTI_PERSPECTIVE_CODE_REVIEW.md) - Uses Sabbath Rest
+
+---
+
+## Time to Implement
+
+**Per command:** 5 minutes to add Sabbath Rest section
+**ROI:** Saves 15-30 minutes per context reset
+
+## Difficulty Level
+
+⭐ (1/5) - Simple pattern, just requires discipline
+
+---
+
+**Author Notes:**
+The name "Sabbath Rest" came from a user who observed that AI context resets are like human sleep - a necessary reset that requires preparation to preserve what's important.
+
+The key insight: **Write state continuously, not just at the end.** You never know when the Sabbath will come.

package/skills-library/methodology/STONE_AND_SCAFFOLD.md

@@ -0,0 +1,220 @@
+# Stone & Scaffold — Handoff Archival with Dormant Project Protection
+
+## The Problem
+
+Handoff files accumulate at ~2/day. Within 2 months, `warrior-handoffs/` has 100+ files. Most are scaffolding — they built the skills (stones) and now just add weight. But some are the ONLY bridge back to a dormant project the user hasn't touched in months. Blindly archiving kills the cold-start path.
+
+### Why It Was Hard
+
+- No distinction between "scaffolding from active work" and "last known state of a sleeping project"
+- Archiving by date alone misses project context — a 60-day-old handoff might be the ONLY handoff for a project
+- No index means archived handoffs are effectively invisible
+- Deleting is irreversible; moving without an index is almost as bad
+
+### Impact
+
+- 100+ files in warrior-handoffs/ slows agent orientation at session start
+- Dormant projects lose their resume bridge if archived carelessly
+- No way to distinguish "this handoff built a skill" from "this handoff IS the skill for this project"
+
+---
+
+## The Solution
+
+### The Principle
+
+> Skills are the permanent stones. Handoffs are the scaffolding that built them.
+> Once the stones are set, move the scaffolding out of the way — don't destroy it,
+> just put it where it won't clutter the workspace.
+
+### The Exception: Dormant Project Shield
+
+> **Last In From Project = First One Out At Resume.**
+>
+> For any project that hasn't been touched in 30+ days, the MOST RECENT handoff
+> stays in `warrior-handoffs/`. It's not scaffolding — it's the cold-start bridge.
+> When the user opens that project 6 months later, the agent reads this handoff
+> and knows exactly where things stand.
+
+### Frequency
+
+| Trigger | Action |
+|---------|--------|
+| `warrior-handoffs/` > 50 files | Run Stone & Scaffold |
+| Milestone completion | Archive that milestone's handoffs |
+| Monthly (natural rhythm) | Sweep for scaffolding |
+| `/fire-cleanse --poop` or `--shower` | Include as part of Colon batch dump |
+
+### The Process
+
+```
+Step 1: INVENTORY
+  List all files in warrior-handoffs/
+  Group by project (parse filename or read first 5 lines)
+
+Step 2: IDENTIFY DORMANT PROJECTS
+  For each project group:
+    - Last handoff date > 30 days ago? → DORMANT
+    - Last handoff date < 30 days ago? → ACTIVE
+
+Step 3: PROTECT DORMANT PROJECT BRIDGES
+  For each DORMANT project:
+    - Mark the MOST RECENT handoff as PROTECTED (do not archive)
+    - All older handoffs for that project → archive candidates
+
+Step 4: ARCHIVE ACTIVE PROJECT SCAFFOLDING
+  For each ACTIVE project:
+    - Skills already extracted? (check skills library for matching patterns)
+    - Keep the MOST RECENT handoff (current session bridge)
+    - All older handoffs → archive candidates
+
+Step 5: WRITE INDEX
+  Create INDEX.md in backup location:
+    - First line: backup location path
+    - One line per archived handoff (filename + one sentence)
+    - Last line: recovery instructions
+    - Group by date or project for scanability
+
+Step 6: MOVE (NOT DELETE)
+  Move archive candidates to backup location
+  Verify file counts match expectations
+  Leave protected handoffs in warrior-handoffs/
+```
+
+### Decision Matrix
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│              STONE & SCAFFOLD DECISION                        │
+├──────────────────────────────────────────────────────────────┤
+│                                                              │
+│  Is this the MOST RECENT handoff for its project?            │
+│    YES → Is the project ACTIVE (touched < 30 days)?          │
+│           YES → KEEP (current session bridge)                │
+│           NO  → KEEP + MARK AS DORMANT BRIDGE                │
+│    NO  → Have skills been extracted from this handoff?       │
+│           YES → ARCHIVE (scaffolding, stones already set)    │
+│           NO  → KEEP until skills extracted                  │
+│                                                              │
+│  Is this a non-markdown file (image, html)?                  │
+│    YES → ARCHIVE (unless referenced by a kept handoff)       │
+│                                                              │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### Backup Location
+
+```
+C:\Users\FirstName\Documents\warrior-handoff-backup\
+  INDEX.md          ← One-page summary of everything archived
+  {handoff files}   ← Moved here, intact, recoverable
+```
+
+### INDEX.md Format
+
+```markdown
+# Warrior Handoff Backup
+
+**Location:** C:\Users\FirstName\Documents\warrior-handoff-backup\
+**Moved from:** C:\Users\FirstName\.claude\warrior-handoffs\
+**Date moved:** {YYYY-MM-DD}
+**Reason:** Scaffolding archived — skills extracted, stones set.
+
+---
+
+## {Date Group}
+- FILENAME.md — One sentence about what this handoff covers
+
+---
+
+**Recovery:** Copy needed files back to C:\Users\FirstName\.claude\warrior-handoffs\
+```
+
+---
+
+## Integration with Cleansing Cycle
+
+Stone & Scaffold is the **Colon's handoff-specific batch dump**:
+
+| Cleansing Mode | Stone & Scaffold Role |
+|----------------|----------------------|
+| Pee | Not triggered (too light for file moves) |
+| Poop | Run Step 1-6 as part of Colon batch dump |
+| Shower | Full sweep — re-evaluate ALL handoffs including dormant bridges |
+
+The Spleen fitness test applies to handoffs too:
+- 4/4 (recent + referenced + project active + skills not yet extracted) → KEEP
+- 3/4 → KEEP (probably the dormant bridge)
+- 2/4 → Archive candidate
+- 0-1/4 → Archive immediately
+
+---
+
+## Example: The Dec 2025 Archive
+
+First real execution (2026-02-17):
+- **33 files archived** (26 .md + 3 images + 1 HTML + INDEX.md)
+- **Projects covered:** SSD Recovery (complete), WSL Crisis (resolved), Form 656 (skills extracted), Zadok Calendar (dormant — but had no 2026 handoffs to protect)
+- **Dormant bridges kept:** BoltBudget and LMS handoffs from Jan 2026 stayed in warrior-handoffs/ (most recent for those projects)
+- **Result:** warrior-handoffs/ went from 122 → 89 files
+
+---
+
+## Testing
+
+```markdown
+- [ ] Dormant projects have their most recent handoff PROTECTED
+- [ ] Active projects keep only the most recent handoff
+- [ ] INDEX.md has one line per archived file
+- [ ] INDEX.md first line = backup location, last line = recovery instructions
+- [ ] No files deleted — only moved
+- [ ] File counts match (archived + remaining = original total)
+- [ ] Non-markdown files archived (unless referenced by kept handoff)
+```
+
+---
+
+## Prevention
+
+- Never archive the ONLY handoff for a project — that's the dormant bridge
+- Never delete handoffs — always move to backup with an index
+- Don't archive handoffs whose skills haven't been extracted yet
+- Run the dormant project check BEFORE any archival
+- When resuming a dormant project, the agent reads the bridge handoff FGTAT
+
+---
+
+## Common Mistakes to Avoid
+
+- **Archiving by date alone** — a 6-month-old handoff might be the only bridge to a sleeping project
+- **Deleting instead of moving** — the colon absorbs before it eliminates; the backup is the absorption
+- **No index** — archived handoffs without an index are effectively lost
+- **Archiving too early** — if skills haven't been extracted yet, the handoff IS the skill
+- **Forgetting non-markdown files** — images and HTML referenced by handoffs should travel with them
+
+---
+
+## Related Patterns
+
+- [CLEANSING_CYCLE](./CLEANSING_CYCLE.md) — Colon batch dump triggers this protocol
+- [PORTAL_MEMORY_ARCHITECTURE](./PORTAL_MEMORY_ARCHITECTURE.md) — Revisitation Ladder: 1x=handoff, 5x+=skill
+- [GLOMERULUS_DECISION_GATE](./GLOMERULUS_DECISION_GATE.md) — 3-layer filter applies to handoff triage
+
+---
+
+## Resources
+
+- Revisitation Ladder: Handoffs are 1x use (read, extract, archive). Skills are 5x+ (permanent stones).
+- Thierry's insight: "The skills are what truly matter — that's what the handoffs built."
+- Thierry's insight: "Last in from project, first one out at resume" — dormant bridge principle.
+- Biological analog: Colon absorbs nutrients (skills) from food (handoffs), then eliminates the bulk.
+
+---
+
+## Time to Implement
+
+**2-5 minutes** per archival sweep
+
+## Difficulty Level
+
+⭐⭐ (2/5) — Simple file operations. The nuance is in the dormant project detection.

package/skills-library/performance/cache-augmented-generation.md

@@ -0,0 +1,172 @@
+---
+name: cache-augmented-generation
+category: performance
+version: 1.0.0
+contributed: 2026-03-01
+contributor: dominion-flow
+last_updated: 2026-03-01
+contributors:
+  - dominion-flow
+tags: [caching, llm, rag-alternative, prompt-caching, anthropic, context-window, performance]
+difficulty: medium
+usage_count: 0
+success_rate: 100
+---
+
+# Cache Augmented Generation (CAG)
+
+## Problem
+
+RAG (Retrieval Augmented Generation) adds latency and complexity: embedding queries, vector search, re-ranking, then injecting chunks. For **small, stable document sets** that change infrequently, this retrieval overhead is unnecessary. The documents fit in the context window, and paying for retrieval infrastructure (Qdrant, embeddings, chunking pipeline) is architectural overkill.
+
+Common symptoms that CAG is a better fit:
+- Corpus is <100K tokens and changes less than weekly
+- RAG retrieval adds 200-500ms latency per query
+- Chunk boundary issues cause incomplete answers
+- Users ask about the SAME reference material repeatedly
+- You're maintaining embedding + vector DB infrastructure for a small, static corpus
+
+## Solution Pattern
+
+**Pre-load the entire document corpus into the prompt prefix and cache it.** Instead of retrieving relevant chunks at query time (RAG), load ALL relevant documents into a cached system prompt. The LLM sees everything and selects what's relevant — no retrieval pipeline needed.
+
+This works because:
+1. Modern context windows (200K tokens) can hold substantial corpora
+2. Anthropic's prompt caching stores the prefix server-side (90% cost reduction on cache hits)
+3. LLMs are good at finding relevant information within their context — often better than chunked retrieval
+
+### Architecture Comparison
+
+```
+RAG Pipeline:
+  Query → Embed → Vector Search → Rerank → Inject Chunks → LLM → Response
+  Latency: 500-1500ms | Infrastructure: Embedding model + Vector DB + Chunking pipeline
+
+CAG Pipeline:
+  Query → [Cached Prefix: All Docs] + Query → LLM → Response
+  Latency: 100-300ms | Infrastructure: None (prompt caching is built-in)
+```
+
+## Code Example
+
+### Anthropic Prompt Caching (Python)
+
+```python
+import anthropic
+
+# Load your stable corpus once
+def load_corpus():
+    """Load all reference documents into a single string."""
+    docs = []
+    for path in REFERENCE_DIR.glob("*.md"):
+        docs.append(f"## {path.stem}\n\n{path.read_text()}")
+    return "\n\n---\n\n".join(docs)
+
+CORPUS = load_corpus()  # Load once at startup
+
+client = anthropic.Anthropic()
+
+def query_with_cag(user_question: str) -> str:
+    """Query against the full cached corpus."""
+    response = client.messages.create(
+        model="claude-sonnet-4-20250514",
+        max_tokens=4096,
+        system=[
+            {
+                "type": "text",
+                "text": f"You are an expert assistant. Answer questions using ONLY the reference material below.\n\n{CORPUS}",
+                "cache_control": {"type": "ephemeral"}  # Cache this prefix
+            }
+        ],
+        messages=[{"role": "user", "content": user_question}]
+    )
+    return response.content[0].text
+```
+
+### Anthropic Prompt Caching (TypeScript/Node.js)
+
+```typescript
+import Anthropic from '@anthropic-ai/sdk';
+
+const client = new Anthropic();
+
+// Load corpus once at startup
+const CORPUS = loadAllDocs();  // Returns concatenated document text
+
+async function queryWithCAG(question: string): Promise<string> {
+  const response = await client.messages.create({
+    model: 'claude-sonnet-4-20250514',
+    max_tokens: 4096,
+    system: [
+      {
+        type: 'text',
+        text: `You are an expert assistant. Answer using ONLY the reference material below.\n\n${CORPUS}`,
+        cache_control: { type: 'ephemeral' },
+      },
+    ],
+    messages: [{ role: 'user', content: question }],
+  });
+  return response.content[0].type === 'text' ? response.content[0].text : '';
+}
+```
+
+### Cache Invalidation
+
+```typescript
+// Simple: Reload corpus on file change (fs.watch or chokidar)
+import { watch } from 'chokidar';
+
+let corpus = loadAllDocs();
+
+watch(REFERENCE_DIR, { ignoreInitial: true }).on('change', () => {
+  corpus = loadAllDocs();
+  console.log('CAG corpus reloaded — next request uses fresh cache');
+});
+```
+
+## Implementation Steps
+
+1. Inventory your document corpus — count tokens (use `tiktoken` or Anthropic's token counter)
+2. If corpus < 100K tokens AND changes infrequently, CAG is viable
+3. Concatenate all documents into a single system prompt string with clear section markers
+4. Add `cache_control: { type: "ephemeral" }` to the system message
+5. Remove RAG infrastructure (embedding, vector DB, chunking) if CAG covers the entire use case
+6. Add file watcher for cache invalidation if documents can change
+
+## When to Use
+
+- Reference material is small (<100K tokens) and stable (changes < weekly)
+- Users repeatedly query the SAME document set
+- RAG retrieval latency is a pain point
+- Chunk boundary issues cause incomplete or fragmented answers
+- You want to eliminate embedding/vector DB infrastructure for a specific use case
+- Bible corpus, legal documents, company policies, API specs, style guides
+
+## When NOT to Use
+
+- Corpus exceeds context window limits (>150K tokens for safety margin)
+- Documents change frequently (hourly/daily) — cache invalidation overhead negates benefits
+- You need to search across millions of documents (RAG scales, CAG doesn't)
+- Queries need to combine information from different document versions
+- Cost is the primary concern and queries are infrequent (cached prefix has per-session cost)
+- You need metadata filtering (by date, author, category) — RAG handles this naturally
+
+## Common Mistakes
+
+- Pre-loading a corpus that's too large — causes context window pressure and degrades answer quality
+- Forgetting cache invalidation — stale cached responses return outdated information
+- Caching with high temperature — non-deterministic outputs make cached patterns unreliable
+- Not measuring token count — "small" corpora can be surprisingly large when fully loaded
+- Mixing CAG and RAG without clear boundaries — pick one per document set
+- Ignoring the 5-minute cache TTL on Anthropic — frequent cold starts negate cost savings
+
+## Related Skills
+
+- [AI_RESPONSE_DATABASE_CACHING](../database-solutions/AI_RESPONSE_DATABASE_CACHING.md) - Response-level caching for expensive LLM calls
+- [persistent-analysis-storage](../database-solutions/persistent-analysis-storage.md) - Dual-storage for expensive analysis results
+
+## References
+
+- Anthropic Prompt Caching: https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
+- CAG concept derived from AITMPL prompt-caching skill analysis (2026-03-01)
+- Contributed from: dominion-flow gap analysis (AITMPL audit session)