abcd

module

v0.6.7 Latest Latest Go to latest Published: Aug 27, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/intentdriven/abcd

Links

Open Source Insights

README ¶

Agent-Based Configuration for Development

A host-agnostic configuration layer for intent-driven development.

What it is for

abcd is for people who know what they want to build and need help shipping it. While agents are good at producing work, they're not very good at remembering why it was built: What was decided, what was rejected, and on what evidence. All of that reasoning lives in transcripts nobody reads.

abcd keeps that reasoning as structured records agents and humans do read: The intent that says what shipping looks like, the decision that says what was chosen and what was refused, the specification, and the issue ledger. They are plain files in the repository, checked by gates that refuse rather than warn, so what these records claim about the product stays true as the product moves.

How it works

Two mechanisms carry the record into the work:

Rules reach the agent selectively. On each prompt a hook matches what you typed against the keyword triggers every rule domain declares, and injects only the domains that matched: A prompt about committing gets the commit conventions, and a prompt that matches nothing adds no tokens at all.

Gates refuse rather than warn. A warning is advice, and advice is what a hurried author skips. The gates run before the push leaves the machine, and they stop it:

$ git push
check-issue-resolution: RS001 commit c1e2c4c3d915 declares 'Resolves: iss-317', but iss-317 does not enter .abcd/work/issues/resolved/ or .abcd/work/issues/wontfix/ in origin/main..HEAD. Resolve it in this change (abcd capture resolve iss-317 ...) or drop the trailer.
check-issue-resolution: FAILED — 1 violation(s)

Built in the open

abcd is built with abcd, and its own record is public and complete: Every decision, intent, specification and issue, from the first commit onward, with the reasoning attached.

That record is the demonstration. It is not a claim that the approach works but the trail of a real product being built this way, including the parts that were wrong: Reversed decisions, abandoned designs, and defects found by the gates and recorded before they were fixed.

You can interrogate abcd's development process at abcdev.app/record/, alongside more details on who abcd is for, roles, artefacts and the process.

At this stage, abcd remains experimental, and you should expect the surface to keep moving: Verbs change, and the plugin surface currently targets a single harness (the command-line app is host-agnostic and runs in any repository with no harness at all). What's not experimental is the record.

Requirements

Only the first of these applies to every use; the rest are scoped to one route.

Git: Always. abcd shells out to the git binary and anchors every record it keeps to a repository.
A released platform: macOS or Linux, on amd64 or arm64. Windows runs the Linux route inside WSL.
An agent harness: The plugin route and the verbs that hand their work to a model, and nothing else. The deterministic verbs need no harness, and the command-line app runs in any repository without one.
curl and a SHA-256 tool: The CLI one-liner below only. It fetches over HTTPS and checks the binary against the release's checksums.txt with sha256sum or shasum.
Go 1.26 or later: A source build only. Both install routes provision a prebuilt binary, so installing abcd needs no Go toolchain.

Install

The easiest route to get started is to install abcd as a Claude Code plugin.

Run these two from a session in that harness. The first registers this repository as a plugin marketplace; the second installs abcd from it.

/plugin marketplace add intentdriven/abcd

Wait for the confirmation that the marketplace was added, then:

/plugin install abcd@abcd-marketplace

Restart the session afterwards so the hooks load, then check what you got:

/abcd:version

Later, /plugin update abcd pulls the marketplace's current state.

As a CLI

Support for other harnesses will follow. If your harness isn't supported yet, abcd runs from a terminal in any repository, with no harness involved:

sh -c 'set -eu; unset HTTPS_PROXY https_proxy HTTP_PROXY http_proxy ALL_PROXY all_proxy CURL_HOME CURL_CA_BUNDLE SSL_CERT_FILE SSL_CERT_DIR; 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 -q --proto =https --proto-redir =https -fsSLO "https://github.com/intentdriven/abcd/releases/latest/download/$b"; curl -q --proto =https --proto-redir =https -fsSLO "https://github.com/intentdriven/abcd/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'

Checksum-verified, no administrator rights, installs to ~/.local/bin. The install guide covers building from source and what to do when abcd isn't found afterwards. Consult the verb reference for what abcd can do.

First run

Point abcd at a repository you care about and ask where you are. The status board is read-only, so it is safe on any tree:

$ abcd
abcd — /path/to/your-repo
  git repo:   true
  record:     true
  work tiers: [development work work.local]

The plugin surface adds three commands the CLI does not carry, all host-delegated markdown with no Go verb behind them. The one that matters first: /abcd:prepare-this-repo gives a repository with no record yet the three-tier .abcd/ layout, an AGENTS.md router, and the commit gates. (/abcd:consult and /abcd:ingest drive a local sources corpus.)

From there, three verbs cover most of a first session. In a plugin session, /abcd:lint checks the repository against the working conventions and names what is missing. /abcd:capture "…" files a half-formed observation to the issue ledger so it survives the session that noticed it. /abcd:intent "…" opens a user-facing change as a press-release intent, which is where a shipping change starts.

The verb reference lists the rest.

Citation

If you use abcd in your work, please cite it. The form below is rendered from CITATION.cff, which is the record GitHub's own Cite this repository button reads:

@software{reppel_abcd,
  author  = {Reppel, Alex},
  title   = {{abcd}: {Agent-Based} {Configuration} for {Development}},
  url     = {https://github.com/intentdriven/abcd},
  license = {MIT}
}

Resources

SECURITY.md: Report a vulnerability privately.
ACKNOWLEDGEMENTS.md: The ideas, tools and writing abcd stands on.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
abcd command Command abcd is the CLI front door to the abcd engine.	Command abcd is the CLI front door to the abcd engine.
abcd-gen-cli-ref command Command abcd-gen-cli-ref writes the generated CLI reference page from the abcd command tree.	Command abcd-gen-cli-ref writes the generated CLI reference page from the abcd command tree.
abcd-gen-surface command Command abcd-gen-surface writes the committed compatibility snapshot from the abcd command tree and the plugin manifests.	Command abcd-gen-surface writes the committed compatibility snapshot from the abcd command tree and the plugin manifests.
record-lint command Command record-lint is the deterministic drift gate for the abcd design record.	Command record-lint is the deterministic drift gate for the abcd design record.
scaffold-sync command Command scaffold-sync propagates the pinned action refs in the committed release workflows back into the scaffold templates they were rendered from, keeping TestSelfScaffoldParity satisfied after a dependency bump.	Command scaffold-sync propagates the pinned action refs in the committed release workflows back into the scaffold templates they were rendered from, keeping TestSelfScaffoldParity satisfied after a dependency bump.
internal
adapter/scanner Package scanner is abcd's native secret + PII detector.	Package scanner is abcd's native secret + PII detector.
core Package core is abcd's transport-agnostic engine.	Package core is abcd's transport-agnostic engine.
core/ahoy Package ahoy is abcd's install/update engine for `abcd ahoy`.	Package ahoy is abcd's install/update engine for `abcd ahoy`.
core/banlist Package banlist is abcd's two-layer banned-names store (itd-74, spc-20).	Package banlist is abcd's two-layer banned-names store (itd-74, spc-20).
core/capture Package capture is abcd's transport-agnostic issue-ledger engine: the write side of a per-repo issue ledger that replaces the free-form .work/issues.md.	Package capture is abcd's transport-agnostic issue-ledger engine: the write side of a per-repo issue ledger that replaces the free-form .work/issues.md.
core/changelog Package changelog is abcd's transport-agnostic release-derivation domain: the version and the changelog are facts derived from the records that shipped, not numbers and lines a human types (itd-73, spc-10).	Package changelog is abcd's transport-agnostic release-derivation domain: the version and the changelog are facts derived from the records that shipped, not numbers and lines a human types (itd-73, spc-10).
core/cite Package cite is the live half of the citation gate: the on-demand refresh that fetches every cited URL and writes the committed baseline the zero-network docs lint then enforces offline.	Package cite is the live half of the citation gate: the on-demand refresh that fetches every cited URL and writes the committed baseline the zero-network docs lint then enforces offline.
core/frontmatter Package frontmatter is abcd's shared markdown-frontmatter line scanner.	Package frontmatter is abcd's shared markdown-frontmatter line scanner.
core/glossary Package glossary derives the brief glossary's own index from the term files.	Package glossary derives the brief glossary's own index from the term files.
core/guard Package guard is abcd's transport-agnostic shell-hazard registry (itd-103, spc-16).	Package guard is abcd's transport-agnostic shell-hazard registry (itd-103, spc-16).
core/history Package history is abcd's native session-transcript store: the write/read/ redact engine that populates ~/.abcd/history/<root-sha>/transcripts/ and retires the specstory shim (adr-29).	Package history is abcd's native session-transcript store: the write/read/ redact engine that populates ~/.abcd/history/<root-sha>/transcripts/ and retires the specstory shim (adr-29).
core/ideate Package ideate is the deterministic frame around abcd's idea-admission protocol (itd-104, spc-18): the three-leg gauntlet an idea may be put through before it is allowed to become a record entry.	Package ideate is the deterministic frame around abcd's idea-admission protocol (itd-104, spc-18): the three-leg gauntlet an idea may be put through before it is allowed to become a record entry.
core/identity Package identity checks that the git author identity a commit would use in a managed repo matches the identity pinned in .abcd/config/identity.json.	Package identity checks that the git author identity a commit would use in a managed repo matches the identity pinned in .abcd/config/identity.json.
core/intent Package intent is abcd's transport-agnostic native intent store (intent lifecycle, itd-80).	Package intent is abcd's transport-agnostic native intent store (intent lifecycle, itd-80).
core/issueschema Package issueschema is the issue record's frontmatter schema as DATA: the one list of properties issue.schema.json marks required, held where every gate that asks the question can read it.	Package issueschema is the issue record's frontmatter schema as DATA: the one list of properties issue.schema.json marks required, held where every gate that asks the question can read it.
core/launch Package launch is abcd's transport-agnostic launch engine: it assembles the release bundle under a default-deny taxonomy, runs the native secret+PII scan, checks manifest lockstep, and previews newest-per-line retention — all as a dry-run that renders decisions without writing an artefact or touching the network.	Package launch is abcd's transport-agnostic launch engine: it assembles the release bundle under a default-deny taxonomy, runs the native secret+PII scan, checks manifest lockstep, and previews newest-per-line retention — all as a dry-run that renders decisions without writing an artefact or touching the network.
core/launch/scaffold Package scaffold renders and writes the changelog-driven release machinery — release.yml, auto-release.yml, and the adr-37 runbook — into a managed repo that lacks it (itd-93, spc-14).	Package scaffold renders and writes the changelog-driven release machinery — release.yml, auto-release.yml, and the adr-37 runbook — into a managed repo that lacks it (itd-93, spc-14).
core/lifeboat Package lifeboat holds the brief-to-lifeboat contract and, later, the source adapters that fill it.	Package lifeboat holds the brief-to-lifeboat contract and, later, the source adapters that fill it.
core/lint Package lint is abcd's record-drift gate: it reads a JSON config and lints the markdown design record, returning findings.	Package lint is abcd's record-drift gate: it reads a JSON config and lints the markdown design record, returning findings.
core/memory Package memory is abcd's transport-agnostic curated-knowledge substrate at .abcd/memory/ (itd-36 / adr-13).	Package memory is abcd's transport-agnostic curated-knowledge substrate at .abcd/memory/ (itd-36 / adr-13).
core/positioning Package positioning holds a repository's canonical self-description — its title, tagline, and elevator pitch — and the deterministic check that every rendered surface still says it.	Package positioning holds a repository's canonical self-description — its title, tagline, and elevator pitch — and the deterministic check that every rendered surface still says it.
core/record Package record is the read side of `abcd <id>`: dispatch on a record id — iss-N, itd-N, spc-N, adr-N — and report what the record is, its links, and the concrete next move for its lifecycle state (spc-26).	Package record is the read side of `abcd <id>`: dispatch on a record id — iss-N, itd-N, spc-N, adr-N — and report what the record is, its links, and the concrete next move for its lifecycle state (spc-26).
core/recordid Package recordid is abcd's canonical home for the record-id space: the native timestamp-numeric mint (mint.go), the read-side resolver (resolve.go), and the legacy max+1 allocator support this file keeps for the families that have not yet adopted the mint seam.	Package recordid is abcd's canonical home for the record-id space: the native timestamp-numeric mint (mint.go), the read-side resolver (resolve.go), and the legacy max+1 allocator support this file keeps for the families that have not yet adopted the mint seam.
core/release Package release is the transport-agnostic composition of a release cut: the deterministic half of `abcd launch ship` and the whole of `abcd changelog`.	Package release is the transport-agnostic composition of a release cut: the deterministic half of `abcd launch ship` and the whole of `abcd changelog`.
core/repolint Package audit is abcd's read-only repo-conformance engine: it evaluates a set of declarative rules against a repository and returns findings.	Package audit is abcd's read-only repo-conformance engine: it evaluates a set of declarative rules against a repository and returns findings.
core/rules Package rules is abcd's transport-agnostic modular rules loader (itd-3).	Package rules is abcd's transport-agnostic modular rules loader (itd-3).
core/site Package site is the home of the abcd site verb family (adr-47).	Package site is the home of the abcd site verb family (adr-47).
core/spec Package spec is abcd's transport-agnostic native spec store (intent lifecycle, itd-64).	Package spec is abcd's transport-agnostic native spec store (intent lifecycle, itd-64).
core/surface Package surface models abcd's public compatibility surface — the commands, flags, and manifest entries a consumer can bind to — as a transport-agnostic value that is snapshotted, committed, and diffed between releases (itd-73, spc-10).	Package surface models abcd's public compatibility surface — the commands, flags, and manifest entries a consumer can bind to — as a transport-agnostic value that is snapshotted, committed, and diffed between releases (itd-73, spc-10).
core/update Package update implements the core of `abcd update` (itd-130 / spc-32): a user-invoked fetch/verify/swap for the PATH-installed binary.	Package update implements the core of `abcd update` (itd-130 / spc-32): a user-invoked fetch/verify/swap for the PATH-installed binary.
core/vintage Package vintage is abcd's staleness comparator: it establishes whether the running binary is the one that should be running, by comparing the binary's own build vintage against a reference supplied by a provider.	Package vintage is abcd's staleness comparator: it establishes whether the running binary is the one that should be running, by comparing the binary's own build vintage against a reference supplied by a provider.
fsutil Package fsutil holds the durable-write and path-safety primitives shared by the ~/.abcd and repo .abcd store writers.	Package fsutil holds the durable-write and path-safety primitives shared by the ~/.abcd and repo .abcd store writers.
gittest Package gittest is the shared hermetic-git environment for tests that spawn git as a subprocess (iss-28).	Package gittest is the shared hermetic-git environment for tests that spawn git as a subprocess (iss-28).
gitutil Package gitutil holds the shared, isolated git queries.	Package gitutil holds the shared, isolated git queries.
livery Package livery holds the canonical pixel-grid definitions of abcd's visual identity — the duckling mascot, the signal-flag logo, and the lifeboat mark — and the palette they share (itd-133/spc-36).	Package livery holds the canonical pixel-grid definitions of abcd's visual identity — the duckling mascot, the signal-flag logo, and the lifeboat mark — and the palette they share (itd-133/spc-36).
livery/gen command Command gen writes the committed SVG identity assets from the canonical livery grids.	Command gen writes the committed SVG identity assets from the canonical livery grids.
surface/cli Package cli is abcd's default front door: a Cobra command tree that marshals internal/core results to the terminal (human text or, with --json, machine output).	Package cli is abcd's default front door: a Cobra command tree that marshals internal/core results to the terminal (human text or, with --json, machine output).
surface/cli/identitygen command Command identitygen bakes the canonical identity block's title and tagline into a generated Go file (itd-112/spc-41).	Command identitygen bakes the canonical identity block's title and tagline into a generated Go file (itd-112/spc-41).
term Package term holds the canonical terminal-capability primitives: the colour-mode ladder and the TTY check (adr-49, brief invariant 13).	Package term holds the canonical terminal-capability primitives: the colour-mode ladder and the TTY check (adr-49, brief invariant 13).
termsafe Package termsafe holds the one canonical sanitiser for a string built from untrusted content (commit subjects, refs, file paths, repo prose, error text echoing a malformed file) before it is written to a terminal or a human report.	Package termsafe holds the one canonical sanitiser for a string built from untrusted content (commit subjects, refs, file paths, repo prose, error text echoing a malformed file) before it is written to a terminal or a human report.
urlguard Package urlguard is the canonical SSRF guard for every outbound fetch abcd makes.	Package urlguard is the canonical SSRF guard for every outbound fetch abcd makes.