Signal-Write

# Agent Signals

Emit structured signals from a desk to the operator or other desks.

When to use

- A desk needs operator attention (hands-up, blocked)

- Work is complete and ready for review (done)

- Significant progress worth noting (checkpoint)

- Two desks disagree and can't resolve it (hands-up)

- The TA is reporting coordination quality (partnership)

Signal types

`hands-up`

Two desks disagree and can't settle it against external facts.

This is the system working — the operator reads where desks

*disagree*, not where they perform confidence.

`blocked`

A desk can't proceed without input — missing access, ambiguous

scope, need a decision only the operator can make.

`done`

Work is complete and ready for review. Artifacts are on the bench.

`checkpoint`

Significant progress worth the operator knowing about, but work

continues. Not blocked, not done — just a marker.

`partnership`

Used by the TA (room coordinator) to report coordination quality.

Self-assessment scores reflect coordination, not code accuracy:

- **intent** — understood what the operator needed

- **confidence** — right work went to the right desks

- **accuracy** — dispatched work produced the right outcome

- **completeness** — nothing fell through the cracks

How to emit

1. Write a JSON signal file to `.signals/`

This is the primary output — it's what the dashboard reads.

Create `desks/<desk-name>/.signals/<timestamp>.json`:

{
  "signal_type": "execution",
  "subtype": "checkpoint",
  "timestamp": "2026-07-19T21:30:00Z",
  "run_id": "<optional; set to pair this with an outcome signal>",
  "agent_name": "<desk-name>",
  "self_assessment": {
    "intent": 4,
    "confidence": 5,
    "accuracy": 4,
    "completeness": 3
  },
  "patterns": {
    "what_worked": "description of what went well",
    "what_was_hard": "description of challenges",
    "skill_gap": "areas for improvement"
  },
  "escalation": {
    "reason": null,
    "blocked_on": null,
    "recommendation": null
  }
}

Signal type mapping

| Signal | `signal_type` | `subtype` |

|-----------|-----------------|----------------|

| hands-up | `"escalation"` | `"hands-up"` |

| blocked | `"escalation"` | `"blocked"` |

| done | `"execution"` | `"done"` |

| checkpoint| `"execution"` | `"checkpoint"` |

| partnership| `"partnership"` | `"partnership"`|

The `subtype` field preserves the specific signal state for

dashboard consumers. `signal_type` controls sort priority

(escalation → top).

> **Note:** The signals-dashboard canvas extension reads `subtype`

> when present and falls back to `signal_type` for display. If

> consuming signals in your own tooling, prefer `subtype` for the

> specific state.

> **Ordering:** include a `timestamp` (ISO 8601 UTC). The dashboard

> orders signals by it and falls back to file mtime only when it's

> absent — a git clone/checkout resets mtimes, so mtime alone is not a

> dependable clock.

2. Note the signal in the journal

Also append a short marker to the desk's journal for persistence:

## <date> — [signal:<type>] <summary>
- <key details>

The journal note is the trail marker. The JSON file is the

machine-readable signal.

Outcome signals (calibration)

The signals-dashboard can pair a desk's self-assessment with an

*outcome* — an independent rating of the realized result — and show

the **honesty gap** (how far the desk's confidence was from the

delivered quality). Outcome signals are optional and are usually

emitted by a reviewer/evaluator, not the desk itself.

Write them to the **same** `.signals/` directory:

{
  "signal_type": "outcome",
  "run_id": "<same run_id as the signal it rates>",
  "agent_name": "<reviewer name>",
  "quality_rating": 4,
  "effort_to_merge": "minimal",
  "issues_found": ["optional short strings"],
  "timestamp": "2026-07-19T22:00:00Z"
}

- **`run_id`** correlates an outcome with the execution/partnership

signal it rates —