mindsystem-cc 3.0.0

package/mindsystem/templates/research-project/FEATURES.md

@@ -0,0 +1,147 @@
+# Features Research Template
+
+Template for `.planning/research/FEATURES.md` — feature landscape for the project domain.
+
+<template>
+
+```markdown
+# Feature Research
+
+**Domain:** [domain type]
+**Researched:** [date]
+**Confidence:** [HIGH/MEDIUM/LOW]
+
+## Feature Landscape
+
+### Table Stakes (Users Expect These)
+
+Features users assume exist. Missing these = product feels incomplete.
+
+| Feature | Why Expected | Complexity | Notes |
+|---------|--------------|------------|-------|
+| [feature] | [user expectation] | LOW/MEDIUM/HIGH | [implementation notes] |
+| [feature] | [user expectation] | LOW/MEDIUM/HIGH | [implementation notes] |
+| [feature] | [user expectation] | LOW/MEDIUM/HIGH | [implementation notes] |
+
+### Differentiators (Competitive Advantage)
+
+Features that set the product apart. Not required, but valuable.
+
+| Feature | Value Proposition | Complexity | Notes |
+|---------|-------------------|------------|-------|
+| [feature] | [why it matters] | LOW/MEDIUM/HIGH | [implementation notes] |
+| [feature] | [why it matters] | LOW/MEDIUM/HIGH | [implementation notes] |
+| [feature] | [why it matters] | LOW/MEDIUM/HIGH | [implementation notes] |
+
+### Anti-Features (Commonly Requested, Often Problematic)
+
+Features that seem good but create problems.
+
+| Feature | Why Requested | Why Problematic | Alternative |
+|---------|---------------|-----------------|-------------|
+| [feature] | [surface appeal] | [actual problems] | [better approach] |
+| [feature] | [surface appeal] | [actual problems] | [better approach] |
+
+## Feature Dependencies
+
+```
+[Feature A]
+    └──requires──> [Feature B]
+                       └──requires──> [Feature C]
+
+[Feature D] ──enhances──> [Feature A]
+
+[Feature E] ──conflicts──> [Feature F]
+```
+
+### Dependency Notes
+
+- **[Feature A] requires [Feature B]:** [why the dependency exists]
+- **[Feature D] enhances [Feature A]:** [how they work together]
+- **[Feature E] conflicts with [Feature F]:** [why they're incompatible]
+
+## MVP Definition
+
+### Launch With (v1)
+
+Minimum viable product — what's needed to validate the concept.
+
+- [ ] [Feature] — [why essential]
+- [ ] [Feature] — [why essential]
+- [ ] [Feature] — [why essential]
+
+### Add After Validation (v1.x)
+
+Features to add once core is working.
+
+- [ ] [Feature] — [trigger for adding]
+- [ ] [Feature] — [trigger for adding]
+
+### Future Consideration (v2+)
+
+Features to defer until product-market fit is established.
+
+- [ ] [Feature] — [why defer]
+- [ ] [Feature] — [why defer]
+
+## Feature Prioritization Matrix
+
+| Feature | User Value | Implementation Cost | Priority |
+|---------|------------|---------------------|----------|
+| [feature] | HIGH/MEDIUM/LOW | HIGH/MEDIUM/LOW | P1/P2/P3 |
+| [feature] | HIGH/MEDIUM/LOW | HIGH/MEDIUM/LOW | P1/P2/P3 |
+| [feature] | HIGH/MEDIUM/LOW | HIGH/MEDIUM/LOW | P1/P2/P3 |
+
+**Priority key:**
+- P1: Must have for launch
+- P2: Should have, add when possible
+- P3: Nice to have, future consideration
+
+## Competitor Feature Analysis
+
+| Feature | Competitor A | Competitor B | Our Approach |
+|---------|--------------|--------------|--------------|
+| [feature] | [how they do it] | [how they do it] | [our plan] |
+| [feature] | [how they do it] | [how they do it] | [our plan] |
+
+## Sources
+
+- [Competitor products analyzed]
+- [User research or feedback sources]
+- [Industry standards referenced]
+
+---
+*Feature research for: [domain]*
+*Researched: [date]*
+```
+
+</template>
+
+<guidelines>
+
+**Table Stakes:**
+- These are non-negotiable for launch
+- Users don't give credit for having them, but penalize for missing them
+- Example: A community platform without user profiles is broken
+
+**Differentiators:**
+- These are where you compete
+- Should align with the Core Value from PROJECT.md
+- Don't try to differentiate on everything
+
+**Anti-Features:**
+- Prevent scope creep by documenting what seems good but isn't
+- Include the alternative approach
+- Example: "Real-time everything" often creates complexity without value
+
+**Feature Dependencies:**
+- Critical for roadmap phase ordering
+- If A requires B, B must be in an earlier phase
+- Conflicts inform what NOT to combine in same phase
+
+**MVP Definition:**
+- Be ruthless about what's truly minimum
+- "Nice to have" is not MVP
+- Launch with less, validate, then expand
+
+</guidelines>

package/mindsystem/templates/research-project/PITFALLS.md

@@ -0,0 +1,200 @@
+# Pitfalls Research Template
+
+Template for `.planning/research/PITFALLS.md` — common mistakes to avoid in the project domain.
+
+<template>
+
+```markdown
+# Pitfalls Research
+
+**Domain:** [domain type]
+**Researched:** [date]
+**Confidence:** [HIGH/MEDIUM/LOW]
+
+## Critical Pitfalls
+
+### Pitfall 1: [Name]
+
+**What goes wrong:**
+[Description of the failure mode]
+
+**Why it happens:**
+[Root cause — why developers make this mistake]
+
+**How to avoid:**
+[Specific prevention strategy]
+
+**Warning signs:**
+[How to detect this early before it becomes a problem]
+
+**Phase to address:**
+[Which roadmap phase should prevent this]
+
+---
+
+### Pitfall 2: [Name]
+
+**What goes wrong:**
+[Description of the failure mode]
+
+**Why it happens:**
+[Root cause — why developers make this mistake]
+
+**How to avoid:**
+[Specific prevention strategy]
+
+**Warning signs:**
+[How to detect this early before it becomes a problem]
+
+**Phase to address:**
+[Which roadmap phase should prevent this]
+
+---
+
+### Pitfall 3: [Name]
+
+**What goes wrong:**
+[Description of the failure mode]
+
+**Why it happens:**
+[Root cause — why developers make this mistake]
+
+**How to avoid:**
+[Specific prevention strategy]
+
+**Warning signs:**
+[How to detect this early before it becomes a problem]
+
+**Phase to address:**
+[Which roadmap phase should prevent this]
+
+---
+
+[Continue for all critical pitfalls...]
+
+## Technical Debt Patterns
+
+Shortcuts that seem reasonable but create long-term problems.
+
+| Shortcut | Immediate Benefit | Long-term Cost | When Acceptable |
+|----------|-------------------|----------------|-----------------|
+| [shortcut] | [benefit] | [cost] | [conditions, or "never"] |
+| [shortcut] | [benefit] | [cost] | [conditions, or "never"] |
+| [shortcut] | [benefit] | [cost] | [conditions, or "never"] |
+
+## Integration Gotchas
+
+Common mistakes when connecting to external services.
+
+| Integration | Common Mistake | Correct Approach |
+|-------------|----------------|------------------|
+| [service] | [what people do wrong] | [what to do instead] |
+| [service] | [what people do wrong] | [what to do instead] |
+| [service] | [what people do wrong] | [what to do instead] |
+
+## Performance Traps
+
+Patterns that work at small scale but fail as usage grows.
+
+| Trap | Symptoms | Prevention | When It Breaks |
+|------|----------|------------|----------------|
+| [trap] | [how you notice] | [how to avoid] | [scale threshold] |
+| [trap] | [how you notice] | [how to avoid] | [scale threshold] |
+| [trap] | [how you notice] | [how to avoid] | [scale threshold] |
+
+## Security Mistakes
+
+Domain-specific security issues beyond general web security.
+
+| Mistake | Risk | Prevention |
+|---------|------|------------|
+| [mistake] | [what could happen] | [how to avoid] |
+| [mistake] | [what could happen] | [how to avoid] |
+| [mistake] | [what could happen] | [how to avoid] |
+
+## UX Pitfalls
+
+Common user experience mistakes in this domain.
+
+| Pitfall | User Impact | Better Approach |
+|---------|-------------|-----------------|
+| [pitfall] | [how users suffer] | [what to do instead] |
+| [pitfall] | [how users suffer] | [what to do instead] |
+| [pitfall] | [how users suffer] | [what to do instead] |
+
+## "Looks Done But Isn't" Checklist
+
+Things that appear complete but are missing critical pieces.
+
+- [ ] **[Feature]:** Often missing [thing] — verify [check]
+- [ ] **[Feature]:** Often missing [thing] — verify [check]
+- [ ] **[Feature]:** Often missing [thing] — verify [check]
+- [ ] **[Feature]:** Often missing [thing] — verify [check]
+
+## Recovery Strategies
+
+When pitfalls occur despite prevention, how to recover.
+
+| Pitfall | Recovery Cost | Recovery Steps |
+|---------|---------------|----------------|
+| [pitfall] | LOW/MEDIUM/HIGH | [what to do] |
+| [pitfall] | LOW/MEDIUM/HIGH | [what to do] |
+| [pitfall] | LOW/MEDIUM/HIGH | [what to do] |
+
+## Pitfall-to-Phase Mapping
+
+How roadmap phases should address these pitfalls.
+
+| Pitfall | Prevention Phase | Verification |
+|---------|------------------|--------------|
+| [pitfall] | Phase [X] | [how to verify prevention worked] |
+| [pitfall] | Phase [X] | [how to verify prevention worked] |
+| [pitfall] | Phase [X] | [how to verify prevention worked] |
+
+## Sources
+
+- [Post-mortems referenced]
+- [Community discussions]
+- [Official "gotchas" documentation]
+- [Personal experience / known issues]
+
+---
+*Pitfalls research for: [domain]*
+*Researched: [date]*
+```
+
+</template>
+
+<guidelines>
+
+**Critical Pitfalls:**
+- Focus on domain-specific issues, not generic mistakes
+- Include warning signs — early detection prevents disasters
+- Link to specific phases — makes pitfalls actionable
+
+**Technical Debt:**
+- Be realistic — some shortcuts are acceptable
+- Note when shortcuts are "never acceptable" vs. "only in MVP"
+- Include the long-term cost to inform tradeoff decisions
+
+**Performance Traps:**
+- Include scale thresholds ("breaks at 10k users")
+- Focus on what's relevant for this project's expected scale
+- Don't over-engineer for hypothetical scale
+
+**Security Mistakes:**
+- Beyond OWASP basics — domain-specific issues
+- Example: Community platforms have different security concerns than e-commerce
+- Include risk level to prioritize
+
+**"Looks Done But Isn't":**
+- Checklist format for verification during execution
+- Common in demos vs. production
+- Prevents "it works on my machine" issues
+
+**Pitfall-to-Phase Mapping:**
+- Critical for roadmap creation
+- Each pitfall should map to a phase that prevents it
+- Informs phase ordering and success criteria
+
+</guidelines>

package/mindsystem/templates/research-project/STACK.md

@@ -0,0 +1,120 @@
+# Stack Research Template
+
+Template for `.planning/research/STACK.md` — recommended technologies for the project domain.
+
+<template>
+
+```markdown
+# Stack Research
+
+**Domain:** [domain type]
+**Researched:** [date]
+**Confidence:** [HIGH/MEDIUM/LOW]
+
+## Recommended Stack
+
+### Core Technologies
+
+| Technology | Version | Purpose | Why Recommended |
+|------------|---------|---------|-----------------|
+| [name] | [version] | [what it does] | [why experts use it for this domain] |
+| [name] | [version] | [what it does] | [why experts use it for this domain] |
+| [name] | [version] | [what it does] | [why experts use it for this domain] |
+
+### Supporting Libraries
+
+| Library | Version | Purpose | When to Use |
+|---------|---------|---------|-------------|
+| [name] | [version] | [what it does] | [specific use case] |
+| [name] | [version] | [what it does] | [specific use case] |
+| [name] | [version] | [what it does] | [specific use case] |
+
+### Development Tools
+
+| Tool | Purpose | Notes |
+|------|---------|-------|
+| [name] | [what it does] | [configuration tips] |
+| [name] | [what it does] | [configuration tips] |
+
+## Installation
+
+```bash
+# Core
+npm install [packages]
+
+# Supporting
+npm install [packages]
+
+# Dev dependencies
+npm install -D [packages]
+```
+
+## Alternatives Considered
+
+| Recommended | Alternative | When to Use Alternative |
+|-------------|-------------|-------------------------|
+| [our choice] | [other option] | [conditions where alternative is better] |
+| [our choice] | [other option] | [conditions where alternative is better] |
+
+## What NOT to Use
+
+| Avoid | Why | Use Instead |
+|-------|-----|-------------|
+| [technology] | [specific problem] | [recommended alternative] |
+| [technology] | [specific problem] | [recommended alternative] |
+
+## Stack Patterns by Variant
+
+**If [condition]:**
+- Use [variation]
+- Because [reason]
+
+**If [condition]:**
+- Use [variation]
+- Because [reason]
+
+## Version Compatibility
+
+| Package A | Compatible With | Notes |
+|-----------|-----------------|-------|
+| [package@version] | [package@version] | [compatibility notes] |
+
+## Sources
+
+- [Context7 library ID] — [topics fetched]
+- [Official docs URL] — [what was verified]
+- [Other source] — [confidence level]
+
+---
+*Stack research for: [domain]*
+*Researched: [date]*
+```
+
+</template>
+
+<guidelines>
+
+**Core Technologies:**
+- Include specific version numbers
+- Explain why this is the standard choice, not just what it does
+- Focus on technologies that affect architecture decisions
+
+**Supporting Libraries:**
+- Include libraries commonly needed for this domain
+- Note when each is needed (not all projects need all libraries)
+
+**Alternatives:**
+- Don't just dismiss alternatives
+- Explain when alternatives make sense
+- Helps user make informed decisions if they disagree
+
+**What NOT to Use:**
+- Actively warn against outdated or problematic choices
+- Explain the specific problem, not just "it's old"
+- Provide the recommended alternative
+
+**Version Compatibility:**
+- Note any known compatibility issues
+- Critical for avoiding debugging time later
+
+</guidelines>

package/mindsystem/templates/research-project/SUMMARY.md

@@ -0,0 +1,170 @@
+# Research Summary Template
+
+Template for `.planning/research/SUMMARY.md` — executive summary of project research with roadmap implications.
+
+<template>
+
+```markdown
+# Project Research Summary
+
+**Project:** [name from PROJECT.md]
+**Domain:** [inferred domain type]
+**Researched:** [date]
+**Confidence:** [HIGH/MEDIUM/LOW]
+
+## Executive Summary
+
+[2-3 paragraph overview of research findings]
+
+- What type of product this is and how experts build it
+- The recommended approach based on research
+- Key risks and how to mitigate them
+
+## Key Findings
+
+### Recommended Stack
+
+[Summary from STACK.md — 1-2 paragraphs]
+
+**Core technologies:**
+- [Technology]: [purpose] — [why recommended]
+- [Technology]: [purpose] — [why recommended]
+- [Technology]: [purpose] — [why recommended]
+
+### Expected Features
+
+[Summary from FEATURES.md]
+
+**Must have (table stakes):**
+- [Feature] — users expect this
+- [Feature] — users expect this
+
+**Should have (competitive):**
+- [Feature] — differentiator
+- [Feature] — differentiator
+
+**Defer (v2+):**
+- [Feature] — not essential for launch
+
+### Architecture Approach
+
+[Summary from ARCHITECTURE.md — 1 paragraph]
+
+**Major components:**
+1. [Component] — [responsibility]
+2. [Component] — [responsibility]
+3. [Component] — [responsibility]
+
+### Critical Pitfalls
+
+[Top 3-5 from PITFALLS.md]
+
+1. **[Pitfall]** — [how to avoid]
+2. **[Pitfall]** — [how to avoid]
+3. **[Pitfall]** — [how to avoid]
+
+## Implications for Roadmap
+
+Based on research, suggested phase structure:
+
+### Phase 1: [Name]
+**Rationale:** [why this comes first based on research]
+**Delivers:** [what this phase produces]
+**Addresses:** [features from FEATURES.md]
+**Avoids:** [pitfall from PITFALLS.md]
+
+### Phase 2: [Name]
+**Rationale:** [why this order]
+**Delivers:** [what this phase produces]
+**Uses:** [stack elements from STACK.md]
+**Implements:** [architecture component]
+
+### Phase 3: [Name]
+**Rationale:** [why this order]
+**Delivers:** [what this phase produces]
+
+[Continue for suggested phases...]
+
+### Phase Ordering Rationale
+
+- [Why this order based on dependencies discovered]
+- [Why this grouping based on architecture patterns]
+- [How this avoids pitfalls from research]
+
+### Research Flags
+
+Phases likely needing deeper research during planning:
+- **Phase [X]:** [reason — e.g., "complex integration, needs API research"]
+- **Phase [Y]:** [reason — e.g., "niche domain, sparse documentation"]
+
+Phases with standard patterns (skip research-phase):
+- **Phase [X]:** [reason — e.g., "well-documented, established patterns"]
+
+## Confidence Assessment
+
+| Area | Confidence | Notes |
+|------|------------|-------|
+| Stack | [HIGH/MEDIUM/LOW] | [reason] |
+| Features | [HIGH/MEDIUM/LOW] | [reason] |
+| Architecture | [HIGH/MEDIUM/LOW] | [reason] |
+| Pitfalls | [HIGH/MEDIUM/LOW] | [reason] |
+
+**Overall confidence:** [HIGH/MEDIUM/LOW]
+
+### Gaps to Address
+
+[Any areas where research was inconclusive or needs validation during implementation]
+
+- [Gap]: [how to handle during planning/execution]
+- [Gap]: [how to handle during planning/execution]
+
+## Sources
+
+### Primary (HIGH confidence)
+- [Context7 library ID] — [topics]
+- [Official docs URL] — [what was checked]
+
+### Secondary (MEDIUM confidence)
+- [Source] — [finding]
+
+### Tertiary (LOW confidence)
+- [Source] — [finding, needs validation]
+
+---
+*Research completed: [date]*
+*Ready for roadmap: yes*
+```
+
+</template>
+
+<guidelines>
+
+**Executive Summary:**
+- Write for someone who will only read this section
+- Include the key recommendation and main risk
+- 2-3 paragraphs maximum
+
+**Key Findings:**
+- Summarize, don't duplicate full documents
+- Link to detailed docs (STACK.md, FEATURES.md, etc.)
+- Focus on what matters for roadmap decisions
+
+**Implications for Roadmap:**
+- This is the most important section
+- Directly informs create-roadmap workflow
+- Be explicit about phase suggestions and rationale
+- Include research flags for each suggested phase
+
+**Confidence Assessment:**
+- Be honest about uncertainty
+- Note gaps that need resolution during planning
+- HIGH = verified with official sources
+- MEDIUM = community consensus, multiple sources agree
+- LOW = single source or inference
+
+**Integration with create-roadmap:**
+- This file is loaded as @context in create-roadmap
+- Phase suggestions here become starting point for roadmap
+- Research flags inform detect_research_needs step
+
+</guidelines>