Add plan-file-hygiene skill (addresses #1417) - #1479

Addresses #1417.

Credit where it's due: @halilxibrahim named the problem precisely (planning artifacts accumulate with no lifecycle), and @xg-gh-25's comment framed it as a lifecycle gap — this skill is built on that framing. @halilxibrahim, you mentioned wanting to take a first pass: happy to hand this off to you, fold it into your implementation, or iterate on it together — please treat this as a working draft toward your proposal, not a claim on it.

What this adds

skills/plan-file-hygiene/ — a single SKILL.md (plus bundled Apache-2.0 LICENSE.txt) with four rules and a reporting contract:

1. Discover before you create — search for existing PLAN*/NOTES*/TODO*/scratch* markdown and classify (current / superseded / stale / unrelated) before spawning a new file.
2. Merge, don't spawn; append, don't regenerate — update the existing plan via re-read-then-targeted-edit; never rewrite a shared plan file from session memory. Includes concrete "you are about to clobber" warning signs (writing without reading this turn; output smaller than the existing file).
3. One current plan; supersede explicitly — restructures replace the old plan with a dated supersede marker, never a PLAN-v2.md sibling.
4. Close the lifecycle — mark done + archive on completion, staleness sweep for cluttered directories, and never silently delete another writer's (or uncommitted) file.

Plus a required hygiene report, a worked example, and edge cases (concurrent writers, multi-task directories, ephemeral scratch).

Where it comes from

The rules are distilled from a production multi-writer setup (multiple agent sessions and humans sharing plan files). Repeated plan-file losses there were traced through file version history to exactly one habit — regenerating the whole plan from what the current session remembered, which silently deleted other writers' sections — not to sync races, which were the initial suspect. The discipline in this skill is the fix that eliminated that failure class; the "shrinking plan file is a red flag" heuristic comes straight from that forensics.

Testing

• Frontmatter validated against the agentskills.io spec constraints (name/dir match, charset, description length, body <500 lines).
• Followed literally by a separate agent session against a fixture directory (a current plan with open checkboxes, overlapping scratch notes from the same task, a month-old finished plan, and someone else's untracked TODO file). The resulting actions matched the intended decisions, including leaving the untracked file in place and flagging it in the report. The ambiguities that agent reported (which file wins when notes overlap the plan; shrink-warning vs. legitimate consolidation; targeted-edit vs. restructure threshold; act-vs-propose on archiving) were fixed in the text.
• Two adversarial review passes by a second, independent model; its findings (read-then-rewrite race caveat, ownership gate on deletion and superseding, supersede-marker ordering on interruption) are folded in.

Disclosure

Architecture, the underlying incident forensics, and validation are mine; the text was drafted in pair with Claude.