agentleFS
lifemixturelifemixture/ai-orchestration-repo/.claude/skills/feature-plan/SKILL.md

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

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

    YAGNI / subtractive: Keep asking what can be dropped.

    line 23
  2. Very specific:

    Read repos.yaml. The summary and role of each entry exist for exactly this moment.

    line 34
  3. Very specific:

    Read docs/system/architecture.md for how the system is cut up and why.

    line 47
  4. Distinctive:

    Keep a running decision ledger (decision → rationale).

    line 81
  5. Very specific:

    Keep PRD ("what & why") and IMPLEMENTATION_PLAN ("how") consistent with each other.

    line 128
  6. Very specific:

    If docs/features/<slug>/plan-reviews/ already holds a report, read the latest one and revise both documents with the user to address its …

    line 132

“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

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.

  1. Read repos.yaml. The summary and role of each entry exist for exactly this moment.
  2. Read .claude/rules/services/<svc>.md as files for the plausible candidates. Those are path-scoped rules: nothing under projects/ has been read yet, so none of them is loaded automatically. At planning time you must open them yourself.
  3. 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.
  4. 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-build as 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-build implements 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:

    ServicePhasesBranchPRState
    orders-api1, 3feature/<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.

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.