mindsystem-cc 3.0.0

package/mindsystem/templates/roadmap.md

@@ -0,0 +1,214 @@
+# Roadmap Template
+
+Template for `.planning/ROADMAP.md`.
+
+## Initial Roadmap (v1.0 Greenfield)
+
+```markdown
+# Roadmap: [Project Name]
+
+## Overview
+
+[One paragraph describing the journey from start to finish]
+
+## Phases
+
+**Phase Numbering:**
+- Integer phases (1, 2, 3): Planned milestone work
+- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
+
+Decimal phases appear between their surrounding integers in numeric order.
+
+- [ ] **Phase 1: [Name]** - [One-line description]
+- [ ] **Phase 2: [Name]** - [One-line description]
+- [ ] **Phase 3: [Name]** - [One-line description]
+- [ ] **Phase 4: [Name]** - [One-line description]
+
+## Phase Details
+
+### Phase 1: [Name]
+**Goal**: [What this phase delivers]
+**Depends on**: Nothing (first phase)
+**Requirements**: [REQ-01, REQ-02, REQ-03]
+**Success Criteria** (what must be TRUE):
+  1. [Observable behavior from user perspective]
+  2. [Observable behavior from user perspective]
+  3. [Observable behavior from user perspective]
+**Research**: Unlikely (established patterns)
+**Plans**: [Number of plans, e.g., "3 plans" or "TBD"]
+
+Plans:
+- [ ] 01-01: [Brief description of first plan]
+- [ ] 01-02: [Brief description of second plan]
+- [ ] 01-03: [Brief description of third plan]
+
+### Phase 2: [Name]
+**Goal**: [What this phase delivers]
+**Depends on**: Phase 1
+**Requirements**: [REQ-04, REQ-05]
+**Success Criteria** (what must be TRUE):
+  1. [Observable behavior from user perspective]
+  2. [Observable behavior from user perspective]
+**Research**: Likely (new integration)
+**Research topics**: [What needs investigating]
+**Plans**: [Number of plans]
+
+Plans:
+- [ ] 02-01: [Brief description]
+- [ ] 02-02: [Brief description]
+
+### Phase 2.1: Critical Fix (INSERTED)
+**Goal**: [Urgent work inserted between phases]
+**Depends on**: Phase 2
+**Success Criteria** (what must be TRUE):
+  1. [What the fix achieves]
+**Plans**: 1 plan
+
+Plans:
+- [ ] 02.1-01: [Description]
+
+### Phase 3: [Name]
+**Goal**: [What this phase delivers]
+**Depends on**: Phase 2
+**Requirements**: [REQ-06, REQ-07, REQ-08]
+**Success Criteria** (what must be TRUE):
+  1. [Observable behavior from user perspective]
+  2. [Observable behavior from user perspective]
+  3. [Observable behavior from user perspective]
+**Research**: Likely (external API)
+**Research topics**: [What needs investigating]
+**Plans**: [Number of plans]
+
+Plans:
+- [ ] 03-01: [Brief description]
+- [ ] 03-02: [Brief description]
+
+### Phase 4: [Name]
+**Goal**: [What this phase delivers]
+**Depends on**: Phase 3
+**Requirements**: [REQ-09, REQ-10]
+**Success Criteria** (what must be TRUE):
+  1. [Observable behavior from user perspective]
+  2. [Observable behavior from user perspective]
+**Research**: Unlikely (internal patterns)
+**Plans**: [Number of plans]
+
+Plans:
+- [ ] 04-01: [Brief description]
+
+## Progress
+
+**Execution Order:**
+Phases execute in numeric order: 2 → 2.1 → 2.2 → 3 → 3.1 → 4
+
+| Phase | Plans Complete | Status | Completed |
+|-------|----------------|--------|-----------|
+| 1. [Name] | 0/3 | Not started | - |
+| 2. [Name] | 0/2 | Not started | - |
+| 3. [Name] | 0/2 | Not started | - |
+| 4. [Name] | 0/1 | Not started | - |
+```
+
+<guidelines>
+**Initial planning (v1.0):**
+- Phase count depends on depth setting (quick: 3-5, standard: 5-8, comprehensive: 8-12)
+- Each phase delivers something coherent
+- Phases can have 1+ plans (split if >3 tasks or multiple subsystems)
+- Plans use naming: {phase}-{plan}-PLAN.md (e.g., 01-02-PLAN.md)
+- No time estimates (this isn't enterprise PM)
+- Progress table updated by execute workflow
+- Plan count can be "TBD" initially, refined during planning
+
+**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
+- Verified by verify-phase after execution
+- Format: "User can [action]" or "[Thing] works/exists"
+
+**Research flags:**
+- `Research: Likely` - External APIs, new libraries, architectural decisions
+- `Research: Unlikely` - Internal patterns, CRUD operations, established conventions
+- Include `Research topics:` when Likely
+- Flags are hints, not mandates - validate at planning time
+
+**After milestones ship:**
+- Collapse completed milestones in `<details>` tags
+- Add new milestone sections for upcoming work
+- Keep continuous phase numbering (never restart at 01)
+</guidelines>
+
+<status_values>
+- `Not started` - Haven't begun
+- `In progress` - Currently working
+- `Complete` - Done (add completion date)
+- `Deferred` - Pushed to later (with reason)
+</status_values>
+
+## Milestone-Grouped Roadmap (After v1.0 Ships)
+
+After completing first milestone, reorganize with milestone groupings:
+
+```markdown
+# Roadmap: [Project Name]
+
+## Milestones
+
+- ✅ **v1.0 MVP** - Phases 1-4 (shipped YYYY-MM-DD)
+- 🚧 **v1.1 [Name]** - Phases 5-6 (in progress)
+- 📋 **v2.0 [Name]** - Phases 7-10 (planned)
+
+## Phases
+
+<details>
+<summary>✅ v1.0 MVP (Phases 1-4) - SHIPPED YYYY-MM-DD</summary>
+
+### Phase 1: [Name]
+**Goal**: [What this phase delivers]
+**Plans**: 3 plans
+
+Plans:
+- [x] 01-01: [Brief description]
+- [x] 01-02: [Brief description]
+- [x] 01-03: [Brief description]
+
+[... remaining v1.0 phases ...]
+
+</details>
+
+### 🚧 v1.1 [Name] (In Progress)
+
+**Milestone Goal:** [What v1.1 delivers]
+
+#### Phase 5: [Name]
+**Goal**: [What this phase delivers]
+**Depends on**: Phase 4
+**Plans**: 2 plans
+
+Plans:
+- [ ] 05-01: [Brief description]
+- [ ] 05-02: [Brief description]
+
+[... remaining v1.1 phases ...]
+
+### 📋 v2.0 [Name] (Planned)
+
+**Milestone Goal:** [What v2.0 delivers]
+
+[... v2.0 phases ...]
+
+## Progress
+
+| Phase | Milestone | Plans Complete | Status | Completed |
+|-------|-----------|----------------|--------|-----------|
+| 1. Foundation | v1.0 | 3/3 | Complete | YYYY-MM-DD |
+| 2. Features | v1.0 | 2/2 | Complete | YYYY-MM-DD |
+| 5. Security | v1.1 | 0/2 | Not started | - |
+```
+
+**Notes:**
+- Milestone emoji: ✅ shipped, 🚧 in progress, 📋 planned
+- Completed milestones collapsed in `<details>` for readability
+- Current/future milestones expanded
+- Continuous phase numbering (01-99)
+- Progress table includes milestone column

package/mindsystem/templates/state.md

@@ -0,0 +1,224 @@
+# State Template
+
+Template for `.planning/STATE.md` — the project's living memory.
+
+---
+
+## File Template
+
+```markdown
+# Project State
+
+## Project Reference
+
+See: .planning/PROJECT.md (updated [date])
+
+**Core value:** [One-liner from PROJECT.md Core Value section]
+**Current focus:** [Current phase name]
+
+## Current Position
+
+Phase: [X] of [Y] ([Phase name])
+Plan: [A] of [B] in current phase
+Status: [Ready to plan / Planning / Ready to execute / In progress / Phase complete]
+Last activity: [YYYY-MM-DD] — [What happened]
+
+Progress: [░░░░░░░░░░] 0%
+
+## Performance Metrics
+
+**Velocity:**
+- Total plans completed: [N]
+- Average duration: [X] min
+- Total execution time: [X.X] hours
+
+**By Phase:**
+
+| Phase | Plans | Total | Avg/Plan |
+|-------|-------|-------|----------|
+| - | - | - | - |
+
+**Recent Trend:**
+- Last 5 plans: [durations]
+- Trend: [Improving / Stable / Degrading]
+
+*Updated after each plan completion*
+
+## Accumulated Context
+
+### Decisions
+
+Decisions are logged in PROJECT.md Key Decisions table.
+Recent decisions affecting current work:
+
+- [Phase X]: [Decision summary]
+- [Phase Y]: [Decision summary]
+
+### Pending Todos
+
+[From .planning/todos/pending/ — ideas captured during sessions]
+
+None yet.
+
+### Recent Adhoc Work
+
+[Small work items executed via /ms:do-work]
+
+None yet.
+
+*See `.planning/adhoc/` for full history*
+
+### Blockers/Concerns
+
+[Issues that affect future work]
+
+None yet.
+
+## Session Continuity
+
+Last session: [YYYY-MM-DD HH:MM]
+Stopped at: [Description of last completed action]
+Resume file: [Path to .continue-here*.md if exists, otherwise "None"]
+```
+
+<purpose>
+
+STATE.md is the project's short-term memory spanning all phases and sessions.
+
+**Problem it solves:** Information is captured in summaries, issues, and decisions but not systematically consumed. Sessions start without context.
+
+**Solution:** A single, small file that's:
+- Read first in every workflow
+- Updated after every significant action
+- Contains digest of accumulated context
+- Enables instant session restoration
+
+</purpose>
+
+<lifecycle>
+
+**Creation:** After ROADMAP.md is created (during init)
+- Reference PROJECT.md (read it for current context)
+- Initialize empty accumulated context sections
+- Set position to "Phase 1 ready to plan"
+
+**Reading:** First step of every workflow
+- progress: Present status to user
+- plan: Inform planning decisions
+- execute: Know current position
+- transition: Know what's complete
+
+**Writing:** After every significant action
+- execute: After SUMMARY.md created
+  - Update position (phase, plan, status)
+  - Note new decisions (detail in PROJECT.md)
+  - Add blockers/concerns
+- transition: After phase marked complete
+  - Update progress bar
+  - Clear resolved blockers
+  - Refresh Project Reference date
+- do-work: After adhoc work completed
+  - Add entry to "Recent Adhoc Work" section
+  - Keep last 5 entries (older entries remain in .planning/adhoc/)
+
+</lifecycle>
+
+<sections>
+
+### Project Reference
+Points to PROJECT.md for full context. Includes:
+- Core value (the ONE thing that matters)
+- Current focus (which phase)
+- Last update date (triggers re-read if stale)
+
+Claude reads PROJECT.md directly for requirements, constraints, and decisions.
+
+### Current Position
+Where we are right now:
+- Phase X of Y — which phase
+- Plan A of B — which plan within phase
+- Status — current state
+- Last activity — what happened most recently
+- Progress bar — visual indicator of overall completion
+
+Progress calculation: (completed plans) / (total plans across all phases) × 100%
+
+### Performance Metrics
+Track velocity to understand execution patterns:
+- Total plans completed
+- Average duration per plan
+- Per-phase breakdown
+- Recent trend (improving/stable/degrading)
+
+Updated after each plan completion.
+
+### Accumulated Context
+
+**Decisions:** Reference to PROJECT.md Key Decisions table, plus recent decisions summary for quick access. Full decision log lives in PROJECT.md.
+
+**Pending Todos:** Ideas captured via /ms:add-todo
+- Count of pending todos
+- Reference to .planning/todos/pending/
+- Brief list if few, count if many (e.g., "5 pending todos — see /ms:check-todos")
+
+**Recent Adhoc Work:** Small fixes executed via /ms:do-work
+- Last 5 adhoc work entries
+- Format: `- [date]: [description] (.planning/adhoc/[file]-SUMMARY.md)`
+- Full history remains in .planning/adhoc/ directory
+- Older entries removed from STATE.md but files preserved
+
+**Blockers/Concerns:** From "Next Phase Readiness" sections
+- Issues that affect future work
+- Prefix with originating phase
+- Cleared when addressed
+
+### Session Continuity
+Enables instant resumption:
+- When was last session
+- What was last completed
+- Is there a .continue-here file to resume from
+
+</sections>
+
+<size_constraint>
+
+Keep STATE.md under 100 lines.
+
+It's a DIGEST, not an archive. If accumulated context grows too large:
+- Keep only 3-5 recent decisions in summary (full log in PROJECT.md)
+- Keep only active blockers, remove resolved ones
+
+The goal is "read once, know where we are" — if it's too long, that fails.
+
+</size_constraint>
+
+<guidelines>
+
+**When created:**
+- During project initialization (after ROADMAP.md)
+- Reference PROJECT.md (extract core value and current focus)
+- Initialize empty sections
+
+**When read:**
+- Every workflow starts by reading STATE.md
+- Then read PROJECT.md for full context
+- Provides instant context restoration
+
+**When updated:**
+- After each plan execution (update position, note decisions, update issues/blockers)
+- After phase transitions (update progress bar, clear resolved blockers, refresh project reference)
+- After adhoc work via /ms:do-work (add entry to "Recent Adhoc Work")
+
+**Size management:**
+- Keep under 100 lines total
+- Recent decisions only in STATE.md (full log in PROJECT.md)
+- Keep only active blockers
+
+**Sections:**
+- Project Reference: Pointer to PROJECT.md with core value
+- Current Position: Where we are now (phase, plan, status)
+- Performance Metrics: Velocity tracking
+- Accumulated Context: Recent decisions, pending todos, adhoc work, blockers
+- Session Continuity: Resume information
+
+</guidelines>

package/mindsystem/templates/summary.md

@@ -0,0 +1,269 @@
+# Summary Template
+
+Template for `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md` - phase completion documentation.
+
+---
+
+## File Template
+
+```markdown
+---
+phase: XX-name
+plan: YY
+subsystem: [primary category: auth, payments, ui, api, database, infra, testing, etc.]
+tags: [searchable tech: jwt, stripe, react, postgres, prisma]
+
+# Dependency graph
+requires:
+  - phase: [prior phase this depends on]
+    provides: [what that phase built that this uses]
+provides:
+  - [bullet list of what this phase built/delivered]
+affects: [list of phase names or keywords that will need this context]
+
+# Tech tracking
+tech-stack:
+  added: [libraries/tools added in this phase]
+  patterns: [architectural/code patterns established]
+
+key-files:
+  created: [important files created]
+  modified: [important files modified]
+
+key-decisions:
+  - "Decision 1"
+  - "Decision 2"
+
+patterns-established:
+  - "Pattern 1: description"
+  - "Pattern 2: description"
+
+# Metrics
+duration: Xmin
+completed: YYYY-MM-DD
+---
+
+# Phase [X]: [Name] Summary
+
+**[Substantive one-liner describing outcome - NOT "phase complete" or "implementation finished"]**
+
+## Performance
+
+- **Duration:** [time] (e.g., 23 min, 1h 15m)
+- **Started:** [ISO timestamp]
+- **Completed:** [ISO timestamp]
+- **Tasks:** [count completed]
+- **Files modified:** [count]
+
+## Accomplishments
+- [Most important outcome]
+- [Second key accomplishment]
+- [Third if applicable]
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: [task name]** - `abc123f` (feat/fix/test/refactor)
+2. **Task 2: [task name]** - `def456g` (feat/fix/test/refactor)
+3. **Task 3: [task name]** - `hij789k` (feat/fix/test/refactor)
+
+**Plan metadata:** `lmn012o` (docs: complete plan)
+
+_Note: TDD tasks may have multiple commits (test → feat → refactor)_
+
+## Files Created/Modified
+- `path/to/file.ts` - What it does
+- `path/to/another.ts` - What it does
+
+## Decisions Made
+[Key decisions with brief rationale, or "None - followed plan as specified"]
+
+## Deviations from Plan
+
+[If no deviations: "None - plan executed exactly as written"]
+
+[If deviations occurred:]
+
+### Auto-fixed Issues
+
+**1. [Rule X - Category] Brief description**
+- **Found during:** Task [N] ([task name])
+- **Issue:** [What was wrong]
+- **Fix:** [What was done]
+- **Files modified:** [file paths]
+- **Verification:** [How it was verified]
+- **Committed in:** [hash] (part of task commit)
+
+[... repeat for each auto-fix ...]
+
+---
+
+**Total deviations:** [N] auto-fixed ([breakdown by rule])
+**Impact on plan:** [Brief assessment - e.g., "All auto-fixes necessary for correctness/security. No scope creep."]
+
+## Issues Encountered
+[Problems and how they were resolved, or "None"]
+
+[Note: "Deviations from Plan" documents unplanned work that was handled automatically via deviation rules. "Issues Encountered" documents problems during planned work that required problem-solving.]
+
+## User Setup Required
+
+[If USER-SETUP.md was generated:]
+**External services require manual configuration.** See [{phase}-USER-SETUP.md](./{phase}-USER-SETUP.md) for:
+- Environment variables to add
+- Dashboard configuration steps
+- Verification commands
+
+[If no USER-SETUP.md:]
+None - no external service configuration required.
+
+## Next Phase Readiness
+[What's ready for next phase]
+[Any blockers or concerns]
+
+---
+*Phase: XX-name*
+*Completed: [date]*
+```
+
+<frontmatter_guidance>
+**Purpose:** Enable automatic context assembly via dependency graph. Frontmatter makes summary metadata machine-readable so plan-phase can scan all summaries quickly and select relevant ones based on dependencies.
+
+**Fast scanning:** Frontmatter is first ~25 lines, cheap to scan across all summaries without reading full content.
+
+**Dependency graph:** `requires`/`provides`/`affects` create explicit links between phases, enabling transitive closure for context selection.
+
+**Subsystem:** Primary categorization (auth, payments, ui, api, database, infra, testing) for detecting related phases.
+
+**Tags:** Searchable technical keywords (libraries, frameworks, tools) for tech stack awareness.
+
+**Key-files:** Important files for @context references in PLAN.md.
+
+**Patterns:** Established conventions future phases should maintain.
+
+**Population:** Frontmatter is populated during summary creation in execute-plan.md. See `<step name="create_summary">` for field-by-field guidance.
+</frontmatter_guidance>
+
+<one_liner_rules>
+The one-liner MUST be substantive:
+
+**Good:**
+- "JWT auth with refresh rotation using jose library"
+- "Prisma schema with User, Session, and Product models"
+- "Dashboard with real-time metrics via Server-Sent Events"
+
+**Bad:**
+- "Phase complete"
+- "Authentication implemented"
+- "Foundation finished"
+- "All tasks done"
+
+The one-liner should tell someone what actually shipped.
+</one_liner_rules>
+
+<example>
+```markdown
+# Phase 1: Foundation Summary
+
+**JWT auth with refresh rotation using jose library, Prisma User model, and protected API middleware**
+
+## Performance
+
+- **Duration:** 28 min
+- **Started:** 2025-01-15T14:22:10Z
+- **Completed:** 2025-01-15T14:50:33Z
+- **Tasks:** 5
+- **Files modified:** 8
+
+## Accomplishments
+- User model with email/password auth
+- Login/logout endpoints with httpOnly JWT cookies
+- Protected route middleware checking token validity
+- Refresh token rotation on each request
+
+## Files Created/Modified
+- `prisma/schema.prisma` - User and Session models
+- `src/app/api/auth/login/route.ts` - Login endpoint
+- `src/app/api/auth/logout/route.ts` - Logout endpoint
+- `src/middleware.ts` - Protected route checks
+- `src/lib/auth.ts` - JWT helpers using jose
+
+## Decisions Made
+- Used jose instead of jsonwebtoken (ESM-native, Edge-compatible)
+- 15-min access tokens with 7-day refresh tokens
+- Storing refresh tokens in database for revocation capability
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 2 - Missing Critical] Added password hashing with bcrypt**
+- **Found during:** Task 2 (Login endpoint implementation)
+- **Issue:** Plan didn't specify password hashing - storing plaintext would be critical security flaw
+- **Fix:** Added bcrypt hashing on registration, comparison on login with salt rounds 10
+- **Files modified:** src/app/api/auth/login/route.ts, src/lib/auth.ts
+- **Verification:** Password hash test passes, plaintext never stored
+- **Committed in:** abc123f (Task 2 commit)
+
+**2. [Rule 3 - Blocking] Installed missing jose dependency**
+- **Found during:** Task 4 (JWT token generation)
+- **Issue:** jose package not in package.json, import failing
+- **Fix:** Ran `npm install jose`
+- **Files modified:** package.json, package-lock.json
+- **Verification:** Import succeeds, build passes
+- **Committed in:** def456g (Task 4 commit)
+
+---
+
+**Total deviations:** 2 auto-fixed (1 missing critical, 1 blocking)
+**Impact on plan:** Both auto-fixes essential for security and functionality. No scope creep.
+
+## Issues Encountered
+- jsonwebtoken CommonJS import failed in Edge runtime - switched to jose (planned library change, worked as expected)
+
+## Next Phase Readiness
+- Auth foundation complete, ready for feature development
+- User registration endpoint needed before public launch
+
+---
+*Phase: 01-foundation*
+*Completed: 2025-01-15*
+```
+</example>
+
+<guidelines>
+**When to create:**
+- After completing each phase plan
+- Required output from execute-plan workflow
+- Documents what actually happened vs what was planned
+
+**Frontmatter completion:**
+- MANDATORY: Complete all frontmatter fields during summary creation
+- See <frontmatter_guidance> for field purposes
+- Frontmatter enables automatic context assembly for future planning
+
+**One-liner requirements:**
+- Must be substantive (describe what shipped, not "phase complete")
+- Should tell someone what was accomplished
+- Examples: "JWT auth with refresh rotation using jose library" not "Authentication implemented"
+
+**Performance tracking:**
+- Include duration, start/end timestamps
+- Used for velocity metrics in STATE.md
+
+**Deviations section:**
+- Documents unplanned work handled via deviation rules
+- Separate from "Issues Encountered" (which is planned work problems)
+- Auto-fixed issues: What was wrong, how fixed, verification
+
+**Decisions section:**
+- Key decisions made during execution
+- Include rationale (why this choice)
+- Extracted to STATE.md accumulated context
+- Use "None - followed plan as specified" if no deviations
+
+**After creation:**
+- STATE.md updated with position, decisions, issues
+- Next plan can reference decisions made
+</guidelines>