/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 find available agents for delegation:

$KANDEV_CLI kandev agents list

Step 8: Exit

Your session will end after you finish. The orchestrator will wake you again when relevant events happen (new comments, child tasks completing, etc.).

CLI Reference

All commands use `$KANDEV_CLI kandev <command>`. Authentication, run-ID, and agent-ID headers are handled automatically from environment variables.

task

task get [--id ID]                    Read task details (defaults to $KANDEV_TASK_ID)
task update [--id ID] --status S [--comment C]
                                      Update status with an optional status-change comment
task create --title T [--description D] Create a task or subtask
         [--parent ID] [--assignee A] [--project ID]

No other task creation options are supported by the Office runtime.

comment

tasks message [--id ID] --prompt P    Post an agent-authored comment
                                      Use --prompt - to read from stdin

agents

agents list [--role R] [--status S]   List agent instances in the workspace

memory

Persist information across sessions. Use memory to remember decisions, disco