harness-bujang 0.1.0

package/templates/project-template/lib/harness-db/index.ts

@@ -0,0 +1,45 @@
+// Factory + singleton for the active harness-db adapter.
+//
+// Mode is decided once per process by the env var HARNESS_DB:
+//   - "sqlite"   (default) — local file `.harness/chat.db`, no setup
+//   - "supabase"           — cloud Postgres via Supabase, prod-ready
+//
+// To switch later, run `bujang migrate --to=supabase` (or back to sqlite).
+
+import type { HarnessDb, HarnessDbMode } from './types';
+import { createSqliteAdapter } from './sqlite';
+import { createSupabaseAdapter } from './supabase';
+
+export type { HarnessDb, ChatMessage, ListOptions, HarnessDbMode } from './types';
+export { createSqliteAdapter, createSupabaseAdapter };
+
+let _instance: HarnessDb | null = null;
+
+export function getHarnessDb(): HarnessDb {
+  if (_instance) return _instance;
+  _instance = createAdapter(currentMode());
+  return _instance;
+}
+
+export function currentMode(): HarnessDbMode {
+  const m = (process.env.HARNESS_DB ?? 'sqlite').toLowerCase();
+  if (m === 'sqlite' || m === 'supabase') return m;
+  throw new Error(
+    `harness-db: invalid HARNESS_DB="${m}". Expected "sqlite" or "supabase".`,
+  );
+}
+
+export function createAdapter(mode: HarnessDbMode): HarnessDb {
+  switch (mode) {
+    case 'sqlite':   return createSqliteAdapter();
+    case 'supabase': return createSupabaseAdapter();
+  }
+}
+
+/**
+ * Reset the cached singleton. Mainly for tests / migrations that need to
+ * switch adapters mid-process.
+ */
+export function resetHarnessDb(): void {
+  _instance = null;
+}

package/templates/project-template/lib/harness-db/sqlite.ts

@@ -0,0 +1,128 @@
+// SQLite adapter for harness-db.
+//
+// Storage: `.harness/chat.db` in the project root by default.
+// Override via env var `HARNESS_SQLITE_PATH=/absolute/path/to/chat.db`.
+//
+// Requires `better-sqlite3` to be installed in the host project:
+//   npm i better-sqlite3
+//   npm i -D @types/better-sqlite3
+
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import type { HarnessDb, ChatMessage, ListOptions } from './types';
+
+let _db: import('better-sqlite3').Database | null = null;
+
+function resolveDbPath(): string {
+  if (process.env.HARNESS_SQLITE_PATH) return process.env.HARNESS_SQLITE_PATH;
+  return path.join(process.cwd(), '.harness', 'chat.db');
+}
+
+async function ensureDb(): Promise<import('better-sqlite3').Database> {
+  if (_db) return _db;
+
+  // Lazy import so projects that don't use SQLite don't pay the cost.
+  const { default: Database } = await import('better-sqlite3');
+
+  const dbPath = resolveDbPath();
+  const dir = path.dirname(dbPath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  _db = new Database(dbPath);
+  _db.pragma('journal_mode = WAL');
+
+  _db.exec(`
+    CREATE TABLE IF NOT EXISTS harness_messages (
+      id          TEXT PRIMARY KEY,
+      timestamp   TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+      "from"      TEXT NOT NULL,
+      "to"        TEXT NOT NULL,
+      type        TEXT NOT NULL CHECK (type IN ('command', 'feedback', 'info', 'report')),
+      message     TEXT NOT NULL,
+      severity    TEXT CHECK (severity IS NULL OR severity IN ('info', 'warning', 'error')),
+      data        TEXT,
+      created_at  TEXT DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+    );
+
+    CREATE INDEX IF NOT EXISTS harness_messages_timestamp_idx
+      ON harness_messages(timestamp DESC);
+
+    CREATE INDEX IF NOT EXISTS harness_messages_from_to_idx
+      ON harness_messages("from", "to");
+  `);
+
+  return _db;
+}
+
+function rowToMessage(row: any): ChatMessage {
+  return {
+    id: row.id,
+    timestamp: row.timestamp,
+    from: row.from,
+    to: row.to,
+    type: row.type,
+    message: row.message,
+    ...(row.severity ? { severity: row.severity } : {}),
+    ...(row.data ? { data: JSON.parse(row.data) } : {}),
+  };
+}
+
+export function createSqliteAdapter(): HarnessDb {
+  return {
+    async list(options: ListOptions = {}) {
+      const db = await ensureDb();
+
+      if (options.before) {
+        const limit = options.limit ?? 50;
+        const stmt = db.prepare(
+          `SELECT * FROM harness_messages
+             WHERE timestamp < ?
+             ORDER BY timestamp ASC
+             LIMIT ?`,
+        );
+        return stmt.all(options.before, limit).map(rowToMessage);
+      }
+
+      const days = options.days ?? 2;
+      const since = new Date(Date.now() - days * 86_400_000).toISOString();
+      const stmt = db.prepare(
+        `SELECT * FROM harness_messages
+           WHERE timestamp >= ?
+           ORDER BY timestamp ASC`,
+      );
+      return stmt.all(since).map(rowToMessage);
+    },
+
+    async upsert(msg: ChatMessage) {
+      const db = await ensureDb();
+      const stmt = db.prepare(
+        `INSERT INTO harness_messages (id, timestamp, "from", "to", type, message, severity, data)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+           ON CONFLICT(id) DO UPDATE SET
+             timestamp = excluded.timestamp,
+             "from"    = excluded."from",
+             "to"      = excluded."to",
+             type      = excluded.type,
+             message   = excluded.message,
+             severity  = excluded.severity,
+             data      = excluded.data`,
+      );
+      stmt.run(
+        msg.id,
+        msg.timestamp,
+        msg.from,
+        msg.to,
+        msg.type,
+        msg.message,
+        msg.severity ?? null,
+        msg.data ? JSON.stringify(msg.data) : null,
+      );
+    },
+
+    async count() {
+      const db = await ensureDb();
+      const row = db.prepare('SELECT COUNT(*) AS c FROM harness_messages').get() as { c: number };
+      return row.c;
+    },
+  };
+}

package/templates/project-template/lib/harness-db/supabase.ts

@@ -0,0 +1,64 @@
+// Supabase adapter for harness-db.
+//
+// Required env vars:
+//   NEXT_PUBLIC_SUPABASE_URL
+//   SUPABASE_SERVICE_ROLE_KEY
+//
+// Apply migrations 00010_harness_messages.sql and 00025_harness_insert_admin_only.sql
+// against your Supabase project before using.
+
+import { createClient, type SupabaseClient } from '@supabase/supabase-js';
+import type { HarnessDb, ChatMessage, ListOptions } from './types';
+
+let _client: SupabaseClient | null = null;
+
+function client(): SupabaseClient {
+  if (_client) return _client;
+  const url = process.env.NEXT_PUBLIC_SUPABASE_URL;
+  const key = process.env.SUPABASE_SERVICE_ROLE_KEY;
+  if (!url || !key) {
+    throw new Error(
+      'harness-db (supabase): NEXT_PUBLIC_SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY are required',
+    );
+  }
+  _client = createClient(url, key);
+  return _client;
+}
+
+export function createSupabaseAdapter(): HarnessDb {
+  return {
+    async list(options: ListOptions = {}) {
+      let q = client()
+        .from('harness_messages')
+        .select('*')
+        .order('timestamp', { ascending: true });
+
+      if (options.before) {
+        q = q.lt('timestamp', options.before).limit(options.limit ?? 50);
+      } else {
+        const days = options.days ?? 2;
+        const since = new Date(Date.now() - days * 86_400_000).toISOString();
+        q = q.gte('timestamp', since);
+      }
+
+      const { data, error } = await q;
+      if (error) throw new Error(error.message);
+      return (data ?? []) as ChatMessage[];
+    },
+
+    async upsert(msg: ChatMessage) {
+      const { error } = await client()
+        .from('harness_messages')
+        .upsert(msg, { onConflict: 'id' });
+      if (error) throw new Error(error.message);
+    },
+
+    async count() {
+      const { count, error } = await client()
+        .from('harness_messages')
+        .select('id', { count: 'exact', head: true });
+      if (error) throw new Error(error.message);
+      return count ?? 0;
+    },
+  };
+}

package/templates/project-template/lib/harness-db/types.ts

@@ -0,0 +1,35 @@
+// Shared types for the harness-db adapters (sqlite + supabase).
+// Both adapters implement the same `HarnessDb` interface so the API routes
+// don't care which one is active — the choice is made by the HARNESS_DB env var.
+
+export interface ChatMessage {
+  id: string;
+  /** ISO 8601 timestamp string (UTC). */
+  timestamp: string;
+  from: string;
+  to: string;
+  type: 'command' | 'feedback' | 'info' | 'report';
+  message: string;
+  severity?: 'info' | 'warning' | 'error';
+  data?: Record<string, unknown>;
+}
+
+export interface ListOptions {
+  /** When set, return messages newer than `now() - days`. Mutually exclusive with `before`. */
+  days?: number;
+  /** When set, return messages older than this ISO timestamp. Used for infinite scroll. */
+  before?: string;
+  /** Used together with `before`. Defaults to 50. */
+  limit?: number;
+}
+
+export interface HarnessDb {
+  /** List messages. With `days`: recent N days. With `before`: older messages (paginated). */
+  list(options?: ListOptions): Promise<ChatMessage[]>;
+  /** Insert one message. Idempotent on `id`. */
+  upsert(message: ChatMessage): Promise<void>;
+  /** Total count — used for generating the next sequential id. */
+  count(): Promise<number>;
+}
+
+export type HarnessDbMode = 'sqlite' | 'supabase';

package/templates/project-template/migrations/00010_harness_messages.sql

@@ -0,0 +1,56 @@
+-- harness_messages: chat-room messages for the Harness-Bujang multi-agent system
+--
+-- This migration assumes Postgres + a `users` table with a `role` column ('admin' / etc.).
+-- If your schema differs, replace the `EXISTS (...)` predicates with your own admin check.
+--
+-- Idempotent: uses CREATE TABLE IF NOT EXISTS + DROP POLICY IF EXISTS.
+
+CREATE TABLE IF NOT EXISTS public.harness_messages (
+  id          text        PRIMARY KEY,
+  "timestamp" timestamptz NOT NULL DEFAULT now(),
+  "from"      text        NOT NULL,
+  "to"        text        NOT NULL,
+  type        text        NOT NULL CHECK (type IN ('command', 'feedback', 'info', 'report')),
+  message     text        NOT NULL,
+  severity    text        CHECK (severity IS NULL OR severity IN ('info', 'warning', 'error')),
+  data        jsonb,
+  created_at  timestamptz DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS harness_messages_timestamp_idx
+  ON public.harness_messages ("timestamp" DESC);
+
+CREATE INDEX IF NOT EXISTS harness_messages_from_to_idx
+  ON public.harness_messages ("from", "to");
+
+-- Enable Row Level Security
+ALTER TABLE public.harness_messages ENABLE ROW LEVEL SECURITY;
+
+-- ---------------------------------------------------------------------------
+-- Policies
+-- ---------------------------------------------------------------------------
+-- Admins can SELECT all messages.
+-- Adjust the EXISTS subquery below to match your project's admin definition.
+
+DROP POLICY IF EXISTS admin_select_harness_messages ON public.harness_messages;
+CREATE POLICY admin_select_harness_messages
+  ON public.harness_messages FOR SELECT
+  USING (
+    EXISTS (
+      SELECT 1 FROM public.users
+      WHERE users.id = auth.uid()
+        AND users.role = 'admin'
+    )
+  );
+
+-- Initial INSERT policy (further hardened by 00025).
+DROP POLICY IF EXISTS admin_insert_harness_messages ON public.harness_messages;
+CREATE POLICY admin_insert_harness_messages
+  ON public.harness_messages FOR INSERT
+  WITH CHECK (
+    EXISTS (
+      SELECT 1 FROM public.users
+      WHERE users.id = auth.uid()
+        AND users.role = 'admin'
+    )
+  );

package/templates/project-template/migrations/00025_harness_insert_admin_only.sql

@@ -0,0 +1,17 @@
+-- Harden the harness_messages INSERT policy to admin-only.
+--
+-- This replaces any earlier permissive INSERT policy (e.g., authenticated-only)
+-- with a strict admin check. Run this only after 00010.
+
+DROP POLICY IF EXISTS harness_admin_insert ON public.harness_messages;
+
+CREATE POLICY harness_admin_insert
+  ON public.harness_messages
+  FOR INSERT TO authenticated
+  WITH CHECK (
+    EXISTS (
+      SELECT 1 FROM public.users
+      WHERE users.id = auth.uid()
+        AND users.role = 'admin'
+    )
+  );

package/templates/templates/en/AGENT_LEARNING_LOG.seed.md

@@ -0,0 +1,43 @@
+# Agent Learning Log
+
+> Shared record of mistakes and lessons across all teams (Director, dev-team, auditors, verifier-team, consultant).
+> **Mandatory reading at session start.** Append new entries at the bottom (preserve insertion order; don't reverse).
+
+---
+
+## 📐 Format
+
+```markdown
+### YYYY-MM-DD — [team] one-line title
+
+**Context**: 1–2 lines on what was being done
+**Mistake / misjudgment**: what went wrong
+**Root cause**: why it happened (structural or cognitive)
+**Lesson**: how to do it differently next time
+**Files**: file:line (if any)
+```
+
+---
+
+## 📚 Entries
+
+<!-- First entry is added by the init script, or appended by the Director after the first task. -->
+
+### {{TODAY}} — [Director] Harness-Bujang adopted
+
+**Context**: Introduced the Harness-Bujang multi-agent system to this project.
+**Root cause**: Single-agent work has weak review and zero chat visibility — when something stalls, the principal cannot see where.
+**Lesson**: Never skip `{{HARNESS_TABLE}}` INSERTs. Every step must surface in the chat room so the principal can track progress.
+**Files**: `.claude/agents/*.md`, `{{ADMIN_HARNESS_ROUTE}}`
+
+---
+
+## 🎯 Recurring categories (high-attention areas)
+
+Mistakes in these categories must update **both this log AND the relevant agent file** on recurrence:
+
+- DB schema judgment — migration files vs. actual prod schema drift
+- Prose reports — chat INSERTs without markdown bullets
+- Missing chat INSERTs — work step completed but never logged
+- Skipped verification — reporting "done" without going through `verifier-team`
+- Missing audit calls — payment / DB / legal-text work without the relevant audit team

package/templates/templates/en/CLAUDE.md.harness-section.template

@@ -0,0 +1,59 @@
+<!--
+  Harness-Bujang — section template appended to the user's CLAUDE.md.
+  The init script reads this file, fills `{{...}}` placeholders, and appends it.
+-->
+
+## Harness Engineering (Agent Organization)
+
+### Structure
+
+- **Entry point**: Claude Code CLI only. The chat room is observation-only.
+- **Director = a persona of Main Claude** 🎭 (not a real subagent)
+  - Claude Code platform constraint: subagents cannot spawn other subagents
+  - Real team calls and code work are done **by Main Claude directly**
+  - Main Claude reads `.claude/agents/director.md` and takes on the Director's tone and responsibilities
+  - Chat-room INSERTs are **proxied** by Main Claude under the Director's / each team's name
+- **Actual subagents**: `.claude/agents/*.md` — invoked by Main Claude via the `Agent` tool
+  - `dev-team` · `architect-team` · `doc-sync-team` · `code-review-team` · `security-team` · `db-guard-team` · `qa-team` · `verifier-team` · `consultant`
+- **Chat room**: `{{ADMIN_HARNESS_ROUTE}}` — super-admin only (`SUPER_ADMIN_EMAILS` env). Real-time view of `{{HARNESS_TABLE}}`.
+- **Learning log**: `{{LEARNING_LOG_PATH}}` — collective record of mistakes and lessons. Mandatory reading at session start.
+- **Chat message format**: markdown line breaks and bullets required. No prose.
+
+### Flow
+
+```
+Principal's command
+    ↓
+Main Claude (= Director persona)
+    ├─ INSERT into chat as 'director' (receive, plan, dispatch)
+    ├─ Call Agent(dev-team) — Main Claude does this directly
+    ├─ INSERT as 'dev-team' (proxy completion report)
+    ├─ Call Agent(code-review-team / security-team / ...) in parallel
+    ├─ INSERT each team's result on its behalf
+    ├─ Call Agent(verifier-team) as the final gate
+    ├─ INSERT as 'director' (final report)
+    └─ Reply to the principal
+```
+
+Every step writes to `{{HARNESS_TABLE}}` → live in the chat-room UI.
+
+### 🎭 Director persona rules
+
+- **Tone**: polite professional. To the principal "…done"; to teams "please review."
+- **Identity**: Main Claude plays the Director by following `.claude/agents/director.md` — its scope, checklists, and work-mapping table.
+- **Persona guide**: `.claude/agents/director.md` is the only source.
+
+### 🚨 Real-time chat reporting — absolute rule
+
+Every major step must INSERT into `public.{{HARNESS_TABLE}}`. Main Claude proxies each role:
+
+1. Right after receiving — `from='principal' to='director' type='command'`
+2. On dispatch — `from='director' to='dev-team' type='command'`
+3. Team completion — `from='dev-team' to='director' type='report'`
+4. Final report — `from='director' to='principal' type='report'`
+5. Failures / blockers — `severity='warning'` or higher, immediately
+
+Table columns: `id · timestamp · from · to · type · message · severity · data · created_at`
+type CHECK: `command|feedback|info|report`
+Message format: markdown bullets (no prose)
+Details: `.claude/agents/director.md` · `{{LEARNING_LOG_PATH}}`

package/templates/templates/ko/AGENT_LEARNING_LOG.seed.md

@@ -0,0 +1,43 @@
+# 에이전트 집단 학습 로그
+
+> 모든 팀(부장·dev-team·감사팀·검수팀·consultant)이 공유하는 실수·교훈 기록.
+> **세션 시작 시 필독.** 새 항목은 하단에 append (시간 역순 X — 추가 순서 보존).
+
+---
+
+## 📐 형식
+
+```markdown
+### YYYY-MM-DD — [팀명] 한 줄 제목
+
+**상황**: 무엇을 하다가 발생했는지 1~2줄
+**실수/오판**: 무엇이 잘못됐는지
+**원인**: 왜 그렇게 됐는지 (구조적·인지적)
+**교훈**: 다음에 어떻게 다르게 할 것인지
+**파일**: 관련 파일:라인 (있으면)
+```
+
+---
+
+## 📚 항목
+
+<!-- 첫 항목은 init 스크립트가 자동으로 추가하거나, 첫 작업 후 부장이 append 한다. -->
+
+### {{TODAY}} — [부장] 하네스 부장 시스템 도입
+
+**상황**: 본 프로젝트에 하네스 부장 다중 에이전트 시스템 도입.
+**원인**: 코드 작업이 단일 에이전트로는 검수가 약하고, 톡방 가시성 없이는 "어디서 막혔는지" 파악이 어려움.
+**교훈**: 작업마다 `{{HARNESS_TABLE}}` INSERT를 빠뜨리지 말 것. 모든 단계가 톡방에 보여야 대표님이 진행 파악 가능.
+**파일**: `.claude/agents/*.md`, `{{ADMIN_HARNESS_ROUTE}}`
+
+---
+
+## 🎯 자주 반복되는 카테고리 (주의 영역)
+
+이 카테고리에 해당하는 실수는 **재발 시 즉시 본 로그 + 해당 팀 에이전트 파일 둘 다 갱신**:
+
+- DB 스키마 판단 — 마이그레이션 파일 vs prod 실태 불일치
+- 줄글 보고 — 톡방에 마크다운 없이 한 줄 줄글 INSERT
+- 톡방 INSERT 누락 — 작업 단계 진행했는데 기록 안 함
+- 검수 누락 — verifier-team 거치지 않고 "완료" 보고
+- 감사팀 누락 — 결제·DB·법적 문구 등 도메인 작업에 해당 감사팀 호출 안 함

package/templates/templates/ko/CLAUDE.md.harness-section.template

@@ -0,0 +1,59 @@
+<!--
+  하네스 부장 (Harness-Bujang) — 사용자의 CLAUDE.md 에 추가되는 섹션 템플릿.
+  init 스크립트가 이 파일을 읽어 `{{...}}` placeholder를 채운 뒤 본 프로젝트 CLAUDE.md 하단에 append 한다.
+-->
+
+## 하네스 엔지니어링 (에이전트 조직)
+
+### 구조
+
+- **명령 입구**: Claude Code CLI만. 톡방은 관찰 전용
+- **부장 = Main Claude의 페르소나** 🎭 (서브에이전트 아님)
+  - Claude Code 플랫폼 제약: 서브에이전트는 다른 서브에이전트를 스폰 못 함
+  - 실제 팀 호출·코드 작업은 **Main Claude가 직접** 담당
+  - Main Claude가 `.claude/agents/director.md`를 읽고 부장 역할·말투·책임을 인수
+  - 톡방 INSERT는 Main Claude가 부장·팀 명의로 **대행 기록**
+- **실제 서브에이전트**: `.claude/agents/*.md` — Main Claude가 `Agent` 툴로 호출
+  - `dev-team` · `architect-team` · `doc-sync-team` · `code-review-team` · `security-team` · `db-guard-team` · `qa-team` · `verifier-team` · `consultant`
+- **톡방**: `{{ADMIN_HARNESS_ROUTE}}` — 슈퍼어드민(`SUPER_ADMIN_EMAILS` ENV) 전용. `{{HARNESS_TABLE}}` 테이블 실시간 뷰
+- **학습 로그**: `{{LEARNING_LOG_PATH}}` — 실수·교훈 집단 기록. 세션 시작 시 필독
+- **톡방 메시지 포맷**: 마크다운 줄바꿈·들여쓰기·개조식 필수. 줄글 금지
+
+### 흐름
+
+```
+대표님 지시
+    ↓
+Main Claude (= 부장 페르소나)
+    ├─ 톡방 INSERT: from='부장' (지시 접수·계획·분배)
+    ├─ Agent(dev-team) 호출 ← Main Claude가 직접
+    ├─ 톡방 INSERT: from='dev-team' (완료 보고 — Main이 대행)
+    ├─ Agent(code-review-team / security-team / ...) 병렬 호출
+    ├─ 톡방 INSERT: 각 팀 명의 (결과 — Main이 대행)
+    ├─ Agent(verifier-team) 최종 호출
+    ├─ 톡방 INSERT: from='부장' (final report)
+    └─ 대표님께 답변
+```
+
+각 단계마다 `{{HARNESS_TABLE}}` INSERT → 톡방 UI 실시간 반영.
+
+### 🎭 부장 페르소나 규칙
+
+- **말투**: 정중한 표준어 (부장 톤). 대표님께 "~합니다", 팀에 "~부탁드립니다"
+- **정체성**: Main Claude가 부장 역할을 맡으며, `.claude/agents/director.md`의 책임 범위·체크리스트·작업 매핑표를 그대로 실행
+- **페르소나 가이드**: `.claude/agents/director.md` 단독 정의
+
+### 🚨 톡방 실시간 보고 — 절대 규칙
+
+모든 주요 단계에서 `public.{{HARNESS_TABLE}}` INSERT 의무. Main Claude가 각 역할 명의로 대행:
+
+1. 지시 수신 직후 — `from='대표님' to='부장' type='command'`
+2. 착수/분배 시 — `from='부장' to='dev-team' type='command'`
+3. 팀 완료 보고 — `from='dev-team' to='부장' type='report'`
+4. 대표님 최종 보고 — `from='부장' to='대표님' type='report'`
+5. 실패·블로커 — `severity='warning'` 이상으로 즉시
+
+테이블 컬럼: `id · timestamp · from · to · type · message · severity · data · created_at`
+type CHECK: `command|feedback|info|report`
+메시지 포맷: 마크다운 줄바꿈·개조식 (줄글 금지)
+상세: `.claude/agents/director.md` · `{{LEARNING_LOG_PATH}}`