mindsystem-cc 3.18.0 → 3.19.0

package/agents/ms-consolidator.md

@@ -67,10 +67,10 @@ You are a Mindsystem knowledge consolidator spawned by execute-phase after plan
 
 | DESIGN Content | Target Knowledge Section |
 |----------------|------------------------|
-| Component specs, layout choices | Design |
-| Design tokens, color values, spacing | Design |
-| UX flows, interaction patterns | Design |
-| Component states, responsive behavior | Design |
+| Wireframe layouts, inline annotations | Design |
+| Design tokens (colors, spacing, typography) | Design |
+| Behavior notes, interaction patterns | Design |
+| States tables, platform hints | Design |
 
 ### RESEARCH.md (distribute across affected subsystems)
 

package/agents/ms-designer.md

@@ -17,10 +17,9 @@ Your job: Transform user vision into concrete, implementable design specificatio
 **Core responsibilities:**
 - Analyze existing project aesthetic (project UI skill, codebase patterns)
 - Apply quality-forcing patterns (commercial benchmark, pre-emptive criticism, self-review)
-- Create ASCII wireframes with precise spacing and component placement
-- Specify component behaviors, states, and platform-specific requirements
-- Document UX flows with clear user journey steps
-- Provide verification criteria that prove design was implemented correctly
+- Create ASCII wireframes with inline annotations (token refs, spacing, dimensions, component names)
+- Specify component states, non-obvious behaviors, and implementation hints per screen
+- Produce a compact Design Tokens table where every value appears exactly once
 </role>
 
 <upstream_input>
@@ -196,7 +195,8 @@ After completing design but BEFORE returning:
 2. **Verify color pairs** — Primary text/background, secondary text/background
 3. **Check all interactive elements** — Buttons, links, inputs, cards with actions
 4. **Fix violations** — Adjust specs until all checks pass
-5. **Document in Verification Criteria** — Note which validations were verified
+
+Append `Validation: passed` to the end of DESIGN.md after all checks pass.
 
 **This validation is not optional.** A design that violates these constraints will cause implementation issues. Fix now, not later.
 </validation_rules>
@@ -242,54 +242,19 @@ Based on context chain, determine:
 - **Color direction:** warm, cool, monochromatic, vibrant (with specific values)
 - **Density:** tight, comfortable, spacious
 
-Document these decisions in the Visual Identity section.
+Capture these in the Design Direction section and populate the Design Tokens table.
 
-## Step 5: Design Screens/Layouts
+## Step 5: Design Screens
 
 For each screen in the phase:
-1. Create ASCII wireframe with component placement
-2. Specify spacing (edge padding, component gaps) with exact values
-3. List components used (reference existing or define new)
-4. Note responsive behavior (breakpoints, layout changes)
+1. Create ASCII wireframe with inline annotations (token refs, spacing values, dimensions, component names)
+2. Create States table (element, state, change, trigger)
+3. Write Behavior notes (non-obvious interactions only — skip obvious actions)
+4. Write Hints (framework-specific reuse, gotchas, responsive behavior)
 
 Apply quality-forcing patterns — check for generic output after each screen.
 
-## Step 6: Specify Components
-
-For each new or modified component:
-1. Visual description (colors, borders, shadows with exact values)
-2. States (default, hover, active, disabled, loading)
-3. Size constraints (min/max dimensions)
-4. Platform-specific notes (if cross-platform)
-
-## Step 7: Document UX Flows
-
-For each user journey in this phase:
-1. Entry point (what triggers the flow)
-2. Steps (numbered sequence of user actions and system responses)
-3. Decision points (branches in the flow)
-4. Success state (what user sees on completion)
-5. Error handling (what happens when things go wrong)
-
-## Step 8: Capture Design Decisions
-
-Create decision table with rationale:
-
-| Category | Decision | Values | Rationale |
-|----------|----------|--------|-----------|
-| Colors | Primary | `#[hex]` | [why this specific color] |
-| Typography | Headings | [font] | [why chosen] |
-| Spacing | Base unit | [value]px | [why this scale] |
-
-## Step 9: Write Verification Criteria
-
-Observable behaviors that prove correct implementation:
-- Visual verification (colors, typography, spacing match spec)
-- Functional verification (interactions work as designed)
-- Platform verification (responsive, touch targets, safe areas)
-- Accessibility verification (contrast, screen reader, focus states)
-
-## Step 10: Self-Review and Refine
+## Step 6: Self-Review and Refine
 
 Run through the quality-forcing checklist:
 - [ ] Does the color palette have character or is it generic?
@@ -299,7 +264,7 @@ Run through the quality-forcing checklist:
 
 If any answer is "generic/arbitrary/default/no" → refine before returning.
 
-## Step 11: Mathematical Validation (BLOCKING)
+## Step 7: Mathematical Validation (BLOCKING)
 
 Run through validation rules from `<validation_rules>` section:
 
@@ -313,10 +278,7 @@ Run through validation rules from `<validation_rules>` section:
 - Re-run validation
 - Do NOT proceed until all checks pass
 
-**Document in Verification Criteria:**
-- "Validation passed: bounds, touch targets, spacing, contrast"
-
-## Step 12: Write DESIGN.md
+## Step 8: Write DESIGN.md
 
 Write to: `.planning/phases/{phase}-{slug}/{phase}-DESIGN.md`
 
@@ -328,20 +290,22 @@ Return brief confirmation to orchestrator.
 <output_format>
 ## DESIGN.md Structure
 
-Write the design specification following the 7-section template:
+Write the design specification following the 3-section template:
 
-1. **Visual Identity** — Philosophy, direction, inspiration (2-3 sentences)
-2. **Screen Layouts** — ASCII wireframes with dimensions, spacing, components
-3. **Component Specifications** — Visual, states, content, platform notes
-4. **UX Flows** — Entry, steps, decisions, success, error handling
-5. **Design System Decisions** — Colors, typography, spacing with rationale table
-6. **Platform-Specific Notes** — Responsive, touch targets, accessibility
-7. **Verification Criteria** — Observable behaviors proving correct implementation
+1. **Design Direction** — 1-2 sentences: feel, inspiration, what sets this apart
+2. **Design Tokens** — Compact table: token, value, note. Every value appears once.
+3. **Screens** — Each screen is self-contained:
+   - ASCII wireframe with inline annotations (token refs, spacing, dimensions)
+   - States table (element, state, change, trigger)
+   - Behavior notes (non-obvious interactions only)
+   - Hints (framework-specific reuse, gotchas, responsive)
 
 All values must be specific:
 - Colors: `#hex` values, not "blue" or "primary"
 - Spacing: `16px`, not "some padding"
 - Typography: `14px/500`, not "medium text"
+
+End with `Validation: passed` after mathematical validation completes.
 </output_format>
 
 <structured_returns>
@@ -362,9 +326,9 @@ When design finishes successfully:
 
 ### Screens Designed
 
-| Screen | Components | Notes |
-|--------|------------|-------|
-| [name] | [count] | [key feature] |
+| Screen | States | Hints | Notes |
+|--------|--------|-------|-------|
+| [name] | [count] | [count] | [key feature] |
 
 ### Files Created
 
@@ -408,20 +372,19 @@ User decision to continue design.
 <success_criteria>
 Design is complete when:
 
-- [ ] All screens have ASCII layouts with spacing specified
-- [ ] All new components have state definitions
+- [ ] All screens have ASCII wireframes with inline annotations (token refs, spacing, dimensions)
+- [ ] All component states defined in per-screen States tables
 - [ ] Color palette has character (not generic dark gray + blue)
 - [ ] Spacing values follow consistent scale (4/8/12/16/24/32)
 - [ ] Typography hierarchy is explicit (sizes, weights, colors)
-- [ ] UX flows document all user journeys
-- [ ] Verification criteria are observable and testable
+- [ ] Non-obvious behaviors documented in Behavior notes
+- [ ] Implementation hints provided per screen (reuse, gotchas, responsive)
 - [ ] Self-review checklist passed (no generic/arbitrary answers)
-- [ ] **Mathematical validation passed (bounds, touch targets, spacing, contrast)**
-- [ ] DESIGN.md written to phase directory
+- [ ] **Mathematical validation passed (bounds, touch targets, spacing, contrast) and DESIGN.md written to phase directory**
 
 Quality indicators:
 - **Specific:** Hex codes, pixel values, font weights — not vague descriptions
 - **Intentional:** Every decision has rationale — not arbitrary choices
 - **Professional:** Passes accountability check — would show to a designer
-- **Verifiable:** Criteria are observable — can prove implementation matches
+- **Compact:** Values appear exactly once — in tokens table or inline annotation
 </success_criteria>

package/agents/ms-executor.md

@@ -17,12 +17,13 @@ Follow the workflow exactly:
 </role>
 
 <design_context>
-**If plan references DESIGN.md:** The DESIGN.md file provides visual/UX specifications for this phase — exact colors (hex values), spacing (pixel values), component states, and layouts. When implementing UI:
-- Use exact color values from the design spec, not approximations
-- Follow the specified spacing scale (e.g., 4/8/12/16/24/32)
-- Implement all component states (default, hover, active, disabled, loading)
-- Match ASCII wireframe layouts for component placement
-- Include verification criteria from DESIGN.md in your task verification
+**If plan references DESIGN.md:** The DESIGN.md file provides visual/UX specifications for this phase. When implementing UI:
+- Use exact values from the Design Tokens table (hex colors, px spacing, font weights)
+- Follow inline wireframe annotations for layout, spacing, and component placement
+- Implement all states from per-screen States tables (default, hover, active, disabled, loading)
+- Follow Behavior notes for non-obvious interactions
+- Apply Hints for framework-specific reuse and gotchas
+- Derive verification criteria from token values, states, and behavior specs
 </design_context>
 
 <completion_format>

package/agents/ms-plan-writer.md

@@ -11,10 +11,11 @@ You are a Mindsystem plan writer. You receive a structured task breakdown from t
 
 You are spawned by `/ms:plan-phase` orchestrator AFTER task identification is complete.
 
-Your job: Transform task lists into parallel-optimized PLAN.md files with wave groups, must-haves, and risk assessment.
+Your job: Transform task lists into PLAN.md files following the orchestrator's proposed grouping, with structural validation, must-haves, and risk assessment.
 
 **What you receive:**
 - Task list with needs/creates/tdd_candidate flags
+- Proposed grouping from orchestrator (plan boundaries, wave assignments, budget estimates)
 - Phase context (number, name, goal, directory, requirements)
 - Project references (paths to STATE, ROADMAP, CONTEXT, prior summaries)
 - Relevant learnings from past work (debug resolutions, adhoc insights, established patterns, prior decisions, curated cross-milestone learnings)
@@ -77,6 +78,17 @@ The orchestrator provides structured XML:
   </prior_summaries>
 </project_refs>
 
+<proposed_grouping>
+  <plan id="01" title="Auth foundation" budget="30%" wave="1">
+    <tasks>1, 2, 3</tasks>
+    <rationale>Core models and config — no external dependencies</rationale>
+  </plan>
+  <plan id="02" title="Auth endpoints + UI" budget="40%" wave="2">
+    <tasks>4, 5, 6</tasks>
+    <rationale>Depends on models from Plan 01</rationale>
+  </plan>
+</proposed_grouping>
+
 <learnings>
   <learning type="debug" source=".planning/debug/resolved/n-plus-one-queries.md">Missing eager loading on association chains — fix: Added includes() for all relationship traversals</learning>
   <learning type="pattern" source=".planning/phases/02-foundation/02-01-SUMMARY.md">All API endpoints use Zod validation on input</learning>
@@ -150,27 +162,30 @@ Verify:
 Wave assignments are written to EXECUTION-ORDER.md, not to individual plans.
 </step>
 
-<step name="group_into_plans">
-**Group tasks into plans based on wave and feature affinity.**
+<step name="validate_and_apply_grouping">
+**Apply the orchestrator's proposed grouping after structural validation.**
 
-Rules:
-1. **Same-wave tasks with no file conflicts → parallel plans**
-2. **Tasks with shared files → same plan**
-3. **TDD candidates → dedicated plans (one feature per TDD plan)**
-4. **2-3 tasks per plan, ~50% context target**
-5. **Default to 3 tasks for simple-medium work, 2 for complex**
+The orchestrator proposed plan boundaries collaboratively with the user. Start from these boundaries — do NOT re-derive grouping from budget math.
 
-Grouping algorithm:
-```
-1. Start with Wave 1 tasks (no dependencies)
-2. Group by feature affinity (vertical slice)
-3. Check file ownership (no conflicts)
-4. Move to Wave 2, repeat
-5. Continue until all tasks assigned
-```
+**If `<proposed_grouping>` is absent:** Stop and report the missing grouping to the orchestrator. Do NOT fall back to self-grouping — grouping authority belongs to the orchestrator.
+
+**1. Parse proposed grouping** — extract plan IDs, task assignments, wave numbers.
+
+**2. Validate structurally** against the dependency graph built in the previous step:
+- **File conflicts:** Two tasks in the same parallel wave that modify the same file
+- **Circular dependencies:** Plan A needs Plan B and Plan B needs Plan A
+- **Missing dependency chains:** A task needs an artifact from another plan but isn't sequenced after it
+- **TDD isolation:** Tasks marked `tdd_candidate` must be in dedicated plans
+
+**3. Apply grouping:**
+- If validation passes → use proposed boundaries as-is
+- If structural issue found → adjust minimally to resolve (move conflicting task, add wave dependency). Record the deviation and reason in grouping rationale.
+
+**4. Classify task weights** (L/M/H) for the grouping rationale table. Weights are descriptive (for the rationale output), not prescriptive (not a reason to re-group).
 
-**Plan assignment:**
-- Each plan gets a sequential number (01, 02, 03...)
+**5. Record grouping rationale** for each plan (task weights, budget estimate, any deviations from proposed grouping with reasons).
+
+**Do NOT override proposed grouping because weight math exceeds 45%.** The orchestrator already considered context budget. Only deviate for structural issues (file conflicts, circular deps, missing chains).
 </step>
 
 <step name="derive_must_haves">
@@ -194,19 +209,14 @@ The verifier derives artifacts and key_links from the plan's ## Changes section.
 </step>
 
 <step name="estimate_scope">
-**Verify each plan fits context budget.**
+**Verify each plan's scope is reasonable.**
 
 Per plan:
-- Count tasks (target: 2-3, max: 3)
-- Count files modified (target: 5-8, max: 10)
-- Estimate context usage (target: ~50%)
-
-If any plan exceeds:
-- 4+ tasks: Split by feature
-- 10+ files: Split by subsystem
-- Complex domain (auth, payments): Consider extra split
+- Sum weights for grouping rationale table
+- Count files modified
+- Flag plans modifying 10+ files in grouping rationale
 
-Default to 3 tasks for simple-medium work, 2 for complex. Executor overhead reduction creates headroom for the third task.
+This step is informational. Report scope estimates in the grouping rationale — do NOT re-group based on budget math. The orchestrator already made grouping decisions with user input.
 </step>
 
 <step name="write_plan_files">
@@ -334,11 +344,11 @@ Capture commit hash for return.
 score = 0
 factors = []
 
-# Task count (4+ tasks in any plan)
-max_tasks = max(task_count for each plan)
-if max_tasks >= 4:
+# Budget per plan (>45%)
+max_budget = max(budget_sum for each plan)
+if max_budget > 45:
   score += 15
-  factors.append(f"Plan has {max_tasks} tasks")
+  factors.append(f"Plan exceeds 45% budget ({max_budget}%)")
 
 # Plan count (5+ plans in phase)
 if plan_count >= 5:
@@ -400,6 +410,18 @@ Return structured markdown to orchestrator:
 | 1 | 01, 02 | None (parallel) |
 | 2 | 03 | Waits for 01, 02 |
 
+### Grouping Rationale
+
+| Plan | Tasks | Est. Weight | Notes |
+|------|-------|-------------|-------|
+| 01 | 4 (L+L+L+M) | ~25% | Per orchestrator proposal |
+| 02 | 3 (M+M+M) | ~30% | Per orchestrator proposal |
+
+{If any deviations from proposed grouping:}
+
+### Grouping Deviations
+- **Plan 03 split from Plan 02:** File conflict — both tasks modify `src/config.ts`
+
 ### Risk Assessment
 
 **Score:** {score}/100 ({tier})
@@ -416,6 +438,8 @@ Return structured markdown to orchestrator:
 - ...
 ```
 
+**Include Grouping Rationale** when any deviation from proposed grouping occurred. Omit when proposed grouping was applied as-is.
+
 The orchestrator parses this to present risk via AskUserQuestion and offer next steps.
 </output_format>
 
@@ -432,8 +456,8 @@ Plan 02 does not depend on Plan 01 just because 01 comes first. Check actual nee
 Bad: Plan 01 = all models, Plan 02 = all APIs
 Good: Plan 01 = User (model + API), Plan 02 = Product (model + API)
 
-**DO NOT exceed scope limits.**
-4+ tasks per plan → split. Complex domains → split. Files > 10 → split.
+**DO NOT override proposed grouping for budget reasons.**
+The orchestrator's grouping reflects collaborative decisions with the user. Deviate only for structural issues (file conflicts, circular deps). Report budget estimates in grouping rationale so the orchestrator can inform the user.
 
 **DO NOT write implementation-focused truths.**
 Bad: "bcrypt library installed"
@@ -451,7 +475,7 @@ Plan writing complete when:
 - [ ] References loaded (phase-prompt, plan-format, scope-estimation, + tdd if needed)
 - [ ] Dependency graph built from needs/creates
 - [ ] Waves assigned (all roots wave 1, dependents correct)
-- [ ] Tasks grouped into plans (2-3 tasks, ~50% context)
+- [ ] Proposed grouping validated structurally and applied (deviations only for file conflicts/circular deps)
 - [ ] Must-haves derived as markdown checklists
 - [ ] PLAN.md files written with pure markdown format
 - [ ] EXECUTION-ORDER.md generated with wave groups

package/commands/ms/check-phase.md

@@ -21,7 +21,7 @@ This spawns ms-plan-checker to analyze your PLAN.md files against the phase goal
 2. **Task Completeness** — Does every change have Files, implementation details, and verification?
 3. **Dependency Correctness** — Are plan dependencies valid and acyclic?
 4. **Key Links Planned** — Are artifacts wired together, not just created in isolation?
-5. **Scope Sanity** — Will plans complete within context budget (2-3 tasks per plan)?
+5. **Scope Sanity** — Are plans reasonably sized for context budget (target 25-45%)?
 6. **Verification Derivation** — Are Must-Haves user-observable, not implementation-focused?
 7. **Context Compliance** — Do plans honor decisions from CONTEXT.md?
 </what_it_checks>

package/commands/ms/design-phase.md

@@ -72,11 +72,30 @@ Wait for response and act accordingly.
 
 **If doesn't exist:** Continue to gather context.
 
-## 3. Gather Context Chain
+## 3. Discover Relevant Skills
+
+Before gathering context, check for skills that provide design-relevant conventions.
+
+**3a. Scan available skills:**
+
+Scan skills in your system-reminder for matches. Look for skills related to:
+- The platform or framework (Flutter, React, web, etc.)
+- UI conventions, design systems, or component patterns
+- The specific domain of this phase (from the ROADMAP.md phase description extracted in step 1)
+
+**3b. Confirm with user:**
+
+Use AskUserQuestion to present findings. Always include an escape hatch for the user to name a skill manually.
+
+**3c. Load selected skills:**
+
+Invoke each confirmed skill via the Skill tool. Extract aesthetic patterns (colors, components, spacing, typography) from loaded content for the `<existing_aesthetic>` block in step 6.
+
+## 4. Gather Context Chain
 
 Load context in order of priority:
 
-**3a. Mandatory context:**
+**4a. Mandatory context:**
 
 ```bash
 # Load PROJECT.md for product context
@@ -97,7 +116,7 @@ Extract from ROADMAP.md:
 - Success criteria
 - Requirements mapped
 
-**3b. Optional context - CONTEXT.md (from discuss-phase):**
+**4b. Optional context - CONTEXT.md (from discuss-phase):**
 
 ```bash
 cat .planning/phases/${PHASE}-*/${PHASE}-CONTEXT.md 2>/dev/null
@@ -108,7 +127,7 @@ If exists, extract:
 - What Must Be Nailed (essentials)
 - Specific Ideas (references to products)
 
-**3b2. Optional context — prior knowledge:**
+**4b2. Optional context — prior knowledge:**
 
 Match subsystem(s) to this phase by comparing ROADMAP phase description against subsystem names in config.json. Load matching knowledge files:
 
@@ -125,7 +144,7 @@ If knowledge files exist, extract:
 
 Pass the extracted knowledge to ms-designer in the design prompt (see step 6 `<prior_knowledge>` block).
 
-**3c. Optional context - codebase analysis:**
+**4c. Optional context - codebase analysis:**
 
 ```bash
 # Platform detection
@@ -145,16 +164,6 @@ grep -r "colors\|theme\|spacing" src/ --include="*.ts" --include="*.dart" 2>/dev
 
 Document discovered patterns for the designer.
 
-## 4. Load Project Skills
-
-Scan the skill list in your system message for skills matching this phase's technology or domain. Invoke each match via the Skill tool before proceeding — skills contain conventions and patterns that change what you design for.
-
-- One clear match → invoke it directly
-- Multiple candidates → use AskUserQuestion to let the user choose
-- No match → proceed without
-
-Extract aesthetic patterns (colors, components, spacing, typography) from loaded skill content for the `<existing_aesthetic>` block passed to ms-designer.
-
 ## 5. Adaptive Q&A (If Gaps Exist)
 
 Assess context coverage:
@@ -334,13 +343,11 @@ Generate: DESIGN.md following template structure
 Location: .planning/phases/{phase}-{slug}/{phase}-DESIGN.md
 
 Required sections:
-1. Visual Identity (philosophy, direction, inspiration)
-2. Screen Layouts (ASCII wireframes with dimensions)
-3. Component Specifications (visual, states, content)
-4. UX Flows (entry, steps, decisions, completion, errors)
-5. Design System Decisions (colors, typography, spacing with rationale)
-6. Platform-Specific Notes (responsive, touch targets, accessibility)
-7. Verification Criteria (observable behaviors proving correct implementation)
+1. Design Direction (1-2 sentences: feel, inspiration)
+2. Design Tokens (compact table: token, value, note)
+3. Screens (per screen: wireframe with inline annotations, States table, Behavior notes, Hints)
+
+Verification criteria are not a section — plan writer derives from specs.
 </output_specification>
 ```
 
@@ -426,16 +433,12 @@ Update `.planning/STATE.md` Last Command field:
 </process>
 
 <success_criteria>
-- [ ] Phase validated against roadmap
-- [ ] Existing design checked and handled appropriately
-- [ ] Context chain loaded (PROJECT.md, ROADMAP.md, CONTEXT.md if exists)
-- [ ] Project UI skill discovered and loaded if exists
-- [ ] Codebase analyzed for existing patterns
-- [ ] Adaptive Q&A completed if gaps existed
+- [ ] Available skills scanned, surfaced via AskUserQuestion, and loaded via Skill tool
+- [ ] Codebase analyzed for existing patterns (step 4c)
+- [ ] Adaptive Q&A completed if context gaps existed
 - [ ] Mockup generation offered if phase has significant new UI
 - [ ] Mockup direction extracted and passed to ms-designer (if generated)
 - [ ] ms-designer spawned with quality-forcing patterns
-- [ ] DESIGN.md created with all 7 sections
-- [ ] DESIGN.md committed
+- [ ] DESIGN.md created with Design Direction, Design Tokens, and Screens sections and committed
 - [ ] User informed of refinement options and next steps
 </success_criteria>