plan

# File-Based Task Plan ## Default: Use Platform Planning Unless explicitly requested ("create a plan.md", "use the plan template"), prefer your AI platform's built-in planning. This file-based approach is only justified for multi-session or handoff work. ## Use When - User explicitly requests it - Work spans multiple sessions / context resets - Handoff to another AI or human - Complex multi-PR coordination ## Setup 1. Copy template → `plans/[task_name]/plan.md` 2. Replace `[placeholders]` 3. Fill Context sections 4. Mark Step 1 `🔄` 5. For multiple checkouts, record the absolute plan path, each worktree root, and base/head SHAs. Link existing handoff plans and preserve completed work; append to shared plans without overwriting concurrent updates. ⚠️ **gitignore**: `plans/` is local only — never commit unless user explicitly requests (`git add -f`). ## Writing Style Terse but recoverable — every token earns its place, but a cold-start agent with zero context must still understand and resume. Abbreviate, omit filler. Test: would a stranger understand this with no other context? If yes, cut further. If no, add the minimum needed. Emoji: only use where it saves characters or adds clarity not already present in the text (e.g. status icons replace words, ⚠️ flags a genuine warning). Do not add emoji just to have them — if removing one loses nothing, remove it. ## Critical Meta-Goals This plan MUST be: 1. **Self-describing** — all context to resume is IN THIS FILE and files it points to 2. **Write before run** — record planned action in file *before* executing 3. **Update before continuing** — record results immediately after, *before* next step 4. **Single source of truth** — if not in the plan, it didn't happen 5. **Safe to resume** — any agent can pick up by reading only this file > ⚠️ External memory is unreliable. This file — and files it points to — are your ONLY memory. ## Anti-Drift Protocol ### Three Commandments 1. **RELOAD** before every action — memory wiped, plan is all you have 2. **UPDATE** after every action — unwritten = didn't happen 3. **TRUST ONLY THE PLAN** — not memory, not assumptions ### Rules - 🚫 **No assumptions** — plan is truth - 🚫 **No offroading** — if not in plan, don't do it - **Changing external state**: before a dependent write or resumed step, revalidate issue comments, PR heads/checks, and other changing facts. Record current evidence and reuse verified completed actions instead of repeating stale TODOs. - 🔐 **No secrets** — never write passwords, tokens, API keys, or credentials; use `$ENV_VAR`, `<redacted>`, or pointer to env file (e.g. `source .env.local`) - **Parallel subagents**: before spawning, mark claimed step `🔄(🤖agent_<id>_step_<N>)` and record subagent plan path. Subagents **must NOT edit this file** — main agent updates it from their output. - **Subagent plans**: each subagent has its own full plan at `plans/[task]/subagents/agent_<id>_step_<N>/plan.md`, same protocol. Subordinate to this file. ### Step Protocol Per step: 1. `cat plans/[task]/plan.md | head -200` — reload 2. Find current `🔄` step 3. Write planned action in file first 4. Execute only that step 5. Write results before continuing 6. `tail -50 plans/[task]/plan.md` — verify **Order: write plan → run → write results → continue** ### If Confused STOP → reload plan → find last ✅ step → continue from there ## Plan Template ```markdown # [Task] Plan 🔴 COLD START: reload skill first → `.agents/skills/plan/SKILL.md` File: `plans/[task]/plan.md` | Date: [DATE TZ] | Branch: [branch] | PR#[N] → [target] | Base: [branch @ SHA] ## Context (read-only) **Prompt**: [verbatim user request] **Goal**: [what we're achieving] **Done when**: [success criteria] **Constraints**: [key limits] **Branch**: `[name]` off `[parent]` @ `[SHA]` ## Strategy **Approach**: [high-level plan] **Decisions**: [decision → reason] ## Commands Record ALL commands verbatim — exact flags, paths, env vars. No paraphrasing. No secrets (use `$VAR`, `<redacted>`, or `source .env.local`). Preferred: ```bash cat plans/[task]/plan.md | head -200 # reload plan python -m pytest -q [test_path] # targeted tests ./bin/test-minimal-lite.sh # fast repo sentinel tests ./bin/ruff.sh && ./bin/typecheck.sh # lint + types ./bin/test.sh [optional_test_args] # broader test pass gh pr checks [PR] --watch # CI gh run view [RUN_ID] --json status,conclusion,jobs git log --oneline -10 ``` Add task-specific commands here as discovered. ## Status ⬜ TODO · 🔄 IN_PROGRESS · 🔄(🤖agent_<id>_step_<N>) subagent · ✅ DONE · ❌ FAILED · ⏭️ SKIPPED · 🚧 BLOCKED ## Steps Hierarchical numbering (1, 1.1, 1.1.a …) — insert substeps freely without renumbering siblings. #### Step 1: [Description] 🔄 | Do: [action] | OK: [criteria] ``` $ [exact command] [output] ``` Result: [decisions / errors / next] ##### Step 1.1: [Substep] ⬜ | Do: [action] | OK: [criteria] #### Step 2: [Description] ⬜ | Do: [action] | OK: [criteria] ``` ## Compaction Trigger when plan file exceeds ~500 lines. Target 200–300 lines after compaction. 1. Archive completed steps → `plans/[task]/history/steps<N>-<M>.md` 2. Replace with tight summary: what was done, key decisions, gotchas + pointer to archive 3. Continue numbering from where you left off > 🔴 On context compaction/reset: **reload THIS SKILL FILE first** — before the plan, before code. It governs all execution. Skipping it causes silent drift.