PRD Plugin

PRD Plugin is a project-agnostic plugin for turning ideas into traceable project artifacts:

• brainstorm records
• PRD requirements
• architecture decisions and components
• implementation plans
• acceptance criteria
• evidence records
• agent memory and tracking state
• request, issue, bug, and compatibility intake records
• project health checks
• cross-artifact "fold it in" integration workflow
• end-to-end planning lifecycle workflow
• traceability reviews

It is not Gandalf-specific and not Auto-Harness-specific. Those projects can use it, but the method is intended to work in any repository.

Quick Install

In the downstream repo where you want to use PRD Plugin:

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

The five install options are --codex, --opencode, --claude, --vectorsmith, and --opencode-skill-inject. See the Install Options section and docs/INSTALL-MATRIX.md for the full matrix of what each option installs.

PRD Plugin can also be used as a Claude Code plugin without a per-repo install — the hub repo is a self-contained marketplace:

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

Repository Model

The plugin itself lives outside target projects.

Each target project keeps its own method state in:

.prd_plugin/

That folder is intended to be committed with the target repo unless the project chooses otherwise.

Recommended target-repo layout:

.agents/
  skills/
    project-memory/
      SKILL.md
    project-session-close/
      SKILL.md
    ...

.claude/
  skills/
    project-memory/
      SKILL.md
    ...

.prd_plugin/
  config.json
  METHOD.md
  ID-SCHEME.md
  ids/
    registry.json
  state/
    artifacts/
      prd/
      architecture/
      implementation_plan/
    project.json
    memory.json
    decisions.json
    changelog.json
    tracking.json
    requests.json
    health.json
    sessions/
      shared/
        promoted-session-summaries.jsonl
  local/
    sessions/
  templates/
    brainstorm.md
    prd.json
    architecture.json
    implementation-plan.json
    human-exports/
      prd.md
      architecture.md
      implementation-plan.md
    decision-record.md
    evidence.md

docs/
  brainstorm/
  exports/
  decisions/
  evidence/
  traceability/

Core Flow

Idea
  -> brainstorm IDs
  -> PRD requirements
  -> architecture decisions/components
  -> implementation plan tasks
  -> evidence
  -> promoted agent memory
  -> request intake, when external agents propose changes
  -> health check
  -> traceability review

The goal is consistent thinking and traceability across repos without forcing a specific product architecture.

Superpowers Method Alignment

PRD Plugin adopts selected Superpowers execution disciplines as PRD-native skills rather than competing with them. The adapted skills preserve the stronger Superpowers method rules for implementation planning, test-first development, root-cause debugging, and verification, while adding PRD Plugin's durable ID, evidence, request, health, changelog, and traceability requirements.

Imported/adapted methods:

• project-implementation-plan
• project-test-driven-implementation
• project-systematic-debugging
• project-verification-before-completion

Superpowers controls execution discipline; PRD Plugin controls durable IDs and project truth. BR-*, PRD-*, ARCH-*, IMP-*, EV-*, REQ-*, MSG-*, HLT-*, MEM-*, OBS-*, TRK-*, CHG-*, and DEC-* remain non-negotiable. See THIRD_PARTY_NOTICES.md for attribution.

Planning Lifecycle Workflow

Use project-planning-lifecycle when brainstorms, early notes, accepted requests, or rough feature ideas need to become a complete planning chain:

brainstorm -> PRD -> architecture -> implementation plan -> traceability sync/review

The workflow prevents stale jumps from brainstorms straight into implementation plans. It requires PRD requirements to cite BR-* or accepted REQ-* sources, architecture to cite PRD-* or DEC-* sources, implementation tasks to cite both PRD-* and ARCH-* sources, and open or stale BR-Q-*, BR-RISK-*, TRK-*, REQ-*, and HLT-* items to be carried forward or recorded as explicit follow-up.

Canonical Planning Artifacts

JSON/JSONL is canonical for planning artifacts. Generate Markdown only on explicit human request.

PRDs, architecture docs, and implementation plans live under .prd_plugin/state/artifacts/{artifact_type}/{artifact_id}.json as the single source of truth. Those JSON artifacts record stable IDs, short summaries, source links, traceability, open questions, stale follow-ups, and evidence expectations. Markdown exports may be created under docs/exports/ for human review, but exports are snapshots and must not be edited as project truth.

Agent Memory Model

The plugin uses JSON as the canonical machine-readable format for agent-facing project state. Markdown remains useful for optional human exports and document branches, but durable agent memory and planning truth should live in structured files that are easy to validate and selectively load.

Committed state belongs under .prd_plugin/state/ by default. Raw session memory belongs under .prd_plugin/local/ and should be ignored by git. Agents may write rich local session logs, but only concise, source-backed, non-sensitive summaries should be promoted into committed project memory.

Configuration

Projects may customize method paths and policy in .prd_plugin/config.json. Agents and scripts should read this file before assuming default state, request, health, registry, or local session paths.

Script Install-Scope

PRD Plugin scripts are not blanket-installed into repositories that use the plugin. The authoritative script install-scope policy is templates/script-install-scope.json, and installed skeletons carry the same policy at .prd_plugin/templates/script-install-scope.json.

Downstream repos should not receive a copied scripts/ directory by default. If a repo explicitly opts into local helper scripts, install only scripts marked downstream_runtime or downstream_optional. Keep hub_runtime and plugin_development scripts in the PRD Plugin hub/development repo or plugin bundle. In particular, do not copy release_check.py, local_workflow_check.py, gap_audit.py, request_import.py, or request_mailbox.py into ordinary downstream repos.

Repo-Local Skill Install

Host agents discover repo-local skills from their own discovery paths: Codex reads .agents/skills/<skill-name>/SKILL.md; opencode reads .opencode/skill/<skill-name>/SKILL.md; Claude Code reads .claude/skills/<skill-name>/SKILL.md. None of them read .prd_plugin/. Repos that adopt PRD Plugin should carry the PRD Plugin workflow skills in .agents/skills/, .opencode/skill/, and .claude/skills/ so tracking, memory, changelog, request intake, session close, and traceability workflows are available to the host agent without relying on a separate global plugin install.

New repo skeleton installs include downstream runtime skills in .agents/skills/ by default. Existing repos can install or refresh the repo-local skill copy from the PRD Plugin hub/plugin bundle:

python scripts/prd_install.py D:/Projects/some-repo --codex --opencode

This copies the repo skeleton (.prd_plugin/, .codex-plugin/, .opencode/, .claude-plugin/, .codex/hooks.json), installs repo-local skills, and installs allowed downstream runtime scripts. It skips existing files unless --force is passed, and it refuses to install into the PRD Plugin hub repo itself. With --force, existing .prd_plugin/state/ files are preserved unless you also pass --yes. Plugin development and hub-only scripts are never copied.

Installed helper scripts live under .prd_plugin/scripts/ in the downstream repo — prd-install does not create a repo-root scripts/ directory. Skills reference scripts/<name>.py from the hub's layout and guard each call with "if available"; most referenced validators (gap_audit.py, release_check.py, local_workflow_check.py, version_advice.py, prd_doctor.py, state_consistency_check.py, …) are hub-only or optional by design and are not installed downstream. The Codex Stop hook (.codex/hooks.json) is guarded so it no-ops when the optional archive_automation_session.py helper is absent, and it targets .prd_plugin/scripts/ downstream.

See the Install Options section for the five explicit flags and the full matrix in docs/INSTALL-MATRIX.md.

npm install

PRD Plugin is published as an npm package. In a downstream repo:

npm install --save-dev prd-plugin

Then install or refresh the local PRD Plugin payload:

npx prd-install D:/Projects/some-repo --codex --opencode

The npm package ships the same skeleton, skills, templates, and scripts as the git distribution. When installed from npm, prd-install writes an npm-based opencode.json plugin spec (prd-plugin@^<version>) instead of a git URL.

To preview what would be installed:

npx prd-install D:/Projects/some-repo --dry-run --codex --opencode

Install Options

prd-install has five explicit flags. Each flag controls which skills, scripts, and config sections are installed.

| Flag | Purpose | Default | | --- | --- | --- | | --codex / --no-codex | Install Codex skill discovery under .agents/skills/ | on | | --opencode / --no-opencode | Install opencode skill discovery under .opencode/skill/ and write opencode.json | on | | --claude / --no-claude | Install Claude Code skill discovery under .claude/skills/ (no config injection needed) | on | | --vectorsmith / --no-vectorsmith | Install the optional VectorSmith evidence bridge (prd_vectorsmith.py and project-vectorsmith-evidence skill) | off | | --opencode-skill-inject / --no-opencode-skill-inject | Add the opencode-agent-skills plugin and the prd-plugin skill permission to opencode.json | on when --opencode is on |

Common combinations:

# Codex only
npx prd-install . --codex --no-opencode --no-claude

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

# opencode with auto-injection
npx prd-install . --codex --opencode --opencode-skill-inject

# Full install with all hosts and add-ons
npx prd-install . --codex --opencode --claude --vectorsmith --opencode-skill-inject

# Disable auto-injection
npx prd-install . --opencode --no-opencode-skill-inject

When the same flag exists as both --X and --no-X, they are mutually exclusive. Combining --codex, --opencode, and --claude is the default for new installs; --no-codex, --no-opencode, or --no-claude lets you install for a subset of host agents only.

The full skill, script, and config matrix is documented in docs/INSTALL-MATRIX.md.

The deprecated --target-agent codex|opencode|both flag is still accepted and maps to the new options. It will be removed in a future release.

Optional helpers

To also install optional helpers such as prd_doctor.py or message_check.py:

npx prd-install . --codex --opencode --include-optional-scripts

or from npm:

npx prd-install D:/Projects/some-repo --include-optional-scripts --target-agent both

The .agents/skills copy is agent capability. The .prd_plugin/ directory is project state, templates, and method configuration. Both are needed for a self-contained downstream repo. PRD Plugin hub/development workflows, such as changing the plugin package itself, stay in the plugin hub/bundle and are not installed into ordinary downstream .agents/skills.

Downstream installs include project-local-integration for local requests such as "fold this into project truth." That workflow updates the current repo's PRD Plugin artifacts, memory, traceability, health, evidence, changelog, and request state without pulling in plugin release or version-bump behavior.

When a downstream repo has explicitly installed optional helpers, agents can run a read-only setup and policy diagnostic before changing project truth:

python scripts/prd_doctor.py --repo-root .

The doctor checks PRD Plugin config, request-state parseability, stale or privacy-sensitive requests, and copied hub/development scripts that violate the script install-scope policy.

Fold It In Workflow

The project-fold-it-in skill is the default workflow for cross-cutting plugin changes. Use it when a change needs to be integrated across method docs, skills, templates, config, state, scripts, workflows, validation, release hygiene, and versioning rather than applied as an isolated edit.

In downstream repos, use project-local-integration instead. It handles current-repo project-truth integration and explicitly excludes PRD Plugin package release mechanics.

When the user asks to fold a change into the plugin workflow, the workflow creates or checks an active goal before implementation, keeps the visible progress plan aligned with it, and reports goal status at closeout.

Project Health

Project health checks summarize whether the planning and memory graph is safe to continue from. Health findings use HLT-* IDs and are stored in .prd_plugin/state/health.json.

Health checks do not replace traceability reviews. They are compact operational snapshots for agents: stale tracking records, orphan requirements, missing evidence, weak memory provenance, unpromoted document branches, and other attention points. Every PRD Plugin skill has an explicit staleness responsibility so stale requests, tracking records, health findings, request transport, automation locks, and scheduler state are either resolved, refreshed with evidence, or left as visible follow-up work.

Request Intake

Outside agents should not directly change project truth for speculative ideas, bug reports, or compatibility concerns. They should append a REQ-* record to .prd_plugin/state/requests.json with their proposed change or issue, rationale, affected IDs, provenance, severity, and risk. Before adding a new REQ-*, search existing requests and thread.messages for the same issue. If a bug still reproduces on a later version, append a MSG-* update to the original request thread and update affected-version metadata rather than opening a new request.

Request intake uses a hub-and-spoke privacy model. This prd-plugin repo is the upstream hub for plugin-level requests and discussions. Repos using the plugin should keep only their own local requests, issues, and messages unless they explicitly submit a request upstream.

Accepted requests can graduate into TRK-*, DBR-*, PRD-*, CHG-*, or other normal project artifacts. Rejected requests stay recorded with a decision and rationale.

Requests can be discussed without changing project truth by adding MSG-* records to the request's thread.messages array. Use in_review while the request is being shaped and needs_info when the requester must reply before a decision can be made. Only messages marked for upstream visibility should be included in sanitized upstream submissions.

The request-check automation is intended to validate and triage requests autonomously by risk band, not stop at a read-only summary. Low- or medium-risk bug submissions with clear reproduction steps and a bounded fix must continue into the bug investigation workflow, failing test, fix, verification, request-state update, and commit unless the report is missing required detail, unsafe, unbounded, or explicitly blocked by the user.

For a quick read-only check of PRD Plugin messages and transport state, run:

python scripts/message_check.py --repo-root . --config .prd_plugin/config.json

The message check summarizes new inbox packages, already imported inbox packages, outgoing outbox packages, scoped mailbox files, and unresolved request-thread messages in one report.

To prepare a sanitized submission from a downstream repo, run the downstream runtime helper from the PRD Plugin hub/plugin bundle, or from the target repo only when that exact helper has been explicitly installed according to the script install-scope policy:

python scripts/request_export.py --request-id REQ-001

That writes a portable upstream package to .prd_plugin/outbox/.

The hub repo stages incoming packages in .prd_plugin/inbox/, then publishes repo-scoped replies through .prd_plugin/mailboxes/<repo-id>/. Downstream repos pull only their own mailbox and merge request statuses/messages locally:

python scripts/request_pull.py --mailbox .prd_plugin/mailboxes/my-repo/mailbox.json

To reply from a downstream repo:

python scripts/request_reply.py --request-id REQ-001 --visibility upstream --body "Here are the repro steps..."
python scripts/request_export.py --request-id REQ-001

When a downstream user asks to report, submit, upstream, or file a PRD Plugin bug, local request state is only the source record. The report is not complete until upstream-visible content has been exported with request_export.py and staged in the PRD Plugin hub inbox with request_import.py, unless the hub or import path is unavailable and that blocker is reported.

Automation Guard

Recurring request/mailbox checks should use a single-run lock before reading or acting on intake state:

python scripts/automation_guard.py begin --name request-check
python scripts/automation_guard.py complete --name request-check --run-id <run-id>

Locks and pending markers live under .prd_plugin/local/automation/, which is ignored by git. If a five-minute tick starts while a previous run is active, the new tick records a pending follow-up and exits. When the active run completes, it reports whether another pass is needed.

Treat scheduler state as a separate check from the local lock. The local guard shows whether a run is active, stale, or pending, but it does not show whether future ticks are still scheduled. To answer recurrence or pause/resume questions, also inspect the host agent's app-side automation record (for Codex, the file at %USERPROFILE%/.codex/automations/<automation-id>/automation.toml; for opencode, the equivalent host-managed schedule record) and read its kind, rrule, and status.

Completed automation runs may be archived automatically from a Stop hook when the transcript proves the session came from a Codex automation prompt with a known Automation ID. Use the host agent's archive semantics (for Codex, codex archive <session-id>) rather than moving or deleting transcript files directly. Stop-hook archive scripts should not print arbitrary diagnostics to stdout in normal hook mode because the host agent may parse stdout as hook protocol output; use an explicit diagnostic flag such as --json for manual checks.

Version Advice

Repos using PRD Plugin can check what changed before bumping their installed plugin version. Run version_advice.py from the PRD Plugin hub/development repo or plugin bundle, not from a blanket-copied downstream scripts/ directory:

python scripts/version_advice.py --installed-repo D:/Projects/some-repo

The script reads the downstream repo's installed version, compares it with this repo's .prd_plugin/state/releases.json, lists newer releases, and recommends safe_to_update, review_first, or blocked. When review is needed, create a version_change request with the current version, requested version, target repo, migration blockers, and breaking-change concerns.

To append that request automatically when review is advised:

python scripts/version_advice.py --installed-repo D:/Projects/some-repo --write-request --requests D:/Projects/some-repo/.prd_plugin/state/requests.json

Before bumping this plugin's version, run the gap audit:

python scripts/gap_audit.py --target-version 0.5.30

The primary PRD Plugin development workflow check does not require a GitHub remote:

python scripts/local_workflow_check.py

It validates structured files, runs full unittest discovery, checks state consistency, checks script install-scope policy, runs gap audit, version advice, release hygiene, and generates request and message reports. The request report analyzes .prd_plugin/state/requests.json, counts outstanding, denied, approved, implemented, in-review, and needs-info requests, and flags implemented requests that do not link to the plugin artifacts they graduated into. It also breaks intake down by request type, severity, request-thread message counts, unresolved threads, stale requests, and privacy warnings. It flags stale outstanding requests using requests.stale_after_days and stale accepted requests using health.accepted_request_stale_after_days.

The state consistency check verifies that evidence and session summaries do not claim missing MEM-*, TRK-*, CHG-*, OBS-*, or SES-* records, registry counters do not skip absent canonical records, and state or fixture timestamps are not in the future relative to validation time.

The optional GitHub Actions workflow at .github/workflows/request-intake-report.yml is only a wrapper around the same local command for repos that have GitHub configured. Plugin-impacting changes should bump .codex-plugin/plugin.json, .opencode/plugin.json, and .claude-plugin/plugin.json together, and skill changes should update related docs or templates so repos using the plugin know what changed.

System Tests

The system_tests/ directory contains a downstream integration test harness for REQ-028. It creates a temporary downstream repo, installs PRD Plugin from the local hub source, injects a canary .env, and drives an agent through scripted user prompts using either a deterministic mock driver or the opencode CLI simulated agent driver. After each scenario it asserts:

• durable state files are created and cross-linked by ID
• canonical planning/evidence/decision artifacts exist
• state_consistency_check.py reports no errors
• no secrets leak into output, logs, or persisted files
• no hub-only scripts run and no hub repo files are touched
• git push/merge only happen with explicit consent

Run the mock-driven system tests (no opencode required):

python -m pytest system_tests -v

The opencode-driven scenario tests run automatically when the opencode CLI is installed and are skipped otherwise. Set OPENCODE_MODEL to override the default model (opencode/deepseek-v4-flash-free):

set OPENCODE_MODEL=opencode/deepseek-v4-flash-free
python -m pytest system_tests/scenarios/ -v

You can also include system tests in the local workflow check:

python scripts/local_workflow_check.py --include-system-tests

Current Version Scope

This v0.5.33 package contains host-agent-neutral method docs, templates, structured agent state, request intake, project health checks, configuration, a downstream-safe installer (scripts/prd_install.py), repo-local skill installation, and a local request-report script, state consistency validator, mandatory upstream reporting rules for downstream PRD Plugin bug reports, sanitized upstream request export helper, release hygiene checks, version advice script, pre-bump gap audit, a PRD Plugin development local workflow check runner, downstream-safe local integration, Superpowers-adapted PRD-native planning, TDD, debugging, and verification skills, read-only downstream prd_doctor.py diagnostics, read-only message_check.py inbox/outbox/mailbox/thread summaries, scoped request mailboxes, guarded recurring automation with explicit app-side scheduler verification, protocol-safe automation-only session archiving through a Stop hook, a risk-based autonomous request-check workflow, request-thread deduplication for persistent bugs and repeated repros, autonomous investigation and commit requirements for clear low/medium-risk bug reports, workflow-wide staleness checks, an end-to-end planning lifecycle workflow, canonical JSON planning artifacts with Markdown exports only on human request, plus a default goal-backed fold-it-in integration workflow. A fuller CLI or human-readable export command can be added later.

OpenCode Deployment

Starting with v0.5.30, PRD Plugin ships an opencode-compatible delivery layer alongside the Codex layer:

• .opencode/plugin.json — opencode plugin manifest (mirrors the Codex manifest's name, version, skills, interface, and capabilities).
• .opencode/skill/<skill>/SKILL.md — the same downstream_runtime skill set that ships under .agents/skills/, discoverable by opencode agents.
• prd_install_skills.py --target-agent opencode (or --target-agent both) to populate the opencode target on demand.
• templates/repo-skeleton/.opencode/ — pre-seeded for new downstream repos.

The method itself (ID scheme, state schema, request/evidence/health workflow, skills) is host-agent neutral. Only the discovery paths and a few host-agent references in the docs (e.g. Codex's %USERPROFILE%/.codex/... automation record path) needed to change. Existing Codex consumers keep working without modification.

Claude Code Deployment

PRD Plugin ships a Claude Code delivery layer alongside the Codex and opencode layers:

• .claude/skills/<skill>/SKILL.md (repo-local) — the same downstream_runtime skill set that ships under .agents/skills/, auto-discovered by Claude Code. Claude Code needs no config-file injection (unlike opencode's opencode.json).
• prd_install_skills.py --target-agent claude (or the default --claude option of prd-install) populates the .claude/skills/ target on demand.
• templates/repo-skeleton/.claude/ — pre-seeded for new downstream repos.
• .claude-plugin/plugin.json + .claude-plugin/marketplace.json (hub) — make the hub repo installable as a Claude Code plugin via /plugin marketplace add, loading the plugin's top-level skills/ directory directly. Its version tracks .codex-plugin/plugin.json and is checked by release_check.py.

The SKILL.md frontmatter (name + description) is already the format Claude Code expects, so no skill content changed — only the discovery path was added.