harness-everything 0.2.2 → 0.4.0

package/docs/mechanism-first-skill-mesh.md

@@ -0,0 +1,165 @@
+# Mechanism-First Skill Mesh
+
+Harness is not intended to be a rigid workflow engine. Its skills should remain independently useful, while still coordinating through lightweight mechanisms that help the model and the software engineer work together with less drift, fewer loops, and better evidence.
+
+The preferred shape is a **mechanism-first skill mesh**: skills are autonomous, coordination is explicit, and enforcement happens at narrow decision points through scripts, hooks, exit codes, and compact return values. Platform-specific enforcement claims follow [platform-capabilities.md](platform-capabilities.md).
+
+---
+
+## Design Intent
+
+Harness exists to improve engineering collaboration, not to replace model judgment with a fixed state machine.
+
+Each skill should be able to answer four questions on its own:
+
+1. **When should I activate?** The trigger should be clear without requiring another skill to interpret it.
+2. **What do I protect?** The skill should describe the failure mode it prevents or the engineering habit it reinforces.
+3. **What mechanism do I expose?** When possible, the skill should provide a script, command, checklist primitive, verifier, or return-value contract that makes its guidance concrete.
+4. **What should I hand to nearby skills?** The skill may recommend a next skill, but it should not require a global handoff template to remain useful.
+
+This keeps the system composable: `tdd` can run alone, `verification-loop` can run alone, `todo-driven-workflow` can run alone, and `harness-everything` can route among them when the task benefits from orchestration.
+
+---
+
+## Why Not a Single Handoff Block?
+
+A universal handoff block makes workflow state easy to parse, but it also has costs:
+
+- It encourages every platform and model to speak in the same rigid shape, even when a natural response would be clearer.
+- It can turn skills into a centralized workflow runner instead of a federation of local engineering disciplines.
+- It can make the model optimize for satisfying the template rather than making the best next engineering move.
+- It adds prompt weight on platforms where the mechanism cannot actually enforce the block.
+
+Harness should avoid mandatory global handoff text. Local skills may still use concise reports when they need them, but the mesh should not depend on one universal response format.
+
+---
+
+## Mechanisms Over Prose
+
+LLMs are highly sensitive to tool results, command outputs, exit codes, and short structured decisions. Harness should prefer those signals over long textual handoffs.
+
+Good mechanism outputs are:
+
+- **Short:** the result should be easy for the model to keep in active attention.
+- **Actionable:** the output should name the next constraint, gate, or recommended skill.
+- **Non-authoritarian:** the mechanism should guide the model without stealing all judgment from it.
+- **Portable:** hook-capable platforms can run the mechanism automatically; hook-less platforms can call the same script explicitly.
+
+Example shape:
+
+```text
+HARNESS_DECISION
+tier: 2
+required: route-before-execution, verify-before-claim, re-plan-after-repeat-failure
+suggest: todo-driven-workflow, verification-loop
+reason: user requested code changes
+```
+
+This is not a handoff block. It is a compact mechanical signal. The model remains free to decide how to present the work, explain trade-offs, and collaborate with the engineer.
+
+---
+
+## Skill Autonomy Contract
+
+Every skill in the mesh should remain useful when loaded directly.
+
+Recommended contract:
+
+- **Independent trigger:** the skill description should identify the problem or situation that activates it.
+- **Local workflow:** the skill should contain enough guidance to execute without reading the whole Harness ecosystem.
+- **Mechanism hook:** if a script can make the skill more reliable, expose it as an optional or required command.
+- **Neighbor links:** when another skill is commonly needed, recommend it by name and explain why.
+- **Exit discipline:** if the skill reaches a blocking state, it should say what evidence is missing or what human decision is needed.
+
+This contract keeps skills interoperable without requiring central ownership of every task path.
+
+---
+
+## Coordination Patterns
+
+Harness should coordinate skills through small, composable patterns.
+
+### Router Decision
+
+`harness-everything/scripts/kernel-router.js` is the public invariant-first runtime entry point. It delegates classification and guide discovery to `tier-router.js`, then returns the recommended tier, rationale, required invariants, and advisory skill suggestions. It intentionally does not emit a mandatory global execution pipeline.
+
+### Checklist State
+
+`todo-driven-workflow` may own explicit task decomposition state when that helps a Tier 2 or Tier 3 task. It is a suggested tactic, not a universal prerequisite, and the model may use native host TODO tracking or a Markdown checklist instead.
+
+### Verification Gate
+
+`verification-loop` and `verify-gate.js` provide reusable verification mechanisms. Hosts with a compatible stop/completion hook can invoke verification mechanically; instruction-only hosts can call the same verifier explicitly before final delivery.
+
+### Recovery Gate
+
+`rule-of-3` and `zoom-out` coordinate through failure signatures and recovery instructions where the host exposes the required lifecycle/tool hooks. On hosts without those hooks, `zoom-out` remains usable as an explicit recovery discipline, but the automatic failure counter must not be implied.
+
+### Skill Suggestion
+
+`self-evolve` and generated skills feed the router through manifest metadata. The router should surface likely skills, but the model keeps final responsibility for selecting what actually applies.
+
+---
+
+## Platform Strategy
+
+Harness should use the strongest mechanism each installation surface actually provides.
+
+| Platform class | Preferred coordination style | Enforcement level |
+| --- | --- | --- |
+| Hook/plugin-capable surfaces | Hooks/plugins run routers, guards, trackers, or completion gates automatically | Mechanical injection/blocking is possible for the mechanisms actually packaged |
+| CLI/tool-capable but hook-less surfaces | The model explicitly calls Harness scripts at decision points | Mechanism-guided, not automatically enforced |
+| Prompt-only surfaces | Advisory instructions include command snippets and decision rules | Self-regulated by the model |
+
+One host may expose more than one surface. Codex is the important example: the general `--codex` installer path is instruction/advisory oriented, while the **local OpenAI plugin** packages session, prompt, supported-tool, subagent, and stop hooks for mechanism-tested runtime enforcement. The public OpenAI **Skills-only** submission does not include those local lifecycle hooks.
+
+OpenCode is plugin-capable and has mechanism coverage, but live plugin loading remains unverified. Claude Code has the broadest currently verified Harness lifecycle-hook surface.
+
+---
+
+## Guidance for Instruction-Only / Hook-Less Paths
+
+Do not recreate hooks with a rigid universal handoff template. Instead, make mechanisms easy to call.
+
+Implemented today, both wired into `bin/cli.js` and referenced by name in the advisory text each platform's installer writes (`scripts/lib/advisory-text.js`):
+
+- `npx github:dyphn1/Harness-everything next "<prompt>"`: runs the Harness routing path and prints the recommended tier, invariant contract, and matching knowledge/skill suggestions.
+- `npx github:dyphn1/Harness-everything verify`: wraps `verify-gate.js`, running the target project's own lint/test scripts and exiting non-zero on failure. This is the explicit hook-less verification path; it is not equivalent to claiming that a host automatically runs a `Stop` hook.
+
+Both resolve their target scripts relative to the CLI's own package install, not the caller's cwd, so they work the same way regardless of which platform-specific directory (`.codex/skills/`, `.cursor/skills/`, `.github/skills/`, ...) a copy of the `harness-everything` skill also happens to be sitting in — a fixed relative path like `harness-everything/scripts/tier-router.js` would silently point at nothing depending on which platform installed it.
+
+Not yet implemented — still aspirational, do not reference these as if they exist until they're built:
+
+- `harness recover`: summarize repeated failure signatures and recommend `zoom-out` when needed. Hook-less paths do not collect failure signatures the way the Claude Code `PostToolUse` mechanism does, so there is no reliable state to summarize yet.
+- `harness skills`: list installed, generated, and matching skills for the current workspace.
+
+These commands let instruction-only Codex installs, Cursor, Copilot, Continue, and Hermes receive high-signal mechanical feedback without forcing them into a single scripted conversation shape.
+
+---
+
+## Anti-Goals
+
+Harness should not become:
+
+- A centralized DAG runner where every skill depends on one global workflow file.
+- A mandatory response-template system that suppresses useful model variation.
+- A command-only framework where skills cannot be understood by reading `SKILL.md`.
+- A hidden daemon that performs broad actions without visible evidence.
+- A platform-specific product that only works well when Claude Code hooks are available.
+
+The mesh should remain local, legible, and cooperative.
+
+---
+
+## Practical Authoring Rules
+
+When adding or revising a skill:
+
+1. Keep the skill independently executable.
+2. Add a script only when a mechanism can make the behavior more reliable than prose.
+3. Keep script output compact and stable enough for models to react to.
+4. Prefer gates at natural decision points: before editing, after repeated failure, before final delivery, and before persistence.
+5. Let the model choose wording and presentation unless the skill truly needs a specific artifact format.
+6. Document neighboring skills as recommendations, not hidden dependencies, unless the dependency is required for safety.
+
+The result should feel like an engineering co-pilot with good reflexes: autonomous where creativity matters, constrained where repeated mistakes are expensive, and explicit whenever evidence is needed.

package/docs/openai-plugin.md

@@ -0,0 +1,118 @@
+# OpenAI / ChatGPT Plugin Packaging
+
+Harness Everything ships an Agent Plugin package under `plugins/harness-everything/`. The root skill directories remain canonical; packaged copies are synchronized from them.
+
+## Architecture
+
+```mermaid
+flowchart TD
+    U([User prompt]) --> H[UserPromptSubmit hook]
+    H --> K[Harness Kernel Router]
+    K --> I[Required invariants]
+    I --> A[Agent chooses useful domain skills]
+    A --> E[Execute / inspect / edit]
+    E --> P[PreToolUse guards]
+    P --> T[Supported local tool]
+    T --> Q[PostToolUse state and evidence]
+    Q --> V{Objective evidence?}
+    V -->|yes| D[Evidence-backed completion]
+    V -->|no| R[Diagnose and retry]
+    R --> F{Same-signature failure x3?}
+    F -->|no| E
+    F -->|yes| Z[Zoom out / re-plan]
+    Z --> E
+
+    S[SessionStart hook] --> C[Cognitive OS policy]
+    C --> K
+    G[SubagentStart / Stop] --> A
+    X[Stop hook] --> V
+```
+
+The local OpenAI adapter enforces cross-cutting invariants through the lifecycle events that it packages. Tier-specific skills remain advisory; the model may choose, combine, reorder, or skip them. Tool enforcement is limited to the host tool names declared in `hooks/hooks.json`.
+
+## Package layout
+
+```text
+plugins/harness-everything/
+├── plugin.json                 # portable Agent Plugin manifest
+├── .codex-plugin/plugin.json   # Codex compatibility manifest
+├── hooks/
+│   ├── hooks.json
+│   ├── session-start.js
+│   └── scripts/                # shared runtime hook dependencies
+└── skills/                     # 26 synchronized canonical skills
+```
+
+The portable manifest follows the Agent Plugins schema and uses a root `skills/` directory. OpenAI-specific hook and interface metadata lives under `extensions.com.openai`; the compatibility manifest keeps the legacy `.codex-plugin` shape for clients that still expect it. These are two distribution manifests for the same package, not two different products.
+
+The package is intentionally skill-only: it does not declare `mcpServers` or `apps`. Hooks are a local package capability and require the host’s trust/review flow; they are not a claim that every OpenAI surface provides the same lifecycle enforcement.
+
+Run:
+
+```bash
+npm run plugin:sync
+npm run test:plugin:openai
+npm run test:plugin:submission
+```
+
+`plugin:sync` refreshes package copies from canonical skill directories and copies the shared hook runtime/dependencies into the package. Text parity is normalized to LF so the same package is reproducible from Windows and Unix checkouts. The checks compare both skill trees byte-for-byte, validate both manifest forms, execute local hook entry points, and verify deterministic routing/runtime behavior.
+
+## Managed ChatGPT workspace import
+
+OpenAI documents GitHub marketplace import for workspace administrators. The repository provides both `.agents/plugins/marketplace.json` and `.claude-plugin/marketplace.json`; the source entry resolves to `plugins/harness-everything/`.
+
+Use the repository URL as the source, leave Path empty so the marketplace is read from the repository root, and select the intended branch (normally `main`). In ChatGPT, use **Workspace settings > Plugins > Add > Import marketplace**, review the import results, and set the workspace installation policy. OpenAI documents automatic daily synchronization and a **Sync now** action for later refreshes.
+
+This repository contains the marketplace/package artifacts and deterministic import-shape checks. It does not contain a managed-workspace import report or a fresh host smoke-test artifact, so those operations remain `Unknown` in the compatibility matrix.
+
+Official documentation: [Importing and syncing plugin marketplaces from GitHub](https://help.openai.com/en/articles/20001504-importing-and-syncing-plugin-marketplaces-from-github) and [Plugins in Codex](https://help.openai.com/en/articles/20001256-plugins-in-codex).
+
+## Local Codex / OpenAI package
+
+The local package path is distinct from the general `--codex` installer. The general installer writes advisory `AGENTS.md` and repo-scoped `.agents/skills/`; the plugin package additionally contains local session, prompt, supported-tool, subagent, and stop hooks.
+
+The package tests prove the following repository-side contract:
+
+- the portable root manifest and `.codex-plugin` compatibility manifest agree on identity, version, interface, and hook entry point;
+- the root `skills/` tree contains exactly the 26 canonical skills;
+- Windows and POSIX hook commands resolve through `PLUGIN_ROOT`;
+- session start emits the compact policy and prompt submission invokes invariant-first routing;
+- supported local `Bash` and `apply_patch` calls receive the packaged guards and state tracking;
+- subagent lifecycle and stop verification contracts are covered;
+- identical routing input produces identical output.
+
+These are package/mechanism results. They do not prove that a live Codex or ChatGPT host loaded the package; a preserved host/session artifact is required for that claim. OpenAI’s current event/tool contract is documented in the [Codex/ChatGPT hooks reference](https://learn.chatgpt.com/docs/hooks).
+
+## Public Skills-only submission
+
+OpenAI’s public submission flow supports a **Skills only** plugin. This is separate from managed-workspace marketplace import and from the local hook-capable package.
+
+Build the final upload from the synchronized package:
+
+```bash
+npm run plugin:submission:build
+```
+
+The generated ZIP contains only `skills/<name>/...` files from `plugins/harness-everything/skills/`. It does **not** include the local `.codex-plugin` lifecycle hooks, MCP definitions, or a fake app wrapper. The generated manifest records every path, byte count, file hash, and final bundle hash; repeated builds from the same revision must match.
+
+The submission source files in [`../submission/openai/`](../submission/openai/) model the official review inputs: listing metadata, starter prompts, release notes, exactly five positive cases, and exactly three negative cases. Positive cases specify the prompt, expected skill/workflow behavior, expected result shape, and fixture/account data. Negative cases specify the prompt/scenario, expected refusal/clarification/safe fallback, and why completion is not appropriate.
+
+The official portal flow is: **Create plugin → Skills only → upload the final skill bundle → provide review cases and listing metadata → complete identity, availability, policy, and access requirements → submit for review → publish after approval**. The repository cannot complete verified identity, logo upload, availability selection, Apps Management write access, review, approval, or public-directory publication.
+
+Official documentation: [Submit a plugin](https://developers.openai.com/plugins/deploy/submission) and [Build plugins](https://developers.openai.com/plugins/build/plugins).
+
+## Evidence boundary
+
+The local plugin and public Skills-only artifact must not be conflated:
+
+| Artifact | Repository evidence | Claim that is safe today |
+| --- | --- | --- |
+| Portable/root plugin package | Manifest, tree, hook, and routing mechanism tests | Package shape and local mechanism are verified |
+| Managed workspace marketplace | Marketplace JSON and source-path checks | Import-ready repository artifact; live import remains unverified |
+| Public Skills-only ZIP | Deterministic builder and 5+3 review-input checks | Reproducible skills bundle; approval and live public behavior remain unverified |
+
+See the [platform capability matrix](platform-capabilities.md) for the complete ten-dimension status table and official source URLs.
+
+## Publication smoke checklist
+
+Before public submission, run `plugin:sync`, both OpenAI package checks, and the platform compatibility check. Confirm all 26 skills are content-identical to canonical sources after EOL normalization, the ZIP is reproducible, public links are current, the publisher identity and Apps Management access are ready, and final reviewer-facing cases run against the exact submitted skills tree.

package/docs/philosophy.md

@@ -1,45 +1,58 @@
-# Harness Philosophy
-
-Harness is built on a single, core belief: **AI coding models are highly capable, but they struggle with self-regulation, attention drift, and environment awareness.** 
-
-Instead of replacing the model or restricting it with heavy, opinionated frameworks that stifle creativity, Harness acts as a **behavioral runtime**—a lightweight, non-intrusive layer that guides, guards, and immunizes.
-
----
-
-## The Core Philosophy: Intervene Only When Necessary
-
-Many AI development frameworks attempt to fully control the model's execution flow. They use rigid DAGs, forced chains, or complex state machines. While this works for trivial, repetitive tasks, it destroys the model's creative problem-solving capability when tackling complex, novel engineering challenges.
-
-Harness takes the opposite approach:
-
-1. **Model Autonomy is Paramount:** The model should have full freedom to explore, choose its tools, and design its solution.
-2. **Context-Driven Guidance:** Harness injects high-context, low-friction signals (via hooks, rules, and local preflight checks) rather than forcing rigid execution paths.
-3. **Reactive Guardrails:** Harness remains completely silent and out of the way until a critical failure state is detected (e.g., repeating the same error 3 times, or context bloat reaching a dangerous threshold).
-4. **Behavior-First, Not Prompt-First:** Harness is not a collection of static templates or "magic prompts." It is a dynamic runtime that reacts to terminal outcomes, git status, and actual workspace conditions.
-
----
-
-## The 4 Pillars of AI Model Guidance
-
-To keep agents aligned and productive, Harness operates across four distinct domains:
-
-### 1. Environment Alignment (Discovery over Assumption)
-AI models often hallucinate terminal environments or make incorrect assumptions about the host operating system, shells, or package managers (especially on Windows or within sandboxed shells). 
-Harness forces a **Discovery** phase immediately upon session start. By auditing the environment beforehand, the model knows exactly what commands are safe to run, preventing wasted tokens on syntax trial-and-error.
-
-### 2. Guardrails (The Circuit Breakers)
-When a model gets stuck on a subtle bug or compiler error, its natural tendency is to make micro-adjustments repeatedly (the "infinite loop of trial-and-error"). 
-Harness implements a **Circuit Breaker** (the `Rule of 3`). If the exact same failure occurs three times, Harness halts execution and forces a "zoom out": the agent must rebuild the full picture and fact-check the assumptions behind its failed attempts before it may touch the code again. Most loops die right there, resolved by a fresh diagnosis. The human partner is asked to step in only when a genuine decision is on the table — a requirement conflict, an architecture trade-off, a destructive step — preserving both your token budget and your sanity.
-
-### 3. Context Preservation (Anti-Bloat Protection)
-As sessions grow, models often read too many large files or run commands that generate massive output, causing severe "Lost in the Middle" attention degradation. 
-Harness acts as an informational dashboard that tracks active file counts and staging queues, proactively nudging the model to commit changes, clean the terminal, or compact its context.
-
-### 4. Self-Evolution (Continuous Workspace Memory)
-When a complex issue is resolved, the model should never have to solve it again. Harness abstracts the underlying root cause and permanently saves it to local workspace rules. On subsequent sessions, the model immediately imports these lessons, preventing regression.
-
----
-
-## A Non-Intrusive Cognitive Amplifier
-
-Harness does not run a heavy daemon, send your code to third-party APIs, or lock you into a proprietary ecosystem. It runs entirely locally within your project, acting as a quiet guardian that ensures your AI sessions are efficient, secure, and successful.
+# Harness Philosophy
+
+Harness is built on a single, core belief: **AI coding models are highly capable, but they struggle with self-regulation, attention drift, and environment awareness.**
+
+Instead of replacing the model or restricting it with heavy, opinionated frameworks that stifle creativity, Harness acts as a **behavioral layer** — reusable skills plus the strongest lightweight runtime mechanisms each supported installation surface actually provides.
+
+The current mechanism/enforcement boundary is platform-specific; see [Platform Capability Matrix](platform-capabilities.md). A skill-only or instruction-only install must not be described as if it automatically runs lifecycle hooks.
+
+---
+
+## The Core Philosophy: Intervene Only When Necessary
+
+Many AI development frameworks attempt to fully control the model's execution flow. They use rigid DAGs, forced chains, or complex state machines. While this works for trivial, repetitive tasks, it can suppress useful model judgment on complex, novel engineering work.
+
+Harness takes the opposite approach:
+
+1. **Model Autonomy is Paramount:** The model should have freedom to explore, choose useful skills/tools, and design its solution inside a small set of cross-cutting invariants.
+2. **Context-Driven Guidance:** Harness uses high-context, low-friction signals — skills, rules, local checks, and hooks/plugins where the host supports and packages them — rather than one rigid global execution path.
+3. **Reactive Guardrails:** On integration surfaces that expose the required lifecycle/tool hooks, Harness can stay quiet until a boundary is violated or a repeated failure is detected. On advisory surfaces, the same principles remain guidance rather than automatic blocking.
+4. **Behavior-First, Not Prompt-First:** Harness is not a collection of magic prompts. Its skills remain independently useful, while supported runtime adapters can react to real tool/session outcomes and workspace conditions.
+
+---
+
+## The 4 Pillars of AI Model Guidance
+
+To keep agents aligned and productive, Harness operates across four distinct domains. The **principle** applies everywhere; whether it is injected or enforced automatically depends on the selected host surface.
+
+### 1. Environment Alignment (Discovery over Assumption)
+
+AI models often hallucinate terminal environments or make incorrect assumptions about the host operating system, shell, or package manager — especially on Windows or mixed-shell setups.
+
+Harness requires environment assumptions to be discovered rather than guessed. On surfaces that package a session-start/preflight hook, that context can be injected automatically. On instruction/skill-only paths, the agent must discover it explicitly before relying on shell-specific commands.
+
+### 2. Guardrails (The Circuit Breakers)
+
+When a model gets stuck on a subtle bug or compiler error, its natural tendency is to make micro-adjustments repeatedly.
+
+The Harness recovery invariant is to stop same-signature micro-retries and re-plan after repeated failure. On hosts where the Rule-of-3 mechanism is actually packaged, a circuit breaker can track failures and block further mutation until a `zoom-out` diagnosis is performed. On other surfaces, `zoom-out` remains a reusable recovery discipline but there is no claim that an automatic counter/blocker exists.
+
+### 3. Context Preservation (Anti-Bloat Protection)
+
+As sessions grow, models can read too broadly or produce oversized output, degrading active context.
+
+Harness uses narrow reads, explicit scope, compact evidence, and — where a compatible runtime adapter exists — boundary mechanisms that can react mechanically. Skill-only surfaces still receive the discipline, but not an imaginary background daemon or hook.
+
+### 4. Self-Evolution (Continuous Workspace Memory)
+
+When a complex issue is resolved, Harness can turn the verified lesson into durable workspace knowledge through `self-evolve`: a concise rule or a reusable generated skill, when persistence is actually justified.
+
+This long-term learning path is distinct from **runtime session state** such as WAL/checkpoint files. Runtime state exists only on integrations that package the corresponding state hooks; reusable rules/skills are project artifacts and can outlive a single host session.
+
+---
+
+## A Non-Intrusive Cognitive Amplifier
+
+Harness does not require a heavy daemon or a proprietary service. The repository's mechanisms and skill content operate locally in the developer/host environment, while each platform gets only the enforcement strength its real integration supports.
+
+For skill-level coordination, see [Mechanism-First Skill Mesh](mechanism-first-skill-mesh.md). For the exact current platform/install/evidence boundary, see [Platform Capability Matrix](platform-capabilities.md).

package/docs/platform-capabilities.md

@@ -0,0 +1,73 @@
+# Platform Capability Matrix
+
+This is the repository-wide source of truth for current platform integration, installation, and enforcement claims. The machine-readable matrix is [platform-compatibility.json](platform-compatibility.json); this page explains its evidence boundaries and the most important operator-facing paths.
+
+## Evidence policy
+
+The matrix separates standalone Agent Skills from plugin support, bundled skills, lifecycle hooks, project/global scope, install/uninstall symmetry, assets/references, update/sync, and live-host verification. A package or deterministic mechanism test cannot be promoted to `Live verified` without a preserved real-host session, import report, or portal artifact.
+
+Statuses are intentionally explicit:
+
+- `Supported`: official/native host support and a verified Harness path.
+- `Mechanism verified`: the repository package, adapter, or installer contract passes; a real host run is not confirmed.
+- `Live verified`: preserved evidence shows a real host session or portal operation.
+- `Partial`: only part of the capability is available or verified.
+- `Unsupported`: official host documentation explicitly rules out the capability.
+- `Unknown`: the capability or its current host behavior was not established.
+
+All current `liveHostVerification` rows are `Unknown`. This checkout contains deterministic package and installer evidence, but no fresh host-session artifacts, managed-workspace import report, or public OpenAI approval record.
+
+## Current capability summary
+
+| Platform surface | Standalone skills | Plugin support | Hooks/lifecycle | Project scope | Global scope | Current evidence boundary |
+| --- | --- | --- | --- | --- | --- | --- |
+| Codex | `Supported` | `Mechanism verified` | `Mechanism verified` for the local OpenAI package, including session, prompt, supported-tool, subagent, and stop hooks | `.agents/skills/`, `AGENTS.md` | `~/.agents/skills/` | Local package hooks are mechanically checked; live loading and marketplace refresh remain `Unknown`. |
+| ChatGPT / OpenAI Plugin | `Unknown` for a repository-local standalone path | `Mechanism verified` | `Partial`: local Work/Codex hooks are separate from ordinary Chat | Managed workspace marketplace | Not established | The public Skills-only bundle is mechanically reproducible; import, approval, and live behavior remain `Unknown`. |
+| Claude Code | `Supported` | `Supported` | `Mechanism verified` for Harness configuration | `.claude/skills/` | `~/.claude/skills/` | Native Claude surfaces are documented and package/installer checks pass; fresh-host execution is not preserved here. |
+| OpenCode | `Supported` | `Mechanism verified` | `Mechanism verified` against `tool.execute.*` and `session.idle` | `.opencode/skills/`, `.agents/skills/`, `.opencode/plugins/` | `~/.config/opencode/skills/`, `~/.agents/skills/`, `~/.config/opencode/plugins/` | The real adapter API is tested, but live plugin loading remains unverified. |
+| GitHub Copilot agent surfaces | `Supported` | `Unknown` for a Harness-specific plugin install | `Unknown` | `.github/skills/`, `.agents/skills/`, repository instructions | `~/.copilot/skills/`, `~/.agents/skills/` | GitHub Agent Skills paths and installer behavior are checked; no live Copilot session or plugin install is preserved. |
+| Cursor | `Supported` | `Mechanism verified` for the portable package shape | `Unknown` for Harness | `.cursor/skills/`, `.agents/skills/` | `~/.cursor/skills/`, `~/.agents/skills/` | Official paths and package shape are checked; Cursor plugin loading and hooks remain unverified. |
+| Continue.dev | `Unknown` for standalone `SKILL.md` discovery | `Unknown` | `Unknown` | `.continue/rules/` is documented; `.continue/skills/` is only an installer candidate | `~/.continue/skills/` is only an installer candidate | The reviewed official docs establish rules, not an Agent Skills host contract. |
+| Hermes Agent | `Supported` | `Unknown` | `Unknown` | `.hermes/skills/` or trusted `.agents/skills/` | `~/.hermes/skills/` | Skill installation and ownership are tested; project loading still follows Hermes trust, and no live session is preserved. |
+
+The full ten-dimension entries and official source URLs are in [platform-compatibility.json](platform-compatibility.json). “Supported” in the standalone-skills column refers to the host’s documented skill surface plus the repository’s verified path contract; it does not mean that a live Harness session was run on every platform.
+
+## Installer target contract
+
+The general installer’s target paths are tested independently from host discovery. This prevents a successful file copy from being reported as proof that an agent will load the file.
+
+| Installer target | Project scope | User/global scope | Host-support note |
+| --- | --- | --- | --- |
+| Claude Code | `.claude/skills/` | `~/.claude/skills/` | Official skill locations |
+| Cursor | `.cursor/skills/` | `~/.agents/skills/` | Official Agent Skills compatibility path |
+| GitHub Copilot agent surfaces | `.github/skills/` | `~/.agents/skills/` | Official project/global Agent Skills paths |
+| Codex | `.agents/skills/` | `~/.agents/skills/` | Official Agent Skills paths; `AGENTS.md` is separate instruction context |
+| Continue.dev | `.continue/skills/` | `~/.continue/skills/` | Installer adapter candidate; host discovery is `Unknown` from reviewed official docs |
+| Hermes Agent | `.agents/skills/` | `~/.hermes/skills/` | Project loading is subject to Hermes trust |
+
+These targets apply to both default link mode and explicit `--copy` mode. A canonical store is only a deduplication detail; it cannot make an unsupported host path supported. Install/uninstall tests also protect user-owned files and cover Linux, Windows, and macOS round-trip fixtures.
+
+## Codex / local OpenAI plugin boundary
+
+Codex has two paths that must not be collapsed:
+
+1. The general `--codex` installer writes advisory `AGENTS.md` plus repo-scoped skills under `.agents/skills/`.
+2. The local OpenAI plugin at `plugins/harness-everything/` packages the skills plus lifecycle hooks for session start, prompt routing, supported local tool calls, subagent lifecycle, and stop verification. Those hooks are mechanically checked, but no live plugin/session artifact is committed.
+
+The package is tested at the mechanism layer and remains subject to the host’s hook review/trust flow. A fresh host session is still required before claiming that a particular ChatGPT/Codex installation loaded and fired the hooks.
+
+The public OpenAI Skills-only plugin is narrower again. Its ZIP contains the packaged `skills/` tree and referenced files, but not the local `.codex-plugin` lifecycle hooks. Public submission readiness is therefore a package/form contract, not evidence of public-directory approval or live hook execution.
+
+## Install/uninstall ownership boundary
+
+The general installer merges shared files only through Harness-owned markers and removes only manifest-tracked artifacts. Malformed configuration and pre-existing user-owned files fail closed. Install/uninstall round-trip coverage protects user skills and runs on Linux, Windows, and macOS fixtures.
+
+## OpenCode boundary
+
+The OpenCode adapter uses the documented plugin API and has deterministic mechanism coverage. That proves the implementation contract only. **Live plugin loading remains unverified** until a real OpenCode session artifact demonstrates that the host loaded and fired the module.
+
+## Official sources
+
+The matrix records the official documentation reviewed for each platform. Important source families include [OpenAI plugin packaging](https://developers.openai.com/plugins/build/plugins), [OpenAI public submission](https://developers.openai.com/plugins/deploy/submission), [Codex skills](https://learn.chatgpt.com/docs/build-skills), [Codex hooks](https://learn.chatgpt.com/docs/hooks), [Claude skills](https://code.claude.com/docs/en/skills), [OpenCode skills](https://opencode.ai/docs/skills), [GitHub Copilot Agent Skills](https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/add-skills), [Cursor skills](https://cursor.com/docs/skills), [Continue rules](https://docs.continue.dev/customize/rules), and [Hermes skills](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills).
+
+When a platform behavior changes, update this page, `docs/platform-compatibility.json`, and every affected current-state surface in the same change. `npm run test:docs:capabilities` and the compatibility mechanism suite enforce the repository-side contract; they do not replace manual live-host evidence.