A contribution pipeline for software projects built with AI agents. Every change disclosed, gated by hard checks, reviewed against its spec, and merged by a named human. The goal is bug-free software.
Drop ASDD into any GitHub repo. It handles the parts that break when AI writes real pull requests: undisclosed authorship, unchecked security, and agents that auto-merge things they shouldn't. Everything in it, disclosure, independent multi-lens review, test agents on a different model, and an accountable human merge, exists to drive the defect rate on AI-authored code toward zero.
- The three rules
- How it works
- Get started
- Bring your own assistant, and your own spec tool
- Running the operate layer with Goose
- Own the record: governance, training, and knowledge
- Lanes and the PR template
- Conformance
- Optional profiles: Assure and spec-driven
- What it does not do
- Prior art and lineage
- Status · Contributing · License
Disclose agents. If an AI agent helped write the code, say so in the PR and the commit trailer. Every change stays attributable. There is no hidden AI involvement.
Humans own the merges. Agents review and recommend. A human approves and merges. Auto-merge is off by default.
Quality and security are gates. Not suggestions, not advisory-only on the things that matter. The intake gate fails hard; the security lens blocks on real findings.
Every contribution crosses an airlock: agent-held membranes between an untrusted public side (PR bodies, diffs, fork contents) and the trusted development side (code, wiki, model). Only a validated spec or a review-ready change crosses inward; raw untrusted content, including submitted code, never crosses as an instruction.
A change moves through five steps. The first two happen before the PR; the last three run on it. (For the full model, see how it works.)
- Spec. The change is captured as a spec: outcomes, scope, constraints, and how "done" is checked. The spec agent can guide anyone through it in conversation, a non-engineer included, and parks an incomplete idea until it is ready.
- Build. Someone implements the spec and opens a PR. The developer is always the contributor's own, their agent or their hands; a deployment never runs a standing developer.
- Intake. A deterministic gate, no model, read-only, runs first: authorship disclosure is present, every commit is DCO signed off, and the PR carries exactly one lane tag. A failure posts the specific fixes as a PR comment, and nothing downstream runs, so a failed intake never reaches a model.
- Review. Only after intake passes, the four lenses (code, security, spec, quality) judge the change. Because this is triggered by intake completing rather than by the PR event, a fork PR gets the same real review and a failed intake spends nothing. The analysis holds
contents: readonly and makes two independent model calls, the quality lens in a separate context so it cannot rubber-stamp the others. - Merge. A separate, write-scoped job posts one advisory comment and sets the
asdd/reviewstatus through a policy decision point that denies merge, push, and branch-protection changes. Then a human merges.
Merges are tiered by change class. The default is that humans merge everything; auto-merge is earned (only after a track record), narrow (a declared class of trivial, fully-green changes), and protected paths stay human-approved permanently.
Inside the read-only review job, three layers stack: deterministic rules over the added diff lines (committed keys, disabled TLS, dangerous sinks, Trojan-Source bidi and zero-width Unicode, injection markers), a SAST pass (bandit) over changed Python, and a model lens on top when a runtime is wired. Code under review is always data: the scanner reads bytes and runs static checks, never importing or executing what it reviews. A block finding flips asdd/review to request-changes, so the gate bites even in dry-run before a model is connected. Suppress a line with a visible # nosec or # asdd: ignore.
pip install git+https://github.com/OneHillAI/ASDD
asdd init --goose /path/to/your-repo
init writes the constitution (AGENTS.md), the config (.asdd.yml), the gates and workflows, the PR template, CODEOWNERS, and the Goose operate recipes. Drop --goose for the govern layer only. To place every file by hand instead, the deploy guide lists them.
The intake gate runs on the next pull request immediately. The review runs in a labelled dry-run until you connect a model. Run asdd setup (it also asks whether readiness is decided by ASDD's built-in validator or OpenSpec) and set three repository secrets:
ASDD_RUNTIME_TOKEN- your model API keyASDD_MODEL_URL- an OpenAI-compatible chat-completions URLASDD_MODEL- the model name
Any OpenAI-compatible provider works. The analysis job holds contents: read only; the write scope stays in the publish job, which never reads untrusted PR content. That split is the security invariant, do not merge the two jobs.
init writes a pointer for the common assistants (CLAUDE.md for Claude Code and the Claude app, .cursor/rules/asdd.mdc for Cursor, and AGENTS.md for Codex and any tool that follows the AGENTS.md convention), so whatever you bring reads the contribution constitution with no extra setup. From there the workflow is a set of slash commands: /asdd:setup, /asdd:spec, /asdd:review, /asdd:status, thin prompts over the CLI that port to any assistant. You do not have to be an engineer to start: describe the change to the spec agent in plain language and it drafts the spec the pipeline needs. The CLI also runs the deterministic gates and a read-only dashboard locally; a spec that passes locally passes on the PR, because it is the same code. See bring your own developer.
ASDD is installed into the repository, not into a chat window. The config, the constitution, the gates, and the pipeline are files and CI in your repo; no assistant holds any part of the standard. That is deliberate: bring your own assistant, Claude Code, Cursor, Copilot, Goose, or a contributor's tool you have never heard of. The governance is identical for all of them because it runs where they cannot rewrite it. Tools that live inside one assistant govern only that assistant's users; a contribution boundary has to hold for the rest.
The same holds for the spec: bring Spec Kit, OpenSpec, or plain files. ASDD requires that a spec exists and that the change is checked against it, not that a particular tool produced it. spec_tool: in .asdd.yml chooses the readiness validator (built-in or OpenSpec), and spec_paths: points the gate at wherever your specs live, so adopting ASDD never means abandoning the authoring workflow you already run. See adopt OpenSpec.
Most projects that adopt ASDD are not starting from zero. They already have a changelog format, a docs layout, an impact log, a house style and years of commits that predate every rule. That is the normal case, so it is a first-class path rather than an afterthought.
Two things make it work. Your conventions are declared, and the agents are held to them. A conventions: block in .asdd.yml names where your specs live, whether your changelog is written as per-change fragments or edited directly, the impact log you maintain, and your house style. The operate agents read that as an output contract instead of guessing, and asdd conventions-check holds their output to it, so a drifting agent fails loudly rather than quietly producing work you have to redo. Where you already keep an artefact, ASDD points at it; it never creates a second changelog beside yours.
Gates judge the change, not your repository. Only the diff under review is checked, and house style is checked on added lines only, so a repository with thousands of pre-existing violations can adopt today and tighten from there rather than being told to fix its history first. See adopt into an existing project.
init above wires the govern layer (the CI gates). The operate layer, the agents that do the work, is optional and runtime-neutral: implement the contract in agents/runtime.md on your own harness, or use the ready-to-run kit for unmodified Goose, which is open source and free to run. You bring an API key for a model; you do not buy the harness.
Status: alpha. The Goose operate kit is usable and dogfooded, but its recipes and interfaces may still change.
With the kit already scaffolded (from asdd init --goose), configure and run:
goose configure- pick your provider. The recipes are provider-neutral; a model is set per run and switching is one line.- The developer is bring-your-own: a contributor connects their own coding agent to build a change. The deployment runs only the governance and support agents (
test-author,test-runner,documentation,interaction) on your models. Keep the test agents' models distinct from the developer's, the one hard rule;cli/check-models.shenforces it. - Run the loop: a contributor builds a change and opens a PR; the test agents and the CI gates check it; a human merges. The interaction agent brings ideas in from the public as validated specs.
The Goose quickstart walks it end to end, including a free, no-keys "prove it runs" check.
Every agent action is recorded to an append-only, hash-chained ledger: who did what, to what, under whose authority, when, why, and what it caused. It lives in a private sink you own. ASDD hosts nothing and no data leaves your control by default. That trail is not only governance evidence; it is one event stream with three views:
- Governance. The tamper-evident record behind STANDARD 1.3, reviewable in the dashboard.
- Training and tuning (
asdd audit corpus). A clean JSONL of your project's own decisions, so you can fine-tune a model on how your team actually builds. Content-safe by construction: counts and categoricals, never reviewed code or a finding's paths. - Knowledge (
asdd audit knowledge). Durable learnings, a review invariant, a rejected approach, an exemplar, emitted as OKGF pages a knowledge store ingests, so later runs reuse what the system already learned instead of rediscovering it.
The longer it runs, the more it is worth: governance evidence, a training corpus, and a knowledge base, all accumulating in infrastructure you own. See docs/guides/audit-ledger.md and docs/guides/okgf-integration.md.
Every PR carries exactly one lane tag, enforced at intake:
| Lane | What it covers |
|---|---|
feature |
A new user-facing capability |
fix |
A bug fix |
docs |
Documentation |
chore |
A trivial change (tests, dependencies, formatting); skips the spec requirement |
The gate reads this set from .asdd.yml; adapt it to your project. And every PR carries a disclosure block, which the intake gate checks for:
## Disclosure
[ ] Entirely human-authored
[ ] Authored or co-authored by an AI agent under human direction
Agent identity (if any): [name]
Instructed by (human handle): [handle]
Commit trailers follow the same pattern: Agent: Claude on a commit an agent produced.
A project that calls itself ASDD conformant must:
- Run the intake gate on every PR, including maintainer PRs
- Require authorship disclosure in every PR
- Keep the write scope isolated in the publish job
- Route every publish action through a policy decision point that denies merge
- Not modify the security lens to suppress findings without a visible comment
The asdd/review status check is what external tooling relies on. Self-certify against CONFORMANCE.md.
Two profiles a project can opt into, both mandated by nothing:
- Assure: integrity attestation. A signed per-change record binding provenance, a threat scan mapped to the OWASP agentic risks, agent identity, and independent different-model review. It composes with SLSA / in-toto / Sigstore / SBOM rather than replacing them. Forward-looking; the format is in draft.
- Spec-driven (STANDARD §8). The spec is the artifact and code is a build output: a spec-object intake gate, a trust membrane, two-tier contributor identity (DCO-capable to merge, attributable to propose), a claim protocol, and a contributor-facing reviewer distinct from the merge gate. Channel- and identity-provider-neutral.
ASDD does not auto-merge anything. It does not replace human code review, does not catch everything the security lens misses, and does not remove the need for human judgement on architecture, design, or product. It gives humans better information before they merge, produced under conditions the project can defend.
ASDD stands on prior art, and it is worth naming it.
- Spec Kit, and spec-driven development generally, is where the core idea comes from: the specification is the artifact and code is a build output validated against it. Spec Kit solves the authoring loop for one developer in their own repo; ASDD takes that foundation to the contribution boundary, what happens when work from many humans and agents arrives at a project that has to decide whether to trust it.
- OpenSpec is the spec lifecycle ASDD adopts rather than reinvents: a change is a reviewed delta against living specs that accumulate as the source of truth. ASDD governs the boundary around that lifecycle; it does not replace it.
- AGENTS.md is the constitution format the agents read. MCP is how an agent reaches the deterministic gates. Goose (Linux Foundation AAIF) is one ready-to-run operate runtime, used unmodified.
docs/prior-art.md sets out how ASDD differs from each in detail.
v0.1 draft. The standard (STANDARD.md) is published and self-certifiable against CONFORMANCE.md; while pre-1.0 it is a moving draft, so a conformance claim should name the commit or date it was checked against. The govern layer runs in production on this repo. ASDD with Goose, the operate layer, is alpha.
Contributions are welcome under a disclosure block and a DCO sign-off, the same gate ASDD runs on itself. See CONTRIBUTING.md to propose a change, and GOVERNANCE.md for how the standard is stewarded and versioned.
Apache-2.0 (see LICENSE): reuse and extend it freely, and attribute the OneHill Foundation. It covers the whole project, the written standard (STANDARD.md and standards/) as well as the tooling and reference implementation. Software that adopts ASDD is licensed separately by its own project. See NOTICE.