IDD · Quick Start

Write applications, not source code.

IDD is a repo-native contract for describing software in natural language. You and Copilot maintain the intent; the model maintains the code. It is dramatically more productive than hand-writing every line, and it gets better every time the model does.

Install

curl -fsSL https://raw.githubusercontent.com/dan1hc/idd/main/install.sh | bash

This is the only command you ever run in a terminal. The installer is non-activating: it stages the inert IDD artifact layer (artifact scaffolds, templates, scripts, the review policy, ast-grep wiring via sgconfig.yml, a .gitignore entry for .idd-state/) and the on-demand slash commands — nothing that injects instructions, hooks a session, or gates anything. Everything after it happens in-session — open your agent and run /idd-activate to opt in per integration (explicitly confirmed in-chat, recorded locally, reversible; the agent runs .github/idd/bin/idd-activate.sh on your behalf). Upgrading from an older IDD? Re-installing never removes the legacy always-on hooks and contract — /idd-activate detects them and offers migration (idd-activate.sh migrate) before you re-enable anything.

Flow

  1. Install

    Stages the operating contract and the IDD artifact set — inert until you activate.

  2. Activate

    Run /idd-activate in your agent (Copilot discovers it from .github/prompts/; in a harness without prompt-file discovery, ask the agent to follow .github/prompts/idd-activate.prompt.md). It confirms each integration with you in-chat and enables only what you choose, independently, for your clone only; a committed IDD configuration is never consent for other contributors.

  3. Bootstrap

    Run /idd-init for a new repo, or /idd-discover against an existing one. Copilot seeds architecture, conventions, and the first wiki entries.

  4. Think in the wiki

    You and Copilot flesh out a concept, subsystem, or feature as one or more wiki entries. This is the design surface. No code yet.

  5. Derive feature specs

    Run /idd-feature. The wiki entry holds the concept; each feature spec is one bounded change to it. A wiki entry can spawn many feature specs over time — initial build, additions, refactors.

  6. Execute

    Copilot works through specs sequentially under Red / Green TDD, then writes back so prose follows source.

  7. Enforce

    Approving a learned rule compiles it in the same session: mechanical rules become linter config or committed ast-grep checks that opt-in session hooks run on every edit and again on git commit — deterministic checks only; judgment rules become path-scoped instruction files plus the on-request /idd-judgment-review — tool-less, context-isolated adversarial reviewer subagents (at most six rules each, per the committed review policy) that never see the authoring context and must cite the code for every verdict, writing fingerprint-bound receipts. Repairs re-review only changed units, orchestration stops after one delta pass and escalates the rest, and the review is advisory — no hook triggers it and a missing receipt blocks nothing. Everything runs in-session — no CI, no git hooks. Enforced rules drop out of prose, keeping the rule set small.

  8. Review

    Run /idd-lint on demand to sweep for drift, duplicates, orphans, broken anchors, and enforcement sync (rule ↔ check ↔ compiled artifact).

Enforcement setup

Enforcement runs entirely in-session, so there are no repo secrets and no branch-protection settings — and it is opt-in: hooks exist only after you enable them via /idd-activate — Claude Code's claude-hooks (.claude/settings.local.json), GitHub Copilot's (CLI, cloud coding agent, VS Code agent mode) copilot-hooks (.github/hooks/idd.json) — the agent runs idd-activate.sh for you. Enabled hooks enforce deterministic checks only and need two local tools; without them they degrade to silent no-ops:

  1. Install ast-grep

    brew install ast-grep (or npm i -g @ast-grep/cli). Runs the committed mechanical checks on every edit and again on git commit.

  2. Install jq

    brew install jq. The hooks use it to read the harness event payload; idd-review.sh uses it for plans and receipts.

The judgment review is manual and advisory: no hook triggers it, and a missing, stale, or failing receipt blocks nothing. idd-review.sh verify deterministically checks the session-local receipts written by /idd-judgment-review (in .idd-state/, gitignored) against fingerprints of the exact change set and rule set — on request, and no LLM ever runs inside a hook.

Footprint

.github/ ├── prompts/ │ ├── idd-activate.prompt.md │ ├── idd-discover.prompt.md │ ├── idd-init.prompt.md │ ├── idd-feature.prompt.md │ ├── idd-judgment-review.prompt.md │ └── idd-lint.prompt.md └── idd/ ├── operating-contract.md ├── architecture.md ├── conventions.md ├── learned.md ├── review-policy.yml ├── bin/ ├── checks/ ├── check-tests/ ├── templates/ ├── wiki/ └── features/ sgconfig.yml (ast-grep wiring — created or extended) opt-in, per contributor (idd-activate.sh): .github/copilot-instructions.md · CLAUDE.md · .cursorrules .claude/settings.local.json · .github/hooks/idd.json .idd-state/ (consent + receipts, gitignored)