ai-toolkit

Professional-grade AI coding toolkit with multi-platform support. Machine-enforced safety, 107 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.

What's New in v4.8.0

v4.8.0 migrates the deprecated Windsurf Cascade hooks onto the Devin CLI surface before Cascade sunsets on 2026-07-01.

• Devin CLI hooks: new generate_devin_hooks.py emits .devin/hooks.v1.json in the Claude-compatible format Devin CLI uses — Claude-style events (PreToolUse/PostToolUse/UserPromptSubmit/Stop/SessionStart) with matchers on Devin tool names (read/edit/exec/mcp__*), reusing the existing toolkit hook scripts.
• Cascade deprecation: .windsurf/hooks.json is Cascade-scoped and dies 2026-07-01 with no Devin fallback; both generators run during the transition, the Cascade one drops in the first release after the sunset.
• Global hooks reach Devin for free: Devin CLI reads ~/.claude/settings.json hooks directly, so a global ai-toolkit install already covers Devin even without the project-local file.
• No normalizer change needed: _hook-io.sh already parses Devin's flat hook_event_name/tool_name/tool_input payload.

See CHANGELOG.md for full history.

Table of Contents

• Install
• Platform Support
• What You Get
• Architecture
• Key Features
• Key Slash Commands
• Getting Started
• Documentation
• Contributing
• Security
• License
• Changelog

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 107 skills, 44 agents, quality hooks, and the safety constitution automatically.

Windows: WSL is the recommended runtime. Native Windows works when Git Bash is available for hook scripts; dependency hints cover winget, Chocolatey, and Scoop. See Windows Support.

Update

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

Per-Project Setup

cd your-project/
ai-toolkit install --local                        # Claude Code only
ai-toolkit install --local --editors all          # + all editors
ai-toolkit install --local --editors cursor,aider # + specific editors
ai-toolkit update --local                         # auto-detects editors

Plugin Management

ai-toolkit plugin list                            # show available packs
ai-toolkit plugin install --editor all --all      # install all for Claude + Codex
ai-toolkit plugin status --editor all             # show what's installed

Install Profiles

ai-toolkit install --profile minimal    # agents + skills only
ai-toolkit install --profile standard   # full install (default)
ai-toolkit install --profile strict     # full + git hooks

Verify & Repair

ai-toolkit validate          # check integrity
ai-toolkit doctor --fix      # auto-repair

See CLI Reference for all commands and options.

Platform Support

| Platform | Config Files | Hooks | Scope | |----------|-------------|:-----:|-------| | Claude Code | ~/.claude/ | ✅ | global | | Cursor | .cursor/rules/*.mdc + .cursor/mcp.json + .cursor/skills/* | ✅ | project (~/.cursor/mcp.json for MCP only) | | Windsurf (Devin Desktop) | ~/.codeium/.../global_rules.md + ~/.codeium/windsurf/skills/* + .devin/rules/*.md + .windsurf/rules/*.md (legacy) | ✅ | global + project | | Gemini CLI | ~/.gemini/GEMINI.md | ✅ | global | | GitHub Copilot | .github/copilot-instructions.md | — | project | | Cline | ~/Documents/Cline/Rules/*.md + ~/.cline/skills/* + .clinerules/*.md | — | global + project | | Roo Code | ~/.roo/rules/*.md + .roomodes + .roo/rules/*.md | — | global rules + project | | Aider | ~/.aider.conf.yml + .aider.conf.yml + CONVENTIONS.md | — | global + project | | Augment | ~/.augment/rules/*.md + .augment/rules/ai-toolkit-*.md | ✅ | global + project | | Google Antigravity | .agents/rules/*.md + .agents/workflows/*.md + skill pointer in .agent/skills/* (IDE) and .agents/skills/* (CLI) | — | project | | Codex CLI | AGENTS.md (coding rules inlined) + .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. Every platform receives the agent/skill catalog, guidelines, and registered custom rules as text. The Hooks column marks platforms that also get lifecycle hook enforcement — the machine-enforced constitution (guard-destructive, quality gates, search-first discipline). Platforms marked — receive those rules as guidance only, without blocking hooks.

What You Get

| Component | Count | Description | |-----------|-------|-------------| | skills/ (task) | 32 | Slash commands: /commit, /build, /deploy, /test, /mcp-builder, ... | | skills/ (hybrid) | 30 | Slash commands with agent knowledge base | | skills/ (knowledge) | 45 | Domain knowledge auto-loaded by agents (includes 13 <lang>-rules skills) | | agents/ | 44 | Specialized agents across 10 categories | | hooks/ | 29 entries / 14 events | Quality gates, path safety, prompt governance, loop guard, session lifecycle | | plugins/ | 11 packs | Opt-in domain bundles (security, research, frontend, enterprise, 6 language packs) | | constitution.md | 6 articles | Machine-enforced safety rules | | rules/ | auto-injected | Language-specific and custom rules injected into your configs | | kb/ | reference docs | Architecture, procedures, and best practices |

Architecture

ai-toolkit/
├── app/
│   ├── agents/          # 44 agent definitions
│   ├── skills/          # 107 skills (task / hybrid / knowledge)
│   ├── rules/           # Auto-injected into your CLAUDE.md
│   ├── hooks/           # Hook scripts (29 entries, 14 lifecycle events)
│   ├── plugins/         # 11 experimental plugin packs (opt-in)
│   ├── output-styles/   # System prompt output style overrides
│   ├── constitution.md  # 6 immutable safety articles
│   └── ARCHITECTURE.md  # Full system design
├── kb/                  # Reference docs, procedures, plans
├── scripts/             # Validation, install, evaluation scripts
├── tests/               # Bats test suite (1196 tests)
└── CHANGELOG.md

Distribution: Symlink-based for agents/skills, copy-based for hooks. Run ai-toolkit update after npm install — all projects pick up changes instantly. See Distribution Model.

Key Features

Machine-enforced constitution — 6-article safety constitution enforced via PreToolUse hooks that actually block rm -rf, DROP TABLE, and irreversible operations. Not just documentation.

29 lifecycle hooks — Executable scripts across 14 events (SessionStart → SessionEnd, plus InstructionsLoaded + ConfigChange). Guards, governance, quality gates, session persistence, MCP health checks, revert protection, test-cohesion enforcement, loop guard, search-first discipline. See Hooks Catalog.

Security scanning — /skill-audit for code-level risks, /cve-scan for dependency CVEs. Both CI-ready with exit codes.

Iron Law enforcement — /tdd, debugging-tactics, and verification-before-completion enforce non-negotiable gates with anti-rationalization tables. 15 skills total include rationalization resistance.

Multi-language quality gates — Stop hook runs lint + type checks across Python, TypeScript, PHP, Dart, Go after every response.

Agent verification checklists — 10 agents include exit criteria that must be met before presenting results.

Two-stage review — /subagent-development runs Implementer → Spec Review → Quality Review per task.

Persistent memory — memory-pack plugin: SQLite + FTS5 search across past sessions.

Local product telemetry — ai-toolkit stats --summary reports total invocations, skill coverage, unused catalog skills, recent activity, and top skills from local usage data.

Persona presets — 4 roles (backend-lead, frontend-lead, devops-eng, junior-dev) adjust style and priorities.

Config inheritance — Enterprise extends system with constitution immutability and enforcement constraints. See Enterprise Config Guide.

70 language rules — 13 languages + common, 5 categories each. Auto-detected or explicit --lang. See Language Rules.

26 MCP templates — Ready-to-use configs for GitHub, PostgreSQL, Slack, Jira, Sentry, and more. See MCP Templates.

See Unique Features for detailed descriptions of all differentiators.

Key Slash Commands

| Command | Purpose | Effort | |---------|---------|--------| | /workflow <type> | Pre-defined multi-agent workflow (15 types) | max | | /orchestrate | Custom multi-agent coordination (3–6 agents) | max | | /swarm | Parallel Agent Teams: map-reduce, consensus, relay | max | | /plan | Implementation plan with task breakdown | high | | /review | Code review: quality, security, performance | high | | /debug | Systematic debugging with diagnostics | medium | | /refactor | Safe refactoring with pattern analysis | high | | /tdd | Test-driven development with red-green-refactor | high | | /commit | Structured commit with linting | medium | | /pr | Pull request with generated checklist | medium | | /docs | Generate README, API docs, architecture notes | high | | /explore | Interactive codebase visualization | medium | | /write-a-prd | Create PRD through interactive interview | high | | /prd-to-plan | Convert PRD into vertical-slice implementation plan | high | | /design-an-interface | Generate 3+ radically different interface designs | high | | /grill-me | Stress-test a plan through Socratic questioning | medium | | /triage-issue | Triage bug with deep investigation and TDD fix plan | high | | /architecture-audit | Discover shallow modules, propose refactors | high | | /council | 4-perspective decision evaluation | high | | /cve-scan | Scan dependencies for known CVEs | medium | | /skill-audit | Scan skills/agents for security risks | medium | | /repeat | Autonomous loop with safety controls | medium | | /persona | Switch engineering persona at runtime | low |

/workflow Types

feature-development    backend-feature       frontend-feature
api-design             database-evolution    test-coverage
security-audit         codebase-onboarding   spike
debugging              incident-response     performance-optimization
infrastructure-change  application-deploy    proactive-troubleshooting

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

Getting Started

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

2. Start using skills:

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

3. Verify your install:

   ai-toolkit validate

Documentation

| Topic | Link | |-------|------| | CLI Reference | kb/reference/cli-reference.md | | Unique Features | kb/reference/unique-features.md | | Architecture Overview | kb/reference/architecture-overview.md | | Hooks Catalog | kb/reference/hooks-catalog.md | | Language Rules | kb/reference/language-rules.md | | MCP Templates | kb/reference/mcp-templates.md | | Extension API | kb/reference/extension-api.md | | Manifest Install | kb/reference/manifest-install.md | | Plugin Packs | kb/reference/plugin-pack-conventions.md | | Enterprise Config | kb/reference/enterprise-config-guide.md | | Distribution Model | kb/reference/distribution-model.md | | Ecosystem Comparison | kb/reference/comparison.md | | Codex CLI Compatibility | kb/reference/codex-cli-compatibility.md | | opencode Compatibility | kb/reference/opencode-compatibility.md | | Maintenance SOP | kb/procedures/maintenance-sop.md |

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.