{"id":50468087,"url":"https://github.com/luongnv89/idd","last_synced_at":"2026-06-01T08:32:49.651Z","repository":{"id":354522626,"uuid":"1186756435","full_name":"luongnv89/idd","owner":"luongnv89","description":"Turn GitHub Issues Into Structured, Agent-Ready Work Orders","archived":false,"fork":false,"pushed_at":"2026-05-22T20:46:19.000Z","size":1362,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-22T22:56:53.582Z","etag":null,"topics":["ai","development","workflow"],"latest_commit_sha":null,"homepage":"https://luongnv.com","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/luongnv89.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-20T00:41:58.000Z","updated_at":"2026-05-22T20:46:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/luongnv89/idd","commit_stats":null,"previous_names":["luongnv89/idd"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/luongnv89/idd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luongnv89%2Fidd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luongnv89%2Fidd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luongnv89%2Fidd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luongnv89%2Fidd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/luongnv89","download_url":"https://codeload.github.com/luongnv89/idd/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luongnv89%2Fidd/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33767435,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","development","workflow"],"created_at":"2026-06-01T08:32:49.535Z","updated_at":"2026-06-01T08:32:49.645Z","avatar_url":"https://github.com/luongnv89.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/logo/logo-white.svg\"\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"assets/logo/logo-black.svg\"\u003e\n    \u003cimg src=\"assets/logo/logo-black.svg\" alt=\"gitissue logo\" height=\"64\"\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/luongnv89/idd/releases/latest\"\u003e\u003cimg src=\"https://img.shields.io/badge/version-0.10.0-blue.svg\" alt=\"Version 0.10.0\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/luongnv89/idd/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-green.svg\" alt=\"MIT License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/luongnv89/idd\"\u003e\u003cimg src=\"https://img.shields.io/badge/commands-8-blue.svg\" alt=\"8 commands\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/luongnv89/idd/blob/main/CONTRIBUTING.md\"\u003e\u003cimg src=\"https://img.shields.io/badge/PRs-welcome-brightgreen.svg\" alt=\"PRs Welcome\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n# Turn GitHub Issues Into Structured, Agent-Ready Work Orders\n\nEight terminal commands that structure, analyze, triage, resolve, review, and self-check GitHub issue workflows — so any developer or AI agent can pick up an issue and ship a tested PR.\n\n[**Get Started**](#get-started) · [**What is IDD?**](#what-is-idd) · [**Intention-Driven Development**](#idd-as-intention-driven-development) · [**Why Good Issues \u0026 Commits Matter**](#why-good-issues-and-commit-messages-matter) · [**Works With Any Tool**](#works-with-any-tool)\n\n---\n\n## The Problem\n\nUnstructured issues kill velocity — and destroy your project history.\n\nSomeone files \"the login is broken on mobile.\" A developer — human or AI — spends 30 minutes figuring out which files to open before writing a line of code. An AI agent produces changes to the wrong files because the issue lacked context. Meanwhile, 47 open issues sit in the backlog with no dependency awareness and no execution order.\n\nWorse: when issues are vague, the commits that resolve them are vague too. Six months later, `git log` reads like `\"fix stuff\"`, `\"update\"`, `\"WIP\"`. Nobody can trace *why* a change was made, *what problem* it solved, or *what decision* led to that approach. The development history — which should be your project's most valuable knowledge base — becomes noise.\n\nGitHub issues were designed for humans to read, not for agents to execute. And commit messages were designed to tell a story, not to fill a required field.\n\n## The Fix\n\ngitissue turns every GitHub issue into a self-contained work order: typed, structured, and enriched with acceptance criteria. Then it resolves them — with commit messages and PR titles that link every line of code back to the intention that created it.\n\n```mermaid\ngraph TD\n    A[\"Describe a problem\"] --\u003e B[\"/issue-creator\"]\n    B --\u003e C[\"Structured issue\"]\n    C --\u003e D[\"/issue-triage\"]\n    D --\u003e E[\"/issue-analysis N\"]\n    E --\u003e F[\"/issue-resolver N\"]\n    F --\u003e G[\"Tested PR that closes the issue\"]\n    D -.-\u003e H[\"/auto-pilot\"]\n    H -.-\u003e G\n\n    style A fill:#4CAF50,color:#fff\n    style G fill:#2196F3,color:#fff\n    style H fill:#FF9800,color:#fff\n```\n\n| Command | What it does | Version | Effort |\n|---------|-------------|---------|--------|\n| `/issue-creator` | Classify type, generate acceptance criteria, create a structured issue | 0.4.1 | medium |\n| `/issue-analysis N` | Root cause, git history, implementation options, complexity and risk | 0.4.1 | high |\n| `/issue-resolver N` | 6-step pipeline: preflight, research, plan, implement, QA, deliver PR with `Closes #N` | 0.7.1 | max |\n| `/issue-triage` | Dependency graph, stale detection, already-fixed detection via commit/PR scanning, priority and execution order | 0.5.2 | medium |\n| `/init-gitissue` | Auto-detect language/framework/test runner, generate `.gitissue.yml` | 0.3.2 | low |\n| `/auto-pilot` | Triage → resolve → review → merge loop. Conservative-by-default merge modes (`conservative`/`balanced`/`aggressive`) and explicit issue lists for targeted runs | 2.2.0 | max |\n| `/issue-pr-review` | Review PR end-to-end: script pre-pass (lint/format/test auto-fix), per-criterion AC verification, five-dimension scoring (correctness, acceptance_criteria, traceability, maintainability, safety), reuses reviewer/fixer agents across cycles | 0.5.0 | high |\n\n### Internal tooling\n\nInternal-only skills are not published in the public skill index and are not built into `dist/`. They live alongside the source for repo maintainers to invoke directly from a working tree.\n\n| Skill | Folder | Purpose |\n|-------|--------|---------|\n| `/idd-doctor` | [`src/internal-skills/idd-doctor/`](src/internal-skills/idd-doctor/) | Read-only health check for IDD repository invariants — runs against the local `src/` checkout; not distributed |\n\n---\n\n## How It Works\n\n### 1. Create a structured issue\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/screenshots/issue-creator.png\" alt=\"issue-creator terminal output\" width=\"680\"\u003e\n\u003c/p\u003e\n\nDescribe a bug, feature, or improvement in plain text. gitissue classifies it, generates acceptance criteria, and creates a GitHub issue with labels.\n\n### 2. Resolve it in one command\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/screenshots/issue-resolver-11.png\" alt=\"issue-resolver terminal output\" width=\"680\"\u003e\n\u003c/p\u003e\n\nSix steps run automatically: preflight, research, plan, implement, QA, and deliver a PR with `Closes #N`.\n\n### 3. Triage the backlog\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/screenshots/issue-triage-view.png\" alt=\"issue-triage terminal output\" width=\"680\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/screenshots/issue-triage-suggestion.png\" alt=\"issue-triage suggested execution order\" width=\"680\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/screenshots/issue-triage-asm.png\" alt=\"issue-triage hot-spot files and critical path analysis\" width=\"680\"\u003e\n\u003c/p\u003e\n\nDependency detection, priority suggestions, parallelizable work, stale issue warnings, and already-fixed detection — one command for the entire backlog.\n\n### 4. Deep-dive on a single issue\n\n```\n  [1/8] Fetch          ✓ issue #42 loaded (bug)\n  [2/8] Extract        ✓ 8 keywords, 2 file refs\n  [3/8] Research       ✓ read 18 files, traced 12 deps\n  [4/8] History        ✓ 5 related commits, 1 regression\n  [5/8] Cross-refs     ✓ 2 related issues\n  [6/8] Analysis       ✓ root cause identified\n  [7/8] Options        ✓ 3 approaches proposed\n  [8/8] Report         ✓ saved to .gitissue/analysis-42.json\n```\n\n### 5. Go hands-free with auto-pilot\n\n```\n  ◆ auto-pilot        starting (5 open issues)\n  ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄\n  [1/5] #42            ✓ resolved → PR #51 merged\n  [2/5] #38            ✓ resolved → PR #52 merged\n  [3/5] #35            ✗ stopped — test failures after 2 fix cycles\n  [4/5] #29            ✓ resolved → PR #53 merged\n  [5/5] #21            ✓ resolved → PR #54 merged\n  ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄\n  ◆ complete           4/5 resolved, 1 stopped\n```\n\nTriage, resolve, review, merge — repeated for every open issue. Up to three review-fix cycles per PR with a script pre-pass (lint/format/test auto-fix) before any LLM cycle is spent. Conservative by default: clean PRs are merged, partial PRs are left open for review unless `autopilot.mode: aggressive` is explicitly set. Supports explicit issue lists for targeted runs.\n\n---\n\n## Works With Any Tool\n\nIDD is a methodology, not a vendor lock-in. The structured issue format is plain GitHub markdown — any tool that reads GitHub issues can consume it. gitissue adds structure to your issues; your existing tools keep working exactly as before.\n\n| Tool | How it works with gitissue |\n|------|---------------------------|\n| **Claude Code** | Load skills directly — `/issue-creator`, `/issue-resolver` |\n| **Codex CLI** | `gh issue view 42 --json body` and pass to codex as context |\n| **Gemini CLI** | Pipe issue body to gemini for resolution |\n| **GitHub Copilot** | Structured issues give Copilot better context for suggestions |\n| **Any SKILL.md agent** | Load skills from `src/skills/` directory |\n| **Human developers** | Read the issue — acceptance criteria and structure are right there |\n\ngitissue is **complementary** to your existing workflow. Use it alongside TDD, BDD, CI/CD pipelines, project management tools, or any AI coding agent. It fills one gap — structuring and triaging issues — and stays out of the way for everything else.\n\n---\n\n## Get Started\n\n### Prerequisites\n\n- [GitHub CLI](https://cli.github.com) (`gh`) 2.0+, authenticated via `gh auth login`\n- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or any SKILL.md-compatible agent\n- Git 2.30+\n\n### Install\n\nStandalone is the recommended default. Each skill ships as a self-contained directory under `dist/skills/\u003cname\u003e/`, ready to drop into any SKILL.md-compatible harness — Claude Code, Codex CLI, or anything else that loads SKILL.md trees.\n\n#### Recommended — Standalone via `asm install`\n\n[`asm`](https://github.com/luongnv89/asm) is the primary install tool. It pulls the skill straight from this repo (no clone required) and writes it where Claude Code looks for skills. Pick one skill or install them all:\n\n```bash\n# One skill (most common):\nasm install github:luongnv89/idd#main:dist/skills/issue-resolver\n\n# Every public skill in one loop:\nfor skill in issue-creator issue-analysis issue-resolver issue-triage \\\n             issue-pr-review auto-pilot init-gitissue; do\n  asm install \"github:luongnv89/idd#main:dist/skills/$skill\" -p claude -y\ndone\n\n# Shared Claude Code agents used by those skills:\nmkdir -p \"$HOME/.claude/agents\"\nfor agent in code-reviewer codebase-researcher duplicate-detector \\\n             implementer issue-relationship-scanner synthesizer; do\n  dst=\"$HOME/.claude/agents/$agent.md\"\n  if [ -f \"$dst\" ] \u0026\u0026 ! grep -q 'Managed by IDD installer' \"$dst\"; then\n    echo \"Skipping unmanaged existing agent: $dst\"\n    continue\n  fi\n  curl -fsSL \"https://raw.githubusercontent.com/luongnv89/idd/main/dist/agents/$agent.md\" -o \"$dst\"\ndone\n```\n\n`asm` is idempotent — re-running the same command updates the skill in place with no duplicate files. The agent loop is also safe to re-run: it only replaces IDD-managed agents and skips unmanaged same-name files. Target Claude Code explicitly with `-p claude` (or `-p all` for every supported tool).\n\n\u003e **Why a loop?** A single `asm install …:dist/skills --all` would be nicer, but `--all` is currently ignored when the source includes a subpath (tracked in [luongnv89/asm#251](https://github.com/luongnv89/asm/issues/251)). The per-skill loop above exercises the working single-skill path. Once asm #251 lands we'll switch back to the one-liner. If you'd rather not loop, the [from-source alternative](#from-source-alternative-no-asm-required) installs all skills with a single command today.\n\nAfter install, restart Claude Code so it picks up the new skill(s) and agents. The full list of skills lives under [`dist/skills/`](dist/skills/) and generated Claude Code agents live under [`dist/agents/`](dist/agents/) — substitute any skill name (`issue-creator`, `issue-resolver`, `issue-triage`, `issue-pr-review`, `auto-pilot`, `issue-analysis`, `init-gitissue`) into the command above.\n\n#### From-source alternative (no `asm` required)\n\nIf you can't or don't want to install `asm`, clone the repo and run the bundled install script. One command, no manual `tar`/`cp`, idempotent on re-run:\n\n```bash\ngit clone https://github.com/luongnv89/idd.git\ncd idd\n./scripts/install.sh                          # interactive tool picker — choose one or more tools\n# the picker lists every supported tool; pick by number (e.g. \"1 3 4\"), \"a\" for all,\n# or press Enter for Claude Code. Bypass the picker by naming tools explicitly:\n# or: ./scripts/install.sh --skill issue-resolver\n# or target another tool: ./scripts/install.sh --tool codex\n# or several at once:      ./scripts/install.sh --tools claude,codex,pi\n# or every supported tool: ./scripts/install.sh --tools all\n```\n\n\u003e When run on a terminal with no `--tool`/`--tools` flag, the script shows an interactive picker so you can select one or more tools. In a non-interactive context (CI, `curl | bash` without a TTY, piped input) it falls back to Claude Code so automation keeps working.\n\nThe script copies each `dist/skills/\u003cname\u003e/` to the selected tool's skills directory (default `~/.claude/skills/\u003cname\u003e/`). It supports `claude`, `agents`, `codex`, `opencode`, `pi`, `openclaw`, `hermes`, `antigravity`, and `windsurf` — each `dist/skills/\u003cname\u003e/` is a self-contained SKILL.md tree (the shared agents are bundled inside it at `references/agents/`), so a skill runs on any SKILL.md-compatible tool. Shared agents are *also* installed standalone from `dist/agents/*.md` into `~/.claude/agents/` (and `~/.agents/agents/`) — a Claude Code optimization for native subagent spawning; other tools use the bundled copies. The installer replaces IDD-managed agents cleanly, removes stale managed agents on update, and skips unmanaged same-name agents unless you pass `--force-agents` (which backs them up before replacement). Use `./scripts/install.sh --target \u003cdir\u003e` to target a different Claude root (Claude tool only; other tools use their fixed conventions). Pure POSIX bash — no extra runtime needed.\n\nYou can also do the copy by hand if you prefer to see every file move:\n\n```bash\nmkdir -p ~/.claude/skills ~/.claude/agents\ncp -r dist/skills/\u003cname\u003e ~/.claude/skills/\ncp dist/agents/*.md ~/.claude/agents/\n```\n\n`dist/skills/` and `dist/agents/` are committed to the repository, so this path works on a fresh clone without running a build.\n\n#### Plugin path (advanced — Claude Code only)\n\nThe plugin layout bundles every public skill under one `~/.claude/plugins/idd/` tree. It is the heavier option; pick it only if you want all skills installed atomically as a single Claude Code plugin.\n\nGrab the `idd-plugin-\u003ctag\u003e.tar.gz` asset from the [latest release](https://github.com/luongnv89/idd/releases/latest) and extract it into your Claude Code plugins directory:\n\n```bash\nmkdir -p ~/.claude/plugins/idd\n# Download idd-plugin-\u003ctag\u003e.tar.gz from the release page (browser or `gh release download`)\ntar -xzf idd-plugin-\u003ctag\u003e.tar.gz -C ~/.claude/plugins/idd\n```\n\nThe tarball unpacks to `.claude-plugin/plugin.json`, `agents/`, `skills/`, `shared/`, and `docs/` at its root. Restart Claude Code to load the new plugin.\n\n\u003e **Heads up — `claude plugin install \u003ctarball-url\u003e` is not supported.** Claude Code's `claude plugin install` only accepts `plugin@marketplace` references and resolves them through configured marketplaces, not direct tarball URLs or paths. Running `claude plugin install https://github.com/luongnv89/idd/releases/download/\u003ctag\u003e/idd-plugin-\u003ctag\u003e.tar.gz` returns `not found in any configured marketplace` and does nothing. Use the manual `tar -xzf` extract above — that is the supported install path today. (Tracked in [#79](https://github.com/luongnv89/idd/issues/79).)\n\nIf you cloned the repo, you can build the plugin tree locally and install it with the script: `./scripts/build.sh \u0026\u0026 ./scripts/install.sh --plugin`. `dist/plugin/` is generated only at release time and gitignored, so the build step is required.\n\n\u003e **Note:** `dist/skills/` and `dist/agents/` are committed so the standalone paths work without running a build. `dist/plugin/` is built fresh by `./scripts/build.sh` and shipped as the release tarball above.\n\n### First issue in 30 seconds\n\nCreate a structured issue:\n\n```bash\n/issue-creator \"Login fails on mobile when session cookie expires\"\n```\n\nResolve it:\n\n```bash\n/issue-resolver 42\n```\n\nTriage the backlog:\n\n```bash\n/issue-triage\n```\n\nOr go hands-free — triage, resolve, review, and merge everything:\n\n```bash\n/auto-pilot\n```\n\nZero config required. Run `/init-gitissue` to customize.\n\nBrowse the authored source for each skill — these links point to `src/` for reading; install copies come from `dist/skills/\u003cname\u003e/` (see [Install](#install)):\n\n| Skill | Source |\n|-------|--------|\n| `/issue-creator` | [`src/skills/issue-creator/`](src/skills/issue-creator/) |\n| `/issue-analysis` | [`src/skills/issue-analysis/`](src/skills/issue-analysis/) |\n| `/issue-resolver` | [`src/skills/issue-resolver/`](src/skills/issue-resolver/) |\n| `/issue-triage` | [`src/skills/issue-triage/`](src/skills/issue-triage/) |\n| `/auto-pilot` | [`src/skills/auto-pilot/`](src/skills/auto-pilot/) |\n| `/issue-pr-review` | [`src/skills/issue-pr-review/`](src/skills/issue-pr-review/) |\n| `/init-gitissue` | [`src/skills/init-gitissue/`](src/skills/init-gitissue/) |\n| `/idd-doctor` _(internal)_ | [`src/internal-skills/idd-doctor/`](src/internal-skills/idd-doctor/) |\n\n---\n\n## What is IDD?\n\nIssue-Driven Development — also **Intention-Driven Development** — treats GitHub issues as the atomic unit of all development work. Every change starts as a structured issue and ends as a PR linked to that issue.\n\nThe key idea: the gap between \"someone describes a problem\" and \"someone ships a fix\" is both a **translation gap** and an **intention gap**. IDD automates that translation — turning vague reports into structured work orders with acceptance criteria — while helping creators discover and articulate what they actually want through iterative refinement.\n\n```mermaid\ngraph TD\n    A[\"Problem described\"] --\u003e B[\"/issue-creator\"]\n    B --\u003e C[\"Structured issue with acceptance criteria\"]\n    C --\u003e D[\"/issue-triage\"]\n    D --\u003e E[\"/issue-analysis N\"]\n    E --\u003e F[\"/issue-resolver N\"]\n    F --\u003e G[\"Fetch → Branch → Research → Plan → Execute → Verify → Ship\"]\n    G --\u003e H[\"PR merges → Issue auto-closes\"]\n    D -.-\u003e I[\"/auto-pilot\"]\n    I -.-\u003e |\"triage → resolve → review → merge loop\"| H\n\n    style A fill:#4CAF50,color:#fff\n    style H fill:#2196F3,color:#fff\n    style I fill:#FF9800,color:#fff\n```\n\n### IDD as Intention-Driven Development\n\nIDD is also **Intention-Driven Development** — and that name captures something deeper about what it solves.\n\nExpressing what you actually want is hard. Even experienced developers struggle to articulate a problem clearly enough for someone else — human or AI — to act on it. Vague descriptions lead to wrong assumptions, wasted effort, and solutions that miss the point.\n\n`/issue-creator` changes this dynamic. When you describe a problem in plain language, it structures your input into a typed issue with reporter context and acceptance criteria — capturing intent only, never guessing affected files or implementation notes. But the real value isn't the output — it's the **feedback loop**:\n\n1. **You describe the problem** — loosely, incompletely, however it comes to mind\n2. **The agent proposes a structured issue** — classifying the type, filling in context, generating acceptance criteria\n3. **You read back what it captured** — and realize what you actually meant, what's missing, what's wrong\n4. **You refine through conversation** — correcting, adding detail, sharpening the intent until the issue says exactly what you want\n\nThis iterative process does something no template or form can do: it helps you **discover your own intention**. By the time the issue is finalized, it accurately represents what the creator wants — expressed in a way that both humans and AI agents can understand and execute.\n\nThis matters because understanding user requirements is one of the hardest steps in the software development lifecycle. Most bugs and missed features trace back to requirements that were never clearly stated. IDD makes that step explicit, collaborative, and repeatable — turning an informal complaint into a precise, agent-ready work order.\n\nThe structured issue becomes the **single source of truth** for what needs to happen. When `/issue-resolver` picks it up, there's no guesswork — the intention is already captured.\n\n### Why Good Issues and Commit Messages Matter\n\nA well-defined issue and a well-written commit message are two halves of the same story. Together, they turn your git history into a **searchable, navigable record** of every decision your project has ever made.\n\n**The issue captures the _why_** — what was broken, what was needed, what the user actually wanted. **The commit captures the _how_** — what was changed, which approach was chosen, and what trade-offs were made. **The PR links them together** — providing the full narrative from problem to solution.\n\nWhen these artifacts are well-crafted:\n\n- **Debugging becomes archaeology, not guesswork.** `git log --oneline` tells you which issue motivated each change. `git blame` on any line links to the commit that changed it, which links to the PR, which links to the issue. You can trace any line of code back to the original problem report.\n- **Onboarding accelerates.** New team members read the git history and understand not just *what* the code does, but *why* it does it that way. The history teaches the project's evolution.\n- **AI agents get better context.** When `/issue-analysis` scans git history for related commits, structured commit messages with issue references surface relevant changes instantly. Vague commits like `\"fix bug\"` are invisible to this analysis.\n- **Reverts and rollbacks are safe.** When every commit is atomic and linked to an issue, you can revert a specific change with confidence — you know exactly what it did and why.\n- **Changelogs write themselves.** Conventional commit messages (`feat:`, `fix:`, `refactor:`) can be parsed automatically into release notes grouped by type.\n\ngitissue enforces this discipline automatically. `/issue-creator` structures the issue. `/issue-resolver` creates branches, commits, and PRs that follow [naming conventions](docs/naming-conventions.md) — linking every artifact back to the issue that started it. The result: a development history that remains useful and valuable for the entire lifetime of the project.\n\n### IDD and other methodologies\n\nIDD operates at a different layer than TDD, BDD, or spec-driven development. It structures the *work* before you write the *code or tests*. This makes it complementary, not competitive.\n\n| Aspect | IDD | TDD | BDD | Spec-Driven |\n|--------|-----|-----|-----|-------------|\n| **Source of truth** | GitHub issue | Test suite | Feature specs | Spec documents |\n| **Starts with** | Problem description | Failing test | User story | Detailed spec |\n| **Agent-compatible** | Any agent | Needs framework | Needs framework | Needs parser |\n| **Overhead** | Zero-config CLI | Test setup | Gherkin syntax | Spec authoring |\n| **Best for** | Brownfield, mixed teams | New code | User-facing features | Formal contracts |\n\nUse IDD **with** TDD: structure the issue first, then write tests during resolution. Use IDD **with** BDD: let acceptance criteria inform your Gherkin scenarios. They compose.\n\n---\n\n## FAQ\n\n**Is it free?**\nMIT licensed. No telemetry, no accounts, no cloud dependency.\n\n**Does it work without Claude Code?**\nThe skills are designed for Claude Code, but the structured issue format works with any AI agent or human developer. The issue is the interface.\n\n**Will it modify my existing issues?**\nOnly when you explicitly run `/issue-creator N`. A backup comment is posted before any changes. If the backup fails, it aborts.\n\n**How does it handle security issues?**\nIssues labeled `security`, `CVE`, or `vulnerability` are automatically skipped during normalization. Use `--force` to override.\n\n**Can I use it with my existing tools?**\nYes. gitissue adds structure to issues. Your CI/CD, project boards, code review tools, and AI agents all keep working. Structured issues give them better input.\n\n**Does it work with private repos?**\nYes. It uses `gh` CLI authentication — whatever repos you can access via `gh auth login` will work.\n\n---\n\n## Contributing\n\nContributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\nMIT Licensed · [View on GitHub](https://github.com/luongnv89/idd)\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCommands Reference\u003c/strong\u003e\u003c/summary\u003e\n\n### /issue-creator -- Create and Normalize Issues\n\n| Invocation | Mode | Description |\n|------------|------|-------------|\n| `/issue-creator \u003ctext\u003e` | Create | Create a structured issue from text |\n| `/issue-creator \u003cN\u003e` | Normalize | Structure existing issue #N with acceptance criteria |\n| `/issue-creator \u003cN\u003e --dry-run` | Preview | Show normalization preview without applying |\n| `/issue-creator \u003cN\u003e --force` | Force | Normalize even if issue has a security label |\n| `/issue-creator \u003cmulti-item text\u003e` | Batch | Extract and create multiple issues from one input |\n\n**Create mode** classifies the issue type (bug/feature/improvement), generates acceptance criteria, uploads screenshots to GitHub, and creates a structured issue.\n\n**Normalize mode** restructures an existing issue: preserves original text in a Reporter Context blockquote, generates acceptance criteria, and posts a backup before editing.\n\n**Batch mode** auto-detects multiple items (numbered lists, bullet points, planning documents) and creates them sequentially with a preview table and approval step.\n\n### /issue-analysis N -- Deep Issue Analysis\n\nAnalyzes issue #N in depth without making code changes:\n\n```\n[1/8] Fetch          — Load issue, classify type\n[2/8] Extract        — Parse keywords, file refs, error messages\n[3/8] Research       — Deep codebase scan (30 files, 3-level import tracing)\n[4/8] History        — Git log: prior fix attempts, regressions, domain experts\n[5/8] Cross-refs     — Related issues/PRs, duplicates, already resolved\n[6/8] Analysis       — Root cause (bugs), architecture fit (features)\n[7/8] Options        — 2-3 implementation approaches with pros/cons\n[8/8] Report         — Terminal report + .gitissue/analysis-N.json\n```\n\n### /issue-resolver N -- Resolve Issues\n\nResolves issue #N through a 6-step pipeline:\n\n```\n[0/5] Preflight    — Check issue status, verify not already resolved\n[1/5] Research     — Scan codebase, trace dependencies\n[2/5] Plan         — Propose 3 approaches, pick one\n[3/5] Implement    — Write code + tests, atomic commits\n[4/5] QA           — Code review + test + build + fix loop\n[5/5] Deliver      — Push branch, create PR with \"Closes #N\"\n```\n\n### /issue-triage -- Triage the Backlog\n\nDependency detection via codebase scanning, topological sort for execution order, parallelizable issue identification, stale issue detection (\u003e14 days), already-fixed detection (scans commit history and merged PRs with confidence levels), priority suggestions.\n\n### /auto-pilot -- Automated Backlog Processing\n\nFully automated loop: triage open issues, pick the highest-priority task, resolve it end-to-end, review the PR with up to three review-fix cycles (script pre-pass first, LLM cycles only for issues the pre-pass can't resolve), merge, and repeat. Supports explicit issue lists to process specific issues in user-defined order. Stop conditions prevent runaway execution.\n\n```\n/auto-pilot                          # triage and resolve all open issues\n/auto-pilot --issues 5,12,3          # resolve these issues in this order\n/auto-pilot --limit 5                # cap to 5 iterations\n/auto-pilot --dry-run                # show plan without resolving\n```\n\nMerge modes (configured under `autopilot.mode` in `.gitissue.yml`):\n\n| Mode | Clean PR | Partial PR (review issues remain) |\n|------|----------|-----------------------------------|\n| `conservative` (default) | merge | leave open |\n| `balanced` | merge | leave open + create follow-up issue |\n| `aggressive` | merge | merge + create follow-up issue (requires `merge_partial: true`) |\n\n### /idd-doctor -- Read-Only Health Check\n\nQuick read-only diagnostic that verifies the IDD invariants of the current repo. Checks four things and reports per-check pass/fail with file/line evidence:\n\n1. `/issue-creator` keeps its intent-only contract (no `affected_files` / `technical_notes` / `architecture_constraints` in templates or output)\n2. Every `gh` invocation in skills uses `--json` with explicit field selection\n3. Each skill has a `references/error-messages.md` using the three-part format\n4. Repo merge strategy is set to squash so PR bodies land in `git log` (durable analysis-artifact rule from #35)\n\nRead-only by design — never modifies files, branches, or remote state.\n\n```\n/idd-doctor                          # run all checks\n```\n\n### /issue-pr-review -- PR Review Pipeline\n\nReviews a PR end-to-end: script pre-pass (lint/format/test auto-fix, zero LLM cost), code review with confidence-based filtering classified as `fix` (critical/high) vs `note` (medium), per-criterion acceptance-criteria verification, traceability checks (Closes link, Decision Record, AC Verification table), runs tests and build, checks CI status, fixes only `fix` issues, and repeats until clean. Soft-pass when zero `fix` issues remain. Supports auto-merge in auto-pilot mode.\n\n```\n/issue-pr-review 87              # review PR #87\n/issue-pr-review                 # auto-detect PR for current branch\n```\n\nPipeline:\n\n```\n[1/7] PR Info      ✓ PR #87: fix(auth): resolve redirect (#42)\n[2/7] Pre-pass     ✓ lint clean, format clean, 17 tests passed\n[3/7] Review       ● analyzing changes...\n[4/7] Test         ✓ 17 tests passed, build ok\n[5/7] CI Status    ✓ all checks passed\n[6/7] Fix          ○ no issues to fix\n[7/7] Report       ✓ PR is clean — ready to merge\n```\n\nMax 3 review-fix cycles with stagnation detection.\n\n### /init-gitissue -- Generate Config\n\nScans your repository and generates `.gitissue.yml` with sensible defaults: detects language, framework, test runner, existing templates, and adjusts timeouts based on repo size.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eConfiguration\u003c/strong\u003e\u003c/summary\u003e\n\ngitissue works with **zero configuration**. All settings have sensible defaults.\n\nTo customize, create `.gitissue.yml` in your repo root (or run `/init-gitissue`):\n\n```yaml\nplatform: github                # github | gitlab (future)\n\nissue:\n  auto_normalize: true          # auto-normalize in /issue-resolver\n  template: default             # default | path to custom template dir\n  labels_auto_suggest: true     # auto-suggest labels based on content\n  normalize_comment: true       # add comment when normalizing\n\nresolve:\n  approval_gate: auto           # auto | comment-and-wait\n  branch_prefix: \"auto\"         # type-based: fix/42-description, feat/15-description\n  auto_test: true               # run tests before creating PR\n  test_timeout: 300             # abort verify phase after N seconds\n  pr_auto_link: true            # include \"Closes #N\" in PR body\n  max_commits: 10               # warn if resolve produces \u003eN commits\n\ntriage:\n  stale_threshold_days: 14      # flag issues with no activity\n  auto_priority: true           # suggest priorities based on type + age + deps\n  include_closed: false         # include recently closed issues in triage\n  scan_timeout_per_issue: 30    # max seconds to scan codebase per issue\n\nautopilot:\n  mode: conservative            # conservative | balanced | aggressive\n  merge_partial: false          # only meaningful when mode: aggressive\n  max_iterations: 10\n  review_cycles: 3              # max LLM review-fix cycles per PR\n  skip_labels: [\"wontfix\", \"blocked\", \"do-not-merge\"]\n  critical_labels: [\"critical\", \"priority:critical\"]\n\nreview:\n  require_traceability_check: true        # block soft-pass if Closes #N is missing (covers Decision Record presence)\n  require_acceptance_criteria_check: true # block soft-pass if AC Verification fails\n```\n\nFull schema: [`docs/config-schema.md`](docs/config-schema.md)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eIssue Templates\u003c/strong\u003e\u003c/summary\u003e\n\nThree default templates:\n\n- **Bug** -- current vs expected behavior, reproduction context\n- **Feature** -- user story, acceptance criteria\n- **Improvement** -- current state, proposed change\n\nEach normalized issue includes:\n- `\u003c!-- gitissue:normalized v1 --\u003e` marker (invisible in GitHub UI)\n- Reporter's original text in a `\u003e Reporter Context` blockquote\n- Acceptance criteria derived from the reporter's intent\n\n`/issue-creator` is **intent-only** — it never scans the codebase, never lists \"affected files\", and never proposes implementation notes. Codebase analysis is performed at execution time by `/issue-resolver`, `/issue-triage`, and `/issue-analysis`, always against current code.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eProject Structure\u003c/strong\u003e\u003c/summary\u003e\n\n```\nsrc/\n├── shared/\n│   └── agents/                    # Shared agent definitions (used by multiple skills)\n│       ├── codebase-researcher.md # Deep codebase scan + solution research\n│       ├── synthesizer.md         # Analysis + implementation options\n│       ├── implementer.md         # Code + tests implementation\n│       ├── code-reviewer.md       # Confidence-based code review\n│       ├── duplicate-detector.md  # Issue dedup scoring\n│       └── issue-relationship-scanner.md  # File deps + already-fixed detection\n│\n├── skills/\n│   ├── auto-pilot/         # /auto-pilot\n│   ├── issue-analysis/     # /issue-analysis N\n│   ├── issue-creator/      # /issue-creator (+ templates/)\n│   ├── issue-resolver/     # /issue-resolver N\n│   ├── issue-triage/       # /issue-triage\n│   ├── issue-pr-review/    # /issue-pr-review — review, test, CI, fix, merge\n│   └── init-gitissue/      # /init-gitissue\n│       (each skill has SKILL.md, README.md, references/)\n│\n├── internal-skills/\n│   └── idd-doctor/         # /idd-doctor — read-only repo health check\n│\n├── deprecated-skills/\n│   └── issue-pr-review-fix-loop/  # Retained deprecated source only; not distributed\n│\n└── (no docs/ — see below)\n\ndocs/                             # Single docs tree (issue #81)\n├── config-schema.md              # ↓ Runtime docs — bundled into each skill\n├── idd-methodology.md            #   at build time via transitive-closure scan\n├── naming-conventions.md         #   on bare `docs/X.md` tokens\n├── sync-conventions.md\n├── github-projects-sync.md       # ↑\n├── ARCHITECTURE.md               # ↓ Project docs — humans only, not bundled\n├── CHANGELOG.md\n├── DEVELOPMENT.md                # ↑\n├── decisions/                    # Decision records\n├── experiments/                  # Experimental design notes\n└── release-notes/                # Per-release smoke-test reports\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eIDD Methodology\u003c/strong\u003e\u003c/summary\u003e\n\nFull documentation: [`docs/idd-methodology.md`](docs/idd-methodology.md)\n\n\u003c/details\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluongnv89%2Fidd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fluongnv89%2Fidd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluongnv89%2Fidd/lists"}