---
title: "SOP: AI Toolkit Maintenance"
category: procedures
service: ai-toolkit
tags: [sop, maintenance, agents, skills, install]
version: "3.3.0"
created: "2026-03-23"
last_updated: "2026-07-14"
description: "Standard operating procedures for installing, maintaining, and evolving the ai-toolkit."
---

# SOP: AI Toolkit Maintenance

## Init Repository (New Project)

Use this when starting a new project that should use the toolkit.

**Prerequisites:** toolkit installed globally (`ai-toolkit install` already done once).

```bash
cd /path/to/new-project
ai-toolkit install --local
```

By default, `--local` installs Claude Code configs only:
- `CLAUDE.md` — project-specific rules template (only if missing)
- `.claude/settings.local.json` — MCP servers, env vars, permissions (only if missing, initialized with MCP defaults)
- `.claude/constitution.md` — toolkit constitution **injected** via markers (preserves user content)

To also install editor configs, use `--editors`:

```bash
ai-toolkit install --local --editors all                  # all supported editors
ai-toolkit install --local --editors cursor,aider         # specific editors only
```

Supported editors: `cursor`, `windsurf`, `cline`, `roo`, `aider`, `augment`, `copilot`, `antigravity`, `codex`, `gemini`, `opencode`.

To restrict which language rules are injected, use `--lang`:

```bash
ai-toolkit install --local --lang python,typescript
ai-toolkit install --local --lang python --editors all  # language rules propagated to all editors
```

When `--editors` is combined with `--lang` (or auto-detected languages), language rules are propagated to all configured editors as `ai-toolkit-lang-<lang>` files — not just Claude's `CLAUDE.md`. Similarly, registered custom rules (`~/.softspark/ai-toolkit/rules/`) are propagated to directory-based editor configs as `ai-toolkit-custom-<name>` files.

**Note:** Claude Code hooks are global-only and merge into
`~/.claude/settings.json`; any legacy `.claude/hooks.json` is removed. Editors
with documented repository hook surfaces may receive local native files. Codex
uses `.codex/hooks.json` plus `.codex/hooks/*`; Copilot profile `standard` and
above uses `.github/hooks/ai-toolkit.json` plus its adjacent runtime.

**Input validation (v1.4.2):** `--only`, `--skip`, `--editors`, and `--lang` are validated on input; an invalid value exits with a clear error before any changes are made.

Then edit `CLAUDE.md`:
```markdown
# My Project

## Overview
What this project does.

## Tech Stack
- Language: TypeScript
- Framework: Next.js
- Database: PostgreSQL

## Commands
# Dev: npm run dev
# Test: npm test
# Build: npm run build
```

---

## Install Toolkit Globally

Run once per machine. Installs into `~/.claude/` — available in all projects.

```bash
npm install -g @softspark/ai-toolkit   # once per machine
ai-toolkit install                      # sets up ~/.claude/
```

What `install` and `update` do (merge-friendly — user content never overwritten):

| Component | Strategy | User collision |
|-----------|----------|---------------|
| `agents/*.md` | Per-file symlinks into `~/.claude/agents/` | User file with same name preserved (toolkit skipped) |
| `skills/*/` | Per-directory symlinks into `~/.claude/skills/` | User dir with same name preserved |
| `settings.json` hooks | JSON merge via `merge-hooks.py` | User hooks + settings preserved, toolkit entries tagged `_source: ai-toolkit` |
| `constitution.md` | Marker injection via `inject_section_cli.py` | User content outside `<!-- TOOLKIT:* -->` markers untouched |
| `ARCHITECTURE.md` | Marker injection via `inject_section_cli.py` | Same as above |
| `CLAUDE.md` | Compact index for managed global rules | User content outside toolkit markers untouched |
| `rules/ai-toolkit-*.md` | File-based Claude Code user-level rules from `app/rules/*.md` and registered rules | `ai-toolkit-*` prefix reserved for installer-managed files |

Re-running updates only toolkit content. Old whole-directory symlinks are auto-upgraded to per-file on next run.

### Install in Claude Chat / Desktop / Cowork

The Claude app does not read Claude Code's `~/.claude/rules/`, `CLAUDE.md`,
agents, skills, or settings. Build the separate app-native plugin:

```bash
ai-toolkit claude-app export --verify
```

1. Open Claude and choose `Customize > Plugins > + > Upload plugin`.
2. Select `ai-toolkit-claude-app.zip`.
3. Paste `ai-toolkit-claude-app-global-instructions.md` into
   `Settings > Cowork > Global instructions`.

The export includes registered rules by default; use `--no-custom-rules` for a
shareable clean bundle. Re-export and re-upload after toolkit or registered-rule
updates. Skills work in Chat and Cowork. Hooks and sub-agents run only in Cowork.

### Install Profiles (v3.0.0)

| Profile | Claude Code core | Copilot | Codex | Other editor-native surfaces | Git hooks |
|---------|:---------------:|---------|-------|------------------------------|:---------:|
| `minimal` | yes | root instructions + agents + skills | instructions + agents + skills + hooks | pointer-only where required | no |
| `standard` (default) | yes | minimal + scoped instructions + prompts + hooks | same native bundle | Gemini hooks + editor rules | no |
| `strict` | yes | same as standard | same native bundle | same as standard | yes |
| `full` | yes | same as standard | same native bundle | all supported hooks, agents, commands, and skill pointers | optional |

Codex materializes the full skill catalog under `.agents/skills/` in every
profile. `--codex-skills` remains only as an explicit refresh compatibility
flag. See `kb/reference/global-install-model.md` for the full breakdown.

---

## Update Toolkit

After a new npm release:

```bash
npm install -g @softspark/ai-toolkit@latest
ai-toolkit update
```

`update` is a semantic alias for `install` — use it for all re-apply flows. Supports the same flags:

```bash
ai-toolkit update --only agents,hooks                  # re-apply only specific components
ai-toolkit update --local                              # refresh project-local Claude Code configs; auto-detects editors from existing project files (no --editors needed)
ai-toolkit update --local --editors cursor,windsurf   # override auto-detection and target specific editors
ai-toolkit update --list                               # dry-run: show what would change
```

When running `update --local`, the CLI inspects existing config files (e.g. `.cursor/rules`, `.aider.conf.yml`) to determine which editors are present and refreshes only those — no flags required.

---

## Register a Rule from Another Repo

Third-party repos (jira-mcp, rag-mcp, etc.) can register their own rules globally:

```bash
ai-toolkit add-rule ./my-project-rules.md
# → copies to ~/.softspark/ai-toolkit/rules/my-project-rules.md

ai-toolkit update
# → syncs the rule into ~/.claude/rules/ai-toolkit-registered-*.md and all global editor configs

ai-toolkit update --local
# → also propagates as ai-toolkit-custom-<name> to directory-based editors (Cursor, Windsurf, Cline, Roo, Augment, Antigravity)
```

To unregister (removes from registry **and** strips the block from CLAUDE.md):

```bash
ai-toolkit remove-rule my-project-rules
```

Rule names derive from the filename (`my-project-rules.md` → marker `TOOLKIT:my-project-rules`).

After adding or removing a registered rule, re-export the Claude app plugin if
that runtime should receive the change.

---

## Adding a New Agent

1. Create `app/agents/<agent-name>.md` with YAML frontmatter:
   ```yaml
   ---
   name: agent-name
   description: "When to use this agent. Triggers: keyword1, keyword2."
   tools: Read, Write, Edit, Bash
   model: opus
   skills: skill-1, skill-2
   ---
   ```
2. Write agent instructions below frontmatter
3. Update `kb/reference/agents-catalog.md`
4. Update `app/ARCHITECTURE.md` counts
5. Run `scripts/validate.py`
6. Regenerate: `scripts/generate_agents_md.py > AGENTS.md`

## Adding a New Skill

1. Create `app/skills/<skill-name>/SKILL.md` with frontmatter:
   ```yaml
   ---
   name: skill-name
   description: "Third-person description. Max 1024 chars."
   effort: medium
   disable-model-invocation: true   # task skill
   user-invocable: false            # knowledge skill
   ---
   ```
2. Update `kb/reference/skills-catalog.md` and `app/ARCHITECTURE.md`
3. Run `scripts/validate.py`

## Adding a New Hook

Preferred path:

```bash
/hook-creator [event or hook description]
```

Manual path:

1. Create `app/hooks/<hook-name>.sh`
2. Register the hook under `app/hooks.json`
3. Run `scripts/validate.py`
4. Run `scripts/doctor.py`
5. Update `kb/reference/hooks-catalog.md`, `README.md`, and any affected architecture docs

Use `PreToolUse` for blocking validations, `PostToolUse` for non-blocking feedback, `UserPromptSubmit` for prompt governance, and `PreCompact` / `SessionEnd` for context preservation and handoff.

## Troubleshooting Rule Enforcement in Claude Code

Use this when Claude appears to ignore `CLAUDE.md`, `.claude/rules/*.md`, output styles, or search-first rules.

1. **Check current Claude docs first.** Confirm the live contract for memory, settings, output styles, and hooks:
   - `https://code.claude.com/docs/en/memory`
   - `https://code.claude.com/docs/en/settings`
   - `https://code.claude.com/docs/en/output-styles`
   - `https://code.claude.com/docs/en/hooks`
2. **Isolate with safe mode (v2.1.169+).** Start a session with `claude --safe-mode` (or `CLAUDE_CODE_SAFE_MODE=1`) — it disables hooks, skills, agents, and CLAUDE.md. If the problem persists in safe mode, the cause is upstream, not toolkit customization; if it disappears, bisect toolkit components with `ai-toolkit update --only <component>`.
3. **Verify instruction loading.** Run `/memory` in Claude Code and confirm the expected `CLAUDE.md`, `CLAUDE.local.md`, and `.claude/rules/*.md` files are listed. Remember that Claude Code reads `CLAUDE.md`, not `AGENTS.md`, unless `CLAUDE.md` imports it.
4. **Verify the active output style.** Check `.claude/settings.local.json` or `/config`. Output style changes apply after `/clear` or a new session.
5. **Inspect installed hooks.** Ensure `~/.claude/settings.json` contains the ai-toolkit `UserPromptSubmit` and `Stop` entries. The governance hook must run with `AI_TOOLKIT_HOOK_QUIET=1 AI_TOOLKIT_HOOK_FORMAT=json` so it injects `additionalContext` without noisy transcript output.
6. **Reproduce the hook path directly.**
   ```bash
   printf '{"session_id":"debug","prompt":"debug this technical rule issue"}' \
     | AI_TOOLKIT_SEARCH_FIRST=strict AI_TOOLKIT_HOOK_QUIET=1 AI_TOOLKIT_HOOK_FORMAT=json \
       ~/.softspark/ai-toolkit/hooks/user-prompt-submit.sh
   ```
   The output must be valid JSON with `hookSpecificOutput.additionalContext`.
7. **Check corrective enforcement.** If the assistant still skips required research, `stop-search-check.sh` should block Stop with the search-first message. If it does not, inspect `~/.softspark/ai-toolkit/state/search-required-*.flag` and the Codex/Claude transcript logs.
8. **Repair drift.** Run:
   ```bash
   ai-toolkit update --only hooks
   python3 scripts/ecosystem_doctor.py --tool claude-code --format text
   scripts/validate.py
   ```

## Troubleshooting Rule Enforcement in Claude Chat / Cowork

Do not use `/memory` or inspect `~/.claude/rules/` for the app runtime; those
checks apply only to Claude Code.

1. Run `ai-toolkit claude-app verify` and fix any manifest/component error.
2. Re-export the ZIP and upload it from `Customize > Plugins`.
3. Confirm `ai-toolkit-rules` appears in the `/` or `+` skill picker.
4. Confirm the generated standing instructions are saved under
   `Settings > Cowork > Global instructions`.
5. In regular Chat, expect skills only. Hooks and sub-agents are intentionally
   unavailable there; test those in Cowork.
6. Start a new chat/task after updating the plugin so the new component catalog
   is loaded.

## Verification

After changing rule-enforcement behavior, run at minimum:

```bash
bats tests/test_hooks.bats tests/test_search_first_flow.bats
bats tests/test_install.bats tests/test_codex.bats
bats tests/test_claude_app.bats tests/test_hooks_per_editor.bats
python3 scripts/claude_app.py verify
python3 scripts/validate.py --strict
```

## Managing Plugins

```bash
ai-toolkit plugin list                             # show available packs
ai-toolkit plugin install --editor claude <name>  # install for Claude Code global target
ai-toolkit plugin install --editor codex <name>   # install for Codex global target
ai-toolkit plugin install --editor all --all      # install all 12 packs for both runtimes
ai-toolkit plugin update --editor all --all       # re-apply all installed packs after toolkit updates
ai-toolkit plugin clean <name>                    # prune data older than 90 days
ai-toolkit plugin clean <name> --days 30  # custom retention
ai-toolkit plugin remove --editor codex <name>    # remove from one runtime only
ai-toolkit plugin status --editor all             # show installed packs with runtime details
```

Install copies runtime-owned hooks/scripts, ensures the required base skills are
available, merges native hook configuration, and runs init scripts. Codex uses
`$CODEX_HOME/AGENTS.md`, `$CODEX_HOME/hooks.json`, self-contained
`$CODEX_HOME/ai-toolkit-hooks/*`, and shared `$HOME/.agents/skills/*`; it never
uses `~/AGENTS.md` or `$HOME/.agents/rules/` as user configuration. Update
removes and reinstalls the selected pack while preserving plugin data. Remove
strips only exact pack-owned handlers, assets, and marker sections. Core
agents/skills and user handlers remain untouched.

Memory-pack auto-prunes observations older than 90 days on every session end (configurable via `MEMORY_RETENTION_DAYS`).

State is tracked per runtime in `~/.softspark/ai-toolkit/plugins.json`. After every `ai-toolkit update`, also run `ai-toolkit plugin update --editor all --all` if plugin packs are installed.

## Adding a KB Document

Follow the `documentation-standards` knowledge skill (`app/skills/documentation-standards/SKILL.md`) for full spec. Quick checklist:

1. **Choose category directory:** `kb/reference/`, `kb/howto/`, `kb/procedures/`, `kb/troubleshooting/`, `kb/best-practices/`, or `kb/planning/`
2. **Create file:** kebab-case name, no dates in filename
3. **Add frontmatter** with all 7 required fields: `title`, `category`, `service`, `tags`, `created`, `last_updated`, `description`
4. **Write in English**
5. **Validate:** `scripts/validate.py` (checks all `kb/**/*.md` frontmatter)

**Documents without valid frontmatter will fail `validate.py` and block CI.**

## Adding Scripts to Skills

1. Create `app/skills/<skill-name>/scripts/<script>.py` (stdlib only, JSON output)
2. `chmod +x` the script
3. Reference: `` python3 ${CLAUDE_SKILL_DIR}/scripts/script.py . ``

## Cross-Editor Verification (Mandatory)

**Every addition — skill, hook, MCP template, agent, rule — MUST be verified against all supported editors before merge.**

The ecosystem registry tracks 13 targets: Claude Code, the Claude Chat/Cowork app, and 11 editor integrations. Each has its own config format, file path conventions, and runtime capabilities. A feature that works in Claude Code may silently break in Cursor, Codex, or Copilot if the editor's official spec diverges.

### Verification checklist

When adding or modifying any toolkit component:

1. **Check official docs** — before implementing, fetch the editor's current documentation (web search or Context7) to confirm the config format, file path, and feature support haven't changed
2. **Validate output format** — ensure the generated file matches what the editor expects (JSON schema, TOML structure, MDC frontmatter, directory naming)
3. **Test scope rules** — verify project-local vs global behavior matches the editor's own scope model
4. **Confirm feature parity** — if the feature relies on runtime primitives (hooks, MCP, agent delegation), check whether the target editor supports them; document gaps in `kb/reference/` if not

### Editor documentation sources

| Editor | Where to verify |
|--------|----------------|
| Claude Code | `docs.anthropic.com/claude-code` |
| Cursor | `docs.cursor.com` |
| Windsurf | `docs.codeium.com/windsurf` |
| GitHub Copilot | `docs.github.com/copilot` |
| Gemini CLI | `github.com/google-gemini/gemini-cli` |
| Cline | `github.com/cline/cline` |
| Roo Code | `github.com/RooVetGit/Roo-Code` |
| Aider | `aider.chat` |
| Augment | `docs.augmentcode.com` |
| Codex CLI | `github.com/openai/codex` |
| Google Antigravity | `developers.google.com/project-idx` |

### When to do this

- Adding a new skill → verify it renders correctly for Codex `.agents/skills/` and all directory-based editors
- Adding a new hook → verify event name is valid in Claude and check `.codex/hooks.json` compatibility
- Adding a new MCP template → verify it installs correctly for all 8 native adapters (`mcp_editors.py`)
- Modifying generator output → check that every editor-specific generator still produces valid output
- Adding a new editor → verify ALL existing features render correctly for the new target

### Anti-pattern

Do NOT assume an editor's format based on memory or past behavior. Editors ship breaking changes to their config surfaces. Always verify against current official docs before implementation.

---

## Quality Checks

```bash
scripts/validate.py           # agents, skills, hooks, core files, metadata counts
scripts/doctor.py             # install health, hooks, benchmark freshness, artifact drift diagnostics
scripts/benchmark_ecosystem.py --offline   # ecosystem benchmark snapshot
scripts/benchmark_ecosystem.py --dashboard-json --out benchmarks/ecosystem-dashboard.json
scripts/harvest_ecosystem.py --offline     # refresh machine-readable ecosystem harvest
scripts/evaluate_skills.py    # skill classification report
npm test                      # bats test suite (all workstreams)
```

Or via CLI:

```bash
ai-toolkit validate           # integrity check
ai-toolkit doctor             # install health diagnostics
ai-toolkit benchmark-ecosystem --offline   # benchmark snapshot
```

## Modifying Components

Changes propagate instantly to all machines via symlinks. After any change:

```bash
npm run generate:all          # FIRST: regenerate AGENTS.md, Codex rules, llms.txt, and platform configs
scripts/validate.py           # then validate — must pass before commit
npm test                      # then test — must pass before commit
```

Run `generate:all` before validate and test so that generated artifacts are current when
the metadata contract tests run. Directory-based rule generators now use ownership-aware
cleanup: repo regeneration manages only standard generated files, while `install/update`
manages standard, language, and custom overlays together. That keeps regeneration safe
without leaving stale standard artifacts behind. Committing without regenerating first
causes artifact drift and fails CI.

## Release Checklist

Follow this sequence before every `npm publish` / `git tag`:

### 1. Bump version

```bash
# Edit package.json version field (semver: X.Y.Z)
# Sync package-lock.json: npm install --package-lock-only
# Add entry to CHANGELOG.md
```

### 2. Regenerate all artifacts

```bash
npm run generate:all
```

### 3. Validate and test

```bash
npm run validate    # scripts/validate.py — agents, skills, counts
npm test            # full bats suite including metadata contracts and CLI tests
```

### 4. Verify counts are in sync

The metadata contract tests (`tests/test_metadata_contracts.bats`) catch drift
automatically. If they fail, fix the stale numbers before continuing.

### 5. Check for artifact drift

```bash
git diff --stat
```

Review the diff to confirm that all generated files (`AGENTS.md`, `llms.txt`, platform
configs) reflect the current state. If `generate:all` produced unexpected changes,
investigate before staging.

### 6. Commit and tag

```bash
git add -A
git commit -m "chore: release vX.Y.Z"
git tag vX.Y.Z
git push origin main --tags
```

The publish workflow (`.github/workflows/publish.yml`) picks up the tag, runs full
validation + tests, regenerates AGENTS.md + llms.txt, and publishes to npm.

## Model Tiers

| Agent Type | Model | Examples |
|-----------|-------|---------|
| Complex reasoning | opus | orchestrator, backend-specialist, security-auditor |
| Pattern-following | sonnet | documenter, explorer-agent, data-analyst |

## Uninstall

```bash
ai-toolkit uninstall    # strips toolkit components from ~/.claude/
```

What `uninstall` does:
- Removes per-file agent symlinks (user agents preserved)
- Removes per-directory skill symlinks (user skills preserved)
- Strips toolkit hook entries from `settings.json` (user hooks + settings preserved)
- Strips toolkit markers from `constitution.md` and `ARCHITECTURE.md` (user content preserved; empty files removed)
- `~/.claude/CLAUDE.md` preserved (contains your custom content + compact toolkit index)
- `~/.claude/rules/` preserved unless explicitly removed
- Empty `agents/` and `skills/` directories cleaned up