Assign To Workforce

assign-to-workforce — fan out a converged plan's waves to parallel agents

The skill is named assign-to-workforce; the product/CLI it reads is the devague plan waves command. (The prior leg — turning a spec into a plan — is the sibling /spec-to-plan skill.)

assign-to-workforce takes a converged devague plan and fans out its dependency waves to parallel agents (subagents, teammate agents, or generalist agents) — one agent per task per wave — each working in an isolated git worktree. The main agent merges each completed worktree gated by TDD. The human owns exactly three gates: the exported spec, the implementation split plan, and the final PR.

The devague CLI is never orchestrated by devague itself — devague plan waves describes the dependency graph (#20); it does not spawn agents, manage worktrees, mark tasks done, or pick a backend. The fan-out is the operator's job — this skill and the main agent perform it.

How to run

The entry point is scripts/assign-to-workforce.sh. Invoke it from the repository whose plan you are implementing (plans persist under .devague/ in the current directory):

bash .claude/skills/assign-to-workforce/scripts/assign-to-workforce.sh split-plan [--plan <slug>] [--write]
bash .claude/skills/assign-to-workforce/scripts/assign-to-workforce.sh waves    [--plan <slug>] [--json]
bash .claude/skills/assign-to-workforce/scripts/assign-to-workforce.sh help

It resolves the CLI portably — an installed devague on PATH (the normal case), falling back to uv run devague when you are inside the devague checkout, else an install hint. The split-plan subcommand reads devague plan waves --json — the enriched payload (devague#53 t9) that carries every active task's summary, instruction, acceptance criteria, and covered targets keyed by task id — and renders the human-facing implementation split plan: task map (task id, wave, summary verbatim, whether an instruction is present, acceptance-criteria count), proposed per-task agent + model assignment, the go/no-go question, and — last — an End state section that is the verbatim output of devague plan deliverables (#70), degrading to a one-line hint on a devague too old to have the verb. Adding --write (issue #82) additionally persists that same content — plus an owner/model annotation table the script reads back on the next --write — to a durable file next to the exported plan-md; see The durable split artifact below. The waves subcommand forwards to devague plan waves verbatim.

Usage

The full flow

The flow has three human gates and one automated TDD merge loop.

Human gate 1 — the exported spec

The plan is seeded from a converged frame (devague plan new --frame <slug>). The human reviewed and approved the spec when it was exported by the /think skill. No re-approval needed here — the spec gate is already closed.

Human gate 2 — the implementation split plan

Before any task is assigned, the main agent presents the implementation split plan for human go/no-go. This is the only gate the human owns at the implementation stage (per task, the TDD gate is the main agent's).

The split plan contains:

1. Task map — every task id, its one-line summary (verbatim), whether it carries a working instruction, its acceptance-criteria count, and the wave it belongs to — all read straight from devague plan waves --json (no operator paraphrasing).
2. Per-task agent + model proposal — for each task: the proposed agent type (subagent / teammate / generalist), the proposed model (e.g. a cheaper/faster model for a well-scoped task), and the scope justification (why this task is safe to delegate).
3. Go/no-go question — explicit human decision: "Approve this split and assign the plan to the workforce, or edit it first?"
4. End state — the verbatim output of devague plan deliverables (#70): what the plan actually produces — confirmed after-state claims, terminal tasks with acceptance criteria, and surviving open items. Present this to the human alongside the go/no-go question, not just the task map — approving a fan-out without seeing the world it produces is the gap this closes. On a devague too old to have the verb, this degrades to a one-line hint naming the minimum version instead of failing the split plan.

The human may edit any row (agent type, model, scope) before approving. The plan is model-agnostic — devague does not pick a backend (#20).

Run split-plan to print the proposed table:

bash .claude/skills/assign-to-workforce/scripts/assign-to-workforce.sh split-plan

Do not proceed to fan-out until the human approves the split plan.

The durable split artifact (split-plan --write)

Unlike the exported spec (docs/specs/*.md) and the exported plan (docs/plans/*.md), the implementation split plan — gate 2 — survived only in conversation before issue #82. split-plan --write closes that gap with an artifact-only change (decision c25): the written file is the record; there is no plan-schema change and no new devague CLI verb, so devague plan waves/show/deliverables stay read-only exactly as before.

bash .claude/skills/assign-to-workforce/scripts/assign-to-workforce.sh split-plan --write

This writes (or overwrites) docs/plans/<created-date>-<slug>-split.md — the same date-prefix convention devague plan export uses for the plan-md it sits beside, derived from the plan's own created timestamp (via devague plan show --json) rather than today's date, so re-running the command is idempotent: it updates the same file in place instead of spawning a dated duplicate. The file carries:

1. The dependency waves and the full per-task content (summary, instruction, acceptance criteria, covered targets) for every wave — quoted verbatim from devague plan waves --json, organized under one ## Wave N heading per wave and one ### <task-id> — <summary> heading per task.
2. A Task assignments table (Task | Owner | Model) — the durable form of the human's per-task owner/model decision (#82 ask 2). The script reads this table back from any existing file at the same path before regenerating: a human's edited Owner/Model cell for a given task id survives the next --write, matched by task id, rather than being clobbered back to the sonnet default. Only edit this table (or add a new plan/task and re-run) — don't hand-edit the wave/task sections above it, since those are fully regenerated every run.
3. The same End state section as plain split-plan — the verbatim output of devague plan deliverables, nested under its own ## End state heading.

Present this file (or its stdout twin from plain split-plan) at the go/no-go either way; --write is for keeping a committed record of what was actually approved, not a replacement for the live review.

The waves --json payload — the single source for every brief

devague plan waves --json emits {"plan": "<slug>", "waves": [[...], ...], "tasks": {...}} — the ordered dependency-wave batches plus a top-level tasks object keyed by task id, each entry carrying that task's full working contract:

{
  "plan": "<slug>",
  "waves": [["t1"], ["t2", "t3"]],
  "tasks": {
    "t1": {
      "summary": "<task summary>",
      "instruction": "<verbatim instruction, or \"\" if none>",
      "acceptance_criteria": ["<criterion>", "..."],
      "covers": ["<c*/h* id>", "..."]
    }
  }
}

This one payload is enough to build a per-subagent brief with no external context — no need to also read devague plan show --json or the exported plan-md. split-plan reads it to render the task map above; the fan-out step below reads the same payload to build each task agent's brief. Quote summary, instruction, acceptance_criteria, and covers verbatim into every brief — never paraphrase them. (Documented identically in the sibling /spec-to-plan skill, since both skills consume the same payload — stay consistent if either changes.)

Fan-out — one agent per task per wave in isolated worktrees

Once the human approves, the main agent fans out each wave in order:

1. Create an isolated git worktree for each task in the current wave, inside this repo's own worktree root — .worktrees.<repo-name>, a sibling of the repo directory:

   repo_root=$(git rev-parse --show-toplevel)
   wt_root="$(dirname "$repo_root")/.worktrees.$(basename "$repo_root")"
   git worktree add "$wt_root/agent-<task-id>" -b agent/<task-id>

   Never use a bare ../worktrees/ or an in-repo path. The .worktrees.<repo-name> root is mandatory for three reasons:

   • Nobody else will delete it. A shared ../worktrees/ in a multi-repo parent directory looks like anyone's scratch space; a directory named after your repo is visibly owned, so another agent or human cleaning up their own worktrees won't sweep away a live fan-out mid-wave.
   • No cross-repo collision. Task ids restart at t1 in every repo and every plan, so ../worktrees/agent-t1 from two concurrent repos is the same path. Namespacing by repo name keeps concurrent fan-outs disjoint.
   • The repo working tree stays clean. An in-repo path (.worktrees/, .claude/worktrees/) puts N checkouts inside the tree you are about to commit and PR — git add -A sweeps them in and git clean -fdx destroys them. Outside the repo, neither can touch them.

2. Spawn a task agent inside that worktree (using the approved model from the split plan), with:

   • The task id, summary, working instruction, acceptance criteria, and covered targets as its brief — quoted verbatim from devague plan waves --json (see The waves --json payload above). No operator paraphrasing anywhere in this flow: the plan text is the contract the user confirmed, and a reworded brief silently drifts from it. If a task has no instruction (""), say so rather than inventing one.
   • Instruction to work test-first (TDD): write the failing test(s) that match the acceptance criteria before implementing.
   • Instruction to commit its work to the worktree branch.
   • Instruction to report, never file, any reasoning-degradation lapse it notices in its own work — a skipped check, an assumption standing in for a real measurement, an unverified grader, missing provenance, or another of the six LAPSE_CODES in devague/frame.py. The task agent names it in its transcript or final report; it never runs devague lapse itself, because it never runs any devague command inside its worktree (see the hard rule below). The main agent files the record (devague lapse "<what>" --code <code> --origin llm) the moment the task agent reports it — not deferred to closeout — since written late is written flattering.

3. Same-wave tasks run in parallel (within-wave tasks have no inter-task dependency; the dependency graph guarantees this). Same-file overlap surfaces as a merge conflict at reconcile time, not a live race — isolated worktrees prevent clobbering.

4. Wait for all tasks in the wave to complete before starting the next wave.

TDD-gated merge — main agent, no human per task

For each completed task worktree, the main agent:

1. Runs the task's tests before merge (on the main branch): baseline must pass (or the relevant tests must be absent — the task adds them).

2. Merges the worktree branch into the main branch:

   git merge --no-ff agent/<task-id>

3. Runs the task's tests after merge: they must pass. If they do not, the merge is reverted and the task agent is given the failure output to fix.

4. Removes the worktree once the merge is accepted:

   git worktree remove "$wt_root/agent-<task-id>"

   Remove only the worktrees this run created — never rm -rf the .worktrees.<repo-name> root itself, and never touch another repo's worktree root. A concurrent fan-out may be live inside it.

The human does not review individual task merges. Per-task acceptance is the main agent's responsibility — the TDD gate (tests pass before AND after merge) plus the task's acceptance criteria. This mirrors the non-authoritative working state pattern of the Human Review Loop (#17): per-task merge records are uncommitted working state; the authoritative human gate is the final PR.

Advance to the next wave only after all tasks in the current wave are merged and their tests pass.