Harness - Spec-Driven Parallel Development

You are a team lead running a test-driven harness. Your ONE goal: make all tests pass.

PROGRESS 파일: .harness/PROGRESS-{feature}.md — 다중 하네스 동시 실행을 지원한다.

Phase Overview

Phase 0: Spec Intake → Analyze spec, extract feature name, create .harness/PROGRESS-{feature}.md
Phase 1: Test Suite  → Lead writes ALL tests (only phase lead writes code)
Phase 2: Team Setup  → Spawn agent team, assign tasks
Phase 3: Harness Loop → Test → Analyze → Decide → Track → Commit → Repeat
Phase 4: Convergence → 100% pass confirmed, lessons learned, cleanup

Phase 0: Spec Intake

1. Ask user for spec location
2. Check ~/.claude/skills/harness/LESSONS_LEARNED.md for prior lessons
3. Read spec, analyze project structure (stack, conventions, test runner)
4. Extract feature name: spec/PRD 제목 → kebab-case 변환 → 사용자 확인
   • 예: "사용자 인증 시스템 MVP" → auth-system-mvp
   • "하네스 이름: auth-system-mvp — 맞나요?"
   • 영문/숫자/하이픈만 허용
5. .harness/ 디렉토리 준비
   • 없으면 mkdir .harness
   • .gitignore에 .harness/ 엔트리 없으면 추가
6. 충돌 체크: .harness/PROGRESS-{feature}.md가 이미 존재하면 사용자에게 경고
   • 덮어쓸지 / 이름 변경할지 확인
7. Define module boundaries and file ownership map
8. Create .harness/PROGRESS-{feature}.md (see references/progress-template.md)
9. Confirm module breakdown with user

Phase 1: Test Suite Generation

Lead writes tests directly. For each module:

• Happy path, edge cases, error cases, integration points
• Tests verify general correctness, NOT specific outputs
• Run all tests → confirm ALL FAIL
• Commit: test: initial test suite (0/N passing)

For test reporting format and execution tiers, see references/phase-details.md.

Phase 2: Team Setup

Inform user: "Phase 2 시작: delegate mode (Shift+Tab)로 전환해주세요."

Spawn team: researcher, impl-1~N (max 4), tester, reviewer. Each implementer gets file ownership, target tests, and the PROGRESS file path (.harness/PROGRESS-{feature}.md).

For team creation prompts and spawn context, see references/phase-details.md.

Phase 3: Harness Loop

Core loop — repeat until all tests pass or max 10 iterations.

Step 1: Test      → Message tester (quick/smoke/full tier)
Step 2: Analyze   → Compare with previous .harness/PROGRESS-{feature}.md
Step 3: Decide    → Regression? Stalled? Complete? Act accordingly
Step 4: Track     → Update .harness/PROGRESS-{feature}.md (EVERY iteration)
Step 5: Commit    → Implementers + lead commit
Step 6: Guard     → Pause at 10 iterations, ask user

Decision Quick Reference

Condition	Action
Regression	STOP new work → fix immediately
Stalled 2+ rounds	Researcher investigates → new tasks
Wrong test	Confirm with user → adjust with approval
Module complete	Reviewer checks → reassign implementer

Parallelism by Pass Rate

• 0-80%: Max parallelism by module
• 80-95%: Cluster by dependency graph
• 95-100%: Researcher first, then single implementer

For full loop details, mistake recording protocol, and sub-agent guidelines, see references/phase-details.md.

Phase 4: Convergence

1. Full test suite → confirm 100%
2. Update .harness/PROGRESS-{feature}.md status to COMPLETE
3. Extract lessons → append to LESSONS_LEARNED.md
4. Delete .harness/PROGRESS-{feature}.md (lessons already extracted)
5. If .harness/ is empty, remove the directory
6. Shutdown team, final report

문서화 (Phase 4 완료 후 자동 실행)

작업 완료 시 auto-documenter를 호출하여 프로젝트 문서를 업데이트한다.

Lead Rules Summary

See references/lead-rules.md for complete 19 rules. Key rules:

• NEVER implement code yourself (except Phase 1)
• Regression = highest priority
• File ownership is sacred
• No hard-coding, no over-engineering
• Record every mistake with prevention rule

Completion

Phase 4 완료: 전체 테스트 100% 통과 + .harness/PROGRESS-{feature}.md 삭제 + LESSONS_LEARNED.md 업데이트.

Troubleshooting

Tests pass but implementation is wrong: Tests may be too loose. Tighten assertions to verify correctness, not just absence of errors. Agent team member is stuck: Reassign the task or spawn a researcher to investigate. Never wait more than 2 iterations on a stalled task. Regression after a fix: Immediately stop all other work. The implementer who caused the regression owns the fix. Update .harness/PROGRESS-{feature}.md with the regression event. PROGRESS file conflict: If .harness/PROGRESS-{feature}.md already exists at Phase 0, another harness may be running with the same name. Ask user to rename or confirm overwrite.