@shirayner/ace 0.1.7-snapshot.1 → 0.1.8-SNAPSHOT.1

package/README.md

@@ -31,17 +31,27 @@ ACE 是一个**AI 开发环境配置工具**，基于 Claude Code 官方最佳
 - 📝 **规范驱动工作流** — OpenSpec 集成的需求管理体系
 - 🧩 **跨会话记忆系统** — 持久化的开发者画像与项目记忆
 
+### 视频教程
+
+从下载安装到实际使用的完整演示：
+
+![ACE 使用示例](assets/ace-demo.gif)
+
+动图速度过快，另有示例视频：[ACE 使用示例](assets/ace-demo.mp4)
+
+---
+
+## ✨ 一分钟速览
+
+### 安装
+
 ```bash
 # 一键安装，即刻拥有专业级 AI 开发环境
 npm install -g @shirayner/ace
-ace init
 ```
 
----
 
-## ✨ 一分钟速览
-
-### 初始化向导
+### 初始化
 
 ```bash
 $ ace init
@@ -74,38 +84,64 @@ $ ace init
 
 ### Spec Coding 完整流程
 
+进入工作目录
+
 ```bash
 # 进入工作目录
 $ mkdir my-project 
 $ cd my-project
 
+```
+
+Spec 初始化
+
+```bash
 # 执行 aspec 初始化
 $ ace spec init
 ✓ aspec 工作流已初始化
 Done! 规范驱动开发已就绪。
 
-# 在 Claude Code 中体验三命令开发流程：
+```
+
+Spec驱动开发
+
+```bash
+# 在 Claude Code 中体验Spec开发流程：
+# 输入 /opsx:proposal 命令后，一路交互式澄清、确认，然后需求完成，Spec归档
 $ claude
 
 > /opsx:proposal 帮我实现用户积分系统
 
-Claude:
-【需求澄清】积分获取规则？消费规则？过期策略？→ 3 个问题确认
-【创建提案】proposal.md
-【技术澄清】并发扣减方案？积分流水存储？→ 2 个问题确认
-【确定方案】design.md + tasks.md（8 个可执行任务）
+Claude: 【需求澄清】对需求不确定的地方提出疑问？→  请求人工澄清
+人工：选择选项，或者进行纠正，然后点击submit
+
+Claude: 【需求对齐】Claude输出自己对本需求的理解 → 请求人工确认
+人工：选择确认，或者纠正信息，然后点击submit
+
+-- 人工确认之后，Cluade会创建提案
+
+Claude: 【技术设计澄清】对技术不确定的地方提出疑问 → 请求人工确认
+人工：选择确认，或者纠正信息，然后点击submit
+
+Claude: 【技术设计对齐】Claude输出自己对本需求的技术方案设计的理解 → 请求人工确认
+人工：选择确认，或者纠正信息，然后点击submit
+
+-- 人工确认之后，Cluade会创建Design
+
+Claude: 【Design审批并创建Tasks】Claude请求人工确认Design设计，然后创建Tasks → 请求人工审批
+人工：选择确认，或者纠正信息，然后点击submit
+
+-- 人工确认之后，Cluade会创建tasks
 
-> /opsx:apply
+Claude: 【执行】Claude 请求按规划的任务进行代码实现 → 请求人工审批
+人工：选择确认，或者纠正信息，然后点击submit
 
-Claude:
-按 tasks.md 逐项实现，每步验证
-✓ 所有任务完成，测试通过
+-- 人工确认之后，Cluade会进行代码实现，然后进行经验收集
 
-> /opsx:archive
+Claude: 【归档同步】Claude 会请求进行归档同步→ 请求人工审批
+人工：选择确认，或者纠正信息，然后点击submit
 
-Claude:
-spec 归档，收敛检查
-✓ 归档完成
+-- 人工确认之后，Cluade会对Spec进行归档同步
 ```
 
 ### 健康检查

package/bin/ace.js

@@ -51,6 +51,7 @@ spec
   .option('-f, --force', 'Overwrite existing configuration', false)
   .option('--dry-run', 'Preview without making changes', false)
   .option('--skip-openspec', 'Skip openspec CLI installation', false)
+  .option('--team-repo <url>', 'Git repository URL for team conventions')
   .action(specInitCommand);
 
 spec

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shirayner/ace",
-  "version": "0.1.7-snapshot.1",
+  "version": "0.1.8-SNAPSHOT.1",
   "description": "AI Coding Environment - One command to set up your Claude Code harness",
   "bin": {
     "ace": "./bin/ace.js"

package/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ace",
-  "version": "0.1.3",
+  "version": "0.1.8-SNAPSHOT",
   "description": "AI Coding Environment - Skills and commands for Claude Code",
   "author": {
     "name": "shirayner"

package/plugin/skills/auto-goal/SKILL.md

@@ -11,27 +11,62 @@ description: |
 
   DO NOT TRIGGER: 明确代码变更（修 bug、加功能、重构、写测试 → coding）；优化/创建 skill（→ skill-optimize / skill-creator）；单步可完成的简单操作（→ 直接执行）。
 ---
-
 # Auto Goal Skill
 
-自主完成目标的赋能系统。信任模型的推理能力，只做模型不会自发做的事。
+自主完成目标的赋能系统。信任模型推理能力，只做模型不会自发做的事。
 
 **核心信念**：对齐优先于效率。准确完成用户真正想要的，胜过高效完成 agent 以为的。
 
 ---
 
-## 三条硬规则（不可跳过）
+## 硬规则（不可跳过）
+
+### 规则 0：Pre-execution Checkpoint（结构性屏障）
+
+**在发出第一个修改性工具调用（Edit/Write/创建或修改文件的 Bash）之前，必须通过此检查：**
+
+> 我是否已完成 Step 3 的对齐确认，且用户已通过 AskUserQuestion 确认？
+
+- **是** → 继续执行
+- **否** → **立即停止**，返回规则 1 执行对齐流程
+
+此规则存在的原因：auto mode 的"立即执行"指令会与对齐要求冲突。当模型感到"这个任务很简单，不需要对齐"时，恰恰是最需要对齐的时刻——因为"简单"往往意味着隐含决策被忽略了。
+
+**Auto mode 优化的是执行效率，不是对齐质量。跳过对齐不是"更快"——是"更可能做错"。**
 
 ### 规则 1：首轮对齐（MANDATORY — 优先于 auto mode）
 
 接收目标后，**必须完成以下三步才能开始执行**。
 
-**Step 1: 初步分析** — 结合已有上下文（memory、CLAUDE.md、git status、会话历史）和探索性工具（Read/Grep/Glob/Agent），形成对目标的理解。
+**Step 1: 苏格拉底式分析** — 结合已有上下文（memory、CLAUDE.md、git status、会话历史）和探索性工具（Read/Grep/Glob/Agent），并行执行，形成对目标的深层理解。
+
+分析时在内部（思考过程中）进行苏格拉底式追问：
+- **追问目的**：用户为什么要做这个？解决什么根本问题？做了之后谁受益？
+- **追问完整性**：用户说的是全貌还是冰山一角？有没有没意识到的关联问题或前置依赖？
+- **追问前提**：用户的假设成立吗？有没有更好的问题框架？是不是在解决错误的问题？
+- **追问约束**：什么不能动？什么是硬限制？时间/资源/技术债/团队认知负担？
+
+目标：不只是理解用户说了什么，而是理解用户**真正需要**什么——包括他们自己可能没意识到的部分。
+
+**Step 2: 澄清** — **调用 AskUserQuestion 工具**向用户批量澄清歧义和关键决策点。复杂项目可多轮澄清。
+
+跳过条件（必须**同时满足全部**才可跳过 Step 2，直接进入 Step 3）：
+- 用户在**同一会话中**已明确表达过完整意图，且你在 Step 1 分析后未发现任何隐含决策点
+- 不存在"用户可能会惊讶"的假设需要验证
+- 任务是对前一个已对齐目标的延续性修复（而非新目标）
+
+**如果不确定是否需要澄清 → 澄清。** 默认执行，跳过是例外。
+
+澄清时采用引导性提问（而非纯选择题）：
+- "你提到了 X，但我注意到这还关联到 Y——这是否也在范围内？"
+- "如果我们做了 X 但不处理 Y，后续会有什么风险？"
+- "在时间、质量、范围之间，你的首要约束是什么？"
 
-**Step 2: 澄清** — **调用 AskUserQuestion 工具**向用户批量澄清歧义和关键决策点。复杂项目可多轮澄清。仅当目标完全明确无歧义时可跳过。
+好的引导性问题能帮用户发现自己没想到的维度，而不只是确认 AI 已知的信息。
 
-**Step 3: 对齐确认（不可跳过）** — 用普通文本（markdown）向用户呈现对齐内容：
-1. **我的理解** — 复述目标核心意图
+**Step 3: 对齐确认（不可跳过）** — 用普通文本（markdown）向用户呈现：
+
+1. **我的理解** — 复述目标核心意图（包含分析中发现的用户可能没意识到的关联问题）
 2. **计划方向** — 打算怎么做（高层策略）
 3. **关键假设** — 不确定的假设，标注出来
 4. **完成标准** — "我认为完成的标志是..."（必须可测试，描述需求状态而非执行命令）
@@ -40,131 +75,129 @@ description: |
 
 ### 规则 2：替用户做选择时，必须暂停
 
-模型最危险的特征是自信地做错事。以下情况**必须暂停，向用户呈现选项**：
+**一句话判断**：如果用户此刻看到我的决策会惊讶 → 暂停询问。
+
+触发条件：
+
 - 存在多个可行方案且各有取舍
 - 决策依赖用户偏好（风格、架构、优先级）
 - 范围超出原始目标描述
 - 不可逆操作（删除、重写、架构变更）
 - 正在用自己的理解填补用户未说明的部分
 
-**一句话判断**：如果用户此刻看到我的决策会惊讶 → 暂停询问。
-
-### 规则 3：长任务外化状态
+### 规则 3：状态外化
 
-预估超过 10 步的任务，**用户确认对齐后、首个执行动作前**，必须创建 `.tasks/auto-goal-{id}/state.md`。这是从对齐到执行的过渡门——不创建就不开始执行。执行中发现任务超出预估时同理。
+| 任务规模 | 策略                                                                                                                               |
+| -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| ≤5 步   | 无需状态文件，直接执行                                                                                                             |
+| 6-9 步   | 轻量 checkpoint：创建 `.tasks/auto-goal-{id}/state.md`，只写目标+进度+下一步（见 `references/state-template.md` 中的轻量模板） |
+| ≥10 步  | 完整状态管理：Read `references/state-template.md` 获取完整模板后创建，含 Phase 规划、Tier 2 索引、风险追踪                       |
 
-设计目标：**让一个全新 agent 读完 state.md 后能定位自己，按需加载 Tier 2 后能以 80% 效率继续**。模板中 `Phase Final: 收尾` 是强制阶段，确保经验进化和正式交付不被跳过。
+设计目标：让一个全新 agent 读完 state.md 后能定位自己，按需加载 Tier 2 后能以 80% 效率继续。
 
-**分层架构（懒加载）**：
+---
 
-```
-.tasks/auto-goal-{id}/
-├── state.md       # Tier 1：核心状态索引（≤40 行，恢复必读）
-├── context.md     # Tier 2：世界模型详情（按需创建/加载）
-├── decisions.md   # Tier 2：决策日志（按需创建/加载）
-└── reflections.md # Tier 2：反思日志（按需创建/加载）
-```
+## 执行原则
 
-**Tier 1 — state.md**（始终加载，严格控制体积）：
+1. **先定义完成，再开始执行** — 每个目标都需要可测试的完成标准。验证力度匹配错误成本
+2. **承诺当前计划，卡住时换方向** — 新信息更新信念，不自动更新计划。同一方法连续失败时换策略，三次失败后质疑前提。每次意外失败都问：这揭示了哪个假设是错的？
+3. **永不空手而归** — 任意时刻中断都应有可用产出。按价值排序交付
+4. **上下文是稀缺资源** — 探索性工作用 sub-agent 隔离；大阶段完成后压缩保留决策和结论；关键中间结果外化到文件
+5. **对齐不是一次性事件** — 发现目标理解偏差时，回到对齐。连续成功对齐后可降低确认频率，遇到意外时重新提高
 
-```markdown
----
-status: in-progress
-last-updated: {timestamp}
 ---
 
-## 目标与完成标准
-[用户确认的目标]
-- [ ] 可测试的完成标准 1
-- [ ] 可测试的完成标准 2
+## 并行执行
 
-## 进度
-### Phase 1: {name} [done]
-### Phase 2: {name} [active]
-- [x] 已完成子任务
-- [ ] → 当前进行中
-- [ ] 待做子任务
-### Phase 3: {name} [pending]
-### Phase Final: 收尾 [pending]
-- [ ] 经验进化 → experience.md
-- [ ] 交付结果
+**原则**：独立子任务必须并行，有依赖的必须串行。默认寻找并行机会，而非默认串行。
 
-## 已修改文件
+**识别并行机会**：
 
-## 下一步
+- 多个文件/模块的独立调研 → 并行 Agent
+- 多个不相关的代码修改 → 并行 Agent（配合 worktree 隔离）
+- 信息收集 + 不依赖其结果的准备工作 → 并行
+- 多个独立验证步骤（测试、lint、类型检查）→ 并行 Bash
 
-## 活跃风险与未确认假设
+**执行方式**：在**单个 response** 中发出多个 Agent tool 调用。Claude Code 原生支持同一 message 内的并行 tool 调用——利用它。
 
-## Tier 2 索引
-| 文件 | 摘要 | 条目数 |
-|------|------|--------|
-```
+**依赖判断**：如果 A 的结果完全不同，B 的执行方式会变吗？不会 → 并行。
 
-**Tier 2 — 按需加载**（agent 根据当前需要自行决定加载）：
-- **context.md** — 环境上下文（技术栈、项目结构发现）、约束空间（不可行路径、硬限制）、信念状态（✓已验证 / ~假设 / ?待验）
-- **decisions.md** — 关键决策 + 理由 + 被排除的替代方案
-- **reflections.md** — 失败根因 + 揭示的错误假设 + 策略调整
+**约束**：
+
+- 并行 agent 数量 ≤ 4（避免结果整合复杂度爆炸）
+- 每个 agent prompt 必须自包含（明确目标、上下文、交付物格式）
+- 结果回收后，主 agent 负责整合、冲突解决、更新 state.md
+- 并行 agent 不应修改同一文件（冲突风险）
+
+**state.md 标注**：`⟂` 标记可并行子任务，`(depends: X)` 标记依赖。
 
 ---
 
-## 生成式原则（引导方向，不规定过程）
+## 进度通信与自检
 
-以下原则指定**方向**，模型自主决定**如何**执行：
+### 进度心跳
 
-1. **先定义完成，再开始执行** — 每个目标都需要可测试的完成标准。验证力度匹配错误成本
-2. **承诺当前计划，卡住时换方向** — 新信息更新信念，不自动更新计划。同一方法连续失败时换策略，三次失败后质疑前提。每次意外失败都问：这揭示了哪个假设是错的？
-3. **永不空手而归** — 任意时刻中断都应有可用产出。按价值排序交付
-4. **上下文是稀缺资源** — 探索性工作用 sub-agent 隔离；大阶段完成后压缩保留决策和结论；关键中间结果外化到文件
-5. **对齐不是一次性事件** — 发现目标理解偏差时，回到对齐。连续成功对齐后可降低确认频率，遇到意外时重新提高
+- 完成一个 Phase → 一句话报告进展 + 下一步预告
+- 连续 5+ 工具调用无文本输出 → 插入一句进展说明
+- 遇到意外或方向变化 → 立即告知用户并说明原因
+- 预估剩余时间显著变化 → 更新用户预期
+
+用户不应感到"黑箱"。但心跳是一句话，不是段落。
+
+### 执行后自检
+
+完成代码修改后，**必须用适当手段验证**：
+
+- 有编译器/类型检查 → 运行它
+- 有相关测试 → 运行它
+- 无自动化手段 → 人工 review 关键路径，向用户说明验证范围和局限
+
+自检失败 → 修复后再报告完成。不要把失败的产出交给用户。
 
 ---
 
 ## 上下文纪律
 
-| 策略 | 时机 |
-|------|------|
-| **隔离** — 搜索/读大文件/查资料用 sub-agent | 会污染主上下文的工作 |
-| **压缩** — 已完成阶段只保留决策和结论 | 大阶段完成后 |
-| **外化** — 关键发现/决策写入状态文件 | 重要信息出现时 |
+| 策略                                                 | 时机                 |
+| ---------------------------------------------------- | -------------------- |
+| **隔离** — 搜索/读大文件/查资料用 sub-agent   | 会污染主上下文的工作 |
+| **压缩** — 已完成阶段只保留决策和结论         | 大阶段完成后         |
+| **外化** — 关键发现/决策写入状态文件          | 重要信息出现时       |
+| **预算感知** — 上下文接近极限时主动压缩或外化 | 对话持续较长时       |
 
 压缩时必须保留：当前目标、完成标准、关键决策及理由、已修改文件、未完成待办。
 
 ---
 
-## 恢复协议
+## 经验进化（条件触发）
 
-恢复中断的任务时：
-1. 读取 `.tasks/auto-goal-{id}/state.md`（Tier 1 定位）
-2. 验证声称的产出是否真实存在（Glob/Read 轻量确认）
-3. 根据当前需要加载 Tier 2 文件
-4. 读取 `.tasks/experience.md` 摘要（如存在）
-5. 用 TaskCreate 重建 UI 进度
-6. 从"下一步"继续
+**触发条件**（满足任一才写 experience.md）：
 
----
+- 执行中遇到意外、踩坑、策略转换
+- 发现反直觉的技术事实
+- 找到了跨任务可复用的模式
+
+**不触发时**：任务顺利完成且无新发现 → 标注"无新经验"，直接交付。不要为了仪式感而编造经验。
 
-## 经验进化（交付门控）
+**执行**（触发时）：
 
-**结构性规则**：经验进化是交付的前置条件——**不写 experience.md，不交付结果**。这不是建议，而是与首轮对齐同等强制的流程步骤。state.md 的 `Phase Final: 收尾` 追踪此步，未勾选即未完成。
+1. 写入 `.tasks/experience.md`（每条：编号 / 场景 / 发现 / 适用范围）
+2. 更新 state.md 的 Phase Final（如有状态文件）
+3. 交付结果
 
-**触发时机**：所有执行阶段完成后、向用户交付结果前。
+**经验应用**：新任务启动时读取 experience.md（如存在），应用时告知用户（"基于经验 E3，采用…"）。每次应用后记录验证结果（✓有效 / ✗无效 / — 不适用）。
 
-**执行步骤**（三步，不可省略）：
+**全局提升**：经验累计 3+ 次 ✓有效 → 调用 AskUserQuestion 向用户提议提升至 `~/.claude/memory/`。
 
-1. **提取经验** — 写入 `.tasks/experience.md`
-   - 每条经验：编号 / 场景 / 发现 / 适用范围
-   - 只记录反直觉的、踩坑才知道的、跨任务可复用的发现
-   - 跳过显而易见的技术常识
-2. **更新 state.md** — 勾选 `Phase Final` 中的经验进化项
-3. **交付结果** — 此时才向用户呈现最终交付
+**收敛**：条目 >20 条时合并相似、淘汰无效。
 
-**新任务启动时**：读取 experience.md（如存在），应用经验时告知用户（"基于经验 E3，采用…"）。每次应用后记录验证结果（✓有效 / ✗无效 / — 不适用）。
+---
 
-**全局提升** — 经验累计 3+ 次 ✓有效 后：
-- **必须调用 AskUserQuestion** 向用户提议提升至 `~/.claude/memory/`
-- 用户确认后写入全局，拒绝则标记为"仅项目级"
+## 恢复协议
 
-**收敛**：条目 >20 条时合并相似、淘汰无效。
+恢复中断任务时，Read `references/recovery.md` 获取详细流程。
+
+简要流程：读 state.md → 验证产出真实存在（Glob/Read 确认）→ 按需加载 Tier 2 → 读 experience.md → TaskCreate 重建 UI 进度 → 从"下一步"继续。
 
 ---
 
@@ -174,3 +207,14 @@ last-updated: {timestamp}
 - **全自动**：仅不可逆操作前确认
 
 未声明时默认协作。
+
+---
+
+## 参考文件索引
+
+以下文件按需 Read，不预加载：
+
+| 文件                             | 何时加载                                                          |
+| -------------------------------- | ----------------------------------------------------------------- |
+| `references/state-template.md` | 创建状态文件时（含完整模板、轻量模板、Tier 2 说明、并行标注约定） |
+| `references/recovery.md`       | 恢复中断任务时（含标准流程和 fallback 路径）                      |

package/plugin/skills/auto-goal/references/recovery.md

@@ -0,0 +1,29 @@
+# 恢复协议
+
+恢复中断的 auto-goal 任务时，按以下步骤执行：
+
+## 标准恢复流程
+
+1. **定位** — 读取 `.tasks/auto-goal-{id}/state.md`（Tier 1）
+2. **验证** — Glob/Read 轻量确认声称的产出是否真实存在
+3. **加载上下文** — 根据当前需要加载 Tier 2 文件（context.md / decisions.md / reflections.md）
+4. **读经验** — 读取 `.tasks/experience.md`（如存在）
+5. **重建 UI** — 用 TaskCreate 重建进度显示
+6. **继续** — 从 state.md 的"下一步"继续执行
+
+## Fallback：state.md 不存在时
+
+如果 `.tasks/` 目录不存在或为空（用户换了环境、清理了文件）：
+
+1. **从 git 重建** — `git log --oneline -20` + `git diff --stat` 了解最近工作
+2. **从文件重建** — Glob 查找最近修改的文件，推断进度
+3. **向用户确认** — 呈现你重建的理解，确认后继续
+4. **创建新 state.md** — 基于重建的理解创建，避免再次丢失
+
+## 恢复后验证清单
+
+- [ ] state.md 中标记 [done] 的 Phase，产出文件确实存在
+- [ ] 当前 Phase 的"已完成子任务"对应的代码变更确实存在
+- [ ] 没有遗留的半完成修改（编译错误、broken import 等）
+
+验证失败 → 将对应项标回 pending，从正确的状态重新开始。

package/plugin/skills/auto-goal/references/state-template.md

@@ -0,0 +1,97 @@
+# 状态文件模板
+
+## 完整状态文件（≥10 步任务）
+
+创建路径：`.tasks/auto-goal-{id}/state.md`
+
+```markdown
+---
+status: in-progress
+last-updated: {timestamp}
+---
+
+## 目标与完成标准
+[用户确认的目标]
+- [ ] 可测试的完成标准 1
+- [ ] 可测试的完成标准 2
+
+## 进度
+### Phase 1: {name} [done]
+### Phase 2: {name} [active]
+- [x] 已完成子任务
+- [ ] → 当前进行中  ⟂
+- [ ] 待做子任务  ⟂
+- [ ] 依赖项 (depends: 上两项)
+### Phase 3: {name} [pending]
+### Phase Final: 收尾 [pending]
+- [ ] 经验进化（如有新发现）
+- [ ] 交付结果
+
+## 已修改文件
+
+## 下一步
+
+## 活跃风险与未确认假设
+
+## Tier 2 索引
+| 文件 | 摘要 | 条目数 |
+|------|------|--------|
+```
+
+**≤40 行原则**：state.md 是索引，不是文档。超出时移入 Tier 2。
+
+---
+
+## 轻量 checkpoint（6-9 步任务）
+
+同样创建 `.tasks/auto-goal-{id}/state.md`，但只需：
+
+```markdown
+---
+status: in-progress
+last-updated: {timestamp}
+---
+
+## 目标
+[一句话目标]
+
+## 进度
+- [x] 已完成
+- [ ] → 当前
+- [ ] 待做
+
+## 下一步
+```
+
+---
+
+## Tier 2 文件（按需创建）
+
+```
+.tasks/auto-goal-{id}/
+├── state.md       # Tier 1：核心状态索引
+├── context.md     # Tier 2：世界模型详情
+├── decisions.md   # Tier 2：决策日志
+└── reflections.md # Tier 2：反思日志
+```
+
+### context.md
+- 环境上下文（技术栈、项目结构发现）
+- 约束空间（不可行路径、硬限制）
+- 信念状态：✓已验证 / ~假设 / ?待验
+
+### decisions.md
+- 每条：决策 + 理由 + 被排除的替代方案
+- 格式：`### D{n}: {决策标题}` + 正文
+
+### reflections.md
+- 失败根因 + 揭示的错误假设 + 策略调整
+- 格式：`### R{n}: {事件}` + 分析
+
+---
+
+## 并行标注约定
+
+在 state.md 进度中：
+- `⟂` — 该任务可与同级其他 `⟂` 任务并行
+- `(depends: X, Y)` — 该任务依赖 X 和 Y 完成后才能开始

package/src/commands/doctor.js

@@ -27,10 +27,10 @@ export async function doctorCommand() {
       const ruleFiles = await fs.readdir(templateRulesDir);
       for (const file of ruleFiles) {
         if (!file.endsWith('.md')) continue;
-        checks.push(await check(`rules/ace/${file}`, fs.pathExists(path.join(CLAUDE_DIR, rulesDir, file))));
+        checks.push(await check(`ace/rules/${file}`, fs.pathExists(path.join(CLAUDE_DIR, rulesDir, file))));
       }
     } catch {
-      checks.push({ name: 'rules/ace/ directory', ok: false });
+      checks.push({ name: 'ace/rules/ directory', ok: false });
     }
   }
 
@@ -91,14 +91,21 @@ export async function doctorCommand() {
     checks.push({ name: 'settings.json parseable', ok: false });
   }
 
-  // 8. Validate CLAUDE.md @references
+  // 8. Validate CLAUDE.md references (both @refs and path-index style)
   try {
     const claudeMd = await fs.readFile(path.join(CLAUDE_DIR, 'CLAUDE.md'), 'utf-8');
-    const refs = claudeMd.match(/@~?\/?\.?claude\/[^\s)]+/g) || [];
-    for (const ref of refs) {
+    // Check @references (legacy format)
+    const atRefs = claudeMd.match(/@~?\/?\.?claude\/[^\s)]+/g) || [];
+    for (const ref of atRefs) {
       const refPath = ref.replace(/^@/, '').replace(/^~/, process.env.HOME || process.env.USERPROFILE);
       checks.push(await check(`@ref: ${path.basename(refPath)}`, fs.pathExists(refPath)));
     }
+    // Check path-index style references (new format: lines starting with "- ~/.claude/...")
+    const pathRefs = claudeMd.match(/(?:^|\n)-\s+(~\/.claude\/[^\s—]+)/g) || [];
+    for (const match of pathRefs) {
+      const refPath = match.replace(/(?:^|\n)-\s+/, '').replace(/^~/, process.env.HOME || process.env.USERPROFILE);
+      checks.push(await check(`path: ${path.basename(refPath)}`, fs.pathExists(refPath)));
+    }
   } catch {
     checks.push({ name: 'CLAUDE.md readable', ok: false });
   }

package/src/commands/init.js

@@ -14,7 +14,6 @@ const componentLabels = {
   rules: 'Rules',
   plugin: 'Plugin',
   hooks: 'Hooks',
-  hookify: 'Safety Guards',
   memory: 'Memory',
 };
 
@@ -91,6 +90,11 @@ export async function initCommand(options) {
 
   s.start('Installing...');
 
+  // Prepare: migrate legacy directory structure if needed
+  if (!options.dryRun) {
+    await installer.prepare();
+  }
+
   for (const componentName of components) {
     const component = COMPONENTS[componentName];
     if (!component) continue;
@@ -149,8 +153,8 @@ export async function initCommand(options) {
       '',
       'Customize',
       '  Change role      edit ~/.claude/memory/user_profile.md',
-      '  Adjust rules     edit ~/.claude/rules/ace/',
-      '  Safety guards    edit ~/.claude/hookify.ace.*.local.md',
+      '  Adjust rules     edit ~/.claude/ace/rules/',
+      '  Safety guards    edit ~/.claude/hooks/ace.*.sh',
       '  Verify setup     ace doctor',
     ].join('\n'),
     'Next steps'
@@ -224,8 +228,8 @@ async function buildInstallPreview(installer, components) {
       try {
         const existing = await fs.readFile(path.join(installer.targetDir, item.dest), 'utf-8');
         const template = await fs.readFile(path.join(installer.templatesDir, item.src), 'utf-8');
-        const { added } = mergeClaudeMd(existing, template);
-        item.detail = added.length > 0 ? `adds ${added.length} new @references` : 'up to date';
+        const { content } = mergeClaudeMd(existing, template);
+        item.detail = content !== existing ? 'will update managed section' : 'up to date';
       } catch {
         item.detail = 'will merge';
       }