Hokage Core Cross-Harness Architecture

Last updated: 2026-05-22

Purpose

Hokage Core is the shared workflow contract behind Claude Code Harness.

The product stays Claude-first until adapter parity is proven. The internal near-term positioning is:

Claude Code Harness, powered by Hokage Core

This is an implementation direction, not a public marketing claim. The repository already uses "Hokage" for the v4 Go-native runtime line, so public README wording must stay conservative until the spin-off gate passes.

Why This Exists

Superpowers shows the useful pattern: the reusable part is not a single CLI. It is a common skills library plus thin harness-specific entrypoints. Its repository exposes separate Claude, Codex, Cursor, OpenCode, and Copilot surfaces while pointing host adapters at common skills. Harness evaluates Antigravity CLI separately as future/unsupported public scope until an official or verified adapter route is observed.

Claude Code Harness already has part of that shape:

• skills/ is the current primary skill surface.
• skills-codex/ contains Codex-native overrides.
• codex/.codex/skills/ and opencode/skills/ are checked mirrors.
• docs/hardening-parity.md already documents that Claude Code and Codex do not have identical runtime enforcement.

The missing piece is a stable boundary that says what is core, what is adapter, and what must be proven before public cross-harness claims.

Core Contract

Core is allowed to define:

• workflow intent
• user-facing triggers
• inputs and outputs
• required evidence
• acceptance criteria
• review and completion rules
• tool capability requirements

Core must not depend directly on:

• Claude Code hook names such as PreToolUse, PostToolUse, or SessionStart
• Claude-only tools such as Task or AskUserQuestion
• Codex-only tools such as spawn_agent
• OpenCode-specific config shape
• Cursor rule shape
• GitHub Copilot CLI command shape
• Antigravity CLI command or profile shape
• plugin marketplace packaging details

If a core workflow needs a capability, it names the capability in generic terms. Examples:

Capability	Meaning
skill_loading	Host can discover and load workflow skills
bootstrap_notice	Host can inject startup guidance or prove it was loaded
prompt_routing	Host can route natural language prompts to workflows
pre_use_guard	Host can block dangerous actions before execution
post_use_gate	Host can inspect output after execution
review_artifact	Host can emit structured review evidence
memory_bridge	Host can read or write session memory through a safe adapter

Adapter Contract

Adapters translate the core contract into host-specific mechanics.

Adapter	Phase 73 tier	Owns	Must not claim
Claude Code	supported	plugin manifest, hooks, settings, output styles, runtime guardrails	That non-Claude hosts have identical pre-use hooks
Codex CLI	internal-compatible	Codex skills, AGENTS guidance, companion wrapper, local plugin marketplace investigation, post-exec quality gates	That Codex can always stop unsafe commands before execution
Codex app	candidate	app-specific handoff and worktree/runtime proof when observed	That CLI help proves app behavior
OpenCode	internal-compatible	native skill frontmatter, AGENTS guidance, opencode config, setup docs, package validation	That mirror sync alone is first-class adapter parity
Cursor	candidate	rules/adapter investigation and smoke proof when available	That Cursor PM handoff docs are adapter support
GitHub Copilot CLI	candidate	CLI command investigation, tool mapping candidate, bootstrap smoke proof when available	Support based only on Superpowers evidence
Antigravity CLI	future/unsupported for public claim	official-doc and local availability investigation, manual profile candidate if no plugin route exists	Adapter support without an official or verified bootstrap route

Each adapter must declare:

• support tier
• supported core skills
• unsupported core skills with reasons
• capability mapping
• bootstrap route
• install/update path
• verification commands
• known asymmetries

Implementation Flow

The no-regression flow is intentionally staged:

1. Plan Define Hokage Core and adapter contracts in docs before changing runtime behavior.
2. Pre-implementation validation Add failing tests for the capability matrix and bootstrap routing. Treat adapter manifests as a follow-up only after a consumer exists in setup, docs generation, or release preflight.
3. Implementation Repair stale OpenCode docs/setup first. Add adapter manifests and generator checks only when they are consumed by setup, docs generation, or release preflight in the same phase.
4. Post-implementation validation Run targeted contract tests, mirror checks, Codex/OpenCode package checks, release preflight, and the full plugin validator. Non-shipping adapter checks should be path-triggered or opt-in unless the release claims that adapter support.
5. Positioning closeout Update README only to the level proven by tests. Public Hokage Harness spin-off remains blocked until the gate below passes.

Public Spin-Off Gate

Hokage Harness can become a public generic distribution only when all of the following are true:

Gate	Required proof
Claude adapter	./tests/validate-plugin.sh passes with Hokage Core contract checks
Codex adapter	bash tests/test-codex-package.sh passes and Codex bootstrap route is documented
OpenCode adapter	node scripts/validate-opencode.js and mirror sync pass with no stale command/MCP docs
Candidate adapters	Codex app, Cursor, and GitHub Copilot CLI remain candidate until host-specific smoke proves bootstrap and workflow behavior
Unsupported future adapters	Antigravity CLI remains future/unsupported for public claims until an official or verified adapter route and local bootstrap smoke are observed
Capability matrix	Claude Code / Codex CLI / Codex app / OpenCode / Cursor / GitHub Copilot CLI / Antigravity CLI tiers are documented and tested
Bootstrap routing	Golden prompts route to the expected workflows or produce an explicit unsupported result
Release preflight	bash scripts/release-preflight.sh includes adapter drift gates
Positioning	README avoids claiming support for unproven hosts

Until then, use the wording:

Claude Code Harness is Claude-first, with Hokage Core extraction underway.

Explicit Rejects

• Do not rename the main product to Hokage Harness before adapter parity.
• Do not copy Superpowers skill names or trigger phrases as a shortcut.
• Do not call skills/ tool-neutral while it still contains host-specific assumptions.
• Do not promise the same safety model across hosts with different hook models.
• Do not describe Codex app, Cursor, or GitHub Copilot CLI as supported while they are still candidate.
• Do not describe Antigravity CLI as supported while it is still future/unsupported for public claims.
• Do not add adapter manifest files unless setup, docs generation, or release preflight consumes them in the same phase.
• Do not make Claude plugin releases hard-block on non-shipping adapter checks unless that release claims adapter support.
• Do not treat OpenCode as first-class while docs still point at stale commands/ or missing mcp-server/ setup paths.

Source Links

• Superpowers repository: https://github.com/obra/superpowers
• Superpowers Codex plugin manifest: https://github.com/obra/superpowers/blob/main/.codex-plugin/plugin.json
• Superpowers OpenCode plugin: https://github.com/obra/superpowers/blob/main/.opencode/plugins/superpowers.js
• Local distribution scope: docs/distribution-scope.md
• Local skill orchestration contract: docs/skill-orchestration-design-contract.md
• Local hardening parity: docs/hardening-parity.md