prd-plugin

PRD Plugin is a method delivered as a plugin: it installs a disciplined product-development workflow (idea → PRD → architecture → plan → implementation → evidence) into any repo that a host AI coding agent works in, and enforces that discipline with stable IDs, a JSON state store, cross-host hooks, and a verification gate. This document is chunked by heading for shared-knowledge indexing — each section is written to be read correctly on its own, with no surrounding context.

1. What this repo is

PRD Plugin (prd-plugin on npm) is a method-as-a-plugin for host AI coding agents — primarily Claude Code, with parity support for OpenAI Codex and opencode. It gives an agent a repeatable way to turn an idea into a requirement, a requirement into architecture and an implementation plan, and code into verified, evidence-backed work — with every artifact carrying a stable ID so the chain is traceable and no record can be silently invented. It solves the problem that agents drift, hallucinate "done", skip verification, and lose the thread across sessions and compactions; the plugin replaces recollection with on-disk state, skills the agent must consult, and hooks that run checks it cannot forget.

This repository is the hub (the source of truth), located at D:\Projects\prd-plugin / github.com/markusuk1/prd-plugin. It authors the skills, templates, scripts, MCP server, and hooks, and publishes them to npm. Downstream repos consume the plugin by running npx prd-install, which lays down a .prd_plugin/ tree (method docs, state store, ID registry, hooks, config) plus host-specific skill mirrors. The hub is edited with the same method it ships (it dogfoods itself: its own work is tracked as REQ-*/TRK-*/EV-* records under .prd_plugin/state/).

What it is not. It is not a library or framework you import at runtime — nothing in a downstream app links against it. It is not an orchestrator: it does not spawn or manage subagents; the host agent runs the method itself and may manage its own parallelism. It is not project-specific — the skills and schema are domain-agnostic. And it is not a replacement for the host agent's own tools; it is a governance and memory layer on top of whatever agent is driving.

2. Capability map

Everything PRD Plugin provides, and where it lives in this repo. Counts are as of version 0.15.0.

3. Interfaces — how to call it

PRD Plugin is driven five ways: the install CLI, MCP tools, host slash commands, the Python scripts directly, and a UTCP tool surface. The UTCP manual (utcp.json, generated by scripts/prd_tools.py --utcp-manual) describes a set of read-only observe/recall tools (status, tracking, decisions, evidence, wiki, drift, gate, reporting) as cli call templates that run this repo's own scripts. A UTCP host such as the AI-Collab hub mounts the manual with a cli provider and bridges it to MCP — so the tools are defined and owned here, not re-implemented downstream. Writes are deliberately excluded: they stay on the validated MCP/script path (branch-first parallel tracking, serialized canonical promotion, and the consent floor).

3.1 Install CLI

The npm package's bin runs the installer. Invoked in a target repo:

npx prd-install [target-dir]        # first-time install into a repo (default: cwd)
npx prd-install . --force           # refresh plugin files, PRESERVE .prd_plugin/state + config.json
npx prd-install . --force --yes     # DESTRUCTIVE reset request; interactive confirmation required
npx prd-install . --host codex      # choose host wiring (claude | codex | opencode)

--force is the update path: it re-lays hooks, skills, scripts, and templates but never overwrites .prd_plugin/state/, .prd_plugin/ids/, .prd_plugin/local/, or .prd_plugin/config.json (the state-protected set), and never overwrites a downstream README.md. The report labels each file copied, skipped, or preserved.

Every install also creates or refreshes the lines between # BEGIN PRD Plugin managed ignores and # END PRD Plugin managed ignores in the repo-root .gitignore. It preserves surrounding lines and line-ending style; malformed markers or a non-UTF-8 file are reported and left untouched. The block ignores runtime/transport state, reports, local command adapters, secrets, caches, logs, temporary files, and OS metadata while leaving committed state, tracking branches, drift exports, evidence, MCP configuration, and the shipped Codex environment trackable.

3.2 MCP tools

Exposed by mcp/server.cjs over the Model Context Protocol. Read tools are side-effect-free; write tools allocate IDs from the registry and append to the state store under the owner-token lock. The thirty-five tools:

3.3 Slash commands

Thin host-command wrappers over the scripts (files under commands/):

3.4 Scripts

The Python scripts under scripts/ are the real implementation; commands, hooks, and MCP tools all call into them. Stdlib-only, cross-platform.

3.5 Reflection CRUD example

The CLI and MCP CRUD tools operate on the same .prd_plugin/config.json#reflection store and use the same local lock as canonical state writes. They require local repository write access but no network authentication. Invalid IDs, duplicate normalized text/category names, unknown targets, and non-empty category deletion without an explicit cascade return an error without partially editing the bank. Real read output at commit c5bab8c:

$ python scripts/prd_reflections.py list --json --category harness_friction
{
  "enabled": false,
  "on_stop": true,
  "max_questions_per_stop": 5,
  "categories": [
    {
      "id": "harness_friction",
      "name": "Harness friction",
      "enabled": true,
      "question_count": 2
    }
  ],
  "questions": [
    {
      "id": "RFQ-004",
      "text": "What harness friction points made this work more difficult?",
      "enabled": true,
      "category_id": "harness_friction",
      "category_name": "Harness friction",
      "effective_enabled": false
    },
    {
      "id": "RFQ-005",
      "text": "What up to three changes would most improve friction in the harness?",
      "enabled": true,
      "category_id": "harness_friction",
      "category_name": "Harness friction",
      "effective_enabled": false
    }
  ]
}

3.6 Worked example

Running the status script in this repo prints the current state summary. Real output at commit f7d182d:

$ python scripts/prd_status.py
# PRD Plugin Status

Autonomy: `autonomous`

## Requests
- accepted: 1
- deferred: 1
- implemented: 54
- proposed: 3
- rejected: 1

## Active tracking (1)
- TRK-063

## Open health findings (1)
- HLT-001

## Stale items
- 1

## Skills used this repo
- project-decision-policy: 1
- project-request-intake: 1
- project-test-driven-implementation: 1
- project-verification-before-completion: 1

Architecture — how the pieces fit

PRD Plugin has four structural layers: the skill mirrors, the per-repo state store, the MCP server, and the host hooks — all authored once in the hub and projected outward by the installer. This section reads on its own; it describes how a change made in the hub reaches a downstream agent.

Skill delivery: one canonical set, seven mirrors

The 29 skills are authored in skills/<name>/SKILL.md. Because each host discovers skills from a different directory, the canonical set is copied byte-identically into per-host mirrors: hub-level .agents/skills, .opencode/skill, and .claude/skills, plus three skeleton copies under templates/repo-skeleton/ that ship downstream. Parity tests assert the mirrors are identical. Two skills (project-verification-before-completion, project-prd-plugin-setup) have adapted skeleton variants that strip hub-only scripts — a blanket copy would clobber them, so those two are excluded from the byte-identical sweep.

State store: branch-first parallel writes, serialized promotion

Every durable record lives in .prd_plugin/state/*.json (requests.json, tracking.json, decisions.json, evidence, health.json, changelog). IDs are allocated only from .prd_plugin/ids/registry.json, which holds a next counter per type — this is what makes "no inventing records" enforceable: a referenced ID that was never allocated is a gate failure. Before parallel fan-out, the lead pre-allocates one DBR tracking branch per worker and commits the distinct files under .prd_plugin/state/tracking-branches/. It launches workers with PRD_WORKER_SESSION=1, PRD_TRACKING_BRANCH_ID, and PRD_TRACKING_BRANCH_OWNER. When tracking.branching.require_for_parallel_agents is true, the MCP dispatcher rejects every canonical state/registry write and any branch assignment mismatch. Workers update only their assigned files, allocate no IDs, and leave non-TRK closeout requests as notes for the lead. After worktree merges, the lead promotes branches serially; canonical state and registry allocation therefore remain single-authority and duplicate-safe.

Hooks: shared scripts, thin per-host wiring

Hook logic is host-neutral and lives once in .prd_plugin/hooks/ (byte-identical to .claude/hooks/). Each host wires the same scripts differently: Claude Code via .claude/settings.json; Codex via .codex/hooks.json across all five events (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop) with the same payload shape and exit-2 block semantics as Claude; opencode via a JavaScript plugin (.opencode/plugins/prd-hooks.js) mapping session.idle to Stop-like behavior and tool.execute.before to PreToolUse. opencode's session.idle is non-blocking, so opencode alone cannot enforce run-until-done; the gate and CI are the portable backstop.

The gate: composition, not reimplementation

prd_gate.py composes the existing validators (state_consistency_check, release_check) and adds checks seeded by real past failures (duplicate IDs, version markers out of sync including already-published-on-npm, implemented-without-graduated_to, stranded outbox, autonomy-tier violations). It reads the config policy flags that would otherwise be dormant, so the gate is where advisory policy becomes enforced. state_consistency_check.py is installed by default beside the downstream gate; a missing validator is itself an error rather than a silent skip.

Recipes — common tasks end to end

Copy-pasteable paths for the things operators and agents do most. Each recipe stands alone.

Install PRD Plugin into a repo

cd my-repo
npx prd-install .            # also creates/merges the managed root .gitignore block
python .prd_plugin/scripts/prd_status.py   # confirm the state store is live

Update the plugin without losing state

npm update prd-plugin
npx prd-install . --force    # refreshes hooks/skills/scripts/templates; preserves state + config

Turn on drift detection with an on-Stop check

python scripts/prd_config.py set drift.monitoring.enabled true
python scripts/prd_config.py set drift.monitoring.on_stop true
python scripts/drift_monitor.py            # run it now

Turn on Stop reflections and inspect the question bank

python scripts/prd_config.py set reflection.enabled true
python scripts/prd_reflections.py list --json
python scripts/prd_reflections.py update question RFQ-005 --disabled

The first eligible Stop asks the active questions and writes only a hashed local session marker. The immediately following Stop consumes that marker and allows completion, preventing an infinite reflection loop.

Enable the AI-Collab Substrate adapter in observe mode

python .prd_plugin/scripts/prd_config.py set integrations.substrate.enabled true
python .prd_plugin/scripts/prd_config.py set integrations.substrate.mode observe
python .prd_plugin/scripts/prd_substrate.py handshake --repo-root .

Use coordinate only with the additional capability names the runtime needs. Substrate remains a derived mirror; writes still use PRD MCP.

Check for a newer plugin version

python scripts/prd_version_check.py        # npm-vs-installed, cached, fail-open

Plan and run a deterministic workflow

python scripts/prd_workflows.py --repo-root . audit --json
python scripts/prd_workflows.py --repo-root . plan engineering.verify --inputs '{}'
python scripts/prd_workflows.py --repo-root . run engineering.verify --inputs '{}'

Use the equivalent prd_workflow_* MCP tools from an agent. If a run reaches waiting_judgment, AI-Collab receives only the declared, source-hashed request and result schema; deterministic validation must accept the result before the run can continue.

Build or query the LLM wiki

python scripts/prd_wiki_backfill.py        # build/backfill articles
python scripts/prd_wiki_backfill.py --drift --format json   # detect stale/unstamped/missing articles

File a request (bug/change/feature)

Invoke the project-request-intake skill (or the prd_file_request MCP tool). It allocates the next REQ-* from the registry and appends to requests.json with severity, risk, and provenance — never a hand-typed ID.

4. Operations — run, deploy, configure

PRD Plugin runs as files in a repo, not a service; "operating" it means installing/updating it, setting config knobs, and running its release ceremony in the hub. There is nothing to stand up on a server.

Stand it up

One command in a target repo: npx prd-install .. Update with npm update prd-plugin && npx prd-install . --force (state- and config-preserving). Never add --yes to an update: it requests a destructive reset, is refused in non-interactive sessions, and requires the exact interactive phrase RESET PRD STATE. The hub itself needs Python 3 (stdlib only) and Node for the MCP server and installer.

Configuration knobs and defaults

Managed by scripts/prd_config.py and stored in .prd_plugin/config.json. The unified catalog covers every shipped persistent setting and reports type, owner, mutability, activation, dependencies, and latency. inventory also reports environment, installer, host-wiring, specialized-CRUD, and invocation-only controls. Validated writes are atomic and formatting-preserving; lean, balanced, and thorough profiles can be previewed before apply and never auto-enable external integrations. Core runtime hook controls include:

python scripts/prd_config.py inventory --json and list --json are machine contracts. Agents use the equivalent prd_config_list, prd_config_get, prd_config_set, and prd_config_profile MCP tools. Each host event launches one dispatcher process, which checks these switches before importing disabled behavior.

Autonomy tiers

Three tiers set by automation.autonomy_level (change via python scripts/prd_gate.py set-autonomy <level>): guided and key_decision require explicit consent before push/merge/publish; autonomous makes the tier itself the standing consent — the agent ships the work end-to-end (commit, push, merge to the work's own main, tag, publish) provided the gate is green, and never ships red. What never unlocks in any tier: committing/exposing secrets, force-push or history destruction, editing an unrelated repo, or irreversible external spend. Local commits on a work branch never need consent in any tier.

Release ceremony (hub only)

Cutting a version bumps every version marker (the marker set plus package.json and index.js), adds entries to the releases ledgers, graduates the driving REQ-* to implemented with a graduated_to, appends CHG-*/EV-*, and updates the registry counters — then runs the full gate green before merge/tag/publish to npm. In this hub the remote v* tag push is the publication action: .github/workflows/npm-publish.yml checks out the tag, runs tests and package verification, and publishes to npm. Agents must not run npm publish locally or treat missing local npm credentials as a release blocker. After a successful tag push, treat the release as published unless the owner reports otherwise. Only then inspect or rerun the GitHub Actions Publish to npm workflow to distinguish workflow failure from registry lag.

5. Design decisions & re-open triggers

The load-bearing decisions behind PRD Plugin's shape, and what would make each worth revisiting. These are the choices a newcomer most often questions.

6. Verification — how claims are proven

Every claim in this manual is backed by a test, a script, or a reproducible command. PRD Plugin holds itself to the same grounding rule it ships: verify before claiming done, cite real output.

Test suite

The hub carries a stdlib unittest suite. Release-wide verification for version 0.15.0 runs the complete discovered suite:

$ python -m unittest discover -s tests
...
OK

Included are data-driven parity tests that assert the seven skill mirrors are byte-identical (except the two adapted skeleton variants), Windows-console-safety tests that reject non-ASCII in Python source (a real past crash class), and installer tests that assert --force preserves state/config while refreshing plugin files. The installer suite also invokes git check-ignore --no-index to prove generated/runtime paths are ignored while committed PRD Plugin truth stays trackable.

The five gates

Before any release the following must be green, and the same checks compose into prd_gate.py for commit-time enforcement:

python -m unittest discover -s tests                 # unit + parity + safety
python scripts/state_consistency_check.py --repo-root .   # cross-record integrity -> ok
python scripts/release_check.py                      # version markers / ledger
python scripts/gap_audit.py --target-version 0.15.0  # coverage gaps
python scripts/workflow_chml_audit.py --repo-root . --format json  # C/H/M/L -> 0
python scripts/prd_gate.py                           # composite gate (reads policy flags)

Drift detection

The drift monitor re-runs the validators and flags when documentation, state, the wiki, or this ingest manual have fallen behind the code. Wiki drift is measured by commit-stamp staleness; ingest-manual drift is source-path-aware — it flags precisely when a file the manual cites has changed since the manual's commit stamp (silent for unrelated churn), and immediately if the manual becomes unstamped or non-conformant. A repo that consumes an external fork can also enable a fork-version check that polls a configured source (a static manifest or a node /v1/status) and surfaces a newer fork version on Stop — inert unless configured. It writes snapshots and a compact drift-event feed and can run a cheap subset on every Stop.

Evidence records

Completion claims in this repo are backed by EV-* records in the state store, linked from the REQ-*/TRK-* that drove the work. A claim of "done" with no evidence record and no reproduction command does not pass the method — and this manual follows that rule: its counts (29 skills, 35 MCP tools, 13 commands, version 0.15.0) were each captured by running the command shown, not recalled.