Orchestration

Three run-paths

You have three ways to engage the cotton team, ordered by context-preservation:

A — cotton-orchestrate skill (default)

Invoke the cotton-orchestrate skill or say "orchestrator mode." This chat stays the conductor and keeps its full conversation memory while delegating heavy work to subagents. The root orchestrator runs inside the current thread. Best for most tasks.

B — Spawn cotton-orchestrator subagent

Use the Agent tool to launch cotton-orchestrator as an independent subagent with its own context window. Useful when you want full isolation or parallel team branches.

C — Headless cotton-goal

cotton-goal "<condition>" — goal mode. The team loops until the goal condition is provably true, then emits COTTON DONE: <condition> — <proof>. Requires COTTON GATE: PASS before it can close.

Subagents vs Agent Teams

Two delegation modes exist depending on whether work is sequential or genuinely parallel:

• Subagents (default) — the root spawns scouts for recon, experts for planning, bosses and workers for building, the tester for verification. Work flows sequentially through the hierarchy.
• Agent Teams — TeamCreate launches bosses as teammates with a shared task list. Used only for genuinely parallel cross-domain work (e.g., backend + frontend + devops simultaneously). Always clean up with TeamDelete. The root orchestrator is the only agent that calls TeamCreate.

The build flow

Every task follows the same ordered pipeline — scouts first, experts next, builders after, then the quality gate last:

The verify → audit gate

Nothing is done until cotton-boss-tester says so. It is always the last step in any flow. The order is fixed: write tests → run tests → audit → verdict.

Verdict lines to recognize in agent output:

TEST_RESULT: PASS (42 passed)
TEST_RESULT: FAIL (3 failed, 1 error)
AUDIT_RESULT: CLEAN
AUDIT_RESULT: ISSUES (1 critical, 2 high)
COTTON GATE: PASS — tests green, audit clean
COTTON GATE: FAIL — <blocker description>

On COTTON GATE: FAIL, the tester routes the blocking findings back to the owning boss via SendMessage. The loop continues until the gate is green.

Root status lines

In goal mode, the root orchestrator emits one status line per turn and a closing line when done:

COTTON STATUS: DONE — <evidence of goal met>
COTTON STATUS: NOT DONE — <what remains>
COTTON DONE: <condition> — <proof>

Goal mode

Goal mode is a deterministic loop: the team keeps running until a condition is provably satisfied. It is guarded by a Stop hook (~/.claude/hooks/cotton-goal-gate.py) that reads .claude/goal.json and blocks the conversation from ending until COTTON GATE: PASS has been issued.

Manage goals via the CLI:

cotton-goal "<condition string>"   # start
cotton-goal check                    # is goal met?
cotton-goal status                   # current goal
cotton-goal clear                    # remove goal

Key rules

• Bosses are restricted: Write / Edit trivial only.
• Scouts (Haiku) return JSON only — no prose.
• Experts return plans only — never code.
• Workers (Sonnet) do the actual typing.
• The tester is always last; it never signs off with open Critical/High findings.
• Teammates ≠ subagents. Bosses are teammates to the root; workers are subagents of bosses.