Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Other skills

archive-plan

Retires a finished plan document: establishes from artifacts what actually shipped, files it under plans/archive/ with that record, and decides whether its procedure is worth generalising.

gsarig · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add gsarig/skills --skill archive-plan

About this skill


name: archive-plan description: "Retires a finished plan document: establishes from artifacts what actually shipped, files it under plans/archive/ with that record, and decides whether its procedure is worth generalising." when_to_use: "Use when the user asks to archive, retire or file a plan that is finished: 'archive this plan', 'retire the security-hardening plan', 'this plan is done, file it away', '/archive-plan '. Do NOT use to write or revise a plan (that is plan mode), on a plan still being worked, or to build a script or skill out of a procedure. Follow all steps in order; do not shortcut based on this description." argument-hint: "[path to the plan, or its name]" effort: high disable-model-invocation: true

Critical: never trust the plan's own status line

A finished plan almost always still claims to be a draft. Nobody goes back to edit the header on the way out. In the repo this skill was written for, four of five plans said "Not implemented" or "draft" while their deliverables were demonstrably live.

The status line is therefore the thing being corrected, never the thing being read to decide. Establish what shipped from artifacts, and treat the header as unverified prose until you have.

The corollary matters just as much: do not replace a stale claim with a fresh unverified one. A confident "shipped, 2026-08-25" written after checking two of six deliverables is the same failure with a newer date. Step 2 exists to make that impossible.

Steps

1. Find the plan and read it

If an argument was given, resolve it. If not, search in this order and stop at the first directory that holds a plan-shaped document: plans/ (excluding archive/), then tmp/, docs/, then the project root. Match *plan*.md first, then any Markdown file whose opening lines read as a plan.

A document merely titled as a plan is not automatically a candidate. docs/ in particular tends to hold design write-ups whose heading says "implementation plan" but which are kept as standing reference, to be read rather than retired. The test is whether anyone is still meant to act on it.

Name the file you settled on and confirm it is the right one before going further. If several match, list them and ask.

Read it in full. List every deliverable it names: files it said it would create, configuration it said it would apply, decisions it said it would record, records it said it would update.

2. Establish what actually shipped

This step is not optional and cannot be sampled. Build one row per deliverable from step 1, and check each against a real artifact:

DeliverableArtifact checkedResult
A script the plan said it would addfile present at the stated path, and wired into its callerpresent
A dependency the plan said it would removeno match in any manifest, lockfile or configpresent
A setting the plan said it would switch on in productionno evidence found either waycould not verify

Rules for the table:

  • Every deliverable gets a row. A plan with six work sections gets at least six rows, not two.
  • Result is one of present, absent, or could not verify. The last is a real answer and must be recorded, never rounded up to present.
  • The Artifact checked column names what you actually looked at. "Seems done" is not an artifact.
  • A blanket "shipped" is forbidden unless every row says present. If any row does not, the plan is partial and must be reported as partial, naming the specific rows.

Then classify the plan's state:

  • Shipped: every row present. Continue to step 3.
  • Partially shipped: some rows absent or could not verify. Report exactly which, and ask whether to archive it as partial (recording the gaps) or leave it live. Do not decide this alone.
  • Abandoned or superseded: it will not ship, because the approach was dropped or a later plan replaced it. Confirm this with the user rather than inferring it from absent artifacts, then continue to step 3.
  • Nothing shipped and still intended: the plan is live. Say so and stop. Do not archive it.

3. Triage to a disposition

Exactly one:

DispositionTest
Archive onlyThe work does not repeat. It changed one system once.
Generalised alreadyThe reusable form shipped as something executable: provisioning code, a template, a script, a skill. Find it and record where.
Abandoned or supersededIt will not ship. Record why, and point at whatever replaced it if anything did.
Warrants a playbookIt repeats on a new target, and the repeating part is judgement rather than commands.

The discriminator between "generalised already" and "warrants a playbook" is the one that matters: if the repeatable part is commands, it wants a script or a skill, not a playbook. A playbook is for a procedure whose value is its decisions and its traps, which no script can carry.

A plan that never ran cannot warrant a playbook. Everything that makes a playbook worth having comes from what went wrong in execution, so abstracting an unexecuted draft yields only the plan with its specifics deleted.

4. Propose, and stop

This step is not optional. Present, and wait for approval:

  • the evidence table from step 2, in full, including any could not verify rows
  • the plan's state and the disposition, with the reasoning
  • the exact file moves and reference edits that will follow

Move nothing before the user answers.

5. Archive (on approval)

In this order:

  1. Create plans/ and plans/archive/ in the project if absent. Do not create plans/playbooks/ unless step 6 runs.
  2. Move the plan with git mv, or plain mv outside a repository. Confirm it landed before going further: the file is readable at its new path, and nothing remains at the old one. If either check fails, stop here. Repointing references at a file that never moved is worse than not having started. 3
Read the complete source ↗