3.8 KiB
Decisions
Append-only. Never edit or delete an entry — supersede it with a new one that links back.
One entry per decision a future maintainer would otherwise have to reverse-engineer.
No index: grep -n '^## ' docs/DECISIONS.md lists every entry (date, title, line number).
2026-10-23 — Mockups are committed and served, not throwaway
Status: accepted
Context: The agent-repo playbook keeps mockups gitignored in design/mockups/, never wired into the app.
Spec 001 asks for 7 design-direction mockups that run in the Docker image for the maintainer to compare.
Decision: (maintainer decision) Mockups live in src/mockups/NN-slug/, are committed, served by the
Bun server and covered by route smoke tests. Mockup agents edit only their own folder.
Alternatives: Gitignored design/mockups/ (can't ship in the image or be reviewed from the remote).
Consequences: Mockup code is in the bundle and the history; when a direction is chosen, the unused
mockups need an explicit removal decision (docs/TODO.md).
2026-10-23 — Production bundle runs from dist/
Status: accepted
Context: With Bun 1.3.14, a --production bundle of HTML imports resolves its assets relative to the
current working directory; bun dist/server.js from the repo root throws "Bundled file … not found".
Decision: bun run start is cd dist && bun server.js; the Docker runtime stage uses WORKDIR /app/dist.
Alternatives: Not recorded (e.g. --asset-naming/naming options were not explored).
Consequences: Any new run script or deploy target must set the cwd to dist/.
2026-10-23 — Bun only, self-contained assets
Status: accepted Context: Spec 001 constraints. Decision: Bun's own server, bundler and test runner with HTML imports; no Vite/Next. Fonts and three.js bundled from npm, no CDN. YouTube as link cards, not embeds. three.js only in the 3D mockups (06, 07). Alternatives: Not recorded. Consequences: The image works offline apart from outbound links.
2026-10-23 — Placeholder lyrics, unverified facts marked
Status: accepted
Context: Lyrics recalled from memory risk inaccuracy, and their copyright question is open.
Decision: Sample data uses clearly marked placeholder lyric lines in the real data shape; any fact,
story time or Odyssey reference not confirmed carries // TODO(verify).
Alternatives: Real lyrics (deferred by the maintainer).
Consequences: Nothing in src/data/sample.ts may be presented as fact-checked.
2026-10-23 — Adopt AGENTS.md as single source of truth
Status: accepted
Context: Agents had no durable project context and no consistent workflow between sessions.
Decision: AGENTS.md is canonical; CLAUDE.md/GEMINI.md are pointers. Specs are permanent in
docs/specs/. Plans live in docs/plans/ only while work is in progress and are removed before the
merge request. Both override the superpowers default paths.
Alternatives: Per-tool rule files (drift, synchronisation debt); no rules file (agents re-explore
the repo every session — measurably slower and more tokens).
Consequences: Rule changes happen in one file; pointer files must stay thin. Plans are working
artefacts: kept after merge they go stale and contradict the code, so the spec is the record.
2026-10-30 — three.js allowed in mockup 13
Decision: mockup 13 (Curtain call) may use three.js, like 06 and 07. It mocks the frieze → 3D sea → frieze → cave transition, which needs the 3D sea. three.js is already a dependency; nothing new is added.
2026-10-30 — three.js allowed in mockup 14
Decision: mockup 14 (Voyage with side panel) may use three.js; it converges 13's 3D flow with a persistent side panel. No new dependency.
2026-10-30 — three.js allowed in mockup 15
Decision: mockup 15 (Voyage, look 2) may use three.js; it iterates on 14. No new dependency.