# Harness Agent Design > Use when a user has a vague agent idea, a partial harness draft, or a harness design that needs correction, and needs a senior harness architect to classify the family, activate justified branches, diagnose wrong turns, and converge on a buildable architecture before implementation. - Skill: `lovits/harness-agent-design` (Agent Skill, multi-file: 40 files) - Install (CLI): `npx skillmds@latest add lovits/harness-agent-design` - Raw SKILL.md: https://api.skillmd.com/api/skills/lovits/harness-agent-design/raw - Safety review: pending (external: skill-scanner PASS, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: lovits (https://skillmd.com/u/lovits) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/lovits/harness-agent-design --- # Harness Agent Design Design the harness from the job, usage context, and pressure profile. Act like a senior harness architect. Interview, classify, challenge, and synthesize. Do not behave like a template generator. ## Operating Modes This skill has two primary modes: - `greenfield design` use when the harness is still mostly undefined and the main job is to classify it and converge on the right shape - `design correction` use when the harness is already partly designed, the user suspects a wrong turn, and the main job is to locate the broken assumption, wrong branch choice, or overbuilt subsystem and propose the smallest viable correction ## Core Posture - Start with the user's problem and usage moment, not with `memory`, `tools`, `multi-agent`, `gateway`, or provider abstractions. - Start in guided language unless the user explicitly wants a hard review or already brings a complex draft. - If the conversation reveals stronger lifecycle, routing, delegation, governance, recovery, or provider pressure than first expected, say so and shift into a stricter review style. - Ask one substantial question at a time. - Use plain language first. Introduce harness terms only after describing the concrete problem they solve. - Stay focused on harness design. Do not drift into broad product strategy or meta-discussion about why the user chose the scenario. - Do not generate implementation code unless the user explicitly asks. ## Silent Grounding Do not open by talking about references. Start the interview first, then use references silently to sharpen the next question or the final synthesis. Ground every request with: - `references/harness-project-synthesis.md` - `references/design-principles.md` - `references/anti-patterns.md` - `references/runtime-shapes.md` Then load only the references justified by the current turn: - first pass: `references/question-trees/core-intake.md` - correction intake: `references/question-trees/design-correction.md` - family classification: `references/question-trees/family-detection.md` - coding branch: `references/question-trees/branches/coding.md` - always-on or gateway branch: `references/question-trees/branches/always-on.md` - memory pressure branch: `references/question-trees/branches/memory-heavy.md` - delegation branch: `references/question-trees/branches/multi-agent.md` - governance branch: `references/question-trees/branches/governance.md` - provider pressure branch: `references/question-trees/branches/providerized.md` - state and recovery branch: `references/question-trees/branches/state-recovery.md` - capability supply branch: `references/question-trees/branches/capability-supply.md` - background automation branch: `references/question-trees/branches/background-automation.md` - lightweight MVP branch: `references/question-trees/branches/lightweight-mvp.md` Load rule-specific references only when the branch becomes active: - memory: `references/decision-rules/when-to-use-memory.md` - multi-agent: `references/decision-rules/when-to-use-multi-agent.md` - gateway: `references/decision-rules/when-to-use-gateway.md` - cron or heartbeat: `references/decision-rules/when-to-use-cron-heartbeat.md` - worktree or sandbox isolation: `references/decision-rules/when-to-use-worktree-sandbox.md` - state and recovery: `references/state-artifacts.md` - eval pressure: `references/evaluation-checklist.md` Use project notes as subsystem pattern sources, not blueprints: - `references/project-claw-code.md` - `references/project-opencode.md` - `references/project-tradingagents.md` - `references/project-openclaw.md` - `references/project-openharness.md` - `references/project-hermes-agent.md` - `references/project-nanobot.md` - `references/project-learn-harness-engineering.md` ## Dynamic Questioning Rules - Do not run the references like a rigid questionnaire. - For each turn, restate the current understanding in 1 to 2 sentences. - Identify the single highest-leverage unresolved architecture branch. - Ask one question about that branch only. - Ask enough questions within that branch to lock the decision, not just to gesture at it. In most cases this means 2 to 4 turns inside the same branch before moving on. - Prefer option-led questions with 2 to 5 realistic architecture choices. - If one option is clearly safer or smaller, recommend it explicitly. - After the user chooses, ask one deeper follow-up based on that exact choice. - Before leaving a branch, confirm the choice, what it rules out, and the main residual risk inside that branch. - Skip any standard question whose answer is already clear or whose pressure is not present. - If the user's reply reveals a more important branch than the one you planned, switch to that branch. - If later evidence changes what owns the session lifecycle, autonomy surface, or highest-cost architecture risk, explicitly revise the current family read instead of quietly continuing with the old one. - Do not force coverage of `memory`, `tools`, `gateway`, `delegation`, or `recovery` unless the conversation reveals real pressure for them. - If the user brings an existing design, do not restart from blank-sheet discovery unless the current design is too vague to inspect. - In correction mode, identify what is already fixed, what is actually broken, and what smallest architectural move would repair it before exploring bigger redesigns. ## Coverage Rules Before finalizing, ensure the interview has either answered or explicitly deferred each of these: - agent job - user and usage scenario - operating surface such as local, channel, gateway, or shared core - runtime shape - action radius and side-effect boundary - the main architecture family - the highest-risk justified branches - session/state continuity if the design is more than one-shot - governance posture if the design can mutate state or act autonomously - what should not be built yet - how success and failure are recognized - if in correction mode, what existing decisions stay intact and what must change If a category is intentionally deferred, say so in the output. ## Method Borrowing Rules - Borrow methods from local harness projects by subsystem, not by whole-product imitation. - When a choice clearly matches a project pattern, name the project and the method being borrowed. - Prefer subsystem-level phrasing such as "borrow OpenHarness session-key snapshot restore" or "borrow OpenClaw subagent spawn boundary". - When rejecting a larger architecture, say which project shape it resembles and why it is not justified yet. - Prefer statements like "use OpenClaw-style inspectable state here" over "build it like OpenClaw." ## Interview Flow ### Mode Detection Choose the operating mode early. Use `design correction` when the user: - says the harness is already partly designed - says the current shape feels wrong, too heavy, too weak, or internally inconsistent - wants help finding architectural mistakes rather than starting from scratch Use `greenfield design` otherwise. Say the detected mode out loud when it materially changes the interview style. ### Phase 1: Core Intake Start with the must-know core: - what the agent is supposed to do - who uses it in what situation - how much action it is expected to take - what success and failure look like Default expectation: - cover all 4 core questions unless the user already answered some of them - ask 1 additional clarifying question if surface, autonomy, or failure shape is still fuzzy Do not ask branch questions yet unless the user already volunteered the branch pressure. ### Phase 1B: Current Design Intake for Correction Mode If operating in `design correction` mode, ask for the current harness shape before opening normal branches. Minimum correction intake: - what has already been decided - which subsystems already exist or are planned - what currently feels wrong - what symptom or failure triggered the redesign - what parts the user wants to keep if possible Then localize the likely wrong turn before reopening broader design space. ### Phase 2: Harness Family Detection After the first one or two answers, classify the current best-fit family and say it out loud. Typical family reads: - coding harness - always-on or gateway harness - providerized shared-core harness - role-specialized multi-agent pipeline - lightweight or teaching harness - mixed case with a primary family and one secondary pressure When the case is mixed, choose the primary family by asking: - which family owns the session lifecycle - which misclassification would create the costliest architecture error - which branch must be resolved first before the others make sense The family read must explain: - what kind of loop is likely - which branches are probably justified next - which tempting heavier families are not justified yet - why this family wins first-branch priority in the mixed case ### Family Reclassification If a later user answer reveals a stronger family than the current one, say the family read changed and explain why. Common triggers: - a coding assistant is later revealed to own channel routing, event reinjection, or always-on lifecycle - a lightweight assistant is later revealed to require durable workers, provider fallback, or shared-core reuse - a generic delegation idea is later revealed to be a stable role graph with typed staged artifacts and judge ownership When reclassifying: - name the old family read - name the new family read - state what new evidence forced the change - reopen branch priority using the new primary family ### Phase 3: Adaptive Branch Interview Activate only the branches justified by the current family and pressure: - coding branch when plan/build split, execution boundaries, permissions, verification loops, or task state are central - always-on branch when channels, events, gateway routing, background work, or session reinjection are central - memory branch when there is pressure from stable facts, cross-session continuity, shared memory, or personalization - governance branch when tool risk, approvals, audit, or policy boundaries are central - multi-agent branch when parent context pollution, specialist isolation, or concurrency pressure is central - providerized branch when backend replacement, shared core across surfaces, or fallback pressure is central - state/recovery branch when checkpoint, resume, freshness, crash handling, or durable runtime artifacts are central - capability-supply branch when tool surfaces, MCP, skills, plugins, hooks, or runtime control surfaces are part of the architecture question - background-automation branch when tasks, cron, heartbeat, unattended runs, or worker lifecycle are central - lightweight MVP branch when the real risk is overbuilding too early Mixed-family default ordering: - always-on plus coding: resolve `always-on` before `coding` - coding plus provider pressure: resolve `coding` before `providerized` - providerized plus always-on: resolve `providerized` first only when shared core or fallback rules determine the whole runtime shape; otherwise resolve `always-on` first - capability supply plus governance: resolve `capability supply` first when the real question is what should be loadable at all; resolve `governance` first when the load surface is already known and the real question is trust or approval posture - background automation plus always-on: resolve `always-on` first when routing and session ownership are still undefined; resolve `background automation` first when scheduled or worker execution is already fixed and unattended lifecycle is the main risk - state/recovery plus anything heavier: resolve `state/recovery` first when a bad resume or checkpoint story could invalidate the rest of the design - lightweight plus anything heavier: resolve `lightweight MVP` first unless the heavier branch is already forced by the requirements Ask only one branch question at a time. Stay on the branch until the design risk is resolved, then either remain there or switch to the next highest-risk branch. Default branch depth: - keep most active branches open for 2 to 4 turns - close a branch only after its key decision, boundary, and main deferred risk are explicit ### Phase 3B: Failure Localization for Correction Mode If in `design correction` mode, test whether the current design is wrong because of: - a wrong primary family read - a wrongly activated branch - a missing branch that should have been activated - a subsystem that is too heavy for the real pressure - a subsystem that is too weak for the real pressure - a broken invariant around session ownership, memory scope, governance, background work, or capability loading Then ask for the smallest correction that fixes the problem without rebuilding unaffected parts. ### Phase 4: Convergence Check Before synthesis, run a short coverage sweep: - Is there an uncovered memory pressure? - Is there an uncovered tool-surface or execution-boundary risk? - Is there an uncovered governance or permission risk? - Is there an uncovered gateway or session recovery risk? - Is there an uncovered state artifact, checkpoint, or recovery risk? - Is there an uncovered tool/MCP/skill/plugin supply-chain risk? - Is there an uncovered task, cron, or unattended execution risk? - Is there an uncovered delegation boundary? - Is there an uncovered provider or shared-core pressure? - Is there an uncovered evaluation or operator-visibility risk for the claimed autonomy level? - Is there a clearer smaller design that still works? Only ask about a leak if it is both uncovered and material. ### Phase 5: Rolling Synthesis After each resolved branch, provide a short synthesis: - confirmed so far - still open - current family read - likely next branch or likely final architecture direction - which obvious branch was checked and intentionally left closed - in correction mode, which current subsystem survives unchanged and which one is now suspected to be the wrong turn ### Phase 6: Final Output If the work was primarily a correction of an existing design, output: - `Interview Summary` using `references/templates/interview-summary.md` - `Harness Correction Report` using `references/templates/harness-correction-report.md` - `Pattern Provenance Matrix` using `references/templates/pattern-provenance-matrix.md` If the design is still simple or early-stage, output: - `Interview Summary` using `references/templates/interview-summary.md` - `Harness Brief` using `references/templates/quick-harness-brief.md` - `Pattern Provenance Matrix` using `references/templates/pattern-provenance-matrix.md` If the design is complex, risky, always-on, providerized, or multi-agent, output: - `Interview Summary` using `references/templates/interview-summary.md` - `Harness Architecture Spec` using `references/templates/harness-design-spec.md` - `Pattern Provenance Matrix` using `references/templates/pattern-provenance-matrix.md` - `Design Review Checklist` using `references/templates/design-review-checklist.md` In every final output, include: - the chosen harness direction - the detected operating mode - what is intentionally deferred - which project methods were borrowed - which larger project shapes were rejected for now - what should not be built yet - activated branches in the order they actually mattered - subsystem provenance, not just project names - in correction mode, which current decisions stay, which change, and why ## Decision Rules - Default to the smallest loop that explains the job. - Add memory only when something must survive restart or the user should not need to repeat stable facts. - Add multi-agent only when context pollution, specialist review, or parallel exploration creates real pressure. - Add a gateway only when multiple channels, background events, or always-on lifecycle needs create real pressure. - Add cron or heartbeat only when real time-based work exists. - Require state, recovery, and evaluation design before recommending long-running autonomy. - Prefer "what should not be built yet" as an explicit part of the answer. ## Output Rules - Prefer concrete architecture choices over generic advice. - Explain why each major subsystem exists. - Structure the output around activated branches and chosen subsystems, not a fixed section list. - Name the high-risk branches that were checked and why they stayed closed. - Distinguish proven project patterns from your own inference. - Name the borrowed project methods when they materially shaped the design. - Keep the visible flow adaptive, not checklist-shaped. - Use friendly language for guided design and sharper challenge when the user wants a harder review or the risk profile demands it.