mindsystem-cc 3.11.0 → 3.13.0

package/mindsystem/workflows/mockup-generation.md

@@ -87,16 +87,22 @@ Task(prompt=assembled_context, subagent_type="ms-mockup-designer", description="
 </step>
 
 <step name="present_mockups">
-After all 3 agents return, display file paths:
+After all 3 agents return, generate comparison page and open it:
+
+```bash
+uv run ~/.claude/mindsystem/scripts/compare_mockups.py "${PHASE_DIR}/mockups"
+open "${PHASE_DIR}/mockups/comparison.html"
+```
+
+Display summary:
 
 ```markdown
-3 mockup variants generated:
+3 mockup variants generated — comparison page opened in browser.
 
+Individual variants for reference:
 - **A: {Direction A name}** — `.planning/phases/{phase}-{slug}/mockups/variant-a.html`
 - **B: {Direction B name}** — `.planning/phases/{phase}-{slug}/mockups/variant-b.html`
 - **C: {Direction C name}** — `.planning/phases/{phase}-{slug}/mockups/variant-c.html`
-
-Open these in your browser to compare.
 ```
 
 Use AskUserQuestion:

package/mindsystem/workflows/plan-phase.md

@@ -36,7 +36,7 @@ PLAN.md IS the prompt that Claude executes. Plans are grouped into execution wav
 
 **Vertical slices over horizontal layers:** Group by feature (User: model + API + UI) not by type (all models → all APIs → all UIs).
 
-**Explicit dependencies:** Every plan declares what it needs (`depends_on`) and what it touches (`files_modified`). Empty dependencies = parallel candidate.
+**Explicit dependencies:** EXECUTION-ORDER.md centralizes dependency and parallelism tracking. Plans with no dependencies = parallel candidates.
 
 **Secure by design:** Assume hostile input on every boundary. Validate, parameterize, authenticate, fail closed.
 
@@ -120,7 +120,7 @@ grep -l "status: diagnosed" "$PHASE_DIR"/*-UAT.md 2>/dev/null
 
 **2. Parse gaps:**
 
-**From VERIFICATION.md** (if exists): Parse `gaps:` from YAML frontmatter.
+**From VERIFICATION.md** (if exists): Parse gaps from `## Gaps Summary` section (markdown format with `### Critical Gaps` and `### Non-Critical Gaps` subsections).
 
 **From UAT.md** (if exists with status: diagnosed): Parse gaps from `## Gaps` section (YAML format).
 
@@ -154,40 +154,49 @@ Cluster related gaps by:
 - Same concern (fetch + render → one "wire frontend" plan)
 - Dependency order (can't wire if artifact is stub → fix stub first)
 
-**6. Create gap closure tasks:**
+**6. Create gap closure changes:**
 
-For each gap:
-```xml
-<task name="{fix_description}" type="auto">
-  <files>{artifact.path}</files>
-  <action>
-    {For each item in gap.missing:}
-    - {missing item}
-
-    Reference existing code: {from SUMMARYs}
-    Gap reason: {gap.reason}
-  </action>
-  <verify>{How to confirm gap is closed}</verify>
-  <done>{Observable truth now achievable}</done>
-</task>
+For each gap, create a markdown change subsection:
+
+```markdown
+### N. {Fix description}
+**Files:** `{artifact.path}`
+
+{For each item in gap.missing:}
+- {missing item}
+
+Reference existing code: {from SUMMARYs}
+Gap reason: {gap.reason}
 ```
 
 **7. Write PLAN.md files:**
 
-Use standard template but note gap closure context:
+Use pure markdown plan format with gap closure context:
 
-```yaml
----
-phase: XX-name
-plan: NN              # Sequential after existing
-type: execute
-wave: 1               # Gap closures typically single wave
-depends_on: []        # Usually independent of each other
-files_modified: [...]
-gap_closure: true     # Flag for tracking
----
+```markdown
+# Plan NN: {Gap closure description}
+
+**Subsystem:** {subsystem} | **Type:** execute
+
+## Context
+Gap closure for phase XX. Addresses gaps identified by verification.
+
+## Changes
+
+### 1. {Fix description}
+**Files:** `{artifact.path}`
+
+{Implementation details from gap.missing items}
+
+## Verification
+- {How to confirm gap is closed}
+
+## Must-Haves
+- [ ] {Observable truth now achievable}
 ```
 
+Also create or update EXECUTION-ORDER.md to include gap closure plans (typically single wave, independent of each other).
+
 **9. Present gap closure summary:**
 
 ```markdown
@@ -432,7 +441,7 @@ cat .planning/phases/XX-name/${PHASE}-DESIGN.md 2>/dev/null
 **If DESIGN.md exists:**
 - Tasks reference specific screens/components from design
 - Verification criteria include design verification items
-- must_haves include design-specified observable behaviors
+- Must-Haves include design-specified observable behaviors
 - Task actions specify exact values (colors, spacing) from design
 
 **If none exist:** Suggest /ms:research-phase for niche domains, /ms:discuss-phase for simpler domains, or proceed with roadmap only.
@@ -494,43 +503,16 @@ External service indicators:
 Note external services for risk scoring.
 
 <output_format>
-**After task identification, produce structured task list for handoff:**
+**Present a concise numbered task summary for the user:**
 
-```xml
-<task_list>
-  <task id="1">
-    <name>Create User model</name>
-    <type>auto</type>
-    <needs>nothing</needs>
-    <creates>src/models/user.ts</creates>
-    <tdd_candidate>false</tdd_candidate>
-    <action_hint>Define User type with id, email, createdAt</action_hint>
-    <verify_hint>tsc --noEmit passes</verify_hint>
-    <done_hint>User type exportable</done_hint>
-  </task>
-  <task id="2">
-    <name>Create login endpoint</name>
-    <type>auto</type>
-    <needs>src/models/user.ts</needs>
-    <creates>src/app/api/auth/login/route.ts</creates>
-    <tdd_candidate>true</tdd_candidate>
-    <action_hint>POST endpoint with bcrypt validation</action_hint>
-    <verify_hint>curl returns 200 with valid credentials</verify_hint>
-    <done_hint>Login works with valid credentials</done_hint>
-  </task>
-</task_list>
-```
+### Tasks Identified
+
+1. **Create User model** → `src/models/user.ts` (no dependencies)
+2. **Create login endpoint** → `src/app/api/auth/login/route.ts` (needs: Task 1) [TDD]
+
+Format: numbered list with task name, key files, dependency hint, and `[TDD]` flag if applicable. No XML.
 
-Each task captures:
-- `id`: Sequential identifier
-- `name`: Action-oriented task name
-- `type`: auto
-- `needs`: Files/types this task requires (or "nothing")
-- `creates`: Files/types this task produces (or "nothing")
-- `tdd_candidate`: true if should be TDD plan
-- `action_hint`: Brief implementation guidance (subagent expands)
-- `verify_hint`: How to verify completion
-- `done_hint`: Acceptance criteria
+**Retain full task details internally.** For each task, maintain in your analysis: id, name, type, needs, creates, tdd_candidate, action_hint, verify_hint, done_hint. These are needed for the handoff step — they just don't need to be displayed.
 </output_format>
 </step>
 
@@ -545,7 +527,7 @@ Assemble handoff payload:
 
 ```xml
 <task_list>
-  {tasks from break_into_tasks}
+  {Construct full task XML from your analysis. Each task needs: id, name, type, needs, creates, tdd_candidate, action_hint, verify_hint, done_hint. Use the same XML schema the plan-writer expects.}
 </task_list>
 
 <phase_context>
@@ -554,7 +536,6 @@ Assemble handoff payload:
   <phase_dir>.planning/phases/{PHASE}-{PHASE_NAME}</phase_dir>
   <phase_goal>{goal from ROADMAP}</phase_goal>
   <requirements>{REQ-IDs from ROADMAP}</requirements>
-  <depth>{from config.json or "standard"}</depth>
   <subsystem_hint>{best-match subsystem from config.json}</subsystem_hint>
 </phase_context>
 
@@ -601,10 +582,10 @@ Task(
 The subagent handles:
 - Building dependency graph from needs/creates
 - Assigning wave numbers
-- Grouping tasks into plans (2-3 per plan)
-- Deriving must_haves (goal-backward)
+- Grouping tasks into plans (2-3 changes per plan)
+- Deriving Must-Haves (goal-backward)
 - Estimating scope, splitting if needed
-- Writing PLAN.md files
+- Writing PLAN.md files + EXECUTION-ORDER.md
 - Git commit
 - Calculating risk score
 </step>
@@ -772,10 +753,10 @@ Tasks are instructions for Claude, not Jira tickets.
 - [ ] Prior decisions, issues, concerns synthesized
 - [ ] Tasks identified with needs/creates dependencies
 - [ ] Task list handed off to ms-plan-writer
-- [ ] PLAN file(s) created by subagent with XML structure
-- [ ] Each plan: depends_on, files_modified in frontmatter
-- [ ] Each plan: must_haves derived (truths, artifacts, key_links)
-- [ ] Each plan: 2-3 tasks (~50% context)
+- [ ] PLAN file(s) created with pure markdown format
+- [ ] EXECUTION-ORDER.md created with wave groups
+- [ ] Each plan: Must-Haves section with observable truths
+- [ ] Each plan: 2-3 changes (~50% context)
 - [ ] Wave structure maximizes parallelism
 - [ ] PLAN file(s) committed to git
 - [ ] Risk assessment presented (score + top factors)
@@ -787,8 +768,8 @@ Tasks are instructions for Claude, not Jira tickets.
 - [ ] Existing SUMMARYs read for context
 - [ ] Gaps clustered into focused plans
 - [ ] Plan numbers sequential after existing (04, 05...)
-- [ ] PLAN file(s) exist with gap_closure: true
-- [ ] Each plan: tasks derived from gap.missing items
+- [ ] PLAN file(s) created with pure markdown format
+- [ ] EXECUTION-ORDER.md updated with gap closure plans
 - [ ] PLAN file(s) committed to git
 - [ ] User knows to run `/ms:execute-phase {X}` next
 </success_criteria>

package/mindsystem/workflows/transition.md

@@ -50,14 +50,6 @@ ls .planning/phases/XX-current/*-SUMMARY.md 2>/dev/null | sort
 - If counts match: all plans complete
 - If counts don't match: incomplete
 
-<config-check>
-
-```bash
-cat .planning/config.json 2>/dev/null
-```
-
-</config-check>
-
 **If all plans complete:**
 
 ```
@@ -71,8 +63,7 @@ Proceed directly to cleanup_handoff step.
 
 **If plans incomplete:**
 
-**SAFETY RAIL: always_confirm_destructive applies here.**
-Skipping incomplete plans is destructive — ALWAYS prompt regardless of mode.
+**SAFETY RAIL: Skipping incomplete plans is destructive — always confirm.**
 
 Present:
 

package/mindsystem/workflows/verify-phase.md

@@ -42,7 +42,7 @@ grep -E "^| ${PHASE_NUM}" .planning/REQUIREMENTS.md 2>/dev/null
 # All SUMMARY files (claims to verify)
 ls "$PHASE_DIR"/*-SUMMARY.md 2>/dev/null
 
-# All PLAN files (for must_haves in frontmatter)
+# All PLAN files (for Must-Haves in plan markdown)
 ls "$PHASE_DIR"/*-PLAN.md 2>/dev/null
 ```
 
@@ -54,32 +54,28 @@ ls "$PHASE_DIR"/*-PLAN.md 2>/dev/null
 <step name="establish_must_haves">
 **Determine what must be verified.**
 
-**Option A: Must-haves in PLAN frontmatter**
+**Option A: Must-haves in plan markdown**
 
-Check if any PLAN.md has `must_haves` in frontmatter:
+Check if any PLAN.md has a `## Must-Haves` section:
 
 ```bash
-grep -l "must_haves:" "$PHASE_DIR"/*-PLAN.md 2>/dev/null
+grep -l "## Must-Haves" "$PHASE_DIR"/*-PLAN.md 2>/dev/null
 ```
 
-If found, extract and use:
-```yaml
-must_haves:
-  truths:
-    - "User can see existing messages"
-    - "User can send a message"
-  artifacts:
-    - path: "src/components/Chat.tsx"
-      provides: "Message list rendering"
-  key_links:
-    - from: "Chat.tsx"
-      to: "api/chat"
-      via: "fetch in useEffect"
+If found, extract checklist items. Must-haves are markdown checklist entries:
+
+```markdown
+## Must-Haves
+- [ ] User can see existing messages
+- [ ] User can send a message
+- [ ] Messages persist after refresh
 ```
 
+Each `- [ ]` item is an observable truth to verify. Derive artifacts from `**Files:**` lines in `## Changes` sections and key links from the implementation details.
+
 **Option B: Derive from phase goal**
 
-If no must_haves in frontmatter, derive using goal-backward process:
+If no `## Must-Haves` section found in plans, derive using goal-backward process:
 
 1. **State the goal:** Take phase goal from ROADMAP.md
 
@@ -370,7 +366,7 @@ verify_state_render_link() {
 
 ### Aggregate key link results
 
-For each key link in must_haves:
+For each key link derived from plan `## Changes` and `## Must-Haves` sections:
 - Run appropriate verification function
 - Record status and evidence
 - WIRED / PARTIAL / STUB / NOT_WIRED
@@ -615,7 +611,7 @@ The orchestrator will:
 </process>
 
 <success_criteria>
-- [ ] Must-haves established (from frontmatter or derived)
+- [ ] Must-haves established (from plan ## Must-Haves section or derived)
 - [ ] All truths verified with status and evidence
 - [ ] All artifacts checked at all three levels
 - [ ] All key links verified

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindsystem-cc",
-  "version": "3.11.0",
+  "version": "3.13.0",
   "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.",
   "bin": {
     "mindsystem-cc": "bin/install.js"

package/scripts/update-state.sh

@@ -0,0 +1,59 @@
+#!/bin/bash
+#
+# update-state.sh
+# Updates .planning/STATE.md Plan and Status lines based on plan progress.
+# Idempotent — same arguments produce the same result.
+#
+# Usage: ./scripts/update-state.sh <completed_plan_count> <total_plans>
+# Example: ./scripts/update-state.sh 2 4
+#          (2 of 4 plans complete)
+#
+
+set -e
+
+# --- Validation ---
+if [ -z "$1" ] || [ -z "$2" ]; then
+  echo "Error: Two arguments required"
+  echo "Usage: $0 <completed_plan_count> <total_plans>"
+  exit 1
+fi
+
+COMPLETED="$1"
+TOTAL="$2"
+
+if ! [[ "$COMPLETED" =~ ^[0-9]+$ ]] || ! [[ "$TOTAL" =~ ^[0-9]+$ ]]; then
+  echo "Error: Both arguments must be numeric"
+  echo "Usage: $0 <completed_plan_count> <total_plans>"
+  exit 1
+fi
+
+if [ "$COMPLETED" -gt "$TOTAL" ]; then
+  echo "Error: Completed ($COMPLETED) cannot exceed total ($TOTAL)"
+  exit 1
+fi
+
+# --- Find STATE.md from git root ---
+GIT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+if [ -z "$GIT_ROOT" ]; then
+  echo "Error: Not in a git repository"
+  exit 1
+fi
+
+STATE_FILE="$GIT_ROOT/.planning/STATE.md"
+if [ ! -f "$STATE_FILE" ]; then
+  echo "Error: STATE.md not found at $STATE_FILE"
+  exit 1
+fi
+
+# --- Update Plan line ---
+sed -i '' "s/^Plan:.*/Plan: $COMPLETED of $TOTAL complete in current phase/" "$STATE_FILE"
+
+# --- Update Status line ---
+if [ "$COMPLETED" -eq "$TOTAL" ]; then
+  sed -i '' "s/^Status:.*/Status: All plans executed, pending verification/" "$STATE_FILE"
+else
+  sed -i '' "s/^Status:.*/Status: In progress — plan $COMPLETED of $TOTAL complete/" "$STATE_FILE"
+fi
+
+echo "STATE.md updated: $COMPLETED of $TOTAL plans complete"
+exit 0

package/scripts/validate-execution-order.sh

@@ -0,0 +1,102 @@
+#!/bin/bash
+#
+# validate-execution-order.sh
+# Validates EXECUTION-ORDER.md against plan files in a phase directory.
+# Checks bidirectional consistency and warns about file conflicts within waves.
+#
+# Usage: ./scripts/validate-execution-order.sh <phase_directory>
+# Example: ./scripts/validate-execution-order.sh .planning/phases/03-auth
+#
+
+set -e
+
+# --- Validation ---
+if [ -z "$1" ]; then
+  echo "Error: Phase directory required"
+  echo "Usage: $0 <phase_directory>"
+  exit 1
+fi
+
+PHASE_DIR="$1"
+
+if [ ! -d "$PHASE_DIR" ]; then
+  echo "FAIL: Directory does not exist: $PHASE_DIR"
+  exit 1
+fi
+
+EXEC_ORDER="$PHASE_DIR/EXECUTION-ORDER.md"
+if [ ! -f "$EXEC_ORDER" ]; then
+  echo "FAIL: EXECUTION-ORDER.md not found in $PHASE_DIR"
+  exit 1
+fi
+
+# --- Collect plan files on disk ---
+DISK_PLANS=$(ls -1 "$PHASE_DIR"/*-PLAN.md 2>/dev/null | xargs -I{} basename {} | sort)
+DISK_COUNT=$(echo "$DISK_PLANS" | grep -c . 2>/dev/null || echo 0)
+
+if [ "$DISK_COUNT" -eq 0 ]; then
+  echo "FAIL: No *-PLAN.md files found in $PHASE_DIR"
+  exit 1
+fi
+
+# --- Parse EXECUTION-ORDER.md for plan filenames ---
+ORDER_PLANS=$(grep -oE '[0-9]+-PLAN\.md' "$EXEC_ORDER" | sort -u)
+ORDER_COUNT=$(echo "$ORDER_PLANS" | grep -c . 2>/dev/null || echo 0)
+
+# --- Check 1: Every disk plan is listed in EXECUTION-ORDER.md ---
+ERRORS=""
+while IFS= read -r plan; do
+  if ! echo "$ORDER_PLANS" | grep -qx "$plan"; then
+    ERRORS="${ERRORS}  Missing from EXECUTION-ORDER.md: $plan\n"
+  fi
+done <<< "$DISK_PLANS"
+
+# --- Check 2: Every plan in EXECUTION-ORDER.md exists on disk ---
+while IFS= read -r plan; do
+  if ! echo "$DISK_PLANS" | grep -qx "$plan"; then
+    ERRORS="${ERRORS}  Listed in EXECUTION-ORDER.md but file missing: $plan\n"
+  fi
+done <<< "$ORDER_PLANS"
+
+if [ -n "$ERRORS" ]; then
+  echo "FAIL: Plan/execution-order mismatch"
+  printf "%b" "$ERRORS"
+  exit 1
+fi
+
+# --- Check 3 (warning): File conflicts within waves ---
+CURRENT_WAVE=""
+WAVE_COUNT=0
+declare -A WAVE_FILES
+
+while IFS= read -r line; do
+  if echo "$line" | grep -qE '^## Wave [0-9]+'; then
+    CURRENT_WAVE=$(echo "$line" | grep -oE '[0-9]+')
+    WAVE_COUNT=$((WAVE_COUNT + 1))
+    WAVE_FILES[$CURRENT_WAVE]=""
+  elif [ -n "$CURRENT_WAVE" ]; then
+    PLAN_FILE=$(echo "$line" | grep -oE '[0-9]+-PLAN\.md' || true)
+    if [ -n "$PLAN_FILE" ] && [ -f "$PHASE_DIR/$PLAN_FILE" ]; then
+      # Extract **Files:** lines from plan
+      FILE_PATHS=$(grep -E '^\*\*Files:\*\*' "$PHASE_DIR/$PLAN_FILE" | sed 's/\*\*Files:\*\*//g' | tr ',' '\n' | sed 's/`//g; s/^[[:space:]]*//; s/[[:space:]]*$//' | grep -v '^$' || true)
+      while IFS= read -r fpath; do
+        [ -z "$fpath" ] && continue
+        EXISTING="${WAVE_FILES[$CURRENT_WAVE]}"
+        if echo "$EXISTING" | grep -qF "|$fpath|"; then
+          echo "WARNING: File '$fpath' appears in multiple plans within Wave $CURRENT_WAVE"
+        else
+          WAVE_FILES[$CURRENT_WAVE]="${EXISTING}|$fpath|"
+        fi
+      done <<< "$FILE_PATHS"
+    fi
+  fi
+done < "$EXEC_ORDER"
+
+# --- Handle edge case: no waves parsed ---
+if [ "$WAVE_COUNT" -eq 0 ]; then
+  echo "FAIL: No '## Wave N' headers found in EXECUTION-ORDER.md"
+  exit 1
+fi
+
+echo "PASS: $DISK_COUNT plans across $WAVE_COUNT waves"
+exit 0

package/skills/flutter-code-quality/SKILL.md

@@ -24,11 +24,12 @@ Comprehensive guidelines for Flutter/Dart code quality, widget organization, and
 
 Fetch fresh guidelines before each review:
 
-```
-https://gist.githubusercontent.com/rolandtolnay/edf9ea7d5adf218f45accb3411f0627c/raw/flutter-code-quality-guidelines.md
+```bash
+gh api /gists/edf9ea7d5adf218f45accb3411f0627c \
+  --jq '.files["flutter-code-quality-guidelines.md"].content'
 ```
 
-Use WebFetch to retrieve. Contains: anti-patterns, widget patterns, state management, collections, hooks, theme/styling, etc.
+Never use WebFetch for gist content — it summarizes instead of returning raw text. Contains: anti-patterns, widget patterns, state management, collections, hooks, theme/styling, etc.
 
 ## Widget Organization Guidelines (Embedded)