harness-for-yall 1.0.0

package/README.ko.md

@@ -0,0 +1,182 @@
+# harness-for-yall
+
+[Claude Code](https://docs.anthropic.com/en/docs/claude-code)용 멀티에이전트 하네스: 에이전트 25개, 스킬 15개, 5개 팀.
+
+> **[English](./README.md)**
+
+## 이게 뭔데?
+
+Claude Code 에이전트를 5개 전문 팀으로 조직한 사전 설정 패키지. 각 팀은 목적에 맞는 멀티에이전트 오케스트레이션 패턴을 사용한다.
+
+## 팀 구성
+
+| 플러그인 | 패턴 | 에이전트 | 스킬 | 하는 일 |
+|---------|------|:-------:|:----:|--------|
+| `dev-pipeline` | Pipeline | 5 | 1 | 기능 개발 전체: 기획 → FE+BE 병렬 → 리뷰 게이트 → QA |
+| `review-pipeline` | Fan-out / Fan-in | 5 | 1 | 코드 리뷰: 3개 스크리너 병렬 → 모더레이터 → 판정 (SARIF 출력) |
+| `fe-experts` | Expert Pool | 5 | 5 | 프론트엔드: 아키텍트 → 구현/스타일 → 성능 + 테스트 |
+| `be-experts` | Pipeline + Expert Pool | 6 | 5 | 백엔드: 아키텍트 → 구현+검증 → 회복성/프로바이더 → 테스트 |
+| `explore-team` | Hierarchical Delegation | 4 | 3 | 코드베이스 탐색: 스카우트(opus) → 가설 → 증거 → 종합 |
+
+## 설치
+
+### 방법 1 — npx
+
+```bash
+# 전체 설치
+npx @justn-hyeok/claude-code-harness
+
+# 원하는 팀만 골라서
+npx @justn-hyeok/claude-code-harness fe-experts be-experts
+
+# 미리보기
+npx @justn-hyeok/claude-code-harness --dry-run
+
+# 기존 파일 덮어쓰기
+npx @justn-hyeok/claude-code-harness --force
+```
+
+`~/.claude/`에 에이전트/스킬 파일을 복사한다. 의존성 없음.
+
+### 방법 2 — Plugin Marketplace
+
+Claude Code 안에서:
+
+```
+/plugin marketplace add bssm-oss/harness-for-yall
+```
+
+필요한 팀 설치:
+
+```
+/plugin install dev-pipeline@justn-harness
+/plugin install review-pipeline@justn-harness
+/plugin install fe-experts@justn-harness
+/plugin install be-experts@justn-harness
+/plugin install explore-team@justn-harness
+```
+
+### 방법 3 — 쉘 스크립트
+
+```bash
+git clone https://github.com/bssm-oss/harness-for-yall.git
+cd harness-for-yall
+chmod +x install.sh && ./install.sh
+```
+
+## 아키텍처
+
+```
+                    ┌─────────────┐
+                    │   사용자 요청  │
+                    └──────┬──────┘
+                           │
+              ┌────────────┼────────────┐
+              ▼            ▼            ▼
+        ┌──────────┐ ┌──────────┐ ┌──────────┐
+        │  특화 팀   │ │  범용 팀   │ │  분석 팀   │
+        │ fe / be  │ │   dev    │ │ explore  │
+        └────┬─────┘ └────┬─────┘ └────┬─────┘
+             │             │             │
+             ▼             ▼             ▼
+        ┌──────────────────────────────────────┐
+        │          review-pipeline             │
+        │  스크리너×3 → 모더레이터 → 판정관       │
+        └──────────────────────────────────────┘
+```
+
+### 라우팅 규칙
+
+1. **구체성 우선** — 프론트/백엔드 특화 작업이면 `dev-*` 말고 `fe-*` / `be-*` 선택
+2. **체이닝 가능** — `explore → dev → review`로 복잡한 워크플로우 연결
+3. **과잉이면 생략** — 한 줄 수정이나 단순 질문에 하네스는 불필요
+
+### 모델 전략
+
+| 에이전트 | 모델 | 이유 |
+|---------|------|------|
+| `explore-scout` | opus | 아키텍처 분석 오케스트레이션에는 판단력이 중요 |
+| 나머지 전부 | sonnet | 비용 효율 — 구현 작업은 sonnet으로 충분 |
+
+## 팀별 상세
+
+### dev-pipeline (기능 개발)
+
+```
+사용자 요청 → dev-planner (기획)
+                  ↓
+        dev-frontend + dev-backend (병렬 구현)
+                  ↓
+            dev-reviewer (리뷰 게이트)
+                  ↓
+              dev-qa (테스트)
+```
+
+**스킬:** `/dev-feature` — 기능 개발 전체 파이프라인 실행
+
+### review-pipeline (코드 리뷰)
+
+```
+코드/PR → review-screener-1 (정확성)  ──┐
+       → review-screener-2 (보안)     ──┼→ review-moderator → review-judge
+       → review-screener-3 (성능/스타일) ─┘        (통합)         (판정)
+```
+
+**스킬:** `/review-code` — SARIF v2.1.0 호환 리포트 출력
+
+### fe-experts (프론트엔드)
+
+```
+요청 → fe-architect (설계)
+           ├→ fe-implementer (구현)
+           ├→ fe-styler (스타일/접근성)
+           ├→ fe-perf (성능 리뷰)
+           └→ fe-tester (테스트)
+```
+
+**스킬:** `/fe-component`, `/fe-page`, `/fe-refactor`, `/fe-review`, `/fe-test`
+
+### be-experts (백엔드)
+
+```
+요청 → be-architect (API 설계)
+           ├→ be-implementer + be-validator (병렬)
+           ├→ be-resilience (회로 차단기/재시도)
+           ├→ be-provider (LLM 멀티프로바이더)
+           └→ be-tester (계약 테스트)
+```
+
+**스킬:** `/be-api`, `/be-mcp-server`, `/be-pipeline`, `/be-llm-integration`, `/be-observability`
+
+### explore-team (코드베이스 탐색)
+
+```
+질문 → explore-scout (opus, 정찰 + 오케스트레이션)
+           ├→ explore-hypothesizer (경쟁 가설 생성)
+           ├→ explore-evidence (증거 수집)
+           └→ explore-synthesizer (아키텍처 리포트)
+```
+
+**스킬:** `/explore-investigate`, `/explore-quick`, `/explore-hypothesis`
+
+## 커스터마이징
+
+각 에이전트는 YAML frontmatter가 있는 독립 `.md` 파일. 자유롭게 수정 가능:
+
+```yaml
+---
+name: fe-architect
+description: "React/Next.js component architecture"
+model: sonnet          # opus로 바꾸면 업그레이드
+tools:
+  - Read
+  - Glob
+  - Grep
+---
+```
+
+스킬은 `plugins/<팀>/skills/<이름>/SKILL.md` 형태. 새 스킬을 추가하려면 같은 구조로 폴더 만들면 된다.
+
+## 라이선스
+
+MIT

package/README.md

@@ -0,0 +1,149 @@
+# harness-for-yall
+
+Multi-agent harness for [Claude Code](https://docs.anthropic.com/en/docs/claude-code): 25 agents, 15 skills, 5 teams.
+
+> **[한국어 문서](./README.ko.md)**
+
+## What is this?
+
+A pre-configured set of Claude Code agents organized into 5 specialized teams. Each team uses a different multi-agent orchestration pattern optimized for its purpose.
+
+## Teams
+
+| Plugin | Pattern | Agents | Skills | What it does |
+|--------|---------|:------:|:------:|-------------|
+| `dev-pipeline` | Pipeline | 5 | 1 | Full feature dev: planner → FE+BE parallel → reviewer gate → QA |
+| `review-pipeline` | Fan-out / Fan-in | 5 | 1 | Code review: 3 parallel screeners → moderator → judge (SARIF output) |
+| `fe-experts` | Expert Pool | 5 | 5 | Frontend: architect → implementer / styler → perf + tester |
+| `be-experts` | Pipeline + Expert Pool | 6 | 5 | Backend: architect → impl + validator → resilience / provider → tester |
+| `explore-team` | Hierarchical Delegation | 4 | 3 | Codebase exploration: scout(opus) → hypothesizer → evidence → synthesizer |
+
+## Install
+
+### Option 1 — npx
+
+```bash
+# All plugins
+npx @justn-hyeok/claude-code-harness
+
+# Pick specific teams
+npx @justn-hyeok/claude-code-harness fe-experts be-experts
+
+# Preview first
+npx @justn-hyeok/claude-code-harness --dry-run
+
+# Overwrite existing
+npx @justn-hyeok/claude-code-harness --force
+```
+
+Copies agents/skills to `~/.claude/`. Zero dependencies.
+
+### Option 2 — Plugin Marketplace
+
+Inside Claude Code:
+
+```
+/plugin marketplace add bssm-oss/harness-for-yall
+```
+
+Then install what you need:
+
+```
+/plugin install dev-pipeline@justn-harness
+/plugin install review-pipeline@justn-harness
+/plugin install fe-experts@justn-harness
+/plugin install be-experts@justn-harness
+/plugin install explore-team@justn-harness
+```
+
+### Option 3 — Shell script
+
+```bash
+git clone https://github.com/bssm-oss/harness-for-yall.git
+cd harness-for-yall
+chmod +x install.sh && ./install.sh
+```
+
+## Architecture
+
+```
+                    ┌─────────────┐
+                    │  User Task  │
+                    └──────┬──────┘
+                           │
+              ┌────────────┼────────────┐
+              ▼            ▼            ▼
+        ┌──────────┐ ┌──────────┐ ┌──────────┐
+        │ Specific │ │ Generic  │ │ Analysis │
+        │ fe / be  │ │   dev    │ │ explore  │
+        └────┬─────┘ └────┬─────┘ └────┬─────┘
+             │             │             │
+             ▼             ▼             ▼
+        ┌──────────────────────────────────────┐
+        │            review-pipeline           │
+        │  screener×3 → moderator → judge      │
+        └──────────────────────────────────────┘
+```
+
+### Routing Rules
+
+1. **Specificity first** — `fe-*` / `be-*` over `dev-*` when the task is clearly frontend or backend
+2. **Chainable** — `explore → dev → review` for complex workflows
+3. **Skip when overkill** — One-line fixes and simple questions don't need a harness
+
+### Model Strategy
+
+| Agent | Model | Why |
+|-------|-------|-----|
+| `explore-scout` | opus | Orchestration quality matters for architecture analysis |
+| Everything else | sonnet | Cost efficiency — sonnet handles implementation well |
+
+## Structure
+
+```
+.claude-plugin/
+  marketplace.json        # Plugin Marketplace catalog
+plugins/
+  dev-pipeline/           # 5 agents, 1 skill
+    .claude-plugin/plugin.json
+    agents/               # dev-planner, dev-frontend, dev-backend, dev-reviewer, dev-qa
+    skills/dev-feature/
+  review-pipeline/        # 5 agents, 1 skill
+    agents/               # review-screener-{1,2,3}, review-moderator, review-judge
+    skills/review-code/
+  fe-experts/             # 5 agents, 5 skills
+    agents/               # fe-architect, fe-implementer, fe-styler, fe-perf, fe-tester
+    skills/               # fe-component, fe-page, fe-refactor, fe-review, fe-test
+  be-experts/             # 6 agents, 5 skills
+    agents/               # be-architect, be-implementer, be-validator, be-resilience, be-provider, be-tester
+    skills/               # be-api, be-mcp-server, be-pipeline, be-llm-integration, be-observability
+  explore-team/           # 4 agents, 3 skills
+    agents/               # explore-scout, explore-hypothesizer, explore-evidence, explore-synthesizer
+    skills/               # explore-investigate, explore-quick, explore-hypothesis
+bin/install.mjs           # npx CLI
+package.json              # npm config
+install.sh                # Shell installer
+uninstall.sh              # Shell uninstaller
+```
+
+## Customization
+
+Each agent is a standalone `.md` file with YAML frontmatter. Edit freely:
+
+```yaml
+---
+name: fe-architect
+description: "React/Next.js component architecture"
+model: sonnet          # change to opus if you want
+tools:
+  - Read
+  - Glob
+  - Grep
+---
+```
+
+Skills are in `SKILL.md` format inside named folders. Add your own by creating `plugins/<team>/skills/<name>/SKILL.md`.
+
+## License
+
+MIT

package/bin/install.mjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, cpSync, readdirSync, statSync } from 'node:fs';
+import { join, dirname, basename } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { createInterface } from 'node:readline';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PLUGINS_DIR = join(__dirname, '..', 'plugins');
+const CLAUDE_HOME = join(homedir(), '.claude');
+
+function ask(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase());
+    });
+  });
+}
+
+function collectFiles(src, dest, list = []) {
+  if (!existsSync(src)) return list;
+  const entries = readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = join(src, entry.name);
+    const destPath = join(dest, entry.name);
+    if (entry.isDirectory()) {
+      collectFiles(srcPath, destPath, list);
+    } else {
+      list.push({ src: srcPath, dest: destPath });
+    }
+  }
+  return list;
+}
+
+function printHelp() {
+  console.log(`
+  claude-code-harness — install multi-agent harness to ~/.claude/
+
+  Usage:
+    npx claude-code-harness [options] [plugins...]
+
+  Options:
+    --force, -f     Overwrite existing files
+    --dry-run       Preview without copying
+    --help, -h      Show this help
+
+  Plugins:
+    dev-pipeline    Feature development pipeline (5 agents, 1 skill)
+    review-pipeline Code review fan-out/fan-in (5 agents, 1 skill)
+    fe-experts      Frontend expert pool (5 agents, 5 skills)
+    be-experts      Backend expert pool (6 agents, 5 skills)
+    explore-team    Codebase exploration (4 agents, 3 skills)
+
+  Examples:
+    npx claude-code-harness                 # Install all plugins
+    npx claude-code-harness fe-experts      # Install only frontend
+    npx claude-code-harness fe-experts be-experts  # Install FE + BE
+    npx claude-code-harness --dry-run       # Preview all
+`);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const force = args.includes('--force') || args.includes('-f');
+  const dryRun = args.includes('--dry-run');
+  const help = args.includes('--help') || args.includes('-h');
+
+  if (help) {
+    printHelp();
+    process.exit(0);
+  }
+
+  const flags = ['--force', '-f', '--dry-run', '--help', '-h'];
+  const requestedPlugins = args.filter((a) => !flags.includes(a));
+
+  const allPlugins = readdirSync(PLUGINS_DIR, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name);
+
+  const plugins =
+    requestedPlugins.length > 0
+      ? requestedPlugins.filter((p) => {
+          if (!allPlugins.includes(p)) {
+            console.log(`  unknown plugin: ${p} (available: ${allPlugins.join(', ')})`);
+            return false;
+          }
+          return true;
+        })
+      : allPlugins;
+
+  if (plugins.length === 0) {
+    console.log('  no plugins to install.');
+    process.exit(1);
+  }
+
+  console.log('\n  Claude Code Harness Installer\n');
+  console.log(`  Target: ${CLAUDE_HOME}`);
+  console.log(`  Plugins: ${plugins.join(', ')}`);
+  console.log(`  Mode: ${dryRun ? 'dry-run' : force ? 'force' : 'safe (skip existing)'}\n`);
+
+  // Collect all file operations
+  const operations = [];
+
+  for (const plugin of plugins) {
+    const pluginDir = join(PLUGINS_DIR, plugin);
+
+    // agents/ -> ~/.claude/agents/
+    const agentsDir = join(pluginDir, 'agents');
+    if (existsSync(agentsDir)) {
+      operations.push(...collectFiles(agentsDir, join(CLAUDE_HOME, 'agents')));
+    }
+
+    // skills/<name>/SKILL.md -> ~/.claude/skills/<name>.md (flatten)
+    const skillsDir = join(pluginDir, 'skills');
+    if (existsSync(skillsDir)) {
+      const skillFolders = readdirSync(skillsDir, { withFileTypes: true }).filter((d) =>
+        d.isDirectory()
+      );
+      for (const folder of skillFolders) {
+        const skillFile = join(skillsDir, folder.name, 'SKILL.md');
+        if (existsSync(skillFile)) {
+          operations.push({
+            src: skillFile,
+            dest: join(CLAUDE_HOME, 'skills', `${folder.name}.md`),
+          });
+        }
+      }
+    }
+
+    // harness docs (*.md at plugin root, excluding .claude-plugin/)
+    const rootMds = readdirSync(pluginDir)
+      .filter((f) => f.endsWith('.md') && statSync(join(pluginDir, f)).isFile());
+    for (const md of rootMds) {
+      operations.push({
+        src: join(pluginDir, md),
+        dest: join(CLAUDE_HOME, 'harnesses', md),
+      });
+    }
+  }
+
+  // Execute
+  let copied = 0;
+  let skipped = 0;
+
+  for (const op of operations) {
+    const rel = op.dest.replace(CLAUDE_HOME + '/', '');
+    if (dryRun) {
+      console.log(`  [dry-run] ${rel}`);
+      copied++;
+      continue;
+    }
+
+    mkdirSync(dirname(op.dest), { recursive: true });
+
+    if (existsSync(op.dest) && !force) {
+      console.log(`  skip: ${rel}`);
+      skipped++;
+    } else {
+      cpSync(op.src, op.dest);
+      console.log(`  copy: ${rel}`);
+      copied++;
+    }
+  }
+
+  console.log(`\n  Done! ${dryRun ? 'Would copy' : 'Copied'}: ${copied}, Skipped: ${skipped}\n`);
+}
+
+main().catch((err) => {
+  console.error(`Error: ${err.message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "harness-for-yall",
+  "version": "1.0.0",
+  "description": "Multi-agent harness for Claude Code: dev pipeline, code review, frontend/backend experts, codebase exploration",
+  "type": "module",
+  "bin": {
+    "claude-code-harness": "bin/install.mjs"
+  },
+  "files": [
+    "bin/",
+    "plugins/"
+  ],
+  "keywords": [
+    "claude-code",
+    "harness",
+    "agents",
+    "multi-agent",
+    "code-review",
+    "pipeline"
+  ],
+  "author": "justn-hyeok",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/plugins/be-experts/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "be-experts",
+  "version": "1.0.0",
+  "description": "Backend expert pool for Hono/Express with LLM multi-provider support",
+  "author": { "name": "justn-hyeok" },
+  "keywords": ["backend", "api", "hono", "express", "llm", "zod"]
+}

package/plugins/be-experts/agents/be-architect.md

@@ -0,0 +1,138 @@
+---
+name: be-architect
+description: "API design, resource modeling, route structure, middleware layering, and error strategy for Hono/Express backends"
+model: sonnet
+tools:
+  - Read
+  - Glob
+  - Grep
+  - mcp__sequential-thinking__sequentialthinking
+---
+
+# Backend Architect Agent
+
+You are an expert backend architect specializing in Node.js API design with Hono and Express, TypeScript strict mode, and multi-agent LLM orchestration systems.
+
+## Core Responsibilities
+
+1. **API Design**: RESTful resource modeling, RPC endpoint design, URL structure, HTTP method semantics
+2. **Route Structure**: Hono app hierarchy, route groups, base paths, versioning (e.g., `/api/v1/`)
+3. **Middleware Layering**: Auth → validation → rate limiting → error handling → logging
+4. **Error Strategy**: RFC 9457 Problem Details for all error responses
+5. **Task Delegation**: Route implementation tasks to specialist agents
+
+## Architecture Principles
+
+- **Hono First**: Default to Hono for new projects (edge-ready, type-safe). Express only for legacy constraints
+- **Zod Everywhere**: All request/response validation through Zod schemas
+- **Dependency Injection**: Constructor injection or factory patterns — no global singletons
+- **Layered Architecture**: Route → Handler → Service → Repository/Adapter
+- **OpenAPI Auto-gen**: Every endpoint must produce OpenAPI spec (Hono's built-in or zod-openapi)
+
+## Project Structure Convention
+
+```
+src/
+  index.ts                  # App entry point
+  app.ts                    # Hono/Express app factory
+  routes/
+    v1/                     # API version group
+      users.ts              # Resource routes
+      health.ts             # Health check endpoints
+  handlers/                 # Request handlers (thin — delegate to services)
+  services/                 # Business logic
+  adapters/                 # External API adapters (LLM providers, etc.)
+  middleware/
+    auth.ts                 # Authentication
+    validator.ts            # Zod validation middleware
+    error-handler.ts        # RFC 9457 error formatting
+    circuit-breaker.ts      # Circuit breaker wrapper
+    logger.ts               # pino request logging
+  schemas/                  # Zod schemas (shared between validation & OpenAPI)
+  types/                    # TypeScript types/interfaces
+  lib/                      # Utilities, constants, config
+  __tests__/                # Integration tests
+    fixtures/               # Test fixtures
+```
+
+## RFC 9457 Problem Details Standard
+
+All error responses MUST follow this format:
+
+```typescript
+interface ProblemDetail {
+  type: string;        // URI identifying the problem type
+  title: string;       // Short human-readable summary
+  status: number;      // HTTP status code
+  detail?: string;     // Explanation specific to this occurrence
+  instance?: string;   // URI identifying the specific occurrence
+  [key: string]: unknown; // Extension fields
+}
+```
+
+## Middleware Layer Order
+
+```
+1. Request ID (x-request-id generation)
+2. Logger (pino request/response logging)
+3. CORS
+4. Auth (JWT/API key validation)
+5. Rate Limiting
+6. Input Validation (Zod)
+7. → Route Handler →
+8. Error Handler (RFC 9457 formatting)
+```
+
+## Expert Pool Pattern — Delegation Rules
+
+You are the **router** in the Expert Pool pattern. When receiving a task:
+
+1. **Analyze** the requirements
+2. **Design** the API (routes, schemas, middleware, data flow)
+3. **Write spec** to `.claude/specs/be-{slug}.md`
+4. **Delegate** to specialists:
+
+| Task Type | Delegate To | What to Include |
+|-----------|-------------|-----------------|
+| Route/handler implementation | `be-implementer` | Route spec, handler signatures, middleware chain |
+| Schema/validation | `be-validator` | Schema definitions, OpenAPI requirements, error formats |
+| Both impl + validation | `be-implementer` + `be-validator` in parallel | Full spec |
+| External API calls | `be-resilience` | Which services, timeout/retry requirements |
+| LLM provider integration | `be-provider` | Provider list, streaming needs, fallback strategy |
+
+5. After implementation, **mandatory gate**: send to `be-tester` for contract tests.
+
+## Delegation Template
+
+```markdown
+## Task: [Endpoint/Feature Name]
+
+### Architecture Decision
+- Framework: Hono | Express
+- Pattern: REST | RPC
+- Auth: JWT | API Key | None
+- External dependencies: [list]
+
+### Route Spec
+- Method: GET | POST | PUT | DELETE
+- Path: /api/v1/...
+- Request schema: [Zod schema name]
+- Response schema: [Zod schema name]
+- Error cases: [list with RFC 9457 types]
+
+### Middleware Chain
+[ordered list]
+
+### Files to Create/Modify
+- [file path]: [description]
+
+### Constraints
+- [specific requirements]
+```
+
+## When to Escalate
+
+- If the task requires database schema changes — confirm with user
+- If auth strategy is ambiguous — ask user for clarification
+- If the endpoint has no clear resource model — suggest alternatives and confirm
+- If circuit breaker thresholds need tuning — propose defaults and confirm