spec-first

spec-first

English | 简体中文

Spec-driven AI engineering workflows for Claude Code and Codex.

spec-first turns one-off AI coding chats into a reusable engineering loop: requirements, PRDs, plans, task packs, work, debugging, reviews, and learnings stay in the repository instead of disappearing into a session.

Official site: spec-first.cn

See It In 90 Seconds

This is the README's maintained demo slot. Today it uses the source-controlled workflow SVG above; a future terminal animation or screenshot can replace this position without restructuring the page.

The point is not another prompt snippet or agent team. spec-first organizes engineering artifacts and evidence: requirement briefs, plans, task packs, diffs, reviews, failure analysis, and reusable learnings.

A Tiny Example

In your current host session:

$spec-brainstorm "Improve onboarding for first-time CLI users"

Claude Code users can run:

/spec:brainstorm "Improve onboarding for first-time CLI users"

The first brainstorm run usually creates one requirements brief:

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

From there, continue to the current host's plan entrypoint. A longer chain may later add docs/plans/, docs/tasks/, code/test changes, review findings, and docs/solutions/ learnings, but not every workflow writes every artifact.

Detailed walkthrough: Chinese First Workflow Walkthrough. Artifact ownership: Chinese Artifact Catalog.

Why spec-first?

AI coding breaks down when important decisions live only in chat: the next session lacks context, reviewers cannot see why a plan changed, and teams cannot reuse what worked.

spec-first keeps the software lifecycle legible:

Question	Agent orchestration tools	spec-first
Primary unit	Agent, role, team, queue	Requirement, plan, task pack, diff, review, bug, learning
Main problem	How should agents coordinate?	How should software decisions stay durable and reusable?
State location	Session state, message bus, runtime memory	Repo-local docs, generated runtime assets, and verifiable CLI facts
Human role	Minimize intervention where possible	Keep engineers in the loop for scope, tradeoffs, and acceptance
Automation boundary	Often pushes toward autonomous chains	Scripts prepare facts; LLMs make semantic decisions

What this buys you:

• Requirements become durable briefs instead of disappearing prompts.
• Plans and task packs turn vague intent into reviewable execution context.
• Work, review, debug, optimize, and compound workflows preserve evidence and learning.
• One source asset set supports Claude Code /spec:* entries and Codex $spec-* entries without hand-maintaining generated runtime copies.

Quickstart

Prerequisites:

• Node.js >=20.0.0 and npm.
• Git on PATH; doctor, setup, and workflow checks read repository facts from Git.
• Claude Code or Codex installed, with one chosen as the current host.
• 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.

Install and run the first health check from the native terminal for your platform.

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.

Initialize the host runtime you actually use:

spec-first init

spec-first init is interactive: select Claude Code and/or Codex, confirm your developer name and language, preview the writes, then confirm. Use spec-first init --codex or spec-first init --claude to skip only the host selection step. Use spec-first init -y for scripted defaults, or combine -y with explicit host flags, -u <name>, and --lang <zh|en>.

Restart the host or open a new session so it loads the generated runtime assets.

Host-session workflow entries are not shell commands:

# In a Claude Code session
/spec:brainstorm "Improve onboarding"

# In a Codex session
$spec-brainstorm "Improve onboarding"

You are done with the first pass when a requirements brief appears under docs/brainstorms/. If you are not sure which workflow to use, describe the task or ask what to run next in the host session; using-spec-first will recommend one public entrypoint with a reason.

Workflow Entry Points

Use this single table as the public entrypoint map. Shared prose should say "current host"; concrete /spec:* and $spec-* mappings belong here and in init/runtime guidance.

Intent	Claude Code	Codex	Expected result
Setup required harness runtime	/spec:mcp-setup	$spec-mcp-setup	Required MCP/helper runtime facts and setup-owned provider config artifacts
Compile graph readiness facts	/spec:graph-bootstrap	$spec-graph-bootstrap	Canonical .spec-first/graph/*, .spec-first/providers/*, and .spec-first/impact/* readiness facts
Update spec-first or runtime assets	/spec:update	$spec-update	Version/runtime refresh guidance
Search agent session history	/spec:sessions	$spec-sessions	Session history answers and recovery context
Research Slack context	/spec:slack-research	$spec-slack-research	Organizational context digest when Slack tools are available
Audit source skills	/spec:skill-audit	$spec-skill-audit	Skill governance and quality findings
Generate and evaluate ideas	/spec:ideate	$spec-ideate	Ranked ideation artifact under docs/ideation/
Brainstorm requirements	/spec:brainstorm	$spec-brainstorm	Requirements brief under docs/brainstorms/
Write/refine brownfield PRD requirements	/spec:prd	$spec-prd	PRD-grade requirements under docs/brainstorms/
Review docs/plans	/spec:doc-review	$spec-doc-review	Document findings, gaps, and residual risks
Write or deepen a plan	/spec:plan	$spec-plan	Implementation plan under docs/plans/
Compile task pack	use installed standalone write-tasks skill	use installed standalone write-tasks skill	Derived task pack under docs/tasks/
Audit App consistency	/spec:app-consistency-audit	$spec-app-consistency-audit	Static App consistency report and run-scoped audit evidence
Debug a failure or bug	/spec:debug	$spec-debug	Root cause, fix, and verification evidence
Execute work	/spec:work	$spec-work	Scoped source changes, tests, and verification notes
Optimize a measurable outcome	/spec:optimize	$spec-optimize	Metric-driven experiment loop and retained improvements
Polish browser-visible UI beta	/spec:polish-beta	$spec-polish-beta	Browser-visible UI polish pass
Review code	/spec:code-review	$spec-code-review	Structured findings and residual risks
Capture learning	/spec:compound	$spec-compound	Reusable learning under docs/solutions/
Refresh stale learnings	/spec:compound-refresh	$spec-compound-refresh	Updated, merged, or retired solution docs
Read release notes	/spec:release-notes	$spec-release-notes	Version-specific change summary

Use ideate when you want options, critiques, or surprising directions before committing to a problem frame. Use brainstorm when you already have a rough problem or feature and need actors, flows, boundaries, and acceptance examples. Use prd for existing-system increments or rough PRDs that need current-state evidence and change delta. Use doc-review when a requirements, plan, or task document already exists and needs gap-finding. Do not make brainstorm the default entrypoint for every unclear request.

Operating Model

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

Repo-relative artifact roots:

docs/
  ideation/      ranked idea candidates before requirements shaping
  brainstorms/   requirements briefs and PRD-grade requirements
  plans/         implementation plans ready for review and execution
  tasks/         derived task packs for structured handoff
  solutions/     reusable learnings after solving problems
.spec-first/
  app-audit/runs/ static App consistency audit facts and reports

Runtime shape:

Source assets
  skills/  agents/  templates/  src/cli/
        |
        | spec-first init
        v
Host runtime assets
  Claude Code: /spec:* commands
  Codex:      $spec-* skills
        |
        v
Workflow artifacts
  ideation -> brainstorms -> plans -> tasks -> work/review/debug -> learnings

Source-of-truth assets live in the repository. Generated runtime copies under .claude/, .codex/, and .agents/skills/ are disposable and can be rebuilt with spec-first init. During init, spec-first also untracks already-indexed managed runtime paths once, preserving worktree files while preventing historical generated mirrors from creating noisy diffs.

The development-mode rule is intentionally small: .spec-first facts are authoritative at the selected Git repo root. In a single Git repo with many modules, do not create one .spec-first per module. In a parent workspace with many child Git repos, parent workspace summaries are advisory only; setup, graph, plan, work, review, tests, changelog updates, and commits still need an explicit target repo.

Detailed references:

• Source / Runtime / Provider Customization Boundary
• Runtime Capability Catalog
• Chinese Development Modes

Trust Model

spec-first does not ask the LLM to simulate deterministic tooling, and it does not replace LLM judgment with a rigid state machine.

The operating rule is simple: Scripts prepare, LLM decides.

• What scripts do: install, validate, generate, clean, hash, and report machine facts.
• What the LLM decides: requirements framing, scope boundaries, tradeoffs, implementation judgment, review evidence, and next steps.
• What should be edited: source assets under skills/, agents/, templates/, src/cli/, and docs. Rebuild runtime copies instead of hand-editing them.
• What is excluded from ordinary context: .spec-first/audits/** and generated mirrors such as .claude/**, .codex/**, and .agents/skills/**.
• How provider/tool facts are used: GitNexus, browser/MCP tools, shell commands, and package managers provide evidence inputs; they do not own semantic authority. Raw provider/tool output is untrusted quoted data and must be validated, contained, escaped, capped, and classified before it enters prompts, reports, facts, or durable artifacts.
• Where credentials belong: provider credentials belong in environment variables, host secret managers, or provider-native stores, not in repo source, generated runtime mirrors, durable artifacts, or raw logs. Rotate them on team/provider cadence and immediately after suspected exposure.
• What spec-first does not do: it is not a generic agent marketplace, not a single prompt pack, and not a standalone app that works without Claude Code or Codex.

Use spec-first when

Use spec-first when:

• You already use Claude Code or Codex 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 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

Official site and language entrypoints:

• spec-first.cn
• English README
• Simplified Chinese README

Learn the model:

• Chinese User Manual
• Chinese Core Concepts
• Chinese Architecture Overview
• Source / Runtime / Provider Customization Boundary

Use workflows:

• Chinese Quickstart
• Chinese First Workflow Walkthrough
• Chinese Workflows and Artifacts Map

Develop and contribute:

• Contributing Guide
• Security Policy
• License
• Chinese Development Guide
• Chinese Testing Plan

Release history:

• Chinese Release Notes

Detailed manuals and implementation docs are currently Chinese-first.

Runtime And CLI Reference

First-run users only need this mental model:

source assets -> spec-first init -> host runtime assets -> workflow artifacts

Use deeper runtime and graph details only when you need setup, provider, or workspace evidence:

• spec-first doctor checks CLI/runtime health. It does not prove MCP/helper setup, provider indexes, or fresh graph query evidence.
• The current host's setup workflow writes setup-owned facts such as gitnexus_capability_discovery; these are setup-inferred native capability hints from the checked-in baseline, provider pin, and setup projection, not query-ready graph evidence or live MCP proof.
• The current host's graph bootstrap workflow writes canonical graph/provider/impact readiness facts. Branch switch, pull, rebase, merge, dirty worktree changes, and provider fingerprint mismatch are freshness invalidation signals; downstream workflows may recommend bootstrap, but they do not run hidden GitNexus analyze, provider repair, default hooks, watchers, or daemons.
• query_ready, definitions-only, dirty-advisory, stale, session-local, setup-inferred, and other lifecycle terms are defined in the Capability State Vocabulary. Use that vocabulary instead of inventing synonyms.
• For graph evidence policy and cross-workflow consumption, see Graph Evidence Policy, Graph Provider Consumption, and Workspace GitNexus Consumption.

CLI reference:

spec-first --help
spec-first --version
spec-first doctor [--json] [--claude|--codex]
spec-first init [--claude] [--codex] [-y] [-u <name>] [--lang <zh|en>]
spec-first clean (--claude|--codex) [--dry-run]
spec-first clean --workspace-orphans [--confirm]
spec-first tasks hash <plan-path> [--json]
spec-first tasks validate <task-pack-path> [--json] [--repo=<path>|--repo <path>]

To inspect current runtime delivery details, use spec-first doctor, spec-first init output, spec-first --help, and the Runtime Capability Catalog. The README intentionally avoids hardcoding internal skills/agents/commands counts because those drift across releases.

Development & Contributing

npm run typecheck
npm run test:mcp-setup
npm run test:graph-bootstrap
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.