# 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 JSON file is the sole persistent runtime authority. `prd_config.py` and the `prd_config_*` MCP tools provide one derived, validated catalog over every shipped setting: type, default, owner, mutability, activation point, dependencies, and latency. `inventory` also reports controls that intentionally remain outside persistent JSON. Built-in lean/balanced/thorough profiles are atomic policy bundles; external integrations remain explicit even under thorough. Manual setting changes mark the active profile as custom. Host manifests launch one dispatcher per event. It reads `hooks.enabled` and the relevant child/feature switches before loading existing behavior handlers. Disabling per-prompt nudge, skill logging, Stop reports, drift, reflection, or archive work therefore skips the handler entirely. Safety controls remain separately selectable and profile dependencies are visible through `effective`. The `reporting.delegation` block optionally delegates non-deterministic report prose to an AI-Collab-managed `fast-capable` model profile. PRD Plugin remains the control plane: it validates config, builds deterministic source-referenced bundles, selects a configured fallback, and validates returned JSON. It neither calls a model provider nor permits delegated results to mutate canonical state. The same policy is discoverable and toggleable through `prd_config.py`. The `integrations.substrate` block controls the optional AI-Collab adapter. It is disabled by default. `observe` permits read-only record, graph, and event projection; `coordinate` permits only the additional capabilities explicitly listed in config, with canonical writes still routed through PRD MCP. The direct JSON settings and `prd_config.py` are equivalent configuration paths. The optional `verification.test_scope` block delegates verification enrichment and execution to AI-Collab without duplicating its blast-radius engine. PRD Plugin's `prd_test_scope.py` deterministically collects exact local git changes, applies core/release/breadth fallbacks, and emits a fingerprinted plan. AI-Collab adds structural and predictive neighbours, maps every changed file to tests, and executes the scope. Degraded, unavailable, or unmapped results require full verification; no remote or CI is required. The `reflection` block controls optional Stop-hook self-assessment. It contains global `enabled`/`on_stop` toggles, a bounded question count, and ordered categories with independently enabled `RFQ-*` questions. The hook requests one concise pass using observable outcomes and then allows the next Stop; it never requests private chain-of-thought and never writes answers to canonical state. Use `prd_reflections.py` or the `prd_reflection_*` MCP tools for validated, duplicate-safe category/question CRUD instead of editing IDs manually. The `workflows` block controls the deterministic lifecycle engine. Shipped definitions own bounded sequencing, state-tool calls, exact facts, checks, verification plans, checkpoints, receipts, retries, and postconditions. The engine pauses only at explicit hash-bound `judgment.request` steps; AI-Collab executes the configured profile, and deterministic resume validates its schema and source provenance. See `.prd_plugin/method/deterministic-workflows.md`. Shipped feature guidance is also deterministic-audited. The compact `templates/feature-skill-map.json` contract maps capabilities, workflow IDs, and admin commands to their owning skill text. Run `python scripts/feature_skill_audit.py --repo-root .`; the result is folded into `workflow_chml_audit.py` and `local_workflow_check.py`, so mirror parity cannot masquerade as semantic freshness. ## Recommended Host Tooling The following host-agent tool patterns prevent common errors observed in agent session transcripts. They are not PRD Plugin skills — they are host-level tool wrappers that any agent should configure regardless of the plugin they use. ### `read-with-offset` `File content exceeds maximum allowed tokens` is the single largest tool error class in observed agent sessions (48 of 87 errors, 55%). A `read-with-offset` tool handler should auto-chunk large files into `Read` calls with `offset` and `limit` parameters before they hit the host's token ceiling. ### `read-before-edit` `File has not been read yet. Read it first before writing to it` is the second most common error class (9 of 87). A `read-before-edit` guard should require the agent to have read the file in the current session before allowing an `Edit` or `Write` on the same path. Most hosts already enforce this in their tool contract; the failure mode is when an agent's tool-call ordering violates the contract. These are host concerns, not PRD Plugin concerns. PRD Plugin documents them here because plugin agents that read or edit `.prd_plugin/state/*.json` or `docs/` will hit them. Configure your host agent to enforce both patterns before relying on PRD Plugin skills that depend on file state. 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 - delegated-reporting eligibility, executor contract, profile, bounds, and fallback - AI-Collab Substrate adapter mode, capability allowlist, per-workflow automation switches, endpoints, and source-reference policy - repository service consume/provide declarations in `.prd_plugin/services.json` - impact-scoped verification executor, bounds, core/test patterns, and full-suite triggers - release hygiene policy - release metadata and version advice policy - privacy and upstream submission policy - canonical planning artifact and Markdown export policy ## Superpowers Method Alignment PRD Plugin adopts selected Superpowers execution disciplines as PRD-native skills where Superpowers has the stronger method. Those adapted skills keep the execution iron laws while making PRD Plugin IDs, evidence, request state, health, changelog, and traceability non-negotiable. Use: - `project-implementation-plan` for durable `IMP-PHASE-*`, `IMP-TASK-*`, and `IMP-VAL-*` planning from approved PRD/architecture/request sources. - `project-test-driven-implementation` for test-first feature, bug, refactor, and behavior changes tied to `REQ-*`, `IMP-TASK-*`, or `HLT-*`. - `project-systematic-debugging` for root-cause investigation before fixes. - `project-verification-before-completion` before claiming work is complete, fixed, healthy, passing, or ready to commit. Superpowers-style specs, checklists, and debugging reports may be source material, but they do not replace PRD Plugin durable IDs. Map useful execution steps into `IMP-*`, validation into `EV-*`, lasting decisions into `DEC-*`, and request discussions into `REQ-*` / `MSG-*`. ## Fold It In Workflow Use `project-fold-it-in` when a change should become part of the plugin rather than a single artifact edit. Use `project-local-integration` in downstream repos when a change should become part of that repo's project truth. That workflow updates local PRD Plugin artifacts, requests, memory, traceability, health, evidence, changelog, and tracking state, but does not run plugin release, version-bump, publication, or gap-audit mechanics. The workflow ensures agents: - classify the change - create or update an active goal for fold-it-in work before implementation - inspect affected docs, skills, templates, config, state, scripts, tests, and workflows - keep the visible progress plan aligned with the active goal - update companion artifacts - update request, health, traceability, or changelog state when needed - run validation - run release hygiene - bump the plugin version for plugin-impacting changes - report remaining `REQ-*` or `HLT-*` items and the goal status when relevant ## Planning Lifecycle Workflow Use `project-planning-lifecycle` when brainstorms, early notes, accepted requests, or rough feature ideas need to become a complete planning chain: ```text brainstorm -> PRD -> architecture -> implementation plan -> traceability sync/review ``` This workflow is the guardrail against stale planning shortcuts. It requires agents to gather or refresh source context, create or update the PRD before architecture, create or update architecture before implementation planning, and run traceability sync/review before closeout. Lifecycle gates: - `PRD-REQ-*` records cite `BR-*` or accepted `REQ-*` sources. - Major `ARCH-*` components, interfaces, decisions, and risks cite `PRD-*` or `DEC-*` sources. - `IMP-TASK-*` records cite both `PRD-*` and `ARCH-*` sources. - Open `BR-Q-*`, `BR-RISK-*`, stale `TRK-*`, stale `REQ-*`, open `HLT-*`, stale request threads, and stale request transport are carried forward or recorded as explicit follow-up. - Implementation planning does not begin until PRD and architecture are coherent enough to plan from. ## Canonical Planning Artifacts JSON/JSONL is canonical for planning artifacts. Generate Markdown only on explicit human request. PRDs, architecture docs, and implementation plans may become too large for reliable agent parsing and too risky to dual-write. Each planning artifact therefore lives as a canonical JSON artifact at: ```text .prd_plugin/state/artifacts/{artifact_type}/{artifact_id}.json ``` The JSON artifact should include the artifact ID, short agent summary, stable child IDs, traceability links, open questions, stale follow-ups, and evidence expectations. Markdown exports are human-readable snapshots generated under `docs/exports/` only when requested; they are not project truth and should not be edited as canonical state. ## Artifact Flow | Stage | Artifact | Main IDs | | --- | --- | --- | | Brainstorm | `docs/brainstorm/*.md` | `BR-REQ`, `BR-DEC`, `BR-RISK`, `BR-Q` | | PRD | `.prd_plugin/state/artifacts/prd/*.json` | `PRD-REQ`, `PRD-NFR`, `PRD-ACC` | | Architecture | `.prd_plugin/state/artifacts/architecture/*.json` | `ARCH-COMP`, `ARCH-DEC`, `ARCH-IF`, `ARCH-RISK` | | Plan | `.prd_plugin/state/artifacts/implementation_plan/*.json` | `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` | ## Repo-Local Skill Install `.prd_plugin/` is project state and method configuration. It is not a Codex skill discovery path. Codex discovers repository skills from: ```text .agents/skills//SKILL.md ``` Downstream PRD Plugin installs should therefore include only the downstream runtime PRD Plugin skill set under `.agents/skills/` so memory promotion, tracking, changelog, request intake, health, session-close, and traceability workflows are available to Codex agents in the repo itself. New repo skeletons carry this structure by default. Existing repos can install or refresh the full downstream payload from the PRD Plugin hub/plugin bundle: ```bash python scripts/prd_install.py ``` `prd_install.py` copies the repo skeleton (`.prd_plugin/`, `.codex-plugin/`, `.opencode/`, `.codex/hooks.json`), installs repo-local skills, and installs allowed downstream runtime scripts. It skips existing files unless `--force` is passed and refuses to install into the PRD Plugin hub repo itself. Plugin development and hub-only scripts are never copied. To refresh only repo-local skills: ```bash python scripts/prd_install_skills.py --repo-root ``` Use `.agents/skills` for agent workflow capability and `.prd_plugin/` for durable project state. Keep plugin-development workflows, such as changing the PRD Plugin package itself, in the PRD Plugin hub/plugin bundle rather than installing them into ordinary downstream repos. ## 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 fold-it-in 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-* ``` ## LLM Wiki Navigation The LLM wiki is the durable human- and agent-readable knowledge layer, distinct from canonical project state. Every reference from wiki prose to another local Markdown file must be an inline relative link. Run `prd_wiki_backfill.py --lint-links --fix` during Lint; the fixer changes only unambiguous references, while missing or ambiguous targets remain blocking findings. The composed gate enforces the policy when `knowledge.llm_wiki.require_inline_md_links` is enabled (the default). See the [LLM wiki article](../wiki/knowledge/the-llm-wiki.md). ## 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 - evidence or session summaries claiming missing `MEM-*`, `TRK-*`, `CHG-*`, `OBS-*`, or `SES-*` records - registry counters that skip absent canonical records - future timestamps in state or fixtures Staleness checks are a cross-workflow requirement. Skills and workflows should use configured thresholds for requests, tracking, accepted-request graduation, and automation locks; stale records should be resolved, refreshed with evidence, superseded, or left as explicit `HLT-*`/`REQ-*` follow-up rather than silently ignored. `state_consistency_check.py` is a required downstream runtime beside `prd_gate.py`; the gate reports an error rather than silently skipping it when installation is incomplete. Run `python scripts/state_consistency_check.py --repo-root .` before marking health healthy or claiming evidence/session closeout is complete. 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. Before creating a new `REQ-*`, search existing requests and thread messages for the same affected area, error text, reproduction path, compatibility symptom, or requested outcome. Persistent bugs, repeated compatibility failures, and later-version repro confirmations should be recorded as new `MSG-*` entries on the original request thread, not as fresh duplicate `REQ-*` records. Update affected-version metadata on the original request when the new message proves the issue still applies. 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. For `prd_file_request`, an explicitly supplied `scope: local` is authoritative and prevents automatic upstream export. Omit `scope` to allow automatic classification. A canonical `.prd_plugin/` state path is not, by itself, a reference to the PRD Plugin product. 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 Downstream repos do not need write access to the hub repo. ### Script Install-Scope PRD Plugin scripts are not copied wholesale into downstream repositories. `templates/script-install-scope.json` is the authoritative script install-scope policy, and installed skeletons carry the same policy at `.prd_plugin/templates/script-install-scope.json`. Downstream repos should not have a default copied `scripts/` directory. If a repo explicitly opts into local helper execution, 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. Agents should treat a full copied PRD Plugin `scripts/` directory in a downstream repo as a stale install artifact to report and clean up by policy, not as project truth. When optional downstream helpers are explicitly installed, run the read-only doctor before mutating project truth: ```bash python scripts/prd_doctor.py --repo-root . ``` The doctor reports missing or invalid PRD Plugin config, invalid request JSON, stale request attention points, request privacy warnings, and copied hub/development scripts that should not live in ordinary downstream repos. When examples below use `python scripts/*.py`, run that helper from the PRD Plugin hub/plugin bundle unless the exact helper has been explicitly installed in the target repo according to the script install-scope policy. When asked to check messages, inboxes, mailboxes, outbox packages, or unresolved request-thread replies, inspect the current repository's PRD Plugin transport first: Call the `prd_check_messages` MCP tool. The MCP tool is the preferred host-neutral surface. If it is unavailable, run `python .prd_plugin/scripts/message_check.py --repo-root . --config .prd_plugin/config.json` downstream or `python scripts/message_check.py --repo-root . --config .prd_plugin/config.json` in the hub checkout. The checker reports new inbox packages, packages already imported into canonical `REQ-*` records, outgoing outbox packages, scoped mailbox files, pending replies, and unresolved request threads. Do not report an empty inbox from a chat, email, collaboration, or host-message tool without completing this PRD check. Use the mailbox protocol: 1. Downstream repo creates or updates local `REQ-*` and `MSG-*` records. 2. Downstream repo exports a sanitized package to `.prd_plugin/outbox/`. 3. Hub repo imports packages into `.prd_plugin/inbox//incoming/`. 4. Hub maintainers or automation validate incoming packages before graduating them into hub `.prd_plugin/state/requests.json`. 5. Hub repo publishes scoped replies to `.prd_plugin/mailboxes//`. 6. Downstream repo pulls only its own mailbox into local requests. When a downstream user asks to report, submit, upstream, or file a PRD Plugin bug, local request state is not enough. 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 checkout or import path is unavailable and that blocker is reported. For autonomous request checks in the hub repo, low-risk validated inbox submissions may be imported automatically, while medium-risk non-bug submissions should still be triaged into canonical request state with review status rather than left only in transport. Low- or medium-risk bug submissions with clear reproduction steps and a bounded fix must not stop at `in_review`. Run the bug investigation workflow, add a failing test, implement the fix, verify it, update request state, and commit unless missing detail, unsafe scope, unbounded work, or explicit user direction blocks the fix. Commands: ```bash python scripts/request_reply.py --request-id REQ-001 --visibility upstream --body "..." python scripts/request_export.py --request-id REQ-001 python scripts/request_import.py --package .prd_plugin/outbox/REQ-001-upstream.json python scripts/request_mailbox.py --repo-id my-repo --output .prd_plugin/mailboxes/my-repo/mailbox.json python scripts/request_pull.py --mailbox .prd_plugin/mailboxes/my-repo/mailbox.json ``` The PRD Plugin development repo may run the local request-intake report workflow without a GitHub remote: ```bash python scripts/local_workflow_check.py ``` The workflow reads `.prd_plugin/state/requests.json` and 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 - stale requests - 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. Treat recurrence as a separate layer from the local guard. Local automation state answers whether a run is active, stale, or pending; it does not answer whether future ticks are configured. For pause/resume or "is this still scheduled?" questions, inspect the host agent's app-side automation record (for Codex, the file at `%USERPROFILE%/.codex/automations//automation.toml`; for opencode, the equivalent host-managed schedule record) and report its `kind`, `rrule`, and `status` alongside the local lock state. 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. Use a Stop hook for session archiving, not transcript file moves, and scope it to real automation sessions by verifying the Automation ID against `$CODEX_HOME/automations//automation.toml`. Archive through the host agent's archive command (e.g. `codex archive ` for Codex) after the run finishes so the session is removed from the picker without deleting its transcript. Keep normal hook-mode stdout empty unless emitting a documented Codex hook response; arbitrary diagnostic JSON belongs behind an explicit manual flag or on stderr for failures. ## Version Advice Repos using PRD Plugin should inspect upgrade impact before changing their installed plugin version. Use `scripts/version_advice.py` from the hub repo: ```bash python scripts/version_advice.py --installed-repo ``` The script reads the downstream repo's installed version from `.prd_plugin/config.json`, `.codex-plugin/plugin.json`, or `.prd_plugin/state/project.json`, then compares it with `.prd_plugin/state/releases.json`. Advice outputs: - installed version - latest hub version - releases newer than the installed version - changes and migration notes - recommendation: `safe_to_update`, `review_first`, or `blocked` - suggested `request_type: version_change` when review is needed `version_change` requests should include `current_plugin_version`, `requested_plugin_version`, `target_repo`, `update_window`, `breaking_change_concerns`, and `migration_blockers` where known. Use `--write-request` to append a local `version_change` request when the advice is `review_first` or `blocked`. ## 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. For PRD Plugin development validation, prefer the combined workflow command: ```bash python scripts/local_workflow_check.py ``` GitHub Actions, when configured by a repo, should call that local command rather than duplicate a separate workflow definition. ## Release Hygiene Plugin-impacting changes should update the plugin version in `.codex-plugin/plugin.json`. Skill changes should also update companion docs or templates when repos using the plugin need new instructions, examples, or starter artifacts. The local release hygiene workflow should report: - whether plugin-impacting files changed - whether the plugin version changed - whether skill changes had companion docs or template updates - whether every `scripts/*.py` file is classified in `templates/script-install-scope.json` - whether the repo skeleton is free of scripts that are not explicitly allowed for default downstream install - required follow-up actions before release ## Document Branching Mainline structured state contains promoted project truth. Markdown document branches contain proposed or review-friendly narrative snapshots. 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. ### Parallel tracking branches Tracking state uses document branches when agents work concurrently. Before fan-out, the lead creates and commits one branch per worker with `prd_open_tracking_branch`, then launches it with `PRD_WORKER_SESSION=1`, `PRD_TRACKING_BRANCH_ID=`, and `PRD_TRACKING_BRANCH_OWNER=`. Each worker writes only its assigned `.prd_plugin/state/tracking-branches/DBR-*.json` through `prd_update_tracking_branch`; workers never edit canonical tracking or allocate registry IDs. After worktree merges, the lead applies branches serially with `prd_promote_tracking_branch`, which performs conflict checks and idempotent canonical promotion under the state lock. The MCP runtime enforces that boundary when `tracking.branching.require_for_parallel_agents` is true. Workers record needed canonical state changes in branch notes; the lead applies them serially after merge. `prd_status`, `prd_find(kind: DBR)`, and `prd_get(DBR-*)` expose branch state without file scanning.