A host-agnostic configuration layer for intent-driven development.
"This book has only one major purpose—to trigger the beginning of a new field of study: computer programming as a human activity"
—Gerald M. Weinberg, The Psychology of Computer Programming, 1971
AI coding is getting more powerful, yes one important group of people who most need that power — the domain experts, the product thinkers, the people who actually know what should be built — are currently underserved to be able to use AI coding directly. abcd's bet is that a small team of two roles can close that gap: A product thinker who holds the why, and a facilitator who translates the why into work that AI coding agents can act on.
abcd is being shaped by what real two-person teams discover as they use it. In the initial version, both roles — the product thinker and the facilitator — are human. In a later version, abcd aims to offer an automated facilitator, so a product thinker can run the framework with an AI translator alongside their agentic team of AI-engineers.
As a product thinker, you know who the user is. You know what done looks like when you see it. You know which trade-offs are acceptable and which would betray the point of the project. abcd is built around two moments where that judgement is decisive. First, at the start of a piece of work (when you set the why as an intent), and at the end (when you read the verdict on whether the why was delivered). What happens in between — turning your why into engineering work AI agents can act on — is the facilitator's job.
The facilitator is a translator, not an engineer-on-the-team in the traditional sense. Their work is to take what you wrote, shape it into plans an AI coding agent can execute well, run the framework's audit and review machinery, and tell you when the work didn't match the promise (and what to do about it).
| Product thinker | Facilitator | |
|---|---|---|
| The brief — what is this project about? | bring the substance | shape it into the brief structure |
| Capturing an intent — why does this change matter? | write the press release | sharpen the acceptance criteria |
| Turning the why into engineering work | — | drive |
| Cross-cutting concerns the brief implies | — | derive and encode |
| Reading the verdict when work ships | read; decide what to do next | investigate any not delivered findings |
The product thinker and facilitator collaborate on artefacts that are jointly owned, with others generated and consumed autonomously by the AI-engineering team. Two of them — an initial briefing document and a set of articulated intents — are familiar territory for product thinkers; abcd builds on them, and adds a third, to carry intent through to delivered reality.
-
The brief (owned jointly by the product thinker and the facilitator) answers what is this whole thing about? — purpose, scope, the vocabulary the project uses, what "good" looks like. It makes one hard promise: Everything it says reads true right now. On day one, when the team has agreed a design but built nothing, most of the brief is ambition — and every ambitious passage is visibly marked as not yet real. As work ships, those markings come off one by one: the change that ships a capability also rewrites its passage in the brief to describe what actually exists (which is rarely word-for-word what was planned). The brief is never re-versioned and keeps no history — version control does that — so it earns its role as the project's living canvas one shipped change at a time.
-
Intents (user-facing, and thus the product thinker's domain) answer why does each user-facing change matter? Each is a one-page press release written as if the change had already shipped, with a named user feeling the difference, plus acceptance criteria in plain Given / When / Then language. Intents are how ambition travels into the brief: An intent is drafted, planned into engineering work, and built — and the same change that ships it updates the brief. Once its acceptance criteria are verifiably met, the intent is filed as shipped and becomes the permanent record of the why; the brief carries the what is; the engineering spec carries the how. Intents are individually portable: Each stands on its own and can be reordered, deferred, bundled, or dropped without rewriting the bigger picture.
-
Automated reviews (owned by the AI-engineering team) grade delivered reality against the original promise. When work lands, a fidelity review reads each acceptance bullet against the actual repository and writes its verdict back onto the intent itself — so the why and the did-we-deliver-it live side by side, in one file, for as long as the project does.
Some things the project needs aren't user-facing — cross-cutting rules every feature must satisfy (e.g., a privacy review, an accessibility checklist), or background plumbing that enables other capability. Those skip the press-release treatment and go straight into the brief, under the same promise: Real, or visibly marked as not yet real. As a product thinker you don't have to recognise or label them — that's your facilitator's job.
It starts with the brief. You sit down with your facilitator and whatever discovery material you have — recordings, notes, a shared workspace, a half-finished slide deck, a transcript of yesterday's stakeholder call. abcd has a skill that ingests that material and produces a plain-language draft of your project's brief; the parts that feel fuzzy, you sharpen together with a Socratic interview the framework provides. By the end of the session you have a brief that says — in language a stakeholder would recognise — what this project is about. Much of it is ambition rather than fact at this stage, and that's fine: The brief never bluffs, so those passages are marked accordingly.
Ideas become intents. From then on, whenever an idea arrives, capturing it is one line:
abcd intent "<one-line idea>"Your facilitator helps sharpen the press release and its acceptance criteria — the criteria are a hard gate, not a suggestion — then turns the intent into engineering work, surfaces the cross-cutting concerns it implies, and lets AI coding agents do the building. You stay in the seat where your judgement matters most: Setting the why at the start, and reading the verdict at the end.
Shipping closes the loop twice. When the work lands, the fidelity review grades each acceptance bullet against the actual repository — the code, the configs, the tests, the docs — and writes the verdict onto the intent. And the same change updates the brief: The passage covering this capability loses its not-yet-real marking and is rewritten to describe what actually shipped. That second half is what keeps the brief honest — the true description of your project, one shipped change at a time, instead of a wish list nobody trusts.
╭─────────────────────╮
│ Half-formed idea │ ◄─────────────────────────┐
╰─────────────────────╯ │
│ │
▼ │
┌─────────────────────┐ │
│ Capture as a │ │
│ press release — │ │
│ what does the │ │
│ user feel after │ │
│ this ships? │ │
└─────────────────────┘ │
│ │
▼ │
┌─────────────────────┐ │
│ Add acceptance │ │
│ criteria — how │ │
│ will we tell, on │ │
│ the day, whether │ │
│ it was delivered? │ │
└─────────────────────┘ │
│ │
▼ │
┌─────────────────────┐ │
│ Refine / grill — │ │
│ stress-test the │ │
│ why and the │ ◄─────────┐ │
│ criteria until │ │ │
│ both are clear │ │ not yet │
└─────────────────────┘ │ clear enough │
│ │ │
▼ │ │
╱───────────╲ │ │
╱ Ready to ╲ ── No ─────────┘ │
╲ build it? ╱ │
╲───────────╱ │
│ Yes │
▼ │
┌─────────────────────┐ │
│ Facilitator turns │ │
│ the intent into │ │
│ engineering work; │ │
│ AI agents build it │ │
└─────────────────────┘ │
│ │
▼ │
┌─────────────────────┐ │
│ Fidelity review │ │
│ reads each │ │
│ acceptance bullet │ │
│ against the actual │ │
│ shipped repo │ │
└─────────────────────┘ │
│ │
▼ │
┌─────────────────────┐ │
│ Shipped — verdict │ next idea │
│ on the intent; the │ ─────────────────────────►┘
│ brief passage is │
│ rewritten to what │
│ now exists │
└─────────────────────┘
Acceptance criteria for each intent use three words to describe a checkable outcome.
| What it pins down | |
|---|---|
| Given | The starting state — what's already true before anything happens. |
| When | The trigger — a single user or system action. |
| Then | The observable outcome — something a human (or the fidelity reviewer) can check by looking at the result, not by reading the author's intent. |
The reviewer is allowed to fail honestly. If a promise wasn't kept, it says so. If something was delivered but with a wrinkle worth your attention, it flags the wrinkle rather than glossing it. And if it genuinely couldn't tell from the repo, it says that — which is different from saying the promise wasn't met, and abcd insists on the distinction.
While intents are at the core of abcd, you will sometimes find that a thought that feels relevant crosses your mind — a half-formed observation, a question for the team, a doubt about the brief, a behaviour you'd expect a user to notice — and you don't want to lose it. Instead of articulating an intent, abcd has a fast hatch for capturing it:
abcd capture "<whatever crossed your mind>"One line, deliberately shaped like intent capture but for un-typed thoughts: abcd capture writes one small record into the repo's issue ledger (.abcd/work/issues/open/), minted with the next free id. Everything else — severity, category, where it was found — has sensible defaults, so you don't have to decide anything beyond the text itself at this stage.
abcd capture essentially decouples retention from classification. Intents demand press-release discipline — a named user, acceptance criteria, a why. Forcing a half-formed doubt through that discipline either kills the thought (too much ceremony, you let it go) or pollutes the intent corpus (you file something vague to avoid losing it). The fast hatch makes retention almost free — seconds, zero decisions — and defers the "what is this?" question to someone in the right seat at the right time.
That "someone" is your technical facilitator, who triages those captures later: They sweep the open captures and route each one — a bug gets fixed (finding first, fix after); a feature seed gets promoted into an intent draft; a doubt about the brief becomes a brief correction; a deliberate non-action goes to wontfix with the reasoning recorded, so the question never gets re-litigated.
One line, checksum-verified, no administrator rights. It detects your
OS/architecture, downloads the binary and the checksums.txt manifest from the
latest release, verifies the binary's SHA-256 against the manifest (and refuses
to install on any mismatch — or if the manifest doesn't list the binary at all),
then installs to ~/.local/bin, the single-user location:
sh -c 'set -eu; cd "$(mktemp -d)"; os=$(uname -s | tr "[:upper:]" "[:lower:]"); arch=$(uname -m); case "$arch" in x86_64) arch=amd64;; aarch64) arch=arm64;; esac; b="abcd-$os-$arch"; curl -fsSLO "https://github.com/REPPL/abcd-cli/releases/latest/download/$b"; curl -fsSLO "https://github.com/REPPL/abcd-cli/releases/latest/download/checksums.txt"; grep " $b$" checksums.txt | if command -v sha256sum >/dev/null; then sha256sum -c -; else shasum -a 256 -c -; fi; mkdir -p "$HOME/.local/bin"; install -m 0755 "$b" "$HOME/.local/bin/abcd"; "$HOME/.local/bin/abcd" version'If abcd isn't found by name afterwards, ~/.local/bin isn't on your PATH.
Add this line to your shell profile:
export PATH="$HOME/.local/bin:$PATH"abcd ahoy reports the same thing as a named gap with the same one-line fix,
and the installer writes its own PATH entry to ~/.local/bin unless you
point it elsewhere with --bin-dir. abcd never escalates privileges: a
directory it can't write to is an error, not a prompt for your password.
Already have an abcd in a system directory from an earlier install? Delete it
(rm /usr/local/bin/abcd, with whatever rights put it there) — otherwise it
comes first on PATH and keeps answering instead of the new one. abcd ahoy
names it in a gap rather than removing it: abcd does not touch a binary it does
not own.
Prefer to inspect before running? The command is exactly what it says: two
downloads from the latest release,
a checksum verification, and a copy into a directory you own. You can do the
same by hand — grab the binary for your platform plus checksums.txt from the
releases page, run shasum -a 256 -c (or sha256sum -c) against the matching
line, and copy the binary anywhere on your PATH. Every release is built and
published by CI from the exact tagged commit, with the checksums generated
over the same bytes that are uploaded.
This repository is also its own plugin marketplace, so a compatible agent
harness can install the /abcd:* surface — the commands under
commands/, the agents under agents/ and the hook
wiring in hooks/ — straight from it. Add the marketplace, then
install the plugin:
/plugin marketplace add REPPL/abcd-cli
/plugin install abcd@abcd-marketplace
abcd-marketplace is the marketplace name declared in
.claude-plugin/; abcd is the single plugin it lists,
sourced from the repository root. Pull the current state of the marketplace with:
/plugin update abcd
The marketplace is served from the repository itself, so an install tracks the
repository rather than a versioned artefact: the manifests here carry no version
key, and a release publishes the abcd binaries and their checksums, alongside
the source archives GitHub attaches for the tagged tree.
The plugin provisions its own binary. This repository commits none, and every
plugin update lands in a fresh cache directory, so a plugin root starts empty
each time: hooks/bootstrap.sh runs first at session
start, downloads the release binary for this platform along with
checksums.txt, verifies the binary's SHA-256 against the manifest, and
installs it into the plugin root. A mismatch, a manifest that doesn't list the
platform, or a platform outside the released matrix (darwin and linux on amd64
and arm64) installs nothing and says why in plain language. A plugin root that
already holds the binary costs one file test and no network.
That covers the hooks. For the abcd command in your own terminal, keep the
install above, or put the plugin-root binary on your PATH by
running it once by its absolute path — '<plugin-root>/abcd' ahoy install.
The path is absolute because abcd is not on your PATH yet, which is what
that one run fixes. <plugin-root> is the directory the agent harness unpacked
the abcd plugin into, with the binary sitting directly inside it as abcd; the
bootstrap's success notice prints that full binary path, so the shortest route
is to copy the command straight out of the notice. That notice appears once per
plugin root — later sessions take the fast path and stay silent — so if it has
scrolled away and you would rather not go looking for the directory, the
install one-liner above needs no plugin root at all and gets you to
the same place.
For a stronger root of trust than same-origin checksums, build from source —
go build ./cmd/abcd — and place the binary in the plugin root and on your
PATH yourself. A binary placed there by hand takes the same no-network fast
path, so the .binary-meta provenance record beside it still describes
whichever release the bootstrap last fetched: delete that file so no
version-skew notice is rendered from a release the binary in place did not come
from.
make preflight # the pre-push gate: lint-reviews, record-lint and docs-lint,
# then build, vet, test and race (internal)
go run ./cmd/abcd # bare status board for the current directory
go run ./cmd/abcd version # print the version
make build # cross-compile bin/abcd-<goos>-<arch>cmd/abcd/— CLI entry point.internal/— the engine (core/) and front doors (surface/); seeinternal/README.md.commands/,.claude-plugin/— the plugin surface (auto-loaded)..abcd/— the development record and working files (present in every repository checkout, marketplace installs and release source archives included; never in the released binaries).
Contributor guidance: AGENTS.md.