mindsystem-cc 3.17.1 → 3.18.1

package/mindsystem/templates/design.md

@@ -2,7 +2,7 @@
 
 Template for `.planning/phases/XX-name/{phase}-DESIGN.md` - captures visual/UX design specifications for a phase.
 
-**Purpose:** Translate user vision into concrete, implementable design specifications. This is design context, not technical implementation. Technical details come from research and planning.
+**Purpose:** Translate user vision into concrete, implementable design specifications. All values appear exactly once, inline where consumed.
 
 ---
 
@@ -15,225 +15,77 @@ Template for `.planning/phases/XX-name/{phase}-DESIGN.md` - captures visual/UX d
 **Platform:** [web / mobile / both]
 **Aesthetic source:** [project UI skill / codebase analysis / fresh design]
 
-## Visual Identity
-
-[2-3 sentences describing the design philosophy and feelings evoked. What's the vibe? What should users feel when they see this interface?]
-
-**Design direction:**
-- Overall feel: [e.g., "Professional yet approachable"]
-- Key differentiator: [e.g., "Generous whitespace, subtle animations"]
-- Inspiration: [e.g., "Linear's clean density, Notion's approachability"]
-
----
-
-## Screen Layouts
-
-### [Screen 1 Name]
-
-```
+## Design Direction
+
+[1-2 sentences: feel, inspiration, what sets this apart. Not generic — specific enough to guide decisions.]
+
+## Design Tokens
+
+| Token | Value | Note |
+|-------|-------|------|
+| bg-primary | `#[hex]` | [brief context] |
+| bg-surface | `#[hex]` | [brief context] |
+| text-primary | `#[hex]` | |
+| text-secondary | `#[hex]` | |
+| accent | `#[hex]` | [brief context] |
+| error | `#[hex]` | |
+| success | `#[hex]` | |
+| font-heading | [family] | |
+| font-body | [family] | |
+| h1 | [size/weight] | |
+| h2 | [size/weight] | |
+| body | [size/weight] | |
+| caption | [size/weight] | |
+| spacing-base | [value]px | [scale: 4/8/12/16/24/32] |
+| radius | [value]px | |
+| shadow-1 | [values] | [subtle depth] |
+| shadow-2 | [values] | [prominent depth] |
+
+## Screens
+
+### [Screen Name]
+
+` ` `
 +--------------------------------------------------+
-|  [Header Area]                                   |
-|  Logo        Nav Items              User Avatar  |
+|  ← bg-primary                                    |
+|  [Header]  h1 "Title"                            |
+|            text-secondary caption                 |
 +--------------------------------------------------+
-|                                                  |
-|  [Main Content Area]                             |
-|                                                  |
+|                         ↕ 24px                    |
 |  +---------------------+  +-------------------+  |
-|  |                     |  |                   |  |
-|  |  Primary Card       |  |  Secondary Card   |  |
-|  |                     |  |                   |  |
+|  | Card  ← bg-surface  |  | Card              |  |
+|  | ↔ 16px padding      |  |                   |  |
+|  | body text-primary    |  | body              |  |
+|  | radius: 8px          |  | radius: 8px       |  |
 |  +---------------------+  +-------------------+  |
-|                                                  |
-|  +---------------------------------------------+ |
-|  |  Full-width Section                         | |
-|  +---------------------------------------------+ |
-|                                                  |
+|         ↕ 16px gap                                |
 +--------------------------------------------------+
-|  [Footer]                                        |
-+--------------------------------------------------+
-```
-
-**Dimensions:** [width x height or responsive]
-**Edge padding:** [value]px
-**Component gaps:** [value]px
-**Components used:**
-- Header: [component names]
-- Cards: [component names]
-- Footer: [component names]
-
-**Responsive behavior:**
-- Desktop (1024px+): [layout description]
-- Tablet (768-1024px): [layout changes]
-- Mobile (<768px): [layout changes]
-
-### [Screen 2 Name]
-
-[Repeat structure for each screen]
-
----
-
-## Component Specifications
-
-### [Component Name]
+` ` `
 
-**Purpose:** [what this component does]
+**States**
 
-**Visual:**
-- Background: [color/gradient]
-- Border: [style, color, radius]
-- Shadow: [depth level]
-- Size: [min/max dimensions]
+| Element | State | Change | Trigger |
+|---------|-------|--------|---------|
+| Card | hover | border → accent | mouse over |
+| Card | loading | skeleton pulse | data fetch |
+| Button | disabled | opacity 0.5 | form invalid |
 
-**States:**
-| State | Visual Change | Trigger |
-|-------|--------------|---------|
-| Default | [base appearance] | Initial |
-| Hover | [change description] | Mouse over (web) |
-| Active | [change description] | Click/tap |
-| Disabled | [change description] | Interaction blocked |
-| Loading | [change description] | Async operation |
+**Behavior**
+- [Non-obvious interaction only — skip obvious actions like "tap button submits form"]
+- [Animations, transitions, or conditional logic worth noting]
 
-**Content:**
-- Typography: [font, size, weight, color]
-- Icons: [if any, which ones, sizing]
-- Spacing: [internal padding]
-
-**Platform notes:**
-- Web: [specific considerations]
-- iOS: [specific considerations]
-- Android: [specific considerations]
-
-### [Next Component]
-
-[Repeat for each component]
-
----
-
-## UX Flows
-
-### [Flow Name]
-
-**Entry point:** [what triggers this flow]
-**Goal:** [what user is trying to accomplish]
-
-**Steps:**
-1. User sees [initial screen/state]
-2. User [action] on [element]
-3. App responds with [feedback/transition]
-4. User sees [next screen/state]
-5. [Continue as needed]
-
-**Decision points:**
-- At step [N]: If [condition], go to step [X]; else continue
-- [Additional branches]
-
-**Success state:**
-- User sees: [what appears]
-- System state: [what changed]
-
-**Error handling:**
-- If [error condition]: Show [error message/state]
-- Recovery: [how user recovers]
-
-### [Next Flow]
-
-[Repeat for each flow]
-
----
-
-## Design System Decisions
-
-| Category | Decision | Values | Rationale |
-|----------|----------|--------|-----------|
-| **Colors** | Primary | `#[hex]` | [why this color] |
-| | Secondary | `#[hex]` | [why this color] |
-| | Background | `#[hex]` | [why this color] |
-| | Text | `#[hex]` | [why this color] |
-| | Accent | `#[hex]` | [why this color] |
-| | Error | `#[hex]` | [standard red variant] |
-| | Success | `#[hex]` | [standard green variant] |
-| **Typography** | Headings | [font family] | [why chosen] |
-| | Body | [font family] | [why chosen] |
-| | H1 | [size/weight] | [hierarchy purpose] |
-| | H2 | [size/weight] | [hierarchy purpose] |
-| | Body | [size/weight] | [hierarchy purpose] |
-| | Caption | [size/weight] | [hierarchy purpose] |
-| **Spacing** | Base unit | [4px / 8px] | [scaling approach] |
-| | Edge padding | [value]px | [breathing room] |
-| | Component gap | [value]px | [relationship] |
-| | Section gap | [value]px | [separation] |
-| **Borders** | Radius | [value]px | [style approach] |
-| | Width | [value]px | [visibility] |
-| **Shadows** | Elevation 1 | [values] | [subtle depth] |
-| | Elevation 2 | [values] | [prominent depth] |
-
----
+**Hints**
+- [Framework-specific reuse: "Extend existing CardWidget", "Use Tailwind group-hover"]
+- [Gotchas: "Safe area inset on iOS", "Focus trap in modal"]
+- [Responsive: "Stack cards vertically below 768px"]
 
-## Platform-Specific Notes
-
-### Web (React + Tailwind)
-
-**Responsive breakpoints:**
-- Mobile: `< 640px`
-- Tablet: `640px - 1024px`
-- Desktop: `> 1024px`
-
-**Touch targets:** Minimum 44x44px for interactive elements
-
-**Keyboard navigation:**
-- [Which elements should be focusable]
-- [Focus order/flow]
-
-**Accessibility:**
-- Color contrast: WCAG AA (4.5:1 body text, 3:1 large text)
-- Screen reader: [aria labels needed]
-
-### Mobile (Flutter)
-
-**iOS considerations:**
-- Follow HIG for [specific patterns]
-- Safe area insets: Respect notch/home indicator
-- Navigation: [pattern - stack, tabs, drawer]
-
-**Android considerations:**
-- Follow Material Design 3 for [specific patterns]
-- System bars: [edge-to-edge consideration]
-- Back gesture: [handling]
+### [Screen 2 Name]
 
-**Shared:**
-- Touch targets: 48x48dp minimum
-- Text sizes: 16sp minimum for body text
+[Repeat: wireframe + states + behavior + hints per screen]
 
 ---
 
-## Verification Criteria
-
-Observable behaviors that prove this design was implemented correctly:
-
-### Visual Verification
-- [ ] Color palette matches specification exactly
-- [ ] Typography hierarchy is clearly visible
-- [ ] Spacing follows specified scale consistently
-- [ ] Components match specified states and transitions
-
-### Functional Verification
-- [ ] [Screen 1]: User can [primary action]
-- [ ] [Screen 2]: User can [primary action]
-- [ ] [Flow 1]: User can complete [goal]
-- [ ] Error states display correctly when [condition]
-
-### Platform Verification
-- [ ] Web: Responsive layout works at all breakpoints
-- [ ] Web: Keyboard navigation functional
-- [ ] Mobile: Touch targets meet minimum size
-- [ ] Mobile: Safe areas respected
-
-### Accessibility Verification
-- [ ] Color contrast meets WCAG AA
-- [ ] Screen reader can navigate all interactive elements
-- [ ] Focus states are visible
-
----
+Validation: passed
 
 *Phase: XX-name*
 *Design created: [date]*
@@ -247,171 +99,137 @@ Observable behaviors that prove this design was implemented correctly:
 **Platform:** Web (React + Tailwind)
 **Aesthetic source:** Codebase analysis + fresh design
 
-## Visual Identity
-
-Professional analytics dashboard with approachable data visualization. Clean density inspired by Linear, with generous whitespace that doesn't sacrifice information. Dark mode primary (analysts work long hours), with a distinctive deep navy (`#0a0f1a`) instead of generic black. Amber accent (`#F59E0B`) for energy and warmth.
-
-**Design direction:**
-- Overall feel: "Powerful yet approachable"
-- Key differentiator: "Data-dense without feeling cluttered"
-- Inspiration: Linear's information hierarchy, Stripe's professional polish
-
----
-
-## Screen Layouts
+## Design Direction
+
+Professional analytics dashboard with approachable data visualization. Dark mode primary — deep navy instead of generic black, amber accent for energy. Inspired by Linear's information hierarchy and Stripe's professional polish.
+
+## Design Tokens
+
+| Token | Value | Note |
+|-------|-------|------|
+| bg-primary | `#0a0f1a` | Deep navy, not generic black |
+| bg-surface | `#1a1f2e` | Card backgrounds |
+| text-primary | `#ffffff` | |
+| text-secondary | `#8b95a8` | Labels, captions |
+| accent | `#F59E0B` | Amber — warm, stands out from cool tones |
+| error | `#ef4444` | |
+| success | `#22c55e` | |
+| font-all | Inter | Clean, excellent number rendering |
+| h1 | 32px/600 | Page titles |
+| h2 | 24px/600 | Section headers |
+| body | 14px/400 | General content |
+| caption | 12px/500 | Labels, metadata |
+| spacing-base | 4px | Scale: 4/8/12/16/24/32 |
+| edge-padding | 24px | Breathing room at edges |
+| component-gap | 16px | Related items |
+| section-gap | 32px | Distinct sections |
+| radius | 8px | |
+
+## Screens
 
 ### Dashboard Overview
 
 ```
 +------------------------------------------------------------------+
-|  [Sidebar]  |  [Header: Page Title    Date Picker    [Export]]   |
-|             |--------------------------------------------------------|
-|  [Logo]     |                                                    |
-|             |  [KPI Card 1]  [KPI Card 2]  [KPI Card 3]  [KPI 4] |
-|  Dashboard  |                                                    |
-|  Campaigns  |--------------------------------------------------------|
-|  Reports    |                                                    |
-|  Settings   |  +--------------------------------------------+    |
-|             |  |                                            |    |
-|  [Avatar]   |  |           Main Chart Area                  |    |
-|             |  |           (Trend over time)                |    |
-|             |  |                                            |    |
-|             |  +--------------------------------------------+    |
-|             |                                                    |
-|             |  +---------------------+  +---------------------+  |
-|             |  | Secondary Chart 1   |  | Secondary Chart 2   |  |
-|             |  | (Funnel)            |  | (Top Campaigns)     |  |
-|             |  +---------------------+  +---------------------+  |
+|  [Sidebar 240px]  |  ← bg-primary                                |
+|  ← bg-surface     |  [Header] h1 "Dashboard"  [DatePicker] [Export]
+|                    |                                              |
+|  Logo              |  ↕ 24px edge-padding                        |
+|  ─────────         |                                              |
+|  Dashboard  ←active|  [KPI] [KPI] [KPI] [KPI]  ← 16px gap       |
+|  Campaigns         |  ↕ 16px                    min-w:180 h:120  |
+|  Reports           |                                              |
+|  Settings          |  +--------------------------------------------+
+|                    |  | Main Chart ← bg-surface  radius:8px      |
+|  ─────────         |  | h2 "Trend"   ↔ 16px padding              |
+|  [Avatar]          |  | AreaChart                                 |
+|                    |  +--------------------------------------------+
+|                    |  ↕ 16px                                      |
+|                    |  +-------------------+  +-------------------+|
+|                    |  | FunnelChart       |  | BarChart          ||
+|                    |  | ← bg-surface      |  | ← bg-surface     ||
+|                    |  +-------------------+  +-------------------+|
 +------------------------------------------------------------------+
 ```
 
-**Dimensions:** 1440x900 primary, responsive to 1024px
-**Edge padding:** 24px
-**Component gaps:** 16px
-**Sidebar width:** 240px (collapsible to 64px on tablet)
-
-**Components used:**
-- Sidebar: NavSidebar, Logo, UserAvatar
-- Header: PageHeader, DateRangePicker, ExportButton
-- KPIs: MetricCard (x4)
-- Charts: AreaChart, FunnelChart, BarChart
-
-**Responsive behavior:**
-- Desktop (1024px+): Full sidebar, 4 KPI cards in row, 2-column secondary charts
-- Tablet (768-1024px): Collapsed sidebar (icons only), 2 KPI cards per row
-- Mobile (<768px): Bottom nav replaces sidebar, stacked layout
-
----
-
-## Component Specifications
-
-### MetricCard
-
-**Purpose:** Display single KPI with trend indicator
+**States**
 
-**Visual:**
-- Background: `#1a1f2e` (dark navy)
-- Border: 1px `#2a3142`, 8px radius
-- Shadow: none (flat design)
-- Size: min 180px width, 120px height
+| Element | State | Change | Trigger |
+|---------|-------|--------|---------|
+| KPI Card | hover | border brightens `#2a3142` → `#3a4152` | mouse over |
+| KPI Card | loading | content → skeleton pulse | data fetch |
+| Nav item | active | text-primary + left accent bar | current route |
+| Sidebar | collapsed | 240px → 64px (icons only) | tablet ≤1024px |
 
-**States:**
-| State | Visual Change | Trigger |
-|-------|--------------|---------|
-| Default | Base appearance | Initial |
-| Hover | Border brightens to `#3a4152` | Mouse over |
-| Loading | Content replaced with skeleton | Data fetching |
+**Behavior**
+- Date picker filters all displayed data (KPIs + charts) simultaneously
+- Chart tooltips appear on hover with exact values and % change
+- Bottom nav replaces sidebar below 768px
 
-**Content:**
-- Label: 12px, 500 weight, `#8b95a8`
-- Value: 32px, 600 weight, `#ffffff`
-- Trend: 14px, `#22c55e` (up) or `#ef4444` (down)
-- Spacing: 16px padding all sides
+**Hints**
+- Sidebar collapse: CSS transition 200ms, persist preference in localStorage
+- KPI cards: Use CSS Grid `repeat(auto-fit, minmax(180px, 1fr))` for responsive wrapping
+- Charts: Lazy-load chart library, show skeleton during load
+- Touch targets: All nav items and buttons ≥ 44px
 
 ---
 
-## Design System Decisions
-
-| Category | Decision | Values | Rationale |
-|----------|----------|--------|-----------|
-| **Colors** | Primary | `#0a0f1a` | Deep navy instead of pure black - warmer, more sophisticated |
-| | Secondary | `#1a1f2e` | Card backgrounds - slight contrast from primary |
-| | Text | `#ffffff` | Primary text |
-| | Text Secondary | `#8b95a8` | Labels, captions |
-| | Accent | `#F59E0B` | Amber - warm, energetic, stands out from cool tones |
-| **Typography** | All | Inter | Clean, professional, excellent number rendering |
-| | H1 | 32px/600 | Page titles |
-| | H2 | 24px/600 | Section headers |
-| | Body | 14px/400 | General content |
-| | Caption | 12px/500 | Labels, metadata |
-| **Spacing** | Base unit | 4px | 4/8/12/16/24/32/48 scale |
-| | Edge padding | 24px | Breathing room at edges |
-| | Component gap | 16px | Related items |
-| | Section gap | 32px | Distinct sections |
-
----
-
-## Verification Criteria
-
-### Visual Verification
-- [ ] Background is deep navy `#0a0f1a`, not generic black
-- [ ] Accent color is amber `#F59E0B`, visible in buttons and highlights
-- [ ] Cards have consistent 16px internal padding
-- [ ] Typography uses Inter font family
-
-### Functional Verification
-- [ ] Dashboard: All 4 KPI cards display with correct values
-- [ ] Dashboard: Main chart shows trend data with interactive tooltips
-- [ ] Dashboard: Date picker filters all displayed data
-
-### Platform Verification
-- [ ] Responsive: Sidebar collapses to icons at 1024px
-- [ ] Responsive: Layout stacks vertically below 768px
-- [ ] Touch: All interactive elements meet 44px minimum
-
----
+Validation: passed
 
 *Phase: 03-user-dashboard*
 *Design created: 2026-01-19*
 ```
 </good_examples>
 
+<annotation_conventions>
+**Arrows and inline refs in wireframes:**
+- `←` points to a property of the region (e.g., `← bg-surface` means this area uses bg-surface token)
+- `↕` vertical spacing between elements (e.g., `↕ 16px`)
+- `↔` horizontal padding/spacing (e.g., `↔ 16px padding`)
+- Token names reference the Design Tokens table (e.g., `bg-primary`, `accent`, `h1`)
+- Dimensions inline where relevant (e.g., `min-w:180 h:120`, `240px`)
+- Component names in `[brackets]`
+</annotation_conventions>
+
 <guidelines>
 **This template captures DESIGN, not technical implementation.**
 
 The design phase produces:
-- How it should look (visual identity, layouts)
-- How it should behave (states, transitions)
-- How it should feel (UX flows, interactions)
-- What proves it's correct (verification criteria)
+- How it should look (wireframe layouts with inline specs)
+- How it should behave (states, non-obvious interactions)
+- How it should feel (design direction)
+- Implementation hints (framework-specific reuse, gotchas)
 
 The design phase does NOT produce:
 - Library choices (that's research)
 - Task breakdown (that's planning)
 - Code architecture (that's execution)
+- Verification criteria (plan writer derives from specs)
 
 **Content should read like:**
 - A design specification a developer can implement
-- "The card has 16px padding, 8px border radius, and a subtle shadow"
-- "On hover, the border brightens from #2a3142 to #3a4152"
-- ASCII wireframes showing exact layout structure
+- ASCII wireframes with inline token refs, spacing, and dimensions
+- States tables with concrete triggers and changes
+- Behavior notes for non-obvious interactions only
 
 **Content should NOT read like:**
 - A technical architecture document
 - A list of npm packages to install
 - Code snippets or implementation details
 - Vague descriptions ("make it look nice")
+- Narration of obvious interactions ("user taps button, form submits")
 
 **Quality markers:**
-- Specific color values (hex codes), not "blue" or "primary"
-- Exact spacing values (16px), not "some padding"
-- All component states defined (default, hover, active, disabled)
-- ASCII wireframes with labeled regions
-- Verification criteria that are observable and testable
+- Specific values in tokens (hex, px, font/weight), not "blue" or "primary"
+- All values appear exactly once — in tokens table or inline wireframe annotation
+- All component states defined (default, hover, active, disabled, loading)
+- ASCII wireframes with inline annotations (token refs, spacing, dimensions)
+- Non-obvious behaviors documented, obvious ones omitted
 
 **After creation:**
 - File lives in phase directory: `.planning/phases/XX-name/{phase}-DESIGN.md`
 - Research phase adds technical details (which libraries enable this design)
 - Planning phase creates tasks that reference design specs
+- Plan writer derives verification criteria from specs
 - Execute phase implements to match design exactly
 </guidelines>

package/mindsystem/templates/knowledge.md

@@ -54,7 +54,7 @@ Template for `.planning/knowledge/{subsystem}.md` — per-subsystem knowledge fi
 |---------|----------|-----------------|
 | **Decisions** | Choices with rationale (the "because" part) | CONTEXT.md locked decisions, RESEARCH.md recommendations, PLAN.md approach rationale, SUMMARY.md key-decisions |
 | **Architecture** | How the subsystem works, structural patterns | RESEARCH.md architecture patterns, PLAN.md implementation details, SUMMARY.md accomplishments |
-| **Design** | Visual/UX specs, interaction patterns, design tokens | DESIGN.md component specs, UX flows, color/spacing values |
+| **Design** | Visual/UX specs, interaction patterns, design tokens | DESIGN.md wireframe layouts, states tables, behavior notes, design tokens |
 | **Pitfalls** | What to watch out for, operational patterns | RESEARCH.md common pitfalls, SUMMARY.md issues/deviations, debug resolutions, adhoc learnings |
 | **Key Files** | Important file paths for this subsystem | SUMMARY.md key-files, PLAN.md file targets |
 

package/mindsystem/templates/milestone-archive.md

@@ -89,7 +89,7 @@ Plans:
 
 ---
 
-_For current project status, see .planning/ROADMAP.md_
+_For current project status, see .planning/PROJECT.md_
 
 ---
 
@@ -117,7 +117,7 @@ _For current project status, see .planning/ROADMAP.md_
 
 **After archiving:**
 
-- Update ROADMAP.md to collapse completed milestone in `<details>` tag
-- Update PROJECT.md to brownfield format with Current State section
+- Delete ROADMAP.md (fresh one created for next milestone via `/ms:create-roadmap`)
+- Update PROJECT.md with full evolution review
 - Continue phase numbering in next milestone (never restart at 01)
   </guidelines>

package/mindsystem/templates/phase-prompt.md

@@ -16,19 +16,18 @@ read `~/.claude/mindsystem/references/plan-format.md`.
 
 ## Scope Guidance
 
-**Plan sizing:**
+**Plan sizing — budget-based grouping:**
 
-- 2-3 tasks per plan, ~50% context usage maximum
-- Default to 3 tasks for simple-medium work, 2 for complex
-- Executor overhead reduction creates headroom for the third task
-- Complex phases: Multiple focused plans, not one large plan
+Weight classifications (L: 5%, M: 10%, H: 20%) defined in scope-estimation.md.
+
+Grouping rule: `sum(weights) <= 45%`. Target 25-45% per plan. Plans under ~10% → consolidate with related same-wave work. Bias toward consolidation.
 
 **When to split:**
 
 - Different subsystems (auth vs API vs UI)
-- More than 3 tasks
+- Budget sum exceeds 45%
 - Risk of context overflow
-- TDD candidates — separate plans
+- TDD candidates — separate plans (inherently heavy-weight)
 
 **Vertical slices preferred:**
 

package/mindsystem/templates/research-subagent-prompt.md

@@ -22,7 +22,7 @@ Templates for the 3 parallel agents spawned by `/ms:research-phase`. The orchest
 ## Template 1: External Docs (ms-researcher)
 
 **Focus:** Library documentation, APIs, verified code examples
-**Tools emphasized:** ms-lookup docs (Context7), ms-lookup deep (Perplexity), WebSearch, WebFetch
+**Tools emphasized:** ms-lookup docs, ms-lookup deep, WebSearch, WebFetch
 **Returns:** Structured findings (not files)
 
 ```markdown
@@ -118,7 +118,7 @@ The agent's built-in `<what_to_scan>` section handles the systematic scan checkl
 ## Template 3: Best Practices (ms-researcher)
 
 **Focus:** Community consensus, pitfalls, SOTA
-**Tools emphasized:** ms-lookup deep (Perplexity), WebSearch
+**Tools emphasized:** ms-lookup deep, WebSearch
 **Returns:** Structured findings (not files)
 
 ```markdown