convez.ai
AgenteDevOps & InfraestruturaAvançado
zstevovich

APD — Agent Pipeline Development

zstevovich/claude-apd

Pipelines multi-agente com guardrails mecânicos para dev assistido por IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Framework de pipeline com múltiplos agentes especializados para desenvolvimento de código assistido por IA, com gates mecânicos e hooks de segurança. Enforça fluxo disciplinado de especificação, construção, revisão e verificação em cada ciclo de desenvolvimento.

Instalação

$npx convez-ai zstevovich/claude-apd

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
5
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 2 dias
Versão
v8.0.1
Issues abertas
0
Contribuidores
1

Casos de uso

  • Orquestração de múltiplos agentes em fluxos de desenvolvimento estruturado
  • Implementação de gates mecânicos e hooks de segurança em pipelines de código
  • Divisão de trabalho entre agentes especializados (builder, reviewer, verifier)

Veredito

APD é uma solução robusta para equipes que necessitam orquestração disciplinada de agentes em pipelines de desenvolvimento. Complexidade alta, mas com retorno claro em projetos que exigem enforcement mecânico e auditoria de código.

README

A tradução para o português deste README ainda está na fila.

APD Demo


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/claude-apd@v6.16.1     # 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

RoleModelEffortResponsibility
OrchestratoropusmaxCoordinates pipeline, writes spec, dispatches agents, commits
BuildersonnetxhighImplements code per spec, scoped to specific files
RevieweropusmaxFinds bugs, security issues, edge cases (read-only)
Adversarial ReviewersonnetmaxContext-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.

One command switches every pipeline agent's model/effort between named profiles:

ProfileBuilders / ReviewerAdversarialWhen
burnclaude-fable-5 / highopus / maxLaunch-critical features — maximum quality, cost ignored
cruiseopus / xhighsonnet / maxDaily default — strong builders, balanced cost
ecosonnet / xhighsonnet / maxSmall, well-scoped tasks, copy fixes, Lean runs
apd profile list              # profiles + role mappings
apd profile status            # current agents vs declared profile (flags drift)
apd profile cruise            # apply, then /reload-plugins

Or just run /apd-profile and pick.

Design notes baked into the defaults:

  • Builders carry the tier — they hold the context, so they get the strongest model the profile pays for. The adversarial reviewer may sit one tier below: its value is positional (fresh, context-free perspective), not model-tier.
  • Every switch is recorded (MODEL_PROFILE in the APD config + an audit-log entry), so each pipeline run carries model attribution — economy vs quality becomes a measurable trade-off, not a feeling.
  • Profiles are data, never enforcement. The mapping lives in model-profiles.conf (per-project override supported); new model generations are a one-line table edit. No profile can loosen a gate or guard — the quality floor is not for sale, only the average is.

Pipeline flow

Pipeline commands

apd pipeline spec "Task name"     # Start task (requires spec-card.md with R* criteria)
apd pipeline builder              # Advance after builder (requires implementation-plan.md)
apd pipeline reviewer             # Advance after review
apd pipeline verifier             # Run verification (spec traceability + build + test)
apd pipeline status               # Show current state
apd pipeline rollback             # Undo last step
apd pipeline reset                # Clear pipeline (start fresh)
apd pipeline metrics              # Performance dashboard
apd pipeline stats                # Skip log
apd doctor                        # Full diagnostics
apd verify                        # Setup verification (50+ checks)

All commands via bash .claude/bin/apd <command> (CC) or bash .codex/bin/apd <command> (Codex) — the shortcut each runtime's installer scaffolds. User-facing framework messages auto-select the correct path.

Pipeline report

Full pipeline recap — available after any run or on demand:

apd report              # Current/last run
apd report --history    # All runs with trends and stats

Shows task info, step timing, spec coverage bar, adversarial findings, guard blocks, and agent durations. History mode adds success rate, trend analysis, session stats, and adversarial insights.

Mechanical enforcement

Every rule is backed by a hook script that blocks violations. No bypass from within Claude Code.

What is blockedGuard
Commit without all 4 pipeline stepspipeline-gate
Orchestrator writes code files directlyguard-orchestrator
Agent writes outside its scopeguard-scope
Bash writes to pipeline state (.done, .agents)guard-bash-scope + guard-pipeline-state
Direct Write/Edit to .apd/pipeline/ state filesguard-pipeline-state
git commit without APD_ORCHESTRATOR_COMMIT=1guard-git
git add . / mass stagingguard-git
--no-verify / force push / destructive git opsguard-git
Lock file modificationguard-lockfile
Access to sensitive files (.env, .pem, credentials)guard-secrets
Superpowers agents replacing APD rolespipeline-advance (agent type check)
Spec modified mid-pipelinepipeline-advance (sha256 hash freeze)
More than 7 acceptance criteria per specpipeline-advance (forces decomposition)
Spec advance without the pipeline-guide markerpipeline-advance (guide gate, no skip flag)
Builder dispatch without implementation planpipeline-advance (hard block)
Pipeline step forgeryCompiled Go binary creates HMAC-signed .done files — orchestrator cannot forge signatures
SendMessage during pipelineguard-send-message blocks — must use Agent() for tracked dispatch

Spec traceability

Acceptance criteria get R* IDs. Builders add @trace R* markers in test files. Verification blocks commit if any criterion lacks test coverage.

# .apd/pipeline/spec-card.md
**Acceptance criteria:**
- R1: Login endpoint returns JWT
- R2: Invalid credentials return 401
- R3: Password compared via bcrypt
// @trace R1 R2
test('login returns JWT on valid credentials', () => { ... });
test('login returns 401 on invalid credentials', () => { ... });

// @trace R3
test('password verified via bcrypt', () => { ... });

Implementation plan

Orchestrator writes .apd/pipeline/implementation-plan.md before dispatching builder — lists files to change with 1-2 sentences each, plus ### Agents section.

## Implementation Plan: Add user login

### Agents
- backend-api

### Files to create
- `src/Auth/LoginHandler.cs` — POST endpoint, validates credentials, returns JWT

### Files to modify
- `src/Auth/AuthModule.cs` — register the new endpoint

Project structure

Plugin (installed via /plugin install)

${CLAUDE_PLUGIN_ROOT}/                # = repo root for CC; CC auto-discovers hooks/ + skills/ here
├── .claude-plugin/plugin.json        # CC plugin manifest
├── .claude-plugin/marketplace.json   # CC marketplace manifest
├── .agents/plugins/marketplace.json  # Codex marketplace manifest → ./plugins/apd
├── hooks/hooks.json                  # CC plugin hooks (auto-discovered)
├── skills/                           # 8 CC skills (brainstorm, tdd, debug, finish, setup, audit, github, miro)
└── plugins/apd/                      # Plugin payload — single source of truth for both runtimes
    ├── .apd-version                  # CC version constraints (MIN_CC_VERSION, FUNC_CC_VERSION)
    ├── .codex-plugin/plugin.json     # Codex plugin manifest
    ├── .mcp.json                     # Codex MCP self-registration (cwd: ".", 9 tools)
    ├── VERSION                       # Plugin version (read by every script + MCP server)
    ├── bin/
    │   ├── apd                       # Single entry point
    │   ├── core/                     # Pipeline + guard + verify scripts
    │   ├── adapter/cc/               # CC-specific guards + post-commit
    │   ├── adapter/cdx/              # Codex install + doctor + skills + agents
    │   ├── compiled/                 # Go binaries (validate-agent)
    │   └── lib/                      # resolve-project.sh + style.sh
    ├── mcp/apd_mcp_server.py         # Codex MCP server (9 tools)
    ├── rules/workflow.md             # Pipeline workflow rules (copied to project on init)
    ├── templates/                    # Agent + project templates (CC + Codex scaffold)
    └── skills/                       # 7 Codex skills (brainstorm, tdd, debug, finish, audit, github, miro)

Path semantics. CC hook commands resolve via ${CLAUDE_PLUGIN_ROOT}/plugins/apd/bin/.... The MCP server resolves its plugin root as Path(__file__).resolve().parent.parent → plugins/apd/, so it sees bin/, templates/, rules/, VERSION as siblings without any path arithmetic. The Codex plugin cache contains exactly the contents of plugins/apd/, so plugin-shipped .mcp.json self-registration with cwd: "." works end-to-end.

Your project — CC install (generated by /apd-setup)

my-project/
├── CLAUDE.md                      # Project instructions
├── .claude/
│   ├── agents/                    # One .md per agent with scoped hooks
│   ├── bin/apd                    # Shortcut to plugin entry point
│   ├── scripts/verify-all.sh      # Build + test commands (project-specific)
│   ├── rules/                     # workflow.md + principles.md
│   └── memory/                    # Session log, status, metrics
├── .apd/
│   └── pipeline/                  # Ephemeral pipeline state (gitignored)
└── docs/adr/                      # Architecture Decision Records

Your project — Codex install (generated by apd cdx init)

my-project/
├── AGENTS.md                      # Codex project-context (analogue of CLAUDE.md)
├── .codex/
│   ├── config.toml                # Codex feature flags + plugin trust (NO mcp_servers.apd block in v6.0+; the MCP server self-registers via plugin .mcp.json)
│   ├── hooks.json                 # PreToolUse Bash → guard-bash-scope
│   └── bin/apd                    # Shortcut to plugin entry point
├── .apd/
│   ├── config                     # Activation marker (PROJECT_NAME, STACK)
│   ├── .apd-version               # Plugin version tag
│   ├── rules/workflow.md          # Pipeline workflow (paths rewritten to .codex/)
│   ├── memory/                    # MEMORY.md, status.md, session-log.md
│   ├── agents/                    # Populated with `apd cdx agents add <name>`
│   └── pipeline/                  # Ephemeral pipeline state (gitignored)
└── docs/adr/                      # Architecture Decision Records

Hybrid projects (both runtimes on one repo) keep the CC layout intact — the Codex installer detects .claude/ and skips the .apd/ scaffold.

Integrations (optional)

IntegrationWhat it doesSetup
GitHub ProjectsAuto-syncs pipeline steps to board columns (Spec → In Progress → Review → Testing → Done)Configure .mcp.json + gh auth login
FigmaFrontend builders get design context via MCPConfigure Figma MCP server
MiroOrchestrator reads boards for spec input, pushes pipeline dashboardclaude mcp add --transport http miro https://mcp.miro.com

Human gate

User MUST approve before: API changes, database migrations, auth/role logic, deploy to production.

Agent scope example

# .claude/agents/backend-api.md
hooks:
  PreToolUse:
    - matcher: "Write|Edit"
      hooks:
        - type: command
          command: "bash ${CLAUDE_PLUGIN_ROOT}/plugins/apd/bin/adapter/cc/guard-scope src/ tests/"

Agent writing to apps/frontend/App.tsx:

BLOCKED: File apps/frontend/App.tsx is outside the allowed scope.
Allowed paths: src/ tests/

Skills (Claude Code)

SkillWhenRequired?
/apd-pipeline-guideBefore EVERY spec — pipeline operating manual, writes the gate markerMandatory (no skip)
/apd-brainstormBefore the guide — vague or complex task clarificationRecommended when scope is unclear
/apd-tddDuring builder implementationMandatory
/apd-debugOn verifier failure or critical review findingMandatory
/apd-finishAfter successful commitMandatory
/apd-setupProject initialization and maintenanceOn setup
/apd-auditQualitative framework auditOptional
/apd-githubGitHub Projects board syncOptional
/apd-miroMiro board dashboard syncOptional
/apd-profileSwitch agent model profile (burn/cruise/eco — economy vs quality)Optional, between tasks

Codex adapter surface

CommandPurpose
apd cdx initScaffold .codex/ + .apd/ + AGENTS.md on the project
apd cdx agents listShow available templates and installed agents
apd cdx agents add <name> [scope ...]Scaffold an agent definition (5 templates available)
apd cdx doctorRuntime-aware audit of the pure-Codex setup
apd cdx testE2E smoke test (~75 checks, runs without Codex CLI)

Codex uses an MCP server (mcp/apd_mcp_server.py) that exposes the pipeline as 8 MCP tools: apd_ping, apd_doctor, apd_advance_pipeline, apd_guard_write, apd_verify_step, apd_adversarial_pass, apd_list_agents, apd_pipeline_state. The orchestrator on Codex plays all roles inline — there is no sub-agent dispatch like on CC — and scope enforcement happens through apd_guard_write(apd_role, file_path), which reads each role's scope server-side from the agent registry instead of trusting client arguments.

Real-world results

See Pipeline Runs for tracked production results with metrics.

Plugin compatibility

APD mechanically blocks superpowers:* agents — the two pipelines are incompatible. APD includes its own equivalents: brainstorming, TDD, debugging, code review, verification, and finish workflows.

Other plugins (Figma, context7, etc.) work alongside APD without conflicts.

License

MIT — Zoran Stevovic

Ver o original no GitHub

Bom para

Relacionados