spec-init

disable-model-invocation	true
name	spec-init
description	当项目首次接入 Spec 驱动开发 / R&K Flow，需要创建 AGENTS.md、.agents/rules/、 .agents/skills/、spec/ 目录、记忆系统和 Obsidian Vault 时使用。 典型信号：用户说"初始化项目"/"搭建 Spec 环境"/"创建开发环境"，或项目根目录缺少 AGENTS.md / spec/。 不要用于已有项目的单个 Spec 开发、功能更新或少量规范修改。

Spec Init

核心原则

1. 幂等性：所有操作先检查后创建，已存在则跳过，不覆盖已有内容
2. 完整性：一次搭建完整的项目骨架，用户无需手动补充
3. 一次性：整个项目生命周期只需执行一次，后续开发任务使用 spec-start

工作流程

步骤 1：检查项目状态

# 检查项目是否已初始化
ls AGENTS.md
ls spec/
ls .agents/

# 检查 Git 仓库状态
git rev-parse --is-inside-work-tree
git branch --show-current
git remote -v

如果 AGENTS.md 和 spec/ 都已存在，告知用户无需重复初始化，建议直接使用 spec-start 启动开发任务。 如果部分存在，只补充缺失部分。

Git 检查规则：

• 如果已经是 Git 仓库，记录当前分支和远程仓库；不要重新 git init
• 如果不是 Git 仓库，询问用户是否初始化 Git 仓库
• 用户确认后执行：

git init
git branch -M main

• 如果没有远程仓库，提示用户稍后添加 origin，但不阻塞 Spec 基础设施初始化
• 如果当前分支不是 main，只记录现状，不强制切换；后续 spec-start 会按 GitHub Flow 创建工作分支

步骤 2：询问项目基本信息

使用当前运行环境的确认/提问方式收集项目信息（用于生成 AGENTS.md）：

请提供项目基本信息：
1. 项目名称
2. 项目简介（一句话描述）
3. 主要技术栈（如 Python/FastAPI、TypeScript/React 等）
4. 项目类型（如 Web 应用、CLI 工具、库等）
5. 长期项目偏好（可选，如产品体验、前端风格、协作习惯）

收集完基本信息后，必须询问当前运行环境（决定只生成哪一套运行时适配文件）：

请确认你当前使用的 Agent 运行环境（用于生成对应的运行时适配，只创建当前环境所需文件）：
1. OMP（Oh My Pi）【推荐】 → 生成 .omp/agents/ 与 .omp/hooks/
2. Claude Code            → 生成 .claude/agents/ 与 .claude/settings.json
3. Codex                  → 生成 .codex/agents/ 与 .codex/ hook 配置

若用户没有明确偏好，推荐 OMP：R&K Flow 优先面向 OMP 设计并端到端验证，是契合度最高、
唯一支持 session.compacting 自动重注入落盘账本的运行时。

记录用户选择为 <runtime>（omp / claude / codex）。后续步骤 4.3、4.4 只为 <runtime> 生成运行时适配文件，不创建其它环境的目录和文件。中立产物（.agents/roles/、.agents/hooks/team-context-hook-contract.md）始终创建，与运行环境无关。

[!important] 只建当前环境 不要默认三套全建。.agents/roles/（中立角色定义）和 .agents/hooks/team-context-hook-contract.md（中立协议）是权威源，必须创建；.claude / .codex / .omp 三套运行时适配只生成 <runtime> 对应的那一套。

步骤 3：创建 AGENTS.md

在项目根目录创建 AGENTS.md，这是项目的身份文件和路由入口。保持精简：只写项目身份、最高优先级工作方式、详细目录入口；具体规则和项目偏好写入 .agents/rules/。

# {项目名称}

{项目简介}

## 项目身份

- **技术栈**: {主要技术栈}
- **类型**: {项目类型}

## 工作方式

本项目采用 R&K Flow / Spec 驱动式开发。新功能、更新、修复和收尾均通过 `.agents/skills/` 中的对应 Skill 执行。

## 详细规则入口

@import .agents/rules/
@import .agents/skills/

## 目录路由

- `.agents/rules/`：长期项目规则、项目偏好、前端风格、测试/安全/文档约束
- `.agents/skills/`：R&K Flow 工作流 Skill 与项目 SOP
- `.agents/roles/`：CLI 中立项目级角色定义
- `.agents/hooks/`：Team Context 事件记录协议
- `spec/context/knowledge/`：项目架构、模块理解、技术调研
- `spec/context/experience/`：困境-策略、踩坑经验、决策经验

> AGENTS.md 是入口清单，不承载长篇规范。每个 Spec 收尾时由 spec-end 审查是否需要维护 AGENTS.md 或 `.agents/rules/`。

[!important] AGENTS.md 是模板 根据用户提供的项目信息填充模板。如果用户有额外的长期项目规范或偏好，优先写入 .agents/rules/，只在需要修改入口、导入或项目身份摘要时更新 AGENTS.md。

步骤 4：创建 .agents/ 配置目录

4.1 创建 rules/ 目录

mkdir -p ".agents/rules"

创建 .agents/rules/coding-style.md（编码风格模板，根据技术栈调整）：

# 编码风格

- 变量命名：{根据语言选择 camelCase / snake_case}
- 函数/方法：简短、单一职责
- 文件长度：建议不超过 300 行
- 注释：关键逻辑必须注释，勿注释显而易见的代码
- 本文件只记录长期规则，临时实现细节不要写入

创建 .agents/rules/project-preferences.md（项目偏好模板，根据项目类型调整）：

# 项目偏好

- 产品体验：{如内部工具优先信息密度；未知则写"遵循现有产品风格"}
- 前端风格：{如 UI 项目，记录布局、组件、图标、色彩、动效等长期偏好}
- 协作习惯：{如评审口径、发布节奏、命名偏好}
- 偏好必须长期有效、可复用；一次性需求写入当前 Spec
- 详细设计理由写入 `spec/context/knowledge/`

创建 .agents/rules/spec-workflow.md（Spec 工作流规范）：

# Spec 工作流规范

- 实现前必须有已确认的 writer/plan.md
- 不添加 Spec 未定义的功能
- 每个关键节点等待用户确认
- 收尾时使用 exp-reflect 沉淀经验，并由 spec-end 审查是否维护 AGENTS.md / rules
- rules 只记录长期项目约束，避免写入一次性任务细节

创建 .agents/rules/documentation.md（文档规范）：

# 文档规范

- 所有 Spec 文档使用 Obsidian Flavored Markdown
- Spec 目录命名：`YYYYMMDD-HHMM-任务描述`，任务描述使用中文
- 使用 `[[wikilink]]` 建立文档关联
- 每个文档包含完整 YAML frontmatter
- 长篇背景写入 `spec/context/knowledge/`，不要塞进 AGENTS.md

创建 .agents/rules/git-workflow.md（GitHub Flow 规范）：

# GitHub Flow 规范

- 每个新 Spec 从 main 创建短生命周期分支
- 同一活跃 Spec 的 update 复用原 Spec 分支
- 禁止直接在 main 上实现、测试或归档 Spec
- writer/plan.md / updater/update-xxx.md 必须记录 git_branch、base_branch、pr_url
- 收尾时提交、推送当前分支并创建 PR
- PR 合并后同步 main 并删除本地/远程工作分支

[!tip] rules/ 每文件 ≤ 20 行 .agents/rules/ 中的文件每次会话都会加载，保持精简，避免占用 context window。新增长期规则时优先更新已有文件，必要时再创建新的规则文件。

4.2 创建 skills/ 目录并安装 Skills

mkdir -p ".agents/skills"

引导用户安装 Skills 体系：

请选择 Skills 安装方式：
- 通过 R&K Flow CLI 安装：运行 rk-flow init 安装核心 Skills
- 手动安装：从 GitHub 仓库手动复制 Skills 到 .agents/skills/
- 跳过：稍后手动安装，先完成其他初始化

如果用户选择 CLI 安装：

rk-flow init

4.3 创建项目级角色定义与运行时 Agent 适配

[!important] 角色定义属于 spec-init spec-start 只负责加载和唤起角色实例，不再内联维护 7 个角色的 prompt 模板。7 个角色的唯一源定义见 references/project-agent-roles.md。

创建中立角色定义目录（始终创建），以及 仅当前运行环境 的适配目录：

# 中立角色定义：始终创建
mkdir -p ".agents/roles"

# 运行时适配目录：只创建 <runtime> 对应的一个
# <runtime> == omp    → mkdir -p ".omp/agents"
# <runtime> == claude → mkdir -p ".claude/agents"
# <runtime> == codex  → mkdir -p ".codex/agents"

按 references/project-agent-roles.md 创建 7 个中立角色定义：

.agents/roles/spec-explorer.md
.agents/roles/spec-writer.md
.agents/roles/spec-tester.md
.agents/roles/spec-executor.md
.agents/roles/spec-debugger.md
.agents/roles/spec-reviewer.md
.agents/roles/spec-ender.md

角色定义必须包含：

• role_id
• required_skill
• purpose
• activation
• inputs
• outputs
• handoff
• rules

同时生成 仅 <runtime> 对应 的项目级运行时 Agent 适配文件（其它环境不创建）。

若 <runtime> == claude，生成 Claude Code 适配：

.claude/agents/spec-explorer.md
.claude/agents/spec-writer.md
.claude/agents/spec-tester.md
.claude/agents/spec-executor.md
.claude/agents/spec-debugger.md
.claude/agents/spec-reviewer.md
.claude/agents/spec-ender.md

若 <runtime> == codex，生成 Codex 适配：

.codex/agents/spec-explorer.toml
.codex/agents/spec-writer.toml
.codex/agents/spec-tester.toml
.codex/agents/spec-executor.toml
.codex/agents/spec-debugger.toml
.codex/agents/spec-reviewer.toml
.codex/agents/spec-ender.toml

并按需创建/合并 .codex/config.toml（不存在则创建最小配置，已存在则在不覆盖用户配置的前提下合并 [agents]）：

[agents]
max_threads = 7
max_depth = 1

若 <runtime> == omp，生成 OMP 适配。OMP 只发现 .omp/agents/<name>.md，明确跳过 .claude/agents 与 .codex/agents（其 frontmatter 不符合 OMP task-agent 契约）：

.omp/agents/spec-explorer.md
.omp/agents/spec-writer.md
.omp/agents/spec-tester.md
.omp/agents/spec-executor.md
.omp/agents/spec-debugger.md
.omp/agents/spec-reviewer.md
.omp/agents/spec-ender.md

运行时适配规则（只应用 <runtime> 对应的条目，其它环境的规则跳过）：

• Claude Code 适配文件使用 Markdown + YAML frontmatter，正文要求角色先读取 .agents/roles/<role-id>.md
• Codex 适配文件使用 TOML，developer_instructions 要求角色先读取 .agents/roles/<role-id>.md
• Codex 适配文件的文件名继续使用 <role-id>.toml，但 name 字段使用 snake_case，例如 spec_explorer、spec_tester
• Codex CLI 的 /agent 只显示已启动的子 Agent 线程，不显示 .codex/agents/ 下的 Agent 库；验证时应明确要求 Codex spawn 对应 name
• 不向 ~/.claude/agents/ 或 ~/.codex/agents/ 写入任何文件，除非用户明确要求安装为个人全局 Agent
• 已存在的角色或适配文件不覆盖；如需要更新，先说明差异并等待用户确认
• OMP 适配文件使用 Markdown + YAML frontmatter，但遵循 OMP task-agent 契约：frontmatter 必须含 name 与 description（缺一即被判为无效定义而跳过），正文整体作为该 Agent 的 system prompt，正文首行要求角色先读取 .agents/roles/<role-id>.md 获取权威职责
• OMP 可选 frontmatter 字段：model（按角色挂不同模型，对应 modelRoles 思路）、thinkingLevel（off/minimal/low/medium/high/xhigh）、tools（CSV 或数组，限制可用工具）、spawns（*/CSV，控制可再 spawn 的 Agent）、output（结构化输出 schema）、read-summarize: false（让该 Agent 的 read 返回原文而非摘要）
• 每个角色的推荐 OMP 字段（tools/spawns/thinkingLevel/read-summarize 及理由）见 references/project-agent-roles.md 的「OMP Per-Role Field Mapping」表。要点：spec-explorer/spec-reviewer 限只读工具；spec-writer/spec-executor/spec-debugger 设 read-summarize: false 读原文；spec-tester 是 delegation 例外（必须真跑测试采集证据，不套用「子 Agent 跳过验证」默认）；7 个角色一律 spawns: "" 保持深度 1
• TeamLead 是 OMP 主 Agent，通过 task 工具 spawn 这 7 个 .omp/agents 角色；角色间协作（如 spec-tester ↔ spec-debugger 修复循环）用 OMP 的 irc 子 Agent 通信，handoff 仍落盘到 lead/team-context.md
• 注意 OMP 的 task.maxRecursionDepth：TeamLead spawn 的角色处于深度 1，若某角色还需再 spawn 子 Agent，受递归深度限制，必要时在角色 frontmatter 显式声明 spawns 并确认未触顶
• .agents/skills/ 本身就是 OMP agents provider 的原生发现路径（受 enableAgentsProject 控制），R&K 的 Skill 在 OMP 下开箱即用，无需额外 skill 适配
• 不向 ~/.omp/agent/agents/ 写入任何文件，除非用户明确要求安装为个人全局 Agent；已存在的 .omp/agents/*.md 不覆盖，需要更新先说明差异并等待用户确认

4.4 创建中立 Hook 协议与运行时适配

Hook 的职责是自动维护 lead/team-context.md 的事实事件，不负责流程决策。spec-init 必须创建中立协议文件，当前运行环境再按自己的 Hook 系统生成适配：

mkdir -p ".agents/hooks"

创建 .agents/hooks/team-context-hook-contract.md，内容来源见 references/team-context-hook-contract.md。

运行时适配规则（Hook 适配只为 <runtime> 生成；中立协议文件始终创建）：

• .agents/hooks/team-context-hook-contract.md 是唯一的跨 CLI Hook 协议源，描述事件语义、可自动更新区块、禁止自动推断的区块和安全规则。
• 生成 Claude Code / Codex 项目级 Hook 适配时，参考 references/runtime-hook-examples.md；样例只用于运行时配置，不替代中立协议。
• Claude Code 运行时根据该协议生成或更新 .claude/settings.json，接入 Claude Code 当前版本支持的项目级 hooks。
• Codex 运行时根据该协议生成或更新 .codex/ 下当前版本支持的 hooks 配置；不要在中立协议里写死 Codex 配置 schema。
• 适配器可以创建 .agents/hooks/team-context-sync.* 作为本项目的同步脚本，但脚本输入输出必须遵循中立协议。
• 如果当前运行环境不支持 hooks，或用户不希望自动 hook，跳过适配，只保留中立协议，并由 TeamLead / 各角色按 lead/team-context.md 规则手动维护。
• 已存在的 .claude/settings.json、.codex/* hook 配置或 .agents/hooks/team-context-sync.* 不覆盖；如需要更新，先说明差异并等待用户确认。
• OMP 运行时根据该协议在 .omp/hooks/post/*.ts 生成事件 Hook：OMP Hook 是 default-export 的工厂函数 export default (pi) => { pi.on(...) }，通过 pi.on("tool_result", ...) 监听 write/edit 等工具结果，自动向 lead/team-context.md 追加 artifact 写入、updated_at、Task Progress 等事实事件；可用事件还包括 agent_start / agent_end / turn_end，分别记录角色启动/结束。
• OMP 独有：Hook 还应监听 session.compacting，在上下文压缩前把当前 Spec 的恢复要点（阶段、门禁、Loop Budget、Next Action、未确认产物）从 lead/team-context.md 只读注入回上下文，保证压缩后仍能从落盘账本恢复。这是 Claude Code / Codex hook 没有的能力，直接服务 R&K「跨上下文必须从落盘恢复」原则。样例见 references/runtime-hook-examples.md。
• OMP 不读取 .claude/settings.json 也不读取 .codex/hooks.json；OMP 同步脚本放在 .omp/hooks/post/team-context-sync.ts，输入输出仍遵循中立协议，只记录事实、不推断业务结论。
• 如果用户未启用 OMP hook 或运行环境不便注入 TS Hook，则降级跳过，由 TeamLead / 各角色按 lead/team-context.md 规则手动维护；已存在的 .omp/hooks/** 不覆盖，需要更新先说明差异并等待用户确认。

Hook 只自动记录事实：

• 文件创建/修改、artifact 状态、updated_at
• Git/PR 元数据
• agent runtime handle
• 当前角色自己的 Task Progress
• 问题发现/解决文件对应的 Problem Resolution Log 初始行或状态

Hook 不自动推断：

• Next Action
• gate decision
• handoff reason
• blocker 业务判断
• plan / test / debug 正文摘要

步骤 5：创建 Spec 目录结构

# 创建分类目录
mkdir -p "spec/01-产品规划"
mkdir -p "spec/02-技术设计"
mkdir -p "spec/03-能力交付"
mkdir -p "spec/04-系统改进"
mkdir -p "spec/05-验证工程"
mkdir -p "spec/06-已归档"

# 创建记忆系统目录
mkdir -p "spec/context/experience"
mkdir -p "spec/context/knowledge"

步骤 6：创建记忆索引文件

创建 spec/context/experience/index.md：

---
title: 经验记忆索引
type: index
updated: {当前日期}
---

# 经验记忆索引

> 此文件由 exp-write 自动维护，记录所有经验记忆的摘要。
> 详情按需检索，避免占用过多 context window。

## 经验列表

（暂无经验记录）

创建 spec/context/knowledge/index.md：

---
title: 知识记忆索引
type: index
updated: {当前日期}
---

# 知识记忆索引

> 此文件由 exp-write 自动维护，记录所有知识记忆的摘要。
> 详情按需检索，避免占用过多 context window。

## 知识列表

（暂无知识记录）

步骤 7：注册 Obsidian Vault

检查项目根目录是否已有 .obsidian/ 目录：

ls .obsidian/

如果不存在，创建最小化的 Obsidian Vault 配置：

mkdir -p ".obsidian"

创建 .obsidian/app.json（基础配置）：

{
  "alwaysUpdateLinks": true,
  "newLinkFormat": "relative",
  "useMarkdownLinks": false,
  "showFrontmatter": true
}

创建 .obsidian/community-plugins.json（推荐插件列表）：

[
  "obsidian-bases"
]

步骤 8：向用户确认初始化结果

展示初始化摘要，并询问下一步：

项目 Spec 开发环境已初始化完成：
- AGENTS.md（项目身份 + 入口路由）
- .agents/rules/（长期规则 + 项目偏好）
- .agents/skills/（Skills 体系）
- .agents/roles/（CLI 中立项目级角色定义）
- .agents/hooks/（中立 Hook 协议；运行时适配按需生成）
- 运行时适配（只创建了 `<runtime>` 对应的一套）：
  - omp    → .omp/agents/ + .omp/hooks/post/
  - claude → .claude/agents/ + .claude/settings.json
  - codex  → .codex/agents/ + .codex/ hook 配置
- spec/（Spec 目录 + 记忆系统）
- .obsidian/（Obsidian Vault）

是否需要立即启动一个开发任务？
- 启动开发任务：调用 spec-start 加载项目级角色并开始 5 阶段流程
- 暂不启动：先熟悉项目结构，稍后手动调用 /spec-start

用户选择"启动开发任务"时，调用 /spec-start。

初始化后的目录结构

注意：.claude/、.codex/、.omp/ 三套运行时适配只生成 <runtime> 对应的一套，下图同时列出仅为参考。

项目根目录/
├── AGENTS.md                        # 项目身份 + 入口清单 + 路由
├── .agents/
│   ├── rules/                       # 长期规则与项目偏好（每文件 ≤ 20 行）
│   │   ├── coding-style.md          # 编码风格
│   │   ├── project-preferences.md   # 项目偏好/产品体验/前端风格
│   │   ├── spec-workflow.md         # Spec 工作流规范
│   │   ├── documentation.md         # 文档规范
│   │   └── git-workflow.md          # GitHub Flow 规范
│   ├── roles/                       # CLI 中立项目级角色定义
│   │   ├── spec-explorer.md
│   │   ├── spec-writer.md
│   │   ├── spec-tester.md
│   │   ├── spec-executor.md
│   │   ├── spec-debugger.md
│   │   ├── spec-reviewer.md
│   │   └── spec-ender.md
│   ├── hooks/                       # 中立 Hook 协议 + 运行时同步脚本
│   │   ├── team-context-hook-contract.md
│   │   └── team-context-sync.*       # 由当前运行环境按需生成
│   └── skills/                      # Skills 体系（通过 CLI 或手动安装）
│       ├── spec-init/SKILL.md
│       ├── spec-start/SKILL.md
│       ├── spec-explore/SKILL.md
│       ├── spec-write/SKILL.md
│       ├── spec-test/SKILL.md
│       ├── spec-execute/SKILL.md
│       ├── spec-debug/SKILL.md
│       ├── spec-end/SKILL.md
│       ├── spec-update/SKILL.md
│       ├── spec-review/SKILL.md
│       ├── exp-search/SKILL.md
│       ├── exp-reflect/SKILL.md
│       ├── exp-write/SKILL.md
│       ├── intent-confirmation/SKILL.md
│       ├── git-work/SKILL.md
│       ├── skill-creator/SKILL.md
│       ├── find-skills/SKILL.md
│       ├── obsidian-markdown/SKILL.md
│       ├── obsidian-bases/SKILL.md
│       ├── obsidian-plugin-dev/SKILL.md
│       └── json-canvas/SKILL.md
├── .claude/                          # 仅当 <runtime> == claude 生成
│   ├── settings.json                 # Claude Code 项目级 Hook 配置（如需）
│   └── agents/                      # Claude Code 项目级 Agent 适配
│       ├── spec-explorer.md
│       ├── spec-writer.md
│       ├── spec-tester.md
│       ├── spec-executor.md
│       ├── spec-debugger.md
│       ├── spec-reviewer.md
│       └── spec-ender.md
├── .codex/                          # 仅当 <runtime> == codex 生成
│   ├── config.toml                  # Codex 项目级 Agent 配置（如需）
│   ├── hooks.json                   # Codex 项目级 Hook 配置（如需）
│   └── agents/                      # Codex 项目级 Agent 适配
│       ├── spec-explorer.toml
│       ├── spec-writer.toml
│       ├── spec-tester.toml
│       ├── spec-executor.toml
│       ├── spec-debugger.toml
│       ├── spec-reviewer.toml
│       └── spec-ender.toml
├── .omp/                            # 仅当 <runtime> == omp 生成（OMP 运行时适配）
│   ├── agents/                      # OMP 项目级 Agent 适配（OMP 只发现 .omp/agents）
│   │   ├── spec-explorer.md
│   │   ├── spec-writer.md
│   │   ├── spec-tester.md
│   │   ├── spec-executor.md
│   │   ├── spec-debugger.md
│   │   ├── spec-reviewer.md
│   │   └── spec-ender.md
│   └── hooks/
│       └── post/
│           └── team-context-sync.ts # OMP 事件 Hook（如需）
├── spec/
│   ├── 01-产品规划/
│   ├── 02-技术设计/
│   ├── 03-能力交付/
│   │   └── YYYYMMDD-HHMM-任务描述/    # 由 spec-start 创建
│   │       ├── lead/                  # TeamLead 运行上下文
│   │       │   └── team-context.md
│   │       ├── explorer/              # spec-explorer 产物
│   │       │   └── exploration-report.md
│   │       ├── writer/                # spec-writer 产物
│   │       │   └── plan.md
│   │       ├── tester/                # spec-tester 产物
│   │       │   ├── test-plan.md
│   │       │   ├── test-report.md
│   │       │   └── artifacts/
│   │       │       └── test-logs/
│   │       ├── executor/              # spec-executor 产物
│   │       │   └── summary.md
│   │       ├── debugger/              # spec-debugger 产物（按需）
│   │       │   ├── debug-001.md
│   │       │   └── debug-001-fix.md
│   │       ├── reviewer/              # spec-reviewer 产物（按需）
│   │       │   ├── review.md
│   │       │   └── update-001-review.md
│   │       ├── updater/               # spec-update 产物（按需）
│   │       │   ├── update-001.md
│   │       │   └── update-001-summary.md
│   │       └── ender/                 # spec-ender 产物
│   │           └── end-report.md
│   ├── 04-系统改进/
│   ├── 05-验证工程/
│   ├── 06-已归档/
│   └── context/
│       ├── experience/
│       │   └── index.md             # 经验索引
│       └── knowledge/
│           └── index.md             # 知识索引
└── .obsidian/                       # Obsidian Vault 配置
    ├── app.json                     # 基础配置
    └── community-plugins.json       # 推荐插件

后续动作

初始化完成后确认：

1. Git 仓库状态已检查；如用户确认，已完成 git init + main 分支初始化
2. AGENTS.md 已创建（项目身份 + 入口清单 + 路由）
3. .agents/rules/ 已创建（编码规范 + 项目偏好 + Spec 工作流 + 文档规范 + GitHub Flow）
4. .agents/skills/ 已安装或引导安装
5. .agents/roles/ 已创建（7 个项目级角色定义）
6. .agents/hooks/ 已创建（中立 Hook 协议；运行时适配按当前 CLI 能力生成或降级跳过）
7. 运行时适配已按 <runtime> 只创建一套：
   • omp → .omp/agents/（OMP 只发现 .omp/agents，跳过 .claude/.codex）+ .omp/hooks/post/
   • claude → .claude/agents/ + .claude/settings.json
   • codex → .codex/agents/ + .codex/ hook 配置（+ .codex/config.toml 的 [agents]）
8. spec/ 目录结构已创建（6 个分类目录 + context/；单个 Spec 内由 spec-start 创建角色子目录）
9. 经验/知识索引文件已创建
10. Obsidian Vault 已注册（.obsidian/ + app.json）
11. 已询问用户是否启动开发任务（spec-start）

常见陷阱

• 已有 AGENTS.md 时覆盖用户自定义内容（应先检查，已有则跳过或合并）
• 跳过步骤 2 的运行环境询问，默认三套适配全建（应先确认 <runtime>，只建对应一套）
• 已有 .agents/rules/ 时覆盖已有规范（应先检查）
• 已有 .agents/roles/ 或运行时适配文件时覆盖用户自定义角色（应先检查）
• 已有 .agents/hooks/、.claude/settings.json 或 .codex hook 配置时直接覆盖（应先检查并合并）
• 误以为 OMP 能读 .claude/agents 或 .codex/agents（实际被跳过，必须生成 .omp/agents/*.md 才能被 OMP 发现）
• 已有 .omp/agents/*.md 或 .omp/hooks/** 时直接覆盖（应先检查并说明差异）
• 已有 spec/ 目录时重复创建（应先检查）
• 覆盖已有的 .obsidian/ 自定义配置（应先检查）
• 初始化后直接开始开发，跳过 spec-start 的需求对齐阶段
• AGENTS.md 中的技术栈信息与实际项目不符（应根据用户回答填充）