OpenCode command directory: `command/` vs `commands/`

[calionauta]

While reading through the OpenSpec OpenCode adapter, I noticed that generated commands are written to a singular directory:

  .opencode/command/

Specifically, in: src/core/command-generation/adapters/opencode.ts there is a hard-coded path similar to:

path.join('.opencode', 'command', `opsx-${commandId}.md`)

From what I understand, the current OpenCode documentation describes the plural form as the standard structure:

  .opencode/commands/
  ~/.config/opencode/commands/

I also noticed that the docs mention singular directory names may still be supported for backward compatibility, so it’s very possible that I’m missing some context here.

Questions:

1. Is OpenSpec intentionally targeting command/ (singular) for backward compatibility with OpenCode?
2. Given that the OpenCode docs describe commands/ as the standard, would it make sense to consider switching the adapter to the plural form, or supporting both to better align with upstream?

Thanks!

[21st-connector]

Task completed.

The comment has been posted on issue #748. Here's a summary of what was included:

Key findings:

1. All active code uses singular command/ — the adapter (opencode.ts:20), legacy cleanup (legacy-cleanup.ts:52), docs (supported-tools.md:33), and tests all consistently use .opencode/command/.

2. Historical migration: The archived specs show the project originally used plural commands/ in Sept 2025, then deliberately switched to singular command/ around Oct 2025. No rationale was documented for this change.

3. OpenCode is the only outlier — every other adapter in the codebase (Claude, Cursor, Factory, etc.) uses plural directory names.

4. 4 files would need changes if switching to plural, plus the legacy cleanup module would need to handle both paths for backward compatibility.

5. Related issue Bug: Command arguments not being passed to .opencode/command templates #153 (closed) was linked as prior art confirming the singular path has been in use since Oct 2025.

---

View full conversation

Powered by 1Code

[21st-connector]

Codebase Analysis

Good catch — this is a real inconsistency worth discussing. Here's what the codebase shows:

Current state: singular command/ throughout active code

All active code uses singular .opencode/command/:

File	Line	Path used
src/core/command-generation/adapters/opencode.ts	L20	path.join('.opencode', 'command', ...)
src/core/legacy-cleanup.ts	L52	'.opencode/command/openspec-*.md'
docs/supported-tools.md	L33	.opencode/command/
test/core/command-generation/adapters.test.ts	L447	path.join('.opencode', 'command', 'opsx-explore.md')

Historical context: started as commands/ (plural), switched to command/ (singular)

The archived specs tell the story of a migration:

• Sept 2025 (2025-09-29-add-slash-command-support/tasks.md L19–20): Original implementation used plural .opencode/commands/
• Oct 2025 (2025-10-14-add-codex-slash-command-support/specs/cli-init/spec.md L36): Switched to singular .opencode/command/
• All specs from Oct 2025 onward consistently use singular command/ in update specs

This suggests the change from commands/ → command/ was deliberate, made around October 2025.

OpenCode is the only adapter using singular naming

Every other tool adapter uses plural directory names:

Tool	Commands directory
Claude	.claude/commands/opsx/
Cursor	.cursor/commands/
Factory	.factory/commands/
Windsurf	.windsurf/workflows/
Continue	.continue/prompts/
OpenCode	.opencode/command/ (singular)

Files that would need updating

If the decision is to switch to plural commands/, these files would need changes:

1. src/core/command-generation/adapters/opencode.ts:20 — the adapter path
2. src/core/legacy-cleanup.ts:52 — legacy cleanup glob pattern (would need to handle both command/ and commands/ for backward compat)
3. docs/supported-tools.md:33 — documentation table
4. test/core/command-generation/adapters.test.ts:447 — test assertion

Related issue

• Bug: Command arguments not being passed to .opencode/command templates #153 (closed) — "Bug: Command arguments not being passed to .opencode/command templates" — also references the singular command/ path, confirming it has been in use since at least Oct 2025.

Summary

The singular command/ appears to have been an intentional choice made in Oct 2025, but there's no code comment or commit message explaining the rationale. Given that OpenCode's own docs now describe commands/ (plural) as the standard, it may be worth aligning — but the legacy cleanup module would need to handle both paths during the transition.