prompt-capability-optimizer 1.0.0

package/adapters/host_capabilities.json

@@ -0,0 +1,135 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "HostCapabilitiesSchema",
+  "description": "Cross-agent host runtime capability specification and detection schema for prompt-capability-optimizer.",
+  "author": "Mahmoud Abdelhameid <Develper.net@gmail.com>",
+  "linkedin": "https://www.linkedin.com/in/mahmoud-abdelhameid-dev/",
+  "copyright": "Copyright (c) 2026 Mahmoud Abdelhameid. All rights reserved.",
+  "type": "object",
+  "properties": {
+    "agent_identity": {
+      "type": "string",
+      "enum": ["claude_code", "gemini_cli", "cursor", "windsurf", "cline", "roo_code", "codex", "opencode", "generic_agent", "unknown"]
+    },
+    "runtime_environment": {
+      "type": "object",
+      "properties": {
+        "os": { "type": "string", "enum": ["windows", "linux", "darwin"] },
+        "shell_type": { "type": "string", "enum": ["powershell", "pwsh", "bash", "zsh", "cmd", "none"] },
+        "working_directory": { "type": "string" }
+      },
+      "required": ["os", "shell_type", "working_directory"]
+    },
+    "capabilities": {
+      "type": "object",
+      "properties": {
+        "supports_filesystem": {
+          "type": "object",
+          "properties": {
+            "available": { "type": "boolean" },
+            "methods": { "type": "array", "items": { "type": "string", "enum": ["native_tool", "shell_commands", "read_only", "full_access"] } }
+          },
+          "required": ["available"]
+        },
+        "supports_shell": {
+          "type": "object",
+          "properties": {
+            "available": { "type": "boolean" },
+            "supports_async": { "type": "boolean" },
+            "supports_daemon": { "type": "boolean" },
+            "interactive_input": { "type": "boolean" }
+          },
+          "required": ["available"]
+        },
+        "supports_git": {
+          "type": "object",
+          "properties": {
+            "available": { "type": "boolean" },
+            "in_git_repo": { "type": "boolean" },
+            "branch_isolation": { "type": "boolean" }
+          },
+          "required": ["available"]
+        },
+        "supports_web_search": {
+          "type": "object",
+          "properties": {
+            "available": { "type": "boolean" },
+            "provider": { "type": "string" }
+          },
+          "required": ["available"]
+        },
+        "supports_web_fetch": {
+          "type": "object",
+          "properties": {
+            "available": { "type": "boolean" },
+            "javascript_execution": { "type": "boolean" }
+          },
+          "required": ["available"]
+        },
+        "supports_browser": {
+          "type": "object",
+          "properties": {
+            "available": { "type": "boolean" },
+            "headless": { "type": "boolean" },
+            "devtools_protocol": { "type": "boolean" }
+          },
+          "required": ["available"]
+        },
+        "supports_mcp": {
+          "type": "object",
+          "properties": {
+            "available": { "type": "boolean" },
+            "active_servers": { "type": "array", "items": { "type": "string" } },
+            "lazy_loading_supported": { "type": "boolean" }
+          },
+          "required": ["available"]
+        },
+        "supports_connectors": {
+          "type": "object",
+          "properties": {
+            "available": { "type": "boolean" },
+            "active_connectors": { "type": "array", "items": { "type": "string" } }
+          },
+          "required": ["available"]
+        },
+        "supports_skills": {
+          "type": "object",
+          "properties": {
+            "available": { "type": "boolean" },
+            "local_skill_roots": { "type": "array", "items": { "type": "string" } },
+            "registry_cli_available": { "type": "boolean" }
+          },
+          "required": ["available"]
+        },
+        "supports_subagents": {
+          "type": "object",
+          "properties": {
+            "available": { "type": "boolean" },
+            "supports_parallel": { "type": "boolean" },
+            "isolated_workspace": { "type": "boolean" }
+          },
+          "required": ["available"]
+        },
+        "supports_code_execution": {
+          "type": "object",
+          "properties": {
+            "available": { "type": "boolean" },
+            "languages": { "type": "array", "items": { "type": "string" } },
+            "sandboxed": { "type": "boolean" }
+          },
+          "required": ["available"]
+        }
+      },
+      "required": [
+        "supports_filesystem",
+        "supports_shell",
+        "supports_git",
+        "supports_web_search",
+        "supports_web_fetch",
+        "supports_mcp",
+        "supports_skills"
+      ]
+    }
+  },
+  "required": ["agent_identity", "runtime_environment", "capabilities"]
+}

package/bin/cli.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/**
+ * CLI Runner for prompt-capability-optimizer
+ * Author: Mahmoud Abdelhameid <Develper.net@gmail.com>
+ * LinkedIn: https://www.linkedin.com/in/mahmoud-abdelhameid-dev/
+ */
+
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const args = process.argv.slice(2);
+
+// Check if python is available
+const pyCmd = process.platform === 'win32' ? 'python' : 'python3';
+const checkPy = spawnSync(pyCmd, ['--version'], { encoding: 'utf-8' });
+
+if (checkPy.error || checkPy.status !== 0) {
+  console.log(`=== Prompt Capability Optimizer ===`);
+  console.log(`Author: Mahmoud Abdelhameid (https://www.linkedin.com/in/mahmoud-abdelhameid-dev/)`);
+  console.log(`Skill Location: ${path.join(PACKAGE_ROOT, 'SKILL.md')}`);
+  console.log(`Notice: Python runtime is required for the full optimizer engine CLI.`);
+  console.log(`To use this skill with Claude/Cursor/Gemini, point your agent to: ${PACKAGE_ROOT}`);
+  process.exit(0);
+}
+
+// Transparently run python engine
+const proc = spawnSync(pyCmd, ['-m', 'prompt_capability_optimizer', ...args], {
+  cwd: PACKAGE_ROOT,
+  stdio: 'inherit'
+});
+
+process.exit(proc.status || 0);

package/index.js

@@ -0,0 +1,54 @@
+/**
+ * Prompt Capability Optimizer
+ * ===========================
+ * Production-grade agent meta-skill for autonomous capability discovery & prompt engineering.
+ * 
+ * Author: Mahmoud Abdelhameid <Develper.net@gmail.com>
+ * LinkedIn: https://www.linkedin.com/in/mahmoud-abdelhameid-dev/
+ * License: MIT
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { spawnSync } = require('child_process');
+
+const PACKAGE_ROOT = __dirname;
+const SKILL_MD_PATH = path.join(PACKAGE_ROOT, 'SKILL.md');
+
+function getSkillPath() {
+  return SKILL_MD_PATH;
+}
+
+function getSkillContent() {
+  return fs.readFileSync(SKILL_MD_PATH, 'utf-8');
+}
+
+function getPackageMetadata() {
+  const pkg = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf-8'));
+  return {
+    name: pkg.name,
+    version: pkg.version,
+    author: pkg.author,
+    description: pkg.description,
+    repository: pkg.repository.url
+  };
+}
+
+function runOptimizer(args = []) {
+  // Attempt python execution
+  const pyCmd = process.platform === 'win32' ? 'python' : 'python3';
+  const res = spawnSync(pyCmd, ['-m', 'prompt_capability_optimizer', ...args], {
+    cwd: PACKAGE_ROOT,
+    stdio: 'inherit'
+  });
+  return res.status;
+}
+
+module.exports = {
+  PACKAGE_ROOT,
+  SKILL_MD_PATH,
+  getSkillPath,
+  getSkillContent,
+  getPackageMetadata,
+  runOptimizer
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "prompt-capability-optimizer",
+  "version": "1.0.0",
+  "description": "Production-grade, cross-platform agent meta-skill for autonomous capability discovery & two-pass prompt optimization.",
+  "main": "index.js",
+  "bin": {
+    "prompt-capability-optimizer": "bin/cli.js"
+  },
+  "scripts": {
+    "test": "python -m unittest discover -s tests -p \"test_*.py\" -v",
+    "start": "node ./bin/cli.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mahmoud-abdulhamid/prompt-capability-optimizer.git"
+  },
+  "keywords": [
+    "agent-skill",
+    "skills",
+    "mcp",
+    "prompt-engineering",
+    "prompt-optimization",
+    "capability-discovery",
+    "ai-agent",
+    "claude",
+    "gemini",
+    "cursor",
+    "windsurf"
+  ],
+  "author": "Mahmoud Abdelhameid <Develper.net@gmail.com> (https://www.linkedin.com/in/mahmoud-abdelhameid-dev/)",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/Mahmoud-abdulhamid/prompt-capability-optimizer/issues"
+  },
+  "homepage": "https://github.com/Mahmoud-abdulhamid/prompt-capability-optimizer#readme",
+  "files": [
+    "SKILL.md",
+    "index.js",
+    "bin/",
+    "prompt_capability_optimizer/",
+    "references/",
+    "templates/",
+    "adapters/",
+    "scripts/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}

package/prompt_capability_optimizer/__init__.py

@@ -0,0 +1,35 @@
+"""
+Prompt Capability Optimizer
+===========================
+Autonomous, cross-agent prompt optimization and capability discovery framework.
+"""
+
+from .models import (
+    Capability,
+    Resource,
+    ResourceType,
+    PromptIR,
+    CritiqueReport,
+    ClassificationReport
+)
+from .config import OptimizerConfig, DEFAULT_CONFIG
+from .engine import PromptOptimizerEngine
+
+__version__ = "1.0.0"
+__author__ = "Mahmoud Abdelhameid"
+__email__ = "Develper.net@gmail.com"
+__linkedin__ = "https://www.linkedin.com/in/mahmoud-abdelhameid-dev/"
+__copyright__ = "Copyright (c) 2026 Mahmoud Abdelhameid. All rights reserved."
+__license__ = "MIT"
+
+__all__ = [
+    "PromptOptimizerEngine",
+    "OptimizerConfig",
+    "DEFAULT_CONFIG",
+    "Capability",
+    "Resource",
+    "ResourceType",
+    "PromptIR",
+    "CritiqueReport",
+    "ClassificationReport"
+]

package/prompt_capability_optimizer/__main__.py

@@ -0,0 +1,7 @@
+# Copyright (c) 2026 Mahmoud Abdelhameid (Develper.net@gmail.com). All rights reserved.
+# Licensed under the MIT License.
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

package/prompt_capability_optimizer/adapters/__init__.py

@@ -0,0 +1,21 @@
+# Copyright (c) 2026 Mahmoud Abdelhameid (Develper.net@gmail.com). All rights reserved.
+# Licensed under the MIT License.
+
+from .host_adapter import HostAdapter, detect_host_runtime
+from .agent_adapters import (
+    ClaudeCodeAdapter,
+    GeminiCliAdapter,
+    CursorAdapter,
+    ClineAdapter,
+    get_agent_adapter
+)
+
+__all__ = [
+    "HostAdapter",
+    "detect_host_runtime",
+    "ClaudeCodeAdapter",
+    "GeminiCliAdapter",
+    "CursorAdapter",
+    "ClineAdapter",
+    "get_agent_adapter"
+]

package/prompt_capability_optimizer/adapters/agent_adapters.py

@@ -0,0 +1,281 @@
+# Copyright (c) 2026 Mahmoud Abdelhameid (Develper.net@gmail.com). All rights reserved.
+# Licensed under the MIT License.
+
+"""
+Agent Ecosystem Adapters & Compatibility Verification
+=====================================================
+Concrete host implementations for Claude Code, Codex, Gemini CLI, OpenCode,
+Cursor, Windsurf, Cline, and Roo Code.
+Guarantees that unknown agents are NEVER silently mapped to Gemini or any other agent.
+"""
+
+import os
+from pathlib import Path
+from typing import List, Optional
+from ..models import HostCapabilityItem, CapabilityStatus
+from .host_adapter import HostAdapter
+
+class GeminiCliAdapter(HostAdapter):
+    def get_agent_name(self) -> str:
+        return "gemini_cli"
+        
+    def get_skill_paths(self) -> List[Path]:
+        home = Path.home()
+        cwd = Path.cwd()
+        return [
+            cwd / ".gemini" / "skills",
+            home / ".gemini" / "config" / "skills",
+            home / ".gemini" / "antigravity" / "builtin" / "skills"
+        ]
+        
+    def supports_mcp(self) -> HostCapabilityItem:
+        return HostCapabilityItem(
+            capability="mcp",
+            status=CapabilityStatus.RUNTIME_DETECTED,
+            confidence=0.98,
+            details={"protocol": "Model Context Protocol JSON-RPC", "validated": True}
+        )
+        
+    def supports_web(self) -> HostCapabilityItem:
+        return HostCapabilityItem(
+            capability="web",
+            status=CapabilityStatus.RUNTIME_DETECTED,
+            confidence=0.95,
+            details={"provider": "search_web / read_url_content", "validated": True}
+        )
+
+class ClaudeCodeAdapter(HostAdapter):
+    def get_agent_name(self) -> str:
+        return "claude_code"
+        
+    def get_skill_paths(self) -> List[Path]:
+        home = Path.home()
+        cwd = Path.cwd()
+        return [
+            cwd / ".claude" / "skills",
+            home / ".claude" / "skills"
+        ]
+        
+    def supports_mcp(self) -> HostCapabilityItem:
+        home = Path.home()
+        has_cfg = (home / ".claude" / "mcp.json").exists()
+        return HostCapabilityItem(
+            capability="mcp",
+            status=CapabilityStatus.RUNTIME_DETECTED if has_cfg else CapabilityStatus.HOST_DECLARED,
+            confidence=0.90,
+            details={"config_file": str(home / ".claude" / "mcp.json"), "validated": True}
+        )
+        
+    def supports_web(self) -> HostCapabilityItem:
+        return HostCapabilityItem(
+            capability="web",
+            status=CapabilityStatus.HOST_DECLARED,
+            confidence=0.90,
+            details={"provider": "WebSearch / WebFetch", "validated": True}
+        )
+
+class CursorAdapter(HostAdapter):
+    def get_agent_name(self) -> str:
+        return "cursor"
+        
+    def get_skill_paths(self) -> List[Path]:
+        cwd = Path.cwd()
+        return [
+            cwd / ".cursor" / "skills",
+            cwd / ".cursor" / "rules"
+        ]
+        
+    def supports_mcp(self) -> HostCapabilityItem:
+        cwd = Path.cwd()
+        has_cfg = (cwd / ".cursor" / "mcp.json").exists()
+        return HostCapabilityItem(
+            capability="mcp",
+            status=CapabilityStatus.RUNTIME_DETECTED if has_cfg else CapabilityStatus.UNKNOWN,
+            confidence=0.75,
+            details={"config_file": str(cwd / ".cursor" / "mcp.json"), "validated": "Partial"}
+        )
+        
+    def supports_web(self) -> HostCapabilityItem:
+        return HostCapabilityItem(
+            capability="web",
+            status=CapabilityStatus.HOST_DECLARED,
+            confidence=0.80,
+            details={"provider": "Integrated web query", "validated": "Partial"}
+        )
+
+class WindsurfAdapter(HostAdapter):
+    def get_agent_name(self) -> str:
+        return "windsurf"
+        
+    def get_skill_paths(self) -> List[Path]:
+        cwd = Path.cwd()
+        return [
+            cwd / ".windsurf" / "skills",
+            cwd / ".codeium" / "windsurf" / "memories"
+        ]
+        
+    def supports_mcp(self) -> HostCapabilityItem:
+        cwd = Path.cwd()
+        has_cfg = (cwd / ".windsurf" / "mcp.json").exists()
+        return HostCapabilityItem(
+            capability="mcp",
+            status=CapabilityStatus.RUNTIME_DETECTED if has_cfg else CapabilityStatus.HOST_DECLARED,
+            confidence=0.75,
+            details={"validated": "Partial"}
+        )
+        
+    def supports_web(self) -> HostCapabilityItem:
+        return HostCapabilityItem(
+            capability="web",
+            status=CapabilityStatus.HOST_DECLARED,
+            confidence=0.80,
+            details={"provider": "Integrated web search", "validated": "Partial"}
+        )
+
+class ClineAdapter(HostAdapter):
+    def get_agent_name(self) -> str:
+        return "cline"
+        
+    def get_skill_paths(self) -> List[Path]:
+        cwd = Path.cwd()
+        return [
+            cwd / ".cline" / "skills"
+        ]
+        
+    def supports_mcp(self) -> HostCapabilityItem:
+        return HostCapabilityItem(
+            capability="mcp",
+            status=CapabilityStatus.HOST_DECLARED,
+            confidence=0.85,
+            details={"provider": "Extension MCP manager", "validated": "Partial"}
+        )
+        
+    def supports_web(self) -> HostCapabilityItem:
+        return HostCapabilityItem(
+            capability="web",
+            status=CapabilityStatus.HOST_DECLARED,
+            confidence=0.85,
+            details={"provider": "Browser tool", "validated": "Partial"}
+        )
+
+class RooCodeAdapter(HostAdapter):
+    def get_agent_name(self) -> str:
+        return "roo_code"
+        
+    def get_skill_paths(self) -> List[Path]:
+        cwd = Path.cwd()
+        return [
+            cwd / ".roo" / "skills"
+        ]
+        
+    def supports_mcp(self) -> HostCapabilityItem:
+        return HostCapabilityItem(
+            capability="mcp",
+            status=CapabilityStatus.HOST_DECLARED,
+            confidence=0.85,
+            details={"provider": "Roo MCP client", "validated": "Partial"}
+        )
+        
+    def supports_web(self) -> HostCapabilityItem:
+        return HostCapabilityItem(
+            capability="web",
+            status=CapabilityStatus.HOST_DECLARED,
+            confidence=0.80,
+            details={"provider": "Browser tool", "validated": "Partial"}
+        )
+
+class CodexAdapter(HostAdapter):
+    def get_agent_name(self) -> str:
+        return "codex"
+        
+    def get_skill_paths(self) -> List[Path]:
+        cwd = Path.cwd()
+        return [cwd / ".agents" / "skills", cwd / "skills"]
+        
+    def supports_mcp(self) -> HostCapabilityItem:
+        return HostCapabilityItem(
+            capability="mcp",
+            status=CapabilityStatus.UNAVAILABLE,
+            confidence=0.90,
+            details={"validated": "Host-Dependent"}
+        )
+        
+    def supports_web(self) -> HostCapabilityItem:
+        return HostCapabilityItem(
+            capability="web",
+            status=CapabilityStatus.UNAVAILABLE,
+            confidence=0.90,
+            details={"validated": "Host-Dependent"}
+        )
+
+class OpenCodeAdapter(HostAdapter):
+    def get_agent_name(self) -> str:
+        return "opencode"
+        
+    def get_skill_paths(self) -> List[Path]:
+        cwd = Path.cwd()
+        return [cwd / ".opencode" / "skills", cwd / "skills"]
+        
+    def supports_mcp(self) -> HostCapabilityItem:
+        return HostCapabilityItem(
+            capability="mcp",
+            status=CapabilityStatus.UNKNOWN,
+            confidence=0.70,
+            details={"validated": "Host-Dependent"}
+        )
+        
+    def supports_web(self) -> HostCapabilityItem:
+        return HostCapabilityItem(
+            capability="web",
+            status=CapabilityStatus.UNKNOWN,
+            confidence=0.70,
+            details={"validated": "Host-Dependent"}
+        )
+
+class UnknownAgentAdapter(HostAdapter):
+    def __init__(self, raw_name: str):
+        self._raw_name = raw_name
+        
+    def get_agent_name(self) -> str:
+        return f"unknown:{self._raw_name}"
+        
+    def get_skill_paths(self) -> List[Path]:
+        cwd = Path.cwd()
+        return [cwd / "skills", cwd / ".skills"]
+        
+    def supports_mcp(self) -> HostCapabilityItem:
+        return HostCapabilityItem(
+            capability="mcp",
+            status=CapabilityStatus.UNKNOWN,
+            confidence=0.0,
+            details={"error": f"Agent '{self._raw_name}' is not recognized"}
+        )
+        
+    def supports_web(self) -> HostCapabilityItem:
+        return HostCapabilityItem(
+            capability="web",
+            status=CapabilityStatus.UNKNOWN,
+            confidence=0.0,
+            details={"error": f"Agent '{self._raw_name}' is not recognized"}
+        )
+
+def get_agent_adapter(agent_name: str) -> HostAdapter:
+    canonical = agent_name.lower().strip()
+    adapters = {
+        "gemini_cli": GeminiCliAdapter(),
+        "gemini": GeminiCliAdapter(),
+        "antigravity": GeminiCliAdapter(),
+        "claude_code": ClaudeCodeAdapter(),
+        "claude": ClaudeCodeAdapter(),
+        "cursor": CursorAdapter(),
+        "windsurf": WindsurfAdapter(),
+        "cline": ClineAdapter(),
+        "roo_code": RooCodeAdapter(),
+        "roo": RooCodeAdapter(),
+        "codex": CodexAdapter(),
+        "opencode": OpenCodeAdapter()
+    }
+    # Fix critical bug: NEVER silently convert unknown agent to Gemini
+    if canonical not in adapters:
+        return UnknownAgentAdapter(agent_name)
+    return adapters[canonical]

package/prompt_capability_optimizer/adapters/host_adapter.py

@@ -0,0 +1,48 @@
+# Copyright (c) 2026 Mahmoud Abdelhameid (Develper.net@gmail.com). All rights reserved.
+# Licensed under the MIT License.
+
+"""
+Host Runtime Abstraction
+========================
+Provides abstract interface for discovering capabilities, filesystem layouts,
+and execution boundaries across different AI agent hosts.
+"""
+
+import os
+import platform
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Dict, Any, List, Optional
+from ..models import HostCapabilityItem, CapabilityStatus
+
+def detect_host_runtime() -> str:
+    env = os.environ
+    if env.get("ANTIGRAVITY_AGENT") or any("antigravity" in k.lower() for k in env):
+        return "gemini_cli"
+    if env.get("CLAUDE_CODE_ENTRY") or ".claude" in env.get("CWD", ""):
+        return "claude_code"
+    if env.get("CURSOR_PROJECT_DIR") or env.get("CURSOR_TRACE"):
+        return "cursor"
+    if env.get("CLINE_ACTIVE"):
+        return "cline"
+    if env.get("ROO_CODE"):
+        return "roo_code"
+    return "generic_agent"
+
+class HostAdapter(ABC):
+    
+    @abstractmethod
+    def get_agent_name(self) -> str:
+        pass
+        
+    @abstractmethod
+    def get_skill_paths(self) -> List[Path]:
+        pass
+        
+    @abstractmethod
+    def supports_mcp(self) -> HostCapabilityItem:
+        pass
+        
+    @abstractmethod
+    def supports_web(self) -> HostCapabilityItem:
+        pass

package/prompt_capability_optimizer/capabilities/__init__.py

@@ -0,0 +1,7 @@
+# Copyright (c) 2026 Mahmoud Abdelhameid (Develper.net@gmail.com). All rights reserved.
+# Licensed under the MIT License.
+
+from .extractor import CapabilityExtractor
+from .graph import CapabilityGraph
+
+__all__ = ["CapabilityExtractor", "CapabilityGraph"]