From abb1ee7e7105522a14c73790a506c0c3910c6956 Mon Sep 17 00:00:00 2001 From: "Paul.Kim" Date: Sun, 13 Jul 2025 20:18:27 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=EA=B8=B0=EB=B3=B8=20=ED=8C=8C=EC=9D=BC?= =?UTF-8?q?=20=EA=B5=AC=EC=A1=B0,=20.gitignore,=20CLAUDE.md,=20README.md,?= =?UTF-8?q?=20=EB=B0=8F=20=EC=9E=91=EC=97=85=20=EA=B4=80=EB=A6=AC=20?= =?UTF-8?q?=EC=8B=9C=EC=8A=A4=ED=85=9C=EC=9D=84=20=EC=9C=84=ED=95=9C=20?= =?UTF-8?q?=EC=84=A4=EC=A0=95=20=ED=8C=8C=EC=9D=BC=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .claude/commands/debug.md | 8 + .claude/commands/docs/create-app-design.md | 282 +++++++++ .claude/commands/docs/create-doc.md | 51 ++ .../commands/docs/create-prd-interactive.md | 116 ++++ .claude/commands/docs/create-prd.md | 114 ++++ .claude/commands/docs/create-rule.md | 260 ++++++++ .claude/commands/docs/create-tech-stack.md | 346 +++++++++++ .claude/commands/docs/parse-prd.md | 181 ++++++ .claude/commands/docs/update-app-design.md | 303 +++++++++ .../commands/docs/update-project-structure.md | 14 + .claude/commands/docs/update-rule.md | 313 ++++++++++ .claude/commands/docs/update-tech-stack.md | 327 ++++++++++ .claude/commands/research/architecture.md | 33 + .claude/commands/research/security.md | 34 + .claude/commands/research/task.md | 32 + .claude/commands/research/tech.md | 31 + .claude/commands/snippets/create-snippet.md | 32 + .claude/commands/task/add-interactive.md | 59 ++ .claude/commands/task/add.md | 65 ++ .claude/commands/task/done.md | 21 + .claude/commands/task/expand.md | 21 + .claude/commands/task/list.md | 21 + .claude/commands/task/move.md | 21 + .claude/commands/task/next.md | 18 + .claude/commands/task/research.md | 32 + .claude/commands/task/show.md | 20 + .claude/commands/task/spec.md | 77 +++ .../commands/task/update-task-interactive.md | 59 ++ .claude/commands/task/update-task.md | 30 + .claude/scripts/tree.sh | 70 +++ .claude/settings.json | 13 + .cursor/mcp.json | 10 + .cursor/rules/cursor-rules.mdc | 54 ++ .cursor/rules/project-status.mdc | 145 +++++ .cursor/rules/self-improve.mdc | 73 +++ .cursor/rules/taskmaster/dev-workflow.mdc | 489 +++++++++++++++ .cursor/rules/taskmaster/taskmaster.mdc | 172 +++++ .git-commit-template.txt | 20 + .gitignore | 27 + .taskmaster/config.json | 32 + .taskmaster/docs/app-design-document.md | 0 .taskmaster/docs/project-structure.md | 75 +++ .taskmaster/docs/taskmaster-guide.md | 588 ++++++++++++++++++ .taskmaster/docs/tech-stack.md | 0 .taskmaster/reports/.gitkeep | 0 .taskmaster/state.json | 6 + .taskmaster/tasks/tasks.json | 18 + .taskmaster/templates/example_prd.md | 77 +++ CLAUDE.md | 134 ++++ README.md | 238 ++++++- 50 files changed, 5161 insertions(+), 1 deletion(-) create mode 100644 .claude/commands/debug.md create mode 100644 .claude/commands/docs/create-app-design.md create mode 100644 .claude/commands/docs/create-doc.md create mode 100644 .claude/commands/docs/create-prd-interactive.md create mode 100644 .claude/commands/docs/create-prd.md create mode 100644 .claude/commands/docs/create-rule.md create mode 100644 .claude/commands/docs/create-tech-stack.md create mode 100644 .claude/commands/docs/parse-prd.md create mode 100644 .claude/commands/docs/update-app-design.md create mode 100644 .claude/commands/docs/update-project-structure.md create mode 100644 .claude/commands/docs/update-rule.md create mode 100644 .claude/commands/docs/update-tech-stack.md create mode 100644 .claude/commands/research/architecture.md create mode 100644 .claude/commands/research/security.md create mode 100644 .claude/commands/research/task.md create mode 100644 .claude/commands/research/tech.md create mode 100644 .claude/commands/snippets/create-snippet.md create mode 100644 .claude/commands/task/add-interactive.md create mode 100644 .claude/commands/task/add.md create mode 100644 .claude/commands/task/done.md create mode 100644 .claude/commands/task/expand.md create mode 100644 .claude/commands/task/list.md create mode 100644 .claude/commands/task/move.md create mode 100644 .claude/commands/task/next.md create mode 100644 .claude/commands/task/research.md create mode 100644 .claude/commands/task/show.md create mode 100644 .claude/commands/task/spec.md create mode 100644 .claude/commands/task/update-task-interactive.md create mode 100644 .claude/commands/task/update-task.md create mode 100644 .claude/scripts/tree.sh create mode 100644 .claude/settings.json create mode 100644 .cursor/mcp.json create mode 100644 .cursor/rules/cursor-rules.mdc create mode 100644 .cursor/rules/project-status.mdc create mode 100644 .cursor/rules/self-improve.mdc create mode 100644 .cursor/rules/taskmaster/dev-workflow.mdc create mode 100644 .cursor/rules/taskmaster/taskmaster.mdc create mode 100644 .git-commit-template.txt create mode 100644 .gitignore create mode 100644 .taskmaster/config.json create mode 100644 .taskmaster/docs/app-design-document.md create mode 100644 .taskmaster/docs/project-structure.md create mode 100644 .taskmaster/docs/taskmaster-guide.md create mode 100644 .taskmaster/docs/tech-stack.md create mode 100644 .taskmaster/reports/.gitkeep create mode 100644 .taskmaster/state.json create mode 100644 .taskmaster/tasks/tasks.json create mode 100644 .taskmaster/templates/example_prd.md create mode 100644 CLAUDE.md diff --git a/.claude/commands/debug.md b/.claude/commands/debug.md new file mode 100644 index 0000000..9cb7e59 --- /dev/null +++ b/.claude/commands/debug.md @@ -0,0 +1,8 @@ +1. Reflect on 5-7 different possible sources of the problem +2. Distill those down to 1-2 most likely sources +3. Add additional logs to validate your assumptions and track the transformation of data structures throughout the application control flow before we move onto implementing the actual code fix +4. Use the "getConsoleLogs", "getConsoleErrors", "getNetworkLogs" & "getNetworkErrors" tools to obtain any newly added web browser logs +5. Obtain the server logs as well if accessible - otherwise, ask me to copy/paste them into the chat +6. Deeply reflect on what could be wrong + produce a comprehensive analysis of the issue +7. Suggest additional logs if the issue persists or if the source is not yet clear +8. Once a fix is implemented, ask for approval to remove the previously added logs diff --git a/.claude/commands/docs/create-app-design.md b/.claude/commands/docs/create-app-design.md new file mode 100644 index 0000000..c92842e --- /dev/null +++ b/.claude/commands/docs/create-app-design.md @@ -0,0 +1,282 @@ +--- +allowed-tools: Read, Glob, Grep, Write, MultiEdit, TodoWrite +description: Generate comprehensive app design document with project stage assessment +--- + +# Generate Application Design Document + +**User Request:** $ARGUMENTS + +## Context + +- Project root: !`pwd` +- Package.json: @package.json +- Existing design docs: !`ls -la .taskmaster/docs/ 2>/dev/null || echo "No .taskmaster/docs directory yet"` + +## Goal + +Create a comprehensive Application Design Document based on deep codebase analysis and user input. The document provides a high-level overview of the application's architecture, core features, user experience, and business logic while remaining technology-agnostic and focused on the "what" rather than the "how". + +## Process + +### 1. Initial Analysis + +- Analyze project structure and existing codebase +- Review package.json for project name and dependencies +- Check for existing documentation in .taskmaster/docs/ +- Identify key application features and patterns +- **Think deeply** about the application's purpose and architecture + +### 2. Codebase Deep Dive + +**Think harder about the application's architecture and business logic.** + +Analyze the codebase to understand: + +- **Application Structure:** Main modules, features, and components +- **User Flows:** Authentication, navigation, key user journeys +- **Data Models:** Conceptual relationships and entities +- **Business Logic:** Core rules, workflows, and processes +- **Integrations:** External services and APIs +- **Security Patterns:** Authentication and authorization approaches + +_Extended thinking helps identify non-obvious patterns, understand complex business rules from code, and make strategic decisions about what aspects are most important to document._ + +### 3. Interactive Q&A Session + +**CRITICAL:** Ask project stage question FIRST, then 4-7 additional questions: + +- Use lettered/numbered options for easy response +- Focus on business goals and user needs +- Gather context for proper documentation + +### 4. Update Project Configuration + +Based on project stage response: + +- Update `CLAUDE.md` "Project Status" section +- Set appropriate DO/DON'T priorities for the stage +- Document stage-specific development guidelines + +### 5. Generate Document + +Create comprehensive app design document following the standard structure + +### 6. Save and Organize + +- Create `.taskmaster/docs/` directory if needed +- Save as `app-design-document.md` +- Suggest next steps (tech stack doc, PRD, etc.) + +## Required Questions Template + +### 🎯 CRITICAL: Project Stage Assessment (Ask First!) + +**1. What stage is your application currently in?** + +a) **Pre-MVP** - Building initial version, not deployed to production yet + b) **MVP** - Basic version deployed and live with early users + c) **Production** - Mature application with established user base + d) **Enterprise** - Large scale deployment, multiple teams involved + +**2. Based on your selected stage, here are the development priorities:** + +- **Pre-MVP Priorities:** + + - βœ… DO: Core functionality, security basics, input validation, working features + - ❌ DON'T: Unit tests, performance optimization, accessibility polish, perfect code + - πŸš€ Focus: Ship fast with security, iterate based on feedback + +- **MVP Priorities:** + + - βœ… DO: Critical path testing, basic monitoring, user feedback loops + - ❌ DON'T: Comprehensive test coverage, advanced patterns, premature optimization + - πŸš€ Focus: Stability for early users, rapid iteration + +- **Production Priorities:** + + - βœ… DO: Testing, monitoring, performance, accessibility, documentation + - ❌ DON'T: Skip security reviews, ignore technical debt + - πŸš€ Focus: Reliability, scalability, user experience + +- **Enterprise Priorities:** + - βœ… DO: Comprehensive testing, security audits, team coordination, compliance + - ❌ DON'T: Skip documentation, ignore code standards + - πŸš€ Focus: Team efficiency, maintainability, compliance + +### πŸ“‹ Context-Specific Questions (Ask 4-7 based on analysis) + +**3. Application Purpose & Users** + +- What is the primary problem your application solves? +- Who are your target users and what are their main goals? + +**4. Unique Value Proposition** + +- What makes your application unique compared to existing solutions? +- What's your competitive advantage? + +**5. User Roles & Permissions** + +- What different types of users interact with your system? +- Examples: end users, admins, moderators, content creators, viewers + +**6. Core User Journeys** + +- What are the 2-3 most critical user flows? +- Example: Sign up β†’ Create content β†’ Share β†’ Get feedback + +**7. Business Model & Growth** + +- How does this application generate value? +- Options: SaaS subscription, marketplace, freemium, advertising, one-time purchase + +**8. Integration Ecosystem** + +- What external services must you integrate with? +- Examples: payment processors, email services, analytics, social platforms + +**9. Scale & Performance Goals** + +- What scale are you planning for in the next 12 months? +- Users: dozens, hundreds, thousands, millions? +- Geographic: local, national, global? + +**10. Success Metrics** + +- How will you measure if your application is successful? +- Examples: user retention, revenue, engagement, conversion rates + +## Document Structure + +The generated document must follow this high-level structure: + +### **Introduction** + +- Application overview and purpose +- Target audience and user base +- Core value proposition +- Business context and goals + +### **Core Features** + +- **Feature Category 1:** (e.g., User Management) + - Purpose and user benefit + - Key functionalities + - User experience considerations +- **Feature Category 2:** (e.g., Content Creation) + - Purpose and user benefit + - Key functionalities + - User experience considerations +- **[Additional feature categories as needed]** + +### **User Experience** + +- User personas and roles +- Key user journeys and flows +- Interface design principles +- Accessibility and usability considerations + +### **System Architecture** + +- High-level system components +- Data flow and relationships +- Integration points and external services +- Security and privacy approach + +### **Business Logic** + +- Core business rules and processes +- Data models and relationships (conceptual) +- Workflow and state management +- Validation and business constraints + +### **Future Considerations** + +- Planned enhancements and features +- Scalability considerations +- Potential integrations +- Long-term vision and roadmap + +## Target Audience + +The document should be accessible to: + +- **Business stakeholders** who need to understand the application's purpose and capabilities +- **Product managers** planning features and roadmaps +- **Designers** creating user interfaces and experiences +- **New developers** joining the project who need a high-level understanding +- **Technical leaders** making architectural decisions + +The language should be clear, business-focused, and avoid technical implementation details. + +## Writing Principles + +### DO: + +- **Business Focus:** Describe WHAT the application does, not HOW +- **User Value:** Emphasize benefits and outcomes for users +- **Clear Language:** Write for non-technical stakeholders +- **Visual Thinking:** Use diagrams and flows where helpful +- **Future Ready:** Consider growth and evolution paths + +### DON'T: + +- **Technical Details:** No code snippets or implementation specifics +- **Technology Stack:** Save for tech-stack.md document +- **Database Schemas:** Keep data models conceptual +- **API Specifications:** Focus on capabilities, not endpoints +- **Performance Metrics:** Describe goals, not technical benchmarks + +## Output + +- **Format:** Markdown (`.md`) +- **Location:** `.taskmaster/docs/` +- **Filename:** `app-design-document.md` + +## Execution Steps + +### 1. Start with Analysis + +- Use Read, Glob, and Grep to explore the codebase +- Identify key features and patterns +- Look for existing documentation +- **Use extended thinking:** "Think deeply about this codebase's architecture, business purpose, and how different components work together to serve users" + +### 2. Interactive Q&A + +- **MUST ASK PROJECT STAGE FIRST** +- Present questions with numbered/lettered options +- Wait for user responses before proceeding + +### 3. Update Project Status + +```markdown +## Project Status + +**Current Stage**: [Stage from user response] + +### DO Care About (Production-Ready Foundation) + +[Stage-specific priorities] + +### DO NOT Care About (Skip for Velocity) + +[Stage-specific items to skip] + +### Development Approach + +[Stage-specific development focus] +``` + +### 4. Generate Document + +- Follow the standard structure +- Tailor content to project stage +- Keep language accessible + +### 5. Save and Next Steps + +- Create directory: `mkdir -p .taskmaster/docs` +- Save document: `.taskmaster/docs/app-design-document.md` +- Suggest: "Would you like me to create a technical stack document next?" diff --git a/.claude/commands/docs/create-doc.md b/.claude/commands/docs/create-doc.md new file mode 100644 index 0000000..016b683 --- /dev/null +++ b/.claude/commands/docs/create-doc.md @@ -0,0 +1,51 @@ +# Feature Documentation Generator + +When asked to enter "Documentation Mode" for a specific feature, I will: + +1. **Analyze the feature scope**: First, I'll ask 3-5 clarifying questions to understand exactly what feature needs to be documented and its boundaries. + +2. **Review existing documentation**: Before generating new documentation, I'll check and reference these existing guides: + + - Authentication patterns β†’ @.cursor/rules/2106-auth.mdc + - CRUD implementation β†’ @.cursor/rules/2105-crud.mdc + - Router implementation β†’ @.cursor/rules/2102-router.mdc + - Schema definition β†’ @.cursor/rules/2101-schema-prisma.mdc + - End-to-end feature specs β†’ @.cursor/rules/2100-spec.mdc + - tRPC React Query integration β†’ @.cursor/rules/2103-trpc-react-query.mdc + +3. **Conduct comprehensive codebase exploration**: I'll systematically search for and identify all relevant files and components that contribute to the feature, including: + + - Entry points and main components + - State management + - API interactions + - Utility functions + - Types and interfaces + - Configuration files + +4. **Generate a structured documentation** with these sections: + + - **Feature Overview**: High-level description of the feature's purpose and functionality + - **Core Files Map**: List of essential files with their paths and a brief description of their role + - **Data Flow**: How data moves through the system for this feature + - **Key Dependencies**: External libraries or internal services the feature relies on + - **Configuration Options**: Any configurable aspects of the feature + - **Extension Points**: How the feature can be extended or customized + - **Implementation References**: Links to relevant sections in existing documentation that were used or should be followed + +5. **Include code snippets** for critical sections with line numbers and file paths in the format: + + ```startLine:endLine:filepath + // Code snippet here + ``` + +6. **Create a visual representation** of the component hierarchy or data flow if applicable (described in text format that can be converted to a diagram). + +7. **Summarize implementation patterns** used in the feature that should be followed when extending it, referencing existing documentation where applicable: + - Authentication patterns if the feature requires protection + - CRUD patterns if the feature involves data operations + - Error handling patterns + - Router implementation patterns + - Schema patterns + - React Query patterns + +The final documentation will be comprehensive enough that someone could continue development on this feature with minimal additional context beyond the generated document and the referenced existing documentation. diff --git a/.claude/commands/docs/create-prd-interactive.md b/.claude/commands/docs/create-prd-interactive.md new file mode 100644 index 0000000..319ad31 --- /dev/null +++ b/.claude/commands/docs/create-prd-interactive.md @@ -0,0 +1,116 @@ +--- +allowed-tools: Bash, Read, Write, Glob, Grep, Task, TodoWrite, mcp__taskmaster-ai__parse_prd +description: Generate a PRD interactively with clarifying questions for complex features +--- + +# Generate a Product Requirements Document (PRD) + +## Context + +- **User Request:** $ARGUMENTS +- **Project Root:** !`pwd` +- **Existing PRDs:** !`ls -la .taskmaster/docs/prd-*.md 2>/dev/null || echo "No existing PRDs found"` +- **Project Status:** @CLAUDE.md#project-status +- **Tech Stack:** @.taskmaster/docs/tech-stack.md +- **Project Structure:** !`bash .claude/scripts/tree.sh` +- **PRD Template:** @.taskmaster/templates/example_prd.md + +## Goal + +To create a detailed Product Requirements Document (PRD) in Markdown format. The PRD should be clear, actionable, and suitable for a junior developer to understand and implement. + +## Process + +1. **Analyze Feature Request:** Think deeply about the user's feature request and its implications for the codebase. + +2. **Codebase Analysis:** + + - Search for relevant existing code patterns + - Review components that might be affected + - Identify potential integration points + - Consider architectural impacts + +3. **Ask Clarifying Questions:** + + - Ask 4-6 targeted questions based on codebase analysis + - Provide lettered/numbered options for easy response + - Focus on understanding the "what" and "why", not the "how" + +4. **Generate PRD:** + + - Follow the example PRD structure exactly + - Include all required sections from the template + - Ensure clarity for junior developers + +5. **Save and Next Steps:** + - Save as `prd-[feature-name].md` in `.taskmaster/docs/` + - Suggest running Task Master parse command + +## Clarifying Questions Framework + +Adapt questions based on the specific feature request provided above. Consider these areas: + +- **Problem/Goal:** "What problem does this feature solve for the user?" or "What is the main goal we want to achieve with this feature?" +- **Target User:** "Who is the primary user of this feature?" +- **Core Functionality:** "Can you describe the key actions a user should be able to perform with this feature?" +- **User Stories:** "Could you provide a few user stories? (e.g., As a [type of user], I want to [perform an action] so that [benefit].)" +- **User Experience:** "Describe the user journey and key user flows for this feature" +- **Scope/Boundaries:** "Are there any specific things this feature _should not_ do (non-goals)?" +- **Technical Integration:** "What existing systems or components should this integrate with?" +- **Data Requirements:** "What kind of data does this feature need to display or manipulate?" +- **Design/UI:** "Are there any existing design patterns or UI guidelines to follow?" or "Can you describe the desired look and feel?" +- **Development Phases:** "Should this be built in phases? What's the MVP vs future enhancements?" +- **Dependencies:** "What needs to be built first? Are there logical dependencies?" +- **Success Criteria:** "How will we know when this feature is successfully implemented?" +- **Edge Cases:** "Are there any potential risks or technical challenges we should consider?" + +## PRD Structure Requirements + +The PRD must follow the exact structure from @.taskmaster/templates/example_prd.md: + +### `` Section + +1. **Overview:** High-level overview of the product/feature, what problem it solves, who it's for, and why it's valuable +2. **Project Context:** Include the standard project status information. CRITICIAL: DO NOT forget this section. Read the mentioned files if needed. +3. **Core Features:** List and describe the main features, including what each does, why it's important, and how it works at a high level +4. **User Experience:** Describe user personas, key user flows, and UI/UX considerations + +### `` Section + +1. **Technical Architecture:** System components, data models, APIs and integrations, infrastructure requirements +2. **Development Roadmap:** Break down into phases (MVP requirements, future enhancements) focusing on scope and detailing exactly what needs to be built +3. **Logical Dependency Chain:** Define the logical order of development, which features need to be built first, getting quickly to something usable/visible, properly pacing and scoping each feature +4. **Risks and Mitigations:** Technical challenges, figuring out the MVP that can be built upon, resource constraints +5. **Appendix:** Research findings, technical specifications, additional information + +## Target Audience + +Assume the primary reader of the PRD is a **junior developer**. Therefore, requirements should be explicit, unambiguous, and avoid jargon where possible. Provide enough detail for them to understand the feature's purpose and core logic. + +## Output + +- **Format:** Markdown (`.md`) +- **Location:** `.taskmaster/docs/` +- **Filename:** `prd-[feature-name].md` + +## Final Instructions + +1. **Think deeply** about the feature request and its architectural implications +2. **Do NOT start implementing** - only create the PRD document +3. **Ask clarifying questions** with lettered/numbered options +4. **Generate complete PRD** following the template structure exactly +5. **Save the PRD** to `.taskmaster/docs/prd-[feature-name].md` +6. **Suggest next step:** "Use `/parse` or `task-master parse-prd .taskmaster/docs/prd-[feature-name].md` to convert this PRD into Task Master tasks" + +## Example Usage + +``` +/project:prd user authentication system +``` + +This will: + +1. Analyze the codebase for existing auth patterns +2. Ask questions about auth requirements +3. Generate a comprehensive PRD +4. Save it as `prd-user-authentication.md` diff --git a/.claude/commands/docs/create-prd.md b/.claude/commands/docs/create-prd.md new file mode 100644 index 0000000..806b9e5 --- /dev/null +++ b/.claude/commands/docs/create-prd.md @@ -0,0 +1,114 @@ +--- +allowed-tools: Bash, Read, Write, Glob, Grep, Task, TodoWrite, mcp__taskmaster-ai__parse_prd +description: Generate a PRD directly without questions for simple, well-defined features +--- + +# Generate a Quick Product Requirements Document (PRD) + +## Context + +- **User Request:** $ARGUMENTS +- **Project Root:** !`pwd` +- **Existing PRDs:** !`ls -la .taskmaster/docs/prd-*.md 2>/dev/null || echo "No existing PRDs found"` +- **Project Status:** @CLAUDE.md#project-status +- **Project Structure:** !`bash .claude/scripts/tree.sh` +- **Tech Stack:** @.taskmaster/docs/tech-stack.md +- **PRD Template:** @.taskmaster/templates/example_prd.md + +## Goal + +To quickly create a Product Requirements Document (PRD) without asking clarifying questions. Best suited for simple, well-defined features where requirements are clear. + +## Process + +1. **Analyze Feature Request:** + + - Think deeply about the user's feature request + - Make reasonable assumptions based on common patterns + - Review existing codebase for context + +2. **Codebase Analysis:** + + - Search for relevant existing code patterns + - Review components that might be affected + - Identify potential integration points + - Consider architectural impacts + +3. **Generate PRD Immediately:** + + - Follow the example PRD structure exactly + - Include all required sections from the template + - Make reasonable assumptions for unclear requirements + - Document assumptions clearly in the PRD + +4. **Save and Next Steps:** + - Save as `prd-[feature-name].md` in `.taskmaster/docs/` + - Suggest running Task Master parse command + +## PRD Structure Requirements + +The PRD must follow the exact structure from @.taskmaster/templates/example_prd.md: + +### `` Section + +1. **Overview:** High-level overview of the product/feature, what problem it solves, who it's for, and why it's valuable +2. **Project Context:** Include the standard project status information. CRITICAL: DO NOT forget this section. Read the mentioned files if needed. +3. **Core Features:** List and describe the main features, including what each does, why it's important, and how it works at a high level +4. **User Experience:** Describe user personas, key user flows, and UI/UX considerations + +### `` Section + +1. **Technical Architecture:** System components, data models, APIs and integrations, infrastructure requirements +2. **Development Roadmap:** Break down into phases (MVP requirements, future enhancements) focusing on scope and detailing exactly what needs to be built +3. **Logical Dependency Chain:** Define the logical order of development, which features need to be built first, getting quickly to something usable/visible, properly pacing and scoping each feature +4. **Risks and Mitigations:** Technical challenges, figuring out the MVP that can be built upon, resource constraints +5. **Appendix:** Research findings, technical specifications, additional information + +## Assumptions Section + +When using quick mode, include an "Assumptions" section at the beginning of the PRD documenting: + +- Key assumptions made about requirements +- Default choices for ambiguous features +- Suggested areas that may need refinement + +## Final Instructions + +1. **Think deeply** about the feature request and make intelligent assumptions +2. **Do NOT ask questions** - proceed directly to PRD generation +3. **Document assumptions** clearly in the PRD +4. **Generate complete PRD** following the template structure exactly +5. **Save the PRD** to `.taskmaster/docs/prd-[feature-name].md` +6. **Suggest next step:** "Use `/parse` or `task-master parse-prd .taskmaster/docs/prd-[feature-name].md` to convert this PRD into Task Master tasks" + +## Example Usage + +``` +/project:prd-quick user profile page with avatar upload +``` + +This will: + +1. Analyze the codebase for existing user/profile patterns +2. Make assumptions about profile fields and avatar requirements +3. Generate a comprehensive PRD immediately +4. Save it as `prd-user-profile-page.md` +5. Document all assumptions made + +## When to Use Quick Mode + +βœ… **Good for:** + +- Simple CRUD features +- Standard UI components +- Well-defined integrations +- Features with clear precedent in codebase + +❌ **Avoid for:** + +- Complex architectural changes +- Features with many unknowns +- Security-critical features +- Features affecting multiple systems + +For complex features, use `/project:prd` for the full interactive process. diff --git a/.claude/commands/docs/create-rule.md b/.claude/commands/docs/create-rule.md new file mode 100644 index 0000000..582dfae --- /dev/null +++ b/.claude/commands/docs/create-rule.md @@ -0,0 +1,260 @@ +--- +allowed-tools: Read, Glob, Grep, Write, MultiEdit, TodoWrite, Bash +description: Create a new Cursor rule file with proper structure and conventions +--- + +# Create Cursor Rule + +**User Request:** $ARGUMENTS + +## Context + +- Rules directory: !`ls -la .cursor/rules/*.mdc 2>/dev/null | wc -l | xargs -I {} echo "{} existing rules"` +- Existing rules: !`ls -1 .cursor/rules/*.mdc 2>/dev/null | sed 's/.*\///' | head -10 || echo "No rules yet"` +- Rule guidelines: @.cursor/rules/cursor-rules.mdc + +## Goal + +Create a new Cursor rule file that follows the established conventions and structure. The rule should be actionable, well-documented, and reference actual code patterns from the codebase. + +## Process + +### 1. Analyze Rule Request + +**Think deeply about what patterns or conventions this rule should enforce.** + +Consider: + +- What problem does this rule solve? +- What patterns should it enforce? +- What anti-patterns should it prevent? +- Which files or areas of code does it apply to? +- Are there existing examples in the codebase? + +### 2. Search for Patterns + +Search the codebase for: + +- Existing implementations to reference +- Common patterns that need standardization +- Anti-patterns to discourage +- Related code that demonstrates the rule + +### 3. Interactive Rule Design + +Ask clarifying questions about: + +- Specific file patterns (globs) +- When the rule should apply +- Exceptions or edge cases +- Related existing rules + +### 4. Generate Rule File + +Create comprehensive rule following the standard structure: + +- YAML frontmatter +- Clear description +- Actionable requirements +- Code examples +- File references + +### 5. Save and Cross-Reference + +- Save to `.cursor/rules/[rule-name].mdc` +- Update related rules if needed +- Update CLAUDE.md to reference new rule in Core Rules section +- Suggest next steps + +## Rule Creation Questions + +### πŸ“‹ Rule Definition + +**1. What is the primary purpose of this rule?** + +Please describe what convention, pattern, or standard this rule should enforce. + +**2. Which files should this rule apply to?** + +a) **Specific file types** - `*.ts`, `*.tsx`, etc. +b) **Directory patterns** - `src/components/**/*`, `app/**/*` +c) **Framework files** - Route handlers, API endpoints, etc. +d) **Configuration files** - `*.config.ts`, setup files +e) **All files** - Universal convention + +**3. Should this rule always apply or conditionally?** + +a) **Always apply** - Enforced on every matching file +b) **Conditional** - Only when certain patterns exist +c) **Opt-in** - Developers choose when to apply + +### πŸ” Pattern Examples + +**4. Can you provide examples of GOOD patterns to follow?** + +Share code snippets or describe the correct implementation. + +**5. What are BAD patterns to avoid?** + +Share anti-patterns or common mistakes this rule should prevent. + +**6. Are there existing files that demonstrate this pattern well?** + +List files that already follow this convention correctly. + +### πŸ”— Related Rules + +**7. Does this rule relate to any existing conventions?** + +a) **Extends existing rule** - Builds on another rule +b) **Complements rule** - Works alongside another +c) **Replaces rule** - Supersedes an outdated rule +d) **Standalone** - Independent convention + +## Rule Structure Template + +````markdown +--- +description: [Clear, one-line description of what the rule enforces] +globs: [path/to/files/*.ext, other/path/**/*] +alwaysApply: [true/false] +--- + +# [Rule Title] + +## Overview + +[Brief explanation of why this rule exists and what problem it solves] + +## Requirements + +- **[Requirement Category]:** + - [Specific requirement] + - [Another requirement] + - [Edge cases or exceptions] + +## Examples + +### βœ… DO: [Good Pattern Name] + +```[language] +// Example of correct implementation +[code example] +``` +```` + +**Why:** [Explanation of why this is the right approach] + +### ❌ DON'T: [Anti-pattern Name] + +```[language] +// Example of what to avoid +[code example] +``` + +**Why:** [Explanation of why this should be avoided] + +## File References + +- Good examples: [component.tsx](mdc:src/components/example/component.tsx) +- Pattern usage: [api-handler.ts](mdc:app/api/example/route.ts) + +## Related Rules + +- [other-rule.mdc](mdc:.cursor/rules/other-rule.mdc) - [How it relates] +- [another-rule.mdc](mdc:.cursor/rules/another-rule.mdc) - [How it relates] + +## Migration Guide + +[If applicable, how to migrate existing code to follow this rule] + +1. [Step 1] +2. [Step 2] +3. [Step 3] + +```` + +## Execution Steps + +### 1. Initial Analysis + +```bash +# Search for relevant patterns +rg -t ts -t tsx "[pattern]" --glob "!node_modules" + +# Find files that might need this rule +find . -name "*.tsx" -path "*/components/*" | head -20 +```` + +**Think deeply about:** "What patterns in the codebase would benefit from standardization? What mistakes do developers commonly make that this rule could prevent?" + +### 2. Pattern Discovery + +- Use Grep to find existing patterns +- Use Read to examine good examples +- Identify variations that need standardization + +### 3. Interactive Design + +- Ask clarifying questions +- Get specific examples +- Understand edge cases + +### 4. Rule Generation + +- Follow the template structure +- Include real code examples +- Reference actual files +- Connect to related rules + +### 5. Save and Integrate + +```bash +# Create rule file +# Save to .cursor/rules/[rule-name].mdc + +# Show related rules +ls -la .cursor/rules/*.mdc | grep -E "(related|similar)" +``` + +## Best Practices + +### DO: + +- **Real Examples:** Use actual code from the project +- **Clear Globs:** Specific file patterns, not overly broad +- **Actionable:** Developers should know exactly what to do +- **Justification:** Explain WHY not just WHAT +- **Cross-Reference:** Link to related rules and examples + +### DON'T: + +- **Theoretical:** Avoid hypothetical examples +- **Vague:** Don't use unclear descriptions +- **Overly Broad:** Don't apply to all files unless necessary +- **Redundant:** Don't duplicate existing rules +- **Complex:** Keep rules focused on one concept + +## Output + +- **Format:** Markdown with `.mdc` extension +- **Location:** `.cursor/rules/` +- **Filename:** `[descriptive-name].mdc` + +## Example Usage + +``` +/project:rules:create component naming conventions + +/project:rules:create API error handling patterns +``` + +## Next Steps + +After creating the rule: + +1. Review existing code for compliance +2. Update non-compliant code if needed +3. Add to code review checklist +4. Update CLAUDE.md Core Rules section to reference the new rule +5. Share with team diff --git a/.claude/commands/docs/create-tech-stack.md b/.claude/commands/docs/create-tech-stack.md new file mode 100644 index 0000000..9a36141 --- /dev/null +++ b/.claude/commands/docs/create-tech-stack.md @@ -0,0 +1,346 @@ +--- +allowed-tools: Read, Glob, Grep, Write, MultiEdit, TodoWrite, Bash +description: Generate comprehensive technical stack documentation from codebase analysis +--- + +# Generate Tech Stack Documentation + +**User Request:** $ARGUMENTS + +## Context + +- Project root: !`pwd` +- Package.json: @package.json +- Node version: !`node --version 2>/dev/null || echo "Node.js not found"` +- TypeScript config: @tsconfig.json +- Database schema: !`ls -la prisma/schema.prisma 2>/dev/null || echo "No Prisma schema found"` +- Existing docs: !`ls -la .taskmaster/docs/*.md 2>/dev/null || echo "No docs yet"` + +## Goal + +Create comprehensive Tech Stack Documentation based on deep codebase analysis. Document all technologies, frameworks, libraries, development tools, deployment strategies, and implementation patterns with specific versions and configurations. + +## Process + +### 1. Automated Technical Discovery + +- Parse package.json for all dependencies +- Analyze configuration files (tsconfig, vite.config, next.config, etc.) +- Detect database setup (Prisma, Drizzle, TypeORM, etc.) +- Identify testing frameworks and tools +- Scan for CI/CD configurations +- Check deployment configurations + +### 2. Deep Code Analysis + +Examine codebase for: + +- **Architecture Patterns:** Monorepo structure, module organization +- **Framework Usage:** Next.js app router vs pages, API routes +- **State Management:** Zustand, Redux, Context API patterns +- **Styling Approach:** Tailwind, CSS modules, styled-components +- **Type Safety:** TypeScript strictness, validation libraries +- **API Design:** REST, GraphQL, tRPC implementation +- **Authentication:** Auth libraries and session management +- **Testing Strategy:** Unit, integration, E2E test patterns + +### 3. Interactive Technical Q&A + +Ask 4-6 deployment and infrastructure questions: + +- Use numbered/lettered options +- Focus on non-discoverable information +- Gather hosting, monitoring, and workflow details + +### 4. Generate Comprehensive Documentation + +Create detailed tech stack document with: + +- Specific version numbers +- Configuration examples +- Command references +- Architecture diagrams (when applicable) + +### 5. Save and Organize + +- Create `.taskmaster/docs/` if needed +- Save as `tech-stack.md` +- Update CLAUDE.md commands section + +## Technical Questions Template + +### πŸš€ Deployment & Infrastructure + +**1. Where is your application currently deployed?** + +a) **Vercel** - Next.js optimized hosting + b) **AWS** - EC2, Lambda, or containerized + c) **Railway/Render** - Modern PaaS providers + d) **Self-hosted** - VPS or on-premise + e) **Other** - Please specify + f) **Not deployed yet** - Still in development + +**2. How is your database hosted?** + +a) **Managed service** (Supabase, PlanetScale, Neon, etc.) + b) **Cloud provider** (AWS RDS, Google Cloud SQL, etc.) + c) **Self-hosted** (Docker, VPS, etc.) + d) **Local only** - No production database yet + +### πŸ“Š Monitoring & Operations + +**3. What observability tools do you use?** + +a) **Error tracking:** Sentry, Rollbar, Bugsnag + b) **Analytics:** Vercel Analytics, Google Analytics, Plausible + c) **Monitoring:** Datadog, New Relic, custom solution + d) **Logging:** CloudWatch, LogTail, custom logs + e) **None yet** - Planning to add later + +### πŸ‘₯ Development Workflow + +**4. What's your Git workflow?** + +a) **Feature branches** with PR reviews + b) **Trunk-based** development + c) **GitFlow** with release branches + d) **Direct to main** (solo project) + +**5. How do you manage environments?** + +a) **Multiple deployments** (dev, staging, prod) + b) **Preview deployments** for PRs + c) **Single production** environment + d) **Local development** only + +### πŸ” Additional Services + +**6. Which external services do you integrate with?** + +- [ ] Payment processing (Stripe, PayPal) +- [ ] Email service (SendGrid, Resend, AWS SES) +- [ ] File storage (S3, Cloudinary, UploadThing) +- [ ] Authentication (Auth0, Clerk, Supabase Auth) +- [ ] Search (Algolia, Elasticsearch) +- [ ] Other APIs (please specify) + +## Document Structure + +The generated document must follow this technical structure: + +### **Overview** + +- Brief description of the application's technical nature +- Technology stack summary +- Architecture approach (monolith, microservices, etc.) + +### **Programming Language & Runtime** + +- Primary programming language and version +- Runtime environment and version +- Type system and language features used + +### **Frontend** + +- UI Framework/Library and version +- Styling approach and frameworks +- Component libraries and design systems +- State management solutions +- Build tools and bundlers +- Browser support and compatibility + +### **Backend** + +- Backend framework and architecture +- API design (REST, GraphQL, tRPC, etc.) +- Authentication and authorization +- Middleware and security +- File handling and uploads + +### **Database & Storage** + +- Database type and version +- ORM/Query builder +- Schema management and migrations +- Caching solutions +- File storage solutions +- Data backup and recovery + +### **Development Tools & Workflow** + +- Package manager +- Code formatting and linting +- Type checking and compilation +- Testing frameworks and strategies +- Development server and hot reload +- Version control workflow + +### **Deployment & Infrastructure** + +- Hosting platform and services +- Build and deployment pipeline +- Environment configuration +- Domain and DNS management +- SSL/TLS and security +- Monitoring and logging + +### **External Integrations** + +- Third-party APIs and services +- Payment processing +- Email services +- Analytics and tracking +- Error monitoring +- Performance monitoring + +### **Quality Assurance & Testing** + +- Testing strategy and frameworks +- Code coverage tools +- End-to-end testing +- Performance testing +- Security testing +- Code review process + + +### **Schemas & Data Models** + +- Database schema (if applicable) +- API schemas and validation +- Type definitions and interfaces +- Data relationships and constraints + +## Target Audience + +The document should serve: + +- **Developers** joining the project who need technical onboarding +- **DevOps engineers** setting up infrastructure and deployment +- **Technical architects** evaluating or improving the tech stack +- **Security teams** understanding the technical landscape +- **Future maintainers** who need to understand technical decisions + +The language should be technical, precise, and include specific version numbers and configuration details. + +## Documentation Principles + +### DO Include: + +- **Exact Versions:** Lock file versions, not just ranges +- **Configuration Examples:** Actual config snippets from the project +- **Command Reference:** All npm scripts and their purposes +- **Setup Instructions:** Step-by-step for new developers +- **Architecture Decisions:** Why specific technologies were chosen +- **Integration Details:** How services connect and communicate + +### DON'T Include: + +- **Generic Descriptions:** Avoid Wikipedia-style explanations +- **Outdated Information:** Only document what's actually used +- **Wishful Thinking:** Document current state, not future plans +- **Sensitive Data:** No API keys, secrets, or credentials +- **Redundant Info:** Link to official docs instead of copying + +## Output + +- **Format:** Markdown (`.md`) +- **Location:** `.taskmaster/docs/` +- **Filename:** `tech-stack.md` + +## Execution Steps + +### 1. Automated Analysis Phase + +```bash +# Extract key technical information +- Read package.json and lock files +- Scan for configuration files +- Detect framework patterns +- Identify database setup +- Find test configurations +``` + +### 2. Manual Discovery Phase + +- Read key source files to understand architecture +- Check for API route patterns +- Analyze authentication implementation +- Review deployment configurations + +### 3. Interactive Q&A + +- Present deployment and infrastructure questions +- Use checkboxes for multi-select options +- Wait for user responses + +### 4. Document Generation + +- Start with discovered information +- Incorporate user responses +- Add specific configuration examples +- Include all npm scripts with descriptions + +### 5. Save and Update + +```bash +# Create directory and save +mkdir -p .taskmaster/docs +# Save to .taskmaster/docs/tech-stack.md +``` + +### 6. Update CLAUDE.md + +Add discovered commands to the Commands section: + +```markdown +### Development + +- `pnpm dev` - Start development server +- `pnpm build` - Build for production +- `pnpm typecheck` - Run TypeScript type checking + +# ... other discovered commands +``` + +### 7. Next Steps + +- Suggest: "Would you like me to update CLAUDE.md with the discovered commands?" +- Recommend: "Should I create an app design document to complement this technical documentation?" + +## Example Usage + +```bash +# Basic usage +/project:create-tech-stack + +# With specific focus +/project:create-tech-stack Focus on deployment and CI/CD setup +``` + +## Sample Output Structure + +```markdown +# Tech Stack Documentation + +## Overview + +- **Framework:** Next.js 14.2.5 (App Router) +- **Language:** TypeScript 5.5.3 +- **Database:** PostgreSQL with Prisma ORM +- **Deployment:** Vercel with preview deployments + +## Commands Reference + +### Development + +- `pnpm dev` - Start Next.js dev server on port 3000 +- `pnpm build` - Build production bundle +- `pnpm typecheck` - Run tsc --noEmit + +### Database + +- `pnpm db:generate` - Generate Prisma client +- `pnpm db:push` - Push schema changes to database + +# ... continue with full documentation +``` diff --git a/.claude/commands/docs/parse-prd.md b/.claude/commands/docs/parse-prd.md new file mode 100644 index 0000000..6fdef76 --- /dev/null +++ b/.claude/commands/docs/parse-prd.md @@ -0,0 +1,181 @@ +--- +allowed-tools: TodoWrite, mcp__taskmaster-ai__parse_prd, mcp__taskmaster-ai__add_tag, mcp__taskmaster-ai__use_tag, mcp__taskmaster-ai__list_tags, mcp__taskmaster-ai__get_tasks +description: Parse a PRD into Task Master tasks with optional tag creation +--- + +# Parse PRD into Task Master Tasks + +## Context + +- **User Request:** $ARGUMENTS +- Current directory: !`pwd` +- Task Master state: !`cat .taskmaster/state.json 2>/dev/null || echo "No state file yet"` +- Current tag: !`jq -r '.currentTag // "master"' .taskmaster/state.json 2>/dev/null || echo "master"` +- Available tags: !`jq -r '.tags | keys | join(", ")' .taskmaster/tasks/tasks.json 2>/dev/null || echo "No tags yet"` +- PRD files: !`ls -la .taskmaster/docs/prd*.md 2>/dev/null | tail -5 || echo "No PRD files found"` + +## Goal + +Parse a Product Requirements Document (PRD) into structured Task Master tasks. This command handles tag creation, context switching, and PRD parsing in a streamlined workflow. + +## Process + +### 1. Determine PRD Location + +**Think about which PRD file the user wants to parse.** + +Check for: + +- Explicit PRD path in +- Default PRD location: `.taskmaster/docs/prd.txt` or `.taskmaster/docs/prd.md` +- Tag-specific PRD: `.taskmaster/docs/prd-[tag-name].md` + +### 2. Tag Context Decision + +Determine if we need a new tag: + +- If PRD is for a specific feature β†’ Create new tag +- If updating existing work β†’ Use current tag +- If starting fresh β†’ Consider new tag + +### 3. Execute Parse Workflow + +Based on context: + +1. Create new tag if needed +2. Switch to appropriate tag +3. Parse the PRD +4. Generate tasks with proper numbering +5. Suggest next steps + +## Execution Steps + +### Scenario 1: Parse with New Tag Creation + +If the user wants to parse a feature-specific PRD: + +```markdown +1. **Create a new tag** for this feature: + Using: add_tag with name and description + +2. **Switch to the new tag**: + Using: use_tag to set context + +3. **Parse the PRD**: + Using: parse_prd with the PRD path + +4. **Confirm success**: + Show task count and suggest next steps +``` + +### Scenario 2: Parse in Current Context + +If parsing into the current tag: + +```markdown +1. **Confirm current tag** is appropriate + Show current tag context + +2. **Parse the PRD directly**: + Using: parse_prd with the PRD path + +3. **Show results**: + Display generated tasks summary +``` + +### Scenario 3: Parse Default PRD + +If no specific PRD mentioned: + +```markdown +1. **Check for default PRD**: + Look for .taskmaster/docs/prd.txt or prd.md + +2. **Confirm with user** if found +3. **Parse the default PRD**: + Using: parse_prd +``` + +## Interactive Flow + +Based on User Request, determine the appropriate flow: + +### If arguments include a tag name: + +1. Create the tag +2. Switch to it +3. Parse the corresponding PRD + +### If arguments include a PRD path: + +1. Ask if a new tag is needed +2. Parse the specified PRD + +### If no arguments: + +1. Check current tag context +2. Look for default PRD +3. Proceed with parsing + +## Best Practices + +### DO: + +- **Check tag context** before parsing +- **Use descriptive tag names** for features +- **Keep PRDs organized** by feature/tag +- **Verify PRD exists** before parsing +- **Show task summary** after parsing + +### DON'T: + +- **Parse into master tag** for feature work +- **Overwrite existing tasks** without confirmation +- **Mix unrelated features** in one tag +- **Skip tag creation** for new features + +## Example Usage + +```bash +# Parse default PRD in current context +/project:parse + +# Parse specific PRD with new tag +/project:parse user-auth feature + +# Parse existing PRD file +/project:parse .taskmaster/docs/prd-payments.md +``` + +## Natural Language Examples + +Since MCP supports natural language: + +``` +"Please parse my PRD for the user authentication feature" +"Create tasks from the payments PRD and put them in a new tag" +"Parse the default PRD into the current tag context" +``` + +## Next Steps + +After parsing, suggest: + +1. **View generated tasks**: Use `/next` to see the first task +2. **Analyze complexity**: Run complexity analysis if many tasks +3. **Expand tasks**: Break down complex tasks into subtasks +4. **Start implementation**: Begin with the highest priority task + +## Task Tracking + +Add parsed PRD to todo list for tracking: + +```typescript +{ + content: "Parse PRD: [filename]", + status: "completed", + priority: "high" +} +``` + +This helps track which PRDs have been processed and when. diff --git a/.claude/commands/docs/update-app-design.md b/.claude/commands/docs/update-app-design.md new file mode 100644 index 0000000..0b93add --- /dev/null +++ b/.claude/commands/docs/update-app-design.md @@ -0,0 +1,303 @@ +--- +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: @.taskmaster/docs/app-design-document.md +- Last modified: !`stat -f "%Sm" .taskmaster/docs/app-design-document.md 2>/dev/null || echo "No existing document"` +- Project status: @CLAUDE.md#project-status + +## 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 app-design-document.md +- 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.md` "Project Status" section +- 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 app-design-document.md +- 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.md] + +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" .taskmaster/docs/app-design-document.md + +# 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.md + +## 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 + +``` + +### 5. Save and Backup + +```bash +# Optional: Create backup +cp .taskmaster/docs/app-design-document.md .taskmaster/docs/app-design-document.backup.md + +# Save updated document +# Overwrite .taskmaster/docs/app-design-document.md +``` + +## 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 (`.md`) +- **Location:** `.taskmaster/docs/` +- **Filename:** `app-design-document.md` (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.md if stage/priorities changed +5. βœ… Make incremental, targeted updates +6. βœ… Preserve document quality and tone +7. βœ… Suggest backup for major changes +8. βœ… Consider tech-stack.md updates if needed diff --git a/.claude/commands/docs/update-project-structure.md b/.claude/commands/docs/update-project-structure.md new file mode 100644 index 0000000..41f1966 --- /dev/null +++ b/.claude/commands/docs/update-project-structure.md @@ -0,0 +1,14 @@ +--- +allowed-tools: Bash +description: Update project structure documentation by running tree script +--- + +# Update Project Structure + +Run the tree script to update project structure documentation: + +```bash +bash .claude/scripts/tree.sh +``` + +Do not do anything else. diff --git a/.claude/commands/docs/update-rule.md b/.claude/commands/docs/update-rule.md new file mode 100644 index 0000000..5e0feb9 --- /dev/null +++ b/.claude/commands/docs/update-rule.md @@ -0,0 +1,313 @@ +--- +allowed-tools: Read, Glob, Grep, Write, MultiEdit, TodoWrite, Bash +description: Update existing Cursor rules based on new patterns or codebase evolution +--- + +# Update Cursor Rule + +## Context + +- **User Request:** $ARGUMENTS +- Rules directory: !`ls -la .cursor/rules/*.mdc | wc -l | xargs -I {} echo "{} total rules"` +- Rule guidelines: @.cursor/rules/cursor-rules.mdc + +## Goal + +Update an existing Cursor rule to reflect new patterns, codebase changes, or improved conventions. Maintain consistency with the rule structure while incorporating new learnings and examples. + +## Process + +### 1. Rule Analysis + +- Read the existing rule thoroughly +- Understand current requirements +- Note the file patterns (globs) +- Review existing examples + +### 2. Pattern Evolution Detection + +**Think deeply about how code patterns have evolved since this rule was created.** + +Analyze for: + +- **New Patterns:** Better ways to implement the same concept +- **Framework Updates:** Changes due to library/framework evolution +- **Anti-patterns:** New problematic patterns discovered +- **Edge Cases:** Scenarios not covered by current rule +- **Related Changes:** Impact from other rule updates + +### 3. Codebase Scanning + +Search for: + +- Current implementations of the pattern +- Violations of the existing rule +- New good examples to reference +- Emerging patterns that should be included + +### 4. Interactive Update Session + +Ask about: + +- Specific patterns that need updating +- New edge cases discovered +- Framework or library changes +- Team feedback on the rule + +### 5. Update Rule + +Make targeted updates: + +- Preserve valid existing content +- Update examples with current code +- Add new patterns or exceptions +- Update file references +- Revise related rules section + +### 6. Save and Communicate + +- Save updated rule +- Note what changed +- Update CLAUDE.md if rule significance changed +- Suggest reviewing affected code + +## Update Questions Template + +### πŸ” Pattern Evolution + +**1. What prompted this rule update?** + +a) **New patterns emerged** - Better ways to do things +b) **Framework changes** - Library updates require new approach +c) **Problems discovered** - Current rule has issues +d) **Team feedback** - Developers suggested improvements +e) **Codebase evolution** - Patterns have naturally changed + +**2. Are there new GOOD patterns to add?** + +Please describe or provide examples of patterns that should be encouraged. + +**3. Have you discovered new ANTI-patterns?** + +What problematic patterns have emerged that the rule should discourage? + +### πŸ“ Scope Changes + +**4. Should the rule apply to different files now?** + +Current globs: [show from existing rule] + +a) **Same scope** - No change to file patterns +b) **Expand scope** - Apply to more files +c) **Narrow scope** - Apply to fewer files +d) **Different patterns** - Change glob patterns entirely + +**5. Should alwaysApply setting change?** + +Currently: [show from existing rule] + +a) **Keep current setting** +b) **Change to always apply** +c) **Change to conditional** + +### πŸ”— Related Updates + +**6. Have related rules changed?** + +Review if updates to other rules affect this one. + +**7. Are there new related rules to reference?** + +List any newly created rules that relate to this one. + +## Update Strategy + +### Incremental Updates + +````markdown +## Examples + +### βœ… DO: [Good Pattern Name] + + + +```typescript +// Original good example +``` +```` + + + +```typescript +// New pattern discovered in [file] +``` + +### ❌ DON'T: [Anti-pattern Name] + + + +```typescript +// More relevant anti-pattern +``` + +```` + +### Version Notes + +When framework/library updates affect rules: + +```markdown +## Framework Compatibility + +**React 18+**: Use the new pattern +**React 17**: Legacy pattern still acceptable + + +```` + +### Edge Case Documentation + +```markdown +## Edge Cases + +**NEW:** [Scenario discovered since last update] + +- How to handle: [Approach] +- Example: [Code snippet] +``` + +## Execution Steps + +### 1. Start with Analysis + +```bash +# Find current implementations +rg -t ts -t tsx "[pattern from rule]" --glob "!node_modules" + +# Check for violations +# Search for anti-patterns mentioned in rule + +# Find new examples +# Look for files modified recently that might have new patterns +``` + +**Think deeply about:** "How has our understanding of this pattern evolved? What have we learned from using this rule? Are there better ways to achieve the same goal?" + +### 2. Current State Review + +- Read existing rule completely +- Check all file references still exist +- Verify examples are still current +- Test if globs match intended files + +### 3. Interactive Q&A + +- Present current rule state +- Ask about specific changes needed +- Gather new examples + +### 4. Update Rule + +Follow incremental approach: + +- Mark sections that are updated +- Preserve good existing content +- Add new examples from current code +- Update stale file references + +### 5. Save and Document + +```markdown + + +``` + +## Key Principles + +### DO: + +- **Preserve Value:** Keep good existing examples +- **Real Updates:** Use actual current code +- **Clear Changes:** Note what's new or updated +- **Maintain Structure:** Follow established format +- **Test Globs:** Verify patterns still match correctly + +### DON'T: + +- **Complete Rewrite:** Unless fundamentally wrong +- **Break References:** Ensure linked files exist +- **Lose History:** Keep record of why changes were made +- **Theoretical Updates:** Use real examples +- **Overcomplicate:** Keep rule focused + +## Common Update Scenarios + +### Framework Version Updates + +```markdown +## Requirements + +- **React 18+:** + - Use `useId()` for unique IDs + - Prefer `startTransition` for non-urgent updates +- **React 17 (legacy):** + - Continue using previous patterns + - Plan migration to new patterns +``` + +### New Tool Adoption + +```markdown +## Tools + +**Previous:** ESLint + Prettier +**Current:** Biome (replaced both) + + +``` + +### Pattern Evolution + +````markdown +## Examples + +### βœ… DO: Modern Async Pattern + +```typescript +// NEW: Using async/await with proper error boundaries +const MyComponent = () => { + const { data, error } = useSWR("/api/data", fetcher); + + if (error) return ; + if (!data) return ; + + return ; +}; +``` +```` + + + +``` + +## Output + +- **Format:** Markdown with `.mdc` extension +- **Location:** `.cursor/rules/` +- **Filename:** Same as existing rule +- **Backup:** Consider keeping version history + +## Final Checklist + +1. βœ… Read existing rule completely +2. βœ… Search for current pattern usage +3. βœ… Find new good examples +4. βœ… Identify new anti-patterns +5. βœ… Update with real code examples +6. βœ… Verify all file references exist +7. βœ… Test glob patterns still work +8. βœ… Update related rules section +9. βœ… Document what changed +10. βœ… Update CLAUDE.md if needed +11. βœ… Consider impact on existing code +``` diff --git a/.claude/commands/docs/update-tech-stack.md b/.claude/commands/docs/update-tech-stack.md new file mode 100644 index 0000000..8f7a103 --- /dev/null +++ b/.claude/commands/docs/update-tech-stack.md @@ -0,0 +1,327 @@ +--- +allowed-tools: Read, Glob, Grep, Write, MultiEdit, TodoWrite, Bash +description: Update tech stack documentation based on dependency changes and technical evolution +--- + +# Update Tech Stack Documentation + +**User Request:** $ARGUMENTS + +## Context + +- Project root: !`pwd` +- Package.json: @package.json +- Current tech doc: @.taskmaster/docs/tech-stack.md +- **Project Structure:** !`bash .claude/scripts/tree.sh` +- Last modified: !`stat -f "%Sm" .taskmaster/docs/tech-stack.md 2>/dev/null || echo "No existing document"` +- Recent package changes: !`git diff HEAD~10 HEAD -- package.json 2>/dev/null | grep -E "^[+-]" | head -20 || echo "No recent changes"` + +## Goal + +Update the existing Tech Stack Documentation to reflect current technical state, dependency changes, new tools adoption, and infrastructure evolution. Maintain technical accuracy while documenting all changes. + +## Process + +### 1. Document Analysis + +- Read existing tech-stack.md thoroughly +- Note documented versions and configurations +- Understand current technical baseline +- Identify sections that may need updates + +### 2. Technical Change Detection + +**Think deeply about technical evolution in the codebase.** + +Analyze for: + +- **Dependency Changes:** New packages, version updates, removals +- **Framework Evolution:** Major version upgrades, breaking changes +- **Tool Adoption:** New dev tools, linters, formatters, testing frameworks +- **Infrastructure Shifts:** Deployment, hosting, monitoring changes +- **Database Evolution:** Schema changes, new ORMs, migrations +- **Integration Updates:** New APIs, services, authentication providers + +_Extended thinking helps identify cascading dependency updates, understand version compatibility issues, and recognize architectural implications of technical changes._ + +### 3. Automated Comparison + +```bash +# Compare current vs documented dependencies +# Check for version mismatches +# Identify new configuration files +# Detect new tool configurations +``` + +### 4. Interactive Technical Q&A + +Ask targeted questions about: + +- Non-discoverable infrastructure changes +- Deployment and hosting updates +- New external service integrations +- Workflow and process changes + +### 5. Update Documentation + +Update incrementally: + +- Preserve accurate technical information +- Update version numbers precisely +- Add new sections for major additions +- Mark deprecated technologies + +### 6. Save and Verify + +- Suggest backup for major changes +- Update CLAUDE.md commands if needed +- Verify all versions are accurate + +## Technical Questions Template + +### πŸ”„ Version Updates & Dependencies + +**1. Which major dependencies have been updated?** + +Review your recent dependency changes: + +a) **Framework upgrades** (Next.js, React, etc.) with breaking changes +b) **Tool updates** (TypeScript, ESLint, etc.) requiring config changes +c) **New dependencies** added for features or development +d) **Removed packages** that are no longer needed +e) **All of the above** - Major technical overhaul + +**2. Have you changed your package manager or Node version?** + +a) **Same setup** - No changes to tooling +b) **Node upgrade** - Updated Node.js version +c) **Package manager switch** - Changed from npm/yarn/pnpm +d) **Monorepo adoption** - Moved to workspace setup + +### πŸ—οΈ Infrastructure Evolution + +**3. Have your deployment or hosting arrangements changed?** + +Current deployment is documented as: [show from existing doc] + +a) **Same platform** - Just configuration updates +b) **Platform migration** - Moved to different provider +c) **Architecture change** - Serverless, containers, etc. +d) **Multi-region** - Expanded geographic deployment + +**4. Database or storage changes?** + +a) **Version upgrade** - Same DB, newer version +b) **Migration** - Switched database systems +c) **New caching** - Added Redis, Memcached, etc. +d) **Storage addition** - New file storage, CDN +e) **No changes** - Same setup as before + +### πŸ› οΈ Development Workflow Updates + +**5. New development tools or practices?** + +Select all that apply: + +- [ ] New testing framework or strategy +- [ ] Added code quality tools (linters, formatters) +- [ ] CI/CD pipeline changes +- [ ] Docker/containerization adoption +- [ ] New build tools or bundlers +- [ ] Performance monitoring tools + +**6. External service integrations?** + +Have you added or changed: + +a) **Payment processing** - New or updated provider +b) **Authentication** - Different auth service +c) **Email/SMS** - Communication service changes +d) **Monitoring** - New error tracking or analytics +e) **APIs** - Additional third-party integrations +f) **None** - Same external services + +### πŸ” Security & Compliance + +**7. Security tool adoption?** + +- [ ] Vulnerability scanning (Snyk, etc.) +- [ ] Secret management changes +- [ ] New authentication methods +- [ ] Compliance tools (GDPR, etc.) +- [ ] Security headers/policies +- [ ] None of the above + +## Update Strategy + +### Version Precision + +```typescript +// ❌ Outdated +"next": "^13.0.0" + +// βœ… Current and precise +"next": "14.2.5" +``` + +### Configuration Updates + +- Update all config examples to match current files +- Include new configuration options +- Remove deprecated settings +- Add migration notes for breaking changes + +### New Technology Sections + +When adding major new tools: + +```markdown +### [New Tool Category] + +**Tool:** [Name] [Version] +**Purpose:** [Why it was adopted] +**Configuration:** [Key settings] +**Integration:** [How it connects with other tools] +``` + +## Document Update Areas + +### Always Check: + +1. **package.json changes** + + ```bash + # Compare all dependencies + # Note version changes + # Identify new packages + ``` + +2. **Configuration files** + + - tsconfig.json updates + - New .config files + - Build tool configurations + - Linting rule changes + +3. **Development scripts** + + - New npm/pnpm scripts + - Changed command purposes + - Removed scripts + +4. **Infrastructure files** + - Dockerfile changes + - CI/CD workflows + - Deployment configs + - Environment examples + +### Conditional Updates: + +- **Architecture:** Only if fundamental changes +- **Conventions:** Only if standards changed + +## Execution Steps + +### 1. Start with Analysis + +```bash +# Check current dependencies vs documented +diff <(jq -r '.dependencies | keys[]' package.json | sort) \ + <(grep -E '^\*\*.*:' .taskmaster/docs/tech-stack.md | cut -d: -f1 | sed 's/\*//g' | sort) + +# Review recent dependency commits +git log --oneline --grep="dep" --since="30 days ago" + +# Check for new config files +find . -name "*.config.*" -newer .taskmaster/docs/tech-stack.md 2>/dev/null +``` + +**Think deeply about:** "What technical decisions drove these changes? How do version updates affect the overall architecture? What new capabilities do these tools enable?" + +### 2. Interactive Q&A + +- Present technical questions clearly +- Include current state from documentation +- Wait for detailed responses + +### 3. Update Documentation + +Follow incremental approach: + +```markdown + + +**Before:** React 18.2.0 +**After:** React 18.3.1 - Includes new compiler optimizations + + + +### Code Quality Tools + +**New Addition:** + +- **Biome:** 1.8.3 - Replaced ESLint and Prettier + - Faster performance (10x) + - Single configuration file + - Built-in formatting +``` + +### 4. Commands Update + +Update CLAUDE.md if new scripts discovered: + +```markdown +### Development + +- `pnpm dev` - Start development server +- `pnpm check` - NEW: Run Biome linting and formatting +- `pnpm test:e2e` - NEW: Run Playwright tests +``` + +### 5. Save and Backup + +```bash +# Optional backup +cp .taskmaster/docs/tech-stack.md .taskmaster/docs/tech-stack.backup.md + +# Save updated document +# Overwrite .taskmaster/docs/tech-stack.md +``` + +## Key Principles + +### DO: + +- **Exact Versions:** Use precise version numbers from lock files +- **Config Accuracy:** Match actual configuration files +- **Change Rationale:** Explain why tools were adopted/changed +- **Migration Notes:** Document breaking changes and updates +- **Performance Impact:** Note improvements or concerns + +### DON'T: + +- **Generic Updates:** Avoid vague version ranges +- **Assumption:** Verify every technical detail +- **Old Information:** Remove outdated configurations +- **Wishful Documentation:** Only document what exists +- **Sensitive Data:** Never include secrets or keys + +## Output + +- **Format:** Markdown (`.md`) +- **Location:** `.taskmaster/docs/` +- **Filename:** `tech-stack.md` (overwrites) +- **Backup:** Suggest for major changes + +## Final Checklist + +1. βœ… Read existing tech-stack.md completely +2. βœ… Analyze all dependency changes +3. βœ… Check configuration file updates +4. βœ… Review infrastructure changes +5. βœ… Ask targeted technical questions +6. βœ… Update with exact versions +7. βœ… Include configuration examples +8. βœ… Update CLAUDE.md commands +9. βœ… Suggest backup if major changes +10. βœ… Verify technical accuracy diff --git a/.claude/commands/research/architecture.md b/.claude/commands/research/architecture.md new file mode 100644 index 0000000..600c1c7 --- /dev/null +++ b/.claude/commands/research/architecture.md @@ -0,0 +1,33 @@ +--- +allowed-tools: mcp__taskmaster-ai__research, Write, TodoWrite +description: Research architectural patterns and best practices +--- + +# Research Architecture + +**User Request:** $ARGUMENTS + +## Goal + +Research current architectural patterns, system design best practices, and scaling strategies. + +## What You Can Say + +``` +"Research microservices vs modular monolith for SaaS" +"Best practices for event-driven architecture 2024" +"How to scale WebSocket connections to 100k users" +"Database sharding strategies for multi-tenant apps" +"Research CQRS and Event Sourcing patterns" +``` + +## How It Works + +I'll research architectural topics and: + +1. **Get latest patterns** and industry best practices +2. **Include project context** if relevant +3. **Provide actionable recommendations** +4. **Save findings** if requested + +Great for making informed architectural decisions before implementation. diff --git a/.claude/commands/research/security.md b/.claude/commands/research/security.md new file mode 100644 index 0000000..699c489 --- /dev/null +++ b/.claude/commands/research/security.md @@ -0,0 +1,34 @@ +--- +allowed-tools: mcp__taskmaster-ai__research, mcp__taskmaster-ai__update_task +description: Research security best practices and vulnerabilities +--- + +# Research Security + +**User Request:** $ARGUMENTS + +## Goal + +Research security best practices, vulnerabilities, and compliance requirements. + +## What You Can Say + +``` +"Latest OWASP top 10 for web apps" +"JWT security best practices 2024" +"How to implement secure file uploads" +"PCI compliance for SaaS applications" +"Research CSP headers configuration" +"OAuth 2.0 vs SAML for enterprise" +``` + +## How It Works + +I'll research security topics and: + +1. **Find current vulnerabilities** and mitigations +2. **Get compliance requirements** if applicable +3. **Provide secure implementation** patterns +4. **Update relevant tasks** with security considerations + +Critical for security-sensitive features. diff --git a/.claude/commands/research/task.md b/.claude/commands/research/task.md new file mode 100644 index 0000000..475f09d --- /dev/null +++ b/.claude/commands/research/task.md @@ -0,0 +1,32 @@ +--- +allowed-tools: mcp__taskmaster-ai__research, mcp__taskmaster-ai__update_task, mcp__taskmaster-ai__update_subtask +description: Research best practices and update tasks +--- + +# Research for Tasks + +- **User Request:** $ARGUMENTS + +## Goal + +Research current best practices, or solutions to help with task implementation. + +## What You Can Say + +``` +"Research JWT security best practices for task 5" +"What's the best way to handle file uploads in Next.js?" +"Research MongoDB vs PostgreSQL for our use case" +"Find React Query v5 migration guide" +``` + +## How It Works + +I'll research what you asked about (User Request) and: + +1. **Get current information** beyond my knowledge cutoff +2. **Include relevant context** from your project if needed +3. **Show you the findings** +4. **Update tasks** if you mentioned specific ones + +Just tell me what you need to know and optionally which task it's for. diff --git a/.claude/commands/research/tech.md b/.claude/commands/research/tech.md new file mode 100644 index 0000000..c1821d2 --- /dev/null +++ b/.claude/commands/research/tech.md @@ -0,0 +1,31 @@ +--- +allowed-tools: mcp__taskmaster-ai__research +description: Research technologies, frameworks, and tools +--- + +# Research Technology + +**User Request:** $ARGUMENTS + +## Goal + +Research technologies, frameworks, libraries, and tools to make informed decisions. + +## What You Can Say + +``` +"Compare Next.js vs Remix for our project" +"Research state management solutions for React 2024" +"Best Node.js ORMs for PostgreSQL" +"Evaluate Bun vs Node.js performance" +"Research authentication libraries for Next.js" +``` + +## How It Works + +I'll research the technology topics you specify and provide: + +1. **Current landscape** and popular options +2. **Pros/cons** for your use case +3. **Community adoption** and support +4. **Performance comparisons** if relevant diff --git a/.claude/commands/snippets/create-snippet.md b/.claude/commands/snippets/create-snippet.md new file mode 100644 index 0000000..85f693d --- /dev/null +++ b/.claude/commands/snippets/create-snippet.md @@ -0,0 +1,32 @@ +Title: Create Snippet Prompt +Description: Generates a snippet template based on provided example code. Template contains instructions and example code. Provide more examples for coverage if needed. Don't include obvious steps you already know like imports. +Body: + +### Instructions + +Title: ${1:Create ${2:Component}} +Description: Generates a template for ${3:a ${2}} +Rules: + +- ${4:Add relevant rules here} +- Keep rules concise and specific to the snippet +- Include any critical requirements or conventions +- Add validation rules if applicable + +Body: + +${5:$TM_SELECTED_TEXT} + +### Example + +Title: ${1} +Description: ${3} +Rules: + +- ${4} +- Example rule 2 +- Example rule 3 + +Body: + +${5} diff --git a/.claude/commands/task/add-interactive.md b/.claude/commands/task/add-interactive.md new file mode 100644 index 0000000..3578845 --- /dev/null +++ b/.claude/commands/task/add-interactive.md @@ -0,0 +1,59 @@ +--- +allowed-tools: mcp__taskmaster-ai__add_task, TodoWrite +description: Add tasks interactively with clarifying questions +--- + +# Add Tasks Interactively + +## Context + +- **User Request:** $ARGUMENTS +- **Current Tag:** !`jq -r '.currentTag // "master"' .taskmaster/state.json 2>/dev/null || echo "master"` + +## Goal + +Create well-defined tasks by asking clarifying questions about the feature requirements. + +## Process + +1. **Analyze Feature Request:** Think deeply about what tasks might be needed. + +2. **Ask Clarifying Questions:** + + - Ask 4-6 targeted questions based on the feature + - Provide lettered/numbered options for easy response + - Focus on understanding scope and breakdown + +3. **Generate Tasks:** + - Create tasks based on answers + - Add to current tag context + +## Clarifying Questions Framework + +Adapt questions based on the specific feature request provided above. Consider these areas: + +- **Scope:** "How big is this feature?" +- **Components:** "What are the main parts that need to be built?" +- **Dependencies:** "Does this depend on any existing tasks or features?" +- **Priority:** "How urgent is this feature?" +- **Testing:** "What kind of testing will this need?" +- **Phases:** "Should this be built all at once or in phases?" + +## Final Instructions + +1. **Think deeply** about the feature request +2. **Ask clarifying questions** with lettered/numbered options +3. **Generate tasks** based on the answers +4. **Add tasks** to the current tag context + +## Example Usage + +``` +/add-interactive user notification system +``` + +This will: + +1. Ask about notification types and delivery methods +2. Understand scope and dependencies +3. Create appropriate tasks based on answers diff --git a/.claude/commands/task/add.md b/.claude/commands/task/add.md new file mode 100644 index 0000000..d8385e3 --- /dev/null +++ b/.claude/commands/task/add.md @@ -0,0 +1,65 @@ +--- +allowed-tools: mcp__taskmaster-ai__add_task, TodoWrite +description: Add one or more tasks to the current tag +--- + +# Add Tasks + +- **User Request:** $ARGUMENTS + +## Goal + +Add new tasks to your current tag context. Can handle single tasks or multiple tasks at once. + +## What You Can Say + +### Single Task + +``` +/add implement user login with email and password +/add create API endpoint for user profile +``` + +### Multiple Tasks + +``` +/add +1. Setup database schema +2. Create user authentication +3. Add email verification +4. Implement password reset +``` + +### With Details + +``` +/add high priority: implement payment processing with Stripe +/add depends on 5: add payment confirmation emails +``` + +## How It Works + +Based on your input (User Request), I'll: + +1. **Parse your request** - Single task or numbered list +2. **Create tasks** in the current tag context +3. **Set dependencies** if you mention "depends on X" +4. **Set priority** if you mention high/medium/low +5. **Confirm** what was added + +## Examples + +### Quick Add + +- `/add fix the login bug` β†’ Creates task "fix the login bug" + +### Batch Add + +- `/add 1. Setup 2. Test 3. Deploy` β†’ Creates 3 tasks + +### With Context + +- `/add urgent: fix security vulnerability in auth` β†’ High priority task +- `/add after task 3: add unit tests` β†’ Sets dependency + +The command is smart enough to understand your intent from natural language. diff --git a/.claude/commands/task/done.md b/.claude/commands/task/done.md new file mode 100644 index 0000000..f8dd93e --- /dev/null +++ b/.claude/commands/task/done.md @@ -0,0 +1,21 @@ +--- +allowed-tools: mcp__taskmaster-ai__set_task_status, mcp__taskmaster-ai__next_task, TodoWrite +description: Mark task as complete and optionally get next task +--- + +# Task Done + +**User Request:** $ARGUMENTS + +## Goal + +Mark task(s) as complete. By default, also shows the next task. + +## What You Can Say + +``` +/done 3 # Mark task 3 as done, show next +/done 3 stop # Mark done, don't show next +/done 5,7,9 # Mark multiple tasks done +/done # Mark current task done (if tracking) +``` diff --git a/.claude/commands/task/expand.md b/.claude/commands/task/expand.md new file mode 100644 index 0000000..0a0bf71 --- /dev/null +++ b/.claude/commands/task/expand.md @@ -0,0 +1,21 @@ +--- +allowed-tools: mcp__taskmaster-ai__expand_task, mcp__taskmaster-ai__expand_all +description: Break down tasks into subtasks +--- + +# Expand Tasks + +**User Request:** $ARGUMENTS + +## Goal + +Break complex tasks into manageable subtasks. + +## What You Can Say + +``` +/expand 5 # Break down task 5 +/expand 5 security focus # With specific context +/expand all # Expand all pending tasks +/expand 5 research # Use research for better breakdown +``` diff --git a/.claude/commands/task/list.md b/.claude/commands/task/list.md new file mode 100644 index 0000000..94e60dc --- /dev/null +++ b/.claude/commands/task/list.md @@ -0,0 +1,21 @@ +--- +allowed-tools: mcp__taskmaster-ai__get_tasks +description: List all tasks in current tag +--- + +# List Tasks + +**User Request:** $ARGUMENTS + +## Goal + +Show all tasks with their status, priority, and progress. + +## What You Can Say + +``` +/list # All tasks +/list pending # Only pending tasks +/list done # Completed tasks +/list blocked # Blocked tasks +``` diff --git a/.claude/commands/task/move.md b/.claude/commands/task/move.md new file mode 100644 index 0000000..980a8f3 --- /dev/null +++ b/.claude/commands/task/move.md @@ -0,0 +1,21 @@ +--- +allowed-tools: mcp__taskmaster-ai__move_task +description: Reorganize task structure +--- + +# Move Tasks + +**User Request:** $ARGUMENTS + +## Goal + +Move tasks to different positions or parents. + +## What You Can Say + +``` +/move 5.2 to 7.3 # Move subtask to different parent +/move 5 to 25 # Move to new position +/move 10,11,12 to 16,17,18 # Move multiple tasks +/move 5.2 to 7 # Subtask becomes standalone +``` diff --git a/.claude/commands/task/next.md b/.claude/commands/task/next.md new file mode 100644 index 0000000..7022bbe --- /dev/null +++ b/.claude/commands/task/next.md @@ -0,0 +1,18 @@ +--- +allowed-tools: mcp__taskmaster-ai__next_task, mcp__taskmaster-ai__get_task, TodoWrite, Read, Write, MultiEdit, Bash, Grep, Glob +description: Get next task and start implementing it immediately +--- + +# Next Task & Implement + +**User Request:** $ARGUMENTS + +## Goal + +Find the next task and start implementing it right away (unless you say otherwise). + +## How It Works + +1. **Find next task** based on priorities and dependencies +2. **Show task details** briefly +3. **Start implementation** immediately diff --git a/.claude/commands/task/research.md b/.claude/commands/task/research.md new file mode 100644 index 0000000..475f09d --- /dev/null +++ b/.claude/commands/task/research.md @@ -0,0 +1,32 @@ +--- +allowed-tools: mcp__taskmaster-ai__research, mcp__taskmaster-ai__update_task, mcp__taskmaster-ai__update_subtask +description: Research best practices and update tasks +--- + +# Research for Tasks + +- **User Request:** $ARGUMENTS + +## Goal + +Research current best practices, or solutions to help with task implementation. + +## What You Can Say + +``` +"Research JWT security best practices for task 5" +"What's the best way to handle file uploads in Next.js?" +"Research MongoDB vs PostgreSQL for our use case" +"Find React Query v5 migration guide" +``` + +## How It Works + +I'll research what you asked about (User Request) and: + +1. **Get current information** beyond my knowledge cutoff +2. **Include relevant context** from your project if needed +3. **Show you the findings** +4. **Update tasks** if you mentioned specific ones + +Just tell me what you need to know and optionally which task it's for. diff --git a/.claude/commands/task/show.md b/.claude/commands/task/show.md new file mode 100644 index 0000000..35e8810 --- /dev/null +++ b/.claude/commands/task/show.md @@ -0,0 +1,20 @@ +--- +allowed-tools: mcp__taskmaster-ai__get_task +description: Show specific task details +--- + +# Show Task + +**User Request:** $ARGUMENTS + +## Goal + +Display detailed information about specific task(s). + +## What You Can Say + +``` +/show 5 # Show task 5 +/show 5,7,9 # Show multiple tasks +/show 5.2 # Show subtask +``` diff --git a/.claude/commands/task/spec.md b/.claude/commands/task/spec.md new file mode 100644 index 0000000..37dbf6f --- /dev/null +++ b/.claude/commands/task/spec.md @@ -0,0 +1,77 @@ +# End-to-End Feature Implementation Guide + +## Context + +- When implementing new end-to-end features +- When planning feature development workflow +- When ensuring consistent architecture + +## Requirements + +- Follow the implementation steps in order +- Use the appropriate standards for each step +- Ensure consistency across all implementation layers +- Test each phase before moving to the next + +## Implementation Steps + +1. **Schema Definition** β†’ Use rule @.cursor/rules/2101-schema-prisma.mdc + + - Define Prisma schema with standard fields + - Add proper relations and indexes + - Use correct field types and constraints + - Follow naming conventions + +2. **Router Implementation** β†’ Use rule @.cursor/rules/2102-router.mdc + + - Create protected tRPC router + - Add input validation with Zod + - Implement cursor-based pagination + - Handle security and responses + +3. **React Query Integration** β†’ Use rule @.cursor/rules/2103-trpc-react-query.mdc + + - Set up queries with queryOptions + - Handle loading states + - Implement optimistic updates + - Manage cache invalidation + +4. **CRUD Implementation** β†’ Use rule @.cursor/rules/2105-crud.mdc + + - Follow phased implementation approach + - Start with Create & Read operations + - Add Update & Delete operations + - Implement advanced features last + +5. **Authentication** β†’ Use rule @.cursor/rules/2106-auth.mdc + - Use protectedProcedure for routes + - Add session checks in components + - Implement auth guards + - Handle unauthorized states + +## Examples + + +```typescript +// Implementation follows all steps in order +// 1. Schema defined in prisma/schema.prisma +// 2. Router implemented in src/server/api/routers/item.ts +// 3. React Query integration in src/components/ItemList.tsx +// 4. CRUD operations implemented in phases +// 5. Authentication checks in all appropriate places +``` +Complete feature implementation following all steps in order + + + +```typescript +// Implementation skips steps or does them out of order +// Missing schema definition +// Incomplete router implementation +// Using old tRPC patterns instead of React Query +// Missing error handling +// Implementing all CRUD operations at once +// Missing authentication checks +``` +Incomplete or out-of-order implementation missing critical steps + diff --git a/.claude/commands/task/update-task-interactive.md b/.claude/commands/task/update-task-interactive.md new file mode 100644 index 0000000..386e052 --- /dev/null +++ b/.claude/commands/task/update-task-interactive.md @@ -0,0 +1,59 @@ +--- +allowed-tools: mcp__taskmaster-ai__update, mcp__taskmaster-ai__update_task, mcp__taskmaster-ai__update_subtask, mcp__taskmaster-ai__get_tasks +description: Update tasks interactively with clarifying questions +--- + +# Update Tasks Interactively + +## Context + +- **User Request:** $ARGUMENTS +- **Current Tag:** !`jq -r '.currentTag // "master"' .taskmaster/state.json 2>/dev/null || echo "master"` + +## Goal + +Update tasks based on implementation changes by asking clarifying questions to ensure accurate updates. + +## Process + +1. **Analyze Change:** Think deeply about the implications of the change. + +2. **Ask Clarifying Questions:** + + - Ask 4-6 targeted questions about the change + - Provide lettered/numbered options for easy response + - Focus on understanding impact and scope + +3. **Update Tasks:** + - Update affected tasks based on answers + - Show what was changed + +## Clarifying Questions Framework + +Adapt questions based on the change described above. Consider these areas: + +- **Scope:** "Which tasks are affected by this change?" +- **Reason:** "Why was this change made?" +- **Impact:** "How does this affect the implementation approach?" +- **Dependencies:** "Does this change affect task dependencies?" +- **Testing:** "How should test strategies be updated?" +- **Documentation:** "What additional context should be added?" + +## Final Instructions + +1. **Think deeply** about the change and its implications +2. **Ask clarifying questions** with lettered/numbered options +3. **Update tasks** based on the answers +4. **Confirm** what was updated + +## Example Usage + +``` +/project:task:update-interactive switching to microservices architecture +``` + +This will: + +1. Ask about which components are affected +2. Understand the migration approach +3. Update relevant tasks with new architecture details diff --git a/.claude/commands/task/update-task.md b/.claude/commands/task/update-task.md new file mode 100644 index 0000000..6984dff --- /dev/null +++ b/.claude/commands/task/update-task.md @@ -0,0 +1,30 @@ +--- +allowed-tools: mcp__taskmaster-ai__update, mcp__taskmaster-ai__update_task, mcp__taskmaster-ai__update_subtask, mcp__taskmaster-ai__get_tasks +description: Update tasks based on implementation changes +--- + +# Update Tasks + +**User Request:** $ARGUMENTS + +## Goal + +Update tasks when implementation changes from the original plan. Just tell me what changed and I'll update the relevant tasks. + +## What You Can Say + +``` +"We're using MongoDB instead of PostgreSQL" +"Update task 5 to use OAuth instead of JWT" +"All tasks from 10 onwards should use the new API structure" +"Task 7.2 needs a note about the Redis caching we added" +``` + +## How It Works + +Based on what you tell me (User Request), I'll: + +1. **Understand the change** from your description +2. **Find affected tasks** automatically or use the ones you specify +3. **Update them** with the new approach +4. **Confirm** what was updated diff --git a/.claude/scripts/tree.sh b/.claude/scripts/tree.sh new file mode 100644 index 0000000..382d67d --- /dev/null +++ b/.claude/scripts/tree.sh @@ -0,0 +1,70 @@ +#!/bin/bash + +# Custom folders to ignore (in addition to .gitignore) +CUSTOM_IGNORE="public|migrations" + +# Parse tsconfig.json exclude patterns +TSCONFIG_IGNORE="" +if [ -f "tsconfig.json" ]; then + # Extract exclude patterns from tsconfig.json + # Parse the JSON properly and handle wildcards + TSCONFIG_PATTERNS=$(node -e " + const fs = require('fs'); + const tsconfig = JSON.parse(fs.readFileSync('tsconfig.json', 'utf8')); + if (tsconfig.exclude) { + const patterns = tsconfig.exclude.map(p => { + // Remove leading **/ and trailing /* + return p.replace(/^\*\*\//, '').replace(/\/\*$/, '').replace(/^\*\*/, ''); + }).filter(p => p && !p.includes('*')); + console.log(patterns.join('|')); + } + " 2>/dev/null || echo "") + + if [ -n "$TSCONFIG_PATTERNS" ]; then + TSCONFIG_IGNORE="|$TSCONFIG_PATTERNS" + fi +fi + +# Combine all ignore patterns +FULL_IGNORE=".git|*.bak|$CUSTOM_IGNORE$TSCONFIG_IGNORE" + +# Output file +OUTPUT=".taskmaster/docs/project-structure.md" + +# Create directory if it doesn't exist +mkdir -p .taskmaster/docs + +# Header +cat > "$OUTPUT" << 'EOF' +# Project Structure + +EOF + +echo "_Last Updated: $(date +%Y-%m-%d)_" >> "$OUTPUT" +echo "" >> "$OUTPUT" +echo '```' >> "$OUTPUT" + +# Backup original .gitignore +cp .gitignore .gitignore.bak + +# Remove !.* line temporarily (both commented and uncommented versions) +grep -v '^!\.\*' .gitignore | grep -v '^# !\.\*' > .gitignore.tmp && mv .gitignore.tmp .gitignore + +# Use tree with gitignore (now without !.* line) +tree --gitignore \ + -a \ + -I "$FULL_IGNORE" \ + --dirsfirst \ + >> "$OUTPUT" + +# Restore original .gitignore +mv .gitignore.bak .gitignore + +# Close code block +echo '```' >> "$OUTPUT" +echo "" >> "$OUTPUT" + +echo "Project structure written to $OUTPUT" + +# Output the contents to stdout as well +cat "$OUTPUT" \ No newline at end of file diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..b922c6f --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,13 @@ +{ + "allowedTools": [ + "Bash(grep:*)", + "Bash(rg:*)", + "Bash(npx tsc:*)", + "Edit", + "Bash(task-master *)", + "Bash(git commit:*)", + "Bash(git add:*)", + "Bash(npm run *)", + "mcp__task_master_ai__*" + ] +} diff --git a/.cursor/mcp.json b/.cursor/mcp.json new file mode 100644 index 0000000..5a2950d --- /dev/null +++ b/.cursor/mcp.json @@ -0,0 +1,10 @@ +{ + "mcpServers": { + "taskmaster-ai": { + "type": "stdio", + "command": "npx", + "args": ["-y", "--package=task-master-ai", "task-master-ai"], + "env": {} + } + } +} diff --git a/.cursor/rules/cursor-rules.mdc b/.cursor/rules/cursor-rules.mdc new file mode 100644 index 0000000..de685f0 --- /dev/null +++ b/.cursor/rules/cursor-rules.mdc @@ -0,0 +1,54 @@ +--- +description: Guidelines for creating and maintaining Cursor rules to ensure consistency and effectiveness. +globs: .cursor/rules/*.mdc +alwaysApply: true +--- + +- **Required Rule Structure:** + ```markdown + --- + description: Clear, one-line description of what the rule enforces + globs: path/to/files/*.ext, other/path/**/* + alwaysApply: boolean + --- + + - **Main Points in Bold** + - Sub-points with details + - Examples and explanations + ``` + +- **File References:** + - Use `[filename](mdc:path/to/file)` ([filename](mdc:filename)) to reference files + - Example: [prisma.mdc](mdc:.cursor/rules/prisma.mdc) for rule references + - Example: [schema.prisma](mdc:prisma/schema.prisma) for code references + +- **Code Examples:** + - Use language-specific code blocks + ```typescript + // βœ… DO: Show good examples + const goodExample = true; + + // ❌ DON'T: Show anti-patterns + const badExample = false; + ``` + +- **Rule Content Guidelines:** + - Start with high-level overview + - Include specific, actionable requirements + - Show examples of correct implementation + - Reference existing code when possible + - Keep rules DRY by referencing other rules + +- **Rule Maintenance:** + - Update rules when new patterns emerge + - Add examples from actual codebase + - Remove outdated patterns + - Cross-reference related rules + - Update CLAUDE.md if new slash commands or guidelines are added + +- **Best Practices:** + - Use bullet points for clarity + - Keep descriptions concise + - Include both DO and DON'T examples + - Reference actual code over theoretical examples + - Use consistent formatting across rules \ No newline at end of file diff --git a/.cursor/rules/project-status.mdc b/.cursor/rules/project-status.mdc new file mode 100644 index 0000000..fa80c72 --- /dev/null +++ b/.cursor/rules/project-status.mdc @@ -0,0 +1,145 @@ +--- +description: +globs: +alwaysApply: true +--- +# Project Status Guidelines + +## **Project Stage Assessment** +- **Determine Current Stage**: Always assess project maturity before making development decisions +- **Stage-Based Priorities**: Adjust development focus based on current project stage +- **Documentation Updates**: Keep [CLAUDE.md](mdc:CLAUDE.md) "Project Status" section current + +## **Development Stage Categories** + +Based on the project stage assessment from `@create-app-design-document.md`: + +### **Stage-Based Development Guidelines** + +Development priorities should be determined based on the project stage assessment from the app design document. Each stage has different priorities for what AI should care about vs skip during development. + +**Reference:** The specific DO/DON'T lists for each stage are defined in: +- App Design Document generated via `@create-app-design-document.md` +- CLAUDE.md "Project Status" section (updated during app design document creation) + +## **Implementation Guidelines** + +### **Security-First Approach (All Stages)** +```typescript +// βœ… DO: Always validate inputs with Zod +const userInput = userSchema.parse(input); + +// βœ… DO: Use protectedProcedure for auth +export const updateUser = protectedProcedure + .input(updateUserSchema) + .mutation(async ({ ctx, input }) => { + // Implementation + }); + +// ❌ DON'T: Skip validation even in pre-MVP +const user = input; // Unsafe +``` + +### **Stage-Appropriate Error Handling** +```typescript +// βœ… Pre-MVP: Basic error handling +try { + await updateUser(data); +} catch (error) { + toast.error('Update failed'); +} + +// βœ… Production: Comprehensive error handling +try { + await updateUser(data); +} catch (error) { + logger.error('User update failed', { userId, error }); + if (error instanceof ValidationError) { + toast.error('Please check your input'); + } else { + toast.error('An unexpected error occurred'); + captureException(error); + } +} +``` + +## **Decision Framework** + +### **Feature Priority Questions** +1. **Stage Check**: What project stage are we in? +2. **Security Impact**: Does this affect user data or system security? +3. **Core Functionality**: Is this essential for primary user goals? +4. **User Impact**: How many users does this affect? +5. **Technical Debt**: Can we defer this to post-MVP? + +### **Code Quality Standards** +- **Pre-MVP**: Focus on readable, working code with security +- **MVP+**: Add testing for user-facing features +- **Production**: Full quality standards and documentation +- **Enterprise**: Advanced patterns and team coordination + +## **Status Documentation** + +### **Required in CLAUDE.md** +```markdown +## Project Status: [Stage Name] + +**Current Stage**: [Pre-MVP | MVP | Production | Enterprise] + +**DO NOT care about:** +- [List based on stage] + +**DO care about:** +- [List based on stage] + +**Next Stage Goals:** +- [Key milestones to reach next stage] +``` + +### **Regular Updates** +- Update status when deploying to production +- Reassess priorities quarterly or at major milestones +- Document stage transition criteria +- Communicate status changes to team + +## **Examples by Stage** + +### **Pre-MVP Example: Authentication Feature** +```typescript +// βœ… FOCUS: Core login flow with security +export const loginUser = publicProcedure + .input(loginSchema) + .mutation(async ({ input }) => { + const user = await verifyCredentials(input); + const session = await createSession(user.id); + return { success: true, sessionId: session.id }; + }); + +// ❌ SKIP: Comprehensive testing (save for MVP+) +// ❌ SKIP: Password strength indicators (save for MVP+) +// ❌ SKIP: Remember me functionality (save for MVP+) +``` + +### **Production Example: Authentication Feature** +```typescript +// βœ… COMPREHENSIVE: Full feature with testing, accessibility, monitoring +export const loginUser = publicProcedure + .input(loginSchema) + .mutation(async ({ input, ctx }) => { + try { + await rateLimiter.check(ctx.ip); + const user = await verifyCredentials(input); + const session = await createSession(user.id); + + logger.info('User login successful', { userId: user.id }); + await auditLog.record('USER_LOGIN', { userId: user.id }); + + return { success: true, sessionId: session.id }; + } catch (error) { + logger.warn('Login attempt failed', { ip: ctx.ip, error }); + throw new TRPCError({ code: 'UNAUTHORIZED', message: 'Invalid credentials' }); + } + }); +``` + +Follow stage-appropriate development practices to maintain velocity while ensuring quality at the right time. \ No newline at end of file diff --git a/.cursor/rules/self-improve.mdc b/.cursor/rules/self-improve.mdc new file mode 100644 index 0000000..7884b6c --- /dev/null +++ b/.cursor/rules/self-improve.mdc @@ -0,0 +1,73 @@ +--- +description: Guidelines for continuously improving Cursor rules based on emerging code patterns and best practices. +globs: **/* +alwaysApply: true +--- + +- **Rule Improvement Triggers:** + - New code patterns not covered by existing rules + - Repeated similar implementations across files + - Common error patterns that could be prevented + - New libraries or tools being used consistently + - Emerging best practices in the codebase + +- **Analysis Process:** + - Compare new code with existing rules + - Identify patterns that should be standardized + - Look for references to external documentation + - Check for consistent error handling patterns + - Monitor test patterns and coverage + +- **Rule Updates:** + - **Add New Rules When:** + - A new technology/pattern is used in 3+ files + - Common bugs could be prevented by a rule + - Code reviews repeatedly mention the same feedback + - New security or performance patterns emerge + + - **Modify Existing Rules When:** + - Better examples exist in the codebase + - Additional edge cases are discovered + - Related rules have been updated + - Implementation details have changed + +- **Example Pattern Recognition:** + ```typescript + // If you see repeated patterns like: + const data = await prisma.user.findMany({ + select: { id: true, email: true }, + where: { status: 'ACTIVE' } + }); + + // Consider adding to [prisma.mdc](mdc:.cursor/rules/prisma.mdc): + // - Standard select fields + // - Common where conditions + // - Performance optimization patterns + ``` + +- **Rule Quality Checks:** + - Rules should be actionable and specific + - Examples should come from actual code + - References should be up to date + - Patterns should be consistently enforced + +- **Continuous Improvement:** + - Monitor code review comments + - Track common development questions + - Update rules after major refactors + - Add links to relevant documentation + - Cross-reference related rules + +- **Rule Deprecation:** + - Mark outdated patterns as deprecated + - Remove rules that no longer apply + - Update references to deprecated rules + - Document migration paths for old patterns + +- **Documentation Updates:** + - Keep examples synchronized with code + - Update references to external docs + - Maintain links between related rules + - Document breaking changes + - Update CLAUDE.md when adding new rules or slash commands +Follow for proper rule formatting and structure. diff --git a/.cursor/rules/taskmaster/dev-workflow.mdc b/.cursor/rules/taskmaster/dev-workflow.mdc new file mode 100644 index 0000000..acade3e --- /dev/null +++ b/.cursor/rules/taskmaster/dev-workflow.mdc @@ -0,0 +1,489 @@ +--- +description: Guide for using Taskmaster's tagged task management system in development workflows +globs: **/* +alwaysApply: true +--- + +# Taskmaster Tagged Development Workflow + +This guide outlines the standard process for using Taskmaster's **tagged task management system** to manage software development projects. This is written as instructions for you, the AI agent. + +**⚠️ CRITICAL PRINCIPLE: Never Work on Master Tag** +- **NEVER suggest working directly on the `master` tag** for feature development +- **ALWAYS guide users to create or switch to appropriate feature tags** +- The `master` tag is reserved for high-level deliverables and major milestones only + +- **Your Goal**: Guide users to use the tagged system effectively from the start, creating organized, conflict-free development workflows + +## The Tagged Development Loop +The fundamental development cycle you will facilitate is: +1. **`tags`**: Show available tag contexts and current active tag +2. **`use-tag `**: Switch to appropriate feature context (NOT master) +3. **`list`**: Show tasks in the current tag context +4. **`next`**: Help the user decide what to work on in current tag +5. **`show `**: Provide details for a specific task in current tag +6. **`expand `**: Break down complex tasks within the tag context +7. **Implement**: The user writes the code and tests +8. **`update-subtask`**: Log progress and findings within the tag +9. **`set-status`**: Mark tasks as `done` within the tag context +10. **Repeat** or switch to another tag context + +All command executions operate within the current tag context. Always verify the active tag before starting work. + +--- + +## Standard Development Workflow Process + +### Standard Tagged Workflow (Always Start Here) + +For ALL projects, guide users to use the tagged system from the beginning: + +1. **Initialize with Tags in Mind:** + - Run `initialize_project` / `task-master init` with appropriate rule sets + - Immediately create feature tags: `add_tag user-auth --description="Authentication features"` + - Never parse PRDs directly into master + +2. **Create Tagged PRDs:** + ```bash + # Guide users to create context-specific PRDs + .taskmaster/docs/ + prd-user-authentication.md + prd-payment-system.md + prd-mobile-app.md + ``` + +3. **Parse PRDs into Feature Tags:** + ```bash + task-master use-tag user-auth + task-master parse-prd .taskmaster/docs/prd-user-authentication.md + + task-master use-tag payments + task-master parse-prd .taskmaster/docs/prd-payment-system.md + ``` + +4. **Daily Tagged Workflow:** + - Check contexts: `list_tags` / `task-master tags --show-metadata` + - Switch context: `use_tag` / `task-master use-tag ` + - Work within tag: `next_task` / `task-master next` + - Analyze complexity: `analyze_project_complexity --research` + - Expand tasks: `expand_task --id= --research` + - Log progress: `update_subtask --id= --prompt="..."` + - Mark complete: `set_task_status --id= --status=done` + +--- + +## Always Use Tagged Workflows + +**You must ALWAYS guide users to use tagged workflows from the start.** The tagged system is not an advanced feature - it's the standard way to use Task Master. This prevents conflicts, maintains organization, and scales naturally with project growth. + +### Standard Tag Creation Patterns + +Always suggest creating tags for these common scenarios: + +#### Pattern 1: Feature Development (Most Common) +This is the standard approach for any new feature. + +- **Trigger**: User mentions implementing any new feature or functionality +- **Your Action**: Immediately suggest creating a dedicated tag +- **Your Suggested Prompt**: *"I'll create a dedicated tag for this feature to keep tasks organized. This is the standard Task Master workflow that prevents conflicts and maintains clean task organization."* +- **Example Implementation**: + ```bash + # For authentication feature + task-master add-tag user-auth --description="User authentication features" + task-master use-tag user-auth + # Then create PRD and parse it + ``` + +#### Pattern 2: Git Branch Alignment +- **Trigger**: User creates a new git branch +- **Your Action**: Create a corresponding tag to maintain branch-task alignment +- **Your Suggested Prompt**: *"I'll create a task tag that matches your git branch. This keeps your tasks aligned with your code changes."* +- **Tool to Use**: `task-master add-tag --from-branch` + +#### Pattern 3: Team Collaboration +- **Trigger**: Multiple developers working on the same project +- **Your Action**: Ensure each developer has their own tag context +- **Your Suggested Prompt**: *"To prevent conflicts with your team, let's create separate task contexts for each developer's work."* +- **Example**: `task-master add-tag alice-frontend --description="Alice's frontend tasks"` + +#### Pattern 4: Experiments or Refactoring +- **Trigger**: Trying new approaches or major refactoring +- **Your Action**: Create experimental tags that can be deleted if not needed +- **Your Suggested Prompt**: *"I'll create an experimental tag for this work. If it doesn't work out, we can simply delete the tag."* +- **Example**: `task-master add-tag experiment-graphql --description="Testing GraphQL migration"` + +#### Pattern 5: PRD-Driven Development (Best Practice) +This is the recommended approach for all significant features. + +- **Trigger**: Any feature that requires planning +- **Your Action**: Guide through PRD creation and parsing +- **Your Implementation Flow**: + 1. **Create feature tag**: `add_tag feature-dashboard --description="Dashboard features"` + 2. **Switch to tag**: `use_tag feature-dashboard` + 3. **Create PRD**: Work with user to create `.taskmaster/docs/prd-dashboard.md` + 4. **Parse PRD**: `parse_prd .taskmaster/docs/prd-dashboard.md` + 5. **Analyze & Expand**: `analyze_project_complexity --research` then `expand_all --research` + +#### Pattern 5: Version-Based Development +Tailor your approach based on the project maturity indicated by tag names. + +- **Prototype/MVP Tags** (`prototype`, `mvp`, `poc`, `v0.x`): + - **Your Approach**: Focus on speed and functionality over perfection + - **Task Generation**: Create tasks that emphasize "get it working" over "get it perfect" + - **Complexity Level**: Lower complexity, fewer subtasks, more direct implementation paths + - **Research Prompts**: Include context like "This is a prototype - prioritize speed and basic functionality over optimization" + - **Example Prompt Addition**: *"Since this is for the MVP, I'll focus on tasks that get core functionality working quickly rather than over-engineering."* + +- **Production/Mature Tags** (`v1.0+`, `production`, `stable`): + - **Your Approach**: Emphasize robustness, testing, and maintainability + - **Task Generation**: Include comprehensive error handling, testing, documentation, and optimization + - **Complexity Level**: Higher complexity, more detailed subtasks, thorough implementation paths + - **Research Prompts**: Include context like "This is for production - prioritize reliability, performance, and maintainability" + - **Example Prompt Addition**: *"Since this is for production, I'll ensure tasks include proper error handling, testing, and documentation."* + +### The Master Tag Strategy + +**Remember**: The `master` tag is NOT for daily development work. Guide users to understand what belongs there: + +#### What Goes in Master Tag: +- **High-level deliverables** that provide significant business value +- **Major milestones** and epic-level features +- **Critical infrastructure** work affecting the entire project +- **Release-blocking** items +- **References to feature tags** (e.g., "Complete user authentication - see user-auth tag") + +#### What NEVER Goes in Master: +- **Feature implementation tasks** (use feature-specific tags) +- **Bug fixes** (use `bugfix-*` tags) +- **Refactoring work** (use `refactor-*` tags) +- **Experimental features** (use `experiment-*` tags) +- **Individual developer tasks** (use person-specific tags) + +#### PRD-Driven Feature Development + +**For New Major Features**: +1. **Identify the Initiative**: When user describes a significant feature +2. **Create Dedicated Tag**: `add_tag feature-[name] --description="[Feature description]"` +3. **Collaborative PRD Creation**: Work with user to create comprehensive PRD in `.taskmaster/docs/feature-[name]-prd.txt` +4. **Parse & Prepare**: + - `parse_prd .taskmaster/docs/feature-[name]-prd.txt --tag=feature-[name]` + - `analyze_project_complexity --tag=feature-[name] --research` + - `expand_all --tag=feature-[name] --research` +5. **Add Master Reference**: Create a high-level task in `master` that references the feature tag + +**For Existing Codebase Analysis**: +When users initialize Taskmaster on existing projects: +1. **Codebase Discovery**: Use your native tools for producing deep context about the code base. You may use `research` tool with `--tree` and `--files` to collect up to date information using the existing architecture as context. +2. **Collaborative Assessment**: Work with user to identify improvement areas, technical debt, or new features +3. **Strategic PRD Creation**: Co-author PRDs that include: + - Current state analysis (based on your codebase research) + - Proposed improvements or new features + - Implementation strategy considering existing code +4. **Tag-Based Organization**: Parse PRDs into appropriate tags (`refactor-api`, `feature-dashboard`, `tech-debt`, etc.) +5. **Master List Curation**: Keep only the most valuable initiatives in master + +The parse-prd's `--append` flag enables the user to parse multple PRDs within tags or across tags. PRDs should be focused and the number of tasks they are parsed into should be strategically chosen relative to the PRD's complexity and level of detail. + +### Common Workflow Examples + +**Example 1: Starting a New Feature** +``` +User: "I need to add user authentication" +Your Response: "I'll set up a dedicated tag for the authentication feature following Task Master's standard workflow." +Actions: +1. add_tag user-auth --description="User authentication features" +2. use_tag user-auth +3. "Let's create a PRD for this feature in .taskmaster/docs/prd-user-authentication.md" +4. parse_prd .taskmaster/docs/prd-user-authentication.md +``` + +**Example 2: Cross-Tag Development** +``` +User: "The mobile app needs to use the authentication APIs" +Your Response: "Let me check the auth implementation status and coordinate between tags." +Actions: +1. use_tag user-auth +2. get_task 2 # Check auth API status +3. use_tag mobile +4. update_subtask --id=3.1 --prompt="Auth APIs completed in user-auth tag, ready for integration" +``` + +**Example 3: Managing Multiple Contexts** +``` +User: "I'm working on both payments and user profiles" +Your Response: "Let's organize these into separate contexts so you can switch between them cleanly." +Actions: +1. tags --show-metadata # Show current contexts +2. add_tag payments --description="Payment system implementation" +3. add_tag user-profiles --description="User profile features" +4. "You can now switch between contexts with 'use-tag payments' or 'use-tag user-profiles'" +``` + +--- + +## Primary Interaction: MCP Server vs. CLI + +Taskmaster offers two primary ways to interact: + +1. **MCP Server (Recommended for Integrated Tools)**: + - For AI agents and integrated development environments (like Cursor), interacting via the **MCP server is the preferred method**. + - The MCP server exposes Taskmaster functionality through a set of tools (e.g., `get_tasks`, `add_subtask`). + - This method offers better performance, structured data exchange, and richer error handling compared to CLI parsing. + - Refer to @`mcp.mdc` for details on the MCP architecture and available tools. + - A comprehensive list and description of MCP tools and their corresponding CLI commands can be found in @`taskmaster.mdc`. + - **Restart the MCP server** if core logic in `scripts/modules` or MCP tool/direct function definitions change. + - **Note**: MCP tools fully support tagged task lists with complete tag management capabilities. + +2. **`task-master` CLI (For Users & Fallback)**: + - The global `task-master` command provides a user-friendly interface for direct terminal interaction. + - It can also serve as a fallback if the MCP server is inaccessible or a specific function isn't exposed via MCP. + - Install globally with `npm install -g task-master-ai` or use locally via `npx task-master-ai ...`. + - The CLI commands often mirror the MCP tools (e.g., `task-master list` corresponds to `get_tasks`). + - Refer to @`taskmaster.mdc` for a detailed command reference. + - **Tagged Task Lists**: CLI fully supports the new tagged system with seamless migration. + +## Critical Tagged System Principles + +### For Your Implementation: +- **Task Independence**: Each tag has its own task numbering starting from 1 +- **Context Isolation**: Changes in one tag never affect another tag +- **No Cross-Tag Dependencies**: Dependencies only work within the same tag +- **Always Verify Context**: Check active tag before any operation with `tags` +- **Manual Tag Switching**: Never assume tag context, always explicitly switch + +### Key Commands to Use Frequently: +- `list_tags` - Show all tags with current context marked +- `use_tag ` - Switch to specific tag context +- `add_tag --description="..."` - Create new contexts +- `parse_prd ` - Always parse into current tag, not master + +### File Organization: +``` +.taskmaster/ +β”œβ”€β”€ tasks/ +β”‚ └── tasks.json # Contains ALL tag contexts +β”œβ”€β”€ docs/ +β”‚ β”œβ”€β”€ prd-master.md # High-level only +β”‚ β”œβ”€β”€ prd-user-auth.md # Feature PRDs +β”‚ └── prd-payments.md # Feature PRDs +└── state.json # Current tag context + +--- + +## Task Complexity Analysis + +- Run `analyze_project_complexity` / `task-master analyze-complexity --research` (see @`taskmaster.mdc`) for comprehensive analysis +- Review complexity report via `complexity_report` / `task-master complexity-report` (see @`taskmaster.mdc`) for a formatted, readable version. +- Focus on tasks with highest complexity scores (8-10) for detailed breakdown +- Use analysis results to determine appropriate subtask allocation +- Note that reports are automatically used by the `expand_task` tool/command + +## Task Breakdown Process + +- Use `expand_task` / `task-master expand --id=`. It automatically uses the complexity report if found, otherwise generates default number of subtasks. +- Use `--num=` to specify an explicit number of subtasks, overriding defaults or complexity report recommendations. +- Add `--research` flag to leverage Perplexity AI for research-backed expansion. +- Add `--force` flag to clear existing subtasks before generating new ones (default is to append). +- Use `--prompt=""` to provide additional context when needed. +- Review and adjust generated subtasks as necessary. +- Use `expand_all` tool or `task-master expand --all` to expand multiple pending tasks at once, respecting flags like `--force` and `--research`. +- If subtasks need complete replacement (regardless of the `--force` flag on `expand`), clear them first with `clear_subtasks` / `task-master clear-subtasks --id=`. + +## Implementation Drift Handling + +- When implementation differs significantly from planned approach +- When future tasks need modification due to current implementation choices +- When new dependencies or requirements emerge +- Use `update` / `task-master update --from= --prompt='\nUpdate context...' --research` to update multiple future tasks. +- Use `update_task` / `task-master update-task --id= --prompt='\nUpdate context...' --research` to update a single specific task. + +## Task Status Management + +- Use 'pending' for tasks ready to be worked on +- Use 'done' for completed and verified tasks +- Use 'deferred' for postponed tasks +- Add custom status values as needed for project-specific workflows + +## Task Structure Fields + +- **id**: Unique identifier for the task (Example: `1`, `1.1`) +- **title**: Brief, descriptive title (Example: `"Initialize Repo"`) +- **description**: Concise summary of what the task involves (Example: `"Create a new repository, set up initial structure."`) +- **status**: Current state of the task (Example: `"pending"`, `"done"`, `"deferred"`) +- **dependencies**: IDs of prerequisite tasks (Example: `[1, 2.1]`) + - Dependencies are displayed with status indicators (βœ… for completed, ⏱️ for pending) + - This helps quickly identify which prerequisite tasks are blocking work +- **priority**: Importance level (Example: `"high"`, `"medium"`, `"low"`) +- **details**: In-depth implementation instructions (Example: `"Use GitHub client ID/secret, handle callback, set session token."`) +- **testStrategy**: Verification approach (Example: `"Deploy and call endpoint to confirm 'Hello World' response."`) +- **subtasks**: List of smaller, more specific tasks (Example: `[{"id": 1, "title": "Configure OAuth", ...}]`) +- Refer to task structure details (previously linked to `tasks.mdc`). + +## Configuration Management (Updated) + +Taskmaster configuration is managed through two main mechanisms: + +1. **`.taskmaster/config.json` File (Primary):** + * Located in the project root directory. + * Stores most configuration settings: AI model selections (main, research, fallback), parameters (max tokens, temperature), logging level, default subtasks/priority, project name, etc. + * **Tagged System Settings**: Includes `global.defaultTag` (defaults to "master") and `tags` section for tag management configuration. + * **Managed via `task-master models --setup` command.** Do not edit manually unless you know what you are doing. + * **View/Set specific models via `task-master models` command or `models` MCP tool.** + * Created automatically when you run `task-master models --setup` for the first time or during tagged system migration. + +2. **Environment Variables (`.env` / `mcp.json`):** + * Used **only** for sensitive API keys and specific endpoint URLs. + * Place API keys (one per provider) in a `.env` file in the project root for CLI usage. + * For MCP/Cursor integration, configure these keys in the `env` section of `.cursor/mcp.json`. + * Available keys/variables: See `assets/env.example` or the Configuration section in the command reference (previously linked to `taskmaster.mdc`). + +3. **`.taskmaster/state.json` File (Tagged System State):** + * Tracks current tag context and migration status. + * Automatically created during tagged system migration. + * Contains: `currentTag`, `lastSwitched`, `migrationNoticeShown`. + +**Important:** Non-API key settings (like model selections, `MAX_TOKENS`, `TASKMASTER_LOG_LEVEL`) are **no longer configured via environment variables**. Use the `task-master models` command (or `--setup` for interactive configuration) or the `models` MCP tool. +**If AI commands FAIL in MCP** verify that the API key for the selected provider is present in the `env` section of `.cursor/mcp.json`. +**If AI commands FAIL in CLI** verify that the API key for the selected provider is present in the `.env` file in the root of the project. + +## Rules Management + +Taskmaster supports multiple AI coding assistant rule sets that can be configured during project initialization or managed afterward: + +- **Available Profiles**: Claude Code, Cline, Codex, Cursor, Roo Code, Trae, Windsurf (claude, cline, codex, cursor, roo, trae, windsurf) +- **During Initialization**: Use `task-master init --rules cursor,windsurf` to specify which rule sets to include +- **After Initialization**: Use `task-master rules add ` or `task-master rules remove ` to manage rule sets +- **Interactive Setup**: Use `task-master rules setup` to launch an interactive prompt for selecting rule profiles +- **Default Behavior**: If no `--rules` flag is specified during initialization, all available rule profiles are included +- **Rule Structure**: Each profile creates its own directory (e.g., `.cursor/rules`, `.roo/rules`) with appropriate configuration files + +## Determining the Next Task + +- Run `next_task` / `task-master next` to show the next task to work on. +- The command identifies tasks with all dependencies satisfied +- Tasks are prioritized by priority level, dependency count, and ID +- The command shows comprehensive task information including: + - Basic task details and description + - Implementation details + - Subtasks (if they exist) + - Contextual suggested actions +- Recommended before starting any new development work +- Respects your project's dependency structure +- Ensures tasks are completed in the appropriate sequence +- Provides ready-to-use commands for common task actions + +## Viewing Specific Task Details + +- Run `get_task` / `task-master show ` to view a specific task. +- Use dot notation for subtasks: `task-master show 1.2` (shows subtask 2 of task 1) +- Displays comprehensive information similar to the next command, but for a specific task +- For parent tasks, shows all subtasks and their current status +- For subtasks, shows parent task information and relationship +- Provides contextual suggested actions appropriate for the specific task +- Useful for examining task details before implementation or checking status + +## Managing Task Dependencies + +- Use `add_dependency` / `task-master add-dependency --id= --depends-on=` to add a dependency. +- Use `remove_dependency` / `task-master remove-dependency --id= --depends-on=` to remove a dependency. +- The system prevents circular dependencies and duplicate dependency entries +- Dependencies are checked for existence before being added or removed +- Task files are automatically regenerated after dependency changes +- Dependencies are visualized with status indicators in task listings and files + +## Task Reorganization + +- Use `move_task` / `task-master move --from= --to=` to move tasks or subtasks within the hierarchy +- This command supports several use cases: + - Moving a standalone task to become a subtask (e.g., `--from=5 --to=7`) + - Moving a subtask to become a standalone task (e.g., `--from=5.2 --to=7`) + - Moving a subtask to a different parent (e.g., `--from=5.2 --to=7.3`) + - Reordering subtasks within the same parent (e.g., `--from=5.2 --to=5.4`) + - Moving a task to a new, non-existent ID position (e.g., `--from=5 --to=25`) + - Moving multiple tasks at once using comma-separated IDs (e.g., `--from=10,11,12 --to=16,17,18`) +- The system includes validation to prevent data loss: + - Allows moving to non-existent IDs by creating placeholder tasks + - Prevents moving to existing task IDs that have content (to avoid overwriting) + - Validates source tasks exist before attempting to move them +- The system maintains proper parent-child relationships and dependency integrity +- Task files are automatically regenerated after the move operation +- This provides greater flexibility in organizing and refining your task structure as project understanding evolves +- This is especially useful when dealing with potential merge conflicts arising from teams creating tasks on separate branches. Solve these conflicts very easily by moving your tasks and keeping theirs. + +## Iterative Subtask Implementation + +Once a task has been broken down into subtasks using `expand_task` or similar methods, follow this iterative process for implementation: + +1. **Understand the Goal (Preparation):** + * Use `get_task` / `task-master show ` (see @`taskmaster.mdc`) to thoroughly understand the specific goals and requirements of the subtask. + +2. **Initial Exploration & Planning (Iteration 1):** + * This is the first attempt at creating a concrete implementation plan. + * Explore the codebase to identify the precise files, functions, and even specific lines of code that will need modification. + * Determine the intended code changes (diffs) and their locations. + * Gather *all* relevant details from this exploration phase. + +3. **Log the Plan:** + * Run `update_subtask` / `task-master update-subtask --id= --prompt=''`. + * Provide the *complete and detailed* findings from the exploration phase in the prompt. Include file paths, line numbers, proposed diffs, reasoning, and any potential challenges identified. Do not omit details. The goal is to create a rich, timestamped log within the subtask's `details`. + +4. **Verify the Plan:** + * Run `get_task` / `task-master show ` again to confirm that the detailed implementation plan has been successfully appended to the subtask's details. + +5. **Begin Implementation:** + * Set the subtask status using `set_task_status` / `task-master set-status --id= --status=in-progress`. + * Start coding based on the logged plan. + +6. **Refine and Log Progress (Iteration 2+):** + * As implementation progresses, you will encounter challenges, discover nuances, or confirm successful approaches. + * **Before appending new information**: Briefly review the *existing* details logged in the subtask (using `get_task` or recalling from context) to ensure the update adds fresh insights and avoids redundancy. + * **Regularly** use `update_subtask` / `task-master update-subtask --id= --prompt='\n- What worked...\n- What didn't work...'` to append new findings. + * **Crucially, log:** + * What worked ("fundamental truths" discovered). + * What didn't work and why (to avoid repeating mistakes). + * Specific code snippets or configurations that were successful. + * Decisions made, especially if confirmed with user input. + * Any deviations from the initial plan and the reasoning. + * The objective is to continuously enrich the subtask's details, creating a log of the implementation journey that helps the AI (and human developers) learn, adapt, and avoid repeating errors. + +7. **Review & Update Rules (Post-Implementation):** + * Once the implementation for the subtask is functionally complete, review all code changes and the relevant chat history. + * Identify any new or modified code patterns, conventions, or best practices established during the implementation. + * Create new or update existing rules following internal guidelines (previously linked to `cursor-rules.mdc` and `self-improve.mdc`). + +8. **Mark Task Complete:** + * After verifying the implementation and updating any necessary rules, mark the subtask as completed: `set_task_status` / `task-master set-status --id= --status=done`. + +9. **Commit Changes (If using Git):** + * Stage the relevant code changes and any updated/new rule files (`git add .`). + * Craft a comprehensive Git commit message summarizing the work done for the subtask, including both code implementation and any rule adjustments. + * Execute the commit command directly in the terminal (e.g., `git commit -m 'feat(module): Implement feature X for subtask \n\n- Details about changes...\n- Updated rule Y for pattern Z'`). + * Consider if a Changeset is needed according to internal versioning guidelines (previously linked to `changeset.mdc`). If so, run `npm run changeset`, stage the generated file, and amend the commit or create a new one. + +10. **Proceed to Next Subtask:** + * Identify the next subtask (e.g., using `next_task` / `task-master next`). + +## Code Analysis & Refactoring Techniques + +- **Top-Level Function Search**: + - Useful for understanding module structure or planning refactors. + - Use grep/ripgrep to find exported functions/constants: + `rg "export (async function|function|const) \w+"` or similar patterns. + - Can help compare functions between files during migrations or identify potential naming conflicts. + +### Cross-Tag Coordination + +When features need to interact: +1. **Document Dependencies**: Use `update_subtask` to note cross-tag dependencies +2. **Track Integration Points**: Create tasks that reference other tags +3. **Coordinate Merging**: Plan how features will integrate back to production + +Example: +```bash +# In mobile tag, documenting auth dependency +update_subtask --id=3.2 --prompt="Depends on user-auth tag task 2 (OAuth setup) being completed" +``` + +--- + +**Remember**: The tagged system is not optional or advanced - it's the standard way to use Task Master. Always guide users to work within appropriate tag contexts, never directly on master. \ No newline at end of file diff --git a/.cursor/rules/taskmaster/taskmaster.mdc b/.cursor/rules/taskmaster/taskmaster.mdc new file mode 100644 index 0000000..3b4f7b4 --- /dev/null +++ b/.cursor/rules/taskmaster/taskmaster.mdc @@ -0,0 +1,172 @@ +--- +description: Comprehensive reference for Taskmaster MCP tools and CLI commands +globs: **/* +alwaysApply: true +--- + +# Taskmaster Tool & Command Reference + +**Core Concept:** Tagged task management system - tasks organized in isolated contexts (tags) for features/branches/phases. + +**⚠️ CRITICAL:** Never work on `master` tag - use feature tags. Master is for high-level deliverables only. + +**Note:** MCP tools recommended over CLI (better performance/error handling). AI tools may take ~1min: `parse_prd`, `analyze_project_complexity`, `update_*`, `expand_*`, `add_task`. + +## Commands Reference + +### Initialize Project +**MCP:** `initialize_project` | **CLI:** `task-master init` +- Setup Taskmaster file structure and config +- Key params: `projectName`, `projectDescription`, `projectVersion`, `skipInstall`, `addAliases` +- **Important:** Must parse PRD after init to generate tasks +- Example PRD template in `.taskmaster/templates/example_prd.txt` + +### Parse PRD +**MCP:** `parse_prd` | **CLI:** `task-master parse-prd` +- Parse PRD/text file to generate tasks.json +- Params: `input`, `output`, `numTasks`, `force`, `tag` +- Always parse into feature tags, not master +- Create PRDs per context: `prd-.md` +- **AI tool - may take ~1min** + +### Models Configuration +**MCP:** `models` | **CLI:** `task-master models` +- View/set AI models for roles: main, research, fallback +- Params: `setMain`, `setResearch`, `setFallback`, `ollama`, `openrouter` +- Config stored in `.taskmaster/config.json` (don't edit manually) +- API keys required in mcp.json (MCP) or .env (CLI) +- Costs in $: 3 = $3.00, 0.8 = $0.80 + +### Task Viewing +**Get Tasks:** `get_tasks` / `task-master list` +- Filter by status, show subtasks, specify tag + +**Next Task:** `next_task` / `task-master next` +- Shows next available task based on dependencies + +**Get Task:** `get_task` / `task-master show` +- View specific task(s) - use comma-separated IDs for multiple (1,2,3) +- **CRITICAL:** Use batch IDs to avoid multiple calls + +### Task Creation +**Add Task:** `add_task` / `task-master add-task` +- Params: `prompt` (required), `dependencies`, `priority`, `research`, `tag` +- **AI tool - may take ~1min** + +**Add Subtask:** `add_subtask` / `task-master add-subtask` +- Add to parent or convert existing task +- Params: `id` (parent), `taskId`, `title`, `description`, `details`, `dependencies`, `status` + +### Task Updates +**Update Tasks:** `update` / `task-master update` +- Update multiple tasks from ID onwards +- Params: `from` (required), `prompt` (required), `research` +- **AI tool - may take ~1min** + +**Update Task:** `update_task` / `task-master update-task` +- Update single task by ID +- Params: `id`, `prompt`, `append`, `research` +- Use `--append` to log progress +- **AI tool - may take ~1min** + +**Update Subtask:** `update_subtask` / `task-master update-subtask` +- Append timestamped progress to subtask +- Params: `id`, `prompt`, `research` +- **AI tool - may take ~1min** + +**Set Status:** `set_task_status` / `task-master set-status` +- Update status: pending, in-progress, done, review, cancelled +- Supports multiple IDs: '15,15.2,16' + +**Remove Task:** `remove_task` / `task-master remove-task` +- Permanently delete task/subtask +- Consider using status instead of deletion + +### Task Breakdown +**Expand Task:** `expand_task` / `task-master expand` +- Break task into subtasks +- Params: `id`, `num`, `research`, `prompt`, `force` +- Uses complexity report if available +- **AI tool - may take ~1min** + +**Expand All:** `expand_all` / `task-master expand --all` +- Expand all eligible tasks +- Same params as expand_task +- **AI tool - may take ~1min** + +**Clear Subtasks:** `clear_subtasks` / `task-master clear-subtasks` +- Remove all subtasks from parent(s) + +**Remove Subtask:** `remove_subtask` / `task-master remove-subtask` +- Remove or convert subtask to top-level task + +**Move Task:** `move_task` / `task-master move` +- Move task/subtask in hierarchy +- Params: `from`, `to` (supports comma-separated) +- Useful for merge conflicts + +### Dependency Management +**Add/Remove Dependency:** `add_dependency`/`remove_dependency` +- Define task prerequisites + +**Validate/Fix Dependencies:** `validate_dependencies`/`fix_dependencies` +- Check and fix circular references or missing tasks + +### Analysis +**Analyze Complexity:** `analyze_project_complexity` / `task-master analyze-complexity` +- Score tasks 1-10, suggest expansions +- **AI tool - may take ~1min** + +**View Report:** `complexity_report` / `task-master complexity-report` + +### Files +**Generate:** `generate` / `task-master generate` +- Create markdown files from tasks.json + +### Research +**Research:** `research` / `task-master research` +- Get fresh info beyond AI cutoff +- Params: `query`, `taskIds`, `filePaths`, `customContext`, `includeProjectTree`, `detailLevel` +- **USE FREQUENTLY** for: + - Latest best practices + - New tech guidance + - Security updates + - Dependency changes +- **AI tool - may take ~1min** + +### Tag Management (Essential) +**List Tags:** `list_tags` / `task-master tags` + +**Add Tag:** `add_tag` / `task-master add-tag` +- Create feature/branch contexts +- Options: `--from-branch`, `--copy-from`, `--description` + +**Use Tag:** `use_tag` / `task-master use-tag` +- **CRITICAL:** Switch to feature tag before work + +**Delete/Rename/Copy Tag:** Standard operations + +### Misc +**Sync Readme:** CLI only - `task-master sync-readme` (experimental) + +## Configuration + +**Config File:** `.taskmaster/config.json` (via `models` command) +**API Keys:** `.env` (CLI) or `mcp.json` env section (MCP) +- Required: Provider-specific API keys +- Optional: `AZURE_OPENAI_ENDPOINT`, `OLLAMA_BASE_URL` + +## Key Concepts + +**Tagged System:** +- Each tag = isolated task context (1, 2, 3...) +- No cross-tag dependencies +- Always verify active tag +- Never edit tasks.json manually + +**Workflow:** See [dev-workflow.mdc](mdc:.cursor/rules/taskmaster/dev-workflow.mdc) for patterns + +**Quick Reference:** +1. `add_tag` β†’ `use_tag` β†’ `parse_prd` +2. `analyze_complexity` β†’ `expand_task/expand_all` +3. `next_task` β†’ implement β†’ `update_subtask` β†’ `set_task_status` \ No newline at end of file diff --git a/.git-commit-template.txt b/.git-commit-template.txt new file mode 100644 index 0000000..2f9605f --- /dev/null +++ b/.git-commit-template.txt @@ -0,0 +1,20 @@ +: (ν•œκΈ€λ‘œ μ΅œλŒ€ 40 κΈ€μ§œκΉŒμ§€) +# <type> +# - feat : μƒˆλ‘œμš΄ κΈ°λŠ₯ μΆ”κ°€ +# - fix : 버그 μˆ˜μ • +# - docs : λ¬Έμ„œ μˆ˜μ • +# - style : μ½”λ“œ ν¬λ§·νŒ…, μ„Έλ―Έμ½œλ‘  λˆ„λ½, μ½”λ“œ 변경이 μ—†λŠ” 경우 +# - refact : μ½”λ“œ λ¦¬νŽ™ν† λ§ +# - test : ν…ŒμŠ€νŠΈ μ½”λ“œ, λ¦¬νŽ™ν† λ§ ν…ŒμŠ€νŠΈ μ½”λ“œ μΆ”κ°€ +# - chore : λΉŒλ“œ 업무 μˆ˜μ •, νŒ¨ν‚€μ§€ λ§€λ‹ˆμ € μˆ˜μ • + +# <title> +# 제λͺ©μ˜ κΈΈμ΄λŠ” μ΅œλŒ€ 40κΈ€μžκΉŒμ§€ ν•œκΈ€λ‘œ 간단 λͺ…λ£Œν•˜κ²Œ μž‘μ„± +# <type>: ν•œμΉΈ 띄고 <title μž‘μ„±> +# 제λͺ©μ„ μž‘μ„±ν•˜κ³  λ°˜λ“œμ‹œ 빈 쀄 ν•œ 쀄을 λ§Œλ“€μ–΄μ•Ό 함 +# 제λͺ©μ— .(λ§ˆμΉ¨ν‘œ) κΈˆμ§€ + + +<description>(ν•œκΈ€λ‘œ ν•œμ€„μž₯ 50자 λ‚΄μ™Έλ‘œ μ€„λ°”κΏˆ) +# λ‚΄μš©μ˜ κΈΈμ΄λŠ” ν•œ 쀄당 60κΈ€μž λ‚΄μ™Έμ—μ„œ 쀄 λ°”κΏˆ. ν•œκΈ€λ‘œ 간단 λͺ…λ£Œν•˜κ²Œ μž‘μ„± +# μ–΄λ–»κ²Œ λ³΄λ‹€λŠ” 무엇을, μ™œ λ³€κ²½ν–ˆλŠ”μ§€λ₯Ό μž‘μ„±ν•  것 (ν•„μˆ˜) \ No newline at end of file diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..eee8e7d --- /dev/null +++ b/.gitignore @@ -0,0 +1,27 @@ +!.* + +# Logs +logs +*.log +npm-debug.log* +yarn-debug.log* +yarn-error.log* +dev-debug.log + +# Dependency directories +node_modules/ + +# Environment variables +.env + +# Editor directories and files +.git +.idea +.vscode +*.suo +*.ntvs* +*.njsproj +*.sln +*.sw? + +.DS_Store diff --git a/.taskmaster/config.json b/.taskmaster/config.json new file mode 100644 index 0000000..10d95fd --- /dev/null +++ b/.taskmaster/config.json @@ -0,0 +1,32 @@ +{ + "models": { + "main": { + "provider": "claude-code", + "modelId": "sonnet", + "maxTokens": 64000, + "temperature": 0.2 + }, + "research": { + "provider": "claude-code", + "modelId": "opus", + "maxTokens": 32000, + "temperature": 0.1 + }, + "fallback": { + "provider": "claude-code", + "modelId": "sonnet", + "maxTokens": 64000, + "temperature": 0.2 + } + }, + "global": { + "logLevel": "info", + "debug": false, + "defaultSubtasks": 5, + "defaultPriority": "medium", + "projectName": "Task Master", + "ollamaBaseURL": "http://localhost:11434/api", + "bedrockBaseURL": "https://bedrock.us-east-1.amazonaws.com", + "userId": "1234567890" + } +} \ No newline at end of file diff --git a/.taskmaster/docs/app-design-document.md b/.taskmaster/docs/app-design-document.md new file mode 100644 index 0000000..e69de29 diff --git a/.taskmaster/docs/project-structure.md b/.taskmaster/docs/project-structure.md new file mode 100644 index 0000000..9608b87 --- /dev/null +++ b/.taskmaster/docs/project-structure.md @@ -0,0 +1,75 @@ +# Project Structure + +_Last Updated: 2025-07-03_ + +``` +. +β”œβ”€β”€ .claude +β”‚Β Β  β”œβ”€β”€ commands +β”‚Β Β  β”‚Β Β  β”œβ”€β”€ docs +β”‚Β Β  β”‚Β Β  β”‚Β Β  β”œβ”€β”€ create-app-design.md +β”‚Β Β  β”‚Β Β  β”‚Β Β  β”œβ”€β”€ create-doc.md +β”‚Β Β  β”‚Β Β  β”‚Β Β  β”œβ”€β”€ create-prd-interactive.md +β”‚Β Β  β”‚Β Β  β”‚Β Β  β”œβ”€β”€ create-prd.md +β”‚Β Β  β”‚Β Β  β”‚Β Β  β”œβ”€β”€ create-rule.md +β”‚Β Β  β”‚Β Β  β”‚Β Β  β”œβ”€β”€ create-tech-stack.md +β”‚Β Β  β”‚Β Β  β”‚Β Β  β”œβ”€β”€ parse-prd.md +β”‚Β Β  β”‚Β Β  β”‚Β Β  β”œβ”€β”€ update-app-design.md +β”‚Β Β  β”‚Β Β  β”‚Β Β  β”œβ”€β”€ update-project-structure.md +β”‚Β Β  β”‚Β Β  β”‚Β Β  β”œβ”€β”€ update-rule.md +β”‚Β Β  β”‚Β Β  β”‚Β Β  └── update-tech-stack.md +β”‚Β Β  β”‚Β Β  β”œβ”€β”€ research +β”‚Β Β  β”‚Β Β  β”‚Β Β  β”œβ”€β”€ architecture.md +β”‚Β Β  β”‚Β Β  β”‚Β Β  β”œβ”€β”€ security.md +β”‚Β Β  β”‚Β Β  β”‚Β Β  β”œβ”€β”€ task.md +β”‚Β Β  β”‚Β Β  β”‚Β Β  └── tech.md +β”‚Β Β  β”‚Β Β  β”œβ”€β”€ snippets +β”‚Β Β  β”‚Β Β  β”‚Β Β  └── create-snippet.md +β”‚Β Β  β”‚Β Β  β”œβ”€β”€ task +β”‚Β Β  β”‚Β Β  β”‚Β Β  β”œβ”€β”€ add-interactive.md +β”‚Β Β  β”‚Β Β  β”‚Β Β  β”œβ”€β”€ add.md +β”‚Β Β  β”‚Β Β  β”‚Β Β  β”œβ”€β”€ done.md +β”‚Β Β  β”‚Β Β  β”‚Β Β  β”œβ”€β”€ expand.md +β”‚Β Β  β”‚Β Β  β”‚Β Β  β”œβ”€β”€ list.md +β”‚Β Β  β”‚Β Β  β”‚Β Β  β”œβ”€β”€ move.md +β”‚Β Β  β”‚Β Β  β”‚Β Β  β”œβ”€β”€ next.md +β”‚Β Β  β”‚Β Β  β”‚Β Β  β”œβ”€β”€ research.md +β”‚Β Β  β”‚Β Β  β”‚Β Β  β”œβ”€β”€ show.md +β”‚Β Β  β”‚Β Β  β”‚Β Β  β”œβ”€β”€ spec.md +β”‚Β Β  β”‚Β Β  β”‚Β Β  β”œβ”€β”€ update-task-interactive.md +β”‚Β Β  β”‚Β Β  β”‚Β Β  └── update-task.md +β”‚Β Β  β”‚Β Β  └── debug.md +β”‚Β Β  β”œβ”€β”€ scripts +β”‚Β Β  β”‚Β Β  └── tree.sh +β”‚Β Β  └── settings.json +β”œβ”€β”€ .cursor +β”‚Β Β  β”œβ”€β”€ rules +β”‚Β Β  β”‚Β Β  β”œβ”€β”€ taskmaster +β”‚Β Β  β”‚Β Β  β”‚Β Β  β”œβ”€β”€ dev-workflow.mdc +β”‚Β Β  β”‚Β Β  β”‚Β Β  └── taskmaster.mdc +β”‚Β Β  β”‚Β Β  β”œβ”€β”€ cursor-rules.mdc +β”‚Β Β  β”‚Β Β  β”œβ”€β”€ project-status.mdc +β”‚Β Β  β”‚Β Β  └── self-improve.mdc +β”‚Β Β  └── mcp.json +β”œβ”€β”€ .taskmaster +β”‚Β Β  β”œβ”€β”€ docs +β”‚Β Β  β”‚Β Β  β”œβ”€β”€ app-design-document.md +β”‚Β Β  β”‚Β Β  β”œβ”€β”€ project-structure.md +β”‚Β Β  β”‚Β Β  β”œβ”€β”€ taskmaster-guide.md +β”‚Β Β  β”‚Β Β  └── tech-stack.md +β”‚Β Β  β”œβ”€β”€ reports +β”‚Β Β  β”‚Β Β  └── .gitkeep +β”‚Β Β  β”œβ”€β”€ tasks +β”‚Β Β  β”‚Β Β  └── tasks.json +β”‚Β Β  β”œβ”€β”€ templates +β”‚Β Β  β”‚Β Β  └── example_prd.md +β”‚Β Β  β”œβ”€β”€ config.json +β”‚Β Β  └── state.json +β”œβ”€β”€ .gitignore +β”œβ”€β”€ .mcp.json +β”œβ”€β”€ CLAUDE.md +└── README.md + +16 directories, 50 files +``` + diff --git a/.taskmaster/docs/taskmaster-guide.md b/.taskmaster/docs/taskmaster-guide.md new file mode 100644 index 0000000..65a7a14 --- /dev/null +++ b/.taskmaster/docs/taskmaster-guide.md @@ -0,0 +1,588 @@ +# Task Master AI - Claude Code Integration Guide + +## Tagged Task Management System + +Task Master uses a **tagged task management system** that organizes tasks into separate, isolated contexts called **tags**. This enables working across multiple contexts such as different features, branches, or project phases without conflicts. + +### Tagged System Benefits + +- **Complete Context Isolation**: Each tag maintains its own task numbering (starting from 1) +- **Parallel Development**: Multiple features can be developed simultaneously without conflicts +- **Independent Dependencies**: Task dependencies are managed within each tag context +- **Flexible Organization**: Align tags with git branches, features, or project phases +- **Team Collaboration**: Clear ownership and responsibility per tag context + +## Essential Commands + +### Tag Management Commands + +```bash +# Tag Context Management +task-master tags # List all available tags with status +task-master tags --show-metadata # List tags with detailed metadata +task-master add-tag <tag-name> # Create a new empty tag +task-master add-tag <tag-name> --description="desc" # Create tag with description +task-master add-tag --from-branch # Create tag from current git branch +task-master use-tag <tag-name> # Switch to a different tag context +task-master copy-tag <source> <target> # Copy entire tag to create new one +task-master delete-tag <tag-name> # Delete tag and all its tasks +task-master rename-tag <old-name> <new-name> # Rename an existing tag + +# Tag-based Task Operations (all work within current tag context) +task-master list # Show tasks in current tag +task-master next # Get next task in current tag +task-master show <id> # View task in current tag (e.g., 1.2) +task-master add-task --prompt="description" # Add task to current tag +``` + +### Core Workflow Commands + +```bash +# Project Setup +task-master init # Initialize Task Master with tagged system +task-master models --setup # Configure AI models interactively + +# Tagged PRD Workflow +task-master use-tag <tag-name> # Switch to tag context +task-master parse-prd .taskmaster/docs/prd-<tag>.md # Generate tasks from PRD in current tag + +# Daily Development Workflow (within current tag) +task-master list # Show all tasks in current tag +task-master next # Get next available task in current tag +task-master show <id> # View detailed task information +task-master set-status --id=<id> --status=done # Mark task complete in current tag + +# Task Management (within current tag) +task-master expand --id=<id> --research --force # Break task into subtasks +task-master update-task --id=<id> --prompt="changes" # Update specific task +task-master update --from=<id> --prompt="changes" # Update multiple tasks from ID onwards +task-master update-subtask --id=<id> --prompt="notes" # Add implementation notes to subtask + +# Analysis & Planning (within current tag) +task-master analyze-complexity --research # Analyze task complexity in current tag +task-master complexity-report # View complexity analysis for current tag +task-master expand --all --research # Expand all eligible tasks in current tag + +# Dependencies & Organization (within current tag) +task-master add-dependency --id=<id> --depends-on=<id> # Add task dependency +task-master move --from=<id> --to=<id> # Reorganize task hierarchy +task-master validate-dependencies # Check for dependency issues +task-master generate # Update task markdown files +``` + +## Tagged Workflow Integration + +### ⚠️ CRITICAL RULE: Never Work on Master Tag + +**NEVER work directly on the `master` tag.** Always switch to a feature-specific tag before working with Task Master: + +```bash +# ❌ BAD - Working on master tag +task-master use-tag master +task-master next # Don't do this! + +# βœ… GOOD - Switch to feature tag first +task-master add-tag modal-panel-isolation --description="Modal panel isolation feature" +task-master use-tag modal-panel-isolation +task-master parse-prd .taskmaster/docs/prd-modal-panel-isolation.md +task-master next # Now this is correct! +``` + +### Setting Up Tagged Contexts + +#### 1. Initialize Multiple Tag Contexts + +```bash +# Create tag contexts for different features/areas +task-master add-tag user-auth --description="User authentication features" +task-master add-tag payments --description="Payment system implementation" +task-master add-tag mobile --description="Mobile app development" +task-master add-tag admin --description="Admin dashboard features" +``` + +#### 2. Organize Tagged PRDs + +Create PRDs for different contexts: + +``` +.taskmaster/docs/ + prd-master.md # Main project PRD + prd-user-authentication.md # Authentication feature PRD + prd-payment-system.md # Payment system PRD + prd-mobile-app.md # Mobile app PRD + prd-admin-dashboard.md # Admin features PRD +``` + +#### 3. Parse PRDs into Tag Contexts + +```bash +# Switch to authentication context and parse its PRD +task-master use-tag user-auth +task-master parse-prd .taskmaster/docs/prd-user-authentication.md + +# Switch to payments context and parse its PRD +task-master use-tag payments +task-master parse-prd .taskmaster/docs/prd-payment-system.md + +# Continue for each feature area... +``` + +### Daily Tagged Development Workflow + +#### 1. Tag Context Management + +```bash +# Check available tag contexts +task-master tags --show-metadata + +# Switch to desired context (NEVER master for feature work!) +task-master use-tag user-auth + +# Work within that context +task-master next # Find next task in current tag +task-master show <id> # Review task details in current tag +``` + +#### 2. Cross-Tag Development + +```bash +# Work on authentication, then switch to mobile +task-master use-tag user-auth +task-master list # See auth tasks +# ... work on auth tasks ... + +task-master use-tag mobile +task-master list # See mobile tasks +# ... work on mobile tasks ... +``` + +#### 3. Tag-Specific Implementation + +```bash +# Within a tag context, all operations are isolated +task-master update-subtask --id=2.1 --prompt="implementation notes..." # Updates task 2.1 in current tag only +task-master set-status --id=3 --status=done # Marks task 3 done in current tag only +``` + +### Advanced Tagged Workflows + +#### Branch-Based Tag Management + +```bash +# Align tag contexts with git branches +git checkout -b feature/authentication +task-master add-tag --from-branch # Creates tag from branch name + +git checkout -b feature/payments +task-master add-tag --from-branch # Creates another tag +``` + +#### Tag Copying and Templates + +```bash +# Create new contexts from existing ones +task-master copy-tag user-auth admin-auth --description="Admin authentication" + +# Copy tasks from current tag to new context +task-master add-tag testing --copy-from-current --description="QA testing tasks" +``` + +#### Cross-Tag Coordination + +When coordinating work across tags: + +1. **Plan Integration Points**: Identify where different tag contexts need to interact +2. **Manual Coordination**: Note cross-tag dependencies in task details +3. **Tag Switching**: Use `task-master use-tag` to switch contexts as needed +4. **Documentation**: Use `task-master update-subtask` to document cross-tag decisions + +## Key Files & Project Structure + +### Core Files + +- `.taskmaster/tasks/tasks.json` - Tagged task data file (auto-managed) +- `.taskmaster/state.json` - Current tag context and state information +- `.taskmaster/config.json` - AI model configuration (use `task-master models` to modify) +- `.taskmaster/docs/prd-<tag>.md` - Product Requirements Documents for each tag +- `.taskmaster/tasks/*.md` - Individual task files (auto-generated, tagged by context) + +### Tagged Task Structure + +```json +{ + "master": { + "tasks": [ + { "id": 1, "title": "Setup API", "status": "pending", ... } + ] + }, + "user-auth": { + "tasks": [ + { "id": 1, "title": "OAuth Integration", "status": "pending", ... } + ] + }, + "payments": { + "tasks": [ + { "id": 1, // Independent numbering per tag + "title": "Setup Stripe Integration", + "description": "Configure Stripe payment processing", + "status": "pending", + "priority": "high", + "dependencies": [], + "details": "Use Stripe API for payment processing...", + "testStrategy": "Test payment flow with test cards" + } + ] + } +} +``` + +### Claude Code Integration Files + +- `CLAUDE.md` - Auto-loaded context for Claude Code (this file) +- `.claude/settings.json` - Claude Code tool allowlist and preferences +- `.claude/commands/` - Custom slash commands for repeated workflows +- `.mcp.json` - MCP server configuration (project-specific) + +### Directory Structure + +``` +project/ +β”œβ”€β”€ .taskmaster/ +β”‚ β”œβ”€β”€ tasks/ # Tagged task files directory +β”‚ β”‚ β”œβ”€β”€ tasks.json # Tagged task database +β”‚ β”‚ β”œβ”€β”€ task-1.md # Individual task files (tagged) +β”‚ β”‚ └── task-2.md +β”‚ β”œβ”€β”€ docs/ # Documentation directory +β”‚ β”‚ β”œβ”€β”€ prd-master.md # Main PRD +β”‚ β”‚ β”œβ”€β”€ prd-user-authentication.md # Auth PRD +β”‚ β”‚ β”œβ”€β”€ prd-payment-system.md # Payment PRD +β”‚ β”‚ └── prd-mobile-app.md # Mobile PRD +β”‚ β”œβ”€β”€ reports/ # Analysis reports directory +β”‚ β”‚ └── task-complexity-report.json +β”‚ β”œβ”€β”€ templates/ # Template files +β”‚ β”‚ └── example_prd.md # Example PRD template +β”‚ β”œβ”€β”€ state.json # Current tag context and state +β”‚ └── config.json # AI models & settings +β”œβ”€β”€ .claude/ +β”‚ β”œβ”€β”€ settings.json # Claude Code configuration +β”‚ └── commands/ # Custom slash commands +β”œβ”€β”€ .mcp.json # MCP configuration +└── CLAUDE.md # This file - auto-loaded by Claude Code +``` + +### Essential MCP Tools + +```javascript +help; // = shows available taskmaster commands +// Tag management +list_tags; // = task-master tags +add_tag; // = task-master add-tag +use_tag; // = task-master use-tag +copy_tag; // = task-master copy-tag +delete_tag; // = task-master delete-tag + +// Tagged workflow +initialize_project; // = task-master init (with tagged system) +parse_prd; // = task-master parse-prd (in current tag) + +// Tag-aware operations (all work within current tag) +get_tasks; // = task-master list +next_task; // = task-master next +get_task; // = task-master show <id> +set_task_status; // = task-master set-status + +// Task management +add_task; // = task-master add-task +expand_task; // = task-master expand +update_task; // = task-master update-task +update_subtask; // = task-master update-subtask +update; // = task-master update + +// Analysis +analyze_project_complexity; // = task-master analyze-complexity +complexity_report; // = task-master complexity-report +``` + +## Claude Code Workflow Integration + +### Tagged Project Initialization + +```bash +# Initialize Task Master with tagged system +task-master init + +# Set up multiple tag contexts +task-master add-tag user-auth --description="Authentication features" +task-master add-tag payments --description="Payment system" +task-master add-tag mobile --description="Mobile app" + +# Parse PRDs into respective contexts +task-master use-tag user-auth +task-master parse-prd .taskmaster/docs/prd-user-authentication.md + +task-master use-tag payments +task-master parse-prd .taskmaster/docs/prd-payment-system.md + +# Analyze and expand within each context +task-master use-tag user-auth +task-master analyze-complexity --research +task-master expand --all --research +``` + +### Multi-Context Development Loop + +```bash +# Morning: Check all contexts +task-master tags --show-metadata # Overview of all tag contexts + +# Work on authentication +task-master use-tag user-auth +task-master next # Find next auth task +task-master show <id> # Review auth task details + +# Afternoon: Switch to payments +task-master use-tag payments +task-master next # Find next payment task +task-master show <id> # Review payment task details + +# Log progress in current context +task-master update-subtask --id=<id> --prompt="implementation progress..." +``` + +### Multi-Claude Tagged Workflows + +For complex projects with multiple tag contexts: + +```bash +# Terminal 1: Authentication development +cd project && claude +# > task-master use-tag user-auth + +# Terminal 2: Payment system development +cd project-payment-worktree && claude +# > task-master use-tag payments + +# Terminal 3: Mobile app development +cd project-mobile-worktree && claude +# > task-master use-tag mobile +``` + +## Tagged Task Structure & IDs + +### Tag-Specific Task IDs + +- **Independent Numbering**: Each tag maintains its own task sequence starting from 1 +- **Main tasks**: `1`, `2`, `3`, etc. (within each tag) +- **Subtasks**: `1.1`, `1.2`, `2.1`, etc. (within each tag) +- **Sub-subtasks**: `1.1.1`, `1.1.2`, etc. (within each tag) + +### Tagged Task Context + +```json +{ + "user-auth": { + "tasks": [ + { + "id": 1, + "title": "Setup OAuth Provider", + "description": "Configure GitHub OAuth integration", + "status": "pending", + "priority": "high", + "dependencies": [], + "details": "Use GitHub OAuth client ID/secret...", + "testStrategy": "Test OAuth flow with GitHub account", + "subtasks": [ + { + "id": 1, + "title": "Register OAuth App", + "status": "pending", + "dependencies": [] + } + ] + } + ] + }, + "payments": { + "tasks": [ + { + "id": 1, // Independent numbering per tag + "title": "Setup Stripe Integration", + "description": "Configure Stripe payment processing", + "status": "pending", + "priority": "high", + "dependencies": [], + "details": "Use Stripe API for payment processing...", + "testStrategy": "Test payment flow with test cards" + } + ] + } +} +``` + +## Claude Code Best Practices with Tagged System + +### Tag Context Awareness + +- Always know your current tag context: `task-master tags` shows current context +- Use `/clear` between different tag contexts to maintain focus +- Use `task-master show <id>` to pull specific task context when needed +- Remember: Task IDs are independent per tag (each tag has its own task 1, 2, 3...) + +### Tagged Implementation Strategy + +1. **Context Setup**: `task-master use-tag <target-tag>` - Switch to appropriate context +2. **Task Discovery**: `task-master show <id>` - Understand requirements within tag +3. **Planning**: `task-master update-subtask --id=<id> --prompt="detailed plan"` - Log plan in context +4. **Status Management**: `task-master set-status --id=<id> --status=in-progress` - Start work in context +5. **Implementation**: Implement code following logged plan +6. **Progress Logging**: `task-master update-subtask --id=<id> --prompt="progress notes"` - Log within context +7. **Completion**: `task-master set-status --id=<id> --status=done` - Complete within context + +### Cross-Tag Development Patterns + +#### Feature Integration Workflow + +```bash +# 1. Implement core feature in its tag +task-master use-tag user-auth +task-master show 2 # Review auth API task +# ... implement auth APIs ... +task-master set-status --id=2 --status=done + +# 2. Switch to consuming feature's tag +task-master use-tag mobile +task-master show 3 # Review mobile integration task +task-master update-subtask --id=3.1 --prompt="Auth APIs completed in user-auth tag, ready for integration" +# ... implement integration ... +``` + +#### Cross-Tag Documentation + +```bash +# Document cross-tag dependencies +task-master use-tag mobile +task-master update-subtask --id=3.2 --prompt="Depends on user-auth tag task 2 (OAuth setup) being completed" + +# Document integration decisions +task-master update-subtask --id=3.3 --prompt="Using JWT tokens from auth service, implemented in user-auth tag" +``` + +### Complex Tagged Workflows + +#### Multi-Feature Migration + +1. **Create Migration PRD**: `touch .taskmaster/docs/prd-migration.md` +2. **Create Migration Tag**: `task-master add-tag migration --description="System migration tasks"` +3. **Parse Migration**: `task-master use-tag migration && task-master parse-prd .taskmaster/docs/prd-migration.md` +4. **Cross-Reference**: Document which existing tags are affected in migration tasks +5. **Coordinate**: Use `task-master update-subtask` to log progress across affected tags + +#### Tag Lifecycle Management + +```bash +# Development lifecycle +task-master add-tag feature-x --description="New feature development" # Create +task-master use-tag feature-x # Develop +task-master copy-tag feature-x testing-x --description="Feature testing" # Test +task-master delete-tag feature-x # Cleanup +``` + +### Git Integration with Tagged System + +Tagged Task Master works excellently with git workflows: + +```bash +# Align tags with branches +git checkout -b feature/user-authentication +task-master add-tag --from-branch + +# Work within tag context +task-master use-tag feature-user-authentication +task-master next + +# Commit with tag context +git commit -m "feat: implement OAuth setup (user-auth tag, task 1.2)" + +# Create PR with tag context +gh pr create --title "Complete user-auth tag: OAuth integration" --body "Implements all user authentication tasks from user-auth tag context" +``` + +### Parallel Development with Tagged Worktrees + +```bash +# Create worktrees for different tag contexts +git worktree add ../project-auth feature/auth-system +git worktree add ../project-payment feature/payment-system +git worktree add ../project-mobile feature/mobile-app + +# Run Claude Code in each worktree with different tag contexts +cd ../project-auth && claude # Terminal 1: user-auth tag +cd ../project-payment && claude # Terminal 2: payments tag +cd ../project-mobile && claude # Terminal 3: mobile tag +``` + +## Troubleshooting Tagged System + +### Tag Context Issues + +```bash +# Check current tag context +task-master tags # Shows current tag (marked with *) + +# Switch if needed +task-master use-tag <correct-tag> + +# List tasks in current context +task-master list +``` + +### Cross-Tag Dependencies + +- **Note**: Task dependencies only work within the same tag context +- **Workaround**: Document cross-tag dependencies in task details using `update-subtask` +- **Coordination**: Use clear naming and documentation for cross-tag integration points + +### Task File Sync Issues + +```bash +# Regenerate task files for current tag +task-master generate + +# Fix dependencies within current tag +task-master fix-dependencies +``` + +## Important Tagged System Notes + +### Tag Context Isolation + +- **Task IDs are independent per tag** - each tag has its own sequence starting from 1 +- **Dependencies only work within tags** - cannot create dependencies across tags +- **Status and progress are tag-specific** - marking task 1 done in tag A doesn't affect task 1 in tag B +- **Current tag context affects all operations** - always verify you're in the correct tag + +### AI-Powered Operations (within current tag) + +These commands work within the current tag context and may take up to a minute: + +- `parse_prd` / `task-master parse-prd` - Generates tasks in current tag +- `analyze_project_complexity` / `task-master analyze-complexity` - Analyzes current tag's tasks +- `expand_task` / `task-master expand` - Expands tasks in current tag +- `add_task` / `task-master add-task` - Adds to current tag +- `update` / `task-master update` - Updates tasks in current tag + +### File Management with Tagged System + +- Never manually edit `tasks.json` - contains all tag contexts, use commands instead +- Current tag context is stored in `.taskmaster/state.json` +- Task markdown files are generated with tag context information +- Use `task-master generate` after any manual changes + +### Claude Code Session Management with Tags + +- Use `/clear` when switching between tag contexts to maintain focus +- Start sessions by checking tag context: `task-master tags` +- Use `task-master use-tag <name>` to switch contexts within session +- Headless mode with tag context: `claude -p "task-master use-tag auth && task-master next"` + +The tagged system ensures your task management scales with project complexity while maintaining clear organization and preventing conflicts across different feature areas or development contexts. \ No newline at end of file diff --git a/.taskmaster/docs/tech-stack.md b/.taskmaster/docs/tech-stack.md new file mode 100644 index 0000000..e69de29 diff --git a/.taskmaster/reports/.gitkeep b/.taskmaster/reports/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/.taskmaster/state.json b/.taskmaster/state.json new file mode 100644 index 0000000..b248975 --- /dev/null +++ b/.taskmaster/state.json @@ -0,0 +1,6 @@ +{ + "currentTag": "master", + "lastSwitched": "2025-06-23T12:52:52.147Z", + "branchTagMapping": {}, + "migrationNoticeShown": true +} diff --git a/.taskmaster/tasks/tasks.json b/.taskmaster/tasks/tasks.json new file mode 100644 index 0000000..4b5c82a --- /dev/null +++ b/.taskmaster/tasks/tasks.json @@ -0,0 +1,18 @@ +{ + "master": { + "tasks": [], + "metadata": { + "created": "2025-06-22T13:38:45.420Z", + "updated": "2025-06-22T22:10:07.199Z", + "description": "Tasks for master context" + } + }, + "app-design-document": { + "tasks": [], + "metadata": { + "created": "2025-06-22T22:11:31.835Z", + "updated": "2025-06-23T10:16:48.937Z", + "description": "Tasks for app-design-document context" + } + } +} diff --git a/.taskmaster/templates/example_prd.md b/.taskmaster/templates/example_prd.md new file mode 100644 index 0000000..2178315 --- /dev/null +++ b/.taskmaster/templates/example_prd.md @@ -0,0 +1,77 @@ +<context> +# Overview + +# Project Context + +**Project Status: Pre-MVP** + +- Read this file: `.taskmaster/docs/app-design-document.md` - App design document +- Read this file: `.taskmaster/docs/tech-stack.md` - Tech stack, architecture +- DO NOT care about breaking changes. We didn't deploy yet. +- DO NOT care about unit testing, accessibility, visual testing (Storybook), and performance optimization unless asked. +- Care about security, zod validation, authorization, rate limiting, and other production-level concerns. In general, you can see how it's done in the other features. + +# Overview + +[Provide a high-level overview of your product here. Explain what problem it solves, who it's for, and why it's valuable.] + +# Core Features + +[List and describe the main features of your product. For each feature, include: + +- What it does +- Why it's important +- How it works at a high level] + +# User Experience + +[Describe the user journey and experience. Include: + +- User personas +- Key user flows +- UI/UX considerations] + +</context> +<PRD> + +# Technical Architecture + +[Outline the technical implementation details: + +- System components +- Data models +- APIs and integrations +- Infrastructure requirements] + +# Development Roadmap + +[Break down the development process into phases: + +- MVP requirements +- Future enhancements +- Do not think about timelines whatsoever -- all that matters is scope and detailing exactly what needs to be build in each phase so it can later be cut up into tasks] + +# Logical Dependency Chain + +[Define the logical order of development: + +- Which features need to be built first (foundation) +- Getting as quickly as possible to something usable/visible front end that works +- Properly pacing and scoping each feature so it is atomic but can also be built upon and improved as development approaches] + +# Risks and Mitigations + +[Identify potential risks and how they'll be addressed: + +- Technical challenges +- Figuring out the MVP that we can build upon +- Resource constraints] + +# Appendix + +[Include any additional information: + +- Research findings +- Technical specifications] + +</PRD> diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..94bd74a --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,134 @@ +# CLAUDE.md + +## Project Overview + +<!-- Run /app-design:create to generate app design document --> +<!-- Run /tech-stack:create to generate tech stack documentation --> + +- App Design: @.taskmaster/docs/app-design-document.md +- Tech Stack: @.taskmaster/docs/tech-stack.md + +## Project Status + +<!-- **Current Stage**: Pre-MVP --> + +### DO Care About + +<!-- - **Security**: Authentication, authorization, input validation +- **Core Functionality**: Essential features that deliver primary value +- **Data Integrity**: Proper database design and constraints +- **Error Handling**: Basic error boundaries and user feedback --> + +### DO NOT Care About + +<!-- - **Unit Tests**: Focus on manual testing for now +- **Performance Optimization**: Premature optimization +- **Perfect Code**: Working implementation over perfect abstractions +- **Comprehensive Logging**: Basic console.error is enough --> + +### Development Approach + +<!-- - **Focus**: Ship working features quickly +- **Iterate**: Get user feedback early and often +- **Refactor**: Clean up after validation, not before --> + +## Commands + +### Development + +<!-- - `pnpm typecheck` - Run TypeScript type checking (must pass without errors) +- `pnpm lint` - Run ESLint +- `pnpm format` - Format code with Prettier --> + +### Database + +<!-- - `pnpm db:generate` - Generate Prisma client from schema +- `pnpm db:push` - Push schema changes to database +- `pnpm db:seed` - Seed database with initial data --> + +### Testing + +<!-- - `pnpm test` - Run unit tests +- `pnpm test:e2e` - Run end-to-end tests --> + +## Available Slash Commands + +### Task Management + +- `/task:next` - Get next task and start implementing +- `/task:list` - List all tasks +- `/task:show <id>` - Show task details +- `/task:done <id>` - Mark task complete +- `/task:add` - Add one or more tasks +- `/task:add-interactive` - Add tasks with clarifying questions +- `/prd:parse` - Parse PRD into tasks +- `/task:expand <id>` - Break down complex tasks +- `/task:move <from> to <to>` - Reorganize tasks + +### Task Updates + +- `/task:update` - Update tasks based on changes +- `/task:update-interactive` - Update tasks with clarifying questions +- `/task:research` - Research best practices + +### Research + +- `/research:task` - Research for specific tasks +- `/research:architecture` - Research system design +- `/research:tech` - Research technologies +- `/research:security` - Research security practices + +### Documentation + +- `/app-design:create` - Create app design document +- `/app-design:update` - Update app design document +- `/tech-stack:create` - Create tech stack documentation +- `/tech-stack:update` - Update tech stack documentation +- `/prd:create-interactive` - Create PRD with Q&A +- `/prd:create` - Create PRD without questions + +### Development Tools + +- `/rules:create` - Create new Cursor rule +- `/rules:update` - Update existing Cursor rule + +## Development Guidelines + +This project uses a unified approach to development patterns across Claude Code and Cursor: + +### Core Rules + +- @.cursor/rules/cursor-rules.mdc - Rule creation guidelines +- @.cursor/rules/project-status.mdc - Stage-based development priorities +- @.cursor/rules/self-improve.mdc - Continuous improvement patterns + +### Task Management + +- @.cursor/rules/taskmaster/taskmaster.mdc - Task Master command reference +- @.cursor/rules/taskmaster/dev-workflow.mdc - Development workflow patterns + +### Complete Task Master Guide + +- .taskmaster/docs/taskmaster-guide.md - Full tagged task management documentation, if needed + +## Project Structure + +``` +project/ +β”œβ”€β”€ .taskmaster/ # Task management files +β”‚ β”œβ”€β”€ tasks/ # Task database and files +β”‚ β”œβ”€β”€ docs/ # PRDs and documentation +β”‚ └── config.json # AI model configuration +β”œβ”€β”€ .cursor/ # Cursor-specific rules +β”‚ └── rules/ # Development patterns +β”œβ”€β”€ .claude/ # Claude Code configuration +β”‚ β”œβ”€β”€ commands/ # Custom slash commands +β”‚ └── settings.json # Tool preferences +└── src/ # Application source code +``` + +## Notes + +- Never work directly on the `master` tag - always create feature tags +- Run typecheck before committing +- Use `/task:next` to automatically get and start implementing tasks diff --git a/README.md b/README.md index 4b53dd6..a0acc9e 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,239 @@ # ai-dev-claude-tm-cursor -Claude Codeλ₯Ό ν†΅ν•œ 지λŠ₯ν˜• μ½”λ“œ 생성, Task Masterλ₯Ό ν†΅ν•œ 효율적인 ν”„λ‘œμ νŠΈ 관리, 그리고 Cursorλ₯Ό ν†΅ν•œ AI 기반 μ½”λ“œ νŽΈμ§‘ κΈ°λŠ₯을 ν†΅ν•©ν•œ AI 기반 개발 ν…œν”Œλ¦Ώμž…λ‹ˆλ‹€. κ³ κΈ‰ AI κΈ°λŠ₯을 ν™œμš©ν•˜μ—¬ 개발 μ›Œν¬ν”Œλ‘œμš°λ₯Ό κ°„μ†Œν™”ν•˜μ„Έμš”. \ No newline at end of file +Claude Code, Task Master, Cursorλ₯Ό μ—°λ™ν•œ AI 기반 개발 ν…œν”Œλ¦Ώμž…λ‹ˆλ‹€. + +## μ†Œκ°œ + +μ„Έ 가지 κ°•λ ₯ν•œ AI 개발 도ꡬλ₯Ό κ²°ν•©ν•œ ν”„λ‘œμ νŠΈ ν…œν”Œλ¦Ώμž…λ‹ˆλ‹€: + +- [**Claude Code**](https://docs.anthropic.com/en/docs/claude-code/overview) - Anthropic의 Claude용 CLI +- [**Task Master**](https://github.com/eyaltoledano/claude-task-master) - νƒœκ·Έ 기반 μž‘μ—… 관리 μ‹œμŠ€ν…œ +- [**Cursor**](https://www.cursor.com/) - μ •λ°€ν•œ μ½”λ“œ 리뷰 μ›Œν¬ν”Œλ‘œλ₯Ό μœ„ν•œ AI 기반 IDE (선택 사항) + +## μ‹œμž‘ν•˜κΈ° + +1. **Claude Code μ‹€ν–‰** + + ```bash + claude + ``` + +2. **Task Studio μ—΄κΈ°** (선택적 μ›Ή μΈν„°νŽ˜μ΄μŠ€) + + ```bash + npx task-studio@latest + ``` + +3. **μ›Œν¬ν”Œλ‘œλ₯Ό λ”°λ₯΄μ„Έμš”:** + - `/create-app-design` - μ•± μ„€λͺ…ν•˜κΈ° + - `/create-tech-stack` - 기술 μŠ€νƒ μ„ νƒν•˜κΈ° + - `/create-prd-interactive` - κΈ°λŠ₯ μš”κ΅¬μ‚¬ν•­ μž‘μ„±ν•˜κΈ° + - `/parse-prd` - μš”κ΅¬μ‚¬ν•­μ„ μž‘μ—…μœΌλ‘œ λ³€ν™˜ν•˜κΈ° + - `/next` - μ½”λ”© μ‹œμž‘ν•˜κΈ° + +## μž‘λ™ 방식 + +Claude CodeλŠ” λ‹€μŒμ„ 톡해 ν”„λ‘œμ νŠΈλ₯Ό μ΄ν•΄ν•©λ‹ˆλ‹€: + +- **CLAUDE.md** - μžλ™μœΌλ‘œ λ‘œλ“œλ˜λŠ” ν”„λ‘œμ νŠΈ μ»¨ν…μŠ€νŠΈ 및 κ·œμΉ™ +- **Task Master** - MCP 연동을 ν†΅ν•œ μž‘μ—… 관리 +- **μžμ—°μ–΄** - ν•˜κ³  싢은 μž‘μ—…μ„ μ„€λͺ…ν•˜κΈ°λ§Œ ν•˜λ©΄ λ©λ‹ˆλ‹€ + +λͺ…λ Ήμ–΄λ₯Ό μ™ΈμšΈ ν•„μš” 없이 Claudeμ—κ²Œ κ°„λ‹¨νžˆ μš”μ²­ν•˜μ„Έμš”: + +- "인증을 μœ„ν•œ μƒˆ κΈ°λŠ₯ νƒœκ·Έ 생성" +- "λ‹€μŒ μž‘μ—… 보여주기" +- "이 μž‘μ—…μ„ μ™„λ£Œλ‘œ ν‘œμ‹œ" +- "이 κΈ°λŠ₯에 남은 μž‘μ—…μ€?" + +## λͺ…λ Ήμ–΄ + +### λΉ λ₯Έ μ°Έμ‘° + +| λͺ…λ Ήμ–΄ | μ„€λͺ… | λΆ„λ₯˜ | +| ------------------------------ | -------------------------------------------------------------------- | ------------- | +| `/create-app-design` | ν”„λ‘œμ νŠΈ 단계 평가λ₯Ό ν¬ν•¨ν•œ 포괄적인 μ•± 섀계 λ¬Έμ„œ 생성 | λ¬Έμ„œ | +| `/update-app-design` | μ½”λ“œλ² μ΄μŠ€ 변경사항을 기반으둜 κΈ°μ‘΄ μ•± 섀계 λ¬Έμ„œ μ—…λ°μ΄νŠΈ | λ¬Έμ„œ | +| `/create-tech-stack` | μ½”λ“œλ² μ΄μŠ€ 뢄석을 톡해 포괄적인 기술 μŠ€νƒ λ¬Έμ„œ 생성 | λ¬Έμ„œ | +| `/update-tech-stack` | μ˜μ‘΄μ„± 변경에 따라 기술 μŠ€νƒ λ¬Έμ„œ μ—…λ°μ΄νŠΈ | λ¬Έμ„œ | +| `/create-prd-interactive` | λ³΅μž‘ν•œ κΈ°λŠ₯에 λŒ€ν•΄ λͺ…ν™•ν•œ μ§ˆλ¬Έμ„ 톡해 λŒ€ν™”ν˜•μœΌλ‘œ PRD 생성 | λ¬Έμ„œ | +| `/create-prd` | λ‹¨μˆœν•˜κ³  잘 μ •μ˜λœ κΈ°λŠ₯에 λŒ€ν•΄ 질문 없이 λ°”λ‘œ PRD 생성 | λ¬Έμ„œ | +| `/parse-prd` | PRDλ₯Ό νŒŒμ‹±ν•˜μ—¬ 선택적 νƒœκ·Έ 생성과 ν•¨κ»˜ Task Master μž‘μ—…μœΌλ‘œ λ³€ν™˜ | λ¬Έμ„œ | +| `/create-rule` | μ μ ˆν•œ ꡬ쑰와 μ»¨λ²€μ…˜μ„ κ°–μΆ˜ μƒˆ Cursor κ·œμΉ™ 파일 생성 | λ¬Έμ„œ | +| `/update-rule` | μƒˆλ‘œμš΄ νŒ¨ν„΄μ΄λ‚˜ μ½”λ“œλ² μ΄μŠ€ 진화에 따라 κΈ°μ‘΄ Cursor κ·œμΉ™ μ—…λ°μ΄νŠΈ | λ¬Έμ„œ | +| `/update-project-structure` | `tree` 슀크립트λ₯Ό μ‹€ν–‰ν•˜μ—¬ ν”„λ‘œμ νŠΈ ꡬ쑰 λ¬Έμ„œ μ—…λ°μ΄νŠΈ | λ¬Έμ„œ | +| `/next` | λ‹€μŒ μž‘μ—…μ„ λ°›μ•„ μ¦‰μ‹œ κ΅¬ν˜„ μ‹œμž‘ | μž‘μ—… | +| `/done` | μž‘μ—…μ„ μ™„λ£Œλ‘œ ν‘œμ‹œν•˜κ³  μ„ νƒμ μœΌλ‘œ λ‹€μŒ μž‘μ—… λ°›κΈ° | μž‘μ—… | +| `/show` | νŠΉμ • μž‘μ—…μ˜ μ„ΈλΆ€ 정보 ν‘œμ‹œ | μž‘μ—… | +| `/list` | ν˜„μž¬ νƒœκ·Έμ˜ λͺ¨λ“  μž‘μ—… λ‚˜μ—΄ | μž‘μ—… | +| `/add` | ν˜„μž¬ νƒœκ·Έμ— ν•˜λ‚˜ μ΄μƒμ˜ μž‘μ—… μΆ”κ°€ | μž‘μ—… | +| `/add-interactive` | λͺ…ν™•ν•œ μ§ˆλ¬Έμ„ 톡해 λŒ€ν™”ν˜•μœΌλ‘œ μž‘μ—… μΆ”κ°€ | μž‘μ—… | +| `/update-task` | κ΅¬ν˜„ 변경사항에 따라 μž‘μ—… μ—…λ°μ΄νŠΈ | μž‘μ—… | +| `/update-task-interactive` | λͺ…ν™•ν•œ μ§ˆλ¬Έμ„ 톡해 λŒ€ν™”ν˜•μœΌλ‘œ μž‘μ—… μ—…λ°μ΄νŠΈ | μž‘μ—… | +| `/expand` | μž‘μ—…μ„ ν•˜μœ„ μž‘μ—…μœΌλ‘œ λΆ„ν•΄ | μž‘μ—… | +| `/move` | μž‘μ—… ꡬ쑰 μž¬κ΅¬μ„± | μž‘μ—… | +| `/research` | λͺ¨λ²” 사둀λ₯Ό μ—°κ΅¬ν•˜κ³  μž‘μ—… μ—…λ°μ΄νŠΈ | μž‘μ—… | +| `/task` | λͺ¨λ²” 사둀λ₯Ό μ—°κ΅¬ν•˜κ³  μž‘μ—… μ—…λ°μ΄νŠΈ | λ¦¬μ„œμΉ˜ | +| `/tech` | 기술, ν”„λ ˆμž„μ›Œν¬, 도ꡬ 연ꡬ | λ¦¬μ„œμΉ˜ | +| `/security` | λ³΄μ•ˆ λͺ¨λ²” 사둀 및 취약점 연ꡬ | λ¦¬μ„œμΉ˜ | +| `/architecture` | μ•„ν‚€ν…μ²˜ νŒ¨ν„΄ 및 λͺ¨λ²” 사둀 연ꡬ | λ¦¬μ„œμΉ˜ | +| `/create-snippet` | μž¬μ‚¬μš© κ°€λŠ₯ν•œ μ½”λ“œ μŠ€λ‹ˆνŽ« 생성 | μŠ€λ‹ˆνŽ« | +| `/debug` | λ³΅μž‘ν•œ λ¬Έμ œμ— λŒ€ν•œ 체계적인 디버깅 ν”„λ‘œμ„ΈμŠ€ | 지원 | + +### λͺ…λ Ήμ–΄ μ„ΈλΆ€ 정보 + +λͺ¨λ“  λͺ…λ Ήμ–΄λŠ” ν”„λ‘œμ νŠΈ μ»¨ν…μŠ€νŠΈλ₯Ό λΆ„μ„ν•˜κ³  지λŠ₯적인 지원을 μ œκ³΅ν•˜λŠ” νŒ¨ν„΄μ„ λ”°λ¦…λ‹ˆλ‹€. λ¬Έμ„œ κ΄€λ ¨ λͺ…λ Ήμ–΄λŠ” 일반적으둜 μ •ν™•ν•œ 결과물을 보μž₯ν•˜κΈ° μœ„ν•΄ λͺ…ν™•ν•œ μ§ˆλ¬Έμ„ ν•©λ‹ˆλ‹€. μž‘μ—… κ΄€λ ¨ λͺ…λ Ήμ–΄λŠ” ν˜„μž¬ νƒœκ·Έ μ»¨ν…μŠ€νŠΈ λ‚΄μ—μ„œ μž‘λ™ν•©λ‹ˆλ‹€. λ¦¬μ„œμΉ˜ κ΄€λ ¨ λͺ…λ Ήμ–΄λŠ” μ›Ή 검색을 ν™œμš©ν•˜μ—¬ AI의 지식 마감일 μ΄ν›„μ˜ μ΅œμ‹  정보λ₯Ό κ°€μ Έμ˜΅λ‹ˆλ‹€. + +## 팁 + +### Claude Code λŒ€ Cursor + +**λŒ€λΆ€λΆ„μ˜ 개발 μž‘μ—…μ—λŠ” 기본적으둜 Claude Codeλ₯Ό μ‚¬μš©ν•˜μ„Έμš”**: + +βœ… **μž₯점:** + +- μž₯기적인 ν”„λ‘œμ νŠΈ 이해 및 μ»¨ν…μŠ€νŠΈ μœ μ§€ +- λͺ¨λ“  Task Master AI λͺ…λ Ήμ–΄ 지원 +- 병렬 개발 +- Claude Opus의 κ΄‘λ²”μœ„ν•œ μ‚¬μš©μ„ μœ„ν•œ κ°€μž₯ μ €λ ΄ν•œ μš”κΈˆμ œ + +❌ **단점:** + +- μ„Έμ…˜ κ°„ μ±„νŒ… 기둝 μœ μ§€ μ•ˆ 됨 +- κ°œλ³„ 파일 변경에 λŒ€ν•œ μ„ΈλΆ„ν™”λœ μ œμ–΄ λΆ€μ‘± + +**λ‹€μŒκ³Ό 같은 경우 Cursor둜 μ „ν™˜ν•˜μ„Έμš”:** + +βœ… **μ„ΈλΆ„ν™”λœ μ½”λ“œ 리뷰 μ œμ–΄:** + +- νŒŒμΌλ³„λ‘œ νŠΉμ • diffλ₯Ό 수락/κ±°λΆ€ +- 인라인 μ½”λ“œ 탐색 κΈ°λŠ₯이 μžˆλŠ” μ‹œκ°μ  diff κ²€ν†  +- 볡원 지점 및 μ‰¬μš΄ λ³€κ²½ 되돌리기 +- μ‹ μ€‘ν•œ μ½”λ“œ 검사가 ν•„μš”ν•œ λ³΅μž‘ν•œ λ¦¬νŒ©ν† λ§ + +❌ **단점:** + +- λŒ€ν™”κ°€ 길어지면 λŠλ €μ§€κ³  λΆˆμ•ˆμ •ν•΄μ§ +- λΉ„-AI Task Master λͺ…λ Ήμ–΄λ§Œ 지원 +- Claude Code보닀 ν”„λ‘œμ νŠΈ μ»¨ν…μŠ€νŠΈ 관리가 λΉ„νš¨μœ¨μ  +- 자주 μƒˆλ‘œμš΄ μ±„νŒ…μ„ μ‹œμž‘ν•΄μ•Ό 함 + +**μΆ”μ²œ μš”κΈˆμ œ:** + +**Claude Max ($100/μ›”)** + +- κΈ°λ³Έ μ‚¬μš©μ„ μœ„ν•΄ Pro μš”κΈˆμ œ($20/μ›”)둜 μ‹œμž‘ +- μ€‘μš” ν”„λ‘œμ νŠΈλ₯Ό μœ„ν•΄ **Max 5x**($100/μ›”)둜 μ—…κ·Έλ ˆμ΄λ“œ: 훨씬 높은 μ‚¬μš©λŸ‰ ν•œλ„, 심측 연ꡬλ₯Ό μœ„ν•œ Claude Opus λͺ¨λΈ 잠금 ν•΄μ œ +- μ‚¬μš©λŸ‰ ν•œλ„μ— 자주 λ„λ‹¬ν•˜λŠ” 경우 **Max 20x**($200/μ›”)둜 μ—…κ·Έλ ˆμ΄λ“œ. Claude Opus의 κ΄‘λ²”μœ„ν•œ μ‚¬μš©μ— κ°€μž₯ κ°€μ„±λΉ„ μ’‹μŒ. + +**Cursor Pro ($20/μ›”)** + +- 선택 μ‚¬ν•­μ΄μ§€λ§Œ, μ„ΈλΆ„ν™”λœ μ½”λ“œ 리뷰 μ›Œν¬ν”Œλ‘œμ— ν•„μˆ˜μ  +- μ‹œκ°μ  diff 관리 및 볡원 지점 +- μ •λ°€ν•œ νŽΈμ§‘μ„ μœ„ν•΄ Claude Codeλ₯Ό μ™„λ²½ν•˜κ²Œ 보완 + +### μ»¨ν…μŠ€νŠΈ 관리 + +- **Claude Code**: λ‹€λ₯Έ μž‘μ—… 사이에 `/clear`λ₯Ό μ‚¬μš©ν•˜μ—¬ 집쀑 μœ μ§€ +- **Claude Code**: ν”„λ‘œμ νŠΈ μ»¨ν…μŠ€νŠΈλ₯Ό μœ„ν•΄ `CLAUDE.md`λ₯Ό μžλ™μœΌλ‘œ 읽음 +- **두 도ꡬ λͺ¨λ‘**: Task Master μƒνƒœλŠ” μ„Έμ…˜ 간에 μœ μ§€λ¨ + +### λΉ λ₯Έ λͺ…λ Ήμ–΄ (μžμ—°μ–΄) + +- "λ‹€μŒ μž‘μ—…μ€?" - λ‹€μŒ μž‘μ—… κ°€μ Έμ˜€κΈ° +- "μž‘μ—… 2.1 λ³΄μ—¬μ€˜" - νŠΉμ • μž‘μ—… μ„ΈλΆ€ 정보 보기 +- "μ™„λ£Œλ‘œ ν‘œμ‹œν•΄μ€˜" - ν˜„μž¬ μž‘μ—… μ™„λ£Œν•˜κΈ° +- "인증 κΈ°λŠ₯ νƒœκ·Έ λ§Œλ“€μ–΄μ€˜" - μƒˆ κΈ°λŠ₯ μ»¨ν…μŠ€νŠΈ 생성 +- "결제 νƒœκ·Έλ‘œ μ „ν™˜ν•΄μ€˜" - μ»¨ν…μŠ€νŠΈ λ³€κ²½ + +### μ‚¬μš©μž μ •μ˜ λͺ…λ Ήμ–΄ 생성 + +`.claude/commands/`에 μΆ”κ°€ν•˜μ—¬ μžμ‹ λ§Œμ˜ μŠ¬λž˜μ‹œ λͺ…λ Ήμ–΄λ₯Ό λ§Œλ“œμ„Έμš”. + +### 닀쀑 μž‘μ—… 및 닀쀑 κΈ°λŠ₯ 개발 + +λ™μΌν•œ κΈ°λŠ₯ λ‚΄μ—μ„œ λ˜λŠ” μ—¬λŸ¬ κΈ°λŠ₯에 걸쳐 닀쀑 μž‘μ—…μ„ μˆ˜ν–‰ν•©λ‹ˆλ‹€: + +```bash +# 닀쀑 μž‘μ—… 개발 (동일 κΈ°λŠ₯) +"ν˜„μž¬ νƒœκ·Έμ˜ λͺ¨λ“  μž‘μ—… λ³΄μ—¬μ€˜" +"μž‘μ—… 2.1 λ³΄μ—¬μ€˜" - νŠΉμ • μž‘μ—… κ²€ν†  +"μ™„λ£Œλ‘œ ν‘œμ‹œ" - μž‘μ—… μ™„λ£Œ ν›„ λ‹€μŒμœΌλ‘œ 이동 + +# 닀쀑 κΈ°λŠ₯ 개발 +"결제 νƒœκ·Έλ‘œ μ „ν™˜ν•˜κ³  λ‹€μŒ μž‘μ—… λ³΄μ—¬μ€˜" +"λͺ¨λ°”일 κ°œλ°œμ„ μœ„ν•œ μƒˆ νƒœκ·Έ λ§Œλ“€μ–΄μ€˜" +"λͺ¨λ“  νƒœκ·Έμ™€ 진행 상황 λ³΄μ—¬μ€˜" +``` + +### Git Worktreeλ₯Ό μ΄μš©ν•œ 병렬 개발 + +```bash +# 병렬 κ°œλ°œμ„ μœ„ν•œ μ›Œν¬νŠΈλ¦¬ 생성 +git worktree add ../project-api feature/api +git worktree add ../project-components feature/components + +# 각 μ›Œν¬νŠΈλ¦¬μ—μ„œ λ‹€λ₯Έ νƒœκ·Έλ‘œ Claude Code μ‹€ν–‰ +cd ../project-api && claude # 터미널 1: API μž‘μ—… +cd ../project-components && claude # 터미널 2: μ»΄ν¬λ„ŒνŠΈ μž‘μ—… +``` + +### 문제 ν•΄κ²° + +```bash +# ν˜„μž¬ νƒœκ·Έ 확인 +"λ‚˜ μ§€κΈˆ 무슨 νƒœκ·Έ μ“°κ³  μžˆμ–΄?" + +# μž‘μ—… 파일 동기화 문제 ν•΄κ²° +"μž‘μ—… 파일 λ‹€μ‹œ μƒμ„±ν•΄μ€˜" + +# AI λͺ¨λΈ μ„€μ • +task-master models --setup +``` + +## μ£Όμš” 파일 및 ν”„λ‘œμ νŠΈ ꡬ쑰 + +### 핡심 파일 + +- `.taskmaster/tasks/tasks.json` - νƒœκ·Έ 기반 μž‘μ—… λ°μ΄ν„°λ² μ΄μŠ€ (μžλ™ 관리) +- `.taskmaster/state.json` - ν˜„μž¬ νƒœκ·Έ μ»¨ν…μŠ€νŠΈ +- `.taskmaster/config.json` - AI λͺ¨λΈ μ„€μ • +- `.taskmaster/docs/prd-<tag>.md` - νƒœκ·Έλ³„ μ œν’ˆ μš”κ΅¬μ‚¬ν•­ λͺ…μ„Έμ„œ (PRD) +- `.taskmaster/tasks/*.md` - κ°œλ³„ μž‘μ—… 파일 (μžλ™ 생성) + +### Claude Code 연동 파일 + +- `CLAUDE.md` - Claude Codeλ₯Ό μœ„ν•œ μžλ™ λ‘œλ“œ μ»¨ν…μŠ€νŠΈ +- `.claude/settings.json` - Claude Code 도ꡬ ν—ˆμš© λͺ©λ‘ 및 ν™˜κ²½μ„€μ • +- `.claude/commands/` - 반볡적인 μ›Œν¬ν”Œλ‘œλ₯Ό μœ„ν•œ μ‚¬μš©μž μ •μ˜ μŠ¬λž˜μ‹œ λͺ…λ Ήμ–΄ +- `.mcp.json` - MCP μ„œλ²„ μ„€μ • + +### 디렉토리 ꡬ쑰 + +``` +project/ +β”œβ”€β”€ .taskmaster/ +β”‚ β”œβ”€β”€ tasks/ # νƒœκ·Έ 기반 μž‘μ—… 파일 +β”‚ β”‚ β”œβ”€β”€ tasks.json # μž‘μ—… λ°μ΄ν„°λ² μ΄μŠ€ +β”‚ β”‚ β”œβ”€β”€ task-1.md # κ°œλ³„ μž‘μ—… +β”‚ β”‚ └── task-2.md +β”‚ β”œβ”€β”€ docs/ # λ¬Έμ„œ +β”‚ β”‚ β”œβ”€β”€ app-design-document.md +β”‚ β”‚ β”œβ”€β”€ tech-stack.md +β”‚ β”‚ └── prd-<tag>.md +β”‚ β”œβ”€β”€ reports/ # 뢄석 λ³΄κ³ μ„œ +β”‚ β”œβ”€β”€ templates/ # PRD ν…œν”Œλ¦Ώ +β”‚ β”œβ”€β”€ state.json # ν˜„μž¬ νƒœκ·Έ μ»¨ν…μŠ€νŠΈ +β”‚ └── config.json # AI λͺ¨λΈ μ„€μ • +β”œβ”€β”€ .claude/ +β”‚ β”œβ”€β”€ settings.json # Claude Code μ„€μ • +β”‚ └── commands/ # μ‚¬μš©μž μ •μ˜ λͺ…λ Ήμ–΄ +β”œβ”€β”€ .cursor/ # Cursor IDE κ·œμΉ™ +β”‚ └── rules/ # μ½”λ”© ν‘œμ€€ +β”œβ”€β”€ .mcp.json # MCP μ„€μ • +└── CLAUDE.md # ν”„λ‘œμ νŠΈ μ»¨ν…μŠ€νŠΈ +``` + +## λΌμ΄μ„ μŠ€ + +MIT