kandev-protocol

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.

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

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" \
  --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      Update task status
task update [--id ID] --comment C     Add a status-change comment
task create --title T [--parent ID]   Create a task or subtask
         [--assignee A] [--priority P]

comment

tasks message [--id ID] --prompt P    Post an agent-authored comment
comment add [--task ID] --body BODY   Simulate a user comment for fixtures
comment list [--task ID] [--limit N]  List comments on a task

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:

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 and block your task on it. 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.