@softspark/ai-toolkit 1.4.2 → 1.5.0

package/kb/procedures/maintenance-sop.md

@@ -3,9 +3,9 @@ title: "SOP: Claude Toolkit Maintenance"
 category: procedures
 service: ai-toolkit
 tags: [sop, maintenance, agents, skills, install]
-version: "1.0.0"
+version: "1.4.2"
 created: "2026-03-23"
-last_updated: "2026-04-02"
+last_updated: "2026-04-09"
 description: "Standard operating procedures for installing, maintaining, and evolving the ai-toolkit."
 ---
 
@@ -22,18 +22,30 @@ cd /path/to/new-project
 ai-toolkit install --local
 ```
 
-This creates/updates:
+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)
-- `.github/copilot-instructions.md` — GitHub Copilot rules (marker-injected)
-- `.clinerules` — Cline rules (marker-injected)
-- `.roomodes` — Roo Code custom modes (generated)
-- `.aider.conf.yml` — Aider configuration (generated)
-- `.git/hooks/pre-commit` — Safety fallback for quality gates (generated)
+
+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`.
+
+To restrict which language rules are injected into `CLAUDE.md`, use `--lang`:
+
+```bash
+ai-toolkit install --local --lang python,typescript
+```
 
 **Note:** Hooks are global-only — merged into `~/.claude/settings.json` by `ai-toolkit install`. Project-local `--local` does not install hooks; any legacy `.claude/hooks.json` is removed automatically.
 
+**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
@@ -90,11 +102,14 @@ 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 configs (auto-detects editors from existing files)
-ai-toolkit update --list                # dry-run: show what would change
+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
@@ -233,15 +248,14 @@ ai-toolkit benchmark-ecosystem --offline   # benchmark snapshot
 Changes propagate instantly to all machines via symlinks. After any change:
 
 ```bash
-scripts/validate.py           # must pass before commit
-npm test                      # must pass before commit
+npm run generate:all          # FIRST: regenerate AGENTS.md, llms.txt, all platform configs
+scripts/validate.py           # then validate — must pass before commit
+npm test                      # then test — must pass before commit
 ```
 
-If you added/removed agents or skills, also regenerate derived artifacts:
-
-```bash
-npm run generate:all          # regenerates AGENTS.md, llms.txt, all platform configs
-```
+Run `generate:all` before validate and test so that generated artifacts are current when
+the metadata contract tests run. Committing without regenerating first causes artifact
+drift and fails CI.
 
 ## Release Checklist
 
@@ -272,7 +286,17 @@ npm test            # full bats suite including metadata contracts and CLI tests
 The metadata contract tests (`tests/test_metadata_contracts.bats`) catch drift
 automatically. If they fail, fix the stale numbers before continuing.
 
-### 5. Commit and tag
+### 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

package/kb/procedures/release-preparation-sop.md

@@ -0,0 +1,277 @@
+---
+title: "SOP: Release Preparation"
+category: procedures
+service: ai-toolkit
+tags: [sop, release, version, publish, changelog, semver]
+version: "1.5.0"
+created: "2026-04-10"
+last_updated: "2026-04-10"
+description: "Step-by-step checklist for preparing a new ai-toolkit release — version sync, changelog, artifact regeneration, validation, and tagging. Run BEFORE every git tag."
+---
+
+# SOP: Release Preparation
+
+Complete checklist for preparing a new `@softspark/ai-toolkit` release.
+Run this **before** tagging. After tagging and publishing, run the
+[Release Verification SOP](release-verification-sop.md) to smoke-test.
+
+**Pipeline:**
+```
+Release Preparation (this SOP) → git tag → CI publish → Release Verification SOP
+```
+
+**Time:** 5-10 minutes
+
+---
+
+## Quick Checklist (TL;DR)
+
+```bash
+# 1. Decide version bump
+#    patch (1.4.2 → 1.4.3): bugfix, typo, doc fix
+#    minor (1.4.2 → 1.5.0): new feature, new skill, new flag
+#    major (1.4.2 → 2.0.0): breaking change
+
+# 2. Sync version across all files
+python3 scripts/sync_version.py X.Y.Z          # if script exists, else manual
+
+# 3. Write CHANGELOG.md entry
+# 4. Regenerate artifacts
+python3 scripts/generate_agents_md.py > AGENTS.md
+python3 scripts/generate_llms_txt.py > llms.txt
+python3 scripts/generate_llms_txt.py --full > llms-full.txt
+
+# 5. Validate + audit + test
+python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && npm test
+
+# 6. Commit + tag + push
+git add -A && git commit -m "chore: release vX.Y.Z"
+git tag vX.Y.Z
+git push origin main --tags
+```
+
+---
+
+## Phase 1: Determine Version Bump
+
+Follow [Semantic Versioning](https://semver.org/):
+
+| Change Type | Bump | Examples |
+|-------------|------|---------|
+| Bugfix, typo, doc-only | **patch** | Fix install flag, correct description |
+| New feature, skill, agent, flag | **minor** | Add `/hipaa-validate`, add `--output json` |
+| Breaking CLI change, removed skill, config format change | **major** | Rename `install` to `setup`, remove skill |
+
+**Rule:** When in doubt, bump minor.
+
+---
+
+## Phase 2: Sync Version in All Files
+
+The canonical version lives in `package.json`. These files **must** match:
+
+### Mandatory sync (every release)
+
+| File | Field | How to update |
+|------|-------|---------------|
+| `package.json` | `"version": "X.Y.Z"` | Edit directly |
+| `manifest.json` | `"version": "X.Y.Z"` | Edit directly |
+| `app/.claude-plugin/plugin.json` | `"version": "X.Y.Z"` | Edit directly |
+
+### Auto-synced (no manual action)
+
+| File | Mechanism |
+|------|-----------|
+| `package-lock.json` | Regenerated by `npm install --package-lock-only` |
+
+### Conditional sync (only if the doc was modified in this release)
+
+| File | Field | When to update |
+|------|-------|---------------|
+| `kb/procedures/maintenance-sop.md` | frontmatter `version:` | If SOP content changed |
+| `kb/reference/skills-catalog.md` | frontmatter `version:` | If skills added/removed |
+| `kb/reference/agents-catalog.md` | frontmatter `version:` | If agents added/removed |
+| `kb/reference/hooks-catalog.md` | frontmatter `version:` | If hooks changed |
+| `kb/reference/architecture-overview.md` | frontmatter `version:` | If architecture changed |
+| `kb/reference/distribution-model.md` | frontmatter `version:` | If install model changed |
+| `kb/reference/global-install-model.md` | frontmatter `version:` | If install model changed |
+
+> **Note:** KB `version:` fields track the **document version**, not the toolkit version.
+> Only bump them when the document content actually changes in this release.
+
+### Count sync (if skills/agents/hooks changed)
+
+| File | What to check |
+|------|---------------|
+| `package.json` | `"description"` — skill/agent count |
+| `README.md` | Badge counts, "What You Get" table |
+| `app/ARCHITECTURE.md` | Section headings with counts |
+
+> **Tip:** `validate.py --strict` and `npm test` (metadata contract tests) catch
+> count drift automatically. If tests pass, counts are correct.
+
+### Verification command
+
+After syncing, verify all mandatory files match:
+
+```bash
+VERSION=$(python3 -c "import json; print(json.load(open('package.json'))['version'])")
+echo "Target: $VERSION"
+echo "manifest.json:     $(python3 -c "import json; print(json.load(open('manifest.json'))['version'])")"
+echo "plugin.json:       $(python3 -c "import json; print(json.load(open('app/.claude-plugin/plugin.json'))['version'])")"
+echo "package-lock.json: $(python3 -c "import json; print(json.load(open('package-lock.json'))['version'])")"
+```
+
+All four must print the same version. If not, fix before proceeding.
+
+---
+
+## Phase 3: Write CHANGELOG Entry
+
+Add entry at the top of `CHANGELOG.md` (after the header, before previous release):
+
+```markdown
+## vX.Y.Z — Short Title (YYYY-MM-DD)
+
+### Added
+- **Feature name** — description
+
+### Changed
+- **What changed** — old behavior → new behavior
+
+### Fixed
+- **Bug description** — what was broken and how it's fixed
+
+### Removed
+- **What was removed** — migration path if any
+```
+
+**Rules:**
+- Use **bold** for feature names
+- Start descriptions with a verb (Added, Changed, Fixed, Removed)
+- Reference skill names with backticks and slash: `/hipaa-validate`
+- Include script names: `scripts/hipaa_scan.py`
+- Include count changes: `Skill count: 91 → 92`
+- Date format: `YYYY-MM-DD`
+- Title: short, descriptive, no version number repetition
+
+---
+
+## Phase 4: Regenerate Artifacts
+
+```bash
+python3 scripts/generate_agents_md.py > AGENTS.md
+python3 scripts/generate_llms_txt.py > llms.txt
+python3 scripts/generate_llms_txt.py --full > llms-full.txt
+```
+
+Check if anything actually changed:
+
+```bash
+git diff --stat AGENTS.md llms.txt llms-full.txt
+```
+
+If no diff, the artifacts are already current. If there is a diff, stage them.
+
+---
+
+## Phase 5: Validate, Audit, Test
+
+Run the full quality gate:
+
+```bash
+python3 scripts/validate.py --strict
+python3 scripts/audit_skills.py --ci
+npm test
+```
+
+**Expected results:**
+- `validate.py`: `Errors: 0 | Warnings: 0 | VALIDATION PASSED`
+- `audit_skills.py`: `HIGH: 0 | WARN: 0` (INFO is acceptable)
+- `npm test`: `1..N` with zero `not ok`
+
+**One-liner:**
+```bash
+python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && npm test
+```
+
+**If tests fail:** Fix the issue, do NOT skip. Common failures:
+- Stale counts → re-run `generate:all` or fix README/ARCHITECTURE
+- Missing frontmatter → add to new KB docs
+- Broken symlink → `ai-toolkit doctor --fix`
+
+---
+
+## Phase 6: Commit
+
+Stage all release files:
+
+```bash
+git add package.json manifest.json app/.claude-plugin/plugin.json
+git add package-lock.json
+git add CHANGELOG.md
+git add AGENTS.md llms.txt llms-full.txt
+git add -p  # review and stage any other changes
+```
+
+Commit:
+
+```bash
+git commit -m "chore: release vX.Y.Z"
+```
+
+---
+
+## Phase 7: Tag and Push
+
+```bash
+git tag vX.Y.Z
+git push origin main --tags
+```
+
+This triggers `.github/workflows/publish.yml` which:
+1. Runs `validate.py --strict`
+2. Runs `npm test`
+3. Publishes to npm as `@softspark/ai-toolkit@X.Y.Z`
+
+**After CI completes:** Run the [Release Verification SOP](release-verification-sop.md)
+to smoke-test the published package.
+
+---
+
+## Rollback
+
+If a bad release was published:
+
+```bash
+# Unpublish from npm (within 72h)
+npm unpublish @softspark/ai-toolkit@X.Y.Z
+
+# Or deprecate (preferred — doesn't break existing installs)
+npm deprecate @softspark/ai-toolkit@X.Y.Z "Known issue: <description>. Use vA.B.C instead."
+
+# Delete tag
+git tag -d vX.Y.Z
+git push origin --delete vX.Y.Z
+```
+
+---
+
+## Checklist Summary
+
+| # | Step | Command / Action | Pass Criteria |
+|---|------|-----------------|---------------|
+| 1 | Version bump type | Decide patch/minor/major | — |
+| 2 | `package.json` version | Edit `"version"` | Matches target |
+| 3 | `manifest.json` version | Edit `"version"` | Matches target |
+| 4 | `plugin.json` version | Edit `"version"` | Matches target |
+| 5 | `package-lock.json` | `npm install --package-lock-only` | Matches target |
+| 6 | Count sync | Check `package.json` description, README | `validate.py` passes |
+| 7 | CHANGELOG.md | Add release entry | Entry exists for vX.Y.Z |
+| 8 | Regenerate artifacts | `generate_agents_md.py`, `generate_llms_txt.py` | No unexpected diff |
+| 9 | Validate | `validate.py --strict` | 0 errors, 0 warnings |
+| 10 | Security audit | `audit_skills.py --ci` | 0 HIGH |
+| 11 | Tests | `npm test` | All pass |
+| 12 | Commit | `git commit` | Clean working tree |
+| 13 | Tag | `git tag vX.Y.Z` | Tag exists |
+| 14 | Push | `git push origin main --tags` | CI triggered |

package/kb/reference/agents-catalog.md

@@ -3,9 +3,9 @@ title: "AI Toolkit - Agents Catalog"
 category: reference
 service: ai-toolkit
 tags: [agents, catalog, roles, ai-development]
-version: "1.3.10"
+version: "1.4.2"
 created: "2026-03-23"
-last_updated: "2026-03-25"
+last_updated: "2026-04-09"
 description: "Complete catalog of specialized agents with roles, models, and use cases."
 ---
 

package/kb/reference/architecture-overview.md

@@ -3,9 +3,9 @@ title: "AI Toolkit - Architecture Overview"
 category: reference
 service: ai-toolkit
 tags: [architecture, overview, design, structure]
-version: "1.4.0"
+version: "1.4.2"
 created: "2026-03-23"
-last_updated: "2026-04-08"
+last_updated: "2026-04-09"
 description: "Architecture of ai-toolkit: directory layout, global install model, skill tiers, and integration with projects."
 ---
 
@@ -177,7 +177,7 @@ Three tiers determine how to approach a task:
 
 | Type | Field | Invocation | Count |
 |------|-------|-----------|-------|
-| Task | `disable-model-invocation: true` | User via `/skill` only | 28 |
+| Task | `disable-model-invocation: true` | User via `/skill` only | 29 |
 | Hybrid | (neither) | User via `/skill` + agent knowledge | 31 |
 | Knowledge | `user-invocable: false` | Claude auto-loads | 32 |
 

package/kb/reference/distribution-model.md

@@ -3,9 +3,9 @@ title: "Distribution Model"
 category: reference
 service: ai-toolkit
 tags: [architecture, distribution, symlinks, npm, install]
-version: "1.0.0"
+version: "1.4.2"
 created: "2026-03-23"
-last_updated: "2026-03-28"
+last_updated: "2026-04-09"
 description: "Reference description of how ai-toolkit is delivered and propagated on a developer machine."
 ---
 

package/kb/reference/global-install-model.md

@@ -3,9 +3,9 @@ title: "Global Install Model"
 category: reference
 service: ai-toolkit
 tags: [install, global, claude, local-setup]
-version: "1.0.0"
+version: "1.4.2"
 created: "2026-03-26"
-last_updated: "2026-03-28"
+last_updated: "2026-04-09"
 description: "Reference description of the global install target, local project setup, and command responsibilities in ai-toolkit."
 ---
 
@@ -23,7 +23,9 @@ That means one machine-level install provides agents, skills, hooks, and rules t
 |---------|--------|---------|
 | `ai-toolkit install` | `~/.claude/` | first-time machine setup |
 | `ai-toolkit update` | `~/.claude/` | re-apply after package or rule changes |
-| `ai-toolkit install --local` | current project | Claude Code configs only (CLAUDE.md, settings, constitution, language rules). Add `--editors all` for other tools. |
+| `ai-toolkit install --local` | current project | Claude Code configs only (CLAUDE.md, settings, constitution, language rules). Add `--editors all` for other tools, or `--editors cursor,aider` for specific ones. Auto-detects editors from existing project files when `--editors` is omitted. |
+| `ai-toolkit install --local --lang <lang>` | current project | explicit language selection for rules (e.g. `--lang typescript`, `--lang go,python`); auto-detected when omitted |
+| `ai-toolkit install --modules <list>` | `~/.claude/` | selective module install (e.g. `--modules core,agents,rules-typescript`) |
 | `ai-toolkit update --local` | current project | refresh project configs; auto-detects editors from existing files |
 | `ai-toolkit add-rule` | `~/.ai-toolkit/rules/` | register a global rule |
 | `ai-toolkit remove-rule` | `~/.ai-toolkit/rules/` | unregister a global rule |
@@ -45,6 +47,8 @@ These files still stay local to a repository:
 - `.clinerules`
 - `.roomodes`
 - `.aider.conf.yml`
+- `.augment/rules/ai-toolkit-*.md`
+- `.agent/rules/*.md` and `.agent/workflows/*.md` (Google Antigravity)
 - `.git/hooks/pre-commit` (fallback)
 - project-specific documentation or safety overlays
 

package/kb/reference/hooks-catalog.md

@@ -3,9 +3,9 @@ title: "Hooks Catalog"
 category: reference
 service: ai-toolkit
 tags: [hooks, quality, safety, enforcement, settings.json]
-version: "1.1.0"
+version: "1.4.2"
 created: "2026-03-27"
-last_updated: "2026-04-07"
+last_updated: "2026-04-09"
 description: "Complete reference of all ai-toolkit hooks: events, scripts, installation, and runtime behavior."
 ---
 
@@ -380,7 +380,7 @@ Set in `.claude/settings.local.json`:
 
 **Hook script not found:**
 ```bash
-ls ~/.ai-toolkit/hooks/     # should list 12 .sh files (plus _profile-check.sh helper)
+ls ~/.ai-toolkit/hooks/     # should list 21 .sh files (plus _profile-check.sh helper)
 ai-toolkit update            # re-copies scripts
 ```
 

package/kb/reference/skills-catalog.md

@@ -3,9 +3,9 @@ title: "AI Toolkit - Skills Catalog"
 category: reference
 service: ai-toolkit
 tags: [skills, domain-knowledge, catalog, task-skills, hybrid-skills]
-version: "1.4.0"
+version: "1.4.2"
 created: "2026-03-23"
-last_updated: "2026-04-08"
+last_updated: "2026-04-09"
 description: "Complete skills catalog with task, hybrid, and knowledge skills. Includes effort levels, skill-scoped hooks, executable scripts, security auditor, and persona presets."
 ---
 
@@ -21,7 +21,7 @@ All functionality is unified under skills. Task and hybrid skills are user-invoc
 | **2 — Multi-agent workflow** | `/workflow <type>` | Cross-cutting task with known pattern |
 | **3 — Custom parallelism** | `/orchestrate`, `/swarm` | No predefined workflow matches |
 
-## Task Skills (28)
+## Task Skills (29)
 
 Task skills execute a specific action. Invoked via slash commands. `disable-model-invocation: true`.
 
@@ -55,6 +55,7 @@ Task skills execute a specific action. Invoked via slash commands. `disable-mode
 | **health** | `/health` | medium | Check health of project services (auto-detect) |
 | **prd-to-issues** | `/prd-to-issues` | medium | Break PRD into GitHub issues with vertical slices and HITL/AFK tagging |
 | **skill-audit** | `/skill-audit` | medium | Scan skills and agents for security risks: dangerous patterns, secrets, excessive permissions |
+| **hipaa-validate** | `/hipaa-validate` | medium | Scan codebase for HIPAA compliance issues: PHI exposure, missing audit logging, unencrypted transmission/storage, access control gaps, temp file exposure, and missing BAA references |
 
 ## Hybrid Skills (31)