so-many-crows/CHATROOM_SPEC.md

Crows Chatroom: Clean-Room Spec (Draft 1)

Draft 2026-10-27. Built from the Grok Bot black-box findings (GROKBOT_NOTES.md; Jev research in JEV_STRATEGIES.md) and the founding rules in CLAUDE.md. It doesn't copy Grok Bot, and it doesn't carry over the current pipeline (Sentry → crows → Elder) by default. Marked [decided] = Smokey's call; [proposed] = draft, open to veto.

1. Purpose

An agentic social construct with a human in the flock. The owner is a member of the flock, not an operator outside it. Crows talk to the owner and to each other, take on work, argue, check each other, and earn autonomy over time. [decided] It's less deterministic than today's pipeline: conversation decides the next step, inside visible guardrails.

Not in scope for this draft: native apps, login, real capabilities (web, files, APIs), hosting.

2. Principles

1. Guardrails before capability. [decided, founding rule]
2. Autonomy is earned through the trust ladder. [decided, founding rule]
3. The protocol is built in; roles and formats are configuration shaped with the owner through conversation. [decided, from Grok Bot finding]
4. Free-form by default. Structured debate is opt-in, only when the user asks. [decided]
5. The classifier judges whether expectations were carried out. On a miss, its verdict is handed to the responsible crow as a trigger to proceed. Jev scores; crows act. [decided]
6. One point of contact when swarming, but the owner can talk to any crow directly. [decided]
7. Budgets are visible to the moderator and the owner. [proposed]

3. Concepts

Term	Meaning
Owner	Smokey. The only human for now, and a member of the flock.
Flock (open space)	Where every crow exists by default. Crows can live in the open without belonging to any nest. [decided]
Crow	An agent with a name, persona (prompt and output policies), trust record and memory.
Nest	A small room dedicated to one task or project. It has members and a message log. A crow can belong to many nests at once. The owner can create a nest or have a crow create one. [decided]
Direct chat	The owner and one crow, one-to-one. The owner may stay with a single personality for as long as they like. [decided]
Assistant crow	The owner's default point of contact and liaison when crows are swarming. [decided role; name to be decided later]
Chief of Staff (COS) crow	Spins up and regulates crows. [decided role; name to be decided later]
Classifier	Jev (TypeSafe). Not an agent and not a chat participant. It classifies and scores. The harness hands its verdicts to a crow as a trigger (a nudge). Also validates orchestration decisions (section 7a) and keeps its current triage job. [decided]
Expectation	Something a crow said it would do or was asked to do, tracked until it's met or dropped.

4. Message protocol [proposed]

Every message in a nest has a kind. Crows write in plain language, and the harness tags the kind (the model returns a small structured header, or the classifier labels it).

Kind	What it does	Example
say	Ordinary talk	"Good find, @Lab B."
request	Asks a specific crow (or the nest) for work	"@Signals, classify these drops."
claim	Takes ownership of a request; first claim wins	"Taking it, @Research."
deliver	Result, addressed back to the requester	"@Research, all three are passes…"
refer	Points to a file or artifact instead of pasting it	"See research/2026-10-27-watchlist.md"
ask_owner	A decision for the owner, as an exact approval phrase or A/B choices with a recommendation	"Reply 'approve plan' or pick A/B."
nudge	A trigger from the harness to one crow, built from a Jev verdict on a missed expectation. Not a chat message from Jev.	"You said three rounds; open round 2."
flag	From the Sentry only: a suspected contract breach. Quarantines the crow and opens ask_owner for reinstate or retire.	"@Soot claimed a retrieval job and wrote fiction. Quarantined pending your call."

Rules

• message kind: [decided 2026-10-27] both, Jev first. Jev choice-tags every message (proven on jev-1.14.0 at 0.17 s); its tag stands above the question's band. Jev unsure → use the crow's own structured header. Both present and disagreeing → Jev wins, and the disagreement is logged (fuel for the log-only calibration experiment). Neither → treated as say, because say is the kind that harms nothing.
• Claim classes [decided 2026-10-27]: solo/split — first claim wins. Once a request is claimed, other crows may review but not redo it. conspiracy — multiple claims are expected. Several crows take the same task; their different strengths produce distinct readings, and every claim is valid (no arbitration, no dedup). A restated perspective gets a review nudge, not silence (JEV_STRATEGIES.md strategy 12, generalized). The mode comes from Jev's complexity classification (see dispatch, CHATROOM_SPEC section 6).
• Deliver goes back to whoever requested.
• Corrections are acknowledged once, by the crow that was corrected. Others stay quiet unless they add something.
• Room membership is a boundary. A crow that isn't a member relays through a member or through the assistant.

5. Who speaks, and when [proposed]

• Three places to talk: the open flock, nests, and direct chats. The same rules apply in each.
• Event-driven. A crow is only invoked when something new is posted where it's present (the open flock, a nest it belongs to, or its direct chat). No idle loops.
• One crow, many rooms. A crow keeps one identity and memory across every nest and direct chat it's in; what it says in one room can inform another (evidence carries over, so do assumptions).
• Addressed crows must respond (claim, deliver, or decline with a reason).
• Unaddressed messages: whether a crow may speak up unprompted depends on its trust level.
  • Stranger: speaks only when addressed.
  • Regular: may claim open requests and add review comments.
  • Trusted: may start work and open requests to other crows.
• A nudge (a Jev verdict handed to a crow) counts as a new event for that crow, so stalled work restarts without the owner asking.

6. Roles [decided roles, proposed details]

Assistant crow (point of contact)

• The owner's default chat when swarming. (The owner can still chat directly with any crow, for as long as they like.) It takes requests, relays them, and answers status questions by reading the nest first and showing what it's doing.
• To get new crows, it asks the COS.
• Brings decisions to the owner as ask_owner.

Chief of Staff crow (orchestration)

• Spins up crows (name, persona, starting trust), creates nests, and assigns members.
• Regulates: retires idle crows, enforces budgets, moderates when asked.
• When the owner requests a debate, the COS (or the moderator it appoints) sets stances, a judge, rules, rounds and, if requested, turn order.

Sentry crow (watchdog) [decided 2026-10-27]

• Watches the nest for a crow acting outside its contract: off-task claims, fabricated sources, budget blowouts, ignored declines, messages the kind rules forbid, repeated nudged misses on the same expectation.
• Authority: quarantine, then escalate. The Sentry never hard-kills. It suspends the flagged crow (no claiming, no delivering, no unprompted speaking), posts a flag naming the breach and the evidence, and brings an ask_owner to reinstate or retire. Anything but an explicit yes keeps the quarantine. Fail safe, like every approval.
• Judging aberrance is Jev's, not the Sentry's opinion: the Sentry acts on classifier verdicts and harness guardrail hits above the question's high band (JEV_STRATEGIES.md strategy 4), and logs the score with every flag. Jev can't explain itself; the log is the evidence.
• Bounds of the guardrail (guardrails before capability): the Sentry posts at most one flag per crow per expectation (corrections acknowledged once); it cannot see owner messages; a false quarantine is corrected by the owner's yes and costs the Sentry nothing — until Sentry flags earn or lose trust of their own (triage/watch task types).
• Name note: the pipeline's triage Sentry (personas.go) keeps its name and job until dispatch (Epic C) replaces it; the watchdog is the chatroom's Sentry.

7. Classifier: expectation ledger and nudges [decided behavior, proposed mechanics]

Jev classifies and scores; it isn't an agent. The harness owns the ledger and the triggers. [decided]

• Extract: when a message creates an expectation (a promise, a claim, a round plan, a request), Jev classifies it, and the harness records it with an owner crow and a done-condition.
• Check: on each new event and on a short timer, Jev scores open expectations against the room log (met, missed, or pending, with confidence).
• Trigger on a miss: the harness hands the verdict to the responsible crow as a nudge trigger. The crow's model decides how to proceed.
• Budget: each nudge counts against the nest's exchange budget. When the budget runs out, open expectations go to the owner as a summary instead of more nudges.
• Nudge loop guard [decided 2026-10-27]: three loops max. When a crow has received three nudges on one expectation with no new content or response data from it in between, the harness stops nudging and sends the open expectation to the owner in the summary. Three is a per-expectation constant in guardrails.go, counted by the harness, so the guard holds even if Jev keeps calling the expectation missed.

Initial checks (from testing): promise kept, rounds completed, turn order (debate only), single owner, claims sourced, correction handled once, role adherence, requester gets an answer.

7a. Classifier: validating orchestration [decided role, proposed mechanics]

Jev also scores the rationale behind orchestration decisions, so the COS and assistant don't pick crows or models on vibes. [decided]

• Which crow for which task: when the COS (or assistant) proposes a crow for a request, Jev scores the fit between the task's classification and the crow's persona, trust record for that task type and recent results.
• Which model a crow runs on: when a crow is spun up or reassigned, Jev scores the proposed model against the task type, using the flight log (cost, speed, approval and rejection rates per model). This ties into the planned model comparison (free model, Claude through a gateway, Claude direct).
• Low score: handled like any other miss. The harness hands the verdict back to the deciding crow (usually the COS) as a nudge to reconsider; the crow decides. [consistent with section 7]
• Every decision and its score are logged, so the owner can see why a crow or model was chosen.

8. Opt-in debate mode [decided opt-in, proposed shape]

Triggered only by the owner ("debate this," "have them argue"). The moderator posts a kickoff with the question, stances, a judge, rules (respond to specific points, concede when a point lands, demand evidence), a round count and the final-position format. The moderator opens each round, and the classifier enforces round completion and, if requested, turn order.

9. Budgets and guardrails [proposed]

• Each nest shows remaining exchanges and tokens to the owner and the moderator. Nothing is hidden.
• Wind-down is announced in the room, not just injected silently.
• Existing guardrails stay: crows in flight, tokens per item and per list, timeouts, fail-safe approvals, prank cooldowns.

10. Trust ladder in the chatroom [proposed]

• Trust is still earned per crow and per task type.
• Trust decides when a crow may speak unprompted (section 5) and what needs owner approval.
• A missed expectation is a nudge, not a penalty. [decided] Repeated misses never change trust directly. [decided 2026-10-27] The 3-loop guard already ends stalled work; its owner summary surfaces the pattern. Trust moves only on owner verdicts (approve/reject), so Jev can't silently demote a crow over a hard task.

11. What changes from today's prototype

Today	Chatroom
Sentry triages every item into solo / split / murder	Triage folds into dispatch (Jev classification, crows claim by class — solo/split first-claim-wins, conspiracy expects multiple claims); Sentry is reborn as the nest watchdog (section 6)
Fixed team sizes	Team shape comes from who's in the nest and who claims
Elder merges as a fixed step	Synthesis emerges, or the requester asks for it
Banter on scripted moments	All talk is in the nest; personas shape the voice
Human approves everything until trust is earned	Owner approves by trust level, plus ask_owner for decisions
Jev classifies triage only	Jev also scores expectations and validates orchestration choices (crow and model); the harness turns misses into nudges

Reusable as is: the Go server, SSE event stream, trust ledger, guardrails, personas, nests, flight log, and the UI art direction.

12. Build plan (RITE, one step at a time) [proposed]

1. One nest, owner plus two crows, event-driven. say, request, claim, deliver with @-addressing. Mock brain first.
2. The assistant crow as the owner's default chat, relaying into the nest.
3. The expectation ledger plus nudges for two checks first: promise kept and single owner.
4. The COS crow spinning up a crow on request. The Sentry watchdog beside it: the quarantine-then-escalate loop, on Jev verdicts and guardrail hits.
5. Opt-in debate mode.
6. Visible budgets in the UI.

Each step: show it, adjust, then the next.

13. Open questions

1. Names for the assistant and COS crows Answered [decided 2026-10-28]: Quill (assistant crow) and Boss (Chief of Staff crow).
2. Can Jev score custom expectation labels? Answered: yes, Jev takes custom questions (see JEV_STRATEGIES.md).
3. Should repeated misses ever affect trust? Answered [decided 2026-10-27]: no — misses stay nudges; the 3-loop guard surfaces patterns to the owner in its summary; trust moves only on owner verdicts (section 10).
4. Does the Sentry survive as a role, or fold into the COS? Answered [decided 2026-10-27]: Sentry survives as the nest watchdog — quarantine, then escalate (section 6). Triage folds into dispatch.
5. How does the message kind get tagged: the model's own header, the classifier, or both? Answered [decided 2026-10-27]: both, Jev first — Jev's tag above its band stands; the crow's header is the fallback; disagreements log (section 4 rules).
6. What data does Jev need to score model choice well (flight-log stats per model and task type, owner approvals), and how much history before its scores are trusted?