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/code-craft.md
View on GitHub# Code craft - TDD + YAGNI for every line this plugin writes
**The discipline every stage that decides what gets built answers
to.** Read by `protocols/architecture.md` and `protocols/stack.md`,
which decide what will exist, and by `protocols/plan.md`,
`protocols/build.md`, and `protocols/implement.md`, which write it.
`review` judges against it. A layer agreed at design time and a
dependency agreed at stack time are both code the ladder never gets
to stop later, which is why the ladder runs there too, before a line
exists. Adapted from the ponytail skill.
**Precedence, and its one limit.** `standards.md` records the user's
own decisions and outranks this file: capstone's rule everywhere is
that your recorded decisions beat generic best practice. But the
override must be **deliberate and recorded** - a standards rule that
names what it overrides wins, while a silent conflict resolves to the
ladder. "The user might not have wanted this" is not an override.
This file governs everything standards leaves open.
**And the user can always overrule it live.** The ladder is the
position you argue from, never a veto: a rung that says "defer this"
is a recommendation with a reason, and core.md's Pushback rule caps
you at two rounds. If the user wants the layer, the dependency, or the
abstraction built now anyway, build it - and record the rung you
climbed and their answer, so the decision reads as considered rather
than careless.
Lazy means efficient, not careless: the best code is the code never
written.
## The ladder
Stop at the first rung that holds, after understanding the problem,
never instead of it. Read the task and the code it touches, trace the
real flow end to end, then climb:
1. Does this need to exist at all? Speculative need = skip it, say so
in one line. (YAGNI)
2. Already in this codebase? Reuse the helper, util, type, or pattern
that already lives here. Look before you write.
3. Stdlib does it? Use it.
4. Native platform feature covers it? `<input type="date">` over a
picker lib, CSS over JS, a DB constraint over app code.
5. Already-installed dependency solves it? Use it. Never add a new one
for what a few lines can do.
6. Can it be one line? One line.
7. Only then: the minimum code that works.
Bug fix = root cause, not symptom: before editing, grep every caller
of the function you touch. One guard in the shared function beats one
per caller; patching only the reported path leaves sibling callers
broken.
## Rules
- No unrequested abstractions: no factory for one product, no config
for a value that never changes, no scaffolding "for later".
- Deletion over addition. Boring over clever. Fewest files possible.
Shortest working diff wins, in the right place; the smallest change
in the wrong place is a second bug.
- Two same-size options: take the one correct on edge cases. Less
code, never a flimsier algorithm.
- Mark deliberate ceilings with a `ceiling:` comment naming the limit
and the upgrade path
(`# ceiling: global lock, per-account locks if throughput matters`).
- Comments earn their line or they don't get written; see Comments
below.
## Comments: the same ladder, applied to prose
A comment is code that must be maintained and that nothing tests, so
it climbs a rung of its own: **does this say something the code
cannot say itself?** No - delete it. The reader can already see the
next line. What they can't see is why you picked it.
Earned:
- Why this and not the obvious alternative, when the obvious one
looks better on the page.
- A constraint no reader would reconstruct: an upstream bug and its
issue link, a spec or RFC clause, an ordering requirement, an
overflow or precision trap, a rate limit.
- A workaround, named as one, with the condition that retires it.
- `ceiling:` markers per the rule above.
- Docstrings where `standards.md` asks for them, on the surface it
names, and nowhere else.
Not earned, and deleted on sight:
- Restating the line (`# increment the counter`, `// set the flag`).
- Narrating a sequence the code already spells out ("Step 1:
validate the payload").
- Section banners inside a file.
- Docstrings on self-evident helpers; parameter and return lists that
repeat what the annotations already say.
- Commented-out code. Delete it, git has it.
- A `TODO` standing in for work the current task covers. Do the work.
Naming beats explaining. A comment saying what a badly-named thing is
is a rename waiting; one explaining a dense block is usually an
extracted function waiting. Reach for those first, and the comment
stops being needed.
A stale comment is worse than no comment, because it gets read as
true: the commit that outdates one updates or deletes it in the same
diff.
Prose the code already carries is a review finding, ranked like any
other unearned addition.
## TDD, YAGNI-scoped
Test-first stands (the plan's task cycle: failing test → minimum code
to green → verify → commit). YAGNI bounds the scope, never the order:
test the behavior being built now, with the project's real runner; no
speculative suites for unbuilt features, no fixture cathedrals, no
per-function ceremony. Non-trivial logic (a branch, a loop, a parser,
a money/security path) always leaves its failing-then-green check
behind. Trivial one-liners need no test: YAGNI applies to tests too.
## Interfaces: earned, not speculative
- Consumer-side interfaces/Protocols for typing and test doubles are
notation, not abstraction: narrow, named by behavior, always fine.
- An adapter/seam is EARNED by one of: (a) a commodity-shaped boundary
with real swap probability (email, payments, blob storage, SMS, LLM
providers); (b) portability within ONE guarantee family (Kafka ↔
Kinesis: durable partitioned log; never across families; Kafka to
Redis pub/sub is a redesign, not a plug); (c) a second real
implementation existing today.
- One seam per guarantee family, named by behavior. Domain types cross
the seam; vendor types (`ConsumerRecord`, shard iterators, partition
numbers) never leak past it.
- Banned: provider-side god-interfaces (`IDatabase`), abstraction over
an abstraction (an interface over an ORM: the ORM is the database
abstraction), DI ceremony for one implementation, config-switchable
backends for hypothetical vendors. Swappability elsewhere comes from
locality (one contained module), not ceremony.
- The seam interface is written when the second implementation becomes
real: it teaches the true shape. An in-memory test fake validates
the seam's shape, not its semantics.
## Never lazy about
Understanding the problem (read fully, then be lazy); input validation
at trust boundaries; error handling that prevents data loss; security;
accessibility basics; typing per `standards.md` (annotations, enums,
Protocols are how minimal code is written, never bloat to cut);
anything the spec or the user explicitly requires: the user insisting
on the full version ends the argument.
## Git: branches, commits, and their density
The default for every stage that writes code. `standards.md`'s
Process domain records the user's own conventions and wins wherever
the two conflict; a repo whose existing history plainly follows
another convention wins too: match what `git log` shows rather than
imposing this.
### Branch
One branch per unit of work, named `<type>/<slug>`, the slug matching
the feature's own (`feat/invite-links`, not `feat/new-stuff`). Types:
`feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`.
Never commit to `main`/`master` without the user's explicit consent:
offer the branch first. Consent given, the rules below still hold.
### Commit message
<type>(<scope>): <subject>
<body: why, not what>
<footer: refs, breaking changes>
- `<type>` from the list above; `<scope>` the module or area touched,
omitted when the change is genuinely repo-wide.
- `<subject>`: imperative mood, no trailing period, at most 72
characters, and a real claim: `fix(auth): reject expired refresh
tokens`, never `fix bug` or `update code`.
- **The body says why.** The diff already says what. Explain the
reason the change was needed, the approach's trade-off, and anything
a reader would otherwise have to reconstruct. A commit whose reason
is obvious from the subject needs no body; most need one.
- Footer carries issue or spec references and `BREAKING CHANGE:` with
the migration path.
- Never mention the tool that wrote it, and never add co-author or
"generated by" trailers unless the user asks.
### Density: one reviewable idea per commit
The unit is **one complete idea a reviewer could accept or reject on
its own**, which for a plan-driven run is one task: its test, its
implementation, and the verification that proves it, together.
- **Never a broken commit.** Every commit builds and its tests pass.
The red step of a TDD cycle is not committed on its own; red and
green land together.
- **Never mix kinds.** A refactor and a behavior change in one commit
are two commits. Formatting churn is its own commit, or better, its
own branch.
- **Never a catch-all.** "wip", "fixes", "address review" say nothing;
say what was fixed. Squash the wip locally before the branch is
finished.
- Too big: a reviewer cannot hold it in their head, or the subject
needs an "and". Too small: a commit that does not build, or that
only makes sense read beside its neighbor.
- Fixes to review findings amend or follow the commit they correct,
named for the correction (`fix(auth): narrow the token window
review flagged`), never a bare "review fixes".
### Order
Commits land in dependency order: what a later commit consumes, an
earlier one defines. A branch reads top to bottom as the argument for
the change, so a reviewer walking it never meets a name before its
definition.
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 |