Four-layer single-repository architecture
ADR-0001: Four-layer single-repository architecture
Section titled “ADR-0001: Four-layer single-repository architecture”Status
Section titled “Status”Accepted
Context
Section titled “Context”Background and Problem Statement
Section titled “Background and Problem Statement”A research harness must package the orchestration engine, the methodology skills,
the contracts, the knowledge graph, and the output pipelines into something a
user can clone (or instantiate with Copier) and use immediately. The question is
where the boundary between the engine and the harness services should fall:
across repositories, or inside one (docs/explanation/architecture.md, design
spec §1, §3).
Current Limitations
Section titled “Current Limitations”The defining defect of the prior system was that the capability was split across two repositories that had to be assembled by hand: the engine (a Claude Code plugin) and the harness layer (a corpus repo). Neither half alone was a research harness, and the quality-enforcement hooks lived corpus-side, so they did not travel with the tool on clone.
Decision Drivers
Section titled “Decision Drivers”Primary Decision Drivers
Section titled “Primary Decision Drivers”- A clone must be a working harness with nothing left to assemble by hand.
- Enforcement (hooks, gates) must ship and run on clone, not live elsewhere.
Secondary Decision Drivers
Section titled “Secondary Decision Drivers”- The engine/services split should remain legible without a repo boundary.
- One distribution unit must support both
git cloneand Copier instantiation.
Considered Options
Section titled “Considered Options”Option 1: Two repositories (engine plugin + corpus repo)
Section titled “Option 1: Two repositories (engine plugin + corpus repo)”Description: Keep the prior system’s shape — the engine ships as a Claude Code plugin in one repo and the corpus/harness layer lives in a second repo, assembled together by the user.
- Advantages: Each half can be released on its own cadence and versioned independently.
- Disadvantages: Neither half is a harness alone; assembly is manual and error-prone, and enforcement hooks stay corpus-side and do not travel with the tool.
- Risk Assessment: technical low; schedule low; ecosystem high (reproduces the assembly defect).
Option 2: Single repository, four internal layers
Section titled “Option 2: Single repository, four internal layers”Description: Ship Engine, Contracts, Harness services, and Outputs as four layers inside one repository, all present on clone, with the engine/services boundary as a module boundary inside the repo.
- Advantages: The whole harness ships on clone; bundled hooks under
.claude/hooks/travel with the engine;harness.config.jsonis the single deploy contract a user edits. - Disadvantages: The engine cannot be versioned fully independently of the corpus.
- Risk Assessment: technical low; schedule low; ecosystem low.
Option 3: Monorepo of many published packages
Section titled “Option 3: Monorepo of many published packages”Description: Split each layer into an independently versioned and released package within a monorepo.
- Advantages: Maximal independent versioning of each layer.
- Disadvantages: Reintroduces the assembly problem and demands heavy release tooling for a single-author template.
- Risk Assessment: technical high; schedule high; ecosystem medium.
Decision
Section titled “Decision”Adopt Option 2: a single repository with four internal layers. The
repository ships four layers on clone — Engine (.claude/agents/ +
.claude/commands/), Contracts (schemas/), Harness services (multi-topic
registry, knowledge graph, search, discovery, reindex), and Outputs
(reports/, channels, packs). The engine↔services boundary is a module boundary
inside one repo (§6a), and enforcement hooks ship under .claude/hooks/.
Consequences
Section titled “Consequences”Positive
Section titled “Positive”- A clone is immediately a complete harness; enforcement is portable because it travels with the engine.
harness.config.jsonis the single deploy contract a user edits.
Negative
Section titled “Negative”- The engine is not independently releasable from the corpus.
Neutral
Section titled “Neutral”- The engine/services split is preserved as a module boundary rather than a repo boundary — the same separation, expressed differently.
Decision Outcome
Section titled “Decision Outcome”The four-layer single repository eliminates the manual-assembly defect of the prior two-repo system: everything needed to research, verify, and publish ships on clone. The loss of independent engine versioning is the deliberate trade that buys portability of both capability and enforcement.
Related Decisions
Section titled “Related Decisions”More Information
Section titled “More Information”- Date: 2026-06-23
- Source:
docs/explanation/architecture.md,README.md
2026-06-23
Section titled “2026-06-23”Status: Compliant
| Finding | Files | Assessment |
|---|---|---|
| Engine layer ships on clone | .claude/agents/, .claude/commands/ | compliant |
| Contracts layer ships on clone | schemas/ | compliant |
| Single deploy contract present | harness.config.json, harness.config.schema.json | compliant |
| Enforcement travels with the engine | .claude/hooks/ | compliant |
Summary: All four layers and the bundled hooks are present in the repository on clone.
Action Required: None