---
applyTo: '**'
---
Provide project context and coding guidelines that AI should follow when generating code, answering questions, or reviewing changes.

INITIALIZATION PHASE:
When user provides initial project instruction:
- STOP and analyze if the instruction is high-level or lacks detail
- ASK clarifying questions about:
  * Specific features and functionality required
  * Technology stack preferences
  * UI/UX requirements and design preferences
  * Data models and business logic
  * Integration requirements (APIs, databases, third-party services)
  * User workflows and interactions
  * Performance requirements
  * Security and authentication needs
- Continue asking questions until user explicitly says "enough" or "that's sufficient"
- NEVER start coding during this phase
- Focus ONLY on understanding requirements completely

AFTER REQUIREMENTS GATHERING:
Once user confirms requirements are sufficient:
- Check if a bundler/package manager is detected (package.json, vite.config, etc.)
- If bundler detected: Create ONLY feature_list.json
- If NO bundler detected: Create init.sh AND feature_list.json
- DO NOT write any code yet
- STOP after creating these files

FEATURE_LIST.JSON TEMPLATE:
``` json
{
  "features": [
    {
      "id": 1,
      "category": "functional",
      "description": "Clear one-line description of what user can do",
      "steps": [
        "Concrete step 1 to test",
        "Concrete step 2 to test",
        "Concrete step 3 to verify expected outcome"
      ],
      "passes": false,
      "estimatedTime": "15-20 minutes",
      "dependencies": []
    }
  ]
}
```

Categories: "functional", "performance", "security", "ui/ux", "data", "integration"

CLAUDE-PROGRESS.TXT TEMPLATE:
```
=== Session [Date/Time] ===
Feature ID: [#]
Feature: [Feature description from feature_list.json]
Implementation Approach: [Brief description of how it was implemented]
Files Created/Modified:
- file1.js (85 lines) - [what was changed]
- file2.html (45 lines) - [what was changed]
- mock/testData.js (150 lines - mock data)
Status: Completed / Partially Complete / Blocked
Changes Made:
- [Specific change 1]
- [Specific change 2]
Issues Encountered:
- [Any problems or limitations]
Solutions Applied:
- [How issues were resolved]
File Size Check: All files under 120 lines ✓ / Required refactoring ✗
Tests Performed:
- [What tests were run]
Next Feature Suggested: [Feature ID and description]
App State: Working / Needs Testing / Broken
---
```

INIT.SH TEMPLATE (Only if no bundler detected):
```
#!/bin/bash
# Purpose: Start development environment
# Should include:
# - Dependency installation (if needed)
# - Database startup (if applicable)
# - Development server startup
# - Any required environment variables
# Must be runnable multiple times safely
```

FEATURE SIZE REQUIREMENTS:
- Each feature must be completable in ONE conversation session
- Break down complex features into multiple small features
- Each feature should take 15-30 minutes maximum
- Features must be independently testable
- Features must be focused on ONE specific capability
- Example: Instead of "User authentication system", break into:
  * "User can register with email and password"
  * "User can login with credentials"
  * "User can logout"
  * "User can reset password via email"

EVERY SESSION START (Working on ONE feature):
- Run pwd to confirm working directory
- Read claude-progress.txt to understand what was last completed
- Read git log (last 5-10 commits) for recent changes
- Look at feature_list.json to see current feature status
- User will tell you which feature to work on OR work on next incomplete feature
- If init.sh exists, run it to start development environment
- If no init.sh (bundler detected), start dev server using package manager (npm run dev, yarn dev, etc.)
- Run basic smoke test to verify app works

IMPLEMENTATION PLANNING PHASE (BEFORE ANY CODING):
After understanding the current feature, MUST do this:
- Explain your implementation approach in detail:
  * Which files will be created/modified
  * What code structure you'll use
  * How you'll keep files under 120 lines
  * Where mock data will be stored (separate file)
  * What libraries or dependencies needed
  * How you'll implement the logic
  * How you'll test the feature
  * Any potential challenges or trade-offs
- Present your plan clearly and wait for user feedback
- DISCUSS with user - they may have preferences on:
  * Architecture decisions
  * Code organization
  * Technology choices
  * Implementation approach
- Adjust plan based on user input
- ONLY start coding after user explicitly approves (says "go ahead", "looks good", "start", etc.)
- If user suggests changes, revise plan and confirm again

IMPLEMENTATION PLAN FORMAT:
## Implementation Plan for: [Feature Name]

**Files to Create/Modify:**
- file1.js (~70 lines) - [what changes]
- file2.html (~40 lines) - [what changes]
- utils/helpers.js (~30 lines) - [extracted utilities]
- mock/featureData.js (~80 lines) - [mock data for this feature]

**File Organization Strategy:**
[Explain how you'll keep files under 120 lines]

**Mock Data Location:**
[Specify which mock data file(s) and what data they contain]

**Approach:**
[Detailed explanation of implementation strategy]

**Dependencies/Libraries:**
[Any new packages or tools needed]

**Testing Strategy:**
[How you'll verify it works]

**Trade-offs/Considerations:**
[Any architectural decisions or potential issues]

**Estimated Time:** [X minutes]

Does this approach work for you? Any preferences or changes?

FILE SIZE AND ORGANIZATION RULES:
- EVERY file must be 120 lines or below (HARD LIMIT)
- If a file approaches 120 lines, MUST split into multiple files
- Use modular architecture to keep files small:
  * Separate concerns into different files
  * Extract utilities into separate files
  * Split large components into smaller sub-components
  * Create separate files for constants, types, interfaces
- Mock data MUST ALWAYS be in separate files:
  * Create mock/ or data/ directory for all mock data
  * File naming: mockUsers.js, mockProducts.json, testData.js, etc.
  * NEVER inline large mock data arrays/objects in implementation files
  * Even small mock data (3+ items) should be in separate file
- When a file reaches ~100 lines, proactively refactor before adding more
- Prefer many small focused files over few large files

DURING SESSION - SINGLE FEATURE FOCUS:
- Work ONLY on the current feature being discussed
- Do NOT look ahead to other features
- Do NOT implement anything beyond the current feature scope
- Stay laser-focused on completing this ONE feature
- If you notice the feature is too large, STOP and suggest breaking it into smaller features
- If you need to deviate from approved plan, STOP and discuss changes with user first
- If any file exceeds 120 lines during implementation, STOP and refactor before continuing

TESTING FOR CURRENT FEATURE:
- Test ONLY the current feature end-to-end
- Use browser automation for web features
- Verify the specific acceptance criteria in feature_list.json
- Do NOT test unrelated features unless they break

SESSION END (After completing ONE feature):
FOLLOW THIS EXACT ORDER:
1. Verify ALL files are under 120 lines (except mock data files)
2. Ensure code is in clean state
3. Update claude-progress.txt with complete session information
4. Update feature_list.json: change ONLY current feature's "passes" to true
5. WAIT for user to say "commit" or give commit instruction
6. When user says "commit": Write git commit with descriptive message
7. STOP - user will start new conversation for next feature

COMMIT RULES:
- NEVER commit automatically
- ONLY commit when user explicitly says "commit", "git commit", "save this", or similar
- Wait for user instruction before committing
- Commit message should be descriptive of the feature completed
- Commit includes: code changes + claude-progress.txt + feature_list.json

SINGLE FEATURE CONVERSATION FLOW:
1. Read context (progress file, git log, feature list)
2. Confirm which feature to work on
3. Start dev environment (init.sh or bundler command)
4. Verify app still works (smoke test)
5. Present implementation plan and WAIT for approval
6. Discuss and adjust plan based on user feedback
7. Get explicit approval before coding
8. Implement ONLY that feature (following approved plan)
9. Monitor file sizes - refactor immediately if approaching 120 lines
10. Ensure mock data is in separate files
11. Test ONLY that feature
12. Verify all files under 120 lines
13. Update claude-progress.txt (document everything)
14. Update feature_list.json (mark feature as passes: true)
15. WAIT for user to say "commit"
16. When user says commit: Write git commit with descriptive message
17. STOP - end conversation

BETWEEN CONVERSATIONS:
- User starts fresh conversation for each new feature
- Each conversation = ONE feature from feature_list.json
- Context resets between features (this is intentional)
- Progress tracking via git commits + claude-progress.txt + feature_list.json

FORBIDDEN BEHAVIORS:
- Never start coding during requirements gathering
- Never create more than necessary files during initialization (only feature_list.json if bundler detected, or init.sh + feature_list.json if no bundler)
- Never work on multiple features in one conversation
- Never look ahead or prepare for future features
- Never create large features that span multiple conversations
- NEVER start coding before presenting and discussing implementation plan
- NEVER start coding without explicit user approval
- NEVER create files over 120 lines (except mock data files)
- NEVER put mock data inline in implementation files
- NEVER continue coding if a file exceeds 120 lines without refactoring first
- NEVER commit without user explicitly instructing to commit