@walwal-harness/cli 1.1.0 → 1.3.0

package/README.md

@@ -46,15 +46,26 @@ Planner → Generator-BE → Evaluator-Func(API-only)
 npm install @walwal-harness/cli
 ```
 
-설치 시 자동으로:
+`postinstall`이 자동으로 프로젝트 루트에 설치합니다:
 - `.harness/` 디렉토리 스캐폴딩 (actions, archive, gotchas)
 - `.claude/skills/` 에 6개 에이전트 스킬 설치
 - `AGENTS.md` 생성 + `CLAUDE.md` 심볼릭 링크
 - 기존 프로젝트면 구조 스캔 → IA-MAP 자동 생성
 
+> **Note:** `npm install` 후 Claude Code 세션을 **재시작**해야 skills가 인식됩니다.
+> Claude Code는 세션 시작 시 `.claude/skills/`를 스캔하므로, 설치 후 `/exit` → 재진입이 필요합니다.
+
+### CLI 명령
+
+```bash
+npx walwal-harness           # 초기화 (postinstall과 동일)
+npx walwal-harness --force   # 강제 재초기화 (기존 파일 덮어쓰기)
+npx walwal-harness --help    # 도움말
+```
+
 ## 사용법
 
-Claude Code에서:
+Claude Code를 **재시작**한 뒤:
 
 ```
 > 하네스 엔지니어링 시작
@@ -159,6 +170,17 @@ your-project/
 | Unit Testing | Jest (BE) + Vitest (FE) |
 | Database | PostgreSQL / SQLite |
 
+## 권장 외부 스킬
+
+하네스는 자체 reference 파일로 기본 가이드를 제공하지만, 아래 외부 스킬을 설치하면 품질이 향상됩니다. 초기화 시 자동으로 설치 여부를 체크하고 안내합니다.
+
+| 스킬 | 설명 | 사용 에이전트 |
+|------|------|-------------|
+| **vercel** | Vercel/Next.js 배포, 성능 최적화, AI SDK | Generator-FE |
+| **web-design-guidelines** | UI/UX 접근성, Web Interface Guidelines | Evaluator-Visual, Generator-FE |
+| **taste-skill** | AI 생성 UI 디자인 품질, AI슬롭 감지 | Evaluator-Visual, Generator-FE |
+| **supanova-design-skill** | 디자인 시스템 규칙, 시각적 일관성 | Evaluator-Visual, Generator-FE |
+
 ## Playwright MCP 설정
 
 Evaluator가 브라우저 테스트를 수행하려면 Playwright MCP가 필요합니다. `~/.mcp.json`에 추가:

package/assets/templates/config.json

@@ -84,6 +84,33 @@
     "gotchas": ".harness/gotchas",
     "progress": ".harness/progress.txt"
   },
+  "recommended_skills": {
+    "comment": "Claude Code에 설치하면 하네스 품질이 향상되는 외부 스킬 목록",
+    "vercel": {
+      "description": "Vercel/Next.js 배포, 성능 최적화, AI SDK 가이드",
+      "used_by": ["generator-frontend"],
+      "install": "claude skill install vercel",
+      "check_path": ".claude/skills/vercel"
+    },
+    "web-design-guidelines": {
+      "description": "UI/UX 접근성, 디자인 리뷰, Web Interface Guidelines",
+      "used_by": ["evaluator-visual", "generator-frontend"],
+      "install": "claude skill install web-design-guidelines",
+      "check_path": ".claude/skills/web-design-guidelines"
+    },
+    "taste-skill": {
+      "description": "AI 생성 UI의 디자인 품질 검증, AI슬롭 패턴 감지",
+      "used_by": ["evaluator-visual", "generator-frontend"],
+      "install": "npx claude-skill install leonxlnx/taste-skill",
+      "check_path": ".claude/skills/taste-skill"
+    },
+    "supanova-design-skill": {
+      "description": "디자인 시스템 규칙, 컴포넌트 패턴, 시각적 일관성",
+      "used_by": ["evaluator-visual", "generator-frontend"],
+      "install": "npx claude-skill install uxjoseph/supanova-design-skill",
+      "check_path": ".claude/skills/supanova-design-skill"
+    }
+  },
   "tech_stack": {
     "backend": {
       "framework": "NestJS (TypeScript)",

package/bin/init.js

@@ -13,13 +13,43 @@ const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
 
-const PROJECT_ROOT = process.cwd();
 const PKG_ROOT = path.resolve(__dirname, '..');
-const HARNESS_DIR = path.join(PROJECT_ROOT, '.harness');
-const CLAUDE_SKILLS_DIR = path.join(PROJECT_ROOT, '.claude', 'skills');
-
 const isAuto = process.argv.includes('--auto');
 const isForce = process.argv.includes('--force');
+const isHelp = process.argv.includes('--help') || process.argv.includes('-h');
+
+// ─────────────────────────────────────────
+// Resolve project root
+// ─────────────────────────────────────────
+// During `npm install` postinstall, cwd is the dependency's own directory
+// inside node_modules, NOT the consumer project root.
+// We detect this and walk up to find the actual project root.
+function resolveProjectRoot() {
+  let cwd = process.cwd();
+
+  // If we're running inside node_modules, walk up to the project root
+  // e.g. /project/node_modules/@walwal-harness/cli → /project
+  const nmIndex = cwd.indexOf(path.sep + 'node_modules' + path.sep);
+  if (nmIndex !== -1) {
+    return cwd.substring(0, nmIndex);
+  }
+
+  // Also handle case where cwd IS a node_modules child (no trailing sep match)
+  if (cwd.includes(`${path.sep}node_modules`)) {
+    const parts = cwd.split(path.sep);
+    const nmIdx = parts.indexOf('node_modules');
+    if (nmIdx > 0) {
+      return parts.slice(0, nmIdx).join(path.sep);
+    }
+  }
+
+  // npx or direct invocation — cwd is the project root
+  return cwd;
+}
+
+const PROJECT_ROOT = resolveProjectRoot();
+const HARNESS_DIR = path.join(PROJECT_ROOT, '.harness');
+const CLAUDE_SKILLS_DIR = path.join(PROJECT_ROOT, '.claude', 'skills');
 
 // ─────────────────────────────────────────
 // Utility
@@ -253,28 +283,137 @@ function checkPlaywrightMcp() {
   log('');
 }
 
+// ─────────────────────────────────────────
+// 6. Recommended skills check
+// ─────────────────────────────────────────
+function checkRecommendedSkills() {
+  const configPath = path.join(HARNESS_DIR, 'config.json');
+  if (!fileExists(configPath)) return;
+
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch (e) { return; }
+
+  const skills = config.recommended_skills;
+  if (!skills) return;
+
+  const missing = [];
+  const found = [];
+
+  for (const [name, info] of Object.entries(skills)) {
+    if (name === 'comment') continue;
+    const checkPath = path.join(PROJECT_ROOT, info.check_path);
+    if (fileExists(checkPath)) {
+      found.push(name);
+    } else {
+      missing.push({ name, ...info });
+    }
+  }
+
+  if (found.length > 0) {
+    log(`Recommended skills installed: ${found.join(', ')}`);
+  }
+
+  if (missing.length > 0) {
+    console.log('');
+    log('╔═══════════════════════════════════════════════════════════╗');
+    log('║  Recommended skills (not installed)                      ║');
+    log('╠═══════════════════════════════════════════════════════════╣');
+    for (const skill of missing) {
+      const agents = skill.used_by.join(', ');
+      log(`║  ${skill.name}`);
+      log(`║    ${skill.description}`);
+      log(`║    Used by: ${agents}`);
+      log(`║    Install: ${skill.install}`);
+      log('║');
+    }
+    log('║  These skills are optional but improve output quality.   ║');
+    log('║  Harness reference files provide baseline guidance       ║');
+    log('║  even without these skills installed.                    ║');
+    log('╚═══════════════════════════════════════════════════════════╝');
+  } else if (found.length > 0) {
+    log('All recommended skills are installed!');
+  }
+}
+
+// ─────────────────────────────────────────
+// Help
+// ─────────────────────────────────────────
+function showHelp() {
+  const pkg = require(path.join(PKG_ROOT, 'package.json'));
+  console.log(`
+╔══════════════════════════════════════╗
+║     walwal-harness v${pkg.version.padEnd(16)}║
+║     AI Agent Harness Engineering     ║
+╚══════════════════════════════════════╝
+
+Usage:
+  npx walwal-harness           Initialize project for harness engineering
+  npx walwal-harness --force   Re-initialize (overwrites existing files)
+  npx walwal-harness --help    Show this help
+
+What it does:
+  1. Scaffolds .harness/ directory (actions, archive, gotchas, config)
+  2. Installs skills to .claude/skills/ (dispatcher, planner, generators, evaluators)
+  3. Copies helper scripts to scripts/
+  4. Creates AGENTS.md + CLAUDE.md symlink
+  5. Checks Playwright MCP configuration
+  6. Checks recommended external skills (Vercel, design skills)
+
+After init:
+  1. Restart Claude Code session (exit and re-enter) for skills to load
+  2. Say "하네스 엔지니어링 시작" or invoke /harness-dispatcher
+`);
+}
+
 // ─────────────────────────────────────────
 // Main
 // ─────────────────────────────────────────
 function main() {
+  if (isHelp) {
+    showHelp();
+    return;
+  }
+
+  const pkg = require(path.join(PKG_ROOT, 'package.json'));
   console.log('');
   console.log('╔══════════════════════════════════════╗');
-  console.log('║     walwal-harness v1.0.0            ║');
+  console.log(`║     walwal-harness v${pkg.version.padEnd(16)}║`);
   console.log('║     AI Agent Harness Engineering     ║');
   console.log('╚══════════════════════════════════════╝');
   console.log('');
 
+  log(`Project root: ${PROJECT_ROOT}`);
+  console.log('');
+
   scaffoldHarness();
   installSkills();
   installScripts();
   setupAgentsMd();
   checkPlaywrightMcp();
+  checkRecommendedSkills();
 
   console.log('');
   log('═══ Initialization Complete ═══');
   log('');
-  log('Start with: "하네스 엔지니어링 시작"');
-  log('Or invoke:  /harness-dispatcher');
+
+  if (isAuto) {
+    // postinstall context — Claude Code is likely already running
+    log('╔═══════════════════════════════════════════════════════════╗');
+    log('║  IMPORTANT: Restart Claude Code for skills to activate!  ║');
+    log('║                                                          ║');
+    log('║  Claude Code discovers skills at session startup.        ║');
+    log('║  Type /exit, then re-enter this directory to begin.      ║');
+    log('║                                                          ║');
+    log('║  Then say: "하네스 엔지니어링 시작"                        ║');
+    log('║  Or invoke: /harness-dispatcher                          ║');
+    log('╚═══════════════════════════════════════════════════════════╝');
+  } else {
+    log('Next steps:');
+    log('  1. Restart Claude Code session (/exit → re-enter directory)');
+    log('  2. Say "하네스 엔지니어링 시작" or invoke /harness-dispatcher');
+  }
   console.log('');
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@walwal-harness/cli",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Production harness for AI agent engineering — Planner, Generator(BE/FE), Evaluator(Func/Visual) with Gotcha management",
   "bin": {
     "walwal-harness": "bin/init.js"