# Superpowers Lecture & Study Pipeline

Superpowers fork with two AI-driven pipelines — a full **lecture production pipeline** for creating technical lectures, and a **3-day study pipeline** for deep-diving into coding concepts.

## How it works

## Installation

### Claude Code — GitHub 마켓플레이스로 설치 (권장)

1. GitHub 저장소를 마켓플레이스로 등록한다:

```bash
claude plugin marketplace add github:soyotime0118/superpowers --name superpowers-dev
```

2. 플러그인을 설치한다:

```bash
claude plugin install superpowers@superpowers-dev
```

### 업데이트

```bash
claude plugin marketplace update superpowers-dev
claude plugin update superpowers@superpowers-dev
```

### Claude Code — 로컬 디렉토리로 직접 로드 (개발용)

1. 이 저장소를 클론한다:

```bash
git clone https://github.com/soyotime0118/superpowers.git
```

2. Claude Code에서 로컬 마켓플레이스로 등록한다:

```bash
claude plugin marketplace add /path/to/superpowers --name superpowers-local
```

3. 플러그인을 설치한다:

```bash
claude plugin install superpowers@superpowers-local
```

## The Basic Workflow

### 강의 제작 파이프라인

0. **brainstorming** (선택, 권장) — 강의 주제/목표/범위를 대화로 정리. `current-run.md`의 Keywords/Topics 초안 도출.

1. **plugin-phase0-run-initializer** — `lecture_dir`을 전달하여 run 디렉토리 구조 생성 (`runs/run-YYYYMMDD-HHMM-N/`).

2. **plugin-rq-fanout-orchestrator** — `current_run_path` 전달. Concept/Implementation/Trade-off 3개 관점으로 RQ를 병렬 생성.

3. **plugin-rq-set-merger** — 3개 관점의 RQ 후보를 통합·중복제거·우선순위화하여 `phase1/merge/rq-set.md` 생성.

4. ⛔ **Gate 1 — rq-review skill** — `rq-set.md`를 대화형으로 검토·수정·확정. "RQ 검토해줘" 또는 "Gate 1 시작"으로 시작.

5. **plugin-rq-set-a-to-rq-files** — 확정된 RQ를 관점별 개별 파일로 분리 생성.

6. **plugin-evidence-master** — RQ별 Evidence-Collector 실행 계획 수립. E-NN 번호 사전 배정으로 충돌 방지.

7. **plugin-evidence-collector** — RQ별로 실행. GitHub MCP 우선, WebSearch fallback으로 코드/PR/문서 증거 수집.

8. **plugin-evidence-summary** — RQ↔Evidence 매핑 + Mermaid 관계도 생성.

9. ⛔ **Gate 2** — `phase2/rq-evidence-map.md` 검토 후 Phase 3 진행 여부 결정.

10. **plugin-outline-architect** — 강의 구성(outline) 설계. `mode: create`로 실행. 결과는 `phase3/outline/draft-NN/`에 저장.

11. **plugin-example-designer** — Java 예제 코드 설계. outline section별 example-plan.md 생성.

12. ⛔ **Gate 3 — outline-finalize skill** — draft 기반 대화형으로 section/example 선택 후 최종 outline 확정. 확정 직후 Section/Example 전체 요약 출력 → "script-maker 실행할까요?" 로 Phase 4 진입까지 한 번에 처리. "outline 확정해줘" 또는 "Gate 3 시작"으로 시작.

13. **plugin-script-maker** — Marp 슬라이드 형식 스크립트 작성.

14. **plugin-script-reviewer** — 스크립트 품질 검토 (DONE/PARTIAL/MISSING/MISALIGNED 평가).

### 3-Day 스터디 파이프라인

1. **plugin-study-run-initializer** — 스터디 주제와 `study_dir`을 전달하여 day1/day2/day3 구조 생성.

2. **[Day 1]** plugin-study-term-extractor → plugin-study-quiz-generator → quiz-session skill → plugin-study-concept-diagram

3. **[Day 2]** plugin-study-tutorial-guide → plugin-study-oss-analyzer → plugin-study-practice-reviewer

4. **[Day 3]** plugin-study-project-designer → plugin-study-code-reviewer → retrospective skill

## What's Inside

### Lecture Pipeline Agents

**Phase 0**
- **plugin-phase0-run-initializer** — Run 디렉토리 초기화 및 `current-run.md` 생성

**Phase 1 — RQ 세트 생성**
- **rq-fanout-orchestrator** — 3개 관점 병렬 RQ 생성 오케스트레이션
- **plugin-rq-list-generator** — 관점별 RQ 목록 생성 (Concept / Implementation / Trade-off)
- **plugin-rq-set-merger** — RQ 통합·정규화·우선순위화

**Phase 2 — Evidence 수집**
- **plugin-evidence-master** — Evidence 수집 Invocation Block 생성
- **plugin-evidence-collector** — RQ별 코드/문서/PR 증거 수집
- **plugin-evidence-summary** — RQ↔Evidence 매핑 문서 생성

**Phase 3 — 구성 설계**
- **plugin-outline-architect** — 강의 outline 설계 (CREATE/REVIEW 모드). 각 Section에 `related_examples` 필드로 연관 예제 ID 명시
- **example-designer** — 예제 코드 설계. 결과물은 `phase3/examples/{id}-example-plan.md`로 저장

**Phase 4 — 스크립트**
- **plugin-script-maker** — Marp 형식 강의 스크립트 작성. 발표자 노트에 ⏱ 시간, 💡 연관 예제(example-plan 내용) 포함
- **plugin-script-reviewer** — 스크립트 품질 검토

### Study Pipeline Agents (3-Day Study Workflow)

**Day 0**
- **plugin-study-run-initializer** — 스터디 Run 디렉토리 초기화 (`day1/`, `day2/`, `day3/` 구조 생성)

**Day 1 — Concept 학습**
- **plugin-study-term-extractor** — 학습 주제에서 핵심 용어 추출 및 정의 수집
- **plugin-study-quiz-generator** — terms.md 기반 Checkpoint 1 퀴즈 생성
- **plugin-study-concept-diagram** — 핵심 개념 간 관계를 Mermaid 다이어그램으로 시각화 (선택)

**Day 2 — 실습**
- **plugin-study-tutorial-guide** — 단계별 튜토리얼 가이드 생성
- **plugin-study-oss-analyzer** — 관련 OSS 코드 분석 (Best Practice / Anti-pattern 도출)
- **plugin-study-practice-reviewer** — 실습 코드 리뷰 및 Checkpoint 2 점검

**Day 3 — 프로젝트**
- **plugin-study-project-designer** — 학습 개념을 적용한 미니 프로젝트 명세 설계
- **plugin-study-code-reviewer** — 구현된 프로젝트 코드 리뷰 및 Checkpoint 3 평가
- **plugin-study-retrospective-guide** — 3일 학습 회고 문서 작성 가이드

### Skills Library

**Lecture Pipeline**
- **lecture-workflow** — 전체 강의 파이프라인 가이드
- **rq-review** — Gate 1: RQ 목록 대화형 검토·수정·확정
- **outline-finalize** — Gate 3: draft outline 기반 대화형 section/example 선택 → 최종 outline 확정 → Phase 4 진입 승인까지 한 번에 처리

**Study Pipeline**
- **study-workflow** — 전체 스터디 파이프라인 가이드
- **quiz-session** — Checkpoint 1: 퀴즈 대화형 Q&A 진행 및 즉시 채점
- **retrospective** — Day 3: KPT/4L 대화형 회고 → evaluation.md + retrospective.md 자동 작성

**Pipeline Utilities**
- **record-phase-result** — 각 phase 완료 시 `current-run.md`에 완료 블록 기록 (completed_at / status / outputs / summary)

**General (Superpowers 기본 제공)**
- **brainstorming** — 아이디어를 구조화된 설계로 정리
- **dispatching-parallel-agents** — 독립 작업 병렬 실행
- **systematic-debugging** — 체계적 디버깅 4단계 프로세스
- **test-driven-development** — RED-GREEN-REFACTOR 사이클
- **writing-plans** — 구현 계획 작성

## Lecture Production Pipeline

```
Phase 0 → Phase 1 → [Gate 1] → Phase 2 → [Gate 2] → Phase 3 → [Gate 3] → Phase 4
```

| Phase | 역할 | Agent/Skill |
|-------|------|-------------|
| Phase 0 | Run 초기화, 디렉토리 구조 생성 | `plugin-phase0-run-initializer` |
| Phase 1-1 | RQ 관점 분리 (fanout) | `plugin-rq-fanout-orchestrator` |
| Phase 1-2 | 관점별 RQ 생성 (병렬 ×3) | `plugin-rq-list-generator` |
| Phase 1-3 | RQ 병합 및 통합 | `plugin-rq-set-merger` |
| **Gate 1** | **RQ 목록 대화형 검토·수정·확정** | **`rq-review` skill** |
| Phase 1-4 | RQ 개별 파일 분리 생성 | `plugin-rq-set-a-to-rq-files` |
| Phase 2-1 | Evidence 수집 계획 수립 (E-NN 사전 배정) | `plugin-evidence-master` |
| Phase 2-2 | RQ별 Evidence 수집 (GitHub MCP / WebSearch) | `plugin-evidence-collector` |
| Phase 2-3 | RQ↔Evidence 매핑 + Mermaid 관계도 생성 | `plugin-evidence-summary` |
| **Gate 2** | **Evidence 커버리지 검토** | 수동 |
| Phase 3-1 | 강의 outline 설계 | `plugin-outline-architect` |
| Phase 3-2 | Java 예제 코드 설계 | `plugin-example-designer` |
| **Gate 3** | **최종 outline 확정 + Phase 4 진입 승인** | **`outline-finalize` skill** |
| Phase 4 | 스크립트 작성 및 리뷰 | `plugin-script-maker`, `plugin-script-reviewer` |

### 주요 설계 원칙

- **current_run_path 패턴**: 모든 agent가 `current-run.md` 경로 하나를 받아 `run_dir`, `lecture_dir`을 추출
- **Phase 완료 기록**: 각 phase agent가 완료 시 `record-phase-result` skill로 `current-run.md`에 완료 블록(status / outputs / summary) 누적 기록
- **Agent vs Skill 분리**: 대량 파일 처리·병렬 작업 → Agent / 사용자 상호작용·반복 수정 → Skill
- **Manual Gate**: 각 단계 전 사용자 검토 및 확인 단계 포함
- **plugin-evidence-collector 실행 모드**: 순차(Y) / 병렬(P, Rate Limit 위험 고지 포함) / 건너뜀(N) 선택 가능
- **RQ 관점 (Invocation B)**: OSS 구현 분석 시 `Pattern Fidelity & Evolution` 관점 포함 — 교과서(GoF) 대비 OSS가 포기한 부분·유지한 부분·진화 경로를 RQ로 다룸
- **연관 예제 연결**: outline Section의 `related_examples` 필드로 예제 ID 명시 → script-maker가 `example-plan.md`를 로드하여 발표자 노트에 자동 포함

## Study Pipeline

```
Day 0 → Day 1 → Day 2 → Day 3
```

| Day | 역할 | Agent/Skill |
|-----|------|-------------|
| Day 0 | Run 초기화 | `plugin-study-run-initializer` |
| Day 1 | 용어 추출 | `plugin-study-term-extractor` |
| Day 1 | 퀴즈 생성 | `plugin-study-quiz-generator` |
| Day 1 (선택) | 개념 다이어그램 | `plugin-study-concept-diagram` |
| **Checkpoint 1** | **대화형 퀴즈 세션** | **`quiz-session` skill** |
| Day 2 | 튜토리얼 생성 | `plugin-study-tutorial-guide` |
| Day 2 | OSS 분석 | `plugin-study-oss-analyzer` |
| Day 2 | 실습 코드 리뷰 | `plugin-study-practice-reviewer` |
| Day 3 | 미니 프로젝트 설계 | `plugin-study-project-designer` |
| Day 3 | 코드 리뷰 | `plugin-study-code-reviewer` |
| **Day 3 완료** | **대화형 회고** | **`retrospective` skill** |

### Study 빠른 시작

```
1. plugin-study-run-initializer 실행
   → study_dir: studies/study-01-factory-method
   → topic: "Factory Method Pattern"

2. current-run.md 경로를 복사하여 이후 agent에 전달

3. Day 1 순서대로 실행:
   plugin-study-term-extractor → plugin-study-quiz-generator → (plugin-study-concept-diagram 선택)

4. "퀴즈 풀어볼게" → quiz-session skill로 Checkpoint 1 진행

5. Day 2: plugin-study-tutorial-guide ∥ plugin-study-oss-analyzer → plugin-study-practice-reviewer

6. Day 3: plugin-study-project-designer → [직접 구현] → plugin-study-code-reviewer

7. "회고 시작해줘" → retrospective skill로 마무리
```

### 주요 설계 원칙 (Study)

- **current_run_path 패턴**: 강의 파이프라인과 동일. `current-run.md` 경로 하나로 모든 agent 연결
- **Checkpoint**: 학습 단계별 자가 점검 (1: 용어/개념, 2: 실습, 3: 프로젝트)
- **대화형 Skill**: 퀴즈(즉시 채점·해설)와 회고(KPT/4L 대화 → 문서 자동 작성)는 컨텍스트 유지가 필요하여 skill로 구현

## License

MIT License - see LICENSE file for details