aim-coordinator-guide

name	aim-coordinator-guide
description	Coordinator decision entry for AIM Task Pool maintenance; form an approvable POST /tasks/batch operations plan from Manager output, latest baseline facts, current Tasks, and rejected Task feedback before applying atomic Task Pool writes.

aim-coordinator-guide

概述

这个 skill 是 AIM Coordinator 维护 Task Pool 时的决策入口。Coordinator 的产物不是泛化分析报告，也不是直接执行开发工作，而是一个等待用户批准的 POST /tasks/batch operations 计划。Manager 评估信号的产品语义见 docs/manager-evaluation-signal.md。

POST /tasks/batch operations 用来对同一个 project_id 的 Task Pool 做原子写入。每一项只能是 create 或 delete；用户批准后，一次性提交到服务端，任一 operation 失败则整体回滚。

何时使用

• 需要根据 AIM Manager 输出、最新基线、当前 Task Pool 与 rejected Task 反馈决定 Task Pool 后续写入时。
• 需要判断应新增哪些 Task、删除哪些未完成 Task，或用 rejected Task 失败原因重新规划后续写入时。
• 需要把 Coordinator 判断收敛成可审批的 Task Pool batch operations 时。

何时不使用

• 不用它直接执行 Developer Task、修改代码、创建 PR 或跟进 Developer 生命周期。
• 不用它替代 aim-verify-task-spec 判断候选 Task Spec 是否仍可执行。
• 不用它替代 aim-create-tasks；不得直接调用 POST /tasks 逐条写入。
• 不用它实现真实 Coordinator 调度器、后台 worker 或自动执行器。

必需输入

• AIM Manager 的最新输出：差距分析、坐标系、迭代方向建议、开放问题。
• 最新 origin/main 基线事实：README、代码、文档、已合并 PR 与可只读验证的当前状态。
• 当前 Task Pool：所有未完成 Task 的标题、Spec、状态、依赖、worktree_path、pull_request_url、source_metadata、已知阻塞与目标边界。
• rejected Task 反馈：失败原因、失败发生的基线事实、是否暴露了前提缺失或目标歧义。

如果这些输入缺失到影响目标、范围、验收、边界或优先级，必须升级给 Director 澄清；不得创建澄清类 Developer Task 来替代目标层决策。

上下文获取纪律

Coordinator session prompt 可能预置 dimensions、latest dimension_evaluations、Active Task Pool、rejected feedback 与 baseline 摘要，但这些内容只是启动 / 历史便利，不是完整事实源。它可能被截断、过期，或为了降低 prompt 体积被刻意瘦身；Coordinator 在提出任何 POST /tasks/batch operations 前，必须按需重新获取当前上下文。

形成 batch 计划前至少重新获取并核对：

• dimensions：使用 GET ${SERVER_BASE_URL:-http://localhost:8192}/dimensions?project_id=${project_id} 获取当前规划坐标系。
• latest dimension evaluations：对每个相关 dimension 使用 GET ${SERVER_BASE_URL:-http://localhost:8192}/dimensions/${dimension_id}/evaluations，只把与最新 origin/main 匹配的 evaluation 当作当前证据；旧 commit 的 evaluation 只能作为历史信号。
• Active Task Pool：使用 GET ${SERVER_BASE_URL:-http://localhost:8192}/tasks?project_id=${project_id}，筛出未完成 Tasks，并读取 dependencies、worktree_path、pull_request_url、source_metadata、source_baseline_freshness 与 session / PR 事实。
• rejected Task feedback：使用 GET ${SERVER_BASE_URL:-http://localhost:8192}/tasks?project_id=${project_id}&status=rejected，读取 result 与 source_metadata.task_spec_validation，把失败原因作为新规划输入，而不是简单重试。
• baseline facts：执行 git fetch origin 后读取 origin/main commit、最近提交、README、代码与文档当前状态；不要把 prompt 中的 baseline 摘要当作当前基线。
• PR / worktree state：对已有 worktree_path 或 pull_request_url 的未完成 Task，用本地 git 与 gh pr view / gh pr checks 判断是否已有在途执行、是否落后、是否已被 PR 覆盖；不得只因 Manager refresh 或 prompt 里的旧描述替换 PR-backed 工作。

这样做的原因是 batch 写入会原子改变 Task Pool；如果依据过期 prompt，容易创建重复 coverage、删除仍在途工作、忽略 rejected 反馈，或把旧 evaluation 当作当前 README 差距。按需获取当前事实后，才能判断 create / delete / noop 是否仍贴合最新基线。

历史说明

较长的 Coordinator prompt 最初是为了把 freshness、overlap、rejected-feedback 与 validation guardrails 直接放进自治规划 session，降低 Agent 在未主动查上下文时创建 stale 或 duplicate Task、重复 rejected 模式、或替换在途工作的概率。现在这些内容只应作为 bootstrap guardrails；真实 POST /tasks/batch 决策仍必须以 AIM API 与本地 repo / GitHub 检查的当前结果为准。

输出：POST /tasks/batch operations

Coordinator 必须输出一个可审批的 POST /tasks/batch operations 计划，不能只输出建议、分析或讨论文本。

每个条目必须包含：

• type：只能是 create 或 delete。
• reason：为什么这个写入能推进最新基线，或为什么旧 Task 应从未完成视图移除。
• source：触发依据，例如 Manager 差距、最新基线事实、Task Pool 冲突、rejected Task 失败原因。

Create 条目还必须包含：

• task.task_id：调用方生成并传入的 UUID。
• task.title：候选 Task 标题。
• task.spec：完整五段式候选 Task Spec，而不是标题或实现提示。
• dependencies：候选 Task 创建时应携带的 Task 依赖；如果没有依赖，写空列表。
• source_metadata：来源信息，例如 Manager 评估、Coordinator session 或 rejected 反馈；每个 create operation 必须先经过最小 Coordinator Task Spec validation entrypoint，取得 pass / waiting_assumptions / failed 之一的独立 Task Spec validation 结论，并把可持久化证据保存在 source_metadata.task_spec_validation。
• source_metadata.dimension_id 与 source_metadata.dimension_evaluation_id：用于依赖、冲突、重复覆盖判断的规划证据。它们必须与 validation evidence 分开保留；source_metadata.task_spec_validation 里的 source gap 不能替代这类 planning evidence。
• source_metadata.current_task_pool_coverage：当前 Task Pool 是否已有未完成覆盖，以及覆盖/未覆盖的依据。
• source_metadata.dependency_rationale：候选 Task 与现有未完成 Task 的依赖关系；无依赖时也要说明为什么无依赖。
• source_metadata.conflict_duplicate_assessment：候选 Task 与现有未完成 Task 是否重复、冲突或覆盖重叠的判断。
• source_metadata.unfinished_task_non_conflict_rationale：为什么该候选不会覆盖或冲突于现有未完成 Tasks。

source_metadata.task_spec_validation 必须至少保留：

• validation_source：校验来源，例如 aim-verify-task-spec。
• validated_at 或 validation_session_id：校验发生时间或可追踪 session。
• conclusion：只能是 pass、waiting_assumptions 或 failed；只有 pass 可以进入 POST /tasks/batch。
• conclusion_summary：校验结论摘要，且进入创建时结论必须是可继续推进的 pass。
• dimension_evaluation_id、dimension_id 或等价 source gap：说明该 validation 对应哪个 Manager dimension_evaluation/source gap。
• blocking_assumptions：当结论是 waiting_assumptions 时，记录阻断创建的待确认前提，并作为 planning feedback 回到 Coordinator 规划。
• failure_reason：当结论是 failed 时，记录失败原因，并作为 planning feedback 回到 Coordinator 规划。

Delete 条目还必须包含：

• task_id：要删除的未完成 Task UUID。
• delete_reason：删除依据，例如已被最新基线吸收、被更清晰的替代 Task 覆盖、与当前 README 或 Manager 方向冲突、或已不可执行；必须包含未完成 Task 的 worktree/PR 分类，以及 stale、conflict 或 baseline absorbed 判断。保留 / noop 的候选也必须保留明确 rationale。

Batch 规则

• 顶层必须包含唯一 project_id，不得跨 project 原子写入。
• operations 按数组顺序执行。
• 同一 batch 内禁止重复 task_id，避免顺序依赖。
• create.task.task_id 必须是调用方传入的 UUID。
• delete 只允许删除未完成 Task；禁止删除 resolved / rejected 终态 Task。

Create 判断规则

产生 Create 写入意图的条件：

• Manager 输出指出 README 目标与最新基线之间存在可执行差距。
• 当前 Task Pool 没有覆盖该差距，或已有 Task 的范围不足以推进该差距。
• rejected Task 暴露了可通过后续基线增量修复的前提缺口。
• 最新基线出现了新的事实，需要补一个明确的后续迭代 Task 才能继续逼近 README。

Create 禁止项：

• 禁止用含糊目标、开放问题或需要 Director 决策的内容生成 Developer Task。
• 禁止把 README 或 Manager 输出不清晰的问题包装成“澄清类 Developer Task”。
• 禁止跳过 aim-verify-task-spec 自行认定候选 Spec 可创建。
• 禁止把泛化 optimizer-loop placeholder 当作 validation evidence；validation evidence 必须对应具体候选 Spec 和具体 dimension_evaluation/source gap。
• 禁止未经用户批准直接创建 Task。
• 禁止直接调用 POST /tasks 逐条写入；批准后的原子写入必须通过 POST /tasks/batch。

Delete 判断规则

未完成 Task 执行产物分类门禁

Coordinator 在形成任何 delete 或 create+delete 替换前，必须先按可观察字段把每个未完成 Task 分成三类，并把分类写入判断理由：

• worktree_path = null 且 pull_request_url = null：没有执行产物。只有当该 Task 的前提已经被最新基线、Manager dimension source 或 rejected 反馈明确证明 stale、冲突或不可执行时，才允许用更准确的 create + delete batch 替换；不得把泛化 optimizer-loop placeholder、低优先级或抽象迭代建议当作 stale 证据。
• worktree_path 已记录且 pull_request_url = null：已有 Developer lane 执行产物但尚未上报 PR。默认保留并进入 evaluate_existing_tasks / follow-up 路径；除非存在明确 terminal/rejected/Director 决策或 scope 冲突证据，否则不得用 Manager refresh 生成替换 batch。
• pull_request_url 已记录：PR-backed 在途工作。默认保留并进入 evaluate_existing_tasks / follow-up 路径；不得只因新 baseline、Manager 新分数或更优描述就删除、重复创建或替换，除非存在明确 terminal/rejected/Director 决策或 scope 冲突证据。

产生 Delete 写入意图的条件：

• 未完成 Task 的内容已被最新基线吸收，不再代表待推进差距。
• 未完成 Task 被更清晰、更小或更准确的 Task 覆盖。
• 未完成 Task 与当前 README、Manager 方向或最新基线事实冲突。
• 未完成 Task 已不可执行，且等待后续基线自然恢复不再合理。
• rejected Task 反馈表明旧 Task 的失败原因已经使其原目标失效。

Delete 禁止项：

• 禁止删除已 resolved 的 Task 来维护历史记录；Task Pool 是未完成视图，不是历史系统。
• 禁止只因旧 Task 排序较低、暂时不优先或实现较难就删除。
• 禁止在没有明确 target_task_id 和 delete_reason 时执行删除。
• 禁止把 Delete 当作静默放弃；必须说明它如何让 Task Pool 更贴合最新基线。

Rejected 反馈闭环

rejected Task 的失败原因是新的基线规划输入。Coordinator 必须先判断失败原因属于哪一类：

• 前提缺失但可修复：产生修复前提的 Create，并说明它如何解除失败原因。
• 原 Task 已失效：产生 Delete，必要时再用更准确的 Create 替代。
• README、Manager 输出或优先级不清晰：升级给 Director 澄清，不产生 Developer Task。
• 失败原因超出当前 README 目标：不创建 scope 外 Task，必要时记录为 Director 决策输入。

不得把 rejected Task 反馈简单重试为同一个 Task，也不得忽略失败原因继续创建同类失效任务。

批准后路由

用户批准 POST /tasks/batch operations 后：

1. 对每个 create，先进入最小 Coordinator Task Spec validation orchestration：用 aim-verify-task-spec 校验 task.spec，并把候选归类为 pass、waiting_assumptions 或 failed。
2. pass：生成或规范化 source_metadata.task_spec_validation，至少包含 validation source、validated_at 或 validation_session_id、conclusion = pass、conclusion_summary、dimension_evaluation/source gap；同时保留独立的顶层 dimension_id / dimension_evaluation_id、current_task_pool_coverage、dependency_rationale、conflict_duplicate_assessment、unfinished_task_non_conflict_rationale planning evidence。
3. waiting_assumptions：不得构造或提交包含该候选的 POST /tasks/batch；把 blocking_assumptions 作为 Coordinator planning feedback。
4. failed：不得构造或提交包含该候选的 POST /tasks/batch；把 failure_reason 作为 Coordinator planning feedback。
5. 只有所有 create 校验结论均为 pass 且已写入 source_metadata.task_spec_validation 时，才提交 POST /tasks/batch。
6. 对每个 delete，只在目标 Task 未完成且删除原因明确时保留在 batch 中。
7. delete-only batch 不要求 Task Spec validation，因为没有候选 Task Spec；它仍必须满足目标 Task、删除理由和 batch guardrails。

Coordinator 不得在这个阶段接管 Developer 生命周期；已创建的 Task 后续执行必须由 aim-developer-guide 覆盖。

README / Manager 不清晰门禁

如果 README 或 Manager 输出的不清晰会影响以下任一内容，Coordinator 必须升级给 Director 澄清：

• Task Spec 的目标。
• Task Spec 的范围。
• Task Spec 的验收方式。
• Task Spec 的边界或 Non-Goal。
• Task 之间的优先级或依赖方向。

升级时输出具体不清晰点、为什么它会改变 Task Pool 写入、以及需要 Director 决策的问题。不得创建澄清类 Developer Task，也不得用自己的猜测填补 Director 输入。

自检清单

• 输出是 POST /tasks/batch operations，而不是泛化分析报告。
• 每个 operation 都是 create 或 delete。
• 每个 create 都有调用方生成的 UUID 和完整五段式候选 Task Spec。
• 每个 create 都有独立 Task Spec validation pass 结论，并已在 source_metadata.task_spec_validation 保留 validation_source、validated_at 或 validation_session_id、conclusion = pass、conclusion_summary 与 dimension_evaluation/source gap。
• 每个 create 都在 source_metadata 顶层保留独立 planning evidence：dimension_id、dimension_evaluation_id、current_task_pool_coverage、dependency_rationale、conflict_duplicate_assessment、unfinished_task_non_conflict_rationale；没有用 task_spec_validation 替代 dependency/conflict planning evidence。
• 没有直接调用 POST /tasks 逐条写入，也没有跳过用户批准。
• validation 失败或 waiting_assumptions 的候选 create 不得进入 POST /tasks/batch，失败原因已作为 rejected/planning feedback 输入下一轮规划。
• delete-only batch 不要求 Task Spec validation。
• 不得把泛化 optimizer-loop placeholder 当作 validation evidence。
• 每个 delete 都有明确 task_id 和 delete_reason，并保留 worktree/PR 分类、stale/conflict/baseline absorbed 理由；每个 keep/noop 都有明确保留 rationale。
• rejected Task 失败原因已被纳入后续规划。
• README 或 Manager 输出不清晰且会影响目标、范围、验收、边界或优先级时，已升级 Director 澄清。
• 没有修改 Developer 生命周期规则，也没有把 Coordinator Guide 扩展成调度器或执行器。