Skip to content
Merged
2 changes: 1 addition & 1 deletion .abcd/development/brief/01-product/01-press-release.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Long-running projects accumulate context that doesn't live in any one file: why
- **Unpack the lifeboat:** `/abcd:embark from <path>` reads the lifeboat, runs a press-release interview to confirm the framing with the user, scaffolds the new repo at canonical locations, and writes provenance so the rebuild knows where it came from. The literal string `home` resolves to the current repo's `.abcd/lifeboat/` for the round-trip case.
- **Install / promote:** `/abcd:ahoy install` bootstraps abcd in any repo (transparent prompts, visibility-driven gitignore, marker block in CLAUDE.md/AGENTS.md, prompt-router hook). `/abcd:launch ship` cuts a curated release from the single repo — `.abcd/**` excluded from the artifact by packaging — with secret/PII scans and a version stamp.
- **Forward-looking discipline:** `/abcd:intent` captures product intents in three structural kinds per itd-34 — `standalone` (one user moment, one spec), `bundle-member` (coupled intents share a spec), and `discipline` (cross-cutting rules with no user moment, e.g., the itd-1 acceptance-gates rule that enforces Given-When-Then on every other spec). Standalone and bundle-member intents are press-release-shaped; disciplines use a `## Rule` template instead. `/abcd:capture` runs a structured issue ledger that replaces free-form `.work/issues.md`. `/abcd:intent grill` (sibling of `refine`, per itd-27) is a Socratic-questioning sub-verb that stress-tests intents (or brief sections, via `--brief-section`) before planning. After shipping, `/abcd:intent review` (Role 1 of `intent-fidelity-reviewer`) reviews delivered reality against the press release; `/abcd:intent consistency` (Role 2, shipped in spc-29 per itd-48, which superseded itd-31) catches cross-document drift; `/abcd:intent shape` (Role 3) keeps each intent's `kind` honest.
- **Plumbing that makes it possible:** 15 agents, a vendor-agnostic adapter seam, a host-delegated LLM with opt-in oracle adapters (native, CLI, API, MCP), a prompt-quality stack with golden-test fixtures, structural lint, periodic SOTA audit, prompt-version frontmatter, self-improvement pre-flight, and injection-canary fixtures — plus operator-internal command wiring (e.g. `/abcd:run`, the itd-29 autonomous-run operator surface — read-mostly `status`/`pause`/`resume`/`preflight` over the pluggable autonomous-run seam; not part of the user-facing command set).
- **Plumbing that makes it possible:** 16 agents, a vendor-agnostic adapter seam, a host-delegated LLM with opt-in oracle adapters (native, CLI, API, MCP), a prompt-quality stack with golden-test fixtures, structural lint, periodic SOTA audit, prompt-version frontmatter, self-improvement pre-flight, and injection-canary fixtures — plus operator-internal command wiring (e.g. `/abcd:run`, the itd-29 autonomous-run operator surface — read-mostly `status`/`pause`/`resume`/`preflight` over the pluggable autonomous-run seam; not part of the user-facing command set).

See [`04-scope.md`](04-scope.md) for the full scope boundary and [`04-surfaces/`](../04-surfaces) for per-command detail.

Expand Down
2 changes: 1 addition & 1 deletion .abcd/development/brief/01-product/03-mental-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ flowchart TD

**Why typing matters.** The 1:1-only model (every intent = one spec) forces bundle-shaped work into separate specs that redo each other's plumbing, and forces discipline-shaped rules into "specs" whose only deliverable is "every other spec inherits this gate." Both shapes calcify into wrong fits. The three kinds let each intent's *delivery shape* match its *forward-looking shape* without forcing one onto the other.

**The six phases target thirteen intents across two of the three kinds:** ten standalone (itd-2, itd-3, itd-4, itd-6, itd-7, itd-27, itd-28, itd-34, itd-36, itd-40) and three disciplines (itd-1, itd-5, itd-37). The `bundle-member` kind exists in the framework but isn't currently exercised — the corpus has zero live bundles. See [`phases/README.md`](../../roadmap/phases/README.md) for the phase plan and each phase's intent scope, [`intents/README.md`](../../intents/README.md) for the intent index, and that file's § Bundles for the retired-bundle history.
**The phased intents span two of the three kinds** standalone capabilities plus the three disciplines (itd-1, itd-5, itd-37); the set itself is the union of the phase docs' `## Scope` sections and is never transcribed here (per [adr-9](../../decisions/adrs/0009-phase-as-product-layer.md), hand-kept counts re-drift). The `bundle-member` kind exists in the framework but isn't currently exercised — the corpus has zero live bundles. See [`phases/README.md`](../../roadmap/phases/README.md) for the phase plan and each phase's intent scope, [`intents/README.md`](../../intents/README.md) for the intent index, and that file's § Bundles for the retired-bundle history.

**Classification happens at plan time.** Capture stays cheap and format-neutral (`/abcd:intent "<text>"` produces a press-release-shaped draft regardless of eventual kind, with an optional advisory `suggested_kind` hint from the LLM classifier). The binding `kind` field is set at `/abcd:intent plan` time, when the user is committing to *build* the thing — that's when the shape decision has to be true. A continuous audit role (the third role on `intent-fidelity-reviewer`, see [`05-internals/01-agents.md`](../05-internals/01-agents.md)) suggests reclassifications when patterns emerge in the corpus over time.

Expand Down
26 changes: 18 additions & 8 deletions .abcd/development/brief/01-product/04-scope.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Scope

The scope this brief covers is bounded by what is bundled into the six planned phases (Phase 0 — Substrate & disciplines through Phase 5 — round-trip; see [`roadmap/phases/README.md`](../../roadmap/phases/README.md)) plus what is explicitly slated for a later phase.
The scope this brief covers is bounded by what is bundled into the seven planned phases (Phase 0 — Foundations through Phase 6 — Lifeboat round-trip; see [`roadmap/phases/README.md`](../../roadmap/phases/README.md)) plus what is explicitly slated for a later phase.

## What the phases deliver

Expand All @@ -13,22 +13,32 @@ The scope this brief covers is bounded by what is bundled into the six planned p
- `/abcd:intent` — press-release intent capture — see [`04-surfaces/05-intent.md`](../04-surfaces/05-intent.md)
- `/abcd:capture` — issue ledger — see [`04-surfaces/06-capture.md`](../04-surfaces/06-capture.md)
- `/abcd:memory` — multi-upstream curated knowledge substrate (per itd-36) — see [`05-internals/07-memory.md`](../05-internals/07-memory.md)
- `/abcd` — top-level where-am-i status board (per itd-20) — see [`04-surfaces/08-abcd.md`](../04-surfaces/08-abcd.md)
- `/abcd:reflect` — phase retrospective (per itd-24) — see [`04-surfaces/09-reflect.md`](../04-surfaces/09-reflect.md)

**Operator-internal commands** (wiring under `commands/abcd/`, NOT part of the user-facing surface above): `/abcd:run` — the itd-29 autonomous-run operator surface (`status`/`pause`/`resume`/`preflight`; read-mostly over the pluggable autonomous-run seam ([adr-27](../../decisions/adrs/0027-autonomous-run-pluggable-seam.md)), v1 never starts or kills the loop). See [`04-surfaces/README.md`](../04-surfaces/README.md) for the user-facing-vs-operator-internal boundary.

**Thirteen phased intents — ten standalone plus three disciplines:**
- **Standalone (10):** itd-2, itd-3, itd-4, itd-6, itd-7, itd-27, itd-28, itd-34, itd-36, itd-40.
- **Disciplines (3):** itd-1 (acceptance gates), itd-5 (prompt-quality + capability_scope per idea-4), itd-37 (modification grammar per ideas 2+3). Disciplines have no user moment; they impose acceptance gates on every other spec per the three-kinds taxonomy in [`01-product/03-mental-model.md`](03-mental-model.md) and itd-34.
**Phased intents — derived, never hand-counted here.** The intents each phase
bundles are named in that phase doc's `## Scope` section — the single source of
the mapping ([adr-9](../../decisions/adrs/0009-phase-as-product-layer.md)); the
phased set is the union across the seven phase docs, and this page keeps no
static copy of it (a hand-kept count re-drifts the moment a phase doc changes,
the same failure the roadmap dashboard avoids by deriving counts from disk).
The set spans two of the three kinds: standalone capabilities, plus the three
disciplines (itd-1 acceptance gates, itd-5 prompt-quality + capability_scope,
itd-37 modification grammar) — disciplines have no user moment; they impose
acceptance gates on every other spec per the three-kinds taxonomy in
[`01-product/03-mental-model.md`](03-mental-model.md) and itd-34.

See [`phases/README.md`](../../roadmap/phases/README.md) for the phase plan and each phase's intent scope, and [`intents/README.md`](../../intents/README.md) for the intent index. itd-27 (`/abcd:intent grill` sub-verb), itd-28 (spec-tied RP reviews), and itd-34 (three intent kinds) were captured post-brief on 2026-05-07. itd-36 (memory unification) and itd-37 (modification grammar) were captured on 2026-05-08 following adversarial RP review of four candidate ideas (LLM Wiki, Naur theory-building, systems thinking, jagged frontier); itd-40 (folder classification) was captured 2026-05-16.
See [`phases/README.md`](../../roadmap/phases/README.md) for the phase plan and each phase's intent scope, and [`intents/README.md`](../../intents/README.md) for the intent index. Capture history lives in `git log` and each intent file's own provenance, never in this page (per [adr-5](../../decisions/adrs/0005-brief-is-current-state.md)).

**Plumbing infrastructure** (15 agents, 11 adapters, harness shim, prompt-quality stack, hooks): see [`05-internals/`](../05-internals).
**Plumbing infrastructure** (16 agents — the canonical roster is the catalog in [`05-internals/01-agents.md`](../05-internals/01-agents.md) — 11 adapters, harness shim, prompt-quality stack, hooks): see [`05-internals/`](../05-internals).

## What comes in a later phase

**All later-phase items live as press-release intents** in `.abcd/development/intents/drafts/`. The canonical out-of-scope list is at [`06-delivery/03-out-of-scope.md`](../06-delivery/03-out-of-scope.md).
**Later-phase items live as press-release intents** — the uncommitted bench in `.abcd/development/intents/drafts/`, plus the committed-but-unscheduled intents in `planned/` (per [adr-34](../../decisions/adrs/0034-lifecycle-and-scheduling-orthogonal.md)). The canonical out-of-scope list is at [`06-delivery/03-out-of-scope.md`](../06-delivery/03-out-of-scope.md).

The later-phase set is the live `drafts/` corpus minus the intents already scoped into a planned phase; it is enumerated — and kept non-drifting via a filesystem-derived command rather than a hand-count — in the canonical [`06-delivery/03-out-of-scope.md`](../06-delivery/03-out-of-scope.md). itd-31 and itd-32 are superseded (preserved as historical record in `intents/superseded/`).
The later-phase bench is the live `drafts/` corpus (per adr-34 no phase-scoped intent lives there, so nothing is subtracted); it is enumerated — and kept non-drifting via a filesystem-derived command rather than a hand-count — in the canonical [`06-delivery/03-out-of-scope.md`](../06-delivery/03-out-of-scope.md). itd-31 and itd-32 are superseded (preserved as historical record in `intents/superseded/`).

Each intent captures the press-release-shaped scope and acceptance criteria. A later-phase intent enters work by being scoped into a phase, then promoted to `planned/` via `/abcd:intent plan <itd-N>` and to `shipped/` via `/abcd:intent ship <itd-N>` (or automatically when the linked spec closes).

Expand Down
4 changes: 2 additions & 2 deletions .abcd/development/brief/04-surfaces/02-disembark.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# `/abcd:disembark` — Pack a Lifeboat

> **Status:** design target — builds in Phase 4 (the lifeboat pipeline). Today only the probe / dry-run stubs ship (spc-17); the full flow below is not yet built.
> **Phase ownership** ([adr-33](../../decisions/adrs/0033-launch-phase-ownership-tiered.md)): the lifeboat round-trip — disembark packing and embark unpacking — ships in [Phase 6](../../roadmap/phases/phase-6-lifeboat.md).

> **Recovery humility.** Disembark packs the highest-fidelity proxy of the project's theory we can leave behind. It is not the theory. The theory of any non-trivial project lives in the people who built it, the conversations where decisions were made, and the alternatives they rejected before this one — what Naur (1985) called the lived activity of building. The lifeboat is the floor we can carry forward across a session, machine, or team boundary; it is not the activity itself. See [`01-product/03-mental-model.md § The Naurian gap`](../01-product/03-mental-model.md#the-naurian-gap) for the framing.

Expand Down Expand Up @@ -109,7 +109,7 @@ Pass B's chat-distiller is exempt (already streams by per-spine-entry queries).
│ └── code-principles.{json,md} # from code-rescuer
├── docs/
│ ├── adrs/ # verbatim ADR copies
│ ├── terminology.md # rendered from .abcd/development/foundation/terminology/<context>/<term>.md (per itd-27 / spc-3)
│ ├── terminology.md # rendered from .abcd/development/brief/glossary/<context>/<term>.md (per itd-27 / spc-3, adr-30)
│ ├── claude-md-snapshot.md
│ └── tutorials/ guides/ reference/ explanation/ # verbatim from source docs/
├── assets/
Expand Down
2 changes: 1 addition & 1 deletion .abcd/development/brief/04-surfaces/03-embark.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# `/abcd:embark` — Unpack a Lifeboat

> **Status:** design target — builds in Phase 5 (round-trip and ship). Today only the probe / scan stubs ship (spc-17); the full flow below is not yet built.
> **Phase ownership** ([adr-33](../../decisions/adrs/0033-launch-phase-ownership-tiered.md)): the lifeboat round-trip — disembark packing and embark unpacking — ships in [Phase 6](../../roadmap/phases/phase-6-lifeboat.md).

> **Recovery humility.** Embark unpacks the lifeboat into a working repo. The lifeboat is the highest-fidelity floor the originating session could leave behind; it is not the activity that produced it. **When something here doesn't make sense, hunt the originating session before trusting the lifeboat blindly** — ask the prior author, surface the chat where the decision happened, look at the rejected alternatives. The lifeboat is a starting point, not an oracle. See [`01-product/03-mental-model.md § The Naurian gap`](../01-product/03-mental-model.md#the-naurian-gap) for the framing.

Expand Down
Loading
Loading