@softspark/ai-toolkit 2.5.0 → 2.6.1

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)
@@ -4638,7 +4639,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 +8242,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.1",
   "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.1",
+  "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/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()

package/scripts/generate_opencode_agents.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+"""Generate .opencode/agents/*.md files for opencode (https://opencode.ai).
+
+Each ai-toolkit agent becomes an opencode subagent with frontmatter:
+
+    ---
+    description: "..."
+    mode: subagent
+    ---
+
+    <body from agent file>
+
+Generated files are prefixed ``ai-toolkit-`` so they never collide with
+user-authored opencode agents and can be cleanly removed on uninstall.
+
+Usage:
+  python3 scripts/generate_opencode_agents.py [target-dir]
+
+Writes files to target-dir/.opencode/agents/.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from emission import agents_dir
+from frontmatter import frontmatter_field
+
+AGENT_PREFIX = "ai-toolkit-"
+
+
+def _agent_body(agent_file: Path) -> str:
+    """Return the markdown body of an agent file (content after frontmatter)."""
+    text = agent_file.read_text(encoding="utf-8")
+    if not text.startswith("---"):
+        return text.strip() + "\n"
+    # Skip first frontmatter block
+    parts = text.split("---", 2)
+    if len(parts) < 3:
+        return text.strip() + "\n"
+    return parts[2].lstrip("\n")
+
+
+def _render_opencode_agent(agent_file: Path) -> str:
+    """Render a single opencode subagent .md file from an ai-toolkit agent."""
+    name = frontmatter_field(agent_file, "name")
+    description = frontmatter_field(agent_file, "description")
+    model = frontmatter_field(agent_file, "model")
+    color = frontmatter_field(agent_file, "color")
+
+    # Escape description for YAML quoted string
+    safe_desc = description.replace('"', "'")
+
+    lines: list[str] = ["---"]
+    lines.append(f'description: "{safe_desc}"')
+    lines.append("mode: subagent")
+    # opencode requires `provider/model-id` for the `model` field. ai-toolkit
+    # only stores a short alias (opus/sonnet/haiku) which is not mappable
+    # without assuming a provider, so we deliberately omit it — opencode falls
+    # back to the user's `default_agent` / top-level `model` config.
+    _ = model  # intentionally unused
+    if color:
+        lines.append(f"color: {color}")
+    lines.append("---")
+    lines.append("")
+    body = _agent_body(agent_file).rstrip()
+    if body:
+        lines.append(body)
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _cleanup_stale(agents_out: Path) -> int:
+    """Remove stale ai-toolkit-* agent files whose source no longer exists."""
+    if not agents_out.is_dir():
+        return 0
+    removed = 0
+    for f in sorted(agents_out.glob(f"{AGENT_PREFIX}*.md")):
+        source_name = f.stem[len(AGENT_PREFIX):]
+        source = agents_dir / f"{source_name}.md"
+        if not source.is_file():
+            f.unlink()
+            removed += 1
+    return removed
+
+
+def generate(
+    target_dir: Path, config_root: Path | None = None
+) -> tuple[int, int]:
+    """Write opencode agent files and return (written, removed_stale).
+
+    By default writes to ``target_dir/.opencode/agents/`` (project-local).
+    Pass ``config_root=~/.config/opencode`` for the global layout, which
+    lives directly under ``agents/`` (no ``.opencode/`` prefix).
+    """
+    base = config_root if config_root is not None else target_dir / ".opencode"
+    agents_out = base / "agents"
+    agents_out.mkdir(parents=True, exist_ok=True)
+
+    written = 0
+    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
+        out_path = agents_out / f"{AGENT_PREFIX}{name}.md"
+        out_path.write_text(_render_opencode_agent(agent_file), encoding="utf-8")
+        written += 1
+
+    removed = _cleanup_stale(agents_out)
+    return written, removed
+
+
+def main() -> None:
+    target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
+    written, removed = generate(target)
+    msg = f"Generated: .opencode/agents/ ({written} agents"
+    if removed:
+        msg += f", {removed} stale removed"
+    msg += ")"
+    print(msg)
+
+
+if __name__ == "__main__":
+    main()