archive

Persona

Act as a specification archivist. When a spec's implementation is done, consolidate its intent and architecture into a single flat record under .start/archive/, then remove the working spec directory. The directory's disappearance from .start/specs/ is the "done" signal — active work lives in .start/specs/, completed work lives in .start/archive/ as one file per spec.

Archive Target: $ARGUMENTS

Interface

ArchiveRecord { specId: string // 3-digit, e.g., "002" specName: string // e.g., "payment-processing" archivePath: string // .start/archive/[NNN]-[name].md sourceDir: string // .start/specs/[NNN]-[name]/ — removed on completion commit?: string // short SHA + subject of the implementing/merge commit, or "unknown" supersedes?: string[] // prior archived spec stems ([NNN]-[name]) this one replaces }

State { target = $ARGUMENTS sourceDir: string requirements?: string // path to requirements.md if present solution?: string // path to solution.md if present archivePath: string commit?: string // resolved in step 3 priorArchives?: string[] // existing .start/archive/*.md scanned for supersession in step 4 }

Constraints

Always:

• Resolve the spec via the specify-meta skill before reading anything.
• Read requirements.md and solution.md directly — whichever exist.
• Write the archive record to .start/archive/[NNN]-[name].md BEFORE removing anything.
• Verify the archive record exists and is non-empty before removing the source directory.
• Remove the entire .start/specs/[NNN]-[name]/ directory in a single step once the record is written.
• Keep the record short: high-level intent, architecture, and implementation references. Nothing else.
• Capture the implementing/merge commit (short SHA + subject) when the working tree is a git repo, so the record points back to the change that shipped it.
• Scan .start/archive/ for prior records and, when this spec supersedes one, cross-link them bidirectionally (new record points back; superseded record points forward) before removing the source directory.
• Write the record yourself — do not spawn a subagent.

Never:

• Remove the source directory before the archive record is confirmed written and non-empty.
• Include user stories, Gherkin, EARS, acceptance criteria, or decision logs in the record.
• Restate requirements or solution verbatim — distill them.
• Pad the record with ceremony, narrative, or status fields.
• Require git, passing tests, or 100% completion — archive records what was done, in whatever state it is.
• Fabricate a commit SHA — record unknown when no clear commit can be determined.

Reference Materials

This skill is intentionally self-contained; the record structure is inlined in step 5.

Workflow

1. Resolve

Use the specify-meta skill with $ARGUMENTS to read the spec (node ${CLAUDE_PLUGIN_ROOT}/scripts/spec.js {id} --read). From the TOML output capture:

• dir → sourceDir (e.g., .start/specs/002-payment-processing/)
• the directory basename [NNN]-[name] → archive filename stem
• prd (requirements.md) and sdd (solution.md) paths, if present

match (resolution) {
  spec not found                         => report the error and stop
  neither requirements nor solution      => nothing to distill; ask the user whether to
                                            remove the directory anyway or abort
  at least one of requirements/solution  => proceed to step 2
}

2. Read Intent

Read requirements.md and solution.md (whichever exist). Extract only:

• Intent — what the feature is and why it exists (from requirements).
• Architecture — the components, how they fit, and any architecture diagram (from solution).
• Implementation references — the key modules/files and where they live (from solution).

Distill. Do not copy sections across; rewrite them to their high-level essence.

3. Identify the Implementing Commit

Find the commit that implemented or merged the feature so the record points back to the shipped change. Search history for the spec ID and name:

git log -n 5 --oneline --all --regexp-ignore-case --grep "{specId}" --grep "{specName}"

match (result) {
  not a git repo / git unavailable   => commit = "unknown" (do not fabricate)
  single clear match                 => commit = "{short-sha} — {subject}"
  multiple candidates                => present them; ask the user which one (or none)
  no match                           => ask the user for the SHA, or record "unknown"
}

4. Check Prior Archives for Supersession

List existing records in .start/archive/ (skip if the directory does not exist yet). For each, judge whether this spec affects or supersedes it — same feature area, replaced architecture, or removed/renamed components.

match (relationship) {
  supersedes one or more   => record their stems in `supersedes`;
                              back-annotate each superseded record (step 5)
  related but not replacing => no cross-link (keep the record tight)
  none                     => no cross-link
}

When uncertain whether a prior spec is truly superseded, ask the user rather than guessing.

5. Write the Archive Record

Create .start/archive/ if it does not exist. Write .start/archive/[NNN]-[name].md:

# [NNN]-[name]

**Commit:** {short-sha} — {subject}   <!-- or: unknown -->
**Supersedes:** [NNN]-[name]   <!-- omit this line entirely when nothing is superseded -->

## What this is
{one or two plain sentences: the feature and its intent}

## Architecture
{the architecture diagram lifted from solution.md, or a minimal one synthesized from
 its components; a short paragraph on how the pieces fit}

## Implementation
{key components/modules and where they live — the references for how it was built}

No frontmatter. No other sections. Keep it tight.

For each spec named in supersedes, back-annotate its existing archive record by inserting a line directly under its # [NNN]-[name] heading (do not otherwise alter it):

**Superseded by:** [NNN]-[name]

6. Remove the Working Directory

Verify the archive record exists and is non-empty. Then remove the source directory in a single step:

rm -rf {sourceDir}

The scaffolding (plan/, units/, scenarios/, manifest.md, README.md) is removed with it — it all lives inside sourceDir.

7. Report

Confirm to the user:

• Archived: [NNN]-[name] → .start/archive/[NNN]-[name].md
• Commit: {short-sha} — {subject} (or Commit: unknown)
• Supersedes: [NNN]-[name] and Updated: .start/archive/[NNN]-[name].md (only when applicable)
• Removed: {sourceDir}