Most orchestration needs only role prompts, messages, and terminal reports. Coordination state helps when several roles must read or update one current machine-readable fact, such as a decision, owner, lock, vote, or verified checkpoint.
Ask for the behavior, not the schema
Section titled “Ask for the behavior, not the schema”For most workflows, an intent-level request is enough:
Orchestrate this feature. Keep discussion in role messages, but maintain one shared current value for the API decision and the verified integration checkpoint if several roles need them.
Or explicitly avoid the extra structure:
Keep this orchestration conversational. Add shared coordination state only if the lead identifies a fact that genuinely needs one authoritative value.
The provider decides whether the public coordination-state commands help. It defines keys and value shapes before asking roles to rely on them.
Choose the right channel
Section titled “Choose the right channel”| Channel | Best for |
|---|---|
| Agent message | Discussion, questions, answers, corrections, and negotiation |
| Group message | One shared instruction to several existing roles |
| Team report | A role’s final outcome, verification, failures, and uncertainty |
| Coordination state | One current machine-readable decision, owner, lock, vote, or checkpoint |
State should contain the current fact, not the conversation that produced it.
Shared decisions
Section titled “Shared decisions”Use a shared value when several roles must implement against the same choice:
Have the lead publish the chosen API contract as a versioned shared decision. Tell affected roles to read it before implementation and to escalate conflicts instead of overwriting it.
A useful value records the decision, owner, short reason, and relevant version or timestamp. Keep detailed discussion in agent sessions.
Ownership
Section titled “Ownership”Shared ownership state can help a large or changing team:
Publish one owner per shared component. Require roles to check ownership before changing an interface, and have the lead announce any reassignment to both owners.
For a small, stable team, ownership in the role prompts is simpler.
Competing updates
Section titled “Competing updates”Coordination state is versioned. The provider should use compare-and-set updates when several roles may write the same key. A version conflict means the value changed; the role must reconcile it instead of overwriting newer state.
Prompt this behavior when races are plausible:
Protect shared decisions from competing writes. Reconcile version conflicts through the lead and preserve the newer value until the conflict is resolved.
Watching a value allows a role to react to later changes. It does not grant authority to change it.
Advisory locks
Section titled “Advisory locks”Use a lock only when non-overlapping ownership cannot prevent concurrent work:
If two roles may edit the migration, coordinate access with one advisory lock and have the lead resolve contention.
The lock coordinates agents; it does not lock Git or the filesystem. Prefer clear ownership whenever possible.
Verified checkpoints
Section titled “Verified checkpoints”A shared checkpoint keeps later reviewers on the same result:
After integration, publish one verified checkpoint with the revision, verification performed, results, and unresolved risks. Start reviewers only after that checkpoint is ready.
This is especially useful for parallel review panels or comparisons across existing worktrees.
Independent assessments
Section titled “Independent assessments”Separate values preserve independent judgments:
Give each reviewer its own assessment entry. After all reviewers finish, have the lead resolve disagreements and publish the final decision separately.
One shared vote value can hide disagreement if later writers replace earlier ones.
Reports are different
Section titled “Reports are different”Every durable team-run role receives reporting instructions automatically. Its report records the role’s terminal result; coordination state records a current shared fact. Manually launched roles return results through their session output instead.
The lead must verify both reports and shared state before declaring completion. Neither is proof by itself.
Keep state proportionate
Section titled “Keep state proportionate”After a run, ask:
- Which facts truly needed one authoritative value?
- Did versioning prevent a real conflict?
- Did state duplicate role conversation or reports?
- Could the next workflow use less structure?
Remove stale advisory locks and avoid secrets or large transcripts. See CLI automation for exact keys, reads, writes, watches, and version checks.