issuedev
Issue-Driven Development · Spec v1.1 · 8 commands · MIT

Issues → agent-ready work orders.

Eight terminal commands that structure, analyze, triage, resolve, and review your GitHub issues — so any developer or AI agent can pick up an issue and ship a tested PR. Zero config.

▶ Get Started Read the Docs View on GitHub
✓ Latest release v0.18.0 ✓ Plain GitHub markdown ✓ No vendor lock-in ✓ Runs in your terminal ⚡ Model + thinking hints on create ✓ idd-lint — spec conformance in CI, no LLM
~/your-repo — issuedev
❯ /issue-resolver 42
◆ Resolve Pipeline
[0/5] Preflight ✓ issue #42 open
[1/5] Research ✓ read 5 files
[2/5] Plan ✓ fix redirect logic
[3/5] Implement ✓ 2 files, 45 lines
[4/5] QA ✓ clean after 2 cycles
[5/5] Deliver ✓ PR #87 created
 
✓ Done — PR #87: fix(auth): resolve redirect (#42)
❯
The problem

Unstructured issues kill velocity — and destroy your history.

GitHub issues were designed for humans to read, not for agents to execute. The gap between "someone describes a problem" and "someone ships a fix" is where projects bleed time.

✗

30 minutes before line one

Someone files "the login is broken on mobile." A developer — human or AI — burns half an hour figuring out which files to even open before writing a single line of code.

✗

Agents edit the wrong files

Without typed context and acceptance criteria, an AI agent confidently produces changes to the wrong files — because the issue never told it where to look or when it's done.

✗

A backlog with no order

47 open issues sit untriaged: no dependency awareness, no execution order, no idea which ones are already fixed or which two could ship in parallel.

Six months later your git log reads "fix stuff", "update", "WIP"
— and nobody can trace why a change was ever made.

The fix

Every issue becomes a self-contained work order.

issuedev turns each GitHub issue into something typed, structured, and enriched with acceptance criteria — then resolves it, with commit messages and PR titles that link every line of code back to the intention that created it.

/issue-creator

Structure, don't guess — plus the right model mode for the job

Describe a bug or feature in plain text. issuedev classifies the type, estimates effort (XS–XL), generates acceptance criteria, and files a clean issue — preserving your original words in a Reporter Context block without guessing implementation details.

⚡ Model: Each issue gets an advisory Suggested model with thinking level (e.g. GPT-5.5 High · Opus 4.8 Medium) keyed off effort, using CursorBench benchmarks — so you pick a capable tier for hard work and a cheaper tier for trivial fixes instead of running everything on max.

/issue-resolver N

Issue → tested PR, one command

A 6-step pipeline runs end to end: preflight, research, plan, implement, QA, deliver. Out comes an atomic PR with Closes #N — branch named, commits conventional, tests written.

effort max
/issue-triage

See the whole backlog at once

Dependency graph, priority suggestions, parallelizable work, stale-issue warnings, and already-fixed detection by scanning commits and PRs. One command produces a suggested execution order.

/auto-pilot

Hands-free, balanced by default

Triage → resolve → review → merge, looped across the backlog. In the default balanced mode clean PRs merge and partial ones stay open with a follow-up issue; conservative holds every merge, aggressive opts into partial merges. A dependency-aware merge gate keeps order sane.

effort max
Cost-aware by default

Right model, right thinking level — stamped on every issue

When you create or normalize an issue, /issue-creator maps estimated effort to a model + thinking tier from CursorBench data. The preview shows ⚡ Model:; the issue body stores an advisory Suggested model: line with the benchmark date.

Use it to route XS typo fixes to low-cost modes and reserve extra-high thinking for large features — without blocking creation if the cache is offline (bundled seed + graceful fallback).

EffortOpenAIAnthropic
XSGPT-5.5 LowOpus 4.7 Low
SGPT-5.5 MediumOpus 4.8 Low
MGPT-5.5 HighOpus 4.8 Medium
LGPT-5.5 Extra HighOpus 4.7 Extra High
XLGPT-5.5 Extra HighFable 5 Max

Toggle with model_suggestion.enabled in .gitissue.yml · refresh CursorBench into .gitissue/model-data.json

/issue-creator — preview
◆ Issue Preview
┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
Type: bug (high)
Title: Fix session cookie expiry on mobile
Effort: M
⚡ Model: GPT-5.5 High · Opus 4.8 Medium (~$7.42/task)
Labels: bug, auth, mobile
Criteria: 4 acceptance criteria (medium)
 
Metadata in issue body:
**Suggested model:** GPT-5.5 High · Opus 4.8 Medium
_(CursorBench 3.1, 2026-06-12 — advisory)_
How it works

From a sentence to a merged PR — in four moves.

No new platform to learn. The structured issue format is plain GitHub markdown, and every step is a command you run in the terminal you already live in.

1

Describe

Type the problem in plain English. /issue-creator classifies it, estimates effort, suggests model + thinking level, and structures a typed issue with acceptance criteria.

2

Triage

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

3

Resolve

/issue-resolver N researches, plans, implements, and QAs — then opens an atomic PR that closes the issue.

4

Review & ship

/issue-pr-review verifies each acceptance criterion, scores five dimensions, fixes, and merges when green.

See it run

Transparency, not a black box.

Confidence scores, step progress, and exactly what's happening at each phase — straight from your terminal. Every symbol carries meaning.

❯ /issue-creator — classify, effort, model + thinking hint, acceptance criteria
issue-creator terminal output showing a structured issue preview
❯ /issue-resolver 11
issue-resolver running its 6-step pipeline
❯ /issue-triage — execution order
issue-triage suggested execution order
❯ /issue-triage — backlog view
issue-triage backlog table with priorities and blockers
❯ /issue-triage — hot-spot & critical path
issue-triage hot-spot files and critical path analysis
The toolkit

Eight commands. One source of truth.

Each is a self-contained skill — drop it into Claude Code, Codex CLI, or any SKILL.md-compatible harness. Mix and match; nothing depends on the rest. Need exact inputs? See the full docs.

/issue-creator

Classify type, estimate effort, suggest model + thinking level (CursorBench), preserve reporter context, and file structured acceptance criteria.

/issue-analysis N

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

/issue-resolver N

6-step pipeline: preflight → research → plan → implement → QA → deliver a PR with Closes #N.

/issue-triage

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

/issue-pr-review

Lint/format/test pre-pass, per-criterion AC verification, five-dimension scoring, and fix cycles. Auto-merge only with --auto.

/auto-pilot

Triage → resolve → review → merge loop with balanced-by-default merge modes (conservative/balanced/aggressive).

/init-gitissue

Auto-detect language, framework, and test runner; generate a tuned .gitissue.yml.

/idd-doctor

Read-only health check for your IDD repository invariants. (maintainer tooling)

No agent required

idd-lint — enforce the spec in CI

scripts/idd-lint.py validates IDD Spec conformance from plain data — no LLM, no network, no dependencies beyond the Python standard library. Lint issues, PRs, commit messages, branches, or a whole repo; every check is tagged with the spec section it enforces and mapped to L1–L3 levels.

The stats mode goes further: an evidence report with trace completeness, Decision-Record coverage, and resolution outcomes by issue quality — rendered with verdict meters. Exit code 0/1 makes it CI-native; /idd-doctor stays the deep, agent-powered check.

Runs on any repo, gitissue skills or not · --level L2 skips L3 Decision-Record checks · --json for machines, --no-github for offline

idd-lint — spec conformance
❯ idd-lint 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)
❯
Specialists under the hood

Eight shared agents, one per job.

Skills orchestrate the pipeline; sub-agents do the deep work. Each prompt in src/shared/agents/ is a single-responsibility specialist — research, synthesis, implementation, review, fixes — with its model tier and thinking level tuned to the task, so every stage stays focused instead of generic.

Duplicate Detector

issue dedup · scoring

Scores a new issue against the open backlog and flags likely duplicates before one more copy lands.

Used by: /issue-creator

Codebase Researcher

deep scan · solution research

Maps the files, dependencies, and git history an issue touches — and researches how similar problems were solved.

Used by: /issue-resolver · /issue-analysis · /auto-pilot

Synthesizer

analysis · implementation options

Turns research into weighed options with trade-offs and a recommended approach — plus an overall complexity read.

Used by: /issue-analysis · /issue-resolver

Implementer

code · tests

Ships the change and its tests to match project conventions — data structures first, red-capable verification before bug fixes.

Used by: /issue-resolver

Code Reviewer

confidence-based review

Evidence-based review that reports only high-confidence findings, grouped under Spec and Standards axes — no nitpick noise.

Used by: /issue-pr-review · /issue-resolver · /auto-pilot

Fixer

targeted fixes

Applies scoped fixes for review, test, CI, and acceptance-criteria failures — cycling until the PR turns green.

Used by: /issue-pr-review · /issue-resolver

Relationship Scanner

deps · already-fixed detection

Finds file-level dependencies between issues, work that can run in parallel, and issues already fixed by a commit or PR.

Used by: /issue-triage

UI/UX Reviewer

a11y · screenshot review

Auto-detects UI changes and reviews accessibility, responsive layout, and honest UI against the screenshots in the PR.

Used by: /issue-pr-review · /issue-resolver

What is IDD?

A tool-neutral spec — issues as the atomic unit of work.

Issue-Driven Development is a written contract: an issue tracker and git history become executable project memory. SPEC.md (v1.1) defines the issue format, dependency and Part of #N hierarchy markers, naming grammar, and L1–L3 conformance levels — with RFC-2119 MUST/SHOULD language. It needs no specific AI agent, editor, or host. issuedev is the reference implementation for Claude Code + GitHub; a human with a text editor can conform too.

// The translation gap

From vague report to work order

Turning a vague report — "login is broken on mobile" — into a structured work order with acceptance criteria, current-code analysis at execution time, and a clear definition of done. That's the gap between describing a problem and shipping a fix, and IDD closes it.

// The intention gap

Commits that carry the why

Every change ends as a PR linked to its issue, so the commit that resolves it carries the why forward. Decision Records bind durable memory to the work. Your git history becomes a knowledge base you can retrieve from — not noise.

No lock-in

Works with the tools you already use.

IDD is a methodology, not a platform. The structured issue format is plain GitHub markdown — anything that reads issues can consume it. issuedev adds structure; everything else keeps working exactly as before.

Claude Code — load skills directly
Codex CLI — pipe issue body as context
Gemini CLI — resolve from the issue
GitHub Copilot — richer context
Any SKILL.md agent
Human developers — just read it
Get started

Your first issue in 30 seconds.

Needs gh 2.0+, Git 2.30+, and Claude Code (or any SKILL.md agent). Zero config to start.

# one command installs the whole pack — all eight skills
asm install https://github.com/luongnv89/idd
▶ Read the full docs Latest release
FAQ

Questions, answered.

Does this lock me into a specific AI tool? +
No. The structured issue format is plain GitHub markdown — any tool that reads GitHub issues can consume it. issuedev ships as self-contained SKILL.md skills that run on Claude Code, Codex CLI, Gemini CLI, or any SKILL.md-compatible harness. Your existing workflow keeps working exactly as before.
Will it rewrite or overwrite my existing issues? +
Normalization preserves your original text inside a > Reporter Context blockquote and posts a backup comment before changing anything. Inferred fields are tagged with confidence markers — (high confidence), (needs review) — so you can see exactly what was guessed versus what was certain.
Is auto-pilot safe to run on a real repo? +
It's balanced by default: clean PRs are merged, but a PR with unresolved review issues gets a follow-up issue and stays open — partial merges never happen unless you explicitly opt into aggressive mode with merge_partial: true. Prefer to review everything yourself? conservative mode holds every merge. A dependency-aware merge gate respects Depends on #N / Blocked by #N, and you can pass an explicit issue list for targeted runs.
Do I need to configure anything to start? +
No. Every command runs zero-config with sensible defaults. When you're ready to tune language, framework, and test-runner settings, run /init-gitissue to generate a project-specific .gitissue.yml — but it's entirely optional.
What does it actually require? +
The GitHub CLI (gh) 2.0+ authenticated via gh auth login, Git 2.30+, and Claude Code or any SKILL.md-compatible agent. Every gh call uses explicit JSON field selection — no fragile text parsing.
How much does it cost? +
issuedev is open source under the MIT license. Clone it, fork it, ship it. You only pay for whatever AI agent you choose to run the skills with.
Can I enforce the spec without running an AI agent? +
Yes. scripts/idd-lint.py checks IDD Spec conformance from plain data — no LLM, no network, no dependencies beyond the Python standard library. Lint issues, PRs, commits, branches, or a whole repo (--level L2 to skip L3 Decision-Record checks), and get an exit code 0/1 that drops straight into CI. Its stats mode prints an evidence report — trace completeness, Decision-Record coverage, and outcomes by issue quality. Any repo can run it, gitissue skills or not; /idd-doctor remains the deeper, agent-powered health check.
What is the suggested model on new issues? +
/issue-creator estimates issue effort (XS–XL) and adds an advisory Suggested model with a thinking level (e.g. GPT-5.5 High · Opus 4.8 Medium), grounded in CursorBench benchmarks. It appears in the create preview as ⚡ Model: and in the issue metadata so humans and agents can match spend to scope — use a low tier for trivial fixes and higher thinking only when the issue warrants it. Disable via model_suggestion.enabled: false in .gitissue.yml.

Stop translating issues by hand.
Let your agents execute them.

Turn vague reports into agent-ready work orders — and turn your git history back into the knowledge base it was meant to be.

▶ Get Started Free Star on GitHub ★
✓ MIT licensed  ·  ✓ Zero config  ·  ✓ No vendor lock-in