Harness Hub

Harness Hub is a personal repo harness toolkit for making agent work repeatable across projects. It installs the full standard skill/routing set, initializes the minimal repo harness when requested, validates the result, and keeps managed files safe through lock-backed lifecycle commands.

Imported skills can keep their upstream style; Harness Hub mainly owns routing, source records, harness templates, and lifecycle safety.

Agent execution rules live in AGENTS.md. Human-facing workflow detail lives in Development Workflow.

First-Use Summary

Harness Hub does three bounded jobs:

check and analyze inspect a target repo and stay read-only.
init-harness creates the minimal root harness only when you explicitly approve it.
install installs the standard skill set only; it does not create root harness files.

For a new target repo, start with a dry run:

npx @jasonwen/harness-hub init-harness D:\path\to\target --target standard --dry-run --json

Move to --yes only after reviewing the planned files. Harness Hub does not create schedules, webhooks, commits, pushes, global skill installs, or remote service changes unless a command explicitly says so.

Visual Navigator

flowchart TD
  Start["I have a repo"] --> Analyze["Analyze readiness"]
  Analyze --> Init["Initialize minimal harness"]
  Init --> Work["Run SDD + TDD work"]
  Work --> Validate["Validate and hand off"]

  Start --> Skills["Install standard skills only"]
  Start --> Maintain["Maintain Harness Hub itself"]
  Start --> Insight["Publish source-backed insight posts"]

  Analyze --> A1["harness-hub analyze --agent-readiness --harness"]
  Init --> I1["harness-hub init-harness --target standard"]
  Skills --> S1["harness-hub install --target standard"]
  Work --> W1["workflow-router -> sdd-workflow -> tdd-workflow"]
  Validate --> V1["validate-harness / bun run validate"]
  Maintain --> M1["hub-maintenance-workflow"]
  Insight --> P1["insight-generate -> insight-build -> insight-validate"]

Choose A Path

I want to...	Start here	What it gives you
Prepare another repo for Codex-driven work	`init-harness --target standard`	Standard skills, root harness files, local state templates, validation script, lock ownership.
Install skills without root harness files	`install --target standard`	Full standard skill tree under `skills/<name>/`, no root file changes.
Check a target repo before writing files	`analyze --agent-readiness --harness --json`	Read-only readiness, harness gaps, and recommendations.
Run a routine status self-check	`self-check --json`	Read-only aggregate status, advisory/failure split, and conditional harness validation.
Make installed skills visible to local Codex	`activate-codex --yes`	Sync project-local `skills/<name>` into `.codex/skills` without global installation.
Validate a bootstrapped repo	`validate-harness --json`	Required files, state, QA boundaries, trigger hygiene, and structural scores.
Maintain this hub	`workflow-router` then `hub-maintenance-workflow`	Source records, routing, capability metadata, docs, templates, and lifecycle safety.
Create a public source-backed insight post	`insight-*` commands	Source ledger, Effective Interact adaptation, Pages output, and publish preflight.

Harness Hub has one standard skill install set and one minimal harness path. There are no named skill install variants, harness pack levels, or bundle selectors. Confirmed install overwrites an existing same-name skill directory; use --dry-run first when a target may already have local skills.

One-Step Target Bootstrap

Run this against a clean target git worktree:

npx @jasonwen/harness-hub init-harness D:\path\to\target --target standard --yes

If the target already has root harness files, inspect first:

npx @jasonwen/harness-hub init-harness D:\path\to\target --target standard --dry-run --json

From source:

git clone https://github.com/JasonxzWen/harness-hub.git
cd harness-hub
bun install
bun run build
node bin\harness-hub.mjs init-harness D:\path\to\target --target standard --yes

Core Commands

bun install
bun run validate
bun run bootstrap:codex-skills

npx @jasonwen/harness-hub analyze D:\path\to\target --agent-readiness --harness --json
npx @jasonwen/harness-hub check D:\path\to\target --json
npx @jasonwen/harness-hub self-check D:\path\to\target --json
npx @jasonwen/harness-hub activate-codex D:\path\to\target --dry-run --json
npx @jasonwen/harness-hub activate-codex D:\path\to\target --yes
npx @jasonwen/harness-hub init-harness D:\path\to\target --target standard --dry-run --json
npx @jasonwen/harness-hub init-harness D:\path\to\target --target standard --yes
npx @jasonwen/harness-hub validate-harness D:\path\to\target --json
npx @jasonwen/harness-hub install D:\path\to\target --target standard --dry-run
npx @jasonwen/harness-hub install D:\path\to\target --target standard --yes
npx @jasonwen/harness-hub status D:\path\to\target --json
npx @jasonwen/harness-hub update D:\path\to\target --dry-run --json
npx @jasonwen/harness-hub remove D:\path\to\target --dry-run --json

Insight publishing:

npx @jasonwen/harness-hub insight-generate . --input input.json --json
npx @jasonwen/harness-hub insight-build . --json
npx @jasonwen/harness-hub insight-validate . --json
npx @jasonwen/harness-hub insight-publish . --dry-run --json

check is a read-only startup check. It reports the released CLI package status from npm registry in cli, the target repository's lock-managed component status in target, and explicit CodeGraph/Headroom configuration advice in externalTools; update availability, registry failures, missing locks, missing project-local Codex activation, and external tool suggestions are advisory and do not apply updates, install tools, or block the agent startup path.

activate-codex is an explicit local activation step for Codex projects. It copies the already installed skills/<name> tree into .codex/skills/<name> so Codex can index the skill metadata, including helper triggers such as package-release-sniffer. It writes only the target repository's local .codex/skills cache, uses a Harness Hub marker to avoid overwriting unmarked local Codex skills, and does not write global skill directories or .harness-hub/lock.json.

self-check is the routine health-check aggregate. It wraps check, classifies hard failures separately from advisory items, and runs strict validate-harness only when the target has an installed harness:minimal lock record unless --validate-harness is explicitly provided. A local daily 21:30 runner can call:

npx @jasonwen/harness-hub self-check D:\path\to\target --json

Harness Hub does not create the schedule, webhook, commit, push, tool install, or target setup for that command.

What Is Included

Area	Included surface
Routing and lifecycle	`workflow-router`, owner workflow skills, SDD-first change flow, delivery closeout.
Planning and implementation	`grill-me`, `product-capability`, `tdd-workflow`, `karpathy-guidelines`, `verification-loop`.
Diagnosis and review	`diagnosis-workflow`, `diagnose`, `review-workflow`, `compound-code-review`, `security-review`.
Communication and handoff	`effective-interact`, `handoff`, `doc-coauthoring`, `internal-comms`, `documentation-lookup`.
Web and artifacts	`frontend-design`, `design-taste-frontend`, `webapp-testing`, `e2e-testing`, `web-artifacts-builder`, `frontend-slides`, `theme-factory`.
Platform extension	`claude-api`, `mcp-builder`, `skill-creator`, source records, capability metadata.
External tool advice	`check.externalTools` and `analyze --agent-readiness` signals for explicit CodeGraph and Headroom setup.
Harness lifecycle	`check`, `self-check`, `analyze`, `init-harness`, `validate-harness`, `install`, `status`, `update`, `remove`, `harness-quality-check`.

Source Layout

skills/
  <skill-name>/
    SKILL.md
    references/   # optional
    scripts/      # optional
    assets/       # optional
harness/
  minimal/          # the only supported target bootstrap harness
  website-cloner/  # explicit authorized website clone smoke scaffold
.claude-plugin/
  plugin.json
  marketplace.json

Project Map

Path	Purpose
`README.md` / `README.zh-CN.md`	Human-facing entry and visual navigation.
`AGENTS.md`	Agent-facing repo rules and execution workflow.
`skills/`	Platform-neutral skill source of truth.
`harness/`	Minimal bootstrap harness and explicit-only smoke scaffolds.
`capabilities/index.json`	Skill and harness component metadata.
`docs/development-workflow.md`	SDD+TDD workflow guide and state-file responsibilities.
`docs/skill-routing.md`	Skill overlap and routing rules.
`docs/personal-workflow-distribution.md`	Personal distribution policy.
`docs/source-projects.md`	Upstream source and decision log.
`src/harnessHub.ts`	CLI implementation.
`config/artifact-policy.json`	Git/npm artifact inclusion policy.

Generated reports, worktree-local harness state, interaction artifacts, and Codex dogfood copies stay local: reports/, .harness-hub/reports/, .harness-hub/state/, skills/effective-interact/artifacts/, and .codex/ are ignored. site/ is Git-only Pages output and is intentionally excluded from the npm package.

Validation

bun run typecheck
bun test ./tests
bun run validate:artifact-policy
bun run validate:skills
bun run validate
git diff --check

Release validation:

bun run validate:release