@uzysjung/agent-harness 26.83.0

package/templates/skills/spec-scaling/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: spec-scaling
+description: "Detects when SPEC.md or PRD.md exceeds 300 lines and proposes feature-based splitting with a master route document. Use when SPEC.md grows too large to be effectively used as a single document."
+---
+
+# Spec Scaling
+
+## When to Use
+
+SPEC.md 또는 PRD.md가 300줄을 초과했을 때 자동 트리거.
+
+## Process
+
+1. 현재 SPEC.md/PRD.md의 줄 수를 확인한다.
+2. 300줄 초과 시 기능별 분리를 제안한다 (SPEC와 PRD 둘 다 동일 패턴):
+
+### SPEC 분리 (기능별)
+```
+docs/
+├── SPEC.md                    # 마스터 — 공통 규칙 + 각 기능 파일 라우트
+├── specs/
+│   ├── auth.md                # 인증/인가 기능 스펙
+│   ├── dashboard.md           # 대시보드 기능 스펙
+│   └── payment.md             # 결제 기능 스펙
+```
+
+### PRD 분리 (제품 영역별)
+```
+docs/
+├── PRD.md                     # 마스터 — 비전, 사용자, 큰 그림 + 영역 파일 라우트
+└── PRD/                       # 영역별 세부 사양
+    ├── platform-common.md     # 플랫폼 공통 (인증, 권한, 인프라)
+    ├── feature-screener.md    # 스크리너 영역
+    ├── feature-portfolio.md   # 포트폴리오 영역
+    └── feature-simulator.md   # 시뮬레이터 영역
+```
+
+> Vantage 프로젝트의 `.claude/PRD/` 구조를 일반화한 것 (도메인 비종속). 본 패턴에서는 `docs/PRD/` 하위에 위치.
+> 두 패턴 모두 **마스터 = 인덱스 + 공통**, **하위 = 독립 참조 가능 단위** 원칙.
+
+3. 마스터 SPEC.md 구조:
+
+```markdown
+# SPEC: [프로젝트명]
+
+## 공통 규칙
+[전체 적용 Boundaries, Tech Stack, DO NOT CHANGE]
+
+## 기능별 스펙
+- [인증/인가](specs/auth.md)
+- [대시보드](specs/dashboard.md)
+- [결제](specs/payment.md)
+```
+
+4. 마스터 PRD.md 구조:
+
+```markdown
+# PRD: [프로젝트명]
+
+## 1. 비전 / Personas / NSM
+[North Star 요약 (없으면 생략)]
+
+## 2. 영역별 사양
+- [Platform Common](PRD/platform-common.md) — 인증/권한/인프라
+- [Feature: Screener](PRD/feature-screener.md)
+- [Feature: Portfolio](PRD/feature-portfolio.md)
+
+## 3. 영역 간 의존성
+- Screener → Portfolio (선택 결과 전달)
+- All → Platform Common (인증 의존)
+```
+
+5. **인간 승인 후에만 분리 실행**. 자동 분리 금지.
+
+## Rules
+
+- 공통 규칙(Boundaries, Tech Stack, DO NOT CHANGE)은 마스터에 유지.
+- 각 하위 파일은 독립적으로 참조 가능해야 한다 — 다른 파일을 읽지 않아도 의미 통해야 함.
+- 영역/기능 간 의존성은 마스터에 명시.
+- 분리 후 기존 SPEC.md/PRD.md는 마스터로 변환 (삭제 아님).
+- 하위 파일도 다시 300줄 초과하면 sub-area로 추가 분리 (재귀 적용).
+
+## When to Split SPEC vs PRD
+
+| 경우 | 분리 대상 |
+|------|---------|
+| 비즈니스 맥락 / 사용자 시나리오가 큰 비중 | PRD 우선 분리 |
+| 기술 스펙이 핵심 (API, 데이터 모델, AC) | SPEC 우선 분리 |
+| 둘 다 큰 경우 | PRD를 영역별로, SPEC를 기능별로 (서로 cross-link) |

package/templates/skills/strategic-compact/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: strategic-compact
+description: Suggests manual context compaction at logical intervals to preserve context through task phases rather than arbitrary auto-compaction.
+origin: ECC
+---
+
+# Strategic Compact Skill
+
+Suggests manual `/compact` at strategic points in your workflow rather than relying on arbitrary auto-compaction.
+
+## When to Activate
+
+- Running long sessions that approach context limits (200K+ tokens)
+- Working on multi-phase tasks (research → plan → implement → test)
+- Switching between unrelated tasks within the same session
+- After completing a major milestone and starting new work
+- When responses slow down or become less coherent (context pressure)
+
+## Why Strategic Compaction?
+
+Auto-compaction triggers at arbitrary points:
+- Often mid-task, losing important context
+- No awareness of logical task boundaries
+- Can interrupt complex multi-step operations
+
+Strategic compaction at logical boundaries:
+- **After exploration, before execution** — Compact research context, keep implementation plan
+- **After completing a milestone** — Fresh start for next phase
+- **Before major context shifts** — Clear exploration context before different task
+
+## How It Works
+
+The `suggest-compact.js` script runs on PreToolUse (Edit/Write) and:
+
+1. **Tracks tool calls** — Counts tool invocations in session
+2. **Threshold detection** — Suggests at configurable threshold (default: 50 calls)
+3. **Periodic reminders** — Reminds every 25 calls after threshold
+
+## Hook Setup
+
+Add to your `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit",
+        "hooks": [{ "type": "command", "command": "node ~/.claude/skills/strategic-compact/suggest-compact.js" }]
+      },
+      {
+        "matcher": "Write",
+        "hooks": [{ "type": "command", "command": "node ~/.claude/skills/strategic-compact/suggest-compact.js" }]
+      }
+    ]
+  }
+}
+```
+
+## Configuration
+
+Environment variables:
+- `COMPACT_THRESHOLD` — Tool calls before first suggestion (default: 50)
+
+## Compaction Decision Guide
+
+Use this table to decide when to compact:
+
+| Phase Transition | Compact? | Why |
+|-----------------|----------|-----|
+| Research → Planning | Yes | Research context is bulky; plan is the distilled output |
+| Planning → Implementation | Yes | Plan is in TodoWrite or a file; free up context for code |
+| Implementation → Testing | Maybe | Keep if tests reference recent code; compact if switching focus |
+| Debugging → Next feature | Yes | Debug traces pollute context for unrelated work |
+| Mid-implementation | No | Losing variable names, file paths, and partial state is costly |
+| After a failed approach | Yes | Clear the dead-end reasoning before trying a new approach |
+
+## What Survives Compaction
+
+Understanding what persists helps you compact with confidence:
+
+| Persists | Lost |
+|----------|------|
+| CLAUDE.md instructions | Intermediate reasoning and analysis |
+| TodoWrite task list | File contents you previously read |
+| Memory files (`~/.claude/memory/`) | Multi-step conversation context |
+| Git state (commits, branches) | Tool call history and counts |
+| Files on disk | Nuanced user preferences stated verbally |
+
+## Best Practices
+
+1. **Compact after planning** — Once plan is finalized in TodoWrite, compact to start fresh
+2. **Compact after debugging** — Clear error-resolution context before continuing
+3. **Don't compact mid-implementation** — Preserve context for related changes
+4. **Read the suggestion** — The hook tells you *when*, you decide *if*
+5. **Write before compacting** — Save important context to files or memory before compacting
+6. **Use `/compact` with a summary** — Add a custom message: `/compact Focus on implementing auth middleware next`
+
+## Token Optimization Patterns
+
+### Trigger-Table Lazy Loading
+Instead of loading full skill content at session start, use a trigger table that maps keywords to skill paths. Skills load only when triggered, reducing baseline context by 50%+:
+
+| Trigger | Skill | Load When |
+|---------|-------|-----------|
+| "test", "tdd", "coverage" | tdd-workflow | User mentions testing |
+| "security", "auth", "xss" | security-review | Security-related work |
+| "deploy", "ci/cd" | deployment-patterns | Deployment context |
+
+### Context Composition Awareness
+Monitor what's consuming your context window:
+- **CLAUDE.md files** — Always loaded, keep lean
+- **Loaded skills** — Each skill adds 1-5K tokens
+- **Conversation history** — Grows with each exchange
+- **Tool results** — File reads, search results add bulk
+
+### Duplicate Instruction Detection
+Common sources of duplicate context:
+- Same rules in both `~/.claude/rules/` and project `.claude/rules/`
+- Skills that repeat CLAUDE.md instructions
+- Multiple skills covering overlapping domains
+
+### Context Optimization Tools
+- `token-optimizer` MCP — Automated 95%+ token reduction via content deduplication
+- `context-mode` — Context virtualization (315KB to 5.4KB demonstrated)
+
+## Related
+
+- [The Longform Guide](https://x.com/affaanmustafa/status/2014040193557471352) — Token optimization section
+- Memory persistence hooks — For state that survives compaction
+- `continuous-learning` skill — Extracts patterns before session ends

package/templates/skills/strategic-compact/suggest-compact.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+# Strategic Compact Suggester
+# Runs on PreToolUse or periodically to suggest manual compaction at logical intervals
+#
+# Why manual over auto-compact:
+# - Auto-compact happens at arbitrary points, often mid-task
+# - Strategic compacting preserves context through logical phases
+# - Compact after exploration, before execution
+# - Compact after completing a milestone, before starting next
+#
+# Hook config (in ~/.claude/settings.json):
+# {
+#   "hooks": {
+#     "PreToolUse": [{
+#       "matcher": "Edit|Write",
+#       "hooks": [{
+#         "type": "command",
+#         "command": "~/.claude/skills/strategic-compact/suggest-compact.sh"
+#       }]
+#     }]
+#   }
+# }
+#
+# Criteria for suggesting compact:
+# - Session has been running for extended period
+# - Large number of tool calls made
+# - Transitioning from research/exploration to implementation
+# - Plan has been finalized
+
+# Track tool call count (increment in a temp file)
+# Use CLAUDE_SESSION_ID for session-specific counter (not $$ which changes per invocation)
+SESSION_ID="${CLAUDE_SESSION_ID:-${PPID:-default}}"
+COUNTER_FILE="/tmp/claude-tool-count-${SESSION_ID}"
+THRESHOLD=${COMPACT_THRESHOLD:-50}
+
+# Initialize or increment counter
+if [ -f "$COUNTER_FILE" ]; then
+  count=$(cat "$COUNTER_FILE")
+  count=$((count + 1))
+  echo "$count" > "$COUNTER_FILE"
+else
+  echo "1" > "$COUNTER_FILE"
+  count=1
+fi
+
+# Suggest compact after threshold tool calls
+if [ "$count" -eq "$THRESHOLD" ]; then
+  echo "[StrategicCompact] $THRESHOLD tool calls reached - consider /compact if transitioning phases" >&2
+fi
+
+# Suggest at regular intervals after threshold
+if [ "$count" -gt "$THRESHOLD" ] && [ $((count % 25)) -eq 0 ]; then
+  echo "[StrategicCompact] $count tool calls - good checkpoint for /compact if context is stale" >&2
+fi

package/templates/skills/ui-visual-review/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: ui-visual-review
+description: "Captures screenshots of key UI flows after E2E tests pass, runs an agent-side first-pass diff (regressions, console errors, layout shifts), then surfaces a checklist for the user's final approval. Use after /uzys:test passes on a UI track (csr-*, ssr-*, full). Adapts the GoalTrack screenshot-review pattern into a repeatable workflow."
+---
+
+# UI Visual Review
+
+## Purpose
+
+E2E 테스트가 PASS 했어도 시각적 회귀(layout shift, 색상/간격 변화, 빈 화면, 잘림)는 functional test가 못 잡는다. 본 skill은:
+
+1. 핵심 사용자 화면을 자동 캡처
+2. 이전 baseline과 diff
+3. 에이전트가 명백한 regression 1차 판정
+4. 사용자가 최종 승인 → 새 baseline 채택 또는 수정 요청
+
+GoalTrack의 `docs/screenshots/` 수동 패턴(mvp-home / v3-search / v4-wiki 등)을 자동화한 형태.
+
+## When to Invoke
+
+| 트리거 | 행동 |
+|--------|------|
+| `/uzys:test` PASS + UI Track(csr-*/ssr-*/full) | 본 skill 호출 권유 |
+| `/uzys:review` UI 변경 PR | visual diff 결과 review 입력으로 |
+| 의도적 디자인 변경 후 baseline 갱신 | "approve all" 옵션 |
+| Track이 data/tooling/executive | **skip** — UI 없음 |
+
+## Pre-conditions
+
+- Playwright 또는 chrome-devtools MCP 사용 가능 (UI Track 설치 시 기본 포함)
+- 앱이 로컬에서 기동 가능 (예: `pnpm dev`, `docker-compose up`)
+- 핵심 화면 URL 리스트가 정의됨 (없으면 본 skill 첫 실행 시 사용자 질의)
+
+## Process
+
+### 1. 화면 리스트업 (한 번만)
+
+`docs/visual-pages.json` 부재 시 사용자에게 핵심 화면을 묻는다 (5-10개 권장):
+
+```json
+{
+  "base_url": "http://localhost:3000",
+  "pages": [
+    { "id": "login", "path": "/login", "wait_for": "form" },
+    { "id": "home", "path": "/", "wait_for": "main", "auth": "user1" },
+    { "id": "detail", "path": "/items/sample", "auth": "user1" },
+    { "id": "settings", "path": "/settings", "auth": "user1" }
+  ],
+  "viewports": [
+    { "name": "desktop", "width": 1440, "height": 900 },
+    { "name": "mobile",  "width": 375,  "height": 812 }
+  ]
+}
+```
+
+`auth` 키는 `docs/visual-auth.example.json`(별도 시크릿)에서 매핑.
+
+### 2. 캡처
+
+각 page × viewport 조합으로 스크린샷 캡처. chrome-devtools MCP 사용 예:
+
+```
+for page in pages:
+  navigate_page({url: base_url + page.path})
+  wait_for({text: page.wait_for})
+  take_screenshot({fullPage: true})
+  → 저장: docs/screenshots/<branch-or-date>/<page.id>__<viewport.name>.png
+```
+
+저장 경로 규칙: `docs/screenshots/<phase>/<page_id>__<viewport>.png`. `phase`는 git branch 이름 또는 `YYYY-MM-DD-HHmm`.
+
+### 3. Diff (baseline 대비)
+
+baseline 위치: `docs/screenshots/baseline/`. 첫 실행이면 현재 캡처가 baseline.
+
+비교 방식 (간단 → 정밀 순):
+- **L1 (해시)**: `sha256` 비교. 같으면 PASS, 다르면 L2.
+- **L2 (pixelmatch)**: `pixelmatch` 또는 ImageMagick `compare -metric AE`. threshold(예: 0.5%) 이내 PASS.
+- **L3 (시각 검토)**: L2 fail 시 에이전트가 두 이미지를 LLM 입력으로 보고 차이 서술.
+
+L1만 구현해도 50% 가치. L2는 의존성 추가.
+
+### 4. 에이전트 1차 리뷰 (자동)
+
+L2/L3 fail이거나 차이가 임계 이상이면 에이전트가 다음 휴리스틱으로 명백한 regression 판정:
+
+| 시그널 | 분류 |
+|--------|------|
+| 빈 화면 / 흰 페이지 | **REGRESSION** |
+| 콘솔 에러 (chrome-devtools `list_console_messages`) | **REGRESSION** |
+| 핵심 컴포넌트(navbar, main content) 누락 | **REGRESSION** |
+| 색상/간격 미세 변화 | **CHANGED** (사용자 판단) |
+| 의도된 카피/레이아웃 변경 | **EXPECTED** (커밋 메시지 매칭) |
+
+### 5. 결과 보고
+
+`docs/visual-review-<phase>.md` 생성:
+
+```markdown
+# Visual Review — 2026-04-20
+
+## Summary
+- 8 pages × 2 viewports = 16 captures
+- PASS (no diff): 12
+- CHANGED (review needed): 3
+- REGRESSION: 1
+
+## REGRESSION
+- `home__desktop`: 콘솔 에러 "Cannot read properties of undefined" + main 영역 빈 화면
+
+## CHANGED
+- `login__mobile`: 버튼 색상 변경 (의도 추정 — git diff에 button.primary 수정 발견)
+- `settings__desktop`: spacing 변화
+
+## PASS
+- (생략)
+```
+
+### 6. 사용자 승인 게이트
+
+사용자가 `docs/visual-review-<phase>.md` 보고 다음 중 결정:
+
+- **REGRESSION 있음** → 수정 후 재실행 (Revision Gate)
+- **CHANGED만 있음** → 항목별 approve 또는 reject. approve 시 baseline 업데이트
+- **PASS만 있음** → 자동 baseline 업데이트 가능
+
+## Output
+
+- `docs/screenshots/<phase>/*.png` — 캡처본
+- `docs/screenshots/baseline/*.png` — 승인된 baseline
+- `docs/visual-review-<phase>.md` — diff 리포트
+
+## Integration with Workflow
+
+- **`/uzys:test`**: UI Track + `docs/visual-pages.json` 존재 시 PASS 후 본 skill 자동 호출 권유
+- **`/uzys:review`**: visual-review-<phase>.md 가 있으면 review 입력으로 흡수. REGRESSION 1건이라도 있으면 Review Gate 차단
+- **`/uzys:auto`**: revision loop에 포함 (REGRESSION → 수정 → 재캡처 → 재diff)
+
+## Anti-Patterns
+
+- **사용자 승인 없이 baseline 자동 갱신** — 의도하지 않은 regression이 영구화. 항상 명시적 approve 필요
+- **모든 페이지 다 캡처 (50+)** — 노이즈 폭증. 핵심 5-10개로 시작
+- **viewport 1개만** — mobile 깨짐 놓침. desktop + mobile 최소 2개
+- **L3(LLM 시각 비교) 매번 호출** — 비용. L1/L2에서 못 거른 것만 L3
+- **screenshots/ 디렉토리 git에 커밋 X** — 회귀 비교 불가. `docs/screenshots/baseline/`은 커밋, `<phase>/`는 gitignore
+
+## Examples
+
+GoalTrack 프로젝트의 수동 패턴 (참고):
+- `docs/screenshots/mvp-home-empty.png`, `mvp-home-list.png` — 같은 화면 다른 상태
+- `crypto-365d-after-fix.png`, `crypto-365d-round2.png` — 수정 round별 보존
+- `shared_portfolio.png`, `shared_simulation.png` — 기능별 핵심 화면
+
+본 skill은 그 패턴을 자동화 + diff + 에이전트 사전 판정 추가.

package/templates/skills/verification-loop/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: verification-loop
+description: "A comprehensive verification system for Claude Code sessions."
+origin: ECC
+---
+
+# Verification Loop Skill
+
+A comprehensive verification system for Claude Code sessions.
+
+## When to Use
+
+Invoke this skill:
+- After completing a feature or significant code change
+- Before creating a PR
+- When you want to ensure quality gates pass
+- After refactoring
+
+## Verification Phases
+
+### Phase 1: Build Verification
+```bash
+# Check if project builds
+npm run build 2>&1 | tail -20
+# OR
+pnpm build 2>&1 | tail -20
+```
+
+If build fails, STOP and fix before continuing.
+
+### Phase 2: Type Check
+```bash
+# TypeScript projects
+npx tsc --noEmit 2>&1 | head -30
+
+# Python projects
+pyright . 2>&1 | head -30
+```
+
+Report all type errors. Fix critical ones before continuing.
+
+### Phase 3: Lint Check
+```bash
+# JavaScript/TypeScript
+npm run lint 2>&1 | head -30
+
+# Python
+ruff check . 2>&1 | head -30
+```
+
+### Phase 4: Test Suite
+```bash
+# Run tests with coverage
+npm run test -- --coverage 2>&1 | tail -50
+
+# Check coverage threshold
+# Target: 80% minimum
+```
+
+Report:
+- Total tests: X
+- Passed: X
+- Failed: X
+- Coverage: X%
+
+### Phase 5: Security Scan
+```bash
+# Check for secrets
+grep -rn "sk-" --include="*.ts" --include="*.js" . 2>/dev/null | head -10
+grep -rn "api_key" --include="*.ts" --include="*.js" . 2>/dev/null | head -10
+
+# Check for console.log
+grep -rn "console.log" --include="*.ts" --include="*.tsx" src/ 2>/dev/null | head -10
+```
+
+### Phase 6: Diff Review
+```bash
+# Show what changed
+git diff --stat
+git diff HEAD~1 --name-only
+```
+
+Review each changed file for:
+- Unintended changes
+- Missing error handling
+- Potential edge cases
+
+## Output Format
+
+After running all phases, produce a verification report:
+
+```
+VERIFICATION REPORT
+==================
+
+Build:     [PASS/FAIL]
+Types:     [PASS/FAIL] (X errors)
+Lint:      [PASS/FAIL] (X warnings)
+Tests:     [PASS/FAIL] (X/Y passed, Z% coverage)
+Security:  [PASS/FAIL] (X issues)
+Diff:      [X files changed]
+
+Overall:   [READY/NOT READY] for PR
+
+Issues to Fix:
+1. ...
+2. ...
+```
+
+## Continuous Mode
+
+For long sessions, run verification every 15 minutes or after major changes:
+
+```markdown
+Set a mental checkpoint:
+- After completing each function
+- After finishing a component
+- Before moving to next task
+
+Run: /verify
+```
+
+## Integration with Hooks
+
+This skill complements PostToolUse hooks but provides deeper verification.
+Hooks catch issues immediately; this skill provides comprehensive review.

package/templates/skills/verification-loop/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Verification Loop"
+  short_description: "Build, test, lint, typecheck verification"
+  brand_color: "#10B981"
+  default_prompt: "Run verification: build, test, lint, typecheck, security"
+policy:
+  allow_implicit_invocation: true

package/templates/track-mcp-map.tsv

@@ -0,0 +1,15 @@
+# track-mcp-map.tsv — Track별 MCP 서버 매핑 데이터
+# v26.12.0 — setup-harness.sh의 .mcp.json 조립 case문 외재화 (deep-research 권장)
+#
+# 형식 (탭 구분):
+#   <mcp_name>	<track_pattern>	<command>	<args_json>
+#
+# - mcp_name: .mcp.json의 mcpServers[키]
+# - track_pattern: any_track 패턴 (csr-*|full 같은 bash glob)
+# - command: 실행 명령 (npx 등)
+# - args_json: jq 인자 배열 (JSON 형식)
+#
+# 신규 MCP 추가 시: 이 파일에 1줄 추가만 하면 setup-harness.sh 수정 불필요.
+# 주석 (#) 라인은 무시.
+railway-mcp-server	csr-supabase|csr-fastify|csr-fastapi|ssr-htmx|ssr-nextjs|full	npx	["-y", "@railway/mcp-server"]
+supabase	csr-supabase|full	npx	["-y", "@supabase/mcp-server"]