Contributing to Repospec

Thank you for helping build Repospec. This project aims to become a standard, so the way we work is deliberate. Please read this before opening your first PR.

Two tracks of change

You are changing…	Process
Code (CLI, engine, templates, adapters, docs, tests)	Pull Request
The protocol itself (the .repospec/ format or its meaning)	RFC first — see spec/rfcs/0000-template.md and docs/governance.md

Protocol changes are heavier on purpose: third parties depend on the format's stability.

Prerequisites

• Node.js (see .nvmrc)
• pnpm 10+ (corepack enable will provide it)

Setup

pnpm install
pnpm build
pnpm test

The development loop

pnpm dev            # watch-build all packages
pnpm test:watch     # run tests in watch mode
pnpm lint           # eslint
pnpm format         # prettier --write
pnpm typecheck      # tsc --noEmit across packages

Before pushing, make sure the full check suite is green (this is exactly what CI runs):

pnpm format:check && pnpm lint && pnpm build && pnpm typecheck && pnpm test

Repository structure

spec/        the Repospec Specification (the standard) — read this first
docs/        architecture, ADRs, roadmap, governance, vision
packages/    the reference implementation
  protocol/  executable spec (types + zod)
  engine/    protocol operations (UI-agnostic)
  templates/ default content + adapter templates
  cli/       the repospec command-line front-end

The dependency direction is strict: cli → engine → protocol/templates (ADR-0001 / ADR-0007). Do not import "upward."

Definition of Done

Every change must satisfy:

• [ ] Tests pass and cover the change (pnpm test).
• [ ] Docs updated (package README / ADR / spec as applicable).
• [ ] A changeset is included for user-facing changes (pnpm changeset).
• [ ] It respects the ownership model (ADR-0004) and protocol versioning (ADR-0002).
• [ ] pnpm format:check && pnpm lint && pnpm typecheck are clean.

Commits & PRs

• Keep changes small and focused — one concern per PR (charter: "small iterations over rewrites").
• Use clear, imperative commit subjects.
• Reference the issue/milestone from docs/roadmap.md where relevant.

Architecture decisions

Significant or hard-to-reverse decisions are recorded as ADRs in docs/adr/. If your change makes such a decision, add an ADR using docs/adr/template.md.

Code of Conduct

Participation is governed by our Code of Conduct.