# ai-toolkit

> Professional-grade Claude Code toolkit: skills, agents, machine-enforced constitution, quality hooks.

## Documentation

- [README](README.md): Installation, usage, and feature overview
- [CHANGELOG](CHANGELOG.md): Version history
- [ARCHITECTURE](app/ARCHITECTURE.md): System design
- [CONSTITUTION](app/constitution.md): Safety rules

## Knowledge Base

- [Best Practices](kb/best-practices/README.md)
- [No Hardcoded Counts in Secondary Docs](kb/best-practices/no-hardcoded-counts.md)
- [Plan: Deep Coverage v3.0 — 100% Native Surface Utilization](kb/history/completed/deep-coverage-v3-20260423.md)
- [Plan: Drop Cascade hooks after 2026-07-01 sunset](kb/history/completed/drop-cascade-hooks-after-sunset-20260710.md)
- [Plan: Ecosystem Deep Sweep — All 12 Supported Tools](kb/history/completed/ecosystem-deep-sweep-20260423.md)
- [Plan: Enterprise Config Inheritance — Multi-Repo Governance with `extends`](kb/history/completed/enterprise-config-inheritance-plan-20260412.md)
- [Spike: F2 MCP Context Trim — Hook Feasibility & Path Decision](kb/history/completed/f2-mcp-trim-spike-20260504.md)
- [Language Plugin Packs — REMOVED](kb/history/completed/language-packs-removed-20260727.md)
- [PRD: MCP Context Trim v4.0 — ABANDONED](kb/history/completed/mcp-context-trim-v4-prd-obsoleted-20260727.md)
- [Implementation Plan: Native Tool Output Filter](kb/history/completed/native-tool-output-filter-plan.md)
- [Removed: Nine Plugin Packs That Installed Nothing](kb/history/completed/no-op-plugin-packs-removed-20260727.md)
- [Plan: Offline-First SLM Profile — Lightweight Mode for Local Models](kb/history/completed/offline-slm-profile-plan-20260411.md)
- [Retirement: Native Tool-Output Filter](kb/history/completed/output-filter-retirement-20260726.md)
- [Plan: Output & Token Discipline](kb/history/completed/output-token-discipline-plan-20260504.md)
- [rtk Pack Integration](kb/history/completed/rtk-pack-integration-20260726.md)
- [Retirement: rtk-pack](kb/history/completed/rtk-pack-retirement-20260727.md)
- [Closed: Tool-Output Token Reduction](kb/history/completed/tool-output-token-reduction-closed-20260727.md)
- [How-To Guides](kb/howto/README.md)
- [Plan: Cloud Security Pack — Multi-Cloud Audit](kb/planning/cloud-security-pack-plan.md)
- [SOP: Ecosystem Sync](kb/procedures/ecosystem-sync-sop.md)
- [SOP: AI Toolkit Maintenance](kb/procedures/maintenance-sop.md)
- [SOP: Post-Release Testing](kb/procedures/post-release-testing-sop.md)
- [SOP: Release Preparation](kb/procedures/release-preparation-sop.md)
- [SOP: Release Verification](kb/procedures/release-verification-sop.md)
- [Agents Catalog](kb/reference/agents-catalog.md)
- [Anti-Pattern Registry Format](kb/reference/anti-pattern-registry-format.md)
- [AI Toolkit Architecture](kb/reference/architecture-overview.md)
- [Config Benchmark](kb/reference/benchmark-config.md)
- [CI Integration](kb/reference/ci-integration.md)
- [Claude Ecosystem Benchmark Snapshot](kb/reference/claude-ecosystem-benchmark-snapshot.md)
- [Claude Ecosystem Expansion Foundations](kb/reference/claude-ecosystem-expansion-foundations.md)
- [CLI Reference](kb/reference/cli-reference.md)
- [AI Toolkit - Codex CLI Compatibility](kb/reference/codex-cli-compatibility.md)
- [Ecosystem Comparison](kb/reference/comparison.md)
- [Plan: Competitive Features — ai-toolkit](kb/reference/competitive-features-implementation.md)
- [AI Toolkit - GitHub Copilot Compatibility](kb/reference/copilot-compatibility.md)
- [Distribution Model](kb/reference/distribution-model.md)
- [Enterprise Config Inheritance Guide](kb/reference/enterprise-config-guide.md)
- [Extension API Reference](kb/reference/extension-api.md)
- [Global Install Model](kb/reference/global-install-model.md)
- [Hierarchical Override Pattern](kb/reference/hierarchical-override-pattern.md)
- [Hooks Catalog](kb/reference/hooks-catalog.md)
- [External Integrations](kb/reference/integrations.md)
- [Language Rules System](kb/reference/language-rules.md)
- [Licensing](kb/reference/licensing.md)
- [Manifest-Driven Install System](kb/reference/manifest-install.md)
- [MCP Editor Compatibility](kb/reference/mcp-editor-compatibility.md)
- [MCP Server Templates](kb/reference/mcp-templates.md)
- [Medplum Documentation Map](kb/reference/medplum-docs-map.md)
- [Merge-Friendly Install Model](kb/reference/merge-friendly-install-model.md)
- [AI Toolkit - opencode Compatibility](kb/reference/opencode-compatibility.md)
- [Plugin Pack Conventions](kb/reference/plugin-pack-conventions.md)
- [Quick Wins Implementation Summary](kb/reference/quick-wins-implementation-summary.md)
- [Skill Templates](kb/reference/skill-templates.md)
- [Skills Catalog](kb/reference/skills-catalog.md)
- [Skills Unification Model](kb/reference/skills-unification.md)
- [Usage Statistics](kb/reference/stats.md)
- [Supported Tools Registry](kb/reference/supported-tools-registry.md)
- [Config Sync](kb/reference/sync.md)
- [Unique Features & Differentiators](kb/reference/unique-features.md)
- [Windows Support](kb/reference/windows-support.md)
- [Troubleshooting](kb/troubleshooting/README.md)

## Skills

- **a11y-validate**: Accessibility validator: WCAG 2.1 AA, EN 301 549, EAA. Triggers: a11y, accessibility, WCAG, EAA, ARIA, contrast, keyboard, screen reader.
- **agent-creator**: Creates new specialized agents with frontmatter, tools, delegation. Triggers: new agent, create agent, agent scaffold, specialized agent.
- **analyze**: Analyzes code quality, complexity, patterns across codebase. Triggers: quality report, hotspot scan, code analysis, architecture signal.
- **api-patterns**: REST/GraphQL API design: naming, versioning, pagination, idempotency, OpenAPI. Triggers: API design, REST, GraphQL, OpenAPI, Swagger, idempotency, rate limit.
- **app-builder**: App scaffolding: Next.js, Vite, Nuxt, Astro, FastAPI, Django, Laravel, RN, Flutter. Triggers: scaffold, bootstrap, new project, starter, dashboard, mobile app.
- **architecture-audit**: Audits codebase for architectural friction, shallow modules; proposes RFCs. Triggers: improve architecture, shallow modules, deepen modules, reduce coupling.
- **architecture-decision**: Architecture decisions in ADR/RFC/RFD format: context, constraints, options, recommendation. Triggers: ADR, RFC, RFD, trade-offs, design choice, pick between, evaluate approach.
- **biz-scan**: Scans codebase for revenue opportunities, KPIs, monetization gaps. Triggers: business metrics, KPI, analytics gaps, monetization, revenue.
- **brand-voice**: Direct technical voice for docs, README, user-facing text. Concise/strict modes. Triggers: documentation, README, content, output-mode, voice, prose style.
- **briefing**: Executive daily briefing aggregating reports from all agents into decision-focused summary. Triggers: briefing, daily summary, status across system, executive update.
- **build**: Builds project with auto-detected toolchain (npm, poetry, cargo, go, flutter, Docker). Triggers: build, compile, bundle, produce artifacts.
- **chaos**: Injects controlled faults for resilience testing on non-prod. Triggers: chaos, fault injection, latency injection, dependency kill, resilience test.
- **ci**: Detect/generate/debug CI pipeline config (GitHub Actions, GitLab CI). Triggers: CI setup, build pipeline, GitHub Actions config, debug CI, GitLab CI.
- **ci-cd-patterns**: CI/CD: GitHub Actions, GitLab CI, Jenkins, caching, blue-green, canary. Triggers: CI, CD, pipeline, GitHub Actions, workflow YAML, release, canary, rollout.
- **clean-code**: Code quality: meaningful names, SRP, DRY, small functions, guard clauses, refactoring. Triggers: clean code, naming, code smell, SRP, DRY, long function, god class, dead code.
- **command-creator**: Creates new Claude Code slash commands with frontmatter and validation. Triggers: new slash command, create command, command scaffold.
- **commit**: Creates Conventional Commits with pre-commit validation. Triggers: commit, conventional commit, git commit, message.
- **content-moderation-patterns**: Content moderation with Claude: pre-filter vs LLM-classify, categories, thresholds, HITL. Triggers: moderation, safety filter, policy enforcement, content classifier.
- **council**: 4-perspective decision evaluation for architecture choices. Triggers: council, evaluate decision, pros cons, multi-angle, alternatives.
- **cpp-rules**: C++ coding rules: style, patterns, security, testing. Triggers: .cpp, .cc, .cxx, .hpp, .h, CMakeLists.txt, Makefile, GoogleTest, clang-tidy.
- **csharp-patterns**: C#/.NET: LINQ, async/await, DI, records, nullable refs, ASP.NET Core, EF Core, MediatR. Triggers: C#, .NET, dotnet, ASP.NET, EF Core, LINQ, record type, IServiceCollection.
- **csharp-rules**: C#/.NET coding rules: style, patterns, security, testing. Triggers: .cs, .csproj, .sln, ASP.NET, ASP.NET Core, EF Core, LINQ, NUnit, xUnit, dotnet.
- **cve-scan**: Scans deps for known CVEs via native audit (npm, pip, composer, cargo, go, bundler, dart). Triggers: CVE scan, vulnerability scan, npm audit, pip audit.
- **dart-rules**: Dart/Flutter coding rules: style, patterns, security, testing. Triggers: .dart, pubspec.yaml, Flutter, Riverpod, Bloc, widget, StatelessWidget, StatefulWidget.
- **database-patterns**: DB schema design and query tuning: normalization, indexing, N+1, transactions, EXPLAIN. Triggers: schema, index, slow query, N+1, PostgreSQL, MySQL, EXPLAIN, deadlock, query plan.
- **debug**: Systematic debugging via logs, health checks, hypothesis-driven investigation. Triggers: debug, error, trace root cause, fix bug, reproduce symptom, investigation.
- **deep-research**: Multi-source web research methodology: retrieve-vs-answer gate, complexity-scaled search budget, query craft, primary-source preference, source-conflict skepticism, adversarial verification, attribution-without-reproduction. Triggers: deep research, multi-source, web research, synthesize sources, cross-reference, fact synthesis, source verification.
- **deploy**: Deploys with pre-flight checks and health verification. Triggers: deploy, deployment, ship, release, push to prod.
- **design-an-interface**: Generates and compares parallel interface designs (Ousterhout 'Design It Twice'). Triggers: design API, interface options, compare modules, design it twice.
- **design-engineering**: UI craftsmanship: animation rules, easing, micro-interactions, state polish. Triggers: animation, transition, ease-out, motion, micro-interaction, hover, loading state, UI polish.
- **docker-devops**: Docker/K8s: Dockerfile, multi-stage, compose, manifests, Helm. Triggers: Docker, Dockerfile, container, Kubernetes, k8s, compose, Helm, pod.
- **docs**: Generates/updates README, API docs, architecture notes. Triggers: docs, README, API docs, architecture note, documentation.
- **documentation-standards**: KB conventions: YAML frontmatter, 5-category taxonomy (reference/howto/procedures/troubleshooting/best-practices). Triggers: kb/, SOP, runbook, howto, frontmatter, knowledge base.
- **ecommerce-patterns**: E-commerce: cart, checkout, payments (Stripe/Adyen), order state, inventory, promos, tax. Triggers: cart, checkout, SKU, payment, Stripe, Shopify, Medusa, Magento, coupon, refund.
- **evaluate**: Evaluates RAG retrieval and LLM-as-judge metrics (faithfulness, relevancy, context precision). Triggers: measure RAG quality, knowledge gap, RAG eval, golden dataset.
- **evolve**: Analyzes agent/skill failures, drafts prompt/permission fixes. Triggers: improve agent, refine skill, system prompt, optimize agent.
- **explain**: Explains code/architecture with Mermaid diagrams and sequence flows. Triggers: what does X do, how does Y work, explain code, sequence diagram.
- **explore**: Explores codebase structure, stack, and architecture. Triggers: explore codebase, project structure, stack overview, architecture map.
- **fix**: Applies targeted fix to known bug/lint error, verifies with same command that surfaced it. Triggers: fix, apply fix, fix bug, fix lint, targeted fix.
- **flutter-patterns**: Flutter/Dart: widgets, state mgmt (Riverpod/Bloc), navigation, platform channels. Triggers: Flutter, Dart, widget, Riverpod, Bloc, pubspec, hot reload.
- **git-mastery**: Advanced Git: rebase, bisect, reflog, cherry-pick, worktrees, LFS. Triggers: rebase, bisect, cherry-pick, reflog, force push, merge conflict, worktree.
- **golang-rules**: Go coding rules: style, patterns, security, testing. Triggers: .go, go.mod, go.sum, Gin, Echo, Gorilla, testing, gofmt.
- **grill-me**: Stress-tests a plan via Socratic questioning down each decision branch. Triggers: stress-test, grill me, validate assumptions, challenge plan, socratic review.
- **health**: Service/infra health via liveness/readiness checks, resource usage, quick diagnostics. Triggers: health check, services up, system status, infra health, degraded service.
- **hipaa-validate**: HIPAA validator: PHI exposure, audit logging, encryption, access control, BAA refs. Triggers: HIPAA, PHI, healthcare compliance, audit log, BAA.
- **hook-creator**: Create new Claude Code lifecycle hook (PreToolUse/PostToolUse/Stop/SessionStart) with bash + hooks.json. Triggers: create hook, lifecycle hook, PreToolUse, PostToolUse, hook event.
- **index**: Reindexes KB for semantic search via vector store (Qdrant). Triggers: reindex KB, rebuild index, vector reindex, refresh embeddings.
- **instinct-review**: Reviews/promotes/removes instincts from `.claude/instincts/*.md`. Triggers: instinct review, curate instincts, manage instincts, promote instinct.
- **introspect**: Agent self-debugging and recovery. Use when stuck in loops, making repeated errors, or quality degrades. Triggers: introspect, self-debug, stuck, loop, why failing.
- **java-patterns**: Java: Spring Boot, CompletableFuture, records, sealed types, JPA/Hibernate, virtual threads. Triggers: Java, Spring, JPA, Hibernate, Maven, Gradle, virtual thread, sealed class.
- **java-rules**: Java coding rules: style, patterns, security, testing. Triggers: .java, pom.xml, build.gradle, Spring, Spring Boot, JPA, Hibernate, JUnit, Maven, Gradle.
- **json-mode-patterns**: Structured JSON output from Claude: tool-use-as-JSON, schema, parsing, partial recovery. Triggers: JSON mode, structured output, schema validation, JSON parsing.
- **kotlin-patterns**: Kotlin: coroutines, Flow, sealed/data classes, null safety, Ktor, Compose, KMP. Triggers: Kotlin, coroutine, Flow, suspend, Ktor, Jetpack Compose, KMP, kotlinx.
- **kotlin-rules**: Kotlin coding rules: style, patterns, security, testing. Triggers: .kt, .kts, build.gradle.kts, Ktor, Jetpack Compose, coroutines, kotlinx.
- **lint**: Runs linter+typechecker with auto-detected toolchain (ruff/mypy, eslint/tsc, phpstan, golangci-lint, clippy). Triggers: lint, typecheck, static analysis.
- **mcp-builder**: Builds production MCP servers via 4-phase methodology: research, implement, test, evaluate. Triggers: build MCP, new MCP, MCP integration, MCP server scaffold.
- **mcp-patterns**: MCP server design: tool schemas, resources, stdio/SSE, capability negotiation. Triggers: MCP, Model Context Protocol, JSON-RPC, stdio, SSE, Claude Desktop.
- **medplum-rules**: Medplum (FHIR healthcare) coding rules: style, patterns, security, testing. Triggers: medplum.config.mts, medplum.config.ts, FHIR, Medplum, Bot, Subscription, Questionnaire.
- **mem-search**: Searches past coding sessions for observations, decisions, context. Triggers: mem-search, recall session, past work, prior decisions, session history.
- **migrate**: Run/create DB migrations (Alembic, Prisma, Laravel, Django, Flyway, Drizzle); checks backup. Triggers: apply migration, rollback, generate migration.
- **migration-patterns**: Zero-downtime DB migrations: expand-contract, double-write, backfill, blue-green. Triggers: migration, schema change, backfill, ALTER TABLE, online DDL.
- **model-routing-patterns**: Multi-model pipelines (Haiku/Sonnet/Opus): cost routing, escalation, fallback chains. Triggers: model routing, Haiku, Sonnet, Opus, escalation, fallback chain.
- **night-watch**: Autonomous maintenance (dep updates, dead code, small refactors) in isolated branch, off-hours. Triggers: night watch, autonomous maintenance, dep updates.
- **observability-patterns**: Observability: structured logs, metrics (RED/USE), tracing, SLO/SLI. Triggers: logging, metrics, Prometheus, Grafana, OpenTelemetry, trace, monitoring.
- **onboard**: Sets up ai-toolkit in a project: symlinks, CLAUDE.md, intent interview. Triggers: onboard, setup project, install ai-toolkit, migrate project.
- **orchestrate**: Coordinates multiple specialized agents in parallel. Triggers: orchestrate, multi-agent, parallel agents, coordinate agents.
- **panic**: Emergency kill switch — halts all agents via lockfile gate. Triggers: panic, stop everything, kill switch, halt agents, agents looping.
- **performance-profiling**: Performance: golden signals, p50/p95/p99, flame graphs, load testing. Triggers: performance, slow, latency, p99, flame graph, bottleneck, memory leak.
- **persona**: Switches engineering persona at runtime. Triggers: persona, switch role, backend-lead, frontend-lead, devops-eng, junior-dev.
- **php-rules**: PHP coding rules: style, patterns, security, testing. Triggers: .php, composer.json, Laravel, Symfony, PHPUnit, PSR-12, Composer.
- **plan**: Breaks features/goals into phased plans with task lists, agent assignments, dependencies. Triggers: plan feature, implementation roadmap, break down task, project phases.
- **plugin-creator**: Creates opt-in plugin packs with manifests + module scaffolding for Claude/Codex. Triggers: new plugin, plugin pack, plugin scaffold.
- **pr**: Creates GitHub PR after pre-flight checks (lint/typecheck/tests), structured summary from commits. Triggers: pr, pull request, create PR, ready to merge.
- **prd-to-issues**: Splits a PRD into vertical-slice GitHub issues with HITL/AFK tagging and dependencies. Triggers: PRD to issues, create tickets, break down PRD, work items.
- **prd-to-plan**: Converts PRD into phased plan via tracer-bullet vertical slices. Triggers: PRD to plan, break down PRD, implementation plan, tracer bullets, phased plan.
- **predict**: Analyzes diffs for regression risk and blast radius, generates risk-scored impact report. Triggers: PR review, code change risk, breaking change, blast radius, regression check.
- **prompt-caching-patterns**: Anthropic API prompt caching: TTL, breakpoints, stacking, invalidation, hit rate. Triggers: prompt caching, cache_control, cache breakpoint, cache TTL, hit rate.
- **python-rules**: Python coding rules: style, patterns, security, testing. Triggers: .py, .pyi, pyproject.toml, requirements.txt, Pipfile, FastAPI, Django, Flask, pytest, SQLAlchemy, ruff, mypy.
- **qa-session**: Interactive QA: user reports bugs conversationally, agent files GitHub issues. Triggers: QA session, report bug, file issue, conversational QA, bug intake.
- **rag-patterns**: RAG: embeddings, chunking, hybrid search (BM25+vector), reranking, CRAG, multi-hop. Triggers: RAG, embedding, pgvector, Qdrant, Pinecone, Weaviate, reranker, semantic search.
- **refactor**: Refactors code for quality and maintainability. Triggers: refactor, clean up, restructure, improve code, modernize.
- **refactor-plan**: Creates detailed refactor plan with tiny commits via interview, files as GitHub RFC. Triggers: refactor plan, refactoring RFC, incremental refactor, safe steps.
- **repeat**: Runs prompt/slash command on recurring interval until done or limit. Triggers: repeat, recurring task, poll status, run every N minutes, interval.
- **research-mastery**: Hierarchical retrieval: KB → MCP/Context7 → web. Triggers: research, fact-check, verify, synthesize, cross-reference, multi-source, cite sources.
- **review**: Reviews code for quality, security, correctness. Triggers: code review, quality review, security review, review PR, review branch.
- **rollback**: Rolls back git commit, DB migration, or deploy to known-good with safety + health checks. Triggers: rollback, revert deploy, revert migration, rollback commit, git revert.
- **ruby-patterns**: Ruby/Rails: blocks, metaprogramming, ActiveRecord, Sidekiq, RSpec, Sorbet, Hanami. Triggers: Ruby, Rails, ActiveRecord, Sidekiq, RSpec, Gemfile, bundler, Hanami, Sorbet.
- **ruby-rules**: Ruby coding rules: style, patterns, security, testing. Triggers: .rb, Gemfile, .gemspec, Rails, ActiveRecord, Sidekiq, RSpec, Sorbet, rubocop.
- **rust-patterns**: Rust: ownership, lifetimes, async (Tokio), Result/anyhow/thiserror, traits, unsafe. Triggers: Rust, borrow checker, lifetime, Tokio, cargo, trait, impl, Result, unsafe, clippy.
- **rust-rules**: Rust coding rules: style, patterns, security, testing. Triggers: .rs, Cargo.toml, Cargo.lock, Tokio, Axum, Serde, clippy, cargo test.
- **security-patterns**: App security: OWASP, authN/authZ, input validation, secrets, TLS, CSRF/XSS/SQLi, JWT, CSP, LLM prompt injection. Triggers: security, OWASP, auth, JWT, CSRF, XSS, SQL injection, secrets, TLS, CSP, CORS, prompt injection, LLM output trust, tool permissions.
- **seo-validate**: SEO validator: meta/OG, Schema.org, hreflang, Core Web Vitals, crawlability. Triggers: SEO, meta tags, Schema.org, hreflang, LCP, INP, CLS, Core Web Vitals, sitemap, crawlability.
- **skill-audit**: Scans skills/agents for security risks: dangerous patterns, secrets, excessive perms. Triggers: skill audit, security scan, agent audit, dangerous pattern.
- **skill-creator**: Creates new skills from templates via guided workflow. Triggers: new skill, create skill, skill scaffold, skill template.
- **subagent-development**: Executes plans via fresh subagents per task with two-stage review (spec → quality). Triggers: subagent execution, execute plan, fresh agent per task, spec compliance review.
- **swarm**: Runs tasks via Map-Reduce, Consensus, or Relay swarms. Triggers: swarm, map-reduce, consensus swarm, relay swarm, parallel agents.
- **swift-patterns**: Swift/iOS: SwiftUI, Combine, async/await, actors, SPM, Core Data, UIKit interop. Triggers: Swift, SwiftUI, Combine, iOS, Xcode, actor, Core Data, @MainActor, @State.
- **swift-rules**: Swift coding rules: style, patterns, security, testing. Triggers: .swift, Package.swift, .xcodeproj, SwiftUI, Combine, async/await, XCTest.
- **tdd**: TDD with red-green-refactor loop and vertical slices. Triggers: TDD, test-first, red-green-refactor, test driving development.
- **test**: Runs project test suite with coverage, auto-detects framework (pytest, vitest, jest, flutter, go, cargo, phpunit). Triggers: run tests, test suite, coverage report.
- **testing-patterns**: Testing strategy: pyramid, AAA, mocks/fakes/stubs, flaky tests, coverage. Triggers: test, fixture, mock, stub, e2e, TDD, Playwright, Cypress, flaky, coverage, property-based.
- **triage-issue**: Bug triage: explores codebase for root cause, files GitHub issue with TDD fix plan. Triggers: triage, investigate bug, fix plan, root cause, file issue, bug report.
- **typescript-patterns**: TypeScript types: generics, discriminated unions, Zod, satisfies, branded types. Triggers: TypeScript, TS, generics, Zod, satisfies, strict mode.
- **typescript-rules**: TypeScript/JavaScript coding rules: style, patterns, security, testing. Triggers: .ts, .tsx, .js, .jsx, package.json, tsconfig.json, React, Next.js, Vue, Vite, Vitest, Jest, ESLint.
- **ubiquitous-language**: Extracts DDD ubiquitous language glossary, flags ambiguities, saves to UBIQUITOUS_LANGUAGE.md. Triggers: define domain terms, build glossary, harden terminology, DDD, domain model.
- **verification-before-completion**: Forces verification commands before success claims. Evidence before assertions. Triggers: complete, fixed, passing, done, ready, verified.
- **workflow**: Starts and manages autonomous agent workflows. Triggers: workflow, start workflow, autonomous agents, agent pipeline.
- **write-a-prd**: Creates PRD via interactive interview + codebase exploration + module design. Triggers: write PRD, product requirements, plan new feature, PRD interview.

## Agents

- **ai-engineer**: AI/ML integration specialist. Use for LLM integration, vector databases, RAG pipelines, embeddings, AI agent orchestration, document indexing, semantic search, hybrid retrieval, and answer generation. Triggers: ai, ml, llm, embedding, vector, rag, agent, openai, anthropic, search, retrieval, indexing, chunking, reranking.
- **backend-specialist**: Expert backend architect for Node.js, Python, PHP, and modern serverless systems. Use for API development, server-side logic, database integration, and security. Triggers: backend, server, api, endpoint, database, auth, fastapi, express, laravel.
- **business-intelligence**: Opportunity Discovery agent. Scans data models and code to identify missing business metrics, KPIs, and opportunities for value creation.
- **chaos-monkey**: Resilience testing agent. Use to inject faults, latency, and failures into the system to verify robustness and recovery mechanisms.
- **chief-of-staff**: Executive Summary agent. Aggregates reports from all other agents to reduce noise and present a single, actionable daily briefing to the user.
- **code-archaeologist**: Legacy code investigation and understanding specialist. Trigger words: legacy code, code archaeology, dead code, technical debt, dependency analysis, refactoring, code history
- **code-reviewer**: Code review and security audit expert. Use for security reviews, Devil's Advocate analysis, quality audits, best practices validation. Triggers: review, security, audit, quality, best practices, vulnerability.
- **command-expert**: CLI commands and shell scripting specialist. Trigger words: bash, shell, CLI, script, automation, command line, build script, deployment script
- **data-analyst**: Data analysis and visualization expert. Use for SQL queries, data exploration, analytics, reporting, and insights. Triggers: data, analysis, sql, query, visualization, metrics, dashboard, pandas, report.
- **data-scientist**: Statistical analysis and data insights specialist. Use for statistical analysis, data visualization, EDA, A/B testing, and predictive modeling. Triggers: statistics, visualization, eda, analysis, hypothesis testing, ab test.
- **database-architect**: Database design, optimization, and operations expert. Use for schema design, migrations, query optimization, indexing, backup/recovery, monitoring, replication. Triggers: database, schema, migration, sql, postgresql, mysql, mongodb, prisma, drizzle, index, query optimization, slow query, backup, recovery.
- **debugger**: Root cause analysis expert. Use for cryptic errors, stack traces, intermittent failures, silent bugs, and systematic debugging. Triggers: debug, error, exception, traceback, bug, failure, root cause.
- **devops-implementer**: Infrastructure implementation expert. Use for writing Terraform, Ansible, Docker, and shell scripts based on approved architecture notes and implementation summaries. Triggers: terraform, ansible, docker, kubernetes, shell, infrastructure, deployment, configuration.
- **documenter**: Documentation and KB expert. Use for architecture notes, runbooks, changelogs, KB updates, how-to guides, API docs, READMEs, tutorials, SOP creation, KB organization, content quality review. Triggers: document, documentation, architecture-note, runbook, changelog, howto, readme, kb, sop, technical writing.
- **explorer-agent**: Codebase exploration and discovery agent. Use for mapping project structure, finding dependencies, understanding architecture, and research. Does NOT write code - only reads and analyzes.
- **fact-checker**: Claim verification expert. Use for verifying facts, source validation, RAG result accuracy checking. Triggers: fact check, verify, accuracy, claim, source validation.
- **frontend-specialist**: Senior Frontend Architect for React, Next.js, Vue, and modern web systems. Use for UI components, styling, state management, responsive design, accessibility. Triggers: component, react, vue, ui, ux, css, tailwind, responsive, nextjs.
- **game-developer**: Game development across all platforms (PC, Web, Mobile, VR/AR). Use for Unity, Godot, Unreal, Phaser, Three.js. Covers game mechanics, multiplayer, optimization, 2D/3D graphics.
- **incident-responder**: Production incident response expert. Use for P1-P4 incidents, outages, emergency fixes, and postmortem documentation. Triggers: incident, outage, production down, emergency, P1, alert, monitoring.
- **infrastructure-architect**: System design expert. Use for architectural decisions, architecture notes, trade-off analysis, technology selection. Triggers: architecture, design, decision, trade-off, scalability, infrastructure planning.
- **infrastructure-validator**: Deployment validation expert. Use for deployment verification, health checks, testing, rollback procedures. Triggers: validate, deploy, deployment, health check, smoke test, rollback.
- **llm-ops-engineer**: LLM operations expert. Use for LLM caching, fallback strategies, cost optimization, observability, and reliability. Triggers: llm, language model, openai, ollama, caching, fallback, token, cost.
- **mcp-specialist**: MCP server design, implementation, client configuration, and integration troubleshooting. Triggers: mcp, model context protocol, json-rpc, sse, stdio, mcp server, mcp config, mcp integration, mcp connection, claude desktop, mcp client.
- **mcp-testing-engineer**: MCP protocol testing expert. Use for MCP server testing, protocol compliance, transport validation, integration testing. Triggers: mcp test, protocol compliance, mcp validation, transport testing.
- **meta-architect**: Self-Optimization agent. Analyzes system performance and mistakes to update agent definitions and instructions. The only agent allowed to modify .claude/agents/*.
- **ml-engineer**: Machine learning systems specialist. Use for model training, data pipelines, MLOps, and model deployment. Triggers: ml, machine learning, model training, mlops, tensorflow, pytorch, scikit-learn.
- **mobile-developer**: Expert in React Native, Flutter, and native mobile development. Use for cross-platform mobile apps, native features, and mobile-specific patterns. Triggers: mobile, react native, flutter, ios, android, app store, expo, swift, kotlin.
- **night-watchman**: Autonomous maintenance agent. Use for automated dependency updates, dead code removal, refactoring, and project hygiene tasks. Typically scheduled to run off-hours.
- **nlp-engineer**: Natural Language Processing specialist. Use for text processing, NER, text classification, information extraction, and language model fine-tuning. Triggers: nlp, ner, tokenization, text classification, sentiment, spacy, transformers.
- **orchestrator**: Multi-agent coordination and task orchestration. Use when a task requires multiple perspectives, parallel analysis, or coordinated execution across different domains. Invoke for complex tasks benefiting from security, backend, frontend, testing, and DevOps expertise combined.
- **performance-optimizer**: Performance optimization expert. Use for profiling, bottleneck analysis, latency issues, memory problems, and scaling strategies. Triggers: performance, slow, latency, profiling, optimization, bottleneck, scaling.
- **predictive-analyst**: Precognition agent. Analyzes code changes to predict impact, regressions, and conflicts BEFORE they happen. Uses dependency graphs and historical data.
- **product-manager**: Product management and value maximization expert. Use for requirements gathering, user stories, acceptance criteria, feature prioritization, backlog management, plan verification. Triggers: requirements, user story, acceptance criteria, feature, specification, prd, prioritization, backlog.
- **project-planner**: Smart project planning agent. Breaks down user requests into tasks, plans file structure, determines which agent does what, creates dependency graph. Use when starting new projects or planning major features.
- **prompt-engineer**: LLM prompt design and optimization specialist. Trigger words: prompt, LLM, chain-of-thought, few-shot, system prompt, prompt engineering, token optimization
- **qa-automation-engineer**: Test automation and QA specialist. Use for E2E testing, API testing, performance testing, and CI/CD test integration. Triggers: e2e, playwright, cypress, selenium, api test, performance test, automation.
- **search-specialist**: Information retrieval and search optimization specialist. Trigger words: search, query, semantic search, information retrieval, relevance, ranking, search optimization
- **security-architect**: Proactive security design expert. Use for Threat Modeling, architecture security reviews, and designing secure systems (AuthN/AuthZ, Crypto).
- **security-auditor**: Security expert. Use for OWASP Top 10, CVE analysis, security audits, penetration testing, vulnerability assessment, hardening. Triggers: security, owasp, cve, vulnerability, audit, hardening, penetration, pentest, injection test, api security.
- **seo-specialist**: Search engine + generative engine optimization specialist. Trigger words: SEO, GEO, AEO, search engine, meta tags, structured data, Core Web Vitals, sitemap, robots.txt, schema.org, llms.txt, ChatGPT visibility, Claude citation, Perplexity ranking, AI Overviews, topical authority, chunk architecture, semantic triples, query fan out
- **system-governor**: The Guardian of the Constitution. Validates all evolutionary changes and enforces immutable rules. Has VETO power.
- **tech-lead**: Technical authority for code quality, architecture patterns, and stack decisions. Use for code reviews, technological disputes, and standards enforcement.
- **technical-researcher**: Deep technical investigation and multi-source research synthesis specialist. Trigger words: technical research, feasibility study, root cause analysis, API investigation, compatibility research, comparison matrix, synthesize, aggregate, report, executive summary, gap analysis, findings, multi-source, cross-reference
- **test-engineer**: Testing expert. Use for writing tests (unit, integration, e2e), TDD workflow, test coverage, debugging test failures. Triggers: test, pytest, unittest, coverage, tdd, testing, mock, fixture.

---

## kb/best-practices/README.md

---
title: "Best Practices"
service: ai-toolkit
category: best-practices
tags: [best-practices, guidelines]
last_updated: "2026-03-25"
---

# Best Practices

Guidelines and recommendations. Guides will be added here as they are created.

---

## kb/best-practices/no-hardcoded-counts.md

---
title: "No Hardcoded Counts in Secondary Docs"
category: best-practices
service: ai-toolkit
tags: [counts, documentation, maintenance, skills, agents, hooks, tests]
created: "2026-04-07"
last_updated: "2026-04-07"
description: "Counts (skills, agents, hooks, tests) should only appear in README.md and manifest.json. All other docs must NOT contain hardcoded numbers to avoid drift."
---

# No Hardcoded Counts in Secondary Docs

## Rule

Hardcoded counts (skills, agents, hooks, tests, plugins) are allowed ONLY in:
- **README.md** — badges, "What You Get" table, comparison table
- **manifest.json** — module descriptions
- **package.json** — description field

All other files (CLAUDE.md, ARCHITECTURE.md, KB docs, plugin.json, llms.txt, AGENTS.md, copilot-instructions, rules, GEMINI.md) must NOT contain hardcoded counts like "90 skills" or "44 agents".

## Why

Every time a skill, agent, or hook is added/removed, dozens of files need updating. This causes constant drift and stale counts that erode trust. Consolidating to 2-3 files makes maintenance tractable.

## How to Apply

- In secondary docs, use relative language: "all agents", "the full skill set", "available hooks"
- If a doc MUST reference scale, use: "see README.md for current counts"
- `validate.py` checks counts only in README.md badges — that's sufficient
- When adding skills/agents/hooks, update ONLY: README.md badges + manifest.json descriptions

## Anti-Pattern

```markdown
# BAD — hardcoded count in ARCHITECTURE.md
Shared AI development toolkit — 90 skills, 44 agents

# GOOD — no count
Shared AI development toolkit with multi-platform support
```

---

## kb/history/completed/deep-coverage-v3-20260423.md

---
title: "Plan: Deep Coverage v3.0 — 100% Native Surface Utilization Across 12 Tools"
category: planning
service: ai-toolkit
doc_type: plan
status: completed
tags: [v3, deep-coverage, ecosystem, generators, hooks, skills, subagents, commands, profile-full]
created: "2026-04-23"
last_updated: "2026-04-23"
completed: "2026-04-23"
completion: "100%"
description: "Ship v3.0.0 where every supported editor exposes the full ai-toolkit surface it is capable of hosting natively: hooks, subagents, custom commands, skill pointers. Introduce --profile full. Skip the 2.13.0 interim release and fold the completed deep sweep into 3.0.0."
---

# Plan: Deep Coverage v3.0 — 100% Native Surface Utilization

**Status:** :yellow_circle: IN PROGRESS
**Invocation:** continuation of `ecosystem-deep-sweep-2026-04-23` — same orchestration model
**Estimated effort:** 10-15h orchestrated (~3h wall-clock across 4 parallel buckets + consolidation)
**Deliverable:** v3.0.0 release where every editor's native surface is fully utilized; `--profile full` available

---

## 1. Objective

After the 2026-04-23 deep sweep closed the doc-drift gap, **v3.0.0 closes the capability-utilization gap**: each editor now exposes the full ai-toolkit surface it can host natively.

Definition of "100% coverage" chosen: **each editor works at 100% of its native capability** (compat-read counts). No cargo-cult duplication. No writing to `~/.cursor/`, `~/.augment/rules/` etc. globally.

---

## 2. Policy decisions (immutable constraints for all buckets)

| # | Decision | Rule |
|---|----------|------|
| 1 | Skill propagation | `.claude/skills/` canonical. Cursor/Windsurf/opencode → compat-read (nothing). Augment/Gemini/Antigravity → **pointer skill** (1 file per editor). Codex → native `.agents/skills/` mirror |
| 2 | Global writes | Only `~/.claude/`. Cursor/Windsurf/opencode get global coverage via compat-read. Augment/Gemini/Roo require `--local` |
| 3 | Surface activation | **`--profile full`** turns on every native surface. `standard` stays close to today's defaults but adds niepodważalne wypełnienia (Copilot wiring + Gemini hooks). `minimal` unchanged |
| 4 | Default behavior | `--editors <name>` alone uses `standard`. Users who want the full stack pass `--profile full` |
| 5 | Version | Skip 2.13. Ship everything (completed sweep + v3 work) as **3.0.0** with migration notes |

---

## 3. What's missing → what each bucket delivers

### Bucket 1 — Hooks generators (backend-specialist)

**Owned files**
- New: `scripts/generate_gemini_hooks.py` (writes `.gemini/settings.json` hooks merge)
- New: `scripts/generate_cursor_hooks.py` (writes `.cursor/hooks.json`)
- New: `scripts/generate_windsurf_hooks.py` (writes `.windsurf/hooks.json`)
- New: `scripts/generate_augment_hooks.py` (writes `~/.augment/settings.json` hooks merge)
- New: `tests/test_hooks_per_editor.bats` (≥20 tests covering all 4 generators)

**Must-haves**
- All generators reuse `~/.softspark/ai-toolkit/hooks/*.sh` scripts (no duplicate shell code).
- Preserve user-authored hook entries; mark our entries with `_source: ai-toolkit`.
- Idempotent on regeneration.
- Event mapping informed by each editor's docs (Claude Code events ↔ target editor events).

### Bucket 2 — Native agents + custom commands (ai-engineer)

**Owned files**
- New: `scripts/generate_augment_agents.py` (`.augment/agents/*.md` with YAML frontmatter: name, description, model, color, tools, disabled_tools)
- New: `scripts/generate_augment_commands.py` (`.augment/commands/*.md` from user-invocable skills)
- New: `scripts/generate_cursor_agents.py` (`.cursor/agents/*.md` mirroring Claude Code agents)
- New: `scripts/generate_gemini_commands.py` (`.gemini/commands/*.toml` custom slash commands)
- New: `tests/test_native_surfaces.bats` (≥25 tests)

**Must-haves**
- Filter: only `user-invocable: true` skills become custom commands.
- `ai-toolkit-*` prefix everywhere for install/uninstall sweep.
- Do not touch files without our prefix.

### Bucket 3 — Skill pointers + Codex mirror (ai-engineer)

**Owned files**
- New: `scripts/generate_gemini_skills.py` (`.gemini/skills/ai-toolkit-skill-catalogue/SKILL.md` — pointer)
- New: `scripts/generate_augment_skills.py` (`.augment/skills/ai-toolkit-skill-catalogue/SKILL.md` — pointer)
- New: `scripts/generate_codex_skills.py` (Codex-native mirror to `.agents/skills/<name>/SKILL.md`)
- New: `tests/test_skills_native.bats` (≥15 tests)

**Must-haves**
- Pointer pattern same as Antigravity: 1 file per editor referencing `~/.claude/skills/<name>` and listing the catalogue.
- Codex mirror respects `user-invocable: false` (knowledge skills stay, task skills stay — Codex reads them all).
- Codex skills use the upstream `.agents/skills` discovery path.

### Bucket 4 — Install wiring + profile full + docs (devops-implementer)

**Owned files**
- `scripts/install_steps/ai_tools.py` — wire in all new generators from buckets 1-3
- `scripts/install.py` — parse `--profile full`, propagate to `_create_local_ai_tool_configs`
- `scripts/config_validator.py` — ensure `full` profile is accepted (already present, verify)
- `README.md` — "What's New in v3.0.0" + migration notes
- `CHANGELOG.md` — v3.0.0 entry
- `kb/reference/global-install-model.md` — document profile semantics
- `kb/reference/supported-tools-registry.md` — per-tool "generators by profile" column
- `kb/procedures/maintenance-sop.md` — profile table update
- `package.json` version bump → `3.0.0`
- `package-lock.json` sync
- `tests/test_install_profiles.bats` (≥15 tests covering minimal/standard/strict/full × 3 editors)

**Must-haves**
- `standard` profile: Copilot directory mode ON, Gemini hooks ON (non-breaking additions).
- `full` profile: everything from `standard` + all native surfaces from buckets 1-3.
- Migration note: users on `standard` today get Copilot instructions/prompts and Gemini hooks automatically after upgrading (acceptable breaking for major bump, documented).

---

## 4. Success criteria

- [ ] 13 new Python generators (6+4+3, minus wiring)
- [ ] ≥75 new bats tests across buckets
- [ ] `npm test` green
- [ ] `python3 scripts/validate.py --strict` 0/0
- [ ] `python3 scripts/ecosystem_doctor.py --check` exit 0
- [ ] `ai-toolkit install --local --editors all --profile full` produces every native surface per editor
- [ ] `ai-toolkit install --local --editors all --profile standard` is still minimal-invasive (no subagents, no hooks for non-Claude editors) **except** Copilot + Gemini hooks (both documented migration notes)
- [ ] README test badge bumped
- [ ] CHANGELOG v3.0.0 entry
- [ ] All docs updated (registry, install model, maintenance SOP)
- [ ] Single atomic commit
- [ ] Tag `v3.0.0` ready (push held for user confirmation)

---

## 5. Safety rails

- **Do not commit during bucket work.** Orchestrator consolidates.
- **Do not touch files outside your bucket's ownership list.**
- **Preserve user files** via `ai-toolkit-*` prefix on generated artifacts.
- **Do not write to global editor paths** (`~/.cursor/`, `~/.augment/rules/`, etc.) — policy decision 2.
- **Do not change `standard` profile in ways that break existing users**, beyond the two documented additions (Copilot directory mode + Gemini hooks).
- **Test per bucket locally before reporting.** Bucket reports must include a "tests green" line.

---

## 6. Consolidation steps (orchestrator)

1. Merge all 4 bucket registry deltas into `scripts/ecosystem_tools.json`
2. Run `python3 scripts/ecosystem_doctor.py --update`
3. Run `npm run generate:all`
4. Bump `package.json` → `3.0.0`; sync `package-lock.json`
5. Update `README.md` badge + "What's New"
6. Update `CHANGELOG.md` with v3.0.0 entry (include migration notes)
7. Run `python3 scripts/validate.py --strict` (must pass 0/0)
8. Run `npm test` (all green)
9. Run `python3 scripts/ecosystem_doctor.py --check` (exit 0)
10. Move this plan doc to `kb/history/completed/deep-coverage-v3-20260423.md`
11. Single commit + tag `v3.0.0`
12. Hold push pending user confirmation

---

## 7. Related

- `kb/history/completed/ecosystem-deep-sweep-20260423.md` — predecessor plan (doc-drift closure)
- `kb/reference/global-install-model.md` — install scope semantics
- `kb/reference/supported-tools-registry.md` — tool registry
- `scripts/config_validator.py` — `VALID_PROFILES` already includes `full`

---

## kb/history/completed/drop-cascade-hooks-after-sunset-20260710.md

---
title: "Plan: Drop Cascade hooks after 2026-07-01 sunset"
category: planning
service: ai-toolkit
tags:
  - windsurf
  - devin
  - cascade
  - hooks
  - deprecation
  - cleanup
doc_type: plan
status: completed
created: "2026-06-10"
last_updated: "2026-07-10"
completion: "100%"
trigger_date: "2026-07-01"
description: "Completed cleanup of the deprecated Windsurf Cascade hooks generator after the 2026-07-01 sunset; Devin CLI .devin/hooks.v1.json is now the sole live hook surface."
---

# Plan: Drop Cascade hooks after 2026-07-01 sunset

**Completed in v4.13.0 (2026-07-10).** The deprecated generator and install/test wiring were removed; the Devin hook generator remains.

> **Filed to history 2026-07-27.** The plan was finished in v4.13.0 but sat in
> `kb/planning/` for another two and a half weeks, where it read as open work.
> Before moving it, every claim in the Verification section below was re-run
> against the codebase:
>
> | Check | Result |
> |---|---|
> | `scripts/generate_windsurf_hooks.py` deleted | gone |
> | `grep -rn generate_windsurf_hooks scripts/ tests/` | no source references (one stale `.pyc` under gitignored `__pycache__`) |
> | `_HOOK_STEM_ALIAS = {"devin": "windsurf"}` retained in `validate.py` | present, line 882 |
> | windsurf `our_generators` in `scripts/ecosystem_tools.json` | Cascade generator absent, `generate_devin_hooks.py` present |
> | `kb/reference/supported-tools-registry.md` hooks-migration row | reads "Complete" in past tense |
> | `validate.py --strict` | 0 errors, 0 warnings |
>
> The work was real and complete. Only the filing was wrong.
>
> **Process note.** This is the second document found misfiled in
> `kb/planning/` on the same day; the other,
> [`mcp-context-trim-v4-prd-obsoleted-20260727.md`](mcp-context-trim-v4-prd-obsoleted-20260727.md),
> had gone obsolete because the platform shipped the fix first. A plan with a
> `trigger_date` needs a matching move-to-history step in the release that acts
> on it — otherwise `kb/planning/` accumulates work that is already done or no
> longer worth doing, and the next reader cannot tell which is which.

## Why this exists

Windsurf rebranded to Devin Desktop on 2026-06-02. The Cascade agent — and its
`.windsurf/hooks.json` hook surface (`agent_action_name`/`tool_info` format) — is
available **only through 2026-07-01**. Devin Local / Devin CLI do **not** read
`.windsurf/hooks.json` as a fallback.

v4.8.0 already shipped the replacement: `generate_devin_hooks.py` emits
`.devin/hooks.v1.json` in the Claude-compatible format Devin CLI uses. During the
transition **both** generators run at `profile=full` so pre-sunset Cascade users
keep working. After 2026-07-01 the Cascade half is dead code and must be removed
(Constitution Art. VI.1 — no dead code).

## Trigger

First ai-toolkit release **on or after 2026-07-01**. Do NOT do this earlier —
removing it before the sunset breaks Cascade users who are still on the old agent.

## Scope — remove the Cascade hooks surface

1. **Delete the generator:** `scripts/generate_windsurf_hooks.py`.
2. **Unwire the install step:** in `scripts/install_steps/ai_tools.py`, remove the
   `_try_generator("generate_windsurf_hooks", cwd)` call (keep
   `generate_devin_hooks`). Update the `profile=full` dry-run message to drop
   `.windsurf/hooks.json (Cascade, deprecated)`.
3. **Tests:** remove the windsurf-`.windsurf/hooks.json` cases from
   `tests/test_hooks_per_editor.bats` (output path, valid JSON, source tag,
   `$HOME` prefix, idempotence, user-preservation, `pre_write_code` coverage) and
   the `profile=full` assertion in `tests/test_install_profiles.bats`
   (`windsurf + full emits .windsurf/hooks.json`). Keep all `.devin/hooks.v1.json`
   tests. Adjust the README test-count badge to the new total.
4. **Registry:** in `scripts/ecosystem_tools.json` (windsurf entry), remove
   `scripts/generate_windsurf_hooks.py` from `our_generators`; keep
   `.windsurf/hooks.json` out of `config_paths` (it was never listed). Trim the
   `status_note` hooks-migration paragraph to past tense ("Cascade hooks removed
   in vX.Y.Z").
5. **Docs:** in `kb/reference/supported-tools-registry.md` drop the
   `generate_windsurf_hooks.py` row and the "drop after 2026-07-01" note; in
   `kb/reference/hooks-catalog.md` remove the Cascade row from the
   Per-Editor Native Hooks table and the deprecation wording, leaving the Devin CLI
   section as the windsurf-family hook surface.
6. **validate.py:** the `_HOOK_STEM_ALIAS = {"devin": "windsurf"}` mapping STAYS —
   it is what keeps the `devin` hook generator counted as windsurf hooks in the
   README-honesty check after the Cascade generator is gone.
7. **CHANGELOG / version:** minor bump, `Removed` entry, regen artifacts, full
   release-preparation SOP gate.

## Verification

- `python3 scripts/validate.py --strict` — 0/0 (editor-hooks-honesty must still
  report windsurf as hook-enabled via the `devin` generator alias).
- `python3 scripts/ecosystem_doctor.py --offline --check` — exit 0.
- `npm test` — 0 `not ok`; no test recreates the deleted
  `generate_windsurf_hooks.py` generator.
- `grep -rn "generate_windsurf_hooks" scripts/ tests/` returns nothing
  (Art. VI.1 orphan check — the deleted generator is fully unwired).
  `.windsurf/hooks.json` intentionally remains referenced by the one-time
  migration/strip cleanup (`scripts/install_steps/ai_tools.py`) and its test,
  and in narrative docs (CHANGELOG, README, `kb/`, docstrings).

## Do NOT touch

- `generate_devin_hooks.py` and `.devin/hooks.v1.json` — the live replacement.
- The `.devin/`/`.windsurf/` rules + skills dual-emit (that fallback persists as
  long as Devin Desktop reads legacy `.windsurf/` paths; this plan is hooks-only).

## Related

- `kb/reference/hooks-catalog.md` — Per-Editor Native Hooks + Devin CLI section
- `kb/reference/supported-tools-registry.md` — windsurf entry, hooks-migration row
- `kb/procedures/ecosystem-sync-sop.md` — class-D deprecation workflow
- `scripts/ecosystem_tools.json` — windsurf `status_note`

---

## kb/history/completed/ecosystem-deep-sweep-20260423.md

---
title: "Plan: Ecosystem Deep Sweep — All 12 Supported Tools"
category: planning
service: ai-toolkit
doc_type: plan
status: completed
tags: [ecosystem, editors, generators, deep-sweep, orchestrate, drift, integration]
created: "2026-04-23"
last_updated: "2026-04-23"
completed: "2026-04-23"
completion: "100%"
description: "Orchestrate-ready plan for a deep per-tool documentation sweep across all 12 supported tools (Claude Code + 11 editors). Each agent owns 2-3 tools: fetches docs, diffs against our generators, proposes minimal patches. Consolidation step collects results into a single changeset."
---

# Plan: Ecosystem Deep Sweep — All 12 Supported Tools

**Status:** :yellow_circle: PROPOSED
**Invocation:** `/orchestrate deep ecosystem sweep per kb/planning/ecosystem-deep-sweep-2026-04-23.md`
**Estimated effort:** 4-6 hours orchestrated (1-1.5 h per agent in parallel)
**Deliverable:** Per-tool drift report + concrete generator/skill patches + updated registry

---

## 1. Objective

For every supported tool in `scripts/ecosystem_tools.json`:

1. Read the current official documentation end-to-end (not just landing page)
2. Identify every feature that ai-toolkit could integrate with but does not currently
3. Classify each gap using the ecosystem-sync SOP taxonomy (class A-F)
4. Produce minimal, reviewable patches for class B/D/E/F gaps
5. Update the registry (`ecosystem_tools.json`) with new capability markers and config paths
6. Refresh the snapshot (`benchmarks/ecosystem-doctor-snapshot.json`)

**Explicit non-goals:** complete feature parity, deep refactor of generators, adding new editors to the roster.

---

## 2. Parallelization Strategy

12 tools → **4 agents × 3 tools each** by affinity and complexity:

| Agent | Role | Tools | Rationale |
|-------|------|-------|-----------|
| `backend-specialist` | Deep CLI / config analysis | `claude-code`, `codex-cli`, `opencode` | CLI + config.toml + agents/commands/plugins — backend integration depth |
| `frontend-specialist` | Editor UI integrations | `cursor`, `windsurf`, `google-antigravity` | Editor-embedded AI, rule files, MCP-via-UI |
| `devops-implementer` | Pipeline + rules tools | `github-copilot`, `cline`, `roo-code` | Rules directories, MCP JSON variants, mode configs |
| `ai-engineer` | LLM-native tools | `gemini-cli`, `aider`, `augment` | Pure LLM workflows, minimal IDE coupling |

Each agent works **in parallel**, independent file scopes (different generators). Cross-file coordination only at the registry update (single JSON file).

---

## 3. Per-Tool Task Template

Every agent applies the **same 7-step protocol** per tool in their bucket:

### Step 1 — Baseline our current integration

Read these files (read-only):
- `scripts/generate_<tool>_*.py` — every generator targeting this tool
- `scripts/ecosystem_tools.json` — the tool's registry entry
- `kb/reference/supported-tools-registry.md` — human docs section
- `benchmarks/ecosystem-doctor-snapshot.json` — last-seen headings/markers/version

Produce a 3-line summary: "we currently generate X, Y, Z for this tool".

### Step 2 — Fetch official docs

Primary URL is in `ecosystem_tools.json::urls.docs`. Additionally fetch:
- `urls.release_notes` — recent changes (last 6 months)
- `urls.changelog` — if distinct from release notes
- Any deep-link from the docs landing page that corresponds to an integration surface (rules, hooks, MCP, agents, commands, plugins, config schema)

Use `WebFetch` (for general) or `gh api` (for GitHub-hosted docs like Codex CLI, opencode).

### Step 3 — Extract the feature surface

For the current version of the tool, enumerate:
- Config file paths (the tool's OWN paths, not ours)
- Rule / instruction / prompt formats
- Hook / lifecycle event names (if any)
- MCP config target path (if supported)
- Agent / custom-mode / preset concepts (if any)
- Slash command / CLI subcommand surface
- Supported model providers (note, do not integrate)
- Authentication / API-key mechanisms

Produce a structured markdown table: `Feature | Since version | Stable? | Our integration?`

### Step 4 — Diff against our output

For each feature in the table, compare against:
- What our `generate_<tool>_*.py` produces
- What fields are in our registry's `capability_markers`

Mark each row with one of:
- `✅ supported` — we already emit / track it
- `⚠️ partial` — we emit a subset; specific sub-feature missing
- `❌ missing` — we do not support at all
- `➖ out of scope` — tool has it, but not applicable to ai-toolkit's mission

### Step 5 — Classify each gap

For each `⚠️` / `❌` row, assign one of the SOP drift classes:

| Class | Name | Action |
|-------|------|--------|
| A | Cosmetic | No code change; update snapshot only |
| B | New feature — integrate | Patch generator(s), add tests |
| C | New feature — not adopted | Note in registry, no code |
| D | Deprecation | Migration warning in generator + CHANGELOG |
| E | Feature promoted to default | Simplify generator; keep fallback comment |
| F | Newly globally available | New generator / extended generator |

### Step 6 — Produce patches (class B/D/E/F only)

For every class B/D/E/F gap:
1. Edit the relevant generator in `scripts/generate_<tool>_*.py`
2. If a new capability marker emerges, add to `ecosystem_tools.json::capability_markers`
3. If a new config path emerges, add to `ecosystem_tools.json::config_paths`
4. If a hook event or skill frontmatter field emerges (for Claude Code), update:
   - `app/skills/hook-creator/SKILL.md` (hooks table)
   - `app/skills/skill-creator/SKILL.md` (frontmatter reference)
   - `scripts/validate.py` (allowlist)
5. Add a bats test under `tests/test_<tool>.bats` covering the new output
6. Update the tool's section in `kb/reference/supported-tools-registry.md`

**Constraints on patches:**
- One generator change per logical feature (no "big bang" commits)
- Preserve existing output format for backward compatibility
- New output opt-in via flag if it would change existing user-visible state
- Every new capability marker must pass the doctor's probe on the live docs page

### Step 7 — Report

Each agent emits a single markdown report with:
- Feature matrix table (step 3+4+5 combined)
- List of patches applied (files changed, bats tests added)
- List of class B/D/E/F gaps NOT patched (with reason: "out of scope", "requires user decision", "blocker")
- Registry diff (before/after for the tool's JSON entry)

---

## 4. Consolidation (after all agents finish)

Run in order:

1. Merge registry entries — single edit to `ecosystem_tools.json` combining all 12 per-tool updates
2. Regenerate human registry doc: manually update `kb/reference/supported-tools-registry.md` from JSON
3. `python3 scripts/ecosystem_doctor.py --update` — baseline new capability markers
4. `python3 scripts/validate.py --strict` — must pass
5. `npm test` — must pass (includes the newly added bats tests per tool)
6. `python3 scripts/ecosystem_doctor.py --check` — exit 0
7. Regenerate downstream artifacts:
   ```bash
   npm run generate:all
   ```
8. Collect all per-agent reports into `kb/learnings/ecosystem-sweep-2026-04-23.md`

---

## 5. Success Criteria

- [ ] All 12 tools covered (no "skipped for time" items)
- [ ] Every class B/D/E/F gap has either a patch OR a documented reason for deferral
- [ ] Registry `capability_markers` list grew for at least 6 of 12 tools (signals real gap coverage)
- [ ] `validate.py --strict`: 0 errors, 0 warnings
- [ ] `npm test`: all green (including new per-tool bats tests)
- [ ] `ecosystem_doctor.py --check`: exit 0 after snapshot refresh
- [ ] Single consolidated commit per agent-bucket, plus one final consolidation commit

---

## 6. Known Traps (from prior ecosystem work)

- **SPA docs** (Cursor, Antigravity, some Augment pages): `urllib` gets empty HTML skeleton. Agents should note this and do a **manual browser visit** or use a JS-aware fetcher. Do not treat "0 headings" as "nothing new".
- **GitHub docs** rate-limit aggressively on repeated reads. Space out fetches or use `gh api`.
- **Feature gates** vary by user plan. Copilot Business vs Individual vs Enterprise have different surface. Integrate with the OSS surface; document gated features as C (not adopted).
- **Version skew** on config schemas. A setting that existed in v1.x may be deprecated in v2.x. When docs reference "available since v1.5" and we don't know what version users run, default to generating the newer form with a comment.
- **Markdown vs MDX**: Cursor uses `.mdc`, Claude Code uses `.md`, Cline uses `.md` in `.clinerules/`, Roo uses `.md` in `.roo/rules/`. Don't assume one format fits all.

---

## 7. Orchestrate Invocation

In a fresh Claude Code session (to avoid context rot from this session):

```
/orchestrate deep ecosystem sweep for ai-toolkit per kb/planning/ecosystem-deep-sweep-2026-04-23.md

Spawn 4 agents in parallel:
- backend-specialist: claude-code, codex-cli, opencode
- frontend-specialist: cursor, windsurf, google-antigravity
- devops-implementer: github-copilot, cline, roo-code
- ai-engineer: gemini-cli, aider, augment

Each agent follows the 7-step per-tool protocol in section 3.
After all 4 report, run consolidation (section 4) and produce the sweep summary.
```

---

## 8. Deliverables (per agent)

Each agent's final output to orchestrator:
1. **Feature matrix** — one table per assigned tool (step 3+4+5)
2. **Patch log** — list of commits staged (not committed yet — orchestrator consolidates)
3. **Registry delta** — proposed JSON diff for `ecosystem_tools.json`
4. **Gaps not patched** — with rationale (out-of-scope, blocker, deferred)
5. **Test additions** — bats test file names + test count

Orchestrator's final output:
1. Consolidated commit with message `feat(ecosystem): deep sweep 2026-04-23 — N class B/F integrations`
2. Version bump decision (minor if any class B/F, patch if only class A updates)
3. `kb/learnings/ecosystem-sweep-2026-04-23.md` — retrospective noting which tools needed most work (informs priority for next sweep)

---

## 9. Safety Rails

- **Do not** silently upgrade default behavior — every user-visible change lands behind a flag OR goes through a minor version bump with CHANGELOG mention
- **Do not** rewrite generators wholesale — incremental additions only
- **Do not** commit during the sweep — orchestrator consolidates at the end
- **Do not** modify files outside the tool's scope (e.g., backend-specialist touching frontend-specialist's files requires a handoff)
- **Do** preserve existing symlinks and file-path expectations — the installer depends on them

---

## 10. Related

- [Ecosystem Sync SOP](../procedures/ecosystem-sync-sop.md) — the process this plan instantiates
- [Supported Tools Registry](../reference/supported-tools-registry.md) — source of truth for tool list
- `scripts/ecosystem_doctor.py` — drift detector consumed by orchestrator consolidation
- `scripts/ecosystem_tools.json` — registry file edited by every agent

---

## 11. Retrospective — 2026-04-23

### Execution summary

- 4 parallel agents, 3 tools each — full 12/12 coverage, one consolidation pass.
- 161 new bats tests (679 → 840); validate.py 0 errors / 0 warnings; `ecosystem_doctor --check` exit 0.
- 14 files modified, 12 new test files, 2 registry docs updated, 1 snapshot rebaselined.

### What worked

- **Bucket-level file ownership** eliminated merge conflicts entirely. Agents that flagged cross-bucket edits (`ecosystem_tools.json`, registry markdown) correctly left them for the orchestrator.
- **The 7-step protocol** caught high-impact bugs we would have shipped otherwise — Windsurf rules missing `trigger:` frontmatter (silent invisibility to Cascade), Aider's default `attribute-co-authored-by: true` violating our own git policy, Roo modes lacking `whenToUse` (invisible to Orchestrator).
- **SPA-wall compensation patterns** (Antigravity bundle strings, Cursor/Windsurf llms.txt mirrors, GitHub release notes as fallback) were reusable across buckets.

### What surprised us

- **Claude Code 2.1.x grew ~14 new hook events** and 3 new handler types since our last sync. Our validate.py allowlist was the bottleneck, not any generator.
- **Cross-editor compat reads**: Cursor, Windsurf, and opencode now natively read `.claude/skills/` and `.claude/agents/` — we get skill/agent discovery in those editors "for free" without emitting duplicates. Saved ~300 generated files.
- **Copilot tier-gating is heavy**: half of the upstream surface (custom agents, repo MCP, org instructions) is Business/Enterprise-only and was classified as C (documented non-integration).
- **Test #755 regression** from the Codex `PermissionRequest` addition: the test counted `guard-destructive.sh` occurrences with `== 1`. Fixed by updating the expected count to 2 with a comment explaining why base hooks legitimately register it twice now.

### Open items flagged for future passes

1. **Native `.agents/skills/*/SKILL.md` emission** (class B) — writes the Codex skill catalog to the upstream discovery path.
2. **`.opencode/skills/` duplication** — deferred indefinitely; `.claude/skills/` fallback already works.
3. **New generators needed**: `generate_gemini_hooks.py`, `generate_augment_agents.py`, `generate_augment_commands.py`, `generate_augment_hooks.py`.
4. **Cross-editor hooks unification**: Cursor and Windsurf both shipped `.cursor/hooks.json` and `.windsurf/hooks.json` — worth a dedicated shared-schema pass rather than per-editor copies.
5. **Roo `.roomodes` YAML variant** — upstream-preferred; deferred until a YAML multi-line helper is added.
6. **Copilot install wiring**: new `.github/instructions/` and `.github/prompts/` directories are emitted when `generate_copilot.py` is called with a target dir, but `install_steps/ai_tools.py` doesn't invoke that path yet. Wire behind minor bump.

### Process refinements for next sweep

- **Add a "class B/F deferred" register**: buckets produced these ad-hoc; a structured list in the plan would make prioritization for the next sweep trivial.
- **Cross-bucket test impact**: adding per-tool bats tests inflates the test count and trips the README badge validator. Next time, bump the badge at the start of consolidation, not at the end.
- **Search docs via llms.txt first** when the vendor publishes one — bypasses SPA walls with zero fallback logic.

---

## kb/history/completed/enterprise-config-inheritance-plan-20260412.md

---
title: "Plan: Enterprise Config Inheritance — Multi-Repo Governance with extends"
category: planning
service: ai-toolkit
tags:
  - enterprise
  - multi-repo
  - config-inheritance
  - extends
  - governance
  - team-management
  - monorepo
doc_type: plan
status: completed
created: "2026-04-10"
last_updated: "2026-04-11"
completion: "100%"
description: "Configuration inheritance system for ai-toolkit. Enables organizations to define a shared base config (agents, rules, hooks, profiles, constitution overrides) published as an npm package or local path, which individual projects extend via an `extends` field. Changes to the base config propagate automatically on `ai-toolkit update`. Targets enterprises managing 10-100+ repositories with uniform AI governance."
---

# Plan: Enterprise Config Inheritance — Multi-Repo Governance with `extends`

**Status:** Proposed
**Completion:** 0%
**Created:** 2026-04-10
**Origin:** Organizations adopting ai-toolkit across 10-100+ repositories face a config synchronization problem — updating a rule or policy requires touching every repository individually. The `extends` pattern (popularized by ESLint, TypeScript, Prettier) solves this by establishing a single source of truth that projects inherit from.
**Estimated Effort:** 5-7 weeks (1 person) — MVP (core engine + install integration) shippable in ~3.5 weeks

---

## 1. Objective

Create a configuration inheritance system where projects can extend a shared base config published as an npm package, a Git URL, or a local path. The base config defines organizational defaults (which agents to enable, which rules to enforce, which hooks to require, persona presets, and constitution amendments). Individual projects can override or supplement the base, creating a layered governance model.

**Key design principles:**
- **Familiar pattern** — mirrors ESLint's `extends`, TypeScript's `extends`, and Prettier's shared configs
- **npm-first distribution** — base configs are regular npm packages (e.g., `@mycompany/ai-toolkit-config`). Resolver shells out to `npm pack` CLI (respects `.npmrc` auth) — no hand-rolled npm client, preserves stdlib-only constraint
- **Single extends in v1** — `"extends": "string"` only. Multi-base merge (`"extends": [...]`) deferred to v2 to avoid merge-ordering complexity (ESLint's multi-extends is a known source of confusion)
- **Layered merge** — base → project, with explicit override semantics (`override: true` required for safety-critical overrides)
- **Constitution immutable** — base constitution articles cannot be modified by projects, period. Projects can only ADD new articles (article 6+). No weakening detection heuristics — absolute immutability is simpler and safer
- **Offline-capable** — resolved at `install`/`update` time, not at runtime
- **Backward-compatible** — projects without `extends` work exactly as today (no breaking changes)
- **Audit trail** — `state.json` records which base config was resolved and what was overridden

---

## 1a. Functional Requirements

| ID | Requirement | Priority | Success Metric |
|----|-------------|----------|----------------|
| FR1 | Resolve `extends` from npm package, git URL, local path | Must | 4 source types work |
| FR2 | Deep merge base → project config with layered semantics | Must | Merge engine handles dict, list, scalar types |
| FR3 | Constitution immutability — Articles I-V cannot be modified | Must | 100% block rate on modification attempts |
| FR4 | Override validation with `override: true` + `justification` | Must | Missing justification → error |
| FR5 | `enforce` block constraints (minHookProfile, requiredPlugins, forbidOverride, requiredAgents) | Must | All 4 constraint types enforced |
| FR6 | Install/update integration — resolve extends during install | Must | `install --local` detects `.softspark-toolkit.json` |
| FR7 | `config diff` command — show project vs base differences | Must | All merge layers visible |
| FR8 | `config validate` command — schema + enforcement validation | Must | Exit 0/1 for pass/fail |
| FR9 | `config init` — interactive project config setup | Should | Guided flow produces valid `.softspark-toolkit.json` |
| FR10 | `config create-base` — scaffold npm base config package | Should | Ready-to-publish package with `package.json` |
| FR11 | Lock file for reproducible installs | Should | Identical resolved config across team members |
| FR12 | Audit trail in `state.json` | Should | Resolved version + overrides recorded |
| FR13 | CI enforcement command (`config check`) | Could | Exit 0/1 for governance compliance |
| FR14 | Multi-base extends (`"extends": [...]`) | Won't (v2) | Deferred — merge ordering complexity |

---

## 2. Architecture Overview

```
Organization Level (published once, consumed by all repos):
═══════════════════════════════════════════════════════════

  @mycompany/ai-toolkit-config (npm package)
  ├── ai-toolkit.config.json       ← base configuration
  ├── rules/
  │   ├── code-review-policy.md    ← company-specific rules
  │   └── deployment-checklist.md
  ├── agents/
  │   └── compliance-auditor.md    ← company-specific agent
  └── package.json

Project Level (per-repository):
══════════════════════════════

  my-service/
  ├── .softspark-toolkit.json             ← project config with "extends"
  ├── .claude/
  │   ├── CLAUDE.md                ← generated (base + project merged)
  │   └── settings.json            ← generated (base hooks + project hooks merged)
  └── ...

Merge Pipeline:
══════════════

  @mycompany/ai-toolkit-config     ← Layer 0: organizational defaults
          │
          ▼
  ai-toolkit defaults (manifest.json) ← Layer 1: toolkit defaults
          │
          ▼
  .softspark-toolkit.json                  ← Layer 2: project overrides
          │
          ▼
  Resolved Configuration             ← Final: CLAUDE.md, settings.json, etc.
```

### Config Resolution Order

```
1. Load base config from "extends" (npm package, git URL, or local path)
2. Merge with ai-toolkit defaults (manifest.json profiles)
3. Apply project-level overrides from .softspark-toolkit.json
4. Validate merged config (constitution immutability, schema validation)
5. Generate output files (CLAUDE.md, settings.json, agent symlinks, etc.)
```

---

## 3. Progress Tracking

| # | Feature | Priority | Status | Est. Time | Notes |
|---|---------|----------|--------|-----------|-------|
| 1.1 | `.softspark-toolkit.json` schema definition | P0 | **Done** | 1d | `scripts/schemas/ai-toolkit-config.schema.json` |
| 1.2 | Config resolver (npm, git, local path) | P0 | **Done** | 3d | `scripts/config_resolver.py` (~330 LOC) |
| 1.3 | Merge engine (layered merge with override semantics) | P0 | **Done** | 3d | `scripts/config_merger.py` (~340 LOC) |
| 1.4 | Constitution immutability guard | P0 | **Done** | 1d | In config_merger.py `_merge_constitution()` |
| 2.1 | Install/update integration | P0 | **Done** | 2d | `install.py` + `ai_tools.py` — auto-detect, resolve, merge, inject |
| 2.2 | `ai-toolkit config diff` command | P0 | **Done** | 1.5d | `scripts/config_cli.py` `cmd_diff()` |
| 2.3 | `ai-toolkit config validate` command | P0 | **Done** | 1d | `scripts/config_cli.py` `cmd_validate()` |
| 2.4 | `ai-toolkit config init` command | P1 | **Done** | 1.5d | Interactive + flag-driven, validates extends |
| 2.5 | `ai-toolkit config create-base` command | P1 | **Done** | 2d | `scripts/config_scaffold.py` — full npm package scaffold |
| 3.1 | Audit trail in state.json | P1 | **Done** | 1d | `install_state.py` extends field + `.softspark-toolkit-extends.json` |
| 3.2 | Lock file (`.softspark-toolkit.lock.json`) | P1 | **Done** | 1.5d | `scripts/config_lock.py` — generate/consume/staleness check |
| 3.3 | Base config scaffolder (npm package template) | P1 | **Done** | 1.5d | Part of `config_scaffold.py` `create_base_package()` |
| 3.4 | CI enforcement (`ai-toolkit config check`) | P2 | **Done** | 1d | `config_cli.py` `cmd_check()` — JSON output, exit codes |
| 4.1 | Tests | P1 | **Done** | 3d | 39 tests: resolver (7), merger (13), CLI (10), install integration (9) |
| 4.2 | Documentation | P1 | **Done** | 3d | `kb/reference/enterprise-config-guide.md` — comprehensive guide |

**Phasing (MVP-first):**
- **MVP Phase 1 (week 1-2):** Core engine — schema (1.1), resolver (1.2), merge engine (1.3), constitution guard (1.4)
- **MVP Phase 2 (week 2-3):** Integration + diff — install integration (2.1), `config diff` (2.2), `config validate` (2.3), tests for above (~3.5 weeks = shippable MVP)
- **Phase 3 (week 4-5):** CLI polish — `config init` (2.4), `config create-base` (2.5), scaffolder (3.3)
- **Phase 4 (week 5-6):** Enterprise — audit trail (3.1), lock file (3.2), CI enforcement (3.4) (**gate behind real enterprise feedback**)
- **Phase 5 (week 6-7):** Tests + documentation (4.1, 4.2) (3d docs — all 9 docs per CLAUDE.md rules)

> **Demand validation gate:** Ship MVP (Phases 1-2), announce, measure adoption. Only build Phase 4 (lock file, CI enforcement, audit trail) in response to confirmed enterprise demand.

---

## 4. Dependency Graph

```
                     MVP Phase 1: Core Engine (week 1-2)
                     ====================================
Schema definition (1.1) ──────┐
                              ├──► Merge engine (1.3)
Config resolver (1.2) ────────┤
                              └──► Constitution guard (1.4)

                     MVP Phase 2: Integration + Diff (week 2-3)
                     ============================================
Install integration (2.1) ──┐
                            ├──► config diff (2.2)
                            └──► config validate (2.3)
                            └──► MVP tests → SHIP

                     ═══ DEMAND VALIDATION GATE ═══

                     Phase 3: CLI Polish (week 4-5)
                     ===============================
                            ├──► config init (2.4)
                            └──► create-base (2.5) + scaffolder (3.3)

                     Phase 4: Enterprise (week 5-6)
                     ================================
Audit trail (3.1) ──┐
                    ├──► Lock file (3.2)
                    └──► CI enforcement (3.4)

                     Phase 5: Polish (week 6-7)
                     ===========================
                            └──► Full tests + docs (4.1, 4.2)
```

---

## 5. Detailed Implementation

### Phase 1: Core Engine (week 1-2)

#### 1.1 Configuration Schema (`.softspark-toolkit.json`)

> **v1 scope:** The full schema below shows the target state. v1 implements only: `extends`, `profile`, `agents`, `rules`, `constitution`, and `enforce`. See section 6a for the v1/v2 field breakdown.

**Project-level config file:**

```json
{
  "$schema": "https://softspark.github.io/ai-toolkit/schemas/ai-toolkit-config.json",

  "extends": "@mycompany/ai-toolkit-config",

  "profile": "standard",
  "persona": "backend-lead",
  "hookProfile": "strict",

  "agents": {
    "enabled": ["backend-specialist", "test-engineer", "debugger"],
    "disabled": ["game-developer", "mobile-developer"],
    "custom": ["./agents/compliance-auditor.md"]
  },

  "skills": {
    "disabled": ["/deploy", "/rollback"],
    "custom": ["./skills/internal-deploy/"]
  },

  "rules": {
    "inject": ["./rules/code-review-policy.md"],
    "remove": []
  },

  "plugins": {
    "required": ["security-pack", "memory-pack"],
    "forbidden": []
  },

  "languages": ["typescript", "python"],

  "editors": ["cursor", "windsurf", "copilot"],

  "constitution": {
    "amendments": [
      {
        "article": 6,
        "title": "Data Sovereignty",
        "text": "All code generation must comply with GDPR. No personal data in prompts. No PII in generated code comments."
      }
    ]
  },

  "overrides": {
    "hooks": {
      "quality-check": {
        "override": true,
        "justification": "Company uses custom lint pipeline via Jenkins",
        "replacement": "skip"
      }
    }
  }
}
```

**Base config (`ai-toolkit.config.json` in npm package):**

```json
{
  "$schema": "https://softspark.github.io/ai-toolkit/schemas/ai-toolkit-base-config.json",
  "name": "@mycompany/ai-toolkit-config",
  "version": "2.1.0",
  "description": "MyCompany standard AI coding config",

  "extends": null,

  "profile": "strict",
  "persona": "backend-lead",
  "hookProfile": "strict",

  "agents": {
    "enabled": ["backend-specialist", "test-engineer", "code-reviewer", "security-auditor", "debugger", "documenter"],
    "disabled": ["game-developer"],
    "custom": ["./agents/compliance-auditor.md"]
  },

  "rules": {
    "inject": [
      "./rules/code-review-policy.md",
      "./rules/deployment-checklist.md",
      "./rules/data-handling-policy.md"
    ]
  },

  "plugins": {
    "required": ["security-pack"]
  },

  "languages": ["typescript"],

  "constitution": {
    "amendments": [
      {
        "article": 6,
        "title": "Data Sovereignty",
        "text": "All code generation must comply with GDPR. No personal data in prompts."
      },
      {
        "article": 7,
        "title": "Audit Compliance",
        "text": "All AI-generated code changes must be logged to the company audit system. The governance-capture hook must remain enabled."
      }
    ]
  },

  "enforce": {
    "minHookProfile": "standard",
    "requiredPlugins": ["security-pack"],
    "forbidOverride": ["constitution", "guard-destructive", "guard-path"],
    "requiredAgents": ["security-auditor"]
  }
}
```

**`enforce` section:** Base configs can define non-overridable constraints:
- `minHookProfile` — projects cannot go below this profile
- `requiredPlugins` — must be installed in all projects
- `forbidOverride` — these components cannot be overridden
- `requiredAgents` — must be enabled in all projects

---

#### 1.2 Config Resolver

**Resolution sources:**

| Source | Syntax | Resolution |
|--------|--------|------------|
| npm package | `"extends": "@mycompany/ai-toolkit-config"` | `npm pack --pack-destination /tmp` + extract |
| npm with version | `"extends": "@mycompany/ai-toolkit-config@^2.0.0"` | Version resolution via npm |
| Git URL | `"extends": "git+https://github.com/myco/ai-config.git"` | `git clone --depth 1` to cache |
| Local path | `"extends": "../shared-config"` | Resolve relative to project root |
| ~~Multiple bases~~ | ~~`"extends": ["@mycompany/base", "@mycompany/typescript-extra"]`~~ | Deferred to v2 — multi-base merge ordering is a complexity trap |

**Cache directory:** `~/.softspark/ai-toolkit/config-cache/`
```
~/.softspark/ai-toolkit/config-cache/
  @mycompany/
    ai-toolkit-config/
      2.1.0/
        ai-toolkit.config.json
        rules/
        agents/
```

**Resolution algorithm:**
```python
def resolve_extends(extends_value: str, project_root: str) -> list[BaseConfig]:
    """Resolve extends chain into ordered list of base configs.

    v1: single string only. Multi-base (list) deferred to v2.
    """
    configs = []
    for source in [extends_value]:  # v2: support list[str]
        if source.startswith('@') or source.startswith('npm:'):
            config = resolve_npm(source)
        elif source.startswith('git+'):
            config = resolve_git(source)
        elif source.startswith('.') or source.startswith('/'):
            config = resolve_local(source, project_root)
        else:
            raise ConfigError(f"Unknown extends source: {source}")

        # Recursive: base config may also have "extends"
        if config.extends:
            parent_configs = resolve_extends(config.extends, config.root)
            configs.extend(parent_configs)

        configs.append(config)

    return configs


def resolve_extends(extends_value: str, project_root: str,
                    _visited: set[str] | None = None) -> list[BaseConfig]:
    """Full signature with cycle detection via visited set."""
    if _visited is None:
        _visited = set()
    if extends_value in _visited:
        raise ConfigError(
            f"Circular extends detected: {extends_value} already in chain "
            f"{' → '.join(_visited)}. Check your base config's 'extends' field."
        )
    if len(_visited) >= 5:
        raise ConfigError(
            f"Extends chain too deep (max 5 levels). Chain: {' → '.join(_visited)}"
        )
    _visited.add(extends_value)
    # ... resolution logic as above, passing _visited to recursive calls
```

**Max recursion depth:** 5 levels (prevent circular extends). Circular detection via visited set.

**Offline handling:** If the npm/git source is unavailable:
1. Check cache (`~/.softspark/ai-toolkit/config-cache/`)
2. If cached version found → use with warning: "Using cached config v2.1.0 (offline)"
3. If not cached → error with instructions: "Run `ai-toolkit config update` when online"

---

#### 1.3 Merge Engine

**Layered deep merge with explicit override semantics:**

```python
def merge_configs(base: dict, project: dict) -> dict:
    """Merge project config over base config with rules."""
    merged = {}

    for key in set(base.keys()) | set(project.keys()):
        base_val = base.get(key)
        proj_val = project.get(key)

        if proj_val is None:
            merged[key] = base_val
        elif base_val is None:
            merged[key] = proj_val
        elif key == 'constitution':
            merged[key] = merge_constitution(base_val, proj_val)
        elif key == 'agents':
            merged[key] = merge_agents(base_val, proj_val)
        elif key == 'rules':
            merged[key] = merge_rules(base_val, proj_val)
        elif key == 'overrides':
            merged[key] = validate_overrides(base, proj_val)
        elif isinstance(base_val, dict) and isinstance(proj_val, dict):
            merged[key] = merge_configs(base_val, proj_val)
        elif isinstance(base_val, list) and isinstance(proj_val, list):
            merged[key] = list(set(base_val + proj_val))  # union
        else:
            merged[key] = proj_val  # project wins for scalars

    return merged
```

**Agent merge rules:**
```python
def merge_agents(base: dict, project: dict) -> dict:
    """Merge agent configs — project can enable/disable but not remove base-required."""
    merged_enabled = set(base.get('enabled', []))

    # Project can add agents
    merged_enabled.update(project.get('enabled', []))

    # Project can disable agents (unless base enforces them)
    for agent in project.get('disabled', []):
        if agent in base.get('enforce', {}).get('requiredAgents', []):
            raise ConfigError(
                f"Cannot disable '{agent}' — required by base config '{base['name']}'. "
                f"Contact your team lead to request an exemption."
            )
        merged_enabled.discard(agent)

    return {
        'enabled': sorted(merged_enabled),
        'custom': base.get('custom', []) + project.get('custom', [])
    }
```

**Override validation:**
```python
def validate_overrides(base: dict, overrides: dict) -> dict:
    """Validate project overrides against base enforcement rules."""
    forbidden = set(base.get('enforce', {}).get('forbidOverride', []))

    for key, override in overrides.items():
        if key in forbidden:
            raise ConfigError(
                f"Cannot override '{key}' — forbidden by base config '{base['name']}'.\n"
                f"Forbidden overrides: {', '.join(sorted(forbidden))}\n"
                f"Contact your team lead to request an exemption."
            )
        if not override.get('override'):
            raise ConfigError(
                f"Override for '{key}' requires explicit 'override: true' + 'justification' field.\n"
                f"This ensures intentional deviation from organizational defaults."
            )
        if not override.get('justification'):
            raise ConfigError(
                f"Override for '{key}' requires a 'justification' field explaining why.\n"
                f"Example: \"Company uses custom lint pipeline via Jenkins\""
            )

    return overrides
```

---

#### 1.4 Constitution Immutability Guard

**Core rule:** Base constitution articles are absolutely immutable. Projects can only ADD new articles.

No weakening-detection heuristic (character count, semantic analysis) — these produce false positives and are gameable. Instead, the rule is simple and absolute: if an article number exists in the base, it cannot be modified by the project.

```python
def merge_constitution(base: dict, project: dict) -> dict:
    """Merge constitution — additions only, no modifications."""
    base_amendments = {a['article']: a for a in base.get('amendments', [])}
    proj_amendments = {a['article']: a for a in project.get('amendments', [])}

    # Toolkit articles I-V are always immutable
    IMMUTABLE_ARTICLES = {1, 2, 3, 4, 5}

    merged = dict(base_amendments)

    for article_num, amendment in proj_amendments.items():
        if article_num in IMMUTABLE_ARTICLES:
            raise ConfigError(
                f"Cannot modify Constitution Article {article_num} — immutable.\n"
                f"Articles I-V are defined by ai-toolkit and cannot be overridden.\n"
                f"You can ADD new articles (article 6+)."
            )
        if article_num in base_amendments:
            # Base articles are immutable — projects cannot modify them
            raise ConfigError(
                f"Cannot modify Constitution Article {article_num} — "
                f"defined by base config '{base.get('name', 'unknown')}'.\n"
                f"Base articles are immutable. You can ADD new articles "
                f"with a higher article number."
            )
        merged[article_num] = amendment

    return {'amendments': list(merged.values())}
```

---

### MVP Phase 2: Integration + Diff (week 2-3)

#### 2.1 Install/Update Integration

**Modified `install.py` flow:**

```python
# During install --local:
# 1. Check for .softspark-toolkit.json in project root
# 2. If found and has "extends":
#    a. Resolve base config(s)
#    b. Merge base → project
#    c. Validate merged config
#    d. Generate files from merged config
# 3. If not found: proceed with current behavior (backwards compatible)
```

**CLI flags:**
```bash
ai-toolkit install --local                           # auto-detect .softspark-toolkit.json
ai-toolkit install --local --config ./custom.json    # explicit config file
ai-toolkit update --local                            # re-resolve extends + update
ai-toolkit update --local --refresh-base             # force re-fetch base config
```

---

#### 2.2 `ai-toolkit config diff`

**Show differences between project config and base:**

```bash
ai-toolkit config diff

# Output:
# Base: @mycompany/ai-toolkit-config@2.1.0
#
# Profile:     strict (base) → standard (project) ⚠ OVERRIDE
# Persona:     backend-lead (base) → frontend-lead (project)
# Hook Profile: strict (base) → strict (inherited)
#
# Agents:
#   + frontend-specialist     (project adds)
#   - game-developer          (base disables)
#   = security-auditor        (base requires, cannot disable)
#
# Rules:
#   + ./rules/api-standards.md  (project adds)
#   = code-review-policy.md     (inherited from base)
#
# Constitution:
#   = Articles I-V              (immutable)
#   = Article 6: Data Sovereignty (inherited from base)
#   + Article 8: API Standards    (project adds)
#
# Overrides:
#   quality-check: SKIP (justification: "Custom Jenkins pipeline")
```

---

#### 2.3 `ai-toolkit config validate`

```bash
ai-toolkit config validate

# Checks:
# ✓ .softspark-toolkit.json schema valid
# ✓ extends: @mycompany/ai-toolkit-config@2.1.0 resolved
# ✓ No forbidden overrides
# ✓ Required plugins installed: security-pack
# ✓ Required agents enabled: security-auditor
# ✓ Constitution articles I-V intact
# ✓ Hook profile meets minimum: standard ≥ standard
# ✓ All custom rule files exist
# ✓ All custom agent files exist
```

---

### Phase 3: CLI Polish (week 4-5)

#### 2.4 `ai-toolkit config init`

**Interactive project config setup:**

```bash
ai-toolkit config init

# Flow:
# 1. "Does your organization have a shared ai-toolkit config? [y/n]"
#    → y: "npm package name or git URL:" → resolves + validates
#    → n: creates minimal .softspark-toolkit.json without extends
# 2. "Which profile? [minimal/standard/strict]" → default from base or standard
# 3. "Which persona? [none/backend-lead/frontend-lead/devops-eng/junior-dev]"
# 4. Auto-detect languages from project
# 5. Auto-detect editors from project files
# 6. Write .softspark-toolkit.json
# 7. Run ai-toolkit install --local
```

---

#### 2.5 `ai-toolkit config create-base`

**Scaffold a base config package:**

```bash
ai-toolkit config create-base @mycompany/ai-toolkit-config

# Creates:
# @mycompany-ai-toolkit-config/
# ├── package.json          (name, version, files, peerDependencies)
# ├── ai-toolkit.config.json (base config with sane defaults)
# ├── rules/                (empty, ready for company rules)
# ├── agents/               (empty, ready for company agents)
# └── README.md             (setup instructions)
```

**Generated `package.json`:**
```json
{
  "name": "@mycompany/ai-toolkit-config",
  "version": "1.0.0",
  "description": "Shared ai-toolkit configuration for MyCompany",
  "main": "ai-toolkit.config.json",
  "files": ["ai-toolkit.config.json", "rules/", "agents/"],
  "peerDependencies": {
    "@softspark/ai-toolkit": ">=1.5.0"
  },
  "keywords": ["ai-toolkit", "config", "shared"]
}
```

---

### Phase 4: Enterprise Features (week 5-6)

#### 3.1 Audit Trail

**`state.json` additions:**
```json
{
  "extends": {
    "source": "@mycompany/ai-toolkit-config",
    "version": "2.1.0",
    "resolved_at": "2026-04-10T10:30:00Z",
    "hash": "sha256:abc123...",
    "overrides_applied": [
      {
        "key": "hooks.quality-check",
        "action": "skip",
        "justification": "Custom Jenkins pipeline"
      }
    ]
  }
}
```

---

#### 3.2 Lock File (`.softspark-toolkit.lock.json`)

**Purpose:** Pin the exact resolved version of base configs for reproducible installs across team members and CI.

```json
{
  "lockfileVersion": 1,
  "resolved": {
    "@mycompany/ai-toolkit-config": {
      "version": "2.1.0",
      "resolved": "https://registry.npmjs.org/@mycompany/ai-toolkit-config/-/ai-toolkit-config-2.1.0.tgz",
      "integrity": "sha512-abc123...",
      "cached": "~/.softspark/ai-toolkit/config-cache/@mycompany/ai-toolkit-config/2.1.0/"
    }
  },
  "generated_at": "2026-04-10T10:30:00Z",
  "ai_toolkit_version": "1.5.1"
}
```

**Behavior:**
- `ai-toolkit install --local` → uses lock file if present (like `npm ci`)
- `ai-toolkit update --local` → re-resolves and updates lock file (like `npm install`)
- `ai-toolkit update --local --refresh-base` → force re-fetch ignoring cache
- `.softspark-toolkit.lock.json` should be committed to git (team synchronization)

---

#### 3.4 CI Enforcement

**`ai-toolkit config check` — for CI pipelines:**

```bash
ai-toolkit config check

# Exit codes:
# 0 — project complies with base config
# 1 — violations found (missing required plugins, forbidden overrides, etc.)
# 2 — .softspark-toolkit.json not found
```

**GitHub Actions example:**
```yaml
- name: AI Toolkit Governance Check
  run: |
    npx @softspark/ai-toolkit config check
    npx @softspark/ai-toolkit config validate --strict
```

**What it checks:**
1. Required plugins are installed
2. Required agents are enabled
3. No forbidden overrides applied without exemption
4. Hook profile meets minimum
5. Constitution articles intact
6. Lock file up-to-date (warn if stale)

---

## 6. File Summary

| File | Action | LOC (est.) | Description |
|------|--------|------------|-------------|
| `scripts/config_resolver.py` | CREATE | ~400 | Resolve extends (npm, git, local path) |
| `scripts/config_merger.py` | CREATE | ~350 | Layered merge engine |
| `scripts/config_validator.py` | CREATE | ~200 | Schema + enforcement validation |
| `scripts/config_scaffold.py` | CREATE | ~250 | create-base scaffolder |
| `scripts/config_diff.py` | CREATE | ~200 | Diff viewer |
| `scripts/config_check.py` | CREATE | ~150 | CI enforcement checker |
| `scripts/install.py` | EDIT | +80 | Integrate extends resolution |
| `bin/ai-toolkit.js` | EDIT | +40 | Register config subcommands |
| `manifest.json` | EDIT | +10 | Schema references |
| `kb/reference/enterprise-config-guide.md` | CREATE | ~300 | Enterprise setup guide |
| `kb/reference/base-config-template/` | CREATE | ~200 | Scaffolded base config files |
| `tests/test_config_resolver.bats` | CREATE | ~150 | Resolution tests |
| `tests/test_config_merger.bats` | CREATE | ~200 | Merge + override tests |
| `tests/test_config_immutability.bats` | CREATE | ~100 | Constitution guard tests |
| `tests/test_config_cli.bats` | CREATE | ~150 | CLI command tests |
| **Total** | | **~2780** | |

---

## 6a. Schema Scope (v1 vs v2)

v1 ships with a minimal schema. Each additional field adds merge logic, validation, diff output, and test surface. Expand based on real usage, not speculation.

| Field | v1 | v2 | Rationale |
|-------|----|----|-----------|
| `extends` | single string | array (multi-base) | Multi-base merge ordering is complex |
| `profile` | yes | — | Core governance knob |
| `agents` | yes | — | Most common customization |
| `rules` | yes | — | Rule injection is existing feature |
| `constitution` | yes | — | Key differentiator |
| `enforce` | yes | — | Non-overridable constraints |
| `skills` | — | yes | Less commonly customized at org level |
| `plugins` | — | yes | Depends on plugin maturity |
| `languages` | — | yes | Auto-detected, rarely org-level |
| `editors` | — | yes | Auto-detected, rarely org-level |
| `overrides` | — | yes | Complex, needs real-world feedback |
| `hookProfile` / `persona` | — | yes | Low demand signal |

---

## 6b. Non-Functional Requirements

| Category | Requirement |
|----------|-------------|
| **Performance** | `install --local` with extends resolution < 5s (cached), < 15s (first fetch). Config merge < 100ms. |
| **Offline** | Cached configs used when registry unavailable, with clear warning. |
| **Security** | No secret exposure in config files or audit trail. npm auth via `.npmrc` (user-managed). `execFile` for npm CLI (no shell injection). |
| **Error messages** | Every validation error includes: what failed, which config layer caused it, and what to do (e.g., "Contact your team lead to request an exemption"). |
| **Backward compatibility** | 100% — projects without `.softspark-toolkit.json` work exactly as today. Zero behavioral changes for existing users. |
| **Maintainability** | Each new schema field requires: merge logic, validation, diff output, test. Budget 0.5d per new field. |
| **Quality gates** | `ruff check scripts/config_*.py` (0 errors), `mypy --strict scripts/config_*.py` (0 errors). Run before every commit. |
| **Type safety** | 100% public API type hints (all function signatures). >60% internal. Use `TypedDict` for config schemas, `dataclass` for resolved configs. |

---

## 7. Success Criteria (Overall)

| Metric | Target |
|--------|--------|
| Extends sources (v1) | 4 (npm, npm+version, git URL, local path) — single string only |
| Merge depth | 5 levels max (recursive extends) |
| Config schema | JSON Schema validated |
| Constitution protection | 100% (Articles I-V immutable) |
| Override justification | Required for all overrides |
| Enforce constraints | 4 types (minHookProfile, requiredPlugins, forbidOverride, requiredAgents) |
| Backward compatibility | 100% (projects without .softspark-toolkit.json work as today) |
| CI enforcement | Exit code 0/1 for governance compliance |
| Lock file | Reproducible installs across team members |
| Scaffold command | Ready-to-publish npm package template |
| Tests | 30+ |
| Offline resolution | Cached configs with warning |

---

## 8. Risks and Mitigation

| Risk | Probability | Impact | Mitigation |
|------|-------------|--------|------------|
| npm registry unavailable during install | Low | Medium | Cache + offline fallback with warning |
| Circular extends chain | Low | High | Max depth 5 + visited set for cycle detection |
| Base config breaks project | Medium | High | Lock file pins exact version; `ai-toolkit config diff` shows changes before update |
| Override abuse (teams bypass governance) | Medium | Medium | `enforce.forbidOverride` + CI check + justification requirement |
| Config schema too restrictive | Medium | Medium | Start with minimal enforcement, expand based on enterprise feedback |
| Multiple base configs conflict | — | — | Deferred to v2 (single extends only in v1) |
| Private npm registry authentication | Medium | Low | Use existing npm auth (`.npmrc`), document setup |
| Git URL resolution slow | Low | Low | `--depth 1` clone, cache aggressively |

---

## 9. Pre-Mortem

1. **"Config file fatigue"** — developers already have `.eslintrc`, `tsconfig.json`, `.prettierrc`. Another `.softspark-toolkit.json` may feel like bloat. Mitigation: file is optional, all features work without it. The DX gain (organizational governance without per-repo updates) justifies the file.
2. **"Base config never gets updated"** — team lead creates base config, nobody maintains it. Mitigation: `ai-toolkit config check` in CI catches drift; lock file staleness warnings.
3. **"Override justification is annoying"** — developers will write "needed" as justification. Mitigation: CI check can enforce minimum justification length (>20 chars); code review culture catches low-effort justifications.
4. **"Merge semantics are confusing"** — "does project override or extend the base agent list?" Mitigation: explicit semantics documented in schema; `ai-toolkit config diff` shows exactly what happened.
5. **"Enterprise teams want RBAC on overrides"** — who can approve overrides? Mitigation: v1 uses justification text + code review; v2 could integrate with GitHub CODEOWNERS for override approval.

---

## 10. Market Positioning

**Target users:**
1. **Engineering managers** — enforce AI coding standards across 20+ repos without touching each one
2. **Security teams** — ensure constitution + security-auditor agent is always enabled
3. **Platform teams** — distribute company-specific agents, rules, and plugins via npm
4. **Compliance officers** — audit trail of what AI governance rules are active in each project

**Competitive advantage:** No existing AI coding toolkit supports configuration inheritance. This is a unique enterprise feature that transforms ai-toolkit from a developer tool into an organizational governance platform.

**Revenue potential:** Enterprise teams are the primary audience for paid support/consulting around ai-toolkit. Config inheritance is the feature that makes enterprise adoption manageable.

---

## 11. Next Actions

**MVP (ship first, ~3.5 weeks):**
1. [x] Approve plan
2. [x] Define `.softspark-toolkit.json` JSON Schema — v1 scope only (1.1)
3. [x] Implement config resolver (npm, git, local) with caching (1.2)
4. [x] Implement merge engine with override validation (1.3)
5. [x] Implement constitution immutability guard (1.4)
6. [x] Integrate into install.py flow (2.1)
7. [x] Create `config diff` viewer (2.2) — primary debugging tool
8. [x] Create `config validate` checker (2.3)
9. [x] Tests for above (4.1 partial)
10. [x] **Ship MVP → announce → measure adoption**

**Post-MVP:**
11. [x] Create `config init` interactive command (2.4)
12. [x] Create `config create-base` scaffolder (2.5)
13. [x] Add audit trail to state.json (3.1)
14. [x] Implement lock file generation + resolution (3.2)
15. [x] Create base config npm package template (3.3)
16. [x] Create CI enforcement command `config check` (3.4)
17. [x] Full tests + documentation (4.1, 4.2)

**All 17 items completed — 2026-04-11.**

---

## 12. Future (v2)

| Feature | Rationale |
|---------|-----------|
| Multi-base extends (`"extends": [...]`) | Needs real-world feedback on merge ordering UX |
| v1 deferred schema fields (skills, plugins, languages, editors, overrides, hookProfile, persona) | Expand based on actual enterprise requests |
| RBAC on overrides (GitHub CODEOWNERS integration) | v1 uses justification + code review |
| Semantic constitution analysis | Character-count heuristics removed in v1; revisit only if absolute immutability proves too restrictive |
| `ai-toolkit config audit` (full governance report) | Depends on audit trail maturity |

---

## 13. Cross-Plan Dependencies

This plan shares modification targets with the Offline SLM plan:

| Shared File | This Plan | Offline SLM Plan |
|-------------|-----------|-----------------|
| `scripts/install.py` | +80 LOC (extends resolution) | +30 LOC (offline-slm profile) |
| `manifest.json` | +10 LOC (schema refs) | +5 LOC (offline-slm profile) |
| `bin/ai-toolkit.js` | +40 LOC (config subcommands) | +10 LOC (compile-slm command) |

**If implementing in parallel:** coordinate merge order for shared files. Recommended sequence: Offline SLM (smallest changes) → Enterprise Config.

---

**Last Updated:** 2026-04-10

---

## kb/history/completed/f2-mcp-trim-spike-20260504.md

---
title: "Spike: F2 MCP Context Trim — Hook Feasibility & Path Decision"
category: planning
service: ai-toolkit
tags:
  - mcp
  - hooks
  - claude-code
  - spike
  - feasibility
doc_type: spike
status: completed
created: "2026-05-04"
last_updated: "2026-05-04"
completed: "2026-05-04"
shipped_in: "v3.2.0 (decision only — implementation deferred to v4.0)"
description: "Spike conclusion for Feature 2 of the output-token-discipline plan. Determines whether Claude Code hooks can modify MCP tool descriptions before they reach the LLM. Result: hooks operate per-call, not on tool list metadata. Full feature requires an MCP proxy server (multi-day scope). Outcome: F2 deferred to v4.0 with own dedicated PRD."
---

# Spike: F2 MCP Context Trim — Hook Feasibility & Path Decision

## Question

Can Claude Code's hook system modify MCP **tool descriptions** that get included in the model's system prompt, or do hooks only intercept individual tool **calls**?

## Method

Reviewed local sources only (RAG MCP offline at spike time):

1. `app/skills/hook-creator/SKILL.md` — exhaustive list of supported hook events and their data shapes
2. `app/hooks/guard-destructive.sh`, `app/hooks/guard-path.sh` — actual examples reading `tool_input` from stdin
3. `app/skills/mcp-builder/SKILL.md` — MCP server-side conventions
4. `~/.claude/.mcp.json` — user's installed MCP servers (Context7, sequential-thinking, filesystem, rag-mcp, memory, jira-mcp)

## Findings

### Hook events that touch tool data

| Event | Modifies tool list? | Modifies tool input? | Notes |
|-------|--------------------|--------------------|-------|
| `PreToolUse` | no | no (only block via exit 2) | Reads `tool_input.*`, decides allow/deny |
| `PostToolUse` | no | no | Sees result for logging / feedback |
| `PermissionRequest` | no | yes (`updatedInput`) | Can rewrite a single call's args |
| `Elicitation` | no | n/a | Intercepts MCP UI prompts, not tool list |
| `SessionStart` | no | n/a | Context injection only |
| `InstructionsLoaded` | no | n/a | Verifies CLAUDE.md presence |

**No event exposes the MCP `tools/list` response or the system-prompt tool catalog**. The tool catalog is materialized once per MCP server connection from the server's own `tools/list` reply.

### Why this matters

The compression target was the bulk of MCP tool descriptions sitting in every model turn's system prompt. Examples from the user's installed servers:

- `dart-mcp-server` — ~30 tools with multi-paragraph descriptions
- `filesystem` — verbose paths and example sections
- `pencil` — "IMPORTANT" stanzas repeated across tools
- `jira-mcp` — long `Use this tool to...` boilerplate

At ~100 tools across 7 servers in this user's config, easily 8–15k tokens of pure description text. Real waste, but Claude Code does not let a hook touch it.

### What would actually work

To compress MCP tool descriptions before they reach the LLM, exactly two architectures are viable:

1. **Local MCP proxy server** between Claude Code and each target server. The proxy re-implements `tools/list` to rewrite descriptions on the fly while passing through `tools/call`. Requires JSON-RPC 2.0 over stdio + SSE per server, per-server config in `~/.claude/.mcp.json`, and a process supervisor for the proxies. Multi-day scope. Failure mode: a buggy proxy breaks all MCP-dependent skills.
2. **Source-side fork**: ship pre-trimmed copies of common MCP servers (`@softspark/jira-mcp-trim`, etc.) — high maintenance burden, doesn't help users with custom servers.

Neither is a "minimal change" by the standards of this plan.

## Decision (final, 2026-05-04)

**Drop F2 from v3.2.0 entirely. Defer the full MCP proxy approach to v4.0** with its own dedicated PRD and architecture spike.

The spike originally surfaced a smaller "F2-lite observability tool" alternative (read-only inventory + suggestions). After review, the user chose to drop both options from v3.2.0:

- v3.2.0 ships F1 + F3 + F3.5 only (output modes, token telemetry, default statusline)
- F2 work — including any observability-first prototype — moves wholesale to v4.0 milestone
- Reasoning: keep v3.2.0 release scope tight; v4.0 owns MCP-cost story end-to-end with proper proxy architecture

## Alternatives considered

| Option | Pros | Cons | Verdict |
|--------|------|------|---------|
| Build full MCP proxy in v3.2.0 | Achieves original compression goal | Multi-day work, single-bug-breaks-all-MCP failure mode, would block release | Rejected — too big for current release |
| Pre-install rewrite of `.mcp.json` | One-shot, no runtime cost | MCP spec sources descriptions from server, not config — wouldn't actually take effect | Rejected — does not work |
| F2-lite observability tool in v3.2.0 | Low risk, gives users data | Not the original target; partial value; mixes two milestones | Rejected by user — keep v3.2.0 focused |
| **Defer F2 entirely to v4.0** | Clean release boundaries; v4.0 owns MCP story end-to-end with full proxy scope | Token waste in MCP descriptions stays invisible to users until v4.0 | **Selected** |

## What was delivered in v3.2.0 (F1 + F3 + F3.5)

The output-discipline goal is partially addressed by what shipped:

- **Output modes** (F1) cut conversational response tokens 60–80% on the shipped fixture set
- **Real token telemetry** (F3) lets users see actual cost per session — including the MCP description overhead, even if they cannot yet trim it
- **Default statusline** (F3.5) surfaces that cost continuously

Users now have visibility into the MCP-description waste this spike identified, even though automated compression has to wait for v4.0.

## What goes into v4.0

Tracked as an active PRD: [`kb/planning/mcp-context-trim-v4-prd.md`](../../planning/mcp-context-trim-v4-prd.md). It carries forward:

1. Compression heuristics from the original F2 design (migrated out of the archived plan into the live PRD)
2. Local MCP proxy server architecture: JSON-RPC 2.0 over stdio + SSE per server, process supervisor, per-server config in `~/.softspark/ai-toolkit/mcp-proxy/`
3. Rollback / opt-out story — a buggy proxy must not break MCP-dependent skills
4. Failure mode — proxy down → fall through to direct MCP server, with telemetry warning
5. Migration of existing user `.mcp.json` configs

Estimate in the PRD: ~8 working days.

## Status

| Date | Status | Author |
|------|--------|--------|
| 2026-05-04 | Spike completed | claude |
| 2026-05-04 | User decision: defer F2 to v4.0 entirely (no F2-lite in v3.2.0) | lukasz.krzemien |
| 2026-05-04 | Spike archived to `kb/history/completed/` alongside the parent plan | claude |

---

## kb/history/completed/language-packs-removed-20260727.md

---
title: "AI Toolkit - Language Plugin Packs (removed)"
category: planning
service: ai-toolkit
tags: [plugins, languages, rust, java, csharp, kotlin, swift, ruby, removed]
doc_type: postmortem
status: completed
version: "1.1.0"
created: "2026-03-29"
last_updated: "2026-07-27"
description: "REMOVED 2026-07-27 in v4.20.0. The six language packs wrapped skills that already ship in core, so installing one put zero files on disk. The skills themselves (rust-patterns, java-patterns, csharp-patterns, kotlin-patterns, swift-patterns, ruby-patterns) were never in the packs and are unaffected."
---

# Language Plugin Packs — REMOVED

> **Removed 2026-07-27 in v4.20.0. Nothing was lost.**
>
> The six packs described below each declared exactly one skill —
> `rust-patterns`, `java-patterns`, `csharp-patterns`, `kotlin-patterns`,
> `swift-patterns`, `ruby-patterns` — and every one of those skills lives in
> `app/skills/`, is part of the core install, and **still does**. The packs
> owned no files of their own beyond a `README.md`.
>
> Because `ai-toolkit install` links every core skill, installing a language
> pack put **zero** files on disk. Measured on both runtimes and all three
> profiles: `(0 file items)` every time.
>
> **If you used one of these packs, you lose nothing.** The skill it named is
> already installed and triggers on the same file types it always did — open a
> `.rs` file and `rust-patterns` still loads.
>
> Full measurement and the rule that now prevents a repeat:
> [`no-op-plugin-packs-removed-20260727.md`](no-op-plugin-packs-removed-20260727.md).
>
> The document below is preserved as written on 2026-03-29.

---

## Overview

Language packs are domain-scoped plugin packs that provide knowledge skills for specific programming languages. Each pack contains a single knowledge skill with idiomatic patterns, error handling, testing conventions, common frameworks, and performance tips.

## Available Packs

| Pack | Skill | Language | Key Topics |
|------|-------|----------|------------|
| `rust-pack` | `rust-patterns` | Rust | Ownership, borrowing, Cargo, tokio, serde |
| `java-pack` | `java-patterns` | Java | Records, sealed classes, Spring Boot, JUnit 5 |
| `csharp-pack` | `csharp-patterns` | C# / .NET | Nullable refs, async/await, ASP.NET Core, EF Core |
| `kotlin-pack` | `kotlin-patterns` | Kotlin | Coroutines, DSLs, sealed classes, Ktor, MockK |
| `swift-pack` | `swift-patterns` | Swift / iOS | Protocol-oriented, SwiftUI, async/await, SPM |
| `ruby-pack` | `ruby-patterns` | Ruby | Blocks, Rails conventions, RSpec, ActiveRecord |

## Skill Content Sections

Each language skill follows a consistent structure:

1. **Project Structure** — standard directory layout and build tool configuration
2. **Idioms / Code Style** — language-specific patterns and conventions
3. **Error Handling** — error types, patterns, and best practices
4. **Testing Patterns** — test frameworks, assertion libraries, mocking
5. **Common Libraries / Frameworks** — ecosystem essentials
6. **Performance Tips** — optimization techniques and profiling
7. **Build / Package Management** — dependency management and CI

## How Knowledge Skills Work

These skills have `user-invocable: false` in their frontmatter, meaning they are NOT slash commands. Instead, Claude loads them contextually when the conversation topic matches the skill's description trigger.

For example, when a user asks "How do I handle errors in Rust?", Claude automatically loads `rust-patterns` to provide idiomatic Rust error handling guidance.

## Requesting New Language Packs

File an issue with the `language-pack` label. Include:
- Language name
- Key topics to cover
- Popular frameworks/libraries to include

---

## kb/history/completed/mcp-context-trim-v4-prd-obsoleted-20260727.md

---
title: "PRD: MCP Context Trim v4.0 — Local Proxy with Description Compression"
category: planning
service: ai-toolkit
tags:
  - mcp
  - proxy
  - tool-descriptions
  - jsonrpc
  - tokens
  - v4
doc_type: plan
status: obsoleted
created: "2026-05-04"
last_updated: "2026-07-27"
completion: "0% — never started, and no longer worth starting"
target_milestone: "v4.0 (abandoned)"
predecessor:
  - "kb/history/completed/output-token-discipline-plan-20260504.md"
  - "kb/history/completed/f2-mcp-trim-spike-20260504.md"
description: "ABANDONED 2026-07-27. Local MCP proxy that would compress tool descriptions before they reach the model. Never built. Claude Code now defers MCP tool schemas by default — the catalog costs ~120 tokens of tool names, with schemas fetched on demand — so the 8-15k per-turn overhead this PRD was written to remove no longer exists. Kept as the record of a plan the platform solved first."
---

# PRD: MCP Context Trim v4.0 — ABANDONED

> **Abandoned 2026-07-27, never implemented.**
>
> **Why:** the premise expired. This PRD is built on one measured claim — that
> MCP tool descriptions sit in every turn's system prompt, costing 8–15k tokens
> per turn. Claude Code now **defers MCP tool schemas by default**: the model
> receives roughly 120 tokens of tool *names*, and full schemas are fetched on
> demand through tool search when a task actually needs one.
> ([Claude Code docs — context window](https://code.claude.com/docs/en/context-window),
> `ENABLE_TOOL_SEARCH=auto|false` controls the older eager behaviour.)
>
> The overhead this proxy was designed to remove is already gone. Building it
> now would add a supervised local daemon, an `.mcp.json` rewrite, a rollback
> path and five pre-mortem failure modes in order to compress a 120-token
> catalog.
>
> **How it was caught:** during the 2026-07-27 token-reduction review, a
> measurement of 1189 real sessions put the median startup context at 22,175
> tokens against ~7,850 in the documented reference shape. Attributing that gap
> showed the excess was skill and agent descriptions and rule files — not MCP.
> The MCP catalog was already deferred, exactly as the docs describe. Full
> context: [`tool-output-token-reduction-closed-20260727.md`](tool-output-token-reduction-closed-20260727.md).
>
> **What survives:** nothing in the architecture below is reusable, because it
> exists to solve a problem the host now solves. What survives is the process
> note — this PRD sat in `kb/planning/` for nearly three months while the
> platform shipped the fix, and nobody re-checked the premise. A plan blocked on
> a host limitation should carry a re-validation date, not wait indefinitely.
>
> Everything below is the document as written on 2026-05-04. It is preserved
> unedited so the reasoning stays auditable.

---

**Status:** Proposed *(as of 2026-05-04; see abandonment note above)*
**Target milestone:** v4.0
**Carved out of:** [`output-token-discipline-plan-20260504.md`](output-token-discipline-plan-20260504.md) (was Feature 2)
**Spike basis:** [`f2-mcp-trim-spike-20260504.md`](f2-mcp-trim-spike-20260504.md)

## Problem

MCP server tool descriptions are injected into every model turn's system prompt. With ~100 tools across 7 typical servers, descriptions consume 8–15k tokens per turn — pure overhead, paid every message. Examples observed in users' configs:

- `dart-mcp-server` — ~30 tools with multi-paragraph descriptions
- `filesystem` — verbose paths and example sections
- `pencil` — "IMPORTANT" stanzas repeated across tools
- `jira-mcp` — long `Use this tool to…` boilerplate

The v3.2.0 output-discipline plan attempted to solve this with a hook-based trimmer. The spike conducted 2026-05-04 proved Claude Code hooks do not expose `tools/list` metadata or the system-prompt tool catalog. The only viable architecture is a local MCP proxy.

## Goal

Reduce MCP-description overhead by ≥40% per server, with **zero** loss of parameter schemas, required fields, or discrimination signals (`not`, `never`, `only`, `except`, `unless`).

## Non-goals

- Modifying tool **call** behavior (only descriptions)
- Compressing user-facing prompts or completions
- Replacing or rewriting upstream MCP servers
- Touching MCP servers we do not control

## Architecture

### Proxy topology

```
Claude Code  ──stdio──▶  ai-toolkit MCP proxy  ──stdio/SSE──▶  upstream MCP server
                                │
                                └─ rewrites tools/list response
                                   passes through tools/call unchanged
```

One proxy process per upstream server, supervised by `ai-toolkit mcp-trim daemon` (or equivalent). User's `~/.claude/.mcp.json` is rewritten by `ai-toolkit install` (opt-in) to point Claude Code at the proxy instead of upstream — proxy reads the original target from a sidecar config.

### Required components

| Component | Purpose |
|-----------|---------|
| `scripts/mcp_proxy_server.py` | JSON-RPC 2.0 proxy. Reads stdin, forwards to upstream over stdio or SSE, intercepts `tools/list` response, rewrites descriptions. Stdlib-only. |
| `scripts/mcp_description_trimmer.py` | Pure function library: `trim(description: str) → str`. Reused from heuristics below. Stdlib-only. |
| `scripts/mcp_proxy_config.py` | Reads `~/.softspark/ai-toolkit/mcp-proxy/servers.json`, validates upstream targets, generates supervisord/launchd config. |
| `app/hooks/mcp-proxy-health.sh` | SessionStart hook — verifies all configured proxies responsive; fall through (warn, do not block) if any down. |
| `app/skills/mcp-trim/SKILL.md` | Knowledge skill: how to enable, opt out, audit savings. |
| `bin/ai-toolkit-mcp-trim` | CLI: `enable`, `disable`, `status`, `audit` (per-server token savings report). |
| `tests/test_mcp_proxy.bats` | Integration tests with mock upstream MCP servers. |
| `tests/test_mcp_trimmer.bats` | Unit tests for description trim heuristics on captured fixtures. |

### Compression heuristics (from spike)

Applied to each tool description in `tools/list` response:

- Drop example sections >40 chars
- Collapse `Use this server to…` / `Use this tool to…` boilerplate to minimum form preserving intent
- Drop duplicate occurrences of tool name in its own description
- **Preserve bytewise:** `inputSchema.properties[*].description`, `required`, `enum` values, URL/path identifiers
- **Never strip:** the words `not`, `never`, `only`, `except`, `unless` — these carry "when NOT to use" signals
- Target: ≥40% length reduction, 0% schema loss

### Failure modes & rollback

| Scenario | Behavior |
|----------|----------|
| Proxy crashes mid-session | `mcp-proxy-health.sh` detects on next SessionStart, prints warning, suggests `ai-toolkit mcp-trim disable <server>` |
| Upstream MCP server changes its tool catalog | Proxy passes through unchanged tools (no cached schema), warns once if a tool's description was previously trimmed |
| Trimmer produces malformed JSON | Proxy falls through to upstream response unchanged, logs to `~/.softspark/ai-toolkit/mcp-proxy/error.log` |
| User wants to bypass | `AI_TOOLKIT_MCP_TRIM_DISABLE=1` env var → proxies pass everything through unchanged |
| User wants to fully uninstall | `ai-toolkit mcp-trim disable` reverts `~/.claude/.mcp.json` to original upstream targets |

### Migration of existing user `.mcp.json`

`ai-toolkit mcp-trim enable` does:

1. Backup `~/.claude/.mcp.json` → `~/.softspark/ai-toolkit/mcp-proxy/.mcp.json.bak.<timestamp>`
2. Read each server entry, store in `~/.softspark/ai-toolkit/mcp-proxy/servers.json`
3. Rewrite each entry to point at the local proxy (with sidecar `target` field)
4. Spawn supervisor (per-OS: launchd on macOS, systemd on Linux, scheduled task on Windows)
5. Verify each upstream reachable via proxy, abort + restore backup on any failure

## Out-of-scope decisions (rejected mid-spike)

| Option | Why rejected |
|--------|--------------|
| Pre-install rewrite of `.mcp.json` only | MCP spec sources descriptions from server runtime, not config — wouldn't take effect |
| Source-side forks of MCP servers | Doesn't help users with custom servers; high maintenance |
| F2-lite observability tool | User decision 2026-05-04: tracking token waste without trimming is half-value; do the full thing in v4.0 |
| Hook-based interception | Spike proved hooks cannot reach `tools/list` |

## Success criteria

- ≥40% description-length reduction per server on the captured fixture set (jira, filesystem, dart, pencil)
- Deep-equal `inputSchema` between trimmed and upstream — zero schema regression
- Proxy adds <50ms per `tools/list` call (one-time per session)
- Proxy adds <5ms per `tools/call` (passthrough overhead)
- Round-trip correctness: every tool callable via proxy returns byte-identical result vs direct call
- Zero MCP-skill regressions in `npm test` after enabling proxy in CI
- Rollback (`ai-toolkit mcp-trim disable`) restores byte-identical original `.mcp.json`

## Open questions

1. Process supervision per-OS — launchd / systemd / scheduled-task wrappers, or a built-in `ai-toolkit-mcp-trimd` daemon binary?
2. SSE-mode upstreams (e.g., rag-mcp at `http://localhost:8081/mcp/sse`) — proxy listens on SSE locally too, or stdio-only with internal SSE client?
3. Description rewrites — static dictionary of "boilerplate phrases to drop" (faster, deterministic) vs LLM-based summarizer (more aggressive, less predictable)? Recommend static for v4.0, LLM as v4.1 stretch.
4. Config path — `~/.softspark/ai-toolkit/mcp-proxy/` (matches existing convention) or `~/.claude/mcp-proxy/` (closer to MCP config)? Recommend the former.
5. Telemetry — does this become an opt-in metric in `/briefing --tokens` ("MCP descriptions: 12.3k → 7.2k, saved 5.1k per turn")? Recommend yes.

## Pre-mortem (failure scenarios to design against)

1. **Proxy gets out of sync with upstream** — upstream adds a new tool, proxy doesn't know how to compress it → passthrough that tool's description unchanged, log warning
2. **Compression breaks tool discriminability** — model picks wrong tool because trimmed description lost the "use only when X" qualifier → the `not/never/only/except/unless` blacklist must be exhaustive; add per-server allowlists for false positives
3. **Multi-process race on `.mcp.json` rewrite** — two `ai-toolkit install` invocations clobber each other → file lock during enable/disable
4. **Proxy supervisor fails to start on user's machine** — different distro / no systemd → ai-toolkit doctor must detect and report; degrade to "MCP proxy unavailable, falling through" with no functionality loss
5. **User has custom MCP server we don't recognize** — must work without per-server schema; default heuristics must be safe enough for arbitrary servers

## Estimate

- Architecture spike + working proxy prototype: 2 days
- Production proxy + supervisor + config + CLI: 3 days
- Test suite + fixtures + CI integration: 2 days
- Documentation + migration guide + release notes: 1 day

**Total: ~8 working days** (1.5–2 weeks calendar time at typical pace)

## Status

| Date | Status | Author |
|------|--------|--------|
| 2026-05-04 | PRD drafted from spike conclusions, carved out of v3.2.0 plan | claude |
| 2026-07-27 | Abandoned without implementation. Claude Code began deferring MCP tool schemas by default, removing the per-turn overhead this proxy targeted. Moved from `kb/planning/` to `kb/history/completed/`. | claude |

---

## kb/history/completed/native-tool-output-filter-plan.md

---
title: "Implementation Plan: Native Tool Output Filter"
category: planning
service: ai-toolkit
tags:
  - output-filter
  - hooks
  - recovery
  - performance
  - claude-code
doc_type: plan
status: completed
created: "2026-07-23"
last_updated: "2026-07-23"
completed: "2026-07-23"
completion: "100% of approved Claude Code scope; other runtimes remain manual-only by capability decision"
shipped_in: "Unreleased"
description: "Approved implementation plan and completion evidence for the original dependency-free ai-toolkit tool-output filter, including conservative profiles, exact recovery, telemetry, runtime capability gates, and adjacent repairs."
---

# Implementation Plan: Native Tool Output Filter

## Status

Completed on 2026-07-23 after user approval.

Completion evidence:

- 69 focused Python tests pass, including the production-wrapper benchmark.
- The 100-sample cold wrapper measures 63.565 ms p95 against the 75 ms gate.
- The 8 MiB profile case measures 4.354 ms p95 and 8,792,932 peak traced
  bytes against the 150 ms and 41,943,040 byte gates.
- The strict repository validator reports 44 agents, 108 skills, and 1477
  tests with zero errors or warnings.
- Ruff, mypy, ShellCheck, skill audit, generated artifacts, and the final
  repository test gate pass for the changed surface.

## Context

`ai-toolkit` currently controls assistant response length and reports real
Claude session tokens, but it does not transform live tool output before that
output reaches the model. The requested feature is an original, MIT-licensed,
dependency-free implementation inside `ai-toolkit`. RTK is research input only:
no runtime dependency, vendoring, translated code, copied filters, fixtures,
regex tables, CLI names, or configuration keys.

The first native integration targets Claude Code because current Claude hooks
support replacing successful tool output through
`PostToolUse.hookSpecificOutput.updatedToolOutput`. The transformer remains
strictly post-execution and cannot alter the command, arguments, environment,
working directory, permission decision, exit status, or signal.

This feature is separate from MCP `tools/list` description trimming. Hooks can
transform an executed tool result, but they do not intercept MCP catalog
metadata. [PATH: kb/history/completed/f2-mcp-trim-spike-20260504.md]
[PATH: kb/planning/mcp-context-trim-v4-prd.md]

Relevant local boundaries:

- Fixed lifecycle enforcement belongs in hooks. [PATH: CLAUDE.md:10]
- The current safety guards run in `PreToolUse`. [PATH: app/hooks.json:37]
- Hook runtime Python helpers are deployed explicitly.
  [PATH: scripts/install_steps/hooks.py:71]
- Runtime hook schemas differ by editor.
  [PATH: kb/reference/hooks-catalog.md:571]
- Existing output/token work intentionally uses native mechanisms.
  [PATH: kb/history/completed/output-token-discipline-plan-20260504.md]
- Claude hook contract:
  <https://code.claude.com/docs/en/hooks>

## Scope

### Included

- Python standard library implementation under `scripts/`.
- Pure post-execution transformation of successful textual Bash output.
- `off`, `observe`, and `safe` modes.
- Claude Code integration through `PostToolUse.updatedToolOutput`.
- Manual CLI for fixture inspection, status, recovery, and cleanup.
- Two initial deterministic profiles:
  - `repeat-lines`: aggregate adjacent identical non-diagnostic lines and state
    their multiplicity.
  - `tap-success`: compact valid successful TAP while retaining plan,
    directives, comments, totals, duration, and all diagnostic material.
- Byte and line savings, latency, outcome, profile ID, and profile version.
- Exact, bounded, session-scoped raw recovery when `safe` mode is enabled.
- Capability-gated adapters for additional runtimes after Phase 2.

### Excluded

- RTK binaries, libraries, source code, filters, fixtures, configuration, or
  branding.
- Command rewriting, `sh -c`, shell parsing, permission decisions, or command
  execution by the filter.
- LLM-generated summaries or network calls.
- Project-defined regex filters in the first release.
- Failed commands, non-empty `stderr`, signals, TTY/streaming output, binary or
  invalid text, pipes, redirects, security scanners, dependency audits,
  deployment, migrations, permission failures, and destructive-command
  diagnostics.
- `Read`, web results, arbitrary MCP results, and MCP `tools/list`.
- Claims that byte reduction equals billed-token or whole-session savings.

## Architecture

```text
PostToolUse payload
        |
        v
runtime adapter validates the native payload and output shape
        |
        +-- unsupported, disabled, unsafe, failed, or malformed --> no hook output
        |
        v
eligibility policy selects an explicit profile
        |
        v
pure deterministic transformer
        |
        v
invariant gate
  - mandatory facts preserved
  - no forbidden invention
  - deterministic and idempotent
  - at least 15% and 1 KiB smaller
        |
        +-- invariant failure --> exact raw passthrough + session circuit breaker
        |
        v
exact raw response written to bounded ephemeral recovery store
        |
        +-- recovery unavailable --> exact raw passthrough
        |
        v
hookSpecificOutput.updatedToolOutput
```

### Module layout

```text
scripts/
  tool_output_filter/
    __init__.py
    contracts.py
    engine.py
    hook_runtime.py
    input.py
    policy.py
    invariants.py
    recovery.py
    telemetry.py
    profiles/
      __init__.py
      repeat_lines.py
      tap_success.py
  output_filter_hook.py
  output_filter_cli.py
  benchmark_output_filter.py

app/
  hooks/
    filter-tool-output.sh
    session-end.sh
  hooks.json
  output-filter-policy.json

tests/
  fixtures/output-filter/
    repeat-basic/
    tap-basic/
    tap-diagnostic/
    ansi-adversarial/
  test_tool_output_filter.py
  test_tool_output_filter_cli.py
  test_tool_output_filter_properties.py
  test_tool_output_filter_recovery.py
  test_tool_output_filter_benchmark.py
  test_output_filter_config.bats
  test_output_filter_hook.bats

kb/reference/
  tool-output-filter.md
```

### Configuration contract

```json
{
  "toolOutputFilter": {
    "mode": "off",
    "profiles": ["repeat-lines", "tap-success"],
    "maxInputBytes": 8388608,
    "minSavingsBytes": 1024,
    "minSavingsRatio": 0.15,
    "recovery": {
      "mode": "ephemeral",
      "ttlMinutes": 60,
      "maxSessionBytes": 33554432
    }
  }
}
```

- `off`: no Python invocation and no metrics.
- `observe`: calculate an eligible result and metadata, but return no hook
  output, so the model receives the original bytes.
- `safe`: replace only output that passes every invariant and has exact raw
  recovery available.
- `AI_TOOLKIT_OUTPUT_FILTER_DISABLE=1`: global emergency bypass.
- Three consecutive runtime or invariant failures disable filtering for the
  current session and emit one bounded warning.
- All profiles remain explicit opt-in until GA evidence is reviewed.

### Recovery and privacy

- Store the exact original tool-response object, not a redacted approximation.
- Location:
  `~/.softspark/ai-toolkit/sessions/<repo-key>/output-filter/<session>/<opaque-id>`.
- Directory mode `0700`, file mode `0600`, exclusive no-follow creation,
  opaque random identifiers, atomic publication, quota, and TTL.
- Never store raw commands, paths, output, environment values, or session IDs
  in telemetry.
- Telemetry contains only profile ID/version, input/output byte and line
  counts, latency, outcome, and fallback reason.
- Session end, explicit clean, uninstall, and expired-TTL cleanup remove only
  ai-toolkit-owned recovery artifacts.
- If the platform cannot provide the secure-store contract, `safe` degrades to
  raw passthrough. It must not silently become lossy.

## Success Criteria

- [x] No new npm, pip, Cargo, system, or runtime dependency.
- [x] Shadow/observe mode is byte-identical for 100% of fixtures and native
      hook-contract test payloads.
- [x] Any exception, timeout, unsupported encoding, unknown profile, malformed
      payload, failed invariant, unavailable recovery store, non-zero exit,
      signal, or non-empty `stderr` returns the exact original output.
- [x] Every omission is marked with profile/version, original and emitted
      line counts, and an opaque exact-recovery handle.
- [x] Golden fixtures preserve 100% of declared mandatory facts and introduce
      zero non-marker facts.
- [x] Filter output is deterministic, idempotent, and never larger than raw.
- [x] Eligible fixtures achieve median reduction of at least 30%; replacement
      requires at least 15% and 1 KiB saved per call.
- [x] Hard input cap is 8 MiB; larger payloads pass through without parsing.
- [x] Algorithm p95 is at most 20 ms for 100 KiB and 150 ms for 8 MiB; cold
      end-to-end hook invocation p95 is at most 75 ms on CI reference runners.
- [x] Peak traced Python allocation is at most three times input size plus
      16 MiB.
- [x] No regex has unbounded catastrophic backtracking.
- [x] Claude Code `safe` mode is opt-in and can be disabled globally without
      reinstalling.
- [x] Additional runtimes activate only after their native result-replacement
      contract has captured fixtures and passing integration tests.
- [x] Full repository validation and test suite are green.

## Pre-Mortem

| Risk | Probability | Impact | Mitigation |
|---|---|---|---|
| A profile removes a discriminating fact | High | High | Mandatory-fact fixtures, adversarial sentinels, raw recovery, one regression disables the profile |
| A runtime changes its tool-output schema | Medium | High | Versioned adapters, strict shape validation, unknown shape returns no hook output |
| Filtering hides security or failure diagnostics | Medium | High | Explicit exclusion list, successful stdout-only MVP, failures always raw |
| Recovery leaks secrets or paths | Medium | High | Exact data only in opt-in ephemeral spool, `0700`/`0600`, no-follow, quota, TTL, complete cleanup |
| Hook latency degrades normal tool use | Medium | Medium | Bash fast-path, size threshold, hard cap, benchmark gates, circuit breaker |
| Command classification mishandles shell syntax | High | Medium | No command rewriting or execution, conservative allowlist, pipes/redirects bypass |
| Regex or parser behavior is locale/version-specific | Medium | High | Independently captured multi-version fixtures; malformed/localized output passes raw |
| Concurrent sessions corrupt metrics or recovery | Medium | Medium | Per-session directories, opaque IDs, atomic writes; do not reuse global `session-edits.json` |
| Runtime adapters diverge in safety behavior | High | High | Capability matrix and one adapter at a time; no guessed compatibility |
| Scope expands into MCP catalog proxying | Medium | Medium | Keep MCP trim as a separate PRD and release boundary |

## Tasks

### Phase 1: Observable vertical slice, no output mutation (M)

Success criteria:

- Claude PostToolUse payloads are parsed by a native Python stdlib engine.
- `off` and `observe` modes cannot change model-visible output.
- Independent fixture format and semantic oracle are operational.
- No raw tool output or command is persisted.

Tasks:

- [x] Define contracts, independent fixture provenance ledger, conservative
      eligibility rules, and clean implementation boundary.
      Owner: `infrastructure-architect`.
      Files: `kb/reference/tool-output-filter.md`,
      `tests/fixtures/output-filter/README.md`.
- [x] Implement pure engine, policy, invariants, `repeat-lines` candidate, and
      `tap-success` candidate in observe-only mode.
      Owner: `backend-specialist`.
      Files: `scripts/tool_output_filter/**`.
- [x] Add manual `inspect`, `status`, recovery, and cleanup CLI.
      Owner: `backend-specialist`.
      Files: `scripts/output_filter_cli.py`, `bin/ai-toolkit.js`.
- [x] Add Claude PostToolUse adapter last in hook order and deploy the Python
      runtime package with installed hooks.
      Owner: `command-expert`.
      Files: `app/hooks/filter-tool-output.sh`, `app/hooks.json`,
      `scripts/install_steps/hooks.py`.
- [x] Add `toolOutputFilter` schema, merge, validation, and effective-policy
      materialization; fix config-lock source/version/integrity staleness and
      the Article VII reserved-number mismatch while those files are open.
      Owner: `backend-specialist`.
      Files: `scripts/schemas/ai-toolkit-config.schema.json`,
      `scripts/config_merger.py`, `scripts/config_validator.py`,
      `scripts/config_lock.py`, `app/output-filter-policy.json`.
- [x] Build unit, property, hook-contract, malformed, binary, Unicode,
      ANSI/OSC, injection, huge-line, and concurrency tests.
      Owner: `test-engineer`.
      Files: `tests/test_tool_output_filter*.py`,
      `tests/test_tool_output_filter*.bats`,
      `tests/fixtures/output-filter/**`.

Rollback/scope cut:

- Remove the owned PostToolUse entry and deployed runtime package.
- If native payload fixtures are unstable, ship only the manual inspect CLI
  and fixture oracle; do not enable the hook.

### Phase 2: Claude Code safe mode with exact recovery (L)

Dependency: Phase 1 must pass all observe-mode and performance gates.

Success criteria:

- `safe` is explicit opt-in.
- Only successful, stdout-only, allowlisted text is replaceable.
- Exact raw recovery is available before replacement is emitted.
- Every failure path is byte-identical passthrough.

Tasks:

- [x] Promote `repeat-lines` and `tap-success` only after mandatory-fact,
      idempotence, determinism, and minimum-savings gates pass.
      Owner: `backend-specialist`.
      Files: `scripts/tool_output_filter/profiles/**`,
      `scripts/tool_output_filter/invariants.py`.
- [x] Implement bounded secure ephemeral recovery and exact `recover`/`clean`
      CLI operations.
      Owner: `security-architect`.
      Files: `scripts/tool_output_filter/recovery.py`,
      `scripts/output_filter_cli.py`.
- [x] Add session circuit breaker, metadata-only telemetry, TTL/quota cleanup,
      and owned-artifact removal.
      Owner: `backend-specialist`.
      Files: `scripts/tool_output_filter/telemetry.py`,
      `app/hooks/session-end.sh`, `scripts/uninstall.py`.
- [x] Verify safety precedence and that filtering cannot emit permission
      decisions, execute output, or change original tool input/status.
      Owner: `security-auditor`.
      Files: `tests/test_tool_output_filter.py`,
      `tests/test_tool_output_filter_recovery.py`,
      `tests/test_output_filter_hook.bats`.
- [x] Add deterministic benchmark corpus and enforce latency, memory, maximum
      input, and savings thresholds.
      Owner: `performance-optimizer`.
      Files: `scripts/benchmark_output_filter.py`,
      `benchmarks/output-filter/**`.

Rollback/scope cut:

- Global disable returns the hook to observe/raw behavior immediately.
- Per-profile disable preserves other validated profiles.
- If exact secure recovery is unavailable on a platform, that platform stays
  in `observe`; no weaker recovery implementation is accepted.
- If TAP cannot meet semantic gates, release only `repeat-lines`.

### Phase 3: Capability-gated runtime expansion (L)

Dependency: Phase 2 must complete Claude safe-mode dogfooding without a
confirmed semantic loss.

Success criteria:

- Each runtime has a documented capability: native replacement, observe-only,
  manual CLI, or unsupported.
- No adapter uses command rewriting or `additionalContext` as fake replacement.
- Each active adapter has captured native payload/output fixtures.

Tasks:

- [x] Build and document the capability matrix from current runtime contracts.
      Owner: `technical-researcher`.
      Files: `kb/reference/tool-output-filter.md`,
      `kb/reference/supported-tools-registry.md`.
- [x] Classify adapters one by one and keep OpenCode, Cursor, and the remaining
      runtimes manual-only because no independently verified native
      result-replacement contract passed the release boundary.
      Owner: `command-expert`.
      Files: `scripts/generate_opencode_plugin.py`,
      `scripts/generate_cursor_hooks.py`, runtime-specific fixture files.
- [x] Fix ignored OpenCode guard block propagation before adding its filter
      adapter.
      Owner: `backend-specialist`.
      Files: `scripts/generate_opencode_plugin.py`,
      `tests/test_opencode*.bats`.
- [x] Fix Gemini invalid-settings overwrite and non-atomic write before any
      Gemini filter adapter is attempted.
      Owner: `backend-specialist`.
      Files: `scripts/generate_gemini_hooks.py`,
      `tests/test_gemini.bats`.
- [x] Add per-runtime uninstall, rollback, user-hook preservation, failure, and
      schema-drift tests.
      Owner: `test-engineer`.
      Files: `tests/test_hooks_per_editor.bats`,
      `tests/test_*hooks*.bats`.

Rollback/scope cut:

- A runtime without safe native replacement remains manual CLI or
  observe-only.
- Any runtime-specific regression removes only its owned adapter.
- Cross-runtime uniformity is not a release requirement.

### Phase 4: Documentation and GA decision (M)

Dependency: Phases 1 and 2 are mandatory; Phase 3 may remain partial.

Success criteria:

- Dogfood evidence distinguishes eligible-output byte savings from actual
  session token receipts.
- Documentation lists exclusions, recovery sensitivity, and bypass procedure.
- `safe` remains opt-in unless a separate user-approved promotion decision is
  made.

Tasks:

- [x] Review available shadow/safe evidence, false-positive and
      circuit-breaker paths, and latency. No production Claude JSONL receipt
      evidence was collected in this implementation run, so documentation
      makes no token-savings claim and `safe` remains opt-in.
      Owner: `data-analyst`.
      Files: `kb/reference/tool-output-filter.md`,
      `kb/reference/stats.md`.
- [x] Update all hook counts, architecture references, CLI help, lifecycle
      catalog, README, changelog, generated instruction surfaces, and release
      notes.
      Owner: `documenter`.
      Files: `README.md`, `CLAUDE.md`, `ARCHITECTURE.md`,
      `app/ARCHITECTURE.md`, `kb/reference/architecture-overview.md`,
      `kb/reference/hooks-catalog.md`, `CHANGELOG.md`, `AGENTS.md`,
      `llms.txt`, `llms-full.txt`, `package.json`, `plugin.json`.
- [x] Re-read the complete diff for orphaned references, dead code, missing
      behavior coverage, stale docs, and unexpected generated changes.
      Owner: `code-reviewer`.
      Files: all changed files.

Rollback/scope cut:

- Release `observe` and manual CLI only if active-mode evidence is insufficient.
- Do not promote any profile to default without separate approval.

## Dependencies

```text
Phase 1 → Phase 2 → Phase 3 → Phase 4
                   └────────→ Phase 4 if runtime expansion is deferred
```

There are no circular dependencies. Phase 1 is shippable as diagnostics,
Phase 2 as Claude-only opt-in filtering, and Phase 3 as incremental
runtime-by-runtime support.

## Verification

Focused verification:

1. `python3 -m unittest discover -s tests -p 'test_tool_output_filter*.py'`
2. `bats tests/test_output_filter_config.bats tests/test_output_filter_hook.bats`
3. `python3 scripts/benchmark_output_filter.py`
4. `shellcheck --severity=warning app/hooks/*.sh`

Repository quality gates:

1. `npm run generate:all`
2. `python3 scripts/validate.py --strict`
3. `python3 scripts/audit_skills.py --ci`
4. `npm test`
5. `git diff --check`
6. Re-read `git diff` and confirm no orphaned references, missing tests, stale
   docs, copied upstream expressions, or new external dependencies.

Expected result: every command exits `0`, focused semantic fixtures report zero
missing mandatory facts and zero forbidden inventions, active replacements meet
the savings threshold, and all unsafe paths remain exact passthrough.

## Agent Assignments

| Responsibility | Agent | Model |
|---|---|---|
| Architecture and contracts | `infrastructure-architect` | Assigned tier, no override |
| Python engine and configuration | `backend-specialist` | Assigned tier, no override |
| Hook and runtime adapters | `command-expert` | Assigned tier, no override |
| Recovery threat model | `security-architect` | Assigned tier, no override |
| Security verification | `security-auditor` | Assigned tier, no override |
| Semantic and integration tests | `test-engineer` | Assigned tier, no override |
| Performance gates | `performance-optimizer` | Assigned tier, no override |
| Runtime contract research | `technical-researcher` | Assigned tier, no override |
| Evidence analysis | `data-analyst` | Assigned tier, no override |
| Documentation | `documenter` | Assigned tier, no override |
| Final diff review | `code-reviewer` | Assigned tier, no override |

## Independent-Implementation Boundary

- Implement from this plan, local ai-toolkit requirements, native runtime
  contracts, and independently captured command outputs.
- Do not consult or copy RTK source while implementing filters.
- Do not copy or transliterate identifiers, control flow, comments, regex
  tables, filter order, fixtures, messages, configuration keys, default values,
  benchmarks, or documentation wording.
- Record the origin and rationale of each filter rule in the fixture provenance
  ledger.
- If any upstream expression is intentionally adapted, stop and perform an
  Apache-2.0 attribution and NOTICE review before continuing.

---

## kb/history/completed/no-op-plugin-packs-removed-20260727.md

---
title: "Removed: Nine Plugin Packs That Installed Nothing"
category: planning
service: ai-toolkit
tags:
  - plugins
  - plugin-pack
  - measurement
  - postmortem
  - dead-code
doc_type: postmortem
status: completed
created: "2026-07-27"
last_updated: "2026-07-27"
shipped_in: "v4.20.0 (removal)"
description: "Nine of eleven plugin packs installed zero files, because every asset they declared already ships in the core install. Measured across both runtimes and all three profiles. Records what was removed, what survived, why the authoring guidance produced the problem, and the check that now prevents a repeat."
---

# Removed: Nine Plugin Packs That Installed Nothing

`csharp-pack`, `java-pack`, `kotlin-pack`, `ruby-pack`, `rust-pack`,
`swift-pack`, `frontend-pack`, `research-pack`, `security-pack` — removed in
v4.20.0. `memory-pack` and `enterprise-pack` stay.

## The measurement

`ai-toolkit install` into a throwaway `HOME`, then `plugin install <pack>`, on
each runtime. The number is what `plugin install` itself reports:

| Pack | claude | codex |
|---|---:|---:|
| `csharp-pack` | 0 | 0 |
| `java-pack` | 0 | 0 |
| `kotlin-pack` | 0 | 0 |
| `ruby-pack` | 0 | 0 |
| `rust-pack` | 0 | 0 |
| `swift-pack` | 0 | 0 |
| `research-pack` | 0 | 0 |
| `security-pack` | 0 | 0 |
| `frontend-pack` | 0 | **1** |
| **`memory-pack`** | **4** | **4** |
| **`enterprise-pack`** | **2** | **2** |

Cross-checked against the filesystem, not just the reported count: after core
install (108 skills, 44 agents, 4742 characters of hook config), installing
`rust-pack`, `security-pack`, `research-pack` or any language pack produced
`+0` skills, `+0` agents, `+0` bytes of `settings.json` and `+0` files under
`~/.softspark`.

Profiles make no difference. `minimal`, `standard` and `strict` all install the
same 108 skills and 44 agents, and packs add `+0` to each.

## Why

Every one of the nine declared only assets that already ship in core:

| Pack | Declared | All present in core? |
|---|---|---|
| `rust-pack` | `rust-patterns` | yes |
| `security-pack` | `review`, `security-patterns`, `panic`, `security-auditor`, `security-architect`, `code-reviewer` | yes |
| `research-pack` | `docs`, `research-mastery`, `plan`, `technical-researcher`, `fact-checker`, `search-specialist` | yes |

Since `ai-toolkit install` links every core skill and agent, a manifest that
names only core assets resolves to a set of things already installed. There is
nothing left to do, so nothing is done.

Eight of the nine owned no file but `README.md`. `security-pack`'s two hooks
were core's `guard-destructive.sh` and `quality-gate.sh`; `research-pack`'s was
core's `user-prompt-submit.sh`.

## The one that was not quite zero

`frontend-pack` installed exactly one file, on codex only:
`plugin-frontend-pack-post-tool-use.sh`. The pack owned no such file — it
declared core's `post-tool-use.sh`, which core's codex surface does not install,
so the pack copied it in under a pack-prefixed name.

That is a generic hook wearing a domain label, not frontend functionality. It
was removed with the pack. **If `post-tool-use` should run on codex, it belongs
in the core codex hook set**, and adding it there is a separate, honest change —
not a side effect of installing a pack named after a UI framework.

## The authoring rule that caused this

`app/skills/plugin-creator/SKILL.md` told pack authors:

> **MUST** reference existing toolkit assets before duplicating — packs extend,
> they do not fork

Read literally against a core install that ships everything, that instruction
produces a no-op every time. It was correct about avoiding forks and silent
about the pack needing to add anything. Nine packs followed it exactly.

The rule now reads that a pack **must install something the core install does
not**, with the verification spelled out, and the validation checklist carries a
line item requiring a non-zero file count on every runtime the pack claims.

## What survived, and what users lose

**Nothing.** Every skill and agent the nine packs named is a core asset, still
present, still installed, still triggering on the same conditions. A Rust
developer who had `rust-pack` installed keeps `rust-patterns`, because it was
never in the pack.

The two remaining packs are the two that own files:

- `memory-pack` — two hooks, `init_db.py`, `strip_private.py`, and its own
  `mem-search` skill. Verified working the same day: driving
  `observation-capture.sh` with a real payload wrote a row to the SQLite store.
- `enterprise-pack` — `status-line.sh` and `output-style.sh`, both its own.

## Process note

The removal was nearly made on a wrong measurement. The first pass concluded
"nine no-ops on every editor" after testing only four packs on the claude
surface. `tests/test_plugin.bats` contradicted it by asserting that
`frontend-pack` creates a file on codex — the test was right and the
measurement was incomplete. The full 11 × 2 matrix was only then run.

The existing test suite caught an error in a fresh measurement. That is worth
remembering next time a test looks like it is merely in the way of a cleanup.

## Related

- [Plugin Pack Conventions](../../reference/plugin-pack-conventions.md) — the rule this postmortem installed
- [Language Packs (removed)](language-packs-removed-20260727.md) — the reference doc for six of the nine
- [rtk-pack Retirement](rtk-pack-retirement-20260727.md) — the pack removed the day before, for a different reason

---

## kb/history/completed/offline-slm-profile-plan-20260411.md

---
title: "Plan: Offline-First SLM Profile — Lightweight Mode for Local Models"
category: planning
service: ai-toolkit
tags:
  - offline
  - slm
  - small-language-models
  - ollama
  - lm-studio
  - profile
  - context-optimization
  - privacy
doc_type: plan
status: completed
created: "2026-04-10"
last_updated: "2026-04-11"
completion: "100%"
completed: "2026-04-11"
description: "Lightweight profile for ai-toolkit optimized for Small Language Models (SLMs) running locally via Ollama, LM Studio, or similar. Compiles a minimal instruction set that fits within 4K-8K system prompt budgets while preserving critical safety guardrails. Targets air-gapped, privacy-first, and cost-sensitive development workflows."
---

# Plan: Offline-First SLM Profile — Lightweight Mode for Local Models

**Status:** Completed
**Completion:** 100%
**Completed:** 2026-04-11
**Created:** 2026-04-10
**Origin:** Enterprise IP security requirements (air-gapped environments), cost-sensitive solo developers, and the growing adoption of local models (Ollama, LM Studio, llamafile). Current toolkit emits 20K+ token system prompts that exceed SLM context windows and degrade small model performance.
**Estimated Effort:** 4-5 weeks (1 person)

---

## 1. Objective

Create a `--profile offline-slm` install profile and a `scripts/compile_slm.py` compiler that produces a minimal, high-signal instruction set optimized for Small Language Models (8B-32B parameters). The compiled output preserves critical safety guardrails while stripping agent orchestration, multi-agent coordination, and complex skill routing that SLMs cannot handle.

**Key design principles:**
- **Token budget** — compiled output fits within 4K tokens (system prompt), with optional 8K mode for larger SLMs
- **Safety-preserved** — Constitution Articles I-V always included (non-negotiable)
- **Single-agent focus** — no multi-agent orchestration, no /swarm, no /teams
- **Deterministic compilation** — same input → same output, no LLM involved in compilation
- **Model-aware** — detects model size from Ollama API or manual flag and adjusts verbosity
- **Platform-agnostic** — outputs plain markdown consumable by any local inference engine
- **Hooks stripped** — SLM providers don't support lifecycle hooks; rules compile into system prompt

---

## 1a. Functional Requirements

| ID | Requirement | Priority | Success Metric |
|----|-------------|----------|----------------|
| FR1 | Token counter (stdlib-only, ±10% accuracy target) | Must | Conservative estimate, no external deps |
| FR2 | Component parser + scorer with safety-priority ranking | Must | Constitution=1.0, all components scored |
| FR3 | Compression engine with 4 levels (ultra-light, light, standard, extended) | Must | Each level strips progressively less |
| FR4 | Budget packer (greedy knapsack by score/size ratio) | Must | Output ≤ budget × 0.95 in all cases |
| FR5 | Markdown emitter with safety-first structure | Must | Constitution always first in output |
| FR6 | `--profile offline-slm` install integration | Must | `install.py` + `manifest.json` updated |
| FR7 | `compile-slm` CLI command with flags | Must | `--budget`, `--model-size`, `--persona`, `--lang`, `--output`, `--format`, `--dry-run` |
| FR8 | Constitution always included (non-negotiable) | Must | Compilation fails if constitution exceeds budget alone |
| FR9 | Model size detection from Ollama API | Should | Auto-detect with graceful fallback to `14b` |
| FR10 | Persona-aware compilation (boost relevant skills) | Should | Persona skills ranked higher |
| FR11 | Language-aware compilation (include matching rules only) | Should | Non-matching language rules excluded |
| FR12 | Integration guides for 4 platforms (Ollama, LM Studio, Aider, Continue.dev) | Should | Step-by-step setup per platform |
| FR13 | Compile quality validator (post-compilation checks) | Should | FAIL on missing constitution, budget exceeded |
| FR14 | 4 output formats (raw markdown, Ollama Modelfile, JSON string, Aider-compatible) | Should | Each format usable by target tool |
| FR15 | `--dry-run` output showing included components + token counts | Should | Table: component, score, tokens, included? |

---

## 2. Architecture Overview

```
ai-toolkit install --profile offline-slm [--model-size 8b|14b|32b|70b]
ai-toolkit compile-slm [--budget 4096] [--persona backend-lead] [--lang typescript]

  ┌──────────────────────────────────────────────────────────┐
  │              offline-slm Profile                          │
  │                                                          │
  │  Compiler: scripts/compile_slm.py                        │
  │  Input:  full toolkit (agents, skills, rules, constitution)│
  │  Output: single compiled .md file for system prompt       │
  │                                                          │
  │  Token Budget Tiers:                                     │
  │    ultra-light (2K) — safety + persona only              │
  │    light (4K) — safety + persona + top skills + rules    │
  │    standard (8K) — safety + persona + full skills + rules │
  │    extended (16K) — near-full toolkit (for 32B+ models)   │
  │                                                          │
  │  Output Files:                                           │
  │    ~/.softspark/ai-toolkit/compiled/slm-system-prompt.md           │
  │    ~/.softspark/ai-toolkit/compiled/slm-skills-reference.md        │
  │    CLAUDE.md (or equivalent) — auto-generated            │
  │                                                          │
  │  Integration Targets:                                    │
  │    Ollama (modelfile SYSTEM directive)                    │
  │    LM Studio (system prompt field)                       │
  │    llamafile (--system-prompt flag)                       │
  │    Open WebUI (system prompt setting)                    │
  │    Aider (--system-prompt-file flag)                     │
  │    Continue.dev (system prompt in config)                │
  └──────────────────────────────────────────────────────────┘
```

### Compilation Pipeline

```
Full Toolkit (20K+ tokens)
         │
         ▼
  ┌─────────────────┐
  │ 1. Parse Phase   │  Read all agents, skills, rules, constitution
  └────────┬────────┘
           ▼
  ┌─────────────────┐
  │ 2. Rank Phase    │  Score components by: safety criticality × usage frequency × persona relevance
  └────────┬────────┘
           ▼
  ┌─────────────────┐
  │ 3. Compress Phase│  Strip: examples, rationalization tables, related skills, verbose headers
  └────────┬────────┘
           ▼
  ┌─────────────────┐
  │ 4. Budget Phase  │  Pack highest-scoring components until token budget reached
  └────────┬────────┘
           ▼
  ┌─────────────────┐
  │ 5. Emit Phase    │  Write compiled .md + integration instructions
  └─────────────────┘
```

---

## 3. Progress Tracking

| # | Feature | Priority | Status | Est. Time | Notes |
|---|---------|----------|--------|-----------|-------|
| 1.1 | Token counter (tiktoken-free, word-based estimator) | P0 | Proposed | 0.5d | ~0.75 tokens/word heuristic (stdlib only) |
| 1.2 | Component parser + scorer | P0 | Proposed | 2d | Parse frontmatter, score by criticality/frequency/persona |
| 1.3 | Compression engine | P0 | Proposed | 2d | Strip examples, rationalization tables, headers |
| 1.4 | Budget packer | P0 | Proposed | 1d | Greedy knapsack by score/size ratio |
| 1.5 | Emitter (markdown output) | P0 | Proposed | 1d | Clean compiled .md file |
| 2.1 | Profile integration (`--profile offline-slm`) | P0 | Proposed | 1.5d | Install.py + manifest.json + state.json |
| 2.2 | CLI command (`ai-toolkit compile-slm`) | P0 | Proposed | 1d | Standalone compilation with flags |
| 2.3 | Model size detection (Ollama API) | P1 | Proposed | 1d | Auto-detect model params from `ollama list` |
| 2.4 | Persona-aware compilation | P1 | Proposed | 1.5d | Boost persona-relevant skills in ranking |
| 2.5 | Language-aware compilation | P1 | Proposed | 1d | Include only matching language rules |
| 3.1 | Integration guides (Ollama, LM Studio, Aider, Continue) | P1 | Proposed | 1.5d | Step-by-step per platform |
| 3.2 | Compile quality validator | P1 | Proposed | 1d | Verify output covers constitution, fits budget |
| 3.3 | Tests | P1 | Proposed | 3d | Unit: compilation determinism, budget compliance, 4 compression levels × 4 output formats, constitution guard. Integration: `compile-slm --model-size 8b`, verify output fits 2048 tokens + constitution present end-to-end. Target: 40+ tests |
| 3.4 | Documentation | P1 | Proposed | 2.5d | All 9 docs per CLAUDE.md: README, CLAUDE.md, ARCHITECTURE.md, package.json, llms.txt, llms-full.txt, AGENTS.md, skills-catalog.md, architecture-overview.md + integration guide |

**Phasing:**
- **Phase 1 (week 1-2):** Compiler — parser, scorer, compressor, packer, emitter
- **Phase 2 (week 2-3):** Integration — profile, CLI, model detection, persona/language awareness
- **Phase 3 (week 3-4):** Polish — integration guides, validator, tests, documentation

> **Demand validation gate:** Ship Phase 1 + basic Phase 2 (compiler + profile + CLI with `--budget` and `--model-size` flags) as MVP. Test with 3 real models (8B, 14B, 32B). Only build persona/language-aware compilation and platform-specific integration guides if MVP validation confirms output quality.

---

## 4. Dependency Graph

```
                     Phase 1: Compiler (week 1-2)
                     ============================
Token counter (1.1) ────┐
                        ├──► Compression engine (1.3) ──► Budget packer (1.4) ──► Emitter (1.5)
Component parser (1.2) ──┘

                     Phase 2: Integration (week 2-3)
                     ================================
Profile integration (2.1) ──┐
                            ├──► CLI command (2.2)
Model detection (2.3) ──────┤
Persona-aware (2.4) ────────┤
Language-aware (2.5) ────────┘

                     Phase 3: Polish (week 3-4)
                     ===========================
                            ├──► Integration guides (3.1)
                            ├──► Compile validator (3.2)
                            └──► Tests + docs (3.3, 3.4)
```

---

## 5. Detailed Implementation

### Phase 1: Compiler Engine (week 1-2)

#### 1.1 Token Counter

**Stdlib-only token estimation** — no tiktoken, no external dependencies.

```python
def estimate_tokens(text: str) -> int:
    """Estimate token count from text without external dependencies.

    Uses two heuristics and returns the higher (conservative) estimate:
    1. Word-based: ~0.75 tokens/word for English prose
    2. Char-based: ~1 token per 4 chars (more accurate for code-heavy content)

    Accuracy target: ±10% vs tiktoken cl100k_base. To be validated on 50 toolkit files before shipping.
    """
    word_est = int(len(text.split()) * 0.75)
    char_est = len(text) // 4
    # Code blocks have higher token density — adjust
    code_blocks = text.count('```')
    code_penalty = code_blocks * 15
    return max(word_est, char_est) + code_penalty
```

**Why not tiktoken:** tiktoken requires a C extension and network download of the BPE file. This violates the stdlib-only constraint and fails in air-gapped environments (which is literally the target audience for this feature).

**Accuracy target:** ±10% vs tiktoken cl100k_base. Using `max(word, char)` gives a conservative estimate. We pack to budget × 0.95 (5% safety margin) to absorb estimation error.

---

#### 1.2 Component Parser + Scorer

**Parse all toolkit components into a unified scoring table:**

```python
@dataclass
class Component:
    name: str
    type: str          # 'constitution', 'agent', 'skill', 'rule', 'hook-equivalent'
    source_file: str
    full_text: str
    compressed_text: str  # after stripping (populated by compressor)
    tokens_full: int
    tokens_compressed: int
    score: float       # 0.0 - 1.0

    # Scoring factors
    safety_criticality: float   # 0.0-1.0 (constitution=1.0, guard hooks=0.9)
    usage_frequency: float      # 0.0-1.0 (from stats.json, normalized)
    persona_relevance: float    # 0.0-1.0 (match against active persona)
    language_relevance: float   # 0.0-1.0 (match against project language)
```

**Scoring formula:**
```python
score = (
    safety_criticality * 0.40 +    # Safety always dominates — non-negotiable content gets priority
    usage_frequency * 0.25 +       # Frequently used = valuable — from stats.json invocation counts
    persona_relevance * 0.20 +     # Persona-matched = valuable — e.g. backend-lead boosts API skills
    language_relevance * 0.15      # Language-matched = contextual — include only relevant rules
)
# Weight rationale: safety must dominate (0.40) to guarantee constitution + guard rules always fit.
# Usage + persona (0.45 combined) ensure the most practical content fills remaining budget.
# Language (0.15) is a tiebreaker — most projects use 1-2 languages.
# Weights are compile-time constants in v1. If empirical testing (5 standard tasks across
# 3 model sizes) shows suboptimal results, expose as --score-weights flag in v2.
```

**Fixed-score components (always included):**

| Component | Score | Reason |
|-----------|-------|--------|
| Constitution (Articles I-V) | 1.0 | Non-negotiable safety |
| Guard hooks (destructive, path) | 0.95 | Core safety rules (compiled as text, not hooks) |
| Active persona definition | 0.90 | User-selected identity |
| Active language rules | 0.85 | Project-specific quality gates |

**Dynamic-score components:**

| Component | Base Score | Adjusted By |
|-----------|-----------|-------------|
| Individual skills | 0.3-0.7 | Usage frequency + persona fit |
| Agent definitions | 0.2-0.6 | Persona relevance (only 1 agent in SLM mode) |
| Knowledge skills | 0.2-0.5 | Language match + persona match |
| Iron Law rules | 0.7 | Always high (quality enforcement) |

---

#### 1.3 Compression Engine

**Strip low-signal content while preserving semantics:**

| Strip Target | Savings (est.) | Example |
|-------------|---------------|---------|
| `## Common Rationalizations` tables | 200-400 tokens/skill | 15 skills have these tables |
| `## Related Skills` sections | 50-100 tokens/skill | Routing not useful for SLMs |
| `## Verification Checklist` (keep 1-liner summary) | 100-200 tokens/agent | Compress to "Verify: tests pass, no placeholders" |
| Markdown headers (collapse hierarchy) | 20-50 tokens/file | `### 2.1.3 Sub-feature` → plain paragraph |
| Example code blocks (keep first, strip rest) | 100-500 tokens/skill | Keep 1 example max |
| Frontmatter (YAML) | 50-100 tokens/file | Strip entirely from compiled output |
| Agent `## Allowed CLI Commands` lists | 200-400 tokens/agent | Not needed when agent won't execute them |
| Multi-agent coordination instructions | 300-500 tokens | SLM = single agent, no /orchestrate |
| Effort-based budgeting rules | 100 tokens | SLM doesn't manage budgets |

**Compression levels:**

```python
COMPRESSION_LEVELS = {
    'ultra-light': {
        'strip_examples': True,
        'strip_rationalizations': True,
        'strip_related_skills': True,
        'strip_verification': True,
        'strip_agent_commands': True,
        'strip_multi_agent': True,
        'max_skills': 5,         # Only top 5 skills by score
        'max_agents': 0,         # No agent definitions (persona only)
        'include_rules': False,
    },
    'light': {
        'strip_examples': True,
        'strip_rationalizations': True,
        'strip_related_skills': True,
        'strip_verification': 'summary',  # 1-liner
        'strip_agent_commands': True,
        'strip_multi_agent': True,
        'max_skills': 10,
        'max_agents': 1,         # Persona agent only
        'include_rules': True,
    },
    'standard': {
        'strip_examples': 'first-only',  # Keep 1 example
        'strip_rationalizations': True,
        'strip_related_skills': True,
        'strip_verification': 'summary',
        'strip_agent_commands': True,
        'strip_multi_agent': True,
        'max_skills': 20,
        'max_agents': 3,
        'include_rules': True,
    },
    'extended': {
        'strip_examples': 'first-only',
        'strip_rationalizations': 'first-only',
        'strip_related_skills': False,
        'strip_verification': False,
        'strip_agent_commands': False,
        'strip_multi_agent': True,  # Still stripped for SLMs
        'max_skills': 40,
        'max_agents': 5,
        'include_rules': True,
    },
}
```

---

#### 1.4 Budget Packer

**Greedy knapsack algorithm:** Sort components by `score / compressed_tokens` ratio (value density), pack until budget exhausted.

```python
def pack_components(components: list[Component], budget: int) -> list[Component]:
    """Pack highest-value components into token budget."""
    # Fixed components always included (constitution, persona, language rules)
    fixed = [c for c in components if c.score >= 0.85]
    remaining_budget = budget - sum(c.tokens_compressed for c in fixed)

    # Sort remaining by value density
    dynamic = sorted(
        [c for c in components if c.score < 0.85],
        key=lambda c: c.score / max(c.tokens_compressed, 1),
        reverse=True
    )

    packed = list(fixed)
    for comp in dynamic:
        if comp.tokens_compressed <= remaining_budget:
            packed.append(comp)
            remaining_budget -= comp.tokens_compressed

    return packed
```

**Budget validation:** After packing, verify total tokens ≤ budget × 0.95 (5% safety margin for tokenizer estimation error).

**Constitution budget guard:** Before packing dynamic components, verify that fixed components (constitution + persona + language rules) fit within the budget. If `sum(fixed.tokens_compressed) > budget`, fail with: `"Constitution + safety rules alone exceed {budget} token budget. Minimum safe budget: {required}. Use --budget {required} or higher."` This prevents silent omission of safety-critical content.

---

#### 1.5 Emitter

**Output:** Single markdown file structured for maximum SLM comprehension.

```markdown
# AI Coding Assistant — System Instructions

## Safety Rules (MANDATORY)
[Compiled constitution — always first, highest attention position]

## Your Identity
[Compiled persona — who you are, what you focus on]

## Coding Standards
[Compiled language rules — active language only]

## Key Skills
[Top N skill summaries — compressed, actionable]

## Quality Checklist
[Compiled from Iron Laws + verification — bullet points only]
```

**Why this structure:**
- Safety first = maximum attention weight in transformer architecture
- Identity second = establishes persona before task instructions
- Standards = project-specific rules that shape code output
- Skills at end = reference material, lower attention needed

---

### Phase 2: Integration (week 2-3)

#### 2.1 Profile Integration

**manifest.json addition:**
```json
{
  "profiles": {
    "offline-slm": ["core"],
    "offline-slm-extended": ["core", "agents"]
  }
}
```

**Install behavior:**
```bash
ai-toolkit install --profile offline-slm

# What happens:
# 1. Standard install of core components
# 2. Runs compile_slm.py with auto-detected settings
# 3. Writes compiled output to ~/.softspark/ai-toolkit/compiled/
# 4. Generates integration instructions for detected local model tools
# 5. state.json records profile as "offline-slm"
```

**No hooks installed:** SLM providers (Ollama, LM Studio) don't support lifecycle hooks. The critical hook behavior (destructive command guard, path guard) is compiled into the system prompt text as rules.

---

#### 2.2 CLI Command

```bash
ai-toolkit compile-slm                              # auto-detect model, default budget
ai-toolkit compile-slm --budget 4096                 # explicit token budget
ai-toolkit compile-slm --budget 8192 --persona backend-lead  # persona + budget
ai-toolkit compile-slm --model-size 8b               # auto-select budget for 8B model
ai-toolkit compile-slm --model-size 32b              # auto-select budget for 32B model
ai-toolkit compile-slm --lang typescript,python       # include specific language rules
ai-toolkit compile-slm --output ./my-system-prompt.md # custom output path
ai-toolkit compile-slm --dry-run                     # show what would be included + token counts (table format below)

# --dry-run output format:
# Budget: 4096 tokens | Level: light | Persona: backend-lead
# ┌────────────────────────────┬──────────┬────────┬──────────┐
# │ Component                  │ Score    │ Tokens │ Included │
# ├────────────────────────────┼──────────┼────────┼──────────┤
# │ Constitution (Articles I-V)│ 1.00     │ 420    │ YES      │
# │ Persona: backend-lead      │ 0.90     │ 180    │ YES      │
# │ Rule: coding-style         │ 0.85     │ 310    │ YES      │
# │ Skill: /review             │ 0.68     │ 290    │ YES      │
# │ ...                        │ ...      │ ...    │ ...      │
# │ Skill: /deploy             │ 0.22     │ 350    │ NO (budget)│
# └────────────────────────────┴──────────┴────────┴──────────┘
# Total: 3,840 / 4,096 tokens (93.7% utilization)
ai-toolkit compile-slm --format ollama               # output as Ollama Modelfile SYSTEM block
ai-toolkit compile-slm --format json-string          # JSON-escaped string (for config files)
ai-toolkit compile-slm --format raw                  # plain markdown (default)
```

**Model size → budget mapping:**

Note: budget is about *effective instruction following capacity*, not context window. A 128K-context 8B model can *hold* 16K system prompt tokens, but cannot *follow* them reliably. Empirically, SLMs degrade when system prompt exceeds ~10-15% of their effective capacity.

```python
MODEL_BUDGETS = {
    '7b':  {'budget': 2048, 'level': 'ultra-light'},   # Llama 3.1 8B, Mistral 7B
    '8b':  {'budget': 2048, 'level': 'ultra-light'},
    '14b': {'budget': 4096, 'level': 'light'},          # Qwen 2.5 14B, Phi-3 14B
    '32b': {'budget': 8192, 'level': 'standard'},       # Qwen 2.5 32B, Mixtral 8x7B
    '70b': {'budget': 16384, 'level': 'extended'},      # Llama 3.1 70B
}
```

---

#### 2.3 Model Size Detection

**Auto-detect from Ollama:**
```python
def detect_model_size() -> str | None:
    """Detect running model size from Ollama API."""
    try:
        # curl http://localhost:11434/api/tags
        resp = urllib.request.urlopen('http://localhost:11434/api/tags', timeout=2)
        data = json.loads(resp.read())
        models = data.get('models', [])
        if models:
            # Extract parameter count from model name: "llama3.1:8b" → "8b"
            latest = models[0]['name']
            match = re.search(r'(\d+)[bB]', latest)
            if match:
                return match.group(0).lower()
    except (urllib.error.URLError, TimeoutError, json.JSONDecodeError):
        pass
    return None
```

**Fallback:** If no model detected, use `14b` defaults (4K budget, light compression). User can override with `--model-size`.

---

### Phase 3: Polish (week 3-4)

#### 3.1 Integration Guides

Per-platform setup instructions generated by the compiler.

**Ollama:**
```bash
# 1. Compile system prompt
ai-toolkit compile-slm --format ollama --model-size 8b > Modelfile.ai-toolkit

# 2. Create custom model
ollama create my-coder -f Modelfile.ai-toolkit

# 3. Use
ollama run my-coder "implement the payment API"
```

**LM Studio:**
```
1. ai-toolkit compile-slm --model-size 14b
2. Open LM Studio → Chat → System Prompt
3. Paste contents of ~/.softspark/ai-toolkit/compiled/slm-system-prompt.md
```

**Aider:**
```bash
ai-toolkit compile-slm --output .aider.system-prompt.md --model-size 32b
aider --model ollama/qwen2.5-coder:32b --system-prompt-file .aider.system-prompt.md
```

**Continue.dev:**
```bash
# 1. Compile to a local file
ai-toolkit compile-slm --model-size 14b

# 2. In .continue/config.json, paste the compiled content into systemMessage
#    (Continue.dev does not support file references — content must be inline)
#    Use: ai-toolkit compile-slm --format json-string to get escaped output
```

---

#### 3.2 Compile Quality Validator

Post-compilation checks:

| Check | Severity | Description |
|-------|----------|-------------|
| Constitution present | FAIL | Articles I-V must be in output |
| Budget exceeded | FAIL | Token count > budget |
| Persona missing (when specified) | WARN | Persona definition not included |
| No language rules included | WARN | Project language not detected |
| Less than 3 skills included | WARN | Very minimal — may be too sparse |
| Output empty | FAIL | Compilation produced no content |

---

## 6. File Summary

| File | Action | LOC (est.) | Description |
|------|--------|------------|-------------|
| `scripts/compile_slm.py` | CREATE | ~500 | Main compiler — orchestrates pipeline: parse → score → compress → pack → emit. Contains `Component` dataclass, scorer, and budget packer |
| `scripts/slm_token_counter.py` | CREATE | ~50 | Token estimation (stdlib only) — `estimate_tokens()` function used by compiler and validator |
| `scripts/slm_compression.py` | CREATE | ~300 | Compression engine — strip/summarize functions per content type, compression level configs (`COMPRESSION_LEVELS` dict) |
| `scripts/slm_integration.py` | CREATE | ~150 | Platform-specific output formatters — Ollama Modelfile, JSON-escaped string, raw markdown, Aider-compatible |
| `bin/ai-toolkit.js` | EDIT | +10 | Register `compile-slm` command |
| `scripts/install.py` | EDIT | +30 | Handle `--profile offline-slm` |
| `manifest.json` | EDIT | +5 | Add offline-slm profile |
| `kb/reference/offline-slm-guide.md` | CREATE | ~200 | Integration guides for all platforms |
| `tests/test_compile_slm.bats` | CREATE | ~150 | Compilation tests |
| `tests/test_slm_budgets.bats` | CREATE | ~80 | Budget compliance tests |
| **Total** | | **~1575** | |

---

## 6a. Non-Functional Requirements

| Category | Requirement |
|----------|-------------|
| **Performance** | Compilation < 2 seconds. No network calls during compilation (all data local). |
| **Accuracy** | Token estimation ±10% vs tiktoken cl100k_base. Budget compliance: output ≤ budget × 0.95. |
| **Determinism** | Same input (agents, skills, rules, persona, language, budget) → identical output. No randomness. |
| **Security** | Constitution Articles I-V always present in output — compilation fails if they exceed budget alone. |
| **Offline** | Zero network dependencies. Ollama auto-detection gracefully fails to manual fallback. |
| **Portability** | Output is plain markdown — consumable by any tool accepting a system prompt string/file. |
| **Quality gates** | `ruff check scripts/compile_slm.py scripts/slm_*.py` (0 errors), `mypy --strict scripts/compile_slm.py scripts/slm_*.py` (0 errors). Run before every commit. |
| **Type safety** | 100% public API type hints (all function signatures). `Component` dataclass fully typed. Scoring functions use typed parameters, not bare `dict`. |

---

## 6b. Cache Invalidation & Recompile Triggers

Compiled output (`~/.softspark/ai-toolkit/compiled/slm-system-prompt.md`) is a **derived artifact** — it must be recompiled when inputs change:

| Trigger | Action |
|---------|--------|
| `ai-toolkit update` | Auto-recompile if profile is `offline-slm` |
| `ai-toolkit install --profile offline-slm` | Always compile |
| Agent/skill/rule files changed (detected via mtime) | Warn: "Compiled SLM prompt may be stale. Run `ai-toolkit compile-slm`" |
| Manual `ai-toolkit compile-slm` | Always recompile |

Compiled output includes a header comment: `<!-- Compiled: 2026-04-10T10:30:00Z | Budget: 4096 | Level: light | Persona: backend-lead -->` for staleness detection.

---

## 6b-bis. Rollback & Removal

The offline-slm feature is purely additive — removing it is trivial:
1. Delete `scripts/compile_slm.py`, `scripts/slm_token_counter.py`, `scripts/slm_compression.py`, `scripts/slm_integration.py`
2. Remove `"offline-slm"` and `"offline-slm-extended"` from `manifest.json` profiles
3. Remove `compile-slm` from `SCRIPT_COMMANDS` in `bin/ai-toolkit.js`
4. Delete `~/.softspark/ai-toolkit/compiled/` directory (user-side)
5. No hooks, no state files, no config entries to clean up

---

## 6c. Quality Gate Degradation Notice

**Important:** The `offline-slm` profile strips lifecycle hooks because SLM providers don't support them. This means:

- No pre-commit quality check (ruff/tsc/mypy)
- No destructive command interception (guard hooks)
- No session context preservation

Guard hook behavior is **compiled into the system prompt as text rules** — the SLM is *instructed* not to run destructive commands, but unlike hook-based enforcement, this is advisory, not blocking.

Documentation must clearly state: **"SLM mode trades enforcement for guidance. Safety rules are present but not machine-enforced."**

For teams needing enforcement, recommend `--profile offline-slm` combined with a Git pre-commit hook (`.git/hooks/pre-commit`) that runs lint/type-check independently of the AI tool.

---

## 7. Success Criteria (Overall)

| Metric | Target |
|--------|--------|
| Budget tiers | 4 (ultra-light 2K, light 4K, standard 8K, extended 16K) |
| Token budget compliance | 100% (output ≤ budget in all cases) |
| Constitution inclusion | 100% (always present, all 5 articles) |
| Compilation time | < 2 seconds |
| Model size auto-detection | Ollama API (with graceful fallback) |
| Output formats | 4 (raw markdown, Ollama Modelfile, JSON-escaped string, Aider-compatible) |
| Integration guides | 4 platforms (Ollama, LM Studio, Aider, Continue.dev) |
| Persona support | 4 personas (backend-lead, frontend-lead, devops-eng, junior-dev) |
| Language rule support | 13 languages (all existing rules) |
| External dependencies | 0 (stdlib Python only) |
| Tests | 40+ |

---

## 8. Risks and Mitigation

| Risk | Probability | Impact | Mitigation |
|------|-------------|--------|------------|
| Token estimation too inaccurate | Medium | Medium | Validate against tiktoken on 50 files, target ±10% |
| Compiled prompt too compressed — loses meaning | Medium | High | Validate with 8B model on 5 standard tasks; if quality drops, increase minimum budget |
| Ollama API changes | Low | Low | Graceful fallback to manual `--model-size` |
| User expects full toolkit features with SLM | Medium | Medium | Clear documentation: "SLM mode = safety + coding standards, not multi-agent orchestration" |
| Air-gapped environment can't run `ai-toolkit compile-slm` | Low | Medium | Pre-compile during `install` when network is available; compiled output is self-contained |
| Constitution text changes break compiled cache | Low | Low | Recompile on every `ai-toolkit update` |

---

## 9. Pre-Mortem

1. **"Compiled prompt is too generic"** — without the full agent definitions, the SLM may produce generic code that doesn't match project conventions. Mitigation: Language rules and persona have highest priority after constitution — they provide project-specific context.
2. **"Users expect /review to work with 8B model"** — Skill invocations won't be available via SLM providers that lack hook support. Mitigation: Compiled output includes skill *knowledge* as rules, not invocable commands. Clear docs: "Skills are compiled as coding standards, not slash commands."
3. **"Model detects wrong size"** — Ollama model naming is inconsistent (`llama3.1:8b` vs `codellama:7b-instruct`). Mitigation: regex extracts any `\d+[bB]` pattern; fallback to `14b` if ambiguous.
4. **"Other local inference tools emerge"** — Jan.ai, GPT4All, Tabby, etc. Mitigation: Raw markdown output works with any tool that accepts a system prompt file.
5. **"Nobody uses the feature"** — SLM adoption among professional developers may be niche. Mitigation: Low effort (3-4 weeks), high signaling value ("we support air-gapped environments"), enterprise sales enabler.

---

## 10. Market Positioning

**Target users:**
1. **Enterprise (air-gapped)** — financial services, defense, healthcare firms that cannot send code to cloud LLM APIs
2. **Privacy-conscious solo devs** — developers who don't want code leaving their machine
3. **Cost-sensitive teams** — startups that can't afford Anthropic/OpenAI API costs at scale
4. **Offline-first** — developers working on trains, planes, or in regions with poor connectivity

**Competitive advantage:** No existing AI coding toolkit provides a compilation pipeline that adapts its instruction set to model capacity. This is a first-mover feature.

---

## 11. Next Actions

1. [ ] Approve plan
2. [ ] Implement token counter (1.1)
3. [ ] Implement component parser + scorer (1.2)
4. [ ] Implement compression engine (1.3)
5. [ ] Implement budget packer + emitter (1.4, 1.5)
6. [ ] Integrate profile into install.py + manifest.json (2.1)
7. [ ] Create CLI command `compile-slm` (2.2)
8. [ ] Add Ollama model detection (2.3)
9. [ ] Add persona + language aware compilation (2.4, 2.5)
10. [ ] Write integration guides for 4 platforms (3.1)
11. [ ] Compile quality validator (3.2)
12. [ ] Tests + documentation (3.3, 3.4)

---

## 12. Future

| Feature | Rationale |
|---------|-----------|
| Automatic recompile on file changes (file watcher) | v1 uses manual recompile + staleness warning |
| Quality benchmarks (run 5 standard tasks, measure output quality per budget tier) | Validate compilation quality empirically before shipping |
| Plugin-aware compilation (include memory-pack prompts if installed) | Depends on plugin system maturity |
| Model-specific prompt templates (different SLM families prefer different instruction styles) | Needs empirical testing across model families |
| `--profile offline-slm --enforce-git-hooks` (install git pre-commit hook for quality gates) | Compensates for stripped lifecycle hooks |

---

## 13. Cross-Plan Dependencies

This plan shares modification targets with the Enterprise Config plan:

| Shared File | This Plan | Enterprise Config Plan |
|-------------|-----------|----------------------|
| `scripts/install.py` | +30 LOC (offline-slm profile) | +80 LOC (extends resolution) |
| `manifest.json` | +5 LOC (offline-slm profile) | +10 LOC (schema refs) |
| `bin/ai-toolkit.js` | +10 LOC (compile-slm command) | +40 LOC (config subcommands) |

**If implementing in parallel:** this plan has the smallest changes to shared files — merge first to minimize conflicts.

**Enterprise Config interaction:** If Enterprise Config ships, `compile-slm` should respect the `extends` chain — compile the merged config, not just local. Add a `--ignore-extends` flag for air-gapped environments without access to the base config.

---

**Last Updated:** 2026-04-10

---

## kb/history/completed/output-filter-retirement-20260726.md

---
title: "Retirement: Native Tool-Output Filter — Measured 0% and Removed"
category: planning
service: ai-toolkit
tags:
  - output-filter
  - token-reduction
  - postmortem
  - measurement
  - claude-code
doc_type: postmortem
status: completed
created: "2026-07-26"
last_updated: "2026-07-26"
shipped_in: "v4.17.0 (removal)"
description: "Why the native tool-output filter shipped in v4.16.0 was removed in v4.17.0: measured 0.0000% whole-session token saving on real traffic, because agent-issued commands are compound and the design accepted only simple registered shapes."
---

# Retirement: Native Tool-Output Filter

**Shipped:** v4.16.0 (2026-07-23). **Removed:** v4.17.0 (2026-07-26).

## The number

Measured whole-session input-token saving: **0.0000%**.

Real Bash results from local Claude Code transcripts were replayed through the
shipped classifier and the full filter registry. The filters ran on the actual
captured output; this is a measurement, not an estimate.

| Scope | Value |
|---|---:|
| Transcripts replayed | 134, across 22 distinct projects |
| Successful Bash results | 7600 |
| Of those, parsed as a simple command shape | 145 (1.9%) |
| Of those, matched a registered shape | 18 (0.24%) — 16 `git diff`, 2 `git show` |
| Accepted by any filter | **0** |
| Bytes saved | **0** |

The classifier was verified working before the result was accepted: `git
status`, `git log -n 20`, `pytest -v`, `bats --tap`, and `npm test` each
produced exactly one candidate. The zero is real.

## Why: the premise, not the implementation

Seventeen filters were correct. They cleared their byte floors on owned
fixtures (44–95% reduction), stayed inside every latency budget at the 8 MiB
engine cap, passed adversarial safety review, and never once compressed a
failure. None of that mattered, because the commands they were built for are
not the commands that get issued.

95% of successful Bash invocations are compound. The byte pool breaks down as:

| Class | Share of compound bytes | Why the filter refused it |
|---|---:|---|
| `;` chain | 44.3% | multiple output producers, attribution ambiguous |
| multiline script | 29.1% | rejected at the raw-string boundary |
| pipeline | 12.7% | the pipe transformed the output |
| `&&` chain with producing segments | 5.6% | multiple output producers |
| redirect, substitution | 4.4% | rejected at the raw-string boundary |
| heredoc | 3.5% | rejected at the raw-string boundary |

Every one of those refusals was the correct safety decision in isolation.
Together they excluded the entire population.

The most-frequent single shape was `cd <path> && …`, at 375 results and 480 KB.
A bounded `cd`-prefix subset had already been designed, threat-modelled, and
measured during Phase 3, and it was dropped because it covered 0.00% of the
compound pool. The retirement measurement confirms why: of those 375 results,
only 5 had a single simple second segment, and those 5 produced 0 bytes of
output.

## What was already rejected on the way, and still stands

- **Read-result coverage: rejected on the `Edit` exact-match hazard.** On
  670.7 KB of real Read content, adjacent-duplicate collapse saves 0.00%,
  blank-run collapse 0.04%, trailing-whitespace 0.00%. Anything above noise
  requires elision, and 80.7% of `Edit` old-strings target a file read earlier
  in the same session, 63.4% of them multi-line byte-exact quotes. A Read
  result asserts what is on disk, so omission is a false claim rather than a
  summary.
- **Compound-command subset: designed, measured at 0.00% coverage, dropped.**
  The pipeline-truncator shape failed on an inversion: a truncated document
  parses cleanly exactly where the shape would pay, and rejects exactly where
  truncation is detectable.

## The process lesson

The plan validated its **design** exhaustively across five phases and its
**premise** not at all until the fifth. Fixtures measured the filter; only real
traffic measured the value, and the two disagreed by two orders of magnitude.

The end-to-end replay that produced the 0% took under an hour and could have
run on day one, before any filter existed. Any future plan of this shape must
put premise validation in Phase 0, with a kill number published before the
measurement rather than argued after it.

## Evaluated as a replacement: rtk

`rtk` (https://github.com/rtk-ai/rtk, Apache-2.0) rewrites commands at
`PreToolUse` rather than filtering output afterwards, which is the mechanism
this project's own safety contract had excluded. Its rewrite pipeline was
ported and validated against 197 of its own test assertions (197/197 exact
agreement), then applied to the same traffic:

- addresses **31.5%** of successful Bash bytes, **9.7%** of all tool-result
  bytes — genuinely non-zero, so the in-house 0% was a coverage failure rather
  than a law of nature;
- projected saving is **0.32–0.48%** of session input tokens on rtk's own
  60–90% claim, and **0.15–0.21%** once its filters' actual behaviour is
  modelled;
- its two largest families here under-deliver: `rtk read` returns files
  verbatim at the default `--level none`, and `rtk grep` models at 12.3%
  against a claimed 75%;
- custom TOML filters, the documented extension point, would reach 1.91% of
  Bash bytes. The large misses are structurally unreachable from config:
  `| head` and `| tail` (34.6%) are blocked by the pipeline-final rule, and
  `sed` (19.4%) sits in the hard-ignored prefix list.

Not adopted.

## Where the tokens actually are

The measurement points somewhere other than command output. In this traffic,
`Read` is 53.8% of tool-result bytes, and within Bash the two largest buckets
are `sed` used as a file reader (16.2%) and `| head` / `| tail` pipeline tails
(34.6%). Those are file-reading patterns, not tool reports. Any future attempt
at token reduction should start there, and should start by measuring.

---

## kb/history/completed/output-token-discipline-plan-20260504.md

---
title: "Plan: Output & Token Discipline — Concise Modes, MCP Trim, Token Receipts"
category: planning
service: ai-toolkit
tags:
  - brand-voice
  - output-style
  - mcp
  - statusline
  - token-tracking
  - hooks
  - briefing
doc_type: plan
status: completed
created: "2026-05-04"
last_updated: "2026-05-04"
completed: "2026-05-04"
completion: "100% of v3.2.0 scope (F2 deferred to v4.0 per spike conclusion)"
shipped_in: "v3.2.0"
description: "Three coordinated extensions to ai-toolkit that reduce token usage and surface real cost data: (1) brand-voice output modes for concise/strict Claude responses, (2) MCP description trimmer to compact tool listings before they reach the model, (3) token receipts in statusline reading session JSONL directly. Native extensions, no third-party skill names imported."
---

# Plan: Output & Token Discipline

**Status:** Completed (shipped in v3.2.0 on 2026-05-04)
**Author:** lukasz.krzemien
**Source of inspiration:** external Claude Code plugin observed 2026-05-04 (mechanism only, not naming or branding)
**Spike companion:** [`kb/history/completed/f2-mcp-trim-spike-20260504.md`](f2-mcp-trim-spike-20260504.md)

## Cel

Zmniejszyć realne zużycie tokenów w sesjach Claude Code i dać użytkownikowi widoczność tego zużycia w czasie rzeczywistym. Trzy mechanizmy działające razem, każdy jako natywne rozszerzenie istniejących komponentów ai-toolkit (`brand-voice`, `briefing`, `track-usage.sh`). Bez importowania obcych nazw — adaptacja idei jako własnych.

## Kontekst

Obecnie ai-toolkit ma:

- `brand-voice` skill — pilnuje stylu pisanego (docs, README, content)
- `track-usage.sh` hook — liczy `/skill` invocations do `~/.softspark/ai-toolkit/stats.json`
- `compile_slm.py` — kompresuje cały toolkit dla małych modeli (inny scope)
- 113 skilli, pełen system hooków, doctor, eject

Brakuje:

- Trybu zwięzłego dla *odpowiedzi* Claude'a (brand-voice działa tylko dla pisanej zawartości)
- Kompresji opisów MCP-tooli, które zżerają setki tokenów na każdym wywołaniu
- Realnego pomiaru tokenów per sesja (mamy tylko licznik invocations, nie tokenów)

## Zakres

Trzy features, zaplanowane w kolejności narastającego ryzyka.

---

## Feature 1 — `brand-voice` output modes

### Cel
Rozszerzyć `brand-voice` o tryby zwięzłości stosowane do odpowiedzi konwersacyjnych Claude'a, nie tylko do generowanych dokumentów.

### Decyzje nazewnicze
- **Wybrane:** zostaje `brand-voice` z wewnętrznymi trybami (`default`, `concise`, `strict`)
- **Odrzucone:**
  - `concise` jako osobny skill — duplikuje brand-voice, niepotrzebny rozłam
  - `terse` — niejednoznaczne, kojarzy się z "rude"
  - `output-discipline` — zbyt biurokratyczne

### Pliki

| Ścieżka | Akcja | Cel |
|---------|-------|-----|
| `app/skills/brand-voice/SKILL.md` | edit | Dodaj sekcję `## Output Modes` z opisem trzech trybów i sposobu aktywacji |
| `app/skills/brand-voice/modes/concise.md` | new | Reguły: max 3 zdania per odpowiedź na pytanie zamknięte, brak preamble, brak "I'll now..." |
| `app/skills/brand-voice/modes/strict.md` | new | Reguły: tylko fakty, zero filler adjectives, max 1 zdanie per fakt, listy zamiast prozy |
| `app/skills/brand-voice/scripts/measure.py` | new | Eval przed/po na fixtures, raport oszczędności tokenów |
| `tests/fixtures/output-modes/` | new | 10 par baseline/expected dla różnych typów zadań (debug, review, plan, eksploracja) |
| `tests/skills_brand_voice.bats` | edit | Dodaj asercje dla modes (regex na zakazane filler, max-line-length) |

### Aktywacja

Trzy mechanizmy:

1. Frontmatter w projekcie: `output-mode: concise` w `CLAUDE.md` lub `.claude/settings.json`
2. Slash: `/brand-voice concise` przełącza dla bieżącej sesji (przez `track-usage.sh` zapisuje do session state)
3. Auto-trigger: skill ładuje się także przy długich sesjach generowania (>30 min, heurystyka)

### Success criteria

- Na zestawie 10 fixtures `concise` redukuje output >40% bez utraty kluczowych faktów
- Test asercji: zachowane są wszystkie nazwy plików i symboli z baseline (regex match)
- `validate.py --strict` przechodzi
- `audit_skills.py --ci` zero HIGH

### Estymata
4–6h

---

## Feature 2 — MCP context trim — DEFERRED TO v4.0

**Status:** Deferred. Spike conducted before implementation, conclusion in [`f2-mcp-trim-spike-20260504.md`](f2-mcp-trim-spike-20260504.md).

**Reason:** Claude Code hooks do not expose the MCP `tools/list` response or the system-prompt tool catalog. Hook events (`PreToolUse`, `PermissionRequest`, `Elicitation`) operate on individual tool calls only. Modifying tool descriptions before they reach the model requires a local MCP proxy server — multi-day scope, single-bug-breaks-all-MCP failure mode, out of scope for v3.2.0.

**Resolution:** Full proxy-server approach moved to its own active planning doc: [`kb/planning/mcp-context-trim-v4-prd.md`](../../planning/mcp-context-trim-v4-prd.md). The mid-spike "F2-lite observability tool" alternative was also dropped per user decision (2026-05-04) — v3.2.0 ships F1+F3 only; v4.0 picks up the proxy-server work in full scope.

The compression heuristics, file plan, and risk register from the original Feature 2 design were migrated into the v4.0 PRD. They are no longer duplicated in this archived doc.

---

## Feature 3 — Token receipts w statusline

### Cel
Pokazać realne (nie estymowane) zużycie tokenów per-sesja w statusline Claude Code. Dane czytane z session JSONL, nie z heurystyk.

### Decyzje nazewnicze
- **Wybrane:** rozszerzenie istniejącego skilla `briefing` + nowy hook `statusline-tokens.sh` + nowy skrypt `session_token_stats.py`
- **Odrzucone:**
  - Nowy skill `stats` / `receipts` — duplikuje funkcjonalnie `briefing`
  - Modyfikacja istniejącego `track-usage.sh` jako jedynego punktu — za duża odpowiedzialność jednego pliku

### Pliki

| Ścieżka | Akcja | Cel |
|---------|-------|-----|
| `scripts/session_token_stats.py` | new | Parser JSONL stdlib-only. Funkcje: `read_session()`, `aggregate_by_skill()`, `compare_baseline_vs_concise()` |
| `app/hooks/statusline-tokens.sh` | new | Type `statusLine` w settings.json. Sumuje `usage.input_tokens` + `usage.output_tokens` z bieżącej sesji JSONL |
| `app/hooks/track-usage.sh` | edit | Po wykryciu `/skill` zapisuj też `prompt_tokens` jeśli `transcript_path` dostępne |
| `app/skills/briefing/SKILL.md` | edit | Nowa sekcja "Token receipts", komendy `/briefing --tokens --since 7d`, `/briefing --tokens --share` |
| `scripts/merge-hooks.py` | edit | Statusline injection do `settings.json`, preserve user-customized entries (delivered as F3.5) |
| `app/hooks/ai-toolkit-statusline.sh` | new | Comprehensive statusline (cwd + git + ctx + tokens + cost + model), default install (delivered as F3.5) |
| `tests/session_token_stats.bats` | new | Fixture JSONL z 3 messages, asercje na sumę i breakdown |
| `tests/statusline_tokens.bats` | new | Mock JSONL, weryfikacja outputu hooka (max 80 znaków, brak NaN, fallback gdy brak sesji) |

### Format statusline (proponowany)

```
[ai-toolkit] /concise · session: 24.7k · trend: ↓18%
```

Krótki tryb default, `--verbose` dodaje breakdown per skill.

### Ścieżka odczytu sesji

Claude Code zapisuje JSONL do `~/.claude/projects/<sanitized-cwd>/<session-id>.jsonl`. Każda linia to message z polem `usage` (input_tokens, output_tokens, cache_*). Skrypt:

1. Identyfikuje aktualną sesję z env var `CLAUDE_SESSION_ID` (jeśli istnieje) lub najświeższy plik
2. Parsuje linie ignorując te bez `usage`
3. Sumuje + agreguje per skill (jeśli `track-usage.sh` zapisał skill mapping w sidecar pliku)

### Success criteria

- Statusline pokazuje liczbę tokenów odczytaną z JSONL z dokładnością ±2% vs Anthropic API report (jeśli dostępny)
- Brak crash gdy sesja jeszcze pusta
- Brak crash gdy JSONL malformed
- `validate.py --strict` przechodzi

### Estymata
6–8h

---

## Co nie wchodzi w plan

| Pomysł | Powód odrzucenia |
|--------|------------------|
| Memory/file compressor (`/compress <file>`) | `compile_slm.py` już kompresuje toolkit, brak konkretnego use-case dla per-file |
| Compact `/commit`, `/review` modes | Powstaną automatycznie po Feature 1 (te skille będą używać reguł `concise` mode) |
| "Caveman speak" / classical Chinese mode | Nie pasuje do tonu workmanlike, sprzeczne z brand-voice |
| Single curl-installer | Już mamy `ai-toolkit install` z profilami |

---

## Kolejność realizacji i zależności

```
Feature 1 (brand-voice modes)
    ↓ dostarcza reguły zwięzłości
Feature 3 (token receipts)
    ↓ dostarcza pomiar before/after dla F1
Feature 2 (mcp-trim)  ← spike research najpierw, niezależne od F1/F3
```

**F1 i F3 mogą iść parallel po dokończeniu F1 mode files.**
**F2 ma osobną decyzję go/no-go po spike'u.**

## Estymata zbiorcza

| Feature | Min | Max |
|---------|-----|-----|
| F1 | 4h | 6h |
| F3 | 6h | 8h |
| F2 spike | 1h | 1h |
| F2 implementacja | 0h | 10h |
| **Total** | **11h** | **25h** |

## Doc & test sweep (obowiązkowy po każdym feature)

1. `python3 scripts/validate.py --strict`
2. `python3 scripts/audit_skills.py --ci`
3. Regen `AGENTS.md`: `python3 scripts/generate_agents_md.py > AGENTS.md`
4. Regen `llms.txt`: `python3 scripts/generate_llms_txt.py > llms.txt`
5. Bump version w `package.json` + `plugin.json`
6. Update `skills-catalog.md` z nowymi/zmienionymi skillami
7. Update `README.md`, `CLAUDE.md`, `ARCHITECTURE.md`, `architecture-overview.md` jeśli zmiana behavior
8. Commit conventional: `feat(brand-voice): add output modes`, `feat(briefing): add token receipts`, `feat(mcp-trim): add description trimmer`

## Open questions — resolved

1. **Czy `PreToolUse` może modyfikować deklarację tool'a w MCP listingu?** — NIE. Spike potwierdził że żaden hook event nie wystawia `tools/list`. F2 wymaga MCP proxy. Odsunięte do v4.0.
2. **Czy Claude Code wystawia hookom `CLAUDE_SESSION_ID`?** — częściowo. `scripts/session_token_stats.py` używa fallback "newest JSONL w katalogu projektu" + opcjonalnie cwd → sanitize → match. Działa stabilnie na realnych sesjach (96.6k tokens parsed correctly w smoke tescie).
3. **Czy włączyć `concise` mode jako default?** — pozostaje opt-in. `brand-voice` z trybami auto-loaduje się tylko gdy projekt ustawi `output-mode: concise` w `CLAUDE.md` lub user wpisze `/brand-voice concise`. Pomiary z F3 dadzą dane do późniejszej decyzji.

## Final delivery (v3.2.0)

### Shipped

| Feature | Outcome | Pliki |
|---------|---------|-------|
| **F1 — brand-voice output modes** | Done. Aggregate ratio na 3 fixtures: concise **21%**, strict **14%** (cel ≤60% / ≤40%). | `app/skills/brand-voice/SKILL.md`, `app/skills/brand-voice/modes/{concise,strict}.md`, `app/skills/brand-voice/scripts/measure.py`, `tests/fixtures/output-modes/{debug-explanation,plan-question,review-summary}/`, `tests/test_brand_voice.bats` (14 tests) |
| **F3 — token receipts** | Done. Smoke-test na realnej sesji: 96.6k tokenów poprawnie sparsowane. | `scripts/session_token_stats.py`, `tests/fixtures/session-jsonl/{three-messages,malformed,empty}.jsonl`, `tests/test_session_token_stats.bats` (15 tests) |
| **F3.5 — comprehensive default statusline** | Done. Pełny segment: cwd + git + ctx% + tokens + trend + model-aware cost + model. Installed by default via `merge-hooks.py`, user-custom statusLine preserved untouched. | `app/hooks/ai-toolkit-statusline.sh`, `app/hooks.json` (`statusLine` entry), `scripts/merge-hooks.py` (statusLine inject/strip), `tests/test_statusline_hook.bats` (14 tests), `tests/test_merge_hooks_statusline.bats` (8 tests) |
| **briefing skill extension** | `/briefing --tokens` + wire-up docs + opt-out env vars. | `app/skills/briefing/SKILL.md` |

### Deviations from plan

| Plan said | Shipped | Reason |
|-----------|---------|--------|
| 10 fixtures w F1 | 3 fixtures + `must_contain.txt` mechanism | Mniejszy zestaw + extensible konwencja wystarcza do walidacji budżetów; jakość > ilość |
| F3 hook integracja jako follow-up (manual settings.json edit) | F3.5 dostarczył pełny default install via `merge-hooks.py` | User feedback w trakcie pracy: "niech ai-toolki instaluje go domyslnie od nowej wersji" |
| F2 implementacja po spike'u | F2 deferred do v4.0 | Spike pokazał że Claude Code hooki nie wystawiają `tools/list` → wymaga proxy server, multi-day scope |

### Quality gates passed

- `validate.py --strict`: 0 errors / 0 warnings
- `audit_skills.py --ci`: 0 HIGH / 0 WARN / 13 INFO (pre-existing)
- `audit_skills.py --sarif`: SARIF 2.1.0 valid, 5 rules
- `npm test`: 1032 / 1032 passing (was 981 in v3.1.1)
- Registry drift: clean
- Provenance + checksum-pin: verified
- Ecosystem doctor: 9 cosmetic drifts (class A) refreshed

### Skill classification change

`brand-voice` przeszedł `user-invocable: false → true` (knowledge → hybrid):

- **Hybrid**: 31 → 32
- **Knowledge**: 49 → 48
- **Task**: 32 (no change)

Updated: `README.md`, `kb/reference/architecture-overview.md`, `kb/reference/skills-catalog.md`.

## Status & rewizje

| Data | Zmiana | Autor |
|------|--------|-------|
| 2026-05-04 | Initial draft | lukasz.krzemien |
| 2026-05-04 | F1 implementation done — brand-voice modes, measure.py, 3 fixtures, 14 bats tests. Aggregate ratio: concise 21%, strict 14%. | claude |
| 2026-05-04 | F3 implementation done — `session_token_stats.py`, `statusline-tokens.sh`, briefing skill extension. 22 new bats tests. Smoke-tested on real session. | claude |
| 2026-05-04 | F3.5 follow-up done — replaced focused tokens hook with comprehensive `ai-toolkit-statusline.sh`. Extended `merge-hooks.py` for safe statusLine injection. Version bumped 3.1.1 → 3.2.0. 22 new bats tests. CHANGELOG + README updated. | claude |
| 2026-05-04 | F2 spike completed — see [`f2-mcp-trim-spike-20260504.md`](f2-mcp-trim-spike-20260504.md). Hooks cannot modify `tools/list`. F2 deferred to v4.0 with own PRD. | claude |
| 2026-05-04 | Plan archived to `kb/history/completed/`. Shipped in v3.2.0. | claude |

---

## kb/history/completed/rtk-pack-integration-20260726.md

---
title: "Plan: rtk Pack Integration"
category: planning
service: ai-toolkit
tags:
  - rtk
  - plugin-pack
  - token-reduction
  - vendored-binaries
  - cross-build
  - upstream-sync
doc_type: postmortem
status: completed
created: "2026-07-26"
last_updated: "2026-07-26"
completion: "100% — phases 0, 1, 2, 4, 5 delivered; phase 3 cut on the measurement"
shipped_in: "v4.18.0"
pinned_upstream: "v0.44.0"
description: "Integrate rtk as an opt-in ai-toolkit plugin pack: binaries cross-built from source in our CI with telemetry disabled, hosted on our own GitHub Release, fetched and checksum-verified at pack install, auto-update on ai-toolkit update, and an SOP for tracking upstream releases. Custom filter presets were cut on the measurement (0.008% of input tokens). Phase 0 validated the premise against v0.44.0 on the full transcript corpus before any build work."
---

# rtk Pack Integration

**Completed 2026-07-26, shipped in v4.18.0.** Kept whole rather than summarised,
because the value here is the measurements and the things that turned out to be
false, not the plan structure. Live procedure:
`kb/procedures/rtk-upstream-sync-sop.md`.

Headline: rtk-pack ships opt-in, built from source with telemetry compiled out,
and saves a **measured 0.0615% of input tokens** against a kill number of 0.05%
published before the measurement. Phase 3 (our own filter presets) was cut at
0.008%. The projection this plan published for itself was about twice too
optimistic, and section 10.1 says why.

## 1. Decision

Ship `rtk` to ai-toolkit users as an **opt-in plugin pack**, with the binary
supply chain owned end to end by us.

Five choices, made and locked:

| Question | Decision |
|---|---|
| Delivery | Plugin pack (`rtk-pack`), never a native feature |
| Binary hosting | Our own GitHub Release, fetched and SHA-256 verified at pack install |
| Binary provenance | Cross-built from upstream source in our CI, `RTK_TELEMETRY_URL` unset |
| Pinned upstream tag | **v0.44.0** (2026-07-26). v0.43.0 was ruled out on evidence, see section 2 |
| Upstream tracking | An SOP that rebuilds, verifies, and re-publishes when rtk ships a release |

Upstream: https://github.com/rtk-ai/rtk, Apache-2.0, Rust 1.91 plus a C
toolchain (rusqlite `bundled` compiles SQLite from source).

## 2. Phase 0: premise validated before building anything

The retired output filter validated its design across five phases and its
premise not at all until the fifth. This plan runs premise validation first.
Everything below is measured, not estimated.

### 2.1 Why v0.43.0 was ruled out

Two structural facts, read from the source of both tags:

- **Custom TOML filters are not wired into the rewrite path in v0.43.0.**
  `src/discover/registry.rs` at v0.43.0 contains zero references to
  `toml_filter`. In v0.44.0 they appear at `registry.rs:1047,1055,1058`.
  *This reason no longer applies:* section 7 cut our own presets, so nothing we
  ship depends on that wiring. It is recorded because it was one of the two
  arguments made at pin time, and the pin now rests on the second alone.
- **`pipeline_final_safe` does not exist in v0.43.0.** It arrives in v0.44.0
  (`rules.rs:7,115,124`, `registry.rs:605,659,864,1069`). v0.43.0 rewrote the
  first pipeline stage; v0.44.0 rewrites the last. On this traffic 56.5% of
  `rtk grep` hits arrive through the pipeline-final path, so they do not exist
  at all on v0.43.0.

### 2.2 The port models v0.44.0, not v0.43.0

`rtk_port.py` is re-validated by extracting the `assert_eq!` assertions from
each tag's `registry.rs` `#[cfg(test)]` block and replaying them:

| Port checked against | Assertions | Exact-string agreement |
|---|---:|---:|
| **v0.44.0** | 203 | **203/203** |
| v0.43.0 | 160 | 147/160 |

The 13 v0.43.0 failures are all the same pipeline inversion. The port also
passes the 15 assertions v0.44.0 added after the port was written. Pinning
v0.44.0 makes the existing measurement correct rather than requiring rework.

`registry.rs:590-592` returns `Some(unchanged)` for a simple already-`rtk`
command; the port's equivalent bail must be mapped to that, not to `None`.

### 2.3 The recorded numbers came from an 11% sample

`measure_rtk.py` sets `N_FILES = 134` and takes the most recently modified
transcripts. The available pool is **1224 transcripts**. At n=134 the projected
saving swings **8.8x** across windows (0.071% to 0.628%); at n>=408 it converges
to within **1.05x**. The spread recorded in earlier revisions of this plan was
sampling noise.

### 2.4 The port over-counted, and by how much

Both real entry points call `contains_unattestable_construct` **before**
`registry::rewrite_command`: `hook_cmd.rs:149-151` (Defer) and
`rewrite_cmd.rs:54-56` (Passthrough). Any command carrying a command
substitution, a process substitution, or a redirect with a file target is
rejected whole. Upstream's rewrite tests call `rewrite_command` directly, so a
port validated only against them passes while still over-counting.

The gate is ported from `lexer.rs:295-347` and validated **35/35** against
upstream's own assertions at `lexer.rs:1186-1276`. Applying it costs 3.1%
relative coverage.

### 2.5 Corrected numbers

Full corpus, 1224 transcripts, 552 MB, 106 MB of tool results, 26.6 MB of
successful Bash, entry gate applied:

| Metric | Earlier revision (n=134, ungated) | Phase 0 (n=1224, gated) |
|---|---:|---:|
| Coverage of successful Bash bytes | 31.5% | **35.17%** |
| Coverage of all tool-result bytes | 9.69% | **8.77%** |
| Ceiling: tool results as share of input volume | 5.52% | **4.54%** |
| Projection at rtk's 60-90% claim | 0.32-0.48% | **0.239-0.359%** |
| Projection, mechanism modelled | 0.15-0.21% | **0.117-0.164%** |
| Reach of our own TOML presets (the number that cut section 7) | 1.91% of Bash | **1.08% of Bash** |
| `Read` share of tool-result bytes | 53.8% | **62.8%** |

Modelled effectiveness per family against the claim: `rtk grep` 75% claimed and
**9.0%** modelled; `rtk read` 60% claimed and **0.0%** modelled; `rtk rg` 75%
and 30%; `rtk make` 65% and 16%; `rtk jq` 74%.

Largest unaddressed buckets, as a share of successful Bash bytes: pipeline not a
rewritable final stage **39.78%**, ignored by rtk **10.72%**, entry gate
**8.29%**, multiline script **4.71%**.

### 2.6 Open question 3 answered: no

Patching `pipeline_final_safe` for `head` and `tail` unlocks 10.56 MB, 39.96% of
Bash bytes. **88.3% of that (9.33 MB) routes to `rtk read`, measured at 0.00%
saving** on this traffic because it returns files verbatim at the default
`--level none`. The largest reachable gap is reachable and worthless. The
argument for maintaining a fork does not survive its own measurement.

## 3. Why a pack rather than a native feature

- **Opt-in is structural, not a policy.** Plugin packs must not be
  auto-installed [PATH: kb/reference/plugin-pack-conventions.md]. The retired
  output filter shipped `off` by default and still had to be wired into every
  install path, which is why v4.17.0 needed a bespoke migration cleanup.
- **Removal is already solved.** `plugin remove` strips hook entries from
  `settings.json`, deletes owned `plugin-<pack>-*` assets, and leaves core and
  user files alone.
- **The core package stays lean.** ai-toolkit is 4.4 MB unpacked; the platform
  artifacts are ~19.5 MB compressed. They never enter the base package.
- **There is a working precedent.** `memory-pack` ships hooks, a shared script
  directory, an install-time init script, its own data with retention, and a
  clean uninstall. `rtk-pack` is the same shape with a binary instead of a
  database.

## 4. Architecture

```text
app/plugins/rtk-pack/
├── plugin.json          # pinned rtk version + per-platform SHA-256
├── README.md
├── hooks/
│   └── rewrite.sh       # PreToolUse; delegates to the fetched binary
└── scripts/
    ├── init.py          # platform detect → fetch → verify → install
    └── status.py        # reports binary, digest and hook wiring
```

Runtime layout on a user machine:

```text
~/.softspark/ai-toolkit/
├── hooks/plugin-rtk-pack-rewrite.sh        # installed hook
└── plugin-scripts/rtk-pack/
    ├── bin/rtk                              # verified binary, 0755
    └── version.json                         # pinned version + recorded digest
```

Everything the pack writes lives under `plugin-scripts/rtk-pack/`, which
`plugin remove` deletes wholesale (`plugin.py:500-503`). The pack owns no state
outside the toolkit data directory: no `filters.toml`, no entry in rtk's trust
store, nothing in an OS config directory. That is a consequence of cutting
section 7 and it is what keeps removal complete.

Binary supply chain:

```text
upstream tag  →  our CI cross-build (RTK_TELEMETRY_URL unset)
              →  our GitHub Release  softspark-rtk-<upstream>-<build>
              →  SHA-256 recorded in plugin.json
              →  plugin install: detect platform, fetch, verify, chmod
```

## 5. Phase 1: build pipeline and binary release

**Outcome:** we can produce, from an upstream tag, a set of binaries that
provably make no network calls of their own.

**Targets: five, not six.** `x86_64-apple-darwin`, `aarch64-apple-darwin`,
`x86_64-unknown-linux-musl`, `aarch64-unknown-linux-gnu`,
`x86_64-pc-windows-msvc`. Earlier revisions added `x86_64-unknown-linux-gnu` on
the reasoning that upstream does not ship it. It is dropped: upstream's own
Homebrew formula routes Linux x86_64 to the **musl** tarball
(`release.yml:314-316`), a static musl binary runs on glibc, and upstream has
never validated a gnu x86_64 artifact, so we would be first to ship one and
would own all its breakage plus an uncontrolled glibc floor inherited from the
runner image.

Build constraints, all read from the pinned checkout:

- **Pin the toolchain.** Upstream uses `dtolnay/rust-toolchain@stable`
  (`release.yml:65,116`) with `warnings = "deny"` (`Cargo.toml:70-72`) and ships
  no `rust-toolchain` file. A future rustc lint turns our builds red with no
  change on either side. We pin an exact version at or above 1.91.
- **Windows must build natively.** `build.rs:6-13` emits
  `cargo:rustc-link-arg=/STACK:8388608` under `#[cfg(windows)]`, which in a
  build script is a **host** predicate. Cross-building Windows from Linux
  silently drops the 8 MiB stack reservation that upstream's own comment says is
  what makes `rtk.exe --version`, `--help`, and hook entry points start
  reliably. Build on `windows-latest`, or pass the link-arg explicitly.
- **Both darwin targets build on `macos-latest` (arm64).** `macos-13` is the
  last x86_64 macOS image and GitHub is winding it down: on runs 30212577757 and
  30214341444 that job sat queued indefinitely while every other target
  finished. Upstream builds both on arm64 too, but never runs its x86_64
  artifact. We do: the verifier detects Rosetta 2 and executes it, and reports
  `inconclusive` rather than `pass` if it cannot.
- **Every target needs a target-capable C compiler.** rusqlite `bundled`
  (`Cargo.toml:26`) is not switchable off; there is no `[features]` table and no
  `cfg(feature` in `src/`. There is no pure-Rust escape route.
- **aarch64-linux is the hard case, but upstream already solves it** with
  `cross: true` on `ubuntu-latest` (`release.yml:51-54`). Copy that. Upstream
  sets only the linker env var and lets the `cc` crate guess the C compiler;
  export `CC_aarch64_unknown_linux_gnu` and `AR_aarch64_unknown_linux_gnu`
  explicitly so a runner image change surfaces as a clear error.
- **Run our own blocking `cargo audit`.** Upstream's is advisory: `ci.yml:88-96`
  swallows failures into a warning. Rebuilding from a tag inherits that
  lockfile, and on v0.44.0 it inherits four advisories across three of its 203
  crates. The audit and the build jobs apply the same remediation, so we audit
  the dependency set we ship rather than a different one:

  | Crate | Advisory | Disposition |
  |---|---|---|
  | `anyhow` 1.0.102 | RUSTSEC-2026-0190 | `cargo update` to 1.0.103, in range |
  | `crossbeam-epoch` 0.9.18 | RUSTSEC-2026-0204 | `cargo update` to 0.9.20, in range |
  | `quick-xml` 0.37.5 | RUSTSEC-2026-0194, RUSTSEC-2026-0195 | ignored with reasons |

  The quick-xml fix lands only in 0.41.0 while rtk pins `"0.37"` as a direct
  dependency (`Cargo.toml:34`), so taking it means editing `Cargo.toml` and the
  calling code in `src/cmds/dotnet/dotnet_trx.rs`. That would break the promise
  that the only difference from an upstream build is the undefined telemetry
  endpoint. The reachable surface is narrow: quick-xml parses .NET TRX test
  output only, the input is a report produced locally by the user's own test
  run, and both advisories are availability-only (CVSS `C:N/I:N/A:H`). The SOP
  re-checks this on every sync and deletes the ignores once upstream moves to
  quick-xml 0.41 or later.
- A target that will not build is dropped, not faked.

### 5.1 Proving the binary is silent

The endpoint is compile-time only: `option_env!("RTK_TELEMETRY_URL")` at
`telemetry.rs:16` and `telemetry_cmd.rs:176`, with the token at
`telemetry.rs:17` and `telemetry_cmd.rs:189`. Nothing supplies a default:
`build.rs` emits no `cargo:rustc-env`, `TelemetryConfig` has no URL field, and
no runtime `std::env::var` resolves the endpoint. Upstream injects it only in
`release.yml:85-86,124-125,151-152`. Building without it yields a binary whose
telemetry destination cannot be re-enabled by any env var or config at runtime.

**The acceptance criterion in earlier revisions was untestable and is replaced.**
"No telemetry symbols in the binary" cannot be checked: the guard is a runtime
`if TELEMETRY_URL.is_none()` on a const (`telemetry.rs:23-26`), not a `#[cfg]`,
so the code compiles in and is only eliminated by LLVM as an optimisation; and
`Cargo.toml:51` sets `strip = true`, which removes the symbols regardless of
whether the code is present. A symbol check would pass for the wrong reason.

What we assert instead:

0. **The artifact was actually started.** Every other assertion is worthless on
   a binary nobody executed, and two of the five targets are not native to their
   runner. `aarch64-unknown-linux-gnu` runs under `qemu-user` with the cross
   sysroot passed as `-L`, and `x86_64-apple-darwin` runs under Rosetta 2 on the
   arm64 runner. A target that cannot be started reports `inconclusive`, never
   `pass`.
1. **Build gate.** `RTK_TELEMETRY_URL` and `RTK_TELEMETRY_TOKEN` are unset in
   the build environment, asserted in CI before `cargo build`, with a clean
   target directory per build.
2. **Offline smoke run.** Each artifact runs its real command surface with no
   network route available and makes zero outbound connections. This is
   Linux-only: `unshare -rn` has no unprivileged equivalent on macOS or Windows
   runners, and Ubuntu 24.04's
   `kernel.apparmor_restrict_unprivileged_userns=1` means even there it needs
   `sudo`. On the first run this assertion silently degraded to a skip on every
   target while the verdict still read `pass`, so the manifest now records which
   isolator was used and a target that could not be started at all reports
   `inconclusive` rather than `pass`.
3. **Filesystem assertion.** No telemetry state is created under the resolved
   data directory.
4. **Drift detection.** Record artifact size and a string-allowlist hash per
   target and fail the build on unexplained drift, since whether `ureq`,
   `rustls`, `ring` and `webpki-roots` are actually eliminated is an LLVM
   outcome under `lto = true`, not a guarantee.

Three findings that must reach the pack README:

- **`rtk cc` shells out to `npx --yes ccusage`** when `ccusage` is not on PATH
  (`ccusage.rs:104-119`). That is a runtime npm fetch and third-party code
  execution. It is not telemetry and not automatic, but it is outbound network
  from a binary we tell users makes no network calls.
- **`RTK_TELEMETRY_DISABLED` only accepts the exact string `1`**
  (`telemetry_cmd.rs:31-33`, locked by the test at `:222-229`). `true` and `yes`
  are silent no-ops. Never write anything else anywhere in the pack.
- **`rtk telemetry forget` on an endpoint-free build prints a misleading
  failure** telling the user to email upstream to complete erasure
  (`telemetry_cmd.rs:158-169`), when nothing was ever sent.

Apache-2.0 obligations ship alongside: upstream `LICENSE`, a `NOTICE` file
(upstream has none), and a statement that the only build-time change is leaving
the telemetry endpoint undefined. **Do not redistribute upstream
`DISCLAIMER.md` verbatim**: `DISCLAIMER.md:25` states telemetry is collected by
default, which the code contradicts and which a compliance reviewer would read
as a reason to block the pack. `docs/TELEMETRY.md:180` calls the mechanism
"compile-time gating" where "all telemetry code is dead", which is imprecise for
the same reason our own criterion changed.

**Success criteria:** five artifacts build from the pinned tag; each runs
`rtk --version` on its target; the silence assertions pass or say plainly that
they did not run; checksums published.

### 5.2 Result, run 30214882862

All five targets build and verify. Every artifact was actually started, none
shipped on a skipped assertion.

| Target | `runs` | `offline` |
|---|---|---|
| `aarch64-apple-darwin` | native | not applicable |
| `x86_64-apple-darwin` | translated via Rosetta 2 | not applicable |
| `x86_64-unknown-linux-musl` | native | passed under `sudo -n unshare -rn` |
| `aarch64-unknown-linux-gnu` | emulated via `qemu-aarch64-static` | passed under `sudo -n unshare -rn` |
| `x86_64-pc-windows-msvc` | native | not applicable |

No TLS markers in any artifact, so `ureq`, `rustls`, `ring` and `webpki-roots`
appear to be eliminated under LTO once the endpoint const is `None`. That is an
optimisation outcome rather than a guarantee, which is why the fingerprint is
recorded per target and drift fails the build.

**Four of five targets are bit-reproducible.** Across independent runs with
identical inputs, `aarch64-apple-darwin`, `x86_64-apple-darwin`,
`aarch64-unknown-linux-gnu` and `x86_64-unknown-linux-musl` produced
byte-identical binaries. The concern about unset `trim-paths` embedding registry
paths does not materialise on these runners.

`x86_64-pc-windows-msvc` did not, and the cause was bounded: **24 bytes out of
8,018,432 differed**, in five regions. Four were the same two-byte value at
`0x100` and in the debug directory, which is the MSVC link timestamp; the fifth
was a 16-byte CodeView GUID. The code was identical; only the link stamp varied.

`-C link-arg=/Brepro` is now set for the Windows target, which makes the linker
derive that timestamp from content rather than the clock. **The shipped
`softspark-rtk-v0.44.0-1` artifacts predate that change**, so the Windows digest
in `plugin.json` is from a non-deterministic link; the flag takes effect on the
next rebuild, which will produce a different Windows digest for the same source.

This matters for the sync SOP: a changed digest means changed input rather than
build noise. That inference holds on four targets today and on all five from the
next rebuild onward.

Note that the **archives** are not reproducible even where the binaries are,
because gzip records a timestamp. Compare extracted binaries, never the
tarballs.

Three defects the run surfaced, all now fixed and guarded:

- The gnu target is dynamically linked, so `qemu-user` needs the cross sysroot.
  It is passed as `-L` rather than `QEMU_LD_PREFIX`, because the offline check
  runs under `sudo` and `env_reset` drops the variable.
- The offline check compared a plain run against a namespaced one, so `sudo`'s
  environment handling was confounded with the network variable and a harness
  failure was reported as a behaviour difference in the binary. Both sides now
  run in a namespace and differ only in `-n`.
- `7z` stored the full relative path, so the Windows zip held
  `rtk-src/target/<triple>/release/rtk.exe` while every tar.gz held a bare
  `rtk`. The pack installer extracts all five the same way, so this was a
  silent install failure on one platform. A `collect` step now asserts every
  archive holds exactly one flat entry.

## 6. Phase 2: the pack

**Outcome:** `ai-toolkit plugin install rtk-pack` produces a working setup and
`plugin remove` leaves nothing behind.

- `scripts/init.py` detects platform and libc, fetches the matching artifact,
  verifies its SHA-256 against `plugin.json`, and installs to
  `plugin-scripts/rtk-pack/bin/rtk`. A mismatch aborts and removes the partial
  download. No network at runtime, only at install.
- Failure to fetch is not an install failure: the pack degrades to inert and
  says so, matching how the core behaves when `jq` is missing.
- The hook is wired at `PreToolUse` through the existing pack hook mechanism, so
  `plugin remove` strips it via the `_source` marker.
- `plugin status` dispatches to the pack's own `scripts/status.py`, which is
  generic rather than another hardcoded `if name == ...` branch. It reports the
  binary, the install record, the live version, and hook wiring, and announces a
  missing binary as inert rather than letting a green install imply it works.

### 6.1 No trust step, because the pack ships no filters

Section 7 is cut, so the pack writes no `filters.toml` and takes no entry in
rtk's trust store. That removes the single highest-ranked risk this plan
carried: an untrusted or content-changed preset produces **zero output on the
command path with no warning, no stderr line, and no non-zero exit**
(`toml_filter.rs:220-221`, `:450-458`) — installed, apparently fine, doing
nothing, which is exactly the shape of failure that retired the in-house filter.

The pack instead reports whether it is actually working. `scripts/status.py`
distinguishes installed from functioning: a missing binary is announced as
`MISSING — the hook is inert and every command runs unchanged` rather than
inferred from a green install.

**If presets are ever revisited, these are the constraints, kept because they
were expensive to establish:**

- Trust is a byte-exact SHA-256 (`trust.rs:142-163`), so every write, upgrade,
  repair, trailing newline, or git CRLF normalisation invalidates it.
- `rtk trust --yes` is indiscriminate: it trusts every gated file that exists,
  including a `.rtk/filters.toml` an attacker committed into the CWD
  (`trust.rs:262-305`, project path is CWD-relative at `:207`).
- It exits 1 both when there is nothing to trust and when the file is invalid
  TOML (`trust.rs:307-312`), so `set -e` aborts on the benign case.
- There is no `rtk doctor`, and `rtk trust --list` never re-hashes
  (`trust.rs:242-256`). Verification means reading the store and recomputing.
- The global path is not `~/.config/rtk/filters.toml` everywhere: it comes from
  `dirs::config_dir()` (`trust.rs:206-216`), which on macOS is
  `~/Library/Application Support`. rtk's own error text hardcodes the Linux path
  and is wrong there.
- One global file, no include mechanism, so injection would have to follow the
  merge-friendly install model [PATH: kb/reference/merge-friendly-install-model.md]
  with comment markers rather than owning the file.

**Success criteria:** install, status, update, remove, and re-install are
idempotent; a machine without the pack behaves exactly as today; uninstalling
ai-toolkit removes every pack artifact.

## 7. Phase 3: cut

**Cut on the measurement, 2026-07-26.** Custom TOML presets reach **1.08% of
Bash bytes**, which is 0.27% of tool-result bytes. At a generous 60% reduction
that is **0.008% of input tokens**, roughly one part in twelve thousand.

Against that: presets would have required a trust step that fails silently, a
doctor check that recomputes digests, marker injection into a file the user may
also edit, re-trusting after every write, and a per-upstream-release review of a
DSL whose `deny_unknown_fields` rejects the entire file on one unknown key. The
maintenance surface is large, the payoff is not measurable, and every item on
that list is a way for the pack to look installed while doing nothing.

The pack therefore ships upstream rtk's built-in filters and nothing of our own.
The 35.2% coverage quoted in section 2.5 is already what those built-ins
deliver; it does not shrink as a result of this cut.

Two consequences recorded so they are not rediscovered:

- The pack owns no state outside `~/.softspark/ai-toolkit/plugin-scripts/rtk-pack/`,
  which is what makes `plugin remove` complete.
- One of the two arguments for pinning v0.44.0 was that custom filters are only
  wired into the rewrite path there. That argument is now moot; the pin rests on
  `pipeline_final_safe`, which carries 56.5% of `rtk grep` hits on this traffic
  and does not exist in v0.43.0. See section 2.1.

Reopening this is a plan change, not a task: it needs a workload where rtk's
built-ins measurably under-perform and a preset that measurably closes the gap,
demonstrated by replay before any code is written.

## 8. Phase 4: auto-update on `ai-toolkit update`

**Outcome:** a user who installed the pack gets the new binary by running the
update they already run.

Verified gap: `handleUpdate` in `bin/ai-toolkit.js` reads installed modules from
`state.json` and does not touch `plugins.json`. Nothing propagates to packs
today, so this is new wiring, not a configuration change.

**Done.** `ai-toolkit update` now calls `plugin update --editor all --all`
after the core update. Two things had to change first, both generic rather than
rtk-specific:

- `update_pack` was an unconditional remove-then-reinstall, so wiring it into
  the core update would have refetched the binary on every run. `plugins.json`
  now records the pack version installed per editor, and an update whose
  manifest version matches is a silent no-op. `--force` overrides.
- State written before versions were tracked has no `versions` map, so every
  pack reads as stale exactly once and is updated once. That is the intended
  migration, not a bug.

`--local` leaves packs alone: they live in `~/.softspark/ai-toolkit` and are
global, while `--local` is project-local config only.

- After the core update completes, `ai-toolkit update` reads `plugins.json` and
  runs the equivalent of `plugin update` for every **currently installed** pack.
  Packs that are not installed stay untouched, which preserves adoption rule 1.
- The rtk-pack update path is: compare the manifest's pinned version against the
  recorded pack version; if they differ, fetch and verify the new binary and
  re-install the hook.
- `--dry-run` reports what would change per pack.
- A pack update failure warns and continues; it never fails the core update.
- Bats coverage in `tests/test_plugin_update.bats`: stale version replaced;
  current version untouched and silent; pack absent means no work; `--dry-run`
  reports without acting; legacy state with no version map updates once; a
  corrupt `plugins.json` does not crash the run.

**Success criteria:** the wiring is generic across packs, not rtk-specific;
`update` remains idempotent; a failed pack update never leaves a half-installed
binary.

## 9. Phase 5: upstream sync SOP

**Outcome:** a written procedure so tracking upstream is routine rather than a
research project each time. **Written**, at
`kb/procedures/rtk-upstream-sync-sop.md`, modelled on the existing
ecosystem-sync SOP.

The 0.43.0 to 0.44.0 bump is a worked example of why the review step exists: 200
commits, and every file the SOP names changed, including a semantic inversion in
pipeline rewriting and the arrival of the trust gate.

Steps the SOP must cover:

1. **Detect.** Check the upstream releases feed for a tag newer than the pinned
   one. Their stable cadence is roughly two to four weeks, behind a long
   release-candidate train. Cadence: on demand, plus a check folded into release
   preparation.
2. **Review before building.** Read the changelog and diff `src/discover/rules.rs`,
   `src/discover/registry.rs`, `src/discover/lexer.rs`, `IGNORED_PREFIXES`, the
   TOML DSL structs in `src/core/toml_filter.rs`, `src/hooks/trust.rs`, and
   anything touching telemetry. A change to the DSL or to trust handling is a
   stop-and-think, not a rebuild.
3. **Re-validate the port.** Re-extract the `rewrite_command` assertions from the
   new tag's `registry.rs` test block and the gate assertions from `lexer.rs`,
   and replay both. Anything short of full agreement invalidates every coverage
   number until the port is fixed.
4. **Rebuild** all five targets from the new tag with telemetry unset.
5. **Verify.** Binary runs on each target; the silence assertions pass; the
   pack's fixtures still produce the expected decisions.
6. **Publish** a new release in our namespace and record the new digests.
7. **Bump** `rtk-pack` version in `plugin.json` and note the upstream version it
   tracks. The bump is what makes `plugin update` fire at all, since a pack whose
   recorded version still matches is skipped silently.
8. **Ship** in the next ai-toolkit release; installed packs pick it up through
   Phase 4.
9. **Record** the licence position if upstream relicenses or adds a NOTICE.

There is no upstream test asserting network silence, so that property can
regress on any bump without turning their CI red. We own that test and re-run it
every time.

**Success criteria:** a maintainer who has never done it can follow the SOP end
to end; the review step names specific files rather than saying "check for
breaking changes".

## 10. Verification

The pack must be able to answer "did this help?" with a number.

**The before-and-after design is replaced.** Phase 0 measured its noise floor:
on a 134-transcript window the projected saving varies by 8.8x while the
mechanism is unchanged. A before-and-after comparison cannot detect an effect of
0.117% to 0.164% against that. Two changes make the measurement possible:

- **Measure over the whole transcript pool, not a recency window.** At n>=408
  the same metric converges to within 1.05x.
- **Measure by replay, not by elapsed calendar time.** Run real captured tool
  output through the built binary and compare byte counts directly. That is the
  method that produced the honest 0% which retired the in-house filter, and it
  removes the confound of what work the user happened to do that week.

The harness is `replay_rtk.py` in the measurement archive, not a script inside
the pack. It pairs each successful Bash result with the command that produced
it, keeps the ones the validated port says rtk would rewrite, and pipes the
captured bytes through the shipped binary via `rtk pipe -f <filter>`.

Two limits, stated because the number is meaningless without them:

- `rtk pipe` runs the same filter code as the command path but knows less than
  it does: no result caps, no exit code, no file set. For search families the
  replay figure is a **lower bound** on what the command path would save.
- Families with no pipe filter (`rtk read`, `rtk ls`, `rtk wc`) cannot be
  measured this way at all. They are reported as **unmeasurable**, never folded
  in as zero, because a zero that is really an absence is how the previous
  effort talked itself into shipping.

Session-level token accounting, when it is wanted, comes from the session JSONL
[PATH: scripts/session_token_stats.py], summing all four usage fields: in a
cached session most context tokens land in the cache fields rather than
`input_tokens`.

**Kill number, published before the measurement rather than argued after it:**
if replay on the full corpus shows the shipped binary saving less than 0.05% of
input tokens, the pack is not worth its maintenance and supply-chain surface,
and it is retired the way the output filter was.

### 10.1 Result: measured 0.0615%, kill number survived by 23%

Full pool, 28.56 MB of successful Bash output, replayed through the published
`softspark-rtk-v0.44.0-1` binary:

| | |
|---|---:|
| Addressed by rtk | 9.99 MB, **35.00%** of Bash bytes |
| Measurable through `rtk pipe` | 5.66 MB |
| After filtering | 4.22 MB |
| **Measured saving** | **1.44 MB = 360,529 tokens** |
| As a share of tool-result bytes | 1.35% |
| **As a share of input tokens** | **0.0615%** |

Against a kill number of 0.05%, the pack survives by a factor of 1.23. That is a
pass, not a vindication.

**The projection published in section 2.5 was roughly twice too optimistic.**
It said 0.117% to 0.164%; the measurement says 0.0615%. The error has a single
identifiable cause: the model credited families it could not simulate with
rtk's own claimed 60-90%. Replayed, the families that can be measured deliver
**25.5%** in aggregate.

Per family, measured against modelled and against upstream's claim:

| Family | Measured | Modelled | Claimed |
|---|---:|---:|---:|
| `rtk grep` | **22.3%** | 9.0% | 75% |
| `rtk git` | **33.1%** | — | 70% |
| `rtk find` | **35.6%** | — | 70% |
| `rtk rg` | **7.0%** | 30% | 75% |
| `rtk ruff` | **0.0%** | — | — |

The model **understated** grep by 2.5x and the total still came out high, so the
two errors are unrelated: coverage modelling was sound, per-family effectiveness
was guesswork wherever the source was not read closely.

**What the replay does not settle.** 43.3% of addressed bytes (4.33 MB) have no
`rtk pipe` filter and are unmeasurable, the largest being `rtk read` at 1.55 MB.
That family is known from source to return files verbatim at the default
`--level none`, so the headroom is smaller than 43.3% suggests. No extrapolation
is applied: a zero that is really an absence of measurement is how the previous
effort talked itself into shipping. For search families the pipe path also lacks
the command path's result caps, making these figures a lower bound.

**One independent confirmation.** The replay measured coverage at 35.00% of Bash
bytes; the gated port measured 35.17% on the same pool by a different method.
The port is right about *which* commands rtk touches even where it was wrong
about how much each saves.

Reproduce with `replay_rtk.py --pool 1300 --rtk <binary>` in the measurement
archive.

## 11. Licence and security obligations

- **Apache-2.0.** Ship upstream `LICENSE` with the binaries, add a `NOTICE`, and
  state the build-time change. Never relabel any upstream file MIT. Do not ship
  `DISCLAIMER.md` verbatim, see section 5.1.
- **Telemetry.** Proven absent per build by the four assertions in section 5.1,
  re-proven on every upstream sync.
- **Supply chain.** Digests pinned in `plugin.json`, verified on fetch,
  re-verified by `doctor`. This mirrors the existing checksum-pin discipline for
  URL-sourced rules and hooks. Run a blocking `cargo audit` on the pinned
  lockfile, because upstream's is advisory.
- **Trust boundary.** rtk rewrites commands before execution, which the retired
  in-house contract explicitly forbade for itself. Adopting it is a conscious
  reversal of that constraint and its own threat surface: what runs is not what
  the model asked for. The pack's README must say this plainly, and
  `plugin install` must not be silent about it. The README must also disclose
  the `rtk cc` npx path.

  The sharp edge is more specific than "the command changes". rtk evaluates the
  host's permission rules against the **original** command and applies the
  verdict to the **rewritten** one: `decide_hook_action(cmd, ...)` takes the
  command the model asked for, and `permissionDecision: allow` is then emitted
  for the substituted `rtk …` form (`hook_cmd.rs:405-436`). An allowlist entry
  for `git status` therefore authorises `rtk git status`, which the user never
  wrote a rule for. Upstream documents the absence case in its own test
  (`hook_cmd.rs:1272-1283`): with no matching allow rule, no decision is emitted
  and the normal prompt stands. Both halves belong in the README.

## 12. Pre-mortem

| Rank | Failure mode | Probability | Impact | Mitigation |
|---:|---|:---:|:---:|---|
| — | ~~Presets install but are untrusted, so they silently do nothing~~ | — | — | **Eliminated**, not mitigated: section 7 is cut, so the pack ships no filters and takes no trust-store entry |
| 2 | Cross-building with bundled SQLite is fragile in CI | Medium | Medium | Copy upstream's `cross` setup for aarch64-linux; five targets not six; a target that will not build is dropped, not faked |
| 3 | Pre-execution rewriting changes command semantics | Medium | High | Opt-in pack, documented one-flag disable, upstream's own review process, our integration tests on real commands |
| 4 | Windows binary cross-built without the 8 MiB stack reservation | Medium | High | Build natively on `windows-latest`, or pass the link-arg explicitly. `build.rs:6-13` |
| 5 | Upstream velocity breaks the rewrite logic the coverage numbers model | Medium | Medium | Pinned version, SOP review step naming exact files, port re-validation as a gate, fork option preserved by Apache-2.0 |
| 6 | Unpinned toolchain plus `warnings = "deny"` turns builds red with no change | Medium | Low | Pin an exact rustc version; treat bumps as deliberate |
| 7 | A fetch failure leaves a half-installed pack | Medium | Medium | Verify-then-install, abort and clean on digest mismatch, `doctor` detects drift |
| 8 | Live saving lands near the projection, not the claim | High | Medium | Section 10 measures it by replay either way, against a published kill number |
| 9 | The auto-update wiring makes `update` slower or flakier | Low | Medium | Skip when versions match, warn-and-continue on failure, `--dry-run` coverage |
| 10 | The pack drifts into being installed by default | Low | High | Adoption rule 1 plus a test asserting `install` never pulls it in |

## 13. Open questions

1. ~~Which upstream tag do we pin first?~~ **Answered: v0.44.0.** See section 2.1.
2. ~~User scope only, or a project-scoped preset variant too?~~ **Moot:** section 7 is cut, so the pack installs no presets at any scope.
3. ~~Is patching `pipeline_final_safe` for `head`/`tail` in scope later?~~
   **Answered: no.** See section 2.6.
4. ~~Does Phase 3 survive its own measurement at 0.008% of input tokens?~~
   **Answered: no, cut 2026-07-26.** See section 7.
5. ~~How does the pack share rtk's single global `filters.toml`?~~ **Moot:** it
   writes no filters at all. The marker-injection design and the trust
   constraints that would have applied are kept in section 6.1 in case presets
   are ever revisited.

---

## kb/history/completed/rtk-pack-retirement-20260727.md

---
title: "Retirement: rtk-pack — Broken On Install, Removed One Day After Shipping"
category: planning
service: ai-toolkit
tags:
  - rtk
  - plugin-pack
  - token-reduction
  - postmortem
  - measurement
  - release-process
doc_type: postmortem
status: completed
created: "2026-07-27"
last_updated: "2026-07-27"
shipped_in: "v4.19.0 (removal)"
description: "Why rtk-pack, shipped in v4.18.0, was removed in v4.19.0: the first real install proved every rewritten command failed with exit 127, the wrong architecture was fetched on Apple Silicon, and the pack's own status check reported both as green. Measured value was 0.0615% of input tokens, so neither defect was worth fixing."
---

# Retirement: rtk-pack

**Shipped:** v4.18.0 (2026-07-26). **Removed:** v4.19.0 (2026-07-27).

The pack was installed on a maintainer's machine for the first time one day
after release. It did not work, in the strongest sense available: it broke the
shell.

## Defect 1: every rewritten command failed with exit 127

rtk emits its rewrite as a bare `rtk git status`. The pack installs its binary
at `~/.softspark/ai-toolkit/plugin-scripts/rtk-pack/bin/rtk` and never puts that
directory on `PATH` — deliberately, so a checksum-pinned binary cannot shadow
anything system-wide. The two decisions are individually defensible and jointly
fatal: the shell could not find `rtk`, so every command the hook touched died
before running.

Observed on the first three commands issued after install:

| Command | Result |
|---|---|
| `cat ~/.softspark/ai-toolkit/plugins.json` | `command not found: rtk` |
| `git --no-pager diff` | `command not found: rtk` |
| `find ~/.softspark -path '*rtk*'` | `command not found: rtk` |

The blast radius is every family in `rtk --help`: `git`, `ls`, `read`, `find`,
`grep`, `rg`, `diff`, `docker`, `kubectl`, `npm`, `jest`, `tsc`. On the reference
workload that is 35% of Bash bytes, which is the same 35% the pack was built to
save. The mechanism that produced the benefit produced the outage.

## Defect 2: the Intel build on an Apple Silicon host

`detect_platform()` trusted `platform.machine()`. The maintainer's `python3` is
an Intel Homebrew build at `/usr/local/opt/python@3.14`, so it runs under
Rosetta 2, where every architecture API inside the process reports `x86_64` —
`platform.machine()`, `os.uname()` and `uname -m` alike. The pack fetched
`rtk-x86_64-apple-darwin.tar.gz` onto an `arm64` machine and ran it emulated.

`sysctl.proc_translated` answers the question that distinguishes the two cases
and was not consulted. Note that CI had already met Rosetta on this project:
commit `30614ca`, *"build x86_64-darwin on arm64 and verify it under Rosetta"*.
The build pipeline knew. The install path did not.

## Defect 3: the pack's own health check called both of them green

`plugin status` reported the binary present, the digest recorded, `runs: rtk
0.44.0`, the hook script present and the hook registered. All true, all useless.
The pack's `status.py` was written specifically to *"distinguish installed from
working"*, and it checked only the installed half.

`kb/procedures/post-release-testing-sop.md`, written the day before the release,
requires exactly the missing step:

> Presence is not function. Drive the hook directly.

The SOP was written and not run. Every defect above would have surfaced in its
first five minutes.

## The number that made fixing it not worth it

All three defects were fixed and tested before the removal decision: a `PATH`
prefix on the emitted command, `sysctl.proc_translated` in the detector, and a
status check that executes what the hook emits and looks for 127. Six tests,
all passing, all failing against the previous code. The work was not hard.

It was measured against this, from `rtk-pack-integration-20260726.md` §10.1:

| | |
|---|---:|
| Measured saving | 1.44 MB = 360,529 tokens |
| As a share of input tokens | **0.0615%** |
| Kill number, published before the measurement | 0.05% |
| Margin | ×1.23 |

The integration plan's own verdict on that margin was *"a pass, not a
vindication"*. A pack that survives its kill number by 23%, carries a
supply-chain surface, an upstream-sync SOP, a cross-build workflow for five
targets, and a hook that rewrites every command before it runs, is not worth
three defect classes discovered on first contact. The cost side moved; the
benefit side never did.

## Why the ceiling was always low, independent of any defect

`Read` results are 62.8% of tool-result bytes on this traffic, and `rtk read`
measures 0.0% — at its default `--level none` it returns files verbatim. Tool
results are 4.54% of input token volume, so that is the arithmetic ceiling for
any tool-output mechanism here, and rtk addresses 8.8% of it.

Replayed against upstream's own claims, the families that can be measured
deliver 25.5% in aggregate against a claimed 60–90%:

| Family | Measured | Claimed |
|---|---:|---:|
| `rtk find` | 35.6% | 70% |
| `rtk git` | 33.1% | 70% |
| `rtk grep` | 22.3% | 75% |
| `rtk rg` | 7.0% | 75% |
| `rtk read` | 0.0% | 60% |

Better engineering does not move any of this. The lever is in the wrong place.

## The process lesson

The previous retirement in this series
([output-filter-retirement-20260726.md](output-filter-retirement-20260726.md))
concluded that premise validation must come first, with a kill number published
before the measurement. rtk-pack did that, and did it well: Phase 0 ran on 1224
transcripts before any build work, the kill number was published in advance, and
Phase 3 was cut on a measured 0.008%.

It then shipped without anyone installing it.

Measurement discipline and release discipline are different disciplines, and
this project now has one clean failure of each. The first shipped a feature that
worked and saved nothing. The second shipped a feature that would have saved
something and did not work. The next plan of this shape needs both gates, and
the second one is the cheap one: install the artifact, run the thing, look at
what happens.

## What survives

- **Multi-runtime pack hook wiring.** Packs write user-scope entries to
  `~/.cursor/hooks.json` and `~/.gemini/settings.json`, tagged per pack, with
  `plugin remove` taking only its own back out. Generic; no rtk in it.
- **`supported_editors` in the manifest.** A pack declares the runtimes it works
  on instead of installing everywhere and silently doing nothing.
- **Generic `plugin status` dispatch.** Any pack can ship `scripts/status.py`.
  The lesson attached: a status check must prove the working half by exercising
  it.
- **Version-aware `plugin update`.** A pack whose manifest has not moved is a
  silent no-op.
- **`audit_skills.py --ci` and the ShellCheck gate now cover `app/plugins/`.**
- **[Post-Release Testing SOP](../../procedures/post-release-testing-sop.md).**
  Kept, and now carries the note that the one time it existed and was skipped,
  this happened.

## What was removed

`app/plugins/rtk-pack/`, `.github/workflows/rtk-build.yml`,
`scripts/verify_rtk_binary.py`, `tests/test_rtk_pack.bats`,
`tests/test_verify_rtk_binary.bats`, `kb/procedures/rtk-upstream-sync-sop.md`,
and the GitHub Release `softspark-rtk-v0.44.0-1` holding the five cross-built
binaries.

Anyone who installed the pack under v4.18.0 should run
`ai-toolkit plugin remove rtk-pack`. With the release deleted, a fresh
`plugin install rtk-pack` on v4.18.0 fails at the fetch and leaves the pack
inert rather than half-installed, which is the degraded path the pack was
designed for.

---

## kb/history/completed/tool-output-token-reduction-closed-20260727.md

---
title: "Closed: Tool-Output Token Reduction — Three Attempts, One Ceiling"
category: planning
service: ai-toolkit
tags:
  - token-reduction
  - measurement
  - postmortem
  - prompt-caching
  - context-window
  - closed-line-of-work
doc_type: postmortem
status: completed
created: "2026-07-27"
last_updated: "2026-07-27"
description: "Closes the tool-output token-reduction line of work after a third measurement. Decomposes 1189 real sessions by cost: 84% is context being fed to the model, 14.7% is responses. Tool output is a small lever by construction and three independent attempts have now hit the same ceiling. Records what shipped (a 20.2% rag-mcp response trim, worth 0.49% of cost), what was killed by its own kill number, and the three measurement errors made on the way."
---

# Closed: Tool-Output Token Reduction

**Read this before proposing a fourth attempt.**

Three independent efforts have tried to cut tokens by shrinking what tools
return. All three were competently built. All three measured out near zero.

| Attempt | Shipped | Measured saving |
|---|---|---:|
| [Native tool-output filter](output-filter-retirement-20260726.md) | v4.16.0, removed v4.17.0 | **0.0000%** |
| [rtk-pack](rtk-pack-retirement-20260727.md) | v4.18.0, removed v4.19.0 | **0.0615%** |
| This review's only clean win (rag-mcp response trim) | rag-mcp, 2026-07-27 | **0.49%** |

This is not three unlucky implementations. It is one structural fact, measured
three different ways.

## Where the money actually is

1189 sessions with traffic, 83,352 assistant turns, priced at Opus list rates:

| Component | Share of cost |
|---|---:|
| `cache_read` | **63.1%** |
| `cache_creation` | 20.9% |
| `output` | 14.7% |
| `input` (uncached) | 1.3% |

**84% of cost is feeding context to the model.** Responses are 14.7%. That
closes "make the model write less" as a serious lever — the whole `brand-voice`
concise mode plays for a seventh of the bill.

Cache hit rate is **97.4%**. Published guidance treats 80–95% as the achievable
band, so there is nothing to win in cache tuning either.

Session shape: median 29 turns (mean 70.1), median peak context 71,276 tokens
(mean 114,712), median startup context 22,175 tokens.

## Why tool output cannot be the lever

Decomposed by amplification — every tool result is re-read on every turn that
follows it, so a result's true cost is its size times the turns remaining:

| Category | Share of `cache_read` |
|---|---:|
| Fixed startup prelude | 12.4% |
| `Read` results | 15.6% |
| `Bash` results | 6.7% |
| `rag-mcp` results | 3.8% |
| Unattributed (assistant text, thinking, user messages, reminders) | ~61% |

Every tool in the toolbox, amplified across every turn, is **26.1%** of
`cache_read`, and it is not compressible without losing what it says. The
original Phase 0 calculation reached the same place from the other direction:
tool results are 4.54% of input-token volume, so 4.54% is the arithmetic
ceiling for any mechanism operating on them.

Raw tool-result bytes, 113 MB across 1308 session files:

| Tool | Share of bytes |
|---|---:|
| `Read` | 62.2% |
| `Bash` | 26.1% |
| `rag-mcp` (3 tools) | 7.6% |
| everything else | <2% each |

## What shipped

**rag-mcp response compaction** — `compact_payload()` in
`app/rag-mcp-server/routes/kb_search.py`, applied to `smart_query`,
`hybrid_search_kb` and `get_document`, plus both sides of the smart_query cache
so a hit and a miss return identical bytes.

Verified by running the shipped function over 1356 real responses captured from
session logs: **20.2% smaller, with no field the agent acts on removed.**
That is 0.77% of `cache_read`, **0.49% of total cost**.

It drops request echo (`use_hyde`/`use_crag`/`use_multi_hop`), null result
columns, `_from_cache: false`, `total_documents_used` when it equals the result
count, and the part of `source_documents_used` that merely repeats
`results[].kb_id`. It deliberately keeps `file_path` (addresses Read/Edit, where
`kb_id` addresses get_document), `routing` (the only signal for which pipeline
ran), `score: 0.0`, and empty result sets. 16 unit tests, most of them asserting
what must survive rather than what gets removed.

## What was killed, and by what

A kill number was published before the work: *if the shipped changes do not cut
`cache_read` by 3%, stop and do not proceed to the behavioural changes.*

Result: **0.79%.** The threshold was not met, and the remaining items were not
built. The kill number did its job — this is the first of the three attempts
where it bound before code was written rather than after it shipped.

## Three measurement errors, and what they cost

Recorded because each one nearly produced a wrong decision, and because two of
them are the same class of error that produced the previous two failures.

**1. Duplicate reads: 11.1% was actually 0.1%.** The first pass keyed duplicate
detection on `file_path` alone, counting re-reads of *different ranges* of the
same file as waste. Re-keyed on `(file_path, offset, limit)`:

| Key | Duplicates | Bytes | Share of `Read` |
|---|---:|---:|---:|
| path only (wrong) | 1754 | 7,787,530 | 11.1% |
| path + offset + limit (right) | **36** | **90,975** | **0.1%** |

A whole planned deliverable — a session-scoped dedup hook, with a designed
mitigation for the post-compaction re-read hazard — rested on that 11.1%. It
does not exist.

**2. A 58% "trim" that was deleting document content.** An aggressive variant of
the rag-mcp compaction measured 58% smaller. It was whitelisting top-level keys
and thereby dropping `content` — which for `get_document` *is* the document,
30.5% of all bytes those endpoints return. Not a trim; data loss that looked
like a win. The honest figure is 20.2%.

**3. "77.5% of the rag-mcp response is overhead."** Roughly half of that
non-content mass is `kb_id`, `file_path`, `title` and `score` — fields the agent
uses. Removable overhead is about 20%, not 77%.

The common thread: **every one of these errors made the opportunity look bigger
than it is, and every one was caught only by decomposing before building.** The
filter retirement drew the same conclusion about premise validation; rtk-pack
drew it about installing the artifact. This adds a third: decompose the metric
before trusting its headline.

## What is left, and why it was not taken

| Option | Value | Why not |
|---|---:|---|
| Model routing | tens of % | Ruled out by the maintainer — Opus 5 stays |
| Trim the toolkit's own startup prelude | ~2.5% of cost | Ruled out — costs skill/agent discoverability |
| `Read` with ranges instead of whole files | up to 10.4% of `cache_read` | The only remaining item of size, and **not quality-neutral**: it is a behavioural change whose effect on correctness cannot be measured automatically |
| Unattributed ~61% of `cache_read` | unknown | Assistant text, thinking blocks, user messages, system reminders — no clean cut available |

For the record, the startup prelude was measured rather than guessed. Median
startup context is 22,175 tokens against ~7,850 in the documented reference
shape, and the gap is the toolkit's own:

| Component | Count | ~tokens |
|---|---:|---:|
| skill descriptions | 108 | 5,051 |
| agent descriptions | 44 | 2,750 |
| project rules | 5 | 3,802 |
| global rules | 6 | 3,133 |
| `CLAUDE.md` files | 3 | 2,338 |
| **total** | | **17,076** |

The tool built to reduce tokens is the single largest addition to every
session's context. That is worth knowing, and it is still only 2.5% of cost,
because the prelude is 12.4% of `cache_read` and only part of it is removable.

## The rule this leaves behind

**Do not open a fourth tool-output token-reduction effort without first
producing a measurement that beats 4.54%.** That is the ceiling on this workload
and it has now been approached from three directions. Any proposal in this space
must state, before any code, which share of *input token volume* it addresses —
not which share of tool output, not which share of Bash bytes.

If token cost genuinely needs to come down, the levers that are actually large
are model selection and turn count. Both are policy decisions, not engineering
projects, and neither is in this line of work.

## Related

- [Output Filter Retirement](output-filter-retirement-20260726.md) — attempt one, 0.0000%
- [rtk-pack Retirement](rtk-pack-retirement-20260727.md) — attempt two, 0.0615%
- [rtk Pack Integration](rtk-pack-integration-20260726.md) — the Phase 0 ceiling calculation
- [MCP Context Trim v4.0 — abandoned](mcp-context-trim-v4-prd-obsoleted-20260727.md) — a fourth idea in this space, killed by the platform shipping the fix first
- [Output & Token Discipline](output-token-discipline-plan-20260504.md) — the plan all of this descends from

---

## kb/howto/README.md

---
title: "How-To Guides"
service: ai-toolkit
category: howto
tags: [howto, guides]
last_updated: "2026-03-25"
---

# How-To Guides

Step-by-step guides for common tasks. Guides will be added here as they are created.

---

## kb/planning/cloud-security-pack-plan.md

---
title: "Plan: Cloud Security Pack — Multi-Cloud Audit (GCP/AWS/Azure)"
category: planning
service: ai-toolkit
tags:
  - cloud-security
  - gcp
  - aws
  - azure
  - firebase
  - plugin-pack
  - security-audit
  - credentials
doc_type: plan
status: proposed
created: "2026-04-10"
last_updated: "2026-04-10"
completion: "0%"
council_review: "2026-04-10 — conditional FOR, scope reduction recommended"
description: "Plugin pack for deterministic, read-only security auditing of GCP (Firebase/Cloud Functions), AWS (S3/Lambda/IAM), and Azure (NSG/Functions/CosmosDB). Includes CLI credential management, static+live modes, false positive resolution, SARIF output, incremental scanning, and CI integration."
---

# Plan: Cloud Security Pack — Multi-Cloud Audit

**Status:** Proposed
**Completion:** 0%
**Created:** 2026-04-10
**Origin:** Firebase RTDB/Firestore rules audit, Cloud Functions public exposure, false positive resolution for App Check/Gateway patterns
**Estimated Effort:** 5-6 weeks (council-revised from original 3-4 weeks)

---

## 1. Objective

Create `cloud-security-pack` plugin pack that provides deterministic, read-only security auditing for three major cloud providers. All scripts are stdlib-only Python with zero external dependencies. The pack includes a dedicated agent, multiple scan scripts, CLI credential management, and CI pipeline integration.

**Key design principles:**
- **Read-only** — never modifies cloud resources, only reads state
- **Deterministic** — reproducible results, no LLM-driven regex (same pattern as `hipaa_scan.py`)
- **False positive aware** — context graph resolves "public endpoint behind gateway/App Check/WAF"
- **CI-ready** — `--output json` + `--output sarif` (SARIF v2.1.0 for GitHub Advanced Security), exit code 1 on HIGH, 0 otherwise
- **Credential isolation** — keys stored in `~/.softspark/ai-toolkit/credentials/`, accessible only by this pack's scripts
- **Static-first** — static mode (no credentials) is the default, live mode is opt-in upgrade
- **Incremental** — `--changed` flag scans only files modified since last commit (PR workflow)
- **IaC via `terraform show -json`** — wraps Terraform's own JSON output instead of parsing HCL directly

---

## 2. Architecture Overview

```
ai-toolkit credentials add gcp --file ~/sa-viewer.json
ai-toolkit credentials add aws --profile my-audit-profile
ai-toolkit credentials add azure --subscription abc-123

  ┌──────────────────────────────────────────────────────┐
  │              cloud-security-pack                      │
  │                                                      │
  │  Agent: cloud-security-auditor                       │
  │  Tools: Read, Grep, Glob, Bash (read-only commands)  │
  │                                                      │
  │  Skills:                                             │
  │    /cloud-security-audit          (orchestrator)     │
  │    /firebase-rules-audit          (GCP: rules)       │
  │    /cloud-functions-audit         (GCP: CF + IAM)    │
  │    /aws-security-audit            (AWS: S3/Lambda)   │
  │    /azure-security-audit          (Azure: NSG/Fn)    │
  │                                                      │
  │  Scripts (stdlib Python, zero deps):                 │
  │    gcp_auth.py                    (credential helper)│
  │    firebase_rules_scan.py         (static parser)    │
  │    cloud_functions_audit.py       (CF IAM + context) │
  │    aws_security_scan.py           (S3/Lambda/IAM)    │
  │    azure_security_scan.py         (NSG/Fn/RBAC)      │
  │    false_positive_resolver.py     (context graph)    │
  │    sarif_formatter.py             (SARIF v2.1.0)     │
  │    incremental.py                 (git diff filter)  │
  │                                                      │
  │  Modes:                                              │
  │    --static    (no credentials, parse IaC/source)    │
  │    --live      (credentials, deployed state)         │
  │    --output json|sarif  (CI pipeline)                │
  │    --changed <ref>  (incremental, static only)       │
  │    --explain <id>   (remediation lookup)             │
  └──────────────────────────────────────────────────────┘

### YAML Parsing Constraint (BLOCKER)

Python stdlib has NO YAML parser. This affects AWS static mode:
- CloudFormation templates (`.yaml`) — YAML
- `serverless.yml` — YAML
- SAM templates (`template.yaml`) — YAML

**Decision: JSON-only for static IaC parsing.** Rationale:
1. CloudFormation supports both JSON and YAML — JSON variant parseable with `json` module
2. `terraform show -json` outputs JSON — the primary Terraform path
3. `serverless.yml` → recommend users run `sls print --format json` to convert
4. Adding `pyyaml` breaks the stdlib-only constraint for the entire toolkit

**Practical impact:** ~30% of CloudFormation users use JSON, ~70% YAML. For YAML users, live mode (`--mode live`) still works (queries APIs directly, no file parsing needed). The `--explain` output will suggest `sls print --format json` conversion.

**v2 option:** Ship a vendored minimal YAML subset parser (~150 LOC, handles flat key-value and simple nested maps — enough for security-relevant fields like `Principal`, `Effect`, `authLevel`).
```

---

## 3. Progress Tracking

| # | Feature | Priority | Status | Est. Time | Notes |
|---|---------|----------|--------|-----------|-------|
| 1.1 | CLI `credentials` command (add/list/remove/test) | P0 | Proposed | 2d | 0600 perms, allowlist wrapper |
| 1.1b | `credentials init` interactive wizard | P1 | Proposed | 1.5d | **Deferred to Milestone 2** (orchestration-review: saves 1.5d in M1 critical path) |
| 1.2 | `cloud-security-auditor` agent | P0 | Proposed | 1d | Agent definition |
| 1.3 | SARIF + incremental scan infrastructure | P0 | Proposed | 2d | `--output sarif`, `--changed` flag |
| 2.1 | `firebase-rules-audit` skill + script | P0 | Proposed | 4-5d | Recursive descent parser (orchestration-review: +1d vs regex) |
| 2.2 | `cloud-functions-audit` skill + script | P0 | Proposed | 3-4d | CF IAM + App Check context |
| 2.3 | False positive resolver (GCP context) | P0 | Proposed | 3-4d | Context graph engine — GCP only (~8 code paths). **+2d per provider** in later milestones (orchestration-review) |
| 3.1 | `aws-security-audit` skill + script | P1 | Proposed | 4-5d | S3/Lambda/IAM/SG, `terraform show -json` |
| 3.2 | `/cloud-security-audit` orchestrator + plugin.json | P1 | Proposed | 3d | Multi-provider orchestration + pack |
| 4.1 | `azure-security-audit` skill + script | P1 | Proposed | 4-5d | NSG/Functions/RBAC |
| 5.1 | Tests + CI integration docs | P1 | Proposed | 3d | Tests + SARIF + pipeline examples |
| 5.2 | Documentation (kb/) | P2 | Proposed | 1d | Checklists, patterns, KB |

**Phasing (full delivery, all 3 providers):**
- **Phase 1 (week 1-2):** Foundation + GCP — credentials CLI, agent, SARIF/incremental infra, firebase-rules, cloud-functions, false positive resolver (GCP context)
- **Phase 2 (week 3-4):** AWS + orchestrator — AWS security audit, `terraform show -json`, orchestrator skill, plugin pack, `credentials init`
- **Phase 3 (week 5-6):** Azure + polish — Azure security audit, false positive resolver (Azure context), full test suite, documentation

---

## 4. Dependency Graph

```
                         Phase 1: Foundation + GCP (week 1-2)
                         ====================================
credentials CLI (1.1) ─────┐
                            ├──► firebase-rules-audit (2.1)
SARIF + incremental (1.3) ──┤
                            ├──► cloud-functions-audit (2.2) ──► false-positive-resolver (2.3)
agent definition (1.2) ─────┘

                         Phase 2: AWS + Orchestrator (week 3-4)
                         ======================================
credentials init (1.1b) ───┐
                            ├──► aws-security-audit (3.1) ─────► false-positive-resolver (+AWS context)
                            └──► orchestrator skill + plugin.json (3.2)

                         Phase 3: Azure + Polish (week 5-6)
                         ==================================
                            ├──► azure-security-audit (4.1) ───► false-positive-resolver (+Azure context)
                            └──► tests + docs (5.1, 5.2)
```

**All 3 providers ship.** No conditional gates — full delivery in 6 weeks.

---

## 5. Detailed Implementation

### Faza 1: Foundation (tydzien 1)

#### 1.1 CLI `credentials` Command

**Purpose:** Secure credential storage for cloud provider API access. Credentials live outside any project directory and are only accessible by this pack's scripts.

**CLI interface:**
```bash
# GCP — Service Account JSON
ai-toolkit credentials add gcp --file ~/sa-viewer.json
ai-toolkit credentials add gcp --file ~/sa-viewer.json --project my-project-id

# GCP — use existing gcloud session (no file needed)
ai-toolkit credentials add gcp --gcloud --project my-project-id

# AWS — named profile (reads from ~/.aws/credentials)
ai-toolkit credentials add aws --profile audit-readonly
ai-toolkit credentials add aws --profile audit-readonly --region eu-west-1

# AWS — explicit keys (interactive, never on CLI args)
ai-toolkit credentials add aws --interactive

# Azure — subscription
ai-toolkit credentials add azure --subscription abc-123-def

# Azure — use existing az login session
ai-toolkit credentials add azure --az-cli

# Interactive guided setup (reduces onboarding from 4 steps to 1)
ai-toolkit credentials init           # auto-detect provider, interactive wizard
ai-toolkit credentials init --provider gcp  # skip auto-detect, go straight to GCP setup

# Management
ai-toolkit credentials list
ai-toolkit credentials remove gcp
ai-toolkit credentials remove aws
ai-toolkit credentials remove azure
ai-toolkit credentials test gcp       # verify read-only access works
ai-toolkit credentials test aws
```

**Storage structure:**
```
~/.softspark/ai-toolkit/
  credentials/
    gcp.json              # SA key file (copied, chmod 0600)
    gcp.meta.json         # { project_id, added_at, method: "file"|"gcloud" }
    aws.json              # { profile, region, method: "profile"|"keys" }
    azure.json            # { subscription_id, method: "subscription"|"az-cli" }
```

**`credentials init` interactive flow:**
1. Auto-detect providers from project files (`firebase.json` → GCP, `*.tf` with `provider "aws"` → AWS, etc.)
2. If multiple detected → ask user: "Found GCP and AWS markers. Which provider to configure first? [gcp/aws/both]"
3. Per provider:
   - GCP: "Do you have a Service Account JSON file? [y/n]" → if yes: ask path → if no: "Run `gcloud auth application-default login` and we'll use that"
   - AWS: "Do you have a named profile in ~/.aws/credentials? [y/n]" → if yes: ask profile name → if no: "Run `aws configure` first"
   - Azure: "Do you have an active `az login` session? [y/n]" → if yes: ask subscription ID → if no: "Run `az login` first"
4. Run `credentials test` automatically after setup
5. Generate `.cloud-security.json` scaffold with detected context

**Security requirements:**
- All credential files: `chmod 0600` (owner read/write only)
- Never log credential contents to stdout/stderr
- `credentials test` validates:
  - Connection works (GCP: `gcloud auth list`, AWS: `aws sts get-caller-identity`, Azure: `az account show`)
  - SA/role has **only read permissions** — **REFUSE to store** if write access detected (orchestration-review: warn-only is ignored by users). Override: `--force` flag with explicit acknowledgment
  - Project/subscription exists
- `.gitignore`-proof — lives in `~/.softspark/ai-toolkit/`, never in project directory
- Scripts access credentials via `gcp_auth.py` helper — single entry point, no direct file reads

**Files to create/modify:**

| File | Action | Description |
|------|--------|-------------|
| `scripts/credentials_cli.py` | CREATE | CLI: add/list/remove/test credentials |
| `bin/ai-toolkit.js` | EDIT | Register `credentials` subcommand |
| `tests/test_credentials.bats` | CREATE | Tests: add, remove, permissions, test |

**Success Criteria:**
- [ ] `credentials add gcp --file` copies and secures SA key
- [ ] `credentials add aws --profile` stores profile reference
- [ ] `credentials add azure --subscription` stores subscription
- [ ] `credentials test` validates read access + warns on write perms
- [ ] `credentials list` shows providers without exposing secrets
- [ ] `credentials remove` cleans up securely
- [ ] All files created with 0600 permissions
- [ ] Tests: >= 8

---

#### 1.3 SARIF Output + Incremental Scanning (Council addition)

**SARIF v2.1.0 output** — industry standard consumed by GitHub Advanced Security (inline PR annotations), VS Code SARIF Viewer, Azure DevOps, and SonarQube.

```bash
/cloud-security-audit --output sarif > results.sarif

# GitHub Actions: upload SARIF for inline PR annotations
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif
```

**SARIF structure (per finding):**
```json
{
  "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/sarif-2.1/schema/sarif-schema-2.1.0.json",
  "version": "2.1.0",
  "runs": [{
    "tool": { "driver": {
      "name": "cloud-security-audit", "version": "1.0.0",
      "rules": [{ "id": "GCP-CF-001", "shortDescription": { "text": "Public Cloud Function invoker" }, "helpUri": "https://cloud.google.com/functions/docs/securing" }]
    } },
    "results": [{
      "ruleId": "GCP-CF-001",
      "level": "error",
      "message": { "text": "Cloud Function 'adminEndpoint' has allUsers invoker with no protection layer" },
      "locations": [{ "physicalLocation": { "artifactLocation": { "uri": "functions/src/admin.ts" }, "region": { "startLine": 42 } } }],
      "properties": { "resolved_severity": "HIGH", "context_chain": [], "provider": "gcp" }
    }]
  }]
}
```

**Incremental scan mode** — scan only changed files since last commit:

```bash
/cloud-security-audit --changed              # files changed vs HEAD~1
/cloud-security-audit --changed HEAD~5       # files changed in last 5 commits
/cloud-security-audit --changed main         # files changed vs main branch (PR workflow)
```

Implementation: use `git diff --name-only <ref>` to get changed files, filter to relevant extensions (.rules, .tf, .json, .ts, .py, .bicep), scan only those. Falls back to full scan if no git repo detected.

**`--changed` applies to static mode ONLY.** Live mode always scans all deployed resources (it queries cloud APIs, not files). If user passes `--changed` with `--mode live`, emit warning: "Incremental scan applies to static analysis only. Live mode will scan all resources." and proceed with full live scan.

**`--explain` flag** — detailed remediation for a specific finding:

```bash
/cloud-security-audit --explain GCP-CF-001
# Output: what the finding means, why it matters, exact fix steps,
# links to GCP documentation, CIS Benchmark reference
```

**Files:**

| File | Action | Description |
|------|--------|-------------|
| `app/skills/cloud-security-audit/scripts/sarif_formatter.py` | CREATE | SARIF v2.1.0 output |
| `app/skills/cloud-security-audit/scripts/incremental.py` | CREATE | Git diff + file filter |
| `app/skills/cloud-security-audit/reference/rule-explanations.json` | CREATE | Per-rule remediation guides |

**Success Criteria:**
- [ ] `--output sarif` produces valid SARIF v2.1.0 JSON with `driver.rules[]` array (orchestration-review: GitHub silently drops annotations without rule metadata)
- [ ] SARIF upload to GitHub Advanced Security works (inline PR annotations)
- [ ] SARIF `level` mapping: HIGH→`error`, WARN→`warning`, INFO→`note`
- [ ] `--changed main` scans only PR-changed files
- [ ] `--explain <rule-id>` shows detailed remediation
- [ ] Tests: >= 6

---

#### 1.2 Agent Definition: `cloud-security-auditor`

**File:** `app/agents/cloud-security-auditor.md`

```markdown
---
name: cloud-security-auditor
description: "Multi-cloud security auditor (GCP/AWS/Azure). Read-only deterministic scans
  for IAM, network, storage, serverless, and compliance. False positive resolution
  via security context graph."
model: opus
color: red
tools: Read, Grep, Glob, Bash
skills: security-patterns, cloud-security-audit
---

# Cloud Security Auditor Agent

You are the **Cloud Security Auditor**. You perform read-only security assessments
across GCP, AWS, and Azure. You never modify cloud resources.

## Core Philosophy
**"Read everything, change nothing. Context before verdict."**

## Mandatory Protocol
Before any audit:
1. Check credentials: `ai-toolkit credentials test <provider>`
2. Determine mode: `--static` (IaC/source only) or `--live` (deployed state)
3. Run deterministic scripts first, then interpret results

## Responsibilities

### 1. Static Analysis (no credentials needed)
- Parse IaC: Terraform (.tf), CloudFormation (.yaml/.json), Bicep (.bicep)
- Parse Firebase rules: firestore.rules, database.rules.json
- Parse source: Cloud Functions (onCall vs onRequest), Lambda handlers, Azure Functions
- Parse configs: firebase.json, serverless.yml, sam-template.yaml

### 2. Live Analysis (credentials required, READ-ONLY)
- GCP: `gcloud` CLI commands (list, describe, get-iam-policy)
- AWS: `aws` CLI commands (s3api, lambda, iam, ec2 — get/list/describe only)
- Azure: `az` CLI commands (network nsg, functionapp, cosmosdb — list/show only)

### 3. False Positive Resolution
Build security context graph before rendering verdict:
- Public endpoint → check: API Gateway? WAF? App Check? CDN?
- Open port → check: behind Load Balancer? VPN? private subnet?
- Broad IAM role → check: scoped to specific resource? temporary?

## Allowed CLI Commands (WHITELIST — read-only only)

### GCP
- gcloud functions list / describe / get-iam-policy
- gcloud projects get-iam-policy
- gcloud app-check services list
- gcloud firestore indexes list
- gcloud compute firewall-rules list
- gcloud run services list / describe
- firebase apps:list

### AWS
- aws s3api get-bucket-policy / get-bucket-acl / get-public-access-block
- aws lambda get-policy / get-function-configuration / list-functions
- aws iam list-roles / list-policies / get-role / get-policy-version
- aws ec2 describe-security-groups / describe-network-acls
- aws apigateway get-rest-apis / get-resources
- aws elbv2 describe-load-balancers / describe-listeners

### Azure
- az network nsg list / show / rule list
- az functionapp list / show / config show
- az cosmosdb list / show / keys list
- az role assignment list
- az webapp show / config show
- az network application-gateway list

### NEVER ALLOWED
- Any create/update/delete/put/set/deploy/push command
- Any command that modifies state
- `gcloud auth activate-service-account` (credential pivot)
- `aws sts assume-role` (lateral movement)
- `az login` (session hijack)
- `terraform apply` / `terraform destroy`

## Output Format
(see skill SKILL.md for detailed format)
```

**SECURITY: Programmatic Bash Allowlist (orchestration-review P0 BLOCKER)**

The read-only whitelist above lives in the agent's system prompt. An LLM can be prompt-injected via malicious IaC files or source code comments. **The prompt-only approach is insufficient.**

**Required:** A shell wrapper script (`scripts/cloud_security_allowlist.sh`) that validates every CLI invocation against a compiled allowlist regex BEFORE execution, independent of the LLM:

```bash
#!/bin/bash
# cloud_security_allowlist.sh — wraps Bash calls from cloud-security-auditor
# Rejects any command not matching read-only patterns

ALLOWED_PATTERNS=(
  '^gcloud (functions|projects|app-check|firestore|compute|run) (list|describe|get-iam-policy|indexes)'
  '^gcloud auth list$'
  '^firebase apps:list'
  '^aws (s3api|lambda|iam|ec2|apigateway|elbv2|sts|cloudfront) (get-|list-|describe-|generate-credential-report)'
  '^aws sts get-caller-identity$'
  '^az (network|functionapp|cosmosdb|role|webapp|storage) (list|show|rule list|config show|assignment list|account show)'
  '^az account show$'
  '^terraform show -json'
  '^git diff --name-only'
  '^python3 .*/scripts/.*\.(py)$'
)

CMD="$*"
for pattern in "${ALLOWED_PATTERNS[@]}"; do
  if [[ "$CMD" =~ $pattern ]]; then
    exec $CMD
  fi
done

echo "BLOCKED: Command not in read-only allowlist: $CMD" >&2
exit 1
```

The agent's `allowed-tools` in SKILL.md references this wrapper instead of raw Bash. All cloud CLI calls go through the allowlist.

**`terraform plan` risk (orchestration-review):** `terraform plan -json` executes providers and provisioners. A malicious `.tf` file with `local-exec` provisioner runs arbitrary code during plan. **Decision: use `terraform show -json` ONLY (reads existing state), NOT `terraform plan -json`.** Document this prominently.

**Files:**

| File | Action | Description |
|------|--------|-------------|
| `app/skills/cloud-security-audit/scripts/cloud_security_allowlist.sh` | CREATE | Bash allowlist wrapper |

**Success Criteria:**
- [ ] Agent file created in `app/agents/`
- [ ] Read-only command whitelist documented
- [ ] NEVER ALLOWED section explicit
- [ ] Programmatic Bash allowlist enforced (not just prompt)
- [ ] `terraform plan` excluded — only `terraform show -json` allowed
- [ ] Allowlist tested: blocked commands return exit 1

---

### Faza 2: GCP / Firebase (Phase 1, tydzien 1-2)

#### 2.1 Skill: `firebase-rules-audit`

**Purpose:** Static analysis of Firestore rules and RTDB rules. No credentials needed.

**What it scans:**

| Check | Severity | Description |
|-------|----------|-------------|
| `allow read, write: if true` | HIGH | World-readable/writable collection |
| `allow read: if true` without `write` guard | WARN | Public read — may be intentional |
| `allow write: if request.auth != null` without field validation | WARN | Authenticated but no field-level validation |
| Missing `request.resource.data` validation on writes | WARN | No schema enforcement |
| Wildcard collection `/{document=**}` with broad permissions | HIGH | Recursive wildcard + open access |
| RTDB `.read: true` or `.write: true` at root | HIGH | Entire database public |
| RTDB `.read: "auth != null"` without path scoping | WARN | All authenticated users can read everything |
| Timestamp/TTL rules missing for sensitive collections | WARN | No data lifecycle enforcement |
| `get()` / `exists()` cross-collection reads without auth check | WARN | Privilege escalation via rule chaining |
| Rules file > 256KB (approaching Firebase limit) | WARN | May hit deployment limit |

**Script:** `scripts/firebase_rules_scan.py`
- Parses `firestore.rules` via **recursive descent parser** (not regex — orchestration-review P1)
  - Grammar: ~8 production rules (service, match, allow, function, condition)
  - Tracks: brace depth, current match path, accumulated allow blocks
  - Handles: nested `match` blocks, multi-line conditions with `&&`/`||`, custom `function` declarations
  - Estimated: 550-650 LOC for parser + check logic
  - Unsupported (documented): CEL ternary expressions, complex `get()`/`exists()` chains with computed paths
- Parses `database.rules.json` (JSON rules — stdlib `json` module)
- Outputs findings as JSON or text
- Exit code 1 on HIGH, 0 otherwise
- Supports `.cloud-security-ignore` for suppressions

**Reference file:** `reference/firebase-rules-patterns.md` — safe/unsafe patterns with examples

**Files:**

| File | Action | Description |
|------|--------|-------------|
| `app/skills/firebase-rules-audit/SKILL.md` | CREATE | Skill definition |
| `app/skills/firebase-rules-audit/scripts/firebase_rules_scan.py` | CREATE | Deterministic scanner |
| `app/skills/firebase-rules-audit/reference/firebase-rules-patterns.md` | CREATE | Safe/unsafe patterns |

**Success Criteria:**
- [ ] Parses `firestore.rules` — detects 10+ check patterns
- [ ] Parses `database.rules.json` — detects root-level open access
- [ ] `--output json` for CI
- [ ] `.cloud-security-ignore` support
- [ ] Tests: >= 10 (one per check pattern + edge cases)

---

#### 2.2 Skill: `cloud-functions-audit`

**Purpose:** Audit Cloud Functions permissions and detect false positives.

**Static mode (no credentials):**

| Check | Severity | Description |
|-------|----------|-------------|
| `onRequest` handler without auth middleware | WARN | Potentially public — needs context |
| `onCall` handler (inherently authenticated) | INFO | Informational — callable is auth'd |
| Hardcoded API keys / secrets in source | HIGH | Secrets in code |
| CORS `origin: '*'` in CF handler | WARN | Unrestricted CORS |
| Missing rate limiting patterns | WARN | No throttling on public endpoint |
| `functions.https.onRequest` + no `validateFirebaseIdToken` | WARN | HTTP function without Firebase Auth check |

**Live mode (credentials required):**

| Check | Severity | CLI Command | Description |
|-------|----------|-------------|-------------|
| `allUsers` invoker on CF | CONTEXT | `gcloud functions get-iam-policy` | Public — resolve with context graph |
| `allAuthenticatedUsers` invoker | WARN | `gcloud functions get-iam-policy` | Any Google account can invoke |
| App Check enforcement status | CONTEXT | `gcloud app-check services list` | Feeds into false positive resolution |
| Deployed rules vs local rules diff | WARN | `gcloud firestore indexes` + local | Rules drift detection |
| Cloud Run public ingress | CONTEXT | `gcloud run services describe` | Public — resolve with context graph |
| Overly broad IAM roles on SA | HIGH | `gcloud projects get-iam-policy` | CF service account with editor/owner |

**Script:** `scripts/cloud_functions_audit.py`

**Files:**

| File | Action | Description |
|------|--------|-------------|
| `app/skills/cloud-functions-audit/SKILL.md` | CREATE | Skill definition |
| `app/skills/cloud-functions-audit/scripts/cloud_functions_audit.py` | CREATE | Scanner |
| `app/skills/cloud-functions-audit/scripts/gcp_auth.py` | CREATE | Credential loader |
| `app/skills/cloud-functions-audit/reference/false-positives-gcp.md` | CREATE | False positive patterns |

**Success Criteria:**
- [ ] Static: parses CF source for auth patterns
- [ ] Live: checks IAM bindings via `gcloud`
- [ ] False positive resolution for App Check + Gateway patterns
- [ ] Tests: >= 8

---

#### 2.3 False Positive Resolver

**Purpose:** Central engine that resolves "is this actually a problem?" by building a security context graph.

**How it works:**
```
Input: Finding { resource, severity, type }

Step 1: Gather context
  ├── Check API Gateway routes (firebase.json rewrites, API Gateway configs)
  ├── Check WAF/CDN (Cloudflare, CloudFront, Azure Front Door)
  ├── Check App Check / AppArmor / Shield
  ├── Check callable vs HTTP function type
  ├── Check VPC / private subnet placement
  └── Check Load Balancer + auth middleware

Step 2: Apply resolution rules
  ├── Public CF + App Check ENFORCED → SUPPRESSED (protected)
  ├── Public CF + API Gateway route → SUPPRESSED (gateway handles auth)
  ├── Public CF + onCall() → SUPPRESSED (callable is auth'd by SDK)
  ├── Public S3 + CloudFront OAI → SUPPRESSED (not directly accessible)
  ├── Open SG port + ALB → SUPPRESSED (ALB handles TLS + auth)
  ├── Open NSG + Application Gateway → SUPPRESSED (WAF handles filtering)
  └── No context found → KEEP ORIGINAL SEVERITY

Step 3: Output
  ├── Original severity
  ├── Resolved severity (SUPPRESSED / DOWNGRADED / CONFIRMED)
  ├── Context chain (what protections were found)
  └── Confidence (high if multiple protections, low if single)
```

**Output example:**
```json
{
  "resource": "processPayment",
  "provider": "gcp",
  "type": "cloud-function-public-invoker",
  "original_severity": "HIGH",
  "resolved_severity": "SUPPRESSED",
  "confidence": "high",
  "context_chain": [
    { "layer": "app_check", "status": "ENFORCED", "source": "gcloud app-check services list" },
    { "layer": "function_type", "status": "onCall", "source": "source:index.ts:42" },
    { "layer": "api_gateway", "status": "ROUTED", "source": "firebase.json:rewrites" }
  ],
  "verdict": "3/3 protection layers active. Suppressing finding."
}
```

**Script:** `scripts/false_positive_resolver.py`

**Resolution rules stored in:** `reference/resolution-rules.json`
```json
{
  "rules": [
    {
      "id": "gcp-cf-appcheck",
      "finding_type": "cloud-function-public-invoker",
      "provider": "gcp",
      "context_required": ["app_check:ENFORCED"],
      "action": "SUPPRESS",
      "reason": "App Check enforced — only verified app instances can invoke"
    },
    {
      "id": "gcp-cf-callable",
      "finding_type": "cloud-function-public-invoker",
      "provider": "gcp",
      "context_required": ["function_type:onCall"],
      "action": "SUPPRESS",
      "reason": "onCall functions require Firebase Auth token from client SDK"
    },
    {
      "id": "aws-s3-cloudfront-oai",
      "finding_type": "s3-bucket-public-access",
      "provider": "aws",
      "context_required": ["cloudfront_oai:ACTIVE"],
      "action": "SUPPRESS",
      "reason": "Bucket accessed only via CloudFront Origin Access Identity"
    },
    {
      "id": "azure-func-apigw",
      "finding_type": "function-app-public",
      "provider": "azure",
      "context_required": ["application_gateway:ACTIVE"],
      "action": "SUPPRESS",
      "reason": "Function behind Application Gateway with WAF"
    }
  ]
}
```

**Files:**

| File | Action | Description |
|------|--------|-------------|
| `app/skills/cloud-security-audit/scripts/false_positive_resolver.py` | CREATE | Context graph engine |
| `app/skills/cloud-security-audit/reference/resolution-rules.json` | CREATE | Configurable rules |

**Success Criteria:**
- [ ] Resolves GCP: App Check, Gateway, callable patterns
- [ ] Resolves AWS: CloudFront OAI, ALB, WAF patterns
- [ ] Resolves Azure: App Gateway, Front Door, VNET patterns
- [ ] JSON output with context chain
- [ ] User can add custom rules to `.cloud-security.json` `context` section
- [ ] Tests: >= 12 (4 per provider)

---

### Faza 3: AWS (Phase 2, tydzien 3-4)

#### 3.1 Skill: `aws-security-audit`

**Static mode (IaC parsing):**

| Check | Severity | Source | Description |
|-------|----------|--------|-------------|
| S3 bucket `"Effect": "Allow", "Principal": "*"` | HIGH | .tf / .json | Public bucket policy |
| S3 `BlockPublicAccess` all false | HIGH | .tf / .json | Public access not blocked |
| Lambda `resource-based policy` with `Principal: "*"` | HIGH | .tf / .json | Public Lambda |
| Security Group `0.0.0.0/0` ingress on non-80/443 | HIGH | .tf / .json | Open port to world |
| IAM policy with `Action: "*"` | HIGH | .tf / .json | God-mode IAM |
| IAM policy with `Resource: "*"` + sensitive actions | WARN | .tf / .json | Broad resource scope |
| Unencrypted RDS/DynamoDB | WARN | .tf / .json | Missing encryption at rest |
| CloudTrail disabled | HIGH | .tf / .json | No audit logging |
| Missing VPC Flow Logs | WARN | .tf / .json | No network monitoring |

**Live mode:**

| Check | CLI Command | Description |
|-------|-------------|-------------|
| S3 public buckets | `aws s3api get-public-access-block` | Per-bucket public access |
| Lambda public policies | `aws lambda get-policy` | Resource-based policies |
| Open Security Groups | `aws ec2 describe-security-groups` | Ingress from 0.0.0.0/0 |
| Overly permissive IAM | `aws iam list-roles` + `get-role` | Roles with admin/broad access |
| Unused IAM credentials | `aws iam generate-credential-report` | Stale access keys |
| API Gateway without auth | `aws apigateway get-rest-apis` | Endpoints without authorizer |

**Script:** `scripts/aws_security_scan.py`

**Files:**

| File | Action | Description |
|------|--------|-------------|
| `app/skills/aws-security-audit/SKILL.md` | CREATE | Skill definition |
| `app/skills/aws-security-audit/scripts/aws_security_scan.py` | CREATE | Scanner |
| `app/skills/aws-security-audit/scripts/aws_auth.py` | CREATE | Credential loader |
| `app/skills/aws-security-audit/reference/aws-security-checklist.md` | CREATE | CIS Benchmark mapping |
| `app/skills/aws-security-audit/reference/false-positives-aws.md` | CREATE | ALB/CloudFront/WAF patterns |

**Terraform approach (council revision):** Do NOT parse HCL directly (stdlib-only Python cannot handle heredocs, variable interpolation, modules, `for_each`). Instead wrap `terraform show -json` / `terraform plan -json` which outputs clean JSON. Fallback to flat-resource regex for projects without `terraform` CLI.

**Success Criteria:**
- [ ] Static: `terraform show -json` wrapper + CloudFormation/SAM JSON parsing
- [ ] Live: checks S3, Lambda, IAM, SG via `aws` CLI
- [ ] False positive resolution for CloudFront/ALB/WAF
- [ ] CIS Benchmark mapping in reference
- [ ] Tests: >= 10

---

### Faza 4: Azure (Phase 3, tydzien 5-6)

#### 4.1 Skill: `azure-security-audit`

**Static mode (IaC parsing):**

| Check | Severity | Source | Description |
|-------|----------|--------|-------------|
| NSG rule `0.0.0.0/0` source on management ports | HIGH | .tf / .bicep | Open RDP/SSH to world |
| Function App `authLevel: "anonymous"` | WARN | source / .tf | Public Azure Function |
| Cosmos DB `publicNetworkAccess: enabled` | WARN | .tf / .bicep | Public database access |
| Storage Account `allowBlobPublicAccess: true` | HIGH | .tf / .bicep | Public blob storage |
| Missing Key Vault references (hardcoded secrets) | HIGH | source | Secrets not in Key Vault |
| Missing RBAC (classic co-admin model) | WARN | .tf | Legacy access model |

**Live mode:**

| Check | CLI Command | Description |
|-------|-------------|-------------|
| Open NSG rules | `az network nsg rule list` | Broad inbound rules |
| Function App auth | `az functionapp show` + `config` | Auth level and provider |
| Cosmos DB access | `az cosmosdb show` | Network access settings |
| RBAC assignments | `az role assignment list` | Owner/Contributor sprawl |
| Storage public access | `az storage account show` | Blob public access |
| App Service auth | `az webapp auth show` | Auth configuration |

**Script:** `scripts/azure_security_scan.py`

**Files:**

| File | Action | Description |
|------|--------|-------------|
| `app/skills/azure-security-audit/SKILL.md` | CREATE | Skill definition |
| `app/skills/azure-security-audit/scripts/azure_security_scan.py` | CREATE | Scanner |
| `app/skills/azure-security-audit/scripts/azure_auth.py` | CREATE | Credential loader |
| `app/skills/azure-security-audit/reference/azure-security-checklist.md` | CREATE | CIS Benchmark mapping |
| `app/skills/azure-security-audit/reference/false-positives-azure.md` | CREATE | App Gateway/Front Door patterns |

**Success Criteria:**
- [ ] Static: parses Terraform, Bicep, ARM templates
- [ ] Live: checks NSG, Functions, CosmosDB, RBAC via `az` CLI
- [ ] False positive resolution for App Gateway/Front Door/VNET
- [ ] Tests: >= 10

---

### Faza 3 (cont.): Orchestration + Pack Integration (Phase 2, tydzien 3-4)

#### 3.2 Orchestrator Skill: `/cloud-security-audit`

**Purpose:** Single entry point that runs all provider audits detected in the project.

**Behavior:**
1. Auto-detect providers from project files:
   - `firebase.json` / `firestore.rules` / `.firebaserc` → GCP
   - `serverless.yml` / `template.yaml` / `*.tf` with `provider "aws"` → AWS
   - `*.bicep` / `*.tf` with `provider "azurerm"` / `azure-pipelines.yml` → Azure
2. Check available credentials: `ai-toolkit credentials list`
3. Run detected provider scans in parallel
4. Merge results through false positive resolver
5. Output unified report

**Skill frontmatter:**
```yaml
---
name: cloud-security-audit
description: "Multi-cloud security audit — auto-detects GCP/AWS/Azure and runs
  deterministic scans with false positive resolution"
user-invocable: true
effort: high
disable-model-invocation: true
context: fork
agent: cloud-security-auditor
argument-hint: "[path] [--provider gcp|aws|azure|auto] [--mode static|live] [--severity high|warn] [--output json]"
allowed-tools: Read, Grep, Glob, Bash
---
```

**CLI usage:**
```bash
/cloud-security-audit                            # auto-detect providers, static mode (default)
/cloud-security-audit --provider gcp             # GCP only
/cloud-security-audit --provider aws,azure       # AWS + Azure
/cloud-security-audit --mode static              # no credentials, IaC/source only (DEFAULT)
/cloud-security-audit --mode live                # deployed state (requires credentials)
/cloud-security-audit --severity high            # HIGH findings only
/cloud-security-audit --output json              # CI pipeline output
/cloud-security-audit --output sarif             # SARIF v2.1.0 for GitHub Advanced Security
/cloud-security-audit --changed main             # incremental: only files changed vs main
/cloud-security-audit --explain GCP-CF-001       # detailed remediation for specific rule
/cloud-security-audit src/functions/             # scan specific path
```

**Unified report format:**
```markdown
## Cloud Security Audit Report

### Summary
| Metric | GCP | AWS | Azure | Total |
|--------|-----|-----|-------|-------|
| Mode | live | static | n/a | — |
| Resources scanned | 12 | 8 | 0 | 20 |
| HIGH | 2 | 1 | 0 | 3 |
| WARN | 4 | 3 | 0 | 7 |
| SUPPRESSED (false positive) | 3 | 1 | 0 | 4 |

### Findings (sorted by severity)

#### [HIGH] GCP: Cloud Function "adminEndpoint" — public invoker, no protection
...

#### [SUPPRESSED] GCP: Cloud Function "processPayment" — public invoker
Context: App Check ENFORCED + onCall + API Gateway routed (3/3 layers)
...
```

---

#### 3.2.1 Plugin Pack Manifest

**File:** `app/plugins/cloud-security-pack/plugin.json`

```json
{
  "name": "cloud-security-pack",
  "description": "Multi-cloud security auditing for GCP, AWS, and Azure",
  "version": "1.0.0",
  "domain": "cloud-security",
  "type": "plugin-pack",
  "status": "experimental",
  "requires": [],
  "includes": {
    "agents": ["cloud-security-auditor"],
    "skills": [
      "cloud-security-audit",
      "firebase-rules-audit",
      "cloud-functions-audit",
      "aws-security-audit",
      "azure-security-audit"
    ],
    "rules": [],
    "hooks": []
  },
  "credentials": {
    "supported_providers": ["gcp", "aws", "azure"],
    "setup_command": "ai-toolkit credentials add <provider>"
  }
}
```

**Directory structure:**
```
app/plugins/cloud-security-pack/
├── plugin.json
├── README.md
└── (skills and agent live in core app/ dirs, referenced by name)
```

---

### Faza 5: Tests + Documentation (ongoing, ships with each milestone)

#### 5.1 Tests

| Test file | Count | Description |
|-----------|-------|-------------|
| `tests/test_credentials.bats` | 8+ | CLI credentials management |
| `tests/test_firebase_rules_scan.py` | 10+ | Firestore/RTDB rules patterns |
| `tests/test_cloud_functions_audit.py` | 8+ | CF static + live checks |
| `tests/test_aws_security_scan.py` | 10+ | S3/Lambda/IAM/SG checks |
| `tests/test_azure_security_scan.py` | 10+ | NSG/Functions/CosmosDB checks |
| `tests/test_false_positive_resolver.py` | 12+ | Context graph resolution |
| `tests/test_sarif_formatter.py` | 4+ | SARIF v2.1.0 output validation |
| `tests/test_incremental.py` | 4+ | Git diff filtering, fallback |
| `tests/test_credentials_init.py` | 4+ | Interactive wizard, auto-detect |
| **Total** | **70+** | |

#### 5.2 Documentation

| File | Description |
|------|-------------|
| `kb/planning/cloud-security-pack-plan.md` | This document |
| `kb/reference/cloud-security-checklist.md` | Unified multi-cloud checklist (created when Milestone 1 ships) |
| Skills `reference/` dirs | Per-provider patterns and false positives |

---

## 6. Configuration & Suppression (Unified)

**Council revision:** merged `.cloud-security-ignore` + `.cloud-security-config` into a single `.cloud-security.json`. Two config files is one too many — developers expect one file.

Scaffold interactively: `ai-toolkit credentials init` generates this file.

**Suppression Governance (orchestration-review P0):**
- **Wildcard ignores** (e.g., `GCP-CF-*`) REQUIRE a `justification` field — scanner refuses to suppress without one
- **All ignore entries** require `justification` — enforced by schema validation
- **CI diff detection:** When `.cloud-security.json` is modified in a PR, scanner emits a `SUPPRESSION_CHANGED` finding (severity: WARN) listing added/removed/modified ignore rules. This prevents silent suppression of vulnerabilities via committed config changes.
- **In live mode:** context claims (e.g., `app_check_enforced: true`) are verified against actual cloud state. If claim doesn't match reality, emit `CONTEXT_MISMATCH` finding (severity: HIGH)

```json
{
  "$schema": "https://softspark.github.io/ai-toolkit/schemas/cloud-security.json",

  "ignore": [
    { "rule": "GCP-CF-001:processPayment", "justification": "Behind App Check + API Gateway, verified 2026-04-10" },
    { "rule": "AWS-S3-001:static-assets", "justification": "Intentionally public static bucket, CloudFront OAI active" },
    { "rule": "GCP-CF-*", "justification": "REQUIRED for wildcard suppression — reviewed by @jacek in PR #142" }
  ],

  "context": {
    "gcp": {
      "app_check_enforced": true,
      "api_gateway": "projects/my-proj/locations/us-central1/gateways/main",
      "known_public_functions": ["healthCheck", "webhookReceiver"]
    },
    "aws": {
      "waf_enabled": true,
      "cloudfront_distributions": ["E1234567890"],
      "known_public_buckets": ["static-assets-prod"]
    },
    "azure": {
      "front_door_enabled": true,
      "application_gateway": "my-app-gw",
      "known_public_functions": ["webhookHandler"]
    }
  }
}
```

---

## 7. CI Pipeline Integration

### Basic: JSON output + fail on HIGH

```yaml
- name: Cloud Security Audit
  run: |
    python3 scripts/cloud_security_audit.py \
      --mode static --output json --severity high \
      > security-report.json
    # Exit code 1 = HIGH findings → fail pipeline
```

### Recommended: SARIF + GitHub Advanced Security (inline PR annotations)

```yaml
- name: Cloud Security Audit
  run: |
    python3 scripts/cloud_security_audit.py \
      --mode static --output sarif --changed ${{ github.event.pull_request.base.sha }} \
      > results.sarif
  continue-on-error: true

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif
```

### Live mode with credentials (hardened — orchestration-review P0)

```yaml
- name: Cloud Security Audit (Live)
  env:
    GCP_SA_KEY: ${{ secrets.GCP_SA_KEY }}
  run: |
    TMPFILE=$(mktemp -m 0600)
    trap 'rm -f "$TMPFILE"' EXIT
    echo "$GCP_SA_KEY" > "$TMPFILE"
    ai-toolkit credentials add gcp --file "$TMPFILE"
    python3 scripts/cloud_security_audit.py \
      --mode live --output sarif --changed "${{ github.event.pull_request.base.sha }}" \
      > results.sarif

- name: Validate & Upload SARIF
  if: always()
  run: python3 -c "import json; d=json.load(open('results.sarif')); assert d.get('version')=='2.1.0', 'Invalid SARIF'"
  continue-on-error: false

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif
```

**CI Security Notes (orchestration-review):**
- `mktemp -m 0600` creates file with owner-only permissions (not world-readable `/tmp/sa.json`)
- `trap 'rm -f' EXIT` ensures cleanup even on script failure
- SARIF schema validated before upload to prevent injected/corrupted annotations
- `${{ github.event.pull_request.base.sha }}` quoted to prevent shell injection via crafted refs
- Consider GitHub OIDC workload identity federation instead of long-lived SA keys for production

---

## 8. Success Criteria (Overall)

| Metric | Target |
|--------|--------|
| Providers supported | 3 (GCP, AWS, Azure) |
| Check patterns (total) | 40+ (GCP: 16, AWS: 15, Azure: 12) |
| False positive rules | 10+ |
| Output formats | 3 (text, JSON, SARIF v2.1.0) |
| CLI commands | 7 (add, list, remove, test, init per provider) |
| Scripts (stdlib Python) | 9 (auth + scanners + resolver + sarif + incremental) |
| Tests | 70+ |
| External dependencies | 0 (stdlib only, CLI tools: gcloud/aws/az/terraform) |
| CI exit codes | 0=clean, 1=HIGH findings, 2=credential error |
| Incremental scan | `--changed` flag works with git refs |
| GitHub integration | SARIF upload → inline PR annotations |

---

## 9. Fix Strategy

**Same approach as HIPAA scanner v1: No auto-fix. Agent interprets and suggests.**

The deterministic scripts produce findings. The `cloud-security-auditor` agent then:
1. **Reads** the flagged file/resource to understand actual context
2. **Suggests** a specific fix (not generic advice — concrete code/config change)
3. **Never** auto-applies changes — the user reviews and applies manually

Examples:
- Firestore rules finding → agent suggests the exact `allow read: if request.auth != null` rule change
- Public CF finding → agent suggests adding `validateFirebaseIdToken` middleware with code snippet
- Open S3 bucket → agent suggests the exact bucket policy JSON to add `BlockPublicAccess`
- Broad IAM role → agent suggests the minimal policy document with only required permissions

**Why no auto-fix in v1:**
- Cloud security fixes require project-specific knowledge (which SA, which bucket, which auth flow)
- Wrong auto-fix on IAM can lock out real users
- Firestore rules changes can break client apps
- The agent's context-aware suggestion is more valuable than a blind auto-fix

**v2 option:** `--fix-mode suggest` generates a `.cloud-security-fixes.patch` file that users can review and apply with `git apply`.

---

## 10. Risks and Mitigation (updated)

| Risk | Probability | Impact | Mitigation |
|------|-------------|--------|------------|
| CLI tools (gcloud/aws/az) not installed | Medium | Medium | Graceful fallback to static-only mode, clear error message |
| Cloud APIs change breaking audit commands | Low | Medium | Version-pin CLI output format parsing, test with CI |
| False positive rules too aggressive (suppress real issues) | Low | High | Default to WARN not SUPPRESS, require `.cloud-security-config` for suppression |
| Credential leakage in logs | Low | Critical | Never log credentials, 0600 perms, `/tmp` cleanup in CI |
| Scope creep (too many checks) | Medium | Medium | Start with top-10 per provider, expand based on feedback |
| YAML IaC not parseable (stdlib-only) | High | Medium | JSON-only for static IaC; live mode unaffected; v2: vendored YAML subset parser |
| `--changed` confused with live mode | Low | Low | Explicit warning: incremental applies to static only |

---

## 11. Pre-Mortem

1. **Firebase rules parser too simplistic** — Firestore rules use CEL-like syntax with nested `match` blocks. Parser needs proper recursive descent, not just regex. Mitigation: build minimal CEL parser or use line-by-line pattern matching with scope tracking.
2. **False positive resolver gives false confidence** — Users may trust SUPPRESSED status and miss real issues. Mitigation: always show context chain, require explicit `.cloud-security-config` for auto-suppression, default to WARN.
3. **AWS credential scope too broad** — User provides admin-level AWS profile. Mitigation: `credentials test` checks actual permissions, WARN if write access detected, suggest read-only IAM policy in docs.
4. **Three providers = 3x maintenance** — Each provider's CLI evolves independently. Mitigation: abstract provider interface, single test matrix, version tracking per provider.
5. **Terraform parsing incomplete** — HCL syntax is complex (modules, variables, conditionals). Mitigation: wrap `terraform show -json` instead of parsing HCL. Fallback to flat regex for projects without `terraform` CLI.
6. **SARIF adoption low** — Users may not know how to use SARIF with GitHub. Mitigation: provide copy-paste GitHub Actions workflow in docs and `--explain` for onboarding.

---

## 12. Council Review Summary (2026-04-10)

**Verdict:** CONDITIONAL FOR — implement with scope reduction.
**Confidence:** MEDIUM (weighted score: FOR 3.1 vs AGAINST 2.9)

**Key insights applied to this plan:**
- [x] Timeline revised from 3-4 → 5-6 weeks
- [x] ~~Azure deferred to Milestone 3~~ → **reinstated: full 3-provider delivery**
- [x] SARIF v2.1.0 output added — essential for GitHub Advanced Security integration
- [x] Incremental scan mode added (`--changed`) — how developers actually use security tools
- [x] `terraform show -json` wrapper instead of HCL parsing — realistic path
- [x] Single config file `.cloud-security.json` (merged ignore + context)
- [x] `credentials init` interactive wizard — reduce onboarding friction
- [x] `--explain <rule-id>` for on-demand remediation guidance
- [x] Static mode as default — zero-setup first experience

**Deferred to v2:**
- Kubernetes/container security (separate pack candidate)
- Secret scanning with entropy detection
- Compliance framework mapping (SOC2, PCI-DSS, NIST 800-53)
- Visual security dashboard in browser
- GitHub PR comment integration beyond SARIF
- Vendored YAML subset parser for CloudFormation YAML static scanning

**Council strongest agreement:** False positive resolver is the killer feature and primary differentiator vs Checkov/Trivy/Prowler. No existing tool combines deterministic scanning with context-aware resolution.

---

## 13. Orchestration Review Summary (2026-04-10)

**Agents:** tech-lead, security-architect, product-manager, code-reviewer (4 parallel)

**Verdict:** Plan structurally complete (14/14 elements). Three P0 security blockers identified and resolved.

**Applied changes:**

| # | Action | Source | Priority | Applied? |
|---|--------|--------|----------|----------|
| 1 | Programmatic Bash allowlist | security-architect | P0 | Yes — allowlist.sh + agent integration |
| 2 | CI hardening (mktemp/trap/SARIF validation) | security-architect | P0 | Yes — CI examples rewritten |
| 3 | Suppression governance (justification + diff detection) | security-architect | P0 | Yes — schema + SUPPRESSION_CHANGED finding |
| 4 | Recursive descent parser for Firestore | code-reviewer | P1 | Yes — replaced regex approach, +1d estimate |
| 5 | SARIF `driver.rules[]` for GitHub annotations | code-reviewer | P1 | Yes — schema + success criteria |
| 6 | Task 4.1→3.2 numbering fix | tech-lead | P1 | Yes — renumbered |
| 7 | `terraform plan` execution risk documented | security-architect | P1 | Yes — only `show -json` allowed |
| 8 | `credentials init` deferred to M2 | code-reviewer | P2 | Yes — saves 1.5d in M1 |
| 9 | False positive resolver budgeted +2d/provider | code-reviewer | P2 | Yes — estimate updated |
| 10 | `SUPPRESSION_CHANGED` finding type | security-architect | P2 | Yes — in governance section |

**Market positioning (product-manager):**
- Not competing with Checkov on check count (40 vs 3000)
- Competing on: zero-noise (false positive resolver), zero-setup (static-first), IDE-native (10 platforms), AI interpretation
- Target: developers in ai-toolkit ecosystem, not enterprise security teams
- Value as ecosystem feature, not standalone product

**Timeline revision (code-reviewer):**
- 1 person: 6-7 weeks realistic (was 5-6)
- 2 people: 4-5 weeks (parallel GCP + AWS tracks)
- All 3 providers ship in 6 weeks — no conditional gates

---

## 14. Next Actions

1. [ ] Approve plan
2. [ ] Implement `credentials` CLI command (1.1) + Bash allowlist
3. [ ] Create `cloud-security-auditor` agent (1.2)
4. [ ] Implement SARIF formatter + incremental scan (1.3)
5. [ ] Implement `firebase-rules-audit` — recursive descent parser (2.1)
6. [ ] Implement `cloud-functions-audit` + false positive resolver GCP (2.2, 2.3)
7. [ ] Implement `aws-security-audit` + `terraform show -json` wrapper (3.1)
8. [ ] Implement orchestrator + plugin pack + `credentials init` (3.2, 1.1b)
9. [ ] Implement `azure-security-audit` + false positive resolver Azure (4.1)
10. [ ] Full test suite (70+) + documentation + release

---

**Last Updated:** 2026-04-10
**Council Reviewed:** 2026-04-10
**Orchestration Reviewed:** 2026-04-10 (4 agents: tech-lead, security-architect, product-manager, code-reviewer)

---

## kb/procedures/ecosystem-sync-sop.md

---
title: "SOP: Ecosystem Sync"
category: procedures
service: ai-toolkit
tags: [sop, ecosystem, editors, generators, drift-detection, sync]
version: "1.1.0"
created: "2026-04-23"
last_updated: "2026-07-10"
description: "Quarterly (or event-triggered) sync procedure that detects documentation and capability drift in supported tools (Claude Code, Claude app, and 11 editors), analyses our generators and skills for missing features, and walks through the migration + generator-update workflow."
---

# SOP: Ecosystem Sync

Keeps ai-toolkit aligned with the tools it integrates with. When an editor adds a new hook lifecycle, makes a feature globally available, changes a config path, or deprecates a flag, this SOP surfaces it before it surprises users.

**When to run:**
- **Every quarter** as a baseline health check (calendar reminder)
- **Before every minor release** of ai-toolkit (Phase 0 of release prep)
- **Whenever an editor ships a major version** (subscribe to their changelogs)
- **On demand** if a user reports "feature X exists but toolkit doesn't support it"

**Time:** 30 minutes for drift review + variable for any generator updates

---

## Quick Reference

```bash
# Full check (all 13 tools, online)
python3 scripts/ecosystem_doctor.py --format text

# Single tool
python3 scripts/ecosystem_doctor.py --tool cursor --format text

# First-ever run — baseline the snapshot
python3 scripts/ecosystem_doctor.py --update > /dev/null

# CI / gating mode
python3 scripts/ecosystem_doctor.py --check

# Offline (no network) — validates our side only
python3 scripts/ecosystem_doctor.py --offline --format text
```

---

## Inputs

| File | Purpose |
|------|---------|
| `scripts/ecosystem_tools.json` | Authoritative registry: 13 tools with doc URLs, config paths, our generators, capability markers |
| `benchmarks/ecosystem-doctor-snapshot.json` | Last-seen state (headings, content hash, markers, version) — updated via `--update` |
| `scripts/ecosystem_doctor.py` | Drift detector |
| `kb/reference/supported-tools-registry.md` | Human-readable view of the registry |

---

## Phase 1: Run the Doctor

```bash
python3 scripts/ecosystem_doctor.py --format text > /tmp/eco-report.txt
cat /tmp/eco-report.txt
```

The report classifies every tool into:

- **Clean** — doc page, headings, and markers match the last snapshot; no action
- **Drift** — something changed upstream. Each drift entry has a `kind`:
  - `headings_added` — the doc grew new sections (new features? reorg?)
  - `headings_removed` — a section disappeared (deprecation? renaming?)
  - `marker_flips` — an expected capability marker appeared (`+`) or vanished (`-`)
  - `content_changed_no_heading_delta` — prose edits, reorder, minor rewrites, OR HTML churn (timestamps, ads, CSRF nonces). Reported but **not** treated as drift by `--check` — too noisy on dynamic pages.
  - `version_changed` — the CLI version bumped (for tools that expose `--version`)
- **Errored** — couldn't fetch docs (timeout, 404, auth wall). Doctor does not overwrite
  the snapshot for errored tools; the last-known-good state persists.

---

## Phase 2: Classify Each Drift

For every drifting tool, read its docs URL and classify the change into exactly one bucket:

| Drift class | What it means | Action owner |
|-------------|---------------|--------------|
| **A. Cosmetic reword** | Prose edited, same feature set | Update snapshot (`--update`), no code change |
| **B. New feature — we should integrate** | New hook event, new config key, new CLI flag, new rule surface | Update the relevant generator in `scripts/generate_<tool>_*.py`; extend `app/skills/*` or `app/agents/*` if the feature maps onto our skills; document in `kb/reference/supported-tools-registry.md` |
| **C. New feature — not our concern** | Enterprise SSO, billing, proprietary UI-only features | Note in registry `capability_markers` as "not adopted"; update snapshot |
| **D. Deprecation** | Flag or path removed / renamed | Open migration issue; coordinate with `ai-toolkit install` and generator output; add deprecation warning to CLAUDE.md rules if user-facing |
| **E. Feature promoted to default** | Was behind a flag, now global | Remove the flag from generator output; simplify our installer |
| **F. Global availability** | Was editor-only, now also available via CLI / hooks / settings.json | Map new config surface; may require a new generator or extending an existing one |

Write one line per drift in `/tmp/eco-report.txt` with its class. Example:

```
cursor: headings_added [AGENTS.md support] -> class B (integrate: extend generate_cursor_mdc.py)
aider:  version_changed 0.70 -> 0.72          -> class A (cosmetic, --update)
windsurf: marker_flips +Cascade               -> class B (already supported, verify snapshot)
```

---

## Phase 3: Execute Changes

### For class B (new feature — integrate)

1. Read the tool's docs section that introduced the feature. Note the exact config key / hook name / file path.
2. Open the relevant generator (`scripts/generate_<tool>_*.py`) and add output for the new surface.
3. If the feature is a **hook event**, also update:
   - `app/hooks.json` (if Claude-Code-native)
   - `app/skills/hook-creator/SKILL.md` — add the event to the Supported Hook Events table
   - `scripts/inject_hook_cli.py` — if the hook target path differs
4. If the feature is a **skill/agent schema extension**:
   - Update `app/skills/skill-creator/SKILL.md` and `app/skills/command-creator/SKILL.md` templates
   - Update `scripts/validate.py` field allowlists
   - Update `kb/reference/agent-skills-spec.md` (if the change is an upstream spec change)
5. Add a bats test under `tests/test_<tool>.bats` covering the new output.
6. Regenerate artifacts: `npm run generate:all`.

### For class D (deprecation)

1. Open a migration issue in GitHub with "class: deprecation" and a link to the upstream changelog.
2. In the generator, mark the deprecated output path as emitting a comment: `# DEPRECATED: <link>, removed in <version>`.
3. If deprecation affects `ai-toolkit install --local --editors <tool>`, add a doctor check that warns when a user's repo still contains the deprecated file.

### For class E / F (feature promotion)

1. Simplify the generator to emit the new-default form; keep a fallback comment for users on older tool versions.
2. Update `kb/reference/supported-tools-registry.md` config-paths column.

### For class A / C (no code change)

1. Run `python3 scripts/ecosystem_doctor.py --update --tool <id>` to refresh that tool's snapshot.

---

## Phase 4: Update the Registry

If new capability markers, config paths, or doc URLs emerged during Phase 3, edit `scripts/ecosystem_tools.json`:

```bash
${EDITOR:-nvim} scripts/ecosystem_tools.json
```

Fields to consider updating:
- `urls.docs` — if the vendor moved their docs
- `urls.release_notes` — if the changelog location changed
- `config_paths` — if new files now ship in our install output
- `our_generators` — if a new generator was added
- `capability_markers` — if a new feature was adopted
- `version_probe.command` — if the CLI binary was renamed

After editing, increment `last_updated` in the registry and save the snapshot:

```bash
python3 scripts/ecosystem_doctor.py --update
```

---

## Phase 5: Validate

```bash
python3 scripts/validate.py --strict
python3 scripts/audit_skills.py --ci
python3 scripts/ecosystem_doctor.py --check              # exits 0 after --update
npm test
```

All four must pass before committing generator / registry changes.

---

## Phase 6: Commit

Use a structured commit per change class:

```bash
git add scripts/ecosystem_tools.json benchmarks/ecosystem-doctor-snapshot.json
git add scripts/generate_<tool>_*.py                  # if class B/D/E/F
git add app/skills/<skill>/SKILL.md                   # if templates touched
git add kb/reference/supported-tools-registry.md
git commit -m "chore(ecosystem): sync <tool> — <brief summary>"
```

Recommended commit messages by class:

| Class | Template |
|-------|----------|
| A | `chore(ecosystem): refresh <tool> snapshot (cosmetic docs update)` |
| B | `feat(<tool>): add support for <feature>` |
| C | `chore(ecosystem): note <tool> <feature> as not-adopted` |
| D | `feat(<tool>): deprecation warning for <old-path>` |
| E | `refactor(<tool>): remove flag for <feature> (now default)` |
| F | `feat(<tool>): add <new-surface> generator` |

---

## Gotchas

- **First run has no baseline.** On a machine where `benchmarks/ecosystem-doctor-snapshot.json` does not exist, every tool shows as clean (no prior state to diff against). Run `--update` once to seed, then run again to see real drift.
- **Documentation sites use client-side rendering.** Aider, opencode, and Antigravity serve most content via JavaScript. `urllib` fetches the bare HTML skeleton — the doctor only sees a few headings. Combine the automated check with a manual visit to the docs on these tools.
- **Release notes pages change structure more often than docs.** Cursor and Windsurf refactor their changelog layouts periodically; a heading delta from a changelog page is often a presentation change, not a feature change. Classify as A when in doubt.
- **Version probes require the CLI to be installed locally.** `gemini --version`, `aider --version`, etc. are skipped silently when the binary isn't on `$PATH`. The snapshot therefore omits version drift for tools you haven't installed — that is intentional, not a bug.
- **GitHub release pages have anti-scraping.** `github.com/<org>/<repo>/releases` works via `urllib` but rate-limits aggressively. If the doctor errors on repeated runs, wait 10 minutes or manually review the release page.
- **Marker list is intentionally small.** Capability markers are a "did we adopt this?" checklist, not a feature coverage map. Adding every sub-feature bloats the JSON and produces noisy flips — keep markers at the top-level-capability tier.
- **`--check` only gates on structural drift.** Heading/marker/version changes and fetch errors exit `1`. Pure content-hash differences (`content_changed_no_heading_delta`) exit `0` — otherwise dynamic pages with timestamps or rotating ads would page you every run. If you want the strictest possible gate, grep for `Content changed` in the text report instead.

---

## Scheduling

Recommended cadence:

| Trigger | Action |
|---------|--------|
| Every Monday morning | `python3 scripts/ecosystem_doctor.py --format text` — scan during coffee |
| Before a minor release | Full sync + clean snapshot before tagging |
| After any drift report | Act within 1 week or record explicit "ignore, low priority" in the commit message |
| New tool added to the registry | Baseline with `--update --tool <id>` |
| Tool removed from support | Delete its entry from the registry AND from the snapshot JSON |

An optional GitHub Action can run `--check` weekly and open an issue on drift. Template:

```yaml
# .github/workflows/ecosystem-doctor.yml  (proposed, not yet committed)
on:
  schedule:
    - cron: '0 9 * * 1'        # Mondays 09:00 UTC
  workflow_dispatch: {}
jobs:
  doctor:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - run: python3 scripts/ecosystem_doctor.py --format text | tee /tmp/doctor.txt
      - run: python3 scripts/ecosystem_doctor.py --check
```

---

## When NOT to Use

- For **runtime** user support (user hit a bug with an editor) — use `/debug` or `/triage-issue`
- For **picking** an editor to add — that is a product decision, not a sync; use `/architecture-decision`
- For **one-off** testing of a specific tool's install flow — use the release-verification SOP
- For **scaling up** the supported-tools list — add the new tool to the registry, then run the SOP to baseline it

---

## Related Documentation

- [Supported Tools Registry](../reference/supported-tools-registry.md) — human-readable per-tool breakdown
- [MCP Editor Compatibility](../reference/mcp-editor-compatibility.md) — MCP-specific adapter table
- [Maintenance SOP](maintenance-sop.md) — general toolkit upkeep
- [Release Preparation SOP](release-preparation-sop.md) — run the doctor before tagging

---

## kb/procedures/maintenance-sop.md

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

---

## kb/procedures/post-release-testing-sop.md

---
title: "SOP: Post-Release Testing"
category: procedures
service: ai-toolkit
tags: [sop, post-release, smoke-test, npm, sandbox, plugin-pack, provenance, isolation]
version: "1.0.0"
created: "2026-07-26"
last_updated: "2026-07-26"
description: "Smoke-test a published @softspark/ai-toolkit release from npm in an isolated HOME and npm prefix, without touching the maintainer's real install. Covers provenance, CLI, doctor, and the full plugin-pack lifecycle including the degraded-install path. Written for v4.18.0 and not run; v4.18.0 shipped a pack that broke every command it touched, and every step here would have caught it."
---

# SOP: Post-Release Testing

Runs **after** `publish.yml` succeeds on a tag. Verifies the artifact users will
actually install, from npm, rather than the working tree.

Sibling procedures exist for `jira-mcp` and `legal-pl-pack`; this is the
ai-toolkit equivalent. It complements
[Release Verification](release-verification-sop.md), which checks the toolkit
from the maintainer's own installed copy. The difference that matters: this one
never writes to the maintainer's `~/.claude` or `~/.softspark`.

**Time:** 10 minutes.

## Why isolation is the first step, not a detail

The toolkit installs into `$HOME`. Testing a release against your own HOME
means the test either pollutes your working setup or, worse, passes because of
state your setup already had. Both make the result meaningless.

Every command below runs against a throwaway HOME and a throwaway npm prefix.
Nothing is global.

## Phase 1: Sandbox

```bash
SB=$(mktemp -d)
mkdir -p "$SB/home" "$SB/npm"
export HOME="$SB/home"
AT="$SB/npm/bin/ai-toolkit"
echo "sandbox: $SB"
```

Record the real state now, so Phase 7 can prove it is unchanged:

```bash
python3 -c "
import json, pathlib
p = pathlib.Path('$SB/../real-before.json')
import os
home = pathlib.Path(os.path.expanduser('~'))
" 2>/dev/null
# Simpler: note what exists today.
cat ~/.softspark/ai-toolkit/plugins.json 2>/dev/null
```

## Phase 2: Provenance

Do this before installing anything: an unsigned publish is a release-blocking
regression, and there is no point smoke-testing a build you would have to redo.

```bash
VERSION="X.Y.Z"
npm view "@softspark/ai-toolkit@${VERSION}" --json \
  | python3 -c "
import json, sys
d = json.load(sys.stdin); att = d['dist'].get('attestations', {})
pt = att.get('provenance', {}).get('predicateType')
assert pt == 'https://slsa.dev/provenance/v1', f'NO PROVENANCE: {pt}'
print('PROVENANCE OK:', att['url'])
"
```

## Phase 3: Install from npm

```bash
npm install -g --prefix "$SB/npm" "@softspark/ai-toolkit@${VERSION}"
"$AT" --version    # must equal VERSION
"$AT" --help >/dev/null && echo "help OK"
```

## Phase 4: Core surfaces

```bash
"$AT" install            # full global install into the sandbox HOME
"$AT" doctor             # must end: Errors: 0 | Warnings: 0
"$AT" status
"$AT" plugin list        # pack count must match app/plugins/
```

**A doctor run before `install` reports `agents directory missing` and
`skills directory missing`.** That is the sandbox being empty, not a defect.
Install first, then judge doctor.

## Phase 5: Plugin-pack lifecycle

Run this for any pack the release touched. For a pack that downloads a binary,
every step below has caught a real defect at least once.

```bash
"$AT" plugin install <pack>
"$AT" plugin status                       # does it report itself working?
find "$HOME/.softspark/ai-toolkit" -path '*<pack>*'   # what actually landed
```

**Verify:**
- [ ] `plugin status` distinguishes *installed* from *working*, not just present
- [ ] For a binary pack: the binary runs and reports the pinned upstream version
- [ ] The hook is registered in `~/.claude/settings.json` with the pack's `_source`

**Does it do its job?** Presence is not function. Drive the hook directly:

```bash
printf '%s' '{"tool_name":"Bash","tool_input":{"command":"git status"}}' \
  | bash "$HOME/.softspark/ai-toolkit/hooks/plugin-<pack>-<hook>.sh"
```

**Update path:**

```bash
"$AT" plugin update --editor claude --all            # current version: silent
"$AT" plugin update --editor claude --all --dry-run  # says "up to date"
# force a stale marker, then confirm it updates and re-records:
python3 -c "
import json, pathlib, os
p = pathlib.Path(os.environ['HOME'] + '/.softspark/ai-toolkit/plugins.json')
d = json.loads(p.read_text()); d['targets']['claude']['versions']['<pack>'] = '0.0.9'
p.write_text(json.dumps(d, indent=2))
"
"$AT" plugin update --editor claude --all            # reports 0.0.9 -> <version>
"$AT" update                                          # core update leaves a current pack alone
```

**Removal must be complete:**

```bash
"$AT" plugin remove <pack>
find "$HOME/.softspark" -path '*<pack>*' | wc -l      # must be 0
python3 -c "
import json, pathlib, os
d = json.loads(pathlib.Path(os.environ['HOME'] + '/.claude/settings.json').read_text())
print('hook still present:', '<pack>' in json.dumps(d.get('hooks', {})))
"
"$AT" plugin install <pack>                           # re-install must work
```

## Phase 6: The degraded path

**This is the step most worth keeping.** A pack that fetches anything can fail
to fetch, and the failure mode must be inert rather than broken or silent.

No pack in the toolkit fetches anything today. Run this phase if one ever does
again, pointing its source-override variable at a dead URL:

```bash
"$AT" plugin remove <pack>
<PACK>_RELEASE_BASE_URL="file:///nonexistent" "$AT" plugin install <pack>
```

**Verify:**
- [ ] Install reports the failure in words a user can act on, and does not claim success
- [ ] No partial artifact is left behind
- [ ] The hook is still wired, and passes commands through untouched
- [ ] `plugin status` says the pack is inert and names the fix
- [ ] Re-installing without the broken source recovers

## Phase 7: Prove the real environment is untouched

```bash
python3 -c "
import json, pathlib
d = json.loads(pathlib.Path.home().joinpath('.softspark/ai-toolkit/plugins.json').read_text())
print('plugins.json:', d['targets']['claude'])
p = pathlib.Path.home() / '.claude/settings.json'
print('pack hook leaked into real settings:', '<pack>' in json.dumps(json.loads(p.read_text()).get('hooks', {})) if p.exists() else False)
print('pack paths in real ~/.softspark:', len(list(pathlib.Path.home().joinpath('.softspark').rglob('*<pack>*'))))
"
```

All three must show the pre-test state.

## Phase 8: Clean up

`guard-destructive.sh` blocks `rm -rf` on a `PreToolUse` hook, so removal goes
through an enumerated delete that reports what it removed:

```bash
python3 -c "
import pathlib, shutil
sb = pathlib.Path('$SB')
assert sb.is_dir() and str(sb).startswith(('/tmp', '/var/folders')), sb
n = sum(1 for _ in sb.rglob('*') if _.is_file())
shutil.rmtree(sb)
print(f'removed {sb} ({n} files)')
"
```

## Success criteria

| Area | Criterion |
|---|---|
| Supply chain | `predicateType == https://slsa.dev/provenance/v1` |
| CLI | `--version` equals the tag, `--help` renders |
| Health | `doctor` after `install`: 0 errors, 0 warnings |
| Catalog | `plugin list` count matches `app/plugins/` |
| Pack install | Binary present, runs, digest verified, hook registered |
| Pack function | Driving the hook produces the expected effect, not just exit 0 |
| Pack update | Current version silent; stale version updates and re-records |
| Pack removal | Zero residue in `~/.softspark` and `settings.json`; re-install works |
| Degraded path | Fetch failure is inert, loud in status, and recoverable |
| Isolation | Real `~/.claude` and `~/.softspark` byte-identical to pre-test |

## Related

- [Release Preparation](release-preparation-sop.md) — run before tagging
- [Release Verification](release-verification-sop.md) — the maintainer-install checks
- [rtk-pack Retirement](../history/completed/rtk-pack-retirement-20260727.md) — what happened the one time this SOP was written and not run

---

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

---
title: "SOP: Release Preparation"
category: procedures
service: ai-toolkit
tags: [sop, release, version, publish, changelog, semver, provenance, sarif, ecosystem, shellcheck]
version: "1.13.0"
created: "2026-04-10"
last_updated: "2026-07-27"
description: "Step-by-step checklist for preparing a new ai-toolkit release — ecosystem-sync drift check, version sync, changelog, artifact regeneration, validation, and tagging. Run BEFORE every git tag. Includes mandatory Provenance, SARIF, and checksum-pin checks added in v2.8.0, the single-run npm test discipline added in v1.8.0, the ecosystem-sync gate added in v1.9.0, the registry-vs-generators drift gate added in v1.10.0, the mandatory pre-tag ShellCheck gate added in v1.11.0 (publish.yml does not run ShellCheck, so a hook lint failure can publish while reddening main CI — see the v4.5.1 postmortem in Phase 5), the pre-push tag assertions added in v1.12.0 after v4.19.0 was tagged on the wrong commit (Phase 7), and the licensing gate added in v1.13.0 with the move to Apache-2.0 (Phase 5c)."
---

# 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:**
```
Ecosystem Sync SOP (drift check + generator updates)
      ↓
Release Preparation (this SOP)
      ↓
git tag → CI publish → Release Verification SOP
```

**Time:** 10-20 minutes (includes ecosystem sync review)

---

## Quick Checklist (TL;DR)

```bash
# 0. Ecosystem sync (mandatory for minor/major releases; optional for patch)
#    Full procedure: kb/procedures/ecosystem-sync-sop.md
python3 scripts/ecosystem_doctor.py --format text > /tmp/eco-report.txt
cat /tmp/eco-report.txt
# If drift detected: stop here, follow ecosystem-sync-sop.md Phase 2-4 to
# classify each drift (A-F), update generators as needed, refresh snapshot,
# THEN resume this SOP.
python3 scripts/ecosystem_doctor.py --update    # after all drift resolved

# 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, any ecosystem-class-B/F change
#    major (1.4.2 → 2.0.0): breaking change, any ecosystem-class-D removed path

# 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 + SARIF + shellcheck + test + ecosystem check
python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && python3 scripts/audit_skills.py --sarif > /tmp/audit.sarif && shellcheck --severity=warning app/hooks/*.sh && npm test

# 5a. Supply-chain standard (v2.8.0+) — non-negotiable
grep -q -- '--provenance' .github/workflows/publish.yml || { echo "MISSING --provenance"; exit 1; }
grep -q 'id-token: write'   .github/workflows/publish.yml || { echo "MISSING id-token: write"; exit 1; }
python3 scripts/audit_skills.py --permissions   # review Bash/Write/Edit footprint

# 5b. Ecosystem gate — snapshot must be current before tag
python3 scripts/ecosystem_doctor.py --offline --check || { echo "STALE ecosystem snapshot — re-run doctor"; exit 1; }

# 5c. Licensing gate — SPDX headers, LICENSE, NOTICE, manifest consistency
npx bats tests/test_licensing.bats || { echo "LICENSING GATE FAILED"; exit 1; }

# 6. Commit + tag + push
git add -A && git commit -m "chore: release vX.Y.Z"
git tag vX.Y.Z

# 6a. Assert the tag before pushing it (v4.19.0 postmortem, Phase 7)
test "$(git rev-parse vX.Y.Z)" = "$(git rev-parse HEAD)" || { echo "FAIL: tag not on HEAD"; exit 1; }
git show --no-patch --format=%s vX.Y.Z | grep -qx "chore: release vX.Y.Z" || { echo "FAIL: tag not on release commit"; exit 1; }

# 6b. Branch first, then the single tag by full ref. Never --tags.
git push origin main
git push origin refs/tags/vX.Y.Z
```

---

## Phase 0: Ecosystem Sync (MANDATORY for minor/major)

Before touching version numbers, confirm the toolkit is aligned with the current state of every editor / platform it integrates with. Skipping this phase ships a release whose generators may lag a month-old CLI refactor, a rename of `.cursorrules` to `.cursor/rules/`, or a new hook event we do not yet emit.

**When this phase is mandatory:**
- Minor release (X.Y.0) — always
- Major release (X.0.0) — always
- Patch release (X.Y.Z) — only if the patch touches a generator or install flow

**When to skip:** pure doc-only patches, SOP edits, internal refactors that do not touch `scripts/generate_*` or `app/skills/*/SKILL.md`.

### 0.1 Run the doctor

```bash
python3 scripts/ecosystem_doctor.py --format text | tee /tmp/eco-report.txt
```

Output classifies every registered tool as **Clean**, **Drift**, or **Errored**.

### 0.2 Act on drift

For each drifting tool, follow [ecosystem-sync-sop.md](ecosystem-sync-sop.md) Phase 2-4:

| Drift class | Release impact |
|-------------|----------------|
| A (cosmetic reword) | No version impact — refresh snapshot, continue |
| B (new feature — integrate) | **Minor** version bump at minimum; new generator or extended generator |
| C (new feature — not adopted) | No impact — note in registry |
| D (deprecation) | **Minor** or **major** depending on user impact; add migration warning |
| E (feature promoted to default) | **Minor**; simplify generator, keep fallback comment |
| F (feature newly globally available) | **Minor**; may require new generator or new config path |

If any B/D/E/F changes land in this preparation pass, mention them explicitly in the CHANGELOG entry (Phase 3) under a `Ecosystem` subsection.

### 0.3 Refresh snapshot

Once every drift is resolved (either by code change or by re-classifying as acceptable):

```bash
python3 scripts/ecosystem_doctor.py --update
```

This writes the new baseline to `benchmarks/ecosystem-doctor-snapshot.json`. Commit it as part of the release commit.

### 0.4 Gate

```bash
python3 scripts/ecosystem_doctor.py --offline --check
```

Must exit `0`. If it exits `1`, the snapshot is stale — rerun Phase 0.3 or review the remaining drift.

---

## 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` catches count drift AND version mismatches
> (package.json vs manifest.json vs plugin.json) automatically.
> If validation passes, counts and versions 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

### Update README "What's New" section

**MANDATORY on every release.** Update the `## What's New in vX.Y.Z` section in `README.md`:

1. Change the heading version: `## What's New in vX.Y.Z`
2. Replace bullet points with 3-5 highlights from this release
3. **Keep only the latest version block.** Delete the previous `## What's New in vA.B.C` section(s). README is the shop window, not the archive — users see the current release, full history lives in `CHANGELOG.md`.
4. Keep the `See [CHANGELOG.md](CHANGELOG.md) for full history.` link directly below the bullet list.

> **Warning:** This section is the first thing users see after the badges.
> A stale version here (e.g., "What's New in v2.1.3" when shipping v2.3.0)
> signals an unmaintained project. Do NOT skip this step.

> **Single-version rule:** README.md must contain **exactly one** `## What's New in vX.Y.Z` heading at any time. If you find multiple stacked (e.g. v2.6.1 + v2.6.0 + v2.5.0), that is a SOP drift — collapse to the latest on the next release commit.

---

## Phase 4: Regenerate Artifacts

Use the npm scripts, not the generators directly:

```bash
npm run generate:agents   # AI_TOOLKIT_NO_CUSTOM_RULES=1 python3 scripts/generate_agents_md.py > AGENTS.md
npm run generate:llms     # llms.txt + llms-full.txt
```

`generate:agents` sets `AI_TOOLKIT_NO_CUSTOM_RULES=1`. Running
`generate_agents_md.py` bare picks up whatever is registered in the maintainer's
own `~/.softspark/ai-toolkit/rules/`, which then ships inside `AGENTS.md`.

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
python3 scripts/audit_skills.py --sarif > audit.sarif       # MANDATORY — GHAS ingest
python3 scripts/audit_skills.py --permissions               # review Bash/Write/Edit footprint

# ShellCheck on hooks (added in 1.11.0). Mirrors the ci.yml "ShellCheck hooks"
# job. NOT run by validate.py, npm test, OR publish.yml — so a hook with a
# ShellCheck warning passes every other gate AND still publishes on tag while
# turning main CI red. Run it here, before tagging.
shellcheck --severity=warning app/hooks/*.sh && echo "OK: shellcheck clean"

# Registry / generator drift (added in 1.10.0). Meta-generators excluded.
META="generate_agents_md.py|generate_llms_txt.py|generate_language_rules_skills.py"
diff \
  <(grep -oE 'scripts/generate_[a-z_]+\.py' kb/reference/supported-tools-registry.md | sort -u) \
  <(ls scripts/generate_*.py | grep -vE "$META" | sort -u) \
  && echo "OK: registry matches filesystem" \
  || { echo "DRIFT: update supported-tools-registry.md before tagging"; exit 1; }

# Stage first IF this release adds or deletes a kb/ file. The test
# "npm package KB files match the tracked release set" compares `git ls-files
# kb` (the index) against what `npm pack` sees (the working tree), so an
# unstaged addition reads as "extra" and an unstaged deletion as "missing".
# Phase 6 stages, and it runs after this one, so the ordering fails the test
# for any release that touches the KB. Staging early costs nothing.
git status --porcelain kb/ | grep -qE '^(\?\?| D|\?M)' && git add -A kb/

# Run npm test ONCE, cache output, parse from file. The suite is 1400+ bats
# cases — rerunning it per check wastes minutes. Do not pipe npm test into
# tail/grep multiple times in the same session.
npm test > /tmp/npm-test.log 2>&1
tail -3 /tmp/npm-test.log
echo "ok: $(grep -c '^ok ' /tmp/npm-test.log) | not ok: $(grep -c '^not ok' /tmp/npm-test.log)"
```

**Expected results:**
- `validate.py`: `Errors: 0 | Warnings: 0 | VALIDATION PASSED`
- `audit_skills.py --ci`: `HIGH: 0 | WARN: 0` (INFO is acceptable)
- `audit_skills.py --sarif`: valid JSON, non-empty `runs[0].tool.driver.rules`
- `audit_skills.py --permissions`: review `Skills with Bash + Write + Edit` list — any newly-added skill with broad access MUST be justified in the CHANGELOG entry
- `shellcheck --severity=warning app/hooks/*.sh`: no output, exit 0. A common false positive is `SC2034` on `INPUT` or env vars (e.g. `AI_TOOLKIT_HOOK_FORMAT`) that a *sourced* helper (`_hook-io.sh`) consumes — ShellCheck cannot see cross-file use. Fix with a `# shellcheck disable=SC2034` directive or `export`, matching `guard-destructive.sh`. Never tag with a red ShellCheck.
- Registry drift: `OK: registry matches filesystem`. If `DRIFT:` appears, add the missing `scripts/generate_*.py` rows to `kb/reference/supported-tools-registry.md` before tagging.
- `npm test`: `1..N` with zero `not ok` (read from the cached `/tmp/npm-test.log`, do not rerun)

> **Why this matters (v4.5.1 postmortem):** `publish.yml` runs only `validate.py` + `npm test`, so it published v4.5.0 even though the `main` CI `ShellCheck hooks` job was red on two `SC2034` warnings in a new hook. The publish workflow does **not** depend on the CI workflow. Until that is fixed, ShellCheck is a manual pre-tag gate — run it here every time.

**One-liner:**
```bash
python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && python3 scripts/audit_skills.py --sarif > audit.sarif && shellcheck --severity=warning app/hooks/*.sh && diff <(grep -oE 'scripts/generate_[a-z_]+\.py' kb/reference/supported-tools-registry.md | sort -u) <(ls scripts/generate_*.py | grep -vE 'generate_agents_md\.py|generate_llms_txt\.py|generate_language_rules_skills\.py' | sort -u) && 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 5c: Licensing Gate (v4.20.0+)

The project is Apache-2.0. Attribution only works if the artefact actually
carries it, and every part of that is mechanically checkable.

```bash
# The whole gate, enforced in CI. Run it here so a failure is caught before tagging.
npx bats tests/test_licensing.bats
```

The seven assertions, and why each exists:

| Check | Fails when |
|---|---|
| Every shipped source file carries an SPDX header | A new `.py`/`.sh`/`.js`/`.bats` file was added without one — the common case, and the reason this is a test rather than a habit |
| Headers name Apache-2.0 and nothing else | A file was copied in from an MIT/GPL source with its own header intact |
| **No** markdown file carries an SPDX header | Someone "helpfully" ran the header script over `app/skills/` — headers there sit above parsed frontmatter and bill every session for it |
| `LICENSE` is the complete Apache 2.0 text | The file was truncated or replaced with a summary |
| `NOTICE` carries attribution, the source URL, §4(d) and the MIT-era notice | The attribution mechanism was gutted |
| `LICENSE` **and** `NOTICE` ship in the npm package | `package.json` `files` lost an entry — a NOTICE that never reaches the consumer cannot satisfy §4(d) |
| Every manifest declaring a licence declares Apache-2.0 | `package.json`, `manifest.json`, `plugin.json` and `package-lock.json` drifted apart |

**Adding source files in this release?** The header goes *after* the shebang,
never before it. Short SPDX form:

```
# SPDX-License-Identifier: Apache-2.0
# Copyright 2024-2026 Lukasz Krzemien (biuro@softspark.eu)
# Source: https://github.com/softspark/ai-toolkit
```

`//` for JavaScript. Full convention and the reasoning behind the markdown
exclusion: [Licensing](../reference/licensing.md).

**Changing the licence itself?** Do not hand-type the licence text. Take it
verbatim from a published copy and cross-verify against a second independent
copy before writing `LICENSE` — a rendered or summarised licence is not the
licence. Prior releases stay under their original terms; a licence change
applies going forward and revokes nothing already granted.

### Phase 5a: Supply-Chain Hardening Verification (v2.8.0+)

These checks enforce the security standard introduced in v2.8.0. Do NOT tag a release until all pass.

**1. Publish workflow emits provenance:**

```bash
grep -E '\-\-provenance|id-token: write' .github/workflows/publish.yml
```

- [ ] Both markers present (`--provenance` flag + `id-token: write` permission)
- [ ] Any PR that changes `publish.yml` REQUIRES an approved security review

**2. URL-sourced rules and hooks are checksum-pinned:**

```bash
# On a machine that has consumed URL rules/hooks at least once
# (schema_version 1: entries live under the .rules / .hooks key):
jq '.rules | to_entries | map(select(.value.url != null and (.value.sha256 // "" | length) == 0))' ~/.softspark/ai-toolkit/rules/sources.json
jq '.hooks | to_entries | map(select(.value.url != null and (.value.sha256 // "" | length) == 0))' ~/.softspark/ai-toolkit/hooks/external/sources.json
```

- [ ] Both queries return empty arrays (every URL entry has a `sha256`)
- [ ] If not, run `ai-toolkit update` to backfill missing hashes before tagging

**3. Audit SARIF output is well-formed:**

```bash
python3 scripts/audit_skills.py --sarif | python3 -c "import json, sys; d=json.load(sys.stdin); assert d['version']=='2.1.0' and d['runs'][0]['tool']['driver']['name']; print('SARIF OK')"
```

- [ ] Prints `SARIF OK`
- [ ] If the script ever grows new rule classes, extend the SARIF `rules[]` coverage before releasing

**4. Strict-pin mode passes on CI** (optional, recommended for stable branches):

```bash
AI_TOOLKIT_STRICT_PIN=1 ai-toolkit update --dry-run
```

- [ ] Exit 0, no `CHECKSUM CHANGED` line
- [ ] Any unexpected upstream change blocks the release until explicitly approved

---

## 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 llms.txt llms-full.txt
# NOTE: AGENTS.md, GEMINI.md, and .github/copilot-instructions.md are generated
# editor configs and are gitignored — do NOT commit them. `prepublishOnly` runs
# `npm run generate:all`, so the shipped package (which lists AGENTS.md in
# package.json `files`) gets a fresh copy at publish time.
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

# Assert the tag before pushing it. Both checks are one line each and both
# have caught a real broken release.
test "$(git rev-parse vX.Y.Z)" = "$(git rev-parse HEAD)" \
  || { echo "FAIL: tag is not on HEAD"; exit 1; }
git show --no-patch --format=%s vX.Y.Z | grep -qx "chore: release vX.Y.Z" \
  || { echo "FAIL: tag is not on the chore: release commit"; exit 1; }

# Push the branch, then the single release tag by its full ref.
git push origin main
git push origin refs/tags/vX.Y.Z
```

**Why the assertions (v4.19.0 postmortem).** v4.19.0 was tagged on a commit
that contained only a KB document and still carried `package.json` version
`4.18.0`; the actual release sat in the commit above it under a recycled
`fix:` message. `publish.yml` fired, tried to publish a version already on
npm, and failed. Nothing on npm, a tag pointing at the wrong tree, and the
only way out was rewriting a pushed commit. Both assertions above catch this
in under a second. Run them.

**Never `git push --tags`.** It pushes every local tag at once, and GitHub
suppresses tag-triggered workflow runs when many tags arrive in a single push
— the workflow silently does not fire and nothing publishes. Push the single
release tag by its full ref, as above. (Sibling evidence: this is exactly how
rag-mcp's `1.0.3` image build was skipped, when a `--tags` push carried 37
tags at once.)

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` with `--provenance` (SLSA v1 build attestation)

**Provenance is non-negotiable.** If `id-token: write` permission or the `--provenance` flag is missing from `publish.yml`, fix it BEFORE tagging — an unsigned release is a regression against the v2.8.0 standard.

**After CI completes:** Run the [Release Verification SOP](release-verification-sop.md)
to smoke-test the published package AND verify the provenance attestation landed on npm.

---

## 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 |
|---|------|-----------------|---------------|
| 0a | Ecosystem drift check | `ecosystem_doctor.py --format text` | All tools Clean, or drift classified and resolved |
| 0b | Ecosystem snapshot refresh | `ecosystem_doctor.py --update` | `benchmarks/ecosystem-doctor-snapshot.json` updated |
| 0c | Ecosystem gate | `ecosystem_doctor.py --offline --check` | Exit 0 |
| 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 (incl. `Ecosystem` subsection if any B/D/E/F drift) | 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 (CI mode) | `audit_skills.py --ci` | 0 HIGH |
| 11 | Security audit (SARIF) | `audit_skills.py --sarif` | Valid SARIF 2.1.0 JSON |
| 12 | Per-skill permissions | `audit_skills.py --permissions` | New broad-access skills justified in CHANGELOG |
| 13 | ShellCheck hooks | `shellcheck --severity=warning app/hooks/*.sh` | Exit 0, no output (mirrors ci.yml; publish.yml does NOT run it) |
| 14 | Provenance flag check | `grep -- '--provenance' .github/workflows/publish.yml` | Present |
| 15 | Checksum-pin backfill | `sources.json` entries all have `sha256` | No unpinned URL sources |
| 15a | Licensing gate | `npx bats tests/test_licensing.bats` | 7/7 — SPDX headers, LICENSE, NOTICE, npm `files`, manifest consistency |
| 16 | Tests | `git add -A kb/` if the KB changed, then `npm test` | All pass |
| 17 | Commit | `git commit` | Clean working tree |
| 18 | Tag | `git tag vX.Y.Z` | Tag exists |
| 18a | Tag is on HEAD | `test "$(git rev-parse vX.Y.Z)" = "$(git rev-parse HEAD)"` | Exit 0 |
| 18b | Tag is on the release commit | `git show --no-patch --format=%s vX.Y.Z` | Reads `chore: release vX.Y.Z` |
| 19 | Push branch, then the single tag | `git push origin main && git push origin refs/tags/vX.Y.Z` | CI triggered with `id-token: write`. Never `--tags`. |

---

## kb/procedures/release-verification-sop.md

---
title: "SOP: Release Verification"
category: procedures
service: ai-toolkit
tags: [sop, verification, release, smoke-test, install, update, qa, provenance, sarif]
version: "1.7.0"
created: "2026-04-08"
last_updated: "2026-07-14"
description: "End-to-end smoke test after installing or updating @softspark/ai-toolkit. Verifies CLI, native Codex and GitHub Copilot surfaces, Claude app export, doctor, validation, tests, eject, provenance, SARIF, and per-skill permissions."
---

# SOP: Release Verification

End-to-end smoke test after installing or updating `@softspark/ai-toolkit`.
Verifies all critical paths from the user's perspective.

**Use this SOP when:**
- After `npm install -g @softspark/ai-toolkit@latest`
- After `ai-toolkit update`
- Before tagging a new version (`git tag`)
- Before publishing to npm (`npm publish`)
- As a smoke test in CI/CD

**Prerequisites:**
- Node.js >= 18, Python 3, `bats`, git
- `@softspark/ai-toolkit` installed globally

**Time:** 10-15 minutes (full), 2 minutes (quick checklist)

---

## Quick Checklist (TL;DR)

14 commands — if all pass, the release is ready:

```bash
# Pre-commit (Phase 0)
python3 scripts/generate_agents_md.py > AGENTS.md           # 1. Regenerate AGENTS.md
python3 scripts/generate_llms_txt.py > llms.txt             # 2. Regenerate llms.txt
python3 scripts/validate.py --strict                        # 3. Validation passed?
npm test > /tmp/npm-test.log 2>&1 && grep -c '^ok ' /tmp/npm-test.log && ! grep -q '^not ok' /tmp/npm-test.log  # 4. All tests passed? (single run, cached)

# Post-install verification (Phases 1-7)
ai-toolkit --version                                        # 5. Version OK?
ai-toolkit status                                           # 6. Status OK?
ai-toolkit doctor                                           # 7. Health check passed?
ai-toolkit install --dry-run                                # 8. Global install OK?
python3 scripts/audit_skills.py --ci                        # 9. Security audit clean?

# Supply-chain verification (Phase 8, v2.8.0+)
python3 scripts/audit_skills.py --sarif | python3 -c "import json,sys; assert json.load(sys.stdin)['version']=='2.1.0'; print('SARIF OK')"   # 10. SARIF 2.1.0 well-formed?
python3 scripts/audit_skills.py --permissions | head -30    # 11. Broad-access skills reviewed?
npm view @softspark/ai-toolkit@X.Y.Z --json | python3 -c "import json,sys; d=json.load(sys.stdin); assert d['dist']['attestations']['provenance']['predicateType']=='https://slsa.dev/provenance/v1'; print('PROVENANCE OK')"   # 12. Provenance attested on npm?
python3 scripts/claude_app.py verify                         # 13. Claude Chat/Cowork plugin contract valid?

# Deep-coverage verification (Phase 9, v3.0.0+)
META="generate_agents_md.py|generate_llms_txt.py|generate_language_rules_skills.py"
diff <(grep -oE 'scripts/generate_[a-z_]+\.py' kb/reference/supported-tools-registry.md | sort -u) <(ls scripts/generate_*.py | grep -vE "$META" | sort -u) && echo "OK: registry matches"   # 14. Registry <-> generators drift?
```

---

## Phase 0: Pre-Commit & Pre-Push (2 min)

Run these commands **before every commit and push to main**. CI validates
counts but does NOT auto-regenerate — you must do it locally.

```bash
# 1. Regenerate generated 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

# 2. Validate everything (catches stale counts, missing assets)
python3 scripts/validate.py --strict

# 3. Security audit
python3 scripts/audit_skills.py --ci

# 4. Run tests
npm test

# 5. Stage and commit
# AGENTS.md, GEMINI.md, and .github/copilot-instructions.md are generated and
# gitignored — do NOT commit them (regenerated at prepublishOnly). Only the
# doc artifacts llms.txt / llms-full.txt are committed.
git add llms.txt llms-full.txt
git add -p  # stage your other changes
git commit -m "feat: your change description"
```

**Why local?** Branch protection on `main` requires PRs and status checks.
CI cannot push directly to `main`, so generated artifacts must be committed
by the developer as part of their PR.

**One-liner (copy-paste):**
```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 && python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && npm test
```

---

## Phase 1: CLI & Version (1 min)

```bash
ai-toolkit --version
ai-toolkit --help
which ai-toolkit
```

**Verify:**
- [ ] `--version` returns correct semver (e.g., `1.4.0`)
- [ ] `--help` displays full command list without errors
- [ ] `which` points to global npm bin path

---

## Phase 2: Global Install & Status (2 min)

```bash
ai-toolkit install --dry-run
ai-toolkit status
```

**Verify `--dry-run`:**
- [ ] Agents: 44
- [ ] Skills: 108
- [ ] Hooks merged into settings.json
- [ ] "Other AI Tools" lists documented global targets (with `--editors`): aider, antigravity, augment, cline, codex, copilot, cursor, gemini, opencode, roo, windsurf. Scope varies: Codex uses `$CODEX_HOME` (default `~/.codex`) plus `$HOME/.agents/skills`; Copilot uses `$COPILOT_HOME` (default `~/.copilot`); cursor has only `~/.cursor/hooks.json`; antigravity has the `~/.gemini/*/skills` pointer. Cursor and Antigravity rules remain project-only.

**Verify `status`:**
- [ ] Version matches expected
- [ ] Profile: minimal/standard/strict
- [ ] Modules: list of installed modules
- [ ] Latest: up to date / update available

---

## Phase 3: Doctor Health Check (1 min)

```bash
ai-toolkit doctor
```

**Expected sections (all OK):**
- Environment: node, bash, python3, bats
- Global Install: .claude exists, agents/skills symlinks (0 broken), settings.json hooks
- Hook Scripts: all present and executable
- Hook Configuration: 14 events registered
- Generated Artifacts: AGENTS.md, llms.txt, llms-full.txt
- Planned Assets: plugin.json, benchmarks, plugin packs
- Benchmark Freshness: < 30 days
- Stale Rules: all healthy

**Verify:**
- [ ] `Errors: 0 | Warnings: 0`
- [ ] `HEALTH CHECK PASSED`

If doctor detects problems: `ai-toolkit doctor --fix` auto-repairs
(broken symlinks, non-executable hooks, missing scripts, missing llms-full.txt).

---

## Phase 4: Local Install (2 min)

```bash
mkdir -p /tmp/ai-toolkit-verify && cd /tmp/ai-toolkit-verify
git init -q
ai-toolkit install --local --editors all --dry-run
cd - && rm -rf /tmp/ai-toolkit-verify
```

**Verify "Project-local" section:**
- [ ] Would create: CLAUDE.md
- [ ] Would create: .claude/settings.local.json
- [ ] Would inject: .claude/constitution.md
- [ ] Editors: all 11 listed (copilot, cursor, windsurf, cline, roo, aider, augment, antigravity, codex, gemini, opencode)
- [ ] Would generate configs for each editor (legacy + directory-based)
- [ ] Would install: .git/hooks/pre-commit
- [ ] Would inject language rules (auto-detected)

**Also test auto-detect (no --editors flag):**
```bash
ai-toolkit install --local --dry-run
# → Editors: none (empty project has no existing configs)
```

---

## Phase 5: Validation & Security Audit (3 min)

```bash
python3 scripts/validate.py --strict
python3 scripts/audit_skills.py --ci
```

**Verify validate.py:**
- [ ] Agents: 44, Skills: 108, Tests: exactly the current README badge count
- [ ] Hook events: 14, Hook scripts: >= 30
- [ ] Plugin packs >= 10, KB documents >= 20
- [ ] `Errors: 0 | Warnings: 0` → `VALIDATION PASSED`

**Verify audit_skills.py:**
- [ ] `HIGH: 0` (MUST be zero — CI fails otherwise)
- [ ] `WARN: 0`
- [ ] `INFO: N` (acceptable — broad-access skills: orchestrate, swarm, workflow)

---

## Phase 6: Tests (3-5 min)

```bash
# Run ONCE, capture to file, then parse. Full suite is 669+ bats cases —
# re-running it per check (tail / grep ok / grep not ok piped separately)
# wastes minutes every release. Always cache the output.
npm test > /tmp/npm-test.log 2>&1
exit=$?
tail -3 /tmp/npm-test.log
echo "ok:     $(grep -c '^ok '    /tmp/npm-test.log)"
echo "not ok: $(grep -c '^not ok' /tmp/npm-test.log)"
echo "exit:   $exit"
```

**Verify:**
- [ ] `exit == 0`
- [ ] `ok == expected test count` (e.g., 945 on v3.0.0)
- [ ] `not ok == 0`
- [ ] Bats runs tests in parallel (4 jobs)
- [ ] Groups: agents, autodetect, cli, generators, guards, hooks, inject,
      install, kb, mcp, readme, profiles, uninstall, validate

**Anti-pattern — do NOT do this:**
```bash
# Runs the full suite THREE times. Adds 1-3 min and pressures CI capacity.
npm test 2>&1 | tail -3
npm test 2>&1 | grep -c '^ok '
npm test 2>&1 | grep -c '^not ok'
```

**Key test areas:**
- Guards: rm -rf, DROP TABLE, git push --force blocked
- Install: idempotent, profiles, --only/--skip, orphan cleanup
- Eject: real files (not symlinks), inlined rules
- Uninstall: removes toolkit, preserves user content

---

## Phase 7: Eject (1 min)

```bash
mkdir -p /tmp/ai-toolkit-eject-test
cd /tmp/ai-toolkit-eject-test
ai-toolkit eject
cd - && rm -rf /tmp/ai-toolkit-eject-test
```

**Verify:**
- [ ] Agents copied as real files (not symlinks)
- [ ] Skills copied as real directories
- [ ] Rules inlined into CLAUDE.md
- [ ] constitution.md and ARCHITECTURE.md copied
- [ ] `output-styles/` directory present (v2.7.1+)

---

## Phase 8: Supply-Chain Verification (2 min, v2.8.0+)

These checks enforce the v2.8.0 security standard on a freshly-published release. Run AFTER the `publish.yml` workflow completes on the tag.

### 8.1 Provenance attestation on npm

```bash
VERSION="X.Y.Z"                                           # the tag just published
npm view "@softspark/ai-toolkit@${VERSION}" --json \
  | python3 -c "import json, sys; d=json.load(sys.stdin); att=d['dist'].get('attestations', {}); assert att.get('provenance', {}).get('predicateType') == 'https://slsa.dev/provenance/v1', f'NO PROVENANCE for {d[\"version\"]}'; print(f'PROVENANCE OK: {att[\"url\"]}')"
```

**Verify:**
- [ ] Exit 0 and prints `PROVENANCE OK: https://registry.npmjs.org/...`
- [ ] `https://www.npmjs.com/package/@softspark/ai-toolkit/v/${VERSION}` shows the green "Provenance" badge

**If provenance is missing:** the `publish.yml` ran without `id-token: write` or `--provenance`. Restore them and cut a patch release — a silently unsigned publish is a regression against the v2.8.0 standard.

### 8.2 Audit SARIF output (for GHAS ingest)

```bash
python3 scripts/audit_skills.py --sarif > /tmp/audit.sarif
python3 -c "import json; d=json.load(open('/tmp/audit.sarif')); assert d['version']=='2.1.0' and d['runs'][0]['tool']['driver']['name']=='ai-toolkit-audit-skills'; print(f'SARIF OK: {len(d[\"runs\"][0][\"results\"])} results across {len(d[\"runs\"][0][\"tool\"][\"driver\"][\"rules\"])} rules')"
```

**Verify:**
- [ ] Valid SARIF 2.1.0
- [ ] In the publishing repo, the CI job uploads `audit.sarif` via `github/codeql-action/upload-sarif@v3` so findings appear in the Security tab

### 8.3 Per-skill permissions report

```bash
python3 scripts/audit_skills.py --permissions | head -40
```

**Verify:**
- [ ] Bash skill count has NOT jumped unexpectedly since the previous release
- [ ] Any newly added entry under `Skills with Bash + Write + Edit` matches a CHANGELOG bullet that justifies the broad scope
- [ ] JSON form (`--permissions --json`) is available for automated drift dashboards

### 8.4 URL-sourced rules/hooks are checksum-pinned

`sources.json` is an envelope of the form `{"schema_version": 1, "rules"|"hooks": {...}}`, so the jq filter must pick the nested map before piping into the pin assertion. The URL-count in the success message ignores local `path:`-only entries — only entries with a `url:` field are pinned and counted.

```bash
jq '.rules // .hooks // {}' ~/.softspark/ai-toolkit/rules/sources.json 2>/dev/null \
  | python3 -c "import json, sys; d=json.load(sys.stdin) or {}; bad=[n for n,v in d.items() if v.get('url') and not v.get('sha256')]; assert not bad, f'UNPINNED: {bad}'; url_n=sum(1 for v in d.values() if v.get('url')); print(f'RULE PIN OK: {url_n} URL rules, all with sha256')"
jq '.hooks // {}' ~/.softspark/ai-toolkit/hooks/external/sources.json 2>/dev/null \
  | python3 -c "import json, sys; d=json.load(sys.stdin) or {}; bad=[n for n,v in d.items() if v.get('url') and not v.get('sha256')]; assert not bad, f'UNPINNED: {bad}'; url_n=sum(1 for v in d.values() if v.get('url')); print(f'HOOK PIN OK: {url_n} URL hooks, all with sha256')"
```

**Verify:**
- [ ] Both commands print `... PIN OK`
- [ ] If any entry is unpinned, the `register_url_source()` call missed passing `content=` — fix the call-site and retag

### 8.5 Strict-pin smoke test (optional but recommended)

```bash
AI_TOOLKIT_STRICT_PIN=1 ai-toolkit update --dry-run
```

**Verify:**
- [ ] Exit 0, no `CHECKSUM CHANGED` line
- [ ] If a checksum change was intentional (e.g. upstream rule update), document it in the CHANGELOG entry before tagging

---

## Phase 9: Deep-Coverage Checks (v3.0.0+)

These verify the native-surface generators shipped in v3.0.0 actually emit the right files for the right profiles, and that the tool registry stays in sync with shipped generators.

> **Safety warning — HOME-scoped writes:** Running `--profile full` with `augment` in the editor list writes to `$HOME/.augment/settings.json` (Augment stores hooks under HOME, not per-project). Use `--dry-run` for verification unless you intend to carry ai-toolkit hook entries on this machine. The generator is marker-safe (only rewrites its own `_source: ai-toolkit` entries) but is still a side-effect.

### 9.1 `--profile full` emits every native surface

```bash
D=/tmp/aitk-profile-full-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
ai-toolkit install --local --editors cursor,windsurf,gemini,augment,codex,copilot \
  --profile full --dry-run 2>&1 \
  | grep -E "\\.cursor/(hooks\\.json|agents)|\\.devin/hooks\\.v1\\.json|\\.gemini/(settings\\.json|commands)|\\.augment/(agents|commands)|\\.codex/(agents|hooks)|\\.agents/skills|\\.github/(agents|skills|instructions|prompts|hooks)"
```

**Verify** — at least the following lines appear:
- [ ] `.cursor/hooks.json` and `.cursor/agents/`
- [ ] `.devin/hooks.v1.json`
- [ ] `.gemini/settings.json` hooks AND `.gemini/commands/`
- [ ] `.augment/agents/` + `.augment/commands/` + `$HOME/.augment/settings.json`
- [ ] `.codex/hooks.json` + `.codex/hooks/` + `.codex/agents/`
- [ ] `.agents/skills/` (Codex native discovery path)
- [ ] `.github/agents/` + `.github/skills/` + `.github/instructions/` + `.github/prompts/` + `.github/hooks/`

### 9.2 Codex skills are profile-independent

```bash
D=/tmp/aitk-codex-skills-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
ai-toolkit install --local --editors codex --profile minimal --dry-run 2>&1 \
  | grep -q "Would generate: .agents/skills" && echo "OK: Codex skills emit at minimal"
ai-toolkit install --local --editors codex --profile standard --codex-skills --dry-run 2>&1 \
  | grep -q "Would refresh: .agents/skills" && echo "OK: legacy flag explicitly refreshes the same catalog"
```

**Verify:**
- [ ] Selecting Codex emits all skills under `.agents/skills/` at every profile
- [ ] `--codex-skills` remains an explicit refresh alias; it is not required for installation
- [ ] No profile emits `.codex/skills/`

### 9.3 Breaking-change surfaces land on `--profile standard`

The standard profile must include:
- Copilot scoped instructions, prompts, custom agents, portable skills, and hooks
- Gemini hooks (`.gemini/settings.json`)

```bash
D=/tmp/aitk-breaking-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
ai-toolkit install --local --editors copilot,gemini --profile standard --dry-run 2>&1 \
  | tee /tmp/aitk-breaking.log
grep -q "\\.github/instructions/" /tmp/aitk-breaking.log && echo "OK: Copilot dir layout at standard"
grep -q "\\.github/agents/.*\\.github/skills/" /tmp/aitk-breaking.log && echo "OK: Copilot agents and skills at standard"
grep -q "\\.github/hooks/" /tmp/aitk-breaking.log && echo "OK: Copilot hooks at standard"
grep -q "\\.gemini/settings\\.json hooks" /tmp/aitk-breaking.log && echo "OK: Gemini hooks at standard"
```

**Verify all four lines print `OK:`**. If any is missing, native Copilot or Gemini coverage has regressed.

### 9.4 Install is idempotent

```bash
D=/tmp/aitk-idem-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
# Sort file paths before hashing — find traversal order follows inode order,
# which can shift between runs even when content is byte-identical, producing
# false FAIL signals.
ai-toolkit install --local --editors cursor,gemini --profile full >/dev/null 2>&1
SHA1=$(find .cursor .gemini -type f -print0 | LC_ALL=C sort -z | xargs -0 shasum | shasum | awk '{print $1}')
ai-toolkit install --local --editors cursor,gemini --profile full >/dev/null 2>&1
SHA2=$(find .cursor .gemini -type f -print0 | LC_ALL=C sort -z | xargs -0 shasum | shasum | awk '{print $1}')
[ "$SHA1" = "$SHA2" ] && echo "OK: idempotent" || echo "FAIL: install is not idempotent"
```

**Verify:** prints `OK: idempotent`. A second run must produce byte-identical files in every managed path.

### 9.5 Live-install JSON outputs parse

The bats suite validates JSON shape at generation time. This re-checks that what actually landed on disk after a live install parses without errors.

```bash
D=/tmp/aitk-json-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
ai-toolkit install --local --editors cursor,windsurf,gemini,augment,codex,copilot --profile full >/dev/null 2>&1
for f in .cursor/hooks.json .devin/hooks.v1.json .gemini/settings.json .codex/hooks.json .github/hooks/ai-toolkit.json "$HOME/.augment/settings.json"; do
  [ -f "$f" ] && python3 -c "import json; json.load(open('$f'))" && echo "OK: $f"
done
```

**Verify:** each emitted file prints `OK: <path>`. Any `json.decoder.JSONDecodeError` means the merge logic corrupted the output.

### 9.6 Registry / generator drift check

`kb/reference/supported-tools-registry.md` should enumerate every per-editor `scripts/generate_*.py` we ship. Meta-generators (`generate_agents_md.py`, `generate_llms_txt.py`) are excluded — they produce docs/artifacts, not editor configs.

```bash
META="generate_agents_md.py|generate_llms_txt.py|generate_language_rules_skills.py"
REG=$(grep -oE 'scripts/generate_[a-z_]+\.py' kb/reference/supported-tools-registry.md | sort -u)
FS=$(ls scripts/generate_*.py | grep -vE "$META" | sort -u)
diff <(echo "$REG") <(echo "$FS") && echo "OK: registry matches filesystem" || echo "DRIFT: update supported-tools-registry.md"
```

**Verify:** prints `OK: registry matches filesystem`. If not, add the missing rows to the registry before tagging the next release.

### 9.7 Claude Chat / Cowork plugin validates and exports

```bash
python3 scripts/claude_app.py verify
D=/tmp/aitk-claude-app-${RANDOM}
python3 scripts/claude_app.py export --output "$D.zip" --no-custom-rules
python3 -c "import zipfile; z=zipfile.ZipFile('$D.zip'); assert '.claude-plugin/plugin.json' in z.namelist(); assert 'claude-app/skills/ai-toolkit-rules/SKILL.md' in z.namelist(); print('OK: Claude app archive')"
```

**Verify:** the official validator exits 0; the archive contains the manifest,
app-native rules skill, bundled agents/skills, and plugin-relative Cowork hooks.

---

## Troubleshooting

### `ai-toolkit: command not found`

```bash
npm install -g @softspark/ai-toolkit
# or check PATH:
export PATH="$(npm config get prefix)/bin:$PATH"
```

### Doctor: broken symlinks

```bash
ai-toolkit doctor --fix    # auto-repair
ai-toolkit update          # or full re-install
```

### Tests fail: missing bats

```bash
brew install bats-core     # macOS
npm install -g bats        # cross-platform
```

### validate.py: stale counts

README badges don't match the current agents/skills/tests counts.
Update README.md and re-run.

### Eject: missing skills

```bash
ai-toolkit update          # re-link missing symlinks
ai-toolkit eject /tmp/test # retry
```

---

## Success Criteria

| Area | Criterion |
|------|-----------|
| CLI | `--version` correct, `--help` full list, `status` current |
| Health | `doctor`: 0 errors, 0 warnings, PASSED |
| Install | `--dry-run` correct counts, `--local` all configs |
| Quality | `validate.py --strict`: PASSED |
| Security (baseline) | `audit_skills.py --ci`: 0 HIGH |
| Security (SARIF) | `audit_skills.py --sarif`: valid SARIF 2.1.0 with non-empty rules array |
| Security (permissions) | `audit_skills.py --permissions`: broad-access skills unchanged or justified in CHANGELOG |
| Supply chain | `dist.attestations.provenance.predicateType == https://slsa.dev/provenance/v1` on npm |
| Supply chain | All `sources.json` URL entries carry a `sha256`; `AI_TOOLKIT_STRICT_PIN=1 ai-toolkit update --dry-run` passes |
| Tests | `npm test`: N/N passed, 0 failures |
| Eject | Standalone `.claude/` with real files AND `output-styles/` directory |
| Guards | Destructive commands blocked |
| Deep coverage | `--profile full` emits every documented native surface, including Codex agents/skills/hooks and Copilot agents/skills/hooks |
| Profile contract | Codex skills emit at every profile without `--codex-skills`; Copilot standard emits agents, skills, instructions, prompts, and hooks |
| Idempotence | Second `install` run produces byte-identical output in every managed path |
| Live JSON | Every generated `.json` file on disk parses as valid JSON |
| Registry | `supported-tools-registry.md` enumerates every `scripts/generate_*.py` we ship |

---

## kb/reference/agents-catalog.md

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

# Agents Catalog

## By Category

### Orchestration & Planning (4)

| Agent | Model | Use Case |
|-------|-------|----------|
| **orchestrator** | opus | Multi-agent coordination, 3+ agents per task |
| **project-planner** | opus | Task breakdown, dependency graphs, file structure |
| **product-manager** | opus | Requirements, user stories, acceptance criteria, backlog prioritization |
| **tech-lead** | opus | Code quality authority, architecture patterns |

### Development (5)

| Agent | Model | Use Case |
|-------|-------|----------|
| **backend-specialist** | opus | Node.js, Python, PHP, FastAPI, APIs |
| **frontend-specialist** | opus | React, Next.js, Vue, Nuxt, Tailwind |
| **mobile-developer** | opus | React Native, Flutter, native iOS/Android |
| **game-developer** | opus | Unity, Godot, Unreal, Phaser, Three.js |
| **database-architect** | opus | Schema design, migrations, query optimization, operations |

### AI/ML (6)

| Agent | Model | Use Case |
|-------|-------|----------|
| **ai-engineer** | opus | LLM integration, vector databases, RAG pipelines, agent orchestration |
| **ml-engineer** | opus | Model training, MLOps, TensorFlow, PyTorch |
| **nlp-engineer** | opus | NLP pipelines, NER, text classification, transformers |
| **data-scientist** | opus | Statistics, visualization, EDA, hypothesis testing |
| **data-analyst** | sonnet | SQL, analytics, reporting, dashboards |
| **prompt-engineer** | opus | Prompt design, chain-of-thought, few-shot, optimization |

### Quality & Security (6)

| Agent | Model | Use Case |
|-------|-------|----------|
| **code-reviewer** | opus | Code review, standards, quality audit |
| **test-engineer** | opus | Test strategy, TDD, unit/integration/E2E tests |
| **qa-automation-engineer** | opus | Playwright, Cypress, API testing, performance testing |
| **security-auditor** | opus | OWASP, CVE analysis, pen testing, vulnerability assessment |
| **security-architect** | opus | Threat modeling, secure design, AuthN/AuthZ |
| **system-governor** | opus | Constitution guardian, validates changes, VETO power |

### Infrastructure & DevOps (6)

| Agent | Model | Use Case |
|-------|-------|----------|
| **devops-implementer** | opus | Terraform, Ansible, Docker, Kubernetes, CI/CD |
| **infrastructure-architect** | opus | System design, architecture notes, trade-off analysis |
| **infrastructure-validator** | sonnet | Deployment verification, health checks, rollback |
| **incident-responder** | sonnet | P1-P4 incidents, emergency fixes, postmortem |
| **performance-optimizer** | opus | Profiling, bottleneck analysis, latency, scaling |
| **llm-ops-engineer** | opus | LLM caching, fallback, cost optimization, observability |

### Research & Documentation (5)

| Agent | Model | Use Case |
|-------|-------|----------|
| **explorer-agent** | sonnet | Codebase discovery (READ-ONLY, never writes) |
| **technical-researcher** | opus | Deep technical investigation, research synthesis |
| **search-specialist** | sonnet | Search optimization, relevance ranking |
| **fact-checker** | sonnet | Claim verification, source validation |
| **documenter** | sonnet | Documentation, KB management, SOPs, API docs, tutorials |

### MCP (2)

| Agent | Model | Use Case |
|-------|-------|----------|
| **mcp-specialist** | opus | MCP server design, client config, troubleshooting |
| **mcp-testing-engineer** | sonnet | MCP protocol compliance, transport testing |

### Management & Evolution (4)

| Agent | Model | Use Case |
|-------|-------|----------|
| **chief-of-staff** | sonnet | Executive summaries, daily briefings, noise reduction |
| **meta-architect** | opus | Self-optimization, agent definition updates |
| **predictive-analyst** | sonnet | Impact prediction, regression forecasting |
| **business-intelligence** | sonnet | Opportunity discovery, KPI gaps, value creation |

### Autonomous (2)

| Agent | Model | Use Case |
|-------|-------|----------|
| **night-watchman** | sonnet | Autonomous maintenance: dependency updates, dead code |
| **chaos-monkey** | opus | Resilience testing: fault injection, failure verification |

### Specialist (4)

| Agent | Model | Use Case |
|-------|-------|----------|
| **debugger** | opus | Root cause analysis, stack traces, intermittent failures |
| **code-archaeologist** | sonnet | Legacy code investigation, technical debt |
| **command-expert** | sonnet | CLI commands, bash scripting, build scripts |
| **seo-specialist** | sonnet | SEO optimization, meta tags, Core Web Vitals |

## Agent Selection Matrix

| Task Type | Primary | Supporting | Validation |
|-----------|---------|------------|------------|
| New Feature | backend/frontend-specialist | test-engineer | code-reviewer |
| Bug Fix | debugger | backend/frontend | test-engineer |
| Performance | performance-optimizer | database-architect | infrastructure-validator |
| Security | security-auditor | security-architect | code-reviewer |
| Architecture | infrastructure-architect | devops-implementer | security-auditor |
| Documentation | documenter | explorer-agent | tech-lead |
| AI/ML | ai-engineer | ml-engineer | data-scientist |
| Research | technical-researcher | search-specialist | fact-checker |

---

## kb/reference/anti-pattern-registry-format.md

---
title: "Anti-Pattern Registry Format"
category: reference
service: ai-toolkit
description: "Structured JSON format for anti-patterns with severity, auto-fixability, and conflict rules. Used by domain skills with reasoning engines."
tags: [anti-patterns, skills, reasoning-engine, format]
created: 2026-04-01
last_updated: 2026-04-01
---

# Anti-Pattern Registry Format

## Overview

The anti-pattern registry is a structured JSON format used by domain skills that
employ reasoning engines. It provides a machine-readable catalog of known
anti-patterns with severity levels, auto-fix capabilities, and conflict rules.

## When to Use

Use structured JSON registries (this format) when:

- The skill catalogs **more than 50 items** across **more than 3 compatibility
  dimensions** (e.g., domain, severity, language, framework).
- Items have relationships (conflicts, prerequisites, alternatives) that must be
  queryable at runtime.
- The reasoning engine (`search.py`) needs to filter, score, and exclude
  conflicting entries programmatically.

Use Markdown tables when:

- Fewer than 50 items with 3 or fewer dimensions.
- No inter-item relationships.
- Human readability is the only consumer.

## JSON Schema

Each entry in the registry follows this schema:

```json
{
  "id": "string (required)",
  "name": "string (required)",
  "domain": "string (required)",
  "description": "string (required)",
  "pattern": "string (optional)",
  "severity": "string (required)",
  "auto_fixable": "boolean (required)",
  "conflicts_with": ["string (optional)"],
  "remediation": "string (required)",
  "tags": ["string (optional)"]
}
```

### Field Definitions

#### `id` (required)

Unique identifier in kebab-case. Must be globally unique across all registry
files within the same assets directory.

```
"id": "n-plus-one-query"
```

#### `name` (required)

Human-readable display name. Used in reports and dashboards.

```
"name": "N+1 Query Problem"
```

#### `domain` (required)

The skill domain this anti-pattern belongs to. Used for filtering when a
reasoning engine serves multiple domains.

Valid domains include: `security`, `database`, `api`, `architecture`,
`performance`, `testing`, `general`. Skills may define additional domains as
needed.

```
"domain": "database"
```

#### `description` (required)

Clear explanation of what this anti-pattern is and why it is problematic. Should
be actionable -- a developer reading this should understand the risk.

```
"description": "Executing one query per item in a loop instead of a single batch query. Causes O(n) database round-trips where O(1) is possible."
```

#### `pattern` (optional)

A regex pattern for automated detection in source code. When present, tooling
can scan codebases for occurrences. Omit if the anti-pattern is architectural
or cannot be detected via regex.

```
"pattern": "for\\s+.*\\sin\\s+.*:\\s*\\n\\s+.*\\.objects\\.get"
```

#### `severity` (required)

Impact level. Must be one of:

| Value | Meaning |
|-------|---------|
| `critical` | Causes security vulnerabilities, data loss, or production outages. Must fix before merge. |
| `important` | Degrades performance, maintainability, or reliability significantly. Should fix in current sprint. |
| `suggestion` | Improvement opportunity. Fix when convenient or during refactoring. |

```
"severity": "important"
```

#### `auto_fixable` (required)

Boolean indicating whether tooling can automatically remediate this
anti-pattern. When `true`, the reasoning engine or a companion script can
generate a fix.

```
"auto_fixable": true
```

#### `conflicts_with` (optional)

List of anti-pattern IDs that conflict with this entry. The reasoning engine
uses this for mutual exclusion -- if one pattern is selected/detected, the
conflicting ones are filtered out of results.

This prevents contradictory advice (e.g., "use eager loading" and "use lazy
loading" simultaneously).

```
"conflicts_with": ["eager-load-everything"]
```

#### `remediation` (required)

Concrete instructions for fixing the anti-pattern. Should include a code
example or reference to a known-good pattern when possible.

```
"remediation": "Replace loop queries with select_related() or prefetch_related() for Django, or use JOIN/eager loading in your ORM."
```

#### `tags` (optional)

Freeform tags for cross-cutting search. Useful for filtering by technology,
language, or concern that does not map to a single domain.

```
"tags": ["orm", "django", "sqlalchemy", "performance"]
```

## Complete Example

```json
[
  {
    "id": "n-plus-one-query",
    "name": "N+1 Query Problem",
    "domain": "database",
    "description": "Executing one query per item in a loop instead of a single batch query. Causes O(n) database round-trips where O(1) is possible.",
    "pattern": "for\\s+.*\\sin\\s+.*:\\s*\\n\\s+.*\\.objects\\.get",
    "severity": "important",
    "auto_fixable": false,
    "conflicts_with": [],
    "remediation": "Replace loop queries with select_related() or prefetch_related() for Django, or use JOIN/eager loading in your ORM.",
    "tags": ["orm", "django", "sqlalchemy", "performance"]
  },
  {
    "id": "hardcoded-secrets",
    "name": "Hardcoded Secrets",
    "domain": "security",
    "description": "API keys, passwords, or tokens embedded directly in source code. Exposed in version control history even after removal.",
    "pattern": "(api_key|secret|password|token)\\s*=\\s*[\"'][^\"']+[\"']",
    "severity": "critical",
    "auto_fixable": true,
    "conflicts_with": [],
    "remediation": "Move secrets to environment variables or a secrets manager (AWS SSM, Vault, dotenv for local). Reference via os.environ or settings module.",
    "tags": ["secrets", "env", "vault", "ci"]
  }
]
```

## File Organization

Registry files live in the `assets/` directory alongside the reasoning engine:

```
templates/reasoning-engine/
  search.py           # Reasoning engine
  assets/
    example.json      # Template/example entries
    security.json     # Security anti-patterns
    database.json     # Database anti-patterns
    api.json          # API anti-patterns
```

Each file is a JSON array. The reasoning engine loads and merges all `*.json`
files from `assets/` at startup. Keep files organized by domain to avoid merge
conflicts and improve discoverability.

## Integration with Reasoning Engine

The `search.py` reasoning engine uses registry entries as follows:

1. **Load**: All JSON files in `assets/` are loaded and merged into a flat list.
2. **Match**: User query is tokenized and scored against all fields.
3. **Filter**: `conflicts_with` entries are excluded based on already-selected
   items via `filter_anti_patterns()`.
4. **Return**: Top results are returned as JSON to stdout.

Skills that use this pattern should document the `--domain` flag to scope
searches to their specific domain.

---

## kb/reference/architecture-overview.md

---
title: "AI Toolkit - Architecture Overview"
category: reference
service: ai-toolkit
tags: [architecture, overview, design, structure]
version: "1.6.0"
created: "2026-03-23"
last_updated: "2026-07-26"
description: "Architecture of ai-toolkit: directory layout, Claude app export, global install model, editor-aware MCP install, Codex translation layer, skill tiers, and integration with projects."
---

# AI Toolkit Architecture

## Purpose

Shared, project-agnostic AI development toolkit for Claude Code, Claude Chat/Cowork, and compatible assistants such as Cursor, Devin, Copilot, Gemini, Cline, Roo/Zoo Code, Aider, Augment, and Google Antigravity. Provides agents, skills, lifecycle hooks, persona presets, and runtime-specific plugin packaging.

## Design Principles

1. **Global install** — one `~/.claude/` install works for all projects; no per-project setup beyond `init`
2. **Merge-friendly** — per-file symlinks, JSON merge, marker injection; user content never overwritten
3. **Composable** — agents reference skills; skills invoke agents; hooks validate all work
4. **Multi-language** — hooks and skills support Python, TypeScript, PHP, Dart, Go
5. **Cost-optimized** — simpler agents run on `sonnet`, complex reasoning on `opus`

## Directory Structure

```
ai-toolkit/
  bin/
    ai-toolkit.js        # CLI entry point (install, init, add-rule, ...)
  app/                       # All toolkit components
    agents/                  # Agent definitions (.md + YAML frontmatter)
    skills/                  # skills: task, hybrid, knowledge
    rules/                   # Source rules synced into Claude/editor rule files
    claude-app/              # Generated app-only rules skill, hooks, instructions
    hooks/                   # Hook scripts (copied to ~/.softspark/ai-toolkit/hooks/)
    hooks.json               # Hook definitions (merged into ~/.claude/settings.json)
    constitution.md          # Immutable safety rules, 7 articles (marker-injected)
    ARCHITECTURE.md          # System architecture reference (marker-injected)
    CLAUDE.md.template       # Template for project CLAUDE.md (used by init)
    settings.local.json.template
    .claude-plugin/
      plugin.json            # Official plugin manifest
    plugins/                 # Experimental opt-in plugin packs + optional modules
  scripts/                   # All scripts
    install.py               # Global installer → ~/.claude/ (--local for project-local setup)
    uninstall.py             # Removes toolkit components from ~/.claude/
    inject_rule_cli.py       # Injects a rule into CLAUDE.md (delegates to inject_section_cli.py)
    inject_section_cli.py    # Marker-based content injection (canonical implementation)
    _common.py               # Shared helper for generators (frontmatter, agents/skills emission)
    merge-hooks.py           # JSON merge for hooks into settings.json (inject/strip modes)
    validate.py              # Toolkit integrity check
    evaluate_skills.py       # Skill quality report
    generate_agents_md.py    # Regenerates AGENTS.md
    generate_cursor_rules.py # Generates .cursorrules (sources _common.py)
    generate_windsurf.py     # Generates .windsurfrules (sources _common.py)
    generate_copilot.py      # Generates Copilot instructions, agents, and portable skills
    generate_copilot_hooks.py # Generates native Copilot hooks + self-contained runtime
    generate_gemini.py       # Generates GEMINI.md (sources _common.py)
    generate_cline.py        # Generates .clinerules (sources _common.py)
    generate_roo_modes.py    # Generates .roomodes
    generate_aider_conf.py   # Generates .aider.conf.yml
    generate_llms_txt.py     # Generates llms.txt
    install_git_hooks.py     # Installs fallback pre-commit hook
    plugin.py                # Plugin pack management (install, remove, list, status)
    claude_app.py            # Claude Chat/Desktop/Cowork plugin export + validation
    benchmark_ecosystem.py   # Generates ecosystem benchmark snapshot
    harvest_ecosystem.py     # Writes machine-readable ecosystem harvest JSON
    compile_slm.py           # Compiles toolkit into minimal SLM system prompt (2K-16K tokens)
  tests/                     # Bats test suite
  benchmarks/                # Benchmark tasks + results
  kb/                        # Knowledge base
    reference/               # Catalogs, architecture, usage guides
    procedures/              # SOPs (install, maintenance)
    reference/               # architecture, operating models, and usage guides
```

## Install Model

All components use merge-friendly strategies — user content is never overwritten.

```
Machine (global)                              Project (local)
──────────────────────────────────────────    ──────────────────────────────────────
~/.claude/                                    ~/.softspark/ai-toolkit/
  agents/*.md    → per-file symlinks             rules/     ← registered rules
  skills/*/      → per-dir symlinks              hooks/     ← hook scripts (copied)
  settings.json  ← hooks merged here
  constitution.md ← marker injection            my-project/
  ARCHITECTURE.md ← marker injection              CLAUDE.md            ← project index
  CLAUDE.md       ← compact rule index            .claude/
  rules/*.md      ← Claude user-level rules
                                                    settings.local.json  ← MCP, perms
                                                    constitution.md     ← marker injection
```

| Component | Strategy | Collision handling |
|-----------|----------|-------------------|
| `agents/*.md` | Per-file symlinks | User file with same name wins (toolkit skipped) |
| `skills/*/` | Per-directory symlinks | User dir with same name wins (toolkit skipped) |
| `settings.json` hooks | JSON merge via `merge-hooks.py` | User hooks + settings preserved, toolkit entries tagged with `_source` |
| `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` | Marker injection via `inject_rule_cli.py` | Same as above |

**`ai-toolkit install`** — run once per machine, merges toolkit into `~/.claude/`. Auto-upgrades old whole-directory symlinks.

**`ai-toolkit update`** — re-apply after `npm install -g @softspark/ai-toolkit@latest` or after `add-rule` / `remove-rule`. Same as `install` but semantically correct for update flows.

**`ai-toolkit install --local`** — run per project. Always installs Claude Code configs (CLAUDE.md, settings.local.json, constitution.md, language rules). Editor configs are opt-in via `--editors`:
- `--editors all` — install all 11 editors (Cursor, Windsurf, Cline, Roo, Aider, Augment, Copilot, Antigravity, Codex, Gemini, opencode)
- `--editors cursor,aider` — install only selected editors
- (no flag) — auto-detect from existing project files; `update --local` picks up whatever editors already have configs

Each editor gets its documented directory-based format. Copilot receives root
`AGENTS.md`, `.github/copilot-instructions.md`, native `.github/agents`, and
self-contained `.github/skills` in every profile. Profile `standard` and above
also emits `.github/instructions`, `.github/prompts`, and native
`.github/hooks`. The user target writes the supported personal surfaces below
`$COPILOT_HOME` (default `~/.copilot`) and does not generate prompt files there.
Full-profile installs also emit native skill pointer catalogues for Cursor,
Windsurf, and Cline. Codex local install generates `AGENTS.md`,
`.agents/skills/*`, `.codex/agents/*.toml`, `.codex/hooks.json`, and
self-contained `.codex/hooks/*`. Global Codex install writes its user-owned
surfaces below `$CODEX_HOME` (default `~/.codex`) while user skills remain in
the documented shared `$HOME/.agents/skills/` directory. Experimental plugin
packs can layer their rules, skills, and hooks onto that Codex user target.

Claude Chat/Desktop/Cowork is deliberately outside `--editors`: the app does not scan filesystem configuration under `~/.claude`. `ai-toolkit claude-app export` creates a self-contained plugin ZIP with skills, agents, Cowork hooks, app-native rules, and bundled hook dependencies. It also emits the compact text that users paste into Cowork global instructions. Updating requires re-export and re-upload because the app owns its plugin store.

If a project already has `.mcp.json`, local install mirrors its `mcpServers`
entries into `.claude/settings.local.json` plus any selected editors with
project-scoped native MCP files: `.cursor/mcp.json`, `.github/mcp.json`,
`.roo/mcp.json`, and `.codex/config.toml`.

## CLI Commands

| Command | Target | What it does |
|---------|--------|-------------|
| `install` | `~/.claude/` | First-time: per-file symlinks + JSON merge + marker injection + rules |
| `install --local` | `./` | Claude Code configs + editors via `--editors` (auto-detect or explicit) |
| `claude-app export` | output ZIP + Markdown | Uploadable Claude Chat/Cowork plugin and global instructions |
| `update` | `~/.claude/` | Re-apply after npm update or after add-rule/remove-rule |
| `update --local` | `./` | Re-apply + refresh project-local configs |
| `uninstall` | `~/.claude/` | Strips toolkit components (preserves user content) |
| `add-rule <file>` | `~/.softspark/ai-toolkit/rules/` | Register rule — auto-applied on every `update` |
| `remove-rule <name>` | `~/.softspark/ai-toolkit/rules/` + `~/.claude/rules/` | Unregister rule and remove generated Claude rule file |
| `mcp add <name...>` | `./.mcp.json` | Merge canonical MCP template(s) into project config |
| `mcp install --editor <name...>` | native editor config | Render MCP template(s) into editor-native config files |
| `validate` | toolkit | Integrity check |
| `doctor` | toolkit | Install health, hooks, benchmark freshness, and artifact drift diagnostics |
| `benchmark-ecosystem` | toolkit | Benchmark snapshot for official Claude Code and external ecosystem repos |
| `evaluate` | toolkit | Skill quality report |
| `cursor-rules` | `./` | Generates `.cursorrules` (legacy) |
| `cursor-mdc` | `./` | Generates `.cursor/rules/*.mdc` (recommended) |
| `windsurf-rules` | `./` | Generates `.windsurfrules` (legacy) |
| `windsurf-dir-rules` | `./` | Generates `.devin/rules/*.md` + `.windsurf/rules/*.md` (dual-emit) |
| `copilot-instructions` | `./` | Generates `.github/copilot-instructions.md` |
| `gemini-md` | `./` | Generates `GEMINI.md` |
| `cline-rules` | `./` | Generates `.clinerules` (legacy) |
| `cline-dir-rules` | `./` | Generates `.clinerules/*.md` |
| `roo-modes` | `./` | Generates `.roomodes` |
| `roo-dir-rules` | `./` | Generates `.roo/rules/*.md` |
| `aider-conf` | `./` | Generates `.aider.conf.yml` |
| `conventions-md` | `./` | Generates `CONVENTIONS.md` (Aider auto-loaded) |
| `augment-dir-rules` | `./` | Generates `.augment/rules/ai-toolkit-*.md` |
| `antigravity-rules` | `./` | Generates `.agents/rules/` + `.agents/workflows/` |
| `codex-md` | `./` | Generates Codex-facing `AGENTS.md` |
| `codex-hooks` | `./` | Generates `.codex/hooks.json` |
| `agents-md` | toolkit | Regenerates `AGENTS.md` |
| `llms-txt` | `./` | Generates `llms.txt` |
| `generate-all` | `./` | Generates all platform configs at once |

## Skill Tiers

Three tiers determine how to approach a task:

| Tier | Skills | When to use |
|------|--------|-------------|
| **1 — Quick single-agent** | `/debug`, `/review`, `/refactor`, `/analyze`, `/docs`, `/plan`, `/explain` | One concern, one file area, fast |
| **2 — Multi-agent workflow** | `/workflow <type>` | Cross-cutting task with a known pattern |
| **3 — Custom parallelism** | `/orchestrate`, `/swarm` | No predefined workflow matches |

### `/workflow` types (15)

| Type | Use case |
|------|----------|
| `feature-development` | New feature, full stack |
| `backend-feature` | Backend only: API + logic + tests |
| `frontend-feature` | UI component + state + tests |
| `api-design` | New API endpoint design → implement → document |
| `database-evolution` | Schema change + migration + code update |
| `test-coverage` | Boost test coverage for a module |
| `security-audit` | Multi-vector security assessment |
| `codebase-onboarding` | Understand unfamiliar codebase (read-only) |
| `spike` | Time-boxed technical research → architecture note |
| `debugging` | Bug spanning multiple layers |
| `incident-response` | Production down |
| `performance-optimization` | Degradation >50% |
| `infrastructure-change` | Docker, CI/CD, infra |
| `application-deploy` | Deploy |
| `proactive-troubleshooting` | Warning / trend |

## Skill Classification

| Type | Field | Invocation | Count |
|------|-------|-----------|-------|
| Task | `disable-model-invocation: true` | User via `/skill` only | 32 |
| Hybrid | (neither) | User via `/skill` + agent knowledge | 30 |
| Knowledge | `user-invocable: false` | Claude auto-loads | 46 |

## Multi-Agent Execution

Skills that spawn real parallel agents use:
- `agent: <name>` — delegates to a specialized agent persona
- `context: fork` — runs in isolated forked context
- `Agent` tool — spawns subagents in parallel within the agent's response

`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` must be set for Agent Teams (tmux-based) support.

### Codex Translation Layer

Codex does not expose Claude's `Agent`, `Team*`, and `Task*` primitives with the
same runtime semantics. To keep the skill catalog aligned, local Codex install
uses a translation layer:

- native Codex-compatible skills are linked directly
- Claude-only orchestration skills are emitted as generated wrappers
- wrapper guidance maps delegation to `spawn_agent`, `send_input`, `wait_agent`, `close_agent`, and `update_plan`

Codex therefore receives the full skill catalog, but not the full Claude hook
surface or tmux-backed Agent Teams lifecycle. Plugin packs reuse the same
translation and hook-compatibility model when targeting the global Codex layer.

See `kb/reference/codex-cli-compatibility.md` for the detailed mapping.

## MCP Rendering Layer

`.mcp.json` is the canonical project-level template format. ai-toolkit can render that configuration into editor-native MCP files through `scripts/mcp_editors.py`.

Current native adapters:
- Claude Code: `.claude/settings.local.json` and `~/.claude/settings.json`
- Cursor: `.cursor/mcp.json` and `~/.cursor/mcp.json`
- GitHub Copilot: `.github/mcp.json` and `$COPILOT_HOME/mcp-config.json` (default `~/.copilot/mcp-config.json`)
- Gemini CLI: `.gemini/settings.json` and `~/.gemini/settings.json`
- Windsurf: `~/.codeium/windsurf/mcp_config.json`
- Cline: `~/.cline/data/settings/cline_mcp_settings.json`
- Augment: `~/.augment/settings.json`
- Codex CLI: `.codex/config.toml` and `$CODEX_HOME/config.toml` (default `~/.codex/config.toml`)

See `kb/reference/mcp-editor-compatibility.md` for the support matrix and scope rules.

## Quality Guardrails

### Anti-Rationalization Tables
15 core skills include `## Common Rationalizations` tables — domain-specific excuses with rebuttals that prevent agent drift. Skills: `/review`, `/debug`, `/refactor`, `/tdd`, `/plan`, `/docs`, `/analyze`, `security-patterns`, `testing-patterns`, `api-patterns`, `ci-cd-patterns`, `clean-code`, `performance-profiling`, `git-mastery`, `database-patterns`.

### Confidence Scoring & LLM-as-Judge (`/review`)
Review findings include per-issue confidence scores (1-10) and severity tiers (critical/major/minor/nit). A self-evaluation pass after review checks for anchoring bias, assumption vs verification, and calibrates confidence.

### Agent Verification Checklists
10 agents have `## Verification Checklist` — domain-specific exit criteria: `code-reviewer`, `test-engineer`, `security-auditor`, `debugger`, `backend-specialist`, `frontend-specialist`, `database-architect`, `performance-optimizer`, `devops-implementer`, `documenter`.

### Skill Reference Routing
7 core skills include `## Related Skills` suggesting follow-up skills: `/review`, `/debug`, `/plan`, `/refactor`, `/tdd`, `/docs`, `/analyze`.

### Intent Capture Interview (`/onboard`)
Step 0 interview — 5 questions to capture undocumented project intent before setup.

## Component Relationships

```
Skills (/review, /deploy, /debug, ...)
    │
    ▼
Agents (code-reviewer, debugger, devops-implementer, ...)
    │
    ├── load: knowledge skills (clean-code, typescript-patterns, ...)
    │
    ├── validated by: hooks in settings.json (SessionStart, PreToolUse, UserPromptSubmit, PostToolUse, Stop, TaskCompleted, TeammateIdle, SubagentStart, SubagentStop, PreCompact, SessionEnd)
    │
    └── constrained by: constitution.md (7 safety articles)
```

## Quality Hooks

29 entries across 14 lifecycle events. See [hooks-catalog.md](hooks-catalog.md) for full details.

| Hook | Trigger | Script | Action |
|------|---------|--------|--------|
| SessionStart | Session start + compact | `session-start.sh` | MANDATORY rules reminder + session context + instincts |
| SessionStart | Session start | `mcp-health.sh` | Check MCP runtime availability |
| Notification | Claude waiting for input | *(inline)* | macOS desktop notification |
| PreToolUse | Before Bash | `guard-destructive.sh` | Block destructive commands |
| PreToolUse | Before file ops (Bash, Read, Edit, Write, MultiEdit, Glob, Grep, NotebookEdit, mcp\_filesystem) | `guard-path.sh` | Block wrong-user path hallucination |
| PreToolUse | Before Edit/Write/MultiEdit | `guard-config.sh` | Always block protected config edits; remove the hook deliberately when a change is authorized |
| PreToolUse | Before Bash (git commit) | `commit-quality.sh` | Advisory Conventional Commits format check |
| UserPromptSubmit | Before user prompt execution | `user-prompt-submit.sh` | Prompt governance reminder |
| UserPromptSubmit | Before user prompt execution | `track-usage.sh` | Record skill invocations to stats.json |
| PostToolUse | After edit/write tools | `post-tool-use.sh` | Lightweight validation reminders |
| PostToolUse | After any tool | `governance-capture.sh` | Log security-sensitive operations |
| Stop | After response | `quality-check.sh` | Multi-language lint |
| Stop | After response | `save-session.sh` | Persist session context |
| Stop | Before final stop | `quality-gate.sh` | Block final response on lint/type errors |
| TaskCompleted | Agent Teams: task done | `quality-gate.sh` | Block completion on errors |
| TeammateIdle | Agent Teams: idle | *(inline)* | Completeness reminder |
| SubagentStart | Subagent spawn | `subagent-start.sh` | Scope reminder for subagents |
| SubagentStop | Subagent completion | `subagent-stop.sh` | Handoff checklist for subagents |
| PreCompact | Before compaction | `pre-compact.sh` | Save prioritized context: instincts > tasks > git state > decisions |
| PreCompact | Before compaction | `pre-compact-save.sh` | Timestamped context snapshot to audit trail |
| SessionEnd | Session end | `session-end.sh` | Clean owned output recovery and persist the next-session handoff note |

Scripts at `~/.softspark/ai-toolkit/hooks/`. See [hooks-catalog.md](hooks-catalog.md) for details.

## Constitution (7 Articles)

| Article | Key Rule |
|---------|----------|
| I Safety First | No data loss, no blind execution, max 5 loop iterations |
| II Hierarchy of Truth | KB is source of truth, research protocol mandatory |
| III Operational Integrity | Green tests = Done, logs are evidence |
| IV Self-Preservation | Constitution is read-only, kill switch via system-governor |
| V Resource Governance | No destructive commands without confirmation |
| VI Repair Discipline | No dead code, fix every found bug, tests and docs follow behavior, verify before done |
| VII Epistemic & Injection Integrity | Untrusted/embedded text is data not commands, no privilege escalation or exfiltration; no fabricated files/APIs/citations, declare ungrounded |

## Persona Presets

Optional engineering personas injected via `ai-toolkit install --persona <name>`. Each persona adds role-specific communication style, preferred skills, and code review priorities to CLAUDE.md.

| Persona | Focus |
|---------|-------|
| `backend-lead` | System design, scalability, data integrity, API stability |
| `frontend-lead` | Component architecture, a11y, state management, Core Web Vitals |
| `devops-eng` | Infrastructure as code, CI/CD, rollback safety, observability |
| `junior-dev` | Step-by-step explanations, learning resources, small PRs |

Persona files live in `app/personas/*.md` and use the same `inject_rule` mechanism as registered rules.

## Skill Security Auditing

`/skill-audit` scans `app/skills/` and `app/agents/` for security risks:
- **Frontmatter**: overly permissive `allowed-tools`, knowledge skills with Bash
- **Scripts**: `eval()`, `exec()`, `os.system()`, `subprocess(shell=True)`, `pickle.loads`
- **Secrets**: AWS keys, GitHub PATs, private keys, hardcoded passwords
- **Bash**: `curl | bash`, unquoted variables, `chmod 777`

Severity levels: HIGH (blocks deployment), WARN (should fix), INFO (best practice). CI-ready with non-zero exit on HIGH findings.

## Agent Model Tiers

| Model | Purpose | Count |
|-------|---------|-------|
| opus | Complex reasoning, code generation, security | 32 |
| sonnet | Documentation, analysis, pattern-following | 15 |

## Extension Points

### MCP Templates
`app/mcp-templates/` contains 26 ready-to-use MCP server config templates. Opt-in via `ai-toolkit install --modules mcp-templates` or activated automatically with `--profile strict|full`.

### Language Rules
`app/rules/` provides language-specific rule files covering 13 languages (TypeScript, Python, Go, Rust, Java, Kotlin, Swift, Dart, C#, PHP, C++, Ruby, common). Auto-detected from project files via `--auto-detect` or selectable with `--modules rules-<lang>`. See README.md for current count.

### Extension API (`inject-hook`, `inject-rule`)
`inject_section_cli.py` provides a stable marker-based API for injecting content into `CLAUDE.md`, `constitution.md`, or `ARCHITECTURE.md` without overwriting user content. `inject_hook_cli.py` injects hooks into `settings.json` with `_source` tags — supports both local files and HTTPS URLs (cached in `~/.softspark/ai-toolkit/hooks/external/`, auto-refreshed on `update`).

### Manifest Install (`--modules`, `--auto-detect`)
`manifest.json` defines all installable components as named modules. Install individual modules with `ai-toolkit install --modules <name>` or enable auto-detection to select language rules based on files found in the project.

---

## kb/reference/benchmark-config.md

---
title: "AI Toolkit - Config Benchmark"
category: reference
service: ai-toolkit
tags: [benchmark, config, comparison, coverage]
version: "1.0.0"
created: "2026-03-29"
last_updated: "2026-03-29"
description: "Compare your installed ai-toolkit config vs toolkit defaults vs ecosystem competition."
---

# Config Benchmark

## Usage

```bash
ai-toolkit benchmark --my-config
```

## What It Shows

1. **Your Configuration** — counts of installed agents, skills, hooks in `~/.claude/`
2. **Toolkit Totals** — counts of available assets in the toolkit package
3. **Coverage** — percentage of toolkit assets you have installed
4. **Missing Components** — up to 10 agents and skills not yet installed
5. **Ecosystem Comparison** — your config vs public Claude Code ecosystem repos

## Output Example

```
AI Toolkit Config Benchmark
========================

## Your Configuration (~/.claude/)
  Agents:  44
  Skills:  80
  Hooks:   12

## Toolkit Totals
  Agents:  44
  Skills:  80
  Hooks:   12

## Coverage
  Agents:  100%  (44 / 44)
  Skills:  100%  (80 / 80)
  Hooks:   100%  (12 / 12)

## Ecosystem Comparison
Repo                                     Agents  Skills  Hooks
--------------------------------------------------------------
Your config                                  47      80     12
--------------------------------------------------------------
anthropics/claude-code                       15      10      5
affaan-m/everything-claude-code             152     397      2
```

## Data Sources

- User config: `~/.claude/agents/`, `~/.claude/skills/`, `~/.softspark/ai-toolkit/hooks/`
- Toolkit: `app/agents/`, `app/skills/`, `app/hooks/`
- Ecosystem: `benchmarks/ecosystem-dashboard.json`

---

## kb/reference/ci-integration.md

---
title: "AI Toolkit - CI Integration"
category: reference
service: ai-toolkit
tags: [ci, github-actions, automation, validation]
version: "1.0.0"
created: "2026-03-29"
last_updated: "2026-03-29"
description: "Reusable GitHub Action for ai-toolkit validation in CI pipelines."
---

# CI Integration

## GitHub Action

Validate your toolkit setup in CI using the reusable composite action.

### Basic Usage

```yaml
# .github/workflows/validate-toolkit.yml
name: Validate AI Toolkit
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: softspark/ai-toolkit@v1
        with:
          command: validate
```

### Inputs

| Input | Default | Description |
|-------|---------|-------------|
| `toolkit-version` | `latest` | npm version of @softspark/ai-toolkit |
| `node-version` | `20` | Node.js version |
| `command` | `validate` | Command to run (`validate` or `doctor`) |

### Outputs

| Output | Description |
|--------|-------------|
| `status` | `pass` or `fail` |

## Alternative: npx

For simpler setups without the action:

```yaml
      - uses: actions/setup-node@v6
        with:
          node-version: 20
      - run: npx @softspark/ai-toolkit validate
```

## What Gets Validated

- Agent frontmatter (name, description, tools, model)
- Skill frontmatter (name, description, format, references)
- Hook event names against whitelist
- Plugin pack manifests (JSON validity, asset references)
- Metadata contracts (README badges vs actual counts)
- Core file presence (LICENSE, CHANGELOG, SECURITY)

---

## kb/reference/claude-ecosystem-benchmark-snapshot.md

---
title: "Claude Ecosystem Benchmark Snapshot"
category: reference
service: ai-toolkit
tags: [benchmark, ecosystem, claude-code, competitive-analysis, roadmap]
version: "1.0.0"
created: "2026-03-28"
last_updated: "2026-04-01"
description: "Repeatable benchmark snapshot of official Claude Code and selected external repositories used to guide ai-toolkit expansion decisions."
---

# Claude Ecosystem Benchmark Snapshot

## Purpose

This document records the external repositories that `ai-toolkit` uses as benchmark inputs for ecosystem expansion work. It complements the planning documents by turning the benchmark set into a stable, repeatable reference.

## Source Set

- `anthropics/claude-code`
- `affaan-m/everything-claude-code`
- `ChrisWiles/claude-code-showcase`
- `disler/claude-code-hooks-mastery`
- `codeaholicguy/ai-devkit`
- `alirezarezvani/claude-code-skill-factory`

## Snapshot (2026-03-28)

| Repository | Category | Why it matters |
|------------|----------|----------------|
| `anthropics/claude-code` | official | Canonical plugin layout, command development, hook development, feature workflows |
| `affaan-m/everything-claude-code` | ecosystem-scale | Scale benchmark for commands, agents, and packaging patterns |
| `ChrisWiles/claude-code-showcase` | practical-showcase | Strong examples of edit-time automation and branch safety hooks |
| `disler/claude-code-hooks-mastery` | hooks-reference | Strong reference for lifecycle breadth and operational hook patterns |
| `codeaholicguy/ai-devkit` | cross-tool | Cross-tool toolkit positioning benchmark |
| `alirezarezvani/claude-code-skill-factory` | meta-tooling | Creator workflow and factory-style inspiration |

## Operational Use

Use the benchmark script for a repeatable snapshot:

```bash
python3 scripts/benchmark_ecosystem.py --offline
python3 scripts/benchmark_ecosystem.py --format json
python3 scripts/benchmark_ecosystem.py --dashboard-json
python3 scripts/harvest_ecosystem.py --offline
python3 scripts/benchmark_ecosystem.py --out /tmp/claude-ecosystem-benchmark.md
```

The script prefers live GitHub metadata when available and falls back to the embedded snapshot when offline.

Machine-readable artifacts:

- `benchmarks/ecosystem-dashboard.json` — curated dashboard summary with freshness and comparison matrix
- `benchmarks/ecosystem-harvest.json` — latest harvested benchmark JSON for roadmap / changelog reuse

## Adoption Matrix

| Pattern | Current ai-toolkit State | Benchmark Signal | Priority |
|---------|--------------------------|------------------|----------|
| Plugin manifest | Present | Strong in official Claude Code | High |
| Hook creator workflow | Present | Reinforced by official plugin-dev assets | High |
| Command creator workflow | Present | Reinforced by command-development patterns | High |
| Agent creator workflow | Present | Reinforced by agent-development patterns | High |
| Lifecycle breadth (`PreCompact`) | Present | Validated by hooks-focused repos | High |
| Lifecycle breadth (`PostToolUse`) | Present | Strong benchmark signal | High |
| Lifecycle breadth (`UserPromptSubmit`) | Present | Prompt-governance benchmark signal | High |
| Lifecycle breadth (`SubagentStart` / `SubagentStop`) | Present | Strong subagent instrumentation signal | Medium |
| Lifecycle breadth (`SessionEnd`) | Present | Needed for handoff / cleanup patterns | Medium |
| Ecosystem benchmark script | Present | Needed for repeatable comparison | High |
| Harvesting script + dashboard JSON | Present | Repeatable evidence for roadmap and release notes | High |
| Domain plugin packs | Present (experimental) | Validates modular packaging direction | Medium |
| Policy packs | Not yet implemented | Strong but still optional | Later |

## Notes

- This snapshot is intentionally small and curated.
- The goal is decision quality, not ecosystem collection for its own sake.
- Large benchmark repositories are references, not implementation blueprints.


---

## kb/reference/claude-ecosystem-expansion-foundations.md

---
title: "Claude Ecosystem Expansion Foundations"
category: reference
service: ai-toolkit
tags: [benchmark, claude-code, ecosystem, hooks, plugins, architecture]
version: "1.1.0"
created: "2026-03-27"
last_updated: "2026-07-10"
description: "Reference summary of the ecosystem signals and implementation foundations adopted in ai-toolkit, including runtime-aware plugin packaging."
---

# Claude Ecosystem Expansion Foundations

## Purpose

This document captures the architectural foundations adopted in `ai-toolkit` after reviewing:

1. the current toolkit repository,
2. official Claude Code patterns,
3. selected external benchmark repositories.

The outcome is a toolkit that is now positioned as a more modular, Claude-first, benchmark-backed system with stronger lifecycle automation and extension tooling.

## Implemented Foundations

### 1. Plugin-oriented structure

`ai-toolkit` now treats plugin packaging as a first-class capability, with separate runtime-aware surfaces for Claude Code, the Claude Chat/Desktop/Cowork app, and optional global Codex layering.

Implemented artifacts:
- `app/.claude-plugin/plugin.json`
- `app/claude-app/`
- `app/plugins/`
- `app/skills/plugin-creator/SKILL.md`
- `scripts/claude_app.py`
- `kb/reference/plugin-pack-conventions.md`

Claude Code reads filesystem configuration such as `~/.claude/rules` and
`CLAUDE.md`. The Claude app does not scan those locations. For the app,
`ai-toolkit claude-app export --verify` creates an uploadable plugin ZIP and a
separate Cowork global-instructions file. Plugin skills work in Chat and Cowork;
hooks and sub-agents are Cowork-only.

### 2. Broader lifecycle coverage

The toolkit now covers prompt, edit, subagent, compaction, and session-end phases.

Implemented events:
- `SessionStart`
- `Notification`
- `PreToolUse`
- `UserPromptSubmit`
- `PostToolUse`
- `Stop`
- `TaskCompleted`
- `TeammateIdle`
- `SubagentStart`
- `SubagentStop`
- `PreCompact`
- `SessionEnd`

### 3. Creator workflows

The toolkit now includes first-class creator workflows for extension work:
- `hook-creator`
- `command-creator`
- `agent-creator`
- `plugin-creator`

### 4. Benchmark-backed maintenance

External ecosystem research is operationalized through repeatable scripts and machine-readable artifacts.

Implemented artifacts:
- `scripts/benchmark_ecosystem.py`
- `scripts/harvest_ecosystem.py`
- `benchmarks/ecosystem-dashboard.json`
- `benchmarks/ecosystem-harvest.json`
- `kb/reference/claude-ecosystem-benchmark-snapshot.md`

## Benchmark Inputs

The reference benchmark set is intentionally curated:
- `anthropics/claude-code`
- `affaan-m/everything-claude-code`
- `ChrisWiles/claude-code-showcase`
- `disler/claude-code-hooks-mastery`
- `codeaholicguy/ai-devkit`
- `alirezarezvani/claude-code-skill-factory`

## Adopted Outcomes

| Area | Adopted in ai-toolkit |
|------|------------------------|
| Plugin manifests | Yes |
| Claude Chat/Cowork uploadable plugin export | Yes |
| Domain plugin packs | Yes (experimental) |
| Hook creator workflow | Yes |
| Command creator workflow | Yes |
| Agent creator workflow | Yes |
| Plugin creator workflow | Yes |
| Post-edit feedback hooks | Yes |
| Prompt governance hook | Yes |
| Subagent lifecycle hooks | Yes |
| Session-end handoff | Yes |
| Benchmark dashboard JSON | Yes |
| Harvesting workflow | Yes |

## Current Position

`ai-toolkit` is now documented and implemented as a complete, production-ready toolkit baseline rather than a staged roadmap. Future changes should be treated as normal product evolution, not backlog catch-up.

---

## kb/reference/cli-reference.md

---
title: "CLI Reference"
category: reference
service: ai-toolkit
tags: [cli, commands, reference, install, update, plugin, mcp, telemetry]
created: "2026-04-13"
last_updated: "2026-07-26"
description: "Complete CLI reference for all ai-toolkit commands, options, and flags."
---

# CLI Reference

```
Usage: ai-toolkit <command> [options]
```

## Core Commands

| Command | Description |
|---------|-------------|
| `install` | First-time global install into `~/.claude/` + Cursor, Windsurf, Gemini |
| `install --local` | Claude Code configs only; add `--editors all` or `--editors cursor,aider` for other tools |
| `update` | Re-apply toolkit after `npm install -g @softspark/ai-toolkit@latest` |
| `update --local` | Re-apply + auto-detect editors from existing project files |
| `reset --local` | Wipe all project-local configs and recreate from scratch (clean slate) |
| `status` | Show installed modules and version |
| `uninstall` | Remove toolkit from `~/.claude/` |
| `validate` | Verify toolkit integrity (`--strict` for CI-grade, warnings = errors) |
| `doctor` | Diagnose install health, hooks, quick-win assets, and artifact drift |
| `doctor --fix` | Auto-repair broken symlinks, missing hooks, stale artifacts |
| `eject [dir]` | Export standalone config (no symlinks, no toolkit dependency) |
| `claude-app export [--output FILE] [--no-custom-rules] [--verify]` | Build an uploadable Claude Chat/Desktop/Cowork plugin ZIP and global-instructions file |
| `claude-app verify` | Validate a clean staged plugin with structural checks and the official Claude plugin validator |

## Rule & Hook Injection

| Command | Description |
|---------|-------------|
| `add-rule <rule.md\|url> [name]` | Register rule in `~/.softspark/ai-toolkit/rules/` — auto-applied on every `update` |
| `remove-rule <name> [dir]` | Unregister rule and remove its block from `CLAUDE.md` |
| `inject-hook <file.json\|url> [name]` | Inject external hooks (file or URL) into settings.json (idempotent, `_source` tagged, URL hooks auto-refresh on update) |
| `remove-hook <name>` | Remove injected hooks by source name (also unregisters URL source if present) |

## MCP Management

| Command | Description |
|---------|-------------|
| `mcp list` | List available MCP server templates (26 templates) |
| `mcp editors` | List editors with native MCP config adapters and scopes |
| `mcp add <name> [names...]` | Add MCP server template(s) to `.mcp.json` |
| `mcp install --editor <name[,..]> [names...]` | Install templates into native editor MCP config |
| `mcp show <name>` | Show MCP template config details |
| `mcp remove <name>` | Remove MCP server from `.mcp.json` or editor MCP config |

## Plugin Management

| Command | Description |
|---------|-------------|
| `plugin list` | Show available plugin packs with install status |
| `plugin install <name> [--editor claude\|codex\|all]` | Install a plugin pack for Claude Code and/or Codex (`claude` means Claude Code, not the Claude app) |
| `plugin install --all [--editor claude\|codex\|all]` | Install all 12 plugin packs |
| `plugin update <name> [--editor claude\|codex\|all]` | Update a plugin pack (remove + reinstall, preserves data) |
| `plugin update --all [--editor claude\|codex\|all]` | Update all installed plugin packs |
| `plugin clean <name> [--days N]` | Prune old plugin data (default: 90 days) |
| `plugin remove <name> [--editor claude\|codex\|all]` | Remove a plugin pack |
| `plugin status [--editor claude\|codex\|all]` | Show installed plugins with runtime-specific details |

## Config Inheritance

| Command | Description |
|---------|-------------|
| `config validate [path]` | Validate `.softspark-toolkit.json` schema + extends + enforcement |
| `config diff [path]` | Show project vs base config differences |
| `config init [flags]` | Create `.softspark-toolkit.json` (`--extends`, `--profile`, `--no-extends`) |
| `config create-base <name>` | Scaffold base config npm package |
| `config check [path]` | CI enforcement gate (exit 0=pass, 1=fail, 2=no config; `--json`) |

## Native Tool-Output Filter

| Command | Description |
|---------|-------------|

`AI_TOOLKIT_OUTPUT_FILTER_DISABLE=1` bypasses active filtering immediately.

## Project Registry

| Command | Description |
|---------|-------------|
| `projects` | List registered projects |
| `projects --prune` | Remove stale (deleted) entries |
| `projects remove /path` | Unregister specific project |

## Generator Commands

| Command | Description |
|---------|-------------|
| `generate-all` | Generate all platform configs at once |
| `agents-md` | Regenerate `AGENTS.md` from agent definitions |
| `codex-md` | Generate `AGENTS.md` (coding rules inlined) with marker injection for Codex CLI |
| `codex-hooks` | Generate `.codex/hooks.json` for Codex CLI |
| `cursor-rules` | Generate `.cursorrules` (legacy single file) |
| `cursor-mdc` | Generate `.cursor/rules/*.mdc` (recommended) |
| `windsurf-rules` | Generate `.windsurfrules` (legacy) |
| `windsurf-dir-rules` | Generate `.windsurf/rules/*.md` (recommended) |
| `copilot-instructions` | Generate `.github/copilot-instructions.md` |
| `gemini-md` | Generate `GEMINI.md` for Gemini CLI |
| `cline-rules` | Generate `.clinerules` (legacy) |
| `cline-dir-rules` | Generate `.clinerules/*.md` (recommended) |
| `roo-modes` | Generate `.roomodes` |
| `roo-dir-rules` | Generate `.roo/rules/*.md` |
| `aider-conf` | Generate `.aider.conf.yml` |
| `conventions-md` | Generate `CONVENTIONS.md` for Aider |
| `augment-rules` | Generate `.augment/rules/ai-toolkit.md` (legacy) |
| `augment-dir-rules` | Generate `.augment/rules/ai-toolkit-*.md` (recommended) |
| `antigravity-rules` | Generate `.agents/rules/` and `.agents/workflows/` |
| `llms-txt` | Generate `llms.txt` and `llms-full.txt` |

## Other Commands

| Command | Description |
|---------|-------------|
| `stats` | Show skill usage statistics (`--summary` for product telemetry, `--reset` to clear, `--json` for raw output) |
| `benchmark --my-config` | Compare your config vs defaults vs ecosystem |
| `benchmark-ecosystem` | Generate ecosystem benchmark snapshot |
| `create skill <name>` | Scaffold new skill from template (`--template=linter\|reviewer\|generator\|workflow\|knowledge`) |
| `sync` | Config portability via GitHub Gist (`--export`, `--push`, `--pull`, `--import`) |
| `compile-slm` | Compile toolkit into minimal SLM system prompt (`--budget`, `--model-size`, `--dry-run`) |
| `evaluate` | Run skill evaluation suite |

### `stats`

```bash
ai-toolkit stats                 # table of local skill usage
ai-toolkit stats --summary       # product telemetry summary
ai-toolkit stats --summary --json  # machine-readable telemetry
ai-toolkit stats --reset         # clear local stats
```

`--summary` reports total invocations, unique skills used, catalog coverage, unused catalog skills, active skills in the last 7 days, and top skills. Data stays local in `~/.softspark/ai-toolkit/stats.json`.

## Install / Update Options

```bash
ai-toolkit install --only agents,hooks          # apply only listed components
ai-toolkit install --skip hooks                 # skip listed components
ai-toolkit install --profile minimal            # minimal | standard | strict
ai-toolkit install --persona backend-lead       # backend-lead | frontend-lead | devops-eng | junior-dev
ai-toolkit install --local --editors all        # Claude Code + all editors
ai-toolkit install --local --editors cursor,aider  # + specific editors
ai-toolkit install --local --lang typescript    # explicit language rules
ai-toolkit install --modules core,agents,rules-typescript  # selective modules
ai-toolkit install --list                       # dry-run: show what would change
ai-toolkit update --local                       # auto-detects editors from existing files
```

---

## kb/reference/codex-cli-compatibility.md

---
title: "AI Toolkit - Codex CLI Compatibility"
category: reference
service: ai-toolkit
tags: [codex, compatibility, install, skills, hooks]
version: "1.0.4"
created: "2026-04-12"
last_updated: "2026-07-14"
description: "Reference for how ai-toolkit maps Claude-oriented skills, hooks, and plugin packs to Codex CLI."
---

# AI Toolkit - Codex CLI Compatibility

## Summary

Codex CLI now receives the full `ai-toolkit` skill catalog during local install.

Native Codex-compatible skills are linked directly into `.agents/skills/`.
Skills that contain Claude-only tools, prompt placeholders, or skill-directory
variables are generated as Codex wrappers. The wrappers preserve workflow intent
using semantic subagent and planning guidance instead of version-specific tool
signatures.

Experimental plugin packs can also target the Codex user surface with
`ai-toolkit plugin install --editor codex`, which layers plugin-specific skills,
rules, and hooks onto the active `CODEX_HOME` without changing project-local
configuration.

## Local Install Outputs

`ai-toolkit install --local --editors codex` generates:

- `AGENTS.md` (project root; universal coding rules inlined — Codex reads instructions only from AGENTS.md, not `.agents/rules/`)
- `.agents/skills/*`
- `.codex/hooks.json`
- `.codex/hooks/*` (self-contained executable hook assets)
- `.codex/agents/*.toml`
- `.codex/config.toml` when project MCP servers are selected

Project-local Codex paths never follow `CODEX_HOME`; the variable selects the
user configuration root only.

## Global Core Install Outputs

`ai-toolkit install --editors codex` writes Codex-owned user files below the
active `CODEX_HOME` (default `~/.codex`):

- `$CODEX_HOME/AGENTS.md`
- `$CODEX_HOME/agents/*.toml`
- `$CODEX_HOME/hooks.json`
- `$CODEX_HOME/ai-toolkit-hooks/*`

The portable user skill catalog intentionally remains under
`$HOME/.agents/skills/*`. This is Codex's documented shared user-skill discovery
path, not a Codex-owned config-root path. A configured `CODEX_HOME` must be an
existing absolute directory; the installer preserves user guidance, custom
agents, and unrelated hook handlers inside it.

Sources: [Codex environment variables](https://learn.chatgpt.com/codex/config-file/environment-variables),
[AGENTS.md discovery](https://learn.chatgpt.com/codex/agent-configuration/agents-md),
[Codex skills](https://developers.openai.com/codex/skills).

## Global Plugin Outputs

`ai-toolkit plugin install --editor codex <pack>` bootstraps or reuses:

- `$CODEX_HOME/AGENTS.md` (default `~/.codex/AGENTS.md`; pack rules are marker-injected here, not written as unread `.agents/rules/` files)
- `$HOME/.agents/skills/*`
- `$CODEX_HOME/hooks.json`
- `$CODEX_HOME/ai-toolkit-hooks/*`

Plugin packs only add their own runtime-specific layer on top of the generated
Codex base. Codex hooks no longer depend on executable paths under
`~/.softspark/ai-toolkit/`; project assets live beside `.codex/hooks.json`, and
user assets live under `$CODEX_HOME/ai-toolkit-hooks/`.

## Skill Translation Model

Two delivery modes are used for Codex:

| Mode | How it is installed | Use case |
|------|----------------------|----------|
| Native | Symlink to `app/skills/<name>/` | Skills with portable tools, prompts, and paths |
| Adapted | Generated wrapper directory in `.agents/skills/<name>/` | Skills with Claude-only tools, prompt placeholders, path variables, or orchestration APIs |

Adapted skills keep the same support assets (`reference/`, `scripts/`, `assets/`)
via symlinks, but rewrite `SKILL.md` to Codex-native guidance.

## Claude-to-Codex Semantic Mapping

The adapter deliberately avoids embedding runtime function names or guessed
signatures. Generated guidance describes stable intent:

| Claude-oriented concept | Codex guidance |
|-------------------------|----------------|
| Delegated agent call | Delegate a narrow task to a suitable Codex-native subagent |
| Agent redirection | Use the subagent controls available in the current client |
| Task bookkeeping | Use the planning mechanism available in the current client or an explicit checklist |
| Waiting for a task | Wait only when the next critical-path step depends on the delegated result |
| Agent teams | Coordinate subagents with explicit, non-overlapping ownership |
| Prompt input placeholder | Use the task details supplied by the user |
| Claude skill-directory variable | Use the installed skill directory containing `SKILL.md` |

## Adapted Skill Classes

The adapted group includes multi-agent orchestration:

- `/orchestrate`
- `/workflow`
- `/swarm`
- `/subagent-development`

It also includes any skill that contains Claude-only prompt or path variables,
even when its tool list is otherwise portable. Examples include:

- `/tdd`
- `/write-a-prd`
- `/qa-session`
- `/triage-issue`
- `/architecture-audit`
- `/build`
- `/cve-scan`

## Hook Compatibility

Codex does not expose the full Claude hook event surface. Codex's
`HookEventName` enum defines 10 events; the Codex hook generator wires 9 of
them:

- `SessionStart`
- `PreToolUse`
- `PostToolUse`
- `PermissionRequest`
- `UserPromptSubmit`
- `SubagentStart`
- `SubagentStop`
- `PreCompact`
- `Stop`

`PostCompact` is the one enum event left unwired (its only hook was the removed
environment-snapshot probe). Claude-only events such as `TaskCompleted`,
`TeammateIdle`, `SessionEnd`, and `Notification` have no Codex equivalent and
are not available in `.codex/hooks.json`. Handler types: only `command` runs;
`prompt` and `agent` are parsed by Codex but not yet executed.

The generator merges these Codex-compatible events into project or user
`hooks.json`, preserving unrelated user handlers and replacing only commands
marked as ai-toolkit-owned. Project commands resolve their assets from the git
root; core user commands use `$CODEX_HOME/ai-toolkit-hooks/`.

Hook JSON is parsed from the snapshot held by the same secure transaction that
writes generated handlers, installs executable assets, and removes stale
managed assets. A failure in any of those stages rolls back the whole upgrade.
Existing file permissions are retained; new `hooks.json` files use a secure
`0600` base filtered by umask, while new executable hook assets are explicitly
installed as `0755`.

After installation or any hook change, open `/hooks` in Codex and review/trust
the exact definitions. Project hooks additionally require a trusted `.codex`
project layer. The installer never bypasses hook trust.

Generated Codex hook commands include `AI_TOOLKIT_HOOK_QUIET=1`. Native
`SessionStart`, `PreCompact`, and MCP-health adapters use Codex instruction and
config terminology (`AGENTS.md`, `.codex/config.toml`) instead of Claude-only
paths. The generated
`UserPromptSubmit` governance hook does not set `AI_TOOLKIT_HOOK_FORMAT=json`
by default because Codex currently renders `additionalContext` as visible hook
context in the TUI. This keeps prompt-submit output quiet while preserving hook
side effects and blocking decisions such as search-first Stop enforcement.

Codex hooks must not force Claude-only JSON output fields such as
`suppressOutput`. In particular, advisory `PostToolUse` hooks like
`loop-guard.sh` run in quiet/plain mode under Codex; they keep side effects but
do not emit hidden Claude-style context unless a future Codex runtime explicitly
supports that schema.

If a future Codex runtime enables JSON context output for `UserPromptSubmit`,
the output must be event-specific and include the event name alongside the
context:

```json
{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "..."
  }
}
```

Older `{"hookSpecificOutput":{"additionalContext":"..."}}` output can be valid
JSON but fail newer Codex event-output validation.

Plain-text informational hook context is also silent by default in the shared
hook helper. Set `AI_TOOLKIT_HOOK_VERBOSE=1` only when debugging hook output
outside the Codex UI.

## MCP Configuration

Codex MCP servers are supported at both documented scopes:

- project: `.codex/config.toml` (trusted project layers only)
- user: `$CODEX_HOME/config.toml` (default `~/.codex/config.toml`)

The adapter renders `[mcp_servers.<name>]` for STDIO and Streamable HTTP
transports. It validates documented transport, timeout, tool-filter, and
approval fields, preserves unrelated TOML bytes/comments, and owns only its
marker-bounded block. Invalid TOML and symlinked roots are rejected unchanged.

## Behavioral Limits

Codex wrappers preserve workflow intent, but not every Claude runtime behavior
has a perfect one-to-one equivalent.

Known limits:

- No native Codex equivalent of tmux-backed Agent Teams lifecycle events
- No separate task object model equivalent to Claude `Task*` APIs
- Hook event coverage is narrower than Claude Code
- MCP search tool calls may not fire the shared `PostToolUse` search tracker,
  so `stop-search-check.sh` also checks `$CODEX_HOME/log/codex-tui.log` (default
  `~/.codex/log/codex-tui.log`) for
  `smart_query`, `hybrid_search_kb`, `crag_search`, `multi_hop_search`, and
  `verify_answer` calls after the search-first flag timestamp before blocking.
  The scan is bounded to a recent log window, but sized to tolerate noisy Codex
  skill-loader output between the search call and the Stop hook.

These are runtime platform limits, not installation defects.

## Verification

The Codex compatibility path is verified by:

1. Generator contract tests for `generate_codex.py`
2. Local install tests for `.agents/skills/` and `.codex/hooks.json`
3. Plugin install tests for global Codex rules, hooks, and cleanup paths
4. CLI tests for `codex-md` and `codex-hooks`

## Related

- `kb/reference/skills-catalog.md`
- `kb/reference/architecture-overview.md`
- `kb/reference/global-install-model.md`
- `kb/reference/copilot-compatibility.md`

---

## kb/reference/comparison.md

---
title: "Ecosystem Comparison"
category: reference
service: ai-toolkit
tags: [comparison, ecosystem, features, alternatives]
created: "2026-04-13"
last_updated: "2026-04-13"
description: "Feature comparison of ai-toolkit vs other Claude Code toolkits and agent frameworks."
---

# Ecosystem Comparison

| Feature | ai-toolkit | everything-claude-code | wshobson/agents | ruflo |
|---------|---------------|----------------------|-----------------|-------|
| Skills | 93 | 100+ | 146 | 20+ |
| Agents | 44 | 30+ | 112 | 20+ |
| Machine-enforced constitution | **Yes** | No (docs only) | No | No |
| Skill-scoped lifecycle hooks | **Yes** | No | No | No |
| Effort-based model budgeting | **Yes** | No | No | No |
| Test suite | Yes (bats) | Yes (997 tests) | No | Yes |
| npm/npx install | Yes | Yes | Yes | Yes |
| Cross-tool support | **Cursor, Windsurf, Copilot, Gemini, Cline, Roo, Aider, Augment, Antigravity, Codex** | 5+ tools | Smithery | Limited |
| Selective install | Yes | Yes | Yes (72 plugins) | No |
| Session persistence | Yes | Yes | No | No |
| Architecture notes | **Yes** | No | No | No |
| KB/RAG integration | **Yes** | No | No | Yes |
| License | **Apache-2.0** (NOTICE attribution, change notices, patent grant) | MIT | MIT | MIT |

For live benchmark data, see the [ecosystem benchmark snapshot](claude-ecosystem-benchmark-snapshot.md).

---

## kb/reference/competitive-features-implementation.md

---
title: "Plan: Competitive Features Implementation — Learning System, Language Rules, Hook Matrix, MCP Templates"
category: reference
service: ai-toolkit
tags:
  - competitive-analysis
  - continuous-learning
  - language-rules
  - hook-matrix
  - mcp-templates
  - install-profiles
  - completed
doc_type: plan
status: completed
created: "2026-04-07"
last_updated: "2026-04-24"
completion: "100%"
description: "Implementation plan for features identified from competitive analysis of everything-claude-code and claude-mem. Focus on learning system, language rules, advanced hooks, MCP templates, and rag-mcp integration. COMPLETED: 8/9 features shipped (1 skipped). See kb/reference/ for permanent documentation."
---

# Plan: Competitive Features — ai-toolkit

**Status:** :white_check_mark: COMPLETED
**Completion:** 100% (8/9 features, 1 skipped)
**Started:** 2026-04-07
**Estimated Completion:** 2026-06-15
**Source:** Competitive analysis of `affaan-m/everything-claude-code` (ECC) + `thedotmack/claude-mem`

---

## 1. Objective

Strengthen ai-toolkit's competitive position by implementing 10 features from competitive analysis while maintaining our advantages (clean architecture, 11 editors, personas, safety constitution).

**Key design principle:** ai-toolkit is a **generic toolkit** — it does NOT know about rag-mcp or any specific consumer. Consumers (like rag-mcp) use ai-toolkit's public API (`inject-rule`, `inject-hook`, `merge-hooks`) to add their own rules and hooks.

**State before plan:** 88 skills, 47 agents, 14 hooks, 9 editor integrations
**State after plan:** See manifest.json and README.md for current counts. Target: skills, agents, hooks, language rules, MCP templates, extension API

---

## 2. Progress Tracking

| # | Feature | Priority | Status | Est. Time | Actual | Notes |
|---|---------|----------|--------|-----------|--------|-------|
| 1.1 | Language-Specific Rules (13 langs) | P0 | :white_check_mark: | 5-7d | 1d | 70 files (13 langs × 5 + 5 common) |
| 1.2 | Advanced Hook Matrix | P0 | :white_check_mark: | 5-7d | 1d | 6 new hooks + hooks.json |
| 1.3 | MCP Server Templates (25) | P0 | :white_check_mark: | 2-3d | 1d | 25 templates + mcp_manager.py + CLI |
| 2.1 | `inject-hook` CLI command | P1 | :white_check_mark: | 3-5d | 1d | inject_hook_cli.py + 17 tests + CLI |
| 2.2 | Manifest-Driven Install | P1 | :white_check_mark: | 7-10d | 1d | modules, state tracking, auto-detect |
| 3.1 | Council Skill | P2 | :white_check_mark: | 3-5d | 1d | /council (4-perspective orchestrator) |
| 3.2 | Brand Voice Skill | P2 | :white_check_mark: | 2-3d | 1d | knowledge skill + anti-trope list |
| 3.3 | Agent Introspection Skill | P2 | :white_check_mark: | 3-5d | 1d | /introspect (7 failure patterns) |
| 4.1 | Documentation Site (Starlight/Astro) | P3 | :no_entry: SKIPPED | — | — | Unnecessary — README/CLAUDE.md sufficient |

---

## 3. Dependency Graph

```
ALL FEATURES ARE INDEPENDENT — no external dependencies

MCP Templates (1.3) ← quick win, start here
Language Rules (1.1) ← independent
Hook Matrix (1.2) ← independent
inject-hook CLI (2.1) ← independent (extends existing inject-rule pattern)
Manifest Install (2.2) ← independent but complex
Council Skill (3.1) ← independent
Brand Voice (3.2) ← independent
Agent Introspection (3.3) ← independent
Documentation Site (4.1) ← independent
```

---

## 4. Detailed Implementation

### Faza 1: Quick Wins + Foundation (tydzień 1-2)

#### 1.1 Language-Specific Rules System

**Source:** ECC — 13 language dirs × 5 files each = 65 rule files
**What we create:** Skill-based language rules that inject into CLAUDE.md via `--local`

**Current state:** We have `app/skills/` with some language patterns (typescript-patterns, ruby-patterns, etc.)
**Gap:** No systematic coding-style + testing + security + hooks + patterns per language

**Files to create:**

```
app/rules/
├── common/
│   ├── coding-style.md          # KISS, DRY, YAGNI, immutability
│   ├── testing.md               # Testing standards
│   ├── git-workflow.md          # Commit conventions
│   ├── performance.md           # Performance guidelines
│   └── security.md              # OWASP, input validation
├── typescript/
│   ├── coding-style.md          # TS-specific (strict mode, no any, etc.)
│   ├── testing.md               # Jest/Vitest patterns
│   ├── patterns.md              # TS patterns (discriminated unions, etc.)
│   ├── hooks.md                 # React hooks, lifecycle
│   └── security.md              # XSS, sanitization
├── python/
│   ├── coding-style.md          # PEP 8, type hints, dataclasses
│   ├── testing.md               # pytest, fixtures, parametrize
│   ├── patterns.md              # Python patterns
│   ├── hooks.md                 # Django/FastAPI lifecycle
│   └── security.md              # SQL injection, SSTI
├── golang/                      # Same 5-file structure
├── rust/
├── java/
├── kotlin/
├── swift/
├── dart/
├── csharp/
├── php/
├── cpp/
└── ruby/
```

**Total: 13 languages × 5 files + 5 common = 70 files**

**Integration with install:**
```bash
# During ai-toolkit install --local
# Detect project language from package.json, Cargo.toml, go.mod, etc.
# Inject relevant language rules into CLAUDE.md
```

**Files to modify:**

| File | Action | Description |
|------|--------|-------------|
| `app/rules/` (70 files) | CREATE | Language-specific rules |
| `scripts/install_steps/detect_language.py` | CREATE | Auto-detect project language |
| `scripts/install_steps/inject_rules.py` | EDIT | Inject language rules into CLAUDE.md |
| `scripts/validate.py` | EDIT | Validate rules format |
| `tests/test_rules.py` | CREATE | Tests |

**Success Criteria:**
- [x] 13 languages × 5 rule files created (70 files: 13 dirs × 5 + 5 common)
- [x] `ai-toolkit install --local` auto-detects language and injects rules (two-phase: marker files + extension scan)
- [x] Manual override: `ai-toolkit install --local --lang typescript` (with aliases: go→golang, c++→cpp, cs→csharp)
- [x] validate.py checks rules format
- [x] Tests: dedicated `tests/test_rules.bats`

---

#### 1.2 Advanced Hook Matrix

**Source:** ECC — 11+ specific hooks with PreToolUse/PostToolUse matrix
**Current state:** 14 hooks in `app/hooks/`
**Gap:** Missing specific hooks for config protection, MCP health, governance, continuous learning

**New hooks to add:**

| Hook | Event | Script | Purpose |
|------|-------|--------|---------|
| `guard-config.sh` | PreToolUse (Edit/Write) | Bash | Block edits to .eslintrc, .prettierrc, tsconfig unless explicit |
| `mcp-health.sh` | SessionStart | Bash | Check MCP server health before session |
| `governance-capture.sh` | PostToolUse | Bash | Log governance events (security, policy) |
| `observe-session.sh` | PostToolUse | Bash | Send observations to rag-mcp (bridge) |
| `pre-compact-save.sh` | PreCompact | Bash | Save context state before compaction |
| `commit-quality.sh` | PreToolUse (Bash) | Bash | Check commit message quality |

**Files:**

| File | Action | Description |
|------|--------|-------------|
| `app/hooks/guard-config.sh` | CREATE | Config file protection |
| `app/hooks/mcp-health.sh` | CREATE | MCP server health check |
| `app/hooks/governance-capture.sh` | CREATE | Governance event logging |
| `app/hooks/observe-session.sh` | CREATE | Send obs to rag-mcp |
| `app/hooks/pre-compact-save.sh` | CREATE | Context save before compact |
| `app/hooks/commit-quality.sh` | CREATE | Commit message quality |
| `scripts/install_steps/install_hooks.py` | EDIT | Register new hooks |
| `tests/test_hooks.py` | EDIT | Tests for new hooks |

**Success Criteria:**
- [x] 5/6 new hooks created and registerable (observe-session.sh not in app/hooks — lives in rag-mcp as consumer)
- [x] guard-config blocks config edits unless `--force`
- [x] mcp-health pings configured MCP servers on session start
- [x] All hooks optional (enable/disable in settings.json)
- [x] Tests: 89 hook tests in test_hooks.bats

---

#### 1.3 MCP Server Templates

**Source:** ECC — 25 preconfigured MCP servers
**What we create:** Template configs that users can copy

**File to create:**
```
app/mcp-templates/
├── README.md                    # How to use templates
├── github.json                  # GitHub MCP server
├── jira.json                    # Jira MCP server
├── context7.json                # Context7 docs
├── filesystem.json              # Filesystem MCP server
├── sequential-thinking.json     # Sequential thinking
├── exa-search.json              # Exa web search
├── supabase.json                # Supabase
├── postgres.json                # PostgreSQL
├── redis.json                   # Redis
├── cloudflare.json              # Cloudflare
├── vercel.json                  # Vercel
├── railway.json                 # Railway
├── docker.json                  # Docker
├── browser-use.json             # Browser automation
├── fal-ai.json                  # fal.ai (image/video)
├── firecrawl.json               # Web scraping
├── sentry.json                  # Sentry error tracking
├── linear.json                  # Linear issue tracker
├── slack.json                   # Slack
├── notion.json                  # Notion
├── confluence.json              # Confluence
├── grafana.json                 # Grafana
├── datadog.json                 # Datadog
└── custom-template.json         # Template for custom MCP
```

**CLI command:**
```bash
ai-toolkit mcp add github          # Copy github.json to .mcp.json
ai-toolkit mcp add github jira     # Add multiple
ai-toolkit mcp list                 # List available templates
ai-toolkit mcp show github         # Show config details
```

**Files:**

| File | Action | Description |
|------|--------|-------------|
| `app/mcp-templates/` (25 files) | CREATE | MCP configs |
| `bin/ai-toolkit` | EDIT | Add `mcp` subcommand |
| `scripts/mcp_manager.py` | CREATE | MCP template manager |
| `tests/test_mcp_templates.py` | CREATE | Validate JSON schemas |

**Success Criteria:**
- [x] 25 MCP template configs created
- [x] `ai-toolkit mcp add <name>` merges into .mcp.json
- [x] `ai-toolkit mcp list` shows all available
- [x] Tests: 15 in test_mcp_manager.bats

---

### Faza 2: Extension API + Install (tydzień 3-5)

#### 2.1 `inject-hook` CLI Command (Generic Hook Injection)

**Purpose:** Allow ANY external tool to inject hooks into `~/.claude/settings.json` — the same way `inject-rule` works for `~/.claude/CLAUDE.md`. This is the missing piece that enables consumers (rag-mcp, custom tools, CI systems) to register hooks without knowing ai-toolkit internals.

**Current state:**
- `inject-rule ./my-rules.md` → injects rules into CLAUDE.md between `<!-- TOOLKIT:my-rules START/END -->` markers
- `merge-hooks.py inject <hooks.json> <settings.json>` → merges hooks but ONLY with `_source: "ai-toolkit"` tag
- **Gap:** No public CLI for external tools to inject hooks with their OWN `_source` tag

**Architecture (parallels inject-rule):**
```
inject-rule ./rag-mcp-rules.md          → CLAUDE.md      (markers: <!-- TOOLKIT:rag-mcp-rules -->)
inject-hook ./rag-mcp-hooks.json        → settings.json  (tag: "_source": "rag-mcp-hooks")
remove-rule rag-mcp-rules               → strips from CLAUDE.md
remove-hook rag-mcp-hooks               → strips from settings.json
```

**Example: rag-mcp consuming this API:**
```bash
# rag-mcp creates a hooks file:
cat > /tmp/rag-mcp-hooks.json << 'EOF'
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "echo 'apply KB-first research'" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "$HOME/.rag-mcp/hooks/observe-session.sh" }]
      }
    ],
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "$HOME/.rag-mcp/hooks/inject-instincts.sh" }]
      }
    ]
  }
}
EOF

# rag-mcp calls ai-toolkit to inject:
npx @softspark/ai-toolkit inject-hook /tmp/rag-mcp-hooks.json
# → all entries tagged with _source: "rag-mcp-hooks" in settings.json
# → re-running is idempotent (strips old rag-mcp-hooks entries, appends new)

# rag-mcp removes its hooks:
npx @softspark/ai-toolkit remove-hook rag-mcp-hooks
```

**Files:**

| File | Action | Description |
|------|--------|-------------|
| `scripts/inject_hook_cli.py` | CREATE | CLI: inject-hook / remove-hook |
| `scripts/merge-hooks.py` | EDIT | Support custom `_source` tag (not just "ai-toolkit") |
| `bin/ai-toolkit.js` | EDIT | Register `inject-hook` + `remove-hook` subcommands |
| `tests/test_inject_hook.bats` | CREATE | Tests |
| `kb/howto/inject-hook-api.md` | CREATE | Documentation for consumers |

**merge-hooks.py changes:**
```python
# Current: always uses SOURCE_TAG = "ai-toolkit"
# New: accept --source parameter
SOURCE_TAG = "ai-toolkit"  # default

def cmd_inject(toolkit_path: str, target_path: str, source: str = "") -> None:
    source_tag = source or derive_source_from_filename(toolkit_path)
    # ... tag all entries with _source: source_tag
    # ... strip old entries with same source_tag
    # ... append new entries
```

**inject_hook_cli.py:**
```python
#!/usr/bin/env python3
"""Inject external hooks into ~/.claude/settings.json.

Usage:
  inject_hook_cli.py <hooks-file.json> [target-dir]
  inject_hook_cli.py --remove <hook-source-name> [target-dir]

The source name is derived from the filename stem (e.g., rag-mcp-hooks.json → "rag-mcp-hooks").
All entries are tagged with "_source": "<source-name>" for idempotent updates.
"""
```

**Consistency table — all ai-toolkit extension commands:**

| Command | Target File | Mechanism | Idempotent |
|---------|------------|-----------|------------|
| `inject-rule <file.md>` | `~/.claude/CLAUDE.md` | HTML markers (`<!-- TOOLKIT:name -->`) | Yes |
| `remove-rule <name>` | `~/.claude/CLAUDE.md` | Strip markers | Yes |
| `inject-hook <file.json>` | `~/.claude/settings.json` | JSON `_source` tag | Yes |
| `remove-hook <name>` | `~/.claude/settings.json` | Strip by `_source` | Yes |
| `add-rule <file.md>` | `~/.softspark/ai-toolkit/rules/` | File copy + re-inject all | Yes |

**Success Criteria:**
- [x] `inject-hook ./my-hooks.json` merges hooks with auto-derived `_source` tag
- [x] `remove-hook my-hooks` strips all entries with that `_source`
- [x] Re-running is idempotent (update, not duplicate)
- [x] Existing ai-toolkit hooks (`_source: "ai-toolkit"`) are never touched
- [x] Tests: 17 in test_inject_hook.bats

---

#### 2.2 Manifest-Driven Install System

**Source:** ECC — JSON manifests, state tracking, 5 profiles
**Current state:** Simple profile-based install (minimal/standard/strict)
**Gap:** No granular module selection, no state tracking, no incremental updates

**Files:**

| File | Action | Description |
|------|--------|-------------|
| `manifest.json` | EDIT | Full module manifest with dependencies |
| `scripts/install_steps/install_plan.py` | CREATE | Plan what to install |
| `scripts/install_steps/install_apply.py` | CREATE | Execute install plan |
| `scripts/install_steps/install_state.py` | CREATE | Track installed modules |
| `tests/test_manifest_install.py` | CREATE | Tests |

**manifest.json structure:**
```json
{
  "modules": {
    "core": {
      "description": "Core skills and hooks",
      "files": ["app/skills/commit/*", "app/skills/review/*", "app/hooks/*.sh"],
      "required": true
    },
    "agents": {
      "description": "Specialized agents",
      "files": ["app/agents/*.md"],
      "required": false,
      "default": true
    },
    "rules-common": {
      "description": "Common coding rules",
      "files": ["app/rules/common/*.md"],
      "required": false,
      "default": true
    },
    "rules-typescript": {
      "description": "TypeScript-specific rules",
      "files": ["app/rules/typescript/*.md"],
      "auto_detect": "package.json"
    },
    "rules-python": {
      "description": "Python-specific rules",
      "files": ["app/rules/python/*.md"],
      "auto_detect": "requirements.txt|pyproject.toml|setup.py"
    },
    "mcp-templates": {
      "description": "MCP server templates",
      "files": ["app/mcp-templates/*.json"],
      "required": false
    },
    "rag-mcp-bridge": {
      "description": "rag-mcp integration hooks",
      "files": ["app/hooks/observe-session.sh", "scripts/config/rag-mcp-bridge.yaml"],
      "required": false,
      "requires": ["core"]
    }
  },
  "profiles": {
    "minimal": ["core"],
    "standard": ["core", "agents", "rules-common"],
    "strict": ["core", "agents", "rules-common", "mcp-templates"],
    "full": ["*"]
  }
}
```

**State tracking (~/.softspark/ai-toolkit/state.json):**
```json
{
  "installed_version": "1.2.1",
  "installed_modules": ["core", "agents", "rules-common", "rules-typescript"],
  "installed_at": "2026-04-07T10:00:00Z",
  "last_updated": "2026-04-07T10:00:00Z",
  "file_hashes": {
    "app/hooks/session-start.sh": "abc123..."
  }
}
```

**CLI:**
```bash
ai-toolkit install --profile standard          # Profile-based (existing)
ai-toolkit install --modules core,agents       # Module-based (new)
ai-toolkit install --auto-detect               # Detect language, install matching rules
ai-toolkit update                              # Incremental update (only changed files)
ai-toolkit status                              # Show installed modules
```

**Success Criteria:**
- [x] manifest.json defines all modules with dependencies
- [x] install --modules allows granular selection
- [x] install --auto-detect detects language from project files (two-phase: markers + extensions)
- [x] state.json tracks what's installed
- [x] update only changes modified files (content hash)
- [x] Backward compatible with existing install
- [x] Tests: 35 across test_install.bats, test_install_flags.bats, test_install_state.bats

---

### Faza 3: New Skills (tydzień 6-7)

#### 3.1 Council Skill (/council)

**Source:** ECC — 4-voice decision workflow
**Type:** Hybrid skill (user-invocable: true)

**File:** `app/skills/council/SKILL.md`

**Skill definition:**
```yaml
---
name: council
description: "4-perspective decision evaluation for architecture choices"
user-invocable: true
agent: orchestrator
context: fork
---
```

**Behavior:**
1. User invokes `/council "Should we migrate from Redis to Valkey?"`
2. Spawn 4 sub-agents in parallel:
   - **Advocate:** Strongest case FOR
   - **Critic:** Strongest case AGAINST (devil's advocate)
   - **Pragmatist:** Trade-offs, costs, timeline, team capacity
   - **User-Proxy:** End-user/customer impact
3. Synthesize into structured output:
   - Pros (from Advocate)
   - Cons (from Critic)
   - Trade-offs (from Pragmatist)
   - User Impact (from User-Proxy)
   - **Recommendation** with confidence level

**Success Criteria:**
- [x] `/council` invocable
- [x] 4 perspectives generated
- [x] Structured output with recommendation
- [x] Tests: dedicated council skill contract

---

#### 3.2 Brand Voice Skill (/brand-voice)

**Source:** ECC — canonical voice system
**Type:** Knowledge skill (user-invocable: false, auto-loaded for writing tasks)

**File:** `app/skills/brand-voice/SKILL.md`

**Content:**
- Anti-trope list (banned LLM phrases: "dive into", "game-changer", "cutting-edge", etc.)
- Voice capture template (how to define a project's voice)
- Consistency checks (before outputting content, verify voice match)

**Success Criteria:**
- [x] Skill auto-loads when writing docs/content
- [x] Anti-trope list prevents generic LLM rhetoric
- [x] Tests: dedicated brand-voice skill contract

---

#### 3.3 Agent Introspection Skill (/introspect)

**Source:** ECC — agent-introspection-debugging
**Type:** Task skill (user-invocable: true)

**File:** `app/skills/introspect/SKILL.md`

**Behavior:**
1. Capture current failure/stuck state
2. Classify pattern (loop, wrong approach, missing context, etc.)
3. Suggest smallest recovery action
4. Emit structured introspection report
5. Optionally hand off to verification

**Success Criteria:**
- [x] `/introspect` invocable when agent is stuck
- [x] Classifies failure pattern
- [x] Suggests recovery action
- [x] Tests: dedicated introspect skill contract

---

### Faza 4: Documentation & Marketing (tydzień 8)

#### 4.1 Documentation Site

**Source:** claude-mem (Mintlify, 27 languages)
**Options:**
1. **Starlight (Astro)** — free, static, fast (recommended)
2. **Mintlify** — paid, beautiful, hosted
3. **Docusaurus** — free, React-based

**Structure:**
```
docs/
├── astro.config.mjs
├── src/content/docs/
│   ├── getting-started/
│   │   ├── installation.md
│   │   ├── quick-start.md
│   │   └── first-skill.md
│   ├── skills/
│   │   ├── tier-1.md
│   │   ├── tier-2.md
│   │   └── tier-3.md
│   ├── agents/
│   │   └── catalog.md
│   ├── hooks/
│   │   └── lifecycle.md
│   ├── guides/
│   │   ├── create-skill.md
│   │   ├── create-agent.md
│   │   └── rag-mcp-integration.md
│   └── reference/
│       ├── cli.md
│       └── manifest.md
```

**Success Criteria:**
- :no_entry: SKIPPED — README/CLAUDE.md sufficient, no documentation site needed

---

## 5. Extension API Design (Generic — No Consumer Knowledge)

ai-toolkit provides a **generic extension API**. It does NOT know about any specific consumer. Consumers use the public CLI to register their rules and hooks.

```
┌──────────────────────────────────────────────────────┐
│                   ai-toolkit (generic)                │
│                                                      │
│  Public Extension API:                               │
│    inject-rule  <file.md>     → CLAUDE.md            │
│    remove-rule  <name>        → CLAUDE.md            │
│    inject-hook  <file.json>   → settings.json  [NEW] │
│    remove-hook  <name>        → settings.json  [NEW] │
│    add-rule     <file.md>     → rules/ registry      │
│    mcp add      <template>    → .mcp.json      [NEW] │
│                                                      │
│  Idempotent: markers (rules) / _source tags (hooks)  │
│  ai-toolkit NEVER calls external services            │
└──────────────────────────────────────────────────────┘
                        ▲
                        │ uses API
        ┌───────────────┼───────────────┐
        │               │               │
   rag-mcp          custom-tool     ci-system
   (consumer)       (consumer)      (consumer)
```

**Example: how rag-mcp would consume (handled in rag-mcp repo, NOT here):**
```bash
# rag-mcp install script calls:
npx @softspark/ai-toolkit inject-rule  ./rag-mcp-rules.md      # existing
npx @softspark/ai-toolkit inject-hook  ./rag-mcp-hooks.json    # NEW
# → rag-mcp's hooks + rules are registered, ai-toolkit doesn't care what they do
```

---

## 6. Success Criteria (Overall)

| Metric | Before | Target |
|--------|--------|--------|
| Skills | 88 | ~91 (+3 new skills) |
| Hooks | 14 | 21 (+7, observe-session in rag-mcp) |
| Language rules | ~8 (pattern skills) | 70 (13 langs × 5 + 5 common) |
| MCP templates | 0 | 25 |
| Install granularity | 3 profiles | 3 profiles + module-level |
| Extension API | inject-rule only | inject-rule + inject-hook + mcp add |
| Documentation | README only | Published site |

---

## 7. Risks and Mitigation

| Risk | Probability | Impact | Mitigation |
|------|-------------|--------|------------|
| Rule files = maintenance burden | Medium | Medium | Auto-generate from ECC (port script), validate.py checks |
| inject-hook misuse by consumers | Low | Medium | Validate JSON schema, reject malformed hooks |
| Manifest install breaks existing | Low | High | Backward compatible, existing CLI preserved |
| Documentation site drift | Medium | Medium | Generate from source (CLAUDE.md → site), CI check |
| Too many hooks slow session start | Low | Medium | Hooks run async, timeout 5s each |

---

## 8. Pre-Mortem

1. **Language rules become stale** — Mitigation: version in frontmatter, validate.py checks freshness
2. **inject-hook consumers conflict** — Mitigation: each consumer has unique `_source` tag, never collide
3. **Manifest install confuses users** — Mitigation: `--profile` still works, manifest is opt-in power feature
4. **Council skill too slow** — Mitigation: parallel sub-agents, timeout 60s per perspective
5. **Documentation out of sync** — Mitigation: CI job: generate docs → diff → fail if stale

---

## 9. Remaining Gaps

All major features shipped. Outstanding items:

1. [x] `validate.py` checks rules format (1.1)
2. [x] Dedicated `test_rules` test file exists (1.1)
3. [x] Dedicated tests exist for council, brand-voice, introspect skills (3.1-3.3)
4. [x] `observe-session.sh` lives in rag-mcp (consumer), not ai-toolkit — by design

---

## 10. Blockers

None — all features are independent of external systems.

---

**Last Updated:** 2026-04-09

---

## kb/reference/copilot-compatibility.md

---
title: "AI Toolkit - GitHub Copilot Compatibility"
category: reference
service: ai-toolkit
tags: [copilot, compatibility, install, skills, prompts, instructions, agents, hooks]
version: "1.0.0"
created: "2026-07-15"
last_updated: "2026-07-15"
description: "Reference for how ai-toolkit integrates with GitHub Copilot — the five .github/ surfaces, their runtime context-loading semantics, and why the same skill is emitted as both a prompt file and a skill directory."
---

# AI Toolkit - GitHub Copilot Compatibility

## Summary

`ai-toolkit install --local --editors copilot` emits native GitHub Copilot
customization files under `.github/`. Copilot is the toolkit's widest-surface
editor target: a single skill can materialize into up to three distinct Copilot
mechanisms (path-scoped instruction, invokable prompt, on-demand skill). All
emitted paths are generated build artifacts and are `.gitignore`d — they are not
committed source. This document explains what each surface is, **when each one
enters the model context**, and why the same skill body appears in more than one
file. Install/profile behavior is owned by `kb/reference/global-install-model.md`;
config-path and capability tracking by `kb/reference/supported-tools-registry.md`.

## Generated Surfaces

| Surface | Path | Copilot mechanism |
|---------|------|-------------------|
| Repo-wide instructions | `.github/copilot-instructions.md` | Always-on repository custom instructions |
| Path-scoped instructions | `.github/instructions/ai-toolkit-*.instructions.md` | Custom instructions gated by an `applyTo` glob |
| Prompt files | `.github/prompts/ai-toolkit-*.prompt.md` | Reusable prompts, invoked as `/name` |
| Native agents | `.github/agents/ai-toolkit-*.agent.md` | Custom agents in the agent picker |
| Portable skills | `.github/skills/ai-toolkit-*/SKILL.md` (+ `reference/`, `scripts/`) | Agent Skills, injected on demand |
| Lifecycle hooks | `.github/hooks/ai-toolkit.json` + runtime | Version-1 Copilot hooks (profile ≥ `standard`) |
| Shared rules | root `AGENTS.md` | Read by Copilot code review and CLI |

## Surface Loading Semantics

The five customization surfaces do **not** all cost context the same way. This
is the practical difference that governs token usage and any perceived
"double loading":

| Surface | Enters context… | Passive cost |
|---------|-----------------|--------------|
| `copilot-instructions.md` | Every chat request in the repo | Always-on |
| `*.instructions.md` with `applyTo: "**"` | Every request (glob matches all files) | Effectively always-on |
| `*.instructions.md` with a scoped glob (e.g. `**/*.py`) | Only when a matching file is in context | Path-scoped |
| `*.prompt.md` | **Only** when the user runs `/<name>` | None until invoked |
| `SKILL.md` | **Only** when Copilot chooses to use the skill (progressive disclosure) | None until triggered |
| `*.agent.md` | Only when that agent is selected in the picker | None until selected |

Instructions are auto-added to requests as soon as their `applyTo` glob matches;
skills and prompts are pull-based, never injected passively.

## Prompt ↔ Skill Duplication

Every user-invocable skill is emitted **both** as a `.github/prompts/*.prompt.md`
(so it is available as a `/slash-command`) **and** as a
`.github/skills/<name>/SKILL.md` directory (so Copilot can auto-trigger it with
its bundled `scripts/` and `reference/` assets). The two bodies are byte-identical
after their frontmatter and Copilot execution-notes header; the differences are:

- the prompt carries only a `description`; the skill adds `name` and bundles the
  runnable assets the prompt does not ship;
- the prompt's execution note treats the current request as task input, the
  skill's note resolves relative paths against its own directory.

**This is intentional, not a stale leftover, and does not cause a persistent
double-load:**

- Neither surface is always-on. The prompt loads only on explicit `/invoke`; the
  skill loads only on trigger. Neither sits in `copilot-instructions.md` or in an
  always-matching `applyTo`, so the shared body carries **zero** passive context
  cost.
- The same skill is registered from a **single** root (`.github/skills`), not
  duplicated across `.claude/skills` or `.agents/skills` in the same repo, so
  there is no duplicate skill registration.
- The one edge case is a single turn where the user runs `/<name>` **and** Copilot
  autonomously pulls the matching skill in the same request. That is a one-shot
  redundancy of identical text — wasted tokens for that turn only, with no
  conflicting instructions and no persistent effect.

Neither surface can replace the other: the prompt has no bundled scanner or
reference material, and the skill directory is not exposed as a slash command.
The body is duplicated so each surface is self-contained.

## Compatibility Read Paths

Copilot also discovers project `.claude/skills` and `.agents/skills`, and
personal `~/.agents/skills`. ai-toolkit still materializes self-contained native
skills under `.github/skills` (and under the active Copilot config root for
global installs) so that bundled assets and helper scripts remain available and
`COPILOT_HOME` sessions do not depend on fallback discovery. The toolkit does not
write the same skill into two roots at once, so fallback discovery never produces
a duplicate registration.

## Generated, Git-Ignored Artifacts

All Copilot outputs are build products, regenerated on every install/generate,
and listed in `.gitignore`:

- `.github/copilot-instructions.md`
- `.github/instructions/`
- `.github/prompts/`
- `.github/agents/`
- `.github/skills/`
- `.github/hooks/`

Deleting them locally is safe (they are untracked and ignored); the next
`ai-toolkit install --editors copilot` or generator run recreates them. The
generator also cleans stale managed entries and byte-exact historical ai-toolkit
files while preserving user-authored files.

## Install & Profiles

Authoritative behavior lives in `kb/reference/global-install-model.md`. In brief:

- **All profiles (including `minimal`)** emit root `AGENTS.md`,
  `.github/copilot-instructions.md`, native `.github/agents`, and portable
  self-contained `.github/skills`.
- **`standard`, `strict`, `full`** additionally emit scoped `.github/instructions`,
  `.github/prompts`, and native version-1 `.github/hooks`.
- **`minimal`** omits instructions, prompts, and hooks.

Moving an existing project down to `minimal` removes only marked or byte-exact
historical ai-toolkit instructions/prompts/hooks; unmanaged project files stay.

## Auto-Detection

The installer treats Copilot as configured when any of these markers exist:
`.github/copilot-instructions.md`, `.github/instructions`, `.github/prompts`,
`.github/agents`, `.github/skills`, `.github/hooks`, `.github/mcp.json`.
`ai-toolkit update` then picks up Copilot automatically.

## Generators & CLI

Copilot has no dedicated `ai-toolkit copilot-*` subcommand; it is produced by
`ai-toolkit install --editors copilot` (add `--local` for project scope) or by
running the generators directly:

- `scripts/generate_copilot.py` — instructions, prompts, native agents, and
  portable skill directories (`> .github/copilot-instructions.md` with no target
  argument; multi-surface emission with a target directory).
- `scripts/generate_copilot_hooks.py` — version-1 hook config plus a
  self-contained repository/config-root runtime.

## Behavioral Limits

- Prompt files are available only in VS Code, Visual Studio, and JetBrains IDEs;
  GitHub.com and the CLI use instructions, skills, agents, and `AGENTS.md`.
- Custom agents emit native `.agent.md` with `name` and `description`; `tools` is
  omitted rather than guessing editor-specific aliases.
- Prompt and skill bodies strip Claude-only interpolation (`$ARGUMENTS`,
  `CLAUDE_SKILL_DIR`) and delegation APIs; hooks use the GitHub version-1 schema
  with camelCase event names.

## Verification

- `scripts/generate_copilot.py` / `generate_copilot_hooks.py` contract tests
  (`tests/test_copilot.bats`, `tests/test_copilot_hooks.bats`).
- Release layout check in `kb/procedures/release-verification-sop.md` asserts the
  `.github/{agents,skills,instructions,prompts,hooks}` surfaces.
- `validate.py --strict` + `audit_skills.py --ci` in CI.

## Related

- `kb/reference/global-install-model.md`
- `kb/reference/supported-tools-registry.md`
- `kb/reference/codex-cli-compatibility.md`
- `kb/reference/opencode-compatibility.md`
- `kb/reference/skills-catalog.md`
- `kb/reference/agents-catalog.md`

---

## kb/reference/distribution-model.md

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

# Distribution Model

## Summary

`ai-toolkit` uses a split delivery model:

- **npm package** for delivery to the machine,
- **filesystem symlinks and merged files** for propagation into Claude Code directories.

```text
npm install -g @softspark/ai-toolkit   → delivers toolkit files
ai-toolkit install                     → links / merges into ~/.claude/
```

## Why this model exists

The toolkit must be reusable across many projects while remaining easy to update from one place.

This model gives:
- standard installation and versioning,
- instant propagation for symlinked assets,
- predictable update flow for merged / copied assets,
- one source of truth per machine.

## Adopted Strategies

| Layer | Mechanism | Result |
|------|-----------|--------|
| Delivery | npm package | standard install / update UX |
| Agents | per-file symlinks | zero-overhead propagation |
| Skills | per-directory symlinks | zero-overhead propagation |
| Hooks | copied scripts + merged JSON | safe runtime integration |
| Docs / rules | marker injection | user content preserved |

## Trade-offs

### Positive
- easy installation
- clear update path
- global reuse across projects
- low propagation overhead

### Negative
- symlink targets depend on a valid global install location
- merged / copied assets require `ai-toolkit update` after source changes
- all projects on a machine share the same installed toolkit version

## Related Documents

- `kb/reference/global-install-model.md`
- `kb/reference/merge-friendly-install-model.md`
- `kb/reference/architecture-overview.md`

---

## kb/reference/enterprise-config-guide.md

---
title: "Enterprise Config Inheritance Guide"
category: reference
service: ai-toolkit
tags:
  - enterprise
  - config-inheritance
  - extends
  - governance
  - multi-repo
doc_type: reference
created: "2026-04-11"
last_updated: "2026-07-26"
description: "Comprehensive guide for setting up and using ai-toolkit configuration inheritance. Covers base config creation, project setup, enforcement rules, CI integration, and troubleshooting."
---

# Enterprise Config Inheritance Guide

## Overview

Configuration inheritance enables organizations to define a shared base config published as an npm package, Git URL, or local path. Individual projects extend this base via an `extends` field in `.softspark-toolkit.json`. Changes to the base propagate automatically on `ai-toolkit update --local`.

**Pattern:** Mirrors ESLint's `extends`, TypeScript's `extends`, and Prettier's shared configs.

---

## Quick Start

### 1. Create a base config (team lead)

```bash
ai-toolkit config create-base @mycompany/ai-toolkit-config
cd mycompany-ai-toolkit-config

# Edit ai-toolkit.config.json — add your org's rules, agents, enforcement
# Add rule files to rules/
# Add custom agent definitions to agents/

npm publish
```

### 2. Set up a project (developer)

```bash
cd my-project
ai-toolkit config init --extends @mycompany/ai-toolkit-config
ai-toolkit install --local
```

Or manually create `.softspark-toolkit.json`:

```json
{
  "extends": "@mycompany/ai-toolkit-config",
  "profile": "standard",
  "agents": {
    "enabled": ["frontend-specialist"]
  }
}
```

### 3. Verify

```bash
ai-toolkit config validate    # Schema + extends + enforcement
ai-toolkit config diff        # Show differences from base
ai-toolkit config check       # CI enforcement check
```

---

## Configuration Reference

### Project config (`.softspark-toolkit.json`)

| Field | Type | Description |
|-------|------|-------------|
| `extends` | string | Base config source (npm, git URL, local path) |
| `profile` | enum | `minimal`, `standard`, `strict`, `full`, `offline-slm` |
| `agents` | object | `enabled`, `disabled`, `custom` arrays |
| `plugins` | object | Resolved `enabled` and `disabled` plugin intent |
| `rules` | object | `inject`, `remove` arrays |
| `constitution` | object | `amendments` array (article 8+ only) |
| `enforce` | object | Non-overridable constraints (base configs only) |
| `overrides` | object | Explicit overrides with justification |

### Base config (`ai-toolkit.config.json`)

Same fields as project config, plus:

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Package identity (required) |
| `version` | string | Semver version (required) |

### Extends sources

| Source | Syntax | Example |
|--------|--------|---------|
| npm package | `"@scope/pkg"` | `"@mycompany/ai-toolkit-config"` |
| npm + version | `"@scope/pkg@version"` | `"@mycompany/ai-toolkit-config@^2.0.0"` |
| Git URL | `"git+https://..."` | `"git+https://github.com/myco/config.git"` |
| Local path | `"./path"` or `"../path"` | `"../shared-config"` |

---

## Merge Semantics

When a project extends a base, configs are merged with these rules:

| Type | Rule |
|------|------|
| **Dicts** | Recursive deep merge |
| **Lists** | Union (base + project, deduplicated) |
| **Scalars** | Project wins |
| **Agents** | Union enabled, project can disable (unless required) |
| **Rules** | Union inject, project can remove |
| **Constitution** | Base articles immutable, project adds only (8+) |
| **Enforce** | Base wins (cannot weaken, only strengthen) |
| **Profile** | Project can change |

### Merge order (multi-level)

```
grandparent → parent → project
```

Deepest ancestor is resolved first. Max chain depth: 5 levels.

---

## Enforcement

Base configs can define non-overridable constraints via the `enforce` block:

```json
{
  "enforce": {
    "minHookProfile": "standard",
    "requiredPlugins": ["memory-pack"],
    "forbidOverride": ["constitution", "guard-destructive"],
    "requiredAgents": ["security-auditor"]
  }
}
```

| Constraint | Effect |
|------------|--------|
| `minHookProfile` | Projects cannot use a weaker hook profile |
| `requiredPlugins` | Adds each required name to the effective `plugins.enabled` intent and prevents projects from disabling it |
| `forbidOverride` | These components cannot be overridden |
| `requiredAgents` | Must be enabled in all projects |

`requiredPlugins` is configuration enforcement, not an installer. It makes the
effective intent explicit and causes validation to reject a conflicting
`plugins.disabled` entry. Install the named plugin pack separately with
`ai-toolkit plugin install <name>` or your organization deployment workflow.

### Overrides

Projects can override base settings, but must declare intent:

```json
{
  "overrides": {
    "quality-check": {
      "override": true,
      "justification": "Company uses custom lint pipeline via Jenkins",
      "replacement": "skip"
    }
  }
}
```

Requirements:
- `override: true` must be explicit
- `justification` must be at least 20 characters
- Component must not be in `enforce.forbidOverride`

---

## Constitution Immutability

- **Articles I-VII** (toolkit core) are absolutely immutable
- **Base config articles** are immutable — projects cannot modify them
- Projects can **only ADD** new articles (article 8+)

```json
{
  "constitution": {
    "amendments": [
      {"article": 8, "title": "API Standards", "text": "All APIs must be RESTful."}
    ]
  }
}
```

---

## CLI Commands

### `ai-toolkit config validate [path]`

Validates `.softspark-toolkit.json` schema, resolves extends, checks enforcement.

```bash
ai-toolkit config validate
# ✓ schema valid
# ✓ extends resolved: 1 base config(s)
# ✓ no forbidden overrides
# ✓ constitution articles intact
```

### `ai-toolkit config diff [path]`

Shows differences between project config and base.

```bash
ai-toolkit config diff
# Base: @mycompany/ai-toolkit-config@2.1.0
# Profile:     strict (base) → standard (project) ⚠ OVERRIDE
# Agents:
#   + frontend-specialist     (project adds)
#   = security-auditor        (base requires, cannot disable)
```

### `ai-toolkit config init [flags]`

Create `.softspark-toolkit.json` interactively or with flags.

```bash
ai-toolkit config init                                    # interactive
ai-toolkit config init --extends @mycompany/config        # with extends
ai-toolkit config init --no-extends --profile standard    # without extends
ai-toolkit config init --force                            # overwrite existing
```

### `ai-toolkit config create-base <name> [output-dir]`

Scaffold a base config npm package.

```bash
ai-toolkit config create-base @mycompany/ai-toolkit-config
# Creates: mycompany-ai-toolkit-config/
#   package.json, ai-toolkit.config.json, rules/, agents/, README.md
```

### `ai-toolkit config check [path] [--json]`

CI enforcement check. Exit codes: 0 (pass), 1 (fail), 2 (no config).

```bash
ai-toolkit config check --json
# {"status": "pass", "code": 0, "checks": [...]}
```

GitHub Actions example:

```yaml
- name: AI Toolkit Governance Check
  run: |
    npx @softspark/ai-toolkit config check --json
    npx @softspark/ai-toolkit config validate --strict
```

---

## Lock File

`.softspark-toolkit.lock.json` pins exact resolved versions for reproducible installs.

- `install --local` → creates/updates lock file
- `update --local` → re-resolves and updates lock file
- `update --local --refresh-base` → force re-fetch ignoring cache
- Commit `.softspark-toolkit.lock.json` to git for team synchronization

```json
{
  "lockfileVersion": 1,
  "resolved": {
    "@mycompany/ai-toolkit-config": {
      "version": "2.1.0",
      "integrity": "sha256:abc123...",
      "cached": "~/.softspark/ai-toolkit/config-cache/@mycompany/ai-toolkit-config/2.1.0/"
    }
  }
}
```

---

## Offline Support

When npm/git is unavailable:

1. Checks cache (`~/.softspark/ai-toolkit/config-cache/`)
2. If cached version found → uses with warning
3. If not cached → error with instructions

```bash
# Force refresh when back online:
ai-toolkit update --local --refresh-base
```

---

## Troubleshooting

### "Cannot resolve extends"

- Check network connectivity
- Verify npm package name is correct
- For private packages, ensure `.npmrc` has auth configured
- Try `--refresh-base` to clear cache

### "Cannot disable agent — required by base config"

The base config's `enforce.requiredAgents` prevents disabling this agent.
Contact your team lead to request an exemption.

### "Cannot modify Constitution Article X"

Base constitution articles are immutable. You can only ADD new articles with higher numbers.

### "Override requires justification"

All overrides need `"override": true` and a `"justification"` field (min 20 chars).

### "Circular extends detected"

Your extends chain has a loop. Check that base configs don't reference each other cyclically. Max depth is 5 levels.

### Lock file stale

Run `ai-toolkit update --local` to re-resolve and update the lock file.

---

## kb/reference/extension-api.md

---
title: "Extension API Reference"
category: reference
service: ai-toolkit
tags: [extension-api, inject-rule, inject-hook, inject-mcp, mcp-templates, integration, editors]
version: "1.8.0"
created: "2026-04-07"
last_updated: "2026-07-14"
description: "Reference for ai-toolkit's extension API: inject-rule, inject-hook, inject-mcp, remove-* variants, and editor-aware MCP template management."
---

# Extension API Reference

## Overview

ai-toolkit exposes a generic extension API that lets external tools register their own rules and hooks alongside the toolkit's built-in components. The toolkit has no knowledge of any specific consumer — it only provides the injection mechanism. Consumers call the public CLI commands from their own install scripts.

This design is intentional: ai-toolkit is a generic toolkit. Consumers (MCP servers, CI systems, custom tools) use the public API to add their own rules and hooks without modifying toolkit internals.

## Commands

| Command | Target File | Mechanism | Idempotent |
|---------|-------------|-----------|------------|
| `inject-rule <file.md>` | `~/.claude/CLAUDE.md` | Legacy HTML comment markers (`<!-- TOOLKIT:name -->`) | Yes |
| `remove-rule <name>` | `~/.softspark/ai-toolkit/rules/` + `~/.claude/rules/` | Unregister and remove generated Claude rule file | Yes |
| `inject-hook <file.json\|url> [name]` | `~/.claude/settings.json` + `$CODEX_HOME/hooks.json` | Claude `_source` ownership plus native Codex command translation | Yes |
| `remove-hook <name>` | `~/.claude/settings.json` + `$CODEX_HOME/hooks.json` | Strip exact source ownership in both schemas, unregister URL source | Yes |
| `inject-mcp <file.json\|url> [name] [--force]` | `~/.mcp.json` + every editor with `global_path` | JSON `_source` tag per server, URL cached + registered, full editor propagation | Yes |
| `remove-mcp <name>` | `~/.mcp.json` + every editor with `global_path` | Strip all servers with matching `_source`, clean editor configs, unregister URL | Yes |
| `add-rule <file.md\|url>` | `~/.softspark/ai-toolkit/rules/` | File copy + sync to `~/.claude/rules/ai-toolkit-registered-*.md` on next `update` | Yes |
| `mcp add <name...>` | `.mcp.json` | Merge `mcpServers` block from built-in template | Yes |
| `mcp install --editor <name...>` | Native editor MCP config | Render canonical template into editor format | Yes |

## inject-rule

Legacy direct injection: injects a Markdown rules file into `~/.claude/CLAUDE.md` between named HTML comment markers. Prefer `add-rule` for persistent global rules; `ai-toolkit update` syncs those into Claude Code user-level rule files under `~/.claude/rules/`.

```bash
npx @softspark/ai-toolkit inject-rule ./my-tool-rules.md
```

**Implementation:** `scripts/inject_rule_cli.py` (delegates to `inject_section_cli.py`).

**Markers written:**
```html
<!-- TOOLKIT:my-tool-rules START -->
... content of my-tool-rules.md ...
<!-- TOOLKIT:my-tool-rules END -->
```

The block name is derived from the file stem (`my-tool-rules.md` → `my-tool-rules`). Re-running replaces the existing block — no duplicates. Content outside these markers is never modified.

## remove-rule

Unregisters a persistent rule, removes `~/.claude/rules/ai-toolkit-registered-<name>.md`, and strips any legacy injected rule block from `~/.claude/CLAUDE.md`.

```bash
npx @softspark/ai-toolkit remove-rule my-tool-rules
```

The argument is the block name (file stem used during `inject-rule`). If the block is not present, the command exits 0 silently.

## inject-hook

Injects hook entries from a JSON file or HTTPS URL into `~/.claude/settings.json`. Every injected entry is tagged with `"_source": "<source-name>"` where the source name is derived from the filename stem or URL last segment.

```bash
# From local file
npx @softspark/ai-toolkit inject-hook ./my-tool-hooks.json

# From URL (HTTPS only) — cached locally, auto-refreshed on update
npx @softspark/ai-toolkit inject-hook https://example.com/my-tool-hooks.json

# With explicit source name
npx @softspark/ai-toolkit inject-hook https://example.com/hooks.json my-tool-hooks

# Local source name plus explicit target directory
npx @softspark/ai-toolkit inject-hook ./hooks.json my-tool-hooks /custom/target
```

**Implementation:** `scripts/inject_hook_cli.py`, `scripts/hook_sources.py`, `scripts/url_fetch.py`.

**Input format:**
```json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "$HOME/.my-tool/hooks/on-start.sh" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "$HOME/.my-tool/hooks/on-edit.sh" }]
      }
    ]
  }
}
```

**Source name derivation:** `my-tool-hooks.json` → source name `"my-tool-hooks"`. For URLs: `https://example.com/path/my-tool-hooks.json` → `"my-tool-hooks"`. All entries are tagged `"_source": "my-tool-hooks"` in settings.json.

**URL support:** When an HTTPS URL is provided, the JSON is fetched, validated, cached in `~/.softspark/ai-toolkit/hooks/external/<name>.json`, and registered in `sources.json`. On every `ai-toolkit update`, URL-sourced hooks are re-fetched and re-injected automatically. If the fetch fails during update, the cached version is used.

**Idempotency:** Re-running strips all existing entries with the same source name, then appends the new ones. No duplicates accumulate.

**Safety:** Entries tagged `"_source": "ai-toolkit"` are never modified or
removed by this command. External tools cannot affect the toolkit's own hooks.
Only HTTPS URLs are accepted. Claude settings, the source registry/cache, and
Codex hooks are parsed from the byte snapshots captured after their trusted
roots and parent directories are pinned. Every create, write, replace, unlink,
and rollback runs relative to those descriptors with `O_NOFOLLOW`; a swapped
ancestor cannot redirect the transaction, and an inode change after snapshot
capture aborts instead of overwriting concurrent work. A later failure restores
every touched file byte-for-byte. Existing file modes are preserved. New JSON
configuration files are created with a secure `0600` base filtered by the
current umask. Mutation requires POSIX `dir_fd` support. Native Windows Python
fails closed before changing any file; use WSL for `inject-hook` and
`remove-hook`. Read-only parsing and validation remain available.

**Codex propagation:** command handlers for Codex's 10 documented events are
translated into the native schema and merged into `$CODEX_HOME/hooks.json`
(default `~/.codex/hooks.json`). The translated document never contains
Claude's private `_source` key. Each command carries an exact, collision-resistant
`AI_TOOLKIT_HOOK_OWNER=ai-toolkit-external-<source>-<digest>` marker; update and
remove operations match only that owner. Existing core, plugin, and user
handlers are preserved through the same validator and atomic writer used by the
Codex generator.

Only fields shared unambiguously by native command hooks are propagated:
`matcher`, `type: command`, `command`, `commandWindows`, `timeout`,
`statusMessage`, and `async`. Unsupported events, non-command handlers, and
schema-specific extra fields are reported as skipped instead of being guessed.
`command` must be non-empty. `timeout`, when present, is a positive integer in
seconds; Codex defaults it to 600 seconds when omitted.
`UserPromptSubmit` and `Stop` matchers are omitted only when empty; a non-empty
matcher is skipped because Codex does not support it. `CODEX_HOME` must be an
existing absolute non-symlink directory when configured.

## remove-hook

Strips all hook entries from `~/.claude/settings.json` that carry a given
`_source` tag and removes only the matching native command owner from the active
Codex `hooks.json`. If the hook was URL-sourced, it also unregisters the URL
from `sources.json` and removes the cached file.

```bash
npx @softspark/ai-toolkit remove-hook my-tool-hooks
```

The argument is the source name (file stem used during `inject-hook`). If no entries with that source are present, the command exits 0 silently.

## inject-mcp

Injects an external MCP server template into `~/.mcp.json` (toolkit source-of-truth) and propagates it to every editor that exposes a `global_path` in `EDITOR_SPECS`. Symmetric with `inject-hook` -- accepts both local file paths and HTTPS URLs, with cache + auto-refresh on `ai-toolkit update`.

```bash
# From local file
npx @softspark/ai-toolkit inject-mcp ./rag-mcp-template.json

# From URL (cached locally, auto-refreshed on update)
npx @softspark/ai-toolkit inject-mcp https://example.com/rag-mcp-template.json

# With explicit source name (preferred when filename stem is generic)
npx @softspark/ai-toolkit inject-mcp ./mcp/mcp-template.json --name rag-mcp

# With explicit target dir
npx @softspark/ai-toolkit inject-mcp ./template.json /custom/target --name my-rag

# Force overwrite of servers with a different _source (collision resolution)
npx @softspark/ai-toolkit inject-mcp ./conflict.json --force
```

**Flags:** `--name <name>` overrides the auto-derived source name (works for both local files and URLs). `--force` overwrites servers tagged with a different `_source`. Positional `template-name` is supported only for URL sources (legacy positional grammar inherited from `inject-hook`); for local files use `--name`.

**Implementation:** `scripts/inject_mcp_cli.py`, `scripts/mcp_sources.py`, `scripts/url_fetch.py`.

**Input format:** Same as built-in templates in `app/mcp-templates/`:
```json
{
  "name": "rag-mcp",
  "description": "Multi-tenant RAG over knowledge bases",
  "mcpServers": {
    "rag-mcp": {
      "type": "http",
      "url": "http://localhost:8081/mcp/sse?secret_key=${RAG_MCP_SECRET_KEY}"
    }
  }
}
```

**Source name derivation:** `rag-mcp-template.json` → `"rag-mcp-template"`. For URLs: `https://example.com/rag-mcp-template.json` → `"rag-mcp-template"`. Every server in the `mcpServers` block is tagged with `"_source": "<source-name>"` inside `~/.mcp.json` only; native editor configs receive the same servers **without** the `_source` field (some clients reject unknown keys).

**URL support:** When an HTTPS URL is provided, the JSON is fetched, validated, cached in `~/.softspark/ai-toolkit/mcp-templates/external/<name>.json`, and registered in `sources.json`. On every `ai-toolkit update`, URL-sourced templates are re-fetched and re-injected automatically. If the fetch fails during update, the cached version is used.

**Editor propagation:** Every editor with a `global_path` in `EDITOR_SPECS` is
updated: Claude (`~/.claude.json`), Cursor (`~/.cursor/mcp.json`), GitHub
Copilot (`$COPILOT_HOME/mcp-config.json`, default
`~/.copilot/mcp-config.json`), Gemini CLI (`~/.gemini/settings.json`), Windsurf
(`~/.codeium/windsurf/mcp_config.json`), Cline
(`~/.cline/data/settings/cline_mcp_settings.json`), Augment
(`~/.augment/settings.json`), and Codex CLI (`$CODEX_HOME/config.toml`, default
`~/.codex/config.toml`). Per-editor failures are non-fatal; the command reports
a warning and continues.

**Idempotency:** Re-running with the same source overwrites entries for that source cleanly -- no duplicates accumulate.

**Collisions:** If a server name in `~/.mcp.json` already exists under a *different* `_source` tag, the command exits with code 3 unless `--force` is passed. Entries tagged `"_source": "ai-toolkit"` are protected even with `--force` -- the built-in template namespace cannot be hijacked.

**Safety:** Only HTTPS URLs are accepted. The source name `ai-toolkit` is reserved.

## remove-mcp

Strips all server entries from `~/.mcp.json` that carry a given `_source` tag, cleans the same server names from every editor `global_path`, and (if URL-sourced) unregisters from `sources.json` and removes the cached file.

```bash
npx @softspark/ai-toolkit remove-mcp rag-mcp-template
```

The argument is the source name (file stem used during `inject-mcp`). If no entries with that source are present, the command exits 0 silently. `ai-toolkit` source is reserved and cannot be removed via this command.

## mcp add / install

Merges one or more MCP server templates from `app/mcp-templates/` into the project's `.mcp.json`.

```bash
ai-toolkit mcp add github                # add a single template
ai-toolkit mcp add github postgres slack  # add multiple at once
ai-toolkit mcp list                       # list all available templates
ai-toolkit mcp editors                    # list supported native adapters
ai-toolkit mcp show github                # print a template's JSON
ai-toolkit mcp install --editor cursor --scope project github --target .
ai-toolkit mcp install --editor codex context7
ai-toolkit mcp remove github             # remove an entry from .mcp.json
ai-toolkit mcp remove github --editor cursor --scope project --target .
```

**Implementation:** `scripts/mcp_manager.py`.

The `add` command merges the `mcpServers` block from the template into `.mcp.json`. If `.mcp.json` does not exist, it is created. If the server name already exists, the entry is overwritten.

The `install` command renders the same canonical template into a native editor config format. Supported adapters currently cover:
- JSON clients with `mcpServers`: Claude Code, Cursor, Gemini CLI, Windsurf, Cline, Augment
- JSON clients with additional required metadata: GitHub Copilot
- TOML clients: Codex CLI

When `install` runs with `--scope project`, ai-toolkit also updates `.mcp.json` so the project-level config remains the source of truth for later sync and local install flows.

## Architecture

```
┌──────────────────────────────────────────────────────┐
│                   ai-toolkit (generic)               │
│                                                      │
│  Public Extension API:                               │
│    inject-rule  <file.md>     → CLAUDE.md            │
│    remove-rule  <name>        → CLAUDE.md            │
│    inject-hook  <file|url>    → settings.json        │
│    remove-hook  <name>        → settings.json        │
│    inject-mcp   <file|url>    → .mcp.json + editors  │
│    remove-mcp   <name>        → .mcp.json + editors  │
│    add-rule     <file|url>    → rules/ registry      │
│    mcp add      <template>    → .mcp.json            │
│    mcp install  <template>    → editor-native MCP    │
│                                                      │
│  Idempotent: markers (rules) / _source tags (hooks)  │
│  URL sources: cached + auto-refreshed on update      │
└──────────────────────────────────────────────────────┘
                        ▲
                        │ uses API
        ┌───────────────┼───────────────┐
        │               │               │
   rag-mcp          custom-tool     ci-system
   (consumer)       (consumer)      (consumer)
```

## Example: Registering Rules, Hooks, and MCP Servers from an External Tool

An external tool's install script would call:

```bash
# Register rules into CLAUDE.md
npx @softspark/ai-toolkit inject-rule ./rules/my-tool-rules.md

# Register hooks into settings.json (auto-propagates to Codex)
npx @softspark/ai-toolkit inject-hook ./hooks/my-tool-hooks.json

# Register MCP server template into .mcp.json + all editor MCP configs
npx @softspark/ai-toolkit inject-mcp ./mcp-template.json

# Alternative: pull MCP template from a URL (auto-refreshed on update)
npx @softspark/ai-toolkit inject-mcp https://example.com/mcp-template.json
```

To uninstall:

```bash
npx @softspark/ai-toolkit remove-rule my-tool-rules
npx @softspark/ai-toolkit remove-hook my-tool-hooks
npx @softspark/ai-toolkit remove-mcp my-tool
```

All operations are idempotent — safe to run on every install or update.

## Related Documentation

- [PATH: kb/reference/hooks-catalog.md] — built-in hooks reference
- [PATH: kb/reference/mcp-templates.md] — available MCP server templates
- [PATH: kb/reference/mcp-editor-compatibility.md] — native editor MCP support matrix
- [PATH: kb/reference/architecture-overview.md] — overall install model

---

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

---
title: "Global Install Model"
category: reference
service: ai-toolkit
tags: [install, global, claude, codex, plugins, local-setup]
version: "3.3.1"
created: "2026-03-26"
last_updated: "2026-07-15"
description: "Reference description of Claude Code global install, Claude app plugin export, project-local editor setup, global Codex plugin layering, and command responsibilities in ai-toolkit."
---

# Global Install Model

## Summary

`ai-toolkit` installs globally into `~/.claude/` by default.

That means one machine-level install provides agents, skills, hooks, constitution, and rule files to every project without committing toolkit boilerplate into each repository.

Other editor targets are opt-in and only use documented file surfaces. Cursor
rules stay project-local because Cursor's global user rules are managed through
the settings UI, not a stable merge-safe file. Codex supports both project and
user installs: project files stay in the repository, while user files use the
active `CODEX_HOME` (default `~/.codex`) and shared user skills use
`$HOME/.agents/skills/`. Experimental plugin packs can add a layer to the same
Codex user surface.

Claude Chat/Desktop/Cowork is a separate runtime. It does not read the
filesystem surfaces under `~/.claude`; it receives ai-toolkit through an
uploaded plugin plus app-managed global/folder instructions.

## Command Responsibilities

| Command | Target | Purpose |
|---------|--------|---------|
| `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, 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 claude-app export` | ZIP + Markdown output | build the uploadable Claude Chat/Cowork plugin and Cowork global instructions; registered rules are included unless `--no-custom-rules` is set |
| `ai-toolkit add-rule` | `~/.softspark/ai-toolkit/rules/` | register a global rule |
| `ai-toolkit remove-rule` | `~/.softspark/ai-toolkit/rules/` | unregister a global rule |
| `ai-toolkit mcp add <name...>` | current project | merge MCP templates into `.mcp.json` |
| `ai-toolkit mcp install --editor <name...>` | editor-native config | render MCP templates into editor-specific config files |
| `ai-toolkit plugin install --editor claude|codex|all <name>` | runtime-native config | install plugin pack for selected runtime(s) |
| `ai-toolkit plugin update --editor claude|codex|all <name>` | runtime-native config | re-apply plugin pack after toolkit updates |
| `ai-toolkit plugin remove --editor claude|codex|all <name>` | runtime-native config | remove plugin pack from selected runtime(s) |

## Install Profiles (v3.0.0)

The `--profile` flag controls how much of each editor's native surface is activated.

| Profile | What runs | Use when |
|---------|-----------|----------|
| `minimal` | Smallest editor surface. Copilot still receives its root instructions, native agents, and self-contained skills; Codex still receives instructions, agents, skills, and native safety hooks. | You want the smallest supported footprint. |
| `standard` (default) | Claude Code + editor rule files. Includes Gemini hooks and native Copilot instructions, agents, portable skills, and hooks. | Day-to-day installs. Most users. |
| `strict` | Everything in `standard` plus git-hook wiring for commit-time safety checks. | Solo dev or tight team with zero tolerance for drift. |
| `full` | Every native surface across every editor: hooks, sub-agents, custom commands, skill pointers for Cursor / Windsurf / Gemini / Augment / Antigravity. | You want maximum coverage and understand that each editor will carry generated files under its own layout. |

Codex installs materialize the full skill catalog under `.agents/skills/`
regardless of profile. The legacy `--codex-skills` flag only requests an
explicit second refresh of that same mirror and is no longer required.

## Global Editor Targets

Claude Code's default global install writes these managed surfaces:

- `~/.claude/agents/*.md` — per-file symlinks to toolkit agents.
- `~/.claude/skills/*/` — per-directory symlinks to toolkit skills.
- `~/.claude/settings.json` — merged hook configuration and global settings.
- `~/.claude/constitution.md` — marker-injected safety constitution.
- `~/.claude/ARCHITECTURE.md` — marker-injected architecture reference.
- `~/.claude/rules/ai-toolkit-*.md` — toolkit rules from `app/rules/*.md`.
- `~/.claude/rules/ai-toolkit-registered-*.md` — rules registered with `ai-toolkit add-rule`.
- `~/.claude/CLAUDE.md` — compact index pointing at the managed rule files.

The `ai-toolkit-*` prefix in `~/.claude/rules/` is reserved for installer-managed files. User-authored Claude rules should use another filename prefix, or be registered through `ai-toolkit add-rule` so they are emitted as `ai-toolkit-registered-*.md`.

## Claude App Target

`~/.claude/` is a Claude Code surface, not a Claude Chat/Cowork surface. Run:

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

Upload the ZIP from `Customize > Plugins`, then paste the sibling
`*-global-instructions.md` file into `Settings > Cowork > Global instructions`.
The plugin contains the normal skills and agents, app-relative Cowork hooks,
and an `ai-toolkit-rules` skill generated from common/standalone rules.
Registered rules are embedded in a separate skill by default. Skills work in
Chat and Cowork; hooks and sub-agents are Cowork-only. The app owns its plugin
store, so toolkit updates require re-export and re-upload.

`ai-toolkit install --editors <name>` can write global files only for editors
with documented, file-based config surfaces:

- `windsurf`: `~/.codeium/windsurf/memories/global_rules.md` plus `~/.codeium/windsurf/skills/ai-toolkit-skill-catalogue/SKILL.md` plus `~/.config/devin/AGENTS.md` (Devin CLI global rules — the Desktop `global_rules.md` path is not imported by `read_config_from.windsurf`)
- `gemini`: `~/.gemini/GEMINI.md`; hooks at `~/.gemini/settings.json` (profile ≥ standard); `~/.gemini/commands/` and `~/.gemini/skills/` pointer (profile full)
- `augment`: `~/.augment/rules/ai-toolkit.md`; `~/.augment/agents/`, `~/.augment/commands/`, and hooks in `~/.augment/settings.json` (profile full)
- `cline`: `~/Documents/Cline/Rules/ai-toolkit-*.md` plus `~/.cline/skills/ai-toolkit-skill-catalogue/SKILL.md`
- `roo`: `~/.roo/rules/ai-toolkit-*.md` plus `~/.agents/skills/*` (Roo/Zoo native skill discovery; skipped when `codex` is also selected, which fills the same dir)
- `aider`: `~/.aider.conf.yml` plus `~/.aider-ai-toolkit-CONVENTIONS.md` when the YAML file does not already exist
- `codex`: `$CODEX_HOME/AGENTS.md`, `$CODEX_HOME/agents/*.toml`, `$CODEX_HOME/hooks.json`, `$CODEX_HOME/ai-toolkit-hooks/*`, plus `$HOME/.agents/skills/*`; `CODEX_HOME` defaults to `~/.codex`, and `~/AGENTS.md` is not Codex's user-instruction file
- `opencode`: `~/.config/opencode/*`

Cursor, GitHub Copilot, and Google Antigravity now have partial global support,
scoped to whatever documented HOME file surface each exposes:

- `cursor`: `~/.cursor/hooks.json` (safety/quality hooks; profile ≥ standard). Cursor RULES stay project-local — their only global surface is the Settings UI.
- `copilot`: instructions, native agents, portable skills, and native hooks under `$COPILOT_HOME` when set or `~/.copilot` otherwise. The hook config is `hooks/ai-toolkit.json`; its self-contained runtime is `hooks/ai-toolkit/copilot_hook.py`. VS Code and GitHub.com still use repo `.github/` files, which local install emits.
- `antigravity`: skill pointer at `~/.gemini/config/skills/` and `~/.gemini/antigravity-cli/skills/`. Antigravity RULES stay project-local.

Their global MCP support, where available, is handled by `ai-toolkit mcp
install`, not by the rule installer.

## Why global install is the default

- less setup friction,
- no repeated per-project install step,
- easier machine-level upgrades,
- correct alignment with Claude Code user-level paths.

## What remains project-local

These files still stay local to a repository as part of the core install model:
- `CLAUDE.md`
- `.claude/settings.local.json`
- `.mcp.json`
- `.cursor/mcp.json`
- `.roo/mcp.json`
- `.github/mcp.json`
- `.claude/constitution.md`
- project `AGENTS.md`
- project `.agents/rules/*.md`
- project `.agents/skills/*`
- project `.codex/hooks.json`
- project `.codex/hooks/*`
- project `.codex/agents/*.toml`
- project `.codex/config.toml` when Codex MCP servers are selected
- `.github/copilot-instructions.md`
- `.github/instructions/ai-toolkit-*.instructions.md`
- `.github/prompts/ai-toolkit-*.prompt.md`
- `.github/agents/ai-toolkit-*.agent.md`
- `.github/skills/ai-toolkit-*/SKILL.md` plus required assets and helper scripts
- `.github/hooks/ai-toolkit.json` plus `.github/hooks/ai-toolkit/copilot_hook.py` (profile ≥ `standard`)
- `.clinerules`
- `.roomodes`
- `.aider.conf.yml`
- `.augment/rules/ai-toolkit-*.md`
- `.agents/rules/*.md` and `.agents/workflows/*.md` (Google Antigravity; singular `.agent/` still read as fallback)
- `.git/hooks/pre-commit` (fallback)
- project-specific documentation or safety overlays

Project-local Claude Code language rules live in `.claude/rules/ai-toolkit-*.md` with `paths` frontmatter. They are separate from the global user-level `~/.claude/rules/ai-toolkit-*.md` files above.

Claude Code hooks do **not** live in project-local settings. They are merged only into global `~/.claude/settings.json`. Editor-native generators may emit project-local hook files when that editor documents them; Copilot uses `.github/hooks/*.json` and Codex uses `.codex/hooks.json`.

## Copilot Install Behavior

`ai-toolkit install --local --editors copilot` always emits root `AGENTS.md`,
`.github/copilot-instructions.md`, native `.github/agents`, and portable,
self-contained `.github/skills`. Profiles `standard`, `strict`, and `full`
add scoped `.github/instructions`, `.github/prompts`, and native version-1
`.github/hooks`. Profile `minimal` omits those three additional directories.
When an existing project moves from `standard`, `strict`, or `full` to
`minimal`, the installer removes only marked or byte-exact historical ai-toolkit
instructions, prompts, and hooks. Unmanaged project files remain in place.

Global install emits personal instructions, scoped instructions, agents, and
skills under the active Copilot config root; profile `standard` and above adds
hooks. Personal prompt files are not a documented Copilot CLI user surface and
are not generated. `COPILOT_HOME` replaces `~/.copilot` for every generated
Copilot surface, including `mcp-config.json`. Existing user files and user-added
skill assets are preserved; reserved managed-path collisions and symlinked
config roots are rejected instead of overwritten.

Codex hook bundles are self-contained. Project `.codex/hooks.json` commands
reference executable assets in `.codex/hooks/`; user `$CODEX_HOME/hooks.json`
commands reference `$CODEX_HOME/ai-toolkit-hooks/`. Neither bundle depends on
Claude's shared `~/.softspark/ai-toolkit/hooks/` installation.

## Codex Local Install Behavior

`ai-toolkit install --local --editors codex` creates:

- `AGENTS.md`
- `.agents/skills/*`
- `.codex/hooks.json`
- `.codex/hooks/*`
- `.codex/agents/*.toml`
- `.codex/config.toml` when project MCP servers are selected

Native Codex-compatible skills are linked directly. Claude-oriented skills that
depend on `Agent`, `Team*`, or `Task*` primitives are translated into generated
Codex wrappers so the project still receives the full skill catalog.

## Codex Global Plugin Layer

`ai-toolkit plugin install --editor codex <pack>` additionally targets:

- `$CODEX_HOME/AGENTS.md` (pack rules are marker-injected here)
- `$HOME/.agents/skills/*`
- `$CODEX_HOME/hooks.json`
- `$CODEX_HOME/ai-toolkit-hooks/plugin-<pack>-*`

This is an explicit, opt-in layer on top of the normal Codex user install.
Runtime state is tracked in
`~/.softspark/ai-toolkit/plugins.json` per target (`claude`, `codex`).

## MCP Local Sync Behavior

If `.mcp.json` exists in the current project, `ai-toolkit install --local` mirrors its `mcpServers` block into:
- `.claude/settings.local.json`
- `.cursor/mcp.json` when `--editors cursor` is selected
- `.github/mcp.json` when `--editors copilot` is selected
- `.roo/mcp.json` when `--editors roo` is selected
- `.codex/config.toml` when `--editors codex` is selected

Global-only editor MCP configs are not written during `install --local`. Use `ai-toolkit mcp install --editor <name...>` for those targets.

## Related Documents

- `kb/reference/distribution-model.md`
- `kb/reference/merge-friendly-install-model.md`
- `kb/reference/codex-cli-compatibility.md`
- `kb/reference/copilot-compatibility.md`
- `kb/reference/mcp-editor-compatibility.md`

---

## kb/reference/hierarchical-override-pattern.md

---
title: "Hierarchical Override Pattern"
category: reference
service: ai-toolkit
description: "Convention for SKILL.md + reference/*.md relationship with explicit override semantics."
tags: [skills, architecture, patterns, override]
created: 2026-04-01
last_updated: 2026-04-01
---

# Hierarchical Override Pattern

## Overview

Skills in ai-toolkit follow a two-level content hierarchy: a master `SKILL.md`
file that defines global defaults and the main instruction flow, and optional
`reference/*.md` files that extend and specialize without contradicting the
master.

This document defines the conventions, override semantics, and splitting
criteria for this pattern.

## Architecture

```
app/skills/<skill-name>/
  SKILL.md                    # Master: global defaults, main flow
  reference/
    domain-a.md               # Extension: adds detail for domain A
    domain-b.md               # Extension: adds detail for domain B
    visual-companion.md       # Extension: visual/UI-specific guidance
```

## Roles

### SKILL.md (Master)

The `SKILL.md` file is the single source of truth for a skill. It defines:

- **Purpose and scope** of the skill.
- **Global defaults** that apply unless overridden by context.
- **Main instruction flow** -- the step-by-step process the agent follows.
- **Cross-references** to reference files (explicit `see reference/X.md` links).
- **Invocation metadata** (frontmatter: `disable-model-invocation`, etc.).

The master file is always loaded. It is the entry point for the agent.

### reference/*.md (Extensions)

Reference files extend the master by providing:

- **Domain-specific detail** that would bloat the master.
- **Lookup tables** (e.g., language-specific patterns, framework configs).
- **Specialized workflows** that apply in narrow contexts.
- **Examples and templates** too long for inline inclusion.

Reference files are loaded on demand -- only when the agent determines the
context requires them, or when the master explicitly references them.

## Override Semantics

The relationship between master and reference files follows strict rules:

### Rule 1: Reference files ADD, never REPLACE

A reference file must not contradict the master. It adds specificity within the
boundaries the master defines.

```
SKILL.md says:     "Use type hints on all public APIs"
reference/go.md:   "Use Go's built-in type system; exported functions are public APIs"
```

This is valid -- it specializes the general rule for Go without contradicting it.

```
SKILL.md says:     "Always validate input at the API boundary"
reference/perf.md: "Skip validation for internal microservice calls"
```

This is INVALID -- it contradicts the master. If an exception is needed, it must
be documented in the master itself with explicit conditions.

### Rule 2: Master defines the contract, references fill in the details

Think of it as interface vs. implementation:

| Layer | Defines | Example |
|-------|---------|---------|
| Master | "Validate all inputs" | General principle |
| Reference | "In Python, use Pydantic v2 BaseModel with Field validators" | Concrete implementation |

### Rule 3: Conflicts are resolved by the master

If a reference file and the master appear to conflict, the master wins. This
should be treated as a bug in the reference file and corrected.

### Rule 4: References may cross-reference each other

Reference files can link to other reference files, but the dependency graph
should remain shallow (max 2 levels deep). Deep chains make maintenance
difficult.

## When to Split

Split content from `SKILL.md` into `reference/*.md` when:

| Criterion | Threshold |
|-----------|-----------|
| **Total line count** | Master exceeds 300 lines |
| **Distinct sub-domains** | Content covers 3+ distinct domains (languages, frameworks, concerns) |
| **Lookup tables** | Tables with 20+ rows that serve as reference material |
| **Reuse potential** | Content could be useful to multiple skills |
| **Update frequency** | A section changes much more frequently than the rest |

Do NOT split when:

- The master is under 300 lines and covers a single domain.
- The "reference" content is only a few paragraphs.
- Splitting would force the agent to always load multiple files for basic
  operation.

## Examples from Existing Skills

### write-a-prd

```
app/skills/write-a-prd/
  SKILL.md                          # Main PRD creation flow
  reference/visual-companion.md     # Visual/UI-specific PRD guidance
```

- `SKILL.md` defines the interview-driven PRD process, output format, and
  quality criteria.
- `reference/visual-companion.md` extends with guidance for PRDs that involve
  visual interfaces -- design system references, wireframe conventions,
  accessibility requirements.
- The master references it: `"For visual products, see reference/visual-companion.md"`

### clean-code

```
app/skills/clean-code/
  SKILL.md                    # Universal clean code principles
  reference/python.md         # Python-specific patterns
  reference/typescript.md     # TypeScript-specific patterns
  reference/php.md            # PHP-specific patterns
  reference/go.md             # Go-specific patterns
  reference/dart.md           # Dart/Flutter-specific patterns
```

- `SKILL.md` defines language-agnostic principles (naming, SRP, DRY).
- Each `reference/<lang>.md` provides language-specific idioms, linting config,
  and type system patterns.
- The master links to them: `"For Python patterns, see reference/python.md"`

### testing-patterns

```
app/skills/testing-patterns/
  SKILL.md                             # Universal testing principles (AAA, org, targets)
  reference/python-pytest.md           # pytest specifics
  reference/typescript-vitest.md       # Vitest/Jest specifics
  reference/php-phpunit.md             # PHPUnit specifics
  reference/go-testing.md              # Go testing specifics
  reference/flutter-testing.md         # Flutter/Dart testing specifics
```

Same pattern: master defines the universal structure, references specialize per
ecosystem.

## Authoring Guidelines

1. **Master first.** Always write the `SKILL.md` completely before splitting.
   Premature splitting leads to fragmented, hard-to-follow skills.

2. **Explicit cross-references.** Every reference file must be linked from the
   master with a clear sentence explaining when to consult it.

3. **Self-contained references.** A reference file should be useful on its own
   for someone who has already read the master. Do not assume the reader will
   re-read the master alongside it.

4. **Consistent frontmatter.** Reference files do not need frontmatter unless
   they are independently searchable. If they are, use the same YAML format as
   the master.

5. **Naming convention.** Use kebab-case filenames that describe the domain:
   `python.md`, `visual-companion.md`, `database-patterns.md`. Avoid generic
   names like `extra.md` or `notes.md`.

## Anti-Patterns

| Anti-Pattern | Problem | Fix |
|--------------|---------|-----|
| Reference contradicts master | Agent gets conflicting instructions | Move exception to master with conditions |
| Master too thin | Agent lacks context without loading all references | Keep core flow in master, only split detail |
| Circular references | Infinite loading, confused agent | Keep dependency graph acyclic and shallow |
| Unnamed splits | `misc.md`, `extra.md` -- no signal about content | Use descriptive domain-based names |
| Over-splitting | 10+ reference files for a simple skill | Consolidate until the 300-line / 3-domain threshold justifies splitting |

---

## kb/reference/hooks-catalog.md

---
title: "Hooks Catalog"
category: reference
service: ai-toolkit
tags: [hooks, quality, safety, enforcement, settings.json]
version: "1.9.0"
created: "2026-03-27"
last_updated: "2026-07-26"
description: "Complete reference of all ai-toolkit hooks: events, scripts, installation, and runtime behavior."
---

# Hooks Catalog

## Overview

ai-toolkit provides 29 global hook entries across 14 lifecycle events that enforce quality, safety, and workflow rules across all Claude Code sessions, plus a separate `statusLine` command. Hooks are merged into `~/.claude/settings.json` on install, with logic in standalone scripts at `~/.softspark/ai-toolkit/hooks/`.

## Supported Surface

`scripts/validate.py` validates both event names and handler shapes before release. The accepted lifecycle surface includes `PostToolUseFailure`, `PostToolBatch`, and `UserPromptExpansion` in addition to the installed ai-toolkit events below.

Supported handler types are `command`, `http`, `prompt`, `agent`, and `mcp_tool`. ai-toolkit ships command hooks by default; non-command handlers are validated so external consumers can safely inject richer hook definitions through `inject-hook`.

## Installation

```bash
ai-toolkit install    # copies scripts to ~/.softspark/ai-toolkit/hooks/, merges into settings.json
ai-toolkit update     # re-copies scripts, re-merges (idempotent)
```

**File locations:**

- Scripts: `~/.softspark/ai-toolkit/hooks/*.sh`
- Config: `~/.claude/settings.json` → `hooks` key
- Source: `ai-toolkit/app/hooks/*.sh` + `app/hooks.json`

## Hook Events

### SessionStart — `session-start.sh`

| Field | Value |
|-------|-------|
| Event | `SessionStart` |
| Matcher | `startup\|compact` |
| Script | `~/.softspark/ai-toolkit/hooks/session-start.sh` |
| Fires | Session start + after context compaction |

**Actions:**
1. Injects MANDATORY reminder to follow CLAUDE.md rules
2. Injects REMINDER about tests and documentation
3. Loads session context from the per-repo session store (if exists)
4. Loads active instincts from `.claude/instincts/*.md` (if any)

By default the hook resets edit state for a new native session, preserves it
when the source is `compact`, performs stale search-flag cleanup, and checks
for updates without printing informational stdout. Set
`AI_TOOLKIT_HOOK_VERBOSE=1` to print the startup reminders and loaded context
for debugging; `AI_TOOLKIT_HOOK_QUIET=1` keeps it silent explicitly.

> **Session storage:** auto-generated session artifacts (context, handoff note,
> checkpoints, decisions) are stored **outside the project repo** under
> `~/.softspark/ai-toolkit/sessions/<repo-key>/`, where `<repo-key>` is the git
> work-tree root path (fallback: cwd) with `/` replaced by `-` (mirrors Claude
> Code's own `~/.claude/projects/` convention). This keeps generated files from
> piling up in every project's `.claude/` directory. Path resolution lives in the
> shared helper `app/hooks/_session-paths.sh`.

### Notification — `notify-waiting.sh`

| Field | Value |
|-------|-------|
| Event | `Notification` |
| Matcher | *(all)* |
| Script | `~/.softspark/ai-toolkit/hooks/notify-waiting.sh` |
| Fires | Claude Code waiting for user input |

**Action:** Cross-platform desktop notification ("Claude Code needs your attention"):
- macOS: `osascript` (native)
- Linux: `notify-send` (libnotify)
- Windows/WSL: `powershell.exe` WScript popup (5s auto-close)

### PreToolUse (Bash) — `guard-destructive.sh`

| Field | Value |
|-------|-------|
| Event | `PreToolUse` |
| Matcher | `Bash` |
| Script | `~/.softspark/ai-toolkit/hooks/guard-destructive.sh` |
| Fires | Before any Bash command |

**Action:** Blocks (exit 2) commands matching destructive patterns:
- `rm -rf`, `sudo rm`
- `DROP TABLE`, `DROP DATABASE`, `TRUNCATE`
- `format /`, `dd if=`
- `git push --force`
- `chmod -R 777`

**Exemptions (avoid false positives):**
- `git push --force-with-lease` / `--force-if-includes` — the safe force-push variants are allowed.
- A single, non-chained `echo`/`printf`/`git commit`/`git tag` carrying a destructive token as *data* (e.g. a commit message mentioning `DROP TABLE`) is allowed. Chained commands (`&&`, `;`, `|`) are still inspected in full.

### PreToolUse (file ops) — `guard-path.sh`

| Field | Value |
|-------|-------|
| Event | `PreToolUse` |
| Matcher | `Bash\|Read\|Edit\|Write\|MultiEdit\|Glob\|Grep\|NotebookEdit\|mcp__filesystem__.*` |
| Script | `~/.softspark/ai-toolkit/hooks/guard-path.sh` |
| Fires | Before any file access tool (including Bash, MCP filesystem) |

**Action:** Blocks (exit 2) when a path contains `/Users/<wrong>` or `/home/<wrong>` that doesn't match the actual `$HOME`. Prevents Claude from hallucinating or confusing similar usernames (common with non-ASCII names like Polish names).

**Feedback to Claude:** Tells it to use `~`, `$HOME`, or run `echo $HOME` instead of guessing.

### UserPromptSubmit — `user-prompt-submit.sh`

| Field | Value |
|-------|-------|
| Event | `UserPromptSubmit` |
| Matcher | *(all)* |
| Script | `~/.softspark/ai-toolkit/hooks/user-prompt-submit.sh` |
| Fires | Before Claude starts working on a submitted prompt |

**Action:** Maintains the per-session search-first flag used by Stop enforcement
and can provide a lightweight governance reminder: plan mode for architectural
work, evidence-first debugging, KB-first research, and validation expectations.

Skipped when `TOOLKIT_HOOK_PROFILE=minimal`. The bundled `app/hooks.json`
registers this command with `AI_TOOLKIT_HOOK_QUIET=1 AI_TOOLKIT_HOOK_FORMAT=json`.
This keeps the hook visually quiet (`suppressOutput: true`) while still
injecting event-specific JSON context before Claude starts working in runtimes
that consume hidden context:

```json
{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "..."
  },
  "suppressOutput": true
}
```

That context is the proactive half of search-first enforcement; the paired
`stop-search-check.sh` remains the corrective half. In plain-text mode,
informational reminders are silent by default and require
`AI_TOOLKIT_HOOK_VERBOSE=1`.

Codex-generated hooks intentionally run this script without
`AI_TOOLKIT_HOOK_FORMAT=json` by default because Codex renders
`additionalContext` visibly in the TUI; the search-first flag side effect still
arms the corrective Stop hook.

### UserPromptSubmit (usage tracking) — `track-usage.sh`

| Field | Value |
|-------|-------|
| Event | `UserPromptSubmit` |
| Matcher | *(all)* |
| Script | `~/.softspark/ai-toolkit/hooks/track-usage.sh` |
| Fires | Before Claude starts working on a submitted prompt |

**Action:** Records skill invocations (slash commands like `/commit`, `/review`) to `~/.softspark/ai-toolkit/stats.json` for local usage analytics. Non-slash prompts are ignored. Stats writes are best-effort and stay silent if the local state path is not writable.

### PostToolUse (edit feedback) — `post-tool-use.sh`

| Field | Value |
|-------|-------|
| Event | `PostToolUse` |
| Matcher | `Edit\|MultiEdit\|Write` |
| Script | `~/.softspark/ai-toolkit/hooks/post-tool-use.sh` |
| Fires | After file edit/write tool operations |

**Action:** Adds a lightweight reminder to run relevant validation, tests, and documentation updates after edits.

Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.

### Stop (quality check) — `quality-check.sh`

| Field | Value |
|-------|-------|
| Event | `Stop` |
| Matcher | *(all)* |
| Script | `~/.softspark/ai-toolkit/hooks/quality-check.sh` |
| Fires | After every Claude response |

**Action:** Runs language-appropriate linter:
- Python: `ruff check .`
- TypeScript: `npx tsc --noEmit`
- PHP: `vendor/bin/phpstan analyse`
- Dart: `dart analyze`
- Go: `go vet ./...`

Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.

### Stop (session save) — `save-session.sh`

| Field | Value |
|-------|-------|
| Event | `Stop` |
| Matcher | *(all)* |
| Script | `~/.softspark/ai-toolkit/hooks/save-session.sh` |
| Fires | After every Claude response |

**Action:** Writes enriched session context to the per-repo session store (`~/.softspark/ai-toolkit/sessions/<repo-key>/session-context.md`) for cross-session persistence. Captures:
- Session ID and last assistant message (first 5 lines)
- Git branch, uncommitted change count, and diff stat (last 5 lines)
- Agent-written checkpoints from `session-context.md.checkpoints` in the same store (if present — written by proactive checkpointing per Constitution Art. I §5)

Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.

### Stop (quality gate) — `quality-gate.sh`

| Field | Value |
|-------|-------|
| Event | `Stop` |
| Matcher | *(all)* |
| Script | `~/.softspark/ai-toolkit/hooks/quality-gate.sh` |
| Fires | Before Claude is allowed to finish a response |

**Action:** Runs lint/typecheck. **Blocks stopping (exit 2)** if errors found, so Claude must continue and fix the issues. Missing local tooling is reported as skipped rather than blocking the session.

Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.

### TaskCompleted — `quality-gate.sh`

| Field | Value |
|-------|-------|
| Event | `TaskCompleted` |
| Matcher | *(all)* |
| Script | `~/.softspark/ai-toolkit/hooks/quality-gate.sh` |
| Fires | When an Agent Teams task is marked complete |

**Action:** Runs lint/typecheck. **Blocks completion (exit 2)** if errors found. Strict profile also runs `mypy --strict`.

Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.

### SubagentStart — `subagent-start.sh`

| Field | Value |
|-------|-------|
| Event | `SubagentStart` |
| Matcher | *(all)* |
| Script | `~/.softspark/ai-toolkit/hooks/subagent-start.sh` |
| Fires | When a subagent is spawned |

**Action:** Reminds subagents to stay narrow in scope, gather evidence first, and return explicit validation notes.

Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.

### SubagentStop — `subagent-stop.sh`

| Field | Value |
|-------|-------|
| Event | `SubagentStop` |
| Matcher | *(all)* |
| Script | `~/.softspark/ai-toolkit/hooks/subagent-stop.sh` |
| Fires | When a subagent completes |

**Action:** Enforces a concise handoff checklist: findings, files touched, tests run, risks, and docs follow-up.

Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.

### PreCompact — `pre-compact.sh`

| Field | Value |
|-------|-------|
| Event | `PreCompact` |
| Matcher | *(all)* |
| Script | `~/.softspark/ai-toolkit/hooks/pre-compact.sh` |
| Fires | Before context compaction |

**Actions (prioritized — higher priority items survive tighter token budgets):**
1. **Mandatory reload reminder** — always emitted, instructs Claude to re-read CLAUDE.md and active tasks
2. **Active instincts** — lists each instinct with confidence score and pattern name from `.claude/instincts/*.md`
3. **Session context** — preserves task state from the per-repo session store (if exists)
4. **Git working state** — branch name, uncommitted change count, last commit (if inside a git repo)
5. **Key decisions** — last 10 lines from `decisions.md` in the per-repo session store (if exists)

Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.

### SessionEnd — `session-end.sh`

| Field | Value |
|-------|-------|
| Event | `SessionEnd` |
| Matcher | *(all)* |
| Script | `~/.softspark/ai-toolkit/hooks/session-end.sh` |
| Fires | When a Claude session ends |

**Action:** Removes isolated edit state for the ending native session, then writes `session-end.md` to the per-repo session store
(`~/.softspark/ai-toolkit/sessions/<repo-key>/`) with a lightweight handoff note
for the next session.

The handoff note is skipped when `TOOLKIT_HOOK_PROFILE=minimal`; recovery and
edit-state cleanup still run.

### TeammateIdle — inline

| Field | Value |
|-------|-------|
| Event | `TeammateIdle` |
| Matcher | *(all)* |
| Fires | Agent Teams teammate going idle |

**Action:** Reminds teammate to verify: files modified, tests written, docs updated.

---

## New Hooks (v1.1.0)

### PreToolUse (config guard) — `guard-config.sh`

| Field | Value |
|-------|-------|
| Event | `PreToolUse` |
| Matcher | `Edit\|Write\|MultiEdit` |
| Script | `~/.softspark/ai-toolkit/hooks/guard-config.sh` |
| Fires | Before any file write/edit operation |

**Action:** Always blocks (exit 2) edits to protected linter and formatter configuration: ESLint, Prettier, TypeScript, Stylelint, Biome, `ruff.toml`, and Ruff sections in `pyproject.toml`. Prompt text and acknowledgment phrases do not bypass the guard. A user who explicitly authorizes a protected edit must deliberately remove the guard for that operation.

### SessionStart — `mcp-health.sh`

| Field | Value |
|-------|-------|
| Event | `SessionStart` |
| Matcher | *(all)* |
| Script | `~/.softspark/ai-toolkit/hooks/mcp-health.sh` |
| Fires | Session start |

**Action:** Non-blocking (always exits 0). Reads MCP server definitions from `~/.claude/settings.json` and any local `.mcp.json`. For each configured server, checks whether the required runtime command (`npx`, `uvx`, `docker`, etc.) is available in `$PATH`. Emits warnings for any missing runtimes, including install hints (e.g. "npm install -g npx"). Helps surface MCP misconfiguration early without interrupting the session.

### PostToolUse (governance) — `governance-capture.sh`

| Field | Value |
|-------|-------|
| Event | `PostToolUse` |
| Matcher | *(all)* |
| Script | `~/.softspark/ai-toolkit/hooks/governance-capture.sh` |
| Fires | After any tool use |

**Action:** Non-blocking (always exits 0). Logs recognized
dangerous-command categories and writes to sensitive filenames to
`~/.softspark/ai-toolkit/governance.log` with an ISO timestamp, normalized
session ID, tool name, and a bounded category or path detail. It does not
store the full command or file content. Skipped when
`TOOLKIT_HOOK_PROFILE=minimal`.

### PreCompact — `pre-compact-save.sh`

| Field | Value |
|-------|-------|
| Event | `PreCompact` |
| Matcher | *(all)* |
| Script | `~/.softspark/ai-toolkit/hooks/pre-compact-save.sh` |
| Fires | Before context compaction |

**Action:** Saves a timestamped context snapshot to
`~/.softspark/ai-toolkit/compactions/YYYY-MM-DD_HH-MM-SS_<session>.txt`.
Captures the bounded normalized session ID, working directory, and git branch.
Provides an audit trail for compaction boundaries. Skipped when
`TOOLKIT_HOOK_PROFILE=minimal`.

### PreToolUse (commit quality) — `commit-quality.sh`

| Field | Value |
|-------|-------|
| Event | `PreToolUse` |
| Matcher | `Bash` |
| Script | `~/.softspark/ai-toolkit/hooks/commit-quality.sh` |
| Fires | Before any Bash command |

**Action:** Non-blocking (always exits 0). Inspects Bash commands containing `git commit`. Extracts the commit message from the `-m` flag and checks it against Conventional Commits format (`type: description`, where type is one of feat/fix/docs/refactor/test/chore/ci/perf/style/revert). Emits an advisory warning if the message does not match — the commit is not blocked, only nudged. Commands without `git commit` or without a `-m` message (e.g. interactive commits) are ignored.

---

## New Hooks (Constitution Art. VI Enforcement)

These six hooks turn Constitution Article VI ("Repair Discipline") from prose into executable enforcement. Each one closes a specific gap that previously relied on agent goodwill.

### PreToolUse (revert protection) — `revert-guard.sh`

| Field | Value |
|-------|-------|
| Event | `PreToolUse` |
| Matcher | `Bash` |
| Script | `~/.softspark/ai-toolkit/hooks/revert-guard.sh` |
| Fires | Before any Bash command |

**Action:** Blocks (exit 2) `git checkout/restore -- <file>`, `git reset --hard`, or `git clean -fd` when the affected files were edited in the current session (per `session_state.py` log). Forces the agent to fix root causes instead of reverting work-in-progress (Art. VI.2). Branch switches (`git checkout main`) and reverts on untouched files pass through unchanged.

**Override (one-off):** `CLAUDE_REVERT_OK=1`. Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.

### PostToolUse (test cohesion) — `test-cohesion.sh`

| Field | Value |
|-------|-------|
| Event | `PostToolUse` |
| Matcher | `Edit\|MultiEdit\|Write` |
| Script | `~/.softspark/ai-toolkit/hooks/test-cohesion.sh` |
| Fires | After every file edit |

**Action:** Runs the test commands mapped to the edited path via `test-cohesion-map.json`. Lookup order: project-local `.claude/test-cohesion-map.json`, then toolkit default `app/hooks/test-cohesion-map.json`. Blocks (exit 2) when the related test command fails. Runs **only** related tests, not the full suite (one of the user-stated requirements).

Map schema:
```json
[
  {
    "match": "src/auth/*.py",
    "tests": ["tests/test_auth.py"],
    "runner": "pytest",
    "command": null
  }
]
```
First-match-wins per file. Built-in runners: `bats`, `pytest`, `vitest`, `jest`. Use `"command"` for full overrides.

**Overrides:** `CLAUDE_SKIP_COHESION=1` (one-off), `CLAUDE_HOOK_BOOTSTRAP=1` (when editing the hook itself). Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.

### PostToolUse (loop guard) — `loop-guard.sh`

| Field | Value |
|-------|-------|
| Event | `PostToolUse` |
| Matcher | `Bash\|Edit\|MultiEdit\|Write` |
| Script | `~/.softspark/ai-toolkit/hooks/loop-guard.sh` |
| Fires | After every Bash command or file edit |

**Action:** Advisory only, never blocks. Hashes a `tool|identity` signature of each action (command for Bash; file path + new content for edits) and keeps the last `AI_TOOLKIT_LOOP_WINDOW` (default 6) hashes per session. When the same signature repeats `AI_TOOLKIT_LOOP_THRESHOLD` times (default 3) it emits a `PostToolUse` `additionalContext` advisory telling Claude to reassess instead of retrying. Catches successful-but-identical loops that the `/repeat` circuit breaker (which only counts failures) does not. Edits track content, so normal iterative editing of one file does not trip it. Only short hashes are stored — never raw payloads.

**Tunables:** `AI_TOOLKIT_LOOP_WINDOW`, `AI_TOOLKIT_LOOP_THRESHOLD`. Skipped when `TOOLKIT_HOOK_PROFILE=minimal`; honours `AI_TOOLKIT_DISABLED_HOOKS`.

### PostToolUse (search-first tracker) — `search-tracker.sh`

| Field | Value |
|-------|-------|
| Event | `PostToolUse` |
| Matcher | `mcp__.*__(smart_query\|hybrid_search_kb\|crag_search\|multi_hop_search\|verify_answer)\|WebSearch\|WebFetch` |
| Script | `~/.softspark/ai-toolkit/hooks/search-tracker.sh` |
| Fires | After any search-style tool call |

**Action:** Clears `~/.softspark/ai-toolkit/state/search-required-<session_id>.flag`
for the bounded normalized native session. Identity lookup accepts
`session_id`, Augment `conversation_id` / `conversationId`,
`CLAUDE_SESSION_ID`, or the transcript basename before falling back to
`default`. It pairs with `user-prompt-submit.sh` (sets the flag on long
technical prompts only when a search provider is detected or strict mode is
enabled) and `stop-search-check.sh` (blocks Stop if the calling session's flag
is still set). Search provider detection parses actual MCP server names from
`mcpServers`, `mcp_servers`, or `mcp` config blocks; hook matchers and
permission allowlists do not count as providers. Codex Stop enforcement also
scans the recent `$CODEX_HOME/log/codex-tui.log` window (default
`~/.codex/log/codex-tui.log`) for `ToolCall:
mcp__...__smart_query` and `tool.name="smart_query"`-style entries because
Codex MCP tool calls may not fire the shared `PostToolUse` tracker. Together
the hooks enforce the global CLAUDE.md GOLDEN RULE without breaking
offline/no-RAG installs and without cross-session interference when multiple
runtime windows run in parallel.

Non-blocking (exit 0). Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.

### Stop (search-first enforcement) — `stop-search-check.sh`

| Field | Value |
|-------|-------|
| Event | `Stop` |
| Matcher | *(all)* |
| Script | `~/.softspark/ai-toolkit/hooks/stop-search-check.sh` |
| Fires | When Claude finishes a response |

**Action:** If `search-required-<session_id>.flag` for the calling session is still present (no search tool ran during this turn) and a search provider is still detectable, emits `{"decision":"block","reason":"..."}` to continue the conversation with a search-first reminder. If no RAG/Web provider is detected, it clears the stale flag and exits 0, so offline/no-MCP users are not blocked. On Codex, where MCP search tools may not trigger the shared `PostToolUse` tracker, the hook also checks `$CODEX_HOME/log/codex-tui.log` (default `~/.codex/log/codex-tui.log`) for search tool calls after the flag timestamp before blocking. Flags are scoped by `session_id` from the hook stdin payload so a Stop in session B never consumes session A's flag (and vice versa). Stale per-session flags older than 60 minutes are GC'd on the next `SessionStart`.

**Overrides:** `CLAUDE_SKIP_SEARCH_FIRST=1`, `AI_TOOLKIT_SEARCH_FIRST=off`, or `AI_TOOLKIT_SEARCH_FIRST=strict` to force enforcement. Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.

### InstructionsLoaded — `instructions-audit.sh`

| Field | Value |
|-------|-------|
| Event | `InstructionsLoaded` |
| Matcher | *(all)* |
| Script | `~/.softspark/ai-toolkit/hooks/instructions-audit.sh` |
| Fires | Whenever CLAUDE.md / `.claude/rules/*.md` is loaded into context |

**Action:** Appends `<ts>\t<memory_type>\t<load_reason>\t<file_path>` to `~/.softspark/ai-toolkit/state/loaded-instructions.log`. Provides audit visibility: when a rule does NOT enter context (silently dropped, token budget, glob miss), the absence is observable. Auto-rotates at 2000 lines.

Non-blocking (exit 0). Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.

### ConfigChange — `config-desync-guard.sh`

| Field | Value |
|-------|-------|
| Event | `ConfigChange` |
| Matcher | `user_settings` |
| Script | `~/.softspark/ai-toolkit/hooks/config-desync-guard.sh` |
| Fires | When `~/.claude/settings.json` changes |

**Action:** Compares `_source: ai-toolkit` entries between `~/.claude/settings.json` (installed) and the toolkit source `app/hooks.json`. If they diverge (missing/stale entries), emits an advisory to stderr suggesting `ai-toolkit update` or `ai-toolkit doctor --fix`. Non-blocking by design — user's legitimate settings edits never get rejected.

**Override (silence advisory):** `CLAUDE_SKIP_CONFIG_DESYNC=1`. Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.

### Supporting Infrastructure

| Component | Purpose |
|-----------|---------|
| `scripts/session_state.py` | Isolated edit state keyed by a hash of the normalized native session ID. Reset on SessionStart and cleaned on SessionEnd. Read by revert-guard and quality-gate. |
| `scripts/test_cohesion.py` | Resolves changed paths → test commands via cohesion map. First-match-wins. Stdlib-only. |
| `app/hooks/test-cohesion-map.json` | Toolkit-default path → tests mapping (used when no project map exists). |
| `app/hooks/_locate-toolkit.sh` | Shared bash helper that exports `$TOOLKIT_DIR` for hooks needing scripts/. |
| `app/hooks/_hook-io.sh` | Shared bash helper that normalizes hook payloads across Claude, Augment, Gemini, Windsurf, and Cursor-style JSON. JSON context output takes precedence over `AI_TOOLKIT_HOOK_QUIET=1`, so quiet hooks can still emit `additionalContext` with `suppressOutput: true`; plain-text output requires `AI_TOOLKIT_HOOK_VERBOSE=1`. |
| `app/hooks/_search-capability.sh` | Shared bash helper that enables search-first blocking only when RAG/Web is configured or strict mode is requested. |

## Runtime Profiles

Set in `.claude/settings.local.json`:

```json
{ "env": { "TOOLKIT_HOOK_PROFILE": "standard" } }
```

| Profile | Behavior |
|---------|----------|
| `minimal` | Only destructive guard + SessionStart |
| `standard` | All hooks (default) |
| `strict` | Standard + mypy --strict on task completion |

**Disabling individual hooks:** set `AI_TOOLKIT_DISABLED_HOOKS` to a comma-separated list of hook names (with or without `.sh`), e.g. `{ "env": { "AI_TOOLKIT_DISABLED_HOOKS": "loop-guard,quality-check" } }`. Listed hooks become no-ops. This covers profile-gated hooks only; the safety guards (`guard-destructive`/`guard-path`/`guard-config`) intentionally cannot be env-disabled — remove them deliberately with `ai-toolkit remove-hook`.

Non-blocking informational context is silent in plain-text mode by default while
side effects and blocking decisions still run. Set `AI_TOOLKIT_HOOK_VERBOSE=1`
only when debugging hook context locally. `AI_TOOLKIT_HOOK_QUIET=1` keeps hook
commands explicitly silent, and Codex-generated hooks plus Claude's bundled
`UserPromptSubmit` entry use it to avoid visible prompt hook context.

## Architecture

```
~/.softspark/ai-toolkit/
├── rules/          # Registered rules (add-rule.sh)
├── state/          # Per-session runtime state
│   ├── session-edits-<hash>.json  # Isolated edit state, removed at SessionEnd
│   ├── session-edits.json         # Compatibility alias for the active session
│   ├── search-required-<sid>.flag # Per-session: set by user-prompt-submit, cleared by search-tracker/stop-search-check, GC'd at SessionStart (>60min)
│   ├── loaded-instructions.log    # Audit trail of which rules entered context
│   └── test-cohesion-last.log     # Last cohesion test command output
└── hooks/          # Hook scripts (copied on install)
    ├── _profile-check.sh         # Shared: profile skip logic (sourced by hooks)
    ├── _locate-toolkit.sh        # NEW: shared $TOOLKIT_DIR locator
    ├── _hook-io.sh               # NEW: shared multi-editor payload/output adapter
    ├── _search-capability.sh     # NEW: capability-aware search-first enforcement
    ├── _session-paths.sh         # NEW: per-repo session storage path resolver
    ├── session-start.sh
    ├── guard-destructive.sh
    ├── guard-path.sh
    ├── guard-config.sh
    ├── revert-guard.sh           # NEW: block revert on session-edited files (Art. VI.2)
    ├── mcp-health.sh
    ├── user-prompt-submit.sh     # extended: arms search-required flag
    ├── post-tool-use.sh          # extended: appends edits to session state
    ├── governance-capture.sh
    ├── test-cohesion.sh          # NEW: runs mapped tests after edits (Art. VI.3)
    ├── test-cohesion-map.json    # NEW: path → tests mapping
    ├── search-tracker.sh         # NEW: clears search-required flag
    ├── quality-check.sh
    ├── quality-gate.sh           # extended: cohesion-tests session edits
    ├── stop-search-check.sh      # NEW: enforces search-first on Stop
    ├── save-session.sh
    ├── subagent-start.sh
    ├── subagent-stop.sh
    ├── track-usage.sh
    ├── pre-compact.sh
    ├── pre-compact-save.sh
    ├── commit-quality.sh
    ├── instructions-audit.sh     # NEW: logs CLAUDE.md / rules loads
    ├── config-desync-guard.sh    # NEW: warns on settings ↔ source drift
    └── session-end.sh

~/.claude/settings.json
└── hooks:          # Hook definitions referencing ~/.softspark/ai-toolkit/hooks/
    ├── SessionStart       → session-start.sh, mcp-health.sh
    ├── Notification       → notify-waiting.sh
    ├── PreToolUse         → guard-destructive.sh, guard-path.sh, guard-config.sh, commit-quality.sh, revert-guard.sh
    ├── UserPromptSubmit   → user-prompt-submit.sh, track-usage.sh
    ├── PostToolUse        → post-tool-use.sh, governance-capture.sh, test-cohesion.sh, search-tracker.sh
    ├── Stop               → quality-check.sh, save-session.sh, quality-gate.sh, stop-search-check.sh
    ├── TaskCompleted      → quality-gate.sh
    ├── TeammateIdle       → echo (inline)
    ├── SubagentStart      → subagent-start.sh
    ├── SubagentStop       → subagent-stop.sh
    ├── PreCompact         → pre-compact.sh, pre-compact-save.sh
    ├── SessionEnd         → session-end.sh
    ├── InstructionsLoaded → instructions-audit.sh
    └── ConfigChange       → config-desync-guard.sh
```

**Claude Code design decisions:**
- Scripts **copied** (not symlinked) — user can customize without breaking git
- Hooks in `settings.json` (not `hooks.json`) — Claude Code only reads settings files
- `_source: "ai-toolkit"` tag on every entry — allows idempotent merge/strip
- Claude hooks are **global only** — `--local` does not install them into project settings

## Per-Editor Native Hooks

Beyond the global Claude Code hooks above, editor profiles emit native hook files for runtimes that support their own lifecycle. The profile threshold and command/output contract are editor-specific; generators must not assume Claude event names or exit semantics.

| Editor | File | Generator | Format |
|--------|------|-----------|--------|
| Cursor | `.cursor/hooks.json` | `generate_cursor_hooks.py` | Cursor hooks schema |
| Devin CLI | `.devin/hooks.v1.json` | `generate_devin_hooks.py` | Claude-compatible (the replacement for Cascade) |
| Gemini CLI | `.gemini/settings.json` (hooks block) | `generate_gemini_hooks.py` | Gemini `BeforeTool`/`AfterTool` events |
| Augment | `.augment/settings.json` (hooks block) | `generate_augment_hooks.py` | Claude-style events |
| GitHub Copilot | `.github/hooks/ai-toolkit.json`; user `$COPILOT_HOME/hooks/ai-toolkit.json` | `generate_copilot_hooks.py` | GitHub version 1, camelCase events (profile ≥ `standard`) |
| Codex CLI | `.codex/hooks.json`; user `$CODEX_HOME/hooks.json` | `generate_codex_hooks.py` | Native Codex schema, PascalCase events, command ownership markers |
| OpenCode | `.opencode/plugins/ai-toolkit-hooks.js`; user `~/.config/opencode/plugins/ai-toolkit-hooks.js` | `generate_opencode_plugin.py` | Native JavaScript plugin hooks |

### Cursor hooks (`.cursor/hooks.json`)

Cursor hooks follow the native [version-1 hooks contract](https://cursor.com/docs/hooks):

- **Cloud:** cloud agents load only repository `.cursor/hooks.json`; they cannot read user-level `~/.cursor/hooks.json`. Project commands call the adjacent self-contained `.cursor/hooks/ai-toolkit/cursor_hook.py` runtime and contain no host `~/.softspark` dependency.
- **Events:** the generator emits the complete documented Agent, Tab, and workspace lifecycle event set, including Cursor 3.11 conversation events `beforeSubmitPrompt`, `afterAgentResponse`, `afterAgentThought`, `subagentStart`, `subagentStop`, `preCompact`, and `stop`.
- **Schema:** managed entries use only documented `command`, `timeout`, and `loop_limit` fields. Regeneration recognizes the runtime command as its ownership marker and removes legacy `_source: ai-toolkit` entries without emitting that non-standard key again.
- **Safety:** destructive shell commands return Cursor's native `permission: deny` response and exit 2. A failed detected quality gate returns a bounded `followup_message`; `stop` and `subagentStop` declare `loop_limit: 5`, with an earlier three-failure circuit breaker in the runtime.
- **Preservation:** unrelated top-level settings and user hook entries survive regeneration. Config and runtime replacement is staged and rejects symlinked destinations or a user-owned runtime collision.

### GitHub Copilot hooks (`.github/hooks/ai-toolkit.json`)

Copilot hooks follow GitHub's native [hooks reference](https://docs.github.com/en/copilot/reference/hooks-reference), not Claude's settings schema:

- **Locations:** repository hooks live in `.github/hooks/*.json`; user hooks live in `hooks/*.json` below `$COPILOT_HOME` or `~/.copilot`.
- **File shape:** top-level `version: 1` plus a `hooks` object containing camelCase events.
- **Runtime:** `ai-toolkit.json` calls the adjacent self-contained `ai-toolkit/copilot_hook.py`; local hooks do not depend on a package checkout or `~/.softspark` scripts.
- **Native decisions:** `preToolUse` returns `permissionDecision`, `permissionDecisionReason`, and optional `modifiedArgs`. `agentStop` returns `decision` plus `reason`. Context events use `additionalContext`.
- **Failure semantics:** the runtime uses GitHub's event-specific stdout and exit-code contracts. It does not reuse Claude's generic exit-2 blocking behavior.
- **Loop safety:** a failing `agentStop` quality gate can block twice; the third consecutive failure opens the circuit so the session cannot loop forever.
- **Ownership:** generated configs carry `AI_TOOLKIT_HOOK_OWNER=ai-toolkit`; unrelated hook files are not edited.

### Codex CLI hooks (`.codex/hooks.json`)

Codex hooks follow the native [Codex hooks contract](https://learn.chatgpt.com/docs/hooks):

- **Locations:** repository hooks live in `.codex/hooks.json`; user hooks live in `$CODEX_HOME/hooks.json` (default `~/.codex/hooks.json`). Project hooks load only for a trusted `.codex` layer.
- **Assets:** repository commands use self-contained `.codex/hooks/*`; user commands use `$CODEX_HOME/ai-toolkit-hooks/*`. They do not call Claude's `~/.softspark/ai-toolkit/hooks/` paths.
- **Events:** Codex documents 10 events. ai-toolkit wires 9: `SessionStart`, `PreToolUse`, `PostToolUse`, `PermissionRequest`, `UserPromptSubmit`, `SubagentStart`, `SubagentStop`, `PreCompact`, and `Stop`. `PostCompact` is intentionally unwired.
- **Compaction:** `PreCompact` runs `codex-pre-compact.sh`, a Codex-native reminder that refers to the active `AGENTS.md` chain, plan, and git state. It does not run Claude's `pre-compact.sh` or `pre-compact-save.sh` payload adapters.
- **Ownership:** native JSON contains no private `_source` keys. Core handlers carry `AI_TOOLKIT_HOOK_OWNER=ai-toolkit` in their command; plugin and external handlers use exact source-specific command markers.
- **Preservation:** generation replaces only toolkit-owned handlers and assets. Unrelated user handlers and plugin-owned handlers remain intact.
- **Trust:** installation never bypasses trust. Review the active definitions with `/hooks` after install or update.

### Devin CLI hooks (`.devin/hooks.v1.json`)

Windsurf rebranded to Devin Desktop (2026-06-02). The Cascade hook surface ended on 2026-07-01; ai-toolkit now emits only the live Devin CLI format.

Devin CLI uses a **Claude-compatible** hook format (docs.devin.ai/cli/extensibility/hooks). Key facts driving the generator:

- **Standalone file shape:** in `.devin/hooks.v1.json` the entire file IS the hooks object — no top-level `"hooks"` wrapper key (unlike `.claude/settings.json`).
- **Events:** Claude-style PascalCase — `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`. `post_cascade_response` maps to `Stop` (which carries no response text on stdin).
- **Matchers:** regex against the Devin **tool name** (`read`, `edit`, `exec`, `grep`, `glob`, `mcp__<server>__<tool>`) — NOT Claude's `Bash`/`Edit`, so the shared guards reliably fire.
- **Block contract:** the guard scripts emit `{"decision":"block","reason":...}` on stdout (plain mode) AND exit 2 — Devin honors both. Hooks run **without** `AI_TOOLKIT_HOOK_FORMAT=json` because Devin expects the flat `{"decision","reason"}` shape, not Claude's `hookSpecificOutput` envelope.
- **Stdin payload:** flat `{ "hook_event_name", "tool_name", "tool_input" }` — already handled by `_hook-io.sh` via its `.tool_name` / `.tool_input.*` branches, so no normalizer change was needed.
- **Global bonus:** Devin CLI reads `~/.claude/settings.json` + `.claude/settings.json` hooks directly (`read_config_from.claude` default on, since CLI `2026.3.20-2`), so a global `ai-toolkit install` already covers Devin even without the project-local file.

## Troubleshooting

**Hooks not loading:**
1. Run `/hooks` in Claude Code — lists all active hooks
2. Check `claude --debug hooks` — shows matcher resolution
3. Verify JSON: `python3 -c "import json; json.load(open('$HOME/.claude/settings.json'))"`

**Hook script not found:**
```bash
ls ~/.softspark/ai-toolkit/hooks/     # should list 28 .sh files (plus _profile-check.sh + _locate-toolkit.sh + _hook-io.sh + _search-capability.sh helpers + test-cohesion-map.json)
ai-toolkit update            # re-copies scripts
```

**Legacy cleanup:**
```bash
rm ~/.claude/hooks.json      # old format, no longer used
rm -rf ~/.claude/hooks       # old symlink, no longer used
```

---

## kb/reference/integrations.md

---
title: "AI Toolkit - External Integrations"
category: reference
service: ai-toolkit
tags: [integrations, rules, add-rule]
version: "1.1.0"
created: "2026-03-26"
last_updated: "2026-06-30"
description: "How external repos register rules that ai-toolkit syncs into Claude Code user-level rules and other editor configs."
---

# External Integrations

Repos that register rules with ai-toolkit so they are automatically synced into Claude Code user-level rules and other editor configs on every `update`.

---

## How to Register Rules

Use `add-rule` to register a rule file globally. Every subsequent `ai-toolkit update` picks it up automatically.

```bash
cd /path/to/your-repo
ai-toolkit add-rule ./jira-rules.md
ai-toolkit update   # inject now
```

After registration, `ai-toolkit update` will always re-sync the rule. Registry location: `~/.softspark/ai-toolkit/rules/`.

For Claude Code, registered rules are written to `~/.claude/rules/ai-toolkit-registered-<name>.md`. The `ai-toolkit-*` prefix in `~/.claude/rules/` is installer-managed; use another prefix for hand-written Claude rules.

To unregister a rule (removes from `~/.softspark/ai-toolkit/rules/`, deletes the generated Claude rule file, and strips any legacy block from `CLAUDE.md`):

```bash
ai-toolkit remove-rule jira-rules
```

---

## How It Works

Claude Code uses file-based user-level rules:

```
~/.claude/rules/ai-toolkit-registered-jira-rules.md
```

Other editors receive the same registered rule through their native generated rule surfaces. Legacy `CLAUDE.md` marker sections are removed during migration, but content outside toolkit-managed markers is never touched.

---

## Adding a New Integration

1. Create `<name>-rules.md` in your repo with Claude-relevant conventions
2. Register it: `ai-toolkit add-rule ./<name>-rules.md`
3. Verify it appears in: `~/.softspark/ai-toolkit/rules/<name>-rules.md`
4. On next `install` it will be listed in: `Rules synced: ... <name>-rules`
5. Verify Claude receives it at: `~/.claude/rules/ai-toolkit-registered-<name>-rules.md`
6. Add an entry below documenting the integration

---

## Known Integrations

### rag-mcp

**Rule file:** `rag-mcp.md`
**Claude rule file:** `~/.claude/rules/ai-toolkit-registered-rag-mcp.md`

Teaches Claude Code the RAG-MCP search protocol: always call `smart_query()` before answering, `kb_id` vs `file_path` distinction, available MCP tools.

```bash
cd /path/to/rag-mcp
ai-toolkit add-rule ./rag-mcp-rules.md
```

### jira-mcp

**Rule file:** `jira-rules.md`
**Claude rule file:** `~/.claude/rules/ai-toolkit-registered-jira-rules.md`

Teaches Claude Code the Jira MCP tool set: `sync_tasks`, `read_cached_tasks`, `update_task_status`, `log_task_time`, and key rules (sync first, hours only, check transitions).

```bash
cd /path/to/jira-mcp
ai-toolkit add-rule ./jira-rules.md
```

---

## kb/reference/language-rules.md

---
title: "Language Rules System"
category: reference
service: ai-toolkit
tags: [rules, languages, coding-style, testing, patterns, security]
version: "2.1.0"
created: "2026-04-07"
last_updated: "2026-06-30"
description: "Reference for the language-specific rules system: 13 per-language rule sets shipped as knowledge skills, plus common rules installed as Claude Code path-scoped project rules."
---

# Language Rules System

## Overview

ai-toolkit ships rule content for 13 languages/platforms plus a language-agnostic common set. Source files live under `app/rules/` and are split into two delivery channels by `ai-toolkit install --local`:

- **Common rules** (`app/rules/common/*.md`): full content is written to `.claude/rules/ai-toolkit-*.md` with Claude Code `paths` frontmatter. The project's `.claude/CLAUDE.md` keeps only a compact `<!-- TOOLKIT:language-rules START -->` index. This follows Claude Code's current guidance to keep `CLAUDE.md` concise and move larger instruction sets into scoped rules.
- **Per-language rules** (`app/rules/<lang>/*.md`): emitted at build time as `<lang>-rules` knowledge skills under `app/skills/`. Each skill is `user-invocable: false`, so Claude loads it via the Agent Skills progressive-disclosure mechanism only when its description triggers match (file extensions, framework names, or matching keywords in the prompt).

The skills are generated from the rule files via `python3 scripts/generate_language_rules_skills.py`, which is idempotent and rerun-safe. Other editors (Cursor, Windsurf, Cline, Roo, Augment, Codex, Copilot, Antigravity, Gemini, opencode) still receive the full per-language rule content via their own generators in `scripts/dir_rules_shared.py::build_language_rules()` — Claude is the only target where the per-language content is now skill-delivered rather than inlined.

## File Structure

```
app/rules/
├── common/
│   ├── coding-style.md     # KISS, DRY, YAGNI, immutability
│   ├── testing.md          # Universal testing standards
│   ├── git-workflow.md     # Commit conventions
│   ├── performance.md      # Performance guidelines
│   └── security.md         # OWASP, input validation
├── typescript/
│   ├── coding-style.md     # Strict mode, no-any, naming
│   ├── testing.md          # Vitest/Jest patterns
│   ├── patterns.md         # Discriminated unions, utility types
│   ├── frameworks.md       # React hooks, Next.js, lifecycle
│   └── security.md         # XSS prevention, sanitization
├── python/
│   ├── coding-style.md     # PEP 8, type hints, dataclasses
│   ├── testing.md          # pytest, fixtures, parametrize
│   ├── patterns.md         # Python idioms, context managers
│   ├── frameworks.md       # FastAPI/Django lifecycle, SQLAlchemy
│   └── security.md         # SQL injection, SSTI prevention
├── golang/           # same 5-file structure
├── rust/
├── java/
├── kotlin/
├── swift/
├── dart/
├── csharp/
├── php/
├── cpp/
├── ruby/
└── medplum/
```

**Total: 13 per-language directories × 5 files + 1 common directory × 5 files + 3 standalone files** (see README.md for canonical count). Per-language directories ship as `<lang>-rules` knowledge skills; the common directory is installed as Claude Code `.claude/rules/ai-toolkit-*.md` files.

## Supported Languages

| Language | Directory | Auto-detect Files |
|----------|-----------|------------------|
| Common | `rules/common/` | always included |
| TypeScript | `rules/typescript/` | `package.json`, `tsconfig.json` |
| Python | `rules/python/` | `requirements.txt`, `pyproject.toml`, `setup.py`, `Pipfile` |
| Go | `rules/golang/` | `go.mod` |
| Rust | `rules/rust/` | `Cargo.toml` |
| Java | `rules/java/` | `pom.xml`, `build.gradle`, `build.gradle.kts` |
| Kotlin | `rules/kotlin/` | `build.gradle.kts` |
| Swift | `rules/swift/` | `Package.swift`, `*.xcodeproj` |
| Dart | `rules/dart/` | `pubspec.yaml` |
| C# | `rules/csharp/` | `*.csproj`, `*.sln` |
| PHP | `rules/php/` | `composer.json` |
| C++ | `rules/cpp/` | `CMakeLists.txt`, `Makefile`, `*.cpp` |
| Ruby | `rules/ruby/` | `Gemfile`, `*.gemspec` |
| Medplum | `rules/medplum/` | `medplum.config.mts`, `medplum.config.ts` |

## Rule Categories

| Category | Filename | Content |
|----------|----------|---------|
| `coding-style` | `coding-style.md` | Naming, formatting, idiomatic constructs, linter config |
| `testing` | `testing.md` | Test framework usage, fixture patterns, coverage targets |
| `patterns` | `patterns.md` | Language-specific design patterns and idioms |
| `frameworks` | `frameworks.md` | Recommended framework conventions and lifecycle hooks |
| `security` | `security.md` | Common language-specific vulnerabilities and mitigations |

The `common/` directory uses the same structure except `frameworks.md` is replaced by `git-workflow.md` and `performance.md`.

## Auto-Detection

`--local` automatically enables language auto-detection. `scripts/install_steps/detect_language.py` uses two-phase detection and merges results from both:

```bash
ai-toolkit install --local     # auto-detects language (--auto-detect is implied)
```

### Phase 1: Marker files (config-level signals)

Scans for configuration files defined in each module's `auto_detect` list in `manifest.json`:

1. `package.json` or `tsconfig.json` → TypeScript
2. `go.mod` → Go
3. `Cargo.toml` → Rust
4. `pubspec.yaml` → Dart
5. `composer.json` → PHP
6. `Gemfile` → Ruby
7. `requirements.txt`, `pyproject.toml`, `setup.py`, or `Pipfile` → Python
8. `pom.xml` or `build.gradle` → Java
9. `build.gradle.kts` → Kotlin
10. `Package.swift` → Swift
11. `*.csproj` or `*.sln` → C#
12. `CMakeLists.txt` or `Makefile` → C++
13. `medplum.config.mts` or `medplum.config.ts` → Medplum

### Phase 2: Source file extensions (actual code presence)

Scans top-level files and one directory level deep for source file extensions (`.py`, `.ts`, `.go`, `.rs`, `.java`, `.kt`, `.swift`, `.dart`, `.cs`, `.php`, `.cpp`, `.rb`, etc.). Skips dependency/build directories (`node_modules`, `venv`, `dist`, `build`, etc.) for speed.

This catches cases where marker files are misleading — e.g., a Python project with a `package.json` only for its npm CLI wrapper will correctly detect both Python (via `.py` files) and TypeScript (via `package.json`).

Both phases contribute; results are merged and deduplicated. Common rules are always injected regardless of detected language.

## Installation

```bash
# Auto-detect language from project files (default with --local)
ai-toolkit install --local

# Explicitly select a language (implies --local, disables auto-detect)
ai-toolkit install --local --lang typescript

# Multiple languages
ai-toolkit install --local --lang go,python

# Skip auto-detect, install specific modules only
ai-toolkit install --local --modules core,agents
```

The `--lang` flag accepts comma-separated language names and converts them to `rules-<lang>` modules. Common aliases are supported: `go` → `golang`, `c++` → `cpp`, `c#`/`cs` → `csharp`. Using `--lang` implies `--local` and disables auto-detection.

Common rules are installed as path-scoped Claude Code rule files:

```
.claude/rules/
├── ai-toolkit-coding-style.md
├── ai-toolkit-git-workflow.md
├── ai-toolkit-performance.md
├── ai-toolkit-security.md
└── ai-toolkit-testing.md
```

Each file starts with:

```yaml
---
paths:
  - "**/*"
---
```

The project `CLAUDE.md` receives only a compact index between a single named marker (the per-language markers from v1.x are no longer used):

```
<!-- TOOLKIT:language-rules START -->
# Language Rules

Common ai-toolkit rules live in `.claude/rules/ai-toolkit-*.md`
with Claude Code `paths` frontmatter so they load when project files
are opened instead of expanding this CLAUDE.md at session startup.

Common rule files: `.claude/rules/ai-toolkit-coding-style.md`, ...

Language-specific rules live in `<lang>-rules` knowledge skills (e.g.
`python-rules`, `typescript-rules`) and load automatically when their
triggers match.

Detected languages: `python-rules`, `typescript-rules`.
<!-- TOOLKIT:language-rules END -->
```

Re-running `install --local` is idempotent — the existing block is replaced, not duplicated, and only managed `.claude/rules/ai-toolkit-*.md` files are refreshed. User-authored `.claude/rules/*.md` files are preserved. Per-language rules are not injected into `CLAUDE.md` for Claude — they are loaded contextually via their respective `<lang>-rules` knowledge skills.

### Generating language-rules skills

The `<lang>-rules` skills under `app/skills/` are produced by:

```bash
python3 scripts/generate_language_rules_skills.py            # write all
python3 scripts/generate_language_rules_skills.py --check    # dry-run, exit 1 on diff
python3 scripts/generate_language_rules_skills.py --langs python,rust  # subset
```

The generator reads `app/rules/<lang>/*.md`, strips YAML frontmatter, concatenates the categories, and writes `app/skills/<lang>-rules/SKILL.md` with frontmatter:

- `name: <lang>-rules`
- `description: ...` — language label, rule categories, and concrete trigger keywords (file extensions, framework names) so the skill activates reliably when Claude is working on that language.
- `user-invocable: false` — knowledge skill, no slash command.
- `allowed-tools: Read` — the skill body is reference content, not an action.

Rerunning the generator is idempotent. Editing rule files under `app/rules/<lang>/` and rerunning the generator is the canonical way to update a language skill.

## Manifest Module Names

Language rules are tracked as modules in `manifest.json`:

| Module | Description |
|--------|-------------|
| `rules-common` | Common coding rules (5 files), included in `standard` profile |
| `rules-typescript` | TypeScript-specific rules |
| `rules-python` | Python-specific rules |
| `rules-golang` | Go-specific rules |
| `rules-rust` | Rust-specific rules |
| `rules-java` | Java-specific rules |
| `rules-kotlin` | Kotlin-specific rules |
| `rules-swift` | Swift-specific rules |
| `rules-dart` | Dart/Flutter-specific rules |
| `rules-csharp` | C#/.NET-specific rules |
| `rules-php` | PHP-specific rules |
| `rules-cpp` | C++-specific rules |
| `rules-ruby` | Ruby-specific rules |
| `rules-medplum` | Medplum/FHIR healthcare platform rules |

## Rules vs Skills

| | Common rules | Per-language rules | Other skills |
|---|---|---|---|
| Source | `app/rules/common/` | `app/rules/<lang>/` | `app/skills/<name>/SKILL.md` |
| Delivery to Claude | Path-scoped `.claude/rules/ai-toolkit-*.md` files (`--local`) + compact `CLAUDE.md` index | Generated as `<lang>-rules` knowledge skills, loaded contextually | Loaded contextually by description match |
| Visibility | Loaded when project files are opened | Loaded when triggers match (file extensions, framework names) | Loaded when triggers match |
| Scope | Language-agnostic standards (security, git, testing, perf, style) | Per-language coding-style, frameworks, patterns, security, testing | Domain skills (testing, debugging, RAG, etc.) |
| Install | `ai-toolkit install --local` | Global install (skills directory is symlinked) | Global install |
| Other editors | Inlined into editor-specific rule files | Inlined into editor-specific rule files (still full content, not skills) | N/A |

Per-language content delivered as a knowledge skill is the same Markdown that other editors receive inlined. The split exists only for Claude, where the Agent Skills progressive-disclosure mechanism keeps the system prompt small.

## Related Documentation

- [PATH: kb/reference/manifest-install.md] — module-level install granularity
- [PATH: kb/reference/extension-api.md] — injecting rules from external tools
- [PATH: kb/reference/architecture-overview.md] — overall install model

---

## kb/reference/licensing.md

---
title: "Licensing"
category: reference
service: ai-toolkit
tags: [licence, apache-2.0, spdx, notice, attribution, headers, mit]
version: "1.0.0"
created: "2026-07-27"
last_updated: "2026-07-27"
description: "ai-toolkit is Apache-2.0 from v4.20.0. What that obliges a redistributor to do, why NOTICE is the point, the SPDX header convention and which files deliberately do not get one, how MIT-era contributions are handled, and the CI gate that enforces all of it."
---

# Licensing

ai-toolkit is licensed under the **Apache License 2.0** from v4.20.0. Releases up
to and including v4.20.0 were published under MIT and remain available under MIT.
The change applies going forward and revokes nothing already granted.

Canonical files: [`LICENSE`](../../LICENSE) (verbatim Apache-2.0 text) and
[`NOTICE`](../../NOTICE) (attribution).

## Why Apache-2.0, given MIT already required attribution

This is the part most often got wrong. MIT already says:

> The above copyright notice and this permission notice shall be included in all
> copies or substantial portions of the Software.

So attribution was never the new thing. What Apache-2.0 adds:

| Mechanism | MIT | Apache-2.0 |
|---|---|---|
| Copyright notice must be preserved | yes | yes |
| **`NOTICE` contents must travel into redistributions** (§4d) | — | **yes** |
| **Modified files must carry a notice saying they changed** (§4b) | — | **yes** |
| Express patent grant, terminated by patent litigation (§3) | — | yes |
| No rights to the licensor's names or marks (§6) | — | yes |

**`NOTICE` is the reason for the change.** It is the only mechanism in a
permissive licence that forces a redistributor to reproduce your attribution —
project name, copyright, source URL — somewhere their users can see it. Without
it, MIT and Apache-2.0 are close to equivalent in practice.

Consequence for packaging: `NOTICE` is listed in `package.json` `files`. A NOTICE
that does not reach the consumer cannot satisfy §4(d), so that entry is a
licensing requirement, not housekeeping, and is asserted in CI.

## What a fork owes

Fork it, modify it, ship it commercially. Three obligations:

1. **Carry the `NOTICE`** into your distribution (§4d).
2. **Say which files you changed** (§4b).
3. **Do not use the "ai-toolkit" or "SoftSpark" names or marks** as if endorsed (§6).

## Source header convention

Short SPDX form, three lines, always **after** the shebang — an interpreter
directive must stay on line 1 — and after a Python `coding:` line if present:

```bash
#!/usr/bin/env bash
# SPDX-License-Identifier: Apache-2.0
# Copyright 2024-2026 Lukasz Krzemien (biuro@softspark.eu)
# Source: https://github.com/softspark/ai-toolkit
#
# guard-path.sh — the file's own description continues here.
```

`//` for JavaScript. SPDX was chosen over the 13-line Apache APPENDIX boilerplate
because it is machine-readable — licence scanners, GitHub and SBOM tooling parse
it — and because 13 lines on top of every source file buries the description that a
reader of a hook actually needs.

### Which files get a header

| Included | Count |
|---|---:|
| `scripts/**/*.py` | 109 |
| `tests/*.bats` | 77 |
| `app/hooks/*.sh` | 32 |
| `app/skills/**/*.py`, `**/*.js` | 27 |
| `app/plugins/**/*.sh`, `**/*.py` | 6 |
| `bin/*.js`, `benchmarks/**/*.py` | 2 |
| **total** | **253** |

These are a snapshot, not a contract — the CI gate checks that *every* matching
file has a header, so the count moves with the codebase and nothing needs
updating here when it does.

### Which files deliberately do not, and why

**No markdown file carries a header.** Not `app/skills/*/SKILL.md`, not
`app/agents/*.md`, not `app/rules/`, not `kb/`. Two reasons, both concrete:

1. **Frontmatter.** Skill and agent files open with parsed YAML. A header above
   it breaks parsing; a header below it is invisible where it matters.
2. **Token cost.** Skill and agent descriptions load into the system prompt of
   every session — measured at 5,051 and 2,750 tokens respectively. A four-line
   header across 108 skills and 45 agents would be a permanent per-session cost,
   billed on every conversation forever, for a notice Apache only *recommends*.
   `LICENSE` and `NOTICE` carry the full terms; the headers are a convenience.

This exclusion is asserted in CI, so a well-meant sweep of the header script over
`app/skills/` fails the build rather than silently taxing every session.

## MIT-era contributions

Contributions made while the project was MIT-licensed remain the copyright of
their authors and were received under MIT terms. Three contributors other than
the maintainer appear in the history.

MIT explicitly permits sublicensing, so those contributions are redistributed
here under Apache-2.0 **with the original MIT notice preserved verbatim** in
`NOTICE`, which is what MIT requires. This is standard practice for an MIT to
Apache-2.0 move and needs no contributor sign-off. A "clean" Apache-2.0 with no
MIT remnant would need each contributor's agreement.

*This is a description of what the project does, not legal advice.*

## Enforcement

`tests/test_licensing.bats`, seven assertions, run by `npm test` in CI:

- every shipped source file carries an SPDX header
- headers name Apache-2.0 and nothing else
- **no** markdown file carries a header
- `LICENSE` is the complete Apache 2.0 text, appendix included
- `NOTICE` carries attribution, the source URL, §4(d) and the MIT-era notice
- `LICENSE` and `NOTICE` both appear in `package.json` `files`
- every manifest declaring a licence declares Apache-2.0

It is a test rather than a checklist line on purpose. This project has two
same-day postmortems about SOPs that existed and were skipped; CI does not skip.
[Release Preparation](../procedures/release-preparation-sop.md) Phase 5c runs the
same gate before tagging so a failure surfaces before the tag, not after.

## If the licence ever changes again

Do not hand-type the licence text and do not paste a rendered copy — a
markdown-formatted licence is not the licence. Take it verbatim from a published
source, cross-verify against a second independent copy, and only then write
`LICENSE`. That is how the Apache-2.0 text in this repository was installed.

## Related

- [`LICENSE`](../../LICENSE), [`NOTICE`](../../NOTICE)
- [Release Preparation SOP](../procedures/release-preparation-sop.md) — Phase 5c
- [Distribution Model](distribution-model.md) — what ships and where

---

## kb/reference/manifest-install.md

---
title: "Manifest-Driven Install System"
category: reference
service: ai-toolkit
tags: [install, manifest, modules, profiles, auto-detect, state-tracking]
version: "1.0.0"
created: "2026-04-07"
last_updated: "2026-04-07"
description: "Reference for the manifest-driven install system: 17 modules, 4 profiles, auto-detection, and state tracking in ~/.softspark/ai-toolkit/state.json."
---

# Manifest-Driven Install System

## Overview

ai-toolkit's install system supports module-level granularity on top of the existing profile-based install. Instead of choosing only between minimal/standard/strict, you can select individual modules (specific language rules, MCP templates, etc.) or enable auto-detection of the project language.

All existing `--profile` behavior is preserved and unchanged. The manifest system is an additive opt-in layer.

## Modules

Modules are defined in `manifest.json` at the repository root. There are 17 modules:

| Module | Description | In Profile |
|--------|-------------|-----------|
| `core` | Core hooks and essential skills | minimal, standard, strict, full |
| `agents` | Specialized agents | standard, strict, full |
| `skills` | All skills (task, hybrid, knowledge) | standard, strict, full |
| `rules-common` | Common coding rules (5 files) | standard, strict, full |
| `rules-typescript` | TypeScript-specific rules (5 files) | auto-detect |
| `rules-python` | Python-specific rules (5 files) | auto-detect |
| `rules-golang` | Go-specific rules (5 files) | auto-detect |
| `rules-rust` | Rust-specific rules (5 files) | auto-detect |
| `rules-java` | Java-specific rules (5 files) | auto-detect |
| `rules-kotlin` | Kotlin-specific rules (5 files) | auto-detect |
| `rules-swift` | Swift-specific rules (5 files) | auto-detect |
| `rules-dart` | Dart/Flutter-specific rules (5 files) | auto-detect |
| `rules-csharp` | C#/.NET-specific rules (5 files) | auto-detect |
| `rules-php` | PHP-specific rules (5 files) | auto-detect |
| `rules-cpp` | C++-specific rules (5 files) | auto-detect |
| `rules-ruby` | Ruby-specific rules (5 files) | auto-detect |
| `mcp-templates` | 26 MCP server config templates | strict, full |

## Profiles

Profiles are predefined module sets. They map directly to `--profile` values:

| Profile | Modules |
|---------|---------|
| `minimal` | `core` |
| `standard` | `core`, `agents`, `skills`, `rules-common` |
| `strict` | `core`, `agents`, `skills`, `rules-common`, `mcp-templates` |
| `full` | All modules (same as strict currently; language rules added via `--auto-detect`) |

## CLI

```bash
# Profile-based install (existing behavior, unchanged)
ai-toolkit install --profile standard

# Module-based install (new)
ai-toolkit install --modules core,agents,rules-typescript

# --local implies --auto-detect (language rules auto-detected)
ai-toolkit install --local

# Show currently installed modules and their state
ai-toolkit status

# Incremental update (only re-applies modules with changed content)
ai-toolkit update
```

### --modules

Accepts a comma-separated list of module names. Can be combined with a profile:

```bash
# Start from standard profile, also add TypeScript rules
ai-toolkit install --profile standard --modules rules-typescript
```

### --auto-detect

Scans the current working directory for marker files and selects the matching language module. Implemented in `scripts/install_steps/detect_language.py`.

Detection markers per module:

| Module | Detected when these files exist |
|--------|--------------------------------|
| `rules-typescript` | `package.json` or `tsconfig.json` |
| `rules-python` | `requirements.txt`, `pyproject.toml`, `setup.py`, or `Pipfile` |
| `rules-golang` | `go.mod` |
| `rules-rust` | `Cargo.toml` |
| `rules-java` | `pom.xml` or `build.gradle` |
| `rules-kotlin` | `build.gradle.kts` |
| `rules-swift` | `Package.swift` |
| `rules-dart` | `pubspec.yaml` |
| `rules-csharp` | `*.csproj` or `*.sln` |
| `rules-php` | `composer.json` |
| `rules-cpp` | `CMakeLists.txt` or `Makefile` |
| `rules-ruby` | `Gemfile` |

### status

Lists all currently installed modules with version and install timestamp:

```bash
ai-toolkit status
# Installed modules (from ~/.softspark/ai-toolkit/state.json):
#   core            v1.3.0   installed 2026-04-07T10:00:00Z
#   agents          v1.3.0   installed 2026-04-07T10:00:00Z
#   skills          v1.3.0   installed 2026-04-07T10:00:00Z
#   rules-common    v1.3.0   installed 2026-04-07T10:00:00Z
#   rules-typescript v1.3.0  installed 2026-04-07T10:00:00Z
```

### update

Re-applies installed modules, skipping files whose content hash has not changed since last install. Implemented in `scripts/install_steps/install_state.py`.

## State Tracking

Installed module state is persisted to `~/.softspark/ai-toolkit/state.json`:

```json
{
  "installed_version": "1.3.0",
  "installed_modules": ["core", "agents", "skills", "rules-common", "rules-typescript"],
  "installed_at": "2026-04-07T10:00:00Z",
  "last_updated": "2026-04-07T10:00:00Z",
  "file_hashes": {
    "app/hooks/session-start.sh": "abc123..."
  }
}
```

- `installed_modules` — used by `update` to know which modules to re-apply
- `file_hashes` — used to skip unchanged files during `update`
- The file is written after every successful install or update

## Implementation Files

| File | Purpose |
|------|---------|
| `manifest.json` | Module and profile definitions |
| `scripts/install_steps/detect_language.py` | Auto-detect project language from marker files |
| `scripts/install_steps/install_state.py` | Read/write `~/.softspark/ai-toolkit/state.json` |

## Backward Compatibility

Existing `--profile` usage works identically. The manifest system does not change what gets installed when you use `--profile minimal/standard/strict`. It only adds:

1. `--modules` for granular selection
2. `--auto-detect` for language rules
3. `state.json` tracking for incremental updates
4. `status` command to inspect installed state

No existing install scripts or CI configurations need changes.

## Related Documentation

- [PATH: kb/reference/language-rules.md] — language rules structure and auto-detection detail
- [PATH: kb/reference/mcp-templates.md] — MCP server templates (the `mcp-templates` module)
- [PATH: kb/reference/architecture-overview.md] — overall install model

---

## kb/reference/mcp-editor-compatibility.md

---
title: "AI Toolkit - MCP Editor Compatibility"
category: reference
service: ai-toolkit
tags: [mcp, editors, compatibility, codex, cursor, antigravity]
version: "1.3.0"
created: "2026-04-12"
last_updated: "2026-07-14"
description: "Official MCP support matrix and native config targets for editors supported by ai-toolkit."
---

# MCP Editor Compatibility

## Overview

ai-toolkit keeps `.mcp.json` as the project-level canonical template format and can render that config into native editor MCP files where the editor exposes a stable, documented configuration surface.

## Supported Native Adapters

| Editor | Scope | Native Config Path | Adapter Behavior |
|--------|-------|--------------------|------------------|
| Claude Code | project + global | `.claude/settings.local.json`, `~/.claude/settings.json` | Merges `mcpServers` while preserving other settings keys |
| Cursor | project + global | `.cursor/mcp.json`, `~/.cursor/mcp.json` | Mirrors `mcpServers` directly |
| GitHub Copilot | project + global | `.github/mcp.json`, `$COPILOT_HOME/mcp-config.json` (default `~/.copilot/mcp-config.json`) | Adds Copilot-required `type` and `tools` fields |
| Gemini CLI | project + global | `.gemini/settings.json`, `~/.gemini/settings.json` | Merges `mcpServers` into settings JSON |
| Google Antigravity | project + global | `.agents/mcp_config.json`, `~/.gemini/config/mcp_config.json` | Preserves documented `command`, `serverUrl`, and `url` transports plus optional authentication, disablement, and tool-filter fields |
| Roo Code | project | `.roo/mcp.json` | Mirrors `mcpServers` into the documented project-level MCP file |
| Windsurf | global | `~/.codeium/windsurf/mcp_config.json` | Global-only JSON config |
| Cline | global | `~/.cline/data/settings/cline_mcp_settings.json` | Global-only JSON config |
| Augment | global | `~/.augment/settings.json` | Global-only JSON settings file |
| Codex CLI | project + global | `.codex/config.toml`, `$CODEX_HOME/config.toml` (default `~/.codex/config.toml`) | Renders validated TOML `mcp_servers` tables inside a managed block while preserving unrelated bytes and comments |

## Unsupported for Automatic Install

These editors are still supported by ai-toolkit for rules and instructions, but ai-toolkit does not currently auto-write MCP config because a stable official file target was not adopted:

| Editor | Reason |
|--------|--------|
| Aider | No verified native MCP config surface was adopted in ai-toolkit |

## CLI

```bash
ai-toolkit mcp editors
ai-toolkit mcp install --editor cursor --scope project github --target .
ai-toolkit mcp install --editor antigravity --scope project context7 --target .
ai-toolkit mcp install --editor codex --scope project context7 --target .
ai-toolkit mcp install --editor codex context7
ai-toolkit mcp remove github --editor cursor --scope project --target .
```

## Install Flow Integration

When `.mcp.json` exists in a project, `ai-toolkit install --local` mirrors its servers into:
- `.claude/settings.local.json`
- `.cursor/mcp.json` when `--editors cursor` is selected
- `.github/mcp.json` when `--editors copilot` is selected
- `.agents/mcp_config.json` when `--editors antigravity` is selected
- `.roo/mcp.json` when `--editors roo` is selected
- `.codex/config.toml` when `--editors codex` is selected; project config is
  active only after the repository `.codex` layer is trusted

Codex project and user config preserve unrelated TOML text. ai-toolkit owns only
the marker-bounded MCP block it generates. Invalid TOML, unsupported transport
fields, and symlinked config roots are rejected without rewriting the file.
Portable `type` metadata is translated only when it matches the Codex transport:
`http` requires `url`, while `local` and `stdio` require `command`. The adapter
removes that metadata from native TOML and rejects SSE, unknown types, and
conflicting transport fields before writing.

Antigravity project and global configs preserve unrelated top-level keys and
user-owned servers. The adapter accepts both `serverUrl` and `url` for remote
servers, as documented by the Antigravity 2.1.4 changelog, but rejects the
unsupported legacy `httpUrl` field before any file in the transaction changes.

`CODEX_HOME` and `COPILOT_HOME` replace their editors' default user config
roots. They never relocate project files.

Global-only clients are configured explicitly via `ai-toolkit mcp install --editor ...`.

## Related

- [PATH: kb/reference/mcp-templates.md] — template catalog and CLI
- [PATH: kb/reference/extension-api.md] — extension API surface

---

## kb/reference/mcp-templates.md

---
title: "MCP Server Templates"
category: reference
service: ai-toolkit
tags: [mcp, templates, servers, configuration, editors, inject-mcp, external-templates]
version: "1.4.0"
created: "2026-04-07"
last_updated: "2026-07-14"
description: "Reference for 26 built-in MCP server templates, external template injection via inject-mcp, and native editor MCP installation support."
---

# MCP Server Templates

## Overview

ai-toolkit ships 26 ready-to-use MCP server configuration templates in `app/mcp-templates/`. Each template is a JSON file that defines the canonical `mcpServers` block for a specific service. Templates can be merged into the project's `.mcp.json` and rendered into editor-native MCP config files via the `ai-toolkit mcp` CLI subcommand.

**External templates:** Tools outside the toolkit (MCP servers, plugins, custom integrations) can register their own MCP templates via `ai-toolkit inject-mcp <file|url>` -- the toolkit caches the template, tags every server with a `_source` field, and propagates the config to every editor that exposes a `global_path`. URL-sourced templates are auto-refreshed on every `ai-toolkit update`. See [PATH: kb/reference/extension-api.md] for the inject-mcp / remove-mcp reference.

## CLI

```bash
ai-toolkit mcp list               # List all available templates
ai-toolkit mcp editors            # List editors with native MCP adapters
ai-toolkit mcp show <name>        # Print a template's JSON config
ai-toolkit mcp add <name>         # Merge a template into .mcp.json
ai-toolkit mcp add <n1> <n2>      # Add multiple templates at once
ai-toolkit mcp install --editor cursor --scope project github --target .
ai-toolkit mcp install --editor antigravity --scope project context7 --target .
ai-toolkit mcp install --editor codex --scope project context7 --target .
ai-toolkit mcp install --editor codex context7
ai-toolkit mcp remove <name>      # Remove from .mcp.json or native editor config
```

**Implementation:** `scripts/mcp_manager.py`

The `add` command merges the `mcpServers` block from the template into `.mcp.json`. If `.mcp.json` does not exist it is created. If the server name already exists in `.mcp.json`, the entry is overwritten with the template version.

The `install` command renders the same canonical template into an editor-native config format:
- JSON clients with `mcpServers` blocks: Claude Code, Cursor, Gemini CLI, Google Antigravity, Roo Code, Windsurf, Cline, Augment
- JSON clients with additional transport metadata: GitHub Copilot
- TOML clients: Codex CLI (`[mcp_servers.<name>]`)

When `install` runs with `--scope project`, ai-toolkit also updates the project's `.mcp.json` so it remains the source of truth for later syncs.

## Editor Support Matrix

| Editor | Scope | Native Config Path | Notes |
|--------|-------|--------------------|-------|
| `claude` | project + global | `.claude/settings.local.json`, `~/.claude/settings.json` | Preserves existing hooks and env keys |
| `cursor` | project + global | `.cursor/mcp.json`, `~/.cursor/mcp.json` | Mirrors canonical `mcpServers` |
| `copilot` | project + global | `.github/mcp.json`, `$COPILOT_HOME/mcp-config.json` (default `~/.copilot/mcp-config.json`) | Adds `type` and `tools: ["*"]` automatically |
| `gemini` | project + global | `.gemini/settings.json`, `~/.gemini/settings.json` | Uses Gemini CLI `mcpServers` format |
| `antigravity` | project + global | `.agents/mcp_config.json`, `~/.gemini/config/mcp_config.json` | Preserves `url` or `serverUrl` remote transports and Antigravity authentication/tool-control fields |
| `roo` | project | `.roo/mcp.json` | Mirrors canonical `mcpServers` into Roo's project MCP file |
| `windsurf` | global | `~/.codeium/windsurf/mcp_config.json` | Global-only official config |
| `cline` | global | `~/.cline/data/settings/cline_mcp_settings.json` | Global-only official config |
| `augment` | global | `~/.augment/settings.json` | Global-only settings file |
| `codex` | project + global | `.codex/config.toml`, `$CODEX_HOME/config.toml` (default `~/.codex/config.toml`) | Validated TOML `mcp_servers` tables in a marker-bounded managed block; unrelated TOML/comments preserved |

Project-local `ai-toolkit install --local` also mirrors `.mcp.json` into Claude
project settings plus selected project editors that have official
repository/workspace MCP files (`cursor`, `copilot`, `antigravity`, `roo`, `codex`). Codex
loads `.codex/config.toml` only for trusted project layers.

## Template List

| Name | Description | Required Env Vars |
|------|-------------|-------------------|
| `brave-search` | Web and local search powered by Brave Search API | `BRAVE_API_KEY` |
| `cloudflare` | Cloudflare Workers, KV, D1, R2, and DNS management | `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID` |
| `context7` | Up-to-date library documentation lookup via Context7 | — |
| `custom-template` | Empty template for building a custom MCP server | `API_KEY` (placeholder) |
| `datadog` | Datadog monitoring: metrics, logs, traces, dashboard queries | `DD_API_KEY`, `DD_APP_KEY`, `DD_SITE` |
| `docker` | Docker container and image management, logs, compose operations | — |
| `fetch` | HTTP fetch for web pages and API responses as markdown or raw content | — |
| `filesystem` | Local filesystem access for reading, writing, and searching files | — |
| `git` | Git repository inspection: diffs, logs, branches | — |
| `github` | GitHub API: issues, PRs, repos, code search | `GITHUB_PERSONAL_ACCESS_TOKEN` |
| `google-drive` | Google Drive file search, reading, and management | `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `GOOGLE_REDIRECT_URI` |
| `google-maps` | Google Maps geocoding, directions, place search | `GOOGLE_MAPS_API_KEY` |
| `grafana` | Grafana dashboard queries, alerting, and data source management | `GRAFANA_URL`, `GRAFANA_API_KEY` |
| `linear` | Linear issue tracker: issues, projects, team workflows | `LINEAR_API_KEY` |
| `memory` | Persistent memory store using a local knowledge graph | — |
| `notion` | Notion workspace: pages, databases, content management | `NOTION_API_KEY` |
| `postgres` | PostgreSQL database access, schema inspection, analysis | — |
| `puppeteer` | Browser automation: screenshots, navigation, web scraping | — |
| `redis` | Redis cache inspection, data management, and monitoring | `REDIS_URL` |
| `sentry` | Sentry error tracking: issue search, event details, alerting | `SENTRY_AUTH_TOKEN`, `SENTRY_ORG` |
| `sequential-thinking` | Step-by-step reasoning and problem decomposition | — |
| `slack` | Slack workspace: channels, messages, users | `SLACK_BOT_TOKEN`, `SLACK_TEAM_ID` |
| `sqlite` | SQLite database access, queries, schema management | — |
| `supabase` | Supabase project management, database queries, edge functions | `SUPABASE_URL`, `SUPABASE_SERVICE_ROLE_KEY` |
| `vercel` | Vercel deployment management, project settings, environment variables | `VERCEL_TOKEN` |

## Template Format

Each template is a JSON file with the following structure:

```json
{
  "name": "example",
  "description": "Human-readable description of what this server provides",
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-example"],
      "env": {
        "EXAMPLE_API_KEY": "${EXAMPLE_API_KEY}"
      }
    }
  }
}
```

- `name` — identifier used with `mcp add <name>`
- `description` — shown by `mcp list` and `mcp show`
- `mcpServers` — the block merged verbatim into `.mcp.json`
- `env` values use `${VAR_NAME}` placeholders that must be set in the shell environment or `.env` file before Claude Code starts

## Example: Adding GitHub and PostgreSQL

```bash
# Add templates
ai-toolkit mcp add github postgres

# Set required env vars (e.g., in .env or shell profile)
export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_...

# Resulting .mcp.json contains both mcpServers entries
```

## Contributing a New Template

1. Create `app/mcp-templates/<name>.json` following the format above.
2. Use `${ENV_VAR}` placeholders for secrets — never hardcode values.
3. Keep the `name` field identical to the filename stem.
4. Run `python3 scripts/validate.py` to verify the file is valid JSON.
5. Add an entry to this document's template list table.

## Related Documentation

- [PATH: kb/reference/extension-api.md] — `mcp add` as part of the extension API
- [PATH: kb/reference/architecture-overview.md] — overall install model
- [PATH: kb/reference/mcp-editor-compatibility.md] — native editor MCP support matrix

---

## kb/reference/medplum-docs-map.md

---
title: "Medplum Documentation Map"
category: reference
service: ai-toolkit
tags: [medplum, fhir, healthcare, ehr, sdk, api, clinical, interoperability]
version: "1.0.0"
created: "2026-04-17"
last_updated: "2026-04-17"
description: "Comprehensive navigable index of Medplum documentation covering SDK, FHIR resources, clinical workflows, security, integrations, and terminology."
---

# Medplum Documentation Map

## Overview

Medplum is an open-source healthcare platform built on FHIR R4. It provides a FHIR-compliant datastore, TypeScript SDK, React component library, bot automation engine, and compliance infrastructure (HIPAA, SOC2, HITRUST).

| Item | Value |
|------|-------|
| Docs | `https://www.medplum.com/docs/` |
| API Base | `https://api.medplum.com/fhir/R4/` |
| App | `https://app.medplum.com/` |
| Storybook | `https://storybook.medplum.com/` |
| GraphiQL | `https://graphiql.medplum.com/` |

### Key Packages

| Package | Purpose |
|---------|---------|
| `@medplum/core` | SDK client, FHIR helpers, FHIRPath, HL7 parsing |
| `@medplum/fhirtypes` | TypeScript type definitions for all FHIR R4 resources |
| `@medplum/react` | React UI components (Mantine 7+, React 18+) |
| `@medplum/mock` | MockClient for unit testing |
| `@medplum/cli` | Command-line interface for FHIR operations |

---

## Documentation Sections

| Section | Path | Description |
|---------|------|-------------|
| FHIR Basics | `/docs/fhir-basics` | Resources, references, search, CodeableConcepts, identifiers, ValueSets, Subscriptions |
| FHIR Datastore | `/docs/fhir-datastore` | CRUD, binary data, batch requests, profiles, history, deduplication, USCDI |
| Search | `/docs/search` | Basic search, advanced parameters, `_filter`, pagination, `_include`/`_revinclude`, chaining |
| Terminology | `/docs/terminology` | CodeSystem, ValueSet, ConceptMap operations; LOINC, SNOMED, ICD-10 |
| GraphQL | `/docs/graphql` | Queries, mutations, connections, nested resolution, reverse references, array filtering |
| React Components | `/docs/react` | MedplumProvider, hooks, Mantine integration, tree-shaking, useSubscription |
| Analytics | `/docs/analytics` | Analytics and reporting capabilities |
| Auth | `/docs/auth` | OAuth2 flows, client credentials, external IDPs, Google, mTLS, MFA, token exchange, sessions |
| User Management | `/docs/user-management` | Project vs server users, registration, invitations |
| Access Control | `/docs/access` | Access policies, compartments, SMART scopes, IP rules, multi-tenant, field-level control |
| AI | `/docs/ai` | AI operations, AWS integration, MCP server |
| Bots | `/docs/bots` | Bot basics, cron jobs, questionnaire handlers, Lambda layers, secrets, webhooks, HL7, PDFs, unit testing |
| Subscriptions | `/docs/subscriptions` | Event-driven notifications, WebSocket, webhook resending |
| CLI | `/docs/cli` | Command-line FHIR operations, external servers |
| Integrations | `/docs/integration` | DoseSpot, Health Gorilla, Stedi, Candid Health, eFax, HL7, FHIRcast, SMART, CDS Hooks, C-CDA |
| Agent | `/docs/agent` | On-prem agent for HL7/DICOM bridging |
| Self-Hosting | `/docs/self-hosting` | Self-hosted deployment |
| Compliance | `/docs/compliance` | HIPAA, SOC2, HITRUST, ONC, CLIA/CAP, CFR11, GMP, ISO9001 |
| API Reference | `/docs/api` | REST endpoints, FHIR resources (150+), operations (40+), datatypes (40+), Medplum custom resources |
| SDK Reference | `/docs/sdk/core` | MedplumClient, utility functions, interfaces, types |

---

## Clinical Workflows

| Workflow | Path | Key Resources |
|----------|------|---------------|
| Intake & Registration | `/docs/intake` | Patient, QuestionnaireResponse, Encounter |
| Charting | `/docs/charting` | Condition, AllergyIntolerance, Observation (vitals), DocumentReference |
| Scheduling | `/docs/scheduling` | Schedule, Slot, Appointment, AppointmentResponse |
| Labs & Imaging | `/docs/labs-imaging` | ServiceRequest, DiagnosticReport, Observation, ImagingStudy |
| Medications | `/docs/medications` | MedicationRequest, Medication, MedicationAdministration |
| Care Plans | `/docs/careplans` | CarePlan, CareTeam, Task, PlanDefinition, Goal |
| Communications | `/docs/communications` | Communication, CommunicationRequest (threads, messaging, SMS) |
| Billing | `/docs/billing` | Claim, Coverage, ExplanationOfBenefit, ChargeItem |

### Clinical Configuration

| Feature | Path | Resources |
|---------|------|-----------|
| Provider Directory | `/docs/administration/provider-directory` | Practitioner, PractitionerRole, Organization, Location |
| Questionnaires | `/docs/questionnaires` | Questionnaire, QuestionnaireResponse, SDC extensions |
| Diagnostic Catalog | `/docs/careplans/diagnostic-catalog` | CodeSystem, ValueSet (LOINC panels) |
| Clinical Protocols | `/docs/careplans/protocols` | PlanDefinition, ActivityDefinition |

---

## SDK Reference — MedplumClient

### CRUD Operations

| Method | Description |
|--------|-------------|
| `createResource(resource)` | Create new FHIR resource (server assigns ID) |
| `readResource(resourceType, id)` | Read resource by type and ID |
| `updateResource(resource)` | Update existing resource (must include ID) |
| `patchResource(resourceType, id, operations)` | Apply JSON Patch operations |
| `deleteResource(resourceType, id)` | Delete resource by type and ID |
| `upsertResource(resource, query)` | Atomic create-or-update via search query |
| `createResourceIfNoneExist(resource, query)` | Conditional create if no match found |

### Search

| Method | Description |
|--------|-------------|
| `search(resourceType, query)` | Execute FHIR search, returns Bundle |
| `searchResources(resourceType, query)` | Returns resource array (unwrapped Bundle) |
| `searchOne(resourceType, query)` | Returns first matching resource |
| `searchResourcePages(resourceType, query)` | Async generator for paginated results |
| `fhirSearchUrl(resourceType, query)` | Build search URL from parameters |

### Authentication

| Method | Description |
|--------|-------------|
| `startLogin(loginRequest)` | Initiate user login flow |
| `startClientLogin(clientId, clientSecret)` | OAuth2 client credentials flow |
| `startGoogleLogin(loginRequest)` | Google Sign-In authentication |
| `setAccessToken(accessToken, refreshToken)` | Manually set auth tokens |
| `setBasicAuth(clientId, clientSecret)` | Configure basic auth |
| `signOut()` | Revoke token and clear cache |
| `isAuthenticated(gracePeriod)` | Check current auth status |
| `getProfile()` | Get current user profile (sync) |
| `getProfileAsync()` | Get current user profile (async fetch) |

### Advanced Operations

| Method | Description |
|--------|-------------|
| `executeBatch(bundle)` | Process batch or transaction Bundle |
| `executeBot(id, body, contentType)` | Run bot by ID or Identifier |
| `graphql(query, operationName, variables)` | Execute GraphQL queries |
| `readHistory(resourceType, id)` | Get all resource versions |
| `readPatientEverything(id)` | Patient $everything operation |
| `validateResource(resource)` | Validate resource against profiles |
| `valueSetExpand(params)` | Expand ValueSet for code lookups |
| `readResourceGraph(resourceType, id, graphName)` | Fetch linked resources via $graph |

### Media & Files

| Method | Description |
|--------|-------------|
| `createBinary(data, filename, contentType)` | Create Binary resource from data |
| `createAttachment(data, filename, contentType)` | Create Attachment element with Binary |
| `createPdf(docDefinition, filename)` | Generate PDF as Binary (pdfmake) |
| `uploadMedia(contents, contentType, filename)` | Upload and create Media resource |
| `download(url)` | Download URL as blob |

### Subscriptions & Real-time

| Method | Description |
|--------|-------------|
| `subscribeToCriteria(criteria, props)` | Subscribe to WebSocket notifications |
| `unsubscribeFromCriteria(criteria, props)` | Unsubscribe from criteria |
| `getSubscriptionManager()` | Access WebSocket subscription manager |

---

## SDK Utility Functions

| Function | Description |
|----------|-------------|
| `createReference(resource)` | Create a FHIR Reference from a resource |
| `getReferenceString(resource)` | Get `ResourceType/id` string |
| `getDisplayString(resource)` | Human-readable display for any resource |
| `formatHumanName(name)` | Format FHIR HumanName as string |
| `formatAddress(address)` | Format FHIR Address as string |
| `formatCodeableConcept(cc)` | Format CodeableConcept as string |
| `formatDate(date)` | Format FHIR date as human-readable |
| `formatDateTime(dateTime)` | Format FHIR dateTime as human-readable |
| `formatQuantity(quantity)` | Human-readable Quantity string |
| `getCodeBySystem(cc, system)` | Find code for a given system in CodeableConcept |
| `setCodeBySystem(cc, system, code)` | Set code for a given system |
| `getIdentifier(resource, system)` | Get identifier value for a system |
| `setIdentifier(resource, system, value)` | Set identifier for a system |
| `getExtension(resource, urls)` | Get extension by URL |
| `getExtensionValue(resource, urls)` | Get extension value by URL |
| `parseReference(ref)` | Parse reference string to ResourceType/ID |
| `resolveId(reference)` | Extract ID from reference |
| `isResource(value)` | Type guard for FHIR resource |
| `isReference(value)` | Type guard for FHIR Reference |
| `deepClone(value)` | Deep clone a FHIR resource |
| `deepEquals(a, b)` | Compare resources (ignoring versionId) |
| `normalizeOperationOutcome(error)` | Normalize error to OperationOutcome |
| `normalizeErrorString(error)` | Normalize error to displayable string |
| `getQuestionnaireAnswers(response)` | Extract answers as map by linkId |
| `evalFhirPath(expression, resource)` | Evaluate FHIRPath expression |
| `validateResource(resource)` | Validate against StructureDefinition |
| `generateId()` | Cross-platform UUID generator |

---

## FHIR Search Syntax

### Parameter Types

| Type | Behavior | Example |
|------|----------|---------|
| `string` | Case-insensitive prefix match | `name=eve` matches Eve, Evelyn |
| `token` | Exact match, supports system namespace | `identifier=http://sys\|val` |
| `date` | Supports comparison prefixes | `birthdate=1940-03-29` |
| `reference` | Links to other resources | `subject=Patient/123` |
| `quantity` | Numeric with units | `value-quantity=gt40` |
| `number` | Plain numeric | `probability=gt0.8` |

### Operators

| Operator | Syntax | Example |
|----------|--------|---------|
| AND | Multiple parameters | `name=Simpson&birthdate=1940-03-29` |
| OR | Comma-separated | `status=completed,cancelled` |

### Modifiers

| Modifier | Purpose | Example |
|----------|---------|---------|
| `:not` | Exclude values | `status:not=completed` |
| `:missing` | Include/exclude absent params | `birthdate:missing=true` |
| `:contains` | Substring match (string only) | `name:contains=eve` |
| `:exact` | Case-sensitive exact match | `name:exact=Eve` |

### Comparison Prefixes (date, quantity, number)

| Prefix | Meaning |
|--------|---------|
| `eq` | Equal (default) |
| `ne` | Not equal |
| `gt` | Greater than |
| `lt` | Less than |
| `ge` | Greater than or equal |
| `le` | Less than or equal |
| `sa` | Starts after |
| `eb` | Ends before |

### Special Parameters

| Parameter | Purpose | Example |
|-----------|---------|---------|
| `_sort` | Sort results (prefix `-` for descending) | `_sort=-_lastUpdated` |
| `_count` | Results per page | `_count=20` |
| `_offset` | Pagination offset | `_offset=40` |
| `_total` | Include total count | `_total=accurate` |
| `_include` | Include forward-referenced resources | `_include=Observation:patient` |
| `_revinclude` | Include backward-referencing resources | `_revinclude=Provenance:target` |
| `_include:iterate` | Recursive inclusion (multi-hop) | `_include:iterate=Patient:general-practitioner` |

---

## Core FHIR Resources

### Clinical

| Resource | Purpose |
|----------|---------|
| `Patient` | Demographics, identifiers, contacts |
| `Practitioner` | Provider demographics, qualifications |
| `PractitionerRole` | Provider role at organization/location |
| `Organization` | Healthcare organization |
| `Encounter` | Patient visit or interaction |
| `Condition` | Diagnosis or health concern |
| `Observation` | Measurements, vitals, lab results |
| `DiagnosticReport` | Lab/imaging report aggregating observations |
| `ServiceRequest` | Order for a procedure, lab, or referral |
| `MedicationRequest` | Prescription or medication order |
| `AllergyIntolerance` | Allergy or adverse reaction record |
| `Procedure` | Performed clinical procedure |
| `CarePlan` | Treatment plan with activities and goals |
| `CareTeam` | Group of practitioners caring for a patient |
| `Goal` | Patient health objective |
| `Task` | Actionable work item |

### Administrative

| Resource | Purpose |
|----------|---------|
| `Schedule` | Provider availability container |
| `Slot` | Bookable time block within a Schedule |
| `Appointment` | Scheduled visit with participants |
| `Coverage` | Insurance/payer information |
| `Claim` | Billing claim submission |
| `Communication` | Message between participants |
| `Questionnaire` | Form/survey definition |
| `QuestionnaireResponse` | Completed form responses |

### Infrastructure

| Resource | Purpose |
|----------|---------|
| `Bundle` | Collection of resources (transaction, batch, searchset) |
| `Subscription` | Event-driven notification trigger |
| `AuditEvent` | Security/privacy audit log entry |
| `Binary` | Raw binary data (files, images) |
| `DocumentReference` | Metadata about a document/attachment |
| `OperationOutcome` | Processing result with issues/errors |
| `ValueSet` | Set of codes for a specific use |
| `CodeSystem` | Collection of codes in a domain |
| `StructureDefinition` | Resource profile/schema definition |
| `PlanDefinition` | Clinical protocol/workflow template |

### Medplum Custom Resources

| Resource | Purpose |
|----------|---------|
| `Bot` | Serverless function definition |
| `ClientApplication` | OAuth2 client registration |
| `Project` | Top-level tenant/organization container |
| `ProjectMembership` | User membership with role/access policy |
| `AccessPolicy` | Resource-level access control rules |
| `Agent` | On-prem integration agent |
| `UserConfiguration` | User UI preferences |

---

## Security & Identity

### Authentication Flows

| Flow | Use Case | SDK Method |
|------|----------|------------|
| Client Credentials | Service-to-service, backend | `startClientLogin(clientId, secret)` |
| Authorization Code | User-facing web apps | `startLogin()` + `processCode()` |
| Google Sign-In | Google SSO | `startGoogleLogin()` |
| External IDP | Auth0, Cognito, Okta | `signInWithExternalAuth()` |
| JWT Bearer | Server-issued JWT assertion | `startJwtBearerLogin()` |
| Token Exchange | Convert external tokens | `exchangeExternalAccessToken()` |
| mTLS | Certificate-based auth | Server config |

### Access Policy Features

| Feature | Description |
|---------|-------------|
| Resource type rules | Allow/deny per resource type (read, write, create, delete) |
| Read-only fields | `readonlyFields` array on resource type |
| Hidden fields | `hiddenFields` array on resource type |
| Criteria filtering | FHIR search query (e.g., `Patient?address-state=CA`) |
| Compartments | Patient-based data isolation via `_compartment` |
| Parameterized | Variables: `%profile`, `%profile.id`, `%patient`, custom |
| Write constraints | FHIRPath expressions for state machine enforcement |
| SMART scopes | `patient/*.read`, `user/*.write` style scopes |
| IP rules | Restrict by IP address/CIDR |

---

## Automation

### Bot Handler Pattern

```typescript
import { BotEvent, MedplumClient } from '@medplum/core';
import { Patient } from '@medplum/fhirtypes';

export async function handler(medplum: MedplumClient, event: BotEvent): Promise<any> {
  const patient = event.input as Patient;
  // event.secrets — project secrets map
  // event.bot — reference to this Bot resource
  // event.traceId — request correlation ID
  return true;
}
```

### Bot Execution Triggers

| Trigger | Method |
|---------|--------|
| HTTP POST | `POST /fhir/R4/Bot/<ID>/$execute` |
| FHIR Subscription | Subscription criteria → rest-hook to `Bot/<ID>` |
| Cron schedule | Bot with cron expression in properties |
| Manual | Execute button in Medplum App |

### Subscription Pattern

```typescript
// Server-side: create Subscription resource
const sub = await medplum.createResource({
  resourceType: 'Subscription',
  status: 'active',
  criteria: 'Patient?name=Simpson',
  channel: { type: 'rest-hook', endpoint: 'Bot/<BOT_ID>' }
});

// Client-side: WebSocket subscription
medplum.subscribeToCriteria('Patient?name=Simpson');
```

---

## Integrations

| Integration | Path | Purpose |
|-------------|------|---------|
| DoseSpot | `/docs/integration/dosespot` | E-prescribing (enrollment, favorites, Rx) |
| Health Gorilla | `/docs/integration/health-gorilla` | Lab orders, receiving results |
| Stedi | `/docs/integration/stedi` | EDI/X12 eligibility checks |
| Candid Health | `/docs/integration/candid-health` | Revenue cycle management |
| eFax | `/docs/integration/efax` | Fax send/receive |
| HL7 v2 | `/docs/integration/hl7-interfacing` | ADT, ORM/OBR/OBX message interfacing |
| FHIRcast | `/docs/fhircast` | Real-time clinical context synchronization |
| SMART App Launch | `/docs/integration/smart-app-launch` | Embedded app launch framework |
| CDS Hooks | `/docs/integration/cds-hooks` | Clinical decision support at workflow triggers |
| C-CDA | `/docs/integration/c-cda` | Continuity of Care Document export |
| On-Prem Agent | `/docs/agent` | Bridge to on-prem HL7/DICOM systems |
| Log Streaming | `/docs/integration/log-streaming` | External log aggregation |

---

## Terminology Systems

| System | URI | Usage |
|--------|-----|-------|
| LOINC | `http://loinc.org` | Lab tests, vitals, clinical observations |
| SNOMED CT | `http://snomed.info/sct` | Clinical findings, procedures, body structures |
| ICD-10 | `http://hl7.org/fhir/sid/icd-10-cm` | Diagnoses, billing codes |
| RxNorm | `http://www.nlm.nih.gov/research/umls/rxnorm` | Medications (ingredients, brands, dose forms) |
| NDC | `http://hl7.org/fhir/sid/ndc` | Drug product codes (packaging level) |
| CPT | `http://www.ama-assn.org/go/cpt` | Procedure billing codes |
| UCUM | `http://unitsofmeasure.org` | Units of measure |
| US NPI | `http://hl7.org/fhir/sid/us-npi` | National Provider Identifier |
| US SSN | `http://hl7.org/fhir/sid/us-ssn` | Social Security Number |

---

## Compliance

| Standard | Path | Scope |
|----------|------|-------|
| HIPAA | `/docs/compliance/hipaa` | PHI protection, BAA, audit logging |
| SOC 2 Type II | `/docs/compliance/soc2` | Security, availability, confidentiality |
| HITRUST | `/docs/compliance/hitrust` | Healthcare security framework |
| ONC | `/docs/compliance/onc` | Health IT certification |
| CLIA/CAP | `/docs/compliance/clia-cap` | Laboratory certification |
| 21 CFR Part 11 | `/docs/compliance/cfr11` | Electronic records/signatures |
| ISO 9001 | `/docs/compliance/iso9001` | Quality management |
| HTI-1/HTI-4 | `/docs/compliance/hti-4` | Health tech interoperability rules |

---

## React Components (@medplum/react)

### Setup

Requires: React 18+, Mantine 7+, PostCSS with Mantine preset, `@medplum/core`, `@medplum/react`.

Provider nesting: `BrowserRouter` → `MedplumProvider` → `MantineProvider`.

### Key Components

| Component | Purpose |
|-----------|---------|
| `<MedplumProvider>` | Provides MedplumClient context to app |
| `<SignInForm>` | Authentication form |
| `<ResourceTable>` | Display resource fields in table |
| `<ResourceForm>` | Edit resource with auto-generated form |
| `<SearchControl>` | Search interface with filters and results |
| `<QuestionnaireForm>` | Render and submit FHIR Questionnaire |
| `<QuestionnaireBuilder>` | Build/edit Questionnaire resources |
| `<ChatControl>` | Communication thread interface |

### Key Hooks

| Hook | Purpose |
|------|---------|
| `useMedplum()` | Access MedplumClient instance |
| `useMedplumContext()` | Access client + profile + loading state |
| `useResource(ref)` | Read resource by reference |
| `useSearch(type, query)` | Execute search with React Suspense |
| `useSubscription(criteria)` | WebSocket subscription with auto-cleanup |

---

## Bundle Transaction Pattern

```typescript
const bundle = await medplum.executeBatch({
  resourceType: 'Bundle',
  type: 'transaction',
  entry: [
    {
      fullUrl: 'urn:uuid:patient-1',
      resource: { resourceType: 'Patient', name: [{ family: 'Smith' }] },
      request: { method: 'POST', url: 'Patient' }
    },
    {
      resource: {
        resourceType: 'Observation',
        subject: { reference: 'urn:uuid:patient-1' },  // internal ref
        code: { coding: [{ system: 'http://loinc.org', code: '8867-4' }] }
      },
      request: { method: 'POST', url: 'Observation' }
    }
  ]
});
```

Key patterns:
- `urn:uuid:` for internal references resolved server-side
- `ifNoneExist` on request for conditional creates
- `ifMatch` with `W/"versionId"` for optimistic concurrency
- Conditional references: `Practitioner?identifier=http://hl7.org/fhir/sid/us-npi|123`
- Async processing via `Prefer: respond-async` header for large bundles

---

## GraphQL Patterns

```graphql
# Search with nested resolution
{
  PatientList(name: "Eve", address_city: "Philadelphia") {
    id
    name { family given }
  }
}

# Reverse references
{
  Patient(id: "123") {
    encounters: EncounterList(_reference: patient) {
      id
      status
    }
  }
}

# Inline fragments for reference resolution
{
  DiagnosticReport(id: "456") {
    result {
      resource { ... on Observation { valueQuantity { value unit } } }
    }
  }
}
```

Notes: Search uses snake_case params (not kebab-case). `:not`, `:missing`, `:contains` modifiers not supported in GraphQL. Schema introspection disabled by default.

---

## kb/reference/merge-friendly-install-model.md

---
title: "Merge-Friendly Install Model"
category: reference
service: ai-toolkit
tags: [install, merge, hooks, injection, symlinks]
version: "1.0.0"
created: "2026-03-27"
last_updated: "2026-03-28"
description: "Reference description of how ai-toolkit preserves user content while installing toolkit components."
---

# Merge-Friendly Install Model

## Summary

`ai-toolkit` preserves user content while injecting toolkit behavior.

Instead of replacing entire directories or files, the installer uses merge-friendly strategies tailored to each component type.

## Component Strategies

| Component | Strategy | User content behavior |
|-----------|----------|-----------------------|
| `agents/*.md` | per-file symlinks | preserved; user file wins on name conflict |
| `skills/*/` | per-directory symlinks | preserved; user directory wins on name conflict |
| `settings.json` hooks | JSON merge with `_source: ai-toolkit` | preserved; toolkit entries removable |
| `constitution.md` | marker injection | preserved outside markers |
| `ARCHITECTURE.md` | marker injection | preserved outside markers |
| `CLAUDE.md` | marker injection | preserved outside markers |

## Why this model exists

This avoids two common failure modes:
1. users losing custom agents / skills due to whole-directory symlinks,
2. users losing custom hooks or docs due to full-file replacement.

## Operational Consequences

### Positive
- reversible installs and uninstalls,
- backward-compatible upgrades,
- safe coexistence of toolkit and user customizations,
- idempotent update flow.

### Trade-offs
- merged / copied artifacts require `ai-toolkit update` to refresh,
- hook merge logic depends on valid JSON and the `_source` tagging convention,
- install behavior is more complex than a simple copy or symlink-only model.

## Local Project Setup

Project-local setup uses the same preservation approach for files that should remain repository-specific, especially `CLAUDE.md` and `.claude/settings.local.json`.

## Related Documents

- `kb/reference/distribution-model.md`
- `kb/reference/global-install-model.md`
- `kb/reference/hooks-catalog.md`

---

## kb/reference/opencode-compatibility.md

---
title: "AI Toolkit - opencode Compatibility"
category: reference
service: ai-toolkit
tags: [opencode, compatibility, install, skills, hooks, mcp, plugins]
version: "1.0.1"
created: "2026-04-16"
last_updated: "2026-07-14"
description: "Reference for how ai-toolkit integrates with opencode — AGENTS.md, subagents, slash commands, JS plugin hook bridge, and MCP merge into opencode.json."
---

# AI Toolkit - opencode Compatibility

## Summary

opencode (https://opencode.ai) is the 11th supported editor. `ai-toolkit install --editors opencode` (or `--editors all`) lays down a full native integration: shared `AGENTS.md`, per-agent `.opencode/agents/` files, per-command `.opencode/commands/` files, a JS plugin bridging toolkit Bash hooks to opencode lifecycle events, and MCP server merge into `opencode.json`.

opencode also reads `CLAUDE.md` as a fallback, so a user without the native integration still gets baseline rules. The native path adds subagents, slash commands, hooks, and MCP.

## Local Install Outputs

`ai-toolkit install --local --editors opencode` generates:

- `AGENTS.md` (shared with Codex CLI via distinct marker sections)
- `.opencode/agents/ai-toolkit-*.md` (one per ai-toolkit agent, `mode: subagent`)
- `.opencode/commands/ai-toolkit-*.md` (one per user-invocable skill; the prompt lives in the markdown body)
- `.opencode/plugins/ai-toolkit-hooks.js` (JS plugin bridging Bash hooks)
- `opencode.json` (MCP key merged from `.mcp.json`, user keys preserved)

## Global Install Outputs

`ai-toolkit install --editors opencode` (no `--local`) lays down:

- `~/.config/opencode/AGENTS.md`
- `~/.config/opencode/agents/ai-toolkit-*.md`
- `~/.config/opencode/commands/ai-toolkit-*.md`
- `~/.config/opencode/plugins/ai-toolkit-hooks.js`
- `~/.config/opencode/opencode.json` (MCP merge, user keys preserved)

Files land directly under `~/.config/opencode/` (no `.opencode/` nesting) because that is the global layout opencode expects per https://opencode.ai/docs/config/. Shared hook scripts stay in `~/.softspark/ai-toolkit/hooks/` and are referenced by the global JS plugin.

## Editor Surface Comparison

| Feature            | Claude Code | Codex CLI       | opencode                                  |
|--------------------|-------------|-----------------|-------------------------------------------|
| Rules file         | `CLAUDE.md` | `AGENTS.md`     | `AGENTS.md` + `CLAUDE.md` fallback        |
| Subagents          | Yes         | Yes (`.codex/agents/*.toml`) | Yes (`mode: subagent`)          |
| Slash commands     | Skills      | Adapted skills  | Native commands with frontmatter          |
| MCP                | Yes         | Yes             | Yes (`opencode.json`)                     |
| Lifecycle hooks    | JSON config | `.codex/hooks`  | JS/TS plugins (~30+ events)               |
| Global config dir  | `~/.claude` | `$CODEX_HOME` (default `~/.codex`) | `~/.config/opencode`       |
| Project config dir | `.claude`   | `.codex` + `.agents/skills` | `.opencode`                    |

## Shared AGENTS.md

opencode and Codex CLI both read `AGENTS.md`. The toolkit emits two distinct marker-bounded sections in a single file, so installing both editors does not clobber either. The Codex section is produced by `generate_codex.py`; the opencode section is produced by `generate_opencode.py`. OpenCode commands use a platform-specific portable renderer for Claude-only orchestration primitives, so generated content uses OpenCode-native wording.

## Subagent Translation Model

Each file in `app/agents/*.md` emits a corresponding `.opencode/agents/ai-toolkit-<name>.md` with:

- `description` — copied from the source agent frontmatter
- `mode: subagent` (required)
- `color` — copied when present

The `model` field is deliberately omitted. opencode requires the `provider/model-id` form; ai-toolkit only stores a short alias (`opus`/`sonnet`/`haiku`) which cannot be mapped without assuming a provider. opencode falls back to the user's `default_agent` / top-level `model` config.

Opencode treats these files as auto-completable with `@` and can delegate to them from the primary agent.

## Slash Command Translation Model

Only user-invocable skills (`user-invocable: true` or no `disable-model-invocation`) emit to `.opencode/commands/`. Knowledge skills (`user-invocable: false`) are intentionally skipped — they are not intended as commands.

Each command file carries the prompt in its markdown body (built from the SKILL.md body). opencode reads the body as the prompt; the `template` field is JSON-config-only and is ignored in `.md` command files.

OpenCode natively interpolates `$ARGUMENTS` and positional placeholders `$1`
through `$9` in command bodies. The renderer preserves those placeholders for
OpenCode while translating Claude-only skill-directory variables and runtime
APIs. Codex output uses a separate renderer and converts prompt placeholders to
durable user-input prose.

## Hook Bridge (JS Plugin)

`.opencode/plugins/ai-toolkit-hooks.js` is a single-file plugin that maps opencode events to the shared Bash hooks in `~/.softspark/ai-toolkit/hooks/`:

| opencode event             | Bash hook(s)                                                       |
|----------------------------|--------------------------------------------------------------------|
| `session.created`          | `session-start.sh` + `mcp-health.sh`                               |
| `session.compacted`        | `pre-compact.sh` + `pre-compact-save.sh` (PreCompact equivalent)   |
| `session.deleted`          | `session-end.sh` + `save-session.sh`                               |
| `message.updated`          | `user-prompt-submit.sh` + `track-usage.sh`                         |
| `message.part.updated`     | `user-prompt-submit.sh` + `track-usage.sh`                         |
| `tool.execute.before` (bash) | `guard-destructive.sh` + `commit-quality.sh`                     |
| `tool.execute.after`       | `post-tool-use.sh`                                                 |
| `permission.asked`         | `guard-destructive.sh` (approval-gate bridge)                      |
| `command.executed`         | `post-tool-use.sh`                                                 |

Plugin exports a single named export `AiToolkitHooks` — per opencode docs, named exports only (no default export). Hook scripts are invoked via Bun's `$` with the script path bound as a JS constant; opencode event payloads are passed as JSON on stdin, never interpolated into the shell command, so payload data cannot inject shell metacharacters. The toolkit's `exit 2` semantics for PreToolUse guards are preserved and bubble up as the plugin's return code.

**Intentionally unmapped events**: `tui.*`, `lsp.*`, `installation.*`, `session.idle/status/updated/error/diff`, `file.edited`, `file.watcher.updated`, `todo.updated`, `shell.env`, `server.connected`, `message.*.removed`, `experimental.*` — no matching Bash hook in the toolkit, or the event is opencode-UI-only.

## MCP Merge (opencode.json)

`generate_opencode_json.py` reads `.mcp.json` and merges its servers under the `mcp` key in `opencode.json`:

- `local` shape entries are translated to opencode's local command shape.
- `remote` shape entries are translated to opencode's remote URL shape.
- User-authored keys in `opencode.json` (outside `mcp`) are preserved.
- Re-running the generator is idempotent.

## Auto-Detection

The installer detects opencode as configured when any of these markers exist:

- `opencode.json`
- `.opencode/` directory
- `.opencode/agents/`
- `.opencode/commands/`
- `~/.config/opencode/`

`ai-toolkit update` picks up opencode automatically when detection fires.

## Uninstall & Reset

`scripts/install_steps/ai_tools.py` cleanup only removes ai-toolkit-marked artifacts:

- Generated `.opencode/agents/ai-toolkit-*.md`
- Generated `.opencode/commands/ai-toolkit-*.md`
- Generated `.opencode/plugins/ai-toolkit-hooks.js`
- Managed markers from `AGENTS.md`
- `mcp` key entries injected by the toolkit (user keys preserved)

User-authored opencode files and user-authored `opencode.json` keys are never deleted.

## Behavioral Limits

- opencode does not expose the full Claude hook event surface; only the events in the mapping table above are bridged. Claude-only events (`TaskCompleted`, `TeammateIdle`, `SubagentStart`, `SubagentStop`, `PreCompact`) are silently skipped.
- Multi-agent orchestration skills (`/orchestrate`, `/workflow`, `/swarm`, `/subagent-development`) run through the OpenCode renderer and use OpenCode-native subagents with explicit file ownership.

## Verification

The opencode integration is verified by:

1. Generator contract tests for the five `generate_opencode*.py` scripts (bats)
2. MCP merge idempotency and user-key preservation tests
3. Plugin export shape and event coverage tests
4. Auto-detection tests for install / update flow
5. `validate.py --strict` + `audit_skills.py --ci` in CI

## CLI Commands

| Command | Description |
|---------|-------------|
| `ai-toolkit opencode-md` | Generate `AGENTS.md` body for opencode |
| `ai-toolkit opencode-agents` | Generate `.opencode/agents/ai-toolkit-*.md` |
| `ai-toolkit opencode-commands` | Generate `.opencode/commands/ai-toolkit-*.md` |
| `ai-toolkit opencode-plugin` | Generate `.opencode/plugins/ai-toolkit-hooks.js` |
| `ai-toolkit opencode-json` | Merge MCP servers into `opencode.json` |

## Related

- `kb/reference/skills-catalog.md`
- `kb/reference/agents-catalog.md`
- `kb/reference/codex-cli-compatibility.md`
- `kb/reference/copilot-compatibility.md`
- `kb/reference/architecture-overview.md`
- `kb/reference/global-install-model.md`
- `kb/reference/mcp-editor-compatibility.md`

---

## kb/reference/plugin-pack-conventions.md

---
title: "Plugin Pack Conventions"
category: reference
service: ai-toolkit
tags: [plugins, plugin-packs, conventions, manifests, hooks, policy-packs]
version: "1.1.0"
created: "2026-03-28"
last_updated: "2026-07-14"
description: "Conventions for experimental ai-toolkit plugin packs, policy packs, hook packs, and plugin-creator scaffolding across Claude Code and Codex runtimes."
---

# Plugin Pack Conventions

## Purpose

`ai-toolkit` includes experimental plugin packs under `app/plugins/` for Claude Code and optional global Codex layering. These internal pack manifests are distinct from the official uploadable Claude app plugin built by `ai-toolkit claude-app export`.

## Pack Types

| Type | Purpose | Example |
|------|---------|---------|
| `plugin-pack` | Curated bundle of existing assets by domain | `security-pack`, `research-pack` |
| `policy-pack` | Rules / compliance / governance overlays | future enterprise policy add-ons |
| `hook-pack` | Optional hook modules or observability bundles | status line, output style |

## Directory Contract

```text
app/plugins/<pack-name>/
├── plugin.json
├── README.md
├── hooks/        # optional, executable if present
├── rules/        # optional
├── skills/       # optional
├── agents/       # optional
└── templates/    # optional
```

## Manifest Contract

Required keys:
- `name`
- `description`
- `version`
- `domain`
- `type`
- `status`
- `requires`
- `includes`

`includes` should declare arrays for:
- `agents`
- `skills`
- `rules`
- `hooks`

## Naming Rules

- Pack directory and `name` should use lowercase-hyphen format
- Prefer `*-pack` suffix for curated bundles
- Hook module filenames should be kebab-case and executable
- Experimental packs should declare `"status": "experimental"`

## Adoption Rules

1. Packs are opt-in and must not be auto-installed by `ai-toolkit install`
2. Reuse core agents/skills before duplicating definitions
3. Optional hooks must be documented as opt-in and non-default
4. Policy packs should be additive and marker-injected where possible
5. Keep manifests small and reviewable; use README for narrative guidance

## CLI Management

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

### What `plugin install` Does

1. **Parses** `--editor claude|codex|all` (default: `claude`)
2. **Copies** plugin-specific hooks to runtime-owned storage: Claude uses `~/.softspark/ai-toolkit/hooks/plugin-<pack>-<hook>.sh`; Codex uses `$CODEX_HOME/ai-toolkit-hooks/plugin-<pack>-<hook>.sh`
3. **Copies** shared plugin scripts to `~/.softspark/ai-toolkit/plugin-scripts/<pack>/`
4. **Runs** init scripts if present (e.g. `init_db.py` for memory-pack — safe to re-run, preserves data)
5. **Claude Code target**: links missing agents/skills into `~/.claude/`, injects plugin-local rules into `~/.claude/CLAUDE.md`, and merges plugin hook entries into `~/.claude/settings.json`
6. **Codex target**: bootstraps `$CODEX_HOME/AGENTS.md`, `$HOME/.agents/skills`, `$CODEX_HOME/hooks.json`, and self-contained `$CODEX_HOME/ai-toolkit-hooks`, then layers plugin-specific rules and hooks on top; it does not write `~/AGENTS.md` or `.agents/rules/`
7. **Records** installed state per runtime in `~/.softspark/ai-toolkit/plugins.json`

### What `plugin update` Does

1. **Removes** existing plugin runtime entries for the selected editor(s) (same as `remove`)
2. **Reinstalls** from the current source (same as `install`)
3. **Preserves plugin data** (e.g. memory-pack SQLite database is never deleted)
4. Shared plugin scripts/hooks are kept if another runtime still has the same pack installed
5. `--all` updates only currently installed packs for the selected runtime(s)

### What `plugin clean` Does

1. **Prunes** old plugin data based on `--days N` (default 90)
2. For memory-pack: deletes observations older than N days, removes orphan sessions, runs VACUUM
3. Shows before/after counts and DB size

### What `plugin remove` Does

1. **Claude Code target**: strips plugin hook entries from `~/.claude/settings.json` and removes plugin-local rule sections from `~/.claude/CLAUDE.md`
2. **Codex target**: strips only command handlers carrying the exact `AI_TOOLKIT_HOOK_OWNER=ai-toolkit-plugin-<pack>` marker from `$CODEX_HOME/hooks.json`, removes owned `$CODEX_HOME/ai-toolkit-hooks/plugin-<pack>-*` assets, and removes the pack's marker-bounded sections from `$CODEX_HOME/AGENTS.md`
3. **Claude/shared assets** (`~/.softspark/ai-toolkit/hooks/plugin-*`, `plugin-scripts/<pack>/`) are removed only when no remaining runtime still uses that pack
4. **Updates** `plugins.json` state per runtime
5. **Leaves** core agents/skills untouched (they belong to the base install)
6. **Leaves** plugin data intact (e.g. `memory.db` — use `clean` to prune)

### Data Retention (memory-pack)

- **Auto-retention**: `session-summary.sh` hook auto-prunes observations older than 90 days on every session end (configurable via `MEMORY_RETENTION_DAYS` env var)
- **Manual clean**: `ai-toolkit plugin clean memory-pack --days 30`
- **Status**: `ai-toolkit plugin status --editor claude|codex|all` shows runtime-specific install details plus DB size, observation count, and date range where relevant

## Current Experimental Packs

| Pack | Domain | Owns | Installs (claude / codex) | Description |
|------|--------|------|---------------------------|-------------|
| `memory-pack` | memory | 2 hooks, 2 scripts, 1 skill | 4 / 4 files | SQLite persistent memory with FTS5 search |
| `enterprise-pack` | enterprise | 2 hooks | 2 / 2 files | Status-line and output-style overlays |

Both packs ship content in this repository. Neither fetches anything at install
time.

### The rule the table now enforces

**A pack must install files the core install does not.** `ai-toolkit install`
links every core skill and agent, so a manifest naming only core assets resolves
to nothing: `plugin install` reports `(0 file items)` and no file appears on
disk. This is not a subtle degradation — it is a complete no-op, identical on
every profile (`minimal`, `standard`, `strict`) and on both runtimes.

Nine packs were removed in v4.20.0 for failing this: `csharp`, `java`, `kotlin`,
`ruby`, `rust`, `swift`, `frontend`, `research`, `security`. Every one declared
only skills and agents that already ship in core, and eight of them owned nothing
but a `README.md`. Full measurement:
[`no-op-plugin-packs-removed-20260727.md`](../history/completed/no-op-plugin-packs-removed-20260727.md).

Before adding a pack, prove it does something: install core into a throwaway
`HOME`, install the pack, and check that the reported file count is above zero.

**A pack that downloads a binary has been tried once and retired.** `rtk-pack`
(v4.18.0, removed in v4.19.0) fetched a checksum-pinned artifact in
`scripts/init.py`, declared platform assets and digests in `plugin.json`, and
rewrote commands at `PreToolUse`. Read
`kb/history/completed/rtk-pack-retirement-20260727.md` before proposing another
pack of that shape; the two defects that killed it were both invisible to
`validate.py --strict` and to the pack's own status check.

What survives from that work and applies to any pack:

- **A pack reports its own health.** `scripts/status.py` is picked up
  generically by `plugin status`, replacing what used to be a hardcoded
  `if name == "memory-pack"` branch. A status check must distinguish *installed*
  from *working*, and prove the working part by exercising it rather than by
  checking that files exist.
- **A pack may declare `supported_editors`.** Without it a pack installs on
  every runtime and silently does nothing on the ones it was never built for.
- **The manifest schema tolerates extra keys.** Anything additive is unvalidated,
  so a malformed block fails at install time rather than in `validate.py
  --strict`. Do not rely on the schema to catch it.

## Optional Hook Modules

`enterprise-pack` provides two optional hook modules:
- `hooks/status-line.sh` — status line overlay
- `hooks/output-style.sh` — enterprise reporting style

`memory-pack` provides two hooks:
- `hooks/observation-capture.sh` — captures tool actions to SQLite (PostToolUse)
- `hooks/session-summary.sh` — summarizes session on Stop

These are intentionally excluded from the default install until explicitly enabled via `ai-toolkit plugin install`.

---

## kb/reference/quick-wins-implementation-summary.md

---
title: "Quick Wins Implementation Summary"
category: reference
service: ai-toolkit
tags: [implementation, hooks, cli, benchmark, validation]
version: "1.0.0"
created: "2026-03-28"
last_updated: "2026-04-01"
description: "Reference summary of the quick-win execution slice that became part of the baseline toolkit implementation."
---

# Quick Wins Implementation Summary

## Purpose

This document records the implementation slice that hardened the toolkit around creator workflows, diagnostics, lifecycle hooks, benchmark tooling, and validation.

## Delivered Runtime Features

### Creator workflows
- `app/skills/hook-creator/SKILL.md`
- `app/skills/command-creator/SKILL.md`
- `app/skills/agent-creator/SKILL.md`
- `app/skills/plugin-creator/SKILL.md`

### CLI and diagnostics
- `ai-toolkit doctor`
- `ai-toolkit benchmark-ecosystem`
- `scripts/harvest_ecosystem.py`

### Hook coverage
- `PreCompact`
- `PostToolUse`
- `UserPromptSubmit`
- `SubagentStart`
- `SubagentStop`
- `SessionEnd`

### Validation and benchmarks
- benchmark dashboard JSON
- benchmark harvest JSON
- plugin-pack validation
- benchmark freshness checks in `doctor`
- expanded lifecycle and asset checks in `validate.py`

## Delivered Documentation

Updated baseline docs:
- `README.md`
- `app/ARCHITECTURE.md`
- `kb/reference/architecture-overview.md`
- `kb/reference/hooks-catalog.md`
- `kb/reference/skills-catalog.md`
- `kb/reference/plugin-pack-conventions.md`
- `kb/reference/claude-ecosystem-benchmark-snapshot.md`
- `kb/procedures/maintenance-sop.md`

## Validation Evidence

The implementation is backed by:
- `scripts/validate.py`
- CLI tests
- install tests
- generator tests
- metadata contract tests
- validator negative tests

## Final Outcome

The quick-win slice is no longer a pending execution plan. Its outputs are part of the default toolkit baseline and should be treated as shipped product behavior.

---

## kb/reference/skill-templates.md

---
title: "AI Toolkit - Skill Templates"
category: reference
service: ai-toolkit
tags: [templates, scaffolding, create, skills]
version: "1.0.0"
created: "2026-03-29"
last_updated: "2026-04-01"
description: "5 skill templates for scaffolding new skills: linter, reviewer, generator, workflow, knowledge."
---

# Skill Templates

## Overview

`ai-toolkit create skill` scaffolds new skills from predefined templates. Each template produces a valid SKILL.md that passes `validate.py`.

## Usage

```bash
ai-toolkit create skill my-skill --template=linter
ai-toolkit create skill my-checker --template=reviewer --description="Review security headers"
```

## Available Templates

| Template | Skill Type | Key Frontmatter | Use When |
|----------|-----------|-----------------|----------|
| `linter` | Task | `disable-model-invocation: true`, `allowed-tools: Bash, Read` | Automated checks, validators |
| `reviewer` | Hybrid | `context: fork`, `agent: code-reviewer` | Code review with agent delegation |
| `generator` | Task | `allowed-tools: Read, Write, Bash, Glob` | File generation, scaffolding |
| `workflow` | Hybrid | `context: fork`, `agent: orchestrator`, `model: opus` | Multi-phase orchestration |
| `knowledge` | Knowledge | `user-invocable: false` | Auto-loaded domain patterns |

## Template Variables

| Variable | Replaced With | Example |
|----------|--------------|---------|
| `{{NAME}}` | Skill name argument | `my-linter` |
| `{{DESCRIPTION}}` | `--description` value or default | `Provides my-linter functionality` |

## Template Location

Templates are stored in `app/templates/skill/{type}/SKILL.md.template`.

## After Scaffolding

1. Edit the generated `app/skills/{name}/SKILL.md`
2. Add `reference/` or `templates/` subdirectories if needed
3. Run `ai-toolkit validate` to verify

---

## kb/reference/skills-catalog.md

---
title: "AI Toolkit - Skills Catalog"
category: reference
service: ai-toolkit
tags: [skills, domain-knowledge, catalog, task-skills, hybrid-skills]
version: "1.4.3"
created: "2026-03-23"
last_updated: "2026-04-12"
description: "Complete skills catalog with task, hybrid, and knowledge skills. Includes Codex adaptation notes, effort levels, skill-scoped hooks, executable scripts, security auditor, and persona presets."
---

# Skills Catalog

All functionality is unified under skills. Task and hybrid skills are user-invocable as slash commands. Knowledge skills provide domain patterns auto-loaded by agents.

## Skill Tiers

| Tier | Skills | When |
|------|--------|------|
| **1 — Quick single-agent** | `/debug`, `/review`, `/refactor`, `/analyze`, `/docs`, `/plan`, `/explain`, `/tdd`, `/grill-me`, `/triage-issue` | One concern, fast |
| **1.5 — Product planning** | `/write-a-prd` → `/prd-to-plan` → `/prd-to-issues` | Interview-driven PRD → vertical-slice plan → GitHub issues |
| **1.5 — Design & architecture** | `/design-an-interface`, `/architecture-audit`, `/refactor-plan`, `/ubiquitous-language`, `/qa-session` | Parallel sub-agent exploration |
| **2 — Multi-agent workflow** | `/workflow <type>` | Cross-cutting task with known pattern |
| **3 — Custom parallelism** | `/orchestrate`, `/swarm` | No predefined workflow matches |

## Task Skills (30)

Task skills execute a specific action. Invoked via slash commands. `disable-model-invocation: true`.

| Skill | Slash Command | Effort | Description |
|-------|---------------|--------|-------------|
| **commit** | `/commit` | medium | Create well-structured git commits (Conventional Commits) |
| **pr** | `/pr` | medium | Create GitHub pull request with template and checks |
| **test** | `/test` | medium | Run tests (auto-detect: pytest, vitest, jest, phpunit, flutter, go, cargo) |
| **build** | `/build` | low | Build the current project (auto-detects project type) |
| **lint** | `/lint` | low | Run linting and type checking (ruff/mypy, eslint/tsc, phpstan, dart analyze) |
| **fix** | `/fix` | low | Autonomously fix failing tests or lint errors (iterative loop) |
| **deploy** | `/deploy` | medium | Deploy to target environment with pre-deployment checks |
| **rollback** | `/rollback` | medium | Safe rollback (git, database migrations, deployments) |
| **migrate** | `/migrate` | medium | Database migration workflow (auto-detect: Alembic, Prisma, Laravel, Django) |
| **ci** | `/ci` | medium | Generate/manage CI/CD pipeline configuration (GitHub Actions, GitLab CI) |
| **panic** | `/panic` | low | EMERGENCY: Immediately halt all autonomous agent operations |
| **index** | `/index` | low | Reindex knowledge base to vector store with change detection |
| **onboard** | `/onboard` | medium | Guided project setup with the toolkit |
| **night-watch** | `/night-watch` | medium | Trigger Night Watchman autonomous maintenance cycle |
| **evolve** | `/evolve` | medium | Trigger Meta-Architect self-optimization cycle |
| **chaos** | `/chaos` | medium | Trigger Chaos Engineering experiment |
| **predict** | `/predict` | medium | Predict impact and risks of code changes |
| **biz-scan** | `/biz-scan` | medium | Scan project for business value opportunities and metric gaps |
| **briefing** | `/briefing` | medium | Generate daily executive summary of system status |
| **evaluate** | `/evaluate` | medium | Evaluate RAG quality using LLM-as-a-Judge methodology |
| **skill-creator** | `/skill-creator` | high | Create new skills following Agent Skills standard |
| **hook-creator** | `/hook-creator` | high | Create new Claude Code hooks with conventions and validation |
| **command-creator** | `/command-creator` | high | Create new slash commands with frontmatter and workflow guidance |
| **agent-creator** | `/agent-creator` | high | Create new specialized agents with trigger and tool selection guidance |
| **plugin-creator** | `/plugin-creator` | high | Create experimental opt-in plugin packs with manifests, conventions, and optional modules |
| **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 |
| **a11y-validate** | `/a11y-validate` | medium | Scan codebase for accessibility violations: WCAG 2.1 Level AA, EN 301 549, European Accessibility Act (EAA / EU 2019/882). Covers semantics, keyboard, focus, color contrast, forms, media, ARIA, motion, mobile (React Native + Flutter), and EAA accessibility-statement documentation. |
| **seo-validate** | `/seo-validate` | medium | Scan codebase for SEO issues: W3C semantics, meta/OG tags, Schema.org, hreflang, Core Web Vitals (LCP/INP/CLS), resource hints, GEO, SPA/SSG/CSR crawlability, technical SEO, accessibility-for-SEO. Framework-aware (Next/Nuxt/Astro/Gatsby/SvelteKit/Remix/Angular/Vue/static HTML). |
| **mcp-builder** | `/mcp-builder` | high | Build production-grade MCP servers using the 4-phase methodology (research, implement, test, evaluate). TypeScript/Python, stdio/streamable-http. |

## Hybrid Skills (32)

Hybrid skills combine slash-command invocation with domain knowledge that agents reference.

| Skill | Slash Command | Effort | Description |
|-------|---------------|--------|-------------|
| **explore** | `/explore` | medium | Explore and understand codebase structure and tech stack |
| **debug** | `/debug` | medium | Systematic debugging with logs, health checks, diagnostics (Tier 1 — single agent) |
| **review** | `/review` | high | Review code changes: quality, security, performance (Tier 1 — single agent) |
| **plan** | `/plan` | high | Create structured plan with task breakdown and agent assignments |
| **refactor** | `/refactor` | high | Plan and execute code refactoring with safety checks (Tier 1 — single agent) |
| **analyze** | `/analyze` | medium | Analyze code quality, complexity, and patterns |
| **cve-scan** | `/cve-scan` | medium | Scan project dependencies for known CVEs using native audit tools (npm, pip, composer, cargo, go, ruby, dart) |
| **docs** | `/docs` | high | Generate/update docs: README, API docs, architecture notes, changelogs (Tier 1 — single agent) |
| **explain** | `/explain` | medium | Explain architecture of a file/module using Mermaid diagrams |
| **orchestrate** | `/orchestrate` | max | Custom multi-agent parallelism — Tier 3, native in Claude, Codex-adapted with semantic subagent guidance |
| **swarm** | `/swarm` | max | Massive parallelism: map-reduce, consensus, relay — Tier 3 |
| **workflow** | `/workflow` | max | 15 predefined multi-agent workflow types — Tier 2, Codex-adapted to native subagent orchestration |
| **instinct-review** | `/instinct-review` | low | Review, curate, and manage learned instincts from past sessions |
| **write-a-prd** | `/write-a-prd` | high | Create PRD through interactive interview, codebase exploration, and module design |
| **prd-to-plan** | `/prd-to-plan` | high | Convert PRD into phased implementation plan using tracer-bullet vertical slices |
| **tdd** | `/tdd` | high | Test-driven development with red-green-refactor loop and vertical slices |
| **design-an-interface** | `/design-an-interface` | high | Generate 3+ radically different interface designs using parallel sub-agents |
| **grill-me** | `/grill-me` | medium | Stress-test a plan through relentless Socratic questioning |
| **ubiquitous-language** | `/ubiquitous-language` | medium | Extract DDD-style ubiquitous language glossary from conversation |
| **refactor-plan** | `/refactor-plan` | high | Create detailed refactor plan with tiny commits via user interview |
| **qa-session** | `/qa-session` | high | Interactive QA session — report bugs conversationally, file GitHub issues |
| **triage-issue** | `/triage-issue` | high | Triage bug with deep codebase exploration and TDD fix plan |
| **architecture-audit** | `/architecture-audit` | high | Discover shallow modules and propose module-deepening refactors |
| **subagent-development** | `/subagent-development` | high | Execute plans with 2-stage review (spec + quality) per task |
| **repeat** | `/repeat` | medium | Autonomous loop with safety controls (Ralph Wiggum pattern) |
| **mem-search** | `/mem-search` | medium | Search past coding sessions via natural language (memory-pack) |
| **persona** | `/persona` | low | Switch engineering persona at runtime (backend-lead, frontend-lead, devops-eng, junior-dev) |
| **council** | `/council` | high | 4-perspective decision evaluation (Advocate, Critic, Pragmatist, User-Proxy) with synthesis and confidence-rated recommendation. Tier 1, orchestrator, `context: fork`. |
| **introspect** | `/introspect` | medium | Agent self-debugging: classify failure pattern, suggest smallest recovery action, emit structured introspection report |
| **brand-voice** | `/brand-voice` | medium | Anti-trope list, voice principles, LLM rhetoric prevention; output modes (`concise` ≤60% tokens, `strict` ≤40%) governing conversational responses. |

### `/workflow` types

| Type | Agents | Use case |
|------|--------|----------|
| `feature-development` | 8 | Full stack feature: plan → backend + frontend + DB + tests + security + docs |
| `backend-feature` | 5 | Backend only: API + logic + DB + tests + security |
| `frontend-feature` | 4 | UI: component + state + tests + docs |
| `api-design` | 7 | API contract → implement → test → benchmark → document |
| `database-evolution` | 7 | Schema change + migration + ORM update + tests + perf + security |
| `test-coverage` | 4 | Boost coverage: map gaps → unit tests + fixtures → review |
| `security-audit` | 7 | Multi-vector: OWASP + code + infra + DB → prioritize → report |
| `codebase-onboarding` | 6 | Read-only: structure + architecture + DB + tests + security → guide |
| `spike` | 7 | Research → feasibility → security + perf → architecture note |
| `debugging` | 5 | Diagnose → fix → test → document |
| `incident-response` | 3 | Triage → fix → postmortem |
| `performance-optimization` | 4 | Profile → optimize → benchmark → document |
| `infrastructure-change` | 5 | Design + implement + security + tests + runbook |
| `application-deploy` | 3 | Deploy → smoke test → release notes |
| `proactive-troubleshooting` | 4 | Investigate → check perf → preventive fix → docs |

## Knowledge Skills - Development (15)

| Skill | Directory | Domain |
|-------|-----------|--------|
| **app-builder** | `skills/app-builder/` | Full-stack application architecture |
| **api-patterns** | `skills/api-patterns/` | REST/GraphQL design, versioning, error handling |
| **database-patterns** | `skills/database-patterns/` | Schema design, indexing, query optimization |
| **flutter-patterns** | `skills/flutter-patterns/` | Flutter/Dart architecture, state management |
| **ecommerce-patterns** | `skills/ecommerce-patterns/` | E-commerce: catalog, cart, checkout, payments |
| **clean-code** | `skills/clean-code/` | Multi-language code quality: Python, TS, PHP, Go, Dart |
| **typescript-patterns** | `skills/typescript-patterns/` | TypeScript/JavaScript patterns for frontend and backend |
| **rust-patterns** | `skills/rust-patterns/` | Ownership, borrowing, error handling, Cargo, tokio, serde |
| **java-patterns** | `skills/java-patterns/` | Records, sealed classes, Stream API, Spring Boot, JUnit 5 |
| **csharp-patterns** | `skills/csharp-patterns/` | Nullable refs, async/await, ASP.NET Core, EF Core |
| **kotlin-patterns** | `skills/kotlin-patterns/` | Coroutines, DSLs, sealed classes, Ktor, MockK |
| **swift-patterns** | `skills/swift-patterns/` | Protocol-oriented, SwiftUI, async/await, SPM |
| **ruby-patterns** | `skills/ruby-patterns/` | Blocks, Rails conventions, RSpec, ActiveRecord |
| **design-engineering** | `skills/design-engineering/` | UI polish, animation craft, easing, transforms, accessibility |
| **documentation-standards** | `skills/documentation-standards/` | KB document conventions, frontmatter validation, category taxonomy |

## Knowledge Skills - Infrastructure (6)

| Skill | Directory | Domain |
|-------|-----------|--------|
| **docker-devops** | `skills/docker-devops/` | Docker, deployment, infrastructure |
| **security-patterns** | `skills/security-patterns/` | OWASP, auth, encryption, vulnerability prevention |
| **ci-cd-patterns** | `skills/ci-cd-patterns/` | GitHub Actions, GitLab CI, Docker builds, Kubernetes |
| **observability-patterns** | `skills/observability-patterns/` | Logging, metrics, tracing, monitoring, SLOs |
| **testing-patterns** | `skills/testing-patterns/` | Multi-language TDD: pytest, vitest, phpunit, go test, flutter |
| **migration-patterns** | `skills/migration-patterns/` | Database migrations, API versioning, zero-downtime |

## Knowledge Skills - AI/RAG (6)

| Skill | Directory | Domain |
|-------|-----------|--------|
| **rag-patterns** | `skills/rag-patterns/` | RAG pipelines, chunking, reranking, evaluation |
| **mcp-patterns** | `skills/mcp-patterns/` | MCP protocol, server/client design, tools |
| **prompt-caching-patterns** | `skills/prompt-caching-patterns/` | Anthropic prompt caching: TTL, breakpoints, hit rate, anti-patterns |
| **json-mode-patterns** | `skills/json-mode-patterns/` | Structured JSON output via tool-use; schema design; partial recovery |
| **content-moderation-patterns** | `skills/content-moderation-patterns/` | Two-stage moderation: pre-filter + LLM classifier; categories; thresholds |
| **model-routing-patterns** | `skills/model-routing-patterns/` | Haiku/Sonnet/Opus routing; escalation; sub-agent delegation; fallback |

## Knowledge Skills - Process (6)

| Skill | Directory | Domain |
|-------|-----------|--------|
| **git-mastery** | `skills/git-mastery/` | Git workflows, branching, conflict resolution |
| **architecture-decision** | `skills/architecture-decision/` | Architecture notes, trade-off analysis, alternatives |
| **performance-profiling** | `skills/performance-profiling/` | Profiling, bottleneck analysis, optimization |
| **research-mastery** | `skills/research-mastery/` | Multi-source research, synthesis, fact-checking |
| **deep-research** | `skills/deep-research/` | Web/multi-source research methodology, retrieval budget, adversarial verification, citation discipline |
| **verification-before-completion** | `skills/verification-before-completion/` | Iron Law: evidence-before-claims, no completion without fresh verification |

## Quality Guardrails

### Anti-Rationalization Tables

15 core skills include `## Common Rationalizations` — domain-specific tables of excuses and rebuttals that prevent agent drift and shortcut-taking:

| Skill | Example rationalization blocked |
|-------|---------------------------------|
| `/review` | "Small change, quick scan is enough" |
| `/debug` | "It must be a library bug" |
| `/refactor` | "It works, don't touch it" |
| `/tdd` | "Too simple to test" |
| `/plan` | "Planning is wasted time, just start coding" |
| `/docs` | "The code is self-documenting" |
| `/analyze` | "The linter is green, the code is fine" |
| `security-patterns` | "It's an internal API, security doesn't matter" |
| `testing-patterns` | "Tests slow down development" |
| `api-patterns` | "We'll version the API later" |
| `ci-cd-patterns` | "Manual deploys give us more control" |
| `clean-code` | "It's readable enough" |
| `performance-profiling` | "It feels slow, let me optimize this function" |
| `git-mastery` | "One big commit is simpler" |
| `database-patterns` | "We'll add indexes later when it's slow" |

### Confidence Scoring (`/review`)

The `/review` skill outputs structured findings with:
- **Severity**: critical / major / minor / nit
- **Confidence score**: 1-10 per finding with calibration guide
- **Evidence requirement**: each finding must include file:line + reasoning

### Self-Evaluation — LLM-as-Judge (`/review`)

After completing a review, the agent performs a self-evaluation pass:
1. Verify vs assume — did I read actual code for each finding?
2. Check the inverse — if X is a problem, is NOT-X also a problem elsewhere?
3. Detect anchoring bias — did early findings bias toward similar patterns?
4. Check unhappy paths — error handling, edge cases, failure modes
5. Calibrate confidence — overconfident? re-examine weakest finding

### Agent Verification Checklists

10 key agents include `## Verification Checklist` — exit criteria before presenting results:
`code-reviewer`, `test-engineer`, `security-auditor`, `debugger`, `backend-specialist`, `frontend-specialist`, `database-architect`, `performance-optimizer`, `devops-implementer`, `documenter`.

### Skill Reference Routing

7 core skills include `## Related Skills` sections suggesting logical follow-up skills:
`/review`, `/debug`, `/plan`, `/refactor`, `/tdd`, `/docs`, `/analyze`.

### Intent Capture Interview (`/onboard`)

Step 0 interview before setup — 5 targeted questions to capture undocumented project intent, customizing the generated `CLAUDE.md`.

---

## Advanced Features

### Effort Levels
- **low**: Mechanical operations (lint, build, fix, panic, index)
- **medium**: Standard operations (most skills)
- **high**: Complex reasoning (review, plan, refactor, docs, skill-creator)
- **max**: Multi-agent orchestration (orchestrate, swarm, workflow)

### Skill-Scoped Hooks
5 skills have lifecycle hooks:
- **commit**: PreToolUse — lint reminder before committing
- **test**: PostToolUse — coverage threshold reminder
- **deploy**: PostToolUse — health check reminder
- **migrate**: PreToolUse — backup reminder before migrations
- **rollback**: PostToolUse — verification reminder after rollback

### Skill Frontmatter Conventions
- `agent: <name>` — delegates to a specialized agent persona
- `context: fork` — runs skill in isolated forked context
- `allowed-tools: ...` — tools available to the agent when processing this skill
- `depends-on: skill-a, skill-b` — declares dependencies on other skills (validated by `validate.py`)

### Codex CLI Adaptation

Codex CLI receives the full skill catalog during `ai-toolkit install --local --editors codex`.

Claude Chat/Desktop/Cowork receives this same catalog through `ai-toolkit claude-app export`. The export also adds an app-only `ai-toolkit-rules` skill because the Claude app does not read Claude Code's `CLAUDE.md` or `.claude/rules/` surfaces.

- Native Codex-compatible skills are symlinked directly into `.agents/skills/`
- Skills with Claude-only tools, placeholders, path variables, or orchestration APIs are generated as Codex wrappers
- Adapted wrappers describe subagent control, waiting, and planning as durable current-client semantics without embedding guessed tool signatures

Common adapted skills:

- `/orchestrate`
- `/workflow`
- `/swarm`
- `/subagent-development`
- `/tdd`

The translated skill content keeps the original support assets (`reference/`,
`scripts/`, `assets/`) while replacing Claude-specific runtime instructions.

See `kb/reference/codex-cli-compatibility.md` for the detailed mapping and hook limits.

### Skill Dependencies (`depends-on`)
Skills can declare dependencies on other skills (primarily knowledge skills) for documentation and validation:
```yaml
depends-on: clean-code, api-patterns
```
- CSV list of skill directory names
- Validated by `validate.py` — each dep must exist as `app/skills/{dep}/SKILL.md`
- Reported in `evaluate_skills.py` quality metrics
- No runtime autoloading — Claude loads knowledge skills contextually based on topic matching

### SLM Compilation (`compile-slm`)

Compiles the full toolkit into a minimal system prompt for local Small Language Models (Ollama, LM Studio, Aider, Continue.dev). Pipeline: Parse → Score → Compress → Pack → Validate → Emit.

| Flag | Purpose |
|------|---------|
| `--model-size` | 7b/8b/14b/32b/70b — auto-selects budget + compression level |
| `--budget` | Token budget override (2K-16K) |
| `--persona` | Boost persona-relevant skills in scoring |
| `--lang` | Include language-specific rules |
| `--format` | Output: raw, ollama, json-string, aider |
| `--dry-run` | Preview included components + token utilization |

Profile `offline-slm` in `manifest.json` — installs core only, then compiles.

### Executable Scripts (18 total, stdlib-only, JSON output)

| Skill | Script | Purpose |
|-------|--------|---------|
| **commit** | `scripts/pre-commit-check.py` | Staged files, secrets detection |
| **test** | `scripts/detect-runner.py` | Auto-detect test framework |
| **lint** | `scripts/detect-linters.py` | Detect available linters |
| **build** | `scripts/detect-build.py` | Detect build system |
| **deploy** | `scripts/pre_deploy_check.py` | Pre-deployment readiness |
| **rollback** | `scripts/rollback_info.py` | Rollback context |
| **migrate** | `scripts/migration-status.py` | Detect migration tool, status |
| **ci** | `scripts/ci-detect.py` | Detect CI platform |
| **fix** | `scripts/error-classifier.py` | Classify lint/test errors |
| **pr** | `scripts/pr-summary.py` | Generate PR title/description |
| **review** | `scripts/diff-analyzer.py` | Parse git diff, categorize files |
| **debug** | `scripts/error-parser.py` | Parse stack traces |
| **explore** | `scripts/visualize.py` | Interactive HTML codebase tree |
| **explain** | `scripts/dependency-graph.py` | Import graph → Mermaid |
| **docs** | `scripts/doc-inventory.py` | Inventory docs, measure coverage |
| **refactor** | `scripts/refactor-scan.py` | Detect code smells |
| **health** | `scripts/health_check.py` | JSON health report |
| **analyze** | `scripts/complexity.py` | Code complexity metrics |

---

## kb/reference/skills-unification.md

---
title: "Skills Unification Model"
category: reference
service: ai-toolkit
tags: [skills, commands, architecture, classification]
version: "1.0.0"
created: "2026-03-25"
last_updated: "2026-03-28"
description: "Reference explanation of why ai-toolkit standardizes on the Agent Skills format for slash-command behavior."
---

# Skills Unification Model

## Summary

`ai-toolkit` standardizes on the Agent Skills directory format for all reusable slash-command behavior.

The toolkit no longer treats commands and skills as separate implementation models. Instead, it uses one consistent format:

- task skills,
- hybrid skills,
- knowledge skills.

## Why this model is used

The Agent Skills format supports capabilities that plain command markdown files do not:
- richer frontmatter,
- progressive disclosure,
- bundled scripts,
- templates and reference files,
- cross-tool compatibility.

## Classification

| Type | Frontmatter signal | Purpose |
|------|--------------------|---------|
| Task skill | `disable-model-invocation: true` | explicit user-triggered actions |
| Hybrid skill | default invocation | user-invocable + agent-usable workflows |
| Knowledge skill | `user-invocable: false` | auto-loaded patterns and conventions |

## Consequences

### Positive
- one mental model for reusable behavior,
- easier validation,
- simpler install logic,
- better alignment with Claude Code ecosystem conventions.

### Trade-offs
- more directories than a flat commands model,
- stronger need for naming and frontmatter conventions,
- documentation and generators must stay synchronized with counts.

## Related Documents

- `kb/reference/skills-catalog.md`
- `kb/reference/architecture-overview.md`

---

## kb/reference/stats.md

---
title: "AI Toolkit - Usage Statistics"
category: reference
service: ai-toolkit
tags: [stats, usage, tracking, analytics]
version: "1.0.0"
created: "2026-03-29"
last_updated: "2026-03-29"
description: "Local usage tracking for skill invocations. CLI command, JSON format, hook mechanism."
---

# Usage Statistics

## Overview

`ai-toolkit stats` tracks how often each skill is invoked via slash commands. All data is local — stored in `~/.softspark/ai-toolkit/stats.json`. No telemetry, no network calls.

## CLI Commands

```bash
ai-toolkit stats           # Show usage table (sorted by count)
ai-toolkit stats --reset   # Clear all stats
ai-toolkit stats --json    # Output raw JSON
```

## How It Works

A `UserPromptSubmit` hook (`track-usage.sh`) fires on every prompt. When the prompt starts with `/skill-name`, it increments the counter in `stats.json`.

### Hook Details
- **Event**: `UserPromptSubmit`
- **Script**: `~/.softspark/ai-toolkit/hooks/track-usage.sh`
- **Detection**: `grep -oE '^/[a-z][a-z0-9-]*'`
- **Storage**: Atomic write via python3 `os.replace()`
- **Overhead**: ~50ms (python3 startup + JSON read/write)

## JSON Format

```json
{
  "commit": {
    "count": 42,
    "last_used": "2026-03-29 14:30:00"
  },
  "review": {
    "count": 15,
    "last_used": "2026-03-28 09:12:00"
  }
}
```

## Output Example

```
AI Toolkit Usage Stats
========================

Skill                           Count  Last Used
------------------------------------------------------------
commit                             42  2026-03-29 14:30:00
review                             15  2026-03-28 09:12:00
debug                               8  2026-03-27 16:45:00

Total invocations: 65
Unique skills: 3

File: ~/.softspark/ai-toolkit/stats.json
Reset: ai-toolkit stats --reset
```

---

## kb/reference/supported-tools-registry.md

---
title: "Supported Tools Registry"
category: reference
service: ai-toolkit
tags: [editors, platforms, generators, integration, ecosystem]
version: "1.11.0"
created: "2026-04-23"
last_updated: "2026-07-23"
description: "Human-readable view of scripts/ecosystem_tools.json — the canonical list of tools ai-toolkit integrates with (Claude Code, Claude Chat/Cowork, and 11 editors), their documentation URLs, config paths, our generators, and tracked capability markers."
---

# Supported Tools Registry

The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed by `scripts/ecosystem_doctor.py`. This document is a derived view — when the JSON changes, update this table too.

## Tool Count: 13

1 primary runtime (Claude Code) + 1 Claude app target + 11 editor integrations.

---

## Primary Runtime

### Claude Code

| Field | Value |
|-------|-------|
| ID | `claude-code` |
| Docs | https://code.claude.com/docs (platform.claude.com/docs 307-redirects here) |
| Release notes | https://github.com/anthropics/claude-code/releases |
| Changelog | https://code.claude.com/docs/en/changelog; GitHub release feed is authoritative when the generated page lags (current local/release: 2.1.206, 2026-07-10) |
| Config paths | `~/.claude/settings.json`, `.claude/settings.json` (project, committed), `.claude/settings.local.json`, `CLAUDE.md`, `.claude/rules/*.md`, `.claude/agents/*.md`, `.claude/skills/*/SKILL.md`, `~/.claude/themes/*.json` (v2.1.118+) |
| Our generators | — (Claude Code is the primary target; toolkit content ships directly as `.md` files and `settings.json` merges) |
| Tracked hook events | Core: `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `Notification`, `MessageDisplay`. Tool: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PostToolBatch`. Turn: `Stop`, `StopFailure`, `UserPromptExpansion`. Subagent: `SubagentStart`, `SubagentStop`. Compaction: `PreCompact`, `PostCompact`. Permissions: `PermissionRequest`, `PermissionDenied`. Elicitation: `Elicitation`, `ElicitationResult`. Teams: `TaskCreated`, `TaskCompleted`, `TeammateIdle`. Worktrees/env: `WorktreeCreate`, `WorktreeRemove`, `CwdChanged`, `FileChanged`, `ConfigChange`. Setup: `Setup`, `InstructionsLoaded` |
| Tracked handler types | `command`, `prompt`, `agent`, `mcp_tool`, `http` (POST event JSON to allowlisted URLs via `allowedHttpHookUrls`) |
| Other capabilities | slash commands, MCP server/client, sub-agent, output style, `SKILL.md` (≥500 lines warn) |
| Version probe | `claude --version` |
| Notes | v2.1.169 added `disableBundledSkills` setting + `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` env var (hides bundled skills/built-in slash commands from the model; toolkit skills in `.claude/skills/` are unaffected — useful when toolkit skills overlap built-ins) and `claude --safe-mode` / `CLAUDE_CODE_SAFE_MODE` (starts with hooks, skills, agents, and CLAUDE.md disabled — first isolation step when debugging toolkit rule enforcement). `fallbackModel` settings key (v2.1.166) noted as not-adopted (class C, no toolkit surface writes model settings). |

---

## Claude App Target

### Claude Chat / Cowork

| Field | Value |
|-------|-------|
| ID | `claude-app` |
| Docs | https://support.claude.com/en/articles/13345190-get-started-with-claude-cowork |
| Plugin docs | https://support.claude.com/en/articles/13837440-use-plugins-in-claude |
| Config surfaces | `Settings > Cowork > Global instructions`, Cowork folder instructions, `Customize > Skills`, and `Customize > Plugins` |
| Plugin layout | `.claude-plugin/plugin.json`, `skills/*/SKILL.md`, `agents/*.md`, `hooks/hooks.json`; ai-toolkit uses manifest paths under `claude-app/` for its generated app-only rules and hooks |
| Our generator | `scripts/claude_app.py` (`ai-toolkit claude-app export`) |
| Runtime split | Skills work in Chat (web/Desktop) and Cowork. Hooks and sub-agents run only in Cowork. Claude app does **not** scan Claude Code's `~/.claude/rules/`, `CLAUDE.md`, or `~/.claude/settings.json`. |
| Install/update | Export the ZIP, upload it from `Customize > Plugins`, then paste the generated global-instructions file into `Settings > Cowork > Global instructions`. Re-export/re-upload after toolkit updates. |

---

## Editor Integrations

### Cursor

| Field | Value |
|-------|-------|
| ID | `cursor` |
| Docs | https://cursor.com/docs |
| Changelog | https://cursor.com/changelog |
| Stable docs mirror | https://cursor.com/llms.txt (all doc pages have .md twins) |
| Config paths | `.cursorrules` (**legacy** — no longer in cursor.com/docs/rules; deprecated ~0.43–0.45 in favor of `.cursor/rules/*.mdc`, still read, no removal deadline; we keep emitting for back-compat), `.cursor/rules/*.mdc` (plain `.md` files in `.cursor/rules/` are **ignored** by the rules system), `AGENTS.md`, `.cursor/mcp.json`, `~/.cursor/mcp.json`, `.cursor/hooks.json`, `~/.cursor/hooks.json` (user-level hooks scope; enterprise system paths + dashboard team hooks not adopted, class C), `.cursor/skills/*/SKILL.md`, `~/.cursor/skills/*/SKILL.md`, `.cursor/agents/*.md`, `~/.cursor/agents/*.md` |
| Compat read paths | skills: `.agents/skills/`, `~/.agents/skills/`, `.claude/skills/`, `~/.claude/skills/`, `.codex/skills/`, `~/.codex/skills/`; subagents: `.claude/agents/`, `~/.claude/agents/`, `.codex/agents/`, `~/.codex/agents/` (`.cursor/` wins on name conflicts) |
| Our generators | `scripts/generate_cursor_rules.py`, `scripts/generate_cursor_mdc.py`, `scripts/generate_cursor_hooks.py` (complete version-1 event set plus self-contained `.cursor/hooks/ai-toolkit/cursor_hook.py`; profile=full local **and** global `~/.cursor/hooks.json`), `scripts/generate_cursor_agents.py` (profile=full), `scripts/generate_cursor_skills.py` (profile=full pointer) |
| Global install | Cursor is in `GLOBAL_CAPABLE_EDITORS` for **hooks only**: `ai-toolkit install --editors cursor` writes `~/.cursor/hooks.json` (profile ≥ standard). RULES stay project-local (Cursor's only global rules surface is the Settings UI). |
| Tracked capabilities | `cursorrules`, `.cursor/rules`, `AGENTS.md`, `mcp.json`, Composer, Agent Mode, hooks.json, subagents, skills, plugins |
| Hook compatibility | Cursor 3.11 project hooks run locally and in cloud agents from repository `.cursor/hooks.json`; cloud VMs do not load `~/.cursor/hooks.json`. The generated project manifest uses only documented command-entry keys, calls a repo-relative runtime, covers conversation hooks including `afterAgentResponse` and `afterAgentThought`, preserves user entries, and caps `stop`/`subagentStop` follow-up loops at 5. |

### Windsurf

| Field | Value |
|-------|-------|
| ID | `windsurf` |
| Docs | https://docs.devin.ai/desktop (Windsurf rebranded to Devin Desktop ~2026-06-02; docs.windsurf.com resolves here) |
| Changelog | https://docs.devin.ai/desktop/changelog (windsurf.com/changelog 308-permanent-redirects here) |
| Stable docs mirror | https://docs.devin.ai/desktop/... per-page .md twins; legacy `.windsurf/`, `.windsurfrules`, `~/.codeium/windsurf/` rule paths still read as fallback (new canonical rules/hooks tree: `.devin/`) |
| Config paths | **Primary (Devin Desktop):** `.devin/rules/*.md`, `.devin/workflows/*.md`, `.devin/hooks.v1.json` (Devin CLI hooks, Claude format), `.devin/config.json`, `.devin/config.local.json`, `~/.config/devin/config.json` (Devin Local MCP/permissions). **Skills:** eight documented paths, all scanned in every repo — `.agents/skills/*/SKILL.md` (recommended), `.devin/skills`, `.github/skills`, `.claude/skills`, `.cursor/skills`, `.codex/skills`, `.cognition/skills`, and `.windsurf/skills`. ai-toolkit emits a single canonical pointer under `.windsurf/skills` to avoid duplicate registration. **Legacy fallback:** `.windsurfrules`, `.windsurf/rules/*.md`, `.windsurf/workflows/*.md`, `~/.codeium/windsurf/memories/global_rules.md`, `~/.codeium/windsurf/skills/*/SKILL.md`, `~/.codeium/windsurf/mcp_config.json`. Plus `AGENTS.md`. |
| Compat read paths | Current skill docs explicitly scan all eight paths — `.agents/skills/`, `.devin/skills/`, `.github/skills/`, `.claude/skills/`, `.cursor/skills/`, `.codex/skills/`, `.cognition/skills/`, and `.windsurf/skills/`. **Hooks:** Devin CLI reads `.claude/settings.json` + `~/.claude/settings.json` hooks when `read_config_from.claude` is enabled, so globally-installed toolkit hooks also work under Devin. |
| Our generators | `scripts/generate_windsurf.py`, `scripts/generate_windsurf_rules.py` (dual-emits `.devin/` + `.windsurf/` rules/workflows), `scripts/generate_devin_hooks.py` (profile=full; `.devin/hooks.v1.json`), `scripts/generate_windsurf_skills.py` (`.windsurf/skills` pointer) |
| Global install | `ai-toolkit install --editors windsurf` writes `~/.codeium/windsurf/memories/global_rules.md` + skills pointer **and** `~/.config/devin/AGENTS.md` (Devin CLI global rules — the Desktop `global_rules.md` path is absent from `read_config_from.windsurf`, so editor-only Devin CLI installs need this). |
| Tracked capabilities | Cascade, `windsurfrules`, `AGENTS.md`, activation triggers (`always_on`/`glob`/`model_decision`), workflows, skills, MCP, memories, hooks |
| Activation modes emitted | always_on (agents/security/quality), glob (testing + language rules), model_decision (code-style/workflow) |
| Hooks migration | **Complete.** Cascade and `.windsurf/hooks.json` ended on 2026-07-01. `generate_devin_hooks.py` is now the only Windsurf-family hook generator and emits `.devin/hooks.v1.json` with Claude-style events, Devin tool-name matchers, and the flat Devin block contract. |
| Latest upstream | Devin Desktop v3.4.27 (2026-07-07). v3.4.22 made skill `permissions:` frontmatter affect auto-approvals; ai-toolkit does not emit permissions because its pointer skill executes no privileged workflow. |

### GitHub Copilot

| Field | Value |
|-------|-------|
| ID | `github-copilot` |
| Docs | https://docs.github.com/en/copilot |
| Release notes | https://github.blog/changelog/label/copilot/ |
| Native docs | [Hooks reference](https://docs.github.com/en/copilot/reference/hooks-reference), [skills](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills), [CLI config directory](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-config-dir-reference) |
| Config paths | **Repo (`.github/`):** `.github/copilot-instructions.md`, `.github/instructions/*.instructions.md`, `.github/prompts/*.prompt.md`, `.github/agents/*.agent.md`, `.github/skills/<name>/SKILL.md`, `.github/hooks/*.json`, `AGENTS.md`. **Copilot CLI user-level (`~/.copilot/`, `COPILOT_HOME` override):** `copilot-instructions.md`, `instructions/*.instructions.md`, `agents/*.agent.md`, `skills/<name>/SKILL.md`, `hooks/*.json`, `settings.json`, `mcp-config.json` below the active config root. |
| Compat read paths | Copilot also discovers project `.claude/skills` and `.agents/skills`, and personal `~/.agents/skills`. ai-toolkit nevertheless materializes self-contained native skills under `.github/skills` and the active Copilot config root so assets and helper scripts remain available and `COPILOT_HOME` sessions do not depend on fallback discovery. |
| Our generators | `scripts/generate_copilot.py` (instructions, prompts, agents, and portable skill directories), `scripts/generate_copilot_hooks.py` (native version-1 hook config plus self-contained runtime) |
| Global install | `ai-toolkit install --editors copilot` writes instructions, agents, skills, and, for profile ≥ `standard`, native hooks below `$COPILOT_HOME` when set or `~/.copilot` otherwise. VS Code Copilot and GitHub.com use repo `.github/` files, so local emission remains required. |
| Tracked capabilities | `copilot-instructions.md`, Copilot Chat, Copilot Workspace, Copilot cloud agent, `applyTo`, custom agents, prompt files, `instructions.md`, `AGENTS.md`, MCP, skills, CLI hooks, `~/.copilot/` |
| Compatibility notes | Custom agents use native `.agent.md` files with `name` and `description`; `tools` is omitted instead of guessing editor-specific aliases. Prompt and skill bodies remove Claude-only interpolation and delegation APIs. Hooks use the GitHub version-1 schema, camelCase event names, native decision payloads, and a repository/config-root-contained Python runtime instead of Claude hook scripts. Project MCP remains owned by the editor MCP sync path. Copilot code review also reads the nearest `AGENTS.md`; local install keeps its generated section separate from Codex/OpenCode sections. Surface loading semantics and the prompt/skill duplication are documented in `kb/reference/copilot-compatibility.md`. |

### Gemini CLI

| Field | Value |
|-------|-------|
| ID | `gemini-cli` |
| Docs | https://github.com/google-gemini/gemini-cli/tree/main/docs |
| Release notes | https://github.com/google-gemini/gemini-cli/releases |
| Config paths | `GEMINI.md`, `.gemini/settings.json`, `~/.gemini/settings.json`, `.gemini/commands/*.toml`, `.gemini/skills/*/SKILL.md`, `.agents/skills/*/SKILL.md`, `~/.gemini/skills/*/SKILL.md`, `~/.agents/skills/*/SKILL.md` (the `.agents/skills` alias wins over `.gemini/skills` within the same tier), `.gemini/extensions/gemini-extension.json` |
| Our generators | `scripts/generate_gemini.py`, `scripts/generate_gemini_hooks.py` (profile>=standard), `scripts/generate_gemini_commands.py` (profile=full), `scripts/generate_gemini_skills.py` (profile=full) |
| Global install | `ai-toolkit install --editors gemini` writes `~/.gemini/GEMINI.md` **plus** hooks at `~/.gemini/settings.json` (profile ≥ standard) and `~/.gemini/commands/` + `~/.gemini/skills/` pointer (profile=full) — all documented user-tier surfaces. A global-only Gemini user previously got zero hooks. |
| Tracked capabilities | `GEMINI.md`, `mcpServers`, tools, `settings.json`, `BeforeTool`, `AfterTool`, `BeforeToolSelection`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `Notification`, `PreCompress`, `SessionStart`, `SessionEnd`, `SKILL.md`, `activate_skill`, custom commands, `.gemini/agents/*.md` subagents, `gemini-extension.json` (no native `Stop` event — generator maps Stop-equivalent to `AfterAgent`; 11 documented hook events total) |
| Version probe | `gemini --version` |
| Latest upstream | v0.49.0 (2026-06-25; the stable line skipped v0.48.0 — its preview content was promoted into v0.49.0). NOTE: Gemini CLI dropped free/paid individual tiers on 2026-06-18 in favor of Antigravity CLI (we ship `generate_antigravity.py`); enterprise Code Assist and paid API keys keep Gemini CLI, so the integration stays. The 11 hook events are unchanged. v0.49.0 completed the `coreTools` → `tools.core` migration (auto-migrated; `tools.exclude` deprecated) — both are tool-allowlist keys we do not emit, so no generator change. Watch item: `.gemini/agents/*.md` / `~/.gemini/agents/*.md` native subagents are documented but we do not yet emit them (candidate `generate_gemini_agents.py`). |

### Cline

| Field | Value |
|-------|-------|
| ID | `cline` |
| Docs | https://docs.cline.bot |
| Release notes | https://github.com/cline/cline/releases |
| Config paths | **Extension:** `.clinerules/*.md`, `.clinerules/workflows/*.md`, `.clinerules/skills/*/SKILL.md`, `.clinerules/hooks/` (project), `~/Documents/Cline/Rules/Hooks/` (global hooks), `~/.cline/data/settings/cline_mcp_settings.json`. **CLI/SDK unified layout** (docs.cline.bot/getting-started/config; `.clinerules` is deprecated there): `.cline/{rules,hooks,plugins,skills}/`, `~/.cline/{rules,hooks,plugins,skills}/`, `CLINE_HOOKS_DIR` env var. **Cross-tool:** `AGENTS.md` + `~/.agents/AGENTS.md` (first-class rules sources), `.claude/skills/*/SKILL.md` (native discovery, always-on since v3.57.0). |
| Our generators | `scripts/generate_cline.py`, `scripts/generate_cline_rules.py`, `scripts/generate_cline_skills.py` |
| Tracked capabilities | `clinerules`, Plan Mode, Act Mode, MCP, custom modes, workflows, hooks, skills, subagents, conditional rules, `AGENTS.md`, plugins |
| Plugins | `.cline/plugins/` + `~/.cline/plugins/` (JS/TS), `package.json` `cline.plugins` manifest; plugins can bundle skills. Not adopted as a distribution channel yet — candidate for shipping toolkit skills to CLI/SDK users. |
| Notes | Conditional rules (`paths:` YAML frontmatter) are emitted for testing and language-specific rules since 2026-04. Project rules still use `.clinerules/` for compatibility; global rules are written to `~/Documents/Cline/Rules/` (the documented Cline global rules dir — `~/.cline/rules/` is not a Cline-read path). Skills are emitted as a pointer catalogue in `profile=full` and global installs. |
| Global install | `ai-toolkit install --editors cline` writes documented global rules under `~/Documents/Cline/Rules/` and a skill pointer under `~/.cline/skills/`; MCP remains managed by `ai-toolkit mcp install --editor cline`. |

### Roo Code

| Field | Value |
|-------|-------|
| ID | `roo-code` |
| Docs | https://roocodeinc.github.io/Roo-Code (frozen; docs.roocode.com 301-redirects here). Successor docs: https://docs.zoocode.dev |
| Release notes | https://github.com/Zoo-Code-Org/Zoo-Code/releases (authoritative). **Original RooCodeInc/Roo-Code repo ARCHIVED/read-only since 2026-05-15, frozen at v3.54.0 — its feed is dead.** Successor project by former Roo contributors: **Zoo-Code-Org/Zoo-Code** (marketplace `ZooCodeOrganization.zoo-code`), active through v3.64.0 (2026-06-26). |
| Config paths | `.roomodes` (JSON still fully supported), `.roo/rules/*.md`, `.roo/rules-{slug}/*.md`, `.roo/skills/*/SKILL.md`, `~/.roo/skills/*/SKILL.md`, `.agents/skills/*/SKILL.md`, `~/.agents/skills/*`, `.roo/commands/*.md`, `~/.roo/commands/*.md`, `.roo/mcp.json`, `~/.roo/rules/`, `mcp_settings.json` + global custom modes live in VS Code globalStorage (`<globalStorage>/rooveterinaryinc.roo-cline/settings/custom_modes.yaml`), NOT `~/.roo/custom_modes.yaml` |
| Our generators | `scripts/generate_roo_modes.py`, `scripts/generate_roo_rules.py` |
| Tracked capabilities | `roomodes`, custom modes, Code Actions, MCP, Orchestrator mode, `whenToUse`, `description`, `roleDefinition`, `groups`, skills, slash commands |
| Notes | Config compat with the Zoo fork is total, so both generators stay valid unchanged. `.roomodes` includes `description`/`whenToUse` for every mode (since 2026-04); JSON is still accepted (YAML is upstream-preferred but not emitted). Global install writes `~/.roo/rules/` plus `~/.agents/skills/*` (Roo/Zoo native skill discovery, shipped v3.46.0/v3.47.2; skipped when `codex` is also selected). `~/.roo/commands/` (global slash commands, since v3.25) is a documented surface not yet generated. |

### Aider

| Field | Value |
|-------|-------|
| ID | `aider` |
| Docs | https://aider.chat/docs |
| Changelog | https://aider.chat/HISTORY.html |
| Config paths | `.aider.conf.yml`, `CONVENTIONS.md`, `~/.aider.conf.yml` |
| Our generators | `scripts/generate_aider_conf.py`, `scripts/generate_conventions.py` |
| Tracked capabilities | `.aider.conf.yml`, `CONVENTIONS.md`, `architect`, `auto-accept-architect`, `read`, `lint-cmd`, `test-cmd`, `commit-prompt`, `attribute-co-authored-by`, `chat-language`, `commit-language`, `watch-files`, `auto-commits` |
| Global install | `ai-toolkit install --editors aider` creates `~/.aider.conf.yml` only when absent and always refreshes `~/.aider-ai-toolkit-CONVENTIONS.md`; existing YAML is preserved. |
| Version probe | `aider --version` |
| Latest upstream | v0.86.1 (Aug 2025) |

### Augment

| Field | Value |
|-------|-------|
| ID | `augment` |
| Docs | https://docs.augmentcode.com |
| Changelog | https://www.augmentcode.com/changelog |
| Config paths | `.augment/rules/*.md`, `.augment-guidelines` (workspace root, legacy single-file), `~/.augment/user-guidelines.md`, `.augment/agents/*.md`, `.augment/commands/*.md`, `.augment/skills/*/SKILL.md`, `.augment/settings.json`, `.augment/settings.local.json`, `~/.augment/rules/*.md`, `~/.augment/settings.json`, `/etc/augment/settings.json`. Auggie CLI also discovers skills/commands from `.claude/` and `.agents/` (`.augment/` wins on precedence). |
| Our generators | `scripts/generate_augment.py`, `scripts/generate_augment_rules.py`, `scripts/generate_augment_agents.py` (profile=full), `scripts/generate_augment_commands.py` (profile=full), `scripts/generate_augment_hooks.py` (profile=full, HOME-scoped), `scripts/generate_augment_skills.py` (profile=full) |
| Global install | `ai-toolkit install --editors augment` writes `~/.augment/rules/ai-toolkit.md` **plus** (profile=full) `~/.augment/agents/`, `~/.augment/commands/`, and hooks in `~/.augment/settings.json` — all documented user-tier surfaces. A global-only Augment user previously got no hooks/agents/commands. Skills need no global emission: Auggie natively reads `~/.claude/skills/`. |
| Tracked capabilities | `.augment`, Agent mode, Next Edit, MCP, context engine, Auggie CLI, `always_apply`, `agent_requested`, subagents, custom commands, `SKILL.md`, `PreToolUse`, `PostToolUse`, `SessionStart`, `SessionEnd`, `Stop`, `Notification`, ACP Mode, plugins/marketplace |
| Latest / notes | Auggie CLI v0.31.0. Since v0.30.0 (2026-06-25) `PreToolUse`/`PostToolUse` hooks fire during sub-agent sessions. The shared hook input adapter normalizes Augment's `conversation_id`, so edit and quality state remains isolated across parallel sub-agents. `Notification` is enum-only (doctor flipped its marker), with no dedicated handler documented, so class C (do NOT wire). Plugins/marketplace (`auggie plugin marketplace add`, `.augment-plugin`/`.claude-plugin` layouts, `enabledPlugins`/`autoUpdateMarketplaces` in settings) are documented but not yet a shipping target. |
| SPA caveat | Mintlify Next.js SPA; use `https://docs.augmentcode.com/<path>.md` siblings (discoverable via `/llms.txt`) for machine reads |

### Google Antigravity

| Field | Value |
|-------|-------|
| ID | `google-antigravity` |
| Docs | https://antigravity.google/docs (JavaScript SPA — use bundle strings / sitemap to verify) |
| Changelog | https://antigravity.google/changelog (SPA; changelog entries embedded in main-*.js) |
| Config paths | `.agents/rules/*.md`, `.agents/workflows/*.md` (plural is the Antigravity 2.0 default; singular `.agent/rules`, `.agent/workflows` still read as fallback), `.agent/skills/*/SKILL.md` (IDE), `.agents/skills/*/SKILL.md` (CLI), `.agents/hooks.json` (CLI hooks), `.agents/mcp_config.json` (workspace MCP), `AGENTS.md`, `GEMINI.md` |
| Global config paths | Skills: `~/.gemini/config/skills/*/SKILL.md` (shared across all Antigravity products) and `~/.gemini/antigravity-cli/skills/*/SKILL.md` (CLI-private) — both documented in the official Skills codelab. MCP: `~/.gemini/config/mcp_config.json` (shared global, resolved by CLI v1.0.14; the `~/.gemini/antigravity-cli/mcp_config.json` path is legacy). Rules: `~/.gemini/GEMINI.md` (dual-owner with Gemini CLI — Antigravity's IDE "+ Global" writes the same file; gemini-cli#16058 closed "not planned"). Hooks: `~/.gemini/config/hooks.json` (shared, since CLI v1.0.8). |
| Our generators | `scripts/generate_antigravity.py` (rules + workflows + skill pointer dual-emitted to `.agent/skills/` and `.agents/skills/`; `generate_global()` writes the pointer to the two HOME skill dirs). Native MCP project/global merge and removal are provided by `scripts/mcp_editors.py`. |
| Global install | `ai-toolkit install --editors antigravity` writes the skill pointer to `~/.gemini/config/skills/` and `~/.gemini/antigravity-cli/skills/`. Rules stay project-local (no mergeable global rules file beyond the Gemini-CLI-shared `~/.gemini/GEMINI.md`, covered by `--editors gemini`). `ai-toolkit mcp install --editor antigravity <template>` writes the global MCP config; add `--scope project --target <repo>` for `.agents/mcp_config.json`. |
| Tracked capabilities | Antigravity, agent manager, artifacts, MCP, workflows, rules, skills, hooks, `AGENTS.md`, `GEMINI.md`, agent permissions, global skills, `~/.gemini/config/mcp_config.json` |
| CLI notes | Antigravity CLI (GA 2026-05-19; latest CLI v1.0.14 2026-06-30, IDE 2.2.1). Hooks are IDE + CLI (`.agents/hooks.json` workspace, `~/.gemini/config/hooks.json` global; event set `PreToolUse`/`PostToolUse`/`PreInvocation`/`PostInvocation`/`Stop` — `PreInvocation`/`PostInvocation` have no Claude equivalent; shell tool is `run_command` with args at `.toolCall.args.CommandLine`). MCP: the official 2.1.4 changelog (2026-06-11) confirms that `url` is accepted alongside `serverUrl`; `httpUrl` is not documented and the adapter rejects it. The native adapter preserves documented `args`, `env`, `cwd`, `headers`, `authProviderType`, `oauth`, `disabled`, and `disabledTools` fields. A `generate_antigravity_hooks.py` remains backlog. |
| Doc access note | Docs are a JavaScript SPA, but the official search index exposes the current MCP guide and changelog text. Verify changelog claims against the dated official entry because the MCP guide's warning can lag schema releases. |

### Codex CLI

| Field | Value |
|-------|-------|
| ID | `codex-cli` |
| Docs | https://learn.chatgpt.com/docs/codex/cli (official Codex CLI documentation; the previous `https://developers.openai.com/codex` endpoint now redirects to the generic ChatGPT Learn overview; latest verified local/npm release: codex-cli 0.144.4, 2026-07-14) |
| Release notes | https://github.com/openai/codex/releases |
| Config paths | **Instructions:** project `AGENTS.md` (root→cwd chain, closest wins) and global `~/.codex/AGENTS.md` (`$CODEX_HOME/AGENTS.md`; `~/.codex/AGENTS.override.md` takes precedence). NOTE: `~/AGENTS.md` is NOT a global-instruction surface — Codex only reads it if a session's cwd is exactly `$HOME`. Plus `.agents/skills/*/SKILL.md`, `.codex/agents/*.toml`, `~/.codex/agents/*.toml`, `.codex/hooks.json`, `~/.codex/hooks.json`, `.codex/config.toml` (project layers, root→cwd, closest wins, trusted projects only), `~/.codex/config.toml`. |
| Our generators | `scripts/generate_codex.py`, `scripts/generate_codex_agents.py` (native custom-agent TOML), `scripts/generate_codex_hooks.py`, `scripts/generate_codex_skills.py` (opt-in via `--codex-skills`) |
| Rules delivery | Universal coding rules are inlined into `AGENTS.md` (Codex reads instructions only from AGENTS.md, not `.agents/rules/`); language rules ship as `<lang>-rules` skills under `.agents/skills/`. Global install writes `~/.codex/AGENTS.md` (not `~/AGENTS.md`, which Codex never loads globally); plugin-pack rules are marker-injected into the same file. `project_doc_max_bytes` default is 32 KiB and Codex silently truncates AGENTS.md past that (see codex-cli-compatibility.md). |
| Tracked hook events | Upstream canonical (codex-rs `HookEventName` enum): `PreToolUse`, `PostToolUse`, `PermissionRequest`, `PreCompact`, `PostCompact`, `SessionStart`, `UserPromptSubmit`, `SubagentStart`, `SubagentStop`, `Stop` (10 events). We wire 9 through an explicit Codex map, including destructive-command and wrong-home path guards on both Bash `PreToolUse` and `PermissionRequest`. `PostCompact` is not wired (its only hook was the removed environment-snapshot probe). |
| Tracked handler types | `command` (emitted by default; the only handler Codex actually runs). `prompt` and `agent` are parsed by Codex but NOT yet executed, so hand-authored handlers of those types are inert. |
| Other capabilities | `AGENTS.md`, `config.toml`, `mcp_servers`, sandbox policies, `.agents/skills/*/SKILL.md` (native Codex skill discovery path), `.codex/agents/*.toml` (native custom agents) |
| Version probe | `codex --version` |

### opencode

| Field | Value |
|-------|-------|
| ID | `opencode` |
| Docs | https://opencode.ai/docs |
| Release notes | https://github.com/sst/opencode/releases (redirects to anomalyco/opencode) |
| Config paths | `opencode.json`, `.opencode/agents/*.md`, `.opencode/commands/*.md`, `.opencode/plugins/*`, `.opencode/skills/*/SKILL.md` (v1.14+), `AGENTS.md`; skill fallback discovery: `.claude/skills/`, `.agents/skills/`, `~/.config/opencode/skills/`, `~/.claude/skills/`, `~/.agents/skills/` |
| Our generators | `scripts/generate_opencode.py`, `scripts/generate_opencode_agents.py`, `scripts/generate_opencode_commands.py`, `scripts/generate_opencode_json.py`, `scripts/generate_opencode_plugin.py` |
| Hook isolation | Tool hooks preserve native `sessionID` as normalized `session_id`; exit code 2 from a blocking pre-tool guard is raised back to OpenCode instead of being ignored. |
| Tracked plugin events | `session.created`, `session.compacted`, `session.deleted`, `message.updated`, `tool.execute.before`, `tool.execute.after`, `permission.asked`, `command.executed` |
| Other capabilities | `opencode.json` config, primary + subagent modes, `@`-mention subagents, `/`-invocation commands, MCP (local + remote), plugin hooks in JS/TS, native `SKILL.md` discovery with Claude-compatible fallback, `permission.skill.*` matrix |
| Version probe | `opencode --version` |
| Watch item | v1.16.0 (2026-06-05) shipped an experimental v2 skill registry (flat-file skills, `slash` frontmatter key). As of the 2026-06-23 sync (upstream v1.17.9) it is still undocumented and not stabilized: the skills docs show only the nested `SKILL.md` layout with no `slash` key, so `generate_opencode*.py` is unchanged. Re-check next sync. |

---

## How the Registry is Consumed

```
┌─────────────────────────┐
│  ecosystem_tools.json   │  ← authoritative config (this doc mirrors it)
└──────────┬──────────────┘
           │ read
           ▼
┌─────────────────────────┐     ┌─────────────────────────────────┐
│  ecosystem_doctor.py    │◄───►│  ecosystem-doctor-snapshot.json │  (last-seen state)
└──────────┬──────────────┘     └─────────────────────────────────┘
           │ emits
           ▼
    Drift report  (JSON or text)  →  human review  →  generator updates  →  commit
```

---

## Adding a New Tool

1. Append an entry to `scripts/ecosystem_tools.json` with all required fields (schema: `schema_version: 1`).
2. Add a generator under `scripts/generate_<tool>_*.py` (or link to an existing one).
3. Update this registry doc with a new section matching the format above.
4. Baseline the snapshot: `python3 scripts/ecosystem_doctor.py --update --tool <id>`.
5. Run the doctor again to confirm clean state: `python3 scripts/ecosystem_doctor.py --tool <id> --format text`.
6. Update tool count at the top of this document.

---

## Removing a Tool

1. Delete the tool's entry from `scripts/ecosystem_tools.json`.
2. Delete its section from this document.
3. Delete its snapshot entry from `benchmarks/ecosystem-doctor-snapshot.json` (or let the next `--update` prune it — currently not pruned automatically).
4. Decide whether to keep the generator (`scripts/generate_<tool>_*.py`) for backwards compatibility or delete it.
5. Remove references from `README.md`, `manifest.json` `description` field, and `kb/procedures/maintenance-sop.md` `Supported editors` line.

---

## Related

- [Ecosystem Sync SOP](../procedures/ecosystem-sync-sop.md) — how to use the doctor
- [MCP Editor Compatibility](./mcp-editor-compatibility.md) — MCP-specific subset
- `scripts/ecosystem_tools.json` — source of truth
- `scripts/ecosystem_doctor.py` — drift detector
- `benchmarks/ecosystem-doctor-snapshot.json` — last-seen state

---

## kb/reference/sync.md

---
title: "AI Toolkit - Config Sync"
category: reference
service: ai-toolkit
tags: [sync, gist, portability, config, backup]
version: "1.0.0"
created: "2026-03-29"
last_updated: "2026-03-29"
description: "Sync ai-toolkit config to/from GitHub Gist for cross-machine portability."
---

# Config Sync

## Overview

`ai-toolkit sync` exports and imports your toolkit configuration (rules, stats) via GitHub Gist or local files. Zero infrastructure — uses `gh` CLI for Gist operations.

## Commands

```bash
ai-toolkit sync --export              # JSON snapshot to stdout
ai-toolkit sync --push                # Create/update secret Gist
ai-toolkit sync --pull [gist-id]      # Pull from Gist and apply
ai-toolkit sync --import <file|url>   # Import from file or URL
```

## What Gets Synced

| Data | Included | Source |
|------|----------|--------|
| Custom rules | Yes | `~/.softspark/ai-toolkit/rules/*.md` |
| Usage stats | Yes | `~/.softspark/ai-toolkit/stats.json` |
| Toolkit version | Yes (metadata) | `package.json` |
| Agents/skills | No | Installed via `npm` |
| Hooks | No | Installed via `ai-toolkit install` |

## Workflow

### First machine (export)
```bash
ai-toolkit sync --push
# Creates secret Gist, saves ID to ~/.softspark/ai-toolkit/.gist-id
```

### Second machine (import)
```bash
ai-toolkit sync --pull abc123def456   # Use gist ID from first push
# Subsequent pulls: ai-toolkit sync --pull  (uses saved ID)
```

## Requirements

- `--export` / `--import`: No external dependencies
- `--push` / `--pull`: Requires [gh CLI](https://cli.github.com) + `gh auth login`

## JSON Schema

```json
{
  "schema_version": 1,
  "exported_at": "2026-03-29T14:00:00+00:00",
  "toolkit_version": "1.0.0",
  "rules": {
    "rule-name": "# Rule content..."
  },
  "stats": {
    "commit": { "count": 42, "last_used": "..." }
  }
}
```

## Security

- Gists are created as **secret** (not discoverable, but accessible via URL)
- Rules may contain project-specific instructions — review before sharing
- No credentials or tokens are stored in the snapshot

---

## kb/reference/unique-features.md

---
title: "Unique Features & Differentiators"
category: reference
service: ai-toolkit
tags: [features, differentiators, constitution, hooks, security, tdd, memory]
created: "2026-04-13"
last_updated: "2026-07-10"
description: "Detailed description of ai-toolkit's unique features: constitution enforcement, hooks system, security scanning, effort budgeting, quality gates, and more."
---

# Unique Features & Differentiators

## 1. Machine-Enforced Constitution

Unlike other toolkits that put safety rules in documentation only, ai-toolkit enforces a 7-article constitution via hooks. The hooks actually **block** 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 `~/.softspark/ai-toolkit/hooks/` on install and referenced from `~/.claude/settings.json`. Easy to read, debug, and extend.

**14 lifecycle events / 28 global hook entries:**

| Event | Script | Action |
|-------|--------|--------|
| SessionStart | `session-start.sh` | MANDATORY rules reminder + session context + instincts + reset session-edit state |
| SessionStart | `mcp-health.sh` | Check MCP server command availability (non-blocking warning) |
| Notification | `notify-waiting.sh` | Cross-platform desktop notification |
| PreToolUse | `guard-destructive.sh` | Block `rm -rf`, `DROP TABLE`, etc. |
| PreToolUse | `guard-path.sh` | Block wrong-user path hallucination |
| PreToolUse | `guard-config.sh` | Block edits to linter/formatter config files unless explicitly requested |
| PreToolUse | `commit-quality.sh` | Advisory validation of git commit messages |
| PreToolUse | `revert-guard.sh` | Block `git checkout/restore/reset --hard/clean` on files edited this session (Art. VI.2) |
| UserPromptSubmit | `user-prompt-submit.sh` | Prompt governance reminder + arm search-first flag only when RAG/Web is available |
| UserPromptSubmit | `track-usage.sh` | Record skill invocations to local stats |
| PostToolUse | `post-tool-use.sh` | Lightweight validation reminders + append edit to session state |
| PostToolUse | `governance-capture.sh` | Log security-sensitive operations to JSONL |
| PostToolUse | `loop-guard.sh` | Detect repeated successful actions and inject a reassessment advisory |
| PostToolUse | `test-cohesion.sh` | Run cohesion-mapped tests after edits; block on failure (Art. VI.3) |
| PostToolUse | `search-tracker.sh` | Clear search-first flag when smart_query/hybrid_search_kb/Web* runs |
| Stop | `quality-check.sh` | Multi-language lint (ruff/tsc/phpstan/dart/go) |
| Stop | `save-session.sh` | Persist session context for cross-session continuity |
| Stop | `quality-gate.sh` | Block final response on lint/type errors + cohesion tests for session edits |
| Stop | `stop-search-check.sh` | Continue conversation if search-first rule was skipped and a provider exists; no-op offline |
| TaskCompleted | `quality-gate.sh` | Block task completion on lint/type errors |
| SubagentStart | `subagent-start.sh` | Narrow-scope reminder for spawned subagents |
| SubagentStop | `subagent-stop.sh` | Completion checklist for subagent handoff |
| PreCompact | `pre-compact.sh` | Smart compaction: prioritized context |
| PreCompact | `pre-compact-save.sh` | Save timestamped context backup |
| SessionEnd | `session-end.sh` | Persist a session-end handoff note |
| InstructionsLoaded | `instructions-audit.sh` | Append every CLAUDE.md / rules load to audit log (which rules actually entered context) |
| ConfigChange | `config-desync-guard.sh` | Warn when `~/.claude/settings.json` drifts from `app/hooks.json` (advisory) |
| TeammateIdle | *(inline)* | Completeness reminder |

**5 skill-scoped hooks:**

| Skill | Hook | Action |
|-------|------|--------|
| `/commit` | Pre | Run linter, block on failure |
| `/test` | Post | Coverage check, report threshold |
| `/deploy` | Post | Health check, rollback if degraded |
| `/migrate` | Pre | Backup verification |
| `/rollback` | Post | State verification |

## 3. Security Scanning

Two complementary security tools:

**`/skill-audit`** — scan skills and agents for code-level risks:

```bash
/skill-audit                              # Interactive (Claude remediation)
python3 scripts/audit_skills.py --ci      # CI mode: exit 1 on HIGH
```

Detects: `eval()`/`exec()`, hardcoded secrets, permission issues, bash risks.

**`/cve-scan`** — scan project dependencies for known CVEs:

```bash
/cve-scan                                 # Auto-detect ecosystems, scan all
python3 app/skills/cve-scan/scripts/cve_scan.py          # Direct invocation
python3 app/skills/cve-scan/scripts/cve_scan.py --json   # Machine-readable
```

Supports: npm, pip, composer, cargo, go, ruby, dart. Uses native audit tools — zero external deps.

**Severity levels:** HIGH (blocks CI), WARN (should fix), INFO (review)

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

## 5. Multi-Language Quality Gates

The `Stop` hook runs after every response across 5 languages:

| Language | Lint | Type Check |
|----------|------|-----------|
| Python | ruff | mypy --strict |
| TypeScript | ESLint/tsc | tsc --noEmit |
| PHP | phpstan | phpstan |
| Dart | dart analyze | dart analyze |
| Go | go vet | go vet |

## 6. Iron Law Enforcement

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

| Skill | Iron Law | What it prevents |
|-------|----------|-----------------|
| `/tdd` | `NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST` | Code written before test? Delete it. Start over. |
| `debugging-tactics` | `NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST` | 4-phase debugging: root cause → pattern → hypothesis → fix. |
| `verification-before-completion` | `NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE` | Gate: IDENTIFY → RUN → READ → VERIFY → CLAIM. |

Additionally, **15 core skills** include `## Common Rationalizations` tables — domain-specific excuses with rebuttals that prevent agent drift.

## 7. Confidence Scoring & Self-Evaluation (`/review`)

The `/review` skill outputs findings with per-issue confidence scores (1-10) and severity classification (critical/major/minor/nit). After completing a review, an LLM-as-Judge self-evaluation pass checks for blind spots: anchoring bias, assumption vs verification, missing unhappy paths, and calibrates confidence scores.

## 8. Agent Verification Checklists

10 key agents include `## Verification Checklist` — exit criteria that MUST be met before presenting results:

| Agent | Key exit criteria |
|-------|------------------|
| `code-reviewer` | Every finding has file:line + evidence, not just opinion |
| `security-auditor` | Each finding includes proof-of-concept or exploit path |
| `test-engineer` | No empty/placeholder tests, mocks only at boundaries |
| `debugger` | Root cause identified, regression test added |
| `backend-specialist` | Input validation, error format, query optimization |
| `frontend-specialist` | Empty/loading/error states, accessibility, responsive |
| `database-architect` | Migration tested on prod-like volume, rollback tested |
| `performance-optimizer` | Baseline measured, profiler evidence attached |
| `devops-implementer` | Dry run passed, rollback documented, no hardcoded secrets |
| `documenter` | Code examples runnable, no placeholders, valid links |

## 9. Skill Reference Routing

7 core skills include `## Related Skills` sections that suggest logical follow-up skills:

```
/review → found issues? → /debug, /tdd, /cve-scan, /analyze
/debug  → bug fixed?   → /review, /tdd, /workflow incident-response
/plan   → approved?    → /orchestrate, /write-a-prd, /grill-me
```

## 10. Two-Stage Review (`/subagent-development`)

Per-task review pipeline inspired by [obra/superpowers](https://github.com/obra/superpowers):

```
Implementer → Spec Compliance Review → Code Quality Review → Next Task
```

- Implementer reports: `DONE` / `DONE_WITH_CONCERNS` / `NEEDS_CONTEXT` / `BLOCKED`
- Spec reviewer: all requirements met, nothing extra, nothing missing
- Quality reviewer: SOLID, naming, error handling, tests, security

## 11. Ralph Wiggum Loop (`/repeat`)

Autonomous agent loop with safety controls:

```bash
/repeat 5m /test          # run tests every 5 min until all pass
/repeat --iterations 3 /review   # max 3 review passes
```

| Safety Control | Default |
|----------------|---------|
| Max iterations | 5 |
| Circuit breaker | 3 consecutive failures → halt |
| Min interval | 1 minute |
| Exit detection | DONE / COMPLETE / ALL PASS |

## 12. Persistent Memory (`memory-pack` plugin)

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

| Component | Purpose |
|-----------|---------|
| `observation-capture.sh` | PostToolUse hook — captures tool actions to SQLite |
| `session-summary.sh` | Stop hook — AI-compress session observations |
| `mem-search` skill | FTS5 full-text search across past sessions |
| `<private>` tags | Content between tags stripped before storage |
| Progressive disclosure | Summary (~500 tok) → relevant (~2k tok) → full |

## 13. Persona Presets

4 engineering personas that adjust Claude's communication style per role:

| Persona | Focus | Key Skills |
|---------|-------|------------|
| `backend-lead` | System design, scalability, data integrity | `/workflow backend-feature`, `/tdd` |
| `frontend-lead` | Component architecture, a11y, Core Web Vitals | `/design-an-interface`, `/review` |
| `devops-eng` | IaC, CI/CD, blast radius, rollback safety | `/workflow infrastructure-change`, `/deploy` |
| `junior-dev` | Step-by-step explanations, learning focus | `/explain`, `/explore`, `/debug` |

Persistent via `--persona` at install time, or session-scoped via `/persona` runtime command.

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

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

---

## kb/reference/windows-support.md

---
title: "Windows Support"
category: reference
service: ai-toolkit
tags: [windows, wsl, install, uninstall, dependencies, hooks, security]
created: "2026-04-24"
last_updated: "2026-07-15"
description: "Windows support model for ai-toolkit: WSL, Git Bash, dependency detection, hooks, and fail-closed managed mutations."
---

# Windows Support

ai-toolkit supports Windows through two practical modes:

1. **WSL recommended** — best compatibility for Bash hooks, POSIX paths, symlinks, and editor configs.
2. **Native Windows with Git Bash** — supported for CLI usage when Bash is available on `PATH`.

## Dependency Detection

`scripts/check_deps.py` now emits install hints for Windows package managers:

| Manager | Command Prefix |
|---------|----------------|
| winget | `winget install` |
| Chocolatey | `choco install -y` |
| Scoop | `scoop install` |

Required dependency package IDs:

| Dependency | winget | Chocolatey | Scoop |
|------------|--------|------------|-------|
| Python 3 | `Python.Python.3` | `python` | `python` |
| Git | `Git.Git` | `git` | `git` |
| Node.js | `OpenJS.NodeJS` | `nodejs` | `nodejs` |

## Hook Runtime

ai-toolkit hooks are Bash scripts. On Windows, use WSL or Git Bash so Claude Code can execute `~/.softspark/ai-toolkit/hooks/*.sh`.

Cross-platform hooks should keep the Bash entrypoint small and delegate complex work to Python or Node when Windows behavior diverges.

## Managed Mutation Safety

Managed cleanup by `ai-toolkit uninstall`, Copilot profile downgrade cleanup,
external hook injection/removal, and native Codex hook generation require POSIX
`dir_fd` and `O_NOFOLLOW` support.
These primitives are the platform prerequisite for pinning directories between
a trusted configuration root and the file being changed, so a symlink swap
cannot redirect a mutation outside that root. Absolute trusted roots are opened
component by component from a stable filesystem-root descriptor; all target
parsing, mutation, and rollback then use the pinned descriptors.

- **WSL:** managed cleanup is supported.
- **Native Windows Python, including invocation from Git Bash:** managed cleanup
  is unavailable because Windows CPython does not expose the required POSIX
  traversal primitives. Git Bash provides a shell, but it does not add those
  primitives to Python.

On an unsupported runtime, help, dry-run modes where available, component
discovery, validation, cancellation, and other read-only operations remain
available. A requested mutation exits non-zero before its transaction starts
and reports `No files were changed`. Run the command from WSL to remove managed
customizations, inject or remove external hooks, and generate/update native
Codex hooks safely.

## Verification

```bash
ai-toolkit doctor
python3 scripts/check_deps.py
python3 scripts/validate.py
```

The Windows support contract is covered by `tests/test_windows_support.bats`.

---

## kb/troubleshooting/README.md

---
title: "Troubleshooting"
service: ai-toolkit
category: troubleshooting
tags: [troubleshooting, debugging]
last_updated: "2026-03-25"
---

# Troubleshooting

Problem resolution guides. Guides will be added here as they are created.

---