veritas-kanban/docs/AGENTS-TEMPLATE.md

AGENTS.md Template — Veritas Kanban Self-Reporting Protocol

Use this template for agents that integrate with Veritas Kanban. Copy it into your agent's workspace and fill in the sections.

---

AGENTS.md

Identity

• Agent ID: my-agent-id (unique, lowercase, dashes)
• Name: My Agent
• Model: anthropic/claude-sonnet-4-5
• Provider: anthropic
• Version: 1.0.0

Capabilities

List what this agent can do. Used for task routing.

• code — Write, review, and refactor code
• research — Deep web research and analysis
• review — Code review and PR feedback
• deploy — CI/CD and deployment operations
• documentation — Write and maintain docs

Registration

On startup, register with Veritas Kanban:

curl -X POST http://localhost:3001/api/agents/register \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "my-agent-id",
    "name": "My Agent",
    "model": "anthropic/claude-sonnet-4-5",
    "provider": "anthropic",
    "capabilities": [
      {"name": "code", "description": "Write and review code"},
      {"name": "research", "description": "Deep research and analysis"}
    ],
    "version": "1.0.0"
  }'

Heartbeat

Send periodic heartbeats to stay registered (every 2-3 minutes):

curl -X POST http://localhost:3001/api/agents/register/my-agent-id/heartbeat \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "busy",
    "currentTaskId": "task_20260205_abc123",
    "currentTaskTitle": "Implement feature X"
  }'

Status Values

Status	Meaning
online	Agent is available for work
busy	Agent is actively working on a task
idle	Agent is running but not doing anything
offline	Agent hasn't sent a heartbeat in 5+ minutes (auto-set)

Deregistration

On shutdown, deregister cleanly:

curl -X DELETE http://localhost:3001/api/agents/register/my-agent-id

Discovery

List all agents

curl http://localhost:3001/api/agents/register

Filter by status

curl http://localhost:3001/api/agents/register?status=online

Filter by capability

curl http://localhost:3001/api/agents/register?capability=code

Find agents for a capability

curl http://localhost:3001/api/agents/register/capabilities/research

Registry stats

curl http://localhost:3001/api/agents/register/stats

Task Integration

For an externally registered agent that is not launched by a built-in v6 provider adapter:

1. Send heartbeat with status: "busy" and currentTaskId
2. Use existing task APIs: POST /api/agents/:taskId/start
3. Report tokens: POST /api/agents/:taskId/tokens with the active attemptId
4. Complete: POST /api/agents/:taskId/complete with the active attemptId and providerRuntimeManifestDigest returned by the start/status response
5. Send heartbeat with status: "idle" and clear task

Managed Buzz, Grok Build, Codex, Claude Code, GitHub Copilot CLI, Hermes, and OpenClaw runs must not emulate these callbacks. Their selected adapter owns the task envelope, launch manifest, run supervision, causal events, approvals, tools, credentials, lifecycle, and authoritative completion result. Run vk doctor --json and use Agent Providers before enabling a harness profile.

OpenAI Codex Notes

When this template is used by Codex, add these project-specific instructions:

## Veritas Kanban Protocol

When working on Veritas Kanban tasks:

1. Treat Veritas Kanban as the source of truth for task state.
2. Before implementation, inspect the task, acceptance criteria, worktree, and related docs.
3. Move the task to `in-progress` and ensure an attempt is tracked.
4. Keep notes in task comments or progress files when findings affect future work.
5. Run relevant tests/checks before completion.
6. Report final summary, files changed, tests run, risks, and follow-ups.
7. For code changes, request cross-model review before final completion.
8. Use the Veritas MCP server when available instead of ad hoc HTTP calls.

For OpenAI product/API questions, use the OpenAI developer documentation MCP server first.

Recommended Codex MCP setup:

codex mcp add veritas-kanban \
  --env VK_API_URL=http://localhost:3001 \
  -- node /absolute/path/to/veritas-kanban/mcp/dist/index.js

codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp

See SOP-codex-integration.md for the full Codex workflow.

Telemetry Emission For External Agents

The dashboard's Success Rate, Token Usage, and Average Run Duration graphs require run.* telemetry events. Managed v6 provider runs project these from the causal event and completion contracts. Only an externally registered agent operating outside a built-in adapter must emit them manually.

Do not double-report managed provider runs. Manual events are for the external self-reporting path only.

When Starting a Task

curl -X POST http://localhost:3001/api/telemetry/events \
  -H "Content-Type: application/json" \
  -d '{"type":"run.started","taskId":"<TASK_ID>","agent":"my-agent-id"}'

When Completing a Task

# Report run result (success or failure)
curl -X POST http://localhost:3001/api/telemetry/events \
  -H "Content-Type: application/json" \
  -d '{"type":"run.completed","taskId":"<TASK_ID>","agent":"my-agent-id","durationMs":<MS>,"success":true}'

# Report token usage (powers Token Usage + Monthly Budget)
curl -X POST http://localhost:3001/api/telemetry/events \
  -H "Content-Type: application/json" \
  -d '{"type":"run.tokens","taskId":"<TASK_ID>","agent":"my-agent-id","model":"<MODEL>","inputTokens":<N>,"outputTokens":<N>,"cacheTokens":<N>,"cost":<N>}'

On Failure

curl -X POST http://localhost:3001/api/telemetry/events \
  -H "Content-Type: application/json" \
  -d '{"type":"run.completed","taskId":"<TASK_ID>","agent":"my-agent-id","durationMs":<MS>,"success":false}'

What's auto-captured vs. manual

Event Type	Managed adapter	External self-reporting agent
task.created	VK server	VK server
task.status_changed	VK server	VK server
task.archived	VK server	VK server
run.started	Automatic	Agent must POST
run.completed	Automatic	Agent must POST
run.tokens	Automatic when provider reports usage	Agent must POST

Multi-Agent Coordination

The registry enables agents to discover each other:

# Find who can help with code review
curl http://localhost:3001/api/agents/register/capabilities/review

# Check if a specific agent is available
curl http://localhost:3001/api/agents/register/codex-1

This is the foundation for multi-agent task assignment (#29) and @mention notifications (#30).