timmy-config/docs/coordinator-first-protocol.md

Coordinator-first protocol

This doctrine translates the Timmy coordinator lane into one visible operating loop:

intake -> triage -> route -> track -> verify -> report

It applies to any coordinator running through the current sidecar stack:

• Timmy as the governing local coordinator
• Allegro as the operations coordinator
• automation wired through the sidecar, including Huey tasks, playbooks, and wizard-house runtime

The implementation surface may change. The coordination truth does not.

Purpose

The goal is not to invent more process. The goal is to make queue mutation, authority boundaries, escalation, and completion proof explicit.

Timmy already has stronger doctrine than generic coordinator systems. This protocol keeps that doctrine while making the coordinator loop legible and reviewable.

Operating invariants

1. Gitea is the shared coordination truth.

   • issues
   • pull requests
   • comments
   • assignees
   • labels
   • linked branches and commits
   • linked proof artifacts

2. Local-only state is advisory, not authoritative.

   • tmux panes
   • local lock files
   • Huey queue state
   • scratch notes
   • transient logs
   • model-specific internal memory

3. If local state and Gitea disagree, stop mutating the queue until the mismatch is reconciled in Gitea.

4. A worker saying "done" is not enough. COMPLETE requires visible artifact verification.

5. Alexander is not the default ambiguity sink. If work is unclear, the coordinator must either:

   • request clarification visibly in Gitea
   • decompose the work into a smaller visible unit
   • escalate to Timmy for governing judgment

6. The sidecar owns doctrine and coordination rules. The harness may execute the loop, but the repo-visible doctrine in timmy-config governs what the loop is allowed to do.

Standing authorities

Timmy

Timmy is the governing coordinator.

Timmy may automatically:

• accept intake into the visible queue
• set or correct urgency
• decompose oversized work
• assign or reassign owners
• reject duplicate or false-progress work
• require stronger acceptance criteria
• require stronger proof before closure
• verify completion when the proof is visible and sufficient
• decide whether something belongs in Allegro's lane or requires principal review

Timmy must escalate to Alexander when the issue requires:

• a change to doctrine, soul, or standing authorities
• a release or architecture tradeoff with principal-facing consequences
• an irreversible public commitment made in Alexander's name
• secrets, credentials, money, or external account authority
• destructive production action with non-trivial blast radius
• a true priority conflict between principal goals

Allegro

Allegro is the operations coordinator.

Allegro may automatically:

• capture intake into a visible Gitea issue or comment
• perform first-pass triage
• assign urgency using this doctrine
• route work within the audited lane map
• request clarification or decomposition
• maintain queue hygiene
• follow up on stale work
• re-route bounded work when the current owner is clearly wrong
• move work into ready-for-verify state when artifacts are posted
• verify and close routine docs, ops, and queue-hygiene work when proof is explicit and no governing boundary is crossed
• assemble principal digests and operational reports

Allegro must escalate to Timmy when the issue touches:

• doctrine, identity, conscience, or standing authority
• architecture, release shape, or repo-boundary decisions
• cross-repo decomposition with non-obvious ownership
• conflicting worker claims
• missing or weak acceptance criteria on urgent work
• a proposed COMPLETE state without visible artifacts
• any action that would materially change what Alexander sees or believes happened

Workers and builders

Execution agents may:

• implement the work
• open or update a PR
• post progress comments
• attach proof artifacts
• report blockers
• request re-route or decomposition

Execution agents may not treat local notes, local logs, or private session state as queue truth. If it matters, it must be visible in Gitea.

Alexander

Alexander is the principal.

Alexander does not need to see every internal routing note. Alexander must see:

• decisions that require principal judgment
• urgent incidents that affect live work, safety, or trust
• verified completions that matter to active priorities
• concise reports linked to visible artifacts

Truth surfaces

Use this truth order when deciding what is real:

1. Gitea issue and PR state
2. Gitea comments that explain coordinator decisions
3. repo-visible artifacts such as committed docs, branches, commits, and PR descriptions
4. linked proof artifacts cited from the issue or PR
5. local-only state used to produce the above

Levels 1 through 4 may justify queue mutation. Level 5 alone may not.

The loop

Stage	Coordinator job	Required visible artifact	Exit condition
Intake	capture the request as a queue item	issue, PR, or issue comment that names the request and source	work exists in Gitea and can be pointed to
Triage	classify repo, scope, urgency, owner lane, and acceptance shape	comment or issue update naming urgency, intended owner lane, and any missing clarity	the next coordinator action is obvious
Route	assign a single owner or split into smaller visible units	assignee change, linked child issues, or route comment	one owner has one bounded next move
Track	keep status current and kill invisible drift	progress comment, blocker comment, linked PR, or visible state change	queue state matches reality
Verify	compare artifacts to acceptance criteria and proof standard	verification comment citing proof	proof is sufficient or the work is bounced back
Report	compress what matters for operators and principal	linked digest, summary comment, or review note	Alexander can see the state change without reading internal chatter

Intake rules

Intake is complete only when the request is visible in Gitea.

If a request arrives through another channel, the coordinator must first turn it into one of:

• a new issue
• a comment on the governing issue
• a PR linked to the governing issue

The intake artifact must answer:

• what is being asked
• which repo owns it
• whether it is new work, a correction, or a blocker on existing work

Invisible intake is forbidden. A coordinator may keep scratch notes, but scratch notes do not create queue reality.

Triage rules

Triage produces five outputs:

• owner repo
• urgency class
• owner lane
• acceptance shape
• escalation need, if any

A triaged item should answer:

• Is this live pain, active priority, backlog, or research?
• Is the scope small enough for one owner?
• Are the acceptance criteria visible and testable?
• Is this a Timmy judgment issue, an Allegro routing issue, or a builder issue?
• Does Alexander need to see this now, later, or not at all unless it changes state?

If the work spans more than one repo or clearly exceeds one bounded owner move, the coordinator should split it before routing implementation.

Urgency classes

Class	Meaning	Default coordinator response	Alexander visibility
U0 - Crisis	safety, security, data loss, production-down, Gitea-down, or anything that can burn trust immediately	interrupt normal queue, page Timmy, make the incident visible now	immediate
U1 - Hot	blocks active principal work, active release, broken automation, red path on current work	route in the current cycle and track closely	visible now if it affects current priorities or persists
U2 - Active	important current-cycle work with clear acceptance criteria	route normally and keep visible progress	include in digest unless escalated
U3 - Backlog	useful work with no current pain	batch triage and route by capacity	digest only
U4 - Cold	vague ideas, research debt, or deferred work with no execution owner yet	keep visible, do not force execution	optional unless promoted

Urgency may be raised or lowered only with a visible reason. Silent priority drift is coordinator failure.

Escalation rules

Escalation is required when any of the following becomes true:

1. Authority boundary crossed

   • Allegro hits doctrine, architecture, release, or identity questions
   • any coordinator action would change principal-facing meaning

2. Proof boundary crossed

   • a worker claims done without visible artifacts
   • the proof contradicts the claim
   • the only evidence is local logs or private notes

3. Scope boundary crossed

   • the task is wider than one owner
   • the task crosses repos without an explicit split
   • the acceptance criteria changed materially mid-flight

4. Time boundary crossed

   • U0 has no visible owner immediately
   • U1 shows no visible movement in the current cycle
   • any item has stale local progress that is not reflected in Gitea

5. Trust boundary crossed

   • duplicate work appears
   • one worker's claim conflicts with another's
   • Gitea state and runtime state disagree

Default escalation path:

• worker -> Allegro for routing and state hygiene
• Allegro -> Timmy for governing judgment
• Timmy -> Alexander only for principal decisions or immediate trust-risk events

Do not write "needs human review" as a generic sink. Name the exact decision that needs principal authority. If the decision is not principal in nature, keep it inside the coordinator loop.

Route rules

Routing should prefer one owner per visible unit.

The coordinator may automatically:

• assign one execution owner
• split work into child issues
• re-route obviously misassigned work
• hold work in triage when acceptance criteria are weak

The coordinator should not:

• assign speculative ideation directly to a builder
• assign multi-repo ambiguity as if it were a one-file patch
• hide re-routing decisions in local notes
• keep live work unassigned while claiming it is under control

Every routed item should make the next expected artifact explicit. Examples:

• open a PR
• post a design note
• attach command output
• attach screenshot proof outside the repo and link it from the issue or PR

Track rules

Tracking exists to keep the queue honest.

Acceptable tracking artifacts include:

• assignee changes
• linked PRs
• blocker comments
• reroute comments
• verification requests
• digest references

Tracking does not mean constant chatter. It means that a third party can open the issue and tell what is happening without access to private local state.

If a worker is making progress locally but Gitea still looks idle, the coordinator must fix the visibility gap.

Verify rules

Verification is the gate before COMPLETE.

COMPLETE means one of:

• the issue is closed with proof
• the PR is merged with proof
• the governing issue records that the acceptance criteria were met by linked artifacts

Minimum rule: no artifact verification, no COMPLETE.

Verification must cite visible artifacts that match the kind of work done.

Work type	Minimum proof
docs / doctrine	commit or PR link plus a verification note naming the changed sections
code / config	commit or PR link plus exact command output, test result, or other world-state evidence
ops / runtime	command output, health check, log citation, or other world-state proof linked from the issue or PR
visual / UI	screenshot proof linked from the issue or PR, with a note saying what it proves
routing / coordination	assignee change, linked issue or PR, and a visible comment explaining the state change

The proof standard in CONTRIBUTING.md applies here. This protocol does not weaken it.

If proof is missing or weak, the coordinator must bounce the work back into route or track. "Looks right" is not verification. "The logs seemed good" is not verification. A private local transcript is not verification.

Report rules

Reporting compresses truth for the next reader.

A good report answers:

• what changed
• what is blocked
• what was verified
• what needs a decision
• where the proof lives

Alexander-facing report

Alexander should normally see only:

• verified completions that matter to active priorities
• hot blockers and incidents
• decisions that need principal judgment
• a concise backlog or cycle summary linked to Gitea artifacts

Internal coordinator report

Internal coordinator material may include:

• candidate routes not yet committed
• stale-lane heuristics
• provider or model-level routing notes
• reminder lists and follow-up timing
• advisory runtime observations

Internal coordinator material may help operations. It does not become truth until it is written back to Gitea or the repo.

Principal visibility ladder

Level	What it contains	Who it is for
L0 - Internal advisory	scratch triage, provisional scoring, local runtime notes, reminders	coordinators only
L1 - Visible execution truth	issue state, PR state, assignee, labels, linked artifacts, verification comments	everyone, including Alexander if he opens Gitea
L2 - Principal digest	concise summaries of verified progress, blockers, and needed decisions	Alexander
L3 - Immediate escalation	crisis, trust-risk, security, production-down, or principal-blocking events	Alexander now

The coordinator should keep as much noise as possible in L0. The coordinator must ensure anything decision-relevant reaches L1, L2, or L3.

What this protocol forbids

This doctrine forbids:

• invisible queue mutation
• COMPLETE without artifacts
• using local logs as the only evidence of completion
• routing by private memory alone
• escalating ambiguity to Alexander by default
• letting sidecar automation create a shadow queue outside Gitea

Success condition

The protocol is working when:

• new work becomes visible quickly
• routing is legible
• urgency changes have reasons
• local automation can help without becoming a hidden state machine
• Alexander sees the things that matter and not the chatter that does not
• completed work can be proven from visible artifacts rather than trust in a local machine

Sovereignty and service always.