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. 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.