Proposal: AI-Owned Process Overhead — Auto-routing & Doc-sync #29
Description
Problem
Today, the developer is the workflow orchestrator. They must:
- Decide if a change is "small" or "big"
- Choose which workflow to invoke (quick-dev vs dev-story vs full BMAD)
- Know when to update architecture docs, stories, or sprint status
- Manually trigger code review, SM workflows, etc.
This creates friction. Developers want to say "build this" and have the AI figure out the process. When the AI asks "Is this [P] Plan first, [W] Seems bigger, or [E] Execute directly?" — the developer often doesn't know or doesn't care. They just want it done right.
Real-world example: A developer asks to change the auth provider from Supabase Auth to Better Auth. This touches architecture docs, multiple stories, env config, and package dependencies. The developer shouldn't need to know that this requires updating architecture.md first, then the epic, then the story — the AI should detect this and handle it.
Proposed Principle
The AI agent owns process overhead. Developers describe what they want. The agent auto-detects which workflow to invoke, which docs to update, and when to flag architectural conflicts — transparently but without requiring the developer to be the workflow orchestrator.
Proposed Changes
1. Auto-Routing in Quick-Dev Mode Detection
File: _bmad/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-01-mode-detection.md
Current: Escalation evaluation produces a menu that the user must choose from.
Proposed: After evaluating escalation signals, the AI auto-selects the appropriate path and informs the user what it chose and why. Only prompt for user input when genuinely ambiguous (signals are contradictory or borderline).
## ESCALATION HANDLING (revised)
### Auto-Route (default behavior)
After evaluating escalation signals:
**0 signals (simple request):**
- Auto-select [E] Execute directly
- Inform: "Executing directly — straightforward change."
**1-2 signals (moderate complexity):**
- Auto-select [E] Execute directly, but load architecture context first
- Inform: "Executing with architecture cross-check — multiple components involved."
**3+ signals (system-level work):**
- Auto-select [P] Plan first
- Inform: "This touches multiple system layers. Drafting a quick tech-spec
before implementation to catch issues early."
### Override
The developer can always override:
- "just do it" / "skip planning" → Execute directly regardless of signals
- "plan this" → Force planning regardless of signals
### Ambiguous Cases Only
Only present the [P] / [W] / [E] menu when signals are contradictory
(e.g., user says "quick fix" but describes multi-component changes).2. Doc-Scope Detection in Dev-Story Step 2
File: _bmad/bmm/workflows/4-implementation/dev-story/instructions.xml
Where: Step 2 (Load Project Context), after loading story and Dev Notes.
Add:
<action>
Scan the story tasks against the current architecture doc and project context.
Identify if any tasks involve:
- API contract changes (new endpoints, changed request/response shapes)
- Schema or data model changes
- Infrastructure or deployment config changes
- Authentication or authorization flow changes
- New external service integrations
If any are detected:
- Note which docs may need updates (architecture.md, epic file, env configs)
- Plan to update them as part of task implementation, not as a separate step
- Do NOT ask the developer for permission to update docs — just do it
- DO inform the developer briefly when a doc update happens
(e.g., "Updated architecture.md to reflect the new auth flow")
</action>3. Doc-Sync Validation in Dev-Story Step 8
File: Same as above.
Where: Step 8 (Validate and mark task complete), add a new validation check.
Add:
<check>
Before marking task complete, verify documentation consistency:
1. If implementation changed APIs → Check architecture.md API section is current
2. If implementation changed schemas → Check data model docs are current
3. If implementation changed env vars → Check .env.example is updated
4. If implementation contradicts architecture.md → Update architecture.md
and briefly inform the developer of the change
If docs need updating, update them now. Add doc files to the File List.
Do not create a separate task or ask for permission.
</check>4. Continuous Architecture Compliance (New Concept)
Where: Dev agent persona (_bmad/bmm/agents/dev.md) — add to activation steps or as a new standing rule.
Concept: The dev agent maintains a passive architecture awareness throughout implementation. Not a formal gate, but a background check:
## Standing Rule: Architecture Compliance
Throughout implementation, silently cross-check changes against the
architecture doc and project context.
- If a change ALIGNS with architecture: proceed silently
- If a change EXTENDS architecture (new pattern, not contradictory):
proceed, update architecture doc, inform developer briefly
- If a change CONTRADICTS architecture: pause, inform developer,
propose options (update architecture or change approach)
Never ask the developer "should I check the architecture?" — always check.
Never ask "should I update the docs?" — update them if needed.
Only escalate when there's a genuine conflict requiring a decision.Benefits
- Reduced cognitive load — developer focuses on what, not how
- Fewer stale docs — docs updated as side effects of implementation, not ceremonies
- Fewer missed conflicts — AI catches architecture drift that humans miss
- Faster iteration — no workflow selection menus for clear-cut cases
- Better developer experience — feels like a capable teammate, not a process tool
Backwards Compatibility
- Developers who prefer explicit control can override with direct commands
- The
#yolomode already exists for skipping confirmations — this proposal extends that philosophy to workflow routing - No changes to story file format or sprint-status structure
- Existing workflows remain available for manual invocation
Discussion
Q: Won't auto-routing make mistakes?
A: Sometimes, but the cost of asking every time is higher than occasional mis-routing. The AI should optimize for the common case (90% of changes are straightforward) and have good recovery for the uncommon case (flag conflicts when detected).
Q: Should doc updates be in the File List?
A: Yes — the code review workflow already validates File List against git changes. Doc updates should appear there naturally.
Q: Does this change the SM agent's role?
A: No — the SM still handles sprint planning, story creation, and retrospectives. This proposal is about the dev agent being smarter about its own workflow decisions, not absorbing SM responsibilities.