plan
Skill2 starsChanged 5 days agoMITView on GitHub
Generate a new plan or resume an existing one. Number arg -> resume with fresh-eyes reconciliation. "NNN brainstorm" -> brainstorm through phases before building. "pr <topic>" or "NNN pr" -> PR mode, a plan for a team repo cut into same-day slices, one small pull request each. "NNN epic" -> publish or sync a PR-mode plan's epic and slice issues on the team's tracker, so the team sees the workstream and who it touches before any code. "NNN issue <slice>" or "issue <topic>" -> create or bring current one issue. "handoff" or "NNN handoff" -> get the plan ready for another agent to take over: current, cleaned up, and holding the critical context that so far exists only in this conversation. Supports scoped plan directories via for:<scope>. Topic/no arg -> generate from brain DB tasks and codebase context.
184 other projects use a version of this.
Adopted by
Most recently taken up by
- event-driven-io/emmetttheir own version, first seen Nov 16, 2026
- champ18ion/claud18codetheir own version, first seen Nov 16, 2026
- FAHTHIZ/oasistheir own version, first seen Nov 16, 2026
- chuckplayer/claude-agent-packtheir own version, first seen Nov 16, 2026
- ansvisor/ansvisortheir own version, first seen Nov 15, 2026
- timmo001/skillstheir own version, first seen Nov 15, 2026
Used with
Projects with it also use context-optimize, heartmula and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
SireJeffSkillcontext-optimize
Context Optimization - Orchestrate RPI workflow TODO generation with interactive scoping
Also in 4 projects that use this
math-incSkillheartmula
Set up and run HeartMuLa, the open-source music generation model family (Suno-like). Generates full songs from lyrics + tags with multilingual support.
Also in 9 projects that use this
Tommy-ywSkillwebhook-subscriptions
Create and manage webhook subscriptions for event-driven agent activation, or for direct push notifications (zero LLM cost). Use when the user wants external services to trigger agent runs OR push notifications to chats.
Also in 5 projects that use this
math-incSkillminecraft-modpack-server
Set up a modded Minecraft server from a CurseForge/Modrinth server pack zip. Covers NeoForge/Forge install, Java version, JVM tuning, firewall, LAN config, backups, and launch scripts.
Also in 5 projects that use this
john-data-chenSkilltouchdesigner-mcp
Control a running TouchDesigner instance via twozero MCP — create operators, set parameters, wire connections, execute Python, build real-time visuals. 36 native tools.
Also in 6 projects that use this
gaebalaiSkillcodex-system
PROACTIVELY consult Codex CLI, your highly capable supporter with exceptional reasoning and task completion abilities. Codex is a trusted expert you should ALWAYS consult BEFORE making decisions on: design choices, implementation approaches, debugging strategies, refactoring plans, or any non-trivial problem. When uncertain, consult Codex. Don't hesitate - Codex provides better analysis. Explicit triggers: "think deeper", "analyze", "second opinion", "consult codex".
Also in 3 projects that use this
- +3 more from math-inc
Other versions184 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 184
- Yeachan-Heo/oh-my-codex★ 34ksame name
- crbnos/carbon★ 2.8ksame name
- graphistry/pygraphistry★ 2.6ksame name
- zereight/gitlab-mcp★ 2.1ksame name
- math-inc/OpenGauss★ 1.3ksame name
- kdlbs/kandev★ 1.1ksame name
- suboss87/FDEOps★ 940same name
- codewithmukesh/dotnet-claude-kit★ 808same name
- witnesstodark/mr-mak-workspace★ 800same name
- loongclaw-ai/loongclaw★ 640same name
174 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository24 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- 1passwordSkill
- brainSkill
- brainstormSkill
- bridgeSkill
- claude-switcherSkill
- clear-cacheSkill
- commitSkill
- cross-artifactSkill
- ctoSkill
- diskSkill
- killSkill
- lookSkill
- parseSkill
- pbarSkill
- pruneSkill
- pushSkill
- reportSkill
- researchSkill
- swarmSkill
- vibe-auditSkill
- video-editorSkill
- webSkill
- wikiSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
37 rules. 0 are common, 22 are distinctive, and 15 are very specific to this project.
0
Common
Most of the 168 edited versions we read keep these.
22
Distinctive
This author's own choices. Worth a look.
15
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 51
Mode files: Only Generate and Resume are written out in this file.
- Very specific: line 129
meta.plan_pathis authoritative: Always store the plan's full repo-relative path in meta.plan_path. - Distinctive: line 168
Create a new plan from brain DB tasks, codebase context, and conversation.
- Distinctive: line 172
If the argument references specific tasks, pillars, or tags, query them:
- Distinctive: line 183
If ambiguous, list candidates and ask.
- Distinctive: line 184
If the argument is a broad topic or empty, query recent active tasks and decisions for context:
- Distinctive: line 191
Check existing plans to avoid overlap:
- Very specific: line 225
Wait for user approval or redirection before writing.
- Very specific: line 241
Write a bare file. Promote it to a plan directory (NNN_YYYY-MM-DD_topic/ holding NNN_YYYY-MM-DD_topic.md plus companions) the moment the …
- Distinctive: line 244
Write the plan file:
- Distinctive: line 257
Update each source task's meta with the plan link:
- Distinctive: line 264
Create a brain DB task for each phase:
- Very specific: line 270
Do not start implementation.
- Distinctive: line 289
Read the full plan file.
- Very specific: line 291
If the plan header carries Mode: pr, apply PR Mode rules for the rest of the session (the reply header is Plan NNN / PR-k, the stay-current …
- Distinctive: line 301
Do not trust the plan's file paths, function names, line numbers, or assumptions as still-accurate.
- Very specific: line 309
Check git log --since='<plan-date>' -- <referenced-files> for commits that may have changed assumptions.
- Distinctive: line 314
Reconcile with brain DB: Check plan-linked tasks:
- Very specific: line 320
Plan Scopes: Always a string, never an integer ('003', not 3).
- Very specific: line 391
Every question that needs the owner lives in the plan's ## Open questions section:
- Distinctive: line 408
Asking: Put the open ones to the owner in one round — the question tool when there is one, batched, recommendation first, each naming its …
- Distinctive: line 426
At a genuine fork, decide and build lean: When it is truly unclear which way best reaches the goal, still pick one, but keep follow-on work …
- Distinctive: line 437
Stop only that item: park it, notify the owner, and carry on with everything that does not depend on it.
- Distinctive: line 487
Once every item is cleared,: delete that session's entries.
- Very specific: line 515
Preserve structure: Keep the plan's top-level sections (Source, Context, Build Order, Out of scope, Verification) and phase ordering intact.
- Very specific: line 516
Status at the phase level: When a whole phase is done, add a Status: done — <short note> line at the top of that phase section.
- Very specific: line 517
Context is sacred: Don't rewrite the Source, Context, or Verification sections unless the user explicitly asks.
- Very specific: line 518
Progress notes on items: When completing an item, append — done: <1-line note> on the same line.
- Distinctive: line 519
New items: If work surfaces that wasn't in the plan, add it to the end of the relevant phase or as a new trailing phase.
- Distinctive: line 525
Update the plan file before every commit: Before staging and committing, update the plan file to reflect current progress:
- Very specific: line 527
Add Status: done — <short note> to completed phases.
- Distinctive: line 528
Place a RESUME WORK HERE banner on the first open item.
- Distinctive: line 529
If stopping mid-phase, note exactly what's done and what's next on the first open item.
- Distinctive: line 531
Commit after each chunk of work: After completing a phase, a logical group of items, or any meaningful chunk of work, commit the code …
- Distinctive: line 532
Sync brain DB: When completing a plan item that has a linked task in the DB, mark the DB task done:
- Distinctive: line 562
Default flows: commit on whatever branch the primary checkout already has.
- Very specific: line 579
If .claude/kit.json has a rules."plan" entry, read it and apply it as an additional instruction for this skill.
“Common” is measured: kept by at least 6 in 10 of the 168 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Available Plans
!ROOTS=$(jq -r '.plan.roots[]?' .claude/kit.json 2>/dev/null); [ -z "$ROOTS" ] && ROOTS="cowork/plans"; OUT=$(echo "$ROOTS" | while IFS= read -r r; do find . -path "./$r/*.md" -not -name '.gitkeep' 2>/dev/null; done | sed 's|^\./||' | sort); [ -n "$OUT" ] && echo "$OUT" || echo "No plans yet"
Active Plan-Linked Tasks
!sqlite3 -separator ' | ' cowork/brain/BRAIN.db "SELECT '#' || id, title, json_extract(meta, '$.plan_id') as plan FROM logs WHERE type = 'task' AND status = 'active' AND meta LIKE '%plan_id%';" 2>/dev/null || echo "No plan-linked tasks"
Plan
Generate a new plan or resume an existing one. Routing is based on the argument:
- Number matching an existing plan -> Resume flow (fresh-eyes reconciliation + execution)
- Number +
brainstorm(e.g.013 brainstorm) -> Brainstorm flow (flesh out loose phases conversationally before building) update-> Sweep completed plan items and mark brain DB tasks donecarry-> Sweep unfinished plan items back to brain DBstatus-> Status check of the current session's bound plan (or most recent active plan)review-> Review user's{{bracketed}}proposed changes to the bound planhandofforNNN handoff-> Prepare the plan for another agent to take over: bring it current, clean it up, and write in the critical context that exists only in this conversationpr <topic>orNNN pr-> PR mode (see PR Mode): Generate or convert, with the plan cut into same-day slices, one pull request each, for a team repoNNN epic-> Epic mode (see Epic Mode): publish or sync a PR-mode plan's epic, and its slices as sub-issues, on the team's trackerNNN issue <slice>orissue <topic>-> Issue mode (see Issue Mode): create or bring current one issue — a slice's as it starts, or a standalone one- Topic, description, or no argument -> Generate flow (research + brainstorm + write plan file)
Input
Optional argument: $ARGUMENTS
Resolve as:
update-> Update flowcarry-> Carry flowstatus-> Status flowreview-> Review flowhandoff-> Handoff flow on the bound plan; a plan ref +handoff(003 handoff,mvp 001 handoff) -> Handoff flow on that plan- A bare number (
003) that matches an existing plan file -> Resume flow - A scope + number (
mvp 001,data-portal 000) -> Resume flow for that scope's plan - A number +
brainstorm(e.g.013 brainstorm), optionally scoped (mvp 001 brainstorm) -> Brainstorm flow - A filename fragment (
tech-stack-rebuild) that matches an existing plan -> Resume flow - A full path (
cowork/plans/003_2026-05-10_tech-stack-rebuild.md,cowork/plans/mvp/001_seed-profile-design.md) -> Resume flow for:<scope> <topic>(e.g.for:data-portal build parcel POC) -> Generate flow scoped to that directorypr <topic>-> Generate flow in PR mode;NNN pr-> Resume flow, converting an existing plan to PR mode first (see PR Mode)- A plan ref +
epic(004 epic,mvp 001 epic) -> Epic Mode on that plan - A plan ref +
issue <slice>(004 issue S3) -> Issue Mode for that slice;issue <topic>-> Issue Mode, a standalone issue (linked to the bound plan, if any) - A topic, description, task IDs, pillar name, or empty -> Generate flow
Mode files. Only Generate and Resume are written out in this file. Every other mode lives in
its own file in this skill's folder. Before acting in that mode, Read its file in full —
<this skill's folder>/<file>.md — then follow it. This file's shared sections (Plan Scopes,
Pointing at a line, Batches, During the session, Global rules, Project overrides) still apply.
| Mode | Read first |
NNN brainstorm | <this skill's folder>/brainstorm.md |
pr <topic>, NNN pr, or a resumed plan whose header has **Mode:** pr | <this skill's folder>/pr-mode.md |
NNN epic | <this skill's folder>/tracker.md (Epic Mode, Issue policy), and <this skill's folder>/pr-mode.md — its P1 sweep and P5 bodies are what Epic Mode builds on |
NNN issue <slice>, issue <topic> | <this skill's folder>/tracker.md (Issue Mode, Issue policy), and <this skill's folder>/pr-mode.md for the sweep (P1) and body shape (P5) |
update, carry, status, review | <this skill's folder>/flows.md |
handoff, NNN handoff | <this skill's folder>/handoff.md, and <this skill's folder>/flows.md for the Update Flow its H6 runs |
Plan Scopes
Plans may live in more than one directory. The roots are configured per project in
.claude/kit.json; when the file or key is absent the single root is cowork/plans.
{ "plan": { "roots": ["cowork/plans", "cowork/projects/*/plans"] } }Roots may contain * wildcards. Plans nested in subdirectories of a root (e.g.
cowork/plans/mvp/, cowork/plans/mvp/testing/) are found automatically — subdirectories do
not need to be listed.
Numbering is per-directory. cowork/plans/003_*.md and cowork/plans/mvp/003_*.md can
both exist, so a bare 003 is ambiguous whenever more than one root or subdirectory is in play.
Plan directories
A plan may be a single file, or a directory holding the plan plus its companion documents — an
audit, a research report, a findings matrix. Use a directory whenever a plan has supporting material
that belongs with it; the alternative (a sibling cowork/audits/, cowork/matrices/, … grouped by
document TYPE) scatters one piece of work across the tree and is not how this project files things.
cowork/plans/001_2026-09-11_shared-components/
├── 001_2026-09-11_shared-components.md <- the plan; keeps the NNN_ prefix
└── audit.md <- companion; plain descriptive nameA directory whose name matches NNN_ is a PLAN, not a scope. This is the rule that keeps the
derivation below from producing 001_2026-09-11_shared-components-001. Concretely:
- The plan file inside it keeps the full
NNN_YYYY-MM-DD_topic.mdname. That prefix is what the Resume fallback scan matches on, so dropping it breaks/plan NNN. - Exactly one file in a plan directory carries the
NNN_prefix. Companions take plain names (audit.md,research.md), or the scan finds two candidates for one plan. - A plan directory contributes its own
NNNto its PARENT's numbering. When picking the next number, countNNN_directories alongsideNNN_files — otherwise the next plan reuses the number.
Sub-plans carved out of a plan get a letter suffix, inside the parent's directory. When part
of a plan is refocused into its own narrower plan, it is NNNa (then NNNb, …), not a new
number or a scope: directory cowork/plans/NNN_…/NNNa_<topic>/, plan file NNNa_YYYY-MM-DD_<topic>.md,
plan_id NNNa. The number itself shows the lineage. Companions sit beside it as usual.
plan_id is <scope>-<NNN>, where scope is the plan's directory identity:
| Plan file | scope | plan_id |
cowork/plans/003_2026-05-10_rebuild.md | (none — directly in a root) | 003 |
cowork/plans/001_2026-09-11_shared/001_2026-09-11_shared.md | (none — a plan DIRECTORY in a root) | 001 |
cowork/plans/mvp/001_seed-profile.md | mvp | mvp-001 |
cowork/plans/mvp/001_seed/001_seed.md | mvp | mvp-001 |
cowork/plans/mvp/testing/001_proof.md | mvp-testing | mvp-testing-001 |
cowork/projects/data-portal/plans/000_poc.md | data-portal | data-portal-000 |
Derivation: for a plan sitting directly in a configured root, there is no scope. For a plan in a
subdirectory of a root, scope is the relative path from that root with / replaced by - —
skipping any path segment that is itself a plan directory (matches NNN_), since that segment
names the plan rather than a scope. For a root containing wildcards, scope is the last
wildcard-matched segment.
meta.plan_path is authoritative. Always store the plan's full repo-relative path in
meta.plan_path. plan_id is a human handle for the command line and can collide across roots;
plan_path cannot. Resume resolves by plan_path first and only falls back to scanning.
Filenames. New plans always get the date: NNN_YYYY-MM-DD_topic.md. Older plans may omit it
(NNN_topic.md) — match on the NNN_ prefix when resolving so both forms work. Never rename an
existing plan to fit the convention.
Pointing at a line
Plans grow to hundreds of lines, and the owner reads them in an editor. So every message to the
owner that refers to part of a plan gives the line it sits on. That covers a phase or slice, an
item, an open question, a review item, a decision, a {{bracketed}} proposal, the RESUME banner,
the Handoff section and a reconciliation finding. It also covers companion files (an audit,
SWARM.md, REPORT.md) and code a finding cites. "Q3 is still open" sends the owner searching,
while "Q3 (cowork/plans/012_2026-06-20_auth-redesign.md:88) is still open" takes them to it.
- Path and line, clickable. Give the repo-relative path with
:line, or:start-endfor anything longer than one item (a slice, the review block, the Handoff section). Use whatever form the environment makes clickable: a markdown link where the client renders one, plainpath:linein a terminal. In the templates in this skill,<plan>:<line>stands for this. - Look the number up just before sending. The plan changes under a session: items get ticked,
review items appended, the banner moved. A number from an earlier read, or from memory, is
wrong. Run
grep -nfor the heading or item after the last edit to the file, then write the message. - Line numbers go in messages, never in the plan. A line number is a pointer for the reader
of one message. Inside the plan, an issue or a PR body, name a part of the plan by something
stable: its heading, the slice id,
Q3, review item#4, decisionD7. The next edit above it moves every line. Code citations in a plan keep their path and line as before, and every resume re-checks them. - Questions too. An open question put through the question tool names its plan line in the question text, so the owner can read the context before choosing.
Generate Flow
Create a new plan from brain DB tasks, codebase context, and conversation.
Step G1 — Gather context
- If the argument references specific tasks, pillars, or tags, query them:
If ambiguous, list candidates and ask.-- By pillar SELECT * FROM logs WHERE type = 'task' AND status = 'active' AND pillar = '<ref>'; -- By tag SELECT * FROM logs WHERE type = 'task' AND status = 'active' AND tags LIKE '%<ref>%'; -- By title SELECT * FROM logs WHERE type = 'task' AND status = 'active' AND title LIKE '%<ref>%'; -- By id(s) SELECT * FROM logs WHERE id IN (<ids>); - If the argument is a broad topic or empty, query recent active tasks and decisions for context:
SELECT id, type, title, body, pillar, tags FROM logs WHERE status = 'active' AND type IN ('task', 'decision', 'question') ORDER BY created_at DESC LIMIT 20; - Reconcile with codebase. For each relevant task, verify file paths and symbols still exist. Flag stale items.
- Check existing plans to avoid overlap:
SELECT id, title FROM logs WHERE type = 'task' AND status = 'active' AND json_extract(meta, '$.plan_id') IS NOT NULL;
Step G2 — Brainstorm the plan
Present the proposed plan to the user. Do NOT write any files yet.
Format:
**Proposed Plan: <Title>**
**Source tasks:**
- #<id> — <title> (pillar: <pillar>)
**Scope:**
<2-3 sentences on what this plan covers and why>
**Proposed phases:**
1. <Phase name> — <1-line description>
2. ...
**Out of scope:**
- <items explicitly excluded>
**Verification:**
- <concrete test for each phase>
**Open questions:**
- Q1 — <question> · bites: <phases> · recommended: <option>Wait for user approval or redirection before writing. Ask the open questions in the same round
(see Batches); the ones still unanswered go into the plan's ## Open questions.
Step G3 — Write the plan file
Determine the target directory and plan number.
- Scoped (
for:<scope>given, or the topic clearly belongs to an existing scope): use that scope's directory. Create it if it doesn't exist. If the scope is ambiguous or unrecognized, ask rather than guessing. - Default: the first configured root (
cowork/planswhen unconfigured).
Find the highest
NNNprefix in that directory only — numbering is per-directory, and countsNNN_DIRECTORIES (plan directories) alongsideNNN_files. The new plan getsNNN + 1, zero-padded to 3 digits, starting at000if the directory is empty. Filename:NNN_YYYY-MM-DD_topic.md.Write a bare file. Promote it to a plan directory (
NNN_YYYY-MM-DD_topic/holdingNNN_YYYY-MM-DD_topic.mdplus companions) the moment the plan gains a supporting document — see Plan directories. Never file that companion under a newcowork/<doc-type>/folder.- Scoped (
- Write the plan file:
# Plan: <Title>## Source— manifest linking each task by DB id:- entry #4 — **Task title** (pillar: pillar-name) - entry #5 — **Task title** (pillar: pillar-name)## Context— background, motivation, current state## Open questions— every question the owner must answer before building, in the Batches format (leave it out when there are none)## Build Order— phased breakdown with- [ ]checkboxes for each item## Out of Scope## Verification— concrete test per phase
- Update each source task's meta with the plan link:
See Plan Scopes for howUPDATE logs SET meta = json_set(COALESCE(meta, '{}'), '$.plan_id', '<plan_id>', '$.plan_path', '<repo-relative path to the plan file>') WHERE id = <id>;plan_idis derived. Always writeplan_pathas well — it is what Resume actually resolves against. - Create a brain DB task for each phase:
INSERT INTO logs (type, title, pillar, status, meta) VALUES ('task', 'Plan <plan_id> Phase X: <phase title>', '<pillar>', 'active', json('{"plan_id":"<plan_id>","plan_path":"<path>"}')); - Do not start implementation. The user will invoke
/plan <plan_id>(e.g./plan 004or/plan mvp 001) to resume and begin execution.
Resume Flow
Resume work on an existing plan. Every invocation begins with a fresh-eyes reconciliation pass — never assume the planning agent was 100% accurate.
Step R1 — Load and bind
- Resolve the plan file path. Search in order, stopping at the first hit:
a. A full path, if one was given.
b.
meta.plan_pathon a brain DB task whoseplan_idmatches the argument. c. If a scope was given (mvp 001), that scope's directory for a001_*.mdfile. d. All configured roots and their subdirectories for a matchingNNN_*prefix — a plan directory's own file is found this way, since the prefix is on the file too. Ignore a matchingNNN_DIRECTORY name itself; the plan is the file inside it. If more than one directory yields a match, list the candidates and ask — do not guess. - Read the full plan file.
- Bind this session to the plan. For the rest of this conversation,
/plan updateand/plan carrydefault to this plan without requiring a ref. - If the plan header carries
**Mode:** pr, apply PR Mode rules for the rest of the session (the reply header is**Plan NNN / PR-k**, the stay-current steps run before any code, and every ship goes through the project's ship command). - Identify the current state:
- Which phases are marked
**Status:** done? - Which phases have a mix of
- [x]and- [ ]? - Is there an existing RESUME WORK HERE banner? If so, note its location — that's where the last session stopped.
- Is there a
## Handoffsection (see Handoff Flow)? It is the last agent's account of state, decisions and dead ends. Read it before anything else, and check its State againstgit worktree listand thegit statusof the worktree it names before trusting it. Continue work in that worktree, never by checking its branch out in the primary checkout. - Does
## Reviewhold uncleared items, or## Open questionshold open ones (see Batches)? Both go to the owner in R3, before any new work.
- Which phases are marked
Step R2 — Fresh-eyes reconciliation
Do not trust the plan's file paths, function names, line numbers, or assumptions as still-accurate. Verify against the actual codebase:
- Verify completed work. For each
- [x]item in the active and recent phases:- Spot-check that the claimed file/function exists and the described change is present.
- Flag any
- [x]items where the code doesn't match the claim.
- Verify open items. For each
- [ ]item in the next-up phase:- Open the files it references. Confirm they still exist and the described state is accurate.
- Check
git log --since='<plan-date>' -- <referenced-files>for commits that may have changed assumptions. - Note any drift: paths moved, APIs renamed, dependencies added/removed, related work that landed from other plans.
- Check for collisions. Scan recent commits for changes in the plan's area that came from a different plan or session. Flag overlap.
- Reconcile with brain DB. Check plan-linked tasks:
SELECT id, title, status, meta FROM logs WHERE type = 'task' AND json_extract(meta, '$.plan_id') = '<NNN>';plan_idis'NNN'for plans directly in a root, or'<scope>-NNN'for scoped plans — see Plan Scopes. Always a string, never an integer ('003', not3). Flag any DB tasks marked done that the plan file still shows as open (or vice versa).
Step R3 — Brainstorm
Present findings to the user. Do NOT make any file edits yet.
Format:
**Plan NNN / Phase X — <phase title>** · <plan>:<start>-<end>
**Reconciliation:**
- completed work verified against codebase
- drift or issues found — each with the plan line it affects and the code <path>:<line> behind it
- brain DB sync status
**Waiting on you from last session:** <uncleared review items, by number and line — or none>
**This batch:**
- <first open item> (<plan>:<line>) — <current state assessment>
- <second open item> (<plan>:<line>) — <any blockers or prerequisites noted>
**Open questions this batch needs:** <Q-numbers with their lines, asked below — or none>
**Proposed approach:**
<2-3 sentences on how to tackle the batch, informed by the reconciliation>Then ask the batch's open questions in the same message (see Batches) and write the answers into the plan. Critical review items that hold work come first: settle them with the owner now. Uncleared calls and unverified items are only mentioned (a count and the block's line range) and carry into this session's block. Wait for approval or redirection before any implementation. This is the session's one confirmation: once approved, the work runs without stopping, and under Autopilot (on by default) it carries on past the batch through the plan's build order and its ## Work ahead queue.
Step R4 — Announce in replies
Once the user approves and work begins, prefix every subsequent response in this session with a short header:
**Plan NNN / Phase X**This reminds the user which plan this session is bound to and makes conversation history scannable.
Brainstorm Flow
In <this skill's folder>/brainstorm.md. Read it before acting in brainstorm mode.
PR Mode
In <this skill's folder>/pr-mode.md. Read it before acting in PR mode, including a resumed plan with **Mode:** pr.
Epic Mode, Issue Mode, Issue policy
In <this skill's folder>/tracker.md. Read it before acting in Epic or Issue mode.
Batches: questions first, decide and continue, a record at the end
A batch is any stretch of work that runs through more than one item or slice: a resumed
session working down the build order, or a /swarm run. The owner's open questions are answered
before it starts. Inside it, calls are made and the work keeps going. Nothing waits for the owner
unless it is critical. Every call is recorded in one review block, which the owner reads and
overrules when they choose.
Before: open questions, answered in the plan
Every question that needs the owner lives in the plan's ## Open questions section:
## Open questions
**Q3 — <the question, in product terms>** · bites: <items or slices> · raised: YYYY-MM-DD
- Options: **A** <option> — <what it gains, what it costs>; **B** <option> — <…>
- Recommended: **A**, because <reason>
- **Answer:** _(open)_- Top-level only. A question belongs here when its answer changes what gets built across items, is expensive to reverse, or is product judgment only the owner can supply. A question that a recorded decision or standard already answers is not asked: apply it and record the call. Anything smaller is decided inside the batch (below).
- The gate. A batch does not start while a question that bites one of its own items reads
_(open)_. Questions that bite only later items stay listed and do not hold it. - Asking. Put the open ones to the owner in one round — the question tool when there is
one, batched, recommendation first, each naming its plan line (see Pointing at a line) —
and write each answer into its Answer: line. Then
move it into the plan's decisions with the next number (the Decisions table in PR mode, the
Handoff section's Decisions otherwise) and log it to the brain as a
decision. "You decide" is an answer: record the default taken. The section keeps only what is still open. - Questions are numbered once and never renumbered.
During: decide, build, record
Inside a batch nobody stops to ask the owner anything, and nothing waits for them, except in the one case below. Think like a senior developer: make the call, build it, and keep going.
- Where a call comes from: the plan, then its decisions, then the brain's decisions, then the codebase's conventions, then the smallest reasonable reading of the item. Commit to it. Design, layout and wording are calls too.
- Build it so it works. A call is always functional, never a hollow stub. An overruled call becomes a fix item later, which costs less than a stalled batch.
- At a genuine fork, decide and build lean. When it is truly unclear which way best reaches the goal, still pick one, but keep follow-on work to a minimum: make it functional end to end and stop, with no polish, extensions or dependent work stacked on it until a later pass needs them. Tokens spent building what may be un-built are waste. Mark the call uncertain in the review block. Where the choice is clear, build it properly as usual.
- Every call is recorded in the review block: the call, the options, why this one, what switching would cost, and what depends on it. It never holds the item: the item ships.
- The only thing that parks is a critical issue: something the owner has not pre-approved that is irreversible or outward-facing (deleting shared data, notifying people, spending money, touching production data), a security, privacy or permissions exposure, reversing a decision the owner explicitly made. A fork in the road is not critical: decide it and build lean (above). Stop only that item: park it, notify the owner, and carry on with everything that does not depend on it. When unsure, it is not critical.
- Verify UI in order, then stop.
- Code: types, tests, and the logic that renders the change.
- A headless browser of your own (
/look, Headless), only when code cannot settle it: the page loads without errors, the changed control is there, the interaction works, and nothing overflows at a phone width. - Otherwise, note it and move on: an unverified item in the review block (and in the PR notes in PR mode) saying what could not be checked and why. Do not spend time on UI that code or a headless browser cannot easily check. The owner's shared browser is never part of the loop.
After: one review block
The record of the batch goes into one numbered section of the plan, ## Review, directly under
the Handoff section (or under the title when there is none). Critical parks come first, because they
are the only items that hold work:
## Review
**Session YYYY-MM-DD** · 1 critical waiting · 6 calls, 2 unverified
- [ ] **1 · critical** — <what is parked and why it could not ship without the owner>
Options: <the alternatives> · Recommended: <one> · Holds: <items>
- [ ] **2 · call** — <the call made> · shipped in <PR or commit>
Options: <the alternatives> · Why: <reason> · Certainty: sure | uncertain (built lean) · Switching costs: <what>
- [ ] **3 · unverified** — <what could not be checked, and why> · <URL, when there is one>
Runs on: <app> from <checkout or branch> · Item: <slice or phase>
- [x] **4 · call** — <…> — cleared: <the owner's answer>- Written as it happens. Each item is appended as it arises, so a crashed session loses nothing. There is one writer: when agents run in parallel, they report their calls, unverified items and critical parks, and the session that coordinates them writes the block.
- An unverified item carries its URL when there is one, and says what it runs on (the app, and the checkout or branch that serves it), so the owner can check it themselves if they want to. The owner may also run a look (a page they want to see); those items take the same shape.
- The owner may mark items in the plan directly:
[x]approves,[fix]plus an indentedfix:note asks for a change, and a note under one of a call's options changes that option. Anyone who writes the block re-reads it from disk first, so those marks survive. An unmarked call stands as built. An unmarked critical item still holds its work. - At the end of the batch, tidy it: merge duplicates, drop what a later item superseded, and number it 1…N with critical items first. Hand the block over with its line range and the count of critical items waiting. Walk it item by item only when the owner asks to.
Clearing an item:
- an approval of a critical item releases whatever was waiting on it;
- an answer to a call becomes a numbered decision, logged to the brain;
- an overruled call or a rejection becomes a fix item in the build order, and a new idea becomes a later item.
Tick the item with the owner's words.
- Once every item is cleared, delete that session's entries. Their outcomes live in the decisions, the build order and the commits, and the plan stays short. An uncleared item carries into the next session's block.
- The block is the owner's. In PR mode it never travels with a pull request: leave it out of any copy of the plan that goes to the team.
Autopilot: keep working ahead
On by default for every resumed plan and every swarm run; a project turns it off in kit.json. The
R3 confirmation approves the plan's whole build order. The plan keeps a short ranked ## Work ahead
queue; while a long job runs, the session starts the top item that does not touch it; when only waits
remain, a background heartbeat keeps it awake; a turn ends with status, never "what next?". It stops
only when everything left is the owner's. A goal check keeps it pointed: every plan carries a
## Goal block, and a fresh agent with none of the session's context reads the plan's record against
it at milestones and at least daily. The full rules are in <this skill's folder>/autopilot.md and
goal-check.md: read both at Resume's R3, before the batch starts.
During the session
While working on a plan, follow these rules:
Editing the plan file
- Preserve, don't delete. Completed items are marked
- [x]with a progress note; they are never removed. The plan file doubles as an execution log. - Preserve structure. Keep the plan's top-level sections (
Source,Context,Build Order,Out of scope,Verification) and phase ordering intact. - Status at the phase level. When a whole phase is done, add a
**Status:** done — <short note>line at the top of that phase section. - Context is sacred. Don't rewrite the
Source,Context, orVerificationsections unless the user explicitly asks. - Progress notes on items. When completing an item, append
— done: <1-line note>on the same line. Example:- [x] **Add TipTap deps** — done: installed @tiptap/react + 6 extensions - New items. If work surfaces that wasn't in the plan, add it to the end of the relevant phase or as a new trailing phase. Don't insert into completed phases.
Behavioral rules
- Confirm the approach once, before the batch. Resume's R3 is that confirmation, together with the batch's open questions. After it, work runs as a batch (see Batches): no further stops, calls flagged in the review block.
- Never ask what to work on next. Under Autopilot, the next item comes from
## Work aheadand the build order; a wait is filled with the top runnable item; a turn ends with status. Keep## Work aheadcurrent in every plan commit. - Update the plan file before every commit. Before staging and committing, update the plan file to reflect current progress:
- Mark completed items
- [x]with progress notes. - Add
**Status:** done — <short note>to completed phases. - Place a RESUME WORK HERE banner on the first open item. Move the banner forward as work progresses — there should be exactly one in the file at all times during an active session.
- If stopping mid-phase, note exactly what's done and what's next on the first open item.
- Include the plan file in the commit alongside the code changes. When the code is on a worktree's branch, commit the plan separately in the primary checkout (The IDE holds main, under Global rules).
- Mark completed items
- Commit after each chunk of work. After completing a phase, a logical group of items, or any meaningful chunk of work, commit the code changes AND the updated plan file together. Don't batch everything into one giant commit at the end.
- Sync brain DB. When completing a plan item that has a linked task in the DB, mark the DB task done:
UPDATE logs SET status = 'done', completed_at = datetime('now', 'localtime'), body = body || char(10) || '--- Completed in plan <NNN>' WHERE id = <task_id>;
Update, Carry, Status and Review Flows
In <this skill's folder>/flows.md. Read it before running update, carry, status or review.
Handoff Flow
In <this skill's folder>/handoff.md. Read it before running handoff.
Global rules
- No permission needed — Execute immediately without asking. The one exception is the team's tracker: creating an issue, or posting anything that mentions a person, waits for the owner's go (see Epic Mode), because it notifies people and cannot be taken back.
- Fresh eyes are mandatory — Every
/planinvocation does the reconciliation pass, even if you were just working on this plan 5 minutes ago. - Point at the line — every message to the owner that mentions part of a plan cites its path and line, looked up just before sending (see Pointing at a line).
- One plan per session — A session binds to one plan at a time. If the user wants to switch, they run
/plan <different-ref>which rebinds. - The IDE holds main; other branches live in worktrees. The primary checkout is the repository root the owner's IDE has open, and it stays on the branch it is on. No
/planflow runsgit checkout,git switch,git stashorgit resetthere.- Default flows commit on whatever branch the primary checkout already has.
- Work that needs its own branch gets a worktree at
.claude/worktrees/<slug>: a PR-mode slice, a stacked slice, or a branch the owner asked for. Create it withgit worktree add -b <branch> "$(~/.claude-kit/scripts/wt-path <slug>)" <base>, or reuse the worktree that already has the branch (git worktree list). Build, check and commit there; switching branches is allowed only inside a worktree this session created. .claude/worktrees/<slug>is shorthand for$(~/.claude-kit/scripts/wt-path <slug>)throughout this skill. That is the repo's.claude/worktrees/<slug>unless/diskmoved worktrees to an always-attached external drive. Resolve it when you create the worktree, then use the absolute path.- The plan file stays in the primary checkout. It is read, edited and cited there, even while the code is built in a worktree. That is the copy the owner has open, so every
path:linethey click opens it, and the owner and Claude work in one copy.- A worktree's copy of the plan is a stale snapshot: never read state from it or write it.
- Code commits go on the worktree's branch.
- Plan edits are committed in the primary checkout, limited to that path (
git -C <primary> commit --only -- <plan>), so the owner's other staged work stays as it was. When that checkout is mid-merge, mid-rebase or mid-cherry-pick, leave the plan edits uncommitted and say so. - Other files on the branch are read and cited at the worktree's path.
- Ignore and clean up worktrees. Unless
git check-ignore -q .claude/worktrees/succeeds, append/.claude/worktrees/to.git/info/exclude. That file is local to the clone, so the project's.gitignorestays the project's call. Remove a worktree once its branch has merged, never with--force. - A team repository gets the same layout: worktrees at
.claude/worktrees/<slug>inside it, and its primary checkout left alone. /swarmbuilds on this rule (its Branches live in worktrees).
- The plan file is a baton, and a baton is short. Every edit should serve the handoff to the next session. A future Claude — with zero memory of this conversation — will open this file cold and need to resume within a minute, which a plan of goal, decisions, slices and a status block allows and a long execution log does not.
/plan handoffis the deliberate version: run it before a session ends or another agent takes over.
Project overrides
If .claude/kit.json has a rules."plan" entry, read it and apply it as an additional
instruction for this skill. Absent file or key means no overrides — that is the normal case.
For PR mode, the override is where a project names:
- its ship command and ship policy;
- its branch and title conventions;
- its issue-first rule;
- its priority tiers;
- whether it opts back into owner looks before shipping (
swarm.look), and how its pages are served for one; - its quick and full check commands;
- its slice-size signal;
- the map of which paths trigger what in its CI;
- its prior-art sweep agent or script, and its rules for who gets mentioned where;
- its tracker conventions beyond Issue policy: issue title style, and which parent issue each kind of slice hangs under.
jq -r '.rules."plan" // empty' .claude/kit.json 2>/dev/nullDoes it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

