@thierrynakoa/fire-flow 10.0.0

package/commands/fire-learncoding.md

@@ -0,0 +1,242 @@
+---
+description: Linear code walkthrough learning mode — transforms any repo into a step-by-step learning experience. Based on Simon Willison's Agentic Engineering Patterns.
+argument-hint: "[on|off|--from-github URL|--from-path PATH] [--watch|--active] [--step N]"
+---
+
+# /fire-learncoding
+
+> Turn any codebase into a linear learning walkthrough. Anti-vibe-coding. Anti-cognitive-debt.
+> Grounded in Simon Willison's Agentic Engineering Patterns (simonwillison.net/guides/agentic-engineering-patterns/)
+
+---
+
+## The Philosophy
+
+> "If you don't understand the code, your only recourse is to ask AI to fix it for you —
+> like paying off credit card debt with another credit card." — Simon Willison
+
+This mode prevents cognitive debt by walking through every file from the entry point outward,
+explaining WHAT each piece does, WHY it's written that way, and WHICH pattern it uses.
+Real code is extracted via shell tools (grep, cat, sed) — never paraphrased from memory.
+
+---
+
+## Arguments
+
+```yaml
+arguments:
+  action:
+    required: false
+    type: string
+    options: [on, off, --from-github, --from-path]
+    description: "Toggle mode or load source"
+
+  --from-github:
+    type: string
+    description: "GitHub repo URL to learn from"
+    example: "/fire-learncoding --from-github https://github.com/user/repo"
+
+  --from-path:
+    type: string
+    description: "Local path to learn from"
+    example: "/fire-learncoding --from-path ./src"
+
+  --watch:
+    type: boolean
+    default: true
+    description: "Mode 1: Agent explains + scaffolds. You read and say 'next'."
+
+  --active:
+    type: boolean
+    default: false
+    description: "Mode 2: Agent explains purpose, you write the key logic."
+
+  --step:
+    type: integer
+    description: "Jump to a specific step (resume)"
+    example: "/fire-learncoding --step 5"
+
+  --entry:
+    type: string
+    description: "Override entry point detection"
+    example: "/fire-learncoding --entry src/server.ts"
+```
+
+---
+
+## Mode Reference
+
+| Mode | Flag | You do | Agent does |
+|------|------|--------|------------|
+| Watch | `--watch` (default) | Read + say "next" | Explains, scaffolds file |
+| Active | `--active` | Write key logic sections | Explains purpose, marks `// WRITE THIS:` |
+| Hybrid | `--hybrid` (future) | Fill in business logic TODOs | Scaffolds all boilerplate |
+
+---
+
+## Process
+
+### Step 0: Load/Check Mode State
+
+```bash
+# Read mode config
+MODE_FILE=".planning/learncoding.rc"
+STEP_FILE=".planning/learncoding-progress.json"
+```
+
+**If `on` argument:**
+```bash
+mkdir -p .planning
+echo 'LEARNCODING_MODE=watch' > .planning/learncoding.rc
+echo "✓ Learncoding mode ON (--watch). Use /fire-learncoding --from-github URL to start."
+exit 0
+```
+
+**If `off` argument:**
+```bash
+rm -f .planning/learncoding.rc .planning/learncoding-progress.json
+echo "✓ Learncoding mode OFF."
+exit 0
+```
+
+**If `--active` flag:**
+```bash
+echo 'LEARNCODING_MODE=active' > .planning/learncoding.rc
+```
+
+**Resume check:** If `.planning/learncoding-progress.json` exists and has `currentStep < totalSteps`:
+
+```
+📖 Learncoding session found — Step [N] of [M]
+   Source: [repo/path]
+   Mode: [watch|active]
+
+→ Type "resume" to continue from Step N
+→ Type "restart" to start from Step 1
+```
+
+### Step 1: Load Source
+
+**If `--from-github <url>`:**
+
+```bash
+# Extract owner/repo from URL
+REPO=$(echo "$URL" | sed 's|https://github.com/||')
+# e.g. "simonw/datasette"
+
+# Fetch file tree using gh CLI
+gh api repos/$REPO/git/trees/HEAD?recursive=1 \
+  --jq '.tree[] | select(.type=="blob") | .path' \
+  > .planning/learncoding-files.txt
+
+# Fetch key files content as needed per step using:
+# gh api repos/$REPO/contents/{path} --jq '.content' | base64 -d
+```
+
+**If `--from-path <path>`:**
+```bash
+find "$PATH" -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.rs" \) \
+  | grep -v node_modules | grep -v __pycache__ | grep -v .git \
+  > .planning/learncoding-files.txt
+```
+
+Display:
+```
+📦 Source loaded: [repo or path]
+   Files found: [N]
+   Detecting entry point...
+```
+
+### Step 2: Detect Entry Point
+
+Spawn `fire-learncoding-walker` agent with the file list.
+
+Walker returns:
+```json
+{
+  "entryPoint": "src/index.ts",
+  "steps": [
+    { "order": 1, "file": "src/index.ts", "role": "Application entry", "imports": ["src/app.ts", "src/config.ts"] },
+    { "order": 2, "file": "src/config.ts", "role": "Configuration loader", "imports": [] },
+    { "order": 3, "file": "src/app.ts", "role": "Express app setup", "imports": ["src/routes/index.ts"] }
+  ],
+  "totalSteps": 12
+}
+```
+
+Write to `.planning/learncoding-plan.json`.
+
+Display learning plan:
+```
+╔══════════════════════════════════════════════════════════════╗
+║            LEARNCODING — LEARNING PLAN                       ║
+║  Source: [repo/path]        Mode: [watch|active]             ║
+╠══════════════════════════════════════════════════════════════╣
+║  Entry point: src/index.ts                                   ║
+║  Total steps: 12                                             ║
+╠══════════════════════════════════════════════════════════════╣
+║  Step  1: src/index.ts        — Application entry            ║
+║  Step  2: src/config.ts       — Configuration loader         ║
+║  Step  3: src/app.ts          — Express app setup            ║
+║  Step  4: src/routes/index.ts — Route registry               ║
+║  ...                                                         ║
+╚══════════════════════════════════════════════════════════════╝
+
+Ready to start?
+→ Type "start" to begin Step 1
+→ Type "start --step N" to jump to a specific step
+```
+
+### Step 3: Run the Step Loop
+
+For each step N from current position to totalSteps:
+
+**Update progress:**
+```json
+{ "currentStep": N, "totalSteps": 12, "mode": "watch", "source": "..." }
+```
+Write to `.planning/learncoding-progress.json`.
+
+**Spawn `fire-learncoding-explainer`** with:
+- `step`: current step object (file path, role, order)
+- `mode`: watch | active
+- `source`: github repo or local path
+- `totalSteps`: for breadcrumb display
+
+**Wait for explainer to complete.**
+
+**Read user input:**
+- `next` / `n` / `continue` → advance to step N+1
+- `explain more` / `more` → re-spawn explainer with `--deep` flag for deeper dive
+- `why` → re-spawn explainer with `--why` flag for architectural reasoning
+- `skip` → advance without scaffolding (mark as skipped in progress)
+- `exit` / `done` → save progress, exit mode
+
+**If mode is `--active`:** Wait for user to paste their code before accepting "next".
+
+### Step 4: Completion
+
+When all steps complete:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║            LEARNCODING — WALKTHROUGH COMPLETE                ║
+╠══════════════════════════════════════════════════════════════╣
+║  Files walked:  [N]                                          ║
+║  Files written: [N]                                          ║
+║  Patterns seen: [list of patterns encountered]               ║
+║                                                              ║
+║  Your code is in: [output directory]                         ║
+║                                                              ║
+║  What you built:                                             ║
+║    "[one sentence summary of what was learned]"              ║
+║                                                              ║
+║  Recommended next steps:                                     ║
+║    1. Run the tests: [test command]                          ║
+║    2. Start the app: [start command]                         ║
+║    3. Read: simonwillison.net/guides/agentic-engineering-patterns/ ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+Save walkthrough document to `.planning/learncoding-walkthrough.md` —
+a full record of all steps, snippets, and explanations (reference for later).

package/commands/fire-loop-resume.md

@@ -0,0 +1,272 @@
+---
+description: Resume a Power Loop from Sabbath Rest or stopped state
+argument-hint: "[LOOP_ID]"
+---
+
+# /fire-loop-resume
+
+> Resume Power Loop from Sabbath Rest snapshot with full context restoration
+
+---
+
+## Purpose
+
+Resume a Power Loop that was:
+- Paused due to Sabbath Rest (context rot warning)
+- Stopped by user via `/fire-loop-stop`
+- Interrupted by session end
+
+This command restores context from the Sabbath Rest snapshot and continues the loop with fresh context.
+
+---
+
+## Arguments
+
+```yaml
+arguments:
+  loop_id:
+    required: false
+    type: string
+    description: "Loop ID to resume (omit to resume most recent)"
+    example: "/fire-loop-resume 20260123-143052"
+```
+
+---
+
+## Process
+
+### Step 1: Find Loop to Resume
+
+**If LOOP_ID provided:**
+```bash
+SABBATH_FILE=$(ls .planning/loops/sabbath-${LOOP_ID}*.md 2>/dev/null | head -1)
+```
+
+**If no LOOP_ID (resume most recent):**
+```bash
+# Check Sabbath Rest state first
+if [ -f ".claude/dominion-flow.local.md" ]; then
+  LOOP_ID=$(grep "Loop ID:" .claude/dominion-flow.local.md | head -1 | cut -d: -f2 | xargs)
+fi
+
+# Or find most recent sabbath file
+SABBATH_FILE=$(ls -t .planning/loops/sabbath-*.md 2>/dev/null | head -1)
+```
+
+### Step 2: Validate Sabbath File Exists
+
+```bash
+if [ ! -f "$SABBATH_FILE" ]; then
+  echo "No Sabbath Rest snapshot found for loop ${LOOP_ID}"
+  echo "Available loops:"
+  ls .planning/loops/*.md
+  exit 1
+fi
+```
+
+### Step 3: Load Sabbath Rest Context
+
+Read the Sabbath snapshot and extract:
+
+```yaml
+From sabbath file:
+  - loop_id
+  - iteration (where we stopped)
+  - original prompt
+  - files modified
+  - hypotheses tested
+  - next steps
+  - key context to restore
+```
+
+### Step 4: Display Context Restoration
+
+```
++------------------------------------------------------------------------------+
+| POWER LOOP RESUME                                                            |
++------------------------------------------------------------------------------+
+|                                                                              |
+|  Restoring Loop: ${LOOP_ID}                                                  |
+|  Paused At: Iteration [N]                                                    |
+|  Reason: [context_rot | user_stop | session_end]                             |
+|                                                                              |
+|  Sabbath Rest Snapshot:                                                      |
+|    ${SABBATH_FILE}                                                           |
+|                                                                              |
++------------------------------------------------------------------------------+
+| RESTORED CONTEXT                                                             |
++------------------------------------------------------------------------------+
+|                                                                              |
+|  Progress Summary:                                                           |
+|    [from sabbath file]                                                       |
+|                                                                              |
+|  Files Modified:                                                             |
+|    - [file]: [change]                                                        |
+|    - [file]: [change]                                                        |
+|                                                                              |
+|  Key Context:                                                                |
+|    [critical information from sabbath file]                                  |
+|                                                                              |
+|  Immediate Next Step:                                                        |
+|    [exactly what to do]                                                      |
+|                                                                              |
++------------------------------------------------------------------------------+
+```
+
+### Step 5: Restore Loop State
+
+Recreate active loop config:
+
+```bash
+cat > .planning/loops/active-loop.json << 'EOF'
+{
+  "id": "${LOOP_ID}",
+  "prompt": "[original prompt from sabbath file]",
+  "completion_promise": "[promise]",
+  "max_iterations": [original max],
+  "current_iteration": [where we stopped],
+  "checkpoint_interval": [N],
+  "loop_file": "[original loop file]",
+  "resumed_from_sabbath": true,
+  "resume_timestamp": "[now]"
+}
+EOF
+```
+
+### Step 6: Update Loop File
+
+Add resume entry:
+
+```markdown
+## Sabbath Rest Resume
+
+- **Resumed At:** [timestamp]
+- **Previous Iteration:** [N]
+- **Context:** Fresh (post-Sabbath Rest)
+- **Sabbath File:** ${SABBATH_FILE}
+
+### Restored Context Summary
+[Key points from sabbath file]
+
+---
+
+## Loop Progress (Continued)
+
+| Iteration | Timestamp | Action | Result | Context |
+|-----------|-----------|--------|--------|---------|
+| [N+1] | [now] | Resumed from Sabbath Rest | Fresh context | Fresh |
+```
+
+### Step 7: Update CONSCIENCE.md
+
+```markdown
+## Active Power Loop (Resumed)
+
+- **ID:** ${LOOP_ID}
+- **Resumed:** [timestamp]
+- **Iteration:** [N] / [max] (continuing)
+- **Status:** Running (fresh context)
+- **Promise:** "[completion_promise]"
+- **Context Health:** Fresh (post-Sabbath)
+
+To cancel: `/fire-loop-stop`
+```
+
+### Step 8: Run /fire-discover (Optional)
+
+If the loop was paused due to being stuck:
+
+```
+Would you like to run /fire-discover to find new patterns?
+This may help if the loop was stuck before Sabbath Rest.
+
+[Yes - run discovery] [No - continue with existing approach]
+```
+
+### Step 9: Display Resume Banner and Continue
+
+```
++------------------------------------------------------------------------------+
+| POWER LOOP RESUMED - ITERATION [N+1]                                         |
++------------------------------------------------------------------------------+
+|                                                                              |
+|  Loop ID: ${LOOP_ID}                                                         |
+|  Continuing from: Iteration [N]                                              |
+|  Remaining: [max - N] iterations                                             |
+|  Context: FRESH                                                             |
+|                                                                              |
+|  Original Task:                                                              |
+|    [prompt]                                                                  |
+|                                                                              |
+|  Completion Promise: "[promise]"                                             |
+|                                                                              |
+|  Immediate Action:                                                           |
+|    [next step from sabbath file]                                             |
+|                                                                              |
++------------------------------------------------------------------------------+
+```
+
+Then continue executing the task with fresh context.
+
+---
+
+## Edge Cases
+
+### No Loops to Resume
+
+```
++------------------------------------------------------------------------------+
+| NO LOOPS TO RESUME                                                           |
++------------------------------------------------------------------------------+
+|                                                                              |
+|  No paused or stopped Power Loops found.                                     |
+|                                                                              |
+|  To start a new loop:                                                        |
+|    /fire-loop "Your task" --max-iterations 30                               |
+|                                                                              |
+|  To list all loop files:                                                     |
+|    ls .planning/loops/                                                       |
+|                                                                              |
++------------------------------------------------------------------------------+
+```
+
+### Multiple Loops Available
+
+```
++------------------------------------------------------------------------------+
+| MULTIPLE LOOPS AVAILABLE                                                     |
++------------------------------------------------------------------------------+
+|                                                                              |
+|  Found multiple paused loops. Specify which to resume:                       |
+|                                                                              |
+|  1. 20260123-143052 - "Fix auth bug" (iter 15/30, context_rot)              |
+|  2. 20260122-091530 - "Build API" (iter 8/50, user_stop)                    |
+|  3. 20260121-162045 - "Refactor DB" (iter 22/40, session_end)               |
+|                                                                              |
+|  Resume with:                                                                |
+|    /fire-loop-resume 20260123-143052                                        |
+|                                                                              |
++------------------------------------------------------------------------------+
+```
+
+---
+
+## Success Criteria
+
+- [ ] Sabbath Rest snapshot found and loaded
+- [ ] Context fully restored from snapshot
+- [ ] Active loop config recreated
+- [ ] Loop file updated with resume entry
+- [ ] CONSCIENCE.md updated
+- [ ] Fresh context confirmed
+- [ ] Loop continues from correct iteration
+- [ ] Original prompt and promise preserved
+
+---
+
+## References
+
+- **Related:** `/fire-loop` - Start new loop
+- **Related:** `/fire-loop-stop` - Stop active loop
+- **Related:** `/fire-discover` - Find patterns when stuck
+- **Skills:** `@skills-library/methodology/SABBATH_REST_PATTERN.md`