AI commands and skills for `/opsx:archive` do not invoke `openspec archive` CLI, unlike official docs and tutorials

[ngbruce]

Summary

There is a discrepancy between:

1. The official OpenSpec CLI and documentation, which position openspec archive as the canonical way to archive a change and sync specs.
2. The auto-generated AI commands and skills that implement /opsx:archive, which instruct the LLM to perform manual file operations (read/write/mv) and do not call openspec archive.
   This has been partially raised in question: why achive skill or command relies on llm to manually merge specs why it does not use openspec archive cli command? #656, but I want to provide more concrete file paths and examples from the current templates.

---

Current Behavior

1. Official CLI: openspec archive

The OpenSpec CLI provides a dedicated lifecycle command for archiving changes:

openspec archive <change-name> --yes

This is documented as the standard way to:

• Validate the change
• Merge delta specs into the main specs under openspec/specs/
• Move the change directory into openspec/changes/archive/YYYY-MM-DD-<name>/
  Tutorials and docs consistently show openspec archive as the canonical archive step for humans.

2. OPSX workflow: /opsx:archive

In docs/opsx.md, /opsx:archive is described simply as:

/opsx:archive – Archive when done
and the example shows:

/opsx:archive   # Move to archive when done (prompts to sync specs if needed)

This implies that the system is responsible for “moving to archive” and syncing specs, but does not specify whether the LLM should call the CLI or do it manually.

3. Auto-generated AI commands (example: CodeBuddy)

According to docs/supported-tools.md, OpenSpec generates per-tool command and skill files.
For CodeBuddy the relevant paths are:

• Skills: .codebuddy/skills/openspec-*/SKILL.md
• Commands: .codebuddy/commands/opsx/<id>.md
  For the archive workflow, the generated files are:
• project\.codebuddy\commands\opsx\archive.md
• project\.codebuddy\skills\openspec-archive-change\SKILL.md
  From what I see in current templates (e.g. .opencode/skills/openspec-archive-change/SKILL.md in projects using OpenSpec), the openspec-archive-change skill instructs the LLM to:

1. Run openspec list --json and openspec status --json to pick a change and check artifacts.
2. Manually check tasks.md for incomplete tasks.
3. Manually compare delta specs under openspec/changes/<name>/specs/ with main specs under openspec/specs/<capability>/spec.md.
4. Manually create the archive directory and move the change:

   mkdir -p openspec/changes/archive
   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>

Notably, this skill does not invoke openspec archive at all.
It explicitly says:

If sync is requested, use openspec-sync-specs approach (agent-driven)
The auto-generated archive.md command file similarly does not mention calling openspec archive; it essentially points the LLM to the /opsx:archive workflow / skill, which then relies on manual file operations.

---

Why This Is Confusing

• From the CLI docs and tutorials, a human would run openspec archive <name> --yes and let the CLI handle merging and moving.
• From the AI’s perspective, the generated skills and commands make the LLM re-implement the same logic manually:
  • Reading and comparing spec files
  • Moving directories
  • Handling edge cases (incomplete artifacts, missing tasks, etc.)
    This raises a few questions:

1. Why doesn’t the generated skill just call openspec archive?
   Is there a known limitation (e.g. error handling, idempotency, JSON output, or missing flags) that makes it unsafe or unreliable for LLM agents to invoke the CLI?
2. Is the CLI behavior still considered experimental?
   Issues like Archive command moves changes to incorrect path (openspec/changes/archive) #412 (archive path problems) and Use git move for archive #709 (git history behavior) suggest the archive implementation has evolved. Is the current guidance for AI agents to manually implement archiving until the CLI stabilizes?
3. What is the intended integration story between CLI and skills?
   Should tools like CodeBuddy, Claude Code, Cursor, etc. eventually wrap openspec archive in their skills, or is the design to keep skills “pure” and let them drive the CLI through other commands (e.g. openspec status --json) while avoiding the archive command itself?

---

Suggested Improvement

If openspec archive is indeed the intended canonical entry point for archiving, I’d suggest:

1. Updating the skill templates so that openspec-archive-change (and equivalent skills for other tools) prefer calling openspec archive <name> --yes when the CLI is available, falling back to manual steps only if necessary.
2. Documenting the intended relationship between /opsx:archive and openspec archive in docs/opsx.md or docs/supported-tools.md – especially for tool vendors and skill authors.
3. Clarifying whether there are any missing CLI features (e.g. machine-readable output, dry-run mode, or better exit codes) that would make the CLI more suitable for LLM-driven workflows.

---

Related

• Issue question: why achive skill or command relies on llm to manually merge specs why it does not use openspec archive cli command? #656 – “why archive skill or command relies on llm to manually merge specs why it does not use openspec archive cli command?”
• docs/opsx.md – /opsx:archive description.
• docs/supported-tools.md – skill and command paths for CodeBuddy and other tools.
• Example of current skill implementation: .opencode/skills/openspec-archive-change/SKILL.md.