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/implement.md
View on GitHub# implement - execute the approved feature plan
**Reads:** config → the feature interview's approval frontmatter → `plan.md`
→ `spec.md` → `../code-craft.md` → the operations
chapter its verifications rely on → `standards.md` (Phase C only, the
review lens) → `review-ledger.md` (resume).
Last stage of the feature chain: turns the approved `plan.md` into
code. With `build`, one of the two commands allowed to write source
code (core.md hard rule 2), and only after its plan gate.
**Entry gate:** apply [Execution choice](../core.md#execution-choice)
before prerequisite stages, reference bootstrap or resumed work.
Inherit the current `feature` run's explicit answer; a standalone
invocation always asks and waits, including a review-only or wrap-only
resume. Record the chosen `execution: subagent | inline` in the
feature-interview frontmatter as soon as the file exists; a saved
value never skips the entry gate.
Prerequisite, checked in this order (resolve a `<feature>` argument
as `groom`'s Resume rule does): no folder but an
`implement/<id>` key in the ledger (`changelog.md`, its rotation
files, or an unfolded `changelog.d/` fragment), or a folder with
`implemented: true` and that matching key → the feature is done; say
so, point at the changelog entry, and stop. If the folder remains and
`delete_feature_folders` is true, finish its deletion first, under
Phase D step 6's committed-ledger rule; when the
setting is false, retaining it is expected. `implemented: true` without
the matching key is a torn write for `doctor`; do not re-run or delete
it. Otherwise require the feature's `feature-interview.md` to say
`status: formalized` and `plan_approved: true`, with `approved_spec`
still matching a checksum of the current `spec.md`. A feature back in
its interview (`interviewing`, `awaiting-formalization`) goes to
`protocols/groom.md` first, whatever its approval keys say: that plan
was approved for a spec now being changed. No approval → execute
`protocols/plan.md` first (which chains `groom` when there is no
spec); a checksum mismatch is a voided approval: likewise `plan`.
`plan_approved` with `plan.md` missing or truncated is a crash
`plan`'s Resume rule owns: it voids the approval, rebuilds the plan
and gates it again. No code is written from a plan the user has not
approved as it now reads.
**Resume:** `features/` is gitignored (core-authoring.md's Local-only
outputs), so
the feature's progress lives in the working tree (the worktree's,
once Phase A moved the folder there) and is never branch-scoped:
read `plan.md`'s boxes directly, whatever is checked out, and there is no docs copy to merge forward. The code those boxes
describe IS branch-scoped, so confirm the checked-out branch is the
recorded `branch` before trusting a checked box; on a mismatch, say so
and check the branch out rather than re-running its tasks. A resumed
run keeps the recorded `branch` and `base_commit`: Phase A's branch
offer is made once, and a second `base_commit` would drop the finished
tasks out of the review.
Walk the boxes in order: check off any unchecked step whose
verification already passes, continue executing from the first one
that doesn't. Never redo checked steps; a re-plan never unchecks
one either (plan.md's Resume). Every box checked but
`implemented` absent → only Phases C-D remain; `review-ledger.md`
says where (mid-loop resumes the loop, a recorded dry verdict skips
to the wrap).
## Phase A - setup
Never write to main/master without the user's explicit consent: offer
a feature branch (or worktree) first, named per `../code-craft.md`'s
Git section (`<type>/<slug>`, the slug the feature's own). A new
worktree holds no `features/` (it is gitignored), so when the user
picks one, move `features/<id>/` into the worktree's docs area first
and work from the worktree from then on: the boxes, `review-ledger.md`,
the absorption and the ledger fragment land where the code does. Tell
the user the original checkout no longer holds the feature. Record
`branch` and `base_commit` in the feature-interview frontmatter: the
branch the tasks land on, and its branch point, or HEAD before Task 1
on a consented main run; Phase C reviews the diff from it. Read
`plan.md`, `spec.md`, `../code-craft.md` (the
TDD + YAGNI discipline the code follows; the plan's global
constraints win on conflict), and the operations chapter the plan's verification steps
rely on (`07-operations.md`'s Processes and Developer workflow
sections carry the verified commands). Review the plan critically:
a contradiction between tasks, or between plan and spec, goes to the
user before Task 1, batched, not one interrupt per discovery mid-run.
An answer that changes a task changes the plan: `plan`'s gate runs
again before Task 1 (its Phase C).
## Phase B - execute
This phase reads `plan.md`, `spec.md` and `../code-craft.md`, and
never `standards.md`. The plan's Header carries that file's global
constraints copied verbatim (`protocols/plan.md`'s Header bullet), so
the rules binding this feature sit in front of the executor with none
of the seventeen domains behind them; Phase C is where the rest is
enforced.
Use the execution mode explicitly chosen at entry for this run.
Reaching Task 1 does not ask again or change that choice.
Both modes obey the same rules: tasks in dependency order, steps
exactly as written, every verification run and **passing** before its
box is checked off in `plan.md`, one commit per task per
`../code-craft.md`'s Git section (its density, message format, and
never-a-broken-commit rule; a task is exactly the "one reviewable
idea" that section names), never `git add`-ing the docs area or the
index. Stop and ask instead of guessing when a dependency is missing,
a verification keeps failing, or an instruction can be read two ways.
The checked boxes in `plan.md` are the durable progress record: check
each as it passes, never in batches, so a dead session resumes
mid-task.
### Subagent mode
One subagent per task, dispatched fresh, in plan order. Never two at
once: each task consumes what the previous one defined.
**The subagent's prompt carries everything, because nothing else
crosses into its context.** Copy in, verbatim rather than by
reference:
1. The task's full text from `plan.md`: its `Create:`/`Modify:`/
`Test:` paths, the interfaces it consumes and produces, and every
checkbox step with its code and exact commands.
2. The plan's Header constraints, verbatim, and `../code-craft.md`'s
ladder, TDD scoping, **Comments section, and Git section in full**.
A pointer to a file is useless here: a subagent that never reads
`code-craft.md` commits however it likes, and comments every line
it writes.
3. The conventions chapter's paradigm, typing, and error-handling
rules, plus the operations chapter's verified commands.
4. The rules: execute only this task; run every verification and do
not report success until it passes; commit exactly once, in the
given format; touch no path outside the task's list; never
`git add` the docs area; report the verification output, the
commit subject, and anything ambiguous rather than deciding it.
Then, in the main session: check the task's boxes off yourself against
the reported verification, and dispatch the next. A subagent reporting
a failure it could not resolve, or an instruction it read two ways,
stops the run and goes to the user: never re-dispatch the same task
hoping for a better roll.
### Inline mode
Execute the tasks yourself in the same order, under the same rules,
checking each box as its verification passes.
Either way, code lands in the repository's source tree (never under
the docs area), and every code decision follows the plan's Header
constraints and `code-craft.md`.
## Phase C - review until dry
Entered when every box in `plan.md` is checked (the final task's
verification passing checks the last one). Code complete is not code
reviewed: a single pass cannot catch bugs introduced by its own
fixes, so review recursively: loop over the feature's full diff
(`base_commit`..HEAD, from Phase A) until the loop proves itself
dry. The loop's state lives in the feature folder's
`review-ledger.md` (beside the plan; never indexed): every finding
ever raised with its verdict, the dry-round count, and the final dry
verdict; a resumed session picks the loop up from it instead of
restarting at round one.
1. **Round**: independent reviews of the diff, each through a
different lens: spec compliance (every `spec.md` requirement
implemented, nothing extra), code quality per `standards.md`,
`code-craft.md` (unearned abstractions, unclimbed ladder rungs,
and comments that only restate the code are findings), and
the conventions chapter, and the spec's unhappy paths actually
exercised by the tests. **This is the run's only read of
`standards.md`, and enforcement lives here on purpose**: the
reviewer has the budget for it and the implementer, which explores,
writes and debugs against a plan, does not. Fresh eyes every
round: in the user's selected subagent mode, dispatch one reviewer
per lens; in inline mode, re-read the diff yourself once per lens,
coldly, even when subagent tools are available.
2. **Verify**: adversarially check each finding before acting: try
to refute it against the spec, the plan, and the reference. Every
finding goes into the ledger, confirmed or refuted; a round counts
only findings not already there: dedupe against the ledger, not
against the confirmed list, or refuted findings reappear and the
loop never converges.
3. **Fix**: confirmed Critical/Important findings are fixed and
their covering verifications re-run; fixes are new code and
re-enter the next round. Minor findings: fix or record, per
`standards.md`.
4. **Dry**: a round with zero new confirmed findings. Two
consecutive dry rounds end the loop; one is not enough: the
round after a fix wave exists to review the fixes. Record the dry
verdict in the ledger; Phase D resumes read it.
Both execution modes start this loop at round one: neither performs a
whole-branch review of its own, and a per-task subagent has seen only
its own task, so nothing it reported counts as a review of the diff.
In subagent mode the round's lenses may themselves be dispatched in
parallel, one reviewer per lens, each reading the full diff.
## Phase D - wrap
Entered when Phase C goes dry.
1. The spec's Reference impact chapters are now stale by construction:
run the `map` refresh on them in this run's chosen execution mode
so the reference records what was actually built, divergences
included. Where that list carries a
confirmed cross-repo edge (`groom` Phase A step 4), write the
repo name into that row's `to` or `from` in
`09-interfaces.md`'s `edges:` block afterwards: the refresh writes
`kind`, `name`, `site` and `schema` and never those two values
(core.md's Edge confirmation), so an answer the user already gave
lands here or nowhere.
2. **Absorb the spec**: `features/` is local-only, so this is where
its knowledge becomes durable. Per the spec's Reference impact
list: merge the Behavior section into `logic/` (a new
`NN-<scenario>.md` for a new scenario, amendments inside the named
files otherwise; as built, divergences from the spec recorded as
the shipped rule); update the `mockup/` screens the feature
changed; update the touched `uiux/screens/` chapters, and
`uiux/02-system.md` only when the spec recorded a token or lock
change. Every absorbed or created file gains
`absorbed_from: features/<id>@<date>` in frontmatter;
refresh the folders' README indexes and Companion docs rows.
3. Write the changelog entry per core.md's ledger (a `changelog.d/`
fragment): key
`implement/<id>@Q<n>`, the same highest `§Q` (this stage adds
none, so the key is stable across a resumed review loop). The
entry stays a fragment here: folding is main-only per the ledger
rule, and this run is normally on a feature branch. This run never
commits the docs area (Phase B), so the fragment reaches the
branch only once the docs area is committed, which the user or the
repo's own flow does; from there it merges as its own file, and
the next writing run on main folds it. On a consented main run,
fold per the ledger rule, this entry included.
**Step 6 may delete the feature folder, so write this entry to be
read without the spec beside it when `delete_feature_folders` is
enabled.**
Bullets only, per the ledger's entry format. This is the longest
entry any stage writes and still never a narrative:
- **What**: the feature in one line, and for whom.
- **Approach**: the one taken; then one bullet per alternative the
spec rejected, each with its reason.
- **Out of scope**: one bullet per ruling.
- **Tasks**: the completed list, one line each.
- **Diff**: the paths `base_commit`..HEAD touched.
- **Chapters refreshed** (step 1) and **scenarios absorbed**
(step 2): one bullet per file, naming what it gained or amended.
- **Review loop**: rounds run, findings confirmed / fixed /
refuted, and the dry verdict, from `review-ledger.md`.
None of that is recoverable once the folder is gone; the shipped
behavior lives in `logic/` and the chapters, but the reasoning
lives only here.
4. Only now record `implemented: true` in the feature-interview
frontmatter: the chain's done marker, written after the refresh
and the absorption for the same reason `formalized` waits for
outputs (a crash can't strand a "done" feature with a stale
reference). The lifecycle `status` has been `formalized` since the
spec landed.
5. Finish the branch: the repo's own merge flow, following whatever
`git log` shows it uses (on a consented main run there is no branch
to finish, just the repo's push conventions). Ask before opening a
PR or pushing; neither is implied by the plan's approval.
6. Apply `delete_feature_folders` (default `false`) last, after step
3's entry is committed and the branch is finished. When it is
`true`, delete `features/<id>/`: the spec is absorbed into `logic/`,
`mockup/`, and `uiux/`, and the ledger's counts are in the entry.
That entry is the only record deletion leaves, and this run never
commits the docs area (Phase B), so check `git status` first: while
the fragment, or the `changelog.md` it was folded into, is
untracked or modified, keep the folder, say the ledger has to be
committed first, and let the next run finish the delete.
When it is `false`, retain `features/<id>/` as ignored local history
and report that it was preserved. In either mode the
`implement/<id>` ledger key is the done marker, and a retained folder
is not unfinished work.
From here the **changelog key is the done marker**: the id is
retired and never reused, and every stage-detection rule below
reads an `implement/<id>` key in the ledger (fragments included) as
done, whether the folder is present or absent. A folder still
present with that key is expected when `delete_feature_folders` is
false; when it is true, it is a torn wrap: finish the delete, never
re-run the stage (`doctor` repairs this).
Close by naming `review retro`: this session is the evidence it
reads, and a shipped feature is the most common one worth reading.
Name it, do not run it - retro proposes edits to the user's own
steering files and starts when they ask.
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: 470k | Updated | Claude CodeCodex | Unverified | 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 |