From 5e5d3238cb60a74929aa96a737b2378427891e75 Mon Sep 17 00:00:00 2001 From: alexneyman Date: Thu, 9 Jul 2026 15:19:16 -0400 Subject: [PATCH] feat: roadmap as the fifth canonical piece MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Charters decompose into parallel, seam-disjoint lanes the owner hands to agents — one owner chat per lane. Adds ROADMAP.template.md, wires the roadmap into GUIDE outputs and CHECK drift repair, rewrites the handoff section (a canon without a roadmap is incomplete), and adds the persist-the-canon-immediately grill rule (a shared-tree reset destroyed a live grill's uncommitted canon on 2026-07-09). First applied in production on the Iris project the same day. Co-Authored-By: Claude Fable 5 --- README.md | 7 +++-- skills/pdd/SKILL.md | 55 +++++++++++++++++++++++++---------- templates/ROADMAP.template.md | 51 ++++++++++++++++++++++++++++++++ 3 files changed, 95 insertions(+), 18 deletions(-) create mode 100644 templates/ROADMAP.template.md diff --git a/README.md b/README.md index 758d042..bf15dca 100644 --- a/README.md +++ b/README.md @@ -14,9 +14,9 @@ It works the same whether the owner is an engineer or has never written code. Te state preferences when they have them; everyone else gets recommendations in plain language. When the owner doesn't understand a choice, the agent teaches. Progress never stalls on a word. -## The four canonical pieces +## The five canonical pieces -A project is bootstrapped when these four things are decided, written down, and easy to change: +A project is bootstrapped when these five things are decided, written down, and easy to change: 1. **The purpose**: what the project is for, as a northstar plus a few *charters* (see below). 2. **The tools available**: what already exists in the environment: services, accounts, APIs, @@ -24,6 +24,8 @@ A project is bootstrapped when these four things are decided, written down, and 3. **The tools we're willing to have**: the acceptance boundary. What the owner will adopt, pay for, and depend on. 4. **The tech stack**: chosen once, recorded, and not re-argued every session. +5. **The roadmap**: the charters decomposed into parallel, seam-disjoint lanes, each + citing the charter it serves — how the owner organizes agents to do the work. All four are living canon: okay to change over time, never okay to be unwritten. Being unsure is fine too. An open question becomes a *figure-out-through-building* item, recorded as such. @@ -84,6 +86,7 @@ was extracted from. ``` skills/pdd/SKILL.md the core skill: guide or check a project's canon templates/PURPOSE.template.md the northstar + charters skeleton +templates/ROADMAP.template.md charters -> parallel seam-disjoint lanes templates/decisions-ledger.template.md templates/claude-md-injection.md the ≤10-line block a project's CLAUDE.md gets templates/surface.template.html the one page the owner looks at (open items, synthesis, ramble box) diff --git a/skills/pdd/SKILL.md b/skills/pdd/SKILL.md index c7624fe..b428ee8 100644 --- a/skills/pdd/SKILL.md +++ b/skills/pdd/SKILL.md @@ -26,9 +26,9 @@ and teaching the owner whatever they need so progress never stalls on a word. - **Canon already exists** → **CHECK**. Audit it for gaps and drift, fix the mechanical problems automatically, and surface only the judgment calls. -## The four canonical pieces +## The five canonical pieces -Every project's canon is drilled through these four. They become source of truth — +Every project's canon is drilled through these five. They become source of truth — fine to change over time, but always canon: 1. **The purpose** — the northstar plus its charters (what each major feature is @@ -39,6 +39,12 @@ fine to change over time, but always canon: will adopt, pay for, or depend on going forward — and what they won't. 4. **The tech stack** — chosen and recorded once, so it is not re-litigated every session. +5. **The roadmap** — the charters decomposed into parallel, seam-disjoint lanes + (no two lanes own the same files), each citing the charter it serves, each + with its first atoms and its proof. This is how the owner organizes agents to + do the work: one owner chat per lane. Start it from + `templates/ROADMAP.template.md`; when the purpose is amended, the roadmap is + re-ranked in the same pass. ## The rules of every grill (apply in both modes) @@ -73,6 +79,11 @@ you start. The load-bearing rules: - **Unknowns are first-class.** It is fine to be unsure. Record an unanswerable question as a *figure-out-through-building* item in the canon — a real entry, not a forced fake decision. +- **Persist the canon immediately.** Commit (or durably save) the canon files + right after every GUIDE or CHECK pass and after each grill round — never leave + them only in a working tree. An unsaved canon can be destroyed by concurrent + work; it happened (a shared-tree reset wiped a live grill's surface and ledger, + 2026-07-09). ## The one surface @@ -113,6 +124,8 @@ Copy this checklist and check items off as you go: - `PURPOSE.md` ← `templates/PURPOSE.template.md` - a decisions ledger ← `templates/decisions-ledger.template.md` - the surface page ← `templates/surface.template.html` + - the roadmap ← `templates/ROADMAP.template.md` (charters → parallel + seam-disjoint lanes; may start sparse, never absent) - inject the block from `templates/claude-md-injection.md` into the project's `CLAUDE.md` (or `AGENTS.md`), filling in the two paths. - [ ] G6: Confirm the loop closes: open a fresh agent context, have it read @@ -133,7 +146,9 @@ interrupts the owner for genuine judgment calls. a CLAUDE.md missing the block, charters with no "serves" line, ledger entries that never made it into the doc, absolutes that crept in, formatting the templates define, a surface page that has drifted into a status collage - or replays answered questions (regenerate it from the canon). Repair these + or replays answered questions (regenerate it from the canon), a missing + roadmap, a roadmap lane citing no charter or two lanes claiming the same + seam (wire the citation when derivable; otherwise it is a C3 item). Repair these without asking; report what you changed. - [ ] C3: **Surface only judgment calls** — a charter that no longer matches what the project does, a purpose statement contradicted by recent work, two @@ -150,19 +165,27 @@ interrupts the owner for genuine judgment calls. Use the exit status so CHECK can run unattended in a loop: 0 and 1 need no human; 2 stops for the owner. -## Handoff — from purpose to work - -/pdd produces the *why* (purpose + charters). It does **not** -decompose the project into buildable work — that is the atomic-readiness skill's -job. Once the canon exists: - -- Hand the charters to an **atomic-readiness**-style decomposition skill to break - each into independently-improvable lanes and atoms (seam-disjoint: parallel - lanes never share files, so one person can run many lanes without conflicts). -- Enforce the citation rule: **every lane cites the charter it serves.** A lane - that serves no charter is a signal to check the purpose, not to invent one. -- When the purpose is amended, re-weigh the work queue — atoms serving a - downgraded charter drop in priority; a new charter can raise new work. +## The roadmap — from purpose to parallel work + +/pdd produces the *why* (purpose + charters) AND the lane-level *what*: the +roadmap (`templates/ROADMAP.template.md`) decomposes the charters into parallel, +seam-disjoint lanes the owner can hand to agents — one owner chat per lane. +Finer-grained decomposition (atoms, readiness rubrics, eval wiring) may pair +with an atomic-readiness-style skill, but a canon without a roadmap is +incomplete: the owner should never have to invent the work breakdown themselves. + +- **Seam-disjoint is the law of parallelism**: no two lanes own the same files, + so lanes never clobber each other. Shared hot files get one owner and a + declared touch protocol. +- **Every lane cites the charter it serves.** A lane that serves no charter is a + signal to check the purpose, not to invent one. +- Each lane carries: the charter it serves, a one-line goal, its first atoms, + the seams it owns, its proof (how "done" is verified independently), and + dependencies on other lanes. +- **When the purpose is amended, the roadmap is re-ranked in the same pass** — + lanes serving a downgraded charter drop; a new charter opens a lane. +- Live lane state (status, milestones, learnings) stays in the project's lane + docs, not in the roadmap — the roadmap is the map, not the log. The full mechanics of running a grill live (posting cards, collecting answers, appending a schema-checked ledger) come from the how-to-work engine — see the diff --git a/templates/ROADMAP.template.md b/templates/ROADMAP.template.md new file mode 100644 index 0000000..95973a6 --- /dev/null +++ b/templates/ROADMAP.template.md @@ -0,0 +1,51 @@ +# Roadmap — parallel lanes under the purpose + + + +Derived from . + +## The lanes at a glance + +| lane | serves (charter) | one-line goal | depends on | +| --- | --- | --- | --- | +| | | | — | +| | | | | + +## — (charter: ) + + + +- Atoms: . +- Seams owned: . +- Proof: . + +## — (charter: ) + +<...> + +- Atoms: <...> +- Seams owned: <...> +- Proof: <...> + +## Operating notes + +- One owner chat per lane; lanes in the in-focus charters staff first. +-