Claude Code Harness
agaleraib/claude-harness
Harness enxuto para Claude Code com avaliação adversarial e rubricas de qualidade
Ver no GitHubFramework minimalista para agentes Claude Opus 4.7 que implementa avaliadores adversariais, rubricas de scoring e planejamento de specs sem inchar o contexto. Carrega sob 500 tokens no início da sessão e delega peso cognitivo para os pontos fortes nativos do modelo.
Instalação
npx convez-ai agaleraib/claude-harness1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Revisão de código com agentes especializados que capturam falhas de auto-avaliação
- Planejamento de especificações antes de codificação para requisitos claros
- Scoring e qualidade mensurável sem checklist pesado
- Integração com Claude Code mantendo contexto eficiente para tarefas longas
Veredito

Harness robusto que desafia o paradigma de "mais instrução = melhor desempenho". Implementa padrões de pesquisa Anthropic (adversarial review, rubricas minimalistas) com overhead de contexto explicitamente otimizado — ideal para quem já compreende limitações de token budget e quer alavancagem estruturada sem degradação. Construtor avançado de sistemas com Claude.
README
A tradução para o português deste README ainda está na fila.
Claude Code Harness
A lean agent harness for Claude Code, designed for Opus 4.7's native capabilities. Inspired by Anthropic's harness design research and adapted based on their best practices documentation.
Philosophy
"Every component in a harness encodes an assumption about what the model can't do on its own, and those assumptions are worth stress testing." — Anthropic Engineering
Opus 4.7 plans carefully, sustains long tasks, debugs effectively, and follows instructions literally at low effort — so terse rubric items work as written without spelling out "and also check X". This harness doesn't tell the model HOW to think — it tells the model WHAT to check against.
What This Is
- Adversarial evaluation agents that catch what self-assessment misses
- Scoring rubrics that define measurable quality standards
- A spec-planner that ensures requirements are clear before coding starts
- Optional workflow skills you can reach for when you want structure
What This Is NOT
- Process enforcement (everything is optional — use what helps, skip what doesn't)
- Step-by-step checklists loaded into every session
- Elaborate workflow orchestration that fights the model's reasoning
Why Not Superpowers / Heavy Skill Systems?
Research and production experience show that heavy instruction systems degrade Opus 4.7 performance:
- Context bloat: 22k+ tokens of skills loaded at startup = 11% of context consumed before any work begins (GitHub Issue #190)
- Instruction ignoring: Claude models skip CLAUDE.md and skills under load (#23936, #28158)
- Negative ROI on process skills: AGENTbench research (arXiv:2602.11988) found LLM-generated context files decreased success rates
- System-prompt regressions are subtle and slow to detect: Anthropic's own April 23 postmortem traced a month-long Claude Code quality drop to three harness-layer changes — including a 25-word verbosity cap that knocked 3% off internal coding evals. Confirms first-party that adding instructions to the harness can degrade behavior.
- Anthropic's own conclusion: Their harness research removed sprint decomposition, reduced evaluator rounds, and simplified the generator — scaffolding that was essential for earlier models became counterproductive
- Vendor primitives keep absorbing harness territory: Claude Code now ships a built-in
/security-reviewslash command, and Anthropic launched Claude Security in public beta on 2026-04-30 with full-codebase vulnerability scanning + patch generation on Opus 4.7. A custom security-review skill would have been a reasonable addition to this harness six months ago; today it's redundant with first-party tooling. The pattern repeats — keep the harness lean so vendor releases don't deprecate it.
This harness keeps context overhead under 500 tokens at session start (agent descriptions only). Full agent/skill content loads only when invoked.
Architecture
~/.claude/ # User-level (ALL projects)
├── agents/
│ ├── code-reviewer.md # Adversarial code reviewer (tests + types + review)
│ ├── orchestrator.md # Runtime model routing — dispatches to opus/sonnet/haiku
│ ├── project-tracker.md # Save/resume sessions via Second Brain
│ └── spec-planner.md # Discovery-based specification writer
├── skills/ # Optional workflow skills
│ ├── session-start/ # Context injection at start of day
│ ├── session-end/ # Exit ritual + project-tracker
│ ├── micro/ # Focused work blocks
│ ├── park/ # Side-quest capture
│ ├── commit/ # Review → fix/park → commit → plan update
│ ├── project-init/ # One-time project profile setup
│ ├── setup-harness/ # Install harness to a project
│ ├── run-wave/ # Dispatch a plan.md wave to the orchestrator
│ ├── close-wave/ # Merge + finalize a dispatched wave
│ ├── archive-plan/ # Compact ## Recently Shipped in docs/plan.md
│ ├── planning-loop/ # Drive a spec through Codex adversarial review
│ ├── harness-status/ # Read-only cross-repo state scanner
│ ├── deploy-check/ # Pre-deploy validation
│ ├── api-smoke-test/ # End-to-end API testing
│ ├── migration-check/ # DB migration safety review
│ ├── a11y-check/ # Accessibility audit
│ ├── triage-parking/ # Classify + sweep parking_lot.md
│ ├── apply-anthropic-reviews/ # Ship APPLY items from an anthropic-reviews PR
│ ├── memory-prune/ # Cap-management for ~/.claude/memory/*.md
│ ├── shared-root-init/ # Bootstrap the ~/.claude/memory/ shared root
│ └── skill-creator/ # VENDORED — Apache-2.0 fork of Anthropic's skill-creator
│ # (cowork-area-sync/, new-cowork/ live in the repo
│ # but are workspace-specific — not installed universally)
│
~/.config/harness/ # Per-user, per-machine (NOT in any repo)
└── projects.yml # Path-only registry consumed by /harness-status
# Allowed fields: id, path, optional group
# Override via HARNESS_REGISTRY_PATH env var
your-project/ # Project-level (specific projects)
├── .claude/
│ └── agents/
│ ├── ui-evaluator.md # Playwright-based UI testing (web apps only)
│ └── generator.md # Sustained builder (web apps only)
├── criteria/ # Quality rubrics (choose per project)
│ ├── code-architecture.md # ALL projects
│ ├── data-integrity.md # ALL projects
│ ├── frontend-ui-design.md # Web apps only
│ ├── performance-accessibility.md # Web apps only
│ └── ux-user-flows.md # Web apps only
├── procedures/
│ └── api-security-checklist.md # API security reference
├── .harness-profile # Project metadata (audience, stakes, stack)
├── parking_lot.md # Side-quests and deferred issues
├── scripts/
│ └── git-post-commit.sh # Global post-commit hook for Second Brain
├── CLAUDE.md # Build commands + non-obvious conventions
└── .mcp.json # Playwright MCP (web apps only)
Scope Rules
| Component | Location | Available In |
|---|---|---|
| code-reviewer | ~/.claude/agents/ | Every project, always |
| spec-planner | ~/.claude/agents/ | Every project, always |
| orchestrator | ~/.claude/agents/ | Every project, always |
| project-tracker | ~/.claude/agents/ | Every project, always |
| ui-evaluator | <project>/.claude/agents/ | That project only |
| generator | <project>/.claude/agents/ | That project only |
| All skills | ~/.claude/skills/ | Every project, always |
~/.config/harness/projects.yml | ~/.config/harness/ (per-user) | All registered repos via /harness-status |
Criteria files live per-project because quality dimensions differ (a cron job doesn't need UI design rubrics).
Plan and archive layout
docs/plan.md follows a four-section active-board format (Wave 10+):
## Now # H3-block per active wave: spec / status / exit gate
## Next # queued waves not yet started
## Blocked # `- [!] Wave N - <title> - blocked on <reason>`
## Recently Shipped # `- [x] Wave N - <title> -> docs/waves/wave<N>-<slug>.md (<merge SHA>)`
/spec-planner auto-appends new waves to ## Now; /close-wave migrates them to ## Recently Shipped as one-liners; /archive-plan removes rows older than keep_last (default 3).
docs/waves/ is the canonical shipped-wave archive — one Markdown file per closed wave at docs/waves/wave<N>-<slug>.md. Each file carries a YAML frontmatter block (wave_number, slug, spec_path, merge_sha, closed_at) plus the orchestrator summary body (Shipped table, exit-gate proofs, deviations, OQs). When /archive-plan removes a row from ## Recently Shipped, the wave file becomes the sole durable record.
Pre-Wave-10 repos (legacy accreting-log plan.md) keep working — /close-wave accepts both formats. Conversion is opt-in per-repo, not required to use the new skills.
.harness-state/ holds protocol receipts (per docs/protocol/receipt-schema.md): run-wave-<N>-<ts>.yml, close-wave-<N>-<ts>.yml, archive-plan-noop-<ts>.yml, harness-status-<ts>.{md,json,yml}, plus the human-readable wave<N>-closed.md. All §4.2-conformant; cross-adapter idempotency_key equality is mechanically verified by .harness-state/examples/wave2/recompute-wave2-keys.sh.
Skills
All skills are optional — invoke them when you want structure, skip them when you don't. They load on demand (zero context cost until invoked).
Setup Skills
setup-harness
Installs harness files (criteria, agents, CLAUDE.md) into a project. Auto-detects project type or accepts one as argument.
When to use: Once, when starting a new project or adding harness to an existing one.
/setup-harness fullstack
/setup-harness # auto-detects type
project-init
Creates .harness-profile — a YAML file capturing your project's audience, stakes, quality bar, and stack. Other tools (like session-start) read this for context.
When to use: Once per project, right after setup-harness.
/project-init
/project-init --force # regenerate an existing profile
Workflow Skills
session-start
Loads project context at the start of a work session: reads your profile, last exit note, parking lot, recent commits. Asks you to pick today's goal.
When to use: Beginning of a coding day or when sitting down to work after a break.
/session-start
Example output:
## Session context — finflow-deck (fullstack)
Stakes: high — B2B financial product
Last session ended: 2026-04-11
Open parking lot items: 3
### Where you left off
> Tomorrow's first move: wire the /translate endpoint
session-end
Checks for pending commits (offers to run /commit), captures state of play, triages parking lot, writes exit note, and saves session to Second Brain via project-tracker.
When to use: End of a coding day, before closing the laptop.
/session-end
Flow:
- Check for uncommitted changes → offer
/commitor leave as-is - Show session summary
- Ask how the day went (hit / partial / drifted / blocked)
- Offer parking lot triage
- Ask for tomorrow's first move
- Write exit note
- Run project-tracker automatically
micro
Frames a focused work block with one goal and a time budget. Keeps you from drifting into side-quests.
When to use: When starting a chunk of work and you want focus. Good for 10–90 minute blocks.
/micro "wire the /translate endpoint to the profile store"
/micro # asks you for the goal interactively
Example frame:
🎯 Micro-session open
Goal: wire the /translate endpoint to the profile store
Budget: 30m
Started: 14:22
⏰ End of budget: ~14:52
park
Captures a side-quest or unplanned issue to parking_lot.md without switching context. One line, keep going.
When to use: Anytime you notice something that isn't your current task — a bug, a refactor idea, a question to investigate later.
/park "glossary-patcher returns undefined on empty input"
/park "add retry logic to Anthropic SDK calls"
/park # asks you interactively
Output: One line appended to parking_lot.md:
- [2026-04-12] glossary-patcher returns undefined on empty input (source: micro — wire translate endpoint)
triage-parking
Sweeps parking_lot.md on demand: classifies open items (skip / archive / substantive / modest / trivial-auto-ok), archives stale items, queues modest ones, and opens at most one bundled draft PR for items you've explicitly tagged [auto-ok]. Triage-only by default; never auto-merges. Per-repo opt-in via triage_parking.enabled: true in .harness-profile (project-init seeds the block commented out). Skips anything matching /key|secret|credential|token|password/i — secrets never reach a PR. Always writes one line to .harness-state/triage-log.md so you see what the sweep did.
/triage-parking
commit
Reviews staged changes before committing, surfaces related parking lot items, lets you fix or park issues, and updates plan.md if the commit moves a plan item forward.
When to use: When you're ready to commit. Replaces raw git commit with a reviewed commit.
/commit
/commit "feat: add webhook retry logic" # override commit message
Flow:
- Check staged changes
- Scan parking lot for items related to staged files — ask: resolve now or acknowledge?
- Run code-reviewer on staged diff
- If issues found → fix all / review individually / park all
- Commit (max 2 re-review rounds)
- Update
plan.mdif the commit moves a plan item forward
Parked review items are tagged [code-review] with file:line references.
planning-loop
Drives a spec to a Codex-approved verdict in ≤3 rounds, fully autonomously. Two modes: fresh (/planning-loop "<feature blob>" — spec-planner drafts the spec from your pre-answered blob, then loops it through /codex:adversarial-review) and revise (/planning-loop --revise <path-to-spec> [focus] — iterates an existing spec). Spec-planner's discovery phase is suppressed; clarifying answers must be in the initial argument.
Caps at 3 rounds and never auto-ships. On approve → success path. On cap-reached needs-attention → Step 6.5 dispatches arbiters (code-reviewer for detail findings, Plan for scope findings), then either auto-applies (when arbiter rulings are unanimous + mechanical) or prints a 4-option menu with one option marked (Recommended) per Rule 12 (deterministic logic over verdict mix and stop-signals — wrong-premise → 4, 1-line implementation tweaks → 1, same-area regenerated → 3, default → 1). Auto-apply executes via temp-file + atomic rename with SHA-256 hash recheck and a per-finding JSON edit-block contract; you still own /commit. Opt out via PLANNING_LOOP_NO_AUTO_APPLY=1 env var (per-shell) or planning_loop.auto_apply: false in .harness-profile (per-repo). Every round writes findings to .harness-state/planning-loop/.
/planning-loop "RSS reader CLI for solo dev. MVP: subscribe to feeds..."
/planning-loop --revise docs/specs/2026-04-15-rss-mvp.md
/planning-loop --revise docs/specs/2026-04-15-rss-mvp.md "focus on rate limiting"
Requires the openai-codex plugin (/codex:setup must return ready: true).
run-wave
Dispatches the orchestrator to execute a wave from docs/plan.md in an isolated worktree. Reads the ### Wave N block, parses cherry-picked sub-tasks (sub-bullets are authoritative scope), reads each referenced spec, builds a synthetic wave-spec at /tmp/wave-N-<ts>.md, and hands it to the orchestrator with isolation: "worktree". Ends at dispatch — merging belongs to /close-wave.
/run-wave 4
Stops rather than guesses on missing specs, untracked task IDs, or scope ambiguity. Surfaces human-only TODOs (dashboard rotations, live deploys) in the orchestrator's final summary as items NOT to attempt.
close-wave
Closes a fully-shipped wave from an orchestrator's worktree onto master. Idempotent — re-invocation is safe and resumes at the correct step (state-probe at Step 0 detects the resumption point). Verifies the worktree branch (commits, quality-gate from .harness-profile, secret scan, cross-repo symlinks, meta-tooling reminder), checkpoints with you before merging, runs the --no-ff merge with the standard docs/plan.md conflict resolution, processes human-only TODOs, ticks off plan.md with commit hashes, runs the BLOCKING final gate (Step 11), and writes a closure receipt to .harness-state/wave<N>-closed.md.
If any commit in the wave touches meta-tooling paths (skills/, .claude/agents/, .claude/commands/, hooks/, AGENTS.md, WORKFLOW.md), Step 2.5 prints a soft reminder to run /codex:review on the wave diff before merging — a cross-model spot-check that complements the Opus-only code-reviewer running per-commit in /commit. Non-blocking; the reminder fires once at wave-diff scope and is silent on non-meta-tooling waves.
/close-wave 4
Default is push to origin; "close-doesn't-push" is the most common cause of live targets silently reverting to pre-wave state. Reads optional .harness-profile keys for project-specific bits: quality_gate.command, protected_paths, deploy.command, kb.skill. Falls through to safe defaults when fields are absent (e.g. claude-harness has none configured — no quality-gate run, no KB upsert, no deploy hook). Step 0b/8/11b accept both the legacy **Wave N exit gate (PASS …):** annotation and the new four-section closure shape (## Recently Shipped one-liner + docs/waves/<file>.md frontmatter merge_sha) — see "Plan and archive layout" below.
archive-plan
Compacts ## Recently Shipped in docs/plan.md once it grows past keep_last rows (default: 3). Mutating-but-idempotent — re-running on an already-compacted plan.md hits Stage A no-op via the idempotency_key. Sources skills/_shared/lib/emit-receipt.sh and follows the §3.0a reserve-then-mutate lifecycle (atomic temp+rename for docs/plan.md). Emits .harness-state/archive-plan-noop-<ts>.yml.
/archive-plan # default keep_last=3
/archive-plan --dry-run # preview unified diff; no mutation; status=partial
ARCHIVE_PLAN_DRY_RUN=1 /archive-plan
Aborts with aborted-on-ambiguity (no plan.md write) if any row marked for removal links to a docs/waves/wave<N>-<slug>.md file that doesn't exist on disk. The wave file is canonical — once a row leaves ## Recently Shipped, the archive file becomes the sole record.
harness-status
Read-only cross-repo scanner. Reads ~/.config/harness/projects.yml, runs git --no-optional-locks status --porcelain and git --no-optional-locks worktree list --porcelain per registered repo, parses each repo's docs/plan.md ## Now / ## Blocked sections (best-effort), and writes a single Markdown summary plus sibling JSON snapshot under the invoking repo's .harness-state/. Writes nothing in any other repo it scans.
/harness-status # scan all registered repos
/harness-status --group harness # filter by group
/harness-status --id wordwideAI # filter by id
HARNESS_REGISTRY_PATH=/path/to/test.yml /harness-status # override registry path (fixtures/CI)
Tolerates pre-conversion repos ((pre-v2 plan format; skipped)) without failing the whole scan. Hard read-only invariant verified by fixture: git rev-parse HEAD, .git/index SHA-256, .git/HEAD SHA-256, and git status --porcelain output all byte-identical pre/post on every scanned repo. Exempt from §3.0a Stage A no-op reuse — every invocation rescans live state, so two consecutive runs produce different idempotency_key.value strings (the receipt records idempotency_key.trace.stage_a_exempt: true; documented in docs/protocol/receipt-schema.md).
Safety Check Skills
deploy-check
Validates deployment readiness: env vars, secrets, rollback plan, smoke test, monitoring. Catches the things you forget at 5pm on a Friday.
When to use: Before any production deploy.
/deploy-check
What it checks:
- Required env vars are set (not placeholders)
- No hardcoded secrets in code
- Rollback plan exists
- Smoke test script exists and is runnable
- Monitoring/alerting is configured
api-smoke-test
Generates or runs a curl/jq-based bash script that tests your API's critical paths against a live URL.
When to use: After deploying, or when you want a quick end-to-end sanity check.
/api-smoke-test generate # creates the smoke test script
/api-smoke-test run http://localhost:3000 # runs it against a URL
migration-check
Reviews a database migration file for safety: reversibility, concurrent-write safety, backfill behavior, index locking.
When to use: Before running any schema change in production.
/migration-check migrations/0042_add_user_email.sql
/migration-check # asks which file to check
What it checks:
- Is the migration reversible (has a down/rollback)?
- Will it lock tables under concurrent writes?
- Are backfills safe for large tables?
- Are new indexes created concurrently?
a11y-check
Runs an accessibility audit using axe-core via Playwright. Flags WCAG violations on your pages.
When to use: For webapp/fullstack projects, after building UI features.
/a11y-check http://localhost:3000
/a11y-check http://localhost:3000/dashboard,http://localhost:3000/settings
Authoring Skills
skill-creator (vendored)
Create new skills, improve existing ones, and benchmark them with evals. Forked from Anthropic's official skill-creator (Apache-2.0) and kept in-repo so local additions survive a reinstall — notably references/anthropic-skill-authoring.md, a vendored snapshot of Anthropic's skill-authoring best practices that the skill reads before drafting. Maintained as a fork: upstream updates are merged by hand.
When to use: building a new skill from scratch, or editing/optimizing/eval-testing an existing one.
/skill-creator
Not harness-authored — it's listed here because it lives in skills/ and ships out via the same symlink convention as the rest. This is the one exception to "skills/ is harness-original work."
Agents
code-reviewer (Universal)
What it does: Runs tests, checks types, reviews code adversarially. Scores against criteria/ if present.
When to use: After implementing a feature, fixing a bug, or before committing. Works on any code — backend, frontend, scripts, infrastructure. Also runs automatically as part of the /commit skill.
How to invoke:
Use the code-reviewer to review my changes
Or more specifically:
Use the code-reviewer to review src/lib/scheduler/ — I refactored the job runner
What it does NOT do: Fix code. It reports problems with enough specificity that fixes are obvious.
How this complements Anthropic's cloud reviewers
The harness's code-reviewer runs locally, pre-push, against project criteria/, and is invoked synchronously by /commit. As of Code w/ Claude 2026, Anthropic also ships two cloud reviewers that operate at different layers: Code Review (Team/Enterprise; auto-runs on every PR; fan-out parallel agents + verification step) and /ultrareview (Pro/Max; user-triggered; 10–20 min cloud run on the current branch or a PR). Both are billed by token usage — see the linked post for current pricing. Use the local code-reviewer for the build/review loop before commit (cheap, rubric-anchored, blocks at /commit); use Anthropic's cloud reviewers for the post-push pass on substantive PRs that are about to merge (PR-context-aware, multi-agent fan-out). They are complementary, not redundant — different layers, different costs, different recall/precision.
spec-planner (Universal)
What it does: Interviews you about your idea (1-3 rounds of questions), then writes a detailed spec with testable requirements, data model, build phases, and explicit out-of-scope section. Also compares existing specs to help you prioritize what to build first.
When to use: Before starting any non-trivial feature or module. If the diff would be more than ~50 lines, spec it first. Also use when deciding between multiple specs.
How to invoke:
Use the spec-planner — I want to add a webhook notification system
Compare mode — deciding what to build first:
Use the spec-planner to compare these two specs and tell me which to build first:
- docs/specs/2026-04-08-narrative-state.md
- docs/specs/2026-04-10-mempalace-integration.md
Compares specs on dependencies, scope, risk, value unlocked, and readiness. Gives a clear recommendation.
Prior Work mode — building on an existing spec:
Use the spec-planner — I want to add contradiction detection to editorial memory.
Build on docs/specs/2026-04-12-editorial-memory.md
Reads the referenced spec and includes a ## Prior Work section in the new spec linking what it builds on, assumes, and changes. Prevents contradicting or duplicating existing work.
Output: Writes spec to docs/specs/YYYY-MM-DD-<topic>.md.
What it does NOT do: Write code or implementation plans. It defines WHAT to build, not HOW.
project-tracker (Universal, Proactive)
What it does: Saves the current Claude Code session as a project in Second Brain for later resumption. Auto-gathers git state, recent commits, files changed, specs, and plan content. Creates or updates the project with branch/workstream tracking.
When it runs: Automatically at session-end. Also proactively before commits when meaningful work was done (new features, bug fixes, spec changes). Can be invoked explicitly.
How it works:
- CREATE mode (new repo, no project in SB): Gathers context, asks for project name + priority (only questions it asks), creates the project via SB API with repo and branch linked, saves spec/plan content, creates tasks from plan files
- UPDATE mode (project exists for this repo): Refreshes the branch's context snapshot, marks completed tasks, adds a session note — all silently, no questions asked
Communication: Direct HTTP calls to the Second Brain API (curl). No MCP dependency — works in any repo without special configuration.
Complementary automation: A global git post-commit hook (~/.git-hooks/post-commit) handles updates outside Claude Code sessions — manual commits, cron snapshots, other tools. It updates commit hash, dirty files, and auto-completes tasks by matching commit messages. The agent and hook write to the same API and don't conflict.
Backfill example — reconciling drifted task state:
Use the project-tracker to walk the git history and mark completed tasks
Walks recent commits on the current branch, fuzzy-matches each commit message against the project's pending tasks in Second Brain, and marks matched tasks as done. Use this when:
- You've been committing outside Claude Code (manual commits, IDE commits, another machine without the post-commit hook installed) and the tracker has fallen behind
- You just installed the post-commit hook on a project that already has commit history — past commits won't trigger the hook, so this backfills them in one pass
- A task list and the actual code have drifted and you want to reconcile in bulk instead of manually ticking items
- You're resuming a project after weeks away and want to know what's actually done before deciding what to do next
It's read-only against git (only git log / git show) and only writes task completions to Second Brain — it won't touch code, branches, or commits.
Prerequisites:
- Second Brain API reachable (default:
http://10.1.10.82:3001, override withSB_URLenv var) - A git repository (the agent reads branch, commits, and diff)
What it does NOT do: Fix code or make decisions. It only records state.
ui-evaluator (Web Apps Only)
What it does: Launches Playwright, navigates your running app, takes screenshots, tests every interaction, and scores against all criteria/ rubrics. Reports with specific evidence (hex values, pixel measurements, viewport sizes).
When to use: After the generator completes a build, or after you've made significant UI changes.
Prerequisites:
- A running dev server (typically
localhost:3000) - Playwright MCP configured in
.mcp.json - Criteria files in
criteria/
How to invoke:
Use the ui-evaluator to test the app running on localhost:3000
What it does NOT do: Fix code. It's the critic, not the fixer.
generator (Web Apps Only)
What it does: Reads a spec from docs/specs/ or docs/plan.md and builds continuously — data layer first, then structure, then functionality, then polish. Commits working increments. Iterates on evaluator feedback.
When to use: For sustained multi-feature web app builds where you want the full plan → build → evaluate loop.
How to invoke:
Use the generator to implement the spec in docs/specs/2026-04-02-dashboard.md
orchestrator (Universal)
What it does: Reads spec tasks and dispatches each to opus, sonnet, or haiku subagents based on task complexity — decided at runtime, not at spec time. Follows Anthropic's orchestrator-worker pattern. Runs each completed task through /commit (code-reviewer + plan update + spec checklist).
Prerequisites:
- A spec file with tasks in spec-planner format (
Files:,Depends on:,Verify:per task) model_routing: onin.harness-profilefor full routing (without it, runs as a guided executor on the current model)
Three ways to work
You choose the level of automation. All three go through code-reviewer on every commit — you're always in the loop on quality.
1. Fully manual — you write the code, orchestrator not involved:
/micro "Task 6 — harness wiring"
... you write the code ...
"block done" → triggers /commit (review + plan update)
2. Orchestrator per task — you pick the task, orchestrator implements it:
/micro "Task 6 — harness wiring"
Use the orchestrator to run Task 6 from docs/specs/2026-04-12-editorial-memory.md
"block done" → triggers /commit
The orchestrator picks the right model, dispatches a subagent, verifies the result. You stay in control of which task runs when.
3. Orchestrator per phase — hand off a full phase:
Use the orchestrator to build Phase 2 from docs/specs/2026-04-12-editorial-memory.md
The orchestrator runs every task in the phase automatically: pick model → dispatch → verify → /commit → next task. It stops whenever code-reviewer finds issues and asks you what to do (fix all / review individually / park all). You're hands-off until something needs judgment.
Routing logic (runtime, not hardcoded)
The orchestrator evaluates each task at execution time and decides:
- Haiku → read-only, scanning, boilerplate, mechanical tasks
- Sonnet → standard implementation following existing patterns
- Opus → architecture, ambiguity, security, complex algorithms
- High-stakes projects (
stakes.level: high) → never route code-writing to haiku
Each route also picks an effort (low / medium / high / xhigh) — read-only tasks use low, code-reviewer and multi-file work use xhigh, and the default tracks stakes.level via the effort_default pin. See .claude/agents/orchestrator.md for the full routing table.
Safety chain
Every task, regardless of which model wrote it, goes through:
orchestrator completes task → verify step → /commit → code-reviewer → fix/park → commit → plan.md → spec checklist
Failed verification → auto-promotes to opus and retries once. Two failures → stops and asks you.
Logging
All routing decisions, verifications, promotions, and durations are logged to .harness-state/orchestrator.log for review. Persists across phases.
Parallel execution
Tasks with no dependency and no file overlap run in parallel using worktrees. Shared state (migrations, config) is always sequential.
Criteria
Criteria files define what "good" means with specific, scorable dimensions. The evaluator and code-reviewer use these as their grading rubric.
For ALL Projects
| File | What It Scores | Key Dimensions |
|---|---|---|
code-architecture.md | Code quality | Structure, Maintainability, Patterns, Type Safety |
data-integrity.md | Data correctness | Data Modeling (1.5x), Error Handling (1.5x), Consistency, Validation |
For Web App Projects (add these)
| File | What It Scores | Key Dimensions |
|---|---|---|
frontend-ui-design.md | Visual quality | Design Quality (2x), Originality (2x), Craft, Functionality |
performance-accessibility.md | Speed & a11y | Load Perf, Runtime Perf, Semantic HTML, Responsive |
ux-user-flows.md | User experience | Task Completion (1.5x), Info Architecture (1.5x), Product Depth (1.5x), Feedback, Onboarding |
Hard Fail Thresholds
Every criteria file defines hard fails — if ANY dimension scores 3 or below, the entire category fails regardless of the weighted average. Some criteria have stricter thresholds (e.g., Data Consistency at 4 or below also fails).
Files
| File | Purpose | Created by |
|---|---|---|
.harness-profile | Project metadata (type, audience, stakes, stack) | project-init |
parking_lot.md | Side-quests and deferred issues | park (append), session-end (triage) |
plan.md | Project plan | spec-planner (create), commit (update) |
.harness-state/last_exit.md | Exit note from last session | session-end |
criteria/ | Quality rubrics for code-reviewer and ui-evaluator | setup-harness |
procedures/api-security-checklist.md | API security reference checklist | setup-harness |
CLAUDE.md | Build commands + non-obvious conventions | setup-harness |
Setup
1. Install User-Level Components (once, applies everywhere)
# Copy the universal agents to your user config
cp .claude/agents/code-reviewer.md ~/.claude/agents/
cp .claude/agents/spec-planner.md ~/.claude/agents/
cp .claude/agents/project-tracker.md ~/.claude/agents/
# Copy all skills — whole directories, not just SKILL.md. Many skills ship
# lib/ helpers (archive-plan, harness-status, memory-prune, shared-root-init),
# templates/ (setup-harness), or references/+evals/ (planning-loop, skill-creator)
# that the skill cannot run without.
for skill in session-start session-end micro park commit project-init \
setup-harness deploy-check api-smoke-test migration-check a11y-check \
run-wave close-wave archive-plan harness-status planning-loop \
memory-prune shared-root-init triage-parking apply-anthropic-reviews \
skill-creator; do
rm -rf ~/.claude/skills/$skill
cp -R skills/$skill ~/.claude/skills/$skill
done
# Copy the shared receipt-emission helper (sourced by run-wave, close-wave,
# archive-plan, harness-status, memory-prune, commit)
mkdir -p ~/.claude/skills/_shared/lib
cp skills/_shared/lib/emit-receipt.sh ~/.claude/skills/_shared/lib/
That's it. These agents and skills are now available in every Claude Code session across all your projects.
Not installed by the loop above: the repo also contains
cowork-area-sync/andnew-cowork/, which are tied to a specific cowork/workspace platform and are intentionally excluded from the universal install. Add them by hand only if you use that workflow:cp -R skills/new-cowork ~/.claude/skills/new-cowork.
Or use the skill to automate setup for a specific project:
/setup-harness fullstack
/project-init
Optional: Bootstrap the cross-repo registry (for /harness-status)
/harness-status reads ~/.config/harness/projects.yml — a per-user, per-machine, path-only registry of harness-managed repos. Missing registry is a friendly no-op (the skill prints "no projects registered" and exits 0); bootstrap once per machine when you want cross-repo visibility:
mkdir -p ~/.config/harness
$EDITOR ~/.config/harness/projects.yml
Use the example fixture as a template:
projects:
- id: claude-harness
path: /Users/you/workspace/claude-harness
group: harness
- id: my-product
path: /Users/you/workspace/my-product
group: product
Allowed fields: id (kebab-case, unique), path (absolute), optional group. The parser refuses unknown top-level fields (no quality_gate, protected_paths, tracker_team, etc. — those belong in per-repo .harness-profile). Override the registry path with HARNESS_REGISTRY_PATH=/some/test.yml /harness-status for fixtures or CI without touching home.
2. Set Up a New Project
For a backend/API/script project:
cd your-project
# Add criteria (pick what applies)
mkdir -p criteria
cp /path/to/claude-harness/criteria/code-architecture.md criteria/
cp /path/to/claude-harness/criteria/data-integrity.md criteria/
# Write a lean CLAUDE.md (see examples/backend-project/)
# Include: build commands, test commands, non-obvious conventions
# Keep under 200 lines. Under 50 is better.
No project-level agents needed — the user-level code-reviewer and spec-planner handle everything.
For a web application project:
cd your-project
# Add all criteria
mkdir -p criteria .claude/agents
cp /path/to/claude-harness/criteria/*.md criteria/
# Add UI-specific agents
cp /path/to/claude-harness/.claude/agents/ui-evaluator.md .claude/agents/
cp /path/to/claude-harness/.claude/agents/generator.md .claude/agents/
# Add Playwright MCP
cat > .mcp.json << 'EOF'
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
}
}
EOF
# Write a lean CLAUDE.md (see examples/web-app-project/)
3. Write Your CLAUDE.md
Follow Anthropic's guidelines:
# Project Name
## Build & Test
bun run build
bun test
## Conventions
- TypeScript strict. No `any`.
- [Only rules Claude can't figure out from reading the code]
## Verification
After changes: `bun run build && bun test`
Rules for CLAUDE.md:
- Under 200 lines. Under 50 is better.
- Only include what Claude would get wrong without the instruction
- If Claude already does it correctly, delete the rule
- Treat it like code: prune regularly
- Layer separation: CLAUDE.md is the lay of the land (build commands, where docs live, non-obvious project conventions). Project-specific expertise belongs in skills, not here. If a rule starts to read like a tutorial, it's a skill — extract it. (source)
Workflows
Workflow A: Quick Feature (any project)
You: "Add retry logic to the webhook sender"
Claude: [implements it using native planning + execution]
You: /commit
Claude: [reviews changes, fix/park issues, commits, updates plan]
Total context overhead: ~200 tokens (code-reviewer description). Full agent loads only when invoked.
Workflow B: New Module (any project)
You: "Use the spec-planner — I want to add a rate limiter"
Claude: [spec-planner asks 2-6 questions, writes spec]
You: [review spec, approve]
You: "Implement the spec in docs/specs/2026-04-02-rate-limiter.md"
Claude: [implements from spec]
You: /commit
Claude: [code-review → fix/park → commit → plan.md updated]
Workflow C: Full Web App Build (UI projects only)
You: "Use the spec-planner for the analytics dashboard"
Claude: [discovery → spec → docs/specs/]
You: "Use the generator to build phase 1 from the spec"
Claude: [sustained implementation, commits incrementally]
You: "Use the ui-evaluator to test localhost:3000"
Claude: [Playwright testing, screenshots, scoring against all criteria]
You: "Fix the critical issues from the evaluation"
Claude: [implements fixes]
You: "Evaluate again"
Claude: [re-scores, verifies fixes]
Workflow D: Full Day Session
You: /session-start # context injection, pick today's goal
You: /micro "wire the translate API" # frame a focused block
... work ...
You: /park "refactor the round loop" # side-quest captured, keep going
... work ...
You: /commit # review → commit → plan update
You: /session-end # exit note, triage, save to Second Brain
Adapting Criteria for Your Domain
The criteria files are starting points. Adapt them to your domain:
Financial applications (FinFlow):
- Add data density and chart readability to frontend criteria
- Add regulatory compliance to data integrity
- Add multi-language/white-label to UX criteria
Infrastructure tools (monitoring dashboards):
- Add real-time update performance to frontend criteria
- Add alerting accuracy to data integrity
API services:
- Skip all frontend criteria
- Add API contract compliance to code architecture
- Add rate limiting and auth to data integrity
Session Hygiene
The harness gives you better agents and criteria, but how you manage sessions determines whether Opus 4.7 performs at its best or degrades into confused loops. These practices come directly from Anthropic's best practices and production experience.
The One Rule
Context is your most precious resource. Everything else follows from this.
Claude's performance degrades as context fills. At 0-20% usage, output is reliable. Past 60%, retrieval starts failing and instructions get lost. The status line (ctx: 42% used) tells you where you are.
Practices
| Practice | When | Why |
|---|---|---|
/clear between tasks | After finishing a feature, before starting something unrelated | Resets context completely. Single biggest quality improvement. |
/compact Focus on [X] | When you can't clear but context is growing | Summarizes old context while preserving what matters. |
Two corrections → /clear | After correcting Claude twice on the same issue | Failed approaches pollute context. Start fresh with a better prompt that includes what you learned. |
/rename your sessions | When starting meaningful work | claude --resume shows session names. "oauth-migration" beats "session-47". |
| Use subagents for research | When Claude needs to read many files | Research in a subagent returns a summary. Direct exploration fills YOUR context with file contents. |
/btw for side questions | Quick questions mid-task | Answer appears in overlay, never enters conversation history. Zero context cost. |
Permission Mode
Use auto mode to eliminate permission prompts without compromising safety:
// In ~/.claude/settings.json
{
"permissions": {
"mode": "auto",
"allow": ["Bash(*)", "Read(*)", "Write(*)", "Edit(*)", "Glob(*)", "Grep(*)"]
}
}
Auto mode uses a classifier to approve routine actions and block risky ones (scope escalation, unknown infrastructure, hostile-content-driven actions). Your explicit allowlist acts as a fast path — the classifier only evaluates actions not already permitted.
For unattended builds: claude --permission-mode auto -p "fix all lint errors". Auto mode aborts if the classifier repeatedly blocks actions, since there's no user to fall back to.
Hooks (Deterministic Automation)
Unlike CLAUDE.md instructions (which Opus 4.7 can ignore under load), hooks always fire:
// In ~/.claude/settings.json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "if [ -f tsconfig.json ]; then npx tsc --noEmit --pretty 2>&1 | tail -20; fi"
}
]
}
]
}
}
This runs tsc --noEmit after every file edit in TypeScript projects. Claude sees type errors immediately without being told to check. Other high-value hooks:
| Hook | Trigger | What It Does |
|---|---|---|
| Type-check after edit | PostToolUse on Edit|Write | Catches type errors instantly |
| Lint before commit | PreToolUse on Bash(git commit*) | Prevents committing lint failures |
| Format after edit | PostToolUse on Edit|Write | Auto-formats with prettier/biome |
Rule of thumb: If you find yourself writing "always run X after Y" in CLAUDE.md, convert it to a hook instead. Hooks are guaranteed; CLAUDE.md instructions are advisory.
Caveat: Avoid using Stop hooks for blocking signals — they fire on every turn and can create infinite loops with no escape hatch. Use hooks for deterministic automation (type-check, lint, format), not for advisory feedback.
Global Git Post-Commit Hook
A git post-commit hook at ~/.git-hooks/post-commit updates Second Brain automatically on every commit across all repos:
- Updates the project's last commit hash and message
- Reports dirty worktree state (uncommitted files)
- Auto-completes tasks by fuzzy-matching commit messages against pending task titles
- Creates branch records for new branches automatically
Setup:
# Set global hooks path (once)
git config --global core.hooksPath ~/.git-hooks
# Install the hook
mkdir -p ~/.git-hooks
cp scripts/git-post-commit.sh ~/.git-hooks/post-commit
chmod +x ~/.git-hooks/post-commit
The hook fires on every git commit in any repo. If the repo name doesn't match a project in SB, it silently does nothing. It runs curl in the background so it never slows down commits.
Status Line
Track context usage in real time:
// In ~/.claude/settings.json
{
"statusLine": {
"type": "command",
"command": "input=$(cat); used=$(echo \"$input\" | jq -r '.context_window.used_percentage // empty'); remaining=$(echo \"$input\" | jq -r '.context_window.remaining_percentage // empty'); if [ -n \"$used\" ]; then printf \"ctx: %.0f%% used (%.0f%% left)\" \"$used\" \"$remaining\"; else printf \"ctx: waiting...\"; fi"
}
}
Shows ctx: 42% used (58% left) in your terminal. When you see it climbing past 50%, consider /compact or /clear.
Anti-Patterns
| Pattern | Problem | Fix |
|---|---|---|
| Kitchen sink session | Start with one task, ask something unrelated, go back | /clear between unrelated tasks |
| Correction spiral | Correct → still wrong → correct again → context full of failures | After 2 corrections: /clear + better initial prompt |
| Infinite exploration | "Investigate X" without scoping it. Claude reads 100 files. | Scope narrowly or use subagents |
| Bloated CLAUDE.md | 500+ lines, half outdated. Claude ignores most of it. | Keep under 200 lines. Under 50 is better. |
| Trust-then-verify gap | Claude produces plausible code that fails edge cases | Always provide verification: tests, build, screenshots |
Git Branching Guide
When to Branch vs Work on Master
If you'll finish it in this session → master. If it'll span sessions or could break things → branch.
| Situation | Strategy | Why |
|---|---|---|
| Small fix (typo, config, one-file bug) | Master | Done in one commit, no risk |
| Cron job tweak, registry update | Master | Contained change, easy to verify |
| Multi-session feature | Branch | Protects master from half-done work |
| Risky refactor | Branch | Easy rollback if it goes wrong |
| Parallel experiments | Branch | Try two approaches without conflicts |
| Generator agent building for hours | Branch | Review before merging to master |
| Multiple agents working simultaneously | Branch per agent | Prevents stepping on each other |
Branch Naming
feat/board-v2 # New feature
fix/reconciliation-dup # Bug fix
refactor/scheduler # Restructuring
experiment/qwen3-eval # Throwaway experiment
Branch Lifecycle
# 1. Create from up-to-date master
git checkout master
git pull
git checkout -b feat/my-feature
# 2. Work, commit incrementally
# ... make changes ...
git add src/specific-file.ts
git commit -m "feat: add webhook retry logic"
# 3. Keep in sync (if branch lives more than a day)
git merge master # or: git rebase master
# 4. Merge back with --no-ff (preserves history)
git checkout master
git merge --no-ff feat/my-feature
# 5. Clean up
git branch -d feat/my-feature
Critical rule: Always merge with --no-ff. Fast-forward merges lose branch history and make rollbacks harder.
Git Worktrees (Parallel Sessions)
Worktrees let you have the same repo checked out in multiple directories simultaneously — each with its own branch. This is essential when:
- You want to run Claude Code in parallel on different features (each session needs its own directory)
- The generator agent is building for hours and you want to keep coding something else
- You want to keep a dev server running on master while working on a branch
- A scheduled Claude agent is working on one task while you work on another
# Create a worktree for a feature
git worktree add ../myproject-feat-X feat/X
# Work in it (separate directory, separate Claude session)
cd ../myproject-feat-X
claude
# When done, merge from the main directory
cd ../myproject
git merge --no-ff feat/X
# Clean up
git worktree remove ../myproject-feat-X
Each worktree is a full working copy with its own .claude/agents/ and criteria/ — the harness works in worktrees automatically.
Safety Rules
These rules exist because of a real incident where 174 files were accidentally deleted during a git operation:
- Never let a branch diverge 50+ commits from master. Merge to master frequently.
- Check master freshness before branching. If master is days behind, merge current work first.
- Always
--no-ffmerges. Preserves history, makes rollbacks possible. - Never
git add -Aorgit add .Stage specific files by name. - Pre-push deletion check. If more than 10 files are deleted in the diff, stop and verify:
git diff origin/master --stat | grep "delete" | wc -l
Decision Flowchart
Will I finish this in one session?
├── Yes → Is it risky? (refactor, schema change, breaking API)
│ ├── No → Work on master
│ └── Yes → Branch (easy rollback)
└── No → Branch
└── Will I need Claude Code running in parallel?
├── No → Regular branch (same directory)
└── Yes → Git worktree (separate directory)
Multi-agent coordination (2026 trend)
Use these together for day-scale work:
orchestrator→ fans tasks out to sonnet/haiku in parallelgenerator+code-reviewer→ the build/review loop, no human in betweenui-evaluator→ adversarial check, runs concurrently with code-reviewerproject-tracker+claude-progress.txt→ hand off between sessions
Human checkpoints (by design):
- After spec-planner (before coding starts)
- After code-reviewer (before commit)
- After ui-evaluator (before deploy)
What This Replaces
| Before (Superpowers + heavy CLAUDE.md) | After (this harness) |
|---|---|
| 22k tokens at startup | ~500 tokens at startup |
| 14 skills loaded every session | Agent/skill descriptions only (loaded on demand) |
| Process enforcement skills | Optional workflow tools — use when helpful |
| Polite code reviewer | Adversarial reviewer that runs tests |
| No design quality standards | 5 weighted scoring rubrics |
| Brainstorming → writing-plans → executing-plans | spec-planner → build → code-reviewer |
| Skills telling model how to think | Criteria telling model what to check |
References
- Harness Design for Long-Running Apps — Anthropic Engineering
- Best Practices for Claude Code — Claude Code Docs
- Extend Claude Code — Skills, Subagents, Hooks overview
- Custom Subagents — Agent definition reference
- Skills — Skill system reference
- Building Effective Agents — "Start simple, add complexity only when needed"
- How We Built Our Multi-Agent Research System — Orchestrator-worker patterns, model routing
- Context Window Visualization — Understanding what consumes your context
License
MIT