Metadata-Version: 2.4
Name: cstage
Version: 0.2.0
Summary: McKinsey-style AI business consulting tool — Socratic interview to strategy report
License: MIT
Keywords: ai,consulting,mckinsey,mcp,strategy
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: claude-agent-sdk>=0.1.0
Requires-Dist: filelock>=3.0.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-mock>=3.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# cstage

McKinsey-style AI business consulting tool. Socratic interview to strategy report, fully automated.

**API key 불필요** -- Claude Code Max Plan 구독으로 동작합니다.

---

## Install

```bash
git clone https://github.com/ZEP-Biz/cstage ~/Projects/cstage
bash ~/Projects/cstage/install.sh
# Claude Code 재시작
```

설치 스크립트가 자동으로:
- Python 의존성 설치 (uv)
- MCP 서버 등록 (~/.claude/.mcp.json)
- 필요 MCP 체크 (Tavily, Slack 등)

## Usage

```
cstage "매출이 정체되고 있다"
cstage "동남아 시장 진출 전략"
cstage "일본 부등교 사업 전략을 세우려고 해"
```

## Workflow (6 Steps)

```
[1] 인터뷰      참고자료 수집 → 가설 기반 소크라틱 인터뷰 (ambiguity <= 0.2까지)
[2] RFI 확인     SCR + 리서치 범위 확인
[3] 보고서 설정   형태(markdown/slide_deck) + 이해관계자 설정
[4] 중간 보고     초안 보고서 + 추가 질문
[5] 자동 개선     evaluate → evolve → stakeholder review (최대 3회)
[6] 최종 확인     승인/수정/거부
```

사용자가 하는 것: 인터뷰 답변 + 중간 승인. 나머지 자동.

## Architecture (host-driven dispatch — ouroboros v0.44 contract)

```
MCP Server = state management + payload building + validation gates
  ↕ tool responses carry meta.host_action=spawn_subagents + payload arrays
  ↕ Claude Code (the host) spawns subagents, does ALL LLM work,
    folds structured results back via work_results
  ↕ No API key, no server-side subprocess (CSTAGE_DISPATCH=internal for legacy)
```

Quality is code-enforced, not model-promised:
- 인터뷰 완료 = 점수 게이트 + 컴포넌트 floor + 연속 2라운드 + ledger 구조 완결
- deterministic floor가 LLM의 낙관 점수를 코드로 교정
- 보고서 승인 = verify-by-default 게이트 (기준 미달이면 모델이 승인 불가)
- 이해관계자 리뷰에 adversarial probe 9종, 트리거 시 ADVOCATE/DEVIL/JUDGE 심의

### Core Modules

| Module | Purpose |
|--------|---------|
| `bigbang/` | Socratic interview, ambiguity scoring, consulting ledger |
| `dispatch/` | Host-driven work payloads (SubagentPayload, fold-back contracts) |
| `verification/` | Typed verdicts, adversarial probes, report criteria gate |
| `core/` | SCR builder, RFI generator, LLM adapter, model pins |
| `frameworks/` | Porter, SWOT, BCG, McKinsey 7S |
| `data/` | Deep research planner, Tavily client, MCP adapters |
| `report/` | Storyline report models, prompts, renderer |
| `evaluate/` | 3-stage evaluation pipeline |
| `evolve/` | Wonder/reflect/convergence loop |
| `ralph/` | Stakeholder review, Slack interviews |
| `agents/` | Persona prompts (strategy-consultant, deep-researcher, etc.) |

## Report Format

McKinsey consulting deck structure:

```
Executive Summary (SCR)
  Situation → Complication → Resolution
Chapter 1 — Head message (one governing sentence)
  Sub-point ← backup data [확인됨/추정/가설]
  Sub-point ← backup data
Chapter 2 — Head message
  ...
Sensitivity Analysis — base/upside/downside scenarios
Action Items — human-required vs AI-completed
Implementation Roadmap — Week 1-2 through Month 7-12
```

## MCP Tools

| Tool | Description |
|------|-------------|
| `start_consulting` | Start session (with reference_materials, stakeholders) |
| `submit_interview_answer` | Answer Socratic question |
| `complete_interview` | Generate SCR + RFI (ambiguity gate: <= 0.2) |
| `align_seed` | Approve analysis plan |
| `plan_collection` | Get deep research plan (5-10 queries/RFI) |
| `inject_collection` | Inject research results |
| `run_analysis` | Execute frameworks + generate report |
| `get_report` | Retrieve report (markdown/slide_deck) |
| `run_stakeholder_review` | 5-stakeholder evaluation |
| `confirm_report` | Approve/revise/reject |
| `suggest_slack_interviews` | Suggest people to interview via Slack |
| `send_slack_interview` | Send interview DM |
| `check_slack_responses` | Check Slack interview responses |

## Configuration

```bash
# Required
# (none — uses Claude Code Max Plan)

# Optional
export TAVILY_API_KEY="tvly-..."    # External research (recommended)
export CSTAGE_REPORT_FORMAT="markdown"  # markdown | slide_deck
export CSTAGE_LOG_LEVEL="INFO"
```

## Development

```bash
uv run pytest tests/ -q                            # Run tests (5,300+)
uv run cstage-server                               # Start MCP server locally
uv run python scripts/e2e_host_driven_driver.py    # 39-check full-pipeline E2E
uv run python scripts/benchmark_gates.py .         # Gate defense benchmark
```

## Update

```bash
cd ~/Projects/cstage && git pull && uv sync
# Claude Code 재시작
```

---

*Forked from [Ouroboros](https://github.com/Q00/ouroboros) — ouroboros C pattern*
