abcd

module

v0.6.6 Latest Latest Go to latest Published: Aug 25, 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.

Agents are good at producing work and bad at remembering why. Ask one to build something and it will, then the next session starts again from the artefact rather than the argument. What was decided, what was rejected and on what evidence lives in a transcript nobody reads twice, so the reasoning is spent as fast as it is made.

abcd keeps that reasoning as records the agent and the human both read: the intent that says what shipping looks like, the decision that says what was chosen and what was refused, the specification, the issue ledger. They are plain files in the repository, checked by gates that refuse rather than warn, so what the record claims about the product stays true as the product moves.

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 rather than summarised.

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. Read it at abcdev.app, alongside who abcd is for, the roles, the artefacts and the process, rendered from the pages in docs/ and the development record.

abcd is experimental and the surface still moves: Verbs change and it's currently only available for a single harness. What's not experimental is the record and neither is the discipline it's being built with.

Install

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

Run these two, in order, from a session in that harness:

/plugin marketplace add intentdriven/abcd
/plugin install abcd@abcd-marketplace

The first registers this repository as a plugin marketplace; the second installs abcd from it. 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. Two things move at different speeds: the plugin surface tracks this repository, and the binary it provisions tracks the latest published release. Reloading plugins is not the same thing: that re-reads what is already on disk, so it refreshes the commands while leaving the binary as it was.

Support for other harnesses will follow.

As a CLI

If your harness isn't supported yet, abcd runs from a terminal in any repository, with no harness involved:

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/intentdriven/abcd/releases/latest/download/$b"; curl -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.

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/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.