特定任务（spec-task）

Spec-Task 任务管理 核心原则 所有非平凡任务必须通过 spec-task 管理，不存在"太简单不需要"的例外。 任务生命周期每一步都必须显式转换，不可跳过状态。 四文档必须按拓扑序在 running 之前完成：brief → spec → plan → checklist。 没有 checklist 的执行 = 不可追溯 = 验收失败。 验收时所有 criteria 通过且任务为 running，自动转为 completed。

工作流程（8步）

• config_merge → 检查/合并项目配置
• task_recall → 搜索历史经验（keywords 必填，避免重复劳动）
• task_create → 创建任务（task_name 必填，生成 status.yaml）
• 填充文档 → brief → spec → plan → checklist（按拓扑序）
• task_transition → assigned → running（开始执行）
• task_log → 记录运行时事件（error/alert/add-block/remove-block/output/retry）
• task_verify → 验收管理（add-criterion → finalize；finalize 自动触发 completed）
• task_archive → 归档（生成 history + lessons，支持 dry_run）

状态机（8种状态 · 14条转换） pending ──→ assigned ──→ running ──→ completed (终态) │ │ │ └── cancelled ← ─ ─ ─ ─ ┘ running → failed → running running → blocked → pending running → revised → running running → revised → pending running → running (进度刷新)

起始状态 目标状态 说明 pending assigned 任务分配 pending cancelled 取消 assigned running 开始执行 assigned cancelled 取消 running completed 完成（终态） running failed 失败 running blocked 阻塞 running cancelled 取消 running revised 需修订 running running 进度刷新 failed running 重试 blocked pending 解除阻塞，回到待分配 revised running 修订后重新执行 revised pending 修订后回到待分配

四文档拓扑序 brief（无依赖）→ spec（依赖 brief）→ plan（依赖 brief）→ checklist（依赖 spec + plan） brief.md: 问题定义、目标、约束条件、成功标准 spec.md: 技术方案、接口设计、数据结构 plan.md: 实施计划、步骤分解、依赖关系 checklist.md: 可执行检查项，格式：- [x] 1.1 步骤描述

5级检测器 级别 名称 条件 行为 L1 none spec-task/ 不存在 自动初始化 L2 empty 目录存在但无任务 等待任务创建 L3 skeleton 有 status.yaml 但缺文档 提醒补全文档 L4 in_progress 有非终态任务且文档完整 正常推进 L5 all_done 所有任务终态 建议归档

子 Agent 合规 作为子 agent（被 coordinator 通过 sessions_spawn 派发）时： 必须使用 spec-task，不存在例外。 第一步调用 config_merge，第二步调用 task_recall，第三步调用 task_create。 创建后必须填充 brief → spec → plan → checklist 全部四文档。 只有 checklist 中第一个步骤勾选后，才能开始实际执行。 工作区已有 spec-task/ 目录时，优先用 task_resume 检查可恢复任务。

Hook 系统 before_prompt_build: 检测工作区状态，注入 prependContext 提醒。 before_tool_call: 对 task_create、config_merge、task_archive、task_recall 自动注入 project_root 参数。

工具速查表 工具 必填参数 用途 config_merge — 合并项目配置（可选 project_root, format） task_recall keywords 搜索历史经验（可选 project_root, agent_workspace, top） task_create task_name 创建任务（可选 project_root, title, assigned_to, parent, depth） task_transition task_dir, status 状态流转（可选 revision_type, trigger, summary, impact, resume_from, block_type, block_reason, assigned_to, changes, affected_steps） task_log task_dir, action 记录事件；action: error / alert / add-block / remove-block / output / retry task_verify task_dir, action 验收管理；action: add-criterion / finalize / get task_resume task_dir 断点恢复，返回 next_action 决策 task_archive task_dir 归档（可选 agent_workspace, project_root, agent_name, dry_run）

验收状态 标准（criterion）状态：pending | passed | failed 验收流程：add-criterion（添加标准）→ get（查看结果）→ finalize（汇总确认） finalize 时若全部 passed 且任务 status 为 running，自动转为 completed。

错误码 错误码 场景 TASK_NOT_FOUND 任务目录不存在 TASK_ALREADY_EXISTS 同名任务已存在 INVALID_TRANSITION 非法状态转换 DUPLICATE_BLOCK 重复阻塞记录 BLOCK_NOT_FOUND 阻塞记录不存在 DUPLICATE_OUTPUT 重复产出记录 NO_CRITERIA 无验收标准时执行 finalize CONFIG_NOT_FOUND 配置文件不存在 INVALID_PARAMS 参数校验失败 INTERNAL_ERROR 内部错误 LOCK_ACQUIRE_FAILED 文件锁获取失败

配置参考（SpecTaskConfig） context: "项目描述（可选）" runtime: allow_agent_self_delegation: true # 允许 Agent 自行分配 task_timeout: 3600 # 任务超时（秒） failure_policy: soft_block: true # 失败后是否允许继续 hard_block: false # 失败后是否强制阻塞 verify_failed: true # 验证失败是否触发策略 on_exhausted: "cancel" # 重试耗尽后的动作 archive: auto_archive: true # 是否自动归档 record_history: true # 是否记录历史 generate_lessons: true # 是否生成经验教训