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/plan.md
View on GitHub# plan - task-by-task implementation plan from a groomed spec
**Reads:** config → the feature interview's approval frontmatter → `spec.md`
→ the chapters, scenarios, and screens it cites → `standards.md` →
`../code-craft.md` → the conventions and testing chapters.
Second stage of the feature chain: turns a formalized `spec.md` into a
plan an engineer with zero context could execute. The superpowers
writing-plans discipline (bite-sized steps, complete code, exact
paths, TDD throughout) with capstone's twist that context comes from
the chapterized reference, not repo exploration.
Prerequisite: if the ledger already carries the feature's
`implement/<id>` key, the feature is shipped whether its folder is
retained or absent; say so and stop. Otherwise the feature's interview
frontmatter says `formalized` and `spec.md` is on
disk. Interview missing or not yet `formalized` → execute
`protocols/groom.md` first (its Resume rules pick up mid-interview);
`formalized` with `spec.md` missing is a crash `groom`'s Resume rule
regenerates and gates again.
State: the feature's
`docs/capstone/features/<id>/feature-interview.md`
(`plan_approved: true` is set at the gate; the lifecycle `status`
stays `formalized`; this stage never touches it). Output: `plan.md`
beside the spec. Resolve a `<feature>` argument as `groom`'s Resume
rule does; with no argument and exactly one feature not yet
implemented, take it; otherwise ask.
**Resume:** an approval is valid only while `approved_spec` still
matches a checksum of the current `spec.md`. Valid → never re-present
the plan; point at `implement`. Mismatch → the approval is void:
delete `plan_approved` and `approved_spec` from the frontmatter
first, before touching `plan.md`, then re-run Phase A's study and
Phase B's review passes against the changed spec, update the plan,
and re-gate. If `plan.md` exists unapproved (or ends mid-sentence, a
crash artifact), finish it via Phase B's review passes, re-reading
Phase A's sources as needed, then re-present the gate. `plan_approved`
with `plan.md` missing or truncated is a crash too: delete
`plan_approved` and `approved_spec` first, rebuild the plan through
Phase B, and re-gate. A rebuilt plan is not the one that was approved.
A re-plan after `implement` executed tasks keeps every checked task
as it is (its commit stands) and plans the difference as new tasks,
including a new task that changes or removes what a finished task
built; it never unchecks a box and never rewrites a finished task.
## Phase A - study
Read the spec, then exactly what it cites: its Reference impact
chapters, the `logic/` scenarios and `mockup/` screens it names, plus
`standards.md` (every code decision follows it), `../code-craft.md`
(the TDD + YAGNI discipline every planned task obeys; standards wins
on conflict) and the conventions and testing chapters for how code
and tests are written here. The chapters answer where things live and
how they connect; read source files only where the plan must name
exact lines, or where a chapter labels its coverage shallow.
**Cross-repo constraints, before writing a task.** Under the same
conditions as `groom`'s Phase A step 4 (config `cross_repo: "auto"`,
the `quarry` CLI on PATH, a `09-interfaces.md` in the docs area in
play), with `<repo>` named as that step names it - the workspace whose
`path` contains the files the spec's Reference impact and the plan's
file map touch when `workspaces` is configured, else the origin's last
path segment: run `quarry docs deps <repo> --downstream --json`, then
`quarry docs section <consumer> "<contract>"` for each consumer of an
interface the spec touches; fall back to
`quarry docs search "<name>"` where no edge is declared. 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 → skip
silently. This lives in protocol text, never as a harness hook.
## Phase B - write the plan
Assume the executing engineer is skilled but knows nothing about this
codebase, its toolset, or good test design: the plan carries
everything. `plan.md`:
- **Header**: goal in one sentence; approach in 2-3; the stack pieces
touched; global constraints copied verbatim from the spec and
`standards.md` (version floors, naming rules, banned patterns).
`implement` no longer reads `standards.md` while it writes code
(`protocols/implement.md`'s Phase B), so a rule this feature must
follow is only binding if the plan copies it: copy every rule that
bears on these tasks, not a sample of the interesting ones.
- **File map**: every file created or modified, one responsibility
each, before any task is defined.
- **Tasks**: numbered `### Task N: <name>` headings, each the
smallest unit that carries its own test cycle and is worth a fresh
reviewer's gate. Fold setup, configuration, scaffolding, and
documentation steps into the task whose deliverable needs them;
split only where a reviewer could reject one task while approving
its neighbor.
Per task: exact paths (`Create:` / `Modify:` / `Test:`), interfaces
consumed from earlier tasks and produced for later ones (exact
names and signatures; a task's executor may see only its own task),
then checkbox (`- [ ]`) steps of 2-5 minutes each: write the failing
test (the actual test code), run it and see it fail (exact command,
expected failure), implement minimally (the actual code), run it and
see it pass (exact command), commit (message per code-craft's Git
section: `<type>(<scope>): <subject>` plus the why in the body).
- Backend before frontend where the feature spans both.
- Every task that changes an interface a downstream repo consumes
(per Phase A's quarry findings) cites the constraint in the task
body: the consumer, the contract, and the fields it reads. The
executor sees only its own task, so a constraint not written into
the task does not exist.
- **Coverage**, the closing section: a table with one row per
numbered spec requirement, per Behavior rule (each happy-path step,
branch, unhappy path, and state change), and per global constraint,
naming the task(s) that implement it and the task whose test proves
it. A row with no task is a gap; fix the plan, never the table.
There is no catch-all row, and no row covered "implicitly" by
another.
Placeholders are plan failures: never "TBD", "add validation",
"similar to Task N", tests described but not written, or names no task
defines. If a step changes code, the step shows the code.
Every task climbs code-craft's ladder before it is written down: a
task that builds what a rung above already provides, or an
abstraction no rung earned, is cut from the plan, not deferred to the
executor's judgment, unless a spec requirement mandates it, which is
a recorded user decision and earns it per code-craft's never-lazy
list. The plan's tests are YAGNI-scoped per code-craft; its
interfaces appear only where that file says one is earned; and the
code it shows carries only the comments code-craft's Comments section
earns. A plan that narrates its own snippets teaches the executor to
narrate the file.
**Review, then re-review.** A drafted plan is not presentable until
it survives full passes of this check, repeated until a pass finds
nothing to fix:
1. Re-read `spec.md` top to bottom, fresh, against the Coverage
table: every requirement, Behavior rule, and constraint lands on a
real task; a spec line with no row means the pass failed.
2. Walk the tasks in order: names and signatures a task consumes
match the task that defined them, and no task consumes what a
later task defines.
3. Sweep for the placeholder patterns above, and for comments in the
shown code that only restate the line beneath them; any survivor
fails the pass.
Fix what a pass finds, then run the next full pass; a pass that found
anything voids the ones before it. Dropping a spec detail because a
task "obviously implies it" is a gap, not a judgment call: the
executor sees only the plan.
## Phase C - the gate
Present the summary: file map, task list, the Coverage table's totals
(N requirements and N behavior rules, all mapped), what Task 1
proves. The gate is a message question per core.md's Structured
questions: the summary and `plan.md`'s path are the chat message, its
last line asks the user to approve the plan or change it, and the turn
ends there. The user approves before any code is written. Only an
explicit approval passes, and it covers the plan as presented: a reply
that changes a task is an amendment, so update `plan.md` and present
the gate again (core.md's Structured questions). A task changed after
approval is a new plan: delete `plan_approved` and `approved_spec`,
then gate it again. On approval,
first write the changelog entry per core.md's ledger, key
`plan/<id>@Q<n>` from the same highest `§Q`; a re-plan at the same
`Q<n>` wrote something that key does not record, so it appends `.2`,
`.3` to `<rev>` per core.md's ledger rule and records itself. Record
the file map, the task count and titles, and the global constraints
pinned.
Then record `plan_approved: true` and `approved_spec: <checksum of
spec.md>` (`git hash-object spec.md`; any stable checksum outside
git) in the interview frontmatter; `implement` and the chain verify
the approval against it. `plan.md` is covered by the `features/`
Companion docs row; no separate row.
**Consumer:** `implement` executes the 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 |