Thoth-Agents

Adaptive orchestration for OpenCode, Codex, and Claude Code.

Seven roles · Three SDD routes · Runtime-autonomous SDD

---

What it does

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.

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. Root recommends Direct, Accelerated, or Full and the user selects the route. After ready, artifact-backed routes offer optional Oracle plan review or proceeding without it; every final verification remains mandatory. 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.

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.

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.

Install

OpenCode

Install the plugin configuration, five thoth-owned skills, four external skills, and the thoth-mem companion globally:

npx thoth-agents@latest install --agent=opencode --dry-run
npx thoth-agents@latest install --agent=opencode

Restart OpenCode and initialize the current repository:

/thoth-init

The installer materializes the five packaged thoth-owned workflow skills under ~/.config/opencode/skills/; external skills are installed globally from their canonical repositories, and thoth-mem completes its own provider setup. The /thoth-init command only initializes or synchronizes the minimum openspec/ governance structure. It never installs skills, agents, plugins, harness configuration, dependencies, or workflow templates. SDD phases read templates directly from the globally installed thoth-sdd skill; any legacy project openspec/templates/ tree remains untouched.

Codex

Preview, then run the combined native-plugin and global-layer installer:

npx thoth-agents@latest install --agent=codex --dry-run
npx thoth-agents@latest install --agent=codex

The CLI first uses Codex's native manager to register EremesNG/thoth-agents and install or enable thoth-agents@thoth-agents. It then writes the orchestrator block to ~/.codex/AGENTS.md, creates six custom-agent TOMLs under ~/.codex/agents/, merges the managed feature into ~/.codex/config.toml, installs the external skills, and invokes provider-owned thoth-mem setup. Restart Codex, then initialize each target repository's SDD governance:

$thoth-init

The plugin contributes skills, their workflow templates, and MCP configuration. $thoth-init creates only missing openspec/ governance files; SDD phases read templates from the plugin's installed thoth-sdd skill instead of copying them into the repository.

Review /plugins and /hooks after installation. Codex trust and higher-precedence instructions remain in force.

Claude Code

Claude requires its two native marketplace steps before the plugin can expose agents or skills:

claude plugin marketplace add EremesNG/thoth-agents --scope user
claude plugin install thoth-agents@thoth-agents --scope user

Then install the mandatory external skills and invoke provider-owned thoth-mem setup:

npx thoth-agents@latest install --agent=claude --dry-run
npx thoth-agents@latest install --agent=claude

Restart Claude Code or run /reload-plugins, then initialize the repository:

/thoth-agents:thoth-init

Claude discovers the packaged orchestrator, six namespaced subagents, and five 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 or copies workflow templates out of it.

See Installation, Codex Install, and Claude Code Install for scopes, verification, and limitations.

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

Orchestrator Adaptive root and final synthesis. Keeps task ownership and synthesis, recommends a route for the user's selection, coordinates SDD artifacts, and implements bounded work directly. Mode: adaptive-root

Read-only specialists

Explorer Decision-ready local discovery. Resolves repository uncertainty and returns decision-ready local evidence. Mode: read-only

Librarian Authoritative external research. Gathers current authoritative external evidence and labels inference. Mode: read-only

Oracle Independent analysis and verification. Reviews plans when the user requests it and independently verifies every implementation. Mode: read-only

Implementation writers

Designer UI/UX ownership and visual quality. Owns UI/UX choices, implementation, and visual verification. Mode: write-capable

Quick Fast bounded implementation. Makes narrow, clear, low-risk edits within an explicit surface. Mode: write-capable

Deep Correctness-critical implementation. Handles multi-file, edge-case-heavy, or correctness-critical implementation. Mode: write-capable

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.

SDD routes

Direct:      implement -> verify
Accelerated: specify -> plan -> tasks -> implement -> verify -> archive
Full:        explore -> specify -> plan -> tasks -> implement -> verify -> archive

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 separate planning gates.

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 owns user-selected plan review and every verify.

An explicitly named route is the user's selection and wins. Otherwise root recommends one of all three routes and waits for the user's choice. A generic request to use SDD sets Accelerated as the minimum recommendation. Accelerated writes spec.md -> plan.md -> tasks.md in one uninterrupted root pass and does not pause for routine approval between those planning 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;
• plan-review is offered after ready on Accelerated and Full; the user chooses Review plan with Oracle (Recommended) or Proceed without review;
• 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.

Skills

Every harness package includes the workflow contracts owned by thoth-agents:

Skill	Purpose
thoth-init	Offline, idempotent initialization and synchronization of minimum openspec/ governance only.
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.
plan-reviewer	Optional read-only Oracle plan review with exact [OKAY]/[REJECT] results and freshness evidence.

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, global thoth-owned and external skills, and provider-owned thoth-mem setup; /thoth-init only initializes per-repository openspec/ governance. Only the OpenAI built-in preset ships.
Codex	The CLI installs the native plugin and 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 install and sync ship and select only the openai preset. Kimi, GitHub Copilot, ZAI/GLM, and mixed-provider mappings are not built in. Explicit per-role model overrides remain available. Applying model configuration creates a complete seven-role agents preset from the effective values and activates it with preset: agents; unrelated presets and configuration remain intact.

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:

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

In the interactive Configure models flow, Apply is always available. When no role is dirty, it reapplies every currently displayed role value; after an edit, preview and apply remain limited to the dirty roles. In OpenCode, both Apply and Apply changes materialize the complete effective roster and activate the named agents preset.

It does not bypass native marketplace trust or edit manager-owned caches directly; Codex and Claude own their native manager mutations.

Documentation

• Installation
• Quick Reference
• SDD Pipeline
• Skills and MCPs
• Codex Install
• Claude Code Install
• Codex Plugin Packaging
• Claude Code Plugin Packaging
• Provider Configuration

Development

pnpm install
pnpm run check:ci
pnpm run typecheck
pnpm run build
pnpm test

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