Archive command fails when creating new spec file with REMOVED Requirements

[smileeunsong]

Problem

When archiving a change that creates a new spec file (openspec/specs/[capability]/spec.md), if the change delta includes REMOVED Requirements, the archive command fails with an error:

[capability]: target spec does not exist; only ADDED requirements are allowed for new specs. Aborted. No files were changed.

Expected Behavior

When creating a new spec file during archive, REMOVED Requirements should either be:

1. Ignored silently (since there's nothing to remove from a non-existent spec), or
2. Logged as a warning but not cause the archive to fail

Use Case

This occurs when refactoring existing functionality where:

• The change involves removing old fields/requirements
• The target spec file doesn't exist yet (first time documenting this capability)
• The change delta includes both ADDED Requirements (new fields) and REMOVED Requirements (old fields)

Example Scenario

I was refactoring a gift card entity:

• REMOVED: image and thumbnail fields
• ADDED: logo and backgroundColor fields

The openspec/specs/gift-card/spec.md file didn't exist, so the archive command failed even though the ADDED Requirements were valid for creating a new spec.

Workaround

Currently, the workaround is to manually remove REMOVED Requirements from the delta file before archiving, then re-add them after the spec file is created. This is cumbersome and error-prone.

Proposed Solution

The archive command should:

1. Check if the target spec file exists
2. If it doesn't exist and only ADDED Requirements are present → create the spec file (current behavior)
3. If it doesn't exist and both ADDED and REMOVED Requirements are present → create the spec file with only ADDED Requirements and log a warning about ignored REMOVED Requirements
4. If it exists → apply all deltas (ADDED, MODIFIED, REMOVED) as normal

Environment

• OpenSpec CLI version: 0.17.2
• Node.js version: >= 20.19.0

Additional Context

This is a common scenario when:

• Migrating from undocumented code to OpenSpec
• Refactoring existing features while documenting them for the first time
• Consolidating multiple fields into a single field

The current restriction makes sense for modifying existing specs, but is too strict for creating new ones.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Related Issues

• Bug: Archive validation fails despite requirement headers containing SHALL/MUST #159
• Feature request: automatically update project.md during archive #331
• Model tends to cheat around "no deltas found error" #194
• [Suggestion for Opencode Command] - Archiver Archived wrong Proposal #151
• Parser incorrectly treats hash symbols inside code blocks as markdown headers #312

🔗 Related PRs

#227 - chore: add changeset for AI assistants support and validation fixes [merged]
#283 - Fix Cline: use workflows instead of rules for slash commands [merged]
#301 - Document Gemini CLI slash command coverage [merged]
#335 - fix(opencode): remove hardcoded agent field from slash commands [merged]

👤 Suggested Assignees

• TabishB
• PeakMNA
• BobbyWang0120
• agladysh
• webboty

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!