# Install Option Matrix

PRD Plugin has four install options that can be combined. Each option
controls which skills, scripts, and config sections are installed in a
downstream repo.

## Options

| Option | Flag | Purpose |
| --- | --- | --- |
| `codex` | `--codex` | Install Codex skill discovery under `.agents/skills/` |
| `opencode` | `--opencode` | Install opencode skill discovery under `.opencode/skill/` |
| `claude` | `--claude` | Enable Claude Code plugin-primary support through `.claude/settings.json`, hooks, and commands |
| `opencode-skill-inject` | `--opencode-skill-inject` | Configure opencode-agent-skills auto-injection in `opencode.json` |

## Defaults

- `codex` is installed by default.
- `opencode` is installed by default.
- `claude` is enabled by default.
- `opencode-skill-inject` is on by default when `opencode` is enabled.

Claude Code is plugin-primary by default. The `claude` option writes the
repo-scoped `extraKnownMarketplaces` + `enabledPlugins` config in
`.claude/settings.json`, so Claude loads `prd-plugin@prd-plugin` from the
versioned plugin. It also installs Claude hooks and commands. It does not copy
project-level `.claude/skills/` unless the explicit `--claude-skills` escape
hatch is set.

## Skill Matrix

Each row is a skill. The columns are host delivery surfaces. A check means the
skill is delivered to that host. Codex and opencode receive repo-local skill
copies by default. Claude receives the same canonical skills from the enabled
plugin by default; the project-level `.claude/skills/` copy is written only by
`--claude-skills` or `prd_install_skills.py --target-agent claude`.

| Skill | codex | opencode | claude |
| --- | --- | --- | --- |
| project-architecture | yes | yes | yes |
| project-blocker-resolution | yes | yes | yes |
| project-brainstorm | yes | yes | yes |
| project-change-request | yes | yes | yes |
| project-code-review | yes | yes | yes |
| project-decision-ledger | yes | yes | yes |
| project-decision-policy | yes | yes | yes |
| project-deterministic-workflows | yes | yes | yes |
| project-document-branch | yes | yes | yes |
| project-evidence | yes | yes | yes |
| project-evidence-ledger | yes | yes | yes |
| project-git-workflow | yes | yes | yes |
| project-health | yes | yes | yes |
| project-implementation-plan | yes | yes | yes |
| project-implementation-planning | yes | yes | yes |
| project-local-integration | yes | yes | yes |
| project-memory | yes | yes | yes |
| project-llm-wiki | yes | yes | yes |
| project-planning-lifecycle | yes | yes | yes |
| project-prd | yes | yes | yes |
| project-prd-plugin-setup | yes | yes | yes |
| project-request-intake | yes | yes | yes |
| project-self-audit | yes | yes | yes |
| project-session-close | yes | yes | yes |
| project-systematic-debugging | yes | yes | yes |
| project-test-driven-implementation | yes | yes | yes |
| project-traceability-review | yes | yes | yes |
| project-traceability-sync | yes | yes | yes |
| project-verification-before-completion | yes | yes | yes |
| project-fold-it-in (hub only) | — | — | — |

## Script Matrix

A check means the script is installed by default. `opt` means it is
optional and requires `--include-optional-scripts`. Hub-only scripts are
never installed in downstream.

| Script | codex | opencode | claude |
| --- | --- | --- | --- |
| prd_install_skills.py | yes | yes | yes |
| prd_gate.py | yes | yes | yes |
| prd_status.py | yes | yes | yes |
| prd_reporting.py | yes | yes | yes |
| prd_config.py | yes | yes | yes |
| prd_workflows.py | yes | yes | yes |
| prd_substrate.py | yes | yes | yes |
| prd_substrate_catalog.py | yes | yes | yes |
| prd_substrate_links.py | yes | yes | yes |
| prd_runtime_worker.py | yes | yes | yes |
| prd_services.py | yes | yes | yes |
| prd_test_scope.py | yes | yes | yes |
| prd_reflections.py | yes | yes | yes |
| prd_graph.py | yes | yes | yes |
| prd_hooks.py | | | yes |
| automation_guard.py | yes | yes | yes |
| request_autosubmit.py | yes | yes | yes |
| request_export.py | opt | opt | opt |
| request_pull.py | opt | opt | opt |
| request_reply.py | opt | opt | opt |
| prd_doctor.py | opt | opt | opt |
| message_check.py | yes | yes | yes |
| state_consistency_check.py | yes | yes | yes |
| skill_usage_report.py | opt | opt | opt |
| prd_install.py (hub only) | — | — | — |
| release_check.py (hub only) | — | — | — |
| local_workflow_check.py (hub only) | — | — | — |
| gap_audit.py (hub only) | — | — | — |
| version_advice.py (hub only) | — | — | — |
| request_import.py (hub only) | — | — | — |
| request_mailbox.py (hub only) | — | — | — |

`prd_config.py` is the unified configuration surface on every host. Host
manifests use `.prd_plugin/hooks/prd_hook_dispatch.py`, so each event launches
at most one Python process and enabled work is selected from the same
`.prd_plugin/config.json`. Upgrade installs add missing `configuration.*` and
`hooks.*` defaults without replacing existing choices.

### MCP state server

Every install also copies the MCP state server to
`.prd_plugin/mcp/server.cjs` and merges a `prd-plugin` entry into the repo's
`.mcp.json` (additive; existing servers preserved). Agents should prefer its
twenty-six validated tools—including bounded find/get, locked create/update/link,
reflection category/question CRUD, and branch-first parallel tracking with serialized promotion
operations—over hand-editing `.prd_plugin/state` JSON. See the README's
"MCP State Tools" section.

### Where installed scripts live

Downstream installs place copied helpers under **`.prd_plugin/scripts/`** (not a
repo-root `scripts/` directory, which `prd-install` never creates). Skills that
mention `scripts/<name>.py` are written from the hub's layout and are guarded
("if available") — most of the validators they reference (`gap_audit.py`,
`release_check.py`, `local_workflow_check.py`, `version_advice.py`,
`prd_doctor.py`, …) are **hub-only or optional by design and are intentionally
not installed downstream**. `state_consistency_check.py` is a required default
runtime because `prd_gate.py` must not skip branch/state validation. Run the others from the PRD
Plugin hub/plugin bundle. Any automation that must run an installed helper in a
downstream repo should call it at `.prd_plugin/scripts/<name>.py` and tolerate
its absence.

## Config Section Matrix

A check means the config section is written or merged into
`.prd_plugin/config.json` when the option is active.

| Section | codex | opencode | claude | opencode-skill-inject |
| --- | --- | --- | --- | --- |
| `skills.{required_skills, repo_local_path, install_repo_local_by_default}` | yes | | | |
| `skills.{opencode_target, install_opencode_by_default}` | | yes | | |
| `skills.{claude_target, install_claude_by_default}` | | | yes | |
| `opencode.json` plugin entry `prd-plugin@^<version>` | | yes | | |
| `opencode.json` plugin entry `opencode-agent-skills@0.7.0` | | | | yes |
| `opencode.json` permission `skill.prd-plugin=allow` | | | | yes |

Claude Code requires plugin config injection for the default path:
`.claude/settings.json` carries the repo-scoped marketplace and
`enabledPlugins` entry for `prd-plugin@prd-plugin`. The
`skills.{claude_target, install_claude_by_default}` config remains the documented
target for the explicit repo-local `.claude/skills/` escape hatch.

### Claude Code hook interpreter

The generated `.claude/settings.json` wires the routing nudge, skill logger,
autonomous Stop guard, session report, drift check, and configurable reflection
hook. They run as
`<python> .claude/hooks/<name>.py`. The skeleton ships `python`, but many
non-Windows hosts have only `python3` on `PATH` (or `python` is Python 2), where
a hardcoded `python` would make every hook silently fail to launch. So at
install time `prd_install.py` detects a runnable Python-3 interpreter — it
prefers `python3`, falls back to `python`, and verifies the candidate actually
runs Python 3 (skipping a broken Windows `python3` App Execution Alias) — and
rewrites the leading interpreter token in each hook command to it. The chosen
token is reported as `claude_settings.interpreter` in the install output.

The installer only rewrites a `.claude/settings.json` it wrote this run (a fresh
copy, or one overwritten with `--force`); a pre-existing file you own is left
untouched. To refresh the interpreter in an existing install, re-run with
`--force`. The hub's own `.claude/settings.json` is not generated and stays on
`python` (correct on the Windows hub host).

## Combination Examples

| Combination | Installs |
| --- | --- |
| `--codex` | Codex skills + codex scripts |
| `--opencode` | opencode skills + opencode scripts + opencode.json plugin entry |
| `--claude` | Claude Code plugin enablement + hooks/commands + runtime scripts |
| `--claude --claude-skills` | Claude Code plugin enablement plus repo-local `.claude/skills/` copy |
| `--codex --opencode --claude` | Codex/opencode skill copies + Claude plugin enablement + all default scripts + opencode.json plugin entry |
| `--opencode --opencode-skill-inject` | opencode skills + opencode.json with prd-plugin and opencode-agent-skills plugin entries + permission |
| `--codex --opencode --claude --opencode-skill-inject` | Everything: Codex/opencode skill copies, Claude plugin enablement, all default scripts, and all opencode.json entries |

By default (no host flags), `codex`, `opencode`, and `claude` are all enabled.

## Managed downstream `.gitignore`

Every install creates or refreshes a bounded block between
`# BEGIN PRD Plugin managed ignores` and
`# END PRD Plugin managed ignores` in the downstream repo's root `.gitignore`.
The installer creates the file when absent, preserves all project-owned content
outside the block, and makes repeated installs idempotent. A malformed marker
pair or non-UTF-8 file is reported and left unchanged rather than clobbered.

The managed block ignores per-clone `.prd_plugin/local/` state, request
transport (`inbox/`, `outbox/`, and `mailboxes/`), generated
`request-report/` output, local command adapters, secret/npm-local files,
Python caches, logs, temporary files, and OS metadata. It deliberately does
not ignore committed state, tracking branches, drift exports, evidence,
`.mcp.json`, or `.codex/environments/environment.toml`.

## CLI Usage

```bash
# Codex only
npx prd-install . --codex

# opencode only
npx prd-install . --opencode

# Claude Code only (plugin-primary)
npx prd-install . --claude

# Claude Code only, with repo-local project skills
npx prd-install . --claude --claude-skills

# All hosts (also the default when no host flags are passed)
npx prd-install . --codex --opencode --claude

# Everything, with skill injection
npx prd-install . --codex --opencode --claude --opencode-skill-inject

# Disable opencode skill injection even with opencode enabled
npx prd-install . --opencode --no-opencode-skill-inject

# Skip Claude Code support
npx prd-install . --codex --opencode --no-claude

# Include optional scripts
npx prd-install . --codex --opencode --claude --include-optional-scripts
```

The `--target-agent` flag is deprecated. Use `--codex`, `--opencode`, and/or
`--claude` instead. The installer will still accept `--target-agent` for
backward compatibility but it predates Claude Code support and never enables the
`claude` host.

## Using PRD Plugin as a Claude Code plugin

Instead of (or in addition to) the repo-local install, the hub repo is a
self-contained Claude Code plugin marketplace:

```text
/plugin marketplace add markusuk1/prd-plugin
/plugin install prd-plugin@prd-plugin
```

Claude Code then auto-loads the plugin's `skills/` directory; no per-repo
install step is required for the plugin path.