atdd

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 to swingerman/engineer (formerly swingerman/atdd, then swingerman/disciplined-agentic-engineering). Old URLs still redirect; update remotes only if you want to: git remote set-url origin https://github.com/swingerman/engineer.git. The marketplace is still named disciplined-agentic-engineering — install refs (@disciplined-agentic-engineering) are unchanged.

---

Contents

Quick start · Install · Your first feature	Get running
How it works · The pipeline · Guardrails · Autonomy	The methodology
The three plugins · engineer · atdd · crap-analyzer	What's in the box
Host independence	Porting to another runtime
Why not vibe coding · Who it's for · Background	The argument
Repo layout · Contributing	Reference

---

Quick start

Install

On Claude Code:

/plugin marketplace add swingerman/engineer

/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/engineer.git
claude --plugin-dir ./engineer

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

#	Stage	Command	What happens
0	Onboard	/engineer.onboard	Once per project. Human signs off the charter (architecture, conventions, quality + autonomy stance); manifest and features/ layout produced.
1.5	Ready	/engineer.feature-init	feature.md records outcome, scope, owner, autonomy level, branch. The contract for what we're building.
2	ACs	/engineer.discover-acs	Four-pass interview — happy path, edges, errors & security, cross-cutting. Output acs.md in domain language. Reviewed by an adviser + devil's-advocate panel.
3	Spec	/engineer.atdd → atdd:atdd	ACs become standard Gherkin in spec.md; a project-specific test pipeline is generated. Leakage caught by spec-guardian.
4	Plan	/engineer.plan	Architecture plan + structured Charter Check. Human confirms the architecture before the rest drafts. Panel-reviewed.
5	Implement	/atdd:atdd-team	Fresh-per-phase agent team implements against the specs. Two test streams (acceptance + unit) must go green together.
6	Refine	/engineer.refine	Parallel review across Reuse / Quality / Efficiency, fed deterministic duplicate findings, filtered through the charter.
7	Verify	/engineer.arch-check + crap-analyzer	Architecture fitness (layering, cycles, forbidden patterns, naming, size) + change-risk on the diff. A different agent than the implementer.
8	Harden (optional)	/atdd:atdd-mutate	Differential mutation testing proves the unit tests actually catch bugs.

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:

Gate	Script	Enforces
Entry	dae_handoff.py	The prior checkpoint's handoff exists, status: complete, every exit criterion met
Branch	dae_branch.py	You're on the feature's branch (git.manual: true opts out)
Ontology	dae_ontology.py	Artifact-graph constraints — enumerations, AC↔scenario coverage, verifier ≠ implementer
Breadcrumb	dae_progress.py	Passive "you are here" across the pipeline + roadmap

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.

Script	Purpose
dae_resolve.py	Methodology-root + manifest resolver; central schema validation
dae_handoff.py	Handoff-as-gate; project-wide status survey
dae_branch.py	Branch hygiene at every checkpoint entry
dae_progress.py	Pipeline breadcrumb + roadmap position
dae_ontology.py	Artifact-graph constraint checks (see references/ontology.md)
dae_arch.py	Architecture fitness — layering, cycles (Tarjan's SCC), naming, file size
dae_impact.py	Test Impact Analysis — run only the scenarios a change affects
dae_mutmap.py	Differential mutation — re-mutate only what changed
dae_dup.py	Duplicate-code detection (jscpd by default, configurable), fed into Refine's Reuse lens
dae_gherkin.py	Portable Gherkin → IR parser (+ _convert, _mutate siblings)
dae_reconcile.py	Reconciles feature state against git/PR reality
dae_release.py	Version bump + cache sync for the plugins themselves
dae_commit.py	Commit with bounded retry and safe stale-lock removal
dae_roadmap.py · dae_tracker_local.py	Roadmap + tracker drivers
dae_delegable.py	Cloud-vs-local dispatch routing
dae_infra.py	Declared infrastructure probe / start / teardown
dae_introvert.py	Flags tests that pass without asserting on output
dae_fix.py	Bug-fix lifecycle + gap analysis

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.

Level	Behavior
low	Confirm before dispatching the next checkpoint. Review-everything mode.
medium	Auto-dispatch, announced in one line.
high	Auto-dispatch silently; report outcomes. "Agent, go cook."

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

At every step the entry gate verifies the prior handoff, the branch check verifies you're on image-upload, and the breadcrumb shows where you are in the pipeline and on the roadmap.

---

The three plugins

Plugin	Purpose	Version
engineer	The DAE methodology kit — 18 skills, 21 guardrail scripts, the checkpoint pipeline	0.21.0
atdd	ATDD workflow, team orchestration, differential mutation testing, portable Gherkin pipeline	0.8.2
crap-analyzer	Change Risk Anti-Pattern analysis on changed code	0.1.1

engineer — the methodology kit

Skill	Role
onboard	Project bootstrap — charter, manifest, tracker (CP0)
discuss	Upstream funnel — brainstorm; drop / park / promote
feature-init	Produces feature.md, folder, branch, tracker entry (CP1.5)
prime-context	Orient on a Ready feature before AC discovery
discover-acs	AC discovery interview → acs.md (CP2)
atdd	CP3 entry point — bridges into atdd:atdd
plan	Architecture plan + Charter Check → plan.md (CP4)
refine	Parallel reuse / quality / efficiency review (CP6)
arch-check	Architecture fitness — layering, cycles, naming, size (CP7)
fix	Bug lifecycle, with a "why didn't we catch it?" gap analysis
reorient	Mid-task re-anchoring after compaction or a long run
clarify	Single-artifact ambiguity resolution
consistency-check	Cross-artifact validation, read-only
feature-edit	Intent-driven edits with downstream cascade
progress-log	Handoffs → progress.md + tracker sync
session-summary	Per-session session-log.md entry
post-merge	Branch cleanup + state reconcile after a merge
next	Session-start survey — what to pick up now

Deeper detail lives in the repo, not here: engineer/skills/*/SKILL.md for each