The product-thinker README (README.md) is written to the person who holds the why. This page is written to you — the person who turns that why into work AI coding agents can act on, runs the framework's audit and review machinery, and tells the product thinker honestly when delivered reality didn't match the promise.
You are a translator, not an engineer-on-the-team in the traditional sense. The product thinker brings purpose, scope, vocabulary, and judgement about done. You bring fluency with the framework, the tools, and the AI agents that do the building. abcd is the connective tissue between the two roles.
Contents:
- Your role, in detail
- Installing abcd in a project
- Bootstrapping the brief
- Deriving disciplines and plumbing from the brief
- Three intent kinds, and when to use each
- Acceptance criteria as a hard gate
- The fidelity reviewer: roles and verdicts
- Reclassification and supersession
- Lifeboat, launch, and the audit substrate
The product thinker writes two things: intents (the why for each user-facing change) and the brief (the project's shared canvas). Everything else, you derive, encode, run, or read on their behalf.
| Activity | You |
|---|---|
| Brief — bootstrap, structure, maintain | drive |
| Intent acceptance criteria — sharpening | review and tighten with /abcd:intent grill |
Intent → epic — /abcd:intent plan |
drive (calls /flow-next:plan) |
| Cross-cutting concerns implied by the brief | derive and encode as kind: discipline intents |
| Background plumbing implied by the brief | scope and plan as plumbing epics |
AI coding execution — /abcd:intent ship |
drive (calls /flow-next:work) |
| Fidelity review — Role 1 (single-doc) | inspect any NOT_MET / INCONCLUSIVE verdicts |
| Cross-document fidelity — Role 2 | run periodically; act on findings |
| Kind classification — Role 3 | run periodically; reclassify when needed |
| Lifeboat / launch / audit | drive end-to-end |
Your fluency with /flow-next:*, /abcd:*, RepoPrompt, SpecStory, and the underlying Claude Code runtime is what makes the two-role team possible. You are the only person on the team who needs to know any of those.
Three onboarding paths:
| Situation | Command |
|---|---|
| Existing project; add abcd on top | /abcd:ahoy install (idempotent — covers first-install and upgrade) |
| Empty directory; create project shape + install abcd in one step | /abcd:init-project scaffold |
| Rebuilding from a lifeboat | /abcd:embark from <path> |
/abcd:ahoy install is reversible — uninstall removes the marker block from CLAUDE.md/AGENTS.md and the symlink, but does NOT remove .abcd/. Re-running install re-installs cleanly. The destroy sub-verb is the nuclear option: removes abcd-managed files, lifeboat artefacts, and coordination state.
Full command surface in commands.md. Onboarding decision tree in the reference index.
The brief is the project's shared canvas — always-current state, never re-versioned. It lives at .abcd/development/brief/ with surfaces split by concern:
01-product/— press release, context, mental model, scope, personas02-constraints/— what the project won't do, and why03-evidence/— what's been validated and what's still a hypothesis04-surfaces/— command-by-command surface contracts05-internals/— implementation patterns, skill conventions06-delivery/— release sequencing and milestones
The product thinker rarely writes directly into these files. Instead, you and they bootstrap the brief through a discovery → ingest → sharpen loop:
- Discovery (outside abcd). The product thinker has stakeholder conversations — recordings, notes, a Stoa workspace, transcripts, slide decks. Multi-modal, plural-voice, often messy. abcd doesn't try to own this stage.
- Ingest into a draft. A skill (forthcoming) takes that discovery material and produces a plain-language draft of the brief — readable by a stakeholder, not just an engineer. Plain language is the load-bearing constraint here: if a non-engineer can't read it, it's not a brief.
- Sharpen with
/abcd:intent grill --brief-section <id>. The Socratic-questioning sub-verb stress-tests the draft, surfacing fuzzy terms, premise contradictions, and unstated assumptions. Glossary terms get written inline toterminology/. The product thinker drives the answers; you drive the question loop. - Iterate. As intents land and reality ships, the brief gets edited in place. Vocabulary additions, scope refinements, invariant updates — all in the same files. The brief is never re-versioned; there is no second copy in a sibling folder.
Your job during this loop: protect the plain-language constraint. If a draft starts using framework jargon, push back. The brief has to remain readable by a stakeholder who has never seen abcd.
The product thinker writes intents and the brief. They do not write disciplines or plumbing — those emerge from your reading of the brief.
Disciplines are cross-cutting rules every other epic must satisfy. They have no user moment of their own. Examples:
- "Every screen must pass an accessibility checklist before shipping."
- "Every user-facing feature involving personal data must include a privacy-impact review."
- "Every prompt change must be versioned and traceable."
You recognise the need for a discipline by reading the brief — particularly 02-constraints/ and 01-product/04-scope.md. When you spot one, you capture it as a kind: discipline intent. It never gets its own epic; it becomes an inherited gate every other epic must clear (mechanically enforced via pre-commit hooks and intent_lint.py).
Plumbing is background capability that enables user-facing work but has no user moment of its own. Examples:
- "Set up a Stripe integration for the loyalty-card checkout."
- "Build the shared logging substrate that all features will write to."
- "Migrate from SQLite to Postgres before scaling tests."
Plumbing skips the intent surface entirely (no press release — there's no user moment to describe) and goes straight to a build plan via /flow-next:plan. It still passes through the discipline gate. The brief documents why the plumbing exists (which user-facing capability it enables); the epic plan documents how it's built.
Both disciplines and plumbing are your judgement calls. The product thinker doesn't have to recognise the difference — they just describe what the project is for, and you do the structural work.
At /abcd:intent plan time, every intent is classified into one of three kinds.
One user moment, one epic. The default path. Lifecycle:
draft → /abcd:intent plan → /flow-next:plan → planned → /abcd:intent ship → /flow-next:work → shipped → fidelity review
The README's lifecycle diagram is the standalone path.
Two or more intents that only make sense delivered together. They share one engineering effort and one fidelity review pass (per member, against the same delivered reality).
Use when:
- Removing one member would invalidate the others' acceptance criteria
- The user moments are coupled (e.g., "add to cart" and "remove from cart" shipped together)
- The engineering work cannot be cleanly split
Use the multi-arg form: /abcd:intent plan itd-A itd-B itd-C. This calls /flow-next:plan once with all intents as joint input, creates one shared epic with intent: [itd-A, itd-B, itd-C], and writes bundle: <id> into each member's frontmatter.
A cross-cutting rule with no user moment. Lives in disciplines/ indefinitely. Has no ship step; the file existing in disciplines/ is its activation. The discipline's acceptance criteria become an inherited gate every other epic must satisfy.
The interview captures ## Rule and ## Why (not a press release) plus Given/When/Then acceptance. /abcd:intent plan itd-N followed by user-selected kind: discipline registers the acceptance gates in .abcd/disciplines/itd-N.json and runs /flow-next:plan-review against the rule.
Every intent declares acceptance criteria in plain Given / When / Then language. This is enforced by intent_lint.py at /abcd:intent plan time — no draft is promoted to planned/ until the criteria are well-formed. The discipline that enforces this rule is itself an intent (acceptance gates).
Internal abcd example (good):
Given an empty
drafts/directory, when the user runs/abcd:intent new "foo", then a filedrafts/itd-N-foo.mdexists with frontmatter populated, and nostatus:field is present (directory location is the canonical lifecycle state).
Internal abcd example (bad — too vague):
Given the user wants to capture an idea, when they capture it, then it's stored well.
The acid test for any acceptance bullet: could the fidelity reviewer, reading only the bullet and the shipped repo, write [MET] or [NOT_MET] next to it without asking the author what they meant? If yes, the bullet is doing its job.
When a draft fails the lint, /abcd:intent grill <itd-N> is the right next step — it stress-tests the criteria with sharp questions until they're tightenable. /abcd:intent refine <itd-N> is the gentler, user-driven alternative for editing without adversarial pressure.
intent-fidelity-reviewer is the agent that closes the loop between why and delivered reality. It has three roles, run by three different verbs.
Compares one shipped intent's press release and acceptance criteria against the actual repository (code, configs, docs, tests). Each acceptance bullet gets one of four verdicts:
| Verdict | Meaning |
|---|---|
MET |
Delivered as promised. |
MET_WITH_CONCERNS |
Delivered, but the reviewer flagged something worth attention (subtle behaviour change, performance regression, missing test, edge case glossed). |
NOT_MET |
The promise wasn't kept. |
INCONCLUSIVE |
The reviewer couldn't tell from what's in the repo (insufficient observability, ambiguous criterion, test gap). |
INCONCLUSIVE is load-bearing: it lets the reviewer fail honestly. "I couldn't verify this" is a different signal from "this didn't ship," and abcd insists on the distinction. When you see one, your job is to either improve the criterion (so a future review can grade it) or improve the repo (so the answer becomes verifiable).
Auto-fires on the planned → shipped transition via intent_lifecycle_hook (event-driven, watches .flow/specs/ for status: done). The verb is the manual rerun.
Surfaces drift across the corpus: terminology drift, premise contradictions, scope leakage, sequencing impossibilities, naming conflicts. Bare = scan the whole corpus; <itd-N> argument = scan one intent against the rest.
Run periodically (weekly cadence is a reasonable default). Findings are advisory — they suggest reclassifications or brief edits, but don't auto-apply.
Examines whether each intent's declared kind still fits the corpus. Surfaces reclassification suggestions: "itd-12 was captured as standalone but is now coupled to itd-15 — consider bundle-member," or "itd-7 is being applied as a cross-cutting rule across three epics — consider discipline."
Runs continuously in pre-commit; the verb is the on-demand surface.
When a fidelity review (any role) surfaces a finding that requires acting on it, /abcd:intent reclassify <itd-N> is the action verb.
| Path | Command | Effect |
|---|---|---|
| Late kind change | --kind <new-kind> --reason <text> |
Moves file between directories; appends reclassification_history entry to frontmatter |
| Supersession | --kind superseded --by <itd-M> |
Moves to superseded/; writes superseded_by: itd-M and kind_at_supersession: <kind> |
Reclassify can run at any lifecycle state. Supersession preserves the historical record — the file isn't deleted, just moved. Directory location is the canonical lifecycle state, and reclassification is the move.
abcd projects can pack their full state into a portable rebuild seed (a lifeboat), promote a private dev repo to a public sibling (launch), and verify any artefact's tamper-evidence chain (audit). All three share a JCS + UUIDv7 + Merkle substrate.
/abcd:disembark to <path> packs the project's brief, intents, decisions, code seeds, and audit chain into a portable artefact. /abcd:embark from <path> is the mirror — unpack into an empty repo on a fresh account or machine. Use home as shorthand for the current repo's .abcd/lifeboat/ (round-trip case).
The lifeboat is a regenerable output, not a source artefact: the source of truth is always .abcd/development/, and the lifeboat is a distillation. If a lifeboat goes stale, repack it.
probe and dry-run sub-verbs let you inspect what would happen without writing anything.
Promotes a private dev repo to its public sibling, gated by a launch-gatekeeper pre-flight: PII scan, secret scan, payload manifest, doc audit. The gate is reversible (relax with --allow-dirty or --allow-doc-warnings) but the defaults are strict.
--mode controls the public payload shape: overlay (merge into existing public), clean (replace), or branch (stage on a branch first).
Compliance-grade tamper-evidence umbrella. The default sub-verb is chain — Merkle audit of the project's conversation and edit history end-to-end. lifeboat <path> verifies a lifeboat artefact's integrity outside the embark flow (compliance spot-check).
The substrate (JCS canonicalisation, UUIDv7 IDs, Merkle aggregation) is shared across all audit applications. Future audit kinds register as new sub-verbs.