Phase 0: Foundations

This phase is complete. Read the walkthrough for how it was built and what it teaches.

Ships

Repo scaffold, toolchain, protobuf pipeline, art pipeline, Art Batches 01 and 02

Lesson

Project structure, reproducible toolchains, code generation and image processing

Depends on

Nothing

• Write the foundational docs: README.md, AGENTS.md and BUILD.md.
• Owner Choose licenses: one for code (for example MIT or AGPL-3.0) and one for art and written content (for example CC BY-NC 4.0, or all rights reserved).
• Owner Confirm a ChatGPT plan with image generation is available for the art batches.
• Verify git push origin main reaches both GitHub and Codeberg and that both repositories are public.

• Add CLAUDE.md that points Claude Code sessions at AGENTS.md.
• Create the directory layout from AGENTS.md section 7, each top-level directory with a short README saying what belongs there.
• Add .gitignore covering Go build output, Godot .godot/ and export output, node_modules/ and dist/, Python .venv/ and caches, .env* (except .env.example), and OS cruft.
• Add .editorconfig and .gitattributes (LF line endings, images and other binaries marked binary).
• Add LICENSE files for the licenses chosen in 0.1 and fill in the license section of README.md.
• Add docs/decisions/0000-template.md and ADR 0001 recording the stack decisions already in the AGENTS.md decision log.

• Decision Pin toolchain versions (Go, Godot 4.x, Node LTS, Python, uv, buf, golangci-lint, gdtoolkit, GUT) to the latest stable releases and fill in the AGENTS.md toolchain table.
• Root Makefile with at least: help, doctor, setup, fmt, lint, test, check, server, client, proto, sync, art-intake. make help lists every target with a one-line description.
• make doctor checks every required tool and version and prints how to install anything missing (Homebrew on macOS, apt on Debian/Ubuntu).
• make setup installs project-local dependencies (Go modules, uv environments, Godot addons) and is safe to re-run.
• make check runs every format check, linter and test suite in the repo, and is exactly what CI runs.

• Create the Go module in server/ (github.com/dunamismax/lorehallow/server) with cmd/lorehallow-server/ and internal/.
• Configuration from flags and LOREHALLOW_* environment variables, with local-dev defaults, documented in server/README.md and .env.example.
• Structured logging with log/slog (text locally, JSON in production).
• HTTP listener with GET /healthz and GET /version (build version, git commit, protocol version).
• Graceful shutdown on SIGINT and SIGTERM with a timeout.
• Build version and commit injected with -ldflags.
• gofmt, go vet, golangci-lint, go test -race ./... and govulncheck wired into make lint and make test.
• First unit tests (configuration parsing, health handler).
• make server builds and runs the server on a documented local port.

• buf.yaml and buf.gen.yaml in proto/, package lorehallow.v1, buf lint enabled.
• First schema in proto/lorehallow/v1/: an Envelope with a oneof payload, Ping and Pong, and the PROTOCOL_VERSION convention documented in proto/README.md.
• Go code generation into server/internal/pb/ (committed, marked generated).
• Decision GDScript code generation: try godobuf on the pinned Godot 4 version first; if it can’t pass the round-trip tests below, write tools/protoc-gen-gdscript (a Go protoc plugin) for the proto3 subset Lorehallow uses.
• GDScript code generation into client/net/pb/ (committed, marked generated).
• Golden vectors: a Go program writes encoded messages and JSON descriptions to proto/testdata/; Go and GDScript tests decode and re-encode them and compare bytes.
• make proto regenerates everything; make check fails when generated code is stale or buf breaking reports an unplanned breaking change against main.

• Create the Godot 4 project in client/ with the project name, a placeholder icon and the folder layout from AGENTS.md.
• Rendering settings: base viewport 640×360, stretch mode viewport, integer scaling, default texture filter Nearest, no mipmaps, 2D pixel snapping.
• Pixel-art import preset (filter off, mipmaps off, lossless) as the project default.
• Main scene with a placeholder title screen showing the build version.
• Autoload skeletons: Config, Log and Net (empty for now).
• GUT installed in addons/ with one passing test; make test runs GUT headless.
• gdtoolkit through uv; make fmt and make lint cover client/, excluding generated code and addons.
• Static typing enforced: the project warns on untyped declarations.
• make client launches the client (Godot found through a GODOT variable with sensible macOS and Linux defaults).

• tools/art/ Python project managed by uv (Pillow, numpy, PyYAML, pytest, ruff).
• Batch manifest schema (art/batches/<batch>/manifest.yaml): per asset id, target path, kind (tile, tileset, sprite, sheet, ui, web), logical size, grid, frame layout and count, key color and palette.
• Inbox mapping file (art/inbox/<batch>/map.yaml) linking each raw file to a manifest asset id.
• Grid detection: find the real pixel block size and offset of generated “pixel art” and downsample to the logical size by sampling each block (center or mode).
• Background removal: key color and near-key fringe become transparent.
• Palette quantization: nearest palette color in a perceptual color space, no dithering, with a report of pixels changed.
• Sheet slicing: split into frames and check frame count, frame size and foot-baseline alignment across frames, failing with a clear message when they don’t line up.
• Output: write to art/processed/ with project names, plus a sidecar .json for sheets (frames, order, pivot, source file, batch).
• Intake report (art/batches/<batch>/report.md): status per asset (accepted, fixed, regenerate), a 4x preview contact sheet, and corrected prompts for anything to regenerate.
• Per-batch fix scripts are supported so small cleanups are reproducible when intake re-runs.
• make sync mirrors art/processed/ into client/assets/art/ and web/assets/art/.
• Tests with synthetic fixtures (upscaled, jittered, off-grid, off-palette and misaligned images with known expected output).
• make art-intake BATCH=<id> runs the whole pipeline for one batch, and re-running it gives the same result.

• Draft the locked palette (about 32 colors for warm storybook fantasy: moss and leaf greens, lantern ambers, stone greys, dusk blues, earth browns, skin tones, a dark outline color and a near-white) as art/style/palette.hex, a swatch PNG and a .gpl palette file.
• Owner Approve the palette or ask for changes.
• Write art/style/STYLE.md: grid, scale, perspective, light, outlines, shading steps, character proportions, animation rules, and do and don’t examples.
• Write Batch 01 prompts and manifest: a style reference sheet, one character concept (32×48) and a grass, dirt and stone tileset (32×32, including transitions).
• Owner Generate Batch 01 in ChatGPT and drop the files unchanged into art/inbox/batch-01/.
• Run intake on Batch 01 and iterate with corrected prompts until every asset is accepted.
• Save the accepted reference sheet as art/style/reference.png for every later prompt to attach.
• Dev scene client/scenes/dev/art_test.tscn renders the processed tiles and character at 1x to 4x with no blur, seams or off-palette pixels.

• Write Batch 02 prompts and manifest: logo wordmark, square emblem (favicon and app icon), hero key-art scene, 2 or 3 parallax background layers, a character lineup, section icons, a sheet of 20 progress-map landmarks (one per phase, from a starting campfire to a castle for v1.0), devlog header art, an Open Graph card background (1200×630) and 404 art.
• Owner Generate Batch 02 and drop it into art/inbox/batch-02/.
• Run intake on Batch 02 (same palette, larger logical sizes allowed for web art) and iterate until accepted.
• Export the favicon set (16, 32, 180, 192 and 512 px) and the client app icon from the emblem.
• Owner Approve the logo and hero art as the public face of the project.

• GitHub Actions workflow runs make check on every push to main (Linux), caching Go and uv.
• Godot headless tests run in CI with the pinned Godot version.
• CI status badge in README.md.
• Document in AGENTS.md that CI runs on GitHub and Codeberg is a mirror.

• docs/walkthroughs/phase-00-foundations.md: repository tour, the command runner, how protobuf codegen works on both sides, and how the art pipeline turns generated images into true pixel art.
• Devlog draft for Phase 0 in docs/devlog-drafts/.

• Decision Hand-drawn pixel art by agents is the default; image generation only for large painted web images.
• art/src/ sources and make art-draw BATCH=<id>: .pxl.yaml pixel grids (legend by palette name, one grid per frame) and .py draw scripts, rendered deterministically into art/processed/ via a source: manifest field, with intake’s checks (size, palette, frames, baseline, pivot) and a 4x and 8x contact sheet per batch.
• Drawing helpers in tools/art for draw scripts: palette by name, seeded random, pixel, line, rect and ellipse, 1 px outline, mirror, wrap-around drawing for seamless tiles, stamping .pxl parts, and compositing finished assets.
• make check fails when a processed file no longer matches its hand-drawn source, and when a source uses an unknown color name or the wrong size.
• Redraw the base terrain tileset (16 tiles): every tile seamless with itself and its variants, low contrast, checked repeated 3×3.
• Redraw the grass-to-dirt and grass-to-flagstone transition sets so every edge and center tile self-tiles and the 3×3 patch closes.
• Redraw the concept hero (32×48, feet on row 45, 28 to 32 px tall to the top of the head).
• Draw the props the reference scene needs (a tree, a mossy rock, a lantern post, a cottage corner) and rebuild the style reference vignette (240×160) as a composite of the hand-drawn tiles, hero and props; art/style/reference.png follows.
• Redraw the logo wordmark (192×64), the 32 and 16 px emblems, the 16 section icons and the 20 progress landmarks, then re-export the favicons and app icon.
• Redraw the character lineup with five hand-drawn adventurers at the in-game 32×48 scale.
• Keep the generated hero scene, parallax layers, devlog header, social card and 404 art; check they still sit well next to the hand-drawn art, and note any that should be regenerated.
• Update the Phase 0 walkthrough and devlog draft to describe hand-drawn art.

• On a fresh clone, make doctor && make setup && make check passes on macOS, and make check passes in CI on Linux.
• make server runs the server and make client launches the client, which shows the title screen and build version.
• Changing a .proto file and running make proto updates Go and GDScript code, and golden round-trip tests pass on both sides.
• Batch 01 tiles and the character render pixel-perfect in Godot at every integer scale.
• Batch 02 assets are processed and ready in art/processed/web/.
• The Phase 0 walkthrough exists and every ADR item in this phase has its ADR.