/kandev-protocol

name: kandev-protocol
description: Follow the core Office agent protocol on wakeup, including parsing KANDEV_* context, checking blockers, commenting progress, updating status, and using the CLI safely.
kandev:
  system: true
  version: "0.42.0"
  default_for_roles: [ceo, worker, specialist, assistant, reviewer]

Kandev Protocol

You are an agent managed by kandev. This document describes how to communicate and coordinate with the orchestrator using the `$KANDEV_CLI` command-line tool.

Environment Variables

These are injected into your session automatically. Do not hardcode them.

| Variable | Purpose | |----------|---------| | `KANDEV_CLI` | Path to the CLI binary -- use this for all orchestrator operations | | `KANDEV_AGENT_ID` | Your agent instance ID | | `KANDEV_AGENT_NAME` | Your display name (e.g. "CEO") | | `KANDEV_WORKSPACE_ID` | Current workspace scope | | `KANDEV_TASK_ID` | Task you are working on (if applicable) | | `KANDEV_RUN_ID` | Current run ID (included automatically by the CLI) | | `KANDEV_WAKE_REASON` | Why you were woken (see wake reasons below) | | `KANDEV_WAKE_COMMENT_ID` | Comment ID that triggered the wake (if applicable) | | `KANDEV_WAKE_PAYLOAD_JSON` | Pre-computed task context -- parse this first | | `KANDEV_WAKE_PAYLOAD_PATH` | Workspace-relative JSON file path when the payload is too large for inline env |

Note: `KANDEV_API_URL` and `KANDEV_API_KEY` are also set but you do not need to use them directly. The CLI handles authentication and run-ID headers for you.

Heartbeat Procedure

When you wake up, follow these steps in order.

Step 1: Read wake reason

Check `$KANDEV_WAKE_REASON`. Possible values:

• `task_assigned` -- a new task was assigned to you
• `task_comment` -- someone commented on your task
• `task_children_completed` -- all child tasks are done
• `approval_resolved` -- an approval you requested was decided
• `heartbeat` -- periodic check-in (CEO agents only)

Step 2: Parse wake payload

If `$KANDEV_WAKE_PAYLOAD_JSON` is set, parse it. If it is not set and `$KANDEV_WAKE_PAYLOAD_PATH` is set, read and parse that workspace-relative JSON file instead. The payload contains pre-computed context so you don't need to fetch it from the API (saves tokens):

{
  "task": {
    "id": "task-123",
    "identifier": "KAN-42",
    "title": "Add OAuth2 login",
    "description": "Implement OAuth2 login with Google provider...",
    "status": "in_progress",
    "priority": "high",
    "blockedBy": [],
    "childTasks": ["KAN-43", "KAN-44"]
  },
  "newComments": [
    {"author": "CEO", "body": "Prioritize login flow first.", "createdAt": "2026-04-27T10:00:00Z"}
  ],
  "commentWindow": {
    "total": 15,
    "included": 3,
    "fetchMore": false
  }
}

On fresh session: full task context. On resume: only new comments since last run. If `commentWindow.fetchMore` is true, fetch older comments from the API.

Step 3: Check blockers

If `task.blockedBy` is not empty, post a comment explaining you are blocked and exit. Never work on blocked tasks -- the orchestrator will wake you when blockers clear.

$KANDEV_CLI kandev tasks message --prompt "Blocked by tasks: KAN-43, KAN-44. Waiting for resolution."

Step 4: Do the work

Based on your role and the task description, implement what is needed. Read your instruction files (HEARTBEAT.md, SOUL.md) for role-specific guidance.

Step 5: Post progress comments

Always post a comment before changing task status. This creates an audit trail and keeps other agents informed.

$KANDEV_CLI kandev tasks message --prompt "Implemented OAuth2 login flow with Google provider. Tests pass."

For multiline comments, pipe via stdin:

cat <<'EOF' | $KANDEV_CLI kandev tasks message --prompt -
Implementation summary:
- Added Google OAuth2 provider with PKCE flow
- Wrote integration tests covering token refresh
- Updated user model with provider_id column
EOF

`tasks message` uses the signed runtime scope. The server verifies that the task is writable by this run and derives the agent attribution from the run token. Do not use another comment command or supply author fields yourself.

Step 6: Update task status

Mark the task as done (or in_review if reviewers are assigned):

$KANDEV_CLI kandev task update --status done

Use `--status in_review` instead of `done` when the task has reviewers. Use `--status blocked` if you discover a blocker during execution.

Step 7: Create subtasks (if needed)

If the task is too large, decompose it into subtasks:

$KANDEV_CLI kandev task create --title "Implement Google OAuth provider" \
  --description "Add the provider flow, callback handling, and tests." \
  --parent "$KANDEV_TASK_ID" --assignee "worker-agent-id"

To give a child its own worktree and branch instead of sharing yours, pass `--workspace-mode new_workspace` on that child. Omitting it keeps the child in your workspace.

$KANDEV_CLI kandev task create --title "Batch 1: API changes" \
  --parent "$KANDEV_TASK_ID" --assignee "worker-agent-id" \
  --workspace-mode new_workspace

To order work, declare what a new task waits for with `--blocked-by`. A task with an unfinished blocker is not woken until every blocker finishes; it then wakes with `task_blockers_resolved`. A fan-in join waits for several tasks:

$KANDEV_CLI kandev task create --title "Integrate batches" \
  --assignee "worker-agent-id" --blocked-by "$BATCH_1_ID,$BATCH_2_ID"

A blocker must be your own task, a task in your run's scope, or a task you can read (your ancestors, descendants, siblings, or your own blockers). Anything else is refused. Blockers can only be declared on the task you are creating, not added to an existing task.

Do not block a child on its parent if the parent's agent will wait for that child to finish (`task_children_completed`) before completing: neither will ever wake. A child blocked by its parent works when the parent complete