@davidbalzan/groundwork 0.3.1

package/payload/doc-templates/templates/DESIGN_SYSTEM_TEMPLATE.md

@@ -0,0 +1,336 @@
+---
+title: "Design System Template"
+tags: [groundwork/template]
+aliases: []
+---
+
+# [Project Name] - Design System
+
+> Visual language reference for consistent UI across all frontend code. **Essential for AI agents** when generating components, layouts, and styling. All color values, spacing, and component patterns should reference this document.
+
+---
+
+## 🎨 Color Palette
+
+### Primary Colors
+
+> The primary color family is used for main actions, active states, and brand identity elements.
+
+- **Primary**: `#[hex]` — [Usage: main CTA buttons, active navigation, links. Describe the color, e.g., "Deep indigo"]
+- **Primary Dark**: `#[hex]` — [Usage: hover states on primary elements, pressed states. Must meet 4.5:1 contrast with white text]
+- **Primary Light**: `#[hex]` — [Usage: focus rings, selected backgrounds, subtle highlights. Low opacity for layering]
+
+### Secondary Colors (if applicable)
+
+> Secondary colors complement the primary palette for less prominent actions and UI elements.
+
+- **Secondary**: `#[hex]` — [Usage and color description, e.g., "Teal accent for secondary actions and data visualization"]
+- **Accent**: `#[hex]` — [Usage and color description, e.g., "Warm amber for highlights, badges, and attention markers"]
+
+### Status Colors
+
+> Semantic colors that communicate meaning. These should be consistent across all feedback UI.
+
+- **Success**: `#[hex]` ([color name, e.g., "Emerald"]) — [Usage: positive feedback, completed states, confirmation messages. Must pair with success-light for backgrounds]
+- **Warning**: `#[hex]` ([color name, e.g., "Amber"]) — [Usage: caution states, approaching limits, non-critical alerts. Avoid using as the only indicator — pair with text/icon]
+- **Error**: `#[hex]` ([color name, e.g., "Rose"]) — [Usage: error states, destructive action confirmation, form validation failures. High contrast required for accessibility]
+- **Info**: `#[hex]` ([color name, e.g., "Sky"]) — [Usage: informational banners, tooltips, neutral state indicators]
+
+### Neutral Scale
+
+> Grays used for text, backgrounds, borders, and disabled states. The full scale ensures sufficient contrast at every level.
+
+```
+50    #[hex]  — Page background (light mode base surface)
+100   #[hex]  — Alternate/card background (subtle elevation without shadow)
+200   #[hex]  — Borders, dividers, subtle separators
+300   #[hex]  — Disabled text, placeholder text, inactive icons
+400   #[hex]  — Tertiary text, metadata, timestamps
+500   #[hex]  — Secondary text, labels, descriptions
+600   #[hex]  — Icons, medium-emphasis text
+700   #[hex]  — Primary body text (must meet 4.5:1 contrast on white)
+800   #[hex]  — Emphasized text, subheadings
+900   #[hex]  — Headings, high-emphasis text (maximum contrast)
+```
+
+### Dark Mode
+
+> Dark mode inverts the surface hierarchy while maintaining readability and reducing eye strain. All color values must meet WCAG AA contrast requirements on dark surfaces.
+
+```
+Surface:    #[hex]  — Page background (dark mode base, e.g., "Near-black, not pure #000")
+Elevated:   #[hex]  — Card/modal background (subtle elevation above surface)
+Muted:      #[hex]  — Alternate/inset background (lower emphasis areas)
+Border:     #[hex]  — Borders, dividers (subtle, lower contrast than light mode)
+Primary:    #[hex]  — Primary text on dark surface (off-white, not pure #FFF to reduce glare)
+Secondary:  #[hex]  — Secondary/description text (reduced emphasis)
+```
+
+### CSS Custom Properties
+
+> Define these in your global CSS or Tailwind theme. AI agents should use these variable names, not raw hex values.
+
+```css
+/* Example — replace with your actual CSS variable implementation */
+:root {
+  --color-primary: [hex];
+  --color-primary-dark: [hex];
+  --color-primary-light: [hex];
+  /* ... continue for all tokens above */
+}
+
+[data-theme="dark"] {
+  --color-surface: [hex];
+  --color-primary-text: [hex];
+  /* ... dark mode overrides */
+}
+```
+
+---
+
+## ✏️ Typography
+
+### Font Stack
+
+> Define font families with proper fallbacks. Include licensing notes and loading strategy.
+
+```css
+--font-primary:
+  "[Primary Font Name, e.g., Inter]", [fallback stack, e.g.,
+  "system-ui, -apple-system, sans-serif"];
+--font-mono:
+  "[Monospace Font Name, e.g., JetBrains Mono]", [fallback stack, e.g.,
+  "'Fira Code', 'Cascadia Code', monospace"];
+```
+
+**Loading Strategy**: [How fonts are loaded — e.g., "Google Fonts via <link> with display=swap" or "Self-hosted woff2 with font-display: optional"]
+**Licensing**: [Font license — e.g., "Inter: SIL Open Font License, free for commercial use"]
+
+### Type Scale
+
+> Each level in the type scale has a specific semantic purpose. AI agents should match content type to the appropriate level.
+
+| Name       | Size           | Line Height | Weight               | Letter Spacing | Usage                                                            |
+| ---------- | -------------- | ----------- | -------------------- | -------------- | ---------------------------------------------------------------- |
+| Display    | [X]px / [X]rem | [X]         | [Bold/700]           | [X]em          | [Page titles, hero headings — used sparingly, max once per page] |
+| Heading 1  | [X]px / [X]rem | [X]         | [Semibold/600]       | [X]em          | [Section headings — primary content divisions]                   |
+| Heading 2  | [X]px / [X]rem | [X]         | [Semibold/600]       | [X]em          | [Subsection headings — secondary content grouping]               |
+| Body Large | [X]px / [X]rem | [X]         | [Regular/400]        | normal         | [Lead paragraphs, feature descriptions — emphasis text]          |
+| Body       | [X]px / [X]rem | [X]         | [Regular/400]        | normal         | [Main content, paragraphs — the default text size]               |
+| Body Small | [X]px / [X]rem | [X]         | [Regular/400]        | normal         | [Supporting text, captions, helper text below inputs]            |
+| Caption    | [X]px / [X]rem | [X]         | [Medium/500]         | [X]em          | [Labels, metadata, timestamps — often uppercase for labels]      |
+| Code       | [X]px / [X]rem | [X]         | [Regular/400 (mono)] | normal         | [Inline code, code blocks, technical values — uses mono font]    |
+
+---
+
+## 📐 Spacing Scale
+
+> Consistent spacing creates visual rhythm and hierarchy. Use these values for padding, margin, and gap. Never use arbitrary pixel values.
+
+```
+Token    Value    Usage Examples
+──────   ──────   ──────────────────────────────────────────────────
+1        4px      Tight spacing: between icon and label, internal badge padding
+2        8px      Compact: between related form fields, inline element gaps
+3        12px     Default gap: between list items, card internal padding (small)
+4        16px     Standard: component internal padding, gap between form groups
+5        20px     Medium: space between card sections, modal padding
+6        24px     Comfortable: space between content blocks, section padding
+8        32px     Generous: space between major sections, card outer margin
+10       40px     Large: page section dividers, hero padding
+12       48px     Extra large: major layout gaps, page top/bottom padding
+16       64px     Maximum: hero sections, major layout breathing room
+```
+
+### Layout-Specific Spacing
+
+- **Page max width**: [X]px — [E.g., "1280px for content, 1440px for full-bleed"]
+- **Page padding (mobile)**: [X]px — [Horizontal padding on small screens]
+- **Page padding (desktop)**: [X]px — [Horizontal padding on large screens]
+- **Card padding**: [X]px — [Standard card content padding]
+- **Section gap**: [X]px — [Vertical space between major page sections]
+
+---
+
+## 🧩 Components
+
+> Reference implementations for core components. AI agents should follow these patterns for consistency. Use the design tokens defined above — never hardcode colors or spacing.
+
+### Buttons
+
+```tsx
+// Primary — Main call-to-action. Use sparingly: one primary button per section.
+className="bg-[primary] text-white px-4 py-2 rounded-lg font-semibold
+           hover:bg-[primary-dark] active:scale-[0.98]
+           focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[primary]
+           disabled:opacity-50 disabled:cursor-not-allowed"
+
+// Secondary — Supporting actions alongside a primary button.
+className="bg-[neutral-100] text-[neutral-900] px-4 py-2 rounded-lg font-medium
+           hover:bg-[neutral-200] active:bg-[neutral-300]
+           dark:bg-[neutral-800] dark:text-[neutral-100] dark:hover:bg-[neutral-700]"
+
+// Ghost — Tertiary actions, navigation, or low-emphasis contexts.
+className="text-[neutral-600] px-4 py-2 rounded-lg font-medium
+           hover:bg-[neutral-100] active:bg-[neutral-200]
+           dark:text-[neutral-400] dark:hover:bg-[neutral-800]"
+
+// Destructive — Delete, remove, or irreversible actions. Always requires confirmation.
+className="bg-[error] text-white px-4 py-2 rounded-lg font-semibold
+           hover:bg-[error-dark] focus-visible:outline-[error]"
+```
+
+**Button Sizes**:
+
+- `sm`: `px-3 py-1.5 text-sm` — [Usage: inline actions, table rows, compact UI]
+- `md`: `px-4 py-2 text-base` — [Usage: default size, forms, dialogs] (default)
+- `lg`: `px-6 py-3 text-lg` — [Usage: hero CTAs, primary page actions, onboarding]
+
+### Cards
+
+```css
+/* Standard card — the primary content container */
+background: var(--color-surface); /* Light: white, Dark: elevated surface */
+border: 1px solid var(--color-border); /* Subtle border, not shadow, for definition */
+border-radius: 12px; /* Consistent rounding across all cards */
+padding: [spacing-6]; /* 24px standard internal padding */
+box-shadow: 0 1px 2px rgba(0, 0, 0, 0.05); /* Minimal shadow — border does the work */
+
+/* Card hover state (for interactive cards only) */
+transition:
+  border-color 150ms ease-in-out,
+  box-shadow 150ms ease-in-out;
+hover: border-color var(--color-primary-light);
+hover: box-shadow 0 2px 8px rgba(0, 0, 0, 0.08);
+```
+
+### Inputs
+
+```css
+/* Text input — standard form input */
+background: var(--color-surface);
+border: 1px solid var(--color-border);
+border-radius: 8px;
+padding: 10px 12px; /* Slightly more vertical padding for touch targets */
+font-size: 14px; /* Body size for readability */
+line-height: 1.5;
+color: var(--color-primary-text);
+transition:
+  border-color 150ms ease-in-out,
+  box-shadow 150ms ease-in-out;
+
+/* Focus state — clearly visible but not jarring */
+&:focus {
+  border-color: var(--color-primary);
+  box-shadow: 0 0 0 3px var(--color-primary-light);
+  outline: none;
+}
+
+/* Error state — red border with error message below */
+&[aria-invalid="true"] {
+  border-color: var(--color-error);
+  box-shadow: 0 0 0 3px rgba([error-rgb], 0.15);
+}
+
+/* Disabled state */
+&:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+  background: var(--color-muted);
+}
+```
+
+### Badges / Status Indicators
+
+```tsx
+// Pattern for status badges — color communicates meaning, text provides context
+// Success
+className =
+  "inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium bg-[success-light] text-[success-dark]";
+
+// Warning
+className =
+  "inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium bg-[warning-light] text-[warning-dark]";
+
+// Error
+className =
+  "inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium bg-[error-light] text-[error-dark]";
+```
+
+---
+
+## ♿ Accessibility
+
+### Contrast Requirements
+
+> All text must meet WCAG 2.1 AA standards. Verify with a contrast checker tool when defining colors.
+
+- **Normal text** (< 18px): Minimum **4.5:1** contrast ratio against background
+- **Large text** (>= 18px or >= 14px bold): Minimum **3:1** contrast ratio
+- **UI components** (icons, borders, focus indicators): Minimum **3:1** contrast ratio
+- **Non-text contrast** (charts, graphs, data visualization): Minimum **3:1** contrast ratio
+
+### Focus States
+
+> All interactive elements MUST have visible focus indicators for keyboard navigation.
+
+- Focus ring: **2px solid** with **2px offset** — visible on all backgrounds
+- Focus ring color: `var(--color-primary)` at **50% opacity** (or `var(--color-primary-light)`)
+- Use `focus-visible` (not `focus`) to show focus ring only for keyboard navigation, not mouse clicks
+- Tab order must follow logical reading order — never use `tabindex > 0`
+
+### Motion & Animation
+
+> Respect user preferences for reduced motion. All animations must be optional.
+
+- Default transition duration: **150ms** `ease-in-out` — [Quick enough to feel responsive, slow enough to perceive]
+- Maximum animation duration: **300ms** — [Longer animations feel sluggish in utility UI]
+- Respect `prefers-reduced-motion: reduce` — disable all non-essential animations
+- Loading spinners and progress bars are exempt from reduced-motion (they communicate state)
+
+### Keyboard Navigation
+
+- All interactive elements reachable via Tab key
+- Enter/Space activates buttons and links
+- Escape closes modals, dropdowns, and overlays
+- Arrow keys navigate within menus, tabs, and lists
+
+---
+
+## 🖼️ Iconography
+
+> Consistent icon usage reinforces the visual language. Choose one icon library and stick with it.
+
+- **Library**: [Icon library name, e.g., "Lucide React" — include version and why this library was chosen]
+- **Default size**: [X]px — [E.g., "20px (matching body text line height for inline usage)"]
+- **Stroke width**: [X] — [E.g., "1.75 (slightly thinner than default 2 for a lighter feel)"]
+- **Style**: [Outlined / Filled / Duotone — describe the chosen style and when to deviate, e.g., "Outlined for all UI chrome; filled only for active/selected states"]
+- **Color**: [How icons inherit color — e.g., "Icons inherit text color via currentColor. Never hardcode icon colors."]
+
+### Icon Usage Guidelines
+
+- **Navigation**: [Which icons represent nav items — be consistent across mobile/desktop]
+- **Actions**: [Standard icons for common actions: edit, delete, save, close, search, filter]
+- **Status**: [Icons paired with status colors: check-circle for success, alert-triangle for warning, x-circle for error]
+- **Loading**: [Loading indicator pattern — spinner, skeleton, or progressive reveal]
+
+---
+
+## 📱 Responsive Breakpoints
+
+> Define breakpoints and how the layout adapts at each level.
+
+| Breakpoint | Width   | Layout Behavior                                                                            |
+| ---------- | ------- | ------------------------------------------------------------------------------------------ |
+| Mobile     | [< X]px | [Describe layout — e.g., "Single column, full-width cards, hamburger nav, bottom tab bar"] |
+| Tablet     | [X-Y]px | [Describe layout — e.g., "Two-column grid for cards, sidebar collapses to overlay"]        |
+| Desktop    | [> Y]px | [Describe layout — e.g., "Three-column layout, persistent sidebar, max-width container"]   |
+
+---
+
+## 📝 Notes
+
+- [Design tool reference — e.g., "Figma file: [link] — source of truth for mockups and component specs"]
+- [Theme implementation — e.g., "Dark mode toggled via data-theme attribute on <html>, persisted in localStorage"]
+- [Brand guidelines — e.g., "Logo usage rules: minimum clear space of 16px, never stretch or recolor"]
+- [Revision process — e.g., "Design system changes require review: update this doc, update components, update Storybook"]

package/payload/doc-templates/templates/DONE_TEMPLATE.md

@@ -0,0 +1,21 @@
+# DONE — <project>
+
+The completion log — **append-only, the executor is the sole writer** (solo you, or an external
+coordinator pulling from `docs/QUEUE.md`). On completing a queue item, append one line with the PR
+ref. Nobody else writes here, and the executor writes nowhere else in the queue seam (it never
+touches `docs/QUEUE.md`; the queue's writer prunes satisfied items there).
+
+**Done-line format (pinned — required, not just an example):**
+
+```
+- [x] <task> — owner/repo#N · YYYY-MM-DD
+```
+
+Use the **em-dash `—` (U+2014)** before the PR ref and the **middot ` · ` (U+00B7)** before the
+date — exact glyphs, not ASCII. Parsers that consume this file (e.g. the agent-coord-ui
+BacklogPanel) split on those glyphs; an ASCII hyphen/period renders the panel empty.
+
+## Done
+
+<!-- append here, one per line, in the pinned format above:
+     - [x] <task> — owner/repo#N · YYYY-MM-DD -->

package/payload/doc-templates/templates/PHASES_README_TEMPLATE.md

@@ -0,0 +1,144 @@
+---
+title: "Phases README Template"
+tags: [groundwork/template]
+aliases: []
+---
+
+# Production Readiness Phases
+
+> Navigation hub for all development phases. Provides a bird's-eye view of progress and links to detailed phase documentation.
+
+---
+
+## 📁 Phase Organization
+
+Each phase has its own folder with standardized documentation:
+
+- [[README]] — Phase overview, goals, deliverables, and success criteria (quick reference)
+- `PHASE[N]_TASKS.md` — Detailed task breakdown with checkboxes, dependencies, sub-steps, and rollback plans (generated by `/plan-phase`)
+
+### How to Use This Document
+
+1. Check **Roadmap Overview** for current project status at a glance
+2. Click into the active phase folder for detailed task breakdown
+3. Update progress indicators as tasks are completed
+4. Review **Cross-Phase Dependencies** before starting a new phase
+
+---
+
+## 🗺️ Roadmap Overview
+
+| Phase                | Focus Area                                                                                               | Duration  | Status                                          | Progress                                       |
+| -------------------- | -------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------- | ---------------------------------------------- |
+| [Phase 1](./phase1/) | [Focus area — describe the primary theme, e.g., "Foundation: project setup, auth, core database schema"] | [X] weeks | [🟢 Complete / 🟡 In Progress / ⚪ Not Started] | [X/Y tasks — e.g., "5/5 tasks" or "3/7 tasks"] |
+| [Phase 2](./phase2/) | [Focus area — e.g., "Core Features: main user workflows, business logic, API endpoints"]                 | [X] weeks | [Status]                                        | [X/Y tasks]                                    |
+| [Phase 3](./phase3/) | [Focus area — e.g., "Polish & Production: security hardening, monitoring, performance, deployment"]      | [X] weeks | [Status]                                        | [X/Y tasks]                                    |
+
+---
+
+## 📋 Phase Summaries
+
+### Phase 1: [Phase Name] ([X] weeks)
+
+**Goal**: [One-liner measurable outcome — e.g., "A user can create an account, log in, and see a functional dashboard with real data from PostgreSQL"]
+
+**Key Deliverables**:
+
+- [Deliverable with scope — e.g., "User authentication: signup, login, logout, JWT token management with refresh"]
+- [Deliverable with scope — e.g., "Database schema v1: core tables with migrations, seed data for development"]
+- [Deliverable with scope — e.g., "API foundation: health check, CORS, error handling middleware, request logging"]
+
+**Success Criteria**: [How we know it's done — e.g., "All auth flows work end-to-end, database migrations run cleanly, API returns proper error responses with correct HTTP status codes. Test coverage > 70% for auth module."]
+
+**Risks & Mitigations**: [Primary risk — e.g., "Schema design uncertainty: mitigate by starting with minimal tables and using migrations for evolution"]
+
+---
+
+### Phase 2: [Phase Name] ([X] weeks)
+
+**Goal**: [One-liner measurable outcome — describe the user-visible or system-visible outcome]
+
+**Key Deliverables**:
+
+- [Deliverable with scope — describe what's included and what's explicitly NOT included]
+- [Deliverable with scope — include measurable acceptance criteria where possible]
+
+**Success Criteria**: [How we know it's done — describe specific, testable conditions that must all be true]
+
+**Depends On**: [What must be complete from Phase 1 — e.g., "Auth system, database schema, API middleware stack"]
+
+---
+
+### Phase 3: [Phase Name] ([X] weeks)
+
+**Goal**: [One-liner measurable outcome]
+
+**Key Deliverables**:
+
+- [Deliverable with scope — e.g., "Rate limiting configured for all public endpoints"]
+- [Deliverable with scope — e.g., "Error monitoring with alerting for error rate spikes"]
+
+**Success Criteria**: [How we know it's done — e.g., "Application passes security audit checklist, monitoring dashboards show all services green, load test confirms < 200ms p95 under expected traffic"]
+
+**Depends On**: [What must be complete from previous phases]
+
+---
+
+## 🔗 Cross-Phase Dependencies
+
+> Understanding dependencies prevents starting work that will be blocked. Review before beginning each phase.
+
+```
+Phase 1: [Foundation]
+  └──▶ Phase 2: [Core Features]     (requires: auth, database, API foundation)
+        └──▶ Phase 3: [Production]   (requires: all features functional and tested)
+```
+
+| Dependency                                | Source Phase | Required By | Risk if Delayed                                                                         |
+| ----------------------------------------- | ------------ | ----------- | --------------------------------------------------------------------------------------- |
+| [Dependency — e.g., "Auth system"]        | Phase 1      | Phase 2     | [Impact — e.g., "Blocks all authenticated API endpoints and frontend protected routes"] |
+| [Dependency — e.g., "Core API endpoints"] | Phase 2      | Phase 3     | [Impact — e.g., "Cannot performance test or add monitoring without real endpoints"]     |
+
+---
+
+## 📊 Progress Tracking
+
+- **Completed Phases**: 0/[N]
+- **Current Phase**: Phase 1 — [Phase Name]
+- **Current Task**: [Task name or "Phase not yet started"]
+- **Overall Progress**: 0% — [X]/[Y] total tasks complete across all phases
+- **Estimated Completion**: [Date or "TBD after Phase 1 retrospective"]
+
+### Milestone Log
+
+| Date   | Milestone                             | Notes                                                                         |
+| ------ | ------------------------------------- | ----------------------------------------------------------------------------- |
+| [Date] | [Milestone — e.g., "Phase 1 started"] | [Context — e.g., "Initial kickstart complete, beginning auth implementation"] |
+
+---
+
+## 📐 Documentation Standards
+
+> Every phase follows the same structure for consistency and AI-friendly navigation.
+
+Each phase folder contains:
+
+- **README.md** — Generated from `docs/templates/PHASE_README_TEMPLATE.md`:
+  - Phase overview with goal and target state
+  - Quick stats (tasks, files, coverage targets)
+  - Key deliverables organized by sprint/week
+  - Success criteria (functional, quality, architecture)
+  - Risks and dependencies
+- **PHASE[N]\_TASKS.md** — Generated from `docs/phases/templates/TASK_TEMPLATE.md` via `/plan-phase`:
+  - Detailed task breakdown with checkbox sub-steps
+  - Dependencies and expected deliverables per task
+  - Rollback plans for risky tasks
+  - Progress tracking with completion metrics
+
+---
+
+## 🔗 Related Documents
+
+- **[[PRODUCTION_ROADMAP|Production Roadmap]]** — High-level roadmap with current status and success metrics
+- **[[WORKSTREAMS|Workstreams]]** — Live state of parallel work streams
+- **[[DECISIONS|Decisions Log]]** — ADRs that affect phase planning and architecture

package/payload/doc-templates/templates/PHASE_README_TEMPLATE.md

@@ -0,0 +1,142 @@
+---
+title: "Phase README Template"
+tags: [groundwork/template]
+aliases: []
+---
+
+# Phase [N]: [Phase Name]
+
+**Duration**: [X] weeks — [Brief justification for estimate, e.g., "3 sprints based on task complexity analysis"]
+**Status**: [🟢 Complete / 🟡 In Progress / ⚪ Not Started / 🔴 Blocked]
+**Priority**: [🔴 Critical / 🟡 High / 🟢 Medium] — [Context for priority, e.g., "Foundation phase — blocks all subsequent phases"]
+
+---
+
+## 📋 Phase Overview
+
+**Goal**: [One-liner measurable outcome — e.g., "Users can authenticate, access protected routes, and see a functional dashboard with real data from the database"]
+
+**Current State**: [Where things stand before this phase begins — describe existing functionality, infrastructure, and quality level. E.g., "Project scaffolding exists with monorepo, basic API health endpoint, React starter shell. No auth, no database, no real features."]
+
+**Target State**: [Where things should be after this phase completes — describe the delta in concrete terms. E.g., "Full auth flow (signup/login/logout/refresh), PostgreSQL with migrations, 5 core API endpoints, dashboard page consuming real data. Test coverage > 70% for new code."]
+
+---
+
+## 📊 Quick Stats
+
+- **Sprints**: [N] ([Sprint names — e.g., "Setup, Core, Integration"])
+- **Major Tasks**: [N] — [Brief description of task scope, e.g., "Each task represents a standalone deliverable that can be reviewed independently"]
+- **New Files**: ~[N] files (~[N] lines) — [Estimated scope, e.g., "Based on similar features in comparable projects"]
+- **Modified Files**: ~[N] files — [What existing files will change, e.g., "Mostly route registrations and type exports"]
+- **Database Changes**: [Description if applicable — e.g., "3 new tables (users, sessions, profiles) with migration scripts" or "None — this phase is frontend-only"]
+- **Test Coverage Target**: [N]%+ — [Scope of coverage, e.g., "Unit tests for all services, integration tests for API endpoints"]
+- **Performance Target**: [Metric and target — e.g., "Auth endpoints respond < 100ms p95" or "Dashboard loads < 2s on 3G"]
+
+---
+
+## 🎯 Key Deliverables
+
+### Sprint 1: [Sprint Name — e.g., "Setup & Foundation"] (Week [X])
+
+> [Sprint goal — one sentence describing what this sprint achieves]
+
+- [🟢 Complete / 🟡 In Progress / ⚪ Pending / 🔴 Blocked] **[Deliverable name]** — [What this delivers and how to verify it, e.g., "Database schema with migration scripts. Verified by running migrations on clean database and seeding test data."]
+- [Status] **[Deliverable name]** — [What this delivers and verification method]
+- [Status] **[Deliverable name]** — [What this delivers and verification method]
+
+### Sprint 2: [Sprint Name — e.g., "Core Implementation"] (Week [X])
+
+> [Sprint goal]
+
+- [Status] **[Deliverable name]** — [Description and verification]
+- [Status] **[Deliverable name]** — [Description and verification]
+
+### Sprint 3: [Sprint Name — e.g., "Integration & Testing"] (Week [X]-[Y])
+
+> [Sprint goal]
+
+- [Status] **[Deliverable name]** — [Description and verification]
+- [Status] **[Deliverable name]** — [Description and verification]
+
+---
+
+## ✅ Success Criteria
+
+> All criteria must be met before this phase is considered complete. Use these as a checklist during phase review.
+
+### Functional Requirements
+
+- [ ] [Requirement with testable condition — e.g., "User can sign up with email/password, receives confirmation, and can log in with those credentials"]
+- [ ] [Requirement with testable condition — e.g., "Protected API endpoints return 401 for unauthenticated requests and 200 with valid JWT"]
+- [ ] [Requirement with testable condition — e.g., "Dashboard page loads and displays real data from the database within 2 seconds"]
+
+### Quality Requirements
+
+- [ ] [Quality gate with measurable threshold — e.g., "Test coverage >= 70% for all new code (measured by coverage tool)"]
+- [ ] [Quality gate — e.g., "Zero TypeScript errors: `pnpm typecheck` passes across all packages"]
+- [ ] [Quality gate — e.g., "Zero linting errors: `pnpm lint` passes with no warnings"]
+- [ ] [Quality gate — e.g., "All API endpoints return proper error responses (not 500s) for invalid input"]
+
+### Architecture Requirements
+
+- [ ] [Architecture validation — e.g., "All new code follows feature-based organization as defined in ARCHITECTURE_GUIDE.md"]
+- [ ] [Architecture validation — e.g., "No direct database access from route handlers — all queries go through service layer"]
+- [ ] [Architecture validation — e.g., "Shared types used for all API request/response types — no inline type definitions"]
+
+---
+
+## ⚠️ Risks & Mitigation
+
+| Risk                                                                    | Impact                                                                                         | Likelihood                     | Mitigation Strategy                                                                                                                |
+| ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
+| [Specific risk — e.g., "Database schema needs revision mid-phase"]      | [🔴 High / 🟡 Medium / 🟢 Low — explain impact, e.g., "Cascading changes to API and frontend"] | [🔴 High / 🟡 Medium / 🟢 Low] | [Concrete mitigation — e.g., "Start with minimal schema, use migrations for all changes, avoid premature optimization of queries"] |
+| [Specific risk — e.g., "Third-party auth library has breaking changes"] | [Impact and explanation]                                                                       | [Likelihood]                   | [Mitigation — e.g., "Pin dependency version, test upgrade path before adopting, have fallback auth implementation"]                |
+| [Specific risk — e.g., "Scope creep from discovered requirements"]      | [Impact and explanation]                                                                       | [Likelihood]                   | [Mitigation — e.g., "Strict scope boundary: anything not in deliverables list goes to Phase N+1 backlog"]                          |
+
+---
+
+## 🔗 Dependencies
+
+- **Blocks**: [What this phase unblocks — e.g., "Phase 2 (Core Features) — cannot build authenticated features without auth system from this phase"]
+- **Required (must have)**: [What must be done before this phase can start — e.g., "Project scaffolding: monorepo, build system, and dev environment must be functional" or "None — this is the first phase"]
+- **Optional (nice to have)**: [Nice-to-have prerequisites that improve efficiency — e.g., "CI/CD pipeline: not required but speeds up validation" or "Design mockups: can start with wireframes and refine later"]
+
+### External Dependencies
+
+- [External dependency — e.g., "Database provisioning: PostgreSQL instance must be available (Docker Compose handles this locally)"]
+- [External dependency — e.g., "API keys: any third-party service credentials must be obtained and added to .env"]
+
+---
+
+## 🚀 Getting Started
+
+```bash
+# 1. Ensure you're on the correct branch
+git checkout -b feature/phase[N]-[name]
+
+# 2. Review the detailed task plan (generated by /plan-phase)
+# This file contains the step-by-step breakdown with checkboxes
+cat docs/phases/phase[N]/PHASE[N]_TASKS.md
+
+# 3. Check live workstreams
+cat docs/WORKSTREAMS.md
+
+# 4. Start with Task 1 (tasks are ordered by dependency — follow the sequence)
+# Each task has sub-steps; complete all sub-steps before marking the task done
+# Run tests after each task: [test command, e.g., "pnpm test"]
+# Verify types after each task: [typecheck command, e.g., "pnpm typecheck"]
+```
+
+### Before Starting Checklist
+
+- [ ] Read this README fully — understand the goal, deliverables, and success criteria
+- [ ] Read the detailed task plan (PHASE[N]\_TASKS.md) — understand the full scope
+- [ ] Ensure all **Required** dependencies are met
+- [ ] Confirm development environment is working (`pnpm dev` starts without errors)
+- [ ] Review relevant ADRs in [[DECISIONS]] that affect this phase
+
+---
+
+## ⏭️ Next Phase
+
+After completion: → [Phase N+1: [Name]](../phase[N+1]/) — [Brief description of what the next phase covers and how this phase enables it]