运行模型

Spec-First 当前采用 npm CLI + project-local runtime assets 的运行模型。理解这个模型可以帮助你判断什么应该提交、什么由 init 重建、什么是事实源、什么是受管副本。

本页的核心判断是：source 真源在上游 package，runtime 副本在目标项目，control-plane facts 是本机状态，协作文档才是长期团队知识。 这四类资产不能混用。

Runtime Model

上游 npm 包是 source truth；init 只把当前宿主需要的 runtime 副本投影到项目里。

Source Packagespec-first npm 包skills / agents / templates / src/cli / contracts

→

Projectionspec-first init按 host flag 生成 host-specific runtime

→

Claude.claude/commands、skills、workflows、agents、state

Codex.codex/ + .agents/agents、state、spec-* workflow skills

Facts.spec-first/config、workspace、sessions、optional providers

Docsdocs/brainstorms、plans、tasks、solutions、ideation

整体结构

text

spec-first npm 包（source truth）
   │
   ├── skills/          # source skill definitions（含 skill-local references/agents、references/personas）
   ├── templates/       # host runtime templates
   └── src/cli/         # CLI 行为与 contracts
        │
        │ spec-first init
        ▼
你的项目（generated runtime）
   │
   ├── .claude/                        # Claude Code runtime
   │   ├── commands/spec-*.md          # command-backed workflow entries
   │   ├── skills/                     # standalone/internal skills
   │   ├── spec-first/workflows/       # workflow skills
   │   ├── agents/                     # agent profiles
   │   └── spec-first/state.json       # 受管资产状态
   │
   ├── .codex/                         # Codex runtime
   │   └── agents/                     # agent profiles
   │
   ├── .agents/skills/                 # Codex 的 spec-* workflow skills
   │
   ├── .cursor/                        # Cursor generated-runtime preview
   ├── .kiro/                          # Kiro opt-in preview runtime
   ├── .qoder/                         # Qoder opt-in preview runtime
   ├── .opencode/                      # OpenCode generated-runtime preview
   │
   └── .spec-first/                    # control-plane facts
       ├── config/                     # runtime-setup 写入
       ├── workspace/                  # parent workspace advisory
       ├── sessions/                   # opt-in session advisory
       └── providers/                  # optional provider evidence

五种资产类别

类别	位置	谁写	是否提交	事实源
Source 真源	spec-first npm 包内的 `skills/`（含 skill-local `references/agents`）、`templates/`、`src/cli/`	spec-first 维护者	上游仓库提交	✓ 事实源
Generated runtime	项目里的 `.claude/`、`.codex/`、`.agents/skills/`、`.cursor/`、`.kiro/`、`.qoder/`、`.opencode/`	`spec-first init`	不提交（init 自动加 `.gitignore`）	✗ 副本
Control-plane facts	项目里的 `.spec-first/config	workspace	sessions	providers/`
协作文档	项目里的 `docs/brainstorms/`、`docs/plans/`、`docs/tasks/`、`docs/solutions/`、`docs/ideation/`	各 workflow	通常提交	团队长期知识

判断哪个文件该改

想改变什么	应该改哪里	不应该改哪里
workflow 行为、skill 文案、agent profile	上游 `skills/`（含 skill-local `references/agents`）、`templates/`、`src/cli/`	目标项目里的 generated runtime copy
当前项目的 AI 工作规则	`AGENTS.md`、`CLAUDE.md`、`docs/contracts/**`、README	`.agents/skills/` 或 `.claude/skills/`
一次需求、计划或经验沉淀	`docs/brainstorms/`、`docs/plans/`、`docs/tasks/`、`docs/solutions/`	`.spec-first/config/`
本机 provider readiness	重新运行 setup 或显式 provider pack 命令	手写 `.spec-first/providers/**`

CLI 命令面

spec-first CLI 只承担确定性操作；workflow 入口在宿主会话内运行。

命令	用途
`spec-first --help`	查看 CLI 命令面
`spec-first --version`	查看当前版本
`spec-first doctor [--claude\|--codex\|--cursor\|--kiro\|--qoder\|--opencode] [--json] [--verbose]`	检查环境与 managed runtime
`spec-first init [--claude] [--codex] [--cursor] [--kiro] [--qoder] [--opencode] [-y] [-u <name>] [--lang zh\|en]`	安装宿主 runtime assets
`spec-first update`	升级全局 CLI 并尝试刷新当前项目 runtime
`spec-first clean (--claude\|--codex\|--cursor\|--kiro\|--qoder\|--opencode) [--dry-run]`	清理 spec-first managed assets
`spec-first repair-worktree ...`	修复 spec-first 管理的 worktree 辅助状态
`spec-first tasks hash <plan-path> [--json]`	计算计划文件 hash
`spec-first tasks validate <task-pack-path> [--json] [--repo <path>]`	校验 task pack
`spec-first session <subcommand>`	维护可选多 actor worktree advisory session 记录

init / update / clean / repair-worktree / tasks validate / session 都是 deterministic 工具；doctor 既检测环境也读 manifest 与 state。Workflow 入口（当前产品面为 spec-*）由宿主提供，不是 CLI 子命令。

受管资产状态

每次 init 把宿主 runtime 写到项目本地，并把对应 manifest 与 schema 化的状态存入：

.claude/spec-first/state.json
.codex/spec-first/state.json
.cursor/spec-first/state.json
.kiro/spec-first/state.json
.qoder/spec-first/state.json
.opencode/spec-first/state.json

state schema 显式跟踪 commands / skills / workflowSkills / agents / agentSupportFiles。spec-first doctor 比对当前 manifest 与 state，定位漂移；漂移修复方式是重新 init，而不是手改 runtime copy。

升级策略：hard-cut

当前版本采用硬切换：

检测到 legacy state → 重新运行 spec-first init
init 先做 managed hard reset，再按当前版本全量重建
clean 不承担 legacy 迁移

不要尝试手动合并旧版与新版 runtime；让 init 全量重建。

Developer profile

spec-first init 会写入项目级 developer profile：

.claude/spec-first/.developer
.codex/spec-first/.developer

格式：

name=<your-name>
lang=<zh|en>
initialized_at=<ISO timestamp>
version=<spec-first cli version>

未传 -u / --user 时，回退顺序：

全局 ~/.spec-first/.developer
git config user.name

name 主要用于 CHANGELOG.md 等需要署名的写入；lang 决定 spec-first 自身生成内容的默认语言。

多宿主一致性

同一个仓库可以同时支持 Claude Code 和 Codex：

bash

spec-first init

在交互中同时选择多个宿主即可（Claude Code、Codex，以及 Cursor / Kiro / Qoder / OpenCode 的 opt-in preview）。各宿主共用 source skills，但 generated runtime 写到不同位置（.claude/、.codex/ / .agents/、.cursor/、.kiro/、.qoder/、.opencode/）。文件互不干扰。

阅读下一步

产物目录与 Git 边界：每类产物由谁生成、如何提交
.gitignore 参考：init 自动维护 managed block 的内容
三种开发模式：单仓单项目 / 单仓多模块 / 多仓工作区下的 .spec-first 边界
安装指南：实际跑通 doctor + init

运行模型 ​

整体结构 ​

五种资产类别 ​

判断哪个文件该改 ​

CLI 命令面 ​

受管资产状态 ​

升级策略：hard-cut ​

Developer profile ​

多宿主一致性 ​

阅读下一步 ​