feat: every task through /dispatch, and the plugin carries it

[mauricios]

With the parallel-agents module, the session in the main checkout now takes every task and hands it to a new session in a worktree of its own. The plugin also carries /dispatch, so a packaged project no longer commits it. Decision 0020 amends 0008, 0015, and 0016.

What changed and why

1. Every task goes through /dispatch (6fc4cff)

Before, decision 0015 left the route to the developer. A task that needed nothing from the scripts started in a session the developer opened with the worktree option, and /dispatch handled only the scripts' route. A team using the module asked for one way in instead. Every requirement goes to the main checkout's session, which hands it to a new session, and that session runs the whole process.

• The project picks the route, not the task. The route comes from worktree.conf:
  • Worktrees that need nothing from the scripts get Claude Code's worktree: a task chip in the desktop app (one click), or a claude --worktree <slug> "<prompt>" command in a terminal.
  • Worktrees that need a port, setup or start commands, or a base branch other than the default get the scripts' worktree (--no-start), plus a prompt the developer pastes into a session opened on it.
• Why not per task: whether a task runs the app is a triage question, and a wrong chip costs a second dispatch. A wrong paste costs one step. The developer can still pick the other route for one task (/dispatch <task> chip). The dispatcher never does.
• Never a chip for the scripts' worktree. Another project tested this on 2026-09-22: a chip always creates its own worktree, without the env file, port, or setup, even when it's given another folder. A WorktreeCreate hook isn't told the folder or the task, and doesn't run when the app reuses a worktree. The decision, /dispatch, and PARALLEL-AGENTS.md record why.
• Hooks: the session-context hook tells the dispatcher to give every task to /dispatch and names the project's route. protect-hub.sh's message points at /dispatch.
• Docs: PARALLEL-AGENTS.md, MODULE.md, the scenario, ONBOARDING.md, SKILLS-REFERENCE.md, and README.md follow.

2. The plugin carries /dispatch (dfd6768)

/dispatch was the one framework skill a packaged project still committed, only because it ships in a module.

• The build: scripts/build-aplyca-adf.sh now copies every module's skills into the plugin. The module stays the single source, so a committed install doesn't change.
• Projects without the module: the skill stops there, as the plugin's hooks already do.
• Install and upgrade: /aplyca-adf:adopt leaves the skill out of a packaged project. /aplyca-adf:upgrade deletes a packaged project's copy when it's unchanged since the baseline.
• Names: the plugin's hooks and skills name the skill /aplyca-adf:dispatch.

Upgrade impact

The CHANGELOG has the details.

• Overwrite the /dispatch skill and, in a committed project, session-context.sh, protect-hub.sh, .claude/hooks/README.md, and /spec-workflow.
• Merge docs/PARALLEL-AGENTS.md, whose roles and routes sections changed. § Shared services stays.
• Packaged projects with the module: delete .claude/skills/dispatch/. /aplyca-adf:upgrade does it.

Release: this changes a workflow rule for module projects and has a migration step for packaged ones. Decision 0017 reads that as MAJOR, though v1.2.0 shipped an /upgrade-handled migration as MINOR. That's your call when we release.

How to verify

• ./evals/run-evals.sh
• scripts/build-aplyca-adf.sh leaves no drift.
• In a project with the module and no port: from the main checkout, /aplyca-adf:dispatch <a docs task> should offer a task chip. With PORT_SLOTS set, it should create the sibling worktree and give a prompt to paste.

What I verified

• Static evals: all suites pass (159, 83, 45, and 18). New assertions cover:
  • the dispatcher and route lines;
  • the chip rule and the guard in /dispatch;
  • the plugin carrying the skill.
• claude -p --worktree probe-one --model haiku "<prompt>" (Claude Code 2.1.286, a throwaway repo): the session ran in .claude/worktrees/probe-one, on branch worktree-probe-one, with the prompt. The interactive form parses the same way.
• check-packaged.sh's new check, run on throwaway projects:
  • It fails a packaged project that commits /dispatch on a release whose plugin has it.
  • It passes one that doesn't.
  • It's skipped on v1.2.1.
• The rebuilt plugin: it carries skills/dispatch with its copy-selection step (Step 0), and .generated lists it.

What I couldn't verify

• That a chip's worktree gets the env file through .worktreeinclude. The docs say every worktree the desktop app creates does, but checking a chip needs a click in the desktop app. It's the first thing to check on a real project.
• No session eval for /dispatch. The chip hand-off only exists in the desktop app.

🤖 Generated with Claude Code