@softspark/ai-toolkit 1.0.0

package/kb/reference/ci-integration.md

@@ -0,0 +1,66 @@
+---
+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@v4
+      - 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@v4
+        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)

package/kb/reference/claude-ecosystem-benchmark-snapshot.md

@@ -0,0 +1,80 @@
+---
+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.
+

package/kb/reference/claude-ecosystem-expansion-foundations.md

@@ -0,0 +1,102 @@
+---
+title: "Claude Ecosystem Expansion Foundations"
+category: reference
+service: ai-toolkit
+tags: [benchmark, claude-code, ecosystem, hooks, plugins, architecture]
+version: "1.0.0"
+created: "2026-03-27"
+last_updated: "2026-04-01"
+description: "Reference summary of the ecosystem signals and implementation foundations adopted in ai-toolkit."
+---
+
+# 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-native, 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.
+
+Implemented artifacts:
+- `app/.claude-plugin/plugin.json`
+- `app/plugins/`
+- `app/skills/plugin-creator/SKILL.md`
+- `kb/reference/plugin-pack-conventions.md`
+
+### 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 |
+| 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.

package/kb/reference/commands-catalog.md

@@ -0,0 +1,21 @@
+---
+title: "AI Toolkit - Commands Catalog (DEPRECATED)"
+category: reference
+service: ai-toolkit
+tags: [commands, deprecated]
+version: "1.0.0"
+created: "2026-03-23"
+last_updated: "2026-03-28"
+description: "DEPRECATED: All slash commands are implemented as skills. See skills-catalog.md for the current catalog."
+---
+
+# Commands Catalog (DEPRECATED)
+
+All slash commands have been migrated to skills.
+
+See **[Skills Catalog](skills-catalog.md)** for the complete list of 85 skills, including:
+- **27 Task Skills** — formerly standalone commands and creator workflows (e.g., `/commit`, `/test`, `/deploy`, `/hook-creator`, `/plugin-creator`)
+- **27 Hybrid Skills** — slash commands that also provide agent knowledge (e.g., `/review`, `/debug`, `/plan`, `/tdd`, `/write-a-prd`)
+- **31 Knowledge Skills** — domain patterns auto-loaded by agents
+
+Slash command syntax (`/command`) continues to work. The underlying implementation moved from `app/commands/` to `app/skills/`.

package/kb/reference/distribution-model.md

@@ -0,0 +1,63 @@
+---
+title: "Distribution Model"
+category: reference
+service: ai-toolkit
+tags: [architecture, distribution, symlinks, npm, install]
+version: "1.0.0"
+created: "2026-03-23"
+last_updated: "2026-03-28"
+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`

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

@@ -0,0 +1,56 @@
+---
+title: "Global Install Model"
+category: reference
+service: ai-toolkit
+tags: [install, global, claude, local-setup]
+version: "1.0.0"
+created: "2026-03-26"
+last_updated: "2026-03-28"
+description: "Reference description of the global install target, local project setup, 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, and rules to every project without committing toolkit boilerplate into each repository.
+
+## 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 | create local `CLAUDE.md`, `.claude/settings.local.json`, and inject constitution + Copilot + Cline + Roo Code + Aider configs. Installs git hooks fallback. |
+| `ai-toolkit update --local` | current project | refresh those local project files |
+| `ai-toolkit add-rule` | `~/.ai-toolkit/rules/` | register a global rule |
+| `ai-toolkit remove-rule` | `~/.ai-toolkit/rules/` | unregister a global rule |
+
+## 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:
+- `CLAUDE.md`
+- `.claude/settings.local.json`
+- `.claude/constitution.md`
+- `.github/copilot-instructions.md`
+- `.clinerules`
+- `.roomodes`
+- `.aider.conf.yml`
+- `.git/hooks/pre-commit` (fallback)
+- project-specific documentation or safety overlays
+
+Hooks do **not** live in project-local settings. They are merged only into global `~/.claude/settings.json`.
+
+## Related Documents
+
+- `kb/reference/distribution-model.md`
+- `kb/reference/merge-friendly-install-model.md`

package/kb/reference/hierarchical-override-pattern.md

@@ -0,0 +1,200 @@
+---
+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 |