|
| 1 | +# Design: starter stacks |
| 2 | + |
| 3 | +Date: 2026-09-24. Status: approved in conversation, awaiting spec review. |
| 4 | + |
| 5 | +## Why |
| 6 | + |
| 7 | +Sub-project A from the site brainstorm. The site now has a page per entry (sub-project B, |
| 8 | +shipped 2026-09-24), but a visitor still has to assemble a game's assets themselves: |
| 9 | +search for characters, then music, then a font, then work out what the whole set owes. |
| 10 | +People ask AI assistants exactly that question ("free assets for a 2D platformer I can |
| 11 | +sell"), and the catalog already has five tested answers: the task tests A to E recorded |
| 12 | +in `docs/review-ledger.md`, each walked end to end against the catalog. |
| 13 | + |
| 14 | +Goals, from the maintainer: be useful to visitors, reach more people, look credible. |
| 15 | + |
| 16 | +## What success looks like |
| 17 | + |
| 18 | +- A solo developer starting a game of one of five kinds opens one page and gets one |
| 19 | + pick per need, why that pick, and a single list of what the whole set owes. |
| 20 | +- Every licence fact on a stack page comes from the entries at build time, so a stack |
| 21 | + never disagrees with an entry and a re-verified entry updates every stack using it. |
| 22 | +- What the catalog does not cover for a task is stated on the page, not hidden. |
| 23 | + |
| 24 | +## Decisions taken |
| 25 | + |
| 26 | +| Question | Decision | |
| 27 | +| --- | --- | |
| 28 | +| Audience | Solo developers starting out | |
| 29 | +| First release | The five task tests: 3D low-poly arena, 2D top-down pixel, first-person destruction, 2D pixel platformer, mobile puzzle | |
| 30 | +| Engine | Engine-neutral, with format friction noted per pick; engine add-ons only where the task named an engine (the 3D arena, Godot) | |
| 31 | +| Authoring | One markdown file per stack with a strict pick-line format | |
| 32 | +| Combined credits | A "Copy all credits" button alongside per-pick Copy buttons | |
| 33 | +| Deprecated pick | Fails validation and the build | |
| 34 | + |
| 35 | +## The stack file |
| 36 | + |
| 37 | +Each stack is `stacks/<id>.md`. Frontmatter holds flat fields only, which the existing |
| 38 | +parser reads: |
| 39 | + |
| 40 | +- `id`: kebab-case, unique among stacks. |
| 41 | +- `title`: the page title, a task phrased as an action ("Make a 2D pixel platformer"). |
| 42 | +- `task`: one sentence naming the game and the intent to sell it. |
| 43 | +- `walked`: the date the stack was assembled against the catalog. It is deliberately not |
| 44 | + called `verified`: walking a stack re-verifies no licence, and moves no entry's |
| 45 | + `verified` date. |
| 46 | + |
| 47 | +The body: |
| 48 | + |
| 49 | +- A lead paragraph before the first `##`: who the stack is for and what it assumes |
| 50 | + (engine, style, perspective). |
| 51 | +- `##` sections, in this order, each optional: `Art`, `Audio`, `Fonts`, `Tools`, `Gaps`. |
| 52 | + Any other `##` heading is an error. |
| 53 | +- In Art, Audio, Fonts and Tools, every bullet is a pick line: the need in bold followed |
| 54 | + by a colon, then a markdown link to the picked entry's file, then a full stop and one |
| 55 | + or more sentences on why this pick and any friction (format, filtering, perspective). |
| 56 | + The first link in the line is the pick. Later links in the same line are ordinary |
| 57 | + links and do not count as picks. |
| 58 | +- `Gaps` holds plain bullets: what the catalog does not yet cover for this task, taken |
| 59 | + from the task test's recorded leave points. |
| 60 | + |
| 61 | +Rules on picks: |
| 62 | + |
| 63 | +- The pick must link an existing entry whose status is not `deprecated`. |
| 64 | +- A `needs-review` pick is allowed and is flagged on the page. |
| 65 | +- One pick per need. Where two sources honestly split a need, it becomes two needs |
| 66 | + ("Music, no credit" and "Music, with credit"). |
| 67 | +- A why sentence must not state a licence. It is checked against the licence ids in |
| 68 | + `site/license-vocabulary.json` and `site/spdx-allowed.json` (whole words, case |
| 69 | + sensitive, excluding ids that are ordinary lower-case words such as `custom`, |
| 70 | + `unknown` and `varies`) and the phrases "Creative Commons", "public domain" and |
| 71 | + "royalty-free" (any case). Licence facts come from the entry. |
| 72 | + |
| 73 | +## The stack page |
| 74 | + |
| 75 | +Built at `/stack/<id>/`, from the stack file and the picked entries. |
| 76 | + |
| 77 | +- Breadcrumb (Catalog / Stacks / title), the title as the one `h1`, the task sentence |
| 78 | + and the lead. |
| 79 | +- **What this stack owes**, computed from the picks: |
| 80 | + - Credits to ship: each pick with `attribution_required: true`, showing its credit |
| 81 | + line with a Copy button, or "no canned credit line: see the entry" where it has |
| 82 | + none. A "Copy all credits" button copies every canned line as one block, one per |
| 83 | + line. |
| 84 | + - No credit needed: the count and names of picks with `attribution_required: false`. |
| 85 | + - Check each file: picks with `commercial: varies`, with "Some files qualify, some do |
| 86 | + not." |
| 87 | + - Open questions: `needs-review` picks, each with its entry's status note. |
| 88 | + - Unclear credit: picks whose `attribution_required` is neither true nor false. |
| 89 | +- Sections: one row per pick with the need, the entry name linked to its entry page, |
| 90 | + the entry's licence and commercial label, the why sentence, and the entry's verified |
| 91 | + age with the same aging cue as the homepage cards. |
| 92 | +- Gaps, when the file has them. |
| 93 | +- A closing line: "Stack walked <walked>. Each licence is only as current as its entry's |
| 94 | + verified date." |
| 95 | +- Canonical URL, description, social tags and JSON-LD (`ItemList` of the picked entry |
| 96 | + pages). The page works without JavaScript; the only script is the Copy buttons, and |
| 97 | + only when the page has at least one canned credit line. |
| 98 | + |
| 99 | +Links in: |
| 100 | + |
| 101 | +- The homepage gets a "Starter stacks" section above "Safe starting points": one line |
| 102 | + per stack with its title and task. |
| 103 | +- Each picked entry's page lists "Used in" with links to its stacks. |
| 104 | +- `sitemap.xml` lists each stack page. |
| 105 | +- `llms.txt` gets a stacks section at the top; `llms-full.txt` carries each stack's |
| 106 | + picks with their needs, entry page URLs and the owed list. |
| 107 | + |
| 108 | +## Build and validation |
| 109 | + |
| 110 | +- `site/lib/stacks.mjs`, pure functions: |
| 111 | + - `parseStack(md, file)`: frontmatter, lead, sections, picks and gaps; throws |
| 112 | + `StackError` naming the file and line on any rule above. |
| 113 | + - `owes(picks, entriesById)`: `{ credits, noCredit, perFile, openQuestions, unclear }`. |
| 114 | + - `stackPageHtml(...)`: the page. |
| 115 | +- `site/build.mjs` loads `stacks/*.md` after the entries, resolves each pick through the |
| 116 | + existing link resolver, writes `dist/stack/<id>/index.html`, and runs every stack page |
| 117 | + through the existing page checks. It exits 1 on any `StackError`, `LinkError` or page |
| 118 | + check error. Stack pick text is rendered with the existing renderer. |
| 119 | +- `site/validate.mjs` gains V15, which applies `parseStack` and the pick rules to every |
| 120 | + stack file, so `node site/validate.mjs` alone reports stack errors. Build and |
| 121 | + validator share `site/lib/stacks.mjs`, so the rules cannot drift. |
| 122 | +- A deprecated or missing pick fails both; the fix is to repick or move the need to |
| 123 | + Gaps. |
| 124 | +- A duplicate stack `id` fails both. |
| 125 | + |
| 126 | +## Content |
| 127 | + |
| 128 | +- Five stacks, one per task test, picks drawn from what that walk found: |
| 129 | + - `3d-low-poly-arena-godot` (task A) |
| 130 | + - `2d-top-down-pixel` (task B) |
| 131 | + - `first-person-destruction` (task C) |
| 132 | + - `2d-pixel-platformer` (task D) |
| 133 | + - `mobile-puzzle` (task E) |
| 134 | +- Every pick is read from its entry file on the day of writing; no source is re-fetched |
| 135 | + for the stack and no entry changes. |
| 136 | +- Why sentences state only facts the entry records (formats, counts, perspective, |
| 137 | + friction). Gaps restate the ledger's leave points and name the ledger date. |
| 138 | +- Repo style: no emojis, no em dashes, no marketing voice. Prefer removing a claim over |
| 139 | + softening it. |
| 140 | + |
| 141 | +## Testing |
| 142 | + |
| 143 | +- `site/lib/lib.test.mjs`: `parseStack` on a good file and on each malformed shape |
| 144 | + (unknown section, pick line without a link, pick line without the bold need, licence |
| 145 | + name in a why sentence) with file and line; `owes` for every bucket, including a |
| 146 | + required credit with no canned line; `stackPageHtml` for escaping of names and credit |
| 147 | + lines, one `h1`, canonical, Copy script present only with a canned credit line, and |
| 148 | + the Copy all block joining lines in pick order. |
| 149 | +- `site/checks.test.mjs`: V15 pass and fail cases per rule, including a deprecated and a |
| 150 | + missing pick and a duplicate id. |
| 151 | +- Gate proof: point one pick at a deprecated entry; build and validator both exit 1 |
| 152 | + naming the stack file and line; revert by the inverse edit. |
| 153 | +- Browser: both Copy buttons copy; the page works without JavaScript; no horizontal |
| 154 | + scroll at 375px; no text below AA contrast in light and dark; homepage section and |
| 155 | + "Used in" links resolve; zero console errors. |
| 156 | +- Live after deploy: five stack pages return 200; `sitemap.xml` has 323 URLs; the |
| 157 | + stacks appear in `llms.txt`. |
| 158 | + |
| 159 | +## Risks |
| 160 | + |
| 161 | +- **A stack reads as an endorsement of fitness.** The page states the task and the |
| 162 | + assumptions, and the closing line ties every licence to its entry's date. |
| 163 | +- **Picks go stale when an entry changes.** Licence facts are read at build time; only |
| 164 | + the why sentence can drift, and it is limited to facts the entry records. |
| 165 | +- **Copy all credits used for assets not shipped.** The button sits under the list |
| 166 | + that names each asset beside its credit line, so a reader sees what the block holds |
| 167 | + and can drop lines for assets they do not ship. |
| 168 | + |
| 169 | +## Out of scope |
| 170 | + |
| 171 | +- Stacks for further engines, user-submitted stacks, and stacks beyond these five. |
| 172 | +- Pages for category READMEs and `docs/` guides. |
| 173 | +- Folding `docs/godot-budget-stack.md` into the stack format. |
0 commit comments