IDD Framework Plugin for Codex and Claude Code

One shared plugin packages sixteen portable skills, including a complete workflow router. Claude also retains its fifteen command aliases and fourteen role agents.

Installation

See the installation guide for native Codex, native Claude and standalone npx skills choices, local refresh/removal and prerequisites. The new catalogs are available in this local migration checkout; they have not been published to GitHub's default ref or the external Claude marketplace.

Local native commands use the repository root as the marketplace source:

codex plugin marketplace add /absolute/path/to/idd-framework --json
codex plugin add idd-framework@idd-framework-local --json

Or, from a Claude consuming project:

claude plugin marketplace add /absolute/path/to/idd-framework --scope project
claude plugin install idd-framework@idd-framework-local --scope project --json

Avoid duplicate native and standalone installations. CLI/cache lifecycle evidence does not certify every native workflow. All eight Archive observations are now accepted, and native/router implementation closures are complete. Actual human review, native alias execution and publication remain pending.

What Is IDD?

Intent-Driven Development replaces traditional sprint-based agile with a "chain of context" model designed for AI-augmented teams. It decomposes purpose into four levels:

Product          ->  "Here's why this exists and who it's for."
  Intention      ->  "Here's what we're trying to accomplish and why it matters."
    Expectation  ->  "Here's how we'll know it's right, including the edge cases."
      Spec       ->  "Here's everything you need to build it."

Each layer gives developers and AI agents the context they need to make implementation decisions independently.

Commands

Phase 0 — /chart + /resolve: efforts too foggy to interview get an Exploration map of decision tickets, resolved one per session until the way is clear.

Core Pipeline

Accelerated Workflows

Tooling

Each command is an entry point with prerequisites; you do not have to start at interview. The inventory above contains all 15 commands.

Agents

The plugin supplies these 14 role agents.

Quick Start

Standard Pipeline (step-by-step)

1. Define your product:

   /idd-framework:interview My Dashboard Project
   

2. Break it into intentions:

   /idd-framework:define-intentions PROD-a3f8
   

3. Define expectations with edge cases:

   /idd-framework:define-expectations INT-7c21
   

4. Write the spec:

   /idd-framework:write-spec EXP-9b04 EXP-3f2a
   

5. Review for architectural fit:

   /idd-framework:tech-review SPEC-d12e
   

   Resolve technical findings and record actual human peer review plus all readiness items before marking ready. AI approval alone does not do this.

6. Run the pre-build gap-check:

   /idd-framework:gap-check SPEC-d12e
   

   Resolve outstanding findings and rerun until passed with zero unresolved blockers and warnings. The annotation and report must agree.

7. Implement the gated Spec:

   /idd-framework:implement-spec SPEC-d12e
   

   The command verifies evidence before writes, acknowledges Boundaries, and enters in-progress. A verified complete build enters review. Human implementation approval then permits validating.

8. Validate the implementation against the Spec:

   /idd-framework:review-spec SPEC-d12e
   

Fast Track (after Product is defined)

/idd-framework:quick-spec PROD-a3f8 "Users can view their onboarding checklist and track progress"
/idd-framework:tech-review SPEC-d12e

This produces Intentions, Expectations, and a Spec in a single guided session. Continue through human readiness review, gap-check, implementation and validation as above; the accelerated authoring path does not bypass execution prerequisites.

Execution contract

The bundled lifecycle reference is the installed workflow contract. Technical/deep review preserve lifecycle; human peer review is needed for ready. Execution requires ready, a current gap_check.status: passed, zero unresolved counts, and the matching per-Spec report beginning PASS — 0 blockers, 0 warnings with ## Coverage. A report headed PASS with warnings is not executable.

Accepted coverage omissions remain visible; the reviewer must confirm the author's reason leaves no unmet validation dependency before marking them resolved. Substantive warnings require resolution. Repeated checks update one annotation; failed completeness or unsuccessful review uses blocked and report: null, so an old report cannot authorize a build. Failed or interrupted implementations remain in-progress even if a partial report exists. These are agent protocol instructions, not an executable state validator. Resume requires a recovery decision.

Native Codex and Claude packaging is implemented with isolated CLI lifecycle evidence. Final upstream acceptance, desktop discovery and publication remain separate.

Output

All artifacts are saved to docs/ in your project root:

docs/
  products/       # Product definitions (YAML)
  intentions/     # Intention artifacts (YAML)
  expectations/   # Expectation artifacts with edge cases (YAML)
  specs/          # AI-ready Specs with 5 mandatory blocks (YAML)
  reviews/        # Gap-check, execution, validation and archive reports
  explorations/   # EXPL-<id>-<slug>/map.md and decision tickets
  idd-ledger.yaml # Archive ledger: distilled records of completed/retired artifacts

Completed artifacts don't accumulate forever: /idd-framework:archive rolls terminal artifacts into docs/idd-ledger.yaml and deletes the originals, with a git tag per archive run so any artifact's full text remains one git show <tag>:<path> away.

IDD Roles

The framework defines six roles. Each maps to a plugin agent:

• Product Owner -- Defines Products and Intentions; validates outcomes
• Spec Author -- Translates Intentions into AI-ready Specs (new role in IDD)
• Tech Lead -- Reviews for architectural fit; manages Boundaries
• Developer -- Partners with AI agents; makes autonomous decisions within Spec context
• AI Agent -- Executes against Specs; produces Deliverables
• Reviewer -- Validates output against Expectations and Boundaries

Plugin Features

• Lazy docs initialization — Commands create directories when needed; implementation checks the gate and acknowledges Boundaries before creating any
• User config — Set default_product_id and team_name at plugin install for faster workflows
• Helper scripts — idd-next-id (in bin/) generates a unique short-hash artifact ID (e.g., SPEC-a3f8); checked against existing live paths (reconcile unseen branch collisions during integration)
• Reviewer memory — Tech lead and spec reviewer agents accumulate project-specific learnings across sessions
• Agent Teams support — /idd-framework:deep-review uses parallel Agent Teams when the experimental flag is enabled, with graceful fallback to sequential review

Developing the plugin

The maintained router is workflows/idd-orchestration.md. Its six historical reference paths map to portable sources in references/authoring/, references/pilot/, references/exploration/ and references/archive/. From the repository root, run npm ci with Node.js 22.20.0+, edit those sources, and run npm run build:skills to refresh the committed copies in skills/idd-orchestration/. skill-catalog.json defines each mapping and lists fifteen implemented portable stages, sixteen public bundles (including the router), and no placeholder stages. The router includes complete stages/<stage>/workflow.md closures copied from the same canonical mappings.

Run npm run check and npm test before submitting changes. The optional npm run test:install verifies the synthetic fixture and each pilot skill alone in disposable Codex and Claude projects, in copy and symlink modes. Host workflow evaluation is separate. All five router and eight Archive host observations have independent acceptance, with original failures and measured-lane limits retained. See the contributor guide for check behavior, fixture profiles and CI.

License

Apache 2.0 -- see LICENSE.

Portable workflow pilot

This branch includes sixteen complete standalone skill bundles: fifteen direct stages and one complete router. The original three-stage pilot has a documented supported-lane acceptance; the five authoring stages have separate host evaluation evidence:

The Claude aliases load these shared procedures. Their names and frontmatter stay unchanged; reviewer/implementer model choices remain in the Claude adapter. Each standalone bundle contains its own references and any required helper, with no runtime npm dependency added to the consuming project. The interview helper needs Bash, and artifact workflows need safe YAML parsing available in the host environment; missing capabilities are reported before writes. The router includes every stage locally and never relies on a sibling skill. Archive and router host acceptance are complete for the documented cases; native alias execution and published remote installation remain separate checks.

For a local pilot, build this checkout, then run the following from a disposable consuming project, replacing the absolute source path with this checkout:

npx --yes skills@1.5.25 add /absolute/path/to/idd-framework/plugin/skills/idd-interview --agent codex claude-code --skill idd-interview

Use any skill in the table in both source path and --skill to install that stage alone. Add --copy to test a source-independent copy. Select just --agent codex or --agent claude-code if you want one host. These commands are project-scoped; avoid installing duplicate native-plugin and standalone copies in the same host. This branch is unpushed, so GitHub shorthand would still fetch the earlier repository state rather than these changes.

Start a fresh session in that consuming project and request the installed skill by name (for example, $idd-gap-check in Codex or /idd-gap-check in Claude Code), or provide its installed SKILL.md path explicitly. The unattended evaluator uses explicit paths; selector discovery and native alias UX still need interactive review. Full native Codex plugin installation is a later milestone.

Run npm run test:install for deterministic package checks. Optional host scenarios and evidence handling are described in the contributor guide. See the pilot evaluation report for actual tested behavior and limitations. Installation success does not certify model behavior, human review or release readiness.

The optional host evaluator can diagnose Claude output-style conflicts with --claude-output-style default. This affects only the test process, preserves the configured model, and is recorded separately from runs with the configured style. Styles that suppress intermediate messages may conflict with IDD's required pre-write Boundary acknowledgments; a final execution report cannot replace them.

The implementation pilot also has an optional staged evaluation controller. It validates two read-only acknowledgment turns in one Claude session before enabling the build, and verifies evidence before changing lifecycle to review. See the controller instructions and recovery evidence. This is development tooling in the source checkout. Installing the standalone skill does not install that controller or certify ordinary/native Claude execution.

Installed guarded execution pilot

The idd-implement-spec bundle now includes a self-contained Node >=22.20.0 terminal runner for existing Claude authentication. It requires reviewed execution_contract output/check metadata and recorded readiness approval. Use node <installed-skill>/scripts/idd-execute-spec.mjs --project <project> --spec <SPEC-ID> --check for read-only preflight; omit --check to execute from a separate terminal. Never bypass the nested-session guard. The default preserves the configured model/style; optional --implementer-model sonnet requires an observed matching implementation model. The Sonnet option has verified model selection but remains experimental after a failed full workflow trace review. Native alias certification remains separate.

The bundle carries the pinned YAML parser and ISC license; consuming projects need no dependency installation. Failures preserve partial work and controller evidence, and require author recovery. See guarded execution for ownership, limits and report rules. Optional contributor host evaluation: node scripts/evaluate-installed-execution.mjs (or --negative, --sonnet). Offline tests use simulated host receipts and do not replace actual host evidence.

Portable authoring

The five authoring skills share references/authoring/authoring.md as their maintained procedure and each bundles its required templates, references and executable ID helper. Selection, confirmation, validation and saves stay in the stakeholder conversation. Optional Claude drafting preserves existing model policy and returns read-only proposals. Accelerated modes save no intermediate YAML until every proposed Expectation has at least two explicitly confirmed edge cases. All new artifacts remain draft; content confirmation never supplies human Spec peer review.

Parent context baselines begin when loaded, and only an existing Intention expectations list may be changed. Concurrent edits or interrupted saves are reported with exact partial state; there is no automatic rollback or atomic multi-file guarantee. See the authoring evidence for observed cases and limitations.

Portable review stages

The three review bundles share references/review/review.md in the source tree. Technical/deep orchestration invalidates old approval before reviewing, preserves all Spec content/lifecycle/gap bytes, and publishes only current findings. Deep review labels actual parallel, partial or sequential coverage. Implementation validation writes only its report, runs explicitly specified safe bounded checks, and leaves unavailable historical evidence and pending human checks unverified. Such pending items prevent an unqualified Pass.

See review host evidence for the current evaluation state. Native aliases and parallel dispatch are separate acceptance gates.

Portable Forge launcher

Install idd-forge alone using the same local pattern above. It accepts --port, --no-open and --docs as literal arguments, launches from the consuming root through an available background process capability, and reports the actual startup URL and owned stop handle. It uses the existing unpinned npx --yes @jasonrobey/idd-forge policy; Node20+ and npm access may be required for the published app. It initializes no IDD artifacts.

The migration evaluator substitutes an explicitly controlled local launcher in an isolated child PATH and verifies arguments, process inspection and owned cleanup; this does not certify the published UI, native aliases or cross-session persistence. See Forge evidence.

Portable exploration

idd-chart and idd-resolve each install independently with complete formats/procedure and ID helper. Main conversation owns stakeholder questions, claims and serialized writes; optional Sonnet research roles remain Claude-specific and read-only. A claim commit contains only the selected tracked, clean ticket and preserves unrelated staged/dirty work. Unpublished factual research proposals can be investigated before exclusive creation; persisted tickets always require their claim. Missing human answers never become resolutions.

The map is clear only when fog is empty and every ticket is resolved or out_of_scope with valid dependencies; an empty frontier alone is insufficient. The same terminal correction is included in the legacy reference. See exploration evidence for controlled facts/claim tests and unverified native/concurrent-session behavior.

Portable archival

idd-archive classifies first and saves a fresh manifest for review. Explicit apply requires the concrete manifest committed with its unchanged reviewed input files. It creates an annotated recovery tag, saves and rereads a reconciled ledger, then removes/moves only approved paths and commits locally. Artifact records and moved-review records both contribute to the new record count; co-deleted subject reviews are links only. Sources are normalized in memory and surviving artifacts remain unchanged.

Legacy manifests need reclassification to capture the new reviewed-input binding before apply. Tag recovery supports Git file modes (0644/0755); unsupported permission modes refuse. See Archive evidence for disposable trials, failures and limitations. Native aliases and remote publication remain separate verification.

Complete router and local distribution

Install just the router from a built local checkout to access all stages:

npx --yes skills@1.5.25 add /absolute/path/to/idd-framework/plugin/skills/idd-orchestration --agent codex --skill idd-orchestration --copy

Use --agent claude-code for Claude. Ask the installed router for the intended outcome or stage. It loads stages/<stage>/workflow.md and resolves resources from that entry's parent, preserving the selected procedure's confirmation, readiness and execution gates. Routing never creates consumer directories. The nested implementation CLI is stages/implement-spec/scripts/idd-execute-spec.mjs; run it from a separate terminal when the selected workflow requires the guarded Claude controller. Never clear the nested-Claude guard.

For bulk local installation, point add at plugin/skills, use the selected --agent and --skill '*', and retain --copy if that is your chosen mode. Discovery (add <source> --list) exposes sixteen public names; nested entries are workflow.md, so they do not become duplicate skills. Bulk installation is optional: the router alone already contains the full workflow closure.

Pinned skills1.5.25 skips local sources during npx --yes skills@1.5.25 update idd-orchestration --project --yes. This is a no-op, not a content update. Refresh a local installation by repeating its original add command with the same absolute source, selected skill, host and copy option. Remote update behavior is not inferred from this local test.

Remove a selected skill with npx --yes skills@1.5.25 remove idd-orchestration --agent codex --yes (or claude-code). Name every intended skill explicitly; avoid --all across unrelated skills. Verify the installed paths afterward: skills1.5.25 can report success while retaining .agents/skills/<name> for other detected agents that share it. Retained copies remain installed, including for Codex; a success message alone is not complete removal. A separate Claude alias/copy can be removed while that canonical copy remains. Preserve other agents' shared skills; this procedure does not silently broaden deletion.

Codex uses the project's canonical .agents/skills directory. Claude symlink mode points .claude/skills/<name> at that project-local copy; it does not link to the source checkout. Claude copy mode has an independent copied directory. Avoid duplicate native-plugin and standalone installations of the same skills. See the router evidence for observed scope, retained failures and unfinished acceptance.

Pinned installer mode detail: targeting a single host forces copy, even without --copy. The four bulk observations compare explicit copy and default requests while recording actual copy mode. Genuine Claude symlinks are tested separately by the individual probe, which targets Codex and Claude together. Refresh retains actual mode; no additional host is silently selected to force a symlink.