ai-toolkit

Professional-grade AI coding toolkit with multi-platform support. Machine-enforced safety, 109 skills, 44 agents, expanded lifecycle hooks, persona presets, experimental opt-in plugin packs, and benchmark tooling — works with Claude Code, Claude Chat/Cowork, Cursor, Devin, Copilot, Gemini, Cline, Roo/Zoo Code, Aider, Augment, Google Antigravity, Codex CLI, and opencode.

What’s New in v4.24.1

v4.24.1 — plugin install accepted a dead symlink as proof of installation. The guard asked exists() or is_symlink(), and a link with no target still answers yes to the second half, so the installer logged OK and repaired nothing — precisely the state a toolkit upgrade leaves, since replacing app/ breaks every link into it. Dangling links are now dropped and relinked; real files and live links stay untouched. Pairs with v4.24.0’s user-level pack root, which is what stops the breakage happening in the first place.

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 109 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 Code + Codex
ai-toolkit plugin status --editor all             # show what's installed

Claude Chat / Desktop / Cowork

The Claude app does not read Claude Code’s ~/.claude/rules/ or CLAUDE.md. Export and upload the app-native plugin instead:

ai-toolkit claude-app export --verify
# Claude > Customize > Plugins > + > Upload plugin
# Paste the generated *-global-instructions.md into:
# Settings > Cowork > Global instructions

Re-export and re-upload after toolkit or registered-rule updates. Skills work in Chat and Cowork; hooks and sub-agents are active only in Cowork.

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 are selected with --editors; the Claude app uses the separate claude-app export flow because its customization store is UI/plugin-managed. The Hooks column marks platforms with lifecycle enforcement. Platforms marked — receive guidance without blocking hooks.

---

What You Get

---

Architecture

ai-toolkit/
├── app/
│   ├── agents/          # 44 agent definitions
│   ├── skills/          # 109 skills (task / hybrid / knowledge)
│   ├── rules/           # Source rules synced into Claude/editor rule files
│   ├── hooks/           # Hook scripts (29 entries, 14 lifecycle events)
│   ├── claude-app/      # Generated Chat/Cowork plugin rules, hooks, instructions
│   ├── plugins/         # 2 experimental plugin packs (opt-in)
│   ├── output-styles/   # System prompt output style overrides
│   ├── constitution.md  # 7 immutable safety articles
│   └── ARCHITECTURE.md  # Full system design
├── kb/                  # Reference docs, procedures, plans
├── scripts/             # Validation, install, evaluation scripts
├── tests/               # Bats and Python test suite (1494 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 — 7-article safety constitution enforced via PreToolUse hooks that actually block rm -rf, DROP TABLE, and irreversible operations. Not just documentation.

28 lifecycle hook entries: Executable handlers across 14 events (SessionStart → SessionEnd, plus InstructionsLoaded + ConfigChange). Guards, governance, quality gates, session persistence, MCP health checks, revert protection, test-cohesion enforcement, loop guard, and 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

/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  (15 templates)
├── Need consensus/map-reduce? → /swarm 
├── 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

Apache License 2.0 — see LICENSE and NOTICE.

Fork it, modify it, ship it commercially. Three things the licence asks in return:

• Keep the attribution. Redistributions must carry the contents of NOTICE (§4d) — that is where the project name, copyright and source URL live.
• Say what you changed. Modified files must carry a prominent notice stating that you changed them (§4b).
• Names are not included. The licence grants no rights to the “ai-toolkit” or “SoftSpark” names or marks (§6).

Releases up to and including v4.20.0 were published under MIT and stay available under MIT; the change applies going forward and revokes nothing already granted. Contributions received while the project was MIT-licensed remain their authors’ copyright and are redistributed under Apache 2.0 with the original MIT notice preserved in NOTICE, as MIT requires.

Changelog

See CHANGELOG.md.

---

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