ai-toolkit

Professional-grade AI coding toolkit with multi-platform support. Machine-enforced safety, 85 skills, 47 agents, expanded lifecycle hooks, experimental opt-in plugin packs, and benchmark tooling — works with Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, and Aider, 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 85 skills, 47 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 to generate project-specific configs (CLAUDE.md, Copilot, Cline, Roo Code, Aider, git hooks):

cd your-project/
ai-toolkit install --local         # first time
ai-toolkit update --local          # after toolkit updates

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

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.

Platform Support

Note: Claude Code remains the primary platform with full feature support (agents, lifecycle hooks, safety constitution). Other platforms receive a distilled ruleset generated from the same source. 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/          # 47 agent definitions
│   │   ├── orchestrator.md
│   │   ├── backend-specialist.md
│   │   ├── security-architect.md
│   │   └── ... (44 more)
│   ├── skills/          # 85 skills (task / hybrid / knowledge)
│   │   ├── commit/      # /commit slash command
│   │   ├── review/      # /review slash command
│   │   ├── clean-code/  # knowledge skill (auto-loaded)
│   │   └── ... (82 more)
│   ├── rules/           # Auto-injected into your CLAUDE.md
│   ├── hooks/           # Hook scripts (copied to ~/.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
│   │   ├── 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
│   │   ├── session-end.sh        # Session handoff snapshot
│   │   └── post-tool-use.sh      # Lightweight feedback after edits
│   ├── 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
├── 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 ~/.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

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 ~/.ai-toolkit/hooks/ on install and referenced from ~/.claude/settings.json. Easy to read, debug, and extend.

12 lifecycle events / 15 global hook entries:

5 skill-scoped hooks:

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

4. Multi-Language Quality Gates

The Stop hook runs after every response across 5 languages:

5. Iron Law Enforcement

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

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

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

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

9. Persistent Memory (memory-pack plugin)

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

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

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.

Comparison

Agent Teams

Native support for CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

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.md + settings + constitution + Copilot + Cline + Roo + Aider + Git Hooks + MCP Default)
ai-toolkit install --local

# Update project-local configs after toolkit update
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 --local               # also set up project-local configs (CLAUDE.md, settings, constitution, Copilot, Cline, Roo, Aider, Git Hooks, MCP Defaults)
ai-toolkit update --local                # re-apply + refresh project-local configs
ai-toolkit install --list                # dry-run: show what would be applied

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' → ~/.ai-toolkit/rules/jira-rules.md

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

Rules are stored in ~/.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 ~/.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.