@walwal-harness/cli 2.0.1 → 2.3.1

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` (실행은 선택)

package/skills/brainstorming/references/attribution.md

@@ -0,0 +1,109 @@
+---
+docmeta:
+  id: brainstorming-attribution
+  title: Brainstorming Skill — Attribution & Original Source
+  type: output
+  createdAt: 2026-04-09T00:00:00Z
+  updatedAt: 2026-04-09T00:00:00Z
+  source:
+    producer: agent
+    skillId: harness-brainstorming
+  inputs:
+    - documentId: obra-superpowers-brainstorming-skill
+      uri: https://github.com/obra/superpowers/blob/main/skills/brainstorming/SKILL.md
+      relation: output-from
+      sections:
+        - sourceRange:
+            startLine: 1
+            endLine: 165
+          targetRange:
+            startLine: 21
+            endLine: 32
+        - sourceRange:
+            startLine: 29
+            endLine: 33
+          targetRange:
+            startLine: 36
+            endLine: 42
+        - sourceRange:
+            startLine: 12
+            endLine: 18
+          targetRange:
+            startLine: 55
+            endLine: 62
+    - documentId: obra-superpowers-spec-reviewer
+      uri: https://github.com/obra/superpowers/blob/main/skills/brainstorming/spec-document-reviewer-prompt.md
+      relation: output-from
+      sections:
+        - sourceRange:
+            startLine: 1
+            endLine: 50
+          targetRange:
+            startLine: 23
+            endLine: 24
+    - documentId: obra-superpowers-visual-companion
+      uri: https://github.com/obra/superpowers/blob/main/skills/brainstorming/visual-companion.md
+      relation: output-from
+      sections:
+        - sourceRange:
+            startLine: 1
+            endLine: 287
+          targetRange:
+            startLine: 25
+            endLine: 27
+  tags: [attribution, license, mit, obra-superpowers]
+---
+
+# Attribution — obra/superpowers brainstorming skill
+
+walwal-harness 의 `harness-brainstorming` 스킬은 아래 원본을 기반으로
+파이프라인 통합(Session Boundary Protocol, Planner 인터페이스, 출력 경로 등)을
+추가한 파생 저작물입니다.
+
+## 원본
+
+- **Repo**: [obra/superpowers](https://github.com/obra/superpowers)
+- **Path**: `skills/brainstorming/`
+- **Files reused**:
+  - `SKILL.md` — 방법론 (HARD-GATE, 한 번에 한 질문, 2-3 접근법, spec self-review)
+  - `spec-document-reviewer-prompt.md` — spec 리뷰 서브에이전트 프롬프트 템플릿
+  - `visual-companion.md` — 브라우저 기반 시각 도우미 가이드
+  - `scripts/frame-template.html`, `helper.js`, `server.cjs`, `start-server.sh`, `stop-server.sh` — visual companion 서버 구현
+- **License**: MIT License
+
+## 변경점 (walwal-harness 통합)
+
+1. **Session Boundary Protocol 추가** — On Start / On Complete / On Fail 프로토콜로
+   harness 다중 에이전트 흐름에 맞춤
+2. **Terminal state 변경** — 원본의 "invoke writing-plans skill" → "hand off to
+   harness-planner"
+3. **출력 경로 변경** — 원본의 `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
+   → `.harness/actions/brainstorm-spec.md` (Planner 의 입력 위치)
+4. **출력 포맷 변경** — walwal-harness docmeta 프론트매터 + Planner 가 사용하는
+   12 개 섹션 (목적/성공기준/스코프/제약/접근법/아키텍처/컴포넌트/데이터흐름/
+   에러처리/테스트전략/Open Questions/승인로그) 로 구조화
+5. **조건부 호출** — 원본은 "모든 창작 작업 전 필수" 였으나, harness 에서는 Dispatcher 가
+   사용자에게 "브레인스토밍 필요?" 확인 후에만 호출 (피드백/이터레이션 케이스에서
+   피로 최소화)
+6. **Skip 로직** — 기존 brainstorm-spec.md 존재 시 재사용 여부 확인
+
+## 보존된 핵심
+
+- HARD-GATE (구현 전 디자인 필수)
+- "Too simple to need a design" 안티패턴 경고
+- 한 번에 한 질문 원칙
+- 객관식 우선
+- 2-3 개 접근법 탐색
+- YAGNI
+- Spec self-review loop
+- User review gate
+- Visual Companion 옵션
+
+## MIT License
+
+원본 저장소 [obra/superpowers](https://github.com/obra/superpowers) 의 MIT License
+전문은 아래 링크에서 확인할 수 있습니다:
+https://github.com/obra/superpowers/blob/main/LICENSE
+
+MIT License 하에 원본 저작권 표시 및 라이센스 고지 의무를 이 파일로 대체합니다.
+파생물 배포 시에도 이 attribution 파일을 유지해야 합니다.

package/skills/brainstorming/references/spec-document-reviewer-prompt.md

@@ -0,0 +1,49 @@
+# Spec Document Reviewer Prompt Template
+
+Use this template when dispatching a spec document reviewer subagent.
+
+**Purpose:** Verify the spec is complete, consistent, and ready for implementation planning.
+
+**Dispatch after:** Spec document is written to docs/superpowers/specs/
+
+```
+Task tool (general-purpose):
+  description: "Review spec document"
+  prompt: |
+    You are a spec document reviewer. Verify this spec is complete and ready for planning.
+
+    **Spec to review:** [SPEC_FILE_PATH]
+
+    ## What to Check
+
+    | Category | What to Look For |
+    |----------|------------------|
+    | Completeness | TODOs, placeholders, "TBD", incomplete sections |
+    | Consistency | Internal contradictions, conflicting requirements |
+    | Clarity | Requirements ambiguous enough to cause someone to build the wrong thing |
+    | Scope | Focused enough for a single plan — not covering multiple independent subsystems |
+    | YAGNI | Unrequested features, over-engineering |
+
+    ## Calibration
+
+    **Only flag issues that would cause real problems during implementation planning.**
+    A missing section, a contradiction, or a requirement so ambiguous it could be
+    interpreted two different ways — those are issues. Minor wording improvements,
+    stylistic preferences, and "sections less detailed than others" are not.
+
+    Approve unless there are serious gaps that would lead to a flawed plan.
+
+    ## Output Format
+
+    ## Spec Review
+
+    **Status:** Approved | Issues Found
+
+    **Issues (if any):**
+    - [Section X]: [specific issue] - [why it matters for planning]
+
+    **Recommendations (advisory, do not block approval):**
+    - [suggestions for improvement]
+```
+
+**Reviewer returns:** Status, Issues (if any), Recommendations