---
name: afx-migrate
description: Upgrade existing Artifex projects and installations from v0.0.1 to v0.2.0 (and future versions). Use this skill when a user has an older Artifex project with tickets.db at the root, wants to reconcile their ~/.claude/ installation, or needs to sweep a directory of projects. Supports dry-run preview and multi-project sweeps.
---

# Artifex Migration Skill

**For Claude Code AI Assistant**

This skill upgrades Artifex projects and installations to the current version. It is conversational — you walk the user through the steps, preview changes, and only then invoke the underlying script.

## What afx-migrate Does

The migration tool handles three distinct jobs:

1. **Project migration**: move a v0.0.1 project layout to v0.2.0
   - `./tickets.db` → `.artifex/tickets.db`
   - `./STATE.md`, `DECISIONS.md`, `PROGRESS.md` → `.artifex/state/`
   - `./tmp/` → `.artifex/tmp/`
   - Creates `.artifex/.gitignore` from the template
   - Cleans stale entries (`tickets.db`, `tmp/`, `.artifex/`) from the root `.gitignore`
   - Inspects `CLAUDE.md` and offers to append missing v0.2.0 sections (Artifex Directory, Agent Efficiency Rules, Transient Files)

2. **Install verification**: inspect `~/.claude/.artifex-installed`
   - Detects STALE (marker entry but source removed), MISSING (source in repo but not installed), and ORPHAN (symlink not in marker) entries
   - Offers to remove stale symlinks
   - Never touches orphans automatically

3. **Sweep**: find and migrate every Artifex project under a parent directory

## Breaking Changes (v0.0.1 → v0.2.0)

- Skill/command/agent names gained an `afx-` prefix. Example: `ticket-manager` → `afx-ticket-manager`, `init-tickets.md` → `afx-init-tickets.md`.
- Project state moved under `.artifex/`:
  - `./tickets.db` → `.artifex/tickets.db`
  - `./STATE.md` → `.artifex/state/STATE.md`
  - `./tmp/` → `.artifex/tmp/`
- `.gitignore` split: the project's root `.gitignore` no longer tracks `tickets.db`/`tmp/`; `.artifex/.gitignore` handles that.

## How to Run This Skill

When the user asks to "migrate my Artifex project", "upgrade to v0.2.0", "sweep my projects folder", or "check my Claude install", walk them through these modes:

### Mode A: Migrate the current project

1. Confirm the working directory is the intended project root.
2. **Always run with `--dry-run` first:**
   ```bash
   ~/.claude/skills/afx-migrate/afx-migrate.sh --dry-run
   ```
3. Show the user the preview output. Summarize what will change.
4. If the user approves, re-run without `--dry-run`:
   ```bash
   ~/.claude/skills/afx-migrate/afx-migrate.sh
   ```
5. If the script exits with code 2 (dirty git), offer options:
   - Commit the current changes first
   - `git stash` them
   - Re-run with `--force` (not recommended unless the repo is intentionally dirty)

### Mode B: Sweep a parent directory

1. Ask the user which parent directory to scan.
2. Preview:
   ```bash
   ~/.claude/skills/afx-migrate/afx-migrate.sh --all <parent> --dry-run
   ```
3. Show the list of candidate projects. Confirm with the user.
4. Run for real:
   ```bash
   ~/.claude/skills/afx-migrate/afx-migrate.sh --all <parent>
   ```
5. Report the aggregate results (migrated / already current / skipped / failed).

### Mode C: Verify install only

```bash
~/.claude/skills/afx-migrate/afx-migrate.sh --verify-install
```

This inspects `~/.claude/.artifex-installed` and the repo. Summarize the four groups (OK / STALE / MISSING / ORPHAN) for the user. Offer to remove stale links; for missing items suggest running `./install.sh --mode=full`.

## Flags Reference

| Flag | Purpose |
|------|---------|
| `--dry-run` | Preview only, touches nothing |
| `--force` | Bypass dirty-git refusal |
| `--yes` | Auto-confirm all prompts (useful in sweeps or CI) |
| `--all <dir>` | Sweep mode |
| `--verify-install` | Install verification mode |
| `--help` | Usage |

## Handling the Dirty-Git Case (Exit Code 2)

When the script exits with code 2, present the user with three options:

1. **Commit first** (safest): "I'll commit your pending changes, then rerun the migration."
2. **Stash** (reversible): `git stash && afx-migrate.sh && git stash pop`
3. **Force** (only if the user insists): explain that this mixes migration changes with pre-existing uncommitted work and makes `git diff` harder to read.

## Interpreting Output

After a run, always summarize:

- Which files were moved
- Which CLAUDE.md sections were added or skipped
- Which `.gitignore` lines were cleaned
- Anything flagged for manual review (e.g., target already existed)
- For sweeps: the per-category counts

## Idempotency Guarantees

The script is safe to re-run:

- The v0.2.0 layout check (existence of `.artifex/tickets.db` or `.artifex/.gitignore`) short-circuits a second run
- `mkdir -p`, existence-guarded moves, and append-only CLAUDE.md edits mean nothing is clobbered
- You can freely run `--dry-run` followed by the real invocation

## Version

1.0.0