Speckit

Speckit is a local-first Agile + TDD workflow compiler for agentic IDEs. It turns rough intent into specs, stories, TDD evidence, and native IDE instruction packs.

Speckit owns the workflow contract and generates adapters for the tools you already use. The public product vocabulary is Speckit-only: Agile shaping, TDD execution, task graph triage, and IDE adapter compilation.

Speckit also ships a portable skill catalog and super-agent router. IDE-specific agents read .speckit/agents/super-agent.md and .speckit/skills/catalog.md first, then load only the focused skill needed for the current phase.

The curated skill set is intentionally small: spec-shape, spec-research, spec-plan, spec-context, spec-graph, spec-session, spec-tdd, spec-test, spec-debug, spec-review, spec-docs, and spec-ship. These are adapted from proven orchestration patterns without importing a broad domain-specific catalog.

Quickstart

Recommended enterprise setup:

npx @trieungoctam/speckit@latest setup
npx @trieungoctam/speckit@latest doctor --deep
npx @trieungoctam/speckit@latest validate
npx @trieungoctam/speckit@latest score

One story end-to-end:

npx @trieungoctam/speckit@latest memory refresh
npx @trieungoctam/speckit@latest session start "Add checkout validation"
npx @trieungoctam/speckit@latest quick "Add checkout validation"
npx @trieungoctam/speckit@latest context .speckit/stories/<story>.md
npx @trieungoctam/speckit@latest sync
npx @trieungoctam/speckit@latest graph setup
npx @trieungoctam/speckit@latest sprint plan
npx @trieungoctam/speckit@latest graph triage --json
npx @trieungoctam/speckit@latest team status .speckit/stories/<story>.md
npx @trieungoctam/speckit@latest team audit .speckit/stories/<story>.md --json
npx @trieungoctam/speckit@latest team handoff .speckit/stories/<story>.md --from dev --to qa
npx @trieungoctam/speckit@latest score .speckit/stories/<story>.md
npx @trieungoctam/speckit@latest validate --json
npx @trieungoctam/speckit@latest permissions audit --path .env --json
npx @trieungoctam/speckit@latest ready .speckit/stories/<story>.md
npx @trieungoctam/speckit@latest session checkpoint --note "red complete"
npx @trieungoctam/speckit@latest review

Reset repo-local adapters before reinstalling:

rm -rf .claude CLAUDE.md .codex AGENTS.md .cursor .opencode opencode.json
npx @trieungoctam/speckit@latest setup

Interactive CLI output is colorized when the terminal supports ANSI colors. Use NO_COLOR=1 to disable colors, or SPECKIT_COLOR=1 to force colors for demos and snapshots.

Or install globally:

npm i -g @trieungoctam/speckit
speckit init --ide cursor
speckit doctor

Core Flow

intent
  -> start session
  -> super agent routing
  -> refresh project memory
  -> shape
  -> plan
  -> sprint plan
  -> context
  -> story with acceptance criteria
  -> sync / graph triage
  -> readiness gate
  -> red test evidence
  -> session checkpoint
  -> minimal implementation
  -> green test evidence
  -> session checkpoint
  -> refactor validation
  -> session compact
  -> review

For implementation stories, red-green-refactor evidence is mandatory. A story is not review-ready until the evidence file records test intent, red result, green result, and refactor validation.

Commands

| Command | Purpose | | --- | --- | | speckit setup | Open an interactive setup wizard for mode, IDE adapter, overwrite policy, and Beads Viewer setup. | | speckit init | Create .speckit/ core runtime, super-agent, skill catalog, and all IDE adapters. | | speckit init --enterprise | Add flow, tool policy, and prompt harness files on top of the shared runtime. | | speckit init --ide <name> | Generate shared Speckit runtime plus one adapter: claude-code, codex, antigravity, opencode, or cursor. | | speckit doctor | Report required tools, optional integrations, test commands, and adapter readiness. | | speckit doctor --deep | Verify core enterprise harness files and workflow contract checks. | | speckit validate | Validate flow order, core skills, super-agent routing, prompts, and installed adapter contracts. | | speckit start "<idea>" | Create a durable session handoff and current context. | | speckit memory refresh | Create durable project memory files for long-running agent work. | | speckit permissions audit | Check a path or command against the Speckit permission policy. | | speckit session start | Create or resume the active session state. | | speckit session checkpoint | Append a long-session checkpoint and artifact log entry. | | speckit session compact | Create an anchored summary for resume or handoff. | | speckit session resume | Mark a session as active and print its handoff path. | | speckit session status | Print active session state paths. | | speckit team status <story> | Show role-by-role team artifact readiness for a story. | | speckit team audit <story> | Run enterprise review-gate checks and return nonzero when blockers remain. | | speckit team handoff <story> | Create a durable role-to-role handoff artifact. | | speckit score | Score project workflow health across contract, team model, context/session, and graph sync. | | speckit score <story> | Score story health across team readiness, developer trace, TDD evidence, and review gate. | | speckit shape "<intent>" | Create a short spec contract. | | speckit context <story> | Build the current implementation context from a story. | | speckit quick "<intent>" | Create one story plus matching TDD evidence file. | | speckit plan "<intent>" | Create PRD, architecture, story, and evidence skeletons. | | speckit triage | Summarize synced story state without interactive graph commands. | | speckit next | Safely wraps bv --robot-next --format json. | | speckit sprint plan | Build a sprint plan and status file from synced stories. | | speckit sprint next | Pick the next selectable story from sprint state. | | speckit graph setup | Print Beads Viewer install commands, check br/bd/bv, and prepare .beads/beads.jsonl. | | speckit graph triage | Run Beads Viewer robot triage, or local JSON fallback if bv is missing. | | speckit graph plan | Run Beads Viewer robot plan, or local JSON fallback if bv is missing. | | speckit graph insights | Run Beads Viewer robot insights, or local JSON fallback if bv is missing. | | speckit sync | Export Speckit stories as .speckit/sync/beads-sync.jsonl and prepare .beads/beads.jsonl for Beads Viewer. | | speckit ready <story> | Validate story status, context, evidence, graph sync, and safety policy before implementation. | | speckit run <story> | Print the TDD execution handoff for a story. | | speckit review | Print the review checklist and current diff summary. | | speckit close <story> | Create a closure checklist linked to the story and sync step. |

Supported IDEs

Speckit generates native instruction/config files for:

• Claude Code
• Codex
• Antigravity
• OpenCode
• Cursor

See docs/adapters.md for exact output paths.

Guides

• docs/getting-started.md covers setup, adapter reset, verification, story execution, team audit, and close.
• docs/use-cases.md covers setup, migration, quick changes, full planning, long sessions, TDD, graph automation, review, CI, and troubleshooting.
• docs/team-workflow.md covers enterprise role ownership, status, audit, and handoff flow.
• docs/beads-viewer-setup.md covers Beads Viewer installation, bv verification, and robot-safe graph usage.
• docs/workflow-model.md describes the quick and full workflow lanes.
• docs/prompt-architecture.md describes the prompt contract used by the super-agent, skills, workflows, run prompt, and IDE adapters.
• docs/spec-quality-gates.md describes validation gates for release readiness.

Validation

npm run build
npm test