> workflow / architecture
Architecture
Produce ADRs, interface contracts, and threat-model sketches that bound what AI agents may invent during implementation.
What should I do next?
Complete the steps and evidence below, clear the human gates, then continue to Implementation Planning.
When to use
- Kickoff context package exists and DoR is met
- New services, data stores, or external integrations are in play
- NFRs (security, scale, cost, latency) will constrain design choices
- You need agent-enforceable boundaries before planning tickets
Step-by-step
- Restate constraints from the brief and context package; reject silent scope growth.
- Enumerate candidate architectures; pick one primary with explicit tradeoffs.
- Write ADRs for contested decisions (auth, data ownership, sync vs async, model placement).
- Define interface contracts and ownership of each boundary.
- Sketch a threat model covering prompt injection, tool abuse, and data exfiltration paths.
- Run architecture-review.prompt against the ADR set; architect resolves findings.
- Freeze boundaries that coding agents must not cross without a new ADR.
Decisions to make
- Where inference runs (edge, service, batch) and who owns model failures
- Source of truth for each data domain
- Sync vs async boundaries and failure semantics
- Which third-party MCPs/APIs are in the trust boundary
Evidence to collect
- ADR set linked from the context package
- Interface contracts (OpenAPI/events/schemas) for new boundaries
- Threat model sketch with owners for high risks
- Architect approval recorded before implementation planning
Role-specific next actions
- PM: Confirm architecture still delivers the brief metrics; cut scope if NFRs explode cost.
- Architect: Own ADRs, contracts, and agent boundary freeze.
- Engineer: Validate feasibility against stack skills; surface hidden coupling early.
- Security: Challenge data flows and tool allowlists in the threat model.
Inputs
- Approved brief and context package
- Existing system map
- NFRs: security, scale, cost, latency
Outputs
- ADR set
- Interface contracts
- Threat model sketch and boundary freeze
Required prompts
- Architecture review
Stress-tests ADRs for missing failure modes and agent-unsafe inventiveness.
- Security review
Early pass on trust boundaries before coding plans lock in.
Required skills
- Architecture
Scenario-governed design choices and ADR discipline.
- Security
Threat modeling for AI tool and retrieval surfaces.
Required MCP servers
None required at this stage — keep tools off by default.
Tooling & handbook
- Architecture pattern workflow
Stepwise architecture workflow tied to ADRs.
- Enterprise AI overview
Governance constraints that change architecture choices.
- Standards portal
Normative controls to reference in ADRs when applicable.
Recommended agents & patterns
- Architecture pattern
Primary pattern for this stage.
- Architect agent
Drafts options; human architect decides.
- Security agent
Assists threat model — does not approve production risk.
Human approval gates
- Architect approval of ADR set before implementation planning
- Security review of external data and tool boundaries for elevated risk tiers
Automation opportunities
- ADR scaffold from architecture-review.prompt
- Link patterns and cookbooks to affected services in the context package
- CI check that new integrations reference an ADR ID
Enterprise best practices
- Identify SoA-relevant controls early and cite control IDs in ADRs
- Cross-team review for shared platforms and multi-tenant surfaces
- Prohibit agents from inventing integrations not listed in the allowlist
Common mistakes
- Letting agents invent integrations without ADRs
- Architecture drift without updating ADRs and context packages
- Skipping threat model because "it is just a prototype"