Advanced Workflows

Playbooks for orchestrating multiple agents, recycling specs, and keeping worktrees lean

When orchestrating multiple agents you get the best results by laying a shared contract first, then letting specialists branch off in parallel. Think of it like traditional engineering: define the API surface and domain seams before frontend, backend, and data teams sprint ahead. The playbooks below help you sequence that work so sessions stay short-lived, merge conflicts stay rare, and every agent knows the rules of the codebase.

Scaffold → Swarm → Stabilize

The dashed bands illustrate how the scaffolding phase isolates concerns: first establish the orchestration layer (green) that defines the API contract, then set up infrastructure primitives such as repositories and parsers (blue). Once this skeleton is in place, feature-specific surfaces like the frontend (red) can be delegated to independent agents without tripping over one another.

1. Scaffold in the orchestrator

   Use a spec (often owned by the orchestrator session) to define project inputs/outputs and CLI affordances. Document how to run tests, builds, lint, and seed data; verify each command headlessly in the orchestrator terminals; and capture everything in an AGENTS.md so every future agent starts with the same contract.

2. Bootstrap the skeleton

   Launch an initial agent session to commit the scaffolding: repository layout, shared config, domain models, controller/service shells, and automation hooks. The goal is to make every downstream spec depend on clear interfaces instead of volatile files.

3. Swarm on features

   Break work into focused specs (for example, “Billing webhook handler”, “Settings sidebar UI”, “Analytics ingestion job”) and run agents in parallel. Because the skeleton already expresses the shared contracts, each session can focus on its slice without churn in upstream files.

4. Stabilize and integrate

   Use the second terminal pane for tests and linting, review diffs, and mark sessions reviewed. Merge with ⌘⇧M or open a PR once everything is green. Short-lived worktrees keep disk usage in check and allow rapid iteration.

5. Recycle unfinished ideas

   If a concept needs more thought, convert the session back into a spec (⌘S). The session worktree and branch are deleted (uncommitted changes vanish), but the spec (and notes) returns to the backlog for another attempt—ready to relaunch with new context.

As soon as the skeleton lands, branch from that commit (whether it lives on main or a feature branch) and launch agents for each missing capability. Every session owns its worktree, so it can install dependencies, run tests, and iterate on its feature without stepping on the others. Once a slice is green and reviewed, merge it back, recycle any unfinished specs, and keep the swarm moving.

Integrate, Review, Repeat

After each agent session delivers a passing feature—unit tests green, manual QA satisfied, review notes resolved—choose the merge strategy that fits your flow:

• Pull request (⌘⇧P) for collaborative review, or
• Direct merge (⌘⇧M) when you want to squash the worktree back into the skeleton branch yourself.

Resolving conflicts centrally keeps history clean: pull the branch into the orchestrator (or the original skeleton branch), fix any mismatches there, then mark the session reviewed and integrated. Work through the Reviewed column until it’s empty; each completion frees disk space because the session’s worktree can be cancelled.

Need hands-on edits? Press Open (⌘⇧O) on the session card, jump to your preferred IDE, and patch the worktree manually—agents and humans can collaborate on the same isolated branch. If a feature proves too complex, convert it back into a spec (⌘S) so you can revisit later without carrying half-finished code.

Once the integrations land, inspect the product and backlog. Any new bugs, refactors, or missing tests go straight into fresh specs so you can swarm again—treating the agents like a full squad of engineers you direct through specs, reviews, and tests to hit the exact quality bar you expect.

Continuous Maintenance Loop

After integrating the first wave of feature sessions into main, you can immediately branch new maintenance specs for bug fixes, regression tests, or refactors—keeping the cycle moving without bloating a single worktree.

1. Collect fixes as specs

   Log production bugs, refactors, and TODOs as lightweight specs so they remain ready-to-run cards in the backlog.

2. Launch focused agents

   Start one session per fix (e.g., “Resolve UTF-8 parsing bug”, “Tighten PDF export pipeline”, “Rename legacy API module”).

3. Validate locally

   Reproduce issues, run targeted tests in the second terminal, and annotate findings directly in the spec or session notes.

4. Review, merge, recycle

   Approve the diff, mark the session reviewed, then merge or open a PR. Convert anything unresolved back into specs to revisit later.

Parallel Development Tips

1. Create multiple sessions

   Spin up separate sessions for each initiative (e.g., ⌘N → “Add authentication”, ⌘N → “Fix checkout bug”, ⌘N → “Refactor database layer”).

2. Switch deliberately

   Use ⌘1-9 to jump between sessions or ⌘↑/↓ to cycle within the current filter.

3. Monitor all at once

   Each agent runs inside its own worktree, so you can review diffs and test results independently without conflicts.

Spec Management Patterns

1. Draft with intent

   Use ⌘⇧N to capture requirements, architecture decisions, and acceptance criteria before launching a session.

2. Refine centrally

   Iterate on specs in the orchestrator, and document expectations in AGENTS.md or the spec itself.

3. Convert, reset, repeat

   Start sessions with ⌘N, and whenever results miss the mark, press ⌘S to discard the worktree while keeping the spec for another run.

4. Capture insights when agents stall

   If an agent uncovers new requirements or research but can’t finish the implementation, ask it (via MCP) to open a fresh spec populated with the new context—or have it emit a markdown summary you paste into a spec yourself. Restarting from a clean spec keeps the knowledge while giving the next agent a deterministic starting point.