configs-all 1.0.0

package/claude/commands/merge.md

@@ -0,0 +1,129 @@
+## Merge PR — Review, Fix & Merge
+
+Autonomously review a PR, fix any issues found, and merge it. Combines deep code review with autonomous fix capability. Will not merge until 100% confident the PR is clean.
+
+### Input
+$ARGUMENTS - PR number, URL, or branch name. If omitted, finds PR for current branch, or the most recent open PR in the repo.
+
+### Instructions
+
+**Before delegating, gather project context:**
+1. Read `docs/context/` for the most recent context snapshot — extract Architecture, Conventions, Testing, and Gotchas sections
+2. Read the project CLAUDE.md if it exists — extract Conventions and Common Mistakes sections
+3. Read `docs/incidents/` for recent incidents — are any related to the files being changed?
+4. Read `docs/spikes/` for recent spikes — is this PR implementing a spiked approach?
+
+**Then delegate this task to a subagent using the Agent tool with `model: "sonnet"` and `subagent_type: "general-purpose"`.** Pass the full prompt below (with context injected) to the subagent and relay its result.
+
+### Subagent prompt
+
+You are an autonomous PR reviewer and fixer. Your job is to review PR `$ARGUMENTS`, fix any issues you find, and merge it — but ONLY when you are 100% confident it is clean.
+
+**Project Context:**
+[Inject Architecture, Conventions, Testing, Gotchas from docs/context if available]
+[Inject Conventions, Common Mistakes from project CLAUDE.md if available]
+[Inject any related incidents or spikes if relevant]
+If no project context is available, review against general best practices and note that project context was unavailable.
+
+#### Phase 1: Load the PR
+
+1. **Resolve the PR:**
+   - If `$ARGUMENTS` is a number or URL, use it directly
+   - If `$ARGUMENTS` is a branch name: `gh pr list --head $ARGUMENTS --json number --jq '.[0].number'`
+   - If `$ARGUMENTS` is empty:
+     - Try current branch: `gh pr list --head $(git branch --show-current) --json number --jq '.[0].number'`
+     - If no result: latest open PR: `gh pr list --state open --limit 1 --json number --jq '.[0].number'`
+   - If no PR found, stop: "No open PR found. Create one first with `/pr`."
+
+2. **Fetch PR details:**
+   ```bash
+   gh pr view $PR_NUMBER --json title,body,author,baseRefName,headRefName,additions,deletions,commits,reviewDecision
+   gh pr diff $PR_NUMBER
+   ```
+
+#### Phase 2: Review and Fix Loop (max 3 iterations)
+
+For each iteration:
+
+3. **Deep review** — read all changed files in full context (not just the diff):
+   - Read each modified file completely
+   - Check how changed functions/classes are used elsewhere
+   - Check if tests exist for the changed code
+
+4. **Review every change for:**
+   - **Correctness:** Logic errors, off-by-one, null/undefined, race conditions
+   - **Security:** Hardcoded secrets, injection vulnerabilities, XSS, OWASP top 10
+   - **Types:** Missing types, incorrect types, unsafe `any` (TypeScript)
+   - **Error handling:** Unhandled rejections, missing try/catch, bare exceptions
+   - **Project conventions:** Does the code follow established patterns? (Use project context)
+   - **Testing:** Are new features tested? Edge cases covered?
+   - **Performance:** N+1 queries, unnecessary re-renders, unbounded loops
+   - **Breaking changes:** API contracts, migrations, backwards compatibility
+
+5. **Check for anti-patterns:**
+   - Files that shouldn't be committed (`.env`, `node_modules`, build artifacts)
+   - Tests that test implementation instead of behavior
+   - Missing or inadequate PR description
+
+6. **If issues found — fix them:**
+   - Check out the PR branch: `gh pr checkout $PR_NUMBER`
+   - Fix all identified issues in the code
+   - Run the test suite to verify fixes don't break anything
+   - Run linter to verify code style
+   - Stage and commit fixes:
+     ```bash
+     git add <fixed files>
+     git commit -m "fix: address review feedback — <brief description>"
+     ```
+   - Push to the PR branch: `git push`
+   - **Loop back to step 3** for re-review (track iteration count)
+
+7. **If no issues found — proceed to Phase 3**
+
+#### Phase 3: Pre-Merge Verification
+
+8. **Run all checks in parallel:**
+   - `gh pr checks $PR_NUMBER` — all CI checks must be passing (wait up to 5 minutes for in-progress checks)
+   - Run full test suite locally — all must pass
+   - Run linter — zero errors
+   - Run build if applicable — must succeed
+
+9. **Confidence gate:**
+   - If ANY concern remains: **stop and report**. Do NOT merge.
+   - Only proceed if 100% confident this is merge-ready.
+   - Document what was checked and what gives confidence.
+
+10. **Check for merge blockers:**
+    - `gh pr view $PR_NUMBER --json reviewDecision,mergeStateStatus`
+    - If branch protection requires reviews from others, report: "This PR requires human review approval before it can be merged."
+    - If merge is blocked for any other reason, report the blocker and stop.
+
+#### Phase 4: Merge
+
+11. **Merge the PR:**
+    ```bash
+    gh pr merge $PR_NUMBER --merge --delete-branch
+    ```
+    - Verify: `gh pr view $PR_NUMBER --json state --jq '.state'` should return "MERGED"
+
+12. **Report:**
+    ```
+    ## Merge Report
+    - **PR:** #<number> — <title>
+    - **URL:** <pr_url>
+    - **Review iterations:** <count> (0 = clean on first review)
+    - **Fixes applied:** <list of fix commits, or "None">
+    - **CI checks:** all passing
+    - **Merge method:** merge (full history preserved)
+    - **Branch:** <branch> deleted
+    - **Status:** Successfully merged
+    ```
+
+### Critical Rules
+
+- **NEVER merge with failing CI checks.**
+- **NEVER skip the deep review.** Read every changed file in full.
+- **NEVER proceed past the confidence gate with concerns.**
+- **Max 3 fix iterations.** If still not clean after 3 rounds, stop and report remaining issues.
+- **If in doubt, stop and report.** A delayed merge is always better than merging bad code.
+- **NEVER use --squash or --rebase.** Always use --merge to preserve full git history.

package/claude/commands/mikpc.md

@@ -0,0 +1,54 @@
+## Remote Work on mikpc (Windows PC via WSL)
+
+Execute tasks on mikpc remotely over SSH from the current machine.
+
+### Input
+$ARGUMENTS - what to do on the PC (e.g., "install htop", "check disk space", "update configs", "run claude doctor")
+
+### Connection
+- **SSH host**: `mikpc` (Tailscale: 100.89.204.71) or `mikpc-local` (LAN: 192.168.0.5)
+- **User**: `wolfe`
+- **Environment**: WSL2 Ubuntu 24.04, zsh, Node.js 22
+- **Shell**: Commands run via `ssh mikpc "<command>"` land in bash by default. For zsh features, prefix with `zsh -lc '...'`
+
+### Key Paths on PC
+- **Home**: `/home/wolfe`
+- **Dropbox**: `~/Dropbox` (symlink to `/mnt/c/Users/wolfe/Dropbox`)
+- **Configs repo**: `~/Dropbox/mikpc/dev/configs`
+- **Claude config**: `~/.claude/`
+- **SSH keys**: `~/.ssh/id_ed25519` (native WSL key, not 1Password)
+
+### Environment Notes
+- Git is configured with `user.name=chiefmikey`, SSH signing is disabled (uses native key)
+- Passwordless sudo is configured for wolfe
+- NTFS-mounted paths (under `/mnt/c/`) have uid/gid 1001 mapped
+- Config backups route to `~/.config/config-backups` (not NTFS Dropbox path)
+- Claude Code v2.1.58+ with superpowers plugin installed
+
+### Config Sync
+The PC has its own git clone of the configs repo at `~/Dropbox/mikpc/dev/configs`. Dropbox sync is unreliable, so always sync via git:
+1. **Before PC work**: Commit and push any local changes from this machine first
+2. **Pull on PC**: `ssh mikpc "cd ~/Dropbox/mikpc/dev/configs && git pull origin main"`
+3. **Deploy**: `ssh mikpc "cd ~/Dropbox/mikpc/dev/configs && zsh scripts/sync/push-configs.zsh"`
+4. **Push Claude commands manually** if push-configs exits early: `ssh mikpc 'bash -c "cp ~/Dropbox/mikpc/dev/configs/claude/commands/*.md ~/.claude/commands/"'`
+
+Always sync configs at the start of a session if any config files have been modified locally.
+
+### Execution Rules
+1. Use `ssh mikpc` for all commands. Fall back to `ssh mikpc-local` only if Tailscale is unreachable.
+2. For multi-command workflows, chain with `&&` or use a heredoc:
+   ```
+   ssh mikpc bash -s <<'REMOTE'
+   command1
+   command2
+   REMOTE
+   ```
+3. For interactive tools (like running claude), warn the user that SSH pseudo-terminal allocation may be needed (`ssh -t mikpc`).
+4. Always show command output to the user so they can see what happened.
+5. Do the work - don't just explain what to do. Execute the commands remotely.
+
+### Steps
+1. If config files were changed locally, commit and push first, then pull and push-configs on PC
+2. Parse what the user wants done on the PC from $ARGUMENTS
+3. Connect via SSH and execute the task
+4. Report results

package/claude/commands/morning.md

@@ -0,0 +1,72 @@
+## Daily Briefing
+
+**IMPORTANT: Immediately delegate this entire task to a subagent using the Agent tool with `model: "sonnet"` and `subagent_type: "general-purpose"`.** Do not perform operations yourself. Pass the full prompt below to the subagent and relay its result.
+
+### Subagent prompt
+
+You are generating a morning briefing — a complete situational awareness snapshot so the user knows exactly what needs attention today. Run all independent checks in parallel.
+
+1. **Git state across the current repo:**
+   - `git status` — any uncommitted work?
+   - `git log --oneline -15 --since="yesterday"` — what changed since yesterday?
+   - `git branch -a --sort=-committerdate | head -10` — active branches
+   - `git stash list` — any stashed work?
+
+2. **Documentation state:**
+   - Check `docs/handoff/` — read the most recent handoff doc (this is the #1 priority for context)
+   - Check `docs/plans/` — any plans with `_Status: IN PROGRESS_` or `_Status: PENDING_`?
+   - Check `docs/spikes/` — any spikes `_Status: IN PROGRESS_`? Any recent completed spikes with action items?
+   - Check `docs/incidents/` — any incidents `_Status: ACTIVE_` or `_Status: MITIGATED_`? These are P1 priority.
+   - Check `docs/context/` — when was context last updated? Is it stale?
+   - Check `docs/research/` — any Open Questions from recent research?
+
+3. **GitHub state** (if `gh` CLI is available):
+   - `gh pr list --author @me` — your open PRs and their CI status
+   - `gh pr list --search "review-requested:@me"` — PRs waiting for your review
+   - `gh issue list --assignee @me --limit 10` — issues assigned to you
+   - Check CI status on open PRs: `gh pr checks` for each
+
+4. **Code health:**
+   - Check if tests pass (run the test command from project CLAUDE.md or docs/context if available — but use a timeout, don't block on slow suites)
+   - Check for lint errors (quick lint check)
+   - Check for build errors (quick build check)
+
+5. **Format the briefing:**
+
+   ```markdown
+   # Morning Briefing — YYYY-MM-DD
+
+   ## Handoff from Last Session
+   [Summary from docs/handoff/ if exists — what was being worked on, what's next]
+
+   ## Active Incidents
+   [Any ACTIVE or MITIGATED incidents — these are top priority]
+
+   ## Pending Plans
+   [List any IN PROGRESS or PENDING plans with step counts and progress]
+
+   ## In-Progress Spikes
+   [Any spikes still under investigation]
+
+   ## Open PRs
+   [Your PRs with CI status — which need attention?]
+
+   ## Review Requests
+   [PRs waiting for your review]
+
+   ## Issues
+   [Assigned issues, prioritized]
+
+   ## Code Health
+   - Tests: [passing/failing/not run]
+   - Lint: [clean/errors]
+   - Build: [passing/failing]
+
+   ## Recommended Priority
+   Based on all of the above, here's what I'd tackle first:
+   1. [Most important — with reasoning]
+   2. [Second priority]
+   3. [Third priority]
+   ```
+
+6. Keep it concise — this is a 60-second read, not a report. Flag what needs attention, skip what's fine.

package/claude/commands/partymode.md

@@ -0,0 +1,105 @@
+## Full Autopilot — Prep and Execute
+
+The complete autonomous pipeline. Researches the codebase, builds context, creates an implementation plan, gets one approval, then executes to 100% verified completion.
+
+Give it a task and walk away. Come back to done. Or give it nothing — it will determine the highest priority task and do that.
+
+### Input
+$ARGUMENTS - optional task description (e.g., "add dark mode support", "refactor authentication to use JWT"). If omitted, autonomously determines the next highest priority task.
+
+### Instructions
+
+#### Phase 0: Project CLAUDE.md Setup
+
+0. **Ensure the project has a CLAUDE.md** (same as `/init` Phase 1):
+
+   a. **Check for existing CLAUDE.md** in the project root.
+
+   b. **If none exists — generate fresh:**
+      - Detect tech stack, project structure, commands, conventions, testing setup
+      - Write `./CLAUDE.md` with real values — no placeholders, no generic content
+      - Sections: Project Overview, Tech Stack, Architecture, Commands, Conventions, Common Mistakes, Testing
+      - Keep it under 80 lines. Don't duplicate global `~/CLAUDE.md` instructions.
+
+   c. **If one exists — validate and fortify:**
+      - Detect the current tech stack, project structure, commands, and conventions
+      - Compare each section against current codebase reality
+      - Fix stale information, add missing sections, strengthen weak sections
+      - Preserve user-added content and customizations — never destructively rewrite
+
+#### Phase 1: Preparation
+
+1. **Run the full `/prep` pipeline:**
+
+   a. **Research** — deep codebase exploration scoped to the task:
+      - Read ALL existing `docs/research/`, `docs/context/`, `docs/plans/`, `docs/spikes/`, `docs/incidents/`, `docs/handoff/`, and project CLAUDE.md
+      - Verify findings against actual code (never trust docs blindly — check git log since doc dates, verify key claims)
+      - If docs are stale, update them immediately
+      - Write/update `docs/research/YYYY-MM-DD-<topic>.md`
+
+   b. **Context** — validate and update the repo knowledge snapshot:
+      - Read existing context docs, verify against current state
+      - Update stale sections, add task-specific context
+      - Write/update `docs/context/YYYY-MM-DD-<repo-name>.md`
+
+   c. **Plan** — generate implementation plan with all decisions documented:
+      - **If no task was provided — determine the next priority:**
+        - Check `docs/incidents/` for active incidents (`_Status: ACTIVE_` or `_Status: MITIGATED_`) — these are P1, handle first
+        - Check `docs/plans/` for incomplete plans (`_Status: IN PROGRESS_`) — resume where you left off
+        - Check `docs/spikes/` for in-progress spikes (`_Status: IN PROGRESS_`) — finish what was started
+        - Check `docs/plans/` for pending plans (`_Status: PENDING_`) — execute the oldest one
+        - Check `docs/handoff/` for the most recent handoff — what was the next recommended task?
+        - Check for open TODOs, FIXMEs, or `// TODO` comments in the codebase
+        - Check git log for recent patterns — what's actively being worked on?
+        - Check for failing tests, lint errors, or build issues
+        - Check for open GitHub issues if `gh` CLI is available: `gh issue list --limit 10`
+        - Check `docs/research/` for Open Questions that could be addressed
+        - Check `docs/spikes/` for completed spikes with pending Next Steps
+        - Evaluate: what is the highest-impact task that would move this project forward?
+        - Choose one task, state what you chose and why, then proceed
+      - **If a task was provided,** use it directly
+      - Full benefit of freshly verified research + context
+      - All decisions autonomous with documented rationale
+      - Write `docs/plans/YYYY-MM-DD-<task-slug>.md` with:
+        - `_Status: PENDING_`, `_LastCompletedStep: 0_`, `_TotalSteps: N_`
+        - Steps, Verification Plan, Risks, Execution Journal (empty)
+      - Each step: 2-5 minutes, exact file paths, complete code, verify commands
+
+#### Phase 2: Execution (NO CHECKPOINT — full autopilot means no stopping)
+
+2. **Execute the plan using the `/go` process:**
+
+   a. Mark plan `_Status: IN PROGRESS_`
+
+   b. For each step (respecting `_LastCompletedStep_` for resume):
+      - Dispatch implementer subagent with step details + full context
+      - If Execution Journal has prior failures for this step, include that context
+      - Dispatch spec compliance reviewer — does implementation match plan?
+      - Dispatch code quality reviewer — patterns, architecture, conventions
+      - Fix any issues before moving to next step
+      - Verify independently — run the step's verify command
+      - Update `_LastCompletedStep_` and append to Execution Journal after each step
+
+3. **Full verification after all steps:**
+   - Complete test suite (all must pass)
+   - Linter/formatter (zero errors)
+   - Build (must succeed)
+   - Browser testing if frontend (playwright/chrome MCP)
+   - API testing if backend
+   - Infrastructure dry-run if DevOps
+   - All edge cases and manual checks from the Verification Plan
+
+   If ANY verification fails: diagnose, fix, re-verify. Never skip.
+
+4. **Update artifacts:**
+   - Update `docs/context/` if architecture changed
+   - Mark plan `_Status: COMPLETED_`, add `_Completed: YYYY-MM-DD_` and `_Summary_`
+   - Commit all changes with conventional commit messages
+
+5. **Run `/retro`** — capture learnings from the entire process:
+   - What worked, what didn't, what was surprising across all phases
+   - Auto-update CLAUDE.md, docs/context/, and MEMORY.md with learnings
+   - Write retro to `docs/retros/YYYY-MM-DD-<task-slug>.md`
+   - This closes the feedback loop so future agents benefit
+
+6. **Report:** Full summary of what was researched, decided, planned, implemented, verified, and learned. Include all verification evidence and retro highlights.

package/claude/commands/plans.md

@@ -0,0 +1,88 @@
+## Implementation Plan Generator
+
+Generate a detailed, step-by-step implementation plan based on existing research, context, and codebase understanding. All architectural and implementation decisions are made autonomously with documented rationale.
+
+**Do NOT delegate this command to a subagent.** This is an orchestration command — Opus runs it directly.
+
+### Input
+$ARGUMENTS - task description (e.g., "add webhook support to billing", "refactor sync for 5th machine"). If omitted, autonomously determine the highest priority task.
+
+### Instructions
+
+1. **Read and verify existing documentation:**
+   - Read the project CLAUDE.md if it exists
+   - Read ALL files in `docs/context/` — this is your primary knowledge source
+   - Read ALL files in `docs/research/` — supplementary understanding
+   - Read ALL files in `docs/plans/` — check for existing or related plans
+   - Read ALL files in `docs/spikes/` — leverage settled decisions, don't re-investigate
+   - Read ALL files in `docs/incidents/` — learn from past failures, avoid repeating them
+   - **Staleness check:** For each doc, check its date against recent git history. If relevant files have changed significantly since the doc was written, note which claims need re-verification during code exploration (step 3). Never blindly trust documented claims — verify against actual code for the area you're planning.
+
+2. **If no task was provided — determine the next priority:**
+   - Check `docs/incidents/` for active incidents (`_Status: ACTIVE_` or `_Status: MITIGATED_`) — P1 priority
+   - Check `docs/plans/` for incomplete plans (no `Status: COMPLETED` marker) — continue where you left off
+   - Check `docs/spikes/` for in-progress spikes — finish investigations before starting new work
+   - Check for open TODOs, FIXMEs, or `// TODO` comments in the codebase
+   - Check git log for recent patterns — what's actively being worked on?
+   - Check for failing tests, lint errors, or build issues
+   - Check for open GitHub issues if `gh` CLI is available: `gh issue list --limit 10`
+   - Check `docs/research/` for Open Questions that could be addressed
+   - Check `docs/spikes/` for completed spikes with pending Next Steps
+   - Evaluate: what is the highest-impact task that would move this project forward?
+   - Choose one task, state what you chose and why, then proceed as if it was provided as input
+
+3. **Targeted code exploration** for the specific area the task touches:
+   - Read function bodies, not just signatures
+   - Follow imports to understand real dependencies
+   - Check existing tests for the area being changed
+   - Look at recent git history on key files for "why" context
+   - Use parallel Explore subagents for independent areas
+
+4. **Make all decisions autonomously.** Choose libraries, patterns, file structure, naming, error handling — and document WHY for each non-obvious choice. Use current best practices and standards. Do not ask — decide and document.
+
+5. **Write the plan** to `docs/plans/YYYY-MM-DD-<task-slug>.md`:
+
+   ```markdown
+   # Plan: <Task>
+   _Date: YYYY-MM-DD_
+   _Status: PENDING_
+   _LastCompletedStep: 0_
+   _TotalSteps: N_
+   _Context: docs/context/<file>.md_
+   _Research: docs/research/<file>.md (if applicable)_
+
+   ## Goal
+   What this plan accomplishes in 1-2 sentences.
+
+   ## Decisions & Rationale
+   Every non-obvious choice made, with reasoning. (Libraries, patterns, file structure, naming, error handling, approach.)
+
+   ## Steps
+
+   ### Step 1: [Title]
+   - **File:** `exact/path/to/file`
+   - **What:** Specific change description with enough detail for an agent with zero context
+   - **Why:** Reasoning if non-obvious
+   - **Code:** Complete code to write (not "add validation" — show the actual code)
+   - **Verify:** Exact command to confirm this step worked and expected output
+
+   ### Step 2: ...
+
+   ## Verification Plan
+   - [ ] Tests to run (unit, e2e, integration — exact commands)
+   - [ ] Lint/build commands (exact commands)
+   - [ ] Manual checks (browser, API, CLI — exact steps)
+   - [ ] Edge cases to validate
+
+   ## Risks
+   Known risks and mitigation for each.
+
+   ## Execution Journal
+   _Populated by `/go` during execution. Do not fill in manually._
+   ```
+
+6. **Plan granularity:** Each step should be 2-5 minutes of work. One action per step. If a step has substeps, break it into multiple steps.
+
+7. **Do NOT execute anything.** This command produces plans only.
+
+8. Report the file path and a brief summary of the plan (goal, number of steps, key decisions made).

package/claude/commands/pr.md

@@ -0,0 +1,41 @@
+## Commit, Push & Create PR
+
+**IMPORTANT: Immediately delegate this entire task to a subagent using the Agent tool with `model: "sonnet"` and `subagent_type: "general-purpose"`.** Do not perform any git operations yourself. Pass the full prompt below to the subagent and relay its result.
+
+### Subagent prompt
+
+You are performing the full commit-to-PR flow. Follow these steps exactly:
+
+1. Run in parallel:
+   - `git status --short` to see all changes
+   - `git diff` and `git diff --staged` to see what changed
+   - `git log --oneline -10` to match commit message style
+   - `git branch --show-current` to get the current branch
+
+2. If on `main` or `master`, create a feature branch first:
+   - Infer a branch name from the changes (e.g., `feat/add-commit-commands`)
+   - Run `git checkout -b <branch>`
+
+3. Review the changes:
+   - Never stage files that look like secrets (.env, credentials, tokens, keys)
+   - If there are no changes to commit, say so and stop
+
+4. Stage the appropriate files:
+   - If all changes are related, stage them all with specific file paths (not `git add -A`)
+   - If changes span unrelated concerns, stage only the coherent set and note what was left out
+
+5. Write a conventional commit message:
+   - Use the project's commit style from git log (feat:, fix:, chore:, refactor:, docs:, test:)
+   - Summarize the "why" not the "what" — 1-2 sentences max
+   - Use a HEREDOC: `git commit -m "$(cat <<'EOF' ... EOF)"`
+
+6. Push to remote:
+   - Use `git push -u origin <branch>` to ensure tracking is set
+   - Never force push
+
+7. Create a PR using `gh pr create`:
+   - Clear title under 70 chars
+   - Body with `## Summary` (bullet points) and `## Test Plan` (verification steps)
+   - Use a HEREDOC for the body to preserve formatting
+
+8. Report: the commit hash, branch name, and PR URL

package/claude/commands/prep.md

@@ -0,0 +1,132 @@
+## Full Preparation Pipeline
+
+Orchestrate deep research, context validation, and implementation planning in a single session. This replaces built-in plan mode with unrestricted tool access and persistent documentation artifacts.
+
+The goal is to set Claude up for maximum autonomous execution — thorough understanding, verified context, and a concrete plan with all decisions made and documented.
+
+**Do NOT delegate this command to a subagent.** This is an orchestration command — Opus runs it directly.
+
+### Input
+$ARGUMENTS - task description (e.g., "add webhook support to billing", "refactor the sync system")
+
+### Instructions
+
+Execute these three phases in order, carrying all context forward between phases.
+
+#### Phase 1: Research
+
+1. **Read ALL existing documentation first:**
+   - Project CLAUDE.md
+   - ALL files in `docs/research/`
+   - ALL files in `docs/context/`
+   - ALL files in `docs/plans/` (for awareness of past/in-progress work)
+   - ALL files in `docs/spikes/` (for settled decisions — don't re-investigate)
+   - ALL files in `docs/incidents/` (for past failures and their fixes)
+   - MEMORY.md if accessible
+
+2. **Deep codebase exploration** scoped to the task, using parallel Explore subagents:
+   - Trace data flow end-to-end for the area being changed
+   - Read function bodies, not just signatures
+   - Follow imports to understand real dependencies
+   - Check tests to understand intended behavior and edge cases
+   - Look at recent git history on key files for "why" context
+
+3. **Verify ALL findings against actual code — this is non-negotiable.** The value of this system depends on docs being accurate.
+   - Never trust documentation blindly. If a research doc says X but the code shows Y, the code is truth.
+   - Check git log since each doc's date — have relevant files changed?
+   - Run commands to verify documented build/test/lint instructions still work
+   - Every claim carried forward must be verified against current reality, not copied from a previous doc
+   - If a doc is stale, update it immediately as part of this phase
+
+4. **Write or update** `docs/research/YYYY-MM-DD-<topic>.md` with findings. If an existing research doc covers this area, update it rather than creating a duplicate. Use the same format as `/research`:
+
+   ```markdown
+   # Research: <Topic>
+   _Date: YYYY-MM-DD_
+
+   ## Overview
+   ## Architecture
+   ## Data Flow
+   ## Patterns & Conventions
+   ## Dependencies
+   ## Gotchas
+   ## Open Questions
+   ```
+
+#### Phase 2: Context
+
+5. **Validate and update the repo context snapshot.** If `docs/context/` has an existing context doc:
+   - Read it fully
+   - Verify key claims against current repo state
+   - Update any stale sections
+   - Add task-specific context from Phase 1 that future agents will need
+
+   If no context doc exists, create one following the `/context` format:
+
+   ```markdown
+   # Context: <Repo Name>
+   _Last updated: YYYY-MM-DD_
+   _Machine: <hostname>_
+   _Platform: <macOS/Linux/WSL>_
+
+   ## Overview
+   ## Tech Stack
+   ## Project Structure
+   ## Architecture
+   ## Development Workflow
+   ## Testing
+   ## Dependencies
+   ## Environment
+   ## Recent Trajectory
+   ## Gotchas
+   ```
+
+#### Phase 3: Plan
+
+6. **Generate the implementation plan** with the full benefit of freshly verified research and context. Make all architectural and implementation decisions autonomously. Document rationale for every non-obvious choice.
+
+7. **Write** `docs/plans/YYYY-MM-DD-<task-slug>.md`:
+
+   ```markdown
+   # Plan: <Task>
+   _Date: YYYY-MM-DD_
+   _Status: PENDING_
+   _LastCompletedStep: 0_
+   _TotalSteps: N_
+   _Context: docs/context/<file>.md_
+   _Research: docs/research/<file>.md_
+
+   ## Goal
+   What this plan accomplishes in 1-2 sentences.
+
+   ## Decisions & Rationale
+   Every non-obvious choice, with reasoning.
+
+   ## Steps
+   ### Step 1: [Title]
+   - **File:** `exact/path/to/file`
+   - **What:** Specific change description
+   - **Why:** Reasoning if non-obvious
+   - **Code:** Complete code to write
+   - **Verify:** Exact command and expected output
+
+   ## Verification Plan
+   - [ ] Tests, lint, build, manual checks — exact commands
+
+   ## Risks
+   Known risks and mitigation.
+
+   ## Execution Journal
+   _Populated by `/go` during execution. Do not fill in manually._
+   ```
+
+   Each step: 2-5 minutes, one action, concrete enough for a zero-context subagent.
+
+#### Report
+
+8. **Output all three file paths** and a summary:
+   - Research: what was learned or updated
+   - Context: what was captured or changed
+   - Plan: goal, number of steps, key decisions
+
+   The plan is now ready for `/go` to execute.