运行模型

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

整体结构

spec-first npm 包（source truth）
   │
   ├── skills/          # source skill definitions
   ├── agents/          # source agent profiles
   ├── templates/       # host runtime templates
   └── src/cli/         # CLI 行为与 contracts
        │
        │ spec-first init --claude / --codex
        ▼
你的项目（generated runtime）
   │
   ├── .claude/                        # Claude Code runtime
   │   ├── commands/spec/              # /spec:* command 模板
   │   ├── 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-* skills
   │
   └── .spec-first/                    # control-plane facts
       ├── config/                     # mcp-setup 写入
       ├── providers/                  # graph providers
       ├── graph/                      # canonical graph readiness
       ├── impact/                     # capability envelope
       └── standards/                  # project standards baseline

五种资产类别

类别	位置	谁写	是否提交	事实源
Source 真源	spec-first npm 包内的 skills/、agents/、templates/、src/cli/	spec-first 维护者	上游仓库提交	✓ 事实源
Generated runtime	项目里的 .claude/、.codex/、.agents/skills/	spec-first init	不提交（init 自动加 .gitignore）	✗ 副本
Control-plane facts	项目里的 `.spec-first/config	graph	providers	impact/`
Project standards	项目里的 .spec-first/standards/	spec-standards	部分（confirmed 候选可提交）	项目级规范
协作文档	项目里的 docs/brainstorms/、docs/plans/、docs/tasks/、docs/solutions/、docs/ideation/	各 workflow	通常提交	团队长期知识

CLI 命令面

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

命令	用途
spec-first --help	查看 CLI 命令面
spec-first --version	查看当前版本
spec-first doctor [--claude|--codex] [--json]	检查环境与 managed runtime
spec-first init (--claude|--codex) [-u <name>] [--lang zh|en] [--dry-run]	安装宿主 runtime assets
spec-first clean (--claude|--codex) [--dry-run]	清理 spec-first managed assets
spec-first tasks hash <plan-path> [--json]	计算计划文件 hash
spec-first tasks validate <task-pack-path> [--json] [--repo <path>]	校验 task pack

init / clean / tasks validate 是 deterministic 工具；doctor 既检测环境也读 manifest 与 state。Workflow 入口（/spec:*、$spec-*）由宿主提供，不是 CLI 子命令。

受管资产状态

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

.claude/spec-first/state.json
.codex/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 时，回退顺序：

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

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

双宿主一致性

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

spec-first init --claude -u <name> --lang zh
spec-first init --codex -u <name> --lang zh

两次 init 共用 source skills，但 generated runtime 写到不同位置（.claude/ 与 .codex/ / .agents/）。文件互不干扰。

阅读下一步

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