# Executing Skill (Vanilla Reference) Run an approved implementation plan as parallel, wave-based subagent work inside an isolated worktree — then gate, review, and open the PR. > **Vanilla reference skill — adapt the placeholders to your project.** Everything in angle brackets (``, ``, ``, ``, ``) is a slot you fill in for your own repo, toolchain, and conventions. Nothing here is tied to a specific language, framework, or vendor. ## Purpose Turn a written plan into merged code without corrupting a shared checkout, without letting parallel agents overwrite each other, and without declaring "done" on work that merely compiles. The core moves are: isolate in a worktree, split the plan into file-disjoint waves, run each wave's tasks in parallel with strict single-task subagents, gate centrally between waves, and prove the result at runtime before you ship. ## Core principles ### 1. Run the plan as dependency-ordered waves of file-disjoint tasks - Read the plan and group its tasks into **waves**. A wave is a set of tasks that (a) do not depend on each other's output and (b) **touch disjoint sets of files**. - Order the waves by dependency: wave N+1 may rely on wave N's committed result, never the reverse. - Each task is executed by exactly **one** single-task subagent. If two tasks would edit the same file, they cannot share a wave — split them across waves or merge them into one task. ### 2. Never switch the branch in the shared/main checkout - Switching branches in the checkout that other agents are working in **corrupts sibling agents mid-task** — their working files change out from under them. - All work happens in an **isolated git worktree** created off ``. Create it once at the start: ```bash git worktree add -b ``` - **Address every operation with a worktree-scoped path.** Pass absolute paths rooted at `` to every subagent and every command. Never rely on an ambient "current directory" that another agent could change. ### 3. One task per subagent — and tell it so Each subagent gets a task brief that states, explicitly: - **Hard file boundaries.** "Only touch the listed files. Do not create, rename, or edit anything else." - **No side quests.** "Don't refactor unrelated code, add features, or 'improve' things outside the task scope." - **The inlined pattern outranks neighbouring code.** The task carries the exact shape (imports, structure, layering) to produce. If nearby code contradicts that pattern, the pattern wins — the subagent conforms to the brief, *not* to "whatever the surrounding file happens to do." This is deliberately counter to the usual "mimic what's already here" instinct. ### 4. Never run a whole-tree operation in a shared worktree - A repo-wide `reset`, `checkout .`, `add -A`, `stash`, or a **repo-wide formatter/linter run** will wipe or reformat **siblings' uncommitted work**. In a worktree where multiple tasks are in flight, these are destructive. - **Subagents lint only their own changed paths** — never the whole tree: ```bash ``` - The **authoritative gate runs centrally, between waves** — not inside individual subagents. Subagent-local linting is a courtesy pass; the real verdict comes from the central gate. ### 5. Launch a wave in parallel, then gate, then commit For each wave, in order: 1. **Launch all tasks of the wave together** (in parallel). Because the tasks are file-disjoint, they cannot collide. 2. **Wait for every task in the wave to finish.** Do not start the central gate while any task is still running. 3. **Run the central gate** at ``: ```bash # whole-worktree lint/format — safe now, nothing else is in flight # e.g. a compiler / type checker pass # unit + whatever runs fast ``` 4. **Run the new-test gate** (below). 5. **Commit the wave** as one coherent commit once the gate is green. 6. Move to the next wave. The gate runs **between** waves precisely because that is the only moment nothing else is writing to the worktree — a whole-tree format/lint is safe there and dangerous anywhere else. ### 6. A new-test gate every wave Subagents **bias toward adding tests** — often redundant, tautological, or asserting the mock instead of the behavior. - After each wave, **flag every net-new test** the wave introduced (diff the test files against the pre-wave state). - **Keep only tests that name a real production failure** — a test that would go red if a genuine bug were introduced into the code under test. - Delete scaffolding tests, mock-asserting tests, and "it renders" filler. A smaller suite that fails for real reasons beats a large suite that fails for none. ### 7. Compiling + unit-passing is NOT "done" Many real bugs **compile and pass unit tests** but break at runtime, integration, or deploy: a mis-wired dependency, a config that only bites in the container, a visual regression, a broken migration, a route that 500s. - Add an **integration / visual gate the agent cannot skip** before declaring the wave — or the whole plan — done. Examples, pick what fits ``: - Build and run the app the way it actually ships (container, bundle, binary) and hit the real entry point. - Exercise the changed flow end-to-end against a running instance, not a mock. - For UI, render the affected screens and compare against the expected visual state. - "It builds" is a precondition, not a finish line. The finish line is **observed correct behavior**. ### 8. Finish: review, then open the PR After all waves are committed and gated: 1. **Code-review pass.** Read the full diff as a reviewer would. **Fix findings in-PR** — small corrections land as additional commits on the feature branch, not as a new round of planning. 2. **Open the PR against ``.** Summarize what each wave delivered, link the plan, and note how the integration/visual gate was satisfied. ## Wave loop at a glance ``` create worktree off for each wave (dependency order): launch all file-disjoint tasks in parallel # one subagent per task wait for all tasks in the wave central gate: lint -> typecheck -> test # whole-worktree, safe between waves new-test gate: flag net-new tests, keep only real ones integration / visual gate (before "done") commit the wave code-review pass -> fix findings in-PR open PR against ``` ## Subagent task brief — template Give every single-task subagent a brief shaped like this: ``` Task: Worktree: # operate only here, via absolute paths Files you may modify (ONLY these): - - Pattern to match (this OUTRANKS surrounding code): Rules: - Touch ONLY the files listed. Do not create or edit anything else. - No side quests: no unrelated refactors, no extra features, no scope creep. - Never run a whole-tree git or formatter operation. Lint ONLY your changed files: - Do not stage or commit — the wave is committed centrally after the gate. - Report: what you changed, and anything the central gate should know. ``` ## Do not - **Do not switch branches in the shared/main checkout.** Create and use an isolated worktree; corrupting siblings mid-task is the default failure mode of skipping this. - **Do not run whole-tree ops** (`reset`, `checkout .`, `add -A`, `stash`, repo-wide format) inside a shared worktree while tasks are in flight — they wipe or reformat siblings' uncommitted work. - **Do not put two same-file tasks in one wave.** File-disjoint or different waves — no exceptions. - **Do not let subagents run the authoritative gate.** They lint only their own paths; the central gate between waves is the source of truth. - **Do not accept net-new tests unfiltered.** Every wave, keep only tests that name a real production failure. - **Do not declare "done" on compile + unit-pass.** Pass the integration / visual gate first. - **Do not defer review to "later."** Do the review pass and fix findings in-PR before opening — and open the PR against ``.