# PRD Plugin Method ## Principle Every important project idea should gain a stable ID before it becomes a PRD requirement, architecture decision, implementation task, or evidence claim. Stable IDs make it possible to ask: - Where did this requirement come from? - Which architecture decision satisfies it? - Which implementation task delivered it? - Which evidence proves it? - Which decisions changed over time? ## Configuration Project-specific configuration lives in `.prd_plugin/config.json` when present. Agents and scripts should read it before assuming default paths or policies. The config may define: - state, local, docs, registry, request, and health paths - local automation lock paths - request-intake policy - allowed request types and severities - memory promotion policy - health thresholds - ID formatting and required prefixes - agent/session provenance requirements - report defaults - release hygiene policy - release metadata and version advice policy - privacy and upstream submission policy ## Local Integration Workflow Use `project-local-integration` for cross-cutting changes that touch docs, skills, templates, config, state, scripts, tests, and workflows in this repo. The workflow ensures agents: - classify the change - keep the visible progress plan aligned with the active work - inspect affected docs, skills, templates, config, state, scripts, tests, and workflows in this repo - update companion artifacts - update request, health, traceability, or changelog state when needed - run validation - do not bump the plugin version or edit the PRD Plugin hub repo To change the PRD Plugin itself (skills, templates, scripts, version), that is a hub-only workflow. File a `REQ-*` against the plugin and run `npx prd-install . --force` in this repo to pick up the next published version from npm. ## Artifact Flow | Stage | Artifact | Main IDs | | --- | --- | --- | | Brainstorm | `docs/brainstorm/*.md` | `BR-REQ`, `BR-DEC`, `BR-RISK`, `BR-Q` | | PRD | `docs/prd/*.md` | `PRD-REQ`, `PRD-NFR`, `PRD-ACC` | | Architecture | `docs/architecture/*.md` | `ARCH-COMP`, `ARCH-DEC`, `ARCH-IF`, `ARCH-RISK` | | Plan | `docs/implementation/*.md` | `IMP-PHASE`, `IMP-TASK`, `IMP-VAL` | | Decision | `docs/decisions/*.md` | `DEC` | | Evidence | `docs/evidence/*.md` | `EV` | | Agent memory | `.prd_plugin/state/*.json` | `AGENT`, `SES`, `MEM`, `OBS`, `TRK`, `CHG` | | Requests | `.prd_plugin/state/requests.json` | `REQ`, `MSG` | | Health | `.prd_plugin/state/health.json` | `HLT` | | Releases | `.prd_plugin/state/releases.json` | version strings | | Traceability | `docs/traceability/*.md` | mapping tables | | Document branch | `docs/doc-branches/DBR-*/` | `DBR`, `DBR-DELTA`, `DBR-MERGE`, `DBR-REG` | ## Gates 1. Do not write implementation plans until the PRD and architecture are coherent. 2. Do not implement from an unmapped plan task. 3. Do not claim completion without evidence. 4. Do not treat templates as project truth; the repo's committed artifacts are the project truth. 5. Do not promote raw agent session memory into committed state without provenance, sources, and a sensitivity check. 6. Do not run goal-backed local integration work without an explicit active goal and a progress plan that stays in sync with it. ## Agent Memory And State Agent-facing project state lives under `.prd_plugin/state/` as JSON and JSONL. Raw session memory lives under `.prd_plugin/local/` and should be ignored by git. Recommended committed files: ```text .prd_plugin/state/ project.json memory.json decisions.json changelog.json tracking.json requests.json health.json sessions/shared/promoted-session-summaries.jsonl ``` Recommended local files: ```text .prd_plugin/local/sessions// session.json events.jsonl scratch.json handoff.json ``` Use JSON for snapshots and indexes. Use JSONL for append-only event or summary streams. Markdown exports may be generated for humans later, but JSON remains the canonical agent state format. Promotion rule: ```text local session memory -> promoted session summary -> committed project state ``` Only promote concise, source-backed, non-sensitive records that future agents should rely on. Trace promoted memory through this chain where possible: ```text AGENT-* -> SES-* -> OBS-* -> MEM-* -> TRK-* / CHG-* / EV-* ``` ## Project Health Project health checks produce compact operational findings in `.prd_plugin/state/health.json`. Use `HLT-*` for findings such as: - orphan requirements - unmapped architecture or implementation items - stale `TRK-*` records - missing evidence expectations - promoted memory without sources or provenance - document branches promoted without evidence - missing `CHG-*` records for material state changes Health findings should cite affected IDs or source files, include severity, and record the `AGENT-*` and `SES-*` that produced the check. ## Unified Request And Issue Intake Request intake protects project truth from speculative outside-agent edits, bug reports, compatibility concerns, and issue reports that need review. Outside agents should append proposed changes to `.prd_plugin/state/requests.json` using `REQ-*` records instead of directly modifying PRDs, architecture, plans, skills, templates, or committed state. Use request records for: - proposed features - bugs - compatibility issues - proposed method changes - suspected defects that need owner review - suggested refactors - documentation improvements - version-change review before a downstream repo updates PRD Plugin - outside-agent handoff suggestions A reviewed request may become accepted work by linking to `TRK-*`, `DBR-*`, `PRD-*`, `ARCH-*`, `IMP-*`, `CHG-*`, or `EV-*` records. Rejected or superseded requests should keep their rationale so future agents do not relitigate them. ### Request Threads Use `MSG-*` records inside a request's `thread.messages` array when a request needs back-and-forth before a decision. A thread lets maintainers ask for constraints, request reproduction details, offer a compromise, or explain why a request is unsafe without changing project truth. Request statuses support the discussion flow: - `proposed`: submitted but not reviewed - `in_review`: actively being discussed or assessed - `needs_info`: waiting for requester input - `accepted`: approved for work or incorporation - `rejected`: reviewed and declined - `superseded`: replaced by another request or artifact - `implemented`: accepted and completed `MSG-*` records should include author agent/session provenance, visibility, optional `reply_to`, body, timestamps, and source references. Messages must not include secrets, raw reasoning traces, or `.prd_plugin/local/` session state. ### Request Privacy PRD Plugin uses a hub-and-spoke intake model: - the `prd-plugin` repo may act as the upstream hub for plugin-level requests, issues, bugs, compatibility reports, and discussion messages - repos using PRD Plugin should store only their own repo-local requests, issues, bugs, compatibility reports, and messages - a repo must not read another repo's request/message state unless an explicit export/import or upstream submission has occurred - cross-repo request and message visibility should default to false - `.prd_plugin/local/` should be excluded from indexing and upstream submission Use request fields such as `scope`, `origin_repo`, `visibility`, `upstream_submission`, and `upstream_request_id` to distinguish local records from upstream plugin records. Explicit upstream submissions should be sanitized exports. They may include the request summary, rationale, reproducible public evidence, and only thread messages marked for upstream visibility. They must not include repo-local private messages, raw local session paths, or absolute local filesystem paths. ### Request Transport If a downstream repo wants to report a PRD Plugin bug to the hub, the mailbox protocol is: 1. Create or update a local `REQ-*` and `MSG-*` records with `scope: "local"`, `visibility: "upstream"` for messages intended for the hub, and `upstream_submission: true` on the request. 2. Export a sanitized package to `.prd_plugin/outbox/`. The export helper lives in the PRD Plugin hub, not in this repo. 3. The hub import, validation, and mailbox reply steps are hub-only workflows. The repo-local `request_export.py` and `request_pull.py` helpers are optional `downstream_runtime` scripts. They are not installed by default; if you want to use them, run `npx prd-install . --include-optional-scripts --force`. Repositories may run a request-intake report workflow that reads `.prd_plugin/state/requests.json`. The report should count: - outstanding requests: `proposed`, `in_review`, `needs_info`, and `accepted` - denied requests: `rejected` - approved requests: `accepted` - implemented requests: `implemented` - implemented into plugin: `implemented` requests with `graduated_to` links - in-review requests: `in_review` - needs-info requests: `needs_info` - thread messages and unresolved request threads - privacy warnings for cross-repo visibility, invalid scope, or local-state references - request type counts: `feature`, `bug`, `compatibility`, and other configured types - severity counts: `critical`, `high`, `medium`, `low`, and `unspecified` ### Automation Guard Frequent request/mailbox automation must use a local lock before scanning or acting on intake state. Use `scripts/automation_guard.py begin` at run start and `scripts/automation_guard.py complete` at run end. The guard writes only to `.prd_plugin/local/automation/`, which is local-only and ignored by git. If a scheduled tick begins while another run is active, the new tick should exit after writing a pending marker. The active run should check the completion result and perform one follow-up pass when `pending_follow_up` is true. If a lock is stale, automation may take it over after the configured `stale_after_seconds` window and should report the stale takeover in its summary. ## Version Advice Repos using PRD Plugin should inspect upgrade impact before changing their installed plugin version. Use the latest published version on npm and the releases metadata that ships in this repo at `.prd_plugin/state/releases.json`. The installed version lives in `.prd_plugin/config.json` under `plugin.installed_version`. The script in the hub is `version_advice.py`, but downstream repos do not need a local copy. The recommended flow is: 1. Run `npm view prd-plugin versions --json` to see available versions. 2. Read `.prd_plugin/state/releases.json` for the per-version changelog. 3. If the recommended version requires a `review_first` or `blocked` decision, file a local `version_change` `REQ-*`. `version_change` requests should include `current_plugin_version`, `requested_plugin_version`, `target_repo`, `update_window`, `breaking_change_concerns`, and `migration_blockers` where known. ## Gap Audit Run a gap audit before bumping `.codex-plugin/plugin.json`: ```bash python scripts/gap_audit.py --target-version ``` The audit checks release metadata and other pre-bump gaps before the final version change. Fold any findings into docs, skills, templates, scripts, workflows, state, or release metadata first, then bump the version. ## Release Hygiene This repo does not own the PRD Plugin version. Do not edit `.codex-plugin/plugin.json` or run plugin release hygiene in this repo. Those are hub-only workflows. If you want to propose a plugin change, file a `REQ-*` against the plugin. Updates flow from npm only. - required follow-up actions before release ## Document Branching Mainline docs contain promoted project truth. Document branches contain emerging, proposed, experimental, or disputed project truth. Use a document branch when an idea, critical path, fix, lesson, or architecture change is not yet proven enough to merge into mainline PRD, architecture, or implementation docs. Document branches live under: ```text docs/doc-branches/DBR-001-topic/ ``` Each branch should define: - trigger - hypothesis - proposed deltas - evidence requirements - merge criteria - regression conditions - promotion decision Promotion into mainline requires evidence and anchors: - evidence ID - code anchor, if applicable - test anchor, if applicable - telemetry query, if applicable - last verified commit - regression condition - merge decision If a promoted lesson later regresses, create a regression document branch rather than silently editing mainline history.