mindsystem-cc 3.12.0 → 3.13.0

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.
@@ -573,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>
@@ -744,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)
@@ -759,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/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.12.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)