archive

Imported from kirkchen/beat (skills/archive/SKILL.md). Install upstream with npx skills add kirkchen/beat --skill archive. Copyright stays with the author.

Archive a completed change. Checks completion, syncs features to living documentation, then moves to archive.

<decision_boundary>

Use for:

• Archiving a completed (or verified distilled) change
• Syncing features into beat/features/ living documentation
• Final living-doc sweeps (glossary terms, last-mile ADR) before archiving

NOT for:

• Verifying implementation against spec (use /beat:verify)
• Implementing remaining tasks (use /beat:apply)
• Creating or modifying spec artifacts (use /beat:design)

Trigger examples:

• "Archive the change" / "The change is done, wrap it up" / "Sync the features"
• Should NOT trigger: "verify the implementation" / "implement the change" / "design a feature"

</decision_boundary>

Prerequisites (invoke before proceeding)

If unavailable (skill not installed), skip and show archive summary only.

Rationalization Prevention

Red Flags — STOP if you catch yourself:

• Completing archive without invoking finishing-a-development-branch
• Skipping the sync step without checking if gherkin is done
• Moving to archive without asking user about capability mapping (when features exist)
• Completing archive while .feature.orig files remain in beat/features/
• Syncing features without first scanning for project-specific terms missing from beat/CONTEXT.md
• Archiving a change with zero ADRs without running the last-mile sweep prompt
• Archiving a change with no verification record (or status: issues-found) without confirming with the user

Process Flow

digraph archive {
    "Select change" [shape=box];
    "Check artifact completion" [shape=diamond];
    "Warn incomplete" [shape=box];
    "Check task completion" [shape=diamond];
    "Warn incomplete tasks" [shape=box];
    "Verification recorded?" [shape=diamond];
    "Warn unverified" [shape=box];
    "Gherkin done?" [shape=diamond];
    "Ask capability mapping" [shape=box];
    "Scan features for\nundefined terms" [shape=box, style=bold];
    "Sync features" [shape=box];
    "Skip sync" [shape=box];
    "Last-mile ADR sweep" [shape=box, style=bold];
    "Move to archive" [shape=box];
    "Show summary" [shape=box];
    "Invoke finishing-a-development-branch" [shape=doublecircle, style=bold];

    "Select change" -> "Check artifact completion";
    "Check artifact completion" -> "Warn incomplete" [label="pending found"];
    "Check artifact completion" -> "Check task completion" [label="all done/skipped"];
    "Warn incomplete" -> "Check task completion" [label="user confirms"];
    "Check task completion" -> "Warn incomplete tasks" [label="incomplete"];
    "Check task completion" -> "Verification recorded?" [label="all complete\nor no tasks"];
    "Warn incomplete tasks" -> "Verification recorded?" [label="user confirms"];
    "Verification recorded?" -> "Warn unverified" [label="absent or\nissues-found"];
    "Verification recorded?" -> "Gherkin done?" [label="passed"];
    "Warn unverified" -> "Gherkin done?" [label="user confirms"];
    "Gherkin done?" -> "Ask capability mapping" [label="done"];
    "Gherkin done?" -> "Skip sync" [label="skipped"];
    "Ask capability mapping" -> "Scan features for\nundefined terms";
    "Scan features for\nundefined terms" -> "Sync features";
    "Sync features" -> "Last-mile ADR sweep";
    "Skip sync" -> "Last-mile ADR sweep";
    "Last-mile ADR sweep" -> "Move to archive";
    "Move to archive" -> "Show summary";
    "Show summary" -> "Invoke finishing-a-development-branch";
}

Input: Optionally specify a change name. If omitted, infer from context or prompt.

Steps

1. Select the change

   If no name provided:

   • Look for beat/changes/ directories (excluding archive/)
   • If only one exists, use it
   • If multiple exist, use AskUserQuestion tool to let user select
   • Show only active (non-archived) changes

2. Check artifact completion

   Read beat/changes/<name>/status.yaml (schema: references/status-schema.md). Check which artifacts are done vs pending (not skipped).

   If any non-skipped artifacts are still pending:

   • Display warning listing incomplete artifacts
   • Use AskUserQuestion tool to confirm user wants to proceed
   • Proceed if user confirms

3. Check task completion (if tasks.md exists)

   Read tasks.md. Count - [ ] (incomplete) vs - [x] (complete).

   If incomplete tasks found:

   • Display warning: "N/M tasks incomplete"
   • Use AskUserQuestion tool to confirm
   • Proceed if user confirms

3b. Check verification ran (schema: references/status-schema.md)

Read the top-level verification field from status.yaml:

• Absent: warn "This change was never verified (/beat:verify has not run)." Use AskUserQuestion tool to confirm archiving anyway.
• status: issues-found: warn "Verification found N critical issue(s) on ." Use AskUserQuestion tool to confirm.
• status: passed: proceed silently.

Inform and confirm — never block.

4. Sync features to living documentation

   Check status.yaml:

   If gherkin status is skipped: Skip sync (no features to sync). Proceed to step 4b.

   If gherkin status is done:

   Read from beat/changes/<name>/:

   • features/*.feature (all Gherkin files)
   • proposal.md (if exists)
   • design.md (if exists)

   If no feature files exist: skip sync, proceed to step 4b.

   Read beat/config.yaml if it exists (schema: references/config-schema.md). Use language for README content language.

   Determine capability mapping:

   Use AskUserQuestion tool:

   "Where should each feature be synced? Existing capabilities: [list from beat/features/]. Or enter a new name."

   If only one feature file and the mapping is obvious from context, suggest a default.

   Scan features for undefined terms (Layer 1 living-doc enforcement):

   Read beat/CONTEXT.md if it exists (schema: references/context-format.md). The glossary is lazy — it may not exist yet if this is the project's first synced change.

   Scan the feature files being synced for bolded project-specific terms. For each term:

   • If it exists in beat/CONTEXT.md: OK, continue.
   • If it doesn't: use AskUserQuestion tool:

     "Term '' appears in scenarios but isn't in beat/CONTEXT.md. Add it now?"

     • Yes (recommended): provide a one-sentence definition; Beat appends it
     • Skip this term
     • Skip all remaining (record the count for the summary)

   When the user adds a term, append it to beat/CONTEXT.md following the structure in references/context-format.md (one-sentence definition, optional _Avoid_ aliases). Create beat/CONTEXT.md lazily if it doesn't exist.

   If no project-specific bolded terms appear in the scanned features, skip this sub-step silently.

   Sync files:

   If beat/features/ doesn't exist, create it: mkdir -p beat/features

   Source (change)	Target (beat/features/)	Behavior
   features/*.feature	beat/features/<capability>/	Add or update feature files
   proposal.md	beat/features/<capability>/proposal.md	Copy to capability
   design.md	beat/features/<capability>/design.md	Copy to capability

   When features map to multiple capabilities, copy proposal.md and design.md to the primary capability only (the one receiving the most feature files). On a tie, ask the user which capability owns them. Don't duplicate them across capabilities.

   Handle .orig backups (when status.yaml has gherkin.modified):

   For each path in gherkin.modified:

   1. The modified version is in changes/<name>/features/ — sync it to beat/features/<capability>/ (same as new features, unified flow)
   2. Delete the .feature.orig backup from beat/features/
   3. If the project uses pytest-bdd: update @scenario decorator paths in test files (from beat/changes/.../x.feature → beat/features/<capability>/x.feature)

   Verify no .feature.orig files remain in beat/features/ before proceeding.

   Create beat/features/<capability>/README.md if it doesn't exist (placeholder description). Create or update beat/features/README.md with global navigation.

   Update status.yaml phase to sync.

4b. Last-mile ADR sweep (Layer 2 living-doc enforcement)

Runs on every path — whether features were synced or sync was skipped.

Count ADR files written or referenced during this change:

• Check docs/adr/ for files created since this change started (git diff against the change's base commit)
• Scan design.md and tasks.md for docs/adr/NNNN- cross-references

If at least one ADR exists for this change: skip the sweep silently. Earlier triggers (in /beat:design, /beat:plan, /beat:apply) already caught the candidates.

If zero ADRs exist for this change: prompt once using AskUserQuestion tool:

"No ADRs recorded for this change. Was there any hard-to-reverse + surprising + real-trade-off decision worth recording before archiving?"

• No, none qualified
• Yes, let me describe it now

If user describes one, run the three-condition gate from references/adr-format.md. If all three hold, write the ADR under docs/adr/ with the next sequential number. If not all three hold, note the skip.

Either way, proceed to archive.

5. Perform the archive

   Update status.yaml: set phase to archive.

   mkdir -p beat/changes/archive

   Generate target name: YYYY-MM-DD-<change-name>

   Check if target already exists:

   • If yes: fail with error, suggest renaming
   • If no: move the directory

   mv beat/changes/<name> beat/changes/archive/YYYY-MM-DD-<name>

6. Show summary

   ## Archive Complete
   
   **Change:** <change-name>
   **Archived to:** beat/changes/archive/YYYY-MM-DD-<name>/
   **Verification:** passed / issues-found (N critical) / never run (user confirmed)
   **Features:** Synced to beat/features/ (or "Sync skipped" or "No features to sync")
   **Glossary:** N terms added to beat/CONTEXT.md (or "no changes" / "M terms skipped")
   **ADRs:** N written to docs/adr/ (or "none recorded — last-mile sweep declined")
   **Artifacts:** N done, M skipped
   **Tasks:** X/Y complete (or "No tasks file")
   

7. Finish the development branch

   After showing the summary, invoke superpowers:finishing-a-development-branch (if available) to guide the user through merge, PR creation, or cleanup. If not available, skip this step.

Guardrails

• Always prompt for change selection if not provided
• Don't block archive on warnings -- inform and confirm
• Sync features inline before archiving
• Show clear summary of what happened
• If archive target already exists, don't overwrite