Metadata-Version: 2.4
Name: oh-my-braincrew
Version: 0.2.15
Summary: Multi-agent orchestration harness for Claude Code
Project-URL: Homepage, https://github.com/teddynote-lab/oh-my-braincrew
Project-URL: Repository, https://github.com/teddynote-lab/oh-my-braincrew
Project-URL: Issues, https://github.com/teddynote-lab/oh-my-braincrew/issues
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: claude-code,multi-agent,orchestration,pipeline
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.12
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic<3.0,>=2.7
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: slack-sdk>=3.33
Provides-Extra: dev
Requires-Dist: pyright>=1.1; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Description-Content-Type: text/markdown

<h1 align="center">oh-my-braincrew</h1>
<p align="center"><strong>Claude Code를 22인 전문 에이전트 팀으로 바꿔주는 하네스 시스템</strong></p>
<p align="center"><strong>한국어</strong></p>
<p align="center">
  <a href="https://pypi.org/project/oh-my-braincrew/"><img src="https://img.shields.io/pypi/v/oh-my-braincrew?style=flat-square&color=blue" alt="PyPI" /></a>
  <img src="https://img.shields.io/badge/Python-3.12-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python 3.12" />
  <img src="https://img.shields.io/badge/Agents-22-orange?style=flat-square" alt="22 Agents" />
  <img src="https://img.shields.io/badge/Skills-37+-green?style=flat-square" alt="37+ Skills" />
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue?style=flat-square" alt="Apache 2.0" /></a>
</p>

---

## 이런 경험 있으신가요?

"Claude에게 기능 구현을 맡겼는데, 테스트 하나 없이 '완료했습니다'라고 하더라고요.."

검증 없는 완성 선언. 막상 실행하면 터지는 코드. 익숙한 상황이죠.

"코드 리뷰를 요청했더니, 방금 자기가 작성한 코드를 자기가 리뷰하는..."

Self-approval 문제. 저자와 리뷰어가 같은 컨텍스트에 있으면 의미 있는 검토가 불가능합니다.

"15개 파일을 동시에 수정하다가, 중간에 뭘 바꿨는지 추적이 안돼요!!"

작업 추적 불가. 어디까지 했는지, 무엇이 남았는지 알 수 없는 상태.

"plan → execute → test → docs → PR을 매번 수동으로 시켜야 해요. 다음 단계 시작하는 것도 제가 해야 하고요."

워크플로우 자동화 부재. 매 단계마다 사람이 개입해야 하는 반자동 작업.

> "Harness는 결국 '나의 일을 줄여주는 역할'이 1번입니다."
>
> — Teddy

oh-my-braincrew는 이 네 가지 문제를 구조적으로 해결합니다.

---

## oh-my-braincrew란?

Claude Code에 22개의 전문 에이전트와 37개 이상의 스킬을 장착하는 플러그인 하네스입니다. 작업을 설명하면 에이전트 팀이 계획부터 PR 생성까지 자동으로 처리합니다.

| Claude Code 단독 | Claude Code + omb |
|---|---|
| Claude가 모든 것을 직접 구현 | 오케스트레이터가 22개 전문 에이전트에 위임 |
| 워크플로우 강제 없음 — 단계 생략 쉬움 | 훅과 규칙으로 6단계 워크플로우 강제 |
| plan/execute/verify를 수동으로 전환 | 세션 핸들러가 상태 머신으로 전체 파이프라인 자동 실행 |
| 검증 게이트 없음 | 철칙: 증거 없이 완료 선언 불가 |
| 같은 컨텍스트에서 자기 리뷰 | 작성자와 리뷰어를 반드시 별도 패스로 분리 |

### 시스템 구조

```mermaid
graph LR
    A["사용자"] --> B["CLAUDE.md\n오케스트레이터"]
    B --> C["Python CLI\nomb"]
    B --> D["Skills\n37+개"]
    B --> E["Agents\n22개"]
    C --> F["Pipeline\n상태 머신"]
    C --> G["Hooks\n6 이벤트"]
```

---

## 설치

### For Claude Code (자동)

아래 프롬프트를 Claude Code에 그대로 붙여넣으면 설치부터 프로젝트 초기화까지 자동으로 진행됩니다.

```
oh-my-braincrew를 설치하고 현재 프로젝트에 초기화해 주세요.
아래 4개의 bash 명령을 순차적으로 실행합니다.

1) curl -fsSL https://raw.githubusercontent.com/teddynote-lab/oh-my-braincrew-release/main/install.sh | sh
2) omb version
3) omb init
4) omb doctor

모두 완료되면 사용자에게 "/omb:setup 으로 첫 설정을 진행할까요?" 라고 물어보세요.
```

### For Human (수동)

직접 터미널에서 설치합니다.

**macOS / Linux:**

```bash
curl -fsSL https://raw.githubusercontent.com/teddynote-lab/oh-my-braincrew-release/main/install.sh | sh
```

**Windows (PowerShell):**

```powershell
irm https://raw.githubusercontent.com/teddynote-lab/oh-my-braincrew-release/main/install.ps1 | iex
```

설치 후 확인:

```bash
omb version
omb doctor
```

`omb doctor`는 LSP 서버(TypeScript, Python, JSON, CSS, HTML, YAML, Go)와 ast-grep(`sg` CLI)가 없으면 자동으로 설치해줍니다.

#### 프로젝트 초기화

Claude Code와 함께 사용할 프로젝트 디렉토리에서 실행합니다.

```bash
cd /path/to/your/project
omb init
```

`omb init`이 배포하는 항목:

| 항목 | 위치 | 역할 |
|------|------|------|
| 설정 파일 | `.omb/config.json` | 프로젝트 설정, 파이프라인 상태 디렉토리 |
| 스킬 | `.claude/skills/` | `/omb` 명령을 위한 37개 스킬 정의 |
| 에이전트 | `.claude/agents/omb/` | 22개 전문 에이전트 정의 |
| 커맨드 | `.claude/commands/omb/` | 슬래시 명령 자동완성 래퍼 |
| 훅 스크립트 | `.claude/hooks/omb/` | 세션 라이프사이클, 보안 정책, 플랜 파일 검증 |
| 규칙 | `.claude/rules/` | 코드 컨벤션, 워크플로우 규칙, 테스트 기준 |
| 설정 | `.claude/settings.json` | 16개 훅 이벤트 연결, Agent Teams 활성화, 권한 설정 |

#### 최신 플러그인 파일 동기화

```bash
omb sync
```

버전 업그레이드 후 스킬/에이전트/훅 파일을 최신으로 맞추려면 `omb sync`를 실행하세요. CLI도 함께 업데이트하려면 `omb update`를 사용합니다.

---

## 첫 설정 (/omb:setup)

`omb init` 후 프로젝트 디렉토리에서 Claude Code 세션을 열고 `/omb:setup`을 실행합니다.

```
/omb:setup
```

`/omb:setup`이 하는 일:

1. **사용자 프로필 수집** — 이름, 역할. `~/.omb/profile.json`에 저장되어 모든 프로젝트에서 재사용됩니다.

2. **Slack 설정 (선택)** — 파이프라인 완료, 단계 완료, 오류 발생 시 Slack 알림을 받을 수 있습니다.
   - `SLACK_BOT_TOKEN` — Slack Bot Token (xoxb-...)
   - `SLACK_SIGNING_SECRET` — Slack Signing Secret
   - `SLACK_CHANNEL` — 알림 받을 채널 ID
   - Braincrew 슬랙 설정 방법: [Slack Bot Token 설정 가이드 (Braincrew only)](https://www.notion.so/teddynote-lab/Slack-Bot-Token-Braincrew-only-33aadc4b25538078bb5accd7105e4598)

3. **언어 설정** — 두 가지 환경 변수로 각각 독립적으로 제어합니다.

   | 변수 | 값 | 기본값 | 효과 |
   |------|-----|--------|------|
   | `OMB_LANGUAGE` | `en`, `ko` | `en` | 에이전트 응답 언어 — 대화, 상태 메시지, 질문 프롬프트 |
   | `OMB_DOC_LANGUAGE` | `en`, `ko` | `en` | 문서 생성 언어 — 플랜 파일, README, 가이드 |

   두 변수를 독립적으로 설정할 수 있습니다. 예를 들어 에이전트는 한국어로 응답하되, 생성되는 플랜 문서는 영어로 작성되게 할 수 있습니다.

   `/omb:setup` 이후에도 `.claude/settings.json`의 `env` 오브젝트에서 직접 변경할 수 있습니다:

   ```json
   {
     "env": {
       "OMB_LANGUAGE": "ko",
       "OMB_DOC_LANGUAGE": "en"
     }
   }
   ```

4. **코드베이스 스캔** — 프로젝트 구조를 분석하여 `CLAUDE.md`와 `PROJECT.md`를 자동 생성합니다.

설정값은 `.claude/settings.json`의 `env` 오브젝트에 저장됩니다.

---

## 간단 요약: 작업 흐름

3단계만 기억하세요.

```mermaid
graph LR
    A["/omb:task\n파이프라인 생성"] --> B["/omb:run --worktree\n자동 실행"]
    B --> C["Slack 알림\n단계 완료 통지"]
```

| 단계 | 명령 | 설명 |
|------|------|------|
| 1 | `/omb:task` | 작업 파이프라인을 생성합니다. 세션 ID가 자동 발급됩니다. |
| 2 | `/omb:run --worktree <session_id>` | 생성된 파이프라인을 격리된 환경에서 자동 실행합니다. |
| 3 | Slack 알림 | 각 단계가 완료될 때마다 Slack으로 알림을 받습니다. |

이것만으로 계획 → 리뷰 → 구현 → 검증 → 문서 → PR 생성까지 자동으로 진행됩니다.

> 각 단계의 상세 설명은 아래 [파이프라인 시작하기](#파이프라인-시작하기-ombtask), [파이프라인 실행](#파이프라인-실행-ombrun), [파이프라인 템플릿 상세](#파이프라인-템플릿-상세) 섹션을 참조하세요.

---

## 파이프라인 시작하기 (/omb:task)

파이프라인은 oh-my-braincrew의 핵심입니다. 작업을 세션 단위로 관리하고, 단계별로 자동 실행됩니다.

Claude Code 세션에서 실행합니다:

```
/omb:task
```

템플릿 선택 화면이 나타납니다:

```
파이프라인 템플릿을 선택해 주세요:

1. Manual — 커스텀 파이프라인을 인터랙티브하게 설계
2. Interview - Plan - Review - Execute - Verify - Document - Create PR
3. ASK_USER - Plan - Review - Execute - Verify - Document - Create PR
4. ASK_USER - Plan - Review
5. ASK_USER - Execute - Verify - Document - Create PR
6. ASK_USER - Review PR - Judge - Plan - Review - Execute - Verify - Document - Create PR
```

**Manual** 을 선택하면 원하는 단계만 골라서 커스텀 파이프라인을 인터랙티브하게 설계할 수 있습니다.

템플릿을 선택하고 이름을 입력하면 세션이 생성됩니다:

```
session_id: 202604060647-xxpo7n
name: JWT refresh endpoint 추가

Wave 0: [ask-user]
Wave 1: [create-plan]
Wave 2: [review-plan]
Wave 3: [execute]
Wave 4: [verify]
Wave 5: [document]
Wave 6: [create-pr]

Saved: .omb/sessions/202604060647-xxpo7n.json
```

### 템플릿 선택 가이드

| 템플릿 | 별칭 | 단계 수 | 사용 시점 |
|--------|------|---------|----------|
| Interview - Plan - Review - Execute - Verify - Document - Create PR | `full` | 8 | 요구사항이 불명확한 신규 기능. 인터뷰로 요구사항을 먼저 정리합니다. |
| ASK_USER - Plan - Review - Execute - Verify - Document - Create PR | `fix` | 7 | 버그 수정, 일반 기능 작업. 가장 많이 사용하는 템플릿입니다. |
| ASK_USER - Plan - Review | `plan` | 3 | 구현 없이 계획 수립만. 팀 검토 전 계획안을 만들 때 유용합니다. |
| ASK_USER - Execute - Verify - Document - Create PR | `exec` | 5 | 이미 승인된 계획을 실행할 때. 플랜 파일이 있으면 바로 구현으로 시작합니다. |
| ASK_USER - Review PR - Judge - Plan - Review - Execute - Verify - Document - Create PR | `review-pr` | 10 | PR 리뷰 후 수정이 필요하면 자동으로 fix 파이프라인을 실행합니다. |

### 체크포인트 - Human Review

체크포인트를 설정하면 해당 단계에서 파이프라인이 일시 정지되고, 사용자가 결과를 확인한 후 다음 단계로 진행됩니다.

기본적으로 `review-plan` 단계는 체크포인트가 설정되어 있습니다 — 리뷰되지 않은 계획이 실행되는 것을 방지합니다.

**설정 방법 1: `/omb:task` 실행 중 설정**

`/omb:task`로 세션을 생성하는 과정에서 "체크포인트를 설정할 단계를 선택하세요" 라는 질문이 나옵니다. 이때 원하는 단계를 선택하면 됩니다.

**설정 방법 2: 세션 JSON 파일에서 직접 변경**

`.omb/sessions/<session_id>.json` 파일을 열고, 원하는 태스크의 `checkpoint` 값을 `true`로 변경합니다:

```json
{
  "tasks": [
    { "step": "review-plan", "checkpoint": true },
    { "step": "execute", "checkpoint": false },
    { "step": "verify", "checkpoint": true }
  ]
}
```

---

## 파이프라인 실행 (/omb:run)

세션을 만든 후 `/omb:run`으로 파이프라인을 구동합니다. `--worktree` 옵션을 사용하면 격리된 환경에서 안전하게 실행됩니다.

```
/omb:run --worktree 202604060647-xxpo7n
```

파이프라인이 실행되면 각 단계 완료 후 진행 상황을 표시합니다:

```
Pipeline: 202604060647-xxpo7n            3/7 done
┌─────┬──────────────┬───────────┐
│   # │ Task         │ Status    │
├─────┼──────────────┼───────────┤
│   1 │ ask-user     │ done      │
│   2 │ create-plan  │ done      │
│   3 │ review-plan  │ done      │
│   4 │ execute      │ active    │
│   5 │ verify       │   --      │
│   6 │ document     │   --      │
│   7 │ create-pr    │   --      │
└─────┴──────────────┴───────────┘
```

### 체크포인트 동작

체크포인트가 설정된 단계(`review-plan` 등)에서 파이프라인이 일시 정지됩니다. 에이전트가 생성한 결과를 확인하고 계속 진행하려면 Claude Code 세션에서 승인 응답을 입력합니다.

체크포인트 없이 전체 파이프라인이 끝까지 자동으로 실행되게 하려면 세션 생성 시 "모두 자동으로 진행"을 선택하거나, 체크포인트를 설정하지 않으면 됩니다.

### 중단된 파이프라인 재개

파이프라인이 중간에 멈춘 경우, 같은 명령으로 다시 실행하면 마지막으로 완료된 단계부터 이어서 진행합니다:

```
/omb:run --worktree 202604060647-xxpo7n
```

파이프라인 상태는 `.omb/sessions/<session_id>.json`에 저장됩니다.

---

## --worktree로 안전하게 작업하기

`--worktree` 옵션은 git worktree를 활용해 메인 브랜치를 건드리지 않고 작업하는 방법입니다.

**왜 worktree를 써야 하나요?**

- **격리** — 실험적인 변경 사항이 현재 작업 중인 메인 브랜치에 영향을 주지 않습니다.
- **병렬 실행** — 여러 파이프라인을 동시에 서로 다른 worktree에서 실행할 수 있습니다.
- **메인 보호** — 파이프라인이 실패해도 메인 체크아웃은 깨끗하게 유지됩니다.
- **추적 용이** — worktree 경로가 session_id와 같아서 `worktrees/202604060647-xxpo7n/`처럼 어느 작업인지 바로 알 수 있습니다.

**병렬 실행 예시:**

터미널 1에서:
```
/omb:run --worktree 202604060647-xxpo7n
```

터미널 2에서 다른 Claude Code 세션:
```
/omb:run --worktree 202604060701-abc123
```

두 파이프라인이 서로 다른 worktree에서 동시에 진행됩니다.

**Worktree 관리 명령어 (터미널에서):**

```bash
omb worktree list                    # 모든 worktree 목록 확인
omb worktree status                  # 활성/일시정지 파이프라인의 worktree 정보
omb worktree clean                   # main에 머지된 브랜치의 worktree 정리
omb worktree remove worktrees/path   # 특정 worktree 제거
```

작업 완료 후 Claude Code 세션에서:

```
/omb:cleanup
```

---

## 파이프라인 템플릿 상세

### fix — 표준 작업 파이프라인

버그 수정, 기능 추가, 리팩토링 등 대부분의 작업에 사용합니다.

```mermaid
graph LR
    A["ask-user\n요구사항 수집"] --> B["create-plan\n계획 수립"]
    B --> C["review-plan\n계획 리뷰\n체크포인트"]
    C --> D["execute\nTDD 구현"]
    D --> E["verify\n검증 및 증거 수집"]
    E --> F["document\n문서 업데이트"]
    F --> G["create-pr\nPR 생성"]
    E -.->|실패| D
```

### full — 요구사항 인터뷰 포함

신규 기능이나 요구사항이 불명확한 작업에 사용합니다. 인터뷰 단계에서 10개 차원(범위, 기능, 제약, 기술 스택, 데이터 모델, API, 에러, 보안, UX, 테스트)에 걸쳐 요구사항을 정리합니다.

```mermaid
graph LR
    A["ask-user"] --> B["interview\n요구사항 인터뷰"]
    B --> C["create-plan"]
    C --> D["review-plan\n체크포인트"]
    D --> E["execute"]
    E --> F["verify"]
    F --> G["document"]
    G --> H["create-pr"]
    F -.->|실패| E
```

### plan — 계획 수립만

구현 없이 계획안만 만들고 싶을 때 사용합니다. 팀 검토나 사전 아키텍처 논의에 적합합니다.

```mermaid
graph LR
    A["ask-user"] --> B["create-plan\nplanner 에이전트"]
    B --> C["review-plan\ncritic 에이전트\n체크포인트"]
```

### exec — 승인된 계획 실행

이미 플랜 파일이 있고 리뷰까지 완료된 경우 바로 구현으로 시작합니다.

```mermaid
graph LR
    A["ask-user\n플랜 파일 경로 입력"] --> B["execute"]
    B --> C["verify"]
    C --> D["document"]
    D --> E["create-pr"]
    C -.->|실패| B
```

### review-pr — PR 리뷰 + 자동 수정

PR을 리뷰하고, 수정이 필요하면 자동으로 계획을 세우고 구현까지 진행합니다. `judge` 단계에서 조건부 분기가 일어납니다.

```mermaid
graph LR
    A["ask-user\nPR 번호"] --> B["review-pr\n다중 에이전트 분석"]
    B --> C{"judge\n분기 결정"}
    C -->|APPROVED| Z["완료 (수정 불필요)"]
    C -->|NEEDS_REVISION| D["create-plan"]
    D --> E["review-plan\n체크포인트"]
    E --> F["execute"]
    F --> G["verify"]
    G --> H["document"]
    H --> I["create-pr"]
```

---

## 개별 스킬 사용법

파이프라인 없이 특정 스킬을 단독으로 사용할 수도 있습니다. 자주 쓰는 스킬 10가지입니다.

| 스킬 | 사용 시점 | 예시 |
|------|----------|------|
| `/omb:plan` | 계획만 빠르게 만들 때 | `/omb:plan Add JWT refresh endpoint` |
| `/omb:review` | 기존 플랜 파일을 리뷰할 때 | `/omb:review .omb/plans/202604060647-xxpo7n.md` |
| `/omb:exec` | 플랜 파일을 바로 실행할 때 | `/omb:exec .omb/plans/202604060647-xxpo7n.md` |
| `/omb:check` | 구현 후 검증할 때 | `/omb:check .omb/plans/202604060647-xxpo7n.md` |
| `/omb:doc` | 문서만 업데이트할 때 | `/omb:doc .omb/plans/202604060647-xxpo7n.md` |
| `/omb:pr` | PR만 만들 때 | `/omb:pr .omb/plans/202604060647-xxpo7n.md` |
| `/omb:interview` | 요구사항을 체계적으로 정리할 때 | `/omb:interview 사용자 인증 시스템 구축` |
| `/omb:review-pr` | PR 번호로 코드 리뷰할 때 | `/omb:review-pr 42` |
| `/omb:resolve-issue` | GitHub 이슈를 자동 수정할 때 | `/omb:resolve-issue --count 3` |
| `/omb:loop` | 주기적 모니터링/수정을 자동화할 때 | `/omb:loop 10m "FastAPI 로그 확인 후 에러 수정"` |

---

## 자주 쓰는 시나리오 가이드

| 상황 | 권장 접근 | 시작 명령 |
|------|----------|----------|
| 버그 수정 | fix 파이프라인 | `/omb:task` → `fix` 선택 |
| 신규 API 엔드포인트 | full 파이프라인 | `/omb:task` → `full` 선택 |
| 아키텍처 검토 후 구현 | plan 후 exec | `/omb:task` → `plan` 선택, 후에 `exec` |
| PR 리뷰 + 자동 수정 | review-pr 파이프라인 | `/omb:task` → `review-pr` 선택 |
| FastAPI 로그 모니터링 자동화 | loop 스킬 | `/omb:loop 10m "로그 확인 및 자동 수정"` |
| GitHub 이슈 일괄 처리 | resolve-issue 스킬 | `/omb:resolve-issue --count 5` |
| 릴리스 배포 | release 스킬 | `/omb:release patch` |
| 요구사항 명세서 작성 | interview 스킬 | `/omb:interview 새 기능 설명` |

---

## 업데이트

### CLI + 플러그인 파일 함께 업데이트

```bash
omb update
```

프로젝트 디렉토리 안에서 실행해야 합니다. CLI를 업그레이드하고 스킬, 에이전트, 훅, 규칙 파일을 최신 버전으로 동기화합니다.

### 플러그인 파일만 동기화 (CLI 업그레이드 없이)

```bash
omb sync
```

---

## 에이전트 카탈로그

### Tier 1 — 핵심 오케스트레이션 (6개)

모든 워크플로우의 기반이 되는 에이전트들입니다.

| 에이전트 | 모델 | 역할 |
|---------|------|------|
| `explore` | haiku | Python + TS/React 코드베이스에서 파일, 심볼, 라우트 탐색 |
| `planner` | opus | 전체 스택에 걸친 태스크 분해 및 아키텍처 결정 |
| `executor` | sonnet | Python, TypeScript, Node.js 구현 (TDD 방식) |
| `verifier` | sonnet | 테스트 실행, 엔드포인트 검증, 상태 확인, 증거 수집 |
| `reviewer` | opus | Python + TypeScript + Node.js 전체 코드 리뷰 |
| `critic` | opus | 플랜/설계 검토 — 아키텍처 결정의 최종 게이트 |

### Tier 2 — 도메인 전문 에이전트 (11개)

특정 기술 스택에 특화된 에이전트들입니다.

| 에이전트 | 모델 | 역할 |
|---------|------|------|
| `api-specialist` | sonnet | FastAPI 라우트, Pydantic 모델, Node.js API, OpenAPI |
| `db-specialist` | sonnet | Postgres 스키마, Alembic 마이그레이션, Redis 캐시/pub-sub |
| `langgraph-engineer` | sonnet | LangChain 체인, LangGraph 상태 머신, RAG, Deep Agents |
| `prompt-engineer` | sonnet | 프롬프트 최적화, few-shot 큐레이션, A/B 비교 |
| `frontend-engineer` | sonnet | React 컴포넌트/훅, Vite 설정, Tailwind CSS |
| `web-designer` | sonnet | 디자인 시스템, 타이포그래피, 색상, 모션 |
| `electron-specialist` | sonnet | 메인/렌더러 프로세스, IPC, 패키징, 데스크탑 보안 |
| `leak-inspector` | sonnet | 메모리 누수, 커넥션 풀 고갈, 리소스 누수 |
| `infra-engineer` | sonnet | Docker, GitHub Actions, 모니터링, Slack 알림 |
| `async-coder` | sonnet | Python asyncio, Node.js 비동기, React 동시성, 레이스 컨디션 |
| `security-reviewer` | opus | OWASP, Electron RCE, XSS, Redis ACL, Postgres RLS |

### Tier 3 — 운영 에이전트 (4개)

| 에이전트 | 모델 | 역할 |
|---------|------|------|
| `debugger` | sonnet | 전체 스택에 걸친 근본 원인 분석 |
| `test-engineer` | sonnet | pytest, vitest, jest, testcontainers, 커버리지 |
| `git-master` | sonnet | 커밋 컨벤션, 브랜치 전략, PR 생성 |
| `doc-writer` | haiku | 기술 문서, README, ADR, 마이그레이션 가이드 |

---

## 스킬 전체 목록

### 워크플로우 스킬

| 스킬 | 설명 |
|------|------|
| `/omb:interview` | 요구사항 수집 — 10개 차원의 다중 라운드 질문 |
| `/omb:plan` | 계획 수립 — 의도 분석, 탐색, 플랜 생성 |
| `/omb:review` | 플랜 리뷰 — 3-13개 도메인 팀, P0-P3 이슈 추적 |
| `/omb:exec` | 계획 실행 — TDD 에이전트, 의존성 기반 웨이브 스케줄링 |
| `/omb:check` | 검증 — 병렬 verifier 에이전트, 증거 수집 |
| `/omb:doc` | 문서 생성 — 병렬 doc-writer 에이전트, i18n README 지원 |
| `/omb:pr` | PR 생성 — 브랜치, 추적 코드, 카테고리 감지, 체크리스트 |
| `/omb:task` | 파이프라인 세션 초기화 |
| `/omb:run` | 파이프라인 세션 실행 |
| `/omb:review-pr` | PR 리뷰 — 다중 에이전트 분석, 구조화된 판정 |
| `/omb:resolve-issue` | GitHub 이슈 자동 해결 — 병렬 worktree 파이프라인 |
| `/omb:loop` | 반복 작업 루프 — 인터벌 실행, 서브 파이프라인 지원 |

### 유틸리티 스킬

| 스킬 | 설명 |
|------|------|
| `/omb:setup` | 최초 설정 — 사용자 프로필, Slack 설정, CLAUDE.md 생성 |
| `/omb:release` | 릴리스 파이프라인 — 버전 업, 체인지로그, 태그, PyPI 배포 |
| `/omb:feedback` | 피드백 제출 — `gh` CLI로 GitHub 이슈 생성 |
| `/omb:cleanup` | 워크스페이스 정리 — worktree 안전 종료 |
| `/omb:prompt` | 프롬프트 엔지니어링 레퍼런스 (P1-P8 패턴) |
| `/omb:react` | React 품질 체크리스트 — 훅, 접근성, 성능, TypeScript |
| `/omb:design` | 디자인 시스템 레퍼런스 — 타이포그래피, 색상, 모션 |

---

## LangChain/LangGraph 레퍼런스 스킬

`langgraph-engineer` 에이전트가 자동으로 참조하거나, 사용자가 직접 조회할 수 있습니다. 모델 호출 없이 레퍼런스 내용만 로드하는 read-only 스킬들입니다.

| 스킬 | 내용 |
|------|------|
| `/omb:lc-framework-selection` | 프레임워크 선택 가이드 — LangChain vs LangGraph vs Deep Agents |
| `/omb:lc-langchain-deps` | 패키지 버전, 설치, 환경 설정 |
| `/omb:lc-langchain-fundamentals` | create_agent(), @tool, 미들웨어, 구조화 출력 |
| `/omb:lc-langchain-middleware` | HITL 미들웨어, Command resume, 커스텀 훅 |
| `/omb:lc-langchain-rag` | RAG 파이프라인 — 로더, 스플리터, 임베딩, 벡터 스토어 |
| `/omb:lc-langgraph-fundamentals` | StateGraph, 노드, 엣지, Command, Send, 스트리밍 |
| `/omb:lc-langgraph-persistence` | 체크포인터, thread_id, 타임 트래블, Store |
| `/omb:lc-langgraph-hitl` | interrupt(), Command(resume), 승인/검증 워크플로우 |
| `/omb:lc-deep-agents-core` | create_deep_agent(), 하네스, SKILL.md 형식 |
| `/omb:lc-deep-agents-memory` | StateBackend, StoreBackend, FilesystemMiddleware |
| `/omb:lc-deep-agents-orchestration` | SubAgentMiddleware, TodoList, HITL |

---

## FAQ

**`omb version`이 실행되지 않아요.**

`which omb`로 경로를 확인하세요. 설치 스크립트가 바이너리를 배치한 경로가 PATH에 포함되어 있는지 확인합니다. 터미널을 재시작하거나 `source ~/.zshrc` (또는 `~/.bashrc`)를 실행해보세요.

**파이프라인이 중간에 멈췄어요.**

세션 파일을 확인합니다:
```bash
cat .omb/sessions/<session_id>.json | python3 -m json.tool | grep status
```
`stalled` 상태면 수동 개입이 필요합니다. 오류 메시지를 확인하고 해당 단계의 에이전트를 직접 호출하거나, 체크포인트를 해제하고 다시 실행해보세요.

**worktree가 너무 많이 쌓였어요.**

main에 머지된 브랜치의 worktree를 정리합니다:
```bash
omb worktree clean
```
특정 worktree를 직접 제거:
```bash
omb worktree remove worktrees/<session_id>
```

**스킬이 `/` 자동완성에 안 보여요.**

`omb init`이 올바르게 실행되었는지 확인하세요. `.claude/commands/omb/` 디렉토리에 커맨드 파일이 있어야 자동완성에 나타납니다. `omb sync`로 최신 파일을 다시 배포해보세요.

**업데이트는 어떻게 하나요?**

프로젝트 디렉토리에서 `omb update`를 실행하면 CLI와 플러그인 파일이 함께 최신화됩니다.

---

## Deep Dive

### 6단계 워크플로우 상세

| 단계 | 에이전트 | 내용 | 산출물 |
|------|---------|------|--------|
| 1. Plan | planner (opus) | 태스크 목록, 에이전트 배정, 리스크, 검증 기준이 포함된 구조화된 플랜 작성 | `.omb/plans/<session_id>.md` |
| 2. Review | critic (opus) | 독립적인 플랜 리뷰 + 필수 사전 부검(pre-mortem). 최대 2회 수정 | APPROVED / NEEDS REVISION / BLOCKED |
| 3. Execute | executor (sonnet) | TDD 방식 구현: 스캐폴딩 → 테스트(red) → 코드(green) → 통합 | 통과하는 테스트 + 구현 |
| 4. Verify | verifier (sonnet) | 테스트 실행, 출력 확인, 계약 검증, 증거 리포트 생성 | 검증 리포트 |
| 5. Document | doc-writer (haiku) | 섹션 단위 문서 업데이트, ADR, 마이그레이션 가이드 | 업데이트된 문서 |
| 6. Create PR | git-master (sonnet) | 브랜치 + 커밋 컨벤션 + `gh` CLI로 구조화된 PR 생성 | Pull Request |

### 파이프라인 상태 머신

```mermaid
stateDiagram-v2
    [*] --> active : omb task init
    active --> active : advance (APPROVED)
    active --> stalled : advance (FAILED, 재시도 소진)
    active --> completed : 마지막 태스크 완료
    stalled --> active : 수동 개입 후 재시작
    completed --> [*]
```

### 디렉토리 구조

```
.omb/
├── config.json          # 프로젝트 설정 및 추적 코드 카운터
├── sessions/            # 파이프라인 세션 상태 (JSON)
├── plans/               # 플랜 파일 (<session_id>.md)
├── verifications/       # 검증 기록
├── prs/                 # PR 기록
├── reviews/             # PR 리뷰 기록
├── documents/           # 문서 생성 기록
└── loops/               # 루프 상태

.claude/
├── agents/omb/          # 22개 에이전트 정의
├── skills/              # 37개 이상 스킬 정의
├── commands/omb/        # 슬래시 명령 자동완성 래퍼
├── hooks/omb/           # 훅 스크립트 (6개 이벤트)
├── rules/               # 코드 컨벤션, 워크플로우 규칙
└── settings.json        # 훅 연결, 권한 설정

worktrees/
└── <session_id>/        # 격리된 git worktree
```

---

<p align="center">
  질문이나 피드백이 있으시면 <code>omb feedback "메시지"</code>를 실행하거나 <a href="https://github.com/teddynote-lab/oh-my-braincrew/issues">이슈를 열어주세요</a>.
</p>
