@softspark/ai-toolkit 2.1.0 → 2.1.1

package/bin/ai-toolkit.js

@@ -203,11 +203,12 @@ function showHelp() {
   console.log('\nOptions for install / update:');
   console.log('  --only <list>   Apply only listed components (e.g. agents,hooks,cursor,windsurf,gemini)');
   console.log('  --skip <list>   Skip listed components');
-  console.log('  --local         Also set up project-local configs (CLAUDE.md, settings, constitution, copilot, cline, roo, aider, git hooks)');
+  console.log('  --local         Also set up project-local configs (CLAUDE.md, settings, constitution, language rules, git hooks)');
   console.log('  --profile <p>   Install profile: minimal (agents+skills), standard (default), strict (all+git hooks)');
+  console.log('  --persona <p>   Persona preset: backend-lead, frontend-lead, devops-eng, junior-dev');
   console.log('  --modules <list>  Install specific modules (e.g. core,agents,rules-typescript)');
   console.log('  --lang <list>   Explicitly select language rules (e.g. typescript, go,python)');
-  console.log('  --editors <list> Install editor configs: cursor,windsurf,cline,roo,aider,augment,copilot,antigravity (or "all")');
+  console.log('  --editors <list> Install editor configs: cursor,windsurf,cline,roo,aider,augment,copilot,antigravity,codex (or "all")');
   console.log('                  Default with --local: auto-detect from existing project files');
   console.log('  --auto-detect   Detect project languages and install matching rule modules');
   console.log('  --list, --dry-run  Dry-run: show what would be applied');
@@ -403,7 +404,9 @@ function handleConfig(args) {
  * @param {string[]} _args - Unused, kept for signature consistency
  */
 function handleGenerateAll(_args) {
-  for (const gen of Object.values(GENERATORS)) {
+  for (const [name, gen] of Object.entries(GENERATORS)) {
+    // Skip agents-md — codex-md generates a superset to the same AGENTS.md
+    if (name === 'agents-md') continue;
     writeGeneratorOutput(gen);
   }
   // Directory-based generators (multi-file output)
@@ -420,6 +423,14 @@ function handleGenerateAll(_args) {
   fs.writeFileSync(path.join(CWD, 'CONVENTIONS.md'), conventionsOut);
   console.log('Generated: CONVENTIONS.md');
   generateLlmsTxt();
+  // Re-inject registered custom rules into .claude/CLAUDE.md (idempotent markers)
+  const rulesDir = path.join(process.env.HOME, '.softspark', 'ai-toolkit', 'rules');
+  if (fs.existsSync(rulesDir)) {
+    const ruleFiles = fs.readdirSync(rulesDir).filter(f => f.endsWith('.md')).sort();
+    for (const rf of ruleFiles) {
+      run(scriptPath('inject_rule_cli.py'), [path.join(rulesDir, rf), CWD]);
+    }
+  }
 }
 
 /**

package/kb/reference/cli-reference.md

@@ -0,0 +1,135 @@
+---
+title: "CLI Reference"
+category: reference
+service: ai-toolkit
+tags: [cli, commands, reference, install, update, plugin, mcp]
+created: "2026-04-13"
+last_updated: "2026-04-13"
+description: "Complete CLI reference for all ai-toolkit commands, options, and flags."
+---
+
+# CLI Reference
+
+```
+Usage: ai-toolkit <command> [options]
+```
+
+## Core Commands
+
+| Command | Description |
+|---------|-------------|
+| `install` | First-time global install into `~/.claude/` + Cursor, Windsurf, Gemini |
+| `install --local` | Claude Code configs only; add `--editors all` or `--editors cursor,aider` for other tools |
+| `update` | Re-apply toolkit after `npm install -g @softspark/ai-toolkit@latest` |
+| `update --local` | Re-apply + auto-detect editors from existing project files |
+| `reset --local` | Wipe all project-local configs and recreate from scratch (clean slate) |
+| `status` | Show installed modules and version |
+| `uninstall` | Remove toolkit from `~/.claude/` |
+| `validate` | Verify toolkit integrity (`--strict` for CI-grade, warnings = errors) |
+| `doctor` | Diagnose install health, hooks, quick-win assets, and artifact drift |
+| `doctor --fix` | Auto-repair broken symlinks, missing hooks, stale artifacts |
+| `eject [dir]` | Export standalone config (no symlinks, no toolkit dependency) |
+
+## Rule & Hook Injection
+
+| Command | Description |
+|---------|-------------|
+| `add-rule <rule.md> [name]` | Register rule in `~/.softspark/ai-toolkit/rules/` — auto-applied on every `update` |
+| `remove-rule <name> [dir]` | Unregister rule and remove its block from `CLAUDE.md` |
+| `inject-hook <file.json>` | Inject external hooks into settings.json (idempotent, `_source` tagged) |
+| `remove-hook <name>` | Remove injected hooks by source name |
+
+## MCP Management
+
+| Command | Description |
+|---------|-------------|
+| `mcp list` | List available MCP server templates (25 templates) |
+| `mcp editors` | List editors with native MCP config adapters and scopes |
+| `mcp add <name> [names...]` | Add MCP server template(s) to `.mcp.json` |
+| `mcp install --editor <name[,..]> [names...]` | Install templates into native editor MCP config |
+| `mcp show <name>` | Show MCP template config details |
+| `mcp remove <name>` | Remove MCP server from `.mcp.json` or editor MCP config |
+
+## Plugin Management
+
+| Command | Description |
+|---------|-------------|
+| `plugin list` | Show available plugin packs with install status |
+| `plugin install <name> [--editor claude\|codex\|all]` | Install a plugin pack for selected runtime(s) |
+| `plugin install --all [--editor claude\|codex\|all]` | Install all 11 plugin packs |
+| `plugin update <name> [--editor claude\|codex\|all]` | Update a plugin pack (remove + reinstall, preserves data) |
+| `plugin update --all [--editor claude\|codex\|all]` | Update all installed plugin packs |
+| `plugin clean <name> [--days N]` | Prune old plugin data (default: 90 days) |
+| `plugin remove <name> [--editor claude\|codex\|all]` | Remove a plugin pack |
+| `plugin status [--editor claude\|codex\|all]` | Show installed plugins with runtime-specific details |
+
+## Config Inheritance
+
+| Command | Description |
+|---------|-------------|
+| `config validate [path]` | Validate `.softspark-toolkit.json` schema + extends + enforcement |
+| `config diff [path]` | Show project vs base config differences |
+| `config init [flags]` | Create `.softspark-toolkit.json` (`--extends`, `--profile`, `--no-extends`) |
+| `config create-base <name>` | Scaffold base config npm package |
+| `config check [path]` | CI enforcement gate (exit 0=pass, 1=fail, 2=no config; `--json`) |
+
+## Project Registry
+
+| Command | Description |
+|---------|-------------|
+| `projects` | List registered projects |
+| `projects --prune` | Remove stale (deleted) entries |
+| `projects remove /path` | Unregister specific project |
+
+## Generator Commands
+
+| Command | Description |
+|---------|-------------|
+| `generate-all` | Generate all platform configs at once |
+| `agents-md` | Regenerate `AGENTS.md` from agent definitions |
+| `codex-md` | Generate `AGENTS.md` with marker injection for Codex CLI |
+| `codex-rules` | Generate `.agents/rules/*.md` for Codex CLI |
+| `codex-hooks` | Generate `.codex/hooks.json` for Codex CLI |
+| `cursor-rules` | Generate `.cursorrules` (legacy single file) |
+| `cursor-mdc` | Generate `.cursor/rules/*.mdc` (recommended) |
+| `windsurf-rules` | Generate `.windsurfrules` (legacy) |
+| `windsurf-dir-rules` | Generate `.windsurf/rules/*.md` (recommended) |
+| `copilot-instructions` | Generate `.github/copilot-instructions.md` |
+| `gemini-md` | Generate `GEMINI.md` for Gemini CLI |
+| `cline-rules` | Generate `.clinerules` (legacy) |
+| `cline-dir-rules` | Generate `.clinerules/*.md` (recommended) |
+| `roo-modes` | Generate `.roomodes` |
+| `roo-dir-rules` | Generate `.roo/rules/*.md` |
+| `aider-conf` | Generate `.aider.conf.yml` |
+| `conventions-md` | Generate `CONVENTIONS.md` for Aider |
+| `augment-rules` | Generate `.augment/rules/ai-toolkit.md` (legacy) |
+| `augment-dir-rules` | Generate `.augment/rules/ai-toolkit-*.md` (recommended) |
+| `antigravity-rules` | Generate `.agent/rules/` and `.agent/workflows/` |
+| `llms-txt` | Generate `llms.txt` and `llms-full.txt` |
+
+## Other Commands
+
+| Command | Description |
+|---------|-------------|
+| `stats` | Show skill usage statistics (`--reset` to clear, `--json` for raw output) |
+| `benchmark --my-config` | Compare your config vs defaults vs ecosystem |
+| `benchmark-ecosystem` | Generate ecosystem benchmark snapshot |
+| `create skill <name>` | Scaffold new skill from template (`--template=linter\|reviewer\|generator\|workflow\|knowledge`) |
+| `sync` | Config portability via GitHub Gist (`--export`, `--push`, `--pull`, `--import`) |
+| `compile-slm` | Compile toolkit into minimal SLM system prompt (`--budget`, `--model-size`, `--dry-run`) |
+| `evaluate` | Run skill evaluation suite |
+
+## Install / Update Options
+
+```bash
+ai-toolkit install --only agents,hooks          # apply only listed components
+ai-toolkit install --skip hooks                 # skip listed components
+ai-toolkit install --profile minimal            # minimal | standard | strict
+ai-toolkit install --persona backend-lead       # backend-lead | frontend-lead | devops-eng | junior-dev
+ai-toolkit install --local --editors all        # Claude Code + all editors
+ai-toolkit install --local --editors cursor,aider  # + specific editors
+ai-toolkit install --local --lang typescript    # explicit language rules
+ai-toolkit install --modules core,agents,rules-typescript  # selective modules
+ai-toolkit install --list                       # dry-run: show what would change
+ai-toolkit update --local                       # auto-detects editors from existing files
+```

package/kb/reference/comparison.md

@@ -0,0 +1,29 @@
+---
+title: "Ecosystem Comparison"
+category: reference
+service: ai-toolkit
+tags: [comparison, ecosystem, features, alternatives]
+created: "2026-04-13"
+last_updated: "2026-04-13"
+description: "Feature comparison of ai-toolkit vs other Claude Code toolkits and agent frameworks."
+---
+
+# Ecosystem Comparison
+
+| Feature | ai-toolkit | everything-claude-code | wshobson/agents | ruflo |
+|---------|---------------|----------------------|-----------------|-------|
+| Skills | 92 | 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 |
+| Effort-based model budgeting | **Yes** | No | No | No |
+| Test suite | Yes (bats) | Yes (997 tests) | No | Yes |
+| npm/npx install | Yes | Yes | Yes | Yes |
+| Cross-tool support | **Cursor, Windsurf, Copilot, Gemini, Cline, Roo, Aider, Augment, Antigravity, Codex** | 5+ tools | Smithery | Limited |
+| Selective install | Yes | Yes | Yes (72 plugins) | No |
+| Session persistence | Yes | Yes | No | No |
+| Architecture notes | **Yes** | No | No | No |
+| KB/RAG integration | **Yes** | No | No | Yes |
+| License | MIT | MIT | MIT | MIT |
+
+For live benchmark data, see the [ecosystem benchmark snapshot](claude-ecosystem-benchmark-snapshot.md).

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