@walwal-harness/cli 6.1.5 → 7.1.0

package/skills/brainstorming/SKILL.md

@@ -1,220 +0,0 @@
----
-name: harness-brainstorming
-description: "사용자의 러프한(바이브코딩) 요구사항을 대화형으로 구체화하여 Planner가 바로 쓸 수 있는 디자인/스펙 문서(.harness/actions/brainstorm-spec.md)로 만든다. Dispatcher가 사용자에게 '브레인스토밍 필요?' 라고 확인한 뒤에만 호출된다. 원본: obra/superpowers MIT."
-disable-model-invocation: false
----
-
-# 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`
-로 라우팅한다.
-
-## progress.json 업데이트 규칙 (v5.6.3+)
-
-⚠️ **절대로 progress.json 을 통째로 재작성하지 마라**. `Write` 도구로 전체 파일을
-덮어쓰면 `mode` / `company_state` / 기타 top-level 필드가 누락되어 회사모드 병렬 루프가
-끊기는 등 런타임 오류가 발생한다.
-
-**올바른 방법** — 반드시 partial update 로 갱신:
-
-```bash
-# 헬퍼 스크립트 (권장)
-bash scripts/harness-progress-set.sh . '.current_agent = "planner" | .agent_status = "running"'
-
-# 또는 직접 jq 로 partial update
-jq '.agent_status = "completed" | .completed_agents += ["planner"]'   .harness/progress.json > .harness/progress.json.tmp &&   mv .harness/progress.json.tmp .harness/progress.json
-```
-
-위 두 방식은 파일의 나머지 필드를 보존한다. Read → 수정 → Write 패턴은 사용 금지.
-
-## Session Boundary Protocol
-
-### On Start
-1. `.harness/progress.json` 읽기 — `next_agent == "brainstorming"` 인지 확인
-   - 아니면 즉시 STOP + "Dispatcher 를 먼저 실행하세요" 안내
-2. progress.json 업데이트: `current_agent` → `"brainstorming"`, `agent_status` → `"running"`, `updated_at` 갱신
-3. `.harness/memory.md` 읽기 — **프로젝트 공유 학습 규칙 적용**
-4. **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` 에 `"brainstorming"` 추가
-   - `next_agent` → `"planner"`
-3. `.harness/progress.log` 에 요약 추가: `Brainstormer → Planner (spec: <경로>)`
-4. 출력: `"✓ Brainstormer 완료. brainstorm-spec.md 검토 후 승인 신호를 주세요. 승인 시 자동 핸드오프 (Conductor 자율 시동) (Planner)."`
-5. **사용자 승인 게이트**: 사용자의 명시적 승인 ("이 디자인 승인한다", "ok", "다음", "Planner 가자" 등) 을 기다린 후, **내부 핸드오프 (scripts/harness-next.sh) 를 호출하여 Planner 로 자동 핸드오프**.
-6. 사용자가 피드백/수정 요청을 하면 brainstorm-spec.md 를 갱신하고 다시 승인 요청. 승인 없이는 `/harness-next` 호출 금지 (HARD-GATE 준수).
-
-### 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

@@ -1,109 +0,0 @@
----
-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

@@ -1,49 +0,0 @@
-# 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

package/skills/brainstorming/references/visual-companion.md

@@ -1,287 +0,0 @@
-# Visual Companion Guide
-
-Browser-based visual brainstorming companion for showing mockups, diagrams, and options.
-
-## When to Use
-
-Decide per-question, not per-session. The test: **would the user understand this better by seeing it than reading it?**
-
-**Use the browser** when the content itself is visual:
-
-- **UI mockups** — wireframes, layouts, navigation structures, component designs
-- **Architecture diagrams** — system components, data flow, relationship maps
-- **Side-by-side visual comparisons** — comparing two layouts, two color schemes, two design directions
-- **Design polish** — when the question is about look and feel, spacing, visual hierarchy
-- **Spatial relationships** — state machines, flowcharts, entity relationships rendered as diagrams
-
-**Use the terminal** when the content is text or tabular:
-
-- **Requirements and scope questions** — "what does X mean?", "which features are in scope?"
-- **Conceptual A/B/C choices** — picking between approaches described in words
-- **Tradeoff lists** — pros/cons, comparison tables
-- **Technical decisions** — API design, data modeling, architectural approach selection
-- **Clarifying questions** — anything where the answer is words, not a visual preference
-
-A question *about* a UI topic is not automatically a visual question. "What kind of wizard do you want?" is conceptual — use the terminal. "Which of these wizard layouts feels right?" is visual — use the browser.
-
-## How It Works
-
-The server watches a directory for HTML files and serves the newest one to the browser. You write HTML content to `screen_dir`, the user sees it in their browser and can click to select options. Selections are recorded to `state_dir/events` that you read on your next turn.
-
-**Content fragments vs full documents:** If your HTML file starts with `<!DOCTYPE` or `<html`, the server serves it as-is (just injects the helper script). Otherwise, the server automatically wraps your content in the frame template — adding the header, CSS theme, selection indicator, and all interactive infrastructure. **Write content fragments by default.** Only write full documents when you need complete control over the page.
-
-## Starting a Session
-
-```bash
-# Start server with persistence (mockups saved to project)
-scripts/start-server.sh --project-dir /path/to/project
-
-# Returns: {"type":"server-started","port":52341,"url":"http://localhost:52341",
-#           "screen_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/content",
-#           "state_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/state"}
-```
-
-Save `screen_dir` and `state_dir` from the response. Tell user to open the URL.
-
-**Finding connection info:** The server writes its startup JSON to `$STATE_DIR/server-info`. If you launched the server in the background and didn't capture stdout, read that file to get the URL and port. When using `--project-dir`, check `<project>/.superpowers/brainstorm/` for the session directory.
-
-**Note:** Pass the project root as `--project-dir` so mockups persist in `.superpowers/brainstorm/` and survive server restarts. Without it, files go to `/tmp` and get cleaned up. Remind the user to add `.superpowers/` to `.gitignore` if it's not already there.
-
-**Launching the server by platform:**
-
-**Claude Code (macOS / Linux):**
-```bash
-# Default mode works — the script backgrounds the server itself
-scripts/start-server.sh --project-dir /path/to/project
-```
-
-**Claude Code (Windows):**
-```bash
-# Windows auto-detects and uses foreground mode, which blocks the tool call.
-# Use run_in_background: true on the Bash tool call so the server survives
-# across conversation turns.
-scripts/start-server.sh --project-dir /path/to/project
-```
-When calling this via the Bash tool, set `run_in_background: true`. Then read `$STATE_DIR/server-info` on the next turn to get the URL and port.
-
-**Codex:**
-```bash
-# Codex reaps background processes. The script auto-detects CODEX_CI and
-# switches to foreground mode. Run it normally — no extra flags needed.
-scripts/start-server.sh --project-dir /path/to/project
-```
-
-**Gemini CLI:**
-```bash
-# Use --foreground and set is_background: true on your shell tool call
-# so the process survives across turns
-scripts/start-server.sh --project-dir /path/to/project --foreground
-```
-
-**Other environments:** The server must keep running in the background across conversation turns. If your environment reaps detached processes, use `--foreground` and launch the command with your platform's background execution mechanism.
-
-If the URL is unreachable from your browser (common in remote/containerized setups), bind a non-loopback host:
-
-```bash
-scripts/start-server.sh \
-  --project-dir /path/to/project \
-  --host 0.0.0.0 \
-  --url-host localhost
-```
-
-Use `--url-host` to control what hostname is printed in the returned URL JSON.
-
-## The Loop
-
-1. **Check server is alive**, then **write HTML** to a new file in `screen_dir`:
-   - Before each write, check that `$STATE_DIR/server-info` exists. If it doesn't (or `$STATE_DIR/server-stopped` exists), the server has shut down — restart it with `start-server.sh` before continuing. The server auto-exits after 30 minutes of inactivity.
-   - Use semantic filenames: `platform.html`, `visual-style.html`, `layout.html`
-   - **Never reuse filenames** — each screen gets a fresh file
-   - Use Write tool — **never use cat/heredoc** (dumps noise into terminal)
-   - Server automatically serves the newest file
-
-2. **Tell user what to expect and end your turn:**
-   - Remind them of the URL (every step, not just first)
-   - Give a brief text summary of what's on screen (e.g., "Showing 3 layout options for the homepage")
-   - Ask them to respond in the terminal: "Take a look and let me know what you think. Click to select an option if you'd like."
-
-3. **On your next turn** — after the user responds in the terminal:
-   - Read `$STATE_DIR/events` if it exists — this contains the user's browser interactions (clicks, selections) as JSON lines
-   - Merge with the user's terminal text to get the full picture
-   - The terminal message is the primary feedback; `state_dir/events` provides structured interaction data
-
-4. **Iterate or advance** — if feedback changes current screen, write a new file (e.g., `layout-v2.html`). Only move to the next question when the current step is validated.
-
-5. **Unload when returning to terminal** — when the next step doesn't need the browser (e.g., a clarifying question, a tradeoff discussion), push a waiting screen to clear the stale content:
-
-   ```html
-   <!-- filename: waiting.html (or waiting-2.html, etc.) -->
-   <div style="display:flex;align-items:center;justify-content:center;min-height:60vh">
-     <p class="subtitle">Continuing in terminal...</p>
-   </div>
-   ```
-
-   This prevents the user from staring at a resolved choice while the conversation has moved on. When the next visual question comes up, push a new content file as usual.
-
-6. Repeat until done.
-
-## Writing Content Fragments
-
-Write just the content that goes inside the page. The server wraps it in the frame template automatically (header, theme CSS, selection indicator, and all interactive infrastructure).
-
-**Minimal example:**
-
-```html
-<h2>Which layout works better?</h2>
-<p class="subtitle">Consider readability and visual hierarchy</p>
-
-<div class="options">
-  <div class="option" data-choice="a" onclick="toggleSelect(this)">
-    <div class="letter">A</div>
-    <div class="content">
-      <h3>Single Column</h3>
-      <p>Clean, focused reading experience</p>
-    </div>
-  </div>
-  <div class="option" data-choice="b" onclick="toggleSelect(this)">
-    <div class="letter">B</div>
-    <div class="content">
-      <h3>Two Column</h3>
-      <p>Sidebar navigation with main content</p>
-    </div>
-  </div>
-</div>
-```
-
-That's it. No `<html>`, no CSS, no `<script>` tags needed. The server provides all of that.
-
-## CSS Classes Available
-
-The frame template provides these CSS classes for your content:
-
-### Options (A/B/C choices)
-
-```html
-<div class="options">
-  <div class="option" data-choice="a" onclick="toggleSelect(this)">
-    <div class="letter">A</div>
-    <div class="content">
-      <h3>Title</h3>
-      <p>Description</p>
-    </div>
-  </div>
-</div>
-```
-
-**Multi-select:** Add `data-multiselect` to the container to let users select multiple options. Each click toggles the item. The indicator bar shows the count.
-
-```html
-<div class="options" data-multiselect>
-  <!-- same option markup — users can select/deselect multiple -->
-</div>
-```
-
-### Cards (visual designs)
-
-```html
-<div class="cards">
-  <div class="card" data-choice="design1" onclick="toggleSelect(this)">
-    <div class="card-image"><!-- mockup content --></div>
-    <div class="card-body">
-      <h3>Name</h3>
-      <p>Description</p>
-    </div>
-  </div>
-</div>
-```
-
-### Mockup container
-
-```html
-<div class="mockup">
-  <div class="mockup-header">Preview: Dashboard Layout</div>
-  <div class="mockup-body"><!-- your mockup HTML --></div>
-</div>
-```
-
-### Split view (side-by-side)
-
-```html
-<div class="split">
-  <div class="mockup"><!-- left --></div>
-  <div class="mockup"><!-- right --></div>
-</div>
-```
-
-### Pros/Cons
-
-```html
-<div class="pros-cons">
-  <div class="pros"><h4>Pros</h4><ul><li>Benefit</li></ul></div>
-  <div class="cons"><h4>Cons</h4><ul><li>Drawback</li></ul></div>
-</div>
-```
-
-### Mock elements (wireframe building blocks)
-
-```html
-<div class="mock-nav">Logo | Home | About | Contact</div>
-<div style="display: flex;">
-  <div class="mock-sidebar">Navigation</div>
-  <div class="mock-content">Main content area</div>
-</div>
-<button class="mock-button">Action Button</button>
-<input class="mock-input" placeholder="Input field">
-<div class="placeholder">Placeholder area</div>
-```
-
-### Typography and sections
-
-- `h2` — page title
-- `h3` — section heading
-- `.subtitle` — secondary text below title
-- `.section` — content block with bottom margin
-- `.label` — small uppercase label text
-
-## Browser Events Format
-
-When the user clicks options in the browser, their interactions are recorded to `$STATE_DIR/events` (one JSON object per line). The file is cleared automatically when you push a new screen.
-
-```jsonl
-{"type":"click","choice":"a","text":"Option A - Simple Layout","timestamp":1706000101}
-{"type":"click","choice":"c","text":"Option C - Complex Grid","timestamp":1706000108}
-{"type":"click","choice":"b","text":"Option B - Hybrid","timestamp":1706000115}
-```
-
-The full event stream shows the user's exploration path — they may click multiple options before settling. The last `choice` event is typically the final selection, but the pattern of clicks can reveal hesitation or preferences worth asking about.
-
-If `$STATE_DIR/events` doesn't exist, the user didn't interact with the browser — use only their terminal text.
-
-## Design Tips
-
-- **Scale fidelity to the question** — wireframes for layout, polish for polish questions
-- **Explain the question on each page** — "Which layout feels more professional?" not just "Pick one"
-- **Iterate before advancing** — if feedback changes current screen, write a new version
-- **2-4 options max** per screen
-- **Use real content when it matters** — for a photography portfolio, use actual images (Unsplash). Placeholder content obscures design issues.
-- **Keep mockups simple** — focus on layout and structure, not pixel-perfect design
-
-## File Naming
-
-- Use semantic names: `platform.html`, `visual-style.html`, `layout.html`
-- Never reuse filenames — each screen must be a new file
-- For iterations: append version suffix like `layout-v2.html`, `layout-v3.html`
-- Server serves newest file by modification time
-
-## Cleaning Up
-
-```bash
-scripts/stop-server.sh $SESSION_DIR
-```
-
-If the session used `--project-dir`, mockup files persist in `.superpowers/brainstorm/` for later reference. Only `/tmp` sessions get deleted on stop.
-
-## Reference
-
-- Frame template (CSS reference): `scripts/frame-template.html`
-- Helper script (client-side): `scripts/helper.js`