Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .abcd/development/brief/01-product/03-mental-model.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
> **Read with adr-2609212115255771 (2026-09-21).** The phase layer described below is retired: the layers are the brief, the intent and the spec (with its steps), the bundle is a delivery grouping of intents, the derived release is the checkpoint, and Now / Next / Later is a rendered status, never a stored unit. The diagram and the prose keep the phase until itd-2609211913453478 rewrites this chapter; until then, read "phase" as history.

# Four-Layer Mental Model

abcd uses four layers to organise development work, each tuned to the kind of question it answers. Three are the original design layers — brief, intent, spec; the fourth, **phase**, is the sequencing-and-reflection layer added per [adr-9](../../decisions/adrs/0009-phase-as-product-layer.md). The diagram below shows the brief → intent → spec flow into delivered reality, with the phase as the audit target of delivered reality; the phase layer is explained in full after it.
Expand Down
3 changes: 0 additions & 3 deletions .abcd/development/brief/06-delivery/03-out-of-scope.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,6 @@ gate. That is what keeps "not hand-counted" true after the day it was written.
- `itd-142` — The brief-creation interview: staged elicitation into the brief and a ledger (frontier rounds, options at conjectural questions, hold register, two-output rule per adr-50); spec waits on the collaborating prototype's first run
- `itd-143` — The framing chapter under 01-product/: the macro-why home, with its brief↔lifeboat mapping row; receives itd-142's committed framing products
- `itd-144` — Every livery mark has a surface: the lifeboat on disembark and mirrored on embark, the duckling as the harness mascot, the flag icon for the website (settles itd-112's deferred forge/web logo question)
- `itd-146` — abcd's help renders in labelled command groups, gated by a group field in the surface snapshot and an ungrouped-verb test (the reframed survivor of the verb-taxonomy ideate verdict; no verb renamed, moved or hidden)
- `itd-149` — abcd handles inbound security advisories and issues, and cuts the release, for every managed repo (the 2026-08-27 pilot's loop automated; findings F-A…F-W are the acceptance-criteria source, F-U and F-Q load-bearing; filed after the itd-84 SPLIT, awaiting the planning interview)
- `itd-163` — Reference-closure and acknowledgements-mirror gate: every citation resolves to the CSL references, the references and acknowledgements mirror both ways, and a committed influence registry backs the Inspirations list (supersedes itd-145; filed from the 2026-08-28 attribution review with the backfill issue iss-2608280824478819)
- `itd-164` — Licence vetting at source admission: `docs cite refresh` records each source's licence verdict into the committed baseline, and the zero-network gate refuses a new entry without one (builds on itd-163)
Expand All @@ -107,7 +106,6 @@ gate. That is what keeps "not hand-counted" true after the day it was written.
- `itd-175` — The product thinker writes down how this could be wrong, and what would show it (Phase 8; the defeater list an acceptance rests on)
- `itd-176` — Whatever ships says how hard anyone looked at it (Phase 7)
- `itd-201` — every question abcd's agents put to a human is asked one at a time, in plain language, in the addressee's register, with options that widen
- `itd-2609061543533170` — one verb sets up a managed repository's release-rendered site end to end: the site composition, the wrangler configuration, the render-then-deploy workflow, the environments it needs, and the worker itself where a credential is held
- `itd-2609151838312703` — sessions on one machine or one local network leave each other messages in a shared mailbox abcd owns (the built-in basic; nothing leaves the local network)
- `itd-2609151838327688` — an opt-in adapter to a local message broker brings push delivery and cross-machine reach to the session mailbox (sequenced after the mailbox)
- `itd-2609151541116052` — every question an interview puts to a human shows the thing being decided before it asks, at every step (refines itd-201)
Expand All @@ -124,7 +122,6 @@ gate. That is what keeps "not hand-counted" true after the day it was written.
- `itd-2609090746414083` — A lifeboat packs from a lab session home, the throwaway experiment's intention, harvest and bundle, with the same coverage honesty as a repository (refines itd-88 and adr-35; the non-git half, sequenced after the lab verb family)
- `itd-2609180517121254` — every payload a host hands back from a delegated step names the model that produced it and the number of agents that ran, and the ingesting verb refuses one that does not
- `itd-2609201916056194` — a delegated agent runs through a command-line model runner the operator chose (claude CLI, opencode/openrouter); the opt-in cli oracle rung
- `itd-2609211913453478` — one glossary page maps the record families (intent, spec, bundle, phase, batch, issue, roadmap, release) and how they relate, and answers whether a phase is still the sequencing layer
<!-- /index -->

**Later-phase items with no intent id.** These four were written into the brief
Expand Down
12 changes: 10 additions & 2 deletions .abcd/development/brief/glossary/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,20 +72,24 @@ glossary/
├── core/
│ ├── README.md
│ ├── brief.md
│ ├── bundle.md
│ ├── construal.md
│ ├── disembark.md
│ ├── intent.md
│ ├── ledger.md
│ ├── lifeboat.md
│ ├── loop.md
│ ├── milestone.md
│ ├── oracle.md
│ ├── persona.md
│ ├── phase.md
│ ├── plan.md
│ ├── reading-position.md
│ ├── record-families.md
│ ├── record.md
│ ├── roadmap.md
│ ├── spec.md
│ ├── step.md
│ ├── surface.md
│ ├── transport.md
│ └── voyage.md
Expand Down Expand Up @@ -189,20 +193,24 @@ The complete write-back protocol is a **design target** of `/abcd:intent grill`'
| Term | Status | Definition |
|---|---|---|
| [brief](core/brief.md) | stable | The living root document that holds a project's purpose, constraints, and success criteria — always the project's current state, revised in place as the project moves. |
| [bundle](core/bundle.md) | stable | Several intents that share one spec because they ship as one change; each member carries kind bundle-member and the bundle's name, and all ship together when the spec closes. |
| [construal](core/construal.md) | stable | The statement of what the situation is being treated as, in one or two sentences, held at the top of the brief's framing chapter as the frame a widening reading reads against; one of adr-55's three framing surfaces, beside the committed glossary terms and the committed scope. The ledger context's entry governs the term inside the cold-reading experiment. |
| [disembark](core/disembark.md) | stable | The act of packing a lifeboat — `abcd disembark <source-repo> to <dest>` reads a source repository without writing to it and distils its settled artefacts, decisions, and configuration into a portable lifeboat directory at a destination outside that repository, which a fresh context can later unpack via `/abcd:embark`. |
| [intent](core/intent.md) | stable | A press-release-shaped description of a feature written before implementation begins, capturing the user problem, proposed solution, and success criteria. |
| [ledger](core/ledger.md) | stable | An append-or-move store a command writes and a human reads back, the issue ledger under .abcd/work/issues/ when the word stands bare; inside the cold-reading experiment the word means the warm material and its stores, which the read-block keeps from a reading (the ledger context's entries govern that sense). Four further ledgers share the word and are always named in full. |
| [lifeboat](core/lifeboat.md) | stable | A portable directory artefact packed by `/abcd:disembark` that captures the distilled knowledge and configuration of a source project so it can be unpacked into a fresh context by `/abcd:embark`. It always lands outside the source repository, at an operator-chosen destination. |
| [loop](core/loop.md) | draft | The record loop — brief to intent to spec to shipped work to audited verdict and back onto the brief — which shipping closes twice, once by grading the acceptance criteria and once by rewriting the brief passage. Two other loops carry the word and are always qualified: the autonomous-run loop and the lifeboat round-trip. |
| [milestone](core/milestone.md) | superseded | A planned end condition for a stretch of work; retired: the checkpoint is the derived release plus each intent's acceptance criteria. |
| [oracle](core/oracle.md) | stable | An AI model invoked to review, reason over, or validate a project's artefacts — host-delegated by default, or reached through an opt-in oracle adapter. |
| [persona](core/persona.md) | stable | A placeholder stakeholder character drawn from the abcd personas registry, used in press releases, intents, and design documents to represent a real user archetype without using real names. |
| [phase](core/phase.md) | stable | An ordered stretch of development work that bundles a set of intents and brief plumbing-phases and ends in a milestone; abcd's sequencing layer, recorded as a document in roadmap/phases/. Unqualified it always carries that sense, the brief's own numbered build milestones being plumbing-phases. |
| [phase](core/phase.md) | superseded | An ordered stretch of development work that bundles a set of intents and brief plumbing-phases and ends in a milestone; abcd's sequencing layer, recorded as a document in roadmap/phases/. Unqualified it always carries that sense, the brief's own numbered build milestones being plumbing-phases. |
| [plan](core/plan.md) | stable | The maintainer's sign-off act `abcd intent plan <itd-N>`, which mints a spec, links both sides and moves a draft intent to planned/. Three further senses share the word — the ordered build plan the phase docs hold, a dated design plan under development/plans/, and a session's planning brief — and each is qualified where it appears. |
| [reading-position](core/reading-position.md) | stable | One of the four questions a cold reading can be commissioned to answer — widening, entailment, comparative or detection. The position fixes the reading's object, its question and the supply regime its output is validated against; `abcd reading assemble --position` names it. |
| [record-families](core/record-families.md) | stable | The one page that maps abcd's record families (intent, spec, step, bundle, issue, release, status) and how they relate: what each groups, what groups it, its lifecycle and the verb that moves it. |
| [record](core/record.md) | stable | One identified, filed document that a command mints and a lint gate reads — an itd-N, spc-N, adr-N, iss-N or rdg-id. "The development record" is the whole durable corpus those records make up, and "a record family" is one lifecycle-bucketed set of them; each of the three is qualified where the other two could be read. |
| [roadmap](core/roadmap.md) | stable | The sequencing folder .abcd/development/roadmap/, which holds the phase docs and the RFCs. Its README is the roadmap dashboard, a separate sense — a live status render that reads the native spec store and the intent buckets rather than the phase docs. |
| [roadmap](core/roadmap.md) | superseded | The sequencing folder .abcd/development/roadmap/, which holds the phase docs and the RFCs. Its README is the roadmap dashboard, a separate sense — a live status render that reads the native spec store and the intent buckets rather than the phase docs. |
| [spec](core/spec.md) | stable | A specced block of work in abcd's native spec store that implements one or more intents, broken into ordered tasks with acceptance criteria. |
| [step](core/step.md) | stable | One of the ordered, independently landable pieces a spec lists under its Steps section; each step is one lane and one pull request, and a spec with no steps is one step. |
| [surface](core/surface.md) | stable | A verb's front door — the markdown command file under commands/ plus the transport package under internal/surface/ that reaches the core. "A surface chapter" is the brief's design record for one such front door, and "a rendered surface" is a public text held to the repository's identity block; both are qualified. |
| [transport](core/transport.md) | stable | The mechanism by which curated context and artefacts are packaged and delivered to an oracle for review or reasoning. |
| [voyage](core/voyage.md) | stable | The operations namespace at `~/.abcd/voyage/<source-root-sha>/` — an append-only record of what abcd *did* to produce a lifeboat (every disembark and embark run), as against the lifeboat itself, which is what gets carried. |
Expand Down
22 changes: 22 additions & 0 deletions .abcd/development/brief/glossary/core/bundle.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
---
term: bundle
bounded_context: core
definition: Several intents that share one spec because they ship as one change; each member carries kind bundle-member and the bundle's name, and all ship together when the spec closes.
aliases: []
forbidden_synonyms: ["phase", "epic", "milestone"]
status: stable
introduced_in: itd-34
starts_when: null
ends_when: null
not_to_be_confused_with: core/step
versions: null
---
<!-- Adapted from mattpocock/skills (MIT). See README Acknowledgements. -->

# bundle

A **bundle** is a delivery grouping, not a sequencing one: two or three intents whose work is one change, planned together by `abcd intent plan itd-A itd-B --bundle <name>` (itd-34), sharing one spec and shipping together when it closes. A bundle says nothing about what comes before what; that is dependencies. A bundle cannot contain its own blocker.

## When to use

When two intents would be one pull request. Not as a phase in disguise: a bundle of ten is a sign the intents were cut wrong.
18 changes: 18 additions & 0 deletions .abcd/development/brief/glossary/core/milestone.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
---
term: milestone
bounded_context: core
definition: A planned end condition for a stretch of work; retired: the checkpoint is the derived release plus each intent's acceptance criteria.
aliases: []
forbidden_synonyms: []
status: superseded
introduced_in: adr-9
starts_when: null
ends_when: null
not_to_be_confused_with: core/record-families
versions: null
---
<!-- Adapted from mattpocock/skills (MIT). See README Acknowledgements. -->

# milestone

> **Superseded on 2026-09-21 (adr-2609212115255771).** The word never had an entry of its own; it lived as a forbidden synonym of phase. Its job, a checkable end condition, is done twice over: each intent's acceptance criteria say when that work is done, and the derived release says what shipped. An intent that must land by a cut says so with `target_release` (itd-2609212103572513), which the cut reports and carries forward. See [record-families](record-families.md).
7 changes: 5 additions & 2 deletions .abcd/development/brief/glossary/core/phase.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,17 +4,20 @@ bounded_context: core
definition: An ordered stretch of development work that bundles a set of intents and brief plumbing-phases and ends in a milestone; abcd's sequencing layer, recorded as a document in roadmap/phases/. Unqualified it always carries that sense, the brief's own numbered build milestones being plumbing-phases.
aliases: ["roadmap phase"]
forbidden_synonyms: ["version", "release", "milestone", "sprint", "iteration"]
status: stable
status: superseded
introduced_in: adr-9
starts_when: null
ends_when: null
not_to_be_confused_with: core/spec
not_to_be_confused_with: core/record-families
versions: null
---
<!-- Adapted from mattpocock/skills (MIT). See README Acknowledgements. -->

# phase

> **Superseded on 2026-09-21 (adr-2609212115255771): the sequencing layer is dependencies plus the lifecycle shelves, rendered as the Now / Next / Later status block; the phase documents stay as history.** See [record-families](record-families.md).


A **phase** is abcd's sequencing layer — an ordered stretch of work that ends in a
**milestone** (a concrete, checkable end condition). Phases replace plugin-version language
(`v1`, `v2`) as the way the project organises what ships together and in what order. Each
Expand Down
36 changes: 36 additions & 0 deletions .abcd/development/brief/glossary/core/record-families.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
---
term: record-families
bounded_context: core
definition: The one page that maps abcd's record families (intent, spec, step, bundle, issue, release, status) and how they relate: what each groups, what groups it, its lifecycle and the verb that moves it.
aliases: []
forbidden_synonyms: []
status: stable
introduced_in: adr-2609212115255771
starts_when: null
ends_when: null
not_to_be_confused_with: null
versions: null
---
<!-- Adapted from mattpocock/skills (MIT). See README Acknowledgements. -->

# record-families

The families, and the two axes they sit on.

| Family | What it is | Groups | Grouped by | Lifecycle | Moved by |
|---|---|---|---|---|---|
| **intent** | one user-facing capability, press release first | its specs | a bundle (delivery) | drafts → planned → shipped (superseded; disciplines) | `intent plan`, `spec close`, `intent reclassify` |
| **spec** | the design record for one piece of scheduled work | its steps | its intent (one or more specs per intent) | open → closed | `intent plan` mints, `spec close` |
| **step** | one landable piece of a spec | nothing | its spec | listed, landed, or carried into the remainder | `abcd build` |
| **bundle** | intents that ship as one change | intents | nothing | named at plan, ships with its spec | `intent plan --bundle` |
| **issue** | a captured finding with a remedy; no spec by design | nothing | nothing (edges: `blocked_by`) | open → resolved / wontfix | `capture`, `capture resolve`, `drain` |
| **release** | the derived cut: version from impact, changelog from records | what shipped since the last tag | nothing | cut, tagged | `launch ship` |
| **status** | Now / Next / Later, rendered from the shelves, the gate and the build's state | nothing (a view) | nothing | none: computed | nothing |

**Two axes.** The *lifecycle* (what has been decided about a record) lives in the folders and is what the gates read. The *position* (how soon) is rendered from it as Now / Next / Later and is never stored. Sequencing is dependencies (`blocked_by`, `builds_on`) plus the shelves; nothing sits above the intent for sequence.

**Retired**: [phase](phase.md) and [milestone](milestone.md) (2026-09-21, adr-2609212115255771), and the word roadmap; a **batch** is the autonomous run's internal order, derived from dependencies and the pick, and is not a term of the record.

## When to use

When unsure which word to use, or whether a new grouping deserves a name: a name that has no row here is a name nobody has justified.
7 changes: 5 additions & 2 deletions .abcd/development/brief/glossary/core/roadmap.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,17 +4,20 @@ bounded_context: core
definition: The sequencing folder .abcd/development/roadmap/, which holds the phase docs and the RFCs. Its README is the roadmap dashboard, a separate sense — a live status render that reads the native spec store and the intent buckets rather than the phase docs.
aliases: ["roadmap folder"]
forbidden_synonyms: ["backlog", "timeline", "release plan"]
status: stable
status: superseded
introduced_in: adr-9
starts_when: null
ends_when: null
not_to_be_confused_with: core/phase
not_to_be_confused_with: core/record-families
versions: null
---
<!-- Adapted from mattpocock/skills (MIT). See README Acknowledgements. -->

# roadmap

> **Superseded on 2026-09-21 (adr-2609212115255771): the rendered Now / Next / Later status block on the `abcd` board and the site's Status page replaces the roadmap document and the word.** See [record-families](record-families.md).


The **roadmap** is [`.abcd/development/roadmap/`](../../../roadmap/README.md): two things and
no others — [`phases/`](../../../roadmap/phases/README.md), the ordered build plan, and
`rfcs/`, where a proposal is argued before it becomes an ADR. It carries no dates and no
Expand Down
Loading
Loading