89 lines
7.1 KiB
Markdown
89 lines
7.1 KiB
Markdown
# Implementation plan — explicit Codex execution gates
|
|
|
|
## Working rules
|
|
Complete milestones sequentially. Finish one and validate it before moving on. Use `docs/PROGRESS.md` as execution log. Do not implement speculative game systems. In the event of a spec conflict, prioritize: `AGENTS.md`, then this plan, then narrower contracts. Document deviations instead of silently redefining requirements. Prefer small components, one implementation per responsibility and clear error states.
|
|
|
|
## M0 — infrastructure & bootable application
|
|
**Objective:** real running web + API + database through Docker Compose, before domain features.
|
|
|
|
Tasks:
|
|
1. Initialize npm workspace root with `apps/web`, `apps/server`, `packages/genetics`, `packages/renderer`, `packages/rules`, `packages/shared`. Configure shared TS config, ESLint if straightforward, testing via Vitest and root scripts `dev`, `build`, `typecheck`, `test`, `db:migrate`, `db:seed`.
|
|
2. Scaffold React/Vite + router + Tailwind, install shadcn/ui prerequisites only (add actual components as needed), Zustand and TanStack Query; a proper illustrated shell/header and top nav. Implement `/lab`, `/breed`, `/gallery`, `/about`; all pages may show clearly labeled empty states in M0.
|
|
3. Scaffold Fastify TypeScript API, Zod, Drizzle PostgreSQL connection, `/health` returning 200 if DB query succeeds. Implement uniform API errors.
|
|
4. Create DB schema and initial migration consistent with `docs/API_AND_DATA.md`, demo player + `velvetleaf` catalog seed; startup/bootstrap behavior must be repeatable. Seed operation idempotent.
|
|
5. Create production-quality Dockerfiles, nginx SPA/proxy config, .dockerignore. Make Compose from root work with provided .env (host 8155, public origin http://localhost).
|
|
6. Add simple README scripts, screenshots not mandatory yet. No credentials in Git.
|
|
|
|
Gate:
|
|
- `docker compose config` works.
|
|
- `docker compose up --build -d` produces healthy API/DB and reachable UI at `http://localhost:8155`.
|
|
- `curl -fsS http://localhost:8155/health` returns HTTP 200 JSON.
|
|
- Mobile page renders without horizontal overflow.
|
|
- `npm run typecheck`, `npm run test`, `npm run build` pass (root tooling installed and lockfile committed).
|
|
- Database survives `docker compose down` / `up` and cannot be reached via published Compose ports.
|
|
|
|
## M1 — genetics domain (pure package)
|
|
Tasks:
|
|
1. Create versioned catalogs/types, Zod validators, `validateGenome`, `resolvePhenotype`, `canBreed`, `breed`, `classifyRarity` as specified.
|
|
2. Implement a deterministic seeded PRNG with documented integer rules and deterministic cross-run results. Do not mix RNG into renderer.
|
|
3. Allele inheritance: 50/50 from each parent independently by locus; dominance policy per locus; named mutation logging; explicit exceptions for invalid/incompatible pairs.
|
|
4. Add proper unit tests on example cross, mutation boundaries, deterministic replay, phenotypes and rarity policy.
|
|
5. Implement `/api/v1/catalog/species` and `/api/v1/phenotype/resolve` with shared DTOs.
|
|
|
|
Gate:
|
|
- Example cross with mutations disabled yields 1:2:1 genotypes over 10k runs within ±2 percentage points.
|
|
- Same seed → exact same result, across calls.
|
|
- Cross-species breeding blocked unless compatibility is explicitly defined.
|
|
- Untrusted client alleles rejected by server.
|
|
- `npm run test`, `typecheck`, `build` pass.
|
|
|
|
## M2 — illustrated vector rendering
|
|
Tasks:
|
|
1. Create at least **original** handcrafted SVG primitive sources (see GRAPHICS_SPEC). Strong visual quality; use multiple paths, veins/shading, artistically composed plant silhouette.
|
|
2. Implement species-specific plant grammar and pure geometry layout with visualSeed, phenotype, 4 stages and stable IDs.
|
|
3. Render an isolated viewBox 512 SVG. Apply color palettes, silhouette switching, variegation/marbling and golden veins mutation. No unsafe injected XML.
|
|
4. Add export SVG and PNG with transparent or warm background selection, ensure rendered result matches preview.
|
|
5. Add gallery proof view showing at least 12 systematic variations and 100-seed smoke demo; perform browser visual QA and optimize if needed.
|
|
|
|
Gate:
|
|
- 3 leaf shapes, 2 pigments, 2 patterns visibly distinct.
|
|
- Same args produce same SVG geometry; same genotype with different visualSeed varies only cosmetically.
|
|
- 64px icon and 512px hero remain legible; no obvious clipping.
|
|
- SVG and PNG exports open and visually match.
|
|
- 100 plants render without noticeable frozen UI on typical desktop.
|
|
- Build/tests/typecheck pass.
|
|
|
|
## M3 — editor and persistent breeding
|
|
Tasks:
|
|
1. Build polished Lab: live plant preview, species selector, diploid allele editor, stage selector, visual seed control and mutation toggles (manual preview only, not falsely claimed as bred mutations), genotype/phenotype and score explanations.
|
|
2. Add server-side `POST /api/v1/plants`, `GET /api/v1/plants/:id`, pagination GET. Persist canonical genomes, seeds, lineage fields. Seed demo parents.
|
|
3. Implement server authoritative `POST /api/v1/breeding` idempotent and transactional, plus history endpoint; create real child instance with securely selected event seed and recorded parent IDs.
|
|
4. Implement Breeding Lab screen: parent selection, validation, cross, result card and lineage navigation. Show accurate example probabilities only for single-gene preview.
|
|
5. Mutation logic and rarity scores computed once at child creation and persisted. Data migration scripts tested on clean DB.
|
|
|
|
Gate:
|
|
- Editing allele changes expected visible traits instantly.
|
|
- Breed yields child with exactly two persisted parents and generation +1.
|
|
- Retry same idempotencyKey returns same child, no duplicates.
|
|
- Cross incompatible species refuses with clear message.
|
|
- Browser reload persists generated plants.
|
|
- No server error leaks secrets. Tests/build/typecheck pass.
|
|
|
|
## M4 — collection gallery and hardening
|
|
Tasks:
|
|
1. Implement `/gallery` cards with filters, sorting and pagination, details inspector, lineage ancestry links and export JSON/SVG/PNG.
|
|
2. Create **100 deterministic varied demo plants** using seed script. Make seed idempotent so running twice does not duplicate.
|
|
3. Add helpful empty/loading/error states, toast/action confirmation, responsive layout and focus handling, reduced motion.
|
|
4. Polish botanical art direction and cards, ensure readability at 64px; inspect screenshots for desktop + mobile and fix visual issues.
|
|
5. Document API via concise examples, deployment constraints, future idle-game roadmap; verify no public auth claims or security oversell.
|
|
|
|
Gate:
|
|
- 100 plant gallery searchable/filterable without excessive UI lag.
|
|
- Exported SVG, PNG and JSON valid; opens without external resources.
|
|
- Lineage from bred child to parents navigable.
|
|
- 360px and 1440px layouts verified.
|
|
- `docker compose up --build -d`, health, tests, typecheck, build pass.
|
|
- Project ready for further iteration, **not** publicly launchable until auth/ownership controls added.
|
|
|
|
## Scope of next phase (do not code yet)
|
|
M5+ greenhouse economy (pots, seeds, currencies), offline time progression via event timestamps, upgrades and automation, seed shop, collection achievements, research, player accounts, secure multiplayer/trading. Should be planned after Plant Lab proof is accepted, not smuggled into MVP.
|