112 lines
5 KiB
Markdown
112 lines
5 KiB
Markdown
|
# Plugin Architecture & Execution Order
|
||
|
|
|
||
|
|
## Lifecycle
|
||
|
|
|
||
|
|
1. **SessionStart hook** — initializes Codex session state
|
||
|
|
2. **User triggers** `/codeflash-optimize start` (skill)
|
||
|
|
3. **Router agent** (`codeflash`) — reads project context, asks user questions, launches setup
|
||
|
|
4. **Setup agent** (`codeflash-setup`) — detects env, installs deps/profilers, writes `.codeflash/setup.md`
|
||
|
|
5. **Router validates** setup, runs test suite, researches deps via context7
|
||
|
|
6. **Router creates team** and dispatches optimizer agent
|
||
|
|
|
||
|
|
## Optimization Loop
|
||
|
|
|
||
|
|
7. **Optimizer** (`codeflash-deep` or domain-specific: `-cpu`, `-memory`, `-async`, `-structure`) — profiles all dimensions, ranks targets
|
||
|
|
8. **Researcher** (`codeflash-researcher`) — launched alongside to analyze targets in parallel, sends findings back to optimizer
|
||
|
|
9. **Experiment cycle**: profile → reason → implement → test → benchmark → keep/discard → commit → re-profile → repeat
|
||
|
|
10. **Plateau detection** (3+ consecutive discards) → optimizer sends `[complete]`
|
||
|
|
|
||
|
|
## Review Gate
|
||
|
|
|
||
|
|
11. **Review agent** (`codeflash-review`) — 6-pass deep review (comprehension → correctness → safety → benchmark verification → quality → disclosure)
|
||
|
|
12. Writes `.codeflash/review-report.md` with verdict (APPROVE/REQUEST CHANGES/BLOCK)
|
||
|
|
|
||
|
|
## Cleanup
|
||
|
|
|
||
|
|
13. Router shuts down teammates, deletes team
|
||
|
|
14. Preserves `learnings.md`, `results.tsv`, `changelog.md`; deletes temp files
|
||
|
|
15. **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
|
||
|
|
|
||
|
|
### Base (`plugin/agents/`)
|
||
|
|
|
||
|
|
| Agent | Role | Triggered by |
|
||
|
|
|-------|------|-------------|
|
||
|
|
| `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 (`languages/python/plugin/agents/`)
|
||
|
|
|
||
|
|
| Agent | Role | Triggered by |
|
||
|
|
|-------|------|-------------|
|
||
|
|
| `codeflash` | Router/team lead — orchestrates sessions | `/codeflash-optimize` skill |
|
||
|
|
| `codeflash-setup` | Environment detection & preparation | Router, before first optimization |
|
||
|
|
| `codeflash-scan` | Quick cross-domain diagnosis | `/codeflash-optimize scan` or router recon |
|
||
|
|
| `codeflash-deep` | Primary optimizer (all dimensions) | Router (default unless single-domain requested) |
|
||
|
|
| `codeflash-cpu` | CPU/runtime specialist | Router or deep agent dispatch |
|
||
|
|
| `codeflash-memory` | Memory specialist | Router or deep agent dispatch |
|
||
|
|
| `codeflash-async` | Async/concurrency specialist | Router or deep agent dispatch |
|
||
|
|
| `codeflash-structure` | Import-time/module structure specialist | Router or deep agent dispatch |
|
||
|
|
|
||
|
|
## 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 (`languages/python/plugin/skills/`)
|
||
|
|
|
||
|
|
| Skill | Purpose |
|
||
|
|
|-------|---------|
|
||
|
|
| `codeflash-optimize` | Entry point: `start\|resume\|status\|scan\|review` |
|
||
|
|
| `memray-profiling` | Advanced memory profiling utilities (used by codeflash-memory) |
|
||
|
|
|
||
|
|
## 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. Setup agent completes before domain agents start
|
||
|
|
3. Baseline profiling before any optimization experiment
|
||
|
|
4. Re-profiling after every KEEP to update rankings
|
||
|
|
5. Review gate runs after optimizer `[complete]`, before cleanup
|
||
|
|
6. 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) + `languages/python/plugin/` (overlay) into `dist/`. Agent files use `${CLAUDE_PLUGIN_ROOT}` for references — paths differ between source and assembled output.
|