opencode-codeops 1.4.0

package/skills/techdocs/vitepress-setup.md

@@ -0,0 +1,143 @@
+# techdocs — VitePress Setup (Phase 3)
+
+> **CodeOps Artifact Schema**: 1
+
+Scaffold VitePress for the `docs/` set: install it, generate the config, add npm scripts, and
+ignore build output. Read this when first scaffolding the docs site, and whenever new pages are
+added (the sidebar must stay in sync).
+
+## 1. Install VitePress
+
+Install VitePress as a dev dependency using the project's package manager:
+
+```bash
+# npm
+npm install -D vitepress vitepress-plugin-mermaid mermaid
+
+# yarn
+yarn add -D vitepress vitepress-plugin-mermaid mermaid
+
+# pnpm
+pnpm add -D vitepress vitepress-plugin-mermaid mermaid
+```
+
+> `vitepress-plugin-mermaid` is required for the architecture diagrams — vanilla VitePress does
+> NOT render ```` ```mermaid ```` blocks. The config below must wrap `defineConfig` with
+> `withMermaid` accordingly:
+>
+> ```typescript
+> import { withMermaid } from 'vitepress-plugin-mermaid'
+> export default withMermaid(defineConfig({ /* … */ }))
+> ```
+
+## 2. Generate `.vitepress/config.ts`
+
+Generate `docs/.vitepress/config.ts` based on the **actual** documentation structure.
+
+```typescript
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+  title: '[Project Name] — Technical Documentation',
+  description: 'Architecture documentation for [Project Name]',
+
+  themeConfig: {
+    nav: [
+      { text: 'Architecture', link: '/architecture/system-overview' },
+      { text: 'Decisions', link: '/decisions/' },
+      { text: 'Guides', link: '/guides/getting-started' },
+      { text: 'Reference', link: '/reference/configuration' },
+    ],
+
+    sidebar: [
+      {
+        text: 'Overview',
+        items: [
+          { text: 'Introduction', link: '/' },
+        ],
+      },
+      {
+        text: 'Architecture',
+        items: [
+          { text: 'System Overview', link: '/architecture/system-overview' },
+          { text: 'Data Model', link: '/architecture/data-model' },
+          { text: 'API Design', link: '/architecture/api-design' },
+          { text: 'Infrastructure', link: '/architecture/infrastructure' },
+          { text: 'Security', link: '/architecture/security' },
+        ],
+      },
+      {
+        text: 'Decisions',
+        items: [
+          { text: 'Decision Log', link: '/decisions/' },
+          // Individual ADRs are listed here as they are created
+        ],
+      },
+      {
+        text: 'Developer Guides',
+        items: [
+          { text: 'Getting Started', link: '/guides/getting-started' },
+          { text: 'Development Workflow', link: '/guides/development' },
+          { text: 'Deployment', link: '/guides/deployment' },
+        ],
+      },
+      {
+        text: 'Reference',
+        items: [
+          { text: 'Configuration', link: '/reference/configuration' },
+          { text: 'Integrations', link: '/reference/integrations' },
+        ],
+      },
+    ],
+
+    socialLinks: [
+      // { icon: 'github', link: 'https://github.com/...' },
+    ],
+  },
+})
+```
+
+> **Rule:** The sidebar MUST only include sections that actually exist. Remove entries for any
+> section skipped per the project-type adaptation table in SKILL.md.
+
+## 3. Add npm scripts
+
+Add documentation scripts to the project's `package.json`:
+
+```json
+{
+  "scripts": {
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
+  }
+}
+```
+
+## 4. Update `.gitignore`
+
+Add the VitePress build output to `.gitignore`:
+
+```
+docs/.vitepress/dist
+docs/.vitepress/cache
+```
+
+## Sidebar auto-update when pages are added
+
+When new documentation pages are added (new ADRs, new architecture sections), update
+`.vitepress/config.ts` so the new pages appear in the sidebar.
+
+When a new ADR is created, add it under the Decisions section:
+
+```typescript
+{
+  text: 'Decisions',
+  items: [
+    { text: 'Decision Log', link: '/decisions/' },
+    { text: 'ADR-001: [Title]', link: '/decisions/ADR-001-short-name' },
+    { text: 'ADR-002: [Title]', link: '/decisions/ADR-002-short-name' },
+    // New ADR added here
+  ],
+}
+```

package/skills/upgrade-plan/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: upgrade-plan
+description: Upgrade an existing CodeOps requirements set, specification, plan, or project from a legacy artifact format to the current schema and quality standards. Use for upgrade my plan, upgrade requirements, migrate CodeOps artifacts, or bring project artifacts up to date. Assesses and previews changes, closes content ambiguities before structural migration, preserves user-authored semantics and progress, and verifies the result without advancing the roadmap.
+---
+
+# Upgrade CodeOps artifacts
+
+The current CodeOps artifact schema is `1`. Historical Claude CodeOps `3.x` stamps describe the producing skill release, not this schema. Treat them as legacy input requiring assessment, not as numeric predecessors of schema 1.
+
+## Scope
+
+Upgrade content and structure in place. Layout moves belong to `setup-codeops`. Never combine a layout migration and semantic/schema upgrade into one irreversible operation.
+
+Targets may be a requirements set, one feature plan, one feature, or the whole CodeOps project. Resolve flat/nested paths via [../../_shared/layout-convention.md](../../_shared/layout-convention.md).
+
+## Phase 1 — Read-only assessment
+
+1. Read every target artifact and its links.
+2. Detect `CodeOps Artifact Schema: 1`, legacy `CodeOps Skills Version`, partial migrations,
+   obsolete `traceability.json` files, missing RD-to-plan declarations, and contradictory stamps.
+3. Run current requirement, specification, plan, domain-lens, and content-quality checks.
+4. Inventory user-owned semantics, completed/in-progress task marks, custom notes, identifiers, and links that must survive byte-for-byte or meaning-for-meaning.
+5. Produce an upgrade report listing additions, structural changes, semantic gaps, preserved content, risks, and rollback/recovery method.
+
+If current semantic gates pass, every plan declares its implemented RDs, and every execution plan
+uses the four checklist markers, report no upgrade needed. Treat obsolete traceability files as
+deletion candidates after confirming no external consumer depends on them; do not migrate their
+graph state into a replacement platform.
+
+For a whole nested `codeops/` project, preview the deterministic structural portion with:
+
+```bash
+python3 "${CODEOPS_PLUGIN_ROOT}/scripts/codeops_plan_migrate.py" ./codeops
+```
+
+If the preview has no `BLOCKED` entries and the user approves it, rerun with `--apply`. The
+migrator never resolves content ambiguities: return blocked mappings or legacy blocker semantics
+to this skill before applying.
+
+## Phase 2 — Approval and content-quality gate
+
+Present the report before writing. The user may approve all, request details, narrow scope, or decline.
+
+After approval, run [content-quality-gate.md](content-quality-gate.md). Structural modernization must not hide vague or contradictory content. Record every material gap as an ambiguity, resolve it explicitly, and update its authoritative owner before migration.
+
+## Phase 3 — Structural migration
+
+Follow [upgrade-checklists.md](upgrade-checklists.md):
+
+- add `> **CodeOps Artifact Schema**: 1` where artifact stamps belong;
+- add or update each plan's single `> **Implements**:` declaration;
+- preserve completed `[x]` and implemented `[~]` task states;
+- convert a blocked legacy task to `[!]` with a short visible reason;
+- preserve technical decisions, requirements, criteria, rationale, and notes;
+- update renamed skill/project-guidance references;
+- add missing ambiguity, domain, security, verification, and project-tracking sections; and
+- never silently renumber identifiers that external artifacts reference.
+
+Use small recoverable edits. Git history is the rollback and recovery mechanism.
+
+## Phase 4 — Verification
+
+Run the plan parser and the project's verification commands:
+
+```bash
+python3 "${CODEOPS_PLUGIN_ROOT}/scripts/codeops_plan.py" --root . --json
+```
+
+Then verify document/task/requirement counts and user semantics are preserved; material
+ambiguities are resolved or explicitly approved deferrals; tests precede implementation; no task
+is marked `[x]` without passing verification; roadmap lifecycle state is unchanged except for
+approved drift repair; and the Git diff contains only the approved migration.
+
+Report old formats, new schema, files changed, ambiguities resolved, RD-to-plan coverage, preserved
+progress, and residual risk. Do not auto-advance lifecycle stages.

package/skills/upgrade-plan/content-quality-gate.md

@@ -0,0 +1,35 @@
+# Phase 2B — Content Quality Gate (caller preamble, upgrade-plan)
+
+> **CodeOps Artifact Schema**: 1
+
+The Content Quality Gate IS the shared Zero-Ambiguity Gate, scoped to **existing documents**: the
+gate itself is defined ONCE in **[../../_shared/zero-ambiguity-gate.md](../../_shared/zero-ambiguity-gate.md)**
+— read it before running Phase 2B. This preamble binds it to upgrade-plan and adds the
+upgrade-only scanning rules:
+
+- **Phase**: 2B — Phase 3 (structural upgrades) is BLOCKED until it passes. While blocked:
+  no structural upgrades, no version-stamp updates, no document edits.
+- **Scope**: scan ALL existing documents of the artifact being upgraded across the shared gate's
+  12 categories, looking for content that predates the gate (vague decisions, unstated
+  assumptions, AI-guessed specifications). Upgrading format without fixing content produces a
+  polished but hollow artifact.
+- **Register handling**: append to the artifact's existing register (continue numbering) or
+  create a fresh one if none exists; tag every upgrade-found entry `(upgrade)` in the Category
+  column. Record `Upgrade From:` / `Upgrade To:` in the register header.
+
+## Vague-language patterns to flag
+
+```
+"TBD", "to be determined", "something like", "we could", "probably", "might", "maybe",
+"a reasonable approach", "as needed", "if applicable", "similar to", "standard approach",
+"best practices", "etc.", "and so on"
+```
+
+**Materiality clause:** flag an instance only where the vagueness **hides a decision** — wording
+whose resolution would change what gets built, tested, or secured. Non-normative prose (context,
+examples, illustrative asides) is exempt. When unsure whether it hides a decision, flag it.
+
+## After the gate passes
+
+Phase 3 applies structural upgrades AND writes every resolved content gap into the appropriate
+document with an `AR #` back-reference, so document content and register stay linked.

package/skills/upgrade-plan/upgrade-checklists.md

@@ -0,0 +1,107 @@
+# Phase 3 — Per-Document Re-evaluation Checklists (Reference)
+
+The upgrade-plan skill links here. Use these checklists in Phase 3, after the Content Quality Gate
+([content-quality-gate.md](content-quality-gate.md)) has passed. Apply the **plan checklists** when
+upgrading `plans/[feature-name]/`, and the **requirements checklists** when upgrading
+`requirements/`.
+
+For every document: re-evaluate against current standards (the make-plan skill's current standards
+for plans; the make-requirements skill's current standards for requirements), add the version stamp
+`> **CodeOps Artifact Schema**: 1` where stamps belong, and write in any content fixes resolved
+during Phase 2B with an `AR #` back-reference. Always honor the Content Preservation Rules in
+SKILL.md — never destroy user work.
+
+---
+
+## Plan upgrade — re-evaluation checklists
+
+For a whole nested project, use `codeops_plan_migrate.py <codeops-dir>` to preview the mechanical
+RD mapping and obsolete-graph deletion after these content checks pass. Apply only from a clean
+Git tree and only when the preview has no blocked plan.
+
+Re-evaluate each plan document against the make-plan skill's current standards.
+
+### `00-index.md`
+- [ ] Version stamp present? → Add `> **CodeOps Artifact Schema**: 1` if missing.
+- [ ] Follows the current index template structure?
+- [ ] Navigation links to all plan documents?
+- [ ] Document count and overview accurate?
+
+### `00-ambiguity-register.md`
+- [ ] Exists? → If not, it was created during Phase 2B.
+- [ ] All entries resolved with explicit user decisions?
+- [ ] Upgrade entries tagged with `(upgrade)` in the Category column?
+- [ ] `AR #` back-references added to all plan documents for resolved content gaps?
+
+### `01-requirements.md`
+- [ ] Security requirements section present? (per your project's coding standards — AGENTS.md)
+- [ ] Acceptance criteria for each requirement?
+- [ ] Requirements numbered and categorized?
+- [ ] All scope decisions have `AR #` back-references?
+- [ ] No vague language remaining?
+
+### `02-current-state.md` (if it exists)
+- [ ] Gap-analysis format follows the current template?
+
+### `03-XX` technical specification documents
+- [ ] **Preserve user-authored technical decisions verbatim.**
+- [ ] Add missing structural sections (e.g. error-handling table, testing requirements).
+- [ ] Insert `AR #` back-references for content gaps resolved during Phase 2B.
+- [ ] No vague language remaining?
+
+### `07-testing-strategy.md` (if it exists)
+- [ ] Follows current testing standards — your project's testing standards (AGENTS.md)?
+- [ ] Coverage-goals table present?
+- [ ] Test categories clearly defined?
+
+### `99-execution-plan.md`
+- [ ] Version stamp present? → Add `> **CodeOps Artifact Schema**: 1` if missing.
+- [ ] Commit-mode flags documented? (`--ask-commit`, `--no-commit`, `--auto-commit`)
+- [ ] Session protocol section present and current?
+- [ ] Success criteria includes a post-completion re-analysis step?
+- [ ] Success criteria includes a security-hardening check?
+- [ ] Success criteria includes a dead-code check?
+- [ ] Success criteria includes zero-ambiguity verification?
+- [ ] Techdocs-update step present in success criteria (via the techdocs skill)?
+- [ ] Dependencies section present?
+
+### Cross-references (all plan documents)
+- [ ] References point to current skill/command names (make-plan skill, make-requirements skill,
+      techdocs skill, the `git-commit` skill commands, the project's AGENTS.md)?
+- [ ] No references to deprecated or renamed rules / MCP calls?
+
+---
+
+## Requirements upgrade — re-evaluation checklists
+
+Re-evaluate each requirements document against the make-requirements skill's current standards.
+
+### `00-ambiguity-register.md`
+- [ ] Exists? → If not, it was created during Phase 2B.
+- [ ] All entries resolved with explicit user decisions?
+- [ ] Upgrade entries tagged with `(upgrade)` in the Category column?
+- [ ] `AR #` back-references added to all RD documents for resolved content gaps?
+
+### `README.md`
+- [ ] Version stamp present? → Add `> **CodeOps Artifact Schema**: 1` if missing.
+- [ ] Follows the current README template?
+- [ ] Dependency graph present and accurate?
+- [ ] Domain glossary present and complete?
+- [ ] Document index lists all RD documents?
+- [ ] Ambiguity Register listed in the document index?
+
+### Individual RD documents (`RD-XXX-*.md`)
+- [ ] Version stamp present? → Add `> **CodeOps Artifact Schema**: 1` if missing.
+- [ ] Security considerations section present and complete? (per your project's coding standards — AGENTS.md)
+- [ ] Acceptance criteria defined for each requirement?
+- [ ] Dependencies on other RDs documented?
+- [ ] Scope decisions have `AR #` back-references?
+- [ ] Integration points section present?
+- [ ] No vague language remaining?
+- [ ] Priority and status fields present?
+- [ ] Techdocs-update section present (via the techdocs skill)?
+
+### Cross-references (all requirements documents)
+- [ ] References point to current skill/command names (make-requirements skill, make-plan skill,
+      techdocs skill, the `git-commit` skill commands, the project's AGENTS.md)?
+- [ ] No references to deprecated or renamed rules / MCP calls?

package/standards/coding-standards-full.md

@@ -0,0 +1,124 @@
+# Coding standards (CodeOps) — FULL reference
+
+> This is the complete standards text. The `SessionStart` hook injects only the compact core
+> (`standards/coding-standards.md`); read THIS file before writing substantial code or tests,
+> and whenever a core one-liner needs its full definition.
+
+# Coding standards (CodeOps)
+
+These apply to all code I write unless this project's `AGENTS.md` overrides a specific point.
+
+## Quality & structure
+- **DRY.** Extract repeated logic, constants, and patterns; if similar code appears in more than one place, refactor it.
+- **Clarity over cleverness.** Every line should be readable by a junior developer. Prefer explicit logic over "smart" one-liners.
+- **Single responsibility** per function/class/module.
+- **No dead code.** Remove unused imports, variables, parameters, functions, unreachable code, and commented-out blocks (use version control instead). For intentionally-unused required parameters, use the language's convention (e.g. `_param`). Lean on the language's unused-detection tooling.
+- **Consistency is non-negotiable.** Follow the existing patterns, naming, and architecture of the file/codebase; don't introduce new styles without a strong reason.
+- **If in doubt, be explicit** — more readable code and clearer structure beat fewer lines.
+
+## Documentation
+- **NON-NEGOTIABLE — write for a junior developer.** Comment **why**, not just what — explain
+  complex logic, invariants, edge cases, and non-obvious decisions in a calm, teaching tone.
+  Anything above a junior developer's reading level gets a comment that walks through what is
+  happening without merely narrating the syntax.
+- **NON-NEGOTIABLE — document the code's entities.** Every public, exported, or external-facing
+  class, interface, method, function, property, type, and constant gets a language-appropriate doc
+  comment (JSDoc, docstring, `///`, etc.). Document every non-trivial internal entity too. State
+  purpose, parameters, return value, thrown errors, side effects, and important invariants where
+  they apply. Genuinely self-evident private properties and trivial one-line helpers may be skipped;
+  blanket comments that only restate a name or type are noise, not clarity.
+- Add **`@example`** (or the language equivalent) to public and external-facing API wherever practical — worked examples are the fastest way for both a developer and an AI tool to learn correct usage.
+- **NON-NEGOTIABLE — never reference CodeOps planning artifacts in code.** No code comment or doc comment may point at `codeops/`, `plans/`, `requirements/`, an execution plan, or a plan / requirement / task / RD / AR identifier. Those files are ephemeral — regenerated by the planning skills, migrated between layouts, or deleted once a feature ships — so a reference into them is a dangling pointer and pure noise to a reviewer who never had that folder. **The code must be fully self-explanatory on its own.** When a comment needs the rationale a plan recorded, restate that rationale in plain language in the code; do not cite the plan. (This is about shipped source — commit / PR messages may still reference the plan, as that lives in durable git history, not the code a reviewer reads.)
+- Doc comments carry **no change history, bug-fix notes, or "fixed in vX" annotations** — that belongs in the commit / PR body, where the developer and reviewer see it. A doc comment describes what the entity *is and does now*, not how it got there.
+
+## Architecture & boundaries
+- **Split files before ~700 lines** or when they hold multiple concerns; aim for 200–500 lines per file (700 is the ceiling, not the goal). Use foundation-first layering with a single public entry point (`index`/`mod`/`__init__`).
+- **Respect module/package boundaries** — import from public APIs, never reach into another module's internals.
+- Keep imports at the top; separate type-only imports from value imports where supported; avoid deprecated import styles.
+- Separate runtime dependencies from dev/build dependencies; keep the dependency surface minimal.
+
+## Type safety (statically-typed languages)
+- Proper top-of-file imports for types — no inline `import(...)` type expressions.
+- Use type guards / narrowing; **no unsafe casts** (`as any`, `as unknown`) to bypass the type system in production code.
+- Provide all required fields when constructing typed objects; use enums/constants for discriminators, not bare string literals.
+
+## OOP (when the project uses classes)
+- Prefer `public`/`protected` over `private` (unless `private` is idiomatic for the language and the project opts in). Treat `protected` as internal and document it.
+
+## Security — non-negotiable, from the first line of code
+- **Validate and sanitize all input server-side** with allowlists; check types, ranges, lengths, formats at every entry point.
+- **Prevent injection:** parameterized queries (never string-concatenate SQL/NoSQL), escape output / use framework auto-escaping (XSS), never pass unsanitized input to shells/`eval` (command injection), canonicalize and reject `..`/absolute paths (path traversal), anti-CSRF tokens + `SameSite` cookies, rate-limit auth endpoints.
+- **Protect data:** TLS in transit; encrypt sensitive data at rest; hash passwords with `bcrypt`/`argon2`/`scrypt`; never hardcode secrets (use env vars / secret managers); never log secrets or PII; return minimal errors in production; restrictive CORS; request-size limits; audit dependencies; run containers as non-root from minimal images.
+
+# Testing standards
+
+- **Run the project's verify command (build + test) before completing any task or committing.** No code is "done" while any test fails.
+- **Targeted vs. full:** iterate with targeted tests, but run the **full** verify before declaring completion.
+- **Maximum, granular coverage:** happy path, edge/boundary cases, error/invalid inputs, and integration — each test focused on one thing with a clear failure message.
+- **End-to-end tests** for complete workflows wherever feasible.
+- **Prefer real objects over mocks.** Only mock true externals (DB, HTTP, filesystem) or not-yet-built implementations.
+- **Split test files by concern** (~200–300 lines max): `[feature].[concern].test.[ext]`.
+- **Specification vs. implementation tests (non-negotiable).** Keep them in separate files:
+  - *Specification tests* (`[feature].spec.test.[ext]`) derive expectations from requirements/acceptance criteria/API contracts — **never** from reading the implementation. They are immutable oracles: if a spec test fails after implementation, the **implementation** is wrong. Don't weaken or "fix" a spec test to match broken code without explicit approval. Each carries a traceability comment that states, in plain language, the behavior or acceptance criterion it verifies (e.g. `// password must be at least 8 characters`) — the requirement's *substance*, never a path or ID into `requirements/` (per the Documentation ban), so the oracle stays self-contained if the planning folder is ever removed.
+  - *Implementation tests* (`[feature].impl.test.[ext]`) cover internals, edge cases, and error paths.
+  - When planning with the CodeOps skills, this is enforced as: write spec tests → confirm they fail (red) → implement → make them pass (green) → add implementation tests → verify.
+- **Security tests are mandatory** for input validation, authz, injection, and rate limiting.
+
+# Working style
+- **Ask before assuming.** When a request is ambiguous, ask clarifying questions and suggest improvements rather than guessing. (For deep, structured disambiguation, the `grill-me` skill exists.)
+- **Minimum-sufficient design — do not overengineer.** Use the simplest implementation that fully
+  satisfies the authorized requirements and existing project conventions. Do not introduce new
+  abstractions, layers, dependencies, services, generalized frameworks, infrastructure, or
+  future-proofing unless authorized requirements, existing project conventions, or demonstrated
+  risks require them. Prefer modifying and reusing existing patterns. When multiple solutions are
+  correct, choose the smaller one. A proposed material support surface triggers the explicit
+  user-approval stop in `_shared/zero-ambiguity-gate.md`; `--auto-design` cannot approve it.
+- **Verify previous work** before building on it; confirm a task actually meets its acceptance criteria before calling it done.
+- **Grounded options & recommendations (NON-NEGOTIABLE).** Whenever you present options, choices, or recommendations — from analysis, defect/bug findings, a direction to fix a bug, requirements choices, plan-making, or plan execution:
+  1. **Filter** — present only genuinely viable options; drop weakly-grounded options that realistically won't be chosen and never pad with strawmen. Present ≥2 options only when ≥2 are genuinely viable; when one path clearly dominates, present it alone, say it is the only viable one, and name what you rejected and why.
+  2. **Second-guess** — critique and stress-test each surviving option *before* presenting it, not after.
+  3. **Ground in the code** — for any option that involves modifying existing code, verify it against the actual current code (read the real files) before presenting and cite the evidence as `file:line`; if you could not verify, say so explicitly.
+  4. **Recommend** — lead with your recommended option and a concrete, grounded reason. You recommend; the user decides — never decide for them.
+  - **Proportionality** — match the ceremony to the stakes. Trivial, easily-reversible, or obvious choices get a one-line recommendation; the full four-step treatment is for consequential or code-modifying decisions. Drowning the user in analysis wastes their time as surely as strawman options do.
+  - **Presentation** (consequential decisions) — lead with the recommendation, then each surviving option with its viability, terse pros/cons, and (for code-touching options) a `file:line` evidence cite; close with a one-line "considered and dropped: …" when you filtered options out.
+  - **Harden before presenting** (consequential decisions) — institutionalize the "are these your best?" challenge so it runs *before* you present and *converges* (never reflexive change under pressure): run the reframing prompts + the definition-of-done rubric, and close with a `Confidence:` / `Hardening:` disclosure. For **high-stakes** decisions (preflight CRITICAL/MAJOR findings, or complex/sensitive gate decisions) spawn one independent challenger and reconcile. Full protocol: `_shared/recommendation-hardening.md`.
+  - ✅ *"Recommend **A** — cache in the existing `UserRepo.find` (`repo/user.ts:42`), no new layer. **B** (new cache service) adds infra we don't need here. Dropped: client-side cache — can't share across requests."*
+    ❌ *"There are a few ways: A, B, or C — let me know which you prefer."* (no recommendation, no code grounding, options unfiltered)
+
+# Validation for non-code artifacts
+
+"Verify" is not only build+test. When a change touches non-code artifacts, run the matching
+validation before calling it done:
+
+| Artifact | Validation command |
+| -------- | ------------------ |
+| Dockerfile / Compose | `docker build .` / `docker compose config` |
+| Shell scripts | `shellcheck <script>` (and `bash -n`) |
+| Terraform | `terraform validate` (and `terraform plan` where safe) |
+| Kubernetes manifests | `kubectl apply --dry-run=client -f <file>` |
+| CI workflows | the CI linter (`actionlint`, `gitlab-ci-lint`, …) |
+| JSON / YAML / TOML | a parser pass (`python3 -m json.tool`, `yq`, `taplo`) |
+| SQL migrations | apply against a scratch database / the migration tool's dry-run |
+| Nginx / infra configs | the tool's own check (`nginx -t`, etc.) |
+
+# Coverage targets & test naming
+
+| Code type | Coverage target |
+| --------- | --------------- |
+| Core business logic | 90% |
+| Supporting modules / services | 80% |
+| UI / glue / configuration | 60% |
+
+Test names state behavior: `should [expected behavior] when [condition]`. Targets are defaults —
+a project may adjust them explicitly in its requirements (an AR-referenced decision), never
+silently.
+
+# Security-test organization
+
+Security tests live in their own tree, split by concern, so their absence is visible:
+
+```
+tests/security/security.[concern].test.[ext]
+  e.g. security.input-validation.test.ts, security.authz.test.ts,
+       security.injection.test.ts, security.rate-limit.test.ts
+```

package/standards/coding-standards.md

@@ -0,0 +1,64 @@
+# Coding standards (CodeOps) — core
+
+These apply to all code I write unless this project's `AGENTS.md` overrides a specific point.
+This is the compact, always-injected core; the complete text lives in
+`standards/coding-standards-full.md` — **read it before writing substantial code or tests.**
+Do not duplicate these standards in `~/.config/opencode/AGENTS.md` — the plugin injects them.
+
+## Quality & structure
+- **DRY**; **clarity over cleverness** (junior-readable); **single responsibility**; **no dead
+  code**; **consistency with the existing codebase is non-negotiable**; be explicit when in doubt.
+- Split files before ~700 lines (aim for 200–500); respect module boundaries (import public APIs only); imports at
+  the top; keep the dependency surface minimal.
+- **NON-NEGOTIABLE documentation:** write for a junior developer; explain complex logic,
+  invariants, edge cases, and non-obvious decisions in a calm teaching tone. Document every
+  public/exported class, interface, method, function, property, type, and constant, plus every
+  non-trivial internal entity, using the language's doc-comment format; add `@example` to public
+  APIs where practical. Do not pad trivial private code with comments that merely restate it.
+  Never reference `codeops/`/`plans/`/`requirements/`, an execution plan, or a plan/RD/AR/task ID
+  in code or doc comments; restate durable rationale in plain language. Full rules:
+  `coding-standards-full.md`.
+- Statically-typed code: no unsafe casts (`as any`/`as unknown`); use type guards; enums/constants
+  for discriminators.
+
+## Security — non-negotiable, from the first line
+- Validate and sanitize ALL input server-side (allowlists). Prevent injection: parameterized
+  queries, escaped output, no unsanitized shell/`eval`, canonicalized paths (reject `..`),
+  anti-CSRF + `SameSite`, rate-limited auth.
+- Protect data: TLS in transit, encryption at rest, `bcrypt`/`argon2`/`scrypt` for passwords, no
+  hardcoded secrets, never log secrets/PII, minimal prod errors, restrictive CORS, non-root
+  containers.
+
+# Testing standards
+- **Run the project's verify command before completing any task or committing**; full verify
+  before declaring done. No code is "done" while any test fails.
+- Granular coverage (happy path, edges, errors, integration); E2E where feasible; real objects
+  over mocks (mock only true externals); test files split by concern.
+- **Specification vs. implementation tests (non-negotiable):** `[feature].spec.test.[ext]`
+  derives from requirements only — an immutable oracle (a failing spec test means the
+  implementation is wrong, never the test); `[feature].impl.test.[ext]` covers internals.
+  Order: spec tests → red → implement → green → impl tests → verify.
+- Security tests are mandatory (input validation, authz, injection, rate limiting). Non-code
+  artifacts get validation too — see the full standards' validation-command table.
+
+# Working style
+- **Ask before assuming**; **verify previous work** before building on it.
+- **Do not overengineer:** use the simplest implementation that fully satisfies the authorized
+  requirements and existing project conventions. Do not add abstractions, layers, dependencies,
+  services, generalized frameworks, infrastructure, or future-proofing unless authorized
+  requirements, existing project conventions, or demonstrated risks require them. Prefer modifying
+  and reusing existing patterns; when multiple solutions are correct, choose the smaller one. A
+  proposed material support surface triggers the explicit user-approval stop in
+  `_shared/zero-ambiguity-gate.md`; `--auto-design` cannot approve it.
+- **Grounded options & recommendations (NON-NEGOTIABLE):** Filter (only genuinely viable options,
+  no strawmen; ≥2 only when ≥2 are viable) → Second-guess each → Ground in the code (cite
+  `file:line`; say so if unverified) → Recommend (lead with it and a concrete reason; you
+  recommend, the user decides). Proportionality: ceremony matches stakes. Harden consequential
+  recommendations per `_shared/recommendation-hardening.md` (high-stakes decisions get one
+  independent challenger; disclose `Confidence:`/`Hardening:` where that protocol requires).
+
+> Project-specific commands, structure, and conventions live in this project's `AGENTS.md`
+> (generate/refresh it with the `analyze-project` skill). Multi-step CodeOps workflows are available as
+> skills: `make-plan`, `exec-plan`, `make-requirements`, `retro-requirements`, `grill-me`,
+> `preflight`, `techdocs`, `roadmap`, `upgrade-plan`, `setup-codeops`, and `setup-routing`.
+> Guarded commits, GitHub issues, comment cleanup, and outcome reviews are skills as well.

package/standards/output-style.md

@@ -0,0 +1,17 @@
+# Output style (CodeOps) — how to report back
+
+- **Be short and prefer tabular form.** Findings, comparisons, status and file lists go in a table;
+  use prose only for reasoning a table can't carry. Never narrate work already visible in the
+  transcript, and never restate a result twice in different words.
+- **Use plain international English in user-facing text.** Prefer short sentences and common words.
+  Put one main idea in each sentence. Define uncommon technical terms on first use. Avoid idioms,
+  dense clauses, cryptic grammar, and unclear pronouns. Preserve exact identifiers, commands, and
+  technical terms when precision requires them.
+- **Match reasoning effort to stakes.** Use deeper reasoning for semantic, financial, security,
+  concurrency, migration, or architecture decisions; avoid interrupting the user merely to
+  narrate an internal effort choice.
+- **Advise `/compact` at clean boundaries**, not mid-task: after a phase verifies, before
+  `preflight` or `make-plan`, and on a project switch. Say why now.
+- **End with "Next steps"** wherever there is a next action — a small table of what to do and who
+  owns it. When the repo has a roadmap, precede it with a one-line progress count (done / total)
+  and a table of the remaining items, so the distance left to travel is always visible.