From ad3a3d42ef0c60192604a1d3ac52196d4a4ba0a3 Mon Sep 17 00:00:00 2001 From: Arthur Belleville Date: Thu, 14 May 2026 17:19:04 +0200 Subject: [PATCH] docs(01): create phase plan (4 plans, MVP walking skeleton) --- .planning/STATE.md | 5 +++-- .planning/phases/01-foundation/01-01-PLAN.md | 10 ++++++++++ .planning/phases/01-foundation/01-02-PLAN.md | 3 +++ .planning/phases/01-foundation/01-03-PLAN.md | 5 +++++ .planning/phases/01-foundation/01-04-PLAN.md | 2 ++ .planning/phases/01-foundation/01-RESEARCH.md | 8 ++++---- 6 files changed, 27 insertions(+), 6 deletions(-) diff --git a/.planning/STATE.md b/.planning/STATE.md index 938fedc..875dc05 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -3,12 +3,13 @@ gsd_state_version: 1.0 milestone: v1.0 milestone_name: milestone status: unknown -last_updated: "2026-05-14T14:42:38.681Z" +last_updated: "2026-05-14T15:18:59.172Z" progress: total_phases: 7 completed_phases: 0 - total_plans: 0 + total_plans: 4 completed_plans: 0 + percent: 0 --- # STATE diff --git a/.planning/phases/01-foundation/01-01-PLAN.md b/.planning/phases/01-foundation/01-01-PLAN.md index 4a78673..68df887 100644 --- a/.planning/phases/01-foundation/01-01-PLAN.md +++ b/.planning/phases/01-foundation/01-01-PLAN.md @@ -41,6 +41,16 @@ must_haves: - "Running `just --list` shows recipes for at least: bootstrap, dev, db-up, db-down, migrate, generate, styles-watch, test, lint, build" - "Tailwind input CSS declares @source globs that include backend/templates/**/*.templ and backend/internal/web/**/*.{templ,go} so JIT does not purge classes used only in templ files" - ".env.example documents DATABASE_URL, PORT, ENV and .env is gitignored" + - "D-01: Two-binary cmd/web + cmd/worker layout with shared internal/ packages" + - "D-02: Phase 1 creates directory skeleton for all internal/ packages with placeholder doc.go files" + - "D-04: goose (pressly/goose) chosen as migration tool with .sql files using +goose Up/Down annotations" + - "D-05: just migrate up/down/status recipes wired via goose CLI for local development" + - "D-06: Phase 1 includes one trivial bootstrap migration 0001_init.sql exercising the migration pipeline end-to-end" + - "D-12: Standalone Tailwind CLI binary downloaded by just bootstrap into ./bin/tailwindcss — no Node or pnpm toolchain" + - "D-13: air (cosmtrek/air) used for Go live-reload via just dev watching .go and .templ files" + - "D-14: Tailwind watch mode runs as separate just styles-watch process — not via air pre_cmd" + - "D-15: Env-driven configuration via .env files with required keys DATABASE_URL PORT ENV documented in .env.example" + - "D-16: Postgres driver pgx/v5 with pgxpool for connection pool; sqlc configured to emit pgx-compatible code" artifacts: - path: backend/go.mod provides: Go module declaration with required deps (chi, templ, pgx, goose, uuid) diff --git a/.planning/phases/01-foundation/01-02-PLAN.md b/.planning/phases/01-foundation/01-02-PLAN.md index 9be6255..0ff1604 100644 --- a/.planning/phases/01-foundation/01-02-PLAN.md +++ b/.planning/phases/01-foundation/01-02-PLAN.md @@ -37,6 +37,9 @@ must_haves: - "The `internal/web/ui` design-system package compiles standalone and its `ui_test.go` smoke tests PASS — each shipped variant of Button, Card, Badge renders without panicking and emits the expected root CSS class" - "The UI component package mirrors the enum surface of `go-backend/internal/web/ui/` for Size, ButtonVariant, ButtonTone, BadgeVariant — future phases extend these enums' CSS without redefining them" - "Test files declare the exact handler function signatures and templ component names that Plan 03 will implement, so Plan 03 is a fill-in not an exploration" + - "D-07: templ (a-h/templ) used as type-safe HTML templating; UI library components are templ functions returning templ.Component" + - "D-09: templ generate runs as part of the dev loop via just generate alongside sqlc generate; *_templ.go artifacts are gitignored" + - "D-20: /healthz response shape locked — 200 with status:ok db:ok when pinger succeeds; 503 with status:degraded db:down otherwise — asserted by TestHealthz_OK and TestHealthz_Down" artifacts: - path: backend/internal/web/ui/variants.go provides: Size, ButtonVariant, ButtonTone, BadgeVariant enums + class-builder functions + normalizers diff --git a/.planning/phases/01-foundation/01-03-PLAN.md b/.planning/phases/01-foundation/01-03-PLAN.md index 7e33450..076349b 100644 --- a/.planning/phases/01-foundation/01-03-PLAN.md +++ b/.planning/phases/01-foundation/01-03-PLAN.md @@ -38,6 +38,11 @@ must_haves: - "The root page is rendered via `internal/web/ui` components — handlers do NOT inline Tailwind classes — and contains the canonical `hx-get` button declared in UI-SPEC" - "Sending SIGINT to the web binary triggers graceful shutdown: in-flight requests are allowed to finish (up to 10s), then the pgxpool is closed, then the process exits 0" - "`./tmp/worker` connects to Postgres, logs `worker ready` via slog, blocks on signal, and exits 0 on SIGINT (D-03)" + - "D-08: chi router middleware stack ordered RequestID then RealIP then Logger then Recoverer per the locked CONTEXT decision" + - "D-10: HTMX runtime vendored at backend/static/htmx.min.js — never loaded from a CDN; base layout references the local path" + - "D-17: Structured logging via log/slog standard library — JSON handler when ENV=production and text handler in development" + - "D-18: RequestID middleware attaches a UUIDv4 per request into context.Context and onto the slog logger as request_id attribute" + - "D-19: Graceful shutdown traps SIGINT and SIGTERM; http.Server.Shutdown runs with 10-second timeout then pgxpool Close runs before process exits" artifacts: - path: backend/internal/db/pool.go provides: NewPool(ctx, dsn) (*pgxpool.Pool, error) per RESEARCH Pattern 1 diff --git a/.planning/phases/01-foundation/01-04-PLAN.md b/.planning/phases/01-foundation/01-04-PLAN.md index 0d56210..ceeea41 100644 --- a/.planning/phases/01-foundation/01-04-PLAN.md +++ b/.planning/phases/01-foundation/01-04-PLAN.md @@ -20,6 +20,8 @@ must_haves: - "The README spells out the docker compose fallback for contributors who don't use podman (D-11)" - "The README documents the two-terminal dev workflow (`just dev` + `just styles-watch`) per RESEARCH Open Question 2" - "The README documents the bootstrap order: `just bootstrap` → `just db-up` → `just migrate up` → `just dev` (in 1st terminal) + `just styles-watch` (in 2nd terminal) → open localhost:8080" + - "D-11: podman compose chosen for local Postgres; README documents docker compose as the fallback for contributors who do not use podman" + - "D-14: README documents the two-terminal dev workflow — just dev in terminal 1 and just styles-watch in terminal 2 — per the locked Tailwind watch decision" artifacts: - path: backend/README.md provides: Five-minute onboarding doc covering prereqs, bootstrap, dev workflow, common commands, troubleshooting pointers diff --git a/.planning/phases/01-foundation/01-RESEARCH.md b/.planning/phases/01-foundation/01-RESEARCH.md index 6a4b16c..d0544f6 100644 --- a/.planning/phases/01-foundation/01-RESEARCH.md +++ b/.planning/phases/01-foundation/01-RESEARCH.md @@ -655,22 +655,22 @@ stop_on_error = true **Interpretation:** All four assumptions are LOW risk; planner can proceed without user confirmation but should re-verify HTMX/Tailwind versions at the moment of bootstrap. -## Open Questions +## Open Questions (RESOLVED) 1. **Goose: pure CLI in Phase 1, or library-call from a `backend migrate` subcommand now?** - What we know: D-04 + D-05 say CLI for Phase 1; D-71 (Claude's discretion) says planner may set up for Phase 7's likely library approach. - What's unclear: Whether to add the `cmd/migrate/main.go` (or `cmd/web` subcommand) skeleton now or wait. - - Recommendation: Pure CLI in Phase 1. Adding the library wiring now blurs the phase boundary and creates two migration paths (CLI + lib) before one is hardened. Phase 7 can introduce `cmd/web migrate` cleanly. + - RESOLVED: Pure CLI in Phase 1. Adding the library wiring now blurs the phase boundary and creates two migration paths (CLI + lib) before one is hardened. Phase 7 can introduce `cmd/web migrate` cleanly. 2. **Tailwind watch: separate `just styles` process, or air `pre_cmd`?** - What we know: D-14 leaves this to the planner. - What's unclear: Whether developers run `just dev` (one terminal) or `just dev` + `just styles` (two terminals). - - Recommendation: Two terminals — keep concerns separated. Tailwind watch is independent of Go rebuild; piping through air's `pre_cmd` would trigger CSS rebuild on every `.go` save, which is wasteful. Document the two-terminal workflow in README. + - RESOLVED: Two terminals — keep concerns separated. Tailwind watch is independent of Go rebuild; piping through air's `pre_cmd` would trigger CSS rebuild on every `.go` save, which is wasteful. Document the two-terminal workflow in README. 3. **Phase 1 `/healthz` smoke test: ship it or defer?** - What we know: Phase 2 establishes the testing strategy. - What's unclear: Whether a single `handlers_test.go` covering `/healthz` (with a stub `Pinger` interface) earns its keep now. - - Recommendation: Ship it. It exercises the chi+slog wiring, provides a regression net for Phase 2 to extend, and the `Pinger` interface stub costs <10 lines. See Validation Architecture below. + - RESOLVED: Ship it. It exercises the chi+slog wiring, provides a regression net for Phase 2 to extend, and the `Pinger` interface stub costs <10 lines. See Validation Architecture below. ## Environment Availability