GentBajko/capstone / skills/core
core
VerifiedInternal to the capstone suite - carries the shared rules (references/) and scripts every capstone subcommand reads; it exists so npx-skills installs ship them alongside the command skills. Not meant to be invoked directly; when invoked anyway, run references/../scripts/help.sh and output its stdout verbatim.
references/protocols/groom.md
View on GitHub# groom - doc-grounded feature interview
**Reads:** config → the feature's `feature-interview.md` (resume) →
`<index_file>` → the touched topic chapters (after the staleness
pass) → the `logic/` scenarios and `mockup/` screens it extends, plus
the `uiux/` chapters for UI features → `standards.md`.
First stage of the feature chain (`groom` → `plan` → `implement`,
chained by `feature`): turns a feature idea into a spec a
planner could work from, grounded in the existing reference instead of
re-exploring the repo. The superpowers brainstorming discipline,
adapted to capstone: the chapters are the context, every answer
persists before the next question, and the spec traces each
requirement to a recorded decision.
Prerequisite: a stamped index. Without one, build it first per core.md's
Missing reference rule (run `map`, which builds one when none
exists), then groom against it: grooming against no reference is
guessing, and `map` producing no index either - an empty repo - is
the one case that stops the run.
State: `docs/capstone/features/<id>/feature-interview.md`, same
resumable format as the other interviews (frontmatter with `status`,
numbered `§Q` decision entries; standard lifecycle per core.md; never
indexed). `<id>` is `<YYYY-MM-DD>-<slug>`: the date this groom began
plus a short kebab name for the feature. The id is derived from the
request, never allocated from a ledger: the old `<NN>-<slug>` scheme
took the next number from what was visible on the current branch, so
two parallel PRs both minted `03-`. Existing `<NN>-<slug>` folders
and keys stay as they are and are matched like any other id; only
new features get the date form.
Output: `spec.md` beside it; the `features/` folder is one Companion
docs row. Later stages add their own keys to the same frontmatter
(`plan_approved`, `approved_spec`, `branch`, `base_commit`,
`implemented`);
`status: formalized` here means the user approved the spec on disk,
not that the feature is built.
**Resume:** before anything else, match the request against existing
`docs/capstone/features/*/` ids and spec titles **and against the
`implement/*` keys in the ledger** (`changelog.md`, its rotation
files, and unfolded `changelog.d/` fragments, per core.md), whose
features are shipped and whose folders `implement` may have deleted.
Never reuse a shipped feature's id, legacy `<NN>-<slug>` ids included.
A match on an `implement/<id>` changelog key is a **shipped** feature,
whether its folder is absent or retained by
`delete_feature_folders: false`: say so and show that entry. A request
to change it is a new feature grooming against the shipped behavior
now recorded in `logic/` and the chapters, not a reopening: give it its
own date-slug id, and have its `§Q` entries cite the earlier key as the
thing being amended. Do not reopen or re-derive the completed working
files from the changelog; that would invent decisions the user never
restated.
A match on a folder still present continues as before: read its
`feature-interview.md` and continue: `interviewing` resumes the
interview after re-running Phase A's staleness pass (never re-ask an
answered `§Q`), `awaiting-formalization` re-presents the gate over
the draft `spec.md`, rewritten from the recorded `§Q` decisions first
(an amendment may have been recorded and never reached the draft),
`formalized` points at `plan`, unless the request changes the
feature itself: then reopen from `spec.md`, set `status: interviewing`,
and interview only the change (new `§Q` entries may name prior working
entries internally, but the rewritten spec may not),
rewrite `spec.md`, and re-gate; the changed spec voids any recorded
plan approval via `plan`'s checksum rule. `formalized` with
`spec.md` missing or partial is a crash: regenerate the spec from the
recorded `§Q` decisions, without re-interviewing, then set
`status: awaiting-formalization` and gate it again. The regenerated
wording is not the text that was approved, and `plan`'s checksum
voids any approval made against the lost one.
## Phase A - study
1. Per core.md: read the config; expertise governs the conversation.
2. From the index, pick the topics the feature touches:
architecture and models almost always; the rest as the idea
implies. Run the `core` skill's `scripts/map-check.sh <docs_dir>`
via bash (`map check`'s staleness pass: `git diff --name-only`
from each stamp over its globs, plus untracked files) and read
its part 1 rows for just those topics; refresh any stale ones
first: a spec groomed against a stale reference is stale on
arrival. For `mode: prescriptive` chapters the script's verdict
governs: `current` means no tracked source yet, current by
definition; `prescriptive, pending first observation` means code
now exists, stale by definition, refresh first.
3. Read the picked chapters, plus whichever companion docs bear on the
feature: the `logic/` scenarios it extends, the `mockup/` screens
it changes, the `uiux/` chapters it touches, `standards.md`.
Never ask what these already answer.
4. **Cross-repo constraints, before the first question.** When config
`cross_repo` is `auto` (the default), the `quarry` CLI is on PATH,
and the docs area in play has a `09-interfaces.md`: run
`quarry docs deps <repo> --downstream --json` (`<repo>` per
core.md's `workspaces` rule: when `workspaces` is configured, the
name of the workspace whose `path` contains the files the feature
touches, one deps call per workspace when it touches several, and
that workspace's `<path>/docs/capstone/09-interfaces.md` is the
chapter that must exist; otherwise the last path segment of this
repo's origin URL), then
`quarry docs section <consumer> "<contract>"` for each consumer
the deps call returns, to read the contract fields each downstream
repo actually depends on. When the feature touches an interface no
declared edge covers, fall back to
`quarry docs search "<name>"`. A deps row with `by_name: true` is
a possible consumer found by name only, not a declared edge: cite
it as a lead, and a `quarry docs section` refusal on such a row
is not an error. Any condition unmet (config `off`, no CLI, no
chapter) → skip silently and groom exactly as before.
This lives here, in protocol text, deliberately - never as a
harness hook, because capstone also runs on harnesses without
hooks.
In the same pass, run `quarry docs index --json` and take its
`ambiguous` rows for this repo that name an interface the feature
adds or changes. Put those to the user as core.md's Edge
confirmation describes, one digest, before the first question:
the answer decides which consumer the interview is holding the
feature to. Record each answer in the spec's Reference impact so
`implement`'s wrap writes it into `09-interfaces.md`'s `edges:`
block; this stage never edits the chapter itself. Nothing
ambiguous, or any condition unmet → ask nothing.
5. An artifact argument (a ticket, a PRD, notes) seeds the interview
per core-authoring.md's Artifact seeding rule.
## Phase B - the interview
One question per turn, expertise-calibrated, per the conduct rules in
`../interview.md`: concrete options when enumerable, quantified
answers, YAGNI ruthlessly. Record every answer as a `§Q` entry in
`feature-interview.md` before asking the next question. The
generation rule: **"if I had to write the spec right now, what would
I have to invent?"** The next question is whatever tops that list.
- When Phase A step 4 found downstream consumers, the **first
question cites the constraint**: name the consumer, the contract,
and the fields it reads, and ask how the feature holds or breaks
them. A groomed change to a produced interface that never surfaced
its consumers is a spec defect.
- Scope first: if the description hides several independent features,
say so and split: each gets its own `features/` entry and its own
chain run. Groom one; list the rest in the interview file.
- Settle purpose, users, and success criteria before mechanics.
- For the shape decision, present 2-3 approaches with trade-offs and a
recommendation, never one, as a message question so the comparison
is on screen when the user picks. Record the rejected alternatives
and why.
- Walk the unhappy paths like `logic` does: per step: fails, invalid,
happens twice, happens late, concurrent, cancelled midway.
- A feature that contradicts a recorded decision in the reference is a
question, not a silent override: show the chapter's decision, ask
which governs.
## Phase C - the spec, then the gate
Write `spec.md` as a draft, from the recorded decisions:
- **What & why**: the feature in one paragraph; success criteria.
- **Requirements**: numbered, with each confirmed decision and any
needed rationale written directly into the spec.
- **Approach**: the chosen shape and the rejected alternatives.
- **Behavior**: happy path, branches, unhappy paths, state changes;
exact rules with real numbers, `logic/`-style.
- **Reference impact**: which chapters this will change once built,
AND the scenario docs to absorb into after implementation: the
`logic/` scenarios it adds or amends, the `mockup/` screens it
changes, the `uiux/` chapters it touches (`plan` reads this to
scope its study; `implement`'s wrap performs the absorption; the
`map` refresh settles the chapters). Every edge Phase A step 4's
confirmation settled is one line here - direction, kind, name, and
the repo name the user gave - because `09-interfaces.md`'s `to`
and `from` are the one thing the `map` refresh will not derive.
- **Out of scope**: non-goals, recorded as decisions.
Self-review before presenting it (fix inline): no placeholders
("TBD", "handle errors appropriately"), no section contradicting
another, no requirement readable two ways, scoped to a single plan.
Then set `status: awaiting-formalization` and ask the user to check
the spec itself. The gate is a message question per core.md's
Structured questions: the design as a short summary (what it does,
chosen approach, edge-case posture, what's out of scope) and
`spec.md`'s path are the chat message, its last line asks the user to
approve the spec or change it, and the turn ends there, in a
standalone run and inside the `feature` chain alike. Only an explicit
approval passes it. A reply that adds or changes something is an
amendment, however it is worded ("before you plan, add..."): record
it as a new `§Q` entry, rewrite the spec, and present the gate again.
An amendment that leaves something to invent goes back to the
interview first: set `status: interviewing`, ask per Phase B, then
return here.
Nothing is planned from a spec the user has not approved.
On approval write the changelog entry per core.md's ledger: key
`groom/<id>@Q<n>`, `<n>` the highest `§Q` in
`feature-interview.md`; record the chosen approach with the rejected
alternatives and the out-of-scope rulings. Add or refresh the
`features/` Companion docs row and set `status: formalized` (only
now: the spec approved, outputs on disk). A standalone run stops
here; a run another protocol started - the `feature` chain, or `plan`
or `implement` meeting its prerequisite - announces the stage and
returns to that protocol.
**Consumer:** `plan` turns the spec into a task-by-task implementation
plan; suggest it as the next step.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |