mindsystem-cc 3.18.0 → 3.18.1

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

@@ -151,24 +151,43 @@ 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.**
+**Group tasks into plans using budget-based packing per wave.**
 
-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**
+**1. Classify task weight** (L/M/H) from action description, file count, domain complexity using the weight table in scope-estimation.md.
 
-Grouping algorithm:
+**2. Greedy budget packing per wave:**
 ```
-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
+For each wave:
+  Sort tasks by feature affinity (vertical slice)
+  current_plan = new plan
+  current_budget = 0
+
+  For each task:
+    If task.tdd_candidate:
+      Create dedicated plan for this task (TDD plans always standalone)
+      Continue
+
+    task_cost = marginal_cost(task.weight)
+    If current_budget + task_cost > 45% AND current_plan not empty:
+      Finalize current_plan
+      current_plan = new plan
+      current_budget = 0
+
+    If no file conflicts with current_plan:
+      Add task to current_plan
+      current_budget += task_cost
+    Else:
+      Finalize current_plan
+      current_plan = new plan with this task
+      current_budget = task_cost
 ```
 
+**3. Minimum threshold check:** Plans under ~10% → merge with adjacent same-wave plan if no file conflicts and combined budget <= 45%.
+
+**4. File ownership constraint:** Tasks sharing files must be in the same plan.
+
+**5. Record grouping rationale** for each plan (weight classification, budget total, merge decisions).
+
 **Plan assignment:**
 - Each plan gets a sequential number (01, 02, 03...)
 </step>
@@ -197,16 +216,14 @@ The verifier derives artifacts and key_links from the plan's ## Changes section.
 **Verify each plan fits context budget.**
 
 Per plan:
-- Count tasks (target: 2-3, max: 3)
-- Count files modified (target: 5-8, max: 10)
-- Estimate context usage (target: ~50%)
+- Sum weights (target: 25-45%)
+- Check minimum threshold (plans under ~10% → consolidate)
+- Count files modified (max: 10)
 
 If any plan exceeds:
-- 4+ tasks: Split by feature
+- Budget > 45%: Split by feature affinity
 - 10+ files: Split by subsystem
-- Complex domain (auth, payments): Consider extra split
-
-Default to 3 tasks for simple-medium work, 2 for complex. Executor overhead reduction creates headroom for the third task.
+- Under 10%: Merge with related same-wave plan
 </step>
 
 <step name="write_plan_files">
@@ -334,11 +351,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 +417,13 @@ Return structured markdown to orchestrator:
 | 1 | 01, 02 | None (parallel) |
 | 2 | 03 | Waits for 01, 02 |
 
+### Grouping Rationale
+
+| Plan | Tasks | Est. Marginal | Notes |
+|------|-------|---------------|-------|
+| 01 | 4 (L+L+L+M) | ~25% | Merged light fixes with medium refactor |
+| 02 | 3 (M+M+M) | ~30% | Vertical slice: model + API + tests |
+
 ### Risk Assessment
 
 **Score:** {score}/100 ({tier})
@@ -416,6 +440,8 @@ Return structured markdown to orchestrator:
 - ...
 ```
 
+**Include Grouping Rationale** only when consolidation occurred or grouping is non-obvious. Omit for straightforward groupings.
+
 The orchestrator parses this to present risk via AskUserQuestion and offer next steps.
 </output_format>
 
@@ -433,7 +459,7 @@ 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.
+Budget > 45% → split. Single light task alone → consolidate. Files > 10 → split.
 
 **DO NOT write implementation-focused truths.**
 Bad: "bcrypt library installed"
@@ -451,7 +477,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)
+- [ ] Tasks grouped into plans (budget-based, target 25-45%, consolidate under 10%)
 - [ ] 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** — Will plans complete within 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>