continuous-improvement 3.1.0 → 3.8.0

package/plugins/continuous-improvement/bin/observe.mjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+// observe.mts — Mulahazah PreToolUse/PostToolUse observation hook.
+//
+// Reads a Claude Code hook JSON payload from stdin and appends one rich-schema
+// JSONL line to ~/.claude/instincts/<project-hash>/observations.jsonl. Drop-in
+// replacement for the bash observe.sh fallback path: no jq dependency, captures
+// `tool_input.command` for Bash and `Edit.file_path` for Edit/Write/Read so the
+// downstream analysis pass can detect user corrections, error→fix sequences,
+// and tool-argument bigrams the thin schema could not represent.
+//
+// Contract:
+//   - Always exits 0. Never blocks the Claude session.
+//   - Catches every error to stderr; never throws.
+//   - Empty stdin / malformed JSON / missing tool_name → no-op exit 0.
+//   - Hook budget: <500ms on Windows (per CONTRIBUTING.md).
+//
+// See docs/plans/2026-05-05-node-observer-rich-schema.md for the full design.
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { parseHookPayload, summariseInput, summariseOutput } from "../lib/observe-event.mjs";
+const ROTATION_LINE_THRESHOLD = 10_000;
+const ARCHIVE_RETENTION = 10;
+main();
+function main() {
+    try {
+        runObserver();
+    }
+    catch (error) {
+        // Never block the session. Failures land in stderr only.
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`[observe] ${message}\n`);
+    }
+    process.exit(0);
+}
+function runObserver() {
+    const raw = readStdin();
+    const payload = parseHookPayload(raw);
+    if (!payload)
+        return;
+    const projectRoot = resolveProjectRoot();
+    const projectHash = createHash("sha256").update(projectRoot).digest("hex").slice(0, 12);
+    const projectName = basename(projectRoot.replace(/\.git$/, ""));
+    const instinctsDir = join(getHomeDir(), ".claude", "instincts");
+    const projectDir = join(instinctsDir, projectHash);
+    const obsFile = join(projectDir, "observations.jsonl");
+    ensureDir(projectDir);
+    rotateIfNeeded(obsFile, projectDir);
+    const ts = new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+    const event = payload.tool_response !== undefined ? "tool_complete" : "tool_start";
+    const row = {
+        ts,
+        event,
+        session: payload.session_id,
+        tool: payload.tool_name,
+        input_summary: summariseInput(payload.tool_name, payload.tool_input),
+        output_summary: summariseOutput(payload.tool_response),
+        project_id: projectHash,
+        project_name: projectName,
+    };
+    appendFileSync(obsFile, JSON.stringify(row) + "\n", "utf8");
+    writeProjectJsonIfNew(projectDir, projectHash, projectName, projectRoot, ts);
+}
+function readStdin() {
+    try {
+        return readFileSync(0, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+function getHomeDir() {
+    // CLAUDE_PROJECT_DIR is the project root, not the home dir; HOME wins for
+    // home-dir resolution. Fall through to USERPROFILE on Windows then os.homedir.
+    return process.env.HOME || process.env.USERPROFILE || homedir();
+}
+function resolveProjectRoot() {
+    const fromEnv = process.env.CLAUDE_PROJECT_DIR;
+    // The bash version trusts CLAUDE_PROJECT_DIR unconditionally when set;
+    // preserve that semantic so test fixtures with synthetic /tmp/... paths
+    // and operator workflows that pre-set the env var both keep working.
+    if (fromEnv)
+        return fromEnv;
+    try {
+        // execFileSync (not execSync) — no shell, fixed argv array, no injection
+        // surface. Inputs are all hard-coded constants.
+        const root = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        if (root)
+            return root;
+    }
+    catch {
+        // Not in a git repo — fall through.
+    }
+    return "global";
+}
+function ensureDir(dir) {
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+}
+function rotateIfNeeded(obsFile, projectDir) {
+    if (!existsSync(obsFile))
+        return;
+    const lineCount = countLines(obsFile);
+    if (lineCount < ROTATION_LINE_THRESHOLD)
+        return;
+    const archiveTs = new Date().toISOString().replace(/[:.]/g, "-").replace(/Z$/, "");
+    renameSync(obsFile, join(projectDir, `observations.${archiveTs}.jsonl`));
+    pruneArchives(projectDir);
+}
+function countLines(file) {
+    const stat = statSync(file);
+    if (stat.size === 0)
+        return 0;
+    // For files capped at 10k lines, readFileSync is faster than streaming.
+    return readFileSync(file, "utf8").split("\n").length - 1;
+}
+function pruneArchives(projectDir) {
+    const archives = readdirSync(projectDir)
+        .filter((name) => /^observations\..+\.jsonl$/.test(name))
+        .sort()
+        .reverse()
+        .map((name) => join(projectDir, name));
+    for (const path of archives.slice(ARCHIVE_RETENTION)) {
+        try {
+            unlinkSync(path);
+        }
+        catch {
+            // Pruning failure is non-fatal; rotation already happened.
+        }
+    }
+}
+function writeProjectJsonIfNew(projectDir, projectHash, projectName, projectRoot, ts) {
+    const projectJson = join(projectDir, "project.json");
+    if (existsSync(projectJson))
+        return;
+    const body = {
+        id: projectHash,
+        name: projectName,
+        root: projectRoot,
+        created_at: ts,
+    };
+    writeFileSync(projectJson, JSON.stringify(body) + "\n", "utf8");
+}

package/plugins/continuous-improvement/commands/continuous-improvement.md

@@ -0,0 +1,115 @@
+---
+name: continuous-improvement
+description: "Reflect on the current session, analyze observations for patterns, and show instinct status. Runs on-demand to save tokens."
+---
+
+# /continuous-improvement
+
+Run this when you want to reflect and learn — not every session. Three steps in order.
+
+## Step 1: Reflect
+
+Generate a reflection for this session based on what happened:
+
+```
+## Reflection — [Date]
+- What worked:
+- What failed:
+- What I'd do differently:
+- Rule to add:
+- Iteration — Next best recommendations (ranked, top 3):
+  1. <primary — strongest next move>
+  2. <alternative — different angle>
+  3. <alternative — smaller/larger scope>
+```
+
+If there's a "Rule to add", create an instinct YAML file with 0.6 starting confidence in the project's instinct directory.
+
+The "Iteration — Next best recommendations" field is the Law 6 handoff. List the **top 3 ranked** core-development moves — what to build, fix, refactor, or investigate next so the feature/system advances. Item #1 is the strongest; #2 and #3 are alternatives the user can pivot to. NOT git steps (commit, push, PR), NOT verification re-runs, NOT deploy actions — those belong in the end-of-run summary.
+
+Format per item: `<verb> <object at path:line> (<why, one clause grounded in current context>)`.
+
+Rules: always exactly 3 distinct directions, not padding. If fewer real moves exist, fill remaining slots with `None — goal met from this angle.` If the goal is fully met across all angles, write `1. None — goal met, stop.` and omit #2 and #3.
+
+## Step 2: Analyze Observations
+
+Check `~/.claude/instincts/` for the current project (detect via git root → SHA-256 first 12 chars).
+
+Look at `~/.claude/instincts/<hash>/observations.jsonl`. If 20+ lines exist:
+
+1. Read the last 500 lines
+2. Read existing instinct `*.yaml` files (project + global)
+3. Detect patterns:
+   - User corrections → "don't do X" instincts
+   - Error→fix sequences → "when X fails, try Y"
+   - Repeated workflows (3+ times) → "for X, do A→B→C"
+   - Tool preferences → "use tool Y for task X"
+4. Create/update instinct YAML files
+5. Be conservative: only create instincts for 3+ observations of the same pattern
+
+If fewer than 20 observations, skip analysis and note the count.
+
+### Multi-Agent Analysis (500+ observations)
+
+When observation backlog is large, parallelize:
+- **Agent 1:** User corrections + error→fix patterns
+- **Agent 2:** Repeated workflows + tool preferences
+- **Agent 3:** Cross-reference existing instincts for updates
+
+Merge results and deduplicate before writing YAML files.
+
+## Step 3: Show Status
+
+Display all instincts for the current project + global:
+
+```
+=== continuous-improvement ===
+
+## Level: [CAPTURE | ANALYZE | SUGGEST | AUTO-APPLY]
+
+## Session Reflection
+- What worked: [from this session]
+- What failed: [from this session]
+- What I'd do differently: [from this session]
+- Rule to add: [captured as instinct]
+- Iteration — Next best recommendations (ranked, top 3):
+  1. [primary core-development move]
+  2. [alternative angle]
+  3. [alternative scope]
+
+## Learning
+  NEW  [instinct-id]        [domain]  [confidence]  (from reflection)
+   ↑   [instinct-id]        [domain]  [old]→[new]   (+N observations)
+
+## Instincts — [project-name] ([hash])
+  ● [0.85] instinct-id       domain   auto-apply
+  ◐ [0.60] instinct-id       domain   suggest
+  ○ [0.35] instinct-id       domain   silent
+
+## Instincts — global
+  ● [0.90] instinct-id       domain   auto-apply
+
+## Next
+- Keep working — hooks capture automatically
+- System auto-levels as instincts gain confidence
+```
+
+If no instincts or observations exist yet, explain this is expected — the system is in CAPTURE level and will create instincts after 20+ observations accumulate.
+
+## Subcommands
+
+### `/continuous-improvement weekly`
+
+Set up a weekly analysis schedule:
+1. Create a cron/loop schedule that runs `/continuous-improvement analyze` every 7 days
+2. Confirm the schedule to the user
+3. Show next scheduled run date
+
+### `/continuous-improvement always-on`
+
+Toggle always-on mode for the current project:
+1. Find project hash
+2. Create/update `~/.claude/instincts/<hash>/config.yaml` with `always_on: true|false`
+3. Confirm the change
+
+**Default is off** — observations accumulate silently, analysis only runs when you ask.

package/plugins/continuous-improvement/commands/dashboard.md

@@ -0,0 +1,56 @@
+---
+name: dashboard
+description: Visual dashboard showing instinct health, observation stats, and learning progress
+---
+
+# Instinct Dashboard
+
+Generate a visual dashboard for this project's continuous-improvement status.
+
+## Instructions
+
+1. **Find project hash:** Run `git rev-parse --show-toplevel 2>/dev/null`, then SHA-256 first 12 chars
+2. **Read observations:** Count lines in `~/.claude/instincts/<hash>/observations.jsonl`
+3. **Read instincts:** Load all `*.yaml` files from project dir + `global/`
+4. **Read instinct packs:** Check if any packs from `instinct-packs/` have been loaded
+
+## Display Format
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║              continuous-improvement Dashboard                ║
+╠══════════════════════════════════════════════════════════════╣
+║                                                              ║
+║  Project: <name>              Level: <CAPTURE|ANALYZE|...>   ║
+║  Sessions: ~<obs/10>          Mode: <beginner|expert>        ║
+║                                                              ║
+║  ┌─ Observations ────────────────────────────────────────┐   ║
+║  │  Total: <n>    Unprocessed: <n>    Last: <date>       │   ║
+║  └───────────────────────────────────────────────────────┘   ║
+║                                                              ║
+║  ┌─ Instincts ───────────────────────────────────────────┐   ║
+║  │  Total: <n>                                           │   ║
+║  │  ████████░░ Auto-apply (0.7+): <n>                    │   ║
+║  │  █████░░░░░ Suggest (0.5-0.69): <n>                   │   ║
+║  │  ██░░░░░░░░ Silent (< 0.5): <n>                       │   ║
+║  │  Global: <n>    Project: <n>                          │   ║
+║  └───────────────────────────────────────────────────────┘   ║
+║                                                              ║
+║  ┌─ Top Instincts ───────────────────────────────────────┐   ║
+║  │  <list top 5 instincts by confidence with bars>       │   ║
+║  └───────────────────────────────────────────────────────┘   ║
+║                                                              ║
+║  ┌─ Health ──────────────────────────────────────────────┐   ║
+║  │  Stale (30+ days): <n>    Decaying: <n>               │   ║
+║  │  Recently reinforced: <n>                             │   ║
+║  └───────────────────────────────────────────────────────┘   ║
+║                                                              ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+## After Display
+
+- If stale instincts > 0: suggest reviewing them
+- If unprocessed observations > 20: suggest running analysis
+- If no instincts exist: explain the auto-leveling timeline
+- Show available instinct packs that haven't been loaded yet

package/plugins/continuous-improvement/commands/discipline.md

@@ -0,0 +1,51 @@
+---
+name: discipline
+description: Quick reference card for the 7 Laws of AI Agent Discipline
+---
+
+# The 7 Laws — Quick Reference
+
+Print this card and check yourself against each law.
+
+## The Laws
+
+| # | Law | Check | Red Flag |
+|---|-----|-------|----------|
+| 1 | **Research Before Executing** | Did I search for existing solutions? | "I'll just quickly..." |
+| 2 | **Plan Is Sacred** | Did I state WILL / WILL NOT / VERIFY? | "Let me also add..." |
+| 3 | **One Thing at a Time** | Am I finishing before starting? | "While I'm here..." |
+| 4 | **Verify Before Reporting** | Did I check the ACTUAL output? | "This should work..." |
+| 5 | **Reflect After Sessions** | Did I note what worked/failed? | "I'll remember..." |
+| 6 | **Iterate One Change** | Am I changing one thing at a time? | "And also..." |
+| 7 | **Learn From Every Session** | Did I capture this as an instinct? | "Next time I'll..." |
+
+## Operator Stakes
+
+The Laws above are the *how*. These five principles are the *why*: code ships from your account, the incident lands on your pager, the bill hits your budget. Each one pairs with the Law that prevents it from going wrong.
+
+| # | Principle | Vibe coder | Engineer | Law |
+|---|-----------|------------|----------|-----|
+| 1 | **Ownership** | Ships auth, moves on | Adds rate limits, audit logs, password-reset flow, incident runbook before shipping | 4 |
+| 2 | **Reliability over cleverness** | Accepts a clever regex + heavy lib that breaks on ISO 8601 with millis | Picks the boring tested API, writes tests for leap years and DST | 1 |
+| 3 | **Systems thinking** | Builds in-memory CSV export, works for 100 dev users, OOMs in prod | Asks row count first, picks paginated background job + S3 link | 2 |
+| 4 | **Problem framing** | Builds the websocket chat the ticket asked for | Finds out users wanted faster support replies, not chat | 1 |
+| 5 | **Constraints management** | Calls the $0.02/image model on every upload | Does the math, adds client-side validation + caching + cheaper triage model | 2 |
+
+Code is a liability, not an asset. Speed without these five turns into someone else's incident at 3am — except the someone is you.
+
+## The Loop
+
+```
+Research → Plan → Execute (one thing) → Verify → Reflect → Learn → Iterate
+```
+
+## Self-Check
+
+Before saying "Done", verify ALL:
+- [ ] Code runs without errors
+- [ ] Output matches expected result
+- [ ] I checked the **actual** result (not assumed)
+- [ ] Build passes
+- [ ] I can explain the change in one sentence
+
+If you're skipping a step, that's the step you need most.

package/plugins/continuous-improvement/commands/harvest.md

@@ -0,0 +1,76 @@
+---
+name: harvest
+description: Harvest friction events from observation logs into typed instincts (env_issue, permission_block, wrong_approach, buggy_code) with confidence scoring.
+---
+
+# /harvest — Friction Harvest
+
+Run the friction-harvest classifier against this project's observation log and append new typed instincts to `instincts.jsonl`. Idempotent on re-run.
+
+## What it does
+
+Reads `~/.claude/instincts/<project-hash>/observations.jsonl` produced by the Mulahazah hook, classifies failure rows into four typed friction patterns, scores confidence with a recency-weighted decay, and appends new instincts to `<project-hash>/instincts.jsonl` alongside.
+
+| Type | What it catches |
+|---|---|
+| `env_issue` | jq missing, command not found, not recognized as cmdlet |
+| `permission_block` | sandbox / harness blocked, Permission denied |
+| `wrong_approach` | file changed since last read (parallel-actor stale) |
+| `buggy_code` | file not read first, old_string ambiguous, file too large |
+
+## How to invoke
+
+```
+node bin/harvest-friction.mjs
+node bin/harvest-friction.mjs <project-hash>
+node bin/harvest-friction.mjs --list
+```
+
+`--list` shows new classifications without writing to `instincts.jsonl` — useful for dry-run before committing the harvest output.
+
+## Idempotency
+
+Each instinct carries a `dedup_key = sha1(type + tool + summary[:120])`. Re-running on the same observations does not duplicate previously-written instincts; `loadExistingDedupKeys()` reads the destination file once at start.
+
+## Confidence model
+
+```
+confidence = log10(occurrence_count + 1) * recency_factor
+recency_factor = 0.5 + 0.5 * exp(-days_since_last_seen / 14)
+```
+
+One occurrence today → 0.30. Ten occurrences today → clamped to 1.0. One occurrence 30 days ago → 0.17.
+
+## Output shape
+
+```
+harvest-friction project=0af156594b39
+  observations rows:    9346
+  tool_complete rows:   2104
+  classified failures:  47
+  thin-schema rows:     0
+  new instincts:        12
+  skipped (existing):   35
+
+New instincts:
+  [0.92] env_issue on Bash (×8): bash: jq: command not found
+  [0.74] permission_block on Bash (×4): harness blocked direct push to main
+  ...
+
+Appended 12 instinct(s) to /Users/.../instincts/0af156594b39/instincts.jsonl
+```
+
+## When the classifier emits zero instincts
+
+If `tool_complete rows: 0`, the bash-fallback hook is active (no jq AND the Node observer is not on PATH) and only emits `tool_start` events. Two remediation paths:
+
+- **Install jq** — `winget install jqlang.jq` (Windows), `brew install jq` (macOS), `apt install jq` (Linux).
+- **Wire the Node observer** — ensure `hooks/bin/observe.mjs` is reachable from the active hook script.
+
+Both are documented in the WARNING the classifier prints on a thin-schema host.
+
+## Pairs with
+
+- **`continuous-improvement`** (core SKILL.md, Law 7 — Learn From Every Session) — the harvest pipeline is the concrete mechanism behind Law 7's "capture patterns as instincts" contract.
+- **`workspace-surface-audit`** — Phase 1 Environment Grain confirms whether jq + Node observer are available; if not, the harvest will run inert until that gap closes.
+- **`gateguard`** — observation rows include the Parallel-Actor Gate's HEAD/upstream baselines when divergence-halts fire; the classifier surfaces those as `wrong_approach` instincts.

package/plugins/continuous-improvement/commands/learn-eval.md

@@ -0,0 +1,117 @@
+---
+name: learn-eval
+description: "Extract reusable patterns from the session, self-evaluate quality before saving, and determine the right save location (Global vs Project)."
+---
+
+# /learn-eval - Extract, Evaluate, then Save
+
+Extends `/learn` with a quality gate, save-location decision, and knowledge-placement awareness before writing any skill file.
+
+## What to Extract
+
+Look for:
+
+1. **Error Resolution Patterns** — root cause + fix + reusability
+2. **Debugging Techniques** — non-obvious steps, tool combinations
+3. **Workarounds** — library quirks, API limitations, version-specific fixes
+4. **Project-Specific Patterns** — conventions, architecture decisions, integration patterns
+
+## Process
+
+1. Review the session for extractable patterns
+2. Identify the most valuable/reusable insight
+
+3. **Determine save location:**
+   - Ask: "Would this pattern be useful in a different project?"
+   - **Global** (`~/.claude/skills/learned/`): Generic patterns usable across 2+ projects (bash compatibility, LLM API behavior, debugging techniques, etc.)
+   - **Project** (`.claude/skills/learned/` in current project): Project-specific knowledge (quirks of a particular config file, project-specific architecture decisions, etc.)
+   - When in doubt, choose Global (moving Global → Project is easier than the reverse)
+
+4. Draft the skill file using this format:
+
+```markdown
+---
+name: pattern-name
+description: "Under 130 characters"
+user-invocable: false
+origin: auto-extracted
+---
+
+# [Descriptive Pattern Name]
+
+**Extracted:** [Date]
+**Context:** [Brief description of when this applies]
+
+## Problem
+[What problem this solves - be specific]
+
+## Solution
+[The pattern/technique/workaround - with code examples]
+
+## When to Use
+[Trigger conditions]
+```
+
+5. **Quality gate — Checklist + Holistic verdict**
+
+   ### 5a. Required checklist (verify by actually reading files)
+
+   Execute **all** of the following before evaluating the draft:
+
+   - [ ] Grep `~/.claude/skills/` and relevant project `.claude/skills/` files by keyword to check for content overlap
+   - [ ] Check MEMORY.md (both project and global) for overlap
+   - [ ] Consider whether appending to an existing skill would suffice
+   - [ ] Confirm this is a reusable pattern, not a one-off fix
+
+   ### 5b. Holistic verdict
+
+   Synthesize the checklist results and draft quality, then choose **one** of the following:
+
+   | Verdict | Meaning | Next Action |
+   |---------|---------|-------------|
+   | **Save** | Unique, specific, well-scoped | Proceed to Step 6 |
+   | **Improve then Save** | Valuable but needs refinement | List improvements → revise → re-evaluate (once) |
+   | **Absorb into [X]** | Should be appended to an existing skill | Show target skill and additions → Step 6 |
+   | **Drop** | Trivial, redundant, or too abstract | Explain reasoning and stop |
+
+   **Guideline dimensions** (informing the verdict, not scored):
+
+   - **Specificity & Actionability**: Contains code examples or commands that are immediately usable
+   - **Scope Fit**: Name, trigger conditions, and content are aligned and focused on a single pattern
+   - **Uniqueness**: Provides value not covered by existing skills (informed by checklist results)
+   - **Reusability**: Realistic trigger scenarios exist in future sessions
+
+6. **Verdict-specific confirmation flow**
+
+   - **Improve then Save**: Present the required improvements + revised draft + updated checklist/verdict after one re-evaluation; if the revised verdict is **Save**, save after user confirmation, otherwise follow the new verdict
+   - **Save**: Present save path + checklist results + 1-line verdict rationale + full draft → save after user confirmation
+   - **Absorb into [X]**: Present target path + additions (diff format) + checklist results + verdict rationale → append after user confirmation
+   - **Drop**: Show checklist results + reasoning only (no confirmation needed)
+
+7. Save / Absorb to the determined location
+
+## Output Format for Step 5
+
+```
+### Checklist
+- [x] skills/ grep: no overlap (or: overlap found → details)
+- [x] MEMORY.md: no overlap (or: overlap found → details)
+- [x] Existing skill append: new file appropriate (or: should append to [X])
+- [x] Reusability: confirmed (or: one-off → Drop)
+
+### Verdict: Save / Improve then Save / Absorb into [X] / Drop
+
+**Rationale:** (1-2 sentences explaining the verdict)
+```
+
+## Design Rationale
+
+This version replaces the previous 5-dimension numeric scoring rubric (Specificity, Actionability, Scope Fit, Non-redundancy, Coverage scored 1-5) with a checklist-based holistic verdict system. Modern frontier models (Opus 4.6+) have strong contextual judgment — forcing rich qualitative signals into numeric scores loses nuance and can produce misleading totals. The holistic approach lets the model weigh all factors naturally, producing more accurate save/drop decisions while the explicit checklist ensures no critical check is skipped.
+
+## Notes
+
+- Don't extract trivial fixes (typos, simple syntax errors)
+- Don't extract one-time issues (specific API outages, etc.)
+- Focus on patterns that will save time in future sessions
+- Keep skills focused — one pattern per skill
+- When the verdict is Absorb, append to the existing skill rather than creating a new file

package/plugins/continuous-improvement/commands/planning-with-files.md

@@ -0,0 +1,66 @@
+---
+name: planning-with-files
+description: Create and maintain task_plan.md, findings.md, and progress.md for persistent file-based planning
+---
+
+# /planning-with-files
+
+Use this workflow only when the user explicitly wants persistent, file-based planning. It is opt-in.
+
+## Project Root
+
+1. Run `git rev-parse --show-toplevel 2>/dev/null`
+2. If that fails, use the current working directory
+3. Create and read planning files in that root only
+
+The planning files are:
+- `task_plan.md`
+- `findings.md`
+- `progress.md`
+
+## `init`
+
+If the files do not exist, create them in the project root.
+
+`task_plan.md` must include:
+- `## Goal`
+- `## Status`
+- `## Phases`
+- `## Key Questions`
+- `## Decisions Made`
+- `## Errors Encountered`
+
+Default phases:
+- `Research`
+- `Plan`
+- `Execute`
+- `Verify`
+- `Reflect`
+
+Never overwrite existing planning files unless the user explicitly asks you to reset or replace them.
+
+## `status`
+
+Read all three files and summarize:
+- Current status from `task_plan.md`
+- Checked vs unchecked phases
+- Whether `findings.md` has real notes yet
+- Whether `progress.md` has real session or verification entries yet
+
+If the files do not exist, say so and offer to initialize them.
+
+## `checkpoint`
+
+After a meaningful work chunk:
+- Update `progress.md` with what happened, commands run, and verification notes
+- Add new discoveries or sources to `findings.md`
+- Update `task_plan.md` progress, decisions, and errors
+
+Do not hide failures. Log them in `## Errors Encountered`.
+
+## `recover`
+
+When resuming after context loss or a new session:
+- Re-read `task_plan.md`, `findings.md`, and `progress.md` before making major decisions
+- Restate the current goal, phase, open questions, and latest verification state
+- Continue from the recorded plan instead of rebuilding context from memory