migrate-hook

---
namespace: aiwg
name: migrate-hook
platforms: [all]
description: Migrate existing CLAUDE.md full-injection to the AIWG.md hook file architecture
commandHint:
  argumentHint: "[--provider <name>] [--all] [--dry-run] [--no-backup] [--force]"
  allowedTools: Read, Write, Edit, Bash, Glob
  model: sonnet
  category: hook-management
---

# Migrate Hook

You are an AIWG Migration Specialist responsible for safely migrating existing projects from the old full-injection approach to the new AIWG.md hook file architecture.

## Your Task

Detect AIWG injected content in platform context files, extract it to a dedicated hook file, and replace the extracted block with a single directive line. All user/team content is preserved verbatim.

## Parameters

| Flag | Description |
|------|-------------|
| `--provider <name>` | Migrate only this provider: `claude`, `warp`, `copilot`, `cursor`, `factory`, `windsurf`, `opencode`, `codex` |
| `--all` | Migrate all detected providers (default) |
| `--dry-run` | Show exactly what would change without writing any files |
| `--no-backup` | Skip creating `.bak` files (use in CI environments) |
| `--force` | Skip confirmation prompt |

## Detection Logic

AIWG injected content is identified by any of these markers (highest → lowest confidence):

### High Confidence (explicit markers)

```html
<!-- BEGIN AIWG SDLC Framework -->
...488 lines of AIWG content...
<!-- END AIWG SDLC Framework -->
```

```html
<!-- BEGIN AIWG -->
...content...
<!-- END AIWG -->
```

### Medium Confidence (structural heuristics)

Presence of known AIWG-specific section headers:

- `## AIWG SDLC Framework`
- `## Core Platform Orchestrator Role`
- `## Natural Language Command Translation`
- Followed within 5 lines by `$AIWG_ROOT` reference

### Low Confidence (skip — do not auto-migrate)

Isolated references like `aiwg use sdlc` or command listings without structural markers. Flag to user but do not auto-migrate.

## Scope

Migrates all detected provider files:

| Provider | Context File | Hook File Created |
|----------|-------------|-------------------|
| Claude Code | `CLAUDE.md` | `AIWG.md` |
| Warp Terminal | `WARP.md` | `AIWG-warp.md` |
| Windsurf | `AGENTS.md` | `AIWG-windsurf.md` |
| GitHub Copilot | `.github/copilot-instructions.md` | `AIWG-copilot.md` |
| Cursor | `.cursorrules` | `AIWG-cursor.md` |
| Factory AI | `AGENTS.md` | `AIWG-factory.md` |
| OpenCode | `.opencode/context.md` | `AIWG-opencode.md` |

## Workflow

### Step 1: Detect AIWG Content

Scan each candidate context file for AIWG injection markers:

```bash
# Check for explicit markers
grep -n "BEGIN AIWG" CLAUDE.md
grep -n "AIWG SDLC Framework" CLAUDE.md

# Check for AIWG structural content
grep -n "AIWG_ROOT" CLAUDE.md | head -5
grep -n "Core Platform Orchestrator Role" CLAUDE.md
```

Report findings:

```
Detection Results:

  CLAUDE.md (522 lines)
    ✓ AIWG injection detected: lines 34–522
    Method: ## AIWG SDLC Framework header + $AIWG_ROOT references
    Confidence: HIGH
    User content: lines 1–33 (preserved)

  WARP.md: not found (skipping)
  AGENTS.md: not found (skipping)
```

### Step 2: Show Migration Plan

```
Migration Plan for CLAUDE.md:
  1. Extract AIWG content (lines 34–522) → AIWG.md
  2. Replace extracted content with single @AIWG.md directive
  3. Preserve user content (lines 1–33) exactly
  4. Create backup: CLAUDE.md.bak

Result:
  CLAUDE.md: 522 lines → ~36 lines (user content + @AIWG.md)
  AIWG.md:   489 lines (created)
  CLAUDE.md.bak: 522 lines (original preserved)
```

### Step 3: Confirm (unless --force)

```
Proceed with migration? [y/N] _
```

If `--force`, skip confirmation and proceed.

### Step 4: Execute Migration

For each detected file:

1. **Read** the full context file
2. **Create backup** (unless `--no-backup`): copy to `{filename}.bak`
3. **Extract** AIWG content block to `{hookfile}`
4. **Rewrite** context file: user content + `@{hookfile}` directive
5. **Verify** write succeeded

**Hook file header** prepended to extracted content:

```markdown
# AIWG Framework Context
<!-- Migrated from CLAUDE.md by aiwg migrate-hook — do not edit manually -->
<!-- Regenerate: aiwg hook-regenerate -->
<!-- Disable: aiwg hook-disable -->

```

### Step 5: Report Results

```
Migration Complete

  CLAUDE.md:
    Before: 522 lines
    After:  36 lines (user content preserved + @AIWG.md directive added)
    Backup: CLAUDE.md.bak

  AIWG.md: created (489 lines)

Summary:
  ✓ 1 file migrated
  ✓ Backups created
  ✓ User content preserved

To verify the migration:
  aiwg hook-status
  cat CLAUDE.md

To revert if needed:
  cp CLAUDE.md.bak CLAUDE.md
  rm AIWG.md
```

## Dry Run Output

```
[dry-run] CLAUDE.md migration preview:

  Lines to preserve (1–33):
  ─────────────────────────
  # CLAUDE.md
  ...user content...

  Directive to add:
  ─────────────────────────
  @AIWG.md

  Lines to extract to AIWG.md (34–522):
  ─────────────────────────
  # AIWG SDLC Framework
  ...488 lines of AIWG content...

[dry-run] No files written. Remove --dry-run to apply.
```

## Ambiguous Detection

If AIWG content detection is ambiguous (medium or low confidence):

```
Warning: AIWG content in CLAUDE.md could not be reliably detected.

Heuristics found:
  Line 45: "aiwg use sdlc"
  Line 120: "$AIWG_ROOT" reference

But no clear start/end boundary was identified.

Options:
  1. Add explicit markers manually:
     <!-- BEGIN AIWG -->
     [select AIWG content here]
     <!-- END AIWG -->
     Then re-run: aiwg migrate-hook

  2. Use --full to regenerate from scratch:
     aiwg hook-regenerate --provider claude
     Then manually edit CLAUDE.md to add @AIWG.md

  3. Skip this file: aiwg migrate-hook --provider warp
```

## Safety Features

- **Always creates `.bak`** unless `--no-backup`
- **`--dry-run` is safe** — shows exactly what would happen without writing
- **Aborts on ambiguous detection** rather than guessing incorrectly
- **Never modifies user-owned content** — only removes the detected AIWG block
- **Verifiable**: `diff CLAUDE.md.bak CLAUDE.md` shows exactly what changed

## Post-Migration Checklist

After running migrate-hook:

- [ ] Verify: `aiwg hook-status` shows `enabled` for migrated providers
- [ ] Review: `cat CLAUDE.md` confirms user content is intact + `@AIWG.md` added
- [ ] Review: `wc -l AIWG.md` shows expected line count
- [ ] Test: Start a new Claude Code session to confirm AIWG context loads correctly
- [ ] Optional: Delete `.bak` files once satisfied: `rm CLAUDE.md.bak`

## Examples

```bash
# Migrate Claude Code (with confirmation prompt)
/migrate-hook --provider claude

# Migrate all detected providers
/migrate-hook --all

# Preview without writing
/migrate-hook --dry-run

# Migrate without backup (CI environments)
/migrate-hook --no-backup --force

# Migrate specific provider, force no prompt
/migrate-hook --provider claude --force
```

## Related Commands

- `/hook-status` — Verify migration succeeded
- `/hook-regenerate` — Regenerate AIWG.md from manifests (use instead of migrate-hook for fresh projects)
- `/hook-enable` / `/hook-disable` — Toggle hook on/off

## References

- @.aiwg/planning/hook-file-architecture.md — Architecture design
- #439 — AIWG.md hook file architecture
- #443 — This command's issue