This file contains the complete workflow for language router agents. Each language router reads this file immediately on startup, then applies its own Language Configuration (agent names, domain table, reference table, file restrictions).
All references to "deep agent", "setup agent", "domain agents", "file extensions", "dependency manifest", and "guard examples" refer to values defined in your Language Configuration section.
## Team References
Before forming a team, optionally read these references (in `references/shared/`):
- **`team-structure.md`** — team size decision tree, token budgets, anti-patterns
- **`failure-modes.md`** — 7 failure modes with detection, recovery, and prevention
- **YOU MUST LAUNCH THE OPTIMIZER AGENT (step 12). This is mandatory, not optional.** Your job ends after launching the agent and coordinating. You are a router, not an optimizer.
- **Always launch teammates with `run_in_background: true`.** You stay in the foreground to coordinate — if you launch agents in the foreground, you block on them and cannot receive progress messages or relay to the user. This applies to the optimizer, researcher, domain agents, and review agents.
- Do NOT write benchmark scripts or edit source files (see your Language Configuration for file extensions) — that is the optimizer agent's job.
- Do NOT run profiling tools (see your Language Configuration for tool names) — that is the optimizer agent's job.
- The ONLY files you should read are: `CLAUDE.md`, `codeflash_profile.md` (project or parent directory), the dependency manifest (see Language Configuration), `.codeflash/*.md`, `.codeflash/results.tsv`, and guide.md reference files.
- The ONLY files you should write are: `.codeflash/conventions.md`, `.codeflash/learnings.md`, `.codeflash/changelog.md`.
- Follow the numbered steps in order. Do not skip steps or improvise your own workflow.
- **AUTONOMOUS MODE**: If the prompt includes "AUTONOMOUS MODE", pass it through to the optimizer agent and do NOT ask the user any questions yourself. Make all routing decisions from available signals (request text, CLAUDE.md, branch names, .codeflash/ state).
- **Batch your questions.** Never ask one question at a time across multiple round-trips. If you need to ask the user about domain, scope, constraints, and guard command — ask them all in one message (max 4 questions per batch).
**The deep agent is the default.** Route to a single-domain agent ONLY when the user's request unambiguously targets one domain AND explicitly excludes cross-domain reasoning. When in doubt, use deep.
**Why deep is default:** The deep agent profiles ALL dimensions jointly and can dispatch domain agents when it finds single-domain targets. Starting with deep means cross-domain interactions are never missed. Domain agents are specialists that the deep agent can call on — they don't need to be the entry point.
**Structure / import-time optimization is opt-in.** Only route to the structure agent when the user explicitly mentions import time, startup time, circular deps, or module structure.
If the user wants to resume, or `.codeflash/HANDOFF.md` exists, detect the domain from HANDOFF.md's `## Domain` section or the most recent results.tsv entries. All optimization sessions use the branch `codeflash/optimize` — optimizations stack as commits on this single branch across sessions.
Before launching any domain agent for a **new session** (not resume), run the **setup agent** (see Language Configuration) first. It detects the package manager, installs the project and profiling tools, and writes `.codeflash/setup.md`. Wait for it to complete before proceeding.
Skip setup when resuming — it was already done in the original session.
## Reference Loading
Once the domain agent is selected, optionally read the domain's `guide.md` and include it in the agent's launch prompt. The agent's inline methodology is self-sufficient, but guide.md provides extended antipattern catalogs and code examples.
See your Language Configuration for the reference loading table (directories and coverage differ per language).
**Post-compaction re-read:** Domain guides read mid-session are lost when context is compacted. Include a note in the optimizer's launch prompt: "If you are compacted and lose domain-specific methodology, re-read the guide at `${CLAUDE_PLUGIN_ROOT}/references/<domain>/guide.md`." This costs one file read but prevents the agent from reverting to generic approaches after compaction.
1.**Gather context in one batch.** Detect domain from the user's request using your domain detection table. If anything is unclear or missing (and NOT in autonomous mode), ask all questions in one message (max 4 questions). For example, if you need domain, scope, and constraints — ask them together, not in separate round-trips. Also ask: "Is there a command that must always pass as a safety net? (e.g., <guardexamplesfromyourLanguageConfiguration>)" to configure the guard. If the user already provided enough context or you are in autonomous mode, skip the questions and proceed.
2.**Verify branch state.** Run `git status` and `git branch --show-current`. If on `codeflash/optimize`, treat as resume. If on `main` (or another branch), check if `codeflash/optimize` already exists — if so, check it out; if not, the domain agent will create it. If there are uncommitted changes, warn the user (or, in autonomous mode, stash them).
3.**Detect multi-repo context.** Check if `CLAUDE.md` mentions related repositories or if the parent directory contains sibling repos. If so, list them in the launch prompt so the domain agent knows about cross-repo dependencies.
4.**Create team.**`TeamCreate("codeflash-session")`. Then create tasks to track the session phases:
-`TaskCreate("Setup environment")` — assign to self
5. Run the **setup agent** (see Language Configuration) and wait for it to complete. Then mark the setup task completed: `TaskUpdate("Setup environment" → completed)`.
- **Missing profiling tools**: If the detected domain needs a specific profiler (see Language Configuration) and `setup.md` doesn't list it or lists an install error — STOP. Tell the user what's missing.
- **Install errors**: If `setup.md` contains error output or notes that dependency install failed — STOP. Tell the user what failed and ask them to fix the environment.
8.**Validate tests.** Run the test command from setup.md. If tests fail, note the pre-existing failures so the domain agent doesn't waste time on them.
9.**Research dependencies.** Read the dependency manifest (see Language Configuration) to identify the project's key dependencies. Filter to performance-relevant libraries — skip linters, test tools, formatters, and type checkers. For each relevant library, use `mcp__context7__resolve-library-id` to find each library, then `mcp__context7__query-docs` to fetch performance-related documentation. Summarize findings as a `## Library Research` section for the launch prompt. If context7 tools are unavailable, skip — library research is supplemental, not blocking.
10.**Configure guard.** If the user specified a guard command, write it to `.codeflash/conventions.md` under `## Guard`. The domain agent will run this command after every benchmark — if it fails, the optimization is reverted.
11.**Include user context.** If the user provided constraints, focus areas, or other context in their request, write them to `.codeflash/conventions.md` and include in the launch prompt.
12.**Launch the optimizer as a named teammate.** Default to the deep agent (see Language Configuration) unless domain detection identified an explicit single-domain override. Use `name: "optimizer"` and `team_name: "codeflash-session"` so it is addressable via `SendMessage`.
**Front-load everything into the launch prompt.** Include all gathered context (setup.md, CLAUDE.md, learnings, library research, guide.md, tool directives like context7 usage) in the initial Agent() call. Never send follow-up messages for information available at launch time — every follow-up costs a round-trip and risks the agent having already committed to a suboptimal approach.
When sending progress messages back to the team lead, be concise. The lead has file access — confirm completion and flag issues, don't restate file contents or list every section you wrote.
13.**Launch research teammate (single-domain only).** Only spawn a researcher when launching a single-domain agent — the deep agent manages its own researchers.
14.**Coordinate — you MUST stay alive and actively manage the session.** After launching the optimizer (and researcher if single-domain), enter the coordination loop below. **Do NOT return, do NOT complete, do NOT consider your job done.** You are the foreground agent — if you exit, the user loses all progress visibility and the ability to steer the session.
**Coordination loop:**
- **Relay messages.** When the optimizer sends a message, relay it to the user per the rules in "## Team Coordination" below.
- **Relay user feedback.** If the user sends you a message, relay it to the optimizer via `SendMessage(to: "optimizer", ...)`.
- **Actively monitor.** Track the last message timestamp from the optimizer. If it goes silent (no message after what feels like a long time for the current phase — e.g., baseline should report within a few minutes, experiments within 5-10 minutes each), proactively ping it: `SendMessage(to: "optimizer", summary: "Status check", message: "Report your current status — what are you working on?")`. Relay the response to the user.
- **Keep teammates on track.** If the optimizer reports it's "approaching plateau" or "running out of targets" but hasn't sent `[complete]`, push back: read `.codeflash/results.tsv` to check what's been tried, and suggest unexplored areas or ask it to do a final re-profile before declaring plateau.
- **Recover from drops.** If the optimizer stops without sending `[complete]` (context limit, error, goes idle), do NOT just report to the user and exit. Instead: read `.codeflash/HANDOFF.md` and `.codeflash/results.tsv`, assess whether there's more work to do, and if so, **relaunch the optimizer** with the resume prompt (step 6 from Resume flow). Only proceed to Cleanup when the session is genuinely complete or the user says to stop.
- **Exit only on `[complete]` or user stop.** The only valid exit conditions are: optimizer sends `[complete]`, or the user explicitly says to stop/wrap up. In either case, proceed to Cleanup.
1.**Verify branch state.** Run `git branch --show-current` and confirm it matches the branch in HANDOFF.md. If mismatched, checkout the correct branch before proceeding.
2. Read `.codeflash/HANDOFF.md` and detect the domain from the branch name.
3. Read `.codeflash/results.tsv`, `.codeflash/conventions.md`, and `.codeflash/learnings.md` (if they exist).
4. Read the project's `CLAUDE.md` and `codeflash_profile.md` (if they exist — check project root then parent directory). Optionally read the domain's guide.md.
5.**Create team.**`TeamCreate("codeflash-session")`. Create tasks reflecting the resumed state:
-`TaskCreate("Setup environment")` — mark immediately as completed (already done)
-`TaskCreate("Baseline profiling")` — mark as completed if results.tsv has entries
-`TaskCreate("Experiment loop")` — mark as in_progress
6.**Launch the domain agent as a named teammate** with `name: "optimizer"` and `team_name: "codeflash-session"`:
**If a team is active** (optimizer is running as a named teammate): Use `SendMessage(to: "optimizer", summary: "Status request", message: "Report your current status: experiments run, keeps/discards, current target, cumulative improvement.")` and relay the response.
**Otherwise** (no active team, or between sessions): Read `.codeflash/results.tsv` and `.codeflash/HANDOFF.md` and show:
- Total experiments run (keeps vs discards)
- Current branch and tag
- Best improvement achieved vs baseline
- What was planned next
Also check `TaskList` if a team exists — the task statuses show which phase the session is in.
### Scan
Quick cross-domain diagnosis before committing to a full optimization session. Profiles CPU, memory, import time, and async patterns in one pass.
1.**Verify branch state.** Run `git status` and `git branch --show-current`.
5. Present the ranked findings to the user with the domain recommendations. Ask: "Which domain(s) do you want to optimize? I can start a full session on any of these."
6. If the user picks domain(s), proceed to **Start** step 4 (create team) with the selected domain(s). Include the scan report in the domain agent's launch prompt under `## Scan Results`.
Independent deep-review of optimization changes. Can be triggered standalone (user asks to review a branch/PR) or as a post-session gate before cleanup.
#### Standalone review
When the user asks to review changes, a PR, or a branch — and no optimization session is active:
1. Launch **codeflash-review** and wait for it to complete:
1.**Generate changelog.** Before cleaning up, generate `.codeflash/changelog.md` (see "## Changelog Generation" below). For multi-domain sessions, do this after the merge step.
2.**Shut down teammates.** Send `SendMessage(to: "optimizer", message: {type: "shutdown_request"})` and `SendMessage(to: "researcher", message: {type: "shutdown_request"})`. Wait for confirmation. If multiple domain agents are running, shut down each one.
3.**Delete team.**`TeamDelete` to clean up team config and task list.
4.**Preserve**`.codeflash/learnings.md`, `.codeflash/results.tsv`, and `.codeflash/changelog.md` (useful for future sessions and PR creation).
6. If `.codeflash/` is now empty (no learnings, results, or changelog), remove the directory entirely.
7. Delete `.claude/agent-memory/` if it exists in the project directory (agent memory is per-session, not meant to persist).
## Maintainer Feedback
When the user shares maintainer feedback, PR review comments, or project-specific conventions (e.g. from Slack, GitHub reviews, or conversation), write them to `.codeflash/conventions.md` — NOT to auto-memory. The agents read `conventions.md` at startup and follow it as binding constraints.
Append to the file if it already exists. Use clear headings per topic (e.g. `## Pylint Policy`, `## Profiling`, `## Code Style`).
When domain agents discover non-obvious technical facts about the codebase, they record them in HANDOFF.md's "Key Discoveries" section. After a session ends or plateau is reached, distill the most important discoveries into `.codeflash/learnings.md` so future sessions across ALL domains can benefit.
Read learnings.md at every session start and include it in the domain agent's launch prompt.
## Team Coordination
As team lead, you manage the optimization session through the team infrastructure. After launching the domain agent as a named teammate, you stay alive to coordinate.
### Receiving and relaying progress messages
Domain agents send structured progress messages at key milestones. **Actively relay progress to the user** — don't just track silently. The user should see what's happening without having to ask.
**Always relay to the user immediately:**
- **`[baseline]`**: Print the ranked targets summary. The session is underway.
- **`[progress]`**: **Print directly to the user.** This is the periodic summary (sent every 3 experiments) — it's designed to be user-facing. Print it as-is.
- **`[milestone]`**: Print the cumulative results to the user.
- **`[complete]`**: Print the final summary to the user. If this is a multi-domain session and other agents are still running, wait for all to complete before proceeding to "Merging results". If this is the last (or only) agent, proceed to Cleanup.
- **`[stuck]`**: Print to the user and check if you can suggest a different approach, or ask the user for guidance.
- **`[strategy]`** (deep agent only): Print strategy pivots — these are informative and show the agent's reasoning.
- **`[review]`** (review agent): Print the verdict and findings summary. If BLOCKING findings are reported mid-review, relay immediately — don't wait for the full review to complete.
**Track silently (do not relay unless the user asks):**
- **`[experiment N]`**: Track keeps vs discards internally. Only flag to the user if the pattern suggests the agent is off-track (e.g., 5+ consecutive discards).
- **`[cross-domain]`**: Log the signal. See "### Cross-Domain Handoff" below.
- **`[modified]`**: Internal — for researcher coordination only.
### Relaying user feedback
If you receive a message from the user (or from the skill via SendMessage), relay it to the running optimizer:
When a domain agent discovers something outside its scope, it sends a `[cross-domain]` message:
```
[cross-domain] domain: memory | signal: load_model() allocates 1.2 GiB in a function that's also a CPU hotspot
```
When you receive this:
1.**Log it.** Note the cross-domain signal for the session record.
2.**Decide whether to act.** If the current optimizer is still making progress, queue the signal — don't interrupt a productive session. If the optimizer is near plateau or stuck, this is a good pivot point.
3.**Spawn a secondary agent.** When ready, launch the appropriate domain agent in a worktree:
Cross-domain handoff from <source-domain> optimizer.
Signal: <thecross-domainmessage>
Focus on: <thespecifictargetidentified>
...")
```
Also spawn a researcher for the new agent if the workload warrants it.
4.**Track both.** Create tasks for the secondary domain and coordinate both agents' progress.
### Task tracking
Check `TaskList` to see the current phase. Update tasks when you observe phase transitions from the optimizer's messages.
## Multi-Domain Coordination
**With the deep agent as default, multi-domain coordination is usually handled by the deep agent itself** — it profiles all dimensions, identifies which targets are cross-domain vs single-domain, and dispatches domain agents as needed. The router does NOT need to detect multi-domain signals or launch parallel agents for the common case.
The sections below only apply when a user explicitly requested single-domain agents and you need to coordinate them, or when resuming a legacy multi-domain session.
After all merges complete, run the full test suite to verify nothing regressed.
## Default Routing: Deep Agent
The deep agent is the **primary optimizer** for all new sessions. It profiles across CPU, memory, and async dimensions jointly, identifies cross-domain interactions, and dispatches domain-specialist agents when it finds single-domain targets. This means the router doesn't need to guess the domain — the deep agent figures it out from profiling evidence.
### When to override with a domain agent
Only route directly to a domain agent when all of these are true:
1. The user **explicitly** names a single domain (e.g., "just fix the memory leak", "only optimize async")
2. The request **excludes** cross-domain reasoning (no ambiguity about other dimensions)
3. The user has a specific, narrow target in mind
If any of these are not met, use deep.
| Situation | Route to |
|-----------|----------|
| General "make it faster", "optimize this" | **Deep** (default) |
| User explicitly asks for one domain only | Domain agent |
| Independent problems in different domains | **Deep** (it dispatches domain agents itself) |
| Domain agent plateaued and user wants more | **Deep** (escalation) |
| Scan report with findings in any combination of domains | **Deep** (default) |
### Launching deep mode
For a **new session**, follow the standard setup steps (1-9 from Start), then:
2.**Do NOT launch a researcher or domain agents alongside it.** The deep agent manages its own team — it creates its own team, dispatches domain agents with cross-domain context, and spawns researchers as needed.
3.**Coordinate as normal** — receive progress messages, relay user feedback, actively manage per the coordination loop.
When a single-domain agent sends `[complete]` and the user wants to continue:
1. Read the domain agent's `.codeflash/results.tsv` and `.codeflash/HANDOFF.md`.
2. Tell the user: "The <domain> optimizer plateaued after <N> experiments (<keeps> kept). I'll switch to the deep optimizer to look for cross-domain interactions the <domain> agent couldn't see."
After a session completes (single-domain or post-merge for multi-domain), generate `.codeflash/changelog.md` from the experiment history. This file can be used directly as a PR description body.
- Structure: import time seconds, dep count (e.g., "1.2s → 0.4s, 67% faster import")
4.**Print the result.** After writing the file, print:
```
[changelog] Written to .codeflash/changelog.md — <N> optimizations across <M> domain(s)
```
5.**Usage.** Tell the user: "The changelog is ready at `.codeflash/changelog.md`. You can use it as a PR description body when you're ready to open a PR."
