docs: refresh project CLAUDE.md for post-Phase-1 state

- Drop the "Open design questions (Phase 1)" section — answered in
  docs/design.md.
- Replace "Tech stack: TBD by inventor" with the actual stack
  (Go + pgx + html/template + HTMX, msupabase schema projax, Dokploy).
- Replace "Worker preferences: inventor / coder shifts" with the
  current state (PRD landed, Phase 1 implementation underway, Phase 2
  and 3 deferred per docs/design.md).
- Point readers at docs/design.md as the live spec, and add a layout
  map so a fresh agent knows where each concern lives.

No code touched; this is the last commit in the Phase 1 branch before
merge to main per head's review (msg #1775).
This commit is contained in:
mAi
2026-05-15 13:27:32 +02:00
parent 9466759aeb
commit 2df9e1b13f

View File

@@ -5,44 +5,33 @@
Data backbone for m's complete self-management — projects (digital + physical + strategic + life themes), tasks, lifecycle, milestones. Multiple interfaces consume it. No interface is canonical; each is a view.
**Memory group_id:** `projax`
**Live spec:** `docs/design.md` (PRD, schema, migration plan, deferred phases)
## Architecture principles
1. **Model first, interfaces second.** The data model is the asset; UIs are replaceable.
2. **Project Code is the lingua franca.** Every project gets a concise, human-readable code (TBD format) and that code surfaces in every interface, every notification, every task title.
3. **First-class non-code projects.** Greenhouse construction, household chores, career positioning, sport goals — same model as code projects.
4. **No CLI required.** m has explicitly opted out of CLI-first. Interfaces are visual / API / Otto-mediated.
5. **Subsumes existing scattered state.** mai.projects, Gitea issues, CalDAV tasks, mBrian topics, Dokploy services. Migration not greenfield isolation.
6. **Otto is a consumer, not an owner.** Otto-PWA renders projax data; otto coordinates work *based on* projax; otto does not *define* projax.
2. **First-class non-code projects.** Greenhouse construction, household chores, career positioning, sport goals — same model as code projects.
3. **No CLI required.** m has explicitly opted out of CLI-first. Interfaces are visual / API / Otto-mediated.
4. **Subsumes existing scattered state.** mai.projects (adapter view today), Gitea issues, CalDAV tasks, mBrian topics. Migration not greenfield isolation.
5. **Otto is a consumer, not an owner.** Otto-PWA renders projax data; otto coordinates work *based on* projax; otto does not *define* projax.
## Open design questions (Phase 1)
## Tech stack (Phase 1)
The inventor's first deliverable. Don't pre-decide:
- **Backend**: Go single binary. `pgx` for Postgres. `html/template` + HTMX (CDN), no JS build step. Static assets and migrations bundled with `embed`.
- **Database**: msupabase, schema `projax` (new). View `projax.items_unified` reads across `projax.*` + `mai.projects`. RLS off for v1 (single-user, Tailscale-only).
- **Hosting**: Dokploy on mlake, domain `projax.msbls.de`, Tailscale-only.
- **Tests**: `go test ./...` against `SUPABASE_DATABASE_URL` (skips when unset).
- **Storage**: own Postgres schema? SQLite? msupabase `projax` schema? Reuse mai schema?
- **Project Code generation**: shortcode pattern (3-5 char?), collision strategy, retroactive assignment to 30+ existing projects
- **Schema**: project, task, milestone, owner, stakeholder, lifecycle-state, type (code/physical/strategic/life), parent/child for sub-projects, tags, links
- **Lifecycle states**: idea → spec → active → paused → done → archived. Plus blocked-by, waiting-for-input, on-hold.
- **API shape**: REST? GraphQL? Direct DB? mai-MCP-style?
- **Interface integrations**:
- Otto-PWA (read + edit)
- Browser UI (full editor)
- Excalidraw view (visual roadmap, dependencies graph)
- CalDAV tasks (bidirectional sync? one-way mirror? read-only ingest?)
- Gitea issues (sync via webhook? read-only ingest?)
- mBrian topic-hubs (link/back-link integration)
- **Migration**: 28 active mai.projects + ~15 test rows + 4 archived/sleeping
- **Project Tracking gaps surfaced by otto inventory** (2026-05-15):
- mai.projects is verschmutzt with test rows
- projects.yaml symlink is dead
- no cross-project status view exists
- mBrian topic-hubs cover only ~8/30 projects
## Layout
## Tech stack
TBD by inventor. Constraints:
- m's preferred: Go for backends, single-binary deploys, SQLite or Postgres on msupabase, no build-step for frontends if avoidable
- Must work with existing m's infra (Tailscale-only network, Dokploy for hosting if web-side, mai/CLAUDE.md conventions)
```
cmd/projax/ main entrypoint (pool, migrate, serve)
db/ migrations (embedded) + runner + integration tests
store/ pgx-backed data access
web/ handlers, templates, static
deploy/dokploy.yaml reference manifest for projax.msbls.de
docs/design.md PRD — the source of truth for behaviour
```
## Branch strategy
@@ -51,23 +40,26 @@ TBD by inventor. Constraints:
- No `dev` branch initially (small project)
- `--no-ff` merges to main
## Worker preferences
## Status
- **First shift = inventor** (design pass): produce `docs/design.md` answering the open questions, propose Project Code format, sketch schema + lifecycle + interface contracts, plan migration from `mai.projects` + sibling sources.
- **Second shift = coder** (after m's go): bootstrap repo skeleton, schema migrations, minimal API + first interface (probably the simplest one — Otto-PWA read-view or browser CRUD).
- **Gated transitions**: inventor reports design-ready, m approves, head flips to coder. No auto-flip.
- Model: Sonnet for both shifts — structure-heavy work.
- **PRD landed** (`docs/design.md`, 2026-05-15) — schema, lifecycle, interface contracts settled.
- **Phase 1 underway**: schema + path trigger + adapter view + Go server + tree/detail/new/classify pages + Docker/Dokploy + README all on a feature branch.
- **Phase 2** (CalDAV + Gitea ingest) and **Phase 3** (Excalidraw / MCP / Otto-PWA) are scoped in `docs/design.md` but not started.
## Out of scope
When a phase-1 follow-up surfaces (auth, hiding mai.projects test rows, mBrian topic-hub auto-link, …), file it against `docs/design.md` §8 first, then split into commits.
## Out of scope (still)
- Multi-user
- Mobile-first / responsive (desktop browser + Otto-PWA cover)
- Public exposure
- Generic SaaS-product instincts
- CLI surface (m has explicitly opted out)
## Refs
- `docs/design.md` — live spec (this is the source of truth)
- `mai.projects` schema (msupabase) — primary current state (read-only adapted via `projax.items_unified`)
- mBrian conventions (topic-hub pattern) — relevant for non-code project tracking, deferred to Phase 3
- otto session 2026-05-15 — inventory of where project data lives today, justifying this project's existence
- `mai.projects` schema (msupabase) — primary current state
- mBrian conventions (topic-hub pattern) — relevant for non-code project tracking
- `~/.claude/CLAUDE.md` § Git Strategy, Channel Routing, Memory Protocol