---
name: project-fold-it-in
description: Use when the user asks to "fold it in", "wire it in", "integrate this properly", "make this part of the plugin", "add this across the workflow", or otherwise incorporate a change across PRD Plugin method docs, skills, templates, config, state, scripts, workflows, validation, release hygiene, and versioning.
---

# Project Fold It In

Use this skill to incorporate a change across the whole PRD Plugin method
without leaving related artifacts stale.

## Rules

- Treat "fold it in" as an integration request, not a narrow file edit.
- Start by classifying the change and listing affected surfaces.
- Any "fold it in" style request should create or update the active goal
  before implementation. Record the active goal in `.prd_plugin/state/tracking.json`
  as a `TRK-*` record of `type: goal`, and link it from the originating `REQ-*`
  through `linked_ids`.
- Keep the visible progress plan aligned with the active goal throughout
  the work.
- Update companion artifacts when behavior changes.
- Do not mutate project truth silently; use `REQ-*`, `HLT-*`, `CHG-*`, or
  `TRK-*` records when the change affects intake, health, changelog, or active
  work.
- In parallel work with `tracking.branching.require_for_parallel_agents`, the
  lead sets `PRD_WORKER_SESSION=1`, `PRD_TRACKING_BRANCH_ID`, and
  `PRD_TRACKING_BRANCH_OWNER` for each worker. Workers call only
  `prd_update_tracking_branch`; the lead serially performs every canonical state
  write and calls `prd_promote_tracking_branch` after merge.
- If the change is plugin-impacting, update the plugin version in
  `.codex-plugin/plugin.json` and `.opencode/plugin.json` (and any
  `release.version_file_candidates` entry the repo overrides) along with the
  README version wording, only after running the pre-bump gap audit.
- Run verification before claiming completion.
- This skill is for local hub integration only. Do not push to remotes or merge
  branches from here. When the work is ready to share, record the branch name and
  route push/merge decisions through `project-git-workflow`. If the user has
  explicitly said to continue autonomously and no blocker exists, you may still
  use `project-git-workflow` to finish the branch safely.

## Pre-Flight Guardrails

Use the smallest coherent increments that preserve the full requested scope.
File count alone is not a stop condition: split only where increments have
independent behavior, tests, and rollback boundaries.

1. **Map affected surfaces.** Identify skill, template, config, state, script,
   validation, documentation, and release consequences before editing.
2. **Choose coherent increments.** Separate independently verifiable behavior,
   but keep one cross-cutting behavior together when splitting would create
   temporary contradictions.
3. **Require evidence before finalization.** Before writing
   `CHG-*` and marking the goal complete, every `graduated_to`
   link from the originating `REQ-*` must point to a real file
   that was changed in this session. A `graduated_to` that points
   to a file you did not actually edit is a fabrication; the
   audit log will show it.
4. **Fail loud on guardrail trips.** If a guardrail fires, do
   not silently reduce scope. Open a `REQ-*` explaining the
   guardrail failure and link it from the active goal. The
   next agent will see the same signal.
5. **Promote the session to `MEM-*` only after the CHG-*
   is written.** A `MEM-*` that records "skill X was created"
   before the `CHG-*` is committed is a memory of intent, not
   of record. Use `promotion_requires_agent_session` and the
   `selective_min_confidence` policy when in doubt.

## Change Classification

Classify the request as one or more:

- method/docs
- skill behavior
- template/state shape
- config/policy
- ID scheme/registry
- request/issue intake
- health/traceability
- script/test/workflow
- release/version behavior

## Staleness Gate

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


Before editing, audit existing stale `HLT-*`, `TRK-*`, `REQ-*`, request
transport, automation lock, and scheduler findings. If the change touches one
of those surfaces, either resolve the stale item, update its timestamp/status
with evidence, or leave an explicit `HLT-*`/`REQ-*` follow-up.

## Affected Surfaces

Check and update relevant files:

1. `.codex-plugin/plugin.json` and `.opencode/plugin.json`
2. `README.md`
3. `docs/METHOD.md`
4. `docs/ID-SCHEME.md`
5. relevant `skills/*/SKILL.md`
6. `templates/*`
7. `templates/repo-skeleton/.prd_plugin/*`
8. `.prd_plugin/config.json`
9. `.prd_plugin/state/*`
10. `scripts/*`
11. `tests/*`
12. `scripts/local_workflow_check.py`
13. optional `.github/workflows/*` wrappers, when the repo uses GitHub Actions

For script/workflow changes, also update and enforce the script install-scope
policy in `templates/script-install-scope.json`. Downstream repos must not
receive a copied PRD Plugin `scripts/` directory by default; only helpers marked
`downstream_runtime` or `downstream_optional` may be explicitly installed in a
target repo. Keep `hub_runtime` and `plugin_development` scripts in the PRD
Plugin hub/development repo or plugin bundle.

For changes that affect skill behavior, also update the repo-local skill install
surfaces under `templates/repo-skeleton/.agents/skills/` (Codex discovery) and
`templates/repo-skeleton/.opencode/skill/` (opencode discovery). Host agents
discover repo-local skills from their respective paths; `.prd_plugin/` stores
method state and templates, but does not make skills available by itself.

## Goal Handling

- Treat plain "fold it in" as goal-backed work by default.
- If no active goal exists, create one with the concrete integration
  objective before editing.
- If an active goal exists, ensure the fold-it-in work matches it; if it does
  not, report the mismatch before proceeding.
- Keep the progress plan in sync with the goal during analysis,
  implementation, verification, and closeout.
- Before final closeout, confirm whether the goal is complete, blocked, or
  still active. Mark it complete only after verification has passed and no
  required work remains.

## Companion Update Rules

- Skill changes should update related docs or templates unless no repo-facing
  behavior changed.
- Template or state changes should update config, skeleton state, docs, and
  validation scripts when relevant.
- ID changes should update `docs/ID-SCHEME.md`, config required prefixes, live
  registry, and skeleton registry.
- Request/issue intake changes should update request templates, request report,
  request-intake skill, health checks, traceability checks, privacy validation,
  upstream export behavior, and request-thread message shape.
- Health changes should update health template, health skill, traceability
  review, and request/session close guidance.
- Script/workflow changes should add or update tests.
- Script/workflow changes that add, remove, rename, or re-scope helper scripts
  should update `templates/script-install-scope.json`, the repo-skeleton copy,
  docs, and release hygiene checks.
- Version/release behavior changes should update release metadata, version
  advice docs, config paths, templates, workflow coverage, and tests.
- Before a plugin version bump, run
  `python scripts/gap_audit.py --target-version <new-version>` and fold in any
  findings before editing `.codex-plugin/plugin.json` and `.opencode/plugin.json`.

## Verification Checklist

Run the relevant checks, and prefer all of these for plugin-wide changes:

1. Local workflow check: `python scripts/local_workflow_check.py`.
2. Unit tests: `python -m unittest discover -s tests -v`.
3. JSON parse check for all `*.json`.
4. JSONL line parse check for all `*.jsonl`.
5. Skill validation for every `skills/*` folder.
6. Request report: `python scripts/request_report.py --config .prd_plugin/config.json --format json --output request-report/request-report.json`.
7. PRD doctor: `python scripts/prd_doctor.py --repo-root . --format json --output request-report/prd-doctor.json`.
8. Repo-local skill installer dry run: `python scripts/prd_install_skills.py --repo-root . --target-agent both --dry-run`.
9. Gap audit before a version bump: `python scripts/gap_audit.py --target-version <new-version> --no-fail`.
10. Release hygiene: `python scripts/release_check.py --output request-report/release-hygiene.md --no-fail`.

Remove generated `request-report/` artifacts after local verification.

## Closeout

Report:

1. What changed.
2. Which companion artifacts were updated.
3. Whether the plugin version was bumped.
4. Which validation commands ran.
5. Any remaining `REQ-*` or `HLT-*` items.
6. Goal status for the fold-it-in work.