aif-implement

实施 - 执行任务计划

执行计划中的任务、跟踪进度，并支持会话续接。

工作流

步骤 0（预备）：检测交接模式

确定交接模式。如果调用方在提示词中明确传入了 HANDOFF_MODE 和 HANDOFF_SKIP_REVIEW，则使用这些值。否则，使用 Bash 工具：

Bash: printenv HANDOFF_MODE || true
Bash: printenv HANDOFF_SKIP_REVIEW || true

然后检查 HANDOFF_MODE：

当 HANDOFF_MODE 为 1（自主交接 Agent）时

交接协调器已经直接管理状态转换和数据库写入。请勿调用 MCP 工具。改为：

• 不提问： 不要使用 AskUserQuestion——使用合理的默认值（在检查点自动提交，跳过暂停提示）。
• 不暂停或恢复提示： 按顺序执行所有任务，不要停下来等待确认。遇到阻止继续的完整性、安全性或需求冲突时，仍应按规定的非交互式结果停止。

当 HANDOFF_MODE 不为 1（手动 Claude Code 会话）时

交接同步在流程中内联处理——请参阅步骤 0.2（读取计划文件后），了解任务 ID 提取和 MCP 同步触发。同步点如下：

• 开始时（步骤 0.2）： handoff_sync_status → "implementing"（设置 paused: true）
• 更新检查清单时（步骤 3.6）： 使用更新后的计划内容调用 handoff_push_plan
• 完成时（步骤 5）： 先用最终计划调用 handoff_push_plan，然后调用 handoff_sync_status → "review"（设置 paused: true），或 "done"（当 HANDOFF_SKIP_REVIEW=1 时设置 paused: false）

重要： 除 done 外，每次调用 handoff_sync_status 时都必须传入 paused: true。这样可防止自主交接 Agent 在你手动处理期间接手任务。只有 done 才传入 paused: false。

步骤 0：检查当前状态

首先： 确定当前所处的状态：

1. Read `.ai-factory/config.yaml` if it exists to resolve:
   - `paths.description`, `paths.architecture`, `paths.rules_file`, `paths.roadmap`, `paths.research`; derive `research_bundles_dir = <parent directory of paths.research>/research/`
   - `paths.plan`, `paths.plans`, `paths.fix_plan`, `paths.patches`
   - `paths.archive`
   - `paths.rules`
   - `language.ui`, `language.artifacts`
   - `git.enabled`, `git.base_branch`, `git.create_branches`
   - `workflow.plan_id_format` (default: `slug`) — used by branch-based plan discovery.
     Active values: `slug` and `sequential`. Discovery treats a root `*.md` as
     a full plan unless it is the resolved `paths.plan` or `paths.fix_plan`.
     Treat a direct child `*/index.md` as an ultra bundle only after reading it
     and confirming that it contains exactly one
     ``; ignore unrelated directories and never count
     phase files independently.
     When `sequential`, resolve both
     `<paths.plans>/[0-9]{4}_<branch-slug>.md` and
     `<paths.plans>/[0-9]{4}_<branch-slug>/index.md`, then choose the
     highest-numbered matching artifact.
     `timestamp` and `uuid` are **reserved values** and currently behave like `slug`.
     Treat any unknown value as `slug`.
   - `rules.base` plus any named `rules.<area>` entries
2. Parse arguments:
   - --list → list available plans only (no implementation; STOP)
   - --without-plan <description> → inline implementation mode; skip plan discovery and jump to Step 0.inline
   - @<path> → explicit plan file, ultra directory, or ultra `index.md` override (highest priority)
   - <number> → start from specific task
   - status → status-only mode
   - Optional inline-mode flag: --docs=yes|no|warn (only valid with --without-plan; default: warn)
3. If `git.enabled = true`, check for uncommitted changes (`git status`)
4. If `git.enabled = true`, check current branch

步骤 0.list：列出可用计划（--list）

如果 $ARGUMENTS 包含 --list，则以只读方式发现计划，然后停止。

1. Get current branch:
   git branch --show-current (git mode only)
2. Convert branch to canonical stem: replace "/" with "-" (git mode only)
3. Check existence of:
   - <configured plans dir>/<branch-stem>.md and
     <configured plans dir>/<branch-stem>/index.md (git mode only); Read the
     directory entrypoint and report it only when it contains exactly one
     ``
   - when `workflow.plan_id_format = sequential`: also glob
     `<configured plans dir>/[0-9][0-9][0-9][0-9]_<branch-stem>.md` and
     `<configured plans dir>/[0-9][0-9][0-9][0-9]_<branch-stem>/index.md`;
     Read every directory entrypoint, discard those without exactly one marker,
     and report all valid matches (highest-numbered first)
   - if git mode is off or branch creation is disabled: any root `*.md` full
     plan or declared-ultra direct child `*/index.md` entrypoint in
     `<configured plans dir>/`; exclude the resolved fast/fix plan paths
   - <resolved fast plan path>
   - <resolved fix plan path>
4. Print plan availability summary and usage hints
5. STOP.

重要： 在 --list 模式下：

• 不要执行任务
• 不要修改文件
• 不要更新 TaskList 状态

有关详细的输出格式和示例，请参阅：

• skills/aif-implement/references/IMPLEMENTATION-GUIDE.md →“列出可用计划（--list）”

步骤 0.inline：内联实施模式（--without-plan）

如果 $ARGUMENTS 包含 --without-plan，则根据描述执行一个范围明确的任务，不要创建或读取任何计划文件。这是适用于小型 feat/chore 任务的轻量流程；这类任务不值得制定完整计划，但也不是错误修复（修复错误请使用 /aif-fix）。

参数解析：

1. description = everything after `--without-plan`, excluding any recognized flag tokens (`--docs=...`).
2. docs_policy = value of `--docs=yes|no|warn` if present, else `warn` (default).
3. Validation:
   - description is empty →
     ERROR: "Usage: /aif-implement --without-plan <description> [--docs=yes|no|warn]"
     → STOP
   - arguments also contain `@<path>`, `status`, or a bare task id number →
     ERROR: "`--without-plan` is mutually exclusive with @plan-file, status, and task id."
     → STOP
   - `--docs=<value>` where <value> not in {yes, no, warn} →
     ERROR: "Invalid --docs value. Expected yes|no|warn."
     → STOP

范围限制（防止任务悄然膨胀）：

执行前，先评估描述。如果任务范围看起来过于宽泛，不适合一次性内联执行——例如包含多个由“and”/“и”连接且彼此无关的指令、涉及多个子系统，或范围描述大约超过 300 个字符——请勿尝试自行推测计划。请改为打印：

Description looks too broad for inline implementation. Recommended:
  /aif-plan fast <description>

→ 停止。

范围小且明确的描述（例如“添加返回 200 和 {status:"ok"} 的 GET /healthz”）可继续执行。

对现有计划文件发出提醒（非阻塞）：

内联模式按设计会忽略计划文件。如果磁盘上存在以下任何文件，请输出一行 WARN [inline]，提醒用户这些文件被有意跳过（不要读取这些文件，也不要重定向）：

• <configured plans dir>/<branch>.md 或 <configured plans dir>/<branch>/index.md（仅 git 模式）——或对应的 [0-9]{4}_<branch> 顺序编号形式
• 已解析的快速计划路径（paths.plan）
• 已解析的修复计划路径（paths.fix_plan）

示例：WARN [inline] paths.plan exists but is ignored in --without-plan mode.

加载项目上下文（与常规实施相同）：

使用步骤 0 中解析的配置：

• paths.description（DESCRIPTION.md），如果存在
• paths.architecture（ARCHITECTURE.md），如果存在
• paths.rules_file（RULES.md）+ rules.base + 命名的 rules.<area> 条目
• .ai-factory/skill-context/aif-implement/SKILL.md — 如果该文件存在则为必需（其优先级与强制执行方式与 Step 0.1 中常规模式相同）
• language.ui、language.artifacts

计划产物策略： inline 模式不会加载或使用 plan/fix-plan 文件。计划文件永远不会被读取、解析或执行。允许进行最小限度的存在性探测（参见上文 surprise-warn 部分），仅用于输出 WARN [inline] 行——不会从磁盘读取任何内容。同时跳过：resume/recovery 对账、TaskList 加载、复选框状态比较。

执行任务（一次性）：

1. 声明：Inline implementation: <description>
2. 仅读取与所述范围相关的文件
3. 遵循现有代码模式和 skill-context 规则应用更改
4. 按照 references/LOGGING-GUIDE.md 应用详细日志记录
5. 默认不添加测试。仅在以下情况下添加：描述中明确要求测试（例如 "with tests"、"add tests for X"），或者现有项目约定 / 涉及的代码路径明确要求测试（例如，测试文件与该区域每个源文件一一对应，或 RULES.md / skill-context 规则要求此类更改具备测试覆盖）。如有疑问，倾向于不添加测试，让用户通过 /aif-plan 跟进以获得更广泛的测试覆盖。
6. 验证更改可编译/运行，且所述行为正常工作

inline 模式中禁止的操作：

• 不要创建或读取 paths.plan / paths.plans/* / paths.fix_plan。
• 不要调用 /aif-plan 或 /aif-fix。
• 不要在 paths.patches 下创建条目（不创建 [FIX] 自我改进补丁——这不是 bugfix 流程）。
• 不要调用 TaskList / TaskGet / TaskUpdate（没有计划 = 没有持久化任务）。
• 不要在磁盘上搜索或修改计划复选框。
• 不要触发 roadmap 里程碑完成检查、docs checkpoint-from-plan-setting、plan-file cleanup 提示或 worktree merge 提示（这些属于计划支撑的工作流）。

Handoff inline 支持：

命名澄清：--without-plan 意味着“磁盘上没有本地计划产物”（没有 paths.plan / paths.plans/* / paths.fix_plan）。当 Handoff 任务被关联时，该任务仍通过 handoff_push_plan 在 Handoff 内部表示为一个合成计划——那是远程表示，而非本地文件。本地无计划契约得以保留；仅远程同步表面保持不变。

当 HANDOFF_MODE 为 1 时（自主 Handoff Agent 调用 inline 模式）：

• 不要调用任何 mcp__handoff__* 工具（协调器直接管理 status/sync——与 Step 0（pre）规则相同）。
• 不要创建本地计划产物（上述常规 Prohibited 列表仍然适用）。
• 不要切换分支、创建 worktree、合并 worktree，或以其他方式更改协调器设置的 branch/worktree——inline 模式在其被调用时的工作树上操作。
• 继续一次性执行；技能返回后，协调器将任务标记为完成。

当 HANDOFF_MODE 不为 1 且设置了 HANDOFF_TASK_ID 时（手动 Claude Code 会话关联到 Handoff 任务）：

1. 构建合成计划内容：

   # Inline implementation
   - [ ] <description>
   

2. 调用 handoff_sync_status，参数为 { taskId: <HANDOFF_TASK_ID>, newStatus: "implementing", sourceTimestamp: "<current UTC ISO 8601>", direction: "aif_to_handoff", paused: true }。

3. 调用 handoff_push_plan，参数为 { taskId: <HANDOFF_TASK_ID>, planContent: <synthetic content above> }。

4. 执行成功后，将合成内容中的复选框翻转为 - [x]，并使用更新后的文本再次调用 handoff_push_plan。

5. 完成同步：

   • 如果 HANDOFF_SKIP_REVIEW 为 1 → handoff_sync_status → "done"，paused: false。
   • 否则 → handoff_sync_status → "review"，paused: true。

如果 HANDOFF_TASK_ID 缺失 → 跳过本次运行的所有 MCP 同步。 文档策略（内联模式，由 --docs 控制）：

• --docs=yes → 完成后，显示文档检查点（与常规模式中的 Docs: yes 使用相同的 AskUserQuestion），并通过 /aif-docs 处理更改。
• --docs=no → 跳过文档检查点，并输出 WARN [docs] --docs=no in inline mode; documentation checkpoint skipped。
• --docs=warn（默认）→ 输出 WARN [docs] Inline mode default is warn-only; documentation checkpoint skipped. Pass --docs=yes to enable.

内联模式中的上下文维护：

• 已解析的描述文档更新：允许，遵循与常规模式相同的规则（仅记录新增依赖项／集成的事实性差异）。
• 已解析的架构文档和 AGENTS.md：仅在实际创建了新模块／文件夹时允许更新。
• 已解析的路线图文档：内联模式下不更新（没有计划，无法关联里程碑）。
• 已解析的规则文件：内联模式下不编辑（与常规模式相同）。

完成时的输出（内联模式）：

## Inline Implementation Complete

Task: <description>

Files modified:
- <file> (created|modified)
Documentation: <outcome per --docs>

What's next?

1. 🔍 /aif-verify — Verify the change (recommended)
2. 💾 /aif-commit — Commit directly

然后提供：

AskUserQuestion: Inline task complete. What's next?

Options:
1. Verify first — Run /aif-verify (recommended)
2. Skip to commit — Go straight to /aif-commit

→ 所选后续操作完成后即停止。不生成摘要文档或报告文件。

步骤 0.0：恢复／继续（中断后或执行 /clear 后）

如果用户在次日继续、表示会话已中止，或者你怀疑上下文已丢失（例如执行 /clear 后），请先从仓库重建本地上下文，再继续任务：

如果 git.enabled = true：

1. git status
2. git branch --show-current
3. git log --oneline --decorate -20
4. (optional) git diff --stat
5. (optional) git stash list

如果 git.enabled = false，跳过 git 恢复命令，仅根据已解析的计划／修复计划路径和工作树状态进行核对。

然后核对计划／任务状态：

• 当使用 Git 分支计划时，确保当前计划文档与当前分支匹配（@path 覆盖优先；否则，分支命名的完整计划文件或 ultra 目录优先于已解析的快速计划）。
• 如果 git.enabled = false，或者完整／ultra 计划是在没有分支的情况下创建的，则优先选择：
  • 显式指定的 @plan-file-or-directory，
  • 然后是配置的计划目录中唯一的根目录 *.md 完整计划，或已声明 ultra 计划的直接子目录 */index.md 入口文件（排除已解析的快速／修复计划路径），
  • 然后是已解析的快速计划路径。
• 比较 TaskList 状态与计划入口文件中的复选框。
  • 如果某个任务的代码更改看起来已实现，但任务尚未标记为已完成，请快速验证，然后执行 TaskUpdate(..., status: "completed") 并更新计划复选框。
  • 如果某个任务已标记为已完成，但对应代码缺失（发生了 rebase/reset），则将其重新标记为待处理，并与用户讨论。

如果存在未提交的更改：

AskUserQuestion: You have uncommitted changes. Commit them first?

Options:
1. Yes, commit now (/aif-commit)
2. No, stash and continue
3. Cancel

根据选择：

• 是 → 运行 /aif-commit，然后继续发现计划
• 否 → git stash push -m "aif-implement: stash before plan execution"，然后继续
• 取消 → 告知用户：“实施已取消。” → 停止

如果不存在计划文件，但存在已解析的修复计划：

修复计划由 /aif-fix 在计划模式下创建。转入修复工作流：

Found a fix plan at the resolved fix plan path.

This plan was created by /aif-fix and should be executed through the fix workflow
(it creates a patch and handles cleanup automatically).

Running /aif-fix to execute the plan...

→ 调用 /aif-fix（不带参数——它会检测已解析的修复计划并执行该计划）。 → 停止——不要继续实施工作流。

如果不存在计划文件，也不存在已解析的修复计划（所有任务均已完成或刚开始）：

AskUserQuestion: No active plan found. Current branch: <current-branch>.
What would you like to do?

Options:
1. Start new feature from current branch
2. Return to configured base branch and start new feature
3. Create quick task plan (no branch)
4. Nothing, just checking status

根据选择：

• 新功能，基于当前状态 → /aif-plan full <description>
• 返回基础分支 → git checkout <configured-base-branch>，然后执行 git pull origin <configured-base-branch> → /aif-plan full <description>（仅 Git 模式）
• 快速任务 → /aif-plan fast <description>
• 无操作，只查看状态 → 显示分支信息和近期提交摘要 → 停止

如果 git.enabled = false，将选项 2 替换为：

• 2. 不创建分支，创建详细完整计划
• 将其转交给 /aif-plan full <description>，不执行任何 git 命令

如果计划文件存在 → 继续执行步骤 0.1

步骤 0.1：加载项目上下文和过往经验

使用步骤 0 中解析出的配置：

• 路径： description、architecture、RULES.md、路线图、research、plan 文件、patches 和 rules 目录
• 语言： prompts 使用 language.ui，生成的内容使用 language.artifacts
• 规则层级： 已解析的 RULES.md 文件 + rules.base + 命名的 rules.<area> 条目

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

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

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

• 选定的架构模式和文件夹结构
• 依赖规则（什么依赖什么）
• 层／模块边界和通信模式
• 实现时遵循这些约定，包括文件放置、导入和模块边界

如果已解析的 RULES.md 路径存在，请读取：

• 这些是用户添加的项目专属规则和约定
• 实现时始终遵循这些规则——它们优先于通用模式
• 规则简短且可执行——将每条规则视为硬性要求

读取规则层级（路径来自配置）：

1. RULES.md – 公理（通用项目规则）
2. rules/base.md — 项目专属的基础约定（命名、结构、模式）
3. rules. — 根据配置解析出的特定领域规则条目（例如 rules.api、rules.frontend）

加载所有可用的规则文件并合并。更具体的规则优先于通用规则。

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

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

如何应用 skill-context 规则：

• 将其视为对此技能通用说明的项目级覆盖规则
• 当 skill-context 规则与本 SKILL.md 中的通用规则冲突时，以 skill-context 规则为准（更具体的上下文优先——与嵌套 CLAUDE.md 文件遵循相同原则）
• 如果没有冲突，则同时应用：SKILL.md 中的通用规则和 skill-context 中的项目规则
• 即使 skill-context 规则看起来与此技能的默认规则矛盾，也不要忽略它们——这些规则之所以存在，是因为项目经验表明默认规则并不充分
• 重要： skill-context 规则适用于此技能的所有输出——包括编写的代码以及更新计划复选框的方式。如果 skill-context 规则要求“代码必须遵循 X”或“实现必须包含 Y”，则必须遵守。编写违反 skill-context 规则的代码属于缺陷。

执行要求： 生成任何输出文档后，都要根据所有 skill-context 规则进行检查。如果违反了任何规则，请在向用户展示前修正输出。

补丁备用方案（仅在缺少 skill-context 时有限使用）：

• 如果 .ai-factory/skill-context/aif-implement/SKILL.md 不存在，且已解析的 patches 目录存在：
  • 使用 Glob 在已解析的 patches 目录中查找 *.md 文件
  • 按文件名字典序升序排列补丁文件，然后选择最后 10 个（少于 10 个则全部选择）
  • 只读取选中的补丁文件
  • 优先关注 Root Cause 和 Prevention 部分
• 如果 skill-context 存在，默认情况下不要读取所有补丁。
  • 仅当任务明显符合已知故障模式时，才可选择性地读取少量相关的近期补丁。

实现时使用这些上下文：

• 遵循指定的技术栈
• 使用正确的导入模式和约定
• 按照指定方式进行适当的错误处理和日志记录
• 避免 skill-context 规则和相关备用补丁中记录的陷阱

步骤 0.2：查找计划文档

将每个选定的文档统一为：

• plan_entrypoint — 包含设置和 ## Tasks 的单个 Markdown 文件
• plan_bundle_dir — 对于 fast/full/fix 计划为空；其他情况为 ultra 目录
• phase_files — 对于单文件计划为空；其他情况为 ultra 入口文件 ## Phase Index 中 按顺序排列的链接

如果 $ARGUMENTS 包含 @<path>：

1. 相对于项目根目录解析路径（也接受绝对路径）。
2. 接受现有 Markdown 文件、包含 index.md 的 ultra 目录，或该 ultra 包中的 index.md。
3. 如果两种形式都不存在，使用 fast 文件、full 文件和 ultra 目录的示例报告缺失路径，然后停止。
4. 在规范化目录或将显式指定的 index.md 视为 ultra 之前，读取 index.md 并要求其中恰好有一个 ``；否则以计划完整性错误停止。
5. 如果所选文件是 paths.fix_plan，调用 /aif-fix 并停止。
6. 否则使用该文件并跳过自动发现。

如果没有显式覆盖，则按以下顺序解析：

1. Branch-based full/ultra artifact:
   a. Compute <branch-stem> by replacing "/" with "-".
   b. For workflow.plan_id_format=sequential, glob both:
        <paths.plans>/[0-9][0-9][0-9][0-9]_<branch-stem>.md
        <paths.plans>/[0-9][0-9][0-9][0-9]_<branch-stem>/index.md
      Read every directory candidate and retain it only when `index.md` contains
      exactly one . Choose the highest numeric prefix
      across valid artifacts. If multiple valid candidates exist, emit
      WARN [aif-implement] and name the chosen artifact; if both shapes share
      the highest prefix, prefer ultra.
   c. If no valid sequential candidate exists, or sequential mode is inactive,
      check:
        <paths.plans>/<branch-stem>/index.md
        <paths.plans>/<branch-stem>.md
      Read the directory entrypoint before selection and ignore it unless it
      contains exactly one . If both valid shapes
      exist, emit WARN and prefer the ultra entrypoint.
2. If no branch artifact resolves, count active named artifacts as:
     - each root <paths.plans>/*.md file except resolved paths.plan and paths.fix_plan
     - each direct child <paths.plans>/*/index.md containing 
   Exactly one total → use it. More than one → ask the user to choose or use
   @<path>; do not count phase files as independent plans.
3. No named artifact → paths.plan.
4. No regular plan → paths.fix_plan, then redirect to /aif-fix and STOP.

优先级仍为：显式路径 → 基于分支的 full/ultra 工件 → 单个命名的 full/ultra 工件 → fast 计划 → 重定向到 fix 计划。发现过程只扫描 paths.plans；排除 paths.archive/plans 下的归档文件和目录。

读取所选工件：

• 如果自动发现的目录入口文件不恰好包含一个 ``, 则它不是 AI Factory 计划。忽略它并继续发现。如果它包含该标记，但 Phase Index 格式错误，则以计划完整性错误停止，不要回退到其他计划。
• 始终完整读取 plan_entrypoint。
• 如果它是 ultra（包含 ``），则验证 Phase Index 中的每个相对链接，拒绝逃逸出该包的路径，记录按顺序排列的阶段文件，并确保每个索引任务都恰好对应一个 ## Task N 章节。若包损坏，则发出警告并停止，不要猜测。
• 实施某个任务前，完整读取该任务的阶段文件。恢复执行时，即使活动阶段在之前的会话中已读取，也要重新读取。
• index.md 是唯一的进度来源；阶段文件不得包含重复的任务复选框。
• 将 ## Original Request 视为有用的原始范围上下文。可执行输入仍包括设置、依赖项、任务清单、已提交的 Research Context，以及（对于 ultra）链接的阶段规范。
• 对入口文件中的 Research Context 应用研究偏移约定。使用规范语法 ^(?:Source|Reference):\s+\x60([^\x60]+)\x60\s+\( 解析第一行 Source: / Reference:；捕获反引号括起的路径，以保留空格和方括号。对于较旧的裸路径行，回退到 ^(?:Source|Reference):\s+(.+?)\s+\(。仅当两种形式都无法识别出可用路径时，才回退到 paths.research。
• 如果解析出的来源位于 research_bundles_dir 内，则要求其同级 INDEX.md 恰好包含 ``，且在 ## Artifact Index 中链接到该 RESEARCH.md；否则发出 WARN [research-drift]。有效的同级 C4/ADR/依赖项工件仅作为理由说明，不会扩大已提交的范围。
• 存在 SHA256: 时，严格提取当前来源文本中位于 和 之间的内容，移除 HTML 注释块，保留行顺序和行首空白，去除每行末尾的空格，使用 LF 换行，并以一个换行符结尾。通过 stdin 使用 shasum -a 256 或 sha256sum 计算哈希；摘要具有权威性。仅当不存在 SHA256: 时，才将 Updated: 用作旧版回退方式。如果来源缺失或无效，或版本不匹配，则发出 WARN [research-drift] 并继续使用已提交的计划上下文。在本约定的单文件表述中：发出 WARN [research-drift] 并继续使用计划中内嵌的 Research Context 作为范围。

读取 plan_entrypoint 后立即检查其第一行是否包含 ``：

• 在手动模式下，提取它，并调用 handoff_sync_status，状态设为 implementing，使用实际的当前 UTC 时间戳，方向设为 aif_to_handoff，并将 paused: true。
• 在自主 Handoff 模式下，不要调用 MCP。
• 如果不存在，则本次会话跳过 MCP 同步。

向 Handoff 推送 ultra 进度时，将完整套件序列化为入口文件内容，后接每个 链接的阶段文件，并按顺序以 `` 作为前缀。

步骤 1：加载当前状态

TaskList → Get all tasks with status

查找：

• 下一个待处理任务（未阻塞、未完成）
• 任何进行中的任务（优先恢复这些任务）

步骤 2：显示进度

## Implementation Progress

✅ Completed: 3/8 tasks
🔄 In Progress: Task #4 - Implement search service
⏳ Pending: 4 tasks

Current task: #4 - Implement search service

步骤 3：执行当前任务

对于每项任务：

3.1：获取完整详情

TaskGet(taskId) → Get description, files, context

对于 ultra 套件，先从 index.md 解析任务详情链接，然后在将任务标记为进行中 之前，读取链接阶段文件的全部内容。将其中按顺序排列的实现步骤、接口、边缘情况、 日志记录、验收标准和验证要求都视为必需内容。不要仅仅因为 TaskGet 包含较短 摘要，就改用新方案。如果阶段说明与当前代码或项目上下文冲突，请停止并报告 具体差异；不要悄悄做出 ultra 原本要预先规划的架构决策。

3.1.1：运行需求一致性门槛

在将会改变行为的任务标记为进行中之前：

1. 如果计划中存在 ## Requirements Reconciliation 章节，请先阅读。根据内嵌的 ## Research Context（它仍是已提交的需求快照），核对所选研究来源的引用。 仅在步骤 0.2 的差异警告中使用实时研究文件；除非明确执行重新基准，否则 不要用它更改任务需求。重新阅读其他引用权威来源中的相关内容。
2. 仅在用户或项目明确声明优先级层次时才应用该层次。除非明确声明路线图文本 是详细契约，否则应将其视为范围说明。
3. 将任务拟议的行为与引用的需求进行比较。如果二者明显冲突，请输出 ERROR [requirement-conflict]，将任务保留为待处理状态，并停止。在手动模式下， 请求澄清。在 HANDOFF_MODE=1 下，不要提示；返回 handoff_outcome: blocked_external，以便协调器路由该任务，也不要表示实现已完成 或请求评审。不要先实现，再事后改写需求文档。
4. 如果行为取决于彼此独立的选择器、状态、模式或输入形状，请确认任务涵盖 所有适用且受支持的组合，包括验证、持久化、输出／转换和副作用。不要根据 关于某一维度的规则，推断对另一维度的限制。

如果旧计划缺少 ## Requirements Reconciliation，请根据任务、Original Request、 已提交的 Research Context、项目规则以及其中明确引用的任何权威来源执行此门槛。 内嵌的 Research Context 仍优先于其实时差异来源。不要扩展到无关研究。

3.2：标记为进行中

TaskUpdate(taskId, status: "in_progress")

3.3：实现任务

• 阅读相关文件
• 进行必要的更改
• 遵循现有代码模式
• 除非计划包含测试任务，否则不要编写测试
• 不要撰写报告或摘要
• 将需求、研究、路线图、规则和架构文档视为只读，除非当前任务明确要求修改其所属文档。这不妨碍稍后在此工作流中明确允许的事实性上下文维护，但此类更新不得仅为匹配实现而更改行为需求。

3.4：验证实现

• 检查代码能否编译／运行
• 验证功能是否正常
• 修复任何即时问题
• 运行任务指定的验证场景。当有代表性的仓库制品定义契约时，应通过主要路径验证该制品，而不要只依赖合成测试夹具。

3.5：标记为已完成

TaskUpdate(taskId, status: "completed")

3.6：更新计划入口文件中的复选框

完成任务后，立即更新计划入口文件中的复选框 （ultra 对应 index.md）：

# Before

- [ ] Task 1: Create user model

# After

- [x] Task 1: Create user model

此操作为强制要求——复选框必须反映实际进度：

• 使用 Edit 工具将 - [ ] 改为 - [x]
• 每完成一项任务后，立即执行此操作
• 即使之后会提供删除选项，也要执行
• 计划入口文件是进度的真实来源
• 绝不要在 ultra 阶段文件中添加或更新重复的进度复选框

**交接同步（仅限手动模式——当 HANDOFF_MODE 为 1 时跳过）：**如果在步骤 0.2 中提取了 Handoff 任务 ID，则调用 handoff_push_plan，并传入 { taskId: <id>, planContent: <full updated plan text> } 以同步检查清单进度。对于 ultra，请使用步骤 0.2 中定义的 bundle 序列化方式。

3.7：必要时更新已解析的描述文档

如果在实现过程中：

• 添加了新的依赖项／库
• 技术栈发生变化（例如添加 Redis、更换 ORM）
• 添加了新的集成（例如 Stripe、SendGrid）
• 做出了架构决策

→ 更新已解析的描述文档（paths.description，默认值：.ai-factory/DESCRIPTION.md），以反映这些变更：

## Tech Stack

- **Cache:** Redis (added for session storage)

这样可确保已解析的描述文档始终是真实来源。

3.7.1：项目结构发生变化时更新 AGENTS.md 和 ARCHITECTURE.md

如果在实现过程中：

• 创建了新的目录或模块
• 项目结构发生重大变化（新增 src/modules/、新的 API 路由目录等）
• 添加了新的入口点或关键文件

→ 更新 AGENTS.md——刷新“Project Structure”树和“Key Entry Points”表，以反映新增的目录／文件。

→ 更新已解析的架构文档——如果添加了应记录在文件夹结构部分中的新模块或层级。

仅在结构确实发生变化时更新——不要在每项任务后都重写。检查是否创建了当前结构图中尚未列出的新目录。

3.8：检查提交检查点

如果计划中有提交检查点，且当前任务处于某个检查点：

AskUserQuestion: ✅ Tasks <first>-<last> completed. This is a commit checkpoint. Ready to commit? Suggested message: "<conventional commit message>"

Options:
1. Yes, commit now (/aif-commit)
2. No, continue to next task
3. Skip all commit checkpoints

根据选择执行：

• 是，现在提交 → 使用建议的消息调用 /aif-commit，然后继续下一项任务
• 否，继续下一项任务 → 不提交，直接继续下一项任务
• 跳过所有提交检查点 → 在本次 /aif-implement 运行的后续所有检查点中，自动跳过提示并直接继续下一项任务（相当于每次都选择“否，继续下一项任务”）。此项设置仅在当前上下文中有效——执行 /clear 或开启新会话后会重置

3.9：继续下一项任务或暂停

步骤 4：会话持久化

进度会通过 TaskUpdate 自动保存。

暂停：

Current progress saved.

Completed: 4/8 tasks
Next task: #5 - Add pagination support

To resume later, run:
/aif-implement

恢复（下一会话）：

/aif-implement

→ 自动查找下一项未完成的任务

步骤 5：完成

**交接同步（仅限手动模式——当 HANDOFF_MODE 为 1 时完全跳过）：**如果从计划注释中提取了 Handoff 任务 ID，且 HANDOFF_MODE 不为 1：

1. 调用 handoff_push_plan，并传入 { taskId: <id>, planContent: <final updated plan text> }；对于 ultra，请序列化完整的 bundle。
2. 如果 HANDOFF_SKIP_REVIEW 为 1：调用 handoff_sync_status，并传入 { taskId: <id>, newStatus: "done", sourceTimestamp: "<current UTC time in ISO 8601 format>", direction: "aif_to_handoff", paused: false }。
3. 否则：调用 handoff_sync_status，并传入 { taskId: <id>, newStatus: "review", sourceTimestamp: "<current UTC time in ISO 8601 format>", direction: "aif_to_handoff", paused: true }。

所有任务完成后：

## Implementation Complete

All 8 tasks completed.

Branch: feature/product-search
Plan artifact: .ai-factory/plans/feature-product-search.md
Files modified:
- src/services/search.ts (created)
- src/api/products/search.ts (created)
- src/types/search.ts (created)
Documentation: updated existing docs | created docs/<feature-slug>.md | skipped by user | warn-only (Docs: no/unset)

What's next?

1. 🔍 /aif-verify — Verify nothing was missed (recommended)
2. 💾 /aif-commit — Commit the changes directly

检查 ROADMAP.md 进度：

如果已解析的路线图文档存在：

1. 读取该文档 1.1. 如果计划入口文件包含 ## Roadmap Linkage，且其中的里程碑不为 none，则优先使用该里程碑进行完成标记
2. 检查已完成的工作是否对应某个未勾选的里程碑
3. 如果对应——将其标记为 [x]，并使用当天日期在 Completed 表中添加条目
4. 告知用户标记为已完成的里程碑

上下文维护（工件）

仅在有具体内容需要记录时执行此步骤。

DESCRIPTION.md（允许在此命令中修改）：

• 如果此计划引入了新的依赖项/集成，或更改了技术栈，请仅根据实际差异更新已解析的描述工件。
• 不要重写无关章节。

ARCHITECTURE.md + AGENTS.md（允许在此命令中修改）：

• 如果添加了新模块/层/文件夹（或更改了依赖规则），请更新已解析的架构工件，以反映新的结构和约束。
• 如果你维护 AGENTS.md 的结构图或入口点，仅在其内容有误时更新。

ROADMAP.md（允许修改，但有限制）：

• 有明确证据时，此命令可以标记里程碑已完成。
• 如果里程碑映射不明确，输出 WARN [roadmap] ... 并建议用户使用以下命令：
  • /aif-roadmap check
  • 或 /aif-roadmap <short update request>

RULES.md（此命令中不允许修改）：

• 绝不编辑 /aif-implement 中已解析的 paths.rules_file 工件。
• 如果在实现过程中发现了可重复的惯例/陷阱，请提出最多 3 条候选规则，并请用户通过 /aif-rules 添加。
• 不要自动调用 /aif-rules（该命令由用户调用）。

如果存在候选规则：

AskUserQuestion: Capture new project rules in the resolved RULES.md artifact?

Options:
1. Yes — output `/aif-rules ...` commands (recommended)
2. No — skip

文档策略检查点（完成后、清理计划前）：

读取计划入口点设置 Docs: yes/no。

如果计划设置为 Docs: yes：

AskUserQuestion: Documentation checkpoint — how should we document this feature?

Options:
1. Update existing docs (recommended) — invoke /aif-docs
2. Create a new feature doc page — invoke /aif-docs with feature-page context
3. Skip documentation

处理方式：

• 选项 1 → 调用 /aif-docs，根据已完成的工作更新 README/文档
• 选项 2 → 调用 /aif-docs 并提供上下文，以创建 docs/<feature-slug>.md，包含以下章节（Summary、Usage/user-facing behavior、Configuration、API/CLI changes、Examples、Troubleshooting、See Also），并在 README 文档表格中添加链接
• 选项 3 → 不调用 /aif-docs；输出 WARN [docs] Documentation skipped by user

如果计划设置为 Docs: no 或未设置：

• 不要显示强制性的文档检查点提示
• 不要自动调用 /aif-docs
• 输出 WARN [docs] Docs policy is no/unset; skipping documentation checkpoint

最终完成输出中必须始终包含文档处理结果：

• Documentation: updated existing docs
• Documentation: created docs/<feature-slug>.md
• Documentation: skipped by user
• Documentation: warn-only (Docs: no/unset)

完成后处理计划工件：

• 如果是已解析的快速计划路径（来自 /aif-plan fast）：

  AskUserQuestion: Would you like to delete the resolved fast plan file? (It's no longer needed)
  
  Options:
  1. Yes, delete it
  2. No, keep it
  

  根据选择处理：

  • “是，删除” → 删除文件：

    rm <resolved fast plan path>
    

  • “否，保留” → 保留文件不变，继续下一步

• 如果是以分支命名的完整文件或 ultra bundle 目录：

  • 保留——用于记录已完成的工作
  • 如有需要，用户可以在合并前删除

检查当前是否在 git worktree 中运行：

检测 worktree 上下文：

# If .git is a file (not a directory), we're in a worktree
[ -f .git ]

如果当前位于 worktree 中，请提供合并回去并清理的选项：

You're working in a parallel worktree.

  Branch:    <current-branch>
  Worktree:  <current-directory>
  Main repo: <main-repo-path>

AskUserQuestion: Would you like to merge this branch into the configured base branch and clean up?

Options:
1. Yes, merge and clean up (recommended)
2. No, I'll handle it manually

根据选择处理：

• “是，合并并清理” → 按照下方的 Worktree Merge 流程操作
• “否，我会手动处理” → 显示提醒：

  To merge and clean up later:
    cd <main-repo-path>
    git merge <branch>
    /aif-plan --cleanup <branch>
  

Worktree Merge

1. 确保所有内容均已提交 — 检查 git status。如果存在未提交的更改，建议先运行 /aif-commit 并等待。

2. 获取仓库根路径：

   MAIN_REPO=$(git rev-parse --git-common-dir | sed 's|/\.git$||')
   BRANCH=$(git branch --show-current)
   

3. 切换到仓库根目录：

   cd "${MAIN_REPO}"
   

4. 合并分支：

   git checkout <configured-base-branch>
   git pull origin <configured-base-branch>
   git merge "${BRANCH}"
   

   如果发生合并冲突：

   ⚠️  Merge conflict detected. Resolve manually:
     cd <main-repo-path>
     git merge --abort   # to cancel
     # or resolve conflicts and git commit
   

   → 在此处停止，不要继续清理。

5. 移除 worktree 和分支（仅在合并成功后）：

   git worktree remove <worktree-path>
   git branch -d "${BRANCH}"
   

6. 确认：

   ✅ Merged and cleaned up!
   
     Branch <branch> merged into <configured-base-branch>.
     Worktree removed.
   
   You're now in: <main-repo-path> (<configured-base-branch>)
   

→ 停止 — worktree 已合并并移除，无需执行其他步骤。

最后一步 — 验证或提交

AskUserQuestion: All tasks complete. What's next?

Options:
1. Verify first — Run /aif-verify to check completeness (recommended)
2. Skip to commit — Go straight to /aif-commit

根据选择：

• “先验证” → 调用 /aif-verify → 完成后，继续执行下方的上下文清理
• “跳过并提交” → 调用 /aif-commit → 完成后，继续执行下方的上下文清理

上下文清理（验证或提交后）：

如有需要，建议用户释放上下文空间：使用 /clear（完全重置）或 /compact（压缩历史记录）。

重要：不要生成摘要报告，不要编写分析文档，也不要执行收尾任务。

命令

开始／继续实现

/aif-implement

从下一个未完成的任务继续。

列出可用计划

/aif-implement --list

列出已解析的快速／修复计划路径，以及当前分支的完整／超长产物（包括顺序标识符），然后退出，不执行实现。

使用指定的计划产物

/aif-implement @my-custom-plan.md
/aif-implement @.ai-factory/plans/feature-user-auth.md status
/aif-implement @.ai-factory/plans/feature-user-auth status

使用提供的计划文件、超长计划目录或超长计划 index.md，而不是自动检测计划文件或分支默认产物。

内联实现（无计划）

/aif-implement --without-plan add GET /healthz endpoint returning {"status":"ok"}
/aif-implement --without-plan rename LogLevel.VERBOSE to LogLevel.TRACE --docs=yes

一次性执行小型任务，不使用任何计划文件。不能与 @plan-file、status 或任务 ID 同时使用。不会创建 FIX_PLAN.md 或补丁。默认文档策略为 warn；传入 --docs=yes 可运行文档检查点，传入 --docs=no 可关闭警告。完整流程请参阅 Step 0.inline。

从指定任务开始

/aif-implement 5

从任务 #5 开始（适用于跳过任务或重新执行任务）。

仅检查状态

/aif-implement status

显示进度，但不执行任务。

执行规则

应执行：

• ✅ 一次执行一个任务
• ✅ 开始任务前，将其标记为 in_progress
• ✅ 完成任务后，将其标记为 completed
• ✅ 遵循现有代码规范
• ✅ 遵循 /aif-best-practices 指南（命名、结构、错误处理）
• ✅ 创建任务说明中提到的文件
• ✅ 处理任务中提到的边界情况
• ✅ 如果任务不明确，暂停并询问

不应执行：

• ❌ 编写测试（除非任务列表明确要求）
• ❌ 创建报告文件
• ❌ 创建摘要文档
• ❌ 添加计划中没有的任务
• ❌ 未经用户许可跳过任务
• ❌ 将未完成的任务标记为已完成
• ❌ 违反已解析架构产物中关于文件放置和模块边界的规范

产物归属边界

• 此命令的主要归属内容：任务执行状态和计划进度复选框。
• 允许更新的上下文产物：已解析的描述产物、已解析的架构产物，以及在实现证据支持时，已解析路线图产物中的路线图里程碑完成状态。
• 此命令默认只读的上下文：已解析的 paths.rules_file、配置的 paths.research，以及计划入口链接的任何确切研究来源。
• 上下文检查发现应仅通过 WARN／ERROR 输出传达；这不会取代下方要求的详细实现日志记录规则。

有关进度显示格式、阻塞问题处理、会话连续性示例和完整流程示例 → 请参阅 references/IMPLEMENTATION-GUIDE.md

关键规则

1. 除非任务列表明确包含测试任务，否则绝不编写测试
2. 完成后绝不创建报告或摘要文档
3. 开始工作前始终将任务标记为 in_progress
4. 完成后始终将任务标记为 completed
5. 始终更新计划文件中的复选框——任务完成后立即将 - [ ] → - [x]
6. 保留进度——任务应跨会话保留
7. 一次只处理一个任务——只专注于当前任务

关键：日志记录要求

实现代码时始终添加详细日志。 有关日志指南、模式和管理要求 → 请阅读 references/LOGGING-GUIDE.md

关键规则：记录函数的进入／退出、状态变更、外部调用和错误上下文。使用结构化日志和可配置的日志级别（LOG_LEVEL 环境变量）。

不要为了“保持代码整洁”而跳过日志记录——实现期间必须添加详细日志，但日志必须可配置。