squad-architecture

name	squad-architecture
description	System architecture practices — project structure, API contracts, shared types, monorepo setup, and technical decision documentation. Use when designing system architecture, defining contracts between components, or setting up project structure.
version	1.0.0

Architecture & System Design

Project Structure

• Define clear boundaries between components (backend, frontend, shared)
• Use a monorepo with workspaces when frontend and backend share types
• Create a shared types/constants package that both sides import
• Document the project structure in a README or ARCHITECTURE.md

API Contract Definition

When defining API contracts that other agents will implement:

• List EVERY endpoint with method, path, request body, and response shape
• Specify exact field names, types, and which fields are optional
• Define error response format consistently
• Specify authentication requirements per endpoint
• Include example request/response pairs

Example:

POST /api/auth/login
  Request:  { email: string, password: string }
  Response: { user: { id, email, name }, accessToken: string, refreshToken: string }
  Errors:   401 { error: "Invalid credentials" }

Shared Types

• Define TypeScript interfaces for all data models
• Include validation schemas (zod) alongside types
• Export constants (status enums, priority levels, config values)
• Version the shared package so consumers know when contracts change

Technical Decisions

Document every significant decision in your output:

• What was decided and why
• What alternatives were considered
• What trade-offs were accepted

This helps downstream agents understand the rationale and stay consistent.

Handoff Quality

Your output is the contract that all other agents build against. Be precise:

• Don't leave ambiguity in field names or types
• Specify exact port numbers, file paths, directory structure
• Include the database schema with column types and constraints
• List all environment variables needed