# Bzantium Meta Harness Create Harness

> meta-harness — Intelligent Harness Creator

- Skill: `tomevault-io/bzantium-meta-harness-create-harness` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/bzantium-meta-harness-create-harness`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/bzantium-meta-harness-create-harness/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/bzantium-meta-harness-create-harness

---


# meta-harness — Intelligent Harness Creator

Generates project-specific Claude Code harnesses by analyzing the codebase, selecting proven patterns from a curated library, and producing agents, skills, hooks, and rules — while auto-checking official features to avoid duplication.

## Workflow

### Phase 0: Deduplication Pre-check

Before any design work, establish what already exists:

1. **Read the built-in features reference** — Load `references/official-builtins.md` to know what Claude Code provides natively (50+ commands, 25 hook events, 5 subagent types, Agent Teams, etc.)

2. **Live update check** — Use WebSearch to query "Claude Code changelog latest features" to catch anything newer than the reference. If new built-in features are found that overlap with what you'd generate, note them.

3. **Check target project** — Look for existing `.claude/` directory contents:
   - `.claude/agents/` — existing agent definitions
   - `.claude/skills/` — existing skill definitions
   - `.claude/settings.json` — enabled plugins, hook configs
   - `CLAUDE.md` — existing project rules
   - `.mcp.json` — MCP server configs

4. **Compile exclusion list** — Everything found above is off-limits for generation. Present the list to the user.

If the user requests something that's already built-in, inform them and suggest the native feature instead.

### Phase 0.5: Clarification (if needed)

Before analysis, evaluate whether the user's request provides enough context. Use `AskUserQuestion` to gather missing information if:
- The project is empty/new and the user didn't describe what they're building
- The user's description is vague (e.g., "harness this project" with no context)
- Key decisions affect harness design (team size, deployment target, timeline)

Example questions to ask (use the system popup, NOT text):
- "What is the main purpose of this project?" (with options based on what you can infer)
- "What's the team size?" (Solo / Small 2-5 / Medium 6-15 / Large 15+)
- "What's the primary workflow?" (Feature development / Bug fixes / Research / Content creation)

**Skip this phase entirely if:**
- The project has substantial code (scout can infer everything)
- The user provided a detailed description with their request (e.g., `/create-harness FastAPI backend with PostgreSQL, 3-person team`)

### Phase 1: Project Analysis

Spawn the **scout** agent to analyze the target project:

```
Agent(
  name: "scout",
  prompt: "Analyze this project at {project_path}. Follow your investigation protocol and produce the structured analysis report.",
  model: "sonnet"
)
```

Review the scout's output. If the project is empty or has no code AND Phase 0.5 was skipped, use `AskUserQuestion` to ask what kind of project they're building before proceeding.

### Phase 2: Pattern Selection

Spawn a **pattern-selector** subagent to select patterns. This MUST be a subagent — do NOT select patterns in the main conversation, as conversation history will bias the selection.

```
Agent(
  prompt: "Select optimal patterns for this project.

PROJECT ANALYSIS:
{scout output from Phase 1}

DECISION MATRIX — match project traits to patterns:

| Project Trait | Recommended Patterns |
|---|---|
| Any project | Three-tier model routing, Progressive disclosure |
| Modifies files | Destructive command guard (safety hook) |
| Has tests | Verification loop |
| Multi-module | Fan-out parallel agents |
| API + Frontend | Three-layer separation (plan/execute/review) |
| Security-sensitive | READ-ONLY advisor enforcement, Security reviewer agent |
| Long autonomous tasks | Persistence loop (Ralph pattern) |
| Team collaboration | Proactive delegation |
| AI-generated code risk | Anti-slop cleanup |
| Cross-session work | Boulder state persistence |
| Protected directories | Edit freeze zones |
| Repeated workflows | Continuous learning |
| Quality-critical output (code, content, design) | Generator-Evaluator pattern |
| High-level spec → concrete implementation | Sprint contracts |
| Sessions > 1-2 hours | Context reset |

Read `references/pattern-library.md` for full pattern details.

RULES:
- Base your selection ONLY on the project analysis above
- Do NOT consider any topics or context outside the project analysis
- For each selected pattern, cite the specific project trait from the analysis that triggered it
- For each EXCLUDED pattern, provide a concrete reason tied to the project analysis — never use vague reasons like 'unnecessary' or 'overkill'
- Your selections must be defensible. If someone questions an exclusion, the reason you gave should already answer their question

Output format:

## Selected Patterns
| Pattern | Triggered By | Reason |
|---|---|---|
| {name} | {specific project trait from analysis} | {why this pattern fits} |

## Excluded Patterns
| Pattern | Reason for Exclusion |
|---|---|
| {name} | {concrete reason tied to project analysis — e.g., 'No test framework detected in analysis', not 'not needed'} |

## Scale Estimate
- Selected patterns: {N}
- Estimated agents: {N} (map patterns to agent roles — multiple patterns can share one agent)
- Estimated skills: {N}
- Estimated hooks: {N}
- Scale tier: {lightweight | standard | full | extended}",
  model: "sonnet"
)
```

Then spawn a **pattern-critic** subagent to review the selections before presenting to the user:

```
Agent(
  prompt: "Review this pattern selection for quality and consistency.

PROJECT ANALYSIS:
{scout output from Phase 1}

PROPOSED SELECTION:
{pattern-selector output}

Review each decision against the project analysis and check for:

1. FALSE POSITIVES — Selected patterns that the project doesn't actually need
   - Is there a concrete project trait supporting this, or is it assumed?
   - Would this pattern add complexity without proportional value at this project's scale?

2. FALSE NEGATIVES — Excluded patterns that should have been selected
   - Does the exclusion reason hold up? Check it against the actual project analysis
   - Is a pattern excluded as 'overkill' when a lightweight version would fit?

3. REASONING QUALITY — Are exclusion reasons specific and defensible?
   - Flag any vague reasons ('not needed', 'overkill', 'unnecessary')
   - Each exclusion must cite a concrete absence in the project analysis

4. FOCUS AREA CROSS-CHECK — Compare excluded patterns against the scout's Recommended Focus Areas
   - If a focus area implies a pattern that was excluded, flag as potential false negative
   - Example: scout says "credential security is a focus" but Security reviewer is excluded → flag

5. SCALE CHECK — Compare the Scale Estimate against the architect's scale guidelines
   - Solo small: 2-3 agents, 1-2 skills, 0-1 hooks
   - Solo medium: 3-5 agents, 2-3 skills, 1-2 hooks
   - Team medium: 4-6 agents, 3-5 skills, 2-3 hooks
   - Team large: 5-8 agents, 4-6 skills, 3-5 hooks
   - If estimated agents exceed the guideline, flag which patterns to merge or defer

6. CURRENT vs PLANNED — Check if any pattern was selected based on Planned State rather than Current State
   - Patterns triggered by planned-but-not-yet-existing traits should note this explicitly
   - For empty/greenfield projects: only select patterns for what exists NOW, defer the rest with triggers

Output format:

## Verdict
{APPROVE | REVISE}

## Issues Found (if REVISE)
| Pattern | Issue | Recommendation |
|---|---|---|
| {name} | {false positive/negative/vague reasoning} | {what to change} |

## Final Selection (if REVISE, provide corrected list)
| Pattern | Triggered By | Reason |
|---|---|---|
| {name} | {trait} | {reason} |

## Final Exclusions (if REVISE, provide corrected list)
| Pattern | Reason for Exclusion |
|---|---|
| {name} | {concrete reason} |",
  model: "sonnet"
)
```

If the critic returns REVISE, apply the corrections. If APPROVE, proceed.

Then **present the final selections to the user**:
- Show both selected AND excluded patterns with their full reasoning
- The excluded patterns table is as important as the selected one — users need to see WHY each was excluded

After presenting the summary, use `AskUserQuestion` to get approval. The user may want to add or remove patterns.

**When the user questions a selection or exclusion:**
- Do NOT immediately reverse the decision
- Re-examine the scout's project analysis for evidence
- If the evidence supports the original decision, explain why and stand by it
- Only change if the user provides NEW information not in the scout analysis (e.g., "we're adding tests next week", "this will be a team project soon")
- If changing, state what new information justified the change

### Phase 3: Architecture Design

Spawn the **architect** agent with the collected inputs:

```
Agent(
  name: "architect",
  prompt: "Design a harness for this project.

PROJECT ANALYSIS:
{scout output from Phase 1}

SELECTED PATTERNS:
{pattern selections from Phase 2}

DEDUP CONSTRAINTS (do NOT duplicate these):
{exclusion list from Phase 0}

Follow your design process and produce the harness specification.",
  model: "opus"
)
```

**Review the architecture** before proceeding:
- Every agent has an explicit model assignment
- No component duplicates a built-in feature
- Scale matches the project (not over-engineered)
- Skill descriptions are specific enough to trigger correctly

Present the architecture summary to the user, then use `AskUserQuestion` to get approval before generating files.

### Phase 4: File Generation

Generate all harness files based on the approved architecture. Read `references/templates.md` for file templates.

#### 4.1 Agent Definitions

For each agent in the architecture, create `{project}/.claude/agents/{name}.md`:

- YAML frontmatter: name, description, model
- Sections: Core Role, Work Principles, Tool Usage, Constraints
- READ-ONLY agents: explicitly list Write/Edit in disallowed or constrained tools
- Include specific, actionable instructions (not vague role descriptions)

#### 4.2 Skill Definitions

For each skill, create `{project}/.claude/skills/{name}/SKILL.md`:

- YAML frontmatter: name, description (write it "pushy" — aggressive trigger matching)
- Body under 500 lines
- Include: when to trigger, step-by-step workflow, output expectations

**References directory:** Create `{project}/.claude/skills/{name}/references/` when the skill needs supporting content that would bloat SKILL.md beyond 300 lines. Common reference types:
- **Domain knowledge** — API specs, schema definitions, protocol docs the skill needs to consult
- **Decision tables** — detailed criteria, scoring rubrics, or evaluation matrices
- **Templates** — output format templates, file scaffolds, boilerplate the skill generates
- **Examples** — sample inputs/outputs, worked examples for complex workflows
- **Checklists** — validation criteria, review checklists, QA procedures

SKILL.md references these with inline pointers: "For details on X, read `references/x.md`"
The skill body contains the workflow; references contain the knowledge.

#### 4.3 Hook Configuration

Add hooks to `{project}/.claude/settings.json`:

- Only generate hooks with clear, measurable value
- Safety hooks (PreToolUse): shell scripts that check commands
- Quality hooks (PostToolUse): formatting, validation
- **Gotcha Capture hook (Stop)**: Always include. Analyzes the session for harness-level issues and appends to `.forge/gotchas.md`. See `references/templates.md` for the template.
- Include the actual hook scripts if needed

#### 4.4 Project Rules (CLAUDE.md)

Generate `{project}/CLAUDE.md` with:

- Agent catalog table (name, role, model, when to use)
- Model routing rules
- Project-specific conventions
- Delegation rules (when to spawn which agent)
- Deferred Patterns table (from Phase 2 excluded patterns with trigger conditions)
- Do NOT include generic coding advice Claude already knows

#### 4.5 Generation Exclusions

Do NOT generate:
- README, CHANGELOG, or documentation about the harness itself
- Installation guides or setup instructions as separate files
- Meta-information about the generation process
- `.forge/` directory (created at runtime, not at generation time — but add it to the directory structure docs in CLAUDE.md)

### Phase 5: Validation

After generation, verify the harness:

1. **Structure** — All files in correct paths, valid YAML frontmatter
2. **Dedup** — Cross-check every component against Phase 0 exclusion list
3. **Consistency** — Agent names in skills match actual agent files
4. **Triggers** — For each skill, verify with test queries:
   - **Should trigger:** 3+ phrases that must activate the skill
   - **Should NOT trigger:** 2+ phrases that must NOT activate it
   - Fix descriptions that fail either test. For details → `references/skill-testing-guide.md`
5. **Models** — Every agent has a model assignment
6. **Scale** — Component count matches project complexity
7. **Depth** — No delegation chain deeper than 2 levels

Fix any issues found. Then summarize what was generated:

```
## Harness Summary

Generated {N} agents, {N} skills, {N} hooks, CLAUDE.md

### Agents
- {name} ({model}) — {role}

### Skills
- {name} — {trigger description}

### Hooks
- {event}: {purpose}

### Usage
Ready to use. Agents, skills, and hooks are now active.

### Deferred Patterns
| Pattern | Add When... |
|---|---|
| {pattern} | {concrete trigger condition} |
```

The **Deferred Patterns** table is required for every harness. For each excluded pattern, if it could become relevant as the project evolves, include the specific trigger condition. This gives the user a roadmap for harness evolution and makes `update-harness` more effective by providing predefined checkpoints.

## Anti-duplication Rules

These are NEVER generated because they're built-in:

- File search → built-in Glob tool
- Content search → built-in Grep tool
- Code exploration → built-in Explore subagent
- Plan creation → built-in /plan command + Plan subagent
- Task tracking → built-in TaskCreate/TaskUpdate tools
- Context management → built-in /compact, /context, /rewind
- Git operations → built-in Bash tool
- MCP connections → built-in /mcp command
- Agent teams → built-in TeamCreate/SendMessage (experimental)
- Code intelligence → built-in LSP tool

If a user requests any of these, point them to the native feature.

## References

- Pattern details → `references/pattern-library.md`
- Built-in features → `references/official-builtins.md`
- File templates → `references/templates.md`
- Skill testing → `references/skill-testing-guide.md`
- Team examples → `references/team-examples.md`
- QA patterns → `references/qa-patterns.md`

## Test Scenarios

### Normal: Solo web developer
1. User: "Create a harness for this Next.js project"
2. Dedup: no conflicts, no existing harness
3. Scout: Next.js + TypeScript, solo dev, medium complexity
4. Patterns: model routing, verification loop, destructive guard
5. Architect: 3 agents, 2 skills, 1 hook
6. Generate and validate

### Normal: Team API project
1. User: "Set up agents for our Python API"
2. Dedup: existing CLAUDE.md found → preserve, extend
3. Scout: FastAPI + PostgreSQL, 5 contributors, large
4. Patterns: three-layer separation, proactive delegation, security reviewer
5. Architect: 6 agents, 4 skills, 2 hooks
6. Generate and validate

### Conflict: Duplicate request
1. User: "Create a code search agent"
2. Dedup: Explore subagent is built-in
3. Response: "Claude Code already has a built-in Explore agent for code search. No need to generate one."

### Conflict: Existing harness
1. User: "Create a harness" (project already has agents/)
2. Dedup: finds 4 existing agents, 2 skills
3. Response: "Found existing harness with 4 agents and 2 skills. Want to extend it or redesign?"

---
> Source: [bzantium/meta-harness](https://github.com/bzantium/meta-harness) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-16 -->