| 1 | --- |
| 2 | name: "architectural-proposals" |
| 3 | description: "How to write comprehensive architectural proposals that drive alignment before code is written" |
| 4 | domain: "architecture, product-direction" |
| 5 | confidence: "high" |
| 6 | source: "earned (2026-02-21 interactive shell proposal)" |
| 7 | tools: |
| 8 | - name: "view" |
| 9 | description: "Read existing codebase, prior decisions, and team context before proposing changes" |
| 10 | when: "Always read .squad/decisions.md, relevant PRDs, and current architecture docs before writing proposal" |
| 11 | - name: "create" |
| 12 | description: "Create proposal in docs/proposals/ with structured format" |
| 13 | when: "After gathering context, before any implementation work begins" |
| 14 | --- |
| 15 | |
| 16 | ## Context |
| 17 | |
| 18 | Proposals create alignment before code is written. Cheaper to change a doc than refactor code. Use this pattern when: |
| 19 | - Architecture shifts invalidate existing assumptions |
| 20 | - Product direction changes require new foundation |
| 21 | - Multiple waves/milestones will be affected by a decision |
| 22 | - External dependencies (Copilot CLI, SDK APIs) change |
| 23 | |
| 24 | ## Patterns |
| 25 | |
| 26 | ### Proposal Structure (docs/proposals/) |
| 27 | |
| 28 | **Required sections:** |
| 29 | 1. **Problem Statement** — Why current state is broken (specific, measurable evidence) |
| 30 | 2. **Proposed Architecture** — Solution with technical specifics (not hand-waving) |
| 31 | 3. **What Changes** — Impact on existing work (waves, milestones, modules) |
| 32 | 4. **What Stays the Same** — Preserve existing functionality (no regression) |
| 33 | 5. **Key Decisions Needed** — Explicit choices with recommendations |
| 34 | 6. **Risks and Mitigations** — Likelihood + impact + mitigation strategy |
| 35 | 7. **Scope** — What's in v1, what's deferred (timeline clarity) |
| 36 | |
| 37 | **Optional sections:** |
| 38 | - Implementation Plan (high-level milestones) |
| 39 | - Success Criteria (measurable outcomes) |
| 40 | - Open Questions (unresolved items) |
| 41 | - Appendix (prior art, alternatives considered) |
| 42 | |
| 43 | ### Tone Ceiling Enforcement |
| 44 | |
| 45 | **Always:** |
| 46 | - Cite specific evidence (user reports, performance data, failure modes) |
| 47 | - Justify recommendations with technical rationale |
| 48 | - Acknowledge trade-offs (no perfect solutions) |
| 49 | - Be specific about APIs, libraries, file paths |
| 50 | |
| 51 | **Never:** |
| 52 | - Hype ("revolutionary", "game-changing") |
| 53 | - Hand-waving ("we'll figure it out later") |
| 54 | - Unsubstantiated claims ("users will love this") |
| 55 | - Vague timelines ("soon", "eventually") |
| 56 | |
| 57 | ### Wave Restructuring Pattern |
| 58 | |
| 59 | When a proposal invalidates existing wave structure: |
| 60 | 1. **Acknowledge the shift:** "This becomes Wave 0 (Foundation)" |
| 61 | 2. **Cascade impacts:** Adjust downstream waves (Wave 1, Wave 2, Wave 3) |
| 62 | 3. **Preserve non-blocking work:** Identify what can proceed in parallel |
| 63 | 4. **Update dependencies:** Document new blocking relationships |
| 64 | |
| 65 | **Example (Interactive Shell):** |
| 66 | - Wave 0 (NEW): Interactive Shell — blocks all other waves |
| 67 | - Wave 1 (ADJUSTED): npm Distribution — shell bundled in cli.js |
| 68 | - Wave 2 (DEFERRED): SquadUI — waits for shell foundation |
| 69 | - Wave 3 (ADJUSTED): Public Docs — now documents shell as primary interface |
| 70 | |
| 71 | ### Decision Framing |
| 72 | |
| 73 | **Format:** "Recommendation: X (recommended) or alternatives?" |
| 74 | |
| 75 | **Components:** |
| 76 | - Recommendation (pick one, justify) |
| 77 | - Alternatives (what else was considered) |
| 78 | - Decision rationale (why recommended option wins) |
| 79 | - Needs sign-off from (which agents/roles must approve) |
| 80 | |
| 81 | **Example:** |
| 82 | ``` |
| 83 | ### 1. Terminal UI Library: `ink` (recommended) or alternatives? |
| 84 | |
| 85 | **Recommendation:** `ink` |
| 86 | **Alternatives:** `blessed`, raw readline |
| 87 | **Decision rationale:** Component model enables testable UI. Battle-tested ecosystem. |
| 88 | |
| 89 | **Needs sign-off from:** Brady (product direction), Fortier (runtime performance) |
| 90 | ``` |
| 91 | |
| 92 | ### Risk Documentation |
| 93 | |
| 94 | **Format per risk:** |
| 95 | - **Risk:** Specific failure mode |
| 96 | - **Likelihood:** Low / Medium / High (not percentages) |
| 97 | - **Impact:** Low / Medium / High |
| 98 | - **Mitigation:** Concrete actions (measurable) |
| 99 | |
| 100 | **Example:** |
| 101 | ``` |
| 102 | ### Risk 2: SDK Streaming Reliability |
| 103 | |
| 104 | **Risk:** SDK streaming events might drop messages or arrive out of order. |
| 105 | **Likelihood:** Low (SDK is production-grade). |
| 106 | **Impact:** High — broken streaming makes shell unusable. |
| 107 | |
| 108 | **Mitigation:** |
| 109 | - Add integration test: Send 1000-message stream, verify all deltas arrive in order |
| 110 | - Implement fallback: If streaming fails, fall back to polling session state |
| 111 | - Log all SDK events to `.squad/orchestration-log/sdk-events.jsonl` for debugging |
| 112 | ``` |
| 113 | |
| 114 | ## Examples |
| 115 | |
| 116 | **File references from interactive shell proposal:** |
| 117 | - Full proposal: `docs/proposals/squad-interactive-shell.md` |
| 118 | - User directive: `.squad/decisions/inbox/copilot-directive-2026-02-21T202535Z.md` |
| 119 | - Team decisions: `.squad/decisions.md` |
| 120 | - Current architecture: `docs/architecture/module-map.md`, `docs/prd-23-release-readiness.md` |
| 121 | |
| 122 | **Key patterns demonstrated:** |
| 123 | 1. Read user directive first (understand the "why") |
| 124 | 2. Survey current architecture (module map, existing waves) |
| 125 | 3. Research SDK APIs (exploration task to validate feasibility) |
| 126 | 4. Document problem with specific evidence (unreliable handoffs, zero visibility, UX mismatch) |
| 127 | 5. Propose solution with technical specifics (ink components, SDK session management, spawn.ts module) |
| 128 | 6. Restructure waves when foundation shifts (Wave 0 becomes blocker) |
| 129 | 7. Preserve backward compatibility (squad.agent.md still works, VS Code mode unchanged) |
| 130 | 8. Frame decisions explicitly (5 key decisions with recommendations) |
| 131 | 9. Document risks with mitigations (5 risks, each with concrete actions) |
| 132 | 10. Define scope (what's in v1 vs. deferred) |
| 133 | |
| 134 | ## Anti-Patterns |
| 135 | |
| 136 | **Avoid:** |
| 137 | - ❌ Proposals without problem statements (solution-first thinking) |
| 138 | - ❌ Vague architecture ("we'll use a shell") — be specific (ink components, session registry, spawn.ts) |
| 139 | - ❌ Ignoring existing work — always document impact on waves/milestones |
| 140 | - ❌ No risk analysis — every architecture has risks, document them |
| 141 | - ❌ Unbounded scope — draw the v1 line explicitly |
| 142 | - ❌ Missing decision ownership — always say "needs sign-off from X" |
| 143 | - ❌ No backward compatibility plan — users don't care about your replatform |
| 144 | - ❌ Hand-waving timelines ("a few weeks") — be specific (2-3 weeks, 1 engineer full-time) |
| 145 | |
| 146 | **Red flags in proposal reviews:** |
| 147 | - "Users will love this" (citation needed) |
| 148 | - "We'll figure out X later" (scope creep incoming) |
| 149 | - "This is revolutionary" (tone ceiling violation) |
| 150 | - No section on "What Stays the Same" (regression risk) |
| 151 | - No risks documented (wishful thinking) |