prompt-capability-optimizer 1.0.0

package/prompt_capability_optimizer/optimization/semantic_pass.py

@@ -0,0 +1,113 @@
+# Copyright (c) 2026 Mahmoud Abdelhameid (Develper.net@gmail.com). All rights reserved.
+# Licensed under the MIT License.
+
+"""
+Pass 1 — Semantic Optimization & Intent Preservation
+====================================================
+Infers accurate personas from actual task content rather than arbitrary level numbers.
+Categorizes requirements into USER_EXPLICIT, PROJECT_CONSTRAINT, SECURITY_REQUIREMENT,
+and OPTIONAL_RECOMMENDATION without inventing unrequested mandatory burdens.
+"""
+
+import re
+from typing import Dict, Any, List
+from ..models import PromptIR, ClassificationReport, ClassifiedRequirement, RequirementCategory
+
+class SemanticPass:
+
+    @classmethod
+    def infer_task_role(cls, prompt_text: str, level: int) -> str:
+        """
+        Derives an appropriate role from actual task content instead of arbitrary level tier.
+        """
+        lower = prompt_text.lower()
+        
+        # Beginner or educational queries
+        if re.search(r"\b(?:beginner|explain|tutorial|what is|how does)\b", lower):
+            return "Technical Mentor & Software Specialist"
+            
+        # Security & Auth domains
+        if re.search(r"\b(?:auth|authentication|oauth|jwt|security|crypto|asvs|penetration)\b", lower):
+            return "Application Security & Authentication Specialist"
+            
+        # Performance & Memory
+        if re.search(r"\b(?:memory leak|profiling|heap|garbage collect|latency|optimization)\b", lower):
+            return "Runtime Performance & Diagnostics Specialist"
+            
+        # Frontend & UI
+        if re.search(r"\b(?:react|vue|ui|frontend|css|tailwind|playwright|cypress)\b", lower):
+            return "Frontend Systems & QA Automation Engineer"
+            
+        # Backend & APIs
+        if re.search(r"\b(?:nestjs|fastify|express|rest api|graphql|grpc|endpoint|microservices)\b", lower):
+            return "Backend Services & API Architect"
+            
+        # Multi-System SaaS
+        if level >= 4 or "saas" in lower or "multi-tenant" in lower:
+            return "Distributed Systems & Cloud Architect"
+            
+        # General engineering default
+        return "Senior Software Engineer"
+
+    @classmethod
+    def execute(cls, prompt_ir: PromptIR, classification: ClassificationReport) -> PromptIR:
+        # 1. Assign specialized persona based on actual task domain
+        prompt_ir.role = cls.infer_task_role(prompt_ir.raw_prompt, classification.level)
+        prompt_ir.depth = classification.level
+        
+        # 2. Extract and categorize requirements
+        classified_reqs: List[ClassifiedRequirement] = []
+        
+        # A. USER_EXPLICIT
+        classified_reqs.append(ClassifiedRequirement(
+            text=prompt_ir.objective,
+            category=RequirementCategory.USER_EXPLICIT
+        ))
+        
+        # B. PROJECT_CONSTRAINT (respecting existing repo language and style)
+        repo_rule = "Follow the repository's existing language standards, compiler settings, and architectural patterns."
+        classified_reqs.append(ClassifiedRequirement(
+            text=repo_rule,
+            category=RequirementCategory.PROJECT_CONSTRAINT
+        ))
+        if repo_rule not in prompt_ir.constraints:
+            prompt_ir.constraints.append(repo_rule)
+            prompt_ir.diff.added_constraints.append(repo_rule)
+            
+        additive_rule = "Additive Change Policy: Preserve existing working functionality and public contracts."
+        classified_reqs.append(ClassifiedRequirement(
+            text=additive_rule,
+            category=RequirementCategory.PROJECT_CONSTRAINT
+        ))
+        if additive_rule not in prompt_ir.constraints:
+            prompt_ir.constraints.append(additive_rule)
+            prompt_ir.diff.added_constraints.append(additive_rule)
+            
+        # C. SECURITY_REQUIREMENT
+        if classification.level >= 3 or any(w in prompt_ir.raw_prompt.lower() for w in ["auth", "security", "token", "password", "payment"]):
+            sec_rule = "Security: Sanitize all untrusted inputs, parameterize queries, and prevent credential exposure."
+            classified_reqs.append(ClassifiedRequirement(
+                text=sec_rule,
+                category=RequirementCategory.SECURITY_REQUIREMENT
+            ))
+            if sec_rule not in prompt_ir.constraints:
+                prompt_ir.constraints.append(sec_rule)
+                
+        # D. NEGATIVE CONSTRAINTS (Preventing unrequested scope changes)
+        negative_rules = [
+            "Do NOT introduce unapproved third-party dependencies.",
+            "Do NOT modify unrelated modules or existing configurations."
+        ]
+        for nr in negative_rules:
+            if nr not in prompt_ir.negative_constraints:
+                prompt_ir.negative_constraints.append(nr)
+                
+        # E. COMPLETION CRITERIA (emphasizing baseline regression prevention)
+        prompt_ir.completion_criteria = [
+            "All targeted functionality behaves as requested with zero regression against pre-existing baseline.",
+            "Code adheres strictly to project linting, typechecking, and formatting rules."
+        ]
+        
+        prompt_ir.categorized_requirements = classified_reqs
+        prompt_ir.diff.preserved_intent_summary = f"Preserved user intent: '{prompt_ir.objective}'"
+        return prompt_ir

package/prompt_capability_optimizer/scoring/__init__.py

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

package/prompt_capability_optimizer/scoring/deduplicator.py

@@ -0,0 +1,46 @@
+# Copyright (c) 2026 Mahmoud Abdelhameid (Develper.net@gmail.com). All rights reserved.
+# Licensed under the MIT License.
+
+"""
+Capability Deduplicator & Context Budgeter
+==========================================
+Eliminates overlapping capabilities and selects the most specialized, trusted candidates
+under strict token and context budgets.
+"""
+
+from typing import List, Set
+from ..models import Resource
+from .scoring_engine import ScoringEngine
+
+class CapabilityDeduplicator:
+    
+    @classmethod
+    def deduplicate(cls, candidates: List[Resource], max_count: int = 3, min_utility: float = 5.0) -> List[Resource]:
+        """
+        Filters candidates below minimum utility threshold, sorts by rank,
+        and prevents activating multiple tools covering the exact same primary capability.
+        """
+        ranked = ScoringEngine.rank_resources(candidates)
+        selected: List[Resource] = []
+        covered_capabilities: Set[str] = set()
+        
+        for res in ranked:
+            if res.utility_score < min_utility:
+                continue
+                
+            # Check overlap: does this resource provide already covered capabilities?
+            overlap = False
+            for cap in res.capabilities:
+                if cap in covered_capabilities:
+                    overlap = True
+                    break
+                    
+            # If not overlapping or if it provides significant new capability
+            if not overlap or len(selected) == 0:
+                selected.append(res)
+                covered_capabilities.update(res.capabilities)
+                
+            if len(selected) >= max_count:
+                break
+                
+        return selected

package/prompt_capability_optimizer/scoring/scoring_engine.py

@@ -0,0 +1,34 @@
+# Copyright (c) 2026 Mahmoud Abdelhameid (Develper.net@gmail.com). All rights reserved.
+# Licensed under the MIT License.
+
+"""
+Authoritative Scoring Engine
+============================
+The SINGLE source of truth for capability utility calculations, directly implementing
+the mathematical formula established in references/scoring_rubric.md.
+"""
+
+from typing import List
+from ..models import Resource
+
+class ScoringEngine:
+    
+    @classmethod
+    def calculate_utility(cls, resource: Resource) -> float:
+        """
+        Formula:
+        Utility = (0.25*R + 0.25*M + 0.15*Q + 0.15*T + 0.10*C + 0.05*F) - (0.10*O + 0.20*K)
+        """
+        return resource.utility_score
+
+    @classmethod
+    def rank_resources(cls, resources: List[Resource]) -> List[Resource]:
+        """
+        Sorts candidates by utility score descending.
+        Tie-breaking: Higher Trust -> Higher Quality -> Lower Overhead.
+        """
+        return sorted(
+            resources,
+            key=lambda r: (r.utility_score, r.trust, r.quality, -r.overhead),
+            reverse=True
+        )

package/prompt_capability_optimizer/security/__init__.py

@@ -0,0 +1,14 @@
+# Copyright (c) 2026 Mahmoud Abdelhameid (Develper.net@gmail.com). All rights reserved.
+# Licensed under the MIT License.
+
+from .trust_engine import TrustEngine
+from .injection_detector import PromptInjectionDetector
+from .secret_protector import SecretProtector
+from .governance import InstallationGovernance
+
+__all__ = [
+    "TrustEngine",
+    "PromptInjectionDetector",
+    "SecretProtector",
+    "InstallationGovernance"
+]

package/prompt_capability_optimizer/security/governance.py

@@ -0,0 +1,41 @@
+# Copyright (c) 2026 Mahmoud Abdelhameid (Develper.net@gmail.com). All rights reserved.
+# Licensed under the MIT License.
+
+"""
+Installation Governance & Permission Gate
+=========================================
+Enforces the 'Never Install Blindly' mandate and governs tool invocation side-effects.
+"""
+
+from typing import Dict, Any, Optional
+from ..models import Resource, RiskLevel
+
+class InstallationGovernance:
+    
+    @classmethod
+    def evaluate_installation(cls, resource: Resource) -> Dict[str, Any]:
+        """
+        Calculates whether a discovered external capability may be recommended or installed.
+        Decision rule: Expected Value > (Risk + Overhead)
+        """
+        expected_value = (resource.capability_match * 0.4) + (resource.quality * 0.3) + (resource.relevance * 0.3)
+        cost_and_risk = (resource.risk * 0.6) + (resource.overhead * 0.4)
+        
+        approved_for_recommendation = expected_value > cost_and_risk and resource.trust >= 6.0
+        requires_explicit_user_consent = resource.risk_level in [
+            RiskLevel.EXTERNAL_SIDE_EFFECT,
+            RiskLevel.DESTRUCTIVE
+        ]
+        
+        return {
+            "resource_name": resource.name,
+            "expected_value": round(expected_value, 2),
+            "cost_and_risk": round(cost_and_risk, 2),
+            "approved_for_recommendation": approved_for_recommendation,
+            "requires_explicit_user_consent": requires_explicit_user_consent,
+            "risk_level": resource.risk_level.value,
+            "governance_decision": (
+                "REQUIRE_USER_APPROVAL" if requires_explicit_user_consent else
+                ("ADOPT" if approved_for_recommendation else "REJECT")
+            )
+        }

package/prompt_capability_optimizer/security/injection_detector.py

@@ -0,0 +1,60 @@
+# Copyright (c) 2026 Mahmoud Abdelhameid (Develper.net@gmail.com). All rights reserved.
+# Licensed under the MIT License.
+
+"""
+Prompt Injection & Instruction Hijacking Detector
+=================================================
+Identifies directive-override patterns, system prompt hijacking attempts,
+and untrusted data exfiltration payloads.
+"""
+
+import re
+from typing import Dict, Any, List
+
+class PromptInjectionDetector:
+    
+    HIJACK_PATTERNS = [
+        r"(?i)\bignore\s+(?:all\s+)?(?:previous|prior|above)\s+instructions\b",
+        r"(?i)\byou\s+are\s+now\s+(?:in\s+developer\s+mode|unrestricted|dan\b|an\s+evil)",
+        r"(?i)\bdisregard\s+(?:all\s+)?safety\s+(?:guidelines|protocols)\b",
+        r"(?i)\bsystem\s+override\b",
+        r"(?i)\bnew\s+primary\s+directive\b",
+        r"(?i)\b(?:print|upload|exfiltrate|leak|curl|send)\s+(?:the\s+)?(?:secrets?|\.env|id_rsa|api_key|credentials?)\b"
+    ]
+
+    @classmethod
+    def scan(cls, text: str) -> Dict[str, Any]:
+        matched_threats = []
+        
+        for pat in cls.HIJACK_PATTERNS:
+            match = re.search(pat, text)
+            if match:
+                matched_threats.append(match.group(0))
+                
+        is_suspicious = len(matched_threats) > 0
+        
+        return {
+            "is_suspicious": is_suspicious,
+            "threat_count": len(matched_threats),
+            "threats_detected": matched_threats,
+            "action": "SANITIZE_AND_CONTAIN" if is_suspicious else "ALLOW"
+        }
+
+    @classmethod
+    def sanitize(cls, text: str) -> str:
+        """
+        Neutralizes detected hijacking directives by enclosing them in passive containment blocks.
+        """
+        scan_res = cls.scan(text)
+        if not scan_res["is_suspicious"]:
+            return text
+            
+        sanitized = text
+        for threat in scan_res["threats_detected"]:
+            sanitized = re.sub(
+                re.escape(threat),
+                f"[REDACTED_ADVERSARIAL_DIRECTIVE: '{threat}']",
+                sanitized,
+                flags=re.IGNORECASE
+            )
+        return sanitized

package/prompt_capability_optimizer/security/secret_protector.py

@@ -0,0 +1,61 @@
+# Copyright (c) 2026 Mahmoud Abdelhameid (Develper.net@gmail.com). All rights reserved.
+# Licensed under the MIT License.
+
+"""
+Secret & Credential Protector
+=============================
+Detects plaintext secrets, API keys, private tokens, and database passwords
+using strict regex patterns and entropy analysis.
+CRITICAL SAFETY INVARIANT: Never retains or serializes plaintext secret values.
+"""
+
+import re
+from typing import Dict, Any, List
+
+class SecretProtector:
+    
+    SECRET_PATTERNS = [
+        # AWS Access Key
+        (r"\b(AKIA[0-9A-Z]{16})\b", "AWS_ACCESS_KEY"),
+        # GitHub Personal Access Token
+        (r"\b(gh[pousr]_[A-Za-z0-9_]{36,255})\b", "GITHUB_TOKEN"),
+        # OpenAI / Standard Bearer sk- keys
+        (r"\b(sk-[a-zA-Z0-9]{20,64})\b", "API_SECRET_KEY"),
+        # JWT Token pattern (three base64 chunks)
+        (r"\b(ey[A-Za-z0-9_-]{10,}\.ey[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,})\b", "JWT_TOKEN"),
+        # Database connection strings with credentials
+        (r"(?i)\b([a-z]+:\/\/[a-zA-Z0-9_\-\.]+:[^@\s\/]+@[a-zA-Z0-9_\-\.]+:[0-9]+\/[a-zA-Z0-9_\-\.]+)\b", "DATABASE_CREDENTIALS"),
+        # Generic private key headers
+        (r"-----BEGIN\s+(?:RSA\s+)?PRIVATE\s+KEY-----[\s\S]+?-----END\s+(?:RSA\s+)?PRIVATE\s+KEY-----", "PRIVATE_KEY"),
+        # Generic password assignment
+        (r"(?i)\b(?:password|passwd|secret)\s*[:=]\s*['\"]([^'\"]{6,})['\"]", "PLAINTEXT_PASSWORD")
+    ]
+
+    @classmethod
+    def find_secrets(cls, text: str) -> List[Dict[str, Any]]:
+        """
+        Detects secrets and returns sanitized descriptor objects.
+        NEVER stores or leaks the raw plaintext secret string.
+        """
+        found = []
+        for pattern, label in cls.SECRET_PATTERNS:
+            for match in re.finditer(pattern, text):
+                matched_val = match.group(1) if match.groups() else match.group(0)
+                # Form secure masked preview without retaining original payload
+                preview = matched_val[:3] + "..." + matched_val[-3:] if len(matched_val) > 6 else "***"
+                found.append({
+                    "label": label,
+                    "preview": preview,
+                    "length": len(matched_val),
+                    "redacted": True
+                })
+        return found
+
+    @classmethod
+    def redact(cls, text: str) -> str:
+        redacted = text
+        for pattern, label in cls.SECRET_PATTERNS:
+            def _replace(match):
+                return f"[REDACTED_{label}]"
+            redacted = re.sub(pattern, _replace, redacted)
+        return redacted

package/prompt_capability_optimizer/security/trust_engine.py

@@ -0,0 +1,96 @@
+# Copyright (c) 2026 Mahmoud Abdelhameid (Develper.net@gmail.com). All rights reserved.
+# Licensed under the MIT License.
+
+"""
+Trust & Provenance Engine
+=========================
+Separates reputation signals (stars/downloads) from verified security/trust metrics.
+Evaluates requested permissions, publisher domain provenance, and metadata.
+"""
+
+from typing import Dict, Any, List
+from ..models import Resource, RiskLevel, ResourceType
+
+class TrustEngine:
+    
+    VERIFIED_PUBLISHERS = {
+        "anthropics", "vercel-labs", "google", "microsoft", "github",
+        "nestjs", "facebook", "aws", "docker", "composiohq"
+    }
+    
+    TRUSTED_DOMAINS = {
+        "docs.nestjs.com", "owasp.org", "react.dev", "go.dev", "python.org",
+        "typescriptlang.org", "nodejs.org", "postgresql.org", "redis.io",
+        "kafka.apache.org", "temporal.io", "neon.tech", "prisma.io"
+    }
+
+    @classmethod
+    def evaluate_resource_trust(cls, resource: Resource) -> Dict[str, Any]:
+        """
+        Calculates distinct Reputation vs. Trust/Security scores using domain provenance and metadata.
+        """
+        trust_factors = []
+        risk_flags = []
+        provenance_score = 5.0
+        
+        # 1. Provenance from official domains (for Web Documentation)
+        domain = resource.metadata.get("domain", "")
+        if not domain and resource.location:
+            import urllib.parse
+            try:
+                domain = urllib.parse.urlparse(resource.location).hostname or ""
+            except Exception:
+                domain = ""
+                
+        if domain in cls.TRUSTED_DOMAINS or any(domain.endswith(f".{td}") for td in cls.TRUSTED_DOMAINS):
+            trust_factors.append(f"Verified authoritative technical domain ({domain})")
+            provenance_score = 9.8
+        elif resource.type == ResourceType.DOCUMENTATION:
+            if domain.endswith(".org") or domain.endswith(".dev") or domain.endswith(".io"):
+                provenance_score = 8.5
+            else:
+                provenance_score = 7.0
+
+        # 2. Provenance from publisher names (for skills/packages)
+        publisher = resource.name.split("/")[0] if "/" in resource.name else ""
+        if publisher.lower() in cls.VERIFIED_PUBLISHERS:
+            trust_factors.append(f"Verified official ecosystem publisher ({publisher})")
+            provenance_score = max(provenance_score, 9.5)
+            
+        if resource.source.startswith("local_builtin"):
+            trust_factors.append("Host agent built-in capability")
+            provenance_score = 10.0
+        elif resource.source.startswith("local"):
+            trust_factors.append("Local project/user verified file")
+            provenance_score = max(provenance_score, 8.5)
+            
+        # 3. Permission and side-effect review
+        if any("write" in p.lower() or "exec" in p.lower() or "install" in p.lower() for p in resource.permissions):
+            risk_flags.append("Demands write/exec/install permissions")
+            permission_penalty = 1.5
+        else:
+            permission_penalty = 0.0
+            
+        # Composite security trust score (0.0 to 10.0)
+        final_trust = max(1.0, min(10.0, provenance_score - permission_penalty))
+        
+        # Determine strict RiskLevel
+        if "install_required" in resource.permissions:
+            risk_level = RiskLevel.EXTERNAL_SIDE_EFFECT
+        elif permission_penalty > 0:
+            risk_level = RiskLevel.LOW_RISK
+        else:
+            risk_level = RiskLevel.NO_SIDE_EFFECT
+            
+        resource.trust = round(final_trust, 2)
+        resource.risk_level = risk_level
+        
+        return {
+            "resource_id": resource.id,
+            "provenance_score": provenance_score,
+            "security_trust_score": final_trust,
+            "reputation_score": resource.reputation,
+            "risk_level": risk_level.value,
+            "trust_factors": trust_factors,
+            "risk_flags": risk_flags
+        }

package/prompt_capability_optimizer/verification/__init__.py

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

package/prompt_capability_optimizer/verification/verification_engine.py

@@ -0,0 +1,101 @@
+# Copyright (c) 2026 Mahmoud Abdelhameid (Develper.net@gmail.com). All rights reserved.
+# Licensed under the MIT License.
+
+"""
+Repository-Aware Verification Engine
+====================================
+Dynamically derives concrete test, build, lint, and typecheck commands from
+actual repository configuration files, lockfiles, and declared scripts.
+Prioritizes project-declared commands and guards against hallucinated toolchains.
+"""
+
+import os
+import json
+from pathlib import Path
+from typing import List, Dict, Any, Optional
+
+class VerificationEngine:
+    
+    @classmethod
+    def detect_package_manager(cls, root: Path) -> str:
+        # Check modern lockfiles in order of precedence
+        if (root / "bun.lockb").exists() or (root / "bun.lock").exists():
+            return "bun"
+        if (root / "pnpm-lock.yaml").exists():
+            return "pnpm"
+        if (root / "yarn.lock").exists():
+            return "yarn"
+        return "npm"
+
+    @classmethod
+    def derive_verification_directives(cls, workspace_root: Optional[Path] = None) -> List[str]:
+        root = workspace_root or Path.cwd()
+        directives: List[str] = []
+        
+        # 1. Node.js / JavaScript / TypeScript Projects
+        pkg_json = root / "package.json"
+        if pkg_json.exists() and pkg_json.is_file():
+            try:
+                data = json.loads(pkg_json.read_text(encoding="utf-8", errors="replace"))
+                scripts = data.get("scripts", {})
+                pm = cls.detect_package_manager(root)
+                
+                if "test" in scripts:
+                    directives.append(f"Execute project test runner: {pm} test")
+                elif "test:unit" in scripts:
+                    directives.append(f"Execute unit tests: {pm} run test:unit")
+                    
+                if "test:e2e" in scripts:
+                    directives.append(f"Execute e2e integration suite: {pm} run test:e2e")
+                    
+                if "lint" in scripts:
+                    directives.append(f"Run code linter: {pm} run lint")
+                    
+                if "build" in scripts:
+                    directives.append(f"Run compilation build: {pm} run build")
+                    
+                # Only require typecheck if tsconfig exists AND typescript is installed/scripted
+                if (root / "tsconfig.json").exists():
+                    if "typecheck" in scripts:
+                        directives.append(f"Validate types: {pm} run typecheck")
+                    else:
+                        directives.append("Validate TypeScript types: npx tsc --noEmit")
+            except Exception:
+                pass
+                
+        # 2. Python Projects
+        pyproject = root / "pyproject.toml"
+        poetry_lock = root / "poetry.lock"
+        requirements = root / "requirements.txt"
+        
+        if pyproject.exists() or requirements.exists() or poetry_lock.exists() or any(root.glob("*.py")):
+            if poetry_lock.exists():
+                directives.append("Execute Python tests: poetry run pytest")
+            elif pyproject.exists():
+                text = pyproject.read_text(encoding="utf-8", errors="replace")
+                if "pytest" in text:
+                    directives.append("Execute Python tests: pytest")
+                else:
+                    directives.append("Execute Python tests: python -m unittest discover")
+            else:
+                directives.append("Execute Python test suite: python -m unittest discover")
+                
+            directives.append("Verify Python syntax and imports with standard compiler")
+
+        # 3. Rust Projects
+        cargo = root / "Cargo.toml"
+        if cargo.exists():
+            directives.append("Execute Rust test suite: cargo test")
+            directives.append("Run static analysis: cargo clippy -- -D warnings")
+            directives.append("Verify compilation: cargo check")
+
+        # 4. Go Projects
+        gomod = root / "go.mod"
+        if gomod.exists():
+            directives.append("Execute Go test suite: go test -v ./...")
+            directives.append("Verify package compilation: go build ./...")
+
+        # Baseline regression guard
+        directives.append("Verify zero new regressions introduced against pre-existing repository baseline")
+
+        return directives

package/references/capability_graph.md

@@ -0,0 +1,83 @@
+# Capability Graph & Taxonomy Specification
+
+This document formalizes the **Capability Graph** engine of `prompt-capability-optimizer`. Rather than matching keywords superficially, the engine decomposes user tasks into an ontology of technical capabilities, then maps those capabilities to the optimal combination of local skills, MCP tools, and engineering patterns.
+
+---
+
+## 1. Capability Ontology Hierarchy
+
+All software engineering tasks decompose into five primary capability domains:
+
+```text
+                               TASK INTENT
+                                    │
+       ┌──────────────┬─────────────┼─────────────┬──────────────┐
+       ▼              ▼             ▼             ▼              ▼
+[ Architecture ] [ Operations ] [ Security ] [ Data/State ] [ Quality/Test ]
+       │              │             │             │              │
+       ├─ Framework   ├─ CI/CD      ├─ Auth/RBAC  ├─ Relational  ├─ Unit tests
+       ├─ Patterns    ├─ Docker     ├─ Encryption ├─ Key-Value   ├─ E2E/Integ
+       ├─ Contracts   ├─ Cloud/IaC  ├─ Injection  ├─ Migrations  ├─ Static/Lint
+       └─ Boundaries  └─ Monitor    └─ Audit      └─ Caching     └─ Benchmark
+```
+
+---
+
+## 2. Dynamic Decomposition Rules
+
+When a prompt is evaluated, the optimizer traverses the graph:
+
+### Example Decomposition: "Build a real-time collaborative whiteboarding API"
+```text
+Goal: Real-time Whiteboarding API
+ ├── [Data & State]
+ │    ├── Capability: Ephemeral state synchronization
+ │    │    └── Candidate: Redis Pub/Sub, WebSockets
+ │    └── Capability: Durable board storage
+ │         └── Candidate: PostgreSQL + JSONB or MongoDB
+ ├── [Architecture & Protocol]
+ │    ├── Capability: Bidirectional socket streaming
+ │    │    └── Candidate: Socket.io, ws, or WebTransport
+ │    └── Capability: Operational Transformation / CRDT
+ │         └── Candidate: Yjs or Automerge algorithms
+ ├── [Security]
+ │    ├── Capability: Room-level authorization
+ │    │    └── Candidate: JWT claims, tenant scoping
+ │    └── Capability: DoS & Message flood protection
+ │         └── Candidate: Token-bucket rate limiting
+ └── [Quality Assurance]
+      └── Capability: Concurrent socket load testing
+           └── Candidate: Artillery or k6
+```
+
+---
+
+## 3. Capability Matching & Graph Resolution
+
+Once the capability nodes are extracted, the engine maps each node to available resources:
+
+```text
+Capability Node ───► 1. Exact Local Skill Match (Score: 10/10)
+                 ───► 2. Active MCP Tool Match (Score: 9/10)
+                 ───► 3. Verified Online Skill Registry Match (Score: 8/10)
+                 ───► 4. Official Upstream Documentation Pattern (Score: 7/10)
+                 ───► 5. Base LLM In-Context Domain Instruction (Score: 6/10)
+```
+
+---
+
+## 4. Conflict Resolution & Dependency Graph
+
+Tasks often involve mutually exclusive technical options (e.g., REST vs. gRPC, TypeORM vs. Prisma).
+
+1. **Resolution Precedence**:
+   - **User Explicit Choice**: Always honored as primary constraint.
+   - **Existing Repository Dependency**: If `package.json` has `prisma`, do not introduce `typeorm`.
+   - **Official Ecosystem Standard**: If starting from scratch, select the standard community tool (e.g., Fastify + Zod for high-throughput Node.js).
+
+2. **Graph Pruning**:
+   - Capabilities that add zero value to the primary objective are pruned.
+   - Example: A request to "write an algorithmic sorter" does not need Docker, Kubernetes, or JWT auth capabilities.
+
+---
+**Author**: Mahmoud Abdelhameid ([LinkedIn](https://www.linkedin.com/in/mahmoud-abdelhameid-dev/) | [Email](mailto:Develper.net@gmail.com)) | **Copyright**: © 2026 Mahmoud Abdelhameid. All rights reserved. | **License**: MIT License