feature-plan
Slices a finished design into user stories and an ordered task checklist (STORIES.md and PLAN.md) for feature-build. Use once feature-design has decided how to build the feature.
SKILL.mdplugins/umbraco-devkit/skills/feature-plan/SKILL.md
GitHubfeature-plan
🎯 Design for change. Slice tasks so each one touches one seam. A task that edits five unrelated files, or straddles both a Management API controller and an unrelated UUI component, is a coupling smell — re-slice before handing it to
feature-build.
Turn the design into something feature-build can execute. This command transforms
SPEC.md — it does not re-elicit requirements.
Where this writes
The same per-feature plan folder. Owns two files:
STORIES.md— via theuser-storiesskill; Given/When/Then acceptance criteria per story.PLAN.md— the dependency-ordered task checklistfeature-buildexecutes.
Read ARCHITECTURE.md and SPEC.md — this is confirmation and slicing, not a fresh
interview.
Also updates its own two lines in README.md — same append-only discipline as
DECISION-LOG.md: never touch a line owned by another phase.
A checklist of small, dependency-ordered, independently reviewable tasks forces sizing and
sequencing decisions up front and gives feature-build something mechanically parseable to
gate against. Keep this discipline (small, ordered, reviewable units) even for a project that
tracks completion via issues instead of an in-doc checklist.
Scope
- IN: derive user stories from
SPEC.md, order tasks into a dependency-aware checklist, mark what can run concurrently, then generate executable specs viabdd-specs— always, no asking. - OUT: gathering requirements (
feature-explore/feature-design), building (feature-build).
Preflight
- Resolve which feature this run is for. If more than one plan folder exists, prefer a match
between the current branch/worktree name and a folder name (see
CLAUDE.md's "Finding the current feature's plan folder" rule) — this is the normal case oncefeature-buildhas started. If nothing matches, fall back to the one plan folder present, or ask if more than one is ambiguous. - Read
SPEC.md(andARCHITECTURE.mdfor context) in the resolved folder. IfSPEC.mdis still a stub or full ofTODO, stop — send the user back tofeature-design. Likewise ifSPEC.mddescribes a new or visibly changed screen that has no mockup inmockups/: name the screens and send the user back tofeature-design. A screen without a mockup can't be approved, so it can't be planned. - Read any existing
STORIES.md/PLAN.md. Re-entrant: reconcile and extend; never silently drop or renumber completed (- [x]) tasks.
Stories
Delegate to user-stories to produce/refine STORIES.md (Given/When/Then acceptance
criteria per story, formatted so bdd-specs can consume it directly). Don't hand-roll the
format.
Specs (always, no asking)
Once STORIES.md is finalized and PLAN.md is written, always delegate to bdd-specs to
generate executable, pending spec files from the stories. This is part of feature-plan's
contract, not optional. The generated specs should fail (or be marked pending) until
feature-build turns them green.
Interview
Light — confirmation, not elicitation. ~3–5 questions, batched:
- Here's how
SPEC.mdwas sliced into stories — anything mis-cut or missing? - Priority/sequence right? What's the first shippable slice?
- Any task marked parallel that actually shares a file or a migration?
- Hard external dependencies that gate ordering (a CMS API only available from a certain version, a package that must ship first)?
Produce
Write every file this phase produces following plain-writing: a person reads it before the
next phase runs, so it should be quick to read without leaving anything out.
PLAN.md, a checklist feature-build can execute:
- Every task is
- [ ], top-to-bottom in dependency order. - Each task line carries: a short id, the story it implements, explicit
depends-on:ids, and aparallel-group:tag for tasks with no ordering between them. - One task = one reviewable, committable unit of work.
- No task references a file, extension point, or decision not already in
ARCHITECTURE.md/SPEC.md. - Wire tasks are first-class. For every feature that touches a real entry point — a
Management API controller, a Composer-registered service, a backoffice manifest entry —
include an explicit
wire: <feature> into <entry point>task whose acceptance is a real request or resolution through the deployed artifact, not just "unit tests pass." A task whose only acceptance criterion is unit-test-green is not allowed for anything on that path — that's how stubs ship. - Sync tasks travel with their entity. If the project supports Umbraco Deploy or uSync
(
umbraco-env-sync's "Does this project sync?") and a task adds or changes a synced entity, the matching sync change from its "Keep sync in step" table is in the plan: in the same task, or a task thatdepends-on:it. IfARCHITECTURE.mddoesn't say how a new entity moves, stop and send the user back tofeature-design.
Update the STORIES.md and PLAN.md lines in README.md: check each box and replace
<pending> with one plain-English line (e.g. "N stories" / "M tasks, first parallel group
is...").
Append dated DECISION-LOG.md entries for non-obvious sequencing decisions (why task X
blocks task Y, why a slice was deferred).
Hand off
Summarize: N stories, M tasks, S spec files generated, the first parallel group, then:
Suggested next: feature-build — specs are in place and pending. For a large or risky plan,
mention feature-interrogate as an optional stress-test before that first build.