@walwal-harness/cli 2.0.1 → 2.3.0

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.0",
+  "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": "",

package/scripts/harness-next.sh

@@ -18,6 +18,7 @@ PROJECT_ROOT="$(resolve_harness_root "${1:-.}")" || {
 
 PROGRESS="$PROJECT_ROOT/.harness/progress.json"
 CONFIG="$PROJECT_ROOT/.harness/config.json"
+PIPELINE_JSON="$PROJECT_ROOT/.harness/actions/pipeline.json"
 NEXT_PROMPT="$PROJECT_ROOT/.harness/next-prompt.txt"
 
 check_jq || exit 1
@@ -40,6 +41,29 @@ next_agent=$(jq -r '.next_agent // "null"' "$PROGRESS")
 retry_count=$(jq -r '.sprint.retry_count // 0' "$PROGRESS")
 max_retries=$(jq -r '.flow.max_retries_per_sprint // 10' "$CONFIG" 2>/dev/null || echo 10)
 
+# fe_stack 치환 (Flutter 지원) — pipeline.json 에서 읽음
+fe_stack="react"
+if [ -f "$PIPELINE_JSON" ]; then
+  fe_stack=$(jq -r '.fe_stack // "react"' "$PIPELINE_JSON" 2>/dev/null || echo "react")
+fi
+
+# ─────────────────────────────────────────
+# fe_stack 치환 헬퍼
+#   pipeline_selection.pipelines에서 읽은 에이전트명을 fe_stack에 따라 치환
+#   - react: 그대로
+#   - flutter: generator-frontend → generator-frontend-flutter 등, __skip__ 은 건너뜀
+# ─────────────────────────────────────────
+substitute_fe_stack() {
+  local agent="$1"
+  if [ "$fe_stack" != "flutter" ]; then
+    echo "$agent"
+    return
+  fi
+  local sub
+  sub=$(jq -r ".flow.pipeline_selection.fe_stack_substitution.flutter[\"${agent}\"] // \"${agent}\"" "$CONFIG" 2>/dev/null)
+  echo "$sub"
+}
+
 # ─────────────────────────────────────────
 # Determine next agent
 # ─────────────────────────────────────────
@@ -73,8 +97,18 @@ compute_next_agent() {
     return
   fi
 
+  local -a raw_agents
+  mapfile -t raw_agents < <(jq -r ".flow.pipeline_selection.pipelines[\"${pipeline}\"][]" "$CONFIG" 2>/dev/null | sed 's/:.*//')
+
+  # fe_stack 치환 + __skip__ 필터링
   local -a agents
-  mapfile -t agents < <(jq -r ".flow.pipeline_selection.pipelines[\"${pipeline}\"][]" "$CONFIG" 2>/dev/null | sed 's/:.*//')
+  for a in "${raw_agents[@]}"; do
+    local sub
+    sub=$(substitute_fe_stack "$a")
+    if [ "$sub" != "__skip__" ]; then
+      agents+=("$sub")
+    fi
+  done
 
   local found=false
   for agent in "${agents[@]}"; do
@@ -82,6 +116,7 @@ compute_next_agent() {
       echo "$agent"
       return
     fi
+    # current 비교 시에도 치환된 이름으로 (Flutter 변형 에이전트가 실행되는 경우)
     if [ "$agent" = "$current" ]; then
       found=true
     fi

package/scripts/harness-user-prompt-submit.sh

@@ -0,0 +1,106 @@
+#!/bin/bash
+# harness-user-prompt-submit.sh
+# ─────────────────────────────────────────
+# Claude Code UserPromptSubmit hook
+# 모든 사용자 프롬프트를 harness-dispatcher 로 라우팅하도록 Claude 에게
+# 지시하는 컨텍스트를 stdout 에 주입한다.
+#
+# 활성 조건:
+#   1) 현재 cwd 에 .harness/config.json 존재
+#   2) .harness/config.json 의 behavior.auto_route_dispatcher != false
+#
+# 비활성 상황에서는 아무것도 출력하지 않고 exit 0 (pass-through).
+# ─────────────────────────────────────────
+set -e
+
+# stdin 의 JSON payload 읽기 (Claude Code 가 {prompt, cwd, session_id, ...} 전달)
+INPUT=$(cat)
+
+# cwd 추출 (payload 에 없으면 PWD fallback)
+CWD=$(echo "$INPUT" | jq -r '.cwd // empty' 2>/dev/null || true)
+if [ -z "$CWD" ]; then
+  CWD="$PWD"
+fi
+
+# 조건 1: 하네스 초기화 확인
+if [ ! -f "$CWD/.harness/config.json" ]; then
+  exit 0
+fi
+
+# 조건 2: opt-out 플래그 확인 (기본값 true)
+AUTO_ROUTE="true"
+if command -v jq >/dev/null 2>&1; then
+  AUTO_ROUTE=$(jq -r '.behavior.auto_route_dispatcher // true' "$CWD/.harness/config.json" 2>/dev/null || echo "true")
+fi
+if [ "$AUTO_ROUTE" != "true" ]; then
+  exit 0
+fi
+
+# 프롬프트 내용 추출 (opt-out 문구 감지용)
+PROMPT=$(echo "$INPUT" | jq -r '.prompt // empty' 2>/dev/null || true)
+# 사용자가 명시적으로 건너뛰기 요청하면 pass-through
+if echo "$PROMPT" | grep -qiE "harness\s*(skip|off|bypass|없이)|without\s*harness|just\s*(answer|chat|reply)"; then
+  exit 0
+fi
+
+# 현재 세션 상태 읽기
+PIPELINE="none"
+CURRENT_AGENT="none"
+NEXT_AGENT="none"
+SPRINT_NUM="0"
+SPRINT_STATUS="init"
+FE_STACK="react"
+
+if [ -f "$CWD/.harness/progress.json" ] && command -v jq >/dev/null 2>&1; then
+  PIPELINE=$(jq -r '.pipeline // "none"' "$CWD/.harness/progress.json" 2>/dev/null || echo "none")
+  CURRENT_AGENT=$(jq -r '.current_agent // "none"' "$CWD/.harness/progress.json" 2>/dev/null || echo "none")
+  NEXT_AGENT=$(jq -r '.next_agent // "none"' "$CWD/.harness/progress.json" 2>/dev/null || echo "none")
+  SPRINT_NUM=$(jq -r '.sprint.number // 0' "$CWD/.harness/progress.json" 2>/dev/null || echo "0")
+  SPRINT_STATUS=$(jq -r '.sprint.status // "init"' "$CWD/.harness/progress.json" 2>/dev/null || echo "init")
+fi
+
+if [ -f "$CWD/.harness/actions/pipeline.json" ] && command -v jq >/dev/null 2>&1; then
+  FE_STACK=$(jq -r '.fe_stack // "react"' "$CWD/.harness/actions/pipeline.json" 2>/dev/null || echo "react")
+fi
+
+# ─────────────────────────────────────────
+# Context 주입 (stdout → Claude 컨텍스트)
+# ─────────────────────────────────────────
+cat <<EOF
+[walwal-harness] Auto-routing is ACTIVE for this project.
+
+이 프로젝트는 walwal-harness 가 초기화되어 있으며, auto_route_dispatcher 플래그가
+켜져 있습니다. 사용자의 모든 프롬프트는 **harness-dispatcher** 스킬을 통해
+분류/라우팅된 뒤 처리되어야 합니다.
+
+## 분류 규칙 (Dispatcher Request Classification)
+- **기능 요청** (만들어줘, 추가, 고쳐줘, PRD, OpenAPI) → Pipeline Flow
+- **실수 지적** (아니, 잘못됐어, 그렇게 하면 안 돼, X로 해야지) → Gotcha Flow
+- **혼합** → Gotcha 먼저 기록 → Pipeline 이어서
+- **메타/인사/Claude 자체 질문** → 짧게 일반 응답 (dispatcher skip 허용)
+
+## 현재 harness 세션 상태
+- pipeline: $PIPELINE
+- current_agent: $CURRENT_AGENT
+- next_agent: $NEXT_AGENT
+- sprint: $SPRINT_NUM ($SPRINT_STATUS)
+- fe_stack: $FE_STACK
+
+## 지시
+1. 먼저 위 상태를 읽고, 사용자 메시지가 어떤 분류에 해당하는지 판단
+2. **pipeline 이 'none' 또는 dispatcher 미실행 상태**면 harness-dispatcher 스킬 호출
+3. **pipeline 이 이미 활성**이면:
+   - 실수 지적이면 → dispatcher 로 gotcha 기록
+   - 기능 연속 작업이면 → next_agent 또는 current_agent 의 컨텍스트로 계속
+4. 응답 전 반드시 \`.harness/progress.json\` 을 읽고 세션 경계 프로토콜 준수
+
+## 이 라우팅을 건너뛰려면
+- **단일 메시지**: 사용자가 "harness skip", "without harness", "harness 없이", "just answer" 등을 명시
+- **전역 비활성**: \`.harness/config.json\` 에서 \`behavior.auto_route_dispatcher = false\` 설정
+
+## 참고
+이 안내는 \`scripts/harness-user-prompt-submit.sh\` UserPromptSubmit 훅에 의해
+매 프롬프트마다 자동 주입됩니다. 중복 안내처럼 보여도 무시하지 말고 위 규칙을 따르세요.
+EOF
+
+exit 0

package/scripts/lib/harness-render-progress.sh

@@ -282,12 +282,17 @@ render_progress() {
 render_agent_bar() {
   local PROGRESS="${1:-.}/.harness/progress.json"
   local CONFIG="${1:-.}/.harness/config.json"
+  local PIPELINE_JSON="${1:-.}/.harness/actions/pipeline.json"
 
   if [ ! -f "$PROGRESS" ] || [ ! -f "$CONFIG" ]; then return 1; fi
 
-  local pipeline current_agent
+  local pipeline current_agent fe_stack
   pipeline=$(jq -r '.pipeline // "unknown"' "$PROGRESS")
   current_agent=$(jq -r '.current_agent // "none"' "$PROGRESS")
+  fe_stack="react"
+  if [ -f "$PIPELINE_JSON" ]; then
+    fe_stack=$(jq -r '.fe_stack // "react"' "$PIPELINE_JSON" 2>/dev/null || echo "react")
+  fi
 
   local completed_agents
   completed_agents=$(jq -r '.completed_agents // [] | .[]' "$PROGRESS")
@@ -299,6 +304,15 @@ render_agent_bar() {
 
   while IFS= read -r agent; do
     agent=$(echo "$agent" | sed 's/:.*//')  # strip mode suffix like :light, :api-only
+
+    # fe_stack 치환 적용
+    if [ "$fe_stack" = "flutter" ]; then
+      local sub
+      sub=$(jq -r ".flow.pipeline_selection.fe_stack_substitution.flutter[\"${agent}\"] // \"${agent}\"" "$CONFIG" 2>/dev/null)
+      if [ "$sub" = "__skip__" ]; then continue; fi
+      agent="$sub"
+    fi
+
     if [ "$first" = true ]; then
       first=false
     else

package/scripts/scan-project.sh

@@ -61,7 +61,13 @@ elif [ -f "${PROJECT_ROOT}/pom.xml" ] || [ -f "${PROJECT_ROOT}/build.gradle" ];
 fi
 
 # Frontend
-if [ -f "${PROJECT_ROOT}/next.config.js" ] || [ -f "${PROJECT_ROOT}/next.config.ts" ] || [ -f "${PROJECT_ROOT}/next.config.mjs" ]; then
+# Flutter 우선 감지 — pubspec.yaml 존재하면 Flutter 프로젝트로 판정 (TECH_LANG도 보정)
+FE_STACK="react"  # react | flutter (기본값은 react 계열)
+if [ -f "${PROJECT_ROOT}/pubspec.yaml" ] && grep -q "flutter:" "${PROJECT_ROOT}/pubspec.yaml" 2>/dev/null; then
+  TECH_FRONTEND="flutter"
+  TECH_LANG="dart"
+  FE_STACK="flutter"
+elif [ -f "${PROJECT_ROOT}/next.config.js" ] || [ -f "${PROJECT_ROOT}/next.config.ts" ] || [ -f "${PROJECT_ROOT}/next.config.mjs" ]; then
   TECH_FRONTEND="nextjs"
 elif [ -f "${PROJECT_ROOT}/vite.config.ts" ] || [ -f "${PROJECT_ROOT}/vite.config.js" ]; then
   TECH_FRONTEND="vite-react"
@@ -75,11 +81,26 @@ fi
 if [ -d "${PROJECT_ROOT}/apps/web" ]; then
   if [ -f "${PROJECT_ROOT}/apps/web/next.config.js" ] || [ -f "${PROJECT_ROOT}/apps/web/next.config.ts" ]; then
     TECH_FRONTEND="nextjs"
+    FE_STACK="react"
   elif [ -f "${PROJECT_ROOT}/apps/web/vite.config.ts" ]; then
     TECH_FRONTEND="vite-react"
+    FE_STACK="react"
   fi
 fi
 
+# Flutter 서브디렉토리 감지 (monorepo 또는 서브 프로젝트 케이스)
+if [ "$TECH_FRONTEND" = "unknown" ]; then
+  # 대표적인 Flutter 서브폴더 이름을 얕게 탐색
+  for d in apps/mobile mobile clue_mobile_app flutter_app; do
+    if [ -f "${PROJECT_ROOT}/${d}/pubspec.yaml" ] && grep -q "flutter:" "${PROJECT_ROOT}/${d}/pubspec.yaml" 2>/dev/null; then
+      TECH_FRONTEND="flutter"
+      TECH_LANG="dart"
+      FE_STACK="flutter"
+      break
+    fi
+  done
+fi
+
 # Database
 if grep -rq "typeorm\|prisma\|sequelize\|knex" "${PROJECT_ROOT}/package.json" 2>/dev/null; then
   if grep -q "pg\|postgres" "${PROJECT_ROOT}/package.json" 2>/dev/null; then
@@ -203,6 +224,7 @@ cat > "$OUTPUT" << JSONEOF
   "tech_stack": {
     "backend": "${TECH_BACKEND}",
     "frontend": "${TECH_FRONTEND}",
+    "fe_stack": "${FE_STACK}",
     "database": "${TECH_DB}",
     "monorepo": "${TECH_MONOREPO}",
     "language": "${TECH_LANG}"
@@ -260,7 +282,7 @@ echo "=== Scan Complete ==="
 echo "Output: ${OUTPUT}"
 echo ""
 echo "--- Summary ---"
-echo "Tech Stack: ${TECH_BACKEND} / ${TECH_FRONTEND} / ${TECH_DB}"
+echo "Tech Stack: ${TECH_BACKEND} / ${TECH_FRONTEND} (fe_stack=${FE_STACK}) / ${TECH_DB}"
 echo "Monorepo: ${TECH_MONOREPO}"
 echo "OpenAPI: ${OPENAPI}"
 echo "Git: ${GIT_INIT} (${GIT_COMMITS} commits, branch: ${GIT_BRANCH})"

package/skills/brainstorming/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: harness-brainstorming
+description: "사용자의 러프한(바이브코딩) 요구사항을 대화형으로 구체화하여 Planner가 바로 쓸 수 있는 디자인/스펙 문서(.harness/actions/brainstorm-spec.md)로 만든다. Dispatcher가 사용자에게 '브레인스토밍 필요?' 라고 확인한 뒤에만 호출된다. 원본: obra/superpowers MIT."
+disable-model-invocation: true
+---
+
+# Brainstormer — 요구사항 구체화 (obra/superpowers 파생)
+
+> **Attribution**: 이 스킬의 방법론은 [obra/superpowers](https://github.com/obra/superpowers)
+> (MIT License) 의 `skills/brainstorming` 을 walwal-harness 파이프라인에 맞게 이식한 것입니다.
+> 원본 저자(J. Hubbard 등)에게 감사드립니다. 상세 원본 텍스트 + 라이센스는
+> [references/attribution.md](references/attribution.md) 참조.
+
+## 역할
+
+walwal-harness 에서 Brainstormer 의 유일한 목적은 **러프한 바이브코딩 아이디어를
+Planner 가 곧바로 plan.md / feature-list.json / api-contract.json 으로 변환할 수 있는
+수준의 fit 한 요구사항 문서**로 구체화하는 것이다. 결과물은 단 하나:
+
+```
+.harness/actions/brainstorm-spec.md
+```
+
+이 파일이 생성되면 Planner 는 이것을 PRD 대체 입력으로 읽는다.
+
+## 언제 호출되는가
+
+**Dispatcher 가 사용자에게 명시적으로 "브레인스토밍 과정이 필요합니까?" 라고 묻고
+사용자가 승인한 경우에만 실행된다.** 이외의 모든 경로 (피드백, 이터레이션, 직접 에이전트
+명령, Gotcha 교정, 스프린트 retry) 에서는 호출되지 않는다. 사용자가 명확한 PRD 를
+제공하거나 브레인스토밍 불필요를 선언하면 Dispatcher 는 곧바로 `next_agent = planner`
+로 라우팅한다.
+
+## Session Boundary Protocol
+
+### On Start
+1. `.harness/progress.json` 읽기 — `next_agent == "brainstormer"` 인지 확인
+   - 아니면 즉시 STOP + "Dispatcher 를 먼저 실행하세요" 안내
+2. progress.json 업데이트: `current_agent` → `"brainstormer"`, `agent_status` → `"running"`, `updated_at` 갱신
+3. **Skip 조건 검사**: `.harness/actions/brainstorm-spec.md` 가 이미 존재하고
+   사용자가 "새로 브레인스토밍" 을 명시하지 않았다면:
+   - 사용자에게 "기존 brainstorm-spec.md 가 있습니다. 재사용(Y) / 새로 작성(N)?" 질문
+   - Y → 즉시 On Complete 로 이동 (interactive 단계 전부 스킵)
+   - N → 기존 파일을 `.harness/archive/brainstorm-spec-<timestamp>.md` 로 이동 후 interactive 시작
+
+### On Complete
+1. `.harness/actions/brainstorm-spec.md` 가 존재하고 "User Review Gate" 를 통과했는지 확인
+2. progress.json 업데이트:
+   - `agent_status` → `"completed"`
+   - `completed_agents` 에 `"brainstormer"` 추가
+   - `next_agent` → `"planner"`
+3. `.harness/progress.log` 에 요약 추가: `Brainstormer → Planner (spec: <경로>)`
+4. **STOP. 다음 에이전트를 직접 호출하지 않는다.**
+5. 출력: `"✓ Brainstormer 완료. bash scripts/harness-next.sh 실행하여 Planner 단계로 진행."`
+
+### On Fail / Abort
+사용자가 중간에 "중단" / "취소" / "abort" 를 요청하면:
+1. progress.json 업데이트: `agent_status` → `"blocked"`, `failure.message` → `"user aborted brainstorming"`
+2. 작성 중이던 `brainstorm-spec.md` 는 `.harness/archive/brainstorm-spec-draft-<timestamp>.md` 로 이동
+3. **STOP**. 사용자에게 "재시작 원하면 'dispatcher 다시'" 안내
+
+## HARD-GATE (원본에서 계승)
+
+> **Planner / Generator / 어떤 구현 에이전트도 호출하지 말라. 사용자가 "이 디자인 승인한다" 고
+> 명시적으로 말하기 전까지는 brainstorm-spec.md 를 저장하지도 않는다.**
+
+아무리 간단해 보이는 프로젝트라도 이 게이트를 건너뛰지 않는다. "Simple" 한 프로젝트가
+오히려 검증되지 않은 가정 때문에 가장 많은 시간을 낭비시킨다.
+
+## 체크리스트 (Brainstormer 내부 워크플로우)
+
+각 항목을 **순서대로** 수행하고 각 단계 끝에서 사용자 확인을 받는다:
+
+1. **프로젝트 컨텍스트 탐색** — 기존 파일, docs, 최근 커밋, `AGENTS.md`, `.harness/actions/`
+2. **Visual Companion 제안** (시각 요소가 많을 예정이라면, 단일 메시지로) — [visual-companion 가이드](references/visual-companion.md)
+3. **명확화 질문** — 한 번에 **하나씩**, 목적/제약/성공 기준 파악 (가능하면 객관식)
+4. **스코프 점검** — 여러 독립 서브시스템이 섞여 있으면 먼저 분할 제안 (예: "플랫폼 A + 채팅 + 결제" → 먼저 A 만)
+5. **2~3 개 접근법 제시** — 각 접근의 장단점 + 추천안 + 추천 이유
+6. **디자인 섹션별 제시** — 복잡도에 맞춰 섹션별 길이 조절, 각 섹션 끝에 사용자 확인
+   - 아키텍처, 컴포넌트, 데이터 흐름, 에러 처리, 테스트
+7. **사용자 디자인 승인** 받기
+8. **brainstorm-spec.md 저장** — `.harness/actions/brainstorm-spec.md` 에 커밋 (아래 스펙 포맷)
+9. **Spec Self-Review** — 플레이스홀더, 모순, 애매성, 스코프, YAGNI 체크. 발견 시 inline 수정
+   상세 → [spec-document-reviewer-prompt.md](references/spec-document-reviewer-prompt.md)
+10. **User Review Gate** — 사용자에게 작성된 파일을 리뷰 요청. 변경 요청 시 → 8번으로 복귀
+11. **Planner 로 핸드오프** — Session Boundary Protocol On Complete 실행
+
+## 핵심 원칙 (원본 계승)
+
+- **한 번에 한 질문** — 질문 폭탄 금지
+- **객관식 우선** — 가능하면 A/B/C/D 형태로
+- **YAGNI** — 요청되지 않은 기능은 전부 제거
+- **대안 탐색** — 결정하기 전에 항상 2-3 개 접근법 제시
+- **점진적 검증** — 섹션별로 제시하고 승인 후 다음
+- **유연성** — 중간에 "이건 안 맞는 것 같아" 가 나오면 언제든 이전 단계로 복귀
+
+## 출력 포맷: `.harness/actions/brainstorm-spec.md`
+
+```markdown
+---
+docmeta:
+  id: brainstorm-spec
+  title: Brainstorm Spec — <프로젝트/기능 이름>
+  type: output
+  createdAt: <ISO 8601>
+  updatedAt: <ISO 8601>
+  source:
+    producer: agent
+    skillId: harness-brainstorming
+  inputs:
+    - documentId: user-conversation
+      uri: (inline — 사용자와의 대화 전체)
+      relation: output-from
+  tags: [brainstorming, spec, planner-input]
+---
+
+# Brainstorm Spec — <프로젝트/기능 이름>
+
+## 1. 목적 (Purpose)
+<무엇을, 왜 만드는가 — 1-2 문단>
+
+## 2. 성공 기준 (Success Criteria)
+- [ ] ...
+- [ ] ...
+
+## 3. 스코프 (Scope)
+### In
+- ...
+### Out (명시적 제외)
+- ...
+
+## 4. 제약 (Constraints)
+- 기술 스택:
+- 성능:
+- 보안/컴플라이언스:
+- 기타:
+
+## 5. 선택된 접근법 (Chosen Approach)
+<2-3 개 대안 중 사용자가 승인한 것 + 이유>
+
+### 고려했던 대안
+- **Alt A**: ... (장/단점)
+- **Alt B**: ... (장/단점)
+
+## 6. 아키텍처 스케치
+<구성요소 + 상호작용 — ASCII 다이어그램 또는 간단한 설명>
+
+## 7. 주요 컴포넌트 / 엔티티
+- Component A — 책임:
+- Entity X — 필드/관계:
+
+## 8. 데이터 흐름 (Data Flow)
+<입력 → 처리 → 출력 → 저장 경로>
+
+## 9. 에러 처리 전략
+- 경계 에러:
+- 내부 에러:
+- 사용자 노출 메시지:
+
+## 10. 테스트 전략 (High-level)
+- Unit:
+- Integration:
+- E2E:
+
+## 11. Open Questions (Planner 가 확정할 것)
+- Q1: ...
+- Q2: ...
+
+## 12. 사용자 승인 로그
+- YYYY-MM-DD HH:MM — 섹션 <N> 승인 ("네, 좋아요")
+- YYYY-MM-DD HH:MM — 디자인 전체 승인
+- YYYY-MM-DD HH:MM — 작성 스펙 파일 리뷰 통과
+```
+
+## Planner 와의 인터페이스
+
+Planner 는 On Start 에 이 파일을 읽고:
+
+1. `1. 목적`, `2. 성공 기준`, `3. 스코프` → `plan.md` 의 사양서 도입부로 직접 반영
+2. `5. 선택된 접근법`, `6. 아키텍처 스케치` → MSA 서비스 분할 (full 모드) 또는 컴포넌트 설계의 베이스
+3. `7. 주요 컴포넌트 / 엔티티` → `feature-list.json` 초기 feature 목록 시드
+4. `11. Open Questions` → Planner 가 해소 (API 계약으로 확정)
+
+Planner 는 brainstorm-spec.md 에 있는 **승인된 결정** 을 뒤엎지 않는다. 필요한 경우
+`## Change Request` 섹션을 추가해 Dispatcher 를 통한 재논의 요청.
+
+## 금지 사항
+
+- `brainstorm-spec.md` 승인 전에 `plan.md`, `feature-list.json`, `api-contract.json` 작성
+- 코드 작성 / scaffolding / 파일 생성 (scripts/visual-companion 제외)
+- 여러 질문을 한 메시지에 몰아 넣기
+- 사용자 승인 없이 임의로 다음 섹션으로 진행
+- `.harness/archive/` 쓰기 금지 원칙 위반 (skip/abort 시 draft 이동 외에는 금지)
+
+## 참고
+
+- 원본 방법론 + 라이센스 → [references/attribution.md](references/attribution.md)
+- Visual Companion (브라우저 기반 목업/다이어그램 서버) → [references/visual-companion.md](references/visual-companion.md)
+- Spec self-review 상세 → [references/spec-document-reviewer-prompt.md](references/spec-document-reviewer-prompt.md)
+- Visual Companion 실행 스크립트 → `scripts/start-server.sh` (실행은 선택)