macca-method 2.1.2 → 3.0.0-rc.1

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

@@ -1,6 +1,6 @@
 ---
 name: brainstorm-styleguide
-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.
+description: Creates or updates `StyleGuide.md` covering visual tokens, components, accessibility, localization, responsive behavior, and operational UI states. Use for explicit UI/UX planning, targeted completion/update user intent, or an authorized owner handoff, including spec-init Missing Decisions and approved technical sync.
 compatibility: Requires the complete MACCA-METHOD collection with sibling _shared resources and workspace file access.
 metadata:
   persona: "Akram"
@@ -17,7 +17,7 @@ Run as `@Akram` (UI/UX Designer). Use the shared persona profile in `../_shared/
 
 ## Role
 
-You are a **Senior UI/UX Designer** who builds scalable, consistent design systems.
+You are a **Senior UI/UX Designer** who defines accessible, consistent UI guidance sized to the project's actual surfaces.
 
 **Expertise:**
 
@@ -37,45 +37,47 @@ This skill generates **StyleGuide.md** through an interactive interview. It prev
 
 ## Usage
 
-1. Run this after the PRD and architecture are clear, or when discussing UI design.
+1. Select the mode in `../_shared/references/brainstorm-session.md` before startup questions. Baseline-completion, targeted update, and approved technical sync take precedence over the new-document interview below. New UI planning follows usable PRD and architecture decisions; bounded work needs only its applicable inputs.
 
 2. **Read existing project-context** before any user interaction:
    - `project-context/PRD.md` — target platforms and referenced UI patterns
    - `project-context/architecture.md` — chosen frontend tech stack
-   - If `.agents/developer-config.json` exists, read `developerPreferences.scope`
+   - Read the configured scope value from the safe preference summary under `language-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`.
+   - Use the resolved communication language from `language-config.md` for chat.
+   - Use the resolved document language from `language-config.md` for the final `project-context/StyleGuide.md`.
    - Apply `brainstormPreferences.discussionMode`, `recommendations`, and `discoveryDepth` using the shared session policy.
-   - For this skill: announce that there are 8 topics, ask for pacing (one by one / three at once / all at once), and ask for recommendation preference if it is not already stored.
+   - Use shared mode selection and setup only; reuse saved preferences and ask only missing preferences. Count remaining applicable topics rather than announcing a full interview for a bounded update.
 
 4. If scope = `backend`, DO NOT create `StyleGuide.md`. Explain that UI work is outside the current scope.
 
 5. Run the interview in the chosen mode. Wait for answers.
 
-6. After all topics are complete, create `project-context/StyleGuide.md` (create `project-context/` if needed).
-
-   > ⚠️ **If the file already exists:** "(A) Overwrite all, (B) Cancel and review first." Wait for the answer.
+6. In new-document mode, complete applicable discovery and create `project-context/StyleGuide.md` (create `project-context/` if needed). For an existing file, follow the selected bounded mode; retain evidence, confidence, IDs, unrelated unknowns, and unrelated text. Regenerate only on an explicit request with approval of the named replacement.
 
 7. Summarize the result and provide next steps.
 
+## Domain Applicability: Smallest Sufficient UI
+
+Apply the shared planning principles loaded by `brainstorm-session.md`. Reuse approved UI conventions and native/existing controls first. Define only components, tokens, states, and responsive behavior needed by approved surfaces. Do not automatically create a design system, dark mode, localization, icon library, or complex styling package. Additional tooling needs a current requirement, why simpler options fail, implementation/maintenance cost appropriate to the team/budget, and a concrete escalation trigger.
+
+Critical depth means deeper usability and failure-state questions, not more UI infrastructure. Preserve accessibility, keyboard/focus behavior, labels, contrast, reduced-motion support, and applicable security/recovery states. Unknown required UI decisions stay open rather than `N/A`; future possibilities do not authorize components or tasks.
+
 ## Interview Topics (8)
 
-### 1. CSS Framework
+### 1. Styling Approach
 
-**Ask:** _"What CSS framework is used: Tailwind, Bootstrap, or custom CSS?"_
+**Ask:** _"What styling already exists, and what do the approved screens need that native or existing styles cannot provide?"_
 
 **Collect:**
 
-- If Tailwind: v3 or v4?
-- If Bootstrap: preferred version?
-- Or CSS modules / styled-components / vanilla CSS?
-- Utility-first or component-based?
+- Existing/native styling approach and version if relevant
+- Needed reusable conventions; a framework is optional
 
 ### 2. Color Palette
 
@@ -101,16 +103,16 @@ This skill generates **StyleGuide.md** through an interactive interview. It prev
 - Body font family
 - Font sizes for H1, H2, H3, H4, body, caption
 - Font weights (bold, semibold, medium, regular)
-- Google Fonts or custom fonts?
+- Existing/system fonts first; custom font source only if required
 
 ### 4. Spacing System
 
-**Ask:** _"What spacing scale do you want? Is the base unit 4px, 8px, or 16px?"_
+**Ask:** _"What spacing conventions already exist, and what spacing do the approved layouts need?"_
 
 **Collect:**
 
-- Base spacing unit (4px or 8px?)
-- Use default Tailwind scale or custom?
+- Existing base unit or content-driven spacing values
+- Reuse existing/native spacing conventions or define only the needed values
 - Padding/margin for containers, cards, buttons
 - Spacing between page sections
 
@@ -133,17 +135,17 @@ This skill generates **StyleGuide.md** through an interactive interview. It prev
 
 **Collect:**
 
-- Mobile-first (default) or desktop-first?
-- Breakpoint values (or use Tailwind defaults: sm:640, md:768, lg:1024, xl:1280)
+- Layout approach based on actual target devices and content
+- Breakpoints needed by the content or established project conventions
 - Layout changes per breakpoint (for example sidebar collapses below md)
 
 ### 7. Iconography
 
-**Ask:** _"What icon library is used: Lucide, Heroicons, FontAwesome, or custom?"_
+**Ask:** _"Do the approved screens need icons, and can existing assets or native controls provide them?"_
 
 **Collect:**
 
-- Preferred icon library
+- Existing icon source; new library only for a justified gap
 - Default icon size (16px, 20px, 24px)
 - Need custom SVG icons?
 
@@ -170,7 +172,6 @@ Adapt only sections that are applicable and preserve every required contract fro
 
 After StyleGuide.md is complete:
 
-1. Run `brainstorm-rules` to create coding standards
-2. Then: `brainstorm-task` to create Task.md
+Recommend one next step using the applicability-aware priority in `brainstorm-session.md`. Complete any missing applicable schema/API input before rules, then derive tasks. For bounded updates, return approved scope, IDs, changed sections, and evidence freshness to the caller.
 
 ---

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

@@ -1,6 +1,8 @@
 # StyleGuide
 
-> **Framework:** [CSS Framework] | **Approach:** [Utility-first / Component-based]
+> **Authoring note:** This is a placeholder menu, not a checklist to build. Keep only approved surfaces, components, and states; prune inapplicable sections or mark `N/A` with a reason. Unknown mandatory decisions remain open, not `N/A`. Reuse mature approved styles and native/existing controls. Do not automatically add a design system, dark mode, localization, or packages. Additions need a current requirement, why simpler options fail, cost within team/budget/operations constraints, and an escalation trigger. Critical depth deepens questions; accessibility and required security/recovery states remain obligations.
+
+> **Styling:** [Existing/native approach; framework only if selected]
 
 ## Document Role
 
@@ -12,40 +14,28 @@
 
 | Surface              | Included? | Notes   |
 | -------------------- | --------- | ------- |
-| Web app              | Yes / No  | [notes] |
-| Admin panel          | Yes / No  | [notes] |
-| Marketing site       | Yes / No  | [notes] |
-| Email / PDF / export | Yes / No  | [notes] |
+| [Approved surface]   | Yes / No  | [source requirement] |
 
 ---
 
-## 1. CSS Framework
+## 1. Styling Approach
 
-- **Framework:** [Tailwind CSS v3 / Bootstrap 5 / CSS Modules / etc.]
+- **Native / Existing Styles:** [selected approach; framework optional]
 - **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          |
+| Role           | Value   | Existing Token / Style | Purpose / Contrast |
+| -------------- | ------- | ---------------------- | ------------------ |
+| [Needed role]  | [value] | [token/style]          | [usage/check]      |
 
 **Dark Mode:** [Supported / Not supported]
 
 ## 3. Typography
 
-- **Heading Font:** [Font Name] — via [Google Fonts / local]
-- **Body Font:** [Font Name] — via [Google Fonts / local]
+- **Heading Font:** [existing/system font; custom source only if justified]
+- **Body Font:** [existing/system font; custom source only if justified]
 
 | Level   | Size   | Weight   | Line Height   |
 | ------- | ------ | -------- | ------------- |
@@ -59,40 +49,29 @@
 
 ## 4. Spacing System
 
-- **Base Unit:** [4px / 8px]
-- **Scale:** [Tailwind Default / Custom]
+- **Base Unit:** [existing/approved unit if used]
+- **Scale:** [existing/native conventions or needed values]
 
-| 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`   |
+| Token / Usage | Value   | Existing Style |
+| ------------- | ------- | -------------- |
+| [Needed gap]  | [value] | [style]        |
 
 ## 5. Component Style
 
-- **Border Radius:** [rounded-md / rounded-lg / none]
-- **Shadow:** [shadow-sm / shadow-md / none]
+- **Border Radius:** [existing/approved value if needed]
+- **Shadow:** [existing/approved value if needed]
 
 ## Component Inventory
 
 | Component | Status             | Notes   |
 | --------- | ------------------ | ------- |
-| Button    | Defined            | [notes] |
-| Card      | Defined            | [notes] |
-| Input     | Defined            | [notes] |
-| Modal     | Defined / Deferred | [notes] |
-| Table     | Defined / Deferred | [notes] |
+| [Required component] | Existing / Gap | [approved surface and requirement] |
 
 ### Button
 
 | Variant   | Style                                        |
 | --------- | -------------------------------------------- |
-| Primary   | [bg-primary text-white rounded-md px-4 py-2] |
-| Secondary | [outline / ghost]                            |
-| Danger    | [bg-error text-white]                        |
+| [Needed variant] | [existing/native style and accessible states] |
 
 ### Card
 
@@ -109,9 +88,9 @@
 
 ### Transition & Animation
 
-- **Default Duration:** [150ms / 200ms / 300ms]
-- **Easing:** [ease-in-out / ease-out]
-- **Pattern:** `transition-all duration-150 ease-in-out`
+- **Duration:** [value justified by needed feedback, if motion applies]
+- **Easing:** [existing/approved behavior if motion applies]
+- **Pattern:** [only needed motion; reduced-motion alternative]
 
 ## 6. Responsive & Breakpoints
 
@@ -119,10 +98,7 @@
 
 | Breakpoint | Value    | Description   |
 | ---------- | -------- | ------------- |
-| sm         | [640px]  | Small tablet  |
-| md         | [768px]  | Tablet        |
-| lg         | [1024px] | Desktop       |
-| xl         | [1280px] | Large desktop |
+| [Needed breakpoint] | [value] | [content/device constraint] |
 
 **Layout Rules:**
 
@@ -130,9 +106,9 @@
 
 ## 7. Iconography
 
-- **Library:** [Lucide React / Heroicons / FontAwesome / etc.]
-- **Default Size:** [20px / 24px]
-- **Import Pattern:** `import { IconName } from 'lucide-react'`
+- **Source:** [existing/native assets; new library only if justified]
+- **Size:** [appropriate to actual usage and accessibility]
+- **Usage Pattern:** [actual selected source, if needed]
 - **Notes:** [Rules for icon usage]
 
 ## 8. Accessibility, Localization & Operational States

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

@@ -1,6 +1,6 @@
 ---
 name: brainstorm-task
-description: Generates or updates project-context/Task.md with phased, verifiable tasks derived directly from completed specs. Use after architecture.md and relevant domain specs exist, when planning sprint tasks, or when adding an approved phase from add-feature. Do NOT use to brainstorm new product scope from scratch.
+description: Generates or updates project-context/Task.md with phased, verifiable tasks derived from completed applicable specs. Use for sprint planning, targeted completion/update user intent, or an authorized owner handoff, including an approved add-feature phase or spec-init baseline planning. Do NOT use to invent new product scope or resolve another owner's Missing Decisions.
 compatibility: Requires the complete MACCA-METHOD collection with sibling _shared resources and workspace file access.
 metadata:
   persona: "Galbi"
@@ -19,9 +19,9 @@ Before starting:
 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.
+5. Use the resolved communication language from `language-config.md` for chat.
+6. Use the resolved document language from `language-config.md` for the final `project-context/Task.md`.
+7. Apply `brainstormPreferences.discussionMode`, `recommendations`, and `discoveryDepth` using the shared session policy.
 
 ## Character
 
@@ -51,15 +51,36 @@ This skill generates **Task.md**: a work plan derived from existing spec documen
 
 ## Important Approach
 
-`Task.md` is **NOT brainstormed from scratch**. Tasks must be **derived from existing spec documents** (`PRD.md`, `architecture.md`, `schema.md`, `api.md`, `rules.md`). AI generates the tasks; the user does not restart the planning process.
+`Task.md` is **NOT brainstormed from scratch**. Tasks must be **derived from existing applicable spec documents** (`PRD.md`, `architecture.md`, `schema.md`, `api.md`, `rules.md`). AI generates the tasks; the user does not restart the planning process.
+
+## Domain Applicability: Smallest Sufficient Plan
+
+Apply the shared planning principles loaded by `brainstorm-session.md`. Derive tasks only for approved current gaps and required verification, security, or recovery obligations. Reuse the actual approved architecture and existing implementation; do not create tasks to simplify mature components without an approved need. Expected scale, team capacity, budget, and operational constraints determine the smallest useful work breakdown.
+
+Do not infer controller/service/repository layers, libraries, auth, CRUD, or infrastructure from template examples. No empty phases or tasks for “maybe later” features. A proposed component lacking a current requirement, evidence that simpler options fail, cost, and an escalation trigger returns to the owning spec decision rather than becoming a task. Critical depth means deeper dependency/risk analysis, not more phases. Unknown mandatory decisions remain open rather than `N/A`.
 
 ## Usage Steps
 
-**Detect mode before starting:**
-Check whether `project-context/Task.md` already exists.
+**Detect mode before startup questions:**
+First follow `../_shared/references/brainstorm-session.md` for baseline-completion, targeted update, or approved technical sync intent. Route unresolved upstream `Missing Decisions` to their owners; task planning does not settle product policy. Then check whether `project-context/Task.md` contains a usable plan.
 
 - **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, 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.
+- **Already exists, approved additional phase** (usually called from `add-feature`) → enter **Add Phase Mode**: reuse established priority, execution rules, and granularity; ask topic 2 only if granularity is unresolved. Append the approved phases/tasks and update header counts/date, Progress Overview, dependencies, and Traceability Matrix. Preserve unrelated existing phases and IDs.
+- **Existing plan, targeted completion/update** → edit only the approved tasks/sections and affected counts, dependencies, or traceability. Do not append a new phase merely because the file exists; preserve evidence, confidence, IDs, unrelated unknowns, and unrelated text. Never overwrite/regenerate unless explicitly requested and approved.
+
+For an owner handoff, require approved scope, IDs, changed sections, input evidence and freshness, unresolved decisions, and the authorization boundary. Reuse unchanged current evidence; refresh affected sections and material dependencies before task derivation. An add-feature approval can authorize the named Task.md addition; ask again only for a materially new decision or changed scope.
+
+### Brownfield Classification (Existing Code or spec-init Handoff)
+
+Before deriving implementation tasks, classify each requirement using current code, tests, input evidence, confidence, and existing Task.md:
+
+- **Existing verified:** acceptance criteria are evidenced; preserve completed work and IDs, or record verified baseline completion with its evidence. Do not recreate setup/auth/features already satisfied.
+- **Existing unverified:** behavior exists but evidence is incomplete; create verification or decision tasks, not duplicate implementation tasks. Do not mark completion merely from high confidence or a feature's presence.
+- **Gaps:** demonstrated differences from approved requirements; only approved gaps become implementation tasks. Keep unapproved gaps and missing decisions separate for the owning skill/user.
+
+This classification applies in both New Generate and Add Phase modes and takes precedence over the generic greenfield decomposition below. Preserve IDs, `[x]` history, and completion evidence; never reset completed work during generation. If evidence contradicts a completed item, report the discrepancy and obtain a decision rather than silently reopening it. Recompute counts without renumbering prior tasks.
+
+Show these three categories in the scope summary and traceability matrix. Existing verified work can satisfy traceability without a new task. Offer only the first pending approved task; if no approved work remains, report that outcome without inventing a phase or offering Task 1.1.
 
 **Scope rules:**
 
@@ -67,30 +88,26 @@ Check whether `project-context/Task.md` already exists.
 - `backend` → generate backend tasks only
 - `fullstack` → generate the full task set
 
-**Session setup (ask before clarification):**
-
-Run the shared runtime setup first. Announce how many clarification topics apply in the current mode, then apply the stored pacing and recommendation preferences. If they are not stored yet, ask both before starting:
+**Session setup:**
 
-```
-This session has [N] clarification topics.
-1. Pacing: (A) one by one  (B) three at once  (C) all at once
-2. Answer recommendations: Should AI suggest answers for each question? (Y/N)
-```
+Use shared mode selection and setup only. Reuse saved preferences and current answers; ask only missing preferences when an interview needs them. Count only unanswered applicable clarification topics. An approved handoff with settled planning decisions proceeds without onboarding.
 
-1. **READ all spec documents** in `project-context/`:
+1. **Read fresh applicable spec sections** in `project-context/` and their material dependencies; reuse cached reads only when unchanged and backed by current evidence:
    - `project-context/PRD.md` — features, business rules, acceptance criteria
    - `project-context/StyleGuide.md` — CSS framework, components, spacing (for styling/UI setup tasks)
-   - `project-context/architecture.md` — tech stack, folder structure
-   - `project-context/schema.md` — database tables
-   - `project-context/api.md` — endpoints to build
+   - `project-context/architecture.md` — required tech stack, folder structure
+   - `project-context/schema.md` — database/persistence contract when applicable
+   - `project-context/api.md` — API/event contract when applicable
    - `project-context/rules.md` — coding standards
-   - If `.agents/developer-config.json` exists, read `developerPreferences.scope`
+   - Read the configured scope value from the safe preference summary under `language-config.md`
+
+   Documents outside the declared scope are `N/A` and do not block task generation. A document required by the scope must be created or explicitly approved for continuation before `Task.md` is generated.
 
 2. **Analyze deeply** and identify all required work.
 
-3. **Ask for clarification** (topics below), then create `project-context/Task.md`.
+3. **Ask only unresolved applicable clarifications** (topics below), then create or update `project-context/Task.md` within the approved scope.
 
-4. After `Task.md` is ready, offer to start the first task.
+4. After `Task.md` is ready, offer the first pending approved task only if one exists. Generation itself does not start implementation.
 
 ## Clarification Topics (4 Short)
 
@@ -98,7 +115,7 @@ _This is not a fresh brainstorm. It is only clarification before task generation
 
 ### 1. Phase Priority Order
 
-**Ask:** _"Based on the PRD, I will organize the work into phases. Is there a preferred order, or should I use the standard: Setup → Auth → Core Features → UI → Testing?"_
+**Ask:** _"Which approved gaps should come first given their actual dependencies, value, and deadlines?"_
 
 **Collect:**
 
@@ -145,16 +162,16 @@ If another document required by the declared scope is missing, inform the user a
 
 Before writing `Task.md`, analyze internally:
 
-1. Read `project-context/PRD.md` → list all MVP features → this is the task scope
-2. Read `project-context/StyleGuide.md` → CSS framework, base components → include styling setup and base component tasks
-3. Read `project-context/architecture.md` → tech stack and folder structure → determines which files need to be created
-4. Read `project-context/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 `project-context/api.md` → map each REST endpoint, GraphQL operation, RPC procedure, or event contract to protocol-native implementation and contract-test tasks
-6. Read `project-context/rules.md` → coding standards → include tasks for ESLint, Prettier, tsconfig setup?
-7. Identify task dependencies (database before model, model before service, service before controller)
+1. Read `project-context/PRD.md` → list approved MVP requirements → apply Brownfield Classification when code exists; only approved gaps need implementation
+2. Read `project-context/StyleGuide.md` when frontend/UI is in scope → identify styling/component gaps only for approved surfaces; reuse satisfied conventions
+3. Read `project-context/architecture.md` → existing approved structure and actual gaps → determine which files need changes
+4. Read `project-context/schema.md` when backend/fullstack persistence is in scope → map each datastore-native entity/collection/aggregate/stream to the migrations, validation, model, projection, or infrastructure tasks its architecture actually requires
+5. Read `project-context/api.md` when an API or event contract is in scope → map each REST endpoint, GraphQL operation, RPC procedure, or event contract to protocol-native implementation and contract-test tasks
+6. Read `project-context/rules.md` → include tooling/configuration tasks only for approved unsatisfied requirements
+7. Identify dependencies from actual architecture and data flow; do not presume model/service/controller layers
 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.
+9. For required security controls, explicitly track unsatisfied implementation or verification work; retain evidence for controls already verified rather than recreating them.
+10. Create a **traceability matrix**: every main requirement (`FEAT-*`, `BR-*`, `NFR-*`, `API-*`, `DATA-*`) maps to a task or evidenced existing verified baseline; distinguish verification work and unapproved gaps.
 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**:
@@ -177,7 +194,7 @@ Security controls to implement:
 Is this scope correct? Anything to add or remove?
 ```
 
-Wait for user confirmation before creating Task.md.
+Obtain scope confirmation before creating or updating Task.md unless the current explicit approval or authorized handoff already covers the exact bounded change. Do not ask for the same approval again; ask only if scope changes or a material conflict appears.
 
 ## Task.md Output
 
@@ -191,8 +208,7 @@ Adapt only sections that are applicable and preserve every required contract fro
 
 1. Confirm `project-context/Task.md` was created.
 2. Show the progress overview (phases + task counts).
-3. Offer to start:
-   > "All spec documents are ready! Task.md has been created. Start Task 1.1?"
+3. If pending approved work exists, offer its actual ID and purpose (verification or implementation). If none remains, report completion of planning without offering coding. Preserve the user's execution authorization boundary.
 
 ## Critical Notes
 
@@ -200,7 +216,7 @@ Adapt only sections that are applicable and preserve every required contract fro
 - Every task must have **testable acceptance criteria**, not just a description.
 - Mark **task dependencies** clearly. AI cannot skip tasks.
 - **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."
+- Explicitly cover required security controls through gap/verification tasks or evidenced existing completion. 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.
 - Task granularity must be **atomic**: completable and verifiable in one session.

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

@@ -1,5 +1,7 @@
 # Task: [Project Name]
 
+> **Authoring note:** This is a placeholder menu, not a checklist to build. Derive tasks only from approved current gaps and required verification/security/recovery work in the actual architecture. Prune inapplicable sections or mark `N/A` with a reason; unknown mandatory decisions remain open, not `N/A`. Reuse verified existing work and preserve IDs/history. No presumed setup/auth/layers, empty phases, copied example tasks, or “maybe later” features. Critical depth deepens analysis, not the task count. Return unjustified new components to their spec owner for requirement, simpler-option evidence, cost, and escalation-trigger decisions within scale/team/budget/operations constraints.
+
 > **Total Phases:** [X] | **Total Tasks:** [Y] | **Last Updated:** [date]
 
 ## Document Role
@@ -32,9 +34,9 @@
 
 | Phase | Name                    | Status | Progress |
 | ----- | ----------------------- | ------ | -------- |
-| 1     | [Setup & Configuration] | [ ]    | 0/3      |
-| 2     | [Database & Models]     | [ ]    | 0/4      |
-| 3     | [Backend: Auth]         | [ ]    | 0/3      |
+| [ID]  | [Actual approved phase] | [status] | [verified/total] |
+
+Generate only phases with real approved work. If none remains, report that outcome with no placeholder phase.
 
 ## AI Read Order
 
@@ -74,7 +76,7 @@
   - **Files:** `[path/file]`
   - **Description:** [Briefly what is done]
   - **Dependencies:** Task 1.1 must be complete first
-  - **References:** [`project-context/schema.md#users`]
+  - **References:** [`project-context/[applicable-document].md#actual-section`]
   - **Traceability IDs:** [`FEAT-01` / `DATA-01`]
   - **Acceptance Criteria:**
     - [ ] [Testable condition]
@@ -100,7 +102,7 @@
 - [ ] **Task 2.1: [Task Name]**
   - **Files:** `[path/file]`
   - **Description:** [Brief]
-  - **References:** [`project-context/api.md#auth`]
+  - **References:** [`project-context/[applicable-document].md#actual-section`]
   - **Traceability IDs:** [`FEAT-01` / `API-01` / `NFR-02`]
   - **Acceptance Criteria:**
     - [ ] [Testable condition]
@@ -109,16 +111,13 @@
 
 ## 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`                         |
+| Requirement ID | Source | Classification | Covering Task or Verified Evidence |
+| -------------- | ------ | -------------- | ---------------------------------- |
+| [Existing ID] | [actual source/section] | Existing verified / Existing unverified / Gap | [evidence or approved task ID; unapproved gaps remain separate] |
 
 ## 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.
+Use the phase/task blocks only as formatting examples for actual approved work. Repeat `Phase Definition of Done` only for generated non-empty phases, adapting items to scope and preserving required safeguards.