Architecture Phase
The Architecture phase answers: How will we build this? The answer is expressed not as a design document, but as an Architecture Reference Contract (ARC) — a set of enforceable constraints that govern all construction.
Purpose
Section titled “Purpose”Traditional architecture documents describe intent but can’t enforce it. The ARC is different:
- Constraints are binary — met or not met, no gray area
- Every constraint traces to a business need from the Intent Brief
- AI governance is built in, not bolted on
- The ARC is machine-checkable during adherence verification
Key Artifacts
Section titled “Key Artifacts”Architecture Reference Contract (ARC)
Section titled “Architecture Reference Contract (ARC)”The central document. Contains:
- Technology stack and patterns
- MUST constraints (non-negotiable requirements)
- MUST NOT constraints (explicit prohibitions)
- SHOULD constraints (strong recommendations)
- MAY constraints (permitted approaches)
- AI governance rules
- Testing requirements traceable to constraints
Created by: cat-arc-builder with Julian
Quick ARC
Section titled “Quick ARC”For small brownfield changes, a lightweight ARC that focuses on what’s changing rather than documenting the entire system.
Created by: cat-quick-arc with Julian
AI Validation Report
Section titled “AI Validation Report”Evidence that the AI correctly understands both the Intent Brief and ARC before construction begins. This is a critical governance gate — it proves the AI can correctly interpret the constraints it will enforce.
Created by: cat-ai-validation with Julian
UX Design Specification
Section titled “UX Design Specification”For user-facing features, Flora creates interaction specifications and design patterns that become part of the architectural context.
Created by: cat-create-ux-design with Flora
Phase Gates
Section titled “Phase Gates”The Architecture phase has multiple gates:
| Gate | Workflow | Purpose |
|---|---|---|
| ARC Checkpoint | cat-arc-checkpoint | Validates ARC completeness and Intent Brief alignment |
| AI Validation | cat-ai-validation | Proves AI understands the contract |
| Readiness Check | cat-readiness-check | Cross-artifact traceability audit |
All three should pass before starting Construction.
Constraint Writing Guidelines
Section titled “Constraint Writing Guidelines”Good constraints are:
- Specific: “MUST use parameterized queries” not “MUST prevent SQL injection”
- Verifiable: Can be checked during ARC adherence
- Traceable: Maps to a business need in the Intent Brief
- Atomic: One requirement per constraint
Common Pitfalls
Section titled “Common Pitfalls”| Pitfall | Fix |
|---|---|
| Constraints too vague to enforce | Use “MUST [specific action] using [specific mechanism]“ |
| Missing AI governance | Every ARC needs an AI section, even if “no AI-generated code” |
| Constraints without business justification | Each constraint should reference why it exists |
| Skipping AI Validation | The AI can’t enforce what it doesn’t understand |
See Also: What Is an ARC? · Build an ARC · DLC Overview