Danijel Martinek
c85f96c62e
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>
docs/
Documentation hub for the template-vertical monorepo. Start here if you landed at docs/ directly.
For the project entry point, see ../CLAUDE.md (humans + agents) and ../AGENTS.md (package map + boundary rules).
Resolving terminology
glossary.md — canonical vocabulary for every cross-cutting term used in this repo (feature, use case, manifest, conformance, slice, coverage band, dispatch, etc.). When in doubt about what a term means here, check the glossary first.
How the documentation is organised
docs/
├── glossary.md # canonical vocabulary
├── architecture/ # design + invariants (rarely changes)
│ ├── overview.md # high-level architecture summary
│ ├── vertical-feature-spec.md # canonical feature design spec
│ ├── dependency-flow.md # workspace + import-graph reference
│ ├── template-tiers.md # must-have vs optional core packages
│ ├── agent-first-workflow-and-conformance.md # workflow + 5-gate design
│ ├── data-flow-explainer.html # interactive (single-file)
│ ├── di-explainer.html # interactive (single-file)
│ ├── feature-conformance-explainer.html # interactive (single-file)
│ └── audit-and-compliance-explainer.html # interactive (single-file)
├── decisions/ # ADRs (durable design decisions)
│ └── adr-001..adr-020.md # 20 ADRs, numbered in order accepted
├── guides/ # day-to-day how-to docs
│ ├── runbook.md # ← first time? read this end-to-end
│ ├── conformance-quickref.md
│ ├── coverage.md # 4-layer coverage cookbook (ADR-020)
│ ├── releasing.md # release-please workflow + CHANGELOG cookbook (ADR-021)
│ ├── tdd-workflow.md
│ ├── testing-strategy.md
│ ├── adding-a-feature.md # manual path
│ ├── scaffolding-a-feature.md # generator path (preferred)
│ ├── scaffolding-core-package.md
│ ├── scaffolding-core-ui-component.md
│ ├── events-and-jobs.md # requires `gen core-package events`
│ ├── realtime.md # requires `gen core-package realtime`
│ ├── audit-and-compliance.md # requires `gen core-package audit`
│ ├── frontend-work-shape.md
│ └── infrastructure-work-shape.md
└── work/ # local task system (PRD → Epic → Story → Task)
├── README.md # work-folder layout + PRD lifecycle
├── _state.json # derived index (orchestrator-managed)
├── prds/<date>-<slug>.prd.md # PRDs
└── <epic-slug>/... # one folder per epic
Document types
| Type | Where | Purpose | Lifetime |
|---|---|---|---|
| Glossary | glossary.md |
One sentence per term; flagged ambiguities | Long-lived |
| Architecture | architecture/ |
Design invariants, system shape | Long-lived |
| ADR | decisions/adr-NNN-*.md |
Single decision: context → choice → consequences | Long-lived |
| Guide | guides/ |
How-to, reference, troubleshooting | Updated as features evolve |
| PRD | work/prds/*.prd.md |
Implementation seed for one epic | draft → in-review → approved → shipped |
| Epic / Story / Task | work/<epic>/... |
Workflow artifacts | Created → in-progress → done |
When to put what where
- A new architectural decision (events, audit, instrumentation choices, etc.) → ADR. Number is
001 + max(existing). - A new how-to (cookbook, troubleshooting, "how do I do X") → guide.
- A new vocabulary term that's cross-cutting → glossary, alphabetically grouped.
- A new initiative (multi-task feature work) → PRD seed. The decomposer refuses to run on
draft— flip toapprovedafter human review.pnpm work prd-ship <id>auto-flips toshippedon epic completion. - A new interactive diagram → drop a single-file HTML at
architecture/<name>-explainer.html; cross-link from the other explainers + fromarchitecture/overview.md's Interactive explainers section.
See also
../CLAUDE.md— entry point for agents../AGENTS.md— package map + boundary rules + agent-driven development overview../README.md— project-level README
Conventions
- Markdown over HTML unless the doc is genuinely interactive (the 4 architecture HTMLs).
- Reference ADRs by ID (
ADR-NNN) rather than path so renames don't break links. - Cross-reference paths sparingly — they rot. Prefer naming the doc (e.g. "see the coverage guide").
- Don't duplicate — if two docs describe the same thing, consolidate or pick a single source of truth and link from the other.
- Date PRDs + ADRs in the file name (
YYYY-MM-DDprefix for PRDs) and in their frontmatter. - Each ADR cites at least one related ADR when extending or building on prior decisions.