Add AGENTS.md guidance that implementation plan docs are historical records

[fullsend-ai-retro]

What happened

PR #2761 migrated the retro harness from runner_env to env.runner/env.sandbox per ADR 0055, deleting env/retro.env. The review agent on PR #2761 flagged 6 stale references to retro.env in docs/superpowers/plans/2026-05-04-retro-agent.md as a low-severity [stale-reference] finding. The retro agent picked up this finding and filed issue #2939. The triage agent confirmed it, labeling it ready-to-code and good first issue. The code agent attempted a fix but failed. An external contributor (sreedhards) volunteered, spent time understanding the issue, and opened PR #2946. Maintainer ralphbean then closed both the issue and PR as unnecessary — historical plan docs are point-in-time records and don't need updating. This cascaded across 4+ agent runs and wasted a contributor's time.

What could go better

AGENTS.md has explicit immutability guidance for ADRs (lines 94-102) but no equivalent for implementation plan docs under docs/superpowers/plans/. These plan docs follow a similar lifecycle: they are point-in-time records of how features were designed and built, and become historical once the work is complete. Without this context, three agents in the chain (review, retro, triage) all treated stale references in a plan doc as an actionable issue. Confidence is high — the maintainer explicitly stated that updating historical plans is unnecessary, and the pattern mirrors the existing ADR immutability rule. The AGENTS.md gap is the clear root cause: agents had no way to know plan docs are historical.

Proposed change

Add a new section to AGENTS.md after the ADR section (around line 103) titled Implementation plans with guidance analogous to the ADR immutability rule. Suggested content:

## Implementation plans

Implementation plans (`docs/superpowers/plans/`) are point-in-time records of how features were designed and built. Like ADRs, they are historical — do not update them to track subsequent codebase changes. Stale file paths, deleted environment variables, and outdated code references in completed plans are expected artifacts, not bugs.

**When reviewing PRs:** Do not flag stale references in plan docs as findings. A PR that deletes a file referenced in a plan doc does not need to update the plan.

**When triaging issues:** Reject issues that propose updating completed plan docs to match current code. These are unnecessary maintenance.

This parallels the ADR immutability pattern already established in AGENTS.md and directly addresses review, retro, and triage agent behavior for this class of file.

Validation criteria

1. Grep AGENTS.md for 'Implementation plans' confirms the section exists.
2. Over the next 5 PRs that delete or rename files referenced in plan docs, verify the review agent does not flag stale plan-doc references.
3. If a retro agent files an issue about updating a plan doc, the triage agent rejects it rather than labeling it ready-to-code.
4. No further contributor time is wasted on plan-doc update issues.

---

Generated by retro agent from #2939

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 5:09 PM UTC · Completed 5:12 PM UTC
Commit: 0a95cac · View workflow run →

[fullsend-ai-triage]

Triage Summary

Severity: Medium · Category: Feature (new AGENTS.md guidance)

Problem

AGENTS.md has immutability guidance for ADRs but no equivalent for implementation plan docs under docs/superpowers/plans/. This gap caused a cascading failure: review → retro → triage → code agents all treated stale references in a completed plan doc as actionable, ultimately wasting an external contributor's time on a PR that was closed as unnecessary.

Root Cause

Agents read AGENTS.md for repo-specific conventions. Without a section establishing that plan docs are frozen historical records, agents have no way to distinguish expected staleness from actionable drift.

Recommended Fix

Add a section to AGENTS.md after the ADR section (~line 103) titled Implementation plans, mirroring the ADR immutability pattern. The issue body contains well-crafted suggested content covering review, triage, and general agent behavior.

Proposed Test

# Verify section exists after merge
grep -c 'Implementation plans' AGENTS.md  # should return 1

# Verify coverage of key agent roles
grep -A 20 '## Implementation plans' AGENTS.md | grep -c 'reviewing PRs'  # review guidance
grep -A 20 '## Implementation plans' AGENTS.md | grep -c 'triaging issues'  # triage guidance

Related Issues

• Duplicate: Add AGENTS.md guidance that plan docs are historical artifacts not requiring updates #2950 proposes the same AGENTS.md change (from the PR docs: remove stale retro.env references from retro agent plan #2946 retro)
• Complementary: Retro agent should apply a higher bar before filing issues from low-severity doc-only findings #2949 and Retro agent should not propose issues for cosmetic staleness in historical documents #2951 propose retro agent behavior changes as defense-in-depth
• Origin: Remove stale references to deleted env/retro.env in retro agent plan doc #2939 (the stale-reference issue, now closed) and PR docs: remove stale retro.env references from retro agent plan #2946 (the rejected fix)

---

Labels: Retro-filed documentation guidance issue affecting agent behavior, medium priority given demonstrated contributor impact.