spec-init

Throughspec - spec-driven, drift-proof, token-lean scaffolding for Claude Code. spec-init bootstraps a project around a deterministic, spec-first SDLC: you make the decisions, Claude does the heavy lifting, and a fixed structure keeps the work from drifting.

The same CLI ships on PyPI (this package) and npm from one source-of-truth template tree, verified byte-for-byte.

Install

# recommended (isolated)
pipx install spec-init
spec-init my-project

# or regular pip
pip install spec-init
spec-init my-project

Requires Python ≥ 3.10.

Quickstart

# scaffold, then open in Claude Code and run /spec-requirements
spec-init my-project
cd my-project

Run with no arguments in a terminal for an interactive welcome (new-vs-existing, persona, integrations). In a non-interactive shell (CI, pipes) it prints help instead, so scripts are unaffected.

spec-init <name> scaffolds the canonical Throughspec tree:

my-project/
├── CLAUDE.md
├── README.md
├── CHANGELOG.md
├── SECURITY.md
├── CONTRIBUTING.md
├── claude/
│   ├── srs.md
│   ├── plan.md
│   ├── context.md
│   ├── features.md
│   ├── design-decisions.md
│   └── learnings.md
├── design/
│   └── design.md
├── .claude/
│   ├── skills/
│   └── agents/
└── .spec-init/base/    # pristine snapshot for upgrade

Commands

Flags

• --persona vibe|student|engineer|team - which CLAUDE.md persona block to keep.
• --integrations <csv> - activate integrations at scaffold time (see below).
• --force - overwrite an existing directory (init) or replace existing spec files (reinit).
• --dry-run - print the plan without writing files.
• -h, --help / -v, --version.

Integrations

Opt-in, free/open-source tools layered in without touching your source. Add at scaffold time (--integrations graphify,caveman) or later (spec-init customize --add obsidian); remove with customize --remove <name>.

graphify, obsidian, caveman, agentmemory, openwiki, ponytail, opencodereview.

See the Integrations docs for what each does.

Both channels produce byte-identical scaffolded trees for every persona/integration combination, enforced by a cross-language parity test.

The .spec-init/base/ snapshot

init writes a pristine copy of the payload into <project>/.spec-init/base/. upgrade uses it as the common ancestor for its three-way merge; doctor checks it exists. Don't edit files under .spec-init/ - they are the CLI's private state.

Links

• Docs: https://throughspec.v-ai.org/docs/
• Changelog: https://throughspec.v-ai.org/changelog/
• Source & issues: https://github.com/VishalPatil18/throughspec
• Contributing: see CONTRIBUTING.md for local dev and build.

License

MIT © Vishal Patil