One goal: in the order pdd:decompose set, dispatch every task in TASKS.md, accept each against the
acceptance object of its own class, merge the accepted work back into the current working branch and close
its worktree, then dispatch the next batch.
It does not set the order, does not edit tasks, does not write tests or models, does not judge whether a
requirement is right, and does not do a quality review. It is the executor, not a second planner.
When to use
TASKS.md and its tasks/ directory exist, and the work is to execute the DAG they describe.
A layer of ready tasks must be dispatched in parallel and each result accepted before the next layer.
Routing: order, gates and task boundaries belong to pdd:decompose; requirement correctness belongs to
pdd:plan or the user; quality judgement belongs to pdd:review, and only when the user asks.
Without TASKS.md this skill has no input. Report that, and ask the user to run pdd:plan and
pdd:decompose first. A one-off small change is ordinary engineering work: it is not part of the PDD
process and must not borrow this skill's name to be improvised on the spot.
Judging whether a requirement is right or worth doing
pdd:plan, or the user
Quality judgement, adversarial review
pdd:review, and only when the user asks
merging accepted work into the working branch, with one commit per accepted task
this skill, §5
push, tag, deploy, version numbers
the user's explicit instruction
Preconditions
TASKS.md: the DAG (with classes and gates), the register, requirement traces, the wave table.
tasks/<id>-<slug>.md: each task self-sufficient.
PRD.md: the standard for behaviour and architecture.
The repo.
The contract it executes is read-only except through dated amendments; a contradiction found here stops the
run and returns to pdd:decompose, it is never patched in place.
Workflow
1. Load the contract and check only executability
This is not a re-review of the plan, only a check that it can run:
the DAG has no cycles, every node has a task file, and the register and the task files agree on Class,
Depends on and Owned files;
every gate's condition is decidable on the graph (who feeds it, whom it releases);
the ready set is computed from the set accepted by the dispatcher, not from what subagents
self-reported as successful.
If any of these fails: stop, report with evidence, hand back to pdd:decompose. Do not fill the gap
yourself, do not guess, do not edit the contract in place.
2. Shared work before dispatch (the dispatcher does it, not a subagent)
Worktrees, baselines and shared prerequisites are detailed in references/subagent-dispatch.md §1.
One worktree per subagent, each with its own build output directory (Rust's CARGO_TARGET_DIR): a shared
target lets one person's build pollute everyone's.
Record the working branch before the first worktree exists: git rev-parse --abbrev-ref HEAD, written
into the run ledger. Every merge targets that name (§5). A detached HEAD, or a checked-out branch that
changed mid-run, stops the run — merging into whatever HEAD happens to be at the time is how a batch
lands in the wrong branch, and afterwards no evidence distinguishes it from the right one.
An explicit dispatch baseline (hash list) per worktree. A dirty main tree is expressed as an overlay: no
commits, no stashing of the user's work, and every unaccepted sibling delta excluded.
manifest, lockfile, shared enum/type modules, the migration chain, registry/route table/plugin list,
shared fixtures, entry aliases: no single subagent can own these, so the dispatcher finishes them first
and declares them read-only.
3. Dispatch a whole layer
One delegate_task per ready layer. The brief's shape and its rationale are in
references/subagent-dispatch.md §2; the point is to give paths, never pasted text:
the worktree root, the baseline hash list, the isolated build output directory, the read-only integration
tree;
PRD.md, TASKS.md, the tasks/ directory and the path of its own task file — paths, not pasted
bodies. Pasting full text rewrites the contract at dispatch time, and once two copies drift the subagent
follows whichever it read last;
the path of references/subagent-charter.md, with the brief saying "work to it": compile only what
you changed, run only the tests related to your change plus your own acceptance tests, write only owned
files, follow the repo's naming conventions;
an opening report of one line from its task file (the purpose, for instance) as evidence that it opened
the right file; test -f every path before dispatch; record the task file's hash and compare it at
acceptance to prove it was not edited;
the exact list of files it may create, modify or delete, and nothing else;
prohibitions: editing the PRD or TASKS.md, touching a sibling task's files, weakening or deleting
existing tests, adding dependencies, running the full suite, building the whole workspace, commit, push;
stop conditions: the task cannot be satisfied, it contradicts already-merged code, an owned file is
missing → stop and report, leaving the contract untouched;
report format: the one its task file specifies.
Do not poll during the same period. End the turn after dispatch and handle completion notices in batch.
When the parallelism ceiling is below the ready set, dispatch in waves and say so.
Measurement tasks (wall-clock baselines, --record, performance budgets) run in a round of their own.
Their product is a median; sharing CPU with any other task measures the other task's load, and that number
later becomes the before. Re-recording a baseline has one more precondition: the suite must be green — run
the full suite once to confirm, then --record; if the script warns that the baseline records a red suite,
delete that baseline, fix the reds and record again, and never keep the red numbers as a reference point.
4. Accept by class
A subagent's report is not evidence. Acceptance reads its own class, and never applies another class's
criteria.
Class
Acceptance
What the dispatcher looks at
construction
the purpose is observable from the real entry point; delta ⊆ owned; the affected existing suites and the typecheck still green
trigger the real entry point itself; the suite summary and the typecheck count
verification A
the model exists; the property ran within budget; counterexamples are shrunk and pinned
trace, seed, minimal sequence, coverage reading
verification B
the baseline was frozen before the change; after the change the same command reruns and the output is bit-identical
both outputs and the comparison
verification C
the check is all green before the change and still green after; injecting one violation must turn it red
two passes plus one record of a deliberate red
migration
every retention-list item has evidence; source set → target set matches; the old path is removed or has an expiry condition
oracle output plus the structural comparison
removal
the raw output of the absence proof (zero references, compile passes, no node left in the dependency graph); the tests that die with it are deleted
the command output
Common principles:
delta ⊆ owned. Touching another file breaks the contract: send it back to the same owner. lockfile,
build products and caches are byproducts — record them and move on.
count > 0. Any "green" needs real executed volume; selecting zero cases and exiting 0 is not having
run, it is not green.
Existing oracles may not be weakened. If a task invalidates an existing assertion, it must update or
delete that assertion in the same task and list it; not listing it is a defect.
For a flaky red, measure the trigger rate first, do not just rerun. A property that goes red once every
few dozen runs is usually drawing a rare value class, not an environment problem. Sample 20k runs to
compute P(hitting the trigger set) × draws per case: a measured 0.055% per sample means about 1.4% per
25-draw run, and ten all-green runs at 1.4% have an 87% chance of merely not having drawn it — so "it
passed on the rerun" is not acceptance. Send it back to the same owner with the mechanism, the
counterexample and the command; acceptance requires N random seeds (≥20) all green plus the fixed seed
green, and the fix must narrow the value domain or pin the triggering value, not raise numRuns.
Rerun any "measured X" in a report yourself. A subagent will write a wrong measurement into a
deliverable's file header or comment — for instance, claiming fc.string({unit:'binary'}) produced 168 of
200 lone surrogate pairs when the true value is 0 (it counted valid pairs), with its tests all green.
Whenever a number from a report lands in code, docs or a baseline, the dispatcher reproduces it with the
same command; a mismatch goes back to the same owner (and the dispatcher does not edit that file itself).
A mutation experiment hands over byte-level restoration evidence. When a subagent temporarily edits a
sibling task's file to prove "the property goes red", require a sha256 before and after; at acceptance,
confirm once more with a behavioural probe (the family samples still satisfy the predicate, the entry
signature is unchanged). A temporary crossing of the boundary is acceptable; a silent one is not.
Naming and formatting follow the repo, not the agent. New code's naming must show the shadow of a
same-style module; the repo's formatter/linter runs only on the files that task changed, with no new
allow/disable suppressions. A task id, V2, tmp or new* in a name is a defect.
Execution scope stays inside the brief. A report showing the full suite, a whole-workspace build or
another flow's tests is out of bounds: reject that round's conclusions and have it rerun per
references/subagent-charter.md.
5. Merge back and close the worktree, per batch
A batch ends when every task in it is accepted or retained. Then, before the next batch opens, each
accepted delta is merged into the current working branch and its worktree is removed. Deferring the merge to
the end of the run is what produces two worktrees whose deltas can no longer both land: the later one was
built on a baseline the earlier one has already changed.
The target branch is the one recorded in §2, never re-read from HEAD. Merging into "whatever is
checked out now" lands a batch in the wrong place after the user switches branches, and the log looks
innocent. A branch change detected mid-run stops the run.
The dispatcher merges; subagents never do — no commit, no merge, no cherry-pick, no branch
(references/subagent-dispatch.md §1). Two mechanisms, chosen by the state of the main tree:
clean main tree → commit inside the worktree on pdd/<task-id>, then git merge --no-ff pdd/<task-id> into the working branch, so the ancestry and the attribution are real;
main tree carrying the user's uncommitted work (the usual case) → apply the delta as a patch, stage
only the delta's own paths (git add <path> per owned file) and commit on the working branch. No
stashing, no committing the user's files, no git add -A.
Before applying, re-verify the destination hashes. A path whose content changed since the baseline is newer
work: stop and report, never overwrite it. One commit per accepted task, the message naming the task id and
its class, so a later revert is attributable — a batch of three accepted tasks gives three commits in DAG
order. Conflicts are resolved explicitly by the dispatcher and recorded in the layer report; an unresolvable
conflict stops the run with the clause it contradicts.
Then verify in the main tree: that task's observation rerun there, plus the existing modules and suites
it affects, plus the typecheck leg. A green worktree proves nothing about the main tree, where a sibling's
accepted delta is now also present.
Then remove the worktree, in this order: git worktree remove <path> → git worktree prune →
git branch -D pdd/<task-id> → read git worktree list and confirm the path is gone. Removing before
verifying leaves nowhere to run the failing command; verifying without removing leaves a directory that
keeps a stale baseline alive and the next layer may reuse it by accident.
Exactly one case keeps a worktree: acceptance failed, or the merge could not be resolved. It stays with
its blocker attached, is named in the layer report, and is counted in §7. There is no third case, and "I
might still need it" is not one.
6. Next layer, until the DAG is exhausted
The DAG being exhausted ends the dispatching, not the run: §5's cleanup of the last batch and §7's closing
check come after it. TASKS.md sets the order; the dispatcher does not reorder — when the parallelism ceiling
forces waves, wave order still obeys the DAG's partial order.
A batch does not open while the previous batch's worktrees exist. The exception is a retained worktree
named in the layer report; its blocker is worked or escalated first, because a second batch built on a
baseline that excludes the first batch's merged deltas produces reports that are green and wrong.
Before every dispatch, reconcile the register's ids against the set "accepted ∪ in flight". In a graph
of a dozen or so tasks, a skipped mid-graph node raises no error: it may have no downstream, or its
downstream was released by another edge, so it surfaces only in the final wave. The reconciliation is one
set difference costing a second; the price of a miss is that the task's second-phase verdict is never
executed (the list is never emptied, the check is never created) while every report looks green.
The closing task's brief (the joint rerun of B/C) lists every check by name. That is the only mechanism
that catches "one C task was never dispatched": a missing script returns MODULE_NOT_FOUND rather than a
failing verdict, and it surfaces in the step where you ask for "all six checks green". A brief that says
"run all the checks" without the names has no such probe — the subagent runs only the ones it finds.
7. Close the run: no worktree left behind
The DAG being exhausted is not the end of the run; the worktree ledger being empty is.
git worktree list shows exactly the worktrees that existed before the run — normally one, the main
tree — plus any retained worktree named in a layer report, and nothing else. Paste the raw output.
git branch --list 'pdd/*' is empty. A leftover branch is a leftover worktree in another form, and it will
be picked up by the next run as if it were current.
git worktree prune has run, so no administrative entry survives a directory that was deleted by hand.
The count matches the ledger: one worktree created per dispatched task, one removed per accepted task, one
retained per blocked task. Two numbers that disagree mean a merge or a removal was skipped, and the task
it belonged to is now unmerged.
A run whose DAG is exhausted while git worktree list still lists three paths has not finished: its last
batch is unmerged, and every measurement taken in the main tree since is missing those deltas. Report the
paths and their tasks; do not clean up silently and do not call the run complete.
8. Report
Per layer: which tasks were dispatched, which were accepted, which commits landed on which branch, which
worktrees were removed, the gate states, any stops.
At the end: DAG completion, task counts and acceptance counts per class, unresolved items (each with its
command and raw output). Do not enter pdd:review on your own initiative, and do not commit, push, tag or
deploy.
Decision rules
Gate enforcement
The dispatcher only enforces gates; it does not re-judge whether a gate should exist:
model gate unmet (the construction tasks it covers are not all accepted) → do not dispatch A-class
verification.
guard gate unmet (the B-class baseline is not frozen, or the C-class check is not all green) → do not
dispatch migration or removal.
A migration task that wants to edit the check judging it → refuse, report, require a dated amendment.
A C check that is already violated on the day it lands starts in two phases. Phase one accepts "the
hit set equals the frozen violation list", not an empty set; the script must print "this is the violation
set failing to grow, not the rule being satisfied" in its verdict, or phase one will be read as green.
Emptying the baseline counts as editing a rule that judges you: the dispatcher does it after the
corresponding removal is accepted, item by item and reviewable, and neither the script nor the task may
do it.
A C check is a standing gate and turns red because of sibling tasks. It quantifies structure: any new
barrel export, new seam declaration or new spec file may push a check that was green yesterday into red.
That is not a regression, it is the rule being enforced — ask "who added what", and route the removal or
narrowing back to that owner; widening the baseline to fit the hit set is exactly the self-exemption
this rule forbids.
When a gate condition cannot be met, the only action is to stop and report. Do not "do it first and add the
check afterwards" — that is cancelling the gate.
When to stop (rather than adjust the plan)
the task file contradicts itself (two purposes, an owned file that is missing, a Class that does not
match its contents);
the acceptance the task declares is impossible on the real tree;
a gate condition cannot be met (no oracle, for instance, and no way to get one before building);
a red gate cannot be attributed (not a regression, not an overtake, not the baseline, not the
environment).
Stopping carries three things: the command and its raw output, the minimal counterexample, and which clause
of the contract it contradicts. Hand back to pdd:decompose to fix the contract, and let the user decide
whether to re-dispatch.
No plan edits mid-run: no re-cutting, no merging, no relaxing acceptance, no rewriting a clause because
"that is how it really is", no numeric exceptions. That is this skill's discipline and what separates it
from the previous version.
Repo gates
Layer boundaries run the agreed integration checks; subagents run only their own checks, never the full
suite.
typecheck is a separate leg. Test runners usually do not typecheck, so a green suite proves nothing
about types. Record the starting baseline (for instance npx tsc --noEmit 2>&1 | grep -c 'error TS') and
rerun it after every layer; the count may only fail to rise.
Attribute a red before rerunning. Reproduce the failure in isolation first, then decide whether it is a
regression, an overtake, the baseline, or an environment limit. When a subagent blames the environment,
the dispatcher reruns that command itself; a single command's difference decides which kind the amendment
records.
When an evidence artifact asserts equality with the live run, it is a constructive red. Regenerate it
with the repo's own script (for instance npm run evidence); never hand-edit the numbers. When the
generated value disagrees with the task's expectation, report and block — that is a discovery, not a
number to update.
Product tests do not read generated artifacts. The generator empties its output first, so tests run
before the artifact exists; the product test asserts the cause and the pack owns the result.
Pitfalls
The full catalogue is in references/pitfalls.md. The most recurrent:
Treating a subagent's self-report as acceptance. "Done" is neither an observable purpose nor proof
that the delta is inside owned.
Dispatching downstream with a gate unmet. "Do it first and add the check later" turns the gate into
decoration; an A-class model then describes code that is not settled, and a B-class baseline compares new
code with itself.
Editing the contract mid-run. Re-cutting a task, relaxing acceptance, adding a numeric exception —
each one means the later evidence no longer corresponds to the original plan.
Mistaking a byproduct for a contract breach, or a contract breach for a byproduct. A lockfile is the
former; touching a sibling's file is the latter.
Calling zero selected cases green. Green without executed volume is unfinished work, and dispatching
past it lets the defect surface two layers later.
Merging at the end of the run instead of at the end of the batch. The second worktree was opened on a
baseline the first one has since changed, so the two deltas cannot both land and the conflict is
unattributable — merge and remove per batch, in §5's order.
Leaving worktrees and pdd/* branches behind. A stale worktree keeps an old baseline alive, and the
next layer picks it up thinking it is current — the run is closed by git worktree list and
git branch --list 'pdd/*', not by the DAG being exhausted.
Verification
every layer was dispatched in the DAG's partial order; no task started before its dependencies were
accepted;
every register entry appears in "accepted or dispatched" (the dispatch ledger reconciles, no wave was
skipped);
every gate was checked before dispatch, and no A-class task or migration/removal bypassed one;
every task's delta stayed inside its own owned set, with byproducts recorded;
every task was accepted by its own class (construction triggered the real entry point, A has a trace,
B has a bit-for-bit comparison, C has a deliberate red, migration has a retention list, removal has an
absence proof);
existing tests were not weakened, skipped or deleted unless the task listed them in its own report;
after each merge the affected modules and suites were rerun in the main tree;
the typecheck error count did not rise above the baseline;
every accepted task's delta was merged into the working branch recorded in §2, one commit per task
naming its id and class, and no merge landed after the next batch had opened;
every merge was verified in the main tree before its worktree was removed, and every removed worktree's
directory and pdd/<task-id> branch are gone;
the closing check ran: git worktree list lists only the pre-existing worktrees plus retained ones
named in a layer report, git branch --list 'pdd/*' is empty, git worktree prune has run;
no push, tag, deploy or version change happened;
every stop carries its command, raw output and the contract clause it contradicts.
Cross-skill references name the sibling skill and the file separately:
skill_view("pdd:decompose", "references/task-construction.md"). Every sibling is registered under
this plugin's namespace, so the skill argument always carries the pdd: prefix and the path is
relative to that skill's own directory.
References
pdd:decompose/assets/TASK.md — the task file's shape; the brief is taken from it verbatim.
pdd:decompose/references/task-construction.md, task-verification.md, task-migration.md,
task-removal.md — each class's fields and acceptance objects.
pdd:decompose/references/testing-methodology.md — A/B budgets, seeds, shrinking and failure reading.
pdd:decompose/references/ownership-rules.md — one writer per file and the class boundaries; consult it
when judging whether a delta is out of bounds.
scripts/mutate_check.py — negative control: change one byte at an exactly-once anchor, run the check,
restore, rerun. Exit 0 means red after the perturbation, green after restoration and byte-identical;
1 means the check cannot see that error; 2 means the anchor is missing or ambiguous. Both C's "an injected
violation must go red" and B's "the baseline really bites" are executed with it, not described in prose.
references/subagent-charter.md — the subagent charter: the brief must carry its path; compile only what
you changed, run only related tests plus your own acceptance tests, follow the repo's naming conventions
(three levels of authority: configuration → neighbouring modules → language idiom), the action scope, the
report, the failure shape.
references/subagent-dispatch.md — the dispatch paradigm: worktree and baseline, a brief giving the
tasks/ directory instead of pasted text, acceptance by class, the full sequence of a layer,
anti-patterns.
references/pitfalls.md — the full catalogue.
references/browser-harness.md — when the observation is a screenshot, a computed style, font readiness
or an accessible name: configuration binding, parallel-build risk, font loading.
references/behaviour-preserving-refactor.md — the depth of a migration: baseline freezing, extraction
order, cross-module instanceof, runner contention, reaction to a frozen artifact.
1---2name: implement3description: "Use when a TASKS.md exists and its DAG must be executed."4version: 2.4.05author: Tsz Kin Lai (LaiTszKin), Hermes Agent6license: MIT7platforms: [linux, macos, windows]8metadata:9 source: https://skillmd.com/skills/uniterra-solutions/implement10 hermes:11 tags: [software-development, implementation, subagents, dispatch]12 related_skills: [plan, decompose, review, explain]13---1415# Executing a scheduled task DAG1617One goal: **in the order `pdd:decompose` set, dispatch every task in `TASKS.md`, accept each against the18acceptance object of its own class, merge the accepted work back into the current working branch and close19its worktree, then dispatch the next batch.**2021It does not set the order, does not edit tasks, does not write tests or models, does not judge whether a22requirement is right, and does not do a quality review. It is the executor, not a second planner.2324## When to use2526- `TASKS.md` and its `tasks/` directory exist, and the work is to execute the DAG they describe.27- A layer of ready tasks must be dispatched in parallel and each result accepted before the next layer.28- Routing: order, gates and task boundaries belong to `pdd:decompose`; requirement correctness belongs to29 `pdd:plan` or the user; quality judgement belongs to `pdd:review`, and only when the user asks.3031**Without `TASKS.md` this skill has no input.** Report that, and ask the user to run `pdd:plan` and32`pdd:decompose` first. A one-off small change is ordinary engineering work: it is not part of the PDD33process and must not borrow this skill's name to be improvised on the spot.3435### What this skill does not do3637| Thing | Belongs to |38| --- | --- |39| Deciding order, gates, task boundaries, owned files | `pdd:decompose` |40| Splitting tasks, merging tasks, changing dependency direction | `pdd:decompose` (via amendment) |41| Writing tests, models, baselines, constraint scripts | the verification task (A/B/C) |42| Judging whether a requirement is right or worth doing | `pdd:plan`, or the user |43| Quality judgement, adversarial review | `pdd:review`, and only when the user asks |44| merging accepted work into the working branch, with one commit per accepted task | this skill, §5 |45| push, tag, deploy, version numbers | the user's explicit instruction |4647## Preconditions4849- `TASKS.md`: the DAG (with classes and gates), the register, requirement traces, the wave table.50- `tasks/<id>-<slug>.md`: each task self-sufficient.51- `PRD.md`: the standard for behaviour and architecture.52- The repo.5354The contract it executes is read-only except through dated amendments; a contradiction found here stops the55run and returns to `pdd:decompose`, it is never patched in place.5657## Workflow5859### 1. Load the contract and check only executability6061This is not a re-review of the plan, only a check that it can run:6263- the DAG has no cycles, every node has a task file, and the register and the task files agree on `Class`,64 `Depends on` and `Owned files`;65- every gate's condition is decidable on the graph (who feeds it, whom it releases);66- the ready set is computed from the set **accepted by the dispatcher**, not from what subagents67 self-reported as successful.6869If any of these fails: stop, report with evidence, hand back to `pdd:decompose`. Do not fill the gap70yourself, do not guess, do not edit the contract in place.7172### 2. Shared work before dispatch (the dispatcher does it, not a subagent)7374Worktrees, baselines and shared prerequisites are detailed in `references/subagent-dispatch.md` §1.7576- One worktree per subagent, each with its own build output directory (Rust's `CARGO_TARGET_DIR`): a shared77 target lets one person's build pollute everyone's.78- **Record the working branch before the first worktree exists**: `git rev-parse --abbrev-ref HEAD`, written79 into the run ledger. Every merge targets that name (§5). A detached HEAD, or a checked-out branch that80 changed mid-run, stops the run — merging into whatever `HEAD` happens to be at the time is how a batch81 lands in the wrong branch, and afterwards no evidence distinguishes it from the right one.82- An explicit dispatch baseline (hash list) per worktree. A dirty main tree is expressed as an overlay: no83 commits, no stashing of the user's work, and every unaccepted sibling delta excluded.84- manifest, lockfile, shared enum/type modules, the migration chain, registry/route table/plugin list,85 shared fixtures, entry aliases: no single subagent can own these, so the dispatcher finishes them first86 and declares them read-only.8788### 3. Dispatch a whole layer8990One `delegate_task` per ready layer. The brief's shape and its rationale are in91`references/subagent-dispatch.md` §2; the point is to give paths, never pasted text:9293- the worktree root, the baseline hash list, the isolated build output directory, the read-only integration94 tree;95- `PRD.md`, `TASKS.md`, **the `tasks/` directory and the path of its own task file** — paths, not pasted96 bodies. Pasting full text rewrites the contract at dispatch time, and once two copies drift the subagent97 follows whichever it read last;98- **the path of `references/subagent-charter.md`**, with the brief saying "work to it": compile only what99 you changed, run only the tests related to your change plus your own acceptance tests, write only owned100 files, follow the repo's naming conventions;101- an opening report of one line from its task file (the purpose, for instance) as evidence that it opened102 the right file; `test -f` every path before dispatch; record the task file's hash and compare it at103 acceptance to prove it was not edited;104- the exact list of files it may create, modify or delete, and nothing else;105- prohibitions: editing the PRD or `TASKS.md`, touching a sibling task's files, weakening or deleting106 existing tests, adding dependencies, running the full suite, building the whole workspace, commit, push;107- stop conditions: the task cannot be satisfied, it contradicts already-merged code, an owned file is108 missing → stop and report, leaving the contract untouched;109- report format: the one its task file specifies.110111Do not poll during the same period. End the turn after dispatch and handle completion notices in batch.112When the parallelism ceiling is below the ready set, dispatch in waves and say so.113114**Measurement tasks (wall-clock baselines, `--record`, performance budgets) run in a round of their own.**115Their product is a median; sharing CPU with any other task measures the other task's load, and that number116later becomes the before. Re-recording a baseline has one more precondition: the suite must be green — run117the full suite once to confirm, then `--record`; if the script warns that the baseline records a red suite,118delete that baseline, fix the reds and record again, and never keep the red numbers as a reference point.119120### 4. Accept by class121122A subagent's report is not evidence. Acceptance reads its own class, and never applies another class's123criteria.124125| Class | Acceptance | What the dispatcher looks at |126| --- | --- | --- |127| **construction** | the purpose is observable from the real entry point; delta ⊆ owned; the affected existing suites and the typecheck still green | trigger the real entry point itself; the suite summary and the typecheck count |128| **verification A** | the model exists; the property ran within budget; counterexamples are shrunk and pinned | trace, seed, minimal sequence, coverage reading |129| **verification B** | the baseline was frozen **before** the change; after the change the same command reruns and the output is bit-identical | both outputs and the comparison |130| **verification C** | the check is all green before the change and still green after; injecting one violation must turn it red | two passes plus one record of a deliberate red |131| **migration** | every retention-list item has evidence; source set → target set matches; the old path is removed or has an expiry condition | oracle output plus the structural comparison |132| **removal** | the raw output of the absence proof (zero references, compile passes, no node left in the dependency graph); the tests that die with it are deleted | the command output |133134Common principles:135136- **delta ⊆ owned.** Touching another file breaks the contract: send it back to the same owner. lockfile,137 build products and caches are byproducts — record them and move on.138- **count > 0.** Any "green" needs real executed volume; selecting zero cases and exiting 0 is not having139 run, it is not green.140- **Existing oracles may not be weakened.** If a task invalidates an existing assertion, it must update or141 delete that assertion in the same task and list it; not listing it is a defect.142- **For a flaky red, measure the trigger rate first, do not just rerun.** A property that goes red once every143 few dozen runs is usually drawing a rare value class, not an environment problem. Sample 20k runs to144 compute P(hitting the trigger set) × draws per case: a measured 0.055% per sample means about 1.4% per145 25-draw run, and ten all-green runs at 1.4% have an 87% chance of merely not having drawn it — so "it146 passed on the rerun" is not acceptance. Send it back to the same owner with the mechanism, the147 counterexample and the command; acceptance requires **N random seeds (≥20) all green plus the fixed seed148 green**, and the fix must narrow the value domain or pin the triggering value, not raise `numRuns`.149- **Rerun any "measured X" in a report yourself.** A subagent will write a wrong measurement into a150 deliverable's file header or comment — for instance, claiming `fc.string({unit:'binary'})` produced 168 of151 200 lone surrogate pairs when the true value is 0 (it counted valid pairs), with its tests all green.152 Whenever a number from a report lands in code, docs or a baseline, the dispatcher reproduces it with the153 same command; a mismatch goes back to the same owner (and the dispatcher does not edit that file itself).154- **A mutation experiment hands over byte-level restoration evidence.** When a subagent temporarily edits a155 sibling task's file to prove "the property goes red", require a `sha256` before and after; at acceptance,156 confirm once more with a behavioural probe (the family samples still satisfy the predicate, the entry157 signature is unchanged). A temporary crossing of the boundary is acceptable; a silent one is not.158- **Naming and formatting follow the repo, not the agent.** New code's naming must show the shadow of a159 same-style module; the repo's formatter/linter runs only on the files that task changed, with no new160 `allow`/`disable` suppressions. A task id, `V2`, `tmp` or `new*` in a name is a defect.161- **Execution scope stays inside the brief.** A report showing the full suite, a whole-workspace build or162 another flow's tests is out of bounds: reject that round's conclusions and have it rerun per163 `references/subagent-charter.md`.164165### 5. Merge back and close the worktree, per batch166167A batch ends when every task in it is accepted or retained. Then, **before the next batch opens**, each168accepted delta is merged into the current working branch and its worktree is removed. Deferring the merge to169the end of the run is what produces two worktrees whose deltas can no longer both land: the later one was170built on a baseline the earlier one has already changed.171172**The target branch is the one recorded in §2, never re-read from `HEAD`.** Merging into "whatever is173checked out now" lands a batch in the wrong place after the user switches branches, and the log looks174innocent. A branch change detected mid-run stops the run.175176**The dispatcher merges; subagents never do** — no commit, no merge, no cherry-pick, no branch177(`references/subagent-dispatch.md` §1). Two mechanisms, chosen by the state of the main tree:178179- **clean main tree** → commit inside the worktree on `pdd/<task-id>`, then `git merge --no-ff180 pdd/<task-id>` into the working branch, so the ancestry and the attribution are real;181- **main tree carrying the user's uncommitted work** (the usual case) → apply the delta as a patch, stage182 only the delta's own paths (`git add <path>` per owned file) and commit on the working branch. No183 stashing, no committing the user's files, no `git add -A`.184185Before applying, re-verify the destination hashes. A path whose content changed since the baseline is newer186work: stop and report, never overwrite it. One commit per accepted task, the message naming the task id and187its class, so a later revert is attributable — a batch of three accepted tasks gives three commits in DAG188order. Conflicts are resolved explicitly by the dispatcher and recorded in the layer report; an unresolvable189conflict stops the run with the clause it contradicts.190191**Then verify in the main tree**: that task's observation rerun there, plus the existing modules and suites192it affects, plus the typecheck leg. A green worktree proves nothing about the main tree, where a sibling's193accepted delta is now also present.194195**Then remove the worktree, in this order**: `git worktree remove <path>` → `git worktree prune` →196`git branch -D pdd/<task-id>` → read `git worktree list` and confirm the path is gone. Removing before197verifying leaves nowhere to run the failing command; verifying without removing leaves a directory that198keeps a stale baseline alive and the next layer may reuse it by accident.199200**Exactly one case keeps a worktree**: acceptance failed, or the merge could not be resolved. It stays with201its blocker attached, is named in the layer report, and is counted in §7. There is no third case, and "I202might still need it" is not one.203204### 6. Next layer, until the DAG is exhausted205206The DAG being exhausted ends the dispatching, not the run: §5's cleanup of the last batch and §7's closing207check come after it. `TASKS.md` sets the order; the dispatcher does not reorder — when the parallelism ceiling208forces waves, wave order still obeys the DAG's partial order.209210**A batch does not open while the previous batch's worktrees exist.** The exception is a retained worktree211named in the layer report; its blocker is worked or escalated first, because a second batch built on a212baseline that excludes the first batch's merged deltas produces reports that are green and wrong.213214**Before every dispatch, reconcile the register's ids against the set "accepted ∪ in flight".** In a graph215of a dozen or so tasks, a skipped mid-graph node raises no error: it may have no downstream, or its216downstream was released by another edge, so it surfaces only in the final wave. The reconciliation is one217set difference costing a second; the price of a miss is that the task's second-phase verdict is never218executed (the list is never emptied, the check is never created) while every report looks green.219220**The closing task's brief (the joint rerun of B/C) lists every check by name.** That is the only mechanism221that catches "one C task was never dispatched": a missing script returns `MODULE_NOT_FOUND` rather than a222failing verdict, and it surfaces in the step where you ask for "all six checks green". A brief that says223"run all the checks" without the names has no such probe — the subagent runs only the ones it finds.224225### 7. Close the run: no worktree left behind226227The DAG being exhausted is not the end of the run; the worktree ledger being empty is.228229- `git worktree list` shows exactly the worktrees that existed **before** the run — normally one, the main230 tree — plus any retained worktree named in a layer report, and nothing else. Paste the raw output.231- `git branch --list 'pdd/*'` is empty. A leftover branch is a leftover worktree in another form, and it will232 be picked up by the next run as if it were current.233- `git worktree prune` has run, so no administrative entry survives a directory that was deleted by hand.234- The count matches the ledger: one worktree created per dispatched task, one removed per accepted task, one235 retained per blocked task. Two numbers that disagree mean a merge or a removal was skipped, and the task236 it belonged to is now unmerged.237238A run whose DAG is exhausted while `git worktree list` still lists three paths has not finished: its last239batch is unmerged, and every measurement taken in the main tree since is missing those deltas. Report the240paths and their tasks; do not clean up silently and do not call the run complete.241242### 8. Report243244Per layer: which tasks were dispatched, which were accepted, which commits landed on which branch, which245worktrees were removed, the gate states, any stops.246247At the end: DAG completion, task counts and acceptance counts per class, unresolved items (each with its248command and raw output). Do not enter `pdd:review` on your own initiative, and do not commit, push, tag or249deploy.250251## Decision rules252253### Gate enforcement254255The dispatcher only **enforces** gates; it does not re-judge whether a gate should exist:256257- **model gate** unmet (the construction tasks it covers are not all accepted) → do not dispatch A-class258 verification.259- **guard gate** unmet (the B-class baseline is not frozen, or the C-class check is not all green) → do not260 dispatch migration or removal.261- A migration task that wants to edit the check judging it → refuse, report, require a dated amendment.262- **A C check that is already violated on the day it lands starts in two phases.** Phase one accepts "the263 hit set equals the frozen violation list", not an empty set; the script must print "this is the violation264 set failing to grow, not the rule being satisfied" in its verdict, or phase one will be read as green.265 Emptying the baseline counts as **editing a rule that judges you**: the dispatcher does it after the266 corresponding removal is accepted, item by item and reviewable, and neither the script nor the task may267 do it.268- **A C check is a standing gate and turns red because of sibling tasks.** It quantifies structure: any new269 barrel export, new seam declaration or new spec file may push a check that was green yesterday into red.270 That is not a regression, it is the rule being enforced — ask "who added what", and route the removal or271 narrowing back to **that owner**; widening the baseline to fit the hit set is exactly the self-exemption272 this rule forbids.273274When a gate condition cannot be met, the only action is to stop and report. Do not "do it first and add the275check afterwards" — that is cancelling the gate.276277### When to stop (rather than adjust the plan)278279- the task file contradicts itself (two purposes, an owned file that is missing, a `Class` that does not280 match its contents);281- the acceptance the task declares is impossible on the real tree;282- a gate condition cannot be met (no oracle, for instance, and no way to get one before building);283- a red gate cannot be attributed (not a regression, not an overtake, not the baseline, not the284 environment).285286Stopping carries three things: the command and its raw output, the minimal counterexample, and which clause287of the contract it contradicts. Hand back to `pdd:decompose` to fix the contract, and let the user decide288whether to re-dispatch.289290**No plan edits mid-run**: no re-cutting, no merging, no relaxing acceptance, no rewriting a clause because291"that is how it really is", no numeric exceptions. That is this skill's discipline and what separates it292from the previous version.293294### Repo gates295296- Layer boundaries run the agreed integration checks; subagents run only their own checks, never the full297 suite.298- **typecheck is a separate leg.** Test runners usually do not typecheck, so a green suite proves nothing299 about types. Record the starting baseline (for instance `npx tsc --noEmit 2>&1 | grep -c 'error TS'`) and300 rerun it after every layer; the count may only fail to rise.301- **Attribute a red before rerunning.** Reproduce the failure in isolation first, then decide whether it is a302 regression, an overtake, the baseline, or an environment limit. When a subagent blames the environment,303 the dispatcher reruns that command itself; a single command's difference decides which kind the amendment304 records.305- **When an evidence artifact asserts equality with the live run, it is a constructive red.** Regenerate it306 with the repo's own script (for instance `npm run evidence`); never hand-edit the numbers. When the307 generated value disagrees with the task's expectation, report and block — that is a discovery, not a308 number to update.309- **Product tests do not read generated artifacts.** The generator empties its output first, so tests run310 before the artifact exists; the product test asserts the cause and the pack owns the result.311312## Pitfalls313314The full catalogue is in `references/pitfalls.md`. The most recurrent:315316- **Treating a subagent's self-report as acceptance.** "Done" is neither an observable purpose nor proof317 that the delta is inside owned.318- **Dispatching downstream with a gate unmet.** "Do it first and add the check later" turns the gate into319 decoration; an A-class model then describes code that is not settled, and a B-class baseline compares new320 code with itself.321- **Editing the contract mid-run.** Re-cutting a task, relaxing acceptance, adding a numeric exception —322 each one means the later evidence no longer corresponds to the original plan.323- **Mistaking a byproduct for a contract breach, or a contract breach for a byproduct.** A lockfile is the324 former; touching a sibling's file is the latter.325- **Calling zero selected cases green.** Green without executed volume is unfinished work, and dispatching326 past it lets the defect surface two layers later.327- **Merging at the end of the run instead of at the end of the batch.** The second worktree was opened on a328 baseline the first one has since changed, so the two deltas cannot both land and the conflict is329 unattributable — merge and remove per batch, in §5's order.330- **Leaving worktrees and `pdd/*` branches behind.** A stale worktree keeps an old baseline alive, and the331 next layer picks it up thinking it is current — the run is closed by `git worktree list` and332 `git branch --list 'pdd/*'`, not by the DAG being exhausted.333334## Verification335336- [ ] every layer was dispatched in the DAG's partial order; no task started before its dependencies were337 accepted;338- [ ] every register entry appears in "accepted or dispatched" (the dispatch ledger reconciles, no wave was339 skipped);340- [ ] every gate was checked before dispatch, and no A-class task or migration/removal bypassed one;341- [ ] every task's delta stayed inside its own owned set, with byproducts recorded;342- [ ] every task was accepted by its own class (construction triggered the real entry point, A has a trace,343 B has a bit-for-bit comparison, C has a deliberate red, migration has a retention list, removal has an344 absence proof);345- [ ] existing tests were not weakened, skipped or deleted unless the task listed them in its own report;346- [ ] after each merge the affected modules and suites were rerun in the main tree;347- [ ] the typecheck error count did not rise above the baseline;348- [ ] every accepted task's delta was merged into the working branch recorded in §2, one commit per task349 naming its id and class, and no merge landed after the next batch had opened;350- [ ] every merge was verified in the main tree before its worktree was removed, and every removed worktree's351 directory and `pdd/<task-id>` branch are gone;352- [ ] the closing check ran: `git worktree list` lists only the pre-existing worktrees plus retained ones353 named in a layer report, `git branch --list 'pdd/*'` is empty, `git worktree prune` has run;354- [ ] no push, tag, deploy or version change happened;355- [ ] every stop carries its command, raw output and the contract clause it contradicts.356357> Cross-skill references name the sibling skill and the file separately:358> `skill_view("pdd:decompose", "references/task-construction.md")`. Every sibling is registered under359> this plugin's namespace, so the skill argument always carries the `pdd:` prefix and the path is360> relative to that skill's own directory.361362## References363364- `pdd:decompose/assets/TASK.md` — the task file's shape; the brief is taken from it verbatim.365- `pdd:decompose/references/task-construction.md`, `task-verification.md`, `task-migration.md`,366 `task-removal.md` — each class's fields and acceptance objects.367- `pdd:decompose/references/testing-methodology.md` — A/B budgets, seeds, shrinking and failure reading.368- `pdd:decompose/references/ownership-rules.md` — one writer per file and the class boundaries; consult it369 when judging whether a delta is out of bounds.370- `scripts/mutate_check.py` — negative control: change one byte at an exactly-once anchor, run the check,371 restore, rerun. Exit 0 means red after the perturbation, green after restoration and byte-identical;372 1 means the check cannot see that error; 2 means the anchor is missing or ambiguous. Both C's "an injected373 violation must go red" and B's "the baseline really bites" are executed with it, not described in prose.374- `references/subagent-charter.md` — the subagent charter: the brief must carry its path; compile only what375 you changed, run only related tests plus your own acceptance tests, follow the repo's naming conventions376 (three levels of authority: configuration → neighbouring modules → language idiom), the action scope, the377 report, the failure shape.378- `references/subagent-dispatch.md` — the dispatch paradigm: worktree and baseline, a brief giving the379 `tasks/` directory instead of pasted text, acceptance by class, the full sequence of a layer,380 anti-patterns.381- `references/pitfalls.md` — the full catalogue.382- `references/browser-harness.md` — when the observation is a screenshot, a computed style, font readiness383 or an accessible name: configuration binding, parallel-build risk, font loading.384- `references/behaviour-preserving-refactor.md` — the depth of a migration: baseline freezing, extraction385 order, cross-module `instanceof`, runner contention, reaction to a frozen artifact.
Run npx get-skill add uniterra-solutions/implement in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Use when a TASKS.md exists and its DAG must be executed. It is listed under Coding & Dev Tools on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Capability flags: executes scripts. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free. This skill is licensed under MIT.
Uniterra-Solutions (@uniterra-solutions) published this skill. Their other Agent Skills are listed on their SkillMD profile.