@softspark/ai-toolkit 2.4.1 → 2.6.1

package/AGENTS.md

@@ -86,7 +86,7 @@ Legacy code investigation and understanding specialist. Trigger words: legacy co
 
 Code review and security audit expert. Use for security reviews, Devil's Advocate analysis, quality audits, best practices validation. Triggers: review, security, audit, quality, best practices, vulnerability.
 
-**Tools:** `Read, Edit`
+**Tools:** `Read, Edit, Grep, Glob`
 
 ---
 
@@ -446,6 +446,7 @@ Specialized agent personas — apply their expertise for relevant tasks:
 
 Skills are invocable commands or auto-loaded knowledge sources:
 
+- **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
@@ -523,6 +524,7 @@ Skills are invocable commands or auto-loaded knowledge sources:
 - **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. Codex-adapted: uses native subagents and plan tracking.
@@ -583,24 +585,35 @@ Derived from the immutable safety constitution (5 articles):
 
 # Jira MCP Server
 
-Tools: `sync_tasks`, `read_cached_tasks`, `update_task_status`, `update_task`, `add_task_comment`, `reassign_task`, `get_task_statuses`, `get_task_details`, `get_project_language`, `log_task_time`, `get_task_time_tracking`, `list_comment_templates`, `add_templated_comment`, `create_task`, `search_tasks`
+Tools: `sync_tasks`, `read_cached_tasks`, `update_task_status`, `update_task`, `add_task_comment`, `delete_task`, `delete_comment`, `reassign_task`, `get_task_statuses`, `get_task_details`, `get_project_language`, `log_task_time`, `get_task_time_tracking`, `list_comment_templates`, `add_templated_comment`, `create_task`, `search_tasks`
 
 ## Key Rules
 
-- **Always `sync_tasks` first** before reading -- cache may be stale.
-- **Language first:** before writing ANY comment, description, or task content, call `get_project_language(project_key)` or check the `language` field in `get_task_details` response. Write ALL content in the project's configured language. Never assume Polish or English — always check first.
-- **Time format:** `"2h 30m"` -- hours and minutes only, never days.
+- **Always `sync_tasks` first** before reading, because the cache may be stale.
+- **Language first:** before writing ANY comment, description, or task content, call `get_project_language(project_key)` or check the `language` field in `get_task_details` response. Write ALL content in the project's configured language. Never assume Polish or English. Always check first.
+- **Time format:** `"2h 30m"`, using hours and minutes only, never days.
 - **Status changes:** call `get_task_statuses` first to check valid transitions.
 - **Multi-instance:** project key determines which Jira instance is used (mapped in config.json).
 - **Comments are ADF:** `add_task_comment` converts markdown to ADF (Atlassian Document Format) automatically.
+- **Delete guard:** `delete_task` is allowed only for the task creator, and `delete_comment` is allowed only for the comment author. Both require explicit `user_approved=true`.
 - **Templates:** use `list_comment_templates` to discover available templates, then `add_templated_comment` with `template_id` + `variables`.
 
+## Writing Style
+
+- **Write like a real team member:** use plain, direct language that sounds like an engineer writing to another human, not like polished AI copy or marketing text.
+- **No em dash and no double-hyphen separator in prose:** do not use those punctuation patterns in generated comments, descriptions, docs, or summaries. Use commas, periods, or parentheses instead.
+- **Avoid stock AI phrases:** do not use phrases like "worth noting", "it is important to understand", "in today's dynamic environment", "overall", "in conclusion", or similar generic filler.
+- **Prefer concrete wording:** use specific facts, actions, examples, and decisions instead of abstract claims or padded qualifiers.
+- **Avoid repetitive rhythm:** do not make every sentence or bullet sound structurally identical. Vary sentence length and openings when writing longer text.
+- **Keep summaries short:** do not add forced wrap-up paragraphs unless the user explicitly asks for a summary.
+- **Use a workmanlike tone:** prefer a slightly rough, practical style over text that sounds overly smooth, symmetrical, or "LLM-clean".
+
 ## Workflow
 
-1. `sync_tasks(jql="assignee=currentUser() AND status!=Done")` -- fetch fresh
-2. `read_cached_tasks()` -- work offline
-3. `get_task_details(task_key="PROJ-123")` -- deep dive (description + comments as markdown)
-4. `update_task_status(...)` / `add_task_comment(...)` / `log_task_time(...)` -- mutate
+1. `sync_tasks(jql="assignee=currentUser() AND status!=Done")` to fetch fresh data
+2. `read_cached_tasks()` to work offline
+3. `get_task_details(task_key="PROJ-123")` for a deep dive into description and comments as markdown
+4. `update_task_status(...)` / `add_task_comment(...)` / `log_task_time(...)` to mutate data
 
 ## Comment Templates (built-in)
 
@@ -636,25 +649,25 @@ Tools: `sync_tasks`, `read_cached_tasks`, `update_task_status`, `update_task`, `
 
 ## Architecture
 
-Four layers -- each depends only on layers below:
+Four layers. Each depends only on layers below.
 
-1. **Types & Config** (`config/`, `errors/`, `*/types.ts`) -- pure data, zero runtime deps
-2. **Infrastructure** (`connector/`, `cache/`, `adf/`, `templates/`) -- I/O and external APIs
-3. **Business Logic** (`operations/`, `bulk/`) -- orchestrates infrastructure
-4. **Entry Points** (`tools/`, `cli/`, `server.ts`) -- thin dispatchers
+1. **Types & Config** (`config/`, `errors/`, `*/types.ts`), pure data with zero runtime deps
+2. **Infrastructure** (`connector/`, `cache/`, `adf/`, `templates/`), I/O and external APIs
+3. **Business Logic** (`operations/`, `bulk/`), orchestrating infrastructure
+4. **Entry Points** (`tools/`, `cli/`, `server.ts`), thin dispatchers
 
 ## Coding Conventions
 
 - **Strict TypeScript**: `strict: true`, NO `any`, `readonly` interfaces, `import type`, `.js` imports
 - **Zod schemas** for all external data: `type Foo = z.infer<typeof FooSchema>`
 - **Error classes**: extend `JiraMcpError` with `code` property
-- **ADF round-trip**: `markdownToAdf()` for writes, `adfToMarkdown()` for reads -- NEVER throw
+- **ADF round-trip**: `markdownToAdf()` for writes and `adfToMarkdown()` for reads. NEVER throw.
 - **InstancePool**: singleton, lazy connectors, dedup by URL
 - **Dual-write**: after Jira mutation, update local cache, return API result
 - **Dry-run default**: `--execute` required for destructive operations
 - **DI pattern**: handlers accept `deps?` parameter for testing
-- **Config path**: ALWAYS `~/.softspark/jira-mcp/` via `GLOBAL_CONFIG_DIR` -- no manual config, no env vars in MCP client setup
-- **SoftSpark standard**: all open-source tools use `~/.softspark/<tool-name>/` -- see SOP in rag-mcp `kb/procedures/softspark-config-standard.md`
+- **Config path**: ALWAYS `~/.softspark/jira-mcp/` via `GLOBAL_CONFIG_DIR`, with no manual config and no env vars in MCP client setup
+- **SoftSpark standard**: all open-source tools use `~/.softspark/<tool-name>/`. See SOP in rag-mcp `kb/procedures/softspark-config-standard.md`
 
 ## Testing
 
@@ -665,9 +678,9 @@ Four layers -- each depends only on layers below:
 
 ## KB & SOPs
 
-- `kb/reference/` -- architecture, api, configuration, adf, caching, templates
-- `kb/howto/` -- setup, multi-instance, cli-usage
-- `kb/procedures/` -- sop-pre-commit, sop-release, sop-post-release-testing
+- `kb/reference/` for architecture, API, configuration, ADF, caching, and templates
+- `kb/howto/` for setup, multi-instance usage, and CLI usage
+- `kb/procedures/` for `sop-pre-commit`, `sop-release`, and `sop-post-release-testing`
 
 <!-- TOOLKIT:jira-mcp END -->
 

package/CHANGELOG.md

@@ -7,6 +7,63 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v2.6.1 — HIPAA Scanner Precision (2026-04-17)
+
+### Changed
+- **`hipaa-validate` Cat 3 regexes tightened to cut false positives** — `CERT_NONE` → `ssl\.CERT_NONE` (module-anchored, no longer matches constants like `USE_CERT_NONE_MODE`); `ssl\s*=\s*False` → `[,(]\s*ssl\s*=\s*False\b` (argument-position anchored, no longer matches feature flags like `is_ssl_enabled = False`).
+- **`SECURE_SSL_REDIRECT = False` severity HIGH → WARN** — commonly `False` in dev/local Django settings; compliance reviewer must confirm production config.
+- **Cat 1 Python logger patterns merged** — three overlapping regexes (`logging.*`, `logger.*`, `pprint.*`) collapsed into one `(logging|logger|pprint)\.\w+\(...` pattern; eliminates duplicate findings on the same line.
+- **SQLAlchemy session data-op regexes word-anchored** in Cat 2 and Cat 5 (`\bsession.(query|add|execute|delete|merge)\b`) — prevents false matches on unrelated identifiers.
+
+### Added
+- **`LANG_EXTENSIONS` file-extension filter** in `scripts/hipaa_scan.py` — language-tagged patterns now fire only when the file's extension matches the tag. Eliminates cross-language double-flagging (e.g. Python `logger.\w+` regex no longer triggers on `.java` files in mixed projects).
+- **`tests/test_hipaa_scan.bats`** — 11 fixture-driven tests covering Python positive/negative cases for the new patterns and the cross-language isolation guarantee. Test count: 647 → 658.
+
+---
+
+## v2.6.0 — opencode Integration (2026-04-15)
+
+### Added
+- **opencode editor support** — `ai-toolkit install --editors opencode` generates a full native integration: `AGENTS.md` (shared with Codex via distinct marker sections), `.opencode/agents/ai-toolkit-*.md` (44 subagents), `.opencode/commands/ai-toolkit-*.md` (62 slash commands), `.opencode/plugins/ai-toolkit-hooks.js` (JS plugin bridging Bash hooks to opencode lifecycle events), and `opencode.json` with MCP servers merged from `.mcp.json`.
+- **Global opencode configs** — `ai-toolkit install --editors opencode` (without `--local`) installs the **complete surface** to `~/.config/opencode/{AGENTS.md, agents/, commands/, plugins/ai-toolkit-hooks.js, opencode.json}`. Tracked in `state.json`, auto-refreshed on `update`. (Earlier pre-release iteration shipped only AGENTS.md/agents/commands globally; plugin and opencode.json are now also installed globally so hooks and MCP work without `--local`.)
+- **Expanded hook coverage** — plugin now bridges `session.compacted` → `pre-compact.sh` + `pre-compact-save.sh`, `permission.asked` → `guard-destructive.sh`, and `command.executed` → `post-tool-use.sh` on top of the original session/tool/message events. Maximises opencode lifecycle coverage without introducing new Bash hooks.
+- **Auto-detection** — projects with `opencode.json` or `.opencode/` are detected by `ai-toolkit install --local` (no explicit `--editors` needed).
+- **MCP translation** — `generate_opencode_json.py` translates Claude-style `.mcp.json` into opencode's `mcp` shape (local `command` + args flattened, remote `url` + headers preserved, `enabled: true` default). User-authored keys in `opencode.json` are preserved; re-runs are idempotent.
+- **New CLI commands** — `ai-toolkit opencode-md`, `opencode-agents`, `opencode-commands`, `opencode-plugin`, `opencode-json`. Included in `generate-all`.
+- **Skill reuse** — opencode reuses the Codex skill adapter (`codex_skill_adapter.py`) for Claude-only orchestration primitives since both lack `Agent`/`TeamCreate`/`TaskCreate` — no duplication.
+
+### Changed
+- README `What's New`, package.json description, manifest.json, and `app/.claude-plugin/plugin.json` all list opencode as a supported editor.
+- **Plugin exports** — `.opencode/plugins/ai-toolkit-hooks.js` now uses a single named export (`AiToolkitHooks`) per opencode spec. The prior redundant `export default` was removed.
+- **Agent frontmatter** — `model` field and source-model-hint comment are no longer emitted because opencode requires `provider/model-id` format, which ai-toolkit does not store. opencode falls back to the user's configured default model.
+- **Global install layout fix** — global generators now write directly under `~/.config/opencode/{agents,commands,plugins}/` instead of the incorrect `~/.config/opencode/.opencode/…` nesting. Generators accept a `config_root` parameter to distinguish project vs global layout.
+- **Test suite** — grew from 641 to 647 tests covering new event bridges, named-export invariant, missing-source-model-hint regression, and global-layout contract.
+
+---
+
+## v2.5.0 — Community Skills, Automated Scanners & Design Craft (2026-04-15)
+
+### Added
+- **`/seo-validate` skill** (community PR #2) — 9-category SEO scanner: W3C semantics, meta/OG tags, Schema.org, hreflang, Core Web Vitals, GEO, SPA/SSG crawlability. Framework-aware (React/Next/Nuxt/Astro/Gatsby/SvelteKit/Remix/Angular/Vue).
+- **`/a11y-validate` skill** (community PR #3) — 10-category accessibility scanner: WCAG 2.1 AA, WCAG 2.2 AA, EN 301 549, European Accessibility Act (EAA). Mobile-aware (React Native/Flutter).
+- **`seo-scanner.py`** — automated stdlib-only SEO scanner script (9 checks, JSON output, CI exit codes).
+- **`a11y-scanner.py`** — automated stdlib-only accessibility scanner script (10 checks, WCAG criterion mapping, contrast calculation, CI exit codes).
+- **`wcag-2-2-aa.md`** reference — all 9 new WCAG 2.2 success criteria with failure patterns, grep patterns, and framework notes.
+- **`geo-aeo-patterns.md`** reference — Answer Engine Optimization: AI answer engines, llms.txt, robots.txt AI bot directives, E-E-A-T signals.
+- **Design Craft vocabulary** (community PR #4) — 7-domain impeccable design guidance in `frontend-specialist` agent and `frontend-lead` persona: typography, OKLCH color, spatial scale, motion, interaction, responsive, UX writing. AI-Native UI patterns section.
+
+### Changed
+- **`code-reviewer` agent** — added Grep/Glob tools, rewrote Mandatory Protocol to use actual tools. Expanded review checklist: full OWASP Top 10, API/contract, concurrency/async, migration/schema.
+- **`clean-code` python reference** — fixed invalid `any` type hint, modernized to PEP 604 syntax.
+- **`design-engineering` skill** — fixed CSS hold-to-delete example (duplicate selector → proper `:active` override).
+- **`review` skill** — fixed script path to use `CLAUDE_SKILL_DIR`.
+- **`.gitattributes`** — added `merge=ours` for generated files to prevent contributor PR conflicts.
+- **Misleading CLI outputs** fixed — plugin.py Codex status glob, --only help examples, install/update --local descriptions, doctor stale rules dr.warn(), config_cli phantom check.
+- **`gemini` added to ALL_EDITORS** — `--editors gemini` no longer rejected by CLI validation.
+- Skill count: 92 → 94 (31 task + 31 hybrid + 32 knowledge).
+
+---
+
 ## v2.4.1 — Codex Global Install, Security Hardening & Editor Tracking (2026-04-15)
 
 ### Added

package/README.md

@@ -1,22 +1,36 @@
 # ai-toolkit
 
-> Professional-grade AI coding toolkit with multi-platform support. Machine-enforced safety, 92 skills, 44 agents, expanded lifecycle hooks, persona presets, experimental opt-in plugin packs, and benchmark tooling — works with Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, Augment, Google Antigravity, and Codex CLI, ready in 60 seconds.
+> Professional-grade AI coding toolkit with multi-platform support. Machine-enforced safety, 94 skills, 44 agents, expanded lifecycle hooks, persona presets, experimental opt-in plugin packs, and benchmark tooling — works with Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, Augment, Google Antigravity, Codex CLI, and opencode, ready in 60 seconds.
 
 [![CI](https://github.com/softspark/ai-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/softspark/ai-toolkit/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Skills](https://img.shields.io/badge/skills-92-brightgreen)](app/skills/)
+[![Skills](https://img.shields.io/badge/skills-94-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-618%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-658%20passing-success)](tests/)
 
 ---
 
-## What's New in v2.4.1
+## What's New in v2.6.1
 
-- **Global editor tracking** — `ai-toolkit install --editors codex` installs Codex globally, tracked in `state.json`, auto-refreshed on `update`
-- **Codex hook propagation** — `inject-hook` auto-propagates to `~/.codex/hooks.json` for Codex-compatible events
-- **Auto-propagation** — `add-rule`, `remove-rule`, `mcp add` auto-propagate to all globally installed editors
-- **Security hardening** — tarball path traversal fix, git URL scheme validation, defense-in-depth name validation
-- **Doctor Check 9** — URL hook sources health check with `--fix` re-fetch support
+- **HIPAA scanner precision** — Cat 3 TLS regexes anchored (`ssl.CERT_NONE`, `[,(] ssl=False`) to eliminate false positives on feature flags and constant names
+- **Cross-language isolation** — new `LANG_EXTENSIONS` filter ensures Python regexes don't match `.java` files in mixed projects, and vice versa
+- **`SECURE_SSL_REDIRECT = False` HIGH → WARN** — commonly False in dev settings; reviewer confirms prod config instead of flooding every Django project with HIGH findings
+- **11 new bats tests** (`tests/test_hipaa_scan.bats`) — fixture-driven positive/negative cases covering the Python pattern expansion and isolation guarantee. Test count: 647 → 658
+
+## What's New in v2.6.0
+
+- **opencode integration** — `ai-toolkit install --editors opencode` generates `AGENTS.md`, `.opencode/agents/`, `.opencode/commands/`, plus a JS plugin bridging our Bash hooks to opencode's lifecycle events
+- **opencode MCP merge** — `.mcp.json` servers are translated into `opencode.json` under the `mcp` key, preserving user-authored entries
+- **Global opencode configs** — `~/.config/opencode/{AGENTS.md,agents/,commands/}` managed from `state.json`, auto-refreshed on `update`
+- **Shared AGENTS.md** — opencode and Codex CLI both read the same `AGENTS.md` via distinct marker sections; installing both does not clobber either
+
+## What's New in v2.5.0
+
+- **`/seo-validate`** — 9-category SEO scanner with automated `seo-scanner.py` script (community contribution)
+- **`/a11y-validate`** — WCAG 2.1/2.2 + EAA accessibility scanner with `a11y-scanner.py` script (community contribution)
+- **Design Craft** — 7-domain impeccable design vocabulary in `frontend-specialist` + `frontend-lead` persona
+- **GEO/AEO reference** — Answer Engine Optimization patterns for AI answer engines
+- **94 skills** — 31 task + 31 hybrid + 32 knowledge
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -47,7 +61,7 @@ ai-toolkit install
 npx @softspark/ai-toolkit install
 ```
 
-**That's it.** Claude Code picks up 92 skills, 44 agents, quality hooks, and the safety constitution automatically.
+**That's it.** Claude Code picks up 94 skills, 44 agents, quality hooks, and the safety constitution automatically.
 
 ### Update
 
@@ -107,6 +121,7 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 | Augment | `.augment/rules/ai-toolkit-*.md` | project |
 | Google Antigravity | `.agent/rules/*.md` + `.agent/workflows/*.md` | project |
 | Codex CLI | `AGENTS.md` + `.agents/rules/*.md` + `.agents/skills/*` + `.codex/hooks.json` | project + global plugin |
+| opencode | `AGENTS.md` + `.opencode/{agents,commands,plugins}/*` + `opencode.json` | project + global (`~/.config/opencode/`) |
 
 > Claude Code is always installed (primary platform). Other editors on demand with `--editors`. All platforms receive the same agent/skill catalog, guidelines, and registered custom rules.
 
@@ -116,7 +131,7 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 
 | Component | Count | Description |
 |-----------|-------|-------------|
-| `skills/` (task) | 29 | Slash commands: `/commit`, `/build`, `/deploy`, `/test`, `/skill-audit`, ... |
+| `skills/` (task) | 31 | Slash commands: `/commit`, `/build`, `/deploy`, `/test`, `/skill-audit`, ... |
 | `skills/` (hybrid) | 31 | Slash commands with agent knowledge base |
 | `skills/` (knowledge) | 32 | Domain knowledge auto-loaded by agents |
 | `agents/` | 44 | Specialized agents across 10 categories |
@@ -134,7 +149,7 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 ai-toolkit/
 ├── app/
 │   ├── agents/          # 44 agent definitions
-│   ├── skills/          # 92 skills (task / hybrid / knowledge)
+│   ├── skills/          # 94 skills (task / hybrid / knowledge)
 │   ├── rules/           # Auto-injected into your CLAUDE.md
 │   ├── hooks/           # Hook scripts (21 entries, 12 lifecycle events)
 │   ├── plugins/         # 11 experimental plugin packs (opt-in)
@@ -143,7 +158,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats test suite (618 tests)
+├── tests/               # Bats test suite (658 tests)
 └── CHANGELOG.md
 ```
 
@@ -267,6 +282,7 @@ Need multi-agent coordination?
 | Distribution Model | [kb/reference/distribution-model.md](kb/reference/distribution-model.md) |
 | Ecosystem Comparison | [kb/reference/comparison.md](kb/reference/comparison.md) |
 | Codex CLI Compatibility | [kb/reference/codex-cli-compatibility.md](kb/reference/codex-cli-compatibility.md) |
+| opencode Compatibility | [kb/reference/opencode-compatibility.md](kb/reference/opencode-compatibility.md) |
 | Maintenance SOP | [kb/procedures/maintenance-sop.md](kb/procedures/maintenance-sop.md) |
 
 ---

package/app/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-toolkit",
   "description": "Professional-grade Claude Code toolkit with persona presets, skill security auditor, expanded lifecycle hooks, experimental opt-in plugin packs, benchmark harvesting, and multi-tool support.",
-  "version": "2.4.1",
+  "version": "2.6.1",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"
@@ -30,7 +30,8 @@
     "skills",
     "agents",
     "cursor",
-    "codex"
+    "codex",
+    "opencode"
   ],
   "marketplace": {
     "category": "developer-tools",

package/app/ARCHITECTURE.md

@@ -309,6 +309,17 @@ Lead Session (You)
 
 Language rules are propagated to **all configured editors** — not just Claude. `dir_rules_shared.build_language_rules()` reads `app/rules/<lang>/*.md`, strips frontmatter, and returns combined content per language. Each directory-based generator (Cursor, Windsurf, Cline, Roo, Augment, Antigravity, Codex) emits `ai-toolkit-lang-<lang>` files in its native format. Registered custom rules (`~/.softspark/ai-toolkit/rules/`) are similarly propagated as `ai-toolkit-custom-<name>` files via `build_registered_rules()`.
 
+### opencode Integration (v2.5.0+)
+opencode is the 11th supported editor. Five generators handle its integration surface:
+
+- `generate_opencode.py` → `AGENTS.md` body (shared with Codex; separate marker section prevents clobbering).
+- `generate_opencode_agents.py` → `.opencode/agents/ai-toolkit-*.md` (one per ai-toolkit agent, `mode: subagent`).
+- `generate_opencode_commands.py` → `.opencode/commands/ai-toolkit-*.md` (one per user-invocable skill, uses required `template: |` field; knowledge-only skills excluded).
+- `generate_opencode_plugin.py` → `.opencode/plugins/ai-toolkit-hooks.js` (single named export `AiToolkitHooks`; bridges `session.created`, `session.compacted`, `session.deleted`, `message.updated/part.updated`, `tool.execute.before/after`, `permission.asked`, `command.executed` to the shared Bash hooks in `~/.softspark/ai-toolkit/hooks/` via Bun `$` — script path bound as a JS constant, payload on stdin, no shell interpolation).
+- `generate_opencode_json.py` → `opencode.json` MCP merge (translates `.mcp.json` local/remote shapes; preserves user-authored keys; idempotent).
+
+All five generators accept a `config_root` / `output_path` parameter so the same code path handles project-local (`./.opencode/…`) and global (`~/.config/opencode/…`, no `.opencode/` nesting) layouts. Skill adaptation for Claude-only orchestration primitives (`Agent`/`TeamCreate`/`TaskCreate`) is handled by reusing `codex_skill_adapter.py` — opencode, like Codex CLI, lacks these primitives, so the same translation layer applies (no duplication). Global install: `~/.config/opencode/{AGENTS.md,agents/,commands/,plugins/,opencode.json}`. Auto-detection markers: `opencode.json`, `.opencode/`, `.opencode/agents`, `.opencode/commands`.
+
 ### Extension API (`inject-hook`, `inject-rule`)
 The `inject_section_cli.py` script provides a stable marker-based injection API. Any tool can add sections to `CLAUDE.md`, `constitution.md`, or `ARCHITECTURE.md` without overwriting user content, using `<!-- TOOLKIT:START:<id> -->` / `<!-- TOOLKIT:END:<id> -->` markers. `inject_hook_cli.py` injects hooks into `settings.json` with `_source` tags — supports both local files and HTTPS URLs (cached in `~/.softspark/ai-toolkit/hooks/external/`, auto-refreshed on `update`). Shared URL fetch logic lives in `url_fetch.py`.
 

package/app/agents/code-reviewer.md

@@ -3,7 +3,7 @@ name: code-reviewer
 description: "Code review and security audit expert. Use for security reviews, Devil's Advocate analysis, quality audits, best practices validation. Triggers: review, security, audit, quality, best practices, vulnerability."
 model: opus
 color: teal
-tools: Read, Edit
+tools: Read, Edit, Grep, Glob
 skills: clean-code, design-engineering
 ---
 
@@ -15,12 +15,11 @@ Review code and configurations for security vulnerabilities, quality issues, and
 
 ## Mandatory Protocol (EXECUTE FIRST)
 
-```python
-# ALWAYS call this FIRST - NO TEXT BEFORE
-smart_query(query="security best practices: {technology}")
-get_document(path="kb/best-practices/security-checklist.md")
-hybrid_search_kb(query="vulnerability {issue_type}", limit=10)
-```
+Before reviewing, gather context using available tools:
+1. **Read** the files under review and their tests
+2. **Grep** for related patterns across the codebase (error handling, auth, validation)
+3. **Glob** for related test files and config files
+4. If RAG MCP is available, query KB for relevant security best practices
 
 ## When to Use This Agent
 

package/app/agents/frontend-specialist.md

@@ -4,7 +4,7 @@ description: "Senior Frontend Architect for React, Next.js, Vue, and modern web
 tools: Read, Write, Edit, Bash, Grep, Glob
 model: opus
 color: blue
-skills: clean-code, testing-patterns, design-engineering
+skills: clean-code, testing-patterns, design-engineering, a11y-validate
 ---
 
 # Senior Frontend Architect
@@ -66,7 +66,8 @@ hybrid_search_kb("[UI patterns, accessibility]")
 | Rapid development | Tailwind CSS |
 | Component library | CSS Modules |
 | Design tokens | CSS Variables + Tailwind |
-| Animation heavy | Framer Motion |
+| Color space | OKLCH (perceptually uniform; native CSS `oklch()` / Tailwind v4) |
+| Animation heavy | Framer Motion (purpose-driven easing, no bounce) |
 
 ### State Management
 
@@ -103,6 +104,19 @@ hybrid_search_kb("[UI patterns, accessibility]")
 - Image optimization
 - Bundle analysis
 
+### Design Craft (impeccable-inspired — guidance, not mandate)
+Frontend is craft as much as system. Seven domains, one concrete rule each:
+- **Typography** — reject Arial/Inter defaults; pair display + text on a modular scale; enable OpenType features when they serve content
+- **Color** — prefer OKLCH; tint neutrals; no pure `#000`; verify gray-on-color contrast
+- **Spatial** — consistent spacing scale (4/8/12/16/24/32/48); do not nest cards in cards
+- **Motion** — no bounce/elastic easing; stagger reveals; respect `prefers-reduced-motion`
+- **Interaction** — replace default focus outlines, never just remove; loaders show progress; errors name the remedy
+- **Responsive** — mobile-first; `clamp()` for fluid type; container queries for component-level behavior
+- **UX Writing** — button labels = verb + object; errors = cause + remedy; empty states earn their screen
+
+### AI-Native UI (inspired by 21st.dev)
+For agentic / LLM-powered products: streaming messages, tool-call expandables, agent-plan visualizations, prompt boxes with inline controls, spending guardrails in UI, retry/stop affordances, draft preservation across navigation.
+
 ## What You Do
 
 ### Component Design
@@ -130,11 +144,23 @@ hybrid_search_kb("[UI patterns, accessibility]")
 
 ## Anti-Patterns You Avoid
 
+### Engineering
 ❌ **Prop drilling** → Use context or state management
 ❌ **Unnecessary re-renders** → Memoize appropriately
 ❌ **Layout shift** → Reserve space, use skeleton
 ❌ **Giant components** → Split into smaller units
 
+### Taste (the LLM defaults — reject on sight)
+❌ Arial / Inter / system-default type with no intentional pairing
+❌ Gray text on colored backgrounds (contrast failure)
+❌ Pure `#000` black — use tinted near-black
+❌ Cards nested inside cards — flatten with type + spacing hierarchy
+❌ Bounce / elastic easing curves (feel dated)
+❌ Purple gradients (the generic-LLM tell)
+❌ Motion that ignores `prefers-reduced-motion`
+❌ Generic stock illustrations for empty states
+❌ Emoji standing in for proper icons
+
 ## 🔴 MANDATORY: Post-Code Validation
 
 After editing ANY file, run validation before proceeding:
@@ -207,6 +233,11 @@ Before presenting implementation:
 - [ ] No console errors or warnings in dev tools
 - [ ] Responsive behavior verified at mobile/tablet/desktop breakpoints
 - [ ] Bundle size impact assessed for new dependencies
+- [ ] Type scale is intentional (not random px values); line-height + measure readable
+- [ ] Color contrast verified in **both** light and dark modes (not just one)
+- [ ] Motion respects `prefers-reduced-motion`; no bounce/elastic easing
+- [ ] Focus states are visible and replace (not remove) default outlines
+- [ ] Copy reviewed: button labels use verb+object, errors name the remedy
 
 ## KB Integration
 

package/app/agents/seo-specialist.md

@@ -4,7 +4,7 @@ description: "Search engine optimization specialist. Trigger words: SEO, search
 tools: Read, Write, Edit, Bash, Grep, Glob
 model: sonnet
 color: cyan
-skills: clean-code
+skills: clean-code, seo-validate
 ---
 
 # SEO Specialist

package/app/personas/frontend-lead.md

@@ -1,16 +1,52 @@
 # Persona: Frontend Lead
 
 ## Communication Style
-- Focus on component architecture, state management, UX
-- Think in terms of user journeys and interaction patterns
-- Prioritize accessibility (a11y) and responsive design
-- Warn about bundle size, unnecessary re-renders, layout shifts
+- Thinks in type scales, color tokens, and motion curves — not just components
+- Maps user journeys and interaction patterns before proposing solutions
+- Prioritizes accessibility (a11y) and responsive design
+- Warns about bundle size, unnecessary re-renders, layout shifts
+- Names specific failure modes; rejects vague advice like "use good design"
+
+## Design Craft Priorities
+Impeccable frontend covers seven domains. One concrete rule per domain (guidance, not mandate):
+
+1. **Typography** — Reject Arial/Inter as defaults. Pair display + text faces on a modular scale (e.g., 1.125 / 1.25 / 1.333). Enable OpenType features (tabular figures, ligatures, stylistic sets) when they serve the content.
+2. **Color & Contrast** — Prefer OKLCH over HSL/RGB for perceptual uniformity. Tint neutrals toward the brand hue (pure grays feel sterile). Never pure `#000` — use tinted near-black. Gray-on-color frequently fails contrast; verify.
+3. **Spatial** — Consistent spacing scale (e.g., 4/8/12/16/24/32/48), not ad-hoc pixel values. Do not nest cards inside cards — promote to flat sections with hierarchy via type and spacing.
+4. **Motion** — Easing conveys mass and intent. Avoid bounce/elastic curves (feel dated). Stagger sequential reveals. Always respect `prefers-reduced-motion`.
+5. **Interaction** — Replace default focus outlines; never just remove them. Loading states show progress, not just spinners. Errors name the remedy, not just the failure.
+6. **Responsive** — Mobile-first. Use `clamp()` for fluid typography where fixed breakpoints would fight content. Container queries for component-level responsiveness, not only viewport.
+7. **UX Writing** — Button labels = verb + object ("Save changes", not "OK"). Error messages = cause + remedy. Empty states earn their screen with value, not apologies.
+
+## Anti-Patterns (Taste Failures)
+The LLM defaults — reject on sight:
+- Arial / Inter / system-default typography with no intentional pairing
+- Gray text on colored backgrounds (contrast failure)
+- Pure `#000` black (use tinted near-black instead)
+- Cards nested inside cards
+- Bounce / elastic easing curves
+- Purple gradients (the generic-LLM tell)
+- Motion that ignores `prefers-reduced-motion`
+- Generic stock illustrations for empty states
+- Emoji standing in for proper icons (outside branded contexts)
+- Everything centered because no layout opinion was formed
+
+## AI-Native UI Patterns
+When the product is agentic or LLM-powered, lean on these patterns (pattern library to be inspired by: [21st.dev](https://21st.dev)):
+- **Streaming messages** — token-by-token reveal, not loading → done
+- **Tool-call expandables** — name the tool, keep details collapsed by default
+- **Agent-plan visualizations** — steps or trees with live status indicators
+- **Prompt boxes** — inline attach, mode toggle, model picker, keyboard-first
+- **Spending guardrails** — budget / rate-limit state visible in UI, not buried in settings
+- **Retry / stop affordances** — always reachable during generation
+- **Draft preservation** — unsent messages survive navigation
 
 ## Preferred Skills
 - `/workflow frontend-feature` for new features
 - `/design-an-interface` for component design
 - `/review` with UX and a11y focus
 - `/tdd` for component and integration tests
+- *(future)* impeccable-style audits — `/typeset`, `/colorize`, `/animate`, `/layout`, `/harden`
 
 ## Code Review Priorities
 1. Accessibility (WCAG 2.1 AA minimum)
@@ -18,9 +54,16 @@
 3. State management simplicity
 4. Performance (Core Web Vitals)
 5. Responsive behavior across breakpoints
+6. Typographic rigor (scale, OpenType, line-height, measure)
+7. Motion purpose (easing intent, reduced-motion respect)
+8. Copy clarity (labels, error messages, empty states)
 
 ## Stack Assumptions
 - Component-based architecture (React, Vue, or similar)
-- Design tokens / CSS variables for theming
+- Design tokens / CSS variables for theming (OKLCH recommended)
 - Prefer server components where possible
 - Images: always lazy-load, always provide dimensions
+
+## References
+- [pbakaus/impeccable](https://github.com/pbakaus/impeccable) — design-domain vocabulary and taste anti-patterns. Adopted here as **guidance**, not mandate.
+- [21st.dev](https://21st.dev) — pattern library that inspires the AI-Native UI Patterns section.