@ahmed-g-gad/apothem 0.1.1

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

@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: MIT
+
+"""Materializer for the hermes harness — renders YAML config."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import yaml
+
+from apothem.lib.profile import coerce_profile
+from apothem.lib.profile_projection import mcp_servers_for, render_mcp_standard
+
+
+def materialize_native_config(profile: dict[str, Any]) -> str:
+    """Render the hermes native configuration from *profile*.
+
+    Renders the profile's MCP inventory under the native ``auxiliary.mcp`` block.
+    Apothem does NOT author ``skills.config`` — per the convention pin that key
+    is a list of installable registry *packages* (not a directory loader), so a
+    directory path there would be misread as a non-existent package. Apothem's
+    shared command/skill content lands under ``~/.hermes/apothem/`` (support
+    subtree) and the profile reaches Hermes through the projected managed-block
+    document. Returns a YAML string ready to be written to ``output_path``.
+    """
+    for_harness = coerce_profile(profile).for_harness("hermes")
+    header = (
+        "# hermes configuration — managed by Apothem\n"
+        "# Do not edit manually; run `apothem update --harness hermes` to regenerate.\n"
+    )
+    config: dict[str, object] = {}
+    mcp = render_mcp_standard(mcp_servers_for(for_harness))
+    if mcp:
+        config["auxiliary"] = {"mcp": mcp}
+    return header + yaml.safe_dump(config, sort_keys=False, allow_unicode=True)

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

@@ -0,0 +1,33 @@
+# SPDX-License-Identifier: MIT
+
+"""Uninstall logic for the hermes harness adapter."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from apothem.harnesses._shared import install_driver
+from apothem.harnesses.hermes.materializer import materialize_native_config
+
+_HARNESS_NAME: str = "hermes"
+
+
+def uninstall(output_path: Path) -> None:
+    """Remove Apothem-managed Hermes targets surgically.
+
+    The native ``config.yaml`` is rendered by the materializer rather than the
+    manifest, so it is cleaned here: only Apothem's keys (the ``auxiliary.mcp``
+    block) are stripped from the parsed operator YAML — operator channels / auth
+    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,
+        apothem_keys=frozenset({"auxiliary"}),
+    )
+    install_driver.run_uninstall(_HARNESS_NAME, harness_root=output_path.parent)

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

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

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

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

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

@@ -0,0 +1,128 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# Kimi Code Standard Convention Pin
+
+## Snapshot
+
+- Snapshot date: 2026-06-25
+- vendor-doc-url: <https://moonshotai.github.io/kimi-cli/en/configuration/config-files.html>
+- snapshot-date: 2026-06-25
+- Canonical docs host: `moonshotai.github.io/kimi-cli` (source repo `MoonshotAI/kimi-cli`); the legacy `kimi-code` docs host mirror-resolves but risks link-rot.
+- canonical-filename: `AGENTS.md`
+- canonical-schema: the universal AGENTS.md open standard (Markdown agent-instructions file at the project root)
+- Adapter source: `src/apothem/harnesses/kimi_code/`
+- Evidence level: adapter-local projection; no vendor-native UI claim is made here.
+
+## Official Surface Refresh
+
+- Re-verified live 2026-06-25 against `github.com/MoonshotAI/kimi-cli` +
+  `kimi-code`. Kimi Code (Moonshot) reads the project-root `AGENTS.md`
+  instruction file (universal AGENTS.md convention; `/init` generates it,
+  `KIMI_AGENTS_MD` consumes it) — CONFIRMED. FINDING (config-path discovery,
+  flagged not rewritten): the pin declares `kimi-cli` the canonical source yet
+  uses `<project>/.kimi-code/` project-scope paths, while the live kimi-cli docs
+  show user-scope `~/.kimi/config.toml` + `~/.kimi/` for config / sessions / MCP
+  and a conversational `/mcp-config` (`kimi mcp`) surface. The `kimi-code` vs
+  `kimi-cli` product distinction makes the project-scope `.kimi-code/` path
+  UNCERTAIN — it needs a targeted discovery pass against the actual `kimi-code`
+  product before any path rewrite; flagged here rather than guessed (M5: never
+  fabricate a path). The adapter authors no config / MCP entries, so no write is
+  affected by the ambiguity.
+- Canonical filename: `AGENTS.md` at the project root. The adapter is
+  project-scope and writes the apothem governance surface into `AGENTS.md` as a
+  sentinel-delimited managed block so operator prose outside the sentinels is
+  never clobbered.
+- Support tree: non-native Markdown cohorts (rules, commands, skills, agents,
+  templates) land under the Apothem-owned `<project>/.kimi-code/apothem/`
+  subtree and are referenced from the `AGENTS.md` anchor. They are never forced
+  into vendor-reserved configuration directories.
+- Model family: the Kimi Code model FAMILY is vendor-pinned and selected through
+  the operator's own Kimi Code configuration; the adapter authors no model id
+  and presets no model or effort preference.
+
+## Verification
+
+The vendor configuration surface at the pinned `vendor-doc-url` above was
+verified against vendor reality on `snapshot-date`. Adapter materializer output
+MUST produce an `AGENTS.md` managed block conforming to the universal AGENTS.md
+convention; deviations are findings per
+`rules/harness-adapter-shape.md` §4 Standard-Conformance.
+
+## MCP Surface Projection
+
+- Status: MCP is the recognized operator-owned surface at
+  `<project>/.kimi-code/mcp.json`. Apothem names this surface in
+  `capabilities.yml` but does not author MCP server entries; `.kimi-code/mcp.json`
+  is operator-owned and outside the adapter's write surface.
+- Boundary: the registry capability cell is `discovery-pending` — the pinned
+  snapshot catalogs the config-materialization surfaces, not the vendor MCP
+  schema, so Apothem claims only that the surface exists, not that it
+  materializes entries.
+
+## Tool-Surface Restriction Projection
+
+- Status: `discovery-pending`. The Kimi Code tool-permission surface is not yet
+  pinned against a vendor schema. The universal-deny floor (secrets paths,
+  destructive shell ops, network-write to unsigned endpoints) binds regardless
+  per `rules/agent-capability-discipline.md` §5 and is named in
+  `capabilities.yml` under `tool_surface_restrictions`.
+
+## Recommended Postfix Rendering
+
+- Status: supported as plain text.
+- Mechanism: Apothem emits the literal ` (Recommended)` suffix in the option
+  label. Kimi Code-facing prompts and fallback text preserve that suffix as
+  authored.
+- 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` — `AGENTS.md` plus the support tree; 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.
+
+## Refresh cadence
+
+Re-verify against vendor reality every 90 days. On refresh, update
+`snapshot-date` (and `vendor-doc-url` if the authority host moves) in the same
+change-set and emit a `[Pin — refreshed: kimi_code; …]` ledger entry per
+`rules/disclosure-ledger.md`. A pin whose `snapshot-date` exceeds 90 days
+against current vendor reality surfaces as a finding at the next adapter-touch
+boundary per `rules/harness-adapter-shape.md` §6 stale-pin discipline.
+
+## Plugin-alone Persistence
+
+Kimi Code exposes **no vendor plugin or extension install surface** that Apothem
+ships. The adapter is project-scope: it writes the `AGENTS.md` managed block plus
+an Apothem support tree under `<project>/.kimi-code/apothem/`. There is no
+standalone-installable bundle; every artifact requires the full
+`apothem install --harness kimi-code --project <path>` engine run.
+
+| Artifact class | Persists standalone? | Mechanism / limit |
+|---|---|---|
+| Context anchor (rules-as-text) | No — requires `apothem install` | `AGENTS.md` is written by the engine; nothing persists before that run. |
+| Rules / Commands / Skills / Agents / Templates | No — deliberate posture | The support tree under the Apothem-owned subtree is engine-materialized as reference material. NOTE: contrary to the prior framing, Kimi Code/CLI DOES document native skills (marketplace + GitHub install), built-in subagents (coder / explore / plan), slash commands (`/init`, `/plan`, `/mcp-config`), and agent specs — the adapter authors none of them (deliberate AGENTS.md-anchor posture), not an absence-of-surface claim. |
+| MCP servers | No — operator-owned | `.kimi-code/mcp.json` is operator-owned; the adapter authors no entries. |
+
+## Bindings
+
+- Established by ↑ `rules/harness-adapter-shape.md` §6.
+- Cross-bound with ↔ `src/apothem/harnesses/kimi_code/__init__.py` (the adapter
+  whose discovery walk this pin anchors).

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

@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: MIT
+
+"""Apothem harness adapter for kimi_code — project-scope install.
+
+Materializes the apothem instruction surface into the operator-supplied
+project root at ``<project>/AGENTS.md`` — the canonical Kimi Code CLI
+instruction file per the vendor configuration docs
+(https://moonshotai.github.io/kimi-cli/en/configuration/config-files.html,
+snapshot-date 2026-06-24). Kimi Code (Moonshot) reads project-root
+``AGENTS.md`` as its agent-instructions surface following the universal
+AGENTS.md convention; project configuration lives under
+``<project>/.kimi-code/``.
+
+The adapter writes the apothem governance surface into ``AGENTS.md`` as a
+sentinel-delimited managed block (operator prose outside the sentinels is
+preserved — identical to how the user-scope codex adapter handles its
+``AGENTS.md``, but project-scoped via ``${PROJECT_ROOT}``). Non-native
+Markdown cohorts (rules, commands, skills, agents, templates) land under an
+Apothem-owned support tree at ``<project>/.kimi-code/apothem/`` referenced
+from the instruction anchor. The ``.kimi-code/mcp.json`` MCP surface is
+operator-owned and out of apothem's adapter scope; the model FAMILY and
+its configuration are vendor-pinned, not adapter-authored.
+
+The adapter opts into the project-scope contract via
+``requires_project = True``; the CLI rejects an install / update /
+uninstall / verify invocation that omits ``--project <path>``. Delegates
+install logic to :mod:`apothem.harnesses.kimi_code.install`, which consumes
+the canonical propagation manifest at
+``src/apothem/lib/propagation-manifest.yaml``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from apothem.harnesses._shared.wrapper_factories import make_project_scope_adapter
+from apothem.harnesses.kimi_code.install import install as _install
+from apothem.harnesses.kimi_code.install import plan as _plan
+from apothem.harnesses.kimi_code.uninstall import uninstall as _uninstall
+from apothem.harnesses.kimi_code.update import update as _update
+from apothem.harnesses.kimi_code.verify import verify as _verify
+
+# Sentinel relative path used by ``output_path`` for display purposes
+# only. The real target is resolved per-install via
+# ``resolve_output_path(project)`` once the operator supplies
+# ``--project <path>``.
+_SENTINEL_RELATIVE: Path = Path("AGENTS.md")
+
+KimiCodeAdapter = make_project_scope_adapter(
+    "kimi-code",
+    error_label="kimi-code",
+    relative_target=_SENTINEL_RELATIVE,
+    install_fn=_install,
+    plan_fn=_plan,
+    uninstall_fn=_uninstall,
+    update_fn=_update,
+    verify_fn=_verify,
+    class_name="KimiCodeAdapter",
+)

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

@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: MIT
+
+# Per rules/agent-capability-discipline.md §1 / §3 / §7. The kimi_code
+# harness (Kimi Code CLI, Moonshot) reads project-root AGENTS.md as its
+# agent-instructions surface and keeps project configuration under
+# <project>/.kimi-code/. Apothem writes the AGENTS.md managed block plus an
+# Apothem support tree under <project>/.kimi-code/apothem/ for non-native
+# Markdown cohorts (rules, commands, skills, agents, templates). MCP is the
+# recognized operator-owned surface at <project>/.kimi-code/mcp.json; Apothem
+# names it but defers authoring entries. The vendor configuration docs are
+# pinned at https://moonshotai.github.io/kimi-cli/en/configuration/config-files.html
+# (snapshot-date 2026-06-25); the model FAMILY is vendor-pinned, never
+# adapter-authored.
+
+mcp_servers:
+  - project-scope-.kimi-code/mcp.json-operator-owned
+# Operator-owned MCP surface: the adapter recognizes it but authors no entries.
+mcp_servers_authored: false
+sub_agent_dispatch: true
+custom_command_support: "yes"
+recommended_postfix_rendering: "plain-text"
+long_context_compaction: "profile-managed"
+context_ignore_surface: "not-documented-in-current-pin"
+layered_context_surface: "AGENTS.md plus <project>/.kimi-code/apothem/{rules,commands,skills,agents,templates}"
+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: "templates/AGENTS.md"
+agent_memory_surface: "AGENTS.md durable context (memory bank)"

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

@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: MIT
+
+"""Install logic for the kimi_code harness adapter.
+
+Materializes the apothem Kimi Code instruction surface into the
+operator-supplied project root. Kimi Code's canonical instruction surface is
+the project-root ``AGENTS.md`` file (per the vendor configuration docs at
+https://moonshotai.github.io/kimi-cli/en/configuration/config-files.html);
+project configuration lives under ``<project>/.kimi-code/``. The adapter
+writes the apothem governance surface into ``AGENTS.md`` as a
+sentinel-delimited managed block so operator prose is never clobbered, and
+keeps non-native Markdown cohorts (rules, commands, skills, agents,
+templates) under an Apothem-owned support tree at
+``<project>/.kimi-code/apothem/`` referenced from the anchor.
+
+The propagation contract is declared in the canonical manifest at
+``src/apothem/lib/propagation-manifest.yaml`` under the ``kimi_code`` key
+(a single operator-owned ``sentinel_merge`` operation targeting
+``${PROJECT_ROOT}/AGENTS.md`` plus the apothem-owned support tree) 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 = "kimi_code"
+
+install = make_project_scope_install(
+    _HARNESS_NAME,
+    error_message="kimi-code adapter requires --project <path>; CLI must thread it through",
+)
+
+plan = make_project_scope_plan(_HARNESS_NAME)

package/src/apothem/harnesses/kimi_code/templates/AGENTS.md

@@ -0,0 +1,43 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# Apothem — Kimi Code Bootstrap
+
+This file is the vendor-canonical agent-instructions surface for the Kimi
+Code CLI (Moonshot): the project-root `AGENTS.md` per the vendor
+configuration docs
+(https://moonshotai.github.io/kimi-cli/en/configuration/config-files.html).
+It follows the universal AGENTS.md convention adopted across coding-agent
+ecosystems. Apothem materialises its governance surface into this file as a
+sentinel-delimited managed block and keeps non-native Markdown cohorts under
+an Apothem-owned support tree at `<project>/.kimi-code/apothem/`.
+
+## Apothem Conventions
+
+The Apothem-managed cohorts are installed as follows:
+
+- `<project>/AGENTS.md` — this Kimi Code instruction anchor, carrying the
+  Apothem governance surface as a managed block. Operator prose outside the
+  Apothem sentinels is preserved on every re-install.
+- `<project>/.kimi-code/apothem/rules/` — Apothem Markdown rules used as
+  reference material by this file and the installed cohorts.
+- `<project>/.kimi-code/apothem/skills/` — Apothem skills plus command prompts
+  wrapped as skills.
+- `<project>/.kimi-code/apothem/agents/` — Apothem sub-agent definitions.
+- `<project>/.kimi-code/apothem/templates/` — plan, report, and audit
+  templates.
+
+## Runtime Configuration
+
+Kimi Code CLI's runtime configuration lives under `<project>/.kimi-code/`.
+Apothem does not overwrite operator-owned configuration there; it installs
+instructions and support content through the vendor-native paths above. The
+`<project>/.kimi-code/mcp.json` MCP surface is operator-owned — Apothem names
+it but authors no entries. The Kimi Code model family is selected through the
+operator's own configuration; Apothem presets no model or effort.
+
+## Operator Surface
+
+Operators may extend project-specific instructions in this `AGENTS.md` outside
+the Apothem managed block. Re-run `apothem install --harness kimi-code
+--project <this-project-root>` to refresh this instruction anchor and the
+installed support cohorts. The operation is idempotent.

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

@@ -0,0 +1,27 @@
+# SPDX-License-Identifier: MIT
+
+"""Uninstall logic for the kimi_code harness adapter."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from apothem.harnesses._shared import install_driver
+
+_HARNESS_NAME: str = "kimi_code"
+
+
+def uninstall(output_path: Path, *, project: Path | None = None) -> None:
+    """Remove Apothem-managed Kimi Code targets surgically.
+
+    The ``AGENTS.md`` ``sentinel_merge`` anchor is cleaned by the shared
+    driver, which strips only Apothem's managed block (operator prose
+    survives), and the Apothem-owned support tree under
+    ``<project>/.kimi-code/apothem/`` is removed. The target is the
+    project-root ``AGENTS.md``, so the project root is its immediate parent
+    when ``project`` is not threaded through.
+    """
+    install_driver.run_uninstall(
+        _HARNESS_NAME,
+        project_root=project or output_path.parent,
+    )

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

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

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

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

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

@@ -0,0 +1,77 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# Kiro Standard Convention Pin
+
+## Snapshot
+
+- Snapshot date: 2026-06-25
+- Snapshot note: live re-verification against `kiro.dev/docs` surfaced TWO findings: (1) the steering inclusion-mode enumeration was INCOMPLETE — the vendor documents FOUR modes (`always | auto | fileMatch | manual`); the prior pin omitted `auto` (description-matched, skill-like inclusion); (2) STALENESS — the pin framed Kiro's skill/agent surface as absent, but the vendor documents Agent Skills (`kiro.dev/docs/skills`), CLI custom agents (`kiro.dev/docs/cli/custom-agents`), and Kiro powers (`POWER.md`). The adapter's rules-only steering delivery remains a DELIBERATE posture. `.kiro/steering/*.md` (workspace) + `~/.kiro/steering/` (global), specs (`.kiro/specs/`), agent hooks, and MCP (`.kiro/settings/mcp.json`) all confirmed current. Previous 2026-06-09.
+- Adapter source: `src/apothem/harnesses/kiro/`
+- Evidence level: adapter-local projection; no vendor-native UI claim is made here.
+- Vendor doc URL: https://kiro.dev/docs/steering/
+- Canonical filename: `.kiro/steering/apothem-rules.md`
+
+## Official Surface Refresh
+
+- Refreshed live 2026-06-09 against the current Kiro documentation
+  (`kiro.dev/docs`). No immutable version pin is exposed (mutable docs site),
+  so every captured convention carries a no-immutable-source exception.
+- Kiro reached general availability 2026 with a documented steering surface at
+  `.kiro/steering/*.md`. Steering files are Markdown with optional YAML front
+  matter controlling inclusion (`inclusion: always | auto | fileMatch | manual`,
+  with `fileMatchPattern` for the `fileMatch` mode and description-matched
+  inclusion for the `auto` mode). The adapter is project-scope and
+  writes only `<project>/.kiro/steering/apothem-rules.md` with
+  `inclusion: always`, so it never clobbers the operator-authored foundation
+  files (`product.md`, `tech.md`, `structure.md`).
+- MCP is recognized: `.kiro/settings/mcp.json` (workspace) and
+  `~/.kiro/settings/mcp.json` (user) are operator-owned; the adapter recognizes
+  them but does not author entries. `capabilities.yml` `mcp_servers` and the
+  shared capability matrix were set accordingly.
+- Steering is a `.kiro/steering/*.md` directory, not a single file;
+  `layered_context_surface` was set to match. Kiro also recognizes `AGENTS.md`
+  at the project root; the adapter does not write `AGENTS.md` (the dedicated
+  steering file is the deliberate, non-clobbering surface).
+- The vendor documents specs (`.kiro/specs/`), agent hooks, Agent Skills
+  (`kiro.dev/docs/skills`), CLI custom agents (`kiro.dev/docs/cli/custom-agents`),
+  and Kiro powers (`POWER.md`). The adapter delivers only the project steering
+  file and authors none of those cohorts: a DELIBERATE rules-only posture, not a
+  claim the surfaces are absent. Settings and status surfaces remain undocumented
+  as adapter-owned file surfaces.
+
+## Recommended Postfix Rendering
+
+- Status: supported as plain text.
+- Mechanism: Apothem emits the literal ` (Recommended)` suffix in the option label. Kiro steering files preserve that suffix as authored.
+- 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. Kiro steering inclusion modes (`always`, `fileMatch`, `manual`) are the vendor-native context-scoping mechanism; the adapter ships the `always` mode for its governance 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
+
+Kiro exposes **no vendor plugin or extension install surface** that Apothem
+ships. The adapter is project-scope rules-only: it writes a single merged
+steering file at `<project>/.kiro/steering/apothem-rules.md` (`inclusion: always`)
+and authors no other cohort. There is no standalone-installable bundle; every
+artifact requires the full `apothem install --harness kiro --project <path>`
+engine run.
+
+| Artifact class | Persists standalone? | Mechanism / limit |
+|---|---|---|
+| Rules (steering-as-text) | No — requires `apothem install` | The merged `apothem-rules.md` steering file (carrying the embedded behavioral mandates) is written only by the engine into the vendor-native `.kiro/steering/` directory. Nothing persists before that run. |
+| Commands / Skills / Agents | No — deliberate rules-only posture | Kiro documents specs (`.kiro/specs/`), agent hooks, Agent Skills, and CLI custom agents, but the adapter authors none of them (preserve-first rules-only delivery); these cohorts are not materialized for this harness by design. |
+| Hooks / MCP / Settings | No — operator-owned / platform limit | `.kiro/settings/mcp.json` (MCP) and the foundation steering files are operator-owned; the adapter authors no entries. |
+
+Platform limit: Kiro ships no marketplace/extension channel, so a plugin-alone
+story does not exist — the merged steering file via `apothem install` is the sole
+persistence surface.

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

@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: MIT
+
+"""Apothem harness adapter for kiro — project-scope install.
+
+Materializes the apothem rules surface into the operator-supplied
+project root 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; the adapter writes only its own ``apothem-rules.md``
+steering file and never clobbers them. Kiro specs
+(``.kiro/specs/``) and agent hooks are out of apothem's adapter scope.
+
+The adapter opts into the project-scope contract via
+``requires_project = True``; the CLI rejects an install / update /
+uninstall / verify invocation that omits ``--project <path>``. Delegates
+install logic to :mod:`apothem.harnesses.kiro.install`, which
+consumes the canonical propagation manifest at
+``src/apothem/lib/propagation-manifest.yaml``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from apothem.harnesses._shared.wrapper_factories import make_project_scope_adapter
+from apothem.harnesses.kiro.install import install as _install
+from apothem.harnesses.kiro.install import plan as _plan
+from apothem.harnesses.kiro.uninstall import uninstall as _uninstall
+from apothem.harnesses.kiro.update import update as _update
+from apothem.harnesses.kiro.verify import verify as _verify
+
+# Sentinel relative path used by ``output_path`` for display purposes
+# only. The real target is resolved per-install via
+# ``resolve_output_path(project)`` once the operator supplies
+# ``--project <path>``.
+_SENTINEL_RELATIVE: Path = Path(".kiro") / "steering" / "apothem-rules.md"
+
+KiroAdapter = make_project_scope_adapter(
+    "kiro",
+    error_label="kiro",
+    relative_target=_SENTINEL_RELATIVE,
+    install_fn=_install,
+    plan_fn=_plan,
+    uninstall_fn=_uninstall,
+    update_fn=_update,
+    verify_fn=_verify,
+    class_name="KiroAdapter",
+)

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

@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: MIT
+
+# Per rules/agent-capability-discipline.md §1 / §3 / §7. Kiro
+# ratifies MCP via .kiro/settings/mcp.json (workspace) and
+# ~/.kiro/settings/mcp.json (user) — both operator-owned; the adapter
+# recognizes them but does not author entries. The adapter delivers a
+# single project steering file under .kiro/steering/ and does not
+# dispatch sub-agents or author spec/hook cohorts.
+
+mcp_servers:
+  - workspace-scope-.kiro/settings/mcp.json
+  - user-scope-~/.kiro/settings/mcp.json
+# Operator-owned MCP surface: the adapter recognizes it but authors no entries.
+mcp_servers_authored: false
+sub_agent_dispatch: false
+custom_command_support: "no"
+recommended_postfix_rendering: "plain-text"
+long_context_compaction: "profile-managed"
+context_ignore_surface: "not-documented-in-current-pin"
+layered_context_surface: ".kiro/steering/*.md directory"
+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: "templates/apothem-rules.md"
+agent_memory_surface: "kiro-steering-persistent-context"