Issue-Driven Development (IDD) · Spec v1.1 · MIT

GitHub issues in.
Tested PRs out.

IDD Stack turns vague issues into work orders with acceptance criteria, then has your AI agent research, build, test, and review each one. Every commit links back to the issue that asked for it.

▶ Install IDD Stack View the source on GitHub

✓ Latest release v0.26.1 ✓ Zero config ✓ Plain GitHub markdown, no lock-in ✓ Works with any coding agent

~/your-repo — idd

❯ /issue-creator "login redirect loops on mobile Safari"

✓ Created issue #42

┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄

❯ /issue-triage

✓ Next up: #42 · P1 · no blockers

┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄

❯ /issue-resolver 42

✓ PR #87 opened · 2 files, 41 lines, 3 tests

┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄

❯ /issue-pr-review 87 --auto

✓ Merged PR #87 · issue #42 closed

┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄

Autonomous mode

Hand it a plan. Come back to merged PRs.

plan.md→/plan-to-issues→epic + issues→/auto-pilot→merged PRs

/plan-to-issues turns a plan, or the conversation you just had, into an epic with one issue per task. /auto-pilot then triages, resolves, reviews, and merges them on its own, and can keep going for days: it waits out GitHub rate limits, picks up where it stopped with --resume, and sets aside issues that keep failing.

See how auto-pilot works →

The problem

A one-line issue is not a work order.

GitHub issues are written for people to read, not for agents to execute. Everything between the bug report and the fix is left for someone to work out.

✗

30 minutes before line one

Someone files “the login is broken on mobile.” A developer, human or AI, can burn half an hour finding which files to open before writing any code.

✗

Agents edit the wrong files

Without acceptance criteria or pointers into the code, an agent picks files with confidence and gets them wrong. The issue never said where to look or what done means.

✗

A backlog with no order

Dozens of open issues and no map: which ones block others, which are already fixed, and which two could ship in parallel.

Six months later, your git log reads “fix stuff”, “update”, “WIP”,
and nobody can say why a change was made.

The fix

Every issue becomes a self-contained work order.

IDD Stack rewrites each issue into a typed spec with acceptance criteria, resolves it into a tested PR, and names every branch, commit, and PR after the issue it closes. Unlike a one-off prompt, the same pipeline runs every time.

/issue-creator

Issues an agent can act on

Describe a bug or feature in plain words. You get a typed issue with an effort size and acceptance criteria, and your original text stays intact in a Reporter Context block.

/issue-resolver N

Issue to tested PR in one command

Research, plan, implement, and QA run end to end. Out comes an atomic PR with Closes #N, a conventional branch name and commits, and tests for the change.

/issue-triage

A backlog with an order

Maps dependencies, flags stale issues and ones already fixed by a commit or PR, and proposes an execution order, including work that can run in parallel.

/auto-pilot

Hands-free, on merge rules you set

Loops triage, resolve, review, and merge across the backlog. Balanced mode, the default, merges clean PRs and opens a follow-up issue for the rest. Conservative mode holds every merge.

How it works

From one sentence to a merged PR in four steps.

No new platform. Issues stay plain GitHub markdown, and every step is a command in the terminal you already use.

Describe

Type the problem in plain English and /issue-creator files a structured issue. For a whole plan, /plan-to-issues files an epic with one issue per task.

Triage

/issue-triage maps dependencies, flags stale and already-fixed issues, and proposes an order.

Resolve

/issue-resolver N researches, plans, implements, and tests, then opens a PR that closes the issue.

Review & ship

/issue-pr-review checks each acceptance criterion, scores five dimensions, and fixes what fails. Add --auto to merge once it’s green.

▶ Copy the install command

Get started

Install once. Zero config to start.

You need gh 2.0+, Git 2.30+, and a coding agent that loads SKILL.md files (the markdown file that teaches an agent a skill).

# install all eight skills with asm (agent-skill-manager)

npm install -g agent-skill-manager

asm install https://github.com/luongnv89/idd

# or install as a Claude Code plugin, pinned to the latest release

claude plugin marketplace add luongnv89/idd

claude plugin install idd@idd

asm installs the skills for 20+ coding agents, including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, and Windsurf. Restart your agent, then try /issue-creator with a one-line bug report. The Claude Code plugin namespaces commands, like /idd:issue-resolver 42. Pick one install path: with both, every skill shows up twice. Updates and manual install are in the docs.

▶ Read the full docs See the latest release

The toolkit

Eight commands. One source of truth.

Each command is a self-contained skill, so you can install all eight or copy only what you need. /auto-pilot and /plan-to-issues call sibling skills and check for them first. Every input and option is in the docs.

/plan-to-issues

Turn a plan file, or the conversation you just had, into a tracking epic with one labelled issue per task and Depends on #N markers /auto-pilot respects.

/issue-creator

Classify, size (XS–XL), and write acceptance criteria. Also suggests a model and thinking level for the job, from CursorBench (a public coding-agent benchmark).

/issue-analysis N

Root cause, git history, implementation options, complexity, and risk, saved to .idd/.

/issue-resolver N

Preflight, research, plan, implement, and QA, then a PR with Closes #N.

/issue-triage

Dependency graph, stale and already-fixed detection, priority, and an execution order.

/issue-pr-review

Lint and test pre-pass, a check per acceptance criterion, five-dimension scoring, and fix cycles. Merges only with --auto.

/auto-pilot

Triage, resolve, review, and merge across the backlog in conservative, balanced (default), or aggressive mode.

/init-idd

Detect your language, framework, and test runner, and write a tuned .idd.yml.

Under the hood, eight shared agents do the work: duplicate detector, codebase researcher, synthesizer, implementer, code reviewer, fixer, relationship scanner, and UI/UX reviewer. Set each one’s model and thinking effort in .idd.yml, or keep the defaults.

No agent required

`idd-lint`: enforce the spec in CI

scripts/idd-lint.py checks IDD Spec conformance from plain data: issues, PRs, commit messages, branches, or a whole repo. Every check cites the spec section it enforces and maps to an L1–L3 level. Lint checks need no LLM, no network, and nothing beyond the Python standard library.

The stats mode adds an evidence report: trace completeness, Decision-Record coverage, and resolution outcomes by issue quality. Exit codes 0 and 1 drop straight into CI.

# one file, Python standard library only

curl -O https://raw.githubusercontent.com/luongnv89/idd/main/scripts/idd-lint.py

python3 idd-lint.py repo --base origin/main

Not in the skill pack · runs on any repo · --level L2 skips Decision-Record checks · --json for machines · --no-github keeps stats offline

idd-lint — spec conformance

❯ python3 idd-lint.py repo --base origin/main

◆ idd-lint — repo @ main (IDD Spec v1.1, level L2)

┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄

✓ [B02] branch fix/42-mobile-auth matches grammar (§3.1)

✓ [C01] 6 commit(s) match the grammar (§3.2)

┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄

Passed: 7 Warnings: 0 Errors: 0

✓ conformant at L2 (spec v1.1)

❯

What is IDD?

Issue-Driven. Intention-Driven. Same IDD.

IDD began as Issue-Driven Development: every change starts as an issue and ends as a PR that closes it. It is just as much Intention-Driven Development: the issue records what someone wants and why, and that intention travels with the work into the code, the review, and your git history.

intention → analysis → implementation → review → memory

// Issue-Driven

The issue is the unit of work

Each change starts as a structured issue with acceptance criteria and ends as one atomic PR. SPEC.md (v1.1) defines the issue format, dependency and Part of #N markers, naming grammar, and L1–L3 conformance levels in RFC 2119 language. Any agent, editor, or person can conform; these eight skills are the reference implementation on GitHub.

// Intention-Driven

The why travels with the code

The issue says what should change and why. The PR proves how it changed, a Decision Record keeps the reasoning, and the commit that resolves the issue carries it into git history, where the next person or agent can find it.

Works with the coding agent you already use

Claude Code

Codex

Cursor

GitHub Copilot

Gemini CLI

OpenCode

Windsurf

Cline

Amp

Any agent that loads SKILL.md

People just read the issues

FAQ

Questions, answered.

Why not just ask my agent to fix issue #42? +

You can, and it will guess. A one-line issue doesn’t say which files matter, what done looks like, or how to check it. /issue-resolver first rewrites a vague issue into a work order with acceptance criteria, then runs the same pipeline every time: research, plan, implement with tests, and QA against each criterion. The branch, commits, and PR all reference the issue, so the reason behind every change stays in your history.

Does this lock me into a specific AI tool? +

No. Issues stay plain GitHub markdown that any tool or person can read. The skills ship as self-contained SKILL.md files (SKILL.md is the markdown file that teaches an agent a skill), so they run on Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, or any other coding agent that loads skills.

Will it overwrite my existing issues? +

No. Normalizing an issue keeps your original text in a Reporter Context blockquote and posts a backup comment before anything changes. Inferred fields carry confidence markers, (high confidence) or (needs review), so you can see what was guessed.

Is auto-pilot safe to run on a real repo? +

It defaults to balanced mode: clean PRs merge, and a PR with unresolved review findings stays open with a follow-up issue. conservative mode holds every merge for you. Partial merges happen only if you opt into aggressive mode with merge_partial: true. A dependency-aware merge gate respects Depends on #N and Blocked by #N, and you can pass an explicit issue list for targeted runs.

What do I need to get started? +

The GitHub CLI (gh) 2.0+ signed in with gh auth login, Git 2.30+, and any coding agent that loads SKILL.md skills. No config file is needed. When you want to tune settings, /init-idd detects your stack and writes a .idd.yml.

How much does it cost? +

Nothing. IDD Stack is open source under the MIT license. You pay only for the AI agent you run it with.

Can I enforce the spec without an AI agent? +

Yes. idd-lint is a single Python file that checks IDD Spec conformance for issues, PRs, commit messages, branches, or a whole repo. Its lint checks need no LLM, no network, and nothing beyond the standard library, and they exit 0 or 1, so they drop straight into CI. It ships in the repo, not the skill pack: download scripts/idd-lint.py and run it on any repo.