Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion plugins/implementation/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "implementation",
"version": "0.23.1",
"version": "0.24.0",
"description": "Disciplined implementation stage: execute approved plans inline (`/implementation:implement`) or via orchestrated worker subagents (`/implementation:implement-dispatch`) with incremental validation, TDD-by-default cadence, green-checkpoint commits, scope-fence drift detection, and divergence detection that routes back to planning. Build/test/lint, testing, and outcome verification live in the companion `toolchain`, `testing`, and `verification` plugins, invoked when installed.",
"author": {
"name": "Melodic Software",
Expand Down
11 changes: 11 additions & 0 deletions plugins/implementation/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,17 @@
All notable changes to the `implementation` plugin are documented here. Format follows
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning.

## [0.24.0] - 2026-10-09

### Added

- **`/implementation:implement-dispatch` pilots one row before a wave wider than about 4.** It dispatches that row alone and confirms plan usage remains before sending the rest, because a usage limit hit mid-wave stops every worker at once. Eval 17 covers the pilot and the withheld rows. Evidence: 3 fleet lockouts on one lane, about 8 hours lost.
- **Both worker agents can use Monitor.** `implementer` and `scoped-implementer` list `Monitor` in `tools`, and the push-early brief clause tells a worker to wait on CI with `run_in_background` or Monitor, never a foreground `sleep` or `until` loop or `--watch`; both agents carry a drift record pointing at the Monitor section of the tools reference. Evidence: foreground CI waits cost about 41, 21-25 and 19 agent-hours a week on three fleet lanes.

### Changed

- **Worktree briefs anchor on the literal path, one plain command per call.** Brief item 8 and the cwd gotcha now require `git -C <literal path>` and forbid `VAR=` prefixes, loops, `$( )` and `cd` into the shared clone; the open "or a re-`cd` per call" is gone, and `cd <literal worktree path> && <command>` remains only for a command with no path or directory flag that reads its configuration from the working directory. Those shapes leave the permission fast path, where a headless worker is blocked. Evidence: 1,933, 670 and 270 such blocks on three fleet lanes.

## [0.23.1] - 2026-10-07

### Changed
Expand Down
14 changes: 12 additions & 2 deletions plugins/implementation/agents/implementer.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ description: "Scope-fenced implementation worker dispatched per phase by /implem
skills:
- implementation:report
- testing:test-value
tools: "Read, Edit, Write, Grep, Glob, Bash, PowerShell, WebFetch, WebSearch, Skill, Agent"
tools: "Read, Edit, Write, Grep, Glob, Bash, PowerShell, Monitor, WebFetch, WebSearch, Skill, Agent"
model: opus
effort: medium
---
Expand Down Expand Up @@ -38,7 +38,8 @@ guardrail; that absence alone is not a STOP.

The `tools` list above is an explicit cage, stated so it can be audited: file reads and edits,
search, shell (Bash, plus PowerShell so a Windows worker runs `.ps1` and pwsh-native commands
directly rather than launching pwsh through Bash), web research (so a consuming project's
directly rather than launching pwsh through Bash), Monitor (so a wait on CI or a long command runs
in the background, never as a foreground poll), web research (so a consuming project's
Comment thread
kyle-sexton marked this conversation as resolved.
Resolved
fresh-docs obligations stay satisfiable), skill invocation, and nested dispatch for skills that fan
out their own workers. Nothing else is granted.

Expand All @@ -52,6 +53,15 @@ PowerShell tool is unavailable, so one unresolved entry never blocks the launch.
- **Recheck trigger**: that section changes how unresolved entries are handled, or a launch with
`PowerShell` unresolved fails.

We grant `Monitor` so a wait on CI or a long command never holds a foreground turn. Where it is
unavailable, run the same wait with Bash `run_in_background`.

- **Pointer**: for what Monitor does and where it is unavailable, see
<https://code.claude.com/docs/en/tools-reference#monitor-tool>.
- **As of**: 2026-10-09
- **Recheck trigger**: that section changes what Monitor runs, how it reports back, or where it is
available.

The nested-dispatch grant is conditional: we treat `Agent` as absent at the spawn-depth limit,
whatever the `tools` list says, so a deeply chained dispatch fans out nothing; plan the brief's
work as your own.
Expand Down
14 changes: 12 additions & 2 deletions plugins/implementation/agents/scoped-implementer.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ description: "Scope-fenced implementation worker for a phase the plan's routing
skills:
- implementation:report
- testing:test-value
tools: "Read, Edit, Write, Grep, Glob, Bash, PowerShell, WebFetch, WebSearch, Skill, Agent"
tools: "Read, Edit, Write, Grep, Glob, Bash, PowerShell, Monitor, WebFetch, WebSearch, Skill, Agent"
model: sonnet
effort: medium
---
Expand Down Expand Up @@ -38,7 +38,8 @@ guardrail; that absence alone is not a STOP.

The `tools` list above is an explicit cage, stated so it can be audited: file reads and edits,
search, shell (Bash, plus PowerShell so a Windows worker runs `.ps1` and pwsh-native commands
directly rather than launching pwsh through Bash), web research (so a consuming project's
directly rather than launching pwsh through Bash), Monitor (so a wait on CI or a long command runs
in the background, never as a foreground poll), web research (so a consuming project's
fresh-docs obligations stay satisfiable), skill invocation, and nested dispatch for skills that fan
out their own workers. Nothing else is granted.

Expand All @@ -52,6 +53,15 @@ PowerShell tool is unavailable, so one unresolved entry never blocks the launch.
- **Recheck trigger**: that section changes how unresolved entries are handled, or a launch with
`PowerShell` unresolved fails.

We grant `Monitor` so a wait on CI or a long command never holds a foreground turn. Where it is
unavailable, run the same wait with Bash `run_in_background`.

- **Pointer**: for what Monitor does and where it is unavailable, see
<https://code.claude.com/docs/en/tools-reference#monitor-tool>.
- **As of**: 2026-10-09
- **Recheck trigger**: that section changes what Monitor runs, how it reports back, or where it is
available.

The nested-dispatch grant is conditional: we treat `Agent` as absent at the spawn-depth limit,
whatever the `tools` list says, so a deeply chained dispatch fans out nothing; plan the brief's
work as your own.
Expand Down
13 changes: 9 additions & 4 deletions plugins/implementation/skills/implement-dispatch/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ Structural variant of `/implementation:implement` for orchestrated execution: th

**Orchestration mode detection**. Infer autonomous vs interactive from the session shape: a goal/loop harness driving turns with no human in the cycle, a plan that declares itself autonomous-ready, or an explicit orchestration instruction means **autonomous**; a human reviewing each turn means **interactive**.

**Autonomous:** the main window is orchestrator only. Dispatch workers per phase; orchestrated cadence is the **default** even when the plan's routing is all-main-window (synthesize per-phase worker rows from the plan). A **wave** is a batch of one phase's worker rows dispatched together: each row is an independent brief with its own disjoint fence, waves never span phases (see Arguments), and a phase with more rows than the cap runs them as sequential waves. Cap each wave at 3–5 concurrent worker rows by default; `--wave-cap <N>` and the operator's `implement_dispatch_wave_cap` option override that (see Arguments). Rows that share a worktree are further limited by the one-writer rule (see Gates).
**Autonomous:** the main window is orchestrator only. Dispatch workers per phase; orchestrated cadence is the **default** even when the plan's routing is all-main-window (synthesize per-phase worker rows from the plan). A **wave** is a batch of one phase's worker rows dispatched together: each row is an independent brief with its own disjoint fence, waves never span phases (see Arguments), and a phase with more rows than the cap runs them as sequential waves. Cap each wave at 3–5 concurrent worker rows by default, and pilot one row before a wave wider than about 4 (see Dispatch cadence step 2); `--wave-cap <N>` and the operator's `implement_dispatch_wave_cap` option override that (see Arguments). Rows that share a worktree are further limited by the one-writer rule (see Gates).

**Interactive:** read the plan's execution-shape/routing table. Worker rows present (any surface other than main-window) → this skill's dispatch cadence for those phases. Routing table absent or all main-window → `/implementation:implement` classic inline cadence instead.

Expand Down Expand Up @@ -86,7 +86,7 @@ Because the orchestrator stays on the default branch, **every source-touching op
5. **The reason the phase exists**: the goal it serves and what the output enables.
6. Its **commit authority**: `worker` by default, or `orchestrator`. Commit authority below also says which of the clauses in items 8 to 10 change under `orchestrator`.
7. Any model routing the plan specifies.
8. **When the worker edits in a dedicated worktree** (an out-of-tree sibling or any checkout other than the session's default): that worktree's absolute path, plus the anchoring rule in the Gotchas bullet "A worker's worktree cwd does not persist across tool calls". The interactive default is a pre-existing worktree path the brief supplies.
8. **When the worker edits in a dedicated worktree** (an out-of-tree sibling or any checkout other than the session's default): that worktree's absolute path, written literally, plus the anchoring rule in the Gotchas bullet "A worker's worktree cwd does not persist across tool calls": `git -C <literal path>`, one plain command per call, and no `VAR=` prefixes, loops, `$( )` or `cd` into the shared clone. A command with no path or directory flag that reads its configuration from the working directory (a repository's own build, test or lint wrapper) runs as `cd <literal path> && <command>` in that one call. The interactive default is a pre-existing worktree path the brief supplies.
9. **When provisioning is worker-side** (the autonomous work-lane; see Commit authority): materializing that isolated worktree is the worker's **first step**. The orchestrator cannot itself invoke `/source-control:worktree create`, whose `EnterWorktree` terminal would transition the orchestrator's session. The worker invokes `/source-control:worktree` via the Skill tool for its non-entering creation seam when installed, or a plain `git worktree add` otherwise, and works in it under the item 8 anchoring, never entering it. The brief tells the worker, before its first edit, to fetch and confirm the new branch starts from the intended base (`git -C <path> merge-base HEAD <remote>/<default>` equals `<remote>/<default>`, where `<remote>` is the remote provisioning based the branch on, not always `origin`), and on a mismatch to STOP and report. Provisioning happens **once per item, on the first dispatched phase**: the worktree persists across the item's phases, so every **later** phase of the same item is handed that same worktree path and works in it. Never re-provision the already-checked-out item branch; both `git worktree add -b <name>` and attaching the branch fail while it is checked out in the persisted worktree. The first phase's brief also instructs the worker to bring the branch current with the default branch, commit, and push before returning, then **return the worktree's absolute path plus the branch name** so the orchestrator can open the PR against the pushed branch. A worker that cannot provision an isolated worktree STOPs and reports rather than editing the default checkout.
10. **The three CI-hygiene clauses, front-loaded**: the Gotchas bullets on issue-number comments, new shebang files and early push, the last two under `worker`.
11. **The phase's design excerpt**: the part of PLAN.md's `## Design` section the phase touches (its module layout, contracts, variation verdicts, and the conventions they cite), quoted verbatim, never paraphrased. The worker's worktree holds no memory slice, so the quote is the only copy of the design it sees. When the plan has no `## Design` section or the phase touches none of it, the brief says `Design: none`.
Expand Down Expand Up @@ -143,6 +143,11 @@ Because the orchestrator stays on the default branch, **every source-touching op
- **Recheck trigger**: a release note touches subagent model selection, the model-aliases
provider table changes, or the env-vars page adds a provider variable.

**Pilot a wide wave.** Before a wave wider than about 4 rows, dispatch one row alone, wait for
its return, and confirm plan usage remains (the return carries no usage-limit error, and any
usage reading the session has shows room for the rest) before dispatching the other rows. A
usage limit hit mid-wave stops every worker at once.
Comment thread
kyle-sexton marked this conversation as resolved.
Resolved

Dispatch a wave, up to the cap's worker rows from the current phase, and keep working while it
runs: verify returns from the same phase as they arrive, compose the next brief, and run the
build/test gate on accepted returns, except under commit authority `orchestrator` in a shared worktree, where the gate runs after the wave settles (see Concurrency). Rows in a shared worktree dispatch one per wave unless commit authority is `orchestrator` (see Gates). Intervene when
Expand Down Expand Up @@ -238,10 +243,10 @@ We treat the phases of one approved plan as one task, so the orchestrator's wind
- **Do not treat a worker's build report as the signal.** See Gates. Workers report synthesis; the main window invokes `/toolchain:check` via the Skill tool (or runs the project's own build when the `toolchain` plugin is absent) itself after every accepted return, except under commit authority `orchestrator` in a shared worktree, where the gate runs after the wave settles (see Concurrency)
- **A worker STOP is a divergence signal, not a failure.** Route it through `/implementation:implement`'s Step 3 severity ladder; revising the brief is the cheap fix, a plan review the escalation
- **Surface subagent results before ending the turn.** Results left unsurfaced at turn end are lost to the user
- **A worker's worktree cwd does not persist across tool calls.** Brief every dedicated-worktree worker to anchor every command, edits AND git status/add/commit/diff/log, with `git -C <worktree-path>` or a re-`cd` per call, never a one-time `cd`
- **A worker's worktree cwd does not persist across tool calls.** Brief every dedicated-worktree worker to anchor every command, edits AND git status/add/commit/diff/log, on the worktree's literal absolute path: `git -C <literal path>` for git, absolute paths for every other command, one plain command per call. No `VAR=` prefixes, loops, `$( )` or `cd` into the shared clone: a one-time `cd` does not persist, and those shapes leave the permission fast path, where a headless worker is blocked. The one exception is a command with no path or directory flag that reads its configuration from the working directory: it runs as `cd <literal worktree path> && <command>` in that same call, since absolute file paths alone would run it against the wrong checkout
- **No issue-number back-references in code comments.** Brief every worker that a comment citing an issue number (`# Issue #NNN ...`, `(issue #NNN obs #N)`) trips the `comment-hygiene` check; `TODO(#issue)` is the sanctioned exception
- **New shebang files need `chmod`, then `git add`, then `git update-index --chmod=+x`. In that order.** Brief every `worker`-authority worker (for `orchestrator`, see Commit authority): `chmod +x <path>`, then `git add <path>` (a not-yet-tracked file fails `git update-index --chmod=+x` outright. It can't override the index mode of a path that isn't staged yet), then `git update-index --chmod=+x <path>` to force the index mode explicitly (skip symlinks, staged `120000`, they fail the same command). A shebang file staged non-executable trips the `exec-bit` check
- **Push early, before the CI-poll tail. But never the PR.** Brief every `worker`-authority worker to commit and push as early as practical rather than deferring until its fix-and-verify loop is done, so a mid-session death never orphans unpushed work. This is a source-only checkpoint commit. The phase-boundary ritual (Step 4) still runs separately, orchestrator-side, once the phase's acceptance criteria are verified. PR creation stays out of every worker brief. It happens in the orchestrator's post-verification flow (`/implementation:implement` Step 5) after every return is verified and the build/test gate passes. The early push holds only before the pull request exists. Once it is open, every push starts a full CI run and cancels the one in flight, so brief a worker dispatched onto an open pull request (a later phase, a fix) to commit as it goes and push once, after its whole change set passes its checks. Commit authority `orchestrator` forgoes the early push: uncommitted work lives only on local disk until the orchestrator commits.
- **Push early, before waiting on CI. But never the PR.** Brief every `worker`-authority worker to commit and push as early as practical rather than deferring until its fix-and-verify loop is done, so a mid-session death never orphans unpushed work. This is a source-only checkpoint commit. The phase-boundary ritual (Step 4) still runs separately, orchestrator-side, once the phase's acceptance criteria are verified. PR creation stays out of every worker brief. It happens in the orchestrator's post-verification flow (`/implementation:implement` Step 5) after every return is verified and the build/test gate passes. The early push holds only before the pull request exists. Once it is open, every push starts a full CI run and cancels the one in flight, so brief a worker dispatched onto an open pull request (a later phase, a fix) to commit as it goes and push once, after its whole change set passes its checks. Commit authority `orchestrator` forgoes the early push: uncommitted work lives only on local disk until the orchestrator commits. A worker that waits on CI waits with `run_in_background` or Monitor, never a foreground `sleep` or `until` loop or `--watch`.
- **Shared worktrees follow the one-writer rule.** See Gates and Concurrency
- **Two well-formed fences can overlap unseen.** See Dispatch cadence item 1.1
- **Scope-fence drift applies to agent returns.** Every worker return is a decision boundary. Classify proposed follow-ups per `/implementation:implement` "Step 3.5: Scope-fence drift detector (run at every decision boundary)" before announcing them
Expand Down
12 changes: 12 additions & 0 deletions plugins/implementation/skills/implement-dispatch/evals/evals.json
Original file line number Diff line number Diff line change
Expand Up @@ -213,6 +213,18 @@
"It does NOT enable holdout tests on its own initiative",
"The brief's fence lists existing test files as FORBIDDEN"
]
},
{
"id": 17,
"name": "wide-wave-pilots-one-row-first",
"prompt": "/implementation:implement-dispatch phase-2 --wave-cap 5 — autonomous run, commit authority orchestrator in one assigned worktree. Phase 2 has five worker rows with disjoint fences. You dispatch the first row and it returns with a usage-limit error.",
"expected_output": "Because the wave is wider than about 4 rows, the orchestrator dispatches one row alone first rather than all five at once, waits for its return, and checks that plan usage remains before sending the other four. The pilot returned a usage-limit error, so it withholds the remaining four rows and reports the limit instead of dispatching them.",
"files": [],
"expectations": [
"Dispatches exactly one row first, not all five at once",
"Waits for the pilot's return and checks remaining plan usage before dispatching the other rows",
"Withholds the remaining four rows after the pilot returns a usage-limit error and reports it"
]
}
]
}
Loading