Add swarm mode orchestration: worktree launcher, conflict detection, and status awareness

[sebastientaggart]

Problem to Fix

When multiple AI coding agents need to work on unrelated tasks simultaneously, there is no automated way to give each agent an isolated working environment, detect when agents are modifying the same files, or see which agents are active and what they are working on.

Why it Matters

Sequential discipline (one agent, one task at a time) works but limits throughput. As teams adopt multi-agent workflows, the lack of isolation and coordination tooling will cause merge conflicts, lost work, and confusion about what each agent is doing.

General Approach

Three additions, building on the foundations laid in issue #108:

1. Worktree launcher — Makefile targets (make swarm-start, swarm-list, swarm-clean) that create git worktrees as isolated working environments for concurrent agents. Each agent gets its own directory, branch, and temp files. Works automatically with Claude Code; other agents (Cursor, Codex, Gemini) get printed instructions for manual setup.

2. Conflict detection — An advisory check that compares files changed on the current branch against files changed in other open PRs. Warns but never blocks. Runs during /checkpoint and /submit-for-review.

3. Status swarm awareness — Enhance /status to show active worktrees alongside open PRs and issues, giving a unified view of all concurrent work.

Complexity

Verification / QA effort: significant
The worktree launcher requires testing across all four agent adapters. Conflict detection involves GitHub API queries that need performance testing with many open PRs. The full system requires end-to-end testing of the swarm workflow.

Acceptance Criteria

• make swarm-start name=<task> creates a git worktree with a feature branch and prints adapter-specific instructions
• make swarm-list shows all active worktrees with their branches
• make swarm-clean name=<task> removes a worktree cleanly
• .swarm/ directory is gitignored
• Conflict detection warns when the current branch modifies files also changed by other open PRs
• /status shows active worktrees when any exist
• All existing skills work correctly inside a worktree without modification

[sebastientaggart]

Moving to backlog as this greatly increases the complexity of this application (managing worktree support across agents), but worth tracking.

[sebastientaggart]

Design Review: From Swarm Orchestration to /delegate

The original problem

The original scope — worktree launcher, conflict detection, status awareness — was designed to make every agent a peer participant in multi-agent workflows. This required agent-agnostic isolation (worktrees across Claude, Gemini, Cursor, Codex), cross-agent conflict detection, and unified status tracking. That's why this was moved to backlog: it's a coordination problem with enormous surface area.

The reframe

The real question isn't "how do we orchestrate multi-agent work safely?" (an AI coordination problem). It's "how do we let a human operator safely run multiple agents on the same task?" (a tooling problem).

Key insight: the human operator is best positioned to decide when and how to parallelize work. They know which agents they have, which parts of the codebase are safe to split, and when the risk of conflicts is acceptable. CodeCannon doesn't need to infer any of that — it just needs to make delegation possible without breaking existing workflow invariants.

What we considered and discarded

1. Worktree launcher (make swarm-start/list/clean) — Dropped. Not all agents support worktrees equally. Managing worktrees across agent adapters is the primary source of complexity. If agents work on the same branch with scoped tasks, worktrees aren't needed.

2. Conflict detection — Dropped. If the operator scopes tasks to non-overlapping areas, conflicts don't arise. If they do overlap, the operator (or Claude as lead agent) resolves it. Putting detection in the delegated agent's prompt adds noise — it can't do anything useful with that information mid-task.

3. Status awareness / swarm tracking — Dropped. Without worktrees, there's no swarm state to track. The existing /status skill already shows branches and PRs.

4. Agent-as-orchestrator — Considered having Claude auto-decompose tasks and dispatch to other agents. Discarded because it burns tokens trying to infer what the human already knows, and the human will want to edit the delegation anyway.

5. /delegate cursor "task" frontend/ — Considered agent-specific targeting and mandatory scope constraints. Discarded both: the operator chooses which agent to paste into (no need to specify), and scope is often already implicit in the task description.

What survived: the /delegate skill

The model: Claude (or the primary agent) is the "lead developer" who owns the CodeCannon workflow (issues, branches, PRs, commits). Other agents are "contributors" who write code on the same branch under the lead's supervision.

Input: /delegate <task description> — natural language, may include scope hints.

Auto-pulled context: current branch name, linked issue number + body + agent implementation notes.

Output: A ready-to-paste prompt containing:

• The delegated task
• Branch name to check out
• Relevant issue context (so the other agent doesn't burn tokens re-reading the ticket)
• "Do not commit. Leave all changes unstaged."
• "Be surgical. Only modify what's necessary for the task."

The operator reviews the generated prompt, edits if needed, and pastes it into whatever agent they choose. No worktrees, no conflict detection, no agent-specific adapters.

Why a skill and not just "ask Claude to write a prompt"? It's a small checklist (branch name, issue context, no-commit rule, surgical constraint), but small checklists are exactly what people forget. The skill ensures these details are included every time without the operator having to remember them.

Commit and conflict policy

• Delegated agents never commit. All changes stay unstaged. The lead agent or human manages commits via /checkpoint or /submit-for-review. This preserves the existing workflow invariants entirely.
• Conflicts are the operator's responsibility. If two agents touched the same file, the operator resolves it (or asks the lead agent to). This is a conscious tradeoff: simplicity over automation.

---

Updated scope

Close the original scope (worktree launcher, conflict detection, status awareness). New task: create a /delegate skill as described above — a prompt generator that auto-pulls context and enforces the bare minimum rules for safe multi-agent contribution on a shared branch.

[sebastientaggart]

Resolution

The original swarm mode scope (worktree launcher, conflict detection, status awareness) was replaced with a much simpler approach after a design review. Instead of building multi-agent orchestration infrastructure, a new /delegate skill was added that generates ready-to-paste prompts for handing off parts of a task to other AI agents. The skill integrates into the existing /start planning step, letting the operator decide what to delegate before work begins, and automatically tells the lead agent to skip delegated work.

See #151 for full technical details.