@howlil/ez-agents 3.4.1 → 3.5.0

package/ez-agents/templates/research-project/PITFALLS.md

@@ -1,200 +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>
+# 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/ez-agents/templates/research-project/STACK.md

@@ -1,120 +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>
+# 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>