Harness Hub

Repository-first deterministic distribution for Claude Code and Codex project harnesses.

中文说明

Harness Hub has one target capability: full migration. The Git repository and selected commit are the only distribution/version source. There is no npm package, component version, partial installer, update/remove lifecycle, compatibility layer, generic Agent runtime, or second registry.

Claude Code and Codex remain the only main-Agent runtimes. Harness Hub distributes project rules, Host resources, atomic Skills, and an OKF contract; it does not duplicate native orchestration, Subagent dispatch, retries, pause/resume, or result aggregation.

Update an installed repository

The natural-language update entry is a request plus the repository URL:

Update Harness Hub in this repository:
https://github.com/JasonxzWen/harness-hub

Claude Code or Codex clones that URL into a temporary standalone checkout outside the current repository, uses the default branch current HEAD, treats the current repository as the target, reads the existing .harness-hub/manifest.json, and runs from the temporary checkout:

node bin/harness-hub.mjs migrate <current-repository> --yes

A valid schemaVersion 1 manifest supplies omitted hosts and primaryHost, so the Agent does not ask for Host mode again. Explicit --host or --primary still wins. The resulting manifest records the actual source commit. Migration does not commit, push, publish, merge, or otherwise modify remote state.

Recognized HTTPS and SSH spellings of the official remote record the canonical source URL https://github.com/JasonxzWen/harness-hub in the manifest. This identity normalization performs no remote call or remote mutation.

First migration or explicit Host selection

Clone this repository outside the target, then invoke the only public command:

git clone https://github.com/JasonxzWen/harness-hub.git C:\temp\harness-hub
cd C:\temp\harness-hub
node bin/harness-hub.mjs migrate C:\path\to\target --host codex --yes

With no manifest, --host is required. Modes:

--host claude
--host codex
--host both --primary claude
--host both --primary codex

On a first migration, both also requires --primary. In both mode, primary selects only the CLI used for first-time OKF initialization. Node performs all shared and Host-specific copying deterministically.

Use --force only to replace Harness Hub-managed generic resources. Every run also removes resources still owned by the previous manifest that no longer belong to the selected Host surface. Target-owned Skills, project knowledge, Evals, product files, credentials, browser state, and unrelated local information remain outside that ownership set.

Both source and target must be clean standalone Git worktrees with an existing HEAD; use the current repository as the target only when its .git is a real directory. If .git is a file because the repository is a linked worktree or submodule worktree, stop with E_LINKED_WORKTREE and rerun from a clean standalone clone. Do not migrate a replacement target and copy its result or Git metadata back. Every distributed source byte must match the source HEAD tree. Migration rejects collisions, path escape, symlinks, junctions, unsafe Git state, and incomplete output. It never commits, pushes, publishes, merges, changes credentials, changes Host trust, or modifies user/global configuration.

What migration installs

Shared:

  • AGENTS.md: native main-Agent rules, development and delivery boundaries, atomic Skill routing, OKF, Eval, authorization, and safety;
  • CLAUDE.md: exactly @AGENTS.md;
  • .harness-hub/manifest.json: versionless managed-file ownership;
  • .harness-hub/okf-validate.mjs: standalone deterministic Google OKF v0.1 validator;
  • .harness-hub/safety-hook.mjs: deterministic PreTool safety hook with no Agent dispatch or state machine;
  • first-time target-owned knowledge/, generated from real target sources by the selected primary CLI.

Claude Code:

  • .claude/skills/<skill>/**;
  • .claude/settings.json.

Codex:

  • .agents/skills/<skill>/**;
  • Codex-only atomic Skills such as decision-ui;
  • .codex/hooks.json.

Codex project hooks run only when the user already trusts the target repository. Migration never changes trust.

Harness Hub's root knowledge/, source records, docs, tests, task state, and repository history are source-only and never copied.

Atomic Skills and native orchestration

The Host main Agent selects atomic Skills directly. Native development atoms include grill-me, grill-with-docs, product-capability, to-tickets, tdd, codebase-design, code-review, product-ui-review, and verification; other examples include Ponytail, effective-interact, quick-learn, source-post, Agent Reach, Decision UI, security review, and Agent interaction audit.

  • Every repository mutation gets one grill-me alignment pass. An already aligned task asks zero questions and continues; durable contracts, specifications, ADRs, architecture, or OKF changes use grill-with-docs to reuse the same decision graph instead of running a second interview.
  • to-tickets is used only when accepted work needs multiple independently verifiable tracer-bullet tickets, follows the target project's existing task/issue/plan convention, and never creates a Harness task registry.
  • Native Subagents are limited to bounded independent read-only exploration, review, or verification. Skills add no Router, Runtime, orchestration Hook, dispatcher, or fixed lifecycle.
  • Existing Web product experience diagnosis uses product-ui-review for evidence-backed, report-only findings; implementation remains a separately authorized production frontend action.
  • Frontend motion is split into narrow atoms: animation-vocabulary names effects, apple-design guides physical or Apple-platform interaction, and review-animations reports evidence-backed findings without editing code.
  • Existing frontend owners may consult pinned or live sources such as NameThatUI, Kill AI Slop, and a pinned design-system extraction reference. They mirror no corpus, install nothing without separate authorization, and use Host-native image generation without adding a provider runtime.
  • Complex delivery, approach comparisons, and important handoffs use effective-interact; simple results remain plain text.
  • Failed, long-running, high-cost, tool-abnormal, or explicitly requested retrospectives use agent-interaction-audit. Missing duration, token, or cost evidence is unknown, never estimated.
  • decision-ui is installed only for Codex and falls back honestly to text when native structured input is unavailable.
  • Agent Reach is distributed as a safe prompt capability only. It first checks an already installed user-level CLI and never installs dependencies, configures accounts, writes ~/.agent-reach, or copies cookies and credentials.

Project knowledge

On a first migration with no prior manifest and no knowledge/, the primary CLI is invoked once to inspect the target and create the smallest source-traceable Google OKF v0.1 wiki.

That one CLI process receives an isolated temporary user/config directory and only the selected Host's API-key environment (OPENAI_API_KEY for Codex or ANTHROPIC_API_KEY for Claude Code), plus network/TLS process settings. It does not reuse normal Host profiles, keychains, browser state, unrelated credentials, or user configuration; the temporary directory is removed when the process exits.

Later normal and force migrations:

  • invoke no Host CLI for knowledge maintenance;
  • run the standalone validator;
  • preserve the complete knowledge path-and-byte set;
  • fail closed if a prior manifest exists but the project knowledge tree is missing.

Daily knowledge maintenance belongs to the native Host main Agent under the target project's contract. Update an existing canonical owner page before adding another, keep sources/index/log/links synchronized, and make no change when no durable project fact changed.

Failure and evaluation boundaries

Migration keeps deterministic ownership, stale-resource cleanup, Git-control snapshots, protected-path checks, and rollback. If exact restoration is impossible because unrelated ignored content or the source checkout changed, it preserves the unowned change and reports rolledBack: false instead of claiming success.

Each target repository keeps its own task cards, sessions, audits, knowledge, and real-task Eval results. Harness Hub stores no project-specific cases.

Primary metric: real-task first-attempt success rate.

Guardrails: human intervention, Agent/CLI calls, elapsed time, token usage, cost, migration safety, and project-knowledge protection.

Source development

bun install --frozen-lockfile
bun run sync:agent-skills
bun run validate

Project-local .agents/skills/ and .claude/skills/ are ignored dogfood mirrors. Canonical Skills live only under skills/<name>/; capabilities/index.json is the single versionless distribution inventory.