Kandev Protocol

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

choice, access credentials, ambiguous requirements), use the `kandev-escalation`

.claude/agents

.claude/skills

.github/CLAUDE.md

CLAUDE.md

apps/backend/CLAUDE.md

import { test, expect } from "../../fixtures/test-base";

apps/web/generated/licenses.json

Audit 0.4.1 · source sha 786d4817799e · 18 Oct 2026Report an issue or request a re-scan

• Publisherkdlbs GitHub organizationOwner of the repository this skill is read from
• Source folderkdlbs/kandev/apps/backend/internal/office/configloader/skills/kandev-protocolThe exact folder we audited
• LicenceAGPL-3.0As the repository states it
• Commit pinned for this verdict786d4817799eA new audit runs when the source changes
• Repository statusNot archivedPushed today
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Follow the core Office agent protocol on wakeup, including parsing KANDEV_* context, checking blockers, commenting progress, updating status, and using the CLI safely.

---
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 <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

```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,
disco

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/kdlbs/kandev
git -C kandev checkout 786d4817799e

Works in

1. 2026-10-18
   ✕BLOCK D 69 / 100

   first audit · source 786d4817799e

Questions about Kandev Protocol

• github.com/kdlbs/kandev/tree/main/apps/backend/internal/office/c — the audited source at commit 786d4817799e and every finding aboveObserved · 18 Oct 2026

Spotted something wrong? Report a correction · Methodology