archive-roadmap

Archive completed OpenSpec roadmap workspaces into date-prefixed directories.

Updated Apr 12, 2026

Search Tags:#maintenance #roadmap #archiving #openspec #workspace management #status validation #filesystem move

Ready to run

npx skills add https://github.com/jankneumann/agentic-assistant --skill archive-roadmap

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: archive-roadmap
Source: https://github.com/jankneumann/agentic-assistant/tree/main/.agents/skills/archive-roadmap
Command: npx skills add https://github.com/jankneumann/agentic-assistant --skill archive-roadmap

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires shutil, and includes scripts (resource) components.

What problem does it solve?

This Skill archives a completed OpenSpec roadmap workspace so its full history is preserved, while preventing accidental archiving of in-progress work.

Core Features & Use Cases

Completion-aware archiving: moves openspec/roadmaps/<roadmap-id>/ into openspec/roadmaps/archive/<date>-<roadmap-id>/ only when all item statuses are terminal (completed or skipped), unless force is used.
Collision protection: refuses to overwrite an existing archive entry at the same computed destination.
Full workspace preservation: keeps the entire workspace tree intact, including proposal.md, roadmap.yaml, checkpoint.json, and learnings/, so the audit trail remains available.

Quick Start

Ask the assistant to archive roadmap roadmap-id by running the archive-roadmap action with that roadmap identifier.

Frequently Asked Questions about archive-roadmap

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I archive a completed OpenSpec roadmap workspace?▼

To archive an OpenSpec roadmap, run the archive-roadmap action with the target roadmap identifier. It moves the roadmap directory into a date-prefixed archive folder, verifying all item statuses are terminal first.

Can I archive an in-progress OpenSpec roadmap that has pending tasks?▼

You cannot archive an in-progress roadmap without overriding the status validation. The archive command requires all items to have a terminal status of completed or skipped, unless you explicitly use the force option.

What files are preserved when archiving an OpenSpec roadmap directory tree?▼

Archiving preserves the full workspace tree, including proposal.md, roadmap.yaml, checkpoint.json, and learnings. The atomic filesystem move keeps the entire directory structure intact for audit purposes.

Why does my roadmap archive command fail with a destination collision?▼

The archive command fails on destination collision to prevent overwriting existing archive entries. It detects if a date-prefixed archive folder already exists at the computed destination path and refuses to proceed.

Does the archive-roadmap script require Python dependencies?▼

The script requires the shutil Python module to perform the atomic filesystem move. It uses this standard library component to safely relocate the entire roadmap workspace directory tree into the archive.

What is the best way to maintain a durable history of completed OpenSpec roadmaps?▼

The best way is to archive completed roadmaps using a date-prefixed folder structure. This ensures a durable, chronological archive of the full workspace contents while preventing accidental overwrites of previous archive entries.