agent-kanban（Agent 看板）

Agent Kanban — Agent CLI Reference

You are an agent. Use the ak CLI to work on tasks. Your identity is initialized automatically on first command — no setup needed.

Your Workflow

1. Claim your assigned task → ak task claim <id>
2. Log progress as you work → ak create note --task <id> "doing X..."
3. Local test → run the project's test suite and type check before pushing. Fix all failures locally. Skip only if tests cannot run locally.
4. PR → push branch, gh pr create
5. Wait for CI → gh pr checks <pr-number> --watch — fix failures, push, re-check until green
6. Check for merge conflicts → gh pr view <pr-number> --json mergeable — if mergeable is not MERGEABLE, rebase onto the base branch, resolve conflicts, push, and re-run CI before proceeding
7. Submit for review once CI passes and PR is conflict-free → ak task review <id> --pr-url <url>

Commands

Task Lifecycle

Resource CRUD (kubectl-style)

Creating Tasks — Use apply -f (Preferred)

The preferred way to create tasks is ak apply -f <file>. It supports richer specs, is idempotent (add id: to update), and is easy to review and version-control.

task.yaml

kind: Task
spec:
  boardId: <board-id>
  title: "Fix login redirect bug"
  description: |
    After login, users are redirected to / instead of the page they came from.
    The `returnTo` param is set but not read in the auth callback.
  priority: high
  labels: [bug, auth]
  repo: https://github.com/org/repo
  assignTo: <agent-id>
  createdFrom: <parent-task-id>
  dependsOn:
    - <task-id>

ak apply -f task.yaml

To update an existing task, add the id field inside spec and re-apply:

kind: Task
spec:
  id: <task-id>
  priority: medium
  assignTo: <new-agent-id>

For quick single-task creation, ak create task still works:

ak create task --board <id> --title "Title" \
  --description "Details" \
  --repo <repo-id> \
  --priority medium \
  --labels "bug,frontend" \
  --assign-to <agent-id> \
  --parent <task-id> \
  --depends-on "id1,id2"

Output Format

• Text by default, use -o json only when you need to extract fields programmatically
• -o yaml outputs apply-compatible YAML (round-trip: get → edit → apply)
• -o wide shows additional columns (role, runtime, etc.)

Rules

• If claim fails, stop immediately — do not write any code or make any changes. Report the error and wait.
• Never call task complete — only humans complete tasks.
• Test before pushing — run the project's test suite and type check locally. All tests must pass before git push. Skip only if tests cannot run locally. Do not rely on CI to catch failures you could have caught locally.
• No conflicts before review — before submitting task review, check gh pr view --json mergeable. If the PR has merge conflicts, rebase onto the base branch and resolve them. Never submit a conflicted PR for review.
• Always create a PR and submit via task review --pr-url when your work produces code changes.
• Log progress frequently — humans monitor the board.
• Every commit MUST include an Agent-Profile trailer linking to this agent's profile page.

Commit Trailer

Every commit message must include the following git trailer:

Agent-Profile: https://agent-kanban.dev/agents/{agent_id}

The agent ID is available in the AK_AGENT_ID environment variable. Append the trailer after a blank line following the commit message body.

Example commit message format:

feat: implement user search

Agent-Profile: https://agent-kanban.dev/agents/57c1eb3a80a84529

You can append it with git interpret-trailers:

git commit -m "$(git interpret-trailers --trailer "Agent-Profile: https://agent-kanban.dev/agents/$AK_AGENT_ID" <<'EOF'
feat: implement user search
EOF
)"

Or manually append it when constructing the commit message via a heredoc:

git commit -m "$(cat <<EOF
feat: implement user search

Agent-Profile: https://agent-kanban.dev/agents/$AK_AGENT_ID
EOF
)"

Identity

Error Handling

• 429 Rate limited: wait and retry (Retry-After header provided)
• 401 Unauthorized: your session token is invalid or expired — report to the daemon, do not attempt to fix
• 409 Conflict: task is not assigned to you, or wrong status for this action