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/start.md
View on GitHub# start - the greenfield pipeline, one stage at a time
**Reads:** config → each stage's interview file (status frontmatter)
and the presence of its outputs; the six pre-`build` stages' final
outputs, plus core.md's Stage ownership table and the five inventories
step 7's coverage half walks (`logic-craft.md`, `uiux-inventory.md`,
`interview.md`, `standards-inventory.md`, `protocols/stack.md` Phase A),
once, for the readback pass (step 7); nothing else until a stage's own
protocol runs. An argument routes straight to one protocol and reads
none of the above, except `start build` when it runs the readback
pass first (Routing).
Entry point when the user says just "capstone" or asks to start or
continue the pipeline, and the owner of every stage the pipeline runs:
no stage is a command of its own, each is reached as `start <stage>`.
Runs the interview chain in order, resuming wherever it stopped:
1. `mockup` → `docs/capstone/mockup/` (+ `mockup-interview.md`)
2. `logic` → `docs/capstone/logic/` (+ `logic-interview.md`)
3. `uiux` → `docs/capstone/uiux/` (+ `uiux-interview.md`)
4. `architecture` → the prescriptive reference
(+ `architecture-interview.md`)
5. `standards` → `docs/capstone/standards.md`
(+ `standards-interview.md`)
6. `stack` → the researched, user-picked stack in `05-dependencies.md`
(+ `stack-interview.md`)
- then the **readback**: the cross-stage pass of Procedure step 7.
No subcommand, no outputs of its own.
7. `build` → `docs/capstone/implementation.md`, then working code
(+ `build-interview.md`)
## Routing
An argument routes; it does not change what the pipeline is. Match the
first argument against the stage words; the rest of the arguments are
that stage's own (an artifact path for an interview stage, `refresh`
for `stack`).
| Argument | Runs |
| --- | --- |
| none | the pipeline below, from the first incomplete stage |
| `mockup` `logic` `uiux` `architecture` `standards` `stack` `build` | `protocols/<stage>.md` exactly, that one stage alone |
| `stack refresh` | `protocols/stack.md`, which reads `refresh` |
| `retro` | nothing here - it is `review retro`, not a stage. Say so and route there |
| anything else | the pipeline, treating the argument as a seed artifact if it names a readable file, and otherwise ignoring it |
A directly entered stage is the same stage the pipeline runs, entered
mid-chain: it applies [Execution
choice](../core.md#execution-choice) itself (Procedure step 1), reads
`../core-authoring.md` (Procedure step 5) and
its own prerequisites, runs its own formalization gate, and writes its
own changelog entry. It does not run the stage after it, and it does
not run the readback pass, which belongs to the pipeline. Report what
the stage left unfinished in one line when it ends, naming `start`
with no argument as the way to continue the chain.
Entering a stage whose prerequisites are missing is not an error to
route around: say which stage owns the missing input and stop, rather
than interviewing for it here.
`start build` is the one exception to both rules. Entered directly, it
first runs `stack` when the stack output is not formalized, then the
readback pass (Procedure step 7) when no `readback/all@<stamp>` key
matches the current outputs, and only then `build.md`: code is never
written from outputs the readback has not read.
## Procedure
1. Per core.md: read the config (expertise governs every stage's
conversation; `pipeline` records the fork below).
Apply [Execution choice](../core.md#execution-choice): always ask
subagents or inline on entry, including a resumed pipeline, and
wait for the answer before stage work, readback or the fork's
`map` run. Carry the answer through every stage.
2. Determine each stage's state from its interview file and outputs,
per core.md's Interview lifecycle:
- **not started**: no interview file, no complete final outputs, and
no matching stage changelog key.
- **mapped drafts**: `logic/` or `uiux/` files `map` extracted,
with no interview file and no changelog key under that stage.
Not started, for the pipeline: the stage runs, and treats those
files as drafts to confirm or correct, never as decisions.
- **in progress**: status `interviewing` or
`awaiting-formalization` (for the latter, resume by re-presenting
the stage's formalization gate, never generating without the
user's approval; exception: `build` with `plan_approved: true`
resumes coding per its Resume rules instead of re-gating), or
`logic` with pending scenarios in its checklist. On a clone with
no `logic-interview.md` and no `logic/all` key, `logic` with
scenario keys is in progress too: resume by reading the mockup
README's Scenarios table against the `logic/` files present (a
file present is written), never re-asking a written scenario.
- **done**: complete final outputs and the matching stage changelog
key are present. Local interview frontmatter saying `formalized`
confirms the same state when it exists but is not required on a
fresh clone;
`formalized` with no key is repairable: append the missing entry
from the recorded decisions, without re-interviewing. Status
`awaiting-formalization` with complete outputs and the stage key
is done as well: the run stopped between its entry and the
marker, so set `status: formalized` and do not re-gate. `logic`'s
stage key is `logic/all@Q<n>`, which its wrap writes; its
per-scenario keys alone are not done. `build` is done only when
every build-order step in `implementation.md` is checked and the
`build/code` key exists; the walking skeleton running is a
milestone, not done. A
`uiux/skipped@Q<n>` key is done with no outputs: the product
has no visual surface, so nothing is missing.
- **outputs missing**: status `formalized` or a stage changelog key
exists, but outputs are missing or partial. Regenerate from the
interview only when that local working record still exists;
otherwise never invent the missing decisions: stop, tell the
user the loss is unrecoverable and the stage has to be
interviewed again, and re-run it only when they say so.
3. Hold the pipeline as progress tasks per core.md's Progress tasks
rule, one per stage plus one for the readback pass (step 7), so the
user sees where they are; the running stage's protocol adds its own
tasks beneath. `uiux` formalized
with `skipped: no-ui` shows as "skipped (no UI)".
4. The generate-vs-pipeline fork, asked at most once ever:
- Skip it entirely when config `pipeline` is `true`/`false`, or when
a stamped descriptive index already exists (an index without
`mode: prescriptive` files proves the user chose `map`), or
when any stage has started.
- Otherwise, if the project has source code (≥1 tracked source
file, the same measurement as `map`'s Phase 1 step 8), ask
whether they want this greenfield pipeline or `map`, and
write the answer to the project config's `pipeline` key (per
core.md, creating `docs/capstone/capstone.json` holding just
that key if absent).
- On a `map` answer: execute `protocols/map.md` now and
end the pipeline run. The same holds for the answer already on
record: with `pipeline: false`, or a descriptive index and no
stage started, this is `map`'s project, so run `map` and end
here instead of opening a greenfield interview on a mapped repo.
5. Run the first non-done stage by executing its protocol file
(`mockup.md`, `logic.md`, `uiux.md`, `architecture.md`,
`standards.md`, `stack.md`, `build.md`) exactly, including its
own formalization gate. Do not blend stages. Before the first
stage protocol or the readback pass, whichever comes first,
read `../core-authoring.md`: the
wrapper left it out because routing needs none of it, and every
stage and the readback land their outputs under its rules (artifact
seeding, the index row, the local-only ignore list). `build.md` runs only
after step 7's readback pass. A cross-repo edge the design
declares is confirmed inside `architecture` per core.md's Edge
confirmation; `start` carries its execution choice into the stage.
6. When a stage formalizes, announce it in one line and continue to
the next ("mockup done; moving to logic; say stop to pause").
Stopping is always safe: every stage persists its interview file,
and the next `start` resumes exactly here.
7. **Before `build`, read the final outputs back.** No stage can see
every later stage while it runs, so this pass checks coverage,
ownership and contradictions across the completed body of work. The
final files are the only decision sources: completed interview
bodies are not opened, cited, or amended.
Run it when the stack output is formalized and the ledger
(`changelog.md` and unfolded `changelog.d/` fragments, per
core.md) carries no `readback/all@<stamp>` key, before executing
`build.md`.
`<stamp>` is a stable hash of the ordered latest changelog keys for
the six stage outputs, so unchanged outputs skip and any amended
stage runs the pass again. Compute it once, before the pass edits
anything, and record that value in `readback/all@<stamp>`; the
`<stage>/readback@<stamp>` entries the pass itself writes are left
out of the latest keys it hashes, so a later run computes the same
stamp and does not re-run the pass.
Read the final `mockup/`, `logic/`, `uiux/`, architecture chapters,
`standards.md`, and `05-dependencies.md`, then run the three halves
in order: coverage first, because a decision nobody made is cheaper
to settle before the other two argue about what is there, then
misplacement, so the contradiction half cites final locations.
**Coverage: what nobody asked.** Each stage was gated on an
inventory. Walk each one against that stage's final outputs and
collect every required item those outputs neither decide nor rule
out:
| Stage | Inventory | Final outputs |
| --- | --- | --- |
| logic | `logic-craft.md` §3's dimensions D1-D16 | `logic/*.md`, each file's `## Dimensions not in play` |
| uiux | `uiux-inventory.md` §3's system items and §4's screen items | the `uiux/` chapters and `screens/`, each file's `## Not in play` |
| architecture | `interview.md` §0-§4 | the prescriptive chapters |
| standards | `standards-inventory.md` §3's domains and §4's items | `standards.md` and its `## Not in play` |
| stack | the capability list `stack.md` Phase A derives | `05-dependencies.md` |
A ledger carrying a `uiux/skipped@Q<n>` key exempts `uiux`: the
pass skips every uiux row of this table and reads no `uiux/` files.
An item is covered when an output records a decision for it, or
records it inapplicable with a reason. An item another stage's
output settles and this one cites is covered as well. Everything
left over is a finding.
Nothing is being argued here, only asked, so this half is **one
digest rather than a debate** like misplacement: a numbered list,
each line naming the stage, the item, and the final file the answer
would land in ("3. standards, S65 idempotency → `standards.md`, API
conventions"). It is a message question per core.md's Structured
questions: the numbered list is the chat message, its last line
asks for the answers, and the turn ends there. The user answers,
skips, or rules one out. Every
answer is written into the owning final file with its
rationale, that file's stamp refreshed, and the owning stage's
changelog entry appended; an item ruled out is written as an
inapplicable line in the file its own inventory names for that.
Skipped items are named in the pass's own entry, so the next run
raises them again.
The digest is short by construction: an item its output already
answers never reaches it, and on a project whose stages each ran
their own gate the digest is empty. Report an empty one in a single
line ("coverage: nothing uncovered across the five inventories")
rather than passing over it in silence, so the user knows it ran.
**Misplacement: move it to its owner.** Against core.md's Stage
ownership table, collect every decision whose subject belongs to a
different stage, plus every decision one stage restates in its own
words that another final file already owns. A cross-reference to an
owning final file is correct and is not a finding.
Nothing is being re-decided here, only re-filed, so this half is
**one digest rather than a debate**: list every move as a line
("the wind-down threshold: `01-architecture.md` →
`logic/03-wind-down.md`") in the chat, as a message question like
the coverage digest, and the user confirms the set, corrects
a destination, or strikes a move. On confirmation, write the
decision and its rationale into the owner's final file, remove it
from the non-owner, and replace any needed mention there with a
citation to the owning final file. Refresh the changed files'
stamps, the index's `Settles`, `Not here`, and Terms ownership, and
each owning stage's changelog entry. A missing owner file or
scenario is created through that stage's protocol rather than
improvised here.
**Contradiction and pushback: raise it.** Collect what the Pushback
rule's Grounds make a finding across two final outputs: decisions
that contradict each other, or one that cannot meet a number the
other records. Raise these one per turn, ordered by blast radius,
with both final file locations cited, under the same two-round cap;
then the user's answer stands. Write the resolution and rationale
into the owning output and update or remove the superseded rule in
the other output.
Every output either half changes takes its changelog entry, keyed
to the stage that owns it (`standards/readback@<stamp>`).
Close the pass with its own entry, key
`readback/all@<stamp>`, even when it found nothing: it names the
final files read, every uncovered item the coverage half raised with
how each was answered, skipped or ruled out, every decision relocated
and where it went, every finding, and how each was settled. Stopping
mid-pass is safe:
applied resolutions stand, the key goes unwritten, and the next
`start` re-runs the pass.
8. After `build`, close out: the project runs. Point at everything
generated, and note that from now on plain `map` runs replace
prescriptive intent with observed fact as the code evolves, and
that `review retro` reads this session and proposes the instruction
edits it earned. Name it; do not run it. Retro proposes edits to
the user's own steering files one approved row at a time, so it
starts when the user asks, not as the pipeline's last act.
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 |