Template

Files

Danijel Martinek c85f96c62e feat(skills): improve-codebase-architecture skill adapted for template-vertical

Adapts mattpocock/skills/engineering/improve-codebase-architecture to
this repo. Four files at .claude/skills/improve-codebase-architecture/:

  SKILL.md (104 lines):
    - Explore -> Present candidates -> Grilling loop process
    - "Hard constraints (do not propose violations)" section
      enumerating ADRs 006/008/010/012/013/014/015/017/020/021 that
      bound the design space
    - Repointed at docs/glossary.md (not CONTEXT.md) and
      docs/decisions/ (not docs/adr/)
    - Exploration shortcuts specific to this repo: pnpm fallow,
      pnpm coverage:diff, feature.manifest.ts, pnpm turbo boundaries
    - Grilling loop side-effects target the right glossary section
      and the next available ADR number (currently 022)

  DEEPENING.md (93 lines):
    - 4 dependency categories mapped to this repo's reality:
        Cat 1 (in-process) -> entities/use-cases/presenters
        Cat 2 (local-substitutable) -> our existing real + mock
          adapter pattern (every port has both; mocks ARE stand-ins)
        Cat 3 (remote but owned) -> cross-feature events via
          IEventBus (E0/E1 rules)
        Cat 4 (true external) -> Payload, Sentry/OTel, socket.io
          (each constrained to its vendor-isolation seam by ADR)
    - Seam discipline section recognises DI symbols + manifest entries
      as concrete seams alongside .interface.ts files
    - Testing strategy: replace not layer (matches ADR-020 L0 + L1)
    - Conformance check command list at the end (typecheck, lint,
      test --coverage, conformance, fallow:audit, coverage:diff)

  INTERFACE-DESIGN.md (66 lines):
    - Parallel sub-agent "Design It Twice" pattern preserved
    - Every sub-agent brief MUST include glossary terms + ADR
      constraints + manifest awareness
    - Output items extended with "Manifest + binder impact" and
      "ADR conflicts (if any)"
    - Comparison axes include conformance impact + coverage delta
    - Cross-feature moves flag release-please version-bump
      implications (per ADR-021 commit-path targeting)

  LANGUAGE.md (79 lines):
    - Matt's 7 abstract terms preserved (module, interface,
      implementation, depth, seam, adapter, leverage, locality)
    - New "Mapping to this repo's identifiers" table — abstract
      term -> concrete file shape (e.g. seam -> *.interface.ts +
      DI symbol + manifest entry + <gen:*> anchor)
    - Rejected framings extended with our reserved meanings
      ("boundary" stays the ESLint workspace-tag term; "service"
      stays the DI port term)

Per user follow-up: vocabulary anchored so that "module" defaults
to "feature" in this repo (since features are our primary unit of
organisation). Abstract refactor sense survives only when the cross-
scale abstraction is the point. Glossary.md updated:
  - "Feature" entry adds the "module = feature in refactor sense"
    cross-link
  - New "Architecture refactor vocabulary" section with 9 terms
    (Module, Interface (refactor sense), Implementation, Depth,
    Seam, Adapter, Leverage, Locality, Deletion test, Deepening)
    — all framed so feature is the primary instance
  - Flagged ambiguities entry for "module" rewritten to capture the
    three coexisting senses (workspace package / Node ESM / refactor
    vocabulary defaulting to feature); new entries for "seam" and
    "adapter" to prevent drift with the existing "boundary" / "service"
    / "scope" reservations

Hooks updated:
  - session-start.sh skills line lists the new skill
  - prompt-context.sh adds a 10th keyword group firing on
    refactor / deepening / shallow / architecture / seam / adapter /
    interface design / design it twice — inject points at SKILL.md
    + summarises the vocabulary and hard constraints

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-13 17:30:59 +02:00

4.8 KiB

Raw Blame History

Interface Design

When the user wants to explore alternative interfaces for a chosen deepening candidate, use this parallel sub-agent pattern. Based on "Design It Twice" (Ousterhout) — your first idea is unlikely to be the best.

Uses the vocabulary in LANGUAGE.md — module (= feature by default in this repo), interface, seam, adapter, leverage.

Process

1. Frame the problem space

Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate:

The constraints any new interface would need to satisfy
The dependencies it would rely on, and which category they fall into (see DEEPENING.md)
The hard constraints from SKILL.md that the new interface must respect (factory-function shape, per-feature DI, manifest-first, generator-first, brand wrappers, etc.)
A rough illustrative code sketch to ground the constraints — not a proposal, just a way to make the constraints concrete

Show this to the user, then immediately proceed to Step 2. The user reads and thinks while the sub-agents work in parallel.

2. Spawn sub-agents

Spawn 3+ sub-agents in parallel using the Agent tool (subagent_type=general-purpose or a more specific type if appropriate). Each must produce a radically different interface for the deepened module.

Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from DEEPENING.md, what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint:

Agent 1: "Minimise the interface — aim for 1–3 entry points max. Maximise leverage per entry point."
Agent 2: "Maximise flexibility — support many use cases and extension."
Agent 3: "Optimise for the most common caller — make the default case trivial."
Agent 4 (if applicable): "Design around ports & adapters for cross-seam dependencies."

Every brief MUST also include:

This repo's vocabulary from docs/glossary.md (use case, manifest, feature, slice, etc.)
The architecture vocabulary from LANGUAGE.md
The hard constraints from SKILL.md — sub-agents must not propose interfaces that violate ADR-006 (boundaries), ADR-008 (per-feature DI), ADR-012 (factory shape, one controller per use case), ADR-013 (schemas in use-case file), ADR-014/017 (vendor isolation), ADR-015 (events for cross-feature), ADR-020 (manifest-driven coverage bands), or ADR-021 (versioning by commit-path).
The relevant feature feature.manifest.ts shape so the proposed interface aligns with manifest-first ordering.

Each sub-agent outputs:

Interface (types, methods, params — plus invariants, ordering, error modes, schemas if applicable)
Usage example showing how callers in this repo would use it (use real file paths and real existing feature names)
What the implementation hides behind the seam
Dependency strategy and adapters (see DEEPENING.md) — which existing ports/adapters get reused, which (if any) are new
Manifest + binder impact — which feature.manifest.ts entries and which bind-production.ts / bind-dev-seed.ts files change
Trade-offs — where leverage is high, where it's thin
ADR conflicts (if any) — call out by ADR number with rationale, or state "none"

3. Present and compare

Present designs sequentially so the user can absorb each one, then compare them in prose. Contrast by:

Depth (leverage at the interface)
Locality (where change concentrates)
Seam placement (which existing *.interface.ts survives, which gets replaced, which is new)
Conformance impact (how many manifests change, how many binders change, how many tests rewrite)
Coverage delta (cumulative L0 band impact — does any layer drop below its declared 100% / 95%?)

After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid. Be opinionated — the user wants a strong read, not a menu.

If the chosen design crosses a feature-package boundary (e.g. moves a use case from @repo/blog to @repo/media), state explicitly:

Which feature.manifest.ts files lose / gain entries
Which package versions will bump on the next release-please PR (per ADR-021 commit-path bump targeting)
Whether the migration needs an intermediate compatibility seam to keep pnpm conformance green during the transition

The implementation lands via the manifest-first ordering: (1) update the manifests in both packages, (2) write the new contracts in the use-case file, (3) write the failing tests, (4) implement until green. Don't skip the order even when the move feels mechanical.

4.8 KiB Raw Blame History Unescape Escape