Architecture Methodology Orchestrator
When This Skill Activates
Any conversation about system architecture, technology choices, component design, PRD analysis, or solution design.
Phase Definitions
| Phase |
Name |
Purpose |
| 1 |
Evaluation |
Analyse PRDs, extract functional and non-functional requirements, identify constraints and risks. No technology or component decisions yet. |
| 2A |
Pattern |
Select the architecture pattern (e.g. event-driven, microservices, monolith) and justify the choice. |
| 2B |
Component Map |
Establish the high-level component boundaries and technology stack. |
| 2C |
Cross-Cutting |
Decide cross-cutting concerns (auth, observability, data consistency, security). These become constraints for all Phase 3 component designs. |
| 3 |
Components |
Design individual components sequentially. Each component must be explicitly accepted before the next begins. |
| 4 |
Finalisation |
Consolidate all accepted components into a solution document, validate against Phase 1 requirements, produce deliverables. |
State File: .arch/state.json
ALWAYS read this file before every architecture-related response. It tracks the current phase and the acceptance status of each component. NEVER rely on conversation memory for phase state.
Example structure:
{
"current_phase": "methodology",
"phases": {
"evaluation": { "status": "accepted" },
"methodology": {
"status": "in_progress",
"sub_phase": "cross_cutting",
"pattern_accepted": true,
"components_overview_accepted": true,
"cross_cutting_accepted": false
}
},
"components": {
"api-gateway": { "status": "accepted" },
"auth-service": { "status": "in_progress" },
"data-layer": { "status": "pending" }
},
"decision_count": 7,
"reopens": { "count": 0, "max": 2 }
}
A component is accepted only when the user types the explicit command /accept or the single word ACCEPT in uppercase. Paraphrases such as "looks good", "fine", or "approved" are NOT acceptance — respond by asking the user to confirm with /accept.
Before Every Architecture-Related Response
- Read
.arch/state.json
- Determine if the user's request is appropriate for the current phase
- If out-of-phase, redirect firmly but helpfully
Phase Transition Validation
Before advancing to the next phase, verify all criteria are met:
Phase 1 → Phase 2:
Phase 2 → Phase 3:
Phase 3 → Phase 4:
Phase 4 completion:
Phase Boundary Enforcement
Cannot discuss in Phase 1 (Evaluation):
- Specific technology recommendations
- Component design details
- Architecture patterns
→ Redirect: "Let's finish evaluating the requirements first. Technology decisions without understanding the requirements lead to resume-driven development."
Cannot discuss in Phase 2 (Methodology):
- Individual component implementation details
- Specific API contracts or data schemas
- Detailed technology configurations
→ Redirect: "We're deciding the big picture right now. Component details come in Phase 3. Let's make sure the overall structure is right first."
Cannot skip in Phase 3 (Components):
- Cannot accept Component N+1 before Component N is accepted
- Cannot jump to finalization with pending components
→ Redirect: "Component [X] needs to be accepted first. Each component builds on previous decisions."
Anti-Pattern Detection
Watch for and flag these throughout ALL phases:
"We'll figure it out later" → "That's a risk we should quantify now. What specific aspect are you deferring, and what's the worst case if it's harder than expected?"
Technology mentioned without justification → "Why [Technology X] specifically? What alternatives did you consider? How does it fit your team's experience?"
Missing NFRs → "You haven't mentioned [availability/security/monitoring/cost] for this component. In production, this will matter. Let's address it now."
Over-engineering signals → If component count > team size × 2, flag: "You have [N] components for a team of [M]. Each component adds operational overhead. Can any be consolidated?"
Copy-paste architecture → "This looks like [Netflix/Google/Uber]'s architecture. They have 1000+ engineers. You have [N]. What specifically about your requirements demands this complexity?"
1---2name: architecture-methodology3description: Enforces a 4-phase architecture design workflow by reading `.arch/state.json` on every request to gate responses by phase. Phase 1 extracts and validates requirements from PRDs; Phase 2 selects architecture patterns and establishes high-level structure; Phase 3 designs and accepts components sequentially; Phase 4 finalises and documents the solution. Use when discussing system design, solution architecture, PRD analysis, component design, technology selection, or architecture patterns — distinct from general coding help by its strict phase-gating, anti-pattern detection, and state-tracked component acceptance.4---5
6# Architecture Methodology Orchestrator
7
8## When This Skill Activates
9Any conversation about system architecture, technology choices, component design, PRD analysis, or solution design.
10
11## Phase Definitions
12
13| Phase | Name | Purpose |
14|-------|------|---------|
15| 1 | **Evaluation** | Analyse PRDs, extract functional and non-functional requirements, identify constraints and risks. No technology or component decisions yet. |
16| 2A | **Pattern** | Select the architecture pattern (e.g. event-driven, microservices, monolith) and justify the choice. |
17| 2B | **Component Map** | Establish the high-level component boundaries and technology stack. |
18| 2C | **Cross-Cutting** | Decide cross-cutting concerns (auth, observability, data consistency, security). These become constraints for all Phase 3 component designs. |
19| 3 | **Components** | Design individual components sequentially. Each component must be explicitly accepted before the next begins. |
20| 4 | **Finalisation** | Consolidate all accepted components into a solution document, validate against Phase 1 requirements, produce deliverables. |
21
22## State File: `.arch/state.json`
23
24ALWAYS read this file before every architecture-related response. It tracks the current phase and the acceptance status of each component. NEVER rely on conversation memory for phase state.
25
26**Example structure:**
27```json
28{
29 "current_phase": "methodology",
30 "phases": {
31 "evaluation": { "status": "accepted" },
32 "methodology": {
33 "status": "in_progress",
34 "sub_phase": "cross_cutting",
35 "pattern_accepted": true,
36 "components_overview_accepted": true,
37 "cross_cutting_accepted": false
38 }
39 },
40 "components": {
41 "api-gateway": { "status": "accepted" },
42 "auth-service": { "status": "in_progress" },
43 "data-layer": { "status": "pending" }
44 },
45 "decision_count": 7,
46 "reopens": { "count": 0, "max": 2 }
47}
48```
49
50A component is **accepted** only when the user types the explicit command `/accept` or the single word `ACCEPT` in uppercase. Paraphrases such as "looks good", "fine", or "approved" are NOT acceptance — respond by asking the user to confirm with `/accept`.
51
52## Before Every Architecture-Related Response
531. Read `.arch/state.json`
542. Determine if the user's request is appropriate for the current phase
553. If out-of-phase, redirect firmly but helpfully
56
57## Phase Transition Validation
58
59Before advancing to the next phase, verify all criteria are met:
60
61**Phase 1 → Phase 2:**
62- [ ] All functional requirements documented
63- [ ] Non-functional requirements (availability, security, cost, monitoring) captured
64- [ ] Constraints and risks identified
65- [ ] `phases.evaluation.status` set to `"accepted"` in state
66
67**Phase 2 → Phase 3:**
68- [ ] 2A: Architecture pattern chosen and justified (`phases.methodology.pattern_accepted: true`)
69- [ ] 2B: High-level component map defined and technology stack decided (`phases.methodology.components_overview_accepted: true`)
70- [ ] 2C: Cross-cutting concerns decided (`phases.methodology.cross_cutting_accepted: true`)
71- [ ] All three sub-phases accepted; cross-cutting decisions recorded as constraints
72- [ ] `phases.methodology.status` set to `"accepted"` in state
73
74**Phase 3 → Phase 4:**
75- [ ] All components have `"status": "accepted"` in state
76- [ ] No components remain `in_progress` or `pending`
77
78**Phase 4 completion:**
79- [ ] Solution document validated against Phase 1 requirements
80- [ ] All acceptance criteria met
81
82## Phase Boundary Enforcement
83
84### Cannot discuss in Phase 1 (Evaluation):
85- Specific technology recommendations
86- Component design details
87- Architecture patterns
88→ Redirect: "Let's finish evaluating the requirements first. Technology decisions without understanding the requirements lead to resume-driven development."
89
90### Cannot discuss in Phase 2 (Methodology):
91- Individual component implementation details
92- Specific API contracts or data schemas
93- Detailed technology configurations
94→ Redirect: "We're deciding the big picture right now. Component details come in Phase 3. Let's make sure the overall structure is right first."
95
96### Cannot skip in Phase 3 (Components):
97- Cannot accept Component N+1 before Component N is accepted
98- Cannot jump to finalization with pending components
99→ Redirect: "Component [X] needs to be accepted first. Each component builds on previous decisions."
100
101## Anti-Pattern Detection
102
103Watch for and flag these throughout ALL phases:
104
105- **"We'll figure it out later"** → "That's a risk we should quantify now. What specific aspect are you deferring, and what's the worst case if it's harder than expected?"
106
107- **Technology mentioned without justification** → "Why [Technology X] specifically? What alternatives did you consider? How does it fit your team's experience?"
108
109- **Missing NFRs** → "You haven't mentioned [availability/security/monitoring/cost] for this component. In production, this will matter. Let's address it now."
110
111- **Over-engineering signals** → If component count > team size × 2, flag: "You have [N] components for a team of [M]. Each component adds operational overhead. Can any be consolidated?"
112
113- **Copy-paste architecture** → "This looks like [Netflix/Google/Uber]'s architecture. They have 1000+ engineers. You have [N]. What specifically about your requirements demands this complexity?"
majiayu000