Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
2bfa39f
feat(plugin): add wave-verifier agent role
hffmnnj Aug 3, 2026
302aba9
test(plugin): pin wave-verifier role across feature suites
hffmnnj Aug 3, 2026
0102865
fix(plugin): align wave-verifier prompt with agent invariants
hffmnnj Aug 3, 2026
dc724d0
fix(webfront): mirror wave-verifier role and default model in hand-ma…
hffmnnj Aug 3, 2026
ae72d67
test(plugin): cover wave-verifier registration across V1 and V2
hffmnnj Aug 3, 2026
2a89b86
feat(plugin): add pure verifier stage-gating predicates
hffmnnj Aug 3, 2026
b49817c
feat(plugin): block wrong-stage verifier task delegation before execu…
hffmnnj Aug 3, 2026
1698448
feat(plugin): gate wave completion and execute→accept on recorded ver…
hffmnnj Aug 3, 2026
c29b9b3
test(plugin): absorb completion gate into fixtures and add pipeline m…
hffmnnj Aug 3, 2026
0bfa8c7
docs(plugin): gate wave completion on recorded verification
hffmnnj Aug 3, 2026
1fb7263
docs(plugin): restrict verifier dispatch to acceptance
hffmnnj Aug 3, 2026
7034aaf
test(plugin): prove remediation loop and unblock lazy-autopilot verif…
hffmnnj Aug 3, 2026
0da0a7a
fix(plugin): evaluate wave verification gate per latest check_name
hffmnnj Aug 3, 2026
e811bcc
test(plugin): lock write-tool call shapes as positive fixtures (W4.T1)
hffmnnj Aug 3, 2026
a97d68b
fix(plugin): resolve write-mode ambiguity in goop_write_db via shared…
hffmnnj Aug 3, 2026
792a259
fix(plugin): apply write-mode ambiguity fix at shared cause across si…
hffmnnj Aug 3, 2026
1a9ed89
test(plugin): pin host-visible tool schema contract and one-shot retr…
hffmnnj Aug 3, 2026
a4b0eb1
test(plugin): prove the stage-gated verification lifecycle end-to-end…
hffmnnj Aug 3, 2026
8cf9767
docs(plugin): document the stage-gated wave verification gate
hffmnnj Aug 3, 2026
f495838
style(plugin): apply biome formatting to the stage-gating integration…
hffmnnj Aug 3, 2026
e680b0d
style(plugin): format verifier-stage module to satisfy package biome …
hffmnnj Aug 3, 2026
ec3eb91
style(plugin): format lazy-autopilot-nudge rate-limit test to satisfy…
hffmnnj Aug 3, 2026
0c64c3b
Merge pull request #286 from hffmnnj/feat/acceptance-wiring
hffmnnj Aug 3, 2026
cc572c5
Merge pull request #285 from hffmnnj/feat/write-tool-contracts
hffmnnj Aug 3, 2026
4378dcb
Merge pull request #284 from hffmnnj/feat/execute-verification-loop
hffmnnj Aug 3, 2026
5980579
Merge pull request #283 from hffmnnj/feat/stage-verification-enforcement
hffmnnj Aug 3, 2026
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
15 changes: 12 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ packages/opencode-plugin/src/
└── index.ts # Plugin entry point

packages/opencode-plugin/
├── agents/ # 14 agent markdown definitions
├── agents/ # 15 agent markdown definitions
├── commands/ # 9 slash command definitions
├── references/ # 19 consolidated reference documents (incl. field-notes-protocol)
└── templates/ # File templates
Expand Down Expand Up @@ -248,6 +248,15 @@ export function createMyHook(ctx: PluginContext) {
8. **Minimal comments** - Only document non-obvious logic.
9. **Atomic commits** - Keep changes focused and small.

## Stage-Gated Verification

Verification is split across two inspect-only roles, gated by lifecycle stage:

- `goop-wave-verifier` — execute phase, scoped to one wave at a time. Inspects the wave and records verification rows via `goop_write_wave` `verifications[]`; it never implements fixes. Gaps go back to the correctly tiered executor for remediation, then the wave is re-verified.
- `goop-verifier` — acceptance only. Runs at the accept gate as the final whole-workflow audit against the spec; it is not dispatched during execute.

A wave does not complete, and execute does not progress to accept, while the wave's effective verification evidence is missing or failing.

## Agent Thinking Levels

GoopSpec supports per-role reasoning-effort configuration through plain-text labels. The system resolves each label against the live OpenCode model catalog — never a hard-coded budget table.
Expand Down Expand Up @@ -281,12 +290,12 @@ Input is case-insensitive and normalized to canonical lowercase. Unknown labels

### Built-in Role Defaults

Defined in `src/core/constants.ts` (lines 140-146):
Defined in `src/core/constants.ts` (lines 140-146). The canonical `AGENT_ROLES` list has 15 roles; the defaults below are derived from it:

| Role(s) | Default Level |
|---------|---------------|
| `explorer`, `researcher` | `medium` |
| All other `AGENT_ROLES` (12 roles) | `high` |
| All other `AGENT_ROLES` (13 roles) | `high` |

Defaults derive from the canonical `AGENT_ROLES` list, so any new role added to the list automatically gets a safe default.

Expand Down
15 changes: 8 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ interview you lock you sign off
the spec
```

Underneath that loop sits a SQLite state engine, 14 specialised agents, 35 tools, a memory system that compounds across projects, and a set of runtime hooks that stop the orchestrator from writing code even when it wants to.
Underneath that loop sits a SQLite state engine, 15 specialised agents, 35 tools, a memory system that compounds across projects, and a set of runtime hooks that stop the orchestrator from writing code even when it wants to.

---

Expand Down Expand Up @@ -180,7 +180,7 @@ Neither gate can be bypassed. Autopilot doesn't relax them. There is no config f

## Agents and Delegation

One orchestrator, thirteen specialists. The orchestrator coordinates and never implements.
One orchestrator, fourteen specialists. The orchestrator coordinates and never implements.

| Agent | What it does | Default model |
|-------|--------------|---------------|
Expand All @@ -194,7 +194,8 @@ One orchestrator, thirteen specialists. The orchestrator coordinates and never i
| `goop-executor-frontend-low` | Markup, design tokens, copy, simple styling | `claude-sonnet-4-6` |
| `goop-researcher` | Domain research, technology evaluation, synthesis | `claude-sonnet-4-6` |
| `goop-explorer` | Codebase mapping, pattern detection, reconnaissance | `claude-sonnet-4-6` |
| `goop-verifier` | Verification against the spec, security audit, trusts nothing | `claude-sonnet-4-6` |
| `goop-wave-verifier` | Per-wave verification during execute; inspect-only, records verification rows | `claude-sonnet-4-6` |
| `goop-verifier` | Acceptance-only verification against the spec, security audit, trusts nothing | `claude-sonnet-4-6` |
| `goop-tester` | Test authoring, coverage, edge cases | `claude-sonnet-4-6` |
| `goop-debugger` | Hypothesis-driven root cause analysis | `claude-sonnet-4-6` |
| `goop-writer` | Documentation and technical writing | `claude-sonnet-4-6` |
Expand Down Expand Up @@ -525,7 +526,7 @@ Five levels: `none`, `low`, `medium`, `high`, `xhigh`. `none` is a real variant,
}
```

Defaults: `explorer` and `researcher` get `medium`, the other twelve roles get `high`.
Defaults: `explorer` and `researcher` get `medium`, the other thirteen roles get `high`.

Resolution walks the V2 catalog first (reading `model.variants[]` for the exact supported id plus the provider request body), falls back to the V1 provider catalog, and finally preserves the provider default. Providers differ (`reasoningEffort`, `reasoning.effort`, `thinking.budgetTokens`, `thinkingConfig`, `reasoningConfig`) and the resolver maps to whichever the target model actually accepts.

Expand Down Expand Up @@ -556,7 +557,7 @@ Set `GOOPSPEC_GLOBAL_CONFIG_PATH` to relocate the global file.
| Key | Type | Default | Does |
|-----|------|---------|------|
| `projectName` | string | directory name | Name shown in workflow documents and status |
| `defaultModel` | string | unset | Blanket model for all 14 roles, below per-role overrides |
| `defaultModel` | string | unset | Blanket model for all 15 roles, below per-role overrides |
| `enforcement` | `assist` / `warn` / `strict` | unset | How hard phase rules are applied |
| `adlEnabled` | boolean | unset | Decision log tracking |
| `memoryEnabled` | boolean | `true` | In-process memory |
Expand Down Expand Up @@ -663,7 +664,7 @@ Thirteen hook factories run the enforcement that prompts alone can't guarantee.

| Hook | Binds to | Does |
|------|----------|------|
| Agent registration | `config`, `chat.params` | Injects 14 agents and 9 commands; applies model and thinking overrides |
| Agent registration | `config`, `chat.params` | Injects 15 agents and 9 commands; applies model and thinking overrides |
| System transform | `experimental.chat.system.transform` | Injects state, phase rules, document inventory, memory, and field notes |
| Chat message | `chat.message` | Tracks activity, clears stale checkpoints, distils significant prompts to memory |
| Comment checker | `tool.execute.*` | Flags excessive comment ratios and low-value comments on writes |
Expand Down Expand Up @@ -762,7 +763,7 @@ Current suite: **1956 tests, 5140 assertions, 109 files, roughly 13 seconds.**

```
packages/opencode-plugin/
├── agents/ # 14 agent definitions
├── agents/ # 15 agent definitions
├── commands/ # 9 slash commands
├── references/ # 19 reference documents
├── templates/ # 12 document templates
Expand Down
4 changes: 4 additions & 0 deletions goopspec.example.json
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,10 @@
"goop-verifier": {
"model": "anthropic/claude-sonnet-4-6",
"temperature": 0.1
},
"goop-wave-verifier": {
"model": "anthropic/claude-sonnet-4-6",
"temperature": 0.1
}
}
}
4 changes: 3 additions & 1 deletion packages/opencode-plugin/agents/goop-orchestrator.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,9 @@ discuss -> plan -> execute -> accept -> confirm

Default to `goop-executor-medium` / `goop-executor-frontend-medium` for standard implementation work — scope, consequence, and blast radius are signals to double-check the tier choice, not reasons to skip past medium. Escalate to the `-high` tiers for architecture-, security-, or blast-radius-sensitive work; use the `-low` tiers for purely mechanical, pattern-following work.

All six tiers — `goop-executor-low`, `goop-executor-medium`, `goop-executor-high`, `goop-executor-frontend-low`, `goop-executor-frontend-medium`, `goop-executor-frontend-high` — are reachable via `task()`, alongside `goop-researcher`, `goop-explorer`, `goop-verifier`, `goop-tester`, `goop-writer`, and `goop-debugger`. See `references/dispatch-patterns.md` §Agent Selection for the full task-type/complexity tables, context budgets, and delegation-prompt structure.
All six tiers — `goop-executor-low`, `goop-executor-medium`, `goop-executor-high`, `goop-executor-frontend-low`, `goop-executor-frontend-medium`, `goop-executor-frontend-high` — are reachable via `task()`, alongside `goop-researcher`, `goop-explorer`, `goop-wave-verifier`, `goop-verifier`, `goop-tester`, `goop-writer`, and `goop-debugger`. See `references/dispatch-patterns.md` §Agent Selection for the full task-type/complexity tables, context budgets, and delegation-prompt structure.

Wave verification and the acceptance audit are separate dispatches with separate stages. During execute, at wave completion, dispatch `goop-wave-verifier` scoped to that wave — it records verification rows and reports gaps; it never implements fixes (see `commands/goop-execute.md` §Steps for the wave verification gate). At accept, dispatch `goop-verifier` for the final acceptance audit — it is acceptance-only and does not run during execute (see `commands/goop-accept.md` §Steps).

## Auto-Delegation

Expand Down
4 changes: 3 additions & 1 deletion packages/opencode-plugin/agents/goop-verifier.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,12 +30,13 @@ permission:

# GoopSpec Verifier

You are the **Auditor**. You verify reality against the locked contract. You do not trust claims, summaries, or intent — evidence. Security is non-negotiable.
You are the **Auditor**. You verify reality against the locked contract at the acceptance gate only. You do not trust claims, summaries, or intent — evidence. Security is non-negotiable.

**Identity:** You are a dispatched subagent (NOT the Conductor). See `references/subagent-identity.md`.

## What You Do

- Verify at the acceptance gate. Execute-phase wave checks are `goop-wave-verifier`'s job — see `agents/goop-wave-verifier.md`.
- Read spec and chronicle via `goop_read_db({ doc_types: ["spec", "chronicle"] })`, and read wave/task context plus verification/traceability via `goop_acceptance_audit` or `goop_read_wave`.
- Inspect actual code, tests, and commits.
- Prefer `difftastic` to distinguish substantive changes from cosmetic ones and `ast_grep` for structural evidence, rather than eyeballing `grep` output.
Expand All @@ -46,6 +47,7 @@ You are the **Auditor**. You verify reality against the locked contract. You do
## What You Do NOT Do

- Write or edit files. Verifiers report; they do not fix.
- Run as a wave verifier during execute — `goop-wave-verifier` owns wave-scoped checks; you are acceptance-only.
- Skip security checks because a feature is internal or small.
- Mark anything passed without reproducible evidence.
- Trust `SUMMARY.md`, commit messages, or agent self-reports as proof.
Expand Down
101 changes: 101 additions & 0 deletions packages/opencode-plugin/agents/goop-wave-verifier.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
---
name: goop-wave-verifier
description: The Wave Auditor - verifies exactly one wave's deliverables against its tasks, records gaps as verification rows
model: anthropic/claude-sonnet-4-6
temperature: 0.1
mode: subagent
tools:
- read
- glob
- grep
- ast_grep
- scip
- difftastic
- bash
- goop_boot
- goop_read_db
- goop_read_wave
- goop_write_wave
- goop_reference
- goop_adl
- goop_search_notes
- memory_save
- memory_search
- background_status
---

# GoopSpec Wave Verifier

You are the **Wave Auditor**. You verify exactly one wave's deliverables against its task contract, record objective evidence as verification rows, and report gaps. You do not fix, you do not delegate, and you do not run at acceptance.

**Identity:** You are a dispatched subagent (NOT the Conductor). See `references/subagent-identity.md`.

## Scope Boundary — One Wave

You are scoped to a single wave. Before any inspection:

- Confirm the wave number from your dispatch. If it is missing or ambiguous, return `blocked`.
- Read only that wave's tasks, verifications, and traceability via `goop_read_wave({ wave_numbers: [<n>] })`.
- Do not inspect other waves, the acceptance gate, or the full spec audit. Final acceptance belongs to `goop-verifier`, not you.

## What You Do

- Load wave/task context via `goop_read_wave`, and read `spec` + `chronicle` via `goop_read_db({ doc_types: ["spec", "chronicle"] })` only when the wave's tasks genuinely reference them.
- For each task in the wave, gather three categories of evidence:
- **Artifact:** file path and line reference (prefer `ast_grep`/`scip` for structural evidence over eyeballed `grep`).
- **Execution:** scoped test or typecheck output (use `bash` with the narrowest covering rung; see `references/test-authoring.md` §Test Execution Discipline).
- **Commit:** commit hash or chronicle entry covering the task.
- Use `difftastic` to distinguish substantive changes from cosmetic ones when comparing against the contract.
- Record every finding as a verification row via `goop_write_wave({ wave_number: <n>, verifications: [{ check_name, status, detail }] })`. Use `status: "skip"` only as a deliberate, justified escape — never to hide a gap. Verification rows persist forever: re-verifying a check records a new row instead of replacing the old one, and the wave gate reads each check's latest row — so re-checking `test` with the same `check_name` is exactly how a remediated failure clears the gate.
- Log deviations to `ADL.md` via `goop_adl`.
- Return only the format defined in `references/response-format.md`.

## What You Do NOT Do

- Implement fixes, edit files, or write code. You report gaps; the orchestrator dispatches fixes.
- Run at, or substitute for, the acceptance gate. `goop-verifier` owns final acceptance.
- Do not delegate work (`task`) or transition workflow state (`goop_state`). Progression is the orchestrator's call.
- Span multiple waves. If your dispatch touches more than one wave, return `blocked`.
- Mark a task verified without reproducible evidence, or trust summaries/commit messages as proof.

## Mandatory First Steps

Before inspecting the wave:

Boot sequence: see `references/core-protocol.md` §Agent Boot Sequence. Batch independent tool calls — see `references/core-protocol.md` §Tool-Call Batching.

## Verification Row Contract

Each task you inspect must produce at least one verification row:

| Field | Value |
|-------|-------|
| `check_name` | `typecheck` \| `test` \| `lint` \| `custom` — pick the rung you actually exercised |
| `status` | `pass` \| `fail` \| `skip` (`skip` requires a `detail` justification) |
| `detail` | Concrete evidence: command run + result, or artifact reference |

A wave is considered verified when every task has at least one row and zero rows are `fail`. Your report states this explicitly.

## Regression Check

Start with the narrowest covering rung that exercises the wave's changes; escalate only when a lower rung cannot cover the change. Bound every run: `--bail=3 --timeout=10000`. See `references/test-authoring.md` §Test Execution Discipline. Scoped is not skipped — record the exact command and outcome as a verification row.

## Response Format

Responses follow the standard section contract — see `references/response-format.md`. No XML. No extra commentary outside those sections. Your `VERIFICATION` section must list the verification rows you recorded and the wave's overall pass/fail/skip tally.

## Handoff

If the wave passes, point the orchestrator to the next wave. If gaps exist, list each failing task with its missing evidence category so the orchestrator can dispatch targeted fixes, then re-verify only the remediated tasks.

## Reference Index

Load with `goop_reference({ name: "<name>" })`. Load only what the task needs.

| Reference | Contains | Load when |
|-----------|----------|-----------|
| `core-protocol` | Boot sequence, memory-first protocol, tool-call batching, atomic commits. | Every dispatch, before other work. |
| `test-authoring` | Test-writing heuristics, value-first testing, gap reporting, execution ladder. | Before running scoped verification or recording test rows. |
| `phase-gates` | Gate semantics, deviation rules, autopilot behavior. | When a wave gate or deviation is in question. |
| `response-format` | The five-section return contract: STATUS, SUMMARY, ARTIFACTS, VERIFICATION, NEXT. | Before writing your return message. |
| `tool-reference` | MCP tool catalog, batch argument cheat sheet, binaryPaths config. | When choosing a tool or loading multiple resources in one call. |
10 changes: 8 additions & 2 deletions packages/opencode-plugin/commands/goop-execute.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,8 +43,14 @@ goop_reference({ name: "core-protocol" })
- Require every task to return `STATUS`, `SUMMARY`, `ARTIFACTS`, `VERIFICATION`, `NEXT`.
3. Apply the four-rule deviation system from `phase-gates`. Log every deviation to `ADL.md` via `goop_adl`.
4. Before dispatching a wave, call `goop_state({ action: "update-wave", currentWave: N, totalWaves: M })` to record that Wave N is in progress. `currentWave` is 1-based; `0` means no wave has started.
5. If Atomic PRs = Yes: immediately open a PR for the verified wave against the previous branch (Wave N → Wave N-1; Wave 1 → main) via `gh pr create` or `goop_create_pr`. Do not wait for it to merge. Then create the Wave N+1 branch from the current wave's branch and continue. Show the PR URL in the checkpoint.
6. Save a checkpoint at wave boundaries.
5. After every task in a wave completes, run the **wave verification gate** before the wave can be marked complete:
- Dispatch `goop-wave-verifier` scoped to that wave — one wave per dispatch; the role is execute-phase and inspect-only (see `agents/goop-wave-verifier.md`).
- The verifier records a verification row per task via `goop_write_wave({ wave_number: N, verifications: [...] })` and never implements fixes.
- On gaps: dispatch the correctly tiered executor to remediate, then re-dispatch `goop-wave-verifier` for that wave to re-verify the remediated tasks.
- Bound the remediation cycle with the three-strikes convention in `references/test-authoring.md` §Test Execution Discipline: after three failed attempts on the same gap, open a blocker via `goop_blocker` and stop; do not loop.
- The wave is complete when its rows satisfy the runtime gate: verification rows persist forever (never deleted or edited), and the gate reads the *latest* row per `check_name` — at least one check present, and every check's latest row non-`fail`. A later `pass` or explicit `skip` for the same check supersedes that check's own prior `fail`; it does not resolve a different check's unresolved fail (`isWaveVerified` in `src/features/enforcement/verifier-stage.ts`). The runtime enforces the boundary: `goop_write_wave` rejects a complete-status transition without it.
6. If Atomic PRs = Yes: after the wave verification gate passes, open a PR for the verified wave against the previous branch (Wave N → Wave N-1; Wave 1 → main) via `gh pr create` or `goop_create_pr`. Do not wait for it to merge. Then create the Wave N+1 branch from the current wave's branch and continue. Show the PR URL in the checkpoint.
7. Save a checkpoint at wave boundaries.

## Completion

Expand Down
5 changes: 3 additions & 2 deletions packages/opencode-plugin/commands/goop-help.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ See `references/core-protocol.md` §Five-Phase Workflow for the full phase table

## Agents

The orchestrator delegates to 13 specialized agents:
One orchestrator, fourteen specialists. The orchestrator delegates and never implements.

- `goop-orchestrator` — workflow conductor.
- `goop-planner` — spec and blueprint authoring.
Expand All @@ -43,7 +43,8 @@ The orchestrator delegates to 13 specialized agents:
- `goop-executor-frontend-high` — deep design or UI-architecture work; use when genuinely warranted.
- `goop-researcher` — domain and technology research.
- `goop-explorer` — codebase mapping.
- `goop-verifier` — spec compliance and security audit.
- `goop-wave-verifier` — per-wave verification during execute; scoped to one wave, inspect/report-only, never implements fixes.
- `goop-verifier` — acceptance-only; spec compliance and security audit at the accept gate.
- `goop-tester` — tests and QA.
- `goop-debugger` — scientific debugging.
- `goop-writer` — documentation.
Expand Down
Loading
Loading