macca-method 1.1.0 → 2.1.1

package/.agents/skills/brainstorm-styleguide/SKILL.md

@@ -1,8 +1,10 @@
 ---
 name: brainstorm-styleguide
-description: Interview users and generate `StyleGuide.md` (UI/UX Design System). Use after the PRD or when defining the application's appearance.
-persona: "Akram"
-persona_role: "UI/UX Designer"
+description: Interviews users and generates `StyleGuide.md` covering visual tokens, components, accessibility, localization, responsive behavior, and operational UI states. Use only when the user explicitly requests a UI/UX contract.
+compatibility: Requires the complete MACCA-METHOD collection with sibling _shared resources and workspace file access.
+metadata:
+  persona: "Akram"
+  persona-role: "UI/UX Designer"
 ---
 
 # Brainstorm StyleGuide
@@ -41,13 +43,14 @@ This skill generates **StyleGuide.md** through an interactive interview. It prev
     - `project-context/architecture.md` — chosen frontend tech stack
     - If `.agents/developer-config.json` exists, read `developerPreferences.scope`
 
-3. **Shared Runtime Setup** — before the interview:
-    - Read `../_shared/references/runtime-config.md`.
+3. **Shared Runtime Setup** — before the interview (paths written as `../...` are relative to this SKILL.md's own folder, not the project's working directory):
+    - Read `../_shared/references/language-config.md`.
+    - Read `../_shared/references/config-mutation.md`.
     - Read `../_shared/references/brainstorm-session.md`.
     - Read `../_shared/references/scope-rules.md`.
     - Use `languagePreferences.communication.normalized` for chat.
     - Use `languagePreferences.documents.normalized` for the final `project-context/StyleGuide.md`.
-    - Apply `brainstormPreferences.discussionMode` and `brainstormPreferences.recommendations` using the shared session policy.
+    - Apply `brainstormPreferences.discussionMode`, `recommendations`, and `discoveryDepth` using the shared session policy.
     - For this skill: announce that there are 7 topics, ask for pacing (one by one / three at once / all at once), and ask for recommendation preference if it is not already stored.
 
 4. If scope = `backend`, DO NOT create `StyleGuide.md`. Explain that UI work is outside the current scope.
@@ -56,11 +59,11 @@ This skill generates **StyleGuide.md** through an interactive interview. It prev
 
 6. After all topics are complete, create `project-context/StyleGuide.md` (create `project-context/` if needed).
 
-   > ⚠️ **If the file already exists:** ask the user before overwriting — "(A) Replace the entire file, (B) cancel and review first." Wait for the answer.
+   > ⚠️ **If the file already exists:** "(A) Overwrite all, (B) Cancel and review first." Wait for the answer.
 
 7. Summarize the result and provide next steps.
 
-## Interview Topics (7)
+## Interview Topics (8)
 
 ### 1. CSS Framework
 **Ask:** *"What CSS framework is used: Tailwind, Bootstrap, or custom CSS?"*
@@ -129,138 +132,20 @@ This skill generates **StyleGuide.md** through an interactive interview. It prev
 - Default icon size (16px, 20px, 24px)
 - Need custom SVG icons?
 
-## Output Format (StyleGuide.md)
+### 8. Accessibility, Localization & Operational States
+**Ask:** *"Which accessibility target and non-happy-path states must the UI support: loading, empty, error, forbidden, offline, reduced motion, keyboard, screen reader, or localization?"*
 
-````markdown
-# StyleGuide
-
-> **Framework:** [CSS Framework] | **Approach:** [Utility-first / Component-based]
-
-## Document Role
-- **Source of Truth:** Visual system and UI conventions for this project
-- **Primary Owner:** `brainstorm-styleguide`
-- **Out of Scope:** Backend logic, API contracts, and non-UI technical architecture
+**Collect:**
+- Accessibility target from PRD (for example WCAG AA), keyboard order, visible focus, labels, contrast, touch targets, and reduced motion
+- Loading/skeleton, empty, error, disabled/read-only, permission-denied, offline, and partial-data behavior that applies to primary surfaces
+- Supported locales from PRD; text expansion, pluralization, date/number/currency/timezone formatting, and RTL only when relevant
+- UI performance constraints: font loading, asset/image strategy, motion budget, and component/render budget where relevant
 
-## Supported Surfaces
-| Surface | Included? | Notes |
-|---------|-----------|-------|
-| Web app | Yes / No | [notes] |
-| Admin panel | Yes / No | [notes] |
-| Marketing site | Yes / No | [notes] |
-| Email / PDF / export | Yes / No | [notes] |
+## StyleGuide.md Output
 
----
+After discovery is complete and immediately before generating `project-context/StyleGuide.md`, read `assets/StyleGuide.template.md`.
 
-## 1. CSS Framework
-- **Framework:** [Tailwind CSS v3 / Bootstrap 5 / CSS Modules / etc.]
-- **Version:** [version]
-- **Notes:** [Additional rules]
-
-## 2. Color Palette
-| Role | Hex | Tailwind | Description |
-|------|-----|----------|-------------|
-| Primary | `#xxx` | `bg-blue-600` | Main brand |
-| Secondary | `#xxx` | `bg-gray-600` | Accent |
-| Background | `#xxx` | `bg-gray-50` | Page background |
-| Surface | `#xxx` | `bg-white` | Card/panel background |
-| Primary Text | `#xxx` | `text-gray-900` | Main text |
-| Secondary Text | `#xxx` | `text-gray-500` | Secondary text |
-| Error | `#xxx` | `text-red-500` | Error message |
-| Success | `#xxx` | `text-green-500` | Success message |
-| Warning | `#xxx` | `text-yellow-500` | Warning message |
-| Info | `#xxx` | `text-blue-500` | Info message |
-
-**Dark Mode:** [Supported / Not supported]
-
-## 3. Typography
-- **Heading Font:** [Font Name] — via [Google Fonts / local]
-- **Body Font:** [Font Name] — via [Google Fonts / local]
-
-| Level | Size | Weight | Line Height |
-|-------|------|--------|-------------|
-| H1 | [size] | [weight] | [line-height] |
-| H2 | [size] | [weight] | [line-height] |
-| H3 | [size] | [weight] | [line-height] |
-| H4 | [size] | [weight] | [line-height] |
-| Body | [size] | regular | [line-height] |
-| Small | [size] | regular | [line-height] |
-| Caption | [size] | regular | [line-height] |
-
-## 4. Spacing System
-- **Base Unit:** [4px / 8px]
-- **Scale:** [Tailwind Default / Custom]
-
-| Token | Value | Tailwind |
-|-------|-------|----------|
-| xs | [4px] | `p-1` |
-| sm | [8px] | `p-2` |
-| md | [16px] | `p-4` |
-| lg | [24px] | `p-6` |
-| xl | [32px] | `p-8` |
-| 2xl | [48px] | `p-12` |
-
-## 5. Component Style
-- **Border Radius:** [rounded-md / rounded-lg / none]
-- **Shadow:** [shadow-sm / shadow-md / none]
-
-## Component Inventory
-| Component | Status | Notes |
-|-----------|--------|-------|
-| Button | Defined | [notes] |
-| Card | Defined | [notes] |
-| Input | Defined | [notes] |
-| Modal | Defined / Deferred | [notes] |
-| Table | Defined / Deferred | [notes] |
-
-### Button
-| Variant | Style |
-|---------|-------|
-| Primary | [bg-primary text-white rounded-md px-4 py-2] |
-| Secondary | [outline / ghost] |
-| Danger | [bg-error text-white] |
-
-### Card
-- Background: [surface color]
-- Border: [border style]
-- Shadow: [shadow level]
-- Padding: [padding value]
-
-### Input
-- Border: [border style]
-- Focus: [focus ring style]
-- Error state: [error border + message style]
-
-### Transition & Animation
-- **Default Duration:** [150ms / 200ms / 300ms]
-- **Easing:** [ease-in-out / ease-out]
-- **Pattern:** `transition-all duration-150 ease-in-out`
-
-## 6. Responsive & Breakpoints
-- **Approach:** [Mobile-first / Desktop-first]
-
-| Breakpoint | Value | Description |
-|------------|-------|-------------|
-| sm | [640px] | Small tablet |
-| md | [768px] | Tablet |
-| lg | [1024px] | Desktop |
-| xl | [1280px] | Large desktop |
-
-**Layout Rules:**
-- [Description of layout changes per breakpoint]
-
-## 7. Iconography
-- **Library:** [Lucide React / Heroicons / FontAwesome / etc.]
-- **Default Size:** [20px / 24px]
-- **Import Pattern:** `import { IconName } from 'lucide-react'`
-- **Notes:** [Rules for icon usage]
-
-## Non-Goals / Not Yet Defined
-- [UI areas intentionally outside this style guide]
-
-## Assumptions & Open Questions
-- [Assumption about branding, assets, or surface coverage]
-- [Question that needs confirmation]
-````
+Adapt only sections that are applicable and preserve every required contract from the interview. Do not load the template during early discovery.
 
 ---
 

package/.agents/skills/brainstorm-styleguide/assets/StyleGuide.template.md

@@ -0,0 +1,147 @@
+# StyleGuide
+
+> **Framework:** [CSS Framework] | **Approach:** [Utility-first / Component-based]
+
+## Document Role
+- **Source of Truth:** Visual system and UI conventions for this project
+- **Primary Owner:** `brainstorm-styleguide`
+- **Out of Scope:** Backend logic, API contracts, and non-UI technical architecture
+
+## Supported Surfaces
+| Surface | Included? | Notes |
+|---------|-----------|-------|
+| Web app | Yes / No | [notes] |
+| Admin panel | Yes / No | [notes] |
+| Marketing site | Yes / No | [notes] |
+| Email / PDF / export | Yes / No | [notes] |
+
+---
+
+## 1. CSS Framework
+- **Framework:** [Tailwind CSS v3 / Bootstrap 5 / CSS Modules / etc.]
+- **Version:** [version]
+- **Notes:** [Additional rules]
+
+## 2. Color Palette
+| Role | Hex | Tailwind | Description |
+|------|-----|----------|-------------|
+| Primary | `#xxx` | `bg-blue-600` | Main brand |
+| Secondary | `#xxx` | `bg-gray-600` | Accent |
+| Background | `#xxx` | `bg-gray-50` | Page background |
+| Surface | `#xxx` | `bg-white` | Card/panel background |
+| Primary Text | `#xxx` | `text-gray-900` | Main text |
+| Secondary Text | `#xxx` | `text-gray-500` | Secondary text |
+| Error | `#xxx` | `text-red-500` | Error message |
+| Success | `#xxx` | `text-green-500` | Success message |
+| Warning | `#xxx` | `text-yellow-500` | Warning message |
+| Info | `#xxx` | `text-blue-500` | Info message |
+
+**Dark Mode:** [Supported / Not supported]
+
+## 3. Typography
+- **Heading Font:** [Font Name] — via [Google Fonts / local]
+- **Body Font:** [Font Name] — via [Google Fonts / local]
+
+| Level | Size | Weight | Line Height |
+|-------|------|--------|-------------|
+| H1 | [size] | [weight] | [line-height] |
+| H2 | [size] | [weight] | [line-height] |
+| H3 | [size] | [weight] | [line-height] |
+| H4 | [size] | [weight] | [line-height] |
+| Body | [size] | regular | [line-height] |
+| Small | [size] | regular | [line-height] |
+| Caption | [size] | regular | [line-height] |
+
+## 4. Spacing System
+- **Base Unit:** [4px / 8px]
+- **Scale:** [Tailwind Default / Custom]
+
+| Token | Value | Tailwind |
+|-------|-------|----------|
+| xs | [4px] | `p-1` |
+| sm | [8px] | `p-2` |
+| md | [16px] | `p-4` |
+| lg | [24px] | `p-6` |
+| xl | [32px] | `p-8` |
+| 2xl | [48px] | `p-12` |
+
+## 5. Component Style
+- **Border Radius:** [rounded-md / rounded-lg / none]
+- **Shadow:** [shadow-sm / shadow-md / none]
+
+## Component Inventory
+| Component | Status | Notes |
+|-----------|--------|-------|
+| Button | Defined | [notes] |
+| Card | Defined | [notes] |
+| Input | Defined | [notes] |
+| Modal | Defined / Deferred | [notes] |
+| Table | Defined / Deferred | [notes] |
+
+### Button
+| Variant | Style |
+|---------|-------|
+| Primary | [bg-primary text-white rounded-md px-4 py-2] |
+| Secondary | [outline / ghost] |
+| Danger | [bg-error text-white] |
+
+### Card
+- Background: [surface color]
+- Border: [border style]
+- Shadow: [shadow level]
+- Padding: [padding value]
+
+### Input
+- Border: [border style]
+- Focus: [focus ring style]
+- Error state: [error border + message style]
+
+### Transition & Animation
+- **Default Duration:** [150ms / 200ms / 300ms]
+- **Easing:** [ease-in-out / ease-out]
+- **Pattern:** `transition-all duration-150 ease-in-out`
+
+## 6. Responsive & Breakpoints
+- **Approach:** [Mobile-first / Desktop-first]
+
+| Breakpoint | Value | Description |
+|------------|-------|-------------|
+| sm | [640px] | Small tablet |
+| md | [768px] | Tablet |
+| lg | [1024px] | Desktop |
+| xl | [1280px] | Large desktop |
+
+**Layout Rules:**
+- [Description of layout changes per breakpoint]
+
+## 7. Iconography
+- **Library:** [Lucide React / Heroicons / FontAwesome / etc.]
+- **Default Size:** [20px / 24px]
+- **Import Pattern:** `import { IconName } from 'lucide-react'`
+- **Notes:** [Rules for icon usage]
+
+## 8. Accessibility, Localization & Operational States
+- **Accessibility Target:** [PRD target / WCAG level]
+- **Keyboard & Focus:** [rules]
+- **Screen Reader & Labels:** [rules]
+- **Reduced Motion:** [behavior]
+
+| State | Required UI Behavior | Recovery/Action |
+|-------|----------------------|-----------------|
+| Loading | [skeleton/progress] | [wait/cancel] |
+| Empty | [message/CTA] | [next action] |
+| Error | [message/retry] | [recovery] |
+| Forbidden | [explanation] | [request access/back] |
+| Offline/Partial | [if applicable] | [sync/retry] |
+
+- **Locales & Text Expansion:** [supported locales or N/A]
+- **Formatting:** [date/number/currency/timezone]
+- **RTL:** [supported / N/A]
+- **UI Performance Budget:** [fonts/assets/motion/render constraints]
+
+## Non-Goals / Not Yet Defined
+- [UI areas intentionally outside this style guide]
+
+## Assumptions & Open Questions
+- [Assumption about branding, assets, or surface coverage]
+- [Question that needs confirmation]

package/.agents/skills/brainstorm-task/SKILL.md

@@ -1,21 +1,27 @@
 ---
 name: brainstorm-task
-description: Generate `Task.md` (Work Plan) from completed spec documents. Run after `PRD.md`, `architecture.md`, `schema.md`, `api.md`, and `rules.md` are complete.
-persona: "Galbi"
-persona_role: "Project Manager"
+description: Generates `Task.md` from the completed specs applicable to the project's declared scope. Use after `architecture.md` and all relevant product, data, API, UI, and coding-rule documents are ready, or when adding an approved phase to an existing plan.
+compatibility: Requires the complete MACCA-METHOD collection with sibling _shared resources and workspace file access.
+metadata:
+  persona: "Galbi"
+  persona-role: "Project Manager"
 ---
 
 # Brainstorm Task
 
 ## Shared Runtime Setup
 
+Paths written as `../...` below are relative to this SKILL.md's own folder, not the project's working directory - resolve them as a sibling of the folder that contains this file.
+
 Before starting:
 
-1. Read `../_shared/references/runtime-config.md`.
-2. Read `../_shared/references/brainstorm-session.md`.
-3. Use `languagePreferences.communication.normalized` for chat.
-4. Use `languagePreferences.documents.normalized` for the final `project-context/Task.md`.
-5. Apply `brainstormPreferences.recommendations` using the shared session policy.
+1. Read `../_shared/references/language-config.md`.
+2. Read `../_shared/references/config-mutation.md`.
+3. Read `../_shared/references/brainstorm-session.md`.
+4. Read `../_shared/references/scope-rules.md`.
+5. Use `languagePreferences.communication.normalized` for chat.
+6. Use `languagePreferences.documents.normalized` for the final `project-context/Task.md`.
+7. Apply `brainstormPreferences.recommendations` and `discoveryDepth` using the shared session policy.
 
 ## Character
 
@@ -51,7 +57,7 @@ This skill generates **Task.md**: a work plan derived from existing spec documen
 **Detect mode before starting:**
 Check whether `project-context/Task.md` already exists.
 - **Does not exist yet** → follow the steps below (New Generate Mode).
-- **Already exists** (usually called from `add-feature`) → enter **Add Phase Mode**: skip clarification topics 1 and 3 (already defined in the old `Task.md`), ask only topic 2 (granularity), then **append new phases/tasks below the existing content** without overwriting the `Task.md` header.
+- **Already exists** (usually called from `add-feature`) → enter **Add Phase Mode**: skip clarification topics 1 and 3, ask only topic 2, append the approved phases/tasks, and update header counts/date, Progress Overview, dependencies, and Traceability Matrix. Preserve unrelated existing phases and IDs.
 
 **Scope rules:**
 - `frontend` → generate frontend tasks only
@@ -119,7 +125,7 @@ Files: `PRD.md`, `architecture.md`, `schema.md`, `api.md`, `rules.md`, `StyleGui
 
 **architecture.md is required** — if it does not exist, **STOP** and ask the user to run `brainstorm-architecture` first.
 
-If other documents are missing, **inform the user** (do not ask first):
+If another document required by the declared scope is missing, inform the user and obtain one continuation decision:
 > *"I checked: `project-context/[filename]` was not found. It is recommended to complete it first so tasks are more accurate. Continue with the available documents?"*
 
 ## Deep Analysis (Before Creating Tasks)
@@ -129,13 +135,14 @@ Before writing `Task.md`, analyze internally:
 1. Read `PRD.md` → list all MVP features → this is the task scope
 2. Read `StyleGuide.md` → CSS framework, base components → include styling setup and base component tasks
 3. Read `architecture.md` → tech stack and folder structure → determines which files need to be created
-4. Read `schema.md` → all tables → each table needs a migration + model/schema file
-5. Read `api.md` → all endpoints → each endpoint needs route + controller + service
+4. Read `schema.md` → map each datastore-native entity/collection/aggregate/stream to the migrations, validation, model, projection, or infrastructure tasks its architecture actually requires
+5. Read `api.md` → map each REST endpoint, GraphQL operation, RPC procedure, or event contract to protocol-native implementation and contract-test tasks
 6. Read `rules.md` → coding standards → include tasks for ESLint, Prettier, tsconfig setup?
 7. Identify task dependencies (database before model, model before service, service before controller)
-8. **TDD:** Every implementation task (service, endpoint, component) must be preceded by a test task. Format: Task N.1 = write test, Task N.2 = implement (dependency: N.2 depends on N.1 being complete).
+8. **Testing workflow:** Follow the policy in `rules.md`. If it requires test-first/TDD, precede implementation with a test task. Otherwise pair each behavior change with the test/verification task required by the approved rules. Do not force TDD against project policy.
 9. If the specs mention security controls, create explicit security tasks — do not leave them implicit. Examples: auth guards, ownership checks, input validation, secure cookie config, rate limiting, CSRF protection, audit logs, data masking.
 10. Create a **traceability matrix**: every main requirement (`FEAT-*`, `BR-*`, `NFR-*`, `API-*`, `DATA-*`) must have at least one task that references it.
+11. Derive a phase Definition of Done from applicable specs. Do not ask another question: include tests/checks, security, migration/backfill, observability, documentation, rollout/rollback evidence, spec-compliance, and code-review only when relevant.
 
 After analysis, **show the scope summary to the user**:
 
@@ -159,101 +166,11 @@ Is this scope correct? Anything to add or remove?
 
 Wait for user confirmation before creating Task.md.
 
-## Output Format (Task.md)
-
-````markdown
-# Task: [Project Name]
-
-> **Total Phases:** [X] | **Total Tasks:** [Y] | **Last Updated:** [date]
-
-## Document Role
-- **Source of Truth:** Execution plan derived from approved spec documents
-- **Primary Owner:** `brainstorm-task`
-- **Out of Scope:** New product scope, new schema/API decisions, and code quality review findings
-
-## Upstream Dependencies
-| Topic | Canonical Source |
-|------|------------------|
-| Product scope | `project-context/PRD.md` |
-| Technical structure | `project-context/architecture.md` |
-| Data contract | `project-context/schema.md` |
-| API contract | `project-context/api.md` |
-| UI contract | `project-context/StyleGuide.md` |
-| Coding rules | `project-context/rules.md` |
+## Task.md Output
 
-## Execution Rules
-- Work on tasks **one by one** in order within each phase.
-- After each **phase** is complete, **STOP** and wait for user confirmation before the next phase.
-- Update status `[ ]` to `[x]` when a task is complete.
-- If a task is blocked, mark it `[~]` and note the reason.
+After discovery is complete and immediately before generating `project-context/Task.md`, read `assets/Task.template.md`.
 
----
-
-## Progress Overview
-| Phase | Name | Status | Progress |
-|------|------|--------|----------|
-| 1 | [Setup & Configuration] | [ ] | 0/3 |
-| 2 | [Database & Models] | [ ] | 0/4 |
-| 3 | [Backend: Auth] | [ ] | 0/3 |
-
-## AI Read Order
-1. Read `Execution Rules`
-2. Read `Progress Overview`
-3. Read only the current phase
-4. Use `References` and `Traceability IDs` before searching elsewhere
-
----
-
-## Phase 1: [Phase Name]
-> **Dependency:** None (first phase)
-> **Goal:** [What must be complete at the end of this phase]
-
-- [ ] **Task 1.1: [Task Name]**
-  - **Files:** `[path/file created or modified]`
-  - **Description:** [What is done, briefly]
-  - **References:** [`project-context/architecture.md#section` / `project-context/rules.md#section`]
-  - **Traceability IDs:** [`FEAT-01` / `BR-01` / `API-01` / `DATA-01`]
-  - **Acceptance Criteria:**
-    - [ ] [Testable condition 1]
-    - [ ] [Testable condition 2]
-
-- [ ] **Task 1.2: [Task Name]**
-  - **Files:** `[path/file]`
-  - **Description:** [Briefly what is done]
-  - **Dependencies:** Task 1.1 must be complete first
-  - **References:** [`project-context/schema.md#users`]
-  - **Traceability IDs:** [`FEAT-01` / `DATA-01`]
-  - **Acceptance Criteria:**
-    - [ ] [Testable condition]
-
----
-
-## Phase 2: [Phase Name]
-> **Dependency:** Phase 1 must be complete
-> **Goal:** [Phase goal]
-
-- [ ] **Task 2.1: [Task Name]**
-  - **Files:** `[path/file]`
-  - **Description:** [Brief]
-  - **References:** [`project-context/api.md#auth`]
-  - **Traceability IDs:** [`FEAT-01` / `API-01` / `NFR-02`]
-  - **Acceptance Criteria:**
-    - [ ] [Testable condition]
-
----
-
-## Traceability Matrix
-| Requirement ID | Source | Covering Tasks |
-|----------------|--------|----------------|
-| FEAT-01 | `project-context/PRD.md` | `Task 1.1`, `Task 1.2`, `Task 2.1` |
-| BR-01 | `project-context/PRD.md` | `Task 1.1` |
-| API-01 | `project-context/api.md` | `Task 2.1` |
-| DATA-01 | `project-context/schema.md` | `Task 1.2` |
-
-## Assumptions & Open Questions
-- [Assumption that affects planning granularity or order]
-- [Open question that may change future phases]
-````
+Adapt only sections that are applicable and preserve every required contract from the interview. Do not load the template during early discovery.
 
 ---
 
@@ -269,7 +186,7 @@ Wait for user confirmation before creating Task.md.
 - **Tasks MUST be derived from existing specs**. Do not brainstorm from scratch again.
 - Every task must have **testable acceptance criteria**, not just a description.
 - Mark **task dependencies** clearly. AI cannot skip tasks.
-- **TDD:** Implementation tasks are preceded by test tasks (N.1 write test, N.2 implement; N.2 depends on N.1).
+- **Testing:** Task order follows the approved testing workflow in `rules.md`; test-first is required only when that policy requires it.
 - If the specs mention security controls, create explicit security tasks. Do not assume they "happen automatically."
 - Every task must have **Traceability IDs** that reference real upstream requirements or artifacts.
 - A **Traceability Matrix** is required for auditability.

package/.agents/skills/brainstorm-task/assets/Task.template.md

@@ -0,0 +1,113 @@
+# Task: [Project Name]
+
+> **Total Phases:** [X] | **Total Tasks:** [Y] | **Last Updated:** [date]
+
+## Document Role
+- **Source of Truth:** Execution plan derived from approved spec documents
+- **Primary Owner:** `brainstorm-task`
+- **Out of Scope:** New product scope, new schema/API decisions, and code quality review findings
+
+## Upstream Dependencies
+| Topic | Canonical Source |
+|------|------------------|
+| Product scope | `project-context/PRD.md` |
+| Technical structure | `project-context/architecture.md` |
+| Data contract | `project-context/schema.md` |
+| API contract | `project-context/api.md` |
+| UI contract | `project-context/StyleGuide.md` |
+| Coding rules | `project-context/rules.md` |
+
+## Execution Rules
+- Work on tasks **one by one** in order within each phase.
+- After each **phase** is complete, **STOP** and wait for user confirmation before the next phase.
+- Update status `[ ]` to `[x]` when a task is complete.
+- If a task is blocked, mark it `[~]` and note the reason.
+
+---
+
+## Progress Overview
+| Phase | Name | Status | Progress |
+|------|------|--------|----------|
+| 1 | [Setup & Configuration] | [ ] | 0/3 |
+| 2 | [Database & Models] | [ ] | 0/4 |
+| 3 | [Backend: Auth] | [ ] | 0/3 |
+
+## AI Read Order
+1. Read `Execution Rules`
+2. Read `Progress Overview`
+3. Read only the current phase
+4. Use `References` and `Traceability IDs` before searching elsewhere
+
+---
+
+## Phase 1: [Phase Name]
+> **Dependency:** None (first phase)
+> **Goal:** [What must be complete at the end of this phase]
+
+### Phase Definition of Done
+- [ ] Applicable acceptance criteria pass
+- [ ] Required tests/build/type/lint checks pass
+- [ ] Required security controls are verified
+- [ ] Migration/backfill and failure recovery are verified when applicable
+- [ ] Required logs/metrics/alerts are present when applicable
+- [ ] Documentation and rollout notes are updated when applicable
+- [ ] `spec-compliance` passes
+- [ ] `code-review` passes
+
+- [ ] **Task 1.1: [Task Name]**
+  - **Files:** `[path/file created or modified]`
+  - **Description:** [What is done, briefly]
+  - **References:** [`project-context/architecture.md#section` / `project-context/rules.md#section`]
+  - **Traceability IDs:** [`FEAT-01` / `BR-01` / `API-01` / `DATA-01`]
+  - **Acceptance Criteria:**
+    - [ ] [Testable condition 1]
+    - [ ] [Testable condition 2]
+
+- [ ] **Task 1.2: [Task Name]**
+  - **Files:** `[path/file]`
+  - **Description:** [Briefly what is done]
+  - **Dependencies:** Task 1.1 must be complete first
+  - **References:** [`project-context/schema.md#users`]
+  - **Traceability IDs:** [`FEAT-01` / `DATA-01`]
+  - **Acceptance Criteria:**
+    - [ ] [Testable condition]
+
+---
+
+## Phase 2: [Phase Name]
+> **Dependency:** Phase 1 must be complete
+> **Goal:** [Phase goal]
+
+### Phase Definition of Done
+- [ ] Applicable acceptance criteria pass
+- [ ] Required tests/build/type/lint checks pass
+- [ ] Required security controls are verified
+- [ ] Migration/backfill and failure recovery are verified when applicable
+- [ ] Required logs/metrics/alerts are present when applicable
+- [ ] Documentation and rollout notes are updated when applicable
+- [ ] `spec-compliance` passes
+- [ ] `code-review` passes
+
+- [ ] **Task 2.1: [Task Name]**
+  - **Files:** `[path/file]`
+  - **Description:** [Brief]
+  - **References:** [`project-context/api.md#auth`]
+  - **Traceability IDs:** [`FEAT-01` / `API-01` / `NFR-02`]
+  - **Acceptance Criteria:**
+    - [ ] [Testable condition]
+
+---
+
+## Traceability Matrix
+| Requirement ID | Source | Covering Tasks |
+|----------------|--------|----------------|
+| FEAT-01 | `project-context/PRD.md` | `Task 1.1`, `Task 1.2`, `Task 2.1` |
+| BR-01 | `project-context/PRD.md` | `Task 1.1` |
+| API-01 | `project-context/api.md` | `Task 2.1` |
+| DATA-01 | `project-context/schema.md` | `Task 1.2` |
+
+## Assumptions & Open Questions
+- [Assumption that affects planning granularity or order]
+- [Open question that may change future phases]
+
+Repeat the `Phase Definition of Done` block for every generated phase, adapting items to the phase scope.