Spec-Task 任务管理#

核心原则#

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

工作流程（8步）#

text

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

状态机（8种状态 · 14条转换）#

text

pending ──→ assigned ──→ running ──→ completed   (终态)
    │            │            │
    └── cancelled ← ─ ─ ─ ─ ┘
                      running → failed → running
                      running → blocked → pending
                      running → revised → running
                      running → revised → pending
                      running → running   (进度刷新)

起始状态目标状态说明pendingassigned任务分配pendingcancelled取消assignedrunning开始执行assignedcancelled取消runningcompleted完成（终态）runningfailed失败runningblocked阻塞runningcancelled取消runningrevised需修订runningrunning进度刷新failedrunning重试blockedpending解除阻塞，回到待分配revisedrunning修订后重新执行revisedpending修订后回到待分配

四文档拓扑序#

text

brief（无依赖）→ spec（依赖 brief）→ plan（依赖 brief）→ checklist（依赖 spec + plan）

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

5级检测器#

级别名称条件行为L1nonespec-task/ 不存在自动初始化L2empty目录存在但无任务等待任务创建L3skeleton有 status.yaml 但缺文档提醒补全文档L4in_progress有非终态任务且文档完整正常推进L5all_done所有任务终态建议归档

子 Agent 合规#

作为子 agent（被 coordinator 通过 sessions_spawn 派发）时：

1. 必须使用 spec-task，不存在例外。
2. 第一步调用 config_merge，第二步调用 task_recall，第三步调用 task_create。
3. 创建后必须填充 brief → spec → plan → checklist 全部四文档。
4. 只有 checklist 中第一个步骤勾选后，才能开始实际执行。
5. 工作区已有 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_recallkeywords搜索历史经验（可选 project_root, agent_workspace, top）task_createtask_name创建任务（可选 project_root, title, assigned_to, parent, depth）task_transitiontask_dir, status状态流转（可选 revision_type, trigger, summary, impact, resume_from, block_type, block_reason, assigned_to, changes, affected_steps）task_logtask_dir, action记录事件；action: error / alert / add-block / remove-block / output / retrytask_verifytask_dir, action验收管理；action: add-criterion / finalize / gettask_resumetask_dir断点恢复，返回 next_action 决策task_archivetask_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无验收标准时执行 finalizeCONFIG_NOT_FOUND配置文件不存在INVALID_PARAMS参数校验失败INTERNAL_ERROR内部错误LOCK_ACQUIRE_FAILED文件锁获取失败

配置参考（SpecTaskConfig）#

yaml

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              # 是否生成经验教训