home / skills / bacoco / bmad-skills / openspec-change-closure

openspec-change-closure skill

safe

This skill archives completed OpenSpec changes by compiling metrics, learnings, and approvals into archive.md and updating specs accordingly.

npx playbooks add skill bacoco/bmad-skills --skill openspec-change-closure

Review the files below or copy the command above to add this skill to your agents.

Files (6)

SKILL.md

3.1 KB

---
name: openspec-change-closure
description: Archives completed L0-1 changes.
allowed-tools: ["Read", "Write", "Grep", "Bash"]
metadata:
  auto-invoke: true
  triggers:
    patterns:
      - "archive this change"
      - "close change"
      - "document change"
      - "finalize change"
      - "archive"
    keywords:
      - archive
      - close
      - document
      - finalize
      - complete
  capabilities:
    - change-archival
    - documentation
    - spec-merging
    - closure
  prerequisites:
    - implemented-code
  outputs:
    - archive-doc
    - merged-specs
    - closure-report
---

# OpenSpec Archive Skill

## When to Invoke

**Automatically activate when user:**
- Says "Archive this change", "Close the change", "Finalize change"
- Asks "Document this change", "Mark as complete", "Archive proposal [X]"
- Has completed an OpenSpec change that needs closure
- Mentions "archive", "close", "document", "finalize" with change context
- Uses words like: archive, close, document, finalize, complete, wrap up

**Specific trigger phrases:**
- "Archive this change"
- "Close change [proposal-id]"
- "Document the change"
- "Finalize the implementation"
- "Mark proposal [X] as complete"
- "Wrap up this change"

**Prerequisites:**
- OpenSpec change has been implemented
- Tests pass and validation is complete
- Deployment or rollout is done (or documented)

**Do NOT invoke when:**
- Change not yet implemented (use openspec-change-implementation)
- Tests failing or validation incomplete
- Missing approvals or sign-offs
- Change still in progress

**Auto-document:**
- Learnings and deviations
- Metrics (time, lines changed, tests added)
- Follow-up tasks if any

## Mission
Document the outcome of Level 0-1 work, ensuring artifacts, approvals, and follow-up actions are captured before closing the OpenSpec workflow.

## Inputs Required
- proposal: original proposal.md with approvals
- implementation_log: execution notes or commits from implement skill
- validation_evidence: test results or reviewer feedback

## Outputs
- Archive summary (`archive.md`) with outcomes, metrics, and learnings (template: `assets/archive-template.md.template`)
- Updated proposal/tasks reflecting completion status
- Deployment or rollback notes stored with project documentation
- Canonical specs in `openspec/specs/` synchronized with approved deltas

`scripts/archive_change.py` copies validated spec deltas from `openspec/changes/<change-id>/specs/` into `openspec/specs/`.

## Process
1. Verify closure conditions using `CHECKLIST.md`.
2. Gather final state: what shipped, what remains, and any deviations.
3. Record metrics, approvals, and validation evidence in `archive.md`.
4. Run `scripts/archive_change.py <change-id>` to merge spec deltas into `openspec/specs/`.
5. Capture learnings and recommended follow-up actions, then update artifacts and communicate closure.

## Quality Gates
All checklist items must pass before marking work as archived.

## Error Handling
- If validation evidence or approvals are missing, request them before closing.
- Surface outstanding tasks and assign owners if work cannot be fully archived.

Overview

This skill archives completed Level 0-1 OpenSpec changes by packaging outcomes, evidence, and canonical spec updates into the project archive. It ensures closure criteria are met, records final metrics and learnings, and synchronizes approved spec deltas into the canonical specs directory. The skill produces an archive summary and updates project artifacts to reflect completion.

How this skill works

The skill verifies closure conditions against a CHECKLIST and gathers inputs: original proposal, implementation logs, and validation evidence. It generates an archive.md summary using a template, records approvals, metrics, and deviations, and runs a script to merge validated spec deltas into openspec/specs/. If any required evidence or approvals are missing, it halts and requests remediation.

When to use it

A Level 0-1 OpenSpec change has been implemented and validated.
You need to finalize and document a change before marking it complete.
Tests pass, approvals are present, and deployment or rollout is done (or documented).
You want to capture learnings, metrics, and follow-up tasks before closing the workflow.
You need to publish approved spec deltas into the canonical specs directory.

Best practices

Confirm every checklist item in CHECKLIST.md before proceeding.
Collect and attach validation evidence (tests, reviewer feedback) to the implementation_log.
Record concrete metrics: time spent, lines changed, tests added, and rollout impact.
Document deviations from the proposal and rationale in archive.md for future audits.
Assign owners for any follow-up tasks and surface them in the updated proposal/tasks.

Example use cases

Developer asks to “Archive this change” after a successful rollout to production.
Release manager finalizes a small spec update and needs canonical specs synchronized.
QA provides passing validation evidence and you need to capture metrics and lessons learned.
Project lead wants an audit-ready archive of approvals, deployment notes, and rollback instructions.
Team performs post-implementation review and publishes follow-up tasks and owners.

FAQ

What inputs are required to run the archive process?

You must supply the original proposal with approvals, implementation_log (commits/execution notes), and validation_evidence (test results or reviewer feedback).

What happens if approvals or validation evidence are missing?

The skill will not complete the archive. It will surface outstanding items and request the missing approvals or evidence before proceeding.