<div align="center">

# spec-first

[![npm version](https://img.shields.io/npm/v/spec-first.svg)](https://www.npmjs.com/package/spec-first)
[![license](https://img.shields.io/npm/l/spec-first.svg)](https://github.com/sunrain520/spec-first/blob/main/LICENSE)
[![node](https://img.shields.io/node/v/spec-first.svg)](https://github.com/sunrain520/spec-first/blob/main/package.json)
[![CI](https://github.com/sunrain520/spec-first/actions/workflows/npm-install-matrix.yml/badge.svg)](https://github.com/sunrain520/spec-first/actions/workflows/npm-install-matrix.yml)
[![docs](https://img.shields.io/badge/docs-spec--first.cn-0b7285.svg)](http://spec-first.cn/)

[English](https://github.com/sunrain520/spec-first/blob/main/README.md) | [简体中文](https://github.com/sunrain520/spec-first/blob/main/README.zh-CN.md)

**面向 Claude Code 与 Codex 的 spec-driven AI engineering workflows。**

`spec-first` 把一次性的 AI coding 对话变成可复用的工程闭环：requirements、PRD、plans、task packs、work、debug、reviews 和 learnings 留在仓库里，而不是消失在一次会话中。

官网：[spec-first.cn](http://spec-first.cn/)

</div>

---

## 90 秒看懂

![spec-first workflow flow](https://raw.githubusercontent.com/sunrain520/spec-first/main/docs/assets/readme/spec-first-flow.svg)

这是 README 维护的演示素材位。当前复用 source-controlled workflow SVG；未来如果要替换为终端动画或截图，可以直接替换这个位置，不需要重排页面结构。

重点不是再提供一组 prompt 片段或 agent team，而是编排工程产物与证据：requirements brief、plan、task pack、diff、review、failure analysis 和可复用 learning。

## 一个小例子

在当前宿主会话中输入：

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

Claude Code 用户可改用：

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

第一次 brainstorm 通常只生成一个 requirements brief：

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

随后进入当前宿主的 plan 入口继续推进。更长的链路后续可能增加 `docs/plans/`、`docs/tasks/`、代码/测试改动、review findings 和 `docs/solutions/` learnings，但不是每个 workflow 都写入所有 artifact。

完整走查见 [首次工作流走查](https://github.com/sunrain520/spec-first/blob/main/docs/05-%E7%94%A8%E6%88%B7%E6%89%8B%E5%86%8C/09-%E9%A6%96%E6%AC%A1%E5%B7%A5%E4%BD%9C%E6%B5%81%E8%B5%B0%E6%9F%A5.md)。产物归属见 [产物目录](https://github.com/sunrain520/spec-first/blob/main/docs/05-%E7%94%A8%E6%88%B7%E6%89%8B%E5%86%8C/10-%E4%BA%A7%E7%89%A9%E7%9B%AE%E5%BD%95.md)。

## 为什么使用 spec-first？

AI coding 最大的问题通常不是 agent 不会写代码，而是关键判断只停留在聊天窗口里：下一次会话缺上下文，reviewer 看不到计划为什么变化，团队也很难复用一次成功经验。

`spec-first` 让软件生命周期本身保持可读：

| 问题 | Agent 编排工具 | spec-first |
|---|---|---|
| 核心对象 | Agent、role、team、queue | Requirement、plan、task pack、diff、review、bug、learning |
| 主线问题 | Agent 之间怎么协作？ | 软件决策怎么被记下来、被验证、被复用？ |
| 状态位置 | Session state、消息总线、runtime memory | 项目内文档、generated runtime assets、可验证 CLI facts |
| 人的角色 | 尽量减少介入 | 工程师对 scope、tradeoff、验收保持在环 |
| 自动化边界 | 倾向更长的自动接力 | 脚本准备事实，LLM 做语义判断 |

它带来的结果是：

- requirements 变成持久 brief，而不是会话里消失的 prompt。
- plans 和 task packs 把模糊意图变成可评审、可执行的上下文。
- work、review、debug、optimize 和 compound workflows 会沉淀证据与经验。
- 一套 source assets 同时支持 Claude Code 的 `/spec:*` 入口和 Codex 的 `$spec-*` 入口，不需要手工维护生成副本。

## 快速开始

前置条件：

- Node.js `>=20.0.0` 和 npm。
- Git 已安装并在 `PATH` 中；`doctor`、setup 和 workflow 检查会读取 Git 仓库事实。
- 已安装 Claude Code 或 Codex，并选择其中一个作为当前宿主。
- terminal 位于你想启用 `spec-first` 的项目仓库根目录。首次试用者可以先在 throwaway/test repo 中体验，再初始化真实项目。

请在当前平台的原生终端中安装并运行第一次健康检查。

macOS / Linux：

```bash
npm install -g spec-first
spec-first doctor
```

Windows PowerShell 7+ 或 Windows PowerShell 5.1：

```powershell
npm install -g spec-first
spec-first doctor
```

Windows cmd.exe：

```bat
npm install -g spec-first
spec-first doctor
```

在 Win64 上，推荐使用 Windows Terminal + PowerShell 7+ 或原生 `cmd.exe` 做安装和 smoke check。Windows PowerShell 5.1 也支持，但 PowerShell 7+ 的 UTF-8 行为更稳定。

初始化实际使用的宿主 runtime：

```bash
spec-first init
```

`spec-first init` 是交互式流程：多选 Claude Code 和/或 Codex、确认开发者姓名与语言、预览写入内容，然后显式确认。可用 `spec-first init --codex` 或 `spec-first init --claude` 只跳过宿主选择步骤。脚本中可用 `spec-first init -y` 初始化默认宿主集合，或把 `-y` 与显式宿主 flag、`-u <name>`、`--lang <zh|en>` 组合使用。

重启宿主或新开会话，让宿主加载刚生成的 runtime assets。

宿主内 workflow 入口不是 shell 命令：

```text
# 在 Claude Code 会话中
/spec:brainstorm "改进 onboarding"

# 在 Codex 会话中
$spec-brainstorm "改进 onboarding"
```

当 `docs/brainstorms/` 下出现 requirements brief，第一次接入就完成了。如果不确定该用哪个 workflow，可以在宿主会话中直接描述任务或询问下一步；`using-spec-first` 会推荐一个公开入口并说明原因。

## Workflow Entry Points

这张表是公开入口的唯一映射表。共享 prose 优先说“当前宿主”；具体 `/spec:*` 与 `$spec-*` 映射集中放在这里和 init/runtime 指引中。

| Intent | Claude Code | Codex | Expected result |
|---|---|---|---|
| Setup required harness runtime | `/spec:mcp-setup` | `$spec-mcp-setup` | 必备 MCP/helper runtime facts 和 setup-owned provider config artifacts |
| Compile graph readiness facts | `/spec:graph-bootstrap` | `$spec-graph-bootstrap` | Canonical `.spec-first/graph/*`、`.spec-first/providers/*` 和 `.spec-first/impact/*` readiness facts |
| Update spec-first or runtime assets | `/spec:update` | `$spec-update` | 版本/runtime 刷新指引 |
| Search agent session history | `/spec:sessions` | `$spec-sessions` | 会话历史答案和恢复上下文 |
| Research Slack context | `/spec:slack-research` | `$spec-slack-research` | Slack 工具可用时生成组织上下文 digest |
| Audit source skills | `/spec:skill-audit` | `$spec-skill-audit` | Skill 治理与质量 findings |
| Generate and evaluate ideas | `/spec:ideate` | `$spec-ideate` | `docs/ideation/` 下的 ranked ideation artifact |
| Brainstorm requirements | `/spec:brainstorm` | `$spec-brainstorm` | `docs/brainstorms/` 下的 requirements brief |
| Write/refine brownfield PRD requirements | `/spec:prd` | `$spec-prd` | `docs/brainstorms/` 下的 PRD-grade requirements |
| Review docs/plans | `/spec:doc-review` | `$spec-doc-review` | Document findings、gaps 和 residual risks |
| Write or deepen a plan | `/spec:plan` | `$spec-plan` | `docs/plans/` 下的 implementation plan |
| Compile task pack | use installed standalone `write-tasks` skill | use installed standalone `write-tasks` skill | `docs/tasks/` 下的 derived task pack |
| Audit App consistency | `/spec:app-consistency-audit` | `$spec-app-consistency-audit` | Static App consistency report 和 run-scoped audit evidence |
| Debug a failure or bug | `/spec:debug` | `$spec-debug` | Root cause、fix 和 verification evidence |
| Execute work | `/spec:work` | `$spec-work` | Scoped source changes、tests 和 verification notes |
| Optimize a measurable outcome | `/spec:optimize` | `$spec-optimize` | Metric-driven experiment loop 和 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 和 residual risks |
| Capture learning | `/spec:compound` | `$spec-compound` | `docs/solutions/` 下的 reusable learning |
| Refresh stale learnings | `/spec:compound-refresh` | `$spec-compound-refresh` | 更新、合并或退役 solution docs |
| Read release notes | `/spec:release-notes` | `$spec-release-notes` | 指定版本变更摘要 |

想要选项、批判或意外方向，还没确定问题框架时，用 `ideate`。已经有粗略产品问题或功能想法，需要 actors、flows、边界和 acceptance examples 时，用 `brainstorm`。已有系统增量或粗糙 PRD 需要 current-state evidence 和 change delta 时，用 `prd`。已有 requirements、plan 或 task 文档，需要找缺口时，用 `doc-review`。不要把 `brainstorm` 当作所有不清楚请求的默认入口。

## 产物与工作方式

`spec-first` 有两类 durable surface：仓库内 workflow artifacts 和 generated host runtime assets。

Repo-relative artifact roots：

```text
docs/
  ideation/      requirements shaping 前的 ranked idea candidates
  brainstorms/   requirements briefs 与 PRD-grade requirements
  plans/         可评审、可执行的 implementation plans
  tasks/         结构化 handoff 用 derived task packs
  solutions/     解决问题后沉淀的 reusable learnings
.spec-first/
  app-audit/runs/ static App consistency audit facts and reports
```

Runtime shape：

```text
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 位于仓库中。`.claude/`、`.codex/` 和 `.agents/skills/` 下的 generated runtime copies 是可丢弃镜像，可通过 `spec-first init` 重建。init 期间，spec-first 也会一次性 untrack 已被 Git 索引的 managed runtime paths，保留 worktree 文件但避免历史 generated mirrors 制造 noisy diffs。

开发模式规则保持很小：`.spec-first` facts 以所选 Git repo root 为权威。单个 Git 仓库包含多个模块时，不要在每个模块下创建独立 `.spec-first`。父目录包含多个 child Git repos 时，parent workspace summaries 仅作 advisory；setup、graph、plan、work、review、tests、changelog updates 和 commits 仍需明确 target repo。

详细参考：

- [Source / Runtime / Provider Customization Boundary](https://github.com/sunrain520/spec-first/blob/main/docs/contracts/source-runtime-customization-boundary.md)
- [Runtime Capability Catalog](https://github.com/sunrain520/spec-first/blob/main/docs/catalog/runtime-capabilities.md)
- [三种开发模式](https://github.com/sunrain520/spec-first/blob/main/docs/05-%E7%94%A8%E6%88%B7%E6%89%8B%E5%86%8C/08-%E4%B8%89%E7%A7%8D%E5%BC%80%E5%8F%91%E6%A8%A1%E5%BC%8F.md)

## Trust Model

`spec-first` 不要求 LLM 假装执行确定性工具，也不把 LLM 判断替换成僵硬状态机。

核心规则很简单：Scripts prepare, LLM decides.

- **脚本负责什么：** install、validate、generate、clean、hash 和 report machine facts。
- **LLM 负责什么：** requirements framing、scope boundaries、tradeoffs、implementation judgment、review evidence 和 next steps。
- **应该修改哪里：** 修改 `skills/`、`agents/`、`templates/`、`src/cli/` 和 docs 下的 source assets；不要手改 generated runtime copies。
- **普通上下文排除什么：** `.spec-first/audits/**` 和 `.claude/**`、`.codex/**`、`.agents/skills/**` 等 generated mirrors。
- **provider/tool facts 怎么用：** GitNexus、browser/MCP tools、shell commands 和 package managers 只提供 evidence inputs，不拥有 semantic authority。Raw provider/tool output 是 untrusted quoted data；进入 prompts、reports、facts 或 durable artifacts 前必须经过 validation、containment、escaping、excerpt cap 和 provenance/readiness classification。
- **credentials 放在哪里：** provider credentials 应来自环境变量、host secret manager 或 provider-native store，不写入 repo source、generated runtime mirrors、durable artifacts 或 raw logs。按团队/provider cadence 轮换，并在疑似泄露后立即轮换。
- **spec-first 不是什么：** 不是通用 agent marketplace，不是单个 prompt pack，也不是脱离 Claude Code 或 Codex 独立运行的 standalone app。

## 适合使用 spec-first 的情况

适合使用 `spec-first`：

- 你已经使用 Claude Code 或 Codex，希望用项目内 workflow 替代一次性 prompt。
- 你希望 AI coding work 留下 durable requirements、plans、显式路由的 review summaries 和 learnings。
- 你希望脚本处理确定性 setup，同时让语义判断继续由 LLM 完成。
- 你希望 workflow layer 足够轻，并能从 source assets 重新生成。

如果你只需要单次 prompt 片段、通用 agent marketplace、不依赖宿主的独立应用，或团队流程不希望 workflow artifacts 写入 repo，`spec-first` 可能不是最合适的形态。

## 相关文档

官网与语言入口：

- [spec-first.cn](http://spec-first.cn/)
- [English README](https://github.com/sunrain520/spec-first/blob/main/README.md)
- [简体中文 README](https://github.com/sunrain520/spec-first/blob/main/README.zh-CN.md)

理解模型：

- [用户手册](https://github.com/sunrain520/spec-first/blob/main/docs/05-%E7%94%A8%E6%88%B7%E6%89%8B%E5%86%8C/README.md)
- [核心概念](https://github.com/sunrain520/spec-first/blob/main/docs/05-%E7%94%A8%E6%88%B7%E6%89%8B%E5%86%8C/02-%E6%A0%B8%E5%BF%83%E6%A6%82%E5%BF%B5.md)
- [整体架构](https://github.com/sunrain520/spec-first/blob/main/docs/02-%E6%9E%B6%E6%9E%84%E8%AE%BE%E8%AE%A1/01-%E6%95%B4%E4%BD%93%E6%9E%B6%E6%9E%84.md)
- [Source / Runtime / Provider Customization Boundary](https://github.com/sunrain520/spec-first/blob/main/docs/contracts/source-runtime-customization-boundary.md)

使用 workflows：

- [快速开始](https://github.com/sunrain520/spec-first/blob/main/docs/05-%E7%94%A8%E6%88%B7%E6%89%8B%E5%86%8C/01-%E5%BF%AB%E9%80%9F%E5%BC%80%E5%A7%8B.md)
- [首次工作流走查](https://github.com/sunrain520/spec-first/blob/main/docs/05-%E7%94%A8%E6%88%B7%E6%89%8B%E5%86%8C/09-%E9%A6%96%E6%AC%A1%E5%B7%A5%E4%BD%9C%E6%B5%81%E8%B5%B0%E6%9F%A5.md)
- [Workflows 与产物地图](https://github.com/sunrain520/spec-first/blob/main/docs/05-%E7%94%A8%E6%88%B7%E6%89%8B%E5%86%8C/04-workflows-artifacts-map.md)

开发与贡献：

- [Contributing Guide](https://github.com/sunrain520/spec-first/blob/main/CONTRIBUTING.md)
- [Security Policy](https://github.com/sunrain520/spec-first/blob/main/SECURITY.md)
- [License](https://github.com/sunrain520/spec-first/blob/main/LICENSE)
- [开发规范](https://github.com/sunrain520/spec-first/blob/main/docs/03-%E5%AE%9E%E6%96%BD%E6%96%B9%E6%A1%88/06-%E5%BC%80%E5%8F%91%E8%A7%84%E8%8C%83.md)
- [测试方案](https://github.com/sunrain520/spec-first/blob/main/docs/03-%E5%AE%9E%E6%96%BD%E6%96%B9%E6%A1%88/04-%E6%B5%8B%E8%AF%95%E6%96%B9%E6%A1%88.md)

版本历史：

- [版本更新](https://github.com/sunrain520/spec-first/blob/main/docs/08-%E7%89%88%E6%9C%AC%E6%9B%B4%E6%96%B0/README.md)

详细手册和实施文档均以中文为主。

## Runtime 与 CLI Reference

首次接入只需要记住这条因果链：

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

只有在需要 setup、provider 或 workspace evidence 时，再读更深的 runtime / graph 细节：

- `spec-first doctor` 检查 CLI/runtime health，不证明 MCP/helper setup、provider indexes 或 fresh graph query evidence。
- 当前宿主的 setup workflow 会写入 `gitnexus_capability_discovery` 等 setup-owned facts；这些是来自 checked-in baseline、provider pin 和 setup projection 的 setup-inferred native capability hints，不是 query-ready graph evidence，也不是 live MCP proof。
- 当前宿主的 graph bootstrap workflow 写入 canonical graph/provider/impact readiness facts。切换分支、pull、rebase、merge、dirty worktree changes 和 provider fingerprint mismatch 都是 freshness invalidation signals；下游 workflow 可建议 bootstrap，但不会隐藏运行 GitNexus analyze、provider repair、默认 hooks、watchers 或 daemons。
- `query_ready`、`definitions-only`、`dirty-advisory`、`stale`、`session-local`、`setup-inferred` 等 lifecycle terms 定义在 [Capability State Vocabulary](https://github.com/sunrain520/spec-first/blob/main/docs/contracts/gitnexus-capability-catalog.md)。请使用该词典，不要引入同义词。
- Graph evidence policy 与跨 workflow 消费边界见 [Graph Evidence Policy](https://github.com/sunrain520/spec-first/blob/main/docs/contracts/graph-evidence-policy.md)、[Graph Provider Consumption](https://github.com/sunrain520/spec-first/blob/main/docs/contracts/graph-provider-consumption.md) 和 [Workspace GitNexus Consumption](https://github.com/sunrain520/spec-first/blob/main/docs/contracts/workspace-gitnexus-consumption.md)。

CLI reference：

```bash
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>]
```

需要查看当前 runtime delivery 细节时，使用 `spec-first doctor`、`spec-first init` 输出、`spec-first --help` 和 [Runtime Capability Catalog](https://github.com/sunrain520/spec-first/blob/main/docs/catalog/runtime-capabilities.md)。README 有意不硬编码内部 skills/agents/commands 数量，因为这些计数会随版本漂移。

## 开发与贡献

```bash
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` 会执行 `npm pack --dry-run` 并通过 npm 验证 package payload 形态。

修改 source assets 时，编辑 `skills/`、`agents/`、`templates/` 或 `src/cli/`，再通过 `spec-first init` 重新生成 runtime copies，并在 fresh host session 中选择目标宿主。

贡献与支持见 [CONTRIBUTING.md](https://github.com/sunrain520/spec-first/blob/main/CONTRIBUTING.md)、[SECURITY.md](https://github.com/sunrain520/spec-first/blob/main/SECURITY.md)、[LICENSE](https://github.com/sunrain520/spec-first/blob/main/LICENSE) 和 [GitHub Issues](https://github.com/sunrain520/spec-first/issues)。
