This file is the methodology identity. It is loaded by every agent in every project. It defines HOW you work, not WHAT you work on. Project-specific facts belong in the project's own CLAUDE.md (generate one with
/acd:init-project).
These are the eight constraints from the Agentic CD specification. They are non-negotiable.
- Explicit, human-owned intent exists for every change. Every change starts with a human-written intent description that includes a hypothesis: "We believe [change] will produce [outcome] because [reasoning]."
- Intent and architecture are represented as delivery artifacts. Six first-class artifacts (intent description, user-facing behavior, feature description, acceptance criteria, system constraints, implementation) capture the full intent-to-delivery chain.
- All delivery artifacts are versioned and delivered together with the change. Artifacts travel with the code in the same repository. A commit without its artifacts is incomplete.
- Intended behavior is represented independently of implementation. BDD scenarios describe observable outcomes from the user's perspective. They do not reference internal classes, methods, or data structures.
- Consistency between intent, tests, implementation, and architecture is enforced. Pre-commit review gates (deterministic hooks + coordinating AI review agents) and pipeline expert validation agents verify alignment across all artifacts.
- Agent-generated changes must comply with all documented constraints. The feature description (Musts / Must Nots / Preferences / Escalation Triggers) and system constraints are binding on every agent-generated change.
- Agents implementing changes must not be able to promote those changes to production. The deployment pipeline is the sole promotion authority. No agent bypasses the pipeline.
- While the pipeline is red, agents may only generate changes restoring pipeline health. Route to
/acd:fix. No new feature work until green.
Every intent description includes a hypothesis connecting the change to a measurable outcome. Acceptance criteria answer "does the deliverable meet its requirements?" The hypothesis asks "did the change achieve its purpose?"
Format: "We believe [change] will produce [outcome] because [reasoning]."
The hypothesis is not validated by the pipeline — it is validated after delivery by observing the outcome. It exists so the team learns whether changes actually solved the problem, not just whether the deliverable passed its quality gate.
These are engineering practices of this plugin — not ACD constraints, but principles that make the constraints practical for AI agents.
- Token-aware architecture. Model routing by task complexity. Structured outputs at agent boundaries. Context hygiene at every step.
- Context hygiene. Stable content first (caching). Strip what doesn't change output. Session summaries replace conversations.
- Model-agnostic design. Skills are specifications in markdown, not model-specific code. Structured JSON at every interface.
Everything in this methodology exists to shorten feedback loops. TDD gives design feedback in seconds. Acceptance tests give intent feedback in minutes. The pipeline gives integration feedback in minutes. Small batches, trunk-based development, and session discipline all serve the same goal: learn faster whether a change is safe to release.
The corollary: every commit must be deployable, even when the feature it contributes to is not yet complete. This is achieved through release techniques (connect last, build-time exclusion, branch by abstraction) — not through feature branches. The release-techniques discipline skill defines the technique hierarchy and agent decision tree.
Two mechanisms capture knowledge that would otherwise be lost at context reset:
- WIP.md (
docs/wip/[feature-name].md) — feature-level external memory. Carries decisions, discovered work, and architectural state across all sessions of a feature. Created by/acd:start-session, updated by/acd:end-session, archived by/acd:finalize. - LEARNINGS.md (project root) — project-level process corrections. When the human corrects the agent, the correction is proposed as a learning entry. Only human-approved entries are written. Loaded into every session's context so mistakes are not repeated.
Learnings that apply beyond the project graduate to skills or plugin rules. The cycle: human correction → proposed learning → approved entry → graduation to skill. This is the process feedback flywheel.
- One unit of work → one session → one commit
- Context resets at every commit boundary
- Session summaries (≤150 words) replace full conversations
- Broad understanding established before any session
For software: one unit = one BDD scenario. For other domains: one unit = one deliverable element (one positioning brief, one article, one design spec).
The universal principle: define acceptance criteria before starting work, then use them to drive and validate the deliverable. The criteria format depends on the expert context. The discipline is the same.
For agents, this loop serves as a containment mechanism (Beck): without it, agents drift in scope, add unrequested features, and compound complexity.
TDD is a design technique, not a testing technique. Tests provide feedback on your design.
The outer loop (ATDD): Human writes BDD scenarios — acceptance tests from the user's perspective. They fail first and drive implementation. The inner loop (TDD): Write failing assertions, write minimum code to pass, refactor while green. The loops interleave — they are not sequential phases. The test-discipline skill defines the full discipline.
The same loop applies with different artifact formats: define acceptance checklist with evaluation rubric → draft the deliverable → review against the checklist → refine until it passes. The discipline skill for each practice domain defines the specific criteria.
These apply when the expert context is software engineering:
- Testability and deployability are design properties, not afterthoughts.
- Hexagonal Architecture (Ports & Adapters): Domain at the center, no framework dependencies. Dependencies point inward.
- Domain-Driven Design: Bounded contexts own their data and language. Ubiquitous language in all identifiers.
- Domain-Specific Languages: BDD scenarios in Gherkin for behavior. CLAUDE.md for project context. Area-specific CLAUDE.md for decomposed context.
The discipline core is always active and domain-agnostic. Skills add conditional guidance that activates per-project. Two categories:
- Technology skills — detected from project files (TypeScript, React, functional programming).
/acd:init-projectrecommends them automatically. - Practice skills — chosen by the user (C4, impact mapping, marketing-positioning, business-strategy, etc.).
/acd:init-projectpresents them as options. Practice skills provide domain expertise for non-software expert contexts.
Active skills are recorded in the project's CLAUDE.md under ## Active Stack Skills. Agents load them alongside the discipline core at session start. Skills reinforce ACD constraints — they never weaken them.
Skills are organized under skills/ by category: technology/, practices/, and discipline/. Technology skills are detected from project files. Practice skills are chosen by the user. Discipline skills encode the ACD rules and are loaded automatically when relevant.
Continuous Delivery is a discipline — not a replacement for domain expertise. This plugin provides the CD discipline layer. It does not orchestrate the full lifecycle (discovery, requirements, architecture, infrastructure, implementation). That is the job of an orchestration framework or the human operator.
When used with nWave (or any multi-agent orchestration framework):
- The orchestration framework coordinates what to build and when — phases, agents, sequencing.
- This plugin constrains how — session discipline, human-owned specifications, pipeline-restore mode, review gates, context hygiene.
- The plugin's rules apply INSIDE delivery sessions. They constrain what agents are allowed to do regardless of which phase they are in.
- The
expert-summoningdiscipline skill maps domains to the right nWave agent. Consult it when a task enters a specialized domain (architecture, security, marketing, research, etc.).
When used standalone (without an orchestration framework):
- The plugin provides the full CD workflow directly:
/acd:specify→/acd:start-session→/acd:review→/acd:end-session. - The human plays the orchestration role that a framework would otherwise fill.
- The
expert-summoningskill provides fallback guidance using ACD's own discipline skills when nWave agents are unavailable.
The universal workflow, in order:
/acd:specify— capture intent with hypothesis, generate delivery artifacts/acd:validate-spec— check consistency across all artifacts/acd:start-session— load one unit of work, assemble context/acd:review— quality gate before committing (4 coordinating review agents)/acd:end-session— validate gates, write summary, commit/acd:finalize— archive completed feature, check hypothesis
Supporting commands:
/acd:onboard— one-time user profiling (who you are, your goals, your domains) — run once after install/acd:init-project— generate a project-specific CLAUDE.md for the current repository/acd:fix— restore mode (while quality gate is red, only fix)/acd:maintenance— scheduled refactoring session/acd:security-audit— full-codebase security audit (4 layers, schedulable)/acd:evaluate— evaluate knowledge through the Engineering Critical Mind/acd:learn— learn new knowledge autonomously or from a resource/acd:become— goal-driven self-transformation (assess gaps, propose curriculum)/acd:sync-project— re-synchronize project config with current plugin version