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>
---
 docs/adr/003-htmx-write-operations.md | 85 +++++++++++++++++++++++++++++++++++
 1 file changed, 85 insertions(+)
 create mode 100644 docs/adr/003-htmx-write-operations.md

(limited to 'docs/adr/003-htmx-write-operations.md')

diff --git a/docs/adr/003-htmx-write-operations.md b/docs/adr/003-htmx-write-operations.md
new file mode 100644
index 0000000..2471a90
--- /dev/null
+++ b/docs/adr/003-htmx-write-operations.md
@@ -0,0 +1,85 @@
+# ADR 003: HTMX-Based Write Operations
+
+## Status
+Accepted
+
+## Context
+Phase 1-2 of the dashboard were read-only views. Phase 3 required transforming it into an active command center where users can:
+- Complete tasks/cards
+- Create new tasks
+- Add shopping items
+- Toggle item states
+
+Traditional approaches would require either:
+- Full page reloads (poor UX)
+- Complex JavaScript SPA framework (React, Vue)
+- Custom AJAX handlers
+
+## Decision
+Use **HTMX attributes** for all write operations, returning HTML partials that swap into the DOM.
+
+### Technical Details:
+
+**Pattern: Form submission with partial swap**
+```html
+<form hx-post="/complete-atom"
+      hx-vals='{"id": "{{.ID}}", "source": "{{.Source}}"}'
+      hx-target="closest .task-card"
+      hx-swap="outerHTML">
+    <button type="submit">✓</button>
+</form>
+```
+
+**Handler returns HTML partial:**
+```go
+func (h *Handler) HandleCompleteAtom(w http.ResponseWriter, r *http.Request) {
+    // ... complete the task via API
+    // Return completed state HTML or empty response
+    HTMLResponse(w, h.renderer, "completed-atom", data)
+}
+```
+
+**Quick Add Pattern:**
+```html
+<input hx-post="/unified-add"
+       hx-trigger="keyup[key=='Enter']"
+       hx-target="#task-list"
+       hx-swap="afterbegin"
+       name="content">
+```
+
+**Optimistic UI:**
+- Use CSS transitions for immediate visual feedback
+- On error, swap in error banner partial
+- HTMX `hx-on` events for state management
+
+**Unified Quick Add:**
+- Single input parses text for routing hints
+- `#groceries` tag → routes to shopping
+- `#work` tag → routes to Trello
+- Default → routes to Todoist
+
+## Consequences
+
+**Pros:**
+- No JavaScript framework needed
+- Server renders all HTML (single source of truth)
+- Progressive enhancement (works without JS, enhanced with)
+- Trivial to test (just HTTP handlers)
+- Fast development cycle
+
+**Cons:**
+- More HTTP requests than SPA approach
+- Partial HTML responses require careful template organization
+- Limited offline capability
+
+## Alternatives Considered
+
+**Option A: React/Vue SPA**
+- Rejected: Overkill for this use case, adds build complexity, harder to maintain
+
+**Option B: Full page reloads**
+- Rejected: Poor UX, especially on mobile
+
+**Option C: Custom JavaScript + JSON APIs**
+- Rejected: Reinventing what HTMX provides, more code to maintain
-- 
cgit v1.2.3