@softspark/ai-toolkit 2.11.0 → 3.0.0

package/benchmarks/ecosystem-doctor-snapshot.json

@@ -0,0 +1,395 @@
+{
+  "last_run": "2026-04-23T13:13:00Z",
+  "schema_version": 1,
+  "tools": {
+    "aider": {
+      "docs_hash": "3e8a0546effca7f1",
+      "headings": [
+        "Aider Documentation"
+      ],
+      "markers": {
+        ".aider.conf.yml": false,
+        "CONVENTIONS.md": false,
+        "architect": true,
+        "attribute-co-authored-by": false,
+        "auto-accept-architect": true,
+        "auto-commits": false,
+        "chat-language": false,
+        "commit-language": false,
+        "commit-prompt": false,
+        "lint-cmd": false,
+        "read": true,
+        "test-cmd": false,
+        "watch-files": false
+      }
+    },
+    "augment": {
+      "docs_hash": "91dbc84ba3b8652b",
+      "headings": [
+        "Agent",
+        "Code Completions",
+        "Introduction",
+        "Next Edit",
+        "\u200bAuggie CLI",
+        "\u200bGet started in minutes",
+        "\u200bJetBrains IDEs",
+        "\u200bLearn more",
+        "\u200bVisual Studio Code"
+      ],
+      "markers": {
+        ".augment": true,
+        "ACP Mode": true,
+        "Agent mode": false,
+        "Auggie CLI": true,
+        "MCP": true,
+        "Next Edit": true,
+        "PostToolUse": false,
+        "PreToolUse": false,
+        "SKILL.md": false,
+        "SessionEnd": false,
+        "SessionStart": false,
+        "Stop": false,
+        "agent_requested": false,
+        "always_apply": false,
+        "context engine": true,
+        "custom commands": true,
+        "subagents": true
+      }
+    },
+    "claude-code": {
+      "docs_hash": "a117026a47c684b9",
+      "headings": [
+        "Claude Code overview",
+        "\u200bGet started",
+        "\u200bNext steps",
+        "\u200bUse Claude Code everywhere",
+        "\u200bWhat you can do"
+      ],
+      "markers": {
+        "ConfigChange": false,
+        "CwdChanged": false,
+        "Elicitation": false,
+        "ElicitationResult": false,
+        "FileChanged": false,
+        "InstructionsLoaded": false,
+        "MCP server": true,
+        "Notification": true,
+        "PermissionDenied": false,
+        "PermissionRequest": false,
+        "PostCompact": false,
+        "PostToolUse": true,
+        "PreCompact": false,
+        "PreToolUse": true,
+        "SKILL.md": true,
+        "SessionEnd": false,
+        "SessionStart": false,
+        "Setup": true,
+        "Stop": false,
+        "StopFailure": false,
+        "SubagentStart": false,
+        "SubagentStop": false,
+        "TaskCompleted": false,
+        "TaskCreated": false,
+        "TeammateIdle": false,
+        "UserPromptSubmit": false,
+        "WorktreeCreate": false,
+        "WorktreeRemove": false,
+        "hook handler: agent": false,
+        "hook handler: command": false,
+        "hook handler: mcp_tool": false,
+        "hook handler: prompt": false,
+        "output style": true,
+        "slash command": true,
+        "sub-agent": true
+      },
+      "version": "2.1.118 (Claude Code)"
+    },
+    "cline": {
+      "docs_hash": "5ed2cada4d9b3fa6",
+      "headings": [
+        "Cline CLI",
+        "Cline Documentation",
+        "Core Workflows",
+        "Customization",
+        "Features",
+        "Install Cline",
+        "MCP Servers",
+        "Models & Providers",
+        "Quick Start",
+        "What is Cline?",
+        "Your First Project",
+        "\u200bExplore the Docs",
+        "\u200bWhat is Cline?"
+      ],
+      "markers": {
+        "Act Mode": true,
+        "MCP": true,
+        "Plan Mode": false,
+        "clinerules": false,
+        "conditional rules": false,
+        "custom modes": false,
+        "hooks": true,
+        "skills": true,
+        "subagents": true,
+        "workflows": true
+      }
+    },
+    "codex-cli": {
+      "docs_hash": "d66e6b65d5c69da4",
+      "headings": [
+        "About",
+        "Contributing",
+        "Contributors",
+        "Docs",
+        "Folders and files",
+        "Footer",
+        "Footer navigation",
+        "Forks",
+        "History",
+        "Installing and running Codex CLI",
+        "Languages",
+        "Latest commit",
+        "License",
+        "Navigation Menu",
+        "Packages 0",
+        "Provide feedback",
+        "Quickstart",
+        "Releases 732",
+        "Repository files navigation",
+        "Resources",
+        "Saved searches",
+        "Search code, repositories, users, issues, pull requests...",
+        "Security policy",
+        "Stars",
+        "Uh oh!",
+        "Use saved searches to filter your results more quickly",
+        "Using Codex with your ChatGPT plan",
+        "Watchers",
+        "openai/codex"
+      ],
+      "markers": {
+        ".codex/skills": true,
+        "AGENTS.md": true,
+        "config.toml": false,
+        "hook event: PermissionRequest": false,
+        "hook event: PostToolUse": false,
+        "hook event: PreToolUse": false,
+        "hook event: SessionStart": false,
+        "hook event: Stop": false,
+        "hook event: UserPromptSubmit": false,
+        "hook handler: agent": false,
+        "hook handler: command": false,
+        "hook handler: prompt": false,
+        "hooks": false,
+        "mcp_servers": false,
+        "sandbox": true
+      },
+      "version": "codex-cli 0.122.0"
+    },
+    "cursor": {
+      "docs_hash": "594d7b663fb8b3e1",
+      "headings": [],
+      "markers": {
+        ".cursor/rules": false,
+        "AGENTS.md": false,
+        "Agent Mode": false,
+        "Composer": true,
+        "cursorrules": false,
+        "hooks.json": false,
+        "mcp.json": false,
+        "plugins": true,
+        "skills": true,
+        "subagents": true
+      }
+    },
+    "gemini-cli": {
+      "docs_hash": "51d03cce48332772",
+      "headings": [
+        "Breadcrumbs",
+        "Directory actions",
+        "FilesExpand file tree",
+        "Folders and files",
+        "Footer",
+        "Footer navigation",
+        "History",
+        "Latest commit",
+        "More options",
+        "Navigation Menu",
+        "Provide feedback",
+        "Saved searches",
+        "Search code, repositories, users, issues, pull requests...",
+        "Use saved searches to filter your results more quickly",
+        "docs",
+        "parent directory"
+      ],
+      "markers": {
+        "AfterAgent": false,
+        "AfterTool": false,
+        "BeforeAgent": false,
+        "BeforeModel": false,
+        "BeforeTool": false,
+        "GEMINI.md": true,
+        "SKILL.md": false,
+        "SessionEnd": false,
+        "SessionStart": false,
+        "Stop": true,
+        "activate_skill": false,
+        "custom commands": false,
+        "gemini-extension.json": false,
+        "mcpServers": false,
+        "settings.json": false,
+        "tools": true
+      }
+    },
+    "github-copilot": {
+      "docs_hash": "377b588e529c7deb",
+      "headings": [
+        "About Copilot auto model selection",
+        "About Copilot integrations",
+        "About agent management",
+        "About agent skills",
+        "About agentic memory for GitHub Copilot",
+        "About billing for GitHub Copilot in organizations and enterprises",
+        "About billing for individual GitHub Copilot plans",
+        "About custom agents",
+        "Articles",
+        "Did you find what you needed?",
+        "GitHub Copilot",
+        "GitHub Copilot documentation",
+        "Help and support",
+        "Help us make these docs great!",
+        "Legal",
+        "Still need help?"
+      ],
+      "markers": {
+        "Copilot Chat": true,
+        "Copilot Workspace": false,
+        "Copilot cloud agent": true,
+        "MCP": true,
+        "applyTo": false,
+        "copilot-instructions.md": false,
+        "custom agents": true,
+        "instructions.md": false,
+        "prompt files": true
+      }
+    },
+    "google-antigravity": {
+      "docs_hash": "509c72e157ecb6f3",
+      "headings": [],
+      "markers": {
+        "AGENTS.md": false,
+        "Antigravity": false,
+        "GEMINI.md": false,
+        "MCP": false,
+        "agent manager": false,
+        "agent permissions": false,
+        "artifacts": false,
+        "rules": false,
+        "skills": false,
+        "workflows": false
+      }
+    },
+    "opencode": {
+      "docs_hash": "81d548872ef2d912",
+      "headings": [
+        "Add features",
+        "Ask questions",
+        "Configure",
+        "Customize",
+        "Initialize",
+        "Install",
+        "Intro",
+        "Make changes",
+        "On this page",
+        "Share",
+        "Undo changes",
+        "Usage"
+      ],
+      "markers": {
+        "AGENTS.md": true,
+        "MCP": true,
+        "agents": true,
+        "commands": true,
+        "opencode.json": false,
+        "permission.skill": false,
+        "plugin event: command.executed": false,
+        "plugin event: message.updated": false,
+        "plugin event: permission.asked": false,
+        "plugin event: session.compacted": false,
+        "plugin event: session.created": false,
+        "plugin event: session.deleted": false,
+        "plugin event: tool.execute.after": false,
+        "plugin event: tool.execute.before": false,
+        "plugins": true,
+        "primary mode": false,
+        "rules": true,
+        "skills (native .opencode/skills)": false,
+        "skills (via .claude/skills fallback)": false,
+        "subagent mode": false
+      }
+    },
+    "roo-code": {
+      "docs_hash": "960b2e1caf562b43",
+      "headings": [
+        "A mindset for success\u200b",
+        "Additional Resources\u200b",
+        "Getting Started\u200b",
+        "Roo Code Docs",
+        "Tutorial & Feature Videos\u200b",
+        "What can Roo Code do for you\u200b"
+      ],
+      "markers": {
+        "Code Actions": false,
+        "MCP": true,
+        "Orchestrator mode": false,
+        "custom modes": true,
+        "description": true,
+        "groups": false,
+        "roleDefinition": false,
+        "roomodes": false,
+        "whenToUse": false
+      }
+    },
+    "windsurf": {
+      "docs_hash": "99ecee90bc1efe60",
+      "headings": [
+        "Advanced",
+        "App Deploys",
+        "Cascade",
+        "Context Awareness",
+        "MCP",
+        "Memories",
+        "Recommended Plugins",
+        "Terminal",
+        "Usage",
+        "Welcome to Windsurf",
+        "Workflows",
+        "\u200b1. Select setup flow",
+        "\u200b2. Choose editor theme",
+        "\u200b3. Sign up / Log in",
+        "\u200b4. Let\u2019s Surf!",
+        "\u200bCustom App Icons (beta)",
+        "\u200bForgot to Import VS Code Configurations?",
+        "\u200bIncompatible Extensions",
+        "\u200bOnboarding",
+        "\u200bSet Up",
+        "\u200bThings to Try",
+        "\u200bUninstall Windsurf",
+        "\u200bUpdate Windsurf",
+        "\u200bWindsurf Next"
+      ],
+      "markers": {
+        "AGENTS.md": true,
+        "Cascade": true,
+        "MCP": true,
+        "always_on": false,
+        "glob": true,
+        "hooks": true,
+        "memories": true,
+        "model_decision": false,
+        "windsurfrules": false,
+        "workflows": true
+      }
+    }
+  }
+}

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

@@ -0,0 +1,160 @@
+---
+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 → opt-in `--codex-skills` flag emits full 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` (full mirror to `.codex/skills/<name>/SKILL.md` — gated by `--codex-skills` flag)
+- 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` must be opt-in; default OFF.
+
+### 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`