thoth-agents 0.2.11 → 0.3.0

package/README.md

@@ -1,428 +1,418 @@
 <div align="center">
-<img src="img/team.png" alt="thoth-agents agents" width="420">
-
-<p><i>Seven specialized agents, one delegate-first workflow across supported harnesses.</i></p>
-  <p><b>thoth-agents</b> - Multi-harness orchestration - Thoth-mem persistence - Bundled SDD pipeline</p>
+  <img src="img/thoth-agents-header.webp" alt="Seven human cyber-Egyptian thoth-agents roles, with Thoth as the Orchestrator centered between three read-only specialists and three implementation writers" width="100%">
+  <h1>Thoth-Agents</h1>
+  <p><i>Adaptive orchestration for OpenCode, Codex, and Claude Code.</i></p>
+  <p><b>Seven roles</b> · <b>Three SDD routes</b> · <b>Runtime-autonomous SDD</b></p>
   <p>
-    <a href="https://github.com/EremesNG/thoth-agents/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/EremesNG/thoth-agents/ci.yml?branch=master&label=CI" alt="CI status"></a>
-    <a href="https://www.npmjs.com/package/thoth-agents"><img src="https://img.shields.io/npm/v/thoth-agents?label=npm" alt="npm version"></a>
-    <a href="https://github.com/EremesNG/thoth-agents/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/thoth-agents" alt="MIT license"></a>
-    <img src="https://img.shields.io/node/v/thoth-agents" alt="Node.js version">
-    <img src="https://img.shields.io/badge/pnpm-11.2.2-F69220?logo=pnpm&logoColor=white" alt="pnpm 11.2.2">
+    <a href="https://www.npmjs.com/package/thoth-agents"><img src="https://img.shields.io/npm/v/thoth-agents?style=for-the-badge&amp;color=cb9b35&amp;label=npm" alt="npm version"></a>
+    <a href="https://github.com/EremesNG/thoth-agents/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/EremesNG/thoth-agents/ci.yml?branch=master&amp;style=for-the-badge&amp;label=CI" alt="CI status"></a>
+    <a href="package.json"><img src="https://img.shields.io/badge/node-%3E%3D22.13-43853d?style=for-the-badge&amp;logo=node.js&amp;logoColor=white" alt="Node 22.13 or newer"></a>
+    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-1f6feb?style=for-the-badge" alt="MIT License"></a>
   </p>
 </div>
 
 ---
 
-thoth-agents is a delegate-first agent system for coding harnesses. It started
-as an OpenCode plugin and now provides a shared seven-agent workflow for
-OpenCode, Codex, and Claude Code, with each harness getting the integration
-surface that fits it best.
-
-OpenCode remains the stable default path: native plugin install, native `task`
-delegation, optional tmux monitoring, and generated config. Codex is supported
-through an explicit agent-pack and Personal plugin setup path, with documented
-trust review and the current `collaboration.*` delegation surface. Codex can
-spawn and coordinate generic tasks programmatically, while named installed-role
-selection and per-role enforcement remain instruction-level. Claude Code is a first-class path: a
-single auto-discovered plugin package with native subagents, harness-enforced
-hooks, MCP, skills, and per-agent tool permissions.
-
-## What It Is
-
-- A canonical seven-agent roster: `orchestrator`, `explorer`, `librarian`,
-  `oracle`, `designer`, `quick`, and `deep`.
-- A delegate-first operating model that keeps the root coordinator focused on
-  decisions while specialists gather evidence, implement, review, and verify.
-- A bundled requirements interview and SDD pipeline for moving from ambiguous
-  requests to planned, verified implementation.
-- A thoth-mem integration for durable project memory, SDD artifacts, and
-  cross-session recovery.
-- A multi-harness package that preserves OpenCode defaults while adding a
-  Codex setup path.
-
-## What It Is Not
-
-- It is not a claim that every harness has identical runtime behavior.
-- It is not a replacement for each harness's security, trust, sandbox, or
-  approval model.
-- It does not rename the seven roles or require new visual assets.
-- It does not make Codex tmux-aware; tmux integration is scoped to OpenCode
-  child `task` sessions.
-
-## Harness Support
-
-
-| Harness     | Status                     | Setup path                                                                              | Notes                                                                                                                                                                                                                                                 |
-| ----------- | -------------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| OpenCode    | Stable default             | `npx thoth-agents@latest install` or `npx thoth-agents@latest install --agent=opencode` | Native plugin config, native`task` delegation, optional tmux panes, OpenCode provider auth.                                                                                                                                                           |
-| Codex       | Supported explicit path    | `npx thoth-agents@latest install --agent=codex`                                         | Installs ambient/root guidance, six role subagents, and a Personal plugin source. Uses the current `collaboration.*` tools for generic delegation; named-role selection and per-role enforcement remain instruction-level. Requires `/plugins` and `/hooks` trust review. |
-| Claude Code | Supported first-class path | `npx thoth-agents@latest install --agent=claude`                                        | Installs one Claude Code plugin: six specialist subagents (`Task(subagent_type: ...)`), an `orchestrator` agent activated as the main thread via `settings.json`, `.mcp.json`, and bundled skills. Role permissions are enforced by subagent `tools`. |
-
-OpenCode can load the plugin with:
-
-```jsonc
-{
-  "plugin": ["thoth-agents@latest"]
-}
-```
+## What it does
 
-That plugin entry is not a shell command. To run the installer or TUI, use the
-npm binary through a global install, `npx thoth-agents@latest`, or
-`pnpm dlx thoth-agents@latest`.
+thoth-agents is a multi-harness orchestration plugin for OpenCode, Codex, and
+Claude Code. One adaptive root handles clear bounded work directly and delegates
+only when specialization, context isolation, independent review, or safe
+parallelism creates a net gain.
 
-## Quick Start
+The plugin ships the seven-role contract and thoth-owned SDD
+contracts that combine Spec Kit-grade traceability with OpenSpec-style durable
+deltas. Accelerated planning fast-forwards without routine pauses; structural
+`ready`/`closeout` gates and independent oracle review retain rigor. During
+installation, the CLI obtains four mandatory external skills
+from their canonical repositories with `npx skills add` and invokes the official
+provider-owned thoth-mem setup for the selected harness. During an SDD, agents
+load local contracts and the installed thoth-mem guidance; they never need to
+invoke either CLI or download a phase contract.
 
-Run the binary with no arguments in an interactive terminal to open the
-multi-harness TUI:
+Delivery is intentionally asymmetric. OpenCode uses the CLI to configure the
+npm plugin, external skills, and thoth-mem. Codex needs both a native plugin and a mandatory
+CLI-managed global layer because its manifest cannot install custom agents or
+global root instructions. Claude needs its two native marketplace commands
+before the CLI installs external skills and requests provider-owned thoth-mem
+setup.
 
-```bash
-npx thoth-agents@latest
-```
+Runtime guarantees still differ by harness. OpenCode is the default and most
+integrated path; Codex and Claude preserve their own trust, policy, plugin-cache,
+and permission semantics.
 
-The same no-argument binary invocation falls back to the OpenCode install path
-in CI, redirected, or `TERM=dumb` terminals. Use explicit commands when you
-need deterministic automation.
+## Install
 
 ### OpenCode
 
+Install the plugin configuration, external skills, and thoth-mem companion:
+
 ```bash
-npx thoth-agents@latest install
+npx thoth-agents@latest install --agent=opencode --dry-run
 npx thoth-agents@latest install --agent=opencode
-opencode auth login
-opencode
 ```
 
-Then ask OpenCode to verify the roster:
+Restart OpenCode and initialize the current repository:
 
 ```text
-ping all agents
+/thoth-init
 ```
 
-For non-interactive setup:
+This copies the four thoth-owned workflow skills into `.agents/skills/` and
+creates missing `openspec/` governance files. The external skills are already in
+OpenCode's global skill root and thoth-mem has completed its own provider setup
+from the CLI step. Existing project-owned files are preserved.
 
-```bash
-npx thoth-agents@latest install --no-tui --tmux=no --skills=yes
-```
+### Codex
 
-Interactive status, list, update, sync, and model previews are available from
-the no-argument TUI. Command help also documents the explicit command names for
-terminal workflows.
+Register the repository marketplace from a terminal:
 
-### Codex
+```bash
+codex plugin marketplace add EremesNG/thoth-agents
+```
 
-Review the plan first, then install explicitly:
+Restart Codex, open `/plugins`, and install or enable `thoth-agents`. Then return
+to a terminal and apply the mandatory global layer:
 
 ```bash
 npx thoth-agents@latest install --agent=codex --dry-run
 npx thoth-agents@latest install --agent=codex
 ```
 
-Restart Codex and review plugin/hook trust:
+The CLI writes the orchestrator block to `~/.codex/AGENTS.md`, creates six
+custom-agent TOMLs under `~/.codex/agents/`, and merges the managed feature into
+`~/.codex/config.toml`. It also installs the external skills and invokes
+provider-owned thoth-mem setup. Restart Codex again, then initialize each target
+repository's SDD governance:
 
 ```text
-/plugins
-/hooks
+$thoth-init
 ```
 
-Codex install does not create a selectable orchestrator TOML, does not bypass
-trust review, and does not make role permissions or memory governance hard
-runtime guarantees unless Codex exposes those controls.
+The plugin contributes skills and MCP configuration. `$thoth-init` creates only
+missing `openspec/` governance files; it does not pretend to install agents.
 
-Generated root guidance binds delegation to direct `collaboration.*` tools:
-`spawn_agent({ task_name, message, fork_turns? })`, mailbox-oriented
-`wait_agent`, live status through `list_agents`, non-triggering `send_message`,
-turn-triggering `followup_task`, and explicit `interrupt_agent`. A wait timeout
-or silence remains in progress; it is not a collected result body.
+Review `/plugins` and `/hooks` after installation. Codex trust and
+higher-precedence instructions remain in force.
 
 ### Claude Code
 
-Preview, then install the plugin package:
+Claude requires its two native marketplace steps before the plugin can expose
+agents or skills:
 
 ```bash
-npx thoth-agents@latest install --agent=claude --dry-run
-npx thoth-agents@latest install --agent=claude
+claude plugin marketplace add EremesNG/thoth-agents --scope user
+claude plugin install thoth-agents@thoth-agents --scope user
 ```
 
-This writes a single Claude Code **skills-directory plugin** under
-`~/.claude/skills/thoth-agents`: `.claude-plugin/plugin.json`, seven
-auto-discovered agents in `agents/` (six specialists + an `orchestrator`), an
-`.mcp.json` server map, bundled `skills/`, and a plugin-root `settings.json`
-with `{ "agent": "orchestrator" }`. That `agent` key activates the orchestrator
-as the **main thread** — replacing the default system prompt — so the session
-starts in delegate-first mode and bootstraps thoth-mem on its first turn. It
-auto-loads as `thoth-agents@skills-dir` on the next session (no marketplace or
-install step); restart Claude Code or run `/reload-plugins` to activate it
-(confirm in `/plugin` → Installed). The orchestrator delegates to specialists
-with `Task(subagent_type: explorer|librarian|oracle|designer|quick|deep)`. Role
-permissions are enforced through each specialist's frontmatter `tools` allowlist.
-You can also emit the package without installing it:
+Then install the mandatory external skills and invoke provider-owned thoth-mem
+setup:
 
 ```bash
-npx thoth-agents@latest generate --harness=claude --dry-run
+npx thoth-agents@latest install --agent=claude --dry-run
+npx thoth-agents@latest install --agent=claude
 ```
 
-See [docs/claude-code-plugin-packaging.md](docs/claude-code-plugin-packaging.md).
-
-### Reset Generated Config
+Restart Claude Code or run `/reload-plugins`, then initialize the repository:
 
-```bash
-npx thoth-agents@latest install --reset
+```text
+/thoth-agents:thoth-init
 ```
 
-## Seven-Agent Roster
+Claude discovers the packaged orchestrator, six namespaced subagents, and four
+thoth-owned skills from the plugin. The CLI installs the external skills into
+Claude's global skill root and requires thoth-mem's own setup result to be
+complete. Init creates only the missing project governance files; it never edits
+Claude's manager-owned plugin cache.
 
-The delegate-first philosophy is simple: the `orchestrator` coordinates while
-specialists execute. Shared concepts are the same across harnesses, but the
-dispatch mechanism is harness-bound. In OpenCode, specialists are launched with
-the native `task` tool. In Codex, the installed role agents and plugin-bundled
-skills provide the closest supported workflow, with some behavior enforced by
-instructions rather than hard runtime APIs.
+See [Installation](docs/installation.md), [Codex Install](docs/codex-install.md),
+and [Claude Code Install](docs/claude-code-install.md) for scopes, verification,
+and limitations.
 
-### Primary Agent
+## Seven roles
+
+One adaptive root and six specialists cover repository discovery, authoritative
+research, independent verification, UI/UX, narrow implementation, and
+correctness-critical work.
+
+### Adaptive root
 
 <table width="100%">
   <tr>
-    <td width="100%" valign="top">
-      <img src="img/orchestrator.png" width="100%" alt="Orchestrator">
-      <br>
+    <td width="34%" align="center" valign="top">
+      <img src="img/agents/orchestrator.webp" width="240" alt="Human cyber-Egyptian interpretation of Thoth coordinating the team as Orchestrator">
+    </td>
+    <td width="66%" valign="top">
       <b>Orchestrator</b>
       <br>
-      <i>Root coordinator and sole primary agent.</i>
+      <i>Adaptive root and final synthesis.</i>
       <br><br>
-      <b>Role:</b> The root coordinator. Handles delegation, sequencing, memory ownership, requirements routing, and SDD progress tracking. Does not read or modify source files directly when running as the root coordinator.
-      <br>
-      <b>Mode:</b> primary, non-mutating
-      <br>
-      <b>Dispatch:</b> sync coordinator
-      <br>
-      <b>Recommended:</b>
-      <br>
-      <code>anthropic/claude-opus-4-6</code> - <code>openai/gpt-5.4</code> - <code>kimi-for-coding/k2p5</code>
-      <br>
-      <b>Personality:</b> Autonomous deep coordinator; owns decisions and works through specialists.
+      Keeps task ownership and synthesis, chooses the route, coordinates SDD
+      artifacts, and implements bounded work directly.
+      <br><br>
+      <b>Mode:</b> <code>adaptive-root</code>
     </td>
   </tr>
 </table>
 
-### Specialist Subagents
+### Read-only specialists
 
 <table width="100%">
   <tr>
-    <td width="33%" valign="top">
-      <img src="img/explorer.png" width="100%" alt="Explorer">
-      <br>
+    <td width="34%" align="center" valign="top">
+      <img src="img/agents/explorer.webp" width="240" alt="Human cyber-Egyptian interpretation of Anubis tracing repository paths as Explorer">
+    </td>
+    <td width="66%" valign="top">
       <b>Explorer</b>
       <br>
-      <i>Fast local discovery.</i>
+      <i>Decision-ready local discovery.</i>
       <br><br>
-      <b>Role:</b> Local codebase discovery and navigation. Finds files, symbols, references, constraints, and verification targets.
-      <br>
-      <b>Mode:</b> read-only
-      <br>
-      <b>Dispatch:</b> harness-bound specialist dispatch
-      <br>
-      <b>Recommended:</b>
-      <br>
-      <code>Grok Code Fast</code> - <code>openai/gpt-5.4-nano</code> - <code>anthropic/claude-haiku-4-5</code>
+      Resolves repository uncertainty and returns decision-ready local evidence.
+      <br><br>
+      <b>Mode:</b> <code>read-only</code>
     </td>
-    <td width="33%" valign="top">
-      <img src="img/librarian.png" width="100%" alt="Librarian">
-      <br>
+  </tr>
+</table>
+
+<table width="100%">
+  <tr>
+    <td width="34%" align="center" valign="top">
+      <img src="img/agents/librarian.webp" width="240" alt="Human cyber-Egyptian interpretation of Seshat consulting an authoritative scroll as Librarian">
+    </td>
+    <td width="66%" valign="top">
       <b>Librarian</b>
       <br>
-      <i>External docs and examples.</i>
+      <i>Authoritative external research.</i>
       <br><br>
-      <b>Role:</b> External docs and API research. Validates version-specific behavior with official docs or public examples.
-      <br>
-      <b>Mode:</b> read-only
-      <br>
-      <b>Dispatch:</b> harness-bound specialist dispatch
-      <br>
-      <b>Recommended:</b>
-      <br>
-      <code>openai/gpt-5.4</code> - <code>anthropic/claude-sonnet-4-6</code> - <code>google/gemini-3.1-pro-preview</code>
+      Gathers current authoritative external evidence and labels inference.
+      <br><br>
+      <b>Mode:</b> <code>read-only</code>
     </td>
-    <td width="33%" valign="top">
-      <img src="img/oracle.png" width="100%" alt="Oracle">
-      <br>
+  </tr>
+</table>
+
+<table width="100%">
+  <tr>
+    <td width="34%" align="center" valign="top">
+      <img src="img/agents/oracle.webp" width="240" alt="Human cyber-Egyptian interpretation of Ma'at weighing independent evidence as Oracle">
+    </td>
+    <td width="66%" valign="top">
       <b>Oracle</b>
       <br>
-      <i>Deep review and diagnosis.</i>
+      <i>Independent analysis and verification.</i>
       <br><br>
-      <b>Role:</b> Strategic advisor for debugging, architecture review, code review, security/correctness risk, and SDD plan review.
-      <br>
-      <b>Mode:</b> read-only
-      <br>
-      <b>Dispatch:</b> synchronous advisory specialist
-      <br>
-      <b>Recommended:</b>
-      <br>
-      <code>openai/gpt-5.4</code> - <code>anthropic/claude-opus-4-6</code> - <code>opencode-go/glm-5</code>
+      Challenges plans, owns Full analysis, and independently verifies every
+      implementation.
+      <br><br>
+      <b>Mode:</b> <code>read-only</code>
     </td>
   </tr>
+</table>
+
+### Implementation writers
+
+<table width="100%">
   <tr>
-    <td width="33%" valign="top">
-      <img src="img/designer.png" width="100%" alt="Designer">
-      <br>
+    <td width="34%" align="center" valign="top">
+      <img src="img/agents/designer.webp" width="240" alt="Human cyber-Egyptian interpretation of Hathor shaping interface geometry as Designer">
+    </td>
+    <td width="66%" valign="top">
       <b>Designer</b>
       <br>
-      <i>UI, UX, frontend, and visual QA.</i>
+      <i>UI/UX ownership and visual quality.</i>
       <br><br>
-      <b>Role:</b> User-facing design and implementation. Owns visual decisions, browser checks, screenshots, and UX quality.
-      <br>
-      <b>Mode:</b> write-capable
-      <br>
-      <b>Dispatch:</b> synchronous implementation specialist
-      <br>
-      <b>Recommended:</b>
-      <br>
-      <code>google/gemini-3.1-pro-preview</code> - <code>opencode-go/glm-5</code> - <code>kimi-for-coding/k2p5</code>
+      Owns UI/UX choices, implementation, and visual verification.
+      <br><br>
+      <b>Mode:</b> <code>write-capable</code>
     </td>
-    <td width="33%" valign="top">
-      <img src="img/quick.png" width="100%" alt="Quick">
-      <br>
+  </tr>
+</table>
+
+<table width="100%">
+  <tr>
+    <td width="34%" align="center" valign="top">
+      <img src="img/agents/quick.webp" width="240" alt="Human cyber-Egyptian interpretation of Horus placing a precise component as Quick">
+    </td>
+    <td width="66%" valign="top">
       <b>Quick</b>
       <br>
       <i>Fast bounded implementation.</i>
       <br><br>
-      <b>Role:</b> Narrow, mechanical, low-risk edits where the approach is already clear.
-      <br>
-      <b>Mode:</b> write-capable
-      <br>
-      <b>Dispatch:</b> synchronous implementation specialist
-      <br>
-      <b>Recommended:</b>
-      <br>
-      <code>openai/gpt-5.4-mini</code> - <code>anthropic/claude-haiku-4-5</code> - <code>google/gemini-3-flash-preview</code>
+      Makes narrow, clear, low-risk edits within an explicit surface.
+      <br><br>
+      <b>Mode:</b> <code>write-capable</code>
     </td>
-    <td width="33%" valign="top">
-      <img src="img/deep.png" width="100%" alt="Deep">
-      <br>
+  </tr>
+</table>
+
+<table width="100%">
+  <tr>
+    <td width="34%" align="center" valign="top">
+      <img src="img/agents/deep.webp" width="240" alt="Human cyber-Egyptian interpretation of Sobek examining a complex mechanism as Deep">
+    </td>
+    <td width="66%" valign="top">
       <b>Deep</b>
       <br>
-      <i>Thorough implementation and verification.</i>
+      <i>Correctness-critical implementation.</i>
       <br><br>
-      <b>Role:</b> Correctness-critical, multi-file, edge-case-heavy implementation and verification.
-      <br>
-      <b>Mode:</b> write-capable
-      <br>
-      <b>Dispatch:</b> synchronous implementation specialist
-      <br>
-      <b>Recommended:</b>
-      <br>
-      <code>openai/gpt-5.4</code> - <code>anthropic/claude-opus-4-6</code> - <code>google/gemini-3.1-pro-preview</code>
+      Handles multi-file, edge-case-heavy, or correctness-critical
+      implementation.
+      <br><br>
+      <b>Mode:</b> <code>write-capable</code>
     </td>
   </tr>
 </table>
 
-## SDD And Memory
+Children do not delegate. Each mutable surface has one writer. Parallel work is
+limited to independent surfaces. The implementation writer never reviews or
+approves its own result: `oracle` owns every `verify`, including Direct and
+Accelerated work.
 
-The bundled requirements interview is the front door for open-ended work. It
-clarifies intent, assesses scope, asks for user approval when needed, and routes
-work into direct implementation, accelerated SDD, or full SDD.
+## SDD routes
 
 ```text
-propose -> spec -> clarify -> design -> tasks -> apply -> verify -> archive
+Direct:      implement -> verify
+Accelerated: specify -> plan -> tasks -> implement -> verify -> archive
+Full:        explore -> specify -> plan -> tasks -> analyze -> implement -> verify -> archive
 ```
 
-For moderate work, the accelerated path usually runs `propose -> tasks`. For
-high-risk or high-complexity work, the full path adds specification and design
-artifacts before task execution.
-
-Artifacts can be persisted in four modes:
-
-
-| Mode        | Writes to              | Cost   | Use when                                   |
-| ----------- | ---------------------- | ------ | ------------------------------------------ |
-| `thoth-mem` | Memory only            | Low    | Fast iteration without repo planning files |
-| `openspec`  | `openspec/` files only | Medium | Reviewable planning artifacts in the repo  |
-| `hybrid`    | Both                   | High   | Maximum durability; default                |
-| `none`      | Neither                | Lowest | Ephemeral iterations, no persistence       |
-
-[Thoth-mem](https://github.com/EremesNG/thoth-mem) is the local memory MCP used for durable observations, architectural
-decisions, SDD artifacts, and session summaries. The core retrieval pattern is:
+| Route | Use when | Artifacts |
+| --- | --- | --- |
+| Direct | Clear, bounded, low-risk work, including multi-file documentation/mechanical edits | None; oracle returns its verdict in-session. |
+| Accelerated | Generic SDD request, partial clarity, moderate risk, multi-surface behavior, or architecture | Canonical artifacts with fast-forward specification/planning/tasks. |
+| Full | Material uncertainty, cross-cutting behavior/architecture, high contract risk, or high failure cost | Accelerated artifacts plus exploration and independent pre-implementation analysis. |
+
+The root loads only the current phase contract from the bundled `thoth-sdd`
+skill. It owns specification, clarification, planning, requirements checklists,
+task decomposition, convergence, report persistence, and archive. `explorer`
+owns Full discovery; `oracle` always owns `analyze` and `verify`.
+
+An explicitly named route wins. A generic request to use SDD sets Accelerated as
+the minimum. Accelerated writes `spec.md -> plan.md -> tasks.md` in one
+uninterrupted root pass and does not pause for routine approval between phases.
+
+Conditional phases remain deliberately narrow:
+
+- `clarify` runs only for a material ambiguity and updates canonical `spec.md`;
+- `checklist` audits high-risk requirement quality with `CHK###` taxonomy and a
+  separate revalidation pass;
+- `converge` appends tasks only after failed artifact-backed verification; and
+- `architectural-grilling` runs before specification only when explicitly
+  requested or a material human-owned decision remains unresolved.
+
+Accelerated and Full use Spec Kit-grade formats: independent prioritized `US#`
+stories with explicit FR/SC coverage, Given/When/Then scenarios, named normative
+FRs with durable/internal delta metadata, buildable/outcome SC types,
+Constitution checks, `T### [P?] [US#?]` task grammar, honest parallel-or-none
+evidence, risk-driven checklist lenses, `ready`/`closeout` validation, compliance
+reports, and transactional synchronization of declared durable deltas at archive.
+Handled failures roll back within the active process; forced process or OS
+termination is not crash-atomic. See
+[SDD Pipeline](docs/sdd-pipeline.md).
+
+## Skills
+
+Every harness package includes the workflow contracts owned by thoth-agents:
+
+| Skill | Purpose |
+| --- | --- |
+| `thoth-init` | Offline, idempotent project initialization. |
+| `thoth-sdd` | Route rules, phase contracts, templates, and structural validator. |
+| `thoth-constitution` | Explicit governance SemVer lifecycle; routine plans only read principles. |
+| `thoth-archive` | Passing closeout, transactional durable-spec sync, audit report, and dated move. |
+
+The installer obtains these mandatory external skills from their single source
+of truth:
+
+| Skill | Canonical repository |
+| --- | --- |
+| `simplify` | `https://github.com/EremesNG/skills` |
+| `tdd` | `https://github.com/mattpocock/skills` |
+| `progressive-context-router` | `https://github.com/EremesNG/skills` |
+| `architectural-grilling` | `https://github.com/EremesNG/skills` |
+
+It invokes `npx skills add <repository> --skill <name> --global --agent
+<harness> --yes`; missing external skills make installation unhealthy. Project
+QA executables such as Playwright remain project-owned.
+
+The same CLI installation then invokes `npx -y thoth-mem@latest setup
+<opencode|codex|claude> --scope global --json`; dry-run adds `--plan`. Only a
+consistent provider `complete` result completes installation. Provider
+diagnostics, manual actions, and receipt paths remain visible for recovery.
+
+## Harness limitations
+
+| Harness | Important limitation |
+| --- | --- |
+| OpenCode | Strongest integrated path. The CLI installs the npm plugin configuration, external skills, and provider-owned thoth-mem setup; `/thoth-init` materializes thoth-owned project skills/governance. Only the OpenAI built-in preset ships. |
+| Codex | Native plugin installation is incomplete without the CLI. The CLI manages global `AGENTS.md`, six agent TOMLs, config, external skills, and thoth-mem setup; `$thoth-init` only initializes per-repository SDD governance. Runtime role matching and some permissions remain instruction-level. |
+| Claude Code | Run both native marketplace commands before the CLI installs external skills and requests thoth-mem setup. The native manager owns cache files; fine-grained path restrictions remain instruction-level. |
+
+Codex and Claude marketplace manifests are versioned in
+`.agents/plugins/marketplace.json` and `.claude-plugin/marketplace.json`. The
+two catalogs resolve to the same generated `plugin/` bundle. Build and npm
+version lifecycle commands keep that shared bundle synchronized.
+
+## Models and provider boundaries
+
+OpenCode ships only an `openai` preset. Kimi, GitHub Copilot, ZAI/GLM, and
+mixed-provider mappings are not built in. Explicit per-role model overrides
+remain available.
+
+thoth-mem is an independent plugin/provider. `thoth-agents install` orchestrates
+its public setup command, but thoth-mem owns the resulting hooks, MCP, skill,
+session lifecycle, persistence, receipts, and recovery. thoth-agents does not
+copy, edit, force, roll back, or emulate those mechanics.
+
+At runtime the root loads the installed `thoth-mem` skill for prior-work recall,
+durable decisions/root causes/conventions/discoveries, verified compaction, and
+meaningful semantic completion. Delegates receive bounded `none`, `recall`, or
+`observe` authorization separately from workspace write permission; root
+lifecycle never transfers. `openspec/` remains canonical, so SDD phase artifacts
+are not mirrored into memory.
+
+## CLI operations
+
+The npm CLI is part of installation for every harness and remains available for
+status, repair, and model/configuration operations:
 
-1. `mem_recall(mode="compact")` for compact candidate records
-2. `mem_recall(mode="context")` for expanded retrieved context
-3. `mem_get(...)` for the full selected record; use
-   `mem_get(include_timeline=true)` when chronology matters
-
-Use HyDE/fused hybrid recall (sentence + chunk vectors, FTS, KG enrichment) for
-semantic or ambiguous searches; set `mem_recall` `limit` from 1 to 20; narrow
-with `topic_key`, `type`, `time_from`, `time_to`, `scope`, `project`, and
-`session_id` filters. Use `mem_get` with `kind="observation"|"prompt"`,
-`include_timeline=true` plus `before`/`after`, and `offset`/`max_length` for
-large content. Use bounded `mem_context(recall_query=...)` or
-`mem_project(action="graph"|"topics"|"topic")` for supplemental project
-context; `mem_project(action="graph")` relations are `HAS_TYPE`, `IN_PROJECT`,
-`HAS_TOPIC_KEY`, `HAS_WHAT`, `HAS_WHY`, `HAS_WHERE`, and `HAS_LEARNED`.
-
-## Skills And MCPs
-
-thoth-agents ships bundled skills for requirements discovery, plan review, SDD
-planning/execution, verification, and archiving. It also registers MCP servers
-for docs research, public code search, and local memory where the harness
-supports that delivery surface.
-
-
-| Surface          | Shared concept                                 | OpenCode binding                                             | Codex binding                                                    | Claude Code binding                                               |
-| ---------------- | ---------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------- | ----------------------------------------------------------------- |
-| Skills           | Requirements, SDD, review, execution workflows | Copied into the OpenCode skills directory when`--skills=yes` | Packaged as plugin-bundled skills for the Personal plugin source | Bundled in the plugin`skills/` directory                          |
-| MCPs             | `exa`, `context7`, `grep_app`, `thoth_mem`     | Registered by generated OpenCode plugin config               | Packaged/configured only on validated Codex surfaces             | Bundled in the plugin`.mcp.json` (`type: "http"` for URL servers) |
-| Delegation       | Seven-role specialist workflow                 | Native`task` tool                                            | Direct `collaboration.*` generic task delegation; role behavior carried by task name/message | Native`Task(subagent_type: ...)` over auto-discovered subagents   |
-| Blocking choices | Use a structured question surface              | OpenCode`question` tool                                      | `request_user_input` when enabled and available                  | `AskUserQuestion` tool                                            |
+```bash
+npx thoth-agents@latest status
+npx thoth-agents@latest list
+npx thoth-agents@latest install --agent=opencode
+npx thoth-agents@latest install --agent=codex
+npx thoth-agents@latest install --agent=claude
+npx thoth-agents@latest model --harness=codex --role=deep --model=gpt-5.6-sol
+```
 
-See [docs/skills-and-mcps.md](docs/skills-and-mcps.md) for the detailed matrix.
+It does not replace native marketplace trust or mutate manager-owned caches.
 
 ## Documentation
 
-- [Installation](docs/installation.md): OpenCode default setup, explicit Codex
-  setup, non-interactive installs, reset behavior, and troubleshooting.
-- [Codex Install](docs/codex-install.md): Codex targets, backups, dry-run
-  behavior, trust review, and limitations.
-- [Quick Reference](docs/quick-reference.md): Agent roster, SDD flow, memory,
-  delegation, tmux, and key config fields.
-- [Skills and MCPs](docs/skills-and-mcps.md): Bundled skills, MCP servers, and
-  harness delivery surfaces.
-- [Provider Configurations](docs/provider-configurations.md): OpenCode provider
-  presets, fallback chains, and Codex customization cross-links.
-- [Tmux Integration](docs/tmux-integration.md): OpenCode-scoped live pane
-  monitoring for delegated `task` sessions.
-- [SDD Pipeline](docs/sdd-pipeline.md): Planning and execution workflow details.
-- [Codex Plugin Packaging](docs/codex-plugin-packaging.md): Codex plugin package
-  layout and packaging boundaries.
-- [Codex Surface Validation](docs/codex-surface-validation.md): Validated,
-  unknown, and unsupported Codex generation surfaces.
-- [Codex Model Customization](docs/codex-model-customization.md): Codex role
-  model defaults and customization limits.
+- [Installation](docs/installation.md)
+- [Quick Reference](docs/quick-reference.md)
+- [SDD Pipeline](docs/sdd-pipeline.md)
+- [Skills and MCPs](docs/skills-and-mcps.md)
+- [Codex Install](docs/codex-install.md)
+- [Claude Code Install](docs/claude-code-install.md)
+- [Codex Plugin Packaging](docs/codex-plugin-packaging.md)
+- [Claude Code Plugin Packaging](docs/claude-code-plugin-packaging.md)
+- [Provider Configuration](docs/provider-configurations.md)
 
 ## Development
 
-The OpenCode integration targets `@opencode-ai/plugin` and
-`@opencode-ai/sdk` v1.4.7. The repository also contains Codex adapter and
-packaging code for the multi-harness install path.
-
-Use Node.js `>=22.13` with Corepack-managed `pnpm@11.2.2`:
-
 ```bash
-corepack enable
-corepack prepare pnpm@11.2.2 --activate
 pnpm install
+pnpm run check:ci
+pnpm run typecheck
+pnpm run build
+pnpm test
 ```
 
-
-| Command              | Purpose                                                       |
-| -------------------- | ------------------------------------------------------------- |
-| `pnpm run build`     | Build TypeScript into`dist/` and generate declarations/schema |
-| `pnpm run typecheck` | Run TypeScript type checking without emit                     |
-| `pnpm test`          | Run the Vitest suite                                          |
-| `pnpm run lint`      | Run Biome linter                                              |
-| `pnpm run format`    | Run Biome formatter                                           |
-| `pnpm run check`     | Run Biome check with auto-fix                                 |
-| `pnpm run check:ci`  | Run Biome check without writes                                |
-| `pnpm run dev`       | Build and launch the OpenCode plugin in local dev mode        |
+Node.js `>=22.13` and `pnpm@11.2.2` are required. `pnpm run build` regenerates
+both integration packages, compiles the runtime and declarations, and refreshes
+the JSON schema.
 
 ## License
 
-MIT
+[MIT](LICENSE)