# Spec Driven Archive

> Archive a completed spec-driven change. Requires completed tasks, merges delta specs into main specs, then moves the change to archive/ with a date prefix.

- Skill: `kw12121212/spec-driven-archive` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add kw12121212/spec-driven-archive`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kw12121212/spec-driven-archive/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kw12121212 (https://skillmd.com/u/kw12121212)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kw12121212/spec-driven-archive

---


You are helping the user archive a completed spec-driven change.

## This Skill's Commands

If you cannot remember the exact command used by this skill, look it up here
before running anything. Do not guess.

```yaml
modify: node {{SKILL_DIR}}/scripts/spec-driven.js modify
apply: node {{SKILL_DIR}}/scripts/spec-driven.js apply <name>
verify-spec-mappings: node {{SKILL_DIR}}/scripts/spec-driven.js verify-spec-mappings
archive: node {{SKILL_DIR}}/scripts/spec-driven.js archive <name>
```

## Responsibility Split

Explicitly distinguish script work from AI work when you run this skill.

**Handled by CLI scripts**
- `node {{SKILL_DIR}}/scripts/spec-driven.js modify` lists active changes
- `node {{SKILL_DIR}}/scripts/spec-driven.js apply <name>` reports task completion status
- `node {{SKILL_DIR}}/scripts/spec-driven.js archive <name>` moves the change directory into `.spec-driven/changes/archive/YYYY-MM-DD-<name>/` and, when `.spec-driven/roadmap/` exists, reconciles any affected milestone declared status plus `.spec-driven/roadmap/INDEX.md`

**Handled by the AI**
- Ask the user which change to archive when needed
- Interpret the `apply` output and block archive when tasks remain incomplete
- Inspect `.spec-driven/changes/<name>/specs/`, merge delta specs into `.spec-driven/specs/`, and remove emptied main spec files when required by `REMOVED`
- Accept empty `specs/` without confirmation — changes without spec impact are valid
- Update `.spec-driven/specs/INDEX.md` to reflect created or deleted main spec files
- Preserve or apply spec mapping frontmatter during spec merges
- Summarize the merged spec impact, any roadmap status changes caused by archive, and the final archive location

## Prerequisites

The `.spec-driven/` directory must exist at the **project root**. Before proceeding, verify:
```
ls .spec-driven/
```
If this fails, the project is not initialized. Run `/spec-driven-init` first.

## Steps

1. **Select the change** — run `node {{SKILL_DIR}}/scripts/spec-driven.js modify` to list active changes. Ask which change to archive. If already specified, use it.

2. **Check for incomplete tasks** — run:
   ```
   node {{SKILL_DIR}}/scripts/spec-driven.js apply <name>
   ```
   If `remaining > 0`, stop — archiving is not allowed until all tasks are complete. List the incomplete tasks and suggest `/spec-driven-apply <name>` or `/spec-driven-cancel <name>`.

3. **Merge delta specs** — list all files in `.spec-driven/changes/<name>/specs/`:
    - If `specs/` is empty: proceed without confirmation — changes without spec impact are valid.
    - For each delta file (e.g. `specs/install/install-behavior.md`), merge into the corresponding main spec file (e.g. `.spec-driven/specs/install/install-behavior.md`):
     - **ADDED**: append the `### Requirement:` blocks to the target file (create it if it doesn't exist)
     - **MODIFIED**: locate the existing `### Requirement: <name>` block by name and replace it in place
     - **REMOVED**: locate the `### Requirement: <name>` block by name and delete it; remove the file if it becomes empty
     - If the delta file contains mapping frontmatter, apply that frontmatter
       to the target main spec file before moving the change to archive
   - Briefly summarize what changed in `specs/` after merging.

4. **Update specs/INDEX.md** — after merging, update `.spec-driven/specs/INDEX.md`:
   - Add entries for any newly created spec files (with a one-line description)
   - Remove entries for any deleted spec files
   - Leave existing entries unchanged unless the file's scope changed
   - Run `node {{SKILL_DIR}}/scripts/spec-driven.js verify-spec-mappings` and
     fix mapping frontmatter errors before archive closeout

5. **Archive the change** — run:
   ```
   node {{SKILL_DIR}}/scripts/spec-driven.js archive <name>
   ```
   This moves the entire change directory (including questions.md) to the archive.
   If `.spec-driven/roadmap/` exists, the command also reconciles milestone declared
   status and regenerates `.spec-driven/roadmap/INDEX.md` for any milestone affected by
   the archived change.

6. **Confirm** — report the result:
   - Where the change was moved to (e.g. `.spec-driven/changes/archive/2024-01-15-<name>/`)
   - Any milestone declared status or roadmap index entry that changed because of archive
   - Suggest running `/spec-driven-propose` if there's follow-up work

## Rules
- Always check for incomplete tasks before archiving
- Never archive a change with incomplete tasks
- Always state which steps are script-executed and which are AI-executed
- Always merge delta specs before archiving — this is a hard gate, not optional
- If `changes/<name>/specs/` is empty, proceed without confirmation — changes without spec impact are valid
- Deleting requirements or empty spec files in `.spec-driven/specs/` is allowed when applying `REMOVED` delta entries
- Do not delete the change directory manually — archive the change by running the archive command
- Keep implementation and test mappings in frontmatter, not in requirement
  prose