--- name: project-memory description: Use when creating, reviewing, promoting, or updating PRD Plugin project memory files including `.prd_plugin/state` JSON/JSONL files, `.prd_plugin/ids/registry.json`, tracking records, changelog records, decisions, health findings, session records, agent IDs, session IDs, provenance, and promotion rules. --- # Project Memory Use this skill to maintain agent-first project memory and tracking state. ## Rules - Use JSON for snapshots and indexes. - Use JSONL for append-only event or promoted session streams. - Read `.prd_plugin/config.json` when present before assuming default state, local, registry, request, or health paths. - Follow `privacy.*` config. Request/message state is repo-scoped; do not read, index, or promote another repo's requests/messages unless there is an explicit upstream submission or export/import. - Store committed shared state under `.prd_plugin/state/`. - Mirror durable IDs in `.prd_plugin/ids/registry.json` when present. - Store raw session state under `.prd_plugin/local/`; it should be ignored by git. - Exclude `.prd_plugin/local/` from indexing and upstream submission. - Keep automation locks and pending markers under `.prd_plugin/local/automation/`; they are runtime coordination state, not committed project memory. - Use `.prd_plugin/outbox/`, `.prd_plugin/inbox/`, and `.prd_plugin/mailboxes/` as scoped request transport surfaces, not as canonical project truth. - Promote only concise, source-backed, non-sensitive records into committed state. - Include `AGENT-*`, `SES-*`, timestamps, status, confidence, and source references on promoted session-derived records. - Run the selective-promote guardrail before writing new `MEM-*` records to `.prd_plugin/state/memory.json`. When `memory.promotion_policy` is `selective`, candidates must meet `selective_min_confidence` (default `high`) and have at least `selective_min_evidence_count` source references (default `2`); rejected candidates stay in the local session log and are not promoted. When the policy is `all` (default), the guardrail still flags stale candidates older than `weekly_gc_stale_after_days` (default `90`) for the weekly GC pass. Use `python scripts/prd_selective_promote.py --repo-root . --format markdown` to print the rollup. - Treat JSON memory as an operational index, not a replacement for PRDs, architecture docs, implementation plans, or evidence. - Own state-schema changes here: when a `.prd_plugin/state/*.json` shape needs a new/renamed field, bump that file's `schema_version`, keep readers tolerant of older records (default missing fields), and record the change as a `CHG-*` so downstream repos know to migrate. Do not silently change a state schema. ## MCP State Tools (preferred write path) When the repo's `.mcp.json` wires the `prd-plugin` MCP server, use its tools instead of hand-editing state JSON — they stamp timestamps server-side, allocate IDs atomically from the registry, schema-validate records, and write minimal diffs. Hand edits are how counters drift and future timestamps land: - `prd_find` / `prd_get` — discover bounded state or load one exact record, including promoted `MEM-*` records - `prd_create` / `prd_update` — manage ordinary TRK/REQ/HLT state; record-backed IDs are allocated inside creation and never computed by agents - `prd_link` — link supported record-backed state, including `MEM-*`; memory remains non-mutable through the generic update tool - `prd_next_id` — allocate only embedded planning IDs such as `PRD-REQ-*`, `ARCH-*`, or `IMP-TASK-*` - `prd_open_goal` / `prd_update_goal` / `prd_close_goal` — TRK lifecycle - `prd_file_request` — REQ intake; `prd_record_evidence` — EV (+ optional markdown under docs/evidence/); `prd_record_decision` — DEC; `prd_log_change` — CHG - `prd_status` / `prd_validate` — read state, pre-flight the commit gate Fall back to careful hand edits only when the server is unavailable — the commit gate still checks the result either way. For parallel tracking, the lead uses `prd_open_tracking_branch` before fan-out, each worker uses `prd_update_tracking_branch` only on its assigned `.prd_plugin/state/tracking-branches/DBR-*.json`, and the lead serially applies merged deltas with `prd_promote_tracking_branch`. Workers never allocate canonical IDs or edit shared tracking files. Launch each worker with `PRD_WORKER_SESSION=1`, `PRD_TRACKING_BRANCH_ID=`, and `PRD_TRACKING_BRANCH_OWNER=` so the runtime enforces that boundary. ## Staleness Coverage Apply the shared policy in `.prd_plugin/method/staleness-rules.md`. Before promoting or updating memory, inspect related `MEM-*`, `TRK-*`, `CHG-*`, `REQ-*`, and `HLT-*` records for stale timestamps or stale source claims. Do not refresh a stale record by rewriting it without evidence; update status, supersede it, or add an explicit health finding. ## Recommended Files Committed: - `.prd_plugin/ids/registry.json` - `.prd_plugin/state/project.json` - `.prd_plugin/state/memory.json` - `.prd_plugin/state/decisions.json` - `.prd_plugin/state/changelog.json` - `.prd_plugin/state/tracking.json` - `.prd_plugin/state/requests.json` - `.prd_plugin/state/health.json` - `.prd_plugin/state/sessions/shared/promoted-session-summaries.jsonl` - `.prd_plugin/state/tracking-branches/DBR-*.json` (one assigned writer per branch; canonical promotion remains lead-owned) Local: - `.prd_plugin/local/sessions//session.json` - `.prd_plugin/local/sessions//events.jsonl` - `.prd_plugin/local/sessions//scratch.json` - `.prd_plugin/local/sessions//handoff.json` - `.prd_plugin/local/automation/.lock.json` - `.prd_plugin/local/automation/.pending.json` ## IDs - `AGENT-###` for agent identities or profiles. - `SES-###` for agent sessions. - `MEM-###` for promoted memory records. - `OBS-###` for local or promoted observations. - `TRK-###` for tracking records. Set a `type`: `goal` for an overall objective you are driving to completion, or `active_work` for a sub-task. An open (`status: active`) `goal`/`active_work` record is what the autonomous Stop guard (`prd_stop_guard.py`) keeps working toward, so open one at the start of a goal and mark it `complete` when done. - `CHG-###` for changelog records. - `REQ-###` for request intake records. - `MSG-###` for request-thread messages and replies. - `HLT-###` for project health findings. - Use readable labels such as `codex-main` or `2026-06-13T090400Z-codex-main` in label fields, not as the traceability IDs. - Prefer the traceability chain: `AGENT-* -> SES-* -> OBS-* -> MEM-* -> TRK-* / CHG-* / EV-*`. - Use `HLT-*` findings to flag weak or stale parts of the graph, not as a replacement for source artifacts. - Use `REQ-*` records for proposed external changes before they become accepted tracked work. - Use `MSG-*` records only inside a `REQ-*` thread; keep repo-local/private messages out of upstream submissions unless explicitly sanitized. - Pull only the mailbox for the current repo, and merge messages without removing local-only messages. ## Promotion Checklist Before promoting local session memory to committed project memory, verify: 1. The record is useful to future agents. 2. The record is backed by source files, artifact IDs, command output, or evidence. 3. The record contains no secrets, credentials, private prompts, or raw reasoning traces. 4. The record includes `created_by_agent`, `created_from_session`, and `source_refs`, where agent and session values use `AGENT-*` and `SES-*`. 5. The target JSON or JSONL remains valid after the update. 6. New durable IDs are mirrored in `.prd_plugin/ids/registry.json` when that registry exists. ## Output Shape When summarizing memory changes, include: 1. Updated files. 2. New or changed IDs. 3. Sources used. 4. Any records kept local rather than promoted.