From 223c94f52ebaa878f6951ebf7d08754e413bdca7 Mon Sep 17 00:00:00 2001
From: Peter Stone <thepeterstone@gmail.com>
Date: Thu, 5 Feb 2026 10:37:09 -1000
Subject: Document multi-agent workflow, ADRs, and Agent API

- Add Development Workflow section to DESIGN.md documenting three-role
  system (Architect, Implementor, Reviewer) with handoff documents
- Update CLAUDE.md with Key Documents section pointing to DESIGN.md,
  role definitions, and ADRs
- Add ADR-first documentation policy across all role definitions
- Update REVIEWER_ROLE.md with comprehensive test quality checklist
- Document Agent API and completed tasks log in DESIGN.md
- Update database schema table with 5 missing tables
- Update endpoint reference with 10 missing routes
- Create ADRs 002-005 capturing key architectural decisions:
  - 002: Timeline aggregation architecture
  - 003: HTMX write operations pattern
  - 004: Concurrent data fetching with graceful degradation
  - 005: Agent API notification-based authentication
- Add migrations/README.md documenting schema history and 007 gap

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 CLAUDE.md | 35 +++++++++++++++++++++++++++++++----
 1 file changed, 31 insertions(+), 4 deletions(-)

(limited to 'CLAUDE.md')

diff --git a/CLAUDE.md b/CLAUDE.md
index dbef146..c4834a5 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,9 +1,29 @@
 # Claude Code Project Guidelines
 
 ## Project Overview
-A unified web dashboard aggregating Trello (PRIMARY), Todoist, Obsidian, and PlanToEat. 
+A unified web dashboard aggregating Trello (PRIMARY), Todoist, Obsidian, and PlanToEat.
 **Stack:** Go backend + 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
+
+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)
+
 ## Efficiency & Token Management
 - **Context Minimization:** Do not read entire files if `grep`, `sed`, or `ls` can answer a question.
 - **Surgical Edits:** Perform small, targeted file edits. Avoid rewriting entire files for single changes.
@@ -22,19 +42,26 @@ A unified web dashboard aggregating Trello (PRIMARY), Todoist, Obsidian, and Pla
 - **Build:** `go build -o dashboard cmd/dashboard/main.go`
 
 ## State Management
-- **SESSION_STATE.md:** The source of truth for resuming work. It must include:
+- **SESSION_STATE.md:** The source of truth for resuming work. Must include:
     - Current Task Goal
     - Completed Items
-    - Architecture Decisions
     - **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`).
+- **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.
+
+## 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.
 
-- 
cgit v1.2.3