@walwal-harness/cli 1.0.0

package/assets/templates/AGENTS.md.template

@@ -0,0 +1,52 @@
+# AGENTS.md — Project Context for AI Agents
+
+> 이 파일은 모든 AI 에이전트(Claude, Cursor, Copilot, Windsurf 등)의 공통 진입점입니다.
+> CLAUDE.md는 이 파일의 심볼릭 링크입니다.
+> Generated by walwal-harness ({{DATE}})
+
+## Project
+
+- **Name**: (Planner가 설정)
+- **Description**: (Planner가 설정)
+- **Phase**: INIT
+- **Harness**: `.harness/HARNESS.md` 참조
+
+## Tech Stack
+
+- Backend: (scan-project.sh가 감지)
+- Frontend: (scan-project.sh가 감지)
+- Database: (scan-project.sh가 감지)
+
+## IA-MAP (Information Architecture)
+
+> Planner가 프로젝트 시작 시 확정합니다.
+> `[?]` 태그는 Planner가 분류해야 하는 미확인 경로입니다.
+
+```
+/
+├── AGENTS.md             # [META] 프로젝트 컨텍스트           → Planner
+├── CLAUDE.md             # [META] → AGENTS.md 심볼릭 링크
+└── .harness/             # [HARNESS] 하네스 시스템             → Planner
+```
+
+## Rules (모든 에이전트 공통)
+
+### 읽기/쓰기 권한
+
+| 파일 | 읽기 | 쓰기 |
+|------|------|------|
+| AGENTS.md | 전체 | Planner만 |
+| .harness/actions/api-contract.json | 전체 | Planner만 |
+| .harness/actions/feature-list.json | 전체 | passes: Generator, 나머지: Planner |
+| .harness/progress.txt | 전체 | 전체 (세션 종료 시 업데이트 의무) |
+| `[BE]` 소유 경로 | 전체 | Generator-Backend만 |
+| `[FE]` 소유 경로 | 전체 | Generator-Frontend만 |
+| .harness/archive/ | 전체 | 쓰기 금지 (불변) |
+| .harness/gotchas/ | 전체 | Dispatcher만 |
+
+### 금지 사항
+
+- AGENTS.md를 Planner 외 에이전트가 수정
+- 서비스 간 직접 DB 접근
+- 테스트 삭제/약화
+- archive/ 내 파일 수정

package/assets/templates/HARNESS.md

@@ -0,0 +1,159 @@
+# 6-Agent Production Harness — 사용 가이드
+
+> Anthropic 블로그 "Harness Design for Long-Running Application Development" 기반
+> Solo: 20min/$9 (broken) → Harness: 6hr/$200 (fully functional)
+> Stack: NestJS MSA + React/Next.js + Playwright MCP
+
+## 디렉토리 구조
+
+```
+.harness/
+├── HARNESS.md                  # 이 파일
+├── config.json                 # 하네스 설정
+├── progress.txt                # 세션 간 상태 전달 로그
+├── prompts/                    # 에이전트 프롬프트 (6개)
+│   ├── dispatcher.md           # Dispatcher — 파이프라인 선택
+│   ├── planner.md              # Planner — 제품 사양 + MSA 설계
+│   ├── generator-backend.md    # Generator-BE — NestJS MSA 구현
+│   ├── generator-frontend.md   # Generator-FE — React/Next.js 구현
+│   ├── evaluator-functional.md # Evaluator-기능 — Playwright E2E
+│   └── evaluator-visual.md     # Evaluator-비주얼 — 디자인/접근성
+├── actions/                    # 현재 활성 문서
+│   ├── pipeline.json           # Dispatcher 결정 (어떤 파이프라인인지)
+│   ├── plan.md                 # 제품 사양
+│   ├── feature-list.json       # 기능 추적 (layer + service 필드)
+│   ├── api-contract.json       # API 계약서
+│   ├── sprint-contract.md      # 현재 스프린트 계약
+│   ├── evaluation-functional.md
+│   └── evaluation-visual.md
+└── archive/                    # 완료 스프린트 보관 (불변)
+    └── sprint-NNN/
+```
+
+## 실행 흐름
+
+```
+사용자: 프로젝트 요청 (자유 형식)
+         │
+         ▼
+┌──────────────────┐
+│  0. DISPATCHER    │  요청 분석 → pipeline.json 생성
+│  (파이프라인 선택) │  사용자 확인
+└────────┬─────────┘
+         │
+    ┌────┴────┬──────────┐
+    ▼         ▼          ▼
+ FULLSTACK  FE-ONLY   BE-ONLY
+```
+
+### FULLSTACK — 신규 PRD 기반 풀스택
+
+```
+Planner → Gen-BE → Gen-FE → Eval-Func → Eval-Visual → Archive
+```
+
+### FE-ONLY — 기존 API + 프론트엔드 연동
+
+```
+Planner(light) → Gen-FE → Eval-Func → Eval-Visual → Archive
+    │
+    └─ OpenAPI spec → api-contract.json 변환
+       Gen-BE SKIP (외부 서버 사용)
+```
+
+### BE-ONLY — 기존 서버 + 백엔드 기능 추가
+
+```
+Planner → Gen-BE → Eval-Func(API-only) → Archive
+    │
+    └─ 기존 코드 분석 후 확장 설계
+       Gen-FE SKIP, Eval-Visual SKIP
+       Eval-Func: Playwright 대신 curl/httpie API 테스트
+```
+
+### 공통 — 실패 시 루프
+
+```
+Eval-Func FAIL → failure_location에 따라 Gen-BE 또는 Gen-FE 재작업 (max 3회)
+Eval-Visual FAIL → Gen-FE 재작업 (max 3회)
+3회 초과 → 사용자 개입 요청
+```
+
+## 수동 프롬프트 실행 방법
+
+### Step 0: Dispatcher (항상 최초 실행)
+```
+".harness/prompts/dispatcher.md를 읽고 Dispatcher로 동작하세요.
+[사용자의 자유 형식 요청]"
+```
+
+### Step 1: Planner
+```
+".harness/prompts/planner.md를 읽고 Planner 에이전트로 동작하세요.
+pipeline.json을 참조하여 [light/full] 모드로 실행합니다."
+```
+
+### Step 2: Generator-Backend (FULLSTACK, BE-ONLY)
+```
+".harness/prompts/generator-backend.md를 읽고 Generator-Backend으로 동작하세요.
+Sprint [N]을 시작합니다."
+```
+
+### Step 3: Generator-Frontend (FULLSTACK, FE-ONLY)
+```
+".harness/prompts/generator-frontend.md를 읽고 Generator-Frontend으로 동작하세요.
+Sprint [N]의 프론트엔드를 구현합니다."
+```
+
+### Step 4: Evaluator-Functional
+```
+".harness/prompts/evaluator-functional.md를 읽고 Evaluator-Functional로 동작하세요.
+Sprint [N]을 평가합니다. Playwright MCP를 사용하세요."
+```
+
+### Step 5: Evaluator-Visual
+```
+".harness/prompts/evaluator-visual.md를 읽고 Evaluator-Visual로 동작하세요.
+Sprint [N]의 비주얼을 평가합니다."
+```
+
+### Archive (Eval-Visual PASS 후)
+```
+"Sprint [N] 문서를 아카이브 하세요.
+.harness/actions/의 스프린트 문서를 .harness/archive/sprint-NNN/으로 이동합니다."
+```
+
+## 핵심 원칙
+
+1. **Backend First** — API가 안정된 후 Frontend 연동 (없는 API 호출 방지)
+2. **api-contract.json이 진실의 원천** — FE↔Gateway↔Services 간 유일한 계약
+3. **한 세션에 1 스프린트** — 컨텍스트 소진 방지
+4. **feature-list.json의 passes만 수정** — 기능 정의는 Planner만 변경
+5. **테스트 삭제/약화 금지** — 테스트는 계약이다
+6. **Evaluator는 회의적** — 자기 설득 금지, 기준 미달 = FAIL
+7. **아카이브 불변** — 완료 문서 수정 금지
+8. **MSA 경계 존수** — 서비스 간 직접 DB 접근 금지, 반드시 메시지 패턴
+
+## Tech Stack
+
+| 영역 | 기술 |
+|------|------|
+| Backend Framework | NestJS (TypeScript) |
+| Architecture | MSA (Microservice Architecture) |
+| Monorepo | NestJS 내장 monorepo (nest-cli.json) |
+| Runner | 통합 러너 (`npm run dev` = concurrently) |
+| Transport | TCP (dev) / RabbitMQ·NATS (prod) |
+| Frontend | React 또는 Next.js (TypeScript) |
+| Styling | Tailwind CSS |
+| State | TanStack Query + Zustand |
+| E2E Testing | Playwright MCP |
+| Unit Testing | Jest (backend) + Vitest (frontend) |
+| Database | PostgreSQL (dev: SQLite 가능) |
+
+## MCP 도구
+
+Playwright MCP (`@playwright/mcp`) — headless + vision 모드:
+- `browser_navigate`, `browser_click`, `browser_fill`
+- `browser_take_screenshot`, `browser_snapshot`
+- `browser_console_messages`, `browser_network_requests`
+- `browser_resize`, `browser_press_key`, `browser_wait`

package/assets/templates/config.json

@@ -0,0 +1,108 @@
+{
+  "harness": {
+    "name": "6-Agent Production Harness",
+    "version": "3.0.0",
+    "description": "Dispatcher + NestJS MSA + React/Next.js + Playwright 기반 실무 하네스",
+    "source": "https://www.anthropic.com/engineering/harness-design-long-running-apps"
+  },
+  "agents": {
+    "dispatcher": {
+      "role": "사용자 요청 분석 → 파이프라인 결정 (FE-ONLY / BE-ONLY / FULLSTACK)",
+      "prompt_file": "prompts/dispatcher.md",
+      "outputs": ["actions/pipeline.json"],
+      "triggers_next": "planner",
+      "always_first": true
+    },
+    "planner": {
+      "role": "제품 사양 + API 계약서 + 서비스 분할 설계",
+      "prompt_file": "prompts/planner.md",
+      "outputs": [
+        "actions/plan.md",
+        "actions/feature-list.json",
+        "actions/api-contract.json"
+      ],
+      "triggers_next": ["generator-backend", "generator-frontend"]
+    },
+    "generator-backend": {
+      "role": "NestJS MSA 서비스 구현, API 엔드포인트, DB 스키마",
+      "prompt_file": "prompts/generator-backend.md",
+      "inputs": ["actions/plan.md", "actions/feature-list.json", "actions/api-contract.json", "actions/sprint-contract.md"],
+      "outputs": ["code:backend", "actions/sprint-contract.md"],
+      "triggers_next": "generator-frontend",
+      "order": 1
+    },
+    "generator-frontend": {
+      "role": "React/Next.js UI 컴포넌트, 상태관리, API 연동",
+      "prompt_file": "prompts/generator-frontend.md",
+      "inputs": ["actions/plan.md", "actions/feature-list.json", "actions/api-contract.json", "actions/sprint-contract.md"],
+      "outputs": ["code:frontend", "actions/sprint-contract.md"],
+      "triggers_next": "evaluator-functional",
+      "order": 2
+    },
+    "evaluator-functional": {
+      "role": "Playwright로 E2E 기능 검증, API 응답/DB 상태 확인",
+      "prompt_file": "prompts/evaluator-functional.md",
+      "tools": ["playwright:browser_*"],
+      "inputs": ["actions/sprint-contract.md"],
+      "outputs": ["actions/evaluation-functional.md"],
+      "on_fail": "generator-backend OR generator-frontend (결함 위치에 따라)",
+      "on_pass": "evaluator-visual"
+    },
+    "evaluator-visual": {
+      "role": "디자인 일관성, 반응형, 접근성, AI슬롭 감지",
+      "prompt_file": "prompts/evaluator-visual.md",
+      "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"],
+      "on_fail": "generator-frontend",
+      "on_pass": "archive_and_next_sprint"
+    }
+  },
+  "flow": {
+    "sequence": ["dispatcher", "planner", "generator-backend", "generator-frontend", "evaluator-functional", "evaluator-visual"],
+    "pipeline_selection": {
+      "comment": "Dispatcher가 pipeline.json으로 활성 에이전트를 결정. 이하 sequence에서 스킵 대상 제외.",
+      "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"]
+      }
+    },
+    "sprint_execution": {
+      "comment": "Backend 먼저 → API 안정 후 Frontend 연동 → 기능 QA → 비주얼 QA (FULLSTACK 기준)",
+      "backend_first": true,
+      "reason": "프론트가 존재하지 않는 API를 호출하는 실패 방지"
+    },
+    "retry_on_fail": true,
+    "max_retries_per_sprint": 3,
+    "archive_on_sprint_complete": true
+  },
+  "paths": {
+    "actions": ".harness/actions",
+    "archive": ".harness/archive",
+    "prompts": ".harness/prompts",
+    "gotchas": ".harness/gotchas",
+    "progress": ".harness/progress.txt"
+  },
+  "tech_stack": {
+    "backend": {
+      "framework": "NestJS (TypeScript)",
+      "architecture": "MSA (Microservice Architecture)",
+      "monorepo": "Nx 또는 Turborepo",
+      "runner": "통합 러너 (단일 명령으로 전체 서비스 기동/종료)",
+      "database": "PostgreSQL (dev: SQLite fallback 가능)",
+      "api_gateway": "NestJS API Gateway 패턴",
+      "transport": "TCP (dev) / RabbitMQ 또는 NATS (prod)"
+    },
+    "frontend": {
+      "framework": "React 또는 Next.js (TypeScript)",
+      "state": "Zustand 또는 TanStack Query",
+      "styling": "Tailwind CSS"
+    },
+    "testing": {
+      "e2e": "Playwright MCP (browser_* tools)",
+      "backend_unit": "Jest (NestJS 내장)",
+      "frontend_unit": "Vitest"
+    }
+  }
+}

package/assets/templates/progress.txt.template

@@ -0,0 +1,15 @@
+# Harness Progress Log
+# 세션 간 상태 전달을 위한 진행 기록 파일
+# ─────────────────────────────────────────────────
+
+## [{{DATE}}] Harness Initialized
+- walwal-harness 설치 완료
+- 6-Agent 아키텍처 (Dispatcher → Planner → Gen-BE → Gen-FE → Eval-Func → Eval-Visual)
+- Gotcha 관리 시스템 활성화
+
+## Current State
+- Phase: INIT (Dispatcher 실행 대기)
+- Active Sprint: none
+- Features Completed: 0 / 0
+- Blocking Issues: none
+- Next Action: "하네스 엔지니어링 시작"으로 Dispatcher 실행

package/bin/init.js

@@ -0,0 +1,281 @@
+#!/usr/bin/env node
+
+/**
+ * walwal-harness initializer
+ *
+ * Usage:
+ *   npx walwal-harness          # Interactive init
+ *   npx walwal-harness --auto   # Auto init (postinstall)
+ *   npx walwal-harness --force  # Force reinit
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const PROJECT_ROOT = process.cwd();
+const PKG_ROOT = path.resolve(__dirname, '..');
+const HARNESS_DIR = path.join(PROJECT_ROOT, '.harness');
+const CLAUDE_SKILLS_DIR = path.join(PROJECT_ROOT, '.claude', 'skills');
+
+const isAuto = process.argv.includes('--auto');
+const isForce = process.argv.includes('--force');
+
+// ─────────────────────────────────────────
+// Utility
+// ─────────────────────────────────────────
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+function copyFile(src, dest) {
+  ensureDir(path.dirname(dest));
+  fs.copyFileSync(src, dest);
+}
+
+function copyDir(src, dest) {
+  ensureDir(dest);
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      copyFile(srcPath, destPath);
+    }
+  }
+}
+
+function fileExists(p) {
+  return fs.existsSync(p);
+}
+
+function log(msg) {
+  console.log(`[walwal-harness] ${msg}`);
+}
+
+// ─────────────────────────────────────────
+// 1. .harness/ scaffolding
+// ─────────────────────────────────────────
+function scaffoldHarness() {
+  log('Scaffolding .harness/ directory...');
+
+  // Core directories
+  ensureDir(path.join(HARNESS_DIR, 'actions'));
+  ensureDir(path.join(HARNESS_DIR, 'archive'));
+  ensureDir(path.join(HARNESS_DIR, 'gotchas'));
+
+  // Copy gotchas initial files
+  const gotchasSrc = path.join(PKG_ROOT, 'gotchas');
+  if (fs.existsSync(gotchasSrc)) {
+    const files = fs.readdirSync(gotchasSrc);
+    for (const file of files) {
+      const dest = path.join(HARNESS_DIR, 'gotchas', file);
+      if (!fileExists(dest) || isForce) {
+        copyFile(path.join(gotchasSrc, file), dest);
+      }
+    }
+  }
+
+  // Copy templates as initial files
+  const templateMap = {
+    'progress.txt.template': path.join(HARNESS_DIR, 'progress.txt'),
+  };
+
+  const templatesDir = path.join(PKG_ROOT, 'assets', 'templates');
+  if (fs.existsSync(templatesDir)) {
+    for (const [template, dest] of Object.entries(templateMap)) {
+      const src = path.join(templatesDir, template);
+      if (fs.existsSync(src) && (!fileExists(dest) || isForce)) {
+        let content = fs.readFileSync(src, 'utf8');
+        content = content.replace(/\{\{DATE\}\}/g, new Date().toISOString().split('T')[0]);
+        fs.writeFileSync(dest, content);
+      }
+    }
+  }
+
+  // Copy config.json
+  const configSrc = path.join(PKG_ROOT, 'assets', 'templates', 'config.json');
+  const configDest = path.join(HARNESS_DIR, 'config.json');
+  if (fs.existsSync(configSrc) && (!fileExists(configDest) || isForce)) {
+    copyFile(configSrc, configDest);
+  }
+
+  // Copy HARNESS.md
+  const harnessMdSrc = path.join(PKG_ROOT, 'assets', 'templates', 'HARNESS.md');
+  const harnessMdDest = path.join(HARNESS_DIR, 'HARNESS.md');
+  if (fs.existsSync(harnessMdSrc) && (!fileExists(harnessMdDest) || isForce)) {
+    copyFile(harnessMdSrc, harnessMdDest);
+  }
+
+  log('.harness/ scaffolding complete');
+}
+
+// ─────────────────────────────────────────
+// 2. Skills → .claude/skills/
+// ─────────────────────────────────────────
+function installSkills() {
+  log('Installing skills to .claude/skills/...');
+
+  const skillsSrc = path.join(PKG_ROOT, 'skills');
+  if (!fs.existsSync(skillsSrc)) {
+    log('WARNING: skills/ directory not found in package');
+    return;
+  }
+
+  const skills = fs.readdirSync(skillsSrc, { withFileTypes: true })
+    .filter(d => d.isDirectory())
+    .map(d => d.name);
+
+  for (const skill of skills) {
+    const src = path.join(skillsSrc, skill);
+    const dest = path.join(CLAUDE_SKILLS_DIR, `harness-${skill}`);
+
+    if (!fileExists(dest) || isForce) {
+      copyDir(src, dest);
+      log(`  Installed: harness-${skill}`);
+    } else {
+      log(`  Skipped (exists): harness-${skill}`);
+    }
+  }
+
+  log('Skills installation complete');
+}
+
+// ─────────────────────────────────────────
+// 3. Scripts
+// ─────────────────────────────────────────
+function installScripts() {
+  log('Installing scripts...');
+
+  const scriptsSrc = path.join(PKG_ROOT, 'scripts');
+  const scriptsDest = path.join(PROJECT_ROOT, 'scripts');
+
+  if (fs.existsSync(scriptsSrc)) {
+    ensureDir(scriptsDest);
+    const files = fs.readdirSync(scriptsSrc);
+    for (const file of files) {
+      const dest = path.join(scriptsDest, file);
+      if (!fileExists(dest) || isForce) {
+        copyFile(path.join(scriptsSrc, file), dest);
+        try { fs.chmodSync(dest, '755'); } catch (e) {}
+      }
+    }
+  }
+
+  log('Scripts installation complete');
+}
+
+// ─────────────────────────────────────────
+// 4. AGENTS.md + CLAUDE.md
+// ─────────────────────────────────────────
+function setupAgentsMd() {
+  const agentsMd = path.join(PROJECT_ROOT, 'AGENTS.md');
+  const claudeMd = path.join(PROJECT_ROOT, 'CLAUDE.md');
+
+  // Run scan if no AGENTS.md
+  if (!fileExists(agentsMd) || isForce) {
+    log('Running project scan...');
+    try {
+      execSync(`bash "${path.join(PKG_ROOT, 'scripts', 'scan-project.sh')}" "${PROJECT_ROOT}"`, {
+        stdio: 'inherit'
+      });
+      execSync(`bash "${path.join(PKG_ROOT, 'scripts', 'init-agents-md.sh')}" "${PROJECT_ROOT}"`, {
+        stdio: 'inherit'
+      });
+    } catch (e) {
+      log('WARNING: Auto-scan failed. Run manually: bash scripts/scan-project.sh .');
+      // Create minimal AGENTS.md
+      const templateSrc = path.join(PKG_ROOT, 'assets', 'templates', 'AGENTS.md.template');
+      if (fs.existsSync(templateSrc)) {
+        let content = fs.readFileSync(templateSrc, 'utf8');
+        content = content.replace(/\{\{DATE\}\}/g, new Date().toISOString().split('T')[0]);
+        fs.writeFileSync(agentsMd, content);
+      }
+    }
+  }
+
+  // Ensure CLAUDE.md symlink
+  if (fileExists(agentsMd)) {
+    try {
+      const stat = fs.lstatSync(claudeMd);
+      if (!stat.isSymbolicLink()) {
+        // Backup existing CLAUDE.md
+        const backupDir = path.join(HARNESS_DIR, 'archive', 'pre-harness-backup');
+        ensureDir(backupDir);
+        fs.copyFileSync(claudeMd, path.join(backupDir, `CLAUDE.md.${Date.now()}.bak`));
+        fs.unlinkSync(claudeMd);
+        fs.symlinkSync('AGENTS.md', claudeMd);
+        log('CLAUDE.md backed up and replaced with symlink → AGENTS.md');
+      }
+    } catch (e) {
+      // CLAUDE.md doesn't exist
+      try {
+        fs.symlinkSync('AGENTS.md', claudeMd);
+        log('Created symlink: CLAUDE.md → AGENTS.md');
+      } catch (e2) {}
+    }
+  }
+}
+
+// ─────────────────────────────────────────
+// 5. Playwright MCP check
+// ─────────────────────────────────────────
+function checkPlaywrightMcp() {
+  const mcpJson = path.join(require('os').homedir(), '.mcp.json');
+
+  if (fileExists(mcpJson)) {
+    try {
+      const config = JSON.parse(fs.readFileSync(mcpJson, 'utf8'));
+      if (config.mcpServers && config.mcpServers.playwright) {
+        log('Playwright MCP: already configured');
+        return;
+      }
+    } catch (e) {}
+  }
+
+  log('');
+  log('NOTE: Playwright MCP is not configured.');
+  log('Evaluator agents require Playwright MCP for browser testing.');
+  log('Add to ~/.mcp.json:');
+  log('');
+  log('  {');
+  log('    "mcpServers": {');
+  log('      "playwright": {');
+  log('        "command": "npx",');
+  log('        "args": ["-y", "@playwright/mcp@latest", "--headless", "--caps", "vision"]');
+  log('      }');
+  log('    }');
+  log('  }');
+  log('');
+}
+
+// ─────────────────────────────────────────
+// Main
+// ─────────────────────────────────────────
+function main() {
+  console.log('');
+  console.log('╔══════════════════════════════════════╗');
+  console.log('║     walwal-harness v1.0.0            ║');
+  console.log('║     AI Agent Harness Engineering     ║');
+  console.log('╚══════════════════════════════════════╝');
+  console.log('');
+
+  scaffoldHarness();
+  installSkills();
+  installScripts();
+  setupAgentsMd();
+  checkPlaywrightMcp();
+
+  console.log('');
+  log('═══ Initialization Complete ═══');
+  log('');
+  log('Start with: "하네스 엔지니어링 시작"');
+  log('Or invoke:  /harness-dispatcher');
+  console.log('');
+}
+
+main();

package/gotchas/README.md

@@ -0,0 +1,37 @@
+# Gotchas — Agent Mistake Registry
+
+> 이 디렉토리는 각 에이전트가 반복하는 실수를 누적 기록합니다.
+> Dispatcher가 사용자의 실수 지적을 감지하면 해당 에이전트의 gotchas 파일에 추가합니다.
+> 각 에이전트는 세션 시작 시 자신의 gotchas 파일을 읽고 같은 실수를 반복하지 않습니다.
+
+## 파일 구조
+
+```
+.harness/gotchas/
+├── README.md                      # 이 파일
+├── planner.md                     # Planner의 반복 실수
+├── generator-backend.md           # Generator-Backend의 반복 실수
+├── generator-frontend.md          # Generator-Frontend의 반복 실수
+├── evaluator-functional.md        # Evaluator-Functional의 반복 실수
+└── evaluator-visual.md            # Evaluator-Visual의 반복 실수
+```
+
+## 항목 형식
+
+```markdown
+### [G-NNN] 간결한 제목
+- **Date**: YYYY-MM-DD
+- **Trigger**: 사용자가 한 말 (원문 요약)
+- **Wrong**: 에이전트가 했던 잘못된 행동
+- **Right**: 올바른 행동
+- **Why**: 왜 잘못인지 근거
+- **Scope**: 이 규칙이 적용되는 조건/범위
+```
+
+## 관리 규칙
+
+- Dispatcher만 gotchas 파일에 쓰기 가능
+- 각 에이전트는 자신의 gotchas 파일을 읽기 전용으로 참조
+- 중복 항목 금지 — 같은 실수는 기존 항목에 횟수 증가
+- 해결된 항목은 삭제하지 않고 `[RESOLVED]` 태그 추가
+- 항목이 20개 초과 시 가장 오래된 RESOLVED 항목부터 정리

package/gotchas/evaluator-functional.md

@@ -0,0 +1,5 @@
+# Gotchas — Evaluator-Functional
+
+> Dispatcher가 관리. Evaluator-Functional은 세션 시작 시 이 파일을 읽고 같은 실수를 반복하지 않습니다.
+
+<!-- 항목이 추가되면 아래에 기록됩니다 -->

package/gotchas/evaluator-visual.md

@@ -0,0 +1,5 @@
+# Gotchas — Evaluator-Visual
+
+> Dispatcher가 관리. Evaluator-Visual은 세션 시작 시 이 파일을 읽고 같은 실수를 반복하지 않습니다.
+
+<!-- 항목이 추가되면 아래에 기록됩니다 -->

package/gotchas/generator-backend.md

@@ -0,0 +1,5 @@
+# Gotchas — Generator-Backend
+
+> Dispatcher가 관리. Generator-Backend는 세션 시작 시 이 파일을 읽고 같은 실수를 반복하지 않습니다.
+
+<!-- 항목이 추가되면 아래에 기록됩니다 -->

package/gotchas/generator-frontend.md

@@ -0,0 +1,5 @@
+# Gotchas — Generator-Frontend
+
+> Dispatcher가 관리. Generator-Frontend는 세션 시작 시 이 파일을 읽고 같은 실수를 반복하지 않습니다.
+
+<!-- 항목이 추가되면 아래에 기록됩니다 -->