migrate

Files (3)

• SKILL.md
• migrate.py
• worked-example-slice-to-spec.md

SKILL.md (first lines)

> Spec 008 created this skill from scratch. The deterministic filesystem
> walk + verdict logic + report rendering live in `migrate.py`; this
> SKILL.md drives the judgment layer (when to invoke, how to interpret
> ambiguities, what operations to suggest in what order).

## What this skill does

Closes the "already spec-driven" gap that `scaffold-init` doesn't handle:
projects that organically grew the same workflow jig codifies but landed
on different conventions (folder names, filename prefixes, slice
topology). Direct example: a project with `docs/slices/` (flat) and
`docs/decisions/` (validator-style) — `scaffold-init` would not detect
it as scaffolded and would either refuse confusingly or pollute the
tree.

`migrate` flips that around: detect existing shape first, then propose
a migration plan, then (in later slices) apply the rename / restructure
operations.

`migrate.py` exposes six subcommands:

- `report` — strictly read-only inventory + plan.
- `adopt-layout` — validates an existing custom-root corpus and writes only
  its `scaffold.json` sentinel/config; supports `--dry-run`.
- `rename-decisions` — applies ADR-0004's rename. Idempotent; refuses
  on conflict; has a `--dry-run` mode; `--host claude|codex` selects
  whether cross-reference rewrites scan `CLAUDE.md`/`.claude/` or
  `AGENTS.md`/`.codex/`.
- `split-slices` — extracts embedded slice sections into sibling
  slice files.
- `seed-decisions` — seeds `docs/decisions/lightweight-decisions.md` from
  jig's template. Idempotent; supports `--dry-run` and `--docs-root`; never
  overwrites an existing file.
- `copy-machinery` — copies jig runtime machinery into the target's
  host-local scaffold runtime; `--host claude` writes `.claude/`, and
  `--host codex` writes `.codex/`.

## How to use

### Run the migration report

```bash
python3 "${CLAUDE_PLUGIN_ROOT}/skills/migrate/migrate.py" report \
  <project-dir> [--docs-root <relative-root>]
```

- `<project-dir>` — path to the project root (e.g. `/path/to/repo`,
  `.` for cwd).
- `--docs-root .` — inventory a track-local corpus whose `specs/`,
  `decisions/`, `workflow.md`, and `architecture.md` live directly under the
  selected subproject instead of under `docs/`.

### Adopt an existing custom-root corpus

Preview first, then apply:

```bash
python3 "${CLAUDE_PLUGIN_ROOT}/skills/migrate/migrate.py" \
  adopt-layout <subproject-dir> --docs-root . --dry-run
python3 "${CLAUDE_PLUGIN_ROOT}/skills/migrate/migrate.py" \
  adopt-layout <subproject-dir> --docs-root .
```

The operation refuses incomplete/ambiguous corpora and existing or malformed
sentinels before mutation. Apply writes only `<subproject-dir>/scaffold.json`
using scaffold-init's canonical manifest builder; it does not move or rewrite
the existing artifacts. Afterward, `workflow.py transition`, status-board,
and ADR helpers discover the subproject through that sentinel.

### Run the rename-decisions migration

Once `report` has been reviewed and the verdict is `adoptable`, the
recommended sequence is:

```bash
# 1. Preview the plan (no writes).
python3 "${CLAUDE_PLUGIN_ROOT}/skills/migrate/migrate.py" \
  rename-decisions <project-dir> --dry-run

# 2. After reviewing the planned operations, apply them.
python3 "${CLAUDE_PLUGIN_ROOT}/skills/migrate/migrate.py" \
  rename-decisions <project-dir>
```

What it does, in display order:

1. `docs/adrs/` → `docs/decisions/` (directory rename, atomic).
2. Per-file renames: `NNN-<slug>.md` → `adr-NNNN-<slug>.md`
   (pad 3-digit to 4-digit; add `adr-` prefix where missing).
3. Cross-reference rewrites in text files under `docs/`, `CLAUDE.md`,
   and `.claude/` by default. With `--host codex`, rewrites scan
   `docs/`, `AGENTS.md`, and `.codex/` instead. The helper itself
   (`migrate.py` and its fixtures) is never rewritten.

Refusal cases (exit 2, no mutations):

- Both `docs/adrs/` and `docs/decisions/` present (manual merge first).
- Two source files normalize to the same target name (collision).
- `<project-dir>` missing, not a directory, or unreadable.

No-op cases (exit 0):

- Neither dir present, OR all files already on the canonical shape —
  emits "already aligned: nothing to do" and returns.

### Run the seed-decisions operation

`seed-decisions` backfills `docs/decisions/lightweight-decisions.md` — the
home `/jig:memory-sync`'s `decisions.py add-lightweight` records into, and
the one the Stop-hook decision nudge points at.

Reach for it when `report` flags the gap, or when a project's
`add-lightweight` fails because the file is missing. Every project that
adopted jig **before** the lightweight-decisions feature landed needs it:
`scaffold-init` seeds the file only at init and cannot be re-run on an
already-scaffolded project, so there was previously no supported way to
obtain it (bug 012 / [#109](https://github.com/ramboz/jig/issues/109)).

```bash

From ramboz/jig, MIT.

More from ramboz/jig