eo-project-init

定位

所有 eo- skill 的总入口*。其它 skill（eo-change / eo-implement / eo-doc-manager / …）都依赖 .eo-project.json；未运行过本 skill 的项目无法使用其它 eo-* skill。

一次 init 完成三件事：

1. 生成 .eo-project.json（项目级配置，所有 skill 读它）
2. 初始化项目管理侧（<repo>/.eo-project/）——最小骨架
3. 初始化代码侧 eo-doc/ 最小骨架（内部调用 eo-doc-manager init 的子流程）

配置与目录约定详见 references/config.md。

输入

用户提供以下之一：

• PRD/MVP 文档路径
• 口头描述：项目名称 + 要做什么 + 大致阶段
• 仅项目名：快速创建空骨架（后续再补充）

可选：

• 代码仓库路径（当前 cwd 不是代码仓库时）

执行步骤

1. 检查是否已初始化

• cwd 向上已有 .eo-project.json → 走下方「1.5 更新/修复分支」，不进入首次创建流程
• 未有 → 继续首次创建流程

1.5 更新/修复分支（已初始化项目重跑本 skill）

对已有 .eo-project.json 的项目，重跑是幂等的补齐动作，逐项执行、已达标项静默跳过：

0. v1 痕迹检测：发现 eo-doc/dev/ 存在、kanban_path 非 null 等信号 → 先按 references/migrate-v1.md 执行迁移子流程（冻结 spec、建项目级 changes、kanban 退役、roadmap 补 frontmatter、backlog 打散成卡等，幂等），完成后继续下列步骤 0.5. 协作者接入（local 覆盖）：按 config.md 规则合并同目录 .eo-project.local.json（如有）后，检查合并结果的 project_root 在本机是否存在可写。不可用（典型：clone 了别人提交的配置，project_root 指向他人机器上的路径）或必填字段缺失 → 按「3. 计算 project_root」算出本机 project_root，把机器相关字段（mode / project_root）写入 .eo-project.local.json——不改动提交的 .eo-project.json。后续步骤一律以合并结果为准
1. 配置校验：读现有 .eo-project.json（合并 local 覆盖），对照 references/config.md 的 schema——基础字段（project_name/mode/project_root/doc_root）缺失按默认补写；存量配置的 kanban_path 字段忽略不改，已有字段一律不改；project_root 非绝对路径（存量形态）是可修项——按 repo root 解析并解软链后回写绝对路径并提示用户（写回落点沿用既有规则：该顶层字段已存在于 .eo-project.local.json → 写 local，否则写 .eo-project.json）；解析不出已存在目录时不猜，转「3. 计算 project_root」重新算出；sync 段（或其适配器键）与 state 键缺失时不在本步补写（补了显式关闭条目会吞掉第 5 步的询问），只记录缺失，留给第 5 步问答/迁移后落盘
2. 骨架补齐：项目管理侧必建 roadmap.md 与代码侧 eo-doc/ 骨架缺什么补什么；不触碰任何已有文件的内容
3. 注入段刷新：按标记整段刷新 agent 配置文件中的 eo-project / eo-doc / eo-reply-contract 注入段（存在则整段替换，缺失则补注）；仓库根存在 DESIGN.md 时核对 eo-design 注入段
4. .gitignore 核对：tmp/eo/、.eo-project.local.json 缺项补写；.eo-project/ 的 ignore 状态保持现状不核对——已 ignore 的不删行、未 ignore 的不补写
5. sync / state 联动问答与存量迁移（仅合并配置 sync 段缺对应适配器键时问，规则见「7. 生成 .eo-project.json」的 sync 段小节）。存量迁移：检测到旧 board / github 段且合并配置无 sync 键 → 提示用户并代写等价 sync 段（启用集与兼容映射派生结果逐项一致；旧段问答已答过的适配器写显式条目——含关闭态，不重问；旧段保留不删，旧版工具仍可读）；已有 sync 键 → 零动作零提示 state 问答（仅合并配置无 state 键时问，规则见「7. 生成 .eo-project.json」的 state 段小节）：检测到存量 eo-doc/state/ → 问「恢复维护（推荐）/ 保持冻结」，结论写 state.enabled true/false；无存量 state/ → 按 §7 同一问（推荐关闭）；已有 state 键 → 零动作零提示 5.5. 顺手注册：执行 eo-board --register（幂等，已注册则原地更新）。失败不阻塞本流程——注册失败时输出告警并给手工补注册指引：「⚠ 项目注册失败（<原因>），init 已正常完成；稍后可在项目目录手工执行 eo-board --register 补注册（注册后任意目录 eo-board --all 可见本项目）」
6. 输出摘要：列出本次补齐/刷新/跳过了什么（含注册结果），然后结束——不执行首次创建流程的其余步骤

2. 解析项目信息

从输入中提取：

• 项目名称（project_name）
• 项目目标：一句话描述
• 初始状态：active / researching

3. 计算 project_root

project_root = <repo>/.eo-project/。

检查 project_root 是否已存在：

• 存在且含 roadmap.md → 按封闭选择协议三选一：1) 只建代码侧关联（推荐）2) 更新 roadmap 3) 重建（需确认）
• 存在但无 roadmap.md → 异常，提示补全后进入拆解
• 不存在 → 正常创建

4. 创建项目管理侧骨架（最小）

<project_root>/
└── roadmap.md     # 必建

按需目录一律不预建（backlog / phases / decisions / lessons / brainstorm / docs），等对应 skill 首次写入时由那个 skill 创建（backlog 为卡片目录，由 /eo-backlog 管理）。

写入 roadmap.md（读 templates/roadmap.md），填充项目名、目标、阶段概览占位。

5. Roadmap 拆解（可选）

如果用户提供了 PRD/MVP 或愿意拆解：

1. 读取 references/roadmap-breakdown.md 方法论
2. 与用户对话（不超过 5 轮）：终态 → 里程碑 → Phase → 任务
3. 用户确认后，lazy 创建 phases/ 目录，每个阶段一个文件（读 templates/phase.md）
4. 更新 roadmap.md 的阶段概览表

仅"快速创建空骨架"时可跳过此步。

6. 初始化代码侧 eo-doc/（内部调用 eo-doc-manager init 子流程）

在代码仓库根目录创建最小骨架：

eo-doc/
├── changes/INDEX.md          # 骨架
├── agent-handbook/INDEX.md   # 骨架（篇目内容见 §6.5）
└── templates/                # 空目录

额外：

• 询问是否启用 codegraph：启用则在仓库根执行 codegraph init 建索引，并把使用规范（索引按项目目录隔离，每个 worktree 需各自 codegraph init）写入 agent-handbook；不启用则跳过
• 将 tmp/eo/ 追加到 .gitignore（tmp/eo/ 是各 skill 的临时工件命名空间，见 ../eo-shared/conventions.md）
• 将 .eo-project.local.json 追加到 .gitignore（个人/机器覆盖文件不提交，见 references/config.md）
• CLAUDE.md 注入（详见 ../eo-doc-manager/references/claude-injection.md）

注意：如果用户本次只想要项目管理侧（例如纯规划项目，没代码），可用 --skip-code-side 跳过本节。此时 doc_root 字段仍写入配置，留待将来补建。

6.5 Handbook 初始化（可选，逐步授权）

eo-doc/agent-handbook/ 是 Agent 操作手册：相对固定的操作规范，非 SSOT（代码为准），不挂自动同步；骨架由 §6 建好，是否填内容询问用户，同意才继续。模板机制（库位置 / manifest 格式 / 匹配合并细则）见 references/handbook-templates.md。

已有项目（生成 = 匹配合并，不是裸 copy）：

1. 派子 agent 扫描五个面：lint/commit 配置、git log 归纳的 commit 规律、目录结构、架构分工、UI token 用法
2. 按 manifest signals 匹配候选 preset（私有库优先），按封闭选择协议确认（含「不用模板」）
3. 合并生成：实证 > 模板 > 待补——模板篇目为底，扫描实证覆盖冲突项，扫描不到依据的标「待补」；已配置文件化的只落一行指针（指向配置文件）
4. worktree 协作与 codegraph 使用两篇逐个询问授权后才写入（comments 注释纪律随 preset 默认生成，无需单独授权）

空项目：询问项目类型，选定 preset 纯 copy。

7. 生成 .eo-project.json

在代码仓库根目录写入：

{
  "project_name": "{{project_name}}",
  "mode": "local",
  "project_root": "{{absolute_path_to_project_root}}",
  "doc_root": "eo-doc",
  "kanban_path": null
}

kanban_path：固定写 null；存量配置该字段被所有 skill 忽略。项目级总览由 Bases 聚合各项目 roadmap.md 的 frontmatter 承担。

协作/多机场景：机器相关字段（project_root / mode / sync——顶层段整段覆盖）可拆到不提交的 .eo-project.local.json（顶层字段覆盖合并，规则见 references/config.md）。首次 init 默认全部写入 .eo-project.json 即可；协作者 clone 后重跑本 skill 走「1.5 更新/修复分支」的协作者接入步骤生成 local 覆盖。

sync 段（投影开关，eo-sync 直接消费——机制见 ../eo-shared/board-github.md，schema 见 references/config.md；新配置只写 sync 段本身，存量 board / github 段由兼容映射护住）：按封闭选择协议问一次（触发判据 = 合并配置 sync 段缺对应适配器键）——

• github 适配器（检测到 git remote 指向 GitHub 时才问；pr 推荐 auto）：写 sync.github = {"enabled": true, "issue": <bool>, "pr": "auto"|"always"|"never"}

用户跳过 → 对应适配器写显式关闭条目（{"enabled": false}），后续 skill 不再询问。后开场景：对已初始化项目重跑本 skill 走「1.5 更新/修复分支」，其第 5 步提供这一问。 state 段（现状文档层开关，/eo-doc-manager sync 与 archive 联动直接消费，schema 见 references/config.md）：按封闭选择协议问一次（触发判据 = 合并配置无 state 键）——「启用 state 现状文档层？」（推荐关闭：保持精简，需要「系统现在是什么样」活文档的项目再开）。启用 → 写 state.enabled: true 并建 eo-doc/state/（空目录，首篇由 /eo-doc-manager sync 生成）；跳过/拒绝 → 写显式 {"enabled": false}，后续不再询问。

8. 处理 .eo-project/

.eo-project/ 即 project_root。缺省随仓库提交，不写入 .gitignore——roadmap / backlog / decisions / lessons 是协作者最需要的项目记忆，跟代码走。

仅当用户明确表示不想提交管理侧时，当场追加：

# eo-project local management side
.eo-project/

9. Agent 配置注入

检测代码仓库使用的 agent 配置文件（顺序）：

1. CLAUDE.md
2. AGENTS.md
3. COPILOT.md
4. CURSOR.md
5. 都不存在 → 按封闭选择协议问创建哪个（推荐 CLAUDE.md）

注入两个标记段（均幂等、整段替换）：

1. 项目上下文段（<!-- eo-project:start/end -->）：

<!-- eo-project:start -->
## EO-Project

本项目已接入 eo-skills。项目管理侧（roadmap / backlog 卡片 / decisions / lessons 等）位置从 `.eo-project.json` 的 `project_root` 字段解析（同目录存在 `.eo-project.local.json` 时顶层字段覆盖，local 优先），下文记作 `<project_root>`。

- 代码侧文档：`{{doc_root}}/`

### 项目记录入口

仅当**用户明确表达**要记录时响应（不做关键词嗅探，避免误触发）：

- 用户明确说「加个待办 / 记到 backlog / 以后做」→ 调用 `/eo-backlog` 写卡到 `<project_root>/backlog/`
- 用户明确说「把这个决策记下来」→ 调用 `/eo-project-record` 写入 `<project_root>/decisions/`
- 用户明确说「记一条经验 / 踩坑记录一下」→ 调用 `/eo-project-record` 写入 `<project_root>/lessons/`

对话中出现疑似待办/决策/教训但用户未明说时，**至多在当前话题收尾处轻提一句**「要不要记入 backlog/decisions/lessons？」，不打断进行中的工作。
<!-- eo-project:end -->

2. 回复契约段（<!-- eo-reply-contract:start/end -->）：

<!-- eo-reply-contract:start -->
## 回复契约（长任务收尾）

长开发任务收尾时，用一段人话向用户汇报，四条各一句：

1. **做了什么**——行为变化，不是 diff 清单
2. **为什么这么做**——关键决策与理由，被否掉的方案一并点名
3. **主要产出**——文件 / 功能 / 命令，用户去哪看、怎么验
4. **遇到的问题与解法**——没有就明说「无」

受众分两层：对开发者讲接口与路径，对需求方讲行为与结果。一句一事，不铺陈过程。
<!-- eo-reply-contract:end -->

段内正文以 ../eo-shared/reply-contract.md「契约正文」为单一来源，整段搬运不改写——注入是被动兜底通道（覆盖非 eo 流程的直改收尾）；eo 流程收尾的硬步骤（eo-archive 交付汇报 / eo-loop 线段收尾报告）以该文「生效通道」为准。

模板纪律：项目上下文段不内联 project_root 绝对路径——它因人/机器而异且 agent 配置文件提交进仓库，内联会把个人路径泄进 git 并在协作者机器上失真。运行时一律从配置合并结果解析。

DESIGN.md 检查：若仓库根存在 DESIGN.md 但 agent 配置文件中无 <!-- eo-design:start --> 标记段，执行 /eo-design 的约束注入子步骤补上（注入模板见 ../eo-design/references/design-md-template.md）。

10. 注册到生态注册表（顺手注册）

执行 eo-board --register（在仓库根目录），把项目登记进用户级注册表 ${EO_HOME:-$HOME/.eo}/projects.json，供 eo-board --all / eo-sync watch --all 跨项目枚举。

失败不阻塞 init——注册失败（如注册表目录不可写）时本 skill 仍算成功完成，但必须输出告警与手工补注册指引：「⚠ 项目注册失败（<原因>），init 已正常完成；稍后可在项目目录手工执行 eo-board --register 补注册（注册后任意目录 eo-board --all 可见本项目）」

11. 输出摘要

展示：

• .eo-project.json 路径和内容
• 项目管理侧骨架结构
• 代码侧骨架结构
• gitignore / agent 配置 / 生态注册 状态

输出

• 代码仓库：.eo-project.json + eo-doc/ 最小骨架 + agent 配置注入
• 项目管理侧：<project_root>/ 含 roadmap.md（+ 按需 backlog/ 卡片、phases/ 等）

约束

• .eo-project.json 是所有 eo- skill 的启动前置*。本 skill 的核心产出
• 按需目录（phases / decisions / lessons / brainstorm / docs）init 时不预建，由对应 skill 首次写入时 lazy 创建
• 项目名用用户给的原始名称，不转换
• 原始 PRD/MVP 若提供，存到 <project_root>/docs/（lazy 建）
• .eo-project/ 缺省随仓库提交、不进 .gitignore；用户明确不想提交时当场覆盖。存量项目重跑本 skill 不改其既有 ignore 状态
• .eo-project.local.json 始终进 .gitignore（个人/机器覆盖，不提交）；协作者接入只写 local，不改共享的 .eo-project.json
• agent 配置注入使用 <!-- ...:start/end --> 标记段（eo-project / eo-reply-contract），幂等可重复执行