mindsystem-cc 4.1.0 → 4.1.1

package/README.md

@@ -2,9 +2,9 @@
 
 # MINDSYSTEM
 
-**A meta-prompting and context engineering system for Claude Code.**
+**The engineer's meta-prompting system for Claude Code.**
 
-Every piece of work makes the next one better. Mindsystem structures your Claude Code sessions into plannable, executable, verifiable phases, and compounds what it learns into persistent knowledge files that survive `/clear`. Context rot stops being the bottleneck. Every prompt in the system is tested against research on how LLMs actually follow instructions, so quality stays consistent from phase 1 to phase 20.
+Amplifies every step of the development workflow you already follow — discovery, research, design, planning, execution, verification. Each one refined, parallelized, and compounded into persistent knowledge. Built for engineers who want to multiply their output without giving up control.
 
 ```bash
 npx mindsystem-cc
@@ -19,12 +19,32 @@ npx mindsystem-cc
 
 <br>
 
-[How it works](#how-it-works) · [Walkthrough](#end-to-end-walkthrough) · [Features](#features) · [Quick start](#quick-start) · [.planning](#the-planning-directory) · [Config](#configuration) · [Commands](#command-reference) · [Troubleshooting](#troubleshooting)
+[Why Mindsystem](#why-mindsystem) · [How it works](#how-it-works) · [Walkthrough](#end-to-end-walkthrough) · [Features](#features) · [Quick start](#quick-start) · [.planning](#the-planning-directory) · [Config](#configuration) · [Commands](#command-reference) · [Troubleshooting](#troubleshooting)
 
 </div>
 
 ---
 
+## Why Mindsystem
+
+Fully autonomous coding tools take a spec and run for hours until a product emerges. That works for prototypes and one-shot projects.
+
+Mindsystem takes the opposite approach. It follows the same workflow a thorough engineer already uses — and amplifies each step:
+
+| What you'd do manually | What Mindsystem does |
+|---|---|
+| Talk through requirements, catch misalignment early | **Discuss phase** surfaces assumptions with confidence levels, forces tradeoff decisions before any code gets written |
+| Google libraries, read a few docs | **Research phase** runs 3 parallel agents across documentation, your codebase, and community practices — 10x more sources, synthesized in minutes |
+| Try design directions, pick the best one | **Design phase** generates parallel HTML/CSS mockups with side-by-side comparison and exact design tokens |
+| Plan from what you remember about the codebase | **Plan phase** loads knowledge files capturing every decision, pattern, and pitfall from prior phases |
+| Figure out what states to test, mock them manually | **Verify work** determines mock states automatically — you validate visually or programmatically |
+
+The workflow stays yours. Each step finishes in minutes instead of hours. Everything learned compounds into knowledge that survives context resets — phase 10 starts with everything the project learned from phases 1–9.
+
+This is not an autopilot. It's a force multiplier.
+
+---
+
 ## How it works
 
 ```
@@ -75,6 +95,12 @@ Execution happens in fresh subagent contexts, so each plan gets up to 200k token
 
 ## End-to-end walkthrough
 
+### Project setup
+
+Before building features, initialize the project once with `/ms:new-project`. For existing codebases, also run `/ms:map-codebase` (analyzes your stack, conventions, and architecture into 7 structured documents) and `/ms:doctor` (validates config and generates per-subsystem knowledge files from source code). See [Quick start](#quick-start) for the exact sequences.
+
+Everything below is the feature-building loop, identical for new and existing projects.
+
 ### 1. New milestone
 
 ```
@@ -274,31 +300,37 @@ Requirements you want but haven't shipped yet are tracked in `PROJECT.md` with o
 
 ## Quick start
 
-### New project
+### Project setup (one-time)
+
+**New project:**
 
 ```
 /ms:new-project
-/ms:new-milestone
-/ms:create-roadmap
-/ms:plan-phase 1
-/ms:execute-phase 1
-/ms:verify-work 1
 ```
 
-You'll get `.planning/` with your project vision, milestone context, requirements, roadmap, and the first phase implemented with commits, patch files, and knowledge files.
+**Existing codebase:**
+
+```
+/ms:new-project                 # Business context and vision
+/ms:map-codebase                # Analyze code → 7 structured documents
+/ms:doctor                      # Validate config, generate knowledge files
+```
+
+Optional: `/ms:config` — configure code reviewers, gitignore, and other preferences.
 
-### Existing project
+### Building features
+
+Once the project is set up, the workflow is the same for new and existing codebases:
 
 ```
-/ms:new-project
-/ms:map-codebase
-/ms:new-milestone
-/ms:create-roadmap
-/ms:plan-phase 1
-/ms:execute-phase 1
+/ms:new-milestone               # Discover what to build next
+/ms:create-roadmap              # Define requirements, map to phases
+/ms:plan-phase 1                # Create detailed plan
+/ms:execute-phase 1             # Run in fresh subagents
+/ms:verify-work 1               # Manual acceptance testing
 ```
 
-Codebase mapping produces 7 documents covering your stack, conventions, and architecture. Then you define what to build, and all downstream planning respects what's already there.
+Repeat for each milestone. All downstream planning automatically loads codebase docs and knowledge files.
 
 **Returning after a break?** Run `/ms:progress` to see where you left off and what to do next.
 
@@ -315,6 +347,7 @@ Every artifact Mindsystem generates lives in `.planning/` — a markdown knowled
 │
 ├── STATE.md                          # Active phase, blockers, recent decisions
 ├── MILESTONE-CONTEXT.md              # new-milestone → brainstorm that grounds the roadmap
+├── MILESTONE-RESEARCH.md             # research-milestone → domain research before roadmapping
 ├── ROADMAP.md                        # Phase breakdown with goals and success criteria
 ├── REQUIREMENTS.md                   # Checkable REQ-IDs mapped to phases
 │
@@ -359,9 +392,6 @@ Every artifact Mindsystem generates lives in `.planning/` — a markdown knowled
 │       ├── CONTEXT.md                #   discussed, not yet planned
 │       └── 02-01-PLAN.md             #   planned, not yet executed
 │
-├── MILESTONE-RESEARCH.md              # /ms:research-milestone → domain ecosystem
-│                                      #   Technology, product landscape, architecture, risks
-│
 ├── adhoc/                            # /ms:adhoc → out-of-pipeline work
 │   └── 2026-01-15-fix-token/
 │       ├── adhoc-01-SUMMARY.md       # Execution results and learnings
@@ -523,4 +553,4 @@ MIT License. See [LICENSE](LICENSE) for details.
 
 ---
 
-Inspired by [GSD](https://github.com/gsd-build/get-shit-done) and [Compound Engineering](https://github.com/EveryInc/compound-engineering-plugin).
+Originally rooted in [GSD](https://github.com/gsd-build/get-shit-done), now an independent system with its own philosophy. Knowledge compounding inspired by [Compound Engineering](https://github.com/EveryInc/compound-engineering-plugin).

package/bin/install.js

@@ -471,8 +471,8 @@ function ensurePathHook(claudeDir, isGlobal, configDir) {
   });
 
   fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
-  if (removed > 0) {
-    console.log(`  ${green}✓${reset} Configured PATH hook (cleaned ${removed} duplicate(s))`);
+  if (removed > 1) {
+    console.log(`  ${green}✓${reset} Configured PATH hook (cleaned ${removed - 1} duplicate(s))`);
   } else {
     console.log(`  ${green}✓${reset} Configured PATH hook`);
   }

package/commands/ms/create-roadmap.md

@@ -300,25 +300,9 @@ Requirements and roadmap created:
 - Roadmap: .planning/ROADMAP.md
 - State: .planning/STATE.md
 - [X] v1 requirements, [M] phases defined
-
----
-
-## ▶ Next Up
-
-**Phase 1: [Name]** — [Goal from ROADMAP.md]
-
-`/ms:plan-phase 1`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-
-**Also available:**
-- `/ms:discuss-phase 1` — gather context first
-- `/ms:research-phase 1` — investigate unknowns
-
----
 ```
+
+Read `~/.claude/mindsystem/references/routing/next-phase-routing.md` and follow its instructions to present "Next Up" with pre-work context for Phase $START_PHASE.
 </step>
 
 <step name="update_last_command">

package/commands/ms/help.md

@@ -26,21 +26,29 @@ Output ONLY the reference content below. Do NOT add:
 
 ## Quick Start
 
-### Greenfield (new project)
+### Project setup (one-time)
+
+**New project:**
 
 1. `/ms:new-project` — Initialize project with brief
-2. `/ms:config` — (optional) Configure code reviewers and gitignore
-3. `/ms:research-milestone` — (optional) Research domain ecosystem
-4. `/ms:create-roadmap` — Define requirements and create roadmap
-5. `/ms:plan-phase 1` — Create detailed plan for first phase
-6. `/ms:execute-phase 1` — Execute with parallel agents
 
-### Brownfield (existing codebase)
+**Existing codebase:**
 
 1. `/ms:new-project` — Questions focus on business context and vision
-2. `/ms:map-codebase` — Analyze existing code
-3. `/ms:config` — (optional) Configure code reviewers and gitignore
-4. Continue with research/roadmap/plan/execute
+2. `/ms:map-codebase` — Analyze existing code for patterns and conventions
+3. `/ms:doctor` — Validate config and generate knowledge files from source code
+
+Optional: `/ms:config` — Configure code reviewers, gitignore, and other preferences
+
+### Building features (repeat per milestone)
+
+1. `/ms:new-milestone` — Discover what to build next
+2. `/ms:research-milestone` — Research domain ecosystem (recommended)
+3. `/ms:create-roadmap` — Define requirements and create roadmap
+4. `/ms:discuss-phase 1` — Gather context before planning (recommended)
+5. `/ms:plan-phase 1` — Create detailed plan for first phase
+6. `/ms:execute-phase 1` — Execute with parallel agents
+7. `/ms:verify-work 1` — (optional) Manual acceptance testing
 
 ## Staying Updated
 
@@ -56,14 +64,14 @@ Release notes: `/ms:release-notes`
 ## Core Workflow
 
 ```
-Initialize → (Optional Research) → Roadmap → Plan → Execute → Verify → Milestone
+Initialize → Research → Roadmap → Discuss → Plan → Execute → Verify → Milestone
 ```
 
 Common deviations:
 - Existing repo: `/ms:map-codebase` after `/ms:new-project` (or before — either works)
-- Plan looks wrong: `/ms:discuss-phase <phase>`
-- Unknown domain: `/ms:research-milestone` before roadmap, or `/ms:research-phase <phase>` before planning
-- Phase prep: `/ms:discuss-phase` → `/ms:design-phase` → `/ms:research-phase` → `/ms:plan-phase` (all optional before plan)
+- Skip research-milestone: domain is familiar, no external APIs or new patterns
+- Skip discuss-phase: purely mechanical work (config-only, rename-only, version bump)
+- Phase prep: `/ms:discuss-phase` → `/ms:design-phase` → `/ms:research-phase` → `/ms:plan-phase` (discuss recommended, others when flagged)
 - New urgent work: `/ms:insert-phase <after> "<desc>"`
 - New non-urgent work: `/ms:add-todo "<desc>"`
 
@@ -455,27 +463,32 @@ Usage: `/ms:release-notes`
 
 ## Common Workflows
 
-**Starting a new project (greenfield):**
+**Project setup — new project:**
 
 ```
 /ms:new-project                 # Extract your idea through questions
-/ms:config                      # (optional) Configure code reviewers and gitignore
-/ms:research-milestone            # (recommended) Research domain ecosystem
-/ms:create-roadmap              # Define requirements and create phases
-/ms:plan-phase 1                # Create detailed plan
-/ms:execute-phase 1             # Execute with parallel agents
 ```
 
-**Starting with existing code (brownfield):**
+**Project setup — existing codebase:**
 
 ```
-/ms:new-project                 # Step 1: Questions focus on business context and vision
-/ms:map-codebase                # Step 2: Analyze existing code
-/ms:config                      # (optional) Configure code reviewers and gitignore
-/ms:research-milestone            # (optional) Research new domain areas
-/ms:create-roadmap              # Define requirements and create roadmap
-/ms:plan-phase 1                # Codebase docs load automatically
-/ms:execute-phase 1             # Claude knows your patterns & conventions
+/ms:new-project                 # Business context and vision
+/ms:map-codebase                # Analyze code → 7 structured documents
+/ms:doctor                      # Validate config, generate knowledge files
+```
+
+Optional: `/ms:config` — configure code reviewers, gitignore, and other preferences
+
+**Building features (repeat per milestone):**
+
+```
+/ms:new-milestone               # Discover what to build next
+/ms:research-milestone          # Research domain ecosystem (recommended)
+/ms:create-roadmap              # Define requirements and create phases
+/ms:discuss-phase 1             # Gather context before planning (recommended)
+/ms:plan-phase 1                # Create detailed plan
+/ms:execute-phase 1             # Execute with parallel agents
+/ms:verify-work 1               # (optional) Manual acceptance testing
 ```
 
 **Not sure what to do next / returning after a break:**
@@ -526,8 +539,9 @@ Common options:
 
 ```
 /ms:new-milestone                     # Discover what to build, update PROJECT.md
-/ms:research-milestone                  # (optional) Domain / stack research
+/ms:research-milestone                # Research domain ecosystem (recommended)
 /ms:create-roadmap                    # New phases mapped to requirements
+/ms:discuss-phase <phase>             # Gather context before planning (recommended)
 /ms:plan-phase                        # Auto-detect next unplanned phase
 /ms:execute-phase <phase>
 ```

package/commands/ms/map-codebase.md

@@ -59,7 +59,7 @@ Check for .planning/STATE.md - loads context if project already initialized
 4. Wait for agents to complete, collect confirmations (NOT document contents)
 5. Verify all 7 documents exist with line counts
 6. Commit codebase map
-7. Offer next steps (typically: /ms:new-project or /ms:plan-phase)
+7. Offer next steps (adapts: /ms:new-project if no PROJECT.md, /ms:doctor if PROJECT.md exists)
 8. **Update last command:** `ms-tools set-last-command "ms:map-codebase $ARGUMENTS"`
 </process>
 

package/commands/ms/new-milestone.md

@@ -278,7 +278,7 @@ Milestone name: $ARGUMENTS (optional — will emerge during discovery if not pro
 
 19. **Route to next step:**
 
-    Based on the conversation, recommend ONE path. If unfamiliar domains or open questions surfaced during discovery, recommend `/ms:research-milestone`. Otherwise recommend `/ms:create-roadmap`.
+    Default to `/ms:research-milestone` — domain research improves roadmap quality for most milestones. Only recommend `/ms:create-roadmap` directly when the domain is clearly familiar, no open questions surfaced, and there are no external APIs, new libraries, or unfamiliar patterns involved.
 
     ```
     Milestone [Name] initialized.
@@ -311,5 +311,5 @@ Milestone name: $ARGUMENTS (optional — will emerge during discovery if not pro
 - MILESTONE-CONTEXT.md created with vision, features, scope, priorities
 - STATE.md reset for new milestone
 - Git commit made
-- User routed to create-roadmap (or research-milestone if unknowns surfaced)
+- User routed to research-milestone (or create-roadmap if domain is clearly familiar)
 </success_criteria>

package/commands/ms/new-project.md

@@ -242,13 +242,16 @@ Project updated:
 - Config: .planning/config.json
 ```
 
-**Routing (both modes):**
+**Routing:**
 
 ```
 ---
 
 ## ▶ Next Up
 
+[If brownfield detected and no codebase map:]
+`/ms:map-codebase` — Analyze existing codebase for technical context
+[Otherwise:]
 `/ms:new-milestone` — Discover what to build first, create requirements and roadmap
 
 <sub>`/clear` first → fresh context window</sub>
@@ -257,7 +260,8 @@ Project updated:
 
 **Also available:**
 - `/ms:config` — Configure code reviewers, gitignore, and other preferences
-[If brownfield detected and no codebase map:] - `/ms:map-codebase` — Analyze existing codebase for technical context
+- `/ms:doctor` — Health check and fix project configuration
+[If brownfield detected and no codebase map:] - `/ms:new-milestone` — Discover what to build first, create requirements and roadmap
 
 ---
 ```

package/mindsystem/workflows/doctor-fixes.md

@@ -239,14 +239,63 @@ EOF
 <step name="fix_knowledge">
 **Only if Knowledge Files failed.**
 
-Spawn a `general-purpose` subagent (Task tool) to generate knowledge files retroactively. Provide the subagent with:
+### 1. Detect knowledge source
 
-- Subsystem vocabulary from config.json
-- Instructions to read all PHASE-SUMMARIES.md from `milestones/*/PHASE-SUMMARIES.md` AND any remaining SUMMARY files in `phases/`
-- The knowledge template at `~/.claude/mindsystem/templates/knowledge.md`
-- Instructions to read any existing knowledge files and merge (rewrite semantics — current state, not append)
-- Instructions to create `.planning/knowledge/` directory if missing
-- Instructions to write `.planning/knowledge/{subsystem}.md` for each missing subsystem
+Run in main context before spawning agent:
+
+```bash
+SUMMARIES=$(ls .planning/milestones/*/PHASE-SUMMARIES.md .planning/phases/*/*-SUMMARY.md 2>/dev/null | wc -l | tr -d ' ')
+HAS_CODEBASE_DOCS=$([ -d .planning/codebase ] && echo "yes" || echo "no")
+HAS_PROJECT=$([ -f .planning/PROJECT.md ] && echo "yes" || echo "no")
+```
+
+If `SUMMARIES > 0`: **artifact mode**. If `SUMMARIES == 0`: **source code mode**.
+
+### 2. Spawn subagent
+
+Spawn a `general-purpose` subagent (Task tool) with the following structured prompt. Inject detected mode, subsystem list from config.json, and environment flags into the prompt.
+
+---
+
+**Prompt content for subagent:**
+
+> **Task:** Generate `.planning/knowledge/{subsystem}.md` for each subsystem listed below.
+>
+> **Subsystems:** {inject list from config.json}
+>
+> **Knowledge template:** Read `~/.claude/mindsystem/templates/knowledge.md` for format reference.
+>
+> **Mode: {artifact | source code}**
+>
+> **If artifact mode:** Read all PHASE-SUMMARIES.md from `milestones/*/PHASE-SUMMARIES.md` and any remaining `*-SUMMARY.md` in `phases/`. {If HAS_CODEBASE_DOCS=yes: "Also read `.planning/codebase/ARCHITECTURE.md`, `STACK.md`, `STRUCTURE.md` for structural context."} {If HAS_PROJECT=yes: "Read `.planning/PROJECT.md` for product context."}
+>
+> **If source code mode:** No pipeline artifacts exist. {If HAS_CODEBASE_DOCS=yes: "Read `.planning/codebase/ARCHITECTURE.md`, `STACK.md`, `STRUCTURE.md` first for orientation, then dive into source code per subsystem."} {If HAS_CODEBASE_DOCS=no: "Explore from package manifests (package.json, pubspec.yaml, Cargo.toml, etc.) and directory structure to understand the codebase, then analyze source code per subsystem."} {If HAS_PROJECT=yes: "Read `.planning/PROJECT.md` for product context."}
+>
+> **Extraction guide — what to extract per subsystem:**
+>
+> | Source Signal | Target Knowledge Section |
+> |--------------|------------------------|
+> | Library/framework choices, version constraints | Decisions |
+> | Component structure, data flow, API contracts | Architecture |
+> | UI patterns, design tokens, interaction behaviors | Design |
+> | Error handling patterns, edge cases, workarounds | Pitfalls |
+> | Main modules, entry points, config files | Key Files |
+>
+> **Critical rules:**
+> - Extract knowledge, not descriptions. "Has login endpoint" is a description. "POST /auth/login with bcrypt + JWT httpOnly cookie" is architecture knowledge.
+> - Preserve rationale when visible in code comments or config. Do not fabricate reasons.
+> - Do not fabricate specific numbers (limits, thresholds, counts) — read from source or omit.
+> - Omit empty sections. No Design section if subsystem has no UI.
+> - Rewrite semantics — if existing knowledge files exist, merge by producing current state.
+> - Cross-reference between subsystems where relevant: "(see api subsystem)".
+> - Decisions table: 5-10 words per cell. Source column: `"existing"` for source code mode, artifact reference for artifact mode.
+> - Key files must reference actual paths verified to exist.
+> - `mkdir -p .planning/knowledge/` before writing.
+> - No commits.
+
+---
+
+### 3. Verify and commit
 
 After subagent completes, verify files exist:
 
@@ -254,7 +303,7 @@ After subagent completes, verify files exist:
 ls .planning/knowledge/*.md
 ```
 
-Commit:
+Commit (use detected mode in message):
 
 ```bash
 git add .planning/knowledge/
@@ -264,10 +313,12 @@ git add .planning/knowledge/
 git commit -m "$(cat <<'EOF'
 chore(doctor): generate knowledge files
 
-Created per-subsystem knowledge files from phase summaries.
+Created per-subsystem knowledge files from {phase summaries|source code analysis}.
 EOF
 )"
 ```
+
+Replace `{phase summaries|source code analysis}` with the appropriate phrase based on detected mode.
 </step>
 
 </process>

package/mindsystem/workflows/map-codebase.md

@@ -246,6 +246,11 @@ Present completion summary and next steps.
 wc -l .planning/codebase/*.md
 ```
 
+**Detect project state:**
+```bash
+[ -f .planning/PROJECT.md ] && echo "HAS_PROJECT=true" || echo "HAS_PROJECT=false"
+```
+
 **Output format:**
 
 ```
@@ -259,22 +264,40 @@ Created .planning/codebase/:
 - TESTING.md ([N] lines) - Test structure and practices
 - INTEGRATIONS.md ([N] lines) - External services and APIs
 - CONCERNS.md ([N] lines) - Technical debt and issues
+```
+
+**Routing (based on project state):**
+
+**If HAS_PROJECT=false** (map-codebase ran before new-project):
+
+```
+---
 
+## ▶ Next Up
+
+`/ms:new-project` — initialize project with business context (codebase docs load automatically)
 
+<sub>`/clear` first → fresh context window</sub>
+
+---
+```
+
+**If HAS_PROJECT=true** (map-codebase ran after new-project):
+
+```
 ---
 
 ## ▶ Next Up
 
-`/ms:new-project` — use codebase context for planning
+`/ms:doctor` — validate project configuration and generate knowledge files
 
 <sub>`/clear` first → fresh context window</sub>
 
 ---
 
 **Also available:**
-- Re-run mapping: `/ms:map-codebase`
-- Review specific file: `cat .planning/codebase/STACK.md`
-- Edit any document before proceeding
+- `/ms:config` — configure code reviewers, gitignore, and other preferences
+- `/ms:new-milestone` — skip doctor, go straight to defining what to build
 
 ---
 ```

package/package.json

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