Back to Details

openspec-archive-change

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Archive a completed change in the experimental workflow.
Input: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
Steps
  1. If no change name provided, prompt for selection
    Run 
    openspec list --json
    to get available changes. Use the AskUserQuestion tool to let the user select.
    Show only active changes (not already archived). Include the schema used for each change if available.
    IMPORTANT: Do NOT guess or auto-select a change. Always let the user choose.
  2. Check artifact completion status
    Run 
    openspec status --change "<name>" --json
    to check artifact completion.
    Parse the JSON to understand:
    • schemaName
      : The workflow being used
    • artifacts
      : List of artifacts with their status (
      done
      or other)
    If any artifacts are not 
    done
    :
    • Display warning listing incomplete artifacts
    • Use AskUserQuestion tool to confirm user wants to proceed
    • Proceed if user confirms
  3. Check task completion status
    Read the tasks file (typically 
    tasks.md
    ) to check for incomplete tasks.
    Count tasks marked with 
    - [ ]
    (incomplete) vs 
    - [x]
    (complete).
    If incomplete tasks found:
    • Display warning showing count of incomplete tasks
    • Use AskUserQuestion tool to confirm user wants to proceed
    • Proceed if user confirms
    If no tasks file exists: Proceed without task-related warning.
  4. Assess delta spec sync state
    Check for delta specs at 
    openspec/changes/<name>/specs/
    . If none exist, proceed without sync prompt.
    If delta specs exist:
    • Compare each delta spec with its corresponding main spec at 
      openspec/specs/<capability>/spec.md
    • Determine what changes would be applied (adds, modifications, removals, renames)
    • Show a combined summary before prompting
    Prompt options:
    • If changes needed: "Sync now (recommended)", "Archive without syncing"
    • If already synced: "Archive now", "Sync anyway", "Cancel"
    If user chooses sync, execute /opsx:sync logic (use the openspec-sync-specs skill). Proceed to archive regardless of choice.
  5. Perform the archive
    Create the archive directory if it doesn't exist:
    bash
    mkdir -p openspec/changes/archive
    Generate target name using current date: 
    YYYY-MM-DD-<change-name>
    Check if target already exists:
    • If yes: Fail with error, suggest renaming existing archive or using different date
    • If no: Move the change directory to archive
    bash
    mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
  6. Display summary
    Show archive completion summary including:
    • Change name
    • Schema that was used
    • Archive location
    • Whether specs were synced (if applicable)
    • Note about any warnings (incomplete artifacts/tasks)
Output On Success
undefined
归档实验工作流中已完成的变更。
输入：（可选）指定变更名称。如果未指定，检查是否可以从对话上下文推断。如果信息模糊或存在歧义，必须提示用户选择可用的变更。
步骤
  1. 未提供变更名称时，提示用户选择
    运行
    openspec list --json
    获取可用变更。使用AskUserQuestion tool让用户进行选择。
    仅展示活跃变更（即尚未归档的变更）。 如果有可用信息，需包含每个变更所使用的schema。
    重要提示：请勿猜测或自动选择变更，必须始终让用户自行选择。
  2. 检查工件完成状态
    运行
    openspec status --change "<name>" --json
    检查工件完成情况。
    解析JSON以了解：
    • schemaName
      : 所使用的工作流
    • artifacts
      : 工件列表及其状态（
      done
      或其他状态）
    若存在未标记为
    done
    的工件：
    • 显示包含未完成工件的警告信息
    • 使用AskUserQuestion tool确认用户是否要继续
    • 若用户确认，则继续执行
  3. 检查任务完成状态
    读取任务文件（通常为
    tasks.md
    ）以检查未完成任务。
    统计标记为
    - [ ]
    （未完成）和
    - [x]
    （已完成）的任务数量。
    若发现未完成任务：
    • 显示包含未完成任务数量的警告信息
    • 使用AskUserQuestion tool确认用户是否要继续
    • 若用户确认，则继续执行
    若任务文件不存在： 无需任务相关警告，直接继续。
  4. 评估delta规格同步状态
    检查
    openspec/changes/<name>/specs/
    路径下是否存在delta规格。若不存在，无需提示同步，直接继续。
    若存在delta规格：
    • 将每个delta规格与其对应的主规格（位于
      openspec/specs/<capability>/spec.md
      ）进行对比
    • 确定将应用的变更类型（添加、修改、删除、重命名）
    • 在提示用户前展示合并后的汇总信息
    提示选项：
    • 若需要同步变更：“立即同步（推荐）”、“不同步直接归档”
    • 若已完成同步：“立即归档”、“仍要同步”、“取消”
    若用户选择同步，则执行/opsx:sync逻辑（使用openspec-sync-specs skill）。无论用户选择如何，均继续执行归档操作。
  5. 执行归档操作
    若归档目录不存在，则创建该目录：
    bash
    mkdir -p openspec/changes/archive
    使用当前日期生成目标名称：
    YYYY-MM-DD-<change-name>
    检查目标是否已存在：
    • 若已存在：报错并提示用户重命名现有归档或使用其他日期
    • 若不存在：将变更目录移动至归档目录
    bash
    mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
  6. 展示汇总信息
    展示归档完成汇总，包括：
    • 变更名称
    • 所使用的schema
    • 归档位置
    • 规格是否已同步（若适用）
    • 关于警告信息的说明（未完成工件/任务）
成功时的输出
undefined

Archive Complete

归档完成

Change: <change-name> Schema: <schema-name> Archived to: openspec/changes/archive/YYYY-MM-DD-<name>/ Specs: ✓ Synced to main specs (or "No delta specs" or "Sync skipped")
All artifacts complete. All tasks complete.

**Guardrails**

- Always prompt for change selection if not provided
- Use artifact graph (openspec status --json) for completion checking
- Don't block archive on warnings - just inform and confirm
- Preserve .openspec.yaml when moving to archive (it moves with the directory)
- Show clear summary of what happened
- If sync is requested, use openspec-sync-specs approach (agent-driven)
- If delta specs exist, always run the sync assessment and show the combined summary before prompting
变更： <change-name> Schema： <schema-name> 归档至： openspec/changes/archive/YYYY-MM-DD-<name>/ 规格： ✓ 已同步至主规格（或“无delta规格”或“已跳过同步”）
所有工件已完成。所有任务已完成。

**约束规则**

- 若未提供变更名称，必须始终提示用户选择
- 使用工件图谱（openspec status --json）进行完成情况检查
- 请勿因警告信息阻止归档操作 - 仅需告知用户并确认
- 移动至归档目录时保留.openspec.yaml文件（该文件会随目录一同移动）
- 清晰展示操作汇总信息
- 若用户请求同步，使用openspec-sync-specs方法（由Agent驱动）
- 若存在delta规格，必须在提示用户前执行同步评估并展示合并后的汇总信息