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, and Google Antigravity, ready in 60 seconds.

Install

# Option A: install globally (once per machine)
npm install -g @softspark/ai-toolkit
ai-toolkit install

# Option B: try without installing (npx)
npx @softspark/ai-toolkit install

That's it. Claude Code picks up 92 skills, 44 agents, quality hooks, and the safety constitution automatically.

Update

npm install -g @softspark/ai-toolkit@latest && ai-toolkit update

Per-Project Setup

After global install, run --local in each project. By default, only Claude Code configs are installed (CLAUDE.md, settings, constitution, language rules). Add --editors for other tools:

cd your-project/
ai-toolkit install --local                     # Claude Code only
ai-toolkit install --local --editors all       # + all editors (Cursor, Windsurf, Cline, Roo, Aider, Augment, Copilot, Antigravity)
ai-toolkit install --local --editors cursor,aider  # + specific editors
ai-toolkit update --local                      # auto-detects editors from existing project files

Plugin Management

ai-toolkit plugin list             # show available packs
ai-toolkit plugin install --all    # install all packs
ai-toolkit plugin update --all     # re-apply after toolkit updates
ai-toolkit plugin status           # show what's installed
ai-toolkit plugin clean memory-pack --days 30  # prune old data

After each ai-toolkit update, also run ai-toolkit plugin update --all to keep plugin hooks and scripts in sync.

Install Profiles

ai-toolkit install --profile minimal    # agents + skills only (no hooks, no constitution)
ai-toolkit install --profile standard   # full install (default)
ai-toolkit install --profile strict     # full install + git hooks even without --local

Persona Presets

Personas adjust communication style, preferred skills, and code review priorities per engineering role.

Install-time (persistent — injected into CLAUDE.md):

ai-toolkit install --persona backend-lead    # system design, API stability, data integrity
ai-toolkit install --persona frontend-lead   # component architecture, a11y, Core Web Vitals
ai-toolkit install --persona devops-eng      # infra-as-code, CI/CD, rollback safety
ai-toolkit install --persona junior-dev      # step-by-step explanations, learning focus

Runtime (session-scoped — no reinstall needed):

/persona backend-lead     # activate for this session
/persona --list           # show available personas
/persona --clear          # reset to default

Selective Install / Update

ai-toolkit install --only agents,hooks   # first-time: only listed components
ai-toolkit install --skip hooks          # first-time: skip listed components
ai-toolkit update --only agents,hooks    # re-apply: only listed components
ai-toolkit update --skip cursor          # re-apply: skip listed components
ai-toolkit install --list                # dry-run: show what would be applied

Verify & Repair

ai-toolkit validate           # check toolkit integrity
ai-toolkit validate --strict  # CI-grade: warnings = errors
ai-toolkit doctor             # diagnose install health, hooks, and artifact drift
ai-toolkit doctor --fix  # auto-repair: broken symlinks, missing hooks, stale artifacts

Eject (standalone, no toolkit dependency)

ai-toolkit eject              # export to current directory
ai-toolkit eject /path/to    # export to custom directory

Replaces all symlinks with real files, inlines rules into CLAUDE.md, copies constitution and architecture. After eject you can npm uninstall -g @softspark/ai-toolkit.

Compile for Local Models (Ollama, LM Studio, Aider)

ai-toolkit compile-slm                              # auto-detect model, default budget
ai-toolkit compile-slm --model-size 8b              # 2K token budget for 8B models
ai-toolkit compile-slm --model-size 32b --lang python  # 8K budget + Python rules
ai-toolkit compile-slm --persona backend-lead       # boost backend-relevant skills
ai-toolkit compile-slm --format ollama              # Ollama Modelfile SYSTEM block
ai-toolkit compile-slm --dry-run                    # preview what gets included

Compiles the full toolkit (20K+ tokens) into a minimal system prompt that fits SLM context windows. Preserves safety constitution, compresses skills, and packs by value density. Supports 4 output formats: raw, ollama, json-string, aider.

Platform Support

Note: Claude Code is always installed (primary platform with full feature support). Other editors are installed on demand with --editors <list> or auto-detected from existing project files. All platforms receive the same agent/skill catalog, guidelines, rules, language-specific rules, and registered custom rules. For editors lacking native bash lifecycle hooks, --local installs a Git hooks fallback (.git/hooks/pre-commit) to enforce quality gates pre-commit.

What You Get

Architecture

ai-toolkit/
├── app/
│   ├── agents/          # 44 agent definitions
│   │   ├── orchestrator.md
│   │   ├── backend-specialist.md
│   │   ├── security-architect.md
│   │   └── ... (41 more)
│   ├── skills/          # 92 skills (task / hybrid / knowledge)
│   │   ├── commit/      # /commit slash command
│   │   ├── review/      # /review slash command
│   │   ├── clean-code/  # knowledge skill (auto-loaded)
│   │   └── ... (87 more)
│   ├── rules/           # Auto-injected into your CLAUDE.md
│   ├── hooks/           # Hook scripts (copied to ~/.softspark/ai-toolkit/hooks/)
│   │   ├── session-start.sh      # MANDATORY reminder + session context
│   │   ├── guard-destructive.sh  # Block rm -rf, DROP TABLE, etc.
│   │   ├── guard-path.sh         # Block wrong-user path hallucination
│   │   ├── guard-config.sh       # Block edits to linter/formatter configs
│   │   ├── user-prompt-submit.sh # Prompt governance reminder
│   │   ├── quality-check.sh      # Multi-language lint on stop
│   │   ├── quality-gate.sh       # Block task completion on errors
│   │   ├── save-session.sh       # Persist session context
│   │   ├── subagent-start.sh     # Subagent scope reminder
│   │   ├── subagent-stop.sh      # Subagent completion checklist
│   │   ├── pre-compact.sh        # Save context before compaction
│   │   ├── pre-compact-save.sh   # Timestamped backup before compaction
│   │   ├── session-end.sh        # Session handoff snapshot
│   │   ├── post-tool-use.sh      # Lightweight feedback after edits
│   │   ├── mcp-health.sh         # MCP server availability check
│   │   ├── governance-capture.sh # Security-sensitive op logging
│   │   ├── commit-quality.sh     # Conventional commit advisory
│   │   ├── session-context.sh    # Environment snapshot on start
│   │   ├── track-usage.sh        # Skill invocation tracking
│   │   └── notify-waiting.sh     # Cross-platform "Claude waiting" notification
│   ├── hooks.json       # Hook definitions (merged into settings.json)
│   ├── plugins/         # Experimental plugin packs (opt-in, not part of default install)
│   ├── output-styles/   # System prompt output style overrides
│   ├── constitution.md  # 5 immutable safety articles
│   └── ARCHITECTURE.md  # Full system design
├── kb/                  # Reference docs, architecture notes, procedures, plans
├── scripts/             # Validation, install, evaluation scripts
├── tests/               # Bats test suite
└── CHANGELOG.md

Distribution model: Symlink-based for agents/skills, copy-based for hooks. ~/.claude/agents/ and ~/.claude/skills/ contain per-file symlinks into the npm package. Hook scripts are copied to ~/.softspark/ai-toolkit/hooks/ and referenced from ~/.claude/settings.json. Run ai-toolkit update after npm install — all projects pick up changes instantly. (See Distribution Model)

Key Slash Commands

/workflow Types

/workflow feature-development    # New feature, full stack
/workflow backend-feature        # API + logic + tests
/workflow frontend-feature       # UI component + state + tests
/workflow api-design             # Design → implement → document
/workflow database-evolution     # Schema change + migration + code
/workflow test-coverage          # Boost coverage for a module
/workflow security-audit         # Multi-vector security assessment
/workflow codebase-onboarding    # Understand unfamiliar codebase
/workflow spike                  # Time-boxed research → architecture note
/workflow debugging              # Bug spanning multiple layers
/workflow incident-response      # Production down
/workflow performance-optimization  # Degradation >50%
/workflow infrastructure-change  # Docker, CI/CD, infra
/workflow application-deploy     # Full deploy workflow
/workflow proactive-troubleshooting  # Warning / trend analysis

Multi-Agent Skill Selection

Need multi-agent coordination?
├── Know your domains? → /orchestrate (ad-hoc, 3-6 agents)
├── Have a known pattern? → /workflow <type> (15 templates)
├── Need consensus/map-reduce? → /swarm <mode>
├── Want Agent Teams API? → /teams (experimental)
└── Executing a plan? → /subagent-development

Unique 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:

5 skill-scoped hooks:

3. Security Scanning

Two complementary security tools:

/skill-audit — scan skills and agents for code-level risks:

/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:

/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:

6. Iron Law Enforcement

Three skills enforce non-negotiable quality gates with anti-rationalization tables:

Additionally, 15 core skills include ## Common Rationalizations tables — domain-specific excuses with rebuttals that prevent agent drift and shortcut-taking. Skills with rationalization tables: /review, /debug, /refactor, /tdd, /plan, /docs, /analyze, security-patterns, testing-patterns, api-patterns, ci-cd-patterns, clean-code, performance-profiling, git-mastery, database-patterns.

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.

Agent Verification Checklists

10 key agents include ## Verification Checklist — exit criteria that MUST be met before presenting results. Each checklist is domain-specific:

Skill Reference Routing

7 core skills include ## Related Skills sections that suggest logical follow-up skills, improving discoverability:

/review → found issues? → /debug, /tdd, /cve-scan, /analyze
/debug  → bug fixed?   → /review, /tdd, /workflow incident-response
/plan   → approved?    → /orchestrate, /write-a-prd, /grill-me

Intent Capture Interview (/onboard)

The /onboard skill now includes a Step 0 interview phase before setup — asking 5 targeted questions to capture undocumented project intent (common contributor mistakes, protected files, deployment model, non-obvious constraints, review culture). Answers customize the generated CLAUDE.md.

7. Two-Stage Review (/subagent-development)

Per-task review pipeline inspired by obra/superpowers:

Implementer → Spec Compliance Review → Code Quality Review → Next Task

• Implementer reports status: DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED
• Spec reviewer verifies: all requirements met, nothing extra, nothing missing
• Quality reviewer checks: SOLID, naming, error handling, tests, security
• Prompt templates included: reference/implementer-prompt.md, spec-reviewer-prompt.md, code-quality-reviewer-prompt.md

8. Ralph Wiggum Loop (/repeat)

Autonomous agent loop with safety controls:

/repeat 5m /test          # run tests every 5 min until all pass
/repeat --iterations 3 /review   # max 3 review passes

Constitution Article I, Section 4 enforces these limits.

9. 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
• Consent-based: offered once as its own message, never forced

10. Persistent Memory (memory-pack plugin)

SQLite-based session memory (opt-in plugin pack):

11. Persona Presets

4 engineering personas that adjust Claude's communication style per role:

Persistent via --persona at install time, or session-scoped via /persona runtime command.

12. 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

MCP Templates

25 ready-to-use MCP server configuration templates. Install any with a single command:

ai-toolkit mcp add github slack           # add GitHub + Slack MCP servers
ai-toolkit mcp list                       # browse all 25 templates
ai-toolkit mcp show postgres              # inspect config before adding

Templates include: GitHub, PostgreSQL, Slack, Sentry, Context7, Brave Search, Supabase, Cloudflare, Vercel, and 16 more. Each is a validated JSON config fragment merged into .mcp.json.

Language Rules

68 language-specific coding rules across 13 languages: TypeScript, Python, Go, Rust, Java, Kotlin, Swift, Dart, C#, PHP, C++, Ruby, plus common rules. Each language has 5 rule categories: coding-style, testing, patterns, frameworks, security.

ai-toolkit install --local                   # auto-detects project language, installs matching rules
ai-toolkit install --local --lang typescript  # explicit language selection
ai-toolkit install --local --lang go,python   # multiple languages

--local automatically detects languages using two-phase detection: config markers (package.json, go.mod, Cargo.toml, etc.) plus source file extension scanning (.py, .ts, .go, etc.). --lang accepts aliases (go, c++, cs). Rules are injected into CLAUDE.md and auto-updated on ai-toolkit update --local.

When --editors is used alongside detected or explicit languages, language rules are propagated to all configured editors — not just Claude. Each editor receives the full rule content in its native format:

Registered rules (ai-toolkit add-rule) are also propagated to directory-based editor configs as ai-toolkit-custom-<name> files.

Extension API

Generic API for external tools to inject rules and hooks into the toolkit:

# Rules — injected into CLAUDE.md with HTML markers
ai-toolkit inject-rule ./jira-rules.md    # idempotent, source-tagged block
ai-toolkit remove-rule jira-rules

# Hooks — injected into settings.json with _source tags
ai-toolkit inject-hook ./my-hooks.json    # idempotent, _source tagged
ai-toolkit remove-hook my-hooks

Injection is idempotent — re-running updates only the marked block, never touching content outside it. See kb/reference/extension-api.md.

Manifest Install

Module-level install granularity. Install only what you need:

ai-toolkit install --modules core,agents,rules-typescript
ai-toolkit install --local                # auto-detects language, installs matching rules
ai-toolkit status                         # show installed modules and versions
ai-toolkit update                         # incremental re-install (only changed modules)

Install state is tracked in ~/.softspark/ai-toolkit/state.json. See kb/reference/manifest-install.md.

Plugin Packs (Opt-in)

11 experimental plugin packs — domain bundles not part of the default install. Each pack bundles agents, skills, hooks, and/or rules for a specific domain.

All packs have status: experimental. Each has a plugin.json manifest and README.md with installation instructions.

Config Inheritance (extends)

Enterprise-grade configuration inheritance for multi-repo AI governance. Organizations define a shared base config published as an npm package, Git URL, or local path. Projects inherit via .softspark-toolkit.json:

{
  "extends": "@mycompany/ai-toolkit-config",
  "profile": "standard"
}

Key capabilities:

• Layered merge — base config + project overrides, with deep merge for dicts, union for lists, project-wins for scalars
• Constitution immutability — Articles I-V and base articles cannot be modified; projects can only ADD new articles (6+)
• Enforce constraints — requiredAgents, forbidOverride, minHookProfile, requiredPlugins
• Override validation — requires explicit override: true + justification (min 20 chars)
• Lock file — .softspark-toolkit.lock.json pins resolved versions for reproducible installs
• Offline fallback — uses cached configs from ~/.softspark/ai-toolkit/config-cache/ when registry unavailable

ai-toolkit config create-base @mycompany/ai-toolkit-config  # scaffold base package
ai-toolkit config init --extends @mycompany/ai-toolkit-config # setup project
ai-toolkit config validate    # schema + extends + enforcement
ai-toolkit config diff        # project vs base differences
ai-toolkit config check       # CI enforcement gate (exit 0/1/2, --json)

See Enterprise Config Guide for full documentation.

Project Registry

All projects installed with --local are automatically registered in ~/.softspark/ai-toolkit/projects.json. Running ai-toolkit update propagates updates to all registered projects in parallel.

ai-toolkit projects              # list registered projects
ai-toolkit projects --prune      # remove stale (deleted) entries
ai-toolkit projects remove /path # unregister specific project
ai-toolkit update                # global update + parallel update ALL projects

Comparison

Agent Teams

Native support for CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 — automatically enabled during ai-toolkit install / update via env in ~/.claude/settings.json.

Pre-configured team presets via /teams:

Cross-Tool Support

# First-time install (Claude + Cursor + Windsurf + Gemini)
ai-toolkit install

# After npm update — re-apply updated components
ai-toolkit update

# Init project (Claude Code configs only: CLAUDE.md, settings, constitution, language rules)
ai-toolkit install --local

# Init with all editors (Cursor, Windsurf, Cline, Roo, Aider, Augment, Copilot, Antigravity)
ai-toolkit install --local --editors all

# Update project — auto-detects editors from existing config files
ai-toolkit update --local

install --local prepares project files only. Hooks stay global and remain merged into ~/.claude/settings.json. Git hooks are added as a safety fallback for editors without native hooks.

Session Persistence

Context survives across Claude Code sessions:

# Enabled by default after install
# Saved to: .claude/session-context.md
# Loaded on: SessionStart hook

Hook Runtime Profiles

# In .claude/settings.local.json
{
  "env": {
    "TOOLKIT_HOOK_PROFILE": "minimal"  # minimal | standard | strict
  }
}

Post-Install Setup

1. Customize CLAUDE.md — add your project's tech stack, commands, and conventions at the top (above the toolkit markers).

2. Configure settings:

   # .claude/settings.local.json
   {
     "mcpServers": { ... },
     "env": { "TOOLKIT_HOOK_PROFILE": "standard" }
   }

3. Verify:

   ai-toolkit validate

4. Start:

   /onboard     # guided setup
   /explore     # understand your codebase
   /plan        # plan a feature

CLI Reference

Usage: ai-toolkit <command> [options]

Options for install and update:

ai-toolkit install --only agents,hooks   # apply only listed components
ai-toolkit install --skip hooks          # skip listed components
ai-toolkit install --profile minimal     # profile preset: minimal | standard | strict
ai-toolkit install --persona backend-lead # persona preset: backend-lead | frontend-lead | devops-eng | junior-dev
ai-toolkit install --local               # Claude Code only (CLAUDE.md, settings, constitution, language rules)
ai-toolkit install --local --editors all # Claude Code + all editors (Cursor, Windsurf, Cline, Roo, Aider, Augment, Copilot, Antigravity)
ai-toolkit install --local --editors cursor,aider  # Claude Code + specific editors
ai-toolkit update --local                # re-apply; auto-detects editors from existing project files
ai-toolkit install --list                # dry-run: show what would be applied
ai-toolkit install --modules core,agents,rules-typescript  # selective module install
ai-toolkit install --lang typescript     # explicit language for rules install

Injecting Rules from Another Repo

Any repo can register its rules so they are automatically injected into all AI tool configs on every update:

cd /path/to/your-repo
ai-toolkit add-rule ./jira-rules.md
# Registered: 'jira-rules' → ~/.softspark/ai-toolkit/rules/jira-rules.md

ai-toolkit update
# → injects jira-rules into ~/.claude/CLAUDE.md, ~/.cursor/rules, Windsurf, Gemini

Rules are stored in ~/.softspark/ai-toolkit/rules/ and re-applied on every update. Injection is idempotent — re-running updates only the marked block, never touching content outside it.

To unregister:

ai-toolkit remove-rule jira-rules
# Removes from ~/.softspark/ai-toolkit/rules/ and strips the block from ~/.claude/CLAUDE.md

See kb/reference/integrations.md for known integrations.

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md for responsible disclosure policy.

License

MIT -- see LICENSE.

Changelog

See CHANGELOG.md.

Extracted from production use at SoftSpark. Built to be the toolkit we wished existed.