Repospec — Architecture Overview

Status: Draft for review. This is the complete target architecture. It is the reference every issue and PR is measured against. Significant changes require an ADR (see docs/adr/). Product rationale lives in ../vision.md; the standard itself lives in ../../spec/.

1. Repospec is an umbrella; the Specification is its center

Repospec is not one program — it is a standard plus the components that materialize it. The Specification is primary; everything else implements or serves it.

Repospec
├── Repospec Specification   the standard — language-neutral, versioned   ◀ primary
├── Repospec Engine          reference implementation of the spec
├── Repospec CLI             one human entrypoint to the engine
├── Repospec Templates       default content the spec is seeded from
├── Repospec Adapters        project the spec into each assistant's format
└── Repospec Plugins         community extensions (opt-in, consent-gated execution)

The organizing layering is Specification → Engine → CLI → Repository (ADR-0007): the CLI calls the Engine, the Engine implements the Specification, the Specification describes the .repospec/ Repository. The test of the design: if the CLI vanished, the Specification and any other tool built on it still stand.

┌──────────────────────────────────────────────────────────────┐
│  THE SPECIFICATION  (the standard — language-neutral, versioned)│
│                                                                │
│   spec/*.md            normative definition (authored first)    │
│   schemas/         JSON Schema generated from the engine     │
│   .repospec/              the materialized protocol in a repo      │
│                                                                │
│   Source of truth. Any tool, in any language, can implement.   │
└──────────────────────────────────────────────────────────────┘
                              ▲   implements / maintains
                              │
┌──────────────────────────────────────────────────────────────┐
│  A REFERENCE IMPLEMENTATION  (TypeScript)                       │
│                                                                │
│   @repospec/protocol    executable spec: types + zod      │
│   @repospec/engine      operations: init/generate/sync... │
│   @repospec/templates   default content + adapter content │
│   @repospec/cli         commander + clack UX              │
└──────────────────────────────────────────────────────────────┘

The specification is the product. The reference implementation is how we make it easy to adopt and maintain. Keeping them separate — and versioned independently (ADR-0002) — is what lets Repospec become a standard rather than a single vendor's tool.

2. The .repospec/ directory (the protocol in a repo)

.repospec/
  project.yaml          # structured metadata — the machine-readable root
  constitution.md       # non-negotiable engineering principles (prose)
  architecture.md       # how THIS project is structured (prose)
  workflow.md           # how work flows: branching, review, release (prose)
  agents/               # role definitions (Markdown + frontmatter)
    <name>.md
  rules/                # focused, enforceable rules (Markdown + frontmatter)
    <name>.md
  templates/            # project-local scaffolding templates (optional)
  plugins/<id>/         # plugin packages + manifest (RFC-0001)
  plugins.lock          # operator approvals gating plugin execution

• project.yaml is the root. It declares the protocol version, project identity, stack, conventions, and which adapters are enabled. It is validated against a published JSON Schema.
• Prose files (constitution.md, architecture.md, workflow.md) are human/AI-readable and referenced from project.yaml.
• agents/* and rules/* use YAML frontmatter (validated identity + metadata) followed by a Markdown body.
• Everything under .repospec/ is owned by humans. Repospec seeds it from templates and never silently overwrites it.

Tool adapter outputs (owned by Repospec, generated)

These live in their native locations, are generated from .repospec/, and carry a managed header:

CLAUDE.md / AGENTS.md
.cursor/rules/repospec.mdc
.github/copilot-instructions.md
... (one per enabled adapter)

repospec sync regenerates these. They are owned by Repospec; humans edit .repospec/, not the outputs. See ADR-0003 and ADR-0004.

3. Package boundaries and dependency direction

cli ──▶ engine ──▶ protocol
            └────▶ templates ──▶ (protocol types only)

Strict, one-directional. Rationale in ADR-0001 (rename to engine in ADR-0007).

@repospec/protocol

The protocol made executable. No side effects beyond pure (de)serialization.

• TypeScript types for every .repospec/ artifact.
• zod schemas (the internal source of truth for validation).
• JSON Schema generation (published to schemas/, hosted on GitHub raw).
• PROTOCOL_VERSION constant + version compatibility helpers.
• parse/serialize a .repospec/ directory tree given an injected filesystem (so it is testable without touching disk).

Depends on: nothing (only zod).

@repospec/engine

The engine. Tool-UI-agnostic: it accepts plain data (interview answers, config), never prompts. This is what makes it testable and embeddable (a VS Code extension or CI action could use it directly).

• init pipeline: answers → validated config → file plan → write.
• bootstrap: infer a draft .repospec/ from an existing repo (offline; opt-in AI).
• generate: render artifacts/adapters from .repospec/.
• sync: diff desired vs. actual adapter outputs; apply respecting ownership.
• doctor: validate a repo's .repospec/, report problems, detect code drift.
• upgrade: migrate between protocol versions.
• review / architect: AI-assisted, via an injectable LlmClient port.
• the adapter registry (ten built-in renderers) and the plugin runtime (approved, integrity-pinned, run in a permission-restricted subprocess).

Depends on: protocol, templates.

@repospec/templates

Default content as data: the seed constitution.md, architecture.md, workflow.md, starter agents/ and rules/, and adapter output templates (CLAUDE.md, etc.). Minimal logic — mostly files + a manifest.

Depends on: protocol types only.

@repospec/cli

The only package that knows about a terminal. Thin mapping of commands to the engine. One front-end among possible others (editor extension, CI action).

• commander for command parsing.
• @clack/prompts for the interview.
• renders engine results to the terminal; no business logic here.

Depends on: engine.

4. Core flows

repospec init

1. Detect existing .repospec/  → if present, hand off to update/upgrade flow.
2. Run interview (cli) → raw answers.
3. engine: answers → normalized config → validate (zod).
4. engine: build a FilePlan (list of writes, with ownership tags).
5. Preview the plan (dry-run friendly).
6. Write .repospec/ from templates + answers.
7. Render enabled adapter outputs.
8. Print next steps.

Deterministic and offline. Re-run safe.

repospec sync

1. Load + validate .repospec/.
2. Render desired adapter outputs.
3. Diff against on-disk outputs (by managed checksum).
4. Human-modified output? → warn, skip unless --force.
5. Apply changes; report a summary.

repospec doctor

1. Locate .repospec/.
2. Validate project.yaml against the schema for its declared version.
3. Check referenced files exist; check adapters are in sync.
4. Report errors/warnings with fixes; exit non-zero on error.

5. Ownership model (summary)

Artifact	Owner	Sync behavior
.repospec/** (source of truth)	Human	Seeded once; never silently changed
Adapter outputs (CLAUDE.md …)	Repospec	Regenerated; protected by checksum

Full rules: ADR-0004.

6. Validation strategy

• zod schemas in protocol are the single internal source of truth.
• A build step emits a JSON Schema to schemas/ for external use.
• doctor and init validate with zod; error messages are human-first.
• Details: ADR-0005.

7. Versioning

• Protocol version (repospecProtocol) — semver of the standard. Slow, governed by RFC. Lives in spec/.
• Package versions — semver of each npm package, managed by Changesets.
• The CLI advertises which protocol versions it supports; mismatches are a clear, actionable error. Details: ADR-0002.

8. Technology stack (confirmed)

Concern	Choice	Notes
Language	TypeScript
Runtime	Node.js (LTS)	ESM-first
Package mgr	pnpm (workspaces)
Bundler	tsup	per-package
CLI parser	commander
Prompts	@clack/prompts	cli package only
Validation	zod	+ JSON Schema generation
Release	Changesets	addition — see W9
Format/Lint	prettier / eslint
Tests	vitest	snapshot the generated .repospec/ tree
Docs	Markdown	ADRs + spec + package READMEs

9. Testing strategy

• protocol: unit tests on schemas (valid/invalid fixtures), round-trip (de)serialization, JSON Schema generation snapshot.
• engine: pipeline tests with an in-memory fs; snapshot tests of the full generated .repospec/ tree per project archetype; sync ownership tests.
• cli: thin smoke/integration tests (command wiring, exit codes).
• examples/: real generated outputs kept in the repo as living fixtures and documentation.

10. Non-goals (for now)

• Not an agent runtime; Repospec does not execute AI calls except opt-in Phase 9.
• Not a replacement for any assistant; it feeds them.
• No plugin code execution except opt-in, consent- and integrity-gated (ADR-0008/0009).
• No network dependency for the core operations (Phases 1–8).