🎟️ Ticket-Driven Dev

A Ticket-Driven Development framework for AI agents

The agile, lightweight framework that gives your AI-run project a memory — so Claude opens the repo and always knows what to work on next.

npx create-ticket-driven-dev my-project

Created by Teo Dagher · MIT License

The problem

AI coding agents are brilliant for an hour and amnesiac by next session. On a long-running project the real failure isn't bad code — it's lost context:

• The plan gets buried under day-to-day churn.
• The agent forgets why things were decided and re-litigates them.
• Every session starts with "wait, where were we?"

Spec-driven frameworks (BMAD, GitHub Spec Kit, OpenSpec, Kiro) answer this with heavy upfront ceremony — write a full spec, architecture, and epics before you build. That's great for one well-defined feature. It's a lot of weight for a project that's still evolving.

The idea: Ticket-Driven Development

Ticket-Driven Dev is the agile counterpart. Instead of one big spec up front, the unit of work is a ticket: small, self-contained, and carrying its own context. Work flows continuously — the agent pulls the next ticket and goes. Think Kanban for AI agents.

| | Spec-Driven (BMAD, Spec Kit) | Ticket-Driven Dev (Ticket-Driven Dev) | |---|---|---| | Unit of work | A spec (a big doc) | A ticket (a small task) | | When you plan | Heavily, up front | Continuously, as you go | | Answers | "What should this feature be?" | "What do I work on next, with full context?" | | Best for | One well-scoped feature | A whole long-running project | | Ceremony | High | Low — agile and always-moving |

Why it makes the agent fast

The whole system is built so that an agent reading the repo self-directs — no hand-holding, no re-explaining:

1. A fixed read order. CLAUDE.md tells the agent exactly what to read first: PRD.md (the plan) → backlog/board.md (the live task list) → wiki/index.md (what we've learned). In seconds it knows the state of the project and the next move.
2. Self-contained tickets. Each ticket has a goal, checkable acceptance criteria, and links to context — so you can hand the agent one file and it can start without asking a single question.
3. A self-healing board. backlog/board.md is generated from the ticket files and rebuilt automatically after every turn by a Claude Code hook. The tickets are the single source of truth; the board can never drift or go stale.
4. Memory split by rate of change. Stable strategy never gets polluted by fast-churning task updates (see below).

The 4-layer memory model

The core insight: separate memory by how fast each part changes.

| Layer | Lives in | Changes | Purpose | |-------|----------|---------|---------| | 🧭 Product | PRD.md | Deliberately | The north star — vision, scope, milestones | | 🎟️ Execution | backlog/ | Constantly | Tickets: what's done / doing / blocked / todo | | 📚 Knowledge | wiki/ | Continuously | What we've learned + every decision and why | | 🗄️ Sources | raw/ | Append-only | Immutable original material, never edited |

They join through milestone IDs: PRD.md owns M0, M1…; every ticket names the milestone it serves. The stable plan stays readable in seconds while the backlog grows without limit.

Get it / Install

You don't clone this repo to use it — you run the scaffolder, which copies a fresh project (with hooks, scripts, and skills already wired up) into a folder you name. Pick whichever line fits you. All you need is Node 16+; npx downloads and runs the tool in one step, nothing stays installed.

# ① Recommended — scaffold a new project named "my-project"
npx create-ticket-driven-dev my-project

# ② Same thing via npm's create shortcut
npm create ticket-driven-dev@latest my-project

# ③ No npm registry at all — copy the template straight from GitHub
npx degit Teodagher/ticket-driven-dev/template my-project

Replace my-project with whatever you want the folder to be called.

Already have a project? Add it to existing code

Ticket-Driven Dev works just as well bolted onto a codebase you've already started. Run the scaffolder inside your project with . as the target:

cd my-existing-app
npx create-ticket-driven-dev .

This is non-destructive — nothing you already have is overwritten. It only adds the missing pieces (PRD.md, backlog/, wiki/, scripts/, .claude/), appends its lines to your .gitignore, and if you already have a CLAUDE.md it drops the operating manual beside it for onboarding to merge. (Use --force only if you actually want to overwrite conflicts.)

Quick start

# 1. scaffold a new project (Node 16+; works with no install via npx)
npx create-ticket-driven-dev my-project

# 2. go in and make it a git repo
cd my-project
git init && git add -A && git commit -m "Initial Ticket-Driven Dev scaffold"

Then open it in Claude Code and say:

"Onboard me onto Ticket-Driven Dev."

Onboarding fills it in for you

A fresh scaffold ships with placeholders (CLAUDE.md's "What this project is", the PRD's vision/goals/milestones). You don't fill these in by hand — the bundled onboarding skill does it with you. On first run it asks one thing — brand-new project, or adding this to an existing codebase? — and runs the matching flow:

• New project → a few quick questions (what you're building, for whom, the first milestone), then it writes CLAUDE.md, PRD.md, and your first real tickets for you.
• Existing codebase → it reads your code (README, manifests, structure, recent commits), drafts the PRD/board/wiki from what's actually there, confirms with you, and captures the present + next work as tickets — without touching your code.

From then on, every session the agent reads the repo and knows what's next.

First time you open it in Claude Code: the project ships a Stop hook that auto-rebuilds the board after every turn. For your safety, Claude Code won't run any project hook until you approve it once — you'll see a trust prompt on first open. Approve it and the self-healing board works automatically from then on. (It also needs python3 on your PATH.) See the project's own README.md for details.

What's in the box

my-project/
├─ CLAUDE.md              # the operating manual — agents read this first
├─ PRD.md                 # the plan: vision, scope, milestone scoreboard
├─ backlog/
│  ├─ board.md            # GENERATED live task list (never hand-edited)
│  └─ tickets/
│     ├─ _TEMPLATE.md     # copy this to create a ticket
│     └─ T-001-example.md # a worked example ticket
├─ wiki/
│  ├─ index.md            # table of contents for all knowledge
│  ├─ log.md              # append-only history of ingests + decisions
│  └─ decisions/          # decision records (what we chose + why)
├─ raw/                   # immutable source material
├─ inbox/                 # scratch drop zone for unprocessed material
├─ scripts/
│  └─ backlog.py          # rebuilds the board + lints the tickets
└─ .claude/
   ├─ settings.json       # Stop hook → rebuilds the board every turn
   └─ skills/
      ├─ onboarding/       # first-run setup wizard (new vs existing project)
      └─ knowledge-base/   # how the wiki/raw knowledge layer is maintained

Working in a Ticket-Driven Dev project

python3 scripts/backlog.py          # rebuild the board + lint (auto-runs each turn)
python3 scripts/backlog.py --check  # lint only — exits non-zero on problems (CI-friendly)

• Add work: copy backlog/tickets/_TEMPLATE.md → T-<next>-<slug>.md, fill it in. The board rebuilds itself.
• Update progress: change status: in the ticket (todo · doing · blocked · done). Never edit the board.
• Record a decision: copy wiki/decisions/_TEMPLATE.md, and log a line in wiki/log.md.

The linter blocks on real problems — duplicate IDs, a ticket pointing at a milestone that doesn't exist in the PRD, malformed frontmatter — so the project's memory stays consistent on its own.

Requirements

• Python 3 — for the board generator (ships with macOS/Linux).
• Node 16+ — only to run the npx scaffolder.
• Claude Code — the hooks and skills target it, but the structure is plain Markdown and works with any agent or by hand.

Why "Ticket-Driven Dev"?

The name is the method: the unit of work is a ticket — small, self-contained, moving continuously — and the agent is driven by the next ticket on the board. Spec-driven plans a feature; ticket-driven runs a project.

License

MIT © Teo Dagher. Use it, fork it, build on it.

The knowledge-base layer is inspired by Andrej Karpathy's LLM-wiki idea — "the LLM writes and maintains the wiki; the human reads and asks questions."