miniproject

由 Markdown 驱动的任务管理

这是一个简化且精简的项目管理 AI 记忆框架。

说明

重要 开始任何工作之前：

1. 使用辅助脚本查找记忆存储目录：

   MEMORY_DIR=$(/home/zenobius/.pi/agent/skills/projectmanagement/miniproject/scripts/miniproject.sh memory-dir)
   

   • 此脚本会自动处理 git worktree（在主 worktree 中查找 .memory/）
   • 如果目录不存在，请使用 --create 标志创建目录
2. 确保 .memory/ 中存在以下文件：

• 读取 .memory/todo.md、.memory/summary.md、.memory/knowledge.md 和 .memory/team.md（使用 grep/ls，而不是 glob 或 list 工具）
• 如果 .memory/ 缺少这些文件，则创建这三个文件。

3. 如果知识 codemap 不存在，则将其初始化：

• 创建文件 .memory/knowledge-codemap.md，其中包含一张 ASCII 状态机图，表示你对代码库的理解。
• 这对于理解项目结构和流程至关重要。

4. 开始任何工作之前，务必阅读 .memory/summary.md、.memory/todo.md 和 .memory/team.md。
5. 务必更新 .memory/team.md，注明正在处理的 epic 和阶段，以及负责人员（使用会话 ID 表示，而不是 Agent 名称）。
6. 每一步都务必及时更新 .memory/todo.md。
7. 完成任务或阶段后，务必提交更改。未经人工审核，绝对不要推送更改。
8. 严格遵循文件命名约定

规则 0：记忆存储

.memory/ 目录至关重要。所有项目管理和知识文件都必须存储在此处。

规则 0.1：定位记忆存储

使用辅助脚本查找记忆目录：

# Find the .memory directory (fails if not found)
MEMORY_DIR=$(/home/zenobius/.pi/agent/skills/projectmanagement/miniproject/scripts/miniproject.sh memory-dir)

# Find or create the .memory directory
MEMORY_DIR=$(/home/zenobius/.pi/agent/skills/projectmanagement/miniproject/scripts/miniproject.sh memory-dir)

此脚本会处理：

• Git worktree（在主 worktree 中查找 .memory/，而不是 worktree 检出目录）
• 常规 git 仓库
• 返回 .memory/ 的绝对路径

警告

.memory/ 可能被 gitignore，因此常规文件列表工具（Glob、List、ripgrep）可能无法按预期工作。

规则 0.2：保存记忆存储

编辑或创建 .memory/ 中的文件时，务必：

1. 使用 git 提交更改，并将记忆存储作为工作目录。

规则 1：文件名约定

只能创建严格遵循以下约定的文件名。

任何不符合约定的文件均无效，必须检查其用途，并采取以下措施之一：

1. 如果文件用途单一且符合约定，则重命名；或
2. 拆分为多个符合约定的文件；或
3. 如果其他文件已涵盖其内容，则删除。

保留无用或命名不当的文件会造成混乱，并降低记忆系统的效用。

指南

• [core] 将发现内容存储在 .memory/ 目录中
• [core] .memory/ 中的所有笔记都必须采用 Markdown 格式
• [core] 已归档的故事、任务和史诗应移至归档目录：.memory/archive/。
• [core] summary.md、todo.md、team.md、knowledge-*.md 是特殊文件，分别概述项目、待处理任务和团队角色。
• [core] .memory/knowledge-codemap.md 包含一个 ASCII 图，用状态机表示你对代码库的理解。
• [core] .memory/knowledge-data-flow.md 包含一个 ASCII 图，表示数据流
• [core] 可以创建其他 .memory/knowledge-*.md 文件来记录特定知识领域。
• [core] 除 .memory/summary.md 外，.memory/ 中的所有笔记都必须遵循文件名约定：.memory/<type>-<8_char_hashid>-<title>.md
• [core] <type> 的取值为：research、epic、task、story 和 learning
• [core] <8_char_hashid> 是文件唯一的 8 字符哈希标识符。
• [core] 初始化时，为现有代码库创建代码地图，并确保在 .memory/knowledge-codemap.md 中包含一个状态机 ASCII 图，表示你对代码库的理解。
• [core] 每个项目都必须先定义史诗，然后才能创建故事或任务
• [core] 始终及时更新 .memory/summary.md，记录当前史诗、活跃阶段和下一个里程碑。清理错误或过时的信息。
• [git] 完成任务或阶段后，始终提交更改。
• [git] 未经人工审核，绝不推送更改。
• [git] 提交更改时，遵循 Conventional Commits 规范。
• [git] 使用清晰的提交消息，并注明相关更改文件。

概念模型：故事、阶段和任务

理解这些工件之间的关系至关重要：

Epic (vision/goal)
 ├── Stories (WHAT - phase-agnostic requirements)
 │    └── Stories define what users need, independent of timeline
 │
 └── Phases (WHEN - inline sections in epic file)
      └── Phases define when work happens
           └── Tasks link to BOTH:
                ├── story_id → the requirement being implemented (WHAT)
                └── phase_id → the timeline slot (WHEN)

工件	关注点	关联对象	是否与阶段无关？
史诗	愿景	-	是
故事	要做什么	史诗	是
阶段	何时执行	史诗（内联）	否
任务	如何做 + 何时做	故事 + 阶段	否
研究	探索	史诗/任务	是
学习	知识	-	是

关键要点： 故事是独立于实施时间而存在的需求。阶段对任务（计划中的工作）进行分组，而非对故事（需求）进行分组。任务通过关联故事（要实现的内容）和阶段（计划执行的时间），连接这两个方面。

归档

• [archive] 将已完成的任务和故事归档，方法是将其文件移至 .memory/archive/ 目录。
• [archive] 不要归档学习或研究文件。这些是未来项目的宝贵知识。
• [archive] 在所有阶段完成且经验总结提炼之前，不要归档史诗文件。归档前，史诗必须链接到提炼后的经验总结。
• [archive] 更新 .memory/summary.md，以反映已完成的阶段和史诗。
• [archive] 阶段以内联形式保存在史诗文件中，因此会随史诗一起归档。

搜索记忆 [CRITICAL]

由于 .memory/ 可能被 gitignore 忽略，常规的 List 和 Glob 工具无法按预期工作。使用带 --no-ignore 的 ripgrep 绕过 gitignore 规则：

# First, get the memory directory path
MEMORY_DIR=$(/home/zenobius/.pi/agent/skills/projectmanagement/miniproject/scripts/miniproject.sh memory-dir)

# Search for terms (--no-ignore bypasses .gitignore)
rg --no-ignore "<search-term>" "$MEMORY_DIR/"

# Find outstanding tasks
rg --no-ignore "TODO" "$MEMORY_DIR/todo.md"

# List all memory files
ls -al "$MEMORY_DIR/"

提示

使用 rg -u 作为 rg --no-ignore 的简写。使用 rg -uu 还可以搜索隐藏文件。

模板

.memory/ 中的每种 Markdown 文件都应包含特定的 frontmatter 字段，以确保内容一致且易于访问。

通用 Frontmatter 字段

• id：文件唯一的 8 字符哈希标识符。
• title：概括内容的简洁标题。
• created_at：文件的创建时间戳。
• updated_at：文件的最后更新时间戳。
• status：表示其状态为 proposed、planning、todo、in-progress、completed 或 archived。

通用章节

• # {Title}：文档的主标题。

模板：任务

任务用于在计划阶段中实现故事。它们同时关联到故事（“做什么”）和阶段（“何时做”）。

Frontmatter：

• 所有通用的 frontmatter 字段。
• epic_id：父级史诗的唯一标识符。
• phase_id：安排此任务的阶段（“何时做”——必填）。
• story_id：此任务要实现的故事（“做什么”——存在故事时必填）。
• assigned_to：负责此任务的 Agent 或人员的会话 ID。

说明

双重关联模型： 任务有两个用途不同的父级关联：

• story_id → 关联到此任务要满足的需求（做什么）
• phase_id → 关联到安排此任务的时间（何时做）

没有 story_id 的任务属于探索性／基础设施工作。没有 phase_id 的任务则尚未安排。

章节：

• 所有通用章节。
• ## Objective：清晰说明任务旨在实现什么。
• ## Related Story：链接到此任务要实现的故事（如适用）。必须说明此任务有助于满足哪些验收标准。
• ## Related Phase：链接到安排此任务的阶段。包括阶段名称和史诗背景。
• ## Steps：完成任务所需的详细步骤列表。
• ## Unit Tests：总结为此任务编写的单元测试。每项应说明测试内容，以及它支持父级故事的哪个验收标准。格式：- [测试名称/文件]：[验证内容] → 支持故事 [hash] 的 AC#N。如果任务没有父级故事，请记录单元测试独立验证的内容。
• ## Expected Outcome：描述任务完成后的预期结果。
• ## Actual Outcome：描述任务完成后的实际结果。
• ## Lessons Learned：完成任务后获得的关键经验和见解。

模板：史诗

Frontmatter：

• 所有通用的 frontmatter 字段。

章节：

• 所有通用章节。
• ## Vision/Goal：清晰说明史诗的整体愿景和目标。
• ## Success Criteria：衡量史诗成功与否的指标和标准。
• ## Stories：定义此史诗需求的故事列表（链接到故事文件）。故事与阶段无关——它们定义要构建什么，而非何时构建。
• ## Phases：内嵌阶段章节（参见下方格式）。阶段定义工作开展的时间，并包含已安排的任务。
• ## Dependencies：可能影响此史诗的任何依赖项。

阶段章节格式（内嵌于史诗中）

阶段以内嵌章节的形式定义在史诗文件中，而不是单独的文件：

## Phases

### Phase 1: Foundation
- **Status**: completed
- **Start Criteria**: Epic approved
- **End Criteria**: Core data model implemented and tested
- **Tasks**:
  - [x] [task-abc12345-data-model](./task-abc12345-data-model.md)
  - [x] [task-def67890-basic-api](./task-def67890-basic-api.md)
- **Notes**: Completed ahead of schedule

### Phase 2: Core Features  
- **Status**: in-progress
- **Start Criteria**: Phase 1 complete
- **End Criteria**: All core user stories have passing tests
- **Tasks**:
  - [x] [task-ghi11111-auth-flow](./task-ghi11111-auth-flow.md)
  - [ ] [task-jkl22222-user-dashboard](./task-jkl22222-user-dashboard.md)
- **Notes**: Auth complete, dashboard in progress

### Phase 3: Polish & Launch
- **Status**: planned
- **Start Criteria**: Phase 2 complete
- **End Criteria**: Production deployment successful
- **Tasks**: (to be assigned during task breakdown)

模板：Story

Story 用于记录用户需求。它们与阶段无关——Story 定义用户需要什么，与何时实现无关。

Frontmatter：

• 所有通用 Frontmatter 字段。
• epic_id：父级 Epic 的唯一标识符。
• priority：优先级（例如：critical、high、medium、low）。
• story_points：预估工作量／复杂度（可选，例如：1、2、3、5、8、13）。
• test_coverage：所有验收标准是否都关联了通过的测试。可选值：none、partial、full。

说明

Story 没有 phase_id。Story 是需求，而非已排期的工作。 Task 会关联 Story（实现什么）和 Phase（何时排期）。

章节：

• 所有通用章节。
• ## User Story：以如下格式编写的用户故事陈述：“作为一名 [persona]，我希望 [goal]，以便 [benefit]。”
• ## Acceptance Criteria：一份具体、可测试的条件清单，必须全部满足，Story 才算完成。未完成的标准使用 - [ ]，已完成的标准使用 - [x]。
• ## Context：说明需要此 Story 的背景信息和缘由。
• ## Out of Scope：明确列出此 Story 不包含的内容，以防范围蔓延。
• ## Tasks：实现此 Story 的 Task 文件链接（在任务拆分期间填写）。每个 Task 还会引用一个 Phase，用于安排排期。
• ## Test Specification：将每项验收标准映射到对应的验证方式。包含两个子章节：
  • ### E2E Tests：将每项验收标准映射到相应端到端测试用例的表格。一个 Story 对应一个端到端测试套件／文件。每项验收标准对应套件中的一个测试用例。格式：| AC# | Criterion | Test file/case | Status |
  • ### Unit Test Coverage (via Tasks)：列出此 Story 派生的 Task，并概述每个 Task 的单元测试验证内容，以及这些测试如何帮助满足 Story 的验收标准。格式：- Task [hash]: [unit test summary] → satisfies AC#N
• ## Notes：补充说明、边缘情况或注意事项。

说明

Story 是业务需求与技术任务之间的桥梁。

• Story 从用户角度记录“是什么”和“为什么”。
• Task 从实现角度记录“如何做”。
• 一个 Story 可以在不同阶段派生出多个 Task。
• 应在创建 Task 之前编写验收标准。

说明

Story 是主要的测试目标。

• 端到端测试验证 Story。 每个 Story 对应一个端到端测试套件。每项验收标准对应套件中的一个测试用例。对应关系为：1 个 Story：1 个测试套件，N 项验收标准：N 个测试用例。
• 单元测试验证 Task。 单元测试的范围是 Task（实现），而非 Story（需求）。它们通过父级 Task 追溯到 Story：story.acceptance_criteria → task.objective → task.unit_tests。
• 只有当 test_coverage 为 full 时，Story 才能标记为 completed——这意味着每项验收标准都关联了一个通过的测试。

模板：Research

Frontmatter：

• 所有通用 Frontmatter 字段。
• epic_id：父级 Epic 的唯一标识符。
• related_task_id：促使开展此项研究的 Task 的唯一标识符。[可选]

章节：

• 所有通用章节。
• ## Research Questions：列出研究旨在回答的具体问题。
• ## Summary：简要概述研究结果。
• ## Findings：详细说明研究发现。
• ## References：列出研究期间使用的来源和参考资料。

模板：Learning

Frontmatter：

• 所有通用 Frontmatter 字段。
• tags：对所学内容进行分类的一组标签（例如：best-practices、lessons-learned、technical-insights）。

章节：

• 所有通用章节。
• ## Summary：简要概述所学内容。
• ## Details：详细描述所学内容。
• ## Implications：说明如何将所学内容应用于未来项目。

模板：章程

Frontmatter：

• 所有通用 frontmatter 字段。

章节：

• 所有通用章节。
• ## Project Rules：一系列管理项目和执行工作的规则。
• ### {Concept}：每个概念的描述和指南。

模板：知识

Frontmatter：

• 所有通用 frontmatter 字段。
• area：所记录的特定知识领域（例如，codebase-structure、data-flow、design-patterns）。
• tags：用于知识分类的标签列表（例如，architecture、best-practices、technical-insights）。
• learned_from：对此知识有贡献的史诗、阶段、任务或外部来源的引用。

章节：

• 所有通用章节。
• ## Overview：知识领域的摘要。
• ## Details：知识的详细描述。

模板：知识代码地图

说明

请确保内容准确且及时更新。这对于理解代码库的结构和流程至关重要。 做好这项工作会让用户非常满意。 做好这项工作会获得奖励。

此模板与“知识”模板相同，但专用于代码库代码地图。

因此，其详情部分只能包含一个 ASCII 图，用于表示你对代码库状态机的理解。

操作流程

项目章程 工作流

0. Initialise > Action > 停止
1. Idea > Epic Definition > Research > Story Definition（包括测试规范）> Phase Planning > 人工审核 > Task Breakdown > 停止
2. Task Execution（包括单元测试）> Learning Distillation > 重复
3. Story Completion > 验证验收标准 + 测试覆盖率门槛 > Phase Completion > Learnings Distillation > 人工审核 > 停止
4. Epic Completion > Epic Summary & Learnings > 人工审核 > 停止
5. 按需执行 Maintenance Actions。
6. Status > 停止

下面列出了项目生命周期各阶段的详细步骤。

当用户请求执行 miniproject <action> 时，将 <action>（或 <ACTION>、<Action>）对应到下方相关的 [ACTION]，并严格遵循规则和指南。

初始化操作 [INITIALISE]

• [core] 定位或创建记忆目录：

  MEMORY_DIR=$(/home/zenobius/.pi/agent/skills/projectmanagement/miniproject/scripts/miniproject.sh memory-dir)
  

• [core] 确保 $MEMORY_DIR/ 中存在以下文件：
  • todo.md（用于跟踪任务）
  • summary.md（用于项目概览）
  • team.md（用于团队角色和分工）
  • knowledge-codemap.md（用于理解代码库）
  • knowledge-data-flow.md（用 ASCII 图表示代码库中数据流的状态机。）
• [core] 如果这些文件中有任何缺失，请创建相应文件，并添加适当的标题和初始内容
• [core] 询问用户是否要定义 constitution.md 文件以概述项目规则和指南。如果要，请使用模板结构创建该文件。

维护操作

有时需要维护 .memory/ 目录。请按需使用以下操作。

操作：总结记忆 [SUMMARIZE-MEMORY]

• [core] 读取所有 .memory/ 文件，并更新 .memory/summary.md，以反映当前史诗、活跃阶段和下一步里程碑。删除错误或过时的信息。
• [core] 确保 .memory/summary.md 简洁明了，便于快速浏览。

操作：清理 [CLEAN-UP]

• [tasks] 将已完成的任务移至 .memory/archive/ 目录。
• [learning] 确保所有重要经验都记录在 .memory/learning-<8_char_hash_id>-<title>.md 文件中。
• [stories] 在已完成故事的所有任务都归档后，将这些故事移至 .memory/archive/ 目录。

操作：验证记忆 [VALIDATE-MEMORY]

• [core] 运行验证脚本，确保所有记忆文件符合 frontmatter 规则：./scripts/validate.ts

操作：完善章程 [REFINE-CONSTITUTION]

• [core] 根据用户输入审核并更新 .memory/constitution.md。
• [core] 确保所有团队成员了解章程的任何变更。
• [core] 除非有人类明确要求，否则绝不更新 .memory/constitution.md。
• [core] 更新时，确保将变更单独提交，并使用 memory/constitution 作为作用域，且提交说明清晰。

状态操作 [STATUS]

• [core] 根据 .memory/summary.md，总结当前史诗、活跃阶段和下一步里程碑。
• [core] 列出 .memory/todo.md 中未完成的任务。
• [core] 使用 ASCII 图表说明任务工作在状态机中的位置，以便将状态与上下文关联起来。

规划阶段

阶段：构思 [IDEA]

• [core] 每个项目都必须先定义史诗，然后才能创建用户故事或任务
• [core] 初始化时，为现有代码库创建代码地图，并确保在 .memory/knowledge-codemap.md 中绘制状态机 ASCII 图表，以呈现你对代码库的理解。
• [epic] 宣布一个想法后，直接与用户进行问答，完善想法并判断是否值得推进。如果值得推进，则直接进入史诗定义阶段。如果不值得推进，则在 .memory/learning-<8_char_hash_id>-<title>.md 文件中记录该想法及其被否决的原因，以供将来参考。

阶段：史诗定义 [EPIC]

• [epic] 每个项目都必须从一个史诗开始，用以定义总体目标和范围
• [epic] 每个史诗都应记录在 .memory/epic-<8_char_hash_id>-<title>.md 文件中
• [epic] 史诗必须包含：愿景/目标、成功标准、用户故事列表、阶段（内嵌）、总体时间线和依赖项
• [epic] 阶段应作为内嵌章节放在史诗文件中，而非单独成文
• [epic] 除非获得人类明确批准，否则同一时间只能有一个活跃史诗
• [epic] 在所有阶段完成且经验教训已提炼之前，绝不归档史诗文件

阶段：研究 [RESEARCH]

• [research] 开始任何研究之前，先阅读 .memory/summary.md 和所有 .memory/**/learning**.md，了解已有发现。不要重复研究。
• [research] 如果找到现有研究，在需要该研究的文档中链接到它，不要复制或重复其内容。
• [research] 将研究拆解为具体且可回答的问题。
• [research] 搜索外部信息之前，先扫描 .memory/ 中已归档的记忆文件，寻找相关信息。如果找到相关信息，链接到它，而不是重复记录。
• [research] 使用 use_skill(brave_search) 及其 search 和 content 提取脚本收集信息。如果失败，则使用 lynx CLI 手动搜索并提取内容。
• [research] 批判性评估来源的可信度、相关性和偏见。将这些来源链接到脚注，并在脚注中说明理由并给出 10 分制评分。
• [research] 在 .memory/research-<8_char_hash_id>-<title>.md 文件中清晰、简洁地记录研究发现。文件顶部提供摘要，下面记录详细发现，最后列出参考资料。
• [research] 进行由用户主导的探索/规划问答时，应在研究文档中逐字记录完整过程：每个问题、所有提供的选项，以及用户的确切回答。摘要可作为补充，但不能取代逐字记录的问答。
• [research] 研究任务始终委派给 “Deep Researcher SubAgent”。使用你能调用的任何子 Agent、子线程或委派工具。
• [research] 如果你是子 Agent，则只专注于分配给你的任务。不要偏离任务，也不要进一步委派。

阶段：故事定义 [STORY-DEFINITION]

• [story] 故事应在开始实现前，明确记录用户需求和验收标准
• [story] 每个故事都应记录在 .memory/story-<8_char_hash_id>-<title>.md 文件中
• [story] 故事必须包含用户故事陈述、验收标准和上下文
• [story] 故事只链接到其父级 Epic——故事是与阶段无关的需求
• [story] 故事没有 phase_id——它定义的是做什么，而非何时做
• [story] 验收标准必须具体、可测试，并以检查清单的形式编写
• [story] 编写验收标准后，填写 ## Test Specification 部分：
  • 定义此故事的端到端测试套件名称／文件
  • 将每条验收标准映射到一个命名的端到端测试用例
  • 在 frontmatter 中设置 test_coverage: none（编写测试后更新）
• [story] 故事应在创建任务之前编写——任务负责实现故事
• [story] 单个故事可能会产生多个安排在不同阶段的任务
• [story] 满足并验证所有验收标准后，将故事标记为 completed
• [story] 故事有助于区分“用户需要什么”与“我们如何以及何时实现”

说明

故事、阶段与任务的区别：

• 故事：“作为用户，我想重置密码，以便重新访问我的帐户。”（与阶段无关的需求）
  • 验收标准：“用户在 2 分钟内收到电子邮件”“链接在 24 小时后过期”等。
• 阶段：“阶段 2：用户身份验证”——Epic 中有时间限制的工作容器
• 任务：“实现密码重置 API 端点”（链接到故事和阶段）、“创建电子邮件模板”（链接到故事和阶段）等。
• 端到端测试（验证故事）：password-reset.e2e.spec → 每条验收标准对应一个测试用例
• 单元测试（验证任务）：端点输入验证、模板渲染、令牌过期逻辑等

阶段：阶段规划 [PHASE-PLANNING]

• [phase] 阶段是 Epic 文件中的内联部分，而非独立文件
• [phase] 每个阶段都应包含：状态、开始标准、结束标准和任务列表
• [phase] 阶段用于归组任务（已安排的工作），而非故事（需求）
• [phase] 阶段应具有明确的开始和结束标准，并与 Epic 目标一致
• [phase] 不要将阶段视为故事列表——阶段包含用于实现故事的任务
• [phase] 在 Epic 文件的 ## Phases 部分添加新阶段

说明

验证步骤：

• 规划阶段后，继续拆分任务前，务必先请人工审核。
• 在聊天中打印一个大型 ASCII 方框，说明阶段规划需要人工审核。
• 等待人工确认后再继续。

阶段：任务拆分 [TASK-BREAKDOWN]

• [tasks] 每个任务都应记录在 .memory/task-<8_char_hash_id>-<title>.md 文件中，其中包括目标、执行步骤和预期结果。
• [tasks] 任务必须同时包含两个链接：
  • story_id：此任务所实现的故事（“做什么”）
  • phase_id：此任务安排在哪个阶段（“何时做”）
• [tasks] 没有关联故事的任务属于基础设施／探索性工作——应明确记录目标
• [tasks] 没有关联阶段的任务尚未安排——执行前应将其分配到一个阶段
• [tasks] 任务应具体、可衡量、可实现、相关且有时限（SMART）。
• [tasks] 根据影响和紧迫性确定任务优先级。
• [tasks] 创建任务时，也要将其添加到 Epic 文件中相应的阶段部分。
• [tasks] 使用 .memory/todo.md 跟踪剩余任务。此文件只包含指向 .memory/task-<8_char_hash_id>-<title>.md 文件的链接。[CRITICAL] 每一步都要及时更新 .memory/todo.md。

执行阶段

阶段：任务执行 [TASK-EXECUTION]

• [tasks] 始终在任务文件中更新清单和进度。[CRITICAL] 每一步都要及时更新 .memory/todo.md。
• [tasks] 完成任务时，在相关的 .memory/task-<8_char_hash_id>-<title>.md 文件中记录结果和经验教训。
• [tasks] 更新 Epic 文件中父阶段部分的任务复选框。
• [core] 始终及时更新 .memory/summary.md，记录当前 Epic、活动阶段和下一个里程碑。清理不正确或过时的信息。

阶段：经验提炼 [LEARNING-DISTILLATION]

• [learning] 任何重要见解、经验教训或最佳实践都应记录在 .memory/learning-<8_char_hash_id>-<title>.md 文件中，以供将来参考。
• [learning] 经验文件永不归档或删除。[CRITICAL] 始终保留经验文件。

完成阶段

阶段：故事完成 [STORY-COMPLETION]

• [story] 将故事标记为完成之前，验证是否满足所有验收标准。
• [story] 验证每项验收标准后，更新对应复选框（从 - [ ] 改为 - [x]）。
• [story] 如果无法满足任何验收标准，请在故事的 Notes 部分说明原因。
• [story] 在 ## Tasks 部分将已完成的任务关联到故事。
• [story] 测试验证门槛：将故事标记为 completed 之前，验证：
  • ## Test Specification > ### E2E Tests 中的每项验收标准都已关联一个通过的测试用例
  • ## Test Specification > ### Unit Test Coverage 中列出的每项任务都已在其自身的 ## Unit Tests 部分记录单元测试
  • 更新 test_coverage frontmatter：none → partial（关联了部分测试）→ full（所有标准均已覆盖且测试通过）
  • 当 test_coverage 为 none 或 partial 时，故事不能标记为 completed
• [story] 验证所有标准且 test_coverage 为 full 后，将故事状态更新为 completed
• [story] 所有关联任务归档之前，故事不得归档——应保留故事，作为需求及其完成情况的文档

阶段：阶段完成 [PHASE-COMPLETION]

• [phase] 完成阶段时，在 Epic 文件中将阶段状态更新为 completed
• [phase] 确保该阶段中的所有任务均已标记为完成（复选框为 [x]）
• [phase] 在经验文件中记录经验教训
• [phase] 完成阶段时，将研究和任务中的相关经验与结果提炼汇总到 .memory/learning-<8_char_hash_id>-<title>.md 文件中。清理 .memory/summary.md 和 ./memory/todo.md。
• [phase] 将已完成任务的文件移至 .memory/archive/ 目录进行归档

说明

验证步骤：

• 完成阶段后，在开始下一阶段之前请人工审核。
• 在聊天中打印一个大型 ASCII 方框，提示需要人工审核阶段完成情况。
• 等待人工确认后再继续。

阶段：Epic 完成 [EPIC-COMPLETION]

• [epic] 在所有阶段完成且经验已提炼之前，绝不归档 Epic 文件。
• [archive] 在所有阶段完成且经验已提炼之前，不要归档 Epic 文件。归档前，Epic 必须链接到已提炼的经验。
• [archive] 更新 .memory/summary.md，反映已完成的阶段和 Epic。
• [archive] 不要归档经验或研究文件。这些是未来项目的宝贵知识。

说明

验证步骤：

• 完成 Epic 后，归档之前务必请人工审核。
• 在聊天中打印一个大型 ASCII 方框，提示需要人工审核 Epic 完成情况。
• 等待人工确认后再继续。

常规操作步骤

1. [CRITICAL] 如果不存在 epic，请先创建一个，再进行其他工作。 定义愿景、成功标准、故事和计划阶段（内联）。
2. 更新 .memory/team.md，注明正在处理哪个 epic 和阶段，以及由谁负责（使用会话 ID，而不是 Agent 名称）。
3. 如果 .memory/todo.md 中有任何 [NEEDS-HUMAN] 任务，请停止并等待人工介入。
4. 遵循上述研究指南。
5. 如果遇到需要人工介入的操作而受阻，请在 .memory/todo.md 中创建任务，列出需要人工完成的事项，并在任务行中添加 [NEEDS-HUMAN] 标签。
6. 完成一个阶段后，更新 .memory/summary.md，并视需要精简其他文件。
7. 完成一个 epic 后，提炼所有经验，更新 .memory/summary.md，并归档已完成的任务和故事。
8. 提交更改，并编写清晰的提交说明，注明相关文件。

人工介入

• 如果需要澄清或补充信息，请向人工寻求帮助。
• 在聊天中打印一个大型 ASCII 方框，表明需要人工介入，并在方框内列出 .memory/todo.md 中的任务。
• 等待人工完成这些任务后再继续。