majiayu000 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:
- Check current branch
- If on feature branch/worktree: Skip - wait for PR merge
- 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:
- Check conversation context for recently executed plan
- List completed plans in
docs/plans/ - 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 completioncreate-plan- Creates plans this skill archivesreview-plan- Reviews plans before execution