Docs/Get Started/Quickstart

Quickstart

From an empty folder to your first shipped feature in under 90 minutes. Here is the whole initiation cycle end-to-end.

New in 1.2.0spec-init my-app is the create-app shorthand - it implies init, so the examples below no longer need the init subcommand. Full notes on the Changelog.

Scaffold a project

Run the initializer with your project name. It creates the canonical directory tree with safe, lint-clean defaults in under five seconds. The command is identical on both channels:

# npm / npx (no install needed)
npx spec-init my-app

# Python, after: pipx install spec-init
spec-init my-app

cd my-app

Prefer a guided setup?Run npx spec-init with no arguments in a terminal for an interactive welcome - arrow-key selects for new-vs-existing, persona, and integrations, then it scaffolds. In a non-interactive shell (CI, pipes) it prints help instead, so scripts are unaffected.

Python channel?Prefer the Python channel? pipx install spec-init, then spec-init my-app. Both channels ship the same template payload, verified byte-for-byte on every release.

Already have a project?

Adopt Throughspec in an existing repo with reinit. It writes only the missing spec and memory files, keeps everything you already have, and never touches your source code. It also writes spec.config.js, which marks the project as Throughspec-managed so upgrade works from then on.

cd my-existing-project

# npm / npx
npx spec-init reinit          # keeps existing files
npx spec-init reinit --force  # replace spec files with fresh templates

# Python (pipx/pip): same commands without the npx prefix
spec-init reinit

Non-destructive by defaultreinit keeps any spec file that already exists (interactively it asks keep or replace). Pass --force to overwrite them. Already Throughspec-managed? Use upgrade instead - reinit will point you there.

Run the initiation cycle

Open Claude Code in the new directory and run these skills in order. Each gates the next - you cannot plan before the spec is frozen, and you cannot build before the plan is written.

/spec-requirements

At least three rounds of cross-questioning, then freezes claude/srs.md. Refuses to proceed while any of the five mandatory categories is empty.

/spec-design

Extracts a design system from your references, or proposes one from the SRS. Never fabricates brand colors when a reference is supplied.

/spec-plan

Produces an 8-10 step build plan, each ending in a standalone, testable, runnable deliverable.

/spec-feature

Enters the feature cycle: Requirements → Architecting → Product Specs → Tech Specs → Planning → Writing Code.

No skipping/spec-requirements refuses to proceed until target users, jobs-to-be-done, the success metric, hard constraints, and non-goals are all filled in. Overrides must be logged in design-decisions.md.

What you end up with

A scaffolded project whose memory layer keeps Claude oriented across every future prompt - without re-scanning the repo. CLAUDE.md plus claude/context.md stay under 8,000 tokens on a mature project (NFR-PERF-02).

my-app/
├─ CLAUDE.md
├─ claude/
│  ├─ srs.md
│  ├─ plan.md
│  ├─ context.md
│  ├─ features.md
│  ├─ learnings.md
│  └─ design-decisions.md
├─ design/
│  ├─ design.md
│  └─ preview/
├─ .claude/
│  ├─ skills/
│  └─ agents/
├─ CHANGELOG.md
├─ README.md
└─ spec.config.js       (ground-truth config)

What’s next

Workflows

The full initiation, feature, and maintenance cycles.

All 24 skills

Every slash command, what it does, and when to use it.

The memory layer

How the Kit keeps token cost flat as your project grows.

FAQ

Short answers to the most common questions.

‹ Previous

Setup & Channels

Next ›

Spec-Driven Development