spec-first

spec-first

English | 简体中文

An AI Coding Harness for Claude Code, Codex, Kiro, Qoder, and Cursor.

spec-first helps Claude Code, Codex, Kiro, Qoder, and Cursor become easier to trust in real projects: one-off AI coding conversations become repo-backed requirements, plans, scoped work, review, and reusable learning. Scripts enforce deterministic invariants and prepare facts; LLMs judge semantic adequacy above that floor; evidence stays in your repository. Kiro and Qoder remain opt-in previews. Cursor is more conservative: it is an opt-in generated_runtime_preview that currently proves generation of .cursor/skills/**, .cursor/spec-first/**, and .cursor/mcp.json evidence only. Local Cursor skill discovery/invocation has not been verified, and generated skills may not be loaded by Cursor.

Official site: spec-first.cn

See It In 90 Seconds

The first thing to evaluate is not an agent count or a prompt library. It is whether a workflow leaves something durable behind. A healthy first loop gives your existing Claude Code, Codex, Kiro, Qoder, or Cursor session a governed path: define the work, plan it, split it when useful, execute it, review it, and compound the learning.

The smallest success is intentionally concrete: after install and init, run one host workflow and inspect the Markdown artifact it writes under your repo, usually in docs/brainstorms/ or docs/plans/. Deeper governance is available later; the first test is whether the work becomes inspectable.

_{Simulated demo path: install → init → mcp-setup → ideate → brainstorm → prd → doc-review → plan → write-tasks → work → code-review → compound; mcp-setup is the readiness/setup step to run when helper or MCP facts are missing, debug is shown as a side loop for test failures or unclear root causes, and inspectable Markdown artifacts remain in the repository. Animation source: spec-first-cli-workflow-demo.svg.}

Quickstart

Install, initialize, and run your first workflow in about 5 minutes.

Prerequisites:

• Node.js >=20.0.0 and npm.
• Git on PATH; doctor, setup, and workflow checks read repository facts from Git.
• Claude Code, Codex, Kiro, Qoder, or Cursor installed, with one chosen as the current host. Cursor requires explicit --cursor opt-in and is currently generated-runtime preview only.
• A terminal opened at the root of the project repo where you want to enable spec-first. First-time users can try a throwaway/test repo before initializing a real project.

Step 1 — Install and check health

macOS / Linux:

npm install -g spec-first
spec-first doctor

Windows PowerShell 7+ or Windows PowerShell 5.1:

npm install -g spec-first
spec-first doctor

Windows cmd.exe:

npm install -g spec-first
spec-first doctor

On Win64, prefer native Windows Terminal with PowerShell 7+ or cmd.exe for installation and smoke checks. Windows PowerShell 5.1 is supported, but PowerShell 7+ has better UTF-8 behavior.

Expected: doctor reports no blocking issues. If issues appear, follow the printed suggestions before continuing.

Step 2 — Initialize the host runtime

spec-first init

Select your host (Claude Code, Codex, Cursor, Kiro, and/or Qoder), confirm your developer name and language, then confirm the writes. In a parent workspace with many child Git repos, init defaults to writing only the parent workspace runtime; use --repo <child> only when one child repo should be an independent agent root, and reserve --all-repos for explicit batch maintenance. Scripted init -y setup on fresh machines must pass -u <name> because there is no prompt to collect a developer name, for example spec-first init --codex -y -u <name> --lang <zh|en>. Scripted preview setup uses spec-first init --kiro -y -u <name> --lang <zh|en> for Kiro, spec-first init --qoder -y -u <name> --lang <zh|en> for Qoder, or spec-first init --cursor -y -u <name> --lang <zh|en> for Cursor generated-runtime preview. Cursor is not part of the init -y default host set.

Expected: init lists the generated runtime paths under .claude/, .codex/, .agents/skills/, .cursor/, .kiro/, or .qoder/. Generated copies can be rebuilt any time with spec-first init.

If the host reports missing helper or MCP readiness facts, run the unified spec-mcp-setup entry in your current host before continuing.

Cursor note: spec-first init --cursor generates the same spec-* workflow runtime under .cursor/skills/**, spec-first state under .cursor/spec-first/**, and project MCP setup targets .cursor/mcp.json by default. User-level ~/.cursor/mcp.json requires --user-scope / CURSOR_USER_SCOPE=1. Current release evidence records cursor_loader_validation_unavailable, so do not treat Cursor as full host support or an init -y default.

For all init options (flags, scripted mode, multi-repo), see the full Quickstart guide.

Step 3 — Restart the host

Restart the host or open a new session so it loads the generated runtime assets. Host-session workflow entries are not shell commands — they run inside the Claude Code, Codex, Kiro, Qoder, or Cursor session, not in your terminal.

Step 4 — Run your first workflow

Start with brainstorm — it is the most natural first entry and writes a visible artifact you can immediately inspect:

# In any supported host session
spec-brainstorm "describe your first task here"

Step 5 — Verify success

After the brainstorm completes, check your repo for a new file:

docs/brainstorms/YYYY-MM-DD-NNN-<topic>-requirements.md

That file is your first artifact. The work is now repo-local, inspectable, and ready to hand off to planning. From here, continue to the current host's plan entrypoint.

For subsequent tasks, use this quick route to pick the right entrypoint:

If your first task is...	Start with...
A rough idea, feature, or product change	spec-brainstorm
An existing PRD, requirement note, or brownfield change request	spec-prd
A bug, failing test, stack trace, or abnormal behavior	spec-debug
A settled plan, task pack, or scoped implementation request	spec-work
A document, plan, task pack, diff, or implementation that needs review	spec-doc-review or spec-code-review

Detailed manuals are Chinese-first; this README is the English quick path. Walkthrough: Chinese First Workflow Walkthrough. Artifact ownership: Chinese Artifact Catalog.

What You Get

A typical workflow chain produces these repo-local artifacts:

docs/
  ideation/      ranked ideas and exploration notes
  brainstorms/   requirements briefs and PRD-grade requirements
  plans/         implementation plans ready for review and execution
  tasks/         derived task packs for structured handoff
  reviews/       document and code review findings
  solutions/     reusable learnings after solving problems
.spec-first/
  workflows/     structured work closeout evidence (gitignored by default)

Not every workflow writes every artifact. The first run writes one file under docs/brainstorms/. Deeper chains add plans, tasks, code changes, review findings, and learnings over time — all inspectable, all in your repository.

Workflow Entry Points

The main engineering loop: Codebase → Spec → Plan → Tasks → Code → Review → Knowledge. Public workflow identifiers use the same spec-* form across supported hosts.

Task	Unified entry	Artifact
Requirements from a rough idea	spec-brainstorm	docs/brainstorms/
Requirements from an existing PRD	spec-prd	docs/brainstorms/
Implementation plan	spec-plan	docs/plans/
Split a plan into executable tasks	spec-write-tasks	docs/tasks/
Execute scoped work	spec-work	source changes + evidence
Review code	spec-code-review	structured findings
Review docs or plans	spec-doc-review	structured findings
Capture reusable learning	spec-compound	docs/solutions/

Support entrypoints (on demand): spec-mcp-setup for runtime environment plus required harness and MCP/helper readiness; plus the matching debug, optimize, ideate, compound-refresh, polish-beta, and write-skill entries for the current host.

→ Full entrypoint reference with routing rules

The Problem

AI can write code quickly. The expensive part is preserving the judgment around the code: why this scope, what evidence was checked, which review findings mattered, and what the next agent or teammate should inherit.

Without a repo-backed trail, that context disappears with the chat window. The next session starts cold, reviewers cannot see why a plan changed, and teams cannot reuse what worked. spec-first keeps that work as durable artifacts: requirements, PRDs, plans, task packs, work evidence, debugging notes, reviews, and learnings.

Why spec-first?

spec-first keeps the software lifecycle legible without pretending that prose alone is proof. It is not trying to replace Claude Code, Codex, Kiro, Qoder, or Cursor; it gives those hosts a project-local harness. Cursor native rules, Kiro native Specs, and Qoder native rules remain host-owned artifacts; spec-first only treats .cursor/rules/**, .kiro/specs/**, and .qoder/rules/** as advisory input when explicitly named.

Adoption question	Prompt pack / agent orchestration	spec-first
What do I get after the first run?	A better chat answer or agent transcript	A repo-local artifact such as a requirements brief or plan
Where do decisions and evidence live?	Session state, message bus, runtime memory	Repo-local docs, generated runtime assets, and verifiable CLI facts
What does the human review?	Often the final diff or agent output	Requirements, plans, task packs, diffs, review findings, bugs, and learnings
Who enforces mechanical boundaries?	Mostly model discipline or custom glue	Scripts enforce deterministic invariants and prepare facts; LLMs make semantic decisions above that floor
How do Claude Code, Codex, Cursor, Kiro, and Qoder stay aligned?	Separate setup and prompt maintenance	One source asset set regenerates supported host runtime surfaces

Current mechanisms you can inspect today:

• Requirements become durable briefs instead of disappearing prompts.
• Plans and task packs turn vague intent into reviewable execution context.
• Work closeout can point to structured verification evidence instead of a free-form "tests passed" claim.
• Task-pack handoffs now recommend splitting from source-plan structure and recommend document review for high-risk packs while keeping the engineer in the loop.
• Work, review, debug, optimize, and compound workflows preserve evidence and learning.
• Knowledge handoffs stay summary-first, and recalled docs/solutions/ learnings remain advisory until reconfirmed from source evidence.
• Team standards live as source docs under docs/contracts/team-standards.md and docs/standards/**; workflows pick the confirmed rules in scope rather than adding a new entrypoint.
• One source asset set supports unified spec-* workflow entries across Claude Code, Codex, Cursor, Kiro, and Qoder without hand-maintaining generated runtime copies.

These are current repo mechanisms, not measured adoption-outcome claims. Trust the artifacts, tests, and source/runtime boundaries before trusting any marketing sentence.

Operating Model

spec-first has two durable surfaces: repo-local workflow artifacts and generated host runtime assets.

Source assets (skills/, agents/, templates/, src/cli/) are regenerated by spec-first init into host runtime assets — producing repo-local workflow artifacts: ideation -> brainstorms -> plans -> tasks -> work/review/debug -> learnings.

Generated runtime copies under .claude/, .codex/, .agents/skills/, .cursor/skills/, .cursor/spec-first/, .kiro/skills/, .kiro/agents/, .kiro/spec-first/, .qoder/commands/spec-*.md, .qoder/commands/spec/ (retired legacy namespace), .qoder/skills/, .qoder/agents/, and .qoder/spec-first/ are disposable and can be rebuilt with spec-first init. Cursor project .cursor/mcp.json, spec-first managed .kiro/settings/, and Qoder local .qoder/settings.local.json are config outputs, not source; Cursor and Qoder clean preserve user-owned MCP entries. Cursor native .cursor/rules/**, Kiro native .kiro/specs/**, and Qoder native .qoder/rules/** are not spec-first source.

Detailed references:

• Source / Runtime / Provider Customization Boundary
• Runtime Capability Catalog
• Architecture Overview

Trust Model

Scripts enforce deterministic invariants; scripts prepare facts; the LLM decides semantic adequacy above that floor.

• What scripts do: enforce mechanically decidable invariants, install, validate, generate, report machine facts.
• What the LLM decides: requirements framing, scope boundaries, tradeoffs, implementation judgment, review evidence.
• What is excluded from ordinary context: .spec-first/audits/**, .spec-first/governance/**, generated mirrors such as .claude/**, .codex/**, .agents/skills/**, .cursor/skills/**, .cursor/spec-first/**, .kiro/skills/**, .kiro/agents/**, .kiro/spec-first/**, spec-first managed .kiro/settings/**, .qoder/commands/spec-*.md, retired .qoder/commands/spec/**, .qoder/skills/**, .qoder/agents/**, .qoder/spec-first/**, and host-local config such as .cursor/mcp.json and .qoder/settings.local.json.

→ Full trust model and verification contracts

Use spec-first when

Use spec-first when:

• You already use Claude Code, Codex, Kiro, Qoder, or Cursor and want project-local workflows instead of one-off prompts.
• You want AI coding work to leave durable requirements, plans, explicitly routed review summaries, and learnings.
• You want scripts to handle deterministic setup and enforce machine-checkable boundaries while keeping semantic judgment with the LLM.
• You want a lightweight workflow layer that can be regenerated from source assets.

It may not fit when you only need a single prompt snippet, a generic agent marketplace, a no-host standalone app, or a team process that does not want workflow artifacts written into the repo.

Documentation

Get started

• spec-first.cn — official site
• Chinese User Manual
• Chinese First Workflow Walkthrough
• Chinese Workflows and Artifacts Map

Understand the model

• Chinese Architecture Overview
• Source / Runtime / Provider Customization Boundary
• Verification Run Summary Contract
• Honest Closeout Contract
• Chinese Release Notes

Detailed manuals and implementation docs are currently Chinese-first.

Runtime And CLI Reference

First-run users: source assets -> spec-first init -> host runtime assets -> workflow artifacts.

Key commands:

spec-first doctor    # check health
spec-first init      # generate runtime
spec-first update    # upgrade CLI + refresh runtime
spec-first clean     # remove generated runtime

→ Full CLI reference with all flags and options

Development & Contributing

npm run typecheck
npm run test:mcp-setup
npm run test:unit
npm run test:smoke
npm run test:integration
npm run test:ai-dev:gate
npm run test:ai-dev:benchmarks
npm run test:release
npm run test:release:website
npm run build
npm test

npm run build runs npm pack --dry-run and verifies the package payload shape through npm.

When changing source assets, edit skills/, agents/, templates/, or src/cli/, then regenerate runtime copies with spec-first init and choose the target host in a fresh host session.

For contribution and support details, see CONTRIBUTING.md, SECURITY.md, LICENSE, and GitHub Issues.