@walwal-harness/cli 2.0.1 → 2.3.1

package/README.md

@@ -7,87 +7,217 @@
 
 같은 AI 모델이라도 **하네스 설계에 따라 결과물 품질이 극적으로 달라집니다.** walwal-harness는 Anthropic이 제안한 하네스 엔지니어링 패턴을 설치 한 번으로 즉시 사용할 수 있게 패키징한 프레임워크입니다.
 
-## 무엇을 하는가
+---
 
-6개의 전문화된 AI 에이전트가 **역할 분리 + 피드백 루프**로 소프트웨어를 만듭니다:
+## 설치
 
+```bash
+npm install @walwal-harness/cli
 ```
-"하네스 엔지니어링 시작"
-         │
-         ▼
-    DISPATCHER ─── 요청 분석 ─── 파이프라인 자동 선택
-         │
-    ┌────┴────┬──────────┐
-    ▼         ▼          ▼
- FULLSTACK  FE-ONLY   BE-ONLY
+
+`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 자동 생성
+
+> **중요:** 설치 후 Claude Code 세션을 **재시작**해야 skills가 인식됩니다.
+> `/exit` → 디렉터리 재진입이 필요합니다.
+
+### CLI 명령
+
+```bash
+npx walwal-harness           # 초기화 (postinstall과 동일)
+npx walwal-harness --force   # 강제 재초기화 (기존 파일 덮어쓰기)
+npx walwal-harness --help    # 도움말
 ```
 
-### FULLSTACK (신규 프로젝트)
+### 초기화에서 일어나는 일
+
+```
+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/
 ```
-Planner → Generator-BE → Generator-FE → Evaluator-Func → Evaluator-Visual
-                                              │ FAIL
-                                              └──→ 재작업 (max 10회)
+
+---
+
+## Quick Start
+
+### 1. 설치 + 재시작
+
+```bash
+cd your-project
+npm install @walwal-harness/cli
+# Claude Code 세션 재시작 (/exit → 재진입)
 ```
 
-### FE-ONLY (기존 API에 프론트엔드 연동)
+### 2. 하네스 시작
+
+Claude Code에서 아무 요청이나 입력하면 **UserPromptSubmit 훅이 자동으로 Dispatcher를 호출**합니다. 또는 명시적으로:
+
 ```
-Planner(light) → Generator-FE → Evaluator-Func → Evaluator-Visual
-     └─ OpenAPI → api-contract.json 자동 변환
+> 하네스 엔지니어링 시작
 ```
 
-### BE-ONLY (기존 서버에 백엔드 기능 추가)
+### 3. Dispatcher가 분류
+
 ```
-Planner → Generator-BE → Evaluator-Func(API-only)
+사용자 입력
+    │
+    ├─ 신규 기능/제품 요청 → 파이프라인 선택 (FULLSTACK / FE-ONLY / BE-ONLY)
+    │   └─ "브레인스토밍 필요합니까?" → Y: Brainstormer → Planner
+    │                                  → N: Planner 직행
+    ├─ 실수 지적 → Gotcha 기록 → 해당 에이전트 재작업
+    ├─ 특정 에이전트 명령 → 해당 에이전트 직접 라우팅
+    └─ 메타/인사 → 일반 응답
 ```
 
-## 설치
+### 4. 에이전트 순차 실행
 
-```bash
-npm install @walwal-harness/cli
+각 에이전트가 완료되면 다음 프롬프트를 제안합니다:
+
+```
+✓ Dispatcher 완료. bash scripts/harness-next.sh 실행하여 다음 단계 확인.
 ```
 
-`postinstall`이 자동으로 프로젝트 루트에 설치합니다:
-- `.harness/` 디렉토리 스캐폴딩 (actions, archive, gotchas)
-- `.claude/skills/` 에 6개 에이전트 스킬 설치
-- `AGENTS.md` 생성 + `CLAUDE.md` 심볼릭 링크
-- 기존 프로젝트면 구조 스캔 → IA-MAP 자동 생성
+`bash scripts/harness-next.sh` 를 실행하면 프로그레스 바 + 다음 에이전트 안내:
 
-> **Note:** `npm install` 후 Claude Code 세션을 **재시작**해야 skills가 인식됩니다.
-> Claude Code는 세션 시작 시 `.claude/skills/`를 스캔하므로, 설치 후 `/exit` → 재진입이 필요합니다.
+```
+═══ Sprint 1 / FULLSTACK ═══════════════════
 
-### CLI 명령
+Agents: planner✓ → generator-backend✓ → [generator-frontend] → evaluator-functional → evaluator-visual
 
-```bash
-npx walwal-harness           # 초기화 (postinstall과 동일)
-npx walwal-harness --force   # 강제 재초기화 (기존 파일 덮어쓰기)
-npx walwal-harness --help    # 도움말
+/harness-generator-frontend 를 실행하세요.
 ```
 
-## 사용법
+### 5. 반복
 
-Claude Code를 **재시작**한 뒤:
+FAIL이 발생하면 Evaluator가 원인을 분석하고 해당 Generator로 자동 재작업 라우팅 (최대 10회). PASS하면 다음 Evaluator로 진행. 모든 Evaluator를 통과하면 스프린트 완료 → 아카이브.
+
+---
+
+## 파이프라인
+
+Dispatcher가 사용자 요청을 분석하여 3가지 파이프라인 중 하나를 자동 선택합니다:
+
+### FULLSTACK (신규 프로젝트)
 
 ```
-> 하네스 엔지니어링 시작
+Brainstormer? → Planner → Generator-BE → Generator-FE → Evaluator-Func → Evaluator-Visual
+                                                              │ FAIL
+                                                              └──→ 재작업 (max 10회)
 ```
 
-이 한 마디로 Dispatcher가 실행되어:
-1. 프로젝트 초기화 상태 확인 (빈 프로젝트 / 기존 프로젝트 자동 감지)
-2. 사용자 요청 분석 → 파이프라인 선택
-3. 순차적으로 에이전트 실행
+### FE-ONLY (기존 API에 프론트엔드 연동)
+
+```
+Brainstormer? → Planner(light) → Generator-FE → Evaluator-Func → Evaluator-Visual
+                    └─ OpenAPI → api-contract.json 자동 변환
+```
+
+### BE-ONLY (기존 서버에 백엔드 기능 추가)
+
+```
+Brainstormer? → Planner → Generator-BE → Evaluator-Func(API-only)
+```
+
+> `Brainstormer?` = Dispatcher가 사용자에게 확인 후 조건부 실행. 명확한 PRD/OpenAPI가 있으면 생략 가능.
+
+### Flutter 프로젝트 자동 감지
+
+`pubspec.yaml` + `flutter:` 키가 감지되면 FE 에이전트가 **자동 치환**됩니다:
+
+| React (기본) | Flutter |
+|-------------|---------|
+| `generator-frontend` | `generator-frontend-flutter` |
+| `evaluator-functional` (Playwright) | `evaluator-functional-flutter` (flutter analyze/test) |
+| `evaluator-visual` | **SKIP** (브라우저 없음) |
+
+치환은 `pipeline.json.fe_stack` 값에 의해 `harness-next.sh`가 자동 처리합니다. Planner가 프로젝트 스캔 결과를 보고 `fe_stack`을 확정합니다.
+
+---
 
-## 6개 에이전트
+## 에이전트
 
-| 에이전트 | 역할 | SKILL |
-|----------|------|-------|
-| **Dispatcher** | 파이프라인 선택 + Gotcha 관리 | `harness-dispatcher` |
-| **Planner** | 제품 사양 + API 계약서 + IA-MAP 설계 | `harness-planner` |
-| **Generator-Backend** | NestJS MSA 구현 (Gateway + Microservices) | `harness-generator-backend` |
-| **Generator-Frontend** | React/Next.js UI + API 연동 | `harness-generator-frontend` |
-| **Evaluator-Functional** | Playwright E2E 기능 검증 + IA 구조 검증 | `harness-evaluator-functional` |
-| **Evaluator-Visual** | 디자인 일관성, 반응형, 접근성, AI슬롭 감지 | `harness-evaluator-visual` |
+### 9개 에이전트 (조건부 포함)
 
-## 핵심 기능
+| 에이전트 | 역할 | 호출 조건 |
+|----------|------|----------|
+| **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만) |
+
+### Brainstormer (조건부)
+
+[obra/superpowers](https://github.com/obra/superpowers) (MIT License)의 brainstorming 방법론을 이식.
+바이브코딩 수준의 러프한 요구사항을 **대화형 Q&A로 구체화**하여 Planner가 바로 소비할 수 있는 `brainstorm-spec.md`로 만듭니다.
+
+**핵심 원칙:**
+- HARD-GATE: 사용자 승인 없이 구현 단계로 넘어갈 수 없음
+- 한 번에 한 질문, 객관식 우선
+- 2-3개 접근법 제시 후 사용자가 선택
+- Spec self-review + User Review Gate
+
+**실행 조건:** Dispatcher가 "브레인스토밍 과정이 필요합니까? (Y/N)" 라고 묻고 사용자가 Y 응답한 경우에만. 피드백/이터레이션/직접 명령에서는 자동 스킵.
+
+---
+
+## 핵심 메커니즘
+
+### Auto-Routing (UserPromptSubmit Hook)
+
+설치 시 `.claude/settings.json`에 `UserPromptSubmit` 훅이 자동 등록됩니다. 모든 사용자 프롬프트가 Dispatcher를 경유하도록 컨텍스트를 주입합니다.
+
+**per-message opt-out:**
+```
+> harness skip 그냥 이것만 답해줘
+> harness 없이 질문 하나만
+> without harness ...
+```
+
+**전역 비활성:**
+```json
+// .harness/config.json
+{ "behavior": { "auto_route_dispatcher": false } }
+```
 
 ### API Contract — 진실의 원천
 
@@ -124,52 +254,64 @@ Evaluator는 기능 테스트 전에 AGENTS.md의 IA-MAP과 실제 폴더 구조
 - `scan-project.sh`가 Tech Stack, 폴더 구조, 기존 CLAUDE.md를 자동 스캔
 - 기존 CLAUDE.md 규칙을 "Preserved Rules" 섹션으로 이관
 - 원본은 `.harness/archive/pre-harness-backup/`에 백업
+- Flutter 프로젝트 자동 감지 (`pubspec.yaml` + `flutter:`)
 
-## 디렉토리 구조
+---
 
-설치 후 프로젝트에 생성되는 구조:
+## FE 스택별 지원
 
-```
-your-project/
-├── AGENTS.md                       # 에이전트 공통 컨텍스트 (Planner 관리)
-├── CLAUDE.md → AGENTS.md           # 심볼릭 링크
-├── .harness/
-│   ├── config.json                 # 하네스 설정
-│   ├── progress.json               # 세션 간 상태 (기계 판독)
-│   ├── gotchas/                    # 에이전트별 실수 기록
-│   │   ├── planner.md
-│   │   ├── generator-backend.md
-│   │   ├── generator-frontend.md
-│   │   ├── evaluator-functional.md
-│   │   └── evaluator-visual.md
-│   ├── actions/                    # 활성 스프린트 문서
-│   │   ├── pipeline.json
-│   │   ├── plan.md
-│   │   ├── feature-list.json
-│   │   ├── api-contract.json
-│   │   └── sprint-contract.md
-│   └── archive/                    # 완료 스프린트 보관 (불변)
-│       └── sprint-NNN/
-└── .claude/skills/                 # Claude Code 스킬
-    ├── harness-dispatcher/
-    ├── harness-planner/
-    ├── harness-generator-backend/
-    ├── harness-generator-frontend/
-    ├── harness-evaluator-functional/
-    └── harness-evaluator-visual/
-```
+### 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)
+
+| 항목 | 상세 |
+|------|------|
+| Generator | `harness-generator-frontend-flutter` — Riverpod + integrated_data_layer(Retrofit) + ARB i18n |
+| Evaluator-Func | `harness-evaluator-functional-flutter` — `flutter analyze` + `flutter test` + build_runner drift + anti-pattern grep (FL-01~FL-08) |
+| Evaluator-Visual | **SKIP** (Flutter 앱은 브라우저 기반 시각 검증 불가) |
+| 레퍼런스 | API Layer Pattern, Riverpod Pattern, i18n Pattern, Anti-Patterns (9개 금지 패턴 + 셀프 체크 스크립트) |
+
+### FE 스택 감지
+
+1. `scan-project.sh`가 `pubspec.yaml` + `flutter:` 키를 탐지
+2. Planner가 `pipeline.json.fe_stack = "flutter"` 확정
+3. `harness-next.sh`가 FE 에이전트를 자동 치환 (Agent Bar에도 반영)
+
+---
+
+## 스크립트 레퍼런스
+
+| 스크립트 | 설명 | 실행 방법 |
+|----------|------|----------|
+| `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 훅) |
+
+---
 
 ## Tech Stack
 
 | 영역 | 기술 |
 |------|------|
 | Backend | NestJS (TypeScript) + MSA |
-| Frontend | React 또는 Next.js (TypeScript) |
-| Styling | Tailwind CSS |
-| E2E Testing | Playwright MCP |
-| Unit Testing | Jest (BE) + Vitest (FE) |
+| 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 |
 
+---
+
 ## 권장 외부 스킬
 
 하네스는 자체 reference 파일로 기본 가이드를 제공하지만, 아래 외부 스킬을 설치하면 품질이 향상됩니다. 초기화 시 자동으로 설치 여부를 체크하고 안내합니다.
@@ -181,9 +323,11 @@ your-project/
 | **taste-skill** | AI 생성 UI 디자인 품질, AI슬롭 감지 | Evaluator-Visual, Generator-FE |
 | **supanova-design-skill** | 디자인 시스템 규칙, 시각적 일관성 | Evaluator-Visual, Generator-FE |
 
-## Playwright MCP 설정
+---
+
+## Playwright MCP 설정 (React 프로젝트)
 
-Evaluator가 브라우저 테스트를 수행하려면 Playwright MCP가 필요합니다. `~/.mcp.json`에 추가:
+Evaluator-Functional / Evaluator-Visual이 브라우저 테스트를 수행하려면 Playwright MCP가 필요합니다. `~/.mcp.json`에 추가:
 
 ```json
 {
@@ -196,12 +340,75 @@ Evaluator가 브라우저 테스트를 수행하려면 Playwright MCP가 필요
 }
 ```
 
+> Flutter 프로젝트에서는 Playwright가 필요 없습니다 — `evaluator-functional-flutter`는 `flutter analyze` + `flutter test` 기반입니다.
+
+---
+
+## 트러블슈팅
+
+### Skills가 로드되지 않아요
+
+```bash
+# Claude Code 세션을 완전히 종료하고 다시 시작
+/exit
+# 프로젝트 디렉토리에서 재진입 후 확인
+```
+
+Claude Code는 세션 시작 시 `.claude/skills/`를 스캔합니다. `npm install` 이후 반드시 세션 재시작이 필요합니다.
+
+### Dispatcher가 자동 호출되지 않아요
+
+`UserPromptSubmit` 훅이 정상적으로 등록되었는지 확인:
+
+```bash
+cat .claude/settings.json
+# hooks.UserPromptSubmit 배열에 harness-user-prompt-submit.sh가 있어야 함
+```
+
+등록이 안 되었다면:
+
+```bash
+npx walwal-harness --force
+# 재시작
+```
+
+### 브레인스토밍이 매번 실행돼서 피로해요
+
+Brainstormer는 Dispatcher가 "브레인스토밍 필요합니까?" 물을 때만 실행됩니다. **N**으로 답하면 Planner로 직행합니다. 피드백/이터레이션/특정 에이전트 명령에서는 질문 자체가 나오지 않습니다.
+
+### Flutter 프로젝트인데 React 에이전트가 실행돼요
+
+```bash
+# 프로젝트 루트에 pubspec.yaml이 있고 flutter: 키가 존재하는지 확인
+grep "flutter:" pubspec.yaml
+
+# 재스캔
+bash scripts/scan-project.sh .
+# pipeline.json의 fe_stack 값 확인
+cat .harness/actions/pipeline.json | jq '.fe_stack'
+```
+
+### Auto-routing을 끄고 싶어요
+
+```json
+// .harness/config.json
+{ "behavior": { "auto_route_dispatcher": false } }
+```
+
+또는 개별 메시지에서:
+
+```
+> harness skip 그냥 이것만 답해줘
+```
+
+---
+
 ## 참고
 
 - [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)
-- [Skill Authoring Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
+- [obra/superpowers](https://github.com/obra/superpowers) — Brainstorming skill 원본 (MIT License)
 
 ## License
 

package/assets/templates/config.json

@@ -12,9 +12,20 @@
       "outputs": ["actions/pipeline.json"],
       "always_first": true
     },
+    "brainstorming": {
+      "role": "사용자의 러프한 요구사항을 대화형으로 구체화하여 Planner가 바로 쓸 수 있는 brainstorm-spec.md로 변환. Dispatcher가 사용자에게 '브레인스토밍 필요?' 확인 후에만 호출되는 조건부 에이전트.",
+      "skill": "harness-brainstorming",
+      "inputs": ["(user conversation)"],
+      "outputs": ["actions/brainstorm-spec.md"],
+      "conditional": true,
+      "invoked_by": "dispatcher (user opt-in)",
+      "next_on_complete": "planner",
+      "attribution": "Derived from obra/superpowers skills/brainstorming (MIT License)"
+    },
     "planner": {
       "role": "제품 사양 + API 계약서 + 서비스 분할 설계",
       "skill": "harness-planner",
+      "inputs": ["actions/brainstorm-spec.md (optional)"],
       "outputs": [
         "actions/plan.md",
         "actions/feature-list.json",
@@ -48,16 +59,40 @@
       "tools": ["playwright:browser_take_screenshot", "playwright:browser_resize", "playwright:browser_snapshot"],
       "inputs": ["actions/sprint-contract.md", "actions/evaluation-functional.md"],
       "outputs": ["actions/evaluation-visual.md"]
+    },
+    "generator-frontend-flutter": {
+      "role": "Flutter 앱 개발 — Riverpod, integrated_data_layer(Retrofit), i18n(ARB), build_runner",
+      "skill": "harness-generator-frontend-flutter",
+      "inputs": ["actions/plan.md", "actions/feature-list.json", "actions/api-contract.json", "actions/sprint-contract.md"],
+      "outputs": ["code:flutter", "actions/sprint-contract.md"],
+      "order": 2,
+      "fe_stack": "flutter"
+    },
+    "evaluator-functional-flutter": {
+      "role": "Flutter 앱 검증 — flutter analyze, flutter test, build_runner 일관성, 안티패턴 정적 검증",
+      "skill": "harness-evaluator-functional-flutter",
+      "tools": ["bash:flutter", "bash:dart"],
+      "inputs": ["actions/sprint-contract.md"],
+      "outputs": ["actions/evaluation-functional.md"],
+      "fe_stack": "flutter"
     }
   },
   "flow": {
     "sequence": ["dispatcher", "planner", "generator-backend", "generator-frontend", "evaluator-functional", "evaluator-visual"],
     "pipeline_selection": {
-      "comment": "Dispatcher가 pipeline.json으로 활성 에이전트를 결정. 이하 sequence에서 스킵 대상 제외.",
+      "comment": "Dispatcher가 pipeline.json으로 활성 에이전트를 결정. fe_stack 필드로 React/Flutter를 구분. harness-next.sh가 pipeline.json.fe_stack 을 읽어 generator-frontend/evaluator-functional 을 Flutter 변형으로 치환한다.",
       "pipelines": {
         "FULLSTACK": ["planner", "generator-backend", "generator-frontend", "evaluator-functional", "evaluator-visual"],
         "FE-ONLY": ["planner:light", "generator-frontend", "evaluator-functional", "evaluator-visual"],
         "BE-ONLY": ["planner", "generator-backend", "evaluator-functional:api-only"]
+      },
+      "fe_stack_substitution": {
+        "comment": "pipeline.json.fe_stack=flutter 이면 아래 치환을 적용. evaluator-visual은 skip.",
+        "flutter": {
+          "generator-frontend": "generator-frontend-flutter",
+          "evaluator-functional": "evaluator-functional-flutter",
+          "evaluator-visual": "__skip__"
+        }
       }
     },
     "sprint_execution": {
@@ -75,6 +110,11 @@
     "state_log": ".harness/progress.log",
     "next_prompt_file": ".harness/next-prompt.txt"
   },
+  "behavior": {
+    "comment": "하네스 동작 플래그. UserPromptSubmit 훅이 이 값을 읽어 자동 라우팅을 결정한다.",
+    "auto_route_dispatcher": true,
+    "auto_route_dispatcher_description": "true 이면 사용자의 모든 프롬프트가 harness-dispatcher 경유로 분류/라우팅 된다. 사용자가 'harness skip' 등을 말하면 단일 메시지 한정으로 건너뛴다."
+  },
   "paths": {
     "actions": ".harness/actions",
     "archive": ".harness/archive",

package/bin/init.js

@@ -295,6 +295,60 @@ function installSessionHook() {
   }
 }
 
+// ─────────────────────────────────────────
+// 3c. UserPromptSubmit hook (auto dispatcher routing)
+// ─────────────────────────────────────────
+function installUserPromptSubmitHook() {
+  log('Installing UserPromptSubmit hook (auto dispatcher routing)...');
+
+  const settingsDir = path.join(PROJECT_ROOT, '.claude');
+  const settingsFile = path.join(settingsDir, 'settings.json');
+
+  ensureDir(settingsDir);
+
+  let settings = {};
+  if (fileExists(settingsFile)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(settingsFile, 'utf8'));
+    } catch (e) {
+      log('WARNING: Could not parse existing .claude/settings.json, creating new');
+    }
+  }
+
+  if (!settings.hooks) settings.hooks = {};
+  if (!settings.hooks.UserPromptSubmit) settings.hooks.UserPromptSubmit = [];
+
+  const hookCmd = 'bash scripts/harness-user-prompt-submit.sh';
+
+  // Detect existing harness UserPromptSubmit hook (any shape)
+  const alreadyInstalled = settings.hooks.UserPromptSubmit.some((entry) => {
+    if (!entry || typeof entry !== 'object') return false;
+    if (Array.isArray(entry.hooks)) {
+      return entry.hooks.some(
+        (h) => h && h.command && h.command.includes('harness-user-prompt-submit')
+      );
+    }
+    if (entry.type === 'command' && entry.command) {
+      return entry.command.includes('harness-user-prompt-submit');
+    }
+    return false;
+  });
+
+  if (!alreadyInstalled) {
+    settings.hooks.UserPromptSubmit.push({
+      matcher: '',
+      hooks: [{ type: 'command', command: hookCmd }]
+    });
+    fs.writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + '\n');
+    log('UserPromptSubmit hook installed in .claude/settings.json');
+    log('  → All prompts will be routed through harness-dispatcher');
+    log('  → Opt-out per message: say "harness skip" or "without harness"');
+    log('  → Disable globally: set .harness/config.json behavior.auto_route_dispatcher = false');
+  } else {
+    log('UserPromptSubmit hook already installed');
+  }
+}
+
 // ─────────────────────────────────────────
 // 4. AGENTS.md + CLAUDE.md
 // ─────────────────────────────────────────
@@ -453,9 +507,16 @@ What it does:
   1. Scaffolds .harness/ directory (actions, archive, gotchas, config)
   2. Installs skills to .claude/skills/ (dispatcher, planner, generators, evaluators)
   3. Copies helper scripts to scripts/
-  4. Creates AGENTS.md + CLAUDE.md symlink
-  5. Checks Playwright MCP configuration
-  6. Checks recommended external skills (Vercel, design skills)
+  4. Registers SessionStart hook (boot-time progress render)
+  5. Registers UserPromptSubmit hook (auto-route every prompt through harness-dispatcher)
+  6. Creates AGENTS.md + CLAUDE.md symlink
+  7. Checks Playwright MCP configuration
+  8. Checks recommended external skills (Vercel, design skills)
+
+Auto routing:
+  Every user prompt is routed through harness-dispatcher.
+  Per-message opt-out: say "harness skip" or "harness 없이".
+  Global disable: edit .harness/config.json → behavior.auto_route_dispatcher = false
 
 After init:
   1. Restart Claude Code session (exit and re-enter) for skills to load
@@ -487,6 +548,7 @@ function main() {
   installSkills();
   installScripts();
   installSessionHook();
+  installUserPromptSubmitHook();
   setupAgentsMd();
   checkPlaywrightMcp();
   checkRecommendedSkills();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@walwal-harness/cli",
-  "version": "2.0.1",
-  "description": "Production harness for AI agent engineering — Planner, Generator(BE/FE), Evaluator(Func/Visual) with Gotcha management",
+  "version": "2.3.1",
+  "description": "Production harness for AI agent engineering — Planner, Generator(BE/FE), Evaluator(Func/Visual), optional Brainstormer (requirements refinement). Supports React and Flutter FE stacks.",
   "bin": {
     "walwal-harness": "bin/init.js"
   },
@@ -16,11 +16,14 @@
     "ai-agent",
     "claude-code",
     "skill",
+    "brainstorming",
     "planner",
     "generator",
     "evaluator",
     "nestjs",
     "react",
+    "flutter",
+    "riverpod",
     "playwright"
   ],
   "author": "",