feature-plan
Skill1 starsChanged 3 months agoMITView on GitHub
Facilitate the architectural planning/discussion phase for a new feature or technical topic — before any implementation code is written — using docs/plans/TEMPLATE.md's structure (Current State, Open Questions, Decisions, worked Example) and this project's proven planning conventions from docs/plans/ARCHITECTURE.md. Use this whenever the user wants to discuss, design, or plan a new feature or technical topic, says things like "let's plan X", "I want to discuss the architecture for Y", "before we build Z let's figure out the design", or pastes docs/plans/TEMPLATE.md's starter prompt — even if they don't name this skill explicitly. This is a discussion-and-record skill, not a code-generation skill: it never writes implementation files under src/. Once a plan is fully resolved, hand off to implementation (gen-module for scaffolding, arch-audit to verify) via a separate approval step — never generate code as part of this skill.
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
- lifemixture/ai-orchestration-repotheir own version, first seen Oct 11, 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
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
- hempq/symfony-claude-code★ 1same name
- Koshux/agentic-sdlc-scaffold★ 0same name
- kuyacarlo/skills★ 0same name
- lifemixture/ai-orchestration-repo★ 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 repository5 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- arch-auditSkill
- feature-flowSkill
- gen-moduleSkill
- test-badassSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
13 rules. 0 are common, 4 are distinctive, and 9 are very specific to this project.
0
Common
Most of the 9 edited versions we read keep these.
4
Distinctive
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 18
Delete the template's instructional HTML comments as each section gets real content, per the template's own instructions — don't ship them …
- Very specific: line 28
Ask about edge cases, domain boundaries, performance, and trade-offs the user hasn't raised — that's what populates Open Questions in the …
- Distinctive: line 30
When the user proposes something, weigh it — agree with reasoning if it's sound, or push back with a concrete trade-off if it isn't.
- Very specific: line 37
Every Decisions bullet gets a bold lead-in phrase naming the decision, then the actual reasoning — why, not just what — and any real …
- Distinctive: line 39
If a new decision changes something decided earlier in the *same* doc, update or remove the outdated bullet explicitly — don't leave two …
- Very specific: line 40
Update the Example section's strawman code when the discussion has made something concrete enough to be worth showing — and say plainly …
- Very specific: line 46
When Open Questions is (none currently) and at least one real decision has been recorded, stop.
- Very specific: line 55
Read the actual codebase for Current State facts — never invent them.
- Very specific: line 58
Verify a technical claim (a CLI flag, a library's behavior, a naming rule) before writing it into Decisions as settled.
- Very specific: line 62
Don't write any file under src/ during planning, for any reason — including a "quick example" that isn't clearly inline strawman code in …
- Very specific: line 63
Don't leave a resolved item duplicated in both Open Questions and Decisions.
- Distinctive: line 64
Don't skip Step 4's explicit stop-and-ask, even when the plan feels obviously finished — the user approves the plan, not the skill.
- Very specific: line 65
Don't substitute a different command for /feature-flow in the completion message.
“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
Facilitating a feature/topic plan (feature-plan)
This skill runs the same process that produced docs/plans/ARCHITECTURE.md — a real, working example already sitting in this repo. When in doubt about how thorough a Decisions bullet should be, how an Open Question gets resolved, or what the worked Example section looks like, read that file directly; it's the proof this process works, not just a description of it.
Step 1 — Find or create the plan doc
Derive a short <topic-slug> (kebab-case) from what the user is asking to plan, state it, and proceed — if it's wrong, they'll correct you, and renaming a file later is cheap. Then:
docs/plans/<topic-slug>.mdalready exists → this is a resumed discussion, not a new one. Read the whole file —Current State,Open Questions,Decisions, and theExamplesection if there is one — before saying anything. Continue from exactly where it left off; don't restate settled Decisions back to the user, and don't re-ask a question that's already answered in the file.- It doesn't exist → copy
docs/plans/TEMPLATE.mdto the new path, then fill in real content immediately (don't leave the copy sitting with{{placeholders}}):- The
{{Topic}}title and the one-or-two-sentence framing paragraph. Current State, gathered by actually reading the relevant parts of the codebase (existing modules,package.json, config files) — never invented or assumed. List constraints already fixed elsewhere (thedocs/guidelines,CLAUDE.md) as background, explicitly not open for discussion here.- Delete the template's instructional HTML comments as each section gets real content, per the template's own instructions — don't ship them into the live doc.
- The
Step 2 — Discuss. Do not implement.
Absolutely do not write any implementation file — no <feature>.schema.ts, .entity.ts, .dto.ts, .repository.ts, .service.ts, .controller.ts, .errors.ts, nothing under src/modules/ or anywhere else in src/. That's what gen-module (and arch-audit to check it) are for, and only after Step 4's approval gate. If the user asks to jump straight to code mid-discussion, say so plainly and ask them to confirm they want to skip the rest of the plan — don't silently comply just because they asked.
The one exception: small strawman code snippets inside the plan doc's own Example section are expected and useful — see how docs/plans/ARCHITECTURE.md's worked example evolved turn by turn. The line: a snippet that lives in the markdown doc to make a decision concrete is discussion; a file written under src/ is implementation.
Within that boundary, be a sharp, critical co-architect, not a transcriptionist:
- Ask about edge cases, domain boundaries, performance, and trade-offs the user hasn't raised — that's what populates
Open Questionsin the first place, not just what the user happens to think to ask. - Verify technical claims against the real codebase or tooling before writing them into the doc as settled. This is the single highest-value habit from the
ARCHITECTURE.mdprocess: a claimed CLI flag turned out not to exist (drizzle-kit db:migrate— the real subcommand ismigrate), and an assumed-safe naming convention turned out to silently break test discovery (.e2e-spec.tsvs.e2e.spec.ts) — both caught by actually running the command, not by reasoning about it. A decision recorded on a wrong assumption is worse than an honestly-open question. - When the user proposes something, weigh it — agree with reasoning if it's sound, or push back with a concrete trade-off if it isn't. Don't rubber-stamp the first idea just because it was said with confidence.
Step 3 — Update the plan in place, immediately
The moment something is actually agreed — not "sounds plausible, tell me more," but agreed — edit the doc in the same turn, before moving to the next question:
- Move the resolved item out of
Open Questionsand intoDecisions. Never leave a stale "still open" bullet sitting next to the answer that just resolved it. - Every
Decisionsbullet gets a bold lead-in phrase naming the decision, then the actual reasoning — why, not just what — and any real trade-off being accepted. A future reader shouldn't have to re-read the whole conversation to understand why something was decided. - Cross-reference other decisions or
docs/guidelines by name instead of repeating them. - If a new decision changes something decided earlier in the same doc, update or remove the outdated bullet explicitly — don't leave two contradictory statements standing.
- Update the
Examplesection's strawman code when the discussion has made something concrete enough to be worth showing — and say plainly which parts are settled versus still in flux.
After every edit, check whether Open Questions now reads (none currently). If it does, before moving to Step 4, look at the Example section: if the decisions just recorded describe a concrete shape (where something attaches, what a request/response looks like, how pieces fit together) and the section is still empty or placeholder text, that's unfinished work, even though it's not literally an Open Questions bullet — write the strawman now. Only skip it, per docs/plans/TEMPLATE.md's own guidance, when the topic's decisions are genuinely non-code (naming rules, process conventions) and a worked example wouldn't add anything — in that case delete the section outright rather than leaving a placeholder. Don't declare the plan resolved with an empty {{concrete worked example}} placeholder still sitting in the file.
Step 4 — Completion signal (approval gate)
When Open Questions is (none currently) and at least one real decision has been recorded, stop. Don't proceed to implementation, and don't keep inventing new questions just to keep the conversation going. Say exactly:
"The architecture plan for
<topic>is fully resolved and recorded indocs/plans/<topic-slug>.md. Would you like to approve this plan and proceed with implementation via/feature-flow?"
Fill in the real topic name and file path. /feature-flow is the orchestrator skill that runs the rest of the Red-Green-Refactor pipeline (test-badass → gen-module → arch-audit) — if the user approves here, feature-flow's own Step 0 will pick this plan up from exactly this state (a resolved plan doc, not-yet-approved) and take it from there. Don't silently substitute a different skill for /feature-flow in this message.
Do
- State the derived topic-slug and proceed rather than blocking on confirmation for something cheap to fix later.
- Read the actual codebase for
Current Statefacts — never invent them. - Move an item out of
Open Questionsthe instant it's resolved, same turn, not "I'll clean that up later." - Push back with a concrete trade-off when a proposal has one, rather than accepting it uncritically.
- Verify a technical claim (a CLI flag, a library's behavior, a naming rule) before writing it into
Decisionsas settled.
Don't
- Don't write any file under
src/during planning, for any reason — including a "quick example" that isn't clearly inline strawman code in the doc itself. - Don't leave a resolved item duplicated in both
Open QuestionsandDecisions. - Don't skip Step 4's explicit stop-and-ask, even when the plan feels obviously finished — the user approves the plan, not the skill.
- Don't substitute a different command for
/feature-flowin the completion message.
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.

