opencode-codeops 2.0.4 → 2.1.0

package/CHANGELOG.md

@@ -2,8 +2,56 @@
 
 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)

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/package.json

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

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: