agentleFS
MaicololiverasMaicololiveras/praxisgenai-agent-orchestrator/skills/sdd-archive/SKILL.md

sdd-archive

Skill1 starsChanged 8 months agoMITView on GitHub

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.

3 other projects use a version of this, 1 of them edited.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

17 rules. About 0 are common, 7 are distinctive, and 10 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 10

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read and follow skills/_shared/persistence-contract.md for mode resolution rules.

    line 24
  2. Very specific:

    If mode is engram:

    line 26
  3. Very specific:

    If mode is openspec: Read and follow skills/_shared/openspec-convention.md.

    line 55
  4. Very specific:

    If mode is hybrid: Follow BOTH conventions — persist archive report to Engram (with observation IDs) AND perform filesystem merge + archive …

    line 56
  5. Very specific:

    If mode is none: Return closure summary only.

    line 57
  6. Very specific:

    If engram not available or not found: read .atl/skill-registry.md from the project root

    line 66
  7. Distinctive:

    If neither exists: proceed without skills (not an error)

    line 67
  8. Distinctive:

    Read the existing main spec and apply the delta:

    line 77
  9. Very specific:

    Use today's date in ISO format (e.g., 2026-02-16).

    line 110
  10. Very specific:

    If mode is openspec or hybrid: the file was already written in Step 3.

    line 135
  11. Very specific:

    If mode is hybrid: also call mem_save as above (write to BOTH backends).

    line 137
  12. Distinctive:

    NEVER archive a change that has CRITICAL issues in its verification report

    line 171
  13. Distinctive:

    ALWAYS sync delta specs BEFORE moving to archive

    line 172
  14. Distinctive:

    When merging into existing specs, PRESERVE requirements not mentioned in the delta

    line 173
  15. Distinctive:

    Use ISO date format (YYYY-MM-DD) for archive folder prefix

    line 174
  16. Distinctive:

    If the merge would be destructive (removing large sections), WARN the orchestrator and ask for confirmation

    line 175
  17. Very specific:

    If openspec/changes/archive/ doesn't exist, create it

    line 177

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

Read and follow skills/_shared/persistence-contract.md for mode resolution rules.

  • If mode is engram:

    Read ALL artifacts (two-step for each — search returns truncated previews):

    1. mem_search(query: "sdd/{change-name}/proposal", project: "{project}") → get ID
    2. mem_get_observation(id: {id}) → full proposal
    3. mem_search(query: "sdd/{change-name}/spec", project: "{project}") → get ID
    4. mem_get_observation(id: {id}) → full spec
    5. mem_search(query: "sdd/{change-name}/design", project: "{project}") → get ID
    6. mem_get_observation(id: {id}) → full design
    7. mem_search(query: "sdd/{change-name}/tasks", project: "{project}") → get ID
    8. mem_get_observation(id: {id}) → full tasks
    9. mem_search(query: "sdd/{change-name}/verify-report", project: "{project}") → get ID
    10. mem_get_observation(id: {id}) → full verification report

    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.

    (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 Skill Registry

Do this FIRST, before any other work.

  1. Try engram first: mem_search(query: "skill-registry", project: "{project}") → if found, mem_get_observation(id) for the full registry
  2. If engram not available or not found: read .atl/skill-registry.md from the project root
  3. If neither exists: proceed without skills (not an error)

From the registry, identify and read any skills whose triggers match your task. Also read any project convention files listed in the registry.

Step 2: Sync Delta Specs to Main Specs

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:

# Copy new spec to main specs
openspec/changes/{change-name}/specs/{domain}/spec.md
  → openspec/specs/{domain}/spec.md

Step 3: Move to Archive

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

Confirm:

  • Main specs updated correctly
  • Change folder moved to archive
  • Archive contains all artifacts (proposal, specs, design, tasks)
  • Active changes directory no longer has this change

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}/

### 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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.