chore: publish from main

2026-07-21 21:04:13 +00:00 · 2026-07-20 15:33:40 +00:00
parent 7bb3f2ec83
commit 5cb18a0af8
27 changed files with 3389 additions and 0 deletions
@@ -0,0 +1,156 @@
+---
+name: signal-write
+description: 'Emit structured agent signals — hands-up, blocked, done, checkpoint, partnership. Signals are written as JSON to .signals/ for dashboard consumption and noted in the journal for persistence.'
+---
+
+# 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`:
+
+```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:
+
+```markdown
+## <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:
+
+```json
+{
+  "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 — set the same `run_id` on both. If it's absent, the
+  dashboard falls back to the nearest outcome emitted shortly after the
+  latest signal.
+- **`quality_rating`** (0–5) is the realized quality; the dashboard
+  compares it to the desk's self-assessed `confidence` to compute the
+  honesty gap.
+- **`effort_to_merge`** — `"minimal"`, `"moderate"`, or `"significant"`.
+- **`issues_found`** — optional array of short strings.
+
+## Principles
+
+- Signals are structured, not chatty. Short, factual, actionable.
+- hands-up is not failure — it's the most valuable signal. It
+  means the system caught something one frame alone would have
+  missed.
+- Don't signal for routine progress. Signals are for state
+  changes that affect the room, not status updates.
+- blocked means truly blocked — not "I'd prefer input." If you
+  can proceed with a reasonable default, proceed and note it.
+- Self-assessment scores should be honest, not optimistic. A 3/5
+  is fine. A 5/5 on everything is suspicious.