mindsystem-cc 3.19.0 → 3.21.0

package/mindsystem/workflows/plan-phase.md

@@ -277,7 +277,7 @@ PHASE_NAME=$(grep -A2 "Phase ${PHASE}:" .planning/ROADMAP.md 2>/dev/null | head
 **2. Run context scanner:**
 
 ```bash
-uv run ~/.claude/mindsystem/scripts/scan-planning-context.py \
+ms-tools scan-planning-context \
   --phase "${PHASE}" \
   --phase-name "${PHASE_NAME}" \
   ${SUBSYSTEM:+--subsystem="${SUBSYSTEM}"}
@@ -389,7 +389,9 @@ Standard tasks (remain in standard plans):
 → Yes: Mark as tdd_candidate=true
 → No: Standard task
 
-Read `~/.claude/mindsystem/references/tdd.md` now for TDD criteria and plan structure.
+**If any tasks were marked tdd_candidate=true:** Read `~/.claude/mindsystem/references/tdd.md` for TDD plan structure guidance.
+
+**If no TDD candidates:** Skip — the heuristic above is sufficient for detection.
 
 **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.
 
@@ -450,6 +452,25 @@ The user may adjust, merge, or split plans. Once confirmed (or if the user proce
 **TDD plans are always standalone** — propose them as dedicated plans regardless of budget.
 </step>
 
+<step name="discover_skills">
+**Identify relevant project skills for this phase.**
+
+After the user confirms the plan structure, check if project skills could improve plan quality.
+
+**Scan:** Review the skill list in your system-reminder. Match skills against:
+- The phase's technology stack (Flutter, React, Node.js, etc.)
+- The domain of the tasks identified (UI patterns, API design, state management, etc.)
+- Keywords from RESEARCH.md or CONTEXT.md if they exist
+
+**If matches found:** Present via AskUserQuestion:
+- List each matching skill with its description
+- Always include an escape hatch option for the user to name skills manually or skip entirely
+
+**If no matches:** Skip silently — no need to ask the user.
+
+**Store result:** Keep the confirmed skill names (may be empty) for the handoff step.
+</step>
+
 <step name="handoff_to_writer">
 **Spawn ms-plan-writer subagent with task list and context.**
 
@@ -500,6 +521,10 @@ Assemble handoff payload:
   {list of services detected in task breakdown}
 </external_services>
 
+<confirmed_skills>
+  {comma-separated skill names confirmed by user, or "none"}
+</confirmed_skills>
+
 <learnings>
   <!-- Flat list from read_project_history step 6. Omit if no matches found. -->
   <learning type="debug" source=".planning/debug/resolved/{slug}.md">{root_cause} — fix: {resolution}</learning>
@@ -699,7 +724,7 @@ Tasks are instructions for Claude, not Jira tickets.
 - [ ] Prior decisions, issues, concerns synthesized
 - [ ] Tasks identified with needs/creates dependencies
 - [ ] Plan grouping proposed and presented to user
-- [ ] Task list + proposed grouping handed off to ms-plan-writer
+- [ ] Task list + proposed grouping + confirmed skills handed off to ms-plan-writer
 - [ ] PLAN files + EXECUTION-ORDER.md created (pure markdown, Must-Haves, follows proposed grouping)
 - [ ] Plans committed with maximized wave parallelism
 - [ ] Risk assessment presented (score + top factors)

package/mindsystem/workflows/transition.md

@@ -141,16 +141,17 @@ cat .planning/phases/XX-current/*-SUMMARY.md
 **Assess requirement changes:**
 
 1. **Requirements validated?**
-   - Any Active requirements shipped in this phase?
-   - Move to Validated with phase reference: `- ✓ [Requirement] — Phase X`
+   - Any requirements shipped in this phase?
+   - Add to Validated with phase reference: `- ✓ [Requirement] — Phase X`
 
 2. **Requirements invalidated?**
-   - Any Active requirements discovered to be unnecessary or wrong?
-   - Move to Out of Scope with reason: `- [Requirement] — [why invalidated]`
+   - Any requirements discovered to be unnecessary or wrong?
+   - Add to Out of Scope with reason: `- [Requirement] — [why invalidated]`
 
-3. **Requirements emerged?**
-   - Any new requirements discovered during building?
-   - Add to Active: `- [ ] [New requirement]`
+3. **Business context evolved?**
+   - Has understanding of audience, problem, or differentiation changed?
+   - Update Who It's For, Core Problem, or How It's Different if so
+   - New key flows emerged? → Update Key User Flows
 
 4. **Decisions to log?**
    - Extract decisions from SUMMARY.md files
@@ -174,13 +175,11 @@ Make the edits inline. Update "Last updated" footer:
 Before:
 
 ```markdown
-### Active
+## Validated
 
-- [ ] JWT authentication
-- [ ] Real-time sync < 500ms
-- [ ] Offline mode
+- ✓ Canvas drawing tools — Phase 1
 
-### Out of Scope
+## Out of Scope
 
 - OAuth2 — complexity not needed for v1
 ```
@@ -188,27 +187,23 @@ Before:
 After (Phase 2 shipped JWT auth, discovered rate limiting needed):
 
 ```markdown
-### Validated
+## Validated
 
+- ✓ Canvas drawing tools — Phase 1
 - ✓ JWT authentication — Phase 2
 
-### Active
-
-- [ ] Real-time sync < 500ms
-- [ ] Offline mode
-- [ ] Rate limiting on sync endpoint
-
-### Out of Scope
+## Out of Scope
 
 - OAuth2 — complexity not needed for v1
+- Offline mode — real-time is core value, discovered Phase 2
 ```
 
 **Step complete when:**
 
 - [ ] Phase summaries reviewed for learnings
-- [ ] Validated requirements moved from Active
-- [ ] Invalidated requirements moved to Out of Scope with reason
-- [ ] Emerged requirements added to Active
+- [ ] Shipped requirements added to Validated
+- [ ] Invalidated requirements added to Out of Scope with reason
+- [ ] Business context sections reviewed (Who It's For, Core Problem, How It's Different, Key User Flows)
 - [ ] New decisions logged with rationale
 - [ ] "What This Is" updated if product changed
 - [ ] "Last updated" footer reflects this transition
@@ -405,12 +400,12 @@ Exit skill and invoke SlashCommand("/ms:plan-phase [X+1]")
 ```
 Phase {X} marked complete.
 
-🎉 Milestone {version} is 100% complete — all {N} phases finished!
+🎉 Milestone is 100% complete — all {N} phases finished!
 
 ⚡ Auto-continuing: Complete milestone and archive
 ```
 
-Exit skill and invoke SlashCommand("/ms:complete-milestone {version}")
+Exit skill and invoke SlashCommand("/ms:complete-milestone")
 
 </step>
 

package/mindsystem/workflows/verify-work.md

@@ -580,7 +580,7 @@ Use `mocked_files` list from UAT.md frontmatter. Clear the list after reverting.
 
 **2. Generate UAT fixes patch (if fixes were made):**
 ```bash
-~/.claude/mindsystem/scripts/generate-phase-patch.sh ${PHASE_NUMBER} --suffix=uat-fixes
+ms-tools generate-phase-patch ${PHASE_NUMBER} --suffix=uat-fixes
 ```
 Output: `.planning/phases/{phase_dir}/{phase}-uat-fixes.patch`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindsystem-cc",
-  "version": "3.19.0",
+  "version": "3.21.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/fixtures/scan-context/.planning/ROADMAP.md

@@ -0,0 +1,16 @@
+# Roadmap
+
+## Phase 02: Infrastructure
+Database setup and core infrastructure.
+
+## Phase 03: Core Models
+Data models and schemas.
+
+## Phase 04: Setup
+Project configuration and tooling.
+
+## Phase 05: Authentication
+User auth with JWT tokens.
+
+## Phase 06: UI
+Frontend components and screens.

package/scripts/fixtures/scan-context/.planning/adhoc/20260220-fix-token-SUMMARY.md

@@ -0,0 +1,12 @@
+---
+subsystem: auth
+learnings:
+  - Token expiry must account for clock skew
+  - Always validate token signature before checking claims
+related_phase: "05-auth"
+tags: [jwt, tokens]
+---
+
+# Fix Token Validation
+
+Fixed edge case where expired tokens passed validation due to clock skew.

package/scripts/fixtures/scan-context/.planning/config.json

@@ -0,0 +1,3 @@
+{
+  "subsystems": ["auth", "database", "api"]
+}

package/scripts/fixtures/scan-context/.planning/debug/resolved/token-bug.md

@@ -0,0 +1,11 @@
+---
+subsystem: auth
+root_cause: Clock skew between servers caused token validation to fail intermittently
+resolution: Added 30-second leeway to token expiry check
+tags: [jwt, timing]
+phase: "05-auth"
+---
+
+# Token Validation Bug
+
+Intermittent auth failures due to clock skew between API servers.

package/scripts/fixtures/scan-context/.planning/knowledge/auth.md

@@ -0,0 +1,11 @@
+# Auth Subsystem Knowledge
+
+## Authentication Flow
+1. User submits credentials to POST /api/auth/login
+2. Server validates with bcrypt
+3. JWT issued as httpOnly cookie
+4. Middleware validates on subsequent requests
+
+## Key Patterns
+- Token rotation on refresh
+- Clock skew leeway of 30 seconds

package/scripts/fixtures/scan-context/.planning/phases/02-infra/02-1-SUMMARY.md

@@ -0,0 +1,20 @@
+---
+phase: "02-infra"
+subsystem: database
+affects: []
+requires: []
+tags: [postgres, migrations]
+tech-stack:
+  added: [postgres]
+  patterns: []
+patterns-established: []
+key-files:
+  created: [db/schema.sql]
+  modified: []
+key-decisions:
+  - Use PostgreSQL for primary store
+---
+
+# Phase 02 Plan 1 Summary
+
+Set up database infrastructure with migrations.

package/scripts/fixtures/scan-context/.planning/phases/04-setup/04-1-SUMMARY.md

@@ -0,0 +1,21 @@
+---
+phase: "04-setup"
+subsystem: api
+affects: []
+requires: []
+tags: [jwt, config]
+tech-stack:
+  added: [dotenv]
+  patterns: [env-config]
+patterns-established:
+  - Config loading pattern
+key-files:
+  created: [src/config.ts]
+  modified: [package.json]
+key-decisions:
+  - Use dotenv for configuration
+---
+
+# Phase 04 Plan 1 Summary
+
+Project setup and configuration with JWT support.

package/scripts/fixtures/scan-context/.planning/phases/05-auth/05-1-SUMMARY.md

@@ -0,0 +1,28 @@
+---
+phase: "05-auth"
+subsystem: auth
+affects: ["06-ui"]
+requires: ["04-setup"]
+tags: [jwt, auth, tokens]
+tech-stack:
+  added: [jose, bcrypt]
+  patterns: [jwt-auth]
+patterns-established:
+  - JWT token rotation
+  - Password hashing with bcrypt
+key-files:
+  created: [src/auth/login.ts, src/auth/middleware.ts]
+  modified: [src/config.ts]
+key-decisions:
+  - JWT with httpOnly cookies
+  - bcrypt for password hashing
+---
+
+# Phase 05 Plan 1 Summary
+
+Authentication system with JWT and bcrypt.
+
+## Next Phase Readiness
+
+- UI phase needs auth context provider
+- Token refresh endpoint not yet implemented

package/scripts/fixtures/scan-context/.planning/todos/done/setup-db.md

@@ -0,0 +1,10 @@
+---
+title: Set up database migrations
+subsystem: database
+priority: high
+phase_origin: "02-infra"
+---
+
+# Set Up Database Migrations
+
+Configure migration tooling for PostgreSQL.

package/scripts/fixtures/scan-context/.planning/todos/pending/add-logout.md

@@ -0,0 +1,10 @@
+---
+title: Add logout endpoint
+subsystem: auth
+priority: medium
+phase_origin: "05-auth"
+---
+
+# Add Logout Endpoint
+
+Implement POST /api/auth/logout to invalidate tokens.

package/scripts/fixtures/scan-context/expected-output.json

@@ -0,0 +1,257 @@
+{
+  "success": true,
+  "target": {
+    "phase": "06",
+    "phase_name": "",
+    "subsystems": [
+      "auth"
+    ],
+    "keywords": [
+      "jwt",
+      "ui"
+    ]
+  },
+  "sources": {
+    "summaries": {
+      "dir": "<FIXTURE>/.planning/phases",
+      "scanned": 3,
+      "skipped": null
+    },
+    "debug_docs": {
+      "dir": "<FIXTURE>/.planning/debug/resolved",
+      "scanned": 1,
+      "skipped": null
+    },
+    "adhoc_summaries": {
+      "dir": "<FIXTURE>/.planning/adhoc",
+      "scanned": 1,
+      "skipped": null
+    },
+    "completed_todos": {
+      "dir": "<FIXTURE>/.planning/todos/done",
+      "scanned": 1,
+      "skipped": null
+    },
+    "pending_todos": {
+      "dir": "<FIXTURE>/.planning/todos/pending",
+      "scanned": 1,
+      "skipped": null
+    },
+    "knowledge_files": {
+      "dir": "<FIXTURE>/.planning/knowledge",
+      "scanned": 1,
+      "skipped": null
+    },
+    "parse_errors": []
+  },
+  "summaries": [
+    {
+      "path": "<FIXTURE>/.planning/phases/02-infra/02-1-SUMMARY.md",
+      "frontmatter": {
+        "phase": "02-infra",
+        "subsystem": "database",
+        "affects": [],
+        "requires": [],
+        "tags": [
+          "postgres",
+          "migrations"
+        ],
+        "tech-stack": {
+          "added": [
+            "postgres"
+          ],
+          "patterns": []
+        },
+        "patterns-established": [],
+        "key-files": {
+          "created": [
+            "db/schema.sql"
+          ],
+          "modified": []
+        },
+        "key-decisions": [
+          "Use PostgreSQL for primary store"
+        ]
+      },
+      "relevance": "LOW",
+      "match_reasons": [],
+      "has_readiness_warnings": false
+    },
+    {
+      "path": "<FIXTURE>/.planning/phases/04-setup/04-1-SUMMARY.md",
+      "frontmatter": {
+        "phase": "04-setup",
+        "subsystem": "api",
+        "affects": [],
+        "requires": [],
+        "tags": [
+          "jwt",
+          "config"
+        ],
+        "tech-stack": {
+          "added": [
+            "dotenv"
+          ],
+          "patterns": [
+            "env-config"
+          ]
+        },
+        "patterns-established": [
+          "Config loading pattern"
+        ],
+        "key-files": {
+          "created": [
+            "src/config.ts"
+          ],
+          "modified": [
+            "package.json"
+          ]
+        },
+        "key-decisions": [
+          "Use dotenv for configuration"
+        ]
+      },
+      "relevance": "HIGH",
+      "match_reasons": [
+        "overlapping tags: ['jwt']",
+        "adjacent phase (N-2)",
+        "in transitive requires chain"
+      ],
+      "has_readiness_warnings": false
+    },
+    {
+      "path": "<FIXTURE>/.planning/phases/05-auth/05-1-SUMMARY.md",
+      "frontmatter": {
+        "phase": "05-auth",
+        "subsystem": "auth",
+        "affects": [
+          "06-ui"
+        ],
+        "requires": [
+          "04-setup"
+        ],
+        "tags": [
+          "jwt",
+          "auth",
+          "tokens"
+        ],
+        "tech-stack": {
+          "added": [
+            "jose",
+            "bcrypt"
+          ],
+          "patterns": [
+            "jwt-auth"
+          ]
+        },
+        "patterns-established": [
+          "JWT token rotation",
+          "Password hashing with bcrypt"
+        ],
+        "key-files": {
+          "created": [
+            "src/auth/login.ts",
+            "src/auth/middleware.ts"
+          ],
+          "modified": [
+            "src/config.ts"
+          ]
+        },
+        "key-decisions": [
+          "JWT with httpOnly cookies",
+          "bcrypt for password hashing"
+        ]
+      },
+      "relevance": "HIGH",
+      "match_reasons": [
+        "affects contains '06'",
+        "same subsystem 'auth'",
+        "overlapping tags: ['jwt']",
+        "adjacent phase (N-1)"
+      ],
+      "has_readiness_warnings": true
+    }
+  ],
+  "debug_learnings": [
+    {
+      "path": "<FIXTURE>/.planning/debug/resolved/token-bug.md",
+      "slug": "token-bug",
+      "subsystem": "auth",
+      "root_cause": "Clock skew between servers caused token validation to fail intermittently",
+      "resolution": "Added 30-second leeway to token expiry check",
+      "tags": [
+        "jwt",
+        "timing"
+      ],
+      "phase": "05-auth"
+    }
+  ],
+  "adhoc_learnings": [
+    {
+      "path": "<FIXTURE>/.planning/adhoc/20260220-fix-token-SUMMARY.md",
+      "subsystem": "auth",
+      "learnings": [
+        "Token expiry must account for clock skew",
+        "Always validate token signature before checking claims"
+      ],
+      "related_phase": "05-auth",
+      "tags": [
+        "jwt",
+        "tokens"
+      ]
+    }
+  ],
+  "completed_todos": [
+    {
+      "path": "<FIXTURE>/.planning/todos/done/setup-db.md",
+      "title": "Set up database migrations",
+      "subsystem": "database",
+      "priority": "high",
+      "phase_origin": "02-infra"
+    }
+  ],
+  "pending_todos": [
+    {
+      "path": "<FIXTURE>/.planning/todos/pending/add-logout.md",
+      "title": "Add logout endpoint",
+      "subsystem": "auth",
+      "priority": "medium",
+      "phase_origin": "05-auth"
+    }
+  ],
+  "knowledge_files": [
+    {
+      "path": "<FIXTURE>/.planning/knowledge/auth.md",
+      "subsystem": "auth",
+      "matched": true
+    }
+  ],
+  "aggregated": {
+    "tech_stack_added": [
+      "bcrypt",
+      "dotenv",
+      "jose"
+    ],
+    "patterns_established": [
+      "Config loading pattern",
+      "JWT token rotation",
+      "Password hashing with bcrypt",
+      "env-config",
+      "jwt-auth"
+    ],
+    "key_files_created": [
+      "src/auth/login.ts",
+      "src/auth/middleware.ts",
+      "src/config.ts"
+    ],
+    "key_files_modified": [
+      "package.json",
+      "src/config.ts"
+    ],
+    "key_decisions": [
+      "Use dotenv for configuration",
+      "JWT with httpOnly cookies",
+      "bcrypt for password hashing"
+    ]
+  }
+}