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

webrgp · 2026-01-30T21:23:46Z

Summary

Fix OpenCode command references to use hyphen format (/opsx-new) instead of colon format (/opsx:)
Add transformToHyphenCommands() utility for consistent transformation
Apply transformation to both command files and skill files for OpenCode

Changes

New: src/utils/command-references.ts - Shared transformation utility
Modified: OpenCode adapter, skill generation, init.ts, update.ts
Tests: 25 new tests covering transformation and integration

Why

OpenCode uses hyphen-based command syntax but templates use colon-based format, causing inconsistency in generated files.

Summary by CodeRabbit

Release Notes

Bug Fixes
- Fixed OpenCode command reference formatting in generated skill files to consistently use hyphen-based syntax instead of colon-based syntax.
Tests
- Added test coverage for command reference transformation to verify correct formatting across various scenarios and edge cases.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

coderabbitai · 2026-01-30T21:24:06Z

📝 Walkthrough

Walkthrough

This PR implements a transformation system for OpenCode command references, converting /opsx: syntax to /opsx- format. It introduces a new utility function, extends skill generation to accept optional transformation callbacks, and integrates the transformer into the OpenCode adapter and initialization flows.

Changes

Cohort / File(s)	Summary
Project Configuration `.gitignore`	Added ignore rules for OpenCode project artifacts (.opencode/ and opencode.json).
OpenSpec Documentation `openspec/changes/archive/2026-01-30-opencode-command-references/...`	Added comprehensive design documentation, proposal, tasks, README, and configuration files outlining the command reference transformation feature and implementation strategy.
Command Reference Utility `src/utils/command-references.ts`, `src/utils/index.ts`	Created new transformToHyphenCommands utility function for converting /opsx: to /opsx- syntax; exported from utils module.
Skill Generation Enhancement `src/core/shared/skill-generation.ts`	Extended generateSkillContent signature to accept optional transformInstructions callback parameter for applying custom transformations to skill instructions.
OpenCode Adapter & Flow Integration `src/core/command-generation/adapters/opencode.ts`, `src/core/init.ts`, `src/core/update.ts`	Integrated transformer into OpenCode adapter for body text transformation; wired transformer through init and update flows, conditionally applied when tool.value === 'opencode'.
Test Coverage `test/core/command-generation/adapters.test.ts`, `test/core/shared/skill-generation.test.ts`, `test/utils/command-references.test.ts`	Added unit tests for transformer utility, adapter transformation behavior, and skill generation callback functionality covering basic transformations, edge cases, and multiline content.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

feat(cli): add multi-provider skill generation support #556: Introduced the OpenCode adapter that this PR modifies to apply the hyphen-based command reference transformation.

Suggested labels

codex

Suggested reviewers

TabishB

Poem

🐰 The hyphen hops where colons stood,
Commands transform as they should—
/opsx-new, /opsx-apply with grace,
A cozy format in its place!

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and accurately summarizes the main change: transforming OpenCode command references from colon to hyphen format, which is the core objective of the PR.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

📝 Generate docstrings

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

vibe-kanban-cloud · 2026-01-30T21:26:35Z

Review Complete

Your review story is ready!

View Story

Comment !reviewfast on this PR to re-generate the story.

greptile-apps · 2026-01-30T21:27:02Z

Greptile Overview

Greptile Summary

This PR fixes command reference inconsistency in OpenCode by transforming /opsx: to /opsx- format throughout generated files.

Key Changes:

Created shared transformToHyphenCommands() utility for consistent transformation logic
Updated OpenCode adapter to transform command bodies
Extended generateSkillContent() with optional callback parameter for instruction transformation
Applied transformer conditionally in init.ts and update.ts when tool is OpenCode

Implementation Quality:

Clean separation of concerns with reusable utility function
Optional callback pattern maintains flexibility without coupling
Comprehensive test coverage (25 tests across 3 test files)
Zero impact on non-OpenCode tools

Verification:
The transformation is correctly applied to both:

Command files via the OpenCode adapter
Skill files via the callback parameter in skill generation

Confidence Score: 5/5

This PR is safe to merge with minimal risk
Simple, well-tested bug fix with clear scope. The transformation logic is straightforward (regex replace), thoroughly tested (25 tests), and only affects OpenCode. No breaking changes, no complex logic, and the optional parameter approach ensures backward compatibility.
No files require special attention

Important Files Changed

Filename	Overview
src/utils/command-references.ts	New utility with simple regex-based transformation from `/opsx:` to `/opsx-`
src/core/command-generation/adapters/opencode.ts	Integrates transformer to convert command references in OpenCode command bodies
src/core/shared/skill-generation.ts	Adds optional callback parameter for transforming skill instructions
src/core/init.ts	Applies transformer conditionally when tool is OpenCode during initialization
src/core/update.ts	Applies transformer conditionally when tool is OpenCode during update (two locations)

Sequence Diagram

sequenceDiagram
    participant User
    participant InitUpdate as init.ts / update.ts
    participant SkillGen as skill-generation.ts
    participant OpenCodeAdapter as opencode.ts adapter
    participant Transformer as transformToHyphenCommands()
    participant FileSystem as File System

    User->>InitUpdate: Run openspec init/update --tools opencode
    
    Note over InitUpdate: Skill Generation Flow
    InitUpdate->>InitUpdate: Check if tool.value === 'opencode'
    InitUpdate->>SkillGen: generateSkillContent(template, version, transformToHyphenCommands)
    SkillGen->>Transformer: transformInstructions(template.instructions)
    Transformer->>Transformer: Replace /opsx: with /opsx-
    Transformer-->>SkillGen: Transformed instructions
    SkillGen-->>InitUpdate: Skill content with /opsx- references
    InitUpdate->>FileSystem: Write skill file to .opencode/skills/

    Note over InitUpdate: Command Generation Flow
    InitUpdate->>OpenCodeAdapter: formatFile(commandContent)
    OpenCodeAdapter->>Transformer: transformToHyphenCommands(content.body)
    Transformer->>Transformer: Replace /opsx: with /opsx-
    Transformer-->>OpenCodeAdapter: Transformed body
    OpenCodeAdapter-->>InitUpdate: Formatted command with /opsx- references
    InitUpdate->>FileSystem: Write command file to .opencode/command/

    FileSystem-->>User: OpenCode files with consistent /opsx- syntax

webrgp · 2026-01-30T21:32:26Z

src/core/update.ts

+          // Use hyphen-based command references for OpenCode
+          const transformer = tool.value === 'opencode' ? transformToHyphenCommands : undefined;
+          const skillContent = generateSkillContent(template, OPENSPEC_VERSION, transformer);


This approach works for the immediate fix, but we should look into a more robust way to handle tool-specific transformations as we add support for more tools, similar to how it's handled in src/core/command-generation/.

@webrgp Yeah you're right, it's something I mentioned here as well: #603 (comment)

Didn't think this would bite us back so soon. The way you've done it makes sense, but yes we need to find a better way to handle these transformations between different coding agents.

Yeah, totally agree! This was a quick fix to unblock things, but it's definitely not the long-term solution.

I like the idea of mirroring what we already have for commands - basically a skill adapter system that sits alongside the command adapters. Each tool could have its own adapter that knows how to transform content if needed. That way we keep all the tool-specific quirks in one place instead of sprinkling if (tool === 'opencode') checks everywhere.

Happy to open an issue or start a change for this if you want!

TabishB

This is amazing thank you, you're right though that this dosen't fix this problem at the root. I think we need to find a better pattern to do this reliably for all coding agent.s

TabishB · 2026-01-30T23:15:43Z

@webrgp Seems like there's quite a few HappyCog folks using OpenSpec! Would love to setup a slack-connect channel here if you guys are keen!

I've sent an email to Kyle from HappyCog since I had his email on file from the waitlist, but let me know if I should reach out to someone else!

webrgp added 3 commits January 30, 2026 15:25

Add OpenCode files to gitignore

84bef5f

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

2327595

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

caf68be

webrgp requested a review from TabishB as a code owner January 30, 2026 21:23

webrgp commented Jan 30, 2026

View reviewed changes

TabishB approved these changes Jan 30, 2026

View reviewed changes

TabishB merged commit 697738b into Fission-AI:main Jan 30, 2026
10 checks passed

TabishB mentioned this pull request Jan 30, 2026

chore: add changeset for OpenCode command reference fix #627

Merged

2 tasks

greptile-apps bot mentioned this pull request Jan 30, 2026

chore(release): version packages #628

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

Uh oh!

webrgp commented Jan 30, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

coderabbitai bot commented Jan 30, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Suggested reviewers

Poem

Uh oh!

vibe-kanban-cloud bot commented Jan 30, 2026

Uh oh!

greptile-apps bot commented Jan 30, 2026

Uh oh!

webrgp Jan 30, 2026

Uh oh!

TabishB Jan 30, 2026

Uh oh!

webrgp Jan 30, 2026

Uh oh!

TabishB left a comment

Uh oh!

Uh oh!

TabishB commented Jan 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

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

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

Uh oh!

Conversation

webrgp commented Jan 30, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Why

Summary by CodeRabbit

Release Notes

Uh oh!

coderabbitai bot commented Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Suggested reviewers

Poem

Uh oh!

vibe-kanban-cloud bot commented Jan 30, 2026

Review Complete

Uh oh!

greptile-apps bot commented Jan 30, 2026

Greptile Overview

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Sequence Diagram

Uh oh!

webrgp Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

TabishB Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

webrgp Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

TabishB left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

TabishB commented Jan 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

webrgp commented Jan 30, 2026 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Jan 30, 2026 •

edited

Loading