codeflash-agent/plugin/ARCHITECTURE.md

# Plugin Architecture & Execution Order

## Lifecycle

1. **SessionStart hook** — initializes Codex session state
2. **User triggers** `/codeflash-optimize start` (skill)
3. **Language router** (`codeflash`) — detects project language, delegates to language-specific router
4. **Language-specific router** (e.g., `codeflash-python`) — detects domain, asks user questions, launches setup
5. **Setup agent** (e.g., `codeflash-setup`) — detects env, installs deps/profilers, writes `.codeflash/setup.md`
6. **Router validates** setup, runs test suite, researches deps via context7
7. **Router creates team** and dispatches optimizer agent

## Optimization Loop

8. **Optimizer** (`codeflash-deep` or domain-specific: `-cpu`, `-memory`, `-async`, `-structure`) — profiles all dimensions, ranks targets
9. **Researcher** (`codeflash-researcher`) — launched alongside to analyze targets in parallel, sends findings back to optimizer
10. **Experiment cycle**: profile → reason → implement → test → benchmark → keep/discard → commit → re-profile → repeat
11. **Plateau detection** (3+ consecutive discards) → optimizer sends `[complete]`

## Review Gate

12. **Review agent** (`codeflash-review`) — 6-pass deep review (comprehension → correctness → safety → benchmark verification → quality → disclosure)
13. Writes `.codeflash/review-report.md` with verdict (APPROVE/REQUEST CHANGES/BLOCK)

## Cleanup

14. Router shuts down teammates, deletes team
15. Preserves `learnings.md`, `results.tsv`, `changelog.md`; deletes temp files
16. **SessionEnd hook** — finalizes Codex session

## Hooks

Defined in `plugin/hooks/hooks.json`, fire at session boundaries:

| Hook | When | What |
|------|------|------|
| **SessionStart** | New Claude session begins | Initializes Codex session state, records metadata |
| **SessionEnd** | Session ends | Cleans up Codex jobs, saves final state |
| **Stop** | User clicks Stop (900s timeout) | Optionally runs Codex adversarial review gate before allowing termination |

## Agents

### Language-agnostic (`plugin/agents/`)

| Agent | Role | Triggered by |
|-------|------|-------------|
| `codeflash` | Language router — detects language, delegates to language-specific router | `/codeflash-optimize` skill, user request |
| `codeflash-researcher` | Read-only research teammate | Domain agents, after baseline profiling |
| `codeflash-review` | Independent 6-pass deep review | `/codex-review`, post-optimization gate |

### Python-specific (`plugin/languages/python/agents/`)

| Agent | Role | Triggered by |
|-------|------|-------------|
| `codeflash-python` | Python domain router/team lead — orchestrates Python sessions | Language router after detecting Python |
| `codeflash-setup` | Environment detection & preparation | Python router, before first optimization |
| `codeflash-scan` | Quick cross-domain diagnosis | `/codeflash-optimize scan` or router recon |
| `codeflash-deep` | Primary optimizer (all dimensions) | Python router (default unless single-domain requested) |
| `codeflash-cpu` | CPU/runtime specialist | Python router or deep agent dispatch |
| `codeflash-memory` | Memory specialist | Python router or deep agent dispatch |
| `codeflash-async` | Async/concurrency specialist | Python router or deep agent dispatch |
| `codeflash-structure` | Import-time/module structure specialist | Python router or deep agent dispatch |
| `codeflash-ci` | CI mode agent for GitHub webhooks | CI service |
| `codeflash-pr-prep` | PR preparation agent | Post-session |

## Commands (`plugin/commands/`)

User-invocable anytime:

| Command | Purpose |
|---------|---------|
| `/codex-review` | Manual adversarial review via Codex companion |
| `/codex-setup` | Check/install Codex CLI, configure review gate |
| `/codex-status` | Check active and recent Codex jobs |

## Skills (`plugin/languages/python/skills/`)

| Skill | Purpose |
|-------|---------|
| `codeflash-optimize` | Entry point: `start\|resume\|status\|scan\|review` |
| `memray-profiling` | Advanced memory profiling utilities (used by codeflash-memory) |

## References

### Language-agnostic (`plugin/references/shared/`)

Methodology, templates, and frameworks that apply to any language:

| File | Purpose |
|------|---------|
| `agent-base-protocol.md` | Shared operational rules (experiment discipline, commit rules, stuck recovery) |
| `experiment-loop-base.md` | Shared experiment loop framework (keep/discard tree, guard, plateau) |
| `pre-submit-review.md` | Shared pre-submit checklist (resource ownership, concurrency, correctness) |
| `e2e-benchmarks.md` | Two-phase measurement concept (micro-benchmark → E2E) |
| `micro-benchmark.md` | A/B pre-screen pattern |
| `pr-body-templates.md` | Generic PR body structure and writing guidelines |
| `pr-preparation.md` | PR workflow (inventory, folding, conventions) |
| `adversarial-review.md` | Codex adversarial review methodology |
| `changelog-template.md` | Changelog generation structure |
| `handoff-template.md` | HANDOFF.md template |
| `learnings-template.md` | Cross-session learnings template |

### Python-specific (`plugin/languages/python/references/`)

Python implementations of shared protocols, plus domain-specific deep-dive docs:

| File/Dir | Purpose |
|----------|---------|
| `agent-base-protocol.md` | Python profilers (cProfile, tracemalloc, memray), test runners, package managers |
| `e2e-benchmarks.md` | `codeflash compare` usage, pytest-benchmark, fallback tools |
| `micro-benchmark.md` | Python A/B template (timeit, memray, asyncio), domain thresholds |
| `pre-submit-review.md` | Python checks (asyncio, .pyc, os.environ, monkey-patching) |
| `pr-body-templates.md` | Python PR variants (codeflash compare output, memray memory table) |
| `unified-profiling-script.py` | CPU+memory+GC profiling script for deep agent |
| `library-replacement.md` | Library boundary breaking guide |
| `async/` | Async domain: asyncio patterns, blocking detection, concurrency |
| `data-structures/` | CPU domain: containers, algorithms, bytecode, stdlib |
| `memory/` | Memory domain: tracemalloc, memray, leak detection, framework leaks |
| `structure/` | Structure domain: import time, module decomposition, circular deps |

## State Files

Created during execution in `.codeflash/`:

| File | Created by | Purpose |
|------|-----------|---------|
| `setup.md` | codeflash-setup | Environment summary |
| `scan-report.md` | codeflash-scan | Ranked targets + domain recommendations |
| `results.tsv` | optimizer agents | Experiment log (baseline, speedup, keep/discard) |
| `HANDOFF.md` | optimizer agents | Session state for resume |
| `conventions.md` | router | Binding constraints from maintainer feedback |
| `learnings.md` | router | Cross-session discoveries |
| `review-report.md` | codeflash-review | 6-pass review findings + verdict |
| `changelog.md` | router | PR-ready optimization summary |

## Ordering Guarantees

**Sequential:**
1. SessionStart hook fires before any agent acts
2. Language detection before domain routing
3. Setup agent completes before domain agents start
4. Baseline profiling before any optimization experiment
5. Re-profiling after every KEEP to update rankings
6. Review gate runs after optimizer `[complete]`, before cleanup
7. SessionEnd hook fires as session terminates

**Parallel allowed:**
- Researcher analyzes targets #2-5 while optimizer works on target #1
- Multiple domain agents can run in separate worktrees
- Deep agent can dispatch domain agents while continuing its own profiling

## Assembly

`make build-plugin` merges `plugin/` (base, excluding `languages/`) + `plugin/languages/python/` (overlay) into `dist/`. Set `LANG=javascript` to build for JS instead. Agent files use `${CLAUDE_PLUGIN_ROOT}` for references — paths differ between source and assembled output.