@c-d-cc/reap 0.5.0 → 0.6.1

package/README.ja.md

@@ -112,7 +112,7 @@ Objective → Planning → Implementation ⟷ Validation → Completion
 
 | ステージ | 内容 | 成果物 |
 |----------|------|--------|
-| **Objective** | 目標 + 要件 + 受入基準の定義 | `01-objective.md` |
+| **Objective** | 構造化ブレインストーミングによる目標・設計定義：明確化質問、アプローチ代案、セクション別設計、ビジュアルコンパニオン、Specレビュー | `01-objective.md` |
 | **Planning** | タスク分解、実装アプローチ、依存関係 | `02-planning.md` |
 | **Implementation** | AI+Human協力でコード実装 | `03-implementation.md` |
 | **Validation** | テスト実行、完了条件の確認 | `04-validation.md` |

package/README.ko.md

@@ -112,7 +112,7 @@ Objective → Planning → Implementation ⟷ Validation → Completion
 
 | 단계 | 하는 일 | 산출물 |
 |------|---------|--------|
-| **Objective** | 목표 + 요구사항 + 수용기준 정의 | `01-objective.md` |
+| **Objective** | 구조화된 브레인스토밍으로 목표 및 설계 정의: 명확화 질문, 접근법 대안, 섹션별 설계, 비주얼 컴패니언, Spec 리뷰 | `01-objective.md` |
 | **Planning** | 태스크 분해, 구현 접근법, 의존관계 | `02-planning.md` |
 | **Implementation** | AI+Human 협업으로 코드 구현 | `03-implementation.md` |
 | **Validation** | 테스트 실행, 완료 조건 점검 | `04-validation.md` |

package/README.md

@@ -111,7 +111,7 @@ Objective → Planning → Implementation ⟷ Validation → Completion
 
 | Stage | What happens | Artifact |
 |-------|-------------|----------|
-| **Objective** | Define goal, requirements, and acceptance criteria | `01-objective.md` |
+| **Objective** | Define goal through structured brainstorming: clarifying questions, 2-3 approach alternatives, sectional design approval, optional visual companion, and spec review loop | `01-objective.md` |
 | **Planning** | Break down tasks, choose approach, map dependencies | `02-planning.md` |
 | **Implementation** | Build with AI + human collaboration | `03-implementation.md` |
 | **Validation** | Run tests, verify completion criteria | `04-validation.md` |

package/README.zh-CN.md

@@ -112,7 +112,7 @@ Objective → Planning → Implementation ⟷ Validation → Completion
 
 | 阶段 | 内容 | 产出物 |
 |------|------|--------|
-| **Objective** | 定义目标 + 需求 + 验收标准 | `01-objective.md` |
+| **Objective** | 通过结构化头脑风暴定义目标与设计：澄清问题、方案替代、分段设计、视觉伴侣、Spec审查 | `01-objective.md` |
 | **Planning** | 任务分解、实施方案、依赖关系 | `02-planning.md` |
 | **Implementation** | AI+人类协作编写代码 | `03-implementation.md` |
 | **Validation** | 执行测试、检查完成条件 | `04-validation.md` |

package/dist/cli.js

@@ -9500,6 +9500,18 @@ async function initProject(projectRoot, projectName, entryMode, preset, onProgre
     const dest = join4(mergeTemplatesDir, file);
     await writeTextFile(dest, await readTextFileOrThrow(src));
   }
+  log("Installing brainstorm server...");
+  const brainstormSourceDir = join4(ReapPaths.packageTemplatesDir, "brainstorm");
+  const brainstormDestDir = join4(paths.root, "brainstorm");
+  await mkdir3(brainstormDestDir, { recursive: true });
+  const brainstormFiles = ["server.cjs", "frame.html", "start-server.sh"];
+  for (const file of brainstormFiles) {
+    const src = join4(brainstormSourceDir, file);
+    const dest = join4(brainstormDestDir, file);
+    await writeTextFile(dest, await readTextFileOrThrow(src));
+    if (file.endsWith(".sh"))
+      await chmod(dest, 493);
+  }
   log("Installing hook conditions...");
   const conditionsSourceDir = join4(ReapPaths.packageTemplatesDir, "conditions");
   const conditionsDestDir = join4(paths.hooks, "conditions");
@@ -9529,7 +9541,7 @@ async function initProject(projectRoot, projectName, entryMode, preset, onProgre
 }
 
 // src/cli/commands/update.ts
-import { readdir as readdir8, unlink as unlink3, rm as rm2, mkdir as mkdir6 } from "fs/promises";
+import { readdir as readdir8, unlink as unlink3, rm as rm2, mkdir as mkdir6, chmod as chmod2 } from "fs/promises";
 import { join as join9 } from "path";
 
 // src/core/hooks.ts
@@ -10382,6 +10394,26 @@ async function updateProject(projectRoot, dryRun = false) {
       result.updated.push(`~/.reap/templates/merge/${file}`);
     }
   }
+  const brainstormSourceDir = join9(ReapPaths.packageTemplatesDir, "brainstorm");
+  const brainstormDestDir = join9(paths.root, "brainstorm");
+  await mkdir6(brainstormDestDir, { recursive: true });
+  const brainstormFiles = ["server.cjs", "frame.html", "start-server.sh"];
+  for (const file of brainstormFiles) {
+    const src = await readTextFileOrThrow(join9(brainstormSourceDir, file));
+    const dest = join9(brainstormDestDir, file);
+    const existing = await readTextFile(dest);
+    if (existing !== null && existing === src) {
+      result.skipped.push(`.reap/brainstorm/${file}`);
+    } else {
+      if (!dryRun) {
+        await writeTextFile(dest, src);
+        if (file.endsWith(".sh")) {
+          await chmod2(dest, 493);
+        }
+      }
+      result.updated.push(`.reap/brainstorm/${file}`);
+    }
+  }
   const migrations = await migrateHooks(dryRun);
   for (const m of migrations.results) {
     if (m.action === "migrated") {
@@ -10557,7 +10589,7 @@ async function fixProject(projectRoot) {
 
 // src/cli/index.ts
 import { join as join10 } from "path";
-program.name("reap").description("REAP — Recursive Evolutionary Autonomous Pipeline").version("0.5.0");
+program.name("reap").description("REAP — Recursive Evolutionary Autonomous Pipeline").version("0.6.1");
 program.command("init").description("Initialize a new REAP project (Genesis)").argument("[project-name]", "Project name (defaults to current directory name)").option("-m, --mode <mode>", "Entry mode: greenfield, migration, adoption", "greenfield").option("-p, --preset <preset>", "Bootstrap with a genome preset (e.g., bun-hono-react)").action(async (projectName, options) => {
   try {
     const cwd = process.cwd();

package/dist/templates/artifacts/01-objective.md

@@ -14,6 +14,23 @@
 ### Non-Functional Requirements
 
 
+## Design
+
+### Approaches Considered
+
+| Aspect | Approach A | Approach B |
+|--------|-----------|-----------|
+| Summary | | |
+| Pros | | |
+| Cons | | |
+| Recommendation | | |
+
+### Selected Design
+
+
+### Design Approval History
+
+
 ## Scope
 - **Related Genome Areas**:
 - **Expected Change Scope**:

package/dist/templates/brainstorm/frame.html

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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 진입 시 비주얼 컴패니언 제안은 수행한다.
+유저가 명시적으로 거부한 경우에만 스킵한다.

package/dist/templates/commands/reap.objective.md

@@ -2,11 +2,12 @@
 description: "REAP Objective — Define the goal and specification for this Generation"
 ---
 
-# Objective (Goal Definition)
+# Objective (Goal Definition + Brainstorming Design)
 
 <HARD-GATE>
 Do NOT write any code until the artifact (01-objective.md) has been confirmed by the human.
 If the goal is ambiguous, do NOT guess — STOP and ask the human. This is non-negotiable.
+Brainstorming is triggered based on goal complexity — simple tasks skip it, complex tasks require it. The human can always override the AI's assessment.
 </HARD-GATE>
 
 ## Gate (Preconditions)
@@ -107,13 +108,97 @@ If the goal is ambiguous, do NOT guess — STOP and ask the human. This is non-n
     - **constraints.md has empty Validation Commands** → flag as "test commands undefined"
 - Report the genome health status to the human
 
-### 5. Goal + Spec Definition
-- Based on the above information, converse with the human to refine this generation's goal
-- If genome enhancement is needed, discuss whether to include it in this generation's goal
-- Criteria for a good goal:
-  - Achievable within a single Generation
-  - Verifiable completion criteria (no vague wording)
-  - Relevant genome areas are clearly identified
+### 5. Goal + Spec Definition (with optional Brainstorming)
+
+Before entering brainstorming, evaluate whether the goal requires it.
+
+#### Complexity Gate
+Assess the goal's complexity based on these criteria:
+
+**Skip brainstorming** (proceed directly to Step 6 with simple goal+spec definition):
+- Simple bugfix with clear cause and fix
+- Configuration change or settings adjustment
+- Documentation-only changes
+- Single-file refactoring with obvious approach
+- Tasks where the "what" and "how" are both already clear
+
+**Enter brainstorming** (follow sub-steps 5a–5e):
+- New feature development spanning multiple components
+- Architecture changes or new module design
+- Tasks with multiple valid implementation approaches
+- Requirements that need further exploration or clarification
+- Integration with external systems or complex data flows
+
+**Under Autonomous Override**: Assess automatically. If the goal from `current.yml` clearly fits "skip" criteria, skip brainstorming.
+**Human override**: The human can always request brainstorming ("let's brainstorm this") or skip it ("just do it", "skip brainstorming") regardless of the AI's assessment.
+
+When skipping brainstorming, converse with the human to refine the goal:
+- Criteria for a good goal: achievable within a single Generation, verifiable completion criteria (no vague wording), relevant genome areas identified
+- Then proceed directly to Step 6 (Genome Gap Analysis)
+
+When entering brainstorming, follow the structured brainstorming process below to produce a well-designed objective. Follow the sub-steps in order.
+
+#### 5a. Visual Companion Proposal
+- Evaluate whether this generation's goal involves visual questions (UI design, architecture diagrams, layout comparisons, etc.)
+- If visual questions are likely, propose the Visual Companion in a **standalone message** (do NOT combine with other questions):
+  > "이번 설계에서 목업이나 다이어그램으로 보여드리면 이해하기 쉬운 부분이 있을 수 있습니다.
+  > 브라우저에서 시각 자료를 보여드릴 수 있는 비주얼 컴패니언을 사용할까요?
+  > (로컬 서버를 띄워 브라우저에서 확인하는 방식입니다)"
+- If the human accepts: start the brainstorm server (`bash` the start script in `.reap/brainstorm/start-server.sh` or `node` the server directly). Read `src/templates/brainstorm/visual-companion-guide.md` for usage rules.
+- If the human declines: proceed terminal-only. Do NOT offer again.
+- **This step applies even under `/reap.evolve` Autonomous Override** — only skip if the human has explicitly declined.
+
+#### 5b. Clarifying Questions (One at a Time)
+- **CRITICAL**: Ask only ONE question per message. Never bundle multiple questions.
+- Prefer **multiple choice** over open-ended questions when possible.
+- Goal: understand purpose, constraints, success criteria, and scope.
+- Continue asking until you have enough information to propose approaches.
+- Good question flow:
+  1. Purpose/motivation: "What problem does this solve?"
+  2. Users/stakeholders: "Who benefits from this?"
+  3. Constraints: "Are there any hard constraints?" (with examples as choices)
+  4. Success criteria: "How will you know this is done?"
+- Under Autonomous Override: Use existing context (genome, backlog, goal from `current.yml`) to answer these questions yourself. Only STOP and ask if genuinely ambiguous.
+
+#### 5c. Approach Exploration (2-3 Alternatives)
+- Propose **2-3 approaches** with clear trade-offs.
+- Present as a comparison table:
+
+  | Aspect | Approach A | Approach B | Approach C |
+  |--------|-----------|-----------|-----------|
+  | Summary | ... | ... | ... |
+  | Pros | ... | ... | ... |
+  | Cons | ... | ... | ... |
+  | Complexity | ... | ... | ... |
+  | Recommendation | ... | ... | ... |
+
+- Include a clear recommendation with reasoning.
+- If using Visual Companion: show approaches visually in the browser for comparison.
+- If only one sensible approach exists, state why alternatives were considered but dismissed.
+- Wait for the human to choose (or confirm the recommendation).
+- Under Autonomous Override: choose the recommended approach and proceed.
+
+#### 5d. Sectional Design Approval
+- Present the design in sections, scaled to complexity:
+  - **Simple** (few sentences per section): small feature, bug fix, config change
+  - **Medium** (1-2 paragraphs per section): new module, refactoring, integration
+  - **Detailed** (200-300 words per section): new system, major architecture change
+- Sections to cover (skip if not applicable):
+  1. **Architecture** — high-level structure, module relationships
+  2. **Components** — key components and their responsibilities
+  3. **Data Flow** — how data moves through the system
+  4. **Error Handling** — failure modes and recovery strategies
+  5. **Testing Strategy** — what and how to test
+- **After each section**, ask: "Does this look right so far?" (or confirm under Autonomous Override)
+- If using Visual Companion: show architecture/data flow diagrams in the browser.
+- Iterate until the human approves each section.
+
+#### 5e. Scope Decomposition Check
+- **Check for multi-subsystem scope**: If the goal describes 2+ independent subsystems (e.g., "build chat + file storage + billing"):
+  - Flag immediately: "This goal covers multiple independent subsystems. I recommend splitting into separate Generations."
+  - Help decompose into sub-goals, each getting its own Generation.
+- **Check FR count**: If functional requirements exceed 10, warn and suggest splitting.
+- Under Autonomous Override: if scope is clearly single-subsystem, proceed without asking.
 
 ### 6. Genome Gap Analysis
 - Identify information required to achieve the goal that is missing from the genome
@@ -135,6 +220,14 @@ If the goal is ambiguous, do NOT guess — STOP and ask the human. This is non-n
 - **Limit**: Maximum 7 completion criteria. Each must be verifiable.
 - Finalize with the human
 
+### 8. Spec Review Loop
+- After the artifact is complete, dispatch a **spec-document-reviewer subagent** (using the Agent tool with the prompt from `src/templates/brainstorm/spec-reviewer-prompt.md`):
+  - The subagent reads `.reap/life/01-objective.md` and reviews for completeness, consistency, clarity, scope, YAGNI, and verifiability.
+  - If **Issues Found**: fix the issues in the artifact and re-dispatch the reviewer.
+  - If **Approved**: proceed to human review.
+  - **Maximum 3 iterations**. If issues persist after 3 rounds, present remaining issues to the human for decision.
+- Under Autonomous Override: run the review loop automatically. Only escalate if the reviewer flags blocking issues after 3 rounds.
+
 ## Escalation
 In the following situations, do NOT guess — **STOP and ask the human**:
 - When the scope of the goal is unclear
@@ -147,6 +240,8 @@ Before saving the artifact, verify:
 - [ ] Are all completion criteria verifiable? (No vague wording like "improve" or "make better"?)
 - [ ] Are exclusions explicitly stated in the scope?
 - [ ] Do functional requirements have FR-XXX numbering?
+- [ ] Does the Design section include the chosen approach with rationale?
+- [ ] Has the spec review loop completed (approved or human-overridden)?
 
 ❌ Bad completion criterion: "Stabilize the service"
 ✅ Good completion criterion: "`npm run lint` reports 0 errors, `npm run build` succeeds"
@@ -159,9 +254,10 @@ Before saving the artifact, verify:
   - After Previous Generation Reference → update Background section
   - After Backlog Review → update Background section
   - After Genome Health Check → update Genome Reference section
-  - After Goal + Spec Definition → update Goal, Scope sections
+  - After Brainstorming Design (5a-5e) → update Goal, Scope, Design sections
   - After Genome Gap Analysis → update Backlog section
   - After Requirements Finalization → update Requirements, Completion Criteria sections
+  - After Spec Review Loop → update with any review-driven changes
 - The artifact should reflect the **current state of work at all times**
 - Do NOT wait until the end to write the artifact
 

package/dist/templates/hooks/reap-guide.md

@@ -47,7 +47,7 @@ Objective → Planning → Implementation ⟷ Validation → Completion
 
 | Stage | Description | What it does | Artifact |
 |-------|-------------|--------------|----------|
-| **Objective** | Goal definition | Define this generation's goal + requirements. Reference environment, backlog, genome | `01-objective.md` |
+| **Objective** | Goal definition + brainstorming design | Define goal + requirements through structured brainstorming: clarifying questions, 2-3 approach alternatives, sectional design approval, visual companion (optional), and spec review loop. Reference environment, backlog, genome | `01-objective.md` |
 | **Planning** | Plan formulation | Task decomposition, dependencies, implementation approach | `02-planning.md` |
 | **Implementation** | Implementation | AI+Human collaboration to write code. Record genome defects in backlog when found | `03-implementation.md` |
 | **Validation** | Verification | Run tests, check completion criteria. Can regress to Implementation on failure | `04-validation.md` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c-d-cc/reap",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Recursive Evolutionary Autonomous Pipeline — AI and humans evolve software across generations",
   "type": "module",
   "license": "MIT",