# Claude Code Project Guidelines

## Project Overview
A unified web dashboard aggregating Trello, Todoist, PlanToEat, Google Calendar, and Google Tasks.
**Stack:** Go 1.24 + chi router + HTMX + Tailwind CSS + SQLite.

## Key Documents (Read These First)

| Document | Purpose | When to Read |
|----------|---------|--------------|
| `DESIGN.md` | Authoritative design doc: architecture, patterns, visual design, dev guide | Before any significant work |
| `SESSION_STATE.md` | Current task state, next steps | Start of every session |
| `docs/adr/*.md` | Architecture Decision Records | Before implementing features in that area |

### Multi-Agent Workflow (Optional)

Role definitions exist for a three-agent pipeline (`ARCHITECT_ROLE.md`, `IMPLEMENTOR_ROLE.md`, `REVIEWER_ROLE.md`) but the **primary workflow is single-agent** — reading CLAUDE.md + DESIGN.md directly. The role files are reference material, not required reading for every session.

**Self-Improvement Cycle:** After completing each task, every role must reflect, perform 1-3 concrete improvements (test helpers, scripts, checklists, role definitions, docs), and record changes in `SESSION_STATE.md` → "Process Improvements". See each role file for role-specific details.

## Efficiency & Token Management
- **Context Minimization:** Use Grep/Glob with offset/limit rather than reading entire files when a targeted search suffices.
- **Surgical Edits:** Perform small, targeted file edits. Avoid rewriting entire files for single changes.
- **Dependency Awareness:** Use `go test`, `go build` to verify state rather than reasoning through logic.
- **Proactive Checkpointing:** Treat every 3-4 turns as a potential session end. Update `SESSION_STATE.md` frequently.

## Workflow: TDD — ALWAYS Write Tests First
**Every bug fix and feature MUST follow Test-Driven Development:**
1. **Red:** Write a failing test that reproduces the bug or specifies the new behavior.
2. **Green:** Write the minimum code to make the test pass.
3. **Refactor:** Clean up if needed, keeping tests green.

**No exceptions.** Do not skip to writing production code. If you find a bug, write a test that fails first, then fix it. This applies to template assertions, handler logic, store queries, and JS behavior (via template content tests).

### Plan-then-Execute
1. **Discovery:** Use terminal tools to locate relevant Go code/handlers.
2. **Planning:** Propose a specific plan and **wait for user confirmation** before editing.
3. **Execution:** Apply changes incrementally, verifying with `go test ./...`.
4. **Handoff:** If a task is incomplete or the user mentions "limit" or "handoff," immediately summarize progress in `SESSION_STATE.md`.

## Essential Commands
- **Run:** `go run cmd/dashboard/main.go`
- **Test:** `go test ./...`
- **Build:** `go build -o dashboard cmd/dashboard/main.go`
- **Deploy:** `bash deploy.sh` (builds with ldflags, pushes, restarts via SSH)

## Debugging
- **Production logs:** `bash scripts/logs` — fetches journalctl from production via SSH
  - `bash scripts/logs -n 100` last N lines
  - `bash scripts/logs -f` follow
  - `bash scripts/logs --since "1 hour ago"`
  - Pipe through `grep` to filter: `bash scripts/logs -n 500 2>&1 | grep -i error`
- **View bugs:** `bash scripts/bugs` — lists open bugs from production database
- **Resolve bug:** `bash scripts/resolve-bug <id>` — marks a bug as resolved
- **Always check production logs first** when debugging reported issues

## State Management
- **SESSION_STATE.md:** The source of truth for resuming work. Must include:
    - Current Task Goal
    - Completed Items
    - **Next 3 Specific Steps**
- **Status tags:** `[TODO]` → `[IN_PROGRESS]` → `[REVIEW_READY]` → `[APPROVED]` (or `[NEEDS_FIX]`)

## Technical Context
- **Trello is PRIMARY:** Key + Token required in query params.
- **Architecture:** chi router → Handlers (`internal/handlers/`) → Store (`internal/store/sqlite.go`).
- **Errors:** Partial data/cache fallback preferred over hard failure.
- **Full details:** See `DESIGN.md` → Architecture section.

## Coding Style
- Use concise, idiomatic Go.
- Avoid verbose explanations or comments for self-evident logic.
- Prioritize terminal-based verification over manual code review.
- **Patterns:** See `DESIGN.md` → Development Guide for handler/template patterns.

## Test Quality Checklist
When writing or reviewing tests, verify:
- **Effective:** Assertions match test name. Test would fail if code was broken.
- **Clear:** Arrange-Act-Assert structure. Descriptive names like `TestHandler_MissingField_Returns400`.
- **Complete:** Happy path + error cases + edge cases. Bug fixes include regression tests.

## Documentation
- **ADR-first:** Capture architectural decisions in `docs/adr/*.md`, not one-off design docs.
- **Update DESIGN.md** for new features, endpoints, or schema changes.
- **Do NOT create** standalone design documents—use ADRs instead.