Merge and Archive Plan

Archive completed implementation plans with full metadata after successful merge to main.

Purpose

Maintain a clean, organized plan history by:

• Moving completed plans to

  docs/plans/archive/

• Adding comprehensive archive metadata
• Preserving execution history and lessons learned
• Keeping active plans directory focused

When to Use

• After a plan's implementation PR is merged to main
• When plan-execute completes successfully (with confirmation if on main)
• Manual cleanup of completed plans

Trigger Behavior

Automatic Invocation (from plan-execute)

If invoked automatically after plan-execute completes:

1. Check current branch
2. If on feature branch/worktree: Skip - wait for PR merge
3. If on main branch: Prompt user for confirmation

Plan execution complete on main branch.

Would you like to archive this plan now?
- The plan will be moved to docs/plans/archive/
- Archive metadata will be added

[Yes] [No, I'll do it later]

Slash Command Invocation

If invoked via

/ak-merge-archive-plan

:

• Proceed directly without double-confirmation
• User explicitly requested archiving

Archive Workflow

Step 1: Identify the Plan

If plan path provided: Use directly.

If no path:

1. Check conversation context for recently executed plan
2. List completed plans in

   docs/plans/

3. Ask user which plan to archive

Step 2: Verify Merge Status

Before archiving, verify the implementation is merged:

# Check if on main branch
git branch --show-current

# If on feature branch, check if merged to main
git log main --oneline | grep -q "{plan-related-commit}"

If not merged:

⚠️ Plan implementation doesn't appear to be merged to main yet.

Current branch: feature/0042_user-auth
Merge status: Not merged

Options:
1. Archive anyway (not recommended)
2. Wait for merge
3. Check a different plan

How would you like to proceed?

Step 3: Gather Archive Metadata

Collect comprehensive information:

# Get PR information (if available)
gh pr list --state merged --search "{plan-name}" --json number,title,url,mergedAt

# Get commits from implementation
git log --oneline main~{N}..main --grep="{plan-name}"

# Get files changed
git diff --stat {first-commit}^..{last-commit}

Step 4: Update Plan with Archive Header

Use the Edit tool to prepend the archive metadata block at the top of the plan file. Do NOT create a new file - edit the existing plan in place.

See assets/archive-header-template.md for the full template.

Step 5: Move to Archive with git mv

Use

git mv

to move the plan - this preserves git history and stages the change in one step.

# Ensure archive directory exists
mkdir -p docs/plans/archive/

# Move the plan using git mv (preserves history)
git mv docs/plans/{NNNN}_{name}.md docs/plans/archive/

# Move any subplans
git mv docs/plans/{NNNN}A_*.md docs/plans/archive/ 2>/dev/null || true
git mv docs/plans/{NNNN}B_*.md docs/plans/archive/ 2>/dev/null || true

Example:

mkdir -p docs/plans/archive/
git mv docs/plans/0001_bootstrap.md docs/plans/archive/

Step 6: Commit Archive

git add docs/plans/archive/{plan-files}
git add docs/plans/  # To capture the removal
git commit -m "docs(plans): archive {NNNN}_{name}

- Moved to docs/plans/archive/
- Added archive metadata
- PR: {PR URL}

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>"

Step 7: Report

## Plan Archived: {plan-name}

**Status:** ✅ Archived successfully

| Detail | Value |
|--------|-------|
| Plan | `{NNNN}_{name}.md` |
| New Location | `docs/plans/archive/` |
| PR | [{PR title}]({URL}) |
| Commits | {N} |
| Files Changed | {N} |

Subplans also archived:
- `{NNNN}A_{subplan}.md`
- `{NNNN}B_{subplan}.md`

Archive Directory Structure

docs/plans/
├── 0043_current-feature.md     # Active plans
├── 0044_upcoming-work.md
└── archive/                     # Completed plans
    ├── 0001_bootstrap.md
    ├── 0002_cli-core.md
    ├── 0040_old-feature.md
    ├── 0041_another-done.md
    └── 0042_user-auth.md

Metadata Template

See assets/archive-header-template.md for the full archive header format.

Edge Cases

Plan with No PR

If implementation was done directly on main without a PR:

## Archive Information

| Field | Value |
|-------|-------|
| Archived | {date} |
| PR | N/A (direct to main) |
| Commits | {N} commits |

Partial Implementation

If plan was only partially completed:

---
archived: true
archived_date: {date}
partial: true
---

## Archive Information

**Note:** This plan was partially implemented. See Lessons Learned for details.

### Completed
- Phase 1: Database Schema ✅
- Phase 2: API Endpoints ✅

### Not Completed
- Phase 3: Frontend (deferred to plan 0050)
- Phase 4: Integration Tests (covered by 0050)

Abandoned Plan

For plans that were abandoned:

---
archived: true
archived_date: {date}
status: ABANDONED
---

## Archive Information

**Status:** ABANDONED

**Reason:** {Why the plan was abandoned}

**Disposition:**
- Requirements changed
- Superseded by plan {NNNN}
- No longer needed

Examples

Example: Archive after PR merge

User: Archive the user-auth plan, the PR just merged

Claude: [Checks git status]
[Finds merged PR via gh cli]
[Gathers commit history]

Archiving plan 0042_user-auth...

[Updates plan with archive header]
[Moves to docs/plans/archive/]
[Commits changes]

## Plan Archived: 0042_user-auth

✅ Archived successfully

| Detail | Value |
|--------|-------|
| Plan | `0042_user-auth.md` |
| PR | [feat: add user authentication](#123) |
| Commits | 8 |
| Files Changed | 12 |

Example: Auto-invocation on main

[plan-execute completes on main branch]

Claude: Plan execution complete on main branch.

Would you like to archive this plan now?
- The plan will be moved to docs/plans/archive/
- Archive metadata will be added

User: Yes

Claude: [Proceeds with archiving]

Related Skills

• plan-execute

  - May invoke this skill after completion

• create-plan

  - Creates plans this skill archives

• review-plan

  - Reviews plans before execution