@softspark/ai-toolkit 2.0.2 → 2.1.1

package/kb/reference/plugin-pack-conventions.md

@@ -5,15 +5,15 @@ service: ai-toolkit
 tags: [plugins, plugin-packs, conventions, manifests, hooks, policy-packs]
 version: "1.0.0"
 created: "2026-03-28"
-last_updated: "2026-04-02"
-description: "Conventions for experimental ai-toolkit plugin packs, policy packs, hook packs, and plugin-creator scaffolding."
+last_updated: "2026-04-13"
+description: "Conventions for experimental ai-toolkit plugin packs, policy packs, hook packs, and plugin-creator scaffolding across Claude and Codex runtimes."
 ---
 
 # Plugin Pack Conventions
 
 ## Purpose
 
-`ai-toolkit` now includes experimental plugin packs under `app/plugins/` to formalize a Claude Code-compatible plugin direction without changing the default global install surface.
+`ai-toolkit` now includes experimental plugin packs under `app/plugins/` to formalize a runtime-aware plugin direction for Claude and optional global Codex layering without changing the default core install surface.
 
 ## Pack Types
 
@@ -73,32 +73,34 @@ Required keys:
 
 ```bash
 ai-toolkit plugin list               # show all 11 packs with install status
-ai-toolkit plugin install <name>     # install a single pack
-ai-toolkit plugin install --all      # install all 11 packs
-ai-toolkit plugin update <name>      # update a pack (remove + reinstall, preserves data)
-ai-toolkit plugin update --all       # update all installed packs
+ai-toolkit plugin install --editor claude <name>   # Claude global target
+ai-toolkit plugin install --editor codex <name>    # Codex global target
+ai-toolkit plugin install --editor all --all       # install all 11 packs for both runtimes
+ai-toolkit plugin update --editor all --all        # update all installed packs
 ai-toolkit plugin clean <name>       # prune data older than 90 days (default)
 ai-toolkit plugin clean <name> --days 30  # prune data older than 30 days
-ai-toolkit plugin remove <name>      # remove a pack
-ai-toolkit plugin remove --all       # remove all installed packs
-ai-toolkit plugin status             # show installed packs with data stats
+ai-toolkit plugin remove --editor codex <name>     # remove from one runtime only
+ai-toolkit plugin remove --editor all --all        # remove all installed packs everywhere
+ai-toolkit plugin status --editor all              # show installed packs with runtime details
 ```
 
 ### What `plugin install` Does
 
-1. **Verifies** referenced agents/skills exist in `~/.claude/` (links them from core if missing)
+1. **Parses** `--editor claude|codex|all` (default: `claude`)
 2. **Copies** plugin-specific hooks to `~/.softspark/ai-toolkit/hooks/plugin-<pack>-<hook>.sh`
 3. **Copies** plugin-specific scripts to `~/.softspark/ai-toolkit/plugin-scripts/<pack>/`
 4. **Runs** init scripts if present (e.g. `init_db.py` for memory-pack — safe to re-run, preserves data)
-5. **Merges** plugin hooks into `~/.claude/settings.json` (tagged with `_source: ai-toolkit-plugin-<name>`)
-6. **Records** installed state to `~/.softspark/ai-toolkit/plugins.json`
+5. **Claude target**: links missing agents/skills into `~/.claude/`, injects plugin-local rules into `~/.claude/CLAUDE.md`, and merges plugin hook entries into `~/.claude/settings.json`
+6. **Codex target**: bootstraps global Codex assets in `HOME` (`~/AGENTS.md`, `~/.agents/skills`, `~/.agents/rules`, `~/.codex/hooks.json`) and then layers plugin-specific rules/hooks on top
+7. **Records** installed state per runtime in `~/.softspark/ai-toolkit/plugins.json`
 
 ### What `plugin update` Does
 
-1. **Removes** existing plugin hooks, scripts, and settings.json entries (same as `remove`)
+1. **Removes** existing plugin runtime entries for the selected editor(s) (same as `remove`)
 2. **Reinstalls** from the current source (same as `install`)
 3. **Preserves plugin data** (e.g. memory-pack SQLite database is never deleted)
-4. `--all` updates only currently installed packs (not all available)
+4. Shared plugin scripts/hooks are kept if another runtime still has the same pack installed
+5. `--all` updates only currently installed packs for the selected runtime(s)
 
 ### What `plugin clean` Does
 
@@ -108,10 +110,10 @@ ai-toolkit plugin status             # show installed packs with data stats
 
 ### What `plugin remove` Does
 
-1. **Removes** plugin hooks from `~/.softspark/ai-toolkit/hooks/`
-2. **Removes** plugin scripts from `~/.softspark/ai-toolkit/plugin-scripts/`
-3. **Strips** plugin hook entries from `settings.json` (by `_source` tag)
-4. **Updates** `plugins.json` state
+1. **Claude target**: strips plugin hook entries from `~/.claude/settings.json` and removes plugin-local rule sections from `~/.claude/CLAUDE.md`
+2. **Codex target**: strips plugin hook entries from `~/.codex/hooks.json` and removes `~/.agents/rules/plugin-<pack>-*.md`
+3. **Shared assets** (`~/.softspark/ai-toolkit/hooks/plugin-*`, `plugin-scripts/<pack>/`) are removed only when no remaining runtime still uses that pack
+4. **Updates** `plugins.json` state per runtime
 5. **Leaves** core agents/skills untouched (they belong to the base install)
 6. **Leaves** plugin data intact (e.g. `memory.db` — use `clean` to prune)
 
@@ -119,7 +121,7 @@ ai-toolkit plugin status             # show installed packs with data stats
 
 - **Auto-retention**: `session-summary.sh` hook auto-prunes observations older than 90 days on every session end (configurable via `MEMORY_RETENTION_DAYS` env var)
 - **Manual clean**: `ai-toolkit plugin clean memory-pack --days 30`
-- **Status**: `ai-toolkit plugin status` shows DB size, observation count, date range
+- **Status**: `ai-toolkit plugin status --editor claude|codex|all` shows runtime-specific install details plus DB size, observation count, and date range where relevant
 
 ## Current Experimental Packs
 
@@ -148,4 +150,3 @@ ai-toolkit plugin status             # show installed packs with data stats
 - `hooks/session-summary.sh` — summarizes session on Stop
 
 These are intentionally excluded from the default install until explicitly enabled via `ai-toolkit plugin install`.
-

package/kb/reference/skills-catalog.md

@@ -3,10 +3,10 @@ title: "AI Toolkit - Skills Catalog"
 category: reference
 service: ai-toolkit
 tags: [skills, domain-knowledge, catalog, task-skills, hybrid-skills]
-version: "1.4.2"
+version: "1.4.3"
 created: "2026-03-23"
-last_updated: "2026-04-09"
-description: "Complete skills catalog with task, hybrid, and knowledge skills. Includes effort levels, skill-scoped hooks, executable scripts, security auditor, and persona presets."
+last_updated: "2026-04-12"
+description: "Complete skills catalog with task, hybrid, and knowledge skills. Includes Codex adaptation notes, effort levels, skill-scoped hooks, executable scripts, security auditor, and persona presets."
 ---
 
 # Skills Catalog
@@ -73,9 +73,9 @@ Hybrid skills combine slash-command invocation with domain knowledge that agents
 | **docs** | `/docs` | high | Generate/update docs: README, API docs, architecture notes, changelogs (Tier 1 — single agent) |
 | **search** | `/search` | medium | Search knowledge base (MCP tools with local fallback) |
 | **explain** | `/explain` | medium | Explain architecture of a file/module using Mermaid diagrams |
-| **orchestrate** | `/orchestrate` | max | Custom multi-agent parallelism — Tier 3, spawns agents via Agent tool |
+| **orchestrate** | `/orchestrate` | max | Custom multi-agent parallelism — Tier 3, native in Claude, Codex-adapted to `spawn_agent` workflows |
 | **swarm** | `/swarm` | max | Massive parallelism: map-reduce, consensus, relay — Tier 3 |
-| **workflow** | `/workflow` | max | 15 predefined multi-agent workflow types — Tier 2 |
+| **workflow** | `/workflow` | max | 15 predefined multi-agent workflow types — Tier 2, Codex-adapted to native subagent orchestration |
 | **instinct-review** | `/instinct-review` | low | Review, curate, and manage learned instincts from past sessions |
 | **teams** | `/teams` | max | Launch pre-configured Agent Teams compositions for common workflows |
 | **write-a-prd** | `/write-a-prd` | high | Create PRD through interactive interview, codebase exploration, and module design |
@@ -250,6 +250,28 @@ Step 0 interview before setup — 5 targeted questions to capture undocumented p
 - `allowed-tools: ...` — tools available to the agent when processing this skill
 - `depends-on: skill-a, skill-b` — declares dependencies on other skills (validated by `validate.py`)
 
+### Codex CLI Adaptation
+
+Codex CLI receives the full skill catalog during `ai-toolkit install --local --editors codex`.
+
+- Native Codex-compatible skills are symlinked directly into `.agents/skills/`
+- Claude-oriented orchestration skills are generated as Codex wrappers
+- Adapted wrappers translate `Agent`, `Team*`, and `Task*` guidance to `spawn_agent`, `send_input`, `wait_agent`, `close_agent`, and `update_plan`
+
+Common adapted skills:
+
+- `/orchestrate`
+- `/workflow`
+- `/swarm`
+- `/teams`
+- `/subagent-development`
+- `/tdd`
+
+The translated skill content keeps the original support assets (`reference/`,
+`scripts/`, `assets/`) while replacing Claude-specific runtime instructions.
+
+See `kb/reference/codex-cli-compatibility.md` for the detailed mapping and hook limits.
+
 ### Skill Dependencies (`depends-on`)
 Skills can declare dependencies on other skills (primarily knowledge skills) for documentation and validation:
 ```yaml

package/kb/reference/unique-features.md

@@ -0,0 +1,213 @@
+---
+title: "Unique Features & Differentiators"
+category: reference
+service: ai-toolkit
+tags: [features, differentiators, constitution, hooks, security, tdd, memory]
+created: "2026-04-13"
+last_updated: "2026-04-13"
+description: "Detailed description of ai-toolkit's unique features: constitution enforcement, hooks system, security scanning, effort budgeting, quality gates, and more."
+---
+
+# Unique Features & Differentiators
+
+## 1. Machine-Enforced Constitution
+
+Unlike other toolkits that put safety rules in documentation only, ai-toolkit enforces a 5-article constitution via `PreToolUse` hooks. The hook actually **blocks** execution of:
+- Mass deletion (`rm -rf`, `DROP TABLE`)
+- Blind overwrites of uncommitted work
+- Any action that could cause irreversible data loss
+
+## 2. Hooks as Executable Scripts
+
+Hook logic lives in `app/hooks/*.sh` — not inline JSON one-liners. Scripts are copied to `~/.softspark/ai-toolkit/hooks/` on install and referenced from `~/.claude/settings.json`. Easy to read, debug, and extend.
+
+**12 lifecycle events / 21 global hook entries:**
+
+| Event | Script | Action |
+|-------|--------|--------|
+| SessionStart | `session-start.sh` | MANDATORY rules reminder + session context + instincts |
+| SessionStart | `mcp-health.sh` | Check MCP server command availability (non-blocking warning) |
+| SessionStart | `session-context.sh` | Capture environment snapshot to `~/.softspark/ai-toolkit/sessions/current-context.json` |
+| Notification | `notify-waiting.sh` | Cross-platform desktop notification |
+| PreToolUse | `guard-destructive.sh` | Block `rm -rf`, `DROP TABLE`, etc. |
+| PreToolUse | `guard-path.sh` | Block wrong-user path hallucination |
+| PreToolUse | `guard-config.sh` | Block edits to linter/formatter config files unless explicitly requested |
+| PreToolUse | `commit-quality.sh` | Advisory validation of git commit messages |
+| UserPromptSubmit | `user-prompt-submit.sh` | Prompt governance reminder |
+| UserPromptSubmit | `track-usage.sh` | Record skill invocations to local stats |
+| PostToolUse | `post-tool-use.sh` | Lightweight validation reminders after edits |
+| PostToolUse | `governance-capture.sh` | Log security-sensitive operations to JSONL |
+| Stop | `quality-check.sh` | Multi-language lint (ruff/tsc/phpstan/dart/go) |
+| Stop | `save-session.sh` | Persist session context for cross-session continuity |
+| TaskCompleted | `quality-gate.sh` | Block task completion on lint/type errors |
+| SubagentStart | `subagent-start.sh` | Narrow-scope reminder for spawned subagents |
+| SubagentStop | `subagent-stop.sh` | Completion checklist for subagent handoff |
+| PreCompact | `pre-compact.sh` | Smart compaction: prioritized context |
+| PreCompact | `pre-compact-save.sh` | Save timestamped context backup |
+| SessionEnd | `session-end.sh` | Persist a session-end handoff note |
+| TeammateIdle | *(inline)* | Completeness reminder |
+
+**5 skill-scoped hooks:**
+
+| Skill | Hook | Action |
+|-------|------|--------|
+| `/commit` | Pre | Run linter, block on failure |
+| `/test` | Post | Coverage check, report threshold |
+| `/deploy` | Post | Health check, rollback if degraded |
+| `/migrate` | Pre | Backup verification |
+| `/rollback` | Post | State verification |
+
+## 3. Security Scanning
+
+Two complementary security tools:
+
+**`/skill-audit`** — scan skills and agents for code-level risks:
+
+```bash
+/skill-audit                              # Interactive (Claude remediation)
+python3 scripts/audit_skills.py --ci      # CI mode: exit 1 on HIGH
+```
+
+Detects: `eval()`/`exec()`, hardcoded secrets, permission issues, bash risks.
+
+**`/cve-scan`** — scan project dependencies for known CVEs:
+
+```bash
+/cve-scan                                 # Auto-detect ecosystems, scan all
+python3 app/skills/cve-scan/scripts/cve_scan.py          # Direct invocation
+python3 app/skills/cve-scan/scripts/cve_scan.py --json   # Machine-readable
+```
+
+Supports: npm, pip, composer, cargo, go, ruby, dart. Uses native audit tools — zero external deps.
+
+**Severity levels:** HIGH (blocks CI), WARN (should fix), INFO (review)
+
+## 4. Effort-Based Model Budgeting
+
+Every skill declares an effort level used for model token budgeting:
+- `low` — lint, build, fix (fast, cheap)
+- `medium` — debug, analyze, ci
+- `high` — review, plan, refactor, docs
+- `max` — orchestrate, swarm, workflow
+
+## 5. Multi-Language Quality Gates
+
+The `Stop` hook runs after every response across 5 languages:
+
+| Language | Lint | Type Check |
+|----------|------|-----------|
+| Python | ruff | mypy --strict |
+| TypeScript | ESLint/tsc | tsc --noEmit |
+| PHP | phpstan | phpstan |
+| Dart | dart analyze | dart analyze |
+| Go | go vet | go vet |
+
+## 6. Iron Law Enforcement
+
+Three skills enforce non-negotiable quality gates with anti-rationalization tables:
+
+| Skill | Iron Law | What it prevents |
+|-------|----------|-----------------|
+| `/tdd` | `NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST` | Code written before test? Delete it. Start over. |
+| `debugging-tactics` | `NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST` | 4-phase debugging: root cause → pattern → hypothesis → fix. |
+| `verification-before-completion` | `NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE` | Gate: IDENTIFY → RUN → READ → VERIFY → CLAIM. |
+
+Additionally, **15 core skills** include `## Common Rationalizations` tables — domain-specific excuses with rebuttals that prevent agent drift.
+
+## 7. Confidence Scoring & Self-Evaluation (`/review`)
+
+The `/review` skill outputs findings with per-issue confidence scores (1-10) and severity classification (critical/major/minor/nit). After completing a review, an LLM-as-Judge self-evaluation pass checks for blind spots: anchoring bias, assumption vs verification, missing unhappy paths, and calibrates confidence scores.
+
+## 8. Agent Verification Checklists
+
+10 key agents include `## Verification Checklist` — exit criteria that MUST be met before presenting results:
+
+| Agent | Key exit criteria |
+|-------|------------------|
+| `code-reviewer` | Every finding has file:line + evidence, not just opinion |
+| `security-auditor` | Each finding includes proof-of-concept or exploit path |
+| `test-engineer` | No empty/placeholder tests, mocks only at boundaries |
+| `debugger` | Root cause identified, regression test added |
+| `backend-specialist` | Input validation, error format, query optimization |
+| `frontend-specialist` | Empty/loading/error states, accessibility, responsive |
+| `database-architect` | Migration tested on prod-like volume, rollback tested |
+| `performance-optimizer` | Baseline measured, profiler evidence attached |
+| `devops-implementer` | Dry run passed, rollback documented, no hardcoded secrets |
+| `documenter` | Code examples runnable, no placeholders, valid links |
+
+## 9. Skill Reference Routing
+
+7 core skills include `## Related Skills` sections that suggest logical follow-up skills:
+
+```
+/review → found issues? → /debug, /tdd, /cve-scan, /analyze
+/debug  → bug fixed?   → /review, /tdd, /workflow incident-response
+/plan   → approved?    → /orchestrate, /write-a-prd, /grill-me
+```
+
+## 10. Two-Stage Review (`/subagent-development`)
+
+Per-task review pipeline inspired by [obra/superpowers](https://github.com/obra/superpowers):
+
+```
+Implementer → Spec Compliance Review → Code Quality Review → Next Task
+```
+
+- Implementer reports: `DONE` / `DONE_WITH_CONCERNS` / `NEEDS_CONTEXT` / `BLOCKED`
+- Spec reviewer: all requirements met, nothing extra, nothing missing
+- Quality reviewer: SOLID, naming, error handling, tests, security
+
+## 11. Ralph Wiggum Loop (`/repeat`)
+
+Autonomous agent loop with safety controls:
+
+```bash
+/repeat 5m /test          # run tests every 5 min until all pass
+/repeat --iterations 3 /review   # max 3 review passes
+```
+
+| Safety Control | Default |
+|----------------|---------|
+| Max iterations | 5 |
+| Circuit breaker | 3 consecutive failures → halt |
+| Min interval | 1 minute |
+| Exit detection | DONE / COMPLETE / ALL PASS |
+
+## 12. Persistent Memory (`memory-pack` plugin)
+
+SQLite-based session memory (opt-in plugin pack):
+
+| Component | Purpose |
+|-----------|---------|
+| `observation-capture.sh` | PostToolUse hook — captures tool actions to SQLite |
+| `session-summary.sh` | Stop hook — AI-compress session observations |
+| `mem-search` skill | FTS5 full-text search across past sessions |
+| `<private>` tags | Content between tags stripped before storage |
+| Progressive disclosure | Summary (~500 tok) → relevant (~2k tok) → full |
+
+## 13. Persona Presets
+
+4 engineering personas that adjust Claude's communication style per role:
+
+| Persona | Focus | Key Skills |
+|---------|-------|------------|
+| `backend-lead` | System design, scalability, data integrity | `/workflow backend-feature`, `/tdd` |
+| `frontend-lead` | Component architecture, a11y, Core Web Vitals | `/design-an-interface`, `/review` |
+| `devops-eng` | IaC, CI/CD, blast radius, rollback safety | `/workflow infrastructure-change`, `/deploy` |
+| `junior-dev` | Step-by-step explanations, learning focus | `/explain`, `/explore`, `/debug` |
+
+Persistent via `--persona` at install time, or session-scoped via `/persona` runtime command.
+
+## 14. Visual Brainstorming Companion
+
+Optional browser-based companion for `/write-a-prd` and `/design-an-interface`:
+- Ephemeral Node.js HTTP server (auto-kills after 30min idle)
+- Dark theme, responsive, zero external dependencies
+- Per-question routing: mockups/diagrams → browser, text/conceptual → terminal
+
+## 15. KB Integration Protocol
+
+Agents follow a research-before-action protocol enforced via rules:
+1. `smart_query()` or `hybrid_search_kb()` before any technical answer
+2. Source citation mandatory (`[PATH: kb/...]`)
+3. Strict order: KB → Files → External Docs → General Knowledge