claude-apd

Enforced multi-agent pipelines with mechanical guardrails for AI-assisted software development.
Works with Claude Code and OpenAI Codex.

Getting Started · Interactive Demo · Pipeline Runs · Changelog

v6.16.1 · MIT · macOS + Linux

---

What is APD?

APD enforces a disciplined workflow where specialised agents build code through a gated pipeline. Every step is mechanically enforced — hooks block violations, not documentation.

Spec → Builder → Reviewer → [Adversarial] → Verifier → Commit

• Agent — work divided among specialised agents with scoped permissions
• Pipeline — gated flow with mechanical enforcement at every step
• Development — one feature = one pipeline cycle = one commit

Quick start

Claude Code:

/plugin marketplace add zstevovich/claude-apd          # one time
/plugin install claude-apd@zstevovich-plugins          # per project
/apd-setup                                             # configure
bash .claude/bin/apd verify                            # check setup

Codex (OpenAI) — preferred, via plugin marketplace (validated on Codex 0.124):

# Prerequisites: brew install uv jq   (codex_hooks is stable on 0.124, no feature flag needed)
codex plugin marketplace add zstevovich/claude-apd             # one time, pulls latest main
printf '\n[plugins."apd@codex-apd"]\nenabled = true\n' >> ~/.codex/config.toml   # enable
cd <your-project> && codex                                     # open TUI in target project
# On first user prompt in the fresh session, APD auto-scaffolds
# .codex/ + .apd/ + AGENTS.md and MCP tools become available
# (apd_ping, apd_doctor, apd_guard_write, ...).

Codex — alternative, direct-drop (no marketplace):

git clone https://github.com/zstevovich/claude-apd ~/apd && \
    export PATH="$HOME/apd/bin:$PATH"                  # live source at ~/apd
apd cdx init                                           # scaffold .codex/ + .apd/ + AGENTS.md
apd cdx agents add code-reviewer                       # populate agents
apd cdx agents add backend-builder src/ config/
apd cdx skills install                                 # symlink phase skills into ~/.codex/skills/
apd cdx doctor                                         # audit setup
codex                                                  # start session; "run apd_ping"

Upgrading

Claude Code:

/plugin update claude-apd@zstevovich-plugins                  # pulls latest from main
# Restart the CC session — skill slash commands re-register on session start

Codex — marketplace install (Git source):

codex plugin marketplace upgrade codex-apd                    # pulls latest main, replaces cache atomically
# Open a new TUI session — first user prompt picks up the new version

To pin the upgrade to a specific tag or branch (e.g. for pre-release testing):

codex plugin marketplace remove codex-apd
codex plugin marketplace add zstevovich/[email protected]     # or @<branch> for a feature branch

Codex — direct-drop install:

bash .codex/bin/apd update                                    # git pull --ff-only + idempotent re-init
# --check-only      # dry-run, don't pull or write
# --skip-pull       # only re-run install-codex-config locally

Codex SessionStart quirk (upstream). Per openai/codex#15269, Codex 0.124 fires the TUI SessionStart hook when the user submits the first prompt, not at banner display. Practically: gap-analysis runs on first turn, not at open. MCP tools are available immediately.

See Getting Started for both walkthroughs.

Five roles

Role	Model	Effort	Responsibility
Orchestrator	opus	max	Coordinates pipeline, writes spec, dispatches agents, commits
Builder	sonnet	xhigh	Implements code per spec, scoped to specific files
Reviewer	opus	max	Finds bugs, security issues, edge cases (read-only)
Adversarial Reviewer	sonnet	max	Context-free review — no spec knowledge, fresh perspective
Verifier	—	—	Script: build + test + spec traceability check

Model and effort per agent are per-project settings — and since v6.16 they are switchable as named profiles.

Model profiles — economy vs quality

The model raises the average. APD guarantees the floor. The profile chooses what the average costs.