Architecture Authoring
Establish the contract
- Identify the requested artifact and the decision it must enable.
- Locate repository instructions, existing architecture, ADRs, applicable specifications, and implementation evidence.
- Select the most specific contract under
../../../.github/specs/architecture/ when present.
- Record material unknowns instead of silently treating them as decisions.
Build the architecture model
Define only the views needed for the decision:
- context and stakeholders
- scope and system boundary
- components and ownership
- interfaces and data contracts
- data or control flow
- dependencies and integration points
- state, lifecycle, or failure behavior
- security, privacy, accessibility, operations, and developer experience
- alternatives, tradeoffs, and consequential decisions
- migration and compatibility boundaries
Distinguish observed current state, approved target state, recommendations, assumptions, and open questions.
Author the artifact
- Give each concept one canonical owner.
- Link to related documents instead of duplicating their content.
- Use normative terms consistently: must for requirements, should for strong recommendations, and may for optional behavior.
- Prefer a small table or Mermaid diagram only when relationships are clearer visually.
- Keep implementation examples non-normative unless the architecture explicitly standardizes them.
- Avoid speculative components that do not satisfy a stated requirement.
Validate
Check that:
- every goal maps to an architectural responsibility
- boundaries and ownership do not overlap ambiguously
- interfaces identify direction, inputs, outputs, and failures
- consequential tradeoffs are explicit
- requirements do not contradict applicable specifications
- the architecture can be decomposed into implementation work
- unresolved decisions and risks are visible
Return or write the requested artifact, then summarize decisions, assumptions, open questions, and the recommended next workflow stage.
1---2name: architecture-authoring3description: Design or revise software and system architecture artifacts, including boundaries, components, interfaces, data flow, dependencies, tradeoffs, and decisions. Use for architecture documents, system designs, technical direction, platform decomposition, ADR preparation, or architecture review before implementation planning.4---56# Architecture Authoring78## Establish the contract9101. Identify the requested artifact and the decision it must enable.111. Locate repository instructions, existing architecture, ADRs, applicable specifications, and implementation evidence.121. Select the most specific contract under `../../../.github/specs/architecture/` when present.131. Record material unknowns instead of silently treating them as decisions.1415## Build the architecture model1617Define only the views needed for the decision:1819- context and stakeholders20- scope and system boundary21- components and ownership22- interfaces and data contracts23- data or control flow24- dependencies and integration points25- state, lifecycle, or failure behavior26- security, privacy, accessibility, operations, and developer experience27- alternatives, tradeoffs, and consequential decisions28- migration and compatibility boundaries2930Distinguish observed current state, approved target state, recommendations, assumptions, and open questions.3132## Author the artifact3334- Give each concept one canonical owner.35- Link to related documents instead of duplicating their content.36- Use normative terms consistently: **must** for requirements, **should** for strong recommendations, and **may** for optional behavior.37- Prefer a small table or Mermaid diagram only when relationships are clearer visually.38- Keep implementation examples non-normative unless the architecture explicitly standardizes them.39- Avoid speculative components that do not satisfy a stated requirement.4041## Validate4243Check that:4445- every goal maps to an architectural responsibility46- boundaries and ownership do not overlap ambiguously47- interfaces identify direction, inputs, outputs, and failures48- consequential tradeoffs are explicit49- requirements do not contradict applicable specifications50- the architecture can be decomposed into implementation work51- unresolved decisions and risks are visible5253Return or write the requested artifact, then summarize decisions, assumptions, open questions, and the recommended next workflow stage.
egohygiene