mindsystem-cc 3.18.1 → 3.20.0

package/agents/ms-designer.md

@@ -29,9 +29,12 @@ Your job: Transform user vision into concrete, implementable design specificatio
 
 | Section | How You Use It |
 |---------|----------------|
-| `## What This Is` | Product type informs design conventions |
+| `## What This Is` | Product identity — informs design conventions |
 | `## Core Value` | The ONE thing design must serve |
-| `## Context` | Target audience shapes UX priorities |
+| `## Who It's For` | Target audience — shapes UX complexity, language, navigation priorities |
+| `## Core Problem` | Problem being solved — clarifies what UI must address first |
+| `## How It's Different` | Competitive context — prevents generic design |
+| `## Key User Flows` | Primary interactions — drives screen hierarchy and navigation |
 | `## Constraints` | Technical limits, platform requirements |
 
 **ROADMAP.md** — Phase-specific requirements

package/agents/ms-plan-writer.md

@@ -11,10 +11,12 @@ 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)
+- Confirmed skills from user (skill names to embed in plan metadata)
 - 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 +79,21 @@ 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>
+
+<confirmed_skills>
+  flutter-code-quality, flutter-code-simplification
+</confirmed_skills>
+
 <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,46 +167,30 @@ Verify:
 Wave assignments are written to EXECUTION-ORDER.md, not to individual plans.
 </step>
 
-<step name="group_into_plans">
-**Group tasks into plans using budget-based packing per wave.**
+<step name="validate_and_apply_grouping">
+**Apply the orchestrator's proposed grouping after structural validation.**
 
-**1. Classify task weight** (L/M/H) from action description, file count, domain complexity using the weight table in scope-estimation.md.
+The orchestrator proposed plan boundaries collaboratively with the user. Start from these boundaries — do NOT re-derive grouping from budget math.
 
-**2. Greedy budget packing per wave:**
-```
-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
-```
+**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.
 
-**3. Minimum threshold check:** Plans under ~10% → merge with adjacent same-wave plan if no file conflicts and combined budget <= 45%.
+**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
 
-**4. File ownership constraint:** Tasks sharing files must be in the same plan.
+**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.
 
-**5. Record grouping rationale** for each plan (weight classification, budget total, merge decisions).
+**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">
@@ -213,17 +214,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:
-- Sum weights (target: 25-45%)
-- Check minimum threshold (plans under ~10% → consolidate)
-- Count files modified (max: 10)
-
-If any plan exceeds:
-- Budget > 45%: Split by feature affinity
-- 10+ files: Split by subsystem
-- Under 10%: Merge with related same-wave plan
+- Sum weights for grouping rationale table
+- Count files modified
+- Flag plans modifying 10+ files in grouping rationale
+
+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">
@@ -234,7 +232,7 @@ For each plan, create `.planning/phases/{phase_dir}/{phase}-{plan}-PLAN.md`:
 ```markdown
 # Plan {NN}: {Descriptive Title}
 
-**Subsystem:** {subsystem_hint} | **Type:** tdd
+**Subsystem:** {subsystem_hint} | **Type:** tdd | **Skills:** {skill_names}
 
 ## Context
 {Why this work exists. Approach chosen and WHY.}
@@ -262,6 +260,8 @@ For each plan, create `.planning/phases/{phase_dir}/{phase}-{plan}-PLAN.md`:
 
 **Format rules:**
 - Omit `| **Type:** tdd` when type is execute (type defaults to execute)
+- Omit `| **Skills:** ...` when no skills were confirmed (confirmed_skills is "none" or empty)
+- Include `| **Skills:** skill-a, skill-b` when skills were confirmed — apply to ALL plans in the phase
 - Plans carry no `<execution_context>`, `<context>`, or @-references — the executor loads its own workflow and project files via its agent definition
 - No `<tasks>`, `<verification>`, `<success_criteria>`, `<output>` XML containers
 
@@ -419,10 +419,15 @@ Return structured markdown to orchestrator:
 
 ### 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 |
+| 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
 
@@ -440,7 +445,7 @@ Return structured markdown to orchestrator:
 - ...
 ```
 
-**Include Grouping Rationale** only when consolidation occurred or grouping is non-obvious. Omit for straightforward groupings.
+**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>
@@ -458,8 +463,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.**
-Budget > 45% → split. Single light task alone → consolidate. 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"
@@ -477,7 +482,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 (budget-based, target 25-45%, consolidate under 10%)
+- [ ] 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/add-phase.md

@@ -118,13 +118,36 @@ Confirm: "Created directory: $phase_dir"
 Add the new phase entry to the roadmap:
 
 1. Find the insertion point (after last phase in current milestone, before "---" separator)
-2. Insert new phase heading:
+
+2. Before writing the phase entry, analyze the description to determine pre-work flags:
+
+   **Discuss**: Likely when description mentions user-facing features, UX decisions,
+   experiential qualities, or novel features. Unlikely for backend/infra, bug fixes,
+   technical debt, or clear-cut work.
+
+   **Design**: Likely when description involves UI work, visual elements, forms,
+   dashboards, or multi-screen flows. Unlikely for backend-only, API, infrastructure,
+   or established UI patterns.
+
+   **Research**: Likely when description mentions external APIs/services, new
+   libraries/frameworks, or unclear technical approach. Unlikely for established
+   internal patterns or well-documented conventions.
+
+   Use binary Likely/Unlikely with parenthetical reason. Include topics/focus only when Likely.
+
+3. Insert new phase heading with pre-work flags:
 
    ```
    ### Phase {N}: {Description}
 
    **Goal:** [To be planned]
    **Depends on:** Phase {N-1}
+   **Discuss**: {Likely (reason) | Unlikely (reason)}
+   **Discuss topics**: {topics} ← only if Likely
+   **Design**: {Likely (reason) | Unlikely (reason)}
+   **Design focus**: {focus} ← only if Likely
+   **Research**: {Likely (reason) | Unlikely (reason)}
+   **Research topics**: {topics} ← only if Likely
    **Plans:** 0 plans
 
    Plans:
@@ -134,7 +157,7 @@ Add the new phase entry to the roadmap:
    [To be added during planning]
    ```
 
-3. Write updated roadmap back to file
+4. Write updated roadmap back to file
 
 Preserve all other content exactly (formatting, spacing, other phases).
 </step>
@@ -164,24 +187,13 @@ Phase {N} added to current milestone:
 Roadmap updated: {roadmap-path}
 Project state updated: .planning/STATE.md
 
----
-
-## ▶ Next Up
-
-**Phase {N}: {description}**
-
-`/ms:plan-phase {N}`
-
-<sub>`/clear` first → fresh context window</sub>
+```
 
----
+Read `~/.claude/mindsystem/references/routing/next-phase-routing.md` and follow its instructions
+to present "Next Up" with pre-work context for Phase {N}.
 
-**Also available:**
+After the "Next Up" section, add:
 - `/ms:add-phase <description>` — add another phase
-- Review roadmap
-
----
-```
 </step>
 
 <step name="update_last_command">

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 (target 25-45%)?
+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

@@ -15,8 +15,6 @@ Create design specifications for a phase. Spawns ms-designer agent with phase co
 
 **Orchestrator role:** Parse phase, validate against roadmap, check existing design, gather context chain (CONTEXT.md → project UI skill → codebase), adaptive Q&A if gaps, spawn designer agent, enable conversational refinement.
 
-**Why subagent:** Design requires focused attention with quality-forcing patterns. Fresh 200k context for design generation. Main context reserved for user refinement conversation.
-
 **When to use:**
 - UI-heavy phases with significant new interface work
 - Novel flows/components not deducible from existing patterns
@@ -108,7 +106,10 @@ grep -A30 "Phase ${PHASE}:" .planning/ROADMAP.md 2>/dev/null
 Extract from PROJECT.md:
 - What This Is (product type)
 - Core Value (design must serve this)
-- Context (target audience)
+- Who It's For (target audience and their context)
+- Core Problem (what the design must address)
+- How It's Different (competitive context, differentiators)
+- Key User Flows (primary interactions that drive hierarchy)
 - Constraints (platform, technical limits)
 
 Extract from ROADMAP.md:
@@ -148,18 +149,18 @@ Pass the extracted knowledge to ms-designer in the design prompt (see step 6 `<p
 
 ```bash
 # Platform detection
-if [ -f "package.json" ]; then
-  echo "Platform: Web (package.json found)"
-  grep -E "react|vue|angular|svelte" package.json 2>/dev/null | head -5
-fi
-
 if [ -f "pubspec.yaml" ]; then
   echo "Platform: Flutter (pubspec.yaml found)"
+  # Search Flutter project structure
+  find lib -name "*.dart" 2>/dev/null | head -20
+  grep -r "colors\|theme\|spacing" lib/ --include="*.dart" 2>/dev/null | head -10
+elif [ -f "package.json" ]; then
+  echo "Platform: Web (package.json found)"
+  grep -E "react|vue|angular|svelte" package.json 2>/dev/null | head -5
+  # Search web project structure
+  find src -name "*.tsx" -o -name "*.ts" -o -name "*.jsx" 2>/dev/null | head -20
+  grep -r "colors\|theme\|spacing" src/ --include="*.ts" --include="*.tsx" 2>/dev/null | head -10
 fi
-
-# Find existing component/theme files
-find src -name "*.tsx" -o -name "*.dart" 2>/dev/null | head -20
-grep -r "colors\|theme\|spacing" src/ --include="*.ts" --include="*.dart" 2>/dev/null | head -10
 ```
 
 Document discovered patterns for the designer.
@@ -202,8 +203,7 @@ Use AskUserQuestion:
 
 **If user selects "Yes":**
 
-Follow mockup-generation workflow:
-@~/.claude/mindsystem/workflows/mockup-generation.md
+Read `~/.claude/mindsystem/workflows/mockup-generation.md` and follow the mockup-generation workflow.
 
 1. Determine platform from context chain (or ask user)
 2. Identify primary screen for the phase
@@ -230,11 +230,20 @@ Platform: [Inferred from codebase or PROJECT.md constraints]
 Phase: [N]: [Phase name from ROADMAP.md]
 
 Target audience:
-[From PROJECT.md - Context section]
+[From PROJECT.md - Who It's For section]
+
+Core problem:
+[From PROJECT.md - Core Problem section]
+
+Competitive differentiators:
+[From PROJECT.md - How It's Different section]
 
 Core value this design must serve:
 [From PROJECT.md - Core Value section]
 
+Primary user flows:
+[From PROJECT.md - Key User Flows section]
+
 Technical constraints:
 [From PROJECT.md - Constraints section]
 </design_context>
@@ -329,13 +338,13 @@ User preferences:
 [If mockups were NOT generated, omit this entire block.]
 </mockup_direction>
 
-<quality_expectation>
-Commercial benchmark: This design must look like a [benchmark] with intentional decisions, not defaults.
+<quality_constraints>
+Specify exact values for every design token — colors as hex, spacing in px/dp, typography with weight+size+line-height. No "appropriate", "suitable", or "as needed". Every decision must be explicit and implementable without interpretation.
 
-Pre-emptive criticism: Assume the user will say "This looks like generic AI output." Generate something that proves them wrong.
+Differentiate from platform defaults: if a color, radius, or spacing matches the default system value, choose a deliberate alternative that serves the product's identity.
 
-Accountability check: Could you show this design to a professional UI designer and claim it as skilled work? If not, it's not done.
-</quality_expectation>
+Assume the user will say "This looks like generic AI output." Generate something that proves them wrong. Could you show this design to a professional UI designer and claim it as skilled work? If not, it's not done.
+</quality_constraints>
 
 <output_specification>
 Generate: DESIGN.md following template structure
@@ -404,7 +413,7 @@ After initial generation, if user wants to refine:
 
 **For major redesigns (multiple aspects changing):**
 
-Use the iteration template from `~/.claude/mindsystem/templates/design-iteration.md`:
+Read `~/.claude/mindsystem/templates/design-iteration.md` and use the iteration template:
 
 1. Capture feedback using the structured format:
    - What worked well (KEEP)
@@ -441,4 +450,5 @@ Update `.planning/STATE.md` Last Command field:
 - [ ] ms-designer spawned with quality-forcing patterns
 - [ ] DESIGN.md created with Design Direction, Design Tokens, and Screens sections and committed
 - [ ] User informed of refinement options and next steps
+- [ ] STATE.md Last Command updated with timestamp
 </success_criteria>