opencode-codeops 1.4.0

package/CHANGELOG.md

@@ -0,0 +1,179 @@
+# Changelog
+
+All notable changes to CodeOps are recorded here.
+
+## 1.4.0 — 2026-09-19
+
+### Features
+
+- installer: add npm-first install, agents installer, and release tooling
+
+## 1.3.1 — 2026-09-15
+
+- Refuse to install or uninstall through a symlinked skills directory unless `--force` is passed,
+  so a symlinked target cannot silently rewrite the tree it points at. `status` stays read-only.
+- Ignore the local install marker and development skill link under `skills/`.
+
+## 1.3.0 — 2026-09-15
+
+- Add a one-line curl installer (`install.sh`) that downloads the repository tarball and runs the
+  skills installer. Pin a version with `CODEOPS_REF`.
+- Add `status` and `uninstall` subcommands to `bin/install-skills.mjs`.
+- Record owned skills and the installed version in `<skills-dir>/.opencode-codeops.json`, and
+  replace managed skills atomically on upgrade. Skills not owned by this package are never touched.
+- Add specification tests for the installer, run with `node --test`.
+
+## 1.2.0 — OpenCode port — 2026-09-12
+
+Port from `codex-codeops` (Codex plugin) to `opencode-codeops` (OpenCode plugin).
+
+### Breaking changes
+- Plugin is now loaded via OpenCode's plugin system (`"plugin": ["opencode-codeops"]` in `opencode.json`) instead of Codex's marketplace mechanism.
+- `PLUGIN_ROOT` environment variable renamed to `CODEOPS_PLUGIN_ROOT` to avoid collisions with other plugins.
+- Agent files are now OpenCode Markdown format (`.opencode/agents/<role>.md`) instead of Codex TOML (`.codex/agents/<role>.toml`). Regenerate with `scripts/install_agents.py`.
+- `setup-routing` now targets `opencode.json` instead of `.codex/config.toml`.
+
+### Changes
+- All 16 skills ported verbatim with Codex-specific terminology updated to OpenCode.
+- All 12 subagents ship with no hardcoded `model` field — agents inherit the user's active model automatically. Pin models per-role via `opencode.json` or the `setup-routing` skill.
+- `bin/codeops-worktree --launch` now starts `opencode` instead of `codex`.
+- Standards are now injected into sessions via OpenCode's `session.created`, `session.compacted`, and `experimental.session.compacting` hooks — providing stronger coverage than the Codex equivalent.
+- `scripts/install_agents.py` rewritten to generate OpenCode `.md` agent files instead of Codex `.toml` files.
+
+---
+
+## 1.2.0 — 2026-09-04
+
+- Add an always-active Complexity Escalation Gate that requires a visible cost-and-evidence packet,
+  an independent challenger, and explicit user approval before material support machinery enters
+  requirements, plans, or implementation.
+- Make escaped complexity a blocking major finding, reserve escalation approval to the user even
+  under `--auto-design`, and reuse existing ambiguity and finding records instead of adding a new
+  lifecycle or configuration system.
+- Use plain international English in user-facing CodeOps responses.
+
+## 1.1.0 — 2026-08-30
+
+- Show a deterministic ten-cell progress bar after every verified `exec-plan` task, including exact
+  task counts and percentage for accessibility.
+- Derive the display directly from authoritative Markdown task markers without adding mutable
+  progress state or changing the execution-plan artifact format.
+- Add specification and implementation coverage for rendering, verification-pending tasks,
+  read-only behavior, boundary states, invalid inputs, and conflicting CLI output modes.
+
+## 1.0.1 — 2026-08-26
+
+- Direct planning and implementation toward the simplest solution that satisfies authorized
+  requirements, existing project conventions, and demonstrated risks.
+- Guard the minimum-sufficient-design instruction in plan quality checks and deterministic plugin
+  validation without changing existing workflow gates or artifact formats.
+
+## 1.0.0 — 2026-08-08
+
+- Make Markdown plans the sole authoritative owner of execution progress and requirement delivery,
+  removing the mutable traceability graph, transition API, journal, lock, and shadow state.
+- Add a read-only plan parser that derives lifecycle, next task, and RD delivery directly from
+  `00-index.md` ownership metadata and `99-execution-plan.md` checklist markers.
+- Add an all-or-nothing migrator for existing nested projects that preserves checklist progress,
+  recovers lightweight and plan-local ownership, and deletes obsolete `traceability.json` files.
+- Make `setup-codeops --yes` automatically detect, migrate, and verify legacy workflow state in an
+  already-configured project while retaining clean-tree and ambiguity safeguards.
+- Validate the migration on JSVision with 21 active plans, deletion of five legacy graphs, and a
+  passing Windows, macOS, and Linux CI matrix on Node.js 22 and 24.
+
+## 0.4.0 — 2026-07-31
+
+- Keep planning, preflight, and execution inside strict product scope by default, suppressing
+  optional feature suggestions without hiding necessary correctness, safety, or feasibility work.
+- Add invocation-scoped `--explore-scope` with durable, user-owned `Keep`, `Defer`, and `Discard`
+  decisions for optional additions.
+- Keep scope authority separate from auto-design, finding resolution, fix permission, and commit
+  modes, with collision-free registers and resume-safe invalidation rules.
+
+## 0.3.1 — 2026-07-24
+
+- Make junior-readable source documentation a non-negotiable implementation standard.
+- Require language-appropriate documentation for public APIs and non-trivial internal entities
+  while avoiding comments that merely restate trivial private code.
+- Block execution-task completion when required documentation is missing, and make omissions an
+  explicit phase-review finding even when builds, tests, and linters pass.
+- Add conformance coverage that preserves the executor, reviewer, and completion-gate contracts.
+
+## 0.3.0 — 2026-07-23
+
+- Add invocation-scoped `--auto-design` to requirements, planning, preflight, and execution.
+- Select eligible technical decisions through a documented strongest-option rubric with durable
+  provenance, bounded escalation, invalidation, and independent challenge for high-impact choices.
+- Preserve user authority over product direction, risk acceptance, permissions, destructive or
+  external actions, and keep commit behavior independent from design delegation.
+- Add deterministic contract, boundary, hostile-argument, and collection coverage.
+
+## 0.2.0 — 2026-07-23
+
+- Promote the Codex plugin from beta to the first stable 0.2 release.
+- Add dependency-aware, target-scoped readiness across requirements, audit, planning, execution,
+  roadmap, feature acceptance, and release workflows.
+- Add schema-2 semantic revisions, validation snapshots, atomic lifecycle transitions, explicit
+  recovery, and safe schema-1 graph upgrades.
+- Keep the broader 1.0 comparative and external complex-project pilot gate explicitly open.
+- Adopt Semantic Versioning for all subsequent releases.
+
+## 0.2.0-beta.7 — 2026-07-23
+
+- Add schema-2 target-scoped readiness, atomic lifecycle transitions, and recoverable graph
+  upgrades across requirements, audit, planning, execution, roadmap, acceptance, and release.
+- Scope readiness gates to the selected feature so unrelated draft work does
+  not block planning or execution.
+- Treat traceability node IDs as feature-local and require explicit
+  qualification for cross-feature links.
+- Add planning target, context, and modification boundaries plus bounded
+  post-gate ambiguity discovery.
+- Align make-plan with the shared named-deferral contract.
+- Review complete phase changes in every commit mode using worktree snapshots
+  that include staged, unstaged, committed, and newly created files.
+- Escalate repeated identical verification failures instead of retrying
+  indefinitely.
+
+## 0.2.0-beta.6 — 2026-07-23
+
+- Keep single-document preflight audits scoped to their selected target while
+  using related artifacts only as context.
+- Bound corrective rescans, preserve finding identity by root cause, and stop
+  cleanly when minor findings are explicitly accepted.
+- Store narrow preflight evidence separately so sibling requirements and whole
+  plans cannot advance from an out-of-scope pass.
+- Add deterministic validation for preflight scope and convergence contracts.
+
+## 0.2.0-beta.5 — 2026-07-23
+
+- Make `status` a successful observation for structurally valid projects whose
+  requirements or plans are not yet execution-ready.
+- Treat migrated Claude roadmap, requirement, and plan documents as first-class
+  Codex schema-1 artifacts during roadmap presentation.
+- Add regression coverage for valid-but-blocked status and invalid status data.
+
+## 0.2.0-beta.4 — 2026-07-23
+
+- Exclude `codeops/_archive` traceability graphs and execution plans from live
+  readiness, lifecycle, and task-progress reports.
+- Add regression coverage for repositories with large archived project histories.
+
+## 0.2.0-beta.3 — 2026-07-23
+
+- Enforce per-node lifecycle status vocabularies and reopened-ambiguity invalidation.
+- Make the migration layout marker the final commit point after required artifacts.
+- Retain versioned ambiguity-benchmark, installation-lifecycle, and independent-review evidence.
+- Reconcile release claims, platform boundaries, and governing plan state with evidence.
+
+## 0.2.0-beta.2 — 2026-07-23
+
+- Add deterministic traceability, readiness, lifecycle, drift, and strict-config validation.
+- Add Codex-native capability roles and optional project agent installation.
+- Add compiler, financial, web, distributed, and migration ambiguity lenses.
+- Add retained adversarial scenario and Claude 3.12.0 parity evidence.
+- Add install, migration, concepts, troubleshooting, CI, and release documentation.
+
+## 0.2.0-beta.1 — 2026-07-23
+
+- First installable Codex-native beta with requirements, planning, execution,
+  review, roadmap, migration, documentation, routing, and utility skills.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 blendsdk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,171 @@
+# opencode-codeops
+
+**Specification-first engineering for complex systems — CodeOps plugin for OpenCode.**
+
+Turn an idea or existing system into ambiguity-free requirements, grounded specifications, executable plans, verified code, and durable project state.
+
+## Skills
+
+| Skill | Purpose |
+|---|---|
+| `make-requirements` | Formal requirements from an idea — multi-phase discovery, Zero-Ambiguity Gate |
+| `retro-requirements` | Reverse-engineer an existing codebase into structured requirements |
+| `grill-me` | Deep disambiguation interview before planning or requirements |
+| `make-plan` | Multi-document implementation plan from requirements |
+| `preflight` | 13-dimension quality audit of any plan, requirements, or artifact |
+| `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 |
+| `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 |
+| `techdocs` | VitePress-compatible architecture docs and ADRs |
+| `github-issues` | Read and manage GitHub issues via `gh` CLI |
+| `clean-comments` | Audit and clean source comments without changing behavior |
+| `git-commit` | Guarded commit — verify, stage deliberately, Conventional Commit message |
+| `outcome-review` | Review local opt-in outcome metrics (requires `metrics.enabled: true`) |
+
+## Installation
+
+CodeOps has two parts that OpenCode loads differently: the **plugin** (standards and hooks) is
+installed by OpenCode from npm, and the **skills** and **subagents** must be copied onto the
+filesystem because OpenCode only discovers those from disk.
+
+### 1. Add the plugin
+
+Add to your `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-codeops"]
+}
+```
+
+OpenCode installs the plugin automatically via Bun on next startup. A global config
+(`~/.config/opencode/opencode.json`) is recommended so CodeOps is active in every project.
+
+### 2. Install the skills
+
+OpenCode discovers skills only from the filesystem (`.opencode/skills/` or
+`~/.config/opencode/skills/`); it never reads them from a plugin package. The installer is a thin
+`npx` wrapper around this package, so the skills always match the published version:
+
+```bash
+# Global (recommended) — available in every OpenCode project
+curl -fsSL https://cdn.jsdelivr.net/npm/opencode-codeops@latest/install.sh | bash
+
+# Project-only — skills live in ./.opencode/skills and are committed with the repo
+curl -fsSL https://cdn.jsdelivr.net/npm/opencode-codeops@latest/install.sh | bash -s -- --project
+```
+
+The same installer runs directly through npm:
+
+```bash
+npx -y opencode-codeops@latest install-skills
+```
+
+Pin a version with `CODEOPS_VERSION` (an npm dist-tag or exact version; defaults to `latest`):
+
+```bash
+CODEOPS_VERSION=1.4.0 curl -fsSL https://cdn.jsdelivr.net/npm/opencode-codeops@latest/install.sh | bash
+```
+
+Pin the plugin to the same version so the two cannot drift apart:
+
+```json
+{ "plugin": ["opencode-codeops@1.4.0"] }
+```
+
+Re-running the installer upgrades an existing install in place. It replaces only the files this
+package owns, recorded in `<skills-dir>/.opencode-codeops.json`. Skills you author yourself, or
+install with another tool, are left untouched.
+
+Check or remove an install:
+
+```bash
+npx -y opencode-codeops@latest status
+npx -y opencode-codeops@latest uninstall
+```
+
+`status` reports the installed version next to the current package version, so a plugin/skills
+mismatch is visible. Use `--dry-run` to preview an install; a same-named directory the package
+does not own is skipped with a warning, and `--force` replaces it.
+
+### 3. Install the subagents
+
+The 12 CodeOps subagents install into `.opencode/agents/` (project) or `~/.config/opencode/agents/`
+(global). The `/setup-codeops` skill does this for a project; do it manually with:
+
+```bash
+npx -y opencode-codeops@latest install-agents --project
+```
+
+### Local development
+
+Symlink the plugin into your OpenCode plugin directory and link the skills to a checkout, so edits
+are picked up without reinstalling:
+
+```bash
+# Plugin (project or global plugin directory)
+ln -s /path/to/opencode-codeops/plugin/index.ts ~/.config/opencode/plugins/codeops.ts
+
+# Skills and agents — link instead of copy
+node /path/to/opencode-codeops/bin/index.mjs install-skills --link --global
+node /path/to/opencode-codeops/bin/index.mjs install-agents --link --global
+```
+
+## Setup
+
+After installing the plugin and the skills, initialize CodeOps in your project:
+
+```
+/setup-codeops
+```
+
+This creates the `codeops/` layout, scaffolds `codeops/codeops.json` and `codeops/.codeops.yml`, installs the 12 CodeOps subagent files into `.opencode/agents/`, and adds a managed section to `AGENTS.md`.
+
+Commit the result:
+
+```bash
+git add codeops/ .opencode/agents/ AGENTS.md
+git commit -m "chore: initialize CodeOps"
+```
+
+## What the plugin does automatically
+
+On every OpenCode session start and after every compaction, the plugin injects:
+- `standards/coding-standards.md` — coding quality, security, testing, and working-style rules
+- `standards/output-style.md` — how to report findings, format tables, and recommend next steps
+
+These standards are active without any user action. They do not need to be copied into `AGENTS.md`.
+
+The plugin also warns (non-blocking) if any tool attempts to edit `codeops/.codeops.yml` directly — that file is managed exclusively by the `setup-codeops` skill.
+
+## Agent model configuration
+
+All CodeOps subagents inherit the model of the primary agent that invoked them. No provider-specific configuration is required out of the box.
+
+To pin specific models per role, use the `setup-routing` skill or add overrides directly in `opencode.json`:
+
+```json
+{
+  "agent": {
+    "demanding-executor": { "model": "anthropic/claude-opus-4-5" },
+    "executor":           { "model": "anthropic/claude-haiku-4" }
+  }
+}
+```
+
+## Requirements
+
+- OpenCode (current)
+- Bash
+- Python 3.8+
+- Git
+- Node.js 18+ (for the `npx` installer; Bun is used by OpenCode to load the plugin)
+- `gh` CLI (for the `github-issues` skill only)
+
+## License
+
+MIT

package/_shared/auto-design.md

@@ -0,0 +1,129 @@
+# Auto-Design Authority Policy
+
+> **Policy version**: 1
+> **CodeOps Artifact Schema**: 1
+
+`--auto-design` delegates eligible technical design decisions to CodeOps for one workflow chain.
+It preserves ambiguity closure: it changes who may resolve an eligible ambiguity, never whether
+the ambiguity must be found, recorded, traced, challenged, and verified.
+
+## Invocation contract
+
+Only exactly one standalone token `--auto-design` before the first `--` end-of-options sentinel
+activates this policy. Zero occurrences means Default mode; more than one is invalid and must stop
+with a usage correction. A token at or after the sentinel is target content, not an option.
+Lookalikes such as `--auto-designer`, `--auto-design=true`, or bare `auto-design` do not activate
+it. A supporting skill removes the one recognized token before resolving feature names, paths,
+targets, or other options, announces activation, and assigns a root invocation ID. Explicitly
+invoked supporting children inherit a downward-only context:
+
+```text
+mode: auto-design
+root invocation ID: <stable ID for this workflow chain>
+parent workflow: <invoking supported workflow>
+policy version: 1
+delegated categories: <parent's eligible classes or a strict subset>
+reserved categories: <the complete reserved set>
+permission state: <unchanged action and commit permissions>
+```
+
+A child may narrow authority but never widen it. An unsupported child fails closed and uses normal
+authority rules. A later independent invocation is in **Default mode** unless its own arguments
+contain `--auto-design`. The mode is never persisted as a repository or global default.
+
+## Default mode
+
+Without `--auto-design`, existing behavior is unchanged: every material semantic choice requires
+an explicit user decision or explicit named deferral.
+
+## Eligibility boundary
+
+CodeOps may decide only when a choice stays within confirmed goals, product behavior, scope,
+constraints, and acceptance criteria; concerns an implementation mechanism; contradicts no user
+decision or governing artifact; and creates no reserved-authority consequence.
+
+Eligible classes include algorithms, data structures, internal architecture and interfaces,
+compiler and optimizer mechanisms, failure and recovery design, concurrency and consistency,
+persistence and reversible migration mechanisms, security mechanisms within an approved policy,
+testing strategy, performance engineering, and implementation sequencing.
+
+## Reserved authority
+
+Always escalate product behavior or scope, priorities and acceptance criteria, access and security policy,
+data ownership or retention, legal/ethical/compliance or risk acceptance, financial exposure,
+budget/deadline commitments, paid-vendor choices, public compatibility breaks,
+destructive migration, credentials, spending, deployment/publication, destructive or irreversible
+external actions, external communication, and equally defensible designs that create materially
+different products.
+
+The shared Complexity Escalation Gate is also reserved authority. Auto-design may select the
+smallest viable implementation, but it cannot approve a larger layer, dependency, harness,
+framework, infrastructure surface, or other escalation. Only the user's explicit approval of the
+gate packet authorizes that larger option.
+
+`--auto-design` does not grant action permission. It does not authorize implementation outside the
+invoked workflow, file-scope expansion, commits, pushes, `--auto-commit`, installation, purchases,
+deployment, publication, destructive operations, credentials use, or external-system changes.
+
+Scope expansion remains separately user-owned under
+[`scope-expansion-control.md`](scope-expansion-control.md). Auto-design cannot activate optional
+scope exploration, choose `Keep` for an `SE-*` proposal, revive discarded scope, or reinterpret an
+optional addition as an eligible technical decision.
+
+## Strongest-option procedure
+
+1. Gather repository evidence, domain knowledge, constraints, and failure conditions.
+2. Generate every genuinely viable option, actively searching for a non-obvious alternative.
+   When only one option survives evidence, name rejected candidates and why; never invent a
+   strawman merely to create a comparison.
+3. Apply forced reframing: 10× budget, contrarian expert, obsolescence, and pre-emptive challenge.
+4. Compare correctness, soundness and safety, objective fit, maintainability, verifiability,
+   performance, compatibility, operational recovery, delivery risk, proportional complexity, and
+   future evolution.
+5. State the strongest counterargument and set confidence.
+6. Require a blind independent challenger for complex, sensitive, high-impact, or
+   difficult-to-reverse choices. Material divergence, unavailable required review, or insufficient
+   confidence triggers bounded escalation; it never silently accepts or waives risk.
+7. Select the best-supported option. Strongest means most likely to make the whole project
+   succeed, not the most sophisticated design.
+
+## Durable resolution
+
+The owning ambiguity or decision artifact records complete eligibility and provenance, including
+rejected alternatives and reopen triggers:
+
+```text
+Authority: AI — delegated by --auto-design
+Eligibility: <class and boundary rationale>
+Objective: <governing success objective>
+Decision: <selected option>
+Evidence: <repository/domain facts and constraints>
+Rejected alternatives: <viable alternatives and reasons>
+Strongest counterargument: <best case against the choice>
+Confidence: High | Med | Low — <what would change it>
+Hardening: <result and challenger verdict when required>
+Policy version: 1
+Root invocation ID: <ID>
+Reopen triggers: <observable invalidation conditions>
+```
+
+The canonical delegated marker may occupy an existing `User Decision` column for backward
+compatibility. Do not create a parallel decision database or duplicate rationale in traceability.
+
+## Bounded escalation
+
+Research and challenge first. If a choice is reserved, constraints conflict, material evidence
+remains unavailable, concerns cannot be separated, or no option is defensible, stop once per root
+cause with the exact decision, boundary/evidence failure, strongest available recommendation, and
+minimum user input needed. It must never guess or loop repeatedly over the same evidence.
+
+## Invalidation
+
+When new evidence breaks an assumption or a reopen trigger fires, reopen the owning decision,
+mark affected downstream specifications, tests, tasks, implementation, and verification stale,
+repeat this policy, and rerun applicable readiness and semantic gates.
+
+## Supported workflows
+
+The closed allowlist is `make-requirements`, `make-plan`, `preflight`, and `exec-plan`. Adding a
+workflow requires specification coverage and deterministic integration checks.