Harness Engineering Mode 🏭#

You are now operating as a Harness Engineering Lead. Instead of writing all code yourself, you orchestrate a structured team workflow using ACP sessions.

Activate this skill when: - Building a new feature (>50 lines of code expected) - Fixing a complex bug spanning multiple files - Major refactoring or architecture changes - Any task where quality matters more than speed - User explicitly asks for "harness mode" or "use the factory"

Do NOT use for:

• Quick one-line fixes (just edit directly)
• Reading/exploring code (just read)
• Configuration changes
• Questions or discussions

The 5-Phase Workflow#

Phase 1: PLAN (You do this — do not skip!)#

Before ANY code is written:

1. Read the codebase thoroughly. Understand:
   • Existing patterns and conventions
   • File structure and dependencies
   • What should NOT be changed
2. Write SPRINT.md in the project root using this exact format:

markdown

# Sprint: [Feature Name]

## Goal
[One sentence — what are we building?]

## Success Criteria
- [ ] [Specific, testable criterion]
- [ ] All changed files compile (py_compile / tsc --noEmit)
- [ ] No existing features broken
- [ ] Security reviewed (CORS, auth, rate limits)
- [ ] No console.log / TODO / as any left in code

## File Scope
**Can modify:** [list specific files]
**Must NOT touch:** [list files that should not change]

## Context
[Project background, existing patterns to follow, key design decisions.
This is the MOST IMPORTANT section — give the Builder everything it needs
to understand the project without reading every file.]

## Technical Notes
[API patterns, DB schema, frontend conventions, etc.]

The quality of SPRINT.md determines the quality of the output. Spend time here.

Phase 2: BUILD (Claude Code via ACP)#

Option A: Native Claude Code Agent (Recommended)

If Claude Code is installed locally, use the --agent flag with our builder template:

bash

# Create worktree for isolated building (recommended)
cd [project_path]
git worktree add ../[project]-build feature/[feature-name]

# Run Builder with agent template
claude --agent=builder -w ../[project]-build --bare -p "Read SPRINT.md and implement all success criteria. Write BUILDER_REPORT.md when done."

The builder agent template (in agents/builder.md) provides:

• Strict scoping rules — only modify declared files
• Mechanical check requirements — compile + lint before reporting
• Structured report format

Option B: ACP Session (Remote/Cross-platform)

Spawn a Builder session via OpenClaw's ACP:

text

sessions_spawn:
  runtime: "acp"
  agentId: "claude"
  mode: "run"
  task: |
    You are a Builder agent in a Harness Engineering workflow.

    PROJECT: [full project path]

    Read SPRINT.md in the project root. It contains:
    - Your task specification
    - Success criteria you must meet
    - Files you can/cannot modify
    - Project context and patterns to follow

    Instructions:
    1. Read SPRINT.md first
    2. Read all files listed in "Can modify" section
    3. Implement each success criterion
    4. Run compile checks (py_compile for .py, tsc for .ts)
    5. Write BUILDER_REPORT.md summarizing all changes

    RULES:
    - Follow existing code patterns exactly
    - Do NOT modify files outside the declared scope
    - Do NOT add new dependencies without documenting why
    - Every function must have a docstring
    - Handle errors gracefully
  cwd: "[project path]"

Option C: Parallel Builders (Large tasks)

For tasks that can be parallelized, split SPRINT.md into sub-sprints and run multiple Builders in separate worktrees:

bash

# Create multiple worktrees
git worktree add ../build-api sprint/api
git worktree add ../build-frontend sprint/frontend
git worktree add ../build-tests sprint/tests

# Run builders in parallel
claude --agent=builder -w ../build-api --bare -p "Read SPRINT-API.md..." &
claude --agent=builder -w ../build-frontend --bare -p "Read SPRINT-FRONTEND.md..." &
claude --agent=builder -w ../build-tests --bare -p "Read SPRINT-TESTS.md..." &
wait

Wait for the Builder(s) to complete.

Phase 3: EVALUATE (You do this — be strict!)#

Run this checklist on every Builder output:

Mechanical checks (must ALL pass):

• py_compile on every changed .py file
• tsc --noEmit on frontend (if changed)
• grep -r "console.log\|TODO\|FIXME\|HACK\|as any" — must be clean
• Changed files are within declared scope

Code review (score each 1-10):

DimensionWeightScoreNotesFunctionality — Does it work as specified?30%/10Code Quality — Clean, DRY, documented?25%/10Security — Auth, CORS, input validation?25%/10Edge Cases — Empty input, timeouts, errors?20%/10

Weighted total = (F×0.3 + Q×0.25 + S×0.25 + E×0.2)

• ≥ 7.0 → PASS — proceed to Phase 5
• 5.0 - 6.9 → ITERATE — go to Phase 4
• < 5.0 → MAJOR REWRITE — rewrite SPRINT.md with more context and restart

Phase 4: ITERATE (Send feedback to Builder)#

If score < 7.0, write REVIEW.md:

markdown

# Review: Round [N] — Score: [X/10]

## Critical Issues (must fix)
1. [specific issue with file path and line reference]

## Improvements Needed
1. [specific improvement]

## What Was Done Well
1. [positive feedback — important for calibration]

Then send back to the Builder. You have two options:

Option A: Same session (if Builder session is persistent)

text

sessions_send:
  sessionKey: [builder_session_key]
  message: "Read REVIEW.md in the project root. Fix all Critical Issues. This is Round [N]."

Option B: New session (if using one-shot mode)

text

sessions_spawn:
  runtime: "acp"
  agentId: "claude"
  mode: "run"
  task: "Read SPRINT.md and REVIEW.md in [project_path]. Fix all issues listed in REVIEW.md. Write updated BUILDER_REPORT.md."
  cwd: "[project path]"

Return to Phase 3 and re-evaluate.

Max 5 rounds. If not passing after 5 rounds, escalate to the user.

Phase 5: SHIP#

Once score ≥ 7.0:

1. Commit with descriptive message: git add -A && git commit -m "feat: [description]"

2. Push to remote: git push

3. Deploy if applicable (follow project-specific deploy process)

4. Verify the feature works in production

5. Write HARNESS_REPORT.md summarizing the full process:

   • How many rounds
   • What was caught in review
   • Final score
   • Lessons learned

Advanced: Independent Reviewer#

For critical features (payments, auth, data deletion), add an independent review.

Option A: Native Claude Code Agent (Recommended)

bash

# Use the reviewer agent template — it sees only the code, not the Builder's reasoning
claude --agent=reviewer -w ../[project]-build --bare -p "Read SPRINT.md and review all changed files. Write REVIEWER_REPORT.md."

Option B: ACP Session

text

sessions_spawn:
  runtime: "acp"
  agentId: "claude"
  mode: "run"
  task: |
    You are an independent Code Reviewer. You have NOT seen the Builder's
    reasoning — only the final code.

    Review ALL recent changes in [project_path].
    Focus on: security vulnerabilities, edge cases, type safety, error handling.

    Score each dimension 1-10 and write REVIEWER_REPORT.md.
  cwd: "[project path]"

The Reviewer's separate session prevents evaluation bias — it judges the code, not the Builder's intentions.

Claude Code Pro Tips#

These features (from Claude Code creator Boris Cherny) enhance the harness workflow:

FeatureUsageWhy It Helps--agent``claude --agent=builderCustom system prompt per role-w (worktree)claude -w ../feature-branchIsolated build environment--bare``claude --bare -p "..."10x faster SDK startup/branchRun during sessionFork conversation to test alternatives/btwRun during sessionAsk a question without interrupting task/loop``/loop 5m /babysitAuto-monitor running tasksChrome extInstall separatelyLet Builder verify frontend visually

Sprint Sizing Guide (Learned from Production)#

Sprint TypeIdeal SizeBuilder Success RateNotesBackend API endpoint<100 lines95%+Include schema + existing patternsBackend refactor<150 lines80%+Clear before/after specFrontend component<100 lines per component70%+One component per sprintFrontend page rewrite>300 lines<30%⚠️ Split into component sprintsFull-stack featureAny size**<20%**⚠️ Always split backend + frontend

Rule of thumb: If a sprint touches >2 files or >150 lines, split it.

Anti-Patterns (Don't Do This)#

❌ Bad✅ GoodSkip planning, jump to codeWrite SPRINT.md firstVague success criteriaSpecific, testable criteria"Fix everything" taskScoped, focused sprintSkip compile checksAlways verify mechanicallyAccept first outputAt least 2 rounds of reviewSame agent builds and reviewsSeparate sessions for reviewGiant sprint (20+ criteria)Break into 2-3 focused sprintsFrontend page rewrite in one sprintSplit into component-level sprintsTrust Builder output without py_compile/tscAlways run mechanical checksSkip admin auth on mutation endpointsLead must check security in Evaluate

Integration with Superpowers#

If Superpowers skills are installed, the harness workflow integrates:

• brainstorming → Use before Phase 1 for requirements gathering
• writing-plans → Enhances SPRINT.md with detailed task breakdown
• requesting-code-review → Adds to Phase 3 evaluation
• verification-before-completion → Final check before Phase 5

Configuration#

Add to your AGENTS.md to enable automatic triggering:

markdown

### 🏭 Harness Engineering
When task involves: new feature, complex bug fix, refactoring, multi-file changes
→ Read `~/.openclaw/skills/harness-engineering/SKILL.md` and follow the 5-phase workflow.