| name | eo-project-init |
| description | eo-skills 在当前仓库的总入口：生成 .eo-project.json、初始化项目管理侧（roadmap/log/backlog）和代码侧最小骨架（eo-doc/），按需建 vault 软链和 agent 配置注入。触发：启动项目 / 初始化项目 / 新建项目 / /eo-project-init。 |
eo-project-init
定位
所有 eo- skill 的总入口*。其它 skill（eo-change / eo-implement / eo-doc-manager / …）都依赖 .eo-project.json；未运行过本 skill 的项目无法使用其它 eo-* skill。
一次 init 完成三件事：
- 生成
.eo-project.json（项目级配置，所有 skill 读它）
- 初始化项目管理侧（vault 或 local 模式）——最小骨架
- 初始化代码侧
eo-doc/ 最小骨架（内部调用 eo-doc-manager init 的子流程）
配置与目录约定详见 references/config.md。
输入
用户提供以下之一：
- PRD/MVP 文档路径
- 口头描述：项目名称 + 要做什么 + 大致阶段
- 仅项目名：快速创建空骨架（后续再补充）
可选：
- 代码仓库路径（当前 cwd 不是代码仓库时）
- 运行模式偏好（vault / local），不指定则按用户级配置推断
执行步骤
1. 解析配置来源
-
旧路径自动迁移（静默，执行一次）：若 ~/.eo-skills.json 存在且 ~/.eo/config.json 不存在，执行：
mkdir -p ~/.eo
mv ~/.eo-skills.json ~/.eo/config.json
迁移后打印一行提示：已将旧配置 ~/.eo-skills.json 迁移至 ~/.eo/config.json。之后不再检查旧路径。
-
检查 cwd 是否已有 .eo-project.json：
- 已有 → 走「更新/修复」分支（见 §6）
- 未有 → 继续 §3
-
读取 ~/.eo/config.json（用户级默认，可能不存在）：
- 存在 → 取
default_mode / vault_root 等作为推荐值进入 §2（节号指下文的"询问运行模式"）
- 不存在 → 进入 §2 时推荐值为空
2. 询问运行模式（必须问，不默认）
不要直接默认到 local。向用户展示两种模式的区别，让其选择：
这个项目的"项目管理侧"（roadmap / log / backlog / decisions / lessons 等）放在哪里？
A) vault 模式 —— 集中到 Obsidian/文档 vault，跨项目统一浏览
• project_root = <vault_root>/<projects_subdir>/<项目名>/
• 默认把整个 vault 项目目录软链挂到代码侧 eo-doc/vault/（单点整挂，vault 侧新增子目录代码侧自动可见）
• 可选挂到全局项目看板（kanban_path）统一追踪进度
• 适合：多个项目并行、用 Obsidian 做 PKM、想在一处看所有项目状态
B) local 模式 —— 放在仓库自己的 .eo-project/ 下，跟代码走
• project_root = <repo>/.eo-project/
• 默认进 .gitignore（不提交），也可选随仓库提交
• 不建软链、不挂看板
• 适合：单个项目、没有统一 vault、不想跨目录跳转
用户回答后：
- 若选 vault 但用户级配置无
vault_root → 当场询问 vault_root 路径（以及可选的 projects_subdir / kanban_path / create_symlink），写入 ~/.eo/config.json（必要时先 mkdir -p ~/.eo）
- 若用户级已有推荐值，展示并让用户确认或覆盖
最终落定 mode = "vault" | "local" 进入 §3。
3. 解析项目信息
从输入中提取：
- 项目名称（
project_name）
- 项目目标：一句话描述
- 初始状态：
active / researching
4. 计算 project_root
- vault 模式：
<vault_root>/<projects_subdir>/<project_name>/
- local 模式：
<repo>/.eo-project/
检查 project_root 是否已存在：
- 存在且含
roadmap.md → 询问：1) 只建代码侧关联 2) 更新 roadmap 3) 重建（需确认）
- 存在但无
roadmap.md → 异常，提示补全后进入拆解
- 不存在 → 正常创建
5. 检查活跃项目数（仅 vault + 有看板）
若 kanban_path 已配置，读取看板，「进行中」已有 3 个项目时提醒用户考虑搁置或归档。
6. 创建项目管理侧骨架（最小）
<project_root>/
├── roadmap.md # 必建
├── log.md # 必建
└── backlog.md # 必建
按需目录一律不预建（phases / decisions / lessons / brainstorm / docs），等对应 skill 首次写入时由那个 skill 创建。
写入 roadmap.md（读 templates/roadmap.md），填充项目名、目标、阶段概览占位。
写入 log.md（读 templates/log.md）。
写入 backlog.md：
---
type: backlog
project: "{{project_name}}"
updated: "{{date}}"
---
# {{project_name}} Backlog
> 待办池 + 未接入的未来规划（如将来想接入 research、knowledgebase skill 时的 placeholder）。
## 待办
## 灵感 & 以后再说
## 未接入（等 skill 支持再接入）
7. Roadmap 拆解（可选）
如果用户提供了 PRD/MVP 或愿意拆解：
- 读取 references/roadmap-breakdown.md 方法论
- 与用户对话（不超过 5 轮）：终态 → 里程碑 → Phase → 任务
- 用户确认后，lazy 创建
phases/ 目录，每个阶段一个文件（读 templates/phase.md）
- 更新
roadmap.md 的阶段概览表
仅"快速创建空骨架"时可跳过此步。
8. 初始化代码侧 eo-doc/（内部调用 eo-doc-manager init 子流程）
在代码仓库根目录创建最小骨架：
eo-doc/
├── agent-handbook/INDEX.md # 骨架
├── dev/INDEX.md # 骨架
└── templates/ # 空目录
不创建 state/（首次 /eo-doc-manager sync 时按需建）。
不创建 design/ / research/ / knowledgebase/（已移除）。
额外：
- 初始化
eo-doc/.sync-cursor（当前 HEAD 作为首次基线）
- 将
eo-doc/.sync-cursor 追加到 .gitignore
- CLAUDE.md 注入（详见
eo-doc-manager/references/claude-injection.md）
注意：如果用户本次只想要项目管理侧（例如纯规划项目，没代码），可用 --skip-code-side 跳过 §8。此时 doc_root 字段仍写入配置，留待将来补建。
9. 生成 .eo-project.json
在代码仓库根目录写入：
{
"project_name": "{{project_name}}",
"mode": "vault" | "local",
"project_root": "{{absolute_path_to_project_root}}",
"doc_root": "eo-doc",
"kanban_path": "{{absolute_kanban_path_or_null}}"
}
kanban_path 填入规则：
- vault 模式 + 用户级
kanban_path 有值 → 拼接为绝对路径 <vault_root>/<kanban_path>
- 否则 →
null
10. 建立软链（vault 模式 + create_symlink: true）
Obsidian 侧（vault）是源。把整个 vault 项目目录作为一个软链挂进代码侧：
ln -s <project_root> <repo>/<doc_root>/vault
整目录单点软链，不按子目录分别软链——这样 vault 侧日后新增 docs/ / phases/ / decisions/ 等子目录，代码侧自动能看到，不用回来补软链。
在 .gitignore 追加：
# eo-project vault link
<doc_root>/vault
local 模式不建软链。
11. 处理 .eo-project/（仅 local 模式）
.eo-project/ 即 project_root。默认追加到 .gitignore：
# eo-project local management side
.eo-project/
若用户明确想让管理侧随仓库提交，当场询问后跳过 gitignore 追加。
12. Agent 配置注入
检测代码仓库使用的 agent 配置文件（顺序）：
CLAUDE.mdAGENTS.mdCOPILOT.mdCURSOR.md- 都不存在 → 询问用户创建哪个
使用 <!-- eo-project:start --> / <!-- eo-project:end --> 标记段落幂等注入：
<!-- eo-project:start -->
## EO-Project
本项目通过 `.eo-project.json` 关联到项目管理侧：`{{project_root}}`
- 模式：`{{mode}}`
- 项目管理侧（roadmap / backlog / decisions / lessons 等）：`{{project_root}}`
- 代码侧文档：`{{doc_root}}/`
### 待办提醒
当对话中出现"以后要做"、"TODO"、"先跳过"、"回头处理"等信号，或用户做了 workaround 时，主动提示：
> 💡 检测到待办事项：「{内容}」。要加入项目 backlog 吗？
用户确认后调用 `/eo-backlog` 追加到 `{{project_root}}/backlog.md`。
### 决策同步
当对话中出现关键技术决策（选型、架构、方案取舍），提示：
> 💡 这是一个关键决策。要记录到 decisions/ 吗？
用户确认后，在 `{{project_root}}/decisions/` 创建决策记录（首次时 lazy 建目录）。
### 经验教训
当用户提到"踩坑"、"下次不这么干"、"学到了"时，提示：
> 💡 要记录到 lessons/ 吗？
用户确认后，在 `{{project_root}}/lessons/` 创建经验记录（首次时 lazy 建目录）。
<!-- eo-project:end -->
13. 注册到项目看板（仅 kanban_path 非空时）
在 kanban_path 指向的看板对应状态分区添加：
### {{project_name}}
- 状态：`active`
- 当前阶段：[[phase-1-<阶段名>]]（若已拆解）
- 下一步：<第一个任务或"待拆解">
- 阻塞：无
- 决策记录：无
- 经验教训：0 条
kanban_path: null 时跳过整步。
14. 输出摘要
展示：
- 运行模式
.eo-project.json 路径和内容- 项目管理侧骨架结构
- 代码侧骨架结构
- 软链 / gitignore / agent 配置 / 看板 状态
输出
- 代码仓库：
.eo-project.json + eo-doc/ 最小骨架 + agent 配置注入（+ 可选软链）
- 项目管理侧：
<project_root>/ 含 roadmap.md / log.md / backlog.md（+ 可选 phases/）
- 看板（可选）：
{{kanban_path}} 对应条目
约束
.eo-project.json 是所有 eo- skill 的启动前置*。本 skill 的核心产出- 按需目录（phases / decisions / lessons / brainstorm / docs）init 时不预建，由对应 skill 首次写入时 lazy 创建
- 项目名用用户给的原始名称，不转换
- 原始 PRD/MVP 若提供，存到
<project_root>/docs/（lazy 建）
- 活跃项目上限 3 个（仅看板维护时检查）
- 软链仅 vault 模式 +
create_symlink: true 才建
.eo-project/ 默认进 .gitignore；用户可当场覆盖- agent 配置注入使用
<!-- eo-project:start/end --> 标记，幂等可重复执行
