Archive Epic

Archive Epic

Context

You are archiving one or more completed epics from the active development plan. This moves the full epic content to an archive file and replaces it with a one-line summary in the active plan. The goal is to keep docs/development-plan.md under ~300 lines of active content.

Current Plan

Read the file docs/development-plan.md to get the current plan contents. If the file doesn't exist, inform the user and suggest running /vk:create-plan first.

Instructions

1. Identify Epics to Archive

Default behavior: If the user didn't specify which epic(s), archive all completed epics automatically. List the epics being archived for confirmation, then proceed.

## Archiving all completed epics

| Epic | Tasks | Action |
|------|-------|--------|
| 1. Foundation | 7 | Archive |
| 2. Core Features | 8 | Archive |
| 3. Supporting | — | Skip (in progress) |

If the user specified specific epic(s), archive only those.

Rules:

• Only epics marked as COMPLETE can be archived
• Refuse to archive in-progress or not-started epics
• Multiple epics can be archived in one operation

2. Verify the Epic is Truly Complete

Before archiving, confirm:

1. Epic header says (COMPLETE)
2. All tasks in the epic show Done status
3. No other epics have Depends On references to tasks in this epic that are still in progress

If dependencies exist on the epic's tasks from active epics, warn the user but allow archiving (the dependency info will remain in the active epic's task table).

3. Create or Append to Archive File

Archive files live in docs/archive/. Use a descriptive filename:

docs/archive/epics-1-3.md       (batch archive)
docs/archive/epic-1-foundation.md  (single epic)

If the user is archiving multiple epics, group them into one file.

Archive file format:

# Archived Epics

> Archived from `docs/development-plan.md` on [date]
> These epics are complete and moved here to reduce active plan size.
> Full git history is preserved for all changes.

---

[Full epic content copied verbatim from development-plan.md, including:]
- Epic header
- Description
- Acceptance criteria
- Tasks table
- Task details
- All checkboxes in their current state

If appending to an existing archive file, add the new epic(s) at the end with a separator.

4. Update the Active Plan

In docs/development-plan.md:

1. Remove the full epic section (everything from ## Epic N: to the next --- separator)

2. Add a summary line in a "Completed Epics (archived)" section placed after the Completion Status Summary table and before the first active epic:

## Completed Epics (archived)

| Epic | Tasks | Completed | Archive |
|------|-------|-----------|---------|
| 1. Foundation | 7 tasks | 2026-02-15 | [archive](archive/epics-1-3.md) |
| 2. Core Features | 8 tasks | 2026-03-01 | [archive](archive/epics-1-3.md) |

If the section already exists, append to the table.

3. Remove the epic from the Completion Status Summary table — archived epics are tracked in the "Completed Epics (archived)" section instead; the summary table only shows active (non-archived) epics.

4. Add changelog entry in docs/development-plan-changelog.md (prepend at the top of the list):

- **[date]**: Archived Epic N: [Name] to docs/archive/[filename] — [task count] tasks, plan reduced by ~[line count] lines

5. Provide Summary

## Archive Complete

**Archived:** Epic 1: Foundation (7 tasks), Epic 2: Core Features (8 tasks)
**Archive file:** docs/archive/epics-1-2.md
**Lines removed from active plan:** ~180
**Active plan size:** ~250 lines (was ~430)

### What's preserved
- Full epic content in archive file
- Summary row in "Completed Epics (archived)" section
- Git history for all changes

### Next steps
- Commit the changes
- Active epics remain in `docs/development-plan.md` as before
- To review archived epics, read `docs/archive/epics-1-2.md`

Edge Cases

Epic has cross-references from active tasks

If an active task has Depends On: 1.3 and Epic 1 is being archived:

• Allow archiving — the dependency is already satisfied (epic is complete)
• Note in the output that the dependency reference will remain in the active task table

Archive file already exists

If docs/archive/ already has files:

• Ask the user: append to existing file or create a new one?
• Default: create a new file with appropriate name

All epics are complete

If every epic is complete, archive them all. The "Completed Epics (archived)" section provides sufficient context in the active plan. The Completion Status Summary table will be empty — that's fine.

Notes

• Git is the real archive — the archive file is for convenience, but full history lives in commits
• Keep the active plan under ~300 lines for optimal context usage
• Never archive an incomplete epic — use /vk:close-epic first
• The Completion Status Summary table only shows active (non-archived) epics