diff options
Diffstat (limited to 'DESIGN.md')
| -rw-r--r-- | DESIGN.md | 157 |
1 files changed, 2 insertions, 155 deletions
@@ -20,79 +20,6 @@ The dashboard serves as a **personal consolidation hub** designed to: --- -## Development Workflow - -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 | 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 - -Each role has a detailed persona document: - -- `ARCHITECT_ROLE.md` - Planning, documentation, issue tracking -- `IMPLEMENTOR_ROLE.md` - Code execution, TDD, verification -- `REVIEWER_ROLE.md` - Quality gates, clean code review - -### Handoff Documents - -| Document | Purpose | Writer | Reader | -|----------|---------|--------|--------| -| `instructions.md` | Surgical implementation plan (ephemeral) | Architect | Implementor | -| `review_feedback.md` | Code review results (ephemeral) | Reviewer | Implementor | -| `SESSION_STATE.md` | Current state + next steps | All | All | -| `issues/*.md` | Bug reports + feature specs | Architect | All | -| `docs/adr/*.md` | Architectural decisions (permanent) | Architect | All | - -**Note:** `instructions.md` and `review_feedback.md` are ephemeral - they contain current task details. Architectural decisions belong in ADRs, not in ephemeral docs. - -### Status Tags - -Tasks flow through these states: - -``` -[TODO] → [IN_PROGRESS] → [REVIEW_READY] → [APPROVED] - ↑ ↓ - └── [NEEDS_FIX] ←┘ -``` - -### Workflow Example - -1. **Architect** identifies bug, creates `issues/bug_042_description.md` -2. **Architect** writes fix plan to `instructions.md`, updates `SESSION_STATE.md` to `[TODO]` -3. **Implementor** reads instructions, writes failing test (TDD), implements fix -4. **Implementor** runs `go test ./...`, updates state to `[REVIEW_READY]` -5. **Reviewer** reads code, runs tests, writes `review_feedback.md` -6. **Reviewer** marks `[APPROVED]` or `[NEEDS_FIX]` with specific feedback -7. If `[NEEDS_FIX]`, **Implementor** addresses feedback, returns to step 4 -8. **All roles** run self-improvement cycle: reflect, perform 1-3 improvements, record in `SESSION_STATE.md` - -### Self-Improvement Cycle - -After completing each task, every role performs a structured improvement cycle: - -1. **Reflect** — Answer role-specific questions about what went well and what caused friction -2. **Improve (1-3 actions)** — Make concrete changes: extract test helpers, add scripts, update checklists, fix role definitions, document bug patterns, create ADRs for implicit decisions -3. **Record** — Log improvements in `SESSION_STATE.md` → "Process Improvements" for cross-session visibility - -See each role file (`*_ROLE.md`) for the full role-specific checklist of reflection questions and improvement actions. - -### Principles - -- **Surgical edits** - Prefer targeted changes over full-file rewrites -- **TDD** - Write failing test before implementation -- **State tracking** - Always update `SESSION_STATE.md` after completing work -- **Tool verification** - Use `go test`, `go build`, `grep` to verify state before planning -- **ADR-first** - Document architectural decisions in ADRs, not one-off design docs - ---- - ## Architecture ### Directory Structure @@ -686,32 +613,6 @@ func TestHandler_HandleDashboard(t *testing.T) { | Settings | `settings.go`, `settings.html` | | Shopping | `shopping.go`, `shopping-tab.html` or `shopping-mode.html` | -### Configuration Reference - -**Required:** -- `TODOIST_API_KEY` - Todoist API key -- `TRELLO_API_KEY` - Trello API key -- `TRELLO_TOKEN` - Trello token -- `DEFAULT_PASS` - Admin password (must be set) - -**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") — 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 1. **Don't use `"name"` for standalone pages** - Use `"name.html"` @@ -721,7 +622,6 @@ func TestHandler_HandleDashboard(t *testing.T) { 5. **Don't add unnecessary comments** - Code should be self-explanatory 6. **Don't create new files unless necessary** - Prefer editing existing 7. **Don't refactor working code** - Only touch what's needed -8. **Don't alter git history** - Never amend, rebase, or force push. Keep a clean, linear history with new commits only. ### Feature Toggles @@ -765,26 +665,6 @@ if h.store.IsFeatureEnabled("my_feature") { | `calendar_timeline` | Show timeline as a calendar view with time slots | Disabled | | `completed_log` | Track and display completed tasks log | Enabled | -### Git Practices - -**Clean history principles:** -- **Never amend commits** - Create new commits for fixes instead -- **Never rebase** - Use merge to integrate changes -- **Never force push** - All pushes should be fast-forward only -- **One logical change per commit** - Keep commits focused and atomic - -**Commit message format:** -``` -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.6 <noreply@anthropic.com> -``` - -**If history diverges:** Use `git pull --rebase=false` to merge, never force push. - ### Bug Management Workflow Use the bug tracking system to report and resolve issues: @@ -810,13 +690,7 @@ Use the bug tracking system to report and resolve issues: Bugs appear as atoms in the Tasks view (🐛 icon) until resolved. -### Test-Driven Development (TDD) - -**Required approach for all changes:** - -1. **Write failing test first** - Define expected behavior before implementation -2. **Make it pass** - Write minimal code to pass the test -3. **Refactor** - Clean up while tests stay green +### Test Locations & Commands **Test locations:** | Component | Test File | @@ -860,28 +734,7 @@ func TestFeature_Behavior(t *testing.T) { } ``` -**Before submitting any change:** -- `go test ./...` must pass -- Add tests for new functionality -- Update tests for changed behavior - -### Architecture Decision Records (ADRs) - -**ADRs are the primary way to document architectural decisions.** They capture the context, decision, and tradeoffs for significant choices. Unlike one-off design documents that become stale, ADRs remain as a permanent record of why things are the way they are. - -**Always create an ADR when:** -- Choosing between multiple implementation approaches -- Adding new external dependencies or integrations -- Changing authentication, security, or data flow patterns -- Making significant refactoring decisions -- Introducing new patterns or abstractions - -**Do NOT create one-off design docs.** Instead: -- For feature planning → create an ADR with the architectural approach -- For implementation details → put them in `instructions.md` (ephemeral) -- For bug analysis → create an issue in `issues/` (ephemeral) - -**ADR location:** `docs/adr/NNN-title.md` +### Architecture Decision Records **Current ADRs:** | ADR | Decision | @@ -920,12 +773,6 @@ What did we decide and why? **Numbering:** Use sequential 3-digit numbers (001, 002, etc.) -**When to update DESIGN.md:** -- Adding new features or views (update Features section) -- New database tables (update Schema section) -- New API endpoints (update Quick Reference) -- Changes to the development workflow - --- ## Quick Reference |