scc

Spec-driven development for Claude Code, Codex, and opencode — a single Go binary that turns the SDD workflow into a mechanically validated contract for humans and AI agents.

Status: pre-1.0. Scaffolding, artifact creation, validation, and updating all work. scc update currently replaces what is safe to replace and keeps anything you edited, naming it; the three-way merge that would resolve those in place is still ahead.

Use it

No install — run it straight from npm inside the repo you want to govern:

npx @protonspy/scc init                     # asks which harness, then scaffolds the rules, agents, and layout
npx @protonspy/scc init --codex             # or name it: --claude (default), --codex, --opencode
npx @protonspy/scc spec new user-auth       # specs/user-auth/: requirements.md, design.md, tasks.md
npx @protonspy/scc plan new checkout-revamp # plans/checkout-revamp.md
npx @protonspy/scc validate                 # every check; exit 2 means it found something
npx @protonspy/scc update                   # show what a newer scc would change, then confirm

Installed globally (npm i -g @protonspy/scc) the same commands are just scc init, scc spec new user-auth, and so on.

Command	What it does
init	Scaffolds the workspace and records what it wrote. Idempotent; never overwrites your edits.
update	Compares every managed file against this build, shows the plan, and applies it once you agree.
spec new|list|show|delete|validate	The three-artifact vehicle for work whose what and how need settling first.
plan new|list|delete|validate	One file, for everything else: a checklist, a decomposition into specs, or both.
skill validate	Conformance to the published Agent Skills spec.
validate	Every applicable validator, one exit code, one JSON document.
rtk	Wires in RTK: installs it if missing, then splices its usage block into the entry file.

RTK, optionally

RTK is a CLI proxy that filters command output down to what is worth spending context on. scc rtk — or scc init --rtk in one step — installs it with cargo when it is not on PATH, and puts its usage block into CLAUDE.md/AGENTS.md so the agent knows to prefix commands with it:

npx @protonspy/scc init --rtk    # scaffold, then wire RTK in
npx @protonspy/scc rtk           # wire it into a workspace that already exists
npx @protonspy/scc rtk --check   # CI: exit 2 when the block is missing

The block sits between RTK's own <!-- rtk-instructions --> markers, and scc inserts one only where there is none: a block already in the file is left exactly as it is, whatever version it claims, because RTK writes that block and rtk init is what refreshes it. --force replaces it with the copy this scc ships. Everything outside the markers is untouched either way.

Opt-in on purpose: it tells the agent to prefix every command with a binary the machine may not have. --no-install writes the block and never touches cargo.

Three harnesses, one methodology

The same rules, review agents, and skills — the knowledge base's authors, plus plan-run, which drives a whole plan group by group — are scaffolded into whichever tool you work in. Only the paths and the frontmatter dialect change.

	Claude Code	Codex	opencode
entry file	CLAUDE.md	AGENTS.md	AGENTS.md
rules	.claude/rules/	.codex/rules/	.opencode/rules/
review agents	.claude/agents/*.md	.codex/agents/*.toml	.opencode/agent/*.md
skills	.claude/skills/	.codex/skills/	.opencode/skills/
slash commands	.claude/commands/	— (skills are the surface)	.opencode/command/

specs/, plans/, and docs/ are identical everywhere: they are the product, not the tool. Running init twice with different flags gives one repo two managed trees, and update keeps both current.

What it checks

What gets checked: EARS grammar across all five patterns, requirement numbering, one methodology annotation per task, traceability in both directions, plan one-source-of-truth, skill conformance, wiki link/orphan graph, ADR numbering and superseding, glossary vocabulary drift, dependencies missing from docs/stack.md, and codewiki citations that no longer resolve.

What deliberately is not checked: your source code. scc never parses it, so it cannot tell you the code honors what the artifact says — that stays the orchestrator's accountability, and a checker that was confidently incomplete would be worse than none.

Install

Published on npm as @protonspy/scc — the launcher pulls the right prebuilt binary for your platform as an optional dependency, so there is no toolchain to set up.

npx @protonspy/scc help          # no install; pins nothing, always the latest
npx @protonspy/scc@0.0.1 help    # pin a version (CI)
npm i -g @protonspy/scc          # then: scc help

The package is @protonspy/scc; the command it installs is scc. Without -g it lands in node_modules/.bin, which npm scripts see and your shell does not — reach it there as npx scc.

Or from source (Go 1.25+):

go install github.com/protonspy/spec-claude-code/cmd/scc@latest

Prebuilt binaries for Linux, macOS, and Windows on x64/arm64 are attached to each release.

Design

One surface: a headless CLI. Every capability is reachable through flags, with --json output and a stable exit-code contract, so an agent or a CI job drives it exactly as well as a human does.

Exit code	Meaning
0	ok
1	usage or runtime error
2	the command ran and reported validation findings

The artifacts it governs are plain Markdown and JSON in your repo — the harness's own directory, specs/, docs/. No server, no database, no conversion layer: the files are the API, and they are the ones your harness already reads. scc adds no directory of its own and no config file — it owns a single manifest inside the harness's directory, which doubles as the workspace marker.

Development

make check    # the CI gate: gofmt + go vet + go test -race
make build    # -> ./scc
make help     # every target

See CLAUDE.md for architecture and conventions.

License

Apache-2.0. See LICENSE.