{"id":31580977,"url":"https://github.com/matt-hulme/deliberate-agentic-development","last_synced_at":"2025-10-07T02:22:59.438Z","repository":{"id":317416300,"uuid":"1067321767","full_name":"Matt-Hulme/deliberate-agentic-development","owner":"Matt-Hulme","description":"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.","archived":false,"fork":false,"pushed_at":"2025-09-30T17:58:59.000Z","size":35,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-09-30T19:23:06.025Z","etag":null,"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"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Matt-Hulme.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-09-30T17:33:08.000Z","updated_at":"2025-09-30T18:38:49.000Z","dependencies_parsed_at":"2025-10-01T10:00:26.372Z","dependency_job_id":null,"html_url":"https://github.com/Matt-Hulme/deliberate-agentic-development","commit_stats":null,"previous_names":["matt-hulme/deliberate-agentic-development"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Matt-Hulme/deliberate-agentic-development","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Matt-Hulme%2Fdeliberate-agentic-development","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Matt-Hulme%2Fdeliberate-agentic-development/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Matt-Hulme%2Fdeliberate-agentic-development/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Matt-Hulme%2Fdeliberate-agentic-development/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Matt-Hulme","download_url":"https://codeload.github.com/Matt-Hulme/deliberate-agentic-development/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Matt-Hulme%2Fdeliberate-agentic-development/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278526242,"owners_count":26001325,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-05T02:00:06.059Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2025-10-05T21:51:44.699Z","updated_at":"2025-10-05T21:51:47.461Z","avatar_url":"https://github.com/Matt-Hulme.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"**Alpha Release** - This system has undergone significant refactoring and is actively being tested. Expect some rough edges and iteration as workflows are refined.\n\n**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)\n\n# Deliberate Agentic Development\n\nA 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.\n\n**Key Features:**\n- **Structured Workflows** - Plan → Build → Ship with clear steps\n- **Human-in-the-Loop** - Review and approve at every key decision\n- **State Management** - Switch between agents seamlessly, they pick up where the last one left off\n- **Linear Integration** - Full project tracking and task management\n- **TDD Support** - Optional test-driven development mode\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Quick Setup](#quick-setup-4-steps)\n- [File Structure](#file-structure)\n- [Adapting to Your Tools](#adapting-to-your-tools)\n- [Project Modes](#project-modes)\n- [Documentation Organization](#documentation-organization)\n- [Troubleshooting](#troubleshooting)\n\n## Overview\n\nStructured workflows for AI agents to plan and build software projects systematically:\n\n- **Plan** - Vision → Tech stack → Milestones → Issues → Tasks\n- **Build** - One task → One commit → One review → Repeat\n- **Track** - State management + Linear integration for full visibility\n\n## Quick Setup (4 steps)\n\n### 1. Install Required Tools\n\n```bash\n# Install GitHub CLI (for PRs)\nbrew install gh  # macOS\n# or see: https://cli.github.com\n\n# Setup Linear MCP in your AI agent\n# Claude: Settings → Model Context Protocol → Add Linear\n# Cursor: Settings → Features → MCP Servers → Add Linear\n# Codex: Settings → Extensions → Add Linear MCP\n```\n\n**Pro tip:** If using multiple agents, install MCPs globally so all agents share the same connections.\n\n### 2. Copy Files to Your Project\n\n```bash\n# Copy workflow files to your project\ncp AGENTS.md /path/to/your/project/\ncp -r .agents/ /path/to/your/project/\n```\n\n**What you're copying:**\n- `AGENTS.md` → Root of your project (main workflow entry point)\n- `.agents/` → Root of your project (all workflow files and templates)\n\n### 3. Configure PRE-COMMIT-RULES.md\n\nEdit `.agents/rules/PRE-COMMIT-RULES.md` with your actual validation commands:\n\n```markdown\n## Frontend Checks\n- **format**: npm run format\n- **lint**: npm run lint\n- **typecheck**: npm run typecheck\n```\n\n### 4. Start Planning\n\nOpen your AI agent and say:\n```\n\"Load AGENTS.md and let's start planning\"\n```\n\nThe agent will load the workflow system and guide you through project planning.\n\n## File Structure\n\n### Minimal Setup\n\nWhat you start with:\n```\nyour-project/\n├── AGENTS.md                    # Main orchestrator\n└── .agents/\n    ├── PLAN.md                  # Planning orchestrator\n    ├── PLAN-PROJECT.md          # Project planning workflow\n    ├── PLAN-ISSUE.md            # Issue planning workflow\n    ├── IMPLEMENT.md             # Implementation workflow\n    ├── state.json               # Tracks progress\n    ├── templates/               # Ready-to-use templates\n    ├── documentation/\n    │   ├── PRODUCT-OVERVIEW.md  # Your project vision\n    │   ├── systems/             # Feature documentation (empty to start)\n    │   └── project-archive/     # Completed project exports (empty to start)\n    └── rules/\n        └── PRE-COMMIT-RULES.md  # Your validation commands (REQUIRED)\n```\n\n### As Your Project Grows\n\nAfter several milestones:\n```\nyour-project/\n├── AGENTS.md                    # Main orchestrator - loads first, coordinates everything\n├── .agents/\n│   ├── PLAN.md                  # Planning orchestrator - routes to project or issue planning\n│   ├── PLAN-PROJECT.md          # Project planning - vision, tech stack, milestones\n│   ├── PLAN-ISSUE.md            # Issue planning - task breakdown for all milestones\n│   ├── IMPLEMENT.md             # Implementation - execute tasks, create commits, PRs\n│   ├── state.json               # Current position tracker\n│   ├── templates/               # All reusable templates\n│   ├── documentation/\n│   │   ├── PRODUCT-OVERVIEW.md    # Your project vision\n│   │   ├── systems/\n│   │   │   ├── AUTHENTICATION.md    # [CURRENT] OAuth, sessions, permissions\n│   │   │   ├── NOTIFICATIONS.md     # [CURRENT] Email, push, in-app\n│   │   │   ├── PAYMENTS.md          # [CURRENT] Stripe integration\n│   │   │   ├── SEARCH.md            # [LEGACY] Moving to Elasticsearch\n│   │   │   └── FILE-UPLOAD.md       # [CURRENT] S3, image processing\n│   │   └── project-archive/\n│   │       └── 2024-Q1-MVP-{{TICKET_PREFIX}}-100/  # Project name + parent ticket ID\n│   │           ├── PARENT-TICKET.md  # {{TICKET_PREFIX}}-100 parent ticket\n│   │           ├── {{TICKET_PREFIX}}-101.md        # Individual issue\n│   │           ├── {{TICKET_PREFIX}}-102.md        # Individual issue\n│   │           └── {{TICKET_PREFIX}}-103.md        # Individual issue\n│   └── rules/\n│       ├── PRE-COMMIT-RULES.md\n│       ├── CORE-RULES.md\n│       ├── API-RULES.md             # REST conventions, error codes\n│       ├── DATABASE-RULES.md        # Schema patterns, migrations\n│       ├── FE-RULES.md              # Frontend rules/patterns\n│       ├── BE-RULES.md              # Backend rules/patterns\n│       └── testing/\n│           ├── frontend/\n│           │   ├── FE-UNIT-TEST-RULES.md\n│           │   ├── FE-INTEGRATION-TEST-RULES.md\n│           │   └── FE-E2E-TEST-RULES.md\n│           └── backend/\n│               ├── BE-UNIT-TEST-RULES.md\n│               ├── BE-INTEGRATION-TEST-RULES.md\n│               └── BE-API-TEST-RULES.md\n```\n\n\n## Adapting to Your Tools\n\n**Not using Linear?**\n- Find/replace \"Linear\" → \"Jira\" (or your PM tool)\n- Update ticket patterns ({{TICKET_PREFIX}}-XXX → PROJ-XXX)\n\n**Not using GitHub?**\n- Replace `gh` commands with GitLab/Bitbucket CLI\n- Adjust PR creation commands in workflows\n\n## Project Modes\n\nSet during planning phase:\n\n**Project Speed:**\n- **FAST** (default) - Quick demos, manual testing only\n- **SLOW** - Production quality, TDD workflow, full test coverage\n\n**Project Types:**\n- **NEW** - Starting from scratch\n- **LEGACY** - Working with existing codebase (includes M0 analysis phase)\n\n**Special Modes:**\n- **FREEMODE** - Lightweight conversations without workflow loading\n  - `FREEMODE START` - Skip all workflows, treat as normal chat\n  - `FREEMODE END` - Resume normal workflow from AGENTS.md\n\n## Documentation Organization\n\nThe `.agents/` system has three documentation areas:\n\n### 1. System Documentation (`.agents/documentation/systems/*.md`)\n\n**Agent-maintained** - Automatically created/updated during implementation\n\nDocuments how features work in your application:\n- `AUTHENTICATION.md` - OAuth flows, sessions, permissions\n- `NOTIFICATIONS.md` - Email, push, in-app systems\n- `PAYMENTS.md` - Stripe integration, webhooks\n- `FILE-UPLOAD.md` - S3, image processing\n\n**Status tags:** `[CURRENT]` for active systems, `[LEGACY]` for systems being replaced\n\n### 2. Rules Documentation (`.agents/rules/*.md`)\n\n**User-controlled** - Agent can suggest, but you decide\n\nDefine coding patterns and conventions:\n- `PRE-COMMIT-RULES.md` - **REQUIRED** - Validation commands\n- `CORE-RULES.md` - Error handling, logging, config\n- `API-RULES.md` - REST conventions, error codes\n- `DATABASE-RULES.md` - Schema patterns, migrations\n- `FRONTEND-RULES.md` - Component structure, state\n- `BACKEND-RULES.md` - Service architecture\n\n### 3. Testing Rules (`.agents/rules/testing/`)\n\n**User-controlled, SLOW mode only**\n\nOrganize by stack layer:\n```\ntesting/\n├── frontend/\n│   ├── FE-UNIT-TEST-RULES.md\n│   ├── FE-INTEGRATION-TEST-RULES.md\n│   └── FE-E2E-TEST-RULES.md\n└── backend/\n    ├── BE-UNIT-TEST-RULES.md\n    ├── BE-INTEGRATION-TEST-RULES.md\n    └── BE-API-TEST-RULES.md\n```\n\n### Structure Examples by Project Type\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eFull-Stack Web Application\u003c/strong\u003e\u003c/summary\u003e\n\n```\n.agents/\n├── documentation/\n│   ├── PRODUCT-OVERVIEW.md\n│   └── systems/\n│       ├── AUTHENTICATION.md          # OAuth, JWT, sessions\n│       ├── API-GATEWAY.md             # Routing, rate limiting\n│       ├── DATABASE.md                # Schema, migrations, ORM\n│       ├── FRONTEND-STATE.md          # Redux/Zustand patterns\n│       ├── NOTIFICATIONS.md           # Email, push, in-app\n│       └── FILE-UPLOAD.md             # S3, image processing\n└── rules/\n    ├── PRE-COMMIT-RULES.md            # REQUIRED\n    ├── CORE-RULES.md                  # Error handling, logging\n    ├── API-RULES.md                   # REST conventions\n    ├── DATABASE-RULES.md              # Schema patterns\n    ├── FRONTEND-RULES.md              # Component structure\n    ├── BACKEND-RULES.md               # Service architecture\n    └── testing/\n        ├── frontend/\n        │   ├── FE-UNIT-TEST-RULES.md\n        │   ├── FE-INTEGRATION-TEST-RULES.md\n        │   └── FE-E2E-TEST-RULES.md\n        └── backend/\n            ├── BE-UNIT-TEST-RULES.md\n            ├── BE-INTEGRATION-TEST-RULES.md\n            └── BE-API-TEST-RULES.md\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eBackend-Only API Service\u003c/strong\u003e\u003c/summary\u003e\n\n```\n.agents/\n├── documentation/\n│   ├── PRODUCT-OVERVIEW.md\n│   └── systems/\n│       ├── AUTHENTICATION.md          # API keys, OAuth\n│       ├── RATE-LIMITING.md           # Redis, token buckets\n│       ├── DATABASE.md                # PostgreSQL, migrations\n│       ├── CACHING.md                 # Redis strategy\n│       └── QUEUE-PROCESSING.md        # Background jobs, workers\n└── rules/\n    ├── PRE-COMMIT-RULES.md            # REQUIRED\n    ├── CORE-RULES.md                  # Error handling, logging\n    ├── API-RULES.md                   # Endpoint conventions\n    ├── DATABASE-RULES.md              # Schema, indexes\n    └── testing/\n        └── backend/\n            ├── BE-UNIT-TEST-RULES.md\n            ├── BE-INTEGRATION-TEST-RULES.md\n            └── BE-API-TEST-RULES.md\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eFrontend-Only Application\u003c/strong\u003e\u003c/summary\u003e\n\n```\n.agents/\n├── documentation/\n│   ├── PRODUCT-OVERVIEW.md\n│   └── systems/\n│       ├── STATE-MANAGEMENT.md        # Zustand/Redux patterns\n│       ├── ROUTING.md                 # React Router setup\n│       ├── API-CLIENT.md              # Axios/fetch patterns\n│       ├── AUTHENTICATION.md          # Token handling, refresh\n│       └── UI-COMPONENTS.md           # Design system, shared components\n└── rules/\n    ├── PRE-COMMIT-RULES.md            # REQUIRED\n    ├── CORE-RULES.md                  # Error handling, logging\n    ├── COMPONENT-RULES.md             # Structure, naming, props\n    ├── STYLING-RULES.md               # CSS conventions, Tailwind\n    └── testing/\n        └── frontend/\n            ├── FE-UNIT-TEST-RULES.md\n            ├── FE-INTEGRATION-TEST-RULES.md\n            └── FE-E2E-TEST-RULES.md\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eMonorepo / Microservices\u003c/strong\u003e\u003c/summary\u003e\n\n```\n.agents/\n├── documentation/\n│   ├── PRODUCT-OVERVIEW.md\n│   └── systems/\n│       ├── SERVICE-MESH.md            # Inter-service communication\n│       ├── AUTH-SERVICE.md            # Centralized auth\n│       ├── USER-SERVICE.md            # User management\n│       ├── PAYMENT-SERVICE.md         # Stripe integration\n│       ├── NOTIFICATION-SERVICE.md    # Email/SMS service\n│       └── API-GATEWAY.md             # Request routing\n└── rules/\n    ├── PRE-COMMIT-RULES.md            # REQUIRED\n    ├── CORE-RULES.md                  # Cross-service patterns\n    ├── API-RULES.md                   # REST/gRPC conventions\n    ├── SERVICE-RULES.md               # Service boundaries\n    ├── DATABASE-RULES.md              # Per-service DBs\n    └── testing/\n        ├── shared/\n        │   └── INTEGRATION-TEST-RULES.md\n        └── services/\n            ├── AUTH-TEST-RULES.md\n            ├── USER-TEST-RULES.md\n            └── PAYMENT-TEST-RULES.md\n```\n\n\u003c/details\u003e\n\n## Troubleshooting\n\n| Issue | Solution |\n|-------|----------|\n| \"What is the state?\" | Check `.agents/state.json` |\n| \"Validation failing\" | Ensure PRE-COMMIT-RULES.md has real commands, not placeholders |\n| \"Wrong workflow\" | Planning = PLAN.md, Implementation = IMPLEMENT.md |\n| \"Can't find Linear\" | Install Linear MCP in your AI agent settings |\n\n---\n\n**License:** MIT - See [LICENSE](LICENSE) file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatt-hulme%2Fdeliberate-agentic-development","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatt-hulme%2Fdeliberate-agentic-development","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatt-hulme%2Fdeliberate-agentic-development/lists"}