Initial commit

2025-11-30 09:03:24 +08:00
commit c431765352
13 changed files with 1442 additions and 0 deletions
--- a/commands/update-app-design.md
+++ b/commands/update-app-design.md
@@ -0,0 +1,302 @@
+---
+allowed-tools: Read, Glob, Grep, Write, MultiEdit, TodoWrite, Bash
+description: Update existing app design document based on codebase changes and project evolution
+---
+
+# Sync Application Design Document
+
+**User Request:** $ARGUMENTS
+
+## Context
+
+- Project root: !`pwd`
+- Package.json: @package.json
+- Current design doc: @.claude/rules/1-app-design-document.mdc
+- Last modified: !`stat -f "%Sm" .claude/rules/1-app-design-document.mdc 2>/dev/null || echo "No existing document"`
+
+## Goal
+
+Update the existing Application Design Document to reflect current codebase state, new features, changed priorities, and project evolution. Maintain consistency with the original document while incorporating new information.
+
+## Process
+
+### 1. Document Analysis
+
+- Read and understand the existing 1-app-design-document.mdc
+- Establish baseline understanding of documented features
+- Note the document's structure and tone
+- Identify areas that may need updates
+
+### 2. Codebase Change Detection
+
+**Think deeply about what has changed in the codebase since the document was last updated.**
+
+Analyze for:
+
+- **New Features:** Components, modules, or capabilities added
+- **Modified Flows:** Changes to user journeys or business logic
+- **Removed Features:** Deprecated or deleted functionality
+- **Architecture Evolution:** New patterns, services, or integrations
+- **Scale Changes:** Growth in complexity or user base
+- **Security Updates:** New authentication/authorization patterns
+
+_Extended thinking helps identify subtle changes, understand how new features integrate with existing ones, and recognize patterns that indicate architectural evolution._
+
+### 3. Interactive Update Session
+
+**CRITICAL:** Ask project stage question FIRST to assess if priorities have changed:
+
+- Use lettered/numbered options for easy response
+- Focus on what has changed and why
+- Gather context for accurate updates
+
+### 4. Update Project Configuration
+
+If project stage or priorities have changed:
+
+- Update `.claude/rules/3-project-status.mdc`
+- Adjust DO/DON'T lists for new priorities
+- Document any stage transitions
+
+### 5. Sync Document
+
+Update the document incrementally:
+
+- Preserve accurate existing content
+- Add new sections only when necessary
+- Update outdated information
+- Maintain consistent tone and structure
+
+### 6. Save Updated Document
+
+- Backup suggestion if major changes
+- Overwrite existing 1-app-design-document.mdc
+- Note what was updated
+
+## Required Questions Template
+
+### 🎯 CRITICAL: Project Evolution Assessment (Ask First!)
+
+**1. Has your project stage evolved since the last update?**
+
+a) **Same Stage** - Still in [current stage], just adding features  
+b) **Stage Evolution** - Moved from [current] to next stage  
+c) **Major Pivot** - Significant change in direction or purpose  
+d) **Help Me Assess** - Let's review current state together
+
+**2. Have your development priorities changed?**
+
+Based on your current stage, are these still your priorities?
+
+[Show current DO/DON'T lists from `.claude/rules/3-project-status.mdc`]
+
+a) **Same Priorities** - These still reflect our focus  
+b) **Adjusted Priorities** - Some changes needed (please specify)  
+c) **New Focus Areas** - Different priorities based on learnings  
+d) **Stage-Based Change** - Priorities changed due to stage evolution
+
+### 📊 Change Identification Questions
+
+**3. What major features have been added?**
+
+Please describe any significant new capabilities, modules, or user-facing features added since the last update.
+
+**4. Have any core user flows changed?**
+
+a) **Authentication/Authorization** - Login, permissions, security  
+b) **Main User Journey** - Primary application workflow  
+c) **Data Management** - How users create/edit/delete data  
+d) **Integration Points** - External service connections  
+e) **None/Minor Only** - No significant flow changes
+
+**5. What has been removed or deprecated?**
+
+List any features, integrations, or capabilities that have been removed or are being phased out.
+
+**6. Have you integrated new external services?**
+
+a) **Payment Processing** - Stripe, PayPal, etc.  
+b) **Communication** - Email, SMS, notifications  
+c) **Analytics/Monitoring** - Tracking, logging services  
+d) **AI/ML Services** - LLMs, image processing, etc.  
+e) **Other** - Please specify  
+f) **None** - No new integrations
+
+### 🚀 Future Direction Questions
+
+**7. How has user feedback influenced changes?**
+
+Describe any significant pivots or adjustments made based on user feedback or usage patterns.
+
+**8. What are your updated success metrics?**
+
+Have your KPIs or success measurements changed? Current focus:
+
+- User growth targets?
+- Revenue goals?
+- Engagement metrics?
+- Performance benchmarks?
+
+**9. What's the next major milestone?**
+
+a) **Feature Release** - Specific new capability  
+b) **Scale Milestone** - User/revenue target  
+c) **Technical Goal** - Performance, security, architecture  
+d) **Business Goal** - Partnerships, funding, market expansion
+
+## Update Strategy
+
+### Incremental Updates
+
+- **Preserve:** Keep accurate existing content
+- **Enhance:** Add new information to existing sections
+- **Replace:** Update outdated or incorrect information
+- **Remove:** Mark deprecated features appropriately
+
+### Change Documentation
+
+- **New Features:** Add to relevant feature categories
+- **Modified Flows:** Update user journey descriptions
+- **Architecture Changes:** Reflect in system architecture section
+- **Business Evolution:** Update goals and success metrics
+
+### Consistency Maintenance
+
+- Keep the same professional, accessible tone
+- Maintain technology-agnostic descriptions
+- Focus on WHAT not HOW
+- Preserve document structure
+
+## Document Update Areas
+
+### Always Review:
+
+1. **Introduction**
+
+   - Update if purpose or audience has shifted
+   - Reflect any pivot in value proposition
+
+2. **Core Features**
+
+   - Add new feature categories if needed
+   - Update existing features with enhancements
+   - Mark removed features as deprecated
+
+3. **User Experience**
+
+   - Update user journeys with new flows
+   - Add new user personas if applicable
+   - Reflect UI/UX improvements
+
+4. **System Architecture**
+
+   - Add new integrations
+   - Update data flow diagrams
+   - Reflect new security patterns
+
+5. **Business Logic**
+
+   - Update rules and workflows
+   - Reflect new validation requirements
+   - Document new business constraints
+
+6. **Future Considerations**
+   - Update roadmap based on progress
+   - Add new planned features
+   - Reflect lessons learned
+
+## Execution Steps
+
+### 1. Start with Analysis
+
+```bash
+# Check when document was last updated
+stat -f "%Sm" .claude/rules/1-app-design-document.mdc
+
+# Review recent commits for feature changes
+git log --oneline --since="30 days ago" | head -20
+```
+
+**Think deeply about:** "What has fundamentally changed in this application? How have new features altered the original vision? What patterns indicate architectural evolution?"
+
+### 2. Interactive Q&A
+
+- **MUST ASK PROJECT STAGE FIRST**
+- Present all questions clearly
+- Wait for complete responses
+
+### 3. Update Project Status (if needed)
+
+If stage or priorities changed, update both:
+
+```markdown
+# In `.claude/rules/3-project-status.mdc`
+
+## Project Status
+
+**Current Stage**: [New Stage]
+
+### DO Care About (Production-Ready Foundation)
+
+[Updated priorities]
+
+### DO NOT Care About (Skip for Velocity)
+
+[Updated items to skip]
+```
+
+### 4. Sync Document
+
+- Make targeted updates
+- Preserve document quality
+- Add version note if helpful:
+
+```markdown
+<!-- Last updated: [date] - Major changes: [summary] -->
+```
+
+### 5. Save and Backup
+
+```bash
+# Optional: Create backup
+cp .claude/rules/1-app-design-document.mdc .claude/rules/1-app-design-document.backup.mdc
+
+# Save updated document
+# Overwrite .claude/rules/1-app-design-document.mdc
+```
+
+## Key Principles
+
+### DO:
+
+- **Preserve Quality:** Maintain document's professional tone
+- **Incremental Updates:** Don't rewrite unnecessarily
+- **Clear Changes:** Make updates obvious and well-integrated
+- **User Focus:** Keep emphasis on user value
+- **Stage Awareness:** Align with current project maturity
+
+### DON'T:
+
+- **Complete Rewrite:** Unless fundamentally pivoted
+- **Technical Details:** Maintain high-level focus
+- **Break Structure:** Keep established organization
+- **Lose History:** Preserve context of major decisions
+- **Skip Analysis:** Always understand current state first
+
+## Output
+
+- **Format:** Markdown (`.mdc`)
+- **Location:** `.claude/rules/`
+- **Filename:** `1-app-design-document.mdc` (overwrites)
+- **Backup:** Suggest if major changes
+
+## Final Checklist
+
+1. ✅ Read existing document completely
+2. ✅ Analyze codebase changes thoroughly
+3. ✅ Ask project stage question FIRST
+4. ✅ Update `.claude/rules/3-project-status.mdc` if stage/priorities changed
+5. ✅ Make incremental, targeted updates
+6. ✅ Preserve document quality and tone
+7. ✅ Suggest backup for major changes
+8. ✅ Consider 2-tech-stack.mdc updates if needed