Agent-Skills.md

Agent Skills: Two-Agent Harness System Setup

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.

UncategorizedID: ingpoc/SKILLS/two-agent-harness

Repository

ingpoc/SKILLS
ingpoc
5

Skill Files

Browse the full folder contents for two-agent-harness.

Download Skill

Loading file tree…

two-agent-harness/SKILL.md

Skill Metadata

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