@walwal-harness/cli 3.3.1 → 3.4.0

package/assets/templates/CONVENTIONS.md

@@ -0,0 +1,61 @@
+# CONVENTIONS.md — Project Conventions
+
+> 이 파일은 프로젝트의 코딩 컨벤션, 선호 패턴, 금지 패턴을 자유 형식으로 정의합니다.
+> 모든 에이전트는 세션 시작 시 이 파일을 읽고 규칙을 적용합니다.
+> 
+> **진실의 원천**: 이 파일이 유일한 컨벤션 정의 소스입니다.
+> Gotcha나 AGENTS.md에 복사하지 마세요 — 에이전트가 직접 이 파일을 참조합니다.
+
+## Architecture
+
+<!-- 아키텍처 수준의 규칙을 여기에 작성하세요 -->
+<!-- 예시:
+- 서비스 간 직접 DB 접근 금지 — 반드시 API 또는 메시지 패턴 사용
+- 모노리스보다 모듈러 아키텍처 선호
+-->
+
+## Code Style
+
+<!-- 코드 스타일 규칙을 여기에 작성하세요 -->
+<!-- 예시:
+- any 타입 사용 금지
+- console.log 대신 structured logger 사용
+- 함수는 30줄 이내, 파일은 300줄 이내
+-->
+
+## Preferred Patterns
+
+<!-- 선호하는 라이브러리, 패턴, 접근 방식 -->
+<!-- 예시:
+- 상태관리: Zustand
+- API 호출: TanStack Query
+- 폼 처리: React Hook Form + Zod
+-->
+
+## Avoid
+
+<!-- 사용을 피해야 하는 패턴, 라이브러리, 접근 방식 -->
+<!-- 예시:
+- CSS-in-JS (styled-components, emotion)
+- Class components
+- Redux (Zustand으로 대체)
+-->
+
+## Testing
+
+<!-- 테스트 관련 규칙 -->
+<!-- 예시:
+- E2E 테스트는 핵심 사용자 플로우만
+- 단위 테스트 커버리지 80% 이상
+- mock 최소화, 실제 DB 사용 선호
+-->
+
+## Naming
+
+<!-- 네이밍 컨벤션 -->
+<!-- 예시:
+- 컴포넌트: PascalCase
+- 변수/함수: camelCase
+- 파일: kebab-case
+- DB 테이블: snake_case
+-->

package/assets/templates/HARNESS.md

@@ -7,6 +7,7 @@
 ## 디렉토리 구조
 
 ```
+CONVENTIONS.md                    # 프로젝트 컨벤션 (사용자 작성, 에이전트 읽기 전용)
 .harness/
 ├── HARNESS.md                  # 이 파일
 ├── config.json                 # 하네스 설정
@@ -152,29 +153,45 @@ pending → draft → reviewed → approved
 "하네스 엔지니어링 시작" 또는 /harness-dispatcher
 ```
 
-#### 2. 이후 세션: harness-next.sh로 안내받기
-```bash
-bash scripts/harness-next.sh
+#### 2. 이후 세션: 새 세션만 열면 자동 진행
+
+에이전트가 완료 후 STOP하면, **새 세션을 시작하기만 하면 됩니다**.
+SessionStart 훅이 자동으로:
+1. 이전 에이전트의 완료 상태 감지
+2. 게이트 체크 실행 (Pre-Eval Gate, 파일 소유권, 아티팩트 선행조건)
+3. `handoff.json` 생성 (prompt, model, thinking_mode, regression 등)
+4. 다음 에이전트 안내 출력
+
+```
+# 새 세션 시작 시 자동 출력 예시:
+# Harness: next → /harness-generator-backend  (sonnet)
 ```
-Feature-level 프로그래스를 출력하고 다음 에이전트를 안내합니다.
 
-#### 3. 다음 세션 시작
-```bash
-# 방법 A: 새 세션에서 스킬 직접 호출
-/harness-generator-backend
+사용자는 안내에 따라 스킬을 호출하면 됩니다.
+
+#### 자동 CLI 실행 (옵션)
 
-# 방법 B: claude CLI 자동 실행
+완전 자동화를 원하면 아래 명령으로 다음 에이전트를 즉시 시작할 수 있습니다:
+
+```bash
 claude --model $(jq -r .model .harness/handoff.json) --prompt "$(jq -r .prompt .harness/handoff.json)"
 ```
 
-#### 4. SessionStart 훅 (자동)
-세션 시작 시 `.claude/settings.json` 훅이 자동으로 현재 프로그래스를 출력합니다.
+#### 디버깅 (수동)
+
+문제가 생겼을 때만 수동으로 상태를 확인합니다:
+
+```bash
+bash scripts/harness-next.sh        # 게이트 체크 + 프로그래스 출력
+jq . .harness/handoff.json          # handoff 내용 확인
+jq . .harness/progress.json         # 현재 상태 확인
+```
 
 ### Session Boundary Protocol
 
 모든 에이전트 스킬에 내장된 프로토콜:
 
-- **On Start**: `progress.json` 읽기 → `agent_status: "running"` 설정 → `handoff.json` 참조
+- **On Start**: `progress.json` 읽기 → `agent_status: "running"` 설정 → `handoff.json` 참조 → `CONVENTIONS.md` 읽기 (존재 시)
 - **On Complete**: `progress.json` 업데이트 → 아티팩트 상태 갱신 → `next_agent` 계산 → **STOP**
 - **On Fail** (Evaluator): `failure` 정보 기록 → `retry_target` 설정 → **STOP**
 - **On Transition**: 파일 소유권 검증 → Pre-Eval Gate (해당 시) → 아티팩트 선행조건 검증

package/assets/templates/config.json

@@ -333,9 +333,17 @@
     "actions": ".harness/actions",
     "archive": ".harness/archive",
     "gotchas": ".harness/gotchas",
+    "conventions": "CONVENTIONS.md",
     "progress_state": ".harness/progress.json",
     "progress_log": ".harness/progress.log"
   },
+  "conventions": {
+    "comment": "CONVENTIONS.md — 사용자가 자유 형식으로 작성하는 프로젝트 컨벤션. 모든 에이전트가 세션 시작 시 직접 읽음. Gotcha/AGENTS.md에 복사하지 않음.",
+    "file": "CONVENTIONS.md",
+    "read_by": "all_agents",
+    "write_by": "user_only",
+    "read_timing": "session_start"
+  },
   "recommended_skills": {
     "comment": "Claude Code에 설치하면 하네스 품질이 향상되는 외부 스킬 목록",
     "vercel": {

package/bin/init.js

@@ -148,6 +148,14 @@ function scaffoldHarness() {
     copyFile(memorySrc, memoryDest);
   }
 
+  // Copy CONVENTIONS.md to project root
+  const conventionsSrc = path.join(PKG_ROOT, 'assets', 'templates', 'CONVENTIONS.md');
+  const conventionsDest = path.join(PROJECT_ROOT, 'CONVENTIONS.md');
+  if (fs.existsSync(conventionsSrc) && (!fileExists(conventionsDest) || isForce)) {
+    copyFile(conventionsSrc, conventionsDest);
+    log('CONVENTIONS.md created — edit to define your project conventions');
+  }
+
   // Create progress.log
   const progressLog = path.join(HARNESS_DIR, 'progress.log');
   if (!fileExists(progressLog) || isForce) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@walwal-harness/cli",
-  "version": "3.3.1",
+  "version": "3.4.0",
   "description": "Production harness for AI agent engineering — Planner, Generator(BE/FE), Evaluator(Func/Visual), optional Brainstormer (requirements refinement). Supports React and Flutter FE stacks.",
   "bin": {
     "walwal-harness": "bin/init.js"

package/scripts/harness-session-start.sh

@@ -1,6 +1,11 @@
 #!/bin/bash
-# harness-session-start.sh — SessionStart 훅 (compact)
-# statusline이 상시 상태를 표시하므로, 여기서는 핵심 안내만 출력.
+# harness-session-start.sh — SessionStart 훅
+# 새 세션 시작 시 자동으로:
+#   1) 이전 에이전트가 completed이면 harness-next.sh를 실행하여 게이트 체크 + handoff 생성
+#   2) handoff.json이 있으면 다음 에이전트 안내
+#   3) statusline이 상시 상태를 표시하므로 여기서는 핵심 안내만 출력
+#
+# 사용자가 수동으로 harness-next.sh를 실행할 필요가 없도록 자동화.
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 LIB="$SCRIPT_DIR/lib/harness-render-progress.sh"
@@ -11,6 +16,8 @@ command -v jq &>/dev/null || exit 0
 
 PROJECT_ROOT="$(resolve_harness_root "." 2>/dev/null)" || exit 0
 PROGRESS="$PROJECT_ROOT/.harness/progress.json"
+CONFIG="$PROJECT_ROOT/.harness/config.json"
+HANDOFF="$PROJECT_ROOT/.harness/handoff.json"
 [ -f "$PROGRESS" ] || exit 0
 
 sprint_status=$(jq -r '.sprint.status // "init"' "$PROGRESS" 2>/dev/null)
@@ -18,17 +25,45 @@ current_agent=$(jq -r '.current_agent // "none"' "$PROGRESS" 2>/dev/null)
 next_agent=$(jq -r '.next_agent // "none"' "$PROGRESS" 2>/dev/null)
 agent_status=$(jq -r '.agent_status // "pending"' "$PROGRESS" 2>/dev/null)
 
-# init 상태: 간단 안내
+# ─────────────────────────────────────────
+# init 상태: 첫 안내
+# ─────────────────────────────────────────
 if [ "$sprint_status" = "init" ]; then
   echo "# Harness ready — say \"하네스 엔지니어링 시작\" or /harness-dispatcher"
   exit 0
 fi
 
-# 활성 세션: 다음 액션만 안내 (상세 프로그래스는 statusline에서 상시 표시)
+# ─────────────────────────────────────────
+# 이전 에이전트가 completed → 자동으로 harness-next 실행
+# (게이트 체크, 아티팩트 검증, handoff.json 생성)
+# ─────────────────────────────────────────
+if [ "$agent_status" = "completed" ] || [ "$agent_status" = "failed" ]; then
+  # harness-next.sh를 백그라운드로 실행하면 안 됨 — 결과가 필요
+  bash "$SCRIPT_DIR/harness-next.sh" "$PROJECT_ROOT" 2>/dev/null
+
+  # harness-next.sh가 progress.json과 handoff.json을 업데이트했으므로 다시 읽기
+  next_agent=$(jq -r '.next_agent // "none"' "$PROGRESS" 2>/dev/null)
+  agent_status=$(jq -r '.agent_status // "pending"' "$PROGRESS" 2>/dev/null)
+fi
+
+# ─────────────────────────────────────────
+# 상태별 안내 출력
+# ─────────────────────────────────────────
 if [ "$agent_status" = "blocked" ]; then
-  echo "# Harness BLOCKED — user intervention required. Run: bash scripts/harness-next.sh"
-elif [ "$next_agent" != "none" ] && [ "$next_agent" != "null" ]; then
-  echo "# Harness: next → /harness-${next_agent}"
+  echo "# Harness BLOCKED — retry limit reached, user intervention required"
+
+elif [ -f "$HANDOFF" ] && [ "$next_agent" != "none" ] && [ "$next_agent" != "null" ]; then
+  # handoff.json에서 모델/모드 정보 읽기
+  handoff_model=$(jq -r '.model // "opus"' "$HANDOFF" 2>/dev/null)
+  handoff_thinking=$(jq -r '.thinking_mode // empty' "$HANDOFF" 2>/dev/null)
+
+  mode_str=""
+  if [ -n "$handoff_thinking" ] && [ "$handoff_thinking" != "null" ]; then
+    mode_str=" /${handoff_thinking}"
+  fi
+
+  echo "# Harness: next → /harness-${next_agent}  (${handoff_model}${mode_str})"
+
 elif [ "$current_agent" != "none" ] && [ "$current_agent" != "null" ]; then
   echo "# Harness: ${current_agent} [${agent_status}]"
 fi

package/scripts/lib/harness-render-progress.sh

@@ -282,14 +282,8 @@ render_progress() {
     fi
 
     echo ""
-    echo "  Next → /harness-${next_agent}  (model: ${next_model}${mode_str})"
-
-    # Build auto CLI command with model flag, reading prompt from handoff.json
-    local model_flag=""
-    if [ "$next_model" != "opus" ]; then
-      model_flag=" --model ${next_model}"
-    fi
-    echo "  Auto → claude${model_flag} --prompt \"\$(jq -r .prompt .harness/handoff.json)\""
+    echo "  Next → /harness-${next_agent}  (${next_model}${mode_str})"
+    echo "  Tip  → 새 세션을 시작하면 자동으로 안내됩니다"
   fi
 
   echo ""