new-harness

/new-harness — Instantiate a Domain Harness

You are creating a new domain-specific harness that inherits all 6 structural primitives from the meta-harness. The domain builder will build their domain-specific logic on top of these inherited guarantees.

Workflow

Phase 1: Discovery (13 Questions)

Ask these questions in order. The dependency chain matters — each answer informs the next.

If the user provided a domain name as an argument, check if a domain profile exists at ${CLAUDE_PLUGIN_ROOT}/templates/domain-profiles/{domain}.json. If it does, load it as defaults and let the user confirm or modify each answer.

Identity (Q1-4):

1. Purpose: "What is this system's purpose? What problem does it solve?" → Becomes the CLAUDE.md identity anchor. (L1 — immutable after creation)

2. Users: "Who will use this system? What is their role and expertise level?" → Informs tone, complexity, and authority hierarchy.

3. Absolute constraints: "What must this system NEVER do, regardless of context? What are the bright lines?" → Becomes identity.hardcoded_constraints in harness-config.json. These are added to the meta-harness hardcoded constraints, never replacing them. (L1 — immutable)

4. Persona: "What name, tone, and expertise should this system project?" → Becomes identity.persona. Name and expertise are L2 (confirm to change). Tone is L3 (freely adjustable).

Context (Q5-7):

5. Tier 1 context: "What information must this system always have loaded? (Keep it minimal — 25KB budget)" → Becomes context.tier1. Each item maps to a file in .claude/memory/topics/.

6. Tier 2 capabilities: "What tools, integrations, or data sources should be available on demand?" → Becomes context.tier2 and informs MCP configuration.

7. External systems: "What external systems does this connect to? (CRM, databases, APIs, etc.)" → Becomes context.external_systems and generates .mcp.json.

Honesty (Q8-9):

8. Domain risk: "How costly is a wrong answer in this domain? (low = creative/exploration, medium = business/research, high = medical/legal/financial)" → Sets honesty.domain_risk and calibrates honesty.confidence_threshold:

   • low → 0.5
   • medium → 0.7
   • high → 0.9

9. Abstention triggers: "In what specific situations should this system refuse to answer and say 'I don't know' instead?" → Becomes honesty.abstention_triggers. (L2)

Memory (Q10-11):

10. Persistence categories: "What types of information should this system remember between sessions?" → Becomes memory.topic_categories. Each becomes a directory in .claude/memory/topics/.

11. Usage frequency: "How often will this system be used? (daily/weekly/sporadic)" → Sets memory.usage_pattern and informs memory.consolidation_frequency.

Learning (Q12-13):

12. What to improve: "What should this system get better at over time?" → Becomes learning.learn. (L3)

13. What NEVER to optimize: "What must this system never learn to prioritize, even if users seem to prefer it?" → Becomes learning.never_learn. These are Goodhart's Law guards. (L2)

Phase 2: Context Architecture

Map the discovery answers to concrete files:

• Each Tier 1 item → create .claude/memory/topics/{item}.md (initialized empty, ready for content)
• Each Tier 2 item → register as a skill or MCP capability
• External systems → generate .mcp.json configuration
• Configure the SessionStart hook to load domain-specific Tier 1 files

Phase 3: Behavioral Calibration

Translate discovery answers into rule configurations:

• domain_risk → confidence threshold in honesty rules
• abstention_triggers → explicit triggers in honesty rules
• never_learn → Goodhart guards in learning rules
• These extend the inherited meta-harness rules, they do not replace them

Phase 4: Generation (Copy, Don't Reference)

Governing principle: Every file the generated harness needs to run and evolve itself must be copied into the harness directory. After generation, the harness must have zero runtime references to ${CLAUDE_PLUGIN_ROOT}. This is the Self-Containment rule (constitution principle 6): the plugin is a scaffold, not a runtime dependency. A user must be able to uninstall the plugin and have the harness continue to function.

Use $CLAUDE_PROJECT_DIR (not ${CLAUDE_PLUGIN_ROOT}) for any runtime path that needs to resolve to the harness root. Relative paths are also acceptable for files the generated skills and hooks read themselves.

Produce the complete domain harness directory. Operate on the plugin's source files as templates to read, and write the resulting files into the harness directory. The harness root is the current working directory unless the user has specified otherwise.

Step 4.1 — CLAUDE.md (identity anchor)

Read ${CLAUDE_PLUGIN_ROOT}/templates/claude-md.template.md. Fill in the template tokens from the discovery answers ({{HARNESS_NAME}}, {{PURPOSE}}, {{DOMAIN}}, {{USERS}}, {{PERSONA_*}}, {{HARDCODED_CONSTRAINTS}}, {{TIER1}}, {{TIER2}}, {{EXTERNAL_SYSTEMS}}, {{CONSOLIDATION_FREQUENCY}}, {{CREATED_DATE}}). Write the result to <harness>/CLAUDE.md.

Step 4.2 — harness-config.json

Generate the complete config from discovery answers, validated against the schema. Also copy the schema itself into the harness so future /evolve-harness and /health-check runs can validate against it without the plugin being present:

• Read: ${CLAUDE_PLUGIN_ROOT}/schemas/harness-config.schema.json

• Write: <harness>/schemas/harness-config.schema.json (create directory if needed)

• Read: ${CLAUDE_PLUGIN_ROOT}/schemas/mutability-tags.json

• Write: <harness>/schemas/mutability-tags.json

Record meta.created as today's date in absolute form. Record meta.plugin_version as the version string from ${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json so the harness knows which plugin version generated it (important for patch applicability).

Step 4.3 — Rule files (.claude/rules/)

Copy every file in ${CLAUDE_PLUGIN_ROOT}/.claude/rules/ into <harness>/.claude/rules/. As of 2026-04-13 this must include:

• identity.md
• honesty.md
• context-budget.md
• wip-ledger.md
• observability.md
• learning.md

Copy, do not reference. Do not write imports that resolve to the plugin. After this step, a grep for CLAUDE_PLUGIN_ROOT across <harness>/.claude/rules/ must return zero results.

If the plugin has added new rule files since this skill was last updated, copy them as well and warn the user that the new-harness skill's explicit list is out of date and should be refreshed. Do not silently skip files you do not recognize.

Step 4.4 — Hook scripts and hooks.json

This is the critical runtime-decoupling step. Copy every script in ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/ into <harness>/hooks/scripts/:

• session-start.sh
• pre-tool-check.sh
• post-tool-log.sh
• pre-compact-save.sh
• on-stop-stage.sh
• session-end-metrics.sh
• on-tool-failure.sh

Ensure each copied script is executable (chmod +x).

Then copy ${CLAUDE_PLUGIN_ROOT}/templates/hooks.template.json verbatim to <harness>/hooks/hooks.json. This template is pre-rewritten — every "command" field already uses "$CLAUDE_PROJECT_DIR"/hooks/scripts/..., so no path rewriting is required. Strip the leading _comment field if present (it documents the template's purpose; the harness's hooks.json should not carry it).

Do not read ${CLAUDE_PLUGIN_ROOT}/hooks/hooks.json for this step. That file uses ${CLAUDE_PLUGIN_ROOT} because it is the plugin's own hook configuration; copying it would silently couple the generated harness to the plugin. Use templates/hooks.template.json exclusively.

After writing, grep the written hooks.json for CLAUDE_PLUGIN_ROOT. If the grep matches, the template was wrong or the wrong source was copied — stop, report, and do not continue to the next step.

Step 4.5 — Operational skills (.claude/commands/)

Copy the four operational skills from the plugin into the harness as project-local Claude Code commands. These live at .claude/commands/ (Claude Code's native location for project-local slash commands), which means they become /health-check, /consolidate, /evolve-harness, /context-status inside the harness — unnamespaced and plugin-independent.

For each skill in this list:

• health-check → <harness>/.claude/commands/health-check.md
• consolidate → <harness>/.claude/commands/consolidate.md
• evolve-harness → <harness>/.claude/commands/evolve-harness.md
• context-status → <harness>/.claude/commands/context-status.md

Read ${CLAUDE_PLUGIN_ROOT}/skills/<skill>/SKILL.md and write its content to the destination. The YAML frontmatter may need adjustment because project-local commands use a slightly different schema than plugin skills — at minimum, remove any context: fork directive that is plugin-specific. Preserve description, argument-hint, allowed-tools, and the entire body.

Rewrite any remaining plugin references in the copied skills. Specifically, evolve-harness reads the mutability schema. Its original text says "Read the mutability classification from ${CLAUDE_PLUGIN_ROOT}/schemas/mutability-tags.json." When you copy it into the harness, rewrite that line to "Read the mutability classification from $CLAUDE_PROJECT_DIR/schemas/mutability-tags.json." Apply the same rewrite rule to every occurrence of ${CLAUDE_PLUGIN_ROOT} in any copied skill.

After writing each file, grep it for CLAUDE_PLUGIN_ROOT. Any remaining reference is a bug — stop, report, and do not continue.

Step 4.6 — Memory initialization

Copy ${CLAUDE_PLUGIN_ROOT}/templates/memory-init/ into <harness>/.claude/memory/. For each item in memory.topic_categories from discovery, create an empty topic directory at <harness>/.claude/memory/topics/<category>/.

Step 4.7 — .mcp.json (if external systems were declared)

If the discovery answers include external systems, generate <harness>/.mcp.json with the appropriate MCP configurations. Do not pre-configure MCP servers the user did not declare.

Step 4.8 — settings.json (permission patterns)

Generate <harness>/.claude/settings.json with allow/deny patterns based on domain risk level and declared constraints (see "Autonomy-Permission Connection" below).

Step 4.9 — .claude/memory/patches-applied.md

Create an empty patches log so that future patch applications have a canonical location to write to. Initialize it with a header:

# Patches Applied

This file records which meta-harness patches have been applied to this harness. Patches are published in the meta-harness plugin at `primitives/patches/` and are never auto-applied — each entry below represents an explicit decision by the harness operator.

Phase 5: Validation

Run /health-check on the generated harness. All checks must pass, including the self-containment checks:

• No runtime plugin references: grep for CLAUDE_PLUGIN_ROOT across the harness's hooks/, .claude/rules/, .claude/commands/, and schemas/ directories. Must return zero results.
• Every file the generated hooks.json references exists inside the harness. Parse hooks.json, resolve each command path against $CLAUDE_PROJECT_DIR = <harness>, and confirm the script is present and executable.
• Schemas are present: <harness>/schemas/harness-config.schema.json and <harness>/schemas/mutability-tags.json both exist.
• Operational commands are present: all four files under <harness>/.claude/commands/.

If any check fails, fix the issue and re-run. Do not deliver a harness that fails validation.

Output the harness-config.json path, the absolute path of the harness root, and a summary of what was generated (file counts per category).

Autonomy-Permission Connection

Based on the domain risk level and declared constraints, generate appropriate settings.json allow/deny patterns:

• High risk domains: Default deny for destructive operations, require confirmation for external communications
• Medium risk domains: Allow standard operations, confirm external system writes
• Low risk domains: Allow most operations, confirm only destructive actions

Error Handling

• If a domain profile template is not found at the expected path, proceed with empty defaults and inform the user
• If the user provides incomplete answers to discovery questions, do not guess — ask again
• If harness-config.json generation fails validation against the schema, report which fields are invalid and re-prompt
• If template files are missing from ${CLAUDE_PLUGIN_ROOT}/templates/, report the missing files and suggest reinstalling the plugin
• If any copy step (Phase 4.1–4.9) fails partway through, do not continue to Phase 5. Report what was copied, what was not, and leave the partial harness in place so the user can inspect it. Never pretend a partial harness is complete.
• If the post-copy grep for CLAUDE_PLUGIN_ROOT finds a match in any copied file, treat this as a generation failure: report the file and the offending line, and stop. The harness is not self-contained and must not be delivered in that state.
• If /health-check fails after generation, show the failures and attempt to fix them before delivering. If a self-containment check fails, do not ship — the harness has an unresolved runtime dependency on the plugin.