docs: VISION for v1.0 + clarify docs/ vs agent/ vs .claude
All checks were successful
Check / eval (push) Successful in 3m7s

Add docs/VISION.md (product themes, v1.0 bar, agent slice hints) and
README maps under docs/ and agent/. Point ROADMAP, BACKLOG, LOOP,
CLAUDE, HARDWARE, and the root README at the split: VISION = intent,
BACKLOG = executable queue, ROADMAP = design history, .claude = harness
only. Mark v1.0 track in BACKLOG PROPOSED for human triage.
This commit is contained in:
Bernardo Magri
2026-07-09 09:33:51 +01:00
parent caaac88da9
commit 02d7baeb7c
10 changed files with 340 additions and 52 deletions

View File

@@ -1,22 +1,24 @@
# Backlog — the prioritized task queue
The forward-looking half of the old docs/ROADMAP.md, reworked as a queue
agents can execute. Detailed design notes and decision records stay in
`docs/ROADMAP.md` (referenced as "ROADMAP § <item>"); this file is *what's
next, in what order*.
**This is the only executable work list for agents.** Product themes and
v1.0 intent live in [`docs/VISION.md`](../docs/VISION.md); design history
in [`docs/ROADMAP.md`](../docs/ROADMAP.md); map in
[`docs/README.md`](../docs/README.md) and [`agent/README.md`](README.md).
**Rules:**
- Agents take the topmost actionable item (see LOOP.md). Finished items
are **deleted** here — the journal + git log are the record; durable
design notes get a ✓-entry in docs/ROADMAP.md if worth keeping.
design notes get a ✓-entry in docs/ROADMAP.md (and/or a note in VISION)
if worth keeping.
- Item numbers are **stable IDs** — never renumbered or reused. A gap in
the sequence means shipped (or dropped) work; new items take the next
free number regardless of tier.
- Tags: `[blocked:hw]` needs real hardware (see HARDWARE-QUEUE.md) ·
`[human]` needs Bernardo · `[stuck]` two failed attempts, needs help ·
`[big]` must be split before starting.
- Agents may append to **PROPOSED** and **Decisions** freely; only
Bernardo moves items *out* of PROPOSED into the tiers.
- Agents may append to **PROPOSED** and **Decisions** freely (include
`VISION § …` or `ROADMAP § …` when relevant); only Bernardo moves items
*out* of PROPOSED into the tiers.
---
@@ -101,9 +103,19 @@ actually float once seen (regex tolerance for the `.…-wrapped` form).
*Agents: append here with a one-paragraph pitch (what/why/cost). Do not
implement. Bernardo moves accepted items into a tier.*
### v1.0 track — see `docs/VISION.md`
Product themes and the release bar live in **VISION**. Many slices
already have pitches below (Hardware product, Installer bugs, Default
theme → boreal). When adding new product work, reference
`VISION § <theme>` and prefer the north-star laptop user. Suggested
next promotions (human picks order): install P0 contracts · boreal
default · System Firmware · doctor hardware · fingerprint menu ·
first-boot tips · human rebuild errors · neon-glass quarantine.
### Pre-existing
- **Default theme → boreal**
- **Default theme → boreal** (`VISION § B` / v1.0 bar)
Ship Boreal as the distro default instead of Tokyo Night: root
`theme-state.json`, `templates/downstream/theme-state.json` (and any
greeter/plymouth fallbacks that hardcode Tokyo Night when state is