vinta-ai-workflows 0.1.7

package/skills/vinta-install-ai-tools-setup/resources/setup-ai-tools.mjs

@@ -0,0 +1,392 @@
+#!/usr/bin/env node
+// Setup script: wire ai-tools/{AGENTS.md,skills,agents/*.yaml} into every supported vendor.
+//
+// Source of truth:
+//   - ai-tools/AGENTS.md           — universal project conventions (markdown).
+//   - ai-tools/skills/<name>/      — universal skills (SKILL.md format converges across
+//                                    Claude Code, Cursor, Codex, VS Code Copilot — symlinked).
+//   - ai-tools/agents/<name>.yaml  — vendor-agnostic sub-agent definitions. This script
+//                                    reads the YAML and emits per-vendor target files in the
+//                                    format each tool expects (markdown, .agent.md, .toml).
+//
+// What this script does:
+//   1. Symlinks ai-tools/AGENTS.md + ai-tools/skills/ into each vendor's expected paths.
+//   2. Reads each ai-tools/agents/<name>.yaml.
+//   3. For every supported vendor, generates a target file with vendor-specific frontmatter
+//      / format. Vendor-specific overrides come from the YAML's `overrides:<vendor>:` block;
+//      otherwise sensible defaults are derived from the YAML's `access` field
+//      (read-only vs read-write).
+//
+// Idempotent: re-run after editing ai-tools/agents/*.yaml and the vendor copies regenerate.
+//
+// Usage:
+//   pnpm setup:ai-tools                              # all four vendors
+//   node ai-tools/scripts/setup-ai-tools.mjs
+//   node ai-tools/scripts/setup-ai-tools.mjs --only claude-code,cursor
+//   node ai-tools/scripts/setup-ai-tools.mjs --only codex
+//
+// `--only` accepts a comma-separated list of vendor ids or aliases:
+//   claude     (aliases: claude-code)
+//   cursor
+//   copilot    (aliases: vscode, vscode-copilot, github-copilot)
+//   codex      (aliases: openai-codex)
+// Vendors not listed are left untouched: their existing generated files / symlinks remain
+// in place; this script does not delete or rewrite them.
+
+import {
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  symlinkSync,
+  lstatSync,
+  rmSync,
+  unlinkSync,
+  existsSync,
+  appendFileSync,
+} from 'node:fs';
+import { join, basename, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import * as YAML from 'yaml';
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+process.chdir(REPO_ROOT);
+
+const AGENTS_SRC = 'ai-tools/agents';
+
+// ── CLI: --only <comma-separated vendors> ────────────────────────────────
+
+const ALL_VENDORS = ['claude', 'cursor', 'copilot', 'codex'];
+const VENDOR_ALIASES = {
+  claude: 'claude',
+  'claude-code': 'claude',
+  cursor: 'cursor',
+  copilot: 'copilot',
+  vscode: 'copilot',
+  'vscode-copilot': 'copilot',
+  'github-copilot': 'copilot',
+  codex: 'codex',
+  'openai-codex': 'codex',
+};
+
+function parseOnly(argv) {
+  const idx = argv.findIndex((a) => a === '--only' || a.startsWith('--only='));
+  if (idx === -1) return new Set(ALL_VENDORS);
+  const raw = argv[idx].startsWith('--only=')
+    ? argv[idx].slice('--only='.length)
+    : argv[idx + 1];
+  if (!raw) {
+    console.error('--only requires a comma-separated value, e.g. --only claude-code,cursor');
+    process.exit(2);
+  }
+  const requested = raw.split(',').map((s) => s.trim()).filter(Boolean);
+  const resolved = new Set();
+  for (const id of requested) {
+    const canonical = VENDOR_ALIASES[id.toLowerCase()];
+    if (!canonical) {
+      console.error(
+        `unknown vendor "${id}". Allowed: ${Object.keys(VENDOR_ALIASES).sort().join(', ')}`
+      );
+      process.exit(2);
+    }
+    resolved.add(canonical);
+  }
+  return resolved;
+}
+
+const SELECTED = parseOnly(process.argv.slice(2));
+
+// ── Vendor defaults derived from `access` ────────────────────────────────
+
+const DEFAULTS = {
+  claude: {
+    'read-only': { tools: 'Read, Bash, Glob, Grep' },
+    'read-write': { tools: 'Read, Write, Edit, Bash, Glob, Grep, NotebookEdit' },
+  },
+  cursor: {
+    'read-only': { model: 'inherit', readonly: true },
+    'read-write': { model: 'inherit', readonly: false },
+  },
+  copilot: {
+    'read-only': { tools: ['codebase', 'search', 'terminal', 'usages'] },
+    'read-write': {
+      tools: ['codebase', 'editFiles', 'runCommands', 'runTasks', 'search', 'terminal', 'usages'],
+    },
+  },
+  codex: {
+    'read-only': { sandbox_mode: 'read-only' },
+    'read-write': { sandbox_mode: 'workspace-write' },
+  },
+};
+
+// ── Helpers ──────────────────────────────────────────────────────────────
+
+function ensureSymlink(target, linkPath) {
+  mkdirSync(dirname(linkPath), { recursive: true });
+  let existing;
+  try {
+    existing = lstatSync(linkPath);
+  } catch {
+    existing = null;
+  }
+  if (existing) {
+    if (existing.isSymbolicLink()) {
+      unlinkSync(linkPath);
+    } else {
+      console.warn(`[setup-ai-tools] ${linkPath} exists and is not a symlink — leaving as-is`);
+      return;
+    }
+  }
+  symlinkSync(target, linkPath);
+}
+
+function resetDir(path) {
+  rmSync(path, { recursive: true, force: true });
+  mkdirSync(path, { recursive: true });
+}
+
+function resolveVendorConfig(doc, vendor) {
+  // Merge: derived defaults from `access` + everything `doc` declares directly
+  // (e.g. `claude-tools` for backwards compat) + per-vendor `overrides`.
+  const access = doc.access ?? 'read-write';
+  const base = { ...DEFAULTS[vendor]?.[access] };
+  // Convenience: top-level `claude-tools` maps to claude.tools
+  if (vendor === 'claude' && doc['claude-tools']) {
+    base.tools = doc['claude-tools'];
+  }
+  const overrides = doc.overrides?.[vendor] ?? {};
+  return { ...base, ...overrides };
+}
+
+function escapeTomlBasic(s) {
+  return String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+function escapeTomlMultiline(body) {
+  // TOML triple-quoted multiline strings: only conflict is the literal `"""`
+  // sequence inside the body. Replace with escaped triple-quotes.
+  return body.replace(/"""/g, '\\"\\"\\"');
+}
+
+// ── .gitignore management ────────────────────────────────────────────────
+//
+// `.vinta-ai-workflows/` holds durable working state that is per-developer
+// machine, not committed history:
+//   - prs-context/{feature}/{phase}.md — implement-plan / amend-plan PR drafts
+//   - cache.yaml — systematic-debugging MCP preflight state
+// Single umbrella entry covers everything. Append on first run if not present.
+
+function ensureGitignoreEntries(entries) {
+  const path = '.gitignore';
+  let current = '';
+  try { current = readFileSync(path, 'utf8'); } catch { current = ''; }
+  const lines = new Set(current.split('\n').map((l) => l.trim()));
+
+  const missing = entries.filter((e) => !lines.has(e) && !lines.has(e.replace(/\/$/, '')));
+  if (missing.length === 0) return [];
+
+  const block = (current && !current.endsWith('\n') ? '\n' : '')
+    + (current ? '\n' : '')
+    + '# vinta-ai-workflows / implement-plan working notes\n'
+    + missing.join('\n') + '\n';
+
+  if (existsSync(path)) appendFileSync(path, block);
+  else writeFileSync(path, block.trimStart());
+  return missing;
+}
+
+function autoGenHeader(srcPath, comment = '#') {
+  return [
+    `${comment} AUTO-GENERATED by ai-tools/scripts/setup-ai-tools.mjs from ${srcPath}.`,
+    `${comment} Edit ${srcPath}, then run: pnpm setup:ai-tools.`,
+  ].join('\n');
+}
+
+// ── Vendor emitters ──────────────────────────────────────────────────────
+
+function emitClaude(name, doc, body) {
+  const cfg = resolveVendorConfig(doc, 'claude');
+  const lines = [
+    '---',
+    autoGenHeader(`ai-tools/agents/${name}.yaml`),
+    `name: ${doc.name}`,
+    `description: ${doc.description}`,
+  ];
+  if (cfg.tools) lines.push(`tools: ${cfg.tools}`);
+  if (cfg.model) lines.push(`model: ${cfg.model}`);
+  lines.push('---', body);
+  writeFileSync(`.claude/agents/${name}.md`, lines.join('\n') + '\n');
+}
+
+function emitCursor(name, doc, body) {
+  const cfg = resolveVendorConfig(doc, 'cursor');
+  const lines = [
+    '---',
+    autoGenHeader(`ai-tools/agents/${name}.yaml`),
+    `name: ${doc.name}`,
+    `description: ${doc.description}`,
+  ];
+  if (cfg.model) lines.push(`model: ${cfg.model}`);
+  if (cfg.readonly !== undefined) lines.push(`readonly: ${cfg.readonly}`);
+  if (cfg.is_background !== undefined) lines.push(`is_background: ${cfg.is_background}`);
+  lines.push('---', body);
+  writeFileSync(`.cursor/agents/${name}.md`, lines.join('\n') + '\n');
+}
+
+function emitCopilot(name, doc, body) {
+  const cfg = resolveVendorConfig(doc, 'copilot');
+  const lines = [
+    '---',
+    autoGenHeader(`ai-tools/agents/${name}.yaml`),
+    `description: ${doc.description}`,
+  ];
+  if (cfg.tools) lines.push(`tools: ${JSON.stringify(cfg.tools)}`);
+  if (cfg.model) lines.push(`model: ${cfg.model}`);
+  if (cfg['user-invocable'] !== undefined) lines.push(`user-invocable: ${cfg['user-invocable']}`);
+  if (cfg['disable-model-invocation'] !== undefined) {
+    lines.push(`disable-model-invocation: ${cfg['disable-model-invocation']}`);
+  }
+  lines.push('---', body);
+  writeFileSync(`.github/agents/${name}.agent.md`, lines.join('\n') + '\n');
+}
+
+function emitCodex(name, doc, body) {
+  const cfg = resolveVendorConfig(doc, 'codex');
+  const lines = [
+    autoGenHeader(`ai-tools/agents/${name}.yaml`, '#'),
+    `name = "${escapeTomlBasic(doc.name)}"`,
+    `description = "${escapeTomlBasic(doc.description)}"`,
+  ];
+  if (cfg.sandbox_mode) lines.push(`sandbox_mode = "${cfg.sandbox_mode}"`);
+  if (cfg.model) lines.push(`model = "${cfg.model}"`);
+  if (cfg.model_reasoning_effort) {
+    lines.push(`model_reasoning_effort = "${cfg.model_reasoning_effort}"`);
+  }
+  lines.push(
+    'developer_instructions = """',
+    escapeTomlMultiline(body.trimEnd()),
+    '"""',
+    ''
+  );
+  writeFileSync(`.codex/agents/${name}.toml`, lines.join('\n'));
+}
+
+// ── Stage 0: gitignore ───────────────────────────────────────────────────
+
+const gitignoreAdded = ensureGitignoreEntries(['.vinta-ai-workflows/']);
+
+// ── Stage 1: stable symlinks (skills + AGENTS.md) ────────────────────────
+
+// Universal anchors — always set up regardless of --only selection.
+ensureSymlink('ai-tools/AGENTS.md', 'AGENTS.md');
+ensureSymlink('../ai-tools/skills', '.agents/skills');
+
+// Vendor-specific symlinks — gated on SELECTED.
+if (SELECTED.has('claude')) {
+  ensureSymlink('../ai-tools/skills', '.claude/skills');
+}
+if (SELECTED.has('cursor')) {
+  ensureSymlink('../ai-tools/skills', '.cursor/skills');
+}
+if (SELECTED.has('copilot')) {
+  ensureSymlink('../ai-tools/AGENTS.md', '.github/copilot-instructions.md');
+  ensureSymlink('../ai-tools/skills', '.github/skills');
+}
+// Codex shares `.agents/skills` (already linked above) — no extra symlink needed.
+
+// ── Stage 2: regenerate per-vendor sub-agent files ───────────────────────
+
+const VENDOR_AGENT_DIRS = {
+  claude: '.claude/agents',
+  cursor: '.cursor/agents',
+  copilot: '.github/agents',
+  codex: '.codex/agents',
+};
+const VENDOR_EMITTERS = {
+  claude: emitClaude,
+  cursor: emitCursor,
+  copilot: emitCopilot,
+  codex: emitCodex,
+};
+
+// Reset only selected vendors' agent dirs; leave the rest untouched.
+for (const vendor of SELECTED) {
+  resetDir(VENDOR_AGENT_DIRS[vendor]);
+}
+
+const generated = [];
+for (const file of readdirSync(AGENTS_SRC)) {
+  if (!file.endsWith('.yaml') && !file.endsWith('.yml')) continue;
+  const name = basename(file, file.endsWith('.yaml') ? '.yaml' : '.yml');
+  const src = join(AGENTS_SRC, file);
+  const text = readFileSync(src, 'utf8');
+  const doc = YAML.parse(text);
+
+  // Schema: schemas/sub-agent.v1.schema.json (in vinta-ai-workflows package).
+  if (doc?.schema_version !== 1) {
+    throw new Error(`${src}: missing or unsupported 'schema_version' (expected: 1; see schemas/sub-agent.v1.schema.json)`);
+  }
+  if (!doc?.name) throw new Error(`${src}: missing required field 'name'`);
+  if (!doc?.description) throw new Error(`${src}: missing required field 'description'`);
+  if (!doc?.access) throw new Error(`${src}: missing required field 'access' (read-only | read-write)`);
+  if (typeof doc.body !== 'string' || !doc.body.trim()) {
+    throw new Error(`${src}: missing required field 'body' (markdown content as YAML literal block)`);
+  }
+
+  for (const vendor of SELECTED) {
+    VENDOR_EMITTERS[vendor](name, doc, doc.body);
+  }
+
+  generated.push({ name, access: doc.access });
+}
+
+// ── Report ───────────────────────────────────────────────────────────────
+
+const selectedList = [...SELECTED];
+const skipped = ALL_VENDORS.filter((v) => !SELECTED.has(v));
+
+console.log(`Selected vendors: ${selectedList.join(', ')}`);
+if (skipped.length) {
+  console.log(`Skipped (left untouched): ${skipped.join(', ')}`);
+}
+console.log('');
+
+if (gitignoreAdded.length) {
+  console.log(`.gitignore: appended ${gitignoreAdded.join(', ')}`);
+  console.log('');
+}
+
+console.log('Symlinks ensured:');
+console.log('  AGENTS.md                          → ai-tools/AGENTS.md');
+console.log('  .agents/skills                     → ../ai-tools/skills');
+if (SELECTED.has('claude')) {
+  console.log('  .claude/skills                     → ../ai-tools/skills');
+}
+if (SELECTED.has('cursor')) {
+  console.log('  .cursor/skills                     → ../ai-tools/skills');
+}
+if (SELECTED.has('copilot')) {
+  console.log('  .github/skills                     → ../ai-tools/skills');
+  console.log('  .github/copilot-instructions.md    → ../ai-tools/AGENTS.md');
+}
+console.log('');
+
+console.log(
+  `Generated ${generated.length * selectedList.length} sub-agent file(s) from ai-tools/agents/*.yaml across ${selectedList.length} vendor(s):`
+);
+const VENDOR_TARGET_DESC = {
+  claude: '.claude/agents/<name>.md            (markdown)',
+  cursor: '.cursor/agents/<name>.md            (markdown)',
+  copilot: '.github/agents/<name>.agent.md     (markdown)',
+  codex: '.codex/agents/<name>.toml            (TOML)',
+};
+for (const vendor of selectedList) {
+  console.log(`  ${vendor.padEnd(8)} → ${VENDOR_TARGET_DESC[vendor]}`);
+}
+console.log('');
+for (const { name, access } of generated) {
+  console.log(`  ${name.padEnd(20)} ${access}`);
+}
+console.log('');
+console.log('Re-run `pnpm setup:ai-tools` after editing ai-tools/agents/*.yaml.');
+console.log('Limit to specific vendors: --only claude-code,cursor,copilot,codex');

package/skills/vinta-migrate-plans-specs/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: vinta-migrate-plans-specs
+description: Find existing implementation plans and feature specs scattered across a project (`docs/`, `specs/`, `plans/`, root markdown, branch-named files, etc.) and migrate them to the canonical layout `ai-plans/YYYY-MM-DD-{FEATURE_NAME}_{PLAN|SPEC}.md`. Reads each candidate, proposes a target path (date + feature name + classification PLAN vs SPEC), shows the rename diff, and only renames after the user explicitly accepts each one. Run as step 6 of [vinta-bootstrap-ai-tools](../vinta-bootstrap-ai-tools/SKILL.md), or standalone any time afterwards. Read-only by default — every move is gated on per-file approval.
+---
+
+# Migrate plans + specs
+
+The Vinta convention: every implementation plan and every feature spec lives under `ai-plans/` at the repo root, named:
+
+```
+ai-plans/YYYY-MM-DD-{FEATURE_NAME}_{PLAN|SPEC}.md
+```
+
+- `YYYY-MM-DD` — date the doc was authored (use git log first-commit date when migrating, fall back to file mtime, fall back to ask).
+- `FEATURE_NAME` — `UPPERCASE_WITH_UNDERSCORES`. Same prefix shared by a spec and its plan so `ls ai-plans/` groups pairs.
+- `_PLAN` or `_SPEC` — classification. Spec describes *what + why*; plan describes *how + when*.
+
+Real-world repos accumulate these docs in many other shapes:
+
+| Shape | Examples |
+|---|---|
+| Per-feature folders | `docs/features/<name>/spec.md`, `docs/features/<name>/plan.md` |
+| Flat docs/ | `docs/SPEC-checkout.md`, `docs/PLAN-2025-checkout.md` |
+| Project root | `IMPLEMENTATION_PLAN.md`, `SPEC.md`, `ROADMAP.md` |
+| Branch-named | `feature/checkout/spec.md`, `feat-checkout-plan.md` |
+| Date-prefixed but off-format | `2025-11-checkout-plan.md`, `2025_11_checkout_spec.md` |
+| ADR-style | `docs/adr/0007-checkout.md` (sometimes spec-shaped, sometimes not) |
+| Already in `ai-plans/` but off-format | `ai-plans/checkout-plan.md` (no date), `ai-plans/2025-11-CHECKOUT_IMPLEMENTATION_PLAN.md` (legacy `_IMPLEMENTATION_PLAN`) |
+
+This skill normalizes them. Read-only until the user accepts a move.
+
+## Inputs
+
+- Path to the project being migrated (default: cwd).
+- Optional: list of additional dirs/glob patterns to scan (the user may keep specs somewhere unconventional).
+
+## Output
+
+- A migration proposal listing each candidate doc with: current path, classification (`PLAN` / `SPEC` / `unclear — ask`), proposed target path, source of date.
+- For each candidate the user accepts: `git mv <old> ai-plans/<new>`. Inbound references inside the repo's markdown updated where possible (best-effort grep + rewrite, with diff shown).
+- A summary report at the end: moved, skipped, ambiguous (user deferred), and a list of follow-ups.
+
+## Steps
+
+### 1. Prerequisite check
+
+`<project>` is a git repo. If not → fall back to plain `mv`, but warn the user that history won't follow the rename. `AskUserQuestion`: `Continue without git mv`, `Stop and init git first`.
+
+If `ai-plans/` already exists with files, that's fine — the skill normalizes those too if they're off-format.
+
+### 2. Discover candidates
+
+Search the repo for plan/spec-shaped markdown. Prioritize signal over recall — false positives waste user time.
+
+**Strong signals** (always include):
+
+- Filename matches `*spec*.md`, `*plan*.md`, `*roadmap*.md` (case-insensitive).
+- Filename matches `IMPLEMENTATION_PLAN.md`, `SPEC.md`, `RFC.md`, `DESIGN_DOC.md`.
+- Path contains `/specs/`, `/plans/`, `/ai-plans/`, `/rfcs/`, `/design-docs/`.
+- File header (first H1) contains "Spec", "Specification", "Implementation Plan", "RFC", "Design Doc", "Roadmap".
+
+**Weak signals** (consider but interview):
+
+- Files under `docs/features/<name>/` or `docs/proposals/`.
+- ADR files (`docs/adr/NNNN-*.md`) — usually decision records, not specs, but sometimes a team mixes them.
+
+**Always exclude**:
+
+- `node_modules/`, `vendor/`, `dist/`, `build/`, `.git/`, `.next/`, build outputs.
+- Generated docs (`docs/api/`, `docs/generated/`).
+- Files already at the canonical path *and* canonical format — they're done.
+
+Output a candidate list. If empty → report "no plan/spec docs found" and stop. If the user expected something to be there, ask them where to look.
+
+### 3. Classify each candidate (PLAN vs SPEC)
+
+For each candidate, decide its bucket. Heuristics:
+
+| Signal | Likely class |
+|---|---|
+| Filename / heading contains "spec" / "specification" / "RFC" / "design doc" | `SPEC` |
+| Filename / heading contains "plan" / "implementation plan" / "roadmap" / "phases" | `PLAN` |
+| Body has phased structure (Phase 1, Phase 2, sequential todos) | `PLAN` |
+| Body has acceptance criteria / use cases / hypotheses | `SPEC` |
+| Both signals strongly present | `unclear — ask` |
+| Neither | `unclear — ask` |
+
+Don't guess on `unclear — ask`. Surface it to the user with a snippet of the file and let them pick.
+
+### 4. Derive the date prefix
+
+For each candidate, prefer in this order:
+
+1. **Date already in the filename** that obviously corresponds to the doc (e.g. `2025-11-15-checkout-plan.md` → `2025-11-15`). Normalize to `YYYY-MM-DD`.
+2. **Date in the doc body** (e.g. `Date: 2025-11-15`, `Authored: ...` block).
+3. **Git log first-commit date for the file** (`git log --diff-filter=A --follow --format=%aI -- <path> | tail -1`).
+4. **File mtime** as a last resort.
+5. **Ask the user** if the result still looks wrong (e.g. mtime is today because the file got touched by a `find -exec` last week).
+
+Always show the chosen date + its source in the proposal so the user can override before accepting the move.
+
+### 5. Derive the feature name
+
+Strip dates, classification words, and extensions from the filename, then convert to `UPPERCASE_WITH_UNDERSCORES`.
+
+| Input | After strip | Final |
+|---|---|---|
+| `2025-11-15-checkout-plan.md` | `checkout` | `CHECKOUT` |
+| `docs/features/checkout-flow/spec.md` | `checkout-flow` (from parent dir) | `CHECKOUT_FLOW` |
+| `IMPLEMENTATION_PLAN.md` | (filename has no feature) → ask user | `<asked>` |
+| `feat-widget-config-spec.md` | `widget-config` | `WIDGET_CONFIG` |
+| `2026-04-23-WIDGETS_IMPLEMENTATION_PLAN.md` | `WIDGETS` | `WIDGETS` |
+
+If the source is a folder like `docs/features/checkout/spec.md` and a sibling `plan.md` exists, **lock both files to the same `FEATURE_NAME`** so the renamed pair groups in `ls`.
+
+### 6. Build the proposal
+
+Produce a per-candidate report. Group by status. Example:
+
+```
+ai-plans migration proposal — 7 candidates
+==========================================
+
+CLEAR (proposed: git mv to ai-plans/)
+  docs/features/checkout/spec.md
+    → ai-plans/2025-11-15-CHECKOUT_SPEC.md
+    date: 2025-11-15 (from git log first-commit)
+
+  docs/features/checkout/plan.md
+    → ai-plans/2025-11-15-CHECKOUT_PLAN.md
+    date: 2025-11-15 (paired with spec)
+
+  IMPLEMENTATION_PLAN.md
+    → ai-plans/2026-02-04-WAREHOUSE_AUDIT_PLAN.md
+    date: 2026-02-04 (from doc body "Date: 2026-02-04")
+    feature name: asked user (filename had none)
+
+ALREADY CANONICAL — only filename normalization
+  ai-plans/2026-04-23-WIDGETS_IMPLEMENTATION_PLAN.md
+    → ai-plans/2026-04-23-WIDGETS_PLAN.md
+    note: legacy `_IMPLEMENTATION_PLAN` suffix → `_PLAN`
+
+UNCLEAR — need user input
+  docs/adr/0007-checkout.md
+    body has hypothesis + acceptance criteria but is in adr/ folder.
+    classify as SPEC, PLAN, or skip?
+
+UNTOUCHED (no move proposed)
+  docs/api/openapi.md (api docs, excluded)
+```
+
+For each "CLEAR" entry, also list any inbound references discovered by `grep -r "<old-path>" .` so the user knows what else will need to be updated when the file moves.
+
+### 7. Per-candidate confirmation
+
+**Critical: never move silently.**
+
+For each `CLEAR` candidate, ask the user explicitly. Use `AskUserQuestion` with options:
+
+- `Apply` — `git mv <old> <new>`; rewrite inbound references.
+- `Skip` — leave the file in place.
+- `Edit proposal` — let the user override the proposed date / feature name / classification, then re-ask.
+
+For each `UNCLEAR` candidate, the question is upstream:
+
+- `Classify as SPEC, then propose target` — flips to `CLEAR` flow.
+- `Classify as PLAN, then propose target` — same.
+- `Skip — neither` — leave alone.
+- `Show full file body` — re-display before deciding.
+
+Do **not** batch under a single "apply all?" prompt. Each move is a separate decision so the user can keep edge cases unchanged. After all decisions, optionally offer a `Apply remaining clear ones` sweep — but only after every candidate has been individually classified and previewed.
+
+### 8. Apply approved moves
+
+For each accepted candidate:
+
+1. `mkdir -p ai-plans` (idempotent).
+2. `git mv <old> ai-plans/<new>` (or plain `mv` if not in a git repo).
+3. Search the repo for inbound references (`grep -rln "<old-relative-path>" --exclude-dir={node_modules,.git,dist,build}`). For each hit:
+   - Rewrite the path text to the new path.
+   - Show the rewrite diff inline; ask once whether to apply (default `yes`, `no`, `edit`).
+4. Log: `[moved] <old> → ai-plans/<new>`.
+
+If the source file had a sidecar (e.g. `docs/features/checkout/diagram.png` next to the spec): ask the user whether to move it alongside (sub-folder `ai-plans/2025-11-15-CHECKOUT/`) or leave in place. Default: leave in place — the canonical layout is flat markdown.
+
+### 9. Final report
+
+Echo back, in this order:
+
+1. **Moved** — `<old> → ai-plans/<new>` per file. Note inbound-reference rewrites count.
+2. **Skipped by user** — files left in place (with reason if the user gave one).
+3. **Unclear, deferred** — files the user said `Show body / Skip — neither` on. Surface them as TODO so they don't get lost.
+4. **Already canonical** — listed for transparency.
+
+If `git status` shows the rename, suggest the next steps:
+
+```bash
+git diff --stat
+git commit -m "Migrate plans/specs to ai-plans/ canonical layout"
+```
+
+After moves are committed, point the user at the foundation skills (`create-spec`, `plan-feature`) so future docs land in the canonical layout from the start. If the project's foundation skill bodies still reference a non-`ai-plans/` path or the legacy `_IMPLEMENTATION_PLAN` suffix, flag it as a follow-up to align them.
+
+## Read-only mode
+
+If the user asks for a "preview" / "dry-run" / "what would change" — perform steps 1–6 only. Stop before step 7. Print the proposal and exit. Re-invoke without dry-run when ready.
+
+When invoked without explicit dry-run intent, still default to **showing all proposals first, then asking per file**. Never start with destructive actions.
+
+## Pitfalls
+
+- **Mass-renaming based on filename heuristics alone.** A file called `auth-spec.md` might be auto-generated API spec (OpenAPI export). Read the body header before classifying. Strong signals + body shape together — never one alone.
+- **Wrong date prefix.** mtime is the worst source — anything that touched the file (a sweep, a format-on-save) clobbers it. Prefer git log first-commit date. Always show the source so the user can override.
+- **Breaking inbound references.** Wikis, READMEs, prior PRs, and CHANGELOG entries reference plan/spec paths. Run grep for inbound refs *before* moving, show the user what else will change. Apply rewrites in the same batch as the move.
+- **Splitting a paired spec + plan.** When a folder has both, lock the `FEATURE_NAME` so they share the prefix. Don't let the user accidentally rename `spec.md` → `CHECKOUT_FLOW_SPEC.md` and `plan.md` → `CHECKOUT_PLAN.md` (different names break grouping).
+- **Touching ADRs that are decision records, not specs.** `docs/adr/` is its own genre. Default to skip; ask the user before reclassifying.
+- **Renaming inside a feature branch.** Concurrent branches that haven't rebased will hit messy conflicts on next merge. Surface this risk to the user before applying — they may want to coordinate or do migration on `main` first.
+- **Generated docs.** OpenAPI, Storybook MDX, Typedoc output, etc. — exclude by path, don't classify.
+- **Stale `_IMPLEMENTATION_PLAN` suffix.** Some Vinta projects historically used `_IMPLEMENTATION_PLAN.md`. The new standard is `_PLAN.md`. Migrate during this run; flag the foundation skill bodies (project's `ai-tools/skills/plan-feature/SKILL.md`) for alignment if they still mention the old suffix.
+
+## Verification
+
+1. **Empty project**: no candidates found; skill exits cleanly with "no plan/spec docs found". `ai-plans/` not created.
+2. **Single clear plan**: one `IMPLEMENTATION_PLAN.md` at root → proposal shows 1 candidate, classification = PLAN, date from git log; user accepts → file moved with `git mv`, inbound refs (if any) rewritten.
+3. **Paired spec + plan in folder**: `docs/features/checkout/{spec,plan}.md` → both proposed under same `FEATURE_NAME=CHECKOUT`, dates synced where one's date is missing.
+4. **Already canonical**: no diffs proposed; report lists them as `Already canonical`.
+5. **Legacy suffix**: `ai-plans/2026-04-23-WIDGETS_IMPLEMENTATION_PLAN.md` → proposed rename to `_PLAN.md`; user accepts → renamed; inbound refs rewritten.
+6. **Unclear file**: ADR-style file flagged `unclear`; user picks `Skip`; file left untouched and surfaced in final report.
+7. **Dry-run**: user asks for preview → proposal printed, no `git mv` calls executed, exit clean.