Metadata-Version: 2.4
Name: poc-forge
Version: 0.1.0
Summary: AI-native pipeline: idea -> Claude Code-ready docs
Author: Tokamak
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.12
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: anthropic>=0.28.0
Requires-Dist: fastapi>=0.111.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer[all]>=0.12.0
Requires-Dist: uvicorn[standard]>=0.30.0
Provides-Extra: agent-sdk
Requires-Dist: claude-agent-sdk>=0.0.1; extra == 'agent-sdk'
Provides-Extra: dev
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# PoC Forge

**아이디어 → 문서 → 리뷰 → 승인 → Claude Code 자동 개발**

PoC를 빠르게 만들고 싶은 개발자와 PM을 위한 AI-native 문서 생성 + 에이전트 개발 파이프라인.  
**설계 문서가 정확하고 빠짐없어야 에이전트 개발 시 수정이 적다** — 이 원칙을 데이터로 검증합니다.

> 파일럿 실험 결과: CC Ready Score ≥ 60인 문서의 Claude Code AEQ는 평균 **0.867**,  
> 미달 문서는 **0.000** — 30배 이상 차이 (Pearson r = 0.937, n=10)

---

## 핵심 플로우 (v4)

```
Idea Input  (mode: new_project | feature_addition)
    ↓
[Phase 0A] Intake Enrichment  → IdeaDoc JSON (entities · deps · constraints)
[Phase 0B] Architecture Pattern Detection  (8 patterns, Haiku 1-shot)
    ↓  [feature_addition only]
[FA-0] Codebase Ingestion  (CLAUDE.md paste or Git URL)
[FA-1] Delta Analysis  → ADD / MODIFY / CONFLICT report
    ↓
[Phase 1-0] Assumption Map  ← identify-assumptions-new 방법론 내장 (8 리스크)
[Phase 1a]  Domain Model    ← 패턴별 섹션 자동 주입
[Phase 1b]  API Contract    ← 패턴별 섹션 자동 주입
    ↓
[Phase 2 ‖] Task List (WWA 포맷) · PRD · Test Strategy  (병렬 3개)
              ↑ wwas 방법론 내장    ↑ test-scenarios 방법론 내장
    ↓
[Phase 3]   Cross-doc 자가 검증 + 수정 루프  (≤3회)
    ↓
[Phase 4 ‖] 6개 리뷰 에이전트  (병렬)
    · Arch · Security · PM/Biz · Test Strategy · CC Readiness · Regression
    ↓
[Phase 5]   CC Repair Loop  ── score ≥ 80이면 즉시 통과
    while score < 80 AND iteration ≤ 3:
        repair(all issues, HIGH 우선)
        re-run all reviewers
        score 재계산
    ──▶ 3회 후에도 미달이면 경고 표시 (승인은 가능)
    ↓
[Phase 6]   Human Approve Gate
    ├── Approve  ──▶ Phase 7
    └── Reject   ──▶ 파이프라인 종료  (재시작하려면 새 아이디어 제출)
    ↓
[Phase 7]   Agent-Friendly 변환
    · CLAUDE.md  · tasks.json (why 필드)  · CONSTRAINTS.md
    · delta_patch.md  [feature_addition only]
    ↓
[Phase 8]   Claude Code 실행  (task-by-task · SSE 스트리밍)
    ↓
실시간 Progress 대시보드  (SSE — phase · cc_score · doc_ready · task_done)
```

> **외부 플러그인 불필요**: pm-skills 방법론과 CC Repair Loop은 파이프라인에 완전 내장.
> 사용자는 API 키 + `uv tool install poc-forge` 만으로 동일한 품질을 얻습니다.

---

## CC Ready — 핵심 차별점

기존 AI 코딩 도구(Lovable, Bolt, Replit)와의 결정적 차이는 **코드를 쓰기 전에 설계를 검증**하는 것입니다.

> "이 문서만 보고 Claude Code가 **한 번의 질문 없이** 구현 + 테스트까지 완료할 수 있는가?"

CC Ready Score는 11개 기준 × 가중치로 0–100점 정량화됩니다.

| 기준 | 가중치 |
|---|---|
| `task_unambiguous` — 모호한 표현 없음 | 20% |
| `acceptance_criteria` — 검증 가능 + **WHY 필드** | 20% |
| `api_spec_complete` — method/path/request/response | 15% |
| `db_schema_complete` — 타입/제약/인덱스 | 15% |
| `dependencies_explicit` — task 간 의존성 | 10% |
| `env_vars_documented` | 8% |
| `file_structure_defined` | 5% |
| `atomic_tasks` | 5% |
| `no_vague_instructions` + Out-of-scope 미침범 | 2% |

---

## pm-skills 통합 (v3)

[phuryn/pm-skills](https://github.com/phuryn/pm-skills)에서 선별한 3개 스킬이 파이프라인에 내장됩니다.

### `identify-assumptions-new` → Stage 0 Assumption Map

Teresa Torres의 8개 리스크 카테고리 분석.  
Out-of-scope 목록이 `CONSTRAINTS.md`의 `MUST NOT` 룰로 자동 변환됩니다.

### `wwas` → Task List 포맷 강제

모든 task에 **WHY 필드 필수** — 실험에서 `acceptance_criteria` 플래그 감소에 직접 기여.

```markdown
### T001: 사용자 인증 엔드포인트
**Why:** 모든 API 접근 보호 — Viability 리스크 완화의 핵심
**What:** POST /auth/login, JWT HS256 24h TTL
**Acceptance Criteria:**
- [ ] 유효한 credentials → 200 + {token, expires_at}
- [ ] 잘못된 password → 401 + {"error": "invalid_credentials"}
```

### `test-scenarios` → Test Strategy 구조화

Test Objective + Starting Conditions + Test Steps + Expected Outcomes 포맷 강제.  
Assumption Map의 가장 위험한 가정에 대한 검증 시나리오 자동 포함.

---

## 배포 형태

| 형태 | 진입점 | 상태 |
|---|---|---|
| **통합 서버** | `poc-forge` (uv tool install, 프론트+백 단일 포트) | ✅ 지원 |
| CLI | `forge "idea"` (서버 없이 헤드리스 실행) | ✅ 지원 |
| Self-hosted | FastAPI + Docker Compose | ✅ 지원 |
| Web SaaS | `https://poc-forge.dev` | 계획 |
| VS Code Extension | Marketplace | 계획 |

---

## 구조

```
poc-forge/
├── backend/
│   ├── main.py                   # FastAPI app + SSE /stream endpoint
│   ├── core/orchestrator.py      # 전체 파이프라인 실행기
│   ├── agents/
│   │   ├── doc_agents.py         # Stage 0-3 (v3: pm-skills 통합)
│   │   ├── review_agents.py      # 5개 리뷰어 (v3: WHY check 추가)
│   │   └── converter.py          # CLAUDE.md · tasks.json · CONSTRAINTS.md
│   ├── routers/__init__.py       # intake · generate · review · approve · convert · execute
│   └── models/
│       ├── session.py            # 세션 상태 + asyncio approval gate
│       └── metrics.py            # CCReadyScorer · ExecutionMetrics · AEQ Score
├── experiment/
│   ├── run_10_ideas_local.py     # CC Ready × AEQ 상관관계 실험
│   └── results.json              # 파일럿 결과 (r=0.937)
├── docs/
│   ├── CLAUDE.md.template
│   ├── tasks.schema.json
│   └── CONSTRAINTS.md.template
├── docker-compose.yml
└── README.md
```

---

## 빠른 시작

### 통합 서버 (권장)

```bash
uv tool install poc-forge

poc-forge          # 첫 실행 시 LLM 설정 위자드 → http://localhost:3000 자동 오픈
```

브라우저에서 아이디어 제출 → 문서 생성 → 리뷰 → Approve → 프로젝트 경로 지정 → Claude Code 자동 실행.

```bash
poc-forge --port 8080            # 포트 변경
poc-forge --no-browser           # 브라우저 자동 오픈 비활성화
poc-forge setup                  # LLM 설정 재실행
```

**LLM 설정 위자드** (`poc-forge setup`) 에서 선택:

| Provider | 필요 정보 |
|---|---|
| Anthropic API | `ANTHROPIC_API_KEY` |
| LiteLLM 프록시 | `LITELLM_API_BASE` + `LITELLM_API_KEY` |
| Claude Code 구독 | API 키 불필요 |

설정은 `~/.poc-forge/config.toml`에 저장됩니다.

---

### CLI (서버 없이 헤드리스 실행)

```bash
forge "idea"                                        # 기본 (new_project 모드)
forge "idea" --preset web-saas                      # 프리셋: generic|web-saas|cli|smart-contract|mobile
forge "idea" --lang ko                              # 한국어 문서 생성
forge "idea" --auto-approve                         # 승인 게이트 건너뛰기
forge "idea" --output-dir ./docs                    # 출력 경로 지정
forge "idea" -f idea.md                             # 파일에서 아이디어 읽기

# Feature Addition 모드 (기존 코드베이스에 기능 추가)
forge "Slack 알림 추가" --mode feature_addition --codebase ./CLAUDE.md
```

---

### 소스에서 설치 (개발용)

```bash
git clone https://github.com/tokamak-network/poc-forge
cd poc-forge

uv sync

# 프론트엔드 빌드 (선택, 통합 서버 모드 시 필요)
cd frontend && npx next build && cp -r out ../backend/_static

poc-forge --reload   # 자동 리로드 활성화
```

---

### Web API (REST 직접 호출)

```bash
poc-forge    # 서버 실행 후
```

```bash
# 아이디어 제출
curl -X POST http://localhost:3000/api/intake/ \
  -H "Content-Type: application/json" \
  -d '{"idea": "온라인 강의 플랫폼", "preset": "web-saas"}'

# 실시간 진행 확인
curl -N http://localhost:3000/api/sessions/{id}/stream

# 문서 확인
curl http://localhost:3000/api/generate/{id}/docs | jq 'keys'
# ["assumption_map", "domain_model", "api_contract", "task_list", "prd", "test_strategy"]

# CC Ready Score 확인 후 승인
curl http://localhost:3000/api/review/{id}/report
curl -X POST http://localhost:3000/api/approve/{id} -d '{"approved": true}'

# 프로젝트 경로 설정 후 Claude Code 실행
curl -X POST http://localhost:3000/api/execute/{id}/setup \
  -d '{"project_path": "~/projects/my-app"}'
curl -X POST http://localhost:3000/api/execute/{id}
```

---

## 실험 데이터 (파일럿, n=10)

```
Pearson r(CC Ready, AEQ) = 0.937

임계값 분석:
  CC ≥ 60 → AEQ 평균 0.867 (n=8)
  CC <  60 → AEQ 평균 0.000 (n=2)
  Delta:   +0.867 (30배 차이)

가장 자주 걸리는 기준:
  6x acceptance_criteria  (WHY 필드 누락 포함)
  5x api_spec_complete
  5x db_schema_complete
```

실험 재현: `python experiment/run_10_ideas_local.py`

---

## 개발 로드맵

- [x] Core API (FastAPI + SSE)
- [x] Stage 0–3 문서 생성 파이프라인 (순차 + 자가검증)
- [x] 5 Review Agents + CC Ready Scorer
- [x] Human Approval Gate
- [x] Agent-Friendly Converter
- [x] **pm-skills 통합** (identify-assumptions-new · wwas · test-scenarios)
- [x] CC Ready × AEQ 상관관계 실험 프레임워크
- [x] **CLI** (`forge "idea"` — 서버리스, typer + rich)
- [x] Feature Addition 모드 (기존 코드베이스 + 신규 기능 → delta_patch.md)
- [x] **Web UI** (Progress Dashboard + Assumption Map + Approve Gate)
- [x] **통합 바이너리** (`poc-forge` — 프론트+백 단일 포트, 설정 위자드, 브라우저 자동 오픈)
- [x] **Claude Code 실행 대시보드** (프로젝트 경로 설정 → task-by-task 실행 진행)
- [ ] VS Code Extension
- [ ] Preset 시스템 (web-saas · cli · smart-contract · mobile)
- [ ] n=50 실험으로 통계적 유의성 확보

---

## 기여

PR 환영합니다. 새 리뷰 에이전트, Preset 추가, 실제 Claude Code 실행 데이터 제출이 특히 도움됩니다.

---

## 라이선스

MIT
