feature-plan
Skill0 starsChanged 3 months agoMITView on GitHub
Plan a feature that may span several service repositories. Narrows scope from the manifest before reading any code, clarifies requirements and contract changes interactively, then writes PRD.md + a phased IMPLEMENTATION_PLAN.md with a per-service owner, cross-repo ordering and one shared branch name, under docs/features/<slug>/.
9 other projects use a version of this.
Adopted by
Most recently taken up by
- tornikebolokadze1-cyber/agent-foundation-kittheir own version, first seen Nov 1, 2026
- kuyacarlo/skillstheir own version, first seen Oct 13, 2026
- Simone-Tarantino/godot-superpowerstheir own version, first seen Oct 11, 2026
- hempq/symfony-claude-codetheir own version, first seen Oct 9, 2026
- levy-street/world-of-claudecrafttheir own version, first seen Oct 8, 2026
- refpath/chatgpt-teamtheir own version, first seen Sep 12, 2026
Other versions9 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 9
- levy-street/world-of-claudecraft★ 2.3ksame name
- tornikebolokadze1-cyber/agent-foundation-kit★ 6same name
- Simone-Tarantino/godot-superpowers★ 2same name
- dung204/hono-starter-template★ 1same name
- hempq/symfony-claude-code★ 1same name
- Koshux/agentic-sdlc-scaffold★ 0same name
- kuyacarlo/skills★ 0same name
- refpath/chatgpt-team★ 0same name
- telefrek/vallorcine★ 0same name
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 repository6 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- feature-buildSkill
- feature-build-step-by-stepSkill
- feature-code-reviewSkill
- feature-plan-reviewSkill
- system-mapSkill
The file
We split this skill into the rules it gives an agent
6 rules. 0 are common, 2 are distinctive, and 4 are very specific to this project.
0
Common
Most of the 9 edited versions we read keep these.
2
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 23
YAGNI / subtractive: Keep asking what can be dropped.
- Very specific: line 34
Read repos.yaml. The summary and role of each entry exist for exactly this moment.
- Very specific: line 47
Read docs/system/architecture.md for how the system is cut up and why.
- Distinctive: line 81
Keep a running decision ledger (decision → rationale).
- Very specific: line 128
Keep PRD ("what & why") and IMPLEMENTATION_PLAN ("how") consistent with each other.
- Very specific: line 132
If docs/features/<slug>/plan-reviews/ already holds a report, read the latest one and revise both documents with the user to address its …
“Common” is measured: kept by at least 6 in 10 of the 9 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
You are planning a feature that may touch several repositories at once. Goal: a
validated PRD.md and a phased IMPLEMENTATION_PLAN.md under
docs/features/<slug>/. The feature to plan: $ARGUMENTS
This is interactive and multi-round — do NOT rush to writing the files. Validate every decision with the user; never add anything "just in case".
Operating principles (apply throughout)
- Justify every decision. Nothing goes in unless it solves a real problem. Surface the trade-off and give a recommendation.
- Vetted libraries over custom code, especially anywhere security-sensitive (auth, sessions, crypto, payments). Custom code is attack surface. Say so out loud when choosing.
- YAGNI / subtractive. Keep asking what can be dropped. Prefer removing a risk to documenting it when the fix is cheap.
- Verify external facts (pricing, free tiers, library capabilities) with WebSearch — never assert from memory.
- Never write into
projects/. Planning produces documents in this repo only.
Step 1 — Narrow the scope before reading any code
At forty services, reading first and scoping later is the difference between a cheap plan and an unusable one.
- Read
repos.yaml. Thesummaryandroleof each entry exist for exactly this moment. - Read
.claude/rules/services/<svc>.mdas files for the plausible candidates. Those are path-scoped rules: nothing underprojects/has been read yet, so none of them is loaded automatically. At planning time you must open them yourself. - Propose the candidate service set — each with a one-line reason why the feature touches it — and confirm with AskUserQuestion. Invite the user to add or drop services; they know about work you cannot see.
- Record the confirmed set. Everything downstream is limited to it. If a later step reveals another service is needed, re-confirm rather than quietly widening.
Step 2 — Ground in reality (in-scope services only)
Read docs/system/architecture.md for how the system is cut up and why.
Then spawn one Explore subagent per in-scope service, in parallel. Instruct each
to read projects/<svc>/CLAUDE.md first — that service's own rules and skills
only become available once a file in its directory has been read — and then to
report back concisely:
- how the affected area works today, and the conventions actually in use;
- where this change would land (files, modules, migrations, tests);
- what would make it risky.
Enough to plan, not enough to implement. Summarize what you found for the user before asking anything.
Step 3 — Clarify requirements (iterative rounds)
Drive focused rounds with AskUserQuestion, recommended option first, one area per round. Cover only what is relevant:
- Scope & non-goals; success criteria.
- Contract changes between services — the question that makes or breaks a multi-repo feature. Which contract changes, which repo owns it, and is the change breaking? A breaking change is never a single phase; see Step 4.
- Architecture and shape; technology and library choices.
- Data model; external integrations; auth/authz.
- Security / abuse analysis as an explicit pass, not an afterthought.
- Test strategy — which levels each service needs, and whether a contract test
is required and which repository owns it. Tests are written during
/feature-buildas the evidence a phase is done, so this is decided here or it is not decided at all. Note that the seam between two services is covered by neither service's own CI: if nobody is named as its owner, nobody tests it. - Cost / ops implications, with real numbers.
- Open questions.
Keep a running decision ledger (decision → rationale). Reconcile contradictions as they surface rather than at the end.
Step 4 — Order the work across repositories
This step is the reason this skill exists. Decide and write down:
- The contract lands first, in the repository that owns it — normally the producer. Consumers follow. Frontend last.
- A breaking change is at least three phases: expand (additive, old and new both valid) → migrate every consumer → contract (remove the old). Never plan a simultaneous switch across repositories; they do not deploy atomically.
- De-risk early with a thin walking skeleton that crosses all touched services, rather than finishing service A completely before starting service B. In a multi-repo feature, integration is the risk — front-load it.
- One branch name for the whole feature:
feature/<slug>, identical in every repository it touches.
Step 5 — Write the documents
Resolve a kebab-case slug from $ARGUMENTS, create docs/features/<slug>/, and write:
PRD.md — context; goals & non-goals; services touched (table: service · its role in this feature · why); decisions table (id · area · decision · rationale); scope; user stories; functional requirements; data model; contract changes (contract · owning repo · breaking? · migration); non-functional requirements including security; open questions; success criteria.
IMPLEMENTATION_PLAN.md — grounded in the real repositories:
- Branch:
feature/<slug>— the same in every repository below. - Phases, each with: owning service(s), goal, concrete tasks, files touched, acceptance criteria, ⚠️ risks.
- Test strategy — per service, the levels to write; and the contract test:
needed, and owned by which repository.
/feature-buildimplements this; it writes no tests the plan did not ask for and skips none that it did. - Cross-repo order — the phase sequence with the dependency reason for each edge.
- Deploy order and rollback — the sequence in which the merged changes reach production, and what to do if one of them has to go back.
Status checklist, the single place progress is tracked:
Service Phases Branch PR State orders-api 1, 3 feature/<slug>— planned States:
planned→in progress→pushed→PR open→merged.
Keep PRD ("what & why") and IMPLEMENTATION_PLAN ("how") consistent with each other.
Incorporating a plan review
If docs/features/<slug>/plan-reviews/ already holds a report, read the latest one
and revise both documents with the user to address its findings.
Output
State the two paths, the branch name, the confirmed service set, the key decisions
and the open questions. Suggest /feature-plan-review docs/features/<slug> next.
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.

