A formal, governed documentation system for AI-assisted project execution.
Turn AI coding assistants into reliable project executors through structured specs, clear boundaries, and explicit human review.
The AI Project System has completed Phase P1 (System Foundation & Adoption) and is now production-ready for adoption in other projects.
✅ 5 Milestones completed (M1-M5)
✅ 12 Epics delivered
✅ Governance stable (v1.5.0 / v1.4.1)
✅ Battle-tested through dogfooding
✅ Ready to reference from panchew/ai-project-system master
Phase P1 Closed: 2026-02-23
Consolidation PR: #21
AI coding assistants are powerful but chaotic:
❌ Context is lost across conversations
❌ Scope creeps without clear boundaries
❌ Quality varies without standards
❌ Handoffs fail between humans and AI
❌ Decisions disappear into chat history
Traditional project management assumes human-to-human communication. AI needs a different approach.
The AI Project System provides structure without rigidity:
✅ Structured specs preserve context across sessions (Phase → Milestone → Epic)
✅ Authoritative documentation replaces ephemeral chat history
✅ Clear execution boundaries define when AI starts, delivers, and stops
✅ Explicit human review ensures quality and alignment
✅ Version-controlled decisions document intent and rationale
You get AI speed with human governance.
This repository contains the canonical AI Project System used to structure, document, and execute software projects with AI assistance.
It defines:
- Authoritative governance documents
- A Phase–Milestone–Epic execution model
- A documentation-first workflow
- Explicit context management for AI agents
This is not an application.
It is a system for managing projects.
This system is designed for:
- Engineers using AI tools (ChatGPT, GitHub Copilot, Cursor, Claude, etc.)
- Projects where context, scope, and delivery matter (not throwaway prototypes)
- People who want repeatability, not improvisation (structure over chaos)
Prerequisites:
- Git and GitHub (basic familiarity)
- Markdown editing
- AI chat tool access
- Willingness to trade upfront planning for execution clarity
Not for:
- Pure exploratory coding
- Single-file scripts
- Projects without AI assistance
Hierarchical structure that breaks work into manageable, deliverable units:
- Phases: Major segments (e.g., "Foundation", "Feature Development")
- Milestones: Cohesive increments (collection of related Epics)
- Epics: Atomic deliverable work (complete, reviewable, mergeable)
Purpose-built for AI coding assistants:
- Epic Execution Chat Starters provide complete context
- AI agents execute autonomously within guardrails
- Documentation preserves context across sessions
Clear separation of responsibilities:
- Humans (HQ): Define goals, review work, make accept/reject decisions
- AI (Coding Agents): Execute work, produce deliverables, document completion
- Explicit authorization required for merging
Version-controlled, authoritative specs:
- Chat is ephemeral, Markdown is truth
- Governance documents define rules and procedures
- Specs define goals, deliverables, and success criteria
Defined Epic lifecycle prevents chaos:
- HQ creates Epic Spec
- AI executes Epic
- AI produces Delivery Notice and stops
- Human reviews deliverables
- HQ accepts/rejects/requests changes
- HQ authorizes merge (if accepted)
- AI merges and stops
Every Epic has explicit completion criteria:
- Deliverables checklist
- Acceptance criteria for human review
- Success metrics
New to the system? Get started in 30 minutes:
The guide walks you through:
- Initializing repository structure
- Creating your first Phase, Milestone, and Epic
- Executing an Epic with AI assistance
- Reviewing and closing your first Epic
Time: 30 minutes
Outcome: Complete understanding through practice
Understand the system visually:
- 🔄 Epic Lifecycle Flow — How Epics move from idea to closure
- 📊 Authority Hierarchy — Which documents have precedence
- 📁 Repository Structure — Where everything lives
- 🚀 Quick Start Guide — 30-minute walkthrough
- 📖 PROJECT-SYSTEM-GUIDELINES.md — System structure and governance
- 🤖 AI-OPERATING-GUIDELINES.md — Execution procedures
- 🎨 Visual Diagrams — Epic lifecycle, authority, structure
- 🏗️ How to Start a Project — Initialize new projects
- 📝 Templates — Phase, Milestone, Epic templates
- 📋 Template Usage Guide — How to use templates
- ⚙️ Epic Execution Chat Starter System — How to run Epics
- 👔 HQ Chat Guide — Human responsibilities
- 📚 Phase P1 Examples — Real Epic specs and completions
- 🔍 See how this system was built using itself
- 🏛️ Governance Propagation — How governance flows
- 🗺️ Project Tracker Integration — Tracker usage
Create an Epic Spec defining:
- Problem statement
- Goals and deliverables
- Definition of Done
- Acceptance criteria
Launch AI Coding Agent with Epic Execution Chat Starter:
- Agent creates branch
- Agent builds deliverables
- Agent self-validates against DoD
- Agent produces Delivery Notice and stops
Evaluate deliverables:
- Does it meet acceptance criteria?
- Does it solve the stated problem?
- Is quality acceptable?
Make decision:
- Accept: HQ authorizes merge → AI merges → Epic closed
- Reject: Document rationale → create new Epic or abandon
- Request Changes: Define iteration → AI updates
| Traditional Project Management | AI Project System |
|---|---|
| Jira tickets | Epic Specs (Markdown) |
| Standup meetings | Epic Delivery Notices |
| Verbal context | Documentation (version-controlled) |
| Manager assigns work | Human creates spec, AI executes |
| Code reviews | Human reviews + Epic Review Seals |
| "Done when merged" | "Done when DoD verified + accepted + merged" |
| Continuous communication | Async, documented handoffs |
| Human assumes context | AI reads authoritative docs |
Key difference: Traditional PM assumes humans retain context. AI Project System assumes context must be explicitly documented.
What you get:
- ✅ Structure — Clear boundaries for AI execution (no scope creep)
- ✅ Repeatability — Same process for every Epic, predictable outcomes
- ✅ Context preservation — Documentation survives session boundaries
- ✅ Quality control — Explicit review and acceptance gates
- ✅ AI speed — Autonomous execution once spec is clear
What you give up:
- ❌ Improvisation — Must plan before executing
- ❌ Verbal context — Everything must be written down
- ❌ Continuous iteration — Changes require spec updates
Who should use this:
- Engineers building production systems with AI assistance
- Projects where context loss has caused rework
- Teams wanting predictable AI execution
- People who value structure over chaos
Who should NOT use this:
- Pure exploratory coding (no clear deliverables)
- Throwaway prototypes (overhead not worth it)
- Single-file scripts (too much process)
- Projects without AI assistance (system assumes AI execution)
Option 1: Jump Right In (30 minutes)
- 👉 Quick Start Guide — Learn by doing
Option 2: Understand First, Then Practice
- Read governance
- PROJECT-SYSTEM-GUIDELINES.md — System structure (15 min)
- AI-OPERATING-GUIDELINES.md — Execution procedures (10 min)
- See visual overview
- Epic Lifecycle Flow — How Epics work (5 min)
- Authority Hierarchy — Document precedence (5 min)
- Start a project
- How to Start a Project — Step-by-step initialization
You don't need to read everything to begin.
The system is designed to be learned incrementally.
This repository dogfooded its own system — the AI Project System was built using the AI Project System.
Phase P1 Status:
- ✅ Phase P1 COMPLETE — System Foundation & Adoption (closed 2026-02-23)
- ✅ All 5 Milestones closed: M1, M2, M3, M4, M5
- ✅ All 12 Epics delivered and merged
- ✅ Production-ready — Stable baseline for adoption
Completed Milestones:
- ✅ M1 — Genesis & Integration Baseline
- ✅ M2 — Execution Ergonomics & Validation
- ✅ M3 — Governance Distribution & Adoption
- ✅ M4 — Adoption Readiness & Practical Enablement
- ✅ M5 — System Refinement from Real Usage
Governance:
- PROJECT-SYSTEM-GUIDELINES.md v1.5.0 (effective 2026-02-18)
- AI-OPERATING-GUIDELINES.md v1.4.1 (effective 2026-02-22)
Next Phase: Phase P2 scope to be determined based on adoption feedback
Progress is reflected in three complementary ways:
-
Documentation (authoritative)
- Phase, Milestone, and Epic state lives in
docs/ - Completion reports are explicit and versioned
- Phase, Milestone, and Epic state lives in
-
Git history
- Branch hierarchy reflects execution flow
- Commits and PRs correspond to closed Epics
-
Project Tracker (assistive)
- GitHub Projects is used for planning and visibility
- Tracker state does not override documentation
If there is ever a conflict, documentation wins.
Authority Hierarchy (highest to lowest):
- PROJECT-SYSTEM-GUIDELINES.md — System structure, file conventions, core concepts
- AI-OPERATING-GUIDELINES.md — Execution procedures, agent responsibilities
- Epic Execution Chat Starter — Epic-specific instructions
- Epic Spec — Problem statement, goals, deliverables
- Execution Decisions — Real-time implementation choices
- System References — How-to guides, examples
- Chat Messages — Ephemeral communication (lowest authority)
Golden Rule: Documentation is authoritative. Chat is ephemeral. If there's conflict, higher-level docs win.
See Authority Hierarchy Diagram for visual explanation.
Current State:
- ✅ Phase P1 Complete — System Foundation & Adoption (5 milestones, 12 Epics)
- ✅ Production-ready — Stable baseline for adoption in other projects
- ✅ Battle-tested — Built using itself (dogfooding validated)
- ✅ Governance stable — v1.5.0 / v1.4.1 (effective 2026-02-18 / 2026-02-22)
- ✅ Complete documentation — Quick-start, templates, examples, diagrams, FAQ
- ✅ Licensed for adoption — MIT + CC BY-SA 4.0 dual license
Intentional Characteristics:
- Evolving deliberately based on real usage, not speculatively
- No CLI (not needed yet — manual process validates concepts)
- No web UI (not needed yet)
- No automation tooling (intentionally deferred)
- Single-user focus (team/org features deferred to future phases)
Future Work: Phase P2 scope will be determined based on adoption feedback and real usage patterns from other projects.
This repository uses dual licensing:
-
Code & Templates: MIT License
Freely use, modify, and distribute code, templates, and configuration files. -
Documentation: Creative Commons BY-SA 4.0
Documentation must be attributed and shared under the same license.
Why dual licensing?
- MIT allows unrestricted reuse of templates and code (maximum adoption)
- CC BY-SA 4.0 ensures documentation improvements flow back to the community
See LICENSE and docs/LICENSE for full license texts.
Contributions are welcome!
This system is designed to improve through real usage experience. We especially value:
- Bug reports (governance conflicts, unclear procedures)
- Documentation improvements (clarifications, examples)
- Real-world usage feedback ("I tried X and encountered Y")
Before contributing:
- Read CONTRIBUTING.md for guidelines
- Open an issue to discuss significant changes
- Follow existing documentation style and conventions
Not accepting (without discussion):
- Speculative features (no real usage motivation)
- Major redesigns (prove concepts first)
- Tooling/automation (intentionally deferred)
👉 Read the full contributing guide
- 📖 Start here: Quick Start Guide
- ❓ FAQ: Frequently Asked Questions
- 🎨 Visualize: Diagrams
- 🔍 Examples: Phase P1 Epics
- 💬 Ask: Open an issue