Ai Toolkit

ai-toolkit

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

[](https://github.com/softspark/ai-toolkit/actions/workflows/ci.yml) [](LICENSE) [](app/skills/) [](app/agents/) [](tests/)

What's New in v4.10.1

v4.10.1 fixes editor-governance gaps found in the release audit.

• Copilot local installs now emit root AGENTS.md: ai-toolkit install --local --editors copilot writes the generated agent catalog into a TOOLKIT:copilot-agents section while preserving existing Codex/opencode sections and user text.
• Claude Code KB-first enforcement restored: CLAUDE.md now carries the mandatory smart_query() / hybrid_search_kb() rule before technical/project answers, instead of relying on generated AGENTS.md.
• Codex PostToolUse hook output fixed: loop-guard.sh no longer forces Claude-style JSON with suppressOutput under quiet Codex hooks.
• Release packaging hardened: local .claude session artifacts under app/ are excluded from npm pack, even if they exist in a maintainer checkout.
• Docs and ecosystem baseline refreshed: README, registry, and architecture docs now match the Copilot implementation; ecosystem-doctor snapshot is refreshed for upstream Claude/Gemini docs hash drift.
• Test count: 1195 → 1198.

See [CHANGELOG.md](CHANGELOG.md) for full history.

---

Table of Contents

• [Install](#install)
• [Platform Support](#platform-support)
• [What You Get](#what-you-get)
• [Architecture](#architecture)
• [Key Features](#key-features)
• [Key Slash Commands](#key-slash-commands)
• [Getting Started](#getting-started)
• [Documentation](#documentation)
• [Contributing](#contributing)
• [Security](#security)
• [License](#license)
• [Changelog](#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 108 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](kb/reference/windows-support.md).

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](kb/reference/cli-reference.md) 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 + .github/instructions/* + .github/prompts/* + AGENTS.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) | 46 | Domain knowledge auto-loaded by agents (includes 13 -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 | 7 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/          # 108 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  # 7 immutable safety articles
│   └── ARCHITECTURE.md  # Full system design
├── kb/                  # Reference docs, procedures, plans
├── scripts/             # Validation, install, evaluation scripts
├── tests/               # Bats test suite (1198 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](kb/reference/distribution-model.md).

---

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.

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](kb/reference/hooks-catalog.md).

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](kb/reference/enterprise-config-guide.md).

70 language rules — 13 languages + common, 5 categories each. Auto-detected or explicit --lang. See [Language Rules](kb/reference/language-rules.md).

26 MCP templates — Ready-to-use configs for GitHub, PostgreSQL, Slack, Jira, Sentry, and more. See [MCP Templates](kb/reference/mcp-templates.md).

See [Unique Features](kb/reference/unique-features.md) for detailed descriptions of all differentiators.

---

Key Slash Commands

| Command | Purpose | Effort | |---------|---------|--------| | /workflow | 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  (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).

1. Start using skills:

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

1. Verify your install:

``bash ai-toolkit validate ``

---

Documentation

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

---

Contributing

See [CONTRIBUTING.md](.github/CONTRIBUTING.md).

Security

See [SECURITY.md](SECURITY.md) for responsible disclosure policy.

License

MIT — see [LICENSE](LICENSE).

Changelog

See [CHANGELOG.md](CHANGELOG.md).

---

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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: softspark
• Source: softspark/ai-toolkit
• License: MIT
• Homepage: https://softspark.eu

Install and usage instructions live in the source repository linked above.