architectural-proposals

name	architectural-proposals
description	How to write comprehensive architectural proposals that drive alignment before code is written
domain	architecture, product-direction
confidence	high
source	earned (2026-02-21 interactive shell proposal)
tools	[{"name":"view","description":"Read existing codebase, prior decisions, and team context before proposing changes","when":"Always read .squad/decisions.md, relevant PRDs, and current architecture docs before writing proposal"},{"name":"create","description":"Create proposal in docs/proposals/ with structured format","when":"After gathering context, before any implementation work begins"}]

Context

Proposals create alignment before code is written. Cheaper to change a doc than refactor code. Use this pattern when:

• Architecture shifts invalidate existing assumptions
• Product direction changes require new foundation
• Multiple waves/milestones will be affected by a decision
• External dependencies (Copilot CLI, SDK APIs) change

Patterns