DeviaTDD

An agent-orchestration framework that runs your entire TDD loop — explore, spec, red, green, refactor — with two hard human-in-the-loop gates (design/contract review and merge review); shard is a soft review.

DeviaTDD is a CLI that coordinates AI coding agents across the full Test-Driven Development lifecycle, from problem framing through documentation. It ships with a three-layer architecture (Macro · Meso · Micro), append-only ledgers, worktree isolation, and path-scoped GREEN writes. The system is agent-agnostic — Claude Code, OpenCode, Pi, Droid, the Factory Droid IDE, and Oh-My-Pi are first-class backends today.

Why DeviaTDD?

Most AI coding agents stop at "write code that passes." DeviaTDD goes further — it runs the entire engineering loop with verification, not just generation:

Quickstart

# Install (requires Python 3.13+ and uv).
# The PyPI package is `deviatdd`; the CLI binary it installs is `deviate`.

uv tool install deviatdd
deviate --version

# Writes .deviate/, persists the agent, installs default packs
# (including deviate-init) and the shared deviatdd skill.
# Does not write specs/constitution.md, mise.toml, or specs/issues.jsonl.
deviate setup --agent pi     # or: claude | opencode | droid | factory | omp | codex

--agent skips only the agent picker. A TTY still asks [l]ocal/[g]lobal, then claim-remote [y]es/[n]o (default n), then a pack checklist (Enter = none). Skip those with --agent-export-mode local|global --packs none --no-claim-remote.

Where files go (Pi)

Global still writes cwd .deviate/. Other agents: local is <repo>/.<agent>/…; global is ~/.<agent>/… (Codex: ~/.agents/skills).

First hour

Open the agent and run /deviate-init as the first prompt. That scaffolds specs/constitution.md, mise.toml, and specs/issues.jsonl, skipping anything already present.

• Pi: /deviate-init is a prompt template from deviate-init.md, not the deviatdd skill. The skill is /skill:deviatdd (micro loop).
• Codex: the same prompt, installed as the deviate-init skill.
• No agent: deviate init pre && deviate init post stages constitution / mise / issues.jsonl; it does not commit.

Empty CLAUDE.md / AGENTS.md after setup is expected.

Then drive the rest of the lifecycle from inside your agent. Each phase emits a single artifact; post often commits it (you did not type git commit). At the two gates the workflow pauses for human review. See Phase transparency for which commands commit, spawn, or fail closed.

Macro — pick one of two paths. Full path for new features, the adhoc shortcut for low/medium-complexity tasks:

# Full path: feature scoping with a Gate 1 design review
/deviate-explore "Add user authentication via OAuth2"
/deviate-research                          # ← Gate 1: review design.md + data-model.md
/deviate-prd
/deviate-shard                             # ← review every ISS-NNN spec-enriched issue (soft review — system auto-advances to Meso; not a hard HITL gate)

# — or — Adhoc shortcut for low/medium-complexity work
/deviate-adhoc "Add a /healthz endpoint"   # condenses explore+research+prd+shard into one issue

Meso — claim the issue and enter its worktree. Default meso uses a worktree. claim_remote defaults false (local claim only; no push lock). Path A coworker flow stays in this clone: deviate meso run --no-setup --local. Meso slash commands run inside the per-issue worktree; claim first, then cd in:

# From the main checkout (NOT inside a worktree):
deviate specify                            # auto-claim the next unblocked BACKLOG issue, create .worktrees/<branch>/, print the path
#   or, to claim a specific issue by ID:
deviate specify ISS-001-007                # claim that exact issue; same worktree creation
cd $(deviate specify ISS-001-007 2>&1 | grep '^WORKTREE' | awk '{print $2}')
                                           # then re-open the agent inside the worktree

# Path A (this clone, no worktree, no remote lock):
deviate meso run --no-setup --local --issue ISS-001-007

Meso — with the worktree active, decompose into tasks. tasks.md is the human's execution blueprint:

# Now INSIDE the worktree:
/deviate-plan                              # per-issue localized research → plan.md
/deviate-tasks                             # → tasks.md: 4-8 tasks, each with Verification CLI
                                           #   TDD tasks flow to the Red→Green→Judge→Refactor loop;
                                           #   IMMEDIATE tasks flow to /deviate-execute

Micro — for each task, pick the loop that fits:

# TDD cycle (default for TDD-typed tasks)
/deviate-red      T001                   # write a failing test
/deviate-green    T001                   # implement it; GREEN is bounded to src/ + permitted paths
/deviate-judge    T001                   # Gate decision; on rejection, the
                                         # Green → Judge → Green loop kicks in
                                         # (revert + <train_feedback> → re-GREEN, up to 3x)
/deviate-refactor T001                   # only on JUDGE_PASS

# — or — Direct path for low-complexity tasks (boilerplate, config, trivial fixes)
/deviate-execute  T002                   # skips the TDD cycle; still has its own JUDGE pass

Release — close the loop. /deviate-pr, /deviate-review, and /deviate-walkthrough are optional packs (not in default setup):

/deviate-pr       T001                   # conventional-commit PR; merge appends COMPLETED
/deviate-review                          # ← Gate 3: comments-only PR scan (not a merge gate)
/deviate-walkthrough                     # four-look map (brief, tests, production vs checks, command)

Or, run the unattended one-shot pipeline — the top-level deviate run is the unattended drain that replaces the Meso · Claim, Meso · Plan, Meso · Tasks, and Micro steps above with a single command. It discovers the next BACKLOG issue, claims it (creating the per-issue worktree), runs SPECIFY → PLAN → TASKS in the worktree, then drains every PENDING task through the TDD cycle. Under the hood it chains deviate meso run with deviate micro run --all inside the created worktree. Use it when you trust the agent to run end-to-end; use the manual Meso + Micro blocks above when you want to review plan.md and tasks.md between phases:

deviate run                              # full pipeline (meso + micro --all)
deviate run --issue ISS-001-007          # target a specific BACKLOG issue
deviate run --profile fast               # skip JUDGE + REFACTOR in the micro drain
deviate run --no-judge --no-refactor     # same, via boolean overrides

For per-task or deviate micro run --all invocations inside an already-claimed worktree, see deviate micro run: top-level run does both meso and micro for you; the per-task dispatcher is deviate micro run <task-id> and the queue drain is deviate micro run --all.

The full lifecycle takes you from a problem statement to merged, tested code with a documented audit trail.

Architecture: Three Layers, Two Gates

flowchart TB
subgraph Macro["Macro Layer — Feature Scoping"]
  E[explore] --> Re[research]
  Re --> P[prd]
  P --> S[shard]
  E -.->|low/medium complexity| Ad[adhoc]
end

subgraph Meso["Meso Layer — Issue Engineering"]
  Pl[plan] --> T[tasks]
end

subgraph Micro["Micro Layer — Per-Task Loop"]
  T --> Re1[red]
  Re1 --> G1[green]
  G1 --> J{judge}
  J -->|violation| G1
  J -->|pass| Rf[refactor]
  Rf -.->|HITL Gate 3| Done[merged]
end

subgraph MicroAlt["Micro Layer — Direct Path (low-complexity tasks)"]
  T -.->|complexity ≤ 3| Ex[execute]
end

style E fill:#e1f5e1
style Re fill:#e1f5e1
style P fill:#e1f5e1
style S fill:#e1f5e1
style Ad fill:#e1f5e1
style Pl fill:#e1e7f5
style T fill:#e1e7f5
style Re1 fill:#f5e1e1
style G1 fill:#f5e1e1
style J fill:#f5e1e1
style Rf fill:#f5e1e1
style Ex fill:#f5e1e1

Workflow at a Glance

Operational tools (no gate): /deviate-triage, /deviate-constitution, /deviate-hotfix. /deviate-prune is the manual honeycomb test-thinning surface (thin CLI deviate prune pre / post; the slash command commits the cleanup).

Phase transparency

--help and this table say which phases commit, spawn an agent, or fail closed. pre injects a JSON contract to the agent; post validates, writes, and often commits (you did not type git commit). Slash prompts tell the agent to run pre/post; auto prompts tell the agent not to — the orchestrator does. Codex spawn is codex exec --sandbox workspace-write --ask-for-approval never (src/deviate/core/agent.py). meso run and micro run nest that spawn.

Default setup installs macro + meso + micro plus the shared deviatdd skill. Optional packs stay off until selected: product (greenfield scope tracking: /deviate-flows, /deviate-architecture, /deviate-release), merge, pr, review, walkthrough, html, hotfix, triage, prune, e2e.

Why each phase exists — and the research citations — live in docs/rationale.md.

Troubleshooting

uv: command not found — Install uv first (it's the project's mandated package manager per specs/constitution.md). macOS / Linux: curl -LsSf https://astral.sh/uv/install.sh | sh.

deviate: command not found after uv tool install deviatdd — Verify the install landed: uv tool list | grep deviatdd. Reinstall if missing: uv tool install --reinstall deviatdd. The PyPI package name and the CLI binary name differ — that's intentional (see Quickstart).

deviate setup runs but /deviate-* commands don't appear in the agent — Slash commands are installed to <workdir>/.claude/commands/, .opencode/commands/, .omp/commands/, .factory/commands/, .pi/prompts/, and (Pi global) ~/.pi/agent/prompts/. Verify the directory exists and is readable, then restart the agent so it picks up the new commands.

Empty CLAUDE.md / AGENTS.md after setup — Expected. Setup creates the files (and the symlink) but does not seed project guidance. Init scaffolds specs/constitution.md, mise.toml, and specs/issues.jsonl.

--agent did not skip the local/global, lock, or pack prompts — --agent skips only the agent picker. Use --agent-export-mode local|global --packs none --no-claim-remote to skip the TTY extras.

/deviate-plan (or /deviate-tasks) picks up the wrong issue, claims "no active issue", or shows stale context — Meso slash commands must be invoked from inside the per-issue worktree that deviate specify (or deviate run) created. From the main checkout, run deviate specify (or deviate specify ISS-NNN-NNN for a specific issue), cd into the .worktrees/<branch>/ path it prints, and re-open the agent there before running /deviate-plan or /deviate-tasks.

mise run publish fails with PYPI_API_TOKEN is not set — The task loads .env from the project root. .env must contain PYPI_API_TOKEN=pypi-.... .env.example documents the variable name; .env itself is gitignored.

Agent backend not installed — deviate setup --agent <name> scaffolds the project without the agent present, but invoking /deviate-* slash commands requires the agent to be installed. Install Claude Code / OpenCode / Pi / Droid / Factory / OMP first per their respective install instructions.

For development-setup details, see CONTRIBUTING.md and specs/constitution.md.

License

MIT © 2026 Werner Bisschoff