{
  "markdown": "# Intention-Driven Design\n\n**Making meaning explicit, executable, and continuously verified — so systems can scale without semantic drift.**\n\nIntention-Driven Design (IDD) is a methodology for building software where every artifact traces back to a declared human intent. Code is a downstream consequence of intent, never the starting point. We allow change, but we do not allow drift.\n\n## Why IDD exists\n\nAgentic coding tools are remarkably capable at execution but have a subtle failure mode: they optimize locally without a global ground truth. They can write perfect code for the wrong thing. Spec-driven development moved the answer earlier in the process, but still asks \"what should the system do?\" — IDD asks **\"why should the system exist at all?\"** and makes that *why* a first-class, traceable artifact.\n\nThe result is a framework where AI agents can autonomously implement, verify, and evolve software while humans focus on meaning, tradeoffs, and creative decisions.\n\nIDD can also be extended through explicit agent roles: bounded execution\ncontracts that let multiple agents develop the methodology or a target system in\nparallel without breaking traceability.\n\n## How it works\n\n```\n┌──────────────────────────────────────────────────────────────┐\n│                      NARRATIVE LAYER                         │\n│   Personas ──▶ Journeys ──▶ Stories                          │\n│   (who/why)    (experience)   (what)                         │\n│                                          /solution-narrative │\n├──────────────────────────────────────────────────────────────┤\n│                       MODEL LAYER                            │\n│                  Domain Models                               │\n│                  (concepts, rules, lifecycles)               │\n│                                           /domain-modeling   │\n├─────────────────────────────────────────────────────────────┤\n│                     CONTRACT LAYER                           │\n│   Features ◀── Contracts ──▶ Fixtures                        │\n│   (Gherkin)    (OpenAPI / AsyncAPI / JSON-RPC)               │\n│                                        /behavior-contract    │\n├──────────────────────────────────────────────────────────────┤\n│                  IMPLEMENTATION LAYER                        │\n│   Backend ◀──────────────────────▶ Frontend                  │\n│   (any stack)                      (any stack)               │\n│                                                              │\n├──────────────────────────────────────────────────────────────┤\n│                    VALIDATION LAYER                          │\n│   Unit Tests ── Integration ── E2E Journey Tests             │\n│   (domain)      (contract)     (experience)                  │\n│                                     /e2e-journey-testing     │\n├─────────────────────────────────────────────────────────────┤\n│                   CERTIFICATION LAYER                        │\n│   Evidence tied to intent ── published before merge          │\n│                                                              │\n└──────────────────────────────────────────────────────────────┘\n```\n\nEvery downstream artifact references its upstream source:\n\n```\nPersona → Journey → Story → Feature → Contract → Tests → Evidence\n```\n\nNo link in the chain is optional.\n\n## Quick example: from intent to evidence\n\nA stakeholder says: *\"Someone at a trade show should be able to sign up and start an audit on their phone while we're talking to them.\"*\n\nIDD breaks this into a traceable chain:\n\n| Layer | Artifact | What it captures |\n|-------|----------|------------------|\n| Narrative | `specs/personas/trade-show-prospect.md` | Who: mobile, distracted, skeptical |\n| Narrative | `specs/journeys/trade-show-signup.md` | Experience: QR scan → signup → first audit |\n| Narrative | `specs/stories/onboarding/mobile-signup.md` | Capability: quick mobile account creation |\n| Model | `specs/models/audit/audit.model.yaml` | Concept: Audit entity, states, rules |\n| Contract | `specs/features/onboarding/mobile-signup.feature` | Behavior: Gherkin scenarios |\n| Contract | `specs/contracts/openapi/api.yaml` | HTTP boundary: `POST /accounts`, `POST /audits` |\n| Contract | `specs/contracts/asyncapi/audit-events.yaml` | Event boundary: `publish audits/created` |\n| Contract | `specs/contracts/json-rpc/account-service.yaml` | RPC boundary: `account.getQuickStartPrompt` |\n| Contract | `specs/fixtures/onboarding/mobile-signup.json` | Test data: request/response pairs |\n| Implementation | Backend + Frontend code | Derived from contracts |\n| Validation | `frontend/e2e/journeys/trade-show-signup.spec.ts` | E2E test following the journey |\n| Certification | CI evidence report (per capability) | Automated evidence tied to intent — generated in CI, published as job summary, PR comment, and workflow artifact; never committed |\n\nEvery artifact in the chain references the one above it. An agent — or a human — can trace any line of code back to the persona goal that motivated it.\n\nSee [`examples/`](specs/) for a complete working fixture set of these artifact types, wired for tooling validation.\n\n## Visualizing the spec graph\n\nGenerate a Mermaid traceability graph from front-matter metadata:\n\n```bash\nnode tools/graph-generation/generate-spec-graph.js specs --format mermaid > specs/GRAPH.md\n```\n\nTo inspect this repository's example fixtures:\n\n```bash\nnode tools/graph-generation/generate-spec-graph.js examples --format mermaid\n```\n\n## Core principles\n\n1. **Intent precedes code.** No implementation without an explicit intent artifact.\n2. **Shared mental models are artifacts, not conversations.** If a concept matters, it has a file.\n3. **Contracts define reality at boundaries.** OpenAPI, AsyncAPI, and JSON-RPC contracts are the source of truth, not implementation.\n4. **Assumptions must become executable.** Untested assumptions are technical debt.\n5. **Feedback must be fast, honest, and automated.** Evidence, not confidence theater.\n6. **Human cognition is protected.** Agents handle bookkeeping; humans handle meaning.\n7. **Evolution must preserve meaning.** We allow change, but we do not allow drift.\n\nRead the full [manifesto](docs/idd/manifesto.md).\n\n## Stack-agnostic by design\n\nThe narrative, model, and contract layers are completely technology-independent. The `specs/` directory works the same whether your implementation uses Spring Boot, Express, Django, Rails, Angular, React, or anything else. Each consumer binds its own stack-specific implementation skills in `specs/skills/repo-overlay.md` without changing the upstream artifacts.\n\n## Installation\n\n> **Internal UAT:** the toolkit is restarting its public version line at\n> `0.1.0-uat.N`. These builds are prerelease, non-production candidates. The\n> retired prototype line is preserved under `legacy/v1.*` tags, but should not\n> be used for new installations.\n\n### As a ChatGPT / Codex plugin (core skills)\n\nThe repo also exposes a Codex plugin through `.codex-plugin/plugin.json` and a\nrepo-scoped marketplace at `.agents/plugins/marketplace.json`. This surface\nloads the core methodology skills from `skills/`. The plugin source also\ncarries the IDD CLI, validators, schemas, docs, and reusable GitHub Action.\n\nFor installation from GitHub:\n\n```bash\ncodex plugin marketplace add slusset/intention-driven-design --ref main\ncodex plugin add idd-skills@idd\n```\n\nIf `idd-skills` was installed from the retired `1.x` prototype line, remove it\nonce with `codex plugin remove idd-skills@idd`, refresh the marketplace, and\ninstall again. A normal update cannot be assumed to accept a SemVer downgrade.\n\nIn the ChatGPT desktop app, restart after adding the repo marketplace, then\ninstall `idd-skills` from the Intention-Driven Design marketplace. Use a new\nconversation after installation so the host loads the current skill set.\nUpdate both the desktop and CLI environments with:\n\n```bash\ncodex plugin marketplace upgrade idd\ncodex plugin add idd-skills@idd\n```\n\n### As a Claude Code plugin (recommended)\n\nThe repo is a self-contained Claude Code plugin — `.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json` are at the repo root. One install brings the core methodology skills (`skills/`), schemas, and the `idd` validator CLI (the plugin's `bin/` is added to Bash PATH while active, so skills and you can run `idd validate all` with no separate install). Plugin caches do not install `node_modules`; the PATH wrapper falls back to the committed self-contained bundle `dist/bin/idd.js` (built by `just build`), which inlines the CLI, every validator, and the runtime dependencies, so `idd version`, `idd doctor --json`, and `idd validate all --json` work from a fresh plugin install with no `npm install` or `npm link`.\n\nIn Claude Code:\n\n```\n/plugin marketplace add slusset/intention-driven-design\n/plugin install idd-skills@idd\n```\n\nSkills are namespaced as `idd-skills:<name>` (e.g. `/idd-skills:certification`). If you previously copied skills via `idd install-skills claude`, remove those copies from `~/.claude/skills/` — copied and plugin skills coexist under different names and can double-trigger.\n\nIf the plugin was installed from the retired `1.x` prototype line, uninstall\nit once with `claude plugin uninstall idd-skills@idd`, refresh the marketplace,\nand install it again before following the normal update flow.\n\nUpdate with `claude plugin update idd-skills@idd`, then restart Claude or\nreload plugins when prompted. Third-party marketplace auto-update can also be\nenabled in Claude's plugin manager.\n\nFor plugin development from a local checkout: `/plugin marketplace add ~/dev/idd`, refresh after edits with `/plugin marketplace update idd`, or use `claude --plugin-dir ~/dev/idd` for an ephemeral single-session load. Validate changes with `just validate-plugin` (runs `claude plugin validate --strict` on the marketplace and plugin manifests — CI runs the same checks).\n\n### As an npm package (for CI and local dev ergonomics)\n\n```bash\nnpm install --save-dev github:slusset/intention-driven-design#v0.1.0-uat.1\nnpx idd validate all          # run validators outside of Claude Code\n```\n\nRelease Please versions the npm package, lockfile, and both plugin manifests\ntogether on the `0.1.0-uat.N` line. `just validate-plugin` checks the\nCodex/ChatGPT manifest, the core-only skills boundary, bundled tooling, and the\nexisting Claude plugin manifests.\n\nRelease preparation and publication are both manual:\n\n```bash\njust release-prepare          # preflight, then dispatch the prepare workflow\n# review and merge the generated release PR\njust release-publish\n```\n\n**Pull request titles must be Conventional Commits.** Release Please only\ncounts commits whose subject it can parse, and a squash merge takes the pull\nrequest title as that subject. A title like `Implement open issues` is dropped\noutright — its body bullets are not rescued — so the workflow succeeds while\nproposing no release PR at all. `.github/workflows/pr-title.yml` fails a\nnon-conventional title at PR time, and `just release-preflight` (which\n`release-prepare` depends on) reports whether the commits since the last\nrelease would actually produce a release:\n\n```bash\njust release-preflight\n# Release preflight since 0.1.0-uat.2 (anchor: release-commit)\n#   commits: 1; releasable (feat/fix/breaking): 0; unparseable: 1\n```\n\nIf unparseable work has already landed on `main`, release it by merging a\nlater conventional commit; add a `Release-As: <version>` footer to that\ncommit's message when the version must be exact.\n\n### Local development (from checkout)\n\n```bash\ngit clone git@github.com:slusset/intention-driven-design.git\ncd intention-driven-design\njust install                   # npm install && npm link\n```\n\n### Initialize a new project\n\n```bash\nnpx idd init .                 # scaffolds specs/ structure + CI workflow\nnpx idd install-skills claude\n```\n\n### CLI reference\n\n```\nidd validate <check...>       Run validators (or \"all\")\nidd install-skills <target>   Install skills to claude/codex/all\n  --link                       Symlink instead of copy (dev mode)\n  --check                      Check if installed skills are current\nidd generate-evidence          Generate certification evidence manifest\n                               (into .idd/evidence/ — CI report input, not committed)\nidd init [dir]                 Scaffold IDD directory structure\nidd doctor [--repo <dir>]      Inspect migration alignment/catalog (report-only)\nidd doctor plan [--out <file>] Generate a deterministic, digest-pinned migration plan\n                              --from-schema <version> bootstraps an unrecorded consumer\nidd doctor apply --plan <file> Apply an accepted plan (--accept <migration-id>,\n                               writes .idd/evolution/ evidence, never journal history)\nidd evidence record ...        Write one formal-result record for an observed probe\n                               (into .idd/evidence/results/, expected outcome resolved from the maps)\nidd evidence rollup            Derive per-rule coverage and per-capability verification claims\n                               from a run's records, beside the declared claims (--strict gates)\nidd version                    Print version\n```\n\n### Installing skills for AI agents\n\n**Claude Code:** prefer the plugin install above. The copy flow below still works but is deprecated for Claude Code — copied skills coexist with plugin skills under different names and can double-trigger.\n\n**Codex (and Claude Code legacy copy flow):**\n```bash\nidd install-skills codex       # copies versioned skills to ~/.codex/skills/\nidd install-skills claude      # deprecated for Claude Code — use the plugin\nidd install-skills all         # both\n```\n\n**GitHub Copilot App, CLI, VS Code, cloud agent, and code review:**\n\n```bash\ngh skill install slusset/intention-driven-design --all \\\n  --agent github-copilot --scope user\ngh skill update --all\n```\n\nProject scope is the default and is the right choice when Copilot cloud agent\nor code review must consume committed skills from a downstream repository.\nGitHub's installer records source provenance, so `gh skill update` can detect\nupstream changes.\n\n**Other agents (Cursor, Gemini CLI, etc.):**\nAll skills follow the [Agent Skills open standard](https://agentskills.io), and\ncurrent GitHub CLI releases can install them for many supported hosts with\n`gh skill install --agent <host>`.\n\nSee [Release and Distribution](docs/idd/release-and-distribution.md) for the\nrelease lifecycle, desktop/CLI update matrix, verification commands, and the\nboundary with field synchronization work in issues #56–#58.\n\n### CI with GitHub Actions\n\nConsuming repos can use the reusable action:\n\n```yaml\n- uses: slusset/intention-driven-design/.github/actions/idd-check@v0.1.0-uat.1\n  with:\n    checks: all\n```\n\nDuring UAT, pin the exact accepted candidate. No floating major Action tag is\npublished for prerelease or `0.x` builds.\n\nOr install the toolkit directly:\n\n```yaml\n- run: npm install github:slusset/intention-driven-design\n- run: npx idd validate all --json\n```\n\n## Repo overlay and implementation skills\n\nIDD's narrative, model, and contract skills stay stack-agnostic. The core pack does not bundle or discover framework-specific implementation skills. Each consumer repository uses `specs/skills/repo-overlay.md` to bind exact skill identifiers to backend, frontend, mobile, infrastructure, SDK, design, or framework-specific testing areas and to state where those skills are provided from.\n\nThe `idd-workflow` skill loads that overlay before implementation work. If a binding is absent, IDD selects no stack-specific skill and follows the repository's architecture docs, commands, and a generic implementation checklist. Framework files and the active plugin catalog never authorize automatic skill selection.\n\n## Agent roles as an IDD extension\n\nWhen work is split across multiple humans or agents, define a role contract for\neach actor:\n\n- owned boundary\n- required inputs\n- decisions it may make autonomously\n- outputs it must produce\n- invariants it must preserve\n- handoff target and success evidence\n\nThis extends IDD through agency rather than bypassing it. The role governs how\nwork is executed; the artifact spine still governs what must remain true.\n\nSee [Agent Role](docs/idd/agent-role.md) and [Agent Operating Contract](docs/idd/agent-operating-contract.md).\nFor the broader systems view, see [Self-Evolving Engineering Ecosystem](docs/idd/self-evolving-ecosystem.md).\nFor governing changes to IDD itself, see [Methodology Change Process](docs/idd/methodology-change-process.md).\nFor consumer upgrades and continuity dispositions, see [Evolution and Migration](docs/idd/evolution-and-migration.md).\n\n## Skills\n\n| Skill | Purpose | Invocation |\n|-------|---------|------------|\n| **Solution Narrative** | Personas, journeys, stories — the \"why\" | `/solution-narrative` |\n| **Domain Modeling** | Entities, aggregates, business rules | `/domain-modeling` |\n| **Behavior Contract** | BDD features, OpenAPI/AsyncAPI/JSON-RPC contracts, fixtures | `/behavior-contract` |\n| **E2E Journey Testing** | Playwright tests from journey maps | `/e2e-journey-testing` |\n| **Certification** | Traceability verification and evidence manifests | `/certification` |\n| **IDD Doctor** | Report-only migration alignment and continuity inspection | `/idd-doctor` |\n| **IDD Workflow** | Meta-skill: when to use which skill | `/idd-workflow` |\n\nSkills are designed to be invoked in sequence: narrative → model → contract → implementation → validation → certification. For a consumer UAT update, run `/idd-doctor` before planning or applying migration work. Each skill's output feeds the next.\n\n## Implementation skill bindings\n\nStack-specific skills are consumer-owned dependencies, not part of the IDD release. Install them through the mechanism appropriate to the active agent host, then bind them explicitly in the consuming repository's overlay. This keeps framework choices and versions local to the repository that depends on them.\n\n## Repository layout\n\n```\nbin/\n└── idd.js                   CLI entrypoint (npm bin)\n\ndocs/idd/                    IDD philosophy and concept library\n├── manifesto.md             Core principles (the \"why\")\n├── concepts.md              Atomic concept catalog (C1–C17)\n├── concept-skill-map.md     Which concepts each skill carries\n├── agent-operating-contract.md  Non-negotiable agent rules\n├── agent-role.md            Agent-role extension for orchestrated agency\n├── self-evolving-ecosystem.md  Runtime + world-model framing around IDD\n├── methodology-change-process.md  How IDD changes should follow IDD\n├── templates/               Reusable methodology templates\n├── project-template.md      Artifact spine and delivery loop\n└── certification-guide.md   Evidence standards and templates\n\nmigrations/                  Report-only methodology migration catalog\n├── catalog.json              Ordered schema transition metadata\n└── catalog.schema.json       Catalog shape contract\n\nskills/                      IDD methodology skills (bundled in package)\n├── solution-narrative/      Personas, journeys, stories\n├── domain-modeling/         Entities, aggregates, business rules\n├── behavior-contract/       BDD features, protocol contracts, fixtures\n├── e2e-journey-testing/     Playwright journey tests\n├── module-scaffolding/       Bounded-context module creation and linking\n├── idd-doctor/               Read-only migration alignment and continuity inspection\n├── certification/           Traceability verification and evidence\n└── idd-workflow/            Meta-skill: when to use which skill\n\ntools/                       Validators and generators\n├── validate-modules.js      Validate exact capability ownership and the module dependency DAG\n├── validate-verification.js Validate root-aware verification maps and cross-module relation semantics\n├── validate-front-matter.js Validate required/recommended metadata fields\n├── validate-traceability.js Validate cross-artifact reference integrity\n├── validate-capability-scope.js Validate capability scope coverage\n├── validate-capability-closure.js Validate capability scope as a reference closure\n├── validate-contracts.js    Validate OpenAPI, AsyncAPI, and JSON-RPC contracts\n├── validate-fixtures.js     Validate fixtures against protocol-specific contract schemas\n├── validate-models.js       Validate model/lifecycle structural rules\n├── validate-enforcement-bindings.js Validate model rule enforced: bindings resolve to real artifacts\n├── validate-journey-maps.js Validate journey map structural rules\n├── generate-evidence.js     Generate certification evidence manifests (CI report input)\n├── graph-generation/        Mermaid spec traceability graph generators\n└── lib/                     Shared parsing and formatting helpers\n\n.github/actions/idd-check/   Reusable GitHub Action for consuming repos\n```\n\n## Validation Suite\n\nRun all validators at once:\n\n```bash\nidd validate all --json\n```\n\nOr run individual checks:\n\n```bash\nidd validate traceability front-matter --json\nidd validate fixtures models --strict\n```\n\nAvailable validators: `modules`, `verification`, `contracts`, `traceability`, `front-matter`, `capability-scope`, `capability-closure`, `fixtures`, `models`, `enforcement-bindings`, `journey-maps`, `evidence`.\n\n### Evaluating the methodology itself\n\nThe same validators double as the deterministic checker tier of the\nmethodology-evaluation instrument in [`evals/`](evals/README.md): scenario +\ncondition trials recorded as closed, digest-pinned `experiment-record@1`\nartifacts, with a small pinned judged tier. The instrument lives outside the\nrelease unit and no benchmark number ever gates a merge — see the charter in\n`evals/README.md`.\n\n## Module scaffolding\n\nCreate a bounded-context module chain without moving or overwriting existing specifications:\n\n```bash\nidd module create billing --root specs --dry-run\nidd module create billing --root specs\nidd module link billing --depends-on identity-kernel\nidd module link billing --capability billing --contract specs/contracts/identity-kernel.schema.json\nidd module status --json\nidd doctor --json\n```\n\nCreation writes a capability stub, module-owned model/feature/protocol-contract/\nfixture directories, a planned verification map, and one `specs/modules.yaml`\nentry. Linking changes only an explicit DAG edge or a selected map's digest\npin; it never moves existing specs or edits a contract's `x-rules`.\n\n`idd doctor` inspection is report-only. It inspects consumer/version alignment,\ndeprecated structures, validator findings, and cataloged schema migration paths\nwithout writing files or mutating journal history; `idd doctor plan` and\n`idd doctor apply` execute accepted migrations through registered\ntransformations. Findings carry discriminating ids (`validator-<check>-<code>`)\nand the text report groups them by id; `--severity error`, `--summary`, and\n`--verbose` control what is shown. See\n[`docs/idd/evolution-and-migration.md`](docs/idd/evolution-and-migration.md).\n\nThe CLI also installs standalone, outside any plugin host or `node_modules`:\n`install/idd-install.sh` puts an immutable release under\n`~/.idd/toolkits/<version>/` and links `idd` into `~/.local/bin`. See\n[`docs/idd/release-and-distribution.md`](docs/idd/release-and-distribution.md).\n\nConsumer repositories can record their accepted toolkit contract in the\n`idd_consumer` front-matter block of `specs/skills/repo-overlay.md`. The record\npins the toolkit release, schema-registry version/digest, and distribution\nprovenance; it is separate from the consumer's own IDD modules and capabilities.\n\nCommon CLI options:\n- `--files <paths...>` limit checks to specific files\n- `--json` machine-readable output for CI aggregation\n- `--strict` treat warnings as errors\n\n## How concepts and skills relate\n\nConcepts ([`docs/idd/concepts.md`](docs/idd/concepts.md)) are the atomic units of IDD philosophy. Skills ([`skills/`](skills/)) are operational implementations that embody subsets of those concepts. The mapping between them is tracked in [`docs/idd/concept-skill-map.md`](docs/idd/concept-skill-map.md).\n\nWhen converting a skill to a new agent platform:\n1. Check which concepts the skill carries (the map).\n2. Use the concept catalog as the acceptance checklist.\n3. Ensure no concept is lost or contradicted in translation.\n\n## Source of truth policy\n\n1. Concept definitions in `docs/idd/` are authoritative for meaning.\n2. Skills in `skills/` are authoritative for operational implementation.\n3. Runtime copies (`~/.claude/skills`, `~/.codex/skills`) are installed via `idd install-skills` and version-stamped. Run `idd install-skills --check` to detect staleness.\n\n## Self-referential note\n\nThis repository is itself organized as an IDD project. `docs/idd/` is the narrative and concept layer. `skills/` is the implementation layer. `tools/` is the validation layer. `concepts.md` is the domain model for the methodology itself. The framework describes itself.\n\n## Origin\n\nIDD was developed collaboratively by [Ted Slusser](https://github.com/slusset) with AI as a design partner — human intuition driving the exploration, AI reasoning through the structure. The methodology is being refined through prototype and downstream projects across different technology stacks. Its current UAT status is an explicit maturity boundary, not a production-readiness claim.\n\n## License\n\nMIT\n",
  "bytes": 25431,
  "sha": "a2812d14e32d31d79643c17678d7689cbe6d7c64b69b970ace9703c0f750e9fe",
  "repo_slug": "slusset/intention-driven-design",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_slusset_intention_driven_design_intentio_8290ac15/readme"
}