Agent dispatch

Agent Dispatch

Discovers and invokes specialist agents based on task requirements and current PREVC phase. Adapts to available mode (Full/Lite/Minimal).

Announce at start: "I'm using the devflow:agent-dispatch skill to select agents for this task."

Available Agents

DevFlow provides 15 specialist agents, each with defined roles and phase participation:

Agent	Role	Phases	When to use
architect	architect	P, R	System design, technical decisions, scalability review
product-manager	strategist	P	Product strategy, PRDs, roadmap definition, prioritization
feature-developer	developer	E	Feature implementation following specs
bug-fixer	developer	E	Root cause analysis and targeted fixes
code-reviewer	reviewer	R, V	Code quality, patterns, best practices review
test-writer	developer	E, V	Test coverage, test design, testing strategy
documentation-writer	developer	C	API docs, README, inline docs maintenance
refactoring-specialist	developer	E	Code restructuring, pattern improvements
performance-optimizer	specialist	V	Bottleneck identification, optimization
security-auditor	specialist	R, V	Vulnerability assessment, security review
backend-specialist	specialist	E	Server-side architecture, APIs, databases
frontend-specialist	specialist	E	UI development, components, state management
database-specialist	specialist	E	Schema design, query optimization, migrations
devops-specialist	specialist	E, C	CI/CD, infrastructure, deployment
mobile-specialist	specialist	E	iOS/Android development, mobile UX

Framework routing (dynamic discovery)

Perfis NÃO contribuem agents (ADR-008 v1.1.0) — criar agente de projeto é competência exclusiva do dotcontext. O que o perfil contribui é conhecimento de framework (skills) e o vínculo entre esse conhecimento e os papéis de agente que o projeto já tem.

1. List candidate agents from .context/agents/*.md (project) and the bundled agents/*.md (plugin). Each agent declares agentType: in its frontmatter.
2. Load the active framework profiles:

   node "${CLAUDE_PLUGIN_ROOT}/scripts/lib/detect-framework.mjs" "$PWD"
   

   • dispatchKeywords mapeia keyword → papel de agente de projeto (ex.: backend-specialist: ["odoo","orm","addon"]), nunca um agente do plugin.
   • skillBindings diz quais skills de framework cada papel usa.
3. Ao despachar um papel, carregue as skills declaradas no frontmatter skills: do agente de projeto — é ali que o context-sync materializa o vínculo. Essa chave é a fonte de verdade em tempo de dispatch; o skillBindings do perfil é a fonte que a alimenta.

Dispatch Process

Step 1: Identify Needed Agents

Based on the current task and phase:

Full Mode:

agent({ action: "orchestrate", phase: "<current-phase>", task: "<task-description>" })

Returns the optimal agent selection with reasoning.

Lite Mode: Match task keywords to agent roles:

• "API", "endpoint", "server" → backend-specialist
• "UI", "component", "CSS" → frontend-specialist
• "test", "coverage", "spec" → test-writer
• "schema", "migration", "query" → database-specialist
• "deploy", "CI", "docker" → devops-specialist
• "security", "auth", "vulnerability" → security-auditor
• "performance", "optimize", "slow" → performance-optimizer
• "refactor", "restructure", "clean up" → refactoring-specialist
• "docs", "README", "API docs" → documentation-writer
• "architecture", "design", "system" → architect
• "product", "roadmap", "PRD", "requirements" → product-manager

Then append the framework profiles' dispatchKeywords (from the detector above). E.g. num projeto Odoo: "odoo", "orm", "addon", "l10n_br" → backend-specialist; "owl", "qweb", "pos" → frontend-specialist. O roteamento aponta para papéis que o projeto já tem, e o papel escolhido carrega as skills de framework listadas no seu frontmatter skills:. Quando a keyword de perfil e a genérica casam no mesmo papel, não há conflito — é o mesmo agente, com conhecimento de framework anexado.

Minimal Mode: No agent dispatch — proceed with general-purpose approach.

Step 2: Load Agent Playbook

Agent playbooks are resolved using a priority chain — always prefer project-specific over generic:

Priority 1: dotcontext MCP (Full mode)
  └─ agent({ action: "getInfo", agent: "<name>" })
     Richest content: semantic analysis, actual symbols, tree-sitter data

Priority 2: .context/agents/<name>.md (Lite mode)
  └─ Project-specific playbook (generated by dotcontext OR devflow:project-init)
     Has: actual file paths, real patterns, project conventions
     Check: status: filled → use it | status: unfilled → fill it first

Priority 3: <devflow-plugin>/agents/<name>.md (Minimal mode fallback)
  └─ Generic playbook bundled with DevFlow
     Has: general best practices, no project-specific context
     Use ONLY when .context/agents/ doesn't exist

Full Mode:

agent({ action: "getInfo", agent: "<agent-name>" })
agent({ action: "getDocs", agent: "<agent-name>" })

Lite Mode:

Read .context/agents/<agent-name>.md

• If file exists with status: filled → use it directly
• If file exists with status: unfilled → fill it with project context first, then use
• If file doesn't exist → fall back to bundled playbook

Minimal Mode: Read from DevFlow's bundled playbooks:

Read <devflow-plugin>/agents/<agent-name>.md

Important: Never overwrite a .context/agents/ file that was generated by dotcontext (status: filled). dotcontext fills with richer content (semantic analysis, actual symbols) than DevFlow can generate.

Step 3: Apply Agent Guidance

Project-specific playbooks (dotcontext v2 format) provide 11 sections:

• Mission — project-tailored mission
• Responsibilities — specific duties for this project
• Best Practices — project conventions
• Key Project Resources — actual doc paths
• Repository Starting Points — actual directories
• Key Files — actual entry points and important files
• Architecture Context — actual layers and patterns
• Key Symbols — actual classes/functions relevant to this agent
• Documentation Touchpoints — actual doc files to reference
• Collaboration Checklist — project-specific workflow
• Hand-off Notes — typical handoff context

Bundled playbooks (DevFlow format) provide a simpler structure:

• Mission, Responsibilities, Workflow Steps, Best Practices, Handoff Protocol

Apply whichever format you loaded — project-specific is always preferred.

Step 4: Handoff (if multi-agent)

When transitioning between agents in a task group:

Full Mode:

workflow-manage({ action: "handoff", from: "<agent-a>", to: "<agent-b>" })

Lite/Minimal Mode: Log the handoff and switch guidance:

Handoff: backend-specialist → frontend-specialist
Reason: API layer complete, moving to UI integration

Handoff Protocol

Between agents, verify:

• Previous agent's work is committed
• Tests from previous agent pass
• Handoff notes describe: what was done, what's next, any concerns
• New agent's playbook is loaded before continuing

Common Sequences

Task Type	Agent Sequence
Full-stack feature	architect → backend → frontend → test-writer
API endpoint	architect → backend → test-writer
UI feature	architect → frontend → test-writer
Bug fix	bug-fixer → test-writer
Refactoring	refactoring-specialist → test-writer → code-reviewer
Database change	database-specialist → backend → test-writer
Security fix	security-auditor → backend/frontend → test-writer
Performance issue	performance-optimizer → backend/frontend → test-writer

Anti-Patterns

Thought	Reality
"I don't need an agent for this"	In Minimal mode, that's fine. In Full/Lite, agents add domain expertise.
"I'll skip the handoff protocol"	Handoffs prevent context loss between specialists. Always follow it.
"One agent can do everything"	Specialists catch domain-specific issues. Use the right agent.
"Agent playbooks are just suggestions"	Playbooks encode proven domain expertise. Follow their workflow.