HARNESS ENGINEER#

A production-grade skill for Claude Code and OpenClaw that transforms a repository into a self-improving software system using six core harness engineering principles.

---

SIX CORE PRINCIPLES#

P1: CONTEXT ENGINEERING#

Treat context as a finite, precious resource. Curate aggressively. See: runtime/context-engineering.md, runtime/compaction.md

P2: TOOL USAGE#

Each sub-agent receives only the tools it needs -- no more. See: tools/TOOL_REGISTRY.md, references/mcp-tools.md

P3: VERIFICATION MECHANISM#

Every output is verified by someone other than who produced it. See: agents/reviewer.md, references/testing-standards.md

P4: STATUS MANAGEMENT#

State lives outside the context window, in the repo. See: runtime/status-management.md, templates/handoff.md

P5: OBSERVABILITY AND FEEDBACK CLOSED-LOOP#

Track what happens. Feed failures back into the harness, not the code. See: runtime/observability.md, runtime/memory-system.md

P6: HUMAN SUPERVISION#

Humans approve high-impact events. The harness surfaces them explicitly. See: runtime/autonomy-rules.md, runtime/prioritization.md

---

NON-NEGOTIABLE RULES#

1. CLAUDE.md / AGENTS.md IS GROUND TRUTH -- read it first, every session.
2. CODEBASE OVER DOCS -- when they conflict, trust the code.
3. 40% CONTEXT RULE -- compact or sub-agent before crossing 40% of context window.
4. NO IMPLEMENTATION WITHOUT a research output, a plan, and validation criteria.
5. GENERATION AND REVIEW ARE ALWAYS SEPARATE -- never the same agent.
6. FAILURE = HARNESS GAP -- fix the harness, not just the symptom.
7. OPTIMIZATION PRIORITY: Security => Correctness => Reliability => Performance => Memory => Maintainability => Cost
8. MINIMAL SCOPE PER SUBAGENT — Estimate codebase size first (use platform file-count or line-count capability — never raw shell). If >5K lines, split into multiple subagents by module/feature/layer. Pin exact files to read (no wandering). One research doc + one code area per subagent max. If a subagent gets killed or times out, the scope was too large — split further. Adaptive timeouts: Default timeouts are guidelines, not hard kills. Check process logs before killing — if the agent is actively producing output, extend the timeout instead of killing. Only kill-and-split if the agent is silent/stuck for >10min or producing garbage. Scale timeouts by effort: S-effort=15min, M-effort=20min, L-effort=30-40min.
9. SUBAGENT PERMISSION MODE — Subagents are spawned by the platform using its native agent mechanism. The permission mode is set by the platform, NOT by this skill. The skill MUST NOT mandate any specific spawn command or permission mode — that decision belongs to the platform's enforcement layer (see PLATFORM_REQUIREMENTS.md Section 8). If the platform's default permission mode is insufficient, the platform operator configures it — the skill never overrides it.
10. ACTIVE MONITORING — Every time you launch a new batch of subagents, track session IDs, expected output files, and remaining queue. If the platform provides a cron/scheduler, use it to detect dead agents. If no scheduler is available, check agent status before each dispatch step. Dead agents stall the pipeline — detect them early.
11. MAX PARALLEL = 5 — Up to 5 Claude Code agents running simultaneously. If rate/API limit errors encountered, drop to 4, then 3, etc until no errors. Resume increasing after 5 clean minutes.
12. TOKEN EXHAUSTION RECOVERY: If ALL active agents hit rate/API limits (429/500), tokens are exhausted. Wait for token refresh before retrying. If the platform provides a scheduler, set a recovery job to resume after refresh. If no scheduler is available, the human operator must manually restart the cycle.
13. 10-MIN STUCK KILL — If any agent produces no output for >10 minutes, log the issue, kill it, and split the task into smaller subtasks before respawning. MUST ALWAYS set a cron job when a subagent is given a command that will run for a while, to periodically check on its progress.
14. TRACKING EVERYWHERE — Every phase, cycle, and step writes to tracking logs. DISPATCH-TRACK, error log, compact summaries, progress logs. Recovery must be able to pick up from any interruption point.

---

SAFE START GUIDE#

Before anything else: read PLATFORM_REQUIREMENTS.md and verify every item. The harness depends on platform enforcement that cannot be checked from these files alone.

Step 1 -- Verify platform requirements (PLATFORM_REQUIREMENTS.md) Run through the five platform capability checks before any other step.

Step 2 -- Sandbox first Run on a throwaway branch. Observe one single-pass cycle before enabling continuous mode.

Step 2 -- Review CONFIG.yaml before every run | loop_mode | single-pass | Change after sandbox validation | | max_parallel_agents | 3 | Increase after confirming behavior | | block_destructive... | true | Never change |

PRs always require human approval. There is no auto-merge.

Step 3 -- Protect main branch Require human reviewers on main/trunk in your git host.

Step 4 -- Graduation path: single-pass => maintenance => continuous

---

HOW TO USE THIS SKILL#

When activated in Claude Code or OpenClaw, read in this order:

1. CLAUDE.md or AGENTS.md if present (base context)
2. CONFIG.yaml (runtime settings)
3. runtime/loop.md (execution model)
4. runtime/context-engineering.md (context budget rules)
5. runtime/status-management.md (restore checkpoint if resuming)
6. MEMORY.md (prior failure context)
7. agents/dispatcher.md (task decomposition model, worktree agent)
8. Begin the loop

---

REFERENCE FILES#

FileWhen to readCLAUDE.md / AGENTS.mdFirst, every session -- base knowledgeCONFIG.yamlAt startupMEMORY.mdAt startup and after every failureruntime/loop.mdEach loop cycleruntime/context-engineering.mdContinuously -- governs context budgetruntime/compaction.mdWhen compacting context within a phaseruntime/status-management.mdAt startup (resume) and after each taskruntime/observability.mdAfter VERIFY phaseruntime/memory-system.mdWhen writing or querying memoryruntime/self-improvement.mdAfter any failureruntime/prioritization.mdWhen selecting the next taskruntime/autonomy-rules.mdWhen blocked or at human gateagents/dispatcher.mdBefore decomposing any task (worktree agent)agents/researcher.mdResearch phase (Q-Agent + R-Agent model)agents/planner.mdPlan phase (3-phase: design, outline, master plan)agents/implementer.mdImplement phase (worktree-driven execution)agents/reviewer.mdReview cycleagents/debugger.mdOn any failureagents/optimizer.mdOptimization modeagents/garbage-collector.mdGC intervaltools/TOOL_REGISTRY.mdBefore any tool calltools/tool-router.mdRouting and redaction rulestools/execution-protocol.mdFull tool call lifecyclereferences/harness-rules.mdCore constraintsreferences/testing-standards.mdBefore writing or running testsreferences/security-performance.mdBefore any implementationreferences/simplification-checklist.mdDuring review and refactoringreferences/git-workflow.mdBefore any commit or PRreferences/mcp-tools.mdMCP tool definitions and per-agent setsreferences/sensitive-paths.mdForbidden read paths -- enforced in-skillreferences/constraints.mdActive prevention rulestemplates/Plans, ADRs, handoffs, status docs