chore: initial backup of Claude Code configuration

Includes: CLAUDE.md, settings.json, agents, commands, rules, skills,
hooks, contexts, evals, get-shit-done, plugin configs (installed list
and marketplace sources). Excludes credentials, runtime caches,
telemetry, session data, and plugin binary cache.
This commit is contained in:
Yaojia Wang
2026-03-24 22:26:05 +01:00
commit 2876cca8fe
245 changed files with 54437 additions and 0 deletions

View File

@@ -0,0 +1,204 @@
# Architecture Research Template
Template for `.planning/research/ARCHITECTURE.md` — system structure patterns for the project domain.
<template>
```markdown
# Architecture Research
**Domain:** [domain type]
**Researched:** [date]
**Confidence:** [HIGH/MEDIUM/LOW]
## Standard Architecture
### System Overview
```
┌─────────────────────────────────────────────────────────────┐
│ [Layer Name] │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ [Comp] │ │ [Comp] │ │ [Comp] │ │ [Comp] │ │
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
│ │ │ │ │ │
├───────┴────────────┴────────────┴────────────┴──────────────┤
│ [Layer Name] │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────────────────────────────────────────────┐ │
│ │ [Component] │ │
│ └─────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ [Layer Name] │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ [Store] │ │ [Store] │ │ [Store] │ │
│ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### Component Responsibilities
| Component | Responsibility | Typical Implementation |
|-----------|----------------|------------------------|
| [name] | [what it owns] | [how it's usually built] |
| [name] | [what it owns] | [how it's usually built] |
| [name] | [what it owns] | [how it's usually built] |
## Recommended Project Structure
```
src/
├── [folder]/ # [purpose]
│ ├── [subfolder]/ # [purpose]
│ └── [file].ts # [purpose]
├── [folder]/ # [purpose]
│ ├── [subfolder]/ # [purpose]
│ └── [file].ts # [purpose]
├── [folder]/ # [purpose]
└── [folder]/ # [purpose]
```
### Structure Rationale
- **[folder]/:** [why organized this way]
- **[folder]/:** [why organized this way]
## Architectural Patterns
### Pattern 1: [Pattern Name]
**What:** [description]
**When to use:** [conditions]
**Trade-offs:** [pros and cons]
**Example:**
```typescript
// [Brief code example showing the pattern]
```
### Pattern 2: [Pattern Name]
**What:** [description]
**When to use:** [conditions]
**Trade-offs:** [pros and cons]
**Example:**
```typescript
// [Brief code example showing the pattern]
```
### Pattern 3: [Pattern Name]
**What:** [description]
**When to use:** [conditions]
**Trade-offs:** [pros and cons]
## Data Flow
### Request Flow
```
[User Action]
[Component] → [Handler] → [Service] → [Data Store]
↓ ↓ ↓ ↓
[Response] ← [Transform] ← [Query] ← [Database]
```
### State Management
```
[State Store]
↓ (subscribe)
[Components] ←→ [Actions] → [Reducers/Mutations] → [State Store]
```
### Key Data Flows
1. **[Flow name]:** [description of how data moves]
2. **[Flow name]:** [description of how data moves]
## Scaling Considerations
| Scale | Architecture Adjustments |
|-------|--------------------------|
| 0-1k users | [approach — usually monolith is fine] |
| 1k-100k users | [approach — what to optimize first] |
| 100k+ users | [approach — when to consider splitting] |
### Scaling Priorities
1. **First bottleneck:** [what breaks first, how to fix]
2. **Second bottleneck:** [what breaks next, how to fix]
## Anti-Patterns
### Anti-Pattern 1: [Name]
**What people do:** [the mistake]
**Why it's wrong:** [the problem it causes]
**Do this instead:** [the correct approach]
### Anti-Pattern 2: [Name]
**What people do:** [the mistake]
**Why it's wrong:** [the problem it causes]
**Do this instead:** [the correct approach]
## Integration Points
### External Services
| Service | Integration Pattern | Notes |
|---------|---------------------|-------|
| [service] | [how to connect] | [gotchas] |
| [service] | [how to connect] | [gotchas] |
### Internal Boundaries
| Boundary | Communication | Notes |
|----------|---------------|-------|
| [module A ↔ module B] | [API/events/direct] | [considerations] |
## Sources
- [Architecture references]
- [Official documentation]
- [Case studies]
---
*Architecture research for: [domain]*
*Researched: [date]*
```
</template>
<guidelines>
**System Overview:**
- Use ASCII box-drawing diagrams for clarity (├── └── │ ─ for structure visualization only)
- Show major components and their relationships
- Don't over-detail — this is conceptual, not implementation
**Project Structure:**
- Be specific about folder organization
- Explain the rationale for grouping
- Match conventions of the chosen stack
**Patterns:**
- Include code examples where helpful
- Explain trade-offs honestly
- Note when patterns are overkill for small projects
**Scaling Considerations:**
- Be realistic — most projects don't need to scale to millions
- Focus on "what breaks first" not theoretical limits
- Avoid premature optimization recommendations
**Anti-Patterns:**
- Specific to this domain
- Include what to do instead
- Helps prevent common mistakes during implementation
</guidelines>

View File

@@ -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>

View File

@@ -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>

View File

@@ -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>

View File

@@ -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 roadmap creation
- 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 roadmap creation:**
- This file is loaded as context during roadmap creation
- Phase suggestions here become starting point for roadmap
- Research flags inform phase planning
</guidelines>