Skip to content

GentBajko/capstone / skills/core

Internal 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.

FileKindSize
SKILL.mdskill md902 B
VERSIONother6 B
references/arch-craft.mdmarkdown6.6 KB
references/code-craft.mdmarkdown9.6 KB
references/core-authoring.mdmarkdown8.7 KB
references/core.mdmarkdown55.5 KB
references/dispatcher.mdmarkdown1.9 KB
references/interview.mdmarkdown17.5 KB
references/logic-craft.mdmarkdown9.5 KB
references/protocols/architecture.mdmarkdown12.2 KB
references/protocols/build.mdmarkdown10.5 KB
references/protocols/doctor.mdmarkdown9.3 KB
references/protocols/edges.mdmarkdown12.6 KB
references/protocols/feature.mdmarkdown5.3 KB
references/protocols/groom.mdmarkdown11.2 KB
references/protocols/implement.mdmarkdown15.2 KB
references/protocols/logic.mdmarkdown10.7 KB
references/protocols/map.mdmarkdown38.5 KB
references/protocols/mockup.mdmarkdown11.0 KB
references/protocols/plan.mdmarkdown9.3 KB
references/protocols/retro.mdmarkdown9.3 KB
references/protocols/review.mdmarkdown10.6 KB
references/protocols/stack.mdmarkdown8.8 KB
references/protocols/standards.mdmarkdown8.5 KB
references/protocols/start.mdmarkdown14.6 KB
references/protocols/uiux.mdmarkdown24.8 KB
references/schema.txtmarkdown11.9 KB
references/standards-inventory.mdmarkdown36.9 KB
references/style.mdmarkdown1.8 KB
references/topics.mdmarkdown21.2 KB
references/uiux-craft.mdmarkdown20.7 KB
references/uiux-inventory.mdmarkdown19.3 KB
scripts/help-hook.shexecutablescript1.5 KB
scripts/help.shexecutablescript6.4 KB
scripts/init-config.shexecutablescript16.3 KB
scripts/lint-sync.shscript133.5 KB
scripts/map-check.shexecutablescript52.8 KB

references/protocols/edges.md

View on GitHub
# edges - fill the consumer side of cross-repo edges from a folder of clones

**Reads:** config → each clone in the folder: its origin URL and HEAD
commit, its project config, its `<index_file>`, and the frontmatter of
its `09-interfaces.md` (`known_as` and the `edges:` block) → for each
consumes row, open or answered, the file at its `site` and the config
and deploy files that feed the address it calls, in that clone and in
the others → `git grep` across the clones: once per contract an
unread clone might produce (step 4), once per address that named a
unit (step 6).

`map` reads one repo, and one repo never holds another repo's name: a
consumer's code holds an address, a producer's code holds nothing
about its callers (core.md hard rule 3). So every consumes row `map`
writes has no `from`, and quarry or a person supplies it later. With
every repo of a system cloned into one folder the answer is on disk:
some other clone answers to the address the consumer calls. `edges`
reads the folder once and writes that repo's name into each empty
`from`.

Run it from the folder that holds the clones, or name that folder as
the argument, after `map` has run in each repo. It asks nothing, so
it runs the same under `non_interactive`, and it is the one run hard
rule 3 lets derive a far end.

Four bounds, each closing a way to leave a wrong edge behind:

- **A consumer's `from`, never a producer's `to`.** Quarry builds a
  producer's edges from the consumers that name it, so `from` alone
  gives the whole graph. A written `to` takes the row out of quarry's
  name join: a consumer that appears later, in a repo this folder
  never held, would find no producer and raise no warning, and a
  consumer that stops calling would stay listed for good.
- **Empty cells only.** A `from` the block already carries is an
  answer, from a person, a confirmation or an earlier run. It is
  compared and reported, never changed (hard rule 3).
- **One candidate, or nothing.** A row is written only when the
  evidence leaves exactly one repo. Several candidates or none leave
  the cell empty and the row in the report. Never `unknown`: that is
  a person's ruling that no sibling repo sits on the other side
  (core.md's Edge confirmation), and a repo cloned tomorrow may be
  the one.
- **Docs areas only, working tree only.** Each repo's own
  `<docs_dir>` per hard rule 2, and in it one edit to
  `09-interfaces.md` plus one ledger fragment: no initializer run, no
  `.gitignore`, no index row. No source file, no stamp, no commit,
  no branch, no push.

The docs areas are single-writer (core.md's Changelog ledger): if a
capstone run may be live in any of the clones, say so and stop before
writing. Uncommitted docs and unfolded fragments an earlier run left
behind are not a live run.

## Procedure

1. **Config.** Per core.md: the global file governs the conversation.
   The folder has no project config and never gets one; each clone's
   own `docs/capstone/capstone.json` governs that clone's docs area
   in the steps below.

2. **Find the units.** A unit is one docs area plus the one name
   other repos know it by. Every immediate subfolder that is the root
   of a git work tree is a clone, taken in the order `LC_ALL=C sort`
   gives their folder names; when the folder holds none and is itself
   a work tree with `workspaces` configured, its workspaces are the
   units. Per clone, read:
   - **the name**: the last path segment of
     `git -C <clone> remote get-url origin`, without `.git`. Never
     the folder's name: `git clone .../tariff-service.git tariffs`
     is still `tariff-service`.
   - **the commit**: `git -C <clone> rev-parse HEAD`.
   - **the docs area**: `docs_dir`, `index_file` and `interfaces`
     from the clone's project config, then the global file, then the
     defaults. With `workspaces` in the project config the clone is
     one unit per workspace instead: named by the workspace, its docs
     area fixed at `<path>/docs/capstone/` and its index at
     `<path>/docs/capstone/00-index.md` (core.md's naming contract).

   Four kinds of clone are reported and never written as a far end:
   - **no origin**: it has no name. Its own rows are still read and
     filled; a row elsewhere that it alone would answer stays open,
     and the report says the clone needs an origin.
   - **a name an earlier clone already carries** (one repo cloned
     twice): skipped whole, step 6's sweep included.
   - **no `<index_file>`**: never mapped. Name it with
     `run /capstone:map there` and move on. `edges` never runs `map`
     (core.md's Missing reference exempts it): a build in every
     unmapped clone is not what was asked for.
   - **`interfaces: "off"`**: the chapter is not capstone's to write
     there.

   The last two are **unread clones**: their files are still
   evidence in step 4, and what they produce is unknown. A mapped
   unit with no `09-interfaces.md` has no rows to fill: `map` found
   no cross-repo talk in it. It can still be a far end. A chapter
   with no `edges:` block was written by an older capstone: its rows
   are read in the order `../topics.md` gives, nothing is written
   there, and the report names it for `/capstone:map interfaces`.
   Fewer than two units: say so and stop.

3. **Collect what each unit declares.** From the chapter's
   frontmatter: `known_as`, the produces rows, the consumes rows.
   Three tables come out of it:
   - **names**: each unit's name and every `known_as` entry, compared
     case-insensitively. An alias two units both list names both, and
     so settles nothing.
   - **producers**: for each contract, the units with a produces row
     on it. Two rows are one contract when quarry's join would pair
     them: their `kind` is equal, and their `name` is equal as
     written, except in the routed kinds (`http`, `ws`, `wss`,
     `grpc`). There a leading method word is compared
     case-insensitively, and a path with every parameter segment
     counted equal however it is spelled (`:id`, `{tariffId}`,
     `<id>`) and its trailing slash, query string and fragment
     dropped. Nothing else is folded: `pkg.Users/GetUser` and
     `pkg.Users/getuser` are two contracts.
   - **open rows**: every consumes row with no `from`. The rest are
     answered rows.

4. **Resolve each open row.** The second step runs only when the
   first finds no address at all:
   1. **The address in the code.** Open the file at the row's `site`
      and find what that call is addressed to: a host, a base URL, a
      service name. Where the code reads it from a variable or a
      config key, follow the key to its value: a default in the code,
      `.env.example`, a compose file, Helm values or a manifest in
      the consumer's clone, then the deploy config in the other
      clones (an infra repo's values for this service). An unread
      clone is still evidence here. The address names a unit when its
      host or service name is that unit's name or one of its
      `known_as` entries, the consumer's own unit aside. Two things
      are not the address of a far end:
      - **transport**: a broker, a bus, a queue endpoint or a
        database host is what both ends share. A row whose code holds
        only that has no address.
      - **a unit that only passes the call on**: where the named
        unit's own config routes this path to another unit (a
        gateway, a proxy), follow the route; the unit it leads to is
        the address.
   2. **The only producer.** No address to find (a queue or a topic
      carries none, a schema package neither), or a key that leads to
      no value anywhere in the folder: take the units that produce
      the row's contract, the consumer's own aside. An unread clone
      may produce it unseen, so search each one for the contract,
      `git -C <clone> grep -l -F -- '<name>'` with a route searched
      by its path up to the first parameter: a hit makes that clone
      a candidate too.

   What the evidence leaves decides the row:

   | Evidence | Outcome |
   |---|---|
   | The address names one unit, and it produces the contract | Write that unit |
   | The address names one unit that produces no such contract, and no other unit does | Write that unit; report the row `map` missed there |
   | The address names one unit that produces no such contract, and another unit does | Leave it open; report both |
   | The address names several units | Leave it open; report them |
   | The address names no unit | Leave it open; report the address. The only-producer step does not apply: the code already says the call goes somewhere this folder does not hold |
   | No address, one candidate, a unit with a name | Write that unit |
   | No address, one candidate, an unread clone or a unit with no name | Leave it open; report the clone and what it lacks |
   | No address, several candidates | Leave it open; report them |
   | No address, no candidate | Leave it open: the far end is not in this folder, or its chapter is stale |

5. **Compare the answered rows; change none.** Resolve each consumes
   row that already carries a `from` the same way, and report it when
   the evidence disagrees: it names another unit, the named repo is
   in the folder and produces no such contract, or the row says
   `unknown` and a unit in the folder produces the contract. The user
   edits the cell or leaves it; no run does (hard rule 3).

6. **Sweep for callers no row covers.** For each address that named a
   unit in step 4 or step 5, run
   `git -C <clone> grep -l -F -- '<address>' -- . ':(exclude)<docs_dir>'`
   in every clone but the one it addresses and any skipped as a
   second copy. A file it lists is covered when steps 4 and 5 read
   it: a row's `site`, or a config file followed for one. Any other
   file is a lead, a call `map` may have missed. Report it with `run /capstone:map interfaces there`;
   never add the row.

7. **Record, then write**, one unit at a time, for each unit with a
   row step 4 settled. The unit's changelog entry goes to disk first
   (core.md's ledger: an entry is on disk before what it records), as
   the fragment
   `<docs_dir>/changelog.d/<YYYY-MM-DD>-edges-09-interfaces-<rev>.md`,
   in a `changelog.d/` created where the docs area has none:

       ## <date> - edges: 09-interfaces.md
       key: edges/09-interfaces.md@<rev>

   `<rev>` is the moment the run began, `date -u +%Y%m%dT%H%M%SZ`,
   taken once and used in every unit. No one repo's commit describes
   a run over many, and a repo's commit stands still while `map`
   adds rows beside it, so a commit in the key would make a second
   run's entry look already written. Bullets only: one per row
   written, naming the row, the repo, and the evidence as paths
   (`src/TariffClient.kt` calls `tariffs.voltavia.internal`, which
   tariff-service lists in `known_as`; or: the only repo in the
   folder producing it); one per row left open, with its reason; one
   listing the clones found, each with its short commit. A value
   `redact` covers is never quoted: name the variable and the file.
   `edges` folds nothing; the next `map`, `implement` wrap or
   `doctor` repair on the default branch does. A unit where nothing
   is written gets no entry. A run that died midway is run again:
   what it wrote is answered by then and is not written twice.

   Then edit `09-interfaces.md`:
   - in the `edges:` block, add `from: <name>` to the row; the same
     on the legacy top-level `consumes:` list when the page carries
     one (`interfaces_frontmatter`).
   - in the `## Consumes` table, set that row's `From` cell to the
     name, written the way the table's other far ends are: bare, or
     as the relative link `../topics.md` allows when the page links
     the others.

   `<name>` is the unit's name from step 2, never the alias the code
   used. Everything else stays byte for byte: the other rows, every
   `to`, `known_as`, the payload sections, and the stamps, which
   record the `map` run that derived the chapter from the code. This
   run derived nothing.

8. **Report**, once for the folder, in conversation, in this order:
   the rows written (repo, row, far end, evidence); the rows left
   open, each with its reason and any candidates; the answered rows
   the evidence disagrees with; the leads from the sweep; the clones
   skipped or unread, and why; then the files changed, one path per repo, with
   the reminder that nothing was committed and that quarry sees a
   repo's edges only once its docs reach the docs repo. Vocabulary
   follows `expertise` like any other turn. A run that wrote nothing
   says so.

**Consumer:** quarry reads each written `from` as a declared edge and
pairs it with the producer's open row. `map` keeps it on every later
run (`../topics.md`'s merge rule) and drops it with the row when the
code stops making the call.
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall