opencode-skills-collection 4.1.17 → 4.1.19

package/bundled-skills/obsess/references/protocol.md

@@ -0,0 +1,55 @@
+# Measured optimisation protocol
+
+Use this only when the primary objective has a reproducible scalar evaluator. For non-scalar work use [polish](polish.md), even when the target is code. Defaults are engineering choices, not research-established optima.
+
+## Freeze a compact contract
+
+Use [contract.example.json](../assets/contract.example.json) as a field guide. Keep the primary objective separate from hard constraints. Record the target and authorised paths, then the baseline snapshot and comparison conditions. Choose the evaluator revision and minimum meaningful improvement before seeing candidate results.
+
+Default ceiling: 12 candidate attempts and 30 active-session minutes. Explicit limits replace those defaults. `--lite` lowers either mode to at most 2 attempts and 5 active-session minutes, with no extra reviewers. Read [recovery](recovery.md) for cumulative accounting.
+
+## Establish the baseline
+
+Run the untouched version under the chosen conditions. Keep raw results and the evaluator's identity. A new candidate mustn't change the benchmark workload or weaken expected outputs.
+
+If required baseline gates fail, don't use the scalar helper to optimise an ineligible baseline. First establish a bounded repair contract, or explicitly distinguish pre-existing unrelated failures with the user's approval. A repair target may legitimately start out failing; the original failure must remain visible in the record.
+
+For noisy metrics, measure baseline variability and choose the repetition procedure in advance. Alternate or randomise baseline/candidate runs under comparable conditions. Retain all relevant observations, not the single fastest run. The helper's scalar threshold isn't a statistical-significance test.
+
+Tests produced by the proposing agent aren't independent evidence just because they pass. Anchor expected behaviour to the specification or an existing trusted reference. A changed evaluator requires a new comparison epoch and re-evaluation of both versions; don't mix incompatible receipts.
+
+## Protect each candidate
+
+Prefer an isolated copy that includes relevant user work. Don't assume a clean Git worktree contains uncommitted inputs. Never reset, stash or clean the user's working tree. A worktree isn't a security sandbox.
+
+Where a small supervised in-place change is appropriate, apply the snapshot and conflict checks from [polish](polish.md). Preserve the original and incumbent separately. Restore only run-owned changes; external edits cause a stop, not an overwrite.
+
+Before editing, increment `experiments_started`. Save a candidate ID and parent ID. Record a falsifiable hypothesis and one observation that would count against it. A coherent multi-file edit is allowed when the same hypothesis requires it.
+
+## Evaluate before promoting
+
+Run cheap validity checks before the costly evaluator. All fixed constraints must pass and the primary improvement must be positive and meet the agreed threshold. A tie or an inconclusive result leaves the incumbent unchanged. Reject regressions even if another metric improves.
+
+The [scalar gate](../scripts/gate.py) compares supplied receipts. It checks matching contract/evaluator identifiers and mandatory results, then a scalar delta. It doesn't execute tests, read evidence files or authenticate measurements. Only a subset of the contract is machine-checked. Never invent favourable receipts and describe the helper as verification.
+
+A fresh-context review is optional when supported and worth the cost; it isn't required for lite. Give a reviewer the contract and evidence rather than the author's sales pitch. The same model in another role isn't an independent truth source.
+
+Save a recoverable checkpoint before promoting the candidate. Append one [attempt record](../assets/experiment.template.json), including its lesson. Public decision summaries are enough; don't record private chain-of-thought. Keep raw logs on disk and only relevant summaries in the working context.
+
+## Exploration and stopping
+
+Consult previous lessons before generating another candidate. At most 4 recoverable alternatives may be retained outside lite mode. They remain separate from accepted output and mustn't violate mandatory constraints. Combining alternatives is a new attempt that needs fresh evaluation. Lite keeps only the active candidate and best checkpoint.
+
+After 4 consecutive evaluated candidates without acceptance, use one changed approach for up to 2 remaining attempts. If neither produces a gain, stop with `plateau`. This pivot never increases the total budget. Clear the no-gain count after an acceptance.
+
+Stop earlier for a verified terminal goal or when no testable improvement remains. Stop for cancellation, missing evaluation or exhausted resources. An environment failure permits one diagnosis and one retry within the original allowance, not repeated retries or another provider used to bypass a limit. Crashed and invalid attempts still consume the attempt budget.
+
+## Final verification
+
+Reserve roughly one fifth of the time allowance for final checks and reporting; this is a heuristic. Use host timeouts where available, but don't imply that Markdown can enforce process termination.
+
+Compare the selected version with the original baseline under the unchanged contract. Use genuinely held-out data when available. A holdout consumed during selection is no longer held out. Don't try several finalists against it and call the winner an unbiased confirmation.
+
+If a holdout fails, report that failure. Return an eligible checkpoint with its actual verification level; don't label a fallback as holdout-verified unless it was. A later development run needs a new untouched holdout. Without a holdout, label the result as checked on the available development cases only.
+
+The final report names the actual stop reason and distinguishes observed gains from unsupported claims. See [evaluators](evaluators.md) for further evidence limits.

package/bundled-skills/obsess/references/recipes.md

@@ -0,0 +1,51 @@
+# UI recipes
+
+These are risk-based starting points, not mandatory exhaustive audits. Use only the recipe relevant to the request. Test the actual product rather than building an unrelated demo. The checks below don't certify WCAG compliance.
+
+## Toggle: “make the transition super smooth”
+
+**Goal:** improve continuity during switching while preserving correct state changes.
+
+Inspect the current interaction before choosing a duration. Use the product's motion conventions rather than a universal “perfect” easing curve. Slower isn't automatically smoother.
+
+| Risk to inspect | Candidate check |
+|---|---|
+| Motion appears to snap when interrupted | Switch on and off, then reverse while motion is still running; inspect a recording when available |
+| Visual state lags behind actual state | Assert the underlying state after repeated input and inspect the endpoint |
+| Cosmetic changes damage interaction | Test keyboard activation and disabled behaviour; confirm the accessible state and label |
+| Motion ignores a user preference | Exercise the reduced-motion path separately and confirm state is still clear |
+
+Prefer focused CSS transitions where they fit. Consider transform/opacity rather than layout-affecting animation, but measure actual behaviour before claiming a performance gain. Avoid adding an animation library for one toggle without a clear need. The rendering guidance comes from Google's [animation performance guide](https://web.dev/articles/animations-guide).
+
+Keep the widget's established semantics. A switch should remain keyboard-operable with the appropriate checked state; Space is the required switch-pattern activation key, while Enter is optional. Don't accidentally fire an action twice by duplicating native keyboard handling. Refer to the [WAI-ARIA switch pattern](https://www.w3.org/WAI/ARIA/apg/patterns/switch/).
+
+Respect the user's motion preference instead of equating “super smooth” with “more animation”. The [`prefers-reduced-motion` media feature](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@media/prefers-reduced-motion) provides that signal. Reduced-motion support still needs a behaviour check.
+
+**Honest result:** “The captured reversal no longer visibly snaps in the tested browser; state assertions passed.” Only say this if that evidence was actually inspected. With source-only feedback, say “The patch changes the transition mechanism; rendered smoothness wasn't verified.”
+
+## Button: “obsess over the responsive design”
+
+**Goal:** retain a usable action when its available space changes.
+
+Identify the component's real parent layout. A narrow grid cell can fail even in a wide viewport. Don't fix overflow with page-wide clipping or by hiding meaningful label text.
+
+| Risk to inspect | Candidate check |
+|---|---|
+| Narrow layouts clip or overflow | Use a constrained parent and the smallest supported viewport; inspect the label and boundaries |
+| Content changes break sizing | Try a long label and existing icon variants where present |
+| Text enlargement loses content | Exercise supported text enlargement or zoom and confirm that the action remains available |
+| Responsive rules change behaviour | Check keyboard focus and activation; confirm the existing disabled/loading states where present |
+
+Begin with the project's documented support range. Without one, use 320 and 390 CSS-pixel viewports as narrow examples, plus an existing desktop layout and a constrained parent. These are starting checks, not complete device coverage. Also inspect around a changed breakpoint when relevant.
+
+The 320 CSS-pixel case is informed by W3C's [reflow explanation](https://www.w3.org/WAI/WCAG21/Understanding/reflow.html). Passing these local checks isn't a full accessibility assessment. Record browser zoom separately from viewport emulation; they aren't interchangeable tests.
+
+Don't shrink text or remove focus visibility merely to make the button fit. Preserve the existing semantic button rather than replacing it with a clickable generic element. See the [WAI-ARIA button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/) when custom behaviour needs review.
+
+**Honest result:** name the exact layouts checked and what stopped clipping. Don't claim “responsive on every device”. A unit test that finds a CSS class doesn't prove that the rendered label fits.
+
+## Spacing or other visual detail
+
+Use the existing design tokens and compare the affected region under matching content. Preserve nearby layout behaviour. A visually preferred alternative may be useful without being objectively “more correct”.
+
+Stop when the requested discrepancy is resolved and the relevant checks pass. Don't expand a spacing adjustment into a new component system.

package/bundled-skills/obsess/references/recovery.md

@@ -0,0 +1,50 @@
+# Run state and recovery
+
+These conventions make a session recoverable. They don't provide an autonomous runner or tamper-proof accounting.
+
+## Minimal run directory
+
+```text
+.obsess/<run-id>/
+  run.md
+  state.json
+  experiments.jsonl
+  snapshots/
+  evidence/
+```
+
+Use a unique, filesystem-safe run ID and an authorised alternate directory when required. Resolve the location safely; never accept a run ID that escapes the run directory. Don't store secrets or commit run data by default. Keep paths in notes relative when practical.
+
+A small polish run doesn't need a JSON contract in addition to `run.md`. The note still freezes the target and acceptance checks. Scalar optimisation can use `contract.json` because the receipt helper consumes it.
+
+The working tree may hold a provisional candidate while the accepted snapshot remains elsewhere. Record `working_tree_status` and the active candidate explicitly so a later session doesn't confuse them.
+
+## Cumulative accounting
+
+Increment `experiments_started` before the first candidate edit. An interrupted or invalid candidate consumes that attempt. Increment `experiments_evaluated` when evaluation completes, including a rejection. Don't double-count an existing candidate when finishing an interrupted evaluation. A materially new candidate consumes another attempt.
+
+Record cumulative active-session elapsed time. Setup and tool waits count, as do final checks. A deliberately closed/paused session doesn't consume inference time, but mustn't reset used minutes when resumed. If elapsed time can't be measured, store null with `elapsed_time_measured: false`, disclose the limitation and enforce the finite attempt cap as an instruction.
+
+A wall-clock timeout cannot be guaranteed by an instruction-only skill. Host process limits are separate. A requested AUD budget can only be treated as enforced when the host actually provides current pricing and hard accounting; otherwise say the limit can't be guaranteed.
+
+`remaining_experiments` is derived from the authorised cap minus started attempts. Don't trust a stale saved value. Only one writer should own a run. Save `state.json` atomically when possible and keep the attempt log append-only.
+
+## Status
+
+`status <run-id>` reads the stored state and evidence without editing target files or starting candidates. Report the last observed status, recorded usage and known remaining budget. State that the data is saved progress, not a live process. Don't fabricate missing evidence from notes that merely claim it exists.
+
+## Resume
+
+Read the note and state, then the relevant attempt summaries. Check actual contents against the saved baseline and incumbent. Reconcile interrupted work rather than assuming it completed. Checkpoint references and evidence must exist before relying on them.
+
+If files have changed externally, stop and explain the conflict. Don't roll the user's work backwards. Reuse the frozen goal and checks. A changed objective requires a new run, not an unrecorded extension of the old one.
+
+Retain all spent attempts and measured time. An exhausted allowance needs new explicit budget authorisation. Don't launch another run automatically to evade a cap. If persistence is missing, offer an in-session review but no durable resume promise.
+
+## v0.1 migration
+
+A v0.1 run remains an optimise-mode run under its original contract. Don't retrofit new polish limits or silently enable lite. Preserve the original snapshots and receipts.
+
+v0.1 state recorded `experiments_evaluated` rather than `experiments_started`. Reconstruct started attempts from its append-only records, including an unfinished candidate. If the count is uncertain, stop for reconciliation rather than assuming unrecorded work was free. Retain measured elapsed time; a false measurement flag means a numeric placeholder isn't trustworthy.
+
+Existing v0.1 scalar receipt schema remains supported. The v0.2 state schema is a record format, not an automatic migration tool.

package/bundled-skills/obsess/scripts/gate.py

@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""Compare evaluator-produced scalar receipts. This does not authenticate evidence.
+
+Exit codes: 0 accept, 1 reject, 2 invalid input, 3 inconclusive.
+Requires Python 3.10+ and only the standard library. Makes no external calls.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import sys
+from decimal import Decimal
+from pathlib import Path
+from typing import Any
+
+MAX_INPUT_BYTES = 1_000_000
+
+
+def nonempty(value: Any, label: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{label} must be a non-empty string")
+    return value
+
+
+def number(value: Any, label: str) -> Decimal:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ValueError(f"{label} must be a finite JSON number")
+    try:
+        finite = math.isfinite(value)
+    except (OverflowError, TypeError):
+        finite = False
+    if not finite:
+        raise ValueError(f"{label} must be finite")
+    return Decimal(str(value))
+
+
+def object_value(value: Any, label: str) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise ValueError(f"{label} must be a JSON object")
+    return value
+
+
+def verdict(status: str, reason: str, delta: Decimal | None = None) -> dict[str, Any]:
+    result: dict[str, Any] = {
+        "status": status,
+        "reason": reason,
+        "basis": "reported_measurements_only",
+        "evidence_authenticated": False,
+    }
+    if delta is not None:
+        # String preserves decimal subtraction without binary floating-point noise.
+        result["improvement"] = str(delta)
+    return result
+
+
+def decide(contract: dict[str, Any], baseline: dict[str, Any],
+           candidate: dict[str, Any]) -> dict[str, Any]:
+    """Fail closed on incompatible receipts; no mutation or file operations."""
+    contract = object_value(contract, "contract")
+    if type(contract.get("schema_version")) is not int or contract["schema_version"] != 1:
+        raise ValueError("contract.schema_version must be integer 1")
+
+    for field in ("contract_id", "evaluator_revision", "comparison_key"):
+        nonempty(contract.get(field), f"contract.{field}")
+
+    metric = object_value(contract.get("primary_metric"), "primary_metric")
+    metric_name = nonempty(metric.get("name"), "primary_metric.name")
+    direction = metric.get("direction")
+    if direction not in ("minimise", "maximise"):
+        raise ValueError("direction must be 'minimise' or 'maximise'")
+    minimum = number(metric.get("min_delta"), "primary_metric.min_delta")
+    if minimum < 0:
+        raise ValueError("min_delta must not be negative")
+
+    gates = contract.get("required_gates")
+    if not isinstance(gates, list) or not gates:
+        raise ValueError("required_gates must be a non-empty list")
+    for gate in gates:
+        nonempty(gate, "required_gates item")
+    if len(set(gates)) != len(gates):
+        raise ValueError("required_gates must not contain duplicates")
+
+    values: dict[str, Decimal] = {}
+    receipts = {"baseline": baseline, "candidate": candidate}
+    for label, raw in receipts.items():
+        receipt = object_value(raw, label)
+        for field in ("contract_id", "evaluator_revision", "comparison_key"):
+            if receipt.get(field) != contract[field]:
+                raise ValueError(f"{label}.{field} doesn't match the frozen contract")
+        nonempty(receipt.get("artifact_id"), f"{label}.artifact_id")
+        if receipt.get("metric_name") != metric_name:
+            raise ValueError(f"{label}.metric_name doesn't match the contract")
+        if receipt.get("measurement_valid") is not True:
+            raise ValueError(f"{label}.measurement_valid must be true")
+        refs = receipt.get("evidence_refs")
+        if not isinstance(refs, list) or not refs:
+            raise ValueError(f"{label}.evidence_refs must be a non-empty list")
+        for ref in refs:
+            nonempty(ref, f"{label}.evidence_refs item")
+        results = object_value(receipt.get("gates"), f"{label}.gates")
+        for gate in gates:
+            if gate not in results or type(results[gate]) is not bool:
+                raise ValueError(f"{label}.gates.{gate} must be an explicit boolean")
+        values[label] = number(receipt.get("value"), f"{label}.value")
+
+    failed_baseline = [gate for gate in gates if not baseline["gates"][gate]]
+    if failed_baseline:
+        raise ValueError("baseline isn't eligible; resolve its contract failures before optimisation")
+
+    failed = [gate for gate in gates if not candidate["gates"][gate]]
+    if failed:
+        return verdict("reject", "Candidate failed mandatory gates: " + ", ".join(failed))
+
+    if baseline["artifact_id"] == candidate["artifact_id"]:
+        return verdict("inconclusive", "The candidate identifies the same artefact as the baseline")
+
+    delta = values["candidate"] - values["baseline"]
+    if direction == "minimise":
+        delta = -delta
+    if delta < 0:
+        return verdict("reject", "Candidate regressed on the primary metric", delta)
+    if delta == 0:
+        return verdict("inconclusive", "No improvement; retain the incumbent", delta)
+    if delta < minimum:
+        return verdict("inconclusive", "Improvement is below the agreed meaningful threshold", delta)
+    return verdict("accept", "Reported gates pass and the reported improvement meets the threshold", delta)
+
+
+def reject_constant(value: str) -> None:
+    raise ValueError(f"Non-finite JSON constant is forbidden: {value}")
+
+
+def unique_object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError(f"Duplicate JSON key: {key}")
+        result[key] = value
+    return result
+
+
+def read_json(path: Path) -> dict[str, Any]:
+    with path.open("rb") as stream:
+        data = stream.read(MAX_INPUT_BYTES + 1)
+    if len(data) > MAX_INPUT_BYTES:
+        raise ValueError(f"Input exceeds {MAX_INPUT_BYTES} bytes: {path}")
+    return object_value(json.loads(data.decode("utf-8"), parse_constant=reject_constant,
+                                   object_pairs_hook=unique_object), str(path))
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--contract", type=Path, required=True)
+    parser.add_argument("--baseline", type=Path, required=True)
+    parser.add_argument("--candidate", type=Path, required=True)
+    args = parser.parse_args(argv)
+    try:
+        result = decide(read_json(args.contract), read_json(args.baseline), read_json(args.candidate))
+    except (OSError, ValueError, TypeError, OverflowError, RecursionError) as exc:
+        result = verdict("invalid", str(exc))
+    print(json.dumps(result, ensure_ascii=False, allow_nan=False))
+    return {"accept": 0, "reject": 1, "invalid": 2, "inconclusive": 3}[result["status"]]
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/bundled-skills/obsess/scripts/install.py

@@ -0,0 +1,241 @@
+#!/usr/bin/env python3
+"""Install /obsess locally without network access or unapproved overwrites.
+
+Requires Python 3.10+. Install into an explicit project or the user's home.
+--upgrade preserves the prior installation outside the skills search path.
+Concurrent installers or external edits during installation aren't supported.
+"""
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+from datetime import datetime, timezone
+import json
+from pathlib import Path
+import shutil
+import sys
+import tempfile
+from typing import Any
+
+
+class InstallError(RuntimeError):
+    """A validation failure or a recoverable installation failure."""
+
+
+@dataclass(frozen=True)
+class Plan:
+    source: Path
+    config_root: Path
+    skill: Path
+    command: Path | None
+    duplicate_paths: tuple[Path, ...]
+    legacy_command: bool
+    upgrade: bool
+
+
+def check_path(path: Path, *, leaf_directory: bool | None = None) -> None:
+    """Refuse symlinks and files where a directory is required."""
+    if path.is_symlink():
+        raise InstallError(f"Refusing a symlinked path: {path}")
+    for parent in path.parents:
+        if parent.is_symlink():
+            raise InstallError(f"Refusing a symlinked parent: {parent}")
+        if parent.exists() and not parent.is_dir():
+            raise InstallError(f"A parent isn't a directory: {parent}")
+    if path.exists() and leaf_directory is not None:
+        expected = path.is_dir() if leaf_directory else path.is_file()
+        if not expected:
+            kind = "directory" if leaf_directory else "file"
+            raise InstallError(f"Expected a {kind}: {path}")
+
+
+def validate(plan: Plan) -> None:
+    if not plan.source.is_dir() or not (plan.source / "SKILL.md").is_file():
+        raise InstallError("Source must be the obsess skill directory containing SKILL.md")
+    for entry in plan.source.rglob("*"):
+        if entry.is_symlink():
+            raise InstallError(f"The package contains a symlink: {entry}")
+        if not entry.is_file() and not entry.is_dir():
+            raise InstallError(f"The package contains an unsupported file type: {entry}")
+    if plan.skill.is_relative_to(plan.source) or plan.source.is_relative_to(plan.skill):
+        raise InstallError("Source and installation directories mustn't overlap")
+    check_path(plan.config_root, leaf_directory=True)
+    check_path(plan.config_root / "obsess-backups", leaf_directory=True)
+    check_path(plan.skill, leaf_directory=True)
+    for competing in plan.duplicate_paths:
+        if competing.exists() or competing.is_symlink():
+            raise InstallError(
+                f"A same-name skill already exists at {competing}. "
+                "Upgrade that copy instead of creating a duplicate installation."
+            )
+    command_path = plan.config_root / "commands" / "obsess.md"
+    check_path(command_path, leaf_directory=False)
+    if plan.command is None and command_path.exists():
+        raise InstallError(
+            f"An /obsess command already exists at {command_path}. "
+            "Move it aside before native installation, or use --legacy-command for OpenCode."
+        )
+    destinations = [plan.skill] + ([plan.command] if plan.command is not None else [])
+    for destination in destinations:
+        if destination.exists() and not plan.upgrade:
+            raise InstallError(
+                f"Installation already exists: {destination}. "
+                "Use --upgrade to preserve a backup before replacing it."
+            )
+    if plan.legacy_command:
+        wrapper = plan.source / "references" / "integrations" / "opencode" / "obsess.md"
+        if not wrapper.is_file():
+            raise InstallError("The package is missing its OpenCode command wrapper")
+        skill_text = (plan.source / "SKILL.md").read_text(encoding="utf-8")
+        if skill_text.count('  opencode/slash: "true"') != 1:
+            raise InstallError("Expected exactly one native OpenCode slash flag in the source skill")
+
+
+def make_plan(source: Path, host: str, *, project: Path | None = None,
+              global_install: bool = False, home: Path | None = None,
+              legacy_command: bool = False, upgrade: bool = False) -> Plan:
+    if host not in {"claude", "opencode"}:
+        raise InstallError("host must be claude or opencode")
+    if global_install == (project is not None):
+        raise InstallError("Choose exactly one of --project and --global")
+    if legacy_command and host != "opencode":
+        raise InstallError("--legacy-command is only supported for OpenCode")
+    source = source.expanduser().resolve(strict=True)
+    if global_install:
+        base = (home or Path.home()).expanduser().resolve(strict=True)
+        roots = (base / ".claude", base / ".config" / "opencode", base / ".agents")
+    else:
+        assert project is not None
+        base = project.expanduser().resolve(strict=True)
+        roots = (base / ".claude", base / ".opencode", base / ".agents")
+    if not base.is_dir():
+        raise InstallError(f"Installation base isn't a directory: {base}")
+    config_root = roots[0] if host == "claude" else roots[1]
+    skill = config_root / "skills" / "obsess"
+    duplicates = tuple(root / "skills" / "obsess" for root in roots if root != config_root)
+    plan = Plan(
+        source=source, config_root=config_root, skill=skill,
+        command=config_root / "commands" / "obsess.md" if legacy_command else None,
+        duplicate_paths=duplicates, legacy_command=legacy_command, upgrade=upgrade,
+    )
+    validate(plan)
+    return plan
+
+
+def describe(plan: Plan) -> dict[str, Any]:
+    return {
+        "skill": str(plan.skill),
+        "command": str(plan.command) if plan.command else None,
+        "upgrade_requested": plan.upgrade,
+        "native_opencode_slash": not plan.legacy_command,
+        "network_access": False,
+        "permissions_changed": False,
+    }
+
+
+def _promote(staged: Path, destination: Path) -> None:
+    staged.rename(destination)
+
+
+def install(plan: Plan, *, dry_run: bool = False) -> dict[str, Any]:
+    validate(plan)
+    result = describe(plan)
+    if dry_run:
+        return {**result, "status": "dry_run", "files_written": False}
+
+    plan.config_root.mkdir(parents=True, exist_ok=True)
+    stage = Path(tempfile.mkdtemp(prefix=".obsess-stage-", dir=plan.config_root))
+    promoted: list[Path] = []
+    backups: list[tuple[Path, Path]] = []
+    backup_root: Path | None = None
+    try:
+        staged_skill = stage / "skill"
+        shutil.copytree(
+            plan.source, staged_skill,
+            ignore=shutil.ignore_patterns("__pycache__", "*.pyc", ".git", ".DS_Store", ".pytest_cache"),
+        )
+        items: list[tuple[Path, Path, str]] = [(staged_skill, plan.skill, "skill")]
+        if plan.legacy_command:
+            installed_skill = staged_skill / "SKILL.md"
+            text = installed_skill.read_text(encoding="utf-8")
+            installed_skill.write_text(
+                text.replace('  opencode/slash: "true"', '  opencode/slash: "false"', 1),
+                encoding="utf-8",
+            )
+            staged_command = stage / "command.md"
+            shutil.copy2(plan.source / "references" / "integrations" / "opencode" / "obsess.md", staged_command)
+            assert plan.command is not None
+            items.append((staged_command, plan.command, "command.md"))
+
+        # Revalidate before touching existing installations. This isn't a concurrency lock.
+        validate(plan)
+        if any(destination.exists() for _, destination, _ in items):
+            backup_parent = plan.config_root / "obsess-backups"
+            backup_parent.mkdir(parents=True, exist_ok=True)
+            stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ-")
+            backup_root = Path(tempfile.mkdtemp(prefix=stamp, dir=backup_parent))
+        for staged, destination, backup_name in items:
+            destination.parent.mkdir(parents=True, exist_ok=True)
+            if destination.exists():
+                assert backup_root is not None
+                backup = backup_root / backup_name
+                destination.rename(backup)
+                backups.append((destination, backup))
+            _promote(staged, destination)
+            promoted.append(destination)
+        return {**result, "status": "installed", "files_written": True,
+                "backup": str(backup_root) if backup_root else None}
+    except Exception as exc:
+        rollback_errors: list[str] = []
+        for destination in reversed(promoted):
+            try:
+                if destination.is_dir():
+                    shutil.rmtree(destination)
+                elif destination.exists():
+                    destination.unlink()
+            except OSError as error:
+                rollback_errors.append(str(error))
+        for destination, backup in reversed(backups):
+            try:
+                if destination.exists() or destination.is_symlink():
+                    raise InstallError(f"Can't restore backup over an existing path: {destination}")
+                backup.rename(destination)
+            except (OSError, InstallError) as error:
+                rollback_errors.append(str(error))
+        if backup_root is not None:
+            try:
+                backup_root.rmdir()  # Remove only an empty, successfully restored backup.
+            except OSError:
+                pass
+        message = f"Installation failed: {exc}. Existing files were restored where possible."
+        if rollback_errors:
+            message += f" Backup location: {backup_root}. Recovery errors: " + "; ".join(rollback_errors)
+        raise InstallError(message) from exc
+    finally:
+        shutil.rmtree(stage, ignore_errors=True)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--host", required=True, choices=("claude", "opencode"))
+    target = parser.add_mutually_exclusive_group(required=True)
+    target.add_argument("--project", type=Path, help="Existing project directory")
+    target.add_argument("--global", dest="global_install", action="store_true", help="Install for this user")
+    parser.add_argument("--dry-run", action="store_true")
+    parser.add_argument("--upgrade", action="store_true", help="Back up an existing copy before replacement")
+    parser.add_argument("--legacy-command", action="store_true", help="Use an OpenCode command wrapper instead of native slash registration")
+    args = parser.parse_args(argv)
+    try:
+        plan = make_plan(Path(__file__).resolve().parents[1], args.host,
+                         project=args.project, global_install=args.global_install,
+                         legacy_command=args.legacy_command, upgrade=args.upgrade)
+        result = install(plan, dry_run=args.dry_run)
+    except (InstallError, OSError, ValueError) as exc:
+        print(json.dumps({"status": "error", "reason": str(exc)}, ensure_ascii=False), file=sys.stderr)
+        return 2
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())