- Status: Accepted
- Date: 2026-03-13
- Decision makers: Sebastien (plugin author)
The ACD (Agentic Continuous Delivery) plugin and the nWave framework are developed by the same author and are currently both installed on the same development machine. They serve the same developer but through different delivery mechanisms:
- nWave is a Python package (
pipx install nwave-ai) that installs 25+ agents, 21+ commands, and Claude Code hooks into~/.claude/. It provides multi-agent orchestration (waves, sequencing, hook-based guardrails) and specialized expert agents (researcher, architect, crafter, etc.). - ACD plugin is a Claude Code plugin (
~/.claude/plugins/) that provides 17 agents, 10 commands, 16 rules, and skills. It encodes CD discipline: session protocol, review gates, TDD/BDD methodology, pipeline management, release techniques, and security layers.
The plugin has never been tested without nWave installed. The question: should ACD remain an independent plugin, merge into nWave, or declare nWave as a dependency?
Option 1: Keep ACD as an independent plugin. Validate standalone viability through empirical use before considering a merge.
ACD stays a separate Claude Code plugin. nWave stays a separate Python framework. They can be installed together or independently.
Pros:
- Simpler to iterate on — one concern, one repo, one release cycle
- Portable — any Claude Code user can install the CD discipline without adopting the full nWave orchestration
- Forces the plugin to be self-contained — no hidden dependencies on nWave hooks or agents
- Empirical validation — by actually using it standalone, we learn what's missing vs what's inherited from nWave
Cons:
- Untested standalone — may have implicit assumptions about nWave being present
- Two repos to maintain for what may be a single user experience
- nWave users don't get ACD rules automatically — they must install separately
The ACD rules, agents, and commands become a module inside nWave. The ACD plugin ceases to exist.
Pros:
- Single project to maintain
- nWave users get CD discipline automatically
- Hooks and agents can directly reference and enforce ACD rules
- More impact — nWave's existing user base inherits the CD principles
Cons:
- Couples CD discipline to a specific orchestration framework
- Users who want CD discipline without nWave's full agent ecosystem cannot get it
- Larger project = slower iteration on either concern
- If nWave's architecture changes, the CD rules must adapt even if they haven't changed
nWave's install script also installs the ACD plugin. They ship together but live in separate repos.
Pros:
- nWave users get ACD automatically
- ACD stays portable for non-nWave users
- Separation of concerns maintained at repo level
Cons:
- Dependency management across two distribution mechanisms (pipx + Claude Code plugin marketplace)
- Version synchronization between the two
- More complex install/upgrade path
The CD discipline encoded in this plugin (Farley's release techniques, TDD methodology, pipeline management, session protocol) is framework-agnostic knowledge. It applies to any software project regardless of orchestration tooling. Merging it into nWave would limit its reach.
However, the plugin has never been validated standalone. The honest engineering response (per Farley: "be experimental, measure outcomes") is to test the hypothesis before making an irreversible architectural decision.
Hypothesis: "We believe keeping ACD independent will allow broader adoption and faster iteration, because the CD discipline rules are valuable regardless of orchestration framework."
Validation criteria:
- Can a developer install and use ACD without nWave? (functional independence)
- Do the commands (
/acd:specify,/acd:start-session,/acd:review,/acd:end-session) work without nWave hooks? (no implicit dependencies) - Do users outside the nWave ecosystem find the plugin useful? (market signal)
If validation fails — if ACD is unusable without nWave — then Option 2 (merge) becomes the correct decision. This ADR will be superseded.
An investigation of the installed runtime revealed concrete dependencies on nWave infrastructure that this ADR must acknowledge. These are not theoretical — they were observed in a live session.
ACD declares zero hooks. nWave installs four hooks in ~/.claude/settings.json that actively govern agent behavior:
| Hook | What it enforces | ACD impact without it |
|---|---|---|
PreToolUse:Task |
Requires max_turns on all agent invocations |
ACD's agents (implementation, review sub-agents) can run unbounded — no execution budget enforcement |
PreToolUse:Write |
Guards file writes during deliver sessions | No write protection during ACD sessions |
PreToolUse:Edit |
Guards file edits during deliver sessions | No edit protection during ACD sessions |
SubagentStop |
Intercepts sub-agent completion | No post-completion processing for ACD's review orchestrator sub-agents |
Severity: high. The max_turns enforcement is a safety mechanism. Without it, a /acd:review invocation that spawns 4 sub-agents has no execution budget. This is not a convenience feature — it prevents runaway agent loops.
ACD's rules and project CLAUDE.md files reference nWave expert agents (nw-researcher, nw-platform-architect, nw-software-crafter, etc.) in the "Expert Summoning Guide." Without nWave installed, these agents do not exist. The summoning instructions become dead references.
Severity: medium. This is a project-level concern (CLAUDE.md), not a plugin-level one. ACD's own commands and agents do not directly invoke nw-* agents. But the recommended workflow assumes they're available.
nWave provides /nw:deliver, /nw:review, /nw:research, etc. ACD provides /acd:start-session, /acd:review, /acd:specify, etc. These serve different purposes but a user without nWave would lose the nWave commands entirely. No ACD command depends on a nWave command, so this is not a dependency — but it is a workflow gap.
Severity: low. Informational only.
| ACD Feature | Works standalone? | Gap |
|---|---|---|
| Rules (16 files) | Yes | Pure documentation, no runtime dependency |
/acd:specify |
Yes | Conversation-driven, no delegation |
/acd:start-session |
Partially | Invokes implementation agent without execution budget |
/acd:review |
Partially | Spawns 4 sub-agents without execution budget |
/acd:end-session |
Yes | Commit workflow, no agent delegation |
| ACD agents | Structurally yes, unguarded | No max_turns, no file-write protection |
| Expert summoning | No | References nw-* agents that require nWave |
For Option 1 (independence) to hold, ACD must close the hook gap. Two approaches:
A. ACD adds its own hooks — at minimum: max_turns enforcement on agent invocations, file-write guards during sessions. This makes ACD self-contained but duplicates nWave's guardrail logic.
B. ACD documents a "trust mode" — without hooks, the plugin works but relies on Claude Code's default behavior and the user's judgment. The rules still guide behavior through prompts; the hooks just aren't there to mechanically enforce them. This is honest but weaker.
If neither approach proves viable, this ADR should be superseded by Option 2 (merge into nWave).
- The ACD plugin must be tested standalone (without nWave installed) to verify functional independence
- Immediate action required: resolve the hook gap (approach A or B above) before claiming standalone viability
- Any implicit dependency on nWave hooks or agents discovered during standalone testing must be resolved: either removed (making ACD truly independent) or documented as a hard requirement (invalidating this decision)
- The
.nwave/directory appearing in the plugin repo is a local artifact, not a dependency — it stays in.gitignore - nWave's documentation should recommend ACD as a complementary plugin, not assume it
- This decision is explicitly provisional — revisit after standalone validation and after the hook gap is resolved