---
name: project-prd-plugin-setup
description: Use when installing, onboarding, updating, auditing, or reconfiguring PRD Plugin in a repository. Uses the installer and unified configuration authority; never guesses versions, invents config keys, or hand-builds configuration JSON.
---

# Project PRD Plugin Setup

Use this skill for first install, host enablement, update checks, configuration
audits, latency profiles, hook toggles, and optional integration activation.

## Authority

- The installer owns delivery and stamps `plugin.installed_version`; never ask
  the operator to choose that marker and never infer it from memory.
- `prd_config.py` and the equivalent `prd_config_*` MCP tools own configuration
  discovery and atomic writes. Do not assemble `.prd_plugin/config.json` by
  hand.
- Run the deterministic `install.update-check` workflow when it is enabled. It
  audits config, canonical state, and the gate without requiring a remote.
- Installer host flags own Codex, OpenCode, and Claude Code discovery:
  `--codex`, `--opencode`, and `--claude`.
  A repository may enable any combination; do not reduce the choice to a single
  synthetic host key.

## Install Or Refresh

Downstream:

```bash
npm install --save-dev prd-plugin
npx prd-install . --codex --opencode --claude --force
```

Hub development uses `python scripts/prd_install.py <repo> --dry-run` before a
real install. In either case, the installer performs additive migration,
preserves project-owned config choices, installs the allowed scripts and
skills, stamps `plugin.installed_version`, and maintains only the marked
managed PRD Plugin block in the root `.gitignore`.

`--force` is the safe refresh flag and preserves protected project state,
IDs, local data, and config. Never add `--yes` to a normal install or update:
it requests a destructive reset to skeleton defaults. The CLI refuses that
reset in non-interactive agent sessions and requires an interactive operator to
type `RESET PRD STATE` exactly when protected files exist.

## Unified Configuration

Resolve the helper under `.prd_plugin/scripts/prd_config.py` downstream or
`scripts/prd_config.py` in the hub. Start with:

```bash
python <helper> --repo-root . --json inventory
python <helper> --repo-root . --json audit
```

Use `describe` or `effective` before changing an unfamiliar setting. Mutate
with `set`, `enable`, `disable`, or the MCP equivalents `prd_config_get`,
`prd_config_set`, and `prd_config_profile`. Writes are validated, atomic, and
dependency-aware.

Built-in profiles are `lean`, `balanced`, and `thorough`. Preview with
`profile apply <name> --dry-run`; apply only the selected profile. Profiles
tune local latency but do not silently enable external integrations.

Important independently-toggleable surfaces include:

- master and per-capability host hooks;
- deterministic workflows and judgment fallback;
- `verification.test_scope`;
- `reporting.delegation` and `integrations.substrate`;
- `reflection.enabled`, `reflection.on_stop`, categories, and question limits;
- tracking branches, drift monitoring, the ingest manual, and
  `fork.version_check`.

Reflection question CRUD remains with `prd_reflections.py` or the
`prd_reflection_list`, `prd_reflection_create`, `prd_reflection_update`, and
`prd_reflection_delete` MCP tools because they own duplicate-safe `RFQ-*`
allocation.

## Repository Services

Every installed repository owns `.prd_plugin/services.json`. It declares the
services the repository consumes and provides, including capability, contract
version, required/optional status, visibility, and fallback. Treat it as the
machine-readable integration boundary; do not infer service relationships from
prose or duplicate them in config.

Audit with `prd_service_audit`; inspect with `prd_service_list` and
`prd_service_get`; mutate only through `prd_service_upsert` and
`prd_service_remove` (or `prd_services.py`). The installer preserves the file
on safe refresh. When `integrations.substrate` changes through
`prd_config.py`, its known consumer declaration is reconciled automatically.
Run `prd_substrate_catalog` with `audit` when the repository consumes
AI-Collab so declared capabilities remain compatible with the shipped runtime.

## Procedure

1. Detect the existing package, manifests, host directories, config, and
   installed scripts. Do not ask for facts the repository already answers.
2. Install or refresh only when files are missing or an update was requested.
3. Run config `inventory`, `audit`, and `effective` for the affected controls.
4. Audit `.prd_plugin/services.json` and the Substrate capability catalog when
   AI-Collab is declared.
5. Preview the exact setting/profile diff.
6. Apply the requested or safely inferred reversible configuration. Respect the
   autonomy tier for choices that genuinely require operator preference.
7. Run `install.update-check`, or the config/state/gate equivalents if workflows
   are disabled.
8. Report installed hosts, `plugin.installed_version`, effective profile/hooks,
   declared consumed/provided services, optional integrations, and any
   conservative fallback.

## Hard Rules

- Never persist secrets or credentials in tracked config.
- Never replace the whole config to change one setting.
- Never invent a key, version, host target, or skill count.
- Never install hub-only scripts downstream; obey
  `templates/script-install-scope.json`.
- Never use `--yes` for a routine refresh; use `--force` alone.
- Never treat an absent remote as an installation or verification blocker.
- Preserve project-owned `.gitignore` rules; only the managed PRD Plugin block
  belongs to the installer.

## Staleness Coverage

Apply `.prd_plugin/method/staleness-rules.md`. Use the installer/version marker
and `install.update-check`; do not manufacture an `HLT-*` merely because config
has not changed recently.