@softspark/ai-toolkit 2.11.0 → 3.0.0

package/scripts/ecosystem_tools.json

@@ -0,0 +1,500 @@
+{
+  "schema_version": 1,
+  "description": "Authoritative registry of tools ai-toolkit integrates with. Consumed by scripts/ecosystem_doctor.py to detect upstream doc/version drift.",
+  "last_updated": "2026-04-23",
+  "tools": [
+    {
+      "id": "claude-code",
+      "display_name": "Claude Code",
+      "kind": "primary",
+      "urls": {
+        "docs": "https://platform.claude.com/docs/en/claude-code",
+        "release_notes": "https://github.com/anthropics/claude-code/releases",
+        "changelog": null
+      },
+      "config_paths": [
+        "~/.claude/settings.json",
+        ".claude/settings.local.json",
+        "CLAUDE.md",
+        ".claude/agents/*.md",
+        ".claude/skills/*/SKILL.md",
+        "~/.claude/themes/*.json"
+      ],
+      "our_generators": [],
+      "capability_markers": [
+        "PreToolUse",
+        "PostToolUse",
+        "SessionStart",
+        "SessionEnd",
+        "SubagentStart",
+        "SubagentStop",
+        "UserPromptSubmit",
+        "Notification",
+        "Stop",
+        "StopFailure",
+        "PreCompact",
+        "PostCompact",
+        "PermissionRequest",
+        "PermissionDenied",
+        "Elicitation",
+        "ElicitationResult",
+        "TaskCreated",
+        "TaskCompleted",
+        "TeammateIdle",
+        "WorktreeCreate",
+        "WorktreeRemove",
+        "CwdChanged",
+        "FileChanged",
+        "ConfigChange",
+        "Setup",
+        "InstructionsLoaded",
+        "slash command",
+        "MCP server",
+        "sub-agent",
+        "output style",
+        "SKILL.md",
+        "hook handler: command",
+        "hook handler: prompt",
+        "hook handler: agent",
+        "hook handler: mcp_tool"
+      ],
+      "version_probe": {
+        "kind": "command",
+        "command": "claude --version"
+      }
+    },
+    {
+      "id": "cursor",
+      "display_name": "Cursor",
+      "kind": "editor",
+      "urls": {
+        "docs": "https://cursor.com/docs",
+        "release_notes": "https://cursor.com/changelog",
+        "changelog": "https://cursor.com/changelog"
+      },
+      "config_paths": [
+        ".cursorrules",
+        ".cursor/rules/*.mdc",
+        ".cursor/rules/*.md",
+        "AGENTS.md",
+        ".cursor/mcp.json",
+        "~/.cursor/mcp.json",
+        ".cursor/skills/*/SKILL.md",
+        ".cursor/agents/*.md",
+        ".cursor/hooks.json",
+        "~/.cursor/hooks.json"
+      ],
+      "our_generators": [
+        "scripts/generate_cursor_rules.py",
+        "scripts/generate_cursor_mdc.py"
+      ],
+      "capability_markers": [
+        "cursorrules",
+        ".cursor/rules",
+        "AGENTS.md",
+        "mcp.json",
+        "Composer",
+        "Agent Mode",
+        "hooks.json",
+        "subagents",
+        "skills",
+        "plugins"
+      ],
+      "version_probe": null
+    },
+    {
+      "id": "windsurf",
+      "display_name": "Windsurf",
+      "kind": "editor",
+      "urls": {
+        "docs": "https://docs.windsurf.com",
+        "release_notes": "https://windsurf.com/changelog",
+        "changelog": "https://windsurf.com/changelog"
+      },
+      "config_paths": [
+        ".windsurfrules",
+        ".windsurf/rules/*.md",
+        ".windsurf/workflows/*.md",
+        "AGENTS.md",
+        "~/.codeium/windsurf/memories/global_rules.md",
+        "~/.codeium/windsurf/mcp_config.json",
+        "~/.codeium/windsurf/global_workflows/*.md"
+      ],
+      "our_generators": [
+        "scripts/generate_windsurf.py",
+        "scripts/generate_windsurf_rules.py"
+      ],
+      "capability_markers": [
+        "Cascade",
+        "windsurfrules",
+        "AGENTS.md",
+        "always_on",
+        "glob",
+        "model_decision",
+        "workflows",
+        "MCP",
+        "memories",
+        "hooks"
+      ],
+      "version_probe": null
+    },
+    {
+      "id": "github-copilot",
+      "display_name": "GitHub Copilot",
+      "kind": "editor",
+      "urls": {
+        "docs": "https://docs.github.com/en/copilot",
+        "release_notes": "https://github.blog/changelog/label/copilot/",
+        "changelog": null
+      },
+      "config_paths": [
+        ".github/copilot-instructions.md",
+        ".github/instructions/*.instructions.md",
+        ".github/prompts/*.prompt.md",
+        "AGENTS.md"
+      ],
+      "our_generators": [
+        "scripts/generate_copilot.py"
+      ],
+      "capability_markers": [
+        "copilot-instructions.md",
+        "Copilot Chat",
+        "Copilot Workspace",
+        "Copilot cloud agent",
+        "applyTo",
+        "custom agents",
+        "prompt files",
+        "instructions.md",
+        "MCP"
+      ],
+      "version_probe": null
+    },
+    {
+      "id": "gemini-cli",
+      "display_name": "Gemini CLI",
+      "kind": "editor",
+      "urls": {
+        "docs": "https://github.com/google-gemini/gemini-cli/tree/main/docs",
+        "release_notes": "https://github.com/google-gemini/gemini-cli/releases",
+        "changelog": null
+      },
+      "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",
+        ".gemini/extensions/gemini-extension.json"
+      ],
+      "our_generators": [
+        "scripts/generate_gemini.py"
+      ],
+      "capability_markers": [
+        "GEMINI.md",
+        "mcpServers",
+        "tools",
+        "settings.json",
+        "BeforeTool",
+        "AfterTool",
+        "BeforeAgent",
+        "AfterAgent",
+        "BeforeModel",
+        "SessionStart",
+        "SessionEnd",
+        "Stop",
+        "SKILL.md",
+        "activate_skill",
+        "custom commands",
+        "gemini-extension.json"
+      ],
+      "version_probe": {
+        "kind": "command",
+        "command": "gemini --version"
+      }
+    },
+    {
+      "id": "cline",
+      "display_name": "Cline",
+      "kind": "editor",
+      "urls": {
+        "docs": "https://docs.cline.bot",
+        "release_notes": "https://github.com/cline/cline/releases",
+        "changelog": null
+      },
+      "config_paths": [
+        ".clinerules/*.md",
+        ".clinerules/workflows/*.md",
+        ".clinerules/hooks/",
+        ".cline/skills/",
+        "~/.cline/data/settings/cline_mcp_settings.json",
+        "~/Documents/Cline/Rules/"
+      ],
+      "our_generators": [
+        "scripts/generate_cline.py",
+        "scripts/generate_cline_rules.py"
+      ],
+      "capability_markers": [
+        "clinerules",
+        "Plan Mode",
+        "Act Mode",
+        "MCP",
+        "custom modes",
+        "workflows",
+        "hooks",
+        "skills",
+        "subagents",
+        "conditional rules"
+      ],
+      "version_probe": null
+    },
+    {
+      "id": "roo-code",
+      "display_name": "Roo Code",
+      "kind": "editor",
+      "urls": {
+        "docs": "https://docs.roocode.com",
+        "release_notes": "https://github.com/RooCodeInc/Roo-Code/releases",
+        "changelog": null
+      },
+      "config_paths": [
+        ".roomodes",
+        ".roo/rules/*.md",
+        ".roo/rules-{slug}/*.md",
+        ".roo/mcp.json",
+        "~/.roo/rules/",
+        "~/.roo/settings/custom_modes.yaml",
+        "~/.roo/settings/mcp_settings.json"
+      ],
+      "our_generators": [
+        "scripts/generate_roo_modes.py",
+        "scripts/generate_roo_rules.py"
+      ],
+      "capability_markers": [
+        "roomodes",
+        "custom modes",
+        "Code Actions",
+        "MCP",
+        "Orchestrator mode",
+        "whenToUse",
+        "description",
+        "roleDefinition",
+        "groups"
+      ],
+      "version_probe": null
+    },
+    {
+      "id": "aider",
+      "display_name": "Aider",
+      "kind": "editor",
+      "urls": {
+        "docs": "https://aider.chat/docs",
+        "release_notes": "https://aider.chat/HISTORY.html",
+        "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"
+      ],
+      "capability_markers": [
+        ".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"
+      ],
+      "version_probe": {
+        "kind": "command",
+        "command": "aider --version"
+      }
+    },
+    {
+      "id": "augment",
+      "display_name": "Augment",
+      "kind": "editor",
+      "urls": {
+        "docs": "https://docs.augmentcode.com",
+        "release_notes": "https://www.augmentcode.com/changelog",
+        "changelog": null
+      },
+      "config_paths": [
+        ".augment/rules/*.md",
+        ".augment/guidelines.md",
+        ".augment/agents/*.md",
+        ".augment/commands/*.md",
+        ".augment/skills/*/SKILL.md",
+        "~/.augment/rules/*.md",
+        "~/.augment/agents/*.md",
+        "~/.augment/commands/*.md",
+        "~/.augment/settings.json",
+        "/etc/augment/settings.json"
+      ],
+      "our_generators": [
+        "scripts/generate_augment.py",
+        "scripts/generate_augment_rules.py"
+      ],
+      "capability_markers": [
+        ".augment",
+        "Agent mode",
+        "Next Edit",
+        "MCP",
+        "context engine",
+        "Auggie CLI",
+        "always_apply",
+        "agent_requested",
+        "subagents",
+        "custom commands",
+        "SKILL.md",
+        "PreToolUse",
+        "PostToolUse",
+        "SessionStart",
+        "SessionEnd",
+        "Stop",
+        "ACP Mode"
+      ],
+      "version_probe": null
+    },
+    {
+      "id": "google-antigravity",
+      "display_name": "Google Antigravity",
+      "kind": "editor",
+      "urls": {
+        "docs": "https://antigravity.google/docs",
+        "release_notes": "https://antigravity.google/changelog",
+        "changelog": null
+      },
+      "config_paths": [
+        ".agent/rules/*.md",
+        ".agent/workflows/*.md",
+        ".agent/skills/*/SKILL.md",
+        "AGENTS.md",
+        "GEMINI.md"
+      ],
+      "our_generators": [
+        "scripts/generate_antigravity.py"
+      ],
+      "capability_markers": [
+        "Antigravity",
+        "agent manager",
+        "artifacts",
+        "MCP",
+        "workflows",
+        "rules",
+        "skills",
+        "AGENTS.md",
+        "GEMINI.md",
+        "agent permissions"
+      ],
+      "version_probe": null
+    },
+    {
+      "id": "codex-cli",
+      "display_name": "Codex CLI",
+      "kind": "editor",
+      "urls": {
+        "docs": "https://github.com/openai/codex",
+        "release_notes": "https://github.com/openai/codex/releases",
+        "changelog": null
+      },
+      "config_paths": [
+        "AGENTS.md",
+        ".agents/rules/*.md",
+        ".codex/hooks.json",
+        ".codex/skills/*/SKILL.md",
+        "~/.codex/config.toml"
+      ],
+      "our_generators": [
+        "scripts/generate_codex.py",
+        "scripts/generate_codex_rules.py",
+        "scripts/generate_codex_hooks.py"
+      ],
+      "capability_markers": [
+        "AGENTS.md",
+        "config.toml",
+        "mcp_servers",
+        "hooks",
+        "sandbox",
+        "hook event: PreToolUse",
+        "hook event: PostToolUse",
+        "hook event: SessionStart",
+        "hook event: UserPromptSubmit",
+        "hook event: Stop",
+        "hook event: PermissionRequest",
+        "hook handler: command",
+        "hook handler: prompt",
+        "hook handler: agent",
+        ".codex/skills"
+      ],
+      "version_probe": {
+        "kind": "command",
+        "command": "codex --version"
+      }
+    },
+    {
+      "id": "opencode",
+      "display_name": "opencode",
+      "kind": "editor",
+      "urls": {
+        "docs": "https://opencode.ai/docs",
+        "release_notes": "https://github.com/sst/opencode/releases",
+        "changelog": null
+      },
+      "config_paths": [
+        "opencode.json",
+        ".opencode/agents/*.md",
+        ".opencode/commands/*.md",
+        ".opencode/plugins/*",
+        ".opencode/skills/*/SKILL.md",
+        "AGENTS.md",
+        ".claude/skills/*/SKILL.md"
+      ],
+      "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"
+      ],
+      "capability_markers": [
+        "opencode.json",
+        "agents",
+        "commands",
+        "plugins",
+        "MCP",
+        "rules",
+        "AGENTS.md",
+        "skills (native .opencode/skills)",
+        "skills (via .claude/skills fallback)",
+        "permission.skill",
+        "subagent mode",
+        "primary mode",
+        "plugin event: session.created",
+        "plugin event: session.compacted",
+        "plugin event: session.deleted",
+        "plugin event: tool.execute.before",
+        "plugin event: tool.execute.after",
+        "plugin event: permission.asked",
+        "plugin event: command.executed",
+        "plugin event: message.updated"
+      ],
+      "version_probe": {
+        "kind": "command",
+        "command": "opencode --version"
+      }
+    }
+  ]
+}

package/scripts/evaluate_skills.py

@@ -212,6 +212,80 @@ def _collect_quality_metrics() -> tuple[int, int, int, int, int, int]:
     return ref_count, tmpl_count, inject_count, over500, depends_count, orphan_deps
 
 
+def _meta_architect_audit() -> tuple[dict[int, int], list[tuple[str, int, list[str]]]]:
+    """Score each skill against the 5 meta-architect binary criteria.
+
+    Criteria (all binary yes=pass):
+        description : frontmatter description is >= 50 chars and not generic
+        example     : SKILL.md contains at least one fenced code block or an
+                      '## Example' heading
+        constraint  : SKILL.md uses at least one of MUST / NEVER / CRITICAL /
+                      MANDATORY / REQUIRED / DO NOT as an uppercase marker
+        edge_case   : SKILL.md mentions edge cases, failure modes, fallbacks,
+                      or when NOT to use the skill
+        length      : SKILL.md is under 500 lines
+
+    Returns:
+        (score_distribution, weak_skills) where
+          score_distribution maps score -> count of skills,
+          weak_skills is a list of (name, score, failed_criteria) for score <= 3.
+    """
+    score_dist: dict[int, int] = {0: 0, 1: 0, 2: 0, 3: 0, 4: 0, 5: 0}
+    weak: list[tuple[str, int, list[str]]] = []
+
+    desc_generic = {"tbd", "todo", "fixme", "placeholder"}
+    constraint_re = re.compile(r"\b(MUST|NEVER|CRITICAL|MANDATORY|REQUIRED|DO NOT)\b")
+    edge_re = re.compile(
+        r"(?i)\b(edge case|edge-case|corner case|failure mode|when not to|"
+        r"do not use for|fallback|error handling|limitations?)\b"
+    )
+    example_heading_re = re.compile(
+        r"(?im)^##+\s*(example|examples|usage|worked example)"
+    )
+
+    for sf in sorted(skills_dir.glob("*/SKILL.md")):
+        text = sf.read_text(encoding="utf-8")
+        fm = frontmatter_block(sf)
+        desc = _fm_value(fm, "description")
+        line_count = text.count("\n") + (1 if text and not text.endswith("\n") else 0)
+
+        passed: list[str] = []
+        failed: list[str] = []
+
+        if len(desc) >= 50 and not any(g in desc.lower() for g in desc_generic):
+            passed.append("description")
+        else:
+            failed.append("description")
+
+        if re.search(r"^```", text, re.M) or example_heading_re.search(text):
+            passed.append("example")
+        else:
+            failed.append("example")
+
+        if constraint_re.search(text):
+            passed.append("constraint")
+        else:
+            failed.append("constraint")
+
+        if edge_re.search(text):
+            passed.append("edge_case")
+        else:
+            failed.append("edge_case")
+
+        if line_count < 500:
+            passed.append("length")
+        else:
+            failed.append("length")
+
+        score = len(passed)
+        score_dist[score] = score_dist.get(score, 0) + 1
+        if score <= 3:
+            weak.append((sf.parent.name, score, failed))
+
+    weak.sort(key=lambda r: (r[1], r[0]))
+    return score_dist, weak
+
+
 def main() -> None:
     """Run evaluation across all skills and print report."""
     print("AI Toolkit Skill Evaluation")
@@ -249,6 +323,16 @@ def main() -> None:
     print(f"  Orphan dependencies:    {orphan_deps}")
     print()
 
+    score_dist, weak = _meta_architect_audit()
+    print("Meta-Architect Audit (advisory, non-failing):")
+    print(f"  Score distribution (of 5): {dict(sorted(score_dist.items()))}")
+    print(f"  Skills scoring <= 3:       {len(weak)}")
+    if weak:
+        print("  Bottom 10 (score, name, failed criteria):")
+        for name, score, failed in weak[:10]:
+            print(f"    {score}/5  {name:<28} {','.join(failed)}")
+    print()
+
     if fail_count > 0:
         print("EVALUATION: ISSUES FOUND")
         sys.exit(1)

package/scripts/generate_aider_conf.py

@@ -17,9 +17,13 @@ def main() -> None:
     default_model = DEFAULT_CLAUDE_MODELS["sonnet"]
     print("# Aider configuration generated by ai-toolkit")
     print("# Regenerate using: ai-toolkit install --local")
+    print("# Aider docs: https://aider.chat/docs/config/aider_conf.html")
     print()
     print("# Use the architect mode for complex tasks, aligned with our 2-phase workflow")
     print("architect: true")
+    print("# Auto-accept architect proposals (default: true in aider >=0.82). Set to false")
+    print("# if you want to approve every architect-mode edit manually.")
+    print("auto-accept-architect: true")
     print()
     print("# Read project rules (loaded as read-only context)")
     print("read:")
@@ -36,16 +40,37 @@ def main() -> None:
     print('  - "php: ./vendor/bin/phpstan analyse"')
     print('  - "go: go vet"')
     print()
+    print("# Test commands (uncomment and customize per project). aider >=0.80 supports a")
+    print("# single `test-cmd`; run with `--test` or enable `auto-test: true` to run after edits.")
+    print("# test-cmd: pytest -q")
+    print("# auto-test: false")
+    print()
     print("# Model configuration")
     print(f"model: {default_model}")
     print(f"editor-model: {default_model}")
     print()
     print("# Auto-commit message formatting (matches our conventional commits)")
     print(
-        'commit_prompt: "Write a short, concise commit message following'
+        'commit-prompt: "Write a short, concise commit message following'
         ' Conventional Commits (feat/fix/chore/docs/test/refactor)."'
     )
     print()
+    print("# Git attribution (ai-toolkit policy: no AI co-authorship in commits).")
+    print("# Do not flip this to true -- conflicts with the toolkit git-workflow rule")
+    print("# (see app/rules/common/git-workflow.md).")
+    print("attribute-co-authored-by: false")
+    print("attribute-commit-message-author: false")
+    print("attribute-commit-message-committer: false")
+    print()
+    print("# Language settings (aider >=0.83 `commit-language`, >=0.85 confirmed stable).")
+    print("# Leave unset to inherit the user's system locale. Uncomment to pin.")
+    print("# chat-language: en")
+    print("# commit-language: en")
+    print()
+    print("# Watch-files mode scans for `# AI!` / `# ai?` comments (aider >=0.75). Opt-in")
+    print("# because it changes how aider reads your editor buffers.")
+    print("# watch-files: false")
+    print()
     print("# Disable auto-commits if you prefer using the /commit slash skill explicitly")
     print("# auto-commits: false")
     print()