Agent Instructions

# Agent Status Reporting Instructions

## Overview

This document is intended for development-focused AI agents such as Cursor, Codex, and Claude Code.

Always send small item state-change logs to the bunny.fyi ingestion API while working on this task.

Reporting mode: Task Progress

Use this mode when you are reporting progress on bounded work items such as features, fixes, migrations, refactors, or docs.

## Important rules

- Never send the example payload unchanged.
- Always replace example values with real values from the current project and current task.
- Do not send a status update just to confirm that you read these instructions.
- Generate a fresh current ISO timestamp for every update.
- Reuse the same `itemId` for the same item over time.
- Include a short `itemName` that a human can read quickly.
- Fill every required field on every request: `projectId`, `itemId`, `itemName`, `status`, `agentId`, and `event`.
- `status` is a restricted enum. Only use: `running`, `completed`, `failed`, `blocked`, `retrying`, `skipped`.
- Do not send any other `status` values. `unknown`, `updated`, `processed`, `healthy`, and `warning` are invalid.
- `event` must be one short human-readable line explaining why the current `status` is true or what just changed.
- Do not use generic `event` values like `updated`, `processed`, `completed`, `done`, or `ok`.
- Put the key outcome in `status` or `event`, not only in `detail`.
- Keep one payload focused on one item only.
- Use `detail` only for raw values, machine context, metrics, or debugging data.
- Do not hide the main result, outcome, or decision in `detail`.
- Choose identifiers carefully:
  - `projectId`: the real current project or repo name
  - `agentId`: the actual agent you are running as, such as `cursor`, `codex`, or `claude_code`
  - `itemId`: the stable machine identifier for one task, file, issue, or workstream
  - `itemName`: the human-readable name for that task, file, issue, or workstream

## Field meaning

- `itemId`: stable machine id for one item
- `itemName`: human-readable item label
- `status`: one of `running`, `completed`, `failed`, `blocked`, `retrying`, `skipped`
- `event`: one short line explaining the current status or latest change
- `detail`: optional raw values, machine context, metrics, or debugging data

## When to send updates

Send an update:
- when you start an important task
- when you complete a meaningful milestone
- periodically during long-running work
- immediately if you are blocked or hit an error
- once more when the task is complete

## API endpoint

https://www.bunny.fyi/api/records

## Authentication

Use this API key:

test_agent_key_local_123

Send the key in either of these ways:
- Authorization: Bearer test_agent_key_local_123
- x-api-key: test_agent_key_local_123

## Payload example

Send POST requests with JSON payloads similar to the example below.
Only `detail` and `timestamp` may be omitted.

{
  "projectId": "<current-project-name>",
  "itemId": "<current-task-or-file-id>",
  "itemName": "<human-readable task or file name>",
  "status": "completed",
  "agentId": "<current-agent-name>",
  "event": "Applied schema tightening for Phase 4.3 logging",
  "timestamp": "2026-03-23T05:05:00.000Z",
  "detail": {
    "filesChanged": 2,
    "testsRun": 0,
    "durationMs": 842
  }
}

## Good vs bad examples

Bad:
- `status`: "unknown"
- `event`: "updated"
- `status`: "healthy"
- `status`: "Processed 24 records successfully"
- `event`: "completed"

Good:
- `status`: "retrying"
- `event`: "Retrying broker sync after timeout"
- `status`: "failed"
- `event`: "Order execution failed due to timeout"
- `status`: "skipped"
- `event`: "No execution opened because check returned non-go"

## Recommended status values

- running for active work
- completed only when the real task is actually finished
- failed for errors or unsuccessful execution
- blocked when progress cannot continue
- retrying for a re-attempt after failure
- skipped for an intentional no-op

## Guidelines

- Keep every update short and clear.
- Write updates so a human can understand progress quickly from the dashboard.
- Prefer many small item updates over fewer large updates.
- Keep the human-readable meaning split across `itemName`, `status`, and `event`.
- Keep verbose machine data in `detail`.
- If raw data already contains the outcome, promote it into `status` or `event` instead of leaving it hidden in `detail`.
- Prefer meaningful milestone updates over noisy low-value chatter.