squad: Skill for Claude Code

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

Proposal Structure (docs/proposals/)

Required sections:

1. Problem Statement — Why current state is broken (specific, measurable evidence)
2. Proposed Architecture — Solution with technical specifics (not hand-waving)
3. What Changes — Impact on existing work (waves, milestones, modules)
4. What Stays the Same — Preserve existing functionality (no regression)
5. Key Decisions Needed — Explicit choices with recommendations
6. Risks and Mitigations — Likelihood + impact + mitigation strategy
7. Scope — What's in v1, what's deferred (timeline clarity)

Optional sections:

• Implementation Plan (high-level milestones)
• Success Criteria (measurable outcomes)
• Open Questions (unresolved items)
• Appendix (prior art, alternatives considered)

Tone Ceiling Enforcement

Always:

• Cite specific evidence (user reports, performance data, failure modes)
• Justify recommendations with technical rationale
• Acknowledge trade-offs (no perfect solutions)
• Be specific about APIs, libraries, file paths

Never:

• Hype ("revolutionary", "game-changing")
• Hand-waving ("we'll figure it out later")
• Unsubstantiated claims ("users will love this")
• Vague timelines ("soon", "eventually")

Wave Restructuring Pattern

When a proposal invalidates existing wave structure:

1. Acknowledge the shift: "This becomes Wave 0 (Foundation)"
2. Cascade impacts: Adjust downstream waves (Wave 1, Wave 2, Wave 3)
3. Preserve non-blocking work: Identify what can proceed in parallel
4. Update dependencies: Document new blocking relationships

Example (Interactive Shell):

• Wave 0 (NEW): Interactive Shell — blocks all other waves
• Wave 1 (ADJUSTED): npm Distribution — shell bundled in cli.js
• Wave 2 (DEFERRED): SquadUI — waits for shell foundation
• Wave 3 (ADJUSTED): Public Docs — now documents shell as primary interface