System Architecture Overview
The Multi-Step Workflow
Section titled “The Multi-Step Workflow”The system follows a strict sequential workflow with mandatory human approval gates between critical phases:
| Step | Phase | Agent | Output | Review | |
|---|---|---|---|---|---|
| 🔒 | 1 | 📜 Requirements | 02-Requirements | 01-requirements.md | 1 pass |
| 🔒 | 2 | 🏛️ Architecture | 03-Architect | 02-architecture-assessment.md | 3+1 passes |
| 3 | 🎨 Design (opt) | 04-Design | 03-des-*.{drawio,py,png,md} | — | |
| 🔒 | 3.5 | 🛡️ Governance | 04g-Governance | 04-governance-constraints.md | — |
| 🔒 | 4 | 📐 IaC Plan | 05-IaC Planner | 04-implementation-plan.md | 1+3 passes |
| ✔ | 5 | ⚒️ IaC Code | 06b / 06t CodeGen | infra/bicep/ or infra/terraform/ | 3 passes |
| 🔒 | 6 | 🚀 Deploy | 07b / 07t Deploy | 06-deployment-summary.md | 1 pass |
| 7 | 📚 As-Built | 08-As-Built | 07-*.md docs suite | — |
🔒 = Approval gate (human decision required) · ✔ = Automated validation gate (CI pass/fail) · blank = No gate
The Orchestrator Pattern
Section titled “The Orchestrator Pattern”
The Orchestrator (agent 01-Orchestrator) is the master orchestrator. It does not
generate infrastructure code or documentation itself. Instead, it:
- Reads the workflow DAG from
workflow-graph.json - Resolves agent paths and models from
agent-registry.json - Delegates each step to the appropriate specialised agent via
#runSubagent - Enforces approval gates between steps
- Maintains session state in
00-session-state.json - Writes human-readable handoff documents (
00-handoff.md) at every gate - Recommends session breaks at Gates 2 and 3 to prevent context exhaustion
The Orchestrator never touches infrastructure templates. It is a pure orchestrator and state machine.
Parse-and-confirm pattern: The Orchestrator parses the project name from the user’s
message and confirms inline, rather than using the askQuestions tool. It only falls
back to askQuestions if the message gives no clue.
Session Break Protocol: At Gates 2 and 3, the Orchestrator writes 00-handoff.md +
updates 00-session-state.json, then recommends the user start a fresh chat session.
This prevents context exhaustion in long-running sessions — real-world testing showed
that a 3h39m session experienced 5 forced context summarisations, losing critical
decision context. The new session resumes from the checkpoint by reading the state file.
Model Selection: The Orchestrator routes work to different model tiers based on task
complexity, not to specific model versions. Tier assignments are declared per agent in
the model: frontmatter field inside each .github/agents/*.agent.md file and are
validated by npm run lint:model-alignment. Concrete model names change over time.
| Tier | Purpose | Used By |
|---|---|---|
| Primary | Deep reasoning, multi-step planning, architecture & code generation | Orchestrator, all workflow step agents |
| Review | Adversarial critique, structured comparison, A/B validation | Challenger reviews, code reviews |
| Heavy API Work | Long-context batch execution over external APIs with deterministic I/O | Governance discovery (batch REST API calls) |
| Utility | Cheap, fast, well-defined transforms | Session state updates, lightweight tasks |
Subagent Integration Matrix: The full mapping of which subagents are invoked by which parent agents is externalised to the subagent-integration reference to keep the Orchestrator body under the 350-line limit.
Dual IaC Tracks
Section titled “Dual IaC Tracks”
Steps 1–3 (Requirements, Architecture, Design) are shared across both infrastructure
tracks. Step 3.5 (Governance) is also shared and mandatory. At Step 4, the workflow
diverges based on the iac_tool field in the requirements
document:
flowchart TD
Shared["Steps 1-3\n(Shared)"]
Decision{"iac_tool?"}
Bicep["Steps 4-6\nBicep Track\n(05 → 06b → 07b)"]:::track
Terraform["Steps 4-6\nTerraform Track\n(05 → 06t → 07t)"]:::track
AsBuilt["Step 7\nAs-Built Docs\n(Shared)"]:::endNode
Shared --> Decision
Decision -->|Bicep| Bicep
Decision -->|Terraform| Terraform
Bicep --> AsBuilt
Terraform --> AsBuilt