deliberate-agentic-development

**Alpha Release** - This system has undergone significant refactoring and is actively being tested. Expect some rough edges and iteration as workflows are refined.

**Source-Available Repository** - This code is publicly available for reference and learning, but contributions are not accepted at this time. However, **feedback is welcomed and encouraged!** If you have suggestions, questions, or find issues, reach out on Twitter: [@MattHProgrammer](https://twitter.com/MattHProgrammer)

# Deliberate Agentic Development

A structured workflow system for AI coding agents like **Claude Code**, **Cursor**, and **Codex**. Guides AI assistants through software development with built-in checkpoints, reviews, and human oversight—keeping you in control from planning to shipping.

**Key Features:**
- **Structured Workflows** - Plan → Build → Ship with clear steps
- **Human-in-the-Loop** - Review and approve at every key decision
- **State Management** - Switch between agents seamlessly, they pick up where the last one left off
- **Linear Integration** - Full project tracking and task management
- **TDD Support** - Optional test-driven development mode

## Table of Contents

- [Overview](#overview)
- [Quick Setup](#quick-setup-4-steps)
- [File Structure](#file-structure)
- [Adapting to Your Tools](#adapting-to-your-tools)
- [Project Modes](#project-modes)
- [Documentation Organization](#documentation-organization)
- [Troubleshooting](#troubleshooting)

## Overview

Structured workflows for AI agents to plan and build software projects systematically:

- **Plan** - Vision → Tech stack → Milestones → Issues → Tasks
- **Build** - One task → One commit → One review → Repeat
- **Track** - State management + Linear integration for full visibility

## Quick Setup (4 steps)

### 1. Install Required Tools

```bash
# Install GitHub CLI (for PRs)
brew install gh  # macOS
# or see: https://cli.github.com

# Setup Linear MCP in your AI agent
# Cursor: Settings → Model Context Protocol → Add L