docs(spec): content track — demand-driven, bounded by the slice
Content (lore, economy, items, quests, map) was untracked and unbounded. Bound it: a second roadmap (content/roadmap.md) with Spine / Bill of Materials / Backlog, demand-driven by the milestone that consumes it. - Vertical slice = one town + one dungeon (adopt + deepen Greywater). - Ghaul the Yoke is the ledger chain's patron, so the quest chain and the cosmology are one object, not two. - Economy splits per §18: the loop is code (M8), the numbers are content. Currency = 1g/100s/10,000c, copper as the stored atom; lands before M7. - Build tool needs `item` + `quest` namespaces; locations already exist. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
214
docs/superpowers/specs/2026-07-12-content-track-design.md
Normal file
214
docs/superpowers/specs/2026-07-12-content-track-design.md
Normal file
@@ -0,0 +1,214 @@
|
||||
# Content track — design
|
||||
|
||||
**Date:** 2026-07-12
|
||||
**Status:** approved (design); implementation = a docs restructure + one code/content item (currency)
|
||||
|
||||
Folds the authored content of the game — lore, economy, items, quests, the map —
|
||||
into a tracked, bounded track alongside the systems roadmap, so the authoring
|
||||
work is countable rather than open-ended.
|
||||
|
||||
---
|
||||
|
||||
## Problem
|
||||
|
||||
`docs/roadmap.md` sequences **systems** (M0–M9). Content appears in it only
|
||||
implicitly — "item seed-data", "the quest model", "shop economy" — never as work
|
||||
with a size. `content/lore/canon-roadmap.md` tracks **canon** but is thin: an
|
||||
"Authored" list and a three-bullet "Pending".
|
||||
|
||||
So the content needed for a finished game — lore, an economy, every weapon,
|
||||
armour piece, consumable and trinket, quests, the map — is untracked and
|
||||
unbounded. It *looks* infinite, because nothing bounds it. That is the actual
|
||||
problem to solve: not "write more content", but "make the content finite".
|
||||
|
||||
## Approach
|
||||
|
||||
**Demand-driven content, gated by the milestone that consumes it.** Content is
|
||||
not authored to completeness; it is authored to the requirements of the next
|
||||
system milestone. The cure for overwhelm is not a longer list — it is a list
|
||||
with an end.
|
||||
|
||||
Two roadmaps, cross-linked, with clear ownership. Rejected alternatives:
|
||||
|
||||
- **One roadmap** (fold content into `docs/roadmap.md`) — the roadmap becomes
|
||||
huge, and content that serves no milestone (pure lore) has no home.
|
||||
- **Content-first** (author the world broadly, then build systems against it) —
|
||||
authors content no system has yet demanded; the volume is the problem.
|
||||
- **Content-type tracks** (separate lanes for lore / items / quests / map) —
|
||||
mirrors how the work *feels*, and is the structure most likely to read as four
|
||||
infinite parallel lists.
|
||||
|
||||
## The slice
|
||||
|
||||
The demand comes from a **vertical slice: one town + one dungeon.** The smallest
|
||||
thing that is a *game*. Every system (creation, combat, dialogue, inventory,
|
||||
shop, quest log, map) is exercised exactly once, against real content.
|
||||
|
||||
Breadth afterwards is **repetition of a proven shape**, not invention. Adding a
|
||||
second town becomes a known quantity of work against a known template. That is
|
||||
what ends the overwhelm permanently — not this slice, but what the slice teaches
|
||||
about the cost of the next one.
|
||||
|
||||
Rejected: **one region** (3–4× the authoring, before the shape is proven) and
|
||||
**systems-first with placeholder content** (tunes an economy with fake items,
|
||||
tests dialogue with fake NPCs; every system pays a second pass when real content
|
||||
lands).
|
||||
|
||||
---
|
||||
|
||||
## 1. Doc structure
|
||||
|
||||
| Doc | Owns |
|
||||
|---|---|
|
||||
| `docs/roadmap.md` | **Systems.** M0–M9, unchanged in shape. |
|
||||
| `content/roadmap.md` | **Content.** Spine · Bill of Materials · Backlog. |
|
||||
|
||||
- `docs/roadmap.md` gains one line per milestone M4–M9: **"Content it consumes →"**,
|
||||
pointing into the content roadmap's BOM.
|
||||
- `content/lore/canon-roadmap.md` **moves to `content/roadmap.md`**, leaving a
|
||||
pointer behind. The move is load-bearing: an items-and-prices table does not
|
||||
belong under `lore/`, and the file stops being only about canon.
|
||||
|
||||
The content roadmap has exactly three sections, and **only one of them is ever
|
||||
the work**:
|
||||
|
||||
1. **Spine** — the slice's world. Authored once; gates everything downstream.
|
||||
2. **Bill of Materials** — a countable checklist, per milestone, of what that
|
||||
milestone consumes. Numbers, not vibes.
|
||||
3. **Backlog** — everything the slice does not need. Named so it is not lost;
|
||||
parked so it is not looming.
|
||||
|
||||
### The rule
|
||||
|
||||
> **Never author anything that is not in the Bill of Materials.**
|
||||
|
||||
An idea that arrives goes to the Backlog, and is then no longer carried. The
|
||||
Backlog is not a debt. It is where ideas go to be safe.
|
||||
|
||||
---
|
||||
|
||||
## 2. The Spine
|
||||
|
||||
Greywater Docks and one dungeon — the cosmology (`content/lore/cosmology.md`)
|
||||
touching ground for the first time.
|
||||
|
||||
- **The town** — **Greywater Docks.** A rot-black wharf where the river meets
|
||||
the sea trade; everyone owes someone. **~6 NPCs:** Fenn (promoted from M2 test
|
||||
fixture to real NPC), the harbourmaster, a fence, an innkeeper, a dock rough,
|
||||
one more.
|
||||
- **The chain** — **"The Missing Ledger,"** extended from the existing hook.
|
||||
Town → road → dungeon → back. Four objectives.
|
||||
- **The turn** — the debt Fenn cannot cover is a **blood** debt. The
|
||||
harbourmaster is named in the ledger because he is the one *collecting*. The
|
||||
dungeon is the harvest site.
|
||||
- **The patron** — **Ghaul the Yoke.** He is already, by name, the king of debt
|
||||
and bondage; a ledger of what men owe is his liturgy. This makes the quest
|
||||
chain and the cosmology **the same object** rather than two things bolted
|
||||
together, and gives `rule.blood-price` its first concrete instance.
|
||||
- **The dungeon** — the harvest site. One enemy family (the yoked) + a boss.
|
||||
|
||||
**Adopting Greywater, not replacing it.** Fenn is the NPC the aliveness question
|
||||
was actually answered with (M2, live-proven): frightened, aggrieved, covering it
|
||||
with irritation. The ledger hook already has teeth. The slice's job is to make
|
||||
Greywater *deep*, not to make it *new*.
|
||||
|
||||
---
|
||||
|
||||
## 3. Bill of Materials
|
||||
|
||||
Countable. This is the anti-overwhelm device.
|
||||
|
||||
| Milestone | Content it consumes | Count |
|
||||
|---|---|---|
|
||||
| **M4** creation | Origins, calling blurbs, the Bloodsworn's patron choice | ~4 |
|
||||
| **M5** combat | 1 enemy family (4 units) + boss; abilities for the 3 POC classes | ~14 |
|
||||
| **M6** dialogue | 6 NPCs — persona + `knowledge[]` + gated topics (§6) | ~6 |
|
||||
| **M7** inventory | 6 weapons, 4 armour, 3 consumables, **1 cursed item** (+STR / −LCK — §7 says day-one) | ~14 |
|
||||
| **M8** world | 3 map locations + the road; shop stock + the **price table in copper**; the quest chain | ~8 |
|
||||
| **M9** flavour | Authored fallback per AI surface (§13); shrine + Luck-drift events; humiliation seeds | ~10 |
|
||||
|
||||
**≈56 discrete authored pieces for a complete, playable game.** An estimate, and
|
||||
likely optimistic — but an estimate with an end, which is the entire point.
|
||||
|
||||
Explicitly **not** in the slice: rings, amulets, trinkets. A second town. The
|
||||
other six kings and their cults. All parked in the Backlog.
|
||||
|
||||
---
|
||||
|
||||
## 4. Economy — two systems (§18)
|
||||
|
||||
The economy is not one thing. Per charter §18 ("when adding a system, state which
|
||||
side of §2 it falls on — if it is both, it is two systems"):
|
||||
|
||||
- **The loop is code** (§2: state) — purse, buy/sell, the ~40% fence rate,
|
||||
gritty disabled-CTA reasons. Already sequenced as M8's *Shop economy*.
|
||||
- **The numbers are content** — what a shortsword costs, a night at the inn, an
|
||||
ale, the quest's purse. These live in the BOM as the **price table**.
|
||||
|
||||
### Currency model
|
||||
|
||||
```
|
||||
1 gold = 100 silver = 10,000 copper
|
||||
1 silver = 100 copper
|
||||
```
|
||||
|
||||
**Gold is scary.** At 10,000 copper to the gold, a peasant's whole life is
|
||||
copper, a mercenary's fee is silver, and a gold coin is a plot point. The party
|
||||
counting coppers for an inn bed is §3 grit, and Brannoc has an opinion about it.
|
||||
|
||||
**This is a change, not a new thing — and it has a client consumer.** It lands as
|
||||
its own small item **before M7**, cheapest now while `content/world/items/`
|
||||
contains exactly two files:
|
||||
|
||||
- A `Currency` value type — **store everything in copper**, format only at the
|
||||
display edge (`12g 40s 8c`).
|
||||
- `coin.json` → real denominations; all prices re-denominated.
|
||||
- The Main Window shell's command-bar purse updated (it currently shows a flat
|
||||
gold value).
|
||||
|
||||
*§2: state · depends on nothing · goal: money that means something.*
|
||||
|
||||
---
|
||||
|
||||
## 5. Process
|
||||
|
||||
- Each BOM line is authored through the **`/world-building` skill** — it
|
||||
reconciles against existing canon, writes the build tool's source format, and
|
||||
verifies the build stays green.
|
||||
- **Adopting Greywater means authoring it upward.** The hand-written JSON under
|
||||
`content/world/{locations,quests,npcs,items}` becomes
|
||||
`content/lore/greywater.md`, and `python -m content_build` emits `world/` from
|
||||
it.
|
||||
- **The build tool needs two new namespaces: `item` and `quest`.** Its legal
|
||||
namespaces today (`tools/content_build/model.py`) are `town`, `place`,
|
||||
`region`, `faction`, `person`, `rule`, `rumor`, `fact`, `secret`, `npc` — so
|
||||
**locations are already modeled** (`town`/`place`/`region`) and only items and
|
||||
quests fall outside it. Adding those two namespaces (model, emit, resolve) is a
|
||||
prerequisite of the M7 and M8 BOM lines, and is done against content that
|
||||
already has tests.
|
||||
- **Moving or deleting generated content is a client change.** `content/world/**`
|
||||
has a client consumer: `client/scripts/content/content_db.gd` (via
|
||||
`client/scripts/harness/npc_harness.gd`) and its GUT tests in
|
||||
`client/tests/unit/test_content_db.gd`. The Duncarrow lesson, applied
|
||||
preemptively — check `client/` before any content move.
|
||||
|
||||
---
|
||||
|
||||
## Consequences
|
||||
|
||||
- Content becomes **countable and bounded**. "All the items" becomes fourteen.
|
||||
- The cosmology stops being abstract — Ghaul, the blood-price, and possession all
|
||||
land in the slice's quest chain.
|
||||
- The build tool gains `item` and `quest` namespaces, completing the content
|
||||
model (locations already exist as `town`/`place`/`region`).
|
||||
- The currency change jumps the queue ahead of M4, because it is cheapest while
|
||||
the item set is nearly empty.
|
||||
- The Backlog absorbs everything the slice does not need, so it can be forgotten
|
||||
without being lost.
|
||||
|
||||
## Out of scope
|
||||
|
||||
Authoring the slice's actual content — this spec builds the **container**. Each
|
||||
BOM line is its own `/world-building` session. The Greywater canon session (town,
|
||||
NPCs, the ledger chain's four objectives, Ghaul's harvest site) is the next
|
||||
piece of work, not part of this one.
|
||||
Reference in New Issue
Block a user