Repospec

Appearance

Repospec Protocol — TODO & Milestones ​

High-level tracker. Detail lives in docs/roadmap.md; rationale in docs/architecture/overview.md and the ADRs. Phases follow the charter in order.

Status key ​

[ ] not started · [~] in progress · [x] done

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

  • [x] S.1 docs/vision.md — product argument
  • [x] S.2–S.8 spec/{protocol,repository,configuration,agent,workflow,lifecycle,versioning}.md
  • [x] S.9 spec/rfcs/0000-template.md
  • [x] ADR-0007 specification-first architecture; core → engine

▸ Milestone 0 — Repository foundation — ✅ DONE ​

  • [x] 0.1 Scaffold pnpm monorepo (tsconfig, eslint, prettier, vitest)
  • [x] 0.2 Packages with enforced boundaries (ADR-0001): protocol, engine, templates, cli
  • [x] 0.3 CI pipeline (format/lint/build/typecheck/test) + Changesets
  • [x] 0.4 Meta files (CONTRIBUTING, CoC, SECURITY, CODEOWNERS, issue/PR templates)

▸ Milestone 1 — Phase 1 & 2: Structure & CLI shell — ✅ DONE ​

  • [x] 1.1 protocol: types + zod schemas for project.yaml, agents, rules
  • [x] 1.2 protocol: (de)serialize a .repospec/ tree (injected fs)
  • [x] 1.3 cli: commander shell + clack, all commands registered

▸ Milestone 2 — Phase 3 & 4: repospec init → static .repospec/ — ✅ DONE ​

  • [x] 2.1 templates: seed content (constitution, architecture, workflow, agents, rules)
  • [x] 2.2 engine: init pipeline (answers → FilePlan → write), re-run safe
  • [x] 2.3 cli: interview UX (+ non-interactive --yes)
  • [x] 2.4 In-memory end-to-end tests + committed examples/demo-service

▸ Milestone 3 — Phase 5: Config files & adapters — ✅ DONE ​

  • [x] 3.1 engine: adapter registry + interface (ADR-0003)
  • [x] 3.2 Adapters: Claude (CLAUDE.md), AGENTS.md, Cursor, Copilot, Windsurf, Gemini, Zed, Cline, Continue, Claude Code subagents (.claude/agents/)
  • [x] 3.3 repospec generate
  • [x] 3.4 repospec sync with ownership guard + --check (ADR-0004)
  • [x] 3.5 repospec doctor

▸ Milestone 4 — Phase 6: Templates system ​

  • [x] 4.1 Variable interpolation + partials (interpolate / partials, used by seed content)
  • [x] 4.2 Cursor + Copilot adapters (shipped early in Milestone 3)
  • [x] 4.3 Template authoring docs (docs/templates.md)

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

  • [x] 5.1 Generate JSON Schema from zod → schemas/0.1/ (ADR-0005), CI drift-guard
  • [x] 5.2 Conformance test suite (examples + fixtures validated against the schemas)
  • [x] 5.3 repospec upgrade + version-mismatch handling (ADR-0002)
  • [ ] 5.4 Reconcile generated schema with spec/*.md (drift snapshot) (normative prose spec + RFC scaffolding delivered in Milestone S)

▸ Milestone 6 — Phase 8: Plugins (declarative first) ​

  • [x] 6.1 Declarative plugin schema (PluginRefSchema)
  • [x] 6.2 Security ADR for plugin runtime — ADR-0008 (execution stays blocked until its controls ship)
  • [x] 6.3 Plugin discovery + validation (no execution) + SECURITY.md

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

  • [x] 7.1 Repo analysis → draft answers (offline heuristics) — repospec bootstrap
  • [x] 7.2 Optional AI provider behind explicit flag (bootstrap --ai; sends detected metadata only, no source)
  • [x] 7.3 Human approval gate before writing (bootstrap consent prompt)

Beyond the original roadmap: repospec review / repospec architect (AI-assisted, via an injectable LlmClient), and code ⇄ .repospec/ drift detection in doctor (--strict gates it in CI) — both stack drift and rule-target drift (a rule whose appliesTo globs match no files)._

Definition of Done (every issue) ​

  • [ ] Tests pass (unit + relevant snapshots)
  • [ ] Docs updated (package README / ADR / spec as applicable)
  • [ ] A Changeset is included for user-facing changes
  • [ ] Respects ownership model (ADR-0004) and protocol versioning (ADR-0002)

Current state (2026-07-01) ​

The full command surface is implemented: init, bootstrap, generate, sync (--check + ownership guard), doctor (--strict, with code-drift detection), upgrade, review, and architect. Ten adapters render tool entrypoints (Claude, AGENTS.md, Cursor, Copilot, Windsurf, Gemini, Zed, Cline, Continue) — plus claude-agents, which projects each role into a native Claude Code subagent under .claude/agents/. JSON Schema is generated from zod and drift-guarded in CI. Packages are published to npm and released automatically via Changesets. See docs/commands.md.

Every roadmap deliverable is done, plus post-roadmap plugin hardening. The gated plugin runtime ships (RFC-0001): manifests, an integrity-pinned approval lockfile, consent-gated opt-in execution (plugins list/approve, generate --plugins), resolved from local .repospec/plugins/ or npm. Execution runs in a subprocess under Node's Permission Model with no filesystem access (ADR-0010, supersedes ADR-0009's worker), and fetch/WebSocket are denied without the network capability. Plugins are bundled with esbuild engine-side (ADR-0011) so they can span multiple files and dependencies, with integrity pinned over the whole bundle. Remaining hardening: airtight network isolation (an OS sandbox covering sockets — node:net isn't blockable in-process).

Released under the MIT License.

Copyright © npxchaos