diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index ef0024e..977d274 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -9,8 +9,8 @@ { "name": "harness", "source": "./", - "description": "에이전트 팀 & 스킬 아키텍트. 도메인/프로젝트에 맞는 하네스를 구성하고, 전문 에이전트를 정의하며, 에이전트가 사용할 스킬을 생성하는 메타 스킬.", - "version": "1.2.0" + "description": "에이전트 팀 & 스킬 아키텍트 v2. 도메인/프로젝트에 맞는 하네스를 구성하고, 전문 에이전트를 정의하며, 에이전트가 사용할 스킬을 생성하는 메타 스킬. 워크플로우 오케스트레이션 · 퍼시스턴트 에이전트 협업 · 서브에이전트 위임 3중 실행 모드 지원.", + "version": "2.1.0" } ] } diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index e6d0b9a..2ed3f3a 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "harness", - "description": "The team-architecture factory for Claude Code — a meta-skill that turns a domain description into an agent team and the skills they use, with six pre-defined team-architecture patterns (Pipeline, Fan-out/Fan-in, Expert Pool, Producer-Reviewer, Supervisor, Hierarchical Delegation). Claude Code용 팀 아키텍처 팩토리: 도메인 한 문장을 에이전트 팀과 스킬 세트로 변환하는 메타 스킬.", - "version": "1.2.0", + "description": "The team-architecture factory for Claude Code v2 — a meta-skill that turns a domain description into an agent team and the skills they use. Three native execution modes (Workflow orchestration, persistent named-agent collaboration, sub-agent delegation), six team-architecture patterns, and workflow-native quality patterns (adversarial verification, judge panels, loop-until-dry). Claude Code용 팀 아키텍처 팩토리 v2: 도메인 한 문장을 에이전트 팀과 스킬 세트로 변환하는 메타 스킬.", + "version": "2.1.0", "author": { "name": "robin", "url": "https://github.com/revfactory" @@ -17,6 +17,7 @@ "skill-architect", "meta-skill", "orchestration", + "workflow", "claude-code", "claude-code-plugin", "agent-scaffolding", @@ -26,6 +27,8 @@ "expert-pool", "producer-reviewer", "supervisor", - "hierarchical-delegation" + "hierarchical-delegation", + "adversarial-verification", + "judge-panel" ] } diff --git a/.gitignore b/.gitignore index 40ddbcd..a88a60c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ .DS_Store .claude/ +_workspace/ diff --git a/CHANGELOG.md b/CHANGELOG.md index fbcdeea..bd1b67d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,55 @@ 이 프로젝트는 [Semantic Versioning](https://semver.org/)을 따릅니다. +## [2.1.0] - 2026-07-20 + +### Changed + +- **모델 정책 개편: "세션 모델 상속 기본" → "업무 특성 기반 티어 선택"** — 에이전트 정의 시 업무의 복잡도·작업 기간·자율성·응답 속도 4가지 기준으로 opus(설계·코드 생성·복잡한 분석·교차 검증, 계획·장기 자율 실행) / sonnet(로그 파싱·포맷 변환·단순 수집 등 일상·기계적 업무)을 에이전트별로 선택하도록 변경. 애매하면 sonnet, 무근거 일괄 지정 금지 원칙 유지 +- **버전 정합성 2.1.0 동기화** — `.claude-plugin/plugin.json`·`marketplace.json`·README 뱃지(EN/KO)를 2.1.0으로 통일 + +### Added + +- **`references/model-selection-guide.md`** — 티어별 핵심 역할·적합 업무·선택 상황, Opus vs Sonnet 구분 기준, 하네스 적용 규칙(업무 단위 판단, 계층 분리, 워크플로우 단계별 적용) 상세 가이드 + +## [2.0.0] - 2026-07-19 + +전면 재구축 (ground-up rebuild). v1의 전제였던 실험적 Agent Teams API가 현행 Claude Code에서 사라졌고, 결정적 오케스트레이션을 위한 Workflow 도구가 새로 추가된 환경 변화에 맞춰 모든 것을 다시 설계했다. + +### Breaking / Fixed + +- **`TeamCreate`/`TeamDelete`/`team_name` 전면 제거** — 현행 런타임에 존재하지 않는 API. 세션의 단일 암묵 팀 + `Agent(name:)` + `SendMessage` 구조로 전 템플릿 재작성. v1 오케스트레이터는 이 API를 호출하다 단일 에이전트 실행으로 조용히 퇴화하는 실질적 브로큰 상태였다 +- **`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 의존 제거** — 플래그 안내 문서(`docs/experimental-dependency.md`) 및 모든 참조 삭제. v2는 플래그 없이 동작한다 +- **`model: "opus"` 전 에이전트 강제 정책 폐기** — 세션 모델 상속이 기본. 오버라이드는 근거(기계적 작업의 비용 절감 / 최고 난도 검증)가 있을 때만 명시 +- **README-실체 불일치 해소** — v1 README가 홍보하던 `/harness:evolve` 스킬이 실제로는 존재하지 않았다. v2에서 실제 스킬로 출시 +- **"세션당 한 팀" 제약 및 팀 재구성 절차 삭제** — 제약 자체가 소멸 + +### Added + +- **3중 실행 모드 체계** — 워크플로우 오케스트레이션(신규) / 퍼시스턴트 에이전트 협업(v1 팀 모드 대체) / 서브에이전트 위임. 모드 선택 기준을 "팀 크기"에서 **"제어 흐름의 결정성"**으로 재정의 +- **워크플로우 오케스트레이션 모드** — `Workflow` 도구 기반: `pipeline()`/`parallel()`, 구조화 출력 스키마(파싱 불필요), `budget` 연동 규모 조절, `resumeFromRunId` 부분 재실행, 커스텀 `agentType`, `isolation: worktree` +- **품질 패턴 카탈로그** — 적대적 검증, 관점 분산 검증, 심판 패널, loop-until-dry, 다각 스윕, 완전성 비평가, 침묵 상한 금지 +- **`skills/evolve` (`/harness:evolve`)** — 델타 수집 → 피드백 유형 분류 → 일반화 반영 → 변경 이력 갱신 → 진화 보고의 5단계 진화 스킬. 관찰 기반 진화 신호(반복 피드백, 오케스트레이터 우회 흔적) 감지 포함 +- **v1 → v2 마이그레이션 경로** — Phase 0에서 v1 산출물 자동 감지, `docs/migration-v1-to-v2.md` + `references/execution-modes.md`에 변환 매핑 표 +- **신규 레퍼런스** — `execution-modes.md`(3중 모드 + 마이그레이션), `workflow-recipes.md`(스크립트 스켈레톤 6종 + 함정 12종 체크리스트) +- **데이터 전달 프로토콜에 "구조화 반환" 추가** — 워크플로우 schema 기반 타입 안전 전달을 v2 권장 기본으로 +- **워크플로우 기반 A/B 테스트** — 스킬 검증(with/without)을 워크플로우 스크립트로 구성하는 레시피 +- **에이전트 정의 확장** — 프론트매터 `tools`(읽기 전용 리뷰어 등 도구 제한), `재호출 지침` 섹션 표준화 + +### Changed + +- **6패턴 각각에 v2 권장 실행 모드 매핑** — 팬아웃/파이프라인은 워크플로우 1순위, 감독자는 퍼시스턴트+태스크, 계층 위임은 워크플로우 1단계 중첩 등 +- **오케스트레이터 템플릿 3종 전면 재작성** — A: 워크플로우(정찰→실행→종합, run_meta/resume 포함), B: 퍼시스턴트(스폰+태스크+피드백 루프), C: 서브에이전트 +- **Phase 7 재구성** — 운영/유지보수는 harness 스킬에 유지, 진화(피드백 반영)는 evolve 스킬로 분리 +- 산출물 체크리스트에 v1 잔재 검증·워크플로우 함정 검증 항목 추가 +- `references/agent-design-patterns.md` → `team-patterns.md`로 개편 (품질 패턴 흡수), `team-examples.md` 5종 예시를 v2 문법으로 재작성 + +### Removed + +- **마케팅/사이트 자산 제거** — `harness_banner.png`·`harness_icon.png`·`harness_social.png`·`harness_team.png`(합계 약 9MB), `index.html`(랜딩 페이지), `privacy.html` +- **저장소 운영 부산물 제거** — 런치 캠페인용 `_workspace/` 산출물, 마케팅 에이전트 정의(`.claude/agents/launch-strategist` 등), `docs/experimental-dependency.md` +- README_JA (일본어 README) — 유지보수 부담 대비 효용 저조. EN/KO 2종 유지 + ## [1.2.1] - 2026-04-18 ### Fixed diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f30728b..4f4670c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,211 +1,29 @@ # Contributing to Harness -Thanks for considering a contribution to **Harness** — a Claude Code meta-skill factory that designs agent teams and generates skills. +기여를 환영합니다. 이 문서는 짧습니다 — 규칙보다 원칙을 따릅니다. -This document covers: response SLAs, how to contribute, development setup, PR conventions, commit message rules, code of conduct, and maintainer list. +## 원칙 ---- +1. **스킬은 에이전트를 위한 지시서다.** 사용자용 설명서·마케팅 문구·Claude가 이미 아는 일반 지식은 스킬에 넣지 않는다. +2. **컨텍스트는 공공재다.** SKILL.md 본문 500줄 이내, 세부는 `references/`로. 모든 문장이 토큰 비용을 정당화해야 한다. +3. **Why를 설명한다.** "ALWAYS/NEVER" 대신 이유를 쓴다. 이유를 알면 엣지 케이스에서도 올바르게 판단한다. +4. **현행 런타임만 참조한다.** 실험 플래그, 제거된 API(`TeamCreate` 등), 특정 모델 하드코딩을 PR에 넣지 않는다. 런타임 변경으로 문서가 깨지면 그것이 최우선 수정 대상이다. -## Response SLA (commitments) +## PR 체크리스트 -These are the maintainer response targets for this repository. They are **conservative** so that a small maintainer team can realistically keep them while scaling. +- [ ] 변경이 SKILL.md와 관련 references 간에 일관되는가 (한쪽만 고치지 않았는가) +- [ ] 트리거에 영향을 주는 description 변경이면 should-trigger / near-miss 쿼리로 검증했는가 +- [ ] CHANGELOG.md에 항목을 추가했는가 +- [ ] 버전 정합성: `plugin.json` = `marketplace.json` = README 뱃지 -| Surface | Target | Notes | -|---------|--------|-------| -| PR — 1st response | **< 72h** | Business days. A "1st response" means at minimum a label + one comment acknowledging the PR. | -| Issue triage & labeling | **< 48h** | Every new issue gets `needs-triage` removed and a type label (`bug` / `enhancement` / `question` / `discussion`) within 48h. | -| Bug resolve (P0 / P1) | **< 14d** | P0 = data loss / security / broken install. P1 = common path broken. P2/P3 tracked on roadmap without a hard SLA. | -| Security report | **< 7d** | Initial acknowledgement within 7 days. Patch target 30 days. Please see **Security** section below for the private channel. | -| Release cadence | **every 2 weeks** | Biweekly tag unless there is nothing shippable. P0 fixes may cut an off-schedule patch release. | +## 이슈 -If we miss an SLA, please feel free to ping the issue/PR — that is not rude, it is the agreed feedback loop. +- 버그: 재현 프롬프트 + 기대/실제 동작 + `claude --version` +- 런타임 호환성 깨짐: `compat` 라벨 — 최우선 처리 ---- +## 응답 목표 -## How to Contribute +- PR 1차 응답: 72시간 이내 +- Issue 트리아지: 48시간 이내 -Different kinds of contributions go through different entry points. Pick the one that fits. - -### Bug report - -- Open an issue using the **Bug report** form (`.github/ISSUE_TEMPLATE/bug_report.yml`). -- Required: Claude Code version, `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` flag state, reproduction steps, expected vs actual, OS. -- Small reproductions (< 30 lines) are ideal. If your repro needs a full project, link a public fork. - -### Feature request - -- Open an issue using the **Feature request** form. -- We expect a short "what problem does this solve" paragraph. If you have a proposal, put it in the PR-ready shape (which of the 6 team-architecture patterns does it extend / replace?). - -### Question - -- Open an issue using the **Question** form, **or** start a thread in [GitHub Discussions](https://github.com/revfactory/harness/discussions) if the matter is open-ended. - -### Discussion (RFC-sized ideas) - -- Prefer GitHub Discussions. Only promote to an issue once there is rough consensus on direction. - -### Pull Request - -- See **Pull Request Guidelines** below. -- Small PRs merge faster. Anything > 400 lines of diff should probably have been a Discussion first. - -### Security - -- Do **not** open a public issue for anything that could be abused. -- Email: `robin.hwang@kakaocorp.com` with subject prefix `[harness-security]`. -- We aim to acknowledge within 7 days (see SLA table). - ---- - -## Development Setup - -### Prerequisites - -- Claude Code `v2.x` (Agent Teams API required) -- Node.js `>= 18` (for local tooling used in CI) -- Git - -### Environment flag - -Harness currently requires Claude Code's experimental Agent Teams feature. Set the flag in your shell profile or per-session: - -```bash -export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 -``` - -We track this dependency in `docs/experimental-dependency.md` (if Anthropic promotes the flag to stable, we update the README within 72h per the SLA above). - -### Local plugin link - -To test your changes in a local Claude Code session without publishing to the marketplace: - -```bash -# From your checkout -claude plugin link ./harness - -# Verify -claude plugin list | grep harness -``` - -Unlink with `claude plugin unlink harness` when you're done. - -### Running the meta-skill - -```bash -claude "build a harness for a fintech risk-assessment team" -``` - -Scaffolded agents and skills land under `.claude/agents/` and `.claude/skills/` in the target project. - -### Tests & lints - -- Markdown lint: `npx markdownlint '**/*.md'` -- YAML lint (issue templates & workflows): `npx yaml-lint .github/` -- Skill metadata validation: `python scripts/validate_skills.py` (if present) - -CI runs these on every PR. Local execution is encouraged but not required — we won't block on CI-caught issues that are trivial to fix on merge. - ---- - -## Pull Request Guidelines - -### Branch naming - -Use the `type/short-description` shape: - -| Prefix | Use for | Example | -|--------|---------|---------| -| `feat/` | New user-visible capability | `feat/expert-pool-variance-mode` | -| `fix/` | Bug fix | `fix/agent-teams-flag-detection` | -| `docs/` | Docs-only changes | `docs/quickstart-gemini-section` | -| `refactor/` | Internal structure, no behavior change | `refactor/skill-loader-split` | -| `chore/` | Build, deps, housekeeping | `chore/upgrade-markdownlint` | -| `test/` | Tests only | `test/fan-out-fan-in-e2e` | - -### Commit message language - -- **Korean and English are both accepted.** Write in whichever you are more precise in. -- If the change will appear in the CHANGELOG or release notes, please also provide an English title in the PR description so downstream readers can follow. - -### PR template - -Every PR body is pre-filled from `.github/PULL_REQUEST_TEMPLATE.md`. Please fill in: - -- **Summary** (what & why, 2–4 sentences) -- **Motivation** (link issue, reference research, or 1-line rationale) -- **Scope of change** (checklist of touched surfaces) -- **Tests** (what you ran / added) -- **CHANGELOG** (did you update `CHANGELOG.md`? Y/N/NA) -- **SemVer impact** (patch / minor / major — see next section) - -### Review expectation - -- One approving review from a maintainer is required. -- We try to respond on PRs within 72h (see SLA). If you're blocked, ping. - ---- - -## Commit Message Convention - -We follow a light variant of **Conventional Commits** that maps directly to SemVer. - -``` -()!: - - - -