danmcinerney/architect-loop

codebase-design

Shared vocabulary for designing deep modules and for naming factory concepts consistently.

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/danmcinerney/architect-loop --skill codebase-design

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

<!-- Adapted from mattpocock/skills (MIT). -->

Codebase Design

Design deep modules: a lot of behavior behind a small interface, placed at a clean seam, testable through that interface. Use this language wherever code or a factory issue is being designed. The aim is leverage for callers, locality for maintainers, and testability for everyone.

Glossary

Use these terms exactly — don't substitute component, service, boundary, or API when you mean module or interface; don't say task or ticket for issue, or test file for frozen check. Consistent language is the whole point.

Design (Pocock, adapted):

  • Module - anything with an interface and an implementation, at any scale: a function, a package, or a whole vertical slice.
  • Interface - everything a caller must know to use a module correctly: types, invariants, ordering, error modes, config, performance - not just a signature.
  • Implementation - the body of code behind the interface; distinct from adapter, which names role at a seam, not substance.
  • Depth - leverage at the interface: behavior reached per unit of interface learned. Deep means a small interface over a big implementation; shallow is the opposite, and to avoid.
  • Seam (Feathers) - the place a module's interface lives; where behavior can change without editing there.
  • Adapter - a concrete thing satisfying an interface at a seam. One adapter is a hypothetical seam; two make it real.
  • Leverage - what callers get from depth: one implementation pays off across many call sites and tests.
  • Locality - what maintainers get from depth: change and bugs concentrate in one place instead of spreading.

Factory (one line each; matches `docs/spec/skill-library.md` Target flow):

  • Run - one factory build from intake to the closing PR, on its own factory branch.
  • Tracking issue - the run's parent issue: dashboard, digest, preflight record.
  • Issue - one vertical-slice unit of work: one builder job, one disjoint file set, one change-skeleton.
  • Slice - the vertical cut an issue implements; slice names the cut, issue names its tracker record - same unit, two angles.
  • Frozen check - the committed, read-only acceptance check a builder's work is graded against.
  • Check-runner - the deterministic script that grades a frozen check's RUN items and exits typed (0/2/5).
  • Strategist - the fresh high-judgment subagent that drafts specs, cuts issues, stress-tests plans, and runs full-lane reviews.
  • Builder - the fresh, worktree-isolated agent that implements one issue and never commits.
  • Orchestrator - the one session that grounds, dispatches strategist and builder work, freezes, and integrates; never writes implementation code; in the fast lane (/architect-fast) it also runs the closing test pass whose output feeds the builder review - a recorded relaxation.
  • Factory branch - the run's integration branch (factory/<run>) that job branches merge into.
  • Worktree - the isolated git checkout a builder or reviewer works in, verified against the freeze commit.
  • Job report - a builder's raw-evidence artifact, ending in one STATUS line.
  • Verdict - the grading record posted on an issue at close: checkrun summary plus typed exit, postflight result, slice call, decisive reason; the closing review's run-level verdict goes on the tracking issue.
  • Ruling - an orchestrator decision recorded post-freeze: a PHASE-0 execution conflict, boundary amendment, or respawn answer.
  • Digest - the shipped-issues, diffstat, rulings, and domain-language summary handed to the integrate subagent's docs pass.
  • Hard stop - an irreversible or destructive action the loop refuses without a human ruling.

Deep vs. shallow

A deep module hides a lot of implementation behind a small interface: few methods, simple params, most of the complexity out of sight. A shallow module is the opposite - an interface almost as complex as what it wraps, often a near-passthrough. When shaping an interface, ask whether the method count and params can shrink, and whether more logic can move inside.

Principles

  • Depth is a property of the interface, not the implementation - a deep

module can be built from small internal seams its own tests use, without exposing them at the external interface.

  • The deletion test: imagine deleting the module. If complexity vanishes,

it was a pass-through; if it reappears across N callers, it was earning its keep.

  • The interface is the test surface - callers and tests cross the same

seam. If you want to test past the interface, the module is probably the wrong shape.

  • One adapter means a hypothetical seam; two adapters means a real one.

Don't introduce a seam unless something actually varies across it.

Designing for testability

  • Accept dependencies, don't create them - a function that takes its

gateway is testable; one that builds a StripeGateway() internally is not.

  • Return results, don't produce side effects - a function that returns a

computed discount is testable; one that mutates a cart in place is not.

  • Small surface area: fewer methods = fewer tests needed; fewer params =

simpler test setup.

Going deeper

  • Deepening a cluster given its dependencies - see DEEPENING.md:

dependency categories, seam discipline, and replace-don't-layer testing.

  • Exploring alternative interfaces - see DESIGN-IT-TWICE.md: dispatch

parallel subagents to design the interface several radically different ways, then compare on depth, locality, and seam placement.

from this repository

More skills

All skills