Add OpenCode support and rename to @wbern/agent-instructions by wbern · Pull Request #5 · wbern/claude-instructions

wbern · 2026-02-25T21:52:30Z

Summary

Merge PR feat: add OpenCode support as installation target alongside Claude Code #4 from hevolx/agent-instructions adding OpenCode as a supported agent
Add --agent CLI flag (opencode, claude, both) for targeting specific agents
Rename npm package from @wbern/claude-instructions to @wbern/agent-instructions
Keep claude-instructions CLI binary as a backwards-compatible alias
Strip Claude-only frontmatter (allowed-tools) when generating for OpenCode
Check agent-native template file first (AGENTS.md for OpenCode, CLAUDE.md for Claude)

Breaking changes

npm package renamed: @wbern/claude-instructions → @wbern/agent-instructions
After merging, deprecate old package: npm deprecate @wbern/claude-instructions "Renamed to @wbern/agent-instructions"
Rename GitHub repo to wbern/agent-instructions before merging (so the release lands on the correct repo)

Testing this branch

npx github:wbern/claude-instructions#feature/opencode-support --scope=project --agent=opencode

Test plan

957 tests pass with 100% coverage
--agent=opencode generates to .opencode/commands/
--agent=claude generates to .claude/commands/
--agent=both generates to both directories
allowed-tools frontmatter stripped for OpenCode output
Template injection reads AGENTS.md first for OpenCode
claude-instructions CLI binary still works as alias
Skills generate to correct agent directory
Non-interactive mode defaults to OpenCode with warning when --agent omitted

cc @hevolx — would appreciate if you could test the branch with OpenCode

* [feat] added .opencode and skills to directories in cli-generator.ts * [feat] updated getDestinationPath() to handle both agents * feat: rename package to @hevolx/agent-instructions with OpenCode support - Rename npm package from @wbern/claude-instructions to @hevolx/agent-instructions - Rename CLI binary from claude-instructions to agent-instructions - Add OpenCode as primary target (--agent=opencode default) - Generate .opencode/commands/ and .opencode/skills/ artifacts - Update all URLs, tests, and snapshots to hevolx/agent-instructions - Refactor shared frontmatter parsing into transformFrontmatter helper - Add missing test coverage for getSkillsPath, truncatePath, agent cancel/both/claude paths

* [feat] added .opencode and skills to directories in cli-generator.ts * [feat] updated getDestinationPath() to handle both agents * feat: rename package to @hevolx/agent-instructions with OpenCode support - Rename npm package from @wbern/claude-instructions to @hevolx/agent-instructions - Rename CLI binary from claude-instructions to agent-instructions - Add OpenCode as primary target (--agent=opencode default) - Generate .opencode/commands/ and .opencode/skills/ artifacts - Update all URLs, tests, and snapshots to hevolx/agent-instructions - Refactor shared frontmatter parsing into transformFrontmatter helper - Add missing test coverage for getSkillsPath, truncatePath, agent cancel/both/claude paths * ci: fix scoped npm package public publishing

* [feat] added .opencode and skills to directories in cli-generator.ts * [feat] updated getDestinationPath() to handle both agents * feat: rename package to @hevolx/agent-instructions with OpenCode support - Rename npm package from @wbern/claude-instructions to @hevolx/agent-instructions - Rename CLI binary from claude-instructions to agent-instructions - Add OpenCode as primary target (--agent=opencode default) - Generate .opencode/commands/ and .opencode/skills/ artifacts - Update all URLs, tests, and snapshots to hevolx/agent-instructions - Refactor shared frontmatter parsing into transformFrontmatter helper - Add missing test coverage for getSkillsPath, truncatePath, agent cancel/both/claude paths * ci: fix scoped npm package public publishing * ci: remove registry-url from setup-node to fix npm auth conflict

* [feat] added .opencode and skills to directories in cli-generator.ts * [feat] updated getDestinationPath() to handle both agents * feat: rename package to @hevolx/agent-instructions with OpenCode support - Rename npm package from @wbern/claude-instructions to @hevolx/agent-instructions - Rename CLI binary from claude-instructions to agent-instructions - Add OpenCode as primary target (--agent=opencode default) - Generate .opencode/commands/ and .opencode/skills/ artifacts - Update all URLs, tests, and snapshots to hevolx/agent-instructions - Refactor shared frontmatter parsing into transformFrontmatter helper - Add missing test coverage for getSkillsPath, truncatePath, agent cancel/both/claude paths * ci: fix scoped npm package public publishing * ci: remove registry-url from setup-node to fix npm auth conflict * chore: restore wbern/claude-instructions branding for upstream PR * docs: restore file priority and usage stats sections to README * fix: Update GitHub URL in AGENTS.md

hevolx

Checked thru the changed files, looks good. Going to test in an local clean environment now.

hevolx · 2026-02-26T20:43:37Z

Test Report - `feature/opencode-support`

Repo: github:wbern/claude-instructions#feature/opencode-support
Cloned to: /tmp/claude-instructions
Environment: Node.js v24.12.0, npm 11.7.0, Linux (Alacritty 0.13.2)
Tested: 2026-02-26

Setup

Initial test command did not work.

npx github:wbern/claude-instructions#feature/opencode-support --scope=project --agent=opencode

Temporary solution

# 1. Clone into /tmp/claude-instructions (directory name matters — see Test 1)
git clone https://github.com/wbern/claude-instructions.git \
  -b feature/opencode-support /tmp/claude-instructions

# 2. Install dependencies
cd /tmp/claude-instructions && npm install

# 3. Build the project (generates bin/cli.js)
npm run build

Build succeeded and generated bin/cli.js + 62 commands into .opencode/commands.

Test 1: 957 tests pass with 100% coverage

Steps:

cd /tmp/claude-instructions
npm test -- --reporter=verbose

Result: PARTIAL PASS

956/957 tests passed
1 test consistently times out: should generate skills via CLI --skills option in cli-integration.test.ts:266
Cause: The test has a hard 5000ms timeout that is too tight when the CLI is run inside a /tmp filesystem (tmpfs). This is a test design issue, not a code bug, the functionality itself works correctly (verified in Test 8).
Note: The project must be built with npm run build before running tests. Without the build, bin/cli.js is missing and 6 integration tests fail with Cannot find module.

Test 2: `--agent=opencode` generates to `.opencode/commands/`

Steps:

mkdir /tmp/test2-opencode && cd /tmp/test2-opencode
node /tmp/claude-instructions/bin/cli.js --scope=project --agent=opencode --overwrite

Result: PASS

└  Installed 30 commands to /tmp/test2-opencode/.opencode/commands

Directory structure: Only .opencode/ was created, no .claude/ directory.

Test 3: `--agent=claude` generates to `.claude/commands/`

Steps:

mkdir /tmp/test3-claude && cd /tmp/test3-claude
node /tmp/claude-instructions/bin/cli.js --scope=project --agent=claude --overwrite

Result: PASS

└  Installed 30 commands to /tmp/test3-claude/.claude/commands

Directory structure: Only .claude/ was created, no .opencode/ directory.

Test 4: `--agent=both` generates to both directories

Steps:

mkdir /tmp/test4-both && cd /tmp/test4-both
node /tmp/claude-instructions/bin/cli.js --scope=project --agent=both --overwrite

Result: PASS

└  Installed 60 commands to /tmp/test4-both/.opencode/commands

Directory structure: Both .claude/ (30 files) and .opencode/ (30 files) were created.

Test 5: `allowed-tools` frontmatter stripped for OpenCode output

Steps:

mkdir /tmp/test5-frontmatter && cd /tmp/test5-frontmatter
node /tmp/claude-instructions/bin/cli.js \
  --scope=project --agent=both --commands=code-review.md \
  --allowed-tools="Bash(git diff:*),Bash(git status:*)" --overwrite

Result: PASS

.claude/commands/code-review.md (frontmatter includes allowed-tools):

---
allowed-tools: Bash(git diff:*), Bash(git status:*)
description: Code review using dynamic category detection...
argument-hint: (optional) [branch, PR#, or PR URL]
---

.opencode/commands/code-review.md (frontmatter has allowed-tools stripped):

---
description: Code review using dynamic category detection...
argument-hint: (optional) [branch, PR#, or PR URL]
---

Test 6: Template injection reads `AGENTS.md` first for OpenCode

Steps:

mkdir /tmp/test6-template && cd /tmp/test6-template

# Create AGENTS.md with <agent-commands-template> block
cat > AGENTS.md << 'EOF'
# OpenCode Project Instructions
This project uses Python 3.11.

<agent-commands-template>
## OpenCode Context (from AGENTS.md)
Injected from AGENTS.md. Use Python conventions.
</agent-commands-template>
EOF

# Create CLAUDE.md with <claude-commands-template> block
cat > CLAUDE.md << 'EOF'
# Claude Project Instructions
This project uses TypeScript.

<claude-commands-template>
## Claude Context (from CLAUDE.md)
Injected from CLAUDE.md. Use TypeScript conventions.
</claude-commands-template>
EOF

node /tmp/claude-instructions/bin/cli.js \
  --scope=project --agent=both --commands=commit.md --overwrite

Result: PASS

.opencode/commands/commit.md (content from AGENTS.md):

## OpenCode Context (from AGENTS.md)
Injected from AGENTS.md. Use Python conventions.

.claude/commands/commit.md (content from CLAUDE.md):

## Claude Context (from CLAUDE.md)
Injected from CLAUDE.md. Use TypeScript conventions.

Test 7: `claude-instructions` CLI binary still works as alias

Steps:

cd /tmp/claude-instructions && npm link --force
which claude-instructions
claude-instructions --version

mkdir /tmp/test7-alias && cd /tmp/test7-alias
claude-instructions --scope=project --agent=opencode --commands=commit.md --overwrite

Result: PASS

/home/hevol/.local/share/mise/installs/node/24.12.0/bin/claude-instructions
2.11.0
└  Installed 1 commands to /tmp/test7-alias/.opencode/commands

Both agent-instructions and claude-instructions are defined in package.json under bin and point to the same ./bin/cli.js.

Test 8: Skills generate to correct agent directory

Steps:

# OpenCode
mkdir /tmp/test8-skills && cd /tmp/test8-skills
node /tmp/claude-instructions/bin/cli.js \
  --scope=project --agent=opencode --skills=tdd.md --overwrite

# Claude
mkdir /tmp/test8-skills-cl && cd /tmp/test8-skills-cl
node /tmp/claude-instructions/bin/cli.js \
  --scope=project --agent=claude --skills=tdd.md --overwrite

Result: PASS

OpenCode: Installed 1 skills to /tmp/test8-skills/.opencode/skills → .opencode/skills/tdd/SKILL.md
Claude: Installed 1 skills to /tmp/test8-skills-cl/.claude/skills → .claude/skills/tdd/SKILL.md

Test 9: Non-interactive mode defaults to OpenCode with warning when `--agent` omitted

Steps:

mkdir /tmp/test9-noagent && cd /tmp/test9-noagent
node /tmp/claude-instructions/bin/cli.js \
  --scope=project --commands=commit.md --overwrite

Result: PASS

Warning message displayed:

▲  No --agent specified. Defaulting to opencode.
   Pass --agent=claude or --agent=opencode explicitly.

Generates to .opencode/commands/, no .claude/ directory is created.

Summary

Test	Description	Result
1	957 tests with 100% coverage	⚠️ 956/957 (timeout in tmpfs)
2	`--agent=opencode` → `.opencode/commands/`	✅
3	`--agent=claude` → `.claude/commands/`	✅
4	`--agent=both` → both directories	✅
5	`allowed-tools` stripped for OpenCode	✅
6	Template injection reads `AGENTS.md` first	✅
7	`claude-instructions` alias works	✅
8	Skills to correct agent directory	✅
9	Default OpenCode with warning	✅

wbern · 2026-02-27T11:01:02Z

Final OpenCode Compatibility Assessment

Did a thorough pass over the full diff before merge. Here's where things stand:

What works

--agent=opencode routes commands to .opencode/commands/ correctly for all scopes (project, user, custom)
allowed-tools: stripping — two complementary mechanisms ensure Claude-only frontmatter never appears in OpenCode output (injection is skipped entirely + post-hoc stripping as safety net)
Skills system — --skills generates to .opencode/skills/ with proper paths for all scope/agent combinations
Template files — AGENTS.md is checked first for OpenCode, CLAUDE.md first for Claude, with fallback in both directions. Both <claude-commands-template> and <agent-commands-template> tags work
CLI UX — interactive mode presents agent selection first, non-interactive warns when --agent is omitted, success messages show agent-specific restart hints
--agent=both — generates to both directories, accumulates file counts, detects conflicts across both
Package rename — dual bin entry (agent-instructions + claude-instructions) maintains backward compatibility
Build process — build:commands uses --agent=both, cleans both directories, .gitignore excludes .opencode/ (generated at build time, not committed)
Test coverage — 957 tests passing, 100% code coverage, extensive OpenCode-specific tests added

Minor notes (non-blocking)

The README postinstall example doesn't include --agent=, which will trigger the default warning. Could add --agent=opencode or --agent=both to make it explicit — but the warning message handles this gracefully already.
Pre-commit hook only stages .claude/commands/ (correct since .opencode/ is gitignored), but a comment explaining the asymmetry could help future maintainers.

Verdict

Ready to merge. No blockers found.

@hevolx — thanks for cloning the repo, running through the install on Linux, and catching the test timeout and missing build step issues. That kind of hands-on testing is exactly what catches the things automated CI misses (filesystem performance differences, fresh-clone assumptions). Both findings are now addressed in 842b973.

hevolx and others added 6 commits February 21, 2026 18:04

[feat] generalized from claude -> opencode

d1407e7

chore(release): 1.0.0

70c08ff

hevolx reviewed Feb 26, 2026

View reviewed changes

hevolx approved these changes Feb 26, 2026

View reviewed changes

hevolx approved these changes Feb 27, 2026

View reviewed changes

feat: finalize OpenCode integration

693df49

wbern force-pushed the feature/opencode-support branch from fed98c6 to 693df49 Compare February 27, 2026 16:55

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add OpenCode support and rename to @wbern/agent-instructions#5

Add OpenCode support and rename to @wbern/agent-instructions#5
wbern wants to merge 7 commits intomainfrom
feature/opencode-support

wbern commented Feb 25, 2026

Uh oh!

hevolx left a comment

Uh oh!

hevolx commented Feb 26, 2026

Uh oh!

wbern commented Feb 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

wbern commented Feb 25, 2026

Summary

Breaking changes

Testing this branch

Test plan

Uh oh!

hevolx left a comment

Choose a reason for hiding this comment

Uh oh!

hevolx commented Feb 26, 2026

Test Report - feature/opencode-support

Setup

Test 1: 957 tests pass with 100% coverage

Test 2: --agent=opencode generates to .opencode/commands/

Test 3: --agent=claude generates to .claude/commands/

Test 4: --agent=both generates to both directories

Test 5: allowed-tools frontmatter stripped for OpenCode output

Test 6: Template injection reads AGENTS.md first for OpenCode

Test 7: claude-instructions CLI binary still works as alias

Test 8: Skills generate to correct agent directory

Test 9: Non-interactive mode defaults to OpenCode with warning when --agent omitted

Summary

Uh oh!

wbern commented Feb 27, 2026

Final OpenCode Compatibility Assessment

What works

Minor notes (non-blocking)

Verdict

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Test Report - `feature/opencode-support`

Test 2: `--agent=opencode` generates to `.opencode/commands/`

Test 3: `--agent=claude` generates to `.claude/commands/`

Test 4: `--agent=both` generates to both directories

Test 5: `allowed-tools` frontmatter stripped for OpenCode output

Test 6: Template injection reads `AGENTS.md` first for OpenCode

Test 7: `claude-instructions` CLI binary still works as alias

Test 9: Non-interactive mode defaults to OpenCode with warning when `--agent` omitted