Skip to content

Commit 710d9a4

Browse files
TMHSDigitalclaude
andcommitted
docs: starter stacks design
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Wc67NX9MM964uaVGn4bpZJ
1 parent 86db48a commit 710d9a4

1 file changed

Lines changed: 173 additions & 0 deletions

File tree

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
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

Comments
 (0)