docs-migrate

name

docs-migrate

description

This skill should be used when the user asks to "migrate docs to macstack", "move the project documents", "перенести docs в macstack", "standardize an existing project's documents", "we already have a docs folder", "move macstack.json into the folder", or wants an organically-grown `docs/` folder (with `macstack.json` still at the repo root) relocated into the standard `macstack/` layout. Disabled for model-invocation: this is a one-time, destructive, multi-gate procedure that must only run when a human explicitly asks for it, never inferred from context.

Migrate an existing docs/ into macstack/

A one-time, destructive relocation: a project whose documents grew organically in docs/, with macstack.json at the repo root, gets its specification-side material moved into the standard macstack/ folder — safely, reversibly, and never silently. The target layout, ID spaces, anchors and section contract are owned by project-docs — read ${CLAUDE_PLUGIN_ROOT}/skills/project-docs/references/doc-contracts.json before writing anything; do not recall anchors or ID patterns from memory.

disable-model-invocation: true because this moves files with git mv, rewrites references across the repo, and can break links from outside it — the same reason skills/feedback/SKILL.md carries the flag. It must only fire on an explicit ask.

The classification — what moves and what stays

docs/ stays the engineering folder. Only specification-side material moves. The principle: macstack/ must stay a folder you can hand to a client whole; anything that only helps someone write code belongs in docs/. When a document straddles the line, ASK — do not guess.

Genre in the wild	Destination	How to recognize it
Acceptance cases per role, "what the user must get"	macstack/USER-CASES.md	role sections, per-case acceptance lists, priorities
Open items / debt register split by owner	macstack/OPEN-QUESTIONS.md	"what is still owed and by whom", client inputs vs. deferred work
Dated rulings with reasoning	macstack/decisions/	numbered decisions, "because", cost-if-wrong
Analysis of a client document against the live spec	macstack/deltas/	"contradictions / what to add", declares itself a proposal
Conformance audits, case→code→test	macstack/reviews/	status vocabulary, mechanical counts
Client-supplied source material (PDF, docx, exports)	macstack/inbox/	not authored by the team
Product logic in plain words	macstack/BUSINESS-LOGIC.md	invariants, state machines, what the platform refuses
Architecture, API conventions, code style, data contracts, runbooks, deployment, cloud setup	stays in docs/	tells an engineer how to build, not what to build
Execution plans and design specs per milestone	stays in docs/	dated working artifacts of how the work got done

Procedure

0. Preconditions — refuse unless all hold. A git repo with a CLEAN working tree (a destructive move with uncommitted work has no undo); not on the default branch — create and switch to a migration branch first; no existing macstack/ with content, or an explicit go-ahead to merge into it.

1. Inventory. List every file under docs/ with size, first-added / last-modified dates and commit count (the best single signal of a LIVING document). Read enough of each — headings plus the opening paragraph — to classify it. Find client material anywhere in the tree: PDFs, .docx, .xlsx, exports, anything not authored by the team.

2. Move map — present before touching anything. A table of source → destination → genre → why, plus an explicit STAYS list, plus an UNSURE list with a question for each. ── GATE 1 ── the user confirms, corrects, or reclassifies.

3. Inbound references. Grep the whole repository for every path about to move. Report references inside this repo (will be rewritten) separately from references from OUTSIDE this repo, which CANNOT be rewritten — list them for the user. This is real: a sibling knowledge base can cite projects/<name>/docs/open-items.md or projects/<name>/macstack.json by path from a different repository, including from a sources: frontmatter field. ── GATE 2 ── the user accepts the external breakage, or the move is narrowed.

4. Move. git mv only — never cp+rm, so history follows the file. Rewrite in-repo references with the Edit tool, one file at a time — never sed across the tree, a blind substitution hits code, changelogs and quoted examples. For macstack.json: git mv to macstack/macstack.json. Do NOT leave a redirect stub at the old path — a three-line pointer fails the schema's required keys, and relaxing required is not an additive change. Offer git rm of the root file only after the moved copy parses and lints.

5. Normalize. Invoke project-docs to create whatever the layout is still missing. Insert the section anchors from doc-contracts.json into the moved documents idempotently, mapping each existing heading to its anchor key; where a document has no equivalent of a required section, add the anchor with an empty placeholder rather than inventing content. Rename dated artifacts to YYYY-MM-DD-<slug>.md; ASCII-only filenames in inbox/ (the zone is immutable — fix a bad name now, never after). Build inbox/README.md from what is known about each source, leaving "from whom" and "supersedes" blank rather than guessed. Seed log.md with one backfill entry per moved client source, marked as backfilled.

6. Reconcile IDs — a named gate, not a heuristic. Local numbering in existing rulings files ("1." … "26.") is not the project's D-space, and the two cannot be reconciled mechanically. Present the mapping you propose and let the owner correct it. ── GATE 3 ── the owner confirms the D assignment. Then convert lifecycle.open_questions and lifecycle.needs_from_client from prose strings to pointer form {id, ref, status, blocks, closed_by}, keeping the prose in OPEN-QUESTIONS.md — the JSON must end up holding no prose. Back-fill roles[].cases.

7. Verify. Run lint; every rule in group 12 must pass or be explained. Confirm no file lost content — compare line counts before and after. Report: what moved, what stayed, what was renamed, which references were rewritten, which external references are now broken and who must fix them, and which IDs still need a human decision.

8. Prose → pointer, standalone. The same lifecycle.open_questions[] / lifecycle.needs_from_client[] conversion from step 6 can run on its own — no docs/ folder, no full relocation — whenever lint's "Legacy string-form open_questions" warning is the only problem left in an otherwise-standard macstack/ folder: for each prose string, write a fresh OPEN-QUESTIONS.md row (an A or B id) carrying its title and body, then replace the string in the JSON with the matching pointer object {id, ref, status, blocks, closed_by}. ── GATE 4 ── the owner confirms each split — turning one prose paragraph into an id, a title and a body is a judgement call, never mechanical.

Guard rails

• Nothing is moved before the move map (Gate 1) is confirmed.
• git mv only, one migration branch, a clean tree — no exceptions.
• inbox/ becomes immutable the moment material lands in it: fix bad filenames during the move, never after.
• Three named gates (map, external references, D reconciliation) for a full relocation — never collapse them into one confirmation. A fourth (prose → pointer, step 8) stands alone and needs none of the others.

Second mode — a flat macstack/ into the four folders

A folder created before the four-folder layout has twelve files and five directories at its root and no signal about which of them a human may edit. references/restructure.py moves it:

python3 "${CLAUDE_PLUGIN_ROOT}/skills/docs-migrate/references/restructure.py" <repo>          # dry run
python3 "${CLAUDE_PLUGIN_ROOT}/skills/docs-migrate/references/restructure.py" <repo> --apply

git mv only, so history follows. The part that goes wrong quietly is the second job: documents move one level DEEPER, so a link reading ../docs/architecture.md from the root must read ../../docs/architecture.md from client/. The script resolves every reference against its OLD location and re-expresses it against the new one; a reference that does not resolve is REPORTED, never guessed at. Run the dry pass and read that list before applying — on the first real run it found a genuinely broken link that predated the move.

Afterwards: seed.py for the two authored client documents, render-docs, then lint.