@walwal-harness/cli 4.0.0-alpha.9 → 4.0.0-beta.2

package/README.md

@@ -1,4 +1,4 @@
-# walwal-harness
+# @walwal-harness/cli
 
 **AI 에이전트를 위한 프로덕션 하네스 엔지니어링 프레임워크**
 
@@ -9,332 +9,342 @@
 
 ---
 
+## 두 가지 모드
+
+| 모드 | 설명 | 실행 방법 |
+|------|------|----------|
+| **Classic (v3)** | 순차 실행 — Planner → Generator → Evaluator 1세션씩 | `하네스 엔지니어링 시작` |
+| **Agent Teams (v4)** | 병렬 실행 — 3 Team이 Feature 단위 Gen→Eval 루프 동시 실행 | `/harness-team` 또는 `npx walwal-harness v4` |
+
+---
+
 ## 설치
 
+### 첫 설치
+
 ```bash
+cd your-project
 npm install @walwal-harness/cli
 ```
 
-`postinstall`이 자동으로 프로젝트 루트에 설치합니다:
-
-1. `.harness/` 디렉토리 스캐폴딩 (actions, archive, gotchas, config)
-2. `.claude/skills/` 에 에이전트 스킬 설치 (9개)
-3. `scripts/` 에 오케스트레이션 헬퍼 스크립트 설치
-4. `SessionStart` 훅 등록 (세션 시작 시 진행 상태 표시)
-5. `UserPromptSubmit` 훅 등록 (모든 프롬프트를 Dispatcher 경유 자동 라우팅)
-6. `AGENTS.md` 생성 + `CLAUDE.md` 심볼릭 링크
-7. 기존 프로젝트면 구조 스캔 → IA-MAP 자동 생성
+`postinstall`이 자동으로:
+1. `.harness/` 디렉토리 스캐폴딩
+2. `.claude/skills/` 에 에이전트 스킬 설치 (8개)
+3. `scripts/` 에 오케스트레이션 스크립트 설치
+4. SessionStart / UserPromptSubmit 훅 등록
+5. `AGENTS.md` + `CLAUDE.md` 심볼릭 링크 생성
 
 > **중요:** 설치 후 Claude Code 세션을 **재시작**해야 skills가 인식됩니다.
-> `/exit` → 디렉터리 재진입이 필요합니다.
 
-### CLI 명령
+### 기존 설치자 업데이트
 
 ```bash
-npx walwal-harness           # 초기화 (postinstall과 동일)
-npx walwal-harness --force   # 강제 재초기화 (기존 파일 덮어쓰기)
-npx walwal-harness --help    # 도움말
-```
+# latest (v3 안정판)
+npm update @walwal-harness/cli
 
-### 초기화에서 일어나는 일
+# v4 alpha (Agent Teams)
+npm install @walwal-harness/cli@next
 
+# 스크립트 동기화 (코어 스크립트 자동 덮어쓰기)
+npx walwal-harness
 ```
-your-project/
-├── AGENTS.md                       # 에이전트 공통 컨텍스트 (Planner 관리)
-├── CLAUDE.md → AGENTS.md           # 심볼릭 링크
-├── scripts/
-│   ├── harness-next.sh             # 세션 오케스트레이터
-│   ├── harness-session-start.sh    # SessionStart 훅
-│   ├── harness-user-prompt-submit.sh  # UserPromptSubmit 훅 (auto-routing)
-│   ├── scan-project.sh             # 프로젝트 구조 스캔
-│   ├── init-agents-md.sh           # AGENTS.md 생성/리빌드
-│   └── lib/
-│       └── harness-render-progress.sh  # 프로그레스 바 렌더러
-├── .harness/
-│   ├── config.json                 # 하네스 설정
-│   ├── HARNESS.md                  # 하네스 상세 가이드
-│   ├── progress.json               # 세션 간 상태 (기계 판독)
-│   ├── gotchas/                    # 에이전트별 실수 기록
-│   ├── actions/                    # 활성 스프린트 문서
-│   └── archive/                    # 완료 스프린트 보관 (불변)
-└── .claude/
-    ├── settings.json               # 훅 등록 (SessionStart + UserPromptSubmit)
-    └── skills/                     # Claude Code 스킬 (9개)
-        ├── harness-dispatcher/
-        ├── harness-brainstorming/
-        ├── harness-planner/
-        ├── harness-generator-backend/
-        ├── harness-generator-frontend/
-        ├── harness-generator-frontend-flutter/
-        ├── harness-evaluator-functional/
-        ├── harness-evaluator-functional-flutter/
-        └── harness-evaluator-visual/
+
+### CLI 명령어
+
+```bash
+npx walwal-harness            # 초기화 / 스크립트 업데이트
+npx walwal-harness --force    # 강제 재초기화
+npx walwal-harness studio     # Harness Studio v3 (tmux 5-pane)
+npx walwal-harness v4         # Harness Studio v4 (Agent Teams, tmux 6-pane)
+npx walwal-harness --help     # 도움말
 ```
 
 ---
 
-## Quick Start
+## Quick Start — Classic Mode (v3)
 
 ### 1. 설치 + 재시작
 
 ```bash
 cd your-project
 npm install @walwal-harness/cli
-# Claude Code 세션 재시작 (/exit → 재진입)
+# Claude Code 재시작 (/exit → 재진입)
 ```
 
 ### 2. 하네스 시작
 
-Claude Code에서 아무 요청이나 입력하면 **UserPromptSubmit 훅이 자동으로 Dispatcher를 호출**합니다. 또는 명시적으로:
-
 ```
-> 하네스 엔지니어링 시작
+❯ 하네스 엔지니어링 시작
 ```
 
-### 3. Dispatcher가 분류
+또는 Claude Code에서 아무 요청 → UserPromptSubmit 훅이 자동으로 Dispatcher를 호출합니다.
+
+### 3. 파이프라인 자동 선택
+
+Dispatcher가 요청을 분석하여 파이프라인을 결정합니다:
 
 ```
-사용자 입력
-    │
-    ├─ 신규 기능/제품 요청 → 파이프라인 선택 (FULLSTACK / FE-ONLY / BE-ONLY)
-    │   └─ "브레인스토밍 필요합니까?" → Y: Brainstormer → Planner
-    │                                  → N: Planner 직행
-    ├─ 실수 지적 → Gotcha 기록 → 해당 에이전트 재작업
-    ├─ 특정 에이전트 명령 → 해당 에이전트 직접 라우팅
-    └─ 메타/인사 → 일반 응답
+FULLSTACK  : Planner → Gen-BE → Gen-FE → Eval-Func → Eval-Visual
+FE-ONLY    : Planner(light) → Gen-FE → Eval-Func → Eval-Visual
+BE-ONLY    : Planner → Gen-BE → Eval-Func(API-only)
 ```
 
-### 4. 에이전트 순차 실행
+### 4. 순차 실행
 
-각 에이전트가 완료되면 다음 프롬프트를 제안합니다:
+각 에이전트가 독립 Claude Code 세션에서 실행됩니다:
 
 ```
-✓ Dispatcher 완료. bash scripts/harness-next.sh 실행하여 다음 단계 확인.
+❯ /harness-planner           # Plan 작성
+❯ /harness-generator-frontend  # 코드 생성
+❯ /harness-evaluator-functional  # E2E 테스트
 ```
 
-`bash scripts/harness-next.sh` 를 실행하면 프로그레스 바 + 다음 에이전트 안내:
+에이전트가 완료되면 **새 세션**을 시작하면 자동으로 다음 에이전트를 안내합니다.
 
-```
-═══ Sprint 1 / FULLSTACK ═══════════════════
+### 5. Eval FAIL → 자동 재작업
 
-Agents: planner✓ → generator-backend✓ → [generator-frontend] → evaluator-functional → evaluator-visual
+Evaluator FAIL 시 → 실패 원인 + 피드백과 함께 Generator로 자동 리라우팅 (최대 10회).
 
-/harness-generator-frontend 를 실행하세요.
-```
+---
 
-### 5. 반복
+## Quick Start — Agent Teams (v4)
 
-FAIL이 발생하면 Evaluator가 원인을 분석하고 해당 Generator로 자동 재작업 라우팅 (최대 10회). PASS하면 다음 Evaluator로 진행. 모든 Evaluator를 통과하면 스프린트 완료 → 아카이브.
+Claude Code의 **네이티브 Agent Teams 기능**을 사용하여 3개 Teammate가 Feature 단위로 Gen→Eval을 병렬 실행합니다.
 
----
+```
+기존 (v3): Planner → Gen(F-001~028 전부) → Eval(전부)
+v4:        Planner → 3 Teammates 병렬, 각 Feature 단위 Gen→Eval
+```
 
-## 파이프라인
+### 1. Agent Teams 활성화
 
-Dispatcher가 사용자 요청을 분석하여 3가지 파이프라인 중 하나를 자동 선택합니다:
+```bash
+npm install @walwal-harness/cli@next
+npx walwal-harness v4    # settings.json에 env var 설정 + queue 초기화
+```
 
-### FULLSTACK (신규 프로젝트)
+또는 수동으로:
 
+```json
+// .claude/settings.json
+{
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  }
+}
 ```
-Brainstormer? → Planner → Generator-BE → Generator-FE → Evaluator-Func → Evaluator-Visual
-                                                              │ FAIL
-                                                              └──→ 재작업 (max 10회)
+
+### 2. Claude Code 시작
+
+```bash
+claude                           # 기본 모드
+claude --teammate-mode tmux      # tmux split pane 모드 (권장)
 ```
 
-### FE-ONLY (기존 API에 프론트엔드 연동)
+### 3. Planner 실행
 
 ```
-Brainstormer? → Planner(light) → Generator-FE → Evaluator-Func → Evaluator-Visual
-                    └─ OpenAPI → api-contract.json 자동 변환
+❯ 하네스 엔지니어링 시작
+# Dispatcher → Planner → feature-list.json 생성
 ```
 
-### BE-ONLY (기존 서버에 백엔드 기능 추가)
+### 4. Teams 가동
 
 ```
-Brainstormer? → Planner → Generator-BE → Evaluator-Func(API-only)
+❯ /harness-team-action
 ```
 
-> `Brainstormer?` = Dispatcher가 사용자에게 확인 후 조건부 실행. 명확한 PRD/OpenAPI가 있으면 생략 가능.
+이 명령은:
+1. `feature-list.json` → `feature-queue.json` 초기화 (dependency-aware topological sort)
+2. 3개 Teammate 생성 (Claude의 네이티브 Agent Teams)
+3. 각 Teammate가 Queue에서 Feature를 가져와 Gen→Eval 자율 실행
 
-### Flutter 프로젝트 자동 감지 (Web / Mobile / Desktop)
+### 5. 모니터링 & 제어
 
-`pubspec.yaml` + `flutter:` 키가 감지되면 FE 에이전트가 **자동 치환**됩니다. **Flutter Web** 은 컴파일 결과가 HTML+JS+CSS 이므로 React 와 동일하게 Playwright 기반 evaluator 를 그대로 사용하고, **Mobile/Desktop** 만 정적 분석 evaluator 로 교체됩니다.
+| 명령 | 동작 |
+|------|------|
+| `/harness-team-action` | Queue 초기화 + 3 Teammates 생성 |
+| `/harness-team-stop` | 모든 Teammates 해산 |
+| `bash scripts/harness-queue-manager.sh status .` | Queue 상태 확인 |
+| `bash scripts/harness-queue-manager.sh requeue F-XXX .` | 실패 Feature 재큐 |
 
-| fe_stack | fe_target | Generator | Eval-Functional | Eval-Visual |
-|----------|-----------|-----------|----------------|-------------|
-| react | (n/a) | `generator-frontend` | `evaluator-functional` (Playwright) | `evaluator-visual` |
-| **flutter** | **web** | `generator-frontend-flutter` | **`evaluator-functional`** (Playwright!) | **`evaluator-visual`** (Playwright!) |
-| **flutter** | mobile | `generator-frontend-flutter` | `evaluator-functional-flutter` (flutter analyze/test) | **SKIP** |
-| **flutter** | desktop | `generator-frontend-flutter` | `evaluator-functional-flutter` (flutter analyze/test) | **SKIP** |
+**tmux 모드에서 Teammate 간 전환:**
+- `Shift+Down` — Teammate 순회
+- `Ctrl+T` — 태스크 리스트 보기
 
-**감지 방식**: `scan-project.sh` 가 Flutter 프로젝트의 `web/index.html`, `android/`, `ios/`, `macos/`, `windows/`, `linux/` 디렉터리 존재 여부로 `fe_target` 을 자동 판정. 멀티 타겟 또는 모호한 경우 Planner 가 사용자에게 확인합니다. 치환은 `pipeline.json.fe_stack + fe_target` 조합에 의해 `harness-next.sh` 가 자동 처리합니다.
+### 6. 작동 원리
 
----
+```
+Feature Queue (dependency-aware topological sort)
+  Ready:   [F-002, F-003, F-007]  ← depends_on 충족된 것만
+  Blocked: [F-004, F-005, ...]    ← 선행 Feature 미완료
 
-## 에이전트
+Teammate 1: F-002 → 코드 생성 → tsc/eslint 검증 → AC 평가
+  PASS → queue에서 pass 처리 → dependents unblock → 다음 Feature
+  FAIL → 최대 3회 재시도 → 실패 시 fail 처리
+
+Teammate 2: F-003 → (동일 루프)
+Teammate 3: F-007 → (동일 루프)
+```
 
-### 9개 에이전트 (조건부 포함)
+- 각 Teammate는 Claude Code의 **독립 컨텍스트** (1M token)
+- `SendMessage`로 Teammate 간 직접 소통 (API 변경, 실패 알림 등)
+- Lead(사용자 세션)는 오케스트레이터 — 개입, 리뷰, gotcha 등록
 
-| 에이전트 | 역할 | 호출 조건 |
-|----------|------|----------|
-| **Dispatcher** | 파이프라인 선택 + Gotcha 관리 + 라우팅 | 항상 (auto-routing 훅) |
-| **Brainstormer** | 러프한 요구사항을 대화형으로 구체화 | Dispatcher가 사용자에게 확인 후 |
-| **Planner** | 제품 사양 + API 계약서 + 서비스 분할 | 파이프라인 시작 시 |
-| **Generator-Backend** | NestJS MSA 구현 (Gateway + Microservices) | FULLSTACK, BE-ONLY |
-| **Generator-Frontend** | React/Next.js UI + API 연동 | FULLSTACK, FE-ONLY (React) |
-| **Generator-Frontend-Flutter** | Flutter (Riverpod + Retrofit + ARB i18n) | FULLSTACK, FE-ONLY (Flutter) |
-| **Evaluator-Functional** | Playwright E2E 기능 검증 | FULLSTACK, FE-ONLY (React) |
-| **Evaluator-Functional-Flutter** | flutter analyze/test + 정적 anti-pattern 검증 | FULLSTACK, FE-ONLY (Flutter) |
-| **Evaluator-Visual** | 디자인 일관성, 반응형, 접근성, AI슬롭 감지 | FULLSTACK, FE-ONLY (React만) |
+### 7. Lead에서 할 수 있는 것
 
-### Brainstormer (조건부)
+| 할 수 있는 것 | 예시 |
+|--------------|------|
+| Teams 가동/중지 | `/harness-team-action`, `/harness-team-stop` |
+| Queue 상태 확인 | `bash scripts/harness-queue-manager.sh status .` |
+| 실패 Feature 분석 | "F-003이 왜 실패했는지 분석해줘" |
+| Feature 재큐 | `bash scripts/harness-queue-manager.sh requeue F-003 .` |
+| 코드 리뷰 | "F-002의 Sidebar 컴포넌트 리뷰해줘" |
+| Gotcha 등록 | "API 응답에 created_at은 ISO 8601이어야 해" |
+| Teammate에 메시지 | "team-1에게 API 스키마 변경 알려줘" |
 
-[obra/superpowers](https://github.com/obra/superpowers) (MIT License)의 brainstorming 방법론을 이식.
-바이브코딩 수준의 러프한 요구사항을 **대화형 Q&A로 구체화**하여 Planner가 바로 소비할 수 있는 `brainstorm-spec.md`로 만듭니다.
+**하지 말 것:** `/harness-generator-*`, `/harness-evaluator-*` 직접 호출 — Teammate가 처리합니다.
 
-**핵심 원칙:**
-- HARD-GATE: 사용자 승인 없이 구현 단계로 넘어갈 수 없음
-- 한 번에 한 질문, 객관식 우선
-- 2-3개 접근법 제시 후 사용자가 선택
-- Spec self-review + User Review Gate
+---
 
-**실행 조건:** Dispatcher가 "브레인스토밍 과정이 필요합니까? (Y/N)" 라고 묻고 사용자가 Y 응답한 경우에만. 피드백/이터레이션/직접 명령에서는 자동 스킵.
+## 에이전트
+
+| 에이전트 | 역할 | 모델 |
+|----------|------|------|
+| **Dispatcher** | 파이프라인 선택 + Gotcha 관리 | opus |
+| **Brainstormer** | 러프한 요구사항 대화형 구체화 | opus |
+| **Planner** | 제품 사양 + API 계약 + Feature 설계 | opus/ultraplan |
+| **Generator-Backend** | NestJS MSA 구현 | sonnet |
+| **Generator-Frontend** | React/Next.js UI 구현 | sonnet |
+| **Evaluator-Functional** | Playwright E2E 기능 검증 | opus/ultrathink |
+| **Evaluator-Visual** | 디자인, 반응형, 접근성 검증 | opus/ultrathink |
+
+### Brainstormer (조건부)
+
+[obra/superpowers](https://github.com/obra/superpowers) (MIT License) 기반. 바이브코딩 수준의 러프한 요구사항을 대화형 Q&A로 구체화합니다.
 
 ---
 
 ## 핵심 메커니즘
 
-### Auto-Routing (UserPromptSubmit Hook)
+### Auto-Routing
 
-설치 시 `.claude/settings.json`에 `UserPromptSubmit` 훅이 자동 등록됩니다. 모든 사용자 프롬프트가 Dispatcher를 경유하도록 컨텍스트를 주입합니다.
+모든 사용자 프롬프트가 Dispatcher를 자동 경유합니다.
 
-**per-message opt-out:**
-```
-> harness skip 그냥 이것만 답해줘
-> harness 없이 질문 하나만
-> without harness ...
 ```
+# per-message opt-out
+❯ harness skip 그냥 답해줘
 
-**전역 비활성:**
-```json
-// .harness/config.json
-{ "behavior": { "auto_route_dispatcher": false } }
+# 전역 비활성
+.harness/config.json → behavior.auto_route_dispatcher = false
 ```
 
 ### API Contract — 진실의 원천
 
-`api-contract.json`이 Frontend ↔ Gateway ↔ Microservices 간 유일한 계약서입니다. Planner만 수정 가능하며, Generator-BE는 이를 구현하고, Generator-FE는 이를 소비합니다.
+`api-contract.json`이 FE ↔ Gateway ↔ Services 간 유일한 계약서입니다.
 
-### AGENTS.md — 에이전트 불문 범용 컨텍스트
+### Gotcha 시스템
 
-모든 AI 에이전트(Claude, Cursor, Copilot, Windsurf)가 읽을 수 있는 공통 진입점입니다. 1차원 IA-MAP으로 폴더별 책임과 소유 에이전트를 명시합니다.
+사용자가 실수를 지적하면 Dispatcher가 자동 기록 → 이후 세션에서 반복 방지.
 
-```
-├── apps/gateway/     # [BE] API Gateway       → Generator-Backend
-├── apps/service-a/   # [BE] Microservice      → Generator-Backend
-├── apps/web/         # [FE] Frontend App      → Generator-Frontend
-└── .harness/         # [HARNESS] 하네스 시스템  → Planner
-```
+### Pre-Eval Gate
 
-### Gotcha 시스템 — 실수를 반복하지 않는 에이전트
+Generator → Evaluator 전환 전 결정론적 검증 (tsc, eslint, test). 실패 시 Evaluator 세션을 열지 않고 Generator로 자동 리라우팅.
 
-사용자가 에이전트의 실수를 지적하면 Dispatcher가 자동으로 감지하여 해당 에이전트의 gotchas 파일에 기록합니다. 이후 세션에서 에이전트는 시작 시 자신의 gotchas를 읽고 같은 실수를 반복하지 않습니다.
-
-```
-사용자: "API 응답에 created_at은 ISO 8601로 반환해야 해"
-  → Dispatcher: generator-backend.md에 [G-001] 기록
-  → Generator-BE 다음 세션: gotchas 읽기 → 같은 실수 방지
+```json
+// .harness/config.json
+"pre_eval_gate": {
+  "frontend_checks": ["npx tsc --noEmit", "npx eslint src/", "npx vitest run --bail 1"],
+  "frontend_cwd": "path/to/frontend"  // 프로젝트 루트와 다른 경우
+}
 ```
 
-### IA Structure Compliance — Step 0 Gate
-
-Evaluator는 기능 테스트 전에 AGENTS.md의 IA-MAP과 실제 폴더 구조를 대조합니다. 경로 누락이나 소유권 침범이 발견되면 **기능 테스트 없이 즉시 FAIL**합니다.
-
-### 브라운필드 지원
+### Evaluation System
 
-기존 프로젝트에 설치하면:
-- `scan-project.sh`가 Tech Stack, 폴더 구조, 기존 CLAUDE.md를 자동 스캔
-- 기존 CLAUDE.md 규칙을 "Preserved Rules" 섹션으로 이관
-- 원본은 `.harness/archive/pre-harness-backup/`에 백업
-- Flutter 프로젝트 자동 감지 (`pubspec.yaml` + `flutter:`)
+| 설정 | 값 |
+|------|------|
+| PASS 기준 | 2.80 / 3.00 이상 |
+| FAIL 기준 | 2.79 이하 (예외 없음) |
+| Evidence 없는 Score | 0점 강제 |
+| Regression 실패 | 1건이라도 → 전체 FAIL |
 
 ---
 
-## FE 스택별 지원
-
-### React / Next.js (기본)
-
-| 항목 | 상세 |
-|------|------|
-| Generator | `harness-generator-frontend` — RSC, App Router, Tailwind CSS, Cache Components |
-| Evaluator-Func | `harness-evaluator-functional` — Playwright MCP (`browser_*`) E2E 테스트 |
-| Evaluator-Visual | `harness-evaluator-visual` — 스크린샷 기반 디자인/접근성/반응형 검증 |
-| 레퍼런스 | Vercel Best Practices, Design System Rules, AI Forbidden Patterns, Component Patterns |
-
-### Flutter (Dart) — Web / Mobile / Desktop
-
-| 항목 | Web (`fe_target=web`) | Mobile/Desktop (`fe_target=mobile`/`desktop`) |
-|------|----------------------|---------------------------------------------|
-| Generator | `harness-generator-frontend-flutter` (Web 가이드 활성) | `harness-generator-frontend-flutter` (Mobile/Desktop 가이드) |
-| Eval-Func | **`harness-evaluator-functional`** (Playwright MCP) | `harness-evaluator-functional-flutter` (`flutter analyze` + `flutter test` + build_runner drift + FL-01~FL-08 정적 검증) |
-| Eval-Visual | **`harness-evaluator-visual`** (Playwright 스크린샷/반응형/접근성) | **SKIP** (브라우저 없음) |
-| 레퍼런스 공통 | API Layer Pattern, Riverpod Pattern, i18n Pattern, Anti-Patterns | 동일 |
-| 레퍼런스 추가 | **Flutter Web Pattern** (`dart:html`/`package:web` 허용, go_router, CORS, PWA, 빌드/호스팅) | — |
-| dart:html / package:web | **허용** (가능하면 conditional import 권장) | **금지** (모바일/데스크톱 빌드 실패 유발) |
-| 빌드 명령 | `flutter build web --release` / `flutter run -d chrome` | `flutter build apk` / `flutter build ios` / `flutter build macos` 등 |
-
-### FE 스택 + 타겟 감지
-
-1. `scan-project.sh`가 `pubspec.yaml` + `flutter:` 키를 탐지하여 `fe_stack = "flutter"` 설정
-2. 같은 스캔이 `web/index.html`, `android/`, `ios/`, `macos/`/`windows/`/`linux/` 존재 여부로 `fe_target` 자동 판정 (`web` / `mobile` / `desktop`)
-3. Planner 가 모호한 경우(멀티 타겟, unknown) 사용자에게 단 한 번 확인하고 `pipeline.json.fe_target` 확정
-4. `harness-next.sh`가 `fe_stack + fe_target` 조합에 따라 FE 에이전트를 자동 치환 (Agent Bar에도 반영)
+## Harness Studio (tmux)
 
----
+### Studio v3 (Classic)
 
-## 스크립트 레퍼런스
+```bash
+npx walwal-harness studio
+```
 
-| 스크립트 | 설명 | 실행 방법 |
-|----------|------|----------|
-| `harness-next.sh` | 세션 오케스트레이터 — progress.json 읽고 다음 에이전트 결정, 프로그레스 바 출력 | `bash scripts/harness-next.sh` |
-| `scan-project.sh` | 프로젝트 구조 스캔 → `.harness/actions/scan-result.json` 출력 | `bash scripts/scan-project.sh .` |
-| `init-agents-md.sh` | scan-result.json 기반 AGENTS.md 생성/리빌드 | `bash scripts/init-agents-md.sh .` |
-| `harness-session-start.sh` | SessionStart 훅 — 세션 시작 시 progress 요약 출력 | (자동 — .claude/settings.json 훅) |
-| `harness-user-prompt-submit.sh` | UserPromptSubmit 훅 — 모든 프롬프트를 Dispatcher 경유 라우팅 | (자동 — .claude/settings.json 훅) |
+```
+┌──────────────┬──────────────┐
+│  Dashboard    │ Monitor      │
+│  (Progress)   ├──────────────┤
+├──────────────┤ Agent Session │
+│  Control      ├──────────────┤
+│  (harness>)   │ Eval Review  │
+└──────────────┴──────────────┘
+```
 
----
+### Studio v4 (Agent Teams)
 
-## Tech Stack
+```bash
+npx walwal-harness v4
+```
 
-| 영역 | 기술 |
-|------|------|
-| Backend | NestJS (TypeScript) + MSA |
-| Frontend (React) | React 또는 Next.js (TypeScript) + Tailwind CSS |
-| Frontend (Flutter) | Flutter (Dart) + Riverpod + Retrofit + ARB i18n |
-| E2E Testing (React) | Playwright MCP |
-| E2E Testing (Flutter) | flutter analyze + flutter test + 정적 검증 |
-| Unit Testing | Jest (BE) + Vitest (FE-React) + flutter test (FE-Flutter) |
-| Database | PostgreSQL / SQLite |
+```
+┌──────────────┬──────────────┬──────────────┐
+│              │  Progress    │  Team 1      │
+│  Main        ├──────────────┤  Team 2      │
+│  (Claude)    │  Prompts     │  Team 3      │
+└──────────────┴──────────────┴──────────────┘
+```
 
 ---
 
-## 권장 외부 스킬
-
-하네스는 자체 reference 파일로 기본 가이드를 제공하지만, 아래 외부 스킬을 설치하면 품질이 향상됩니다. 초기화 시 자동으로 설치 여부를 체크하고 안내합니다.
+## 프로젝트 구조
 
-| 스킬 | 설명 | 사용 에이전트 |
-|------|------|-------------|
-| **vercel** | Vercel/Next.js 배포, 성능 최적화, AI SDK | Generator-FE |
-| **web-design-guidelines** | UI/UX 접근성, Web Interface Guidelines | Evaluator-Visual, Generator-FE |
-| **taste-skill** | AI 생성 UI 디자인 품질, AI슬롭 감지 | Evaluator-Visual, Generator-FE |
-| **supanova-design-skill** | 디자인 시스템 규칙, 시각적 일관성 | Evaluator-Visual, Generator-FE |
+```
+your-project/
+├── AGENTS.md                           # 에이전트 공통 컨텍스트
+├── CLAUDE.md → AGENTS.md               # 심볼릭 링크
+├── scripts/
+│   ├── harness-next.sh                 # 세션 오케스트레이터
+│   ├── harness-session-start.sh        # SessionStart 훅
+│   ├── harness-user-prompt-submit.sh   # UserPromptSubmit 훅
+│   ├── harness-queue-manager.sh        # v4: Feature Queue 관리
+│   ├── harness-team-worker.sh          # v4: Team Worker (Gen→Eval 루프)
+│   ├── harness-studio-v4.sh            # v4: tmux 레이아웃
+│   ├── harness-dashboard-v4.sh         # v4: Progress 패널
+│   ├── harness-prompts-v4.sh           # v4: Prompts 패널
+│   └── lib/
+├── .harness/
+│   ├── config.json                     # 하네스 설정
+│   ├── HARNESS.md                      # 상세 가이드
+│   ├── progress.json                   # 세션 간 상태
+│   ├── progress.log                    # append-only 히스토리
+│   ├── gotchas/                        # 에이전트별 실수 기록
+│   ├── actions/
+│   │   ├── feature-list.json           # 기능 목록 + AC
+│   │   ├── feature-queue.json          # v4: Feature Queue 상태
+│   │   ├── api-contract.json           # API 계약서
+│   │   └── plan.md                     # 제품 사양
+│   └── archive/                        # 완료 스프린트 보관
+└── .claude/
+    ├── settings.json                   # 훅 등록
+    └── skills/                         # Claude Code 스킬 (8개)
+```
 
 ---
 
-## Playwright MCP 설정 (React 프로젝트)
+## Playwright MCP 설정
 
-Evaluator-Functional / Evaluator-Visual이 브라우저 테스트를 수행하려면 Playwright MCP가 필요합니다. `~/.mcp.json`에 추가:
+Evaluator가 브라우저 테스트를 수행하려면 Playwright MCP가 필요합니다:
 
 ```json
+// ~/.mcp.json
 {
   "mcpServers": {
     "playwright": {
@@ -345,8 +355,6 @@ Evaluator-Functional / Evaluator-Visual이 브라우저 테스트를 수행하
 }
 ```
 
-> **Flutter Web (`fe_target=web`) 프로젝트도 Playwright 가 필요합니다** — 컴파일 결과가 일반 웹앱과 동일하므로 React 와 같은 evaluator 를 재사용합니다. **Flutter Mobile/Desktop (`fe_target=mobile`/`desktop`) 프로젝트만** Playwright 없이 `flutter analyze` + `flutter test` 기반으로 동작합니다.
-
 ---
 
 ## 트러블슈팅
@@ -354,76 +362,30 @@ Evaluator-Functional / Evaluator-Visual이 브라우저 테스트를 수행하
 ### Skills가 로드되지 않아요
 
 ```bash
-# Claude Code 세션을 완전히 종료하고 다시 시작
-/exit
-# 프로젝트 디렉토리에서 재진입 후 확인
+/exit  # Claude Code 세션 종료
+# 프로젝트 디렉토리에서 재진입
 ```
 
-Claude Code는 세션 시작 시 `.claude/skills/`를 스캔합니다. `npm install` 이후 반드시 세션 재시작이 필요합니다.
-
-### Dispatcher가 자동 호출되지 않아요
-
-`UserPromptSubmit` 훅이 정상적으로 등록되었는지 확인:
+### 스크립트가 구버전이에요
 
 ```bash
-cat .claude/settings.json
-# hooks.UserPromptSubmit 배열에 harness-user-prompt-submit.sh가 있어야 함
+npx walwal-harness  # 코어 스크립트 자동 덮어쓰기
 ```
 
-등록이 안 되었다면:
+### v4 Team이 "No features ready" 반복
 
 ```bash
-npx walwal-harness --force
-# 재시작
+# Studio를 재시작하면 자동으로 stale in_progress 복구
+npx walwal-harness v4
 ```
 
-### 브레인스토밍이 매번 실행돼서 피로해요
+### Auto-routing 끄기
 
-Brainstormer는 Dispatcher가 "브레인스토밍 필요합니까?" 물을 때만 실행됩니다. **N**으로 답하면 Planner로 직행합니다. 피드백/이터레이션/특정 에이전트 명령에서는 질문 자체가 나오지 않습니다.
-
-### Flutter 프로젝트인데 React 에이전트가 실행돼요
-
-```bash
-# 프로젝트 루트에 pubspec.yaml이 있고 flutter: 키가 존재하는지 확인
-grep "flutter:" pubspec.yaml
-
-# 재스캔
-bash scripts/scan-project.sh .
-# pipeline.json의 fe_stack + fe_target 값 확인
-cat .harness/actions/pipeline.json | jq '.fe_stack, .fe_target'
 ```
-
-### Flutter Web 프로젝트인데 evaluator-functional-flutter (정적 분석) 가 실행돼요
-
-`fe_target` 이 `web` 으로 감지되지 않아서 발생합니다. 다음 두 가지를 확인:
-
-```bash
-# 1) Flutter 프로젝트 루트에 web/index.html 이 존재하는가?
-ls -la web/index.html
-# 없으면 Flutter Web 활성화:
-flutter config --enable-web
-flutter create --platforms=web .
-
-# 2) pipeline.json 의 fe_target 값 확인
-jq '.fe_target' .harness/actions/pipeline.json
-# "mobile" 또는 "unknown" 이면 수동 수정 또는 재스캔
-bash scripts/scan-project.sh .
-```
-
-`fe_target = web` 으로 확정되면 Playwright 기반 `evaluator-functional` + `evaluator-visual` 이 자동 사용됩니다.
-
-### Auto-routing을 끄고 싶어요
-
-```json
-// .harness/config.json
-{ "behavior": { "auto_route_dispatcher": false } }
+❯ harness skip 답만 해줘
 ```
 
-또는 개별 메시지에서:
-
-```
-> harness skip 그냥 이것만 답해줘
-```
+또는 `.harness/config.json`에서 `behavior.auto_route_dispatcher = false`
 
 ---
 
@@ -432,7 +394,7 @@ bash scripts/scan-project.sh .
 - [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
 - [Anthropic: Harness Design for Long-Running Application Development](https://www.anthropic.com/engineering/harness-design-long-running-apps)
 - [Claude Code Skills Documentation](https://code.claude.com/docs/en/skills)
-- [obra/superpowers](https://github.com/obra/superpowers) — Brainstorming skill 원본 (MIT License)
+- [obra/superpowers](https://github.com/obra/superpowers) — Brainstorming skill (MIT License)
 
 ## License