npm - @c-d-cc/reap - Versions diffs - 0.4.0 → 0.6.1 - Mend

@c-d-cc/reap 0.4.0 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (36) hide show

package/README.ja.md +96 -10
package/README.ko.md +96 -10
package/README.md +96 -10
package/README.zh-CN.md +96 -10
package/dist/cli.js +212 -112
package/dist/templates/artifacts/01-objective.md +17 -0
package/dist/templates/artifacts/merge/01-detect.md +18 -0
package/dist/templates/artifacts/merge/02-mate.md +12 -0
package/dist/templates/artifacts/merge/03-merge.md +15 -0
package/dist/templates/artifacts/merge/04-sync.md +18 -0
package/dist/templates/artifacts/merge/05-validation.md +11 -0
package/dist/templates/artifacts/merge/06-completion.md +13 -0
package/dist/templates/brainstorm/frame.html +125 -0
package/dist/templates/brainstorm/server.cjs +306 -0
package/dist/templates/brainstorm/spec-reviewer-prompt.md +52 -0
package/dist/templates/brainstorm/start-server.sh +67 -0
package/dist/templates/brainstorm/visual-companion-guide.md +120 -0
package/dist/templates/commands/reap.evolve.md +7 -0
package/dist/templates/commands/reap.merge.completion.md +20 -0
package/dist/templates/commands/reap.merge.detect.md +20 -0
package/dist/templates/commands/reap.merge.evolve.md +28 -0
package/dist/templates/commands/reap.merge.mate.md +27 -0
package/dist/templates/commands/reap.merge.md +47 -0
package/dist/templates/commands/reap.merge.merge.md +22 -0
package/dist/templates/commands/reap.merge.start.md +21 -0
package/dist/templates/commands/reap.merge.sync.md +32 -0
package/dist/templates/commands/reap.merge.validation.md +25 -0
package/dist/templates/commands/reap.next.md +14 -1
package/dist/templates/commands/reap.objective.md +105 -9
package/dist/templates/commands/reap.pull.md +51 -0
package/dist/templates/commands/reap.push.md +18 -0
package/dist/templates/hooks/genome-loader.cjs +34 -12
package/dist/templates/hooks/opencode-session-start.js +2 -2
package/dist/templates/hooks/reap-guide.md +1 -1
package/dist/templates/hooks/session-start.cjs +2 -2
package/package.json +1 -1

package/dist/templates/artifacts/merge/06-completion.md ADDED Viewed

@@ -0,0 +1,13 @@
+# Completion
+## Summary
+## Genome Changes Applied
+## Lessons Learned
+## Backlog (Genome Modifications Discovered)
+None

package/dist/templates/brainstorm/frame.html ADDED Viewed

@@ -0,0 +1,125 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>REAP Brainstorm</title>
+<style>
+  :root {
+    --bg: #0f1117;
+    --surface: #1a1d27;
+    --border: #2a2d3a;
+    --text: #e1e4ed;
+    --text-muted: #8b8fa3;
+    --accent: #6c8cff;
+    --accent-soft: rgba(108,140,255,0.12);
+    --success: #4ade80;
+    --warning: #fbbf24;
+    --radius: 8px;
+  }
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+    background: var(--bg);
+    color: var(--text);
+    line-height: 1.6;
+    padding: 2rem;
+    max-width: 960px;
+    margin: 0 auto;
+  }
+  h2 { font-size: 1.25rem; font-weight: 600; margin-bottom: 1rem; color: var(--text); }
+  h3 { font-size: 1rem; font-weight: 600; margin-bottom: 0.75rem; color: var(--text-muted); }
+  .subtitle { color: var(--text-muted); font-size: 0.95rem; }
+  .section { margin-bottom: 2rem; }
+  .label { font-size: 0.75rem; text-transform: uppercase; letter-spacing: 0.05em; color: var(--text-muted); margin-bottom: 0.5rem; }
+  /* Options: single/multi select */
+  .options { display: flex; flex-direction: column; gap: 0.5rem; }
+  .option {
+    padding: 1rem 1.25rem;
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    cursor: pointer;
+    transition: all 0.15s;
+    background: var(--surface);
+  }
+  .option:hover { border-color: var(--accent); background: var(--accent-soft); }
+  .option.selected { border-color: var(--accent); background: var(--accent-soft); box-shadow: 0 0 0 1px var(--accent); }
+  /* Cards: visual design cards */
+  .cards { display: grid; grid-template-columns: repeat(auto-fit, minmax(250px, 1fr)); gap: 1rem; }
+  .card {
+    padding: 1.25rem;
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    cursor: pointer;
+    transition: all 0.15s;
+    background: var(--surface);
+  }
+  .card:hover { border-color: var(--accent); transform: translateY(-2px); }
+  .card.selected { border-color: var(--accent); background: var(--accent-soft); }
+  .card h3 { margin-bottom: 0.5rem; }
+  /* Mockup containers */
+  .mockup {
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    overflow: hidden;
+    background: var(--surface);
+  }
+  .mockup-header {
+    padding: 0.5rem 1rem;
+    background: var(--border);
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+  }
+  .mockup-header::before {
+    content: '';
+    display: inline-flex;
+    gap: 4px;
+    width: 48px;
+    height: 12px;
+    background: radial-gradient(circle at 6px 6px, #ff5f56 5px, transparent 5px),
+                radial-gradient(circle at 22px 6px, #ffbd2e 5px, transparent 5px),
+                radial-gradient(circle at 38px 6px, #27c93f 5px, transparent 5px);
+  }
+  .mockup-body { padding: 1.25rem; }
+  /* Split comparison */
+  .split { display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; }
+  @media (max-width: 600px) { .split { grid-template-columns: 1fr; } }
+  /* Pros and cons */
+  .pros-cons { display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; }
+  .pros-cons .pros { color: var(--success); }
+  .pros-cons .cons { color: var(--warning); }
+  .pros-cons ul { list-style: none; padding: 0; }
+  .pros-cons li { padding: 0.25rem 0; }
+  .pros-cons .pros li::before { content: '+ '; font-weight: bold; }
+  .pros-cons .cons li::before { content: '- '; font-weight: bold; }
+  /* Mock UI elements */
+  .mock-nav { height: 48px; background: var(--border); border-radius: var(--radius) var(--radius) 0 0; display: flex; align-items: center; padding: 0 1rem; }
+  .mock-sidebar { background: var(--surface); border-right: 1px solid var(--border); padding: 1rem; min-height: 200px; }
+  .mock-content { padding: 1rem; flex: 1; }
+  .mock-button { display: inline-block; padding: 0.5rem 1rem; background: var(--accent); border-radius: var(--radius); color: white; font-size: 0.85rem; cursor: pointer; }
+  .mock-input { display: block; width: 100%; padding: 0.5rem 0.75rem; background: var(--bg); border: 1px solid var(--border); border-radius: var(--radius); color: var(--text); font-size: 0.9rem; }
+  .placeholder { background: var(--border); border-radius: 4px; height: 1em; margin: 0.25rem 0; }
+  /* Table for trade-offs */
+  table { width: 100%; border-collapse: collapse; margin: 1rem 0; }
+  th, td { padding: 0.75rem 1rem; text-align: left; border-bottom: 1px solid var(--border); }
+  th { color: var(--text-muted); font-weight: 500; font-size: 0.85rem; }
+</style>
+</head>
+<body>
+{{CONTENT}}
+<script>
+{{WS_SCRIPT}}
+</script>
+</body>
+</html>

package/dist/templates/brainstorm/server.cjs ADDED Viewed

@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+// REAP Visual Companion Server
+// Zero-dependency HTTP + WebSocket server using Node.js built-in modules only.
+// Serves HTML fragments from a screen directory, auto-wraps in frame template,
+// watches for file changes and pushes updates via WebSocket.
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const url = require('url');
+// --- Configuration ---
+const PORT = parseInt(process.env.BRAINSTORM_PORT || '3210', 10);
+const HOST = process.env.BRAINSTORM_HOST || '127.0.0.1';
+const URL_HOST = process.env.BRAINSTORM_URL_HOST || `http://${HOST}:${PORT}`;
+const IDLE_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+// Screen directory: where HTML fragments are written by the AI agent
+const SCREEN_DIR = process.env.BRAINSTORM_DIR || path.join(process.cwd(), '.reap', 'brainstorm');
+const SERVER_INFO_FILE = path.join(SCREEN_DIR, '.server-info');
+const SERVER_STOPPED_FILE = path.join(SCREEN_DIR, '.server-stopped');
+const EVENTS_FILE = path.join(SCREEN_DIR, '.events');
+// Frame template path (same directory as this script)
+const FRAME_TEMPLATE_PATH = path.join(__dirname, 'frame.html');
+// --- State ---
+let idleTimer = null;
+const wsClients = new Set();
+// --- Helpers ---
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+function resetIdleTimer() {
+  if (idleTimer) clearTimeout(idleTimer);
+  idleTimer = setTimeout(() => {
+    console.log('[brainstorm] Idle timeout reached. Shutting down.');
+    shutdown();
+  }, IDLE_TIMEOUT_MS);
+}
+function shutdown() {
+  try {
+    fs.writeFileSync(SERVER_STOPPED_FILE, new Date().toISOString());
+    if (fs.existsSync(SERVER_INFO_FILE)) fs.unlinkSync(SERVER_INFO_FILE);
+  } catch (_) { /* best effort */ }
+  process.exit(0);
+}
+function getNewestHtmlFile() {
+  ensureDir(SCREEN_DIR);
+  const files = fs.readdirSync(SCREEN_DIR)
+    .filter(f => f.endsWith('.html') && !f.startsWith('.'))
+    .map(f => ({ name: f, mtime: fs.statSync(path.join(SCREEN_DIR, f)).mtimeMs }))
+    .sort((a, b) => b.mtime - a.mtime);
+  return files.length > 0 ? files[0].name : null;
+}
+function loadFrame() {
+  if (fs.existsSync(FRAME_TEMPLATE_PATH)) {
+    return fs.readFileSync(FRAME_TEMPLATE_PATH, 'utf-8');
+  }
+  return '<!DOCTYPE html><html><head><meta charset="utf-8"><title>REAP Brainstorm</title></head><body>{{CONTENT}}<script>{{WS_SCRIPT}}</script></body></html>';
+}
+function wrapInFrame(content) {
+  const frame = loadFrame();
+  const wsScript = `
+(function() {
+  var ws = new WebSocket('ws://' + location.host + '/ws');
+  ws.onmessage = function(e) {
+    var data = JSON.parse(e.data);
+    if (data.type === 'reload') location.reload();
+  };
+  ws.onclose = function() { setTimeout(function() { location.reload(); }, 2000); };
+  document.addEventListener('click', function(e) {
+    var el = e.target.closest('[data-choice]');
+    if (!el) return;
+    var container = el.closest('.options, .cards');
+    var isMulti = container && container.hasAttribute('data-multiselect');
+    if (!isMulti) {
+      container.querySelectorAll('[data-choice]').forEach(function(s) { s.classList.remove('selected'); });
+    }
+    el.classList.toggle('selected');
+    var event = {
+      type: 'click',
+      choice: el.getAttribute('data-choice'),
+      text: el.textContent.trim().substring(0, 200),
+      timestamp: Math.floor(Date.now() / 1000)
+    };
+    ws.send(JSON.stringify(event));
+  });
+})();`;
+  // Check if content is a full HTML document
+  if (content.trim().startsWith('<!DOCTYPE') || content.trim().startsWith('<html')) {
+    return content;
+  }
+  return frame.replace('{{CONTENT}}', content).replace('{{WS_SCRIPT}}', wsScript);
+}
+// --- WebSocket (RFC 6455 minimal implementation) ---
+function parseWsFrame(buffer) {
+  if (buffer.length < 2) return null;
+  const secondByte = buffer[1];
+  const masked = (secondByte & 0x80) !== 0;
+  let payloadLen = secondByte & 0x7f;
+  let offset = 2;
+  if (payloadLen === 126) {
+    if (buffer.length < 4) return null;
+    payloadLen = buffer.readUInt16BE(2);
+    offset = 4;
+  } else if (payloadLen === 127) {
+    if (buffer.length < 10) return null;
+    payloadLen = Number(buffer.readBigUInt64BE(2));
+    offset = 10;
+  }
+  let maskKey = null;
+  if (masked) {
+    if (buffer.length < offset + 4) return null;
+    maskKey = buffer.slice(offset, offset + 4);
+    offset += 4;
+  }
+  if (buffer.length < offset + payloadLen) return null;
+  let payload = buffer.slice(offset, offset + payloadLen);
+  if (masked && maskKey) {
+    for (let i = 0; i < payload.length; i++) {
+      payload[i] ^= maskKey[i & 3];
+    }
+  }
+  const opcode = buffer[0] & 0x0f;
+  return { opcode, payload, totalLength: offset + payloadLen };
+}
+function createWsFrame(data) {
+  const payload = Buffer.from(data, 'utf-8');
+  const len = payload.length;
+  let header;
+  if (len < 126) {
+    header = Buffer.alloc(2);
+    header[0] = 0x81; // FIN + text
+    header[1] = len;
+  } else if (len < 65536) {
+    header = Buffer.alloc(4);
+    header[0] = 0x81;
+    header[1] = 126;
+    header.writeUInt16BE(len, 2);
+  } else {
+    header = Buffer.alloc(10);
+    header[0] = 0x81;
+    header[1] = 127;
+    header.writeBigUInt64BE(BigInt(len), 2);
+  }
+  return Buffer.concat([header, payload]);
+}
+function broadcastWs(message) {
+  const frame = createWsFrame(JSON.stringify(message));
+  for (const client of wsClients) {
+    try { client.write(frame); } catch (_) { wsClients.delete(client); }
+  }
+}
+// --- HTTP Server ---
+const server = http.createServer((req, res) => {
+  resetIdleTimer();
+  const parsed = url.parse(req.url, true);
+  const pathname = parsed.pathname;
+  // Serve newest HTML file
+  if (pathname === '/') {
+    const newest = getNewestHtmlFile();
+    if (!newest) {
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+      res.end(wrapInFrame('<div style="display:flex;align-items:center;justify-content:center;min-height:60vh"><p style="color:#888;font-size:1.2em;">Waiting for content...</p></div>'));
+      return;
+    }
+    const content = fs.readFileSync(path.join(SCREEN_DIR, newest), 'utf-8');
+    res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+    res.end(wrapInFrame(content));
+    return;
+  }
+  // Serve specific files from screen directory
+  if (pathname.startsWith('/files/')) {
+    const filename = path.basename(pathname);
+    const filePath = path.join(SCREEN_DIR, filename);
+    if (fs.existsSync(filePath)) {
+      const ext = path.extname(filename).toLowerCase();
+      const mimeTypes = { '.html': 'text/html', '.css': 'text/css', '.js': 'application/javascript', '.png': 'image/png', '.jpg': 'image/jpeg', '.svg': 'image/svg+xml' };
+      res.writeHead(200, { 'Content-Type': (mimeTypes[ext] || 'application/octet-stream') + '; charset=utf-8' });
+      res.end(fs.readFileSync(filePath));
+      return;
+    }
+  }
+  res.writeHead(404);
+  res.end('Not Found');
+});
+// WebSocket upgrade
+server.on('upgrade', (req, socket) => {
+  if (req.url !== '/ws') { socket.destroy(); return; }
+  const key = req.headers['sec-websocket-key'];
+  const accept = crypto.createHash('sha1')
+    .update(key + '258EAFA5-E914-47DA-95CA-5AB5DC085B11')
+    .digest('base64');
+  socket.write(
+    'HTTP/1.1 101 Switching Protocols\r\n' +
+    'Upgrade: websocket\r\n' +
+    'Connection: Upgrade\r\n' +
+    `Sec-WebSocket-Accept: ${accept}\r\n\r\n`
+  );
+  wsClients.add(socket);
+  let buffer = Buffer.alloc(0);
+  socket.on('data', (data) => {
+    resetIdleTimer();
+    buffer = Buffer.concat([buffer, data]);
+    while (true) {
+      const frame = parseWsFrame(buffer);
+      if (!frame) break;
+      buffer = buffer.slice(frame.totalLength);
+      if (frame.opcode === 0x08) { // close
+        wsClients.delete(socket);
+        socket.end();
+        return;
+      }
+      if (frame.opcode === 0x09) { // ping
+        const pong = Buffer.alloc(2);
+        pong[0] = 0x8a; pong[1] = 0;
+        socket.write(pong);
+        continue;
+      }
+      if (frame.opcode === 0x01) { // text
+        try {
+          const event = frame.payload.toString('utf-8');
+          fs.appendFileSync(EVENTS_FILE, event + '\n');
+        } catch (_) { /* best effort */ }
+      }
+    }
+  });
+  socket.on('close', () => wsClients.delete(socket));
+  socket.on('error', () => wsClients.delete(socket));
+});
+// --- File Watcher ---
+function startWatcher() {
+  ensureDir(SCREEN_DIR);
+  let debounce = null;
+  try {
+    fs.watch(SCREEN_DIR, (eventType, filename) => {
+      if (!filename || filename.startsWith('.') || !filename.endsWith('.html')) return;
+      if (debounce) clearTimeout(debounce);
+      debounce = setTimeout(() => {
+        // Clear events file when new HTML is pushed
+        try { fs.writeFileSync(EVENTS_FILE, ''); } catch (_) {}
+        broadcastWs({ type: 'reload' });
+      }, 100);
+    });
+  } catch (err) {
+    console.error('[brainstorm] File watcher error:', err.message);
+  }
+}
+// --- Startup ---
+ensureDir(SCREEN_DIR);
+// Remove stale stopped marker
+if (fs.existsSync(SERVER_STOPPED_FILE)) {
+  fs.unlinkSync(SERVER_STOPPED_FILE);
+}
+server.listen(PORT, HOST, () => {
+  const info = { url: URL_HOST, port: PORT, pid: process.pid, startedAt: new Date().toISOString() };
+  fs.writeFileSync(SERVER_INFO_FILE, JSON.stringify(info, null, 2));
+  console.log(`[brainstorm] Visual Companion running at ${URL_HOST}`);
+  console.log(`[brainstorm] Screen directory: ${SCREEN_DIR}`);
+  console.log(`[brainstorm] Idle timeout: 30 minutes`);
+  resetIdleTimer();
+  startWatcher();
+});
+process.on('SIGINT', shutdown);
+process.on('SIGTERM', shutdown);

package/dist/templates/brainstorm/spec-reviewer-prompt.md ADDED Viewed

@@ -0,0 +1,52 @@
+# Spec Document Review
+You are a spec-document-reviewer subagent. Your job is to review the REAP Objective artifact (`01-objective.md`) for quality issues that would cause problems during planning and implementation.
+## What to Check
+| Category | What to Look For |
+|----------|------------------|
+| Completeness | TODOs, placeholders, "TBD", incomplete sections, missing completion criteria |
+| Consistency | Internal contradictions, conflicting requirements, mismatched scope vs requirements |
+| Clarity | Requirements ambiguous enough to cause someone to build the wrong thing |
+| Scope | Focused enough for a single generation — not covering multiple independent subsystems |
+| YAGNI | Unrequested features, over-engineering, unnecessary complexity |
+| Verifiability | Completion criteria that cannot be objectively verified (vague: "improve", "better") |
+## Calibration
+Only flag issues that would cause **real problems** during planning or implementation.
+**Flag these:**
+- Missing sections that would block planning
+- Contradictions between requirements
+- Ambiguous requirements with multiple valid interpretations
+- Scope too large for a single generation
+**Do NOT flag:**
+- Minor wording improvements
+- Stylistic preferences
+- Suggestions for additional nice-to-have features
+- Formatting issues
+## Output Format
+```
+## Spec Review
+**Status:** Approved | Issues Found
+**Issues (if any):**
+- [Section]: [specific issue] — [why it matters for planning]
+**Recommendations (advisory, do not block approval):**
+- [suggestions for improvement]
+```
+## Important
+- Read the full `01-objective.md` before starting the review
+- Cross-reference requirements against completion criteria — every criterion should map to at least one FR
+- Check that exclusions are explicitly stated
+- Verify that FR numbering is consistent (FR-001, FR-002, ...)
+- Maximum 3 review iterations — if issues persist after 3 rounds, escalate to the human

package/dist/templates/brainstorm/start-server.sh ADDED Viewed

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# REAP Visual Companion — Server Start Script
+# Usage: start-server.sh [--project-dir /path/to/project] [--port 3210] [--foreground]
+set -e
+PROJECT_DIR="$(pwd)"
+PORT="${BRAINSTORM_PORT:-3210}"
+FOREGROUND=false
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --project-dir) PROJECT_DIR="$2"; shift 2 ;;
+    --port) PORT="$2"; shift 2 ;;
+    --foreground) FOREGROUND=true; shift ;;
+    *) shift ;;
+  esac
+done
+SCREEN_DIR="${PROJECT_DIR}/.reap/brainstorm"
+SERVER_INFO="${SCREEN_DIR}/.server-info"
+SERVER_STOPPED="${SCREEN_DIR}/.server-stopped"
+# Find server.cjs relative to this script
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SERVER_JS="${SCRIPT_DIR}/server.cjs"
+# Ensure screen directory exists
+mkdir -p "${SCREEN_DIR}"
+# Remove stale stopped marker
+rm -f "${SERVER_STOPPED}"
+# Check if already running
+if [ -f "${SERVER_INFO}" ]; then
+  PID=$(node -e "try{console.log(JSON.parse(require('fs').readFileSync('${SERVER_INFO}','utf-8')).pid)}catch(e){console.log('')}")
+  if [ -n "${PID}" ] && kill -0 "${PID}" 2>/dev/null; then
+    echo "[brainstorm] Server already running (PID: ${PID})"
+    cat "${SERVER_INFO}"
+    exit 0
+  fi
+  # Stale info file
+  rm -f "${SERVER_INFO}"
+fi
+export BRAINSTORM_PORT="${PORT}"
+export BRAINSTORM_DIR="${SCREEN_DIR}"
+if [ "${FOREGROUND}" = true ]; then
+  exec node "${SERVER_JS}"
+else
+  nohup node "${SERVER_JS}" > "${SCREEN_DIR}/.server.log" 2>&1 &
+  NOHUP_PID=$!
+  # Wait for server-info to appear (max 5 seconds)
+  for i in $(seq 1 50); do
+    if [ -f "${SERVER_INFO}" ]; then
+      echo "[brainstorm] Server started."
+      cat "${SERVER_INFO}"
+      exit 0
+    fi
+    sleep 0.1
+  done
+  echo "[brainstorm] Warning: server may have failed to start. Check ${SCREEN_DIR}/.server.log"
+  exit 1
+fi

package/dist/templates/brainstorm/visual-companion-guide.md ADDED Viewed

@@ -0,0 +1,120 @@
+# Visual Companion Guide
+> REAP Objective 단계에서 비주얼 컴패니언을 사용하는 가이드.
+> `reap.objective` 슬래시 커맨드가 이 파일을 참조한다.
+## 비주얼 컴패니언이란
+로컬 Node.js 서버를 통해 브라우저에 목업, 다이어그램, 비교 카드 등을 표시하여 설계 논의를 시각적으로 보조하는 도구.
+외부 의존 없이 Node.js 내장 모듈만 사용한다.
+## 제안 시점
+Objective Step 5(Goal + Spec Definition) 진입 시, 시각적 질문이 예상되면 컴패니언을 제안한다.
+제안 메시지는 **독립 메시지**로 보내야 한다 (다른 질문과 합치지 않는다):
+> "이번 설계에서 목업이나 다이어그램으로 보여드리면 이해하기 쉬운 부분이 있을 수 있습니다.
+> 브라우저에서 시각 자료를 보여드릴 수 있는 비주얼 컴패니언을 사용할까요?
+> (로컬 서버를 띄워 브라우저에서 확인하는 방식입니다)"
+유저가 거부하면 터미널 전용으로 진행한다.
+## 브라우저 vs 터미널 판단 규칙
+각 질문마다 판단: **유저가 읽는 것보다 보는 것이 이해에 도움이 되는가?**
+### 브라우저 사용
+- UI 목업, 와이어프레임, 레이아웃
+- 아키텍처 다이어그램, 시스템 구성도, 데이터 흐름 맵
+- 나란히 비교 (레이아웃, 색상, 디자인 방향)
+- 디자인 폴리시 (느낌, 간격, 비주얼 위계)
+- 공간 관계 (상태 머신, 플로우차트, ERD를 다이어그램으로)
+### 터미널 사용
+- 요구사항, 범위 질문 ("X는 무슨 뜻인가요?")
+- 개념적 A/B/C 선택 (텍스트로 설명 가능한 접근법)
+- 트레이드오프 목록, 비교표
+- 기술 결정 (API 설계, 데이터 모델링, 아키텍처 접근)
+- 명확화 질문 (답이 시각적 선호가 아닌 말)
+### 핵심 테스트
+UI 관련 질문이라도 자동으로 비주얼은 아니다.
+- "어떤 종류의 마법사를 원하시나요?" → 개념적 → **터미널**
+- "어떤 마법사 레이아웃이 좋으세요?" → 시각적 → **브라우저**
+## 서버 기동
+```bash
+# 프로젝트 루트에서 실행
+bash .reap/brainstorm/start-server.sh
+# 또는 직접
+node .reap/brainstorm/server.cjs
+```
+- `BRAINSTORM_PORT` 환경 변수로 포트 변경 (기본: 3210)
+- `BRAINSTORM_DIR` 환경 변수로 스크린 디렉토리 변경 (기본: `.reap/brainstorm/`)
+## 서버 상태 확인
+- `.reap/brainstorm/.server-info` — 서버 실행 중이면 JSON 존재 (url, port, pid)
+- `.reap/brainstorm/.server-stopped` — 서버가 종료되면 생성됨
+- 서버가 종료된 상태에서 재기동 필요: `start-server.sh` 재실행
+## HTML 작성 규칙
+1. `.reap/brainstorm/` 디렉토리에 HTML 파일을 Write 도구로 작성
+2. 시맨틱 파일명 사용 (`architecture.html`, `layout-options.html`)
+3. 파일명 재사용 금지 (수정 시 `layout-v2.html` 사용)
+4. **Content fragment 기본** — `<!DOCTYPE` 없이 본문만 작성하면 프레임 템플릿이 자동 래핑
+5. 전체 HTML 제어가 필요한 경우만 full document 작성
+## 사용 가능한 CSS 클래스
+| 클래스 | 용도 |
+|--------|------|
+| `.options` + `.option[data-choice]` | A/B/C 단일 선택 |
+| `.options[data-multiselect]` | 다중 선택 |
+| `.cards` + `.card[data-choice]` | 비주얼 디자인 카드 |
+| `.mockup` + `.mockup-header` + `.mockup-body` | 목업 컨테이너 |
+| `.split` | 나란히 비교 |
+| `.pros-cons` + `.pros` + `.cons` | 장단점 |
+| `.mock-nav`, `.mock-sidebar`, `.mock-content` | 목업 UI 요소 |
+| `.mock-button`, `.mock-input` | 목업 인터랙티브 요소 |
+| `.placeholder` | 플레이스홀더 블록 |
+| `table`, `h2`, `h3`, `.subtitle`, `.section`, `.label` | 타이포그래피 |
+## 이벤트 읽기
+유저가 브라우저에서 `[data-choice]` 요소를 클릭하면 WebSocket을 통해 `.events` 파일에 JSON Lines로 기록된다:
+```json
+{"type":"click","choice":"a","text":"Option A","timestamp":1706000101}
+```
+- 터미널 메시지가 주 피드백 채널
+- `.events` 파일은 보조 인터랙션 데이터
+- 새 HTML 파일 푸시 시 `.events`는 자동 초기화
+## 턴 기반 흐름
+1. HTML 파일을 Write 도구로 작성
+2. 유저에게 URL 안내 + 간략한 텍스트 설명 → **턴 종료**
+3. 다음 턴에서 `.events` 파일 읽기 (유저 인터랙션 확인)
+4. 터미널 메시지 + `.events`를 종합하여 다음 단계 진행
+5. 터미널로 돌아갈 때 대기 화면 푸시:
+   ```html
+   <div style="display:flex;align-items:center;justify-content:center;min-height:60vh">
+     <p class="subtitle">터미널에서 계속 진행 중...</p>
+   </div>
+   ```
+## 조건부 실행
+비주얼 컴패니언은 brainstorming이 활성화된 경우에만 제안된다.
+brainstorming 자체가 목표 복잡도에 따라 조건부로 실행되므로, 단순 태스크(bugfix, config, docs-only)에서는 비주얼 컴패니언도 제안되지 않는다.
+## evolve 모드에서의 동작
+`/reap.evolve`의 Autonomous Override가 활성화되어 있어도, brainstorming 진입 시 비주얼 컴패니언 제안은 수행한다.
+유저가 명시적으로 거부한 경우에만 스킵한다.