Claude Code Plugins

Community-maintained marketplace

Feedback

two-agent-harness

@ingpoc/SKILLS
4
0

This skill sets up a complete two-agent development system based on the "Effective Harnesses for Long-Running Agents" research. It creates initializer-agent (for project planning) and coding-agent (for incremental implementation), along with enforcement hooks and progress tracking infrastructure. Use when users ask to "set up two-agent system", "install agent harness", "configure Opus delegation", or want to implement the two-agent architecture pattern.

Install Skill

1Download skill
2Enable skills in Claude

Open claude.ai/settings/capabilities and find the "Skills" section

3Upload to Claude

Click "Upload skill" and select the downloaded ZIP file

Note: Please verify skill by going through its instructions before using it.

SKILL.md

name two-agent-harness
description This skill sets up a complete two-agent development system based on the "Effective Harnesses for Long-Running Agents" research. It creates initializer-agent (for project planning) and coding-agent (for incremental implementation), along with enforcement hooks and progress tracking infrastructure. Use when users ask to "set up two-agent system", "install agent harness", "configure Opus delegation", or want to implement the two-agent architecture pattern.

Two-Agent Harness System Setup

This skill installs a complete two-agent development architecture that separates planning from implementation. Based on the research paper "Effective Harnesses for Long-Running Agents", it enables Claude Code to handle complex, multi-session projects with proper progress tracking and state recovery.

System Overview

The two-agent harness creates a workflow where:

  • Opus (you) orchestrates and delegates - never implements directly
  • Initializer Agent (sonnet) breaks down projects into 200+ trackable features
  • Coding Agent (sonnet) implements features one at a time with quality assurance

Auto-Setup Process

To set up the complete two-agent system, execute the setup script:

bash ~/.claude/skills/two-agent-harness/scripts/setup-two-agent-system.sh

This script will automatically:

  1. Create agent definitions in ~/.claude/agents/
  2. Install enforcement hooks in ~/.claude/hooks/
  3. Add reference documentation to ~/.claude/REFRENCE/TWO-AGENT-HARNESS/
  4. Configure ~/.claude/CLAUDE.md with delegation instructions
  5. Validate the installation

What Gets Installed

Agents (~/.claude/agents/)

Agent Model Purpose
initializer-agent sonnet Breaks down complex tasks into feature-list.json with 200+ features
coding-agent sonnet Implements features systematically, one at a time

Hooks (~/.claude/hooks/)

Hook Event Action
pre-tool-guard.sh PreToolUse Blocks Opus from editing src/ files, updates heartbeat
post-tool-guard.sh PostToolUse Reminds about progress updates after code changes
session-progress-check.sh SessionStart Detects pending features and abnormal exits
verify-coding-agent.sh SubagentStop Verifies coding-agent updated progress files
session-end.sh SessionEnd Marks session complete for recovery detection

Reference Documentation (~/.claude/REFRENCE/TWO-AGENT-HARNESS/)

Nine comprehensive guides covering:

  • Framework overview and philosophy
  • Agent specifications
  • Feature tracking system
  • Hook system
  • Git integration
  • Session workflow
  • Testing strategy
  • File structure

Post-Installation Usage

Starting a New Project

User: "Initialize this as a new project with comprehensive feature breakdown"
Opus: [Invokes initializer-agent via Task tool]
Result: Creates feature-list.json with 200+ features, init.sh, and progress tracking

Implementing Features

User: "Implement the next feature"
Opus: [Invokes coding-agent via Task tool]
Result: Implements one feature, updates progress, commits changes

Delegation Rules

Situation Agent to Use
New project, complex breakdown initializer-agent
Implement feature from feature-list coding-agent
Need codebase understanding Explore (built-in)
Quick fix (<5 min), explicit request Do directly (say "quick fix" or "direct edit")

Bypass Keywords

When you need to bypass the enforcement hooks, include these keywords in your prompt:

  • "quick fix" - Single line change
  • "direct edit" - User explicitly requested direct editing
  • "no progress" - No feature-list.json exists yet

Project Progress Files

When a project is initialized, these files are created in .claude/progress/:

  • feature-list.json - Comprehensive feature breakdown with status tracking
  • session-state.json - Session state for recovery detection
  • claude-progress.txt - Human-readable progress log

Templates

The skill includes templates for new projects in assets/templates/:

  • feature-list-template.json - Starting point for feature breakdown
  • session-state-template.json - Initial session state
  • init-template.sh - Environment setup script

Troubleshooting

Agents Not Appearing in Task Tool

Verify agents are in ~/.claude/agents/:

ls -la ~/.claude/agents/

Hooks Not Triggering

Check hook configuration in ~/.claude/settings.json and verify hooks are executable:

chmod +x ~/.claude/hooks/*.sh

Recovery After Crash

If a session ended abnormally, the session-progress-check.sh hook will detect it on next startup and prompt you to invoke coding-agent for recovery.

Reference Documentation

For detailed information, see the reference files:

  • references/two-agent-framework-overview.md - Full system design
  • references/initializer-agent-spec.md - Initializer agent details
  • references/coding-agent-spec.md - Coding agent details
  • references/hook-system.md - Hook configuration and behavior
  • references/feature-tracking-system.md - Progress tracking details
  • references/session-workflow.md - Session lifecycle management