two-agent-harness
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.
When & Why to Use This Skill
The Two-Agent Harness skill implements a sophisticated multi-agent architecture designed for complex, long-running software development projects. Based on the 'Effective Harnesses for Long-Running Agents' research, it establishes a robust framework that separates high-level project planning from incremental implementation. By deploying specialized Initializer and Coding agents alongside automated enforcement hooks, this skill ensures systematic progress tracking, state recovery, and high-quality code output while preventing context drift in large-scale engineering tasks.
Use Cases
- Complex Project Bootstrapping: Automatically breaking down a large-scale codebase requirement into over 200 manageable, trackable features using the specialized Initializer Agent.
- Structured Incremental Development: Executing feature-by-feature implementation via the Coding Agent to maintain focus and ensure quality assurance throughout long-duration development cycles.
- Automated Workflow Guardrails: Implementing pre-tool and post-tool hooks that prevent unauthorized direct edits to source files and enforce mandatory progress updates.
- Session State Recovery: Utilizing built-in session tracking and heartbeat mechanisms to detect abnormal exits and resume interrupted development workflows without losing context.
- Multi-Agent Delegation: Configuring Opus as a high-level orchestrator that delegates specific technical tasks to specialized sub-agents based on project needs.
| 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:
- Create agent definitions in
~/.claude/agents/ - Install enforcement hooks in
~/.claude/hooks/ - Add reference documentation to
~/.claude/REFRENCE/TWO-AGENT-HARNESS/ - Configure
~/.claude/CLAUDE.mdwith delegation instructions - 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 trackingsession-state.json- Session state for recovery detectionclaude-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 breakdownsession-state-template.json- Initial session stateinit-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 designreferences/initializer-agent-spec.md- Initializer agent detailsreferences/coding-agent-spec.md- Coding agent detailsreferences/hook-system.md- Hook configuration and behaviorreferences/feature-tracking-system.md- Progress tracking detailsreferences/session-workflow.md- Session lifecycle management