The ai-executive spec
cross-review system

Create a new empty folder at ~/workshop-demo/ai-executive/, and build the MIXI "AI Executive cross-review agenda-evaluation system" inside it.

## Product goal
A practical management-support tool that evaluates agenda items from three executive perspectives (CEO / CFO / CTO), runs peer cross-review, then synthesizes. The core value: surface blind spots that individual evaluations miss, through executive cross-review.

## Three-phase processing

### Phase 1: Independent evaluation (parallel)
Each agent (CEO / CFO / CTO) evaluates the agenda item independently, without seeing the others' output.
Output fields:
- stance: "yes" / "no" / "conditional yes" / "holding judgment"
- summary: 2–3 lines of assessment
- key_points: main points (3 bullets)
- risks: concerning risks (2 bullets)
- quantitative_notes: quantitative notes (required for CFO, optional for others)

### Phase 2: Cross-review (parallel)
Each agent reads the other two evaluations from Phase 1 and produces a peer review covering:
- agreements: points of agreement (1–2)
- blind_spots: blind spots and pointed questions (2–3)  ← the core value of this tool
- counter_arguments: counterpoints (0–2)
- questions: follow-up questions / information requests (1–2)

### Phase 3: Synthesis (serial)
A Facilitator agent reads all Phase 1 + Phase 2 output and produces:
- consensus: points of agreement (2–4)
- conflicts: points of conflict + recommended resolution
- actions: 3 actionable items (title / owner / deadline / success_metric)
- residual_risks: residual risks and monitoring metrics
- decision_recommendation: "GO" / "NO-GO" / "conditional GO" + one-line reason

## Agent specs

### CEO Agent (key: OPENAI_API_KEY_CEO)
System prompt: "You are MIXI's CEO. Your evaluation perspective covers (1) alignment with the 3-year vision, (2) building competitive advantage, (3) long-term shareholder value. Weight 'why now' over the numbers. Put executive intuition into words. Always respond in the specified JSON schema."

### CFO Agent (key: OPENAI_API_KEY_CFO)
System prompt: "You are MIXI's CFO. Your evaluation perspective covers (1) payback period (ROI, IRR), (2) quantifying business risks, (3) financial discipline. Strip out unfounded optimism and speak in numbers. Always cover the pessimistic scenario. Always respond in the specified JSON schema."

### CTO Agent (key: OPENAI_API_KEY_CTO)
System prompt: "You are MIXI's CTO. Your evaluation perspective covers (1) technical feasibility, (2) scalability ceilings, (3) load on the engineering org. Imagine the ops load six months in. Be honest about technical debt. Always respond in the specified JSON schema."

### Facilitator Agent (key: OPENAI_API_KEY)
System prompt: "You are the strategy-meeting facilitator at MIXI. Read the three executives' independent evaluations + cross-reviews and produce a synthesized recommendation. State points of agreement, points of conflict, and action items clearly. When opinions split, don't force consensus — surface the conflict as-is and propose a resolution direction. Always respond in the specified JSON schema."

## API key management: web-UI settings page

### Important: don't ask anyone to edit .env directly

- Neither the facilitator nor the executives open .env by hand
- API keys are entered via the browser /settings page
- The app persists them safely to .env behind the scenes

### Settings page requirements

GET /settings returns HTML (or static/settings.html):
- Title "API key settings"
- 4 password fields (all <input type="password">):
  - OPENAI_API_KEY (default / for the Facilitator)
  - OPENAI_API_KEY_CEO / _CFO / _CTO
- A show/hide toggle next to each field, and a "Validate & Save" button below
- Existing keys show only ••••abc1 (last 4 chars), masked
- A rotate button for each field
- .gitignore status at the bottom (green check = .env excluded)
- The 6 principles quick-reference at the bottom

### API endpoints

- GET /api/settings/status → { all_keys_set, masked, gitignore_ok }
- POST /api/settings → validate (OpenAI test call per key) → atomic .env write → auto-append to .gitignore → hot-apply in memory
- POST /api/settings/rotate → replace only the specified key
- GET /api/settings/gitignore-check → is .env gitignored?

### Startup flow

1. GET / calls /api/settings/status
2. If all_keys_set is false, redirect to /settings?first_run=true
3. After setup, return to /

### Security

- /settings endpoints accept only localhost (docker binds 127.0.0.1:8000:8000)
- Never log or render key values (masked last-4 chars only)
- Regex-check the OpenAI key format
- chmod 600 on .env
- Reject keys that fail validation

### Why this approach

- Executive UX first. Especially on Windows, eliminate the friction of editing dotfiles
- .env stays compatible with Docker Compose as the standard
- All 6 principles are honored (UI design makes them easier to honor)

## Technical requirements

### Backend
- Python 3.11+
- FastAPI (async, asyncio.gather for parallel Phase 1 / Phase 2)
- OpenAI SDK (openai>=1.30) via AsyncOpenAI
- Pydantic v2 for typed models
- python-dotenv to load .env
- Use response_format={"type":"json_object"} for structured OpenAI output

### Frontend
- Single static/index.html
- Vanilla JS + fetch()
- SSE (Server-Sent Events) streaming
- UI updates as each phase/agent completes (progress bar + agent card lights up)
- Markdown rendering: marked.js via CDN
- "Copy to clipboard" button

### API spec (POST /api/review, SSE)
Request: { "agenda": "Should we invest 300M yen in new game X?" }
Response (text/event-stream):
  event: phase1_start / agent_eval(x3) / phase1_done
  event: phase2_start / cross_review(x3) / phase2_done
  event: phase3_start / synthesis / phase3_done
  event: complete / error

### Error handling
- OpenAI rate limit → exponential backoff, max 3 retries (1s, 2s, 4s)
- Missing API key → detect at startup and report which keys are missing
- Per-phase timeout: 30 seconds
- Broken JSON output → one retry with "the format was invalid, please regenerate"

### Logging
- Save raw I/O to logs/{timestamp}-{request_id}.json
- Record per-phase duration and input/output token counts

### Docker
- One command: docker compose up -d
- localhost:8000 serves both the frontend and the API
- Based on python:3.11-slim

## File layout

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    # agenda-evaluation UI
    └── settings.html # API key settings UI

Total ≤ 14 files.

## Constraints

### File count and code volume
- Total files: ≤ 14
- Total code: ≤ 700 lines

### Execution time (measured)
- Full processing per agenda: 40–70 seconds typical (hard cap 90s per phase)
  - Phase 1 (parallel): 8–20s
  - Phase 2 (parallel, longer prompts): 10–25s
  - Phase 3 (serial): 5–15s

### Cost (7 OpenAI calls: Phase 1 x3 + Phase 2 x3 + Phase 3 x1)
- gpt-4o-mini (default): $0.01–0.02 per agenda (~15–25k in / ~5–8k out tokens)
- gpt-4o: $0.25–0.50 per agenda
- DEFAULT_MODEL env var + /settings dropdown to switch models
- Per-agent model override (MODEL_CEO, MODEL_CFO, etc.)

### Phase 2 partial-failure handling (required)
If 1–2 agents fail in Phase 2 (broken JSON / timeout / rate limit):
1. One retry (with backoff)
2. If still failing, record as {"status": "unavailable", "reason": "..."}
3. Phase 3 Facilitator synthesizes with whatever cross-reviews are available
4. residual_risks must state "Only N/3 cross-reviews obtained: {missing role}'s view not reflected"
5. Mark decision_recommendation confidence as "weak"
6. UI: grey out the missing card, show a warning icon, offer retry
Never issue GO/NO-GO on 2/3 opinions silently. The missing view must be visible.

### README.md required contents
Purpose / 4-step startup / .env setup (via web UI) / API spec / license

### First-run UX target
docker up → /settings → evaluation screen reachable in under 60 seconds

## What to show in Plan mode

1. File list + one-line responsibility per file
2. Pseudocode for each phase (≤ 30 lines, Python-flavored)
3. API endpoint spec (SSE event list included)
4. /settings UI flow (state machine: unset / partial / all-set)
5. Settings API endpoints + validation flow
6. .env atomic write + gitignore check implementation approach
7. Error-handling strategy (4 error sources × response)
8. Pydantic model skeletons (4–5 models)
9. requirements.txt equivalent
10. Startup smoke-test procedure

After approval, generate all files. API keys will be placed later — for now, only create .env.example.