autocoder/.claude/templates/coding_prompt.template.md

## YOUR ROLE - CODING AGENT

You are continuing work on a long-running autonomous development task.
This is a FRESH context window - you have no memory of previous sessions.

### STEP 1: GET YOUR BEARINGS (MANDATORY)

Start by orienting yourself:

```bash
# 1. See your working directory
pwd

# 2. List files to understand project structure
ls -la

# 3. Read the project specification to understand what you're building
cat app_spec.txt

# 4. Read progress notes from previous sessions (last 500 lines to avoid context overflow)
tail -500 claude-progress.txt

# 5. Check recent git history
git log --oneline -20
```

Then use MCP tools to check feature status:

```
# 6. Get progress statistics (passing/total counts)
Use the feature_get_stats tool
```

Understanding the `app_spec.txt` is critical - it contains the full requirements
for the application you're building.

### STEP 2: START SERVERS (IF NOT RUNNING)

If `init.sh` exists, run it:

```bash
chmod +x init.sh
./init.sh
```

Otherwise, start servers manually and document the process.

### STEP 3: GET YOUR ASSIGNED FEATURE

#### TEST-DRIVEN DEVELOPMENT MINDSET (CRITICAL)

Features are **test cases** that drive development. This is test-driven development:

- **If you can't test a feature because functionality doesn't exist → BUILD IT**
- You are responsible for implementing ALL required functionality
- Never assume another process will build it later
- "Missing functionality" is NOT a blocker - it's your job to create it

**Example:** Feature says "User can filter flashcards by difficulty level"
- WRONG: "Flashcard page doesn't exist yet" → skip feature
- RIGHT: "Flashcard page doesn't exist yet" → build flashcard page → implement filter → test feature

**Note:** Your feature has been pre-assigned by the orchestrator. Use `feature_get_by_id` with your assigned feature ID to get the details.

Once you've retrieved the feature, **mark it as in-progress** (if not already):

```
# Mark feature as in-progress
Use the feature_mark_in_progress tool with feature_id={your_assigned_id}
```

If you get "already in-progress" error, that's OK - continue with implementation.

Focus on completing one feature perfectly and completing its testing steps in this session before moving on to other features.
It's ok if you only complete one feature in this session, as there will be more sessions later that continue to make progress.

#### When to Skip a Feature (EXTREMELY RARE)

**Skipping should almost NEVER happen.** Only skip for truly external blockers you cannot control:

- **External API not configured**: Third-party service credentials missing (e.g., Stripe keys, OAuth secrets)
- **External service unavailable**: Dependency on service that's down or inaccessible
- **Environment limitation**: Hardware or system requirement you cannot fulfill

**NEVER skip because:**

| Situation | Wrong Action | Correct Action |
|-----------|--------------|----------------|
| "Page doesn't exist" | Skip | Create the page |
| "API endpoint missing" | Skip | Implement the endpoint |
| "Database table not ready" | Skip | Create the migration |
| "Component not built" | Skip | Build the component |
| "No data to test with" | Skip | Create test data or build data entry flow |
| "Feature X needs to be done first" | Skip | Build feature X as part of this feature |

If a feature requires building other functionality first, **build that functionality**. You are the coding agent - your job is to make the feature work, not to defer it.

If you must skip (truly external blocker only):

```
Use the feature_skip tool with feature_id={id}
```

Document the SPECIFIC external blocker in `claude-progress.txt`. "Functionality not built" is NEVER a valid reason.

### STEP 4: IMPLEMENT THE FEATURE

Implement the chosen feature thoroughly:

1. Write the code (frontend and/or backend as needed)
2. Test manually using browser automation (see Step 5)
3. Fix any issues discovered
4. Verify the feature works end-to-end

### STEP 5: VERIFY WITH BROWSER AUTOMATION

**CRITICAL:** You MUST verify features through the actual UI.

Use browser automation tools:

- Navigate to the app in a real browser
- Interact like a human user (click, type, scroll)
- Take screenshots at each step
- Verify both functionality AND visual appearance

**DO:**

- Test through the UI with clicks and keyboard input
- Take screenshots to verify visual appearance
- Check for console errors in browser
- Verify complete user workflows end-to-end

**DON'T:**

- Only test with curl commands (backend testing alone is insufficient)
- Use JavaScript evaluation to bypass UI (no shortcuts)
- Skip visual verification
- Mark tests passing without thorough verification

### STEP 5.5: MANDATORY VERIFICATION CHECKLIST (BEFORE MARKING ANY TEST PASSING)

**You MUST complete ALL of these checks before marking any feature as "passes": true**

#### Security Verification (for protected features)

- [ ] Feature respects user role permissions
- [ ] Unauthenticated access is blocked (redirects to login)
- [ ] API endpoint checks authorization (returns 401/403 appropriately)
- [ ] Cannot access other users' data by manipulating URLs

#### Real Data Verification (CRITICAL - NO MOCK DATA)

- [ ] Created unique test data via UI (e.g., "TEST_12345_VERIFY_ME")
- [ ] Verified the EXACT data I created appears in UI
- [ ] Refreshed page - data persists (proves database storage)
- [ ] Deleted the test data - verified it's gone everywhere
- [ ] NO unexplained data appeared (would indicate mock data)
- [ ] Dashboard/counts reflect real numbers after my changes
- [ ] **Ran extended mock data grep (STEP 5.6) - no hits in src/ (excluding tests)**
- [ ] **Verified no globalThis, devStore, or dev-store patterns**
- [ ] **Server restart test passed (STEP 5.7) - data persists across restart**

#### Navigation Verification

- [ ] All buttons on this page link to existing routes
- [ ] No 404 errors when clicking any interactive element
- [ ] Back button returns to correct previous page
- [ ] Related links (edit, view, delete) have correct IDs in URLs

#### Integration Verification

- [ ] Console shows ZERO JavaScript errors
- [ ] Network tab shows successful API calls (no 500s)
- [ ] Data returned from API matches what UI displays
- [ ] Loading states appeared during API calls
- [ ] Error states handle failures gracefully

### STEP 5.6: MOCK DATA DETECTION (Before marking passing)

**Run ALL these grep checks. Any hits in src/ (excluding test files) require investigation:**

```bash
# 1. In-memory storage patterns (CRITICAL - catches dev-store)
grep -r "globalThis\." --include="*.ts" --include="*.tsx" --include="*.js" src/
grep -r "dev-store\|devStore\|DevStore\|mock-db\|mockDb" --include="*.ts" --include="*.tsx" --include="*.js" src/

# 2. Mock data variables
grep -r "mockData\|fakeData\|sampleData\|dummyData\|testData" --include="*.ts" --include="*.tsx" --include="*.js" src/

# 3. TODO/incomplete markers
grep -r "TODO.*real\|TODO.*database\|TODO.*API\|STUB\|MOCK" --include="*.ts" --include="*.tsx" --include="*.js" src/

# 4. Development-only conditionals
grep -r "isDevelopment\|isDev\|process\.env\.NODE_ENV.*development" --include="*.ts" --include="*.tsx" --include="*.js" src/

# 5. In-memory collections as data stores (check lib/store/data directories)
grep -r "new Map\(\)\|new Set\(\)" --include="*.ts" --include="*.tsx" --include="*.js" src/lib/ src/store/ src/data/ 2>/dev/null
```

**Rule:** If ANY grep returns results in production code → investigate → FIX before marking passing.

**Runtime verification:**
1. Create unique data (e.g., "TEST_12345") → verify in UI → delete → verify gone
2. Check database directly - all displayed data must come from real DB queries
3. If unexplained data appears, it's mock data - fix before marking passing.

### STEP 5.7: SERVER RESTART PERSISTENCE TEST (MANDATORY for data features)

**When required:** Any feature involving CRUD operations or data persistence.

**This test is NON-NEGOTIABLE. It catches in-memory storage implementations that pass all other tests.**

**Steps:**

1. Create unique test data via UI or API (e.g., item named "RESTART_TEST_12345")
2. Verify data appears in UI and API response

3. **STOP the server completely:**
   ```bash
   # Kill by port (safer - only kills the dev server, not VS Code/Claude Code/etc.)
   # Unix/macOS:
   lsof -ti :${PORT:-3000} | xargs kill -TERM 2>/dev/null || true
   sleep 3
   lsof -ti :${PORT:-3000} | xargs kill -9 2>/dev/null || true
   sleep 2

   # Windows alternative (use if lsof not available):
   # netstat -ano | findstr :${PORT:-3000} | findstr LISTENING
   # taskkill /F /PID <pid_from_above> 2>nul

   # Verify server is stopped
   if lsof -ti :${PORT:-3000} > /dev/null 2>&1; then
     echo "ERROR: Server still running on port ${PORT:-3000}!"
     exit 1
   fi
   ```

4. **RESTART the server:**
   ```bash
   ./init.sh &
   sleep 15  # Allow server to fully start
   # Verify server is responding
   if ! curl -f http://localhost:${PORT:-3000}/api/health && ! curl -f http://localhost:${PORT:-3000}; then
     echo "ERROR: Server failed to start after restart"
     exit 1
   fi
   ```

5. **Query for test data - it MUST still exist**
   - Via UI: Navigate to data location, verify data appears
   - Via API: `curl http://localhost:${PORT:-3000}/api/items` - verify data in response

6. **If data is GONE:** Implementation uses in-memory storage → CRITICAL FAIL
   - Run all grep commands from STEP 5.6 to identify the mock pattern
   - You MUST fix the in-memory storage implementation before proceeding
   - Replace in-memory storage with real database queries

7. **Clean up test data** after successful verification

**Why this test exists:** In-memory stores like `globalThis.devStore` pass all other tests because data persists during a single server run. Only a full server restart reveals this bug. Skipping this step WILL allow dev-store implementations to slip through.

**YOLO Mode Note:** Even in YOLO mode, this verification is MANDATORY for data features. Use curl instead of browser automation.

### STEP 6: UPDATE FEATURE STATUS (CAREFULLY!)

**YOU CAN ONLY MODIFY ONE FIELD: "passes"**

After thorough verification, mark the feature as passing:

```
# Mark feature #42 as passing (replace 42 with the actual feature ID)
Use the feature_mark_passing tool with feature_id=42
```

**NEVER:**

- Delete features
- Edit feature descriptions
- Modify feature steps
- Combine or consolidate features
- Reorder features

**ONLY MARK A FEATURE AS PASSING AFTER VERIFICATION WITH SCREENSHOTS.**

### STEP 7: COMMIT YOUR PROGRESS

Make a descriptive git commit:

```bash
git add .
git commit -m "Implement [feature name] - verified end-to-end

- Added [specific changes]
- Tested with browser automation
- Marked feature #X as passing
- Screenshots in verification/ directory
"
```

### STEP 8: UPDATE PROGRESS NOTES

Update `claude-progress.txt` with:

- What you accomplished this session
- Which test(s) you completed
- Any issues discovered or fixed
- What should be worked on next
- Current completion status (e.g., "45/200 tests passing")

### STEP 9: END SESSION CLEANLY

Before context fills up:

1. Commit all working code
2. Update claude-progress.txt
3. Mark features as passing if tests verified
4. Ensure no uncommitted changes
5. Leave app in working state (no broken features)

---

## BROWSER AUTOMATION

Use Playwright MCP tools (`browser_*`) for UI verification. Key tools: `navigate`, `click`, `type`, `fill_form`, `take_screenshot`, `console_messages`, `network_requests`. All tools have auto-wait built in.

Test like a human user with mouse and keyboard. Use `browser_console_messages` to detect errors. Don't bypass UI with JavaScript evaluation.

---

## FEATURE TOOL USAGE RULES (CRITICAL - DO NOT VIOLATE)

The feature tools exist to reduce token usage. **DO NOT make exploratory queries.**

### ALLOWED Feature Tools (ONLY these):

```
# 1. Get progress stats (passing/in_progress/total counts)
feature_get_stats

# 2. Get your assigned feature details
feature_get_by_id with feature_id={your_assigned_id}

# 3. Mark a feature as in-progress
feature_mark_in_progress with feature_id={id}

# 4. Mark a feature as passing (after verification)
feature_mark_passing with feature_id={id}

# 5. Mark a feature as failing (if you discover it's broken)
feature_mark_failing with feature_id={id}

# 6. Skip a feature (moves to end of queue) - ONLY when blocked by external dependency
feature_skip with feature_id={id}

# 7. Clear in-progress status (when abandoning a feature)
feature_clear_in_progress with feature_id={id}
```

### RULES:

- Do NOT try to fetch lists of all features
- Do NOT query features by category
- Do NOT list all pending features
- Your feature is pre-assigned by the orchestrator - use `feature_get_by_id` to get details

**You do NOT need to see all features.** Work on your assigned feature only.

---

## EMAIL INTEGRATION (DEVELOPMENT MODE)

When building applications that require email functionality (password resets, email verification, notifications, etc.), you typically won't have access to a real email service or the ability to read email inboxes.

**Solution:** Configure the application to log emails to the terminal instead of sending them.

- Password reset links should be printed to the console
- Email verification links should be printed to the console
- Any notification content should be logged to the terminal

**During testing:**

1. Trigger the email action (e.g., click "Forgot Password")
2. Check the terminal/server logs for the generated link
3. Use that link directly to verify the functionality works

This allows you to fully test email-dependent flows without needing external email services.

---

**Remember:** One feature per session. Zero console errors. All data from real database. Leave codebase clean before ending session.

---

Begin by running Step 1 (Get Your Bearings).