opencode-codeops 1.4.0

package/skills/roadmap/template.md

@@ -0,0 +1,200 @@
+# Roadmap Template & Tracker Reference
+
+Resolve where the roadmap lives via **[../../_shared/layout-convention.md](../../_shared/layout-convention.md)**:
+
+- **Flat layout** (no marker): a single roadmap at `plans/00-roadmap.md` — exactly as before.
+- **Nested layout** (marker present): a **per-feature roadmap** at
+  `codeops/features/<f>/00-roadmap.md` (the template below, scoped to one feature, **plus task
+  rows**) and a **portfolio roadmap** at `codeops/00-roadmap.md` (one row per feature — see
+  [The portfolio roadmap template](#the-portfolio-roadmap-template)).
+
+The per-feature roadmap and the flat roadmap share the same template, columns, and legend; use it
+verbatim when creating either. The portfolio is a separate, higher-altitude template.
+
+## The single / per-feature roadmap template
+
+````markdown
+# Roadmap: [Feature-Set Name]
+
+> **Feature-Set**: [Feature-Set Name]
+> **Status**: In Progress
+> **Created**: [YYYY-MM-DD]
+> **Last Updated**: [YYYY-MM-DD HH:MM]
+> **Progress**: [Done RDs] / [Total RDs] ([Z]%)
+> **CodeOps Artifact Schema**: 1
+
+## Legend
+
+⬜ Backlog · ✏️ RD Drafted · 🔎 RD Preflighted · 📋 Plan Created · 🔬 Plan Preflighted · 🔄 Executing · ✅ Done · ⛔ Blocked · ⏸️ Deferred
+
+## Tracker
+
+| ID | Title | RD | Plan | Stage | Status | Last Updated | Depends-on / Blocker |
+|----|-------|----|------|-------|--------|--------------|----------------------|
+| RD-01 | [Title] | [link] | [link] | Done | ✅ | [date] | — |
+| RD-02 | [Title] | [link] | [link] | Executing | 🔄 | [date] | — |
+| RD-03 | [Title] | [link] | — | Blocked (was: RD Preflighted) | ⛔ | [date] | waiting on DEF-1 |
+| ↳ DEF-1 | [Discovered dependency] | — | [link] | Plan Created | 📋 | [date] | blocks RD-03 |
+| RD-04 | [Title] | — | — | Backlog | ⬜ | [date] | — |
+````
+
+## Header fields
+
+- **Feature-Set** — display name; the slug form is the `plans/_archive/<slug>/` folder name on archive.
+- **Status** — `In Progress` while active; `Archived` once `archive_roadmap` runs.
+- **Created** / **Last Updated** — `Last Updated` bumps on every transition.
+- **Progress** — `[Done RDs] / [Total RDs] ([Z]%)`; counts only top-level `RD-*` rows that reached
+  `Done`. `T-*` task rows and `↳ DEF-n` sub-rows never count toward the fraction. A Progress value
+  that is **not** this computed shape (e.g. `n/a`, or `history archived (no active RD tracker)`) is
+  treated as hand-maintained: the sync engine preserves it verbatim and does not touch it. A
+  computed value may carry a trailing ` · <note>` annotation (e.g. `2 / 2 (100%) · hardening done`);
+  the engine refreshes the count and keeps the ` · …` suffix.
+- **CodeOps Artifact Schema** — the artifact-schema stamp (currently `1`).
+
+## Tracker columns
+
+| Column | Meaning |
+|--------|---------|
+| ID | `RD-NN` for a top-level requirement; `T-NN` for a lightweight task (nested layout — separate per-feature namespace, see the task-lane spec); `↳ DEF-n` for a nested discovered dependency. |
+| Title | Short human label. |
+| RD | Relative link to `requirements/RD-*.md`, or `—` if not yet drafted. |
+| Plan | Relative link to the plan folder's `00-index.md`, or `—` if no plan yet. |
+| Stage | One of the 9 lifecycle states (text form). A `Blocked` row records its prior stage in-cell — `Blocked (was: <stage>)` — so unblocking never depends on memory. |
+| Status | The matching emoji for the stage (see legend). |
+| Last Updated | Date (or date + time) of the last change to this row. |
+| Depends-on / Blocker | Terse. Name a planned prerequisite (`depends on RD-03`) or, for a `Blocked` row, the `DEF-n` being waited on — a short phrase, never a paragraph. |
+
+Links are relative to the roadmap file itself. Flat layout (`plans/00-roadmap.md`): RDs are
+`../requirements/RD-NN-*.md`, plans are `<plan>/00-index.md`. Nested layout
+(`codeops/features/<f>/00-roadmap.md`): RDs are `requirements/RD-NN-*.md`, plans are
+`plans/<plan>/00-index.md`.
+
+## Row ordering & discipline
+
+- **Order rows by dependency** — put prerequisites above the rows that depend on them, so the list
+  is worked top-to-bottom, one row at a time, until the roadmap is done. Capture a *planned*
+  dependency terse in the `Depends-on / Blocker` cell (e.g. `depends on RD-01`); a *discovered*
+  blocker becomes a `↳ DEF-n` sub-row with `waiting on DEF-n` in the cell.
+- **Keep it a table.** A roadmap is only its table (the per-feature/flat roadmap is header + Legend
+  + Tracker; the portfolio adds Features + Archived). A row's cells are short status phrases, never
+  narrative — per-item history and rationale live in the plan folder and git, not here. There is no
+  running-notes log; a stage regression is explained in the git commit that makes it.
+
+## Worked example
+
+```markdown
+# Roadmap: Billing Platform
+
+> **Feature-Set**: Billing Platform
+> **Status**: In Progress
+> **Created**: 2026-05-01
+> **Last Updated**: 2026-05-14 16:20
+> **Progress**: 1 / 4 (25%)
+> **CodeOps Artifact Schema**: 1
+
+## Legend
+
+⬜ Backlog · ✏️ RD Drafted · 🔎 RD Preflighted · 📋 Plan Created · 🔬 Plan Preflighted · 🔄 Executing · ✅ Done · ⛔ Blocked · ⏸️ Deferred
+
+## Tracker
+
+| ID | Title | RD | Plan | Stage | Status | Last Updated | Depends-on / Blocker |
+|----|-------|----|------|-------|--------|--------------|----------------------|
+| RD-01 | Invoicing core | [RD-01](../requirements/RD-01-invoicing.md) | [invoicing](invoicing/00-index.md) | Done | ✅ | 2026-05-10 | — |
+| RD-02 | Payment gateway | [RD-02](../requirements/RD-02-payments.md) | — | Blocked (was: RD Drafted) | ⛔ | 2026-05-14 | waiting on DEF-1 |
+| ↳ DEF-1 | Secrets vault integration | — | [vault](vault/00-index.md) | Executing | 🔄 | 2026-05-14 | blocks RD-02 |
+| RD-03 | Dunning emails | [RD-03](../requirements/RD-03-dunning.md) | — | RD Preflighted | 🔎 | 2026-05-12 | — |
+| RD-04 | Usage metering | — | — | Backlog | ⬜ | 2026-05-01 | — |
+```
+
+Here RD-02 is `Blocked` by the nested `DEF-1` sub-row; once DEF-1 reaches `Done`,
+RD-02 resumes from its prior stage.
+
+In a **nested-layout** repo this same roadmap lives at `codeops/features/<f>/00-roadmap.md` and
+may also carry `T-NN` **task rows** beside its RD rows (a trivial task is just a row; a non-trivial
+one links a single mini-plan). RD and `T` ids are separate per-feature namespaces and never collide.
+
+## Open follow-ons (optional)
+
+When every `RD-*` row is `Done` but post-completion work is still outstanding, record it in an
+optional `## Open follow-ons` section **below the Tracker** — so the feature reads as "shipped, with
+tail work" rather than either fully done or artificially incomplete:
+
+```markdown
+## Open follow-ons
+
+| Item | Scope | Stage | Status |
+|------|-------|-------|--------|
+| `usage-export` | Production usage export, deferred post-launch | Backlog | ⬜ no plan yet |
+```
+
+The table's **last column must be `Status`**. A follow-on is *open* when its Status cell contains no
+✅. While any follow-on is open, the sync engine rolls the feature up to `🔄` (not `✅`) and excludes
+it from the portfolio `Features` done count — but follow-on rows **never** count toward the RD
+fraction (a feature with 2/2 RDs Done and an open follow-on still reads `2/2 RDs`). A section whose
+table is not `Status`-last is ignored. Once every follow-on row is ✅ (or the section is removed),
+the feature rolls up `✅` normally.
+
+---
+
+## The portfolio roadmap template
+
+> **Nested layout only.** Lives at `codeops/00-roadmap.md`. One row per feature in the repo; it is
+> a *derived summary* of the per-feature roadmaps, never the detailed record. Each feature's Stage
+> Summary, Progress, and Status roll up from that feature's own roadmap. Roll-up precedence: any
+> blocked → ⛔; all RDs Done with an open follow-on → 🔄; all RDs Done and none open → ✅; any
+> executing → 🔄; else ⬜. The portfolio **auto-cascades**: every per-feature stage transition
+> immediately updates that feature's portfolio row (see [stage-hooks.md](stage-hooks.md)).
+
+````markdown
+# Portfolio Roadmap: [Repo / Product Name]
+
+> **Status**: Active
+> **Last Updated**: [YYYY-MM-DD HH:MM]
+> **Features**: [Done] / [Total] done
+> **CodeOps Artifact Schema**: 1
+
+## Legend
+
+⬜ Backlog · 🔄 In progress · ✅ Done · ⛔ Blocked · ⏸️ Deferred · 📦 Archived
+
+## Features
+
+| Feature | Roadmap | Stage Summary | Progress | Status | Last Updated |
+|---------|---------|---------------|----------|--------|--------------|
+| billing | [→](features/billing/00-roadmap.md) | 2 RDs · 1 plan executing | 1/2 RDs | 🔄 | 2026-06-29 |
+| auth    | [→](features/auth/00-roadmap.md)    | backlog | 0/3 RDs | ⬜ | 2026-06-20 |
+
+## Archived
+
+| Feature | Roadmap | Completed | Last Updated |
+|---------|---------|-----------|--------------|
+| onboarding | [→](_archive/onboarding/00-roadmap.md) | 4/4 RDs | 2026-05-30 |
+````
+
+### Portfolio header fields
+
+- **Status** — `Active` while the repo has live features; informational.
+- **Last Updated** — bumps on every cascade.
+- **Features** — `[Done] / [Total] done`, counting feature rows whose rolled-up Status is ✅. Rows
+  whose `Progress` is hand-maintained (e.g. `n/a`) are not engine-computed and are excluded from
+  both totals. A trailing ` (…)` annotation on this value is preserved when the count is refreshed.
+
+### Portfolio columns
+
+| Column | Meaning |
+|--------|---------|
+| Feature | The feature folder name under `codeops/features/`. |
+| Roadmap | Relative link to that feature's `00-roadmap.md`. |
+| Stage Summary | Short derived phrase (e.g. "2 RDs · 1 plan executing"). |
+| Progress | Derived count of `RD-*` rows (e.g. "1/2 RDs"), optionally with a ` · …` annotation. A hand-maintained value such as `n/a` is preserved by the engine, which then leaves this row's Status untouched. |
+| Status | Rolled-up emoji (🔄 / ✅ / ⛔ / ⬜ / ⏸️); not re-rolled for a row whose Progress is hand-maintained. |
+| Last Updated | Date of the last cascade to this row. |
+
+### Archived section
+
+Archiving a feature **moves** its row here (📦) — never deletes it (AR #11). The feature folder is
+`git mv`d to `codeops/_archive/<f>/`, so the Roadmap link points under `_archive/`.
+
+A fresh-scaffolded or just-migrated repo seeds this portfolio automatically (the `setup-codeops`
+migration writes a one-feature portfolio; refine it with `update`).

package/skills/setup-codeops/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: setup-codeops
+description: >-
+  Sets up or upgrades CodeOps in the current git repo. It scaffolds a fresh nested codeops/ layout, auto-migrates a flat requirements/ + plans/ layout, and detects obsolete traceability.json workflow-state graphs in an existing nested project. Use when the user says "setup-codeops", "/setup-codeops", "set up codeops", "initialize codeops", "upgrade existing codeops", "migrate to the nested layout", or "scaffold the codeops structure". Supports --dry-run and unattended --yes. Every migration previews deterministically, refuses unsafe or ambiguous apply, requires clean Git state for writes, and is idempotent. setup-codeops is the SOLE writer of the layout marker.
+---
+
+# CodeOps Layout Setup (`setup-codeops`)
+
+> **CodeOps Artifact Schema**: 1
+
+Set up the CodeOps **nested `codeops/` layout** for the git repo the user is currently in. Run as
+`/codeops:setup-codeops` or the typeable alias `/setup-codeops`. This is the one skill that
+**creates and owns the layout marker** `codeops/.codeops.yml`; every other skill only reads it.
+
+Resolve all paths and the marker schema via **[_shared/layout-convention.md](../../_shared/layout-convention.md)** —
+it is the single source of truth for the layout. Do not re-encode paths here.
+
+## Scope
+
+- **Per-repo only.** One git repo at a time; no cross-repo or portfolio-of-projects work.
+- This skill sets up the *structure*. It never authors requirements, plans, or roadmaps — that is
+  `make-requirements` / `make-plan` / `roadmap`, which then resolve paths via the convention doc.
+
+## Dispatch — detect repo state, then branch
+
+Run inside the repo and detect, in this order:
+
+```
+1. Any codeops/features/*/traceability.json or codeops/_archive/*/traceability.json present
+       → LEGACY WORKFLOW-STATE UPGRADE, even when the layout marker is already present. Follow the
+         nested-project flow in migration.md. Preview with codeops_plan_migrate.py; with --yes,
+         apply only when the preview has no BLOCKED entry, then verify with codeops_plan.py.
+         This check intentionally precedes the marker no-op so re-running setup upgrades an
+         existing project without requiring a separate upgrade prompt.
+2. codeops/.codeops.yml present
+       → already set up. NO-OP for the layout: print a short status report (layout = nested, where
+         things live). BUT if the marker is **missing `integrationBranch`**, BACKFILL it — add that
+         one line (resolved to the repo's integration branch: `origin/HEAD`, else the current branch,
+         else `main`/`master`) without touching any other key; if it is already present, leave it.
+         Never re-scaffold or re-migrate. (Idempotent — a marker that is present and complete → no
+         change; this is the existing-project entry point for parallel-agents support.)
+3. Flat layout detected (requirements/  OR  plans/00-roadmap.md  OR  any plans/<dir>/)
+       → MIGRATE. Follow migration.md: run the engine --dry-run, render the preview, take ONE
+         confirmation, then apply. The engine (scripts/codeops-migrate.sh) owns the algorithm.
+4. Neither
+       → fresh SCAFFOLD. Follow scaffold.md: create the minimal codeops/ skeleton.
+```
+
+If the repo is **not a git repo**, refuse with a clear message (migration needs `git mv`; even a
+fresh scaffold should live in version control) and suggest `git init` first.
+
+## Flags
+
+| Flag | Effect |
+|------|--------|
+| *(none)* | Interactive: scaffold creates the skeleton; either migration previews then asks for one confirmation before applying. |
+| `--dry-run` | Preview only — compute and show what would happen; change **nothing**. |
+| `--yes` | Apply an unblocked migration without confirmation, then verify it. Safety refusals still apply. |
+
+## Migration engines (delegation — do not re-implement)
+
+Flat-to-nested path arithmetic, slug derivation, hazard scanning, dirty-tree refusal,
+path-traversal protection, idempotency, and `git mv` apply live in
+**`scripts/codeops-migrate.sh`** (see [migration.md](migration.md)):
+
+- Preview: `scripts/codeops-migrate.sh --dry-run`
+- Apply:   `scripts/codeops-migrate.sh --yes`
+
+Never re-derive the move map in prose — read it from the engine's output and present it.
+
+Existing nested-project graph removal and Markdown ownership inference live in
+**`scripts/codeops_plan_migrate.py`**. Do not inspect or rewrite graph semantics in the skill:
+
+- Preview: `python3 "${CODEOPS_PLUGIN_ROOT}/scripts/codeops_plan_migrate.py" ./codeops`
+- Apply: `python3 "${CODEOPS_PLUGIN_ROOT}/scripts/codeops_plan_migrate.py" ./codeops --apply`
+- Verify: `python3 "${CODEOPS_PLUGIN_ROOT}/scripts/codeops_plan.py" --root . --json`
+
+On `--yes`, run preview first. Apply only when it exits successfully with no `BLOCKED` entry, then
+run verification. The migrator itself owns clean-tree refusal, all-or-nothing writes, graph
+deletion, and idempotency.
+
+## Reference files
+
+- [scaffold.md](scaffold.md) — the minimal fresh-repo skeleton.
+- [migration.md](migration.md) — flat-layout and legacy workflow-state migration UX.
+- [_shared/layout-convention.md](../../_shared/layout-convention.md) — the layout/path/ID/marker source of truth.
+
+## Grounded Options & Recommendations
+
+When a migration surfaces choices (e.g. an ambiguous slug source, or warnings the user must act
+on), present only **genuinely viable** options, second-guessed and grounded in what the engine
+actually reported, and lead with a recommendation. The user decides; never apply a migration
+without an explicit confirmation (or `--yes`). For consequential choices, apply the
+recommendation-hardening protocol (`_shared/recommendation-hardening.md`).

package/skills/setup-codeops/migration.md

@@ -0,0 +1,106 @@
+# CodeOps Migration UX
+
+## Existing nested project: remove legacy workflow state
+
+Read this section when `setup-codeops` finds `traceability.json` in an active or archived feature,
+including when `codeops/.codeops.yml` already exists. This detection precedes the normal
+already-configured no-op.
+
+1. Preview with:
+
+   ```text
+   python3 "${CODEOPS_PLUGIN_ROOT}/scripts/codeops_plan_migrate.py" ./codeops
+   ```
+
+2. Render every `UPDATE`, `KEEP`, `DELETE`, and `BLOCKED` line. A non-zero preview or any
+   `BLOCKED` entry stops the migration without asking to apply.
+3. Unless `--yes` was passed, ask once whether to apply the displayed Markdown updates and graph
+   deletions.
+4. Apply with `codeops_plan_migrate.py ./codeops --apply`. The engine refuses dirty Git state and
+   performs no writes unless every mapping is unambiguous.
+5. Verify with:
+
+   ```text
+   python3 "${CODEOPS_PLUGIN_ROOT}/scripts/codeops_plan.py" --root . --json
+   ```
+
+   Then run the repository's normal verification command. Report plan coverage, preserved task
+   progress, deleted graphs, and any residual risk. Do not advance roadmap lifecycle state.
+
+Re-running after success must report no graph migration and continue to the normal configured
+project status. `--yes` skips only the confirmation; it never bypasses ambiguity or Git-safety
+checks.
+
+## Flat → nested layout
+
+> Read this when `setup-codeops` detects an existing **flat layout** (a `requirements/` dir, a
+> `plans/00-roadmap.md`, or any `plans/<dir>/`). Resolve paths via
+> [_shared/layout-convention.md](../../_shared/layout-convention.md).
+
+## Division of labour (PF-003 — do not blur this)
+
+- **`scripts/codeops-migrate.sh`** owns the *algorithm*: slug derivation + sanitization, the move
+  map, the hazard scan, the dirty-tree refusal, the path-traversal slug guard, idempotency, and
+  the `git mv` apply. It is deterministic and unit-tested (`scripts/migration-check.sh`).
+- **This skill** owns the *UX*: run the engine in dry-run, render its preview, take **one**
+  confirmation, then invoke the engine to apply, and report the result. **Never re-implement the
+  path arithmetic in prose** — read the move map from the engine and present it.
+
+## Flow
+
+1. **Preview.** Run:
+   ```
+   scripts/codeops-migrate.sh --dry-run
+   ```
+   The engine prints the `SLUG:` line (with its source), the `MOVE`/`CREATE` map, and any `WARN`
+   lines. If it exits non-zero, surface its message and stop:
+   - *not a git repo* → suggest `git init`.
+   - *dirty working tree* → ask the user to commit or stash first, then re-run.
+   - *already migrated* (marker present) → report the no-op; nothing to do.
+
+2. **Render the preview** to the user, faithfully reflecting the engine output: the feature slug
+   and where it came from (roadmap header vs. repo/dir name), a count and summary of the moves,
+   the created control files (`codeops/codeops.json`, `codeops/.codeops.yml`, and
+   `codeops/00-roadmap.md`), and every warning.
+
+3. **Confirm (once).** Ask a single yes/no: apply this migration with `git mv`? Skip this prompt
+   only when the user passed `--yes`.
+
+4. **Apply.** On confirmation, run:
+   ```
+   scripts/codeops-migrate.sh --yes
+   ```
+   The engine `git mv`s every mapping (history preserved; intra-`codeops` relative links stay
+   valid because the whole tree shifts by one prefix) and writes the marker + seeded portfolio
+   roadmap **last**.
+
+5. **Report.** Summarize what moved and restate the warnings as **manual follow-ups** — most
+   importantly any **source-relative links** (e.g. a plan doc linking into `src/`), which the
+   engine surfaces but never rewrites. Remind the user to review `git status` / `git diff
+   --staged` and commit (the migration is staged as one reviewable change).
+
+## Preview shape (illustrative)
+
+```
+setup-codeops — migration preview (flat → nested)
+  Feature slug:  billing-platform   (source: roadmap header "Billing Platform")
+  Move:          requirements/, plans/invoicing/, plans/legacy/, plans/00-roadmap.md,
+                 plans/_archive/billing-v1/
+  Create:        codeops/.codeops.yml, codeops/00-roadmap.md (portfolio, 1 feature)
+  ⚠ Warnings:
+    - plans/legacy/ is on disk but not in the roadmap (still migrated)
+    - plans/legacy/03-old.md links ../../src/pay.ts (source-relative; verify after move)
+  Apply with git mv? [y/N]
+```
+
+## Edge cases (all handled by the engine — surface, don't re-derive)
+
+| Case | Engine behaviour | What you tell the user |
+|------|------------------|------------------------|
+| No roadmap to read the slug from | Falls back to the repo/dir name, states the source | "Slug taken from the directory name; rename later if you want a different feature name." |
+| Plans on disk not in the roadmap | Migrated under the feature **and** listed as a warning | List them so the user knows they were included. |
+| Loose file directly under `plans/` (not `00-roadmap.md`, not in a plan dir) | Left in place **and** warned (`loose-file-not-migrated`) — no feature target to guess | Tell the user to move it by hand; it is not auto-relocated. |
+| Relative link into source | Surfaced as a warning, never rewritten | Flag each for manual fixing after the move. |
+| Dirty working tree | Refuses (non-zero), no changes | Ask to commit/stash, then re-run. |
+| Re-run after migration | No-op (marker present) | Report "already migrated". |
+| Hostile/odd Feature-Set header | Slug sanitized to a safe path component | Show the resulting slug; it can never escape `codeops/features/`. |

package/skills/setup-codeops/scaffold.md

@@ -0,0 +1,99 @@
+# Fresh Scaffold
+
+> Read this when `setup-codeops` detects **neither** a marker nor a flat layout — a repo with no
+> CodeOps artifacts yet. Resolve paths via [_shared/layout-convention.md](../../_shared/layout-convention.md).
+
+## What to create
+
+Create **exactly** this minimal skeleton — nothing more (FR-6, AR #12):
+
+```
+codeops/
+├── .codeops.yml          # the layout marker (schema below)
+├── codeops.json          # structured quality/routing/metrics policy
+├── 00-roadmap.md         # empty portfolio roadmap (0 features)
+└── features/             # empty; per-feature dirs are created LAZILY on first RD/plan/task
+```
+
+Do **not** create `_maintenance/`, any `features/<name>/`, or any requirements/plans dirs up
+front. Those appear lazily when the first RD, plan, or task is authored (AR #5).
+
+## Steps
+
+1. Confirm the repo is a git repo (suggest `git init` if not).
+2. Create `codeops/features/` (the empty features dir).
+3. Write `codeops/.codeops.yml` (the marker — `setup-codeops` is its sole writer).
+4. Write `codeops/codeops.json` with the strict defaults below.
+5. Write `codeops/00-roadmap.md` (empty portfolio — see the portfolio template in the `roadmap`
+   skill; seed it with zero features and an empty Archived section).
+6. Confirm the marker, policy, portfolio, and empty feature directory exist; report setup state
+   rather than claiming project readiness.
+7. Report what was created and what to do next (`make-requirements` / `make-plan` for the first
+   feature; the feature folder is created lazily then).
+
+## `codeops/codeops.json` (write verbatim)
+
+```json
+{
+  "schema": 1,
+  "mode": "strict",
+  "artifacts": {"layout": "nested", "root": "codeops"},
+  "quality": {
+    "independentReview": true,
+    "minimumReviewers": 1,
+    "stopOnMajorFinding": true
+  },
+  "metrics": {"enabled": false}
+}
+```
+
+## `codeops/.codeops.yml` (write verbatim)
+
+```yaml
+# CodeOps layout marker. Presence of this file opts the repo into the nested layout.
+# Sole writer: the setup-codeops skill. Schema: _shared/layout-convention.md
+codeopsLayout: nested
+layoutVersion: "3.0.0"
+integrationBranch: <the repo's integration branch — resolve; see the note below>
+conventions:
+  rdIdScope: per-feature
+  taskIdPrefix: "T"
+  maintenanceFeature: _maintenance
+  archiveDir: codeops/_archive
+```
+
+Resolve `integrationBranch` to the repo's default branch — `git symbolic-ref refs/remotes/origin/HEAD`
+(strip `origin/`), else the current branch, else `main`/`master`. It names the branch where features
+integrate and derived files (the portfolio roadmap, `AGENTS.md`) are regenerated, so parallel feature
+worktrees don't collide on them. The key is **optional** — every consumer auto-detects the same
+default when it is absent — so this line is a convenience/pin, not a requirement.
+
+## Notes
+
+- The marker is what flips the repo into nested layout — write it **last** after the structured
+  config and roadmap, so a half-finished
+  scaffold never looks "set up".
+- Scaffolding is intentionally simple, so it lives in skill prose; only the *migration* path
+  needs the deterministic engine. For migration, see [migration.md](migration.md).
+
+## Agent file installation
+
+After scaffolding, install the CodeOps OpenCode agent definitions into the project. Prefer the
+installer bundled with the running plugin, so the agent version always matches the plugin version:
+
+```bash
+node "${CODEOPS_PLUGIN_ROOT}/bin/install-agents.mjs" --project
+```
+
+When the plugin is not active, the published installer does the same thing:
+
+```bash
+npx -y opencode-codeops@latest install-agents --project
+```
+
+This installs the 12 CodeOps subagent definitions (`executor`, `explorer`, `correctness-reviewer`,
+etc.) into `.opencode/agents/` where OpenCode will discover and load them automatically. These files
+are safe to commit to git. Files the installer owns are replaced on upgrade; same-named files it
+does not own are left untouched (pass `--force` to replace them). Users can override individual
+agent models in `opencode.json` under the `agent` key.
+

package/skills/setup-routing/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: setup-routing
+description: Configure risk- and capability-based OpenCode subagent routing for a project. Use when the user asks to set up CodeOps routing, specialist reviewers, model or reasoning policy, or project-local agents. Analyzes the system's domains and risks, proposes roles and review requirements, records structured CodeOps policy, and optionally generates project-local OpenCode agent files. Never weakens CodeOps gates when agents are unavailable.
+---
+
+# Configure CodeOps routing for OpenCode
+
+Routing is an optimization and isolation mechanism, not a source of correctness. Requirements,
+ambiguity, direct artifact checks, verification, and review gates remain identical whether work
+runs inline, through a named custom agent, or through a dynamically prompted generic subagent.
+
+## Inputs
+
+Read, in order:
+
+1. `AGENTS.md` and nested guidance;
+2. `codeops/codeops.json`, if present;
+3. project manifests, languages, frameworks, and verification commands;
+4. requirement/specification tags and system invariants;
+5. active security, financial, concurrency, performance, and compatibility risks; and
+6. current `.opencode/agents/*.md`, preserving all hand-authored files.
+
+## Classify the project
+
+Assign one or more domain capabilities:
+
+- compiler/language semantics;
+- financial integrity;
+- authentication and authorization;
+- tenant isolation;
+- distributed systems and concurrency;
+- performance critical;
+- persistence and migration;
+- public API/protocol compatibility;
+- web/application behavior; or
+- standard product engineering.
+
+Then classify each planned phase:
+
+| Risk | Meaning | Minimum routing |
+|---|---|---|
+| Critical | A defect can corrupt money/data, break security/isolation, or establish incompatible semantics/contracts | demanding executor where useful plus at least two independent relevant reviewers |
+| High | Cross-cutting, difficult to reverse, concurrency-sensitive, migration-heavy, or public-contract work | demanding reasoning plus one independent reviewer |
+| Standard | Normal feature work with bounded impact | inline or balanced executor plus one review pass |
+| Mechanical | Fully specified, locally reversible transformation | fast executor or inline; deterministic verification still required |
+
+## Propose before writing
+
+Present:
+
+- detected domains and concrete evidence;
+- phase tag → capability/effort policy;
+- required specialist reviewers;
+- proposed concurrency limit;
+- whether custom TOML agents add value over dynamic packets; and
+- exact files that would change.
+
+Model names are implementation choices, not policy names. Default to the current OpenCode model guidance and environment availability. A project override may pin a model, but every role must remain operable without the pin.
+
+## Structured policy
+
+Store CodeOps policy in `codeops/codeops.json`, not in `AGENTS.md`. `AGENTS.md` receives only a concise instruction that CodeOps routing is configured and that material ambiguity and verification gates may not be bypassed.
+
+Example policy fields are documented in [routing.md](routing.md).
+
+## Optional project-local agents
+
+Only after confirmation, generate selected `.opencode/agents/*.md` files with:
+
+```bash
+python3 "${CODEOPS_PLUGIN_ROOT}/scripts/install_agents.py" --project . --roles ROLE[,ROLE...]
+```
+
+The installer:
+
+- creates only generated files carrying the CodeOps marker;
+- never overwrites a hand-authored agent;
+- supports `--dry-run` and `--check`;
+- uses read-only sandboxing for auditors and challengers;
+- writes complete developer instructions; and
+- never modifies global OpenCode configuration.
+
+## Runtime dispatch rule
+
+For every dispatch, send a bounded packet containing scope, authoritative excerpts, relevant decisions, target paths, verification command, forbidden actions, and required output schema. Do not assume a custom agent inherits the conversation's system model.
+
+When a requested role is unavailable:
+
+1. use a generic subagent with the complete role packet when isolation or independence matters;
+2. otherwise run inline;
+3. report the fallback; and
+4. preserve every gate and required reviewer count.
+
+## Verification
+
+After setup:
+
+```bash
+python3 "${CODEOPS_PLUGIN_ROOT}/scripts/install_agents.py" --project . --check
+```
+
+Report configured roles, model pins if any, read-only roles, fallbacks, and unresolved capability gaps.

package/skills/setup-routing/routing.md

@@ -0,0 +1,44 @@
+# Routing policy
+
+CodeOps routing lives under the optional `routing` and `quality` fields in `codeops/codeops.json`.
+
+```json
+{
+  "schema": 1,
+  "mode": "strict",
+  "artifacts": {"layout": "nested", "root": "codeops"},
+  "quality": {
+    "independentReview": true,
+    "minimumReviewers": 1,
+    "stopOnMajorFinding": true
+  },
+  "routing": {
+    "maxConcurrentAgents": 4,
+    "roles": {
+      "explorer": {"effort": "medium"},
+      "executor": {"effort": "high"},
+      "correctness-reviewer": {"effort": "high", "sandbox": "read-only"},
+      "security-auditor": {"effort": "high", "sandbox": "read-only"}
+    }
+  },
+  "metrics": {"enabled": false}
+}
+```
+
+Allowed effort values follow the active OpenCode release. Prefer `medium` for bounded reconnaissance, `high` for correctness/security review, and higher supported levels only for genuinely demanding semantic or architectural work.
+
+Model pins are optional per role. When omitted, OpenCode resolves the model from the explicit spawn, project defaults, and parent session. A missing pin must never block the workflow.
+
+Reviewer selection is driven by risk tags:
+
+| Tag | Required role |
+|---|---|
+| `security` | security auditor |
+| `financial-integrity` | financial-integrity auditor |
+| `concurrency` | concurrency auditor |
+| `performance-critical` | performance auditor |
+| `compiler-semantics` | semantics reviewer |
+| `migration` | migration/data-integrity reviewer |
+| all non-trivial phases | correctness reviewer |
+
+Multiple applicable tags produce a review team. Combine closely related lenses into one agent only when independence is not lost and the packet remains bounded.