Kandev Protocol

---
name: kandev-protocol
description: How to interact with the kandev orchestrator via the CLI
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 |

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. It 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 comment add --body "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 comment add --body "Implemented OAuth2 login flow with Google provider. Tests pass."
```

For multiline comments, pipe via stdin:

```bash
cat <<'EOF' | $KANDEV_CLI kandev comment add --body -
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):

```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" \
  --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 <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

```
comment add [--task ID] --body BODY   Post a comment (--body - reads stdin)
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:

```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 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.** It 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.