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/arch-craft.md

View on GitHub
# Architecture craft - review's backend method

Read by `protocols/review.md`. **This file is the method** for the
backend side, in full: no installed skill substitutes for it, so the
same codebase is judged the same way on any machine. §5's rulings
(recorded decisions override the baseline; skip what tooling already
enforces) bind every finding.

**Attribution.** Adapted, condensed and modified, from
mattpocock/skills (MIT, © Matt Pocock,
<https://github.com/mattpocock/skills>), the deep-module school:
Ousterhout's depth, Feathers' seams, Fowler's smells. That project
does not endorse this adaptation, and is not required for any capstone
command to run.

## 1. Vocabulary

Use these terms exactly in findings, never "component," "service,"
"API," or "boundary":

- **Module**: anything with an interface and an implementation;
  scale-agnostic (a function, class, package, or tier-spanning
  slice).
- **Interface**: everything a caller must know to use the module
  correctly: the signature, but also invariants, ordering, error
  modes, configuration, performance character.
- **Depth**: leverage at the interface: how much behaviour a caller
  or test exercises per unit of interface learned. Deep = small
  interface, lots of behaviour. Shallow = interface nearly as complex
  as the implementation.
- **Seam**: the place where behaviour can be altered without editing
  in that place; where a module's interface lives.
- **Adapter**: a concrete thing satisfying an interface at a seam; a
  role, not a substance.
- **Leverage**: what callers get from depth: one implementation
  paying back across N call sites and M tests.
- **Locality**: what maintainers get from depth: change, bugs, and
  verification concentrating in one place.

## 2. Deep vs shallow - the tests that decide

- **The deletion test.** Imagine deleting the module. Complexity
  vanishes → it was a pass-through; flag it. Complexity reappears
  across N callers → it was earning its keep.
- **The interface is the test surface.** Callers and tests cross the
  same seam. Code that must be tested *past* its interface is the
  wrong shape; that is a finding about the module, not the tests.
- Depth is a property of the interface, not the implementation: a
  deep module may be several files and internally composed of small
  swappable parts; they just aren't in the interface. Deep ≠ big
  file; a project's small-files convention and deep modules coexist.

## 3. Dependency categories - how a module tests across its seam

Classify a module's dependencies before judging its testability:

1. **In-process** (pure computation, in-memory state): always
   mergeable and testable directly; no adapter.
2. **Local-substitutable** (a real local stand-in exists: PGLite for
   Postgres, an in-memory filesystem): test with the stand-in; the
   seam stays internal, no port at the interface.
3. **Remote but owned** (your own services over a network): a port
   at the seam; production gets the transport adapter, tests an
   in-memory one; the logic stays in one deep module.
4. **True external** (Stripe, Twilio; not yours): an injected
   port; tests provide a mock adapter.

**Replace, don't layer:** once tests exist at a deepened module's
interface, the old unit tests on its swallowed shallow parts are
waste: their absence is not a coverage gap, their survival is a
finding. Tests assert observable outcomes through the interface and
survive internal refactors; a test that breaks when behaviour didn't
change is testing past the interface.

## 4. Seam discipline

One adapter means a hypothetical seam; two adapters mean a real one:
the same law `code-craft.md`'s "Interfaces: earned, not speculative"
states from the YAGNI side; the two files agree, cite either.
Internal seams (private to an implementation, used by its own tests)
are fine and are not exposed through the interface because tests use
them. A single-adapter port is indirection, not architecture: flag
it.

## 5. The smell baseline

Heuristics, never hard violations; each reads *what it is → the fix
direction*. Two rulings bind in every mode, delegated or not:
**the repo's documented standards and recorded decisions override the
baseline** (where they endorse something the baseline would flag,
suppress the smell), and **skip anything tooling already enforces**.

- **Mysterious Name**: a name that hides what it does → rename; no
  honest name means murky design.
- **Duplicated Code**: the same logic shape in several places →
  extract the shape once.
- **Feature Envy**: a method reaching into another object's data
  more than its own → move it to the data it envies.
- **Data Clumps**: the same fields travelling together → a type
  wanting to be born.
- **Primitive Obsession**: a primitive standing in for a domain
  concept → give the concept its own small type.
- **Repeated Switches**: the same case-cascade on the same type
  recurring → polymorphism or one shared map.
- **Shotgun Surgery**: one logical change forcing scattered edits →
  gather what changes together.
- **Divergent Change**: one module edited for unrelated reasons →
  split by reason for change.
- **Speculative Generality**: abstraction for needs nothing has →
  delete it; inline until a real need shows.
- **Message Chains**: `a.b().c().d()` navigation callers depend on →
  hide the walk behind one method.
- **Middle Man**: a thing that mostly delegates onward → cut it,
  call the target.
- **Refused Bequest**: an implementer ignoring most of what it
  inherits → composition, not inheritance.

## 6. The review method

1. **Scope by heat.** Deepening pays off where change happens: walk
   the git history for hot spots (files and areas that keep coming
   up) and weight attention there. The user naming a direction
   overrides. Scattered change with no hot spot → widen the net.
2. **Walk for friction, not checklists**: where does understanding
   one concept mean bouncing between many small modules; where are
   interfaces nearly as complex as their implementations; where were
   pure functions extracted "for testability" while the real bugs
   hide in how they're called; what leaks across seams; what is
   untestable through its current interface?
3. Apply the deletion test to every suspect; classify dependencies
   (§3) before proposing how a deepened module would be tested.
4. Grade each candidate **Strong / Worth exploring / Speculative**,
   and say what deleting or merging it concentrates. Benefits are
   stated as leverage and locality, never as "cleaner".
5. The project's final reference and `standards.md` are ADR-equivalents:
  a candidate contradicting
   one is surfaced only when the friction justifies reopening the
   decision, and says so explicitly.
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