Skip to content

Commit 9fe67c0

Browse files
cursoragentjackmcdade
cursoragent
and
jackmcdade
committed
Add plan-feature skill for phased atomic feature work
Encodes brain-dump planning with gap analysis, competitive research, batched questions, See/Work/Deepen phases, and slice-by-slice builds on a clean branch. Co-authored-by: Jack McDade <jack@jackmcdade.com>
1 parent 647e8f5 commit 9fe67c0

4 files changed

Lines changed: 387 additions & 0 deletions

File tree

‎.claude/skills/plan-feature/SKILL.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
---
2+
name: plan-feature
3+
description: >-
4+
Plan and build features as researched, phased, atomic work. Use when the user
5+
brain-dumps a feature idea, asks to come up with a plan, wants clarifying
6+
questions / gap analysis / competitive research baked into a plan, or wants
7+
implementation broken into smallest testable slices on a clean branch with
8+
See → Work → Deepen phase groups. Invoke for /plan-feature, "plan this",
9+
"come up with a plan", or starting a new feature from a rough dump.
10+
icon: map
11+
color: blue
12+
---
13+
14+
# Plan Feature
15+
16+
Turn a rough feature dump into a researched plan, then execute it as a linear
17+
sequence of tiny, finishable slices. Never scaffold a whole feature up front.
18+
19+
Read `references/phase-model.md` before writing phases.
20+
Read `references/plan-template.md` when drafting the plan document.
21+
Read `references/competitive-research.md` when doing competitor / peer research.
22+
23+
## Modes
24+
25+
This skill has two modes. Default to **Plan** until the user explicitly says to
26+
build / implement / start / go.
27+
28+
| Mode | Trigger | Output |
29+
| --- | --- | --- |
30+
| **Plan** | Brain dump, "come up with a plan", `/plan-feature` | Questions + full plan (no code) |
31+
| **Build** | "Build it", "start", "go", approve a plan | Atomic slices on a clean branch |
32+
33+
Do not mix modes. In Plan mode: no implementation. In Build mode: follow the
34+
approved plan slice-by-slice; do not re-litigate the plan unless blocked.
35+
36+
---
37+
38+
## Plan mode
39+
40+
### 1. Ingest the dump
41+
42+
Treat the user's message(s) as raw material, not a finished spec.
43+
44+
- Extract goals, constraints, non-goals, named UI/UX beats, tech hunches, and open worries.
45+
- Do **not** start coding.
46+
- Do **not** ask one question at a time mid-ingest. Gather context first.
47+
48+
### 2. Ground in this repo
49+
50+
Before proposing anything:
51+
52+
- Find existing related code, fieldtypes, CP patterns, APIs, config, and tests.
53+
- Prefer extending established patterns over inventing parallel systems.
54+
- Note Eloquent / Stache / GraphQL / REST / CP / frontend touchpoints that may matter later (often Deepen-phase work).
55+
56+
### 3. Gap analysis (things they forgot)
57+
58+
Actively hunt for omissions. Typical Statamic/CMS gaps:
59+
60+
- Permissions, roles, and Pro vs free boundaries
61+
- Multisite, localization, and publish states
62+
- Revisions, blueprints, and default config
63+
- Stache vs Eloquent driver parity
64+
- API / GraphQL exposure
65+
- Upgrade path, migrations, and backward compatibility
66+
- Empty states, errors, loading, and keyboard/a11y in CP
67+
- Docs, changelog, and translation strings
68+
- Performance, caching, and large-site behavior
69+
- Addon extension points / events / tags / modifiers
70+
71+
List forgotten items as either **must decide**, **defer to Deepen**, or **out of scope**.
72+
73+
### 4. Competitive / peer research
74+
75+
Do lightweight but real research. Use web search / docs fetch when available.
76+
77+
- Compare how peer products solve the same job (not feature checklists for vanity).
78+
- Capture: interaction model, naming, defaults, killer detail worth stealing, traps to avoid.
79+
- Prefer primary docs and recent product UI over random blogs.
80+
- Fold findings into the plan as **recommendations**, not a separate essay.
81+
82+
See `references/competitive-research.md` for who to check by domain.
83+
84+
### 5. Clarifying questions
85+
86+
After research + gap analysis, ask a **single batched** set of questions.
87+
88+
Rules:
89+
90+
- Only ask what changes the plan or sequencing.
91+
- Prefer multiple-choice / opinionated defaults when possible ("Default: X — override?").
92+
- Separate **blockers** (need answer before planning further) from **nice-to-know**.
93+
- If the user said "just plan" and leftovers are non-blocking, state assumptions and continue.
94+
95+
Wait for answers on blockers before finalizing the plan (unless they explicitly want a draft plan with assumptions called out).
96+
97+
### 6. Produce the plan
98+
99+
Write the plan using `references/plan-template.md`.
100+
101+
Hard requirements for every plan:
102+
103+
1. **Phase groups** — organize work into groups the human can pause and explore:
104+
- **See** — visible presence / spike. OK if incomplete or broken. Goal: *I can see it.*
105+
- **Work** — core path actually works. Goal: *I can use it.*
106+
- **Deepen** — integrations, parity, polish, edge cases (Eloquent, APIs, a11y, docs, etc.). Goal: *It belongs in the product.*
107+
2. **Phases inside groups** — as many as needed (2 or 10). Each phase ends in something the user can open, click, run, or otherwise inspect.
108+
3. **Atomic slices** — every phase is broken into the **smallest** finishable pieces. One concern per slice. No "set up the whole feature" slices.
109+
4. **Linear dependency** — slices build on prior slices. No parallel mega-scaffolding.
110+
5. **Per-slice contract** — each slice lists: intent, files/areas touched (best guess), how to verify, and commit message intent.
111+
6. **Stop points** — explicit "pause for Jack to explore" markers after See phases and after Work phases (and anytime a phase changes what can be demoed).
112+
113+
Anti-patterns (reject these in your own draft):
114+
115+
- "Phase 1: scaffold models, CP Vue, API, and tests"
116+
- Big-bang branches with everything half-wired
117+
- Deepen work (Eloquent, GraphQL, …) blocking the first visible spike
118+
- Vague slices ("improve UX", "handle edge cases") without a verify step
119+
120+
Present the plan. Ask for approval or edits. Do not build yet.
121+
122+
---
123+
124+
## Build mode
125+
126+
Only after explicit go-ahead on a plan (or a clearly scoped subset).
127+
128+
### 0. Clean branch first
129+
130+
Always start from a fresh branch off the current base (usually `6.x`):
131+
132+
```bash
133+
git fetch origin
134+
git checkout <base>
135+
git pull origin <base>
136+
git checkout -b <type>/<short-feature-name>
137+
```
138+
139+
- Never pile a new feature onto a dirty mixed-purpose branch.
140+
- If the working tree already has unrelated changes, stop and sort that out before building.
141+
- One feature effort → one branch (or stacked branches only if the plan says so).
142+
143+
### 1. One slice at a time
144+
145+
For each slice, in order:
146+
147+
1. **Implement only that slice** — nothing speculative for later slices.
148+
2. **Verify** — run the slice's stated checks (PHPUnit/Vitest/manual CP poke as applicable).
149+
3. **Describe** — short note of what changed and how to see it (for the user / PR body).
150+
4. **Commit** — focused commit message matching the slice intent.
151+
5. **Stop if the plan says to** — especially after See / Work phase boundaries. Tell the user what to open/click/run next. Wait for "continue" unless they pre-approved running through a phase group.
152+
153+
### 2. Progression rules
154+
155+
- Each commit should leave the project **coherent** — not necessarily feature-complete, but not a landmine. Prefer vertical thin slices over horizontal layers.
156+
- See-phase code may be ugly or partial; still keep it runnable enough to inspect.
157+
- Work-phase slices must make the happy path actually work before Deepen starts.
158+
- If a slice reveals the plan is wrong, pause, propose a plan amendment, and get a nod before rewriting the roadmap.
159+
160+
### 3. Testing bar
161+
162+
- Prefer adding/adjusting tests in the same slice that introduces behavior.
163+
- Don't defer all tests to a final "Phase N: tests" dump.
164+
- Manual CP verification counts when UI-only; say exactly where to look.
165+
166+
### 4. Done
167+
168+
When the agreed phases are complete (or the user stops at a pause point):
169+
170+
- Summarize what shipped per phase.
171+
- List what remains (deferred Deepen items).
172+
- Note how to try it.
173+
174+
---
175+
176+
## Communication style
177+
178+
- Treat the user as an expert. Be terse and opinionated.
179+
- Lead with the plan / questions, not process narration.
180+
- Competitive notes: sharp takeaways only.
181+
- During Build: say which slice you're on, then do it — no giant status essays.

‎.claude/skills/plan-feature/references/competitive-research.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Competitive / peer research
2+
3+
Research informs the plan. It is not a slide deck.
4+
5+
## How to research
6+
7+
1. Name the **job** (e.g. "schedule publish UI", "asset folder permissions"), not the implementation.
8+
2. Pick 2–4 peers that actually solve that job.
9+
3. Prefer official docs + current product behavior over third-party listicles.
10+
4. For each peer, capture only:
11+
- How users accomplish the job
12+
- Defaults / opinionated choices
13+
- One thing they do better than our likely approach
14+
- One thing to avoid
15+
5. End with a **recommendation** that changes our phases or UX — or explicitly "no change; peers confirm X".
16+
17+
Timebox: enough to improve the plan, not a market study.
18+
19+
## Who to check (by domain)
20+
21+
Use judgment; skip irrelevant columns.
22+
23+
| Domain | Often worth checking |
24+
| --- | --- |
25+
| CMS / content modeling | Craft CMS, WordPress (+ Gutenberg), Kirby, Directus, Sanity, Storyblok, Contentful |
26+
| Control panel UX | Craft CP, Filament, Nova, WordPress admin (for familiarity traps) |
27+
| Assets / media | Craft Assets, WordPress Media, Cloudinary-style DAM patterns |
28+
| Permissions / roles | Craft, WordPress roles/caps, Laravel policies / Filament shields |
29+
| Live preview / front-end editing | Craft live preview, WordPress editor, visual editors generally |
30+
| Search | Scout-style, Algolia docs patterns, Meilisearch |
31+
| Multisite / i18n | Craft multi-site, WordPress multisite / multilingual plugins, Kirby languages |
32+
| Forms | Craft Formie-class patterns, WordPress form plugins, Typeform-ish UX only if relevant |
33+
| Commerce-ish | Only if the feature is commerce; otherwise skip |
34+
35+
Also check **our own** prior art: Statamic addons, old issues, discussions, and similar fieldtypes/CP tools in this repo.
36+
37+
## Output shape in the plan
38+
39+
Keep it brutal:
40+
41+
```markdown
42+
## Competitive notes
43+
- **Craft**: … → we should …
44+
- **Kirby**: … → avoid …
45+
- **Recommendation**: Prefer A over B in See/Work; leave C for Deepen.
46+
```
47+
48+
## Anti-patterns
49+
50+
- Feature matrices with 20 columns and no decision
51+
- Citing competitors without tying to a phase or UX choice
52+
- Letting competitor scope inflate Deepen into a rewrite of their entire product

‎.claude/skills/plan-feature/references/phase-model.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Phase model
2+
3+
Phases exist so a human can **stop, look, and poke** — not so an agent can batch work.
4+
5+
## Phase groups
6+
7+
Every plan assigns each phase to one group:
8+
9+
### See — "I want to see it"
10+
11+
- Make the feature **visible or tangible** as early as possible.
12+
- Wire the thinnest possible path to something on screen / in CLI / in a test dump.
13+
- Incomplete, stubbed, or broken behavior is OK if the shape is inspectable.
14+
- Typical slices: route + empty CP view, fieldtype shell, config key that appears, nav item, read-only listing with fake data.
15+
- Exit criterion: user can open/run something and recognize the feature.
16+
17+
### Work — "I want to see it work"
18+
19+
- Make the **core happy path** real.
20+
- Still avoid secondary drivers, rare edge cases, and polish.
21+
- Typical slices: create/edit/delete, persistence, validation, primary UX interaction, essential permissions.
22+
- Exit criterion: user can complete the main job without fake data or "TODO" walls.
23+
24+
### Deepen — "make it product-grade"
25+
26+
- Integrations and parity that would have slowed See/Work.
27+
- Examples for Statamic: Eloquent driver, GraphQL/REST, revisions, multisite, translations, docs, performance, addon hooks, a11y pass.
28+
- Exit criterion: each deepen phase has its own demo/verify story; don't amalgamate into "the rest".
29+
30+
## How many phases?
31+
32+
As many as needed. Prefer **more small phases** over few large ones.
33+
34+
Good:
35+
36+
- See-1: CP nav + blank screen
37+
- See-2: list UI with hard-coded rows
38+
- Work-1: read from Stache
39+
- Work-2: create form saves
40+
- Work-3: edit + delete
41+
- Deepen-1: permissions
42+
- Deepen-2: Eloquent parity
43+
- Deepen-3: translations + docs
44+
45+
Bad:
46+
47+
- Phase 1: everything backend
48+
- Phase 2: everything frontend
49+
- Phase 3: tests and docs
50+
51+
## Atomic slices
52+
53+
A slice is too big if you cannot:
54+
55+
- explain it in one sentence, **and**
56+
- verify it without building the next slice, **and**
57+
- commit it without leaving half-related files "for later" uncommitted.
58+
59+
If a slice needs a temporary seam (stub, fake data, feature flag), prefer that over pulling forward the next slice's real implementation.
60+
61+
## Vertical over horizontal
62+
63+
Prefer end-to-end thin cuts:
64+
65+
`nav → view → one action → one test`
66+
67+
over layer cakes:
68+
69+
`all models → all controllers → all Vue → all tests`
70+
71+
## Pause points
72+
73+
After every See phase and every Work phase, the plan must include:
74+
75+
> **Pause:** try X. Say continue when ready.
76+
77+
Build mode honors these unless the user pre-authorizes a longer run ("do all See phases").

‎.claude/skills/plan-feature/references/plan-template.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Plan template
2+
3+
Copy this structure. Omit sections only when truly empty — prefer an explicit "None" over silent gaps.
4+
5+
```markdown
6+
# Feature: <name>
7+
8+
## Problem / job to be done
9+
<1–3 sentences>
10+
11+
## Goals
12+
- …
13+
14+
## Non-goals
15+
- …
16+
17+
## Assumptions
18+
- … (call out anything guessed)
19+
20+
## Existing code to lean on
21+
- `path` — why
22+
23+
## Gaps / risks we almost forgot
24+
| Item | Decision |
25+
| --- | --- |
26+
| … | must decide / defer (Deepen-N) / out of scope |
27+
28+
## Competitive notes
29+
- **<product>**: takeaway → how it affects us
30+
- **Recommendation**: …
31+
32+
## Open questions
33+
### Blockers
34+
1. …
35+
36+
### Non-blocking
37+
1. … (default: …)
38+
39+
## Approach (short)
40+
<paragraph or short bullet architecture — not a novel>
41+
42+
## Phased build
43+
44+
### See
45+
#### Phase S1 — <title>
46+
**Demo:** <what Jack opens/clicks/runs>
47+
**Pause after:** yes/no
48+
49+
| Slice | Intent | Verify | Commit intent |
50+
| --- | --- | --- | --- |
51+
| S1.1 | … | … | … |
52+
| S1.2 | … | … | … |
53+
54+
#### Phase S2 — …
55+
…
56+
57+
### Work
58+
#### Phase W1 — …
59+
…
60+
61+
### Deepen
62+
#### Phase D1 — …
63+
…
64+
65+
## Branch
66+
- Base: `6.x` (or …)
67+
- Branch: `feature/<name>`
68+
69+
## Definition of done (for agreed scope)
70+
- [ ] …
71+
```
72+
73+
## Writing tips
74+
75+
- Slice IDs stay stable (`S1.2`, `W2.1`) so Build chat can say "doing W2.1".
76+
- Verify column must be concrete: `./vendor/bin/phpunit --filter FooTest`, "CP → Foo → create → save", etc.
77+
- If competitive research found nothing useful, say so in one line — don't pad.

0 commit comments

Comments
 (0)