{ "markdown": "

\n \"Capstone\"\n

\n\n

\n Your agent, on rails.
\n Every rule decided before a line is written.
\n Every doc read before a token is spent.\n

\n\n

\n \n \n \n \n

\n\n

\n \n \n

\n\n

\n Architecture docs your AI agent reads instead of re-exploring the repo\n every session. Stamped to commits, refreshed only where the code\n moved. For new projects, an interview pipeline that designs the whole\n thing before building it.\n

\n\n

\n \"Three\n

\n\n

\n Running a fleet of repos?\n Quarry gathers every\n capstone reference into one indexed docs repo, so \"what breaks if I\n change this endpoint\" is a one-line query from any terminal.
\n Capstone writes the edges; quarry walks them.\n

\n\n

\n Install ·\n Update ·\n Where to start ·\n What you get ·\n Commands ·\n Pipeline ·\n Feature chain ·\n Review ·\n Not technical?\n

\n\n

\n Full detail on every command: docs/commands.md.
\n How the three run, in diagrams: docs/flows.md.\n

\n\n---\n\n## Install\n\n### Claude Code\n\n```text\n/plugin marketplace add GentBajko/capstone\n/plugin install capstone@capstone-marketplace\n```\n\n### GitHub Copilot\n\n```bash\ngh skill install GentBajko/capstone --all --agent github-copilot\n```\n\n### Any other agent\n\n70+ editors and CLIs via the skills CLI:\n\n```bash\nnpx skills add GentBajko/capstone\n```\n\nPer-agent commands and the bare-`/capstone` alias are under\n\"Installing on other agents\" below.\n\n## Update\n\nNo reinstall needed. Update in place:\n\n| Installed with | Update with |\n| --- | --- |\n| Claude Code plugin | `claude plugin marketplace update capstone-marketplace`
then `claude plugin update capstone@capstone-marketplace` |\n| `gh skill` | `gh skill update capstone` |\n| `npx skills` | `npx skills update` |\n\nThe Claude Code pair is two steps on purpose: the first refreshes the\nmarketplace clone, the second moves your install onto it. Restart to\napply. To skip it entirely, turn on auto-update: `/plugin` →\nMarketplaces → capstone-marketplace → Enable auto-update.\n\n> [!IMPORTANT]\n> **Updates are additive.** `gh skill update` and `npx skills update`\n> refresh files but never delete a skill that capstone has retired, so\n> a removed command lingers on disk and keeps being offered to your\n> agent. After any release that drops commands, compare\n> `gh skill list` or `npx skills list` against the command tables\n> below and remove whatever is no longer there.\n\n---\n\n## Where to start\n\n| Situation | Command |\n| --- | --- |\n| A repo that already has code | `/capstone:map` |\n| A product that doesn't exist yet | `/capstone:start` |\n| One change to a mapped project | `/capstone:feature add CSV export` |\n\nEverything else is a stage one of those runs, invocable on its own\nwhen you want to enter mid-chain.\n\n## What you get\n\n`/capstone:map` produces a `00-index.md`, up to nine numbered chapters\nbeside it in `docs/capstone/`, and a `logic/` folder mapping the\nobserved business logic scenario by scenario:\n\n```text\n01-architecture.md layers, boundaries, entry points, dispatch tables\n02-models.md entities, relationships, schema DDL, validation\n03-conventions.md paradigm, typing level, error handling, DI\n04-data-flow.md lifecycles hop by hop, state ownership, failure paths\n05-dependencies.md every package, what it's for, where it's wired\n06-testing.md layout, test doubles, coverage shape\n07-operations.md how to run it, env vars, infra, deploy\n08-glossary.md the domain words your codebase invented\n09-interfaces.md cross-repo edges both ways, and the names it goes by\n```\n\nEverything is facts with `file:line` citations, never advice. Every\nfile records the commit it was derived at, a content hash that\nsurvives squash and rebase merges, and the globs it covers, so\na later run rewrites only what actually moved - and every command\ndeclares what it reads before acting, so re-runs don't burn tokens\nre-exploring what the docs already know.\n\nA command that needs the reference and finds none builds it first\ninstead of sending you off to run something else.\n\n## Commands\n\n**Reference**\n\n| Command | What it does |\n| --- | --- |\n| `/capstone:map` | Build the reference, or refresh only what drifted. `rebuild` forces a full rewrite; a topic name targets one chapter |\n| `/capstone:map check` | Read-only trust report in two halves: a bash script (staleness, ledger fragments, schema: stamps, `known_as`, headings, edge sites, payload sections, model references, secret shapes; the CI gate, no API key) and the model's review (pointer drift, absorption, re-vetting, coverage). Writes nothing |\n| `/capstone:doctor` | Diagnose and repair the docs area: torn writes, index drift, voided approvals, absorption gaps |\n| `/capstone:review [be\\|fe]` | The opt-in judgment → `review.md`. No argument does both sides; `backend` takes architecture, `frontend` grades the UI against your own design docs |\n\n**Greenfield pipeline** - `/capstone:start` runs these in order\n\n| Command | What it does |\n| --- | --- |\n| `/capstone:mockup` | Product discovery → one file per screen |\n| `/capstone:logic` | Business logic, scenario by scenario |\n| `/capstone:uiux` | How the UI looks and the UX behaves |\n| `/capstone:architecture` | The big design interview → prescriptive chapters |\n| `/capstone:standards` | How code should be written here |\n| `/capstone:stack` | Research libraries and services per capability; you pick |\n| `/capstone:build` | Implementation plan, your approval, then working code |\n\n**Feature chain** - `/capstone:feature` runs these in order\n\n| Command | What it does |\n| --- | --- |\n| `/capstone:groom ` | Doc-grounded feature interview → a traceable spec |\n| `/capstone:plan ` | Task-by-task TDD plan; you approve before any code |\n| `/capstone:implement ` | Execute the plan, review until dry, absorb back into the docs |\n\nPlus `/capstone:help` for usage - in Claude Code a hook answers it\nbefore the model is invoked, so it costs zero tokens.\n\nNot a command: `docs/capstone/changelog.md`, the ledger every writing\ncommand records itself in before it sets its done marker. New entries\nland as one file each under `changelog.d/`, so parallel doc-carrying\nPRs never conflict; the next writing run on main folds them in.\n\n**[Full command reference →](docs/commands.md)** - every argument,\noutput, prerequisite, ledger key, and the shared mechanics.\n\n---\n\n## The greenfield pipeline\n\n```text\nmockup → logic → uiux → architecture → standards → stack → build\n```\n\nType `capstone` and it runs the stages in order, resuming wherever you\nstopped. Every answer is written to disk before the next question, so\na dead session loses nothing. Each interview takes an optional\nartifact (a PRD, screenshots) and pre-fills what it answers. On\nexisting codebases, `logic` and `uiux` run in reverse: they draft\nfrom the observed code and you confirm.\n\n**mockup**. Product discovery. Three fixed questions, then every\nquestion after that is generated from your answers until nothing is\nleft to invent. One file per screen: ASCII wireframe, the elements and\nwhere they lead, the states each screen has. It depicts rather than\ndecides - the moment an answer would be a rule, it names the behavior\nand hands the question to `logic` instead of guessing a number that\nwould only be contradicted later. What it hands over is the list of\nthings the product has to decide, which is what makes the next stage\nfast. No visual UI? It records your surfaces (api, cli) and the uiux\nstage skips itself.\n\n**logic**. One scenario at a time, walked until a developer could\nimplement it without inventing a single rule: exact steps, real\nformulas, what happens when the payment fails or the user clicks\ntwice. The part of a spec everyone skips and then pays for. It is\nexhaustive on purpose - every scenario is swept against sixteen rule\ndimensions, so it finishes when each is answered or explicitly ruled\nout, never when nothing else comes to mind. That is what catches the\nrules with no natural question behind them: what the system\ndeliberately hides, what it deliberately never says, who eats the cost\nwhen a charge fails after the money moved.\n\n**uiux**. How it looks and feels: a design read, the visual world,\nthe tokens, each screen's composition and states. The method is\nvendored, distilled from `impeccable` (Apache-2.0) and\n`design-taste-frontend` (MIT), so the same product designs the same\nway on any machine. Before the gate it writes `uiux/preview.html`, a\nsingle self-contained page showing the committed tokens as the\nflagship first viewport and a style tile, so you steer the design by\nlooking at it rather than by reading hex values.\n\n**architecture**. The big interview. Done only when every section of\nthe future docs is answerable from your recorded decisions. Writes\nthe same numbered chapters, marked prescriptive; once code exists,\n`map` replaces intent with observation.\n\n**standards**. Typing strictness, library versus hand-rolled, error\nhandling, what an AI must never do in your repo. It sweeps seventeen\ndomains from an inventory - security, logging and privacy, API\nconventions, accessibility, performance budgets and the rest - and is\nfinished only when every item is answered, accepted from the craft\nfile, or written down as not in play. Also a decent starting point for\na CLAUDE.md.\n\n**stack, then build**. `stack` researches real options per\ncapability, licenses and prices included; you pick, and\n`stack refresh` re-vets the picks months later. The capability list\ncomes from your own chapters rather than a stock list, and every\ncapability reaches you as options, writing it yourselves among them,\nwith the ladder recommending rather than deciding for you. `build` writes an\nimplementation plan, stops for your approval, then writes the code:\none subagent per step with fresh context, or inline, whichever you\npick when it starts.\n\nBetween the two, the pipeline reads all six stages' final outputs. It\nmoves what landed in the wrong file to the stage that owns it - a\nbusiness rule in an architecture chapter belongs in `logic` - and\nraises contradictions between final files. Same terms as everywhere\nelse: evidence and final-file citations, two rounds at most, then your\nanswer stands. The corrected decisions and rationale are written into\ntheir owning final outputs; completed interview bodies are not read or\namended.\n\n## The feature chain\n\n`/capstone:feature add CSV export` grows a finished project one\nfeature at a time. `groom` interviews a spec out of you against the\nreference. `plan` turns it into a task-by-task TDD plan; a vendored\nTDD + YAGNI ladder trims every task, and your standards outrank the\nladder on conflict. `implement` executes, reviews the diff until two\nconsecutive rounds find nothing new, then absorbs the shipped\nbehavior back into the scenario docs. A dead session resumes\nmid-chain.\n\n## What `review` is\n\nThe one command allowed opinions, only when invoked. Two sides, one\n`docs/capstone/review.md`, each section carrying its own stamp so you\ncan tell how old each half is.\n\nThe **frontend** side judges the UI against your own design docs\nfirst, then a vendored craft floor, then each screen's mode,\nscreenshotting the live app when it can. The **backend** side covers\narchitecture and backend: shallow modules by the deletion test,\nchange-smells in the git hot paths, security, stack currency.\n\nBare `review` runs both; one argument runs one side and rewrites only\nthat section. Both judge by capstone's own vendored craft files, so\nthe same codebase is judged the same way on any machine. One rule\noutranks the craft baseline: **your recorded decisions beat generic\nbest practice.** Gitignored by default - it is judgment, not\nreference.\n\n## Not technical? Still yours\n\nSet `expertise: 1` and everything happens in plain language: capstone\nasks how many people might use the thing rather than what your p99\nlatency budget is, derives the technical targets itself, and confirms\nthem in words you can sanity-check. Set `teaching_mode: true` and it\nnarrates what it's doing and why as it works, naming the proper term\nfor each concept, one per step, so you learn the craft along the way.\nThe output stays rigorous either way. Engineers set `expertise: 5` for\nterse questions and trade-off tables.\n\n---\n\n
\nSettings\n\nInstalling creates `~/.claude/capstone.json` (the first session after\ninstall runs the plugin's SessionStart hook): one config for the\nuser, shared by every project.\n\n```jsonc\n{\n // Comments ship in the created file too; capstone reads around them.\n \"expertise\": null, // null = ask once | 1-5, vibe -> architect\n \"teaching_mode\": false, // narrate each step and the concept behind it\n \"docs_dir\": \"docs/capstone\", // where generated docs land\n \"index_file\": \"docs/capstone/00-index.md\", // chapter zero of the docs area\n \"subagent_threshold\": 150, // where map fans out to subagents\n \"docs_in_git\": \"ask\", // \"commit\" | \"ignore\" | \"ask\"\n \"language\": \"en\", // language of the generated docs\n \"non_interactive\": false, // resolve defaulted prompts silently (CI)\n \"extract\": [\"logic\", \"uiux\"], // map's extraction passes; [] skips both\n \"interfaces\": \"auto\", // \"auto\" | \"off\" - the 09-interfaces.md chapter\n \"interfaces_frontmatter\": false, // also write the legacy top-level produces:/consumes: lists\n \"cross_repo\": \"auto\", // \"auto\" | \"off\" - quarry lookups in groom/plan/architecture/map\n \"redact\": [\"*_SECRET\", \"*_TOKEN\", \"*_PASSWORD\", \"*_KEY\"] // env-var names whose values the docs never quote\n}\n```\n\n| Key | What it does |\n| --- | --- |\n| `expertise` | 1–5, asked once and saved. Calibrates the conversation only, never the docs |\n| `teaching_mode` | Narrate and teach while working, at any expertise level |\n| `docs_dir` | Where generated docs live. Relocates outputs only - the project config's own path never moves |\n| `index_file` | Chapter zero of the docs area |\n| `subagent_threshold` | Source-file count above which `map` fans out subagents, and above which an unrequested full build asks first |\n| `docs_in_git` | `commit`, `ignore`, or `ask`, for the factual reference |\n| `language` | The generated docs' language |\n| `non_interactive` | Resolve every prompt to its default, for headless CI runs; approval gates still stop |\n| `extract` | Which `map` extraction passes run: `[\"logic\", \"uiux\"]`, `[\"logic\"]`, or `[]` |\n| `interfaces` | `auto` or `off`: whether `map` writes the cross-repo `09-interfaces.md` chapter |\n| `interfaces_frontmatter` | Also write the legacy top-level `produces:`/`consumes:` lists beside the canonical `edges:` block, for a machine consumer pinned to the 6.2 shape; off by default |\n| `cross_repo` | `auto` or `off`: whether `groom`, `plan`, the `architecture` interview, and `map`'s interfaces pass consult the `quarry` CLI; `map` reads the edges quarry could not join and asks you about those, and writes the `known_as` aliases quarry resolves names against |\n| `redact` | Env-var name patterns (`*` at either end) whose values `map` writes as `` and never quotes; case-insensitive |\n\nInterviews, `features/`, `review.md`, `uiux/preview.html` and the\nraster exports under `uiux/assets/` stay local via a generated\n`.gitignore`; the brand SVGs beside those exports are committed, since\n`build` moves them into the app. **The ledger - `changelog.md` and its `changelog.d/`\nfragments - is always\ncommitted**: `implement` deletes a feature's folder once its ledger\nentry is written, so the ledger is the only surviving record of why\nthe feature was built that way. So is the project config below.\n\nThe project's own `docs/capstone/capstone.json` is the team's\nshared config, committed like the ledger whatever `docs_in_git` says:\na config that lives on one machine is not a standard. It is created\nonly when there is something to record, and any global key set there\noverrides the global file for that repo. `expertise` and\n`teaching_mode` are personal, stay in the global file, and are\nignored if they turn up here.\n`pipeline` records the one-time pipeline-or-map choice on repos\nthat already have code, and `workspaces` gives each monorepo workspace\nits own docs area with the root project's `00-index.md` as an\nindex-of-indexes; a workspace's name is also its folder in a quarry\ndocs repo (`quarry init --name --docs-dir /docs/capstone`),\nso `groom` and `plan` query quarry by workspace name.\n\n
\n\n
\nInstalling on other agents\n\nWhichever installer you use, take **all** capstone skills: `core`\ncarries the shared rules every other command reads, so a partial\ninstall fails at the first command that needs it. `--all` and\n`--skill '*'` do that; so does accepting the default.\n\n**GitHub Copilot**, via the GitHub CLI:\n\n```bash\ngh skill install GentBajko/capstone --all --agent github-copilot\n```\n\n`gh skill` also installs to Claude, Cursor, Gemini, Antigravity and\nothers - swap `--agent`, or drop the flag to be asked. Copilot CLI's\nown marketplace format works too:\n\n```bash\ncopilot plugin marketplace add GentBajko/capstone\ncopilot plugin install capstone@capstone-marketplace\n```\n\n**The skills CLI**, covering 70+ agents:\n\n```bash\nnpx skills add GentBajko/capstone\n```\n\n**Gemini CLI**: `gemini extensions install https://github.com/GentBajko/capstone`\n\n**Antigravity**: `agy plugin install https://github.com/GentBajko/capstone`\n\n**OpenCode**, in `opencode.json`:\n\n```json\n{ \"plugin\": [\"capstone@git+https://github.com/GentBajko/capstone.git\"] }\n```\n\nCommands come out namespaced (`/capstone:map`). For a bare\n`/capstone` in Claude Code, drop this in `~/.claude/commands/capstone.md`:\n\n```markdown\n---\ndescription: Capstone entry - no args runs the pipeline; args route to the matching skill\nargument-hint: [command] [args...]\n---\n\nNo arguments: invoke the capstone:start skill. If the first argument\nmatches a capstone skill (map, doctor, review,\nmockup, logic, uiux, architecture, standards,\nstack, build, groom, plan, implement, feature, start, help),\ninvoke capstone: with the remaining arguments.\n\nARGUMENTS: $ARGUMENTS\n```\n\n
\n\n
\nCI\n\nCopy `templates/capstone-map-check.yml` into `.github/workflows/` and\nevery PR fails when the reference is stale. It needs no API key: the\ngate is a bash script, `skills/core/scripts/map-check.sh`, cloned at\nthe pinned release tag and run over `docs/capstone`. For the model\nhalf (pointer drift, absorption, re-vetting, coverage) copy\n`templates/capstone-map-review.yml` too and add an\n`ANTHROPIC_API_KEY` secret; it runs nightly or on demand and fails on\nits own `MAP REVIEW:` line. The script's schema pass also fails the\ngate on a secret-shaped string in any generated file. A repo\nregistered in a quarry pairs the same job with `quarry init` and\n`quarry check`, which reads the `### ` payload sections in\n`09-interfaces.md` and fails the PR when a field one of its consumers\nreads is gone.\n\n**Upgrading from 6.2:** the project config is committed now. Run any\ncommand once and the initializer drops the `capstone.json` line from\n`docs/capstone/.gitignore`, reporting what it removed; commit the\nfile, since it holds the settings every run on the repo follows.\n`09-interfaces.md`'s frontmatter is where the edges live: an `edges:`\nblock with a `kind`, `name`, `site` and `schema` per row, and the\nProduces and Consumes tables rendered from it. `to` and `from` are\nyours: `map` writes neither and never edits one, quarry fills them in\nby joining every registered repo's rows on `(kind, name)`, and you are\nasked only about a contract several repos sit on. Whatever your\nchapter already says in a `To` or `From` cell survives the first run\nuntouched. `Site` cells lose their line numbers on that run - the\nchapter is normative and a line number drifts on every edit - and\nquarry keeps reading the old form meanwhile. A payload section may\nnow read `Model: ` instead of repeating a table\n`02-models.md` already holds; the first `map check` after the upgrade\nreports one finding per payload section that holds neither a table\nnor a model, and one per model reference `02-models.md` has no\n`### ` section for.\n\n**Upgrading from 6.1:** replace your `capstone-map-check.yml` with\nthe new template. The old one still runs the model on every PR and\nstill passes, but it spends a key and tokens the gate no longer\nneeds. The gate's verdict line is unchanged (`MAP CHECK:`); the\nmodel's run now prints a second one, `MAP REVIEW:`, which only the\nreview template reads. `content_hash` stamps written by 6.1 or\nearlier were computed over a file set that never included wildcard\nmatches, so the first check after a squash merge may report such a\nchapter stale once; `map` regenerates it with the new hash. An\n`09-interfaces.md` written by 6.1 has no `### ` payload\nsections, so the first check reports one finding per Produces and\nConsumes row until `map interfaces` rewrites the chapter.\n\n**Upgrading from 5.x:** nothing to migrate by hand. Existing\n`changelog.md` entries, `-` feature keys, and\n`changelog-archive-.md` files stay valid and are read in place;\nnew entries land as `changelog.d/` fragments, new features get\ndate-slug ids, and files without a `content_hash` stamp gain one on\ntheir next regeneration.\n\n**Upgrading from 4.x:** `generate` and `sync` merged into `map`, and\nthe verdict line the CI job greps changed from `SYNC CHECK:` to\n`MAP CHECK:`. An old `capstone-sync-check.yml` fails loudly with\n\"no SYNC CHECK verdict found\" rather than passing silently, but\nreplace it with the template above. Existing `generate/` and `sync/`\nkeys in `changelog.md` are history and stay as they are; nothing\nreads them.\n\n
\n\n
\nRough edges\n\nThe zero-token help trick is Claude Code only.\n\nEvery script is bash, so Windows needs Git Bash (which ships with Git\nfor Windows, and which the SessionStart hook has always required);\nWindows field-testing is thin either way.\n\nBudget an afternoon for the `logic` interview on a real app; the depth\nis the point.\n\nRetrieval is grep over nine markdown files - plenty at this scale,\nunproven on giant monorepos.\n\n
\n\n---\n\n## License\n\n[Apache-2.0](LICENSE). Free to use, fork, and build on, commercially\nor otherwise. Two conditions come with it: a file you modify carries a\nnotice saying you changed it (§4(b)), and any derivative you\ndistribute reproduces the attribution in [NOTICE](NOTICE), which names\nthis repository (§4(d)).\n\nContributions welcome — issues and PRs. See\n[CONTRIBUTING](CONTRIBUTING.md); by opening a PR you license your\ncontribution under the same terms (§5).\n\n`NOTICE` also records the third-party work vendored here: `impeccable`\n(Apache-2.0), `design-taste-frontend` (MIT), and `mattpocock/skills`\n(MIT).\n", "bytes": 24820, "sha": "d4e8adc0e4e2d15f7fc03e10812deca63ff5c4ef93e52baa2f365fbc059a5f94", "repo_slug": "gentbajko/capstone", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/plg_gentbajko_capstone_d3aa95ab/readme" }