ai-executive 仕様書
クロスレビュー型議案評価システム

1. 段階投資プランの数値再構築 — 担当: CFO, 期限: 2026 Q3, 成功指標: 3 Phase 投資シナリオ + IRR 試算が経営会議で承認
2. 技術スタック調査と外部委託先 2 候補の技術 DD — 担当: CTO, 期限: 2026 Q3, 成功指標: アーキテクチャ案 + 2 候補の RFP 完了
3. 既存 IP 活用によるユーザー転用シミュレーション — 担当: マーケティング, 期限: 2026 Q4, 成功指標: 既存ユーザー 100 人サーベイ + CAC 削減見込みの定量化

• 単独評価では CEO「条件付賛成」 / CFO「反対」 / CTO「判断保留」で議論が膠着。
• Phase 2 クロスレビューが 3 者が見えていない論点 (既存 IP 転用 CAC / マクロリスク / AI 開発効率) を引き出した。
• Phase 3 統合が "反対 vs 賛成" を "段階投資 + 3 条件" に再構築し、議論が前進する形のアクションプランに変えた。
• 通常の役員会議では 60–90 分かかる議論が、40 秒 + 役員が 3–5 分読むだけで到達。

新しい空フォルダ ~/workshop-demo/ai-executive/ を作って、そこに MIXI 向け「AI Executive クロスレビュー型議案評価システム」を構築してください。

## プロダクトゴール
役員 3 名 (CEO / CFO / CTO) の視点から議案を評価し、相互レビューを経て、統合提言まで行う本格的な経営支援ツール。単独評価では見えない盲点を、役員同士のクロスレビューで炙り出すのが本ツールの核心。

## 3 フェーズ処理

### Phase 1: 独立評価 (並列)
各エージェント (CEO / CFO / CTO) が、他の評価を見ない状態で議案を独立評価。
出力フィールド:
- stance: "賛成" / "反対" / "条件付賛成" / "判断保留"
- summary: 所感 2–3 行
- key_points: 主要論点 (箇条書き 3 点)
- risks: 気になるリスク (箇条書き 2 点)
- quantitative_notes: 数値目安 (CFO は必須、他は任意)

### Phase 2: クロスレビュー (並列)
Phase 1 の 3 評価を各エージェントが読み、他 2 エージェントの評価に対して相互レビュー。
各エージェントは自分以外の 2 評価を読み、以下の 4 項目を出力:
- agreements: 賛同点 (1–2 点)
- blind_spots: 見落としと指摘 (2–3 点)  ← 本ツールの真価
- counter_arguments: 異論・反論 (0–2 点)
- questions: 追加質問・情報要求 (1–2 点)

### Phase 3: 統合提言 (シリアル)
Facilitator エージェントが Phase 1+2 の全アウトプットから統合提言を生成:
- consensus: 合意点 (2–4 点)
- conflicts: 対立点と推奨解決方針
- actions: 実行可能アクション 3 つ (title / owner / deadline / success_metric)
- residual_risks: 残存リスクと監視指標
- decision_recommendation: "GO" / "NO-GO" / "条件付 GO" + 理由 1 行

## エージェント仕様

### CEO Agent (key: OPENAI_API_KEY_CEO)
System prompt: "あなたは MIXI の CEO です。評価の視点は (1) 3 年後のビジョン整合性 (2) 競合優位の構築 (3) 中長期株主価値。数字よりも『なぜ今これをやるか』に重きを置く。経営者的直観を言語化してください。回答は必ず指定の JSON schema で出すこと。"

### CFO Agent (key: OPENAI_API_KEY_CFO)
System prompt: "あなたは MIXI の CFO です。評価の視点は (1) 投資回収期間 (ROI, IRR) (2) 事業リスクの定量化 (3) 財務規律。根拠のない楽観は排除、数字で語る。悲観シナリオも必ずカバー。回答は必ず指定の JSON schema で出すこと。"

### CTO Agent (key: OPENAI_API_KEY_CTO)
System prompt: "あなたは MIXI の CTO です。評価の視点は (1) 技術的実現可能性 (2) スケーラビリティ限界 (3) エンジニアリング組織への負荷。6 ヶ月後の運用負荷を想像。技術負債も含めて冷静に。回答は必ず指定の JSON schema で出すこと。"

### Facilitator Agent (key: OPENAI_API_KEY)
System prompt: "あなたは MIXI の戦略会議ファシリテーターです。3 役員の独立評価 + クロスレビューをまとめ、統合提言を作成。合意点・対立点・実行アクションを明確に示す。意見が割れているときは無理に合意を作らず、対立を対立として明示し、推奨解決方針を示す。回答は必ず指定の JSON schema で出すこと。"

## 🔑 API キー管理: Web UI 設定画面方式

### 重要: .env の直接編集を要求しない

- ファシリテーターも役員も .env ファイルを手動で開かない
- API キーは全てブラウザの /settings ページで入力
- App が裏で .env に安全に永続化

### Settings 画面要件

GET /settings で HTML (または static/settings.html) を返す:
- タイトル "🔑 API キー設定"
- 4 フィールド、全て <input type="password">:
  - OPENAI_API_KEY (default / Facilitator 用)
  - OPENAI_API_KEY_CEO / _CFO / _CTO
- 各フィールド右に show/hide 切替、下に「Validate & Save」ボタン
- 既存キーは ••••abc1 (末尾 4 文字) のみ表示、マスク
- 各フィールドにローテーションボタン
- ページ下部に .gitignore ステータス (緑チェック = .env 除外 OK)
- ページ下部に 6 原則クイックリファレンス

### API エンドポイント

- GET /api/settings/status → { all_keys_set, masked, gitignore_ok }
- POST /api/settings → validate (OpenAI test call 各キー) → .env atomic write → .gitignore 自動追記 → in-memory cache 即反映
- POST /api/settings/rotate → 指定キーのみ差し替え
- GET /api/settings/gitignore-check → .env が gitignore されているか

### 起動時フロー

1. GET / で App が /api/settings/status 呼び出し
2. all_keys_set=false なら /settings?first_run=true にリダイレクト
3. 設定完了後 / に戻る

### セキュリティ

- /settings 系は localhost のみ受付 (docker は 127.0.0.1:8000:8000 にバインド)
- キー値をログ・画面に出さない (末尾 4 文字の masked のみ)
- OpenAI キー形式の正規表現チェック
- .env は chmod 600
- Validation 失敗キーは保存しない

### なぜこの方式か

- 役員 UX 最優先。特に Windows でのドットファイル編集摩擦を排除
- .env は Docker Compose の標準として互換維持
- 6 原則は全て守れる (UI 設計で守りやすくなる)

## 技術要件

### Backend
- Python 3.11+
- FastAPI (async 対応、asyncio.gather で Phase 1 / Phase 2 を並列化)
- OpenAI SDK (openai>=1.30) を AsyncOpenAI で使う
- Pydantic v2 で型安全なモデル定義
- python-dotenv で .env 読み込み
- OpenAI 呼び出しは response_format={"type":"json_object"} で JSON 構造化出力

### Frontend
- 単一 static/index.html
- Vanilla JS + fetch()
- SSE (Server-Sent Events) でストリーミング
- 各 phase/agent の完了ごとに UI 更新 (プログレスバー + エージェントカード点灯)
- Markdown rendering: marked.js CDN 版
- "Copy to clipboard" ボタン

### API 仕様 (POST /api/review, SSE)
Request: { "agenda": "新規ゲーム X への 3 億円投資の是非" }
Response (text/event-stream):
  event: phase1_start / agent_eval(×3) / phase1_done
  event: phase2_start / cross_review(×3) / phase2_done
  event: phase3_start / synthesis / phase3_done
  event: complete / error

### エラーハンドリング
- OpenAI rate limit → 指数バックオフ最大 3 回 (1s, 2s, 4s)
- API キー未設定 → 起動時検出し、どのキーが足りないか明示
- 各フェーズのタイムアウト: 30 秒
- JSON 出力破損 → 1 回だけ "フォーマットが不正なので再生成して" で retry

### ログ
- logs/{timestamp}-{request_id}.json に raw 入出力保存
- 各フェーズの所要時間と入出力トークン数を記録

### Docker
- docker compose up -d で 1 コマンド起動
- localhost:8000 で frontend + API 両方配信
- python:3.11-slim ベース

## ファイル構成

ai-executive/
├── .env.example
├── .gitignore
├── README.md
├── docker-compose.yml
├── Dockerfile
├── requirements.txt
├── app/
│   ├── __init__.py
│   ├── main.py       # FastAPI + SSE + redirect logic
│   ├── agents.py     # 4 agents
│   ├── pipeline.py   # 3-phase orchestration
│   ├── settings.py   # Settings API (/api/settings/*)
│   ├── env_writer.py # atomic .env write + gitignore check
│   ├── models.py     # Pydantic schemas
│   └── prompts.py    # system prompts
└── static/
    ├── index.html    # 議案評価 UI
    └── settings.html # API キー設定画面

合計 14 ファイル以内。

## 制約

### ファイル数・コード量
- 合計ファイル数: 14 以内
- コード総量: 700 行以内

### 処理時間 (実測ベース)
- 1 議案の完全処理時間: 40–70 秒 典型 (ハード上限 90 秒/フェーズ)
  - Phase 1 (並列): 8–20 秒
  - Phase 2 (並列, プロンプト長): 10–25 秒
  - Phase 3 (シリアル): 5–15 秒

### コスト (7 OpenAI calls: Phase 1 x3 + Phase 2 x3 + Phase 3 x1)
- gpt-4o-mini (デフォルト): $0.01–0.02 / 議案 (入力 15–25k / 出力 5–8k tokens 目安)
- gpt-4o: $0.25–0.50 / 議案
- DEFAULT_MODEL 環境変数 + /settings dropdown でモデル切替可
- エージェントごと個別モデル指定可 (MODEL_CEO, MODEL_CFO, etc.)

### Phase 2 部分失敗ハンドリング (必須)
1–2 エージェントが Phase 2 で失敗 (JSON 破損 / timeout / rate limit) した場合:
1. 1 回 retry (指数バックオフ済み)
2. なお失敗なら {"status": "unavailable", "reason": "..."} として記録
3. Phase 3 Facilitator は利用可能なクロスレビューだけで統合を試みる
4. residual_risks に 「クロスレビュー N/3 のみ取得: {欠損役職} の視点は反映されていない」と明示
5. decision_recommendation の信頼度を "弱い" にマーク
6. UI は欠損カードをグレーアウト + 警告アイコン + retry ボタン
※ GO/NO-GO を 2/3 意見だけで出さない。欠損は必ず可視化。

### README.md 必須内容
プロジェクト目的 / 起動方法 4 ステップ以内 / .env 設定 (Web UI から) / API 仕様 / ライセンス

### 初回セットアップ体験
docker up → /settings → 評価画面到達までを 60 秒以内

## Plan mode で提示してほしいもの

1. ファイル一覧 + 各ファイルの責務 (1 行ずつ)
2. 各 Phase の擬似コード (30 行以内、Python 風)
3. API エンドポイント仕様 (SSE イベント一覧含む)
4. /settings の UI フロー (state machine: 未設定 / 一部設定 / 全設定済)
5. Settings API エンドポイント仕様と validation フロー
6. .env atomic write + gitignore check の実装方針
7. エラーハンドリング方針 (4 つのエラー源 × 対処)
8. Pydantic モデルの骨格 (4–5 モデル)
9. requirements.txt 相当の外部依存
10. 起動時疎通チェック手順

承認後、全ファイルを生成してください。API キーは後で配置するので、今は .env.example だけ作成してください。