Automate cleanup of completed issue specs in docs/issues with a non-interactive script

[josecelano]

Summary

Create an automation script for the skill at .github/skills/dev/planning/cleanup-completed-issues/SKILL.md to reduce manual work and mistakes when cleaning completed issues.

The script should support the two-stage lifecycle already documented:

1. Stage 1: move closed issue specs from docs/issues/open/ to docs/issues/closed/
2. Stage 2: delete old specs from docs/issues/closed/ only when no longer referenced

Motivation

The current process is repetitive and easy to get wrong in batch operations.
Automating it would make maintenance faster and safer while keeping behavior aligned with the skill.

Proposed scope (phase 1)

Implement a script for Stage 1 archive with a strict, agent-friendly interface:

• Non-interactive CLI only (no prompts)
• Verify issue state on GitHub before moving
• Support dry run by default
• Support apply mode for real changes
• Produce structured JSON on stdout
• Send diagnostics to stderr
• Return meaningful non-zero exit codes on failure

Suggested flags:

• --issues 1042,1178,...
• --all-closed-in-open (optional)
• --dry-run (default)
• --apply
• --json

Proposed scope (phase 2)

Add Stage 2 delete with stronger safeguards:

• Check references before delete (filename and issue references in docs)
• Refuse deletion if references are found unless explicit override is provided
• Keep --dry-run default and require explicit confirmation flag for destructive actions

Acceptance criteria

• Script is added under the cleanup skill folder (for example scripts/)
• SKILL.md documents the script(s), usage, examples, and prerequisites
• Stage 1 move flow is fully automated and idempotent
• Script never blocks on interactive input
• Output is parseable JSON for results; diagnostics are separate
• Dry-run behavior is default
• Errors are explicit and actionable (invalid issue, open issue, missing file, ambiguous file)
• Basic tests or fixture-based validation for key paths are included

Notes

Reference guidance used for script design:

• https://agentskills.io/skill-creation/using-scripts

Key recommendations to follow:

• avoid interactive prompts
• provide clear --help
• use structured output
• separate stdout data from stderr diagnostics
• use safe defaults (--dry-run)
• support idempotent retries