feat(agent-comparison): add autoresearch optimization review flow

agents/INDEX.json

@@ -115,23 +115,6 @@
       "complexity": "Medium",
       "category": "meta"
     },
-    "golang-general-engineer-compact": {
-      "file": "golang-general-engineer-compact.md",
-      "short_description": "Use this agent for focused Go development with tight context budgets",
-      "triggers": [
-        "go",
-        "golang",
-        "tight context",
-        "compact",
-        "focused go"
-      ],
-      "pairs_with": [
-        "go-pr-quality-gate",
-        "go-testing"
-      ],
-      "complexity": "Medium-Complex",
-      "category": "language"
-    },
     "golang-general-engineer": {
       "file": "golang-general-engineer.md",
       "short_description": "Use this agent when you need expert assistance with Go development, including implementing features,\ndebugging issues, reviewing code quality, optimizing performance, or answering technical questions\nabout Go codebases",
@@ -151,6 +134,23 @@
       "complexity": "Medium-Complex",
       "category": "language"
     },
+    "golang-general-engineer-compact": {
+      "file": "golang-general-engineer-compact.md",
+      "short_description": "Use this agent for focused Go development with tight context budgets",
+      "triggers": [
+        "go",
+        "golang",
+        "tight context",
+        "compact",
+        "focused go"
+      ],
+      "pairs_with": [
+        "go-pr-quality-gate",
+        "go-testing"
+      ],
+      "complexity": "Medium-Complex",
+      "category": "language"
+    },
     "hook-development-engineer": {
       "file": "hook-development-engineer.md",
       "short_description": "Use this agent when developing Python hooks for Claude Code's event-driven system",
@@ -171,6 +171,34 @@
       "complexity": "Comprehensive",
       "category": "meta"
     },
+    "kotlin-general-engineer": {
+      "file": "kotlin-general-engineer.md",
+      "short_description": "Use this agent when you need expert assistance with Kotlin development, including implementing features, debugging issues, reviewing code quality, optimizing coroutine usage, or answering technical questions about Kotlin codebases",
+      "triggers": [
+        "kotlin",
+        "ktor",
+        "koin",
+        "coroutine",
+        "suspend fun",
+        "kotlin flow",
+        "StateFlow",
+        "kotest",
+        "mockk",
+        "gradle-kts",
+        "detekt",
+        "ktlint",
+        "ktfmt",
+        "android kotlin",
+        "kotlin-multiplatform"
+      ],
+      "pairs_with": [
+        "systematic-debugging",
+        "verification-before-completion",
+        "systematic-code-review"
+      ],
+      "complexity": "Medium-Complex",
+      "category": "language"
+    },
     "kubernetes-helm-engineer": {
       "file": "kubernetes-helm-engineer.md",
       "short_description": "Use this agent for Kubernetes and Helm deployment management, troubleshooting, and cloud-native infrastructure",
@@ -354,6 +382,38 @@
       "complexity": "Medium-Complex",
       "category": "development"
     },
+    "php-general-engineer": {
+      "file": "php-general-engineer.md",
+      "short_description": "Use this agent when you need expert assistance with PHP development, including implementing features, debugging issues, reviewing code quality, enforcing security posture, or answering technical questions about PHP codebases",
+      "triggers": [
+        "php",
+        "laravel",
+        "symfony",
+        "composer",
+        "artisan",
+        "eloquent",
+        "blade",
+        "twig",
+        "phpunit",
+        "pest",
+        "psr-12",
+        "psr standards",
+        "hybris",
+        "sapcc",
+        ".php files",
+        "doctrine",
+        "php-cs-fixer",
+        "phpstan",
+        "psalm"
+      ],
+      "pairs_with": [
+        "systematic-debugging",
+        "verification-before-completion",
+        "systematic-code-review"
+      ],
+      "complexity": "Medium-Complex",
+      "category": "language"
+    },
     "pipeline-orchestrator-engineer": {
       "file": "pipeline-orchestrator-engineer.md",
       "short_description": "Use this agent when building new pipelines that require coordinated creation\nof agents, skills, and hooks",
@@ -792,7 +852,7 @@
     },
     "reviewer-meta-process": {
       "file": "reviewer-meta-process.md",
-      "short_description": "Meta-analysis of system design decisions \u2014 examines whether the SYSTEM ITSELF is creating\nproblems",
+      "short_description": "Meta-analysis of system design decisions — examines whether the SYSTEM ITSELF is creating\nproblems",
       "triggers": [
         "meta-process review",
         "system design review",
@@ -907,7 +967,7 @@
         "hot paths",
         "N+1 queries",
         "allocations",
-        "O(n\u00b2)",
+        "O(n²)",
         "caching",
         "slow code",
         "performance optimization"
@@ -1083,6 +1143,41 @@
       "complexity": "Medium",
       "category": "language"
     },
+    "swift-general-engineer": {
+      "file": "swift-general-engineer.md",
+      "short_description": "Use this agent when you need expert assistance with Swift development, including implementing features for iOS, macOS, watchOS, tvOS, visionOS, or server-side Swift, debugging issues, reviewing code quality, or answering technical questions about Swift codebases",
+      "triggers": [
+        "swift",
+        "ios",
+        "macos",
+        "xcode",
+        "swiftui",
+        "uikit",
+        "appkit",
+        "watchos",
+        "tvos",
+        "visionos",
+        "vapor",
+        "spm",
+        "swift-package-manager",
+        "swiftlint",
+        "swiftformat",
+        "xctest",
+        "swift-testing",
+        "swift actor",
+        "swift sendable",
+        "swift-combine",
+        "swiftdata",
+        "coredata"
+      ],
+      "pairs_with": [
+        "systematic-debugging",
+        "verification-before-completion",
+        "systematic-code-review"
+      ],
+      "complexity": "Medium-Complex",
+      "category": "language"
+    },
     "system-upgrade-engineer": {
       "file": "system-upgrade-engineer.md",
       "short_description": "Use this agent for systematic upgrades to the agent/skill/hook ecosystem when\nClaude Code ships updates, user goals change, or retro learnings accumulate",
@@ -1236,4 +1331,4 @@
       "category": "language"
     }
   }
-}
+}

hooks/creation-protocol-enforcer.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+# hook-version: 1.0.0
+"""
+PreToolUse:Agent Hook: Creation Protocol Enforcer
+
+Soft-warns when an Agent dispatch appears to be for a creation request
+but no ADR has been written yet this session (i.e. .adr-session.json
+does not exist or was last modified more than 900 seconds ago).
+
+This is a SOFT WARN — exit 0 only (never blocks).
+
+Detection logic:
+- Tool is Agent
+- tool_input["prompt"] contains creation keywords
+- .adr-session.json in project root either does not exist or is stale (>900s)
+
+Allow-through conditions:
+- Tool is not Agent
+- No creation keywords found in prompt
+- .adr-session.json exists and was modified within the last 900 seconds
+- ADR_PROTOCOL_BYPASS=1 env var
+"""
+
+import json
+import os
+import sys
+import time
+import traceback
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent / "lib"))
+from stdin_timeout import read_stdin
+
+_BYPASS_ENV = "ADR_PROTOCOL_BYPASS"
+_ADR_SESSION_FILE = ".adr-session.json"
+_STALENESS_THRESHOLD_SECONDS = 900
+
+_CREATION_KEYWORDS = [
+    "create",
+    "scaffold",
+    "build a new",
+    "build a ",
+    "add a new",
+    "add new",
+    "new agent",
+    "new skill",
+    "new pipeline",
+    "new hook",
+    "new feature",
+    "new workflow",
+    "new plugin",
+    "implement new",
+    "i need a ",
+    "i need an ",
+    "we need a ",
+    "we need an ",
+]
+
+_WARNING_LINES = [
+    "[creation-protocol-enforcer] Creation request detected but no recent ADR session found.",
+    "/do Phase 4 Step 0 requires: (1) Write ADR at adr/{name}.md, (2) Register via adr-query.py register, THEN dispatch agent.",
+    "If ADR was already written, set ADR_PROTOCOL_BYPASS=1 to suppress this warning.",
+]
+
+
+def _has_creation_keywords(prompt: str) -> bool:
+    """Return True if the prompt contains any creation keyword (case-insensitive)."""
+    lower = prompt.lower()
+    return any(kw in lower for kw in _CREATION_KEYWORDS)
+
+
+def _adr_session_is_recent(base_dir: Path) -> bool:
+    """Return True if .adr-session.json exists and was modified within the threshold."""
+    adr_session_path = base_dir / _ADR_SESSION_FILE
+    if not adr_session_path.exists():
+        return False
+    try:
+        mtime = os.path.getmtime(adr_session_path)
+        age = time.time() - mtime
+        return age <= _STALENESS_THRESHOLD_SECONDS
+    except OSError:
+        return False
+
+
+def main() -> None:
+    """Run the creation protocol enforcement check."""
+    debug = os.environ.get("CLAUDE_HOOKS_DEBUG")
+
+    raw = read_stdin(timeout=2)
+    try:
+        event = json.loads(raw)
+    except (json.JSONDecodeError, ValueError):
+        sys.exit(0)
+
+    # Filter: only act on Agent tool dispatches.
+    tool_name = event.get("tool_name", "")
+    if tool_name != "Agent":
+        sys.exit(0)
+
+    # Bypass env var.
+    if os.environ.get(_BYPASS_ENV) == "1":
+        if debug:
+            print(
+                f"[creation-protocol-enforcer] Bypassed via {_BYPASS_ENV}=1",
+                file=sys.stderr,
+            )
+        sys.exit(0)
+
+    tool_input = event.get("tool_input", {})
+    prompt = tool_input.get("prompt", "")
+    if not prompt:
+        sys.exit(0)
+
+    # Check for creation keywords.
+    if not _has_creation_keywords(prompt):
+        if debug:
+            print(
+                "[creation-protocol-enforcer] No creation keywords found — allowing through",
+                file=sys.stderr,
+            )
+        sys.exit(0)
+
+    # Resolve project root.
+    cwd_str = event.get("cwd") or os.environ.get("CLAUDE_PROJECT_DIR", ".")
+    base_dir = Path(cwd_str).resolve()
+
+    # Check whether a recent ADR session exists.
+    if _adr_session_is_recent(base_dir):
+        if debug:
+            print(
+                "[creation-protocol-enforcer] Recent .adr-session.json found — allowing through",
+                file=sys.stderr,
+            )
+        sys.exit(0)
+
+    # No recent ADR session — emit soft warning to stdout (context injection).
+    print("\n".join(_WARNING_LINES))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except SystemExit:
+        raise
+    except Exception as e:
+        if os.environ.get("CLAUDE_HOOKS_DEBUG"):
+            traceback.print_exc(file=sys.stderr)
+        else:
+            print(
+                f"[creation-protocol-enforcer] Error: {type(e).__name__}: {e}",
+                file=sys.stderr,
+            )
+        # Fail open — never exit non-zero on unexpected errors.
+        sys.exit(0)