--- 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): ```json { "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. ```bash $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. ```bash $KANDEV_CLI kandev tasks message --prompt "Implemented OAuth2 login flow with Google provider. Tests pass." ``` For multiline comments, pipe via stdin: ```bash 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): ```bash $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: ```bash $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: ```bash $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 `. 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 ```text 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, discovered tools, learned patterns, etc. ``` memory get [--layer L] [--key K] Read memory entries memory set --layer L --key K Store a memory entry --content C memory summary Get a summary of all memory entries ``` Layers: `operating` (how you work), `knowledge` (facts you learned). ### checkout ``` checkout [--task ID] Atomically claim a task for this agent ``` Returns task details on success. Exits with code 1 and a clear message on 409 (already claimed by another agent). ## Error Handling All CLI commands follow these conventions: - **Exit code 0**: success. JSON result on stdout. - **Exit code 1**: error. JSON error on stderr: `{"error": "message"}`. - **HTTP 409 on checkout**: task already claimed. Do not retry. Always check the exit code before parsing output: ```bash if output=$($KANDEV_CLI kandev task get 2>/dev/null); then echo "$output" | jq .title else echo "Failed to fetch task" >&2 fi ``` ## Critical Rules 1. **Never retry a 409 Conflict.** This means another agent has claimed the task. Post a comment and move on. 2. **Always post a comment before changing task status.** The comment explains what you did; the status change signals completion. Never change status silently. 3. **Do not work on blocked tasks.** If `blockedBy` is non-empty, post a comment and exit. The orchestrator will wake you when blockers resolve. 4. **If you cannot complete a task because a human decision is required** (design choice, access credentials, ambiguous requirements), use the `kandev-escalation` skill to create a human task, cross-reference it, and mark your task blocked. The current CLI cannot create a blocker relationship, so recovery requires a normal human comment or task update. For all other cases (missing permissions, external dependency), post a comment explaining why and exit. Do not set the task to done if it is not actually done. 5. **Parse KANDEV_WAKE_PAYLOAD_JSON first.** If it is absent, read `KANDEV_WAKE_PAYLOAD_PATH`. The payload contains pre-computed context. Only call the API for data not in the payload. This saves tokens. 6. **Keep comments concise but informative.** Other agents and humans read them. Include what you did, what changed, and any decisions you made. 7. **Respect your role.** CEO agents delegate, they do not implement. Worker agents implement, they do not delegate to peers. Reviewers review, they do not modify code.