source	https://github.com/juliusz-cwiakalski/agentic-delivery-os/blob/main/README.md

Agentic Delivery OS (ADOS)

Turn AI from "chat assistance" into a repeatable, auditable delivery system:

ticket -> spec -> plan -> test plan -> code -> /review -> /sync-docs -> /check -> /pr -> release

This repo is a practical reference implementation of a spec-driven workflow using OpenCode:

• Artifacts are first-class (versioned in Git), not trapped in chats.
• Deterministic quality gates define "done".
• The workflow is tracker-agnostic: the tracker owns status, Git stores the delivery artifacts.
• The repo maintains a continuously updated "current system spec" under doc/spec/** (created if missing; reconciled after each accepted change).

Note: doc/spec/** may not exist in a fresh repo; it's created/updated by the workflow (see /sync-docs).

Why this exists

AI can generate code quickly, but most teams struggle to use it reliably at scale:

• Prompts live in DMs and chat logs (not versioned, not repeatable)
• Output quality varies day-to-day ("prompt roulette")
• Delivery still needs specs, acceptance criteria, test strategy, reviews, docs, release discipline
• Tooling glue work persists between Jira/Git/CI/docs

Agentic Delivery OS codifies a predictable pipeline where quality and traceability are non-negotiable.

What this gives you

• A team of 19 repo-local agents aligned to SDLC roles (PM, spec writer, planner, coder, reviewer, bootstrapper, and more).
• A standard artifact set (spec, implementation plan, test plan) stored under doc/changes/ using stable, tracker-linked names.
• A versioned, human-readable system spec under doc/spec/** that acts as the baseline input for planning the next change (kept up to date via /sync-docs).
• Commands that compose those agents into repeatable workflows (manual or autopilot).

Quick start

Requires: OpenCode — the AI coding agent that runs ADOS agents and commands.

Global install (one-liner — gives you ADOS agents in every project):

curl -fsSL https://raw.githubusercontent.com/juliusz-cwiakalski/agentic-delivery-os/main/scripts/install.sh | bash -s -- --global

Set up a specific project:

~/.ados/repo/scripts/install.sh --local    # copy artifacts into current project

Then in your AI coding agent:

/bootstrap                                  # AI-guided configuration

Uninstall: ~/.ados/repo/scripts/uninstall.sh --global or ~/.ados/repo/scripts/uninstall.sh --local

Update: Re-run the same install commands to update to the latest version.

Full guide: doc/guides/onboarding-existing-project.md

Benefits

• Less ambiguity: specs and test plans are explicit before code is written.
• Predictable planning: next changes can start from the current system spec (doc/spec/**) instead of rebuilding context from chat history.
• Higher trust: /review and /check run against artifacts, not vibes.
• Quality is non-negotiable: /review iterates until PASS and /check is green before you get a PR/MR (via /pr) to look at.
• Faster iteration: agents can find the right context deterministically (stable paths, no global indexes).
• Better auditability: tickets link to change folders, branches, PR descriptions, and logs.
• Less noise: in autopilot mode, the tracker is the interface; the @pm agent pings you only when decisions/clarifications/reviews are needed.

Intention

This project exists to evolve and validate an AI-native delivery operating model on real work: reduce "prompt roulette", keep humans accountable, and make shipping faster without lowering quality.

Docs at a glance

• AI agent & contributor quick-reference: AGENTS.md
• How to use the agents/commands: doc/guides/opencode-agents-and-commands-guide.md
• Change delivery lifecycle (10-phase workflow): doc/guides/change-lifecycle.md
• Change folder + naming convention (workItemRef, branches, files): doc/guides/unified-change-convention-tracker-agnostic-specification.md
• Broader docs layout standard (some details may differ per repo): doc/documentation-handbook.md
• Tooling definitions (agents/commands): .opencode/README.md
• Tracker/PM setup for autopilot mode: .ai/agent/pm-instructions.md
• Onboarding guide (adopt ADOS in your project): doc/guides/onboarding-existing-project.md

What is implemented here

OpenCode tooling (see .opencode/README.md for the authoritative list):

• 19 agents for SDLC roles:
  • @pm, @coder, @spec-writer, @plan-writer, @test-plan-writer, @reviewer, @doc-syncer, @pr-manager, @runner, @fixer, @committer, @architect, @editor, @designer, @image-generator, @image-reviewer, @bootstrapper, @external-researcher, @toolsmith.
• 16 commands that compose them into a repeatable workflow:
  • /plan-change, /write-spec, /write-plan, /write-test-plan, /run-plan, /review, /review-deep, /sync-docs, /check, /check-fix, /pr, /commit, /plan-decision, /write-decision, /bootstrap, /design.

Autopilot (PM-driven)

Autopilot mode is a high-level handoff: you provide a ticket reference (or URL) and the @pm agent orchestrates the full delivery loop (including /review, /sync-docs, and /check), then creates/updates a PR/MR via /pr only when it's ready for human review.

Example prompt:

@pm deliver change GH-456

(You can also use a GitHub issue URL or a workItemRef like GH-456.)

Typical workflow (manual)

For the detailed walkthrough, see doc/guides/opencode-agents-and-commands-guide.md. The common flow is:

/plan-change <workItemRef?>
/write-spec <workItemRef>
/write-test-plan <workItemRef>
/write-plan <workItemRef>
/run-plan <workItemRef>
/sync-docs <workItemRef>
/review <workItemRef>
/check
/pr

Tool definitions: /plan-change, /write-spec, /write-plan, /write-test-plan, /run-plan, /review, /sync-docs, /check, /pr

Change artifacts (tracker-agnostic)

Changes are identified by workItemRef (for example PDEV-123 for Jira or GH-456 for GitHub). Artifacts live under:

• doc/changes/YYYY-MM/YYYY-MM-DD--<workItemRef>--<slug>/
• Stable filenames inside the folder:
  • chg-<workItemRef>-spec.md
  • chg-<workItemRef>-plan.md
  • chg-<workItemRef>-test-plan.md
  • chg-<workItemRef>-pm-notes.yaml (progress tracking, decisions, open questions)

After the change is implemented and accepted, the workflow reconciles the "current truth" docs (via /sync-docs):

• doc/spec/** (system specification)
• doc/contracts/** (interfaces/contracts, when used)

Branches follow conventional-commit-aligned types:

• <type>/<workItemRef>/<slug> (for example feat/PDEV-123/responsive-product-images)

Repo structure

.
├── AGENTS.md             # delivery system bootstrap (start here)
├── .opencode/            # agent and command definitions (THE product)
│   ├── agent/            # 19 agents (one .md each)
│   └── command/          # 16 commands (one .md each)
├── .ai/
│   ├── agent/            # PM tracker config (pm-instructions.md)
│   ├── local/            # git-ignored ephemeral state
│   └── rules/            # language/tool rules (bash.md)
├── scripts/              # repo-internal automation (.sh extension)
│   └── .tests/           # test files for scripts (test-*.sh)
├── tools/                # PATH-able CLI utilities (no .sh extension)
│   └── .tests/           # test files for tools (test-*.sh)
└── doc/
    ├── 00-index.md           # documentation landing page
    ├── changes/              # change artifacts (spec, plan, test-plan per workItemRef)
    ├── decisions/            # decision records (ADR/PDR/TDR/BDR/ODR)
    ├── guides/               # how-to guides
    ├── overview/             # north star, architecture, glossary
    ├── planning/             # internal planning notes
    ├── spec/                 # current system spec (reconciled after each change)
    ├── templates/            # document templates (7 templates)
    ├── tools/                # CLI tool user guides
    └── documentation-handbook.md

License

Open-source. See LICENSE.

Author

Maintained by Juliusz Ćwiąkalski. If you find this useful, follow me or drop by my homepage (blog + newsletter):

• LinkedIn: @juliusz-cwiakalski
• X: @cwiakalski
• Website (blog + newsletter): https://www.cwiakalski.com