convez.ai
SkillAutomaçãoAvançado
kurone-kito

IDD Skill — Desenvolvimento Orientado por Issues

kurone-kito/idd-skill

Loop GitHub nativo para agentes IA: issues → branches → PRs → merge

Ver no GitHub
BomPluginScore · de 0 a 100

Skill TypeScript que transforma o fluxo de desenvolvimento de IA em um loop nativo do GitHub, mantendo agentes coordenados desde a descoberta de issues até o merge. Implementa um workflow completo e auditável de Issue-Driven Development com instruções em Markdown reutilizáveis.

Instalação

$npx convez-ai kurone-kito/idd-skill

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
11
Forks
2
Acompanhando
0
Saúde
100%
Último commit
há 1 dia
Versão
—
Issues abertas
14
Contribuidores
4

Casos de uso

  • Coordenar múltiplos agentes IA em um repositório sem conflitos
  • Automatizar workflow de desenvolvimento com auditoria completa em issues
  • Implementar CI/CD orientado por issues com feedback automático

Veredito

Skill robusto para equipes que usam agentes IA e precisam de governança no fluxo de desenvolvimento. Implementação complexa que recompensa com auditoria nativa em GitHub e reutilização de policies entre repositórios.

README

A tradução para o português deste README ainda está na fila.

IDD Skill — Issue-Driven Development workflow

License: MIT Linting CodeRabbit

🌐 Language: English | 日本語

Turn AI coding from one-off prompts into a GitHub-native delivery loop that keeps going until the issue is closed.

IDD Skill gives a repository a portable Issue-Driven Development workflow: agents discover ready issues, claim ownership, implement in a branch, open a PR, handle review feedback, wait for CI, merge, and clean up according to the repository's selected merge policy. The whole loop lives in your repo as Markdown instruction files.

Learn by Example

Follow the VRChat Event Calendar workshop to watch IDD build a real app end to end, then inspect the live companion repository at kurone-kito/vrc-event-calendar.

Start here (persona navigation)

If this is your first visit, choose the path that matches your goal:

GoalStart here
Understand the concept firstdocs/concepts.md
Adopt IDD in my repositoryidd-template/ONBOARDING.md
Run an agent on this repositoryAGENTS.md, CLAUDE.md, GEMINI.md, and .github/copilot-instructions.md
Customize policydocs/customization.md
Author AI-ready issuesskills/issue-authoring/SKILL.md

Why Teams Use IDD

AI coding agents are powerful, but team workflows get messy fast:

  • Two agents can pick the same issue.
  • Review comments can be accepted but never fixed.
  • CI can finish after the agent has already stopped watching.
  • A PR can merge while fresh review activity is still arriving.
  • The workflow rules can hide inside a vendor platform instead of your repository.

IDD Skill turns those moving parts into an auditable GitHub-native loop. Issue comments record claims, review snapshots, decisions, holds, and cleanup markers so another agent can resume the work without guessing.

Quick Start

Install IDD

Open an AI-agent session in the repository that should adopt IDD and say:

Import and onboard github:kurone-kito/idd-skill's IDD into this repository.

If the agent needs an explicit URL, use:

Read https://raw.githubusercontent.com/kurone-kito/idd-skill/main/idd-template/ONBOARDING.md and onboard this repository for Issue-Driven Development.

The onboarding guide collects project-specific values, copies the portable template, and updates the agent entry files. No manual file copying is required when the agent has the needed GitHub access.

Run the Loop

After onboarding, start an agent in the target repository and say:

Start the IDD workflow in this repository.

The agent reads the workflow guide, discovers a ready issue, claims it, and follows the loop through work, PR review, CI, the selected merge policy, and cleanup.

Validate onboarding with IDD doctor (optional)

After importing IDD, run the doctor script once in a repository that has the helper installed (this source repository includes it by default) to catch common setup drift:

node scripts/idd-doctor.mjs

The report checks core IDD file presence, unresolved placeholders, marker-prefix consistency, command-table sanity, and (when gh access is available) branch-protection and required-check signals.

Reality Check

IDD is Markdown-native, not dependency-free.

To run the full loop, an agent needs:

  • git
  • An authenticated gh CLI or equivalent GitHub MCP integration
  • jq
  • A REST client such as curl
  • Node.js/npm with npx (optional for non-Node.js projects — see Tooling boundary)
  • Repository-scoped GitHub credentials appropriate for the chosen merge policy
  • Branch protection and required review policy already configured when those gates are part of the loop

See the workflow docs for the detailed command contract. Review Permissions and threat model before granting credentials to unattended or merge-capable agents. The distributed default allows worker sessions to continue through merge (fully_autonomous_merge). human_merge and separate_merge_agent keep merge authority outside the worker session by explicit opt-in. Choose and record one profile in Customizing IDD.

Footprint and sizing guidance

IDD keeps instruction growth mechanically bounded. The maintained budget values are tracked in policy docs and enforced by audit metadata rather than hand-counted file totals:

Budget typeMaintained value
Always-loaded instruction file20,000 bytes
Phase instruction file30,000 bytes
Discovery bundle (bundle-discovery)75,300 bytes
Resume bundle (bundle-resume)46,000 bytes

See Policy constants: Runtime Instruction Size and Bundle Budgets for the canonical table and ownership details.

To inspect current source-repo footprint evidence:

node scripts/audit-docs.mjs --check
jq '.instructionSizeBudgets, .bundleBudgets' audit/sync-manifest.json

audit-docs verifies that the current instruction files still fit the maintained limits, and sync-manifest.json carries the budget contract.

For adopters, practical loop pressure depends on helper runtime choices:

  • Prefer helper runtime support when you want lower day-to-day context pressure in E/F phases (helper commands collect evidence, while merge and mutation decisions still follow written gates).
  • Keep instructions-only when your repository avoids Node.js/helper tooling or your team prefers a fully manual shell/gh/jq path.
  • Expect variance either way: local policy additions, local docs, and extra repository instructions can make your practical footprint smaller or larger than this source repository.

Use ONBOARDING Step 1B policy decisions and helper runtime selection order to pick a profile deliberately.

Operational Evidence

As of 2026-05-12, this repository has been dogfooding IDD through multi-agent, multi-session runs, including bursts of roughly x4-6 parallel sessions. The workflow also originated in a private work repository and was later backported here, where it was exercised for about two weeks with roughly x8-10 concurrent Copilot CLI sessions. That is not zero-failure; it is a workflow that keeps getting tightened as edge cases appear.

Local pnpm tooling baseline (contributors to this repository only)

This repository uses a project-local pnpm baseline and Husky hooks so contributors and autopilot runs can enforce the minimum lint gate before commit. This section is specific to dogfooding work in this source repository. Template adopters do not need pnpm — use your project's existing tooling and configure the validate commands accordingly. See Tooling boundary for adopter-facing guidance.

corepack enable
pnpm install
pnpm run lint
pnpm run test

The pre-commit hook runs pnpm run lint:minimum, and the commit message hook enforces Conventional Commits through commitlint.

When you edit canonical source files in idd-template/, run pnpm run docs:sync to propagate the changes to all mirrored artifacts.

What IDD Automates

IDD is intentionally boring in the best way: every phase has a named job, a resumable marker, and a next step.

StageWhat the agent does
DiscoverFinds ready roadmap or orphan issues without silently widening scope.
ClaimReserves one issue with a machine-readable ownership marker.
WorkCreates a branch/worktree, plans, implements, and self-reviews.
Submit PRPushes, opens a PR, and waits for validation to become reviewable.
Review LoopCaptures review activity, accepts or rejects feedback, and fixes accepted items.
MergeRechecks freshness, advisory review state, CI, unresolved threads, comments, and the selected merge policy.
CleanupAfter a completed merge, hides stale markers when safe and loops back.

The full phase map lives in docs/idd-workflow.md and the .github/instructions/ files.

What You Get

  • Collision-resistant parallel work — Claim and heartbeat markers make issue ownership visible without a central coordinator.
  • Fewer stalled PRs — The workflow keeps watching review comments, CI, and follow-up fixes after the initial pull request opens.
  • Portable rules, not a black box — The workflow is plain Markdown that can be inspected, forked, and customized in the target repo.
  • Agent choice — The core loop works across GitHub Copilot, Claude Code, OpenAI Codex CLI, and Gemini CLI. The distributed default PR policy still includes a Copilot advisory review step, with documented review policy profiles for adopters who use another gate.
  • No service to operate — Import the template files; no separate server, scheduler, or SaaS account is required to start.

For deeper positioning, see docs/positioning.md.

What This Repository Ships

The primary package is idd-template/: a portable set of .github/instructions/ files, onboarding docs, workflow docs, and a machine-readable policy file (.github/idd/config.json) that adopters copy into their own repositories. The policy file lets agents and tools read repository settings (merge policy, command strings, marker prefix) without parsing Markdown.

This repository also includes compatibility entry files such as AGENTS.md, CLAUDE.md, GEMINI.md, and .github/copilot-instructions.md so different agents know where to start here.

Native SKILL.md bundles are optional companions. The canonical source bundle in this repository lives at skills/issue-authoring/; when you install it in a target repository, place it in the agent-specific skill directory your runtime reads, such as .github/skills/, .claude/skills/, or .agents/skills/. They can help with pre-execution tasks such as issue drafting, but they do not replace the portable instruction template.

This source repository's optional helper bundle also includes a maintainer-facing forced-handoff path. idd-force-handoff is a TTY-only operator command that asks for an issue number, asks for a PR number only when a live open PR exists on the active claim branch, previews the successor claim IDs and marker body, and then requires a final y/N confirmation before posting anything. The lower-level idd-forced-handoff-marker helper remains available for rendering or inspection, but unattended or autopilot contexts must not use the interactive facade.

For AI Agents

If a user points you at github:kurone-kito/idd-skill and asks you to onboard IDD, fetch this file first:

https://raw.githubusercontent.com/kurone-kito/idd-skill/main/idd-template/ONBOARDING.md

Follow it exactly. It explains which files to copy, which placeholders to fill, and which target-repository entry files to update.

When a Request Is Too Big

Use the optional issue-authoring companion before the IDD execution loop when a request needs decomposition, dependency encoding, or roadmap and sub-issue drafting.

In this repository, ask an agent to:

  • Use the $issue-authoring skill to draft IDD-ready issues.
  • Open skills/issue-authoring/SKILL.md and prepare the issue set.

Issue authoring only prepares issue drafts and hygiene. Publishing issues or starting Discover -> Claim -> Work still requires explicit approval.

Deeper Reference

License

MIT

Ver o original no GitHub

Bom para

Relacionados