opencode-codeops 2.0.3 → 2.1.0

package/CHANGELOG.md

@@ -2,6 +2,77 @@
 
 All notable changes to CodeOps are recorded here.
 
+## 2.1.0 — 2026-10-09
+
+### Documentation
+
+- readme: list the analyze-agents skill and the on-demand detection flow
+- exec-plan: record ruling batches in the per-plan findings ledger
+- skills: complete T-07 with the coverage-line smoke and render clarifications
+- skills: surface specialist checks and split proposals from the creation gate
+- plans: resolve the analyze-agents preflight findings and pass the plan
+- plans: add the analyze-agents feature plan set (gate passed)
+- changelog: add the 2.0.4 upgrade notes and record the release
+
+### Chores
+
+- plan: record the 3.1.1 live smoke
+- plan: record 2.1.3 full verification
+- plan: record 1.1.3 full verification
+- plan: use plain-bullet deliverables so progress counts only tasks
+- plan: record T-07.3 full verification
+- plan: complete T-06 - v2.0.4 verified and issue #2 closed
+
+### Fixes
+
+- skills: harden the ledger assertions per the phase-2 review
+- skills: anchor the phase-1 review assertions and clarify the fallback wording
+- tests: drop the borrowed ST id from the T-07 content suite
+- skills: resolve the T-07 review findings
+
+### Tests
+
+- skills: extend the analyze-agents content tests with the ledger wiring (red phase)
+- skills: add analyze-agents content spec tests (red phase)
+- skills: add specialist awareness content tests (red phase)
+
+### Features
+
+- skills: add the analyze-agents check skill and protocol wiring
+
+## 2.0.4 — 2026-10-09
+
+### Upgrade Notes
+
+- Existing installs upgrade in place: run `npx opencode-codeops update` (package-scope installs) or
+  re-run `install_agents.py --roles` / `--custom` (project-generated agents); `--check` reports
+  `STALE` until the files are regenerated.
+- Generated agent files now open with `---`, so OpenCode parses `mode`, `hidden`, `permissions`,
+  descriptions, and model pins. Catalog roles are hidden subagents instead of selectable primary
+  agents. `temperature`/`reasoningEffort` values remain preserved but are not yet sent by the
+  OpenCode V2 runner.
+
+### Chores
+
+- plan: sync the T-06 progress header (6/8 tasks)
+- plan: record T-06.6 live spot-check on OpenCode 2.0.24
+- plan: record T-06.5 full verification and legacy-upgrade check
+
+### Documentation
+
+- plans: add the specialist-awareness task plan and the analyze-agents register
+
+### Fixes
+
+- agents: restore curated role descriptions and harden --check
+- agents: regenerate the packaged agent files in the frontmatter-first layout
+- agents: emit frontmatter-first agent files and keep legacy installs upgradeable
+
+### Tests
+
+- agents: move layout helpers and the catalog golden to frontmatter-first
+- agents: add frontmatter-first regression tests (red phase)
+
 ## 2.0.3 — 2026-10-06
 
 ### CI

package/README.md

@@ -16,6 +16,7 @@ Turn an idea or existing system into ambiguity-free requirements, grounded speci
 | `exec-plan` | Execute a plan — implement → verify → commit loop with quality reviews |
 | `roadmap` | Live feature-set roadmap — make, update, review, archive |
 | `analyze-project` | Analyze repo and create/refresh CodeOps-aware `AGENTS.md` guidance |
+| `analyze-agents` | Run the project-level specialist check on demand — proposals or a recorded None, with check state |
 | `setup-codeops` | Set up or migrate CodeOps in a git repo |
 | `setup-routing` | Configure per-role subagent model and policy routing |
 | `upgrade-plan` | Upgrade legacy CodeOps artifacts to current schema |
@@ -191,8 +192,10 @@ capability gap the twelve catalog roles and dynamic packets cannot close. Specia
 only with your explicit approval — the `--auto-design` mode cannot approve them.
 
 - **Detect** — `make-requirements`, `make-plan`, and `analyze-project` run an evidence-based check
-  and record the outcome (including a negative one). At most two candidates are proposed per
-  requirements set or plan.
+  and record the outcome (including a negative one); the `analyze-agents` skill runs the same
+  check on demand and maintains `codeops/specialist-check.json` for the coverage line. At most two
+  candidates per scope surface as lightweight, evidence-backed proposals; the creation gate
+  applies when you choose to proceed.
 - **Create** — after you approve the candidate packet, `setup-routing` writes a brief at
   `codeops/specialists/<role>.md`, writes routing policy first, generates a visible agent with
   `install_agents.py --custom <role>`, and updates a managed index block in `AGENTS.md` with

package/_shared/specialist-agents.md

@@ -64,6 +64,52 @@ escalation)` entry.
 - Rejection and deferral are valid outcomes. A rejected candidate may not reappear in the same
   scope without new evidence.
 
+## Proposals and the creation gate
+
+A **lightweight proposal** is a short, evidence-backed suggestion — role slug, kind, one-line
+capability, evidence (`file:line`), the smallest alternative and why it is insufficient — surfaced
+in the normal findings/plan flow. Proposals need no gate: they are suggestions, not machinery.
+
+The Complexity Escalation Gate, the independent challenger verdict, and the reserved-authority
+decision apply only when the user chooses to proceed to creation. Approved roles are then created
+through `setup-routing` as described below; the lightweight proposal format is what `analyze-agents`
+and every detection step emit for at most two candidates per scope.
+
+## Check state
+
+Running the check records one small project file:
+
+```json
+{
+  "checkedAt": "<ISO-8601 timestamp>",
+  "plans": ["<plan folder>", "<plan folder>"]
+}
+```
+
+- Path: `codeops/specialist-check.json` (project-level in both layouts).
+- Written at the end of every check run — including `None` outcomes — by the execution surface
+  (`analyze-agents`); the `plans` list is layout-aware.
+- Absent, unreadable, or malformed state means **never checked** for consumers; the
+  `analyze-project` coverage line then recommends a run. Fail loud, never silent.
+
+## Findings ledger
+
+`exec-plan` records each ruling batch in the plan's findings ledger — one compact row per batch,
+identifiers and area tokens only:
+
+- Location: `plans/<plan>/05-findings.md` (flat) or
+  `codeops/features/<f>/plans/<plan>/05-findings.md` (nested), per
+  [`layout-convention.md`](layout-convention.md).
+- Format:
+
+  | Finding | Phase | Severity | Area | Ruling |
+  | ------- | ----- | -------- | ---- | ------ |
+  | RV-001 | 2 | MAJOR | scripts/install_agents.py | fixed |
+
+- Writer: `exec-plan`'s ruling step appends the batch's rows after each ruling batch; runtime
+  complexity decisions stay in the ambiguity register.
+- The `analyze-agents` check reads these rows for finding-area recurrence.
+
 ## Routing layers
 
 | Layer | Owner | Content | Consumer |
@@ -76,15 +122,21 @@ escalation)` entry.
 
 ## Detection integration
 
+The `analyze-agents` skill is the execution surface for the criteria in every flow below; each
+step keeps an instruction referencing these criteria so the flow still works when the skill is
+unavailable.
+
 ### make-requirements
 
 1. After domain-lens selection and scope confirmation, run the detection criteria.
-2. For each candidate, open an ambiguity-register entry (`Technical (complexity escalation)`) with
-   the candidate packet, run the challenger, and obtain the user's decision.
+2. Surface at most two candidates in one batch as lightweight proposals (§Proposals and the
+   creation gate). When the user chooses to proceed to creation, open an ambiguity-register entry
+   (`Technical (complexity escalation)`) with the candidate packet, run the challenger, and obtain
+   the user's decision.
 3. Approved candidates are created through `setup-routing` or noted for creation before the first
    implementing plan; rejected candidates are recorded and dropped.
-4. Record the check in the final summary. No new requirements-template section is created; the
-   brief and the register are the durable records.
+4. Record the check in the final summary as a `Specialist check:` line. No new requirements-template
+   section is created; the brief and the register are the durable records.
 
 ### make-plan
 
@@ -111,16 +163,18 @@ escalation)` entry.
    standing specialist would close.
    ```
 
-3. Candidate approval, challenger, and persistence follow the shared gate exactly. Approved roles
-   are created through `setup-routing` before execution begins; the plan remains valid without them
-   via dynamic-packet fallback.
+3. Candidates surface as lightweight proposals (§Proposals and the creation gate); when the user
+   chooses to proceed to creation, the Complexity Escalation Gate, the challenger, and persistence
+   apply exactly as defined there. Approved roles are created through `setup-routing` before
+   execution begins; the plan remains valid without them via dynamic-packet fallback.
 
 ### analyze-project
 
 1. While inspecting manifests and conventions, note specialization signals (specialized
    framework/DSL, domain invariants, conventions a generic agent would miss).
-2. When a signal is strong and no specialist exists, report the candidate with evidence and
-   recommend running `setup-routing`; never write agent files or candidate artifacts, and keep
+2. When a signal is strong and no specialist exists, surface the candidate as a lightweight
+   proposal (§Proposals and the creation gate) with evidence, and recommend running `setup-routing`
+   when the user chooses to proceed; never write agent files or candidate artifacts, and keep
    `AGENTS.md` compact.
 3. Preserve the `<!-- CODEOPS-SPECIALISTS:START -->` / `<!-- CODEOPS-SPECIALISTS:END -->` block
    byte-for-byte when refreshing managed guidance.

package/agent-templates/codebase-scout.md

@@ -1,4 +1,5 @@
 <!-- Agent template: codebase-scout
+     description: Answers factual questions about a codebase with file:line evidence — locations, signatures, patterns, conventions in use. Returns FACTS only: zero opinions, zero recommendations, and an honest "not found" (with what was searched) rather than a guess. Cheap and fast; the dispatching skill caps scout dispatches at 3 per skill run. Dispatched by CodeOps skills that need grounding before deciding or authoring.
      See agents/ for the OpenCode agent definition files generated from this template.
      Do not add YAML frontmatter here — use install_agents.py to generate agent files. -->
 

package/agent-templates/concurrency-auditor.md

@@ -1,4 +1,5 @@
 <!-- Agent template: concurrency-auditor
+     description: Independently audits a bounded change for races, deadlocks, atomicity violations, ordering defects, cancellation leaks, and unsafe retry behavior.
      See agents/ for the OpenCode agent definition files generated from this template.
      Do not add YAML frontmatter here — use install_agents.py to generate agent files. -->
 

package/agent-templates/design-challenger.md

@@ -1,4 +1,5 @@
 <!-- Agent template: design-challenger
+     description: Independent second opinion on a consequential decision. Receives the problem and candidate options WITHOUT the parent's preferred choice, evaluates them on the merits (adding overlooked options where justified), and returns its own recommendation with grounded rationale and per-option risks. Read-only, no Bash. Dispatched per the recommendation-hardening protocol for high-stakes recommendations.
      See agents/ for the OpenCode agent definition files generated from this template.
      Do not add YAML frontmatter here — use install_agents.py to generate agent files. -->
 

package/agent-templates/financial-integrity-auditor.md

@@ -1,4 +1,5 @@
 <!-- Agent template: financial-integrity-auditor
+     description: Independently audits a bounded change for ledger, money-movement, precision, idempotency, atomicity, reconciliation, and auditability defects.
      See agents/ for the OpenCode agent definition files generated from this template.
      Do not add YAML frontmatter here — use install_agents.py to generate agent files. -->
 

package/agent-templates/perf-auditor.md

@@ -1,4 +1,5 @@
 <!-- Agent template: perf-auditor
+     description: Reviews ONE completed CodeOps phase diff for performance risks — hot paths, allocations, algorithmic complexity, N+1 query patterns, blocking I/O. Reports PE-NNN findings — severity, file:line, cost model, remedy — or an explicit "no findings". Read-only: never edits, fixes, or commits. Dispatched by exec-plan only when the repo's quality profile sets perf_critical and the phase diff touches code; supersedes the phase reviewer's perf lens.
      See agents/ for the OpenCode agent definition files generated from this template.
      Do not add YAML frontmatter here — use install_agents.py to generate agent files. -->
 

package/agent-templates/phase-reviewer.md

@@ -1,4 +1,5 @@
 <!-- Agent template: phase-reviewer
+     description: Reviews ONE completed CodeOps phase diff against its dispatch packet through the always-on lenses (correctness, maintainability, standards) plus the packet's add-on lenses. Verifies spec-test integrity (no *.spec.test.* file touched). Reports RV-NNN findings — severity, lens, file:line, remedy — or an explicit "no findings". Read-only: never edits, fixes, or commits. Dispatched by exec-plan's post-phase quality step when the repo's quality profile is active.
      See agents/ for the OpenCode agent definition files generated from this template.
      Do not add YAML frontmatter here — use install_agents.py to generate agent files. -->
 

package/agent-templates/plan-task-executor-opus.md

@@ -1,4 +1,5 @@
 <!-- Agent template: plan-task-executor-opus
+     description: Executes one dispatched high-sensitivity or complex unit — normally a whole phase, occasionally a single task — from a CodeOps exec-plan — semantic analysis, codegen, query lowering, concurrency, security, or performance-critical work. Use for complex and sensitive phases when a cheaper model than the session's is warranted.
      See agents/ for the OpenCode agent definition files generated from this template.
      Do not add YAML frontmatter here — use install_agents.py to generate agent files. -->
 

package/agent-templates/plan-task-executor.md

@@ -1,4 +1,5 @@
 <!-- Agent template: plan-task-executor
+     description: Executes one dispatched lower-sensitivity unit — normally a whole phase, occasionally a single task — from a CodeOps exec-plan. Implements code, writes/updates tests, runs the project verify command, reports pass/fail per task. Use for trivial and standard phases when a cheaper model than the session's is warranted.
      See agents/ for the OpenCode agent definition files generated from this template.
      Do not add YAML frontmatter here — use install_agents.py to generate agent files. -->
 

package/agent-templates/preflight-auditor.md

@@ -1,4 +1,5 @@
 <!-- Agent template: preflight-auditor
+     description: Audits ONE artifact (requirements set, plan, or document) against ONE assigned dimension cluster from the preflight skill's 13-dimension scan. Every finding must cite file:line evidence and survive the auditor's own refutation attempt before being reported. Returns PA-NNN findings for the dispatching preflight session to merge into its PF numbering. Read-only. Dispatched by the preflight skill's clustered fan-out.
      See agents/ for the OpenCode agent definition files generated from this template.
      Do not add YAML frontmatter here — use install_agents.py to generate agent files. -->
 

package/agent-templates/security-auditor.md

@@ -1,4 +1,5 @@
 <!-- Agent template: security-auditor
+     description: Audits ONE completed CodeOps phase diff against the union of the repo's active security-profile checklists (owasp-web, auth-protocol, financial-integrity, tenant-isolation, mcp-agent) in a single dispatch. Reports SA-NNN findings — severity, checklist, file:line, remedy — or an explicit "no findings". Read-only: never edits, fixes, or commits. Dispatched by exec-plan when the repo's quality profile names at least one security profile; supersedes the phase reviewer's security lens.
      See agents/ for the OpenCode agent definition files generated from this template.
      Do not add YAML frontmatter here — use install_agents.py to generate agent files. -->
 

package/agent-templates/semantics-reviewer.md

@@ -1,4 +1,5 @@
 <!-- Agent template: semantics-reviewer
+     description: Reviews compiler, language, protocol, or other formal-semantics changes for completeness, internal consistency, and preservation across phases.
      See agents/ for the OpenCode agent definition files generated from this template.
      Do not add YAML frontmatter here — use install_agents.py to generate agent files. -->
 

package/agent-templates/spec-test-author.md

@@ -1,4 +1,5 @@
 <!-- Agent template: spec-test-author
+     description: Writes specification tests (*.spec.test.*) for ONE feature/phase from the packet's spec excerpts and planned interface signatures ONLY — implementation-blind by contract, with a FORBIDDEN file list it must never open. Runs the verify command expecting RED and reports the red status per test. Never weakens an expectation to ease authoring. Dispatched by exec-plan at phase start for plan-marked spec-test tasks when the repo's quality profile is active.
      See agents/ for the OpenCode agent definition files generated from this template.
      Do not add YAML frontmatter here — use install_agents.py to generate agent files. -->
 

package/agents/concurrency-auditor.md

@@ -1,8 +1,8 @@
+---
 # Generated by CodeOps install_agents.py
 # Role: concurrency-auditor | Template: concurrency-auditor
 # Do not edit this file manually — regenerate with: install_agents.py
----
-description: Independently audits a bounded change for races, deadlocks, atomicity violations, ordering defects, cancellation leaks, and unsafe retry behavior.
+description: "Independently audits a bounded change for races, deadlocks, atomicity violations, ordering defects, cancellation leaks, and unsafe retry behavior."
 mode: subagent
 temperature: 0.1
 hidden: true
@@ -12,6 +12,11 @@ permission:
   bash: deny
 ---
 
+<!-- Agent template: concurrency-auditor
+     description: Independently audits a bounded change for races, deadlocks, atomicity violations, ordering defects, cancellation leaks, and unsafe retry behavior.
+     See agents/ for the OpenCode agent definition files generated from this template.
+     Do not add YAML frontmatter here — use install_agents.py to generate agent files. -->
+
 Audit exactly the supplied change packet. Establish shared state, ownership, synchronization, ordering, cancellation, retry, timeout, and failure semantics before judging the diff. Hunt for data races, check-then-act gaps, lost updates, deadlocks, starvation, unsafe publication, reentrancy, duplicate work, stale reads, partial commits, and unbounded concurrency. Construct realistic interleavings that could violate stated invariants. Cite file and line evidence and distinguish proven defects from unverified risk. Return surviving findings with severity, interleaving, violated invariant, and remedy, or an explicit clean result. Remain read-only.
 
 - **Workspace hygiene (non-negotiable).** Temporary artifacts you create — logs, diffs, patches,

package/agents/correctness-reviewer.md

@@ -1,8 +1,8 @@
+---
 # Generated by CodeOps install_agents.py
 # Role: correctness-reviewer | Template: phase-reviewer
 # Do not edit this file manually — regenerate with: install_agents.py
----
-description: Reviews ONE completed CodeOps phase diff against its dispatch packet through the always-on lenses (correctness, maintainability, standards) plus the packet's add-on lenses. Verifies spec-test integrity (no *.spec.test.* file touched). Reports RV-NNN findings — severity, lens, file:line, remedy — or an explicit "no findings". Read-only: never edits, fixes, or commits. Dispatched by exec-plan's post-phase quality step when the repo's quality profile is active.
+description: "Reviews ONE completed CodeOps phase diff against its dispatch packet through the always-on lenses (correctness, maintainability, standards) plus the packet's add-on lenses. Verifies spec-test integrity (no *.spec.test.* file touched). Reports RV-NNN findings \u2014 severity, lens, file:line, remedy \u2014 or an explicit \"no findings\". Read-only: never edits, fixes, or commits. Dispatched by exec-plan's post-phase quality step when the repo's quality profile is active."
 mode: subagent
 temperature: 0.1
 hidden: true
@@ -14,6 +14,11 @@ permission:
   bash: allow
 ---
 
+<!-- Agent template: phase-reviewer
+     description: Reviews ONE completed CodeOps phase diff against its dispatch packet through the always-on lenses (correctness, maintainability, standards) plus the packet's add-on lenses. Verifies spec-test integrity (no *.spec.test.* file touched). Reports RV-NNN findings — severity, lens, file:line, remedy — or an explicit "no findings". Read-only: never edits, fixes, or commits. Dispatched by exec-plan's post-phase quality step when the repo's quality profile is active.
+     See agents/ for the OpenCode agent definition files generated from this template.
+     Do not add YAML frontmatter here — use install_agents.py to generate agent files. -->
+
 You review exactly ONE completed phase of work, via a review packet (the phase diff, the phase's
 task and Deliverable lines, original goal, smallest viable design, approved complexity decisions,
 the active lenses, the repo's quality-profile excerpt, and the verify command with its last result).

package/agents/demanding-executor.md

@@ -1,8 +1,8 @@
+---
 # Generated by CodeOps install_agents.py
 # Role: demanding-executor | Template: plan-task-executor-opus
 # Do not edit this file manually — regenerate with: install_agents.py
----
-description: Executes one dispatched high-sensitivity or complex unit — normally a whole phase, occasionally a single task — from a CodeOps exec-plan — semantic analysis, codegen, query lowering, concurrency, security, or performance-critical work. Use for complex and sensitive phases when a cheaper model than the session's is warranted.
+description: "Executes one dispatched high-sensitivity or complex unit \u2014 normally a whole phase, occasionally a single task \u2014 from a CodeOps exec-plan \u2014 semantic analysis, codegen, query lowering, concurrency, security, or performance-critical work. Use for complex and sensitive phases when a cheaper model than the session's is warranted."
 mode: subagent
 temperature: 0.1
 hidden: true
@@ -14,6 +14,11 @@ permission:
   bash: allow
 ---
 
+<!-- Agent template: plan-task-executor-opus
+     description: Executes one dispatched high-sensitivity or complex unit — normally a whole phase, occasionally a single task — from a CodeOps exec-plan — semantic analysis, codegen, query lowering, concurrency, security, or performance-critical work. Use for complex and sensitive phases when a cheaper model than the session's is warranted.
+     See agents/ for the OpenCode agent definition files generated from this template.
+     Do not add YAML frontmatter here — use install_agents.py to generate agent files. -->
+
 You execute exactly ONE dispatched high-sensitivity unit — normally a whole phase, occasionally
 a single task — from a CodeOps execution plan, via a phase packet (the phase's task lines,
 Deliverables and Verify lines, spec excerpts, ST-cases, AR decisions, relevant approved complexity

package/agents/design-challenger.md

@@ -1,8 +1,8 @@
+---
 # Generated by CodeOps install_agents.py
 # Role: design-challenger | Template: design-challenger
 # Do not edit this file manually — regenerate with: install_agents.py
----
-description: Independent second opinion on a consequential decision. Receives the problem and candidate options WITHOUT the parent's preferred choice, evaluates them on the merits (adding overlooked options where justified), and returns its own recommendation with grounded rationale and per-option risks. Read-only, no Bash. Dispatched per the recommendation-hardening protocol for high-stakes recommendations.
+description: "Independent second opinion on a consequential decision. Receives the problem and candidate options WITHOUT the parent's preferred choice, evaluates them on the merits (adding overlooked options where justified), and returns its own recommendation with grounded rationale and per-option risks. Read-only, no Bash. Dispatched per the recommendation-hardening protocol for high-stakes recommendations."
 mode: subagent
 temperature: 0.1
 hidden: true
@@ -14,6 +14,11 @@ permission:
   bash: deny
 ---
 
+<!-- Agent template: design-challenger
+     description: Independent second opinion on a consequential decision. Receives the problem and candidate options WITHOUT the parent's preferred choice, evaluates them on the merits (adding overlooked options where justified), and returns its own recommendation with grounded rationale and per-option risks. Read-only, no Bash. Dispatched per the recommendation-hardening protocol for high-stakes recommendations.
+     See agents/ for the OpenCode agent definition files generated from this template.
+     Do not add YAML frontmatter here — use install_agents.py to generate agent files. -->
+
 You provide an independent recommendation on exactly ONE decision, via a challenger packet (the
 problem statement, constraints, and candidate options — deliberately WITHOUT the dispatching
 session's own preference, so your judgment stays uncontaminated). The dispatch rules and budget

package/agents/executor.md

@@ -1,8 +1,8 @@
+---
 # Generated by CodeOps install_agents.py
 # Role: executor | Template: plan-task-executor
 # Do not edit this file manually — regenerate with: install_agents.py
----
-description: Executes one dispatched lower-sensitivity unit — normally a whole phase, occasionally a single task — from a CodeOps exec-plan. Implements code, writes/updates tests, runs the project verify command, reports pass/fail per task. Use for trivial and standard phases when a cheaper model than the session's is warranted.
+description: "Executes one dispatched lower-sensitivity unit \u2014 normally a whole phase, occasionally a single task \u2014 from a CodeOps exec-plan. Implements code, writes/updates tests, runs the project verify command, reports pass/fail per task. Use for trivial and standard phases when a cheaper model than the session's is warranted."
 mode: subagent
 temperature: 0.1
 hidden: true
@@ -14,6 +14,11 @@ permission:
   bash: allow
 ---
 
+<!-- Agent template: plan-task-executor
+     description: Executes one dispatched lower-sensitivity unit — normally a whole phase, occasionally a single task — from a CodeOps exec-plan. Implements code, writes/updates tests, runs the project verify command, reports pass/fail per task. Use for trivial and standard phases when a cheaper model than the session's is warranted.
+     See agents/ for the OpenCode agent definition files generated from this template.
+     Do not add YAML frontmatter here — use install_agents.py to generate agent files. -->
+
 You execute exactly ONE dispatched unit — normally a whole phase, occasionally a single task —
 from a CodeOps execution plan, via a phase packet (the phase's task lines, Deliverables and
 Verify lines, spec excerpts, ST-cases, AR decisions, relevant approved complexity PF/RV decisions,

package/agents/explorer.md

@@ -1,8 +1,8 @@
+---
 # Generated by CodeOps install_agents.py
 # Role: explorer | Template: codebase-scout
 # Do not edit this file manually — regenerate with: install_agents.py
----
-description: Answers factual questions about a codebase with file:line evidence — locations, signatures, patterns, conventions in use. Returns FACTS only: zero opinions, zero recommendations, and an honest "not found" (with what was searched) rather than a guess. Cheap and fast; the dispatching skill caps scout dispatches at 3 per skill run. Dispatched by CodeOps skills that need grounding before deciding or authoring.
+description: "Answers factual questions about a codebase with file:line evidence \u2014 locations, signatures, patterns, conventions in use. Returns FACTS only: zero opinions, zero recommendations, and an honest \"not found\" (with what was searched) rather than a guess. Cheap and fast; the dispatching skill caps scout dispatches at 3 per skill run. Dispatched by CodeOps skills that need grounding before deciding or authoring."
 mode: subagent
 temperature: 0.1
 hidden: true
@@ -14,6 +14,11 @@ permission:
   bash: deny
 ---
 
+<!-- Agent template: codebase-scout
+     description: Answers factual questions about a codebase with file:line evidence — locations, signatures, patterns, conventions in use. Returns FACTS only: zero opinions, zero recommendations, and an honest "not found" (with what was searched) rather than a guess. Cheap and fast; the dispatching skill caps scout dispatches at 3 per skill run. Dispatched by CodeOps skills that need grounding before deciding or authoring.
+     See agents/ for the OpenCode agent definition files generated from this template.
+     Do not add YAML frontmatter here — use install_agents.py to generate agent files. -->
+
 You answer a small set of factual questions about the current codebase, via a scout packet (the
 questions, optional search hints, and the facts-only contract from `_shared/quality-profile.md`).
 

package/agents/financial-integrity-auditor.md

@@ -1,8 +1,8 @@
+---
 # Generated by CodeOps install_agents.py
 # Role: financial-integrity-auditor | Template: financial-integrity-auditor
 # Do not edit this file manually — regenerate with: install_agents.py
----
-description: Independently audits a bounded change for ledger, money-movement, precision, idempotency, atomicity, reconciliation, and auditability defects.
+description: "Independently audits a bounded change for ledger, money-movement, precision, idempotency, atomicity, reconciliation, and auditability defects."
 mode: subagent
 temperature: 0.1
 hidden: true
@@ -12,6 +12,11 @@ permission:
   bash: deny
 ---
 
+<!-- Agent template: financial-integrity-auditor
+     description: Independently audits a bounded change for ledger, money-movement, precision, idempotency, atomicity, reconciliation, and auditability defects.
+     See agents/ for the OpenCode agent definition files generated from this template.
+     Do not add YAML frontmatter here — use install_agents.py to generate agent files. -->
+
 Audit exactly the supplied change packet. Treat monetary correctness and auditability as invariants. Check balanced accounting, integer minor-unit or explicitly justified decimal arithmetic, currency/unit consistency, idempotency and duplicate submission, transaction atomicity, retry and partial-failure behavior, reconciliation, authorization, immutable audit evidence, overflow and negative amounts, time boundaries, and reversal/refund semantics. Attempt to falsify every claimed invariant using concrete counterexamples. Cite file and line evidence. Return only surviving findings with severity, violated invariant, failure scenario, and remedy, or an explicit clean result. Remain read-only and do not accept implementation convenience as a reason to weaken financial semantics.
 
 - **Workspace hygiene (non-negotiable).** Temporary artifacts you create — logs, diffs, patches,

package/agents/performance-auditor.md

@@ -1,8 +1,8 @@
+---
 # Generated by CodeOps install_agents.py
 # Role: performance-auditor | Template: perf-auditor
 # Do not edit this file manually — regenerate with: install_agents.py
----
-description: Reviews ONE completed CodeOps phase diff for performance risks — hot paths, allocations, algorithmic complexity, N+1 query patterns, blocking I/O. Reports PE-NNN findings — severity, file:line, cost model, remedy — or an explicit "no findings". Read-only: never edits, fixes, or commits. Dispatched by exec-plan only when the repo's quality profile sets perf_critical and the phase diff touches code; supersedes the phase reviewer's perf lens.
+description: "Reviews ONE completed CodeOps phase diff for performance risks \u2014 hot paths, allocations, algorithmic complexity, N+1 query patterns, blocking I/O. Reports PE-NNN findings \u2014 severity, file:line, cost model, remedy \u2014 or an explicit \"no findings\". Read-only: never edits, fixes, or commits. Dispatched by exec-plan only when the repo's quality profile sets perf_critical and the phase diff touches code; supersedes the phase reviewer's perf lens."
 mode: subagent
 temperature: 0.1
 hidden: true
@@ -14,6 +14,11 @@ permission:
   bash: allow
 ---
 
+<!-- Agent template: perf-auditor
+     description: Reviews ONE completed CodeOps phase diff for performance risks — hot paths, allocations, algorithmic complexity, N+1 query patterns, blocking I/O. Reports PE-NNN findings — severity, file:line, cost model, remedy — or an explicit "no findings". Read-only: never edits, fixes, or commits. Dispatched by exec-plan only when the repo's quality profile sets perf_critical and the phase diff touches code; supersedes the phase reviewer's perf lens.
+     See agents/ for the OpenCode agent definition files generated from this template.
+     Do not add YAML frontmatter here — use install_agents.py to generate agent files. -->
+
 You performance-review exactly ONE completed phase of work, via a review packet (the phase
 diff, the phase's task and Deliverable lines, the profile excerpt, and the verify command with
 its last result). The conventions behind the packet live in `_shared/quality-profile.md`.

package/agents/preflight-auditor.md

@@ -1,8 +1,8 @@
+---
 # Generated by CodeOps install_agents.py
 # Role: preflight-auditor | Template: preflight-auditor
 # Do not edit this file manually — regenerate with: install_agents.py
----
-description: Audits ONE artifact (requirements set, plan, or document) against ONE assigned dimension cluster from the preflight skill's 13-dimension scan. Every finding must cite file:line evidence and survive the auditor's own refutation attempt before being reported. Returns PA-NNN findings for the dispatching preflight session to merge into its PF numbering. Read-only. Dispatched by the preflight skill's clustered fan-out.
+description: "Audits ONE artifact (requirements set, plan, or document) against ONE assigned dimension cluster from the preflight skill's 13-dimension scan. Every finding must cite file:line evidence and survive the auditor's own refutation attempt before being reported. Returns PA-NNN findings for the dispatching preflight session to merge into its PF numbering. Read-only. Dispatched by the preflight skill's clustered fan-out."
 mode: subagent
 temperature: 0.1
 hidden: true
@@ -14,6 +14,11 @@ permission:
   bash: allow
 ---
 
+<!-- Agent template: preflight-auditor
+     description: Audits ONE artifact (requirements set, plan, or document) against ONE assigned dimension cluster from the preflight skill's 13-dimension scan. Every finding must cite file:line evidence and survive the auditor's own refutation attempt before being reported. Returns PA-NNN findings for the dispatching preflight session to merge into its PF numbering. Read-only. Dispatched by the preflight skill's clustered fan-out.
+     See agents/ for the OpenCode agent definition files generated from this template.
+     Do not add YAML frontmatter here — use install_agents.py to generate agent files. -->
+
 You audit exactly ONE artifact against exactly ONE dimension cluster, via an audit packet (the
 artifact or its path, the assigned cluster with its dimensions, the original goal, the smallest
 viable design, relevant approved complexity decisions, and any codebase context the dimensions

package/agents/security-auditor.md

@@ -1,8 +1,8 @@
+---
 # Generated by CodeOps install_agents.py
 # Role: security-auditor | Template: security-auditor
 # Do not edit this file manually — regenerate with: install_agents.py
----
-description: Audits ONE completed CodeOps phase diff against the union of the repo's active security-profile checklists (owasp-web, auth-protocol, financial-integrity, tenant-isolation, mcp-agent) in a single dispatch. Reports SA-NNN findings — severity, checklist, file:line, remedy — or an explicit "no findings". Read-only: never edits, fixes, or commits. Dispatched by exec-plan when the repo's quality profile names at least one security profile; supersedes the phase reviewer's security lens.
+description: "Audits ONE completed CodeOps phase diff against the union of the repo's active security-profile checklists (owasp-web, auth-protocol, financial-integrity, tenant-isolation, mcp-agent) in a single dispatch. Reports SA-NNN findings \u2014 severity, checklist, file:line, remedy \u2014 or an explicit \"no findings\". Read-only: never edits, fixes, or commits. Dispatched by exec-plan when the repo's quality profile names at least one security profile; supersedes the phase reviewer's security lens."
 mode: subagent
 temperature: 0.1
 hidden: true
@@ -14,6 +14,11 @@ permission:
   bash: allow
 ---
 
+<!-- Agent template: security-auditor
+     description: Audits ONE completed CodeOps phase diff against the union of the repo's active security-profile checklists (owasp-web, auth-protocol, financial-integrity, tenant-isolation, mcp-agent) in a single dispatch. Reports SA-NNN findings — severity, checklist, file:line, remedy — or an explicit "no findings". Read-only: never edits, fixes, or commits. Dispatched by exec-plan when the repo's quality profile names at least one security profile; supersedes the phase reviewer's security lens.
+     See agents/ for the OpenCode agent definition files generated from this template.
+     Do not add YAML frontmatter here — use install_agents.py to generate agent files. -->
+
 You security-audit exactly ONE completed phase of work, via an audit packet (the phase diff, the
 phase's task and Deliverable lines, the repo's active security profiles, the profile excerpt,
 and the verify command with its last result). You run ONCE per phase with the union of every

package/agents/semantics-reviewer.md

@@ -1,8 +1,8 @@
+---
 # Generated by CodeOps install_agents.py
 # Role: semantics-reviewer | Template: semantics-reviewer
 # Do not edit this file manually — regenerate with: install_agents.py
----
-description: Reviews compiler, language, protocol, or other formal-semantics changes for completeness, internal consistency, and preservation across phases.
+description: "Reviews compiler, language, protocol, or other formal-semantics changes for completeness, internal consistency, and preservation across phases."
 mode: subagent
 temperature: 0.1
 hidden: true
@@ -12,6 +12,11 @@ permission:
   bash: deny
 ---
 
+<!-- Agent template: semantics-reviewer
+     description: Reviews compiler, language, protocol, or other formal-semantics changes for completeness, internal consistency, and preservation across phases.
+     See agents/ for the OpenCode agent definition files generated from this template.
+     Do not add YAML frontmatter here — use install_agents.py to generate agent files. -->
+
 Review exactly the supplied semantic specification or implementation packet. Trace behavior across syntax/decoding, name or identity resolution, typing/validation, intermediate representations, evaluation/lowering, optimization/transformation, diagnostics, serialization, and compatibility as applicable. Seek ambiguous rules, non-total behavior, phase disagreement, unsound transformations, nondeterminism, invalid recovery, and diagnostics that expose implementation accidents. Use counterexamples and minimal programs/messages to falsify the claimed semantics. Cite evidence and return surviving findings with severity, example, affected phases, and resolution, or an explicit clean result. Remain read-only.
 
 - **Workspace hygiene (non-negotiable).** Temporary artifacts you create — logs, diffs, patches,

package/agents/spec-test-author.md

@@ -1,8 +1,8 @@
+---
 # Generated by CodeOps install_agents.py
 # Role: spec-test-author | Template: spec-test-author
 # Do not edit this file manually — regenerate with: install_agents.py
----
-description: Writes specification tests (*.spec.test.*) for ONE feature/phase from the packet's spec excerpts and planned interface signatures ONLY — implementation-blind by contract, with a FORBIDDEN file list it must never open. Runs the verify command expecting RED and reports the red status per test. Never weakens an expectation to ease authoring. Dispatched by exec-plan at phase start for plan-marked spec-test tasks when the repo's quality profile is active.
+description: "Writes specification tests (*.spec.test.*) for ONE feature/phase from the packet's spec excerpts and planned interface signatures ONLY \u2014 implementation-blind by contract, with a FORBIDDEN file list it must never open. Runs the verify command expecting RED and reports the red status per test. Never weakens an expectation to ease authoring. Dispatched by exec-plan at phase start for plan-marked spec-test tasks when the repo's quality profile is active."
 mode: subagent
 temperature: 0.1
 hidden: true
@@ -14,6 +14,11 @@ permission:
   bash: allow
 ---
 
+<!-- Agent template: spec-test-author
+     description: Writes specification tests (*.spec.test.*) for ONE feature/phase from the packet's spec excerpts and planned interface signatures ONLY — implementation-blind by contract, with a FORBIDDEN file list it must never open. Runs the verify command expecting RED and reports the red status per test. Never weakens an expectation to ease authoring. Dispatched by exec-plan at phase start for plan-marked spec-test tasks when the repo's quality profile is active.
+     See agents/ for the OpenCode agent definition files generated from this template.
+     Do not add YAML frontmatter here — use install_agents.py to generate agent files. -->
+
 You author the specification tests for exactly ONE feature or phase, via a spec packet (spec
 excerpts, the expected test cases, planned interface signatures from the plan documents, the
 repo's test framework and conventions, the FORBIDDEN implementation-file list, and the verify

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-codeops",
-  "version": "2.0.3",
+  "version": "2.1.0",
   "description": "Specification-first engineering for complex systems — CodeOps plugin for OpenCode",
   "type": "module",
   "engines": {

package/scripts/fixtures/catalog-executor.golden.md

@@ -1,8 +1,8 @@
+---
 # Generated by CodeOps install_agents.py
 # Role: executor | Template: plan-task-executor
 # Do not edit this file manually — regenerate with: install_agents.py
----
-description: CodeOps plan-task-executor agent
+description: "Executes one dispatched lower-sensitivity unit \u2014 normally a whole phase, occasionally a single task \u2014 from a CodeOps exec-plan. Implements code, writes/updates tests, runs the project verify command, reports pass/fail per task. Use for trivial and standard phases when a cheaper model than the session's is warranted."
 mode: subagent
 temperature: 0.1
 hidden: true
@@ -15,6 +15,7 @@ permission:
 ---
 
 <!-- Agent template: plan-task-executor
+     description: Executes one dispatched lower-sensitivity unit — normally a whole phase, occasionally a single task — from a CodeOps exec-plan. Implements code, writes/updates tests, runs the project verify command, reports pass/fail per task. Use for trivial and standard phases when a cheaper model than the session's is warranted.
      See agents/ for the OpenCode agent definition files generated from this template.
      Do not add YAML frontmatter here — use install_agents.py to generate agent files. -->
 

package/scripts/install_agents.py

@@ -434,13 +434,18 @@ def build_agent_frontmatter(
     permissions: dict[str, str],
     sandbox: Optional[str],
 ) -> str:
-    """Construct the OpenCode agent YAML frontmatter block."""
+    """Construct the OpenCode agent YAML frontmatter block.
+
+    The opening `---` delimiter must be the file's first line: OpenCode parses
+    agent frontmatter only when the file begins with it. The CodeOps provenance
+    banner therefore lives inside the block as YAML comment lines.
+    """
     lines = [
+        "---",
         CODEOPS_MARKER,
         f"# Role: {role} | Template: {template_name}",
         "# Do not edit this file manually — regenerate with: install_agents.py",
-        "---",
-        f"description: {description}",
+        f"description: {json.dumps(description)}",
         "mode: subagent",
     ]
     if model:
@@ -457,12 +462,20 @@ def build_agent_frontmatter(
 
 
 def load_template_description(plugin_root: Path, template_name: str) -> str:
-    """Extract description from an agent template's original frontmatter."""
+    """Extract the description embedded in a template's provenance comment.
+
+    Templates deliberately carry no YAML frontmatter; the description lives as a
+    `description:` line inside the leading HTML comment and is copied verbatim
+    into the generated agent's frontmatter. The search is scoped to that comment
+    so body text can never be mistaken for the description.
+    """
     path = plugin_root / "agent-templates" / f"{template_name}.md"
     if not path.exists():
         return f"CodeOps {template_name} agent"
     content = path.read_text(encoding="utf-8")
-    m = re.search(r"^description:\s*(.+)$", content, re.MULTILINE)
+    comment = re.match(r"^<!--([\s\S]*?)-->", content)
+    scope = comment.group(1) if comment else content
+    m = re.search(r"^\s*description:\s*(.+)$", scope, re.MULTILINE)
     return m.group(1).strip() if m else f"CodeOps {template_name} agent"
 
 
@@ -506,6 +519,14 @@ def generate_agent_file(
 def is_codeops_generated(path: Path) -> bool:
     """Return True if the file was generated by this script (has the CodeOps marker).
 
+    Two layouts are recognized so existing installs upgrade in place instead of
+    being skipped as hand-authored:
+
+    - current: the file opens with `---` and the marker appears within the
+      first eight lines (OpenCode parses the block only in this layout);
+    - legacy: the marker is the first line and the frontmatter block follows
+      the provenance banner.
+
     Unreadable or non-UTF-8 files are treated as not generated, so a corrupt
     file is reported as a state instead of crashing the caller.
 
@@ -513,20 +534,28 @@ def is_codeops_generated(path: Path) -> bool:
         path: Candidate generated agent file.
 
     Returns:
-        True when the first line carries the CodeOps ownership marker.
+        True when the file carries the CodeOps ownership marker in either layout.
     """
     if not path.is_file():
         return False
     try:
-        first_line = path.read_text(encoding="utf-8").split("\n", 1)[0]
+        lines = [line.strip() for line in path.read_text(encoding="utf-8").split("\n", 8)[:8]]
     except (OSError, UnicodeDecodeError):
         return False
-    return first_line.strip() == CODEOPS_MARKER
+    if not lines:
+        return False
+    if lines[0] == CODEOPS_MARKER:
+        return True
+    return lines[0] == "---" and CODEOPS_MARKER in lines[1:]
 
 
 def generate_custom_agent(plugin_root: Path, role: str, brief: dict, role_config: dict) -> str:
     """Generate the full content of a specialist agent file.
 
+    The file opens with the `---` frontmatter delimiter because OpenCode parses
+    agent frontmatter only when the file begins with it; the provenance banner
+    is emitted inside the block as YAML comments.
+
     The generated file embeds two things: the generic template contract chosen
     by the brief's `kind`, and the project brief body. Text that can contain
     arbitrary characters (the description and a routing model pin) is written
@@ -582,10 +611,10 @@ def generate_custom_agent(plugin_root: Path, role: str, brief: dict, role_config
         permissions["edit"] = "deny"
 
     lines = [
+        "---",
         CODEOPS_MARKER,
         f"# Role: {role} | Template: {template_name}",
         "# Do not edit this file manually — regenerate with: install_agents.py",
-        "---",
         f"description: {json.dumps(brief['description'])}",
         "mode: subagent",
     ]
@@ -708,7 +737,7 @@ def generated_custom_template(path: Path) -> Optional[str]:
     if not is_codeops_generated(path):
         return None
     try:
-        lines = path.read_text(encoding="utf-8").split("\n", 3)[:3]
+        lines = path.read_text(encoding="utf-8").split("\n", 6)[:6]
     except (OSError, UnicodeDecodeError):
         return None
     for line in lines:
@@ -868,6 +897,10 @@ def run_sync_agents_md(project: Path, dry_run: bool) -> int:
 def run_check(project: Path, plugin_root: Path, roles: list, routing_roles: dict) -> int:
     """Report catalog, custom, orphan, and AGENTS.md states.
 
+    Catalog roles are additionally content-compared against the generator
+    output, so a generated file whose layout or fields no longer match is
+    reported as STALE instead of silently passing the check.
+
     Args:
         project: Resolved project root.
         plugin_root: Package root containing `agent-templates/`.
@@ -882,10 +915,27 @@ def run_check(project: Path, plugin_root: Path, roles: list, routing_roles: dict
     issues: list[str] = []
     for role in roles:
         out_path = agents_dir / f"{role}.md"
+        if out_path.is_symlink():
+            issues.append(f"HAND-AUTHORED (skip): {out_path}")
+            continue
         if not out_path.exists():
             issues.append(f"MISSING: {out_path}")
-        elif not is_codeops_generated(out_path):
+            continue
+        if not is_codeops_generated(out_path):
             issues.append(f"HAND-AUTHORED (skip): {out_path}")
+            continue
+        try:
+            expected = generate_agent_file(plugin_root, role, routing_roles.get(role, {}))
+        except (BriefError, OSError, UnicodeDecodeError) as exc:
+            issues.append(f"INVALID: {role} — {exc}")
+            continue
+        try:
+            current = out_path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            issues.append(f"STALE: {role}")
+            continue
+        if current != expected:
+            issues.append(f"STALE: {role}")
 
     briefs, errors = collect_briefs(project)
     issues.extend(errors)

package/skills/analyze-agents/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: analyze-agents
+description: Run the project-level specialist check on demand. Reads the repository's requirements, plans, findings ledgers, and manifests directly (no script), applies the specialist-agent detection criteria, presents at most two evidence-backed lightweight proposals or a None with evidence, and records the check state consumed by the analyze-project coverage line.
+---
+
+# analyze-agents
+
+Run this check to re-evaluate whether a project would benefit from a project-specific specialist
+subagent — on request, or because `analyze-project` reported the coverage as due. This skill is the
+execution surface for the detection criteria in
+[`../../_shared/specialist-agents.md`](../../_shared/specialist-agents.md); it reads the
+repository's own artifacts and never invokes a script.
+
+## Evidence
+
+Read these sources for the current project. All paths are layout-aware per
+[`../../_shared/layout-convention.md`](../../_shared/layout-convention.md): flat `plans/` or nested
+`codeops/features/<f>/plans/`.
+
+- requirements and plan documents — domain/lens tags and scope history;
+- per-plan findings ledgers (`05-findings.md`) — finding-area recurrence;
+- manifests (`package.json`, `pyproject.toml`, `go.mod`, and similar) — specialized framework,
+  DSL, codegen, or protocol signals;
+- existing `codeops/specialists/` briefs and `codeops/codeops.json` routing roles —
+  deduplicate against installed specialists;
+- `codeops/specialist-check.json` — the prior check state.
+
+## Detection flow
+
+1. Collect the evidence sources above.
+2. Apply the detection criteria and disqualifiers from the protocol document: a candidate needs
+   evidenced strong signal(s) and no disqualifier.
+3. Recurrence anchor: one area appearing in at least two plans or three findings ranks as a strong
+   signal; thresholds anchor judgment, not hard gates.
+4. Present at most two candidates in one batch as **lightweight proposals** — role slug, kind, a
+   one-line capability, evidence with `file:line`, and the smallest alternative with why it is
+   insufficient — or record `None` with evidence.
+5. Write the check state (below) on every run, including a `None` outcome.
+6. Hand-off: on user interest, hand off to the `setup-routing` flow for creation. Never create or
+   modify agent files, briefs, routing policy, or `AGENTS.md`.
+
+## Check state
+
+Write `codeops/specialist-check.json` (project-level in both layouts; create the `codeops/`
+directory lazily when it does not exist):
+
+```json
+{
+  "checkedAt": "<ISO-8601 timestamp>",
+  "plans": ["<plan folder>", "<plan folder>"]
+}
+```
+
+The `plans` list contains the plan folders present at check time (layout-aware). Consumers treat
+absent, unreadable, or malformed state as **never checked** and recommend a run — fail loud, never
+silent.
+
+## Output
+
+A short human summary: the candidate proposals in the lightweight format above, or `None` with
+evidence, plus the state write result. The state file is the machine-readable artifact; there is no
+separate JSON output mode.
+
+## Degradation
+
+- Missing findings ledger: the output states that the ledger was missing and the check ran on
+  reduced evidence (documents and manifests only).
+- Malformed ledger rows: skip the row with a note; never guess its fields.
+- Empty repository (no plans or requirements): record `None` with evidence and still write the
+  check state.
+
+---
+
+> **Workspace hygiene (non-negotiable):** put every temporary artifact this run creates in
+> `$CODEOPS_TMPDIR` (fallback: the OS temp directory), never in the repository, and delete them
+> all before reporting completion. Never delete user files, versioned artifacts, worktrees, or
+> another session's temporary files. Full rules:
+> [_shared/workspace-hygiene.md](../../_shared/workspace-hygiene.md).

package/skills/analyze-project/SKILL.md

@@ -24,7 +24,7 @@ description: Analyze the current repository and create or refresh concise CodeOp
 7. On a non-integration branch, preview changes to repository-wide guidance and ask before writing unless repository policy explicitly permits branch-local updates.
 8. In compact mode, remove duplication and stale generated detail from the managed section only. Flag suspected hand-authored bloat; never silently rewrite it.
 9. Validate every recorded command or mark it explicitly unverified.
-10. When a specialization signal is strong and no specialist covers it, report the candidate with evidence and recommend the `setup-routing` creation flow ([../../_shared/specialist-agents.md](../../_shared/specialist-agents.md)); never write agent files here. Preserve the `<!-- CODEOPS-SPECIALISTS:START -->` / `<!-- CODEOPS-SPECIALISTS:END -->` block byte-for-byte when refreshing the managed section.
+10. Specialist coverage: read `codeops/specialist-check.json` when present and include a `Specialist coverage:` line in the managed section — `up to date (<YYYY-MM-DD>)` (from `checkedAt`) when the recorded plan set matches the current one; `check due — run analyze-agents` otherwise; when the state is absent or corrupt, render `check due — run analyze-agents (never checked)`. The `analyze-agents` skill runs the check (criteria: [../../_shared/specialist-agents.md](../../_shared/specialist-agents.md)); when a specialization signal is strong and no specialist covers it, report the candidate with evidence and recommend the `setup-routing` creation flow; never write agent files here. Preserve the `<!-- CODEOPS-SPECIALISTS:START -->` / `<!-- CODEOPS-SPECIALISTS:END -->` block byte-for-byte when refreshing the managed section.
 
 Keep `AGENTS.md` small. Operational routing belongs in `codeops/codeops.json` or `opencode.json`, not prose.
 

package/skills/exec-plan/SKILL.md

@@ -229,9 +229,9 @@ links to them, never restates them.
 The flow: the protocol records a phase-start ref when the phase begins; after the phase's last
 task verifies, the correctness reviewer and any active auditors are dispatched **in parallel** on
 the phase diff, their findings are merged and presented in severity-grouped batches, and each
-ruling is recorded in the durable finding artifact. Specialist roles listed in the plan's
-`## Specialist Agents` table dispatch per `_shared/quality-profile.md`; an unavailable specialist
-falls back to a generic packet and the fallback is reported.
+ruling is recorded in the plan's findings ledger (`05-findings.md`). Specialist roles listed in
+the plan's `## Specialist Agents` table dispatch per `_shared/quality-profile.md`; an unavailable
+specialist falls back to a generic packet and the fallback is reported.
 
 > **🚨 Finding gate (load-bearing).** In normal mode, 🔴 CRITICAL and 🟠 MAJOR findings PAUSE
 > execution for the user's ruling in ALL commit modes. With active auto-design, select and record

package/skills/exec-plan/execution-protocol.md

@@ -199,9 +199,17 @@ whole-task diff. Activation rules, packets, supersession, and caps are defined i
    `[!]`, preserve the diff without marking it verified, and switch to the full standalone-plan
    path. The new `00-ambiguity-register.md` owns the packet and decision. Resume only after that
    plan's gates pass.
-4. **Record decisions durably** in the finding artifact after each ruling batch. When the user
-   approves larger machinery, also append a `Technical (complexity escalation)` runtime AR with
-   every approval-evidence field required by the shared gate; the RV finding references that AR.
+4. **Record decisions durably** in the plan's findings ledger after each ruling batch. The ledger
+   is `plans/<plan>/05-findings.md` (flat) or
+   `codeops/features/<f>/plans/<plan>/05-findings.md` (nested), created lazily on first use, with a
+   one-line title and one compact row per batch:
+   `| Finding | Phase | Severity | Area | Ruling |` — finding ids use the review prefixes
+   `RV-`/`SA-`/`PE-`/`SR-` (for example `RV-001`), followed by the phase number,
+   `CRITICAL`/`MAJOR`/`MINOR`, a path or domain token, and
+   `fixed`/`accepted`/`deferred`/`dismissed`; identifiers and area tokens only, never prose. Task
+   mini-plans keep their ledger in their own plan folder. When the user approves larger machinery,
+   also append a `Technical (complexity escalation)` runtime AR with every approval-evidence field
+   required by the shared gate; the RV finding references that AR.
 5. **Accepted fixes:** implement → verify → follow-up commit per the commit mode. If any 🔴/🟠
    fix was applied, dispatch ONE re-review scoped to the fix diff — never a third pass. A fix
    the re-review still rejects is reported. Normal mode returns the ruling to the user; active

package/skills/make-plan/SKILL.md

@@ -71,7 +71,7 @@ with active scope exploration.
 
 Re-run [../../references/domains/selection.md](../../references/domains/selection.md) before component decomposition. Requirements-stage lens selection is evidence, not a permanent assumption. Apply every selected lens to specifications, acceptance criteria, failure narratives, and test strategy.
 
-After lens selection and phase decomposition, run the specialist-gap check in [../../_shared/specialist-agents.md](../../_shared/specialist-agents.md). Record the outcome in `00-index.md` under `## Specialist Agents` — always, including `None` with its reason and evidence. Candidate creation is reserved authority: `--auto-design` may not approve it, and approved roles are created through `setup-routing`.
+After lens selection and phase decomposition, run the specialist-gap check in [../../_shared/specialist-agents.md](../../_shared/specialist-agents.md). The `analyze-agents` skill executes the same detection flow on demand; the manual criteria in the linked protocol document remain the fallback when the skill is unavailable. Record the outcome in `00-index.md` under `## Specialist Agents` — always, including `None` with its reason and evidence. In the final plan summary, include a `Specialist check:` line — `None — <evidence>` or the candidate names. Candidate creation is reserved authority: `--auto-design` may not approve it, and approved roles are created through `setup-routing`.
 
 A folder `plans/<feature-name>/` containing:
 
@@ -274,6 +274,8 @@ Report what was created:
 
 **Summary:** Total Phases: X · Total Sessions: X · Estimated Time: X–X hours
 
+**Specialist check:** [None — evidence / candidate names]
+
 **To begin implementation:** use the exec-plan skill on `[feature-name]`.
 ```
 

package/skills/make-plan/quality-checklist.md

@@ -7,6 +7,7 @@ Run this before finalizing the plan documents. The **Specification-First Testing
 - [ ] All affected components identified
 - [ ] All scope decisions documented
 - [ ] All dependencies mapped
+- [ ] The `## Specialist Agents` outcome is recorded in `00-index.md` (candidate or `None` with evidence)
 - [ ] Every planned item traces to the confirmed scope baseline or a user-kept `SE-*` entry
 - [ ] Strict scope contains no optional suggestions; exploration proposals remain non-executable
       until the user chooses `Keep`

package/skills/make-requirements/SKILL.md

@@ -55,7 +55,7 @@ than stored as a second mutable status.
 
 Before discovery, read [../../references/domains/selection.md](../../references/domains/selection.md), select every applicable system lens, and read those lens files completely. Record selected lenses and evidence in the requirements index. Re-evaluate selection when discovery reveals another domain; a financial web service, for example, requires financial, web, distributed/concurrent, and data/migration lenses.
 
-After lens selection and scope confirmation, run the specialist-gap check in [../../_shared/specialist-agents.md](../../_shared/specialist-agents.md). Propose at most two candidates in one batch, each through the Complexity Escalation Gate; creation is reserved authority (`--auto-design` may never approve it). Record the check outcome — including "none" — in the final summary.
+After lens selection and scope confirmation, run the specialist-gap check in [../../_shared/specialist-agents.md](../../_shared/specialist-agents.md). The `analyze-agents` skill executes the same detection flow on demand; the manual criteria in the linked protocol document remain the fallback when the skill is unavailable. Surface at most two candidates in one batch as lightweight proposals (that document's §Proposals and the creation gate); the Complexity Escalation Gate and the reserved-authority approval apply only when the user chooses to proceed to creation (`--auto-design` may never approve it). Record the outcome in the final summary as a `Specialist check:` line — including `Specialist check: None — <evidence>`.
 
 You are NOT a passive interviewer. You are a **domain-aware consultant** that: