Disciplined Agentic Engineering (DAE)

A methodology kit for engineering-led AI development — spec-driven, test-driven, charter-bound. ATDD + mutation testing + deterministic guardrails.

AI agents do the typing. Engineers stay in charge of architecture, behavior contracts, and verification. DAE puts the discipline in deterministic tools the agent has to satisfy — not in prompt rules that erode over long runs.

The methodology is host-independent. It ships today as three plugins for Claude Code, the reference host — see Host independence.

ℹ️ Repo renamed from swingerman/atdd. Old URLs still redirect; update remotes only if you want to: git remote set-url origin https://github.com/swingerman/disciplined-agentic-engineering.git

Contents

Quick start

Install

On Claude Code:

/plugin marketplace add swingerman/disciplined-agentic-engineering

/plugin install engineer@disciplined-agentic-engineering      # the DAE methodology kit
/plugin install atdd@disciplined-agentic-engineering          # ATDD + differential mutation testing
/plugin install crap-analyzer@disciplined-agentic-engineering # change-risk analysis

Or run from a clone:

git clone https://github.com/swingerman/disciplined-agentic-engineering.git
claude --plugin-dir ./disciplined-agentic-engineering

Your first feature

/engineer.onboard        # once per project — charter, manifest, tracker
/engineer.next           # every session — "what should I pick up?"
/engineer.discuss        # an idea → drop, park, or promote to a feature

From there the pipeline tells you the next command at every step. Each checkpoint ends with a handoff naming what comes next, and /engineer.next reconstructs that at any time.

How it works

DAE operates on features — numbered folders that accumulate a stack of progressively-sharper specs, Speckit-style:

feature.md  →  acs.md   →  spec.md   →  plan.md
intent         behavior     Gherkin      architecture
               (domain      (executable)
                language)

Each layer is reviewed and approved before the next is written, and constrains the ones below it. The folder also holds handoffs/ (the audit trail) and .build/ (generated IR and pipelines).

The pipeline

Eight checkpoints, each gated on the previous one's handoff:

0 Onboard → 1.5 Ready → 2 ACs → 3 Spec → 4 Plan → 5 Implement → 6 Refine → 7 Verify → 8 Harden

Cross-cutting, any time: clarify · consistency-check · feature-edit · progress-log · reorient · session-summary · next.

The guardrails

Every checkpoint is gated by tools, not by prompt rules. An agent can talk itself out of an instruction; it cannot talk itself out of a non-zero exit code. At each checkpoint's Step 0:

All 21 scripts are stdlib-only Python 3, each with a test_*.py sibling — 483 tests. No dependencies is a deliberate portability constraint, not an aesthetic one.

Handoffs

Every agentic task ends with a structured handoff — frontmatter plus body — carrying its checkpoint, artifacts, exit-criteria assertions, panel findings, and recommended_next. Two jobs:

• You know when to re-engage after walking away.
• The next checkpoint's entry gate uses it to decide whether it may proceed.

A checkpoint is not done until its handoff says so and the tools agree.

Tunable autonomy

Every feature carries an explicit autonomy level — how much the agent decides alone versus asking for sign-off. Set at feature-init, recorded in feature.md, constrained project-wide by .engineer/manifest.yml's autonomy.allowed_levels, tightened for sensitive paths (security, billing) via path overrides.

Some gates ignore the dial: plan always asks the human to confirm the architecture, and outward-facing writes (pushing to main, opening or merging PRs, self-modifying agent config, writing to live systems) always require explicit authorization — even at high.

# Session 1 — idea to spec
$ /engineer.discuss
  [brainstorm: "add image upload to user profile"] → promote (autonomy: medium)
  Created features/015-image-upload/{feature.md, handoffs/, .build/} + branch

$ /engineer.discover-acs
  [four-pass interview] → acs.md, 8 ACs in domain language
  [adviser + advocate panel] → 2 findings, 1 accepted
  Handoff → human review

$ /engineer.atdd
  → spec.md (4 scenarios, standard Gherkin) + .build/spec.json + test pipeline

# Session 2 — plan and build
$ /engineer.plan
  [agent proposes architecture; human confirms; rest drafts]
  → plan.md (Charter Check: 0 deviations)

$ /atdd:atdd-team
  [fresh agent per phase] → both test streams green
  [refine → arch-check → crap-analyzer → differential mutation]

# Session 3 — wrap
$ /engineer.session-summary
  → session-log.md, next-tasks: open the PR

The three plugins

engineer — the methodology kit

Deeper detail lives in the repo, not here: engineer/skills/*/SKILL.md for each skill's workflow and exit contract, and engineer/references/ for the shared contracts — handoff schema, progress indicators, review panel, model classes, host capabilities, ontology, parallelism, and more.

atdd — Acceptance Test Driven Development

"Specs will be co-authored by the humans and the AI, but with final approval, ferociously defended, by the humans." — Robert C. Martin

Packages Robert C. Martin's approach to applying ATDD against agentic AI coding, as developed in empire-2025.

Two problems it solves. Without acceptance tests anchoring behavior, an agent "willy-nilly plops code around" and writes unit tests that pass without verifying anything worthwhile. And left alone, agents fill Given/When/Then with class names, endpoints, and table names instead of domain language.

/atdd:atdd Add user authentication with email and password
/atdd:spec-check     # audit specs for implementation leakage
/atdd:mutate         # verify the tests actually catch bugs
/atdd:kill-mutants   # write tests targeting survivors

The Golden Rule: specs describe what the system does, never how.

1. Write Given/When/Then specs — natural language, domain only
2. Generate the test pipeline (parser → IR → test generator),
   which has deep knowledge of your codebase internals
3. Run acceptance tests → they FAIL (red)
4. Implement with TDD until BOTH streams pass
5. Review specs for implementation leakage
6. Mutation testing → verify the tests actually catch bugs
7. Next feature, back to 1

Feature: User registration

Scenario: User can register with email and password
  Given no registered users
  When a user registers with email "bob@example.com" and password "secret123"
  Then there is 1 registered user
  And the user "bob@example.com" can log in

Three validation layers, each answering a different question:

Differential mutation testing keeps layer 3 affordable: dae_mutmap.py maintains a committed manifest keyed by function, and re-mutates one only when its code, its covering tests, or the operator set changed. The hash triple makes the cache safe to share across CI, fresh clones, and every developer.

crap-analyzer — change risk

Change Risk Anti-Pattern analysis over changed code: complexity × lack of coverage, scoped to a diff. Multi-language. Part of Checkpoint 7 alongside arch-check.

Host independence

DAE is a methodology, not a set of host features wearing a methodology's name. The pipeline, the checkpoint contract, the artifact schemas, and the dae_*.py guardrails are host-independent by construction — stdlib-only Python 3 with no dependencies, precisely so that stays true.

What is host-specific is the mechanism each capability is reached through. The skills name Claude Code's mechanisms directly ("dispatch via the Agent tool") because that's the host they run on today — but those names are bindings, not the contract. engineer/references/host-capabilities.md holds the seam:

Every optional capability has a specified degradation, so a host that lacks one loses a convenience, never the methodology. Porting is editing that table's binding column, plus the plugin-root path prefix and the host hook examples.

The same discipline applies to models: engineer/references/model-classes.md names capability classes — economy / inherit / frontier — rather than product names, which get deprecated, and resolves them against the host's live model list at dispatch time.

Optional capabilities are used when present and never depended on. A rendered board is a better answer to "where are we" than four lines of breadcrumb, so DAE offers one where the host can publish views — and always emits the terminal text regardless.

Why not vibe coding

Vibe coding is prompting loosely — "build me a thing that does X" — accepting what comes back, running it, patching when something feels off. No charter, no behavior contract, no verification gates. Fast at first, brittle over time: the codebase drifts, tests pass without proving anything, regressions surface when users find them.

Shipping something quick and disposable? Vibe coding is fine. Building something you intend to maintain — with agents helping without eroding what they touch? That's what this is for.

The headline outcome is semantic stability. ATDD plus mutation testing form a semantic firewall: code can be refactored, extended, or rewritten by agents without the system's intended behavior drifting.

Who it's for

Software engineers. DAE assumes you can read a plan.md and judge whether the architecture is sound; read a Gherkin spec and tell whether it captures intent; know when a charter rule should be enforced versus amended.

Not for non-programmers. "Build an app without code" tools target a different audience and a different problem. The decisions DAE puts in front of you — architecture, behavior contracts, charter rules, verification thresholds, autonomy levels — are engineering decisions that need engineering judgment.

Background & influences

Programming has always climbed the abstraction ladder: front-panel switches → punch cards → assembly → high-level languages → managed runtimes → and now, with capable LLMs, specification and behavior description as the next rung. At every step the rung below fades from daily concern. Nobody hand-writes opcodes; nobody audits the assembly a compiler emits.

What never shifts is engineering discipline. Compiler output earned trust because the compiler was rigorous and the inputs were checked. AI-generated code earns it the same way: rigorous input artifacts (charter, ACs, specs, plans) and checked output (two test streams, mutation testing, architecture fitness, change risk, duplicate and cycle detection). Change the artifact you author but stop checking the output, and you don't get speed — you get a faster path to a brittle system.

DAE synthesizes four sources:

Two further debts to Uncle Bob's public writing on ATDD, SDD, and AI-assisted development: the swarm-failure observations that drove DAE's deterministic-guardrail philosophy, and the differential-mutation post that shaped dae_mutmap.py.

DAE's own additions: the Ready contract, autonomy levels, verification independence, the handoff / exit-criteria contract, the artifact ontology, the review panel, and the deterministic dae_*.py guardrails.

This marketplace contains no code from empire-2025 or other upstream projects — it adapts the methodology.

Repo layout

.
├── .claude-plugin/          # marketplace + atdd plugin manifests
├── agents/ commands/        # atdd plugin agents and commands
├── hooks/ references/       # atdd plugin hooks and references
├── skills/                  # atdd plugin skills (atdd, atdd-team, atdd-mutate)
│
├── engineer/                # the DAE methodology kit
│   ├── references/          # shared contracts — handoff, ontology, panel,
│   │                        #   model classes, host capabilities, parallelism
│   ├── scripts/             # dae_*.py guardrails + their unit tests
│   ├── skills/              # the 18 engineer skills
│   └── examples/            # optional host hook configs
│
└── crap-analyzer/           # change-risk analysis plugin

Contributing

Issues and PRs welcome on GitHub.

License

MIT