aif-roadmap

路线图 - 战略项目规划

创建并维护包含主要里程碑的高层级项目路线图。

工作流

步骤 0：加载项目上下文

首先： 如果 .ai-factory/config.yaml 存在，请读取它以解析：

• 路径： paths.description、paths.architecture、paths.rules_file、paths.roadmap、paths.research 和 paths.rules；推导 research_bundles_dir = <paths.research 的父目录>/research/
• 语言： language.ui 用于提示词，language.artifacts 用于生成内容

如果 config.yaml 不存在，则使用默认值：

• 路径：所有制品均使用 .ai-factory/
• 语言：en（英语）

如果 .ai-factory/DESCRIPTION.md 存在，请读取（使用 config 中指定的路径）以了解：

• 技术栈（语言、框架、数据库、ORM）
• 项目架构和约定
• 非功能性需求

如果已解析的架构制品存在，请读取（paths.architecture，默认值：.ai-factory/ARCHITECTURE.md）以了解：

• 选定的架构模式和文件夹结构
• 模块边界和通信模式

可选：读取一个相关的研究来源： 配置的 paths.research 文件，或一个主题明确匹配且处于活跃状态的直接子级研究包。仅当其 INDEX.md 中 `` 恰好出现一次、声明 Status: active，并在 ## Artifact Index 下链接到其 RESEARCH.md 时，才将其视为活跃。使用其 Active Summary 获取战略背景；仅在需要了解依据时，才读取可选的 C4/ADR/依赖制品。不要合并无关主题，也不要将实现层面的笔记当作里程碑。

读取 .ai-factory/skill-context/aif-roadmap/SKILL.md——如果该文件存在，则必须读取。

该文件包含 /aif-evolve 根据补丁、代码库约定和技术栈分析积累的项目专属规则。这些规则针对当前项目进行了定制。

如何应用 skill-context 规则：

• 将其视为本技能通用指令的项目级覆盖规则
• 如果 skill-context 规则与本 SKILL.md 中的通用规则冲突，以 skill-context 规则为准（更具体的上下文优先——这与嵌套 CLAUDE.md 文件的原则相同）
• 如果不存在冲突，则同时应用两者：SKILL.md 中的通用规则和 skill-context 中的项目规则
• 即使 skill-context 规则看起来与本技能的默认规则矛盾，也不要忽略它们——这些规则是因为项目实践证明默认规则不足而制定的
• 关键： skill-context 规则适用于本技能的所有输出，包括 ROADMAP.md 模板。本 SKILL.md 中的模板是基础结构。如果 skill-context 规则要求“路线图必须包含 X”或“里程碑必须包含 Y”，则必须相应扩展模板。生成违反 skill-context 规则的路线图属于错误。

强制要求： 生成任何输出制品后，均须依据所有 skill-context 规则进行验证。如果违反任何规则，须在向用户展示前修正输出。

步骤 1：确定模式

如果参数为 check → 模式 3：检查进度（需要已解析的路线图路径）

否则，检查已解析的路线图路径是否存在（paths.roadmap，默认值：.ai-factory/ROADMAP.md）：

• 不存在 → 模式 1：创建路线图
• 存在 → 模式 2：更新路线图

---

模式 1：创建路线图（首次运行）

1.1：收集输入

如果用户提供了参数（愿景／描述）：

• 将其作为里程碑的主要输入

如果没有提供参数：

• 交互式询问：

AskUserQuestion: What are the major goals for this project?

Options:
1. Let me describe the vision
2. Analyze codebase and suggest milestones
3. Both — I'll describe, you'll add what's missing

根据选择：

• “分析代码库并建议里程碑” → 继续执行步骤 1.2
• “让我描述愿景”或“二者都选” → 收集用户描述（如果选择“二者都选”，还要在步骤 1.2 中添加代码库分析），然后提出后续问题：

AskUserQuestion: Any priorities or deadlines?

Options:
1. Yes, let me specify
2. No, just order by logical sequence
3. Skip — I'll reprioritize later

1.2：探索代码库

扫描项目以了解已构建的内容：

• 使用 Glob 查看项目结构（关键目录、模块）
• 使用 Grep 查找已实现的功能（路由、模型、服务）
• 查看 git 日志中的已完成工作：git log --oneline -20

1.3：生成 ROADMAP.md

创建已确定的路线图产物（默认路径：.ai-factory/ROADMAP.md），格式如下：

# Project Roadmap

> <project vision — one-liner from DESCRIPTION.md or user input>

## Milestones

- [ ] **Milestone Name** — short description of what this achieves
- [ ] **Milestone Name** — short description of what this achieves
- [x] **Milestone Name** — short description (already done based on codebase analysis)

## Completed

| Milestone | Date |
|-----------|------|
| Milestone Name | YYYY-MM-DD |

里程碑规则：

• 每个里程碑都是一个高层目标，而非细化任务（细化任务属于 /aif-plan）
• 5-15 个里程碑最合适——更少会过于笼统，更多则会过于细化
• 按逻辑顺序排列（先列出依赖项）
• 将已完成的里程碑标记为 [x]，并添加到“已完成”表格中
• 对于判定为已完成的里程碑，使用今天的日期

1.4：向用户确认

显示生成的路线图并询问：

AskUserQuestion: Here's the proposed roadmap. What would you like to do?

Options:
1. Looks good — save it
2. Add more milestones
3. Remove/modify some milestones
4. Rewrite — let me give better input

如果用户要求更改，则应用更改，然后保存到已确定的路线图路径。

---

模式 2：更新路线图（后续运行）

2.1：读取当前状态

• 读取已确定的路线图路径
• 读取 .ai-factory/DESCRIPTION.md（使用配置中的路径）以获取上下文
• 简要探索代码库，检查上次更新后有哪些变化

2.2：确定操作

如果用户提供了参数（新里程碑／更改）：

• 直接应用所请求的更改

如果没有提供参数：

• 分析当前状态并提供选项：

AskUserQuestion: What would you like to do with the roadmap?

Options:
1. Review progress — check what's done, mark completed milestones
2. Add new milestones
3. Reprioritize — reorder existing milestones
4. Rewrite — major revision of the roadmap

2.3：审查进度（如果已选择）

• 扫描代码库，查找里程碑已完成的证据
• 对每个未勾选的里程碑，检查相关工作是否看起来已完成
• 提议标记已完成的里程碑：

These milestones appear to be done:
- **Milestone Name** — [evidence: files exist, routes implemented, etc.]

Mark them as completed?

如果确认：

• 在“里程碑”部分将 - [ ] 改为 - [x]
• 在“已完成”表格中添加条目，并填写今天的日期
• 将已完成的里程碑移到未勾选项下方（也可以保留原位，由用户决定）

2.4：添加新里程碑（如果已选择）

• 请用户描述新里程碑
• 按逻辑顺序将其插入现有里程碑中
• 更新已确定的路线图路径

2.5：重新排序优先级（如果已选择）

• 显示当前顺序
• 请用户提供新顺序，或描述优先级调整
• 在已确定的路线图路径中重新排列里程碑

2.6：保存更改

将所有修改更新到已确定的路线图路径。

显示摘要：

## Roadmap Updated

Total milestones: N
Completed: X/N
Next up: **Milestone Name**

To start working on the next milestone:
/aif-plan <milestone description>  → creates a plan and optional branch/worktree flow
/aif-implement                     → executes the plan

---

模式 3：检查进度（/aif-roadmap check）

自动扫描——分析代码库并标记已完成的里程碑，无需交互式提问。

要求已确定的路线图路径存在。如果不存在——告知用户先运行 /aif-roadmap。

3.1：读取路线图和项目上下文

• 读取已确定的路线图路径
• 读取 .ai-factory/DESCRIPTION.md（使用配置中的路径）以了解技术栈背景

3.2：分析每个未勾选的里程碑

对每个 - [ ] 里程碑：

• 确定哪些证据可以证明其已完成（文件、路由、模型、配置、测试）
• 使用 Glob 和 Grep 搜索这些证据
• 使用 git log --oneline --all -30 查找相关提交
• 评分：已完成（有有力证据）、部分完成（已开始部分工作）、尚未开始

3.3：报告发现

## Roadmap Progress Check

✅ Done (ready to mark):
- **User Authentication** — found: src/auth/, JWT middleware, login/register routes
- **Database Setup** — found: migrations/, models/, seed scripts

🔨 In Progress:
- **Payment Integration** — found: src/payments/ exists but Stripe webhook handler missing

⏳ Not Started:
- **Admin Dashboard**
- **Email Notifications**

Mark completed milestones? (2 milestones)

3.4：应用更改（如果已确认）

• 将已完成的里程碑标记为 [x]
• 在“已完成”表格中添加条目，并填写今天的日期
• 保持部分完成和尚未开始的里程碑不变

显示更新后的摘要：

Completed: X/N milestones
Next up: **Milestone Name**

---

ROADMAP.md 格式

# Project Roadmap

> <project vision — one-liner>

## Milestones

- [ ] **Name** — short description
- [ ] **Name** — short description
- [x] **Name** — short description

## Completed

| Milestone | Date |
|-----------|------|
| Name | YYYY-MM-DD |

关键规则

1. 里程碑处于高层级——每个里程碑代表一项主要功能或能力，而不是一项任务
2. ROADMAP.md 是事实来源——修改前务必先阅读
3. 绝不悄悄移除里程碑——移除前务必先征得用户确认
4. 已完成表格用于记录历史——每个已勾选的里程碑都要填写日期
5. 不得进行实现——此技能只负责规划；使用 /aif-plan 启动功能，并使用 /aif-implement 执行
6. 所有权边界——此命令负责路线图的结构和内容；只有在实现证据明确时，/aif-implement 才能将里程碑标记为已完成