v0.2.0

[0.2.0] — 2026-07-01

Re-platforms Repospec from the single-file Python reference tool onto a TypeScript
monorepo with a real engine, CLI, and protocol packages. The .repospec/ directory
is still the human-authored source of truth; generation is now checksum-tracked and
ownership-aware.

Added

• Monorepo (pnpm workspaces). Four published packages:
  • @repospec/protocol — zod schemas, frontmatter/parse, repository model,
    protocol versioning.
  • @repospec/engine — the init, generate, sync, and doctor operations,
    tool adapters (agents, claude), and an injectable filesystem.
  • @repospec/cli — the repospec command-line front end.
  • @repospec/templates — the scaffolds init seeds.
• Idempotent, ownership-aware sync. Generated outputs carry a managed header
  with a sha256 checksum. sync will not overwrite a hand-edited output without
  --force; sync --check reports drift and exits non-zero (ADR-0004).
• doctor. Validates .repospec/ and reports problems with path-first
  messages; detects drift and version mismatch.
• Normative specification under spec/ (protocol, repository, lifecycle,
  workflow, configuration, versioning, RFC process) plus seven ADRs.
• Two worked examples, both engine-generated and drift-guarded in CI:
  demo-service and a richer acme-billing (six roles, billing rules).
• CI (.github/workflows/ci.yml): format, lint, build, typecheck, test, and an
  AGENTS.md drift-guard that runs repospec sync --check on every example.

Changed

• Renamed the npm scope and CLI to @repospec/* / repospec and the convention
  directory to .repospec/, completing the move off forge (Foundry collision).
• AGENTS.md is now generated by the TypeScript engine rather than the Python
  build tool, via the agents adapter.

Removed

• The Python reference tool (tools/repospec_build.py) and its standalone
  workflow, superseded by @repospec/engine. It remains available at the v0.1.0
  tag for the zero-dependency path.

Known limitations (open problems)

• Enforcement. AGENTS.md remains advisory to agents. CI now guards staleness
  (drift-guard) and validity (doctor); commit/merge-time gate hooks are future
  work.
• Code ⇄ .repospec/ drift. sync/doctor detect drift between source and
  generated outputs, but divergence between the code and the .repospec/
  description it documents is still not automatically detected.

v0.1.0

[0.1.0] — 2026-07-01

First working draft of the Repospec Protocol: an open, tool-agnostic standard that
makes a repository self-describing to AI coding agents. Humans author a .repospec/
directory; a build tool compiles it into the root AGENTS.md that agents already read.

Added

• Protocol specification (v0.1). docs/spec-v0.1.md defines the .repospec/
  directory — project.yaml, constitution.md, workflow.md, agents/, rules/,
  decisions/, history/, templates/ — and the invariant that humans edit
  .repospec/ while AGENTS.md is generated. Accompanied by docs/manifesto.md.
• Roles model. Named responsibilities (.repospec/agents/) with owned scope,
  bounded authority, and defined hand-offs — a contract per role, replacing
  "act like a senior engineer."
• Durable memory model. Versioned decisions (.repospec/decisions/, append-only
  ADRs) and narrative history (.repospec/history/) that outlive any single
  conversation or model.
• Reference build tool. tools/repospec_build.py compiles .repospec/ into
  AGENTS.md (repospec build) and, with --check, verifies the committed
  AGENTS.md is current without writing. Dependency-light — PyYAML only.
• CI drift-guard. .github/workflows/repospec.yml runs repospec build --check
  on every push and pull request, failing when AGENTS.md drifts from .repospec/.
• Worked example. examples/acme-billing/ — a complete .repospec/ and its
  generated AGENTS.md.

Changed

• Renamed the project forge → repospec to avoid colliding with Foundry's
  Solidity CLI, whose first command is literally forge init. The rename covers the
  protocol name, the CLI verb, the reference build tool, the .repospec/ convention
  directory, and all user-facing strings and prose.

Known limitations (open problems)

• Enforcement — partially addressed. AGENTS.md is advisory; an agent can ignore
  it. v0.1.0 ships a CI check that the compiled AGENTS.md is current, which closes
  the staleness gap. Optional gate hooks that enforce the workflow at commit/merge
  time remain future work.
• Drift detection — still open. When code and .repospec/ diverge (as opposed to
  AGENTS.md drifting from .repospec/), there is no mechanism yet to detect the
  divergence or decide which side wins before it misleads an agent.

@repospec/templates@0.9.0

Minor Changes

• d1b48e8: Add three built-in adapters — Zed (.rules), Cline
  (.clinerules/repospec.md), and Continue (.continue/rules/repospec.md) —
  bringing the total to nine. Paths verified against each tool's current
  documentation. Enable them in project.yaml adapters (or via repospec init).
• 7891ea3: repospec doctor now detects rule-target drift: a rule whose appliesTo
  globs match no files in the repository is flagged, since it targets code that no
  longer exists. This extends drift detection past the stack into the .repospec/
  artifacts themselves. It only runs when a rule declares appliesTo (repositories
  that don't use it pay nothing), and — like other drift — it's a warning that
  --strict promotes to a CI failure.

Patch Changes

• Updated dependencies [d1b48e8]
• Updated dependencies [7891ea3]
  • @repospec/protocol@0.9.0

@repospec/templates@0.8.0

Minor Changes

• 23e9fd7: Plugins are now bundled engine-side with esbuild before they run
  (ADR-0011),
  lifting ADR-0010's single-file constraint: a plugin may span multiple files and
  use dependencies (local imports and node_modules are inlined; node: builtins
  stay external). The integrity hash is now computed over the whole bundle, so
  tampering any imported file or dependency — not just the entry — fails the
  approval check. The sandbox is unchanged (the self-contained bundle runs in the
  zero-fs data:-URL child). @repospec/engine gains esbuild as a dependency; the
  integrity hash depends on the esbuild version (re-approve after an upgrade).

Patch Changes

• Updated dependencies [23e9fd7]
  • @repospec/protocol@0.8.0

@repospec/templates@0.7.0

Minor Changes

• 7e1a7fd: Plugin hardening: capability-gated network + npm resolution.

  • Network capability enforced (partial): a plugin not approved for the
    network capability runs with fetch and WebSocket replaced by throwing
    stubs. Low-level node:net/node:http can't be blocked in-process (Node has
    no network permission, and loader-hook gating needs --allow-worker, which the
    sandbox denies), so that residual remains — see ADR-0010; full isolation needs
    an OS sandbox.
  • npm resolution: a declared plugin now resolves from a local
    .repospec/plugins/<id>/ or an installed npm package <id> that ships a
    repospec-plugin.yaml. Resolution/reads happen engine-side; the sandboxed
    child still receives only the source (zero-fs). Plugin entries must remain
    single self-contained modules.

• 7c6e8f9: Harden the plugin sandbox (ADR-0010, supersedes ADR-0009's worker). Approved
  plugins now run in a child node process under Node's Permission Model with
  no filesystem access (no read or write), no child-process/worker/addon
  permissions, and env: {}. The engine reads the (integrity-checked) plugin
  source and the child imports it as a data: URL, so it needs zero fs grants —
  an OS-enforced boundary, not cooperative isolation. Filesystem writes from a
  plugin are now blocked by the runtime (verified by test). Constraint: a plugin
  entry must be a single self-contained module (bundle any dependencies), since a
  data: URL cannot resolve relative or node_modules imports.

Patch Changes

• Updated dependencies [7e1a7fd]
• Updated dependencies [7c6e8f9]
  • @repospec/protocol@0.7.0

@repospec/templates@0.6.0

Minor Changes

• b74f6a0: Ship the plugin runtime (ADR-0008 trust model, ADR-0009 sandbox, RFC-0001
  manifest/lockfile). Plugins now execute — safely and opt-in:

  • protocol: PluginManifest / PluginLock schemas + parsePluginManifest,
    parsePluginLock, serializePluginLock.
  • engine: runPlugins / resolvePlugins / buildApprovalLock + integrityOf.
    A plugin runs only if .repospec/plugins.lock approves it with a matching
    integrity hash and the generate-outputs capability (declared + approved).
    Execution is a worker_threads worker with no ambient environment;
    integrity + consent are the load-bearing controls (the worker is
    defense-in-depth, not a hard boundary — see ADR-0009). Outputs flow through the
    same ownership/managed pipeline as adapters.
  • cli: repospec plugins list / repospec plugins approve, and --plugins
    on generate / sync (off by default). Plugin execution is opt-in and skipped
    with a warning for anything unapproved or tampered.

Patch Changes

• 604f373: Refresh package READMEs to the current, feature-complete surface: all nine CLI
  commands, six adapters, the LlmClient port, the plugin runtime, and the
  manifest/lockfile schemas (they previously described a Milestone 1–3 subset).
• Updated dependencies [604f373]
• Updated dependencies [b74f6a0]
  • @repospec/protocol@0.6.0

@repospec/templates@0.5.0

Minor Changes

• 07bec44: Add opt-in AI assist to repospec bootstrap (--ai). When enabled, the detected
  facts (project name + the inference evidence — metadata only, never source code)
  are sent to the model to refine the project description; the result is still a
  draft for human approval. planBootstrap gains an optional llm (the engine's
  injectable LlmClient port), so the assist is provider-agnostic and unit-tested
  with a fake. Offline inference remains the default. Closes roadmap 7.2.

• 16f258c: Add the AI-assisted operations repospec review and repospec architect,
  completing the protocol's command surface.

  • review judges a change (a git diff) against the repository's constitution
    and rules, returning structured findings; exits non-zero on an error-severity
    finding (--strict for any finding).
  • architect drafts or revises .repospec/architecture.md from the project
    identity and current document; prints a draft, --write to save it.

  The engine gains a small, injectable LlmClient port, so the operations stay
  UI- and vendor-agnostic and unit-testable with a fake (ADR-0007). The CLI
  supplies a Claude implementation via @anthropic-ai/sdk (model claude-opus-4-8,
  adaptive thinking); it resolves credentials from ANTHROPIC_API_KEY or an
  ant auth login profile. All roadmap command stubs are now implemented.

• 49809e9: Plugins (declarative), deeper drift detection, and a command reference.

  • Plugins (declarative only): doctor validates declared plugins (warns on
    duplicates) and the generated guide now lists them, explicitly noting no plugin
    code is executed (spec §3.7; roadmap Milestone 6 discovery + validation).
  • Deeper code drift: doctor now also compares declared runtimes against the
    repo, and bootstrap infers the Node runtime version from package.json
engines.node (e.g. node20).
  • Docs: add docs/commands.md (full command reference) and refresh TODO.md
    to the current, feature-complete command surface.

• 93c0c91: Add template rendering primitives to @repospec/templates: interpolate (a
  {{ dotted.path }} substitution engine that throws on a missing variable rather
  than emitting a blank) and partials (reusable snippets). The seed
  architecture.md now renders through them, and both are exported for future
  user-authored templates (roadmap Milestone 4).

Patch Changes

• Updated dependencies [07bec44]
• Updated dependencies [16f258c]
• Updated dependencies [49809e9]
  • @repospec/protocol@0.5.0

@repospec/templates@0.4.0

Minor Changes

• f81d077: repospec doctor --strict treats warnings — including code ⇄ .repospec/ drift —
  as failures, so CI can gate on them. Also extend drift detection to testing tools
  (declared stack.testing vs the dependencies), in both directions.
• c06a2c7: Implement repospec upgrade — the protocol-migration operation (spec/versioning.md
  §4). It reads the repository's declared repospecProtocol, compares it to what the
  tool targets, and: reports when already current; refuses a repo declaring a newer
  protocol; and, for an older repo, applies the chain of migrations, bumping
  repospecProtocol (edits to source artifacts require consent). The migration
  registry is empty for now — 0.1 is the first protocol version — but the mechanism
  is complete and tested. Adds parseProtocolVersion / compareProtocolVersions to
  @repospec/protocol.

Patch Changes

• Updated dependencies [f81d077]
• Updated dependencies [c06a2c7]
  • @repospec/protocol@0.4.0

@repospec/templates@0.3.0

Minor Changes

• f3ad5c6: Add repospec bootstrap — infer a draft .repospec/ from an existing repository
  using offline heuristics (manifests, lockfiles, dependencies), presented for human
  review before writing. Add Windsurf (.windsurf/rules/repospec.md) and Gemini CLI
  (GEMINI.md) adapters.
• 2e80c89: repospec doctor now warns on code ⇄ .repospec/ drift: it compares the declared
  stack (languages, package manager, frameworks) against what the repository actually
  contains, using the same offline inference as bootstrap. Warnings only, gated to
  repositories with a package.json. Also fix repospec --version, which reported
  0.0.0 instead of the real package version.

Patch Changes

• 0577d96: Add keywords to each package for npm discoverability.
• Updated dependencies [f3ad5c6]
• Updated dependencies [2e80c89]
• Updated dependencies [0577d96]
  • @repospec/protocol@0.3.0

@repospec/templates@0.2.1

Patch Changes

• 11465bf: Point the generated project.yaml $schema at a hosted JSON Schema
  (raw.githubusercontent.com/npxchaos/repospec/main/schemas/0.1/project.schema.json)
  instead of the unhosted repospec.dev URL, fixing a dead link in every generated
  repository.
• Updated dependencies [11465bf]
  • @repospec/protocol@0.2.1