Repospec

Appearance

Repospec Protocol — Implementation Roadmap ​

This roadmap turns the architecture into sequenced, shippable work. It follows the nine phases from the charter in order — phases are never skipped. Each phase maps to a milestone, each milestone to a set of GitHub issues, and each issue to small implementation tasks.

Legend: every issue below is sized to be a single, reviewable PR. Tasks inside an issue are checklist items, not separate PRs.

Status (2026-07-01): all milestones S–7 are delivered and shipped in the published @repospec/* packages — including the gated plugin runtime (Milestone 6) and AI-assisted bootstrap (Milestone 7). This document is the original, sequenced plan; the checklists below are kept as that historical plan and do not track current completion. For live status see ../TODO.md, and for the shipped command surface see commands.md.

Milestone S — Specification & Vision (precedes all code) — ✅ DONE ​

Goal: the standard exists in writing before any implementation, so the engine and CLI are built to a contract (ADR-0007). Status: delivered in the design phase.

  • [x] S.1 docs/vision.md — the product argument (why Repospec exists).
  • [x] S.2 spec/protocol.md — terminology, principles, conformance levels.
  • [x] S.3 spec/repository.md — .repospec/ layout + ownership model.
  • [x] S.4 spec/configuration.md — project.yaml fields + validation.
  • [x] S.5 spec/agent.md — agent & rule artifacts (frontmatter + body).
  • [x] S.6 spec/workflow.md — engineering-workflow artifact.
  • [x] S.7 spec/lifecycle.md — states + protocol operations (CLI-independent).
  • [x] S.8 spec/versioning.md — protocol semver, compatibility, migration.
  • [x] S.9 spec/rfcs/0000-template.md — RFC process scaffolding.

The JSON Schema (schemas/0.1/) is intentionally generated later, from the engine (Milestone 5), with this prose as the authoritative source.

Milestone 0 — Repository foundation (precedes Phase 2 code) ​

Goal: a contributor can clone, install, build, lint, and test an empty monorepo. No product code yet.

Issue 0.1 — Scaffold the pnpm monorepo ​

  • [ ] package.json (private root), pnpm-workspace.yaml (packages/*).
  • [ ] Base tsconfig.base.json; per-package extends.
  • [ ] prettier + eslint config at the root; format/lint scripts.
  • [ ] vitest config at the root; test script.
  • [ ] Node + pnpm version pin (.nvmrc / packageManager).

Issue 0.2 — Create empty packages with boundaries (ADR-0001) ​

  • [ ] packages/{protocol,engine,templates,cli} each with package.json, src/index.ts, tsup.config.ts, and a stub README.md.
  • [ ] Wire the dependency graph (cli→engine→protocol/templates).
  • [ ] build script that builds all packages via tsup.

Issue 0.3 — CI pipeline ​

  • [ ] GitHub Actions: install → build → lint → test on PRs.
  • [ ] Cache pnpm store.
  • [ ] Add Changesets + a release-check job.

Issue 0.4 — Project meta files ​

  • [ ] CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, CODEOWNERS.
  • [ ] Issue/PR templates under .github/.
  • [ ] Expand root README.md with quickstart + links to docs/.

Milestone 1 — Phase 1 + Phase 2: Structure & CLI shell ​

Goal: repospec --help runs and lists planned commands; the CLI is wired to engine stubs.

Issue 1.1 — protocol: types + zod schemas for project.yaml ​

  • [ ] Define Project type + zod schema (name, description, repospecProtocol, stack, conventions, repo type, adapters).
  • [ ] Define frontmatter schemas for agents/* and rules/*.
  • [ ] Export PROTOCOL_VERSION and supports() (ADR-0002).
  • [ ] Unit tests: valid + invalid fixtures.

Issue 1.2 — protocol: (de)serialize a .repospec/ tree ​

  • [ ] Injected-fs interface; read/parse .repospec/ → model; serialize model → files.
  • [ ] Round-trip tests with an in-memory fs.

Issue 1.3 — cli: commander shell + clack bootstrap ​

  • [ ] repospec binary; register command stubs: init, doctor, sync, review, bootstrap, upgrade, architect, generate.
  • [ ] Global --version (CLI + supported protocol range), --help.
  • [ ] Each stub prints "not yet implemented" + exit codes.
  • [ ] Smoke test: --help and --version.

Milestone 2 — Phase 3 + Phase 4: repospec init → static .repospec/ ​

Goal: repospec init runs an interview and writes a complete, valid .repospec/.

Issue 2.1 — templates: seed content + manifest (ADR-0006) ​

  • [ ] Seed constitution.md, architecture.md, workflow.md.
  • [ ] Starter agents/* and rules/* with valid frontmatter.
  • [ ] Template manifest (files, ownership, target paths, variables).

Issue 2.2 — engine: init pipeline (answers → FilePlan → write) ​

  • [ ] normalize(answers) → config; validate with zod.
  • [ ] Build a FilePlan (writes tagged with owner).
  • [ ] Execute the plan via injected fs; dry-run support.
  • [ ] Detect existing .repospec/ → defer to update/upgrade (W8); never overwrite without a flag.

Issue 2.3 — cli: interview UX for init ​

  • [ ] clack flow: project identity, stack, conventions, adapters.
  • [ ] Map answers → engine; render the FilePlan preview; confirm; write.
  • [ ] --yes/non-interactive mode using defaults.

Issue 2.4 — Snapshot tests + example output ​

  • [ ] Snapshot the generated .repospec/ tree for 2–3 archetypes (TS library, web app, service).
  • [ ] Commit a generated example under examples/.

Milestone 3 — Phase 5: Configuration files & adapters ​

Goal: .repospec/ projects into at least one assistant's native entrypoint, kept current by sync.

Issue 3.1 — engine: adapter registry + interface (ADR-0003) ​

  • [ ] Adapter contract: id, owned paths, render(model).
  • [ ] Registry + selection from project.yaml.

Issue 3.2 — First adapter: Claude / AGENTS.md + CLAUDE.md ​

  • [ ] Render .repospec/ → assistant entrypoint with managed header (ADR-0004).
  • [ ] Snapshot test of rendered output.

Issue 3.3 — repospec generate ​

  • [ ] Render enabled adapters (or a targeted subset).
  • [ ] Wire CLI command + tests.

Issue 3.4 — repospec sync with ownership guard (ADR-0004) ​

  • [ ] Checksum-based diff; skip human-modified outputs; --force.
  • [ ] --check mode for CI (no writes, non-zero on drift).
  • [ ] Idempotency test (second run = no writes).

Issue 3.5 — repospec doctor ​

  • [ ] Validate project.yaml for its declared version; check referenced files; detect adapter drift.
  • [ ] Human-first error messages; non-zero exit on error.

Milestone 4 — Phase 6: Templates system ​

Goal: templates are extensible and well-documented (still bundled/offline).

Issue 4.1 — Variable interpolation + partials in templates. ​

Issue 4.2 — Additional adapters (Cursor, Copilot) behind the registry. ​

Issue 4.3 — templates README documenting how to author a template. ​

Milestone 5 — Phase 7: Protocol validation & published schema ​

Goal: the (already-authored, Milestone S) specification becomes machine-checked and externally consumable.

Issue 5.1 — Generate JSON Schema from zod → schemas/0.1/ (ADR-0005). ​

Issue 5.2 — Conformance test suite: validate fixtures against the spec. ​

Issue 5.3 — repospec upgrade skeleton + version-mismatch errors (ADR-0002). ​

Issue 5.4 — Reconcile generated schema with spec/*.md; drift snapshot test. ​

Note: the normative prose spec and RFC scaffolding were delivered in Milestone S. This milestone makes them executable, it does not re-author them.

Milestone 6 — Phase 8: Plugins — ✅ DONE ​

Goal: a plugin model exists and executes safely — gated by consent + integrity + a worker sandbox (ADR-0008, ADR-0009, RFC-0001).

Issue 6.1 — Declarative plugin schema (PluginRefSchema + manifest/lockfile). ​

Issue 6.2 — Security ADR for the plugin runtime (trust/sandbox): ADR-0008/0009. ​

Issue 6.3 — Plugin discovery + validation + approval + gated execution. ​

Milestone 7 — Phase 9: AI-powered bootstrap (opt-in) ​

Goal: repospec bootstrap/repospec architect can infer a draft .repospec/ from an existing repo. Strictly opt-in; the only network feature.

Issue 7.1 — Repo analysis → draft answers (offline heuristics first). ​

Issue 7.2 — Optional AI provider behind an explicit flag/config; redaction ​

            and consent UX.

Issue 7.3 — Human review/approval gate before writing (human decisions win). ​

Sequencing rules ​

  • Do not start a milestone before the prior one is green in CI.
  • Any issue touching spec/ or protocol's public shape requires an RFC + ADR.
  • Each issue ships with tests and docs — no exceptions (charter rule).

Released under the MIT License.

Copyright © npxchaos