PsychQuant · kiki830621 · Jun 30, 2026
diff --git a/openspec/changes/codify-claude-canonical-runtime/.openspec.yaml b/openspec/changes/codify-claude-canonical-runtime/.openspec.yaml
@@ -0,0 +1,4 @@
+schema: spec-driven
+created: 2026-06-30
+created_by: che cheng <kiki830621@gmail.com>
+created_with: codex
diff --git a/openspec/changes/codify-claude-canonical-runtime/design.md b/openspec/changes/codify-claude-canonical-runtime/design.md
@@ -0,0 +1,73 @@
+## Context
+
+IDD plugin skills currently use Claude Code as their native execution language. The skill bodies name Claude runtime primitives such as AskUserQuestion, EnterPlanMode, TaskCreate, Agent, SendMessage, Skill(...), Claude plugin install commands, and `.claude/.idd` state paths. That language is intentional: it encodes the workflow discipline IDD relies on.
+
+At the same time, the same Markdown skill tree can be exposed to Codex or other agent runtimes through platform-specific plugin shells. The goal is not to make Claude and Codex identical. The goal is to preserve the Claude-defined workflow semantics as the canonical contract and give non-Claude runtimes an explicit compatibility map.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- State that Claude Code is the canonical runtime for IDD skills.
+- State that `skills/` remains the canonical source tree for IDD behavior.
+- Add `references/claude-code-tools.md` documenting the native Claude contracts used by the skills.
+- Add `references/codex-tools.md` documenting Codex interpretation, fallback limits, and degraded behavior rules.
+- Update README and CLAUDE.md so maintainers know non-Claude runtimes are compatibility shells, not equal sources of truth.
+
+**Non-Goals:**
+
+- Do not fork `skills-codex/`.
+- Do not rewrite existing SKILL.md files into runtime-neutral language.
+- Do not implement a Codex plugin shell in this change.
+- Do not change `.claude/.idd` state namespace or migration behavior.
+- Do not promise full Codex runtime parity for Claude-only constructs.
+
+## Decisions
+
+### Claude Code remains the canonical runtime
+
+IDD skill semantics SHALL be defined first by Claude Code behavior. Other runtimes may load the same skills, but their adapters must preserve the Claude-defined workflow semantics or explicitly mark degraded fallback behavior.
+
+Alternative considered: declare a platform-neutral abstract runtime as the canonical contract. Rejected because current IDD discipline depends on concrete Claude runtime affordances such as plan-mode locking and stage-level task harnesses.
+
+### Keep the shared skills tree canonical
+
+The repository SHALL keep `plugins/issue-driven-dev/skills/` as the single canonical skill source. Compatibility guidance belongs in references and platform shells, not copied skill trees.
+
+Alternative considered: create `skills-codex/`. Rejected until a specific skill proves impossible to express through compatibility guidance without breaking Claude-native behavior.
+
+### Runtime mapping is reference documentation, not behavior rewrite
+
+`claude-code-tools.md` SHALL describe native Claude contracts. `codex-tools.md` SHALL map those contracts to Codex-compatible handling, including when a fallback is degraded or unavailable. Existing skill bodies may continue to name Claude-native tools.
+
+Alternative considered: edit every SKILL.md to include Codex-specific branches. Rejected because it would add noise to the canonical skill instructions and increase maintenance cost before actual runtime gaps are measured.
+
+## Implementation Contract
+
+Observable behavior: maintainers reading the plugin documentation can tell that Claude Code is the canonical runtime, `skills/` is the canonical source tree, and Codex or other runtimes are compatibility consumers. A Codex runner reading `references/codex-tools.md` gets a concrete mapping for common Claude-native primitives and can identify when behavior is degraded.
+
+Data shape:
+
+- `plugins/issue-driven-dev/references/claude-code-tools.md` exists and documents native semantics for AskUserQuestion, EnterPlanMode, TaskCreate/TaskUpdate/TaskList, Agent/SendMessage, Skill(...), Claude plugin commands, `.claude/.idd`, and CLAUDE_PLUGIN_ROOT.
+- `plugins/issue-driven-dev/references/codex-tools.md` exists and maps those same primitives to Codex behavior or explicit degraded fallback.
+- `plugins/issue-driven-dev/README.md` states the canonical-runtime policy and references both mapping files.
+- `plugins/issue-driven-dev/CLAUDE.md` states the maintainer policy: keep Claude-native SKILL.md instructions canonical and add non-Claude compatibility through references/adapters before forking skill trees.
+
+Acceptance criteria:
+
+- The two new reference files contain matching sections for the same tool-contract vocabulary.
+- Documentation does not claim Codex has full runtime parity.
+- Documentation does not require a `skills-codex/` fork.
+- `spectra validate codify-claude-canonical-runtime` succeeds.
+- `spectra analyze codify-claude-canonical-runtime --json` reports no Critical or Warning findings.
+
+Scope boundaries:
+
+- In scope: documentation and Spectra artifacts.
+- Out of scope: plugin shell manifests, runtime code, hooks, state migrations, and edits to individual skill execution steps.
+
+## Risks / Trade-offs
+
+- [Risk] Codex support may look weaker because degraded fallbacks are explicit. -> Mitigation: explicit boundaries are safer than silent semantic drift.
+- [Risk] Maintainers may still copy skills for convenience. -> Mitigation: document that forks are last resort and require a concrete incompatibility.
+- [Risk] Reference mappings can drift from skill bodies. -> Mitigation: keep the mapping vocabulary focused on stable runtime primitives rather than every individual step.
diff --git a/openspec/changes/codify-claude-canonical-runtime/proposal.md b/openspec/changes/codify-claude-canonical-runtime/proposal.md
@@ -0,0 +1,34 @@
+## Why
+
+IDD skills were designed around Claude Code runtime semantics, but the repository is starting to expose the same skill tree to other agent runtimes such as Codex. Without an explicit compatibility policy, maintainers may either over-neutralize the canonical Claude workflow language or accidentally let non-Claude runtimes reinterpret critical workflow gates.
+
+## What Changes
+
+- Document Claude Code as the canonical runtime for IDD skills.
+- Add runtime compatibility references that map Claude-native tool contracts to Codex-compatible interpretations and fallback limits.
+- Update plugin documentation so other runtimes are described as compatibility shells that must preserve Claude-defined workflow semantics or explicitly mark degraded behavior.
+- Keep the shared `skills/` tree as the canonical source; do not fork `skills-codex/` or rewrite existing skill bodies into runtime-neutral language in this change.
+
+## Capabilities
+
+### New Capabilities
+
+- `runtime-compatibility-guidance`: Defines IDD's canonical-runtime policy and runtime tool mapping references for Claude Code and Codex.
+
+### Modified Capabilities
+
+(none)
+
+## Impact
+
+- Affected specs: runtime-compatibility-guidance
+- Affected code:
+  - New: plugins/issue-driven-dev/references/claude-code-tools.md
+  - New: plugins/issue-driven-dev/references/codex-tools.md
+  - New: openspec/changes/codify-claude-canonical-runtime/specs/runtime-compatibility-guidance/spec.md
+  - Modified: plugins/issue-driven-dev/README.md
+  - Modified: plugins/issue-driven-dev/CLAUDE.md
+  - Modified: openspec/changes/codify-claude-canonical-runtime/proposal.md
+  - Modified: openspec/changes/codify-claude-canonical-runtime/design.md
+  - Modified: openspec/changes/codify-claude-canonical-runtime/tasks.md
+  - Removed: none
diff --git a/...es/codify-claude-canonical-runtime/specs/runtime-compatibility-guidance/spec.md b/...es/codify-claude-canonical-runtime/specs/runtime-compatibility-guidance/spec.md
@@ -0,0 +1,58 @@
+## ADDED Requirements
+
+### Requirement: Claude Code is the canonical IDD runtime
+
+IDD skills SHALL treat Claude Code as the canonical runtime for workflow semantics. Other agent runtimes that load the same skill source tree through compatibility shells MUST preserve the Claude-defined workflow semantics or explicitly mark any degraded fallback.
+
+#### Scenario: non-Claude runtime cannot provide an equivalent primitive
+
+- **WHEN** a non-Claude runtime encounters a Claude-native primitive that it cannot faithfully emulate
+- **THEN** it documents the behavior as degraded rather than silently weakening the workflow gate
+- **AND** it does not redefine the canonical skill semantics
+
+##### Example: structured user choice is unavailable
+
+- **GIVEN** Claude Code exposes `AskUserQuestion` with structured choices
+- **AND** Codex support only has a plain-text user prompt available for that workflow
+- **WHEN** a skill requires the user to choose between `diagnose`, `implement`, and `verify`
+- **THEN** the Codex mapping documents the fallback as degraded
+- **AND** the skill still treats the Claude Code behavior as canonical
+
+### Requirement: Shared skills tree remains canonical
+
+The repository SHALL keep `plugins/issue-driven-dev/skills/` as the canonical source tree for IDD skill behavior. Platform-specific support MUST prefer compatibility references, adapters, or plugin shell metadata before introducing a forked skill tree.
+
+#### Scenario: Codex support needs tool interpretation
+
+- **WHEN** Codex support needs to interpret a Claude-native tool contract
+- **THEN** the mapping is documented in a reference file or adapter layer
+- **AND** `skills-codex/` is not introduced unless a specific incompatibility is documented
+
+### Requirement: Runtime tool mappings are explicit
+
+The plugin documentation SHALL provide runtime tool mapping references for Claude Code and Codex. The Codex mapping MUST name unsupported or degraded behavior explicitly.
+
+#### Scenario: maintainer reviews runtime compatibility
+
+- **WHEN** a maintainer needs to assess whether a skill can run under Codex
+- **THEN** they can compare `references/claude-code-tools.md` and `references/codex-tools.md`
+- **AND** both references use the same tool-contract vocabulary
+- **AND** Codex-specific limitations are visible in the mapping
+
+### Requirement: Documentation avoids full-parity claims
+
+The plugin documentation SHALL distinguish between loading the shared skill tree and achieving full runtime parity. Documentation MUST NOT imply that a compatibility shell makes every Claude-native skill contract fully equivalent in another runtime.
+
+#### Scenario: user reads runtime support docs
+
+- **WHEN** a user reads the plugin README
+- **THEN** they see that Claude Code is the canonical runtime
+- **AND** they see that other runtimes are compatibility consumers of the same skills
+- **AND** they see references for runtime tool mappings
+
+##### Example: README points to compatibility references
+
+- **GIVEN** a user opens `plugins/issue-driven-dev/README.md`
+- **WHEN** they read the runtime support section
+- **THEN** they see that `skills/` is shared across supported shells
+- **AND** they see links to `references/claude-code-tools.md` and `references/codex-tools.md`
diff --git a/openspec/changes/codify-claude-canonical-runtime/tasks.md b/openspec/changes/codify-claude-canonical-runtime/tasks.md
@@ -0,0 +1,13 @@
+## 1. Runtime Reference Documents
+
+- [x] 1.1 Deliver Runtime tool mappings are explicit, Claude Code is the canonical IDD runtime, and Claude Code remains the canonical runtime by adding `plugins/issue-driven-dev/references/claude-code-tools.md` with native semantics for AskUserQuestion, EnterPlanMode, TaskCreate/TaskUpdate/TaskList, Agent/SendMessage, Skill(...), Claude plugin commands, `.claude/.idd`, and CLAUDE_PLUGIN_ROOT; verify by content review that every listed primitive has a concrete Claude-native contract.
+- [x] 1.2 Deliver Runtime tool mappings are explicit for Codex by adding `plugins/issue-driven-dev/references/codex-tools.md` with the same section vocabulary as `claude-code-tools.md`, mapping each primitive to Codex handling or an explicit degraded/unavailable fallback; verify by comparing headings between the two reference files and checking Codex limitations are named.
+
+## 2. Plugin Documentation
+
+- [x] 2.1 Deliver Documentation avoids full-parity claims by updating `plugins/issue-driven-dev/README.md` to state Claude Code is the canonical runtime, other runtimes are compatibility consumers, and full runtime parity is not implied by shared skill loading; verify the README links to both runtime mapping references and does not require a `skills-codex/` fork.
+- [x] 2.2 Deliver Shared skills tree remains canonical, Keep the shared skills tree canonical, and Runtime mapping is reference documentation, not behavior rewrite by updating `plugins/issue-driven-dev/CLAUDE.md` with maintainer policy that existing SKILL.md files stay Claude-native, non-Claude compatibility belongs in references/adapters first, and forked skill trees require a documented incompatibility; verify content review confirms the policy names the shared `skills/` tree.
+
+## 3. Verification
+
+- [x] 3.1 Verify the runtime-compatibility-guidance contract by checking matching reference headings, running `spectra validate codify-claude-canonical-runtime`, and running `spectra analyze codify-claude-canonical-runtime --json`; completion requires no Critical or Warning findings.
diff --git a/plugins/issue-driven-dev/CLAUDE.md b/plugins/issue-driven-dev/CLAUDE.md
@@ -6,6 +6,23 @@ Issue-driven development：每個改動都從 issue 出發，每個 issue 都有
 
 Issue 是人和 AI 的介面 — 人負責「什麼是對的」，AI 負責「怎麼做到」。
 
+## Runtime Compatibility Policy
+
+Claude Code 是 IDD skills 的 canonical runtime。`plugins/issue-driven-dev/skills/` 是唯一 canonical
+skill source tree；既有 `SKILL.md` 可以繼續使用 Claude-native tool contract，例如
+`AskUserQuestion`、`EnterPlanMode`、`TaskCreate`、`Agent`、`SendMessage`、`Skill(...)`、
+`.claude/.idd` 與 `CLAUDE_PLUGIN_ROOT`。
+
+非 Claude runtime（例如 Codex）是 compatibility consumer，不是另一個同等規格來源。支援其他 runtime
+時，優先新增 reference / adapter / plugin shell metadata，並保留 Claude-defined workflow semantics。
+若無法等價保留，必須明確標示 degraded fallback；禁止靜默弱化 gate。
+
+維護規則：
+- 不為了 Codex 或其他 runtime 先行 fork `skills-codex/`。
+- 不把 canonical `SKILL.md` 大量改寫成平台中立抽象語言。
+- 只有在具體 skill 證明無法透過 compatibility mapping 保留語意時，才可提案局部 fork。
+- Runtime 對照表見 [`references/claude-code-tools.md`](references/claude-code-tools.md) 與 [`references/codex-tools.md`](references/codex-tools.md)。
+
 ## 鐵律:Step 0 Bootstrap Stage Task List(v2.18.0+)
 
 **每個 stage skill 的第一個動作必須是 `TaskCreate`**,把該 stage 的所有 execution sub-steps 建成 harness-level todo list。完成每一步立即 `TaskUpdate → completed`。**靜默完成 = 違規**。

diff --git a/plugins/issue-driven-dev/README.md b/plugins/issue-driven-dev/README.md
@@ -15,6 +15,25 @@ A Claude Code plugin that enforces issue-driven development as a complete method
 4. **Every completion is independently verified** — no "looks good enough"
 5. **Every closure is documented** — knowledge preserved
 
+## Runtime support
+
+Claude Code is the canonical runtime for IDD skills. The shared `skills/` tree is the canonical
+source of workflow semantics; non-Claude runtimes are compatibility consumers of those same skills.
+
+Other runtimes, including Codex, can load or interpret the shared skills when a platform shell or
+adapter is available, but shared skill loading does not imply full runtime parity. If a runtime
+cannot preserve a Claude-defined workflow gate, it must mark the fallback as degraded instead of
+silently weakening the IDD contract.
+
+Runtime mapping references:
+
+- [`references/claude-code-tools.md`](references/claude-code-tools.md) — native Claude Code tool contracts
+- [`references/codex-tools.md`](references/codex-tools.md) — Codex compatibility mapping and degraded fallback rules
+
+The project does not maintain a `skills-codex/` fork. Forked skill trees are a last resort and need
+a documented incompatibility that cannot be handled through references, adapters, or plugin shell
+metadata.
+
 ## Why?
 
 Each skill guards against a specific failure mode:

diff --git a/plugins/issue-driven-dev/references/claude-code-tools.md b/plugins/issue-driven-dev/references/claude-code-tools.md
@@ -0,0 +1,91 @@
+# Claude Code Tool Contracts
+
+Claude Code is the canonical runtime for IDD skills. This reference records the native tool semantics that existing `SKILL.md` files may rely on.
+
+Non-Claude runtimes can load or interpret the same skills, but they must preserve these workflow semantics or explicitly mark a degraded fallback.
+
+## AskUserQuestion
+
+`AskUserQuestion` is the native attended-decision primitive. IDD uses it when a decision changes workflow state, repository targeting, issue scope, follow-up filing, or PR/direct-commit path.
+
+Required semantics:
+
+- Present bounded options to the user.
+- Wait for a user answer unless the enclosing skill explicitly declares unattended mode.
+- Treat the selected option as an audit-relevant decision.
+- Never replace an irreversible GitHub side-effect decision with a silent default.
+
+## EnterPlanMode
+
+`EnterPlanMode` is a Claude Code runtime gate that locks the session into read-only planning semantics until the user exits or approves the plan.
+
+Required semantics:
+
+- No state-mutating tools run while plan mode is active.
+- The implementation plan is shown before execution.
+- User approval or revision controls whether execution continues.
+- Plain text confirmation is not equivalent when read-only enforcement matters.
+
+## TaskCreate / TaskUpdate / TaskList
+
+`TaskCreate`, `TaskUpdate`, and `TaskList` provide the stage-level harness for IDD skills.
+
+Required semantics:
+
+- Each stage skill creates a visible task list before doing stage work.
+- Each sub-step is marked complete immediately after it is actually complete.
+- Silent completion is a process bug.
+- The stage task list complements, but does not replace, issue checklist contracts.
+
+## Agent / SendMessage
+
+`Agent` and `SendMessage` are Claude-native fan-out and recovery primitives used by review, verification, and orchestration flows.
+
+Required semantics:
+
+- Reviewer prompts remain isolated unless a later merge step intentionally combines findings.
+- Recovery prompts must restate enough context for an idle or restarted agent.
+- Missing reviewer output is reported as a process gap, not silently ignored.
+
+## Skill(...)
+
+`Skill(...)` delegates to another installed skill while preserving that skill's own contract.
+
+Required semantics:
+
+- Delegation is explicit and named.
+- The receiving skill controls its own preconditions, gates, and side effects.
+- Orchestrators pass mode hints such as unattended behavior through arguments or context, not by editing the callee contract.
+
+## Claude plugin commands
+
+Claude plugin commands are the canonical install and dependency-management surface for this package.
+
+Examples:
+
+```bash
+claude plugin marketplace add PsychQuant/issue-driven-development
+claude plugin install issue-driven-dev@issue-driven-development
+```
+
+Detection helpers may inspect Claude plugin cache paths only where the relevant skill documents that trust model.
+
+## .claude/.idd
+
+`.claude/.idd` is the canonical IDD state namespace for per-repo config, state, and attachments.
+
+Required semantics:
+
+- Runtime state and audit artifacts stay under `.claude/.idd` unless a migration is explicitly specified.
+- Walk-up config resolution treats existing `.claude` paths as durable compatibility surface.
+- Non-Claude runtimes must not silently invent a different state namespace for the same IDD workflow.
+
+## CLAUDE_PLUGIN_ROOT
+
+`CLAUDE_PLUGIN_ROOT` is the Claude-side way to locate plugin-bundled scripts or assets from inside installed plugin execution.
+
+Required semantics:
+
+- Script resolution should prefer plugin-bundled paths when the skill depends on shipped helper scripts.
+- If a helper is not on `PATH`, the skill should resolve it relative to the plugin root.
+- A missing plugin root is a runtime compatibility issue, not permission to silently skip helper-backed behavior.