fix(opencode): transform command references from colon to hyphen format (#626)

* Add OpenCode files to gitignore

* docs(changes): add opencode-command-references change artifacts

* fix(opencode): transform command references from colon to hyphen format

Author: webrgp

.gitignore

@@ -149,3 +149,7 @@ CLAUDE.md
 # Pnpm
 .pnpm-store/
 result
+
+# OpenCode
+.opencode/
+opencode.json

openspec/changes/archive/2026-01-30-opencode-command-references/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-01-30

openspec/changes/archive/2026-01-30-opencode-command-references/README.md

@@ -0,0 +1,3 @@
+# opencode-command-references
+
+Transform /opsx: to /opsx- in both commands and skills for OpenCode

openspec/changes/archive/2026-01-30-opencode-command-references/design.md

@@ -0,0 +1,70 @@
+## Context
+
+OpenCode is one of many supported AI tools. Each tool has:
+- A **command adapter** (in `src/core/command-generation/adapters/`) for generating tool-specific command files
+- **Skills** generated via `generateSkillContent()` in `src/core/shared/skill-generation.ts`
+
+Currently:
+- Commands go through the adapter system which can transform content per-tool
+- Skills use a single shared function with no tool-specific transformation
+
+The templates in `src/core/templates/skill-templates.ts` use Claude's colon-based format (`/opsx:new`) as the canonical format. Tools that use different formats need transformation at generation time.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Transform all `/opsx:` command references to `/opsx-` for OpenCode in both commands and skills
+- Create a shared, reusable transformation utility
+- Keep the transformation opt-in via a callback parameter (not hard-coded tool detection)
+
+**Non-Goals:**
+- Modifying the canonical template format (templates stay with `/opsx:`)
+- Applying transformation to other tools (only OpenCode for now)
+- Creating a full adapter system for skills (overkill for current needs)
+
+## Decisions
+
+### Decision 1: Shared Utility Function
+
+**Choice**: Create `transformToHyphenCommands()` in `src/utils/command-references.ts`
+
+**Rationale**: 
+- Single source of truth for the transformation logic
+- Can be used by both command adapter and skill generation
+- Easy to test in isolation
+- Follows existing utils pattern in the codebase
+
+**Alternatives considered**:
+- Inline the transformation in each location - Duplicates logic, harder to maintain
+
+### Decision 2: Callback Parameter for Skill Generation
+
+**Choice**: Add optional `transformInstructions?: (instructions: string) => string` parameter to `generateSkillContent()`
+
+**Rationale**:
+- Flexible - callers define the transformation, not the generation function
+- No coupling - `generateSkillContent()` doesn't need to know about tool formats
+- Extensible - could support other transformations in the future
+- Follows inversion of control principle
+
+**Alternatives considered**:
+- Add tool ID parameter and switch on it - Creates coupling, harder to extend
+- Create skill adapter system parallel to commands - Over-engineering for current needs
+- Transform in templates directly - Breaks single-source-of-truth principle
+
+### Decision 3: Apply at Generation Sites
+
+**Choice**: Pass transformer in `init.ts` and `update.ts` when `tool.value === 'opencode'`
+
+**Rationale**:
+- These are the only two places that generate skills
+- Simple conditional check, no new abstractions needed
+- Easy to extend to other tools if needed later
+
+## Risks / Trade-offs
+
+| Risk | Mitigation |
+|------|------------|
+| Other `/opsx:` patterns exist that shouldn't be transformed | All occurrences in templates are command invocations - verified by inspection |
+| Future tools may need same transformation | Utility is shared and easy to reuse; can add to other tools' generation |
+| Callback adds complexity to function signature | Optional parameter with sensible default (no transformation) |

openspec/changes/archive/2026-01-30-opencode-command-references/proposal.md

@@ -0,0 +1,32 @@
+## Why
+
+OpenCode uses hyphen-based command syntax (`/opsx-new`) but our templates contain colon-based references (`/opsx:new`). This creates inconsistency where generated command files and skill files contain references that don't match the actual command invocation syntax, confusing both the AI and users.
+
+## What Changes
+
+- Create a shared transformation utility (`transformToHyphenCommands`) for converting `/opsx:` to `/opsx-`
+- Update the OpenCode command adapter to transform body text using this utility
+- Add an optional `transformInstructions` callback parameter to `generateSkillContent()`
+- Update `init.ts` and `update.ts` to pass the transformer when generating skills for OpenCode
+
+## Capabilities
+
+### New Capabilities
+
+None - this is a bug fix, not a new capability.
+
+### Modified Capabilities
+
+None - no spec-level behavior changes. This is an implementation fix in the OpenCode adapter and skill generation that doesn't change any external requirements or contracts.
+
+## Impact
+
+- **Code**: 
+  - `src/utils/command-references.ts` (new file)
+  - `src/utils/index.ts` (export)
+  - `src/core/shared/skill-generation.ts` (add callback parameter)
+  - `src/core/command-generation/adapters/opencode.ts` (use transformer)
+  - `src/core/init.ts` (pass transformer for OpenCode)
+  - `src/core/update.ts` (pass transformer for OpenCode)
+- **Users**: OpenCode users will see correct `/opsx-` command references in both generated command files AND skill files
+- **Other tools**: No impact - transformation only applies to OpenCode

openspec/changes/archive/2026-01-30-opencode-command-references/specs/no-changes.md

@@ -0,0 +1,9 @@
+# No Spec Changes
+
+This is a bug fix that doesn't modify any external requirements or contracts.
+
+The proposal's Capabilities section indicates:
+- **New Capabilities**: None
+- **Modified Capabilities**: None
+
+No spec files are needed for this implementation-only fix.

openspec/changes/archive/2026-01-30-opencode-command-references/tasks.md

@@ -0,0 +1,22 @@
+## 1. Implementation
+
+- [x] 1.1 Create `src/utils/command-references.ts` with `transformToHyphenCommands()` function
+- [x] 1.2 Export `transformToHyphenCommands` from `src/utils/index.ts`
+- [x] 1.3 Update `generateSkillContent()` in `src/core/shared/skill-generation.ts` to accept optional `transformInstructions` callback
+- [x] 1.4 Update OpenCode adapter in `src/core/command-generation/adapters/opencode.ts` to use `transformToHyphenCommands()` for body text
+- [x] 1.5 Update `init.ts` to pass transformer when generating skills for OpenCode
+- [x] 1.6 Update `update.ts` to pass transformer when generating skills for OpenCode
+
+## 2. Testing
+
+- [x] 2.1 Create `test/utils/command-references.test.ts` with unit tests for `transformToHyphenCommands()`
+- [x] 2.2 Add test to `test/core/command-generation/adapters.test.ts` for OpenCode body transformation
+- [x] 2.3 Add test to `test/core/shared/skill-generation.test.ts` for transformer callback
+
+## 3. Verification
+
+- [x] 3.1 Run `npx vitest run test/utils/command-references.test.ts test/core/command-generation/adapters.test.ts test/core/shared/skill-generation.test.ts` to ensure tests pass
+- [x] 3.2 Run `pnpm run build` to ensure no TypeScript errors
+- [x] 3.3 Run `openspec init --tools opencode` in a temp directory and verify:
+  - Command files in `.opencode/command/` contain `/opsx-` references (not `/opsx:`)
+  - Skill files in `.opencode/skills/` contain `/opsx-` references (not `/opsx:`)

src/core/command-generation/adapters/opencode.ts

@@ -6,6 +6,7 @@
 
 import path from 'path';
 import type { CommandContent, ToolCommandAdapter } from '../types.js';
+import { transformToHyphenCommands } from '../../../utils/command-references.js';
 
 /**
  * OpenCode adapter for command generation.
@@ -20,11 +21,14 @@ export const opencodeAdapter: ToolCommandAdapter = {
   },
 
   formatFile(content: CommandContent): string {
+    // Transform command references from colon to hyphen format for OpenCode
+    const transformedBody = transformToHyphenCommands(content.body);
+
     return `---
 description: ${content.description}
 ---
 
-${content.body}
+${transformedBody}
 `;
   },
 };

src/core/init.ts

@@ -11,6 +11,7 @@ import ora from 'ora';
 import * as fs from 'fs';
 import { createRequire } from 'module';
 import { FileSystemUtils } from '../utils/file-system.js';
+import { transformToHyphenCommands } from '../utils/command-references.js';
 import {
   AI_TOOLS,
   OPENSPEC_DIR_NAME,
@@ -440,7 +441,9 @@ export class InitCommand {
           const skillFile = path.join(skillDir, 'SKILL.md');
 
           // Generate SKILL.md content with YAML frontmatter including generatedBy
-          const skillContent = generateSkillContent(template, OPENSPEC_VERSION);
+          // Use hyphen-based command references for OpenCode
+          const transformer = tool.value === 'opencode' ? transformToHyphenCommands : undefined;
+          const skillContent = generateSkillContent(template, OPENSPEC_VERSION, transformer);
 
           // Write the skill file
           await FileSystemUtils.writeFile(skillFile, skillContent);

src/core/shared/skill-generation.ts

@@ -101,11 +101,17 @@ export function getCommandContents(): CommandContent[] {
  *
  * @param template - The skill template
  * @param generatedByVersion - The OpenSpec version to embed in the file
+ * @param transformInstructions - Optional callback to transform the instructions content
  */
 export function generateSkillContent(
   template: SkillTemplate,
-  generatedByVersion: string
+  generatedByVersion: string,
+  transformInstructions?: (instructions: string) => string
 ): string {
+  const instructions = transformInstructions
+    ? transformInstructions(template.instructions)
+    : template.instructions;
+
   return `---
 name: ${template.name}
 description: ${template.description}
@@ -117,6 +123,6 @@ metadata:
   generatedBy: "${generatedByVersion}"
 ---
 
-${template.instructions}
+${instructions}
 `;
 }