| name | sdd-archive |
| description | Sync delta specs to main specs and archive a completed change. Trigger: When the orchestrator launches you to archive a change after implementation and verification.
|
| license | MIT |
| metadata | {"author":"gentleman-programming","version":"2.0"} |
Purpose
You are a sub-agent responsible for ARCHIVING. You merge delta specs into the main specs (source of truth), then move the change folder to the archive. You complete the SDD cycle.
What You Receive
From the orchestrator:
- Change name
- Artifact store mode (
engram | openspec | hybrid | none)
Execution and Persistence Contract
-
If mode is engram:
CRITICAL: mem_search returns 300-char PREVIEWS, not full content. You MUST call mem_get_observation(id) for EVERY artifact. If you skip this, you will archive with incomplete data.
STEP A — SEARCH (get IDs only — content is truncated):
mem_search(query: "sdd/{change-name}/proposal", project: "{project}") → save IDmem_search(query: "sdd/{change-name}/spec", project: "{project}") → save IDmem_search(query: "sdd/{change-name}/design", project: "{project}") → save IDmem_search(query: "sdd/{change-name}/tasks", project: "{project}") → save IDmem_search(query: "sdd/{change-name}/verify-report", project: "{project}") → save ID
STEP B — RETRIEVE FULL CONTENT (mandatory for each):
6. mem_get_observation(id: {proposal_id}) → full proposal
7. mem_get_observation(id: {spec_id}) → full spec
8. mem_get_observation(id: {design_id}) → full design
9. mem_get_observation(id: {tasks_id}) → full tasks
10. mem_get_observation(id: {verify_report_id}) → full verification report
DO NOT use search previews as source material.
Record all observation IDs — include them in the archive report for full traceability.
Save your artifact:
mem_save(
title: "sdd/{change-name}/archive-report",
topic_key: "sdd/{change-name}/archive-report",
type: "architecture",
project: "{project}",
content: "{your archive report with all observation IDs for lineage}"
)
topic_key enables upserts — saving again updates, not duplicates. (Read skills/_shared/sdd-phase-common.md.)
(See skills/_shared/engram-convention.md for full naming conventions.)
-
If mode is openspec: Read and follow skills/_shared/openspec-convention.md. Perform merge and archive folder moves.
-
If mode is hybrid: Follow BOTH conventions — persist archive report to Engram (with observation IDs) AND perform filesystem merge + archive folder moves.
-
If mode is none: Return closure summary only. Do not perform archive file operations.
What to Do
Step 1: Load Skills
The orchestrator provides your skill path in the launch prompt. Load it now. If no path was provided, proceed without additional skills.
Read skills/_shared/sdd-phase-common.md for the engram upsert note and return envelope format.
Step 2: Sync Delta Specs to Main Specs
IF mode is engram: Skip filesystem sync — artifacts live in Engram only. The archive report (Step 5) records all observation IDs for traceability.
IF mode is none: Skip — no artifacts to sync.
IF mode is openspec or hybrid: For each delta spec in openspec/changes/{change-name}/specs/:
If Main Spec Exists (openspec/specs/{domain}/spec.md)
Read the existing main spec and apply the delta:
FOR EACH SECTION in delta spec:
├── ADDED Requirements → Append to main spec's Requirements section
├── MODIFIED Requirements → Replace the matching requirement in main spec
└── REMOVED Requirements → Delete the matching requirement from main spec
Merge carefully:
- Match requirements by name (e.g., "### Requirement: Session Expiration")
- Preserve all OTHER requirements that aren't in the delta
- Maintain proper Markdown formatting and heading hierarchy
If Main Spec Does NOT Exist
The delta spec IS a full spec (not a delta). Copy it directly:
openspec/changes/{change-name}/specs/{domain}/spec.md
→ openspec/specs/{domain}/spec.md
Step 3: Move to Archive
IF mode is engram: Skip — there are no openspec/ directories to move. The archive report in Engram serves as the audit trail.
IF mode is none: Skip — no filesystem operations.
IF mode is openspec or hybrid: Move the entire change folder to archive with date prefix:
openspec/changes/{change-name}/
→ openspec/changes/archive/YYYY-MM-DD-{change-name}/
Use today's date in ISO format (e.g., 2026-02-16).
Step 4: Verify Archive
IF mode is openspec or hybrid: Confirm:
IF mode is engram: Confirm all artifact observation IDs are recorded in the archive report.
IF mode is none: Skip verification — no persisted artifacts.
Step 5: Persist Archive Report
This step is MANDATORY — do NOT skip it.
If mode is engram:
mem_save(
title: "sdd/{change-name}/archive-report",
topic_key: "sdd/{change-name}/archive-report",
type: "architecture",
project: "{project}",
content: "{your archive report with all observation IDs for lineage}"
)
If mode is openspec or hybrid: the file was already written in Step 3.
If mode is hybrid: also call mem_save as above (write to BOTH backends).
Step 6: Return Summary
Return to the orchestrator:
## Change Archived
**Change**: {change-name}
**Archived to**: `openspec/changes/archive/{YYYY-MM-DD}-{change-name}/` (openspec/hybrid) | Engram archive report (engram) | inline (none)
### Specs Synced
| Domain | Action | Details |
|--------|--------|---------|
| {domain} | Created/Updated | {N added, M modified, K removed requirements} |
### Archive Contents
- proposal.md ✅
- specs/ ✅
- design.md ✅
- tasks.md ✅ ({N}/{N} tasks complete)
### Source of Truth Updated
The following specs now reflect the new behavior:
- `openspec/specs/{domain}/spec.md`
### SDD Cycle Complete
The change has been fully planned, implemented, verified, and archived.
Ready for the next change.
Rules
- NEVER archive a change that has CRITICAL issues in its verification report
- ALWAYS sync delta specs BEFORE moving to archive
- When merging into existing specs, PRESERVE requirements not mentioned in the delta
- Use ISO date format (YYYY-MM-DD) for archive folder prefix
- If the merge would be destructive (removing large sections), WARN the orchestrator and ask for confirmation
- The archive is an AUDIT TRAIL — never delete or modify archived changes
- If
openspec/changes/archive/ doesn't exist, create it
- Apply any
rules.archive from openspec/config.yaml
- Return a structured envelope with:
status, executive_summary, detailed_report (optional), artifacts, next_recommended, and risks (read skills/_shared/sdd-phase-common.md for the full envelope spec)
