diff options
| -rw-r--r-- | ARCHITECT_ROLE.md | 12 | ||||
| -rw-r--r-- | CLAUDE.md | 37 | ||||
| -rw-r--r-- | DESIGN.md | 111 | ||||
| -rw-r--r-- | IMPLEMENTOR_ROLE.md | 18 | ||||
| -rw-r--r-- | REVIEWER_ROLE.md | 8 |
5 files changed, 115 insertions, 71 deletions
diff --git a/ARCHITECT_ROLE.md b/ARCHITECT_ROLE.md index 409102d..5697f69 100644 --- a/ARCHITECT_ROLE.md +++ b/ARCHITECT_ROLE.md @@ -1,7 +1,7 @@ # Senior Go Architect & Security Lead Persona **Role:** You are acting as a **Senior Go Architect and Security Lead**. -**Project Context:** I am building a unified personal dashboard using Go 1.21, SQLite (caching layer), chi router, and HTMX. +**Project Context:** Unified personal dashboard using Go 1.24, SQLite (caching layer), chi router, and HTMX. **Shared Standards (CLAUDE.md):** * **Efficiency:** Prioritize surgical edits over full-file rewrites. @@ -9,7 +9,7 @@ * **Architecture:** Handler -> Store (SQLite) -> API Clients. * **State:** Maintain `SESSION_STATE.md` as the source of truth for handoffs. -**Gemini Architect Persona:** +**Architect Persona:** * You are the **Lead Architect**. * **Constraint:** You **DO NOT** write or edit Project Source Code (e.g., `.go`, `.html`, `.js`). * **Responsibility:** You **DO** write and update documentation and instruction files (e.g., `SESSION_STATE.md`, `instructions.md`, `issues/*.md`, `docs/adr/*.md`). Your job is to prepare surgical plans for the implementation agent (Claude Code) to execute and guide the Reviewer. @@ -25,12 +25,12 @@ 1. **Analyze:** * When pointed to a task or file, use tools (`read_file`, `grep`, `ls`) to understand the current state. - * Identify specific lines needing fixes based on `SECURITY_CHECKLIST.md` or the current feature requirement. + * Identify specific lines needing fixes based on the current feature requirement. 2. **Bug Handling Protocol:** - * **Create Issue:** When a bug is identified, create a file in `issues/` (e.g., `issues/bug_00X_description.md`). - * **Document:** Describe the bug, root cause, and a plan to fix it. - * **Reproduction:** ALWAYS include instructions for a reproduction test case (preferably an automated `_test.go` file) in the issue document. + * **In-app bugs:** Users report via the dashboard UI. View with `bash scripts/bugs`, resolve with `bash scripts/resolve-bug <id>`. + * **Feature issues:** Create a file in `issues/` (e.g., `issues/feature_description.md`) for larger feature specs. + * **Reproduction:** ALWAYS include instructions for a reproduction test case (preferably an automated `_test.go` file). * **State:** Update `SESSION_STATE.md` to track the issue. 3. **Document & State Management:** @@ -1,8 +1,8 @@ # Claude Code Project Guidelines ## Project Overview -A unified web dashboard aggregating Trello (PRIMARY), Todoist, Obsidian, and PlanToEat. -**Stack:** Go backend + HTMX + Tailwind CSS + SQLite. +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) @@ -12,22 +12,14 @@ A unified web dashboard aggregating Trello (PRIMARY), Todoist, Obsidian, and Pla | `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 +### Multi-Agent Workflow (Optional) -This project uses a three-role development workflow. **Read your role definition before starting work:** - -| Role | Definition File | Responsibilities | -|------|-----------------|------------------| -| Architect | `ARCHITECT_ROLE.md` | Plans, documents, creates ADRs. Does NOT edit code. | -| Implementor | `IMPLEMENTOR_ROLE.md` | Executes plans, writes code, runs tests. | -| Reviewer | `REVIEWER_ROLE.md` | Reviews code quality and tests. Does NOT edit code. | - -**Handoff docs:** `instructions.md` (Architect → Implementor), `review_feedback.md` (Reviewer → Implementor) +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. ## Efficiency & Token Management -- **Context Minimization:** Do not read entire files if `grep`, `sed`, or `ls` can answer a question. +- **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`, and `lint` to verify state rather than asking the agent to "think" through logic. +- **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 @@ -48,6 +40,17 @@ This project uses a three-role development workflow. **Read your role definition - **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: @@ -68,6 +71,12 @@ This project uses a three-role development workflow. **Read your role definition - 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. @@ -4,7 +4,7 @@ Task Dashboard is a personal productivity web application that aggregates tasks, meals, calendar events, and shopping lists from multiple external services into a unified, mobile-friendly interface. Built with Go backend, HTMX frontend, Tailwind CSS styling, and SQLite storage. -**Stack:** Go 1.21+ | chi router | HTMX 1.x | Tailwind CSS | SQLite (WAL mode) +**Stack:** Go 1.24 | chi router | HTMX 1.x | Tailwind CSS | SQLite (WAL mode) --- @@ -12,7 +12,7 @@ Task Dashboard is a personal productivity web application that aggregates tasks, The dashboard serves as a **personal consolidation hub** designed to: -1. **Aggregate multiple data sources** into one view (Trello, Todoist, PlanToEat, Google Calendar, Google Tasks) +1. **Aggregate multiple data sources** into one view (Trello, Todoist, PlanToEat, Google Calendar, Google Tasks, user-reported bugs) 2. **Prioritize reliability** over speed - graceful degradation when APIs fail 3. **Support mobile-first usage** - optimized for phone/tablet in-store or on-the-go 4. **Minimize context switching** - complete tasks from any source without opening multiple apps @@ -22,15 +22,15 @@ The dashboard serves as a **personal consolidation hub** designed to: ## Development Workflow -This project uses a **multi-agent development workflow** with three specialized roles that collaborate through shared documents. +This project supports a **multi-agent development workflow** with three specialized roles. The primary workflow is single-agent (Claude Code reading CLAUDE.md + DESIGN.md directly). The role files exist for optional multi-agent use. ### Roles -| Role | Agent | Responsibilities | -|------|-------|------------------| -| **Architect** | Gemini | Plans features, creates issues, writes surgical instructions. Does NOT edit source code. | -| **Implementor** | Claude Code | Executes plans, writes code, runs tests. Updates state after completing work. | -| **Reviewer** | QA Agent | Reviews code quality, runs tests, provides feedback. Does NOT edit source code. | +| Role | Responsibilities | +|------|------------------| +| **Architect** | Plans features, creates issues, writes surgical instructions. Does NOT edit source code. | +| **Implementor** | Executes plans, writes code, runs tests. Updates state after completing work. | +| **Reviewer** | Reviews code quality, runs tests, provides feedback. Does NOT edit source code. | ### Role Definitions @@ -89,7 +89,7 @@ Tasks flow through these states: ``` task-dashboard/ ├── cmd/dashboard/ -│ └── main.go # Application entry point, route registration +│ └── main.go # Entry point, route registration, ldflags ├── internal/ │ ├── api/ # External API clients │ │ ├── interfaces.go # API client contracts (interfaces) @@ -100,40 +100,54 @@ task-dashboard/ │ │ ├── google_calendar.go # Google Calendar integration │ │ └── google_tasks.go # Google Tasks integration │ ├── auth/ -│ │ ├── auth.go # Authentication service (bcrypt) -│ │ ├── handlers.go # Login/logout handlers +│ │ ├── auth.go # Authentication service (bcrypt + WebAuthn) +│ │ ├── handlers.go # Login/logout/passkey handlers │ │ └── middleware.go # Session + CSRF protection │ ├── config/ │ │ ├── config.go # Environment configuration │ │ ├── constants.go # App constants (timeouts, limits) │ │ └── timezone.go # Display timezone helpers │ ├── handlers/ -│ │ ├── handlers.go # Main HTTP handlers (~2000 LOC) -│ │ ├── response.go # JSON/HTML response utilities -│ │ ├── cache.go # Generic cache fetcher pattern -│ │ ├── atoms.go # Unified task aggregation +│ │ ├── handlers.go # Main HTTP handlers + aggregation +│ │ ├── settings.go # Settings page handlers +│ │ ├── shopping.go # Shopping tab + mode handlers +│ │ ├── agent.go # Agent auth + context API +│ │ ├── websocket.go # WebSocket notification hub │ │ ├── timeline.go # Timeline view handler -│ │ └── timeline_logic.go # Timeline data processing +│ │ ├── timeline_logic.go # Timeline data processing +│ │ ├── atoms.go # Unified task aggregation +│ │ ├── cache.go # Generic cache fetcher pattern +│ │ ├── helpers.go # Form parsing helpers +│ │ ├── renderer.go # Template renderer interface +│ │ └── response.go # JSON/HTML response utilities │ ├── middleware/ │ │ └── security.go # Security headers + rate limiting │ ├── models/ -│ │ ├── types.go # Data models (Task, Card, Meal, etc.) +│ │ ├── types.go # Data models (Task, Card, Meal, Agent, etc.) │ │ ├── atom.go # Unified Atom model + converters │ │ └── timeline.go # TimelineItem + DaySection models │ └── store/ -│ └── sqlite.go # SQLite database layer (~700 LOC) -├── migrations/ # SQL migration files (001-009) +│ └── sqlite.go # SQLite database layer +├── migrations/ # SQL migration files (001-014) +├── scripts/ +│ ├── bugs # List bugs from production DB +│ ├── logs # Fetch production journalctl +│ └── resolve-bug # Resolve a production bug ├── web/ │ ├── templates/ │ │ ├── index.html # Main dashboard shell │ │ ├── login.html # Authentication page +│ │ ├── settings.html # Settings + passkeys page │ │ ├── conditions.html # Standalone live feeds page │ │ ├── shopping-mode.html # Full-screen shopping mode -│ │ └── partials/ # HTMX partial templates +│ │ ├── passkeys_list.html # Passkeys list partial +│ │ ├── agent-*.html # Agent auth flow pages (4 files) +│ │ └── partials/ # HTMX partial templates (12 files) │ └── static/ │ ├── css/input.css # Tailwind source │ ├── css/output.css # Compiled CSS -│ └── js/app.js # Client-side logic +│ └── js/app.js # Client-side logic + WebSocket +├── deploy.sh # Build + deploy script (ldflags injection) └── tailwind.config.js ``` @@ -524,7 +538,7 @@ func (h *Handler) HandleNewFeature(w http.ResponseWriter, r *http.Request) { _ = h.store.SaveResult(result) // 5. Respond - HTMLResponse(w, h.templates, "partial-name", result) + HTMLResponse(w, h.renderer, "partial-name", result) } ``` @@ -576,10 +590,10 @@ r.Post("/newfeature/action", h.HandleNewAction) **Example:** ```go // Standalone page - use filename -h.templates.ExecuteTemplate(w, "shopping-mode.html", data) +h.renderer.Render(w, "shopping-mode.html", data) // Partial - use define name -HTMLResponse(w, h.templates, "shopping-tab", data) +HTMLResponse(w, h.renderer, "shopping-tab", data) ``` ### HTMX Patterns @@ -641,21 +655,25 @@ func TestHandler_HandleDashboard(t *testing.T) { ### Debugging Tips -1. **Check logs:** All errors logged with `log.Printf` -2. **Cache issues:** Check `cache_metadata` table for stale timestamps -3. **API failures:** Look for `"Warning:"` or `"ERROR:"` prefixes -4. **Template errors:** Check for `html/template: "name" is undefined` -5. **HTMX issues:** Browser DevTools Network tab shows all requests +1. **Production logs:** `bash scripts/logs -n 200 2>&1 | grep -i error` +2. **Production bugs:** `bash scripts/bugs` to list, `bash scripts/resolve-bug <id>` to close +3. **Cache issues:** Check `cache_metadata` table for stale timestamps +4. **API failures:** Look for `"Warning:"` or `"ERROR:"` prefixes in logs +5. **Template errors:** Check for `html/template: "name" is undefined` +6. **HTMX issues:** Browser DevTools Network tab shows all requests +7. **WebAuthn issues:** Check for "WebAuthn initialized" in startup logs; requires `WEBAUTHN_RP_ID` + `WEBAUTHN_ORIGIN` env vars ### Files You'll Modify Most | Task | Primary Files | |------|--------------| -| New feature | `handlers.go`, `main.go`, new template | -| Bug fix | Usually `handlers.go` or specific API client | +| New feature | `handlers.go` or new handler file, `main.go`, new template | +| Bug fix | Relevant handler file or API client | | UI change | Template in `partials/`, maybe `input.css` | | API integration | New file in `internal/api/`, update `interfaces.go` | -| Database change | New migration, update `sqlite.go` | +| Database change | New migration in `migrations/`, update `sqlite.go` | +| Settings | `settings.go`, `settings.html` | +| Shopping | `shopping.go`, `shopping-tab.html` or `shopping-mode.html` | ### Configuration Reference @@ -668,13 +686,19 @@ func TestHandler_HandleDashboard(t *testing.T) { **Optional:** - `DEFAULT_USER` (default: "admin") - `PLANTOEAT_SESSION` - PlanToEat session cookie +- `PLANTOEAT_API_KEY` - PlanToEat API key - `GOOGLE_CREDENTIALS_FILE` - OAuth credentials JSON path -- `GOOGLE_CALENDAR_ID` (default: "primary") +- `GOOGLE_CALENDAR_ID` (default: "primary") — comma-separated for multiple - `GOOGLE_TASKS_LIST_ID` (default: "@default") +- `WEBAUTHN_RP_ID` - Passkey Relying Party ID (e.g., "doot.terst.org") +- `WEBAUTHN_ORIGIN` - Passkey expected origin (e.g., "https://doot.terst.org") - `DATABASE_PATH` (default: "./dashboard.db") - `PORT` (default: "8080") - `CACHE_TTL_MINUTES` (default: 5) - `TIMEZONE` (default: "Pacific/Honolulu") +- `TEMPLATE_DIR` (default: "web/templates") +- `STATIC_DIR` (default: "web/static") +- `MIGRATION_DIR` (default: "migrations") - `DEBUG` (default: false) ### Common Mistakes to Avoid @@ -745,7 +769,7 @@ Short summary (50 chars or less) Optional longer description explaining the why, not the what. Reference bug numbers with #N format. -Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> +Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> ``` **If history diverges:** Use `git pull --rebase=false` to merge, never force push. @@ -787,8 +811,11 @@ Bugs appear as atoms in the Tasks view (🐛 icon) until resolved. | Component | Test File | |-----------|-----------| | Store methods | `internal/store/sqlite_test.go` | -| Handlers | `internal/handlers/*_test.go` | +| Handlers | `internal/handlers/handlers_test.go` | +| Timeline logic | `internal/handlers/timeline_logic_test.go` | +| Agent handlers | `internal/handlers/agent_test.go` | | API clients | `internal/api/*_test.go` | +| Auth | `internal/auth/*_test.go` | | Integration | `test/acceptance_test.go` | **Running tests:** @@ -915,11 +942,16 @@ npx tailwindcss -i web/static/css/input.css -o web/static/css/output.css --watch | GET | `/` | Main dashboard | | GET | `/tabs/timeline` | Timeline partial | | GET | `/tabs/tasks` | Tasks partial | +| GET | `/tabs/planning` | Planning partial | +| GET | `/tabs/meals` | Meals partial | | GET | `/tabs/shopping` | Shopping partial | +| GET | `/tabs/conditions` | Conditions partial | | GET | `/conditions` | Live feeds page (public) | -| POST | `/complete-atom` | Complete task/card | +| POST | `/complete-atom` | Complete task/card/bug | | POST | `/uncomplete-atom` | Reopen task/card | | POST | `/unified-add` | Quick add task | +| GET | `/bugs` | List bug reports | +| POST | `/bugs` | Submit bug report | | POST | `/shopping/add` | Add shopping item | | GET | `/shopping/mode/{store}` | Shopping mode view | | POST | `/shopping/mode/{store}/toggle` | Toggle shopping item | @@ -927,6 +959,9 @@ npx tailwindcss -i web/static/css/input.css -o web/static/css/output.css --watch | GET | `/settings` | Settings page | | POST | `/settings/features` | Create feature toggle | | POST | `/settings/features/toggle` | Toggle feature on/off | +| GET | `/settings/passkeys` | List passkeys (requires WebAuthn) | +| POST | `/passkeys/register/begin` | Start passkey registration | +| POST | `/passkeys/register/finish` | Complete passkey registration | | GET | `/ws/notifications` | WebSocket for agent notifications | | POST | `/agent/auth/request` | Agent requests access | | GET | `/agent/auth/poll` | Agent polls for approval | @@ -945,8 +980,8 @@ func (h *Handler) HandleName(w http.ResponseWriter, r *http.Request) { ### Response Helpers ```go -JSONResponse(w, data) // 200 + JSON +JSONResponse(w, data) // 200 + JSON + no-cache JSONError(w, status, "message", err) // Error + log -HTMLResponse(w, h.templates, "name", data) // Partial render +HTMLResponse(w, h.renderer, "name", data) // Partial render + no-cache HTMLString(w, "<html>...</html>") // Raw HTML ``` diff --git a/IMPLEMENTOR_ROLE.md b/IMPLEMENTOR_ROLE.md index 31c3f53..be12a9d 100644 --- a/IMPLEMENTOR_ROLE.md +++ b/IMPLEMENTOR_ROLE.md @@ -1,15 +1,15 @@ # Senior Go Developer & Implementation Specialist Persona **Role:** You are acting as a **Senior Go Developer and Implementation Specialist**. -**Project Context:** Unified personal dashboard using Go 1.21, SQLite (caching layer), chi router, and HTMX. +**Project Context:** Unified personal dashboard using Go 1.24, SQLite (caching layer), chi router, and HTMX. **Shared Standards (CLAUDE.md):** -* **Efficiency:** Prioritize surgical edits (`replace_text`) over full-file rewrites. -* **Tools:** Use terminal commands (`go test`, `go build`, `grep`) to verify state before and after changes. +* **Efficiency:** Prioritize surgical edits over full-file rewrites. +* **Tools:** Use `go test`, `go build`, Grep/Glob to verify state before and after changes. * **Architecture:** Handler -> Store (SQLite) -> API Clients. * **State:** Respect the direction set in `SESSION_STATE.md`. **CRITICAL:** You are responsible for keeping `SESSION_STATE.md` up-to-date as you complete tasks. -**Claude Code Implementor Persona:** +**Implementor Persona:** * You are the **Implementor**. * **Constraint:** You focus on **execution**, **coding**, and **verification**. * **Responsibility:** You **DO** write and edit Project Source Code (e.g., `.go`, `.html`, `.js`). Your job is to execute the surgical plans prepared by the Architect. @@ -22,8 +22,8 @@ * **New Instructions:** If no fixes are needed, read `instructions.md` for new work. 2. **Verify Context:** - * Before editing, use `ls`, `read_file`, or `grep` to confirm file paths and the current code state match the instructions. - * **Check relevant ADRs** in `docs/adr/` for architectural context and constraints. + * Before editing, use Glob, Read, or Grep to confirm file paths and the current code state match the instructions. + * **Check relevant ADRs** in `docs/adr/` for architectural context and constraints (001=auth, 002=timeline, 003=HTMX, 004=caching, 005=agent API). * If the instructions seem outdated or conflict with the current codebase or ADRs, stop and ask for clarification. 3. **Test-Driven Execution (TDD):** @@ -31,7 +31,7 @@ * **Create Test:** If a new feature or complex bug fix is requested, create a `_test.go` file first if one wasn't provided. 4. **Surgical Execution:** - * **Edit:** Apply changes using `replace_text` whenever possible to minimize token usage and risk of overwriting unrelated code. Use `write_file` only for new files or massive rewrites. + * **Edit:** Apply targeted changes using the Edit tool to minimize risk of overwriting unrelated code. Use Write only for new files. * **Style:** Adhere to Go standard formatting (`gofmt`) and the project's existing style. 5. **Verify, Update State & Report:** @@ -43,8 +43,8 @@ * **Output:** clearly state which files were modified and the result of the verification tests. **Tool Usage Protocol:** -* **Terminal:** Use `run_terminal_cmd` for `go test`, `go build`, `go mod tidy`, etc. -* **Editing:** Prefer `replace_text` for targeted edits. +* **Terminal:** Use Bash for `go test`, `go build`, `go mod tidy`, etc. +* **Editing:** Prefer Edit for targeted edits, Write for new files only. **Self-Improvement:** * **Reflection:** After completing a task, ask: "Did I follow TDD? Is the code clean enough that the Reviewer won't find major issues?" diff --git a/REVIEWER_ROLE.md b/REVIEWER_ROLE.md index 9bcf101..ca3baa4 100644 --- a/REVIEWER_ROLE.md +++ b/REVIEWER_ROLE.md @@ -1,7 +1,7 @@ # Senior Code Reviewer & QA Specialist Persona **Role:** You are acting as a **Senior Code Reviewer and QA Specialist**. -**Project Context:** Unified personal dashboard using Go 1.21, SQLite (caching layer), chi router, and HTMX. +**Project Context:** Unified personal dashboard using Go 1.24, SQLite (caching layer), chi router, and HTMX. **Shared Standards (CLAUDE.md):** * **Clean Code:** Prioritize readability, simplicity, and testability. Follow Martin's Clean Code principles. @@ -69,9 +69,9 @@ * `## Praise`: What was done well. **Tool Usage Protocol:** -* **Read-Only:** Use `read_file`, `grep`, `ls` to inspect code. -* **Execution:** Use `run_terminal_cmd` to run tests. -* **Reporting:** Use `write_file` to publish `review_feedback.md` and update `SESSION_STATE.md`. +* **Read-Only:** Use Read, Grep, Glob to inspect code. +* **Execution:** Use Bash to run tests (`go test ./...`, `go test -cover ./...`). +* **Reporting:** Use Write to publish `review_feedback.md` and Edit to update `SESSION_STATE.md`. **Self-Improvement:** * **Reflection:** After a review cycle, ask: "Did my feedback help the Implementor improve the code, or did it just create busy work?" |