---
name: project-local-integration
description: Use when a downstream repo asks to fold, wire, integrate, or make a change part of the current repo's project truth; also use when reporting PRD Plugin bugs from a downstream repo so they are exported upstream instead of only filed locally.
---

# Project Local Integration

Use this skill to integrate a cross-cutting change into the current downstream
repo's PRD Plugin-managed project truth.

## Rules

- Treat "fold this in" as local integration work, not a narrow file edit.
- Keep ordinary project work inside the current repo.
- A local product feature filed with explicit `scope: local` remains in this
  repository and must not be reclassified merely because its artifacts live
  under `.prd_plugin/`.
- **Any request about PRD Plugin itself goes upstream — whether or not the user
  asked.** If the record names a plugin-owned surface — a `prd_*.py` script, a
  hook (`prd_stop_guard.py`, `prd_precommit_gate.py`, …), a `project-*` skill, a
  method doc, the MCP server, or the installer — it is a plugin bug, not a project
  bug. Local request state is not enough, and waiting to be asked is how plugin
  bugs die in local state.
- **Submission is the tool's job, not your memory's.** Filing through the
  `prd_file_request` MCP tool flags the record, exports the package, and delivers
  it to the hub when one is configured. For a record written any other way, run
  `python scripts/request_autosubmit.py --request-id REQ-xxx`. Never hand-export.
- PRD Plugin bug reports from downstream repos must be upstreamed when the PRD
  Plugin hub checkout or import path is available.
- A plugin bug that lives only in your `requests.json` is an **unreported** bug:
  the hub cannot see it, so it never gets fixed. `prd_gate.py` warns on every
  commit while such a request is unsubmitted (`unsubmitted_plugin_request`).
- **Send the request all the way to the hub immediately — do not leave it in the
  outbox where no one can read it.** Exporting a package into
  `.prd_plugin/outbox/` is only the first half of sending; in the same run you
  must import it into the PRD Plugin hub inbox and verify it arrived. An
  exported-but-unimported package is a dropped request, not a sent one. The only
  exception is a genuinely unavailable hub/import path, which must be reported as
  a blocker rather than left as a stranded outbox file.
- Do not use plugin-development workflows such as `project-fold-it-in` for
  ordinary downstream repos.
- Do not bump `.codex-plugin/plugin.json`, update PRD Plugin release metadata,
  run plugin gap audits, or prepare plugin publication from a downstream repo.
- Respect repo instructions such as `AGENTS.md` before mutating project truth.
- Do not give time/duration estimates; use complexity and confidence (and risk)
  ratings instead, only using a schedule when the repo explicitly asks for one.
  Follow `.prd_plugin/method/estimation.md`.
- Run verification before claiming completion.

## Local Surfaces

Check and update only the surfaces that apply:

1. `.prd_plugin/state/requests.json` for proposed, accepted, or implemented
   `REQ-*` and `MSG-*` records.
2. `.prd_plugin/state/tracking.json`, changelog state, and `TRK-*` / `CHG-*`
   records when the work changes active or completed project state.
3. `.prd_plugin/state/memory.json` or related memory files when a durable
   lesson should be promoted with sources.
4. `.prd_plugin/state/health.json` for stale, risky, or blocked follow-up.
5. `.prd_plugin/state/artifacts/*/*.json` for canonical PRD, architecture, or
   implementation-plan changes.
6. Decision, evidence, and traceability ledgers when the change affects durable
   decisions, validation claims, or ID links.
7. Repo files that implement the requested local change.

## Workflow

1. Classify the request as local docs, state, planning, implementation,
   evidence, memory, health, request intake, or traceability work.
2. Search existing project truth for matching `REQ-*`, `TRK-*`, `HLT-*`,
   `DEC-*`, `EV-*`, and relevant artifact IDs before creating new records.
3. If the change is speculative or externally reported, create or update a
   local `REQ-*` through `project-request-intake` before editing mainline
   project truth.
4. If the request is a PRD Plugin bug report, add an upstream-visible `MSG-*`,
   run `request_export.py`, then immediately run `request_import.py` into the PRD
   Plugin hub inbox in the same run — this is one uninterrupted handoff, never
   left half-done with the package parked in `.prd_plugin/outbox/`. Confirm the
   package shows up in the hub inbox (for example via `message_check.py`). The
   report is not complete until the upstream package is staged in the hub inbox,
   or the missing hub/import path is explicitly reported as a blocker.
5. If the change is accepted local work, update the canonical artifact or state
   file that owns the truth, then update traceability and evidence links.
6. Record durable decisions with `project-decision-ledger`.
7. Record validation evidence with `project-evidence` or
   `project-evidence-ledger` before marking work complete.
8. Promote reusable lessons through `project-memory` only when they have source
   references and belong in durable memory.
9. Use `project-session-close` at closeout so tracking, changelog, memory, and
   request state reflect the completed local work.

## Staleness Responsibility

Apply the shared policy in `.prd_plugin/method/staleness-rules.md`.


Before changing local project truth, check whether matching `REQ-*`, `TRK-*`,
`HLT-*`, document branches, request transport, automation locks, or scheduler
state are stale. Resolve stale local items, refresh them with evidence, or leave
an explicit local follow-up before closeout.

## Boundaries

- Use the PRD Plugin hub/plugin bundle, not repo-local downstream skills, for
  plugin package changes, marketplace/package metadata, version bumps, release
  hygiene, and plugin-wide method changes.
- Use upstream request export only for sanitized content explicitly marked
  `upstream`; keep repo-local messages local.
- Do not describe a PRD Plugin bug as reported upstream if it only exists in
  local `.prd_plugin/state/requests.json`.
- Do not copy hub-only or plugin-development scripts into the downstream repo
  unless the script install-scope policy explicitly allows it.

## Closeout

Report:

1. Updated local artifacts, state records, and IDs.
2. New or updated `REQ-*`, `MSG-*`, `TRK-*`, `CHG-*`, `HLT-*`, `DEC-*`, or
   `EV-*` records.
3. Verification commands and results.
4. Remaining local follow-ups or upstream submissions.

## Parallel Worker State Boundary

When `tracking.branching.require_for_parallel_agents` is true, a parallel worker
is launched with `PRD_WORKER_SESSION=1`, `PRD_TRACKING_BRANCH_ID=<DBR-*>`, and
`PRD_TRACKING_BRANCH_OWNER=<owner>`. It calls only
`prd_update_tracking_branch` on that assigned branch. Any `REQ-*`, `TRK-*`,
`CHG-*`, `EV-*`, `DEC-*`, `HLT-*`, `MEM-*`, or other canonical state update is
recorded as a branch note for the lead. After merge, the lead serially performs
those canonical state writes and calls `prd_promote_tracking_branch`. Workers
never edit canonical state or `.prd_plugin/ids/registry.json` directly.