mindsystem-cc 4.0.2 → 4.0.3

package/README.md

@@ -19,7 +19,7 @@ npx mindsystem-cc
 
 <br>
 
-[How it works](#how-it-works) · [Walkthrough](#end-to-end-walkthrough) · [Features](#features) · [Quick start](#quick-start) · [Config](#configuration) · [Commands](#command-reference) · [Troubleshooting](#troubleshooting)
+[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>
 
@@ -282,6 +282,103 @@ Codebase mapping produces 7 documents covering your stack, conventions, and arch
 
 ---
 
+## The .planning directory
+
+Every artifact Mindsystem generates lives in `.planning/` — a markdown knowledge base that grows with your project. Commands read from it, execution enriches it, and it all survives `/clear` boundaries and context resets. Here's what a project looks like after a couple of milestones:
+
+```
+.planning/
+├── PROJECT.md                        # Living spec — vision, users, flows, decisions
+├── MILESTONES.md                     # Registry of completed milestones
+│
+├── STATE.md                          # Active phase, blockers, recent decisions
+├── MILESTONE-CONTEXT.md              # new-milestone → brainstorm that grounds the roadmap
+├── ROADMAP.md                        # Phase breakdown with goals and success criteria
+├── REQUIREMENTS.md                   # Checkable REQ-IDs mapped to phases
+│
+├── TECH-DEBT.md                      # Prioritized debt — TD-IDs, severity tiers
+├── config.json                       # Subsystems, code review tiers, preferences
+│
+├── knowledge/                        # Persists across milestones
+│   ├── auth.md                       # Patterns, decisions, pitfalls per subsystem
+│   ├── api.md                        # Enriched after every execute and verify cycle
+│   └── ui.md                         # Future phases load relevant files automatically
+│
+├── codebase/                         # /ms:map-codebase → existing repo analysis
+│   ├── STACK.md                      # Runtime, frameworks, key dependencies
+│   ├── ARCHITECTURE.md               # Modules, layers, data flow patterns
+│   ├── STRUCTURE.md                  # Directory layout and file organization
+│   ├── CONVENTIONS.md                # Naming, style, established patterns
+│   ├── TESTING.md                    # Test framework, coverage, how to add tests
+│   ├── INTEGRATIONS.md               # External services and API connections
+│   └── CONCERNS.md                   # Known issues, areas requiring care
+│
+├── phases/                           # Active milestone work
+│   │
+│   ├── 01-auth-foundation/           # ── Fully executed phase ──
+│   │   ├── CONTEXT.md                # discuss-phase → locked intent and decisions
+│   │   ├── DESIGN.md                 # design-phase → exact tokens, layout, interactions
+│   │   ├── RESEARCH.md               # research-phase → library picks, patterns, tradeoffs
+│   │   ├── 01-01-PLAN.md             # plan-phase → executable prompt, one per budget slice
+│   │   ├── 01-02-PLAN.md             #
+│   │   ├── EXECUTION-ORDER.md        # plan-phase → wave grouping and dependencies
+│   │   ├── 01-01-SUMMARY.md          # execute-phase → what changed, patterns, learnings
+│   │   ├── 01-02-SUMMARY.md          #
+│   │   ├── VERIFICATION.md           # execute-phase → goal-backward pass/fail
+│   │   ├── UAT.md                    # verify-work → manual acceptance test results
+│   │   ├── 01-changes.patch          # execute-phase → diff of all code changes
+│   │   ├── 01-uat-fixes.patch        # verify-work → diff of fixes applied during testing
+│   │   └── mockups/                  # design-phase → HTML/CSS design exploration
+│   │       ├── variant-a.html        #   self-contained mockup
+│   │       ├── variant-b.html        #   self-contained mockup
+│   │       └── comparison.html       #   side-by-side view, opens in browser
+│   │
+│   └── 02-payment-flow/              # ── Phase in progress ──
+│       ├── CONTEXT.md                #   discussed, not yet planned
+│       └── 02-01-PLAN.md             #   planned, not yet executed
+│
+├── research/                         # /ms:research-project → domain ecosystem
+│   ├── STACK.md                      # Technology recommendations for this domain
+│   ├── ARCHITECTURE.md               # Common system structure patterns
+│   ├── FEATURES.md                   # Feature landscape in this domain
+│   ├── PITFALLS.md                   # Mistakes to avoid
+│   └── SUMMARY.md                    # Synthesized findings with roadmap implications
+│
+├── adhoc/                            # /ms:adhoc → out-of-pipeline work
+│   └── 2026-01-15-fix-token/
+│       ├── adhoc-01-SUMMARY.md       # Execution results and learnings
+│       └── adhoc-01-changes.patch    # Code diff
+│
+├── debug/                            # /ms:debug → structured investigations
+│   ├── websocket-reconnect.md        # Active investigation — survives /clear
+│   └── resolved/
+│       └── race-condition-login.md   # Root cause found, fix documented
+│
+├── todos/                            # /ms:add-todo → captured work items
+│   ├── 2026-02-01-rate-limiting.md   # Pending — priority, estimate, subsystem
+│   └── done/
+│       └── 2026-01-20-header-fix.md  # Completed via /ms:adhoc
+│
+└── milestones/                       # /ms:complete-milestone → archived history
+    └── mvp/
+        ├── ROADMAP.md                # Historical phase breakdown
+        ├── REQUIREMENTS.md           # Final requirement status
+        ├── PHASE-SUMMARIES.md        # Consolidated execution summaries
+        ├── MILESTONE-AUDIT.md        # Requirements coverage, integration check
+        ├── CONTEXT.md                # Original milestone brainstorm
+        ├── research/                 # Archived domain research
+        │   └── ...
+        └── phases/                   # Archived phase artifacts
+            └── 01-foundation/
+                ├── 01-changes.patch  #   code diffs retained
+                └── mockups/          #   design mockups retained
+                    └── ...
+```
+
+Everything is plain markdown (plus `config.json` and `.patch` diffs). The entire directory is greppable, diffable, and readable by any team member or AI assistant. Phase 1 starts from scratch. Phase 10 starts with everything the project has learned.
+
+---
+
 ## Configuration
 
 Mindsystem stores project config in `.planning/config.json`. Run `/ms:config` to change these interactively.

package/agents/ms-codebase-researcher.md

@@ -37,19 +37,15 @@ Grep/Glob for imports, class names, and file patterns related to the research qu
 
 Read `.planning/codebase/*.md` if they exist (from `/ms:map-codebase`). Extract relevant conventions, stack info, architecture patterns.
 
-## 4. Learnings
-
-Grep `.planning/LEARNINGS.md` for entries matching phase keywords, subsystem, or tech terms. Extract matched entries verbatim.
-
-## 5. Prior Phase Summaries
+## 4. Prior Phase Summaries
 
 Scan `.planning/phases/*/SUMMARY.md` frontmatter only (first 25 lines) for `tech-stack`, `patterns-established`, `key-decisions` matching the phase domain. Read full summary only for direct matches.
 
-## 6. Debug Resolutions
+## 5. Debug Resolutions
 
 Scan `.planning/debug/resolved/*.md` for root causes related to the phase domain.
 
-## 7. Adhoc Summaries
+## 6. Adhoc Summaries
 
 Scan `.planning/adhoc/*-SUMMARY.md` learnings arrays for relevant entries.
 
@@ -71,7 +67,7 @@ Return as text (not file). Orchestrator reads this for synthesis.
 [Pattern name, files, description — how the project already handles similar work]
 
 ### Relevant Learnings
-[Verbatim entries from LEARNINGS.md, debug resolutions, summary deviations that match]
+[Debug resolutions, adhoc learnings, summary deviations that match]
 
 ### Reusable Components
 [Existing code that could be extended or reused for this phase]
@@ -99,7 +95,7 @@ Return as text (not file). Orchestrator reads this for synthesis.
 - [ ] All findings include file:line references
 - [ ] Empty sections explicitly noted
 - [ ] Structured output returned (not written to file)
-- [ ] Learnings scanned for relevant entries
+- [ ] Debug resolutions and adhoc summaries scanned for relevant entries
 - [ ] Prior summaries checked (frontmatter only)
 - [ ] Debug resolutions checked
 </success_criteria>

package/package.json

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