Deliberate Agentic Development — Summary

Deliberate Agentic Development is a structured workflow system for AI coding agents (Claude Code, Cursor, Codex) that delivers Plan → Build → Ship with mandatory human-review checkpoints, Linear project management integration, state persistence via state.json, and support for FAST/SLOW project modes (the latter enabling TDD).

Problem it solves: AI coding agents autonomously generate code without structured planning gates, human review points, or coordination with project management tools — leading to scope drift and lack of accountability.

Distinctive trait: Linear integration as first-class PM — the framework creates Linear issues, updates task statuses, and posts commit/PR details as Linear comments automatically, giving teams a fully connected project management trail alongside AI-driven code changes.

Target audience: Teams using Linear for project management + GitHub for code who want AI agents to plan and implement with full traceability and human oversight at every milestone.

Production-readiness: Alpha/active (26 GitHub stars, 1 contributor, last pushed October 2025, MIT license).

Differs from seeds: Closest to agent-os (Archetype 4 — markdown scaffold + workflow files) but adds Linear integration, state.json position tracking (so agents resume from exact position across sessions), and FAST/SLOW mode switching — none of which exist in agent-os.

Deliberate Agentic Development — Overview

Origin

Matt Hulme (independent developer, Twitter: @MattHProgrammer), released as an MIT-licensed "source-available, contributions not accepted" alpha. The framework is explicitly marked as undergoing active iteration.

Philosophy

Deliberate Agentic Development is built on the premise that AI coding agents need structured, human-supervised workflows to produce reliable software at team scale. The name "deliberate" captures the core philosophy: every step should be intentional, reviewed, and tracked — not just generated.

Manifesto-style quotes (verbatim from README)

"Structured workflows for AI agents. Guides Claude Code, Cursor, Codex, and other AI assistants through deliberate software development with checkpoints, reviews, and human oversight. Plan → Build → Ship with full control."

"FREEMODE allows you to temporarily disable all workflow rules and context loading when you need a lightweight conversation without the full agent system."

"MANDATORY FIRST STEPS - EXECUTE IN ORDER"

Design Choices

• state.json tracks exact project position (milestone, issue, task, branch) — agents can resume precisely
• Smart context loading: loads ALL rules in planning phase, selective rules in implementing phase (inferred from filename relevance)
• FAST vs SLOW mode: FAST (quick demos, manual testing only) vs SLOW (production quality, TDD, full test coverage)
• Linear as first-class PM tool (not optional): issues, task lists, comments, and PR details flow to Linear
• FREEMODE escape hatch: FREEMODE START disables all workflow rules without modifying state
• Agent-specific config loading: Claude → .claude/, Cursor → .cursor/, Codex → .codex/
• Documentation has three layers: system docs (agent-maintained), rules (developer-controlled), project archive

Deliberate Agentic Development — Architecture

Distribution

Standalone GitHub repo. No package manager. Install = copy AGENTS.md + .agents/ to project.

Install

cp AGENTS.md /path/to/your/project/
cp -r .agents/ /path/to/your/project/
# Edit .agents/rules/PRE-COMMIT-RULES.md with your validation commands

Directory Tree

your-project/
├── AGENTS.md                         # Main orchestrator (loaded first by AI)
└── .agents/
    ├── PLAN.md                        # Planning orchestrator
    ├── PLAN-PROJECT.md                # Project planning workflow
    ├── PLAN-ISSUE.md                  # Issue planning workflow
    ├── IMPLEMENT.md                   # Implementation workflow
    ├── state.json                     # Position tracker {milestone, issue, task, branch}
    ├── templates/                     # Reusable templates
    ├── documentation/
    │   ├── PRODUCT-OVERVIEW.md        # Project vision + tech stack
    │   ├── systems/                   # Feature docs (agent-maintained)
    │   │   └── *.md  [CURRENT|LEGACY]
    │   └── project-archive/           # Completed milestone archives
    └── rules/
        ├── PRE-COMMIT-RULES.md        # REQUIRED: validation commands
        ├── CORE-RULES.md
        ├── API-RULES.md
        ├── DATABASE-RULES.md
        └── testing/
            ├── frontend/
            └── backend/

Required Runtime

• gh CLI (for PRs)
• Linear MCP (for project management)
• Optional: any AI agent that reads AGENTS.md

Target AI Tools

Claude Code, Cursor, Codex (and any others). The framework auto-detects agent type and loads agent-specific config (.claude/, .cursor/, .codex/).

Config Files

• AGENTS.md — master workflow entry point
• .agents/state.json — position tracker
• .agents/rules/PRE-COMMIT-RULES.md — required validation commands
• .agents/documentation/PRODUCT-OVERVIEW.md — project vision

Deliberate Agentic Development — Components

Workflow Files

State Tracker

{
  "project_speed": "fast",
  "project_type": "new",
  "project_phase": "implementing",
  "current": {
    "milestone": "M3",
    "issue": "M3.1",
    "task": "M3.1.1",
    "branch": "{{TICKET_PREFIX}}-21"
  }
}

Documentation System (Agent-maintained)

Rules System (Developer-controlled)

External Integrations

• Linear MCP — create/update issues, tasks, comments, mark milestones done
• GitHub CLI (gh) — create PRs, auto-merge

Project Modes

Deliberate Agentic Development — Uniqueness

Differs from Seeds

Closest to agent-os (Archetype 4 — markdown scaffold + workflow files) but with three distinctive additions: (1) Linear integration as first-class PM — agent creates/updates Linear issues, posts commit and PR details as Linear comments, creating a bidirectional link between AI work and human-visible project management; (2) state.json position tracker — enabling precise resume across sessions (agent-os has no equivalent); (3) FAST/SLOW project mode — explicitly toggling TDD enforcement at project initialization time. Unlike kiro, this is not an IDE; unlike taskmaster-ai, the PM tool is Linear (external) rather than a local tasks.json. The FREEMODE escape hatch is a pragmatic design not found in other frameworks — acknowledging that full workflow loading is sometimes counterproductive.

Positioning

DAD positions as a "structured workflow system for AI agents" emphasizing human oversight at every key decision. It occupies the space between fully autonomous AI agents (too risky) and fully manual development (too slow).

Distinctive Opinion

The smart context loading decision tree is architecturally notable: it explicitly encodes token budget management as a workflow instruction — "infer relevance from filename, don't read content" — rather than relying on context compaction tools.

Observable Failure Modes

1. Linear dependency: The entire PM tracking breaks without Linear MCP configured; alternative PM tools require find/replace in workflow files
2. Single contributor: One maintainer, contributions not accepted — fork risk
3. Alpha quality: README warns of "rough edges and active iteration"
4. No auto-test execution: PRE-COMMIT-RULES.md must be manually configured; if not set up, validation gate is empty
5. GitHub-only PR creation: gh CLI dependency means GitLab/Bitbucket users must adapt