plan
Skill199 starsChanged 2 months agoMITView on GitHub
Create a detailed implementation plan for a feature or task. Use when user wants to plan before coding.
184 other projects use a version of this, 2 of them edited.
Adopted by
Most recently taken up by
- 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
- felipefontoura/claude-sdd-kittheir own version, first seen Nov 15, 2026
Used with
Projects with it also use heartmula, webhook-subscriptions and 6 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.
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
ibahgatSkillcontext-optimize
Improve context efficiency and cache stability for long or complex sessions.
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 · 2
- gaebalai/claude-code-orchestrator★ 1865% same
- ilhae-ai/claude-code-orchestrator★ 1865% same
Wrote their own version · 182
- 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
172 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 repository17 other files it gives its agents.
- .agents/AGENTS.mdAGENTS.md
- AGENTS.mdAGENTS.md
- .codex/AGENTS.mdAGENTS.md
- catchupSkill
- checkpointingSkill
- codex-systemSkill
- context-loaderSkill
- design-trackerSkill
- featureSkill
- initSkill
- research-libSkill
- simplifySkill
- spikeSkill
- tddSkill
- team-executeSkill
- troubleshootSkill
- update-lib-docsSkill
The file
We split this skill into the rules it gives an agent
8 rules. 0 are common, 4 are distinctive, and 4 are very specific to this project.
0
Common
Most of the 168 edited versions we read keep these.
4
Distinctive
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 9
Create an implementation plan for $ARGUMENTS.
- Very specific: line 37
If .claude/docs/plans/{slug}.md already exists, the plan is a revision of that document — read it first and say so, rather than silently …
- Very specific: line 48
Ask, do not assume. Unresolved items belong in ### Open Questions, not in a guessed step.
- Distinctive: line 85
Write the prompt body to a file, then invoke the shared wrapper (the directory is not created by the wrapper before it reads the prompt, so …
- Very specific: line 117
Read the answer from the JSON output's response_file.
- Very specific: line 125
Write the plan to the plan_doc path from step 0 (.claude/docs/plans/{slug}.md) using this shape.
- Distinctive: line 233
Ask questions at planning stage for unclear points
- Distinctive: line 234
Don't over-detail (adjust during implementation)
“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
Create Implementation Plan
Create an implementation plan for $ARGUMENTS.
A plan is a file, not a transcript. The plan produced here is written to a
resolved path, validated against a document contract, reviewed by Codex, and
approved by the user — in that order, and all four. A plan that lives only in
the conversation cannot be handed to /team-execute, cannot survive a
/checkpointing compaction, and cannot be re-read next session.
Planning Process
0. Resolve the Workspace (always first)
Resolve this plan's slug and output path once. The title becomes the file name, so give it a short English descriptor — not the user's raw wording, which the Language Protocol keeps out of paths:
python3 .claude/skills/_shared/workspace.py \
--skill plan --title "<short English title>" --createThe JSON on stdout carries slug and paths.plan_doc
(.claude/docs/plans/{slug}.md). Every {slug} and every output path below —
and the /team-execute handoff in step 6 — MUST come from this JSON verbatim,
never be re-derived by hand: two hand-derived slugs are exactly how a plan and
its executor's work logs drift apart. Exit codes: 0 resolved (and created);
1 bad arguments.
If .claude/docs/plans/{slug}.md already exists, the plan is a revision of that
document — read it first and say so, rather than silently overwriting it.
1. Requirements Analysis
First clarify with the user:
- Purpose: What to achieve
- Scope: What to include, what to exclude
- Constraints: Technical, time, dependencies
Ask, do not assume. Unresolved items belong in ### Open Questions, not in a
guessed step.
2. Current State Investigation
Reading the codebase for a plan is broad-context work: delegate it rather than consuming orchestrator context.
Task tool:
subagent_type: "general-purpose-opus"
prompt: |
Investigate this codebase for a planned change: {purpose from step 1}
Report, with file:line evidence for every claim:
1. Related existing code — which modules already do something similar
2. Files that will need to change, and why each one
3. Libraries and patterns the change should reuse (project conventions)
4. Existing tests that cover the affected area, and gaps in that coverage
5. Constraints or invariants the change must not break
Use Glob, Grep, and Read. Do not implement anything.
Return the findings; do not summarize away the file paths.The returned findings are the source of ### Scope and ### Risks &
Considerations in the plan document. A plan whose Scope names no concrete file
paths is a plan written without reading the code — send the investigation back
rather than proceeding.
3. Break Down Implementation Steps
.claude/rules/codex-delegation.md names "you need a step-by-step
implementation plan" and "design/architecture decisions are involved" as
explicit Codex triggers, so step decomposition is a MANDATORY Codex
consult — the same rule /feature follows for the same artifact class.
Write the prompt body to a file, then invoke the shared wrapper (the directory is not created by the wrapper before it reads the prompt, so create it first):
mkdir -p .claude/logs/codex
# write the prompt body to .claude/logs/codex/prompt-plan-{slug}-steps.md, then:
python3 .claude/skills/_shared/codex_consult.py \
--prompt-file .claude/logs/codex/prompt-plan-{slug}-steps.md \
--label plan-{slug}-steps --sandbox read-onlyPrompt body:
Objective: Decompose this change into an ordered, independently testable implementation plan.
Context:
- Purpose: {purpose from step 1}
- Scope in / out: {from step 1}
- Constraints: {from step 1}
- Current state: {findings from step 2, with file paths}
Constraints:
- Order steps by dependency (what must exist before what)
- Each step is independently testable; name its verification
- Put high-risk and high-uncertainty steps first
- Keep steps small; do not over-detail work that will be re-decided during implementation
Output format:
## Implementation Steps (ordered by dependency)
## Verification per Step
## Risks and Mitigations
## Open QuestionsRead the answer from the JSON output's response_file. Exit codes: 0 the call
succeeded — read response_file; 1 bad args; 2 codex CLI not on PATH; 3
codex exited non-zero or timed out — inspect error and stderr_file before
retrying or escalating. Codex proposes the decomposition; deciding which steps
are the right steps stays yours.
4. Output Format
Write the plan to the plan_doc path from step 0 (.claude/docs/plans/{slug}.md)
using this shape. The five ### sections are the plan-doc document contract —
renaming or dropping one is a validation failure in step 5:
## Implementation Plan: {Title}
### Purpose
{1-2 sentences}
### Scope
- New files: {list}
- Modified files: {list}
- Dependencies: {list}
### Implementation Steps
#### Step 1: {Title}
- [ ] {Specific task}
- [ ] {Specific task}
**Verification**: {Completion criteria for this step}
#### Step 2: {Title}
...
### Risks & Considerations
- {Potential issues and mitigations}
### Open Questions
- {Items to clarify before implementation}5. Completion Gates
A plan is done when all four gates below have passed. They check different things and none of them substitutes for another: the shape gate proves the document has its sections, never that the plan is any good.
Gate 1 — shape. The document contract:
python3 .claude/skills/_shared/validate_doc.py \
--contract plan-doc --file .claude/docs/plans/{slug}.mdExit 0 the required sections are present; 1 bad args or the file is
unreadable; 2 a required section is missing — read sections_missing in the
JSON and add the section. Exit 0 means the plan has the right shape. It says
nothing about whether the steps are correct, complete, or ordered sensibly.
Gate 2 — the artifact exists and is not empty:
python3 .claude/skills/_shared/workspace.py --skill plan --slug {slug} --verifyExit 0 the plan document exists and is non-empty; exit 2 it is missing or
effectively empty — the plan was never written, so do not report a plan.
Gate 3 — adequacy (MANDATORY Codex validation). Same rigour /feature
applies to its implementation plan. Write the body below to
.claude/logs/codex/prompt-plan-{slug}-validate.md and consult with
--sandbox read-only:
Objective: Validate this implementation plan for completeness, correctness, and risk.
Context:
- Purpose and scope: {from step 1}
- Current state: {findings from step 2}
- Implementation plan: contents of .claude/docs/plans/{slug}.md
Constraints:
- Check for missing edge cases or error handling
- Verify the step order is actually dependency-correct
- Ensure each step's stated verification would really detect a failure
- Identify integration risks and convention violations
- Check that nothing in Open Questions is in fact a blocker disguised as a question
Output format:
## Validation Result (PASS / NEEDS_REVISION)
## Missing Coverage
## Ordering Problems
## Integration Risks
## Revised Steps (if NEEDS_REVISION)On NEEDS_REVISION, revise the plan document and re-run gates 1 and 3 before
continuing. How to revise is judgment; re-validating is not optional.
Gate 4 — user approval. Present the plan (path included) and ask before any implementation starts. No script can decide that a plan is good enough to build.
6. Handoff
Report the resolved path so the next skill can consume it:
Plan written to .claude/docs/plans/{slug}.md (slug: {slug}) — Codex: PASS
Next: /team-execute with slug {slug}/team-execute resolves its own workspace from that same slug and reads the
plan from .claude/docs/plans/{slug}.md. Hand over the path and the slug; do not
paste the plan back into the conversation as the source of truth, and do not
invoke another skill from here — this is a handoff the user makes.
Notes
- Plans should be at actionable granularity
- Include verification method for each step
- Ask questions at planning stage for unclear points
- Don't over-detail (adjust during implementation)
- Deciding the steps, the risks, and what belongs in Open Questions is judgment and stays prose; only the artifact's path, shape, and gates are mechanical
Does 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.

