harness-factory

harness-factory

A Claude Code plugin that analyzes your project codebase and automatically generates a multi-agent team architecture — producing .claude/agents/, .claude/skills/, and CLAUDE.md tailored to your domain.

What it does

Run /generate-team (or /harness-factory:generate-team) in any project directory. The skill:

1. Audits the existing harness state (agents, skills, CLAUDE.md)
2. Analyzes the project's domain, tech stack, and task types
3. Designs an agent team architecture (pipeline, fan-out, expert pool, etc.)
4. Generates agent definition files in .claude/agents/
5. Generates skill files in .claude/skills/
6. Registers orchestration pointers in CLAUDE.md
7. Tests each agent/skill and iterates based on QA feedback

Installation

# 1. Clone the repository
git clone https://github.com/hyunhokim/harness-factory.git ~/.claude/plugins/harness-factory

# 2. Register the marketplace
claude plugin marketplace add ~/.claude/plugins/harness-factory

# 3. Install the plugin
claude plugin install harness-factory

Usage

The default flow is gated: a human reviews and approves a small design spec before any files are generated. This moves review cost from O(output) to O(design).

# 1. Design — interview, then write a reviewable spec and stop
/harness-factory:design <team>

# 2. Review specs/<team>/design.md, then approve (freezes a checksum)
scripts/approve <team>

# 3. Build — reads only the approved spec and generates the harness
/harness-factory:build <team>

design runs the interview (audit → domain analysis → architecture design) and writes specs/<team>/design.md with status: draft, then stops — no .claude/* files are written. After you edit and approve the spec, build reads only the approved spec and generates .claude/agents/, .claude/skills/, and CLAUDE.md. build hard-rejects if the spec is missing, not approved, or was tampered with after approval (checksum mismatch).

You don't have to open a terminal. When design finishes it presents the design in chat and offers Approve now / Revise (tell me changes) / Review the file myself. Picking Approve now runs the approve helper for you (freezing the checksum) so step 2 above becomes a single click; picking Revise lets you describe edits conversationally and Claude updates the spec, then re-presents it. The checksum gate is unchanged either way — approval is still an explicit act, and build still rejects a spec edited after approval.

One-shot escape hatch (--skip-design)

The legacy single-run flow is preserved as an explicit opt-out:

/generate-team --skip-design [project description]

With --skip-design, the original Phase 0–6 flow runs in one pass and writes .claude/* directly, with no design spec and no approval gate.

Running /generate-team without --skip-design does not silently generate anything — it explains the gated path above and routes you to /harness-factory:design <team>. Leave the project description empty to let the skill scan the current working directory automatically.

Practical Example: Generating a UI Component Team

Instead of abstract concepts, here is exactly what you type, what gets generated, and how you use it.

Scenario: Building a React "UI Component Development & QA" Team

Assume you are in your frontend project directory (my-react-app).

Step 1: Trigger the factory

You type the following in Claude Code:

/generate-team "Create an agent team that develops UI components and strictly checks design system consistency"

Step 2: What the factory does behind the scenes

harness-factory audits your current project state and analyzes your request, automatically generating the following files:

• Agent definitions (Who does the work):
  • .claude/agents/ui-developer.md
  • .claude/agents/design-qa.md
• Skill definitions (How they work):
  • .claude/skills/build-component/SKILL.md
  • .claude/skills/ui-orchestrator/SKILL.md (★ The Leader skill that coordinates the team)
• CLAUDE.md pointer:
  • Adds a rule to CLAUDE.md: "For UI tasks, use the ui-orchestrator skill."

Step 3: Daily Usage

The next day, you simply type:

"Create a dark-mode compatible login button component"

The generated Leader skill (ui-orchestrator) immediately kicks in:

1. The ui-developer agent writes the code.
2. The design-qa agent reviews it and sends feedback (e.g., "The dark mode color variable doesn't match the design system").
3. The ui-developer refines the code and submits the final output to you.

The real power: Safe Extensibility

A few days later, you realize you also need accessibility (a11y) checks. Instead of rebuilding everything, you run:

/generate-team "Add an accessibility QA agent to the existing UI team"