agentleFS
dung204dung204/hono-starter-template/.claude/skills/feature-plan/SKILL.md

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

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
  1. Distinctive:

    Delete the template's instructional HTML comments as each section gets real content, per the template's own instructions — don't ship them …

    line 18
  2. Very specific:

    Ask about edge cases, domain boundaries, performance, and trade-offs the user hasn't raised — that's what populates Open Questions in the …

    line 28
  3. Distinctive:

    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.

    line 30
  4. Very specific:

    Every Decisions bullet gets a bold lead-in phrase naming the decision, then the actual reasoning — why, not just what — and any real …

    line 37
  5. Distinctive:

    If a new decision changes something decided earlier in the *same* doc, update or remove the outdated bullet explicitly — don't leave two …

    line 39
  6. Very specific:

    Update the Example section's strawman code when the discussion has made something concrete enough to be worth showing — and say plainly …

    line 40
  7. Very specific:

    When Open Questions is (none currently) and at least one real decision has been recorded, stop.

    line 46
  8. Very specific:

    Read the actual codebase for Current State facts — never invent them.

    line 55
  9. Very specific:

    Verify a technical claim (a CLI flag, a library's behavior, a naming rule) before writing it into Decisions as settled.

    line 58
  10. Very specific:

    Don't write any file under src/ during planning, for any reason — including a "quick example" that isn't clearly inline strawman code in …

    line 62
  11. Very specific:

    Don't leave a resolved item duplicated in both Open Questions and Decisions.

    line 63
  12. Distinctive:

    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.

    line 64
  13. Very specific:

    Don't substitute a different command for /feature-flow in the completion message.

    line 65

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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>.md already exists → this is a resumed discussion, not a new one. Read the whole file — Current State, Open Questions, Decisions, and the Example section 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.md to 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 (the docs/ 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.

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 Questions in 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.md process: a claimed CLI flag turned out not to exist (drizzle-kit db:migrate — the real subcommand is migrate), and an assumed-safe naming convention turned out to silently break test discovery (.e2e-spec.ts vs .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 Questions and into Decisions. Never leave a stale "still open" bullet sitting next to the answer that just resolved it.
  • Every Decisions bullet 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 Example section'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 in docs/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 State facts — never invent them.
  • Move an item out of Open Questions the 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 Decisions as 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 Questions and Decisions.
  • 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-flow in the completion message.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.