convez.ai
AgenteDevOps & InfraestruturaAvançado
Redtropig

Harness Anchor

Redtropig/harness-anchor

Ambiente disciplinado e verificável para agentes de código de longa duração

Ver no GitHub
InicialPluginScore · de 0 a 100

Camada de restrição em tempo de execução para agentes Claude Code, fornecendo persistência de estado, guardas de escopo, verificação Default-FAIL e suporte de primeira classe para engenharia C/C++. Trabalha em conjunto com superpowers para criar um harness completo baseado nas melhores práticas da Anthropic.

Instalação

$npx convez-ai Redtropig/harness-anchor

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
13
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 3 meses
Versão
v0.18.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Desenvolvimento de projetos C/C++ com CMake, Meson, Make ou Bazel
  • Manutenção de estado e contexto em sessões longas de agentes
  • Implementação de gates anti-alucinação e verificação de conclusão
  • Engenharia de harness com subsistemas de instrução, estado, verificação e ciclo de vida

Veredito

Ferramenta especializada e bem arquitetada para engenheiros que precisam de agentes confiáveis e auditáveis em projetos complexos. Excelente implementação dos padrões de harness da Anthropic, mas requer domínio técnico e integração cuidadosa em workflows existentes.

README

A tradução para o português deste README ainda está na fila.

harness-anchor

Runtime constraint layer for Claude Code agents. Companion to superpowers. Anchors your agent to project state, scope boundaries, evidence-based completion, C/C++ engineering best practices, and a strict docs-lookup discipline.


What it is

superpowers gives your agent process methodology (brainstorm → plan → TDD → review).

harness-anchor gives your agent environment & state discipline (where am I, what's the active feature, what counts as "done", which files exist, what to do when stuck on an unfamiliar tool).

Together they form a complete harness based on Anthropic's Effective Harnesses for Long-Running Agents and the learn-harness-engineering 5-subsystem model:

SubsystemProvided by
Instructionssuperpowers + harness-anchor (using-harness-anchor)
Stateharness-anchor (feature_list.json, progress.md, session-handoff.md)
Verificationharness-anchor (anti-hallucination-gates, /verify) + superpowers (TDD)
Scopeharness-anchor (active-feature lock, scope-jump detection)
Lifecycleharness-anchor (init.sh, /session-end)

Installation (local dev marketplace)

# 1. Register the marketplace (from the published GitHub repo)
claude /plugin marketplace add Redtropig/harness-anchor

# 2. Install
claude /plugin install harness-anchor@harness-anchor-local

# 3. Start a session; SessionStart hook injects harness-anchor banner
claude

You should see a <harness-anchor-state>...</harness-anchor-state> block in the agent's awareness on session start.


Quick start in a new project

# In your project root:
/anchor          # scaffolds AGENTS.md, feature_list.json, init.sh, progress.md,
                 # session-handoff.md, PROJECT-TOC.md, context-budget.md
/cpp-init        # (C/C++ projects only) tunes init.sh, drops .clang-format,
                 # .clang-tidy, scripts/sanitizer-build.sh
/index-project   # builds PROJECT-TOC.md from your git-tracked files
bash init.sh     # health-check the environment

# Then work normally; on session end:
/session-end     # writes structured handoff, appends progress.md, suggests commit

Skills (12 total — auto-triggered from session context)

SkillWhen it fires
using-harness-anchorAuto-loaded at every session start (meta-skill)
project-indexingLocating files; consults PROJECT-TOC.md before Glob
feature-state-keeperStarting/advancing/finishing/blocking a feature
init-verificationStart of work; after env change; when something stops working
self-correction-loopAfter tool/hook returns warning, lint/type/build error
anti-hallucination-gatesBefore claiming "done", "fixed", "passing"
context-budget-disciplineLong sessions; subagents; large file fetches
docs-lookupLooking up unfamiliar tools/APIs/errors (Context7 → WebSearch → uncertainty)
cpp-build-systemsCMake/Meson/Make/Bazel projects
cpp-static-analysisclang-tidy / cppcheck / IWYU
cpp-formattingclang-format
cpp-sanitizersASan / UBSan / TSan / valgrind

Subagents (3 — invoked via Task tool or slash commands)

AgentRole
verification-runnerFresh-context evaluator — runs build/tests/lint, reports evidence paths. Read-only.
cpp-build-doctorDiagnoses C/C++ build failures from compiler output. Read-only.
index-curatorSole writer of PROJECT-TOC.md. Used by /index-project.

Slash commands

CommandWhat it does
/anchorScaffolds harness state files into the current project (overwrites only with explicit approval)
/cpp-initC/C++ project: tunes init.sh, drops .clang-format / .clang-tidy / sanitizer-build.sh
/index-project(Re)builds PROJECT-TOC.md from git-tracked sources
/verifyDispatches verification-runner for fresh-context evaluation; opt-in --fix runs a bounded (≤ 2-cycle) auto-fix loop
/sanitizeC/C++ project: builds under ASan+UBSan (TSan separately), runs tests, reports findings in fixed sections with a .harness-anchor/sanitize-*.log evidence path
/session-endWrites structured handoff + appends progress.md + offers commit
/statusRead-only project overview: active feature, counts, git tree, TOC freshness, handoff head

📖 Full command reference: docs/commands.md — when to reach for each command, its arguments, prerequisites, outputs, and how the harness recommends it.

Hooks (4 — all warn-only, never block)

HookPurpose
SessionStartInjects state banner: active feature, project type, TOC freshness, handoff head, meta-skill body (≤ 2000 token budget)
PostToolUseAfter Edit/Write: regression-warn on pass-feature files; duplicate feature-id warn when feature_list.json is written; clang-tidy on C/C++ files when compile_commands.json present; one-line /sanitize nudge on C/C++ edits (never runs sanitizers inline)
StopNudges progress.md update, session-handoff refresh; never blocks
UserPromptSubmitDetects scope-jump phrases ("顺便", "also", "by the way"); surfaces active feature for confirmation

Key design decisions

  • Warn-only hooks. PostToolUse / Stop / UserPromptSubmit hooks never block — they inject additionalContext for self-correction per Anthropic's "feedback loops > gates" guidance.
  • Default-FAIL contracts. Done criteria start false; the agent must produce a concrete evidence path (build log, test output, lint report) to flip them to true. See skills/anti-hallucination-gates/.
  • Progressive Disclosure. SessionStart injects ≤ 2000 tokens (banner + an adaptive PROJECT-TOC view — the directory map, or the full file list on a small repo — + meta-skill). Deeper references live in skill subfolders, loaded on demand.
  • docs-lookup is canonical. No inline Context7 → WebSearch waterfalls in other skills — they all reference docs-lookup for the procedure (including failure-mode detection and calibrated-uncertainty fallback).
  • Fresh-context evaluator. /verify dispatches verification-runner in a subagent with read-only tools; mitigates "self-grading" leniency per Anthropic's March 2026 three-agent architecture.
  • Heavy ops are explicit commands, not auto-fired hooks. Sanitizer builds (/sanitize) and the opt-in auto-fix loop (/verify --fix, bounded to ≤ 2 fresh-evaluated cycles) far exceed the ≤ 5s warn-only hook budget — a hook may suggest /sanitize, but never runs it inline.
  • C/C++ first-class. Build system auto-detect (CMake/Meson/Make/Bazel), compile_commands.json-aware clang-tidy, sanitizer build templates.

Companion plugins

PluginRoleRequired?
superpowersProcess methodologyRecommended
context7 / first-party docs MCP (e.g. Microsoft Learn)Library & ecosystem docs lookupOptional (docs-lookup prefers first-party when relevant, else WebSearch)

harness-anchor is zero-dependency at runtime (bash + git; Node.js for the scripts/*.mjs index/state tools; python3 used inline by the hooks, with graceful fallback).


Verifying installation

bash scripts/validate-anchor.sh        # self-consistency checks (count printed on run)
bash scripts/validate-manifests.sh     # manifest validation (name, version, sync)
bash tests/hook-contracts/post-tool-use-warn.sh  # PostToolUse hook contract
bash scripts/cpp-detect.sh --target tests/cpp-detection/cmake-fixture
                                       # cpp-detect on a known fixture
bash scripts/measure-context.sh        # SessionStart context budget vs 8000-char cap

CI runs all of these on push/PR (ubuntu + macos) — see .github/workflows/validate.yml.

Troubleshooting? See docs/troubleshooting.md.


License

MIT — see LICENSE.

Changelog

See CHANGELOG.md for release history.

Ver o original no GitHub

Bom para

Relacionados