Throughspec v1.0 - spec-driven development for Claude Code, now on npm + PyPIRead the docs
SPEC-DRIVEN SDLC · FOR CLAUDE CODE

Collapse the gap between
idea and shipped software.

Throughspec scaffolds a deterministic, spec-first workflow into Claude Code. You make the decisions. Claude does the heavy lifting. Structure keeps the work from drifting.

Get started Read the docs
$
IDEAREQUIREMENTSCONSTRAINTSNON-GOALSREFERENCESSHIPPED CODETESTSMEMORY FILESDOCSCHANGELOGPSISPEC ENGINEdeterministic · running01020304ASKSPECPLANBUILD
Your decisionsDeterministic SDLCShipped, with memory
Built for the way you actually build
Vibe-coders
Students
Solo engineers
Team leads

Three load-bearing beliefs

Everything in the Kit is downstream of these.

01 / SPEC

Spec beats vibe.

Cross-questioning before code beats open-ended prompting. Throughspec makes a complete spec a precondition - it refuses to proceed without one.

02 / MEMORY

Memory beats re-derivation.

Re-reading source to reconstruct intent is a token tax. The Kit invests once in condensed memory files and amortizes that across every prompt.

03 / STRUCTURE

Structure compounds.

A predictable layout means skills, agents, and humans all know where to look. The Kit refuses to ship freeform - structure is the product.

The initiation cycle

Five commands from empty folder to your first feature.

01
Scaffolds the canonical directory tree with safe, lint-clean defaults - in under five seconds.
02
Three-plus rounds of cross-questioning, then freezes claude/srs.md. Won’t proceed on empty load-bearing categories.
03
Extracts a design system from your references, or proposes one from the SRS - never fabricates brand colors.
04
Produces an 8-10 step build plan, each ending in a standalone, testable, runnable deliverable.
05
Enters the feature cycle, one step at a time - read memory, cross-question, implement, test, refactor.
The feature cycle

No step skipped. No code unspecced.

/spec-feature runs six ordered steps, every time.

01
Requirements
Cross-question transcript → features.md
02
Architecting
≥2 options + tradeoffs → decisions
03
Product Specs
UI, UX, entities, DB schema
04
Tech Specs
Stack + deploy, rejected alts noted
05
Planning
Step-by-step plan, acceptance criteria
06
Writing Code
Implement → test → refactor → memory
The memory layer

Memory beats re-derivation.

Re-reading source to reconstruct intent is a token tax. Throughspec writes condensed memory once - then every prompt reads the snapshot instead of re-scanning the repo.

CLAUDE.md- router + behavior contract
context.md- compressed current state
srs.md- frozen requirements
plan.md- 8-10 step plan
features.md- append-only feature log
design-decisions.md- append-only decisions
~8k token ceiling
Skills catalog

Nine slash commands. One for every move you make.

/spec-init
Scaffold the project inside an existing Claude session.
/spec-requirements
Build claude/srs.md via cross-questioning.
/spec-design
Build design/design.md and download UI assets.
/spec-plan
Build claude/plan.md with 8-10 step deliverables.
/spec-feature
Run the full feature development cycle.
/spec-refactor
Clean only the current cycle’s diff - nothing else.
/spec-bug
Isolated bug resolution: reproduce, test, smallest fix.
/spec-docs
Reconcile docs against reality - never touches source.
/spec-sync
Reconcile context.md against actual repo state.
◈
Graphify

Treat the codebase as a queryable knowledge graph. Claude prefers Graphify queries over full-repo greps when available.

◉
Obsidian

Visualize the claude/ and design/ markdown corpus as a navigable graph, with front-matter conventions baked in.

Questions, answered

Does Throughspec replace Claude Code?+
No. The Kit composes on top of Claude Code’s permission, hook, and settings model - it scaffolds process, not application source, and never hosts or runs Claude Code itself.
How does it keep token cost flat as a project matures?+
A condensed context.md replaces N file scans per prompt, refactors are diff-scoped, memory logs are append-only, and /spec-sync compresses any memory file past 1,500 lines. Target: a 5th feature cycle costs ≤120% of the first.
Can I skip cross-questioning to go faster?+
No. The requirements skill refuses to proceed until target users, jobs-to-be-done, the primary success metric, hard constraints, and non-goals are all filled. Overrides require an explicit, logged decision.
npm or PyPI?+
Both. npx spec-init for Node ≥18, pipx install spec-init for Python ≥3.10. A single source-of-truth template tree feeds both channels, so they never drift.
What about my edits when I upgrade?+
The upgrade command never overwrites your content - it does a three-way merge and surfaces conflicts for manual resolution. Every workflow is also resumable if interrupted.
Is it cross-platform?+
Yes - macOS, Linux, and Windows (PowerShell + WSL), with no compiled native binary required at install time.

Ship your next project
on rails.

Spec-driven. Drift-proof. Token-lean.

Get started Why Throughspec