mindsystem-cc 3.12.0 → 3.13.1

package/mindsystem/templates/phase-prompt.md

@@ -1,194 +1,16 @@
 # Phase Prompt Template
 
-Template for `.planning/phases/XX-name/{phase}-{plan}-PLAN.md` - executable phase plans optimized for parallel execution.
+Process guidance for generating PLAN.md files. For format specification,
+read `~/.claude/mindsystem/references/plan-format.md`.
 
-**Naming:** Use `{phase}-{plan}-PLAN.md` format (e.g., `01-02-PLAN.md` for Phase 1, Plan 2)
+**File naming:** `{phase}-{plan}-PLAN.md` (e.g., `01-02-PLAN.md` for Phase 1, Plan 2)
 
 ---
 
-## File Template
+## Expected Outputs
 
-```markdown
----
-phase: XX-name
-plan: NN
-type: execute
-wave: N                     # Execution wave (1, 2, 3...). Pre-computed at plan time.
-depends_on: []              # Plan IDs this plan requires (e.g., ["01-01"]).
-files_modified: []          # Files this plan modifies.
-subsystem_hint: ""          # From planner, for executor SUMMARY.md
-user_setup: []              # Human-required setup Claude cannot automate (see below)
-
-# Goal-backward verification (derived during planning, verified after execution)
-must_haves:
-  truths: []                # Observable behaviors that must be true for goal achievement
-  artifacts: []             # Files that must exist with real implementation
-  key_links: []             # Critical connections between artifacts
----
-
-<objective>
-[What this plan accomplishes]
-
-Purpose: [Why this matters for the project]
-Output: [What artifacts will be created]
-</objective>
-
-<execution_context>
-@~/.claude/mindsystem/workflows/execute-plan.md
-@~/.claude/mindsystem/templates/summary.md
-</execution_context>
-
-<context>
-@.planning/PROJECT.md
-@.planning/ROADMAP.md
-@.planning/STATE.md
-
-# Only reference prior plan SUMMARYs if genuinely needed:
-# - This plan uses types/exports from prior plan
-# - Prior plan made decision that affects this plan
-# Do NOT reflexively chain: Plan 02 refs 01, Plan 03 refs 02...
-
-[Relevant source files:]
-@src/path/to/relevant.ts
-</context>
-
-<tasks>
-
-<task type="auto">
-  <name>Task 1: [Action-oriented name]</name>
-  <files>path/to/file.ext, another/file.ext</files>
-  <action>[Specific implementation - what to do, how to do it, what to avoid and WHY]</action>
-  <verify>[Command or check to prove it worked]</verify>
-  <done>[Measurable acceptance criteria]</done>
-</task>
-
-<task type="auto">
-  <name>Task 2: [Action-oriented name]</name>
-  <files>path/to/file.ext</files>
-  <action>[Specific implementation]</action>
-  <verify>[Command or check]</verify>
-  <done>[Acceptance criteria]</done>
-</task>
-
-</tasks>
-
-<verification>
-Before declaring plan complete:
-- [ ] [Specific test command]
-- [ ] [Build/type check passes]
-- [ ] [Behavior verification]
-</verification>
-
-<success_criteria>
-
-- All tasks completed
-- All verification checks pass
-- No errors or warnings introduced
-- [Plan-specific criteria]
-  </success_criteria>
-
-<output>
-After completion, create `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`
-</output>
-```
-
----
-
-## Frontmatter Fields
-
-| Field | Required | Purpose |
-|-------|----------|---------|
-| `phase` | Yes | Phase identifier (e.g., `01-foundation`) |
-| `plan` | Yes | Plan number within phase (e.g., `01`, `02`) |
-| `type` | Yes | Always `execute` for standard plans, `tdd` for TDD plans |
-| `wave` | Yes | Execution wave number (1, 2, 3...). Pre-computed at plan time. |
-| `depends_on` | Yes | Array of plan IDs this plan requires. |
-| `files_modified` | Yes | Files this plan touches. |
-| `subsystem_hint` | No | Subsystem from config.json, assigned by planner for executor to use in SUMMARY.md |
-| `user_setup` | No | Array of human-required setup items (external services) |
-| `must_haves` | Yes | Goal-backward verification criteria (see below) |
-
-**Wave is pre-computed:** Wave numbers are assigned during `/ms:plan-phase`. Execute-phase reads `wave` directly from frontmatter and groups plans by wave number. No runtime dependency analysis needed.
-
-**Must-haves enable verification:** The `must_haves` field carries goal-backward requirements from planning to execution. After all plans complete, execute-phase spawns a verification subagent that checks these criteria against the actual codebase.
-
----
-
-## Parallel vs Sequential
-
-<parallel_examples>
-
-**Wave 1 candidates (parallel):**
-
-```yaml
-# Plan 01 - User feature
-wave: 1
-depends_on: []
-files_modified: [src/models/user.ts, src/api/users.ts]
-
-# Plan 02 - Product feature (no overlap with Plan 01)
-wave: 1
-depends_on: []
-files_modified: [src/models/product.ts, src/api/products.ts]
-
-# Plan 03 - Order feature (no overlap)
-wave: 1
-depends_on: []
-files_modified: [src/models/order.ts, src/api/orders.ts]
-```
-
-All three run in parallel (Wave 1) - no dependencies, no file conflicts.
-
-**Sequential (genuine dependency):**
-
-```yaml
-# Plan 01 - Auth foundation
-wave: 1
-depends_on: []
-files_modified: [src/lib/auth.ts, src/middleware/auth.ts]
-
-# Plan 02 - Protected features (needs auth)
-wave: 2
-depends_on: ["01"]
-files_modified: [src/features/dashboard.ts]
-```
-
-Plan 02 in Wave 2 waits for Plan 01 in Wave 1 - genuine dependency on auth types/middleware.
-
-
-</parallel_examples>
-
----
-
-## Context Section
-
-**Parallel-aware context:**
-
-```markdown
-<context>
-@.planning/PROJECT.md
-@.planning/ROADMAP.md
-@.planning/STATE.md
-
-# Only include SUMMARY refs if genuinely needed:
-# - This plan imports types from prior plan
-# - Prior plan made decision affecting this plan
-# - Prior plan's output is input to this plan
-#
-# Independent plans need NO prior SUMMARY references.
-# Do NOT reflexively chain: 02 refs 01, 03 refs 02...
-
-@src/relevant/source.ts
-</context>
-```
-
-**Bad pattern (creates false dependencies):**
-```markdown
-<context>
-@.planning/phases/03-features/03-01-SUMMARY.md  # Just because it's earlier
-@.planning/phases/03-features/03-02-SUMMARY.md  # Reflexive chaining
-</context>
-```
+1. **PLAN.md files** — pure markdown following plan-format.md spec
+2. **EXECUTION-ORDER.md** — wave groups for parallel execution
 
 ---
 
@@ -196,16 +18,17 @@ Plan 02 in Wave 2 waits for Plan 01 in Wave 1 - genuine dependency on auth types
 
 **Plan sizing:**
 
-- 2-3 tasks per plan
-- ~50% context usage maximum
+- 2-3 tasks per plan, ~50% context usage maximum
+- Default to 3 tasks for simple-medium work, 2 for complex
+- Executor overhead reduction creates headroom for the third task
 - Complex phases: Multiple focused plans, not one large plan
 
 **When to split:**
 
 - Different subsystems (auth vs API vs UI)
-- >3 tasks
+- More than 3 tasks
 - Risk of context overflow
-- TDD candidates - separate plans
+- TDD candidates — separate plans
 
 **Vertical slices preferred:**
 
@@ -220,15 +43,15 @@ AVOID:  Plan 01 = All models
 
 ---
 
-## TDD Plans
-
-TDD features get dedicated plans with `type: tdd`.
+## TDD Detection
 
 **Heuristic:** Can you write `expect(fn(input)).toBe(output)` before writing `fn`?
-→ Yes: Create a TDD plan
-→ No: Standard task in standard plan
+- Yes: Create a TDD plan with `**Type:** tdd`
+- No: Standard plan (type defaults to execute, omit from metadata line)
+
+TDD features get dedicated plans. One feature per TDD plan.
 
-See `~/.claude/mindsystem/references/tdd.md` for TDD plan structure.
+See `~/.claude/mindsystem/references/tdd.md` for TDD plan structure (RED/GREEN/REFACTOR in ## Changes).
 
 ---
 
@@ -236,81 +59,51 @@ See `~/.claude/mindsystem/references/tdd.md` for TDD plan structure.
 
 | Type | Use For |
 |------|---------|
-| `auto` | Everything Claude can do independently (default) |
+| `execute` | Everything Claude can do independently (default, can be omitted) |
 | `tdd` | TDD features with RED → GREEN → REFACTOR cycle |
 
-**Decisions:** Resolve during planning via AskUserQuestion, not during execution. For purely technical choices, make the decision and document it in the plan's objective.
+**Decisions:** Resolve during planning via AskUserQuestion, not during execution. For purely technical choices, make the decision and document it in the plan's ## Context.
 
 ---
 
-## Examples
+## Learnings Integration
 
-**Autonomous parallel plan:**
+When expanding tasks into plan ## Changes subsections, check provided learnings for entries relevant to each change. Embed as directives within the change description:
 
 ```markdown
----
-phase: 03-features
-plan: 01
-type: execute
-wave: 1
-depends_on: []
-files_modified: [src/features/user/model.ts, src/features/user/api.ts, src/features/user/UserList.tsx]
----
+### 2. Create auth endpoint
+**Files:** `src/api/auth/login.ts`
 
-<objective>
-Implement complete User feature as vertical slice.
-
-Purpose: Self-contained user management that can run parallel to other features.
-Output: User model, API endpoints, and UI components.
-</objective>
-
-<context>
-@.planning/PROJECT.md
-@.planning/ROADMAP.md
-@.planning/STATE.md
-</context>
-
-<tasks>
-<task type="auto">
-  <name>Task 1: Create User model</name>
-  <files>src/features/user/model.ts</files>
-  <action>Define User type with id, email, name, createdAt. Export TypeScript interface.</action>
-  <verify>tsc --noEmit passes</verify>
-  <done>User type exported and usable</done>
-</task>
-
-<task type="auto">
-  <name>Task 2: Create User API endpoints</name>
-  <files>src/features/user/api.ts</files>
-  <action>GET /users (list), GET /users/:id (single), POST /users (create). Use User type from model.</action>
-  <verify>curl tests pass for all endpoints</verify>
-  <done>All CRUD operations work</done>
-</task>
-</tasks>
-
-<verification>
-- [ ] npm run build succeeds
-- [ ] API endpoints respond correctly
-</verification>
-
-<success_criteria>
-- All tasks completed
-- User feature works end-to-end
-</success_criteria>
-
-<output>
-After completion, create `.planning/phases/03-features/03-01-SUMMARY.md`
-</output>
+POST endpoint accepting {email, password}...
+
+**From prior work:** CommonJS libraries fail silently in Edge runtime — verify ESM compat.
 ```
 
+Rules:
+- Maximum 2 learning directives per change (context budget)
+- Only include learnings that change what the executor would do
+- Phrase as imperative directives, not history
+- If no learnings match a change, add nothing
+
+---
+
+## External Services
+
+When a plan introduces external services requiring human configuration, describe them in the plan's ## Context section. The user handles external service setup (account creation, secret retrieval) based on plan context.
+
+**The automation-first rule:** External service notes contain ONLY what Claude literally cannot do:
+- Account creation (requires human signup)
+- Secret retrieval (requires dashboard access)
+- Dashboard configuration (requires human in browser)
+
+**NOT included:** Package installs, code changes, file creation, CLI commands Claude can run.
+
 ---
 
 ## Anti-Patterns
 
 **Bad: Reflexive dependency chaining**
-```yaml
-depends_on: ["03-01"]  # Just because 01 comes before 02
-```
+Plan 02 does not depend on Plan 01 just because 01 comes first. Check actual needs/creates.
 
 **Bad: Horizontal layer grouping**
 ```
@@ -320,121 +113,12 @@ Plan 03: All UIs (depends on 02)
 ```
 
 **Bad: Vague tasks**
-```xml
-<task type="auto">
-  <name>Set up authentication</name>
-  <action>Add auth to the app</action>
-</task>
 ```
-
----
-
-## Guidelines
-
-- Always use XML structure for Claude parsing
-- Include `wave`, `depends_on`, `files_modified` in every plan
-- Prefer vertical slices over horizontal layers
-- Only reference prior SUMMARYs when genuinely needed
-- 2-3 tasks per plan, ~50% context max
-
----
-
-## User Setup (External Services)
-
-When a plan introduces external services requiring human configuration, declare in frontmatter:
-
-```yaml
-user_setup:
-  - service: stripe
-    why: "Payment processing requires API keys"
-    env_vars:
-      - name: STRIPE_SECRET_KEY
-        source: "Stripe Dashboard → Developers → API keys → Secret key"
-      - name: STRIPE_WEBHOOK_SECRET
-        source: "Stripe Dashboard → Developers → Webhooks → Signing secret"
-    dashboard_config:
-      - task: "Create webhook endpoint"
-        location: "Stripe Dashboard → Developers → Webhooks → Add endpoint"
-        details: "URL: https://[your-domain]/api/webhooks/stripe"
-    local_dev:
-      - "stripe listen --forward-to localhost:3000/api/webhooks/stripe"
+### 1. Set up authentication
+Implement auth.
 ```
 
-**The automation-first rule:** `user_setup` contains ONLY what Claude literally cannot do:
-- Account creation (requires human signup)
-- Secret retrieval (requires dashboard access)
-- Dashboard configuration (requires human in browser)
-
-**NOT included:** Package installs, code changes, file creation, CLI commands Claude can run.
-
-**Result:** Execute-plan generates `{phase}-USER-SETUP.md` with checklist for the user.
-
-See `~/.claude/mindsystem/templates/user-setup.md` for full schema and examples
-
----
-
-## Must-Haves (Goal-Backward Verification)
-
-The `must_haves` field defines what must be TRUE for the phase goal to be achieved. Derived during planning, verified after execution.
-
-**Structure:**
-
-```yaml
-must_haves:
-  truths:
-    - "User can see existing messages"
-    - "User can send a message"
-    - "Messages persist across refresh"
-  artifacts:
-    - path: "src/components/Chat.tsx"
-      provides: "Message list rendering"
-      min_lines: 30
-    - path: "src/app/api/chat/route.ts"
-      provides: "Message CRUD operations"
-      exports: ["GET", "POST"]
-    - path: "prisma/schema.prisma"
-      provides: "Message model"
-      contains: "model Message"
-  key_links:
-    - from: "src/components/Chat.tsx"
-      to: "/api/chat"
-      via: "fetch in useEffect"
-      pattern: "fetch.*api/chat"
-    - from: "src/app/api/chat/route.ts"
-      to: "prisma.message"
-      via: "database query"
-      pattern: "prisma\\.message\\.(find|create)"
-```
+Claude: "How? What type? What library? Where?" — plans must be specific enough for immediate implementation.
 
-**Field descriptions:**
-
-| Field | Purpose |
-|-------|---------|
-| `truths` | Observable behaviors from user perspective. Each must be testable. |
-| `artifacts` | Files that must exist with real implementation. |
-| `artifacts[].path` | File path relative to project root. |
-| `artifacts[].provides` | What this artifact delivers. |
-| `artifacts[].min_lines` | Optional. Minimum lines to be considered substantive. |
-| `artifacts[].exports` | Optional. Expected exports to verify. |
-| `artifacts[].contains` | Optional. Pattern that must exist in file. |
-| `key_links` | Critical connections between artifacts. |
-| `key_links[].from` | Source artifact. |
-| `key_links[].to` | Target artifact or endpoint. |
-| `key_links[].via` | How they connect (description). |
-| `key_links[].pattern` | Optional. Regex to verify connection exists. |
-
-**Why this matters:**
-
-Task completion ≠ Goal achievement. A task "create chat component" can complete by creating a placeholder. The `must_haves` field captures what must actually work, enabling verification to catch gaps before they compound.
-
-**Verification flow:**
-
-1. Plan-phase derives must_haves from phase goal (goal-backward)
-2. Must_haves written to PLAN.md frontmatter
-3. Execute-phase runs all plans
-4. Verification subagent checks must_haves against codebase
-5. Gaps found → fix plans created → execute → re-verify
-6. All must_haves pass → phase complete
-
-See `~/.claude/mindsystem/references/goal-backward.md` for derivation process.
-See `~/.claude/mindsystem/workflows/verify-phase.md` for verification logic.
+**Bad: Unnecessary SUMMARY references**
+Independent plans need NO prior SUMMARY references. Only reference prior SUMMARYs if genuinely importing types/exports from them.

package/mindsystem/templates/roadmap.md

@@ -132,7 +132,7 @@ Phases execute in numeric order: 2 → 2.1 → 2.2 → 3 → 3.1 → 4
 **Success criteria:**
 - 2-5 observable behaviors per phase (from user's perspective)
 - Cross-checked against requirements during roadmap creation
-- Flow downstream to `must_haves` in plan-phase
+- Flow downstream to `## Must-Haves` in plan-phase
 - Verified by verify-phase after execution
 - Format: "User can [action]" or "[Thing] works/exists"
 

package/mindsystem/templates/verification-report.md

@@ -147,7 +147,7 @@ None — all verifiable items checked programmatically.
 ## Verification Metadata
 
 **Verification approach:** Goal-backward (derived from phase goal)
-**Must-haves source:** {PLAN.md frontmatter | derived from ROADMAP.md goal}
+**Must-haves source:** {PLAN.md ## Must-Haves section | derived from ROADMAP.md goal}
 **Automated checks:** {N} passed, {M} failed
 **Human checks required:** {N}
 **Total verification time:** {duration}
@@ -311,7 +311,7 @@ None needed until automated gaps are fixed.
 ## Verification Metadata
 
 **Verification approach:** Goal-backward (derived from phase goal)
-**Must-haves source:** 03-01-PLAN.md frontmatter
+**Must-haves source:** 03-01-PLAN.md ## Must-Haves section
 **Automated checks:** 2 passed, 8 failed
 **Human checks required:** 0 (blocked by automated failures)
 **Total verification time:** 2 min

package/mindsystem/workflows/adhoc.md

@@ -132,33 +132,28 @@ plan_file=".planning/adhoc/${timestamp}-${slug}-PLAN.md"
 Create minimal PLAN.md:
 
 ```markdown
----
-type: adhoc
-description: [user description]
-created: [ISO timestamp]
-related_phase: [current phase from STATE.md, or "none"]
----
+# Adhoc: [User's description]
 
-<objective>
-[User's description of what needs to be done]
-</objective>
+**Subsystem:** [subsystem or "general"] | **Type:** execute
 
-<tasks>
+## Context
+[User's description of what needs to be done and why]
 
-<task type="auto">
-  <name>Task 1: [Action-oriented name]</name>
-  <files>[file paths]</files>
-  <action>[What to do, what to avoid and WHY]</action>
-  <verify>[Command or check to prove completion]</verify>
-</task>
+## Changes
 
-[Task 2 if needed, same structure]
+### 1. [Action-oriented name]
+**Files:** `[file paths]`
 
-</tasks>
+[What to do, what to avoid and WHY]
+
+[### 2. if needed, same structure]
+
+## Verification
+- [How to verify the work is complete]
 
-<verification>
-[How to verify the work is complete]
-</verification>
+## Must-Haves
+- [ ] [Observable outcome 1]
+- [ ] [Observable outcome 2]
 ```
 
 Write to file: