Emdash Worktree Orchestrator

Workflow

When this skill triggers, follow these steps in order.

Step 1 — Locate the agents JSON file

Check whether the user has specified an agents JSON file path.

• If a path is provided, confirm the file exists and is readable.
• If no path is provided, ask: "Please provide the path to your agents JSON file. It must contain repo, baseBranch, worktreeRoot, and an agents array of { id, task } objects. See examples/agents.json for a working example."
• If the user has no file ready, offer to generate one based on their described tasks before proceeding.

Step 2 — Verify the input shape

The engine validates these fields automatically, but confirm with the user that:

• repo — absolute or relative path to the git repository root.
• baseBranch — the branch each agent starts from (e.g. main).
• worktreeRoot — directory where worktrees will be created (e.g. /tmp/worktrees).
• agents — non-empty array; each entry must have a unique id (slug-safe) and a task description.

Duplicate agent ids will be rejected by the engine.

Step 3 — Run the engine

Execute the orchestration planner from the skill root:

node scripts/orchestrate.mjs <agentsFile>

The engine prints a Markdown plan to stdout with four sections:

• Setup — one git worktree add block per agent.
• Assignments — table mapping agent id → branch → worktree path → task.
• Teardown — git worktree remove + git branch -D per agent.
• Notes — reminders about parallel execution and sequential merging.

Capture stdout. If the process exits non-zero, surface the stderr message to the user and stop.

Step 4 — Present the plan

Show the full Markdown plan to the user. Remind them that:

• The plan is read-only output — nothing has been executed yet.
• They should review every setup command before running it.
• Agents should be started in parallel (e.g. using tmux, separate terminals, or a CI matrix).
• Merges back to baseBranch should be done sequentially to avoid conflicts.
• Teardown commands remove both the worktree directory and the local branch.

Example

See examples/input.md for a worked four-agent scenario and examples/output.md for the plan produced by the engine.

Run the example yourself:

cd skills/emdash-worktree-orchestrator
bash examples/run.sh