# Emdash Worktree Orchestrator

> Workflow

- Skill: `riteshkew/emdash-worktree-orchestrator` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add riteshkew/emdash-worktree-orchestrator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/riteshkew/emdash-worktree-orchestrator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: riteshkew (https://skillmd.com/u/riteshkew)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/riteshkew/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:

```bash
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:

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