mindsystem-cc 3.10.0 → 3.11.0

package/mindsystem/workflows/plan-phase.md

@@ -18,7 +18,7 @@ Decimal phases enable urgent work insertion without renumbering:
 1. .planning/ROADMAP.md
 2. .planning/PROJECT.md
 
-**Note:** Heavy references (phase-prompt.md, plan-format.md, scope-estimation.md, checkpoints.md, goal-backward.md, plan-risk-assessment.md) are loaded by the ms-plan-writer subagent, not main context. Lighter references (checkpoint-detection.md, tdd.md) are loaded on demand during task breakdown.
+**Note:** Heavy references (phase-prompt.md, plan-format.md, scope-estimation.md, goal-backward.md, plan-risk-assessment.md) are loaded by the ms-plan-writer subagent, not main context. Lighter references (tdd.md) are loaded on demand during task breakdown.
 </required_reading>
 
 <purpose>
@@ -184,7 +184,6 @@ type: execute
 wave: 1               # Gap closures typically single wave
 depends_on: []        # Usually independent of each other
 files_modified: [...]
-autonomous: true
 gap_closure: true     # Flag for tracking
 ---
 ```
@@ -450,9 +449,9 @@ For each potential task, ask:
 3. **Can this run independently?** (no dependencies = Wave 1 candidate)
 
 **Standard tasks need:**
-- **Type**: auto, checkpoint:human-verify, checkpoint:decision (human-action rarely needed)
+- **Type**: auto
 - **Task name**: Clear, action-oriented
-- **Files**: Which files created/modified (for auto tasks)
+- **Files**: Which files created/modified
 - **Action hint**: Brief implementation guidance
 - **Verify hint**: How to prove it worked
 - **Done hint**: Acceptance criteria
@@ -480,11 +479,9 @@ Standard tasks (remain in standard plans):
 
 Read `~/.claude/mindsystem/references/tdd.md` now for TDD criteria and plan structure.
 
-**Checkpoints:** Visual/functional verification → checkpoint:human-verify. Implementation choices → checkpoint:decision. Manual action (email, 2FA) → checkpoint:human-action (rare).
+**Decisions:** If you identify a task that requires choosing between approaches (which auth provider, which database, etc.), use AskUserQuestion to resolve it now. Don't defer decisions to execution. For purely technical choices where the user hasn't expressed preference, make the decision and document it in the plan's objective.
 
-**Critical:** If external resource has CLI/API (Vercel, Stripe, etc.), use type="auto" to automate. Only checkpoint for verification AFTER automation.
-
-Read `~/.claude/mindsystem/references/checkpoint-detection.md` now for detection rules.
+**Critical:** If external resource has CLI/API (Vercel, Stripe, etc.), use type="auto" to automate.
 
 **User setup detection:** For tasks involving external services, identify human-required configuration:
 
@@ -506,7 +503,6 @@ Note external services for risk scoring.
     <type>auto</type>
     <needs>nothing</needs>
     <creates>src/models/user.ts</creates>
-    <checkpoint>false</checkpoint>
     <tdd_candidate>false</tdd_candidate>
     <action_hint>Define User type with id, email, createdAt</action_hint>
     <verify_hint>tsc --noEmit passes</verify_hint>
@@ -517,33 +513,20 @@ Note external services for risk scoring.
     <type>auto</type>
     <needs>src/models/user.ts</needs>
     <creates>src/app/api/auth/login/route.ts</creates>
-    <checkpoint>false</checkpoint>
     <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 id="3">
-    <name>Verify login flow</name>
-    <type>checkpoint:human-verify</type>
-    <needs>src/app/api/auth/login/route.ts</needs>
-    <creates>nothing</creates>
-    <checkpoint>true</checkpoint>
-    <tdd_candidate>false</tdd_candidate>
-    <action_hint>N/A</action_hint>
-    <verify_hint>User tests login manually</verify_hint>
-    <done_hint>User approves login flow</done_hint>
-  </task>
 </task_list>
 ```
 
 Each task captures:
 - `id`: Sequential identifier
 - `name`: Action-oriented task name
-- `type`: auto, checkpoint:human-verify, checkpoint:decision, checkpoint:human-action
+- `type`: auto
 - `needs`: Files/types this task requires (or "nothing")
 - `creates`: Files/types this task produces (or "nothing")
-- `checkpoint`: true if requires user interaction
 - `tdd_candidate`: true if should be TDD plan
 - `action_hint`: Brief implementation guidance (subagent expands)
 - `verify_hint`: How to verify completion
@@ -790,7 +773,7 @@ Tasks are instructions for Claude, not Jira tickets.
 - [ ] 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, autonomous in frontmatter
+- [ ] Each plan: depends_on, files_modified in frontmatter
 - [ ] Each plan: must_haves derived (truths, artifacts, key_links)
 - [ ] Each plan: 2-3 tasks (~50% context)
 - [ ] Wave structure maximizes parallelism

package/mindsystem/workflows/verify-work.md

@@ -139,25 +139,63 @@ Skip internal/non-observable items (refactors, type changes, etc.).
 </step>
 
 <step name="classify_tests">
-**Classify all tests by mock requirements:**
+**Classify all tests by mock requirements using two-tier analysis:**
 
-For each test, analyze the expected behavior to determine:
+For each test, determine:
 1. **mock_required**: Does this need special backend state?
-2. **mock_type**: Freeform string describing needed state (e.g., "error_state", "premium_user", "empty_response")
+2. **mock_type**: Classification (e.g., "transient_state", "external_data", "error_state", "premium_user", "empty_response")
 3. **dependencies**: Other tests this depends on (infer from descriptions)
 
-**Classification heuristics:**
+**Tier 1: SUMMARY.md mock_hints (primary)**
+
+Check if SUMMARY.md files contain mock_hints frontmatter:
+```bash
+grep -l "mock_hints:" "$PHASE_DIR"/*-SUMMARY.md 2>/dev/null
+```
+
+If found, check the value:
+
+- **`mock_hints: none`** → Short-circuit: all tests start as `mock_required: false`. Apply keyword heuristics only as safety net (scan test descriptions for obvious mock signals like "error", "loading", "empty").
+
+- **`mock_hints` with content** → Parse and match tests against hints:
+  - Test relates to a `transient_states` entry → `mock_type: "transient_state"`, `mock_reason: "[from hint]"`
+  - Test relates to an `external_data` entry → `mock_type: "external_data"`, `needs_user_confirmation: true`
+  - Test doesn't match any hint → apply keyword heuristics below
+
+**Tier 2: Inline classification (fallback for legacy summaries)**
+
+When no `mock_hints` key found in any SUMMARY.md (legacy summaries written before executor populated this field):
+
+Classify in main context using the two-question framework:
+
+1. **Is the observable state transient?** — Does it appear briefly during async operations? (loading skeleton, spinner, transition animation). If YES → `mock_type: "transient_state"`
+
+2. **Does the test depend on external data?** — Does the feature fetch from an API, database, or external service? Would the test fail without specific data existing? If YES → `mock_type: "external_data"`, `needs_user_confirmation: true`
+
+Reason over SUMMARY.md content (accomplishments, files created/modified, decisions) to answer these questions. Supplement with keyword heuristics:
 
 | Expected behavior contains | Likely mock_type |
 |---------------------------|------------------|
-| "error", "fails", "invalid" | error_state |
+| "error", "fails", "invalid", "retry" | error_state |
 | "premium", "pro", "paid", "subscription" | premium_user |
 | "empty", "no results", "placeholder" | empty_response |
-| "loading", "spinner", "skeleton" | loading_state |
+| "loading", "spinner", "skeleton" | transient_state |
 | "offline", "no connection" | offline_state |
 | Normal happy path | no mock needed |
 
-**Dependency inference:**
+For tests that remain genuinely uncertain after both the two-question framework and keyword heuristics, present them via AskUserQuestion grouped by uncertainty:
+```
+questions:
+  - question: "Does [test name] require mock data or a special app state to test?"
+    header: "Mock needed?"
+    options:
+      - label: "No mock needed"
+        description: "Can test with real/local data"
+      - label: "Needs mock"
+        description: "Requires simulated state or data"
+```
+
+**Dependency inference (both tiers):**
 - "Reply to comment" depends on "View comments"
 - "Delete account" depends on "Login"
 - Tests mentioning prior state depend on tests that create that state
@@ -173,12 +211,21 @@ tests:
   - name: "Login error message"
     mock_required: true
     mock_type: "error_state"
+    mock_reason: "error response from auth endpoint"
     dependencies: ["login_flow"]
 
-  - name: "Premium badge display"
+  - name: "Recipe list loading skeleton"
     mock_required: true
-    mock_type: "premium_user"
-    dependencies: ["login_flow"]
+    mock_type: "transient_state"
+    mock_reason: "loading skeleton during recipe fetch — async, resolves in <1s"
+    dependencies: []
+
+  - name: "View recipe list"
+    mock_required: true
+    mock_type: "external_data"
+    mock_reason: "recipe items from /api/recipes"
+    needs_user_confirmation: true
+    dependencies: []
 ```
 </step>
 
@@ -189,10 +236,33 @@ tests:
 
 **Rules:**
 1. Group by mock_type (tests needing same mock state go together)
-2. Respect dependencies (if B depends on A, A must be in same or earlier batch)
-3. Max 4 tests per batch (AskUserQuestion limit)
-4. No-mock tests first (run before any mock setup)
-5. Order mock states logically: success → error → empty → loading
+2. **User confirmation for external_data tests:** Before batching, collect all tests with `needs_user_confirmation: true`, grouped by data source. Present via AskUserQuestion:
+
+```
+questions:
+  - question: "Do you have [data_type] data from [source] locally?"
+    header: "[data_type]"
+    options:
+      - label: "Yes, data exists"
+        description: "I have [data_type] in my local environment"
+      - label: "No, needs mock"
+        description: "I need this data mocked for testing"
+      - label: "Skip these tests"
+        description: "Log as assumptions and move on"
+    multiSelect: false
+```
+
+Handle responses:
+- "Yes, data exists" → reclassify affected tests as `mock_required: false`
+- "No, needs mock" → keep as `mock_required: true`, `mock_type: "external_data"`
+- "Skip these tests" → mark all affected tests as `skipped`
+
+Group by data source (not per-test) to stay within AskUserQuestion's 4-question limit.
+
+3. **Separate transient_state batch:** Transient states use a different mock strategy (delay/force) than data mocks. Give them their own batch.
+4. Respect dependencies (if B depends on A, A must be in same or earlier batch)
+5. Max 4 tests per batch (AskUserQuestion limit)
+6. Batch ordering: no-mock → external_data → error_state → empty_response → transient_state → premium_user → offline_state
 
 **Batch structure:**
 ```yaml
@@ -203,14 +273,24 @@ batches:
     tests: [1, 2, 3]
 
   - batch: 2
+    name: "External Data"
+    mock_type: "external_data"
+    tests: [4, 5]
+
+  - batch: 3
     name: "Error States"
     mock_type: "error_state"
-    tests: [4, 5, 6, 7]
+    tests: [6, 7, 8]
 
-  - batch: 3
+  - batch: 4
+    name: "Transient States"
+    mock_type: "transient_state"
+    tests: [9, 10]
+
+  - batch: 5
     name: "Premium Features"
     mock_type: "premium_user"
-    tests: [8, 9, 10]
+    tests: [11, 12]
 ```
 </step>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindsystem-cc",
-  "version": "3.10.0",
+  "version": "3.11.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/compare_mockups.py

@@ -0,0 +1,219 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# ///
+"""Combine variant-*.html mockup files into a single side-by-side comparison page."""
+
+import re
+import sys
+from pathlib import Path
+
+
+def extract_title(html: str) -> str:
+    """Extract the content of the <title> tag from an HTML string."""
+    match = re.search(r"<title>(.*?)</title>", html, re.IGNORECASE)
+    return match.group(1) if match else "Untitled"
+
+
+def is_device_mockup(html: str) -> bool:
+    """Detect if the HTML is a phone-frame mockup (has a fixed-size .device element)."""
+    return bool(re.search(r"\.device\s*\{", html))
+
+
+def build_device_html(panels: list[tuple[str, str]]) -> str:
+    """Side-by-side layout for phone-frame mockups."""
+    panels_html = ""
+    for label, filename in panels:
+        panels_html += f"""
+      <div class="panel">
+        <h2>{label}</h2>
+        <iframe src="{filename}"></iframe>
+      </div>"""
+
+    return f"""\
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<title>Mockup Comparison</title>
+<style>
+  * {{ margin: 0; padding: 0; box-sizing: border-box; }}
+  body {{
+    background: #1a1a1a;
+    color: #fff;
+    font-family: -apple-system, BlinkMacSystemFont, "Helvetica Neue", sans-serif;
+    padding: 24px;
+  }}
+  h1 {{
+    text-align: center;
+    margin-bottom: 24px;
+    font-size: 24px;
+    font-weight: 600;
+  }}
+  .container {{
+    display: flex;
+    justify-content: center;
+    gap: 32px;
+    flex-wrap: wrap;
+  }}
+  .panel {{
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: 12px;
+  }}
+  .panel h2 {{
+    font-size: 16px;
+    font-weight: 500;
+    color: #ccc;
+  }}
+  iframe {{
+    border: none;
+    border-radius: 8px;
+    background: #e5e5e5;
+    width: 450px;
+    height: 920px;
+  }}
+</style>
+</head>
+<body>
+  <h1>Mockup Comparison</h1>
+  <div class="container">{panels_html}
+  </div>
+</body>
+</html>
+"""
+
+
+def build_fluid_html(panels: list[tuple[str, str]]) -> str:
+    """Tabbed layout for full web page mockups."""
+    tabs_html = ""
+    panes_html = ""
+    for i, (label, filename) in enumerate(panels):
+        active = " active" if i == 0 else ""
+        tabs_html += f"""
+        <button class="tab{active}" data-index="{i}">{label}</button>"""
+        panes_html += f"""
+      <iframe class="pane{active}" data-index="{i}" src="{filename}"></iframe>"""
+
+    return f"""\
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<title>Mockup Comparison</title>
+<style>
+  * {{ margin: 0; padding: 0; box-sizing: border-box; }}
+  html, body {{ height: 100%; }}
+  body {{
+    background: #1a1a1a;
+    color: #fff;
+    font-family: -apple-system, BlinkMacSystemFont, "Helvetica Neue", sans-serif;
+    display: flex;
+    flex-direction: column;
+  }}
+  .tab-bar {{
+    display: flex;
+    gap: 4px;
+    padding: 16px 24px 0;
+    flex-shrink: 0;
+  }}
+  .tab {{
+    padding: 10px 24px;
+    border: none;
+    border-radius: 8px 8px 0 0;
+    background: #2a2a2a;
+    color: #888;
+    font-size: 14px;
+    font-weight: 500;
+    font-family: inherit;
+    cursor: pointer;
+    transition: background 0.15s, color 0.15s;
+  }}
+  .tab:hover {{
+    background: #333;
+    color: #bbb;
+  }}
+  .tab.active {{
+    background: #e5e5e5;
+    color: #111;
+  }}
+  .pane-container {{
+    flex: 1;
+    padding: 0 24px 24px;
+    min-height: 0;
+  }}
+  .pane {{
+    display: none;
+    width: 100%;
+    height: 100%;
+    border: none;
+    border-radius: 0 8px 8px 8px;
+    background: #e5e5e5;
+  }}
+  .pane.active {{
+    display: block;
+  }}
+</style>
+</head>
+<body>
+  <div class="tab-bar">{tabs_html}
+  </div>
+  <div class="pane-container">{panes_html}
+  </div>
+  <script>
+    document.querySelectorAll('.tab').forEach(tab => {{
+      tab.addEventListener('click', () => {{
+        const idx = tab.dataset.index;
+        document.querySelectorAll('.tab').forEach(t => t.classList.remove('active'));
+        document.querySelectorAll('.pane').forEach(p => p.classList.remove('active'));
+        tab.classList.add('active');
+        document.querySelector('.pane[data-index="' + idx + '"]').classList.add('active');
+      }});
+    }});
+  </script>
+</body>
+</html>
+"""
+
+
+def main() -> None:
+    if len(sys.argv) > 1:
+        mockups_dir = Path(sys.argv[1])
+    else:
+        mockups_dir = Path.cwd()
+
+    variants = sorted(mockups_dir.glob("variant-*.html"))
+    if not variants:
+        print(f"No variant-*.html files found in {mockups_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"Found {len(variants)} variants: {', '.join(v.name for v in variants)}")
+
+    # Read variants and detect layout mode
+    panels: list[tuple[str, str]] = []
+    all_device = True
+    for path in variants:
+        html = path.read_text()
+        letter = path.stem.split("-")[-1].upper()
+        title = extract_title(html)
+        label = f"Variant {letter}: {title}"
+        if not is_device_mockup(html):
+            all_device = False
+        panels.append((label, path.name))
+
+    mode = "device" if all_device else "fluid"
+    print(f"Layout mode: {mode}")
+
+    if mode == "device":
+        comparison = build_device_html(panels)
+    else:
+        comparison = build_fluid_html(panels)
+
+    output = mockups_dir / "comparison.html"
+    output.write_text(comparison)
+    print(f"Generated: {output}")
+
+
+if __name__ == "__main__":
+    main()

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

@@ -3,7 +3,7 @@ name: flutter-code-quality
 description: Flutter/Dart code quality, widget organization, and folder structure guidelines. Use when reviewing, refactoring, or cleaning up Flutter code after implementation.
 license: MIT
 metadata:
-  author: forgeblast
+  author: Roland Tolnay
   version: "1.0.0"
   date: January 2026
   argument-hint: <file-or-pattern>

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

@@ -3,7 +3,7 @@ name: flutter-code-simplification
 description: Flutter/Dart code simplification principles. Use when simplifying, refactoring, or cleaning up Flutter code for clarity and maintainability.
 license: MIT
 metadata:
-  author: forgeblast
+  author: Roland Tolnay
   version: "1.0.0"
   date: January 2026
   argument-hint: <file-or-pattern>

package/skills/flutter-senior-review/AGENTS.md

@@ -1,7 +1,7 @@
 # Flutter Senior Review
 
 **Version 1.0.0**
-Forgeblast
+Roland Tolnay
 January 2026
 
 > This document is optimized for AI agents and LLMs. Principles are organized by category and prioritized by structural impact.

package/skills/flutter-senior-review/SKILL.md

@@ -3,7 +3,7 @@ name: flutter-senior-review
 description: Senior engineering principles for Flutter/Dart code reviews. Apply when reviewing, refactoring, or writing Flutter code to identify structural improvements that make code evolvable, not just working.
 license: MIT
 metadata:
-  author: forgeblast
+  author: Roland Tolnay
   version: "1.0.0"
   date: January 2026
   abstract: Code review framework focused on structural improvements that typical reviews miss. Uses 3 core lenses (State Modeling, Responsibility Boundaries, Abstraction Timing) backed by 12 detailed principles organized into 4 categories. Each principle includes detection signals, smell examples, senior solutions, and Dart-specific patterns.

package/commands/ms/define-requirements.md

@@ -1,128 +0,0 @@
----
-name: ms:define-requirements
-description: Define what "done" looks like with checkable requirements
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - AskUserQuestion
----
-
-<objective>
-Define concrete, checkable requirements for v1.
-
-Two modes:
-1. **With research** — Transform FEATURES.md into scoped requirements
-2. **Without research** — Gather requirements through questioning
-
-Run before `/ms:create-roadmap`.
-
-Output: `.planning/REQUIREMENTS.md`
-</objective>
-
-<execution_context>
-@~/.claude/mindsystem/references/principles.md
-@~/.claude/mindsystem/workflows/define-requirements.md
-@~/.claude/mindsystem/templates/requirements.md
-</execution_context>
-
-<context>
-@.planning/PROJECT.md
-@.planning/research/FEATURES.md (if exists)
-@.planning/research/SUMMARY.md (if exists)
-</context>
-
-<process>
-
-<step name="validate">
-```bash
-# Verify project exists
-[ -f .planning/PROJECT.md ] || { echo "ERROR: No PROJECT.md found. Run /ms:new-project first."; exit 1; }
-
-# Check for research
-[ -f .planning/research/FEATURES.md ] && echo "HAS_RESEARCH" || echo "NO_RESEARCH"
-
-# Check if requirements already exist
-[ -f .planning/REQUIREMENTS.md ] && echo "REQUIREMENTS_EXISTS" || echo "NO_REQUIREMENTS"
-```
-</step>
-
-<step name="check_existing">
-**If REQUIREMENTS_EXISTS:**
-
-Use AskUserQuestion:
-- header: "Requirements exist"
-- question: "Requirements already defined. What would you like to do?"
-- options:
-  - "View existing" — Show current requirements
-  - "Replace" — Define requirements fresh (will overwrite)
-  - "Cancel" — Keep existing requirements
-
-If "View existing": Read and display `.planning/REQUIREMENTS.md`, then exit
-If "Cancel": Exit
-If "Replace": Continue with workflow
-</step>
-
-<step name="execute">
-**If HAS_RESEARCH:**
-Follow the define-requirements.md workflow:
-- Load research features from FEATURES.md
-- Present features by category
-- Ask user to scope each category (v1 / v2 / out of scope)
-- Capture any additions research missed
-- Generate REQUIREMENTS.md with checkable list
-
-**If NO_RESEARCH:**
-Gather requirements through questioning:
-- Read PROJECT.md for core value and context
-- Ask: "What are the main things users need to be able to do?"
-- For each capability mentioned, probe for specifics
-- Group into categories (Authentication, Content, etc.)
-- For each category, ask what's v1 vs v2 vs out of scope
-- Generate REQUIREMENTS.md with checkable list
-
-Same output format either way — the difference is source (research vs conversation).
-</step>
-
-<step name="done">
-```
-Requirements defined:
-
-- Requirements: .planning/REQUIREMENTS.md
-- v1 scope: [N] requirements across [M] categories
-- v2 scope: [X] requirements deferred
-- Out of scope: [Y] requirements excluded
-
----
-
-## ▶ Next Up
-
-**Create roadmap** — phases mapped to requirements
-
-`/ms:create-roadmap`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-```
-</step>
-
-<step name="update_last_command">
-Update `.planning/STATE.md` Last Command field:
-- Find line starting with `Last Command:` in Current Position section
-- Replace with: `Last Command: ms:define-requirements | YYYY-MM-DD HH:MM`
-- If line doesn't exist, add it after `Status:` line
-</step>
-
-</process>
-
-<success_criteria>
-- [ ] PROJECT.md validated
-- [ ] Features gathered (from research OR questioning)
-- [ ] User scoped each category (v1/v2/out of scope)
-- [ ] User had opportunity to add missing requirements
-- [ ] REQUIREMENTS.md created with checkable list
-- [ ] Requirements committed to git
-- [ ] User knows next step (create-roadmap)
-</success_criteria>