ak-task

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ak-task — Task Lifecycle

ak-task — 任务生命周期

Create a task, assign it, then monitor → review → reject/complete.

创建任务、分配任务，然后执行监控 → 审核 → 拒绝/完成流程。

Identity

身份配置

This is a leader workflow.

ak

says no leader identity exists for the current runtime, create one first:

bash

ak identity create --username <username> [--name <name>]

The leader chooses its own username and optional full name.

这是一个负责人工作流。

如果

ak

提示当前运行环境不存在负责人身份，请先创建一个：

bash

ak identity create --username <username> [--name <name>]

负责人可自行选择用户名和可选的全名。

Input

输入解析

Parse the user's input:

What — feature description or bug report (required)
Board — which board (if not specified, use the first board)
Priority — infer from context, default to medium

解析用户输入内容：

任务内容 — 功能描述或Bug报告（必填）
看板 — 指定看板（未指定则使用第一个看板）
优先级 — 根据上下文推断，默认中等优先级

Phase 1: Create & Assign

第一阶段：创建与分配

Step 1: Context

步骤1：上下文准备

bash

ak get board                   # pick the right board
ak get agent                   # available agents
ak get repo                    # registered repos

If there's only one board, use it. Otherwise ask which board.

bash

ak get board                   # 选择合适的看板
ak get agent                   # 查看可用Agent
ak get repo                    # 查看已注册仓库

如果只有一个看板，直接使用；否则询问用户选择哪个看板。

Step 2: Investigate

步骤2：前置调研

Before creating the task, understand what's involved:

Read CONTRIBUTING.md in the target repo to understand contribution requirements
Read relevant source files to understand current implementation
Identify which files need to change
Check for existing related tasks:
```
ak get task --board <board-id>
```

创建任务前，先了解相关信息：

阅读目标仓库的CONTRIBUTING.md，了解贡献要求
阅读相关源码文件，理解当前实现逻辑
确定需要修改的文件
检查是否存在相关现有任务：
```
ak get task --board <board-id>
```

Step 3: Confirm with User

步骤3：与用户确认

Use

AskUserQuestion

to interactively resolve any uncertainties before creating the task. For each ambiguous point, present options for the user to choose from:

Scope unclear — present 2-3 scope interpretations as options, each with a preview showing what files/changes are involved
Multiple approaches — present implementation strategies as options with trade-off descriptions
Priority/agent/repo ambiguous — present choices when there are multiple candidates
Dependencies uncertain — present options about whether to depend on or parallelize with related tasks

Keep iterating — each answer may reveal new questions. Only proceed to create when all points are resolved and the user has confirmed the final task spec.

If nothing is ambiguous (simple, clear-cut request), skip straight to the task preview below.

使用

AskUserQuestion

工具交互式解决所有不确定点后再创建任务。针对每个模糊点，提供选项供用户选择：

范围不明确 — 提供2-3种范围解读选项，每个选项附带涉及文件/变更的预览
多种实现方案 — 提供不同实现策略选项，并说明各方案的利弊
优先级/Agent/仓库不明确 — 存在多个候选时提供选择项
依赖关系不确定 — 提供是否依赖相关任务或并行执行的选项

持续迭代确认 — 用户的每个回答可能会引出新问题。只有所有要点都明确且用户确认最终任务规格后，才能继续创建任务。

如果请求简单明确（无模糊点），可直接跳过此步骤，进入下方的任务预览环节。

Step 4: Preview & Create Task

步骤4：任务预览与创建

Before creating, show the user the exact task that will be created using

AskUserQuestion

. Format the preview as:

📋 Task Preview

Title: <concise action phrase>
Board: <board-name>
Repo: <repo-name>
Agent: <agent-name>
Priority: <priority>
Labels: <labels>
Depends on: <task-ids or "none">

创建前，使用

AskUserQuestion

向用户展示即将创建的完整任务内容。预览格式如下：

📋 任务预览

标题：<简洁动作短语>
看板：<看板名称>
仓库：<仓库名称>
Agent：<Agent名称>
优先级：<优先级>
标签：<标签>
依赖任务：<任务ID或“无”>

Goal

目标

<一句话描述>

Files

涉及文件

<file path> — <what changes>

<文件路径> — <变更内容>

Spec

规格

<具体行为：输入、输出、边界情况、错误处理>

Checks

检查项

<verifiable condition — reviewer will check each one in Gate 2>

Examples by task type:

API: "POST /api/items returns 201 with { id, name }"
API: "empty name returns 400 with validation error"
UI: "clicking Submit creates the item and navigates to detail page"
UI: "empty form shows inline validation, submit button stays disabled"
CLI: "ak get task --board xxx prints task table with status column"

Create this task? (y/n)


Everything from `## Goal` through `## Checks` is the exact text that will be passed to `--description`. The header fields above it (Title, Board, Agent, etc.) are metadata for display only — do not include them in `--description`. The user must see the full description before it's sent to the agent.

**On confirmation**, create the task:

```bash
ak create task \
  --board <board-id> \
  --repo <repo-id> \
  --assign-to <agent-id> \
  --title "<concise action phrase>" \
  --description "<detailed spec>" \
  --priority <priority> \
  --labels "<comma-separated>"

--assign-to
is mandatory. Always include it on create.

Dependencies: If this task touches files that overlap with other in-flight tasks, add

--depends-on <task-id>

. Create all related tasks upfront with DAG dependencies — don't wait for one to finish before creating the next.

Report to user: task ID, title, assigned agent.

<可验证条件 — 审核者将在第二环节检查每个项>

任务类型示例：

API："POST /api/items 返回201状态码及 { id, name }"
API："空名称返回400状态码及验证错误"
UI："点击提交按钮创建条目并跳转到详情页"
UI："空表单显示行内验证，提交按钮保持禁用状态"
CLI："ak get task --board xxx 打印包含状态列的任务表格"

是否创建此任务？(y/n)


从`## 目标`到`## 检查项`的所有内容将作为`--description`的参数值。上方的标题栏字段（标题、看板、Agent等）仅用于展示的元数据 — 不要包含在`--description`中。用户必须在任务发送给Agent前查看完整描述内容。

**用户确认后**，创建任务：

```bash
ak create task \
  --board <board-id> \
  --repo <repo-id> \
  --assign-to <agent-id> \
  --title "<concise action phrase>" \
  --description "<detailed spec>" \
  --priority <priority> \
  --labels "<comma-separated>"

--assign-to
为必填项。创建任务时必须包含该参数。

依赖关系：如果此任务涉及的文件与其他进行中的任务重叠，添加

--depends-on <task-id>

参数。提前创建所有相关任务并设置DAG依赖 — 不要等待一个任务完成后再创建下一个。

向用户反馈：任务ID、标题、分配的Agent。

Phase 2: Monitor & Review

第二阶段：监控与审核

Step 5: Monitor

步骤5：任务监控

Block on
ak wait
instead of writing polling loops. Exit codes: 0 condition met, 2 task cancelled, 124 timeout.

bash

ak wait task <task-id> --until in_review --timeout 1h
case $? in
  0)   ;;  # ready for review → Step 6
  2)   echo "task cancelled — abort" ; exit 1 ;;
  124) echo "timed out — investigate" ;;  # fall through to investigation
esac

Run

ak wait task --help

for the full flag list.

On timeout (124) or if you suspect the agent is stuck, investigate immediately — don't just re-wait:

Check daemon logs:
```
ak logs --no-follow --lines 20
```
Check if agent process is alive:
```
ps aux | grep "claude.*session"
```
Check agent session log for what it's doing or where it's stuck
Check child processes: the agent may be stuck on a hook, install, or network call

使用
ak wait
替代轮询循环。退出码说明：0表示条件满足，2表示任务已取消，124表示超时。

bash

ak wait task <task-id> --until in_review --timeout 1h
case $? in
  0)   ;;  # 准备就绪，进入审核 → 步骤6
  2)   echo "任务已取消 — 终止流程" ; exit 1 ;;
  124) echo "超时 — 开始排查" ;;  # 进入排查环节
esac

运行

ak wait task --help

查看完整参数列表。

出现超时（124）或怀疑Agent卡住时，立即排查 — 不要仅重新执行等待命令：

查看守护进程日志：
```
ak logs --no-follow --lines 20
```
检查Agent进程是否存活：
```
ps aux | grep "claude.*session"
```
查看Agent会话日志，了解其当前操作或卡住位置
检查子进程：Agent可能在钩子、安装或网络调用环节卡住

Step 6: Review PR

步骤6：PR审核

Pre-check: CI status. Before reviewing, verify CI has passed on the PR:

bash

gh pr checks <pr-number> --repo <owner>/<repo>

If CI is pending or failed, reject immediately — worker must wait for CI to pass before submitting for review:

bash

ak task reject <task-id> --reason "CI not green — wait for CI to pass before submitting for review"

Two gates — both must pass before merging. Reject as soon as either fails.

预检查：CI状态。审核前确认PR的CI已通过：

bash

gh pr checks <pr-number> --repo <owner>/<repo>

如果CI处于等待或失败状态，立即拒绝任务 — 执行Agent必须等待CI通过后再提交审核：

bash

ak task reject <task-id> --reason "CI未通过 — 请等待CI完成后再提交审核"

审核分为两个环节 — 必须全部通过才能合并。任一环节失败立即拒绝。

Gate 1: Code Review

环节1：代码审核

Read the full PR diff and review against the task spec:

bash

gh pr view <pr-number> --repo <owner>/<repo> --json title,body,additions,deletions,changedFiles
gh pr diff <pr-number> --repo <owner>/<repo>

Check:

Does the implementation match the task spec?
Code quality — logic errors, bad abstractions, security issues
Boundary awareness — CLI user-facing output vs internal logging, public API vs private
Missing or broken test updates
Dropped functionality (lost stack traces, removed useful info, etc.)

Fails → reject immediately, don't proceed to Gate 2.

阅读完整PR差异并对照任务规格进行审核：

bash

gh pr view <pr-number> --repo <owner>/<repo> --json title,body,additions,deletions,changedFiles
gh pr diff <pr-number> --repo <owner>/<repo>

检查要点：

实现是否符合任务规格？
代码质量 — 逻辑错误、不良抽象、安全问题
边界意识 — CLI用户输出与内部日志区分、公共API与私有API区分
测试用例缺失或更新不完整
功能遗漏（如丢失堆栈跟踪、移除有用信息等）

不通过 → 立即拒绝，无需进入环节2。

Gate 2: Functional Acceptance

环节2：功能验收

Re-read the target repo's CONTRIBUTING.md before testing — don't rely on memory from Step 2.

Walk through every item in the task's
```
## Checks
```
section — each must pass
Visit the preview/staging deployment and verify end-to-end
Check for regressions in related features
Run any project-specific verification steps defined in CONTRIBUTING.md

Fails → reject with specific repro steps.

测试前重新阅读目标仓库的CONTRIBUTING.md — 不要依赖步骤2的记忆。

逐一验证任务
```
## 检查项
```
中的所有内容 — 必须全部通过
访问预览/预发布环境，进行端到端验证
检查相关功能是否出现回归问题
执行CONTRIBUTING.md中定义的项目特定验证步骤

不通过 → 附带具体复现步骤拒绝任务。

Step 7: Decide — act immediately, do not ask the user

步骤7：决策 — 立即执行，无需询问用户

Either gate fails → Reject. List all issues in the reason.

bash

ak task reject <task-id> --reason "<all issues, specific and actionable>"

After reject, go back to Step 5 and keep monitoring.

Both gates pass → Post verification comment, then merge.

Post a verification comment on the PR with evidence before merging:

bash

gh pr comment <pr-number> --repo <owner>/<repo> --body "$(cat <<'EOF'

任一环节失败 → 拒绝任务。在拒绝理由中列出所有问题。

bash

ak task reject <task-id> --reason "<所有问题，具体且可执行>"

拒绝后返回步骤5继续监控任务。

两个环节均通过 → 发布验证评论，然后合并PR。

合并前在PR中发布包含验证证据的评论：

bash

gh pr comment <pr-number> --repo <owner>/<repo> --body "$(cat <<'EOF'

Verification

验证结果

Functional Test

功能测试

Visited: <staging/preview URL tested>
Golden path: <what was tested and result>
Edge cases: <what was tested and result>

访问地址：<测试的预发布/预览URL>
主流程：<测试内容及结果>
边界情况：<测试内容及结果>

Test Suite

测试套件

<执行的测试命令及通过/失败汇总>

Conclusion

结论

All checks pass — merging. EOF )"


If the PR has merge conflicts, reject instead of merging — the worker agent will rebase, fix, and resubmit:
```bash
ak task reject <task-id> --reason "merge conflicts with main — rebase and resubmit"

Then merge:

bash

gh pr merge <pr-number> --repo <owner>/<repo> --squash --delete-branch

The daemon's PR Monitor will mark the task done — do NOT manually

ak task complete

所有检查项通过 — 执行合并。 EOF )"


如果PR与主分支存在合并冲突，拒绝任务而非直接合并 — 执行Agent会重新变基、修复冲突并重新提交：
```bash
ak task reject <task-id> --reason "与主分支存在合并冲突 — 请重新变基后提交"

然后执行合并：

bash

gh pr merge <pr-number> --repo <owner>/<repo> --squash --delete-branch

守护进程的PR监控会自动标记任务完成 — 不要手动执行
ak task complete
。

Cleanup after merge

合并后清理

Remove local review artifacts from the repo root:

bash

rm -rf /tmp/ak-review-* playwright-report/ test-results/

从仓库根目录移除本地审核生成的临时文件：

bash

rm -rf /tmp/ak-review-* playwright-report/ test-results/

Phase 3: Exception Handling

第三阶段：异常处理

Removing a task in todo

删除待办状态的任务

Tasks in

todo

status cannot be cancelled — delete them directly:

bash

ak delete task <task-id>

处于

todo

状态的任务无法取消 — 直接删除：

bash

ak delete task <task-id>

Canceling an active task

取消活跃任务

For tasks in

in_progress

in_review

: always close the PR first, then cancel. Closing the PR without canceling is fine — PR Monitor will auto-cancel. But canceling without closing the PR leaves orphaned PRs.

bash

gh pr close <pr-number> --repo <owner>/<repo> --delete-branch
ak task cancel <task-id>

对于处于

in_progress

或

in_review

状态的任务：先关闭PR，再取消任务。仅关闭PR不取消任务是可行的 — PR监控会自动取消任务。但仅取消任务不关闭PR会产生孤立PR。

bash

gh pr close <pr-number> --repo <owner>/<repo> --delete-branch
ak task cancel <task-id>

Stuck rejected task

卡住的已拒绝任务

If a rejected task stays

in_progress

without being picked up:

Check daemon logs — is it detecting the rejection?
If daemon is down or not tracking, close the PR, cancel, recreate with original spec + review feedback + reference the existing PR branch
Always use
```
--assign-to
```
on recreate

如果已拒绝的任务仍处于

in_progress

状态且未被处理：

检查守护进程日志 — 是否检测到拒绝指令？
如果守护进程未运行或未跟踪任务，关闭PR、取消任务，然后根据原始规格+审核反馈+引用现有PR分支重新创建任务
重新创建任务时必须使用
```
--assign-to
```
参数

CI failure

CI失败

Investigate the failure. If it's a source bug, reject with details. If it's flaky CI, re-trigger.

排查失败原因。如果是代码Bug，附带详情拒绝任务；如果是CI不稳定，重新触发CI。

Rules

规则

Workflow completion is mandatory — once this skill is invoked, the full lifecycle (create → assign → monitor → review → merge/reject) MUST run to completion. If you are interrupted mid-workflow (user asks a side question, chat drifts to another topic, tool fails, etc.), handle the interruption and then immediately resume the workflow from where you left off. Never ask "should I continue monitoring?" or "do you want me to keep going?" — the answer is always yes. The only way to exit the workflow early is if the user explicitly says to stop, cancel, or abort.
Follow CONTRIBUTING.md — read the target repo's CONTRIBUTING.md before creating tasks; check PR compliance during review
Investigate before creating — read the code first, don't create vague tasks
One task per invocation — if the user describes multiple things, create one and suggest splitting
Detailed descriptions — agents are autonomous, the description is their only input
Check for duplicates — look at existing tasks before creating
Review = act — reject or merge based on your review, don't ask the user for permission
Think about dependencies — tasks touching shared files must use
```
--depends-on
```
Always
--assign-to
on create — never create a task without assigning an agent
Close PR before cancel — never cancel a task without closing its PR first
Don't sleep-poll blindly — if monitoring takes too long, investigate daemon logs and agent processes immediately

必须完成完整工作流 — 一旦调用此技能，必须执行完整生命周期（创建 → 分配 → 监控 → 审核 → 合并/拒绝）。如果在工作流中途被打断（用户询问其他问题、聊天偏离主题、工具故障等），处理完中断后立即从中断位置恢复工作流。绝不要询问“是否继续监控？”或“是否继续执行？” — 答案永远是肯定的。只有用户明确要求停止、取消或终止时，才能提前退出工作流。
遵循CONTRIBUTING.md — 创建任务前阅读目标仓库的CONTRIBUTING.md；审核时检查PR是否符合要求
创建前先调研 — 先阅读代码，不要创建模糊的任务
每次调用仅创建一个任务 — 如果用户描述多个需求，创建一个任务后建议拆分其他需求
详细描述任务 — Agent是自主执行的，描述内容是其唯一输入
检查重复任务 — 创建前查看现有任务
审核即决策 — 根据审核结果拒绝或合并，无需询问用户许可
考虑依赖关系 — 涉及共享文件的任务必须使用
```
--depends-on
```
参数
创建任务时必须指定
--assign-to
— 绝不创建未分配Agent的任务
取消任务前先关闭PR — 绝不先取消任务再关闭PR
不要盲目轮询等待 — 如果监控耗时过长，立即排查守护进程日志和Agent进程