@softspark/ai-toolkit 2.5.0 → 2.6.2

package/kb/reference/opencode-compatibility.md

@@ -0,0 +1,161 @@
+---
+title: "AI Toolkit - opencode Compatibility"
+category: reference
+service: ai-toolkit
+tags: [opencode, compatibility, install, skills, hooks, mcp, plugins]
+version: "1.0.0"
+created: "2026-04-16"
+last_updated: "2026-04-16"
+description: "Reference for how ai-toolkit integrates with opencode — AGENTS.md, subagents, slash commands, JS plugin hook bridge, and MCP merge into opencode.json."
+---
+
+# AI Toolkit - opencode Compatibility
+
+## Summary
+
+opencode (https://opencode.ai) is the 11th supported editor. `ai-toolkit install --editors opencode` (or `--editors all`) lays down a full native integration: shared `AGENTS.md`, per-agent `.opencode/agents/` files, per-command `.opencode/commands/` files, a JS plugin bridging toolkit Bash hooks to opencode lifecycle events, and MCP server merge into `opencode.json`.
+
+opencode also reads `CLAUDE.md` as a fallback, so a user without the native integration still gets baseline rules. The native path adds subagents, slash commands, hooks, and MCP.
+
+## Local Install Outputs
+
+`ai-toolkit install --local --editors opencode` generates:
+
+- `AGENTS.md` (shared with Codex CLI via distinct marker sections)
+- `.opencode/agents/ai-toolkit-*.md` (one per ai-toolkit agent, `mode: subagent`)
+- `.opencode/commands/ai-toolkit-*.md` (one per user-invocable skill, required `template: |` frontmatter field)
+- `.opencode/plugins/ai-toolkit-hooks.js` (JS plugin bridging Bash hooks)
+- `opencode.json` (MCP key merged from `.mcp.json`, user keys preserved)
+
+## Global Install Outputs
+
+`ai-toolkit install --editors opencode` (no `--local`) lays down:
+
+- `~/.config/opencode/AGENTS.md`
+- `~/.config/opencode/agents/ai-toolkit-*.md`
+- `~/.config/opencode/commands/ai-toolkit-*.md`
+- `~/.config/opencode/plugins/ai-toolkit-hooks.js`
+- `~/.config/opencode/opencode.json` (MCP merge, user keys preserved)
+
+Files land directly under `~/.config/opencode/` (no `.opencode/` nesting) because that is the global layout opencode expects per https://opencode.ai/docs/config/. Shared hook scripts stay in `~/.softspark/ai-toolkit/hooks/` and are referenced by the global JS plugin.
+
+## Editor Surface Comparison
+
+| Feature            | Claude Code | Codex CLI       | opencode                                  |
+|--------------------|-------------|-----------------|-------------------------------------------|
+| Rules file         | `CLAUDE.md` | `AGENTS.md`     | `AGENTS.md` + `CLAUDE.md` fallback        |
+| Subagents          | Yes         | No              | Yes (`mode: subagent`)                    |
+| Slash commands     | Skills      | Adapted skills  | Native commands with frontmatter          |
+| MCP                | Yes         | Yes             | Yes (`opencode.json`)                     |
+| Lifecycle hooks    | JSON config | `.codex/hooks`  | JS/TS plugins (~30+ events)               |
+| Global config dir  | `~/.claude` | `~/.codex`      | `~/.config/opencode`                      |
+| Project config dir | `.claude`   | `.agents`       | `.opencode`                               |
+
+## Shared AGENTS.md
+
+opencode and Codex CLI both read `AGENTS.md`. The toolkit emits two distinct marker-bounded sections in a single file, so installing both editors does not clobber either. The Codex section is produced by `generate_codex.py`; the opencode section is produced by `generate_opencode.py`. Both sections reuse `codex_skill_adapter.py` because both editors lack Claude-only orchestration primitives (`Agent`, `TeamCreate`, `TaskCreate`).
+
+## Subagent Translation Model
+
+Each file in `app/agents/*.md` emits a corresponding `.opencode/agents/ai-toolkit-<name>.md` with:
+
+- `description` — copied from the source agent frontmatter
+- `mode: subagent` (required)
+- `color` — copied when present
+
+The `model` field is deliberately omitted. opencode requires the `provider/model-id` form; ai-toolkit only stores a short alias (`opus`/`sonnet`/`haiku`) which cannot be mapped without assuming a provider. opencode falls back to the user's `default_agent` / top-level `model` config.
+
+Opencode treats these files as auto-completable with `@` and can delegate to them from the primary agent.
+
+## Slash Command Translation Model
+
+Only user-invocable skills (`user-invocable: true` or no `disable-model-invocation`) emit to `.opencode/commands/`. Knowledge skills (`user-invocable: false`) are intentionally skipped — they are not intended as commands.
+
+Each command file carries opencode's required `template: |` frontmatter field, built from the SKILL.md body.
+
+## Hook Bridge (JS Plugin)
+
+`.opencode/plugins/ai-toolkit-hooks.js` is a single-file plugin that maps opencode events to the shared Bash hooks in `~/.softspark/ai-toolkit/hooks/`:
+
+| opencode event             | Bash hook(s)                                                       |
+|----------------------------|--------------------------------------------------------------------|
+| `session.created`          | `session-start.sh` + `session-context.sh` + `mcp-health.sh`        |
+| `session.compacted`        | `pre-compact.sh` + `pre-compact-save.sh` (PreCompact equivalent)   |
+| `session.deleted`          | `session-end.sh` + `save-session.sh`                               |
+| `message.updated`          | `user-prompt-submit.sh` + `track-usage.sh`                         |
+| `message.part.updated`     | `user-prompt-submit.sh` + `track-usage.sh`                         |
+| `tool.execute.before` (bash) | `guard-destructive.sh` + `commit-quality.sh`                     |
+| `tool.execute.after`       | `post-tool-use.sh`                                                 |
+| `permission.asked`         | `guard-destructive.sh` (approval-gate bridge)                      |
+| `command.executed`         | `post-tool-use.sh`                                                 |
+
+Plugin exports a single named export `AiToolkitHooks` — per opencode docs, named exports only (no default export). Hook scripts are invoked via Bun's `$` with the script path bound as a JS constant; opencode event payloads are passed as JSON on stdin, never interpolated into the shell command, so payload data cannot inject shell metacharacters. The toolkit's `exit 2` semantics for PreToolUse guards are preserved and bubble up as the plugin's return code.
+
+**Intentionally unmapped events**: `tui.*`, `lsp.*`, `installation.*`, `session.idle/status/updated/error/diff`, `file.edited`, `file.watcher.updated`, `todo.updated`, `shell.env`, `server.connected`, `message.*.removed`, `experimental.*` — no matching Bash hook in the toolkit, or the event is opencode-UI-only.
+
+## MCP Merge (opencode.json)
+
+`generate_opencode_json.py` reads `.mcp.json` and merges its servers under the `mcp` key in `opencode.json`:
+
+- `local` shape entries are translated to opencode's local command shape.
+- `remote` shape entries are translated to opencode's remote URL shape.
+- User-authored keys in `opencode.json` (outside `mcp`) are preserved.
+- Re-running the generator is idempotent.
+
+## Auto-Detection
+
+The installer detects opencode as configured when any of these markers exist:
+
+- `opencode.json`
+- `.opencode/` directory
+- `.opencode/agents/`
+- `.opencode/commands/`
+- `~/.config/opencode/`
+
+`ai-toolkit update` picks up opencode automatically when detection fires.
+
+## Uninstall & Reset
+
+`scripts/install_steps/ai_tools.py` cleanup only removes ai-toolkit-marked artifacts:
+
+- Generated `.opencode/agents/ai-toolkit-*.md`
+- Generated `.opencode/commands/ai-toolkit-*.md`
+- Generated `.opencode/plugins/ai-toolkit-hooks.js`
+- Managed markers from `AGENTS.md`
+- `mcp` key entries injected by the toolkit (user keys preserved)
+
+User-authored opencode files and user-authored `opencode.json` keys are never deleted.
+
+## Behavioral Limits
+
+- opencode does not expose the full Claude hook event surface; only the events in the mapping table above are bridged. Claude-only events (`TaskCompleted`, `TeammateIdle`, `SubagentStart`, `SubagentStop`, `PreCompact`) are silently skipped.
+- Multi-agent orchestration skills (`/orchestrate`, `/workflow`, `/swarm`, `/teams`, `/subagent-development`) run through the Codex adaptation layer — they use opencode subagents and explicit file ownership instead of Claude's `Agent`/`TaskCreate` primitives.
+
+## Verification
+
+The opencode integration is verified by:
+
+1. Generator contract tests for the five `generate_opencode*.py` scripts (bats)
+2. MCP merge idempotency and user-key preservation tests
+3. Plugin export shape and event coverage tests
+4. Auto-detection tests for install / update flow
+5. `validate.py --strict` + `audit_skills.py --ci` in CI
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `ai-toolkit opencode-md` | Generate `AGENTS.md` body for opencode |
+| `ai-toolkit opencode-agents` | Generate `.opencode/agents/ai-toolkit-*.md` |
+| `ai-toolkit opencode-commands` | Generate `.opencode/commands/ai-toolkit-*.md` |
+| `ai-toolkit opencode-plugin` | Generate `.opencode/plugins/ai-toolkit-hooks.js` |
+| `ai-toolkit opencode-json` | Merge MCP servers into `opencode.json` |
+
+## Related
+
+- `kb/reference/skills-catalog.md`
+- `kb/reference/agents-catalog.md`
+- `kb/reference/codex-cli-compatibility.md`
+- `kb/reference/architecture-overview.md`
+- `kb/reference/global-install-model.md`
+- `kb/reference/mcp-editor-compatibility.md`

package/llms-full.txt

@@ -44,6 +44,7 @@
 - [MCP Editor Compatibility](kb/reference/mcp-editor-compatibility.md)
 - [MCP Server Templates](kb/reference/mcp-templates.md)
 - [Merge-Friendly Install Model](kb/reference/merge-friendly-install-model.md)
+- [AI Toolkit - opencode Compatibility](kb/reference/opencode-compatibility.md)
 - [Plugin Pack Conventions](kb/reference/plugin-pack-conventions.md)
 - [Quick Wins Implementation Summary](kb/reference/quick-wins-implementation-summary.md)
 - [Skill Templates](kb/reference/skill-templates.md)
@@ -3517,9 +3518,9 @@ title: "SOP: Release Preparation"
 category: procedures
 service: ai-toolkit
 tags: [sop, release, version, publish, changelog, semver]
-version: "1.5.0"
+version: "1.6.0"
 created: "2026-04-10"
-last_updated: "2026-04-13"
+last_updated: "2026-04-17"
 description: "Step-by-step checklist for preparing a new ai-toolkit release — version sync, changelog, artifact regeneration, validation, and tagging. Run BEFORE every git tag."
 ---
 
@@ -3677,12 +3678,15 @@ Add entry at the top of `CHANGELOG.md` (after the header, before previous releas
 
 1. Change the heading version: `## What's New in vX.Y.Z`
 2. Replace bullet points with 3-5 highlights from this release
-3. Keep the `See [CHANGELOG.md](CHANGELOG.md) for full history.` link
+3. **Keep only the latest version block.** Delete the previous `## What's New in vA.B.C` section(s). README is the shop window, not the archive — users see the current release, full history lives in `CHANGELOG.md`.
+4. Keep the `See [CHANGELOG.md](CHANGELOG.md) for full history.` link directly below the bullet list.
 
 > **Warning:** This section is the first thing users see after the badges.
 > A stale version here (e.g., "What's New in v2.1.3" when shipping v2.3.0)
 > signals an unmaintained project. Do NOT skip this step.
 
+> **Single-version rule:** README.md must contain **exactly one** `## What's New in vX.Y.Z` heading at any time. If you find multiple stacked (e.g. v2.6.1 + v2.6.0 + v2.5.0), that is a SOP drift — collapse to the latest on the next release commit.
+
 ---
 
 ## Phase 4: Regenerate Artifacts
@@ -4638,7 +4642,7 @@ Three tiers determine how to approach a task:
 
 | Type | Field | Invocation | Count |
 |------|-------|-----------|-------|
-| Task | `disable-model-invocation: true` | User via `/skill` only | 30 |
+| Task | `disable-model-invocation: true` | User via `/skill` only | 31 |
 | Hybrid | (neither) | User via `/skill` + agent knowledge | 31 |
 | Knowledge | `user-invocable: false` | Claude auto-loads | 32 |
 
@@ -8241,6 +8245,172 @@ Project-local setup uses the same preservation approach for files that should re
 
 ---
 
+## kb/reference/opencode-compatibility.md
+
+---
+title: "AI Toolkit - opencode Compatibility"
+category: reference
+service: ai-toolkit
+tags: [opencode, compatibility, install, skills, hooks, mcp, plugins]
+version: "1.0.0"
+created: "2026-04-16"
+last_updated: "2026-04-16"
+description: "Reference for how ai-toolkit integrates with opencode — AGENTS.md, subagents, slash commands, JS plugin hook bridge, and MCP merge into opencode.json."
+---
+
+# AI Toolkit - opencode Compatibility
+
+## Summary
+
+opencode (https://opencode.ai) is the 11th supported editor. `ai-toolkit install --editors opencode` (or `--editors all`) lays down a full native integration: shared `AGENTS.md`, per-agent `.opencode/agents/` files, per-command `.opencode/commands/` files, a JS plugin bridging toolkit Bash hooks to opencode lifecycle events, and MCP server merge into `opencode.json`.
+
+opencode also reads `CLAUDE.md` as a fallback, so a user without the native integration still gets baseline rules. The native path adds subagents, slash commands, hooks, and MCP.
+
+## Local Install Outputs
+
+`ai-toolkit install --local --editors opencode` generates:
+
+- `AGENTS.md` (shared with Codex CLI via distinct marker sections)
+- `.opencode/agents/ai-toolkit-*.md` (one per ai-toolkit agent, `mode: subagent`)
+- `.opencode/commands/ai-toolkit-*.md` (one per user-invocable skill, required `template: |` frontmatter field)
+- `.opencode/plugins/ai-toolkit-hooks.js` (JS plugin bridging Bash hooks)
+- `opencode.json` (MCP key merged from `.mcp.json`, user keys preserved)
+
+## Global Install Outputs
+
+`ai-toolkit install --editors opencode` (no `--local`) lays down:
+
+- `~/.config/opencode/AGENTS.md`
+- `~/.config/opencode/agents/ai-toolkit-*.md`
+- `~/.config/opencode/commands/ai-toolkit-*.md`
+- `~/.config/opencode/plugins/ai-toolkit-hooks.js`
+- `~/.config/opencode/opencode.json` (MCP merge, user keys preserved)
+
+Files land directly under `~/.config/opencode/` (no `.opencode/` nesting) because that is the global layout opencode expects per https://opencode.ai/docs/config/. Shared hook scripts stay in `~/.softspark/ai-toolkit/hooks/` and are referenced by the global JS plugin.
+
+## Editor Surface Comparison
+
+| Feature            | Claude Code | Codex CLI       | opencode                                  |
+|--------------------|-------------|-----------------|-------------------------------------------|
+| Rules file         | `CLAUDE.md` | `AGENTS.md`     | `AGENTS.md` + `CLAUDE.md` fallback        |
+| Subagents          | Yes         | No              | Yes (`mode: subagent`)                    |
+| Slash commands     | Skills      | Adapted skills  | Native commands with frontmatter          |
+| MCP                | Yes         | Yes             | Yes (`opencode.json`)                     |
+| Lifecycle hooks    | JSON config | `.codex/hooks`  | JS/TS plugins (~30+ events)               |
+| Global config dir  | `~/.claude` | `~/.codex`      | `~/.config/opencode`                      |
+| Project config dir | `.claude`   | `.agents`       | `.opencode`                               |
+
+## Shared AGENTS.md
+
+opencode and Codex CLI both read `AGENTS.md`. The toolkit emits two distinct marker-bounded sections in a single file, so installing both editors does not clobber either. The Codex section is produced by `generate_codex.py`; the opencode section is produced by `generate_opencode.py`. Both sections reuse `codex_skill_adapter.py` because both editors lack Claude-only orchestration primitives (`Agent`, `TeamCreate`, `TaskCreate`).
+
+## Subagent Translation Model
+
+Each file in `app/agents/*.md` emits a corresponding `.opencode/agents/ai-toolkit-<name>.md` with:
+
+- `description` — copied from the source agent frontmatter
+- `mode: subagent` (required)
+- `color` — copied when present
+
+The `model` field is deliberately omitted. opencode requires the `provider/model-id` form; ai-toolkit only stores a short alias (`opus`/`sonnet`/`haiku`) which cannot be mapped without assuming a provider. opencode falls back to the user's `default_agent` / top-level `model` config.
+
+Opencode treats these files as auto-completable with `@` and can delegate to them from the primary agent.
+
+## Slash Command Translation Model
+
+Only user-invocable skills (`user-invocable: true` or no `disable-model-invocation`) emit to `.opencode/commands/`. Knowledge skills (`user-invocable: false`) are intentionally skipped — they are not intended as commands.
+
+Each command file carries opencode's required `template: |` frontmatter field, built from the SKILL.md body.
+
+## Hook Bridge (JS Plugin)
+
+`.opencode/plugins/ai-toolkit-hooks.js` is a single-file plugin that maps opencode events to the shared Bash hooks in `~/.softspark/ai-toolkit/hooks/`:
+
+| opencode event             | Bash hook(s)                                                       |
+|----------------------------|--------------------------------------------------------------------|
+| `session.created`          | `session-start.sh` + `session-context.sh` + `mcp-health.sh`        |
+| `session.compacted`        | `pre-compact.sh` + `pre-compact-save.sh` (PreCompact equivalent)   |
+| `session.deleted`          | `session-end.sh` + `save-session.sh`                               |
+| `message.updated`          | `user-prompt-submit.sh` + `track-usage.sh`                         |
+| `message.part.updated`     | `user-prompt-submit.sh` + `track-usage.sh`                         |
+| `tool.execute.before` (bash) | `guard-destructive.sh` + `commit-quality.sh`                     |
+| `tool.execute.after`       | `post-tool-use.sh`                                                 |
+| `permission.asked`         | `guard-destructive.sh` (approval-gate bridge)                      |
+| `command.executed`         | `post-tool-use.sh`                                                 |
+
+Plugin exports a single named export `AiToolkitHooks` — per opencode docs, named exports only (no default export). Hook scripts are invoked via Bun's `$` with the script path bound as a JS constant; opencode event payloads are passed as JSON on stdin, never interpolated into the shell command, so payload data cannot inject shell metacharacters. The toolkit's `exit 2` semantics for PreToolUse guards are preserved and bubble up as the plugin's return code.
+
+**Intentionally unmapped events**: `tui.*`, `lsp.*`, `installation.*`, `session.idle/status/updated/error/diff`, `file.edited`, `file.watcher.updated`, `todo.updated`, `shell.env`, `server.connected`, `message.*.removed`, `experimental.*` — no matching Bash hook in the toolkit, or the event is opencode-UI-only.
+
+## MCP Merge (opencode.json)
+
+`generate_opencode_json.py` reads `.mcp.json` and merges its servers under the `mcp` key in `opencode.json`:
+
+- `local` shape entries are translated to opencode's local command shape.
+- `remote` shape entries are translated to opencode's remote URL shape.
+- User-authored keys in `opencode.json` (outside `mcp`) are preserved.
+- Re-running the generator is idempotent.
+
+## Auto-Detection
+
+The installer detects opencode as configured when any of these markers exist:
+
+- `opencode.json`
+- `.opencode/` directory
+- `.opencode/agents/`
+- `.opencode/commands/`
+- `~/.config/opencode/`
+
+`ai-toolkit update` picks up opencode automatically when detection fires.
+
+## Uninstall & Reset
+
+`scripts/install_steps/ai_tools.py` cleanup only removes ai-toolkit-marked artifacts:
+
+- Generated `.opencode/agents/ai-toolkit-*.md`
+- Generated `.opencode/commands/ai-toolkit-*.md`
+- Generated `.opencode/plugins/ai-toolkit-hooks.js`
+- Managed markers from `AGENTS.md`
+- `mcp` key entries injected by the toolkit (user keys preserved)
+
+User-authored opencode files and user-authored `opencode.json` keys are never deleted.
+
+## Behavioral Limits
+
+- opencode does not expose the full Claude hook event surface; only the events in the mapping table above are bridged. Claude-only events (`TaskCompleted`, `TeammateIdle`, `SubagentStart`, `SubagentStop`, `PreCompact`) are silently skipped.
+- Multi-agent orchestration skills (`/orchestrate`, `/workflow`, `/swarm`, `/teams`, `/subagent-development`) run through the Codex adaptation layer — they use opencode subagents and explicit file ownership instead of Claude's `Agent`/`TaskCreate` primitives.
+
+## Verification
+
+The opencode integration is verified by:
+
+1. Generator contract tests for the five `generate_opencode*.py` scripts (bats)
+2. MCP merge idempotency and user-key preservation tests
+3. Plugin export shape and event coverage tests
+4. Auto-detection tests for install / update flow
+5. `validate.py --strict` + `audit_skills.py --ci` in CI
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `ai-toolkit opencode-md` | Generate `AGENTS.md` body for opencode |
+| `ai-toolkit opencode-agents` | Generate `.opencode/agents/ai-toolkit-*.md` |
+| `ai-toolkit opencode-commands` | Generate `.opencode/commands/ai-toolkit-*.md` |
+| `ai-toolkit opencode-plugin` | Generate `.opencode/plugins/ai-toolkit-hooks.js` |
+| `ai-toolkit opencode-json` | Merge MCP servers into `opencode.json` |
+
+## Related
+
+- `kb/reference/skills-catalog.md`
+- `kb/reference/agents-catalog.md`
+- `kb/reference/codex-cli-compatibility.md`
+- `kb/reference/architecture-overview.md`
+- `kb/reference/global-install-model.md`
+- `kb/reference/mcp-editor-compatibility.md`
+
+---
+
 ## kb/reference/plugin-pack-conventions.md
 
 ---

package/llms.txt

@@ -44,6 +44,7 @@
 - [MCP Editor Compatibility](kb/reference/mcp-editor-compatibility.md)
 - [MCP Server Templates](kb/reference/mcp-templates.md)
 - [Merge-Friendly Install Model](kb/reference/merge-friendly-install-model.md)
+- [AI Toolkit - opencode Compatibility](kb/reference/opencode-compatibility.md)
 - [Plugin Pack Conventions](kb/reference/plugin-pack-conventions.md)
 - [Quick Wins Implementation Summary](kb/reference/quick-wins-implementation-summary.md)
 - [Skill Templates](kb/reference/skill-templates.md)

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.5.0",
+  "version": "2.6.2",
   "components": {
     "agents": {
       "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "2.5.0",
-  "description": "Professional-grade AI coding toolkit: 94 skills, 44 agents, multi-platform support (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, Augment, Google Antigravity, Codex CLI), machine-enforced safety constitution, persona presets, skill security auditor, expanded lifecycle hooks, 11 plugin packs, and benchmark tooling.",
+  "version": "2.6.2",
+  "description": "Professional-grade AI coding toolkit: 94 skills, 44 agents, multi-platform support (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, Augment, Google Antigravity, Codex CLI, opencode), machine-enforced safety constitution, persona presets, skill security auditor, expanded lifecycle hooks, 11 plugin packs, and benchmark tooling.",
   "keywords": [
     "claude",
     "claude-code",
@@ -23,6 +23,7 @@
     "augment",
     "antigravity",
     "google-antigravity",
+    "opencode",
     "multi-platform"
   ],
   "homepage": "https://github.com/softspark/ai-toolkit",
@@ -56,7 +57,9 @@
     "generate:roo": "python3 scripts/generate_roo_modes.py > .roomodes",
     "generate:aider": "python3 scripts/generate_aider_conf.py > .aider.conf.yml",
     "generate:codex-rules": "python3 scripts/generate_codex_rules.py .",
-    "generate:all": "npm run generate:agents && npm run generate:codex-rules && npm run generate:cursor && npm run generate:windsurf && npm run generate:copilot && npm run generate:gemini && npm run generate:cline && npm run generate:roo && npm run generate:aider && npm run generate:llms"
+    "generate:opencode-agents": "python3 scripts/generate_opencode_agents.py .",
+    "generate:opencode-commands": "python3 scripts/generate_opencode_commands.py .",
+    "generate:all": "npm run generate:agents && npm run generate:codex-rules && npm run generate:opencode-agents && npm run generate:opencode-commands && npm run generate:cursor && npm run generate:windsurf && npm run generate:copilot && npm run generate:gemini && npm run generate:cline && npm run generate:roo && npm run generate:aider && npm run generate:llms"
   },
   "files": [
     "bin/",

package/scripts/eject.py

@@ -69,7 +69,11 @@ def main() -> None:
             if dest.exists():
                 shutil.rmtree(dest)
             shutil.copytree(skill, dest)
-            skill_count += 1
+            # Count only real skills. Underscore-prefixed dirs (e.g. `_lib/`)
+            # are shared helpers that must be copied so dependent skills keep
+            # working, but are not skills themselves — matches validate.py.
+            if not skill.name.startswith("_") and (skill / "SKILL.md").is_file():
+                skill_count += 1
     print(f"  Copied: {skill_count} skills")
 
     # -- CLAUDE.md: inline all rules -----------------------------------------

package/scripts/generate_opencode.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""Generate AGENTS.md content for opencode (https://opencode.ai).
+
+opencode reads AGENTS.md using the same convention as OpenAI Codex CLI.
+The generated file is safe for both editors to consume from the same
+project root — each injects into its own marker-wrapped block.
+
+Usage: ./scripts/generate_opencode.py > AGENTS.md
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from codex_skill_adapter import codex_skill_description
+from emission import (
+    agents_dir,
+    skills_dir,
+    generate_quality_standards,
+    generate_workflow_guidelines,
+    print_toolkit_end,
+    print_toolkit_start,
+)
+from frontmatter import frontmatter_field
+from paths import RULES_DIR
+
+
+def _emit_agents() -> str:
+    """Emit agents as opencode subagent bullets."""
+    lines: list[str] = []
+    for agent_file in sorted(agents_dir.glob("*.md")):
+        name = frontmatter_field(agent_file, "name")
+        description = frontmatter_field(agent_file, "description")
+        if not name or not description:
+            continue
+        lines.append(f"- **{name}**: {description}")
+    return "\n".join(lines)
+
+
+def _emit_skills() -> str:
+    """Emit user-invocable skills as opencode command bullets.
+
+    Adapts Claude orchestration-only descriptions via the Codex adapter —
+    opencode, like Codex, lacks Claude's Agent/Team/Task primitives so the
+    same translation layer applies.
+    """
+    lines: list[str] = []
+    for skill_dir in sorted(skills_dir.iterdir()):
+        if skill_dir.name.startswith("_"):
+            continue
+        skill_file = skill_dir / "SKILL.md"
+        if not skill_file.is_file():
+            continue
+        name = frontmatter_field(skill_file, "name")
+        description = codex_skill_description(skill_file)
+        if not name or not description:
+            continue
+        lines.append(f"- **{name}**: {description}")
+    return "\n".join(lines)
+
+
+def main() -> None:
+    print_toolkit_start()
+
+    print("# AI Toolkit — opencode Configuration")
+    print()
+    print(
+        "Shared AI development toolkit with specialized subagents,"
+        " opencode-compatible commands, quality hooks, and a safety constitution."
+    )
+    print()
+    print(
+        "opencode reads this file at session start. Subagents are also"
+        " installed under `.opencode/agents/` and slash commands under"
+        " `.opencode/commands/` for native `@` and `/` autocomplete."
+    )
+
+    # Agents
+    print()
+    print("## Available Subagents")
+    print()
+    print("Invoke with `@<name>` in opencode, or delegate via `spawn_agent`:")
+    print()
+    print(_emit_agents())
+
+    # Skills / slash commands
+    print()
+    print("## Available Commands")
+    print()
+    print("Invoke with `/<name>` in opencode. Knowledge-only skills load automatically:")
+    print()
+    print(_emit_skills())
+
+    # Guidelines
+    print()
+    print(generate_quality_standards())
+    print()
+    print(generate_workflow_guidelines())
+
+    print_toolkit_end()
+
+    # Registered custom rules from ~/.softspark/ai-toolkit/rules/
+    if RULES_DIR.is_dir():
+        for rule_file in sorted(RULES_DIR.glob("*.md")):
+            rule_name = rule_file.stem
+            print()
+            print(f"<!-- TOOLKIT:{rule_name} START -->")
+            print("<!-- Auto-injected by ai-toolkit. Re-run to update. -->")
+            print()
+            print(rule_file.read_text(encoding="utf-8").rstrip())
+            print()
+            print(f"<!-- TOOLKIT:{rule_name} END -->")
+
+
+if __name__ == "__main__":
+    main()