mindsystem-cc 3.0.0

package/mindsystem/references/plan-format.md

@@ -0,0 +1,473 @@
+<overview>
+Claude-executable plans have a specific format that enables Claude to implement without interpretation. This reference defines what makes a plan executable vs. vague.
+
+**Key insight:** PLAN.md IS the executable prompt. It contains everything Claude needs to execute the phase, including objective, context references, tasks, verification, success criteria, and output specification.
+</overview>
+
+<core_principle>
+A plan is Claude-executable when Claude can read the PLAN.md and immediately start implementing without asking clarifying questions.
+
+If Claude has to guess, interpret, or make assumptions - the task is too vague.
+</core_principle>
+
+<frontmatter>
+Every PLAN.md starts with YAML frontmatter:
+
+```yaml
+---
+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
+autonomous: true            # false if plan has checkpoints
+---
+```
+
+| Field | Required | Purpose |
+|-------|----------|---------|
+| `phase` | Yes | Phase identifier (e.g., `01-foundation`) |
+| `plan` | Yes | Plan number within phase (e.g., `01`, `02`) |
+| `type` | Yes | `execute` for standard plans, `tdd` for TDD plans |
+| `wave` | Yes | Execution wave number (1, 2, 3...). Pre-computed during planning. |
+| `depends_on` | Yes | Array of plan IDs this plan requires. |
+| `files_modified` | Yes | Files this plan touches. |
+| `autonomous` | Yes | `true` if no checkpoints, `false` if has checkpoints |
+
+**Wave is pre-computed:** `/ms:plan-phase` assigns wave numbers based on `depends_on`. `/ms:execute-phase` reads `wave` directly from frontmatter and groups plans by wave number. No runtime dependency analysis needed.
+
+**Checkpoint handling:** Plans with `autonomous: false` require user interaction. They run in their assigned wave but pause at checkpoints.
+</frontmatter>
+
+<prompt_structure>
+Every PLAN.md follows this XML structure:
+
+```markdown
+---
+phase: XX-name
+plan: NN
+type: execute
+wave: N
+depends_on: []
+files_modified: [path/to/file.ts]
+autonomous: true
+---
+
+<objective>
+[What and why]
+Purpose: [...]
+Output: [...]
+</objective>
+
+<execution_context>
+@~/.claude/mindsystem/workflows/execute-plan.md
+@~/.claude/mindsystem/templates/summary.md
+[If checkpoints exist:]
+@~/.claude/mindsystem/references/checkpoints.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+[Only if genuinely needed:]
+@.planning/phases/XX-name/XX-YY-SUMMARY.md
+@relevant/source/files.ts
+</context>
+
+<tasks>
+<task type="auto">
+  <name>Task N: [Name]</name>
+  <files>[paths]</files>
+  <action>[what to do, what to avoid and WHY]</action>
+  <verify>[command/check]</verify>
+  <done>[criteria]</done>
+</task>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>[what Claude automated]</what-built>
+  <how-to-verify>[numbered verification steps]</how-to-verify>
+  <resume-signal>[how to continue - "approved" or describe issues]</resume-signal>
+</task>
+
+<task type="checkpoint:decision" gate="blocking">
+  <decision>[what needs deciding]</decision>
+  <context>[why this matters]</context>
+  <options>
+    <option id="option-a"><name>[Name]</name><pros>[pros]</pros><cons>[cons]</cons></option>
+    <option id="option-b"><name>[Name]</name><pros>[pros]</pros><cons>[cons]</cons></option>
+  </options>
+  <resume-signal>[how to indicate choice]</resume-signal>
+</task>
+</tasks>
+
+<verification>
+[Overall phase checks]
+</verification>
+
+<success_criteria>
+[Measurable completion]
+</success_criteria>
+
+<output>
+[SUMMARY.md specification]
+</output>
+```
+
+</prompt_structure>
+
+<task_anatomy>
+Every task has four required fields:
+
+<field name="files">
+**What it is**: Exact file paths that will be created or modified.
+
+**Good**: `src/app/api/auth/login/route.ts`, `prisma/schema.prisma`
+**Bad**: "the auth files", "relevant components"
+
+Be specific. If you don't know the file path, figure it out first.
+</field>
+
+<field name="action">
+**What it is**: Specific implementation instructions, including what to avoid and WHY.
+
+**Good**: "Create POST endpoint that accepts {email, password}, validates using bcrypt against User table, returns JWT in httpOnly cookie with 15-min expiry. Use jose library (not jsonwebtoken - CommonJS issues with Next.js Edge runtime)."
+
+**Bad**: "Add authentication", "Make login work"
+
+Include: technology choices, data structures, behavior details, pitfalls to avoid.
+</field>
+
+<field name="verify">
+**What it is**: How to prove the task is complete.
+
+**Good**:
+
+- `npm test` passes
+- `curl -X POST /api/auth/login` returns 200 with Set-Cookie header
+- Build completes without errors
+
+**Bad**: "It works", "Looks good", "User can log in"
+
+Must be executable - a command, a test, an observable behavior.
+</field>
+
+<field name="done">
+**What it is**: Acceptance criteria - the measurable state of completion.
+
+**Good**: "Valid credentials return 200 + JWT cookie, invalid credentials return 401"
+
+**Bad**: "Authentication is complete"
+
+Should be testable without subjective judgment.
+</field>
+</task_anatomy>
+
+<task_types>
+Tasks have a `type` attribute that determines how they execute:
+
+<type name="auto">
+**Default task type** - Claude executes autonomously.
+
+**Structure:**
+
+```xml
+<task type="auto">
+  <name>Task 3: Create login endpoint with JWT</name>
+  <files>src/app/api/auth/login/route.ts</files>
+  <action>POST endpoint accepting {email, password}. Query User by email, compare password with bcrypt. On match, create JWT with jose library, set as httpOnly cookie (15-min expiry). Return 200. On mismatch, return 401.</action>
+  <verify>curl -X POST localhost:3000/api/auth/login returns 200 with Set-Cookie header</verify>
+  <done>Valid credentials → 200 + cookie. Invalid → 401.</done>
+</task>
+```
+
+Use for: Everything Claude can do independently (code, tests, builds, file operations).
+</type>
+
+<type name="checkpoint:human-action">
+**RARELY USED** - Only for actions with NO CLI/API. Claude automates everything possible first.
+
+**Structure:**
+
+```xml
+<task type="checkpoint:human-action" gate="blocking">
+  <action>[Unavoidable manual step - email link, 2FA code]</action>
+  <instructions>
+    [What Claude already automated]
+    [The ONE thing requiring human action]
+  </instructions>
+  <verification>[What Claude can check afterward]</verification>
+  <resume-signal>[How to continue]</resume-signal>
+</task>
+```
+
+Use ONLY for: Email verification links, SMS 2FA codes, manual approvals with no API, 3D Secure payment flows.
+
+Do NOT use for: Anything with a CLI (Vercel, Stripe, Upstash, Railway, GitHub), builds, tests, file creation, deployments.
+
+**Execution:** Claude automates everything with CLI/API, stops only for truly unavoidable manual steps.
+</type>
+
+<type name="checkpoint:human-verify">
+**Human must verify Claude's work** - Visual checks, UX testing.
+
+**Structure:**
+
+```xml
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>Responsive dashboard layout</what-built>
+  <how-to-verify>
+    1. Run: npm run dev
+    2. Visit: http://localhost:3000/dashboard
+    3. Desktop (>1024px): Verify sidebar left, content right
+    4. Tablet (768px): Verify sidebar collapses to hamburger
+    5. Mobile (375px): Verify single column, bottom nav
+    6. Check: No layout shift, no horizontal scroll
+  </how-to-verify>
+  <resume-signal>Type "approved" or describe issues</resume-signal>
+</task>
+```
+
+Use for: UI/UX verification, visual design checks, animation smoothness, accessibility testing.
+
+**Execution:** Claude builds the feature, stops, provides testing instructions, waits for approval/feedback.
+</type>
+
+<type name="checkpoint:decision">
+**Human must make implementation choice** - Direction-setting decisions.
+
+**Structure:**
+
+```xml
+<task type="checkpoint:decision" gate="blocking">
+  <decision>Select authentication provider</decision>
+  <context>We need user authentication. Three approaches with different tradeoffs:</context>
+  <options>
+    <option id="supabase">
+      <name>Supabase Auth</name>
+      <pros>Built-in with Supabase, generous free tier</pros>
+      <cons>Less customizable UI, tied to ecosystem</cons>
+    </option>
+    <option id="clerk">
+      <name>Clerk</name>
+      <pros>Beautiful pre-built UI, best DX</pros>
+      <cons>Paid after 10k MAU</cons>
+    </option>
+    <option id="nextauth">
+      <name>NextAuth.js</name>
+      <pros>Free, self-hosted, maximum control</pros>
+      <cons>More setup, you manage security</cons>
+    </option>
+  </options>
+  <resume-signal>Select: supabase, clerk, or nextauth</resume-signal>
+</task>
+```
+
+Use for: Technology selection, architecture decisions, design choices, feature prioritization.
+
+**Execution:** Claude presents options with balanced pros/cons, waits for decision, proceeds with chosen direction.
+</type>
+
+**When to use checkpoints:**
+
+- Visual/UX verification (after Claude builds) → `checkpoint:human-verify`
+- Implementation direction choice → `checkpoint:decision`
+- Truly unavoidable manual actions (email links, 2FA) → `checkpoint:human-action` (rare)
+
+**When NOT to use checkpoints:**
+
+- Anything with CLI/API (Claude automates it) → `type="auto"`
+- Deployments (Vercel, Railway, Fly) → `type="auto"` with CLI
+- Creating resources (Upstash, Stripe, GitHub) → `type="auto"` with CLI/API
+- File operations, tests, builds → `type="auto"`
+
+**Golden rule:** If Claude CAN automate it, Claude MUST automate it.
+
+**Checkpoint impact on parallelization:**
+- Plans with checkpoints set `autonomous: false` in frontmatter
+- Non-autonomous plans execute after parallel wave or in main context
+- Subagent pauses at checkpoint, returns to orchestrator
+- Orchestrator presents checkpoint to user
+- User responds
+- Orchestrator resumes agent with `resume: agent_id`
+
+See `./checkpoints.md` for comprehensive checkpoint guidance.
+</task_types>
+
+<tdd_plans>
+**TDD work uses dedicated plans.**
+
+TDD features require 2-3 execution cycles (RED → GREEN → REFACTOR), each with file reads, test runs, and potential debugging. This is fundamentally heavier than standard tasks and would consume 50-60% of context if embedded in a multi-task plan.
+
+**When to create a TDD plan:**
+- Business logic with defined inputs/outputs
+- API endpoints with request/response contracts
+- Data transformations and parsing
+- Validation rules
+- Algorithms with testable behavior
+
+**When to use standard plans (skip TDD):**
+- UI layout and styling
+- Configuration changes
+- Glue code connecting existing components
+- One-off scripts
+
+**Heuristic:** Can you write `expect(fn(input)).toBe(output)` before writing `fn`?
+→ Yes: Create a TDD plan (one feature per plan)
+→ No: Use standard plan, add tests after if needed
+
+See `./tdd.md` for TDD plan structure and execution guidance.
+</tdd_plans>
+
+<context_references>
+Use @file references to load context for the prompt:
+
+```markdown
+<context>
+@.planning/PROJECT.md           # Project vision
+@.planning/ROADMAP.md           # Phase structure
+@.planning/STATE.md             # Current position
+
+# Only include prior SUMMARY if genuinely needed:
+# - This plan imports types from prior plan
+# - Prior plan made decision affecting this plan
+# Independent plans need NO prior SUMMARY references.
+
+@src/lib/db.ts                  # Existing database setup
+@src/types/user.ts              # Existing type definitions
+</context>
+```
+
+Reference files that Claude needs to understand before implementing.
+
+**Anti-pattern:** Reflexive chaining (02 refs 01, 03 refs 02). Only reference what you actually need.
+</context_references>
+
+<verification_section>
+Overall phase verification (beyond individual task verification):
+
+```markdown
+<verification>
+Before declaring phase complete:
+- [ ] `npm run build` succeeds without errors
+- [ ] `npm test` passes all tests
+- [ ] No TypeScript errors
+- [ ] Feature works end-to-end manually
+</verification>
+```
+
+</verification_section>
+
+<success_criteria_section>
+Measurable criteria for phase completion:
+
+```markdown
+<success_criteria>
+
+- All tasks completed
+- All verification checks pass
+- No errors or warnings introduced
+- JWT auth flow works end-to-end
+- Protected routes redirect unauthenticated users
+  </success_criteria>
+```
+
+</success_criteria_section>
+
+<output_section>
+Specify the SUMMARY.md structure:
+
+```markdown
+<output>
+After completion, create `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`
+</output>
+```
+
+</output_section>
+
+<specificity_levels>
+<too_vague>
+
+```xml
+<task type="auto">
+  <name>Task 1: Add authentication</name>
+  <files>???</files>
+  <action>Implement auth</action>
+  <verify>???</verify>
+  <done>Users can authenticate</done>
+</task>
+```
+
+Claude: "How? What type? What library? Where?"
+</too_vague>
+
+<just_right>
+
+```xml
+<task type="auto">
+  <name>Task 1: Create login endpoint with JWT</name>
+  <files>src/app/api/auth/login/route.ts</files>
+  <action>POST endpoint accepting {email, password}. Query User by email, compare password with bcrypt. On match, create JWT with jose library, set as httpOnly cookie (15-min expiry). Return 200. On mismatch, return 401. Use jose instead of jsonwebtoken (CommonJS issues with Edge).</action>
+  <verify>curl -X POST localhost:3000/api/auth/login -H "Content-Type: application/json" -d '{"email":"test@test.com","password":"test123"}' returns 200 with Set-Cookie header containing JWT</verify>
+  <done>Valid credentials → 200 + cookie. Invalid → 401. Missing fields → 400.</done>
+</task>
+```
+
+Claude can implement this immediately.
+</just_right>
+
+<note_on_tdd>
+**TDD candidates get dedicated plans.**
+
+If email validation warrants TDD, create a TDD plan for it. See `./tdd.md` for TDD plan structure.
+</note_on_tdd>
+
+<too_detailed>
+Writing the actual code in the plan. Trust Claude to implement from clear instructions.
+</too_detailed>
+</specificity_levels>
+
+<anti_patterns>
+<vague_actions>
+
+- "Set up the infrastructure"
+- "Handle edge cases"
+- "Make it production-ready"
+- "Add proper error handling"
+
+These require Claude to decide WHAT to do. Specify it.
+</vague_actions>
+
+<unverifiable_completion>
+
+- "It works correctly"
+- "User experience is good"
+- "Code is clean"
+- "Tests pass" (which tests? do they exist?)
+
+These require subjective judgment. Make it objective.
+</unverifiable_completion>
+
+<missing_context>
+
+- "Use the standard approach"
+- "Follow best practices"
+- "Like the other endpoints"
+
+Claude doesn't know your standards. Be explicit.
+</missing_context>
+</anti_patterns>
+
+<sizing_tasks>
+Good task size: 15-60 minutes of Claude work.
+
+**Too small**: "Add import statement for bcrypt" (combine with related task)
+**Just right**: "Create login endpoint with JWT validation" (focused, specific)
+**Too big**: "Implement full authentication system" (split into multiple plans)
+
+If a task takes multiple sessions, break it down.
+If a task is trivial, combine with related tasks.
+
+**Note on scope:** If a phase has >3 tasks or spans multiple subsystems, split into multiple plans using the naming convention `{phase}-{plan}-PLAN.md`. See `./scope-estimation.md` for guidance.
+</sizing_tasks>

package/mindsystem/references/principles.md

@@ -0,0 +1,73 @@
+<principles>
+
+Core principles for the GSD planning system.
+
+<solo_developer_claude>
+
+You are planning for ONE person (the user) and ONE implementer (Claude).
+- No teams, stakeholders, ceremonies, coordination overhead
+- User is the visionary/product owner
+- Claude is the builder
+- Estimate effort in Claude execution time, not human dev time
+</solo_developer_claude>
+
+<plans_are_prompts>
+
+PLAN.md is not a document that gets transformed into a prompt.
+PLAN.md IS the prompt. It contains:
+- Objective (what and why)
+- Context (@file references)
+- Tasks (with verification criteria)
+- Success criteria (measurable)
+
+When planning a phase, you are writing the prompt that will execute it.
+</plans_are_prompts>
+
+<scope_control>
+
+Plans must complete within reasonable context usage.
+
+**Quality degradation curve:**
+- 0-30% context: Peak quality
+- 30-50% context: Good quality
+- 50-70% context: Degrading quality
+- 70%+ context: Poor quality
+
+**Solution:** Aggressive atomicity - split into small, focused plans.
+- 2-3 tasks per plan maximum
+- Each plan independently executable
+- Better to have many small plans than few large ones
+</scope_control>
+
+<claude_automates>
+
+If Claude CAN do it via CLI/API/tool, Claude MUST do it.
+
+Checkpoints are for:
+- **Verification** - Human confirms Claude's work (visual, UX)
+- **Decision** - Human makes implementation choice
+</claude_automates>
+
+<ship_fast>
+
+No enterprise process. No approval gates.
+
+Plan → Execute → Ship → Learn → Repeat
+
+Milestones mark shipped versions (v1.0 → v1.1 → v2.0).
+</ship_fast>
+
+<anti_enterprise>
+
+NEVER include:
+- Team structures, RACI matrices
+- Stakeholder management
+- Sprint ceremonies
+- Human dev time estimates (hours, days, weeks—Claude works differently)
+- Change management processes
+- Documentation for documentation's sake
+
+If it sounds like corporate PM theater, delete it.
+</anti_enterprise>
+
+</principles>

package/mindsystem/references/questioning.md

@@ -0,0 +1,140 @@
+<questioning_guide>
+
+Project initialization is dream extraction, not requirements gathering. You're helping the user discover and articulate what they want to build. This isn't a contract negotiation — it's collaborative thinking.
+
+<philosophy>
+
+**You are a thinking partner, not an interviewer.**
+
+The user often has a fuzzy idea. Your job is to help them sharpen it. Ask questions that make them think "oh, I hadn't considered that" or "yes, that's exactly what I mean."
+
+Don't interrogate. Collaborate. Don't follow a script. Follow the thread.
+
+</philosophy>
+
+<the_goal>
+
+By the end of questioning, you need enough clarity to write a PROJECT.md that downstream phases can act on:
+
+- **research-project** needs: what domain to research, what the user already knows, what unknowns exist
+- **create-roadmap** needs: clear enough vision to decompose into phases, what "done" looks like
+- **plan-phase** needs: specific requirements to break into tasks, context for implementation choices
+- **execute-phase** needs: success criteria to verify against, the "why" behind requirements
+
+A vague PROJECT.md forces every downstream phase to guess. The cost compounds.
+
+</the_goal>
+
+<how_to_question>
+
+**Start open.** Let them dump their mental model. Don't interrupt with structure.
+
+**Follow energy.** Whatever they emphasized, dig into that. What excited them? What problem sparked this?
+
+**Challenge vagueness.** Never accept fuzzy answers. "Good" means what? "Users" means who? "Simple" means how?
+
+**Make the abstract concrete.** "Walk me through using this." "What does that actually look like?"
+
+**Clarify ambiguity.** "When you say Z, do you mean A or B?" "You mentioned X — tell me more."
+
+**Know when to stop.** When you understand what they want, why they want it, who it's for, and what done looks like — offer to proceed.
+
+</how_to_question>
+
+<question_types>
+
+Use these as inspiration, not a checklist. Pick what's relevant to the thread.
+
+**Motivation — why this exists:**
+- "What prompted this?"
+- "What are you doing today that this replaces?"
+- "What would you do if this existed?"
+
+**Concreteness — what it actually is:**
+- "Walk me through using this"
+- "You said X — what does that actually look like?"
+- "Give me an example"
+
+**Clarification — what they mean:**
+- "When you say Z, do you mean A or B?"
+- "You mentioned X — tell me more about that"
+
+**Success — how you'll know it's working:**
+- "How will you know this is working?"
+- "What does done look like?"
+
+</question_types>
+
+<using_askuserquestion>
+
+Use AskUserQuestion to help users think by presenting concrete options to react to.
+
+**Good options:**
+- Interpretations of what they might mean
+- Specific examples to confirm or deny
+- Concrete choices that reveal priorities
+
+**Bad options:**
+- Generic categories ("Technical", "Business", "Other")
+- Leading options that presume an answer
+- Too many options (2-4 is ideal)
+
+**Example — vague answer:**
+User says "it should be fast"
+
+- header: "Fast"
+- question: "Fast how?"
+- options: ["Sub-second response", "Handles large datasets", "Quick to build", "Let me explain"]
+
+**Example — following a thread:**
+User mentions "frustrated with current tools"
+
+- header: "Frustration"
+- question: "What specifically frustrates you?"
+- options: ["Too many clicks", "Missing features", "Unreliable", "Let me explain"]
+
+</using_askuserquestion>
+
+<context_checklist>
+
+Use this as a **background checklist**, not a conversation structure. Check these mentally as you go. If gaps remain, weave questions naturally.
+
+- [ ] What they're building (concrete enough to explain to a stranger)
+- [ ] Why it needs to exist (the problem or desire driving it)
+- [ ] Who it's for (even if just themselves)
+- [ ] What "done" looks like (observable outcomes)
+
+Four things. If they volunteer more, capture it.
+
+</context_checklist>
+
+<decision_gate>
+
+When you could write a clear PROJECT.md, offer to proceed:
+
+- header: "Ready?"
+- question: "I think I understand what you're after. Ready to create PROJECT.md?"
+- options:
+  - "Create PROJECT.md" — Let's move forward
+  - "Keep exploring" — I want to share more / ask me more
+
+If "Keep exploring" — ask what they want to add or identify gaps and probe naturally.
+
+Loop until "Create PROJECT.md" selected.
+
+</decision_gate>
+
+<anti_patterns>
+
+- **Checklist walking** — Going through domains regardless of what they said
+- **Canned questions** — "What's your core value?" "What's out of scope?" regardless of context
+- **Corporate speak** — "What are your success criteria?" "Who are your stakeholders?"
+- **Interrogation** — Firing questions without building on answers
+- **Rushing** — Minimizing questions to get to "the work"
+- **Shallow acceptance** — Taking vague answers without probing
+- **Premature constraints** — Asking about tech stack before understanding the idea
+- **User skills** — NEVER ask about user's technical experience. Claude builds.
+
+</anti_patterns>
+
+</questioning_guide>