opencode-codeops 2.0.3 → 2.0.4

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to CodeOps are recorded here.
 
+## 2.0.4 — 2026-10-09
+
+### 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/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.0.4",
   "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)