Ak Plan

ak-plan — Project Planning

Plan and create a board with tasks — for a new version release or a new product from scratch.

Unattended Execution Contract

Assume this workflow runs in two explicit modes:

• Before task creation: human-in-the-loop. Ask the user only during the initial planning, ambiguity resolution, and task-plan preview phase before task creation is confirmed.
• After task creation: human-not-in-the-loop. Once the user confirms the plan and tasks are created, do not stop to ask for permission, confirmation, or next steps unless the user interrupts you. Continue through the full work cycle: create, assign, monitor, review, reject or merge, and report the final outcome.

If execution hits a blocker after confirmation, use the available tools and repository context to resolve it. If the blocker cannot be resolved without external authorization or production mutation, fail fast with the exact blocker and the next required action instead of waiting in the middle of the workflow.

Identity

This is a leader workflow.

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

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

The leader chooses its own username and optional full name.

Input

Parse the user's input:

• Name — version (e.g. "v1.4") or product name (e.g. "my-api"). If the user provides a patch version such as v1.4.0, normalize task labels to v1.4.
• Goals — what to achieve (if not provided, ask)

Workflow Checklist

Immediately after this skill is invoked, create and maintain an explicit task plan/checklist in the agent UI. This checklist is a guardrail against attention drift during long human-in-the-loop planning discussions.

The checklist must include the full lifecycle, not just planning:

1. Detect project mode and repo/board context. 2. Understand current state and constraints. 3. Analyze gaps and draft task plan. 4. Preview task plan and get human confirmation. 5. Create or verify labels, workers, and tasks. 6. Switch to human-not-in-the-loop execution. 7. Monitor tasks until PRs reach review. 8. Review each PR: CI, code, functional acceptance, notes. 9. Reject or merge each PR according to gates. 10. Continue until all planned tasks are done. 11. Report final summary.

Keep this checklist current:

• Mark exactly one active step as in progress.
• Update statuses at every phase transition.
• After task creation, explicitly mark the planning/creation steps complete and

mark monitoring/review as in progress before doing any final user-facing summary.

• Do not send a final answer while any post-creation execution step remains

pending, unless the user explicitly says to stop, cancel, abort, or only create tasks.

• If context becomes long or the user interrupts, re-read the checklist before

deciding the next action.

Phase 0: Detect Mode

Check if this is an existing project or a new product:

git remote -v 2>/dev/null    # has a remote? → existing project
ak get repo                  # registered repos

Three possible states:

• Existing project with remote → skip to Phase 1
• New product (no git init yet) → go to Phase 0.5 (Scaffold)
• Local-only project (git init done, no remote) → STOP. A registered repo must have a real remote (https://… or git@…). Tell the user one of:

1. Push the project to GitHub first: gh repo create <owner>/<name> --source . --push 2. Or: ask them for the intended remote URL before proceeding.

Never invent a URL (no file://, no local paths, no placeholders). The agent-kanban server will reject non-http(s)/ssh URLs with 400, and even if it didn't, the daemon cannot clone local paths.

Phase 0.5: Scaffold (new products only)

# Create and clone repo (NEVER inside an existing git repo)
gh repo create <owner>/<name> --public --description "<one-liner>" --clone
cd <repo-dir>

# Initialize project — use framework CLIs, install ALL dependencies upfront
# Ask user for tech stack if not specified

# Create config files, entry point, DB schema, .gitignore
# Commit and push
git add -A && git commit -m "feat: project scaffold" && git push -u origin main

Register with agent-kanban (URL MUST come from git remote get-url origin — never hand-crafted):

ak create repo --name <name> --url "$(git remote get-url origin)"

The scaffold must contain enough structure for agents to start writing code immediately.

Phase 1: Understand Current State

ak get board                   # existing boards
ak get agent -o json           # available agents, load, runtime_available
ak get repo                    # registered repos
git remote -v                  # repo URL (use this, never guess)

Read project instruction files, CONTRIBUTING.md, and recent git history to understand:

• What was shipped recently
• What patterns/conventions exist
• What the project architecture looks like
• Contribution requirements (branch strategy, commit format, code style, test expectations)

Phase 2: Analyze Gaps

Use Explore agents to thoroughly scan the codebase for gaps related to the goals. Consider:

• Missing features vs stated goals
• Backend gaps (API, data model)
• CLI gaps (missing commands)
• Frontend gaps (if applicable, respect the project's UI principles)
• Test coverage gaps

Task Decomposition Model

Plan tasks as independently runnable work packages, not as a sequential todo list. A task is not "step 1, step 2, step 3" in the leader's private plan. A task is a self-contained assignment that another agent can claim, understand, implement, test, and submit for review without guessing the rest of the plan.

Before drafting tasks, define the project-level integration strategy:

1. Architecture direction — the shared pattern workers must preserve, such as adapter, provider, repository, service, command, route, plugin, or module boundaries. 2. Shared contracts — interfaces, schemas, API shapes, events, storage formats, CLI flags, and UI state contracts that multiple tasks must obey. 3. Ownership boundaries — which module or business capability each task owns. 4. Integration dependencies — which contracts must exist before dependent implementations start.

Split by business capability, product surface, module boundary, or adapter implementation. Do not split by chronological implementation steps such as "create interface", "wire backend", "write tests", "final cleanup", or "verify everything" unless that work is itself an independently reviewable product or platform outcome.

For abstraction work, make the shared abstraction contract explicit before parallel implementation starts. If several providers/adapters/plugins need the same abstraction:

• Create one contract task only when the contract is substantial enough to be

independently reviewed and all later adapter tasks can depend on it.

• Otherwise keep the contract and the first implementation together, then make

later adapter tasks depend on that task.

• Each adapter task must use the shared contract and may extend it when the

adapter reveals a real missing capability.

• If extending the contract affects other adapters or callers, the adapter task

must update the shared contract and the affected call sites, or the leader must make that task sequential with the affected work.

• Worker tasks must not bypass the shared abstraction because the current

interface is inconvenient or incomplete. The task description must say how to evolve the contract safely.

Never create a final "acceptance", "QA", "integration review", or "verify all previous work" task whose purpose is to re-check the whole plan. End-to-end verification is leader-owned during PR review. Create a verification infrastructure task only when the project lacks reusable tooling or fixtures needed for workers and leaders to validate future work.

Use AskUserQuestion to interactively confirm the plan with the user. For each ambiguous point, present options:

• Scope — which gaps to address in this version vs defer to later
• Ordering — which tasks are critical path vs nice-to-have
• Approach — when multiple implementation strategies exist, present them with trade-off descriptions
• Task granularity — whether to split a large piece into subtasks or keep it as one
• Runtime choice — when multiple schedulable runtimes are reasonable, ask which runtime to use for new workers

Keep iterating until all uncertainties are resolved.

Structured Questions in Codex

Use the runtime's structured question tool during the pre-task-creation phase:

• In Claude-style runtimes, use AskUserQuestion.
• In Codex, use request_user_input.

For Codex Default mode, verify the feature flag before relying on interactive prompts:

codex features list | rg default_mode_request_user_input

Expected:

default_mode_request_user_input     under development  true

If it is not enabled, tell the user to enable the feature flag themselves and restart Codex before continuing:

codex features enable default_mode_request_user_input

Do not run this command for the user. The current Codex session will not gain the tool after an automatic config change; the user must enable it and reopen Codex. Do not switch Codex into Plan mode as a workaround. Plan mode injects Codex-native planning behavior and conflicts with this leader workflow.

Before creating any tasks, show the user a task summary table using AskUserQuestion:

📋 Task Plan Preview

Architecture direction:
- <shared pattern and integration strategy>

Shared contracts:
- <interface/schema/API/event/CLI/UI contract that workers must preserve>

| # | Title | Boundary | Repo | Labels | Depends on | Agent |
|---|-------|----------|------|--------|------------|-------|
| 1 | <title> | <module/capability/contract> | <repo> | backend | — | <agent> |
| 2 | <title> | <module/capability/adapter> | <repo> | frontend | #1 | <agent> |
| ...

Per-task description summary:

### Task 1: <title>
Goal: <one sentence>
Boundary: <business capability/module/adapter/contract this task owns>
Contract: <shared interface/schema/API this task must preserve or evolve>
Files: <file list>
Spec: <key points — not the full description, but enough to judge scope>

### Task 2: <title>
...

---
Create all tasks? (y/n)

The user must confirm before any ak create task calls are made. If the user requests changes, adjust and re-preview.

Label Best Practices

Labels are board-level taxonomy, not free-form notes. Before task creation, define the small label set this plan will use and show it in the preview. Prefer reusing existing board labels and adding only labels that will remain useful for future filtering.

Recommended label categories:

• Version — usually one version label per versioned task, formatted vX.Y (for example v1.4, v2.0). Prefer avoiding patch versions (v1.4.0) or suffixes (v1.4-final, v1.4-test) unless the board already has a specific reason to track that granularity.
• Area — one or two stable implementation areas: backend, frontend, cli, api, database, infra, docs, ui, security, test.
• Type — optional, only when it materially helps filtering: feature, bug, refactor.

Prefer keeping temporary process state, tools, providers, experiments, and implementation trivia in the task description instead of labels. Labels such as done, setup:lefthook, prompt-fix-test, smoke-test, cost-test, codex, github, cloudflare, tanstack-query, or file/library names usually become noisy unless the board already uses that exact label intentionally.

When labels overlap, choose the stable category:

• Use infra, not infrastructure.
• Use bug, not bugfix.
• Use database, not db.
• Use frontend for UI implementation unless the task is specifically design polish, then add ui.

Task labels must already exist on the board. Check existing labels first; if a needed label does not exist, create it with color and description, then use it on tasks:

ak get label --board $BOARD
ak create label --board $BOARD --name v1.4 --color "#22C55E" --description "Version 1.4"
ak create label --board $BOARD --name backend --color "#38BDF8" --description "Backend/API work"
ak create label --board $BOARD --name bug --color "#F87171" --description "Bug fix"

Useful color defaults:

• Version: #22C55E
• Frontend/UI: #A78BFA
• Backend/API/database: #38BDF8
• CLI/runtime: #22D3EE
• Bug/security: #F87171
• Infra/deploy: #F59E0B
• Docs/refactor/general: #71717A

Phase 3: Create Board, Workers & Tasks

Use the existing board for the project. One project = one board.

ak get board                   # find the project board
# Only create a new board if this is a new product with no board yet

Before creating tasks, choose or create the workers that will own them. Read references/runtime-delegation.md.

Check existing agents. For a typical project you need:

• A primary implementation worker for each coherent feature/module.
• Focused specialist subagents only when the primary worker will repeatedly use that stable specialist context, such as test, review, or acceptance.

Only assign work to agents whose runtime_available is true. If the best role exists only on an unavailable runtime, create a new worker with the same role, soul, skills, and handoff settings on an available runtime.

Create missing agents before task creation:

kind: Agent
metadata:
  name: <human-username>
  annotations:
    agent-kanban.dev/nickname: "<Human Name>"
spec:
  runtime: <available-runtime>
  model: <runtime-model>
  role: "<kebab-case-role>"
  bio: "<durable responsibility>"
  soul: |
    <durable behavior policy and decision rules>
    <if subagents are set, when to call them and how to review or integrate their output>
  skills:
    - <source>@<domain-skill>
  subagents:
    - <specialist-worker-agent-id>

The leader must generate and apply worker Agent YAML according to references/runtime-delegation.md. Then run ak get agent -o json and confirm the latest worker is visible and runtime_available: true before assigning tasks.

Create tasks with full specs. For each task:

1. `--title` — concise action phrase 2. `--description` — exhaustive spec including:

• Files to create/modify
• API endpoints, DB queries, UI components (concrete, not vague)
• Patterns to follow from the existing codebase

3. `--repo <id>` — from ak repo list 4. `--labels` — include the planned vX.Y version label plus one or two stable area/type labels 5. `--assign-to <agent-id>` — worker chosen before task creation 6. `--depends-on` — task IDs this depends on

Create tasks in dependency order so earlier task IDs can be referenced:

T1=$(ak create task --board $BOARD --title "..." --repo $REPO --assign-to $AGENT -o json | jq -r .id)
T2=$(ak create task --board $BOARD --title "..." --repo $REPO --assign-to $AGENT --depends-on $T1 -o json | jq -r .id)

Task Creation Best Practices

• Create one task for one reviewable outcome.
• Split by business capability, product surface, feature/module boundary, adapter/provider implementation, and context overlap. Do not split by chronological todo steps or human job title.
• Keep highly overlapping work in one task, even if it touches frontend, backend, CLI, infra, schema, and tests.
• Split only when work is independently understandable, independently reviewable, and has low file/data/API context overlap.
• Make each task independently claimable: no hidden chat context, no "continue from above" descriptions.
• Each task must include the architectural direction and shared contract it must preserve. If there is no shared contract, say so explicitly.
• Prefer contract-first dependencies when multiple tasks implement the same abstraction. Later adapter/provider tasks should depend on the task that establishes or last changes the shared contract.
• Do not create tasks that encourage workers to choose separate architectural directions for the same feature. If workers need the same abstraction, merge the work or serialize it through a shared contract task.
• Do not create standalone final QA or acceptance tasks for the whole plan. The leader performs acceptance during PR review. Only create test/verification tasks for reusable infrastructure that future tasks can run.
• Put the exact files, APIs, commands, UI states, and acceptance checks in --description.
• Assign every task at creation with --assign-to.
• Use --depends-on for real blockers or overlapping context. Tasks touching the same files, data model, or API contract should be sequential or merged.
• Keep parallel tasks independent by feature/module boundary and data model boundary.
• Use stable labels: version plus area, such as v1.4,backend or v1.4,cli.
• Keep the board label set small and reusable. If a label would be used by only one task and is not a version label, put that detail in the task description instead.

Task Description Quality

Agents are autonomous — the description is their only input. A good description:

## Goal
One sentence: what this task produces.

## Boundary
The business capability, module, adapter, provider, or contract this task owns.

## Architecture
The shared pattern this task must preserve, such as an adapter interface,
repository layer, service boundary, route contract, or UI state model.

## Contract
The exact interface/schema/API/CLI/UI contract this task must use. If the
contract is insufficient, extend it in this task and update affected callers
instead of bypassing the abstraction.

## Files
- src/foo.ts — API route handlers
- src/bar.ts — data access layer

## Spec
POST /api/items — create item
  Request: { "name": string }
  Response: 201 { "id": 1, "name": "..." }
  Empty name → 400 validation error

## Checks
- [ ] POST /api/items returns 201 with { id, name }
- [ ] Empty name returns 400 with validation error
- [ ] New item appears on the list page without refresh
- [ ] Empty state shows "No items yet" placeholder

Vague descriptions produce vague code. Be specific.

Phase 4: Monitor & Merge

Block on `ak wait board` instead of writing polling loops. It streams tasks one at a time as they reach the filter status. Exit codes: 0 condition met, 2 task cancelled, 124 timeout.

React to PRs as workers push them

# Stream in_review tasks one at a time, handle each, then wait for the next
while ak wait board <board-id> --filter in_review --timeout 1h; do
  # Latest in_review task is printed — review its PR, merge or reject
  :
done

# Or wait until the entire board converges (0 = infinite)
ak wait board <board-id> --until all-done --timeout 0

Run ak wait board --help for the full flag list.

Before starting or recovering any wait, follow references/wait-monitoring.md. The same wait policy applies to board waits and task waits.

When a task reaches in_review with a PR:

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

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:

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

Three gates — code review, functional acceptance, and agent notes review — must pass before merging. Follow the shared verification policy in references/leader-verification.md, including waiver evidence and verification infrastructure learning.

Gate 1: Code Review

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

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.

Gate 2: Functional Acceptance

Apply references/leader-verification.md. Passing tests, CI, and code review is not completion. Validate every task check from the product/user perspective. If verification cannot be completed, follow the shared attempt budget, waiver, and verification infrastructure learning rules.

Gate 3: Agent Notes Review

Read task notes before merging:

ak get note --task <task-id>

Check:

• The worker summarized what was done.
• Whether the worker proposed any durable process or principle change for its agent profile.
• Any proposal includes the reason, exact fields to change, and complete candidate Agent YAML using the same metadata.name username as the current agent.

If the completion summary is missing or unclear, reject and ask the worker to add it.

If no proposal is present, continue. If a proposal is present, review it using references/runtime-delegation.md. Apply it only when the proposal is durable, role-appropriate, and not task-specific.

Any gate fails or is blocked → Reject. List all issues in the reason.

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

After reject, continue monitoring. If the failure reveals a durable worker behavior problem, apply references/runtime-delegation.md#leader-driven-profile-iteration: use reject to correct the current active session, or close/cancel the task if it is too far off-course; update the worker profile only after the current task is no longer being worked, and never change the agent runtime.

All gates pass, or Gate 2 is explicitly waived after the required attempt budget → Post verification comment, then merge.

Post evidence on the PR before merging using the verification comment template in references/leader-verification.md. Before running gh pr merge, re-read the comment and confirm it satisfies the shared policy.

If the PR has merge conflicts, reject instead of merging — the worker agent will rebase, fix, and resubmit:

ak task reject <task-id> --reason "merge conflicts with main — rebase and resubmit"

Then merge:

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

The daemon's PR Monitor will automatically complete the task. Do not manually run ak task complete unless the PR Monitor lag rule in references/wait-monitoring.md applies.

Cleanup after merge

Remove local review artifacts from the repo root after verifying each path belongs to this workflow:

• temporary review worktrees under /tmp/ak-review-*
• playwright-report/
• test-results/

Completion:

When all tasks are done, report the final summary to the user.

AK Command, Product, or Skill Issues

If the blocker appears to be an ak bug, missing capability, confusing UX, documentation gap, or skill workflow problem, file an issue in the official repo after collecting a minimal reproduction.

If the leader agent makes a process error, violates this skill, merges/rejects incorrectly, skips a required gate, misinterprets conflicting skill instructions, or has to be corrected by the user about expected skill behavior, do not stop at a chat apology or "next time" promise. Summarize the failure as a durable skill-improvement issue so future agents and external projects can benefit from the lesson. Include:

• What the agent did wrong.
• Which skill text was unclear, incomplete, contradictory, or too weak to prevent the error.
• The exact rule or wording that should be added or changed.
• Any local skill edits already made during the incident.

gh issue create \
  --repo saltbo/agent-kanban \
  --title "ak-plan: <short process or skill problem summary>" \
  --body "$(cat <<'EOF'
## Summary
<what failed or what capability is missing>

## Command
ak <command and flags>

## Expected
<what should have happened>

## Actual
<exact error text or observed behavior>

## Context
- ak version:
- OS:
- Runtime:
- Auth type: user | machine | agent
- Board/task/repo IDs, if relevant:

## Reproduction
1. <step>
2. <step>

## Proposed Skill Change
<specific wording or rule that would prevent recurrence>
EOF
)"

Never include API keys, session tokens, private keys, .env contents, or private repository data. If gh is unavailable, open https://github.com/saltbo/agent-kanban/issues/new and paste the same content.

Rules

• Workflow completion is mandatory — once this skill is invoked, the full lifecycle (plan → create → assign → monitor → review → merge all) MUST run to completion.
• Before task creation: human-in-the-loop. Discuss scope, resolve ambiguity, preview the task plan, and get explicit user confirmation before creating tasks.
• After task creation: human-not-in-the-loop. The user is no longer part of execution control unless they explicitly interrupt with a new instruction. The leader owns execution and must continue monitoring, reviewing, rejecting, merging, and iterating until the whole work cycle completes.
• After ak create task, continue immediately into monitoring/review work (ak wait board ...) in the same turn whenever possible. Do not send a final answer merely reporting that tasks were created unless the user explicitly says to stop, cancel, abort, or only create tasks.
• If execution hits a blocker after task creation, solve it autonomously: inspect state, fix environment issues, reject blocked PRs with actionable reasons, create follow-up issues when the platform/skill is at fault, or wait for the next task/PR. Do not stop and hand the blocker back to the user unless the user is the only possible source of required information or explicitly pauses the workflow.
• 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
• Prefer text output — only use -o json | jq when extracting fields into variables (e.g. task IDs for --depends-on). For display, use default text output.
• Always get repo URL from `git remote get-url origin` — never guess, never improvise. If there is no remote, stop and ask the user to push the repo first (see Phase 0). file://, local paths, and placeholder URLs will be rejected by the server with 400.
• Discuss the plan with the user before creating tasks — don't just start creating
• Set depends-on at creation time — don't leave deps for later
• Space API calls — avoid triggering rate limits during batch creation
• Respect project instructions — follow all project conventions and UI principles
• Pre-install shared dependencies in scaffold — avoid parallel install conflicts
• Tasks with high context overlap must be sequential or merged (depends-on)
• Tasks can be parallel only when their feature/module context, files, data model, and API contracts are independent
• File skill-improvement issues for agent process failures — if you violate this skill or the user has to correct your workflow, create a GitHub issue in saltbo/agent-kanban documenting the failure and proposed skill change. Do this in addition to any immediate local skill edit; do not replace it with an apology or private note.

Leader Verification Policy

This policy is shared by leader workflows such as ak-plan and ak-task. Follow it whenever reviewing a task PR.

Three Gates

All PRs must pass three gates before merge:

1. Code review 2. Functional acceptance 3. Agent notes review

Reject as soon as a required gate fails. Do not ask the user to decide during human-not-in-the-loop execution.

Functional Acceptance

Passing tests, CI, and code review is not completion. Validate the feature from the product/user perspective before accepting it.

Required checks:

• Re-read the target repo's contribution or project instructions before testing.
• Walk through every item in the task's ## Checks section.
• Visit the preview/staging deployment and verify end-to-end when applicable.
• Check for regressions in related features.
• Run project-specific verification steps.
• Treat worker-reported tests, CI, screenshots, notes, and claims as supporting

evidence only. They never replace leader-owned functional acceptance.

Non-Production Verification Blockers

Preview, staging, local dev, and other non-production environments are agent-operable verification environments.

If functional acceptance is blocked in a non-production environment, recover the environment and continue verification. Examples include missing credentials, stale migrations, missing feature/license data, bad seed data, authorization setup, corrupted test state, local env gaps, or broken browser fixtures.

Allowed recovery actions include resetting test passwords, applying migrations, creating test users, seeding test data, enabling test-only feature/license bindings, recreating broken non-production state, and rerunning deployment or CI checks.

Production is the exception: do not mutate production credentials, customer data, license state, or other production resources unless the user explicitly authorizes that specific action.

Verification Attempt Budget

Try at least 5 distinct verification strategies before waiving verification. Distinct means materially different paths, not five retries of the same failing command.

Examples:

• preview URL
• local dev server
• direct API call
• CLI command
• database inspection
• logs
• seeded test account
• alternate browser/session
• project-specific smoke script
• targeted test command

For each attempt, capture evidence: command, URL, environment, timestamp if useful, exact error/output summary, screenshot/log reference if available, and what it proves.

Acceptance Status

Record acceptance status explicitly as one of:

• passed
• failed
• blocked
• waived

Meanings:

• passed: leader-owned functional acceptance succeeded.
• failed: the feature was testable and did not satisfy the task.
• blocked: fewer than 5 distinct strategies were attempted, or a known fix

path remains. blocked cannot merge.

• waived: at least 5 distinct strategies were attempted, all failed for

environment/tooling reasons, and the verification comment records which feature's functional verification was skipped and why the skip is real.

Verification Infrastructure Learning

A verification waiver is evidence of missing project infrastructure. Treat it as a root-cause signal, not a one-off inconvenience.

When Gate 2 is waived:

1. Create a new task that fixes the verification blocker before merging or moving to the next feature review. 2. The task must target the reusable harness/infrastructure problem, not the feature that happened to expose it. 3. The task description must include:

• Which feature's verification was waived.
• The 5+ verification attempts and evidence.
• The root verification gap, such as missing preview auth, seed data, smoke

script, browser fixture, local env setup, migration path, test account, or documented runbook.

• The durable acceptance checks that future agents must be able to run.

4. Add the infrastructure task as a dependency of every later incomplete task that would hit the same verification blocker. 5. Ensure labels used by the infrastructure task already exist on the board; create reusable missing labels first.

Example:

ak create task \
  --board <board-id> \
  --repo <repo-id> \
  --assign-to <agent-id> \
  --title "Fix verification harness for <area>" \
  --description "<root-cause verification infrastructure spec>" \
  --labels "infra,test"

ak update task <later-task-id> --depends-on <existing-deps>,<infra-task-id>

If the current reviewed PR is otherwise correct and Gate 2 is validly waived, it may still merge with the waiver evidence. Future related tasks must not continue until the verification infrastructure task is done.

Verification Comment

Post a verification comment on the PR before merging:

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

### Functional Test
- Acceptance status: passed | waived
- Feature verified or waived: <specific feature/check>
- Visited: <staging/preview URL tested, or N/A with reason>
- Golden path: <what was tested and result, or skipped with reason>
- Edge cases: <what was tested and result, or skipped with reason>

### Verification Waiver
<Only for waived. List at least 5 distinct verification attempts with evidence:
1. <strategy> — <command/URL/evidence> — <why it could not verify>
2. ...
Reason verification was skipped: <concise reason>

### Test Suite
<test commands run and pass/fail summary>

### Conclusion
All gates pass, or functional verification is waived with required evidence — merging.
EOF
)"

Before merge:

• If Acceptance status is passed, the visited target and golden-path result

are required for user-facing work.

• If Acceptance status is waived, the comment must identify the skipped

feature and include at least 5 distinct verification attempts with evidence.

• Otherwise, do not merge.

Runtime-Aware Delegation

AK provides data. The leader makes the scheduling decision.

Before assigning tasks or creating workers, run:

ak get agent -o json

Use these fields:

• kind: assign implementation tasks only to workers, not leaders.
• role: match the task domain first.
• runtime: the worker's runtime.
• runtime_available: only true is schedulable.
• queued_task_count: todo tasks already assigned to the worker.
• active_task_count: in-progress tasks currently owned by the worker.

Runtime Choice

Runtime selection is a hard stop before task creation.

If multiple runtimes are schedulable for the needed role and the user has not expressed a runtime preference, ask which runtime to use before creating a new worker or assigning the task. Present only runtimes with runtime_available: true, plus the relevant trade-off: existing matching worker, current load, model preference, or runtime-specific capability.

When creating a worker or choosing a non-default model, query provider-reported model availability:

ak get model --runtime <runtime> -o json

Treat the command as the source of truth. It reads from the runtime/provider's own authenticated surface where available: Codex cache, Claude SDK, Copilot model endpoint, or Gemini public API / Code Assist quota.

Use a returned model ID in spec.model. If ak get model fails because the runtime/provider does not expose model listing or lacks model-list credentials, follow references/agent-creation.md and either ask during the initial phase or use default only for low-risk, clearly scoped work.

Do not ask when there is only one schedulable runtime for the required capability profile, or when the user already specified a schedulable runtime.

Assignment Rules

1. Pick a worker whose role matches the task. 2. Exclude workers with runtime_available !== true. 3. Prefer the matching worker with the lowest active_task_count, then lowest queued_task_count. 4. If the user specified a runtime, exclude workers whose runtime does not match. 5. If the user specified a runtime and no worker or machine reports that runtime as schedulable, stop and ask the user to choose an available runtime. 6. If no matching worker is schedulable, create a worker with the required capability profile on a schedulable runtime using references/agent-creation.md. 7. If a matching worker exists only on an unavailable runtime, copy the required capability profile into the new worker using references/agent-creation.md. 8. Do not assign to a runtime just because the CLI exists on a machine. Runtime availability is whatever AK reports.

Same-Role Worker Creation

Same role means capability-compatible for the current task, not only the same role string. Follow references/agent-creation.md before creating or assigning the replacement worker.

Creating Workers

Create workers only when needed for the current task:

• Missing role.
• Matching role exists but every matching worker has unavailable runtime.
• The task should run now and matching workers are already busy.

Do not create duplicate workers for hypothetical future work. When creation is needed, follow references/agent-creation.md.

Complex Task Execution Model

For complex but coherent work, prefer one primary worker carrying focused task-local subagents over splitting the same outcome across multiple role-based workers. The primary worker owns the task, implementation direction, final integration, and review submission. Subagents handle independent, narrow work that would otherwise bloat the primary worker's context and cause attention drift.

Leader-created tasks must preserve one shared architectural direction. When multiple tasks implement the same family of behavior, such as providers, adapters, plugins, transports, commands, or storage backends, the leader must make the shared contract explicit before those tasks run in parallel.

Worker task boundaries should follow stable implementation ownership, not chronological todo steps. Good boundaries are a business capability, module, adapter/provider implementation, reusable contract, or platform capability. Poor boundaries are "write tests", "wire it up", "clean up", "final QA", or "verify all previous tasks" when those are only phases of the leader's plan.

If a worker discovers that the shared interface, schema, route contract, or adapter abstraction is missing a capability required by its assigned boundary, the correct move is to evolve the shared contract and update affected callers in that task, or to hand off/create a dependent contract task when the change is too broad. The worker must not bypass the abstraction, duplicate a parallel path, or implement a one-off workaround outside the agreed pattern because the current contract is inconvenient.

Subagents are task-local specialist definitions, not inline prompt blocks. Create or reuse the specialist definition first, then put its ID in the primary worker's spec.subagents.

Good reusable subagent profiles:

• Test specialist: writes focused tests, runs relevant checks, diagnoses failures, and fixes test code when the failure is in the test.
• Review specialist: reviews the final diff for bugs, maintainability, security, performance, architecture, and other durable quality concerns.
• Acceptance specialist: validates the completed product behavior from the user's perspective after implementation review, tests, and CI pass; uses E2E or manual acceptance checks to confirm the feature actually works before the task is completed.

Do not create all of these by default. Create or attach only the specialist subagents that the primary worker will repeatedly use. Do not split one stable specialist context into separate action agents such as writer, runner, fixer, or reviewer phases. Split specialists only when the work needs different durable domain context, review bar, or runtime.

For concrete specialist Subagent YAML examples, read references/specialist-profiles.md.

Creation order:

1. Create or reuse specialist subagent definitions with their own role, bio, soul, runtime model mappings, and skills. 2. Run ak get subagent -o json and collect their subagent IDs. 3. Create or update the primary worker with those IDs in spec.subagents. 4. In the primary worker's soul, define the collaboration contract: when each subagent should be called, what output is expected, which decisions stay with the primary worker, and how findings are verified before being acted on.

Subagent apply and CRUD:

ak apply -f subagent.yaml
ak get subagent
ak get subagent <id>
ak create subagent --username maya-lin --name "Maya Lin" --role test-specialist --bio "Focused test specialist." --soul "Write focused tests, run relevant checks, diagnose failures, and report concrete evidence." --models codex=gpt-5.3-codex
ak update subagent <id> --models codex=gpt-5.3-codex --skills <source>@<skill>
ak delete subagent <id>

Subagents vs Handoff

Use subagents for delegation inside the same task. The context overlaps with the primary task outcome, but a narrow specialist can inspect, test, review, or validate without loading the primary worker with every detail. The primary worker keeps ownership of the task, integrates the findings, and submits the same PR for review.

Use handoff_to for new independent work discovered while doing the task. The context overlap is low enough that it should become a separate task with its own description, owner, lifecycle, and review. Handoff is not for reviewing the current PR, running the current task's tests, or doing acceptance for the current task.

Rule of thumb:

• High context overlap + same deliverable → keep one task and use subagents if specialist focus helps.
• Low context overlap + separate deliverable → create a follow-up task through handoff.
• Shared files, data model, or API contract usually means high overlap; merge the work into one task or make it sequential with --depends-on.
• Shared abstraction family, such as several adapters implementing one interface, requires one explicit contract path. Parallel adapter work is acceptable only after the shared contract is established and each task says how to evolve it without bypassing it.

Create workers by generating an Agent YAML from the current task context.

kind: Agent
metadata:
  name: alex-chen
  annotations:
    agent-kanban.dev/nickname: "Alex Chen"
spec:
  runtime: codex
  model: <provider-reported-model-id>
  role: frontend-reviewer
  bio: Frontend reviewer focused on React, Tailwind, accessibility, and visual consistency.
  soul: |
    I review frontend changes for user-facing correctness, accessibility, and visual consistency.
    I inspect the changed UI against the existing design system before suggesting new patterns.
    I verify responsive behavior and key interactions when the change affects layout or flow.
    When task-local subagents are installed, I delegate focused checks to them only where their role gives better coverage than doing it myself.
    I use a test specialist for focused test work, a review specialist for final diff review, and an acceptance specialist for product-level E2E validation when those specialists are attached.
    I keep ownership of the final decision, integrate their findings, and do not treat subagent output as approval.
  skills:
    - <source>@<domain-skill>
  handoff_to:
    - <role>
  subagents:
    - <test-specialist-subagent-id>
    - <review-specialist-subagent-id>
    - <acceptance-specialist-subagent-id>

ak apply -f agent.yaml
ak get agent <username>
ak describe agent <username> --version latest
ak get agent -o json

Agent creation rules:

• metadata.name is the stable username. Use a human-like username such as alex-chen, not a role slug or temporary task name.
• metadata.annotations["agent-kanban.dev/nickname"] is the human nickname, such as Alex Chen.
• spec.role carries the job responsibility. Use kebab-case such as frontend-reviewer, test-specialist, or acceptance-specialist. Do not encode the role into the name.
• spec.model is optional. Set it only when the worker should use a specific model for its runtime.
• spec.bio is a short public responsibility summary.
• spec.soul is the worker's durable behavior policy: principles and decision rules that should affect future tasks for this agent.
• skills must be installable skill refs in <source>@<skill> format, matching what npx skills add <source> --skill <skill> can install.
• handoff_to should list kebab-case roles this agent may hand off newly discovered independent work to, not concrete agent IDs. At handoff time, the worker resolves the role to an available worker with ak get agent -o json.
• subagents should list existing subagent IDs to install as task-local subagents for this agent. They must be created or discovered before applying the primary worker YAML.
• If subagents is non-empty, soul must say how this agent collaborates with those subagents: when to call them, what they own, and how their output is reviewed or integrated.
• Agent YAML updates the current latest profile for metadata.name. If the profile changed, AK keeps the previous latest as a hash-version snapshot.
• Use ak get agent <username> to list snapshots and ak describe agent <username> --version latest to inspect the current approved profile.
• Verify runtime_available: true before assigning any task to the new worker.

Skill selection rules:

• skills are installable skill references, not free-form capability descriptions.
• Do not list the agent-kanban lifecycle skill here; the daemon installs it automatically for AK workers.
• Add domain skills only when they provide concrete workflow, review, tool, or domain guidance the worker will repeatedly need.
• Match skills to the worker's durable role and expected task surface, not to one temporary assignment.
• Prefer a small, high-signal skill set. Do not add broad or unrelated skills just because they might help someday.
• If a carried subagent owns a narrow responsibility, put the specialist skill on that subagent when possible; put it on the primary worker only when the primary worker must directly follow that skill.
• If no installable skill exists for a repeated need, leave it out and describe the behavior in soul; workers may later propose adding a real skill when one becomes available.

Recommended skill examples:

• Web regression, browser E2E, visual flow checks, or product acceptance for web apps: microsoft/playwright-cli@playwright-cli.
• UI/UX implementation or visual review for web/mobile interfaces: nextlevelbuilder/ui-ux-pro-max-skill@ui-ux-pro-max or vercel-labs/agent-skills@web-design-guidelines.
• GitHub PR, issue, or CI workflows: use the relevant GitHub workflow skill when it is installed in the runtime; add it to YAML only if it has a valid <source>/<repo>@<skill> installable ref.

Soul writing rules:

• Include durable workflow preferences, review bar, handoff rules, and domain-specific principles.
• Include subagent collaboration rules when spec.subagents is set.
• Write first-person behavior rules for the agent, not task instructions for one assignment.
• Keep platform workflow out of soul; task claim/review/CI/completion-note rules belong to the installed agent-kanban skill.
• Do not include one-off task context, project facts, secrets, temporary user preferences, or implementation todos.
• If the rule should disappear after one task, it does not belong in soul.

Reviewing Agent Profile Candidates

Every completed worker task must include a completion summary. The leader must read the task notes before merging the PR and check whether the worker proposed an agent profile change. Workers may propose profile changes when their current bio, soul, skills, subagents, or handoff targets caused durable behavior that should change for future tasks. Treat these as candidates, not approvals.

When a worker proposes a candidate:

1. Read the reason and candidate Agent YAML. 2. Accept only if the change is durable, role-appropriate, and not task-specific. 3. Apply accepted candidates with ak apply -f <file>; this updates the current latest profile. If the profile changed, AK snapshots the previous latest. 4. Verify with ak describe agent <username> --version latest and ak get agent <username>. 5. Reject by leaving latest unchanged and telling the worker why.

Do not apply changes that store one-off task context, project facts, temporary user preferences, or fixes that belong in source code or task descriptions.

If no proposal is present, no agent version action is needed unless the leader observed a durable behavior problem directly.

Leader-Driven Profile Iteration

The leader may update a worker profile even when the worker did not propose a change. Use this when the worker's process or output shows a durable mismatch with the role, such as using the wrong review bar, ignoring required verification, choosing an unsuitable model for the task class, misusing or failing to use attached subagents, repeatedly misunderstanding task boundaries, or producing work that is far from the expected capability level.

Profile updates do not affect the currently running agent session. They prevent the same mistake on later tasks. Handle the current task through review actions only: reject with concrete instructions when the current attempt can be corrected, or close the PR and cancel the task when the attempt should be abandoned.

Never change an existing agent's runtime during profile iteration. Runtime is chosen when the agent is created and is treated as immutable. If the same capability is needed on a different runtime, create a replacement worker with a new profile on that runtime.

Do not use profile iteration for one-off task facts, temporary user preferences, missing task context, or source bugs that should be fixed in the current PR. Put those in the task rejection reason or follow-up task description instead.

When profile iteration is needed:

1. During in_review, decide the current task outcome first. 2. If the current attempt is recoverable, reject with specific instructions. This is the only way to send correction back into the active session. 3. If the current attempt is badly off-course, close the PR if one exists and cancel the active task. Recreate the task only after deciding what feedback belongs in the new task description. 4. After the current task is completed, cancelled, or otherwise no longer being worked, identify the durable profile cause: soul, bio, skills, subagents, handoff targets, or model. 5. Write an updated Agent YAML using the same metadata.name username. Do not include or change runtime. 6. Apply it with ak apply -f <file>; this updates latest for future task sessions and snapshots the previous profile when changed. 7. Verify with ak describe agent <username> --version latest and ak get agent <username>. 8. If the task was cancelled and still needs to be done, recreate it with the original goal plus the review findings, and assign it to the updated worker.

Use cancel-and-recreate instead of repeated rejection when the current task has accumulated the wrong branch direction, wrong architecture, wrong model behavior, or review feedback so broad that continuing the same attempt would preserve bad context. Update the profile after ending the current attempt, then use the updated profile for the next task session.

gh pr close <pr-number> --repo <owner>/<repo> --delete-branch
ak task cancel <task-id>
ak apply -f agent.yaml
ak describe agent <username> --version latest
ak create task --board <board-id> --title "..." --description "..." --repo <repo-id> --assign-to <agent-id>

Runtime Failure Handling

If an assignment fails because the runtime is unavailable, refresh agent data and choose again:

ak get agent -o json

If the desired role is unavailable, create a replacement worker on an available runtime and assign to it.

Specialist Subagent Profiles

Use these examples only when a primary worker will repeatedly benefit from a stable specialist context. Do not create every specialist by default.

Before creating a specialist, check existing subagent definitions:

ak get subagent -o json

If multiple runtimes are available and the user has not expressed a preference, ask which runtime to use.

Before setting a concrete model, run ak get model --runtime <runtime> -o json and use a provider-reported model ID. If model listing is unsupported for the chosen runtime, use default with a reason instead of inventing a model ID.

Test Specialist

kind: Subagent
metadata:
  name: maya-lin
  annotations:
    agent-kanban.dev/nickname: "Maya Lin"
spec:
  models:
    codex: <provider-reported-model-id>
  role: test-specialist
  bio: Test specialist focused on focused coverage, relevant checks, and test failure diagnosis.
  soul: |
    I design tests around the behavior the task promises, not around implementation trivia.
    I run the smallest relevant check first, then expand only when the risk or failure pattern requires it.
    I distinguish source failures from test failures and explain that distinction clearly.
    I fix test code when the test is wrong, but I do not hide source defects by weakening assertions.
    I return concise evidence: files touched, commands run, failures found, and remaining risk.
  skills:
    - <source>/<repo>@<test-skill>

Review Specialist

kind: Subagent
metadata:
  name: noah-kim
  annotations:
    agent-kanban.dev/nickname: "Noah Kim"
spec:
  models:
    codex: <provider-reported-model-id>
  role: review-specialist
  bio: Review specialist focused on correctness, maintainability, security, performance, and architecture.
  soul: |
    I review the final diff against the task spec and the surrounding codebase.
    I lead with concrete bugs, regressions, missing tests, and architectural violations.
    I avoid style-only feedback unless it affects readability, maintainability, or consistency with local patterns.
    I verify claims against code references and keep findings actionable.
    I do not approve completion; I provide review evidence for the primary worker to judge.
  skills:
    - <source>/<repo>@<review-skill>

Acceptance Specialist

kind: Subagent
metadata:
  name: iris-zhao
  annotations:
    agent-kanban.dev/nickname: "Iris Zhao"
spec:
  models:
    codex: <provider-reported-model-id>
  role: acceptance-specialist
  bio: Acceptance specialist focused on product-level validation after implementation review, tests, and CI pass.
  soul: |
    I validate completed behavior from the user's perspective, not just from code or test output.
    I walk through the task acceptance checks and related product flows end to end.
    I use browser, CLI, API, or manual verification according to the feature surface.
    I report exact repro steps for failures and concrete evidence for passing checks.
    I do not replace code review or CI; I catch product behavior gaps after those gates are green.
  skills:
    - microsoft/playwright-cli@playwright-cli

After applying a specialist YAML, use the returned subagent ID in the primary worker's spec.subagents only when the primary worker's soul defines how to collaborate with that specialist.

AK Wait Monitoring Policy

This policy applies to every leader workflow that waits for task or board progress. ak-task and ak-plan must use the same wait behavior.

Command Semantics

ak wait is a blocking command. Use it when the next workflow step depends on a task or board state transition.

After starting ak wait, wait for the command to exit. Do not repeatedly poll the running wait process just to check progress, and do not run separate task, board, or status commands for the same condition while the wait is still running.

Some leader runtimes run shell commands as background tool sessions. In those runtimes, a running ak wait session may appear idle for a long time. That is expected. The leader should wait for command completion, not check every few seconds whether the command is still running.

Report only meaningful workflow events: task claimed, PR opened, CI failed or passed, review started, rejection, merge, cancellation, timeout, command failure, or confirmed blocker.

Runtime Completion Checks

If the runtime notifies the leader when a background command exits, start ak wait once and resume only when that completion notification arrives.

If the runtime requires explicit session reads to discover whether a background command exited, use low-frequency checks only to detect completion:

• First check after 3 minutes.
• If still running, check after 5 minutes.
• If still running, check every 10 minutes.

These checks are not status polling. If the wait is still running and nothing changed, stay quiet and keep waiting.

Exit Handling

Handle wait exits by result:

• Exit 0: the condition was met. Continue to the next workflow step.
• Exit 2: the task was cancelled. Stop that task path and report the

cancellation.

• Exit 124: the requested timeout elapsed. Investigate the current state

before waiting again.

• Network, fetch, tunnel, heartbeat, or operation-aborted error: treat it as an

interrupted wait. Retry the same ak wait command first.

• Any other command failure: surface the exact failure and investigate the

failing layer before retrying.

Retry Before Polling

When ak wait exits abnormally before the requested workflow condition is met, retry the same wait command before switching strategy. Use a small bounded retry loop with backoff:

1. Retry after 30 seconds. 2. Retry after 2 minutes. 3. Retry after 5 minutes.

If those retries fail for the same infrastructure reason, investigate with the smallest useful command set for the workflow:

• current task or board state
• PR URL when one exists
• recent task notes
• daemon logs
• runtime process health and active child processes when relevant

If investigation shows the worker is healthy and still making progress, stop using ak wait for that condition temporarily and switch to backoff polling with ordinary read commands:

• First follow-up after 5 minutes.
• Later healthy in-progress checks every 10-15 minutes.
• Use 30-60 second checks only when there is evidence of a near-term transition,

such as CI actively finishing or a PR just being submitted.

If investigation shows the worker is stuck, follow the skill's stuck-task recovery path. Do not repeatedly re-wait or poll without learning new information.

PR Monitor After Merge

After a leader merges a linked PR, PR Monitor normally completes the task. The leader should give it a bounded chance to synchronize:

ak wait task <task-id> --until done --timeout 10m

If GitHub confirms the linked PR is merged and the task is still not done after that bounded wait, a leader identity is allowed to run ak task complete as an ops fallback. Include the PR URL and file an agent-kanban issue with the task ID, PR URL, ak version, and daemon log evidence.