@softspark/ai-toolkit 2.1.0 → 2.1.1

package/llms-full.txt

@@ -27,7 +27,9 @@
 - [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)
 - [Distribution Model](kb/reference/distribution-model.md)
 - [Enterprise Config Inheritance Guide](kb/reference/enterprise-config-guide.md)
@@ -49,6 +51,7 @@
 - [Skills Unification Model](kb/reference/skills-unification.md)
 - [Usage Statistics](kb/reference/stats.md)
 - [Config Sync](kb/reference/sync.md)
+- [Unique Features & Differentiators](kb/reference/unique-features.md)
 - [Troubleshooting](kb/troubleshooting/README.md)
 
 ## Skills
@@ -5112,6 +5115,146 @@ The reference benchmark set is intentionally curated:
 
 ---
 
+## kb/reference/cli-reference.md
+
+---
+title: "CLI Reference"
+category: reference
+service: ai-toolkit
+tags: [cli, commands, reference, install, update, plugin, mcp]
+created: "2026-04-13"
+last_updated: "2026-04-13"
+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) |
+
+## Rule & Hook Injection
+
+| Command | Description |
+|---------|-------------|
+| `add-rule <rule.md> [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>` | Inject external hooks into settings.json (idempotent, `_source` tagged) |
+| `remove-hook <name>` | Remove injected hooks by source name |
+
+## MCP Management
+
+| Command | Description |
+|---------|-------------|
+| `mcp list` | List available MCP server templates (25 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 selected runtime(s) |
+| `plugin install --all [--editor claude\|codex\|all]` | Install all 11 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`) |
+
+## 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` with marker injection for Codex CLI |
+| `codex-rules` | Generate `.agents/rules/*.md` 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 `.agent/rules/` and `.agent/workflows/` |
+| `llms-txt` | Generate `llms.txt` and `llms-full.txt` |
+
+## Other Commands
+
+| Command | Description |
+|---------|-------------|
+| `stats` | Show skill usage statistics (`--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 |
+
+## 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
 
 ---
@@ -5253,6 +5396,40 @@ The Codex compatibility path is verified by:
 
 ---
 
+## 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 | 92 | 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 | MIT | MIT | MIT | MIT |
+
+For live benchmark data, see the [ecosystem benchmark snapshot](claude-ecosystem-benchmark-snapshot.md).
+
+---
+
 ## kb/reference/competitive-features-implementation.md
 
 ---
@@ -8863,6 +9040,224 @@ ai-toolkit sync --pull abc123def456   # Use gist ID from first push
 
 ---
 
+## 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-04-13"
+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 5-article constitution via `PreToolUse` hooks. The hook actually **blocks** execution of:
+- Mass deletion (`rm -rf`, `DROP TABLE`)
+- Blind overwrites of uncommitted work
+- Any action that could cause irreversible data loss
+
+## 2. Hooks as Executable Scripts
+
+Hook logic lives in `app/hooks/*.sh` — not inline JSON one-liners. Scripts are copied to `~/.softspark/ai-toolkit/hooks/` on install and referenced from `~/.claude/settings.json`. Easy to read, debug, and extend.
+
+**12 lifecycle events / 21 global hook entries:**
+
+| Event | Script | Action |
+|-------|--------|--------|
+| SessionStart | `session-start.sh` | MANDATORY rules reminder + session context + instincts |
+| SessionStart | `mcp-health.sh` | Check MCP server command availability (non-blocking warning) |
+| SessionStart | `session-context.sh` | Capture environment snapshot to `~/.softspark/ai-toolkit/sessions/current-context.json` |
+| 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 |
+| UserPromptSubmit | `user-prompt-submit.sh` | Prompt governance reminder |
+| UserPromptSubmit | `track-usage.sh` | Record skill invocations to local stats |
+| PostToolUse | `post-tool-use.sh` | Lightweight validation reminders after edits |
+| PostToolUse | `governance-capture.sh` | Log security-sensitive operations to JSONL |
+| Stop | `quality-check.sh` | Multi-language lint (ruff/tsc/phpstan/dart/go) |
+| Stop | `save-session.sh` | Persist session context for cross-session continuity |
+| 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 |
+| 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/troubleshooting/README.md
 
 ---

package/llms.txt

@@ -27,7 +27,9 @@
 - [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)
 - [Distribution Model](kb/reference/distribution-model.md)
 - [Enterprise Config Inheritance Guide](kb/reference/enterprise-config-guide.md)
@@ -49,4 +51,5 @@
 - [Skills Unification Model](kb/reference/skills-unification.md)
 - [Usage Statistics](kb/reference/stats.md)
 - [Config Sync](kb/reference/sync.md)
+- [Unique Features & Differentiators](kb/reference/unique-features.md)
 - [Troubleshooting](kb/troubleshooting/README.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "Professional-grade AI coding toolkit: 92 skills, 44 agents, multi-platform support (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, Augment, Google Antigravity, Codex CLI), machine-enforced safety constitution, persona presets, skill security auditor, expanded lifecycle hooks, 11 plugin packs, and benchmark tooling.",
   "keywords": [
     "claude",
@@ -46,7 +46,7 @@
     "evaluate": "python3 scripts/evaluate_skills.py",
     "benchmark:ecosystem": "python3 scripts/benchmark_ecosystem.py --offline",
     "benchmark:harvest": "python3 scripts/harvest_ecosystem.py --offline",
-    "generate:agents": "python3 scripts/generate_agents_md.py > AGENTS.md",
+    "generate:agents": "python3 scripts/generate_codex.py > AGENTS.md",
     "generate:cursor": "python3 scripts/generate_cursor_rules.py > .cursorrules",
     "generate:llms": "python3 scripts/generate_llms_txt.py > llms.txt && python3 scripts/generate_llms_txt.py --full > llms-full.txt",
     "generate:windsurf": "python3 scripts/generate_windsurf.py > .windsurfrules",

package/scripts/generate_agents_md.py

@@ -11,6 +11,7 @@ from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from _common import agents_dir, frontmatter_field
+from paths import RULES_DIR
 
 
 def main() -> None:
@@ -86,6 +87,18 @@ def main() -> None:
         print("---")
         print()
 
+    # Registered custom rules from ~/.softspark/ai-toolkit/rules/
+    if RULES_DIR.is_dir():
+        for rule_file in sorted(RULES_DIR.glob("*.md")):
+            rule_name = rule_file.stem
+            print(f"<!-- TOOLKIT:{rule_name} START -->")
+            print("<!-- Auto-injected by ai-toolkit. Re-run to update. -->")
+            print()
+            print(rule_file.read_text(encoding="utf-8").rstrip())
+            print()
+            print(f"<!-- TOOLKIT:{rule_name} END -->")
+            print()
+
 
 if __name__ == "__main__":
     main()

package/scripts/generate_antigravity.py

@@ -40,7 +40,8 @@ def generate(target_dir: Path, *,
 
 def main() -> None:
     target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
-    generate(target)
+    from paths import RULES_DIR
+    generate(target, rules_dir=RULES_DIR)
 
 
 if __name__ == "__main__":

package/scripts/generate_augment_rules.py

@@ -134,7 +134,8 @@ def generate(target_dir: Path, *,
 
 def main() -> None:
     target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
-    generate(target)
+    from paths import RULES_DIR
+    generate(target, rules_dir=RULES_DIR)
 
 
 if __name__ == "__main__":

package/scripts/generate_cline_rules.py

@@ -48,7 +48,8 @@ def generate(target_dir: Path, *,
 
 def main() -> None:
     target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
-    generate(target)
+    from paths import RULES_DIR
+    generate(target, rules_dir=RULES_DIR)
 
 
 if __name__ == "__main__":

package/scripts/generate_codex.py

@@ -22,6 +22,7 @@ from emission import (
     print_toolkit_start,
 )
 from frontmatter import frontmatter_field
+from paths import RULES_DIR
 
 
 def _emit_agents() -> str:
@@ -87,6 +88,18 @@ def main() -> None:
 
     print_toolkit_end()
 
+    # Registered custom rules from ~/.softspark/ai-toolkit/rules/
+    if RULES_DIR.is_dir():
+        for rule_file in sorted(RULES_DIR.glob("*.md")):
+            rule_name = rule_file.stem
+            print()
+            print(f"<!-- TOOLKIT:{rule_name} START -->")
+            print("<!-- Auto-injected by ai-toolkit. Re-run to update. -->")
+            print()
+            print(rule_file.read_text(encoding="utf-8").rstrip())
+            print()
+            print(f"<!-- TOOLKIT:{rule_name} END -->")
+
 
 if __name__ == "__main__":
     main()

package/scripts/generate_codex_rules.py

@@ -44,7 +44,8 @@ def generate(target_dir: Path, *,
 
 def main() -> None:
     target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
-    generate(target)
+    from paths import RULES_DIR
+    generate(target, rules_dir=RULES_DIR)
 
 
 if __name__ == "__main__":

package/scripts/generate_cursor_mdc.py

@@ -149,7 +149,8 @@ def generate(target_dir: Path, *,
 
 def main() -> None:
     target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
-    generate(target)
+    from paths import RULES_DIR
+    generate(target, rules_dir=RULES_DIR)
 
 
 if __name__ == "__main__":

package/scripts/generate_roo_rules.py

@@ -33,7 +33,8 @@ def generate(target_dir: Path, *,
 
 def main() -> None:
     target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
-    generate(target)
+    from paths import RULES_DIR
+    generate(target, rules_dir=RULES_DIR)
 
 
 if __name__ == "__main__":

package/scripts/generate_windsurf_rules.py

@@ -34,7 +34,8 @@ def generate(target_dir: Path, *,
 
 def main() -> None:
     target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
-    generate(target)
+    from paths import RULES_DIR
+    generate(target, rules_dir=RULES_DIR)
 
 
 if __name__ == "__main__":

package/scripts/generator_base.py

@@ -27,6 +27,9 @@ Usage::
 from __future__ import annotations
 
 import sys
+from pathlib import Path
+
+from paths import RULES_DIR
 
 from emission import (
     count_agents_and_skills,
@@ -138,3 +141,15 @@ def render_generator(config: dict) -> None:
     if config.get("use_markers", True):
         print()
         print_toolkit_end()
+
+    # Registered custom rules from ~/.softspark/ai-toolkit/rules/
+    if RULES_DIR.is_dir():
+        for rule_file in sorted(RULES_DIR.glob("*.md")):
+            rule_name = rule_file.stem
+            print()
+            print(f"<!-- TOOLKIT:{rule_name} START -->")
+            print("<!-- Auto-injected by ai-toolkit. Re-run to update. -->")
+            print()
+            print(rule_file.read_text(encoding="utf-8").rstrip())
+            print()
+            print(f"<!-- TOOLKIT:{rule_name} END -->")