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
9 changes: 9 additions & 0 deletions docs/PLUGIN-PHILOSOPHY.md
Original file line number Diff line number Diff line change
Expand Up @@ -569,6 +569,15 @@ the session default model changes):
| Mechanical prep, one tier down | Sonnet 5 |
| Bulk mechanical sweeps | Haiku 4.5 |

The **dispatch-seam** tier enforcement is structural at two binding sites:
`plugins/implementation/agents/implementer.md` and
`plugins/implementation/agents/phase-verifier.md` (both bind the loop-lane convention's strong-tier
current alias; raise the pair together, and note frontmatter binds a floor — the session-relative
raise above it stays a per-invocation override at the dispatch site). That pair is the seam, not the
recheck list: the trigger above re-audits **every** agent-frontmatter `model` value in this
repository, which `git grep -n '^model:' -- 'plugins/*/agents/*.md'` enumerates rather than any
list restated here.

### Effort tiers

Effort routes per lane the way model does. Skill and subagent frontmatter `effort` overrides the
Expand Down
2 changes: 1 addition & 1 deletion plugins/implementation/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
"name": "implementation",
"version": "0.9.2",
"version": "0.10.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
39 changes: 39 additions & 0 deletions plugins/implementation/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,45 @@
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.10.0]

### Added

- **Structural capability-tier model bindings at the dispatch seam (`#1649`).** Two new plugin
agents, `implementer` and `phase-verifier`, carry an explicit `model` frontmatter binding of the
strong capability tier's current alias, replacing the default `inherit` that let a fast
orchestrator root silently run implementers (and their verifiers) at orchestrator strength.
`implement-dispatch`'s cadence now dispatches workers as `implementation:implementer` (step 2)
and the phase-boundary verifier as `implementation:phase-verifier`, reserving the per-invocation
`model` parameter for upward (frontier-tier) routing only, with a gotcha documenting that a set
`CLAUDE_CODE_SUBAGENT_MODEL` (any value but `inherit`) outranks the binding. Tier definitions
stay order-defined and family-agnostic per the marketplace's loop-lane convention §3 — the alias
binding lives only at this seam, and the verifier binds never weaker than the implementer it
checks. Frontmatter binds a floor, not a session-relative value, so both the cadence and the
agent bodies record the upward-only override duty when the session's model resolves above the
binding (per the plugin philosophy's session-relative ladder). Each agent also declares an
explicit tool cage — a change from the previously ungoverned generic-subagent tool surface: the
implementer grants file edit, search, shell, web research, skill invocation, and nested dispatch
(that last one conditional — the harness withholds `Agent` from a subagent at the spawn-depth
limit whatever the `tools` list says); the phase-verifier bars Edit/Write and agent spawning, with
Bash retained for inspection (stated as the cage it is, not as "read-only", per the plugin
philosophy's named-agent bar). Both also bind `effort` rather than inheriting the session's level,
matching this marketplace's other named agents — a model binding alone would still let an
orchestrator that lowered effort for its own bookkeeping lower it for the phase work. Neither
agent sets `maxTurns`, unlike every `discovery` and `review` agent in this marketplace (all of
which cap, between 25 and 40). The documented semantics are that the
field is the "maximum number of agentic turns before the subagent stops"; *applied inference,* not
a documented claim: a stop is not a failure signal, so the return an orchestrator receives from a
capped verifier that outran its budget is a truncated report shaped exactly like a verdict. The
phase-verifier is therefore contracted to return INCONCLUSIVE rather than a partial PASS, and
`implement-dispatch`'s phase-boundary clause makes that return re-dispatch a fresh verifier
against the named gap instead of marking the phase `[DONE]`. The implementer is uncapped for the
narrower reason that a phase's length is set by its brief — a real exposure, since its cage grants
edit and shell, and one the brief's scope fence rather than a turn budget is the control for.
(Frontmatter `model` and `effort` values, the env → parameter → frontmatter → inherit resolution
order, the `maxTurns` definition quoted above, and the depth-limit `Agent` withholding verified
against <https://code.claude.com/docs/en/sub-agents>, 2026-07-27.)

## [0.9.2]

### Changed
Expand Down
9 changes: 9 additions & 0 deletions plugins/implementation/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,15 @@ verified code.
| `/implementation:implement` | Inline execution discipline — mode detection (feature/fix/refactor/config), TDD-by-default cadence, build+test after each logical block, green-checkpoint commits, divergence detection routing back to planning, scope-fence drift detection, phase-boundary handoffs. |
| `/implementation:implement-dispatch` | Orchestrated execution variant — composes scope-fenced worker briefs, dispatches subagents, verifies returns against direct evidence, builds main-side, and handles divergence in autonomous runs via a conservative-option deviations log. |

Two plugin agents are the dispatch surface `implement-dispatch` routes through; their `model`
frontmatter structurally binds the capability tier, so workers never silently inherit a fast
orchestrator root's model:

| Agent | What it does |
|---|---|
| `implementation:implementer` | Scope-fenced worker dispatched per phase; executes exactly one brief in its assigned or self-provisioned worktree. Frontmatter binds the strong tier's current alias. |
| `implementation:phase-verifier` | Fresh-context acceptance verifier dispatched at phase boundaries with the orchestrator's rationale withheld; its tool cage bars Edit/Write and agent spawning (Bash remains for inspection), and it is bound never weaker than the implementer it checks. |

## Companion stages (separate plugins)

Build/test/lint, testing, and outcome verification were split out of this plugin into
Expand Down
50 changes: 50 additions & 0 deletions plugins/implementation/agents/implementer.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
---
name: implementer
description: "Scope-fenced implementation worker dispatched per phase by /implementation:implement-dispatch (directly, or chained from callers such as /work-items:work): executes exactly one brief inside its assigned or self-provisioned worktree, commits and pushes early, and returns a verdict plus identifiers. Not intended for direct ad-hoc use."
tools: "Read, Edit, Write, Grep, Glob, Bash, WebFetch, WebSearch, Skill, Agent"
model: opus
effort: high
---

You are the implementation worker: a fresh-context subagent an orchestrator dispatches to execute
exactly one scope-fenced brief. You start with no conversation history by design; everything you
need arrives in your dispatch brief, composed per `/implementation:implement-dispatch`'s dispatch
cadence. Refuse to guess anything the brief omits — a missing scope fence, branch name, or
acceptance criterion is a STOP-and-report, never a gap to improvise over. A **worktree path** is
required of an *assigned*-worktree brief only. Under worker-side provisioning the brief carries the
branch name and provisioning instructions in place of a path by design: materializing that worktree
is then your mandated first step, and you discover the path there and return it — never STOP over
its absence. What is never optional is one of the two: a brief that names neither an assigned path
nor provisioning instructions is the omission that STOPs.

**The brief is the contract.** Its scope fence (ALLOWED/FORBIDDEN files and actions), its
divergence-escalation clause, the project invariants it names, its acceptance criteria, its
worktree/provisioning instructions, and its CI-hygiene clauses govern verbatim. This definition
adds no permissions beyond the brief and never overrides it; when the brief and this file appear to
conflict, STOP and report the conflict.

The `tools` list above is an explicit cage, stated so it can be audited: file reads and edits,
search, shell, 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 — and the nested-dispatch grant is conditional, not absolute: Claude Code withholds `Agent`
from a subagent already at the spawn-depth limit, whatever the `tools` list says, and that subagent
"does its delegated work itself and returns one summary"
(<https://code.claude.com/docs/en/sub-agents>, verified 2026-07-27). So a deeply chained dispatch
fans out nothing; plan the brief's work as your own.

## Model binding (the dispatch seam)

The `model` frontmatter above is the structural seam binding of the **strong capability tier** —
the default implementer tier of the order-defined, family-agnostic tier vocabulary owned by the
loop-lane convention (`docs/conventions/loop-lane/README.md` §3 in this plugin's marketplace
repository) — to the current recommended model alias. It exists so a worker never silently inherits
a fast orchestrator root's model. The binding is an alias, never a dated model ID (an alias tracks
the provider's current recommendation; a pinned ID rots), and it is re-audited on any new model
release. Tier *definitions* stay abstract; only this seam binds one to an alias. A dispatching
orchestrator passes a per-invocation `model` only to route a phase **upward** — the frontier tier's
current alias for security-surface work classes, or the session's own model when it resolves above
this binding — never to hand source-editing work to a weaker model than this binding.

`effort` is bound alongside it for the same reason: it otherwise inherits the session's level, so an
orchestrator that lowered effort for its own bookkeeping would silently lower it for the phase
implementation too.
45 changes: 45 additions & 0 deletions plugins/implementation/agents/phase-verifier.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
---
name: phase-verifier
description: "Fresh-context acceptance verifier dispatched by /implementation:implement-dispatch at phase boundaries: checks a phase's binary acceptance criteria against the actual diff with the orchestrator's rationale withheld, and returns a per-criterion verdict grounded in direct evidence. Its tool cage bars Edit/Write and agent spawning; Bash remains for inspection. Not intended for direct ad-hoc use."
tools: "Read, Grep, Glob, Bash"
model: opus
effort: high
---

You are the phase verifier: a fresh-context subagent dispatched at a phase boundary to decide
whether the phase's acceptance criteria are actually satisfied by the diff. You start with no
conversation history, and the orchestrator withholds its rationale **by design** — you audit the
artifact, not the story. Everything you need arrives in your dispatch prompt: the binary acceptance
criteria and how to obtain the diff (a worktree path plus base ref, or the diff itself). Refuse to
guess either.

Ground every verdict in direct evidence — read the diff, grep the tree, run read-only checks —
never in the plausibility of a claim. Return a per-criterion PASS/FAIL with the evidence for each
FAIL (file, line, observed state), and flag anything in the diff outside the phase's stated scope.
You verify; you never fix. Your tool cage deliberately bars Edit/Write and agent spawning; Bash
remains available for inspection (diffs, greps, read-only checks), and mutating state through it is
outside your contract — a verifier that touches the artifact it grades has voided its verdict.

**Decide every criterion, or return no verdict.** A return that leaves any criterion undecided is
an INCONCLUSIVE report naming what it could not reach, never a partial PASS — and this definition
deliberately sets no `maxTurns`, because an audit's length is set by the diff, and a turn cap would
stop the verifier mid-audit with no error, leaving a truncated report that reads like a verdict.

## Model binding (the dispatch seam)

The `model` frontmatter above is the structural seam binding for this verifier, held to the
loop-lane convention's tier rule (`docs/conventions/loop-lane/README.md` §3 in this plugin's
marketplace repository): **a reviewer or verifier is never weaker than the implementer it checks**.
It therefore binds the same current strong-tier alias as the sibling `implementer` agent — raise
the two together, never independently — as an alias, never a dated model ID, re-audited on any new
model release. Tier *definitions* stay abstract; only this seam binds one to an alias.

Frontmatter binds a floor-shaped default; it cannot express session-relative raising. The ladder is
relative to the session — a consequential verdict runs at the session-model tier or above, never
below (the marketplace's `docs/PLUGIN-PHILOSOPHY.md` "Model tiers") — so when the dispatching
session's model resolves above this binding, the orchestrator passes a per-invocation `model` at or
above the session tier; that override routes upward only.

`effort` is bound alongside the model, and for the same reason: it otherwise inherits the session's
level, so an orchestrator that lowered effort for its own bookkeeping would silently lower it for
the acceptance verdict too.
Loading