AI Project Framework

A reusable project management framework for AI-assisted development. Drop it into any repo to get structured backlog management, specialized AI roles, repeatable workflows, and synced instruction files for both Claude Code and Codex.

Born from running a real product with 230+ tickets, 19 epics, and a 2-person team. Battle-tested, opinionated, and designed for AI-assisted development.

What's Included

.claude/
  agents/           # Claude-specific wrappers/prompts for those roles
  skills/           # Repeatable workflow skills (invoked via /skill-name)
backlog/
  epics/            # Strategic groupings with phase breakdowns
  TICKET-TEMPLATE.md
  EPIC-TEMPLATE.md  # Standardized epic creation
  readme.md
scripts/
  backlog.sh        # Query tool for the backlog
CLAUDE.md           # Claude Code instructions
AGENTS.md           # Codex instructions
docs/
  architecture/     # System architecture docs
  decisions/        # Architecture Decision Records (ADRs)

Quick Start

1. Copy the contents of this repo into your project root
2. Edit CLAUDE.md and AGENTS.md (symlinked) to match your project (product name, tech stack, commands)
3. Edit backlog/readme.md to set your tier definitions and critical path
4. Create your first epic: copy backlog/EPIC-TEMPLATE.md to backlog/epics/your-epic.md
5. Create tickets: copy backlog/TICKET-TEMPLATE.md to backlog/001-your-ticket.md
6. Claude-specific subagents .claude/agents/
7. Run scripts/backlog.sh ready to see what's actionable

Adopting into an Existing Project

If your project already has some of these files:

• Already have a CLAUDE.md or AGENTS.md? Merge the backlog, role-boundary, and ticket hygiene sections from this framework into yours. The key sections are "Backlog & Ticket Hygiene", "Role Boundaries", and "How You Work".
• Already have a scripts/ directory? Just drop backlog.sh in alongside your existing scripts. It's self-contained.
• Already have a .gitignore? This framework's .gitignore is minimal (OS files, editor files, env files). Merge what you need.
• Want one source of truth? Keep CLAUDE.md and AGENTS.md aligned. The framework ships both so Claude and Codex work out of the box.

The Backlog System

Plaintext, YAML-frontmatter-driven project management that lives in your repo.

Why not Jira/Linear/etc? Because local AI coding tools can read and write markdown files natively. Your assistant can check ticket status, update acceptance criteria, and verify evidence without API integrations. The backlog is part of the codebase.

Key Concepts

• Tickets -- Individual work items with YAML frontmatter, acceptance criteria (AC-01, AC-02...), and verification evidence
• Epics -- Strategic groupings with goals, success metrics, phases, and done criteria
• Tiers -- Priority levels tied to business impact (-2 = ship NOW, 6 = post-scale polish)
• Dependencies -- Ticket-to-ticket blocking relationships, validated by the query script
• Evidence -- Every completed AC maps to proof (test, screenshot, command output)

Important: YAML Format

The frontmatter parser handles single-line values only. Arrays must use inline format:

# Correct
dependencies: [003, 005]

# WRONG -- will silently parse as empty
dependencies:
  - 003
  - 005

Query Tool

scripts/backlog.sh ready          # What's unblocked right now?
scripts/backlog.sh blocked        # What's blocked and why?
scripts/backlog.sh blocks <id>    # What does this ticket block? (reverse deps)
scripts/backlog.sh epic <name>    # Tickets in an epic
scripts/backlog.sh summary        # Counts by status + type breakdown
scripts/backlog.sh epics          # All epics with progress rollup
scripts/backlog.sh critical-path  # Tickets marked critical_path: true
scripts/backlog.sh velocity       # Tickets completed per week (last 8 weeks)
scripts/backlog.sh next-id        # Print next available ticket ID
scripts/backlog.sh search <term>  # Search ticket content
scripts/backlog.sh type <t>       # Filter by type
scripts/backlog.sh tier <n>       # Filter by tier
scripts/backlog.sh status <s>     # Filter by status
scripts/backlog.sh drafts         # Unreviewed drafts

Roles

Specialized AI roles with clear domain boundaries. .claude/agents/ contains Claude-oriented wrappers for teams that use Claude subagents directly.

Role	Domain	When to Use
architect	DB schema, infra, deploys	Any backend/infrastructure decision
code_reviewer	Fresh-context code review	Every formal review before commit
product_owner	Business/pricing/feature decisions	Product-level tradeoffs
ux_designer	All visual/CSS/layout work	Any UI change (mandatory)

Skills

Repeatable workflows invoked as slash-commands in Claude Code or followed manually/in-tool in Codex. Each workflow is a step-by-step procedure that ensures consistency.

Skill	Purpose
/code-review	Comprehensive review with AC evidence matrix
/ticket-verify	Validate ticket format and evidence completeness
/db	Database migration workflow with doc updates
/worktree	Isolated git worktree for parallel work
/plan-epic	Plan and create a new epic with phased ticket breakdown

Sample Data

The repo ships with sample epics and tickets that demonstrate the system:

• 3 epics (onboarding, payments, infra) with realistic phase breakdowns
• 7 tickets showing all statuses: open, in-progress, blocked, done
• Dependency chains (005 blocks 004, which blocks 006)
• Critical path tickets marked with critical_path: true
• 1 team profile showing the format

Epic phase tables reference some planned ticket IDs (007-016) that don't have corresponding files yet. This is intentional -- epics often reference future work that hasn't been broken into tickets.

Customization Guide

Tier System

Edit backlog/readme.md to define tiers that match your business. The default:

Tier	Meaning
-2	Revenue/activation -- ship NOW
-1	Non-blocking parallel lane
0	Infrastructure prerequisites
1	Launch blockers
2	Ship while waiting on external deps
3	First 30 days post-launch
4-6	Progressively further future

Critical Path

Add critical_path: true to the YAML frontmatter of any ticket on your launch chain. Then scripts/backlog.sh critical-path will show them with status and blockers.

Role Boundaries

The key principle: roles should have clear, non-overlapping domains with enforced boundaries. If your UX role exists, your instruction files should mandate that all UI work goes through it. Blurry boundaries produce inconsistent results.

Ticket Types

The default types are feature, content, infra, email, analytics, polish, ops. Edit the list in backlog/readme.md and backlog/TICKET-TEMPLATE.md to match your project's work categories.

Improvements Over v1

This framework incorporates lessons learned from running the system at scale:

• Epic template with required goal, success metric, done criteria, and max 3 phases
• assigned_to and started_at fields on tickets for in-progress visibility
• completed_at field for velocity tracking
• blocked_reason field for self-documenting blocked tickets
• related_tickets field for linking rework and follow-ups
• critical_path field for dynamic critical-path queries
• Standardized evidence types (test, manual-ui, command, code-review, deployment)
• Reverse dependency view in backlog.sh (blocks command)
• next-id and search commands for backlog management at scale
• /plan-epic skill with scoping guardrails and validation checklist

License

MIT -- see LICENSE.