mirror of
https://github.com/Fission-AI/OpenSpec.git
synced 2026-09-14 20:16:53 +08:00
Tabish Bidiwale
111 lines
4.3 KiB
Markdown
111 lines
4.3 KiB
Markdown
# CLI Archive Command Specification
|
|
|
|
## Purpose
|
|
The archive command moves completed changes from the active changes directory to the archive folder with date-based naming, following OpenSpec conventions.
|
|
|
|
## Command Syntax
|
|
```bash
|
|
openspec archive [change-name] [--yes|-y]
|
|
```
|
|
|
|
Options:
|
|
- `--yes`, `-y`: Skip confirmation prompts (for automation)
|
|
|
|
## Behavior
|
|
|
|
### Change Selection
|
|
WHEN no change-name is provided
|
|
THEN display interactive list of available changes (excluding archive/)
|
|
AND allow user to select one
|
|
|
|
WHEN change-name is provided
|
|
THEN use that change directly
|
|
AND validate it exists
|
|
|
|
### Task Completion Check
|
|
The command SHALL scan the change's tasks.md file for incomplete tasks (marked with `- [ ]`)
|
|
|
|
WHEN incomplete tasks are found
|
|
THEN display all incomplete tasks to the user
|
|
AND prompt for confirmation to continue
|
|
AND default to "No" for safety
|
|
|
|
WHEN all tasks are complete OR no tasks.md exists
|
|
THEN proceed with archiving without prompting
|
|
|
|
### Archive Process
|
|
The archive operation SHALL:
|
|
1. Create archive/ directory if it doesn't exist
|
|
2. Generate target name as `YYYY-MM-DD-[change-name]` using current date
|
|
3. Check if target directory already exists
|
|
4. Update main specs from the change's future state specs (see Spec Update Process below)
|
|
5. Move the entire change directory to the archive location
|
|
|
|
WHEN target archive already exists
|
|
THEN fail with error message
|
|
AND do not overwrite existing archive
|
|
|
|
WHEN move succeeds
|
|
THEN display success message with archived name and list of updated specs
|
|
|
|
### Spec Update Process
|
|
Before moving the change to archive, the command SHALL update main specs to reflect the deployed reality:
|
|
|
|
WHEN the change contains specs in `changes/[name]/specs/`
|
|
THEN:
|
|
1. Analyze which specs will be affected by comparing with existing specs
|
|
2. Display a summary of spec updates to the user (see Confirmation Behavior below)
|
|
3. Prompt for confirmation unless `--yes` flag is provided
|
|
4. If confirmed, for each capability spec in the change directory:
|
|
- Copy the spec from `changes/[name]/specs/[capability]/spec.md` to `openspec/specs/[capability]/spec.md`
|
|
- Create the target directory structure if it doesn't exist
|
|
- Overwrite existing spec files (specs represent current reality, change specs are the new reality)
|
|
- Track which specs were updated for the success message
|
|
|
|
WHEN no specs exist in the change
|
|
THEN skip the spec update step
|
|
AND proceed with archiving
|
|
|
|
### Confirmation Behavior
|
|
The spec update confirmation SHALL:
|
|
- Display a clear summary showing:
|
|
- Which specs will be created (new capabilities)
|
|
- Which specs will be updated (existing capabilities)
|
|
- The source path for each spec
|
|
- Format the confirmation prompt as:
|
|
```
|
|
The following specs will be updated:
|
|
|
|
NEW specs to be created:
|
|
- cli-archive (from changes/add-archive-command/specs/cli-archive/spec.md)
|
|
|
|
EXISTING specs to be updated:
|
|
- cli-init (from changes/update-init-command/specs/cli-init/spec.md)
|
|
|
|
Update 2 specs and archive 'add-archive-command'? [y/N]:
|
|
```
|
|
- Default to "No" for safety (require explicit "y" or "yes")
|
|
- Skip confirmation when `--yes` or `-y` flag is provided
|
|
|
|
WHEN user declines the confirmation
|
|
THEN abort the entire archive operation
|
|
AND display message: "Archive cancelled. No changes were made."
|
|
AND exit with non-zero status code
|
|
|
|
## Error Handling
|
|
|
|
SHALL handle the following error conditions:
|
|
- Missing openspec/changes/ directory
|
|
- Change not found
|
|
- Archive target already exists
|
|
- File system permissions issues
|
|
|
|
## Why These Decisions
|
|
|
|
**Interactive selection**: Reduces typing and helps users see available changes
|
|
**Task checking**: Prevents accidental archiving of incomplete work
|
|
**Date prefixing**: Maintains chronological order and prevents naming conflicts
|
|
**No overwrite**: Preserves historical archives and prevents data loss
|
|
**Spec updates before archiving**: Specs in the main directory represent current reality; when a change is deployed and archived, its future state specs become the new reality and must replace the main specs
|
|
**Confirmation for spec updates**: Provides visibility into what will change, prevents accidental overwrites, and ensures users understand the impact before specs are modified
|
|
**--yes flag for automation**: Allows CI/CD pipelines to archive without interactive prompts while maintaining safety by default for manual use |