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

Flow

  1. Install

    Bootstraps the operating contract and the IDD artifact set.

  2. Bootstrap

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

  3. 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.

  4. 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.

  5. Execute

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

  6. Enforce

    Approving a learned rule compiles it in the same session: mechanical rules become linter config or committed ast-grep checks that session hooks run on every edit and as a blocking gate on git commit; judgment rules become path-scoped instruction files plus a mandatory in-session review of the diff before it's proposed. Everything runs in-session — no CI, no git hooks. Enforced rules drop out of prose, keeping the rule set small.

  7. 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. The hooks 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 as the blocking in-session commit gate.

  2. Install jq

    brew install jq. The hooks use it to read the harness event payload.

Footprint

.github/ ├── copilot-instructions.md ├── prompts/ │ ├── idd-discover.prompt.md │ ├── idd-init.prompt.md │ ├── idd-feature.prompt.md │ └── idd-lint.prompt.md └── idd/ ├── architecture.md ├── conventions.md ├── learned.md ├── checks/ ├── templates/ ├── wiki/ └── features/