Upgrade a project's documentation structure to a newer version of the project-docs scaffold template
From project-docsnpx claudepluginhub ichabodcole/project-docs-scaffold-template --plugin project-docsThis skill uses the workspace's default tool permissions.
migrations/scripts/migrate-v2.0-to-v2.3.shmigrations/scripts/migrate-v2.3-to-v2.4.shmigrations/scripts/migrate-v2.4-to-v2.5.shmigrations/scripts/migrate-v2.5-to-v2.6.shmigrations/v1-to-v2.mdmigrations/v2.0-to-v2.3.mdmigrations/v2.3-to-v2.4.mdmigrations/v2.4-to-v2.5.mdmigrations/v2.5-to-v2.6.mdFetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
Retrieves current documentation, API references, and code examples for libraries, frameworks, SDKs, CLIs, and services via Context7 CLI. Ideal for API syntax, configs, migrations, and setup queries.
Uses ctx7 CLI to fetch current library docs, manage AI coding skills (install/search/generate), and configure Context7 MCP for AI editors.
Orchestrate the upgrade of a project's documentation structure when the project-docs scaffold template has released structural changes.
Activate when:
The docs structure version is tracked in docs/README.md frontmatter:
---
docs_version: "2.0.0" # x-release-please-version
docs_template: https://github.com/ichabodcole/project-docs-scaffold-template
---
This version is kept in sync with the scaffold template's package version by
release-please. The x-release-please-version annotation tells release-please
to update this line automatically when a new version is released.
How to read the version:
docs_version frontmatter → pre-2.0 (original flat structure)docs_version: "X.Y.Z" → matches the scaffold template release versionWhat triggers a version bump (with a migration guide):
backlog/, memories/)Not every version bump requires a migration. Minor and patch releases that don't change structure won't have a migration file — only major structural changes do.
What does NOT trigger a version bump:
Check the project's docs/README.md for the version marker:
grep "docs_version" docs/README.md
If no version marker exists, the project is on v1 (the original flat
structure with proposals/, plans/, sessions/).
Check the latest version available. The target is typically the version in the scaffold template you're upgrading to. Migration files in this skill document each version transition.
Look in this skill's migrations/ folder for each version step between current
and target. Migrations must be applied in sequence — you can't skip
versions.
Example: upgrading from v1 to v2.1 requires:
migrations/v1-to-v2.mdmigrations/v2.0-to-v2.1.md (if it exists)For each migration file:
migrations/scripts/ that handles mechanical steps. Run --dry-run first to
preview, then run without the flag. Only content-editing steps (flowchart
updates, README prose) remain for the agent.After all migrations are applied, update the version comment in docs/README.md
to reflect the new version.
Check whether the project's root-level CLAUDE.md or AGENTS.md references the
docs structure. Agents read these files first when entering a project — if
there's no pointer to docs/, agents have to discover the documentation on
their own.
grep -l "docs/README\|docs/memories\|documentation.*docs/" CLAUDE.md AGENTS.md 2>/dev/null
If neither file references the docs structure, recommend adding a section like this to whichever file the project uses for agent context:
## Documentation
This project uses structured documentation in `docs/`. See
[docs/README.md](./docs/README.md) for the full structure overview and document
type guide.
For quick onboarding on recent work, start with
[docs/memories/](./docs/memories/).
This is a recommendation, not a required step — the user may prefer to word it differently or place it in a different file. Present the blurb and ask where they'd like it.
Run a final check that no stale references to old structure remain:
# Check for references specific to the migration
# (each migration file lists what to grep for)
| Migration | From | To | Summary |
|---|---|---|---|
| migrations/v1-to-v2.md | pre-2.0 | 2.0.0 | Flat dirs → project folders, add backlog/memories/specifications/fragments/interaction-design/reports |
| migrations/v2.0-to-v2.3.md | 2.0–2.2 | 2.3.0 | Add design resolution and handoff templates, update READMEs with new pipeline stage |
| migrations/v2.3-to-v2.4.md | 2.3 | 2.4.0 | Add test plan template, external dependencies in DR template, update lifecycle across docs |
| migrations/v2.4-to-v2.5.md | 2.4 | 2.5.0 | Add briefs document type, update pipeline lifecycle to start with Brief |
| migrations/v2.5-to-v2.6.md | 2.5 | 2.6.0 | Rename archive/ → _archive/ for consistent sort-to-top behavior |
When the scaffold template releases structural changes:
migrations/vX-to-vY.mdmigration-authoring skill to ensure every step is agent-executabledocs/README.md is bumped automatically by release-pleaseMigration file structure:
# Migration: vX → vY
## Summary
[What changed and why]
## What's New
[New directories, files, or conventions]
## What Moved
[Files or directories that changed location]
## What's Removed
[Directories or files no longer used]
## Step-by-Step Migration
[Ordered steps to perform the upgrade]
## Cross-Reference Updates
[Paths that change and need updating]
## Verification
[How to confirm the migration succeeded]
## Checklist
[Checkbox list of all migration actions]