convez.ai
AgenteAutomaçãoAvançado
agaleraib

Claude Code Harness

agaleraib/claude-harness

Harness enxuto para Claude Code com avaliação adversarial e rubricas de qualidade

Ver no GitHub
InicialPluginScore · de 0 a 100

Framework 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-harness

1 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

Estrelas
1
Forks
1
Acompanhando
0
Saúde
28%
Último commit
há 2 dias
Versão
—
Issues abertas
192
Contribuidores
2

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-review slash 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

ComponentLocationAvailable 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:

  1. Check for uncommitted changes → offer /commit or leave as-is
  2. Show session summary
  3. Ask how the day went (hit / partial / drifted / blocked)
  4. Offer parking lot triage
  5. Ask for tomorrow's first move
  6. Write exit note
  7. 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:

  1. Check staged changes
  2. Scan parking lot for items related to staged files — ask: resolve now or acknowledge?
  3. Run code-reviewer on staged diff
  4. If issues found → fix all / review individually / park all
  5. Commit (max 2 re-review rounds)
  6. Update plan.md if 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 with SB_URL env 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: on in .harness-profile for 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

FileWhat It ScoresKey Dimensions
code-architecture.mdCode qualityStructure, Maintainability, Patterns, Type Safety
data-integrity.mdData correctnessData Modeling (1.5x), Error Handling (1.5x), Consistency, Validation

For Web App Projects (add these)

FileWhat It ScoresKey Dimensions
frontend-ui-design.mdVisual qualityDesign Quality (2x), Originality (2x), Craft, Functionality
performance-accessibility.mdSpeed & a11yLoad Perf, Runtime Perf, Semantic HTML, Responsive
ux-user-flows.mdUser experienceTask 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

FilePurposeCreated by
.harness-profileProject metadata (type, audience, stakes, stack)project-init
parking_lot.mdSide-quests and deferred issuespark (append), session-end (triage)
plan.mdProject planspec-planner (create), commit (update)
.harness-state/last_exit.mdExit note from last sessionsession-end
criteria/Quality rubrics for code-reviewer and ui-evaluatorsetup-harness
procedures/api-security-checklist.mdAPI security reference checklistsetup-harness
CLAUDE.mdBuild commands + non-obvious conventionssetup-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/ and new-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

PracticeWhenWhy
/clear between tasksAfter finishing a feature, before starting something unrelatedResets context completely. Single biggest quality improvement.
/compact Focus on [X]When you can't clear but context is growingSummarizes old context while preserving what matters.
Two corrections → /clearAfter correcting Claude twice on the same issueFailed approaches pollute context. Start fresh with a better prompt that includes what you learned.
/rename your sessionsWhen starting meaningful workclaude --resume shows session names. "oauth-migration" beats "session-47".
Use subagents for researchWhen Claude needs to read many filesResearch in a subagent returns a summary. Direct exploration fills YOUR context with file contents.
/btw for side questionsQuick questions mid-taskAnswer 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:

HookTriggerWhat It Does
Type-check after editPostToolUse on Edit|WriteCatches type errors instantly
Lint before commitPreToolUse on Bash(git commit*)Prevents committing lint failures
Format after editPostToolUse on Edit|WriteAuto-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

PatternProblemFix
Kitchen sink sessionStart with one task, ask something unrelated, go back/clear between unrelated tasks
Correction spiralCorrect → still wrong → correct again → context full of failuresAfter 2 corrections: /clear + better initial prompt
Infinite exploration"Investigate X" without scoping it. Claude reads 100 files.Scope narrowly or use subagents
Bloated CLAUDE.md500+ lines, half outdated. Claude ignores most of it.Keep under 200 lines. Under 50 is better.
Trust-then-verify gapClaude produces plausible code that fails edge casesAlways 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.

SituationStrategyWhy
Small fix (typo, config, one-file bug)MasterDone in one commit, no risk
Cron job tweak, registry updateMasterContained change, easy to verify
Multi-session featureBranchProtects master from half-done work
Risky refactorBranchEasy rollback if it goes wrong
Parallel experimentsBranchTry two approaches without conflicts
Generator agent building for hoursBranchReview before merging to master
Multiple agents working simultaneouslyBranch per agentPrevents 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:

  1. Never let a branch diverge 50+ commits from master. Merge to master frequently.
  2. Check master freshness before branching. If master is days behind, merge current work first.
  3. Always --no-ff merges. Preserves history, makes rollbacks possible.
  4. Never git add -A or git add . Stage specific files by name.
  5. 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 parallel
  • generator + code-reviewer → the build/review loop, no human in between
  • ui-evaluator → adversarial check, runs concurrently with code-reviewer
  • project-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 sessionAgent/skill descriptions only (loaded on demand)
Process enforcement skillsOptional workflow tools — use when helpful
Polite code reviewerAdversarial reviewer that runs tests
No design quality standards5 weighted scoring rubrics
Brainstorming → writing-plans → executing-plansspec-planner → build → code-reviewer
Skills telling model how to thinkCriteria telling model what to check

References

License

MIT

Ver o original no GitHub

Bom para

Relacionados