| name | archive-legacy-docs |
| description | Normalize legacy repositories by moving scattered documentation into docs-legacy/ (git-aware) and generating a docs-legacy/summary.md before generating new docs/plans. |
| license | MIT |
| compatibility | {"opencode":">=0.1"} |
| metadata | {"category":"hygiene","phase":"pre-docs"} |
Skill: Archive Legacy Docs
This skill prepares a clean, defined repository state before running generate-docs / create-plan on legacy repositories.
It collects existing documentation artifacts that are scattered/historical, moves them into a single archive directory docs-legacy/, and generates a lightweight index docs-legacy/summary.md.
The archived content is intended to be forensic reference, not canonical documentation.
When to Use
Use this skill when:
- You are onboarding a legacy repo and documentation/plan artifacts are scattered.
- You want
docs/ and plans/ to start from a clean slate.
Do not use this skill when:
docs/ and plans/ already follow this framework’s conventions and should be preserved.
Routing Matrix (Who does what)
- Writes:
docs-legacy/** (including docs-legacy/summary.md).
- Moves: legacy doc files from anywhere in the repo into
docs-legacy/.
- Primary: chooses/approves inclusion & exclusion policy (what counts as legacy docs).
- legacy-curator (subagent): performs git-aware moves and writes the summary.
- doc-explorer / implementer: not used.
Execution Model
Key semantics
- git-aware moves:
- If a file is tracked by git, move it with
git mv.
- If a file is untracked, move it with filesystem move.
- flat archive:
- All archived files end up directly under
docs-legacy/ (no path-preserving).
- Name conflicts are resolved by prefixing with the inferred module and adding a stable disambiguator.
Module inference (draft)
For each legacy document, infer a "module origin" label (best-effort):
- If path contains a top-level module directory (e.g.
backend/, frontend/, services/<name>/, packages/<name>/), use that.
- Else use the first directory segment (
<topdir>).
- Else use
root.
Workflow
0) Primary inputs
Primary should provide:
- inclusion patterns (defaults suggested below)
- exclusion patterns (defaults suggested below)
- whether to treat existing
docs/ and plans/ as legacy (default: yes unless they match this framework)
1) Discover candidate legacy docs
legacy-curator:
- Collect candidate files (typical):
**/*.md, **/*.rst, **/*.adoc, **/*.txt.
- Exclude common non-doc files:
README*, LICENSE*, CHANGELOG*, CONTRIBUTING*, .github/**.
- Exclude build/vendor dirs:
node_modules/**, dist/**, build/**, target/**, .venv/**, venv/**.
- Exclude already-archived:
docs-legacy/**.
Special case:
- If
docs/ or plans/ exist but do not match this framework’s structure, treat them as legacy and include their files.
2) Plan the archive mapping (in-memory)
For each candidate file, compute:
original_pathmodule_origin (draft inference)archive_name (flat):
- base:
<module_origin>--<original_basename>
- if collision: append
--<short-hash> or --<n>
archive_path: docs-legacy/<archive_name>
3) Execute moves (git-aware)
- Create
docs-legacy/ if missing.
- For each file:
- If tracked:
git mv <original> <archive>
- Else:
mv <original> <archive>
Do not commit.
4) Generate docs-legacy/summary.md
Create docs-legacy/summary.md using tpl-legacy-summary.md.
For each archived file, include:
- archive path
- original path
- inferred module origin
- type (doc/plan/spec/notes/adr/unknown; best-effort)
- last modified (draft): from
git log -1 --format=%cs -- <file> if available, else unknown
- time bucket (draft):
recent / stale / historic / unknown
- 3-sentence summary (best-effort; if non-text or unreadable → state that)
Defaults (recommended)
Include
**/*.md**/*.rst**/*.adoc**/*.txt
Exclude
docs-legacy/**.git/**.github/**node_modules/**, dist/**, build/**, target/**venv/**, .venv/**README*, LICENSE*, CHANGELOG*, CONTRIBUTING*
Templates
tpl-archive-legacy-docs-prompt.md — Primary → legacy-curator delegation prompttpl-legacy-summary.md — canonical format for docs-legacy/summary.md
