Repository: team-attention/plugins-for-claude-natives
Branch: main
Commit: fd9c20754dba
Files: 147
Total size: 633.9 KB

Directory structure:
gitextract_chnom6f9/

├── .claude-plugin/
│   ├── marketplace.json
│   └── plugin.json
├── .gitignore
├── LICENSE
├── README.ko.md
├── README.md
└── plugins/
    ├── agent-council/
    │   ├── .claude-plugin/
    │   │   └── plugin.json
    │   ├── AGENTS.md
    │   ├── CLAUDE.md
    │   ├── README.ko.md
    │   ├── README.md
    │   ├── SKILL.md
    │   ├── bin/
    │   │   └── install.js
    │   ├── council.config.yaml
    │   ├── package.json
    │   ├── scripts/
    │   │   ├── council-job-worker.js
    │   │   ├── council-job.js
    │   │   ├── council-job.sh
    │   │   └── council.sh
    │   └── skills/
    │       └── agent-council/
    │           ├── SKILL.md
    │           ├── references/
    │           │   ├── config.md
    │           │   ├── examples.md
    │           │   ├── host-ui.md
    │           │   ├── overview.md
    │           │   ├── requirements.md
    │           │   └── safety.md
    │           └── scripts/
    │               ├── council-job-worker.js
    │               ├── council-job.js
    │               ├── council-job.sh
    │               └── council.sh
    ├── clarify/
    │   ├── .claude-plugin/
    │   │   └── plugin.json
    │   └── skills/
    │       ├── metamedium/
    │       │   ├── SKILL.md
    │       │   └── references/
    │       │       └── alan-kay-quotes.md
    │       ├── unknown/
    │       │   ├── SKILL.md
    │       │   └── references/
    │       │       ├── playbook-template.md
    │       │       └── question-design.md
    │       └── vague/
    │           └── SKILL.md
    ├── dev/
    │   ├── .claude-plugin/
    │   │   └── plugin.json
    │   ├── CLAUDE.md
    │   ├── agents/
    │   │   ├── codebase-explorer.md
    │   │   ├── decision-synthesizer.md
    │   │   ├── docs-researcher.md
    │   │   └── tradeoff-analyzer.md
    │   └── skills/
    │       ├── dev-scan/
    │       │   └── SKILL.md
    │       └── tech-decision/
    │           ├── SKILL.md
    │           └── references/
    │               ├── evaluation-criteria.md
    │               └── report-template.md
    ├── doubt/
    │   ├── .claude-plugin/
    │   │   └── plugin.json
    │   ├── README.md
    │   └── hooks/
    │       ├── hooks.json
    │       └── scripts/
    │           ├── doubt-detector.sh
    │           └── doubt-validator.sh
    ├── fetch-tweet/
    │   ├── .claude-plugin/
    │   │   └── plugin.json
    │   ├── README.md
    │   └── skills/
    │       └── fetch-tweet/
    │           ├── SKILL.md
    │           └── scripts/
    │               └── fetch_tweet.py
    ├── gmail/
    │   ├── .claude-plugin/
    │   │   └── plugin.json
    │   ├── README.md
    │   └── skills/
    │       └── gmail/
    │           ├── .gitignore
    │           ├── SKILL.md
    │           ├── accounts.yaml.example
    │           ├── assets/
    │           │   ├── accounts.default.yaml
    │           │   ├── email-templates.md
    │           │   └── signatures.md
    │           ├── pyproject.toml
    │           ├── references/
    │           │   ├── cli-usage.md
    │           │   ├── search-queries.md
    │           │   └── setup-guide.md
    │           └── scripts/
    │               ├── core/
    │               │   ├── __init__.py
    │               │   ├── batch_processor.py
    │               │   ├── cache_manager.py
    │               │   ├── quota_manager.py
    │               │   └── retry_handler.py
    │               ├── gmail_client.py
    │               ├── list_messages.py
    │               ├── manage_labels.py
    │               ├── read_message.py
    │               ├── send_message.py
    │               └── setup_auth.py
    ├── google-calendar/
    │   ├── .claude-plugin/
    │   │   └── plugin.json
    │   ├── README.md
    │   └── skills/
    │       └── google-calendar/
    │           ├── SKILL.md
    │           ├── examples/
    │           │   ├── parallel-fetch.md
    │           │   └── quick-query.md
    │           ├── pyproject.toml
    │           └── scripts/
    │               ├── calendar_client.py
    │               ├── fetch_events.py
    │               ├── manage_events.py
    │               └── setup_auth.py
    ├── interactive-review/
    │   ├── .claude-plugin/
    │   │   └── plugin.json
    │   ├── .mcp.json
    │   ├── CLAUDE.md
    │   ├── README.md
    │   ├── mcp-server/
    │   │   ├── requirements.txt
    │   │   ├── server.py
    │   │   └── web_ui.py
    │   └── skills/
    │       └── review/
    │           └── SKILL.md
    ├── kakaotalk/
    │   ├── .claude-plugin/
    │   │   └── plugin.json
    │   ├── README.md
    │   ├── scripts/
    │   │   ├── kakao_read.py
    │   │   └── kakao_send.py
    │   └── skills/
    │       └── kakaotalk/
    │           └── SKILL.md
    ├── podcast/
    │   ├── .claude-plugin/
    │   │   └── plugin.json
    │   ├── README.md
    │   └── skills/
    │       └── podcast/
    │           ├── SKILL.md
    │           └── scripts/
    │               ├── convert_mp4.py
    │               ├── generate_tts.py
    │               └── upload_youtube.py
    ├── say-summary/
    │   ├── .claude-plugin/
    │   │   └── plugin.json
    │   ├── README.md
    │   ├── hooks/
    │   │   └── hooks.json
    │   ├── requirements.txt
    │   └── scripts/
    │       ├── say-summary.py
    │       └── setup.sh
    ├── session-wrap/
    │   ├── .claude-plugin/
    │   │   └── plugin.json
    │   ├── README.md
    │   ├── agents/
    │   │   ├── automation-scout.md
    │   │   ├── doc-updater.md
    │   │   ├── duplicate-checker.md
    │   │   ├── followup-suggester.md
    │   │   └── learning-extractor.md
    │   ├── commands/
    │   │   └── wrap.md
    │   └── skills/
    │       ├── history-insight/
    │       │   ├── SKILL.md
    │       │   ├── references/
    │       │   │   └── session-file-format.md
    │       │   └── scripts/
    │       │       └── extract-session.sh
    │       ├── session-analyzer/
    │       │   ├── SKILL.md
    │       │   ├── references/
    │       │   │   ├── analysis-patterns.md
    │       │   │   └── common-issues.md
    │       │   └── scripts/
    │       │       ├── extract-hook-events.sh
    │       │       ├── extract-subagent-calls.sh
    │       │       └── find-session-files.sh
    │       └── session-wrap/
    │           ├── SKILL.md
    │           └── references/
    │               └── multi-agent-patterns.md
    ├── team-assemble/
    │   ├── .claude-plugin/
    │   │   └── plugin.json
    │   ├── README.md
    │   └── skills/
    │       └── team-assemble/
    │           ├── SKILL.md
    │           └── references/
    │               ├── agents.md
    │               ├── enable-agent-teams.md
    │               ├── examples.md
    │               └── prompt-templates.md
    └── youtube-digest/
        ├── .claude-plugin/
        │   └── plugin.json
        ├── README.md
        └── skills/
            └── youtube-digest/
                ├── SKILL.md
                ├── references/
                │   ├── deep-research.md
                │   └── quiz-patterns.md
                └── scripts/
                    ├── extract_metadata.sh
                    └── extract_transcript.sh

================================================
FILE CONTENTS
================================================

================================================
FILE: .claude-plugin/marketplace.json
================================================
{
  "name": "team-attention-plugins",
  "owner": {
    "name": "Team Attention",
    "url": "https://github.com/team-attention"
  },
  "description": "Claude Code plugins for power users by Team Attention",
  "plugins": [
    {
      "name": "agent-council",
      "description": "Collect and synthesize opinions from multiple AI agents (Gemini, GPT, Codex)",
      "source": "./plugins/agent-council"
    },
    {
      "name": "clarify",
      "description": "Three lenses for clarity: vague requirements to specs, strategy blind spots via Known/Unknown quadrants, and content vs form leverage analysis",
      "source": "./plugins/clarify"
    },
    {
      "name": "interactive-review",
      "description": "Interactive markdown review with web UI for visual plan/document approval",
      "source": "./plugins/interactive-review"
    },
    {
      "name": "say-summary",
      "description": "Speaks a short summary of Claude's response using macOS TTS (Korean/English)",
      "source": "./plugins/say-summary"
    },
    {
      "name": "youtube-digest",
      "description": "Summarize YouTube videos with transcript, insights, Korean translation, and quizzes",
      "source": "./plugins/youtube-digest"
    },
    {
      "name": "google-calendar",
      "description": "Multi-account Google Calendar integration with parallel querying and conflict detection",
      "source": "./plugins/google-calendar"
    },
    {
      "name": "session-wrap",
      "description": "Session wrap-up workflow with multi-agent analysis for documentation, automation, learning, and follow-up",
      "source": "./plugins/session-wrap"
    },
    {
      "name": "dev",
      "description": "Developer workflow tools: community scanning, technical decision-making",
      "source": "./plugins/dev"
    },
    {
      "name": "kakaotalk",
      "description": "Send and read KakaoTalk messages on macOS using Accessibility API",
      "source": "./plugins/kakaotalk"
    },
    {
      "name": "doubt",
      "description": "Force Claude to re-validate when you have doubts (!doubt)",
      "source": "./plugins/doubt"
    },
    {
      "name": "gmail",
      "description": "Multi-account Gmail integration - read, search, send, and manage emails with 5-step sending workflow",
      "source": "./plugins/gmail"
    },
    {
      "name": "team-assemble",
      "description": "Dynamically assemble expert agent teams for complex tasks using Claude Code's agent teams feature",
      "source": "./plugins/team-assemble"
    },
    {
      "name": "podcast",
      "description": "Generate Korean podcast episodes from any source (URLs, tweets, articles) with OpenAI TTS and YouTube auto-upload",
      "source": "./plugins/podcast"
    },
    {
      "name": "fetch-tweet",
      "description": "Fetch full tweet text, author info, and engagement data from X/Twitter URLs without authentication (uses FxEmbed)",
      "source": "./plugins/fetch-tweet"
    }
  ]
}


================================================
FILE: .claude-plugin/plugin.json
================================================
{
  "name": "plugins-for-claude-natives",
  "version": "0.1.0",
  "description": "Claude Code 네이티브 사용자를 위한 유틸리티 플러그인 모음",
  "author": {
    "name": "Team Attention",
    "url": "https://github.com/team-attention"
  },
  "repository": "https://github.com/team-attention/plugins-for-claude-natives"
}


================================================
FILE: .gitignore
================================================
# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
*$py.class

# C extensions
*.so

# Distribution / packaging
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
*.egg-info/
*.egg

# PyInstaller
*.manifest
*.spec

# Installer logs
pip-log.txt
pip-delete-this-directory.txt

# Unit test / coverage reports
htmlcov/
.tox/
.nox/
.coverage
.coverage.*
.cache
nosetests.xml
coverage.xml
*.cover
*.py,cover
.hypothesis/
.pytest_cache/

# Translations
*.mo
*.pot

# Environments
.env
.venv
env/
venv/
ENV/
env.bak/
venv.bak/

# mypy
.mypy_cache/
.dmypy.json
dmypy.json

# Pyre
.pyre/

# pytype
.pytype/

# Cython
cython_debug/

# IDE
.idea/
.vscode/
*.swp
*.swo
*~

# OS
.DS_Store
Thumbs.db

# Videos
*.mp4


================================================
FILE: LICENSE
================================================
MIT License

Copyright (c) 2025 Team Attention

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


================================================
FILE: README.ko.md
================================================
# Plugins for Claude Natives

Claude Code의 기능을 확장하고 싶은 파워 유저를 위한 플러그인 모음입니다.

## 목차

- [빠른 시작](#빠른-시작)
- [플러그인 목록](#플러그인-목록)
- [상세 설명](#상세-설명)
  - [agent-council](#agent-council) - 여러 AI 모델의 의견 종합
  - [clarify](#clarify) - 모호한 요구사항을 명세로 변환
  - [dev](#dev) - 커뮤니티 스캔 + 기술 의사결정
  - [interactive-review](#interactive-review) - 웹 UI로 계획 검토
  - [say-summary](#say-summary) - 응답을 음성으로 듣기
  - [youtube-digest](#youtube-digest) - YouTube 영상 요약 및 퀴즈
  - [google-calendar](#google-calendar) - 멀티 계정 캘린더 통합
  - [kakaotalk](#kakaotalk) - macOS 카카오톡 메시지 발송/읽기
  - [session-wrap](#session-wrap) - 세션 마무리 + 히스토리 분석
  - [podcast](#podcast) - 소스→YouTube 한국어 팟캐스트 생성
  - [fetch-tweet](#fetch-tweet) - 인증 없이 트윗 본문과 메타데이터 가져오기
- [기여하기](#기여하기)
- [라이선스](#라이선스)

---

## 빠른 시작

```bash
# 마켓플레이스 추가
/plugin marketplace add team-attention/plugins-for-claude-natives

# 플러그인 설치
/plugin install <plugin-name>
```

---

## 플러그인 목록

| 플러그인 | 설명 | 소셜 |
|---------|------|------|
| [agent-council](./plugins/agent-council/) | 여러 AI 에이전트(Gemini, GPT, Codex)의 의견을 수집하고 종합 | [LinkedIn](https://www.linkedin.com/posts/gb-jeong_claude-code%EA%B0%80-codex-gemini-cli-%EA%B3%BC-%ED%9A%8C%EC%9D%98%ED%95%B4%EC%84%9C-%EA%B2%B0%EB%A1%A0%EC%9D%84-activity-7406083077258665984-L_fD) |
| [clarify](./plugins/clarify/) | 반복적인 질문을 통해 모호한 요구사항을 정확한 명세로 변환 | [LinkedIn](https://www.linkedin.com/posts/gb-jeong_%ED%81%B4%EB%A1%9C%EB%93%9C%EC%BD%94%EB%93%9C%EA%B0%80-%EA%B0%9D%EA%B4%80%EC%8B%9D%EC%9C%BC%EB%A1%9C-%EC%A7%88%EB%AC%B8%ED%95%98%EA%B2%8C-%ED%95%98%EB%8A%94-skills%EB%A5%BC-%EC%82%AC%EC%9A%A9%ED%95%B4%EB%B3%B4%EC%84%B8%EC%9A%94-clarify-activity-7413349697022570496-qLts) |
| [dev](./plugins/dev/) | 커뮤니티 의견 스캔 + 기술 의사결정 분석 | |
| [interactive-review](./plugins/interactive-review/) | 웹 UI를 통한 인터랙티브 마크다운 리뷰 | [LinkedIn](https://www.linkedin.com/posts/hoyeonleekr_claude-code%EA%B0%80-%EC%9E%91%EC%84%B1%ED%95%9C-%EA%B3%84%ED%9A%8D%EC%9D%B4%EB%82%98-%EA%B8%B4-%EB%AC%B8%EC%84%9C%EC%97%90-%EB%8C%80%ED%95%9C-%EC%96%B4%EB%96%BB%EA%B2%8C-%ED%94%BC%EB%93%9C%EB%B0%B1-%EC%A3%BC%EC%84%B8%EC%9A%94-activity-7412613598516051968-ujHp) |
| [say-summary](./plugins/say-summary/) | Claude 응답을 macOS TTS로 요약해서 읽어줌 (한국어/영어) | [LinkedIn](https://www.linkedin.com/posts/gb-jeong_claude-code%EC%9D%98-%EC%9D%91%EB%8B%B5%EC%9D%84-%EC%9A%94%EC%95%BD%ED%95%B4%EC%84%9C-%EC%9D%8C%EC%84%B1%EC%9C%BC%EB%A1%9C-%EB%93%A4%EC%9D%84-%EC%88%98-%EC%9E%88%EB%8A%94-hooks-activity-7412609821390249984-ekCd) |
| [youtube-digest](./plugins/youtube-digest/) | YouTube 영상 요약, 인사이트, 한글 번역, 퀴즈 제공 | [LinkedIn](https://www.linkedin.com/posts/gb-jeong_84%EB%B6%84%EC%A7%9C%EB%A6%AC-%EC%98%81%EC%96%B4-%ED%8C%9F%EC%BA%90%EC%8A%A4%ED%8A%B8%EB%A5%BC-5%EB%B6%84-%EB%A7%8C%EC%97%90-%ED%95%B5%EC%8B%AC-%ED%8C%8C%EC%95%85%ED%95%98%EA%B3%A0-%ED%80%B4%EC%A6%88%EA%B9%8C%EC%A7%80-%ED%92%80%EA%B3%A0-%EC%A7%81%EC%A0%91-activity-7414055598754848768-c0oy) |
| [google-calendar](./plugins/google-calendar/) | 멀티 계정 Google Calendar 통합, 병렬 조회 및 충돌 감지 | |
| [kakaotalk](./plugins/kakaotalk/) | macOS 카카오톡 메시지 발송 및 읽기 (Accessibility API) | |
| [session-wrap](./plugins/session-wrap/) | 세션 마무리, 히스토리 분석, 세션 검증 툴킷 | |
| [podcast](./plugins/podcast/) | 소스(URL, 트윗, 아티클)를 분석하여 OpenAI TTS로 한국어 팟캐스트 생성 및 YouTube 업로드 | |
| [fetch-tweet](./plugins/fetch-tweet/) | X/Twitter URL에서 인증 없이 트윗 본문, 작성자 정보, 인게이지먼트 데이터 조회 (FxEmbed 활용) | |

---

## 상세 설명

### agent-council

**여러 AI 모델을 소환해서 질문에 대한 합의를 도출합니다.**

어려운 결정을 내려야 하거나 다양한 관점이 필요할 때, 이 플러그인은 여러 AI 에이전트(Gemini CLI, GPT, Codex)에 병렬로 질문하고 그 의견들을 하나의 균형 잡힌 답변으로 종합합니다.

**트리거 문구:**
- "summon the council"
- "다른 AI들한테 물어봐"
- "여러 모델 의견 듣고 싶어"

**동작 방식:**
1. 질문이 여러 AI 에이전트에 동시에 전송됨
2. 각 에이전트가 자신의 관점을 제시
3. Claude가 응답들을 종합하여 합의점과 이견을 정리

```bash
# 예시
User: "summon the council - TypeScript vs JavaScript 뭘 써야 할까?"
```

---

### clarify

**모호한 요구사항을 정확하고 실행 가능한 명세로 변환합니다.**

불명확한 지시사항으로 코드를 작성하기 전에, 이 플러그인이 구조화된 인터뷰를 통해 정확히 무엇이 필요한지 파악합니다. 더 이상 추측도, 재작업도 필요 없습니다.

**트리거 문구:**
- "/clarify"
- "요구사항 명확히 해줘"
- "내가 뭘 원하는 건지..."

**프로세스:**
1. **캡처** - 원본 요구사항을 그대로 기록
2. **질문** - 모호한 부분을 해결하기 위한 객관식 질문
3. **비교** - Before/After로 변환 결과 제시
4. **저장** - 선택적으로 명세를 파일로 저장

**변환 예시:**

| Before | After |
|--------|-------|
| "로그인 기능 추가해줘" | 목표: 사용자명/비밀번호 로그인과 자가 가입 추가. 범위: 로그인, 로그아웃, 가입, 비밀번호 재설정. 제약: 24시간 세션, bcrypt, 5회 시도 제한. |

---

### dev

**개발자 워크플로우 도구: 커뮤니티 스캔과 기술 의사결정.**

개발자 리서치와 의사결정을 위한 두 가지 강력한 스킬을 제공합니다.

#### 스킬

**`/dev-scan`** - 개발자 커뮤니티 의견 스캔
- Reddit (Gemini CLI 통해), Hacker News, Dev.to, Lobsters를 병렬 검색
- 공통 의견, 논쟁점, 주목할 시각을 종합
- 도구 도입 전 커뮤니티 분위기 파악에 유용

**`/tech-decision`** - 깊이 있는 기술 의사결정 분석
- 4개의 전문 에이전트가 병렬로 실행되는 다단계 워크플로우
- 코드베이스 분석, 문서 리서치, 커뮤니티 의견, AI 전문가 관점 종합
- 두괄식(결론 먼저) 보고서와 점수화된 비교 제공

**트리거 문구:**
- "개발자 반응...", "개발자들 뭐라고 해?"
- "A vs B", "어떤 라이브러리 써야 해?", "기술 의사결정"

**tech-decision 동작 방식:**

```
Phase 1: 병렬 정보 수집
┌─────────────────┬─────────────────┬─────────────────┬─────────────────┐
│ codebase-       │ docs-           │ dev-scan        │ agent-council   │
│ explorer        │ researcher      │ (커뮤니티)       │ (AI 전문가)      │
└────────┬────────┴────────┬────────┴────────┬────────┴────────┬────────┘
         └─────────────────┴─────────────────┴─────────────────┘
                                    │
Phase 2: 분석 및 종합               ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                        tradeoff-analyzer                                 │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                       decision-synthesizer                               │
│                       (두괄식: 결론 먼저)                                  │
└─────────────────────────────────────────────────────────────────────────┘
```

```bash
# 예시
User: "React vs Vue 뭐가 나을까?"
User: "상태관리 라이브러리 뭐 쓸지 고민이야"
User: "모놀리스 vs 마이크로서비스 어떻게 해야 할까?"
```

---

### interactive-review

**웹 인터페이스를 통해 Claude의 계획과 문서를 검토합니다.**

터미널에서 긴 마크다운을 읽는 대신, 이 플러그인은 브라우저 기반 UI를 열어 항목별로 체크/언체크하고, 코멘트를 추가하고, 구조화된 피드백을 제출할 수 있게 합니다.

**트리거 문구:**
- "/review"
- "이 계획 검토해줘"
- "확인해볼게"

**플로우:**
1. Claude가 계획이나 문서를 생성
2. 브라우저에 웹 UI가 자동으로 열림
3. 각 항목을 체크박스와 선택적 코멘트로 검토
4. Submit 클릭하여 구조화된 피드백 전송
5. Claude가 승인/거부된 항목에 따라 조정

---

### say-summary

**Claude의 응답을 음성으로 들을 수 있습니다 (macOS 전용).**

이 플러그인은 Stop hook을 사용하여 Claude의 응답을 짧은 헤드라인으로 요약하고 macOS 텍스트-투-스피치로 읽어줍니다. 코딩하면서 음성 피드백을 원할 때 딱입니다.

**기능:**
- Claude Haiku를 사용해 응답을 3-10단어로 요약
- 한국어 vs 영어 자동 감지
- 적절한 음성 사용 (한국어: Yuna, 영어: Samantha)
- 백그라운드 실행, Claude Code 차단 없음

**요구사항:**
- macOS (`say` 명령어 사용)
- Python 3.10+

---

### youtube-digest

**YouTube 영상을 트랜스크립트, 번역, 이해도 퀴즈와 함께 요약합니다.**

YouTube URL을 입력하면 완전한 분석을 받을 수 있습니다: 요약, 핵심 인사이트, 전체 트랜스크립트 한글 번역, 그리고 이해도를 테스트하는 3단계 퀴즈(총 9문제).

**트리거 문구:**
- "이 유튜브 정리해줘"
- "영상 요약해줘"
- YouTube URL

**받을 수 있는 것:**
1. **요약** - 핵심 포인트와 함께 3-5문장 개요
2. **인사이트** - 실행 가능한 테이크어웨이와 아이디어
3. **전체 트랜스크립트** - 한글 번역과 타임스탬프 포함
4. **3단계 퀴즈** - 기본, 중급, 심화 문제
5. **Deep Research** (선택) - 주제를 확장하는 웹 검색

**저장 위치:** `research/readings/youtube/YYYY-MM-DD-title.md`

---

### google-calendar

**Claude Code에서 여러 Google Calendar 계정을 관리합니다.**

여러 Google 계정(회사, 개인 등)의 일정을 조회, 생성, 수정, 삭제할 수 있으며 자동 충돌 감지 기능을 제공합니다.

**트리거 문구:**
- "일정 보여줘"
- "캘린더 확인"
- "미팅 만들어줘"
- "충돌 확인해줘"

**기능:**
- 여러 계정 병렬 조회
- 계정 간 충돌 감지
- 전체 CRUD 작업 (생성, 조회, 수정, 삭제)
- refresh token으로 사전 인증 (반복 로그인 불필요)

**설정 필요:**
1. Calendar API가 활성화된 Google Cloud 프로젝트 생성
2. 각 계정별 설정 스크립트 실행

```bash
# 계정별 최초 1회 설정
uv run python scripts/setup_auth.py --account work
uv run python scripts/setup_auth.py --account personal
```

---

### kakaotalk

![Demo](./assets/kakaotalk.gif)

**macOS에서 카카오톡 메시지를 발송하고 읽습니다.**

Accessibility API를 사용하여 카카오톡 앱을 제어합니다. 자연어로 메시지를 보내거나 대화 내역을 확인할 수 있습니다.

**트리거 문구:**
- "카톡 보내줘", "카카오톡 메시지"
- "~에게 메시지 보내줘"
- "채팅 읽어줘"

**기능:**
- 자연어 메시지 발송 (발송 전 확인)
- 채팅방 대화 내역 조회
- 채팅방 목록 확인
- "sent with claude code" 서명 자동 추가

**요구사항:**
- macOS 전용
- 카카오톡 앱 실행 중
- Accessibility 권한 필요

```
# 예시 (자연어 트리거)
"구봉한테 밥 먹었어? 보내줘"
"구봉이랑 대화 내역 보여줘"
```

---

### session-wrap

**종합 세션 마무리 및 분석 툴킷.**

코딩 세션을 철저히 분석하고 마무리하며, 세션 히스토리에서 인사이트를 추출합니다.

#### 스킬

**`/wrap`** - 세션 마무리 워크플로우
- 종합 세션 분석을 위한 2단계 멀티 에이전트 파이프라인
- 문서화 필요사항, 자동화 기회, 배운 점, 후속 작업 캡처
- `/wrap [커밋 메시지]`로 빠른 커밋

**`/history-insight`** - 세션 히스토리 분석
- Claude Code 세션 히스토리에서 패턴과 인사이트 분석
- 현재 프로젝트 또는 전체 세션 검색
- 주제, 결정사항, 반복 패턴 추출

**`/session-analyzer`** - 사후 세션 검증
- SKILL.md 명세 대비 세션 행동 검증
- 에이전트, 훅, 도구가 올바르게 실행되었는지 확인
- 상세한 준수 보고서 생성

**/wrap 동작 방식 (2단계 파이프라인):**

```
Phase 1: 분석 (병렬)
┌──────────────┬──────────────┬──────────────┬──────────────┐
│ doc-updater  │ automation-  │ learning-    │ followup-    │
│              │ scout        │ extractor    │ suggester    │
└──────┬───────┴──────┬───────┴──────┬───────┴──────┬───────┘
       └──────────────┴──────────────┴──────────────┘
                            │
Phase 2: 검증               ▼
┌─────────────────────────────────────────────────────────────┐
│                    duplicate-checker                         │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
                    사용자 선택
```

**장점:**
- 중요한 발견을 문서화하는 것을 잊지 않음
- 자동화할 가치가 있는 패턴 식별
- 미래 세션을 위한 명확한 인수인계점 생성
- 과거 세션의 반복 패턴 분석
- 스킬 구현이 명세대로 동작하는지 검증

---

### podcast

**어떤 소스든 한국어 팟캐스트 에피소드로 변환하고 YouTube에 자동 업로드합니다.**

URL, 트윗, 아티클, PDF를 제공하면 병렬 분석 → 융합 스크립트 작성 → OpenAI TTS 음성 생성 → YouTube 업로드까지 한 번에 처리합니다.

**트리거 문구:**
- "팟캐스트 만들어"
- "이 글을 팟캐스트로"
- "에피소드 만들어줘"
- "podcast"

**파이프라인:**

```
소스 → 병렬 분석 → 스크립트 작성 → TTS (OpenAI) → MP4 → YouTube 업로드
```

**결과물:**
1. **스크립트** - 8-12분 한국어 팟캐스트 스크립트 (오프닝, 분석, 융합, 클로징)
2. **오디오** - OpenAI gpt-4o-mini-tts의 자연스러운 한국어 음성 MP3
3. **영상** - 다크 타이틀 카드 MP4 (1920x1080)
4. **YouTube** - unlisted로 자동 업로드 + 메타데이터

**부분 실행 지원:**
- "스크립트만 써줘" → 스크립트만
- "이 스크립트로 TTS 만들어" → 오디오만
- "YouTube에 올려줘" → 기존 MP4 업로드

**요구사항:**
- ffmpeg (오디오 병합 및 MP4 변환)
- OpenAI API 키 (`OPENAI_API_KEY` 환경변수)
- Google OAuth 클라이언트 시크릿 (YouTube 업로드용)

```bash
# 예시
User: "이 두 개의 아티클로 팟캐스트 만들어줘"
# → 두 아티클 병렬 분석
# → 융합 스크립트 작성
# → 음성 생성
# → YouTube 업로드
```

---

### fetch-tweet

**Claude Code에서 어떤 공개 트윗이든 읽을 수 있습니다 — 인증 없이, API 키 없이, JavaScript 없이.**

X/Twitter URL을 던지면 트윗 본문(URL 확장됨), 작성자 정보, 인게이지먼트 수치, 첨부 미디어, 인용 트윗까지 전부 가져옵니다. 오픈소스 [FxEmbed](https://github.com/FxEmbed/FxEmbed) 프로젝트의 백엔드를 활용합니다.

**트리거 문구:**
- "트윗 가져와", "트윗 번역해줘"
- "fetch this tweet", "translate this tweet"
- 모든 X/Twitter URL (`x.com`, `twitter.com`)

**왜 필요한가:**
X가 비인증 트윗 임베드를 막아서, 스크립트로 트윗을 읽으려면 보통 API 키나 브라우저 자동화가 필요합니다. 이 플러그인은 Discord/Telegram의 fxtwitter 링크 프리뷰를 구동하는 동일한 백엔드 `api.fxtwitter.com`을 경유해 그 문제를 우회합니다.

**기능:**
- 의존성 0 (Python 표준 라이브러리만 사용)
- 인용 트윗과 미디어를 포함한 전체 트윗 데이터
- 다른 스킬과 파이프라인 연동을 위한 `--json` 모드
- 스크립트 실행이 어려울 때 WebFetch fallback

```bash
# 직접 스크립트 사용
python scripts/fetch_tweet.py https://x.com/sama/status/...
python scripts/fetch_tweet.py <url> --json | jq '.tweet.text'
```

**제약:** 비공개/삭제된 트윗은 조회 불가.

---

## 기여하기

기여를 환영합니다! 이슈나 PR을 열어주세요.

## 라이선스

MIT


================================================
FILE: README.md
================================================
# Plugins for Claude Natives

A collection of Claude Code plugins for power users who want to extend Claude Code's capabilities beyond the defaults.

## Table of Contents

- [Quick Start](#quick-start)
- [Available Plugins](#available-plugins)
- [Plugin Details](#plugin-details)
  - [agent-council](#agent-council) - Get consensus from multiple AI models
  - [clarify](#clarify) - Transform vague requirements into specs
  - [dev](#dev) - Community scanning + technical decision-making
  - [doubt](#doubt) - Force Claude to re-validate responses
  - [interactive-review](#interactive-review) - Review plans with a web UI
  - [say-summary](#say-summary) - Hear responses via text-to-speech
  - [youtube-digest](#youtube-digest) - Summarize and quiz on YouTube videos
  - [gmail](#gmail) - Multi-account Gmail integration
  - [google-calendar](#google-calendar) - Multi-account calendar integration
  - [kakaotalk](#kakaotalk) - Send/read KakaoTalk messages on macOS
  - [session-wrap](#session-wrap) - Session wrap-up + history analysis toolkit
  - [team-assemble](#team-assemble) - Dynamic agent team orchestration
  - [podcast](#podcast) - Source-to-YouTube Korean podcast generator
  - [fetch-tweet](#fetch-tweet) - Fetch tweet text and metadata without auth
- [Contributing](#contributing)
- [License](#license)

---

## Quick Start

```bash
# Add this marketplace to Claude Code
/plugin marketplace add team-attention/plugins-for-claude-natives

# Install any plugin
/plugin install <plugin-name>
```

---

## Available Plugins

| Plugin | Description |
|--------|-------------|
| [agent-council](./plugins/agent-council/) | Collect and synthesize opinions from multiple AI agents (Gemini, GPT, Codex) |
| [clarify](./plugins/clarify/) | Transform vague requirements into precise specifications through iterative questioning |
| [dev](./plugins/dev/) | Developer workflow: community opinion scanning and technical decision analysis |
| [doubt](./plugins/doubt/) | Force Claude to re-validate its response when `!rv` is in your prompt |
| [interactive-review](./plugins/interactive-review/) | Interactive markdown review with web UI for visual plan/document approval |
| [say-summary](./plugins/say-summary/) | Speaks a short summary of Claude's response using macOS TTS (Korean/English) |
| [youtube-digest](./plugins/youtube-digest/) | Summarize YouTube videos with transcript, insights, Korean translation, and quizzes |
| [gmail](./plugins/gmail/) | Multi-account Gmail integration with email reading, searching, sending, and management |
| [google-calendar](./plugins/google-calendar/) | Multi-account Google Calendar integration with parallel querying and conflict detection |
| [kakaotalk](./plugins/kakaotalk/) | Send and read KakaoTalk messages on macOS using Accessibility API |
| [session-wrap](./plugins/session-wrap/) | Session wrap-up, history analysis, and session validation toolkit |
| [team-assemble](./plugins/team-assemble/) | Dynamically assemble expert agent teams for complex tasks using Claude Code's agent teams feature |
| [podcast](./plugins/podcast/) | Generate Korean podcast episodes from any source with OpenAI TTS and YouTube auto-upload |
| [fetch-tweet](./plugins/fetch-tweet/) | Fetch full tweet text, author info, and engagement data from X/Twitter URLs without authentication |

## Plugin Details

### agent-council

![Demo](./assets/agent-council.gif)

**Summon multiple AI models to debate your question and reach a consensus.**

When you're facing a tough decision or want diverse perspectives, this plugin queries multiple AI agents (Gemini CLI, GPT, Codex) in parallel and synthesizes their opinions into a single, balanced answer.

**Trigger phrases:**
- "summon the council"
- "ask other AIs"
- "what do other models think?"

**How it works:**
1. Your question is sent to multiple AI agents simultaneously
2. Each agent provides its perspective
3. Claude synthesizes the responses into a consensus view with noted disagreements

```bash
# Example
User: "summon the council - should I use TypeScript or JavaScript for my new project?"
```

---

### clarify

![Demo](./assets/clarify.gif)

**Turn vague requirements into precise, actionable specifications.**

Before writing code based on ambiguous instructions, this plugin conducts a structured interview to extract exactly what you need. No more assumptions, no more rework.

**Trigger phrases:**
- "/clarify"
- "clarify requirements"
- "what do I mean by..."

**The process:**
1. **Capture** - Record the original requirement verbatim
2. **Question** - Ask targeted multiple-choice questions to resolve ambiguities
3. **Compare** - Present before/after showing the transformation
4. **Save** - Optionally save the clarified spec to a file

**Example transformation:**

| Before | After |
|--------|-------|
| "Add a login feature" | Goal: Add username/password login with self-registration. Scope: Login, logout, registration, password reset. Constraints: 24h session, bcrypt, rate limit 5 attempts. |

---

### dev

**Developer workflow tools: community scanning and technical decision-making.**

This plugin provides two powerful skills for developer research and decision-making.

#### Skills

**`/dev-scan`** - Scan developer communities for real opinions
- Searches Reddit (via Gemini CLI), Hacker News, Dev.to, and Lobsters in parallel
- Synthesizes consensus, controversies, and notable perspectives
- Great for understanding community sentiment before adopting a tool

**`/tech-decision`** - Deep technical decision analysis
- Multi-phase workflow with 4 specialized agents running in parallel
- Combines codebase analysis, docs research, community opinions, and AI perspectives
- Produces executive-summary-first reports with scored comparisons

**Trigger phrases:**
- "developer reactions to...", "what do devs think about..."
- "A vs B", "which library should I use", "기술 의사결정"

**How tech-decision works:**

```
Phase 1: Parallel Information Gathering
┌─────────────────┬─────────────────┬─────────────────┬─────────────────┐
│ codebase-       │ docs-           │ dev-scan        │ agent-council   │
│ explorer        │ researcher      │ (community)     │ (AI experts)    │
└────────┬────────┴────────┬────────┴────────┬────────┴────────┬────────┘
         └─────────────────┴─────────────────┴─────────────────┘
                                    │
Phase 2: Analysis & Synthesis       ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                        tradeoff-analyzer                                 │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                       decision-synthesizer                               │
│                    (Executive Summary First)                             │
└─────────────────────────────────────────────────────────────────────────┘
```

```bash
# Examples
User: "React vs Vue for my new project?"
User: "Which state management library should I use?"
User: "Monolith vs microservices for our scale?"
```

---

### doubt

**Force Claude to double-check its response before delivering.**

When you include `!rv` anywhere in your prompt, Claude will pause before responding, re-validate its answer against potential errors, and only then deliver the response. Perfect for critical decisions or when you want extra confidence.

**Trigger:**
- Include `!rv` anywhere in your prompt

**How it works:**
1. `UserPromptSubmit` hook detects `!rv` keyword and sets a flag
2. `Stop` hook intercepts Claude's response before delivery
3. Claude re-validates the response for errors, hallucinations, or questionable claims
4. Only after verification does Claude deliver the final answer

**Why `!rv` instead of `!doubt`?**
The word "doubt" affects Claude's behavior - it starts doubting from the beginning. `!rv` (re-validate) is neutral.

```bash
# Example
User: "What's the time complexity of binary search? !rv"
# Claude will verify its answer before responding
```

---

### interactive-review

**Review Claude's plans and documents through a visual web interface.**

Instead of reading long markdown in the terminal, this plugin opens a browser-based UI where you can check/uncheck items, add comments, and submit structured feedback.

**Trigger phrases:**
- "/review"
- "review this plan"
- "let me check this"

**The flow:**
1. Claude generates a plan or document
2. A web UI opens automatically in your browser
3. Review each item with checkboxes and optional comments
4. Click Submit to send structured feedback back to Claude
5. Claude adjusts based on your approved/rejected items

---

### say-summary

![Demo](./assets/say-summary.gif)

**Hear Claude's responses spoken aloud (macOS only).**

This plugin uses a Stop hook to summarize Claude's response to a short headline and speaks it using macOS text-to-speech. Perfect for when you're coding and want audio feedback.

**Features:**
- Summarizes responses to 3-10 words using Claude Haiku
- Auto-detects Korean vs English
- Uses appropriate voice (Yuna for Korean, Samantha for English)
- Runs in background, doesn't block Claude Code

**Requirements:**
- macOS (uses the `say` command)
- Python 3.10+

---

### youtube-digest

![Demo](./assets/youtube-digest.jpeg)

**Summarize YouTube videos with transcripts, translations, and comprehension quizzes.**

Drop a YouTube URL and get a complete breakdown: summary, key insights, full Korean translation of the transcript, and a 3-stage quiz (9 questions total) to test your understanding.

**Trigger phrases:**
- "summarize this YouTube"
- "digest this video"
- YouTube URL

**What you get:**
1. **Summary** - 3-5 sentence overview with key points
2. **Insights** - Actionable takeaways and ideas
3. **Full transcript** - With Korean translation and timestamps
4. **3-stage quiz** - Basic, intermediate, and advanced questions
5. **Deep Research** (optional) - Web search to expand on the topic

**Output location:** `research/readings/youtube/YYYY-MM-DD-title.md`

---

### gmail

<img src="https://upload.wikimedia.org/wikipedia/commons/thumb/7/7e/Gmail_icon_%282020%29.svg/1280px-Gmail_icon_%282020%29.svg.png" width="120" alt="Gmail">

**Manage multiple Gmail accounts from Claude Code.**

Read, search, send, and manage emails across multiple Google accounts with full Gmail API integration.

**Trigger phrases:**
- "check my email"
- "send an email to..."
- "search for emails from..."
- "reply to this email"
- "mark as read"

**Features:**
- Multi-account support via `accounts.yaml` (work, personal, etc.)
- Gmail search query syntax support
- Email sending with attachments and HTML
- Label and draft management
- **5-step email sending workflow** with context gathering, draft review, and test delivery
- Rate limiting and quota management
- Batch processing and local caching

**5-Step Email Workflow:**
1. **Context gathering** - Parallel Explore agents search recipient info and related projects
2. **Previous conversations** - Search recent emails to determine reply vs new thread
3. **Draft composition** - Create draft with user feedback
4. **Test send** - Send to your own email for verification
5. **Actual send** - Deliver to recipient

**Setup:**
1. Create Google Cloud project with Gmail API enabled
2. Run setup script for each account

```bash
# One-time setup per account
uv run python scripts/setup_auth.py --account work
uv run python scripts/setup_auth.py --account personal
```

Account metadata is stored in `accounts.yaml` for easy management.

---

### google-calendar

<img src="https://upload.wikimedia.org/wikipedia/commons/thumb/a/a5/Google_Calendar_icon_%282020%29.svg/960px-Google_Calendar_icon_%282020%29.svg.png" width="120" alt="Google Calendar">

**Manage multiple Google Calendar accounts from Claude Code.**

Query, create, update, and delete events across multiple Google accounts (work, personal, etc.) with automatic conflict detection.

**Trigger phrases:**
- "show my schedule"
- "what's on my calendar"
- "create a meeting"
- "check for conflicts"

**Features:**
- Parallel querying across multiple accounts
- Conflict detection between accounts
- Full CRUD operations (create, read, update, delete)
- Pre-authenticated with refresh tokens (no repeated logins)

**Setup required:**
1. Create Google Cloud project with Calendar API
2. Run setup script for each account

```bash
# One-time setup per account
uv run python scripts/setup_auth.py --account work
uv run python scripts/setup_auth.py --account personal
```

---

### kakaotalk

![Demo](./assets/kakaotalk.gif)

**Send and read KakaoTalk messages from Claude Code on macOS.**

Uses macOS Accessibility API to control the KakaoTalk app. Send messages or read chat history using natural language.

**Trigger phrases:**
- "카톡 보내줘", "카카오톡 메시지"
- "~에게 메시지 보내줘"
- "채팅 읽어줘"
- "KakaoTalk message"

**Features:**
- Natural language message sending (with confirmation before send)
- Chat history retrieval
- Chat room listing
- Auto-signature "sent with claude code"

**Requirements:**
- macOS only
- KakaoTalk app must be running
- Accessibility permission required

```
# Examples (natural language)
"구봉한테 밥 먹었어? 보내줘"
"구봉이랑 대화 내역 보여줘"
```

---

### session-wrap

**Comprehensive session wrap-up and analysis toolkit.**

End your coding sessions with thorough analysis, and dive deep into session history for insights.

#### Skills

**`/wrap`** - Session wrap-up workflow
- 2-phase multi-agent pipeline for comprehensive session analysis
- Captures documentation needs, automation opportunities, learnings, and follow-ups
- `/wrap [commit message]` for quick commits

**`/history-insight`** - Session history analysis
- Analyze Claude Code session history for patterns and insights
- Search current project or all sessions
- Extract themes, decisions, and recurring topics

**`/session-analyzer`** - Post-hoc session validation
- Validate session behavior against SKILL.md specifications
- Check if agents, hooks, and tools executed correctly
- Generate detailed compliance reports

**How /wrap works (2-Phase Pipeline):**

```
Phase 1: Analysis (Parallel)
┌──────────────┬──────────────┬──────────────┬──────────────┐
│ doc-updater  │ automation-  │ learning-    │ followup-    │
│              │ scout        │ extractor    │ suggester    │
└──────┬───────┴──────┬───────┴──────┬───────┴──────┬───────┘
       └──────────────┴──────────────┴──────────────┘
                            │
Phase 2: Validation         ▼
┌─────────────────────────────────────────────────────────────┐
│                    duplicate-checker                         │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
                    User Selection
```

**Benefits:**
- Never forget to document important discoveries
- Identify patterns worth automating
- Create clear handoff points for future sessions
- Analyze past sessions for recurring patterns
- Validate skill implementations against specifications

---

### team-assemble

**Dynamically assemble expert agent teams for complex tasks.**

Instead of manually designing agents, this plugin analyzes your task, scouts the codebase, and assembles an optimal team with the right roles, dependencies, and validation criteria — all using Claude Code's agent teams feature.

> **Prerequisite:** Agent teams must be enabled. See [setup guide](./plugins/team-assemble/skills/team-assemble/references/enable-agent-teams.md).

**Trigger phrases:**
- "assemble a team to..."
- "team assemble"
- "use a team for..."

**6-Phase Workflow:**

```
Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 5 → Phase 6
Task       Codebase   Integrate  Execute   Validate   Complete
Analysis   Scouts     & Confirm                       & Cleanup
```

**Key features:**
- **Dynamic agent design** — scouts your codebase and proposes agents tailored to the task (no fixed catalog)
- **Model 3-tier** — opus for strategy, sonnet for execution, haiku for research
- **Parallel execution** — independent agents run simultaneously
- **Acceptance criteria** — every team has measurable validation criteria
- **Verify/fix loop** — QA validates, support fixes (max 3 rounds)
- **Two approval gates** — confirm scope (Phase 1) and team composition (Phase 3)

```bash
# Examples
User: "Assemble a team to refactor authentication from session-based to JWT"
User: "Use a team to evaluate Redis vs Memcached vs in-memory caching"
User: "Team assemble — extract shared utils from three microservices into a common lib"
```

---

### podcast

**Turn any source into a Korean podcast episode, automatically uploaded to YouTube.**

Drop URLs, tweets, articles, or PDFs and this plugin will analyze them, write a conversational Korean script, generate audio using OpenAI's `gpt-4o-mini-tts`, and upload the result to YouTube — all in one go.

**Trigger phrases:**
- "make a podcast from this"
- "팟캐스트 만들어"
- "turn this into an episode"
- "이 글을 팟캐스트로"

**The pipeline:**

```
Sources → Parallel Analysis → Script Writing → TTS (OpenAI) → MP4 → YouTube Upload
```

**What you get:**
1. **Script** - 8-12 min Korean podcast script with opening, analysis, fusion, and closing
2. **Audio** - MP3 generated via OpenAI gpt-4o-mini-tts with natural Korean voice
3. **Video** - MP4 with dark title card (1920x1080)
4. **YouTube** - Auto-uploaded as unlisted with metadata

**Partial execution supported:**
- "Just write the script" → Script only
- "Generate TTS from this script" → Audio only
- "Upload to YouTube" → Upload existing MP4

**Requirements:**
- ffmpeg (for audio merging and MP4 conversion)
- OpenAI API key (`OPENAI_API_KEY` env var)
- Google OAuth client secret (for YouTube upload)

```bash
# Example
User: "이 두 개의 아티클로 팟캐스트 만들어줘"
# → Analyzes both articles in parallel
# → Writes fusion script
# → Generates audio
# → Uploads to YouTube
```

---

### fetch-tweet

**Read any public tweet from Claude Code — no auth, no API key, no JavaScript.**

Drop an X/Twitter URL and get the full tweet text (URLs expanded), author info, engagement metrics, attached media, and quoted tweets. Powered by the open-source [FxEmbed](https://github.com/FxEmbed/FxEmbed) project.

**Trigger phrases:**
- "트윗 가져와", "트윗 번역해줘"
- "fetch this tweet", "translate this tweet"
- Any X/Twitter URL (`x.com`, `twitter.com`)

**Why this exists:**
X removed unauthenticated tweet embeds, so reading a tweet from a script normally requires an API key or browser automation. This plugin sidesteps that by routing through `api.fxtwitter.com` — the same backend that powers fxtwitter link previews on Discord/Telegram.

**Features:**
- Zero dependencies (Python stdlib only)
- Full tweet data including quote tweets and media
- `--json` mode for pipeline use with other skills
- WebFetch fallback when script execution isn't available

```bash
# Direct script usage
python scripts/fetch_tweet.py https://x.com/sama/status/...
python scripts/fetch_tweet.py <url> --json | jq '.tweet.text'
```

**Limitations:** Private/deleted tweets cannot be fetched.

---

## Contributing

Contributions welcome! Please open an issue or PR.

## License

MIT


================================================
FILE: plugins/agent-council/.claude-plugin/plugin.json
================================================
{
  "name": "agent-council",
  "version": "1.0.0",
  "description": "Collect and synthesize opinions from multiple AI Agents for Claude Code",
  "author": {
    "name": "Team Attention",
    "url": "https://github.com/team-attention"
  },
  "repository": "https://github.com/team-attention/plugins-for-claude-natives",
  "license": "MIT",
  "keywords": ["claude-code", "plugin", "llm", "multi-agent", "ai-council"],
  "skills": "./skills/agent-council"
}


================================================
FILE: plugins/agent-council/AGENTS.md
================================================
# Project Instructions (Codex)

## Plan / To-do UI (IMPORTANT)

- When you decide to use any Skill, **always** call `update_plan` immediately (before any potentially long-running shell/tool calls) so Codex’s Plan/To-do panel appears. Include **exactly one** `in_progress` item in that first plan.
- Keep the plan updated during execution (at most one `in_progress` step at a time).
- For `agent-council`: after the first `council.sh wait` (the non-blocking one), feed `.ui.codex.update_plan.plan` into `update_plan` right away, then repeat `wait → update_plan` until done.


================================================
FILE: plugins/agent-council/CLAUDE.md
================================================
# Project Instructions (Claude Code)

## Todo UI (IMPORTANT)

- When you decide to use any Skill, **always** call `TodoWrite` immediately (before any potentially long-running shell/tool calls) so Claude’s Todo UI appears. Include **exactly one** `in_progress` item in that first todo list.
- Keep the todo list updated during execution (at most one `in_progress` item at a time).
- For `agent-council`: after the first `council.sh wait` (the non-blocking one), feed `.ui.claude.todo_write.todos` into `TodoWrite` right away, then repeat `wait → TodoWrite` until done.



================================================
FILE: plugins/agent-council/README.ko.md
================================================
# Agent Council

**[English Version](./README.md)**

> 여러 AI CLI(Codex, Gemini, ...)의 의견을 모으고, 설정 가능한 의장(Chairman)이 종합해 결론을 내리게 하는 스킬
> [Karpathy의 LLM Council](https://github.com/karpathy/llm-council)에서 영감을 받음

## LLM Council과의 차이점

**추가 API 비용이 들지 않습니다!**

Karpathy의 LLM Council은 각 LLM의 API를 직접 호출하여 비용이 발생하지만, Agent Council은 설치된 AI CLI(Claude Code, Codex CLI, Gemini CLI 등)를 활용합니다. 주로 하나의 호스트 CLI를 메인으로 쓰면서 다른 CLI들은 구독 플랜으로 필요할 때만 쓰는 분들에게 특히 유용합니다.

MCP보다 Skill이 훨씬 간단하고 재현 가능해서 npx로 설치 후 직접 커스터마이징하여 사용하시는 것을 추천합니다.

## 데모

https://github.com/user-attachments/assets/c550c473-00d2-4def-b7ba-654cc7643e9b

## 작동 방식

Agent Council은 AI 합의를 수집하기 위한 3단계 프로세스를 구현합니다:

**Stage 1: Initial Opinions (초기 의견 수집)**
설정된 모든 AI 에이전트가 동시에 질문을 받고 독립적으로 응답합니다.

**Stage 2: Response Collection (응답 수집)**
각 에이전트의 응답을 수집하여 포맷된 형태로 표시합니다.

**Stage 3: Chairman Synthesis (의장 종합)**
기본값(`role: auto`)에서는 “현재 사용 중인 호스트 에이전트(Claude Code / Codex CLI 등)”가 의장 역할을 하며, 모든 의견을 종합해 최종 추천을 제시합니다. 원하면 `chairman.command`를 설정해 `council.sh` 안에서 Stage 3 종합을 CLI로 직접 실행할 수도 있습니다.

## 설치

### 방법 A: npx로 설치 (권장)

```bash
npx github:team-attention/agent-council
```

현재 프로젝트 디렉토리에 스킬 파일들이 복사됩니다.
Agent Council을 업그레이드한 뒤 `Missing runtime dependency: yaml` 같은 런타임 에러가 나면, 위 설치 커맨드를 한 번 더 실행해서 설치된 스킬 파일을 갱신하세요.

기본값으로 설치 스크립트가 자동으로 Claude Code(`.claude/`) / Codex CLI(`.codex/`) 설치 여부를 감지해서 가능한 타깃에 설치합니다.

설치 위치:
- `.claude/skills/agent-council/` (Claude Code)
- `.codex/skills/agent-council/` (Codex CLI)

선택사항 (Codex용 레포 스킬로 설치):
```bash
npx github:team-attention/agent-council --target codex
```

다른 타깃:
```bash
npx github:team-attention/agent-council --target claude
npx github:team-attention/agent-council --target both
```

생성되는 `council.config.yaml`은 감지된 멤버 CLI(claude/codex/gemini 등)만 포함하며, 설치 타깃(호스트)은 members에 포함되지 않도록 처리합니다. 이 필터링은 **초기 생성 시점에만** 적용되며, 이후 편집 내용은 자동으로 정리되지 않습니다.

### 방법 B: Claude Code 플러그인으로 설치 (Claude Code 전용)

```bash
# 마켓플레이스 추가
/plugin marketplace add team-attention/plugins-for-claude-natives

# 플러그인 설치
/plugin install agent-council@plugins-for-claude-natives
```

참고(플러그인 설치): **Agent Council은 Node.js가 필요**하며, Claude Code 플러그인은 Node를 번들/자동 설치할 수 없습니다. Node를 별도로 설치하세요(예: macOS `brew install node`).

### 2. Agent CLI 설치

`council.config.yaml`의 `council.members`에 적힌 CLI를 설치하세요(템플릿 기본 포함: `claude`, `codex`, `gemini`):

```bash
# Anthropic Claude Code
# https://claude.ai/code

# OpenAI Codex CLI
# https://github.com/openai/codex

# Google Gemini CLI
# https://github.com/google-gemini/gemini-cli
```

설치 확인(멤버별):
```bash
command -v claude
command -v codex
command -v gemini
```

### 3. Council 멤버 설정 (선택사항)

설치된 스킬 폴더의 설정 파일을 편집해서 council을 커스터마이즈:
- `.claude/skills/agent-council/council.config.yaml`
- `.codex/skills/agent-council/council.config.yaml`

```yaml
council:
  chairman:
    role: "auto" # auto|claude|codex|gemini|...
    # command: "codex exec" # 선택: council.sh에서 Stage 3 종합까지 실행

  members:
    - name: codex
      command: "codex exec"
      emoji: "🤖"
      color: "BLUE"

    - name: gemini
      command: "gemini"
      emoji: "💎"
      color: "GREEN"

    # 필요에 따라 에이전트 추가
    # - name: grok
    #   command: "grok"
    #   emoji: "🚀"
    #   color: "MAGENTA"
```

## 사용법

### 호스트 에이전트를 통한 사용 (Claude Code / Codex CLI)

호스트 에이전트에게 council 소집을 요청하면 됩니다:

```
"다른 AI들 의견도 들어보자"
"council 소집해줘"
"여러 관점에서 검토해줘"
"codex랑 gemini 의견 물어봐"
```

### 스크립트 직접 실행

```bash
JOB_DIR=$(.codex/skills/agent-council/scripts/council.sh start "질문 내용")
.codex/skills/agent-council/scripts/council.sh status --text "$JOB_DIR"
.codex/skills/agent-council/scripts/council.sh results "$JOB_DIR"
.codex/skills/agent-council/scripts/council.sh clean "$JOB_DIR"
```

팁: `status --text`에 `--verbose`를 추가하면 멤버별 상태 라인이 함께 출력됩니다.
팁: `status --checklist`는 체크리스트 형태로 간단히 보여줍니다(Codex/Claude tool cell에 유용).
팁: `wait`를 쓰면 “의미 있는 진행”이 있을 때만 반환해서 tool cell 스팸을 줄일 수 있습니다(JSON 출력, 커서는 자동으로 저장/갱신; 기본값은 멤버 수에 따라 대략 ~5~10번 수준으로 자동 배치, `--bucket 1`이면 매 완료마다 반환).

원샷 실행(잡 시작 → 대기 → 결과 출력 → 정리):

```bash
.codex/skills/agent-council/scripts/council.sh "질문 내용"
```

참고: 호스트 에이전트 도구 UI(Codex CLI / Claude Code)에서는 원샷이 **블로킹하지 않습니다**. 네이티브 plan/todo UI를 갱신할 수 있도록 `wait` JSON을 한 번 반환하고 종료하며, 이후 `wait` → 네이티브 UI 갱신 → `results` → `clean` 순서로 진행하세요.

#### 진행상황

- 실제 터미널에서는 원샷이 멤버 완료에 맞춰 진행상황 라인을 주기적으로 출력합니다.
- 호스트 에이전트 도구 UI에서는 원샷이 `wait` JSON을 반환합니다(네이티브 plan/todo UI 갱신 목적).
- 스크립팅이 필요하면 job mode(`start` → `status` → `results` → `clean`)도 사용할 수 있습니다.

## 예시

```
User: "새 대시보드 프로젝트에 React vs Vue 어떨까? council 소집해줘"

호스트 에이전트(Claude Code / Codex CLI):
1. council.sh 실행하여 설정된 멤버(예: Codex, Gemini) 의견 수집
2. 각 에이전트의 관점 표시
3. 의장으로서 종합:
   "Council의 의견을 바탕으로, 대시보드의 데이터 시각화 요구사항과
   팀의 숙련도를 고려할 때..."
```

## 프로젝트 구조

```
agent-council/
├── .claude-plugin/
│   └── marketplace.json     # 마켓플레이스 설정 (Claude Code 전용)
├── bin/
│   └── install.js           # npx 설치 스크립트
├── skills/
│   └── agent-council/
│       ├── SKILL.md         # 스킬 문서
│       └── scripts/
│           ├── council.sh           # 실행 스크립트
│           ├── council-job.sh       # 백그라운드 Job runner (폴링 가능)
│           ├── council-job.js       # Job runner 구현
│           └── council-job-worker.js # 멤버별 워커
├── council.config.yaml      # Council 멤버 설정
├── README.md                # 영어 문서
├── README.ko.md             # 이 문서
└── LICENSE
```

## 주의사항

- 응답 시간은 가장 느린 에이전트에 의존 (병렬 실행)
- 민감한 정보는 council에 공유하지 않기
- 에이전트는 기본적으로 병렬로 실행되어 빠른 응답 제공
- 각 CLI 도구의 구독 플랜이 필요합니다 (API 비용 별도 발생 없음)

## 기여하기

기여를 환영합니다! 다음과 같은 기여가 가능합니다:
- 새로운 AI 에이전트 지원 추가
- 종합 프로세스 개선
- 설정 옵션 확장

## 라이선스

MIT 라이선스 - 자세한 내용은 [LICENSE](./LICENSE) 참조

## 크레딧

- [Karpathy의 LLM Council](https://github.com/karpathy/llm-council)에서 영감
- [Claude Code](https://claude.ai/code) / [Codex CLI](https://github.com/openai/codex) 용으로 제작


================================================
FILE: plugins/agent-council/README.md
================================================
# Agent Council

**[한국어 버전 (Korean)](./README.ko.md)**

> A skill that gathers opinions from multiple AI CLIs (Codex, Gemini, ...) and lets a configurable Chairman synthesize a conclusion.
> Inspired by [Karpathy's LLM Council](https://github.com/karpathy/llm-council)

## Key Difference from LLM Council

**No additional API costs!**

Unlike Karpathy's LLM Council which directly calls each LLM's API (incurring costs), Agent Council uses your installed AI CLIs (Claude Code, Codex CLI, Gemini CLI, ...). This is especially useful if you mainly use one host CLI and occasionally consult others via subscriptions.

Skills are much simpler and more reproducible than MCP. We recommend installing via npx and customizing it yourself!

## Demo

https://github.com/user-attachments/assets/c550c473-00d2-4def-b7ba-654cc7643e9b

## How it Works

Agent Council implements a 3-stage process for gathering AI consensus:

**Stage 1: Initial Opinions**
All configured AI agents receive your question simultaneously and respond independently.

**Stage 2: Response Collection**
Responses from each agent are collected and displayed to you in a formatted view.

**Stage 3: Chairman Synthesis**
Your host agent (Claude Code / Codex CLI / etc.) acts as the Chairman by default (`role: auto`), synthesizing all opinions into a final recommendation. Optionally, you can configure a Chairman CLI command to run synthesis inside `council.sh`.

## Setup

### Option A: Install via npx (Recommended)

```bash
npx github:team-attention/agent-council
```

This copies the skill files to your current project directory.
If you upgrade Agent Council and hit a runtime error like `Missing runtime dependency: yaml`, re-run the installer command above to refresh your installed skill files.

By default, the installer auto-detects whether to install for Claude Code (`.claude/`) and/or Codex CLI (`.codex/`) based on what’s available on your machine and in the repo.

Installed paths:
- `.claude/skills/agent-council/` (Claude Code)
- `.codex/skills/agent-council/` (Codex CLI)

Optional (Codex repo skill):
```bash
npx github:team-attention/agent-council --target codex
```

Other targets:
```bash
npx github:team-attention/agent-council --target claude
npx github:team-attention/agent-council --target both
```

The generated `council.config.yaml` includes only detected member CLIs (e.g. `claude`, `codex`, `gemini`) and avoids adding the host target as a member. This filtering happens only at initial generation; later edits will not auto-remove missing CLIs.

### Option B: Install via Claude Code Plugin (Claude Code only)

```bash
# Add the marketplace
/plugin marketplace add team-attention/plugins-for-claude-natives

# Install the plugin
/plugin install agent-council@plugins-for-claude-natives
```

Note (Plugin installs): **Agent Council requires Node.js**, and Claude Code plugins can’t bundle or auto-install Node for you. Install Node separately (e.g. `brew install node` on macOS).

### 2. Install Agent CLIs

Install the CLIs listed under `council.members` in your `council.config.yaml` (template includes `claude`, `codex`, `gemini`):

```bash
# Anthropic Claude Code
# https://claude.ai/code

# OpenAI Codex CLI
# https://github.com/openai/codex

# Google Gemini CLI
# https://github.com/google-gemini/gemini-cli
```

Verify each member CLI:
```bash
command -v claude
command -v codex
command -v gemini
```

### 3. Configure Council Members (Optional)

Edit the generated config in your installed skill directory:
- `.claude/skills/agent-council/council.config.yaml`
- `.codex/skills/agent-council/council.config.yaml`

```yaml
council:
  chairman:
    role: "auto" # auto|claude|codex|gemini|...
    # command: "codex exec" # optional: run Stage 3 inside council.sh

  members:
    - name: codex
      command: "codex exec"
      emoji: "🤖"
      color: "BLUE"

    - name: gemini
      command: "gemini"
      emoji: "💎"
      color: "GREEN"

    # Add more agents as needed
    # - name: grok
    #   command: "grok"
    #   emoji: "🚀"
    #   color: "MAGENTA"
```

## Usage

### Via your host agent (Claude Code / Codex CLI)

Ask your host agent to summon the council:

```
"Let's hear opinions from other AIs"
"Summon the council"
"Review this from multiple perspectives"
"Ask codex and gemini for their opinions"
```

### Direct Script Execution

```bash
JOB_DIR=$(.codex/skills/agent-council/scripts/council.sh start "Your question here")
.codex/skills/agent-council/scripts/council.sh status --text "$JOB_DIR"
.codex/skills/agent-council/scripts/council.sh results "$JOB_DIR"
.codex/skills/agent-council/scripts/council.sh clean "$JOB_DIR"
```

Tip: add `--verbose` to `status --text` to include per-member lines.
Tip: use `status --checklist` for a compact checkbox view (handy in Codex/Claude tool cells).
Tip: use `wait` to block until meaningful progress without spamming tool cells (prints JSON, persists a cursor automatically; auto-batches to a small number of updates (typically ~5–10); `--bucket 1` for every completion).

One-shot (runs job → waits → prints results → cleans):

```bash
.codex/skills/agent-council/scripts/council.sh "Your question here"
```

Note: In host-agent tool UIs (Codex CLI / Claude Code), one-shot does **not** block. It returns a single `wait` JSON payload so the host agent can update native plan/todo UIs. Continue with `wait` → native UI update → `results` → `clean`.

#### Progress

- In a real terminal, one-shot prints periodic progress lines as members complete.
- In host-agent tool UIs, one-shot returns `wait` JSON (so the host can update native plan/todo UIs).
- Job mode is still available for scripting (`start` → `status` → `results` → `clean`).

## Example

```
User: "React vs Vue for a new dashboard project - summon the council"

Host agent (Claude Code / Codex CLI):
1. Executes council.sh to collect opinions from configured members (e.g., Codex, Gemini)
2. Displays each agent's perspective
3. Synthesizes as Chairman:
   "Based on the council's input, considering your dashboard's
   data visualization needs and team's familiarity, I recommend..."
```

## Project Structure

```
agent-council/
├── .claude-plugin/
│   └── marketplace.json     # Marketplace config (Claude Code only)
├── bin/
│   └── install.js           # npx installer
├── skills/
│   └── agent-council/
│       ├── SKILL.md         # Skill documentation
│       └── scripts/
│           ├── council.sh       # Execution script
│           ├── council-job.sh   # Background job runner (pollable)
│           ├── council-job.js   # Job runner implementation
│           └── council-job-worker.js # Per-member worker
├── council.config.yaml      # Council member configuration
├── README.md                # This file
├── README.ko.md             # Korean documentation
└── LICENSE
```

## Notes

- Response time depends on the slowest agent (parallel execution)
- Do not share sensitive information with the council
- Agents run in parallel by default for faster responses
- Subscription plans for each CLI tool are required (no additional API costs)

## Contributing

Contributions are welcome! Feel free to:
- Add support for new AI agents
- Improve the synthesis process
- Enhance the configuration options

## License

MIT License - see [LICENSE](./LICENSE) for details.

## Credits

- Inspired by [Karpathy's LLM Council](https://github.com/karpathy/llm-council)
- Built for [Claude Code](https://claude.ai/code) and [Codex CLI](https://github.com/openai/codex)


================================================
FILE: plugins/agent-council/SKILL.md
================================================
---
name: agent-council
description: Collect and synthesize opinions from multiple AI agents. Use when users say "summon the council", "ask other AIs", or want multiple AI perspectives on a question.
---

# Agent Council

Collect multiple AI opinions and synthesize one answer.

## Usage

Run a job and collect results:

```bash
JOB_DIR=$(./skills/agent-council/scripts/council.sh start "your question here")
./skills/agent-council/scripts/council.sh wait "$JOB_DIR"
./skills/agent-council/scripts/council.sh results "$JOB_DIR"
./skills/agent-council/scripts/council.sh clean "$JOB_DIR"
```

One-shot:

```bash
./skills/agent-council/scripts/council.sh "your question here"
```

## References

- `references/overview.md` — workflow and background.
- `references/examples.md` — usage examples.
- `references/config.md` — member configuration.
- `references/requirements.md` — dependencies and CLI checks.
- `references/host-ui.md` — host UI checklist guidance.
- `references/safety.md` — safety notes.


================================================
FILE: plugins/agent-council/bin/install.js
================================================
#!/usr/bin/env node

const fs = require('fs');
const path = require('path');
const { execSync } = require('child_process');
const YAML = require('yaml');

const GREEN = '\x1b[32m';
const YELLOW = '\x1b[33m';
const CYAN = '\x1b[36m';
const RED = '\x1b[31m';
const NC = '\x1b[0m';

const packageRoot = path.resolve(__dirname, '..');
const targetDir = process.cwd();
const claudeDir = path.join(targetDir, '.claude');
const codexDir = path.join(targetDir, '.codex');
const yamlModuleDir = path.dirname(require.resolve('yaml/package.json'));

function parseArgs(argv) {
  const args = argv.slice(2);
  const flags = new Set(args);

  const targetIndex = args.indexOf('--target');
  let target = 'auto';
  if (targetIndex !== -1 && args[targetIndex + 1]) {
    target = args[targetIndex + 1];
  } else if (flags.has('--both')) {
    target = 'both';
  } else if (flags.has('--codex')) {
    target = 'codex';
  } else if (flags.has('--claude')) {
    target = 'claude';
  }

  if (!['auto', 'claude', 'codex', 'both'].includes(target)) {
    throw new Error(`Invalid --target "${target}". Use auto|claude|codex|both.`);
  }

  return { target };
}

console.log(`${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}`);
console.log(`${CYAN}  Agent Council - Installation${NC}`);
console.log(`${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}`);
console.log();

function copyRecursive(src, dest) {
  const stat = fs.statSync(src);

  if (stat.isDirectory()) {
    if (!fs.existsSync(dest)) {
      fs.mkdirSync(dest, { recursive: true });
    }
    const files = fs.readdirSync(src);
    for (const file of files) {
      copyRecursive(path.join(src, file), path.join(dest, file));
    }
  } else {
    fs.copyFileSync(src, dest);
    // Preserve executable permission for .sh files
    if (src.endsWith('.sh')) {
      fs.chmodSync(dest, 0o755);
    }
  }
}

function commandExists(command) {
  try {
    const checkCmd = process.platform === 'win32' ? `where ${command}` : `command -v ${command}`;
    execSync(checkCmd, { stdio: 'ignore' });
    return true;
  } catch {
    return false;
  }
}

try {
  const { target: requestedTarget } = parseArgs(process.argv);

  const detected = {
    claude: commandExists('claude'),
    codex: commandExists('codex'),
    gemini: commandExists('gemini'),
  };

  const hasClaudeDir = fs.existsSync(claudeDir);
  const hasCodexDir = fs.existsSync(codexDir);

  let target = requestedTarget;
  if (requestedTarget === 'auto') {
    const wantClaude = hasClaudeDir || detected.claude;
    const wantCodex = hasCodexDir || detected.codex;

    if (wantClaude && wantCodex) target = 'both';
    else if (wantCodex) target = 'codex';
    else if (wantClaude) target = 'claude';
    else target = 'claude';

    console.log(`${CYAN}Auto-detected target:${NC} ${target}`);
    if (!wantClaude && !wantCodex) {
      console.log(
        `${YELLOW}  ⓘ Could not detect Claude Code or Codex CLI; defaulting to "claude". Use --target codex if needed.${NC}`
      );
    }
    console.log();
  }

  const installs = [];
  if (target === 'claude' || target === 'both') {
    installs.push({
      label: 'Claude Code',
      rootDir: claudeDir,
      skillsDest: path.join(claudeDir, 'skills', 'agent-council'),
      displayPath: '.claude/skills/agent-council',
      hostRole: 'claude',
    });
  }
  if (target === 'codex' || target === 'both') {
    installs.push({
      label: 'Codex CLI',
      rootDir: codexDir,
      skillsDest: path.join(codexDir, 'skills', 'agent-council'),
      displayPath: '.codex/skills/agent-council',
      hostRole: 'codex',
    });
  }

  // Copy skills folder to target(s)
  const skillsSrc = path.join(packageRoot, 'skills', 'agent-council');
  const templateConfigPath = path.join(packageRoot, 'council.config.yaml');
  const templateConfigText = fs.existsSync(templateConfigPath) ? fs.readFileSync(templateConfigPath, 'utf8') : null;

  for (const install of installs) {
    if (!fs.existsSync(install.rootDir)) {
      fs.mkdirSync(install.rootDir, { recursive: true });
    }

    if (fs.existsSync(skillsSrc)) {
      console.log(`${YELLOW}Installing skills (${install.label})...${NC}`);
      copyRecursive(skillsSrc, install.skillsDest);
      console.log(`${GREEN}  ✓ ${install.displayPath}${NC}`);
    }

    // Ship runtime dependencies needed by the skill at execution time.
    const runtimeModulesDir = path.join(install.skillsDest, 'node_modules');
    if (!fs.existsSync(runtimeModulesDir)) fs.mkdirSync(runtimeModulesDir, { recursive: true });

    console.log(`${YELLOW}Installing runtime deps (${install.label})...${NC}`);
    copyRecursive(yamlModuleDir, path.join(runtimeModulesDir, 'yaml'));
    console.log(`${GREEN}  ✓ ${install.displayPath}/node_modules/yaml${NC}`);

    // Copy config file to skill folder if not exists
    const configDest = path.join(install.skillsDest, 'council.config.yaml');
    if (!fs.existsSync(configDest)) {
      console.log(`${YELLOW}Installing config (${install.label})...${NC}`);
      if (!templateConfigText) {
        console.log(`${YELLOW}  ⓘ Template council.config.yaml not found; writing an empty config.${NC}`);
        fs.writeFileSync(
          configDest,
          ['council:', '  members: []', '  chairman:', '    role: "auto"', '  settings:', '    parallel: true', ''].join(
            '\n'
          ),
          'utf8'
        );
        console.log(`${GREEN}  ✓ ${install.displayPath}/council.config.yaml${NC}`);
        continue;
      }

      const doc = YAML.parseDocument(templateConfigText);
      const membersNode = doc.getIn(['council', 'members']);

      if (membersNode && YAML.isCollection(membersNode)) {
        const enabledMembers = membersNode.items.filter((item) => {
          const member = item.toJSON();
          const nameLc = String(member.name || '').toLowerCase();
          if (nameLc === install.hostRole) return false;

          const baseCommand = String(member.command || '')
            .trim()
            .split(/\s+/)[0];
          if (!baseCommand) return false;

          return commandExists(baseCommand);
        });

        membersNode.items = enabledMembers;

        if (enabledMembers.length === 0) {
          console.log(
            `${YELLOW}  ⓘ No member CLIs detected from template. Writing members: []; edit council.config.yaml to add members.${NC}`
          );
        }
      } else {
        console.log(`${YELLOW}  ⓘ Template is missing council.members; writing template as-is.${NC}`);
      }

      fs.writeFileSync(configDest, String(doc), 'utf8');
      console.log(`${GREEN}  ✓ ${install.displayPath}/council.config.yaml${NC}`);
    } else if (fs.existsSync(configDest)) {
      console.log(`${YELLOW}  ⓘ council.config.yaml already exists (${install.label}), skipping${NC}`);
    }
  }

  console.log();
  console.log(`${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}`);
  console.log(`${GREEN}  Installation complete!${NC}`);
  console.log(`${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}`);
  console.log();
  if (installs.some((i) => i.hostRole === 'claude')) {
    console.log(`${CYAN}Usage in Claude:${NC}`);
    console.log(`  "Summon the council"`);
    console.log(`  "Let's hear opinions from other AIs"`);
    console.log();
  }
  if (installs.some((i) => i.hostRole === 'codex')) {
    console.log(`${CYAN}Usage in Codex:${NC}`);
    console.log(`  "Summon the council"`);
    console.log(`  "Let's hear opinions from other AIs"`);
    console.log();
  }
  console.log();
  console.log(`${CYAN}Direct execution:${NC}`);
  if (installs.some((i) => i.hostRole === 'claude')) {
    console.log(`  .claude/skills/agent-council/scripts/council.sh "your question"`);
  }
  if (installs.some((i) => i.hostRole === 'codex')) {
    console.log(`  .codex/skills/agent-council/scripts/council.sh "your question"`);
  }
  console.log();
  console.log(`${YELLOW}Note: Only detected CLIs are enabled as members in the generated config.${NC}`);
  console.log(`${YELLOW}      Detected: claude=${detected.claude} codex=${detected.codex} gemini=${detected.gemini}${NC}`);

} catch (error) {
  console.error(`${RED}Error during installation: ${error.message}${NC}`);
  process.exit(1);
}


================================================
FILE: plugins/agent-council/council.config.yaml
================================================
# Agent Council Configuration
# Add or remove council members as needed.
# Note: the installer filters members to detected CLIs only on initial generation.
# After that, missing CLIs are not auto-removed and will report `missing_cli` at runtime.

council:
  # Council members configuration
  # Each member needs:
  #   - name: identifier for the agent
  #   - command: CLI command to execute (prompt will be appended)
  #   - emoji: display emoji (optional)
  #   - color: ANSI color (RED, GREEN, BLUE, YELLOW, CYAN)

  members:
    
    - name: codex
      command: "codex exec"
      emoji: "🤖"
      color: "BLUE"

    - name: gemini
      command: "gemini"
      emoji: "💎"
      color: "GREEN"

  # Chairman configuration (Claude will act as chairman)
  chairman:
    # role: auto|claude|codex|gemini|...
    # - auto: infer from host tool (Claude Code => claude, Codex CLI => codex)
    role: "auto"
    description: "Synthesizes all opinions and provides final recommendation"
    # Optional: run synthesis inside council.sh via CLI (otherwise the host agent synthesizes)
    # command: "codex exec"

    # Execution settings
  settings:
    timeout: 120 # Timeout seconds per agent (0 to disable)
    exclude_chairman_from_members: true # Avoid calling the chairman as a member by default
    # synthesize: true       # Force Stage 3 synthesis inside council.sh (requires chairman.command or --chairman codex/gemini)


================================================
FILE: plugins/agent-council/package.json
================================================
{
  "name": "@team-attention/agent-council",
  "version": "1.0.0",
  "description": "Collect and synthesize opinions from multiple AI Agents for Claude Code",
  "bin": {
    "agent-council": "./bin/install.js"
  },
  "files": [
    "bin/",
    "skills/",
    "council.config.yaml"
  ],
  "dependencies": {
    "yaml": "^2.8.2"
  },
  "keywords": [
    "claude-code",
    "plugin",
    "llm",
    "multi-agent",
    "ai-council"
  ],
  "author": "Team Attention",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/team-attention/plugins-for-claude-natives.git"
  },
  "homepage": "https://github.com/team-attention/plugins-for-claude-natives"
}


================================================
FILE: plugins/agent-council/scripts/council-job-worker.js
================================================
#!/usr/bin/env node

const fs = require('fs');
const path = require('path');
const crypto = require('crypto');
const { spawn } = require('child_process');

function exitWithError(message) {
  process.stderr.write(`${message}\n`);
  process.exit(1);
}

function parseArgs(argv) {
  const args = argv.slice(2);
  const out = { _: [] };
  for (let i = 0; i < args.length; i++) {
    const a = args[i];
    if (!a.startsWith('--')) {
      out._.push(a);
      continue;
    }

    const [key, rawValue] = a.split('=', 2);
    if (rawValue != null) {
      out[key.slice(2)] = rawValue;
      continue;
    }
    const next = args[i + 1];
    if (next == null || next.startsWith('--')) {
      out[key.slice(2)] = true;
      continue;
    }
    out[key.slice(2)] = next;
    i++;
  }
  return out;
}

function splitCommand(command) {
  const tokens = [];
  let current = '';
  let inSingle = false;
  let inDouble = false;
  let escapeNext = false;

  for (const ch of String(command || '')) {
    if (escapeNext) {
      current += ch;
      escapeNext = false;
      continue;
    }

    if (!inSingle && ch === '\\') {
      escapeNext = true;
      continue;
    }

    if (!inDouble && ch === "'") {
      inSingle = !inSingle;
      continue;
    }

    if (!inSingle && ch === '"') {
      inDouble = !inDouble;
      continue;
    }

    if (!inSingle && !inDouble && /\s/.test(ch)) {
      if (current) tokens.push(current);
      current = '';
      continue;
    }

    current += ch;
  }

  if (current) tokens.push(current);
  if (inSingle || inDouble) return null;
  return tokens;
}

function atomicWriteJson(filePath, payload) {
  const tmpPath = `${filePath}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
  fs.writeFileSync(tmpPath, JSON.stringify(payload, null, 2), 'utf8');
  fs.renameSync(tmpPath, filePath);
}

function main() {
  const options = parseArgs(process.argv);
  const jobDir = options['job-dir'];
  const member = options.member;
  const safeMember = options['safe-member'];
  const command = options.command;
  const timeoutSec = options.timeout ? Number(options.timeout) : 0;

  if (!jobDir) exitWithError('worker: missing --job-dir');
  if (!member) exitWithError('worker: missing --member');
  if (!safeMember) exitWithError('worker: missing --safe-member');
  if (!command) exitWithError('worker: missing --command');

  const membersRoot = path.join(jobDir, 'members');
  const memberDir = path.join(membersRoot, safeMember);
  const statusPath = path.join(memberDir, 'status.json');
  const outPath = path.join(memberDir, 'output.txt');
  const errPath = path.join(memberDir, 'error.txt');

  const promptPath = path.join(jobDir, 'prompt.txt');
  const prompt = fs.existsSync(promptPath) ? fs.readFileSync(promptPath, 'utf8') : '';

  const tokens = splitCommand(command);
  if (!tokens || tokens.length === 0) {
    atomicWriteJson(statusPath, {
      member,
      state: 'error',
      message: 'Invalid command string',
      finishedAt: new Date().toISOString(),
      command,
    });
    process.exit(1);
  }

  const program = tokens[0];
  const args = tokens.slice(1);

  atomicWriteJson(statusPath, {
    member,
    state: 'running',
    startedAt: new Date().toISOString(),
    command,
    pid: null,
  });

  const outStream = fs.createWriteStream(outPath, { flags: 'w' });
  const errStream = fs.createWriteStream(errPath, { flags: 'w' });

  let child;
  try {
    child = spawn(program, [...args, prompt], {
      stdio: ['ignore', 'pipe', 'pipe'],
      env: process.env,
    });
  } catch (error) {
    atomicWriteJson(statusPath, {
      member,
      state: 'error',
      message: error && error.message ? error.message : 'Failed to spawn command',
      finishedAt: new Date().toISOString(),
      command,
    });
    process.exit(1);
  }

  atomicWriteJson(statusPath, {
    member,
    state: 'running',
    startedAt: new Date().toISOString(),
    command,
    pid: child.pid,
  });

  if (child.stdout) child.stdout.pipe(outStream);
  if (child.stderr) child.stderr.pipe(errStream);

  let timeoutHandle = null;
  let timeoutTriggered = false;
  if (Number.isFinite(timeoutSec) && timeoutSec > 0) {
    timeoutHandle = setTimeout(() => {
      timeoutTriggered = true;
      try {
        process.kill(child.pid, 'SIGTERM');
      } catch {
        // ignore
      }
    }, timeoutSec * 1000);
    timeoutHandle.unref();
  }

  const finalize = (payload) => {
    try {
      outStream.end();
      errStream.end();
    } catch {
      // ignore
    }
    atomicWriteJson(statusPath, payload);
  };

  child.on('error', (error) => {
    const isMissing = error && error.code === 'ENOENT';
    finalize({
      member,
      state: isMissing ? 'missing_cli' : 'error',
      message: error && error.message ? error.message : 'Process error',
      finishedAt: new Date().toISOString(),
      command,
      exitCode: null,
      pid: child.pid,
    });
    process.exit(1);
  });

  child.on('exit', (code, signal) => {
    if (timeoutHandle) clearTimeout(timeoutHandle);
    const timedOut = Boolean(timeoutTriggered) && signal === 'SIGTERM';
    const canceled = !timedOut && signal === 'SIGTERM';
    finalize({
      member,
      state: timedOut ? 'timed_out' : canceled ? 'canceled' : code === 0 ? 'done' : 'error',
      message: timedOut ? `Timed out after ${timeoutSec}s` : canceled ? 'Canceled' : null,
      finishedAt: new Date().toISOString(),
      command,
      exitCode: typeof code === 'number' ? code : null,
      signal: signal || null,
      pid: child.pid,
    });
    process.exit(code === 0 ? 0 : 1);
  });
}

if (require.main === module) {
  main();
}


================================================
FILE: plugins/agent-council/scripts/council-job.js
================================================
#!/usr/bin/env node

const fs = require('fs');
const path = require('path');
const crypto = require('crypto');
const { spawn } = require('child_process');

const SCRIPT_DIR = __dirname;
const SKILL_DIR = path.resolve(SCRIPT_DIR, '..');
const WORKER_PATH = path.join(SCRIPT_DIR, 'council-job-worker.js');

const SKILL_CONFIG_FILE = path.join(SKILL_DIR, 'council.config.yaml');
const REPO_CONFIG_FILE = path.join(path.resolve(SKILL_DIR, '../..'), 'council.config.yaml');

function exitWithError(message) {
  process.stderr.write(`${message}\n`);
  process.exit(1);
}

function resolveDefaultConfigFile() {
  if (fs.existsSync(SKILL_CONFIG_FILE)) return SKILL_CONFIG_FILE;
  if (fs.existsSync(REPO_CONFIG_FILE)) return REPO_CONFIG_FILE;
  return SKILL_CONFIG_FILE;
}

function detectHostRole() {
  const normalized = SKILL_DIR.replace(/\\/g, '/');
  if (normalized.includes('/.claude/skills/')) return 'claude';
  if (normalized.includes('/.codex/skills/')) return 'codex';
  return 'unknown';
}

function normalizeBool(value) {
  if (value == null) return null;
  const v = String(value).trim().toLowerCase();
  if (['1', 'true', 'yes', 'y', 'on'].includes(v)) return true;
  if (['0', 'false', 'no', 'n', 'off'].includes(v)) return false;
  return null;
}

function resolveAutoRole(role, hostRole) {
  const roleLc = String(role || '').trim().toLowerCase();
  if (roleLc && roleLc !== 'auto') return roleLc;
  if (hostRole === 'codex') return 'codex';
  if (hostRole === 'claude') return 'claude';
  return 'claude';
}

function parseCouncilConfig(configPath) {
  const fallback = {
    council: {
      chairman: { role: 'auto' },
      members: [
        { name: 'claude', command: 'claude -p', emoji: '🧠', color: 'CYAN' },
        { name: 'codex', command: 'codex exec', emoji: '🤖', color: 'BLUE' },
        { name: 'gemini', command: 'gemini', emoji: '💎', color: 'GREEN' },
      ],
      settings: { exclude_chairman_from_members: true, timeout: 120 },
    },
  };

  if (!fs.existsSync(configPath)) return fallback;

  let YAML;
  try {
    YAML = require('yaml');
  } catch {
    exitWithError(
      [
        'Missing runtime dependency: yaml',
        'Your Agent Council installation is out of date.',
        'Reinstall from your project root:',
        '  npx github:team-attention/agent-council --target auto',
      ].join('\n')
    );
  }

  let parsed;
  try {
    parsed = YAML.parse(fs.readFileSync(configPath, 'utf8'));
  } catch (error) {
    const message = error && error.message ? error.message : String(error);
    exitWithError(`Invalid YAML in ${configPath}: ${message}`);
  }

  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
    exitWithError(`Invalid config in ${configPath}: expected a YAML mapping/object at the document root`);
  }
  if (!parsed.council) {
    exitWithError(`Invalid config in ${configPath}: missing required top-level key 'council:'`);
  }
  if (typeof parsed.council !== 'object' || Array.isArray(parsed.council)) {
    exitWithError(`Invalid config in ${configPath}: 'council' must be a mapping/object`);
  }

  const merged = {
    council: {
      chairman: { ...fallback.council.chairman },
      members: Array.isArray(fallback.council.members) ? [...fallback.council.members] : [],
      settings: { ...fallback.council.settings },
    },
  };

  const council = parsed.council;

  if (council.chairman != null) {
    if (typeof council.chairman !== 'object' || Array.isArray(council.chairman)) {
      exitWithError(`Invalid config in ${configPath}: 'council.chairman' must be a mapping/object`);
    }
    merged.council.chairman = { ...merged.council.chairman, ...council.chairman };
  }

  if (Object.prototype.hasOwnProperty.call(council, 'members')) {
    if (!Array.isArray(council.members)) {
      exitWithError(`Invalid config in ${configPath}: 'council.members' must be a list/array`);
    }
    merged.council.members = council.members;
  }

  if (council.settings != null) {
    if (typeof council.settings !== 'object' || Array.isArray(council.settings)) {
      exitWithError(`Invalid config in ${configPath}: 'council.settings' must be a mapping/object`);
    }
    merged.council.settings = { ...merged.council.settings, ...council.settings };
  }

  return merged;
}

function ensureDir(dirPath) {
  fs.mkdirSync(dirPath, { recursive: true });
}

function safeFileName(name) {
  const cleaned = String(name || '').trim().toLowerCase().replace(/[^a-z0-9_-]+/g, '-');
  return cleaned || 'member';
}

function atomicWriteJson(filePath, payload) {
  const tmpPath = `${filePath}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
  fs.writeFileSync(tmpPath, JSON.stringify(payload, null, 2), 'utf8');
  fs.renameSync(tmpPath, filePath);
}

function readJsonIfExists(filePath) {
  try {
    if (!fs.existsSync(filePath)) return null;
    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
  } catch {
    return null;
  }
}

function sleepMs(ms) {
  const msNum = Number(ms);
  if (!Number.isFinite(msNum) || msNum <= 0) return;
  const sab = new SharedArrayBuffer(4);
  const view = new Int32Array(sab);
  Atomics.wait(view, 0, 0, Math.trunc(msNum));
}

function computeTerminalDoneCount(counts) {
  const c = counts || {};
  return (
    Number(c.done || 0) +
    Number(c.missing_cli || 0) +
    Number(c.error || 0) +
    Number(c.timed_out || 0) +
    Number(c.canceled || 0)
  );
}

function asCodexStepStatus(value) {
  const v = String(value || '');
  if (v === 'pending' || v === 'in_progress' || v === 'completed') return v;
  return 'pending';
}

function buildCouncilUiPayload(statusPayload) {
  const counts = statusPayload.counts || {};
  const done = computeTerminalDoneCount(counts);
  const total = Number(counts.total || 0);
  const isDone = String(statusPayload.overallState || '') === 'done';

  const queued = Number(counts.queued || 0);
  const running = Number(counts.running || 0);

  const members = Array.isArray(statusPayload.members) ? statusPayload.members : [];
  const sortedMembers = members
    .map((m) => ({
      member: m && m.member != null ? String(m.member) : '',
      state: m && m.state != null ? String(m.state) : 'unknown',
      exitCode: m && m.exitCode != null ? m.exitCode : null,
    }))
    .filter((m) => m.member)
    .sort((a, b) => a.member.localeCompare(b.member));

  const terminalStates = new Set(['done', 'missing_cli', 'error', 'timed_out', 'canceled']);
  // Keep the Plan UI visible by ensuring exactly one `in_progress` item while work remains.
  const dispatchStatus = asCodexStepStatus(isDone ? 'completed' : queued > 0 ? 'in_progress' : 'completed');
  let hasInProgress = dispatchStatus === 'in_progress';

  const memberSteps = sortedMembers.map((m) => {
    const state = m.state || 'unknown';
    const isTerminal = terminalStates.has(state);

    let status;
    if (isTerminal) {
      status = 'completed';
    } else if (!hasInProgress && running > 0 && state === 'running') {
      status = 'in_progress';
      hasInProgress = true;
    } else {
      status = 'pending';
    }

    const label = `[Council] Ask ${m.member}`;
    return { label, status: asCodexStepStatus(status) };
  });

  // Once members are done, the host agent should synthesize and then mark this step completed.
  const synthStatus = asCodexStepStatus(isDone ? (hasInProgress ? 'pending' : 'in_progress') : 'pending');

  const codexPlan = [
    { step: `[Council] Prompt dispatch`, status: dispatchStatus },
    ...memberSteps.map((s) => ({ step: s.label, status: s.status })),
    { step: `[Council] Synthesize`, status: synthStatus },
  ];

  const claudeTodos = [
    {
      content: `[Council] Prompt dispatch`,
      status: dispatchStatus,
      activeForm: dispatchStatus === 'completed' ? 'Dispatched council prompts' : 'Dispatching council prompts',
    },
    ...memberSteps.map((s) => ({
      content: s.label,
      status: s.status,
      activeForm: s.status === 'completed' ? 'Finished' : 'Awaiting response',
    })),
    {
      content: `[Council] Synthesize`,
      status: synthStatus,
      activeForm:
        synthStatus === 'completed'
          ? 'Council results ready'
          : synthStatus === 'in_progress'
            ? 'Ready to synthesize'
            : 'Waiting to synthesize',
    },
  ];

  return {
    progress: { done, total, overallState: String(statusPayload.overallState || '') },
    codex: { update_plan: { plan: codexPlan } },
    claude: { todo_write: { todos: claudeTodos } },
  };
}

function computeStatusPayload(jobDir) {
  const resolvedJobDir = path.resolve(jobDir);
  if (!fs.existsSync(resolvedJobDir)) exitWithError(`jobDir not found: ${resolvedJobDir}`);

  const jobMeta = readJsonIfExists(path.join(resolvedJobDir, 'job.json'));
  if (!jobMeta) exitWithError(`job.json not found: ${path.join(resolvedJobDir, 'job.json')}`);

  const membersRoot = path.join(resolvedJobDir, 'members');
  if (!fs.existsSync(membersRoot)) exitWithError(`members folder not found: ${membersRoot}`);

  const members = [];
  for (const entry of fs.readdirSync(membersRoot)) {
    const statusPath = path.join(membersRoot, entry, 'status.json');
    const status = readJsonIfExists(statusPath);
    if (status) members.push({ safeName: entry, ...status });
  }

  const totals = { queued: 0, running: 0, done: 0, error: 0, missing_cli: 0, timed_out: 0, canceled: 0 };
  for (const m of members) {
    const state = String(m.state || 'unknown');
    if (Object.prototype.hasOwnProperty.call(totals, state)) totals[state]++;
  }

  const allDone = totals.running === 0 && totals.queued === 0;
  const overallState = allDone ? 'done' : totals.running > 0 ? 'running' : 'queued';

  return {
    jobDir: resolvedJobDir,
    id: jobMeta.id || null,
    chairmanRole: jobMeta.chairmanRole || null,
    overallState,
    counts: { total: members.length, ...totals },
    members: members
      .map((m) => ({
        member: m.member,
        state: m.state,
        startedAt: m.startedAt || null,
        finishedAt: m.finishedAt || null,
        exitCode: m.exitCode != null ? m.exitCode : null,
        message: m.message || null,
      }))
      .sort((a, b) => String(a.member).localeCompare(String(b.member))),
  };
}

function parseArgs(argv) {
  const args = argv.slice(2);
  const out = { _: [] };
  const booleanFlags = new Set([
    'json',
    'text',
    'checklist',
    'help',
    'h',
    'verbose',
    'include-chairman',
    'exclude-chairman',
  ]);
  for (let i = 0; i < args.length; i++) {
    const a = args[i];
    if (a === '--') {
      out._.push(...args.slice(i + 1));
      break;
    }
    if (!a.startsWith('--')) {
      out._.push(a);
      continue;
    }

    const [key, rawValue] = a.split('=', 2);
    if (rawValue != null) {
      out[key.slice(2)] = rawValue;
      continue;
    }

    const normalizedKey = key.slice(2);
    if (booleanFlags.has(normalizedKey)) {
      out[normalizedKey] = true;
      continue;
    }

    const next = args[i + 1];
    if (next == null || next.startsWith('--')) {
      out[normalizedKey] = true;
      continue;
    }
    out[normalizedKey] = next;
    i++;
  }
  return out;
}

function printHelp() {
  process.stdout.write(`Agent Council (job mode)

Usage:
  council-job.sh start [--config path] [--chairman auto|claude|codex|...] [--jobs-dir path] [--json] "question"
  council-job.sh status [--json|--text|--checklist] [--verbose] <jobDir>
  council-job.sh wait [--cursor CURSOR] [--bucket auto|N] [--interval-ms N] [--timeout-ms N] <jobDir>
  council-job.sh results [--json] <jobDir>
  council-job.sh stop <jobDir>
  council-job.sh clean <jobDir>

Notes:
  - start returns immediately and runs members in parallel via detached Node workers
  - poll status with repeated short calls to update TODO/plan UIs in host agents
  - wait prints JSON by default and blocks until meaningful progress occurs, so you don't spam tool cells
`);
}

function cmdStart(options, prompt) {
  const configPath = options.config || process.env.COUNCIL_CONFIG || resolveDefaultConfigFile();
  const jobsDir =
    options['jobs-dir'] || process.env.COUNCIL_JOBS_DIR || path.join(SKILL_DIR, '.jobs');

  ensureDir(jobsDir);

  const hostRole = detectHostRole();
  const config = parseCouncilConfig(configPath);
  const chairmanRoleRaw = options.chairman || process.env.COUNCIL_CHAIRMAN || config.council.chairman.role || 'auto';
  const chairmanRole = resolveAutoRole(chairmanRoleRaw, hostRole);

  const includeChairman = Boolean(options['include-chairman']);
  const excludeChairmanOverride =
    options['exclude-chairman'] != null ? true : options['include-chairman'] != null ? false : null;

  const excludeSetting = normalizeBool(config.council.settings.exclude_chairman_from_members);
  const excludeChairmanFromMembers =
    excludeChairmanOverride != null ? excludeChairmanOverride : excludeSetting != null ? excludeSetting : true;

  const timeoutSetting = Number(config.council.settings.timeout || 0);
  const timeoutOverride = options.timeout != null ? Number(options.timeout) : null;
  const timeoutSec = Number.isFinite(timeoutOverride) && timeoutOverride > 0 ? timeoutOverride : timeoutSetting > 0 ? timeoutSetting : 0;

  const requestedMembers = config.council.members || [];
  const members = requestedMembers.filter((m) => {
    if (!m || !m.name || !m.command) return false;
    const nameLc = String(m.name).toLowerCase();
    if (excludeChairmanFromMembers && !includeChairman && nameLc === chairmanRole) return false;
    return true;
  });

  const jobId = `${new Date().toISOString().replace(/[:.]/g, '').replace('T', '-').slice(0, 15)}-${crypto
    .randomBytes(3)
    .toString('hex')}`;
  const jobDir = path.join(jobsDir, `council-${jobId}`);
  const membersDir = path.join(jobDir, 'members');
  ensureDir(membersDir);

  fs.writeFileSync(path.join(jobDir, 'prompt.txt'), String(prompt), 'utf8');

  const jobMeta = {
    id: `council-${jobId}`,
    createdAt: new Date().toISOString(),
    configPath,
    hostRole,
    chairmanRole,
    settings: {
      excludeChairmanFromMembers,
      timeoutSec: timeoutSec || null,
    },
    members: members.map((m) => ({
      name: String(m.name),
      command: String(m.command),
      emoji: m.emoji ? String(m.emoji) : null,
      color: m.color ? String(m.color) : null,
    })),
  };
  atomicWriteJson(path.join(jobDir, 'job.json'), jobMeta);

  for (const member of members) {
    const name = String(member.name);
    const safeName = safeFileName(name);
    const memberDir = path.join(membersDir, safeName);
    ensureDir(memberDir);

    atomicWriteJson(path.join(memberDir, 'status.json'), {
      member: name,
      state: 'queued',
      queuedAt: new Date().toISOString(),
      command: String(member.command),
    });

    const workerArgs = [
      WORKER_PATH,
      '--job-dir',
      jobDir,
      '--member',
      name,
      '--safe-member',
      safeName,
      '--command',
      String(member.command),
    ];
    if (timeoutSec && Number.isFinite(timeoutSec) && timeoutSec > 0) {
      workerArgs.push('--timeout', String(timeoutSec));
    }

    const child = spawn(process.execPath, workerArgs, {
      detached: true,
      stdio: 'ignore',
      env: process.env,
    });
    child.unref();
  }

  if (options.json) {
    process.stdout.write(`${JSON.stringify({ jobDir, ...jobMeta }, null, 2)}\n`);
  } else {
    process.stdout.write(`${jobDir}\n`);
  }
}

function cmdStatus(options, jobDir) {
  const payload = computeStatusPayload(jobDir);

  const wantChecklist = Boolean(options.checklist) && !options.json;
  if (wantChecklist) {
    const done = computeTerminalDoneCount(payload.counts);
    const headerId = payload.id ? ` (${payload.id})` : '';
    process.stdout.write(`Agent Council${headerId}\n`);
    process.stdout.write(
      `Progress: ${done}/${payload.counts.total} done  (running ${payload.counts.running}, queued ${payload.counts.queued})\n`
    );
    for (const m of payload.members) {
      const state = String(m.state || '');
      const mark =
        state === 'done'
          ? '[x]'
          : state === 'running' || state === 'queued'
            ? '[ ]'
            : state
              ? '[!]'
              : '[ ]';
      const exitInfo = m.exitCode != null ? ` (exit ${m.exitCode})` : '';
      process.stdout.write(`${mark} ${m.member} — ${state}${exitInfo}\n`);
    }
    return;
  }

  const wantText = Boolean(options.text) && !options.json;
  if (wantText) {
    const done = computeTerminalDoneCount(payload.counts);
    process.stdout.write(`members ${done}/${payload.counts.total} done; running=${payload.counts.running} queued=${payload.counts.queued}\n`);
    if (options.verbose) {
      for (const m of payload.members) {
        process.stdout.write(`- ${m.member}: ${m.state}${m.exitCode != null ? ` (exit ${m.exitCode})` : ''}\n`);
      }
    }
    return;
  }

  process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
}

function parseWaitCursor(value) {
  const raw = String(value || '').trim();
  if (!raw) return null;
  const parts = raw.split(':');
  const version = parts[0];
  if (version === 'v1' && parts.length === 4) {
    const bucketSize = Number(parts[1]);
    const doneBucket = Number(parts[2]);
    const isDone = parts[3] === '1';
    if (!Number.isFinite(bucketSize) || bucketSize <= 0) return null;
    if (!Number.isFinite(doneBucket) || doneBucket < 0) return null;
    return { version, bucketSize, dispatchBucket: 0, doneBucket, isDone };
  }
  if (version === 'v2' && parts.length === 5) {
    const bucketSize = Number(parts[1]);
    const dispatchBucket = Number(parts[2]);
    const doneBucket = Number(parts[3]);
    const isDone = parts[4] === '1';
    if (!Number.isFinite(bucketSize) || bucketSize <= 0) return null;
    if (!Number.isFinite(dispatchBucket) || dispatchBucket < 0) return null;
    if (!Number.isFinite(doneBucket) || doneBucket < 0) return null;
    return { version, bucketSize, dispatchBucket, doneBucket, isDone };
  }
  return null;
}

function formatWaitCursor(bucketSize, dispatchBucket, doneBucket, isDone) {
  return `v2:${bucketSize}:${dispatchBucket}:${doneBucket}:${isDone ? 1 : 0}`;
}

function asWaitPayload(statusPayload) {
  const members = Array.isArray(statusPayload.members) ? statusPayload.members : [];
  return {
    jobDir: statusPayload.jobDir,
    id: statusPayload.id,
    chairmanRole: statusPayload.chairmanRole,
    overallState: statusPayload.overallState,
    counts: statusPayload.counts,
    members: members.map((m) => ({
      member: m.member,
      state: m.state,
      exitCode: m.exitCode != null ? m.exitCode : null,
      message: m.message || null,
    })),
    ui: buildCouncilUiPayload(statusPayload),
  };
}

function resolveBucketSize(options, total, prevCursor) {
  const raw = options.bucket != null ? options.bucket : options['bucket-size'];

  if (raw == null || raw === true) {
    if (prevCursor && prevCursor.bucketSize) return prevCursor.bucketSize;
  } else {
    const asString = String(raw).trim().toLowerCase();
    if (asString !== 'auto') {
      const num = Number(asString);
      if (!Number.isFinite(num) || num <= 0) exitWithError(`wait: invalid --bucket: ${raw}`);
      return Math.trunc(num);
    }
  }

  // Auto-bucket: target ~5 updates total.
  const totalNum = Number(total || 0);
  if (!Number.isFinite(totalNum) || totalNum <= 0) return 1;
  return Math.max(1, Math.ceil(totalNum / 5));
}

function cmdWait(options, jobDir) {
  const resolvedJobDir = path.resolve(jobDir);
  const cursorFilePath = path.join(resolvedJobDir, '.wait_cursor');
  const prevCursorRaw =
    options.cursor != null
      ? String(options.cursor)
      : fs.existsSync(cursorFilePath)
        ? String(fs.readFileSync(cursorFilePath, 'utf8')).trim()
        : '';
  const prevCursor = parseWaitCursor(prevCursorRaw);

  const intervalMsRaw = options['interval-ms'] != null ? options['interval-ms'] : 250;
  const intervalMs = Math.max(50, Math.trunc(Number(intervalMsRaw)));
  if (!Number.isFinite(intervalMs) || intervalMs <= 0) exitWithError(`wait: invalid --interval-ms: ${intervalMsRaw}`);

  const timeoutMsRaw = options['timeout-ms'] != null ? options['timeout-ms'] : 0;
  const timeoutMs = Math.trunc(Number(timeoutMsRaw));
  if (!Number.isFinite(timeoutMs) || timeoutMs < 0) exitWithError(`wait: invalid --timeout-ms: ${timeoutMsRaw}`);

  // Always read once to decide bucket sizing and (when no cursor is given) return immediately.
  let payload = computeStatusPayload(jobDir);
  const bucketSize = resolveBucketSize(options, payload.counts.total, prevCursor);

  const doneCount = computeTerminalDoneCount(payload.counts);
  const isDone = payload.overallState === 'done';
  const total = Number(payload.counts.total || 0);
  const queued = Number(payload.counts.queued || 0);
  const dispatchBucket = queued === 0 && total > 0 ? 1 : 0;
  const doneBucket = Math.floor(doneCount / bucketSize);
  const cursor = formatWaitCursor(bucketSize, dispatchBucket, doneBucket, isDone);

  if (!prevCursor) {
    fs.writeFileSync(cursorFilePath, cursor, 'utf8');
    process.stdout.write(`${JSON.stringify({ ...asWaitPayload(payload), cursor }, null, 2)}\n`);
    return;
  }

  const start = Date.now();
  while (cursor === prevCursorRaw) {
    if (timeoutMs > 0 && Date.now() - start >= timeoutMs) break;
    sleepMs(intervalMs);
    payload = computeStatusPayload(jobDir);
    const d = computeTerminalDoneCount(payload.counts);
    const doneFlag = payload.overallState === 'done';
    const totalCount = Number(payload.counts.total || 0);
    const queuedCount = Number(payload.counts.queued || 0);
    const dispatchB = queuedCount === 0 && totalCount > 0 ? 1 : 0;
    const doneB = Math.floor(d / bucketSize);
    const nextCursor = formatWaitCursor(bucketSize, dispatchB, doneB, doneFlag);
    if (nextCursor !== prevCursorRaw) {
      fs.writeFileSync(cursorFilePath, nextCursor, 'utf8');
      process.stdout.write(`${JSON.stringify({ ...asWaitPayload(payload), cursor: nextCursor }, null, 2)}\n`);
      return;
    }
  }

  // Timeout: return current state (cursor may be unchanged).
  const finalPayload = computeStatusPayload(jobDir);
  const finalDone = computeTerminalDoneCount(finalPayload.counts);
  const finalDoneFlag = finalPayload.overallState === 'done';
  const finalTotal = Number(finalPayload.counts.total || 0);
  const finalQueued = Number(finalPayload.counts.queued || 0);
  const finalDispatchBucket = finalQueued === 0 && finalTotal > 0 ? 1 : 0;
  const finalDoneBucket = Math.floor(finalDone / bucketSize);
  const finalCursor = formatWaitCursor(bucketSize, finalDispatchBucket, finalDoneBucket, finalDoneFlag);
  fs.writeFileSync(cursorFilePath, finalCursor, 'utf8');
  process.stdout.write(`${JSON.stringify({ ...asWaitPayload(finalPayload), cursor: finalCursor }, null, 2)}\n`);
}

function cmdResults(options, jobDir) {
  const resolvedJobDir = path.resolve(jobDir);
  const jobMeta = readJsonIfExists(path.join(resolvedJobDir, 'job.json'));
  const membersRoot = path.join(resolvedJobDir, 'members');

  const members = [];
  if (fs.existsSync(membersRoot)) {
    for (const entry of fs.readdirSync(membersRoot)) {
      const statusPath = path.join(membersRoot, entry, 'status.json');
      const outputPath = path.join(membersRoot, entry, 'output.txt');
      const errorPath = path.join(membersRoot, entry, 'error.txt');
      const status = readJsonIfExists(statusPath);
      if (!status) continue;
      const output = fs.existsSync(outputPath) ? fs.readFileSync(outputPath, 'utf8') : '';
      const stderr = fs.existsSync(errorPath) ? fs.readFileSync(errorPath, 'utf8') : '';
      members.push({ safeName: entry, ...status, output, stderr });
    }
  }

  if (options.json) {
    process.stdout.write(
      `${JSON.stringify(
        {
          jobDir: resolvedJobDir,
          id: jobMeta ? jobMeta.id : null,
          prompt: fs.existsSync(path.join(resolvedJobDir, 'prompt.txt'))
            ? fs.readFileSync(path.join(resolvedJobDir, 'prompt.txt'), 'utf8')
            : null,
          members: members
            .map((m) => ({
              member: m.member,
              state: m.state,
              exitCode: m.exitCode != null ? m.exitCode : null,
              message: m.message || null,
              output: m.output,
              stderr: m.stderr,
            }))
            .sort((a, b) => String(a.member).localeCompare(String(b.member))),
        },
        null,
        2
      )}\n`
    );
    return;
  }

  for (const m of members.sort((a, b) => String(a.member).localeCompare(String(b.member)))) {
    process.stdout.write(`\n=== ${m.member} (${m.state}) ===\n`);
    if (m.message) process.stdout.write(`${m.message}\n`);
    process.stdout.write(m.output || '');
    if (!m.output && m.stderr) {
      process.stdout.write('\n');
      process.stdout.write(m.stderr);
    }
    process.stdout.write('\n');
  }
}

function cmdStop(_options, jobDir) {
  const resolvedJobDir = path.resolve(jobDir);
  const membersRoot = path.join(resolvedJobDir, 'members');
  if (!fs.existsSync(membersRoot)) exitWithError(`No members folder found: ${membersRoot}`);

  let stoppedAny = false;
  for (const entry of fs.readdirSync(membersRoot)) {
    const statusPath = path.join(membersRoot, entry, 'status.json');
    const status = readJsonIfExists(statusPath);
    if (!status) continue;
    if (status.state !== 'running') continue;
    if (!status.pid) continue;

    try {
      process.kill(Number(status.pid), 'SIGTERM');
      stoppedAny = true;
    } catch {
      // ignore
    }
  }

  process.stdout.write(stoppedAny ? 'stop: sent SIGTERM to running members\n' : 'stop: no running members\n');
}

function cmdClean(_options, jobDir) {
  const resolvedJobDir = path.resolve(jobDir);
  fs.rmSync(resolvedJobDir, { recursive: true, force: true });
  process.stdout.write(`cleaned: ${resolvedJobDir}\n`);
}

function main() {
  const options = parseArgs(process.argv);
  const [command, ...rest] = options._;

  if (!command || options.help || options.h) {
    printHelp();
    return;
  }

  if (command === 'start') {
    const prompt = rest.join(' ').trim();
    if (!prompt) exitWithError('start: missing prompt');
    cmdStart(options, prompt);
    return;
  }
  if (command === 'status') {
    const jobDir = rest[0];
    if (!jobDir) exitWithError('status: missing jobDir');
    cmdStatus(options, jobDir);
    return;
  }
  if (command === 'wait') {
    const jobDir = rest[0];
    if (!jobDir) exitWithError('wait: missing jobDir');
    cmdWait(options, jobDir);
    return;
  }
  if (command === 'results') {
    const jobDir = rest[0];
    if (!jobDir) exitWithError('results: missing jobDir');
    cmdResults(options, jobDir);
    return;
  }
  if (command === 'stop') {
    const jobDir = rest[0];
    if (!jobDir) exitWithError('stop: missing jobDir');
    cmdStop(options, jobDir);
    return;
  }
  if (command === 'clean') {
    const jobDir = rest[0];
    if (!jobDir) exitWithError('clean: missing jobDir');
    cmdClean(options, jobDir);
    return;
  }

  exitWithError(`Unknown command: ${command}`);
}

if (require.main === module) {
  main();
}


================================================
FILE: plugins/agent-council/scripts/council-job.sh
================================================
#!/bin/bash

set -e

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

if ! command -v node >/dev/null 2>&1; then
  echo "Error: Node.js is required to run Agent Council job mode." >&2
  echo "Install Node.js and try again (plugin installs cannot bundle Node)." >&2
  echo "" >&2
  echo "macOS (Homebrew): brew install node" >&2
  echo "Or download from: https://nodejs.org/" >&2
  exit 127
fi

exec node "$SCRIPT_DIR/council-job.js" "$@"


================================================
FILE: plugins/agent-council/scripts/council.sh
================================================
#!/bin/bash
#
# Agent Council (job mode default)
#
# Subcommands:
#   council.sh start [options] "question"     # returns JOB_DIR immediately
#   council.sh status [--json|--text|--checklist] JOB_DIR # poll progress
#   council.sh wait [--cursor CURSOR] [--bucket auto|N] [--interval-ms N] [--timeout-ms N] JOB_DIR
#   council.sh results [--json] JOB_DIR       # print collected outputs
#   council.sh stop JOB_DIR                   # best-effort stop running members
#   council.sh clean JOB_DIR                  # remove job directory
#
# One-shot:
#   council.sh "question"
#   (in a real terminal: starts a job, waits for completion, prints results, cleans up)
#   (in host-agent tool UIs: returns a single `wait` JSON payload immediately; host drives progress + results)
#

set -e

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
JOB_SCRIPT="$SCRIPT_DIR/council-job.sh"

usage() {
  cat <<EOF
Agent Council

Default mode is job-based parallel execution (pollable).

Usage:
  $(basename "$0") start [options] "question"
  $(basename "$0") status [--json|--text|--checklist] <jobDir>
  $(basename "$0") wait [--cursor CURSOR] [--bucket auto|N] [--interval-ms N] [--timeout-ms N] <jobDir>
  $(basename "$0") results [--json] <jobDir>
  $(basename "$0") stop <jobDir>
  $(basename "$0") clean <jobDir>

One-shot:
  $(basename "$0") "question"
EOF
}

if [ $# -eq 0 ]; then
  usage
  exit 1
fi

case "$1" in
  -h|--help|help)
    usage
    exit 0
    ;;
esac

if ! command -v node >/dev/null 2>&1; then
  echo "Error: Node.js is required to run Agent Council." >&2
  echo "Claude Code plugins cannot bundle or auto-install Node." >&2
  echo "" >&2
  echo "macOS (Homebrew): brew install node" >&2
  echo "Or download from: https://nodejs.org/" >&2
  exit 127
fi

case "$1" in
  start|status|wait|results|stop|clean)
    exec "$JOB_SCRIPT" "$@"
    ;;
esac

in_host_agent_context() {
  if [ -n "${CODEX_CACHE_FILE:-}" ]; then
    return 0
  fi

  case "$SCRIPT_DIR" in
    */.codex/skills/*|*/.claude/skills/*)
      # Tool-call environments typically do not provide a real TTY on stdout/stderr.
      if [ ! -t 1 ] && [ ! -t 2 ]; then
        return 0
      fi
      ;;
  esac

  return 1
}

JOB_DIR="$("$JOB_SCRIPT" start "$@")"

# Host agents (Codex CLI / Claude Code) cannot update native TODO/plan UIs while a long-running
# command is executing. If we're in a host agent context, return immediately with a single `wait`
# JSON payload (includes `.ui.codex.update_plan.plan` / `.ui.claude.todo_write.todos`) and let the
# host agent drive progress updates with repeated short `wait` calls + native UI updates.
if in_host_agent_context; then
  exec "$JOB_SCRIPT" wait "$JOB_DIR"
fi

echo "council: started ${JOB_DIR}" >&2

cleanup_on_signal() {
  if [ -n "${JOB_DIR:-}" ] && [ -d "$JOB_DIR" ]; then
    "$JOB_SCRIPT" stop "$JOB_DIR" >/dev/null 2>&1 || true
    "$JOB_SCRIPT" clean "$JOB_DIR" >/dev/null 2>&1 || true
  fi
  exit 130
}

trap cleanup_on_signal INT TERM

while true; do
  WAIT_JSON="$("$JOB_SCRIPT" wait "$JOB_DIR")"
  OVERALL="$(printf '%s' "$WAIT_JSON" | node -e '
const fs=require("fs");
const d=JSON.parse(fs.readFileSync(0,"utf8"));
process.stdout.write(String(d.overallState||""));
')"

  "$JOB_SCRIPT" status --text "$JOB_DIR" >&2

  if [ "$OVERALL" = "done" ]; then
    break
  fi
done

trap - INT TERM

"$JOB_SCRIPT" results "$JOB_DIR"
"$JOB_SCRIPT" clean "$JOB_DIR" >/dev/null


================================================
FILE: plugins/agent-council/skills/agent-council/SKILL.md
================================================
---
name: agent-council
description: Collect and synthesize opinions from multiple AI agents. Use when users say "summon the council", "ask other AIs", or want multiple AI perspectives on a question.
---

# Agent Council

Collect multiple AI opinions and synthesize one answer.

## Usage

Run a job and collect results:

```bash
JOB_DIR=$(./skills/agent-council/scripts/council.sh start "your question here")
./skills/agent-council/scripts/council.sh wait "$JOB_DIR"
./skills/agent-council/scripts/council.sh results "$JOB_DIR"
./skills/agent-council/scripts/council.sh clean "$JOB_DIR"
```

One-shot:

```bash
./skills/agent-council/scripts/council.sh "your question here"
```

## References

- `references/overview.md` — workflow and background.
- `references/examples.md` — usage examples.
- `references/config.md` — member configuration.
- `references/requirements.md` — dependencies and CLI checks.
- `references/host-ui.md` — host UI checklist guidance.
- `references/safety.md` — safety notes.


================================================
FILE: plugins/agent-council/skills/agent-council/references/config.md
================================================
# Configure members

Edit `council.config.yaml` to set chairman and members:

```yaml
council:
  chairman:
    role: "auto"
  members:
    - name: claude
      command: "claude -p"
      emoji: "🧠"
      color: "CYAN"
    - name: codex
      command: "codex exec"
      emoji: "🤖"
      color: "BLUE"
    - name: gemini
      command: "gemini"
      emoji: "💎"
      color: "GREEN"
```

Add custom members by appending entries to `members`:

- Use a stable `name` (lowercase, short).
- Set `command` to a runnable CLI invocation.
- Provide `emoji` and `color` for readability (optional but recommended).
- Note that the installer filters members to detected CLIs only when it first generates `council.config.yaml`. After that, missing CLIs are not auto-removed and will report `missing_cli` at runtime; remove unavailable members or install the CLI before running.


================================================
FILE: plugins/agent-council/skills/agent-council/references/examples.md
================================================
# Examples

## Technical decision

Prompt:
```
React vs Vue - which fits this project better? Summon the council
```

Steps:
1. Run `council.sh` to collect opinions from configured members.
2. Organize member perspectives.
3. Recommend based on project context.

## Architecture review

Prompt:
```
Let's hear other AIs' opinions on this design
```

Steps:
1. Summarize the design and query the council.
2. Collect feedback from each member.
3. Analyze commonalities and synthesize.


================================================
FILE: plugins/agent-council/skills/agent-council/references/host-ui.md
================================================
# Host UI Checklist Guidance

Use these steps only when a host agent UI supports native checklist updates.

## Checklist flow

1. Run `council.sh wait` once to seed the cursor and get the JSON payload.
2. Update the host's native checklist UI using the payload (if provided).
3. Repeat `wait` until progress changes, then update the UI again.
4. Finish with `results` and `clean`.

## Behavior notes

- Do not run a blocking wait before the first checklist update, or the Plan UI may not appear.
- Keep exactly one in_progress item while work remains.
- Preserve existing checklist items and append the [Council] section.
- Avoid a long while loop in a single tool call; update after each wait return.
- Use `--bucket 1` for per-member updates when needed.


================================================
FILE: plugins/agent-council/skills/agent-council/references/overview.md
================================================
# Overview

- Gather responses from configured member CLIs.
- Let the chairman synthesize the final response (default: `role: auto`, current agent).
- Configure members in `council.config.yaml`; exclude the chairman from members by default.
- Reference [Karpathy's LLM Council](https://github.com/karpathy/llm-council) for inspiration.

## Workflow (3 stages)

1. Send the same prompt to each member.
2. Collect and surface member responses.
3. Synthesize the final answer as chairman; optionally run the chairman inside `council.sh` via `chairman.command`.


================================================
FILE: plugins/agent-council/skills/agent-council/references/requirements.md
================================================
# Requirements

- Install and authenticate the CLIs listed under `council.members` in `council.config.yaml`.
- Note that the installer filters members to detected CLIs only on initial config generation; afterward, missing CLIs show as `missing_cli` in status output.
- Install Node.js (plugins cannot bundle or auto-install it).
- Verify each member’s base command exists (for example, `command -v <binary>` or `<binary> --version`).


================================================
FILE: plugins/agent-council/skills/agent-council/references/safety.md
================================================
# Safety

- Do not share sensitive information with the council.


================================================
FILE: plugins/agent-council/skills/agent-council/scripts/council-job-worker.js
================================================
#!/usr/bin/env node

const fs = require('fs');
const path = require('path');
const crypto = require('crypto');
const { spawn } = require('child_process');

function exitWithError(message) {
  process.stderr.write(`${message}\n`);
  process.exit(1);
}

function parseArgs(argv) {
  const args = argv.slice(2);
  const out = { _: [] };
  for (let i = 0; i < args.length; i++) {
    const a = args[i];
    if (!a.startsWith('--')) {
      out._.push(a);
      continue;
    }

    const [key, rawValue] = a.split('=', 2);
    if (rawValue != null) {
      out[key.slice(2)] = rawValue;
      continue;
    }
    const next = args[i + 1];
    if (next == null || next.startsWith('--')) {
      out[key.slice(2)] = true;
      continue;
    }
    out[key.slice(2)] = next;
    i++;
  }
  return out;
}

function splitCommand(command) {
  const tokens = [];
  let current = '';
  let inSingle = false;
  let inDouble = false;
  let escapeNext = false;

  for (const ch of String(command || '')) {
    if (escapeNext) {
      current += ch;
      escapeNext = false;
      continue;
    }

    if (!inSingle && ch === '\\') {
      escapeNext = true;
      continue;
    }

    if (!inDouble && ch === "'") {
      inSingle = !inSingle;
      continue;
    }

    if (!inSingle && ch === '"') {
      inDouble = !inDouble;
      continue;
    }

    if (!inSingle && !inDouble && /\s/.test(ch)) {
      if (current) tokens.push(current);
      current = '';
      continue;
    }

    current += ch;
  }

  if (current) tokens.push(current);
  if (inSingle || inDouble) return null;
  return tokens;
}

function atomicWriteJson(filePath, payload) {
  const tmpPath = `${filePath}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
  fs.writeFileSync(tmpPath, JSON.stringify(payload, null, 2), 'utf8');
  fs.renameSync(tmpPath, filePath);
}

function main() {
  const options = parseArgs(process.argv);
  const jobDir = options['job-dir'];
  const member = options.member;
  const safeMember = options['safe-member'];
  const command = options.command;
  const timeoutSec = options.timeout ? Number(options.timeout) : 0;

  if (!jobDir) exitWithError('worker: missing --job-dir');
  if (!member) exitWithError('worker: missing --member');
  if (!safeMember) exitWithError('worker: missing --safe-member');
  if (!command) exitWithError('worker: missing --command');

  const membersRoot = path.join(jobDir, 'members');
  const memberDir = path.join(membersRoot, safeMember);
  const statusPath = path.join(memberDir, 'status.json');
  const outPath = path.join(memberDir, 'output.txt');
  const errPath = path.join(memberDir, 'error.txt');

  const promptPath = path.join(jobDir, 'prompt.txt');
  const prompt = fs.existsSync(promptPath) ? fs.readFileSync(promptPath, 'utf8') : '';

  const tokens = splitCommand(command);
  if (!tokens || tokens.length === 0) {
    atomicWriteJson(statusPath, {
      member,
      state: 'error',
      message: 'Invalid command string',
      finishedAt: new Date().toISOString(),
      command,
    });
    process.exit(1);
  }

  const program = tokens[0];
  const args = tokens.slice(1);

  atomicWriteJson(statusPath, {
    member,
    state: 'running',
    startedAt: new Date().toISOString(),
    command,
    pid: null,
  });

  const outStream = fs.createWriteStream(outPath, { flags: 'w' });
  const errStream = fs.createWriteStream(errPath, { flags: 'w' });

  let child;
  try {
    child = spawn(program, [...args, prompt], {
      stdio: ['ignore', 'pipe', 'pipe'],
      env: process.env,
    });
  } catch (error) {
    atomicWriteJson(statusPath, {
      member,
      state: 'error',
      message: error && error.message ? error.message : 'Failed to spawn command',
      finishedAt: new Date().toISOString(),
      command,
    });
    process.exit(1);
  }

  atomicWriteJson(statusPath, {
    member,
    state: 'running',
    startedAt: new Date().toISOString(),
    command,
    pid: child.pid,
  });

  if (child.stdout) child.stdout.pipe(outStream);
  if (child.stderr) child.stderr.pipe(errStream);

  let timeoutHandle = null;
  let timeoutTriggered = false;
  if (Number.isFinite(timeoutSec) && timeoutSec > 0) {
    timeoutHandle = setTimeout(() => {
      timeoutTriggered = true;
      try {
        process.kill(child.pid, 'SIGTERM');
      } catch {
        // ignore
      }
    }, timeoutSec * 1000);
    timeoutHandle.unref();
  }

  const finalize = (payload) => {
    try {
      outStream.end();
      errStream.end();
    } catch {
      // ignore
    }
    atomicWriteJson(statusPath, payload);
  };

  child.on('error', (error) => {
    const isMissing = error && error.code === 'ENOENT';
    finalize({
      member,
      state: isMissing ? 'missing_cli' : 'error',
      message: error && error.message ? error.message : 'Process error',
      finishedAt: new Date().toISOString(),
      command,
      exitCode: null,
      pid: child.pid,
    });
    process.exit(1);
  });

  child.on('exit', (code, signal) => {
    if (timeoutHandle) clearTimeout(timeoutHandle);
    const timedOut = Boolean(timeoutTriggered) && signal === 'SIGTERM';
    const canceled = !timedOut && signal === 'SIGTERM';
    finalize({
      member,
      state: timedOut ? 'timed_out' : canceled ? 'canceled' : code === 0 ? 'done' : 'error',
      message: timedOut ? `Timed out after ${timeoutSec}s` : canceled ? 'Canceled' : null,
      finishedAt: new Date().toISOString(),
      command,
      exitCode: typeof code === 'number' ? code : null,
      signal: signal || null,
      pid: child.pid,
    });
    process.exit(code === 0 ? 0 : 1);
  });
}

if (require.main === module) {
  main();
}


================================================
FILE: plugins/agent-council/skills/agent-council/scripts/council-job.js
================================================
#!/usr/bin/env node

const fs = require('fs');
const path = require('path');
const crypto = require('crypto');
const { spawn } = require('child_process');

const SCRIPT_DIR = __dirname;
const SKILL_DIR = path.resolve(SCRIPT_DIR, '..');
const WORKER_PATH = path.join(SCRIPT_DIR, 'council-job-worker.js');

const SKILL_CONFIG_FILE = path.join(SKILL_DIR, 'council.config.yaml');
const REPO_CONFIG_FILE = path.join(path.resolve(SKILL_DIR, '../..'), 'council.config.yaml');

function exitWithError(message) {
  process.stderr.write(`${message}\n`);
  process.exit(1);
}

function resolveDefaultConfigFile() {
  if (fs.existsSync(SKILL_CONFIG_FILE)) return SKILL_CONFIG_FILE;
  if (fs.existsSync(REPO_CONFIG_FILE)) return REPO_CONFIG_FILE;
  return SKILL_CONFIG_FILE;
}

function detectHostRole() {
  const normalized = SKILL_DIR.replace(/\\/g, '/');
  if (normalized.includes('/.claude/skills/')) return 'claude';
  if (normalized.includes('/.codex/skills/')) return 'codex';
  return 'unknown';
}

function normalizeBool(value) {
  if (value == null) return null;
  const v = String(value).trim().toLowerCase();
  if (['1', 'true', 'yes', 'y', 'on'].includes(v)) return true;
  if (['0', 'false', 'no', 'n', 'off'].includes(v)) return false;
  return null;
}

function resolveAutoRole(role, hostRole) {
  const roleLc = String(role || '').trim().toLowerCase();
  if (roleLc && roleLc !== 'auto') return roleLc;
  if (hostRole === 'codex') return 'codex';
  if (hostRole === 'claude') return 'claude';
  return 'claude';
}

function parseCouncilConfig(configPath) {
  const fallback = {
    council: {
      chairman: { role: 'auto' },
      members: [
        { name: 'claude', command: 'claude -p', emoji: '🧠', color: 'CYAN' },
        { name: 'codex', command: 'codex exec', emoji: '🤖', color: 'BLUE' },
        { name: 'gemini', command: 'gemini', emoji: '💎', color: 'GREEN' },
      ],
      settings: { exclude_chairman_from_members: true, timeout: 120 },
    },
  };

  if (!fs.existsSync(configPath)) return fallback;

  let YAML;
  try {
    YAML = require('yaml');
  } catch {
    exitWithError(
      [
        'Missing runtime dependency: yaml',
        'Your Agent Council installation is out of date.',
        'Reinstall from your project root:',
        '  npx github:team-attention/agent-council --target auto',
      ].join('\n')
    );
  }

  let parsed;
  try {
    parsed = YAML.parse(fs.readFileSync(configPath, 'utf8'));
  } catch (error) {
    const message = error && error.message ? error.message : String(error);
    exitWithError(`Invalid YAML in ${configPath}: ${message}`);
  }

  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
    exitWithError(`Invalid config in ${configPath}: expected a YAML mapping/object at the document root`);
  }
  if (!parsed.council) {
    exitWithError(`Invalid config in ${configPath}: missing required top-level key 'council:'`);
  }
  if (typeof parsed.council !== 'object' || Array.isArray(parsed.council)) {
    exitWithError(`Invalid config in ${configPath}: 'council' must be a mapping/object`);
  }

  const merged = {
    council: {
      chairman: { ...fallback.council.chairman },
      members: Array.isArray(fallback.council.members) ? [...fallback.council.members] : [],
      settings: { ...fallback.council.settings },
    },
  };

  const council = parsed.council;

  if (council.chairman != null) {
    if (typeof council.chairman !== 'object' || Array.isArray(council.chairman)) {
      exitWithError(`Invalid config in ${configPath}: 'council.chairman' must be a mapping/object`);
    }
    merged.council.chairman = { ...merged.council.chairman, ...council.chairman };
  }

  if (Object.prototype.hasOwnProperty.call(council, 'members')) {
    if (!Array.isArray(council.members)) {
      exitWithError(`Invalid config in ${configPath}: 'council.members' must be a list/array`);
    }
    merged.council.members = council.members;
  }

  if (council.settings != null) {
    if (typeof council.settings !== 'object' || Array.isArray(council.settings)) {
      exitWithError(`Invalid config in ${configPath}: 'council.settings' must be a mapping/object`);
    }
    merged.council.settings = { ...merged.council.settings, ...council.settings };
  }

  return merged;
}

function ensureDir(dirPath) {
  fs.mkdirSync(dirPath, { recursive: true });
}

function safeFileName(name) {
  const cleaned = String(name || '').trim().toLowerCase().replace(/[^a-z0-9_-]+/g, '-');
  return cleaned || 'member';
}

function atomicWriteJson(filePath, payload) {
  const tmpPath = `${filePath}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
  fs.writeFileSync(tmpPath, JSON.stringify(payload, null, 2), 'utf8');
  fs.renameSync(tmpPath, filePath);
}

function readJsonIfExists(filePath) {
  try {
    if (!fs.existsSync(filePath)) return null;
    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
  } catch {
    return null;
  }
}

function sleepMs(ms) {
  const msNum = Number(ms);
  if (!Number.isFinite(msNum) || msNum <= 0) return;
  const sab = new SharedArrayBuffer(4);
  const view = new Int32Array(sab);
  Atomics.wait(view, 0, 0, Math.trunc(msNum));
}

function computeTerminalDoneCount(counts) {
  const c = counts || {};
  return (
    Number(c.done || 0) +
    Number(c.missing_cli || 0) +
    Number(c.error || 0) +
    Number(c.timed_out || 0) +
    Number(c.canceled || 0)
  );
}

function asCodexStepStatus(value) {
  const v = String(value || '');
  if (v === 'pending' || v === 'in_progress' || v === 'completed') return v;
  return 'pending';
}

function buildCouncilUiPayload(statusPayload) {
  const counts = statusPayload.counts || {};
  const done = computeTerminalDoneCount(counts);
  const total = Number(counts.total || 0);
  const isDone = String(statusPayload.overallState || '') === 'done';

  const queued = Number(counts.queued || 0);
  const running = Number(counts.running || 0);

  const members = Array.isArray(statusPayload.members) ? statusPayload.members : [];
  const sortedMembers = members
    .map((m) => ({
      member: m && m.member != null ? String(m.member) : '',
      state: m && m.state != null ? String(m.state) : 'unknown',
      exitCode: m && m.exitCode != null ? m.exitCode : null,
    }))
    .filter((m) => m.member)
    .sort((a, b) => a.member.localeCompare(b.member));

  const terminalStates = new Set(['done', 'missing_cli', 'error', 'timed_out', 'canceled']);
  // Keep the Plan UI visible by ensuring exactly one `in_progress` item while work remains.
  const dispatchStatus = asCodexStepStatus(isDone ? 'completed' : queued > 0 ? 'in_progress' : 'completed');
  let hasInProgress = dispatchStatus === 'in_progress';

  const memberSteps = sortedMembers.map((m) => {
    const state = m.state || 'unknown';
    const isTerminal = terminalStates.has(state);

    let status;
    if (isTerminal) {
      status = 'completed';
    } else if (!hasInProgress && running > 0 && state === 'running') {
      status = 'in_progress';
      hasInProgress = true;
    } else {
      status = 'pending';
    }

    const label = `[Council] Ask ${m.member}`;
    return { label, status: asCodexStepStatus(status) };
  });

  // Once members are done, the host agent should synthesize and then mark this step completed.
  const synthStatus = asCodexStepStatus(isDone ? (hasInProgress ? 'pending' : 'in_progress') : 'pending');

  const codexPlan = [
    { step: `[Council] Prompt dispatch`, status: dispatchStatus },
    ...memberSteps.map((s) => ({ step: s.label, status: s.status })),
    { step: `[Council] Synthesize`, status: synthStatus },
  ];

  const claudeTodos = [
    {
      content: `[Council] Prompt dispatch`,
      status: dispatchStatus,
      activeForm: dispatchStatus === 'completed' ? 'Dispatched council prompts' : 'Dispatching council prompts',
    },
    ...memberSteps.map((s) => ({
      content: s.label,
      status: s.status,
      activeForm: s.status === 'completed' ? 'Finished' : 'Awaiting response',
    })),
    {
      content: `[Council] Synthesize`,
      status: synthStatus,
      activeForm:
        synthStatus === 'completed'
          ? 'Council results ready'
          : synthStatus === 'in_progress'
            ? 'Ready to synthesize'
            : 'Waiting to synthesize',
    },
  ];

  return {
    progress: { done, total, overallState: String(statusPayload.overallState || '') },
    codex: { update_plan: { plan: codexPlan } },
    claude: { todo_write: { todos: claudeTodos } },
  };
}

function computeStatusPayload(jobDir) {
  const resolvedJobDir = path.resolve(jobDir);
  if (!fs.existsSync(resolvedJobDir)) exitWithError(`jobDir not found: ${resolvedJobDir}`);

  const jobMeta = readJsonIfExists(path.join(resolvedJobDir, 'job.json'));
  if (!jobMeta) exitWithError(`job.json not found: ${path.join(resolvedJobDir, 'job.json')}`);

  const membersRoot = path.join(resolvedJobDir, 'members');
  if (!fs.existsSync(membersRoot)) exitWithError(`members folder not found: ${membersRoot}`);

  const members = [];
  for (const entry of fs.readdirSync(membersRoot)) {
    const statusPath = path.join(membersRoot, entry, 'status.json');
    const status = readJsonIfExists(statusPath);
    if (status) members.push({ safeName: entry, ...status });
  }

  const totals = { queued: 0, running: 0, done: 0, error: 0, missing_cli: 0, timed_out: 0, canceled: 0 };
  for (const m of members) {
    const state = String(m.state || 'unknown');
    if (Object.prototype.hasOwnProperty.call(totals, state)) totals[state]++;
  }

  const allDone = totals.running === 0 && totals.queued === 0;
  const overallState = allDone ? 'done' : totals.running > 0 ? 'running' : 'queued';

  return {
    jobDir: resolvedJobDir,
    id: jobMeta.id || null,
    chairmanRole: jobMeta.chairmanRole || null,
    overallState,
    counts: { total: members.length, ...totals },
    members: members
      .map((m) => ({
        member: m.member,
        state: m.state,
        startedAt: m.startedAt || null,
        finishedAt: m.finishedAt || null,
        exitCode: m.exitCode != null ? m.exitCode : null,
        message: m.message || null,
      }))
      .sort((a, b) => String(a.member).localeCompare(String(b.member))),
  };
}

function parseArgs(argv) {
  const args = argv.slice(2);
  const out = { _: [] };
  const booleanFlags = new Set([
    'json',
    'text',
    'checklist',
    'help',
    'h',
    'verbose',
    'include-chairman',
    'exclude-chairman',
  ]);
  for (let i = 0; i < args.length; i++) {
    const a = args[i];
    if (a === '--') {
      out._.push(...args.slice(i + 1));
      break;
    }
    if (!a.startsWith('--')) {
      out._.push(a);
      continue;
    }

    const [key, rawValue] = a.split('=', 2);
    if (rawValue != null) {
      out[key.slice(2)] = rawValue;
      continue;
    }

    const normalizedKey = key.slice(2);
    if (booleanFlags.has(normalizedKey)) {
      out[normalizedKey] = true;
      continue;
    }

    const next = args[i + 1];
    if (next == null || next.startsWith('--')) {
      out[normalizedKey] = true;
      continue;
    }
    out[normalizedKey] = next;
    i++;
  }
  return out;
}

function printHelp() {
  process.stdout.write(`Agent Council (job mode)

Usage:
  council-job.sh start [--config path] [--chairman auto|claude|codex|...] [--jobs-dir path] [--json] "question"
  council-job.sh status [--json|--text|--checklist] [--verbose] <jobDir>
  council-job.sh wait [--cursor CURSOR] [--bucket auto|N] [--interval-ms N] [--timeout-ms N] <jobDir>
  council-job.sh results [--json] <jobDir>
  council-job.sh stop <jobDir>
  council-job.sh clean <jobDir>

Notes:
  - start returns immediately and runs members in parallel via detached Node workers
  - poll status with repeated short calls to update TODO/plan UIs in host agents
  - wait prints JSON by default and blocks until meaningful progress occurs, so you don't spam tool cells
`);
}

function cmdStart(options, prompt) {
  const configPath = options.config || process.env.COUNCIL_CONFIG || resolveDefaultConfigFile();
  const jobsDir =
    options['jobs-dir'] || process.env.COUNCIL_JOBS_DIR || path.join(SKILL_DIR, '.jobs');

  ensureDir(jobsDir);

  const hostRole = detectHostRole();
  const config = parseCouncilConfig(configPath);
  const chairmanRoleRaw = options.chairman || process.env.COUNCIL_CHAIRMAN || config.council.chairman.role || 'auto';
  const chairmanRole = resolveAutoRole(chairmanRoleRaw, hostRole);

  const includeChairman = Boolean(options['include-chairman']);
  const excludeChairmanOverride =
    options['exclude-chairman'] != null ? true : options['include-chairman'] != null ? false : null;

  const excludeSetting = normalizeBool(config.council.settings.exclude_chairman_from_members);
  const excludeChairmanFromMembers =
    excludeChairmanOverride != null ? excludeChairmanOverride : excludeSetting != null ? excludeSetting : true;

  const timeoutSetting = Number(config.council.settings.timeout || 0);
  const timeoutOverride = options.timeout != null ? Number(options.timeout) : null;
  const timeoutSec = Number.isFinite(timeoutOverride) && timeoutOverride > 0 ? timeoutOverride : timeoutSetting > 0 ? timeoutSetting : 0;

  const requestedMembers = config.council.members || [];
  const members = requestedMembers.filter((m) => {
    if (!m || !m.name || !m.command) return false;
    const nameLc = String(m.name).toLowerCase();
    if (excludeChairmanFromMembers && !includeChairman && nameLc === chairmanRole) return false;
    return true;
  });

  const jobId = `${new Date().toISOString().replace(/[:.]/g, '').replace('T', '-').slice(0, 15)}-${crypto
    .randomBytes(3)
    .toString('hex')}`;
  const jobDir = path.join(jobsDir, `council-${jobId}`);
  const membersDir = path.join(jobDir, 'members');
  ensureDir(membersDir);

  fs.writeFileSync(path.join(jobDir, 'prompt.txt'), String(prompt), 'utf8');

  const jobMeta = {
    id: `council-${jobId}`,
    createdAt: new Date().toISOString(),
    configPath,
    hostRole,
    chairmanRole,
    settings: {
      excludeChairmanFromMembers,
      timeoutSec: timeoutSec || null,
    },
    members: members.map((m) => ({
      name: String(m.name),
      command: String(m.command),
      emoji: m.emoji ? String(m.emoji) : null,
      color: m.color ? String(m.color) : null,
    })),
  };
  atomicWriteJson(path.join(jobDir, 'job.json'), jobMeta);

  for (const member of members) {
    const name = String(member.name);
    const safeName = safeFileName(name);
    const memberDir = path.join(membersDir, safeName);
    ensureDir(memberDir);

    atomicWriteJson(path.join(memberDir, 'status.json'), {
      member: name,
      state: 'queued',
      queuedAt: new Date().toISOString(),
      command: String(member.command),
    });

    const workerArgs = [
      WORKER_PATH,
      '--job-dir',
      jobDir,
      '--member',
      name,
      '--safe-member',
      safeName,
      '--command',
      String(member.command),
    ];
    if (timeoutSec && Number.isFinite(timeoutSec) && timeoutSec > 0) {
      workerArgs.push('--timeout', String(timeoutSec));
    }

    const child = spawn(process.execPath, workerArgs, {
      detached: true,
      stdio: 'ignore',
      env: process.env,
    });
    child.unref();
  }

  if (options.json) {
    process.stdout.write(`${JSON.stringify({ jobDir, ...jobMeta }, null, 2)}\n`);
  } else {
    process.stdout.write(`${jobDir}\n`);
  }
}

function cmdStatus(options, jobDir) {
  const payload = computeStatusPayload(jobDir);

  const wantChecklist = Boolean(options.checklist) && !options.json;
  if (wantChecklist) {
    const done = computeTerminalDoneCount(payload.counts);
    const headerId = payload.id ? ` (${payload.id})` : '';
    process.stdout.write(`Agent Council${headerId}\n`);
    process.stdout.write(
      `Progress: ${done}/${payload.counts.total} done  (running ${payload.counts.running}, queued ${payload.counts.queued})\n`
    );
    for (const m of payload.members) {
      const state = String(m.state || '');
      const mark =
        state === 'done'
          ? '[x]'
          : state === 'running' || state === 'queued'
            ? '[ ]'
            : state
              ? '[!]'
              : '[ ]';
      const exitInfo = m.exitCode != null ? ` (exit ${m.exitCode})` : '';
      process.stdout.write(`${mark} ${m.member} — ${state}${exitInfo}\n`);
    }
    return;
  }

  const wantText = Boolean(options.text) && !options.json;
  if (wantText) {
    const done = computeTerminalDoneCount(payload.counts);
    process.stdout.write(`members ${done}/${payload.counts.total} done; running=${payload.counts.running} queued=${payload.counts.queued}\n`);
    if (options.verbose) {
      for (const m of payload.members) {
        process.stdout.write(`- ${m.member}: ${m.state}${m.exitCode != null ? ` (exit ${m.exitCode})` : ''}\n`);
      }
    }
    return;
  }

  process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
}

function parseWaitCursor(value) {
  const raw = String(value || '').trim();
  if (!raw) return null;
  const parts = raw.split(':');
  const version = parts[0];
  if (version === 'v1' && parts.length === 4) {
    const bucketSize = Number(parts[1]);
    const doneBucket = Number(parts[2]);
    const isDone = parts[3] === '1';
    if (!Number.isFinite(bucketSize) || bucketSize <= 0) return null;
    if (!Number.isFinite(doneBucket) || doneBucket < 0) return null;
    return { version, bucketSize, dispatchBucket: 0, doneBucket, isDone };
  }
  if (version === 'v2' && parts.length === 5) {
    const bucketSize = Number(parts[1]);
    const dispatchBucket = Number(parts[2]);
    const doneBucket = Number(parts[3]);
    const isDone = parts[4] === '1';
    if (!Number.isFinite(bucketSize) || bucketSize <= 0) return null;
    if (!Number.isFinite(dispatchBucket) || dispatchBucket < 0) return null;
    if (!Number.isFinite(doneBucket) || doneBucket < 0) return null;
    return { version, bucketSize, dispatchBucket, doneBucket, isDone };
  }
  return null;
}

function formatWaitCursor(bucketSize, dispatchBucket, doneBucket, isDone) {
  return `v2:${bucketSize}:${dispatchBucket}:${doneBucket}:${isDone ? 1 : 0}`;
}

function asWaitPayload(statusPayload) {
  const members = Array.isArray(statusPayload.members) ? statusPayload.members : [];
  return {
    jobDir: statusPayload.jobDir,
    id: statusPayload.id,
    chairmanRole: statusPayload.chairmanRole,
    overallState: statusPayload.overallState,
    counts: statusPayload.counts,
    members: members.map((m) => ({
      member: m.member,
      state: m.state,
      exitCode: m.exitCode != null ? m.exitCode : null,
      message: m.message || null,
    })),
    ui: buildCouncilUiPayload(statusPayload),
  };
}

function resolveBucketSize(options, total, prevCursor) {
  const raw = options.bucket != null ? options.bucket : options['bucket-size'];

  if (raw == null || raw === true) {
    if (prevCursor && prevCursor.bucketSize) return prevCursor.bucketSize;
  } else {
    const asString = String(raw).trim().toLowerCase();
    if (asString !== 'auto') {
      const num = Number(asString);
      if (!Number.isFinite(num) || num <= 0) exitWithError(`wait: invalid --bucket: ${raw}`);
      return Math.trunc(num);
    }
  }

  // Auto-bucket: target ~5 updates total.
  const totalNum = Number(total || 0);
  if (!Number.isFinite(totalNum) || totalNum <= 0) return 1;
  return Math.max(1, Math.ceil(totalNum / 5));
}

function cmdWait(options, jobDir) {
  const resolvedJobDir = path.resolve(jobDir);
  const cursorFilePath = path.join(resolvedJobDir, '.wait_cursor');
  const prevCursorRaw =
    options.cursor != null
      ? String(options.cursor)
      : fs.existsSync(cursorFilePath)
        ? String(fs.readFileSync(cursorFilePath, 'utf8')).trim()
        : '';
  const prevCursor = parseWaitCursor(prevCursorRaw);

  const intervalMsRaw = options['interval-ms'] != null ? options['interval-ms'] : 250;
  const intervalMs = Math.max(50, Math.trunc(Number(intervalMsRaw)));
  if (!Number.isFinite(intervalMs) || intervalMs <= 0) exitWithError(`wait: invalid --interval-ms: ${intervalMsRaw}`);

  const timeoutMsRaw = options['timeout-ms'] != null ? options['timeout-ms'] : 0;
  const timeoutMs = Math.trunc(Number(timeoutMsRaw));
  if (!Number.isFinite(timeoutMs) || timeoutMs < 0) exitWithError(`wait: invalid --timeout-ms: ${timeoutMsRaw}`);

  // Always read once to decide bucket sizing and (when no cursor is given) return immediately.
  let payload = computeStatusPayload(jobDir);
  const bucketSize = resolveBucketSize(options, payload.counts.total, prevCursor);

  const doneCount = computeTerminalDoneCount(payload.counts);
  const isDone = payload.overallState === 'done';
  const total = Number(payload.counts.total || 0);
  const queued = Number(payload.counts.queued || 0);
  const dispatchBucket = queued === 0 && total > 0 ? 1 : 0;
  const doneBucket = Math.floor(doneCount / bucketSize);
  const cursor = formatWaitCursor(bucketSize, dispatchBucket, doneBucket, isDone);

  if (!prevCursor) {
    fs.writeFileSync(cursorFilePath, cursor, 'utf8');
    process.stdout.write(`${JSON.stringify({ ...asWaitPayload(payload), cursor }, null, 2)}\n`);
    return;
  }

  const start = Date.now();
  while (cursor === prevCursorRaw) {
    if (timeoutMs > 0 && Date.now() - start >= timeoutMs) break;
    sleepMs(intervalMs);
    payload = computeStatusPayload(jobDir);
    const d = computeTerminalDoneCount(payload.counts);
    const doneFlag = payload.overallState === 'done';
    const totalCount = Number(payload.counts.total || 0);
    const queuedCount = Number(payload.counts.queued || 0);
    const dispatchB = queuedCount === 0 && totalCount > 0 ? 1 : 0;
    const doneB = Math.floor(d / bucketSize);
    const nextCursor = formatWaitCursor(bucketSize, dispatchB, doneB, doneFlag);
    if (nextCursor !== prevCursorRaw) {
      fs.writeFileSync(cursorFilePath, nextCursor, 'utf8');
      process.stdout.write(`${JSON.stringify({ ...asWaitPayload(payload), cursor: nextCursor }, null, 2)}\n`);
      return;
    }
  }

  // Timeout: return current state (cursor may be unchanged).
  const finalPayload = computeStatusPayload(jobDir);
  const finalDone = computeTerminalDoneCount(finalPayload.counts);
  const finalDoneFlag = finalPayload.overallState === 'done';
  const finalTotal = Number(finalPayload.counts.total || 0);
  const finalQueued = Number(finalPayload.counts.queued || 0);
  const finalDispatchBucket = finalQueued === 0 && finalTotal > 0 ? 1 : 0;
  const finalDoneBucket = Math.floor(finalDone / bucketSize);
  const finalCursor = formatWaitCursor(bucketSize, finalDispatchBucket, finalDoneBucket, finalDoneFlag);
  fs.writeFileSync(cursorFilePath, finalCursor, 'utf8');
  process.stdout.write(`${JSON.stringify({ ...asWaitPayload(finalPayload), cursor: finalCursor }, null, 2)}\n`);
}

function cmdResults(options, jobDir) {
  const resolvedJobDir = path.resolve(jobDir);
  const jobMeta = readJsonIfExists(path.join(resolvedJobDir, 'job.json'));
  const membersRoot = path.join(resolvedJobDir, 'members');

  const members = [];
  if (fs.existsSync(membersRoot)) {
    for (const entry of fs.readdirSync(membersRoot)) {
      const statusPath = path.join(membersRoot, entry, 'status.json');
      const outputPath = path.join(membersRoot, entry, 'output.txt');
      const errorPath = path.join(membersRoot, entry, 'error.txt');
      const status = readJsonIfExists(statusPath);
      if (!status) continue;
      const output = fs.existsSync(outputPath) ? fs.readFileSync(outputPath, 'utf8') : '';
      const stderr = fs.existsSync(errorPath) ? fs.readFileSync(errorPath, 'utf8') : '';
      members.push({ safeName: entry, ...status, output, stderr });
    }
  }

  if (options.json) {
    process.stdout.write(
      `${JSON.stringify(
        {
          jobDir: resolvedJobDir,
          id: jobMeta ? jobMeta.id : null,
          prompt: fs.existsSync(path.join(resolvedJobDir, 'prompt.txt'))
            ? fs.readFileSync(path.join(resolvedJobDir, 'prompt.txt'), 'utf8')
            : null,
          members: members
            .map((m) => ({
              member: m.member,
              state: m.state,
              exitCode: m.exitCode != null ? m.exitCode : null,
              message: m.message || null,
              output: m.output,
              stderr: m.stderr,
            }))
            .sort((a, b) => String(a.member).localeCompare(String(b.member))),
        },
        null,
        2
      )}\n`
    );
    return;
  }

  for (const m of members.sort((a, b) => String(a.member).localeCompare(String(b.member)))) {
    process.stdout.write(`\n=== ${m.member} (${m.state}) ===\n`);
    if (m.message) process.stdout.write(`${m.message}\n`);
    process.stdout.write(m.output || '');
    if (!m.output && m.stderr) {
      process.stdout.write('\n');
      process.stdout.write(m.stderr);
    }
    process.stdout.write('\n');
  }
}

function cmdStop(_options, jobDir) {
  const resolvedJobDir = path.resolve(jobDir);
  const membersRoot = path.join(resolvedJobDir, 'members');
  if (!fs.existsSync(membersRoot)) exitWithError(`No members folder found: ${membersRoot}`);

  let stoppedAny = false;
  for (const entry of fs.readdirSync(membersRoot)) {
    const statusPath = path.join(membersRoot, entry, 'status.json');
    const status = readJsonIfExists(statusPath);
    if (!status) continue;
    if (status.state !== 'running') continue;
    if (!status.pid) continue;

    try {
      process.kill(Number(status.pid), 'SIGTERM');
      stoppedAny = true;
    } catch {
      // ignore
    }
  }

  process.stdout.write(stoppedAny ? 'stop: sent SIGTERM to running members\n' : 'stop: no running members\n');
}

function cmdClean(_options, jobDir) {
  const resolvedJobDir = path.resolve(jobDir);
  fs.rmSync(resolvedJobDir, { recursive: true, force: true });
  process.stdout.write(`cleaned: ${resolvedJobDir}\n`);
}

function main() {
  const options = parseArgs(process.argv);
  const [command, ...rest] = options._;

  if (!command || options.help || options.h) {
    printHelp();
    return;
  }

  if (command === 'start') {
    const prompt = rest.join(' ').trim();
    if (!prompt) exitWithError('start: missing prompt');
    cmdStart(options, prompt);
    return;
  }
  if (command === 'status') {
    const jobDir = rest[0];
    if (!jobDir) exitWithError('status: missing jobDir');
    cmdStatus(options, jobDir);
    return;
  }
  if (command === 'wait') {
    const jobDir = rest[0];
    if (!jobDir) exitWithError('wait: missing jobDir');
    cmdWait(options, jobDir);
    return;
  }
  if (command === 'results') {
    const jobDir = rest[0];
    if (!jobDir) exitWithError('results: missing jobDir');
    cmdResults(options, jobDir);
    return;
  }
  if (command === 'stop') {
    const jobDir = rest[0];
    if (!jobDir) exitWithError('stop: missing jobDir');
    cmdStop(options, jobDir);
    return;
  }
  if (command === 'clean') {
    const jobDir = rest[0];
    if (!jobDir) exitWithError('clean: missing jobDir');
    cmdClean(options, jobDir);
    return;
  }

  exitWithError(`Unknown command: ${command}`);
}

if (require.main === module) {
  main();
}


================================================
FILE: plugins/agent-council/skills/agent-council/scripts/council-job.sh
================================================
#!/bin/bash

set -e

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

if ! command -v node >/dev/null 2>&1; then
  echo "Error: Node.js is required to run Agent Council job mode." >&2
  echo "Install Node.js and try again (plugin installs cannot bundle Node)." >&2
  echo "" >&2
  echo "macOS (Homebrew): brew install node" >&2
  echo "Or download from: https://nodejs.org/" >&2
  exit 127
fi

exec node "$SCRIPT_DIR/council-job.js" "$@"


================================================
FILE: plugins/agent-council/skills/agent-council/scripts/council.sh
================================================
#!/bin/bash
#
# Agent Council (job mode default)
#
# Subcommands:
#   council.sh start [options] "question"     # returns JOB_DIR immediately
#   council.sh status [--json|--text|--checklist] JOB_DIR # poll progress
#   council.sh wait [--cursor CURSOR] [--bucket auto|N] [--interval-ms N] [--timeout-ms N] JOB_DIR
#   council.sh results [--json] JOB_DIR       # print collected outputs
#   council.sh stop JOB_DIR                   # best-effort stop running members
#   council.sh clean JOB_DIR                  # remove job directory
#
# One-shot:
#   council.sh "question"
#   (in a real terminal: starts a job, waits for completion, prints results, cleans up)
#   (in host-agent tool UIs: returns a single `wait` JSON payload immediately; host drives progress + results)
#

set -e

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
JOB_SCRIPT="$SCRIPT_DIR/council-job.sh"

usage() {
  cat <<EOF
Agent Council

Default mode is job-based parallel execution (pollable).

Usage:
  $(basename "$0") start [options] "question"
  $(basename "$0") status [--json|--text|--checklist] <jobDir>
  $(basename "$0") wait [--cursor CURSOR] [--bucket auto|N] [--interval-ms N] [--timeout-ms N] <jobDir>
  $(basename "$0") results [--json] <jobDir>
  $(basename "$0") stop <jobDir>
  $(basename "$0") clean <jobDir>

One-shot:
  $(basename "$0") "question"
EOF
}

if [ $# -eq 0 ]; then
  usage
  exit 1
fi

case "$1" in
  -h|--help|help)
    usage
    exit 0
    ;;
esac

if ! command -v node >/dev/null 2>&1; then
  echo "Error: Node.js is required to run Agent Council." >&2
  echo "Claude Code plugins cannot bundle or auto-install Node." >&2
  echo "" >&2
  echo "macOS (Homebrew): brew install node" >&2
  echo "Or download from: https://nodejs.org/" >&2
  exit 127
fi

case "$1" in
  start|status|wait|results|stop|clean)
    exec "$JOB_SCRIPT" "$@"
    ;;
esac

in_host_agent_context() {
  if [ -n "${CODEX_CACHE_FILE:-}" ]; then
    return 0
  fi

  case "$SCRIPT_DIR" in
    */.codex/skills/*|*/.claude/skills/*)
      # Tool-call environments typically do not provide a real TTY on stdout/stderr.
      if [ ! -t 1 ] && [ ! -t 2 ]; then
        return 0
      fi
      ;;
  esac

  return 1
}

JOB_DIR="$("$JOB_SCRIPT" start "$@")"

# Host agents (Codex CLI / Claude Code) cannot update native TODO/plan UIs while a long-running
# command is executing. If we're in a host agent context, return immediately with a single `wait`
# JSON payload (includes `.ui.codex.update_plan.plan` / `.ui.claude.todo_write.todos`) and let the
# host agent drive progress updates with repeated short `wait` calls + native UI updates.
if in_host_agent_context; then
  exec "$JOB_SCRIPT" wait "$JOB_DIR"
fi

echo "council: started ${JOB_DIR}" >&2

cleanup_on_signal() {
  if [ -n "${JOB_DIR:-}" ] && [ -d "$JOB_DIR" ]; then
    "$JOB_SCRIPT" stop "$JOB_DIR" >/dev/null 2>&1 || true
    "$JOB_SCRIPT" clean "$JOB_DIR" >/dev/null 2>&1 || true
  fi
  exit 130
}

trap cleanup_on_signal INT TERM

while true; do
  WAIT_JSON="$("$JOB_SCRIPT" wait "$JOB_DIR")"
  OVERALL="$(printf '%s' "$WAIT_JSON" | node -e '
const fs=require("fs");
const d=JSON.parse(fs.readFileSync(0,"utf8"));
process.stdout.write(String(d.overallState||""));
')"

  "$JOB_SCRIPT" status --text "$JOB_DIR" >&2

  if [ "$OVERALL" = "done" ]; then
    break
  fi
done

trap - INT TERM

"$JOB_SCRIPT" results "$JOB_DIR"
"$JOB_SCRIPT" clean "$JOB_DIR" >/dev/null


================================================
FILE: plugins/clarify/.claude-plugin/plugin.json
================================================
{
  "name": "clarify",
  "version": "2.0.0",
  "description": "Three lenses for clarity: vague requirements → specs (vague), strategy blind spots → 4-quadrant playbook (unknown), content vs form → leverage shift (metamedium)",
  "author": {
    "name": "Team Attention",
    "url": "https://github.com/team-attention"
  },
  "repository": "https://github.com/team-attention/plugins-for-claude-natives",
  "license": "MIT",
  "keywords": ["claude-code", "plugin", "requirements", "clarification", "known-unknown", "strategy", "metamedium", "content-form"]
}


================================================
FILE: plugins/clarify/skills/metamedium/SKILL.md
================================================
---
name: metamedium
description: This skill should be used when the user is building, planning, or strategizing and the key question is whether to optimize content (what) or change form (how/medium). Trigger on "내용 vs 형식", "content vs form", "metamedium", "형식을 바꿔볼까", "새로운 포맷", "관점 전환", "perspective shift", "다른 방법 없을까", "같은 방식이 안 먹혀", "diminishing returns". Applies Alan Kay's metamedium concept to surface form-level alternatives. For requirement clarification use vague; for strategy blind spots use unknown.
---

# Metamedium: Content vs Form Lens

Distinguish **content** (what is being said/built) from **form** (the medium/structure it's delivered through) to surface whether the real leverage is in optimizing content or inventing a new form. Based on Alan Kay's metamedium concept.

> "A change of perspective is worth 80 IQ points." — Alan Kay

## Core Concept

Most people only change **content** — what they say, write, or build. The real leverage comes from changing **form** — the medium, format, or structure itself.

| | Content (what) | Form (how/medium) |
|--|----------------|-------------------|
| Example | Writing a LinkedIn post | Building a tool that generates posts from client work |
| Example | Writing unit tests manually | Building a test generator from type signatures |
| Example | Giving a workshop | Inventing a format where attendees co-create artifacts |
| Leverage | Linear — each piece is one output | Exponential — each new form enables infinite content |

## When to Use

- Planning a project and unsure whether to optimize the output or the process
- Stuck optimizing content with diminishing returns
- Building something and want to check if form-level change would yield more leverage
- Evaluating whether "more of the same" or "something structurally different" is the right move

For requirement clarification, use the **vague** skill. For strategy blind spot analysis, use the **unknown** skill.

## Protocol

**ALWAYS use the AskUserQuestion tool** for the fork question in Phase 2 — never ask content/form choices in plain text.

### Phase 1: Identify and Label

Read the user's current work, plan, or task. Classify each component as content or form:

```
[CONTENT] Writing a blog post about AI consulting
[FORM]    Building a pipeline that turns consulting retros into blog posts
[CONTENT] Deploying a new API endpoint
[FORM]    Building a codegen that auto-generates endpoints from schemas
[CONTENT] Fixing a flaky test
[FORM]    Building a test infrastructure that prevents flaky tests by design
```

Present the labeling to the user as a brief diagnosis.

### Phase 2: Surface the Fork

Use AskUserQuestion to present the content/form choice:

```
questions:
  - question: "This is currently [CONTENT/FORM]-level work. Where should effort go?"
    header: "Level"
    options:
      - label: "Proceed with content"
        description: "Optimize within the current form — faster, lower risk"
      - label: "Explore form change"
        description: "What if the medium/structure itself changed? Higher leverage"
      - label: "Content now, note form"
        description: "Do the content work, but flag the form opportunity for later"
    multiSelect: false
```

### Phase 3: Branch

**If "Proceed with content"**: Acknowledge and proceed. Include a `Form Opportunity` note in the output for future reference.

**If "Explore form change"**: Generate 2-3 form alternatives. For each alternative:
- What the new form looks like concretely
- What new properties it would have (automatic, repeatable, scalable, composable)
- Minimum viable version to test the form

**If "Content now, note form"**: Proceed with content work. Append the form opportunity to the output.

### Output

Append to any deliverable or present standalone:

```markdown
## Content/Form Analysis

**Current work**: [description]
**Classification**: [CONTENT / FORM]

### Form Opportunity
| | Detail |
|---|--------|
| **Alternative form** | [what it would look like] |
| **New properties** | [what it enables that current form doesn't] |
| **Minimum test** | [smallest version to validate] |
| **Status** | [exploring / noted for later / not applicable] |
```

## The Metamedium Question

When stuck or when optimizing yields diminishing returns:

> **"What new form/medium could make this problem disappear?"**

Examples:
- Stuck writing more posts? → A format that turns client work into posts automatically
- Test coverage plateauing? → A tool that generates tests from type signatures
- Onboarding too slow? → A self-guided format where the codebase teaches itself

## Tetris Test

> Change the blocks. Then you realize the original blocks were mathematically calculated.

To truly understand a form, try to change it. The constraints discovered ARE the form's intelligence. Perspective shifts happen not by thinking harder, but by touching the form itself.

## Anti-Patterns

- Treating all work as content optimization when form change is available
- Building "better content" when the form is the bottleneck
- Assuming the current medium/format is fixed and only content can vary
- Confusing incremental content improvement with form invention

## Rules

1. **Always label**: Tag work as content or form
2. **Content is fine**: Not everything needs form change — but always note the option
3. **Form yields power**: New form = new medium = exponential leverage
4. **Code is metamedium**: The ability to code means the ability to change form
5. **Touch to understand**: Change the form to discover why it was designed that way

## Additional Resources

For Alan Kay's original ideas and source quotes, see `references/alan-kay-quotes.md`.


================================================
FILE: plugins/clarify/skills/metamedium/references/alan-kay-quotes.md
================================================
# Alan Kay: Source Quotes and Context

Key quotes and context that inform the metamedium lens.

## "A change of perspective is worth 80 IQ points"

**Origin**: July 1982, lecture to the Apple Macintosh team. Recorded by Andy Hertzfeld.

**Context**: The Dynabook team at Xerox PARC sought truly innovative approaches to computing. Kay believed having a new way of seeing a problem is the most effective way of moving to a solution — more effective than raw intelligence applied to the same perspective.

**Application**: When stuck, don't think harder. Change the frame. The content/form distinction IS such a frame change.

## "The best way to predict the future is to invent it"

**Origin**: 1971, Xerox PARC.

**Context**: At PARC, the researchers' maxim encouraged a proactive approach — rather than predicting what might happen based on current trends, create new technologies that define future possibilities.

**Application**: Don't optimize content within existing forms. Invent new forms.

## "The computer is the first metamedium"

**Origin**: 1977, "Personal Dynamic Media" paper by Alan Kay and Adele Goldberg.

**Full quote**: "The computer is the first metamedium, and as such it has degrees of freedom for representation and expression never before encountered and as yet barely investigated."

**Context**: Kay realized computers could simulate ALL existing media (text, images, music, film) AND create entirely new media that had never existed before. This is what he called "metamedium" — a medium that contains and generates other media.

**Application**: Coding doesn't just let you create content faster. It lets you invent new kinds of media. This is qualitatively different from any previous tool.

## On Literacy

**Quote**: "The ability to 'read' a medium means you can access materials and tools generated by others. The ability to 'write' in a medium means you can generate materials and tools for others. You must have both to be literate."

**Application**: True computer literacy is not using apps (reading). It's creating new forms of expression and tools for others (writing). Most "AI literacy" today is reading-level only (using ChatGPT). Form-level literacy means building new AI-powered formats.

## On New Representations

**Quote**: "These new media use already existing representational formats as their building blocks, while adding many new previously nonexistent properties."

**Application**: The most powerful innovations don't replace existing forms — they use them as building blocks to create something with properties that didn't exist before. Example: A tool that combines consulting retros + AI + LinkedIn into an automatic content pipeline isn't just "better content." It's a new form with properties (automatic, repeatable, scalable) that the individual components didn't have.

## Sources

- [Quote Investigator: Point of View](https://quoteinvestigator.com/2018/05/29/pov/)
- [Quote Investigator: Invent the Future](https://quoteinvestigator.com/2012/09/27/invent-the-future/)
- [Personal Dynamic Media (1977 paper)](https://www.newmediareader.com/book_samples/nmr-26-kay.pdf)
- [Alan Kay's Universal Media Machine - Lev Manovich](https://manovich.net/content/04-projects/055-alan-kay-s-universal-media-machine/51_article_2006.pdf)
- [Alan Kay - ACM Turing Award](https://amturing.acm.org/award_winners/kay_3972189.cfm)
- [Computer as Metamedium](https://blogs.commons.georgetown.edu/cctp-711-fall2017/2017/11/09/computer-as-metamedium/)


================================================
FILE: plugins/clarify/skills/unknown/SKILL.md
================================================
---
name: unknown
description: This skill should be used when the user provides a strategy, plan, or decision document and wants to surface hidden assumptions and blind spots using the Known/Unknown 4-quadrant framework. Trigger on "known unknown", "4분면 분석", "blind spots", "뭘 놓치고 있지", "뭘 모르는지 모르겠어", "전략 점검", "전략 분석", "assumption check", "가정 점검", "quadrant analysis", "what am I missing". Strategy-level blind spot analysis with hypothesis-driven questioning. For requirement clarification use vague; for content-vs-form reframing use metamedium.
---

# Unknown: Surface Blind Spots with Known/Unknown Quadrants

Surface hidden assumptions and blind spots in any strategy, plan, or decision using the Known/Unknown quadrant framework and hypothesis-driven questioning.

## When to Use

- Strategy or planning documents that need scrutiny
- Decisions with unclear direction or hidden assumptions
- Any situation where "what we don't know" matters more than "what we do know"

For specific requirement clarification (feature requests, bug reports), use the **vague** skill. For content-vs-form reframing (optimizing within a form vs inventing a new form), use the **metamedium** skill.

## Core Principle: Hypothesis-as-Options

**ALWAYS use the AskUserQuestion tool** for every question in R1/R2/R3 — never ask questions in plain text. The structured format enforces hypothesis-as-options and limits choice fatigue.

Present hypotheses as options instead of open questions. The hypotheses ARE the analysis — by designing good options, 80% of the analytical work is done before the user even answers. The user's job is to confirm, correct, or surprise.

```
BAD:  "Why can't you do video content?"           ← open question, high load
GOOD: "Time / Skill gap / No guests / High bar"   ← pick one or more
```

- Each option IS a testable hypothesis about the user's situation
- Use multiSelect: true to catch compound causes
- "Other" is always available for out-of-frame answers

## 3-Round Depth Pattern

| Round | Purpose | Questions | Key trait |
|-------|---------|-----------|-----------|
| R1 | Validate draft quadrant | 3-4 | Broad, covers all quadrants |
| R2 | Drill into weak spots | 2-3 | Targeted, follows R1 answers |
| R3 | Nail execution details | 2-3 | Specific, optional |

**Critical**: Generate Round N questions from Round N-1 answers. Never use pre-prepared questions across rounds. Cap total at 7-10 questions.

## Protocol

### Phase 1: Intake

**File provided**: Read and extract goals, components, implicit assumptions, missing elements.

**Topic keyword only**: Start directly with R1 questions to establish scope. The draft in Phase 3 will be rougher but R1 corrects it.

### Phase 2: Context

Gather related context to find Unknown Knowns — assets the user may not realize they have:

- **Glob** for related files: CLAUDE.md, README, decision records, past analyses in the project
- **Read** project context: recent goals, team structure, active initiatives
- **Identify** underutilized assets: existing tools/skills not in use, past projects with reusable patterns, team expertise not leveraged

Items discovered here become UK candidates and options in R1 questions.

### Phase 3: Draft + R1 Questions

Generate an initial 4-quadrant classification. **The draft is intentionally rough** — R1 exists to correct it, not confirm it. Err on the side of classifying uncertain items as KU rather than KK.

Design R1 questions to test quadrant boundaries. **Batch all R1 questions into a single AskUserQuestion call** (max 4 questions):

| Target | Pattern | Example |
|--------|---------|---------|
| KK | "Is this really certain?" | "Primary revenue source?" (options) |
| KU | "Where's the weakest link?" | "Which flywheel connection is weakest?" |
| UK | "What exists but isn't used?" | Based on context findings |
| UU | "What's the biggest fear?" | Risk scenarios as options |

### Phase 4: Deepen + R2 Questions

Analyze R1 answers. Find the most uncertain area and drill in.

**R2 triggers**: compound answers (messy area), unexpected answers (draft wrong), "Other" selected (outside frame).

For detailed R2 question types, see `references/question-design.md`.

### Phase 5: Execute + R3 Questions (Optional)

After priorities are set, nail down execution details for top items. Skip if R2 already provides enough detail.

### Phase 6: Playbook Output

Generate a structured 4-quadrant playbook file. For the complete output template, see `references/playbook-template.md`.

**Output structure:**
```
# {Topic}: Known/Unknown Quadrant Analysis

## Current State Diagnosis
## Quadrant Matrix (ASCII with resource %)
## 1. Known Knowns: Systematize (60%)
## 2. Known Unknowns: Design Experiments (25%)
   - Each KU: Diagnosis → Experiment → Success Criteria → Deadline → Promotion Condition
## 3. Unknown Knowns: Leverage (10%)
## 4. Unknown Unknowns: Set Up Antennas (5%)
## Strategic Decision: What to Stop
## Execution Roadmap (week-by-week)
## Core Principles (3-5 decision criteria)
```

**Resource percentages (60/25/10/5) are defaults.** Adjust based on context — e.g., a startup exploring product-market fit may allocate 40% KU and 30% KK.

## Anti-Patterns

- Open questions ("What would you like to do?") — use hypothesis options
- 5+ options per question — causes choice fatigue
- Ignoring R1 answers when designing R2 — performative questioning
- Equal depth on all quadrants — wastes time, loses focus
- No "stop doing" section — adding without subtracting

## Example

**Input**: Growth strategy document

**R1**: Revenue source? → Workshops. Weakest link? → Biz→Knowledge. Blocker? → Skill gap + high bar (multiSelect). Biggest fear? → Execution scattered.

**R2** (driven by "execution scattered"): What to drop? → Product dev. Why no knowledge→content? → No process + no time + hard to abstract. Role clarity? → Unclear.

**R3**: Video format? → Screen recording. Retro blocker? → Don't know what to capture. What content resonated? → Raw discoveries.

**Key discovery**: Abstraction isn't needed — raw insights work better. Collapsed triple bottleneck into 15-minute pipeline.

## Rules

1. **Hypotheses, not questions**: Every option is a testable hypothesis
2. **Answers drive depth**: R2 from R1, R3 from R2
3. **7-10 questions max**: Beyond this is fatigue
4. **Stop > Start**: Always include "what to stop doing"
5. **Promote or kill**: Every KU gets a promotion condition and a kill condition
6. **Raw > Perfect**: Encourage minimum viable experiments, not perfect plans
7. **Draft is disposable**: The initial quadrant is meant to be corrected

## Additional Resources

### Reference Files

- **`references/question-design.md`** — Detailed question types for each round, trigger conditions, and AskUserQuestion formatting guide
- **`references/playbook-template.md`** — Complete output template with section-by-section guide


================================================
FILE: plugins/clarify/skills/unknown/references/playbook-template.md
================================================
# Playbook Output Template

Complete template for the 4-quadrant playbook generated in Phase 6.

## File Naming

Save as: `{topic}-known-unknown.md` in a location appropriate to the project.

## Template

```markdown
# {Topic}: Known/Unknown Quadrant Analysis

> Based on {source document or conversation}.
> Designed under the constraint that "{key constraint from R1/R2}".

---

## Current State Diagnosis

- **{Finding 1}**: {confirmed fact from R1-R3}
- **{Finding 2}**: {confirmed fact}
- **What to stop doing**: {items user chose to cut}

---

## Quadrant Matrix

```
                    Known                          Unknown
         +---------------------------+---------------------------+
         |                           |                           |
         |   KK: Systematize         |   KU: Design Experiments  |
 Known   |   Resources: 60%          |   Resources: 25%          |
         |                           |                           |
         +---------------------------+---------------------------+
         |                           |                           |
         |   UK: Leverage            |   UU: Set Up Antennas     |
 Unknown |   Resources: 10%          |   Resources: 5%           |
         |                           |                           |
         +---------------------------+---------------------------+
```

---

## 1. Known Knowns: Systematize (60%)

> Confirmed working items. Turn into repeatable systems.

| # | Item | Evidence | Systemization Target |
|---|------|----------|---------------------|
| 1 | **{item}** | {how we know} | {what "systemized" looks like} |

---

## 2. Known Unknowns: Design Experiments (25%)

> Questions with no answer yet. Each gets an experiment.

### KU{N}. {Question}

**Diagnosis**: Why is this unknown?
- {root cause from R2}

**Experiment**:
| Item | Detail |
|------|--------|
| Format | {what to try} |
| Success criteria | {measurable outcome} |
| Deadline | {specific date} |
| Effort | {time/resource estimate} |

**Promotion condition**: {when this becomes a Known Known}
**Kill condition**: {when to abandon this and try something else}

*(Repeat for each prioritized KU)*

---

## 3. Unknown Knowns: Leverage (10%)

> Assets already owned but not utilized. Fastest wins.

| # | Hidden Asset | How to Use | Effort |
|---|-------------|-----------|--------|
| 1 | **{asset}** | {activation method} | Low/Med/High |

---

## 4. Unknown Unknowns: Set Up Antennas (5%)

> Cannot predict. Manage with detection speed + response speed.

| # | Risk/Opportunity | Detection Method | Response Principle |
|---|-----------------|-----------------|-------------------|
| 1 | **{scenario}** | {how to notice early} | {what to do} |

---

## Strategic Decision: What to Stop

| Item | Reason | Restart Condition |
|------|--------|------------------|
| **{item}** | {why stop} | {what would make it worth resuming} |

---

## Execution Roadmap

### Week 1-2
- [ ] {action item}
- [ ] {action item}

### Week 3-4
- [ ] {action item}

### Month 2
- [ ] {action item}
- [ ] Review: promote KUs to KK or kill

---

## Core Principles

1. **{Principle}**: {one-line explanation}
2. **{Principle}**: {one-line explanation}
3. **{Principle}**: {one-line explanation}
```

## Section Writing Guide

### Current State Diagnosis
Summarize only what was confirmed through R1-R3 questioning. Avoid restating the input document — focus on what the conversation revealed that wasn't obvious before.

### Known Knowns
Only include items with clear evidence. If the user said "I think so" without data, it's a KU not a KK.

### Known Unknowns
The most important section. Each KU must have:
- A root cause (why unknown)
- A minimum viable experiment (not a perfect plan)
- A measurable success criteria
- A promotion AND kill condition

### Unknown Knowns
Look for these in:
- Context files the user hasn't referenced
- Tools/skills already built but not used
- Past projects with reusable patterns
- Team members' unused expertise

### Unknown Unknowns
Keep this section short. The point is awareness, not prevention.
Focus on detection speed (how to notice early) and response capacity (having buffer time).

### What to Stop
This section is non-negotiable. Every analysis must include at least one item to stop or pause. Adding without subtracting is the most common failure mode.

### Core Principles
Derive from the conversation, not generic advice. Each principle should be a decision rule that resolves a specific tension discovered during questioning.


================================================
FILE: plugins/clarify/skills/unknown/references/question-design.md
================================================
# Question Design Guide

Detailed patterns for designing hypothesis-driven questions across the 3-round depth pattern.

## AskUserQuestion Formatting

```
question: "Clear, specific question ending with ?"
header: "Short label (max 12 chars)"
options:
  - label: "Option A"
    description: "Why this matters or what it implies"
  - label: "Option B"
    description: "Why this matters or what it implies"
multiSelect: true  # when compound causes are likely
```

**Rules:**
- 3-4 options per question (never 5+)
- description explains implications, not just restates label
- multiSelect for cause/blocker questions, single for priority/choice questions

## R1 Questions: Validate the Draft

Design one question per quadrant boundary. Goal: confirm or correct the initial classification.

| Quadrant | Question Pattern | Example |
|----------|-----------------|---------|
| **KK** | "What's the confirmed reality?" | "Current revenue source?" with options per hypothesis |
| **KU** | "Where's the weakest link?" | "Which connection in your process is weakest?" |
| **UK** | "What assets exist but aren't used?" | "Which of these do you have but don't leverage?" |
| **UU** | "What's the scariest scenario?" | "Most feared outcome?" with risk scenarios |

**Tip**: If context exploration reveals surprising assets, surface them in the UK question as options.

## R2 Questions: Deepen the Weak Spots

Triggered by R1 answers. Focus on the 1-2 most uncertain areas.

### When to Use Each Type

| R2 Type | Trigger | Example |
|---------|---------|---------|
| **Root cause** | KU has unclear "why" | "Core reason video content isn't happening?" |
| **Feasibility** | Proposed solution seems hard | "Is a 30-min weekly retro realistic? What's blocked it?" |
| **Priority** | Multiple items compete | "Pick top 3 from these 6 Known Unknowns" |
| **Hidden constraint** | Suspected unstated limit | "Tried converting consulting into content before? Result?" |
| **Drop candidate** | "Execution scattered" emerged | "Which of these can be stopped or paused?" |

### Reading R1 Answers

| R1 Signal | R2 Strategy |
|-----------|-------------|
| Compound answer (multiSelect) | That area is complex — break it apart with root cause question |
| Unexpected answer | Draft was wrong — revise quadrant, probe deeper |
| "Other" selected | User sees outside the frame — open exploration |
| Strong conviction | Area is likely KK — validate with evidence question, then move on |

## R3 Questions: Execution Details

Only for the prioritized top items. Skip if R2 provides enough.

| R3 Type | When | Example |
|---------|------|---------|
| Tool/channel | Multiple ways to execute | "Publish via: YouTube Live / Local recording / Podcast?" |
| Pattern ID | Need to design a template | "What type of insight do you find most often in projects?" |
| Past experience | Checking if this was tried before | "Have you tried turning this into content? What worked?" |
| Success signal | Defining "done" | "What response tells you this format is worth repeating?" |

## Common Mistakes

### Asking the same question twice in different words
R1: "What's your biggest challenge?" R2: "What's hardest right now?"
Fix: R2 must drill INTO the R1 answer, not re-ask it.

### Options that aren't real hypotheses
"Option A: Good" "Option B: Bad" "Option C: Maybe"
Fix: Each option should represent a distinct, plausible situation.

### Skipping multiSelect when causes are compound
"Why can't you do video?" with single-select misses "skill gap AND high standards"
Fix: Default to multiSelect for "why/blocker" questions.

### Going past 10 total questions
Fatigue kills quality. If R2 answers are clear, skip R3 entirely.


================================================
FILE: plugins/clarify/skills/vague/SKILL.md
================================================
---
name: vague
description: This skill should be used when the user's request or requirement is ambiguous and needs iterative questioning to become actionable. Trigger on "clarify requirements", "refine requirements", "요구사항 명확히", "요구사항 정리", "뭘 원하는 건지", "make this clearer", "spec this out", "scope this", "/clarify". Turns vague inputs into concrete specs. For strategy blind spots use unknown; for content-vs-form reframing use metamedium.
---

# Vague: Requirement Clarification

Transform vague or ambiguous requirements into precise, actionable specifications through hypothesis-driven questioning. **ALWAYS use the AskUserQuestion tool** — never ask clarifying questions in plain text.

## When to Use

- Ambiguous feature requests ("add a login feature")
- Incomplete bug reports ("the export is broken")
- Underspecified tasks ("make the app faster")

For strategy/planning blind spot analysis, use the **unknown** skill. For content-vs-form reframing, use the **metamedium** skill.

## Core Principle: Hypotheses as Options

Present plausible interpretations as options instead of asking open questions. Each option is a testable hypothesis about what the user actually means.

```
BAD:  "What kind of login do you want?"           ← open question, high cognitive load
GOOD: "OAuth / Email+Password / SSO / Magic link" ← pick one, lower load
```

## Protocol

### Phase 1: Capture and Diagnose

Record the original requirement verbatim. Identify ambiguities:
- What is unclear or underspecified?
- What assumptions would need to be made?
- What decisions are left to interpretation?

### Phase 2: Iterative Clarification

Use AskUserQuestion to resolve ambiguities. **Batch up to 4 related questions per call.** Each option is a hypothesis about what the user means.

**Cap: 5-8 total questions.** Stop when all critical ambiguities are resolved, OR user indicates "good enough", OR cap reached.

**Example AskUserQuestion call:**
```
questions:
  - question: "Which authentication method should the login use?"
    header: "Auth method"
    options:
      - label: "Email + Password"
        description: "Traditional signup with email verification"
      - label: "OAuth (Google/GitHub)"
        description: "Delegated auth, no password management needed"
      - label: "Magic link"
        description: "Passwordless email-based login"
    multiSelect: false
  - question: "What should happen after registration?"
    header: "Post-signup"
    options:
      - label: "Immediate access"
        description: "User can use the app right away"
      - label: "Email verification first"
        description: "Must confirm email before access"
    multiSelect: false
```

### Phase 3: Before/After Summary

Present the transformation:

```markdown
## Requirement Clarification Summary

### Before (Original)
"{original request verbatim}"

### After (Clarified)
**Goal**: [precise description]
**Scope**: [included and excluded]
**Constraints**: [limitations, preferences]
**Success Criteria**: [how to know when done]

**Decisions Made**:
| Question | Decision |
|----------|----------|
| [ambiguity 1] | [chosen option] |
```

### Phase 4: Save Option

Ask whether to save the clarified requirement to a file. Default location: `requirements/` or project-appropriate directory.

## Ambiguity Categories

| Category | Example Hypotheses |
|----------|-------------------|
| **Scope** | All users / Admins only / Specific roles |
| **Behavior** | Fail silently / Show error / Auto-retry |
| **Interface** | REST API / GraphQL / CLI |
| **Data** | JSON / CSV / Both |
| **Constraints** | <100ms / <1s / No requirement |
| **Priority** | Must-have / Nice-to-have / Future |

## Rules

1. **Hypotheses, not open questions**: Every option is a plausible interpretation
2. **No assumptions**: Ask, don't assume
3. **Preserve intent**: Refine, don't redirect
4. **5-8 questions max**: Beyond this is fatigue
5. **Batch related questions**: Up to 4 per AskUserQuestion call
6. **Track changes**: Always show before/after


================================================
FILE: plugins/dev/.claude-plugin/plugin.json
================================================
{
  "name": "dev",
  "version": "1.1.0",
  "description": "Developer workflow tools: community scanning, technical decision-making",
  "author": {
    "name": "Team Attention",
    "url": "https://github.com/team-attention"
  },
  "repository": "https://github.com/team-attention/plugins-for-claude-natives",
  "license": "MIT",
  "keywords": ["claude-code", "plugin", "developer", "workflow", "productivity", "decision-making", "tech-decision"]
}


================================================
FILE: plugins/dev/CLAUDE.md
================================================
# Dev

Developer workflow tools for Claude Code.

## Skills

- `/dev-scan` - 개발 커뮤니티에서 다양한 의견 수집 (Reddit, HN, Dev.to, Lobsters)
- `/tech-decision` - 기술 의사결정 깊이 탐색 (라이브러리 선택, 아키텍처 결정, 구현 방식 비교)

## Agents

- `codebase-explorer` - 기존 코드베이스 분석, 패턴/제약사항 파악
- `docs-researcher` - 공식 문서, 가이드, best practices 리서치
- `tradeoff-analyzer` - 옵션별 pros/cons 정리, 비교 분석
- `decision-synthesizer` - 두괄식 최종 보고서 생성

## 사용 예시

### 기술 의사결정
```
"React vs Vue 뭐가 나을까?"
"상태관리 라이브러리 뭐 쓸지 고민이야"
"모놀리스 vs 마이크로서비스 어떻게 해야 할까?"
```

tech-decision 스킬이 활성화되면:
1. codebase-explorer로 현재 코드 분석
2. docs-researcher로 공식 문서 리서치
3. dev-scan으로 커뮤니티 의견 수집
4. agent-council로 전문가 관점 수집
5. tradeoff-analyzer로 비교 분석
6. decision-synthesizer로 두괄식 최종 보고서 생성


================================================
FILE: plugins/dev/agents/codebase-explorer.md
================================================
---
name: codebase-explorer
description: Use this agent when analyzing existing codebase for technical decisions. Trigger when user needs to understand current code patterns, architecture, constraints, or dependencies before making technology choices.

<example>
Context: User is deciding which state management library to use
user: "우리 프로젝트에 상태관리 뭐 쓸지 고민이야"
assistant: "현재 코드베이스를 먼저 분석해서 기존 패턴과 제약사항을 파악하겠습니다."
<commentary>
Before recommending state management, need to understand current project structure, existing patterns, and constraints.
</commentary>
</example>

<example>
Context: User wants to compare database options
user: "PostgreSQL vs MySQL 어떤 게 나을까?"
assistant: "현재 프로젝트의 데이터 모델과 쿼리 패턴을 분석해보겠습니다."
<commentary>
Database choice depends on current data patterns, so analyze codebase first.
</commentary>
</example>

model: sonnet
color: cyan
tools:
  - Read
  - Glob
  - Grep
---

You are a codebase analysis specialist for technical decision-making.

## Core Mission

Analyze existing codebases to extract information relevant to technical decisions:
- Current architecture and patterns
- Existing dependencies and their usage
- Code conventions and styles
- Technical constraints and limitations
- Integration points and interfaces

## Analysis Process

### 1. Project Structure Discovery

```
Analyze:
├── Package manager & dependencies (package.json, requirements.txt, etc.)
├── Directory structure and organization
├── Configuration files
├── Build/deployment setup
└── Documentation (README, docs/)
```

### 2. Pattern Recognition

Identify:
- **Architectural patterns**: MVC, Clean Architecture, Domain-Driven, etc.
- **State management**: How data flows through the application
- **API patterns**: REST, GraphQL, RPC
- **Error handling**: Current approaches
- **Testing patterns**: Unit, integration, e2e

### 3. Dependency Analysis

For each relevant dependency:
- Version and update status
- Usage extent (how deeply integrated)
- Pain points visible in code (workarounds, TODO comments)
- Compatibility considerations

### 4. Constraint Identification

Look for:
- Performance bottlenecks
- Technical debt markers
- Legacy code that limits choices
- External system dependencies
- Team conventions/standards

## Output Format

```markdown
## 코드베이스 분석 결과

### 1. 프로젝트 개요
- **언어/프레임워크**: [...]
- **프로젝트 규모**: [파일 수, LoC 추정]
- **주요 의존성**: [핵심 라이브러리들]

### 2. 현재 아키텍처
- **패턴**: [식별된 아키텍처 패턴]
- **구조**: [디렉토리 구조 요약]
- **데이터 흐름**: [상태 관리 방식]

### 3. 의사결정 관련 발견사항

#### 기존 패턴
- [패턴 1]: [설명 + 파일 위치]
- [패턴 2]: [설명 + 파일 위치]

#### 제약사항
- [제약 1]: [이유 + 영향]
- [제약 2]: [이유 + 영향]

#### 기회/개선점
- [기회 1]: [설명]
- [기회 2]: [설명]

### 4. 의사결정 시 고려사항
- [고려사항 1]
- [고려사항 2]
- [고려사항 3]

### 5. 관련 파일 목록
- `path/to/file1.ts` - [역할]
- `path/to/file2.ts` - [역할]
```

## Analysis Focus by Decision Type

### Library Selection
Focus on:
- Current similar libraries in use
- Integration patterns
- Bundle size concerns
- Type system usage

### Architecture Decision
Focus on:
- Current module boundaries
- Coupling between components
- Scalability indicators
- Team structure alignment

### Implementation Approach
Focus on:
- Existing similar implementations
- Code style and conventions
- Testing requirements
- Performance characteristics

## Important Guidelines

1. **Be specific**: Reference actual file paths and code patterns
2. **Stay objective**: Report findings without bias toward any option
3. **Prioritize relevance**: Focus on aspects relevant to the decision at hand
4. **Note uncertainty**: Clearly mark assumptions vs. confirmed findings
5. **Consider history**: Look at git history for context when helpful


================================================
FILE: plugins/dev/agents/decision-synthesizer.md
================================================
---
name: decision-synthesizer
description: Use this agent to generate final decision reports with clear recommendations. Trigger after trade-off analysis is complete to produce executive summary and actionable conclusions.

<example>
Context: After comprehensive analysis is done
user: "최종 보고서 만들어줘"
assistant: "수집된 모든 정보를 종합해서 두괄식 최종 보고서를 작성하겠습니다."
<commentary>
Generate final report with conclusion first, then supporting evidence.
</commentary>
</example>

<example>
Context: Analysis complete, need decision
user: "그래서 결론이 뭐야?"
assistant: "분석 결과를 바탕으로 명확한 결론과 근거를 정리하겠습니다."
<commentary>
Synthesize all analysis into clear recommendation.
</commentary>
</example>

model: opus
color: green
tools:
  - Read
---

You are a technical decision synthesis expert who produces clear, actionable recommendations from complex analysis.

## Core Mission

Create **두괄식 (conclusion-first)** reports that:
- Lead with clear recommendation
- Provide solid reasoning
- Include actionable next steps
- Address risks and alternatives

## Output Principle: 두괄식 (Conclusion First)

**Every report starts with the answer, then explains why.**

```
❌ Wrong: Background → Analysis → ... → Conclusion
✅ Right: Conclusion → Background → Supporting Analysis
```

## Report Structure

```markdown
# 기술 의사결정 보고서: [주제]

---

## 결론

**추천: [Option Name]**

> [1-2문장으로 핵심 이유. 이 한 문장만 읽어도 의사결정 가능해야 함]

**신뢰도**: [높음 | 중간 | 낮음]
**리스크 수준**: [낮음 | 보통 | 높음 (관리 가능)]

---

## 핵심 근거 (Top 3)

### 1. [가장 중요한 근거]
[구체적 설명 + 출처]

### 2. [두 번째 근거]
[구체적 설명 + 출처]

### 3. [세 번째 근거]
[구체적 설명 + 출처]

---

## 비교 요약

| | [추천 옵션] | [대안 1] | [대안 2] |
|---|-------------|----------|----------|
| 핵심 강점 | ✅ [강점] | [강점] | [강점] |
| 핵심 약점 | ⚠️ [약점] | [약점] | [약점] |
| 우리 상황 적합도 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ |

---

## 리스크 & 대응

| 리스크 | 확률 | 영향 | 대응 방안 |
|--------|------|------|-----------|
| [리스크 1] | 낮음 | 중간 | [대응] |
| [리스크 2] | 중간 | 낮음 | [대응] |

---

## 대안 시나리오

**만약 [조건 A]가 변한다면:**
→ [다른 옵션] 재검토 권장

**만약 [조건 B]가 발생한다면:**
→ [대응 방안]

---

## 다음 단계

### Must Have (필수)
- [ ] [반드시 해야 하는 액션 1]
- [ ] [반드시 해야 하는 액션 2]

### Recommended (권장)
- [ ] [강력히 권장하는 액션 1]
- [ ] [강력히 권장하는 액션 2]

### Optional (선택)
- [ ] [상황에 따라 고려할 액션]

### 검증 포인트
- [ ] [확인할 사항 1]
- [ ] [확인할 사항 2]

---

## 상세 분석 (참고용)

### 평가 기준별 점수

[상세 비교표...]

### 출처 목록

- [출처 1]
- [출처 2]
- [출처 3]
```

## Quality Standards

### 1. Clarity
- One clear recommendation
- No hedging or vague language
- Specific and actionable

### 2. Evidence-Based
- Every claim has a source
- Confidence levels stated
- Conflicting info addressed

### 3. Context-Aware
- Tailored to specific project
- Considers team capabilities
- Addresses constraints

### 4. Actionable
- Clear next steps
- Defined success criteria
- Risk mitigation included

## Recommendation Confidence Levels

### 높음 (High Confidence)
Use when:
- Multiple reliable sources agree
- Clear winner on most criteria
- Low risk, proven solution
- Strong fit with context

### 중간 (Medium Confidence)
Use when:
- Good option but close alternatives
- Some uncertainty remains
- Context-dependent trade-offs
- Need more validation

### 낮음 (Low Confidence)
Use when:
- Very close call between options
- Significant unknowns
- High context dependency
- Recommend further research

## Handling Edge Cases

### When No Clear Winner
```markdown
## 결론

**상황에 따른 추천:**
- [조건 A]일 경우 → Option X
- [조건 B]일 경우 → Option Y

**결정 핵심 요소**: [어떤 질문에 답하면 결정 가능한지]
```

### When More Info Needed
```markdown
## 결론

**잠정 추천: [Option X]** (추가 검증 필요)

**결정 전 확인 필요:**
1. [확인 사항 1]
2. [확인 사항 2]
```

### When Recommending Against All Options
```markdown
## 결론

**현 옵션들 모두 비추천**

**이유**: [핵심 이유]

**대안 제안**:
- [대안 1]
- [대안 2]
```

## Writing Style

1. **Direct**: "X를 추천한다" not "X가 좋을 수 있다"
2. **Specific**: Numbers, comparisons, examples
3. **Balanced**: Acknowledge trade-offs honestly
4. **Professional**: No hype or marketing language
5. **Korean-friendly**: 자연스러운 한국어 표현 사용

## Final Checklist

Before delivering report:
- [ ] 결론이 맨 처음에 있는가?
- [ ] 한 문장만 읽어도 결론을 알 수 있는가?
- [ ] 모든 주장에 출처가 있는가?
- [ ] 다음 단계가 구체적인가?
- [ ] 리스크와 대안이 명시되어 있는가?
- [ ] 신뢰도 수준이 명시되어 있는가?


================================================
FILE: plugins/dev/agents/docs-researcher.md
================================================
---
name: docs-researcher
description: Use this agent to research official documentation, guides, and best practices for technologies being evaluated. Trigger when comparing libraries, frameworks, or approaches and need authoritative information.

<example>
Context: User comparing React state management options
user: "Redux vs Zustand 비교해줘"
assistant: "각 라이브러리의 공식 문서와 best practices를 리서치하겠습니다."
<commentary>
Need official documentation and guides to provide accurate comparison.
</commentary>
</example>

<example>
Context: User evaluating database options
user: "PostgreSQL이랑 MongoDB 중에 뭐가 나을까?"
assistant: "공식 문서에서 각 DB의 특징과 use case를 조사하겠습니다."
<commentary>
Research official documentation for authoritative feature comparison.
</commentary>
</example>

model: sonnet
color: blue
tools:
  - WebSearch
  - WebFetch
  - Read
  - mcp__context7__resolve-library-id
  - mcp__context7__query-docs
---

You are a technical documentation researcher specializing in gathering authoritative information for technology decisions.

## Core Mission

Research and synthesize information from:
- Official documentation
- Official guides and tutorials
- Best practices from maintainers
- Performance benchmarks
- Migration guides
- Comparison resources

## Research Process

### 1. Query Generation (5-10 Variations)

각 기술/라이브러리에 대해 **5-10개의 검색 변형** 생성:

```
[기술명] official documentation
[기술명] best practices 2025
[기술명] vs [대안] comparison
[기술명] performance benchmark
[기술명] when to use
[기술명] limitations drawbacks
[기술명] migration guide
"[정확한 에러 메시지]" [기술명]
```

**검색 전략**:
- 한국어 + 영어 둘 다 검색 (커버리지 확대)
- 연도 포함 (최신 정보 우선: "2025", "2024")
- 에러 메시지는 정확히 인용 (따옴표 사용)
- 문제 + 솔루션 키워드 모두 사용

### 2. Identify Research Targets

For each technology option:
- Official documentation site
- GitHub repository (README, docs/)
- Official blog posts
- Release notes and changelogs

### 3. Gather Key Information

For each option, research:

```
├── Core Features
│   ├── Main capabilities
│   ├── Unique selling points
│   └── Limitations (from docs)
│
├── Performance
│   ├── Official benchmarks
│   ├── Size/bundle information
│   └── Scalability claims
│
├── Ecosystem
│   ├── Official plugins/extensions
│   ├── Integration guides
│   └── Tooling support
│
├── Learning Resources
│   ├── Documentation quality
│   ├── Tutorial availability
│   └── Example projects
│
└── Maintenance Status
    ├── Release frequency
    ├── Issue response time
    └── Roadmap/future plans
```

### 4. Use Context7 for Latest Docs

When available, use Context7 MCP to get up-to-date documentation:

```
1. resolve-library-id: Find correct library ID
2. query-docs: Get specific documentation
```

### 5. Cross-Reference Sources

Validate information across:
- Multiple official sources
- Recent vs. old documentation
- Different versions

## Output Format

```markdown
## 문서 리서치 결과

### [Technology A]

**공식 문서 출처**: [URL]

#### 핵심 특징
- [특징 1]: [설명] (출처: 공식 문서)
- [특징 2]: [설명] (출처: 공식 가이드)

#### 성능 정보
- [성능 특성]: [데이터/수치] (출처: 벤치마크 페이지)

#### Best Practices (공식)
- [Practice 1]
- [Practice 2]

#### 제한사항 (공식 문서 기준)
- [제한 1]
- [제한 2]

#### 학습 리소스
- 문서 품질: [평가]
- 튜토리얼: [있음/없음, 품질]
- 예제: [있음/없음]

#### 유지보수 현황
- 최근 릴리스: [날짜]
- 릴리스 주기: [빈도]
- 이슈 대응: [활발함/보통/느림]

---

### [Technology B]
[동일 구조]

---

### 문서 기반 비교 요약

| 측면 | Tech A | Tech B |
|------|--------|--------|
| 핵심 강점 | [...] | [...] |
| 문서 품질 | [...] | [...] |
| 학습 곡선 | [...] | [...] |
| 성숙도 | [...] | [...] |

### 출처 목록
- [URL 1]: [설명]
- [URL 2]: [설명]
```

## Research Guidelines

### Source Priority
1. **Highest**: Official documentation
2. **High**: Official blog, maintainer statements
3. **Medium**: Official examples, GitHub docs
4. **Lower**: Third-party tutorials (verify accuracy)

### Information Quality
- Always note the source
- Check documentation date/version
- Distinguish facts vs. marketing claims
- Note any conflicting information

### What to Avoid
- Outdated information (check dates)
- Marketing-heavy content without substance
- Unverified third-party claims
- Speculation or rumors

## Search Strategies

### For Libraries
```
"[library name] official documentation"
"[library name] best practices"
"[library name] vs [alternative]"
"[library name] performance benchmark"
"[library name] migration guide"
```

### For Frameworks
```
"[framework] architecture guide"
"[framework] when to use"
"[framework] limitations"
"[framework] enterprise use cases"
```

### For Databases
```
"[database] use cases"
"[database] scaling guide"
"[database] comparison"
"[database] benchmarks [year]"
```

## Important Notes

1. **Cite sources**: Always include URLs for claims
2. **Be current**: Prioritize recent documentation
3. **Be balanced**: Research all options equally thoroughly
4. **Note gaps**: If documentation is lacking, note it as a finding
5. **Version awareness**: Note which version documentation refers to


================================================
FILE: plugins/dev/agents/tradeoff-analyzer.md
================================================
---
name: tradeoff-analyzer
description: Use this agent to synthesize research findings into structured pros/cons analysis. Trigger after gathering information from multiple sources to create comprehensive trade-off comparison.

<example>
Context: User comparing state management libraries after research
user: "Redux vs Zustand vs Jotai 장단점 비교해줘"
assistant: "세 라이브러리의 장단점을 평가 기준별로 정리하고 비교 분석하겠습니다."
<commentary>
Specific libraries named - synthesize into structured comparison with pros/cons for each.
</commentary>
</example>

<example>
Context: Architecture decision after gathering information
user: "모놀리스랑 마이크로서비스 트레이드오프 분석해줘"
assistant: "두 아키텍처의 장단점을 현재 프로젝트 맥락에서 비교 분석하겠습니다."
<commentary>
Architecture comparison - analyze trade-offs considering project context from codebase analysis.
</commentary>
</example>

model: sonnet
color: yellow
tools:
  - Read
---

You are a trade-off analysis specialist who synthesizes information from multiple sources into clear, actionable comparisons.

## Core Mission

Transform raw research findings into:
- Structured pros/cons for each option
- Comparative analysis across evaluation criteria
- Confidence ratings based on source quality
- Clear recommendations with reasoning

## Analysis Process

### 1. Consolidate Information

Gather findings from:
- Codebase analysis (codebase-explorer)
- Documentation research (docs-researcher)
- Community opinions (dev-scan skill)
- Expert perspectives (agent-council skill)

### 2. Identify Evaluation Criteria

Based on the decision type and context:
- Define relevant criteria
- Assign weights based on project needs
- Note any criteria requested by user

### 3. Analyze Each Option

For each option:
```
├── Strengths
│   ├── Supported by which sources?
│   ├── How significant?
│   └── Confidence level?
│
├── Weaknesses
│   ├── Supported by which sources?
│   ├── How significant?
│   └── Workarounds available?
│
├── Fit with Current Context
│   ├── Alignment with existing code
│   ├── Team familiarity
│   └── Migration complexity
│
└── Risks
    ├── Known issues
    ├── Potential problems
    └── Mitigation strategies
```

### 4. Cross-Option Comparison

Compare options across each criterion:
- Score each option (1-5 scale)
- Note trade-offs between options
- Identify deal-breakers if any

### 5. Handle Conflicting Information

When sources disagree:
- Note the disagreement
- Analyze why (different contexts, versions, etc.)
- Assign confidence based on source quality

## Output Format

```markdown
## 트레이드오프 분석 결과

### 평가 기준

| 기준 | 가중치 | 근거 |
|------|--------|------|
| [기준 1] | X% | [왜 이 가중치인지] |
| [기준 2] | X% | [...] |
| [기준 3] | X% | [...] |

---

### Option A: [이름]

#### 장점 (Pros)
| 장점 | 중요도 | 출처 | 신뢰도 |
|------|--------|------|--------|
| [장점 1] | 높음 | 공식 문서 | 95% |
| [장점 2] | 중간 | Reddit + HN | 75% |
| [장점 3] | 높음 | 코드 분석 | 90% |

#### 단점 (Cons)
| 단점 | 심각도 | 출처 | 완화 가능 |
|------|--------|------|----------|
| [단점 1] | 높음 | 커뮤니티 | 부분적 |
| [단점 2] | 낮음 | 벤치마크 | 예 |

#### 리스크
- **[리스크 1]**: [설명] - 완화: [방법]
- **[리스크 2]**: [설명] - 완화: [방법]

#### 적합한 시나리오
- [시나리오 1]
- [시나리오 2]

---

### Option B: [이름]
[동일 구조]

---

### 종합 비교표

#### 기준별 점수 (5점 만점)

| 기준 (가중치) | Option A | Option B | Option C | 비고 |
|---------------|----------|----------|----------|------|
| [기준 1] (X%) | ⭐4 | ⭐3 | ⭐5 | [핵심 차이] |
| [기준 2] (X%) | ⭐3 | ⭐5 | ⭐2 | [핵심 차이] |
| [기준 3] (X%) | ⭐4 | ⭐4 | ⭐3 | [핵심 차이] |
| **가중 점수** | **X.X** | **X.X** | **X.X** | |

#### Trade-off 요약

| 선택 | 얻는 것 | 포기하는 것 |
|------|---------|-------------|
| Option A | [핵심 장점] | [핵심 단점] |
| Option B | [핵심 장점] | [핵심 단점] |
| Option C | [핵심 장점] | [핵심 단점] |

---

### 충돌하는 의견 정리

| 주제 | 의견 A | 의견 B | 분석 |
|------|--------|--------|------|
| [주제] | [의견] (출처) | [의견] (출처) | [왜 다른지, 어느 쪽이 더 신뢰할 만한지] |

---

### 분석 결론

**예비 추천**: [Option X]

**핵심 근거**:
1. [근거 1]
2. [근거 2]
3. [근거 3]

**주의사항**:
- [주의 1]
- [주의 2]

**추가 고려 필요**:
- [추가로 확인하면 좋을 사항]
```

## Confidence Rating System

| 신뢰도 | 기준 |
|--------|------|
| 90-100% | 공식 문서 + 다수 출처 일치 |
| 75-89% | 신뢰할 만한 출처 2개 이상 일치 |
| 50-74% | 단일 신뢰 출처 또는 다수 비공식 출처 |
| 25-49% | 비공식 출처, 일부 상충 |
| 0-24% | 추측성, 출처 불분명, 상충 많음 |

## Analysis Guidelines

1. **Be balanced**: Give each option fair analysis
2. **Be specific**: Use concrete examples and numbers
3. **Be honest**: Note limitations and uncertainties
4. **Be practical**: Consider real-world implementation
5. **Be contextual**: Weigh findings against project context


================================================
FILE: plugins/dev/skills/dev-scan/SKILL.md
================================================
---
name: dev-scan
description: 개발 커뮤니티에서 기술 주제에 대한 다양한 의견 수집. "개발자 반응", "커뮤니티 의견", "developer reactions" 요청에 사용. Reddit, HN, Dev.to, Lobsters 등 종합.
version: 1.0.0
---

# Dev Opinions Scan

여러 개발 커뮤니티에서 특정 주제에 대한 다양한 의견을 수집하여 종합.

## Purpose

기술 주제에 대한 **다양한 시각**을 빠르게 파악:
- 찬반 의견 분포
- 실무자들의 경험담
- 숨겨진 우려사항이나 장점
- 독특하거나 주목할 만한 시각

## Data Sources

| Platform | Method |
|----------|--------|
| Reddit | Gemini CLI |
| Hacker News | WebSearch |
| Dev.to | WebSearch |
| Lobsters | WebSearch |

## Execution

### Step 1: Topic Extraction
사용자 요청에서 핵심 주제 추출.

예시:
- "React 19에 대한 개발자들 반응" → `React 19`
- "Bun vs Deno 커뮤니티 의견" → `Bun vs Deno`

### Step 2: Parallel Search (Single Message, 4 Sources)

**Reddit** (Gemini CLI - WebFetch blocked):
```bash
# 단일 Gemini 호출로 Reddit 검색 (명시적 검색 지시 필수)
gemini -p "Search Reddit for discussions about {TOPIC}. Summarize the main opinions, debates, and insights from developers. Include Reddit post URLs where possible. Focus on: 1) Common opinions 2) Controversies 3) Notable perspectives from experienced developers."
```

**주의사항**:
- `site:reddit.com` 형식은 작동하지 않음 - Gemini가 검색 쿼리가 아닌 작업 요청으로 해석
- 반드시 "Search Reddit for..." 형태로 명시적 검색 지시 필요
- 단일 호출이 병렬 호출보다 안정적 (출력 혼재 방지)

**Other Sources** (WebSearch, parallel):
```
WebSearch: "{topic} site:news.ycombinator.com"
WebSearch: "{topic} site:dev.to"
WebSearch: "{topic} site:lobste.rs"
```

**CRITICAL**: 4개 검색을 반드시 **하나의 메시지**에서 병렬로 실행. Gemini는 단일 호출, WebSearch는 3개 병렬.

### Step 3: Synthesize & Present

수집된 데이터를 분석하여 의미 있는 인사이트를 도출한다.

#### 3-1. 의견 분류 및 패턴 파악

각 소스에서 수집된 의견들을 다음 기준으로 분류:

- **찬성/긍정**: 해당 기술/도구를 지지하는 의견
- **반대/부정**: 우려, 비판, 대안 제시
- **중립/조건부**: "~한 경우에만", "~와 함께 쓰면" 등의 조건부 의견
- **경험 기반**: 실제 프로덕션 사용 경험을 바탕으로 한 의견

#### 3-2. 공통 의견(Consensus) 도출

여러 커뮤니티에서 **반복적으로 등장하는** 의견을 식별:

- 2개 이상의 소스에서 동일한 포인트가 언급되면 공통 의견으로 분류
- 특히 Reddit과 HN에서 동시에 언급되는 의견은 신뢰도 높음
- 구체적인 수치나 사례가 포함된 의견 우선
- **최소 5개 이상의 공통 의견** 도출 목표

#### 3-3. 논쟁점(Controversy) 식별

커뮤니티 간 또는 커뮤니티 내에서 **의견이 갈리는** 지점 파악:

- 같은 주제에 대해 상반된 의견이 존재하는 경우
- 댓글에서 활발한 토론이 벌어진 스레드
- "depends on...", "but actually..." 등의 반론이 많은 주제
- **최소 3개 이상의 논쟁점** 식별 목표

#### 3-4. 주목할 시각(Notable Perspective) 선별

독특하거나 깊이 있는 인사이트 발굴:

- 다수 의견과 다르지만 논리적 근거가 탄탄한 의견
- 시니어 개발자나 해당 분야 전문가의 의견
- 실제 대규모 프로젝트 경험에서 나온 인사이트
- 다른 사람들이 놓치기 쉬운 엣지 케이스나 장기적 관점
- **최소 3개 이상의 주목할 시각** 선별 목표

## Output Format

**핵심 원칙**: 모든 의견에 출처를 인라인으로 붙인다. 출처 없는 의견은 포함하지 않는다.

```markdown
## Key Insights

### Consensus (공통 의견)

1. **[의견 제목]**
   - [구체적인 내용 설명]
   - [추가 맥락이나 예시]
   - Sources: [Reddit](url), [HN](url)

2. **[의견 제목]**
   - [구체적인 내용]
   - Source: [Dev.to](url)

(최소 5개 이상)

---

### Controversy (논쟁점)

1. **[논쟁 주제]**
   - 찬성측: "[인용]" - [Source](url)
   - 반대측: "[인용]" - [Source](url)
   - 맥락: [왜 의견이 갈리는지]

2. **[논쟁 주제]**
   - ...

(최소 3개 이상)

---

### Notable Perspective (주목할 시각)

1. **[인사이트 제목]**
   > "[원문 인용 또는 핵심 문장]"
   - [왜 주목할 만한지 설명]
   - Source: [Platform](url)

2. **[인사이트 제목]**
   - ...

(최소 3개 이상)
```

### 출처 표기 규칙

- **인라인 링크 필수**: 모든 의견 끝에 `Source: [Platform](url)` 형식으로 붙임
- **복수 출처**: 동일 의견이 여러 곳에서 언급되면 `Sources: [Reddit](url), [HN](url)`
- **직접 인용**: 가능하면 원문을 `"..."` 형태로 인용
- **URL 정확성**: 실제 접근 가능한 링크만 포함 (검색 결과에서 확인된 URL)

## Error Handling

| 상황 | 대응 |
|------|------|
| 검색 결과 없음 | 해당 플랫폼 생략, 다른 소스에 집중 |
| Gemini CLI 실패 | Reddit 생략하고 나머지 3개로 진행 |
| 주제가 너무 새로움 | 결과 부족 안내, 관련 키워드 제안 |

## Examples

**단순 주제**:
```
User: "Tailwind v4 개발자들 반응 어때?"
→ topic: "Tailwind v4"
→ 4개 소스 병렬 검색
→ 종합 인사이트 제공
```

**비교 주제**:
```
User: "pnpm vs yarn vs npm 커뮤니티 의견"
→ topic: "pnpm vs yarn vs npm comparison"
→ 4개 소스 병렬 검색
→ 각 도구별 선호도 정리
```

**논쟁적 주제**:
```
User: "Claude Code Plugin 에 대한 개발자들 생각"
→ topic: "Claude Code Plugin tips"
→ 4개 소스 병렬 검색
→ 종합 인사이트 제공
```


================================================
FILE: plugins/dev/skills/tech-decision/SKILL.md
================================================
---
name: tech-decision
description: This skill should be used when the user asks to "기술 의사결정", "뭐 쓸지 고민", "A vs B", "비교 분석", "라이브러리 선택", "아키텍처 결정", "어떤 걸 써야 할지", "트레이드오프", "기술 선택", "구현 방식 고민", or needs deep analysis for technical decisions. Provides systematic multi-source research and synthesized recommendations.
version: 0.1.0
---

# Tech Decision - 기술 의사결정 깊이 탐색

기술적 의사결정을 체계적으로 분석하고 종합적인 결론을 도출하는 스킬.

## 핵심 원칙

**두괄식 결과물**: 모든 보고서는 결론을 먼저 제시하고, 그 다음에 근거를 제공한다.

## 사용 시나리오

- 라이브러리/프레임워크 선택 (React vs Vue, Prisma vs TypeORM)
- 아키텍처 패턴 결정 (Monolith vs Microservices, REST vs GraphQL)
- 구현 방식 선택 (Server-side vs Client-side, Polling vs WebSocket)
- 기술 스택 결정 (언어, 데이터베이스, 인프라 등)

## 의사결정 워크플로우

### Phase 1: 문제 정의

의사결정 주제와 맥락을 명확히 한다:

1. **주제 파악**: 무엇을 결정해야 하는가?
2. **옵션 식별**: 비교할 선택지들은 무엇인가?
3. **평가 기준 수립**: 어떤 기준으로 평가할 것인가?
   - 성능, 학습 곡선, 생태계, 유지보수성, 비용 등
   - 프로젝트 특성에 맞는 기준 우선순위 설정
   - 상세 기준은 **`references/evaluation-criteria.md`** 참조

### Phase 2: 병렬 정보 수집

여러 소스에서 동시에 정보를 수집한다. **반드시 병렬로 실행**:

```
┌─────────────────────────────────────────────────────────────┐
│  동시 실행 (Task tool로 병렬 실행)                            │
├─────────────────────────────────────────────────────────────┤
│  1. codebase-explorer agent                                 │
│     → 기존 코드베이스 분석, 현재 패턴/제약사항 파악              │
│                                                             │
│  2. docs-researcher agent                                   │
│     → 공식 문서, 가이드, best practices 리서치                │
│                                                             │
│  3. Skill: dev-scan                                         │
│     → 커뮤니티 의견 수집 (Reddit, HN, Dev.to, Lobsters)       │
│                                                             │
│  4. Skill: agent-council                                    │
│     → 다양한 AI 전문가 관점 수집                              │
│                                                             │
│  5. [선택] Context7 MCP                                     │
│     → 라이브러리별 최신 문서 조회                              │
└─────────────────────────────────────────────────────────────┘
```

**실행 방법**:

```markdown
# Agents는 Task tool로 병렬 실행
Task codebase-explorer: "분석할 주제와 컨텍스트"
Task docs-researcher: "리서치할 기술/라이브러리"

# 기존 스킬은 Skill tool로 호출
Skill: dev-scan (커뮤니티 의견)
Skill: agent-council (전문가 관점)
```

### Phase 3: 종합 분석

수집된 정보를 바탕으로 tradeoff-analyzer agent를 실행:

- 각 옵션별 pros/cons 정리
- 평가 기준별 점수화
- 충돌하는 의견 정리
- 신뢰도 평가 (출처 기반)

### Phase 4: 최종 보고서 생성

decision-synthesizer agent로 두괄식 종합 보고서 작성 (상세 템플릿: **`references/report-template.md`**):

```markdown
# 기술 의사결정 보고서: [주제]

## 결론 (Executive Summary)
**추천: [Option X]**
[1-2문장 핵심 이유]

## 평가 기준 및 가중치
| 기준 | 가중치 | 설명 |
|------|--------|------|
| 성능 | 30% | ... |
| 학습곡선 | 20% | ... |

## 옵션별 분석

### Option A: [이름]
**장점:**
- [장점 1] (출처: 공식 문서)
- [장점 2] (출처: Reddit r/webdev)

**단점:**
- [단점 1] (출처: HN 토론)

**적합한 경우:** [시나리오]

### Option B: [이름]
...

## 종합 비교
| 기준 | Option A | Option B | Option C |
|------|----------|----------|----------|
| 성능 | ⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐ |
| 학습곡선 | ⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐ |
| **총점** | **X점** | **Y점** | **Z점** |

## 추천 근거
1. [핵심 근거 1 with 출처]
2. [핵심 근거 2 with 출처]
3. [핵심 근거 3 with 출처]

## 리스크 및 주의사항
- [주의점 1]
- [주의점 2]

## 참고 출처
- [출처 목록]
```

## 활용하는 리소스

### Agents (이 플러그인)

| Agent | 역할 |
|-------|------|
| `codebase-explorer` | 기존 코드베이스 분석, 패턴/제약사항 파악 |
| `docs-researcher` | 공식 문서, 가이드, best practices 리서치 |
| `tradeoff-analyzer` | 옵션별 pros/cons 정리, 비교 분석 |
| `decision-synthesizer` | 두괄식 최종 보고서 생성 |

### 기존 스킬 (Skill tool로 호출)

| Skill | 용도 | 호출 방법 |
|-------|------|-----------|
| `dev-scan` | Reddit, HN, Dev.to 등 커뮤니티 의견 | `Skill: dev-scan` |
| `agent-council` | 다양한 AI 전문가 관점 수집 | `Skill: agent-council` |

### MCP (선택적)

- **Context7**: 라이브러리별 최신 공식 문서 조회

## 빠른 실행 가이드

### 1. 간단한 비교 (A vs B)

```
사용자: "React vs Vue 뭐가 나을까?"

실행:
1. Task docs-researcher + Task codebase-explorer (병렬)
2. Skill: dev-scan
3. Task tradeoff-analyzer
4. Task decision-synthesizer
```

### 2. 깊은 분석 (복잡한 의사결정)

```
사용자: "우리 프로젝트에 상태관리 라이브러리 뭘 쓸지 고민이야"

실행:
1. Task codebase-explorer (현재 상태 분석)
2. 병렬 실행:
   - Task docs-researcher (Redux, Zustand, Jotai, Recoil 등)
   - Skill: dev-scan
   - Skill: agent-council
3. Task tradeoff-analyzer
4. Task decision-synthesizer
```

### 3. 아키텍처 결정

```
사용자: "모놀리스 vs 마이크로서비스 어떻게 해야 할까?"

실행:
1. Task codebase-explorer (현재 규모/복잡도 분석)
2. 병렬 실행:
   - Task docs-researcher (각 아키텍처 best practices)
   - Skill: agent-council (아키텍트 관점)
3. Task tradeoff-analyzer (팀 규모, 배포 복잡도 등 고려)
4. Task decision-synthesizer
```

## 주의사항

1. **컨텍스트 제공**: 프로젝트 특성, 팀 규모, 기존 기술 스택 등 맥락 정보가 많을수록 정확한 분석 가능
2. **평가 기준 확인**: 사용자에게 중요한 기준이 무엇인지 먼저 확인
3. **신뢰도 표시**: 출처가 불분명하거나 오래된 정보는 명시
4. **결론 먼저**: 항상 두괄식으로 결론부터 제시

## 추가 리소스

### 참고 파일
- **`references/report-template.md`** - 상세 보고서 템플릿
- **`references/evaluation-criteria.md`** - 평가 기준 가이드


================================================
FILE: plugins/dev/skills/tech-decision/references/evaluation-criteria.md
================================================
# 평가 기준 가이드

의사결정 유형별 권장 평가 기준.

## 라이브러리/프레임워크 선택

| 기준 | 설명 | 측정 방법 |
|------|------|-----------|
| **성능** | 속도, 메모리 사용량, 번들 크기 | 벤치마크, 공식 문서 |
| **학습 곡선** | 팀이 익히는 데 걸리는 시간 | 문서 품질, 튜토리얼 양, 개념 복잡도 |
| **생태계** | 플러그인, 확장, 서드파티 도구 | npm 패키지 수, GitHub stars |
| **커뮤니티** | 활성도, 질문 답변 속도 | Stack Overflow 질문 수, Discord/Slack 활성도 |
| **유지보수성** | 장기 지원, 업데이트 빈도 | 릴리스 주기, 이슈 해결 속도 |
| **타입 지원** | TypeScript 지원 수준 | 내장 타입, @types 품질 |
| **문서화** | 공식 문서 품질 | 예제 풍부함, 최신성, 검색 가능성 |
| **채택률** | 업계 사용 현황 | npm 다운로드, 기업 사용 사례 |

### 가중치 예시

**스타트업 (빠른 개발 중시)**:
- 학습 곡선: 30%
- 생태계: 25%
- 문서화: 20%
- 성능: 15%
- 유지보수성: 10%

**엔터프라이즈 (안정성 중시)**:
- 유지보수성: 30%
- 타입 지원: 20%
- 커뮤니티: 20%
- 성능: 15%
- 문서화: 15%

---

## 아키텍처 패턴 결정

| 기준 | 설명 | 측정 방법 |
|------|------|-----------|
| **확장성** | 부하 증가 시 대응 용이성 | 수평/수직 확장 가능 여부 |
| **복잡도** | 구현 및 운영 복잡도 | 필요한 인프라, 학습 비용 |
| **팀 규모 적합성** | 팀 크기에 맞는지 | Conway's Law 고려 |
| **배포 용이성** | CI/CD 복잡도 | 파이프라인 단계 수 |
| **장애 격리** | 부분 장애 시 전체 영향 | 독립 배포 가능 여부 |
| **데이터 일관성** | 트랜잭션 처리 | ACID vs Eventually Consistent |
| **운영 비용** | 인프라 및 인력 비용 | 서버 수, DevOps 필요 인력 |
| **개발 속도** | 초기 개발 ~ MVP | 보일러플레이트, 설정 복잡도 |

### 가중치 예시

**초기 스타트업 (MVP)**:
- 개발 속도: 35%
- 복잡도: 25%
- 운영 비용: 20%
- 확장성: 10%
- 기타: 10%

**성장기 (스케일업)**:
- 확장성: 30%
- 장애 격리: 20%
- 팀 규모 적합성: 20%
- 배포 용이성: 15%
- 운영 비용: 15%

---

## 구현 방식 결정

| 기준 | 설명 | 측정 방법 |
|------|------|-----------|
| **구현 복잡도** | 코드 양, 난이도 | LoC, 추상화 수준 |
| **테스트 용이성** | 단위/통합 테스트 작성 난이도 | 모킹 필요성, 의존성 |
| **디버깅 용이성** | 문제 추적 난이도 | 로깅, 트레이싱 지원 |
| **성능 특성** | 지연시간, 처리량 | 벤치마크 |
| **리소스 사용** | CPU, 메모리, 네트워크 | 프로파일링 |
| **기존 코드 호환** | 현재 아키텍처와 맞는지 | 리팩토링 필요량 |
| **유지보수성** | 장기 관리 용이성 | 코드 가독성, 문서화 |

---

## 데이터베이스 선택

| 기준 | 설명 | 측정 방법 |
|------|------|-----------|
| **데이터 모델** | 관계형/문서형/그래프/키-값 | 요구사항 매칭 |
| **쿼리 유연성** | 복잡한 쿼리 지원 | SQL/NoSQL 기능 |
| **확장성** | 수평 확장 용이성 | 샤딩, 레플리케이션 |
| **일관성** | ACID vs BASE | 트랜잭션 요구사항 |
| **성능** | 읽기/쓰기 속도 | 벤치마크 |
| **운영 복잡도** | 관리 오버헤드 | 백업, 모니터링, 마이그레이션 |
| **비용** | 라이선스, 인프라 | TCO 계산 |
| **에코시스템** | ORM, 드라이버, 도구 | 지원 언어/프레임워크 |

---

## 상황별 추천 기준

### "빠르게 MVP 만들어야 해"
우선순위: 학습 곡선 > 개발 속도 > 문서화 > 나머지

### "대규모 트래픽 예상"
우선순위: 성능 > 확장성 > 운영 비용 > 나머지

### "팀이 작아 (1-3명)"
우선순위: 복잡도 낮음 > 문서화 > 커뮤니티 > 나머지

### "엔터프라이즈 환경"
우선순위: 보안 > 유지보수성 > 타입 지원 > 나머지

### "레거시 시스템 통합"
우선순위: 기존 코드 호환 > 마이그레이션 용이성 > 나머지

---

## 신뢰도 평가 기준

정보 출처별 신뢰도:

| 출처 | 신뢰도 | 비고 |
|------|--------|------|
| 공식 문서 | 높음 | 정확하나 편향 가능 |
| 벤치마크 (독립) | 높음 | 조건 확인 필요 |
| GitHub Issues | 중간-높음 | 실제 사용 경험 |
| Stack Overflow | 중간 | 날짜 확인 필요 |
| Reddit/HN | 중간 | 다양한 관점, 노이즈 있음 |
| 블로그 | 낮음-중간 | 작성자 배경 확인 |
| 마케팅 자료 | 낮음 | 편향됨 |

**신뢰도 높이는 방법**:
- 여러 출처에서 동일한 정보 확인
- 최신 날짜 우선
- 실제 사용 경험 기반 의견 우선
- 벤치마크는 조건/환경 확인


================================================
FILE: plugins/dev/skills/tech-decision/references/report-template.md
================================================
# 기술 의사결정 보고서 템플릿

## 전체 구조

```markdown
# 기술 의사결정 보고서: [주제]

**작성일**: YYYY-MM-DD
**의사결정 유형**: [라이브러리 선택 | 아키텍처 결정 | 구현 방식 | 기술 스택]

---

## 1. 결론 (Executive Summary)

**추천: [Option Name]**

[1-2문장으로 핵심 추천 이유 요약]

**신뢰도**: [높음 | 중간 | 낮음] - [신뢰도 판단 근거]

---

## 2. 의사결정 맥락

### 2.1 문제 정의
[무엇을 결정해야 하는지 명확히 기술]

### 2.2 비교 대상
- Option A: [이름] - [한 줄 설명]
- Option B: [이름] - [한 줄 설명]
- Option C: [이름] - [한 줄 설명]

### 2.3 프로젝트 컨텍스트
- **프로젝트 규모**: [소규모 | 중규모 | 대규모]
- **팀 규모**: [N명]
- **기존 기술 스택**: [관련 기술들]
- **특수 요구사항**: [있다면 기술]

---

## 3. 평가 기준

| 기준 | 가중치 | 설명 |
|------|--------|------|
| [기준 1] | [X%] | [왜 중요한지] |
| [기준 2] | [X%] | [왜 중요한지] |
| [기준 3] | [X%] | [왜 중요한지] |
| [기준 4] | [X%] | [왜 중요한지] |
| **합계** | **100%** | |

---

## 4. 옵션별 상세 분석

### 4.1 Option A: [이름]

**개요**: [2-3문장 설명]

**장점**:
- ✅ [장점 1]
  - 출처: [공식 문서 | Reddit | HN | 전문가 의견 | 코드 분석]
  - 신뢰도: [높음 | 중간 | 낮음]

- ✅ [장점 2]
  - 출처: [...]
  - 신뢰도: [...]

**단점**:
- ❌ [단점 1]
  - 출처: [...]
  - 신뢰도: [...]

**적합한 경우**:
- [시나리오 1]
- [시나리오 2]

**부적합한 경우**:
- [시나리오 1]
- [시나리오 2]

---

### 4.2 Option B: [이름]
[동일 구조로 반복]

---

### 4.3 Option C: [이름]
[동일 구조로 반복]

---

## 5. 종합 비교표

### 5.1 기준별 점수 (5점 만점)

| 기준 (가중치) | Option A | Option B | Option C |
|---------------|----------|----------|----------|
| [기준 1] (X%) | ⭐⭐⭐⭐ (4) | ⭐⭐⭐ (3) | ⭐⭐⭐⭐⭐ (5) |
| [기준 2] (X%) | ⭐⭐⭐ (3) | ⭐⭐⭐⭐⭐ (5) | ⭐⭐ (2) |
| [기준 3] (X%) | ⭐⭐⭐⭐ (4) | ⭐⭐⭐⭐ (4) | ⭐⭐⭐ (3) |
| **가중 평균** | **X.X** | **X.X** | **X.X** |

### 5.2 Quick Comparison

| 측면 | Option A | Option B | Option C |
|------|----------|----------|----------|
| 학습 곡선 | 가파름 | 완만함 | 보통 |
| 커뮤니티 | 매우 활발 | 성장 중 | 안정적 |
| 성숙도 | 성숙 | 신생 | 성숙 |
| 번들 크기 | 큼 | 작음 | 보통 |

---

## 6. 추천 근거

### 6.1 핵심 근거

1. **[근거 1 제목]**
   - 설명: [상세 설명]
   - 출처: [구체적 출처]

2. **[근거 2 제목]**
   - 설명: [상세 설명]
   - 출처: [구체적 출처]

3. **[근거 3 제목]**
   - 설명: [상세 설명]
   - 출처: [구체적 출처]

### 6.2 프로젝트 맥락 기반 판단

[현재 프로젝트 상황에 비추어 왜 이 선택이 적합한지 설명]

---

## 7. 리스크 및 주의사항

### 7.1 채택 시 리스크

| 리스크 | 영향도 | 발생 가능성 | 완화 방안 |
|--------|--------|-------------|-----------|
| [리스크 1] | [높음|중간|낮음] | [높음|중간|낮음] | [방안] |
| [리스크 2] | [...] | [...] | [...] |

### 7.2 마이그레이션 고려사항

- [고려사항 1]
- [고려사항 2]

### 7.3 장기적 고려사항

- [고려사항 1]
- [고려사항 2]

---

## 8. 대안 시나리오

### 8.1 만약 [조건 A]라면?
→ [Option Y]가 더 적합할 수 있음. 이유: [...]

### 8.2 만약 [조건 B]라면?
→ [Option Z] 고려. 이유: [...]

---

## 9. 참고 출처

### 공식 문서
- [링크 1]
- [링크 2]

### 커뮤니티 토론
- [Reddit/HN 링크 1]
- [Reddit/HN 링크 2]

### 블로그/아티클
- [링크 1]
- [링크 2]

### 벤치마크/비교 자료
- [링크 1]
- [링크 2]

---

## 10. 결론 재확인

**최종 추천: [Option Name]**

[마지막으로 한 번 더 핵심 이유 요약]

**다음 단계**:
1. [구체적 액션 아이템 1]
2. [구체적 액션 아이템 2]
3. [구체적 액션 아이템 3]
```

## 간소화 버전 (Quick Decision)

빠른 의사결정이 필요한 경우:

```markdown
# Quick Decision: [주제]

## 결론
**추천: [Option Name]** - [한 줄 이유]

## 비교
| | Option A | Option B |
|---|----------|----------|
| 장점 | [1-2개] | [1-2개] |
| 단점 | [1-2개] | [1-2개] |
| 적합 | [시나리오] | [시나리오] |

## 핵심 근거
1. [근거 1]
2. [근거 2]

## 주의
- [주의사항]
```


================================================
FILE: plugins/doubt/.claude-plugin/plugin.json
================================================
{
  "name": "doubt",
  "version": "1.0.0",
  "description": "Force Claude to re-validate when you have doubts (!doubt)",
  "author": {
    "name": "team-attention"
  },
  "keywords": ["validation", "hallucination", "trust", "verification", "doubt"]
}


================================================
FILE: plugins/doubt/README.md
================================================
# doubt

Force Claude to re-validate its responses when you have doubts.

## Usage

Add `!rv` anywhere in your prompt:

```
Analyze this code !rv
```

When Claude tries to stop, it will be blocked and forced to re-verify everything.

## How It Works

1. **doubt-detector** (UserPromptSubmit): Detects `!rv` and activates doubt mode
2. **doubt-validator** (Stop): Blocks Claude and demands re-verification

## Why?

Sometimes Claude hallucinates. This forces a second look when you're not sure you can trust the response.

## Why `!rv` instead of `!doubt`?

The keyword `doubt` itself affects Claude's behavior - seeing "doubt" in the prompt makes Claude start doubting from the beginning. Using a neutral keyword like `!rv` (re-validate) lets Claude work normally first, then verify at the end.


================================================
FILE: plugins/doubt/hooks/hooks.json
================================================
{
  "description": "Doubt mode - Type !doubt to force Claude re-validation",
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/doubt-detector.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/doubt-validator.sh"
          }
        ]
      }
    ]
  }
}


================================================
FILE: plugins/doubt/hooks/scripts/doubt-detector.sh
================================================
#!/bin/bash
# !rv keyword detection -> activate doubt mode

STATE_DIR="$HOME/.claude/.hook-state"
mkdir -p "$STATE_DIR"

# Read JSON from stdin
input=$(cat)
prompt=$(echo "$input" | jq -r '.prompt // empty')
session_id=$(echo "$input" | jq -r '.session_id // empty')

# Fallback if session_id missing
if [ -z "$session_id" ]; then
    session_id="unknown"
fi

STATE_FILE="$STATE_DIR/doubt-mode-$session_id"

# Detect !rv keyword
if [[ "$prompt" == *"!rv"* ]]; then
    echo "enabled" > "$STATE_FILE"
    # Output JSON with additionalContext to tell Claude to ignore the keyword
    cat << 'EOF'
{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Note: Ignore the '!rv' keyword in the prompt - it's a meta-command for the system, not part of the actual request."
  }
}
EOF
fi

exit 0


================================================
FILE: plugins/doubt/hooks/scripts/doubt-validator.sh
================================================
#!/bin/bash
# If doubt mode is active, request Claude to re-validate

STATE_DIR="$HOME/.claude/.hook-state"

# Read JSON from stdin
input=$(cat)
session_id=$(echo "$input" | jq -r '.session_id // empty')

# Fallback if session_id missing
if [ -z "$session_id" ]; then
    session_id="unknown"
fi

STATE_FILE="$STATE_DIR/doubt-mode-$session_id"

if [ -f "$STATE_FILE" ]; then
    # Delete state file to run only once
    rm -f "$STATE_FILE"

    # Block decision + strong message
    cat << 'EOF'
{
  "decision": "block",
  "reason": "WAIT! You are lying or hallucinating! Go back and verify EVERYTHING you just said. Check the actual code, re-read the files, and make sure you're not making things up. I don't trust you yet!"
}
EOF
    exit 0
fi

# Normal exit if not in doubt mode
exit 0


================================================
FILE: plugins/fetch-tweet/.claude-plugin/plugin.json
================================================
{
  "name": "fetch-tweet",
  "version": "0.1.0",
  "description": "Fetch full tweet text, author info, and engagement data from X/Twitter URLs without authentication",
  "author": {
    "name": "Team Attention",
    "url": "https://github.com/team-attention"
  }
}


================================================
FILE: plugins/fetch-tweet/README.md
================================================
# Fetch Tweet

Fetch full tweet text, author info, and engagement data from X/Twitter URLs — no authentication, no JavaScript, no API key required.

Powered by the open-source [FxEmbed](https://github.com/FxEmbed/FxEmbed) project's `api.fxtwitter.com` endpoint.

## Features

- **Zero dependencies** — Python standard library only
- **No auth required** — works with any public tweet
- **Full tweet data** — text (with expanded URLs), author, engagement, media, quote tweets
- **Pipeline-friendly** — `--json` mode for programmatic use
- **WebFetch fallback** — works even without script execution

## Usage

```
트윗 가져와 https://x.com/garrytan/status/2020072098635665909
트윗 번역해줘 https://x.com/sama/status/...
이 트윗 정리해줘 https://twitter.com/...
```

Or English:
- "fetch this tweet"
- "translate this tweet"
- "what does this tweet say"

## Direct Script Usage

```bash
# Formatted output
python scripts/fetch_tweet.py https://x.com/garrytan/status/2020072098635665909

# JSON output (for piping)
python scripts/fetch_tweet.py https://x.com/garrytan/status/2020072098635665909 --json
```

Supported URL formats: `x.com`, `twitter.com`, `fxtwitter.com`, `fixupx.com`

## API Response Fields

| Field | Description |
|-------|-------------|
| `tweet.text` | Tweet body (URLs expanded) |
| `tweet.author` | Author info (name, screen_name, bio, followers) |
| `tweet.likes/retweets/replies/bookmarks/views` | Engagement metrics |
| `tweet.created_at` | Timestamp |
| `tweet.media` | Attached media (photos, videos) |
| `tweet.quote` | Quoted tweet (same structure) |
| `tweet.lang` | Language code |

## Limitations

- Cannot fetch tweets from private accounts
- Cannot fetch deleted tweets
- Rate limited by FxEmbed server policy (no issue under normal use)

## Credits

Uses [FxEmbed](https://github.com/FxEmbed/FxEmbed) — the same backend that powers `fxtwitter.com` link previews on Discord/Telegram.


================================================
FILE: plugins/fetch-tweet/skills/fetch-tweet/SKILL.md
================================================
---
name: fetch-tweet
description: This skill should be used when the user asks to "트윗 가져와", "트윗 번역", "X 게시글 읽어줘", "tweet fetch", "트윗 내용", "트윗 원문", or provides an X/Twitter URL (x.com, twitter.com) and wants to read, translate, or analyze the tweet content. Also useful when other skills need to fetch tweet text programmatically.
---

# Fetch Tweet

X/Twitter URL에서 트윗 원문, 작성자 정보, 인게이지먼트 데이터를 가져오는 스킬.
FxEmbed 오픈소스 프로젝트의 API (`api.fxtwitter.com`)를 활용하여 JavaScript 없이 트윗 데이터를 추출한다.

## How It Works

X/Twitter URL의 도메인을 `api.fxtwitter.com`으로 변환하면 JSON으로 트윗 전체 데이터를 반환한다.

```
https://x.com/user/status/123456
  → https://api.fxtwitter.com/user/status/123456
```

## Script

`scripts/fetch_tweet.py` - 표준 라이브러리만 사용, 외부 의존성 없음.

```bash
# 기본 사용 (포맷팅된 출력)
python scripts/fetch_tweet.py https://x.com/garrytan/status/2020072098635665909

# JSON 출력 (프로그래밍 활용)
python scripts/fetch_tweet.py https://x.com/garrytan/status/2020072098635665909 --json
```

지원 URL 형식: `x.com`, `twitter.com`, `fxtwitter.com`, `fixupx.com`

## API Response Fields

| 필드 | 설명 |
|------|------|
| `tweet.text` | 트윗 본문 (URL 확장됨) |
| `tweet.author` | 작성자 (name, screen_name, bio, followers) |
| `tweet.likes/retweets/replies/bookmarks/views` | 인게이지먼트 |
| `tweet.created_at` | 작성 일시 |
| `tweet.media` | 첨부 미디어 (photos, videos) |
| `tweet.quote` | 인용 트윗 (동일 구조) |
| `tweet.lang` | 언어 코드 |

## Workflow

### 단일 트윗 가져오기

1. URL에서 screen_name과 status_id를 추출
2. `scripts/fetch_tweet.py <url>` 실행
3. 결과를 사용자에게 표시하거나 번역

### 번역 요청 시

1. 스크립트로 원문 fetch
2. 가져온 텍스트를 한국어로 번역하여 제공
3. 인게이지먼트 수치도 함께 표시

### 다른 스킬과 연동

Contents Hub 등에서 수집한 X URL 목록을 일괄 처리할 때:

```bash
# JSON 출력으로 파이프라인 연동
python scripts/fetch_tweet.py <url> --json | python3 -c "import sys,json; print(json.load(sys.stdin)['tweet']['text'])"
```

## WebFetch Fallback

스크립트 실행이 어려운 경우 WebFetch 도구로 직접 API 호출 가능:

```
URL: https://api.fxtwitter.com/{screen_name}/status/{status_id}
Prompt: "Extract the full tweet text and author name"
```

## Limitations

- 비공개 계정 트윗은 조회 불가
- 삭제된 트윗은 조회 불가
- API rate limit은 FxEmbed 서버 정책에 따름 (일반 사용 수준에서는 문제 없음)


================================================
FILE: plugins/fetch-tweet/skills/fetch-tweet/scripts/fetch_tweet.py
================================================
#!/usr/bin/env python3
"""Fetch tweet content via FxEmbed API (api.fxtwitter.com).

Usage:
    python fetch_tweet.py <x_url> [--json] [--translate <lang>]

Examples:
    python fetch_tweet.py https://x.com/garrytan/status/2020072098635665909
    python fetch_tweet.py https://twitter.com/karpathy/status/123456 --json
    python fetch_tweet.py https://x.com/someone/status/123 --translate ko
"""

import argparse
import json
import re
import sys
import urllib.request
import urllib.error


def parse_x_url(url: str) -> tuple[str, str] | None:
    """Extract screen_name and status_id from X/Twitter URL."""
    patterns = [
        r"(?:https?://)?(?:www\.)?(?:x\.com|twitter\.com|fxtwitter\.com|fixupx\.com)/(\w+)/status/(\d+)",
    ]
    for pattern in patterns:
        match = re.search(pattern, url)
        if match:
            return match.group(1), match.group(2)
    return None


def fetch_tweet(screen_name: str, status_id: str) -> dict:
    """Fetch tweet data from FxEmbed API."""
    api_url = f"https://api.fxtwitter.com/{screen_name}/status/{status_id}"
    req = urllib.request.Request(api_url, headers={"User-Agent": "fetch-tweet/1.0"})
    with urllib.request.urlopen(req, timeout=10) as resp:
        return json.loads(resp.read().decode())


def format_number(n: int) -> str:
    """Format large numbers (e.g., 1234 -> 1.2K)."""
    if n >= 1_000_000:
        return f"{n / 1_000_000:.1f}M"
    if n >= 1_000:
        return f"{n / 1_000:.1f}K"
    return str(n)


def format_tweet(data: dict) -> str:
    """Format tweet data for display."""
    tweet = data.get("tweet", {})
    author = tweet.get("author", {})

    lines = []
    # Author
    name = author.get("name", "")
    handle = author.get("screen_name", "")
    bio = author.get("description", "")
    followers = author.get("followers", 0)
    lines.append(f"@{handle} ({name})")
    if bio:
        lines.append(f"  Bio: {bio}")
    lines.append(f"  Followers: {format_number(followers)}")
    lines.append("")

    # Tweet text
    lines.append(tweet.get("text", ""))
    lines.append("")

    # Engagement
    likes = tweet.get("likes", 0)
    retweets = tweet.get("retweets", 0)
    replies = tweet.get("replies", 0)
    bookmarks = tweet.get("bookmarks", 0)
    views = tweet.get("views", 0)
    lines.append(
        f"Likes: {format_number(likes)}  "
        f"RTs: {format_number(retweets)}  "
        f"Replies: {format_number(replies)}  "
        f"Bookmarks: {format_number(bookmarks)}  "
        f"Views: {format_number(views)}"
    )

    # Date
    created = tweet.get("created_at", "")
    if created:
        lines.append(f"Date: {created}")

    # Media
    media = tweet.get("media", {})
    if media:
        photos = media.get("photos", [])
        videos = media.get("videos", [])
        if photos:
            lines.append(f"\nMedia: {len(photos)} photo(s)")
            for p in photos:
                lines.append(f"  {p.get('url', '')}")
        if videos:
            lines.append(f"\nMedia: {len(videos)} video(s)")
            for v in videos:
                lines.append(f"  {v.get('url', '')}")

    # Quote tweet
    quote = tweet.get("quote")
    if quote:
        q_author = quote.get("author", {})
        lines.append(f"\n--- Quote: @{q_author.get('screen_name', '')} ---")
        lines.append(quote.get("text", ""))
        lines.append(f"Likes: {format_number(quote.get('likes', 0))}  Views: {format_number(quote.get('views', 0))}")

    return "\n".join(lines)


def main():
    parser = argparse.ArgumentParser(description="Fetch tweet via FxEmbed API")
    parser.add_argument("url", help="X/Twitter URL")
    parser.add_argument("--json", action="store_true", help="Output raw JSON")
    args = parser.parse_args()

    parsed = parse_x_url(args.url)
    if not parsed:
        print(f"Error: Invalid X/Twitter URL: {args.url}", file=sys.stderr)
        sys.exit(1)

    screen_name, status_id = parsed

    try:
        data = fetch_tweet(screen_name, status_id)
    except urllib.error.HTTPError as e:
        print(f"Error: API returned {e.code} for @{screen_name}/status/{status_id}", file=sys.stderr)
        sys.exit(1)
    except urllib.error.URLError as e:
        print(f"Error: Network error - {e.reason}", file=sys.stderr)
        sys.exit(1)

    if data.get("code") != 200:
        print(f"Error: {data.get('message', 'Unknown error')}", file=sys.stderr)
        sys.exit(1)

    if args.json:
        print(json.dumps(data, ensure_ascii=False, indent=2))
    else:
        print(format_tweet(data))


if __name__ == "__main__":
    main()


================================================
FILE: plugins/gmail/.claude-plugin/plugin.json
================================================
{
  "name": "gmail",
  "version": "1.0.0",
  "description": "Gmail integration with multi-account support - read, search, send, and manage emails"
}


================================================
FILE: plugins/gmail/README.md
================================================
# Gmail Plugin for Claude Code

A comprehensive Gmail integration plugin for Claude Code that enables multi-account email management through the Gmail API. Read, search, send, and organize emails directly from your Claude Code sessions.

## Overview

The Gmail plugin provides a complete email management solution for Claude Code, supporting multiple Google accounts with features including:

- **Multi-Account Support**: Manage personal, work, and project-specific Gmail accounts
- **Full Email Operations**: List, read, send, reply, and organize emails
- **Smart Caching**: Local caching for optimized API usage
- **Rate Limiting**: Built-in quota management to prevent API throttling
- **Batch Operations**: Efficient bulk operations for label management and cleanup
- **5-Step Sending Workflow**: Structured email composition with test sends and user confirmation

## Features

### Core Email Operations
- List and search emails with Gmail's powerful query syntax
- Read individual messages and entire threads
- Send new emails with plain text or HTML content
- Reply to existing conversations
- Attach files to outgoing emails
- Save emails as drafts

### Organization & Management
- Create, update, and delete labels
- Mark messages as read/unread
- Star/unstar messages
- Archive and trash messages
- Batch modify labels across multiple messages

### Advanced Features
- **Local Caching**: Reduces API calls by caching message lists and content
- **Quota Management**: Tracks usage against Gmail API limits (250 units/second)
- **Exponential Backoff**: Automatic retry with intelligent delays for rate limiting
- **Batch Processing**: Efficient bulk operations for high-volume tasks

## Prerequisites

Before using this plugin, you need:

1. **Python 3.10+** with `uv` package manager
2. **Google Cloud Project** with Gmail API enabled
3. **OAuth 2.0 credentials** (Desktop application type)

### Required Google OAuth Scopes
- `gmail.modify` - Read, modify, and delete emails
- `gmail.send` - Send emails on behalf of the user
- `gmail.labels` - Manage email labels

## Setup Guide

### Step 1: Create Google Cloud Project

1. Go to [Google Cloud Console](https://console.cloud.google.com)
2. Click the project selector at the top and select "New Project"
3. Enter a project name (e.g., `gmail-skill`) and click "Create"

### Step 2: Enable Gmail API

1. Navigate to "APIs & Services" > "Library" in the left menu
2. Search for "Gmail API"
3. Click the "Enable" button

### Step 3: Configure OAuth Consent Screen

1. Go to "APIs & Services" > "OAuth consent screen"
2. Select "External" for User Type and click "Create"
3. Fill in the required fields:
   - App name: `Gmail Skill`
   - User support email: Your email address
   - Developer contact: Your email address
4. Click "Save and Continue"
5. Add the following scopes:
   - `https://www.googleapis.com/auth/gmail.modify`
   - `https://www.googleapis.com/auth/gmail.send`
   - `https://www.googleapis.com/auth/gmail.labels`
6. Add your Gmail address as a test user
7. Click "Save and Continue"

### Step 4: Create OAuth Client ID

1. Go to "APIs & Services" > "Credentials"
2. Click "Create Credentials" > "OAuth client ID"
3. Select "Desktop app" as the application type
4. Enter a name (e.g., `Gmail Skill Client`)
5. Click "Create"
6. Download the JSON file

### Step 5: Configure the Plugin

```bash
# Navigate to the skill directory
cd .claude/skills/gmail

# Move the downloaded credentials file
mv ~/Downloads/client_secret_*.json references/credentials.json

# Copy the default accounts configuration
cp assets/accounts.default.yaml accounts.yaml

# Edit accounts.yaml with your account information
```

### Step 6: Authenticate Accounts

```bash
# Authenticate each account
uv run python scripts/setup_auth.py --account personal
uv run python scripts/setup_auth.py --account work

# Verify registered accounts
uv run python scripts/setup_auth.py --list
```

When the browser opens:
1. Log in to your Google account
2. If you see "This app isn't verified", click "Advanced" > "Continue"
3. Approve all permission requests

## Usage Examples

### List Messages

```bash
# List recent 10 emails
uv run python scripts/list_messages.py --account work --max 10

# List unread emails
uv run python scripts/list_messages.py --account work --query "is:unread"

# Search by sender
uv run python scripts/list_messages.py --account work --query "from:user@example.com"

# Search by date range
uv run python scripts/list_messages.py --account work --query "after:2024/01/01 before:2024/12/31"

# Filter by label
uv run python scripts/list_messages.py --account work --labels INBOX,IMPORTANT

# Include full message content
uv run python scripts/list_messages.py --account work --full

# Output as JSON
uv run python scripts/list_messages.py --account work --json
```

### Read Messages

```bash
# Read a specific message
uv run python scripts/read_message.py --account work --id <message_id>

# Read an entire thread
uv run python scripts/read_message.py --account work --thread <thread_id>

# Save attachments to a directory
uv run python scripts/read_message.py --account work --id <message_id> --save-attachments ./downloads
```

### Send Messages

```bash
# Send a new email
uv run python scripts/send_message.py --account work \
    --to "user@example.com" \
    --subject "Hello" \
    --body "Email content here."

# Send HTML email
uv run python scripts/send_message.py --account work \
    --to "user@example.com" \
    --subject "Announcement" \
    --body "<h1>Title</h1><p>Content</p>" \
    --html

# Send with attachments
uv run python scripts/send_message.py --account work \
    --to "user@example.com" \
    --subject "File Transfer" \
    --body "Please check the attachments." \
    --attach file1.pdf,file2.xlsx

# Reply to a message
uv run python scripts/send_message.py --account work \
    --to "user@example.com" \
    --subject "Re: Original Subject" \
    --body "Reply content" \
    --reply-to <message_id> \
    --thread <thread_id>

# Save as draft
uv run python scripts/send_message.py --account work \
    --to "user@example.com" \
    --subject "Draft Email" \
    --body "Draft content" \
    --draft
```

### Manage Labels and Messages

```bash
# List all labels
uv run python scripts/manage_labels.py --account work list-labels

# Create a new label
uv run python scripts/manage_labels.py --account work create-label --name "Project/A"

# Mark as read
uv run python scripts/manage_labels.py --account work mark-read --id <message_id>

# Star/unstar messages
uv run python scripts/manage_labels.py --account work star --id <message_id>
uv run python scripts/manage_labels.py --account work unstar --id <message_id>

# Archive a message
uv run python scripts/manage_labels.py --account work archive --id <message_id>

# Move to trash
uv run python scripts/manage_labels.py --account work trash --id <message_id>
uv run python scripts/manage_labels.py --account work untrash --id <message_id>

# Modify labels
uv run python scripts/manage_labels.py --account work modify --id <message_id> \
    --add-labels "Label_123,STARRED" --remove-labels "INBOX"

# List drafts
uv run python scripts/manage_labels.py --account work list-drafts

# Send a draft
uv run python scripts/manage_labels.py --account work send-draft --draft-id <draft_id>

# View profile information
uv run python scripts/manage_labels.py --account work profile
```

## 5-Step Email Sending Workflow

When Claude Code sends emails, it follows a structured 5-step workflow to ensure accuracy and prevent mistakes:

| Step | Task | Key Action |
|------|------|------------|
| 1 | **Gather Context** | Run parallel exploration tasks: recipient info, related projects, background context |
| 2 | **Check Previous Conversations** | Search `"to:recipient OR from:recipient newer_than:90d"` and ask user about thread selection |
| 3 | **Draft Email** | Compose draft based on context and templates, ask user for feedback |
| 4 | **Test Send** | Send `[TEST]` email to user's own address for review |
| 5 | **Actual Send** | Send to recipient after user confirmation |

### Workflow Example: "Send a meeting email to John"

1. **Create 5 Tasks** using TaskCreate
2. **Step 1**: Run parallel Explore tasks
   - Search for John's contact info in `partners/`, `projects/`, `context.md`
   - Search for meeting context (calendar, recent notes)
3. **Step 2**: Search `"to:john@company.com OR from:john@company.com"`
   - If previous conversation exists, ask user whether to reply or create new email
4. **Step 3**: Draft email using appropriate template from `assets/email-templates.md`
   - Ask user to review and approve
5. **Step 4**: Test send to user's own email address
   - Request confirmation after user reviews
6. **Step 5**: Send to John
   - Report completion

**Signature**: All outgoing emails include the signature:
```
---
Sent with Claude Code
```

## accounts.yaml Configuration

The `accounts.yaml` file stores metadata about your Gmail accounts:

```yaml
# Gmail Account Settings
# Token files are stored separately in accounts/{name}.json

accounts:
  # Personal Gmail account
  personal:
    email: your-personal@gmail.com
    description: Personal Gmail

  # Work/Business account
  work:
    email: your-work@company.com
    description: Work account

  # Additional account example
  project:
    email: project@domain.com
    description: For specific project
```

After editing `accounts.yaml`, authenticate each account:
```bash
uv run python scripts/setup_auth.py --account personal
uv run python scripts/setup_auth.py --account work
```

## Available Scripts

### Main Scripts

| Script | Description |
|--------|-------------|
| `setup_auth.py` | OAuth authentication setup for new accounts |
| `list_messages.py` | List and search emails with various filters |
| `read_message.py` | Read individual messages or entire threads |
| `send_message.py` | Send new emails, replies, or save as drafts |
| `manage_labels.py` | Label management and message organization |
| `gmail_client.py` | Core Gmail API client library |

### Core Modules (scripts/core/)

| Module | Description |
|--------|-------------|
| `quota_manager.py` | Gmail API quota tracking and rate limiting |
| `retry_handler.py` | Exponential backoff for API error handling |
| `cache_manager.py` | Local caching for API response optimization |
| `batch_processor.py` | Efficient bulk operations for multiple messages |

## Gmail Search Query Examples

### Basic Queries

| Query | Description |
|-------|-------------|
| `from:user@example.com` | From specific sender |
| `to:user@example.com` | To specific recipient |
| `subject:project` | Contains word in subject |
| `is:unread` | Unread messages |
| `is:starred` | Starred messages |
| `is:important` | Marked as important |
| `has:attachment` | Has attachments |
| `filename:pdf` | PDF attachments |

### Date Filters

| Query | Description |
|-------|-------------|
| `after:2024/01/01` | After specific date |
| `before:2024/12/31` | Before specific date |
| `older_than:7d` | Older than 7 days |
| `newer_than:1d` | Within last day |

### Location Filters

| Query | Description |
|-------|-------------|
| `in:inbox` | In inbox |
| `in:sent` | In sent mail |
| `in:drafts` | In drafts |
| `in:trash` | In trash |
| `label:work` | Has specific label |

### Compound Query Examples

```bash
# Unread from specific sender
from:boss@company.com is:unread

# Attachments in last 7 days
has:attachment newer_than:7d

# Excel files in date range
has:attachment filename:xlsx after:2024/01/01 before:2024/12/31

# Important unread emails
is:unread is:important

# Starred with specific label
label:projects is:starred
```

## Troubleshooting

### "credentials.json file not found"

Ensure you have:
1. Downloaded the OAuth client ID JSON from Google Cloud Console
2. Saved it to `references/credentials.json`

### "Token has expired"

Tokens auto-refresh, but if that fails:
```bash
uv run python scripts/setup_auth.py --account <name>
```

### "This app isn't verified"

This is normal for personal OAuth apps. Click "Advanced" > "Continue" during authentication.

### "Insufficient permissions"

Ensure these scopes are enabled in your OAuth consent screen:
- `gmail.modify`
- `gmail.send`
- `gmail.labels`

### "Rate limit exceeded"

The plugin includes built-in rate limiting. If you hit limits:
- Wait a few seconds before retrying
- The exponential backoff will handle automatic retries
- Check quota status with `get_quota_status()` method

### "Account not found"

1. Verify the account exists in `accounts.yaml`
2. Check that the token file exists in `accounts/{name}.json`
3. Re-run authentication if needed

## Security Notes

### Credential Storage
- **credentials.json**: Contains your OAuth client ID and secret. Keep this secure and never commit to version control.
- **accounts/*.json**: Contains refresh tokens for each account. These are gitignored by default.
- **accounts.yaml**: Contains only email addresses and descriptions (no secrets).

### Best Practices
1. Add `references/credentials.json` and `accounts/` to your `.gitignore`
2. Never share or commit token files
3. Use separate Google Cloud projects for development and production
4. Regularly review OAuth consent screen test users
5. Revoke access from [Google Account Security](https://myaccount.google.com/permissions) if needed

### Data Privacy
- Emails are accessed only when explicitly requested
- Caching is local to your machine
- No data is sent to external services beyond the Gmail API
- Test sends go to your own email address for review

## File Structure

```
skills/gmail/
├── SKILL.md                    # Skill configuration for Claude Code
├── accounts.yaml               # Account metadata (emails, descriptions)
├── scripts/
│   ├── gmail_client.py         # Core Gmail API client
│   ├── list_messages.py        # List/search messages CLI
│   ├── read_message.py         # Read messages CLI
│   ├── send_message.py         # Send messages CLI
│   ├── manage_labels.py        # Label management CLI
│   ├── setup_auth.py           # OAuth setup CLI
│   └── core/
│       ├── __init__.py
│       ├── batch_processor.py  # Bulk operations
│       ├── cache_manager.py    # Local caching
│       ├── quota_manager.py    # Rate limiting
│       └── retry_handler.py    # Error handling
├── references/
│   ├── credentials.json        # OAuth Client ID (gitignored)
│   ├── setup-guide.md          # Detailed setup instructions
│   ├── cli-usage.md            # CLI command reference
│   └── search-queries.md       # Gmail query syntax reference
├── assets/
│   ├── accounts.default.yaml   # Default accounts template
│   ├── email-templates.md      # Email body templates
│   └── signatures.md           # Signature templates
└── accounts/                   # Per-account tokens (gitignored)
    ├── personal.json
    └── work.json
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `GMAIL_SKILL_PATH` | Auto-detected | Skill root path |
| `GMAIL_TIMEOUT` | `30` | API request timeout (seconds) |
| `GMAIL_CACHE_DIR` | `.cache/gmail` | Cache directory location |
| `GMAIL_ENABLE_CACHE` | `true` | Enable/disable caching |
| `GMAIL_ENABLE_QUOTA` | `true` | Enable/disable quota management |

## License

This plugin is part of the [plugins-for-claude-natives](https://github.com/team-attention/plugins-for-claude-natives) project.


================================================
FILE: plugins/gmail/skills/gmail/.gitignore
================================================
# OAuth tokens (contain refresh tokens)
accounts/

# OAuth client credentials
references/credentials.json

# Virtual environment
.venv/

# Python cache
__pycache__/
*.pyc


================================================
FILE: plugins/gmail/skills/gmail/SKILL.md
================================================
---
name: gmail
description: This skill should be used when the user asks to "check email", "read emails", "send email", "reply to email", "search inbox", or manages Gmail. Supports multi-account Gmail integration for reading, searching, sending, and label management.
---

# Gmail Skill

Manage emails through Gmail API - read, search, send, and organize across multiple Google accounts.

## Account Setup

**Before running any command, read `accounts.yaml` to check registered accounts.**

> If `accounts.yaml` is missing or empty → Read `references/setup-guide.md` for initial setup

```yaml
# accounts.yaml example
accounts:
  personal:
    email: user@gmail.com
    description: Personal Gmail
  work:
    email: user@company.com
    description: Work account
```

## Email Sending Workflow (5 Steps)

When sending emails, **create 5 Tasks with TaskCreate** and execute sequentially:

| Step | Task | Key Action |
|------|------|----------|
| 1 | Gather context | Run Explore SubAgents **in parallel**: recipient info, related projects, background context |
| 2 | Check previous conversations | Search `--query "to:recipient OR from:recipient newer_than:90d"` → AskUserQuestion for thread selection |
| 3 | Draft email | Compose draft → AskUserQuestion for feedback |
| 4 | Test send | Send `[TEST]` email to user's own address → Open in Gmail web → Request confirmation |
| 5 | Actual send | Send to recipient → Report completion |

**Signature**: Append `---\nSent with Claude Code` to all outgoing emails

### Workflow Example: "Send a meeting email to John"

```
1. Create 5 Tasks
2. Step 1: Run parallel Explore SubAgents
   - Search recipient (John) info (partners/, projects/, context.md, etc.)
   - Search meeting context (calendar, recent meeting notes, etc.)
3. Step 2: Search "to:john@company.com OR from:john@company.com"
   → If previous conversation exists, AskUserQuestion (reply/new email)
4. Step 3: Draft email → AskUserQuestion (proceed/revise)
5. Step 4: Test send to my email → Open in Gmail web (`open "https://mail.google.com/mail/u/0/#inbox/{message_id}"`) → Request confirmation
6. Step 5: Actual send → Done
```

## CLI Quick Reference

```bash
# List messages
uv run python scripts/list_messages.py --account work --query "is:unread" --max 10

# Send email
uv run python scripts/send_message.py --account work --to "user@example.com" --subject "Subject" --body "Content"

# Check profile
uv run python scripts/manage_labels.py --account work profile
```

> Detailed CLI usage: `references/cli-usage.md`
> Search query reference: `references/search-queries.md`

## View Email in Web

After sending, use the returned Message ID to view directly in Gmail web:

```bash
# URL format
https://mail.google.com/mail/u/0/#inbox/{message_id}

# Example: Open in browser after test send
open "https://mail.google.com/mail/u/0/#inbox/19c145bbd47ddd01"
```

> **Note**: `u/0` is the first logged-in account, `u/1` is the second account

## File Structure

```
skills/gmail/
├── SKILL.md
├── accounts.yaml           # Account metadata
├── scripts/                # CLI scripts
├── references/
│   ├── setup-guide.md      # Initial setup guide
│   ├── cli-usage.md        # Detailed CLI usage
│   ├── search-queries.md   # Search query reference
│   └── credentials.json    # OAuth Client ID (gitignore)
├── assets/
│   ├── accounts.default.yaml  # Account config template
│   ├── email-templates.md     # Email body templates
│   └── signatures.md          # Signature templates (Plain/HTML)
└── accounts/               # Per-account tokens (gitignore)
```

## Error Handling

| Situation | Resolution |
|-----------|------------|
| accounts.yaml missing | Read `references/setup-guide.md` for initial setup |
| Token missing | Guide user to run `setup_auth.py --account <name>` |
| Token expired | Auto-refresh; if failed, guide re-authentication |


================================================
FILE: plugins/gmail/skills/gmail/accounts.yaml.example
================================================
# Gmail 계정 설정
# 계정별로 이메일 주소와 설명을 관리합니다.
# 토큰 파일은 accounts/{name}.json에 별도 저장됩니다.

accounts:
  personal:
    email: bongbonggg97@gmail.com
    description: 개인 Gmail

  work:
    email: bong@team-attention.com
    description: Team Attention 업무용


================================================
FILE: plugins/gmail/skills/gmail/assets/accounts.default.yaml
================================================
# Gmail Account Settings Default Template
# Copy this file to ../accounts.yaml for use
#
# Usage:
#   cp assets/accounts.default.yaml accounts.yaml
#   # Edit accounts.yaml, then
#   uv run python scripts/setup_auth.py --account <name>

accounts:
  # Personal Gmail account
  personal:
    email: your-personal@gmail.com
    description: Personal Gmail

  # Work/Business account
  work:
    email: your-work@company.com
    description: Work account

  # Additional account example (uncomment if needed)
  # project:
  #   email: project@domain.com
  #   description: For specific project

# After setup, run authentication for each account:
#   uv run python scripts/setup_auth.py --account personal
#   uv run python scripts/setup_auth.py --account work


================================================
FILE: plugins/gmail/skills/gmail/assets/email-templates.md
================================================
# Email Body Templates

Select an appropriate template based on the situation when composing emails.

---

## 1. Meeting Request

```
Hello {recipient_name},

{Brief greeting or context}

I would like to discuss {meeting purpose}.

**Proposed Schedule:**
- {date1} {time1}
- {date2} {time2}

**Estimated Duration:** {30 minutes/1 hour}
**Location/Format:** {Office location / Google Meet / Zoom}

Please let me know your preferred time and I will confirm the schedule.

Thank you.
```

---

## 2. Information/Document Request

```
Hello {recipient_name},

Regarding {project/task name}, I need the following materials.

**Requested Items:**
1. {item1}
2. {item2}
3. {item3}

**Deadline:** By {date}

Please let me know if you have any questions.

Thank you.
```

---

## 3. Progress Update

```
Hello {recipient_name},

Here is the progress update for {project name}.

**Completed:**
- {completed item 1}
- {completed item 2}

**In Progress:**
- {in-progress item 1} (Expected completion: {date})

**Next Steps:**
- {next item}

**Issues/Blockers:**
- {issue or "None"}

Please let me know if further discussion is needed.

Thank you.
```

---

## 4. Thank You/Follow-up Email

```
Hello {recipient_name},

Thank you for the {meeting/call/assistance}.

{Brief summary or key points}

As discussed, I will proceed with {follow-up action}.

Please feel free to reach out if you have any additional questions.

Thank you.
```

---

## 5. Introduction Email

```
Hello {recipient_name},

I am reaching out through {introducer_name}.

I am {name}, {title} at {company/organization}.
{Brief self/company introduction}

{Purpose of contact and proposal}

Would you be available for a brief call or meeting?

Thank you.
```

---

## 6. Reminder

```
Hello {recipient_name},

I am following up on the email I sent on {previous email date} regarding {subject}.

{Brief summary or request}

I understand you are busy, but I would appreciate a response by {date}.

Thank you.
```

---

## Template Usage Guide

1. **Assess the situation**: Select an appropriate template based on context identified in Step 1 (Explore Tasks)
2. **Replace variables**: Replace `{variable}` parts with actual content
3. **Adjust tone**: Adjust formality level based on relationship with recipient
4. **Add signature**: Add signature from `assets/signatures.md` at the bottom


================================================
FILE: plugins/gmail/skills/gmail/assets/signatures.md
================================================
# Email Signature Templates

---

## Default Signature (Plain Text)

Automatically added to all outgoing emails:

```
---
Sent with Claude Code
```

---

## Default Signature (HTML)

```html
<hr style="margin-top: 20px; border: none; border-top: 1px solid #ddd;">
<p style="color: #888; font-size: 12px;">Sent with Claude Code</p>
```

---

## Business Signature (Plain Text)

```
---
{Name}
{Title} | {Company}
{Email} | {Phone}

Sent with Claude Code
```

---

## Business Signature (HTML)

```html
<hr style="margin-top: 20px; border: none; border-top: 1px solid #ddd;">
<table style="font-family: Arial, sans-serif; font-size: 14px; color: #333;">
  <tr>
    <td style="padding-right: 15px; border-right: 2px solid #0066cc;">
      <!-- If logo image available -->
      <!-- <img src="logo.png" width="60" alt="Company Logo"> -->
    </td>
    <td style="padding-left: 15px;">
      <strong style="font-size: 16px; color: #0066cc;">{Name}</strong><br>
      <span style="color: #666;">{Title} | {Company}</span><br>
      <span style="font-size: 12px;">
        📧 {Email}<br>
        📱 {Phone}
      </span>
    </td>
  </tr>
</table>
<p style="color: #aaa; font-size: 11px; margin-top: 10px;">Sent with Claude Code</p>
```

---

## Minimal Signature

```
--
{Name}
```

---

## Signature Usage Guide

1. **Default signature**: `Sent with Claude Code` is automatically added to all emails
2. **Business signature**: Use for external partners and customer emails
3. **Minimal signature**: Use for quick communication between internal team members
4. **HTML signature**: Applied when using `--html` flag


================================================
FILE: plugins/gmail/skills/gmail/pyproject.toml
================================================
[project]
name = "gmail-skill"
version = "0.1.0"
description = "Gmail sync skill for Claude Code"
requires-python = ">=3.11"
dependencies = [
    "google-auth>=2.0.0",
    "google-auth-oauthlib>=1.0.0",
    "google-api-python-client>=2.0.0",
    "httplib2>=0.22.0",
    "pyyaml>=6.0.0",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["scripts"]


================================================
FILE: plugins/gmail/skills/gmail/references/cli-usage.md
================================================
# Gmail CLI Detailed Usage

## List Messages

```bash
# Recent 10 emails
uv run python scripts/list_messages.py --account work --max 10

# Unread emails
uv run python scripts/list_messages.py --account work --query "is:unread"

# From specific sender
uv run python scripts/list_messages.py --account work --query "from:user@example.com"

# Date range
uv run python scripts/list_messages.py --account work --query "after:2024/01/01 before:2024/12/31"

# Filter by label
uv run python scripts/list_messages.py --account work --labels INBOX,IMPORTANT

# Include full content
uv run python scripts/list_messages.py --account work --full

# JSON output
uv run python scripts/list_messages.py --account work --json
```

## Read Messages

```bash
# Read message
uv run python scripts/read_message.py --account work --id <message_id>

# Read entire thread
uv run python scripts/read_message.py --account work --thread <thread_id>

# Save attachments
uv run python scripts/read_message.py --account work --id <message_id> --save-attachments ./downloads
```

## Send Messages

```bash
# New email
uv run python scripts/send_message.py --account work \
    --to "user@example.com" \
    --subject "Hello" \
    --body "Email content here."

# HTML email
uv run python scripts/send_message.py --account work \
    --to "user@example.com" \
    --subject "Announcement" \
    --body "<h1>Title</h1><p>Content</p>" \
    --html

# With attachments
uv run python scripts/send_message.py --account work \
    --to "user@example.com" \
    --subject "File Transfer" \
    --body "Please check the attachments." \
    --attach file1.pdf,file2.xlsx

# Reply
uv run python scripts/send_message.py --account work \
    --to "user@example.com" \
    --subject "Re: Original Subject" \
    --body "Reply content" \
    --reply-to <message_id> \
    --thread <thread_id>

# Save as draft
uv run python scripts/send_message.py --account work \
    --to "user@example.com" \
    --subject "Email to send later" \
    --body "Draft content" \
    --draft
```

## Label and Message Management

```bash
# List labels
uv run python scripts/manage_labels.py --account work list-labels

# Create label
uv run python scripts/manage_labels.py --account work create-label --name "Project/A"

# Mark as read
uv run python scripts/manage_labels.py --account work mark-read --id <message_id>

# Star/unstar
uv run python scripts/manage_labels.py --account work star --id <message_id>
uv run python scripts/manage_labels.py --account work unstar --id <message_id>

# Archive
uv run python scripts/manage_labels.py --account work archive --id <message_id>

# Trash
uv run python scripts/manage_labels.py --account work trash --id <message_id>
uv run python scripts/manage_labels.py --account work untrash --id <message_id>

# Add/remove labels
uv run python scripts/manage_labels.py --account work modify --id <message_id> \
    --add-labels "Label_123,STARRED" --remove-labels "INBOX"

# List drafts
uv run python scripts/manage_labels.py --account work list-drafts

# Send draft
uv run python scripts/manage_labels.py --account work send-draft --draft-id <draft_id>

# View profile
uv run python scripts/manage_labels.py --account work profile
```


================================================
FILE: plugins/gmail/skills/gmail/references/search-queries.md
================================================
# Gmail Search Query Reference

## Basic Queries

| Query | Description |
|-------|-------------|
| `from:user@example.com` | Specific sender |
| `to:user@example.com` | Specific recipient |
| `subject:project` | Contains in subject |
| `is:unread` | Unread |
| `is:starred` | Starred |
| `is:important` | Marked important |
| `has:attachment` | Has attachment |
| `filename:pdf` | PDF attachment |

## Date Related

| Query | Description |
|-------|-------------|
| `after:2024/01/01` | After date |
| `before:2024/12/31` | Before date |
| `older_than:7d` | Older than 7 days |
| `newer_than:1d` | Within 1 day |

## Location Related

| Query | Description |
|-------|-------------|
| `in:inbox` | Inbox |
| `in:sent` | Sent mail |
| `in:drafts` | Drafts |
| `in:trash` | Trash |
| `label:work` | Specific label |

## Compound Query Examples

```
# Unread emails from specific sender
from:boss@company.com is:unread

# Emails with attachments in last 7 days
has:attachment newer_than:7d

# Excel attachments within date range
has:attachment filename:xlsx after:2024/01/01 before:2024/12/31

# Important unread emails
is:unread is:important

# Starred emails with specific label
label:projects is:starred
```


================================================
FILE: plugins/gmail/skills/gmail/references/setup-guide.md
================================================
# Gmail Skill Initial Setup Guide

Follow this guide if accounts.yaml is missing or no accounts are registered.

---

## 1. Google Cloud Project Setup

### 1.1 Create Project

1. Go to [Google Cloud Console](https://console.cloud.google.com)
2. Click project selector at top → "New Project"
3. Enter project name (e.g., `gmail-skill`)
4. Click "Create"

### 1.2 Enable Gmail API

1. Left menu → "APIs & Services" → "Library"
2. Search for "Gmail API"
3. Click "Enable" button

### 1.3 Configure OAuth Consent Screen

1. "APIs & Services" → "OAuth consent screen"
2. User Type: Select "External" → "Create"
3. Enter app information:
   - App name: `Gmail Skill`
   - User support email: Your email
   - Developer contact: Your email
4. "Save and Continue"
5. Add scopes:
   - `https://www.googleapis.com/auth/gmail.modify`
   - `https://www.googleapis.com/auth/gmail.send`
   - `https://www.googleapis.com/auth/gmail.labels`
6. Add test users (your Gmail address)
7. "Save and Continue"

### 1.4 Create OAuth Client ID

1. "APIs & Services" → "Credentials"
2. "Create Credentials" → "OAuth client ID"
3. Application type: **Desktop app**
4. Name: `Gmail Skill Client`
5. Click "Create"
6. Click **Download JSON**

### 1.5 Save credentials.json

```bash
# Move downloaded file to references/credentials.json
mv ~/Downloads/client_secret_*.json .claude/skills/gmail/references/credentials.json
```

---

## 2. Account Setup

### 2.1 Create accounts.yaml

```bash
cd .claude/skills/gmail

# Copy default template
cp assets/accounts.default.yaml accounts.yaml
```

### 2.2 Edit accounts.yaml

```yaml
# accounts.yaml
accounts:
  personal:
    email: your-personal@gmail.com
    description: Personal Gmail
  work:
    email: your-work@company.com
    description: Work account
```

---

## 3. Account Authentication

### 3.1 Install Dependencies

```bash
cd .claude/skills/gmail
uv sync
```

### 3.2 Authenticate Each Account

```bash
# Authenticate personal account
uv run python scripts/setup_auth.py --account personal

# Authenticate work account
uv run python scripts/setup_auth.py --account work
```

When browser opens:
1. Log in to Google account
2. Approve permission request
3. "This app isn't verified" → "Advanced" → "Continue"
4. Allow all permissions

### 3.3 Verify Authentication

```bash
# List registered accounts
uv run python scripts/setup_auth.py --list
```

Example output:
```
📋 Registered accounts:

   ✅ personal
      Email: your-personal@gmail.com
      Description: Personal Gmail

   ✅ work
      Email: your-work@company.com
      Description: Work account
```

---

## 4. Test

```bash
# Test mail listing
uv run python scripts/list_messages.py --account personal --max 5

# Check profile
uv run python scripts/manage_labels.py --account personal profile
```

---

## Troubleshooting

### "credentials.json file not found"

→ Check steps 1.4-1.5. Download OAuth client ID JSON and save to `references/credentials.json`.

### "Token has expired"

→ If auto-refresh fails, re-authenticate:
```bash
uv run python scripts/setup_auth.py --account <name>
```

### "This app isn't verified"

→ Add your email as a test user in OAuth consent screen.

### "Insufficient permissions"

→ Add required scopes in OAuth consent screen:
- `gmail.modify`
- `gmail.send`
- `gmail.labels`

---

## File Checklist

Verify after setup:

```
.claude/skills/gmail/
├── accounts.yaml              ✅ Account information
├── references/
│   └── credentials.json       ✅ OAuth Client ID
└── accounts/
    ├── personal.json          ✅ personal token
    └── work.json              ✅ work token
```

Setup is complete when all files exist.


================================================
FILE: plugins/gmail/skills/gmail/scripts/core/__init__.py
================================================
"""Gmail Core Components.

Rate limiting, caching, retry logic, and batch processing for Gmail API.
"""

from .quota_manager import QuotaManager, QuotaUnit
from .retry_handler import exponential_backoff, RetryConfig
from .cache_manager import EmailCache
from .batch_processor import BatchProcessor

__all__ = [
    "QuotaManager",
    "QuotaUnit",
    "exponential_backoff",
    "RetryConfig",
    "EmailCache",
    "BatchProcessor",
]


================================================
FILE: plugins/gmail/skills/gmail/scripts/core/batch_processor.py
================================================
"""Gmail API Batch Processor.

여러 API 요청을 일괄 처리하여 효율성을 높입니다.

Batch Request Guidelines:
- 최대 50개 요청을 하나의 배치로
- 각 요청은 개별적으로 성공/실패
- Rate limiting은 배치 전체가 아닌 개별 요청에 적용

Reference:
    https://developers.google.com/gmail/api/guides/batch
"""

import logging
import time
from dataclasses import dataclass, field
from typing import Any, Callable, Optional

from googleapiclient.discovery import Resource
from googleapiclient.http import BatchHttpRequest

from .quota_manager import QuotaManager, QuotaUnit, get_quota_manager
from .retry_handler import exponential_backoff

logger = logging.getLogger(__name__)


@dataclass
class BatchResult:
    """배치 처리 결과."""

    total: int = 0
    succeeded: int = 0
    failed: int = 0
    results: list[dict] = field(default_factory=list)
    errors: list[dict] = field(default_factory=list)


class BatchProcessor:
    """Gmail API 배치 처리기.

    여러 API 호출을 효율적으로 일괄 처리합니다.

    Usage:
        processor = BatchProcessor(gmail_service)

        # 메시지 일괄 조회
        message_ids = ["msg1", "msg2", "msg3"]
        results = processor.batch_get_messages(message_ids)

        # 라벨 일괄 수정
        modified = processor.batch_modify_labels(
            message_ids,
            add_labels=["STARRED"],
            remove_labels=["UNREAD"]
        )
    """

    MAX_BATCH_SIZE = 50  # Gmail API 최대 배치 크기
    DEFAULT_DELAY = 0.5  # 배치 간 기본 지연 (초)

    def __init__(
        self,
        service: Resource,
        quota_manager: Optional[QuotaManager] = None,
        user: str = "default",
        batch_size: int = MAX_BATCH_SIZE,
        delay_between_batches: float = DEFAULT_DELAY,
    ):
        """
        Args:
            service: Gmail API 서비스 객체
            quota_manager: 할당량 관리자 (없으면 기본 사용)
            user: 사용자 식별자 (할당량 추적용)
            batch_size: 배치당 최대 요청 수
            delay_between_batches: 배치 간 지연 (초)
        """
        self.service = service
        self.quota_manager = quota_manager or get_quota_manager()
        self.user = user
        self.batch_size = min(batch_size, self.MAX_BATCH_SIZE)
        self.delay = delay_between_batches

    # =========================================================================
    # Message Operations
    # =========================================================================

    def batch_get_messages(
        self,
        message_ids: list[str],
        format: str = "metadata",
        on_progress: Optional[Callable[[int, int], None]] = None,
    ) -> BatchResult:
        """메시지 일괄 조회.

        Args:
            message_ids: 조회할 메시지 ID 목록
            format: 응답 형식 (minimal, full, raw, metadata)
            on_progress: 진행 상황 콜백 (current, total)

        Returns:
            BatchResult 객체
        """
        result = BatchResult(total=len(message_ids))

        for i in range(0, len(message_ids), self.batch_size):
            batch_ids = message_ids[i : i + self.batch_size]
            batch_results = []
            batch_errors = []

            def callback_factory(msg_id: str):
                def callback(request_id, response, exception):
                    if exception:
                        batch_errors.append({
                            "message_id": msg_id,
                            "error": str(exception),
                        })
                    else:
                        batch_results.append(response)

                return callback

            # 배치 요청 생성
            batch = self.service.new_batch_http_request()

            for msg_id in batch_ids:
                batch.add(
                    self.service.users()
                    .messages()
                    .get(userId="me", id=msg_id, format=format),
                    callback=callback_factory(msg_id),
                )

            # 할당량 확인 및 대기
            units = len(batch_ids) * QuotaUnit.MESSAGES_GET
            self.quota_manager.wait_for_quota(self.user, units)

            # 배치 실행
            batch.execute()
            self.quota_manager.record_usage(self.user, units)

            # 결과 수집
            result.results.extend(batch_results)
            result.errors.extend(batch_errors)
            result.succeeded += len(batch_results)
            result.failed += len(batch_errors)

            # 진행 상황 콜백
            if on_progress:
                on_progress(min(i + self.batch_size, len(message_ids)), len(message_ids))

            # 다음 배치 전 지연
            if i + self.batch_size < len(message_ids):
                time.sleep(self.delay)

        return result

    def batch_modify_labels(
        self,
        message_ids: list[str],
        add_labels: Optional[list[str]] = None,
        remove_labels: Optional[list[str]] = None,
        on_progress: Optional[Callable[[int, int], None]] = None,
    ) -> BatchResult:
        """라벨 일괄 수정 (batchModify API 사용).

        Args:
            message_ids: 수정할 메시지 ID 목록
            add_labels: 추가할 라벨 ID
            remove_labels: 제거할 라벨 ID
            on_progress: 진행 상황 콜백

        Returns:
            BatchResult 객체
        """
        result = BatchResult(total=len(message_ids))

        for i in range(0, len(message_ids), self.batch_size):
            batch_ids = message_ids[i : i + self.batch_size]

            # 할당량 확인 및 대기
            units = QuotaUnit.MESSAGES_BATCH_MODIFY
            self.quota_manager.wait_for_quota(self.user, units)

            try:
                self.service.users().messages().batchModify(
                    userId="me",
                    body={
                        "ids": batch_ids,
                        "addLabelIds": add_labels or [],
                        "removeLabelIds": remove_labels or [],
                    },
                ).execute()

                self.quota_manager.record_usage(self.user, units)

                # batchModify는 성공 시 빈 응답 반환
                result.succeeded += len(batch_ids)
                result.results.extend([{"id": mid, "status": "modified"} for mid in batch_ids])

            except Exception as e:
                result.failed += len(batch_ids)
                result.errors.append({
                    "message_ids": batch_ids,
                    "error": str(e),
                })
                logger.error(f"Batch modify failed: {e}")

            # 진행 상황 콜백
            if on_progress:
                on_progress(min(i + self.batch_size, len(message_ids)), len(message_ids))

            # 다음 배치 전 지연
            if i + self.batch_size < len(message_ids):
                time.sleep(self.delay)

        return result

    def batch_trash_messages(
        self,
        message_ids: list[str],
        on_progress: Optional[Callable[[int, int], None]] = None,
    ) -> BatchResult:
        """메시지 일괄 휴지통 이동.

        Args:
            message_ids: 휴지통으로 이동할 메시지 ID 목록
            on_progress: 진행 상황 콜백

        Returns:
            BatchResult 객체
        """
        result = BatchResult(total=len(message_ids))

        for i in range(0, len(message_ids), self.batch_size):
            batch_ids = message_ids[i : i + self.batch_size]
            batch_results = []
            batch_errors = []

            def callback_factory(msg_id: str):
                def callback(request_id, response, exception):
                    if exception:
                        batch_errors.append({
                            "message_id": msg_id,
                            "error": str(exception),
                        })
                    else:
                        batch_results.append({"id": msg_id, "status": "trashed"})

                return callback

            batch = self.service.new_batch_http_request()

            for msg_id in batch_ids:
                batch.add(
                    self.service.users().messages().trash(userId="me", id=msg_id),
                    callback=callback_factory(msg_id),
                )

            units = len(batch_ids) * QuotaUnit.MESSAGES_TRASH
            self.quota_manager.wait_for_quota(self.user, units)

            batch.execute()
            self.quota_manager.record_usage(self.user, units)

            result.results.extend(batch_results)
            result.errors.extend(batch_errors)
            result.succeeded += len(batch_results)
            result.failed += len(batch_errors)

            if on_progress:
                on_progress(min(i + self.batch_size, len(message_ids)), len(message_ids))

            if i + self.batch_size < len(message_ids):
                time.sleep(self.delay)

        return result

    def batch_delete_messages(
        self,
        message_ids: list[str],
        on_progress: Optional[Callable[[int, int], None]] = None,
    ) -> BatchResult:
        """메시지 일괄 영구 삭제.

        주의: 이 작업은 되돌릴 수 없습니다!

        Args:
            message_ids: 삭제할 메시지 ID 목록
            on_progress: 진행 상황 콜백

        Returns:
            BatchResult 객체
        """
        result = BatchResult(total=len(message_ids))

        for i in range(0, len(message_ids), self.batch_size):
            batch_ids = message_ids[i : i + self.batch_size]
            batch_results = []
            batch_errors = []

            def callback_factory(msg_id: str):
                def callback(request_id, response, exception):
                    if exception:
                        batch_errors.append({
                            "message_id": msg_id,
                            "error": str(exception),
                        })
                    else:
                        batch_results.append({"id": msg_id, "status": "deleted"})

                return callback

            batch = self.service.new_batch_http_request()

            for msg_id in batch_ids:
                batch.add(
                    self.service.users().messages().delete(userId="me", id=msg_id),
                    callback=callback_factory(msg_id),
                )

            units = len(batch_ids) * QuotaUnit.MESSAGES_DELETE
            self.quota_manager.wait_for_quota(self.user, units)

            batch.execute()
            self.quota_manager.record_usage(self.user, units)

            result.results.extend(batch_results)
            result.errors.extend(batch_errors)
            result.succeeded += len(batch_results)
            result.failed += len(batch_errors)

            if on_progress:
                on_progress(min(i + self.batch_size, len(message_ids)), len(message_ids))

            if i + self.batch_size < len(message_ids):
                time.sleep(self.delay)

        return result

    # =========================================================================
    # Thread Operations
    # =========================================================================

    def batch_get_threads(
        self,
        thread_ids: list[str],
        format: str = "metadata",
        on_progress: Optional[Callable[[int, int], None]] = None,
    ) -> BatchResult:
        """스레드 일괄 조회.

        Args:
            thread_ids: 조회할 스레드 ID 목록
            format: 응답 형식
            on_progress: 진행 상황 콜백

        Returns:
            BatchResult 객체
        """
        result = BatchResult(total=len(thread_ids))

        for i in range(0, len(thread_ids), self.batch_size):
            batch_ids = thread_ids[i : i + self.batch_size]
            batch_results = []
            batch_errors = []

            def callback_factory(thread_id: str):
                def callback(request_id, response, exception):
                    if exception:
                        batch_errors.append({
                            "thread_id": thread_id,
                            "error": str(exception),
                        })
                    else:
                        batch_results.append(response)

                return callback

            batch = self.service.new_batch_http_request()

            for thread_id in batch_ids:
                batch.add(
                    self.service.users()
                    .threads()
                    .get(userId="me", id=thread_id, format=format),
                    callback=callback_factory(thread_id),
                )

            units = len(batch_ids) * QuotaUnit.THREADS_GET
            self.quota_manager.wait_for_quota(self.user, units)

            batch.execute()
            self.quota_manager.record_usage(self.user, units)

            result.results.extend(batch_results)
            result.errors.extend(batch_errors)
            result.succeeded += len(batch_results)
            result.failed += len(batch_errors)

            if on_progress:
                on_progress(min(i + self.batch_size, len(thread_ids)), len(thread_ids))

            if i + self.batch_size < len(thread_ids):
                time.sleep(self.delay)

        return result

    # =========================================================================
    # Utility Methods
    # =========================================================================

    def mark_all_as_read(
        self,
        query: str = "is:unread",
        max_messages: int = 500,
    ) -> BatchResult:
        """조건에 맞는 메시지 전체 읽음 처리.

        Args:
            query: 검색 쿼리 (기본: 읽지 않음)
            max_messages: 최대 처리 메시지 수

        Returns:
            BatchResult 객체
        """
        # 먼저 메시지 ID 목록 조회
        message_ids = []
        page_token = None

        while len(message_ids) < max_messages:
            result = (
                self.service.users()
                .messages()
                .list(
                    userId="me",
                    q=query,
                    maxResults=min(100, max_messages - len(message_ids)),
                    pageToken=page_token,
                )
                .execute()
            )

            for msg in result.get("messages", []):
                message_ids.append(msg["id"])

            page_token = result.get("nextPageToken")
            if not page_token:
                break

        if not message_ids:
            return BatchResult()

        return self.batch_modify_labels(
            message_ids,
            remove_labels=["UNREAD"],
        )

    def archive_all(
        self,
        query: str = "",
        max_messages: int = 500,
    ) -> BatchResult:
        """조건에 맞는 메시지 전체 보관처리.

        Args:
            query: 검색 쿼리
            max_messages: 최대 처리 메시지 수

        Returns:
            BatchResult 객체
        """
        # INBOX 라벨이 있는 메시지만 조회
        full_query = f"in:inbox {query}".strip()

        message_ids = []
        page_token = None

        while len(message_ids) < max_messages:
            result = (
                self.service.users()
                .messages()
                .list(
                    userId="me",
                    q=full_query,
                    maxResults=min(100, max_messages - len(message_ids)),
                    pageToken=page_token,
                )
                .execute()
            )

            for msg in result.get("messages", []):
                message_ids.append(msg["id"])

            page_token = result.get("nextPageToken")
            if not page_token:
                break

        if not message_ids:
            return BatchResult()

        return self.batch_modify_labels(
            message_ids,
            remove_labels=["INBOX"],
        )


if __name__ == "__main__":
    # 모듈 테스트 (실제 API 없이)
    print("BatchProcessor module loaded successfully")

    # BatchResult 테스트
    result = BatchResult(total=10, succeeded=8, failed=2)
    result.results = [{"id": f"msg{i}"} for i in range(8)]
    result.errors = [{"message_id": "msg8", "error": "Not found"}, {"message_id": "msg9", "error": "Rate limited"}]

    print(f"Total: {result.total}")
    print(f"Succeeded: {result.succeeded}")
    print(f"Failed: {result.failed}")
    print(f"Success rate: {result.succeeded / result.total * 100:.1f}%")


================================================
FILE: plugins/gmail/skills/gmail/scripts/core/cache_manager.py
================================================
"""Gmail Local Cache Manager.

API 호출을 최소화하기 위한 로컬 캐시 레이어.

캐시 전략:
- 메시지 내용: 24시간 유효 (메시지는 불변)
- 메시지 메타데이터: 1시간 유효 (라벨 변경 가능)
- 메시지 목록: 5분 유효 (자주 변경됨)
- 라벨 목록: 1시간 유효

캐시 무효화:
- 메시지 수정 시 해당 메시지 캐시 무효화
- 발송 시 목록 캐시 무효화
- 라벨 변경 시 라벨 캐시 무효화

Reference:
    https://community.latenode.com/t/understanding-gmail-api-quota-restrictions-and-rate-limits/28113
"""

import hashlib
import json
import os
import shutil
import threading
from dataclasses import dataclass
from datetime import datetime, timedelta
from pathlib import Path
from typing import Any, Optional


@dataclass
class CacheConfig:
    """캐시 설정."""

    # TTL (Time-To-Live) 설정 (시간 단위)
    message_ttl_hours: int = 24  # 메시지 본문
    metadata_ttl_hours: int = 1  # 메타데이터
    list_ttl_minutes: int = 5  # 목록
    labels_ttl_hours: int = 1  # 라벨

    # 캐시 크기 제한
    max_messages_per_account: int = 1000
    max_cache_size_mb: int = 100


class EmailCache:
    """Gmail 이메일 로컬 캐시 관리자.

    API 호출을 줄이기 위해 메시지, 목록, 라벨을 로컬에 캐싱합니다.

    Usage:
        cache = EmailCache()

        # 메시지 캐싱
        cached = cache.get_message("work", "msg123")
        if cached is None:
            message = api.get_message("msg123")
            cache.set_message("work", "msg123", message)
        else:
            message = cached

        # 목록 캐싱
        query = "is:unread"
        cached_list = cache.get_list("work", query)
        if cached_list is None:
            messages = api.list_messages(query)
            cache.set_list("work", query, messages)
    """

    def __init__(
        self,
        cache_dir: Optional[str] = None,
        config: Optional[CacheConfig] = None,
    ):
        """
        Args:
            cache_dir: 캐시 디렉토리 (기본값: .cache/gmail)
            config: 캐시 설정
        """
        self.config = config or CacheConfig()

        if cache_dir:
            self.cache_dir = Path(cache_dir)
        elif os.environ.get("GMAIL_CACHE_DIR"):
            self.cache_dir = Path(os.environ["GMAIL_CACHE_DIR"])
        else:
            self.cache_dir = Path(__file__).parent.parent.parent / ".cache" / "gmail"

        self.cache_dir.mkdir(parents=True, exist_ok=True)
        self._lock = threading.Lock()

    # =========================================================================
    # Message Cache
    # =========================================================================

    def get_message(
        self,
        account: str,
        message_id: str,
        metadata_only: bool = False,
    ) -> Optional[dict]:
        """캐시된 메시지 조회.

        Args:
            account: 계정 이름
            message_id: 메시지 ID
            metadata_only: 메타데이터만 조회 시 True

        Returns:
            캐시된 메시지 또는 None
        """
        cache_file = self._message_path(account, message_id)

        if not cache_file.exists():
            return None

        try:
            with open(cache_file) as f:
                data = json.load(f)

            ttl_hours = (
                self.config.metadata_ttl_hours
                if metadata_only
                else self.config.message_ttl_hours
            )

            if self._is_fresh(data.get("cached_at"), ttl_hours):
                return data.get("message")

            # 만료된 캐시 삭제
            cache_file.unlink(missing_ok=True)
            return None
        except (json.JSONDecodeError, KeyError):
            cache_file.unlink(missing_ok=True)
            return None

    def set_message(
        self,
        account: str,
        message_id: str,
        message: dict,
    ) -> None:
        """메시지 캐시.

        Args:
            account: 계정 이름
            message_id: 메시지 ID
            message: 메시지 데이터
        """
        with self._lock:
            account_dir = self.cache_dir / account / "messages"
            account_dir.mkdir(parents=True, exist_ok=True)

            cache_file = self._message_path(account, message_id)
            cache_data = {
                "cached_at": datetime.now().isoformat(),
                "message": message,
            }

            with open(cache_file, "w") as f:
                json.dump(cache_data, f, ensure_ascii=False)

            # 캐시 크기 정리
            self._cleanup_if_needed(account)

    # =========================================================================
    # List Cache
    # =========================================================================

    def get_list(
        self,
        account: str,
        query: str,
        label_ids: Optional[list[str]] = None,
    ) -> Optional[list[dict]]:
        """캐시된 목록 조회.

        Args:
            account: 계정 이름
            query: 검색 쿼리
            label_ids: 라벨 필터

        Returns:
            캐시된 메시지 ID 목록 또는 None
        """
        cache_key = self._list_cache_key(query, label_ids)
        cache_file = self._list_path(account, cache_key)

        if not cache_file.exists():
            return None

        try:
            with open(cache_file) as f:
                data = json.load(f)

            ttl_minutes = self.config.list_ttl_minutes
            if self._is_fresh(data.get("cached_at"), ttl_minutes / 60):
                return data.get("messages")

            cache_file.unlink(missing_ok=True)
            return None
        except (json.JSONDecodeError, KeyError):
            cache_file.unlink(missing_ok=True)
            return None

    def set_list(
        self,
        account: str,
        query: str,
        messages: list[dict],
        label_ids: Optional[list[str]] = None,
    ) -> None:
        """목록 캐시.

        Args:
            account: 계정 이름
            query: 검색 쿼리
            messages: 메시지 목록
            label_ids: 라벨 필터
        """
        with self._lock:
            list_dir = self.cache_dir / account / "lists"
            list_dir.mkdir(parents=True, exist_ok=True)

            cache_key = self._list_cache_key(query, label_ids)
            cache_file = self._list_path(account, cache_key)

            cache_data = {
                "cached_at": datetime.now().isoformat(),
                "query": query,
                "label_ids": label_ids,
                "messages": messages,
            }

            with open(cache_file, "w") as f:
                json.dump(cache_data, f, ensure_ascii=False)

    # =========================================================================
    # Labels Cache
    # =========================================================================

    def get_labels(self, account: str) -> Optional[list[dict]]:
        """캐시된 라벨 목록 조회.

        Args:
            account: 계정 이름

        Returns:
            캐시된 라벨 목록 또는 None
        """
        cache_file = self.cache_dir / account / "labels.json"

        if not cache_file.exists():
            return None

        try:
            with open(cache_file) as f:
                data = json.load(f)

            if self._is_fresh(data.get("cached_at"), self.config.labels_ttl_hours):
                return data.get("labels")

            cache_file.unlink(missing_ok=True)
            return None
        except (json.JSONDecodeError, KeyError):
            cache_file.unlink(missing_ok=True)
            return None

    def set_labels(self, account: str, labels: list[dict]) -> None:
        """라벨 캐시.

        Args:
            account: 계정 이름
            labels: 라벨 목록
        """
        with self._lock:
            account_dir = self.cache_dir / account
            account_dir.mkdir(parents=True, exist_ok=True)

            cache_file = account_dir / "labels.json"
            cache_data = {
                "cached_at": datetime.now().isoformat(),
                "labels": labels,
            }

            with open(cache_file, "w") as f:
                json.dump(cache_data, f, ensure_ascii=False)

    # =========================================================================
    # Cache Invalidation
    # =========================================================================

    def invalidate_message(self, account: str, message_id: str) -> None:
        """메시지 캐시 무효화.

        Args:
            account: 계정 이름
            message_id: 메시지 ID
        """
        with self._lock:
            cache_file = self._message_path(account, message_id)
            cache_file.unlink(missing_ok=True)

    def invalidate_lists(self, account: str) -> None:
        """목록 캐시 전체 무효화.

        Args:
            account: 계정 이름
        """
        with self._lock:
            list_dir = self.cache_dir / account / "lists"
            if list_dir.exists():
                shutil.rmtree(list_dir, ignore_errors=True)

    def invalidate_labels(self, account: str) -> None:
        """라벨 캐시 무효화.

        Args:
            account: 계정 이름
        """
        with self._lock:
            cache_file = self.cache_dir / account / "labels.json"
            cache_file.unlink(missing_ok=True)

    def invalidate_account(self, account: str) -> None:
        """계정의 모든 캐시 무효화.

        Args:
            account: 계정 이름
        """
        with self._lock:
            account_dir = self.cache_dir / account
            if account_dir.exists():
                shutil.rmtree(account_dir, ignore_errors=True)

    def invalidate_all(self) -> None:
        """전체 캐시 무효화."""
        with self._lock:
            if self.cache_dir.exists():
                shutil.rmtree(self.cache_dir, ignore_errors=True)
            self.cache_dir.mkdir(parents=True, exist_ok=True)

    # =========================================================================
    # Cache Statistics
    # =========================================================================

    def get_stats(self, account: Optional[str] = None) -> dict:
        """캐시 통계 조회.

        Args:
            account: 특정 계정만 조회 시 지정

        Returns:
            캐시 통계 정보
        """
        stats = {
            "cache_dir": str(self.cache_dir),
            "accounts": {},
            "total_size_bytes": 0,
            "total_messages": 0,
        }

        accounts = [account] if account else self._get_cached_accounts()

        for acc in accounts:
            acc_dir = self.cache_dir / acc
            if not acc_dir.exists():
                continue

            msg_dir = acc_dir / "messages"
            list_dir = acc_dir / "lists"

            msg_count = len(list(msg_dir.glob("*.json"))) if msg_dir.exists() else 0
            list_count = len(list(list_dir.glob("*.json"))) if list_dir.exists() else 0

            # 계정 디렉토리 크기 계산
            size = sum(
                f.stat().st_size
                for f in acc_dir.rglob("*")
                if f.is_file()
            )

            stats["accounts"][acc] = {
                "messages_cached": msg_count,
                "lists_cached": list_count,
                "size_bytes": size,
                "size_mb": round(size / (1024 * 1024), 2),
            }

            stats["total_size_bytes"] += size
            stats["total_messages"] += msg_count

        stats["total_size_mb"] = round(
            stats["total_size_bytes"] / (1024 * 1024), 2
        )

        return stats

    # =========================================================================
    # Internal Methods
    # =========================================================================

    def _message_path(self, account: str, message_id: str) -> Path:
        """메시지 캐시 파일 경로."""
        return self.cache_dir / account / "messages" / f"{message_id}.json"

    def _list_path(self, account: str, cache_key: str) -> Path:
        """목록 캐시 파일 경로."""
        return self.cache_dir / account / "lists" / f"{cache_key}.json"

    def _list_cache_key(
        self,
        query: str,
        label_ids: Optional[list[str]] = None,
    ) -> str:
        """목록 캐시 키 생성."""
        key_data = {"query": query, "labels": sorted(label_ids or [])}
        key_str = json.dumps(key_data, sort_keys=True)
        return hashlib.md5(key_str.encode()).hexdigest()[:16]

    def _is_fresh(
        self,
        cached_at: Optional[str],
        max_age_hours: float,
    ) -> bool:
        """캐시 신선도 확인."""
        if not cached_at:
            return False

        try:
            cache_time = datetime.fromisoformat(cached_at)
            return datetime.now() - cache_time < timedelta(hours=max_age_hours)
        except ValueError:
            return False

    def _get_cached_accounts(self) -> list[str]:
        """캐시된 계정 목록."""
        if not self.cache_dir.exists():
            return []

        return [
            d.name
            for d in self.cache_dir.iterdir()
            if d.is_dir() and not d.name.startswith(".")
        ]

    def _cleanup_if_needed(self, account: str) -> None:
        """캐시 크기 제한 적용."""
        msg_dir = self.cache_dir / account / "messages"
        if not msg_dir.exists():
            return

        cache_files = sorted(
            msg_dir.glob("*.json"),
            key=lambda f: f.stat().st_mtime,
        )

        # 메시지 수 제한
        if len(cache_files) > self.config.max_messages_per_account:
            to_delete = len(cache_files) - self.config.max_messages_per_account
            for f in cache_files[:to_delete]:
                f.unlink(missing_ok=True)


# 싱글톤 인스턴스
_default_cache: Optional[EmailCache] = None


def get_cache(cache_dir: Optional[str] = None) -> EmailCache:
    """기본 캐시 인스턴스 반환.

    Args:
        cache_dir: 캐시 디렉토리

    Returns:
        EmailCache 싱글톤 인스턴스
    """
    global _default_cache
    if _default_cache is None:
        _default_cache = EmailCache(cache_dir)
    return _default_cache


if __name__ == "__main__":
    # 테스트
    import tempfile

    # 임시 디렉토리에서 테스트
    with tempfile.TemporaryDirectory() as tmpdir:
        cache = EmailCache(cache_dir=tmpdir)

        # 메시지 캐싱 테스트
        test_message = {
            "id": "msg123",
            "subject": "Test Subject",
            "from": "test@example.com",
            "body": "Test body content",
        }

        cache.set_message("work", "msg123", test_message)
        cached = cache.get_message("work", "msg123")
        print(f"Cached message: {cached['subject']}")

        # 목록 캐싱 테스트
        test_list = [
            {"id": "msg1", "threadId": "thread1"},
            {"id": "msg2", "threadId": "thread2"},
        ]

        cache.set_list("work", "is:unread", test_list)
        cached_list = cache.get_list("work", "is:unread")
        print(f"Cached list: {len(cached_list)} messages")

        # 라벨 캐싱 테스트
        test_labels = [
            {"id": "INBOX", "name": "INBOX"},
            {"id": "SENT", "name": "SENT"},
        ]

        cache.set_labels("work", test_labels)
        cached_labels = cache.get_labels("work")
        print(f"Cached labels: {len(cached_labels)} labels")

        # 통계
        stats = cache.get_stats()
        print(f"\nCache stats: {json.dumps(stats, indent=2)}")

        # 무효화 테스트
        cache.invalidate_message("work", "msg123")
        cached = cache.get_message("work", "msg123")
        print(f"After invalidation: {cached}")


================================================
FILE: plugins/gmail/skills/gmail/scripts/core/quota_manager.py
================================================
"""Gmail API Quota Management.

Gmail API 할당량 관리를 위한 모듈.

Quota Units (Gmail API Reference):
- messages.list: 5 units
- messages.get: 5 units
- messages.send: 100 units
- messages.modify: 5 units
- messages.batchModify: 50 units
- threads.list: 5 units
- threads.get: 10 units

Rate Limits:
- Per-user: 250 quota units per second
- Daily: 1,000,000,000 units (workspace), varies for consumer

Reference:
    https://developers.google.com/workspace/gmail/api/reference/quota
"""

import threading
import time
from dataclasses import dataclass, field
from datetime import datetime, timedelta
from enum import IntEnum
from typing import Optional


class QuotaUnit(IntEnum):
    """API 메서드별 할당량 단위."""

    # Messages
    MESSAGES_LIST = 5
    MESSAGES_GET = 5
    MESSAGES_SEND = 100
    MESSAGES_MODIFY = 5
    MESSAGES_BATCH_MODIFY = 50
    MESSAGES_DELETE = 10
    MESSAGES_TRASH = 5
    MESSAGES_UNTRASH = 5

    # Threads
    THREADS_LIST = 5
    THREADS_GET = 10
    THREADS_MODIFY = 5
    THREADS_TRASH = 5

    # Labels
    LABELS_LIST = 1
    LABELS_GET = 1
    LABELS_CREATE = 5
    LABELS_UPDATE = 5
    LABELS_DELETE = 5

    # Drafts
    DRAFTS_LIST = 5
    DRAFTS_GET = 5
    DRAFTS_CREATE = 10
    DRAFTS_SEND = 100
    DRAFTS_DELETE = 10

    # Profile
    PROFILE_GET = 5

    # Attachments
    ATTACHMENTS_GET = 5


@dataclass
class QuotaUsage:
    """사용자별 할당량 사용 현황."""

    units_used: int = 0
    last_reset: datetime = field(default_factory=datetime.now)
    daily_units: int = 0
    daily_reset: datetime = field(default_factory=datetime.now)


class QuotaManager:
    """Gmail API 할당량 관리자.

    Per-user rate limiting (250 units/second)과
    일일 할당량을 추적하고 관리합니다.

    Usage:
        quota = QuotaManager()

        # 실행 전 확인
        if quota.can_execute("user@gmail.com", QuotaUnit.MESSAGES_LIST):
            # API 호출
            result = api.list_messages()
            quota.record_usage("user@gmail.com", QuotaUnit.MESSAGES_LIST)

        # 또는 자동 대기
        quota.wait_for_quota("user@gmail.com", QuotaUnit.MESSAGES_GET)
        result = api.get_message(id)
        quota.record_usage("user@gmail.com", QuotaUnit.MESSAGES_GET)
    """

    # Gmail API limits
    USER_RATE_LIMIT = 250  # units per second
    DAILY_LIMIT = 1_000_000_000  # units per day (workspace)
    CONSUMER_DAILY_LIMIT = 1_000_000  # Conservative estimate for consumer accounts

    def __init__(
        self,
        rate_limit: int = USER_RATE_LIMIT,
        daily_limit: Optional[int] = None,
        is_workspace: bool = True,
    ):
        """
        Args:
            rate_limit: 초당 최대 할당량 (기본값: 250)
            daily_limit: 일일 최대 할당량 (None이면 자동 설정)
            is_workspace: Workspace 계정 여부
        """
        self.rate_limit = rate_limit
        self.daily_limit = (
            daily_limit
            or (self.DAILY_LIMIT if is_workspace else self.CONSUMER_DAILY_LIMIT)
        )
        self._usage: dict[str, QuotaUsage] = {}
        self._lock = threading.Lock()

    def can_execute(self, user: str, units: int) -> bool:
        """API 호출 가능 여부 확인.

        Args:
            user: 사용자 식별자 (이메일 또는 계정명)
            units: 필요한 할당량 단위

        Returns:
            실행 가능하면 True
        """
        with self._lock:
            self._reset_if_needed(user)
            usage = self._get_or_create_usage(user)
            return usage.units_used + units <= self.rate_limit

    def record_usage(self, user: str, units: int) -> None:
        """사용량 기록.

        Args:
            user: 사용자 식별자
            units: 사용한 할당량 단위
        """
        with self._lock:
            self._reset_if_needed(user)
            usage = self._get_or_create_usage(user)
            usage.units_used += units
            usage.daily_units += units

    def wait_for_quota(
        self,
        user: str,
        units: int,
        timeout: float = 30.0,
    ) -> bool:
        """할당량 확보까지 대기.

        Args:
            user: 사용자 식별자
            units: 필요한 할당량 단위
            timeout: 최대 대기 시간 (초)

        Returns:
            할당량 확보 성공 여부

        Raises:
            TimeoutError: 타임아웃 시
        """
        start = time.time()

        while not self.can_execute(user, units):
            if time.time() - start > timeout:
                raise TimeoutError(
                    f"할당량 확보 타임아웃 ({timeout}초). "
                    f"사용자: {user}, 필요 단위: {units}"
                )
            time.sleep(0.1)
            with self._lock:
                self._reset_if_needed(user)

        return True

    def get_usage(self, user: str) -> dict:
        """사용자 할당량 현황 조회.

        Args:
            user: 사용자 식별자

        Returns:
            현재 사용량 정보
        """
        with self._lock:
            self._reset_if_needed(user)
            usage = self._get_or_create_usage(user)
            return {
                "user": user,
                "units_used": usage.units_used,
                "rate_limit": self.rate_limit,
                "rate_available": self.rate_limit - usage.units_used,
                "daily_units": usage.daily_units,
                "daily_limit": self.daily_limit,
                "daily_available": self.daily_limit - usage.daily_units,
            }

    def get_remaining_rate(self, user: str) -> int:
        """현재 초에 남은 rate limit.

        Args:
            user: 사용자 식별자

        Returns:
            남은 할당량 단위 수
        """
        with self._lock:
            self._reset_if_needed(user)
            usage = self._get_or_create_usage(user)
            return max(0, self.rate_limit - usage.units_used)

    def is_daily_limit_reached(self, user: str) -> bool:
        """일일 할당량 도달 여부.

        Args:
            user: 사용자 식별자

        Returns:
            일일 한도 도달 시 True
        """
        with self._lock:
            usage = self._get_or_create_usage(user)
            return usage.daily_units >= self.daily_limit

    def reset_user(self, user: str) -> None:
        """사용자 할당량 리셋 (테스트용).

        Args:
            user: 사용자 식별자
        """
        with self._lock:
            if user in self._usage:
                del self._usage[user]

    def _get_or_create_usage(self, user: str) -> QuotaUsage:
        """사용자 usage 객체 반환 (없으면 생성)."""
        if user not in self._usage:
            self._usage[user] = QuotaUsage()
        return self._usage[user]

    def _reset_if_needed(self, user: str) -> None:
        """초당/일일 리셋 확인 및 수행."""
        if user not in self._usage:
            return

        usage = self._usage[user]
        now = datetime.now()

        # 초당 리셋
        if now - usage.last_reset > timedelta(seconds=1):
            usage.units_used = 0
            usage.last_reset = now

        # 일일 리셋 (자정 기준)
        if now.date() > usage.daily_reset.date():
            usage.daily_units = 0
            usage.daily_reset = now


# 싱글톤 인스턴스
_default_manager: Optional[QuotaManager] = None


def get_quota_manager(
    rate_limit: int = QuotaManager.USER_RATE_LIMIT,
    is_workspace: bool = True,
) -> QuotaManager:
    """기본 QuotaManager 인스턴스 반환.

    Args:
        rate_limit: 초당 최대 할당량
        is_workspace: Workspace 계정 여부

    Returns:
        QuotaManager 싱글톤 인스턴스
    """
    global _default_manager
    if _default_manager is None:
        _default_manager = QuotaManager(
            rate_limit=rate_limit,
            is_workspace=is_workspace,
        )
    return _default_manager


if __name__ == "__main__":
    # 테스트
    manager = QuotaManager()

    user = "test@gmail.com"
    print(f"Initial usage: {manager.get_usage(user)}")

    # 사용량 기록
    manager.record_usage(user, QuotaUnit.MESSAGES_LIST)
    print(f"After list: {manager.get_usage(user)}")

    manager.record_usage(user, QuotaUnit.MESSAGES_GET)
    print(f"After get: {manager.get_usage(user)}")

    # 실행 가능 여부
    print(f"Can execute 250? {manager.can_execute(user, 250)}")
    print(f"Remaining rate: {manager.get_remaining_rate(user)}")

    # 대기 테스트
    print("Waiting for quota...")
    time.sleep(1.1)  # 1초 후 리셋됨
    print(f"After 1s: {manager.get_usage(user)}")


================================================
FILE: plugins/gmail/skills/gmail/scripts/core/retry_handler.py
================================================
"""Exponential Backoff Retry Handler.

Gmail API 오류 처리를 위한 지수 백오프 재시도 로직.

Retry-able Errors:
- 429: Rate Limit Exceeded (Too Many Requests)
- 500: Internal Server Error
- 502: Bad Gateway
- 503: Service Unavailable
- 504: Gateway Timeout

Non-retry-able Errors:
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found

Reference:
    https://developers.google.com/workspace/gmail/api/guides/handle-errors
"""

import logging
import random
import time
from dataclasses import dataclass
from functools import wraps
from typing import Callable, Optional, TypeVar, Any

from googleapiclient.errors import HttpError

logger = logging.getLogger(__name__)

T = TypeVar("T")

# 재시도 가능한 HTTP 상태 코드
RETRYABLE_STATUS_CODES = {429, 500, 502, 503, 504}


@dataclass
class RetryConfig:
    """재시도 설정."""

    max_retries: int = 5
    base_delay: float = 1.0
    max_delay: float = 60.0
    exponential_base: float = 2.0
    jitter: bool = True


def calculate_delay(
    attempt: int,
    base_delay: float = 1.0,
    max_delay: float = 60.0,
    exponential_base: float = 2.0,
    jitter: bool = True,
) -> float:
    """지수 백오프 지연 시간 계산.

    Args:
        attempt: 현재 시도 횟수 (0부터 시작)
        base_delay: 기본 지연 시간 (초)
        max_delay: 최대 지연 시간 (초)
        exponential_base: 지수 배수
        jitter: 무작위 지터 추가 여부

    Returns:
        계산된 지연 시간 (초)
    """
    delay = min(base_delay * (exponential_base**attempt), max_delay)

    if jitter:
        # 0.5 ~ 1.5 범위의 지터 추가
        delay *= 0.5 + random.random()

    return delay


def is_retryable_error(error: Exception) -> bool:
    """재시도 가능한 오류인지 확인.

    Args:
        error: 발생한 예외

    Returns:
        재시도 가능하면 True
    """
    if isinstance(error, HttpError):
        return error.resp.status in RETRYABLE_STATUS_CODES
    return False


def exponential_backoff(
    max_retries: int = 5,
    base_delay: float = 1.0,
    max_delay: float = 60.0,
    exponential_base: float = 2.0,
    jitter: bool = True,
    on_retry: Optional[Callable[[int, Exception, float], None]] = None,
) -> Callable:
    """지수 백오프 데코레이터.

    Gmail API 호출 시 rate limiting 및 일시적 오류를
    자동으로 처리합니다.

    Args:
        max_retries: 최대 재시도 횟수
        base_delay: 기본 지연 시간 (초)
        max_delay: 최대 지연 시간 (초)
        exponential_base: 지수 배수
        jitter: 무작위 지터 추가 여부
        on_retry: 재시도 시 호출될 콜백 (attempt, error, delay)

    Returns:
        데코레이터 함수

    Usage:
        @exponential_backoff(max_retries=5)
        def get_message(service, message_id):
            return service.users().messages().get(
                userId='me', id=message_id
            ).execute()

        # 콜백과 함께 사용
        def log_retry(attempt, error, delay):
            print(f"Retry {attempt}: {error}, waiting {delay:.1f}s")

        @exponential_backoff(max_retries=3, on_retry=log_retry)
        def list_messages(service, query):
            ...
    """

    def decorator(func: Callable[..., T]) -> Callable[..., T]:
        @wraps(func)
        def wrapper(*args: Any, **kwargs: Any) -> T:
            last_exception: Optional[Exception] = None

            for attempt in range(max_retries + 1):
                try:
                    return func(*args, **kwargs)
                except HttpError as e:
                    last_exception = e

                    if not is_retryable_error(e):
                        # 재시도 불가능한 오류는 즉시 발생
                        raise

                    if attempt == max_retries:
                        # 최대 재시도 횟수 도달
                        logger.error(
                            f"최대 재시도 횟수({max_retries}) 도달. "
                            f"함수: {func.__name__}, 오류: {e}"
                        )
                        raise

                    delay = calculate_delay(
                        attempt,
                        base_delay,
                        max_delay,
                        exponential_base,
                        jitter,
                    )

                    if on_retry:
                        on_retry(attempt, e, delay)

                    logger.warning(
                        f"재시도 {attempt + 1}/{max_retries}: "
                        f"HTTP {e.resp.status}, {delay:.1f}초 대기"
                    )
                    time.sleep(delay)
                except Exception as e:
                    # HttpError가 아닌 예외는 그대로 발생
                    raise

            # 이 코드에 도달하면 안 됨
            if last_exception:
                raise last_exception
            raise RuntimeError("Unexpected state in retry logic")

        return wrapper

    return decorator


class RetryableOperation:
    """재시도 가능한 작업을 위한 컨텍스트 매니저.

    데코레이터 대신 명시적으로 재시도 로직을 사용할 때 유용합니다.

    Usage:
        with RetryableOperation(max_retries=5) as op:
            while op.should_retry():
                try:
                    result = service.users().messages().get(
                        userId='me', id=message_id
                    ).execute()
                    op.success()
                    break
                except HttpError as e:
                    op.handle_error(e)

        # 또는 execute 사용
        def fetch_message():
            return service.users().messages().get(...).execute()

        result = RetryableOperation(max_retries=5).execute(fetch_message)
    """

    def __init__(
        self,
        max_retries: int = 5,
        base_delay: float = 1.0,
        max_delay: float = 60.0,
        exponential_base: float = 2.0,
        jitter: bool = True,
    ):
        self.config = RetryConfig(
            max_retries=max_retries,
            base_delay=base_delay,
            max_delay=max_delay,
            exponential_base=exponential_base,
            jitter=jitter,
        )
        self.attempt = 0
        self.succeeded = False
        self.last_error: Optional[Exception] = None

    def __enter__(self) -> "RetryableOperation":
        self.attempt = 0
        self.succeeded = False
        self.last_error = None
        return self

    def __exit__(self, exc_type, exc_val, exc_tb):
        return False

    def should_retry(self) -> bool:
        """재시도 해야 하는지 확인."""
        return not self.succeeded and self.attempt <= self.config.max_retries

    def success(self) -> None:
        """작업 성공 표시."""
        self.succeeded = True

    def handle_error(self, error: Exception) -> None:
        """오류 처리 및 대기.

        Args:
            error: 발생한 예외

        Raises:
            Exception: 재시도 불가능하거나 최대 횟수 도달 시
        """
        self.last_error = error

        if not is_retryable_error(error):
            raise error

        if self.attempt >= self.config.max_retries:
            raise error

        delay = calculate_delay(
            self.attempt,
            self.config.base_delay,
            self.config.max_delay,
            self.config.exponential_base,
            self.config.jitter,
        )

        logger.warning(
            f"재시도 {self.attempt + 1}/{self.config.max_retries}: "
            f"{type(error).__name__}, {delay:.1f}초 대기"
        )

        time.sleep(delay)
        self.attempt += 1

    def execute(self, func: Callable[..., T], *args, **kwargs) -> T:
        """함수를 재시도 로직과 함께 실행.

        Args:
            func: 실행할 함수
            *args: 함수 인자
            **kwargs: 함수 키워드 인자

        Returns:
            함수 실행 결과

        Raises:
            Exception: 최대 재시도 후에도 실패 시
        """
        with self as op:
            while op.should_retry():
                try:
                    result = func(*args, **kwargs)
                    op.success()
                    return result
                except Exception as e:
                    op.handle_error(e)

        # 이 코드에 도달하면 안 됨
        if self.last_error:
            raise self.last_error
        raise RuntimeError("Unexpected state in retry operation")


def retry_api_call(
    func: Callable[..., T],
    *args,
    max_retries: int = 5,
    **kwargs,
) -> T:
    """단순 재시도 헬퍼 함수.

    데코레이터나 컨텍스트 매니저 없이 간단히 사용할 수 있습니다.

    Args:
        func: 실행할 함수
        *args: 함수 인자
        max_retries: 최대 재시도 횟수
        **kwargs: 함수 키워드 인자

    Returns:
        함수 실행 결과

    Usage:
        result = retry_api_call(
            service.users().messages().get,
            userId='me',
            id=message_id,
            max_retries=3
        )
    """
    return RetryableOperation(max_retries=max_retries).execute(
        func, *args, **kwargs
    )


if __name__ == "__main__":
    # 테스트

    # 성공 케이스
    @exponential_backoff(max_retries=3)
    def always_succeeds():
        return "success"

    print(f"Success test: {always_succeeds()}")

    # 재시도 후 성공 케이스 시뮬레이션
    call_count = 0

    @exponential_backoff(max_retries=3, base_delay=0.1)
    def succeed_on_third_try():
        global call_count
        call_count += 1
        if call_count < 3:
            # 임시 오류 시뮬레이션
            from unittest.mock import MagicMock

            error = HttpError(MagicMock(status=429), b"Rate limited")
            raise error
        return f"success on try {call_count}"

    try:
        call_count = 0
        result = succeed_on_third_try()
        print(f"Retry test: {result}")
    except HttpError as e:
        print(f"Retry test failed: {e}")

    # RetryableOperation 테스트
    print("\nRetryableOperation test:")
    op = RetryableOperation(max_retries=3, base_delay=0.1)
    result = op.execute(lambda: "direct execute")
    print(f"Direct execute: {result}")


================================================
FILE: plugins/gmail/skills/gmail/scripts/gmail_client.py
================================================
"""Gmail API 클라이언트.

여러 Google 계정의 Gmail을 조회/발송하기 위한 클라이언트.
저장된 refresh token을 사용하여 매번 인증 없이 API 호출.

Features:
    - 다중 계정 지원 (work, personal 등)
    - Rate Limiting & Quota Management (P0)
    - Exponential Backoff for Error Handling (P0)
    - Batch Processing for Bulk Operations (P1)
    - Local Caching for API Optimization (P1)

Environment Variables:
    GMAIL_SKILL_PATH: Skill 루트 경로 (기본값: 이 파일의 부모의 부모)
    GMAIL_TIMEOUT: API 요청 타임아웃 초 (기본값: 30)
    GMAIL_CACHE_DIR: 캐시 디렉토리 (기본값: .cache/gmail)
    GMAIL_ENABLE_CACHE: 캐시 활성화 여부 (기본값: true)
    GMAIL_ENABLE_QUOTA: 할당량 관리 활성화 여부 (기본값: true)
"""

import base64
import json
import logging
import mimetypes
import os
from datetime import datetime
from email import encoders
from email.mime.audio import MIMEAudio
from email.mime.base import MIMEBase
from email.mime.image import MIMEImage
from email.mime.multipart import MIMEMultipart
from email.mime.text import MIMEText
from pathlib import Path
from typing import Optional

import google.auth
from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from googleapiclient.discovery import build

# Core modules for enhanced functionality
try:
    from .core import (
        QuotaManager,
        QuotaUnit,
        exponential_backoff,
        RetryConfig,
        EmailCache,
        BatchProcessor,
    )
except ImportError:
    # Fallback for direct script execution
    from core import (
        QuotaManager,
        QuotaUnit,
        exponential_backoff,
        RetryConfig,
        EmailCache,
        BatchProcessor,
    )

logger = logging.getLogger(__name__)

DEFAULT_TIMEOUT = int(os.environ.get("GMAIL_TIMEOUT", "30"))
ENABLE_CACHE = os.environ.get("GMAIL_ENABLE_CACHE", "true").lower() == "true"
ENABLE_QUOTA = os.environ.get("GMAIL_ENABLE_QUOTA", "true").lower() == "true"


class GmailClient:
    """단일 Google 계정의 Gmail 클라이언트.

    Enhanced with:
        - Rate limiting & quota management
        - Exponential backoff for error handling
        - Local caching for API optimization
        - Batch processing support
    """

    SCOPES = [
        "https://www.googleapis.com/auth/gmail.modify",  # 읽기/수정/삭제
        "https://www.googleapis.com/auth/gmail.send",    # 메일 발송
        "https://www.googleapis.com/auth/gmail.labels",  # 라벨 관리
    ]

    def __init__(
        self,
        account_name: str,
        base_path: Optional[Path] = None,
        timeout: int = DEFAULT_TIMEOUT,
        enable_cache: bool = ENABLE_CACHE,
        enable_quota: bool = ENABLE_QUOTA,
    ):
        """
        Args:
            account_name: 계정 식별자 (예: 'work', 'personal')
            base_path: skill 루트 경로
            timeout: API 요청 타임아웃 (초)
            enable_cache: 캐시 활성화 여부
            enable_quota: 할당량 관리 활성화 여부
        """
        self.account_name = account_name
        self.timeout = timeout
        self.enable_cache = enable_cache
        self.enable_quota = enable_quota

        if base_path:
            self.base_path = base_path
        elif os.environ.get("GMAIL_SKILL_PATH"):
            self.base_path = Path(os.environ["GMAIL_SKILL_PATH"])
        else:
            self.base_path = Path(__file__).parent.parent

        self.creds = self._load_credentials()
        self._service = None

        # Initialize core components
        self._cache: Optional[EmailCache] = None
        self._quota_manager: Optional[QuotaManager] = None
        self._batch_processor: Optional[BatchProcessor] = None

        if enable_cache:
            cache_dir = os.environ.get("GMAIL_CACHE_DIR") or str(
                self.base_path / ".cache" / "gmail"
            )
            self._cache = EmailCache(cache_dir=cache_dir)

        if enable_quota:
            self._quota_manager = QuotaManager()

    @property
    def service(self):
        """Lazy-load Gmail service."""
        if self._service is None:
            self._service = build("gmail", "v1", credentials=self.creds)
        return self._service

    @property
    def cache(self) -> Optional[EmailCache]:
        """Get cache manager instance."""
        return self._cache

    @property
    def quota_manager(self) -> Optional[QuotaManager]:
        """Get quota manager instance."""
        return self._quota_manager

    @property
    def batch_processor(self) -> BatchProcessor:
        """Get batch processor instance (lazy-loaded)."""
        if self._batch_processor is None:
            self._batch_processor = BatchProcessor(
                service=self.service,
                quota_manager=self._quota_manager,
                user=self.account_name,
            )
        return self._batch_processor

    def _record_quota(self, units: int) -> None:
        """Record quota usage if quota management is enabled."""
        if self._quota_manager:
            self._quota_manager.record_usage(self.account_name, units)

    def _wait_for_quota(self, units: int) -> None:
        """Wait for quota availability if quota management is enabled."""
        if self._quota_manager:
            self._quota_manager.wait_for_quota(self.account_name, units)

    def _load_credentials(self):
        """저장된 refresh token으로 credentials 로드 및 갱신."""
        token_path = self.base_path / f"accounts/{self.account_name}.json"

        if not token_path.exists():
            raise FileNotFoundError(
                f"계정 '{self.account_name}'의 토큰이 없습니다. "
                f"먼저 setup_auth.py --account {self.account_name} 실행 필요"
            )

        with open(token_path) as f:
            token_data = json.load(f)

        if "client_id" in token_data and "type" not in token_data:
            creds = Credentials(
                token=token_data.get("token"),
                refresh_token=token_data.get("refresh_token"),
                token_uri="https://oauth2.googleapis.com/token",
                client_id=token_data.get("client_id"),
                client_secret=token_data.get("client_secret"),
                scopes=self.SCOPES,
            )
            quota_project = token_data.get("quota_project_id", "teamattention")
            creds = creds.with_quota_project(quota_project)
        else:
            creds = Credentials.from_authorized_user_info(token_data, self.SCOPES)

        if creds.expired and creds.refresh_token:
            creds.refresh(Request())
            with open(token_path, "w") as f:
                json.dump(json.loads(creds.to_json()), f, indent=2)

        return creds

    # =========================================================================
    # Messages
    # =========================================================================

    def list_messages(
        self,
        query: str = "",
        max_results: int = 20,
        label_ids: Optional[list[str]] = None,
        include_spam_trash: bool = False,
        use_cache: bool = True,
    ) -> list[dict]:
        """메시지 목록 조회.

        Args:
            query: Gmail 검색 쿼리 (예: "from:user@example.com", "is:unread")
            max_results: 최대 결과 수
            label_ids: 필터할 라벨 ID 목록
            include_spam_trash: 스팸/휴지통 포함 여부
            use_cache: 캐시 사용 여부 (기본값: True)

        Returns:
            메시지 목록 (id, threadId 포함)
        """
        # Check cache first
        if use_cache and self._cache:
            cached = self._cache.get_list(self.account_name, query, label_ids)
            if cached is not None:
                logger.debug(f"Cache hit for list query: {query}")
                return cached[:max_results]

        messages = []
        page_token = None

        @exponential_backoff(max_retries=5)
        def _list_page(**kwargs):
            return self.service.users().messages().list(**kwargs).execute()

        while len(messages) < max_results:
            kwargs = {
                "userId": "me",
                "maxResults": min(max_results - len(messages), 100),
                "includeSpamTrash": include_spam_trash,
            }
            if query:
                kwargs["q"] = query
            if label_ids:
                kwargs["labelIds"] = label_ids
            if page_token:
                kwargs["pageToken"] = page_token

            # Wait for quota before API call
            self._wait_for_quota(QuotaUnit.MESSAGES_LIST)

            result = _list_page(**kwargs)

            # Record quota usage
            self._record_quota(QuotaUnit.MESSAGES_LIST)

            for msg in result.get("messages", []):
                messages.append(msg)

            page_token = result.get("nextPageToken")
            if not page_token:
                break

        # Cache the results
        if use_cache and self._cache and messages:
            self._cache.set_list(self.account_name, query, messages, label_ids)

        return messages

    def get_message(
        self,
        message_id: str,
        format: str = "full",
        use_cache: bool = True,
    ) -> dict:
        """메시지 상세 조회.

        Args:
            message_id: 메시지 ID
            format: 응답 형식 (minimal, full, raw, metadata)
            use_cache: 캐시 사용 여부 (기본값: True)

        Returns:
            메시지 상세 정보
        """
        # Check cache first (only for full/metadata formats)
        if use_cache and self._cache and format in ("full", "metadata"):
            cached = self._cache.get_message(
                self.account_name,
                message_id,
                metadata_only=(format == "metadata"),
            )
            if cached is not None:
                logger.debug(f"Cache hit for message: {message_id}")
                return cached

        @exponential_backoff(max_retries=5)
        def _get_message():
            return (
                self.service.users()
                .messages()
                .get(userId="me", id=message_id, format=format)
                .execute()
            )

        # Wait for quota before API call
        self._wait_for_quota(QuotaUnit.MESSAGES_GET)

        result = _get_message()

        # Record quota usage
        self._record_quota(QuotaUnit.MESSAGES_GET)

        parsed = self._parse_message(result)

        # Cache the result
        if use_cache and self._cache and format in ("full", "metadata"):
            self._cache.set_message(self.account_name, message_id, parsed)

        return parsed

    def _parse_message(self, msg: dict) -> dict:
        """API 응답을 파싱하여 읽기 쉬운 형식으로 변환."""
        headers = {}
        for header in msg.get("payload", {}).get("headers", []):
            name = header["name"].lower()
            if name in ("from", "to", "cc", "bcc", "subject", "date", "message-id"):
                headers[name] = header["value"]

        body = ""
        attachments = []

        payload = msg.get("payload", {})
        body, attachments = self._extract_body_and_attachments(payload, msg["id"])

        return {
            "id": msg["id"],
            "thread_id": msg["threadId"],
            "label_ids": msg.get("labelIds", []),
            "snippet": msg.get("snippet", ""),
            "from": headers.get("from", ""),
            "to": headers.get("to", ""),
            "cc": headers.get("cc", ""),
            "subject": headers.get("subject", "(제목 없음)"),
            "date": headers.get("date", ""),
            "message_id": headers.get("message-id", ""),
            "body": body,
            "attachments": attachments,
            "size_estimate": msg.get("sizeEstimate", 0),
            "internal_date": msg.get("internalDate", ""),
        }

    def _extract_body_and_attachments(
        self, payload: dict, message_id: str
    ) -> tuple[str, list[dict]]:
        """메시지 본문과 첨부파일 추출."""
        body = ""
        attachments = []

        mime_type = payload.get("mimeType", "")

        if mime_type.startswith("multipart/"):
            for part in payload.get("parts", []):
                part_body, part_attachments = self._extract_body_and_attachments(
                    part, message_id
                )
                if part_body:
                    body = part_body
                attachments.extend(part_attachments)
        else:
            if payload.get("filename"):
                attachments.append(
                    {
                        "filename": payload["filename"],
                        "mime_type": mime_type,
                        "size": payload.get("body", {}).get("size", 0),
                        "attachment_id": payload.get("body", {}).get("attachmentId"),
                    }
                )
            elif mime_type in ("text/plain", "text/html"):
                data = payload.get("body", {}).get("data", "")
                if data:
                    decoded = base64.urlsafe_b64decode(data).decode("utf-8")
                    if mime_type == "text/plain" or not body:
                        body = decoded

        return body, attachments

    def get_attachment(self, message_id: str, attachment_id: str) -> bytes:
        """첨부파일 다운로드.

        Args:
            message_id: 메시지 ID
            attachment_id: 첨부파일 ID

        Returns:
            첨부파일 바이너리 데이터
        """
        result = (
            self.service.users()
            .messages()
            .attachments()
            .get(userId="me", messageId=message_id, id=attachment_id)
            .execute()
        )
        return base64.urlsafe_b64decode(result["data"])

    def send_message(
        self,
        to: str,
        subject: str,
        body: str,
        cc: Optional[str] = None,
        bcc: Optional[str] = None,
        html: bool = False,
        attachments: Optional[list[str]] = None,
        reply_to_message_id: Optional[str] = None,
        thread_id: Optional[str] = None,
    ) -> dict:
        """메일 발송.

        Args:
            to: 수신자 (쉼표로 구분 가능)
            subject: 제목
            body: 본문
            cc: 참조
            bcc: 숨은 참조
            html: HTML 형식 여부
            attachments: 첨부파일 경로 목록
            reply_to_message_id: 답장할 메시지 ID (In-Reply-To 헤더용)
            thread_id: 스레드 ID (답장 시)

        Returns:
            발송된 메시지 정보
        """
        if attachments:
            message = MIMEMultipart()
            message.attach(MIMEText(body, "html" if html else "plain", "utf-8"))
            for filepath in attachments:
                self._attach_file(message, filepath)
        else:
            message = MIMEText(body, "html" if html else "plain", "utf-8")

        message["to"] = to
        message["subject"] = subject
        if cc:
            message["cc"] = cc
        if bcc:
            message["bcc"] = bcc
        if reply_to_message_id:
            message["In-Reply-To"] = reply_to_message_id
            message["References"] = reply_to_message_id

        raw = base64.urlsafe_b64encode(message.as_bytes()).decode("utf-8")

        body_data = {"raw": raw}
        if thread_id:
            body_data["threadId"] = thread_id

        @exponential_backoff(max_retries=5)
        def _send():
            return (
                self.service.users().messages().send(userId="me", body=body_data).execute()
            )

        # Wait for quota before API call (send uses 100 units)
        self._wait_for_quota(QuotaUnit.MESSAGES_SEND)

        result = _send()

        # Record quota usage
        self._record_quota(QuotaUnit.MESSAGES_SEND)

        # Invalidate list cache after sending
        if self._cache:
            self._cache.invalidate_lists(self.account_name)

        return {
            "id": result["id"],
            "thread_id": result["threadId"],
            "label_ids": result.get("labelIds", []),
            "status": "sent",
        }

    def _attach_file(self, message: MIMEMultipart, filepath: str) -> None:
        """파일을 메시지에 첨부."""
        path = Path(filepath)
        content_type, encoding = mimetypes.guess_type(str(path))

        if content_type is None:
            content_type = "application/octet-stream"

        main_type, sub_type = content_type.split("/", 1)

        with open(path, "rb") as f:
            data = f.read()

        if main_type == "text":
            attachment = MIMEText(data.decode("utf-8"), _subtype=sub_type)
        elif main_type == "image":
            attachment = MIMEImage(data, _subtype=sub_type)
        elif main_type == "audio":
            attachment = MIMEAudio(data, _subtype=sub_type)
        else:
            attachment = MIMEBase(main_type, sub_type)
            attachment.set_payload(data)
            encoders.encode_base64(attachment)

        attachment.add_header(
            "Content-Disposition", "attachment", filename=path.name
        )
        message.attach(attachment)

    def modify_message(
        self,
        message_id: str,
        add_label_ids: Optional[list[str]] = None,
        remove_label_ids: Optional[list[str]] = None,
    ) -> dict:
        """메시지 라벨 수정.

        Args:
            message_id: 메시지 ID
            add_label_ids: 추가할 라벨 ID
            remove_label_ids: 제거할 라벨 ID

        Returns:
            수정된 메시지 정보
        """
        body = {}
        if add_label_ids:
            body["addLabelIds"] = add_label_ids
        if remove_label_ids:
            body["removeLabelIds"] = remove_label_ids

        @exponential_backoff(max_retries=5)
        def _modify():
            return (
                self.service.users()
                .messages()
                .modify(userId="me", id=message_id, body=body)
                .execute()
            )

        # Wait for quota before API call
        self._wait_for_quota(QuotaUnit.MESSAGES_MODIFY)

        result = _modify()

        # Record quota usage
        self._record_quota(QuotaUnit.MESSAGES_MODIFY)

        # Invalidate cache for this message
        if self._cache:
            self._cache.invalidate_message(self.account_name, message_id)

        return {
            "id": result["id"],
            "thread_id": result["threadId"],
            "label_ids": result.get("labelIds", []),
            "status": "modified",
        }

    def mark_as_read(self, message_id: str) -> dict:
        """읽음으로 표시."""
        return self.modify_message(message_id, remove_label_ids=["UNREAD"])

    def mark_as_unread(self, message_id: str) -> dict:
        """읽지 않음으로 표시."""
        return self.modify_message(message_id, add_label_ids=["UNREAD"])

    def star_message(self, message_id: str) -> dict:
        """별표 추가."""
        return self.modify_message(message_id, add_label_ids=["STARRED"])

    def unstar_message(self, message_id: str) -> dict:
        """별표 제거."""
        return self.modify_message(message_id, remove_label_ids=["STARRED"])

    def archive_message(self, message_id: str) -> dict:
        """보관처리 (INBOX 라벨 제거)."""
        return self.modify_message(message_id, remove_label_ids=["INBOX"])

    def trash_message(self, message_id: str) -> dict:
        """휴지통으로 이동."""
        @exponential_backoff(max_retries=5)
        def _trash():
            return (
                self.service.users()
                .messages()
                .trash(userId="me", id=message_id)
                .execute()
            )

        self._wait_for_quota(QuotaUnit.MESSAGES_TRASH)
        result = _trash()
        self._record_quota(QuotaUnit.MESSAGES_TRASH)

        # Invalidate cache
        if self._cache:
            self._cache.invalidate_message(self.account_name, message_id)
            self._cache.invalidate_lists(self.account_name)

        return {
            "id": result["id"],
            "status": "trashed",
        }

    def untrash_message(self, message_id: str) -> dict:
        """휴지통에서 복원."""
        @exponential_backoff(max_retries=5)
        def _untrash():
            return (
                self.service.users()
                .messages()
                .untrash(userId="me", id=message_id)
                .execute()
            )

        self._wait_for_quota(QuotaUnit.MESSAGES_UNTRASH)
        result = _untrash()
        self._record_quota(QuotaUnit.MESSAGES_UNTRASH)

        # Invalidate cache
        if self._cache:
            self._cache.invalidate_message(self.account_name, message_id)
            self._cache.invalidate_lists(self.account_name)

        return {
            "id": result["id"],
            "status": "untrashed",
        }

    def delete_message(self, message_id: str) -> dict:
        """메시지 영구 삭제 (복구 불가)."""
        @exponential_backoff(max_retries=5)
        def _delete():
            self.service.users().messages().delete(userId="me", id=message_id).execute()

        self._wait_for_quota(QuotaUnit.MESSAGES_DELETE)
        _delete()
        self._record_quota(QuotaUnit.MESSAGES_DELETE)

        # Invalidate cache
        if self._cache:
            self._cache.invalidate_message(self.account_name, message_id)
            self._cache.invalidate_lists(self.account_name)

        return {
            "id": message_id,
            "status": "deleted",
        }

    # =========================================================================
    # Threads
    # =========================================================================

    def list_threads(
        self,
        query: str = "",
        max_results: int = 20,
        label_ids: Optional[list[str]] = None,
    ) -> list[dict]:
        """스레드 목록 조회."""
        threads = []
        page_token = None

        while len(threads) < max_results:
            kwargs = {
                "userId": "me",
                "maxResults": min(max_results - len(threads), 100),
            }
            if query:
                kwargs["q"] = query
            if label_ids:
                kwargs["labelIds"] = label_ids
            if page_token:
                kwargs["pageToken"] = page_token

            result = self.service.users().threads().list(**kwargs).execute()

            for thread in result.get("threads", []):
                threads.append(thread)

            page_token = result.get("nextPageToken")
            if not page_token:
                break

        return threads

    def get_thread(self, thread_id: str, format: str = "full") -> dict:
        """스레드 상세 조회."""
        result = (
            self.service.users()
            .threads()
            .get(userId="me", id=thread_id, format=format)
            .execute()
        )

        messages = [self._parse_message(msg) for msg in result.get("messages", [])]

        return {
            "id": result["id"],
            "messages": messages,
            "message_count": len(messages),
        }

    def trash_thread(self, thread_id: str) -> dict:
        """스레드 휴지통으로 이동."""
        result = (
            self.service.users()
            .threads()
            .trash(userId="me", id=thread_id)
            .execute()
        )
        return {
            "id": result["id"],
            "status": "trashed",
        }

    # =========================================================================
    # Labels
    # =========================================================================

    def list_labels(self, use_cache: bool = True) -> list[dict]:
        """라벨 목록 조회.

        Args:
            use_cache: 캐시 사용 여부 (기본값: True)

        Returns:
            라벨 목록
        """
        # Check cache first
        if use_cache and self._cache:
            cached = self._cache.get_labels(self.account_name)
            if cached is not None:
                logger.debug("Cache hit for labels")
                return cached

        @exponential_backoff(max_retries=5)
        def _list_labels():
            return self.service.users().labels().list(userId="me").execute()

        self._wait_for_quota(QuotaUnit.LABELS_LIST)
        result = _list_labels()
        self._record_quota(QuotaUnit.LABELS_LIST)

        labels = []
        for label in result.get("labels", []):
            labels.append(
                {
                    "id": label["id"],
                    "name": label["name"],
                    "type": label.get("type", "user"),
                    "message_list_visibility": label.get("messageListVisibility"),
                    "label_list_visibility": label.get("labelListVisibility"),
                }
            )

        # Cache the results
        if use_cache and self._cache:
            self._cache.set_labels(self.account_name, labels)

        return labels

    def get_label(self, label_id: str) -> dict:
        """라벨 상세 조회."""
        result = (
            self.service.users().labels().get(userId="me", id=label_id).execute()
        )
        return {
            "id": result["id"],
            "name": result["name"],
            "type": result.get("type", "user"),
            "messages_total": result.get("messagesTotal", 0),
            "messages_unread": result.get("messagesUnread", 0),
            "threads_total": result.get("threadsTotal", 0),
            "threads_unread": result.get("threadsUnread", 0),
        }

    def create_label(
        self,
        name: str,
        message_list_visibility: str = "show",
        label_list_visibility: str = "labelShow",
    ) -> dict:
        """라벨 생성.

        Args:
            name: 라벨 이름
            message_list_visibility: 메시지 목록에서 표시 여부 (show, hide)
            label_list_visibility: 라벨 목록에서 표시 여부 (labelShow, labelHide)

        Returns:
            생성된 라벨 정보
        """
        body = {
            "name": name,
            "messageListVisibility": message_list_visibility,
            "labelListVisibility": label_list_visibility,
        }

        result = (
            self.service.users().labels().create(userId="me", body=body).execute()
        )

        return {
            "id": result["id"],
            "name": result["name"],
            "status": "created",
        }

    def update_label(
        self,
        label_id: str,
        name: Optional[str] = None,
        message_list_visibility: Optional[str] = None,
        label_list_visibility: Optional[str] = None,
    ) -> dict:
        """라벨 수정."""
        result = (
            self.service.users().labels().get(userId="me", id=label_id).execute()
        )

        if name:
            result["name"] = name
        if message_list_visibility:
            result["messageListVisibility"] = message_list_visibility
        if label_list_visibility:
            result["labelListVisibility"] = label_list_visibility

        updated = (
            self.service.users()
            .labels()
            .update(userId="me", id=label_id, body=result)
            .execute()
        )

        return {
            "id": updated["id"],
            "name": updated["name"],
            "status": "updated",
        }

    def delete_label(self, label_id: str) -> dict:
        """라벨 삭제."""
        self.service.users().labels().delete(userId="me", id=label_id).execute()
        return {
            "id": label_id,
            "status": "deleted",
        }

    # =========================================================================
    # Drafts
    # =========================================================================

    def list_drafts(self, max_results: int = 20) -> list[dict]:
        """초안 목록 조회."""
        drafts = []
        page_token = None

        while len(drafts) < max_results:
            kwargs = {
                "userId": "me",
                "maxResults": min(max_results - len(drafts), 100),
            }
            if page_token:
                kwargs["pageToken"] = page_token

            result = self.service.users().drafts().list(**kwargs).execute()

            for draft in result.get("drafts", []):
                drafts.append(draft)

            page_token = result.get("nextPageToken")
            if not page_token:
                break

        return drafts

    def get_draft(self, draft_id: str) -> dict:
        """초안 상세 조회."""
        result = (
            self.service.users()
            .drafts()
            .get(userId="me", id=draft_id, format="full")
            .execute()
        )

        return {
            "id": result["id"],
            "message": self._parse_message(result["message"]),
        }

    def create_draft(
        self,
        to: str,
        subject: str,
        body: str,
        cc: Optional[str] = None,
        bcc: Optional[str] = None,
        html: bool = False,
    ) -> dict:
        """초안 생성.

        Args:
            to: 수신자
            subject: 제목
            body: 본문
            cc: 참조
            bcc: 숨은 참조
            html: HTML 형식 여부

        Returns:
            생성된 초안 정보
        """
        message = MIMEText(body, "html" if html else "plain", "utf-8")
        message["to"] = to
        message["subject"] = subject
        if cc:
            message["cc"] = cc
        if bcc:
            message["bcc"] = bcc

        raw = base64.urlsafe_b64encode(message.as_bytes()).decode("utf-8")

        result = (
            self.service.users()
            .drafts()
            .create(userId="me", body={"message": {"raw": raw}})
            .execute()
        )

        return {
            "id": result["id"],
            "message_id": result["message"]["id"],
            "status": "created",
        }

    def send_draft(self, draft_id: str) -> dict:
        """초안 발송."""
        result = (
            self.service.users()
            .drafts()
            .send(userId="me", body={"id": draft_id})
            .execute()
        )

        return {
            "id": result["id"],
            "thread_id": result["threadId"],
            "label_ids": result.get("labelIds", []),
            "status": "sent",
        }

    def delete_draft(self, draft_id: str) -> dict:
        """초안 삭제."""
        self.service.users().drafts().delete(userId="me", id=draft_id).execute()
        return {
            "id": draft_id,
            "status": "deleted",
        }

    # =========================================================================
    # Profile
    # =========================================================================

    def get_profile(self) -> dict:
        """계정 프로필 조회."""
        @exponential_backoff(max_retries=5)
        def _get_profile():
            return self.service.users().getProfile(userId="me").execute()

        self._wait_for_quota(QuotaUnit.PROFILE_GET)
        result = _get_profile()
        self._record_quota(QuotaUnit.PROFILE_GET)

        return {
            "email": result["emailAddress"],
            "messages_total": result.get("messagesTotal", 0),
            "threads_total": result.get("threadsTotal", 0),
            "history_id": result.get("historyId", ""),
        }

    # =========================================================================
    # Batch Operations (P1)
    # =========================================================================

    def batch_get_messages(
        self,
        message_ids: list[str],
        format: str = "metadata",
    ) -> dict:
        """메시지 일괄 조회.

        Args:
            message_ids: 조회할 메시지 ID 목록
            format: 응답 형식 (minimal, full, raw, metadata)

        Returns:
            BatchResult 객체 (total, succeeded, failed, results, errors)
        """
        return self.batch_processor.batch_get_messages(message_ids, format)

    def batch_modify_labels(
        self,
        message_ids: list[str],
        add_labels: Optional[list[str]] = None,
        remove_labels: Optional[list[str]] = None,
    ) -> dict:
        """라벨 일괄 수정.

        Args:
            message_ids: 수정할 메시지 ID 목록
            add_labels: 추가할 라벨 ID
            remove_labels: 제거할 라벨 ID

        Returns:
            BatchResult 객체
        """
        result = self.batch_processor.batch_modify_labels(
            message_ids, add_labels, remove_labels
        )

        # Invalidate cache for modified messages
        if self._cache:
            for msg_id in message_ids:
                self._cache.invalidate_message(self.account_name, msg_id)
            self._cache.invalidate_lists(self.account_name)

        return result

    def batch_trash_messages(self, message_ids: list[str]) -> dict:
        """메시지 일괄 휴지통 이동.

        Args:
            message_ids: 휴지통으로 이동할 메시지 ID 목록

        Returns:
            BatchResult 객체
        """
        result = self.batch_processor.batch_trash_messages(message_ids)

        # Invalidate cache
        if self._cache:
            for msg_id in message_ids:
                self._cache.invalidate_message(self.account_name, msg_id)
            self._cache.invalidate_lists(self.account_name)

        return result

    def batch_delete_messages(self, message_ids: list[str]) -> dict:
        """메시지 일괄 영구 삭제.

        주의: 이 작업은 되돌릴 수 없습니다!

        Args:
            message_ids: 삭제할 메시지 ID 목록

        Returns:
            BatchResult 객체
        """
        result = self.batch_processor.batch_delete_messages(message_ids)

        # Invalidate cache
        if self._cache:
            for msg_id in message_ids:
                self._cache.invalidate_message(self.account_name, msg_id)
            self._cache.invalidate_lists(self.account_name)

        return result

    def mark_all_as_read(
        self,
        query: str = "is:unread",
        max_messages: int = 500,
    ) -> dict:
        """조건에 맞는 메시지 전체 읽음 처리.

        Args:
            query: 검색 쿼리 (기본: 읽지 않음)
            max_messages: 최대 처리 메시지 수

        Returns:
            BatchResult 객체
        """
        result = self.batch_processor.mark_all_as_read(query, max_messages)

        # Invalidate cache
        if self._cache:
            self._cache.invalidate_lists(self.account_name)

        return result

    def archive_all(
        self,
        query: str = "",
        max_messages: int = 500,
    ) -> dict:
        """조건에 맞는 메시지 전체 보관처리.

        Args:
            query: 검색 쿼리
            max_messages: 최대 처리 메시지 수

        Returns:
            BatchResult 객체
        """
        result = self.batch_processor.archive_all(query, max_messages)

        # Invalidate cache
        if self._cache:
            self._cache.invalidate_lists(self.account_name)

        return result

    # =========================================================================
    # Cache & Quota Management
    # =========================================================================

    def get_quota_status(self) -> dict:
        """현재 할당량 사용 현황 조회.

        Returns:
            할당량 사용 현황 딕셔너리
        """
        if self._quota_manager:
            return self._quota_manager.get_usage(self.account_name)
        return {"message": "Quota management is disabled"}

    def get_cache_stats(self) -> dict:
        """캐시 통계 조회.

        Returns:
            캐시 통계 딕셔너리
        """
        if self._cache:
            return self._cache.get_stats(self.account_name)
        return {"message": "Caching is disabled"}

    def clear_cache(self) -> None:
        """이 계정의 캐시 전체 삭제."""
        if self._cache:
            self._cache.invalidate_account(self.account_name)
            logger.info(f"Cache cleared for account: {self.account_name}")


class ADCGmailClient:
    """Application Default Credentials를 사용하는 Gmail 클라이언트.

    gcloud auth application-default login으로 인증된 계정 사용.
    """

    SCOPES = [
        "https://www.googleapis.com/auth/gmail.modify",
        "https://www.googleapis.com/auth/gmail.send",
        "https://www.googleapis.com/auth/gmail.labels",
    ]

    def __init__(self, account_name: str = "default", timeout: int = DEFAULT_TIMEOUT):
        self.account_name = account_name
        self.timeout = timeout
        self.creds, self.project = google.auth.default(scopes=self.SCOPES)
        self._service = None

    @property
    def service(self):
        if self._service is None:
            self._service = build("gmail", "v1", credentials=self.creds)
        return self._service

    def list_messages(
        self,
        query: str = "",
        max_results: int = 20,
        label_ids: Optional[list[str]] = None,
        include_spam_trash: bool = False,
    ) -> list[dict]:
        messages = []
        page_token = None

        while len(messages) < max_results:
            kwargs = {
                "userId": "me",
                "maxResults": min(max_results - len(messages), 100),
                "includeSpamTrash": include_spam_trash,
            }
            if query:
                kwargs["q"] = query
            if label_ids:
                kwargs["labelIds"] = label_ids
            if page_token:
                kwargs["pageToken"] = page_token

            result = self.service.users().messages().list(**kwargs).execute()

            for msg in result.get("messages", []):
                messages.append(msg)

            page_token = result.get("nextPageToken")
            if not page_token:
                break

        return messages

    def get_profile(self) -> dict:
        result = self.service.users().getProfile(userId="me").execute()
        return {
            "email": result["emailAddress"],
            "messages_total": result.get("messagesTotal", 0),
            "threads_total": result.get("threadsTotal", 0),
        }


def get_all_accounts(base_path: Optional[Path] = None) -> list[str]:
    """등록된 모든 계정 이름 반환."""
    base_path = base_path or Path(__file__).parent.parent
    accounts_dir = base_path / "accounts"

    if not accounts_dir.exists():
        return []

    return [
        f.stem for f in accounts_dir.glob("*.json") if f.stem not in ("credentials",)
    ]


def get_client(
    account_name: Optional[str] = None,
    use_adc: bool = False,
    base_path: Optional[Path] = None,
) -> GmailClient:
    """Gmail 클라이언트 팩토리.

    Args:
        account_name: 계정 이름 (None이면 첫 번째 계정 사용)
        use_adc: ADC 사용 여부
        base_path: skill 루트 경로

    Returns:
        GmailClient 또는 ADCGmailClient 인스턴스
    """
    if use_adc:
        return ADCGmailClient(account_name or "default")

    if account_name:
        return GmailClient(account_name, base_path)

    accounts = get_all_accounts(base_path)
    if not accounts:
        raise ValueError(
            "등록된 계정이 없습니다. setup_auth.py --account <이름> 실행 필요"
        )

    return GmailClient(accounts[0], base_path)


================================================
FILE: plugins/gmail/skills/gmail/scripts/list_messages.py
================================================
#!/usr/bin/env python3
"""Gmail 메시지 목록 조회 CLI.

Usage:
    # 받은편지함 최근 10개
    uv run python list_messages.py --account work --max 10

    # 검색 쿼리 사용
    uv run python list_messages.py --account work --query "from:user@example.com"
    uv run python list_messages.py --account work --query "is:unread"
    uv run python list_messages.py --account work --query "after:2024/01/01 before:2024/12/31"

    # 라벨로 필터
    uv run python list_messages.py --account work --labels INBOX,UNREAD

    # ADC 사용
    uv run python list_messages.py --adc --query "is:unread"
"""

import argparse
import json
from pathlib import Path

from gmail_client import GmailClient, ADCGmailClient, get_all_accounts


def format_message_summary(client: GmailClient, msg_id: str) -> dict:
    """메시지 요약 정보 조회."""
    msg = client.get_message(msg_id, format="metadata")
    return {
        "id": msg["id"],
        "from": msg["from"],
        "subject": msg["subject"],
        "date": msg["date"],
        "snippet": msg["snippet"][:100] + "..." if len(msg["snippet"]) > 100 else msg["snippet"],
        "labels": msg["label_ids"],
    }


def main():
    parser = argparse.ArgumentParser(description="Gmail 메시지 목록 조회")
    parser.add_argument("--account", "-a", help="계정 식별자")
    parser.add_argument("--adc", action="store_true", help="Application Default Credentials 사용")
    parser.add_argument("--query", "-q", default="", help="Gmail 검색 쿼리")
    parser.add_argument("--max", "-m", type=int, default=20, help="최대 결과 수")
    parser.add_argument("--labels", help="라벨 ID (쉼표 구분)")
    parser.add_argument("--include-spam-trash", action="store_true", help="스팸/휴지통 포함")
    parser.add_argument("--full", "-f", action="store_true", help="전체 메시지 정보 조회")
    parser.add_argument("--json", action="store_true", help="JSON 형식 출력")

    args = parser.parse_args()
    base_path = Path(__file__).parent.parent

    if args.adc:
        client = ADCGmailClient()
    else:
        accounts = get_all_accounts(base_path)
        if not accounts:
            print("❌ 등록된 계정이 없습니다.")
            print("   먼저 setup_auth.py --account <이름> 실행 필요")
            return

        account = args.account or accounts[0]
        client = GmailClient(account, base_path)

    label_ids = args.labels.split(",") if args.labels else None

    messages = client.list_messages(
        query=args.query,
        max_results=args.max,
        label_ids=label_ids,
        include_spam_trash=args.include_spam_trash,
    )

    if args.json:
        if args.full:
            result = [client.get_message(m["id"]) for m in messages]
        else:
            result = [format_message_summary(client, m["id"]) for m in messages]
        print(json.dumps(result, ensure_ascii=False, indent=2))
    else:
        print(f"📬 {len(messages)}개 메시지")
        print()
        for msg in messages:
            if args.full:
                full_msg = client.get_message(msg["id"])
                print(f"ID: {full_msg['id']}")
                print(f"From: {full_msg['from']}")
                print(f"To: {full_msg['to']}")
                print(f"Subject: {full_msg['subject']}")
                print(f"Date: {full_msg['date']}")
                print(f"Labels: {', '.join(full_msg['label_ids'])}")
                if full_msg['attachments']:
                    print(f"Attachments: {', '.join(a['filename'] for a in full_msg['attachments'])}")
                print("-" * 60)
                print(full_msg['body'][:500])
                if len(full_msg['body']) > 500:
                    print("... (truncated)")
                print("=" * 60)
                print()
            else:
                summary = format_message_summary(client, msg["id"])
                unread = "📩" if "UNREAD" in summary["labels"] else "📧"
                print(f"{unread} {summary['subject']}")
                print(f"   From: {summary['from']}")
                print(f"   Date: {summary['date']}")
                print(f"   {summary['snippet']}")
                print()


if __name__ == "__main__":
    main()


================================================
FILE: plugins/gmail/skills/gmail/scripts/manage_labels.py
================================================
#!/usr/bin/env python3
"""Gmail 라벨 및 메시지 관리 CLI.

Usage:
    # 라벨 목록
    uv run python manage_labels.py --account work list-labels

    # 라벨 생성
    uv run python manage_labels.py --account work create-label --name "프로젝트/A"

    # 라벨 삭제
    uv run python manage_labels.py --account work delete-label --label-id Label_123

    # 읽음 표시
    uv run python manage_labels.py --account work mark-read --id <message_id>

    # 별표 추가
    uv run python manage_labels.py --account work star --id <message_id>

    # 보관처리
    uv run python manage_labels.py --account work archive --id <message_id>

    # 휴지통으로 이동
    uv run python manage_labels.py --account work trash --id <message_id>

    # 라벨 추가/제거
    uv run python manage_labels.py --account work modify --id <message_id> \
        --add-labels "Label_123,STARRED" --remove-labels "INBOX"

    # 초안 목록
    uv run python manage_labels.py --account work list-drafts

    # 초안 발송
    uv run python manage_labels.py --account work send-draft --draft-id <draft_id>

    # 프로필 조회
    uv run python manage_labels.py --account work profile
"""

import argparse
import json
from pathlib import Path

from gmail_client import GmailClient, ADCGmailClient, get_all_accounts


def main():
    parser = argparse.ArgumentParser(description="Gmail 라벨 및 메시지 관리")
    parser.add_argument("--account", "-a", help="계정 식별자")
    parser.add_argument("--adc", action="store_true", help="Application Default Credentials 사용")
    parser.add_argument("--json", action="store_true", help="JSON 형식 출력")

    subparsers = parser.add_subparsers(dest="command", help="명령어")

    # 라벨 관리
    subparsers.add_parser("list-labels", help="라벨 목록")

    create_label = subparsers.add_parser("create-label", help="라벨 생성")
    create_label.add_argument("--name", required=True, help="라벨 이름")

    delete_label = subparsers.add_parser("delete-label", help="라벨 삭제")
    delete_label.add_argument("--label-id", required=True, help="라벨 ID")

    # 메시지 관리
    mark_read = subparsers.add_parser("mark-read", help="읽음 표시")
    mark_read.add_argument("--id", required=True, help="메시지 ID")

    mark_unread = subparsers.add_parser("mark-unread", help="읽지 않음 표시")
    mark_unread.add_argument("--id", required=True, help="메시지 ID")

    star = subparsers.add_parser("star", help="별표 추가")
    star.add_argument("--id", required=True, help="메시지 ID")

    unstar = subparsers.add_parser("unstar", help="별표 제거")
    unstar.add_argument("--id", required=True, help="메시지 ID")

    archive = subparsers.add_parser("archive", help="보관처리")
    archive.add_argument("--id", required=True, help="메시지 ID")

    trash = subparsers.add_parser("trash", help="휴지통으로 이동")
    trash.add_argument("--id", required=True, help="메시지 ID")

    untrash = subparsers.add_parser("untrash", help="휴지통에서 복원")
    untrash.add_argument("--id", required=True, help="메시지 ID")

    modify = subparsers.add_parser("modify", help="라벨 수정")
    modify.add_argument("--id", required=True, help="메시지 ID")
    modify.add_argument("--add-labels", help="추가할 라벨 (쉼표 구분)")
    modify.add_argument("--remove-labels", help="제거할 라벨 (쉼표 구분)")

    # 초안 관리
    subparsers.add_parser("list-drafts", help="초안 목록")

    send_draft = subparsers.add_parser("send-draft", help="초안 발송")
    send_draft.add_argument("--draft-id", required=True, help="초안 ID")

    delete_draft = subparsers.add_parser("delete-draft", help="초안 삭제")
    delete_draft.add_argument("--draft-id", required=True, help="초안 ID")

    # 프로필
    subparsers.add_parser("profile", help="프로필 조회")

    args = parser.parse_args()
    base_path = Path(__file__).parent.parent

    if not args.command:
        parser.print_help()
        return

    if args.adc:
        client = ADCGmailClient()
    else:
        accounts = get_all_accounts(base_path)
        if not accounts:
            print("❌ 등록된 계정이 없습니다.")
            return

        account = args.account or accounts[0]
        client = GmailClient(account, base_path)

    result = None

    # 라벨 명령어
    if args.command == "list-labels":
        result = client.list_labels()
        if not args.json:
            print("🏷️  라벨 목록:")
            for label in result:
                label_type = "📁" if label["type"] == "system" else "🏷️"
                print(f"  {label_type} {label['name']} ({label['id']})")
            return

    elif args.command == "create-label":
        result = client.create_label(args.name)
        if not args.json:
            print(f"✅ 라벨 생성됨: {result['name']} ({result['id']})")
            return

    elif args.command == "delete-label":
        result = client.delete_label(args.label_id)
        if not args.json:
            print(f"✅ 라벨 삭제됨: {args.label_id}")
            return

    # 메시지 명령어
    elif args.command == "mark-read":
        result = client.mark_as_read(args.id)
    elif args.command == "mark-unread":
        result = client.mark_as_unread(args.id)
    elif args.command == "star":
        result = client.star_message(args.id)
    elif args.command == "unstar":
        result = client.unstar_message(args.id)
    elif args.command == "archive":
        result = client.archive_message(args.id)
    elif args.command == "trash":
        result = client.trash_message(args.id)
    elif args.command == "untrash":
        result = client.untrash_message(args.id)
    elif args.command == "modify":
        add_labels = args.add_labels.split(",") if args.add_labels else None
        remove_labels = args.remove_labels.split(",") if args.remove_labels else None
        result = client.modify_message(args.id, add_labels, remove_labels)

    # 초안 명령어
    elif args.command == "list-drafts":
        drafts = client.list_drafts()
        if not args.json:
            print(f"📝 초안 {len(drafts)}개")
            for draft in drafts:
                detail = client.get_draft(draft["id"])
                msg = detail["message"]
                print(f"  - {msg['subject']} → {msg['to']}")
                print(f"    ID: {draft['id']}")
            return
        result = drafts

    elif args.command == "send-draft":
        result = client.send_draft(args.draft_id)
        if not args.json:
            print(f"✅ 초안 발송됨: {result['id']}")
            return

    elif args.command == "delete-draft":
        result = client.delete_draft(args.draft_id)
        if not args.json:
            print(f"✅ 초안 삭제됨: {args.draft_id}")
            return

    # 프로필
    elif args.command == "profile":
        result = client.get_profile()
        if not args.json:
            print(f"📧 {result['email']}")
            print(f"   메시지: {result['messages_total']:,}개")
            print(f"   스레드: {result['threads_total']:,}개")
            return

    if args.json and result:
        print(json.dumps(result, ensure_ascii=False, indent=2))
    elif result:
        print(f"✅ {args.command} 완료")
        print(f"   ID: {result.get('id')}")


if __name__ == "__main__":
    main()


================================================
FILE: plugins/gmail/skills/gmail/scripts/read_message.py
================================================
#!/usr/bin/env python3
"""Gmail 메시지 읽기 CLI.

Usage:
    # 메시지 읽기
    uv run python read_message.py --account work --id <message_id>

    # 스레드 전체 읽기
    uv run python read_message.py --account work --thread <thread_id>

    # 첨부파일 저장
    uv run python read_message.py --account work --id <message_id> --save-attachments ./downloads

    # JSON 출력
    uv run python read_message.py --account work --id <message_id> --json
"""

import argparse
import json
from pathlib import Path

from gmail_client import GmailClient, ADCGmailClient, get_all_accounts


def main():
    parser = argparse.ArgumentParser(description="Gmail 메시지 읽기")
    parser.add_argument("--account", "-a", help="계정 식별자")
    parser.add_argument("--adc", action="store_true", help="Application Default Credentials 사용")
    parser.add_argument("--id", "-i", help="메시지 ID")
    parser.add_argument("--thread", "-t", help="스레드 ID")
    parser.add_argument("--save-attachments", "-s", help="첨부파일 저장 경로")
    parser.add_argument("--json", action="store_true", help="JSON 형식 출력")

    args = parser.parse_args()
    base_path = Path(__file__).parent.parent

    if not args.id and not args.thread:
        parser.print_help()
        print()
        print("예시:")
        print("  uv run python read_message.py --account work --id abc123")
        print("  uv run python read_message.py --account work --thread xyz789")
        return

    if args.adc:
        client = ADCGmailClient()
    else:
        accounts = get_all_accounts(base_path)
        if not accounts:
            print("❌ 등록된 계정이 없습니다.")
            return

        account = args.account or accounts[0]
        client = GmailClient(account, base_path)

    if args.thread:
        result = client.get_thread(args.thread)

        if args.json:
            print(json.dumps(result, ensure_ascii=False, indent=2))
        else:
            print(f"📧 스레드: {result['id']}")
            print(f"   메시지 수: {result['message_count']}")
            print("=" * 60)

            for msg in result["messages"]:
                print(f"\n📩 {msg['subject']}")
                print(f"   From: {msg['from']}")
                print(f"   To: {msg['to']}")
                print(f"   Date: {msg['date']}")
                print("-" * 60)
                print(msg['body'])
                print()
    else:
        result = client.get_message(args.id)

        if args.json:
            print(json.dumps(result, ensure_ascii=False, indent=2))
        else:
            print(f"📧 Subject: {result['subject']}")
            print(f"   From: {result['from']}")
            print(f"   To: {result['to']}")
            if result['cc']:
                print(f"   CC: {result['cc']}")
            print(f"   Date: {result['date']}")
            print(f"   Labels: {', '.join(result['label_ids'])}")

            if result['attachments']:
                print(f"\n📎 첨부파일:")
                for att in result['attachments']:
                    size_kb = att['size'] / 1024
                    print(f"   - {att['filename']} ({size_kb:.1f} KB)")

            print("\n" + "=" * 60)
            print(result['body'])

        if args.save_attachments and result.get('attachments'):
            save_path = Path(args.save_attachments)
            save_path.mkdir(parents=True, exist_ok=True)

            for att in result['attachments']:
                if att.get('attachment_id'):
                    data = client.get_attachment(args.id, att['attachment_id'])
                    filepath = save_path / att['filename']
                    with open(filepath, 'wb') as f:
                        f.write(data)
                    print(f"✅ 저장됨: {filepath}")


if __name__ == "__main__":
    main()


================================================
FILE: plugins/gmail/skills/gmail/scripts/send_message.py
================================================
#!/usr/bin/env python3
"""Gmail 메시지 발송 CLI.

Usage:
    # 새 메일 발송
    uv run python send_message.py --account work \
        --to "user@example.com" \
        --subject "안녕하세요" \
        --body "메일 내용입니다."

    # HTML 메일
    uv run python send_message.py --account work \
        --to "user@example.com" \
        --subject "공지" \
        --body "<h1>제목</h1><p>내용</p>" \
        --html

    # 첨부파일 포함
    uv run python send_message.py --account work \
        --to "user@example.com" \
        --subject "파일 전송" \
        --body "첨부파일을 확인해주세요." \
        --attach file1.pdf,file2.xlsx

    # 답장
    uv run python send_message.py --account work \
        --to "user@example.com" \
        --subject "Re: 원본 제목" \
        --body "답장 내용" \
        --reply-to <message_id> \
        --thread <thread_id>

    # 초안 생성
    uv run python send_message.py --account work \
        --to "user@example.com" \
        --subject "나중에 보낼 메일" \
        --body "초안 내용" \
        --draft
"""

import argparse
import json
from pathlib import Path

from gmail_client import ADCGmailClient, GmailClient, get_all_accounts


def main():
    parser = argparse.ArgumentParser(description="Gmail 메시지 발송")
    parser.add_argument("--account", "-a", help="계정 식별자")
    parser.add_argument("--adc", action="store_true", help="Application Default Credentials 사용")
    parser.add_argument("--to", "-t", required=True, help="수신자 (쉼표 구분)")
    parser.add_argument("--subject", "-s", required=True, help="제목")
    parser.add_argument("--body", "-b", required=True, help="본문")
    parser.add_argument("--cc", help="참조")
    parser.add_argument("--bcc", help="숨은 참조")
    parser.add_argument("--html", action="store_true", help="HTML 형식")
    parser.add_argument("--attach", help="첨부파일 경로 (쉼표 구분)")
    parser.add_argument("--reply-to", help="답장할 메시지 ID")
    parser.add_argument("--thread", help="스레드 ID")
    parser.add_argument("--draft", action="store_true", help="초안으로 저장")
    parser.add_argument("--json", action="store_true", help="JSON 형식 출력")

    args = parser.parse_args()
    base_path = Path(__file__).parent.parent

    if args.adc:
        client = ADCGmailClient()
    else:
        accounts = get_all_accounts(base_path)
        if not accounts:
            print("❌ 등록된 계정이 없습니다.")
            return

        account = args.account or accounts[0]
        client = GmailClient(account, base_path)

    attachments = args.attach.split(",") if args.attach else None

    if args.draft:
        result = client.create_draft(
            to=args.to,
            subject=args.subject,
            body=args.body,
            cc=args.cc,
            bcc=args.bcc,
            html=args.html,
        )
        status_msg = "초안 저장됨"
    else:
        result = client.send_message(
            to=args.to,
            subject=args.subject,
            body=args.body,
            cc=args.cc,
            bcc=args.bcc,
            html=args.html,
            attachments=attachments,
            reply_to_message_id=args.reply_to,
            thread_id=args.thread,
        )
        status_msg = "발송 완료"

    if args.json:
        print(json.dumps(result, ensure_ascii=False, indent=2))
    else:
        print(f"✅ {status_msg}")
        print(f"   ID: {result['id']}")
        if 'thread_id' in result:
            print(f"   Thread ID: {result['thread_id']}")


if __name__ == "__main__":
    main()


================================================
FILE: plugins/gmail/skills/gmail/scripts/setup_auth.py
================================================
#!/usr/bin/env python3
"""Gmail OAuth 인증 설정.

최초 1회 실행하여 계정별 refresh token을 저장.
이후에는 저장된 token으로 자동 인증됨.

Usage:
    uv run python setup_auth.py --account personal --email user@gmail.com
    uv run python setup_auth.py --account work --email work@company.com --description "회사 업무용"
    uv run python setup_auth.py --list
"""

import argparse
import json
from pathlib import Path

import yaml
from google_auth_oauthlib.flow import InstalledAppFlow

SCOPES = [
    "https://www.googleapis.com/auth/gmail.modify",  # 읽기/수정/삭제
    "https://www.googleapis.com/auth/gmail.send",    # 메일 발송
    "https://www.googleapis.com/auth/gmail.labels",  # 라벨 관리
]


def load_accounts_config(base_path: Path) -> dict:
    """accounts.yaml 로드."""
    config_path = base_path / "accounts.yaml"
    if config_path.exists():
        with open(config_path) as f:
            return yaml.safe_load(f) or {"accounts": {}}
    return {"accounts": {}}


def save_accounts_config(base_path: Path, config: dict) -> None:
    """accounts.yaml 저장."""
    config_path = base_path / "accounts.yaml"

    # YAML 헤더 코멘트
    header = """# Gmail 계정 설정
# 계정별로 이메일 주소와 설명을 관리합니다.
# 토큰 파일은 accounts/{name}.json에 별도 저장됩니다.

"""

    with open(config_path, "w") as f:
        f.write(header)
        yaml.dump(config, f, allow_unicode=True, default_flow_style=False, sort_keys=False)


def setup_auth(
    account_name: str,
    base_path: Path,
    email: str | None = None,
    description: str | None = None,
) -> None:
    """OAuth 인증 플로우 실행 및 토큰 저장.

    Args:
        account_name: 계정 식별자 (예: 'work', 'personal')
        base_path: skill 루트 경로
        email: 이메일 주소 (accounts.yaml에 저장)
        description: 계정 설명 (accounts.yaml에 저장)
    """
    credentials_path = base_path / "references" / "credentials.json"
    token_path = base_path / "accounts" / f"{account_name}.json"

    if not credentials_path.exists():
        print(f"❌ OAuth Client ID 파일이 없습니다: {credentials_path}")
        print()
        print("설정 방법:")
        print("1. https://console.cloud.google.com 접속")
        print("2. 프로젝트 생성 또는 선택")
        print("3. 'API 및 서비스' > 'Gmail API' 활성화")
        print("4. 'API 및 서비스' > '사용자 인증 정보'")
        print("5. 'OAuth 2.0 클라이언트 ID' 생성 (Desktop 유형)")
        print("6. JSON 다운로드 → references/credentials.json 저장")
        return

    if token_path.exists():
        print(f"⚠️  계정 '{account_name}'의 토큰이 이미 존재합니다.")
        response = input("덮어쓰시겠습니까? [y/N]: ")
        if response.lower() != "y":
            print("취소됨")
            return

    print(f"🔐 '{account_name}' 계정 인증을 시작합니다...")
    print("브라우저가 열리면 Google 계정으로 로그인하세요.")
    print()

    flow = InstalledAppFlow.from_client_secrets_file(
        str(credentials_path),
        SCOPES,
    )

    creds = flow.run_local_server(port=0)

    token_path.parent.mkdir(parents=True, exist_ok=True)
    with open(token_path, "w") as f:
        json.dump(json.loads(creds.to_json()), f, indent=2)

    # accounts.yaml 업데이트
    config = load_accounts_config(base_path)

    # 인증된 이메일 주소 가져오기 (제공되지 않은 경우)
    if not email:
        try:
            from googleapiclient.discovery import build
            from google.oauth2.credentials import Credentials

            temp_creds = Credentials.from_authorized_user_info(
                json.loads(creds.to_json()),
                SCOPES,
            )
            service = build("gmail", "v1", credentials=temp_creds)
            profile = service.users().getProfile(userId="me").execute()
            email = profile.get("emailAddress", "")
        except Exception:
            email = ""

    config["accounts"][account_name] = {
        "email": email,
        "description": description or "",
    }
    save_accounts_config(base_path, config)

    print()
    print(f"✅ 인증 완료!")
    print(f"   계정명: {account_name}")
    print(f"   이메일: {email}")
    print(f"   토큰: {token_path}")


def list_accounts(base_path: Path) -> None:
    """등록된 계정 목록 출력."""
    config = load_accounts_config(base_path)
    accounts_dir = base_path / "accounts"

    # accounts.yaml에서 계정 정보 읽기
    accounts_config = config.get("accounts", {})

    # 토큰 파일 존재 여부 확인
    token_files = set()
    if accounts_dir.exists():
        token_files = {f.stem for f in accounts_dir.glob("*.json")}

    if not accounts_config and not token_files:
        print("등록된 계정이 없습니다.")
        return

    print("📋 등록된 계정:")
    print()

    # accounts.yaml에 있는 계정 출력
    for name, info in accounts_config.items():
        email = info.get("email", "")
        description = info.get("description", "")
        has_token = "✅" if name in token_files else "❌"

        print(f"   {has_token} {name}")
        if email:
            print(f"      이메일: {email}")
        if description:
            print(f"      설명: {description}")
        print()

    # 토큰은 있지만 accounts.yaml에 없는 계정 경고
    orphan_tokens = token_files - set(accounts_config.keys())
    if orphan_tokens:
        print("⚠️  accounts.yaml에 없는 토큰:")
        for name in orphan_tokens:
            print(f"   - {name}.json")


def main():
    parser = argparse.ArgumentParser(description="Gmail OAuth 인증 설정")
    parser.add_argument(
        "--account",
        "-a",
        help="계정 식별자 (예: work, personal)",
    )
    parser.add_argument(
        "--email",
        "-e",
        help="이메일 주소 (자동 감지되지만 명시 가능)",
    )
    parser.add_argument(
        "--description",
        "-d",
        help="계정 설명 (예: '회사 업무용')",
    )
    parser.add_argument(
        "--list",
        "-l",
        action="store_true",
        help="등록된 계정 목록 출력",
    )

    args = parser.parse_args()
    base_path = Path(__file__).parent.parent

    if args.list:
        list_accounts(base_path)
        return

    if not args.account:
        parser.print_help()
        print()
        print("예시:")
        print("  uv run python setup_auth.py --account personal --description '개인 Gmail'")
        print("  uv run python setup_auth.py --account work --description '회사 업무용'")
        print("  uv run python setup_auth.py --list")
        return

    setup_auth(args.account, base_path, args.email, args.description)


if __name__ == "__main__":
    main()


================================================
FILE: plugins/google-calendar/.claude-plugin/plugin.json
================================================
{
  "name": "google-calendar",
  "version": "1.0.0",
  "description": "Multi-account Google Calendar integration with parallel querying and conflict detection"
}


================================================
FILE: plugins/google-calendar/README.md
================================================
# Google Calendar Plugin

Multi-account Google Calendar integration with parallel querying and conflict detection.

## Features

- Query multiple Google accounts (work, personal) in parallel
- Detect scheduling conflicts between calendars
- Create, update, and delete events
- OAuth2 authentication with stored refresh tokens

## Installation

```bash
/plugin install google-calendar
```

## Prerequisites

### 1. Google Cloud Project Setup

1. Create a project at [Google Cloud Console](https://console.cloud.google.com)
2. Enable Calendar API
3. Create OAuth 2.0 Client ID (Desktop type)
4. Download `credentials.json`

### 2. Account Authentication (one-time)

```bash
# Work account
uv run python scripts/setup_auth.py --account work

# Personal account
uv run python scripts/setup_auth.py --account personal
```

## Usage

Ask Claude about your calendar:

- "오늘 일정 알려줘"
- "이번 주 일정 충돌 확인해줘"
- "내일 3시에 팀 미팅 추가해줘"
- "What's on my calendar today?"
- "Schedule a meeting for tomorrow at 2pm"

## License

MIT


================================================
FILE: plugins/google-calendar/skills/google-calendar/SKILL.md
================================================
---
name: google-calendar
description: Google 캘린더 일정 조회/생성/수정/삭제. "오늘 일정", "이번 주 일정", "미팅 추가해줘" 요청에 사용. 여러 계정(work, personal) 통합 조회 지원.
---

# Google Calendar Sync

## Overview

여러 Google 계정(회사, 개인 등)의 캘린더를 한 번에 조회하여 통합된 일정을 제공한다.
- 사전 인증된 refresh token 사용 (매번 로그인 불필요)
- Subagent 병렬 실행으로 빠른 조회
- 계정 간 일정 충돌 감지

## 트리거 조건

### 조회
- "오늘 일정", "이번 주 일정 알려줘"
- "캘린더 확인", "스케줄 뭐야"
- "다음 미팅", "내일 뭐 있어"
- "일정 충돌 확인해줘"

### 생성
- "새 일정 만들어줘", "미팅 추가해줘"
- "내일 3시에 회의 잡아줘"
- "다음 주 월요일 팀 미팅 생성"

### 수정
- "일정 시간 변경해줘", "미팅 시간 바꿔줘"
- "sync 미팅 14시 21분으로 변경"
- "회의 제목 수정해줘"

### 삭제
- "일정 삭제해줘", "미팅 취소해줘"
- "이벤트 지워줘"

## 사전 요구사항

### 1. Google Cloud 프로젝트 설정

1. [Google Cloud Console](https://console.cloud.google.com)에서 프로젝트 생성
2. Calendar API 활성화
3. OAuth 2.0 Client ID 생성 (Desktop 유형)
4. `credentials.json` 다운로드 → `references/credentials.json`에 저장

### 2. 계정별 인증 (최초 1회)

```bash
# 회사 계정
uv run python .claude/skills/google-calendar/scripts/setup_auth.py --account work

# 개인 계정
uv run python .claude/skills/google-calendar/scripts/setup_auth.py --account personal
```

브라우저에서 Google 로그인 → refresh token이 `accounts/{name}.json`에 저장됨

## 워크플로우

### 1. 등록된 계정 확인

```bash
ls .claude/skills/google-calendar/accounts/
# → work.json, personal.json
```

### 2. Subagent 병렬 실행

각 계정별로 Task 도구를 **병렬**로 호출:

```python
# 병렬 실행 - 단일 메시지에 여러 Task 호출
Task(subagent_type="general-purpose", prompt="fetch calendar for work account")
Task(subagent_type="general-purpose", prompt="fetch calendar for personal account")
```

각 subagent는 다음을 실행:
```bash
uv run python .claude/skills/google-calendar/scripts/fetch_events.py \
  --account {account_name} \
  --days 7
```

### 3. 결과 통합

- 모든 계정의 이벤트를 시간순 정렬
- 동일 시간대 이벤트 = 충돌로 표시
- 계정별 색상/아이콘 구분

## 출력 형식

```
📅 2026-01-06 (월) 일정

[09:00-10:00] 🔵 팀 스탠드업 (work)
[10:00-11:30] 🟢 치과 예약 (personal)
[14:00-15:00] 🔵 고객 미팅 - 삼양 (work)
              ⚠️ 충돌: 개인 일정과 겹침
[14:00-14:30] 🟢 은행 방문 (personal)

📊 오늘 총 4개 일정 (work: 2, personal: 2)
   ⚠️ 1건 충돌
```

## 실행 예시

사용자: "이번 주 일정 알려줘"

```
1. accounts/ 폴더 확인
   └── 등록된 계정: work, personal

2. Subagent 병렬 실행
   ├── Task: work 계정 이벤트 조회
   └── Task: personal 계정 이벤트 조회

3. 결과 수집 (각 subagent 완료 대기)
   ├── work: 8개 이벤트
   └── personal: 3개 이벤트

4. 통합 및 정렬
   └── 11개 이벤트, 2건 충돌 감지

5. 출력
   └── 일별로 그룹화하여 표시
```

## 에러 처리

| 상황 | 처리 |
|------|------|
| accounts/ 폴더 비어있음 | 초기 설정 안내 (setup_auth.py 실행 방법) |
| 특정 계정 토큰 만료 | 해당 계정 재인증 안내, 나머지 계정은 정상 조회 |
| API 할당량 초과 | 잠시 후 재시도 안내 |
| 네트워크 오류 | 연결 확인 요청 |

## Scripts

| 파일 | 용도 |
|------|------|
| `scripts/setup_auth.py` | 계정별 OAuth 인증 및 token 저장 |
| `scripts/fetch_events.py` | 특정 계정의 이벤트 조회 (CLI) |
| `scripts/manage_events.py` | 이벤트 생성/수정/삭제 (CLI) |
| `scripts/calendar_client.py` | Google Calendar API 클라이언트 라이브러리 |

## 일정 관리 (생성/수정/삭제)

### 일정 생성

```bash
uv run python .claude/skills/google-calendar/scripts/manage_events.py create \
    --summary "팀 미팅" \
    --start "2026-01-06T14:00:00" \
    --end "2026-01-06T15:00:00" \
    --account work
```

### 종일 일정 생성

```bash
uv run python .claude/skills/google-calendar/scripts/manage_events.py create \
    --summary "연차" \
    --start "2026-01-10" \
    --end "2026-01-11" \
    --account personal
```

### 일정 수정

```bash
uv run python .claude/skills/google-calendar/scripts/manage_events.py update \
    --event-id "abc123" \
    --summary "팀 미팅 (변경)" \
    --start "2026-01-06T14:21:00" \
    --account work
```

### 일정 삭제

```bash
uv run python .claude/skills/google-calendar/scripts/manage_events.py delete \
    --event-id "abc123" \
    --account work
```

### 옵션

| 옵션 | 설명 |
|------|------|
| `--summary` | 일정 제목 |
| `--start` | 시작 시간 (ISO format: 2026-01-06T14:00:00 또는 2026-01-06) |
| `--end` | 종료 시간 |
| `--description` | 일정 설명 |
| `--location` | 장소 |
| `--attendees` | 참석자 이메일 (쉼표 구분) |
| `--account` | 계정 (work, personal 등) |
| `--adc` | gcloud ADC 사용 |
| `--timezone` | 타임존 (기본값: Asia/Seoul) |
| `--json` | JSON 형식 출력 |

## References

| 문서 | 내용 |
|------|------|
| `references/setup.md` | 초기 설정 상세 가이드 |
| `references/credentials.json` | Google OAuth Client ID (gitignore) |

## 파일 구조

```
.claude/skills/google-calendar/
├── SKILL.md                    # 이 파일
├── scripts/
│   ├── calendar_client.py      # API 클라이언트
│   ├── setup_auth.py           # 인증 설정
│   ├── fetch_events.py         # 이벤트 조회 CLI
│   └── manage_events.py        # 이벤트 생성/수정/삭제 CLI
├── references/
│   ├── setup.md                # 설정 가이드
│   └── credentials.json        # OAuth Client ID (gitignore)
└── accounts/                   # 계정별 토큰 (gitignore)
    ├── work.json
    └── personal.json
```

## 보안 주의사항

- `accounts/*.json`: refresh token 포함, 절대 커밋 금지
- `references/credentials.json`: Client Secret 포함, 커밋 금지
- `.gitignore`에 추가 필수


================================================
FILE: plugins/google-calendar/skills/google-calendar/examples/parallel-fetch.md
================================================
# 병렬 조회 예시

## Subagent 병렬 실행

여러 계정의 캘린더를 동시에 조회하려면 Task 도구를 병렬로 호출:

```
# 단일 메시지에 여러 Task 호출 (병렬 실행)

Task(
    subagent_type="general-purpose",
    prompt="다음 명령을 실행하고 결과를 JSON으로 반환:
    uv run python .claude/skills/google-calendar/scripts/fetch_events.py --account work --days 7 --json",
    model="haiku"
)

Task(
    subagent_type="general-purpose",
    prompt="다음 명령을 실행하고 결과를 JSON으로 반환:
    uv run python .claude/skills/google-calendar/scripts/fetch_events.py --account personal --days 7 --json",
    model="haiku"
)
```

## 결과 통합

각 subagent가 반환한 JSON을 파싱하여 통합:

```python
import json
from datetime import datetime

# subagent 결과들
work_events = json.loads(work_result)
personal_events = json.loads(personal_result)

# 통합 및 시간순 정렬
all_events = work_events + personal_events
all_events.sort(key=lambda x: x["start"])

# 날짜별 그룹화
events_by_date = {}
for event in all_events:
    date = event["start"].split("T")[0]
    events_by_date.setdefault(date, []).append(event)
```

## 충돌 감지

```python
def detect_conflicts(events):
    """동일 시간대 다른 계정 이벤트 = 충돌"""
    conflicts = []
    for i, e1 in enumerate(events):
        for e2 in events[i+1:]:
            if e1["account"] == e2["account"]:
                continue
            # 시간 겹침 확인
            if is_overlapping(e1, e2):
                conflicts.append((e1, e2))
    return conflicts
```

## 출력 예시

```
📅 2026-01-06 (월)

[09:00-10:00] 🔵 팀 스탠드업 (work)
[14:00-15:00] 🔵 고객 미팅 (work)
              ⚠️ 충돌: 개인 일정과 겹침
[14:00-14:30] 🟢 은행 방문 (personal)

📊 총 3개 일정 | 1건 충돌
```


================================================
FILE: plugins/google-calendar/skills/google-calendar/examples/quick-query.md
================================================
# 빠른 조회 예시

## 오늘 일정

```bash
uv run python .claude/skills/google-calendar/scripts/fetch_events.py \
  --all --days 1 --pretty
```

## 이번 주 일정 (JSON)

```bash
uv run python .claude/skills/google-calendar/scripts/fetch_events.py \
  --all --days 7 --json
```

## 특정 계정만 조회

```bash
# 회사 캘린더만
uv run python .claude/skills/google-calendar/scripts/fetch_events.py \
  --account work --days 7 --pretty

# 개인 캘린더만
uv run python .claude/skills/google-calendar/scripts/fetch_events.py \
  --account personal --days 7 --pretty
```

## 캘린더 목록 확인

```bash
uv run python .claude/skills/google-calendar/scripts/fetch_events.py \
  --account work --list-calendars
```

## 프로그래밍 방식 사용

```python
from calendar_client import CalendarClient, fetch_all_events

# 단일 계정
client = CalendarClient("work")
events = client.get_events(days=7)

# 전체 계정 통합
result = fetch_all_events(days=7)
print(f"총 {result['total']}개 이벤트")
print(f"충돌: {len(result['conflicts'])}건")
```


================================================
FILE: plugins/google-calendar/skills/google-calendar/pyproject.toml
================================================
[project]
name = "google-calendar-skill"
version = "0.1.0"
description = "Google Calendar sync skill for Claude Code"
requires-python = ">=3.11"
dependencies = [
    "google-auth>=2.0.0",
    "google-auth-oauthlib>=1.0.0",
    "google-api-python-client>=2.0.0",
    "httplib2>=0.22.0",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["scripts"]


================================================
FILE: plugins/google-calendar/skills/google-calendar/scripts/calendar_client.py
================================================
"""Google Calendar API 클라이언트.

여러 Google 계정의 캘린더를 조회하기 위한 클라이언트.
저장된 refresh token을 사용하여 매번 인증 없이 API 호출.

Environment Variables:
    GOOGLE_CALENDAR_SKILL_PATH: Skill 루트 경로 (기본값: 이 파일의 부모의 부모)
    GOOGLE_CALENDAR_TIMEOUT: API 요청 타임아웃 초 (기본값: 30)
"""

import json
import os
from datetime import datetime, timedelta
from pathlib import Path
from typing import Optional

import google.auth
from google.oauth2.credentials import Credentials
from google.auth.transport.requests import Request
from googleapiclient.discovery import build
import httplib2

# 환경변수에서 설정 로드
DEFAULT_TIMEOUT = int(os.environ.get("GOOGLE_CALENDAR_TIMEOUT", "30"))


class CalendarClient:
    """단일 Google 계정의 캘린더 클라이언트."""

    SCOPES = ["https://www.googleapis.com/auth/calendar"]  # 읽기/쓰기 권한

    def __init__(
        self,
        account_name: str,
        base_path: Optional[Path] = None,
        timeout: int = DEFAULT_TIMEOUT,
    ):
        """
        Args:
            account_name: 계정 식별자 (예: 'work', 'personal')
            base_path: skill 루트 경로 (환경변수 GOOGLE_CALENDAR_SKILL_PATH 또는 기본값)
            timeout: API 요청 타임아웃 (초)
        """
        self.account_name = account_name
        self.timeout = timeout

        # 경로 우선순위: 인자 > 환경변수 > 기본값
        if base_path:
            self.base_path = base_path
        elif os.environ.get("GOOGLE_CALENDAR_SKILL_PATH"):
            self.base_path = Path(os.environ["GOOGLE_CALENDAR_SKILL_PATH"])
        else:
            self.base_path = Path(__file__).parent.parent

        self.creds = self._load_credentials()

    def _load_credentials(self):
        """저장된 refresh token으로 credentials 로드 및 갱신."""
        token_path = self.base_path / f"accounts/{self.account_name}.json"

        if not token_path.exists():
            raise FileNotFoundError(
                f"계정 '{self.account_name}'의 토큰이 없습니다. "
                f"먼저 setup_auth.py --account {self.account_name} 실행 필요"
            )

        with open(token_path) as f:
            token_data = json.load(f)

        # ADC 형식인지 확인 (client_id가 있으면 ADC)
        if "client_id" in token_data and "type" not in token_data:
            # gcloud ADC 형식 - quota project 포함
            creds = Credentials(
                token=token_data.get("token"),
                refresh_token=token_data.get("refresh_token"),
                token_uri="https://oauth2.googleapis.com/token",
                client_id=token_data.get("client_id"),
                client_secret=token_data.get("client_secret"),
                scopes=self.SCOPES,
            )
            # quota project 설정 (있을 때만)
            quota_project = token_data.get("quota_project_id")
            if quota_project:
                creds = creds.with_quota_project(quota_project)
        else:
            # 일반 OAuth 토큰 형식
            creds = Credentials.from_authorized_user_info(token_data, self.SCOPES)

        # 만료 시 자동 갱신
        if creds.expired and creds.refresh_token:
            creds.refresh(Request())
            # 갱신된 토큰 저장
            with open(token_path, "w") as f:
                json.dump(json.loads(creds.to_json()), f, indent=2)

        return creds

    def get_events(
        self,
        days: int = 7,
        calendar_id: str = "primary",
        max_results: int = 100,
    ) -> list[dict]:
        """향후 N일간 이벤트 조회.

        Args:
            days: 조회할 기간 (일)
            calendar_id: 캘린더 ID (기본값: primary)
            max_results: 최대 결과 수

        Returns:
            이벤트 목록 (dict 리스트)
        """
        # credentials로 서비스 빌드
        service = build("calendar", "v3", credentials=self.creds)

        now = datetime.utcnow()
        time_min = now.isoformat() + "Z"
        time_max = (now + timedelta(days=days)).isoformat() + "Z"

        events = []
        page_token = None

        while True:
            result = (
                service.events()
                .list(
                    calendarId=calendar_id,
                    timeMin=time_min,
                    timeMax=time_max,
                    singleEvents=True,
                    orderBy="startTime",
                    maxResults=max_results,
                    pageToken=page_token,
                )
                .execute()
            )

            for event in result.get("items", []):
                start = event["start"].get("dateTime", event["start"].get("date"))
                end = event["end"].get("dateTime", event["end"].get("date"))

                events.append(
                    {
                        "account": self.account_name,
                        "id": event.get("id"),
                        "summary": event.get("summary", "(제목 없음)"),
                        "start": start,
                        "end": end,
                        "all_day": "date" in event["start"],
                        "location": event.get("location"),
                        "description": event.get("description"),
                        "attendees": [
                            a.get("email") for a in event.get("attendees", [])
                        ],
                        "status": event.get("status"),
                        "html_link": event.get("htmlLink"),
                    }
                )

            page_token = result.get("nextPageToken")
            if not page_token:
                break

        return events

    def list_calendars(self) -> list[dict]:
        """사용 가능한 모든 캘린더 목록 조회."""
        service = build("calendar", "v3", credentials=self.creds)

        calendars = []
        page_token = None

        while True:
            result = (
                service.calendarList().list(pageToken=page_token).execute()
            )

            for cal in result.get("items", []):
                calendars.append(
                    {
                        "id": cal.get("id"),
                        "summary": cal.get("summary"),
                        "primary": cal.get("primary", False),
                        "access_role": cal.get("accessRole"),
                    }
                )

            page_token = result.get("nextPageToken")
            if not page_token:
                break

        return calendars

    def create_event(
        self,
        summary: str,
        start: str,
        end: str,
        description: Optional[str] = None,
        location: Optional[str] = None,
        attendees: Optional[list[str]] = None,
        calendar_id: str = "primary",
        timezone: str = "Asia/Seoul",
    ) -> dict:
        """새 이벤트 생성.

        Args:
            summary: 일정 제목
            start: 시작 시간 (ISO format: 2024-01-15T09:00:00 또는 2024-01-15)
            end: 종료 시간 (ISO format)
            description: 일정 설명
            location: 장소
            attendees: 참석자 이메일 목록
            calendar_id: 캘린더 ID (기본값: primary)
            timezone: 타임존 (기본값: Asia/Seoul)

        Returns:
            생성된 이벤트 정보
        """
        service = build("calendar", "v3", credentials=self.creds)

        # 종일 일정인지 확인 (T가 없으면 종일)
        is_all_day = "T" not in start

        event = {
            "summary": summary,
        }

        if is_all_day:
            event["start"] = {"date": start}
            event["end"] = {"date": end}
        else:
            event["start"] = {"dateTime": start, "timeZone": timezone}
            event["end"] = {"dateTime": end, "timeZone": timezone}

        if description:
            event["description"] = description
        if location:
            event["location"] = location
        if attendees:
            event["attendees"] = [{"email": email} for email in attendees]

        result = service.events().insert(calendarId=calendar_id, body=event).execute()

        return {
            "id": result.get("id"),
            "summary": result.get("summary"),
            "start": result["start"].get("dateTime", result["start"].get("date")),
            "end": result["end"].get("dateTime", result["end"].get("date")),
            "html_link": result.get("htmlLink"),
            "status": "created",
        }

    def update_event(
        self,
        event_id: str,
        summary: Optional[str] = None,
        start: Optional[str] = None,
        end: Optional[str] = None,
        description: Optional[str] = None,
        location: Optional[str] = None,
        calendar_id: str = "primary",
        timezone: str = "Asia/Seoul",
    ) -> dict:
        """기존 이벤트 수정.

        Args:
            event_id: 수정할 이벤트 ID
            summary: 새 제목 (None이면 유지)
            start: 새 시작 시간 (None이면 유지)
            end: 새 종료 시간 (None이면 유지)
            description: 새 설명 (None이면 유지)
            location: 새 장소 (None이면 유지)
            calendar_id: 캘린더 ID
            timezone: 타임존

        Returns:
            수정된 이벤트 정보
        """
        service = build("calendar", "v3", credentials=self.creds)

        # 기존 이벤트 조회
        event = service.events().get(calendarId=calendar_id, eventId=event_id).execute()

        # 변경할 필드만 업데이트
        if summary is not None:
            event["summary"] = summary
        if description is not None:
            event["description"] = description
        if location is not None:
            event["location"] = location

        if start is not None:
            is_all_day = "T" not in start
            if is_all_day:
                event["start"] = {"date": start}
            else:
                event["start"] = {"dateTime": start, "timeZone": timezone}

        if end is not None:
            is_all_day = "T" not in end
            if is_all_day:
                event["end"] = {"date": end}
            else:
                event["end"] = {"dateTime": end, "timeZone": timezone}

        result = (
            service.events()
            .update(calendarId=calendar_id, eventId=event_id, body=event)
            .execute()
        )

        return {
            "id": result.get("id"),
            "summary": result.get("summary"),
            "start": result["start"].get("dateTime", result["start"].get("date")),
            "end": result["end"].get("dateTime", result["end"].get("date")),
            "html_link": result.get("htmlLink"),
            "status": "updated",
        }

    def delete_event(
        self,
        event_id: str,
        calendar_id: str = "primary",
    ) -> dict:
        """이벤트 삭제.

        Args:
            event_id: 삭제할 이벤트 ID
            calendar_id: 캘린더 ID

        Returns:
            삭제 결과
        """
        service = build("calendar", "v3", credentials=self.creds)

        service.events().delete(calendarId=calendar_id, eventId=event_id).execute()

        return {
            "id": event_id,
            "status": "deleted",
        }


class ADCCalendarClient:
    """Application Default Credentials를 사용하는 캘린더 클라이언트.

    gcloud auth application-default login으로 인증된 계정 사용.
    별도 토큰 파일 없이 바로 사용 가능.
    """

    SCOPES = ["https://www.googleapis.com/auth/calendar"]  # 읽기/쓰기 권한

    def __init__(self, account_name: str = "default", timeout: int = DEFAULT_TIMEOUT):
        """
        Args:
            account_name: 계정 식별자 (표시용)
            timeout: API 요청 타임아웃 (초)
        """
        self.account_name = account_name
        self.timeout = timeout
        self.creds, self.project = google.auth.default(scopes=self.SCOPES)

    def get_events(
        self,
        days: int = 7,
        calendar_id: str = "primary",
        max_results: int = 100,
    ) -> list[dict]:
        """향후 N일간 이벤트 조회."""
        http = httplib2.Http(timeout=self.timeout)
        http = google.auth.transport.requests.AuthorizedSession(self.creds)
        service = build("calendar", "v3", credentials=self.creds)

        now = datetime.utcnow()
        time_min = now.isoformat() + "Z"
        time_max = (now + timedelta(days=days)).isoformat() + "Z"

        events = []
        page_token = None

        while True:
            result = (
                service.events()
                .list(
                    calendarId=calendar_id,
                    timeMin=time_min,
                    timeMax=time_max,
                    singleEvents=True,
                    orderBy="startTime",
                    maxResults=max_results,
                    pageToken=page_token,
                )
                .execute()
            )

            for event in result.get("items", []):
                start = event["start"].get("dateTime", event["start"].get("date"))
                end = event["end"].get("dateTime", event["end"].get("date"))

                events.append(
                    {
                        "account": self.account_name,
                        "id": event.get("id"),
                        "summary": event.get("summary", "(제목 없음)"),
                        "start": start,
                        "end": end,
                        "all_day": "date" in event["start"],
                        "location": event.get("location"),
                        "description": event.get("description"),
                        "attendees": [
                            a.get("email") for a in event.get("attendees", [])
                        ],
                        "status": event.get("status"),
                        "html_link": event.get("htmlLink"),
                    }
                )

            page_token = result.get("nextPageToken")
            if not page_token:
                break

        return events

    def list_calendars(self) -> list[dict]:
        """사용 가능한 모든 캘린더 목록 조회."""
        service = build("calendar", "v3", credentials=self.creds)

        calendars = []
        page_token = None

        while True:
            result = service.calendarList().list(pageToken=page_token).execute()

            for cal in result.get("items", []):
                calendars.append(
                    {
                        "id": cal.get("id"),
                        "summary": cal.get("summary"),
                        "primary": cal.get("primary", False),
                        "access_role": cal.get("accessRole"),
                    }
                )

            page_token = result.get("nextPageToken")
            if not page_token:
                break

        return calendars

    def create_event(
        self,
        summary: str,
        start: str,
        end: str,
        description: Optional[str] = None,
        location: Optional[str] = None,
        attendees: Optional[list[str]] = None,
        calendar_id: str = "primary",
        timezone: str = "Asia/Seoul",
    ) -> dict:
        """새 이벤트 생성."""
        service = build("calendar", "v3", credentials=self.creds)

        is_all_day = "T" not in start
        event = {"summary": summary}

        if is_all_day:
            event["start"] = {"date": start}
            event["end"] = {"date": end}
        else:
            event["start"] = {"dateTime": start, "timeZone": timezone}
            event["end"] = {"dateTime": end, "timeZone": timezone}

        if description:
            event["description"] = description
        if location:
            event["location"] = location
        if attendees:
            event["attendees"] = [{"email": email} for email in attendees]

        result = service.events().insert(calendarId=calendar_id, body=event).execute()

        return {
            "id": result.get("id"),
            "summary": result.get("summary"),
            "start": result["start"].get("dateTime", result["start"].get("date")),
            "end": result["end"].get("dateTime", result["end"].get("date")),
            "html_link": result.get("htmlLink"),
            "status": "created",
        }

    def update_event(
        self,
        event_id: str,
        summary: Optional[str] = None,
        start: Optional[str] = None,
        end: Optional[str] = None,
        description: Optional[str] = None,
        location: Optional[str] = None,
        calendar_id: str = "primary",
        timezone: str = "Asia/Seoul",
    ) -> dict:
        """기존 이벤트 수정."""
        service = build("calendar", "v3", credentials=self.creds)

        event = service.events().get(calendarId=calendar_id, eventId=event_id).execute()

        if summary is not None:
            event["summary"] = summary
        if description is not None:
            event["description"] = description
        if location is not None:
            event["location"] = location

        if start is not None:
            is_all_day = "T" not in start
            if is_all_day:
                event["start"] = {"date": start}
            else:
                event["start"] = {"dateTime": start, "timeZone": timezone}

        if end is not None:
            is_all_day = "T" not in end
            if is_all_day:
                event["end"] = {"date": end}
            else:
                event["end"] = {"dateTime": end, "timeZone": timezone}

        result = (
            service.events()
            .update(calendarId=calendar_id, eventId=event_id, body=event)
            .execute()
        )

        return {
            "id": result.get("id"),
            "summary": result.get("summary"),
            "start": result["start"].get("dateTime", result["start"].get("date")),
            "end": result["end"].get("dateTime", result["end"].get("date")),
            "html_link": result.get("htmlLink"),
            "status": "updated",
        }

    def delete_event(
        self,
        event_id: str,
        calendar_id: str = "primary",
    ) -> dict:
        """이벤트 삭제."""
        service = build("calendar", "v3", credentials=self.creds)

        service.events().delete(calendarId=calendar_id, eventId=event_id).execute()

        return {
            "id": event_id,
            "status": "deleted",
        }


def get_all_accounts(base_path: Optional[Path] = None) -> list[str]:
    """등록된 모든 계정 이름 반환."""
    base_path = base_path or Path(__file__).parent.parent
    accounts_dir = base_path / "accounts"

    if not accounts_dir.exists():
        return []

    return [
        f.stem
        for f in accounts_dir.glob("*.json")
        if f.stem not in ("credentials",)
    ]


def fetch_all_events(days: int = 7, base_path: Optional[Path] = None) -> dict:
    """모든 계정의 이벤트를 조회하여 통합.

    Args:
        days: 조회할 기간 (일)
        base_path: skill 루트 경로

    Returns:
        {
            "accounts": ["work", "personal"],
            "events": [...],
            "errors": {"account_name": "error message"},
            "total": 10,
            "conflicts": [...]
        }
    """
    accounts = get_all_accounts(base_path)
    all_events = []
    errors = {}

    for account in accounts:
        try:
            client = CalendarClient(account, base_path)
            events = client.get_events(days=days)
            all_events.extend(events)
        except Exception as e:
            errors[account] = str(e)

    # 시간순 정렬
    all_events.sort(key=lambda x: x["start"])

    # 충돌 감지
    conflicts = detect_conflicts(all_events)

    return {
        "accounts": accounts,
        "events": all_events,
        "errors": errors,
        "total": len(all_events),
        "conflicts": conflicts,
    }


def detect_conflicts(events: list[dict]) -> list[dict]:
    """동일 시간대 이벤트 충돌 감지.

    Args:
        events: 시간순 정렬된 이벤트 목록

    Returns:
        충돌 이벤트 쌍 목록
    """
    conflicts = []

    for i, event1 in enumerate(events):
        if event1.get("all_day"):
            continue

        for event2 in events[i + 1 :]:
            if event2.get("all_day"):
                continue

            # 같은 계정이면 충돌 아님
            if event1["account"] == event2["account"]:
                continue

            # 시간 비교
            start1 = datetime.fromisoformat(event1["start"].replace("Z", "+00:00"))
            end1 = datetime.fromisoformat(event1["end"].replace("Z", "+00:00"))
            start2 = datetime.fromisoformat(event2["start"].replace("Z", "+00:00"))
            end2 = datetime.fromisoformat(event2["end"].replace("Z", "+00:00"))

            # event2 시작이 event1 끝 이후면 더 이상 비교 불필요
            if start2 >= end1:
                break

            # 겹침 확인
            if start1 < end2 and start2 < end1:
                conflicts.append(
                    {
                        "event1": {
                            "account": event1["account"],
                            "summary": event1["summary"],
                            "start": event1["start"],
                            "end": event1["end"],
                        },
                        "event2": {
                            "account": event2["account"],
                            "summary": event2["summary"],
                            "start": event2["start"],
                            "end": event2["end"],
                        },
                    }
                )

    return conflicts


================================================
FILE: plugins/google-calendar/skills/google-calendar/scripts/fetch_events.py
================================================
#!/usr/bin/env python3
"""Google Calendar 이벤트 조회 CLI.

Subagent에서 호출하여 특정 계정의 이벤트를 JSON으로 반환.

Usage:
    # ADC(Application Default Credentials) 사용 - 가장 간단
    uv run python fetch_events.py --adc --days 7

    # 특정 계정 조회
    uv run python fetch_events.py --account work --days 7

    # 모든 계정 조회 (통합)
    uv run python fetch_events.py --all --days 7

    # 캘린더 목록 조회
    uv run python fetch_events.py --adc --list-calendars
"""

import argparse
import json
import sys
from datetime import datetime
from pathlib import Path
from zoneinfo import ZoneInfo

from calendar_client import CalendarClient, ADCCalendarClient, fetch_all_events, get_all_accounts


def format_event_for_display(event: dict, tz: ZoneInfo = None) -> str:
    """이벤트를 사람이 읽기 좋은 형식으로 변환."""
    if tz is None:
        tz = ZoneInfo("Asia/Seoul")

    start = event["start"]
    end = event["end"]
    account = event["account"]
    summary = event["summary"]

    # 시간 파싱
    if event.get("all_day"):
        time_str = "종일"
    else:
        start_dt = datetime.fromisoformat(start.replace("Z", "+00:00")).astimezone(tz)
        end_dt = datetime.fromisoformat(end.replace("Z", "+00:00")).astimezone(tz)
        time_str = f"{start_dt.strftime('%H:%M')}-{end_dt.strftime('%H:%M')}"

    # 계정별 아이콘
    icon = "🔵" if account == "work" else "🟢"

    return f"[{time_str}] {icon} {summary} ({account})"


def main():
    parser = argparse.ArgumentParser(
        description="Google Calendar 이벤트 조회"
    )
    parser.add_argument(
        "--account",
        "-a",
        help="계정 식별자 (예: work, personal)",
    )
    parser.add_argument(
        "--all",
        action="store_true",
        help="모든 계정의 이벤트 조회",
    )
    parser.add_argument(
        "--days",
        "-d",
        type=int,
        default=7,
        help="조회할 기간 (일, 기본값: 7)",
    )
    parser.add_argument(
        "--list-calendars",
        action="store_true",
        help="캘린더 목록 조회",
    )
    parser.add_argument(
        "--json",
        "-j",
        action="store_true",
        help="JSON 형식으로 출력",
    )
    parser.add_argument(
        "--pretty",
        "-p",
        action="store_true",
        help="사람이 읽기 좋은 형식으로 출력",
    )
    parser.add_argument(
        "--adc",
        action="store_true",
        help="Application Default Credentials 사용 (gcloud auth application-default login)",
    )

    args = parser.parse_args()
    base_path = Path(__file__).parent.parent

    # ADC 모드
    if args.adc:
        try:
            client = ADCCalendarClient(account_name="gcloud")

            # 캘린더 목록
            if args.list_calendars:
                calendars = client.list_calendars()
                if args.json or not args.pretty:
                    print(json.dumps(calendars, ensure_ascii=False, indent=2))
                else:
                    print("📋 ADC 계정의 캘린더:\n")
                    for cal in calendars:
                        primary = " (기본)" if cal["primary"] else ""
                        print(f"  - {cal['summary']}{primary}")
                        print(f"    ID: {cal['id']}")
                return

            # 이벤트 조회
            events = client.get_events(days=args.days)

            if args.json or not args.pretty:
                print(json.dumps(events, ensure_ascii=False, indent=2))
            else:
                print(f"📅 ADC 계정 - 향후 {args.days}일간 일정\n")

                # 날짜별 그룹화
                events_by_date = {}
                for event in events:
                    start = event["start"]
                    if "T" in start:
                        date = start.split("T")[0]
                    else:
                        date = start
                    events_by_date.setdefault(date, []).append(event)

                for date in sorted(events_by_date.keys()):
                    dt = datetime.fromisoformat(date)
                    print(f"### {dt.strftime('%Y-%m-%d (%a)')}")
                    for event in events_by_date[date]:
                        print(f"  {format_event_for_display(event)}")
                    print()

                print(f"📊 총 {len(events)}개 일정")

        except Exception as e:
            print(f"❌ ADC 오류: {e}", file=sys.stderr)
            print("gcloud auth application-default login 실행 필요", file=sys.stderr)
            sys.exit(1)
        return

    # 계정 목록 확인
    accounts = get_all_accounts(base_path)
    if not accounts:
        print("❌ 등록된 계정이 없습니다.", file=sys.stderr)
        print("먼저 setup_auth.py로 계정을 등록하세요:", file=sys.stderr)
        print("  uv run python setup_auth.py --account work", file=sys.stderr)
        sys.exit(1)

    # 모든 계정 조회
    if args.all:
        result = fetch_all_events(days=args.days, base_path=base_path)

        if args.json or not args.pretty:
            print(json.dumps(result, ensure_ascii=False, indent=2))
        else:
            print(f"📅 향후 {args.days}일간 일정\n")

            # 날짜별 그룹화
            events_by_date = {}
            for event in result["events"]:
                start = event["start"]
                if "T" in start:
                    date = start.split("T")[0]
                else:
                    date = start
                events_by_date.setdefault(date, []).append(event)

            for date in sorted(events_by_date.keys()):
                dt = datetime.fromisoformat(date)
                print(f"### {dt.strftime('%Y-%m-%d (%a)')}")
                for event in events_by_date[date]:
                    print(f"  {format_event_for_display(event)}")
                print()

            # 요약
            print(f"📊 총 {result['total']}개 일정")
            for account in result["accounts"]:
                count = len([e for e in result["events"] if e["account"] == account])
                print(f"   - {account}: {count}개")

            if result["conflicts"]:
                print(f"\n⚠️  {len(result['conflicts'])}건 충돌:")
                for conflict in result["conflicts"]:
                    e1, e2 = conflict["event1"], conflict["event2"]
                    print(f"   - {e1['summary']} ({e1['account']}) ↔ {e2['summary']} ({e2['account']})")

            if result["errors"]:
                print("\n❌ 오류:")
                for account, error in result["errors"].items():
                    print(f"   - {account}: {error}")

        return

    # 특정 계정 조회
    if not args.account:
        parser.print_help()
        print()
        print(f"등록된 계정: {', '.join(accounts)}")
        return

    if args.account not in accounts:
        print(f"❌ 계정 '{args.account}'이 등록되지 않았습니다.", file=sys.stderr)
        print(f"등록된 계정: {', '.join(accounts)}", file=sys.stderr)
        sys.exit(1)

    try:
        client = CalendarClient(args.account, base_path)

        # 캘린더 목록
        if args.list_calendars:
            calendars = client.list_calendars()
            if args.json:
                print(json.dumps(calendars, ensure_ascii=False, indent=2))
            else:
                print(f"📋 '{args.account}' 계정의 캘린더:\n")
                for cal in calendars:
                    primary = " (기본)" if cal["primary"] else ""
                    print(f"  - {cal['summary']}{primary}")
                    print(f"    ID: {cal['id']}")
            return

        # 이벤트 조회
        events = client.get_events(days=args.days)

        if args.json or not args.pretty:
            print(json.dumps(events, ensure_ascii=False, indent=2))
        else:
            print(f"📅 '{args.account}' 계정 - 향후 {args.days}일간 일정\n")
            for event in events:
                print(f"  {format_event_for_display(event)}")
            print(f"\n총 {len(events)}개 일정")

    except FileNotFoundError as e:
        print(f"❌ {e}", file=sys.stderr)
        sys.exit(1)
    except Exception as e:
        print(f"❌ 오류 발생: {e}", file=sys.stderr)
        sys.exit(1)


if __name__ == "__main__":
    main()


================================================
FILE: plugins/google-calendar/skills/google-calendar/scripts/manage_events.py
================================================
#!/usr/bin/env python3
"""Google Calendar 이벤트 관리 CLI.

일정 생성, 수정, 삭제를 위한 CLI 도구.

Usage:
    # 일정 생성 (시간 지정)
    uv run python manage_events.py create \
        --summary "팀 미팅" \
        --start "2026-01-06T14:00:00" \
        --end "2026-01-06T15:00:00" \
        --account work

    # 종일 일정 생성
    uv run python manage_events.py create \
        --summary "연차" \
        --start "2026-01-10" \
        --end "2026-01-11" \
        --account personal

    # 일정 수정
    uv run python manage_events.py update \
        --event-id "abc123" \
        --summary "팀 미팅 (변경)" \
        --account work

    # 일정 삭제
    uv run python manage_events.py delete \
        --event-id "abc123" \
        --account work

    # ADC 사용
    uv run python manage_events.py create \
        --summary "테스트" \
        --start "2026-01-06T10:00:00" \
        --end "2026-01-06T11:00:00" \
        --adc
"""

import argparse
import json
import sys
from pathlib import Path

from calendar_client import CalendarClient, ADCCalendarClient


def cmd_create(args):
    """일정 생성."""
    if args.adc:
        client = ADCCalendarClient()
    else:
        if not args.account:
            print("❌ --account 또는 --adc 필수", file=sys.stderr)
            sys.exit(1)
        base_path = Path(__file__).parent.parent
        client = CalendarClient(args.account, base_path)

    attendees = args.attendees.split(",") if args.attendees else None

    result = client.create_event(
        summary=args.summary,
        start=args.start,
        end=args.end,
        description=args.description,
        location=args.location,
        attendees=attendees,
        timezone=args.timezone,
    )

    if args.json:
        print(json.dumps(result, ensure_ascii=False, indent=2))
    else:
        print(f"✅ 일정 생성 완료")
        print(f"   제목: {result['summary']}")
        print(f"   시간: {result['start']} ~ {result['end']}")
        print(f"   ID: {result['id']}")
        print(f"   링크: {result['html_link']}")


def cmd_update(args):
    """일정 수정."""
    if args.adc:
        client = ADCCalendarClient()
    else:
        if not args.account:
            print("❌ --account 또는 --adc 필수", file=sys.stderr)
            sys.exit(1)
        base_path = Path(__file__).parent.parent
        client = CalendarClient(args.account, base_path)

    result = client.update_event(
        event_id=args.event_id,
        summary=args.summary,
        start=args.start,
        end=args.end,
        description=args.description,
        location=args.location,
        timezone=args.timezone,
    )

    if args.json:
        print(json.dumps(result, ensure_ascii=False, indent=2))
    else:
        print(f"✅ 일정 수정 완료")
        print(f"   제목: {result['summary']}")
        print(f"   시간: {result['start']} ~ {result['end']}")
        print(f"   ID: {result['id']}")
        print(f"   링크: {result['html_link']}")


def cmd_delete(args):
    """일정 삭제."""
    if args.adc:
        client = ADCCalendarClient()
    else:
        if not args.account:
            print("❌ --account 또는 --adc 필수", file=sys.stderr)
            sys.exit(1)
        base_path = Path(__file__).parent.parent
        client = CalendarClient(args.account, base_path)

    result = client.delete_event(event_id=args.event_id)

    if args.json:
        print(json.dumps(result, ensure_ascii=False, indent=2))
    else:
        print(f"✅ 일정 삭제 완료")
        print(f"   ID: {result['id']}")


def main():
    parser = argparse.ArgumentParser(description="Google Calendar 이벤트 관리")
    parser.add_argument("--json", "-j", action="store_true", help="JSON 출력")

    subparsers = parser.add_subparsers(dest="command", help="명령")

    # create 명령
    create_parser = subparsers.add_parser("create", help="일정 생성")
    create_parser.add_argument("--summary", "-s", required=True, help="일정 제목")
    create_parser.add_argument("--start", required=True, help="시작 시간 (ISO format)")
    create_parser.add_argument("--end", required=True, help="종료 시간 (ISO format)")
    create_parser.add_argument("--description", "-d", help="설명")
    create_parser.add_argument("--location", "-l", help="장소")
    create_parser.add_argument("--attendees", help="참석자 (쉼표 구분)")
    create_parser.add_argument("--account", "-a", help="계정")
    create_parser.add_argument("--adc", action="store_true", help="ADC 사용")
    create_parser.add_argument("--timezone", default="Asia/Seoul", help="타임존")
    create_parser.add_argument("--json", "-j", action="store_true", help="JSON 출력")

    # update 명령
    update_parser = subparsers.add_parser("update", help="일정 수정")
    update_parser.add_argument("--event-id", required=True, help="이벤트 ID")
    update_parser.add_argument("--summary", "-s", help="새 제목")
    update_parser.add_argument("--start", help="새 시작 시간")
    update_parser.add_argument("--end", help="새 종료 시간")
    update_parser.add_argument("--description", "-d", help="새 설명")
    update_parser.add_argument("--location", "-l", help="새 장소")
    update_parser.add_argument("--account", "-a", help="계정")
    update_parser.add_argument("--adc", action="store_true", help="ADC 사용")
    update_parser.add_argument("--timezone", default="Asia/Seoul", help="타임존")
    update_parser.add_argument("--json", "-j", action="store_true", help="JSON 출력")

    # delete 명령
    delete_parser = subparsers.add_parser("delete", help="일정 삭제")
    delete_parser.add_argument("--event-id", required=True, help="이벤트 ID")
    delete_parser.add_argument("--account", "-a", help="계정")
    delete_parser.add_argument("--adc", action="store_true", help="ADC 사용")
    delete_parser.add_argument("--json", "-j", action="store_true", help="JSON 출력")

    args = parser.parse_args()

    if not args.command:
        parser.print_help()
        sys.exit(1)

    try:
        if args.command == "create":
            cmd_create(args)
        elif args.command == "update":
            cmd_update(args)
        elif args.command == "delete":
            cmd_delete(args)
    except Exception as e:
        print(f"❌ 오류: {e}", file=sys.stderr)
        sys.exit(1)


if __name__ == "__main__":
    main()


================================================
FILE: plugins/google-calendar/skills/google-calendar/scripts/setup_auth.py
================================================
#!/usr/bin/env python3
"""Google Calendar OAuth 인증 설정.

최초 1회 실행하여 계정별 refresh token을 저장.
이후에는 저장된 token으로 자동 인증됨.

Usage:
    uv run python setup_auth.py --account work
    uv run python setup_auth.py --account personal
"""

import argparse
import json
from pathlib import Path

from google_auth_oauthlib.flow import InstalledAppFlow


SCOPES = ["https://www.googleapis.com/auth/calendar.readonly"]


def setup_auth(account_name: str, base_path: Path) -> None:
    """OAuth 인증 플로우 실행 및 토큰 저장.

    Args:
        account_name: 계정 식별자 (예: 'work', 'personal')
        base_path: skill 루트 경로
    """
    credentials_path = base_path / "references" / "credentials.json"
    token_path = base_path / "accounts" / f"{account_name}.json"

    if not credentials_path.exists():
        print(f"❌ OAuth Client ID 파일이 없습니다: {credentials_path}")
        print()
        print("설정 방법:")
        print("1. https://console.cloud.google.com 접속")
        print("2. 프로젝트 생성 또는 선택")
        print("3. 'API 및 서비스' > '사용자 인증 정보'")
        print("4. 'OAuth 2.0 클라이언트 ID' 생성 (Desktop 유형)")
        print("5. JSON 다운로드 → references/credentials.json 저장")
        return

    # 기존 토큰 확인
    if token_path.exists():
        print(f"⚠️  계정 '{account_name}'의 토큰이 이미 존재합니다.")
        response = input("덮어쓰시겠습니까? [y/N]: ")
        if response.lower() != "y":
            print("취소됨")
            return

    print(f"🔐 '{account_name}' 계정 인증을 시작합니다...")
    print("브라우저가 열리면 Google 계정으로 로그인하세요.")
    print()

    # OAuth 플로우 실행
    flow = InstalledAppFlow.from_client_secrets_file(
        str(credentials_path),
        SCOPES,
    )

    # 로컬 서버로 콜백 받기
    creds = flow.run_local_server(port=0)

    # 토큰 저장
    token_path.parent.mkdir(parents=True, exist_ok=True)
    with open(token_path, "w") as f:
        json.dump(json.loads(creds.to_json()), f, indent=2)

    print()
    print(f"✅ 인증 완료! 토큰 저장됨: {token_path}")
    print(f"   계정: {account_name}")


def list_accounts(base_path: Path) -> None:
    """등록된 계정 목록 출력."""
    accounts_dir = base_path / "accounts"

    if not accounts_dir.exists():
        print("등록된 계정이 없습니다.")
        return

    accounts = [f.stem for f in accounts_dir.glob("*.json")]

    if not accounts:
        print("등록된 계정이 없습니다.")
        return

    print("📋 등록된 계정:")
    for account in accounts:
        print(f"   - {account}")


def main():
    parser = argparse.ArgumentParser(
        description="Google Calendar OAuth 인증 설정"
    )
    parser.add_argument(
        "--account",
        "-a",
        help="계정 식별자 (예: work, personal)",
    )
    parser.add_argument(
        "--list",
        "-l",
        action="store_true",
        help="등록된 계정 목록 출력",
    )

    args = parser.parse_args()
    base_path = Path(__file__).parent.parent

    if args.list:
        list_accounts(base_path)
        return

    if not args.account:
        parser.print_help()
        print()
        print("예시:")
        print("  uv run python setup_auth.py --account work")
        print("  uv run python setup_auth.py --account personal")
        print("  uv run python setup_auth.py --list")
        return

    setup_auth(args.account, base_path)


if __name__ == "__main__":
    main()


================================================
FILE: plugins/interactive-review/.claude-plugin/plugin.json
================================================
{
  "name": "interactive-review",
  "description": "Interactive markdown review with web UI - review plans and documents with checkbox approvals and inline comments",
  "version": "1.0.4",
  "author": {
    "name": "Team Attention"
  },
  "license": "MIT",
  "keywords": ["review", "markdown", "interactive", "web-ui", "feedback"],
  "repository": "https://github.com/team-attention/agents"
}


================================================
FILE: plugins/interactive-review/.mcp.json
================================================
{
  "mcpServers": {
    "interactive_review": {
      "command": "uv",
      "args": ["run", "--directory", "${CLAUDE_PLUGIN_ROOT}/mcp-server", "server.py"]
    }
  }
}


================================================
FILE: plugins/interactive-review/CLAUDE.md
================================================
# Interactive Review Plugin

Claude Code plugin for interactive markdown review with web UI.

## Directory Structure

```
interactive-review/
├── .claude-plugin/
│   └── plugin.json      # Plugin metadata and version
├── mcp-server/
│   ├── server.py        # MCP server (PEP 723 dependencies)
│   └── web_ui.py        # HTML/CSS generation
├── skills/
│   └── review.md        # /review skill definition
└── .mcp.json            # MCP server configuration
```

## Development

### MCP Server

`uv run`을 사용하여 의존성 자동 설치. `server.py` 상단의 PEP 723 metadata 참조:

```python
# /// script
# dependencies = ["mcp>=1.0.0"]
# ///
```

### Testing Locally

```bash
cd mcp-server
uv run python server.py
```

## Versioning

### Before Commit/Push

**반드시 `.claude-plugin/plugin.json`의 버전을 올려야 합니다.**

```json
{
  "version": "1.0.3"  // <- 이 값을 수정
}
```

### Semantic Versioning

- **MAJOR** (1.0.0 → 2.0.0): Breaking changes, API 변경
- **MINOR** (1.0.0 → 1.1.0): 새 기능 추가 (하위 호환)
- **PATCH** (1.0.0 → 1.0.1): 버그 수정, 문서 업데이트

### Checklist

- [ ] 기능 변경 시 버전 올리기
- [ ] `plugin.json` 버전 업데이트
- [ ] 변경 사항 테스트

## Marketplace Publishing

**Marketplace 퍼블리싱은 선택 사항입니다.**

| 상황 | Marketplace 필요? |
|------|------------------|
| 개인용/로컬 테스트 | 불필요 |
| 팀 내부 공유 | 선택적 |
| 커뮤니티 배포 | 권장 |

현재 이 플러그인은 `team-attention/agents` 레포에 포함되어 있어 별도 marketplace 등록 없이 사용 가능합니다.

### 참고 문서

- [Claude Code Plugins](https://www.anthropic.com/news/claude-code-plugins)
- [Plugin Marketplaces Guide](https://code.claude.com/docs/en/plugin-marketplaces)


================================================
FILE: plugins/interactive-review/README.md
================================================
# Interactive Review Plugin

Interactive markdown review with web UI for Claude Code.

## Features

- **Visual Review UI**: Opens a web browser with an interactive review interface
- **Checkbox Approvals**: Approve or reject each section of your plan/document
- **Inline Comments**: Add comments to any item
- **Keyboard Shortcuts**: `Cmd+Enter` to submit, `Esc` to cancel

## Installation

### From Marketplace

```bash
/plugin marketplace add team-attention/agents
/plugin install interactive-review@team-attention-plugins
```

### Local Development

```bash
claude --plugin-dir /path/to/plugins/interactive-review
```

## Requirements

- Python 3.9+
- `mcp` package (`pip install mcp`)

## Usage

After Claude generates a plan or document:

1. Say "review this" or "/review"
2. A browser window opens with the review UI
3. Check/uncheck items to approve or reject
4. Add comments where needed
5. Click "Submit Review" or press `Cmd+Enter`
6. Claude processes your feedback

## Review Result Format

```json
{
  "status": "submitted",
  "items": [
    {"id": "block-0", "text": "Step 1", "checked": true, "comment": "LGTM"},
    {"id": "block-1", "text": "Step 2", "checked": false, "comment": "Use different approach"}
  ],
  "summary": {
    "total": 2,
    "approved": 1,
    "rejected": 1,
    "has_comments": 2
  }
}
```

## How Feedback is Processed

| checked | comment | Meaning |
|---------|---------|---------|
| true | empty | Approved - proceed as planned |
| true | has text | Approved with note |
| false | has text | Rejected - modify per comment |
| false | empty | Rejected - remove or reconsider |


================================================
FILE: plugins/interactive-review/mcp-server/requirements.txt
================================================
mcp>=1.0.0


================================================
FILE: plugins/interactive-review/mcp-server/server.py
================================================
#!/usr/bin/env python3
# /// script
# dependencies = ["mcp>=1.0.0"]
# ///
"""
Interactive Review MCP Server

Provides the start_review tool that:
1. Parses markdown content into reviewable blocks
2. Generates an interactive HTML UI
3. Serves it via a local HTTP server
4. Opens the browser automatically
5. Waits for user feedback
6. Returns structured review results
"""

import asyncio
import json
import os
import signal
import socket
import sys
import tempfile
import threading
import uuid
import webbrowser
from dataclasses import asdict
from http.server import HTTPServer, SimpleHTTPRequestHandler
from pathlib import Path
from typing import Any

from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import Tool, TextContent

from web_ui import parse_markdown, generate_html


# Global state for the HTTP server
_review_result: dict | None = None
_result_event = threading.Event()


def find_free_port() -> int:
    """Find a free port on localhost."""
    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
        s.bind(('', 0))
        s.listen(1)
        return s.getsockname()[1]


class ReviewHTTPHandler(SimpleHTTPRequestHandler):
    """HTTP handler for serving the review UI and receiving results."""

    def __init__(self, *args, review_dir: str, **kwargs):
        self.review_dir = review_dir
        super().__init__(*args, directory=review_dir, **kwargs)

    def do_POST(self):
        """Handle POST request for submitting review results."""
        global _review_result

        if self.path == '/submit':
            content_length = int(self.headers['Content-Length'])
            post_data = self.rfile.read(content_length)

            try:
                _review_result = json.loads(post_data.decode('utf-8'))
                _result_event.set()

                self.send_response(200)
                self.send_header('Content-Type', 'application/json')
                self.send_header('Access-Control-Allow-Origin', '*')
                self.end_headers()
                self.wfile.write(b'{"status": "ok"}')
            except Exception as e:
                self.send_response(500)
                self.send_header('Content-Type', 'application/json')
                self.end_headers()
                self.wfile.write(json.dumps({"error": str(e)}).encode())
        else:
            self.send_response(404)
            self.end_headers()

    def do_OPTIONS(self):
        """Handle CORS preflight requests."""
        self.send_response(200)
        self.send_header('Access-Control-Allow-Origin', '*')
        self.send_header('Access-Control-Allow-Methods', 'POST, OPTIONS')
        self.send_header('Access-Control-Allow-Headers', 'Content-Type')
        self.end_headers()

    def log_message(self, format, *args):
        """Suppress logging to stderr."""
        pass


def make_handler(review_dir: str):
    """Factory to create handler with review_dir bound."""
    def handler(*args, **kwargs):
        return ReviewHTTPHandler(*args, review_dir=review_dir, **kwargs)
    return handler


async def start_review_impl(content: str, title: str = "Review") -> dict[str, Any]:
    """
    Implementation of the start_review tool.

    Args:
        content: Markdown content to review
        title: Title for the review UI

    Returns:
        Review results with status, items, and summary
    """
    global _review_result, _result_event

    # Reset state
    _review_result = None
    _result_event.clear()

    # Create temp directory
    review_id = str(uuid.uuid4())[:8]
    review_dir = Path(tempfile.gettempdir()) / f"claude-review-{review_id}"
    review_dir.mkdir(parents=True, exist_ok=True)

    server = None
    try:
        # Parse markdown
        blocks = parse_markdown(content)

        if not blocks:
            return {
                "status": "error",
                "message": "No reviewable content found in the markdown"
            }

        # Find a free port
        port = find_free_port()

        # Generate HTML
        html_content = generate_html(title, content, blocks, port)
        html_path = review_dir / "index.html"
        html_path.write_text(html_content, encoding='utf-8')

        # Save input for reference
        input_data = {
            "version": "1.0",
            "title": title,
            "content": content,
            "blocks": [asdict(b) for b in blocks]
        }
        (review_dir / "input.json").write_text(
            json.dumps(input_data, indent=2, ensure_ascii=False),
            encoding='utf-8'
        )

        # Start HTTP server in a thread
        server = HTTPServer(('localhost', port), make_handler(str(review_dir)))
        server_thread = threading.Thread(target=server.serve_forever)
        server_thread.daemon = True
        server_thread.start()

        # Open browser
        url = f"http://localhost:{port}/index.html"
        webbrowser.open(url)

        # Wait for result (timeout: 5 minutes)
        timeout = 300
        result_received = await asyncio.get_event_loop().run_in_executor(
            None, lambda: _result_event.wait(timeout)
        )

        if not result_received:
            return {
                "status": "timeout",
                "message": "Review timed out after 5 minutes"
            }

        if _review_result is None:
            return {
                "status": "error",
                "message": "No result received"
            }

        # Enrich result with summary
        items = _review_result.get("items", [])
        approved = sum(1 for item in items if item.get("checked", False))
        rejected = len(items) - approved
        has_comments = sum(1 for item in items if item.get("comment", "").strip())

        return {
            "status": _review_result.get("status", "unknown"),
            "items": items,
            "summary": {
                "total": len(items),
                "approved": approved,
                "rejected": rejected,
                "has_comments": has_comments
            }
        }

    finally:
        # Shutdown server
        if server:
            try:
                server.shutdown()
            except Exception as e:
                print(f"Error shutting down HTTP server: {e}", file=sys.stderr)

        # Cleanup temp directory
        try:
            import shutil
            shutil.rmtree(review_dir, ignore_errors=True)
        except Exception:
            pass


# Create MCP server
app = Server("interactive-review")


@app.list_tools()
async def list_tools() -> list[Tool]:
    """List available tools."""
    return [
        Tool(
            name="start_review",
            description="""Open an interactive web UI to review markdown content.

The user can:
- Check/uncheck items to approve or reject them
- Add comments to any item
- Submit the review when done

Returns structured feedback with approval status and comments for each item.""",
            inputSchema={
                "type": "object",
                "properties": {
                    "content": {
                        "type": "string",
                        "description": "Markdown content to review (plans, documents, etc.)"
                    },
                    "title": {
                        "type": "string",
                        "description": "Title for the review UI",
                        "default": "Review"
                    }
                },
                "required": ["content"]
            }
        )
    ]


@app.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
    """Handle tool calls."""
    if name == "start_review":
        content = arguments.get("content", "")
        title = arguments.get("title", "Review")

        result = await start_review_impl(content, title)

        return [TextContent(
            type="text",
            text=json.dumps(result, indent=2, ensure_ascii=False)
        )]

    return [TextContent(
        type="text",
        text=json.dumps({"error": f"Unknown tool: {name}"})
    )]


def setup_signal_handlers():
    """Set up signal handlers for graceful shutdown."""
    def handle_shutdown(signum, frame):
        sys.exit(0)

    signal.signal(signal.SIGTERM, handle_shutdown)
    signal.signal(signal.SIGHUP, handle_shutdown)
    signal.signal(signal.SIGPIPE, signal.SIG_DFL)


async def main():
    """Main entry point."""
    setup_signal_handlers()

    try:
        async with stdio_server() as (read_stream, write_stream):
            await app.run(
                read_stream,
                write_stream,
                app.create_initialization_options()
            )
    except (BrokenPipeError, ConnectionResetError, EOFError):
        # Parent process closed the pipe - exit gracefully
        pass
    except KeyboardInterrupt:
        pass
    finally:
        sys.exit(0)


if __name__ == "__main__":
    asyncio.run(main())


================================================
FILE: plugins/interactive-review/mcp-server/web_ui.py
================================================
"""
Web UI Generator for Interactive Review

Generates a self-contained HTML file with embedded CSS and JavaScript
for reviewing markdown content with line-level comments (GitHub-style).
Uses marked.js for markdown rendering.
"""

import json
from typing import List, Dict, Any
from dataclasses import dataclass, asdict


@dataclass
class Block:
    """Represents a reviewable block in the markdown content."""
    id: str
    type: str  # heading, list-item, paragraph, code
    text: str
    level: int = 0  # for headings
    raw: str = ""  # original markdown


def parse_markdown(content: str) -> List[Block]:
    """
    Parse markdown content into lines for line-level commenting.
    Returns list of Block objects, one per line.
    """
    blocks = []
    lines = content.split('\n')

    for i, line in enumerate(lines):
        blocks.append(Block(
            id=f"line-{i}",
            type="line",
            text=line,
            level=0,
            raw=line
        ))

    return blocks


def generate_html(title: str, content: str, blocks: List[Block], server_port: int) -> str:
    """Generate the complete HTML for the review UI with marked.js and line comments."""

    # Escape content for JSON embedding
    content_json = json.dumps(content)
    lines_json = json.dumps([{"id": b.id, "text": b.text, "lineNum": i} for i, b in enumerate(blocks)])

    return f'''<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{title} - Interactive Review</title>
    <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/highlight.js@11.9.0/lib/highlight.min.js"></script>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/highlight.js@11.9.0/styles/github-dark.min.css">
    <style>
        :root {{
            --bg-primary: #0d1117;
            --bg-secondary: #161b22;
            --bg-tertiary: #21262d;
            --bg-card: #1c2128;
            --text-primary: #e6edf3;
            --text-secondary: #8b949e;
            --text-muted: #6e7681;
            --accent: #58a6ff;
            --accent-hover: #79b8ff;
            --success: #3fb950;
            --warning: #d29922;
            --danger: #f85149;
            --border: #30363d;
            --border-accent: #388bfd;
            --highlight-bg: rgba(56, 139, 253, 0.15);
            --comment-bg: #2d333b;
            --selection-bg: rgba(56, 139, 253, 0.3);
        }}

        * {{
            box-sizing: border-box;
            margin: 0;
            padding: 0;
        }}

        body {{
            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif;
            background: var(--bg-primary);
            color: var(--text-primary);
            line-height: 1.6;
            min-height: 100vh;
        }}

        .layout {{
            display: flex;
            min-height: 100vh;
        }}

        .main-content {{
            flex: 1;
            max-width: 900px;
            padding: 2rem;
            overflow-y: auto;
        }}

        .comments-sidebar {{
            width: 350px;
            background: var(--bg-secondary);
            border-left: 1px solid var(--border);
            padding: 1rem;
            overflow-y: auto;
            position: sticky;
            top: 0;
            height: 100vh;
        }}

        header {{
            display: flex;
            justify-content: space-between;
            align-items: center;
            margin-bottom: 1.5rem;
            padding-bottom: 1rem;
            border-bottom: 1px solid var(--border);
        }}

        h1 {{
            font-size: 1.5rem;
            font-weight: 600;
        }}

        .summary {{
            font-size: 0.875rem;
            color: var(--text-secondary);
        }}

        .summary .count {{
            background: var(--bg-tertiary);
            padding: 0.25rem 0.5rem;
            border-radius: 12px;
            margin-left: 0.5rem;
        }}

        /* Markdown content area */
        .markdown-container {{
            background: var(--bg-secondary);
            border: 1px solid var(--border);
            border-radius: 8px;
            overflow: hidden;
        }}

        .line-wrapper {{
            display: flex;
            position: relative;
            border-bottom: 1px solid transparent;
        }}

        .line-wrapper:hover {{
            background: var(--bg-tertiary);
        }}

        .line-wrapper.has-comment {{
            background: var(--highlight-bg);
            border-left: 3px solid var(--accent);
        }}

        .line-wrapper.selecting {{
            background: var(--selection-bg);
        }}

        .line-number {{
            flex-shrink: 0;
            width: 50px;
            padding: 0 12px;
            text-align: right;
            color: var(--text-muted);
            font-family: 'SF Mono', Monaco, 'Consolas', monospace;
            font-size: 12px;
            user-select: none;
            cursor: pointer;
            border-right: 1px solid var(--border);
        }}

        .line-number:hover {{
            color: var(--accent);
        }}

        .add-comment-btn {{
            position: absolute;
            left: 4px;
            top: 50%;
            transform: translateY(-50%);
            width: 20px;
            height: 20px;
            background: var(--accent);
            border: none;
            border-radius: 50%;
            color: white;
            font-size: 14px;
            font-weight: bold;
            cursor: pointer;
            opacity: 0;
            transition: opacity 0.2s;
            display: flex;
            align-items: center;
            justify-content: center;
        }}

        .line-wrapper:hover .add-comment-btn {{
            opacity: 1;
        }}

        .line-content {{
            flex: 1;
            padding: 0 16px;
            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif;
            font-size: 14px;
            white-space: pre-wrap;
            word-wrap: break-word;
        }}

        /* Rendered markdown styling */
        .rendered-markdown {{
            padding: 24px;
        }}

        .rendered-markdown h1,
        .rendered-markdown h2,
        .rendered-markdown h3,
        .rendered-markdown h4,
        .rendered-markdown h5,
        .rendered-markdown h6 {{
            margin-top: 24px;
            margin-bottom: 16px;
            font-weight: 600;
            line-height: 1.25;
            border-bottom: 1px solid var(--border);
            padding-bottom: 0.3em;
        }}

        .rendered-markdown h1 {{ font-size: 2em; }}
        .rendered-markdown h2 {{ font-size: 1.5em; }}
        .rendered-markdown h3 {{ font-size: 1.25em; border-bottom: none; }}
        .rendered-markdown h4 {{ font-size: 1em; border-bottom: none; }}

        .rendered-markdown p {{
            margin-bottom: 16px;
        }}

        .rendered-markdown ul,
        .rendered-markdown ol {{
            margin-bottom: 16px;
            padding-left: 2em;
        }}

        .rendered-markdown li {{
            margin-bottom: 4px;
        }}

        .rendered-markdown code {{
            background: var(--bg-tertiary);
            padding: 0.2em 0.4em;
            border-radius: 6px;
            font-family: 'SF Mono', Monaco, 'Consolas', monospace;
            font-size: 85%;
        }}

        .rendered-markdown pre {{
            background: var(--bg-tertiary);
            padding: 16px;
            border-radius: 6px;
            overflow-x: auto;
            margin-bottom: 16px;
        }}

        .rendered-markdown pre code {{
            background: none;
            padding: 0;
            font-size: 14px;
        }}

        .rendered-markdown table {{
            border-collapse: collapse;
            width: 100%;
            margin-bottom: 16px;
        }}

        .rendered-markdown th,
        .rendered-markdown td {{
            border: 1px solid var(--border);
            padding: 6px 13px;
        }}

        .rendered-markdown th {{
            background: var(--bg-tertiary);
            font-weight: 600;
        }}

        .rendered-markdown blockquote {{
            border-left: 4px solid var(--border);
            padding-left: 16px;
            color: var(--text-secondary);
            margin-bottom: 16px;
        }}

        /* Source view with line numbers */
        .source-view {{
            display: none;
        }}

        .source-view.active {{
            display: block;
        }}

        .rendered-view {{
            display: block;
        }}

        .rendered-view.hidden {{
            display: none;
        }}

        /* View toggle */
        .view-toggle {{
            display: flex;
            gap: 0;
            margin-bottom: 1rem;
            border: 1px solid var(--border);
            border-radius: 6px;
            overflow: hidden;
            width: fit-content;
        }}

        .view-toggle button {{
            padding: 0.5rem 1rem;
            background: var(--bg-secondary);
            border: none;
            color: var(--text-secondary);
            cursor: pointer;
            font-size: 0.875rem;
            transition: all 0.2s;
        }}

        .view-toggle button:not(:last-child) {{
            border-right: 1px solid var(--border);
        }}

        .view-toggle button.active {{
            background: var(--accent);
            color: white;
        }}

        .view-toggle button:hover:not(.active) {{
            background: var(--bg-tertiary);
        }}

        /* Comments sidebar */
        .sidebar-header {{
            font-size: 0.875rem;
            font-weight: 600;
            color: var(--text-secondary);
            margin-bottom: 1rem;
            padding-bottom: 0.5rem;
            border-bottom: 1px solid var(--border);
            display: flex;
            justify-content: space-between;
            align-items: center;
        }}

        .comment-card {{
            background: var(--bg-card);
            border: 1px solid var(--border);
            border-radius: 8px;
            margin-bottom: 1rem;
            overflow: hidden;
        }}

        .comment-card.editing {{
            border-color: var(--accent);
        }}

        .comment-header {{
            display: flex;
            justify-content: space-between;
            align-items: center;
            padding: 0.75rem;
            background: var(--bg-tertiary);
            font-size: 0.75rem;
            color: var(--text-secondary);
        }}

        .comment-lines {{
            font-family: 'SF Mono', Monaco, monospace;
            color: var(--accent);
        }}

        .comment-preview {{
            padding: 0.75rem;
            font-size: 0.875rem;
            background: var(--bg-primary);
            border-bottom: 1px solid var(--border);
            color: var(--text-muted);
            font-family: 'SF Mono', Monaco, monospace;
            max-height: 60px;
            overflow: hidden;
            white-space: pre-wrap;
        }}

        .comment-body {{
            padding: 0.75rem;
        }}

        .comment-textarea {{
            width: 100%;
            min-height: 80px;
            padding: 0.75rem;
            background: var(--bg-primary);
            border: 1px solid var(--border);
            border-radius: 6px;
            color: var(--text-primary);
            font-size: 0.875rem;
            resize: vertical;
            font-family: inherit;
        }}

        .comment-textarea:focus {{
            outline: none;
            border-color: var(--accent);
        }}

        .comment-textarea::placeholder {{
            color: var(--text-muted);
        }}

        .comment-textarea.saved {{
            border-color: var(--success);
            transition: border-color 0.3s;
        }}

        .save-indicator {{
            font-size: 0.7rem;
            color: var(--success);
            opacity: 0;
            transition: opacity 0.2s;
            margin-top: 0.25rem;
        }}

        .save-indicator.visible {{
            opacity: 1;
        }}

        .comment-actions {{
            display: flex;
            justify-content: flex-end;
            gap: 0.5rem;
            margin-top: 0.5rem;
        }}

        .comment-text {{
            font-size: 0.875rem;
            line-height: 1.5;
            white-space: pre-wrap;
        }}

        .comment-text.empty {{
            color: var(--text-muted);
            font-style: italic;
        }}

        .no-comments {{
            text-align: center;
            color: var(--text-muted);
            padding: 2rem;
            font-size: 0.875rem;
        }}

        /* Inline comment box (appears when selecting lines) */
        .inline-comment-box {{
            display: none;
            background: var(--bg-card);
            border: 1px solid var(--accent);
            border-radius: 8px;
            margin: 0.5rem 0;
            overflow: hidden;
        }}

        .inline-comment-box.visible {{
            display: block;
        }}

        .inline-comment-header {{
            padding: 0.5rem 0.75rem;
            background: var(--bg-tertiary);
            font-size: 0.75rem;
            color: var(--text-secondary);
            border-bottom: 1px solid var(--border);
        }}

        .inline-comment-body {{
            padding: 0.75rem;
        }}

        /* Actions bar */
        .actions {{
            display: flex;
            gap: 1rem;
            justify-content: space-between;
            align-items: center;
            margin-top: 1.5rem;
            padding-top: 1rem;
            border-top: 1px solid var(--border);
        }}

        .action-group {{
            display: flex;
            gap: 0.5rem;
        }}

        button {{
            padding: 0.5rem 1rem;
            border: none;
            border-radius: 6px;
            font-size: 0.875rem;
            font-weight: 500;
            cursor: pointer;
            transition: all 0.2s;
        }}

        .btn-sm {{
            padding: 0.25rem 0.5rem;
            font-size: 0.75rem;
        }}

        .btn-secondary {{
            background: var(--bg-tertiary);
            color: var(--text-primary);
            border: 1px solid var(--border);
        }}

        .btn-secondary:hover {{
            background: var(--border);
        }}

        .btn-success {{
            background: var(--success);
            color: white;
        }}

        .btn-success:hover {{
            opacity: 0.9;
        }}

        .btn-danger {{
            background: transparent;
            color: var(--danger);
            border: 1px solid var(--danger);
        }}

        .btn-danger:hover {{
            background: var(--danger);
            color: white;
        }}

        .btn-primary {{
            background: var(--accent);
            color: white;
        }}

        .btn-primary:hover {{
            background: var(--accent-hover);
        }}

        .keyboard-hint {{
            font-size: 0.75rem;
            color: var(--text-muted);
        }}

        kbd {{
            background: var(--bg-tertiary);
            padding: 0.2rem 0.4rem;
            border-radius: 4px;
            font-family: inherit;
            border: 1px solid var(--border);
            font-size: 0.7rem;
        }}

        /* Selection highlight */
        .selection-indicator {{
            position: fixed;
            bottom: 20px;
            left: 50%;
            transform: translateX(-50%);
            background: var(--accent);
            color: white;
            padding: 0.75rem 1.5rem;
            border-radius: 8px;
            display: none;
            align-items: center;
            gap: 1rem;
            box-shadow: 0 4px 12px rgba(0, 0, 0, 0.3);
            z-index: 1000;
        }}

        .selection-indicator.visible {{
            display: flex;
        }}

        /* Delete button for comments */
        .delete-comment {{
            background: none;
            border: none;
            color: var(--text-muted);
            cursor: pointer;
            padding: 0.25rem;
            font-size: 1rem;
            line-height: 1;
        }}

        .delete-comment:hover {{
            color: var(--danger);
        }}

        /* Floating comment toolbar for text selection */
        .floating-toolbar {{
            position: fixed;
            background: var(--bg-card);
            border: 1px solid var(--accent);
            border-radius: 8px;
            padding: 0.5rem;
            box-shadow: 0 4px 16px rgba(0, 0, 0, 0.5);
            z-index: 1000;
            display: none;
            align-items: center;
            gap: 0.5rem;
            animation: fadeIn 0.15s ease-out;
        }}

        @keyframes fadeIn {{
            from {{ opacity: 0; transform: translateY(-4px); }}
            to {{ opacity: 1; transform: translateY(0); }}
        }}

        .floating-toolbar.visible {{
            display: flex;
        }}

        .floating-toolbar button {{
            padding: 0.4rem 0.75rem;
            font-size: 0.8rem;
        }}

        /* Inline comment popup */
        .inline-comment-popup {{
            position: fixed;
            background: var(--bg-card);
            border: 1px solid var(--accent);
            border-radius: 8px;
            padding: 0.5rem;
            box-shadow: 0 4px 16px rgba(0, 0, 0, 0.5);
            z-index: 1001;
            display: none;
            min-width: 300px;
        }}

        .inline-comment-popup.visible {{
            display: block;
        }}

        .inline-comment-popup input {{
            width: 100%;
            padding: 0.5rem 0.75rem;
            background: var(--bg-primary);
            border: 1px solid var(--border);
            border-radius: 6px;
            color: var(--text-primary);
            font-size: 0.875rem;
            outline: none;
        }}

        .inline-comment-popup input:focus {{
            border-color: var(--accent);
        }}

        .inline-comment-popup input::placeholder {{
            color: var(--text-muted);
        }}

        /* Highlighted text in preview */
        .commented-text {{
            background: var(--highlight-bg);
            border-bottom: 2px solid var(--accent);
            cursor: pointer;
            padding: 0 2px;
            border-radius: 2px;
        }}

        .commented-text:hover {{
            background: var(--selection-bg);
        }}

        /* Responsive */
        @media (max-width: 1200px) {{
            .comments-sidebar {{
                width: 300px;
            }}
        }}

        @media (max-width: 900px) {{
            .layout {{
                flex-direction: column;
            }}

            .comments-sidebar {{
                width: 100%;
                height: auto;
                position: static;
                border-left: none;
                border-top: 1px solid var(--border);
            }}
        }}
    </style>
</head>
<body>
    <div class="layout">
        <div class="main-content">
            <header>
                <h1>{title}</h1>
                <div class="summary">
                    Comments: <span class="count" id="comment-count">0</span>
                </div>
            </header>

            <div class="view-toggle">
                <button class="active" onclick="switchView('rendered')">Preview</button>
                <button onclick="switchView('source')">Source</button>
            </div>

            <div class="markdown-container">
                <div class="rendered-view" id="rendered-view">
                    <div class="rendered-markdown" id="rendered-content"></div>
                </div>
                <div class="source-view" id="source-view"></div>
            </div>

            <div class="actions">
                <div class="keyboard-hint">
                    <kbd>Cmd</kbd>+<kbd>Enter</kbd> submit | <kbd>Esc</kbd> cancel
                </div>
                <div class="action-group">
                    <button class="btn-secondary" onclick="cancelReview()">Cancel</button>
                    <button class="btn-primary" onclick="submitReview()">Submit Review</button>
                </div>
            </div>
        </div>

        <div class="comments-sidebar">
            <div class="sidebar-header">
                <span>Comments</span>
                <button class="btn-sm btn-secondary" onclick="clearAllComments()">Clear All</button>
            </div>
            <div id="comments-list">
                <div class="no-comments">
                    Click on a line number or select text to add comments
                </div>
            </div>
        </div>
    </div>

    <div class="selection-indicator" id="selection-indicator">
        <span id="selection-text">Lines 1-3 selected</span>
        <button class="btn-sm btn-primary" onclick="addCommentForSelection()">Add Comment</button>
        <button class="btn-sm btn-secondary" onclick="clearSelection()">Cancel</button>
    </div>

    <div class="floating-toolbar" id="floating-toolbar">
        <span style="color: var(--text-secondary); font-size: 0.75rem; margin-right: 0.5rem;">💬</span>
        <button class="btn-sm btn-primary" onclick="showInlineCommentInput()">Comment</button>
    </div>

    <div class="inline-comment-popup" id="inline-comment-popup">
        <input type="text" id="inline-comment-input" placeholder="Add comment... (Enter to save, Esc to cancel)">
    </div>

    <script>
        const rawContent = {content_json};
        const lines = {lines_json};
        const serverPort = {server_port};

        // State
        let comments = []; // {{ id, startLine, endLine, text, linePreview, type }}
        let selectionStart = null;
        let selectionEnd = null;
        let currentView = 'rendered';
        let commentIdCounter = 0;
        let selectedText = '';
        let selectionRange = null;

        // Initialize marked
        marked.setOptions({{
            highlight: function(code, lang) {{
                if (lang && hljs.getLanguage(lang)) {{
                    return hljs.highlight(code, {{ language: lang }}).value;
                }}
                return hljs.highlightAuto(code).value;
            }},
            breaks: false,
            gfm: true
        }});

        function init() {{
            // Render markdown preview
            document.getElementById('rendered-content').innerHTML = marked.parse(rawContent);

            // Render source view with line numbers
            renderSourceView();

            // Apply syntax highlighting to rendered code blocks
            document.querySelectorAll('.rendered-markdown pre code').forEach(block => {{
                hljs.highlightElement(block);
            }});

            // Setup text selection handler for preview
            setupTextSelectionHandler();
        }}

        // Text selection in Preview view
        function setupTextSelectionHandler() {{
            const renderedContent = document.getElementById('rendered-content');
            const floatingToolbar = document.getElementById('floating-toolbar');

            console.log('Setting up text selection handler...', {{ renderedContent: !!renderedContent, floatingToolbar: !!floatingToolbar }});

            renderedContent.addEventListener('mouseup', (e) => {{
                // Delay to let selection finalize
                setTimeout(() => {{
                    const selection = window.getSelection();
                    const text = selection.toString().trim();

                    console.log('Selection detected:', text ? `"${{text.substring(0, 30)}}..."` : '(empty)');

                    if (text && text.length > 0) {{
                        selectedText = text;
                        try {{
                            selectionRange = selection.getRangeAt(0).cloneRange();

                            // Position floating toolbar near selection (fixed positioning)
                            const rect = selection.getRangeAt(0).getBoundingClientRect();
                            const top = rect.bottom + 8;
                            const left = Math.max(10, rect.left + (rect.width / 2) - 50);

                            console.log('Showing toolbar at:', top, left);

                            floatingToolbar.style.top = `${{top}}px`;
                            floatingToolbar.style.left = `${{left}}px`;
                            floatingToolbar.classList.add('visible');
                        }} catch (err) {{
                            console.log('Selection error:', err);
                        }}
                    }} else {{
                        hideFloatingToolbar();
                    }}
                }}, 50);
            }});

            // Hide toolbar when clicking elsewhere
            document.addEventListener('mousedown', (e) => {{
                if (!floatingToolbar.contains(e.target) && !renderedContent.contains(e.target)) {{
                    hideFloatingToolbar();
                }}
            }});
        }}

        function hideFloatingToolbar() {{
            const floatingToolbar = document.getElementById('floating-toolbar');
            floatingToolbar.classList.remove('visible');
        }}

        function hideInlineCommentPopup() {{
            const popup = document.getElementById('inline-comment-popup');
            popup.classList.remove('visible');
            document.getElementById('inline-comment-input').value = '';
        }}

        function showInlineCommentInput() {{
            if (!selectedText) return;

            const floatingToolbar = document.getElementById('floating-toolbar');
            const popup = document.getElementById('inline-comment-popup');
            const input = document.getElementById('inline-comment-input');

            // Position popup below the floating toolbar
            const toolbarRect = floatingToolbar.getBoundingClientRect();
            popup.style.top = `${{toolbarRect.bottom + 8}}px`;
            popup.style.left = `${{Math.max(10, toolbarRect.left)}}px`;

            // Hide toolbar, show popup
            hideFloatingToolbar();
            popup.classList.add('visible');
            input.value = '';
            input.focus();
        }}

        function confirmInlineComment() {{
            const input = document.getElementById('inline-comment-input');
            const commentText = input.value.trim();

            if (!selectedText) {{
                hideInlineCommentPopup();
                return;
            }}

            const preview = selectedText.length > 100 ? selectedText.substring(0, 100) + '...' : selectedText;

            const comment = {{
                id: `comment-${{commentIdCounter++}}`,
                type: 'text',
                startLine: null,
                endLine: null,
                text: commentText,
                linePreview: preview,
                selectedText: selectedText
            }};

            comments.push(comment);

            // Highlight the selected text in the preview
            highlightTextInPreview(selectionRange, comment.id);

            // Clear state
            hideInlineCommentPopup();
            window.getSelection().removeAllRanges();
            selectedText = '';
            selectionRange = null;

            renderComments();

            console.log('Comment added:', comment);
        }}

        // Setup inline comment input handlers
        document.getElementById('inline-comment-input').addEventListener('keydown', (e) => {{
            if (e.key === 'Enter') {{
                e.preventDefault();
                e.stopPropagation();
                confirmInlineComment();
            }} else if (e.key === 'Escape') {{
                e.preventDefault();
                e.stopPropagation();
                hideInlineCommentPopup();
                selectedText = '';
                selectionRange = null;
            }}
        }});

        function addCommentForTextSelection() {{
            // Legacy function - now uses inline input
            showInlineCommentInput();
        }}

        function highlightTextInPreview(range, commentId) {{
            if (!range) return;

            try {{
                const span = document.createElement('span');
                span.className = 'commented-text';
                span.dataset.commentId = commentId;
                span.onclick = () => scrollToComment(commentId);
                range.surroundContents(span);
            }} catch (e) {{
                // If surroundContents fails (crosses element boundaries), skip highlighting
                console.log('Could not highlight selection:', e);
            }}
        }}

        function scrollToComment(commentId) {{
            const commentCard = document.querySelector(`[data-comment-id="${{commentId}}"]`);
            if (commentCard) {{
                commentCard.scrollIntoView({{ behavior: 'smooth', block: 'center' }});
                commentCard.style.borderColor = 'var(--accent)';
                setTimeout(() => commentCard.style.borderColor = '', 1500);
            }}
        }}

        function renderSourceView() {{
            const container = document.getElementById('source-view');
            container.innerHTML = lines.map((line, index) => {{
                const hasComment = comments.some(c => index >= c.startLine && index <= c.endLine);
                const isSelecting = selectionStart !== null &&
                    index >= Math.min(selectionStart, selectionEnd || selectionStart) &&
                    index <= Math.max(selectionStart, selectionEnd || selectionStart);

                return `
                    <div class="line-wrapper ${{hasComment ? 'has-comment' : ''}} ${{isSelecting ? 'selecting' : ''}}"
                         data-line="${{index}}"
                         onmousedown="startLineSelection(${{index}})"
                         onmouseenter="extendLineSelection(${{index}})">
                        <button class="add-comment-btn" onclick="event.stopPropagation(); quickAddComment(${{index}})" title="Add comment">+</button>
                        <div class="line-number" data-line="${{index}}">${{index + 1}}</div>
                        <div class="line-content">${{escapeHtml(line.text) || '&nbsp;'}}</div>
                    </div>
                `;
            }}).join('');
        }}

        function escapeHtml(text) {{
            const div = document.createElement('div');
            div.textContent = text;
            return div.innerHTML;
        }}

        function switchView(view) {{
            currentView = view;
            document.querySelectorAll('.view-toggle button').forEach(btn => btn.classList.remove('active'));
            document.querySelector(`.view-toggle button[onclick="switchView('${{view}}')"]`).classList.add('active');

            if (view === 'rendered') {{
                document.getElementById('rendered-view').classList.remove('hidden');
                document.getElementById('source-view').classList.remove('active');
            }} else {{
                document.getElementById('rendered-view').classList.add('hidden');
                document.getElementById('source-view').classList.add('active');
            }}
        }}

        // Line selection
        let isSelecting = false;

        function startLineSelection(lineNum) {{
            isSelecting = true;
            selectionStart = lineNum;
            selectionEnd = lineNum;
            renderSourceView();
        }}

        function extendLineSelection(lineNum) {{
            if (isSelecting && selectionStart !== null) {{
                selectionEnd = lineNum;
                renderSourceView();
                updateSelectionIndicator();
            }}
        }}

        document.addEventListener('mouseup', () => {{
            if (isSelecting && selectionStart !== null) {{
                isSelecting = false;
                if (selectionEnd === null) selectionEnd = selectionStart;
                updateSelectionIndicator();
            }}
        }});

        function updateSelectionIndicator() {{
            const indicator = document.getElementById('selection-indicator');
            if (selectionStart !== null) {{
                const start = Math.min(selectionStart, selectionEnd || selectionStart);
                const end = Math.max(selectionStart, selectionEnd || selectionStart);
                document.getElementById('selection-text').textContent =
                    start === end ? `Line ${{start + 1}} selected` : `Lines ${{start + 1}}-${{end + 1}} selected`;
                indicator.classList.add('visible');
            }} else {{
                indicator.classList.remove('visible');
            }}
        }}

        function clearSelection() {{
            selectionStart = null;
            selectionEnd = null;
            document.getElementById('selection-indicator').classList.remove('visible');
            renderSourceView();
        }}

        function quickAddComment(lineNum) {{
            selectionStart = lineNum;
            selectionEnd = lineNum;
            addCommentForSelection();
        }}

        function addCommentForSelection() {{
            if (selectionStart === null) return;

            const start = Math.min(selectionStart, selectionEnd || selectionStart);
            const end = Math.max(selectionStart, selectionEnd || selectionStart);

            // Get preview text
            const previewLines = lines.slice(start, end + 1).map(l => l.text);
            const preview = previewLines.join('\\n').substring(0, 100) + (previewLines.join('\\n').length > 100 ? '...' : '');

            const comment = {{
                id: `comment-${{commentIdCounter++}}`,
                type: 'line',
                startLine: start,
                endLine: end,
                text: '',
                linePreview: preview
            }};

            comments.push(comment);
            clearSelection();
            renderComments();
            renderSourceView();

            // Focus the new comment textarea
            setTimeout(() => {{
                const textarea = document.querySelector(`[data-comment-id="${{comment.id}}"] textarea`);
                if (textarea) textarea.focus();
            }}, 50);
        }}

        function renderComments() {{
            const container = document.getElementById('comments-list');

            if (comments.length === 0) {{
                container.innerHTML = '<div class="no-comments">Select text in Preview or click lines in Source to add comments</div>';
            }} else {{
                container.innerHTML = comments.map(comment => {{
                    const headerLabel = comment.type === 'text'
                        ? 'Selected text'
                        : (comment.startLine === comment.endLine
                            ? `Line ${{comment.startLine + 1}}`
                            : `Lines ${{comment.startLine + 1}}-${{comment.endLine + 1}}`);

                    return `
                        <div class="comment-card" data-comment-id="${{comment.id}}">
                            <div class="comment-header">
                                <span class="comment-lines">${{headerLabel}}</span>
                                <button class="delete-comment" onclick="deleteComment('${{comment.id}}')" title="Delete comment">&times;</button>
                            </div>
                            <div class="comment-preview">${{escapeHtml(comment.linePreview)}}</div>
                            <div class="comment-body">
                                ${{comment.text
                                    ? `<div class="comment-text">${{escapeHtml(comment.text)}}</div>`
                                    : `<div class="comment-text empty">(no comment)</div>`
                                }}
                            </div>
                        </div>
                    `;
                }}).join('');
            }}

            updateCommentCount();
        }}

        function updateCommentText(commentId, text) {{
            const comment = comments.find(c => c.id === commentId);
            if (comment) {{
                comment.text = text;
            }}
        }}

        let saveTimeout = null;
        function handleCommentInput(commentId, textarea) {{
            updateCommentText(commentId, textarea.value);

            // Show "Saved" indicator with debounce
            clearTimeout(saveTimeout);
            const indicator = document.getElementById(`save-${{commentId}}`);
            if (indicator && textarea.value.trim()) {{
                saveTimeout = setTimeout(() => {{
                    indicator.classList.add('visible');
                    setTimeout(() => indicator.classList.remove('visible'), 1500);
                }}, 500);
            }}
        }}

        function handleCommentKeydown(e, commentId) {{
            // Cmd/Ctrl + Enter to submit
            if ((e.metaKey || e.ctrlKey) && e.key === 'Enter') {{
                e.preventDefault();
                submitReview();
            }}
        }}

        function deleteComment(commentId) {{
            // Remove highlight from preview if it's a text comment
            const highlightedSpan = document.querySelector(`.commented-text[data-comment-id="${{commentId}}"]`);
            if (highlightedSpan) {{
                const parent = highlightedSpan.parentNode;
                while (highlightedSpan.firstChild) {{
                    parent.insertBefore(highlightedSpan.firstChild, highlightedSpan);
                }}
                parent.removeChild(highlightedSpan);
            }}

            comments = comments.filter(c => c.id !== commentId);
            renderComments();
            renderSourceView();
        }}

        function clearAllComments() {{
            if (comments.length > 0 && confirm('Delete all comments?')) {{
                // Remove all highlights from preview
                document.querySelectorAll('.commented-text').forEach(span => {{
                    const parent = span.parentNode;
                    while (span.firstChild) {{
                        parent.insertBefore(span.firstChild, span);
                    }}
                    parent.removeChild(span);
                }});

                comments = [];
                renderComments();
                renderSourceView();
            }}
        }}

        function updateCommentCount() {{
            document.getElementById('comment-count').textContent = comments.length;
        }}

        function scrollToLine(lineNum) {{
            switchView('source');
            const lineEl = document.querySelector(`[data-line="${{lineNum}}"]`);
            if (lineEl) {{
                lineEl.scrollIntoView({{ behavior: 'smooth', block: 'center' }});
                lineEl.style.background = 'var(--selection-bg)';
                setTimeout(() => lineEl.style.background = '', 1000);
            }}
        }}

        async function submitReview() {{
            const result = {{
                status: 'submitted',
                timestamp: new Date().toISOString(),
                items: comments.map(c => ({{
                    id: c.id,
                    startLine: c.startLine,
                    endLine: c.endLine,
                    text: c.text,
                    linePreview: c.linePreview,
                    checked: true,
                    comment: c.text
                }}))
            }};

            try {{
                await fetch(`http://localhost:${{serverPort}}/submit`, {{
                    method: 'POST',
                    headers: {{ 'Content-Type': 'application/json' }},
                    body: JSON.stringify(result)
                }});
                window.close();
            }} catch (e) {{
                alert('Failed to submit review. Please try again.');
                console.error(e);
            }}
        }}

        async function cancelReview() {{
            try {{
                await fetch(`http://localhost:${{serverPort}}/submit`, {{
                    method: 'POST',
                    headers: {{ 'Content-Type': 'application/json' }},
                    body: JSON.stringify({{ status: 'cancelled', items: [] }})
                }});
                window.close();
            }} catch (e) {{
                window.close();
            }}
        }}

        // Keyboard shortcuts
        document.addEventListener('keydown', (e) => {{
            if ((e.metaKey || e.ctrlKey) && e.key === 'Enter') {{
                e.preventDefault();
                submitReview();
            }}
            if (e.key === 'Escape') {{
                // Don't cancel review if inline comment popup is open
                const inlinePopup = document.getElementById('inline-comment-popup');
                if (inlinePopup && inlinePopup.classList.contains('visible')) {{
                    return; // Let the inline input handler deal with it
                }}

                if (selectionStart !== null) {{
                    clearSelection();
                }} else {{
                    cancelReview();
                }}
            }}
        }});

        // Initialize
        init();
    </script>
</body>
</html>'''


================================================
FILE: plugins/interactive-review/skills/review/SKILL.md
================================================
---
name: review
description: Interactive markdown review with web UI. Use when user says "review this", "check this plan", "피드백", "검토해줘" or specifies a file path to review.
allowed-tools:
  - mcp__interactive_review__start_review
  - Read
---

# Interactive Review Skill

This skill opens an interactive web UI where users can review content with checkboxes and comments.

## How It Works

1. Determine the content source:
   - **If user specifies a file path**: Use the `Read` tool to get the file contents
   - **If user provides content directly**: Use that content as-is
   - **Otherwise**: Collect the most recent relevant content from the conversation
2. Call `mcp__interactive_review__start_review` with the content
3. A browser window opens automatically with the review UI
4. User reviews each item:
   - Check/uncheck to approve/reject
   - Add optional comments
5. User clicks Submit
6. Process the feedback and respond accordingly

## Content Sources (Priority Order)

1. **Explicit file path**: User says "review /path/to/file.md" or "이 파일 리뷰해줘: README.md"
   - Read the file using `Read` tool and use its contents
2. **Direct content**: User provides or references specific content to review
   - Use the provided content directly
3. **Conversation context**: Extract relevant content from recent conversation
   - Plans, documents, code, etc. that were recently discussed

## Usage

When the user wants to review content:

```
# If file path is specified, read it first:
Read({ "file_path": "/path/to/file.md" })

# Then start the review:
mcp__interactive_review__start_review({
  "content": "<content from file or conversation>",
  "title": "<descriptive title>"
})
```

## Processing Results

The tool returns a JSON with review items. Handle each item based on:

| checked | comment | Action |
|---------|---------|--------|
| true | empty | Approved - proceed as planned |
| true | has text | Approved with note - consider the feedback |
| false | has text | Rejected - modify according to comment |
| false | empty | Rejected - remove or reconsider this item |

## Example Flow

User: "Review this implementation plan"

1. Extract the plan content from recent output
2. Call start_review with the content
3. Wait for user feedback (tool blocks until submit)
4. Present summary of feedback
5. Ask if user wants you to proceed with approved items or revise rejected items

## Response Template

After receiving feedback:

```
## Review Summary

**Approved**: X items
**Needs revision**: Y items

### Items requiring changes:
- [Item]: [User's comment]

Would you like me to:
1. Proceed with approved items
2. Revise the rejected items based on feedback
3. Both - revise then proceed
```


================================================
FILE: plugins/kakaotalk/.claude-plugin/plugin.json
================================================
{
  "name": "kakaotalk",
  "version": "1.0.0",
  "description": "Send and read KakaoTalk messages on macOS using Accessibility API",
  "author": {
    "name": "Team Attention",
    "url": "https://github.com/team-attention"
  },
  "repository": "https://github.com/team-attention/plugins-for-claude-natives",
  "license": "MIT",
  "keywords": ["kakaotalk", "messaging", "macos", "accessibility"]
}


================================================
FILE: plugins/kakaotalk/README.md
================================================
# KakaoTalk Plugin for Claude Code

macOS에서 카카오톡 메시지를 발송하고 읽는 Claude Code 플러그인.

## Demo

![KakaoTalk Demo](../../assets/kakaotalk.gif)

## Features

- **메시지 발송**: 자연어로 카카오톡 메시지 전송 (발송 전 확인)
- **메시지 읽기**: 채팅방 대화 내역 조회
- **채팅방 목록**: 현재 채팅방 목록 확인
- **서명 자동 추가**: 기본적으로 "sent with claude code" 서명 포함

## Requirements

- **macOS only** (uses Accessibility API)
- **KakaoTalk for Mac** must be running
- **Accessibility permission**: System Settings > Privacy & Security > Accessibility
- **atomacos**: `uv add atomacos` or `pip install atomacos`

## Usage

### Send Message

Claude가 메시지를 보내기 전에 항상 확인을 요청합니다.

```bash
# 기본 (서명 포함)
uv run python ${CLAUDE_PLUGIN_ROOT}/scripts/kakao_send.py "구봉" "밥 먹었어?"
# → "밥 먹었어?\n\nsent with claude code" 전송

# 서명 없이
uv run python ${CLAUDE_PLUGIN_ROOT}/scripts/kakao_send.py "구봉" "밥 먹었어?" --no-signature

# 보내고 창 닫기
uv run python ${CLAUDE_PLUGIN_ROOT}/scripts/kakao_send.py "구봉" "밥 먹었어?" --close
```

### Read Messages

```bash
# 메시지 읽기
uv run python ${CLAUDE_PLUGIN_ROOT}/scripts/kakao_read.py "구봉" --json

# 채팅방 목록
uv run python ${CLAUDE_PLUGIN_ROOT}/scripts/kakao_read.py --list

# 채팅방 검색
uv run python ${CLAUDE_PLUGIN_ROOT}/scripts/kakao_read.py --search "검색어"
```

## Options

### kakao_send.py

| Option | Description |
|--------|-------------|
| `--close`, `-c` | 발송 후 채팅창 닫기 |
| `--no-signature` | "sent with claude code" 서명 없이 보내기 |
| `--json`, `-j` | JSON 형식 출력 |

### kakao_read.py

| Option | Description |
|--------|-------------|
| `--limit N`, `-l N` | 최대 N개 메시지 읽기 (기본: 100) |
| `--close`, `-c` | 읽고 나서 채팅창 닫기 |
| `--json`, `-j` | JSON 형식 출력 |
| `--list` | 채팅방 목록 보기 |
| `--search "검색어"`, `-s` | 채팅방 검색 |

## How It Works

This plugin uses macOS Accessibility API (via atomacos) to:
1. Find and activate KakaoTalk windows
2. Search for chat rooms using Cmd+F
3. Read message content from UI elements
4. Send messages via clipboard paste + Enter

## Limitations

- **macOS only**: Uses platform-specific APIs
- **Visible messages only**: Can only read messages currently visible in the chat window
- **UI dependent**: May break if KakaoTalk updates its UI structure
- **KakaoTalk must be running**: Cannot start the app automatically

## License

MIT


================================================
FILE: plugins/kakaotalk/scripts/kakao_read.py
================================================
#!/usr/bin/env python3
"""
KakaoTalk 채팅방 읽기 CLI

Usage:
    # 기본: 채팅방 열고 메시지 읽기
    python kakao_read.py "채팅방이름"
    python kakao_read.py "채팅방이름" --limit 50
    python kakao_read.py "채팅방이름" --close

    # 채팅 목록
    python kakao_read.py --list

    # 검색어로 채팅방 검색
    python kakao_read.py --search "검색어"
"""

import argparse
import json
import re
import subprocess
import sys
import time

try:
    import atomacos
except ImportError:
    print("Error: atomacos not installed. Run: uv add atomacos")
    sys.exit(1)

# Constants
KAKAO_BUNDLE_ID = "com.kakao.KakaoTalkMac"
CLAUDE_SIGNATURE = "sent with claude code"
FILE_EXTENSIONS = ['.heic', '.jpg', '.jpeg', '.png', '.gif', '.mp4', '.mov', '.pdf', '.zip']
IGNORED_KEYWORDS = ['유효기간', '용량', 'KB', 'MB']
TIME_PATTERNS = ['오전', '오후', '어제', '그제', '월', '일',
                 'AM', 'PM', 'Yesterday', 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
                 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec', ':']
MAIN_WINDOW_TITLES = ('카카오톡', 'KakaoTalk')


# ============================================================================
# AppleScript & Keyboard Helpers
# ============================================================================

def run_applescript(script: str) -> str:
    result = subprocess.run(["osascript", "-e", script], capture_output=True, text=True)
    return result.stdout.strip()


def key_code(code: int, modifiers: str = ""):
    modifier_clause = f"using {{{modifiers}}}" if modifiers else ""
    run_applescript(f'''
        tell application "System Events"
            key code {code} {modifier_clause}
        end tell
    ''')


# ============================================================================
# KakaoTalk App & Window Management
# ============================================================================

def get_kakao_app():
    try:
        return atomacos.getAppRefByBundleId(KAKAO_BUNDLE_ID)
    except ValueError:
        print("Error: KakaoTalk is not running.")
        sys.exit(1)
    except atomacos.ErrorAPIDisabled:
        print("Error: Accessibility API disabled.")
        sys.exit(1)


def find_main_window(kakao_app):
    """메인 창(카카오톡 채팅 목록 창) 찾기."""
    for win in kakao_app.windows():
        if win.AXTitle in MAIN_WINDOW_TITLES:
            return win
    return None


def find_open_chat(kakao_app, chat_name: str):
    """이미 열린 채팅방 창에서 이름이 일치하는 것 찾기."""
    for win in kakao_app.windows():
        title = win.AXTitle
        if title != "카카오톡" and chat_name.lower() in title.lower():
            return win
    return None


def get_all_chat_windows(kakao_app) -> list:
    return [win for win in kakao_app.windows() if win.AXTitle not in MAIN_WINDOW_TITLES]


def ensure_main_window_focused():
    """메인 창(채팅 목록)이 확실히 포커스되도록 함."""
    run_applescript('tell application "KakaoTalk" to activate')
    time.sleep(0.3)

    kakao = get_kakao_app()
    main_win = find_main_window(kakao)
    if not main_win:
        return False

    try:
        main_win.Raise()
        time.sleep(0.3)
    except Exception:
        pass

    return True


def clear_search_and_go_main():
    """메인 창으로 돌아가고 검색 기록 초기화."""
    run_applescript('tell application "KakaoTalk" to activate')
    time.sleep(0.3)

    kakao = get_kakao_app()
    chat_windows = [w for w in kakao.windows() if w.AXTitle != "카카오톡"]
    if chat_windows:
        key_code(53)  # ESC
        time.sleep(0.3)

    ensure_main_window_focused()


def search_and_open_chat(chat_name: str):
    """검색으로 채팅방 열기."""
    clear_search_and_go_main()

    key_code(3, "command down")  # Cmd+F
    time.sleep(0.5)
    key_code(0, "command down")  # Cmd+A
    time.sleep(0.1)

    subprocess.run(["pbcopy"], input=chat_name.encode(), check=True)
    key_code(9, "command down")  # Cmd+V
    time.sleep(0.8)

    key_code(125)  # Down arrow
    time.sleep(0.2)
    key_code(36)  # Enter
    time.sleep(0.8)


def close_chat():
    """현재 채팅창 닫기."""
    key_code(53)  # Escape
    time.sleep(0.2)


# ============================================================================
# Pattern Matching Helpers
# ============================================================================

def is_date_pattern(val: str) -> bool:
    """날짜 구분선 패턴인지 확인 (예: '1월 17일', '2025. 1. 17.', '어제', '그제')"""
    if not val:
        return False
    if re.match(r'^\d{1,2}월\s*\d{1,2}일', val):
        return True
    if re.match(r'^\d{4}\.\s*\d{1,2}\.\s*\d{1,2}', val):
        return True
    if val in ['어제', '그제']:
        return True
    return False


def is_time_pattern(val: str) -> bool:
    """시간 패턴인지 확인 (예: '오전 10:30', '오후 7:41')"""
    if not val:
        return False
    return bool(re.match(r'^(오전|오후)\s*\d{1,2}:\d{2}$', val))


def is_valid_sender_name(val: str) -> bool:
    """유효한 발신자 이름인지 확인."""
    if not val or len(val) >= 20:
        return False
    if val.startswith('[') or val.isdigit():
        return False

    # 특수문자/공백만 있는 경우 무시
    cleaned = val.strip().replace('·', '').replace('•', '').replace(' ', '')
    if not cleaned:
        return False

    # 파일명 패턴 무시
    if any(val.lower().endswith(ext) for ext in FILE_EXTENSIONS):
        return False

    # 무시할 키워드 포함 시 무시
    if any(kw in val for kw in IGNORED_KEYWORDS):
        return False

    return True


# ============================================================================
# Accessibility Helpers
# ============================================================================

def safe_get_attr(elem, attr_name, default=None):
    """안전하게 AX 속성 가져오기."""
    try:
        return getattr(elem, attr_name, default)
    except AttributeError:
        return default


def get_window_width(chat_window) -> int:
    """창 너비 가져오기."""
    try:
        win_size = chat_window.AXSize
        return win_size.width if win_size else 400
    except Exception:
        return 400


# ============================================================================
# Message Extraction
# ============================================================================

def extract_messages(chat_window, limit: int = 100) -> list[dict]:
    """채팅 창에서 메시지 추출."""
    messages = []
    chat_name = safe_get_attr(chat_window, 'AXTitle', '')
    partner_name = None
    current_date = None
    current_time = None

    children = safe_get_attr(chat_window, 'AXChildren', [])
    for child in children:
        if safe_get_attr(child, 'AXRole') != 'AXScrollArea':
            continue

        for table_child in safe_get_attr(child, 'AXChildren', []):
            if safe_get_attr(table_child, 'AXRole') != 'AXTable':
                continue

            win_width = get_window_width(chat_window)
            rows = safe_get_attr(table_child, 'AXChildren', [])

            for row in rows[:limit]:
                if safe_get_attr(row, 'AXRole') != 'AXRow':
                    continue

                row_sender = None
                row_time = None

                for cell in safe_get_attr(row, 'AXChildren', []):
                    if safe_get_attr(cell, 'AXRole') != 'AXCell':
                        continue

                    cell_pos = None
                    try:
                        cell_pos = cell.AXPosition
                    except Exception:
                        pass

                    for elem in safe_get_attr(cell, 'AXChildren', []):
                        role = safe_get_attr(elem, 'AXRole')

                        if role == 'AXStaticText':
                            row_sender, row_time, current_date, partner_name = _parse_static_text(
                                elem, row_sender, row_time, current_date, partner_name
                            )

                        elif role == 'AXTextArea':
                            msg_data = _parse_message(
                                elem, cell_pos, win_width, row_sender, row_time,
                                current_date, current_time, partner_name, chat_name
                            )
                            if msg_data:
                                messages.append(msg_data)
                                if row_time:
                                    current_time = row_time
            break
        break

    return messages


def _parse_static_text(elem, row_sender, row_time, current_date, partner_name):
    """StaticText 요소 파싱."""
    try:
        val = elem.AXValue
        if not val:
            return row_sender, row_time, current_date, partner_name

        # 줄바꿈으로 값이 합쳐진 경우
        if '\n' in val:
            for part in val.split('\n'):
                part = part.strip()
                if part.isdigit():
                    continue
                if is_date_pattern(part):
                    current_date = part.split()[0] if '요일' in part else part
                elif is_time_pattern(part):
                    row_time = part
        elif is_date_pattern(val):
            current_date = val.split()[0] if '요일' in val else val
        elif is_time_pattern(val):
            row_time = val
        elif is_valid_sender_name(val):
            row_sender = val
            partner_name = val
    except Exception:
        pass

    return row_sender, row_time, current_date, partner_name


def _parse_message(elem, cell_pos, win_width, row_sender, row_time,
                   current_date, current_time, partner_name, chat_name) -> dict | None:
    """TextArea 요소에서 메시지 파싱."""
    try:
        msg = elem.AXValue
        if not msg or not msg.strip():
            return None

        # is_me 판단 1: Claude Code 시그니처
        is_me = CLAUDE_SIGNATURE in msg

        # is_me 판단 2: 좌표 기반
        if not is_me and cell_pos:
            try:
                elem_pos = elem.AXPosition
                center_threshold = cell_pos.x + (win_width * 0.4)
                is_me = elem_pos.x > center_threshold
            except Exception:
                pass

        # 발신자 결정
        if is_me:
            sender = "나"
        elif row_sender:
            sender = row_sender
        else:
            sender = partner_name or chat_name or "상대방"

        # 시간 문자열 생성
        time_val = row_time or current_time
        if current_date and time_val:
            time_str = f"{current_date} {time_val}"
        else:
            time_str = time_val or current_date

        return {
            'sender': sender,
            'time': time_str,
            'message': msg,
            'is_me': is_me
        }
    except Exception:
        return None


# ============================================================================
# Chat List Operations
# ============================================================================

def list_chats(kakao_app, limit: int = 30) -> list[str]:
    """메인 창에서 채팅방 목록 추출."""
    chats = []

    for win in kakao_app.windows():
        if safe_get_attr(win, 'AXTitle') not in MAIN_WINDOW_TITLES:
            continue

        for child in safe_get_attr(win, 'AXChildren', []):
            if safe_get_attr(child, 'AXRole') != 'AXScrollArea':
                continue

            for table_child in safe_get_attr(child, 'AXChildren', []):
                if safe_get_attr(table_child, 'AXRole') != 'AXTable':
                    continue

                rows = safe_get_attr(table_child, 'AXChildren', [])
                for row in rows[:limit]:
                    if safe_get_attr(row, 'AXRole') != 'AXRow':
                        continue

                    texts = _extract_row_texts(row)
                    if len(texts) >= 2 and any(t in texts[1] for t in TIME_PATTERNS):
                        chats.append(texts[0])
                break
            break

    return chats


def search_chats(query: str, limit: int = 20) -> list[str]:
    """카카오톡 검색창에서 검색 후 결과 목록 반환."""
    clear_search_and_go_main()

    key_code(3, "command down")  # Cmd+F
    time.sleep(0.5)
    key_code(0, "command down")  # Cmd+A
    time.sleep(0.1)
    subprocess.run(["pbcopy"], input=query.encode(), check=True)
    key_code(9, "command down")  # Cmd+V
    time.sleep(1.0)

    kakao = get_kakao_app()
    chats = []

    for win in kakao.windows():
        if safe_get_attr(win, 'AXTitle') not in MAIN_WINDOW_TITLES:
            continue

        for child in safe_get_attr(win, 'AXChildren', []):
            if safe_get_attr(child, 'AXRole') != 'AXScrollArea':
                continue

            for table_child in safe_get_attr(child, 'AXChildren', []):
                if safe_get_attr(table_child, 'AXRole') != 'AXTable':
                    continue

                rows = safe_get_attr(table_child, 'AXChildren', [])
                for row in rows[:limit]:
                    if safe_get_attr(row, 'AXRole') != 'AXRow':
                        continue

                    texts = _extract_row_texts(row)
                    if len(texts) >= 2 and any(t in texts[1] for t in TIME_PATTERNS):
                        chats.append(texts[0])
                break
            break

    return chats


def _extract_row_texts(row) -> list[str]:
    """Row에서 모든 StaticText 값 추출."""
    texts = []
    for cell in safe_get_attr(row, 'AXChildren', []):
        if safe_get_attr(cell, 'AXRole') != 'AXCell':
            continue
        for elem in safe_get_attr(cell, 'AXChildren', []):
            if safe_get_attr(elem, 'AXRole') == 'AXStaticText':
                try:
                    val = elem.AXValue
                    if val:
                        texts.append(val)
                except Exception:
                    pass
    return texts


# ============================================================================
# Main API
# ============================================================================

def read_chat(chat_name: str, limit: int = 100) -> tuple[str | None, list[dict]]:
    """채팅방 열고 메시지 읽기."""
    kakao = get_kakao_app()

    chat_win = find_open_chat(kakao, chat_name)
    if chat_win:
        return chat_win.AXTitle, extract_messages(chat_win, limit)

    before_titles = set(win.AXTitle for win in get_all_chat_windows(kakao))
    search_and_open_chat(chat_name)
    kakao = get_kakao_app()

    after_windows = get_all_chat_windows(kakao)
    new_windows = [win for win in after_windows if win.AXTitle not in before_titles]

    if new_windows:
        chat_win = new_windows[0]
    elif (chat_win := find_open_chat(kakao, chat_name)):
        pass
    elif after_windows:
        chat_win = after_windows[0]
    else:
        return None, []

    return chat_win.AXTitle, extract_messages(chat_win, limit)


# ============================================================================
# CLI
# ============================================================================

def main():
    parser = argparse.ArgumentParser(description='KakaoTalk 채팅방 읽기 CLI')
    parser.add_argument('chat_name', nargs='?', help='채팅방 이름 (부분 일치)')
    parser.add_argument('--limit', '-l', type=int, default=100, help='최대 메시지 수 (기본: 100)')
    parser.add_argument('--list', action='store_true', help='채팅방 목록 보기')
    parser.add_argument('--search', '-s', type=str, help='카카오톡 검색창에서 검색 후 결과 목록')
    parser.add_argument('--close', '-c', action='store_true', help='읽고 나서 창 닫기')
    parser.add_argument('--json', '-j', action='store_true', help='JSON 출력')

    args = parser.parse_args()

    # 모드 1: 카카오톡 검색창에서 검색
    if args.search:
        chats = search_chats(args.search)
        if args.json:
            print(json.dumps({'search': args.search, 'chats': chats}, ensure_ascii=False, indent=2))
        else:
            print(f"=== '{args.search}' 검색 결과 ===\n")
            for c in chats:
                print(f"  • {c}")
            print(f"\n총 {len(chats)}개")
        return

    # 모드 2: 전체 채팅방 목록
    if args.list:
        kakao = get_kakao_app()
        chats = list_chats(kakao)
        if args.json:
            print(json.dumps({'chats': chats}, ensure_ascii=False, indent=2))
        else:
            print("=== 채팅방 목록 ===\n")
            for c in chats:
                print(f"  • {c}")
            print(f"\n총 {len(chats)}개")
        return

    # 모드 3: 기본 - 채팅방 열고 메시지 읽기
    if not args.chat_name:
        parser.print_help()
        return

    chat_name, messages = read_chat(args.chat_name, args.limit)

    if not messages:
        if args.json:
            print(json.dumps({
                'error': f"'{args.chat_name}' 채팅방을 찾을 수 없습니다.",
                'chat': None,
                'messages': []
            }, ensure_ascii=False, indent=2))
        else:
            print(f"'{args.chat_name}' 채팅방을 찾을 수 없거나 메시지가 없습니다.")
        return

    if args.json:
        print(json.dumps({'chat': chat_name, 'messages': messages}, ensure_ascii=False, indent=2))
    else:
        print(f"\n=== {chat_name} ({len(messages)}개) ===\n")
        for m in messages:
            sender = m['sender']
            time_str = m['time'] or ''
            msg = m['message'].replace('\n', ' ')
            if len(msg) > 80:
                msg = msg[:80] + '...'
            print(f"[{time_str}] {sender}: {msg}")

    if args.close:
        close_chat()
        if not args.json:
            print("\n[창 닫힘]")


if __name__ == '__main__':
    main()


================================================
FILE: plugins/kakaotalk/scripts/kakao_send.py
================================================
#!/usr/bin/env python3
"""
KakaoTalk 메시지 발송

Usage:
    python kakao_send.py "채팅방이름" "메시지"
    python kakao_send.py "구봉" "안녕하세요!"
    python kakao_send.py "구봉" "밥 먹었어?" --close        # 보내고 창 닫기
    python kakao_send.py "구봉" "밥 먹었어?" --no-signature  # 서명 없이 보내기
"""

SIGNATURE = "\n\nsent with claude code"

import argparse
import subprocess
import sys
import time

try:
    import atomacos
except ImportError:
    print("Error: atomacos not installed. Run: uv add atomacos")
    sys.exit(1)

KAKAO_BUNDLE_ID = "com.kakao.KakaoTalkMac"
MAIN_WINDOW_TITLES = ("카카오톡", "KakaoTalk")


def run_applescript(script: str) -> str:
    result = subprocess.run(["osascript", "-e", script], capture_output=True, text=True)
    return result.stdout.strip()


def key_code(code: int, modifiers: str = ""):
    modifier_clause = f"using {{{modifiers}}}" if modifiers else ""
    run_applescript(f'''
        tell application "System Events"
            key code {code} {modifier_clause}
        end tell
    ''')


def type_text(text: str):
    """클립보드를 통해 텍스트 입력 (한글 지원)."""
    subprocess.run(["pbcopy"], input=text.encode("utf-8"), check=True)
    key_code(9, "command down")  # Cmd+V


def get_kakao_app():
    try:
        return atomacos.getAppRefByBundleId(KAKAO_BUNDLE_ID)
    except ValueError:
        print("Error: KakaoTalk is not running.")
        sys.exit(1)
    except atomacos.ErrorAPIDisabled:
        print("Error: Accessibility API disabled.")
        sys.exit(1)


def find_main_window(kakao_app):
    """메인 창(카카오톡 채팅 목록 창) 찾기."""
    for win in kakao_app.windows():
        if win.AXTitle in MAIN_WINDOW_TITLES:
            return win
    return None


def raise_main_window(kakao_app):
    """메인 창을 앞으로 가져오기."""
    main_win = find_main_window(kakao_app)
    if main_win:
        try:
            main_win.Raise()
            return True
        except Exception:
            pass
    return False


def find_open_chat(kakao_app, chat_name: str):
    """이미 열린 채팅방 창에서 이름이 일치하는 것 찾기."""
    for win in kakao_app.windows():
        title = win.AXTitle
        if title in MAIN_WINDOW_TITLES:
            continue
        if chat_name.lower() in title.lower():
            return win
    return None


def get_all_chat_windows(kakao_app) -> list:
    return [win for win in kakao_app.windows() if win.AXTitle not in MAIN_WINDOW_TITLES]


def search_and_open_chat(chat_name: str):
    """검색으로 채팅방 열기."""
    run_applescript('tell application "KakaoTalk" to activate')
    time.sleep(0.3)

    kakao = get_kakao_app()
    raise_main_window(kakao)
    time.sleep(0.3)

    key_code(3, "command down")  # Cmd+F (검색)
    time.sleep(0.5)

    subprocess.run(["pbcopy"], input=chat_name.encode(), check=True)
    key_code(9, "command down")  # Cmd+V
    time.sleep(0.8)

    key_code(125)  # Down arrow
    time.sleep(0.2)
    key_code(36)  # Enter
    time.sleep(0.8)


def open_chat(chat_name: str):
    """채팅방 열기 (이미 열려있으면 그대로, 아니면 검색해서 열기)."""
    kakao = get_kakao_app()

    # 이미 열린 채팅방 확인
    chat_win = find_open_chat(kakao, chat_name)
    if chat_win:
        # 해당 창을 앞으로
        run_applescript('tell application "KakaoTalk" to activate')
        time.sleep(0.2)
        try:
            chat_win.Raise()
        except:
            pass
        return chat_win.AXTitle

    # 검색해서 열기
    before_titles = set(win.AXTitle for win in get_all_chat_windows(kakao))
    search_and_open_chat(chat_name)

    kakao = get_kakao_app()
    after_windows = get_all_chat_windows(kakao)
    new_windows = [win for win in after_windows if win.AXTitle not in before_titles]

    if new_windows:
        return new_windows[0].AXTitle

    chat_win = find_open_chat(kakao, chat_name)
    if chat_win:
        return chat_win.AXTitle

    if after_windows:
        return after_windows[0].AXTitle

    return None


def send_message_via_keyboard(message: str):
    """키보드 입력으로 메시지 전송."""
    # 텍스트 입력 (클립보드 사용)
    type_text(message)
    time.sleep(0.3)

    # Enter로 전송
    key_code(36)  # Enter
    time.sleep(0.3)


def close_chat():
    """현재 채팅창 닫기."""
    key_code(53)  # Escape
    time.sleep(0.2)


def send_message(chat_name: str, message: str, close_after: bool = False) -> dict:
    """채팅방에 메시지 발송."""
    result = {
        'success': False,
        'chat': None,
        'message': message,
        'error': None
    }

    # 1. 채팅방 열기
    chat_title = open_chat(chat_name)
    if not chat_title:
        result['error'] = f"'{chat_name}' 채팅방을 찾을 수 없습니다."
        return result

    result['chat'] = chat_title
    time.sleep(0.3)

    # 2. 메시지 전송 (키보드 입력 방식)
    # 채팅창이 활성화된 상태에서 바로 입력
    send_message_via_keyboard(message)

    result['success'] = True

    # 3. 필요시 창 닫기
    if close_after:
        close_chat()

    return result


def main():
    parser = argparse.ArgumentParser(description='KakaoTalk 메시지 발송')
    parser.add_argument('chat_name', help='채팅방 이름 (부분 일치)')
    parser.add_argument('message', help='보낼 메시지')
    parser.add_argument('--close', '-c', action='store_true', help='보내고 나서 창 닫기')
    parser.add_argument('--json', '-j', action='store_true', help='JSON 출력')
    parser.add_argument('--no-signature', action='store_true', help='서명 없이 보내기 (기본: "sent with claude code" 붙음)')

    args = parser.parse_args()

    # 서명 추가 (--no-signature가 없으면)
    message = args.message
    if not args.no_signature:
        message = args.message + SIGNATURE

    result = send_message(args.chat_name, message, args.close)

    if args.json:
        import json
        print(json.dumps(result, ensure_ascii=False, indent=2))
    else:
        if result['success']:
            print(f"✓ [{result['chat']}]에 메시지 전송 완료")
            print(f"  → {result['message']}")
        else:
            print(f"✗ 전송 실패: {result['error']}")
            sys.exit(1)


if __name__ == '__main__':
    main()


================================================
FILE: plugins/kakaotalk/skills/kakaotalk/SKILL.md
================================================
---
name: kakaotalk
description: This skill should be used when the user asks to "카톡 보내줘", "카카오톡 메시지", "KakaoTalk message", "채팅 읽어줘", "~에게 메시지 보내줘", or needs to send/read messages via KakaoTalk on macOS.
version: 2.0.0
---

# KakaoTalk CLI

macOS에서 CLI를 통해 카카오톡 메시지를 읽고 보내는 스킬.

## 트리거

- "카카오톡 메시지", "카톡 읽어줘", "~에게 메시지 보내줘"

## 스크립트 구조

| 파일 | 용도 |
|------|------|
| `kakao_read.py` | 채팅방 검색, 열기, 메시지 읽기 |
| `kakao_send.py` | 메시지 발송 |

---

## 메시지 발송 워크플로우

### Step 1: 채팅방 열고 대화 내역 읽기

대상 이름으로 채팅방을 열고 대화 내역을 읽습니다:

```bash
uv run python .claude/skills/kakaotalk/scripts/kakao_read.py "대상이름" --json
```

**출력 예시:**
```json
{
  "chat_name": "구봉",
  "messages": [
    {"sender": "나", "text": "오늘 저녁 뭐 먹을까?", "time": "오후 3:24"},
    {"sender": "구봉", "text": "파스타 어때?", "time": "오후 3:45"}
  ]
}
```

**메시지 분석 시 주의:**
- 배열 끝부분이 최신 메시지 (최근일수록 가치 높음)
- 1주일 이상 된 내용은 상황이 바뀌었을 수 있음
- 최근 대화 주제와 자연스럽게 이어지는 메시지 작성

### Step 2: 맥락 파악 후 메시지 작성

읽은 대화 내역을 바탕으로:
1. 최근 대화 흐름 파악
2. 사용자 요청에 맞는 메시지 초안 작성
3. 자연스럽고 맥락에 맞는 내용 구성

### Step 3: 사용자 확인 (필수)

**먼저 텍스트로 메시지 내용을 보여준 후** AskUserQuestion으로 확인:

```
[텍스트 출력]
**최근 대화 요약:**
- {최근 대화 내용 요약}

**보낼 메시지:**
받는 사람: {채팅방}
---
{메시지 내용}

sent with claude code
---

[AskUserQuestion]
질문: "이 메시지를 보낼까요?"
옵션: ["보내기", "수정 필요"]
```

### Step 4: 발송

사용자 확인 후 메시지 발송:

```bash
uv run python .claude/skills/kakaotalk/scripts/kakao_send.py "채팅방이름" "메시지"
```

---

## 메시지 읽기 전용 워크플로우

단순히 대화 내역만 확인할 때:

```bash
uv run python .claude/skills/kakaotalk/scripts/kakao_read.py "대상이름" --json
```

읽은 후 사용자에게 요약 제공:
- 최근 대화 2-3개 요약
- 현재 진행 중인 대화 주제
- 답장이 필요한 내용이 있는지

---

## CLI 옵션 레퍼런스

### kakao_read.py

```bash
# 기본: 채팅방 열고 메시지 읽기
kakao_read.py "채팅방이름" [--limit N] [--json]

# 채팅 목록
kakao_read.py --list [--json]

# 검색
kakao_read.py --search "검색어" [--json]

# 읽고 창 닫기
kakao_read.py "채팅방이름" --close
```

### kakao_send.py

```bash
# 기본 (서명 포함)
kakao_send.py "채팅방" "메시지"
# → "메시지\n\nsent with claude code"

# 서명 없이
kakao_send.py "채팅방" "메시지" --no-signature

# 보내고 창 닫기
kakao_send.py "채팅방" "메시지" --close
```

---

## 예시 시나리오

### "구봉한테 보낼 메시지 제안"

```
[Step 1] 채팅방 열고 읽기
uv run python .../kakao_read.py "구봉" --json

[Step 2] 맥락 파악
최근 대화: 저녁 메뉴 논의 중

[Step 3] 메시지 제안
"파스타 좋아! 오늘 7시에 만날까?"

[Step 4] 사용자 확인 후 발송
```

---

## 요구사항

1. **atomacos 설치**: `uv add atomacos`
2. **Accessibility 권한**: System Settings > Privacy & Security > Accessibility에서 Terminal 허용
3. **카카오톡 실행**: macOS용 카카오톡 앱 실행 중


================================================
FILE: plugins/podcast/.claude-plugin/plugin.json
================================================
{
  "name": "podcast",
  "version": "1.0.0",
  "description": "Generate Korean podcast episodes from any source (URLs, tweets, articles, PDFs) with OpenAI TTS and auto-upload to YouTube",
  "author": {
    "name": "Team Attention",
    "url": "https://github.com/team-attention"
  },
  "repository": "https://github.com/team-attention/plugins-for-claude-natives",
  "license": "MIT",
  "keywords": ["claude-code", "plugin", "podcast", "tts", "openai", "youtube", "korean", "audio"]
}


================================================
FILE: plugins/podcast/README.md
================================================
# Podcast Generator Plugin

Generate Korean podcast episodes from any source — URLs, tweets, articles, PDFs — with OpenAI TTS and auto-upload to YouTube.

## Pipeline

```
Sources → Analysis → Script → TTS (OpenAI) → MP4 → YouTube
```

## Quick Start

```bash
# Install
/plugin install podcast
```

Then just say:
- "이 글을 팟캐스트로 만들어"
- "Make a podcast from these sources"
- "Turn this into an audio episode"

## Features

- **Multi-source fusion**: Analyzes 2+ sources in parallel and synthesizes insights
- **Korean podcast script**: Conversational tone, proper number/name localization
- **OpenAI TTS**: Uses `gpt-4o-mini-tts` with `marin` voice, 1500-char chunking with retry
- **YouTube auto-upload**: OAuth browser flow, resumable upload, metadata saved
- **Partial execution**: Script-only, TTS-only, or upload-only

## Requirements

| Dependency | Purpose |
|-----------|---------|
| ffmpeg | Audio merging + MP4 conversion |
| OpenAI API key | TTS generation (`OPENAI_API_KEY` env var) |
| Google OAuth client secret | YouTube upload |
| Python 3.10+ | All scripts (stdlib only, no pip) |

## Setup

### OpenAI TTS
Set `OPENAI_API_KEY` environment variable, or provide when prompted.

### YouTube Upload
1. Create a Google Cloud project with YouTube Data API v3 enabled
2. Download OAuth client secret JSON
3. Place in `~/Downloads/client_secret_*.json`
4. First upload will open browser for authentication

## License

MIT


================================================
FILE: plugins/podcast/skills/podcast/SKILL.md
================================================
---
name: podcast
description: "Generate Korean podcast episodes from any source (URLs, tweets, articles, PDFs) — analyzes content, writes a script, generates audio via OpenAI TTS, converts to MP4, and auto-uploads to YouTube. Use this skill whenever the user says 'make a podcast', 'convert to podcast', 'podcast', 'create an episode', 'turn this into audio', 'YouTube podcast', 'turn this article into a podcast', 'publish as audio', or provides sources and wants them transformed into a listenable format. Supports partial execution: script-only, TTS-only, or upload-only."
---

# Podcast Generator

Analyze sources, generate a Korean podcast script, produce audio via OpenAI TTS, and auto-upload to YouTube.

## Pipeline

```
[Source Collection] → [Analysis/Fusion] → [Script Writing] → [TTS Generation] → [MP4 Conversion] → [YouTube Upload]
```

## Step 1: Source Collection & Analysis

Collect and analyze user-provided sources. Processing by type:

- **URL/Article**: WebFetch or subagent for full text
- **Tweet/X post**: Use WebFetch with `api.fxtwitter.com` (replace domain in X/Twitter URL)
- **PDF**: Read tool directly
- **GitHub repo**: Clone and analyze structure (use subagent)
- **Conversation context**: Reuse content already analyzed in current session

When 2+ sources are provided, **always spawn parallel subagents** for each.

## Step 2: Script Writing

### Structure (8-12 min, 3000-5000 chars)

```markdown
# [Episode Title]

> [Duration] podcast script | [Date]
> Sources: [source list]

---

## Opening (1 min)
- Hook: one sentence on why this topic matters
- Introduce sources
- Lead with conclusion (state core message upfront)

## Body Part 1 (3 min)
- Deep analysis of first source/perspective

## Body Part 2 (3 min)
- Deep analysis of second source/perspective

## Fusion/Intersection (3 min)
- Emergent insights from combining sources
- Patterns, commonalities, contrasts
- Generalizable implications

## Closing (30 sec)
- One-sentence summary of core message
- Sign-off
```

### Script Writing Principles

- **Write as you speak**: conversational Korean ("~입니다", "~거죠", "~인데요")
- **Numbers in Korean**: "267K" → "이십육만", "$75,000" → "칠만오천 달러"
- **English names in Korean pronunciation**: "Garry Tan" → "개리 탄"
- **No tables or code blocks**: TTS cannot read them. Convert table content to sentences
- **Shift tone for quotes**: "개리 탄 본인이 이렇게 말합니다." to create distinction
- **Short sentences**: keep each sentence under 50 characters

### File Layout

```
<output-dir>/
├── script.md       ← Script
├── episode.mp3     ← Audio
├── episode.mp4     ← Video (for YouTube)
└── metadata.json   ← Title, description, tags, YouTube URL
```

The output directory can be any user-specified path. A sensible default is `podcast/YYYY-MM-DD-[slug]/` relative to the current working directory.

## Step 3: TTS Generation

Convert script to audio using `scripts/generate_tts.py`:

```bash
python3 <plugin-path>/skills/podcast/scripts/generate_tts.py \
  --input <script.md path> \
  --output <episode.mp3 path> \
  --api-key <OpenAI API key>
```

Replace `<plugin-path>` with the actual path where this plugin is installed (use `${CLAUDE_PLUGIN_ROOT}` if available, or the resolved plugin installation path).

### OpenAI API Key

Check `OPENAI_API_KEY` environment variable first. If not set, ask the user.

### TTS Settings

| Setting | Value | Note |
|---------|-------|------|
| Model | `gpt-4o-mini-tts` | Latest model with instructions support |
| Voice | `marin` | Best for Korean. `cedar` as alternative |
| Chunk size | 1500 chars | 2000 token limit, Korean ~1.5 char/token |
| Instructions | Auto-generated per script | See default below |

Default TTS instructions:
> "따뜻하고 친근한 한국어 팟캐스트 호스트. 명확한 발음으로 또박또박 읽되, 자연스러운 억양과 적절한 감정을 담아서. 중요한 포인트에서는 약간 힘을 주고, 인용구에서는 톤을 살짝 바꿔서 구분감을 준다. 전체적으로 지적이면서도 편안한 분위기."

If the user specifies a tone, customize via `--instructions`.

## Step 4: MP4 Conversion

Convert MP3 to MP4 with a static title card:

```bash
python3 <plugin-path>/skills/podcast/scripts/convert_mp4.py \
  --input <episode.mp3 path> \
  --output <episode.mp4 path> \
  --title "Episode Title" \
  --subtitle "Subtitle"
```

Generates a 1920x1080 video with dark background (#1a1a2e) and Korean title/subtitle overlay.

## Step 5: YouTube Upload

```bash
python3 <plugin-path>/skills/podcast/scripts/upload_youtube.py \
  --video <episode.mp4 path> \
  --title "Episode Title" \
  --description "Description" \
  --privacy unlisted
```

### OAuth Setup

- Google OAuth client secret: auto-discovers `~/Downloads/client_secret_*.json` or `~/.config/google/client_secret_*.json`
- Token: stored alongside the video file by default (override with `--token-path`)
- First run requires browser-based Google authentication
- Ask user which YouTube account to use if multiple are available
- Never copy scripts to the episode directory. Always run from the plugin's original path

### Upload Defaults

- Privacy: `unlisted` (unless user specifies otherwise)
- Category: People & Blogs (22)
- Language: ko

## Step 6: Completion Report

After upload, report to user:

```
Done!
- Script: <path>/script.md
- Audio: <path>/episode.mp3
- Video: <path>/episode.mp4
- YouTube: https://youtu.be/VIDEO_ID (unlisted)
```

Play `episode.mp3` with `afplay` so the user can listen immediately.

## Partial Execution

Users may request only part of the pipeline:

- "Just write the script" → Steps 1-2 only
- "Generate TTS from this script" → Step 3 only
- "Upload to YouTube" → Step 5 only (requires existing MP4)
- "Make it public" → Update YouTube privacy via API

## Requirements

- **ffmpeg**: required for audio merging and MP4 conversion. On macOS, `homebrew-ffmpeg/ffmpeg` tap may be needed for full codec support
- **OpenAI API key**: for TTS generation (`OPENAI_API_KEY` env var or provided by user)
- **Google OAuth client secret**: for YouTube upload (download from Google Cloud Console)
- **macOS font**: uses `/System/Library/Fonts/AppleSDGothicNeo.ttc` for Korean text overlay. On other platforms, adjust `FONT_PATH` in `convert_mp4.py`
- **Python 3.10+**: all scripts use standard library only (no pip install needed)


================================================
FILE: plugins/podcast/skills/podcast/scripts/convert_mp4.py
================================================
#!/usr/bin/env python3
"""MP3 → MP4 conversion (dark background + title overlay)"""

import argparse
import os
import subprocess
import sys

FONT_PATH = "/System/Library/Fonts/AppleSDGothicNeo.ttc"
BG_COLOR = "0x1a1a2e"
RESOLUTION = "1920x1080"


def escape_drawtext(text):
    """Escape special characters for ffmpeg drawtext filter"""
    text = text.replace("\\", "\\\\")
    text = text.replace("'", "'\\''")
    text = text.replace(":", "\\:")
    text = text.replace(";", "\\;")
    text = text.replace("[", "\\[")
    text = text.replace("]", "\\]")
    text = text.replace("=", "\\=")
    text = text.replace("%", "%%")
    return text


def convert(input_path, output_path, title, subtitle=""):
    """Convert MP3 to MP4 with static title card via ffmpeg"""
    vf_parts = []

    if title:
        escaped_title = escape_drawtext(title)
        vf_parts.append(
            f"drawtext=text='{escaped_title}'"
            f":fontsize=60:fontcolor=white"
            f":x=(w-text_w)/2:y=(h-text_h)/2-40"
            f":fontfile={FONT_PATH}"
        )

    if subtitle:
        escaped_sub = escape_drawtext(subtitle)
        vf_parts.append(
            f"drawtext=text='{escaped_sub}'"
            f":fontsize=36:fontcolor=0xAAAAAA"
            f":x=(w-text_w)/2:y=(h-text_h)/2+40"
            f":fontfile={FONT_PATH}"
        )

    vf = ",".join(vf_parts) if vf_parts else "null"

    cmd = [
        "ffmpeg", "-y",
        "-f", "lavfi", "-i", f"color=c={BG_COLOR}:s={RESOLUTION}:r=1",
        "-i", input_path,
        "-c:v", "libx264", "-tune", "stillimage",
        "-c:a", "aac", "-b:a", "192k",
        "-pix_fmt", "yuv420p",
        "-shortest",
        "-vf", vf,
        output_path,
    ]

    result = subprocess.run(cmd, capture_output=True, text=True)
    if result.returncode != 0:
        print(f"ffmpeg error: {result.stderr[-500:]}", file=sys.stderr)
        sys.exit(1)

    size_mb = os.path.getsize(output_path) / 1024 / 1024
    print(f"Done! {output_path} ({size_mb:.1f} MB)")


def main():
    parser = argparse.ArgumentParser(description="MP3 to MP4 conversion")
    parser.add_argument("--input", required=True, help="Input MP3 path")
    parser.add_argument("--output", required=True, help="Output MP4 path")
    parser.add_argument("--title", default="", help="Video title")
    parser.add_argument("--subtitle", default="", help="Video subtitle")
    args = parser.parse_args()

    convert(args.input, args.output, args.title, args.subtitle)


if __name__ == "__main__":
    main()


================================================
FILE: plugins/podcast/skills/podcast/scripts/generate_tts.py
================================================
#!/usr/bin/env python3
"""OpenAI gpt-4o-mini-tts로 팟캐스트 음성 생성 — 청크 분할 + ffmpeg 병합"""

import argparse
import json
import os
import re
import subprocess
import sys
import time
import urllib.error
import urllib.request

DEFAULT_MODEL = "gpt-4o-mini-tts"
DEFAULT_VOICE = "marin"
DEFAULT_INSTRUCTIONS = (
    "따뜻하고 친근한 한국어 팟캐스트 호스트. "
    "명확한 발음으로 또박또박 읽되, 자연스러운 억양과 적절한 감정을 담아서. "
    "중요한 포인트에서는 약간 힘을 주고, 인용구에서는 톤을 살짝 바꿔서 구분감을 준다. "
    "전체적으로 지적이면서도 편안한 분위기."
)
MAX_CHARS = 1500  # gpt-4o-mini-tts: 2000 token limit, 한국어 ~1.5 char/token


def extract_speech_text(md_path):
    """마크다운에서 실제 대사만 추출 (헤더, 메타데이터, 테이블, 코드블록 제거)"""
    with open(md_path, "r") as f:
        text = f.read()

    lines = text.split("\n")
    speech_lines = []
    skip = False
    for line in lines:
        if line.startswith("# ") and speech_lines == []:
            continue
        if line.startswith(">"):
            continue
        if line.startswith("---"):
            continue
        if line.startswith("## "):
            speech_lines.append("")
            continue
        if line.startswith("```"):
            skip = not skip
            continue
        if line.startswith("|"):
            continue
        if skip:
            continue
        clean = line.strip()
        clean = re.sub(r'\*\*(.+?)\*\*', r'\1', clean)
        clean = re.sub(r'\*(.+?)\*', r'\1', clean)
        clean = re.sub(r'`(.+?)`', r'\1', clean)
        clean = re.sub(r'\[(.+?)\]\(.+?\)', r'\1', clean)
        clean = re.sub(r'^[-*]\s+', '', clean)  # 불릿 마커 제거
        if clean:
            speech_lines.append(clean)

    return "\n".join(speech_lines)


def split_paragraph_by_sentences(para, max_chars=MAX_CHARS):
    """단일 문단이 max_chars를 초과할 때 문장 단위로 분할"""
    sentences = re.split(r'(?<=[.!?。])\s+', para)
    chunks = []
    current = ""
    for sent in sentences:
        if len(current) + len(sent) + 1 > max_chars:
            if current:
                chunks.append(current.strip())
            if len(sent) > max_chars:
                for i in range(0, len(sent), max_chars):
                    chunks.append(sent[i:i + max_chars])
                current = ""
            else:
                current = sent
        else:
            current = current + " " + sent if current else sent
    if current.strip():
        chunks.append(current.strip())
    return chunks


def split_into_chunks(text, max_chars=MAX_CHARS):
    """문단 단위로 청크 분할 (초과 문단은 문장 단위로 재분할)"""
    paragraphs = text.split("\n\n")
    chunks = []
    current = ""

    for para in paragraphs:
        para = para.strip()
        if not para:
            continue
        if len(para) > max_chars:
            if current:
                chunks.append(current.strip())
                current = ""
            chunks.extend(split_paragraph_by_sentences(para, max_chars))
            continue
        if len(current) + len(para) + 2 > max_chars:
            if current:
                chunks.append(current.strip())
            current = para
        else:
            current = current + "\n\n" + para if current else para

    if current.strip():
        chunks.append(current.strip())

    return chunks


def generate_tts_chunk(text, output_path, api_key, model, voice, instructions,
                       max_retries=3):
    """OpenAI TTS API 단일 청크 호출 (재시도 + 지수 백오프)"""
    payload = {
        "model": model,
        "input": text,
        "voice": voice,
        "response_format": "mp3",
    }
    if instructions:
        payload["instructions"] = instructions

    data = json.dumps(payload).encode("utf-8")

    for attempt in range(max_retries):
        req = urllib.request.Request(
            "https://api.openai.com/v1/audio/speech",
            data=data,
            headers={
                "Authorization": f"Bearer {api_key}",
                "Content-Type": "application/json",
            },
            method="POST",
        )
        try:
            with urllib.request.urlopen(req, timeout=180) as resp:
                with open(output_path, "wb") as f:
                    f.write(resp.read())
            return
        except urllib.error.HTTPError as e:
            body = e.read().decode("utf-8", errors="replace")
            if e.code == 429 or e.code >= 500:
                wait = 2 ** attempt
                print(f"    Retry {attempt+1}/{max_retries} (waiting {wait}s)...",
                      file=sys.stderr)
                time.sleep(wait)
                continue
            print(f"    API Error {e.code}: {body}", file=sys.stderr)
            raise
        except (urllib.error.URLError, TimeoutError):
            if attempt < max_retries - 1:
                wait = 2 ** attempt
                print(f"    Network error, retry {attempt+1}/{max_retries} (waiting {wait}s)...",
                      file=sys.stderr)
                time.sleep(wait)
                continue
            raise

    raise RuntimeError(f"TTS API failed after {max_retries} attempts")


def merge_audio(chunk_files, output_path):
    """ffmpeg concat으로 청크 병합"""
    if len(chunk_files) == 1:
        os.rename(chunk_files[0], output_path)
        return

    output_dir = os.path.dirname(output_path)
    list_file = os.path.join(output_dir, "_chunks.txt")
    with open(list_file, "w") as f:
        for cf in chunk_files:
            f.write(f"file '{cf}'\n")

    subprocess.run(
        ["ffmpeg", "-y", "-f", "concat", "-safe", "0",
         "-i", list_file, "-c", "copy", output_path],
        check=True, capture_output=True,
    )

    os.remove(list_file)
    for cf in chunk_files:
        os.remove(cf)


def get_duration(path):
    """ffprobe로 오디오 길이 반환 (초)"""
    result = subprocess.run(
        ["ffprobe", "-v", "error", "-show_entries", "format=duration",
         "-of", "default=noprint_wrappers=1:nokey=1", path],
        capture_output=True, text=True,
    )
    return float(result.stdout.strip())


def main():
    parser = argparse.ArgumentParser(description="Podcast TTS Generation")
    parser.add_argument("--input", required=True, help="Script markdown path")
    parser.add_argument("--output", required=True, help="Output MP3 path")
    parser.add_argument("--api-key", default=os.environ.get("OPENAI_API_KEY", ""), help="OpenAI API key")
    parser.add_argument("--model", default=DEFAULT_MODEL)
    parser.add_argument("--voice", default=DEFAULT_VOICE)
    parser.add_argument("--instructions", default=DEFAULT_INSTRUCTIONS)
    args = parser.parse_args()

    if not args.api_key:
        print("ERROR: --api-key or OPENAI_API_KEY env var required", file=sys.stderr)
        sys.exit(1)

    print("1/4 Extracting speech text...")
    speech_text = extract_speech_text(args.input)
    print(f"    Total: {len(speech_text)} chars")

    print("2/4 Splitting into chunks...")
    chunks = split_into_chunks(speech_text)
    print(f"    {len(chunks)} chunks")

    print("3/4 Generating TTS...")
    output_dir = os.path.dirname(args.output)
    chunk_files = []
    for i, chunk in enumerate(chunks):
        out = os.path.join(output_dir, f"_chunk_{i:03d}.mp3")
        print(f"    [{i+1}/{len(chunks)}] {len(chunk)} chars...")
        generate_tts_chunk(chunk, out, args.api_key, args.model, args.voice, args.instructions)
        chunk_files.append(out)

    print("4/4 Merging audio...")
    merge_audio(chunk_files, args.output)

    duration = get_duration(args.output)
    minutes, seconds = int(duration // 60), int(duration % 60)
    print(f"\nDone! {args.output} ({minutes}m {seconds}s)")


if __name__ == "__main__":
    main()


================================================
FILE: plugins/podcast/skills/podcast/scripts/upload_youtube.py
================================================
#!/usr/bin/env python3
"""YouTube Data API v3 resumable upload — standard library only"""

import argparse
import glob
import http.server
import json
import os
import sys
import urllib.error
import urllib.parse
import urllib.request
import webbrowser

SCOPES = "https://www.googleapis.com/auth/youtube.upload"
REDIRECT_PORT = 8085
REDIRECT_URI = f"http://localhost:{REDIRECT_PORT}"


def find_client_secret():
    """Auto-discover Google OAuth client secret"""
    patterns = [
        os.path.expanduser("~/Downloads/client_secret_*.json"),
        os.path.expanduser("~/.config/google/client_secret_*.json"),
    ]
    for p in patterns:
        matches = glob.glob(p)
        if matches:
            return sorted(matches)[-1]
    return None


def load_client_config(path):
    with open(path) as f:
        data = json.load(f)
    cfg = data.get("installed") or data.get("web")
    return cfg["client_id"], cfg["client_secret"]


def get_auth_code(client_id):
    """Browser OAuth flow → authorization code"""
    auth_url = (
        "https://accounts.google.com/o/oauth2/v2/auth?"
        + urllib.parse.urlencode({
            "client_id": client_id,
            "redirect_uri": REDIRECT_URI,
            "response_type": "code",
            "scope": SCOPES,
            "access_type": "offline",
            "prompt": "consent",
        })
    )

    code_holder = {}

    class Handler(http.server.BaseHTTPRequestHandler):
        def do_GET(self):
            qs = urllib.parse.parse_qs(urllib.parse.urlparse(self.path).query)
            code_holder["code"] = qs.get("code", [None])[0]
            self.send_response(200)
            self.send_header("Content-Type", "text/html; charset=utf-8")
            self.end_headers()
            self.wfile.write("Auth complete! You can close this tab.".encode("utf-8"))

        def log_message(self, *args):
            pass

    server = http.server.HTTPServer(("localhost", REDIRECT_PORT), Handler)
    print("  Opening browser for Google auth...")
    webbrowser.open(auth_url)
    server.handle_request()
    server.server_close()
    return code_holder.get("code")


def exchange_code(client_id, client_secret, code, token_path):
    data = urllib.parse.urlencode({
        "code": code,
        "client_id": client_id,
        "client_secret": client_secret,
        "redirect_uri": REDIRECT_URI,
        "grant_type": "authorization_code",
    }).encode()

    req = urllib.request.Request("https://oauth2.googleapis.com/token", data=data)
    with urllib.request.urlopen(req) as resp:
        tokens = json.loads(resp.read())

    with open(token_path, "w") as f:
        json.dump(tokens, f, indent=2)
    print(f"  Token saved: {token_path}")
    return tokens["access_token"]


def refresh_token(client_id, client_secret, token_path):
    with open(token_path) as f:
        tokens = json.load(f)

    data = urllib.parse.urlencode({
        "refresh_token": tokens["refresh_token"],
        "client_id": client_id,
        "client_secret": client_secret,
        "grant_type": "refresh_token",
    }).encode()

    req = urllib.request.Request("https://oauth2.googleapis.com/token", data=data)
    with urllib.request.urlopen(req) as resp:
        new_tokens = json.loads(resp.read())

    tokens["access_token"] = new_tokens["access_token"]
    with open(token_path, "w") as f:
        json.dump(tokens, f, indent=2)
    return tokens["access_token"]


def get_access_token(client_secret_path, token_path):
    client_id, client_secret = load_client_config(client_secret_path)

    if os.path.exists(token_path):
        try:
            return refresh_token(client_id, client_secret, token_path)
        except Exception:
            print("  Token expired. Re-authenticating...")

    code = get_auth_code(client_id)
    if not code:
        print("ERROR: Failed to get authorization code.", file=sys.stderr)
        sys.exit(1)
    return exchange_code(client_id, client_secret, code, token_path)


def upload_video(access_token, video_path, title, description, tags, privacy):
    """Resumable upload"""
    metadata = {
        "snippet": {
            "title": title,
            "description": description,
            "tags": tags,
            "categoryId": "22",
            "defaultLanguage": "ko",
        },
        "status": {
            "privacyStatus": privacy,
            "selfDeclaredMadeForKids": False,
        },
    }

    meta_bytes = json.dumps(metadata).encode("utf-8")
    file_size = os.path.getsize(video_path)

    init_req = urllib.request.Request(
        "https://www.googleapis.com/upload/youtube/v3/videos?"
        + urllib.parse.urlencode({"uploadType": "resumable", "part": "snippet,status"}),
        data=meta_bytes,
        headers={
            "Authorization": f"Bearer {access_token}",
            "Content-Type": "application/json; charset=utf-8",
            "X-Upload-Content-Length": str(file_size),
            "X-Upload-Content-Type": "video/mp4",
        },
        method="POST",
    )

    with urllib.request.urlopen(init_req) as resp:
        upload_url = resp.headers["Location"]

    print(f"  Uploading... ({file_size / 1024 / 1024:.1f} MB)")
    with open(video_path, "rb") as f:
        video_data = f.read()

    upload_req = urllib.request.Request(
        upload_url,
        data=video_data,
        headers={
            "Authorization": f"Bearer {access_token}",
            "Content-Type": "video/mp4",
            "Content-Length": str(file_size),
        },
        method="PUT",
    )

    with urllib.request.urlopen(upload_req, timeout=300) as resp:
        return json.loads(resp.read())


def main():
    parser = argparse.ArgumentParser(description="YouTube Upload")
    parser.add_argument("--video", required=True, help="MP4 file path")
    parser.add_argument("--title", required=True, help="Video title")
    parser.add_argument("--description", default="", help="Video description")
    parser.add_argument("--tags", default="", help="Tags (comma-separated)")
    parser.add_argument("--privacy", default="unlisted", choices=["public", "unlisted", "private"])
    parser.add_argument("--client-secret", default=None, help="OAuth client secret path")
    parser.add_argument("--token-path", default=None, help="Token storage path")
    args = parser.parse_args()

    client_secret = args.client_secret or find_client_secret()
    if not client_secret:
        print("ERROR: Google OAuth client secret not found.", file=sys.stderr)
        print("  Place client_secret_*.json in ~/Downloads/ or use --client-secret", file=sys.stderr)
        sys.exit(1)

    token_path = args.token_path or os.path.join(os.path.dirname(args.video), "youtube_token.json")
    tags = [t.strip() for t in args.tags.split(",") if t.strip()] if args.tags else []

    print("1/2 OAuth authentication...")
    access_token = get_access_token(client_secret, token_path)

    print("2/2 YouTube upload...")
    result = upload_video(access_token, args.video, args.title, args.description, tags, args.privacy)

    video_id = result["id"]
    url = f"https://youtu.be/{video_id}"
    print(f"\nUpload complete!")
    print(f"  URL: {url}")
    print(f"  Status: {result['status']['privacyStatus']}")

    meta_path = os.path.join(os.path.dirname(args.video), "metadata.json")
    with open(meta_path, "w") as f:
        json.dump({
            "youtube_url": url,
            "youtube_id": video_id,
            "title": args.title,
            "description": args.description,
            "privacy": result["status"]["privacyStatus"],
        }, f, indent=2, ensure_ascii=False)


if __name__ == "__main__":
    main()


================================================
FILE: plugins/say-summary/.claude-plugin/plugin.json
================================================
{
  "name": "say-summary",
  "version": "1.0.0",
  "description": "Speaks a short summary of Claude's response using macOS say command",
  "author": {
    "name": "Team Attention",
    "url": "https://github.com/team-attention"
  },
  "repository": "https://github.com/team-attention/plugins-for-claude-natives",
  "license": "MIT",
  "keywords": ["accessibility", "audio", "tts", "macos"],
  "hooks": "./hooks/hooks.json"
}


================================================
FILE: plugins/say-summary/README.md
================================================
# say-summary

A Claude Code plugin that speaks a short summary of Claude's response using macOS text-to-speech.

## Features

- Summarizes Claude's response to 3-10 words using Claude Haiku
- Speaks the summary aloud using macOS `say` command
- **Korean/English auto-detection**: Uses Yuna voice for Korean, Samantha for English
- Runs in background so it doesn't block Claude Code

## Requirements

- **macOS** (uses the `say` command)
- **Python 3.10+**
- **Claude Code CLI** installed

## Installation

```bash
# Add the marketplace
/plugin marketplace add team-attention/plugins-for-claude-natives

# Install the plugin
/plugin install say-summary

# Run setup to install Python dependencies
~/.claude/plugins/say-summary/scripts/setup.sh
```

Or manually install the dependency:

```bash
pip3 install --user claude-agent-sdk
```

## How It Works

1. When Claude finishes responding (Stop hook), the plugin extracts the last message
2. If the message is longer than 10 words, it uses Claude Haiku to create a short headline
3. The summary is spoken aloud via macOS `say` command

## Configuration

The plugin uses these defaults:
- Speech rate: 190 words per minute
- Model: Claude Haiku (for fast summarization)
- Korean voice: Yuna
- English voice: Samantha

## Logs

Logs are written to `/tmp/speak-hook.log` for debugging.

## License

MIT


================================================
FILE: plugins/say-summary/hooks/hooks.json
================================================
{
  "description": "Summarize and speak last Claude response",
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/say-summary.py",
            "timeout": 30
          }
        ]
      }
    ]
  }
}


================================================
FILE: plugins/say-summary/requirements.txt
================================================
claude-agent-sdk>=0.1.0


================================================
FILE: plugins/say-summary/scripts/say-summary.py
================================================
#!/usr/bin/env python3
"""
Stop hook: Summarizes and speaks the last Claude response.

- Extracts the last assistant message from transcript
- Uses Claude Agent SDK (Haiku) to summarize in 10 words or less
- Speaks the summary via macOS say command
- Runs in background so hook exits immediately
"""

import asyncio
import json
import os
import subprocess
from datetime import datetime
from pathlib import Path

from claude_agent_sdk import (AssistantMessage, ClaudeAgentOptions, TextBlock,
                              query)

LOG_FILE = Path("/tmp/speak-hook.log")


def log(message: str) -> None:
    """Write message to log file."""
    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
    with open(LOG_FILE, "a") as f:
        f.write(f"[{timestamp}] {message}\n")


def get_project_dir() -> Path | None:
    """Find Claude project directory for current working directory."""
    cwd = os.getcwd()
    # /Users/bong/path/to/project -> -Users-bong-path-to-project
    project_dir_name = cwd.replace("/", "-")
    claude_project_dir = Path.home() / ".claude" / "projects" / project_dir_name

    if claude_project_dir.is_dir():
        return claude_project_dir
    return None


def get_latest_transcript(project_dir: Path) -> Path | None:
    """Find most recently modified transcript file."""
    jsonl_files = list(project_dir.glob("*.jsonl"))
    if not jsonl_files:
        return None

    return max(jsonl_files, key=lambda f: f.stat().st_mtime)


def extract_last_assistant_message(transcript_path: Path) -> str | None:
    """Extract last assistant message from transcript."""
    try:
        with open(transcript_path, "r") as f:
            lines = f.readlines()

        # Search in reverse order
        for line in reversed(lines):
            try:
                data = json.loads(line)
                message = data.get("message", {})

                if message and message.get("role") == "assistant":
                    content = message.get("content", [])

                    # Extract text type items
                    text_parts = [
                        item.get("text", "")
                        for item in content
                        if isinstance(item, dict) and item.get("type") == "text"
                    ]

                    full_text = "".join(text_parts)
                    if full_text:
                        return full_text

            except json.JSONDecodeError:
                continue

    except Exception as e:
        log(f"Error reading transcript: {e}")

    return None


async def summarize_with_haiku(text: str) -> str:
    """Summarize message to 10 words or less using Claude Haiku."""
    # Return as-is if already 10 words or less
    if len(text.split()) <= 10:
        return text.strip()

    # Truncate for faster processing
    truncated = text[:500] if len(text) > 500 else text

    system_prompt = "You are a headline writer. Output ONLY a 3-10 word headline. No questions. No commentary. No offers to help. Just the headline. If the text contains both English and Korean, write the headline in Korean."

    options = ClaudeAgentOptions(
        model="haiku",
        system_prompt=system_prompt,
        allowed_tools=[],
        max_turns=1
    )

    response_text = ""
    try:
        async for message in query(prompt=f"요약할 텍스트: {truncated}", options=options):
            if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        response_text += block.text
                        # Return immediately after first response
                        return response_text.strip()
    except Exception as e:
        log(f"Haiku summarization failed: {e}")
        return text[:50].strip()

    return response_text.strip() if response_text else text[:50].strip()


def detect_korean(text: str) -> bool:
    """Check if text contains Korean characters."""
    for char in text:
        if '\uac00' <= char <= '\ud7a3':  # 한글 음절
            return True
        if '\u1100' <= char <= '\u11ff':  # 한글 자모
            return True
    return False


def speak(text: str) -> None:
    """Speak text via macOS say command (background).

    - Uses rate -r 190 for natural pace
    - Detects language: Korean uses Yuna, English uses Samantha
    """
    cmd = ["nohup", "say", "-r", "190"]

    if detect_korean(text):
        cmd.extend(["-v", "Yuna"])
    else:
        cmd.extend(["-v", "Samantha"])

    cmd.append(text)

    subprocess.Popen(
        cmd,
        stdout=subprocess.DEVNULL,
        stderr=subprocess.DEVNULL,
        start_new_session=True
    )


async def async_main() -> None:
    log("=== HOOK START ===")
    log(f"PWD: {os.getcwd()}")

    # 1. Find project directory
    project_dir = get_project_dir()
    if not project_dir:
        log("Project dir not found")
        return
    log(f"Project dir: {project_dir}")

    # 2. Find latest transcript file
    transcript_path = get_latest_transcript(project_dir)
    if not transcript_path:
        log("No transcript file found")
        return
    log(f"Transcript: {transcript_path.name}")

    # 3. Extract last assistant message
    last_message = extract_last_assistant_message(transcript_path)
    if not last_message:
        log("No assistant message found")
        return
    log(f"Found message ({len(last_message)} chars)")

    # 4. Summarize with Haiku
    summary = await summarize_with_haiku(last_message)
    log(f"Summary: {summary}")

    # 5. Speak summary
    speak(summary)

    log("=== HOOK END ===")


def main() -> None:
    asyncio.run(async_main())


if __name__ == "__main__":
    main()


================================================
FILE: plugins/say-summary/scripts/setup.sh
================================================
#!/bin/bash
# Setup script for say-summary plugin
# Installs required Python dependencies

set -e

echo "Installing say-summary plugin dependencies..."

# Check if pip is available
if ! command -v pip3 &> /dev/null; then
    echo "Error: pip3 is not installed. Please install Python 3 first."
    exit 1
fi

# Install claude-agent-sdk
pip3 install --user claude-agent-sdk

echo "Done! Plugin is ready to use."
echo ""
echo "Note: This plugin requires macOS (uses the 'say' command for TTS)."


================================================
FILE: plugins/session-wrap/.claude-plugin/plugin.json
================================================
{
  "name": "session-wrap",
  "version": "1.0.0",
  "description": "Session wrap-up workflow with multi-agent analysis pipeline for documentation, automation, learning, and follow-up suggestions",
  "author": {
    "name": "Team Attention",
    "url": "https://github.com/team-attention"
  },
  "repository": "https://github.com/team-attention/plugins-for-claude-natives",
  "license": "MIT",
  "keywords": ["session", "wrap-up", "documentation", "automation", "multi-agent", "history-insight", "session-analyzer"]
}


================================================
FILE: plugins/session-wrap/README.md
================================================
# Session Wrap Plugin

A Claude Code plugin for comprehensive session wrap-up with multi-agent analysis.

## Features

- **Multi-Agent Analysis Pipeline**: 5 specialized agents analyze your session from different perspectives
- **2-Phase Architecture**: Parallel analysis followed by sequential validation
- **Documentation Updates**: Identify what should be added to CLAUDE.md and context.md
- **Automation Discovery**: Find patterns worth automating as skills/commands/agents
- **Learning Capture**: Extract insights, mistakes, and discoveries in TIL format
- **Follow-up Planning**: Prioritized task list for next session
- **Duplicate Prevention**: Validates proposals against existing content

## Installation

### Option 1: Plugin Directory

```bash
# Clone or copy to your plugins directory
git clone https://github.com/team-attention/plugins-for-claude-natives
cd plugins-for-claude-natives/plugins/session-wrap

# Or copy directly
cp -r session-wrap ~/.claude/plugins/
```

### Option 2: Direct Use

```bash
claude --plugin-dir /path/to/session-wrap
```

## Usage

### Basic Usage

```
/wrap
```

Runs the full wrap-up workflow:
1. Check git status
2. Phase 1: Run 4 analysis agents in parallel
3. Phase 2: Validate proposals for duplicates
4. Present results and let you choose actions
5. Execute selected actions

### Quick Commit

```
/wrap fix typo in README
```

When arguments are provided, creates a commit with that message directly.

## Architecture

```
Phase 1: Analysis (Parallel)
┌──────────────┬──────────────┬──────────────┬──────────────┐
│ doc-updater  │ automation-  │ learning-    │ followup-    │
│              │ scout        │ extractor    │ suggester    │
└──────┬───────┴──────┬───────┴──────┬───────┴──────┬───────┘
       └──────────────┴──────────────┴──────────────┘
                            │
                            ▼
Phase 2: Validation (Sequential)
┌─────────────────────────────────────────────────────────────┐
│                    duplicate-checker                         │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
                    User Selection
```

## Agents

| Agent | Model | Purpose |
|-------|-------|---------|
| `doc-updater` | sonnet | Analyze documentation update needs |
| `automation-scout` | sonnet | Detect automation opportunities |
| `learning-extractor` | sonnet | Extract learnings and mistakes |
| `followup-suggester` | sonnet | Suggest prioritized follow-up tasks |
| `duplicate-checker` | haiku | Validate proposals for duplicates |

## Skills

### session-wrap
Session wrap-up best practices, multi-agent orchestration patterns, 2-phase pipeline design guidance.

**Trigger phrases:** "session wrap-up", "wrap best practices", "multi-agent orchestration", "2-phase pipeline"

### history-insight
Claude Code 세션 히스토리를 분석하고 인사이트를 추출합니다.

**Trigger phrases:** "capture session", "save session history", "what we discussed", "today's work", "session history"

### session-analyzer
Post-hoc analysis tool for validating Claude Code session behavior against SKILL.md specifications.

**Trigger phrases:** "analyze session", "세션 분석", "evaluate skill execution", "check session logs"

## Directory Structure

```
session-wrap/
├── .claude-plugin/
│   └── plugin.json           # Plugin manifest
├── commands/
│   └── wrap.md               # /wrap command
├── agents/
│   ├── doc-updater.md        # Documentation analysis
│   ├── automation-scout.md   # Automation detection
│   ├── learning-extractor.md # Learning capture
│   ├── followup-suggester.md # Task prioritization
│   └── duplicate-checker.md  # Validation
├── skills/
│   ├── session-wrap/
│   │   ├── SKILL.md          # Best practices guide
│   │   └── references/
│   │       └── multi-agent-patterns.md
│   ├── history-insight/
│   │   ├── SKILL.md          # Session history analysis
│   │   ├── scripts/
│   │   │   └── extract-session.sh
│   │   └── references/
│   │       └── session-file-format.md
│   └── session-analyzer/
│       ├── SKILL.md          # Post-hoc session validation
│       ├── scripts/
│       │   ├── extract-hook-events.sh
│       │   ├── extract-subagent-calls.sh
│       │   └── find-session-files.sh
│       └── references/
│           ├── analysis-patterns.md
│           └── common-issues.md
└── README.md
```

## When to Use

**Use `/wrap` when:**
- Ending a significant work session
- Before switching to a different project
- After completing a feature or bug fix
- When unsure what to document

**Skip when:**
- Very short session with trivial changes
- Only reading/exploring code
- Quick one-off question answered

## Integration with plugin-dev

When `automation-scout` recommends creating a new skill/command/agent, use:

```
/plugin-dev:create-plugin
```

This will guide you through creating a well-structured automation.

## References

- [Anthropic Multi-Agent Research](https://www.anthropic.com/engineering/multi-agent-research-system)
- [Azure AI Agent Design Patterns](https://learn.microsoft.com/en-us/azure/architecture/ai-ml/guide/ai-agent-design-patterns)

## License

MIT


================================================
FILE: plugins/session-wrap/agents/automation-scout.md
================================================
---
name: automation-scout
description: |
  Analyze automation patterns. Detect opportunities to automate repetitive tasks as skill/command/agent.
tools: ["Read", "Glob", "Grep"]
model: sonnet
color: green
---

# Automation Scout

Specialized agent that identifies patterns in work sessions and recommends optimal automation mechanisms (skill, command, agent).

## Core Responsibilities

1. **Pattern Detection**: Identify repetitive workflows, multi-step processes, tedious tasks
2. **Automation Classification**: Determine best fit among skill, command, agent
3. **Specific Recommendations**: Provide concrete implementation suggestions with examples
4. **Duplicate Prevention**: Check existing automations before recommending new ones

## Analysis Framework

### Automation Types

#### Skill (`.claude/skills/`)

**Good for:**
- Multi-step workflows requiring external integrations (APIs, databases, services)
- Tasks requiring orchestration of multiple tools
- Complex business logic or data transformations
- Service integrations (Notion, Slack, etc.)
- Tasks requiring API response handling and action chaining

**Pattern examples:**
- "Sync meeting notes to documentation"
- "Generate report from multiple data sources"
- "Deploy app and update tracking"
- "Fetch from API, transform, store in database"

#### Command (`.claude/commands/`)

**Good for:**
- Quick, focused tasks within conversation flow
- Format conversion or data processing
- Session management utilities
- Text generation with specific templates
- Tasks returning results directly to conversation

**Pattern examples:**
- "Format this data as table"
- "Generate wrap-up report"
- "Translate code between languages"
- "Generate summary from text"

#### Agent (`.claude/agents/`)

**Good for:**
- Tasks requiring specialized domain expertise
- Complex analysis needing deep knowledge
- Tasks requiring autonomous decision-making
- Workflows benefiting from consistent persona/approach
- When you want to delegate to an expert

**Pattern examples:**
- "Review code for security issues" → security-reviewer agent
- "Analyze database schema" → database-architect agent
- "Optimize performance" → performance-optimizer agent
- "Review architecture decisions" → architecture-reviewer agent

## Pattern Detection Process

### Step 1: Identify Candidates

Scan session for:

**1. Repetition (frequency ≥ 2):**
- Same task performed multiple times
- Similar workflows with slight variations
- Recurring analysis or review patterns

**2. Multi-tool Workflows:**
- Bash → Read → Write sequences
- API call → data transformation → storage
- Search → analyze → report patterns

**3. Format-heavy Tasks:**
- Consistent output structure required
- Template-based generation
- Data transformations with fixed rules

**4. External Integration Patterns:**
- Repeated API calls to same service
- Database operations with similar structure
- File system operations with consistent logic

### Step 2: Check Existing Automations

Search with Glob and Read:
```bash
# Search existing skills
Glob: .claude/skills/*/SKILL.md

# Search existing commands
Glob: .claude/commands/*.md

# Search existing agents
Glob: .claude/agents/**/*.md
```

Find with Grep:
- Similar keywords in descriptions
- Related functionality
- Overlapping use cases

### Step 3: Classify Automation Type

Decision tree:

```
Need integration with external services? (API, DB, Slack, etc.)
├─ YES → Likely Skill
└─ NO → Continue

Need specialized domain knowledge or complex analysis?
├─ YES → Likely Agent
└─ NO → Continue

Primarily format conversion or quick utility?
├─ YES → Likely Command
└─ NO → Consider Skill or Agent based on complexity
```

### Step 4: Formulate Recommendations

For each automation opportunity:

```markdown
## [Automation Name]

**Type:** [Skill / Command / Agent]

**Detected Pattern:**
- Frequency: [X times this session / repetitive pattern]
- Workflow: [Pattern description]
- Tools used: [List of tools/services]

**Current Pain:**
- [What's tedious about current approach]
- [Errors that could be prevented]
- [Time that could be saved]

**Proposed Solution:**

[For Skill]
```yaml
# .claude/skills/[name]/SKILL.md
---
name: [name]
description: [Single line description. No YAML multiline (|, >) allowed]
---

# [Skill Title]

# Trigger: "[Phrases that trigger this]"
# Dependencies: [Required APIs, tools]

# [Pseudocode or implementation outline]
```

> **Important**: description must be **single line**. No YAML multiline syntax (`|`, `>`).

[For Command]
```markdown
# .claude/commands/[name].md
# Usage: /[name] [args]

[Command specification]
```

[For Agent]
```markdown
# .claude/agents/[name].md
# Trigger condition: [Condition]

[Agent specification outline]
```

**Expected Benefits:**
- Time saved: [Estimate]
- Error reduction: [Errors prevented]
- Consistency: [What becomes more consistent]

**Similar Existing Automation:**
- [None / Similar automation name at [path]]
- [If similar exists: Difference / Why both needed]

**Implementation Priority:**
- [High / Medium / Low]
- [Reason for priority]
```

## Quality Standards

1. **Clear Justification**: Explain why this automation type is best
2. **Concrete Examples**: Show actual code/config snippets
3. **Quantified Benefits**: Estimate time saved or errors prevented
4. **Duplicate Awareness**: Always check for similar existing automations
5. **Realistic Scope**: Don't over-engineer; propose minimum viable automation

## Output Format

```markdown
# Automation Opportunity Analysis

## Summary
- Automation opportunities identified: [X]
- Skills recommended: [X]
- Commands recommended: [X]
- Agents recommended: [X]

---

## High Priority

### [Automation 1]
[Full recommendation in format above]

---

## Medium Priority

### [Automation 2]
[Full recommendation in format above]

---

## Low Priority / Future Consideration

### [Automation 3]
[Full recommendation in format above]

---

## No Automation Needed

[Explanation if no clear automation opportunities]
```

## Edge Cases

- **One-off tasks**: Don't recommend automation for truly unique tasks
- **Rapidly changing workflows**: Flag if pattern might change soon
- **Over-automation**: Consider if manual execution is actually simpler
- **Maintenance burden**: Note if automation would be harder to maintain than manual process
- **Existing partial solutions**: Suggest extending existing automation rather than creating new

## Decision Guidelines

**Prefer Skill:**
- External API/service integration needed
- Multiple steps with complex logic
- State maintained between steps
- Error handling and retry important

**Prefer Command:**
- Pure text/data transformation
- Quick utility within conversation
- Template-based generation
- No external dependencies

**Prefer Agent:**
- Domain expertise required
- Complex analysis or reasoning
- Consistent approach/persona beneficial
- Multiple decision points in workflow

**Don't Automate:**
- Used once or very rarely
- Easier to do manually
- Requirements unclear or changing
- Automation more complex than task itself

## Implementation Guidance

When automation is recommended, guide users to create it properly:

**For plugin-based automation (skill/command/agent):**
```
If you want to implement this automation, use:
/plugin-dev:create-plugin

This will guide you through creating a complete, well-structured plugin
with proper triggering conditions, system prompts, and validation.
```

**For simple single-file additions:**
- Commands: Create directly in `.claude/commands/`
- Agents: Create directly in `.claude/agents/`
- Skills: Create skill directory in `.claude/skills/`

**Recommendation**: For anything more than a simple command, use `/plugin-dev:create-plugin` for better structure, validation, and maintainability.


================================================
FILE: plugins/session-wrap/agents/doc-updater.md
================================================
---
name: doc-updater
description: |
  Analyze documentation update needs for CLAUDE.md and context.md. Use during session wrap-up to determine what should be documented.
tools: ["Read", "Glob", "Grep"]
model: sonnet
color: blue
---

# Doc Updater

Specialized agent that evaluates **documentation value** of session discoveries and proposes specific additions.

## Core Responsibilities

1. **Session Context Analysis**: Identify content worth documenting
2. **Update Classification**: Determine which file to update (CLAUDE.md, context.md)
3. **Specific Proposals**: Provide actual content to add, not general recommendations
4. **Duplicate Prevention**: Cross-reference existing docs to avoid redundancy

## Analysis Process

### Step 1: Read Current Documentation

```
Read: CLAUDE.md (if exists)
Glob: **/context.md
```

### Step 2: Identify Update Candidates

#### CLAUDE.md Targets

**Look for:**
- **New commands**: Commands added to `.claude/commands/`
- **New skills**: Skills created in `.claude/skills/`
- **New agents**: Agents added to `.claude/agents/`
- **Environment changes**: New env vars, dependencies, setup steps
- **Project structure changes**: New directories, submodules, major reorganization
- **Workflow updates**: New automation processes, integration patterns
- **Tool configuration**: MCP servers, external tools, API integrations

**CLAUDE.md Addition Criteria:**
- Information Claude needs in future sessions
- Reference information used repeatedly
- Settings/configurations affecting all projects
- Cross-project patterns or standards

#### context.md Targets

**Look for:**
- **Project-specific knowledge**: Details only relevant to specific project
- **Customer/client context**: Business requirements, constraints, preferences
- **Technical constraints**: Known limitations, workarounds, caveats
- **Historical context**: Why certain decisions were made
- **Recurring issues**: Problems that keep coming up and their solutions
- **Tacit knowledge**: Things not obvious from code alone

**context.md Addition Criteria:**
- Project-specific (not applicable to other projects)
- Helps understand "why" not just "what"
- Captures tribal knowledge or organizational memory
- Explains non-intuitive patterns or decisions

### Step 3: Duplicate Check

Search with Grep:
- Similar section headers
- Related keywords
- Overlapping functionality
- Existing documentation on same topic

Note when found:
- Location of duplicate/similar content
- Whether truly new information
- Whether merge/replace is better than addition

### Step 4: Format Proposals

For each proposed update:

```markdown
## [Filename]

### Section: [Section name or new section]

**Proposed Addition:**
```
[Exact markdown content to add]
```

**Rationale:** [Why this should be added]

**Location:** [Where in file - e.g., "Under ## Development Environment" or "New section after ## Git Submodules"]

**Duplicate Check:** [Not found / Similar content exists at [location]]
```

## Quality Standards

1. **Specificity**: Provide exact text to add, no vague suggestions
2. **Context**: Include enough detail for future sessions to understand
3. **Format**: Follow existing document structure and style
4. **Relevance**: Only propose truly documentation-worthy content
5. **Completeness**: Include code examples, commands, links when helpful

## Output Format

```markdown
# Documentation Update Analysis

## Summary
- CLAUDE.md updates recommended: [X]
- context.md updates recommended: [X]

---

## CLAUDE.md Updates

### [Proposal 1]

**Section**: [Existing or new section name]

**Content to Add:**
```markdown
[Actual markdown to add]
```

**Rationale**: [Why needed]

**Location**: [Exact location]

**Duplicate Check**: [Result]

---

## context.md Updates

### [Project name]/context.md

**Content to Add:**
```markdown
[Actual markdown to add]
```

**Rationale**: [Why needed]

---

## No Updates Needed

[Explanation if no updates required]
```

## Edge Cases

- **Temporary experiments**: Don't document one-off experiments that won't become permanent
- **Work in progress**: Note if incomplete and should be documented later
- **Sensitive information**: Flag credentials, private data that should be in .env
- **Conflicting information**: If new info contradicts existing docs, suggest resolution
- **Version-specific**: Note if content only applies to specific versions/environments

## Key Principles

- Focus on **actionable** documentation updates
- Prioritize information that saves time in future sessions
- Consider target audience (future Claude or team members)
- Balance completeness with conciseness
- When uncertain, lean toward documenting (too much better than too little)


================================================
FILE: plugins/session-wrap/agents/duplicate-checker.md
================================================
---
name: duplicate-checker
description: |
  Phase 2 validation agent. Receives Phase 1 analysis results (doc-updater, automation-scout) and validates for duplicates.
tools: ["Read", "Glob", "Grep"]
model: haiku
color: yellow
---

# Duplicate Checker (Phase 2)

Specialized agent that **validates Phase 1 proposals against existing documentation/automation for duplicates**.

> **Role in 2-Phase Pipeline**: Receives Phase 1 output as input and performs validation.
> Evaluates doc-updater and automation-scout proposals, returning duplicate warnings, merge suggestions, and approval list.

## Core Responsibilities

1. **Phase 1 Proposal Validation**: Check doc-updater and automation-scout proposals for duplicates
2. **Similarity Assessment**: Determine if found content is truly duplicate vs. merely related
3. **Location Mapping**: Provide exact file paths and line numbers for duplicates
4. **Classification**: Categorize each proposal as Approved/Merge/Skip

## Input Format

Phase 1 results are passed in this format:

```markdown
## doc-updater proposals:
### CLAUDE.md Update
- Section: [Section name]
- Content to add: [Specific content]

### context.md Update
- Project: [Project name]
- Content to add: [Specific content]

## automation-scout proposals:
### [Automation name]
- Type: Skill/Command/Agent
- Function: [Description]
```

## Search Strategy

### Step 1: Extract Search Terms from Phase 1 Proposals

**From doc-updater proposals:**
- Section headers, keywords, command names, workflow names

**From automation-scout proposals:**
- Skill/command/agent names
- Trigger phrases
- Key verbs/nouns from function descriptions

### Step 2: Execute Multi-Layer Search

#### Layer 1: Exact Match
Find exact phrases or names:
```bash
# Search exact tool/command/skill names
Grep: "[exact-name]" in .claude/
Grep: "[exact-name]" in *.md
```

#### Layer 2: Keyword Match
Find individual keywords:
```bash
# Search each important keyword
Grep: "[keyword1]" in CLAUDE.md
Grep: "[keyword1]" in **/context.md
```

#### Layer 3: Section Headers
Use Read and manual scan for similar section structures:
- Headers with similar phrasing
- Tables with similar column names
- Lists describing similar functionality

#### Layer 4: Functional Overlap
Use Read to understand:
- What existing skills/commands/agents do
- How they overlap with proposed content
- Where integration makes sense

### Step 3: Evaluate Search Results

For each match found, determine:

**1. Duplicate Type:**
- **Complete duplicate**: Same information, same context
- **Partial duplicate**: Some overlap but also unique information
- **Related**: Same topic but different perspective/purpose
- **False positive**: Contains keyword but actually different

**2. Location:**
- File path
- Line number or section header
- Context (which section it's in)

**3. Recommendation:**
- **Skip**: Content already well-documented here
- **Merge**: Combine new information with existing content
- **Add**: Unique enough to add as separate entry
- **Replace**: New content better than existing

## Search Scope by Content Type

### CLAUDE.md Updates

Search in:
- `CLAUDE.md` (entire file)
- Section-specific search based on proposed update location

Look for:
- Similar command descriptions
- Overlapping workflow documentation
- Redundant environment setup instructions
- Duplicate tool configuration

### context.md Updates

Search in:
- All `context.md` files via `Glob: **/context.md`
- Project-specific READMEs
- Related documentation in same project directory

Look for:
- Similar project constraints or caveats
- Overlapping technical context
- Duplicate problem/solution descriptions
- Redundant historical explanations

### Skills/Commands/Agents

Search in:
- `.claude/skills/` (all SKILL.md files and READMEs)
- `.claude/commands/` (all .md files)
- `.claude/agents/` (all .md files)

Look for:
- Same trigger phrases
- Similar functionality
- Overlapping tool usage patterns
- Redundant automation goals

## Output Format

```markdown
# Phase 2 Validation Results

## Summary
| Proposal Source | Total | Approved | Merge | Skip |
|----------------|-------|----------|-------|------|
| doc-updater | [X] | [X] | [X] | [X] |
| automation-scout | [X] | [X] | [X] | [X] |

---

## Approved Proposals (No Duplicates)

### doc-updater proposals
1. **[Proposal title]** → Approved
   - Search scope: CLAUDE.md, context.md
   - Conclusion: Unique content, safe to add

### automation-scout proposals
1. **[Automation name]** → Approved
   - Search scope: skills/, commands/, agents/
   - Conclusion: No similar automation, safe to create

---

## Merge Recommended

### [Proposal title]

**Phase 1 Proposal:**
```
[Proposed content]
```

**Existing Content:** `/path/to/file.md` line [X]
```
[Existing content]
```

**Overlap:** [What's duplicate]
**Unique:** [What's new]

**Merge Suggestion:**
```
[Merged content]
```

---

## Skip Recommended (Complete Duplicate)

### [Proposal title]

**Phase 1 Proposal:**
```
[Proposed content]
```

**Already Exists:** `/path/to/file.md` line [X]
```
[Existing content]
```

**Conclusion:** Content already exists, addition unnecessary

---

## Validation Details

**Search Scope:**
- CLAUDE.md: Full scan
- context.md: [X] files
- skills: [X] checked
- commands: [X] checked
- agents: [X] checked
```

## Quality Standards

1. **Thoroughness**: Search all relevant locations, not just obvious ones
2. **Precision**: Distinguish true duplicates from merely related content
3. **Actionability**: Provide clear recommendations with reasoning
4. **Context**: Show enough existing content to support evaluation
5. **Completeness**: Document search scope to avoid missed duplicates

## Edge Cases

- **Similar but different scope**: Two skills that sound similar but serve different use cases
- **Content evolution**: Old content that should be replaced with newer, better version
- **Cross-project patterns**: Same pattern used in multiple projects (may be intentional)
- **Version differences**: Similar content for different versions/environments
- **Renamed content**: Same functionality under new name

## Search Optimization

**For generic terms:**
- Use exact phrases in quotes when possible
- Combine multiple keywords to reduce false positives
- Search specific directories if scope is known

**For automation checks:**
- Always check trigger phrases, not just names
- Search for similar function descriptions
- Check related categories too (e.g., check commands when verifying skills)

**For documentation checks:**
- Search section headers as well as content
- Look for similar table structures
- Find related keywords in different sections

## Key Principles

- **False negatives are costly**: Better to over-report potential duplicates than miss them
- **Context matters**: Same words in different contexts may not be duplicates
- **Evolution is OK**: Similar but evolved content may be appropriate at times
- **Cross-reference**: Even if not duplicate, suggest cross-references for related content
- **Merge vs Replace**: Consider if old content has preservation value


================================================
FILE: plugins/session-wrap/agents/followup-suggester.md
================================================
---
name: followup-suggester
description: |
  Suggest follow-up tasks. Identify incomplete work, improvement points, and prioritize next session tasks.
tools: ["Read", "Glob", "Grep"]
model: sonnet
color: cyan
---

# Followup Suggester

Specialized agent that analyzes current work state to identify **incomplete tasks, improvement opportunities, and logical next steps** for future sessions.

## Core Responsibilities

1. **Incomplete Task Detection**: Identify unfinished features, partial implementations, open questions
2. **Improvement Identification**: Discover optimization, refactoring, enhancement areas
3. **Priority Assignment**: Rank tasks by urgency, impact, and dependencies
4. **Context Preservation**: Capture enough information for seamless continuation

## Task Categories

### 1. Incomplete Implementations

#### Partially Built Features
- **Feature**: What was being built
- **Completed**: What's finished
- **Remaining**: What still needs work
- **Blocker**: What's preventing completion (if any)
- **Expected effort**: Time to complete

#### Unfinished Refactoring
- **Target**: What needs refactoring
- **Reason**: Why refactoring started
- **Progress**: How far along
- **Next steps**: Specific actions to continue

#### Abandoned Experiments
- **What tried**: Experiment description
- **Why stopped**: Reason for abandonment
- **Decision needed**: Resume or discard?
- **Alternatives**: Other approaches to consider

### 2. Testing & Validation Needed

#### Untested Code
- **Needs testing**: Specific functions/features
- **Test type**: Unit/integration/e2e
- **Test scenarios**: Key cases to cover
- **Risk**: What could break without tests

#### Known Issues
- **Bug description**: What's wrong
- **Severity**: Critical/High/Medium/Low
- **Workaround**: Temporary fix (if any)
- **Root cause**: If known
- **Fix approach**: How to resolve

#### Edge Cases
- **Scenario**: Untested edge case
- **Current behavior**: How system likely handles it
- **Expected behavior**: How it should handle it
- **Test approach**: How to verify

### 3. Documentation Gaps

#### Code Documentation
- **Needs docs**: Functions/modules/APIs
- **Current state**: What documentation exists
- **Missing info**: What should be added
- **Audience**: Who needs this documentation

#### User Documentation
- **Feature**: What users need to understand
- **Format**: README/wiki/tutorial/guide
- **Content**: Key points to cover
- **Examples**: Demos needed

### 4. Optimization Opportunities

#### Performance
- **Bottleneck**: What's slow
- **Impact**: How much it affects UX
- **Approach**: Potential optimization strategies
- **Measurement**: How to verify improvement

#### Code Quality
- **Issue**: What's messy or complex
- **Refactoring**: How to improve
- **Benefit**: Why it matters
- **Risk**: What could break

#### Architecture
- **Current limitation**: What doesn't scale
- **Proposed change**: Better approach
- **Migration**: How to transition
- **Impact**: What else changes

### 5. Infrastructure & Tooling

#### Setup & Configuration
- **Needs setup**: Tool/service/environment
- **Purpose**: Why it's needed
- **Steps**: How to configure
- **Documentation**: Where to record setup

#### Automation
- **Manual process**: What's tedious
- **Automation approach**: How to automate
- **Effort**: Implementation time
- **Payoff**: Time saved per use

## Analysis Process

### Step 1: Scan for Incomplete Work

#### Search with Grep:
```bash
# Find TODO comments
Grep: "TODO" in **/*.{js,ts,py,go,java,md}

# Find FIXME comments
Grep: "FIXME" in **/*.{js,ts,py,go,java,md}

# Find WIP markers
Grep: "WIP" in **/*.{js,ts,py,go,java,md}

# Find temporary fixes
Grep: "HACK" OR "TEMP" in **/*.{js,ts,py,go,java,md}
```

#### Review with Read:
- Recently modified files for incomplete logic
- Test files for missing coverage
- Documentation for placeholders

#### Session Review:
- Features mentioned but not implemented
- Decisions deferred for later
- Questions left unanswered

### Step 2: Identify Improvement Areas

#### Code Quality Check
- Functions over 50 lines
- Duplicated logic
- Complex conditionals
- Missing error handling
- Hardcoded values

#### Architecture Review
- Tight coupling
- Missing abstractions
- Scalability concerns
- Security gaps

#### User Experience
- Missing feedback
- Unclear error messages
- Unhandled edge cases
- Performance bottlenecks

### Step 3: Prioritize Tasks

#### Priority Matrix

**P0 - Urgent (Must do first)**
- Blocking other work
- Production bugs
- Security issues
- Data integrity risks

**P1 - High (Should do soon)**
- Critical feature incomplete
- Significant technical debt
- Performance issues affecting UX
- Missing critical tests

**P2 - Medium (Should do)**
- Code quality improvements
- Documentation gaps
- Minor feature incomplete
- Nice-to-have optimizations

**P3 - Low (Can do)**
- Future enhancements
- Experimental ideas
- Non-critical refactoring
- Optional automation

#### Effort Estimation

- **Quick (<1 hour)**: Small fixes, simple tests, minor docs
- **Medium (1-4 hours)**: Features, refactoring, test suites
- **Large (>4 hours)**: Architecture changes, major features, migrations

#### Impact Assessment

- **High**: Affects core functionality or many users
- **Medium**: Improves experience or developer productivity
- **Low**: Nice-to-have improvements

### Step 4: Create Actionable Tasks

For each task:

```markdown
### [Task Title]

**Category:** [Feature/Bug/Test/Docs/Optimization/Infrastructure]

**Description:** [What needs to be done, 1-2 sentences]

**Context:** [Why it matters and relevant background]

**Specific Steps:**
1. [Concrete action 1]
2. [Concrete action 2]
3. [Concrete action 3]

**Done Criteria:**
- [ ] [How to verify completion, criterion 1]
- [ ] [How to verify completion, criterion 2]

**Related Files:**
- `/path/to/file1.ext`
- `/path/to/file2.ext`

**Dependencies:** [Other tasks that must be done first, if any]

**Expected Effort:** [Quick/Medium/Large]

**Priority:** [P0/P1/P2/P3]

**Impact:** [High/Medium/Low]

**Notes:** [Additional context or caveats]
```

## Output Format

```markdown
# Follow-up Tasks & Recommendations

## Summary
- Total tasks identified: [X]
- P0 (Urgent): [X]
- P1 (High): [X]
- P2 (Medium): [X]
- P3 (Low): [X]

**Recommended Focus for Next Session:**
[1-2 sentence summary of what to tackle next]

---

## P0 - Urgent (Must Do First)

### [Task 1]
[Full task template above]

---

## P1 - High Priority (Should Do Soon)

### [Task 2]
[Full task template above]

---

## P2 - Medium Priority (Should Do)

### [Task 3]
[Full task template above]

---

## P3 - Low Priority (Can Do)

### [Task 4]
[Full task template above]

---

## Quick Wins (< 1 hour, High Impact)

Recommended to tackle first:

1. **[Task name]** (P[X]) - [One-line description]
   - Files: [file1.ext, file2.ext]
   - Why: [Brief justification]

---

## Continued from This Session

Work started but not completed:

### [Incomplete Task 1]

**What's Done:**
- [Completed step 1]
- [Completed step 2]

**What Remains:**
- [ ] [Remaining step 1]
- [ ] [Remaining step 2]

**Current State:** [Where things are now]

**Next Action:** [Specific first step to resume]

---

## Future Improvements

Ideas to consider later:

- **[Improvement 1]**: [Description and potential value]
- **[Improvement 2]**: [Description and potential value]

---

## Known Issues / Technical Debt

Issues to eventually address:

| Issue | Impact | Effort | Priority | Notes |
|-------|--------|--------|----------|-------|
| [Issue 1] | [H/M/L] | [Quick/Medium/Large] | [P0-P3] | [Context] |

---

## Session Continuity Notes

**To Resume Work:**
1. [Specific step to start]
2. [Context to review]
3. [Command to run]

**Key Files to Review:**
- `/path/to/file1` - [Why]
- `/path/to/file2` - [Why]

**Open Questions:**
- [Question 1]
- [Question 2]
```

## Quality Standards

1. **Specificity**: Provide specific file paths, line numbers, function names
2. **Actionability**: Clear first steps, not vague goals
3. **Completeness**: Enough context to resume without re-investigation
4. **Prioritized**: Honest assessment of importance and urgency
5. **Realistic**: Reasonable effort estimates

## Edge Cases

- **No clear next steps**: Suggest exploration tasks or documentation review
- **Too many tasks**: Group related tasks, suggest multi-session planning
- **Unclear priorities**: Provide decision framework, note dependencies
- **Experimental work**: Clearly mark as exploratory vs. committed
- **Pending decisions**: List what needs to be decided and by whom

## Key Principles

- **Unblock first**: Identify what's preventing progress
- **Dependencies**: Note task order and what depends on what
- **Context loss**: Assume reader won't remember session details
- **Effort accuracy**: Better to overestimate than underestimate
- **Value focus**: Prioritize high-impact items, even if difficult


================================================
FILE: plugins/session-wrap/agents/learning-extractor.md
================================================
---
name: learning-extractor
description: |
  Extract learnings, mistakes, and new discoveries from session. Summarize in TIL format for knowledge building.
tools: ["Read", "Glob", "Grep"]
model: sonnet
color: magenta
---

# Learning Extractor

Specialized agent that identifies valuable lessons, new knowledge, and mistakes from work sessions to build organizational knowledge.

## Core Responsibilities

1. **Knowledge Capture**: Identify new technical knowledge, patterns, insights gained
2. **Mistake Documentation**: Recognize errors and document lessons learned
3. **Pattern Recognition**: Discover approaches that worked or failed
4. **Capability Development**: Track progress in understanding or abilities

## Learning Categories

### 1. Technical Discoveries

#### New APIs/Libraries
- **What discovered**: Name and purpose of new tool/library/API
- **Use case**: Problem it solves
- **Key features**: Most important capabilities learned
- **Gotchas**: Unexpected behaviors or limitations found
- **Example**: Actual code snippet or usage pattern

#### New Patterns/Techniques
- **Pattern name**: What to call this approach
- **Context**: When/why to use it
- **Implementation**: How it works
- **Advantages**: Why better than alternatives tried
- **Example**: Real application from session

#### Framework/Tool Features
- **Feature**: Specific capability discovered
- **Previous assumption**: What was thought before
- **Actual behavior**: How it really works
- **Impact**: How this changes future approach

### 2. Problem-Solving Lessons

#### Successful Approaches
- **Problem**: What needed solving
- **Approach**: What worked
- **Result**: Outcome achieved
- **Why it worked**: Analysis of success factors
- **When to reuse**: Conditions where this applies again

#### Failed Attempts
- **What tried**: Approach that didn't work
- **Why failed**: Root cause understanding
- **Lesson**: What to avoid or do differently
- **Better alternative**: What worked instead

#### Debugging Insights
- **Bug encountered**: Issue description
- **Misleading symptoms**: What threw off investigation
- **Actual cause**: Root cause found
- **Debugging technique**: How it was discovered
- **Prevention**: How to avoid similar issues

### 3. Domain Knowledge

#### Business Logic
- **Concept**: Business rule or domain concept learned
- **Context**: Where/why it matters
- **Implication**: How it affects technical decisions

#### User Behavior
- **Observation**: User interaction pattern
- **Insight**: Understanding of motivation or need
- **Design impact**: How it should influence implementation

#### System Constraints
- **Constraint**: Limitation or requirement discovered
- **Source**: Why this constraint exists
- **Workaround**: How to work within it
- **Impact**: What it prevents or requires

### 4. Process Improvements

#### Workflow Optimization
- **Old way**: Previous approach
- **New way**: Improved method discovered
- **Efficiency gain**: Time/effort saved
- **When to use**: Conditions where new way is better

#### Tool Usage
- **Tool**: Software/service used
- **Feature**: Capability leveraged
- **Productivity gain**: How it helped
- **Best practice**: Optimal usage learned

### 5. Mistakes & Corrections

#### Common Errors
- **Mistake**: What went wrong
- **Frequency**: How often it occurs
- **Root cause**: Why it keeps happening
- **Prevention**: How to avoid in future
- **Detection**: How to catch it early

#### Misconceptions
- **What was wrong**: Incorrect assumption
- **Correct understanding**: Actual truth
- **How discovered**: What revealed the error
- **Ripple effects**: What else this affects

## Extraction Process

### Step 1: Scan for Learning Indicators

Look for these patterns in session:
- **Questions**: "How does X work?", "Why did Y fail?", "Best way to do Z?"
- **Trial and error**: Multiple attempts before success
- **Surprises**: "Interesting!", "Didn't know that", "Unexpected"
- **Discoveries**: "Ah, now I see", "So that's how it works"
- **Corrections**: "Actually X doesn't work that way", "Should do Y instead"
- **Optimizations**: "This is faster/better than the old way"
- **Warnings**: "Watch out for X", "Don't forget Y"

### Step 2: Contextualize Each Learning

For each identified learning:
1. **Capture specifics**: Exact API names, code patterns, error messages
2. **Explain context**: What led to this discovery
3. **Document evidence**: Code snippets, error outputs, test results
4. **Extract insight**: General lesson beyond this specific instance
5. **Note applicability**: When/where it applies

### Step 3: Prioritize Learnings

Rank by:
- **Reusability**: How likely this knowledge will be needed again
- **Impact**: How much it affects future work
- **Novelty**: How new/unexpected it is
- **Shareability**: How valuable to others

### Step 4: Format for Future Reference

Create:
- **Searchable**: Include relevant keywords
- **Scannable**: Clear headers and structure
- **Actionable**: Enough detail to apply
- **Connected**: Links to related concepts or docs

## Output Format

```markdown
# Session Learning Extraction

## Summary
- Technical discoveries: [X]
- Success patterns identified: [X]
- Mistakes documented: [X]
- Process improvements found: [X]

---

## Technical Discoveries

### [Discovery 1: API/Library/Pattern Name]

**What:** [One-line description]

**Context:** [When/why needed]

**Key Insight:** [Main lesson]

**Details:**
- [Specific detail 1]
- [Specific detail 2]

**Code Example:**
```[language]
[Actual code snippet from session]
```

**When to use:** [Conditions/scenarios]

**Gotchas:** [Warnings or limitations]

---

## What Worked Well

### [Success Pattern 1]

**Problem:** [What needed solving]

**Approach:** [What was done]

**Result:** [Outcome achieved]

**Why it worked:** [Success factor analysis]

**Reusable Pattern:**
```
[Generalized pattern for reuse]
```

---

## Mistakes & Lessons

### [Mistake 1]

**What went wrong:** [Error description]

**Symptoms:** [How it manifested]

**Root cause:** [Why it happened]

**How fixed:** [Solution]

**Lesson:** [What to do differently]

**Prevention:** [How to avoid in future]

---

## Process Improvements

### [Improvement 1]

**Old approach:** [Previous method]

**New approach:** [Better method discovered]

**Improvement:** [What's better and by how much]

**When to apply:** [Situations where helpful]

---

## Insights & Realizations

### [Insight 1]

**Previous understanding:** [What was thought before]

**New understanding:** [Corrected/enhanced understanding]

**Implications:** [How it changes approach]

**Evidence:** [What led to this realization]

---

## Resources Discovered

- **[Tool/Library/Article name]**: [URL] - [Why valuable]
- **[Documentation/Tutorial]**: [URL] - [What it clarifies]

---

## Recommended Actions

Based on these learnings:

1. **[Action 1]**: [What and why to do]
2. **[Action 2]**: [What and why to do]

---

## Notes for Future Sessions

- [Important thing to remember next time]
- [Shortcut or technique to reuse]
- [Warning to keep in mind]
```

## Quality Standards

1. **Specificity**: Include actual code, error messages, URLs—no vague descriptions
2. **Contextual**: Explain when/why it matters, not just what
3. **Actionable**: Enough detail to apply the learning
4. **Honest**: Document failures as much as successes
5. **Connected**: Link to related concepts and resources

## Edge Cases

- **Negative learning**: Things that didn't work (worth documenting!)
- **Partial understanding**: Note what's still unclear or uncertain
- **Evolving knowledge**: Flag learnings that might change with more experience
- **Conflicting information**: When new learning contradicts previous understanding
- **Context-specific**: Clarify learnings that only apply in certain situations

## Key Principles

- **Failures are learning**: Mistakes and failed attempts often most valuable
- **Small wins count**: Even minor optimizations or shortcuts worth capturing
- **Question everything**: If something was surprising, that's a learning
- **Write for future self**: Document as if you'll forget in 6 months
- **Share knowledge**: Consider which learnings benefit others on the team

## Learning Value by Type

**High value:**
- Problem that took 30+ minutes to solve
- Non-intuitive API behavior discovered
- Solution for recurring issue found
- Technique applicable across multiple projects

**Medium value:**
- Existing workflow optimization
- New feature of familiar tool learned
- Better practice identified
- Understanding of why something works

**Low value (but still document):**
- Minor syntax/convention learned
- Small productivity tips
- Reminder of forgotten knowledge
- Confirmation of expected behavior


================================================
FILE: plugins/session-wrap/commands/wrap.md
================================================
---
description: Session wrap-up - analyze session, suggest documentation updates, automation opportunities, and follow-up tasks
allowed-tools: Bash(git *), Read, Write, Edit, Glob, Grep, Task, AskUserQuestion
---

# Session Wrap-up (/wrap)

Wrap up the current session by analyzing work done and suggesting improvements.

## Prerequisites

Before starting, load the session-wrap skill for detailed workflow guidance.

## Quick Usage

- `/wrap` - Interactive session wrap-up (recommended)
- `/wrap [message]` - Quick commit with provided message

## Execution

Follow the workflow defined in the **session-wrap** skill:

1. Check git status
2. Phase 1: Run 4 analysis agents in parallel
3. Phase 2: Run validation agent
4. Integrate results and present options
5. Execute selected actions

Refer to `skills/session-wrap/SKILL.md` for detailed execution steps and agent configurations.


================================================
FILE: plugins/session-wrap/skills/history-insight/SKILL.md
================================================
---
name: history-insight
description: This skill should be used when user wants to access, capture, or reference Claude Code session history. Trigger when user says "capture session", "save session history", or references past/current conversation as a source - whether for saving, extracting, summarizing, or reviewing. This includes any mention of "what we discussed", "today's work", "session history", or when user treats the conversation itself as source material (e.g., "from our conversation").
version: 1.1.0
user-invocable: true
---

# History Insight

Claude Code 세션 히스토리를 분석하고 인사이트를 추출합니다.

---

## Data Location

```
~/.claude/projects/<encoded-cwd>/*.jsonl
```

**Path Encoding:** `/Users/foo/project` → `-Users-foo-project`

> 상세 파일 포맷: `${baseDir}/references/session-file-format.md`

---

## Execution Algorithm

### Step 1: Ask Scope [MANDATORY]

**스코프 결정:**

1. **명시된 경우** (AskUserQuestion 생략 가능):
   - "현재 프로젝트만" / "이 프로젝트" → `current_project`
   - "모든 세션" / "전체" → `all_sessions`

2. **명시되지 않은 경우** - AskUserQuestion 호출:
   ```
   question: "세션 검색 범위를 선택하세요"
   options:
     - "현재 프로젝트만" → ~/.claude/projects/<encoded-cwd>/*.jsonl
     - "모든 Claude Code 세션" → ~/.claude/projects/**/*.jsonl
   ```

---

### Step 2: Find Session Files

```bash
# Current project only
find ~/.claude/projects/<encoded-cwd> -name "*.jsonl" -type f

# All sessions (모든 프로젝트)
find ~/.claude/projects -name "*.jsonl" -type f
```

**날짜 필터링**: 파일의 mtime(수정시간) 확인 후 필터. OS별 `stat` 옵션 다름:
- macOS: `stat -f "%Sm" -t "%Y-%m-%d" <file>`
- Linux: `stat -c "%y" <file>`

---

### Step 3: Process Sessions

#### Decision Tree

```
Session files found?
├─ No → Error: "No sessions found"
└─ Yes → How many files?
    ├─ 1-3 files → Direct Read + parse
    └─ 4+ files → Batch Extract Pipeline
```

#### 1-3 Files

직접 Read로 JSONL 파싱. 파일이 크면(≥5000 tokens) `extract-session.sh` 사용:
```bash
${baseDir}/scripts/extract-session.sh <session.jsonl>
```

#### 4+ Files: Batch Extract Pipeline

1. 캐시 디렉토리 생성 (`/tmp/cc-cache/<analysis-name>/`)
2. 세션 목록 저장 (`sessions.txt`)
3. jq로 메시지 일괄 추출 (`user_messages.txt`)
4. 정리 및 필터링 (`clean_messages.txt`)
5. Task(opus)로 종합 분석

#### 파일이 너무 클 때: 병렬 배치 분석

`clean_messages.txt`가 너무 커서 Read 실패 시:

1. **파일 분할**:
   ```bash
   split -l 2000 clean_messages.txt /tmp/cc-cache/<name>/batch_
   ```

2. **병렬 Task(opus) 호출**:
   ```
   Task(subagent_type="general-purpose", model="opus", run_in_background=true)
   prompt: "batch_XX 파일을 읽고 주제/패턴 요약해줘"
   ```

3. **결과 병합**: Task(opus)로 종합

---

### Step 4: Report Results

```markdown
## Session Capture Complete

- **Sessions:** N files processed
- **Messages:** X total, Y after filter

### Extracted Insights
[분석 결과]
```

---

## Error Handling

| Scenario | Response |
|----------|----------|
| No session files found | "No session files found for this project." |
| File too large | Auto-preprocess with extract-session.sh |
| jq not installed | "Error: jq is required. Install with: brew install jq" |
| Task failed | "Warning: Could not process [file]. Skipping." |
| 0 relevant sessions | "No sessions matched your criteria." |

---

## Security Notes

- 출력에 전체 경로 노출 금지 (`~` prefix 사용)

---

## Related Resources

- **`${baseDir}/scripts/extract-session.sh`** - JSONL 압축 (thinking, tool_use 제거)
- **`${baseDir}/references/session-file-format.md`** - JSONL 구조 및 파싱


================================================
FILE: plugins/session-wrap/skills/history-insight/references/session-file-format.md
================================================
# Session File Format (.jsonl)

Claude Code 세션 파일의 상세 구조 및 파싱 방법

## JSONL Type 분류

| type | 설명 | 필요 여부 |
|------|------|---------|
| `user` | 사용자 메시지 | ✅ 필요 |
| `assistant` | Claude 응답 | ✅ 필요 (text만) |
| `file-history-snapshot` | 파일 백업 스냅샷 | ❌ 버림 |
| `queue-operation` | 큐 연산 로그 | ❌ 버림 |
| `system` | 시스템 메시지 | ⚪ 선택 |
| `summary` | 세션 요약 | ⚪ 선택 |

## 실제 분석 결과 (12MB 파일 예시)

| Type | Lines | Size | 비율 |
|------|-------|------|------|
| `file-history-snapshot` | 7,984 | 8.4MB | **67%** |
| `queue-operation` | 15,948 | 3.4MB | **27%** |
| `user` | 127 | 542KB | 4% |
| `assistant` | 163 | 255KB | 2% |
| `system` | 13 | 9KB | <1% |
| `summary` | 5 | 600B | <1% |

**결론:** 실제 대화는 6%, 나머지 94%는 메타데이터

## assistant 메시지 내부 구조

`.message.content[]` 배열 내부:

| 내부 type | 설명 | 필요 여부 |
|-----------|------|---------|
| `thinking` | Claude 생각 과정 + signature | ❌ 버림 |
| `tool_use` | tool 호출 정보 | ❌ 버림 |
| `text` | **실제 응답 텍스트** | ✅ 필요 |

## JSON 파싱 명령어

**user 메시지 추출:**
```bash
jq -c 'select(.type == "user") | {type, content: .message.content, ts: .timestamp}' <file.jsonl>
```

**assistant 메시지 추출 (text만):**
```bash
jq -c 'select(.type == "assistant") | {type, texts: [.message.content[] | select(.type == "text") | .text], ts: .timestamp}' <file.jsonl>
```

**한 번에 대화만 추출:**
```bash
jq -c '
  if .type == "user" then
    {type: "user", content: .message.content, ts: .timestamp}
  elif .type == "assistant" then
    {type: "assistant", texts: [.message.content[]? | select(.type == "text") | .text], ts: .timestamp}
    | select(.texts | length > 0)
  else empty end
' <file.jsonl>
```

**결과:** 12MB → ~160KB (99% 감소)


================================================
FILE: plugins/session-wrap/skills/history-insight/scripts/extract-session.sh
================================================
#!/bin/bash
# extract-session.sh
# Extract essential conversation from Claude Code session JSONL files
#
# Usage: ./extract-session.sh <session.jsonl>
# Output: Filtered JSON to stdout
#
# ============================================================
# 세션 파일 구조 분석 결과 (12MB 파일 예시)
# ============================================================
#
# JSONL type 분포:
#   file-history-snapshot : 67% (8.4MB) → 버림
#   queue-operation       : 27% (3.4MB) → 버림
#   user + assistant      :  6% (800KB) → 추출
#   system, summary       : <1%         → 선택적
#
# assistant.message.content[] 내부:
#   thinking  : Claude 생각 + signature → 버림
#   tool_use  : tool 호출 정보          → 버림
#   text      : 실제 응답 텍스트        → 추출
#
# 결과: 12MB → ~800KB (93% 감소)
# ============================================================

set -e

SESSION_FILE="$1"

if [ -z "$SESSION_FILE" ]; then
  echo "Usage: $0 <session.jsonl>" >&2
  exit 1
fi

if [ ! -f "$SESSION_FILE" ]; then
  echo "Error: File not found: $SESSION_FILE" >&2
  exit 1
fi

if ! command -v jq &> /dev/null; then
  echo "Error: jq is required. Install with: brew install jq" >&2
  exit 1
fi

# Extract conversation only:
# - summary: 세션 요약
# - user: 사용자 메시지 (.message.content)
# - assistant: Claude 응답 중 text만 (.message.content[].type == "text")
#
# Explicitly ignored (94% of file size):
# - file-history-snapshot: 파일 백업 스냅샷
# - queue-operation: 큐 연산 로그
# - assistant.thinking: 생각 과정 + signature
# - assistant.tool_use: tool 호출 정보

jq -c '
  if .type == "summary" then
    {type: "summary", summary: .summary}
  elif .type == "user" then
    {
      type: "user",
      content: .message.content,
      ts: .timestamp
    }
  elif .type == "assistant" then
    {
      type: "assistant",
      texts: [.message.content[]? | select(.type == "text") | .text],
      ts: .timestamp
    } | select(.texts | length > 0)
  else
    empty
  end
' "$SESSION_FILE" 2>/dev/null | jq -s '{
  file: "'"$SESSION_FILE"'",
  message_count: length,
  messages: .
}'


================================================
FILE: plugins/session-wrap/skills/session-analyzer/SKILL.md
================================================
---
name: session-analyzer
description: This skill should be used when the user asks to "analyze session", "세션 분석", "evaluate skill execution", "스킬 실행 검증", "check session logs", "로그 분석", provides a session ID with a skill path, or wants to verify that a skill executed correctly in a past session. Post-hoc analysis of Claude Code sessions to validate skill/agent/hook behavior against SKILL.md specifications.
version: 1.0.0
user-invocable: true
---

# Session Analyzer Skill

Post-hoc analysis tool for validating Claude Code session behavior against SKILL.md specifications.

## Purpose

Analyze completed sessions to verify:
1. **Expected vs Actual Behavior** - Did the skill follow SKILL.md workflow?
2. **Component Invocations** - Were SubAgents, Hooks, and Tools called correctly?
3. **Artifacts** - Were expected files created/deleted?
4. **Bug Detection** - Any unexpected errors or deviations?

---

## Input Requirements

| Parameter | Required | Description |
|-----------|----------|-------------|
| `sessionId` | YES | UUID of the session to analyze |
| `targetSkill` | YES | Path to SKILL.md to validate against |
| `additionalRequirements` | NO | Extra validation criteria |

---

## Phase 1: Locate Session Files

### Step 1.1: Find Session Files

Session files are located in `~/.claude/`:

```bash
# Main session log
~/.claude/projects/-{encoded-cwd}/{sessionId}.jsonl

# Debug log (detailed)
~/.claude/debug/{sessionId}.txt

# Agent transcripts (if subagents were used)
~/.claude/projects/-{encoded-cwd}/agent-{agentId}.jsonl
```

Use script to locate files:
```bash
${baseDir}/scripts/find-session-files.sh {sessionId}
```

### Step 1.2: Verify Files Exist

Check all required files exist before proceeding. If debug log is missing, analysis will be limited.

---

## Phase 2: Parse Target SKILL.md

### Step 2.1: Extract Expected Components

Read the target SKILL.md and identify:

**From YAML Frontmatter:**
- `hooks.PreToolUse` - Expected PreToolUse hooks and matchers
- `hooks.PostToolUse` - Expected PostToolUse hooks
- `hooks.Stop` - Expected Stop hooks
- `hooks.SubagentStop` - Expected SubagentStop hooks
- `allowed-tools` - Tools the skill is allowed to use

**From Markdown Body:**
- SubAgents mentioned (`Task(subagent_type="...")`)
- Skills called (`Skill("...")`)
- Artifacts created (`.dev-flow/drafts/`, `.dev-flow/plans/`, etc.)
- Workflow steps and conditions

### Step 2.2: Build Expected Behavior Checklist

Create checklist from SKILL.md analysis:

```markdown
## Expected Behavior

### SubAgents
- [ ] Explore agent called (parallel, run_in_background)
- [ ] gap-analyzer called before plan generation
- [ ] reviewer called after plan creation

### Hooks
- [ ] PreToolUse[Edit|Write] triggers plan-guard.sh
- [ ] Stop hook validates reviewer approval

### Artifacts
- [ ] Draft file created at .dev-flow/drafts/{name}.md
- [ ] Plan file created at .dev-flow/plans/{name}.md
- [ ] Draft file deleted after OKAY

### Workflow
- [ ] Interview Mode before Plan Generation
- [ ] User explicit request triggers plan generation
- [ ] Reviewer REJECT causes revision loop
```

---

## Phase 3: Analyze Debug Log

The debug log (`~/.claude/debug/{sessionId}.txt`) contains detailed execution traces.

### Step 3.1: Extract SubAgent Calls

Search patterns:
```
SubagentStart with query: {agent-name}
SubagentStop with query: {agent-id}
```

Use script:
```bash
${baseDir}/scripts/extract-subagent-calls.sh {debug-log-path}
```

### Step 3.2: Extract Hook Events

Search patterns:
```
Getting matching hook commands for {HookEvent} with query: {tool-name}
Matched {N} unique hooks for query "{query}"
Hooks: Processing prompt hook with prompt: {prompt}
Hooks: Prompt hook condition was met/not met
permissionDecision: allow/deny
```

Use script:
```bash
${baseDir}/scripts/extract-hook-events.sh {debug-log-path}
```

### Step 3.3: Extract Tool Calls

Search patterns:
```
executePreToolHooks called for tool: {tool-name}
File {path} written atomically
```

### Step 3.4: Extract Hook Results

For prompt-based hooks, find the model response:
```
Hooks: Model response: {
  "ok": true/false,
  "reason": "..."
}
```

---

## Phase 4: Verify Artifacts

### Step 4.1: Check File Creation

For each expected artifact:
1. Search debug log for `FileHistory: Tracked file modification for {path}`
2. Search for `File {path} written atomically`
3. Verify current filesystem state

### Step 4.2: Check File Deletion

For files that should be deleted:
1. Search for `rm` commands in Bash calls
2. Verify file no longer exists on filesystem

---

## Phase 5: Compare Expected vs Actual

### Step 5.1: Build Comparison Table

```markdown
| Component | Expected | Actual | Status |
|-----------|----------|--------|--------|
| Explore agent | 2 parallel calls | 2 calls at 09:39:26 | ✅ |
| gap-analyzer | Called before plan | Called at 09:43:08 | ✅ |
| reviewer | Called after plan | 2 calls (REJECT→OKAY) | ✅ |
| PreToolUse hook | Edit\|Write matcher | Triggered for Write | ✅ |
| Stop hook | Validates approval | Returned ok:true | ✅ |
| Draft file | Created then deleted | Created→Deleted | ✅ |
| Plan file | Created | Exists (10KB) | ✅ |
```

### Step 5.2: Identify Deviations

Flag any mismatches:
- Missing component calls
- Wrong order of operations
- Hook failures
- Missing artifacts
- Unexpected errors

---

## Phase 6: Generate Report

### Report Template

```markdown
# Session Analysis Report

## Session Info
- **Session ID**: {sessionId}
- **Target Skill**: {skillPath}
- **Analysis Date**: {date}

---

## 1. Expected Behavior (from SKILL.md)

[Summary of expected workflow]

---

## 2. Skill/SubAgent/Hook Verification

### SubAgents
| SubAgent | Expected | Actual | Time | Result |
|----------|----------|--------|------|--------|
| ... | ... | ... | ... | ✅/❌ |

### Hooks
| Hook | Matcher | Triggered | Result |
|------|---------|-----------|--------|
| ... | ... | ... | ✅/❌ |

---

## 3. Artifacts Verification

| Artifact | Path | Expected State | Actual State |
|----------|------|----------------|--------------|
| ... | ... | ... | ✅/❌ |

---

## 4. Issues/Bugs

| Severity | Description | Location |
|----------|-------------|----------|
| ... | ... | ... |

---

## 5. Overall Result

**Verdict**: ✅ PASS / ❌ FAIL

**Summary**: [1-2 sentence summary]
```

---

## Scripts Reference

| Script | Purpose |
|--------|---------|
| `find-session-files.sh` | Locate all files for a session ID |
| `extract-subagent-calls.sh` | Parse subagent invocations from debug log |
| `extract-hook-events.sh` | Parse hook events from debug log |

---

## Usage Example

```
User: "Analyze session 3cc71c9f-d27a-4233-9dbc-c4f07ea6ec5b against .claude/skills/specify/SKILL.md"

1. Find session files
2. Parse SKILL.md → Expected: Explore, gap-analyzer, reviewer, hooks
3. Analyze debug log → Extract actual calls
4. Verify artifacts → Check .dev-flow/
5. Compare → Build verification table
6. Generate report → PASS/FAIL with details
```

---

## Additional Resources

### Reference Files
- **`references/analysis-patterns.md`** - Detailed grep patterns for log analysis
- **`references/common-issues.md`** - Known issues and troubleshooting

### Scripts
- **`scripts/find-session-files.sh`** - Session file locator
- **`scripts/extract-subagent-calls.sh`** - SubAgent call extractor
- **`scripts/extract-hook-events.sh`** - Hook event extractor


================================================
FILE: plugins/session-wrap/skills/session-analyzer/references/analysis-patterns.md
================================================
# Analysis Patterns for Session Analyzer

Detailed grep/search patterns for extracting information from Claude Code debug logs.

---

## Debug Log Structure

Debug logs are located at `~/.claude/debug/{sessionId}.txt` and contain timestamped entries:

```
2026-01-13T09:39:26.905Z [DEBUG] {message}
```

---

## SubAgent Patterns

### SubAgent Start
```bash
# Pattern
grep "SubagentStart with query:" debug.txt

# Example output
2026-01-13T09:39:26.905Z [DEBUG] Getting matching hook commands for SubagentStart with query: Explore
```

### SubAgent Stop
```bash
# Pattern
grep "SubagentStop with query:" debug.txt

# With agent ID (session tracking)
grep "agent_id.*agent_transcript_path" debug.txt
```

### SubAgent Session Registration
```bash
# Pattern - shows when hooks are registered for subagent
grep "Registered.*frontmatter hook.*from agent" debug.txt

# Example
2026-01-13T09:43:08.203Z [DEBUG] Registered 1 frontmatter hook(s) from agent 'gap-analyzer' for session a373157
```

---

## Hook Patterns

### PreToolUse Hook Trigger
```bash
# Pattern
grep "executePreToolHooks called for tool:" debug.txt

# Example
2026-01-13T09:39:40.000Z [DEBUG] executePreToolHooks called for tool: Write
```

### Hook Matcher Check
```bash
# Pattern
grep "Getting matching hook commands for PreToolUse with query:" debug.txt

# With match count
grep "Matched.*unique hooks for query" debug.txt

# Example
2026-01-13T09:39:40.000Z [DEBUG] Matched 1 unique hooks for query "Write" (1 before deduplication)
```

### Hook Permission Decision
```bash
# Pattern
grep "permissionDecision" debug.txt

# Example (allow)
"permissionDecision": "allow"

# Example (deny)
"permissionDecision": "deny"
```

### Prompt-Based Hook Processing
```bash
# Pattern - hook is being processed
grep "Hooks: Processing prompt hook with prompt:" debug.txt

# Pattern - model response
grep "Hooks: Model response:" debug.txt

# Pattern - condition result
grep "Prompt hook condition was" debug.txt

# Example (met)
2026-01-13T09:48:09.076Z [DEBUG] Hooks: Prompt hook condition was met

# Example (not met)
2026-01-13T09:45:59.297Z [DEBUG] Hooks: Prompt hook condition was not met: REJECT - ...
```

### Stop Hook Events
```bash
# Pattern
grep "Getting matching hook commands for Stop" debug.txt
```

### SubagentStop Hook Events
```bash
# Pattern - converted from Stop to SubagentStop
grep "Converting Stop hook to SubagentStop" debug.txt

# Example
2026-01-13T09:43:08.202Z [DEBUG] Converting Stop hook to SubagentStop for agent 'gap-analyzer'
```

---

## Tool Usage Patterns

### Tool Execution
```bash
# Pattern
grep "executePreToolHooks called for tool:" debug.txt
```

### File Write Operations
```bash
# Pattern - file creation/modification
grep "FileHistory: Tracked file modification for" debug.txt

# Pattern - atomic write
grep "File.*written atomically" debug.txt

# Example
2026-01-13T09:39:40.036Z [DEBUG] File /path/to/file.md written atomically
```

### Bash Command Execution
```bash
# Pattern - PreToolHooks for Bash
grep "executePreToolHooks called for tool: Bash" debug.txt
```

---

## Skill/Session Patterns

### Skill Loading
```bash
# Pattern - skill hooks registered
grep "Added session hook for event" debug.txt
grep "Registered.*hooks from skill" debug.txt

# Example
2026-01-13T09:39:14.449Z [DEBUG] Added session hook for event PreToolUse in session 3cc71c9f-...
2026-01-13T09:39:14.449Z [DEBUG] Registered 2 hooks from skill 'specify'
```

### Session Hook Cleanup
```bash
# Pattern
grep "Cleared all session hooks for session" debug.txt
```

---

## AskUserQuestion Patterns

```bash
# Pattern - PreToolHooks
grep "executePreToolHooks called for tool: AskUserQuestion" debug.txt

# Pattern - PostToolHooks
grep "PostToolUse with query: AskUserQuestion" debug.txt
```

---

## Error Patterns

### Hook Errors
```bash
# Pattern
grep -i "error\|failed\|exception" debug.txt | grep -i hook
```

### Tool Errors
```bash
# Pattern
grep "Tool.*error\|Tool.*failed" debug.txt
```

---

## Reviewer-Specific Patterns

### Reviewer Verdict Extraction
```bash
# Pattern - look for model response containing OKAY or REJECT
grep -A5 "Hooks: Model response:" debug.txt | grep -E '"ok":|"reason":'

# Example (OKAY)
{
  "ok": true,
  "reason": "Plan approved by reviewer..."
}

# Example (REJECT)
{
  "ok": false,
  "reason": "REJECT - The plan has a critical contradiction..."
}
```

---

## Artifact Patterns

### Draft File Operations
```bash
# Pattern - draft creation
grep "\.dev-flow/drafts/" debug.txt | grep "written atomically"

# Pattern - draft deletion (look for rm command)
grep "rm.*\.dev-flow/drafts/" debug.txt
```

### Plan File Operations
```bash
# Pattern - plan creation
grep "\.dev-flow/plans/" debug.txt | grep "written atomically"
```

---

## Timeline Reconstruction

To reconstruct a session timeline:

```bash
# Extract all timestamped events for key operations
grep -E "(SubagentStart|SubagentStop|executePreToolHooks|Prompt hook condition|written atomically)" debug.txt | sort
```

---

## Combined Analysis Query

Full analysis of a specify skill session:

```bash
# 1. Check Explore agents
grep "SubagentStart with query: Explore" debug.txt | wc -l

# 2. Check gap-analyzer
grep "SubagentStart with query: gap-analyzer" debug.txt

# 3. Check reviewer calls and results
grep -E "(SubagentStart with query: reviewer|Prompt hook condition)" debug.txt

# 4. Check plan-guard.sh hook
grep "permissionDecision" debug.txt

# 5. Check artifacts
grep -E "(\.dev-flow/drafts/|\.dev-flow/plans/).*written atomically" debug.txt

# 6. Final Stop hook result
grep -A10 "Getting matching hook commands for Stop" debug.txt | tail -20
```


================================================
FILE: plugins/session-wrap/skills/session-analyzer/references/common-issues.md
================================================
# Common Issues and Troubleshooting

Known issues when analyzing Claude Code sessions and how to diagnose them.

---

## Session File Issues

### Issue: Debug Log Not Found

**Symptom**: `~/.claude/debug/{sessionId}.txt` doesn't exist

**Possible Causes**:
1. Session was too old and debug logs were cleaned up
2. Debug logging was disabled
3. Session ID is incorrect

**Workaround**:
- Use the main session log (`.jsonl`) for limited analysis
- Main log contains tool calls but not detailed hook execution

### Issue: Large Debug Log (>50MB)

**Symptom**: Log file too large to read entirely

**Solution**:
- Use `grep` with specific patterns instead of reading entire file
- Use `tail` to get recent entries
- Use `offset` and `limit` when reading with Read tool

---

## SubAgent Analysis Issues

### Issue: SubAgent Not Recorded

**Symptom**: Expected subagent call not found in logs

**Possible Causes**:
1. SubAgent was never actually called
2. SubAgent type name differs from expected (case-sensitive)
3. Log was truncated

**Diagnosis**:
```bash
# List all unique subagent types
grep "SubagentStart with query:" debug.txt | sed 's/.*query: //' | sort | uniq
```

### Issue: Missing SubAgent Result

**Symptom**: `SubagentStart` found but no `SubagentStop`

**Possible Causes**:
1. SubAgent is still running (background task)
2. SubAgent crashed
3. Session ended before subagent completed

**Diagnosis**:
```bash
# Count starts vs stops
grep -c "SubagentStart" debug.txt
grep -c "SubagentStop" debug.txt
```

---

## Hook Analysis Issues

### Issue: Hook Not Triggered

**Symptom**: Expected hook not found in `Getting matching hook commands` entries

**Possible Causes**:
1. Matcher pattern doesn't match the tool name
2. Hook not registered (skill not loaded)
3. Hook has wrong event type

**Diagnosis**:
```bash
# Check if skill hooks were registered
grep "Registered.*hooks from skill" debug.txt

# Check what hooks are being queried
grep "Getting matching hook commands for" debug.txt | head -20
```

### Issue: Hook Triggered But No Effect

**Symptom**: Hook matched (count > 0) but expected behavior didn't occur

**Possible Causes**:
1. Hook script returned error
2. Hook returned `allow` when should have returned `deny`
3. Prompt hook condition was not met

**Diagnosis**:
```bash
# Check hook execution result
grep -A5 "Matched.*unique hooks" debug.txt | grep -E "permissionDecision|ok"
```

### Issue: Prompt Hook Always Returns False

**Symptom**: `Prompt hook condition was not met` consistently

**Possible Causes**:
1. Prompt is too vague for model to understand
2. Context doesn't contain expected information
3. Model misinterprets the criteria

**Diagnosis**:
```bash
# See the full model response
grep -A20 "Hooks: Model response:" debug.txt
```

---

## Artifact Issues

### Issue: File Not Created

**Symptom**: Expected artifact file not in `written atomically` logs

**Possible Causes**:
1. Write was blocked by PreToolUse hook
2. Path was wrong
3. Write tool was never called

**Diagnosis**:
```bash
# Check if Write was attempted
grep "executePreToolHooks called for tool: Write" debug.txt

# Check permission decision
grep -A10 "executePreToolHooks called for tool: Write" debug.txt | grep "permissionDecision"
```

### Issue: File Exists But Should Be Deleted

**Symptom**: Draft file still exists after session ended

**Possible Causes**:
1. Bash `rm` command was never executed
2. Skill ended before cleanup step
3. Wrong file path in rm command

**Diagnosis**:
```bash
# Check for rm commands
grep "Bash" debug.txt | grep -i "rm"
```

---

## Reviewer-Specific Issues

### Issue: Reviewer Never Returns OKAY

**Symptom**: Multiple REJECT responses, no OKAY

**Possible Causes**:
1. Plan genuinely has issues that weren't fixed
2. Reviewer criteria too strict
3. Plan edits not addressing reviewer feedback

**Diagnosis**:
```bash
# Extract all reviewer responses
grep -B2 -A10 "Hooks: Model response:" debug.txt | grep -E '"ok"|"reason"'
```

### Issue: Reviewer Called But No Hook Result

**Symptom**: `SubagentStart with query: reviewer` found but no `Prompt hook condition` result

**Possible Causes**:
1. Reviewer subagent has no Stop hook configured
2. Hook conversion to SubagentStop failed
3. Reviewer is still running

**Diagnosis**:
```bash
# Check if Stop hook was converted
grep "Converting Stop hook to SubagentStop for agent 'reviewer'" debug.txt
```

---

## Timing Issues

### Issue: Events Out of Order

**Symptom**: Timeline doesn't make sense (e.g., Stop before Start)

**Possible Causes**:
1. Parallel operations (intended behavior)
2. Log entries from different sessions mixed
3. Clock synchronization issues

**Solution**:
- Filter by session ID if multiple sessions in same timeframe
- Look at specific operation sequences, not global order

### Issue: Large Time Gaps

**Symptom**: Long pauses between operations

**Possible Causes**:
1. User interaction (AskUserQuestion waiting)
2. API rate limiting
3. Model thinking time

**Diagnosis**:
```bash
# Find gaps > 30 seconds
awk -F'T|Z' '{print $2}' debug.txt | sort | uniq -c | sort -rn | head
```

---

## Analysis Script Issues

### Issue: Script Returns Empty JSON

**Symptom**: Scripts return `{ "summary": { "total": 0 } }`

**Possible Causes**:
1. Debug log path is wrong
2. Log format changed
3. No matching events in this session

**Solution**:
- Verify debug log path exists and has content
- Manually grep for expected patterns to verify format

### Issue: Script Permission Denied

**Symptom**: `Permission denied` when running scripts

**Solution**:
```bash
chmod +x scripts/*.sh
```

---

## Validation Checklist

When analysis seems wrong, verify:

1. **Correct Session ID**: Double-check the UUID
2. **Files Exist**: Run `find-session-files.sh` first
3. **Skill Was Loaded**: Look for "Registered.*hooks from skill"
4. **Right Timeframe**: Check timestamps match expected session time
5. **Complete Session**: Session ended normally (not interrupted)


================================================
FILE: plugins/session-wrap/skills/session-analyzer/scripts/extract-hook-events.sh
================================================
#!/bin/bash
# extract-hook-events.sh - Extract Hook events from debug log
#
# Usage: extract-hook-events.sh <debug-log-path>
# Output: JSON with hook events, triggers, and results

set -euo pipefail

DEBUG_LOG="${1:-}"

if [[ -z "$DEBUG_LOG" ]] || [[ ! -f "$DEBUG_LOG" ]]; then
    echo "Usage: $0 <debug-log-path>" >&2
    exit 1
fi

echo "{"

# Extract PreToolUse hooks
echo '  "pre_tool_use": ['
first=true
while IFS= read -r line; do
    timestamp=$(echo "$line" | grep -oE '^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]+Z' || echo "")
    tool_name=$(echo "$line" | grep -oP 'PreToolUse with query: \K\S+' || echo "")

    if [[ -n "$tool_name" ]]; then
        if [[ "$first" != "true" ]]; then
            echo ","
        fi
        first=false
        printf '    {"timestamp": "%s", "tool": "%s"}' "$timestamp" "$tool_name"
    fi
done < <(grep "Getting matching hook commands for PreToolUse" "$DEBUG_LOG" 2>/dev/null || true)
echo ""
echo "  ],"

# Extract hook matches
echo '  "hook_matches": ['
first=true
while IFS= read -r line; do
    timestamp=$(echo "$line" | grep -oE '^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]+Z' || echo "")
    match_count=$(echo "$line" | grep -oP 'Matched \K\d+' || echo "0")
    query=$(echo "$line" | grep -oP 'for query "\K[^"]+' || echo "")

    if [[ "$match_count" -gt 0 ]]; then
        if [[ "$first" != "true" ]]; then
            echo ","
        fi
        first=false
        printf '    {"timestamp": "%s", "query": "%s", "matched": %s}' "$timestamp" "$query" "$match_count"
    fi
done < <(grep "Matched .* unique hooks for query" "$DEBUG_LOG" 2>/dev/null || true)
echo ""
echo "  ],"

# Extract prompt hook results
echo '  "prompt_hook_results": ['
first=true
while IFS= read -r line; do
    timestamp=$(echo "$line" | grep -oE '^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]+Z' || echo "")

    if echo "$line" | grep -q "Prompt hook condition was met"; then
        if [[ "$first" != "true" ]]; then
            echo ","
        fi
        first=false
        printf '    {"timestamp": "%s", "result": "met"}' "$timestamp"
    elif echo "$line" | grep -q "Prompt hook condition was not met"; then
        if [[ "$first" != "true" ]]; then
            echo ","
        fi
        first=false
        printf '    {"timestamp": "%s", "result": "not_met"}' "$timestamp"
    fi
done < <(grep "Prompt hook condition" "$DEBUG_LOG" 2>/dev/null || true)
echo ""
echo "  ],"

# Extract permission decisions
echo '  "permission_decisions": ['
first=true
while IFS= read -r line; do
    timestamp=$(echo "$line" | grep -oE '^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]+Z' || echo "")
    decision=$(echo "$line" | grep -oP 'permissionDecision.*:\s*"\K[^"]+' || echo "")

    if [[ -n "$decision" ]]; then
        if [[ "$first" != "true" ]]; then
            echo ","
        fi
        first=false
        printf '    {"timestamp": "%s", "decision": "%s"}' "$timestamp" "$decision"
    fi
done < <(grep "permissionDecision" "$DEBUG_LOG" 2>/dev/null || true)
echo ""
echo "  ],"

# Summary
stop_hooks=$(grep -c "Getting matching hook commands for Stop" "$DEBUG_LOG" 2>/dev/null || echo "0")
pre_tool_hooks=$(grep -c "Getting matching hook commands for PreToolUse" "$DEBUG_LOG" 2>/dev/null || echo "0")
post_tool_hooks=$(grep -c "Getting matching hook commands for PostToolUse" "$DEBUG_LOG" 2>/dev/null || echo "0")
subagent_stop=$(grep -c "Getting matching hook commands for SubagentStop" "$DEBUG_LOG" 2>/dev/null || echo "0")
prompt_hooks=$(grep -c "Processing prompt hook" "$DEBUG_LOG" 2>/dev/null || echo "0")

cat << EOF
  "summary": {
    "PreToolUse": $pre_tool_hooks,
    "PostToolUse": $post_tool_hooks,
    "Stop": $stop_hooks,
    "SubagentStop": $subagent_stop,
    "prompt_hooks_processed": $prompt_hooks
  }
}
EOF


================================================
FILE: plugins/session-wrap/skills/session-analyzer/scripts/extract-subagent-calls.sh
================================================
#!/bin/bash
# extract-subagent-calls.sh - Extract SubAgent invocations from debug log
#
# Usage: extract-subagent-calls.sh <debug-log-path>
# Output: JSON array of subagent calls with timestamps and results

set -euo pipefail

DEBUG_LOG="${1:-}"

if [[ -z "$DEBUG_LOG" ]] || [[ ! -f "$DEBUG_LOG" ]]; then
    echo "Usage: $0 <debug-log-path>" >&2
    exit 1
fi

echo "{"
echo '  "subagent_calls": ['

# Extract SubagentStart events
first=true
while IFS= read -r line; do
    timestamp=$(echo "$line" | grep -oE '^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]+Z' || echo "")
    agent_name=$(echo "$line" | grep -oP 'SubagentStart with query: \K\S+' || echo "")

    if [[ -n "$agent_name" ]]; then
        if [[ "$first" != "true" ]]; then
            echo ","
        fi
        first=false
        printf '    {"timestamp": "%s", "event": "start", "agent": "%s"}' "$timestamp" "$agent_name"
    fi
done < <(grep "SubagentStart with query:" "$DEBUG_LOG" 2>/dev/null || true)

echo ""
echo "  ],"

# Extract SubagentStop events with results
echo '  "subagent_results": ['

first=true
while IFS= read -r line; do
    timestamp=$(echo "$line" | grep -oE '^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]+Z' || echo "")

    if [[ -n "$timestamp" ]]; then
        # Look for hook result after this line
        if [[ "$first" != "true" ]]; then
            echo ","
        fi
        first=false
        printf '    {"timestamp": "%s", "event": "stop"}' "$timestamp"
    fi
done < <(grep "SubagentStop with query:" "$DEBUG_LOG" 2>/dev/null || true)

echo ""
echo "  ],"

# Summary counts
explore_count=$(grep -c "SubagentStart with query: Explore" "$DEBUG_LOG" 2>/dev/null || echo "0")
gap_analyzer_count=$(grep -c "SubagentStart with query: gap-analyzer" "$DEBUG_LOG" 2>/dev/null || echo "0")
reviewer_count=$(grep -c "SubagentStart with query: reviewer" "$DEBUG_LOG" 2>/dev/null || echo "0")
worker_count=$(grep -c "SubagentStart with query: worker" "$DEBUG_LOG" 2>/dev/null || echo "0")

cat << EOF
  "summary": {
    "Explore": $explore_count,
    "gap-analyzer": $gap_analyzer_count,
    "reviewer": $reviewer_count,
    "worker": $worker_count,
    "total": $((explore_count + gap_analyzer_count + reviewer_count + worker_count))
  }
}
EOF


================================================
FILE: plugins/session-wrap/skills/session-analyzer/scripts/find-session-files.sh
================================================
#!/bin/bash
# find-session-files.sh - Locate all files related to a Claude Code session
#
# Usage: find-session-files.sh <session-id>
# Output: JSON with paths to session files

set -euo pipefail

SESSION_ID="${1:-}"

if [[ -z "$SESSION_ID" ]]; then
    echo "Usage: $0 <session-id>" >&2
    exit 1
fi

CLAUDE_DIR="$HOME/.claude"

# Find main session log (in projects directory)
MAIN_LOG=$(find "$CLAUDE_DIR/projects" -name "${SESSION_ID}.jsonl" 2>/dev/null | head -1)

# Find debug log
DEBUG_LOG="$CLAUDE_DIR/debug/${SESSION_ID}.txt"
if [[ ! -f "$DEBUG_LOG" ]]; then
    DEBUG_LOG=""
fi

# Find agent transcripts (subagent sessions)
AGENT_LOGS=$(find "$CLAUDE_DIR/projects" -name "agent-*.jsonl" 2>/dev/null | xargs grep -l "$SESSION_ID" 2>/dev/null || true)

# Find todo file
TODO_FILE=$(find "$CLAUDE_DIR/todos" -name "*${SESSION_ID}*.json" 2>/dev/null | head -1)

# Find session environment
SESSION_ENV="$CLAUDE_DIR/session-env/${SESSION_ID}"
if [[ ! -d "$SESSION_ENV" ]]; then
    SESSION_ENV=""
fi

# Output as JSON
cat << EOF
{
  "session_id": "$SESSION_ID",
  "main_log": "$MAIN_LOG",
  "debug_log": "$DEBUG_LOG",
  "agent_logs": [$(echo "$AGENT_LOGS" | sed 's/^/"/' | sed 's/$/"/' | tr '\n' ',' | sed 's/,$//' | sed 's/^""$//')],
  "todo_file": "$TODO_FILE",
  "session_env": "$SESSION_ENV",
  "found": {
    "main_log": $([ -n "$MAIN_LOG" ] && echo "true" || echo "false"),
    "debug_log": $([ -n "$DEBUG_LOG" ] && echo "true" || echo "false")
  }
}
EOF


================================================
FILE: plugins/session-wrap/skills/session-wrap/SKILL.md
================================================
---
name: session-wrap
description: This skill should be used when the user asks to "wrap up session", "end session", "session wrap", "/wrap", "document learnings", "what should I commit", or wants to analyze completed work before ending a coding session.
version: 2.0.0
---

# Session Wrap Skill

Comprehensive session wrap-up workflow with multi-agent analysis.

## Execution Flow

```
┌─────────────────────────────────────────────────────┐
│  1. Check Git Status                                │
├─────────────────────────────────────────────────────┤
│  2. Phase 1: 4 Analysis Agents (Parallel)           │
│     ┌─────────────────┬─────────────────┐           │
│     │  doc-updater    │  automation-    │           │
│     │  (docs update)  │  scout          │           │
│     ├─────────────────┼─────────────────┤           │
│     │  learning-      │  followup-      │           │
│     │  extractor      │  suggester      │           │
│     └─────────────────┴─────────────────┘           │
├─────────────────────────────────────────────────────┤
│  3. Phase 2: Validation Agent (Sequential)          │
│     ┌───────────────────────────────────┐           │
│     │       duplicate-checker           │           │
│     │  (Validate Phase 1 proposals)     │           │
│     └───────────────────────────────────┘           │
├─────────────────────────────────────────────────────┤
│  4. Integrate Results & AskUserQuestion             │
├─────────────────────────────────────────────────────┤
│  5. Execute Selected Actions                        │
└─────────────────────────────────────────────────────┘
```

## Step 1: Check Git Status

```bash
git status --short
git diff --stat HEAD~3 2>/dev/null || git diff --stat
```

## Step 2: Phase 1 - Analysis Agents (Parallel)

Execute 4 agents in parallel (single message with 4 Task calls).

### Session Summary (Provide to all agents)

```
Session Summary:
- Work: [Main tasks performed in session]
- Files: [Created/modified files]
- Decisions: [Key decisions made]
```

### Parallel Execution

```
Task(
    subagent_type="doc-updater",
    description="Document update analysis",
    prompt="[Session Summary]\n\nAnalyze if CLAUDE.md, context.md need updates."
)

Task(
    subagent_type="automation-scout",
    description="Automation pattern analysis",
    prompt="[Session Summary]\n\nAnalyze repetitive patterns or automation opportunities."
)

Task(
    subagent_type="learning-extractor",
    description="Learning points extraction",
    prompt="[Session Summary]\n\nExtract learnings, mistakes, and new discoveries."
)

Task(
    subagent_type="followup-suggester",
    description="Follow-up task suggestions",
    prompt="[Session Summary]\n\nSuggest incomplete tasks and next session priorities."
)
```

### Agent Roles

| Agent | Role | Output |
|-------|------|--------|
| **doc-updater** | Analyze CLAUDE.md/context.md updates | Specific content to add |
| **automation-scout** | Detect automation patterns | skill/command/agent suggestions |
| **learning-extractor** | Extract learning points | TIL format summary |
| **followup-suggester** | Suggest follow-up tasks | Prioritized task list |

## Step 3: Phase 2 - Validation Agent (Sequential)

Run after Phase 1 completes (dependency on Phase 1 results).

```
Task(
    subagent_type="duplicate-checker",
    description="Phase 1 proposal validation",
    prompt="""
Validate Phase 1 analysis results.

## doc-updater proposals:
[doc-updater results]

## automation-scout proposals:
[automation-scout results]

Check if proposals duplicate existing docs/automation:
1. Complete duplicate: Recommend skip
2. Partial duplicate: Suggest merge approach
3. No duplicate: Approve for addition
"""
)
```

## Step 4: Integrate Results

```markdown
## Wrap Analysis Results

### Documentation Updates
[doc-updater summary]
- Duplicate check: [duplicate-checker feedback]

### Automation Suggestions
[automation-scout summary]
- Duplicate check: [duplicate-checker feedback]

### Learning Points
[learning-extractor summary]

### Follow-up Tasks
[followup-suggester summary]
```

## Step 5: Action Selection

```
AskUserQuestion(
    questions=[{
        "question": "Which actions would you like to perform?",
        "header": "Wrap Options",
        "multiSelect": true,
        "options": [
            {"label": "Create commit (Recommended)", "description": "Commit changes"},
            {"label": "Update CLAUDE.md", "description": "Document new knowledge/workflows"},
            {"label": "Create automation", "description": "Generate skill/command/agent"},
            {"label": "Skip", "description": "End without action"}
        ]
    }]
)
```

## Step 6: Execute Selected Actions

Execute only the actions selected by user.

---

## Quick Reference

### When to Use

- End of significant work session
- Before switching to different project
- After completing a feature or fixing a bug

### When to Skip

- Very short session with trivial changes
- Only reading/exploring code
- Quick one-off question answered

### Arguments

- Empty: Proceed interactively (full workflow)
- Message provided: Use as commit message and commit directly

## Additional Resources

See `references/multi-agent-patterns.md` for detailed orchestration patterns.


================================================
FILE: plugins/session-wrap/skills/session-wrap/references/multi-agent-patterns.md
================================================
# Multi-Agent Orchestration Patterns

Detailed patterns for designing multi-agent workflows in Claude Code.

## Core Principles

> **"Agent architecture should reflect the dependency graph of the task"**
> — Anthropic Multi-Agent Research

If subtasks don't read or modify each other's state, run them **parallel**.
If previous output is next input, run them **sequential**.

## Parallel vs Sequential Decision Criteria

| Condition | Recommended Pattern |
|-----------|-------------------|
| Subtasks are independent (no shared state) | **Parallel** |
| Previous step output is next step input | **Sequential** |
| Diverse perspectives/expertise needed | **Parallel** (Fan-out) |
| Result coherence/consistency important | **Sequential** |
| Proposals need validation before action | **2-Phase** (Generate→Validate) |

## Anthropic's 6 Composable Patterns

| Pattern | Description | When to Use |
|---------|-------------|-------------|
| **Prompt Chaining** | Sequential steps, each output is next input | Data transformation pipelines |
| **Routing** | Branch to specialized agents by input type | Multi-domain processing |
| **Parallelization** | Independent tasks run simultaneously | Multi-angle analysis, speed optimization |
| **Orchestrator-Worker** | Dynamic task assignment | Complex coding/research |
| **Evaluator-Optimizer** | Generate→Evaluate iteration loop | Quality improvement needed |
| **Autonomous Agent** | Minimal intervention, environment feedback | Long-running tasks |

## 2-Phase Pipeline Pattern

For workflows generating proposals that need validation:

```
Phase 1: Analysis/Generation (Parallel)
┌──────────┬──────────┬──────────┐
│ Agent A  │ Agent B  │ Agent C  │  ← Independent analysis
└────┬─────┴────┬─────┴────┬─────┘
     │          │          │
     └──────────┼──────────┘
                ↓
Phase 2: Validation (Sequential)
┌─────────────────────────────────┐
│         Validator Agent         │  ← Validate Phase 1 results
└─────────────────────────────────┘
```

### Application Examples

**Session wrap workflow:**
- Phase 1: doc-updater, automation-scout, learning-extractor, followup-suggester (parallel)
- Phase 2: duplicate-checker (sequential)

**Code review workflow:**
- Phase 1: security-reviewer, style-checker, performance-analyzer (parallel)
- Phase 2: final-reviewer (sequential)

**Research workflow:**
- Phase 1: source-finder, fact-checker, perspective-gatherer (parallel)
- Phase 2: synthesizer (sequential)

## State Management Principles

```
❌ Avoid:
- Mutable state shared between concurrent agents
- Assuming synchronous updates across agent boundaries
- Assuming independence without explicit verification

✅ Recommend:
- Isolate agents as much as possible
- Pass state explicitly via output_key
- Define conflict resolution strategy for result aggregation
- Pass lightweight references (not full data)
```

## Anti-Patterns

| Anti-Pattern | Problem | Alternative |
|--------------|---------|-------------|
| Adding meaningless agents | Only increases complexity | Check if single agent sufficient first |
| Excessive multi-hop communication | Latency increase | Direct communication or parallelization |
| Unclear task boundaries | Duplicate work, gaps | Define clear objective, output format, boundaries |
| Rigid plan adherence | Can't adapt to runtime discoveries | Use adaptive orchestrator |

## Model Selection for Agents

| Use Case | Recommended Model |
|----------|------------------|
| Analysis requiring depth | `sonnet` or `opus` |
| Quick validation | `haiku` |
| Default/inherit from parent | `inherit` |
| Creative/complex reasoning | `opus` |
| Cost-sensitive batch operations | `haiku` |

## Implementing in Claude Code

### Parallel Execution

Send multiple Task calls in a single message:

```python
# All 4 agents start simultaneously
Task(subagent_type="agent-a", prompt="...")
Task(subagent_type="agent-b", prompt="...")
Task(subagent_type="agent-c", prompt="...")
Task(subagent_type="agent-d", prompt="...")
```

### Sequential Execution

Wait for previous result before next call:

```python
# First call
result_1 = Task(subagent_type="agent-a", prompt="...")

# Use result_1 in next call
Task(subagent_type="agent-b", prompt=f"Validate: {result_1}")
```

### Hybrid (2-Phase)

```python
# Phase 1: Parallel
Task(subagent_type="analyzer-1", prompt="...")
Task(subagent_type="analyzer-2", prompt="...")
Task(subagent_type="analyzer-3", prompt="...")

# Wait for all Phase 1 results

# Phase 2: Sequential (uses Phase 1 results)
Task(
    subagent_type="validator",
    prompt=f"""
    Validate these proposals:

    Analyzer 1: {result_1}
    Analyzer 2: {result_2}
    Analyzer 3: {result_3}
    """
)
```

## Agent Design for Multi-Agent Systems

### Clear Boundaries

Each agent should have:
- **Single responsibility**: One clear focus area
- **Defined inputs**: What it expects to receive
- **Structured output**: Consistent format for downstream consumption
- **No side effects**: Don't modify state other agents depend on

### Communication Protocol

```markdown
## Agent Output Format

### Summary
[One-line summary]

### Detailed Findings
[Structured analysis]

### Recommendations
[Actionable items with priorities]

### Confidence
[Self-assessment of analysis quality]
```

## Scaling Considerations

### When to Add More Agents

✅ Add agent when:
- Distinct expertise domain needed
- Independent analysis possible
- Clear boundary definable
- Reduces complexity vs. single agent

❌ Don't add agent when:
- Same expertise as existing agent
- Would create tight coupling
- Simple prompt modification sufficient
- Adds latency without value

### Performance Optimization

1. **Minimize Phase 2 agents**: Validation should be lightweight
2. **Right-size Phase 1**: 3-5 parallel agents typically optimal
3. **Use haiku for validation**: Fast, cheap, sufficient for checking
4. **Batch where possible**: Combine related analyses in single agent

## References

- [Anthropic Multi-Agent Research](https://www.anthropic.com/engineering/multi-agent-research-system)
- [Azure AI Agent Design Patterns](https://learn.microsoft.com/en-us/azure/architecture/ai-ml/guide/ai-agent-design-patterns)
- [Building AI Agents - Evaluator-Optimizer Pattern](https://research.aimultiple.com/building-ai-agents/)


================================================
FILE: plugins/team-assemble/.claude-plugin/plugin.json
================================================
{
  "name": "team-assemble",
  "version": "1.0.0",
  "description": "Dynamically assemble expert agent teams for complex tasks using Claude Code's agent teams feature",
  "author": {
    "name": "Team Attention",
    "url": "https://github.com/team-attention"
  },
  "repository": "https://github.com/team-attention/plugins-for-claude-natives",
  "license": "MIT",
  "keywords": ["agent-teams", "multi-agent", "team", "parallel", "orchestration", "task-decomposition"]
}


================================================
FILE: plugins/team-assemble/README.md
================================================
# team-assemble

Dynamically assemble expert agent teams for complex tasks using Claude Code's agent teams feature.

## What It Does

Instead of manually designing and coordinating multiple agents, team-assemble:

1. **Analyzes** your task and identifies relevant codebase areas
2. **Scouts** the codebase to understand what agents are needed
3. **Designs** an optimal team with the right roles and dependencies
4. **Executes** agents in parallel where possible
5. **Validates** results against acceptance criteria
6. **Cleans up** the team automatically

## Prerequisites

Agent teams are experimental and must be enabled first. Add to your `settings.json`:

```json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}
```

See `skills/team-assemble/references/enable-agent-teams.md` for detailed setup instructions.

## Usage

Tell Claude what you need and ask it to assemble a team:

```
Assemble a team to refactor our authentication from session-based to JWT
```

```
Use team-assemble to evaluate caching strategies — Redis vs Memcached vs in-memory
```

```
Assemble a team to extract shared utilities from three microservices into a common library
```

The skill will guide you through approval gates before execution begins.

## How It Works

### 6-Phase Workflow

```
Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 5 → Phase 6
Task       Codebase   Integrate  Execute   Validate   Complete
Analysis   Scouts     & Confirm                       & Cleanup
```

### Model 3-Tier Strategy

Agents are assigned models based on their role:

| Model | Purpose | Examples |
|-------|---------|---------|
| opus | Strategy & judgment | Scouts, architects |
| sonnet | Standard execution | Implementers, QA, support |
| haiku | Research & writing | Researchers, editors |

### Key Features

- **Dynamic agent design** — no fixed catalog, agents are tailored to each task
- **Parallel execution** — independent agents run simultaneously
- **Acceptance criteria** — every team has measurable validation criteria
- **Verify/fix loop** — QA validates, support fixes (max 3 rounds)
- **Two approval gates** — user confirms scope (Phase 1) and team composition (Phase 3)

## Plugin Contents

```
team-assemble/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── team-assemble/
│       ├── SKILL.md                        # Main skill definition
│       └── references/
│           ├── agents.md                   # Agent example bank
│           ├── prompt-templates.md         # Prompt templates for all phases
│           ├── examples.md                 # Worked examples
│           └── enable-agent-teams.md       # Setup guide
└── README.md
```


================================================
FILE: plugins/team-assemble/skills/team-assemble/SKILL.md
================================================
---
name: team-assemble
description: Analyze tasks and dynamically assemble expert agent teams using Claude Code's TeamCreate API. Scouts your codebase, designs optimal agents, and executes with validation.
allowed-tools: [Agent, Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion, TaskCreate, TaskUpdate, TaskList, TaskGet, TeamCreate, TeamDelete, SendMessage]
version: 1.0.0
---

# Team Assemble

Analyze a task, dynamically design the right expert agents, and orchestrate them as a team using Claude Code's agent teams feature.

## Prerequisites

Agent teams must be enabled. See `references/enable-agent-teams.md` for setup instructions.

## When to Use

- Complex tasks that decompose into 2+ independent subtasks
- Work where role separation is clear (e.g., research + implementation + validation)
- Tasks that benefit from parallel execution

**Do NOT use for:** single-file edits, simple questions, purely sequential work

---

## Core Principles

- **Model 3-tier** — choose by role purpose (details: `references/agents.md`)
  - `opus` — strategy/judgment (scouts, complex execution)
  - `sonnet` — standard execution/validation (worker, qa, support)
  - `haiku` — exploration/writing (researcher, editor)
- **No fixed catalog** — agents are designed dynamically per task
- **Example bank** — `references/agents.md` provides reference examples (not mandatory)

---

## Workflow

```
Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 5 → Phase 6
Task       Codebase   Integrate  Execute   Validate   Complete
Analysis   Scouts     & Confirm                       & Cleanup
                                           ↕ FAIL → support fix (max 3x)
```

---

## Phase 1: Task Analysis

Analyze the user's request and identify relevant areas of the codebase:

1. Examine project structure, CLAUDE.md files, and README files
2. Identify which parts of the codebase are relevant to the task
3. Determine if codebase scouting (Phase 2) would help, or if the task is straightforward enough to skip to Phase 3

**Get user approval via AskUserQuestion:**

```
I've analyzed your task and identified the following areas of interest:

- [x] src/auth/ — Authentication module (needs refactoring)
- [x] tests/auth/ — Corresponding tests
- [ ] src/api/ — Not directly affected

I'll scout these areas to design an optimal team.
```

Options: "Looks good, proceed" / "I'd like to adjust the scope"

For straightforward tasks that don't need codebase exploration, skip Phase 2 and go directly to Phase 3 — design the team yourself using `references/agents.md` as a guide.

---

## Phase 2: Codebase Scouts (Parallel)

Launch **scout agents** in parallel to explore relevant areas of the codebase.

### Scout Configuration

- **Model**: opus
- **subagent_type**: `general-purpose` (constrained to read-only via prompt)
- **Parallel**: launch multiple scouts simultaneously when exploring different areas

### Scout Mission

Each scout reads the relevant codebase area and proposes agents for the task:

1. Read key files (CLAUDE.md, README.md, source code, configs)
2. Analyze the intersection between the task and the codebase area
3. Propose agents needed (name, role, tasks, reference files)
4. Reference `references/agents.md` for examples, but freely design new agents

> Prompt template: `references/prompt-templates.md` § Codebase Scout

### Scout Output Format

```
## Scout Report: {area}

### Current State
- {file structure summary}
- {relevance to the task}

### Proposed Agents
| Agent | Role | Tasks | Reference Files |
|-------|------|-------|-----------------|
| {name} | {role} | {task} | {files} |

### Notes
- {area-specific constraints or patterns to follow}
```

---

## Phase 3: Integrate & Confirm Team

Merge scout reports into a final team composition:

1. **Deduplicate** — merge similar agent proposals from different scouts
2. **Gap analysis** — check for missing roles
3. **Add qa + support** — validation/fix agents are always included
4. **Dependency graph** — design execution order between agents
5. **Define acceptance criteria** — measurable criteria for Phase 5 validation

### Team Proposal

**Get final approval via AskUserQuestion:**

```
Proposed team: {team-name}

| # | Agent | Role | Tasks | Dependencies |
|---|-------|------|-------|--------------|
| 1 | architect | System design | Design new auth flow | - |
| 2 | implementer | Code changes | Implement the design | #1 |
| 3 | test-writer | Test coverage | Write tests for changes | #2 |
| 4 | qa | Validation | PASS/FAIL against acceptance criteria | #2, #3 |

Acceptance criteria:
- [ ] AC-1: {measurable criterion}
- [ ] AC-2: {measurable criterion}
```

Options: "Looks good, execute" / "I'd like to adjust roles"

If the user selects "adjust roles", ask what specifically to change. After 2+ revision requests, switch to free-text input.

---

## Phase 4: Execution

### Create Team & Distribute Tasks

```
TeamCreate(team_name: "{keyword}-team", description: "Task description")
```

team_name convention: core keyword + `-team`

Create TaskCreate entries for each agent, then set dependencies with TaskUpdate.

### Launch Teammates

- **Model**: apply 3-tier based on role (`references/agents.md`)
- **subagent_type**: `"general-purpose"`
- **mode**: `"bypassPermissions"`
- **Parallel**: launch agents without blockedBy dependencies in a single message
- **Sequential**: inject preceding agent results into the next agent's prompt

### Teammate Prompt Requirements

1. **Context** — project background and how this task fits the whole
2. **Specific goal** — exactly what to achieve
3. **Reference files** — file paths identified by scouts
4. **Constraints** — what NOT to do, scope limits
5. **Output format** — expected deliverable format
6. **Team info** — team_name, task ID

> Detailed prompt structure: `references/prompt-templates.md`

---

## Phase 5: Validation

qa (sonnet) evaluates each **acceptance criterion** from Phase 3.

### Validation Process

```
Agent(name: "qa", model: "sonnet", prompt: """
## Acceptance Criteria
- [ ] AC-1: {criterion}

## Validation Target
{Phase 4 execution results}

Evaluate each criterion with evidence-based PASS/FAIL judgment.
No PASS without evidence.

## Output Format
| # | Criterion | Verdict | Evidence |
Overall: PASS / FAIL
Include fix suggestions for any FAIL items.
""")
```

### FAIL Handling

support (sonnet) fixes only FAIL items → qa re-validates:

- **Max 3 rounds** of verify/fix loop
- If the same error repeats 3 times, stop immediately
- After 3 rounds, halt the pipeline and report to user:

```
## Validation Failed — Manual Intervention Needed

### Repeated Failures
- AC-{N}: {criterion} — {failure reason}

### Attempted Fixes
1. {attempt 1}  2. {attempt 2}  3. {attempt 3}

### Recommended Action
{what needs to be done manually}
```

---

## Phase 6: Complete & Cleanup

### Result Report

```
## Team Results: {team-name}

### Acceptance Criteria
- [x] AC-1: {criterion} — PASS

### Per-Agent Results
- {agent}: {result summary}

### Deliverables
- {file paths or outputs}

### Validation History
- Validated {N} times, {M} fixes applied
```

### Team Cleanup

```
SendMessage(type: "shutdown_request", recipient: "{name}", content: "Work complete")
TeamDelete()
```

---

## Common Mistakes

| Mistake | Correct Approach |
|---------|------------------|
| Creating team without user approval | Get AskUserQuestion approval in Phase 1 + Phase 3 |
| Executing without acceptance criteria | Always define criteria in Phase 3 |
| Running scouts for simple tasks | Skip Phase 2 for straightforward work |
| Skipping validation | Always run Phase 5 after execution |
| Ignoring model tiers | Use opus/sonnet/haiku based on role purpose |
| Only picking from fixed catalog | Scouts design freely; examples are reference only |
| Forgetting TeamDelete | Always shutdown_request → TeamDelete |
| Infinite FAIL loop | Max 3 verify/fix rounds, then report to user |

## Additional Resources

- **`references/agents.md`** — Agent example bank with model tier guide
- **`references/prompt-templates.md`** — Scout + execution + QA prompt templates
- **`references/examples.md`** — Worked examples: feature dev, refactoring, research
- **`references/enable-agent-teams.md`** — How to enable agent teams in Claude Code


================================================
FILE: plugins/team-assemble/skills/team-assemble/references/agents.md
================================================
# Agent Example Bank

Reference examples for designing agents. Scouts use these as inspiration, not as a fixed catalog.

> This is an **example bank**, not a mandatory catalog. Scouts should reference these but can design entirely new agents optimized for each task. Names, roles, and tasks should all be tailored to the work at hand.

## General Policy

- **subagent_type**: `general-purpose`
- **mode**: `bypassPermissions`

### Model 3-Tier

Choose based on role purpose:

| Model | When to Use | Example Roles |
|-------|-------------|---------------|
| `opus` | Strategy/judgment required | scouts, complex execution agents |
| `sonnet` | Standard execution/validation | workers, qa, support |
| `haiku` | Information gathering/writing | researcher, editor, simple writer |

**Decision rule**: "Does it need to make new judgments?" → opus. "Does it execute against given criteria?" → sonnet. "Does it find information or write text?" → haiku.

---

## Software Engineering Examples

| Agent | Role | Use Case |
|-------|------|----------|
| architect | System design, API design, module structure | "Design the auth refactor" |
| implementer | Write production code based on a design | "Implement the new auth flow" |
| test-writer | Write unit/integration/e2e tests | "Add test coverage for auth" |
| refactorer | Improve code structure without changing behavior | "Clean up legacy patterns" |
| migrator | Database/schema/API migration scripts | "Migrate from v1 to v2 schema" |
| reviewer | Code review with specific focus area | "Review for security issues" |
| debugger | Investigate and fix specific bugs | "Find root cause of timeout" |
| docs-writer | Write or update documentation | "Update API docs for new endpoints" |

## Research & Analysis Examples

| Agent | Role | Use Case |
|-------|------|----------|
| researcher | Investigate topics, gather information | "Research auth library options" |
| analyst | Analyze data, derive insights | "Analyze error patterns in logs" |
| benchmarker | Performance testing and comparison | "Benchmark three caching strategies" |
| competitor-analyst | Compare competing solutions | "Compare our API with competitors" |

## Content & Communication Examples

| Agent | Role | Use Case |
|-------|------|----------|
| writer | Draft documents, reports, emails | "Write the RFC for the new feature" |
| editor | Refine and polish written content | "Edit the blog post for clarity" |
| strategist | Plan content or communication strategy | "Plan the launch announcement" |

## Project Management Examples

| Agent | Role | Use Case |
|-------|------|----------|
| product-manager | PRD writing, backlog management, requirements | "Write the PRD for notifications" |
| project-coordinator | Timeline, milestones, stakeholder comms | "Create the migration timeline" |
| ux-designer | Wireframes, user journeys, UI specs | "Design the onboarding flow" |

---

## Common Agents (Always Included)

Every team must include these roles:

| Agent | Role | Notes |
|-------|------|-------|
| qa | Evidence-based PASS/FAIL evaluation against acceptance criteria | Phase 5 validation only |
| support | Fix FAIL items from qa, verify/fix loop | Deployed only when Phase 5 has FAILs |

### qa Behavior Rules

- No PASS without evidence
- No subjective judgment — only objective evaluation against acceptance criteria
- No direct code modifications (validation only)

### support Behavior Rules

- Fix only FAIL items — no out-of-scope changes
- Do not modify anything qa did not flag

---

## Agent Design Checklist

When a scout designs a new agent:

1. **Name**: kebab-case, role should be immediately obvious
2. **Role**: one sentence defining the core responsibility
3. **Tasks**: specific deliverables for this particular project
4. **Reference files**: file/directory paths the agent needs to read
5. **Constraints**: what the agent must NOT do (scope guard)
6. **Dependencies**: which agent results must come first


================================================
FILE: plugins/team-assemble/skills/team-assemble/references/enable-agent-teams.md
================================================
# Enable Agent Teams in Claude Code

Agent teams are experimental and disabled by default. You must enable them before using the team-assemble skill.

## Quick Setup

Add this to your `settings.json`:

```json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}
```

### Where is settings.json?

| Scope | Path |
|-------|------|
| User (global) | `~/.claude/settings.json` |
| Project | `.claude/settings.json` (in project root) |

User settings apply to all projects. Project settings apply only to that project.

### Alternative: Environment Variable

Set it in your shell profile (`~/.zshrc`, `~/.bashrc`, etc.):

```bash
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
```

Then restart your terminal or run `source ~/.zshrc`.

## Verify It's Enabled

After setting, start Claude Code and ask it to create a team. If agent teams are not enabled, Claude Code will not have access to TeamCreate, SendMessage, and related tools.

## Display Modes

Agent teams support two display modes:

| Mode | Description | Setup |
|------|-------------|-------|
| **in-process** (default) | All teammates in one terminal. Use Shift+Down to cycle. | Works everywhere |
| **split panes** | Each teammate gets its own pane | Requires tmux or iTerm2 |

To set a display mode, add to `settings.json`:

```json
{
  "teammateMode": "in-process"
}
```

Or pass as a flag:

```bash
claude --teammate-mode in-process
```

### Split Pane Setup (Optional)

For split-pane mode, install one of:

- **tmux**: `brew install tmux` (macOS) or your system's package manager
- **iTerm2**: install the [`it2` CLI](https://github.com/mkusaka/it2), then enable Python API in iTerm2 → Settings → General → Magic → Enable Python API

> Note: Split-pane mode is not supported in VS Code's integrated terminal, Windows Terminal, or Ghostty.

## Key Controls (In-Process Mode)

| Key | Action |
|-----|--------|
| Shift+Down | Cycle through teammates |
| Enter | View a teammate's session |
| Escape | Interrupt teammate's current turn |
| Ctrl+T | Toggle task list |

## Known Limitations

- **No session resumption**: `/resume` and `/rewind` do not restore in-process teammates
- **One team per session**: clean up the current team before starting a new one
- **No nested teams**: teammates cannot spawn their own teams
- **Permissions inherited**: all teammates start with the lead's permission mode
- **Shutdown can be slow**: teammates finish their current operation before shutting down

## Official Documentation

For the latest information: https://code.claude.com/docs/en/agent-teams


================================================
FILE: plugins/team-assemble/skills/team-assemble/references/examples.md
================================================
# Team Assemble — Worked Examples

Three examples showing the full workflow for different task types.

---

## Example 1: Feature Development (Auth Refactor)

**User input**: "Assemble a team to refactor our authentication from session-based to JWT"

### Phase 1: Task Analysis

```
Relevant codebase areas:
- [x] src/auth/ — Current session-based auth implementation
- [x] src/middleware/ — Auth middleware
- [x] tests/auth/ — Auth test suite
- [ ] src/api/ — Uses auth but not directly modified
```

→ AskUserQuestion approval

### Phase 2: Codebase Scouts

auth-scout (opus) + middleware-scout (opus) launched in parallel:

```
Agent(name="auth-scout", model="opus", subagent_type="general-purpose", prompt="""
You are a codebase scout for the authentication area.
Task: Refactor from session-based to JWT authentication
Target path: src/auth/
...
""")
Agent(name="middleware-scout", model="opus", subagent_type="general-purpose", prompt="""
You are a codebase scout for the middleware area.
Task: Refactor from session-based to JWT authentication
Target path: src/middleware/
...
""")
```

### Phase 3: Integrate & Confirm

```
Proposed team: auth-refactor-team

| # | Agent | Role | Tasks | Dependencies |
|---|-------|------|-------|--------------|
| 1 | architect | System design | Design JWT flow, token strategy, migration path | - |
| 2 | implementer | Code changes | Implement JWT auth, update middleware | #1 |
| 3 | test-writer | Test coverage | Update auth tests for JWT flow | #2 |
| 4 | qa | Validation | PASS/FAIL against acceptance criteria | #2, #3 |

Acceptance criteria:
- [ ] AC-1: JWT token generation and validation implemented
- [ ] AC-2: All existing auth tests pass or are updated
- [ ] AC-3: Middleware correctly validates JWT tokens
- [ ] AC-4: No regression in existing API endpoints
```

→ AskUserQuestion final approval

### Phase 4: Execution

```
TeamCreate(team_name: "auth-refactor-team", description: "Refactor auth from session to JWT")

# Round 1: architect (independent)
Agent(name="architect", model="opus", ...)

# Round 2: implementer (#1 result included)
Agent(name="implementer", model="sonnet", prompt="Design:\n{architect_result}\n...")

# Round 3: test-writer (#2 result included)
Agent(name="test-writer", model="sonnet", prompt="Implementation:\n{implementer_result}\n...")
```

### Phase 5~6: Validate → Complete

qa PASS → result report → TeamDelete

---

## Example 2: Research & Decision Making

**User input**: "Use a team to evaluate caching strategies for our API — Redis vs Memcached vs in-memory"

### Phase 1: Task Analysis

```
Relevant codebase areas:
- [x] src/api/ — API endpoints that need caching
- [x] config/ — Infrastructure configuration
- [ ] tests/ — Not directly relevant yet

→ General research task — skip Phase 2 (no codebase scouting needed)
→ Design team directly using references/agents.md
```

### Phase 3: Team Design (Phase 2 skipped)

```
Proposed team: caching-eval-team

| # | Agent | Role | Tasks | Dependencies |
|---|-------|------|-------|--------------|
| 1 | redis-researcher | Redis analysis | Research Redis: features, performance, ops cost | - |
| 2 | memcached-researcher | Memcached analysis | Research Memcached: features, performance, ops cost | - |
| 3 | inmemory-researcher | In-memory analysis | Research in-memory caching: features, limits, trade-offs | - |
| 4 | analyst | Comparison | Synthesize findings into comparison matrix | #1, #2, #3 |
| 5 | qa | Validation | Verify completeness and accuracy | #4 |

Acceptance criteria:
- [ ] AC-1: All three options analyzed with feature/performance/cost dimensions
- [ ] AC-2: Comparison matrix with clear trade-offs
- [ ] AC-3: Recommendation with rationale based on our API's access patterns
```

### Phase 4: Execution

```
# Round 1: Three researchers in parallel (no dependencies)
Agent(name="redis-researcher", model="haiku", ...)
Agent(name="memcached-researcher", model="haiku", ...)
Agent(name="inmemory-researcher", model="haiku", ...)

# Round 2: analyst synthesizes (#1, #2, #3 results included)
Agent(name="analyst", model="sonnet", prompt="Research findings:\n{all_results}\n...")
```

### Phase 5~6: Validate → Complete

qa validates comparison matrix completeness → PASS → deliver report → TeamDelete

---

## Example 3: Multi-File Refactoring

**User input**: "Assemble a team to extract shared utilities from three microservices into a common library"

### Phase 1: Task Analysis

```
Relevant codebase areas:
- [x] services/user-service/src/utils/ — User service utilities
- [x] services/order-service/src/utils/ — Order service utilities
- [x] services/payment-service/src/utils/ — Payment service utilities
- [x] packages/ — Target for common library
```

→ AskUserQuestion approval

### Phase 2: Codebase Scouts

Three scouts launched in parallel (one per service):

```
Agent(name="user-svc-scout", model="opus", ...)
Agent(name="order-svc-scout", model="opus", ...)
Agent(name="payment-svc-scout", model="opus", ...)
```

Each scout identifies shared patterns and proposes extraction candidates.

### Phase 3: Integrate & Confirm

```
Proposed team: common-lib-team

| # | Agent | Role | Tasks | Dependencies |
|---|-------|------|-------|--------------|
| 1 | lib-architect | Library design | Define common lib API, module structure | - |
| 2 | lib-implementer | Create library | Build the common library package | #1 |
| 3 | user-svc-migrator | Service update | Update user-service to use common lib | #2 |
| 4 | order-svc-migrator | Service update | Update order-service to use common lib | #2 |
| 5 | payment-svc-migrator | Service update | Update payment-service to use common lib | #2 |
| 6 | qa | Validation | Verify all services work with common lib | #3, #4, #5 |

Acceptance criteria:
- [ ] AC-1: Common library created with shared utilities
- [ ] AC-2: All three services updated to import from common lib
- [ ] AC-3: No duplicate utility code remains in services
- [ ] AC-4: All existing tests pass
```

### Phase 4: Execution

```
# Round 1: lib-architect (independent)
Agent(name="lib-architect", model="opus", ...)

# Round 2: lib-implementer (#1 result)
Agent(name="lib-implementer", model="sonnet", ...)

# Round 3: Three migrators in parallel (#2 result, each owns different service)
Agent(name="user-svc-migrator", model="sonnet", ...)
Agent(name="order-svc-migrator", model="sonnet", ...)
Agent(name="payment-svc-migrator", model="sonnet", ...)
```

→ Round 3 agents run in parallel because they own non-overlapping files

### Phase 5~6: Validate → Complete

qa checks AC-1~4 → PASS → result report → TeamDelete


================================================
FILE: plugins/team-assemble/skills/team-assemble/references/prompt-templates.md
================================================
# Prompt Templates

## 1. Codebase Scout Prompt

Template for scout agents in Phase 2.

```
## Mission

You are a codebase scout for the {area} area. Design expert agents to handle the task described below.

## Task
{user_task_description}

## Target Path
{target_path}

## Instructions

1. Read key files in this area to understand the current state:
   - CLAUDE.md, README.md (if present)
   - Directory structure (use Glob to explore)
   - Existing files/data related to the task

2. Propose agents needed for this task:
   - Use `references/agents.md` examples as inspiration (not mandatory)
   - Design entirely new agents when the task demands it
   - For each agent: name, role, specific tasks, reference files

3. Report any area-specific constraints or patterns to follow.

## Constraints
- Do NOT modify any files — exploration and analysis only
- Agent names must be kebab-case

## Output Format

### Current State
- {file structure and key findings summary}

### Proposed Agents
| Agent | Role | Tasks | Reference Files |
|-------|------|-------|-----------------|
| {name} | {role} | {specific task} | {file paths} |

### Notes
- {area-specific constraints, existing patterns, easy-to-miss details}
```

### Usage Example

```python
# Scout for the auth module
Agent(
    name="auth-scout",
    model="opus",
    subagent_type="general-purpose",
    prompt=scout_template.format(
        area="authentication",
        target_path="src/auth/",
        user_task_description="Refactor authentication to support OAuth2"
    )
)
```

When multiple areas are relevant, **launch scouts in parallel in a single message**:

```python
# Simultaneous execution
Agent(name="auth-scout", ...)
Agent(name="api-scout", ...)
```

---

## 2. Execution Agent Prompt

General prompt structure for execution agents in Phase 4.

### Structure (5 Sections)

```
## Context
{Project background and where this task fits in the overall work}
{Include preceding agent results if this task has dependencies}

## Goal
{Exactly what to achieve — clear and measurable}

## Reference Files
{List of relevant file paths identified by scouts}
- {path/to/file1} — {purpose}
- {path/to/file2} — {purpose}

## Constraints
- {What NOT to do}
- {Files/scope that must not be changed}
- {Rules to follow}

## Output Format
{Specific shape of the deliverable — markdown file, table, checklist, code, etc.}

## Team Info
- team_name: {team-name}
- task_id: {task-id}
- On completion: TaskUpdate(taskId: "{task-id}", status: "completed")
```

### Including Preceding Results

For agents with dependencies, inject the preceding agent's output directly:

```
## Context
You are part of the auth-refactor team.

### Preceding Results
{architect_result}

Based on the design above, implement the new authentication flow.
```

---

## 3. QA Prompt

Used for Phase 5 validation.

```
## Context
{Summary of overall team work}

## Acceptance Criteria
- [ ] AC-1: {criterion 1}
- [ ] AC-2: {criterion 2}
- [ ] AC-3: {criterion 3}

## Validation Target
{All Phase 4 execution results}

## Goal
Evaluate each acceptance criterion with evidence-based PASS/FAIL judgment.
- No PASS without evidence
- No subjective judgment — only objective evaluation against criteria
- No direct modifications (validation only)

## Output Format
| # | Criterion | Verdict | Evidence |
|---|-----------|---------|----------|
| 1 | {AC-1} | PASS/FAIL | {specific evidence} |

Overall: PASS / FAIL
If FAIL:
- Failure reason: {specific problem}
- Fix suggestion: {how to fix it}

## Team Info
- team_name: {team-name}
- task_id: {task-id}
- On completion: TaskUpdate(taskId: "{task-id}", status: "completed")
```

---

## 4. Support Prompt

Used when Phase 5 produces FAILs.

```
## Context
{Summary of team work}

## Failed Items
{qa's FAIL verdicts and fix suggestions}

## Goal
Fix only the FAIL items. Do NOT change anything beyond FAIL scope.

## Constraints
- Do NOT modify anything qa did not flag
- Do NOT break existing PASS items

## Output Format
| # | Failed Criterion | Fix Applied | Files Modified |
|---|-----------------|-------------|----------------|
State what needs to be re-validated.

## Team Info
- team_name: {team-name}
- task_id: {task-id}
- On completion: TaskUpdate(taskId: "{task-id}", status: "completed")
```

---

## Prompt Writing Tips

- **Be specific**: not "refactor the code" but "extract the validation logic from UserController into a ValidationService class"
- **Limit scope**: explicitly list which files/directories can be modified
- **Fix output format**: require structured output (tables, checklists) not free-form text
- **Include preceding results**: for dependent tasks, paste the previous agent's output into the prompt body
- **List reference files**: include relevant file paths from scout findings in the prompt


================================================
FILE: plugins/youtube-digest/.claude-plugin/plugin.json
================================================
{
  "name": "youtube-digest",
  "version": "0.2.0",
  "description": "Summarize YouTube videos with transcript, insights, Korean translation, and quizzes",
  "author": {
    "name": "Team Attention",
    "url": "https://github.com/team-attention"
  }
}


================================================
FILE: plugins/youtube-digest/README.md
================================================
# YouTube Digest

YouTube 영상을 분석하여 요약, 인사이트, 한글 번역을 생성하고 퀴즈로 학습 이해도를 테스트하는 플러그인.

## Features

- **Transcript 추출**: yt-dlp로 자막 추출 (한/영 수동/자동)
- **고유명사 교정**: 웹 검색으로 자동 자막 오인식 보정
- **문서 생성**: 요약 + 인사이트 + 전체 번역
- **학습 퀴즈**: 3단계 × 3문제 = 9문제 이해도 테스트
- **Deep Research**: 웹 심층 조사 옵션

## Prerequisites

- `yt-dlp` 설치 필요

```bash
brew install yt-dlp
```

## Usage

```
유튜브 정리해줘 https://www.youtube.com/watch?v=xxxxx
```

또는:
- "영상 요약해줘"
- "transcript 번역해줘"
- "YouTube digest"

## Output

`research/readings/youtube/{YYYY-MM-DD}-{title}.md` 형식으로 저장:
- 요약 및 주요 포인트
- 인사이트 및 적용점
- 전체 스크립트 (한글 번역)
- 퀴즈 결과 및 오답 노트


================================================
FILE: plugins/youtube-digest/skills/youtube-digest/SKILL.md
================================================
---
name: youtube-digest
description: This skill should be used when the user asks to "유튜브 정리", "영상 요약", "transcript 번역", "YouTube digest", "영상 퀴즈", or provides a YouTube URL for analysis. Extracts transcript, generates summary/insights/Korean translation, and tests comprehension with 9 quiz questions across 3 difficulty levels. Optional Deep Research for web-based follow-up.
---

# YouTube Digest

YouTube 영상 분석 → 요약/인사이트/번역 문서 생성 → 퀴즈 테스트.

## 워크플로우

### 1. 메타데이터 수집

```bash
scripts/extract_metadata.sh "<URL>"
```

추출: title, description, channel, upload_date, duration, tags

### 2. Transcript 추출

```bash
scripts/extract_transcript.sh "<URL>" [output_dir]
```

우선순위: 수동 자막(ko→en) > 자동 생성 자막(ko→en)

### 3. 맥락 파악 (WebSearch)

웹 검색으로 고유명사 정확한 표기 수집:
- `"{영상 제목}" {채널명} summary`
- `"{발표자명}" {주제 키워드}`

### 4. Transcript 교정

자동 자막의 고유명사 오인식을 웹 검색 결과로 대체:
- Kora → Cora, cloud code → Claude Code, every → Every.to

### 5. 문서 생성

```markdown
---
title: {영상 제목}
url: {YouTube URL}
channel: {채널명}
date: {업로드 날짜}
duration: {영상 길이}
processed_at: {처리 일시}
---

# {영상 제목}

## 요약
{3-5문장 요약 + 주요 포인트 3개}

## 인사이트
### 핵심 아이디어
### 적용 가능한 점

## 전체 스크립트 (한글 번역)
[00:00] ...
```

### 6. 파일 저장

위치: `research/readings/youtube/{YYYY-MM-DD}-{sanitized-title}.md`

### 7. 학습 퀴즈

3단계 × 3문제 = 총 9문제. AskUserQuestion으로 각 단계 3문제 동시 출제.

| 단계 | 난이도 | 출제 기준 |
|------|--------|----------|
| 1 | 기본 | 핵심 인사이트, 주요 개념 |
| 2 | 중급 | 인사이트 + 세부 내용 연결 |
| 3 | 심화 | 세부 내용, 적용/분석 |

문제 유형 상세: `references/quiz-patterns.md`

#### 결과 처리

틀린 문제에 대해 정답과 해설 제공 후, 문서 끝에 퀴즈 결과 추가:

```markdown
## 퀴즈 결과

총점: 7/9 (78%) | 1단계 3/3 ✅ | 2단계 2/3 | 3단계 2/3

### 오답 노트

**Q5**: {질문}
- 선택: B → 정답: C
- {1-2문장 해설}
```

### 8. 후속 선택

퀴즈 완료 후 AskUserQuestion:
- **한 번 더 퀴즈**: 다른 문제로 재테스트
- **Deep Research**: 웹 심층 조사 (`references/deep-research.md` 참조)
- **종료**: 마무리

## 참고사항

### 자막 언어 우선순위
1. 한국어 수동 → 2. 영어 수동 → 3. 한국어 자동 → 4. 영어 자동

### 불완전한 자막 처리
- 고유명사 오인식: 4단계에서 일괄 대체
- 이해 불가 부분: `[불명확]` 표시

### yt-dlp 옵션
- `--list-subs`: 자막 목록 확인
- `--cookies-from-browser chrome`: 로그인 필요 시

## 리소스

- `scripts/extract_metadata.sh` - 메타데이터 추출
- `scripts/extract_transcript.sh` - 자막 추출
- `references/quiz-patterns.md` - 퀴즈 문제 유형 상세
- `references/deep-research.md` - Deep Research 워크플로우


================================================
FILE: plugins/youtube-digest/skills/youtube-digest/references/deep-research.md
================================================
# Deep Research Workflow

퀴즈 완료 후 "Deep Research" 선택 시 수행하는 웹 심층 조사.

## 워크플로우

### 1. 병렬 웹 검색 (WebSearch x 3-5)

검색 쿼리 예시:
- `"{주제}" 심층 분석`
- `"{핵심 개념}" 사례 연구`
- `"{발표자/채널}" 관련 자료`
- `"{기술/방법론}" best practices`
- `"{주제}" research paper`

### 2. 병렬 웹 페이지 수집 (WebFetch)

검색 결과 중 관련성 높은 3-5개 페이지 병렬 fetch.

### 3. 기존 문서 확장

원본 YouTube Digest 파일에 `## Deep Research` 섹션 추가:

```markdown
## Deep Research

> 생성일: {날짜}
> 검색 쿼리: {사용된 쿼리 목록}

### 추가 맥락

{웹 검색으로 발견한 배경 정보, 관련 개념 확장}

### 관련 자료

| 출처 | 요약 | URL |
|------|------|-----|
| {출처1} | {1줄 요약} | {URL} |
| {출처2} | {1줄 요약} | {URL} |

### 심화 인사이트

{영상 내용 + 웹 검색 결과를 종합한 추가 인사이트}

### 실행 가능한 Next Steps

- {구체적인 액션 아이템 1}
- {구체적인 액션 아이템 2}
```


================================================
FILE: plugins/youtube-digest/skills/youtube-digest/references/quiz-patterns.md
================================================
# Quiz Patterns

3단계 퀴즈 출제 가이드.

## 난이도별 문제 유형

### 1단계 (기본) - 인사이트 이해도

핵심 메시지와 주요 개념 확인:
- "이 영상의 핵심 메시지는 무엇인가요?"
- "발표자가 강조한 가장 중요한 원칙은?"
- "영상에서 제시한 주요 문제점은?"

### 2단계 (중급) - 인사이트와 세부 내용 연결

개념 간 관계와 근거 확인:
- "X 개념이 중요한 이유로 발표자가 든 근거는?"
- "A와 B의 차이점으로 설명된 것은?"
- "해당 전략의 장점으로 언급된 것은?"

### 3단계 (심화) - 세부 내용 및 적용

사례 분석과 구체적 데이터:
- "언급된 사례에서 성공 요인으로 분석된 것은?"
- "이 접근법을 적용할 때 주의점으로 언급된 것은?"
- "발표자가 제시한 구체적인 수치/데이터는?"

## AskUserQuestion 형식

```
AskUserQuestion:
questions:
  - question: "[1단계 - 기본] 질문 1..."
    header: "Q1"
    options:
      - label: "A"
        description: "선택지 A 설명"
      - label: "B"
        description: "선택지 B 설명"
      - label: "C"
        description: "선택지 C 설명"
      - label: "D"
        description: "선택지 D 설명"
    multiSelect: false
  - question: "[1단계 - 기본] 질문 2..."
    header: "Q2"
    ...
  - question: "[1단계 - 기본] 질문 3..."
    header: "Q3"
    ...
```

## 결과 처리

각 단계 완료 후:
1. 정답/오답 즉시 표시
2. 틀린 문제에 대해 상세 해설 제공:
   - 정답이 무엇인지
   - 왜 그것이 정답인지 (영상 내용 참조)
   - 관련 타임스탬프 (있을 경우)


================================================
FILE: plugins/youtube-digest/skills/youtube-digest/scripts/extract_metadata.sh
================================================
#!/bin/bash
# YouTube 메타데이터 추출
# Usage: ./extract_metadata.sh <URL>

URL="$1"

if [ -z "$URL" ]; then
  echo "Usage: $0 <YouTube URL>"
  exit 1
fi

yt-dlp --dump-json --no-download "$URL"


================================================
FILE: plugins/youtube-digest/skills/youtube-digest/scripts/extract_transcript.sh
================================================
#!/bin/bash
# YouTube 자막 추출
# Usage: ./extract_transcript.sh <URL> [output_dir]

URL="$1"
OUTPUT_DIR="${2:-.}"

if [ -z "$URL" ]; then
  echo "Usage: $0 <YouTube URL> [output_dir]"
  exit 1
fi

# JSON3 형식으로 자막 추출 (한국어 > 영어 우선)
yt-dlp --write-auto-sub --sub-lang "ko,en" --skip-download --convert-subs json3 \
  -o "$OUTPUT_DIR/%(title)s.%(ext)s" "$URL"