@ahmed-g-gad/apothem 0.1.1

package/src/apothem/harnesses/kiro/install.py

@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: MIT
+
+"""Install logic for the kiro harness adapter.
+
+Materializes the apothem Kiro steering surface into the operator-supplied
+project root. Kiro's canonical steering surface is the project-scope
+Markdown format at ``<project>/.kiro/steering/*.md`` (per
+https://kiro.dev/docs/steering/). The adapter writes a dedicated
+``apothem-rules.md`` steering file and never clobbers Kiro's
+operator-authored foundation files (``product.md``, ``tech.md``,
+``structure.md``).
+
+The propagation contract is declared in the canonical manifest at
+``src/apothem/lib/propagation-manifest.yaml`` under the ``kiro`` key
+(a single ``sentinel_merge`` operation targeting
+``${PROJECT_ROOT}/.kiro/steering/apothem-rules.md``) and applied by the
+shared driver at ``apothem.harnesses._shared.install_driver``. The
+``${PROJECT_ROOT}`` placeholder is substituted with the operator-supplied
+``--project <path>`` value the CLI threads through; absence of
+``--project`` is rejected upstream at ``apothem.cli._materialize`` via the
+``requires_project`` opt-in.
+"""
+
+from __future__ import annotations
+
+from apothem.harnesses._shared.wrapper_factories import (
+    make_project_scope_install,
+    make_project_scope_plan,
+)
+
+# Manifest harness key for this adapter.
+_HARNESS_NAME: str = "kiro"
+
+install = make_project_scope_install(
+    _HARNESS_NAME,
+    error_message="kiro adapter requires --project <path>; CLI must thread it through",
+)
+
+plan = make_project_scope_plan(_HARNESS_NAME)

package/src/apothem/harnesses/kiro/templates/apothem-rules.md

@@ -0,0 +1,36 @@
+---
+inclusion: always
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Apothem — Kiro Bootstrap
+
+This file is materialised by `apothem install --harness kiro --project <path>` and lands at `<project>/.kiro/steering/apothem-rules.md`, a dedicated Apothem steering file inside Kiro's documented steering directory per https://kiro.dev/docs/steering/. Kiro's foundation steering files (`product.md`, `tech.md`, `structure.md`) are operator-authored; this Apothem steering file is separate and never clobbers them. The `inclusion: always` front matter applies this governance surface on every interaction; `always` is the safe default because Apothem's mandates hold project-wide rather than for a file-pattern subset.
+
+## What Apothem governs in this project
+
+Apothem propagates a shared governance and convention surface across every supported AI harness in this project's host environment. Inside Kiro, the surface manifests as this `inclusion: always` steering file:
+
+- **Rules** — engineering rules applied on every interaction. The full rule cohort lives at the apothem source repository under `src/apothem/rules/`; this Kiro-facing anchor names the disciplines the operator may consult in detail.
+- **Skills, commands, agents** — reusable techniques, slash-style workflows, and persistent sub-agent definitions. Apothem's canonical-master cohort at the apothem source repository defines them; Kiro does not auto-discover them as separate surfaces, so they manifest here as referenced discipline.
+- **Specs** — Kiro's spec surface (`.kiro/specs/`) is operator-authored, not apothem-managed.
+- **Agent hooks** — Kiro's agent-hook surface is operator-authored, not apothem-managed.
+
+## Engineering disciplines in force
+
+Apothem's foundational mandates apply uniformly across every harness, including Kiro:
+
+- **Plans-Locality.** Plan-suite artefacts (PROGRESS.md, PLAN-NOTES.md, PHASE.md, REPORT.md) live under `<project>/.apothem/plans/{suite}/` — the sole canonical home; a legacy `<project>/.plans/` tree upgrades via `apothem migrate-workspace`. They never land in a global plans directory or any other global-ecosystem location.
+- **Authority hygiene.** Never fabricate identity, scope, security posture, or version-pin data. Surface ambiguity through a question instead of inventing a plausible-looking value.
+- **Definitiveness.** Hedging vocabulary (`maybe`, `might`, `usually`, `generally`, `typically`, `probably`) is eliminated where binding prescription is possible. Pre / post / failure conditions are stated on every contract.
+- **Production-ready discipline.** Every change ships in production-ready form — tests, docs, CHANGELOG entry, conformant commit message, CI green — in the same change-set.
+- **Plain-language.** Codebase artefacts and user-facing prose read as natural domain language with zero trace of internal planning structure.
+- **Human-only authorship.** Git commit messages, PR descriptions, branch names, and tag annotations carry human contributors only — never the underlying language model, runtime, IDE extension, or any automated tool as a co-author.
+- **Lean-context delegation.** Where the host provides delegated-worker dispatch, broad reads and heavy workloads route to a spawned worker by default so the main working context stays lean. The heavy parallel apparatus stays opt-in; routing delegable work away from the main thread is the standing posture once dispatch is available.
+- **Observe-decide-act discipline.** Tool use runs as a loop — observe the current state, decide the next move from what was observed, then act — never an edit before a read or a result asserted before a check. Independent reads and searches run together in one pass, not one per turn; the loop closes on a verifiable condition (a gate green, a read confirmed), never a fixed number of tries. Advisory, never an auto-applied behavior.
+- **Source accessibility.** When the authoritative source for a claim, convention, or version pin is closed, paywalled, login-gated, or otherwise unreachable, ask the operator for it in full rather than substituting a lower-trust open page. Trust outranks reachability.
+
+## Refreshing the file
+
+Re-run `apothem install --harness kiro --project <this-project-root>` to overwrite this file with the latest apothem template. The operation is idempotent. `apothem uninstall --harness kiro --project <this-project-root>` renames the file to a timestamped backup; `apothem verify --harness kiro --project <this-project-root>` checks the file is present and non-empty.

package/src/apothem/harnesses/kiro/uninstall.py

@@ -0,0 +1,25 @@
+# SPDX-License-Identifier: MIT
+
+"""Uninstall logic for the kiro harness adapter."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from apothem.harnesses._shared import install_driver
+
+_HARNESS_NAME: str = "kiro"
+
+
+def uninstall(output_path: Path, *, project: Path | None = None) -> None:
+    """Remove Apothem-managed Kiro targets surgically.
+
+    The apothem-rules ``sentinel_merge`` steering anchor is cleaned by the shared
+    driver, which strips only Apothem's managed block (operator prose survives),
+    deletes an Apothem-only file, and backs the file up under the Apothem backup
+    root — no whole-file ``.bak`` sibling is left beside the operator's file.
+    """
+    install_driver.run_uninstall(
+        _HARNESS_NAME,
+        project_root=project or output_path.parents[2],
+    )

package/src/apothem/harnesses/kiro/update.py

@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: MIT
+
+"""Update logic for the kiro harness adapter."""
+
+from __future__ import annotations
+
+from apothem.harnesses._shared.wrapper_factories import make_update_project
+from apothem.harnesses.kiro.install import install
+
+update = make_update_project(install)

package/src/apothem/harnesses/kiro/verify.py

@@ -0,0 +1,11 @@
+# SPDX-License-Identifier: MIT
+
+"""Verify logic for the kiro harness adapter."""
+
+from __future__ import annotations
+
+from apothem.harnesses._shared.wrapper_factories import make_verify_project
+
+_HARNESS_NAME: str = "kiro"
+
+verify = make_verify_project(_HARNESS_NAME)

package/src/apothem/harnesses/open_claw/STANDARD-CONVENTION-PIN.md

@@ -0,0 +1,62 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# Open-Claw Standard Convention Pin
+
+## Snapshot
+
+- Snapshot date: 2026-06-25
+- Snapshot note: live re-verification against `docs.openclaw.ai` surfaced two REFINEMENTS to the prior reading (see Evidence level): skills load from `~/.openclaw/skills` + agent workspaces and are THEN allowlist-filtered (not allowlist-only), and MCP servers live in an `mcp.servers` config block managed via the `openclaw mcp` CLI (not CLI-only). The adapter authors no skills/MCP entries either way, so no write is affected. Previous 2026-05-31.
+- Adapter source: `src/apothem/harnesses/open_claw/`
+- Evidence level: vendor-doc pinned (live re-fetch 2026-05-31) for
+  `~/.openclaw/openclaw.json` (JSON5). Skills load from `~/.openclaw/skills`
+  (shared root) plus each agent workspace, then are filtered by the effective
+  allowlist under `agents.defaults.skills` (per-agent override
+  `agents.list[].skills`) — the allowlist filters the directory-loaded set; the
+  specific `skills.load.extraDirs` key remains refuted. Subagents are documented
+  via `agents.list[].subagents.allowAgents` (with `maxConcurrent` /
+  `runTimeoutSeconds`). MCP servers live in the `mcp.servers` config block
+  (`mcp.*` changes hot-apply), managed via the `openclaw mcp` CLI subcommands
+  (list / show / set / unset). OpenClaw is a
+  multi-channel messaging gateway. No vendor-native UI claim is made here.
+  Versionless docs carry no version/SHA — no-immutable-source exception.
+- Official references:
+  - <https://docs.openclaw.ai/gateway/config-agents>
+  - <https://docs.openclaw.ai/cli>
+
+## Recommended Postfix Rendering
+
+- Status: supported as plain text.
+- Mechanism: Apothem emits the literal ` (Recommended)` suffix in the option label. Open-Claw adapter output preserves that suffix when prompt text is materialized.
+- Boundary: this pin does not claim a harness-native recommended-option widget. It only pins the text-rendered convention used by `rules/interactive-questions.md`.
+
+## Long Context and Compaction
+
+- Status: profile-managed.
+- Mechanism: Apothem keeps full-suite `/plan-execute` runs continuous by externalizing state to `.apothem/plans/`, compacting or restarting the harness session at phase boundaries as needed, and restoring via the Blind Bootstrap sequence.
+- Boundary: this pin does not claim vendor-native autocompaction or a long-context size. It pins the adapter-local state handoff and compaction-restoration convention used by `rules/context-management.md`.
+
+## Large-Codebase Practice Projection
+
+- Layered context: declared in `capabilities.yml` under `layered_context_surface`; no vendor-native hierarchy is claimed beyond the adapter's documented file/template surface.
+- LSP symbol navigation: `tracked-gap` until a vendor-ratified plugin or tool surface is pinned.
+- Hook learning capture: routed through the `persistent-conventions-vigilance` artifact-evolution cycle; pass-class hooks stay silent and recurring findings become rule, skill, hook, or documentation updates.
+
+## Plugin-alone Persistence
+
+OpenClaw is a multi-channel messaging gateway with **no vendor plugin or
+extension install surface** that Apothem ships. The adapter materializes
+`~/.openclaw/openclaw.json` (JSON5) via its materializer and keeps non-native
+cohorts under the Apothem support subtree (`~/.openclaw/apothem/`). There is no
+standalone-installable bundle; every artifact requires the full
+`apothem install --harness open-claw` engine run.
+
+| Artifact class | Persists standalone? | Mechanism / limit |
+|---|---|---|
+| Config / agents | No — requires `apothem install` | `~/.openclaw/openclaw.json` is materializer-rendered by the engine; nothing persists before that run. |
+| Commands / Skills / Agents / Rules | No — requires `apothem install` | These land under `~/.openclaw/apothem/` (support subtree) via the engine; OpenClaw `agents.defaults.skills` is a name-allowlist the adapter does not author. |
+| Hooks / Settings | No — platform limit | No Apothem-authored hook or settings surface beyond the config materializer. |
+| MCP | No — operator-owned | OpenClaw MCP servers live in the `mcp.servers` config block (managed via the `openclaw mcp` CLI subcommands; `mcp.*` hot-applies); the adapter authors no entries. |
+
+Platform limit: OpenClaw ships no marketplace/extension channel, so a
+plugin-alone story does not exist — the engine install is the sole persistence
+path.

package/src/apothem/harnesses/open_claw/__init__.py

@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: MIT
+
+"""Apothem harness adapter for open-claw.
+
+Materializes ``~/.openclaw/openclaw.json`` from the shared profile:
+OpenClaw's user-global configuration file. Delegates installation to
+:mod:`apothem.harnesses.open_claw.materializer`. OpenClaw's
+``agents.defaults.skills`` is a name allowlist (not a directory loader) and MCP
+is a CLI surface, so Apothem authors no config keys; the support cohort lands
+under ``~/.openclaw/apothem/`` and the projected profile document is written
+there as operator reference.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from apothem.harnesses._shared.wrapper_factories import make_native_config_adapter
+from apothem.harnesses.open_claw.install import install as _install
+from apothem.harnesses.open_claw.materializer import (
+    materialize_native_config as materialize_native_config,
+)
+from apothem.harnesses.open_claw.uninstall import uninstall as _uninstall
+from apothem.harnesses.open_claw.update import update as _update
+from apothem.harnesses.open_claw.verify import verify as _verify
+
+OpenClawAdapter = make_native_config_adapter(
+    "open-claw",
+    target_factory=lambda: Path.home() / ".openclaw/openclaw.json",
+    install_fn=_install,
+    uninstall_fn=_uninstall,
+    update_fn=_update,
+    verify_fn=_verify,
+    class_name="OpenClawAdapter",
+)

package/src/apothem/harnesses/open_claw/capabilities.yml

@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: MIT
+
+# Per rules/agent-capability-discipline.md §1 / §3 / §7. The open_claw
+# harness (a multi-channel messaging gateway) pins ~/.openclaw/openclaw.json
+# (JSON5). Skills are an allowlist of names under agents.defaults.skills (not a
+# directory loader); subagents are documented via
+# agents.list[].subagents.allowAgents. MCP is a CLI surface (openclaw mcp ...),
+# not a config-file block, so no MCP file surface is adapter-owned. Tool-surface
+# universal-deny floor binds regardless.
+
+mcp_servers: []
+# Operator-owned MCP surface: the adapter recognizes it but authors no entries.
+mcp_servers_authored: false
+sub_agent_dispatch: true
+custom_command_support: "skills-allowlist"
+recommended_postfix_rendering: "plain-text"
+long_context_compaction: "profile-managed"
+context_ignore_surface: "not-documented-in-current-pin"
+layered_context_surface: "openclaw.json plus agents.defaults.skills allowlist support skills"
+lsp_symbol_navigation: "tracked-gap-no-adapter-owned-LSP-surface"
+hook_learning_capture: "artifact-evolution-cycle"
+standard_convention_pin: "STANDARD-CONVENTION-PIN.md"
+# web-fetch / browser-retrieval surface — the backing capability dimension for
+# rules/source-accessibility.md step 1 ("retrieve through the host's browser /
+# fetch capability"). The pinned snapshot catalogs config-materialization
+# surfaces, not the vendor tool surface, so the web-fetch tool is not yet
+# discovered against the pin — discovery-pending per
+# rules/agent-capability-discipline-matrix.md §1.
+web_fetch: "discovery-pending"
+tool_surface_restrictions:
+  - secrets-paths
+  - destructive-shell-ops
+  - network-write-unsigned
+system_prompt_template_path: "n/a"
+agent_memory_surface: "n/a"

package/src/apothem/harnesses/open_claw/install.py

@@ -0,0 +1,17 @@
+# SPDX-License-Identifier: MIT
+
+"""Install logic for the open-claw harness adapter."""
+
+from __future__ import annotations
+
+from apothem.harnesses._shared.wrapper_factories import make_native_config_install
+from apothem.harnesses.open_claw.materializer import materialize_native_config
+
+_HARNESS_NAME: str = "open_claw"
+_HARNESS_ID: str = "open-claw"
+
+install = make_native_config_install(
+    _HARNESS_NAME,
+    materialize_native_config,
+    harness_id=_HARNESS_ID,
+)

package/src/apothem/harnesses/open_claw/materializer.py

@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: MIT
+
+"""Materializer for the open-claw harness — renders JSON config.
+
+OpenClaw's user-global config file (``~/.openclaw/openclaw.json``) is JSON with
+a vendor schema that rejects unknown top-level keys. Apothem authors no config
+keys here — it knows neither the operator's chosen skill names nor a file MCP
+surface — so the materializer emits an empty object; the projected managed-block
+profile document lands under the ``~/.openclaw/apothem/`` support subtree
+instead (see ``materialize_native_config``).
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def materialize_native_config(profile: dict[str, Any]) -> str:
+    """Render the open-claw native configuration from *profile*.
+
+    OpenClaw exposes skills as an allowlist of NAMES under
+    ``agents.defaults.skills`` (the earlier ``skills.load.extraDirs`` directory
+    loader was refuted) and manages MCP through the ``openclaw mcp`` CLI, not a
+    config-file block. Apothem knows neither the operator's chosen skill names
+    nor a file MCP surface here, so it authors no config keys — a directory path
+    in a name-allowlist would be misread as a (non-existent) skill name.
+    Apothem's shared command/skill content lands under ``~/.openclaw/apothem/``
+    (support subtree); the projected managed-block profile document is written
+    there as operator reference (OpenClaw has no auto-loaded instruction file,
+    so the operator wires it via the vendor's own mechanisms). Returns a JSON
+    string ready to be written to ``~/.openclaw/openclaw.json``.
+    """
+    _ = profile
+    config: dict[str, Any] = {}
+    return json.dumps(config, indent=2, ensure_ascii=False) + "\n"

package/src/apothem/harnesses/open_claw/uninstall.py

@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: MIT
+
+"""Uninstall logic for the open-claw harness adapter."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from apothem.harnesses._shared import install_driver
+from apothem.harnesses.open_claw.materializer import materialize_native_config
+
+_HARNESS_NAME: str = "open_claw"
+
+
+def uninstall(output_path: Path) -> None:
+    """Remove Apothem-managed OpenClaw targets surgically.
+
+    The native ``openclaw.json`` is rendered by the materializer rather than the
+    manifest, so it is cleaned here: only Apothem's keys are stripped from the
+    parsed operator JSON — operator-added keys survive — and the file is deleted
+    only when nothing operator-authored remains. The pre-mutation file is copied
+    into the Apothem backup root; no whole-file ``.bak`` sibling is left beside
+    the operator's file. The manifest support subtree is then cleaned
+    child-by-child by the shared driver.
+    """
+    install_driver.surgically_remove_materialized_config(
+        output_path,
+        materialize_native_config({}),
+        install_root=output_path.parent,
+        harness_name=_HARNESS_NAME,
+    )
+    install_driver.run_uninstall(_HARNESS_NAME, harness_root=output_path.parent)

package/src/apothem/harnesses/open_claw/update.py

@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: MIT
+
+"""Update logic for the open-claw harness adapter."""
+
+from __future__ import annotations
+
+from apothem.harnesses._shared.wrapper_factories import make_update
+from apothem.harnesses.open_claw.install import install
+
+update = make_update(install)

package/src/apothem/harnesses/open_claw/verify.py

@@ -0,0 +1,11 @@
+# SPDX-License-Identifier: MIT
+
+"""Verify logic for the open_claw harness adapter."""
+
+from __future__ import annotations
+
+from apothem.harnesses._shared.wrapper_factories import make_verify_native_config
+
+_HARNESS_NAME: str = "open_claw"
+
+verify = make_verify_native_config(_HARNESS_NAME)

package/src/apothem/harnesses/opencode/STANDARD-CONVENTION-PIN.md

@@ -0,0 +1,76 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# OpenCode Standard Convention Pin
+
+## Snapshot
+
+- Snapshot date: 2026-06-25
+- Snapshot note: live re-verification of `opencode.ai/docs` — `opencode.json` config sources (global `~/.config/opencode/opencode.json` + project), markdown agents/commands (plural `agents/`/`commands/` subdirs) with frontmatter, `skills/<name>/SKILL.md`, the AGENTS.md instruction-combination (`instructions` key), and `webfetch` (always-on) / `websearch` (provider/`OPENCODE_ENABLE_EXA`-gated) all confirmed current.
+- Adapter source: `src/apothem/harnesses/opencode/`
+- Evidence level: vendor-doc pinned (live re-fetch 2026-05-31) for
+  `opencode.json` and the `instructions`/`agent`/`command`/`mcp`/`plugin`
+  keys; skills are a documented native surface (`skills/<name>/SKILL.md`);
+  plugins are vendor-native (`plugin` key + `plugins/`) and operator-owned;
+  the native config is rendered directly (no Jinja template). No vendor-native
+  UI claim is made here. Rolling docs carry no version/SHA — no-immutable-source
+  exception on every source row.
+- Official references:
+  - <https://opencode.ai/docs/config/>
+  - <https://opencode.ai/docs/agents>
+  - <https://opencode.ai/docs/mcp-servers>
+  - <https://opencode.ai/docs/skills>
+  - <https://opencode.ai/docs/plugins>
+
+## Web-Fetch / Browser-Retrieval Surface
+
+- Capability: `web_fetch` = **partial**. The backing dimension for
+  `rules/source-accessibility.md` step 1 ("retrieve through the host's browser /
+  fetch capability").
+- Vendor-confirmed PARTIAL: opencode ships an unconditional built-in `webfetch`
+  tool (fetch + read web pages), but the `websearch` tool is available only when
+  using the OpenCode provider or when the `OPENCODE_ENABLE_EXA` env var is set.
+  The `partial` subset boundary is: fetch always-on, search provider/env-gated.
+- Evidence: vendor-doc-url <https://opencode.ai/docs/tools/> ("webfetch … Allows
+  the LLM to fetch and read web pages"; "websearch … only available when using
+  the OpenCode provider or when the `OPENCODE_ENABLE_EXA` environment variable is
+  set"); snapshot-id living docs; snapshot-date 2026-06-21.
+
+## Recommended Postfix Rendering
+
+- Status: supported as plain text.
+- Mechanism: Apothem emits the literal ` (Recommended)` suffix in the option label. OpenCode adapter output preserves that suffix when prompt text is materialized.
+- Boundary: this pin does not claim a harness-native recommended-option widget. It only pins the text-rendered convention used by `rules/interactive-questions.md`.
+
+## Long Context and Compaction
+
+- Status: profile-managed.
+- Mechanism: Apothem keeps full-suite `/plan-execute` runs continuous by externalizing state to `.apothem/plans/`, compacting or restarting the harness session at phase boundaries as needed, and restoring via the Blind Bootstrap sequence.
+- Boundary: this pin does not claim vendor-native autocompaction or a long-context size. It pins the adapter-local state handoff and compaction-restoration convention used by `rules/context-management.md`.
+
+## Large-Codebase Practice Projection
+
+- Layered context: declared in `capabilities.yml` under `layered_context_surface`; no vendor-native hierarchy is claimed beyond the adapter's documented file/template surface.
+- LSP symbol navigation: `tracked-gap` until a vendor-ratified plugin or tool surface is pinned.
+- Hook learning capture: routed through the `persistent-conventions-vigilance` artifact-evolution cycle; pass-class hooks stay silent and recurring findings become rule, skill, hook, or documentation updates.
+
+## Plugin-alone Persistence
+
+OpenCode documents a vendor-native `plugin` key plus a `plugins/` directory, but
+that surface is operator-owned and **Apothem ships no OpenCode plugin bundle** —
+and OpenCode exposes no harness-native plugin marketplace Apothem distributes
+through. The cohort lands via native skills/commands/agents surfaces, all written
+by the engine. There is no standalone-installable bundle; every artifact requires
+the full `apothem install --harness opencode` engine run.
+
+| Artifact class | Persists standalone? | Mechanism / limit |
+|---|---|---|
+| Skills | No — requires `apothem install` | Native `~/.config/opencode/skills/*/SKILL.md` is engine-written; no pre-built bundle carries it. |
+| Commands | No — requires `apothem install` | Apothem commands are engine-converted to OpenCode Markdown under `~/.config/opencode/commands/`. |
+| Agents | No — requires `apothem install` | Apothem agents are engine-converted to OpenCode Markdown under `~/.config/opencode/agents/`. |
+| Rules (as native primitive) | No — platform limit | OpenCode has no native rules-directory primitive; Apothem rules land as `~/.config/opencode/apothem/rules/` reference material via the engine. |
+| Hooks | No — platform limit | Engine support material only under `~/.config/opencode/apothem/hooks/`. |
+| MCP / Plugins / Settings | No — operator-owned | The `mcp` and `plugin` keys in `opencode.json` are operator-owned; the adapter authors no entries. |
+
+Platform limit: OpenCode's `plugin` surface is operator-owned and Apothem
+distributes no OpenCode plugin package, so a plugin-alone story does not exist —
+the engine install is the sole persistence path.

package/src/apothem/harnesses/opencode/__init__.py

@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: MIT
+
+"""Apothem harness adapter for opencode.
+
+Materializes ``~/.config/opencode/opencode.json`` per the opencode vendor
+canonical schema at https://opencode.ai/docs/config/ and the adapter-local
+``STANDARD-CONVENTION-PIN.md``. The POSIX-canonical path is uniform across
+supported platforms. The install step also propagates commands, skills, and
+subagents into OpenCode's native discovery directories and keeps unsupported
+reference material under ``~/.config/opencode/apothem``.
+Delegates installation to :mod:`apothem.harnesses.opencode.materializer`.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from apothem.harnesses._shared.wrapper_factories import make_native_config_adapter
+from apothem.harnesses.opencode.install import install as _install
+from apothem.harnesses.opencode.materializer import (
+    materialize_native_config as materialize_native_config,
+)
+from apothem.harnesses.opencode.uninstall import uninstall as _uninstall
+from apothem.harnesses.opencode.update import update as _update
+from apothem.harnesses.opencode.verify import verify as _verify
+
+OpenCodeAdapter = make_native_config_adapter(
+    "opencode",
+    target_factory=lambda: Path.home() / ".config/opencode/opencode.json",
+    install_fn=_install,
+    uninstall_fn=_uninstall,
+    update_fn=_update,
+    verify_fn=_verify,
+    class_name="OpenCodeAdapter",
+)

package/src/apothem/harnesses/opencode/capabilities.yml

@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: MIT
+
+# Per rules/agent-capability-discipline.md §1 / §3 / §7. opencode
+# anchors ~/.config/opencode/opencode.json (user-scope), then uses native
+# commands, skills, and agents discovery directories. Skills are a documented
+# native surface (skills/<name>/SKILL.md). Plugins are vendor-native (plugin
+# key + plugins/ directory) and operator-owned; no plugin package is authored.
+# MCP surface declared within opencode.json. Memory surface not documented as
+# durable. The native config is rendered directly (no Jinja template).
+
+mcp_servers:
+  - opencode.json-mcp-block
+# The adapter's materializer.py authors this MCP block from the shared profile.
+mcp_servers_authored: true
+sub_agent_dispatch: true
+custom_command_support: "markdown"
+recommended_postfix_rendering: "plain-text"
+long_context_compaction: "profile-managed"
+context_ignore_surface: "not-documented-in-current-pin"
+layered_context_surface: "opencode.json instructions plus native commands, skills, and agents"
+lsp_symbol_navigation: "tracked-gap-no-adapter-owned-LSP-surface"
+hook_learning_capture: "artifact-evolution-cycle"
+standard_convention_pin: "STANDARD-CONVENTION-PIN.md"
+# web-fetch / browser-retrieval surface — the backing capability dimension for
+# rules/source-accessibility.md step 1 ("retrieve through the host's browser /
+# fetch capability"). Vendor-confirmed PARTIAL: opencode ships an unconditional
+# built-in `webfetch` tool (fetch + read web pages), but the `websearch` tool is
+# available only when using the OpenCode provider or when the OPENCODE_ENABLE_EXA
+# env var is set. The `partial` subset boundary is: fetch always-on, search
+# provider/env-gated. Evidence triple — vendor-doc-url:
+# https://opencode.ai/docs/tools/ ("webfetch … Allows the LLM to fetch and read
+# web pages"; "websearch … only available when using the OpenCode provider or
+# when the OPENCODE_ENABLE_EXA environment variable is set"); snapshot-id: living
+# docs; snapshot-date: 2026-06-21. Canonical evidence home is
+# STANDARD-CONVENTION-PIN.md per rules/agent-capability-discipline-matrix.md §1A;
+# pin refresh tracked as a follow-up.
+web_fetch: "partial"
+tool_surface_restrictions:
+  - secrets-paths
+  - destructive-shell-ops
+  - network-write-unsigned
+system_prompt_template_path: "n/a"
+agent_memory_surface: "n/a"

package/src/apothem/harnesses/opencode/install.py

@@ -0,0 +1,17 @@
+# SPDX-License-Identifier: MIT
+
+"""Install logic for the opencode harness adapter."""
+
+from __future__ import annotations
+
+from apothem.harnesses._shared.wrapper_factories import make_native_config_install
+from apothem.harnesses.opencode.materializer import materialize_native_config
+
+_HARNESS_NAME: str = "opencode"
+_HARNESS_ID: str = "opencode"
+
+install = make_native_config_install(
+    _HARNESS_NAME,
+    materialize_native_config,
+    harness_id=_HARNESS_ID,
+)

package/src/apothem/harnesses/opencode/materializer.py

@@ -0,0 +1,31 @@
+# SPDX-License-Identifier: MIT
+
+"""Materializer for the opencode harness — renders JSON config."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from apothem.lib.profile import coerce_profile
+from apothem.lib.profile_projection import mcp_servers_for, render_mcp_opencode
+
+
+def materialize_native_config(profile: dict[str, Any]) -> str:
+    """Render the opencode native configuration from *profile*.
+
+    Renders the apothem instructions pointer plus the profile's MCP inventory
+    into opencode's native ``mcp`` surface. Returns a JSON string ready to be
+    written to ``output_path``.
+    """
+    for_harness = coerce_profile(profile).for_harness("opencode")
+    config: dict[str, Any] = {
+        "$schema": "https://opencode.ai/config.json",
+        "instructions": [
+            "~/.config/opencode/apothem/rules/*.md",
+        ],
+    }
+    mcp = render_mcp_opencode(mcp_servers_for(for_harness))
+    if mcp:
+        config["mcp"] = mcp
+    return json.dumps(config, indent=2, ensure_ascii=False) + "\n"

package/src/apothem/harnesses/opencode/uninstall.py

@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: MIT
+
+"""Uninstall logic for the opencode harness adapter."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from apothem.harnesses._shared import install_driver
+from apothem.harnesses.opencode.materializer import materialize_native_config
+
+_HARNESS_NAME: str = "opencode"
+
+
+def uninstall(output_path: Path) -> None:
+    """Remove Apothem-managed OpenCode targets surgically.
+
+    The native ``opencode.json`` is rendered by the materializer rather than the
+    manifest, so it is cleaned here: only Apothem's keys (``$schema``,
+    ``instructions``, and the profile-derived ``mcp`` block) are stripped from the
+    parsed operator JSON — operator-added keys and operator-added ``instructions``
+    entries survive — and the file is deleted only when nothing operator-authored
+    remains. The pre-mutation file is copied into the Apothem backup root; no
+    whole-file ``.bak`` sibling is left beside the operator's file. The manifest
+    support subtree is then cleaned child-by-child by the shared driver.
+    """
+    install_driver.surgically_remove_materialized_config(
+        output_path,
+        materialize_native_config({}),
+        install_root=output_path.parent,
+        harness_name=_HARNESS_NAME,
+        apothem_keys=frozenset({"mcp"}),
+    )
+    install_driver.run_uninstall(_HARNESS_NAME, harness_root=output_path.parent)

package/src/apothem/harnesses/opencode/update.py

@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: MIT
+
+"""Update logic for the opencode harness adapter."""
+
+from __future__ import annotations
+
+from apothem.harnesses._shared.wrapper_factories import make_update
+from apothem.harnesses.opencode.install import install
+
+update = make_update(install)

package/src/apothem/harnesses/opencode/verify.py

@@ -0,0 +1,11 @@
+# SPDX-License-Identifier: MIT
+
+"""Verify logic for the opencode harness adapter."""
+
+from __future__ import annotations
+
+from apothem.harnesses._shared.wrapper_factories import make_verify_native_config
+
+_HARNESS_NAME: str = "opencode"
+
+verify = make_verify_native_config(_HARNESS_NAME)