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/core-authoring.md
View on GitHub# Authoring Rules (read by every subcommand that writes an output)
The companion to `core.md`: how a stage seeds itself, delegates
method to an installed skill, and lands its output in the docs area.
`start` and `feature` route rather than write, so they read
only `core.md`; everything else reads both.
## Local-only outputs: `<docs_dir>/.gitignore`
Some outputs are personal working state and are **never committed**,
whatever `docs_in_git` says: `features/` (the whole feature chain:
interviews, specs, plans, review ledgers), every `*-interview.md`,
and `review.md` (plus the legacy `be-review.md` and
`fe-review.md` older versions wrote) with `review/`, the folder of
screenshots `review` saves as evidence (no index row: they are the
report's attachments, not outputs). Two more join them from the
`uiux` stage: `uiux/preview.html`, the rendered picture of
`02-system.md` that Phase D' writes for the user to steer by (Index
maintenance below says the outputs are markdown, and a picture of a
decision is not the decision), and the raster brand assets under `uiux/assets/` -
`*.png`, `*.jpg`, `*.jpeg`, `*.webp`, and the whole
`uiux/assets/references/` folder of screenshots and mood boards, which
are exports and reference material rather than sources.
`uiux/assets/*.svg` is **NOT** on this list and must never be added:
the SVG is the mark itself, the file `build` moves into the app and
rasterizes the favicon, app icon and `og.png` from, and a logo that
lives on one machine is not a brand. `changelog.md` and the
`changelog.d/` fragment folder are NOT on this
list, and unlike the chapters they do not follow `docs_in_git`
either: **the ledger is always committed** (core.md's Changelog
ledger says why - it is the durable shipped-feature marker, and with
`delete_feature_folders: true` it is the only record left after
`implement` deletes a feature's folder). `capstone.json` is off the
list too: it is the
project's shared config, committed for the same kind of reason - it
holds the settings every run on the repo follows and the project's
state, and a config that lives on one machine is not a standard
(core.md's Project config paragraph). `questionnaires/` stays off the
list as well (core.md's Questionnaires section): each file is a real
artifact sent to a real person and the record of what was asked of
them, and a record that lives on one machine is no record at all. The
initializer's per-project run writes `<docs_dir>/.gitignore` listing
exactly the local-only set, and deletes the `changelog.md` and
`capstone.json` lines older versions wrote; whenever you write into
`<docs_dir>` and that file is absent,
create it (`edges` aside: it writes into other repos' docs areas and
leaves their housekeeping to `map` and `doctor`): the same idempotent
initializer without the global flag
(`init-config.sh [docs_dir]`, via bash on every platform) does
that, the legacy migration below, and the retroactive untracking. The
`.gitignore` itself is committed, so the rules travel with the repo.
**`groom`, `plan`, and `implement` never commit the docs area.** They
commit source code only: `implement`'s per-task commits name the paths
the task touched and never `git add` `<docs_dir>` or `<index_file>`.
Reference chapters that `implement`'s wrap refreshes are left staged
or dirty for the repo's normal flow to handle, per `docs_in_git`.
## Legacy path: `docs/design`
Capstone used to default to `docs/design`. The
initializer (its per-project run, per Local-only outputs above)
migrates that layout automatically and idempotently: when
`docs/design` exists and `docs/capstone` does not, it moves the tree
(`git mv` when tracked, so history follows), repoints the moved docs'
cross-references, the index, and a `docs_dir` that named the old
default (a custom one is left alone), then untracks whatever the
ignore list below now covers. Say what it reported. If both
directories exist it merges nothing and `docs/capstone` wins; resolve
that with the user.
## Legacy folder: `design/`
The uiux stage used to write `docs/capstone/design/` and
`design-interview.md`, back when it was called `design`. The
initializer's per-project run migrates both idempotently: `design/`
present with no `uiux/` → move the tree (`git mv` when tracked),
likewise the interview file, then repoint the moved docs'
cross-references. Both present → nothing is merged, `uiux/` wins;
resolve that with the user. Say what it reported.
## Artifact seeding
Every interview stage accepts an optional
artifact argument: a PRD, a notes file, screenshots, an export. Read
it first; pre-fill every question it answers as `§Q` entries marked
`source: artifact`, quoting the artifact's own words; present ONE
digest ("the PRD answers Q1-Q9; confirm or correct") whose
confirmation turns them into decisions; then interview only what
remains. The digest is a message question per core.md's Structured
questions: every pre-filled answer is listed in the chat with its
number and the artifact's words, the message closes by asking the
user to confirm or correct by number, and the turn ends there. A
question that asks whether "items 1-7" stand, about a list the user
was never shown, has confirmed nothing. One-way doors (irreversible decisions per `interview.md`'s
conduct rules) are never taken from an artifact silently: each is
re-confirmed individually.
## Interviews are working state, not references
An interview is the resumable working record for its stage. While the
stage is `interviewing`, use it to resume questions and to generate the
stage's outputs. Once the stage is `formalized`, those outputs are the
source of truth: every confirmed decision, rationale, constraint, open
question, and deferral needed by a later reader must be written into
them.
Final outputs must stand alone and must be written as if interview files do not exist. They never cite, link to, name, or instruct a
reader to consult an interview file or one of its `§Q`, `### Q`, or
`### D` entries. Question numbers may remain in the changelog key
required by `core.md` and in the interview itself; they do not appear
in the final output. Downstream stages read formalized outputs, not
completed interviews. If a needed decision exists only in a completed
interview, repair the owning output from that record before continuing.
## Index maintenance
The index is `<index_file>`, default
`docs/capstone/00-index.md`: chapter zero, living beside the chapters
it indexes rather than at the repository root. Every file this plugin
writes under `<docs_dir>` must be listed there:
- **Topic index**, a `| Topic | File |` table: the chapterized
filenames (`01-architecture.md` ... `08-glossary.md`, so the folder
reads in order even without the index), plus `logic/`'s per-scenario
files, one row per file under the `logic` topic name (the same
split-topic mechanic map.md uses for a monorepo's per-subsystem
chapters). Topics that do not apply get a row naming the reason:
an absence is a fact, and no file can record it.
- **Companion docs**, a `| File | What it is |` table: everything else
(review, changelog, standards, implementation,
mockup/, uiux/, features/, questionnaires/). The
`questionnaires/` row is one row for the folder, whatever it holds,
and the stage that writes the first file adds it (core.md's
Questionnaires section).
**The index carries no stamps.** Freshness lives in each file's own
frontmatter (`generated_at_commit`, `generated_date`,
`capstone_version`, `paths_covered`), which is what `map` reads;
copying it into the
index would only create a second copy to drift. The index answers what
exists and where, never how fresh it is.
The index does not list itself, and is never a topic. All indexes and
outputs are markdown; never generate HTML, for anything. Never
indexed: the interview Q&A files (`architecture-interview.md`,
`mockup-interview.md`, `standards-interview.md`,
`logic-interview.md`, `uiux-interview.md`, `stack-interview.md`,
`build-interview.md`, `features/*/feature-interview.md`,
`features/*/review-ledger.md`), `changelog.d/` fragments (working
state of the ledger; `changelog.md` and its rotation files get
Companion docs rows, the fragment folder does not), and
`capstone.json`.
After writing your output, write your changelog entry (a
`changelog.d/` fragment per the Changelog
ledger in `core.md`), then add or refresh your row; if `<index_file>` does
not exist yet, create a minimal one (title + the two tables) rather
than leaving the output orphaned.
**Legacy index:** capstone used to write `DESIGN.md` at the repository
root. A root `DESIGN.md` present with no `<index_file>` in the docs
area is that layout: move it (`git mv` when tracked), repoint the
moved docs' cross-references, drop its stamp columns per the rule
above, and say what you did. Both present → the docs-area index wins;
resolve the root file with the user.
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 |