@softspark/ai-toolkit 2.4.1 → 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/kb/reference/skills-catalog.md

@@ -23,7 +23,7 @@ All functionality is unified under skills. Task and hybrid skills are user-invoc
 | **2 — Multi-agent workflow** | `/workflow <type>` | Cross-cutting task with known pattern |
 | **3 — Custom parallelism** | `/orchestrate`, `/swarm` | No predefined workflow matches |
 
-## Task Skills (29)
+## Task Skills (30)
 
 Task skills execute a specific action. Invoked via slash commands. `disable-model-invocation: true`.
 
@@ -58,6 +58,8 @@ Task skills execute a specific action. Invoked via slash commands. `disable-mode
 | **prd-to-issues** | `/prd-to-issues` | medium | Break PRD into GitHub issues with vertical slices and HITL/AFK tagging |
 | **skill-audit** | `/skill-audit` | medium | Scan skills and agents for security risks: dangerous patterns, secrets, excessive permissions |
 | **hipaa-validate** | `/hipaa-validate` | medium | Scan codebase for HIPAA compliance issues: PHI exposure, missing audit logging, unencrypted transmission/storage, access control gaps, temp file exposure, and missing BAA references |
+| **a11y-validate** | `/a11y-validate` | medium | Scan codebase for accessibility violations: WCAG 2.1 Level AA, EN 301 549, European Accessibility Act (EAA / EU 2019/882). Covers semantics, keyboard, focus, color contrast, forms, media, ARIA, motion, mobile (React Native + Flutter), and EAA accessibility-statement documentation. |
+| **seo-validate** | `/seo-validate` | medium | Scan codebase for SEO issues: W3C semantics, meta/OG tags, Schema.org, hreflang, Core Web Vitals (LCP/INP/CLS), resource hints, GEO, SPA/SSG/CSR crawlability, technical SEO, accessibility-for-SEO. Framework-aware (Next/Nuxt/Astro/Gatsby/SvelteKit/Remix/Angular/Vue/static HTML). |
 
 ## Hybrid Skills (31)
 

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)
@@ -56,6 +57,7 @@
 
 ## Skills
 
+- **a11y-validate**: Validate code against accessibility standards: WCAG 2.1 Level AA, EN 301 549, and the European Accessibility Act (EAA / Directive EU 2019/882). Covers semantics, text alternatives, keyboard/focus, color/contrast, forms, media, ARIA, motion, mobile, and EAA documentation requirements. Framework-aware (React/Next/Nuxt/Astro/Gatsby/SvelteKit/Remix/Angular/Vue/React Native/Flutter/static HTML).
 - **agent-creator**: Creates new specialized agents with frontmatter, tool selection, and delegation guidance
 - **analyze**: Analyze code quality, complexity, and patterns
 - **api-patterns**: Loaded when user asks about REST API design or GraphQL patterns
@@ -133,6 +135,7 @@
 - **rust-patterns**: Loaded when user asks about Rust development patterns
 - **search**: Search the knowledge base with semantic and hybrid modes
 - **security-patterns**: Loaded when user asks about security, OWASP, or auth patterns
+- **seo-validate**: Validate code against SEO best practices: W3C semantics, meta/OG tags, Schema.org, hreflang, Core Web Vitals (LCP/INP/CLS), resource hints, GEO, SPA/SSG/CSR crawlability, technical SEO, accessibility-for-SEO. Supports React/Next/Nuxt/Astro/Gatsby/SvelteKit/Remix/Angular/Vue/static HTML.
 - **skill-audit**: Scan skills and agents for security risks: dangerous patterns, secrets, excessive permissions
 - **skill-creator**: Create new skills from templates with guided workflow
 - **subagent-development**: Execute implementation plans using fresh subagents per task with two-stage review: spec compliance first, then code quality. Use when executing plans with independent tasks.
@@ -4456,7 +4459,7 @@ service: ai-toolkit
 tags: [architecture, overview, design, structure]
 version: "1.4.4"
 created: "2026-03-23"
-last_updated: "2026-04-13"
+last_updated: "2026-04-15"
 description: "Architecture of ai-toolkit: directory layout, global install model, editor-aware MCP install, Codex translation layer, skill tiers, and integration with projects."
 ---
 
@@ -4636,7 +4639,7 @@ Three tiers determine how to approach a task:
 
 | Type | Field | Invocation | Count |
 |------|-------|-----------|-------|
-| Task | `disable-model-invocation: true` | User via `/skill` only | 29 |
+| 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 |
 
@@ -4786,7 +4789,7 @@ Severity levels: HIGH (blocks deployment), WARN (should fix), INFO (best practic
 ## Extension Points
 
 ### MCP Templates
-`app/plugins/mcp-templates/` contains 26 ready-to-use MCP server config templates. Opt-in via `ai-toolkit install --modules mcp-templates` or activated automatically with `--profile strict|full`.
+`app/mcp-templates/` contains 26 ready-to-use MCP server config templates. Opt-in via `ai-toolkit install --modules mcp-templates` or activated automatically with `--profile strict|full`.
 
 ### Language Rules
 `app/rules/` provides language-specific rule files covering 13 languages (TypeScript, Python, Go, Rust, Java, Kotlin, Swift, Dart, C#, PHP, C++, Ruby, common). Auto-detected from project files via `--auto-detect` or selectable with `--modules rules-<lang>`. See README.md for current count.
@@ -5137,7 +5140,7 @@ category: reference
 service: ai-toolkit
 tags: [cli, commands, reference, install, update, plugin, mcp]
 created: "2026-04-13"
-last_updated: "2026-04-13"
+last_updated: "2026-04-15"
 description: "Complete CLI reference for all ai-toolkit commands, options, and flags."
 ---
 
@@ -5430,7 +5433,7 @@ description: "Feature comparison of ai-toolkit vs other Claude Code toolkits and
 
 | Feature | ai-toolkit | everything-claude-code | wshobson/agents | ruflo |
 |---------|---------------|----------------------|-----------------|-------|
-| Skills | 92 | 100+ | 146 | 20+ |
+| Skills | 93 | 100+ | 146 | 20+ |
 | Agents | 44 | 30+ | 112 | 20+ |
 | Machine-enforced constitution | **Yes** | No (docs only) | No | No |
 | Skill-scoped lifecycle hooks | **Yes** | No | No | No |
@@ -8239,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
 
 ---
@@ -8553,7 +8722,7 @@ All functionality is unified under skills. Task and hybrid skills are user-invoc
 | **2 — Multi-agent workflow** | `/workflow <type>` | Cross-cutting task with known pattern |
 | **3 — Custom parallelism** | `/orchestrate`, `/swarm` | No predefined workflow matches |
 
-## Task Skills (29)
+## Task Skills (30)
 
 Task skills execute a specific action. Invoked via slash commands. `disable-model-invocation: true`.
 
@@ -8588,6 +8757,8 @@ Task skills execute a specific action. Invoked via slash commands. `disable-mode
 | **prd-to-issues** | `/prd-to-issues` | medium | Break PRD into GitHub issues with vertical slices and HITL/AFK tagging |
 | **skill-audit** | `/skill-audit` | medium | Scan skills and agents for security risks: dangerous patterns, secrets, excessive permissions |
 | **hipaa-validate** | `/hipaa-validate` | medium | Scan codebase for HIPAA compliance issues: PHI exposure, missing audit logging, unencrypted transmission/storage, access control gaps, temp file exposure, and missing BAA references |
+| **a11y-validate** | `/a11y-validate` | medium | Scan codebase for accessibility violations: WCAG 2.1 Level AA, EN 301 549, European Accessibility Act (EAA / EU 2019/882). Covers semantics, keyboard, focus, color contrast, forms, media, ARIA, motion, mobile (React Native + Flutter), and EAA accessibility-statement documentation. |
+| **seo-validate** | `/seo-validate` | medium | Scan codebase for SEO issues: W3C semantics, meta/OG tags, Schema.org, hreflang, Core Web Vitals (LCP/INP/CLS), resource hints, GEO, SPA/SSG/CSR crawlability, technical SEO, accessibility-for-SEO. Framework-aware (Next/Nuxt/Astro/Gatsby/SvelteKit/Remix/Angular/Vue/static HTML). |
 
 ## Hybrid Skills (31)
 

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.4.1",
+  "version": "2.6.1",
   "components": {
     "agents": {
       "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",
@@ -9,7 +9,7 @@
       "tags": ["core", "agents"]
     },
     "skills": {
-      "description": "92 skills (29 task + 31 hybrid + 32 knowledge)",
+      "description": "94 skills (31 task + 31 hybrid + 32 knowledge)",
       "path": "app/skills",
       "target": ".claude/skills",
       "type": "symlink",
@@ -90,7 +90,7 @@
       "default": true
     },
     "skills": {
-      "description": "92 skills (task, hybrid, knowledge)",
+      "description": "94 skills (task, hybrid, knowledge)",
       "default": true
     },
     "rules-common": {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "2.4.1",
-  "description": "Professional-grade AI coding toolkit: 92 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/config_cli.py

@@ -96,17 +96,11 @@ def cmd_validate(args: list[str]) -> int:
             print(f"  ✗ Merge failed: {e}")
             return 1
 
-    checks = [
-        ("schema valid", True),
-        ("no forbidden overrides", True),
-        ("constitution articles intact", True),
-    ]
-
+    # Summary — these passed because validation above would have returned 1
+    print(f"  ✓ schema valid")
+    print(f"  ✓ no forbidden overrides")
     if extends:
-        checks.append(("extends resolved", True))
-
-    for label, ok in checks:
-        print(f"  {'✓' if ok else '✗'} {label}")
+        print(f"  ✓ extends resolved")
 
     print("\n  Config valid ✓")
     return 0

package/scripts/doctor.py

@@ -454,13 +454,13 @@ def check_stale_rules(dr: DiagResult, fix_mode: bool) -> None:
     for rule_file in sorted(RULES_DIR.iterdir()):
         # Check for stale symlinks
         if rule_file.is_symlink() and not rule_file.exists():
-            print(f"  WARNING: Stale symlink: {rule_file}")
+            dr.warn(f"Stale symlink: {rule_file}")
             stale += 1
             if fix_mode:
                 rule_file.unlink()
-                print("    FIXED: removed stale symlink")
+                dr.fixed(f"removed stale symlink: {rule_file.name}")
         elif rule_file.is_file() and rule_file.stat().st_size == 0:
-            print(f"  WARNING: Empty rule file: {rule_file}")
+            dr.warn(f"Empty rule file: {rule_file}")
             stale += 1
 
     if stale == 0: