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

CHANGELOG.md

@@ -11,6 +11,71 @@ For each entry, **Upgrade impact** classifies the change against the [three-buck
 
 ## Unreleased
 
+### Every task goes through `/dispatch` in the main checkout
+
+([0020](docs/decisions/0020-every-task-through-dispatch.md), amending [0008](docs/decisions/0008-dispatcher-and-worker-worktrees.md) and [0015](docs/decisions/0015-tool-worktrees-are-workers.md))
+
+With the `parallel-agents` module, the session in the main checkout now takes every task, not only the
+ones whose worktree needs the project's setup. It hands each task to a new session in a worktree of
+its own, and that session runs the whole process. Before, developers chose each task's route and
+started the common route's session by hand. Now the project's settings in `worktree.conf` pick the
+route:
+
+- **When the project's worktrees need nothing from the scripts,** `/dispatch` takes Claude Code's
+  worktree. In the desktop app it offers a task chip carrying the worker prompt, which the developer
+  starts with one click. In a terminal it gives a `claude --worktree <slug> "<prompt>"` command.
+- **When they need a port, setup or start commands, or tasks start from another branch,** it takes
+  the scripts' worktree, created as before with `worktree-new.sh --no-start`, and gives its path and
+  the prompt to paste into a session opened on it.
+- **Never a chip for the scripts' worktree.** A chip always creates a worktree of its own, without the
+  env file, port, or setup, even when it's given another folder. `/dispatch` and
+  `PARALLEL-AGENTS.md` now say so.
+- **The developer can pick the other route for one task,** for example `/dispatch <task> chip` for a
+  copy change in a project whose worktrees run a server. The dispatcher never picks it on its own:
+  whether a task runs the app is its triage's question.
+
+The session-context hook tells the dispatcher to give every task to `/dispatch` and names its
+project's route. `protect-hub.sh`'s message points at `/dispatch`. A session started with the worktree
+option, without `/dispatch`, is still a worker.
+
+**Upgrade impact:**
+
+- **Overwrite** `.claude/skills/dispatch/SKILL.md` (module) and, in a committed project,
+  `.claude/hooks/session-context.sh`, `.claude/hooks/protect-hub.sh`, `.claude/hooks/README.md`, and
+  `.claude/skills/spec-workflow/SKILL.md`. A packaged project gets the hooks and `/spec-workflow` with
+  its next pin.
+- **Merge** `docs/PARALLEL-AGENTS.md`: its roles and routes sections changed, and your § Shared
+  services stays as it is.
+- Nothing to migrate. A project whose worktrees need the scripts now takes every task through them;
+  ask for a chip when a task won't run the app.
+
+### The plugin carries `/dispatch`
+
+([0020](docs/decisions/0020-every-task-through-dispatch.md), amending [0016](docs/decisions/0016-packaged-install.md))
+
+`/dispatch` was the one framework skill a packaged project still committed, because it ships in a
+module, and decision 0016 keeps modules committed. It's generic machinery like the 20 skills the
+plugin already carries, so the plugin now carries it too, as `/aplyca-adf:dispatch`.
+
+- **`scripts/build-aplyca-adf.sh`** copies every module's skills into the plugin. The module stays
+  their one source, so a committed install doesn't change.
+- **The skill stops in a project without the `parallel-agents` module,** so the plugin can carry it
+  for every project.
+- **`/aplyca-adf:adopt`** leaves the skill out of a packaged project. **`/aplyca-adf:upgrade`**
+  deletes a packaged project's committed copy when it's unchanged since the baseline.
+- The plugin's hooks and skills name it `/aplyca-adf:dispatch`, like every other skill they name.
+
+The module's scripts, `worktree.conf`, `.worktreeinclude`, and `PARALLEL-AGENTS.md` stay committed:
+they're the project's configuration, a doc it fills in, and scripts developers run from their own
+terminal.
+
+**Upgrade impact:**
+
+- **Packaged projects with the `parallel-agents` module:** delete `.claude/skills/dispatch/`, and type
+  `/aplyca-adf:dispatch`. `/aplyca-adf:upgrade` deletes it when it's unchanged since your baseline.
+  One your team edited stays under a name of its own, or goes upstream.
+- **Committed projects:** nothing changes.
+
 ## v1.2.1 — 2026-10-05 — Drift the prompt audit found
 
 A patch release: fixes to the framework's instruction files, with nothing new to adopt

CLAUDE.md

@@ -17,7 +17,7 @@ The repo slug is `AgenticDevelopmentFramework` (renamed from `ai-dev-starter-kit
   - `skeleton/specs/` — `README.md` (the process) and `_templates/{spec,plan,tasks}.md`
   - `skeleton/docs/` — constitution, spec model, process (PDRs), reference, tracker integration, and documentation templates
 - `modules/` — optional additions (`github/`, `git-hooks/`, `clickup/`, `parallel-agents/`); each has a `MODULE.md` and a `files/` tree mirroring the target repo
-- `plugins/aplyca-adf/` — the Claude Code plugin: the installer (`/aplyca-adf:adopt`, `:upgrade`, `:cost-report`, written by hand) and, for the packaged install (decisions 0016, 0017, 0019), the skeleton's skills, agents, workflows, hook scripts, and four reference docs — **generated** by `scripts/build-aplyca-adf.sh` into the paths its `.generated` file lists; never edit those by hand
+- `plugins/aplyca-adf/` — the Claude Code plugin: the installer (`/aplyca-adf:adopt`, `:upgrade`, `:cost-report`, written by hand) and, for the packaged install (decisions 0016, 0017, 0019, 0020), the skeleton's skills, agents, workflows, hook scripts, and four reference docs, and the modules' skills (`/dispatch`) — **generated** by `scripts/build-aplyca-adf.sh` into the paths its `.generated` file lists; never edit those by hand
 - `ADOPT.md` — the adoption procedure for AI agents, which the top of `README.md` points to; keep it in step with `/adopt`
 - `docs/` — framework guides (setup, upgrading, onboarding, catalogs, examples, scenarios) and `docs/decisions/` (why the framework works the way it does)
 - `evals/` — static checks, hook and module functional tests, dynamic fixtures
@@ -32,6 +32,6 @@ The repo slug is `AgenticDevelopmentFramework` (renamed from `ai-dev-starter-kit
 - No symlinks anywhere in the repository — the Claude Directory's checks reject them. A link a project needs (Antigravity's `.agents/skills`) is created by `/adopt`
 - Relative links inside `skeleton/` must resolve inside an adopting repo — never link to framework-only docs from the skeleton
 - Every change to `skeleton/` or `modules/` carries a `CHANGELOG.md` entry with its **Upgrade impact** (overwrite / merge / additive, plus migration steps when needed); significant design changes get a record in `docs/decisions/`
-- After any change under `skeleton/.claude/`, or to a reference doc the plugin carries (`COST-MODEL.md`, `MCP-INTEGRATION.md`, `MEMORY-STRATEGY.md`, `SPEC-MODEL.md` in `skeleton/docs/`), run `scripts/build-aplyca-adf.sh` and commit `plugins/aplyca-adf/` with it — the static checks fail on drift. The plugin's `"version"` changes only in a release (decision 0017)
+- After any change under `skeleton/.claude/`, to a module's skill (`modules/*/files/.claude/skills/`), or to a reference doc the plugin carries (`COST-MODEL.md`, `MCP-INTEGRATION.md`, `MEMORY-STRATEGY.md`, `SPEC-MODEL.md` in `skeleton/docs/`), run `scripts/build-aplyca-adf.sh` and commit `plugins/aplyca-adf/` with it — the static checks fail on drift. The plugin's `"version"` changes only in a release (decision 0017)
 - Run `./evals/run-evals.sh` before committing — structural checks plus functional tests of the hooks and module scripts; CI runs the same on every pull request
 - The repo is public — never include client, customer, or internal project names anywhere (files, examples, commit messages, PR descriptions); use the fictional newsletter feature from `docs/examples/` instead

README.md

@@ -333,7 +333,7 @@ flowchart TD
 | The requester needs an update on a task | `/stakeholder-update` ("update the client") — in the client's terms, shown in chat, posted on the pull request for the team to relay; on the tracker only on your yes to the exact text | `sonnet` | [Tracker integration](skeleton/docs/TRACKER-INTEGRATION.md) |
 | Passing work on — a teammate, another machine, a fresh session | `/handoff` — the state committed to the record first, then a short message of pointers to it | session model | [Skills catalog](docs/SKILLS-REFERENCE.md) |
 | A change to how the team works | `/record-decision` → a PDR in `docs/process/` | `sonnet` | — |
-| Several tasks at once | Each task in its own worktree (`parallel-agents` module): a new session with Claude Code's worktree option, or `/dispatch` from the main checkout when the worktree needs the project's setup | per task | [Parallel agents](docs/scenarios/parallel-agents.md) |
+| Several tasks at once | Each task in its own worktree (`parallel-agents` module): `/dispatch` in the main checkout hands every task to a new session — a one-click task chip in the desktop app, or a prompt to paste when the project's worktrees need its setup | per task | [Parallel agents](docs/scenarios/parallel-agents.md) |
 | High stakes or a broad sweep | `/deep-review`, `/deep-spec-analysis`, `/deep-context-audit`, `/deep-drift-sweep` | each agent its own | [Skills catalog](docs/SKILLS-REFERENCE.md) |
 
 ### Effort, model, and cost

docs/ONBOARDING.md

@@ -313,14 +313,18 @@ if there's no tracker task). Check for business language, verified claims, and y
 
 Each agent session gets its own git worktree — never two in one checkout. With the
 [`parallel-agents` module](../modules/parallel-agents/MODULE.md), the main checkout **only
-dispatches**. A task starts in a new session with Claude Code's worktree option (the desktop app's
-worktree toggle, or `claude --worktree`), or — when its worktree needs the project's setup, such as a
-port — `/dispatch` creates the worktree and branch and hands off a three-line prompt. The worker there
-does everything from triage on. The main checkout is shared — an edit or a dev server
-there collides with every other session — and analysis there is wasted: the dispatcher can't run the
-app or the tests, so the worker re-reads everything where it can verify it.
-([decisions 0008](decisions/0008-dispatcher-and-worker-worktrees.md) and
-[0015](decisions/0015-tool-worktrees-are-workers.md))
+dispatches**: every task goes to `/dispatch` there, which hands it to a new session in a worktree of
+its own. The project's settings pick the route. When its worktrees need nothing from the scripts,
+that's Claude Code's worktree: a task chip you start with one click in the desktop app, or a
+`claude --worktree` command. When they need the project's setup, such as a port, `/dispatch` creates
+the worktree with the scripts and gives you a three-line prompt to paste into a session opened on it.
+You can ask for the other route for one task. The worker there does everything from triage on. The
+main checkout is shared — an edit or a dev server there collides with every other session — and
+analysis there is wasted: the dispatcher can't run the app or the tests, so the worker re-reads
+everything where it can verify it.
+([decisions 0008](decisions/0008-dispatcher-and-worker-worktrees.md),
+[0015](decisions/0015-tool-worktrees-are-workers.md), and
+[0020](decisions/0020-every-task-through-dispatch.md))
 
 **Exercise (module installed):** dispatch the typo and the topics estimate. The main checkout's
 `git status` stays clean, each worker's session context says WORKER, and

docs/SETUP.md

@@ -174,9 +174,11 @@ Open the pull request as a draft; merge after review like any other change.
 ## Packaged install (Claude Code only)
 
 [Decision 0016](decisions/0016-packaged-install.md). The framework's machinery doesn't enter the
-repository: 20 skills, 8 agents, 4 workflows, the hook scripts, and the framework's reference docs
-([decision 0019](decisions/0019-reference-docs-in-the-plugin.md)) come from the `aplyca-adf` plugin,
-pinned to a release tag. The repository commits its own layer as above, and every module's files.
+repository: 20 skills, 8 agents, 4 workflows, the hook scripts, the framework's reference docs
+([decision 0019](decisions/0019-reference-docs-in-the-plugin.md)), and the `parallel-agents`
+module's `/dispatch` ([decision 0020](decisions/0020-every-task-through-dispatch.md)) come from the
+`aplyca-adf` plugin, pinned to a release tag. The repository commits its own layer as above, and
+every module's other files.
 Choose it when the team works in Claude Code only. Cursor, Copilot, and Gemini users would get
 `AGENTS.md` and the rules but no skills, and Claude Code's cloud sessions don't load the plugin.
 
@@ -189,8 +191,10 @@ v1.0.0 or later; its entry in [`CHANGELOG.md`](../CHANGELOG.md) says what it bri
 1. **Copy less** (step 1). Leave out `.claude/skills/`, `.claude/agents/`, `.claude/workflows/`, the
    scripts and helpers in `.claude/hooks/` (keep `config.sh`), `.claude/hooks/README.md`, `GEMINI.md`,
    `.agents/`, `.cursor/`, and the four reference docs: `docs/COST-MODEL.md`,
-   `docs/MCP-INTEGRATION.md`, `docs/MEMORY-STRATEGY.md`, and `docs/SPEC-MODEL.md`. Modules copy as usual: `/dispatch` is the one
-   skill a packaged repository commits. Then point the files that name the reference docs at the
+   `docs/MCP-INTEGRATION.md`, `docs/MEMORY-STRATEGY.md`, and `docs/SPEC-MODEL.md`. Modules copy as
+   usual, but leave out `.claude/skills/dispatch/` when the release's plugin carries it
+   (`plugins/aplyca-adf/skills/dispatch/` in the framework copy); an older release's plugin doesn't,
+   so copy it there. Then point the files that name the reference docs at the
    release you pin, from the framework copy you took the skeleton from:
    `python3 <framework>/scripts/link-reference-docs.py . --packaged v<X.Y.Z>`.
 2. **Wire the plugin, not the hooks** (step 5). Drop the `hooks` block from `.claude/settings.json`,

docs/SKILLS-REFERENCE.md

@@ -51,7 +51,7 @@ In order, for a change with something to decide. Commits: `spec:` → `docs:` 
 
 | Skill | Module | Purpose |
 |---|---|---|
-| `/dispatch` | `parallel-agents` | In the main checkout, for a task whose worktree needs the project's setup (a port, setup or start commands, a non-default base branch): name the task, create its worktree (`worktree-new.sh --no-start`), and hand off to a worker session with a three-line prompt. Other tasks start in Claude Code's own worktree. Reads only; no analysis, no edits. |
+| `/dispatch` | `parallel-agents` | In the main checkout, every task: name it and hand it to a new session in a worktree of its own, by the project's route — Claude Code's worktree through a task chip (desktop app) or a `claude --worktree` command, or, when the project's worktrees need a port, setup or start commands, or a non-default base branch, the scripts' worktree (`worktree-new.sh --no-start`) with a three-line prompt to paste. The developer can pick the other route for one task. Reads only; no analysis, no edits. A packaged install gets it from the plugin, as `/aplyca-adf:dispatch`. |
 
 ## Dynamic workflows
 

docs/UPGRADING.md

@@ -261,7 +261,9 @@ old plugin from each machine that installed it:
 
 A packaged project ([decision 0016](decisions/0016-packaged-install.md)) doesn't commit the skills,
 agents, workflows, hook scripts, or the framework's reference docs
-([decision 0019](decisions/0019-reference-docs-in-the-plugin.md)): they come from the `aplyca-adf`
+([decision 0019](decisions/0019-reference-docs-in-the-plugin.md)), nor the `parallel-agents`
+module's `/dispatch` once its pinned release's plugin carries it
+([decision 0020](decisions/0020-every-task-through-dispatch.md)): they come from the `aplyca-adf`
 plugin, pinned to a release tag in `.claude/settings.json`. Upgrading it means two things:
 
 - **Bump the pin:** the marketplace's `"ref"` moves to the new release tag, `vX.Y.Z`. That one line upgrades

docs/decisions/0008-dispatcher-and-worker-worktrees.md

@@ -1,6 +1,6 @@
 # 0008: The main checkout dispatches; worktrees do the work (optional module)
 
-- **Status:** accepted; amended by [0015](0015-tool-worktrees-are-workers.md) (Claude Code's own worktrees are workers too)
+- **Status:** accepted; amended by [0015](0015-tool-worktrees-are-workers.md) (Claude Code's own worktrees are workers too) and [0020](0020-every-task-through-dispatch.md) (every task goes through `/dispatch`)
 - **Date:** 2026-10-01
 
 ## Context

docs/decisions/0015-tool-worktrees-are-workers.md

@@ -1,6 +1,6 @@
 # 0015: Worktrees that Claude Code creates are workers too (parallel-agents module)
 
-- **Status:** accepted
+- **Status:** accepted; amended by [0020](0020-every-task-through-dispatch.md) (every task goes through `/dispatch`, and the project picks its route)
 - **Date:** 2026-10-02
 - **Amends:** [0008](0008-dispatcher-and-worker-worktrees.md) — how a task gets its worktree
 

docs/decisions/0016-packaged-install.md

@@ -1,6 +1,6 @@
 # 0016: A packaged install — the framework's machinery from its pinned plugin, `aplyca-adf` (opt-in, Claude Code only)
 
-- **Status:** accepted; amended by [0018](0018-packaged-by-default.md) (the packaged install is the default) and [0019](0019-reference-docs-in-the-plugin.md) (the reference docs come from the plugin)
+- **Status:** accepted; amended by [0018](0018-packaged-by-default.md) (the packaged install is the default), [0019](0019-reference-docs-in-the-plugin.md) (the reference docs come from the plugin), and [0020](0020-every-task-through-dispatch.md) (so does a module's skill, `/dispatch`)
 - **Date:** 2026-10-02
 - **Amends:** [0009](0009-optional-modules.md) — what ships as committed files