tools-only ADR-001: Seven-Step Agent Workflow Design
Status
Accepted
Date
2024-01-15
Context
This repository demonstrates GitHub Copilot's capabilities for Azure infrastructure development. We needed to design a workflow that:
- Showcases the full spectrum of Copilot capabilities (planning, architecture, code generation)
- Provides clear separation of concerns between different phases
- Allows for human approval gates between major decisions
- Teaches best practices through the agent prompts themselves
- Handles the token limit constraints of AI responses
Considered Alternatives
- Single monolithic agent - One agent handles everything from requirements to deployment
- Two-step workflow - Architecture → Implementation only
- Seven-step workflow - Finer granularity with separate agents for each phase, including deploy step
- No custom agents - Rely entirely on Copilot Chat without custom prompts
Decision
We adopted a seven-step workflow with approval gates:
@plan → architect → [Design Artifacts] → bicep-plan → bicep-code → Deploy → [As-Built Artifacts]
With optional artifact phases:
- Step 3: Design Artifacts -
diagram,adr(suffix:-des) - Step 7: As-Built Artifacts -
diagram,adr(suffix:-ab)
Workflow Steps
| Step | Agent/Phase | Purpose | Creates Code? |
|---|---|---|---|
| 1 | @plan |
Requirements gathering | No |
| 2 | architect |
WAF assessment, recommendations | No |
| 3 | Design Artifacts (optional) | Design diagrams + ADRs | No |
| 4 | bicep-plan |
Implementation planning with AVM | Planning docs |
| 5 | bicep-code |
Bicep code generation | Yes |
| 6 | Deploy | Deploy to Azure | No |
| 7 | As-Built Artifacts (opt.) | As-built diagrams + ADRs | No |
Why Seven Steps?
- Matches real-world workflow - Architects don't write code, developers don't set requirements
- Prevents token limit issues - Splitting planning from implementation keeps responses focused
- Enables approval gates - Each step requires human confirmation before proceeding
- Supports iterative refinement - Can re-run any step without starting over
Consequences
Positive
- Clear separation between architecture decisions and implementation details
- Human remains in control with explicit approval gates
- Easier to debug issues (which step failed?)
- Supports phased demos (can show just architecture, or full workflow)
- Token limits are manageable with scoped agent responsibilities
Negative
- More complex than single-agent approach
- Requires user to understand workflow sequence
- Context must be passed between steps (sometimes manually)
- New users may be confused by agent selection
Mitigations
- Created
docs/reference/workflow.mdwith detailed workflow documentation - Added workflow diagrams to agent prompts
- Agents prompt for approval before major actions
copilot-instructions.mdincludes workflow quick reference
References
- docs/reference/workflow.md - Full workflow documentation
- .github/agents/ - Agent definitions
- .github/copilot-instructions.md - Copilot guidance