Orchestration Issues

[SoaresMG]

Hi @davepoon and everyone else!

I have started using sub agents a few days ago and I actually created a few similar ones to those present in this project.

Have you faced issues where the lead orchestrator isn't calling consistently the subagents?

I mitigated this by creating a subagent specialised in configuring the lead orchestrator, it came up with a few files dedicated to orchestration in .claude, however it increases the token usage (bigger context) considerably, so I'm trying different approaches.

I know that giving a better context during prompt might have the lead orchestrator doing a better job, but I still find it lacking.

How are you dealing with it?

An example would be asking Claude to update documentation on X feature based on current changes and instead of calling the subagent dedicated to documentation, passing only the necessary context to it, the lead orchestrator tries to do it himself while only the subagent dedicated to documentation contains specific rules.

[virgilhawkins00]

Hey @SoaresMG! Great question - I've dealt with similar orchestration challenges. Here are a few strategies that have worked well for me:

1. Make subagent responsibilities crystal clear
In your .claude/orchestration or main prompt, try being very explicit about when to delegate. Something like:

When the user asks to update/create documentation:
- ALWAYS call @documentation-agent
- Pass the relevant code/feature context
- Let the specialist handle the writing

2. Add decision triggers
Create simple rules that help the orchestrator recognize delegation moments:

• Keywords: "update docs" → documentation agent
• File types: .md files → documentation agent
• Specific commands: /docs → documentation agent

3. Test with edge cases
Try asking the same request in different ways to see when delegation fails:

• "Update the README for feature X"
• "Add documentation about X"
• "Document the X changes"

If one phrasing works better, you can guide users or refine your orchestration logic.

4. Keep orchestrator context lean
Instead of large configuration files, try a focused orchestration checklist. Something like:

Before responding:
1. Does this involve [X]? → Call subagent Y
2. Does this involve [A, B, C]? → Call subagent Z
3. Otherwise → Handle directly

5. Explicit handoff pattern
You could try making the orchestrator output its decision before acting:
"I see this requires documentation updates. Calling @documentation-agent with context: [summary]"

This makes the flow visible and you can catch when delegation is skipped.

The token overhead is real, but I've found that a smaller, well-structured orchestration guide (200-300 tokens) works better than large config files. Focus on when to delegate rather than how the subagents work.

Have you tried experimenting with different phrasing in your requests? Sometimes the orchestrator picks up on subtle cues we don't realize we're giving it.