plan-archive
Automates the organization, linking, and archival of development plan documents in the Librefolio project structure.
Install
mkdir -p .claude/skills/plan-archive && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/10303" && unzip -o skill.zip -d .claude/skills/plan-archive && rm skill.zipInstalls to .claude/skills/plan-archive
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Use this skill when the user needs to verify, cross-link, or archive development plans. Covers plan naming conventions, cross-linking between plans, archiving completed plan chains into phases/, and updating README indexes.Key capabilities
- →Verify plan naming
- →Cross-link plans
- →Archive completed chains
- →Update README indexes
How it works
It verifies naming conventions and cross-links before moving plans to the archive directory.
Inputs & outputs
When to use plan-archive
- →Verify plan naming before archiving
- →Link a bugfix plan to an original project plan
- →Update README index after finishing a project phase
- →Archive a completed chain of development plans
About this skill
Plan Archive Skill
Verification and archiving of development plans in the developer journal.
Where the journal is
The journal is its own local Git repository, beside the main checkout: ../LibreFolio_developer_journal/. It has no
remote and is not part of the public repository. From a worktree, reach it with:
J="$(git rev-parse --path-format=absolute --git-common-dir)/../../LibreFolio_developer_journal"
- Every
git mv,git addandgit commitof an archive runs inside the journal (git -C "$J" …), onmain, by explicit path. Never in the code repository. - In coordinated work only the coordinator commits there; a workstream writes its own files and never runs Git in it.
- Record
git rev-parse --short HEADandgit status --porcelainbefore; verify both after, and report the SHAs. - Links from the journal to the code no longer resolve (the journal used to live inside the code repo): about a
thousand old relative links are broken and stay so. Cite code as
path:lineand a commit hash, not as a link.
Layout (Release_2 onwards)
Release_N/
├── Phase_K/ # ACTIVE: the release in progress (Phase_1 = 1.3, Phase_2 = 1.4, …)
│ ├── README.md # live state of the release
│ ├── plan-phaseKK<Release>.prompt.md
│ ├── 00_coordination/ # coordinator papers: kickoff, briefs, plans, recaps, testlists
│ │ └── ondataN/ # one folder per wave
│ └── NN_<theme>/ # one folder per theme / workstream
│ ├── plan-phaseKK<Theme>.prompt.md
│ └── notes/ # kickoffs (ondataN-kickoff-X.md), checkpoints, analyses
├── Phase_0/BACKLOG_POST_x.y.md # single backlog index, one line per item, dated sign lines
├── Phase_{K+1}/ATTIVITA_INIZIO_<next>.md # what the next release starts with
├── Phase_{K+1}/RESIDUO_CLOUD.md # what only the managed service needs
└── phases/ # ARCHIVE: original folder names, never renamed
├── 00-index.md # master index: one table row per archived folder
├── NN_<stream>/ # archived Phase_0 streams (flat)
└── Phase_K/NN_<theme>/ # archived folders of a release phase
RoadmapV4_UI/ and older roadmaps are history: same idea, with phases/phase-NN-subplan/ and plan files grouped by
step. Do not reorganise them.
Plans: naming and cross-links
| Pattern | Use |
|---|---|
plan-phase{NN}{Description}.prompt.md | main plan |
plan-phase{NN}Step{N}{Description}.prompt.md | step plan |
plan-phase{NN}Step{N}Round{N}-{Description}.prompt.md | bugfix round N |
plan-phase{NN}Step{N}Round{N}{Suffix}.prompt.md | sub-iteration |
A follow-up plan links back at the top (← Previous: [file](path)), the original links forward at the bottom
(→ Follow-up: [file](path)).
1. Bring loose notes in
A release leaves working files outside the journal: in LibreFolio_prj/ and in salvataggi-worktrees-*/<wave>/.
- Only ours. Other coordinators (managed service, business plan) leave notes in the same places. A file wholly about
them stays out. In a mixed file, remove the lines about the managed service: fleet, storage, the founder, customers,
plans and prices. Replace a removed block with one placeholder line. A plain pointer like "the cloud coordinator is
told" may stay. Scan with
grep -i -E 'librefolio-cloud|\bfly\b|\bR2\b|\blfc\b|fondatore|clienti|flotta|polar|brevo'. - Destination. Coordinator files go to
00_coordination/ondataN/. Workstream kickoffs go to<theme>/notes/ondataN-kickoff-<X>.md, and checkpoints and analyses go to<theme>/notes/. The workstream letter decides the theme. When the destination already holds a file with that name, compare the two first: the journal copy may be an edited (sanitised) version. - Only Markdown. Logs, test data,
.diff/.tarsalvage bundles and helper scripts never go into the journal. Report them to the developer with their size; they decide whether to keep, compress or delete them. - Live files stay where the work uses them until the release is tagged: the release closing list, the open testlist, issue reply drafts, anything a running gate writes into.
- Add the new files to the coordination README index, then commit in the journal.
2. Verify before archiving
A plan's own ✅ is not proof. For every folder, list what its plan or README leaves open, then check the code at the release head. Give each item one verdict:
| Verdict | Proof |
|---|---|
| FATTO | file:line, or a commit that is an ancestor of HEAD (git merge-base --is-ancestor) |
| OBSOLETO | superseded, removed, or decided otherwise: cite where |
| GIÀ TRACCIATO | the line in ATTIVITA_INIZIO_*.md, RESIDUO_CLOUD.md or TODO_FUTURI.md |
| APERTO | what is missing, in one line |
- Read the backlog index too: each item has dated sign lines under it (✅ closed, ⏭️ next release, ✖️ discarded, ⏳ waiting, 🌊 to do, 🌐 translation debt). The last line is the item's state.
- Many folders: fan out read-only
Exploresubagents, one per group of folders, with the paths and the verdict table above. Subagents write nothing; the coordinator collects. Keep/tmpin mind: it is a RAM disk, and a full one silently kills every shell, the agents' too. - Sign every closure found in the backlog: one line under the item, at its end, in the section's format:
✅ DD/MM (verifica per l'archivio): in dev con \<hash>`. The same id can exist in two sections (B6of Risk,B6` of I): match the item, not the string, and check each line lands under the right one.
3. Archive
A folder moves only when nothing is APERTO. A whole phase moves as phases/Phase_K/ once every folder of it has.
- Stamp each plan of the folder under its title:
> ✅ **Verificato sul codice e archiviato il DD/MM/YYYY** (\<branch>` = `<hash>`): …`. - Move with Git, inside the journal, so history follows:
For many moves, write a script in the scratchpad (orgit -C "$J" mv Release_2/Phase_0/41_brokerPnlFlows Release_2/phases/41_brokerPnlFlows git -C "$J" mv Release_2/Phase_1/08_email Release_2/phases/Phase_1/08_email/tmp/libreFolio_archive_<x>.sh) and run it. - Fix the relative links of the whole journal with the helper next to this file. It resolves each link from where the
file was, maps it through the moves, and rewrites it from where the file is now. Links that were already broken
are listed and left alone: their count must not grow.
Paths written in backticks are text, not links: the helper does not touch them. Grep for the old path afterwards.python3 .claude/skills/plan-archive/fix_links.py --journal "$J" \ --moved Release_2/Phase_1/08_email=Release_2/phases/Phase_1/08_email [--moved …] [--dry-run] - Update
phases/00-index.md: one table row per archived folder (what it was, the outcome with a commit, the date), and remove its bullet from «Not archived». - Commit in the journal by explicit path, one commit per step (notes in, backlog signs, the move).
4. Residues
What stays APERTO is not decided by the archiver. Write it into one file in the next phase
(Phase_{K+1}/DA-DECIDERE-residui-<release>.md): folder, item, what is missing, a proposal. Proposals are 1.4
(a line in ATTIVITA_INIZIO_*), cloud (RESIDUO_CLOUD.md), futuro (TODO_FUTURI.md) or scarta. Once the
developer has answered, move each item to its home, sign it in the backlog, and archive the folders that are now
clean.
When not to use it
- →Active development plans
- →Projects without plan archives
Prerequisites
Limitations
- →Requires git mv
- →Requires specific naming convention
How it compares
It enforces strict archiving and cross-linking rules for developer journals.
Compared to similar skills
plan-archive side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| plan-archive (this skill) | 0 | 6mo | Review | Intermediate |
| ideate | 1 | 10mo | No flags | Beginner |
| truthmark-structure | 0 | 5mo | No flags | Advanced |
| ml-paper-writing | 48 | 9mo | Review | Advanced |
Try saying
Example prompts that trigger this skill in your AI assistant.
You might also like
ideate
liveloveapp
Capture and document a new idea in this repo. Use when the user says things like "help me brainstorm", "I have an idea", or "let's capture this for the future" and wants it recorded in `design/ideas/` with a summary, supporting research (repo context + web if useful), and a sketch.
truthmark-structure
merlinhu1
Use when routing or truth ownership is missing, stale, broad, overloaded, catch-all, unrouteable, mixed-owner, needs split/repair, or needs new area setup. Not for documenting implemented behavior, syncing a code diff, or realizing docs into code.
ml-paper-writing
davila7
Write publication-ready ML/AI papers for NeurIPS, ICML, ICLR, ACL, AAAI, COLM. Use when drafting papers from research repos, structuring arguments, verifying citations, or preparing camera-ready submissions. Includes LaTeX templates, reviewer guidelines, and citation verification workflows.
docs-review
metabase
Review documentation changes for compliance with the Metabase writing style guide. Use when reviewing pull requests, files, or diffs containing documentation markdown files.
claude-md-improver
anthropics
Audit and improve CLAUDE.md files in repositories. Use when user asks to check, audit, update, improve, or fix CLAUDE.md files. Scans for all CLAUDE.md files, evaluates quality against templates, outputs quality report, then makes targeted updates. Also use when the user mentions "CLAUDE.md maintenance" or "project memory optimization".
markdown-to-html
github
Convert Markdown files to HTML similar to `marked.js`, `pandoc`, `gomarkdown/markdown`, or similar tools; or writing custom script to convert markdown to html and/or working on web template systems like `jekyll/jekyll`, `gohugoio/hugo`, or similar web templating systems that utilize markdown documents, converting them to html. Use when asked to "convert markdown to html", "transform md to html", "render markdown", "generate html from markdown", or when working with .md files and/or web a templating system that converts markdown to HTML output. Supports CLI and Node.js workflows with GFM, CommonMark, and standard Markdown flavors.