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.

What's New in v2.1.1

• Custom rules in generators — generate:all now preserves registered rules from other repos across all platforms
• README restructured — 951 → 292 lines with TOC, "What's New" section, and links to KB docs
• CLI help completeness — added missing --persona option and codex to --editors
• 3 new KB docs — CLI Reference, Unique Features, Ecosystem Comparison (moved from README)

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

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

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

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.

What You Get

Architecture

ai-toolkit/
├── app/
│   ├── agents/          # 44 agent definitions
│   ├── skills/          # 92 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)
│   ├── output-styles/   # System prompt output style overrides
│   ├── constitution.md  # 5 immutable safety articles
│   └── ARCHITECTURE.md  # Full system design
├── kb/                  # Reference docs, procedures, plans
├── scripts/             # Validation, install, evaluation scripts
├── tests/               # Bats test suite (598 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 — 5-article safety constitution enforced via PreToolUse hooks that actually block rm -rf, DROP TABLE, and irreversible operations. Not just documentation.

21 lifecycle hooks — Executable scripts across 12 events (SessionStart → SessionEnd). Guards, governance, quality gates, session persistence, MCP health checks. 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.

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.

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

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

See Unique Features for detailed descriptions of all differentiators.

Key Slash Commands

/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

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.