https://github.com/matt-hulme/deliberate-agentic-development

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.
https://github.com/matt-hulme/deliberate-agentic-development

agentic-coding agentic-engineering agentic-workflow ai-agents ai-workflows claude-code code-quality codex cursor devtools human-in-the-loop linear product-management prompt-engineering software-development test-driven-development vibe-coding vibe-coding-assistant

Last synced: about 14 hours ago
JSON representation

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.

• Host: GitHub
• URL: https://github.com/matt-hulme/deliberate-agentic-development
• Owner: Matt-Hulme
• License: mit
• Created: 2025-09-30T17:33:08.000Z (7 days ago)
• Default Branch: master
• Last Pushed: 2025-09-30T17:58:59.000Z (7 days ago)
• Last Synced: 2025-09-30T19:23:06.025Z (7 days ago)
• Topics: agentic-coding, agentic-engineering, agentic-workflow, ai-agents, ai-workflows, claude-code, code-quality, codex, cursor, devtools, human-in-the-loop, linear, product-management, prompt-engineering, software-development, test-driven-development, vibe-coding, vibe-coding-assistant
• Homepage:
• Size: 34.2 KB
• Stars: 2
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE
  • Agents: AGENTS.md

Awesome Lists containing this project

README

          
**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

# Claude: Settings → Model Context Protocol → Add Linear

# Cursor: Settings → Features → MCP Servers → Add Linear

# Codex: Settings → Extensions → Add Linear MCP

```

**Pro tip:** If using multiple agents, install MCPs globally so all agents share the same connections.

### 2. Copy Files to Your Project

```bash

# Copy workflow files to your project

cp AGENTS.md /path/to/your/project/

cp -r .agents/ /path/to/your/project/

```

**What you're copying:**

- `AGENTS.md` → Root of your project (main workflow entry point)

- `.agents/` → Root of your project (all workflow files and templates)

### 3. Configure PRE-COMMIT-RULES.md

Edit `.agents/rules/PRE-COMMIT-RULES.md` with your actual validation commands:

```markdown

## Frontend Checks

- **format**: npm run format

- **lint**: npm run lint

- **typecheck**: npm run typecheck

```

### 4. Start Planning

Open your AI agent and say:

```

"Load AGENTS.md and let's start planning"

```

The agent will load the workflow system and guide you through project planning.

## File Structure

### Minimal Setup

What you start with:

```

your-project/

├── AGENTS.md                    # Main orchestrator

└── .agents/

    ├── PLAN.md                  # Planning orchestrator

    ├── PLAN-PROJECT.md          # Project planning workflow

    ├── PLAN-ISSUE.md            # Issue planning workflow

    ├── IMPLEMENT.md             # Implementation workflow

    ├── state.json               # Tracks progress

    ├── templates/               # Ready-to-use templates

    ├── documentation/

    │   ├── PRODUCT-OVERVIEW.md  # Your project vision

    │   ├── systems/             # Feature documentation (empty to start)

    │   └── project-archive/     # Completed project exports (empty to start)

    └── rules/

        └── PRE-COMMIT-RULES.md  # Your validation commands (REQUIRED)

```

### As Your Project Grows

After several milestones:

```

your-project/

├── AGENTS.md                    # Main orchestrator - loads first, coordinates everything

├── .agents/

│   ├── PLAN.md                  # Planning orchestrator - routes to project or issue planning

│   ├── PLAN-PROJECT.md          # Project planning - vision, tech stack, milestones

│   ├── PLAN-ISSUE.md            # Issue planning - task breakdown for all milestones

│   ├── IMPLEMENT.md             # Implementation - execute tasks, create commits, PRs

│   ├── state.json               # Current position tracker

│   ├── templates/               # All reusable templates

│   ├── documentation/

│   │   ├── PRODUCT-OVERVIEW.md    # Your project vision

│   │   ├── systems/

│   │   │   ├── AUTHENTICATION.md    # [CURRENT] OAuth, sessions, permissions

│   │   │   ├── NOTIFICATIONS.md     # [CURRENT] Email, push, in-app

│   │   │   ├── PAYMENTS.md          # [CURRENT] Stripe integration

│   │   │   ├── SEARCH.md            # [LEGACY] Moving to Elasticsearch

│   │   │   └── FILE-UPLOAD.md       # [CURRENT] S3, image processing

│   │   └── project-archive/

│   │       └── 2024-Q1-MVP-{{TICKET_PREFIX}}-100/  # Project name + parent ticket ID

│   │           ├── PARENT-TICKET.md  # {{TICKET_PREFIX}}-100 parent ticket

│   │           ├── {{TICKET_PREFIX}}-101.md        # Individual issue

│   │           ├── {{TICKET_PREFIX}}-102.md        # Individual issue

│   │           └── {{TICKET_PREFIX}}-103.md        # Individual issue

│   └── rules/

│       ├── PRE-COMMIT-RULES.md

│       ├── CORE-RULES.md

│       ├── API-RULES.md             # REST conventions, error codes

│       ├── DATABASE-RULES.md        # Schema patterns, migrations

│       ├── FE-RULES.md              # Frontend rules/patterns

│       ├── BE-RULES.md              # Backend rules/patterns

│       └── testing/

│           ├── frontend/

│           │   ├── FE-UNIT-TEST-RULES.md

│           │   ├── FE-INTEGRATION-TEST-RULES.md

│           │   └── FE-E2E-TEST-RULES.md

│           └── backend/

│               ├── BE-UNIT-TEST-RULES.md

│               ├── BE-INTEGRATION-TEST-RULES.md

│               └── BE-API-TEST-RULES.md

```

## Adapting to Your Tools

**Not using Linear?**

- Find/replace "Linear" → "Jira" (or your PM tool)

- Update ticket patterns ({{TICKET_PREFIX}}-XXX → PROJ-XXX)

**Not using GitHub?**

- Replace `gh` commands with GitLab/Bitbucket CLI

- Adjust PR creation commands in workflows

## Project Modes

Set during planning phase:

**Project Speed:**

- **FAST** (default) - Quick demos, manual testing only

- **SLOW** - Production quality, TDD workflow, full test coverage

**Project Types:**

- **NEW** - Starting from scratch

- **LEGACY** - Working with existing codebase (includes M0 analysis phase)

**Special Modes:**

- **FREEMODE** - Lightweight conversations without workflow loading

  - `FREEMODE START` - Skip all workflows, treat as normal chat

  - `FREEMODE END` - Resume normal workflow from AGENTS.md

## Documentation Organization

The `.agents/` system has three documentation areas:

### 1. System Documentation (`.agents/documentation/systems/*.md`)

**Agent-maintained** - Automatically created/updated during implementation

Documents how features work in your application:

- `AUTHENTICATION.md` - OAuth flows, sessions, permissions

- `NOTIFICATIONS.md` - Email, push, in-app systems

- `PAYMENTS.md` - Stripe integration, webhooks

- `FILE-UPLOAD.md` - S3, image processing

**Status tags:** `[CURRENT]` for active systems, `[LEGACY]` for systems being replaced

### 2. Rules Documentation (`.agents/rules/*.md`)

**User-controlled** - Agent can suggest, but you decide

Define coding patterns and conventions:

- `PRE-COMMIT-RULES.md` - **REQUIRED** - Validation commands

- `CORE-RULES.md` - Error handling, logging, config

- `API-RULES.md` - REST conventions, error codes

- `DATABASE-RULES.md` - Schema patterns, migrations

- `FRONTEND-RULES.md` - Component structure, state

- `BACKEND-RULES.md` - Service architecture

### 3. Testing Rules (`.agents/rules/testing/`)

**User-controlled, SLOW mode only**

Organize by stack layer:

```

testing/

├── frontend/

│   ├── FE-UNIT-TEST-RULES.md

│   ├── FE-INTEGRATION-TEST-RULES.md

│   └── FE-E2E-TEST-RULES.md

└── backend/

    ├── BE-UNIT-TEST-RULES.md

    ├── BE-INTEGRATION-TEST-RULES.md

    └── BE-API-TEST-RULES.md

```

### Structure Examples by Project Type

Full-Stack Web Application

```

.agents/

├── documentation/

│   ├── PRODUCT-OVERVIEW.md

│   └── systems/

│       ├── AUTHENTICATION.md          # OAuth, JWT, sessions

│       ├── API-GATEWAY.md             # Routing, rate limiting

│       ├── DATABASE.md                # Schema, migrations, ORM

│       ├── FRONTEND-STATE.md          # Redux/Zustand patterns

│       ├── NOTIFICATIONS.md           # Email, push, in-app

│       └── FILE-UPLOAD.md             # S3, image processing

└── rules/

    ├── PRE-COMMIT-RULES.md            # REQUIRED

    ├── CORE-RULES.md                  # Error handling, logging

    ├── API-RULES.md                   # REST conventions

    ├── DATABASE-RULES.md              # Schema patterns

    ├── FRONTEND-RULES.md              # Component structure

    ├── BACKEND-RULES.md               # Service architecture

    └── testing/

        ├── frontend/

        │   ├── FE-UNIT-TEST-RULES.md

        │   ├── FE-INTEGRATION-TEST-RULES.md

        │   └── FE-E2E-TEST-RULES.md

        └── backend/

            ├── BE-UNIT-TEST-RULES.md

            ├── BE-INTEGRATION-TEST-RULES.md

            └── BE-API-TEST-RULES.md

```

Backend-Only API Service

```

.agents/

├── documentation/

│   ├── PRODUCT-OVERVIEW.md

│   └── systems/

│       ├── AUTHENTICATION.md          # API keys, OAuth

│       ├── RATE-LIMITING.md           # Redis, token buckets

│       ├── DATABASE.md                # PostgreSQL, migrations

│       ├── CACHING.md                 # Redis strategy

│       └── QUEUE-PROCESSING.md        # Background jobs, workers

└── rules/

    ├── PRE-COMMIT-RULES.md            # REQUIRED

    ├── CORE-RULES.md                  # Error handling, logging

    ├── API-RULES.md                   # Endpoint conventions

    ├── DATABASE-RULES.md              # Schema, indexes

    └── testing/

        └── backend/

            ├── BE-UNIT-TEST-RULES.md

            ├── BE-INTEGRATION-TEST-RULES.md

            └── BE-API-TEST-RULES.md

```

Frontend-Only Application

```

.agents/

├── documentation/

│   ├── PRODUCT-OVERVIEW.md

│   └── systems/

│       ├── STATE-MANAGEMENT.md        # Zustand/Redux patterns

│       ├── ROUTING.md                 # React Router setup

│       ├── API-CLIENT.md              # Axios/fetch patterns

│       ├── AUTHENTICATION.md          # Token handling, refresh

│       └── UI-COMPONENTS.md           # Design system, shared components

└── rules/

    ├── PRE-COMMIT-RULES.md            # REQUIRED

    ├── CORE-RULES.md                  # Error handling, logging

    ├── COMPONENT-RULES.md             # Structure, naming, props

    ├── STYLING-RULES.md               # CSS conventions, Tailwind

    └── testing/

        └── frontend/

            ├── FE-UNIT-TEST-RULES.md

            ├── FE-INTEGRATION-TEST-RULES.md

            └── FE-E2E-TEST-RULES.md

```

Monorepo / Microservices

```

.agents/

├── documentation/

│   ├── PRODUCT-OVERVIEW.md

│   └── systems/

│       ├── SERVICE-MESH.md            # Inter-service communication

│       ├── AUTH-SERVICE.md            # Centralized auth

│       ├── USER-SERVICE.md            # User management

│       ├── PAYMENT-SERVICE.md         # Stripe integration

│       ├── NOTIFICATION-SERVICE.md    # Email/SMS service

│       └── API-GATEWAY.md             # Request routing

└── rules/

    ├── PRE-COMMIT-RULES.md            # REQUIRED

    ├── CORE-RULES.md                  # Cross-service patterns

    ├── API-RULES.md                   # REST/gRPC conventions

    ├── SERVICE-RULES.md               # Service boundaries

    ├── DATABASE-RULES.md              # Per-service DBs

    └── testing/

        ├── shared/

        │   └── INTEGRATION-TEST-RULES.md

        └── services/

            ├── AUTH-TEST-RULES.md

            ├── USER-TEST-RULES.md

            └── PAYMENT-TEST-RULES.md

```

## Troubleshooting

| Issue | Solution |

|-------|----------|

| "What is the state?" | Check `.agents/state.json` |

| "Validation failing" | Ensure PRE-COMMIT-RULES.md has real commands, not placeholders |

| "Wrong workflow" | Planning = PLAN.md, Implementation = IMPLEMENT.md |

| "Can't find Linear" | Install Linear MCP in your AI agent settings |

---

**License:** MIT - See [LICENSE](LICENSE) file for details.