| name | claude-code-harness |
| description | Use this skill when introducing, auditing, refactoring, or extending the Claude Code harness of a project — i.e. its `.claude/` directory (CLAUDE.md, settings.json, hooks/, agents/, skills/, commands/) and root CLAUDE.md. Activates on phrases like 'set up Claude Code in this project', 'design my .claude/', 'audit my Claude Code harness', 'add a hook/skill/subagent', 'how should I organize CLAUDE.md', 'what built-ins does Claude Code already have', 'should I write a custom orchestrator subagent', 'when should I use a dynamic workflow', 'why is my harness slow / brittle / token-heavy', 'extend Claude Code with X', 'set up the long-running build kit (Phase 5)', 'refresh my practice baseline'. Claude Code 2.x / Opus-class-specific — does NOT teach harness design for other agent frameworks (building agents in OpenAI/Codex/LangChain-style stacks); an external CLI wired into *this* harness as an MCP server is in scope. Skip when the project's `.claude/` already encodes this discipline. |
| allowed-tools | Read, Write, Edit, Glob, Grep, Bash(ls:*), Bash(tree:*), Bash(cat:*), Bash(find:*), Bash(grep:*), Bash(claude --help), Bash(claude agents:*), Bash(claude --version), Bash(claude --print:*), Bash(claude plugin list:*), Bash(git log:*), Bash(git status:*), Bash(wc:*) |
Claude Code Harness
Designs, bootstraps, audits, and extends the harness around Claude Code — the .claude/
directory and root CLAUDE.md that turn a fresh repository into a high-leverage agentic
workspace. Opinionated, and the opinion is one line:
Under a capable model, less harness yields more productivity. Find the simplest setup that
works; add a component only when a simpler approach demonstrably underperforms. If a
component encodes "the model can't do X" and the model already does X natively, it should
not exist. (Model-agnostic principle — don't re-pin it to a version; evidence in
references/evidence-base.md.)
When to use
- A project has no
.claude/ and wants its harness now → Bootstrap (production-grade
default; minimal on explicit request).
- A project has a
.claude/ that has accumulated cruft (custom orchestrator subagent, multi-stage
pipeline, 500-line CLAUDE.md, mid-thought blocking hooks, prescriptive stack presets, stale
model-version pins, duplicate skills) → Audit.
- About to add a hook/skill/subagent/command and want to confirm a built-in doesn't already
cover it → Extend.
- Someone asks how Claude Code differs from generic agentic frameworks, or when to use a
dynamic workflow → Explain.
Do NOT use when: the operator's own harness already encodes this discipline (this skill is
transmittable knowledge, not a self-description for a mature setup); the question is
about building a harness inside another framework (OpenAI/Codex/MCP-without-Claude) → point to
references/evidence-base.md external sources — an external CLI attached to this harness via
MCP is in scope, not an exclusion (references/codex-peer-skill.md); the question is general
programming/debugging.
The four modes
Mode 1: Bootstrap (empty .claude/)
Read references/bootstrap-checklist.md. Run claude --version first (the built-in subagent
types you must not recreate are catalogued in references/native-capabilities.md; since
v2.1.198 /agents no longer opens a wizard — inspect configured agents via /context
("Custom Agents") or .claude/agents/ directly; the CLI claude agents lists running
background sessions, not types). Default shape is production-grade regardless of project size — which means
conventions + documents, not machinery, so it does not contradict the headline principle:
root CLAUDE.md ≤ 200 lines + settings.json with sane permissions + the shipped workflow distillation
.claude/docs/{workflow,testing,docs-discipline}.md (Phase 2c, verbatim copies from
references/project-docs/) + docs/ARCHITECTURE.md & docs/CODE-MAP.md with real content.
No custom subagents, hooks, or skills until justified; minimal MVH only on explicit operator
request. Transmit the practice baseline (checklist Phase 2b /
references/practice-baseline.md): the behavioral layer the kit's artifacts assume does not
travel with a plugin install — detect across memory layers, then offer a project embed
(default) or a guarded global merge (explicit opt-in). For a
sustained, multi-session product build, also set up the long-running build kit (runnable
oracle / feature-spec ledger / progress-handoff conventions — checklist Phase 5; Anthropic's
long-running-harness playbook, files+conventions not machinery; still no custom
subagents/hooks). Greenfield (0 files, 0 commits) is a valid detected state, not a reason to
stall: an explicit request for the full harness on an empty repo is informed consent — deploy it
with honestly-labelled stubs (never invented facts); on a sustained greenfield an F0 ledger
feature closes them in the loop, and where Phase 5 is skipped the stub marker carries its own fill
trigger (never cite a features.json the project won't have). Close every bootstrap by recording
it (Phase 8: the run writes its own first episodic entry, in whatever carrier the project's
continuity duty names — the layer starts live instead of as a convention nobody has exercised).
Then stop.
Mode 2: Audit (existing .claude/)
Read references/audit-checklist.md. Walk it top-down; produce a gap statement + remediation
per finding. Do not edit until the operator approves. Flag anything irreversible (deleting
accumulated experiment data, removing an actively-used skill) as confirm-before-acting.
Mode 3: Extend (add a primitive)
First load references/native-capabilities.md and confirm Claude Code doesn't already provide
it. If it does, point to the built-in and stop. If a custom primitive is justified, load
references/harness-discipline.md, then pick the right one:
| Need | Primitive |
|---|
| Reusable workflow template the main thread runs | action-skill in .claude/skills/<name>/SKILL.md |
| Knowledge loaded on demand | reference-skill (disable-model-invocation if you only trigger it) |
| Search-heavy work that would pollute main context | subagent — Explore / general-purpose first; custom only with evidence |
| Invariant that must fire even when the model "forgets" | hook (enforce at Stop / UserPromptSubmit, not mid-write) |
| Operator-facing shortcut for a frequent ritual | slash command in .claude/commands/<name>.md |
| Codebase-scale sweep / migration / trust-critical audit exceeding one context | dynamic workflow (keyword ultracode) — built-in; never hand-roll a pipeline |
| Cross-session knowledge | memory (CLAUDE.md / auto memory) |
| External tool surface | MCP server in .mcp.json |
Mode 4: Explain (no edits)
Read the relevant reference and answer concisely. Do not write files.
Operator handoff (end of every Bootstrap / Audit run)
The kit's machinery is opt-in by design, so the operator can't discover it from one run.
End every Bootstrap and Audit run — and any first use of this skill in a project — with a
compact operator map (a footer, not a lecture; skip it when the operator demonstrably
already knows the kit):
What else the kit does (trigger phrases):
- "audit my Claude Code harness" — audit
.claude/ (gap report, edits after approval)
- "set up Claude Code harness in this project" — bootstrap a production-grade harness
(minimal via "set up a minimal harness")
- "set up the long-running build kit (Phase 5)" — oracle / feature-ledger / progress for a
multi-session product build
- Independent verification (fresh context, not self-recheck) — by default a single
code-refuter on each silent-wrong-prone change; escalate to the full 3-role
/claude-code-harness:external-audit <scope> in a fresh session only at a
milestone / irreversible delivery
- Full lifecycle map —
references/operator-playbook.md
Reference map (load on demand — never preload all)
references/native-capabilities.md — current Claude Code built-ins. Read first in Extend / Explain.references/harness-discipline.md — the rules, spawn/workflow policy, anti-patterns. Read in Bootstrap / Extend.references/bootstrap-checklist.md — canonical layout + templates (default shape / MVH-on-request). Read in Bootstrap.references/practice-baseline.md — transmittable behavioral baseline (§1–8) + delivery procedure. Read in Bootstrap (Phase 2b).references/project-docs/ — shipped distillation (workflow.md / testing.md / docs-discipline.md), copied verbatim into the project's .claude/docs/ in Bootstrap (Phase 2c); re-synced by version in Audit.references/audit-checklist.md — structured gap analysis. Read in Audit.references/evidence-base.md — first-party + community sources with a T1–T7 rubric. Read when challenged or asked "where does this come from".references/operator-playbook.md — human-facing lifecycle entry point (what the operator says/prepares at each stage). Point the operator to it; don't preload it as a mode input.references/codex-peer-skill.md — the cross-vendor refuter skill the kit delivers on consent,
behind one mechanical gate: a Codex MCP server is already registered. Read it when the gate is
positive or when the operator asks for it by name; on a negative gate the option is not
mentioned at all — not in a run summary, not as a possibility. The gate condition is stated in
full in bootstrap-checklist.md Phase 2b, so evaluating it never requires loading this file.references/harness-evolution.md — D-cycle (fold journal/audit findings into the canon) + strip revision procedure. Read when running a harness-evolution session.
Non-negotiable principles (all modes)
- Built-ins first. Never duplicate the built-in subagent types
Explore / Plan /
general-purpose / statusline-setup / claude-code-guide (catalogued in
references/native-capabilities.md). The orchestrator is the main thread.
- Main thread owns the task end-to-end. Subagents are for context isolation / parallelism, not ownership.
- Single-agent first; bounded fan-out only when scope exceeds one context. Dynamic
workflows are a built-in — route to them; don't reimplement orchestration. No PM→Architect→Dev→QA pipelines.
- CLAUDE.md is an indexer, not a store (≤ 200 lines). Every line taxes every turn; bloat makes the model ignore it.
- Mechanical invariants beat prompt advice. A repeated correction becomes a hook, validator,
or denied permission — enforced at submit, not mid-thought.
- Single-incident does not become invariant. New rules need multi-source evidence or repeated empirics.
- Give Claude a verification loop it can close (prompt check →
/goal → Stop hook →
/code-review → fresh-context second opinion); tell adversarial reviewers to flag only
correctness/requirement gaps.
- Durable knowledge lives in artifacts (ADRs / progress file / devlog), not chat.
- CLI-subscription only. No managed-agents, beta headers,
--bare, --max-budget-usd, API-key flows.
Output template — Audit report
# Claude Code harness audit — <repo>
## Summary — <1–2 sentences: posture + top-3 gaps>
## Findings
### F1: <one-line gap>
- Where: <file:line> · Why it matters: <token cost / false trigger / duplicates built-in / stale>
- Remediation: <delete X / replace with built-in Y / refactor into hook>
- Principle violated: <which non-negotiable>
## Out of scope — <intentional choices that look like findings>
## Recommended order — <lowest-risk first; mark irreversible items confirm-before-acting>
Output template — Bootstrap plan
# Claude Code harness bootstrap — <repo>
## Detected state — stack / age / existing docs / existing `.claude/` (greenfield = 0 files/0 commits is a state, not a blocker)
## Default shape (production-grade, any project size)
| File | Purpose | ~size |
| CLAUDE.md (root) | entry-point indexer (incl. Working style + verification ladder + continuity duty) | ~80 lines |
| .claude/settings.json | permissions + minimal env | ~20 lines |
| .claude/docs/{workflow,testing,docs-discipline}.md | shipped distillation (verbatim, versioned) | 3 files |
| docs/ARCHITECTURE.md + docs/CODE-MAP.md | real content from the code read | 2 files |
| (no custom subagents/hooks/skills) | built-ins cover it | — |
## Offered — practice baseline (Phase 2b): project embed `.claude/rules/practice-baseline.md` (~80 lines, default) or guarded user-global CLAUDE.md merge (opt-in); operator decides
## Sustained build (Phase 5) adds — oracle (reuse the project's entry point; author scripts/init.sh only if none exists) · .claude/features.json (`priority` on every entry + the intake rule in `rules`: an acceptance-affecting question only the owner can answer is recorded, never decided by the session) · progress+devlog conventions
## Greenfield (no code yet) — ARCHITECTURE/CODE-MAP ship as labelled stubs, never invented facts; on a sustained build the ledger seeds `F0` "get the brief → fill Stack / ARCHITECTURE / CODE-MAP / name the oracle", `passes: false` (no Phase 5 → no ledger: the stub marker carries the trigger)
## Minimal MVH (CLAUDE.md + settings only) — explicit operator request only
## Deferred until justified — subagents (evidence) · hooks (recurring pain) · skills (≥3× repeat)
## Closes with — Phase 8: the bootstrap records itself as episodic entry #1, in the carrier the continuity duty names (live layer + a carrier smoke test)
Gotchas
- Don't preload every reference — load only the active mode's file (inflating the system prompt
contradicts principle 4).
- Don't redesign the operator's own harness mid-conversation if their
.claude/ already encodes this.
- Don't propose API-only features.
- Don't produce generic agentic advice — refer provider-neutral questions to external sources.
- Don't generate skills/hooks/subagents speculatively in Bootstrap.
Maintenance
Version this skill with the primitives: new built-in / hook event → update
native-capabilities.md; new Anthropic essay → add to evidence-base.md with a tier; a major
model release → re-test every "under Opus " invariant. Single anecdotes don't earn
updates (principle 6). On every version bump that touches references/project-docs/*, update
their shipped-by: headers to the new version — Audit's re-sync check keys on them.
Release mechanics are scripted, not manual — run scripts/release.sh <version> from the
repo root (writes plugin.json's version — the sole source of truth and update cache key,
never duplicated in the marketplace entry — verifies shipped-by stamps, stages, prints the
commit/tag/push finish). Two manual releases in a row shipped desynced manifests and
uncommitted content (external audit 2026-07-15), so the ritual is mechanical now. A release
exists only when committed, tagged and pushed: consumers install from origin/main via
/plugin marketplace add nikitaCodeSave/claude-code-harness, and without a version bump
users never receive changes.
When the operator's global baseline (~/.claude/CLAUDE.md §1–8) gains a rule, re-distill
references/practice-baseline.md in the same release — it is a snapshot and drifts silently otherwise.
The codex-peer block carries another vendor's call shape, so it needs a trigger, not a badge:
re-check it against the live tools/list whenever a maintainer's own call is rejected on an
argument, or whenever that vendor's CLI is upgraded on the maintainer's machine — then bump the
block's content-version so installed copies are offered the correction. No sighting, no re-check;
this is the one shipped block whose facts the kit cannot verify from its own repo.
Content-gate for project-docs/* (they ship verbatim into projects that cannot
re-verify upstream facts): state durable principles and stable affordances only. A claim bound
to a ticket number (#NNNNN) or a specific Claude Code version belongs in native-capabilities.md
(dated, re-grounded, never shipped verbatim) or is omitted — never embed a perishable
platform-fact here. The lever against staleness is not shipping the volatile claim, not
badging it: an inline expiry marker is inert without a runner (evidence: a dated "re-check
after X" note rots silently once X passes).
