feat: add /opsx:archive command for archiving completed changes #451
Conversation
Add `/opsx:archive` slash command to complete the OPSX workflow lifecycle. This command archives completed changes in the experimental workflow with: - Change selection prompt (if not specified) - Artifact completion check using `openspec status --json` - Task completion check (parsing tasks.md for `- [ ]`) - Spec sync prompt (offers `/opsx:sync` before archiving if specs exist) - Archive to `openspec/changes/archive/YYYY-MM-DD-<name>/` - Clear output formatting for success, warnings, and errors This completes the OPSX command suite: - /opsx:new - Start a change - /opsx:continue - Create next artifact - /opsx:ff - Fast-forward all artifacts - /opsx:apply - Implement tasks - /opsx:sync - Sync delta specs - /opsx:archive - Archive completed change (NEW)
📝 WalkthroughWalkthroughThis pull request introduces a new Changes
Sequence Diagram(s)sequenceDiagram
actor User
participant Archive as /opsx:archive<br/>Command
participant OpenSpec as OpenSpec<br/>System
participant TasksMD as tasks.md<br/>Parser
participant ArtifactGraph as Artifact<br/>Status
participant FileSystem as File<br/>System
User->>Archive: Invoke /opsx:archive [optional: change-name]
alt Change name not provided
Archive->>Archive: Prompt user to select<br/>active change
User->>Archive: Select change
end
Archive->>ArtifactGraph: Check artifact<br/>completion status
ArtifactGraph-->>Archive: Artifact status
alt Incomplete artifacts detected
Note over Archive: ⚠️ Warn user about<br/>incomplete items
Archive->>User: List incomplete artifacts +<br/>ask for confirmation
alt User rejects
User-->>Archive: Cancel
Archive-->>User: Abort archive
end
end
Archive->>FileSystem: Check for tasks.md
alt tasks.md exists
FileSystem-->>TasksMD: Read tasks.md
TasksMD->>TasksMD: Parse for - [ ]<br/>incomplete tasks
TasksMD-->>Archive: Incomplete task count
alt Incomplete tasks found
Note over Archive: ⚠️ Warn with count
Archive->>User: Confirm to proceed
alt User rejects
User-->>Archive: Cancel
Archive-->>User: Abort archive
end
end
end
Archive->>FileSystem: Check for specs/
alt specs/ directory exists
rect rgb(230, 245, 255)
Note over Archive,User: Delta specs found—<br/>offer sync
Archive->>User: Prompt: Run /opsx:sync?
alt User accepts
User->>OpenSpec: Run /opsx:sync
OpenSpec-->>Archive: Sync results
else User declines
User-->>Archive: Skip sync
end
end
end
rect rgb(200, 255, 200)
Note over Archive,FileSystem: Archive operation
Archive->>FileSystem: Create archive/<br/>if missing
Archive->>FileSystem: Move change to<br/>archive/YYYY-MM-DD-\<name\>/
Archive->>FileSystem: Preserve .openspec.yaml
end
Archive->>User: ✓ Archive complete<br/>with summary<br/>(location, schema, warnings)
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~22 minutes Possibly related PRs
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Review CompleteYour review story is ready! Comment !reviewfast on this PR to re-generate the story. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (4)
openspec/changes/opsx-archive-command/proposal.md (2)
1-3: Condense the "Why" section to 1–2 sentences.Per coding guidelines, the Why section should be concise (1–2 sentences). Consider combining these into a single impactful statement about the motivation.
Current structure:
Sentence 1: Explains existing OPSX commands Sentence 2: Notes missing archive command Sentence 3: States the gap with regular `openspec archive`Could be condensed to:
Single statement: OPSX workflow lacks an archive command integration, forcing users to fall back to `openspec archive`, which doesn't honor schema-aware artifact tracking.
5-11: Add explicit breaking-change markers to "What Changes" bullets (even if none apply).Per coding guidelines, the What Changes section should use breaking-change markers for items that introduce backward-incompatible changes. While this feature appears purely additive, explicitly marking these as non-breaking (e.g.,
[non-breaking]or similar notation) would improve clarity and guideline compliance.Suggested format:
- [non-breaking] Add `/opsx:archive` slash command... - [non-breaking] Use artifact graph to check completion... ...src/commands/artifact-workflow.ts (1)
31-31: Consider breaking the import statement into multiple lines.The import statement is quite long with 12 functions. While functionally correct, splitting it across multiple lines would improve readability:
🔎 Suggested refactor for readability
-import { getNewChangeSkillTemplate, getContinueChangeSkillTemplate, getApplyChangeSkillTemplate, getFfChangeSkillTemplate, getSyncSpecsSkillTemplate, getArchiveChangeSkillTemplate, getOpsxNewCommandTemplate, getOpsxContinueCommandTemplate, getOpsxApplyCommandTemplate, getOpsxFfCommandTemplate, getOpsxSyncCommandTemplate, getOpsxArchiveCommandTemplate } from '../core/templates/skill-templates.js'; +import { + getNewChangeSkillTemplate, + getContinueChangeSkillTemplate, + getApplyChangeSkillTemplate, + getFfChangeSkillTemplate, + getSyncSpecsSkillTemplate, + getArchiveChangeSkillTemplate, + getOpsxNewCommandTemplate, + getOpsxContinueCommandTemplate, + getOpsxApplyCommandTemplate, + getOpsxFfCommandTemplate, + getOpsxSyncCommandTemplate, + getOpsxArchiveCommandTemplate, +} from '../core/templates/skill-templates.js';src/core/templates/skill-templates.ts (1)
1053-1157: Clarify sync execution in the command template.The skill template (line 1108) clarifies: "execute /opsx:sync logic (use the openspec-sync-specs skill)"
The command template (line 1354) only says: "execute
/opsx:synclogic" without clarification.For consistency, the command template should also specify to use the openspec-sync-specs approach or invoke /opsx:sync directly.
🔎 Suggested fix for consistency
**If delta specs exist:** - Prompt: "This change has delta specs. Would you like to sync them to main specs before archiving?" - - If user confirms, execute \`/opsx:sync\` logic + - If user confirms, execute \`/opsx:sync\` logic (use the /opsx:sync command) - Proceed with archive regardless of sync choiceAlso applies to: 1298-1448
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (7)
openspec/changes/opsx-archive-command/.openspec.yamlopenspec/changes/opsx-archive-command/design.mdopenspec/changes/opsx-archive-command/proposal.mdopenspec/changes/opsx-archive-command/specs/opsx-archive-skill/spec.mdopenspec/changes/opsx-archive-command/tasks.mdsrc/commands/artifact-workflow.tssrc/core/templates/skill-templates.ts
🧰 Additional context used
📓 Path-based instructions (4)
openspec/changes/**/*.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Scaffold proposal using
proposal.md,tasks.md, optionaldesign.md, and delta specs underopenspec/changes/<id>/
Files:
openspec/changes/opsx-archive-command/proposal.mdopenspec/changes/opsx-archive-command/tasks.mdopenspec/changes/opsx-archive-command/specs/opsx-archive-skill/spec.mdopenspec/changes/opsx-archive-command/design.md
openspec/changes/*/proposal.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Ensure
proposal.mdincludes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)
Files:
openspec/changes/opsx-archive-command/proposal.md
openspec/changes/*/tasks.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Ensure
tasks.mdcontains implementation checklist with numbered sections and checkbox items
Files:
openspec/changes/opsx-archive-command/tasks.md
openspec/changes/**/specs/**/spec.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
openspec/changes/**/specs/**/spec.md: Use## ADDED|MODIFIED|REMOVED|RENAMED Requirementsheaders in spec delta files
Include at least one#### Scenario:per requirement in spec delta files
Use#### Scenario: Nameformat (4 hashtags) for scenario headers, not bullets or bold text
Use## ADDED Requirementsfor new orthogonal capabilities that can stand alone; use## MODIFIED Requirementsfor behavior changes of existing requirements
When using MODIFIED Requirements, paste the full requirement block including header and all scenarios
Files:
openspec/changes/opsx-archive-command/specs/opsx-archive-skill/spec.md
🧠 Learnings (12)
📓 Common learnings
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Use `openspec archive <change-id> --skip-specs --yes` for tooling-only changes
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Use `openspec archive <change-id> --skip-specs --yes` for tooling-only changes
Applied to files:
openspec/changes/opsx-archive-command/.openspec.yamlopenspec/changes/opsx-archive-command/proposal.mdopenspec/changes/opsx-archive-command/tasks.mdsrc/commands/artifact-workflow.tssrc/core/templates/skill-templates.tsopenspec/changes/opsx-archive-command/specs/opsx-archive-skill/spec.mdopenspec/changes/opsx-archive-command/design.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/*.md : Scaffold proposal using `proposal.md`, `tasks.md`, optional `design.md`, and delta specs under `openspec/changes/<id>/`
Applied to files:
openspec/changes/opsx-archive-command/.openspec.yamlopenspec/changes/opsx-archive-command/tasks.mdopenspec/changes/opsx-archive-command/specs/opsx-archive-skill/spec.mdopenspec/changes/opsx-archive-command/design.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Check `openspec/project.md` for project conventions before creating specs
Applied to files:
openspec/changes/opsx-archive-command/.openspec.yaml
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/tasks.md : Ensure `tasks.md` contains implementation checklist with numbered sections and checkbox items
Applied to files:
openspec/changes/opsx-archive-command/tasks.md
📚 Learning: 2025-11-25T01:08:02.839Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Use `@/openspec/AGENTS.md` to learn how to create and apply change proposals, spec format and conventions, and project structure and guidelines
Applied to files:
openspec/changes/opsx-archive-command/specs/opsx-archive-skill/spec.md
📚 Learning: 2025-11-25T01:08:02.839Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Always open `@/openspec/AGENTS.md` when the request mentions planning or proposals (words like proposal, spec, change, plan), introduces new capabilities, breaking changes, architecture shifts, or performance/security work, or sounds ambiguous and needs the authoritative spec before coding
Applied to files:
openspec/changes/opsx-archive-command/specs/opsx-archive-skill/spec.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : Use `## ADDED Requirements` for new orthogonal capabilities that can stand alone; use `## MODIFIED Requirements` for behavior changes of existing requirements
Applied to files:
openspec/changes/opsx-archive-command/specs/opsx-archive-skill/spec.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : When using MODIFIED Requirements, paste the full requirement block including header and all scenarios
Applied to files:
openspec/changes/opsx-archive-command/specs/opsx-archive-skill/spec.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : Include at least one `#### Scenario:` per requirement in spec delta files
Applied to files:
openspec/changes/opsx-archive-command/specs/opsx-archive-skill/spec.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : Use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements` headers in spec delta files
Applied to files:
openspec/changes/opsx-archive-command/specs/opsx-archive-skill/spec.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Create `design.md` only when needed: cross-cutting changes, new external dependencies, significant data model changes, security/performance complexity, or pre-coding ambiguity
Applied to files:
openspec/changes/opsx-archive-command/design.md
🪛 LanguageTool
openspec/changes/opsx-archive-command/specs/opsx-archive-skill/spec.md
[style] ~37-~37: ‘without warning’ might be wordy. Consider a shorter alternative.
Context: ...s have status done - THEN proceed without warning ### Requirement: Task Completion Check...
(EN_WORDINESS_PREMIUM_WITHOUT_WARNING)
🔇 Additional comments (6)
openspec/changes/opsx-archive-command/.openspec.yaml (1)
1-2: Configuration metadata looks good.The YAML structure correctly records the schema type and creation date for this change. No issues detected.
openspec/changes/opsx-archive-command/tasks.md (1)
1-23: Excellent task checklist structure.The tasks.md file properly follows the coding guideline format with three numbered sections, each containing checkbox items in the standard
[x]format. The hierarchical numbering (1.1, 1.2, etc.) is clear, and all tasks are marked as complete. This provides good documentation of the implementation workflow.openspec/changes/opsx-archive-command/design.md (1)
1-84: LGTM! Well-structured design document.The design decisions are clearly articulated with strong rationale:
- Skill-only implementation avoids CLI duplication
- Agent-driven sync prompting maintains workflow flexibility
- Artifact graph integration provides schema-aware checking
- Identified risks have reasonable mitigations
This appropriately documents the cross-cutting nature of the archive feature and its integration points.
src/commands/artifact-workflow.ts (1)
801-906: LGTM! Archive feature properly integrated.The archive skill and command are correctly wired into the artifact workflow setup:
- Templates retrieved and included in skills/commands arrays
- Directory and file naming consistent with other OPSX features
- Usage documentation updated to include
/opsx:archiveThe integration follows the established pattern for experimental workflow commands.
openspec/changes/opsx-archive-command/specs/opsx-archive-skill/spec.md (1)
1-122: LGTM! Specification follows guidelines correctly.The spec delta properly uses:
## ADDED Requirementsheader for the new archive capability#### Scenario:format (4 hashtags) for all scenarios- At least one scenario per requirement
The requirements comprehensively cover the archive workflow including completion checks, sync prompting, and various output states.
src/core/templates/skill-templates.ts (1)
1069-1069: Theopenspec list --jsoncommand is properly defined and supports the--jsonflag for programmatic output. No action needed.
Summary
/opsx:archiveslash command to archive completed changes in the experimental workflowopenspec artifact-experimental-setupto generate skill and command filesChanges
New Features
openspec status --jsonto verify all artifacts are done (warns if not)- [ ](warns if incomplete)/opsx:syncbefore archiving if delta specs existarchive/YYYY-MM-DD-<name>/, preserves.openspec.yamlFiles Modified
src/core/templates/skill-templates.ts- Added archive skill and command templatessrc/commands/artifact-workflow.ts- Added archive to setup command outputOPSX Command Suite (Complete)
/opsx:new/opsx:continue/opsx:ff/opsx:apply/opsx:sync/opsx:archiveTest plan
.claude/skills/openspec-archive-change/SKILL.md.claude/commands/opsx/archive.md/opsx:archivein usage instructions🤖 Generated with Claude Code
Summary by CodeRabbit
New Features
/opsx:archiveslash command for archiving completed experimental changesDocumentation
✏️ Tip: You can customize this high-level summary in your review settings.