higpertext-cli 0.8.0__py3-none-any.whl

higpertext/hooks/hooks_catalog.json

@@ -0,0 +1,116 @@
+{
+  "hooks": [
+    {
+      "id": "hook_bash_guard",
+      "event": "PreToolUse",
+      "matcher": "Bash",
+      "script": "src/higpertext/hooks/hook_tasks/hook_bash_guard.py",
+      "description": "Evalúa en cadena todas las reglas Bash: bloques duros, grep/find, git, docs, list-rules, load-rules, exit, higpertext-enforcer.",
+      "timeout": 10,
+      "enabled": true,
+      "assistants": [],
+      "profiles": [],
+      "capability_id": ""
+    },
+    {
+      "id": "hook_code_quality",
+      "event": "PreToolUse",
+      "matcher": "Write|Edit",
+      "script": "src/higpertext/hooks/hook_tasks/hook_code_quality.py",
+      "description": "Evalúa calidad de código Python antes de escribir: longitud de funciones y clases.",
+      "timeout": 10,
+      "enabled": true,
+      "assistants": [],
+      "profiles": [
+        "software_developer",
+        "devsecops",
+        "ado_admin"
+      ],
+      "capability_id": "ado_admin.code-quality"
+    },
+    {
+      "id": "hook_read_guard",
+      "event": "PreToolUse",
+      "matcher": "Read",
+      "script": "src/higpertext/hooks/hook_tasks/hook_read_guard.py",
+      "description": "Bloquea lecturas completas de archivos grandes y recomienda smart-read o skeletonizer.",
+      "timeout": 5,
+      "enabled": true,
+      "assistants": [],
+      "profiles": [],
+      "capability_id": "common.smart-read"
+    },
+    {
+      "id": "hook_security_guard_pre",
+      "event": "PreToolUse",
+      "matcher": "Bash|PowerShell|Read|Write|Edit",
+      "script": "src/higpertext/hooks/hook_tasks/hook_security_guard.py",
+      "description": "Bloquea comandos y rutas sensibles según security_guardrails.json.",
+      "timeout": 5,
+      "enabled": true,
+      "assistants": [],
+      "profiles": [],
+      "capability_id": "security.vuln-resolver"
+    },
+    {
+      "id": "hook_security_guard_post",
+      "event": "PostToolUse",
+      "matcher": "",
+      "script": "src/higpertext/hooks/hook_tasks/hook_security_guard.py",
+      "description": "Enmascara secretos detectados en outputs de herramientas.",
+      "timeout": 5,
+      "enabled": true,
+      "assistants": [],
+      "profiles": [],
+      "capability_id": "security.vuln-resolver"
+    },
+    {
+      "id": "hook_post_observer",
+      "event": "PostToolUse",
+      "matcher": "",
+      "script": "src/higpertext/hooks/hook_tasks/hook_post_observer.py",
+      "description": "Registra telemetría de tokens y actividad tras cada tool call.",
+      "timeout": 5,
+      "enabled": true,
+      "assistants": [],
+      "profiles": [],
+      "capability_id": ""
+    },
+    {
+      "id": "hook_session_prompt",
+      "event": "UserPromptSubmit",
+      "matcher": "",
+      "script": "src/higpertext/hooks/hook_tasks/hook_session_prompt.py",
+      "description": "Inyecta estado de sesión higpertext y contexto de skills activas en cada prompt.",
+      "timeout": 10,
+      "enabled": true,
+      "assistants": [],
+      "profiles": [],
+      "capability_id": "common.session-start"
+    },
+    {
+      "id": "hook_session_stop",
+      "event": "Stop",
+      "matcher": "",
+      "script": "src/higpertext/hooks/hook_tasks/hook_session_stop.py",
+      "description": "Al cerrar el turno, verifica commits pendientes y recuerda ejecutar session-clean.",
+      "timeout": 10,
+      "enabled": true,
+      "assistants": [],
+      "profiles": [],
+      "capability_id": "common.session-clean"
+    },
+    {
+      "id": "hook_context_manager",
+      "event": "PreCompact",
+      "matcher": "",
+      "script": "src/higpertext/hooks/hook_tasks/hook_context_manager.py",
+      "description": "Preserva estado higpertext crítico (sesión, skills, perfil) antes de compresión de contexto.",
+      "timeout": 5,
+      "enabled": true,
+      "assistants": [],
+      "profiles": [],
+      "capability_id": ""
+    }
+  ]
+}

higpertext/kernel/__init__.py

@@ -0,0 +1,63 @@
+from higpertext.kernel.htx_resolver import get_htx_cmd, HTX_CMD, HTX_WORKFLOW_CMD
+from higpertext.kernel.engine import HigpertextEngine
+from higpertext.kernel.session_manager import SessionManager
+from higpertext.kernel.pkg_resources import (
+    installed_src_root,
+    resolve_resource,
+    pkg_data_root,
+)
+from higpertext.kernel.application.environment_manager import EnvironmentManager
+from higpertext.kernel.infrastructure.validation.contract_validator import (
+    ContractValidator,
+)
+from higpertext.kernel.infrastructure.execution.parallel import (
+    ParallelExecutor,
+    build_step_groups,
+    StepGroup,
+)
+from higpertext.kernel.infrastructure.execution.resilience import (
+    get_resilience_manager,
+    CircuitBreaker,
+    CircuitState,
+    ResilienceManager,
+)
+from higpertext.kernel.infrastructure.cache.capability_cache import (
+    get_capability_cache,
+    CapabilityCache,
+    CacheEntry,
+)
+from higpertext.kernel.infrastructure.diagnostics.health import run_health_check
+from higpertext.kernel.infrastructure.parser.semantic_graph import (
+    SemanticGraphGenerator,
+)
+from higpertext.kernel.infrastructure.cli.parameter_contracts import (
+    normalize_and_validate_params,
+    ParameterValidation,
+)
+
+__all__ = [
+    "get_htx_cmd",
+    "HTX_CMD",
+    "HTX_WORKFLOW_CMD",
+    "HigpertextEngine",
+    "EnvironmentManager",
+    "SessionManager",
+    "ContractValidator",
+    "ParallelExecutor",
+    "build_step_groups",
+    "StepGroup",
+    "get_resilience_manager",
+    "CircuitBreaker",
+    "CircuitState",
+    "ResilienceManager",
+    "get_capability_cache",
+    "CapabilityCache",
+    "CacheEntry",
+    "run_health_check",
+    "SemanticGraphGenerator",
+    "normalize_and_validate_params",
+    "ParameterValidation",
+    "installed_src_root",
+    "resolve_resource",
+    "pkg_data_root",
+]

higpertext/kernel/_compat.py

@@ -0,0 +1,138 @@
+"""Single shim — all kernel re-exports from infrastructure/application layers."""
+
+# CLI
+from higpertext.kernel.app_config import (  # noqa: F401
+    ASSISTANT_IGNORE_FILES as _ASSISTANT_IGNORE,
+    GUIDE_SPECS as _GUIDE_SPECS,
+    PROFILES_SECTION as _PROFILES_SECTION,
+    RULES_SECTION as _RULES_SECTION,
+)
+from higpertext.kernel.infrastructure.cli.router import (  # noqa: F401
+    ROOT_DIR,
+    POSTMORTEM_DIR,
+    GOVERNANCE_DIR,
+    DOCS_DIR,
+    _ADAPTER_MAP,
+    _parse_kv_args,
+    HigpertextHub,
+    _add_task_ask_subparsers,
+    _add_profile_init_subparsers,
+    _add_session_workflow_subparsers,
+    _add_health_subparser,
+    _add_roadmap_subparser,
+    _build_parser,
+    _parse_session_resources,
+    _start_session,
+    _dispatch_session,
+    _dispatch_workflow,
+    _dispatch_command,
+    _dispatch_roadmap,
+    _dispatch_profile_learn,
+    _dispatch_non_task,
+    main,
+)
+from higpertext.kernel.infrastructure.cli.cli_search import (  # noqa: F401
+    HigpertextSearchMixin,
+)
+
+# Application services
+from higpertext.kernel.application.environment_manager import (  # noqa: F401
+    EnvironmentManager,
+)
+from higpertext.kernel.session_manager import SessionManager  # noqa: F401
+from higpertext.kernel.application.capability_manager import (  # noqa: F401
+    CapabilityManager,
+)
+from higpertext.kernel.application.workflow_manager import (  # noqa: F401
+    WorkflowManager,
+)
+from higpertext.kernel.application.profile_services import (  # noqa: F401
+    ProfileApplicationService,
+    ProfileManager,
+)
+from higpertext.kernel.application.profile_service import (  # noqa: F401
+    ProfileService,
+)
+from higpertext.kernel.application.context_builder import (  # noqa: F401
+    SessionContextBuilder,
+    _UNIVERSAL_SKILLS,
+    _UNIVERSAL_SUBAGENTS,
+)
+from higpertext.kernel.application.engine import (  # noqa: F401
+    ApplicationHigpertextEngine,
+)
+
+# Infrastructure
+from higpertext.kernel.infrastructure.validation.contract_validator import (  # noqa: F401
+    ContractValidator,
+)
+from higpertext.kernel.infrastructure.cache.capability_cache import (  # noqa: F401
+    CapabilityCache,
+    CacheEntry,
+    get_capability_cache,
+)
+from higpertext.kernel.infrastructure.execution.parallel import (  # noqa: F401
+    ParallelExecutor,
+    build_step_groups,
+    StepGroup,
+)
+from higpertext.kernel.infrastructure.execution.resilience import (  # noqa: F401
+    get_resilience_manager,
+    CircuitBreaker,
+    CircuitState,
+    ResilienceManager,
+)
+from higpertext.kernel.infrastructure.diagnostics.health import (  # noqa: F401
+    run_health_check,
+)
+from higpertext.kernel.infrastructure.parser.semantic_graph import (  # noqa: F401
+    SemanticGraphGenerator,
+    IgnoreChecker,
+)
+from higpertext.kernel.infrastructure.parser.language.python_parser import _ASTVisitor as PythonASTVisitor  # noqa: F401
+from higpertext.kernel.infrastructure.parser.language.base import ParseResult as _ParseResult
+
+
+def _empty_parse_result(note: str = "") -> dict:  # noqa: F401
+    return _ParseResult(summary=note).to_dict()
+from higpertext.kernel.infrastructure.presentation.markdown_renderer import (  # noqa: F401
+    MarkdownRenderer,
+)
+from higpertext.kernel.infrastructure.cli.parameter_contracts import (  # noqa: F401
+    normalize_and_validate_params,
+    ParameterValidation,
+)
+from higpertext.kernel.infrastructure.deployment.resource_deployer import (  # noqa: F401
+    ResourceDeployer,
+    _NO_SKILLS_MSG,
+    _NO_SUBAGENTS_MSG,
+)
+from higpertext.kernel.infrastructure.capability_helper import (  # noqa: F401
+    CapabilityHelper,
+)
+from higpertext.kernel.infrastructure.file_repositories import (  # noqa: F401
+    FileProfileRepository,
+    FileSessionRepository,
+)
+from higpertext.kernel.infrastructure.llm.registry import LLMRegistry  # noqa: F401
+
+# Application ports
+from higpertext.kernel.application.ports import (  # noqa: F401
+    IProfileRepository,
+    ICapabilityRepository,
+)
+from higpertext.kernel.domain.entities import Profile, Capability  # noqa: F401
+
+# Adapters
+from higpertext.adapters.gemini_adapter.gemini_adapter import (  # noqa: F401
+    GeminiAdapter,
+)
+from higpertext.adapters.claude_adapter.claude_adapter import (  # noqa: F401
+    ClaudeAdapter,
+)
+from higpertext.adapters.copilot_adapter.copilot_adapter import (  # noqa: F401
+    CopilotAdapter,
+)
+from higpertext.adapters.open_code_adapter.open_code_adapter import (  # noqa: F401
+    OpenCodeAdapter,
+)

higpertext/kernel/app_config.py

@@ -0,0 +1,117 @@
+"""Single source of truth for application-level static constants, driven by src/config/app_config.json."""
+
+from __future__ import annotations
+import json
+from pathlib import Path
+
+from higpertext.kernel.config_paths import PROJECT_ROOT as _ROOT
+
+_CONFIG_FILE = _ROOT / "src" / "config" / "app_config.json"
+
+
+def _load() -> dict:
+    return json.loads(_CONFIG_FILE.read_text(encoding="utf-8"))
+
+
+_CFG = _load()
+
+
+def get(section: str, key: str, default=None):
+    """Return a value from app_config.json by section and key."""
+    return _CFG.get(section, {}).get(key, default)
+
+
+# ── router_content.json ───────────────────────────────────────────────────────
+_ROUTER_FILE = _ROOT / "src" / "config" / "router_content.json"
+_RC = json.loads(_ROUTER_FILE.read_text(encoding="utf-8"))
+
+IGNORE_PATTERNS: list[str] = _RC["ignore_patterns"]
+ASSISTANT_IGNORE_FILES: dict[str, list[str]] = _RC["assistant_ignore_files"]
+GITIGNORE_SECTION: str = "\n".join(_RC["gitignore_section"])
+GUIDE_SPECS: dict[str, dict] = _RC["guide_specs"]
+PROFILES_SECTION: list[str] = _RC["profiles_section"]
+RULES_SECTION: list[str] = _RC["rules_section"]
+
+
+# ── session ───────────────────────────────────────────────────────────────────
+DEFAULT_ASSISTANT: str = _CFG["session"]["default_assistant"]
+DEFAULT_PROFILE: str = _CFG["session"]["default_profile"]
+GLOBAL_PROFILE_NAMES: frozenset[str] = frozenset(_CFG["session"]["global_profile_names"])
+ASSISTANTS: list[str] = _CFG["session"]["assistants"]
+APPEND_ASSISTANTS: set[str] = set(_CFG["session"]["append_assistants"])
+
+# ── logger ────────────────────────────────────────────────────────────────────
+LOGGER_NAME: str = _CFG["logger"]["name"]
+LOG_FILE: str = _CFG["logger"]["log_file"]
+
+# ── store ─────────────────────────────────────────────────────────────────────
+REPORTS_DIR: str = _CFG["store"]["reports_dir"]
+INDEX_FILE: str = _CFG["store"]["index_file"]
+TELEMETRY_FILE: str = _CFG["store"]["telemetry_file"]
+PROFILE_FILE: str = _CFG["store"]["profile_file"]
+AGENTS_DIR: str = _CFG["store"]["agents_dir"]
+SETTINGS_FILE: str = _CFG["store"]["settings_file"]
+ENVIRONMENT_FILE: str = _CFG["store"]["environment_file"]
+SESSION_FILE: str = _CFG["store"]["session_file"]
+
+# ── cache ─────────────────────────────────────────────────────────────────────
+CACHE_DIR: str = _CFG["cache"]["cache_dir"]
+CACHE_FILE_GLOB: str = _CFG["cache"]["file_glob"]
+NO_CACHE_CAPABILITIES: frozenset[str] = frozenset(_CFG["cache"]["no_cache_capabilities"])
+
+# ── deployment ────────────────────────────────────────────────────────────────
+AGENT_JSON: str = _CFG["deployment"]["agent_json"]
+PLAYBOOKS: tuple[str, ...] = tuple(_CFG["deployment"]["playbooks"])
+NO_SKILLS_MSG: str = _CFG["deployment"]["no_skills_message"]
+NO_SUBAGENTS_MSG: str = _CFG["deployment"]["no_subagents_message"]
+
+# ── providers ─────────────────────────────────────────────────────────────────
+OLLAMA_BASE_URL: str = _CFG["providers"]["ollama_base_url"]
+
+# ── context ───────────────────────────────────────────────────────────────────
+UNIVERSAL_SKILLS: list[str] = _CFG["context"]["universal_skills"]
+LOG_SEP: str = _CFG["context"]["log_sep"]
+
+# ── docs ──────────────────────────────────────────────────────────────────────
+INDEX_LINK: str = _CFG["docs"]["index_link"]
+
+# ── rules ─────────────────────────────────────────────────────────────────────
+PINNED_CAPABILITIES: list[str] = _CFG["rules"]["pinned_capabilities"]
+CLI_NAME: str = _CFG["rules"]["cli_name"]
+
+# ── assistants ────────────────────────────────────────────────────────────────
+# {assistant: (workflows_dir, skills_dir, agents_dir)}
+ASSISTANT_PATHS: dict[str, tuple[str, str, str]] = {
+    k: tuple(v) for k, v in _CFG["assistants"]["paths"].items()  # type: ignore[misc]
+}
+SKILL_DIRS: dict[str, str] = _CFG["assistants"]["skill_dirs"]
+AGENT_DIRS: dict[str, str] = _CFG["assistants"]["agent_dirs"]
+ASSISTANT_ROOT_DIRS: dict[str, str] = _CFG["assistants"]["root_dirs"]
+ASSISTANT_DISPLAY_NAMES: dict[str, str] = _CFG["assistants"]["display_names"]
+RULES_DESTINATIONS_REL: dict[str, str] = _CFG["assistants"]["rules_destinations"]
+IGNORE_TOOLS: frozenset[str] = frozenset(_CFG["assistants"]["ignore_tools"])
+ASSISTANT_HOOKS_DIRS: dict[str, str] = _CFG["assistants"]["hooks_dirs"]
+ASSISTANT_ALIASES: dict[str, str] = _CFG["assistants"]["aliases"]
+
+# ── profiles ──────────────────────────────────────────────────────────────────
+RESERVED_PROFILES: frozenset[str] = frozenset(_CFG["profiles"]["reserved"])
+
+# ── git ───────────────────────────────────────────────────────────────────────
+GIT_STATUS_LABELS: dict[str, str] = _CFG["git"]["status_labels"]
+
+# ── telemetry_reporter ────────────────────────────────────────────────────────
+_TR = _CFG["telemetry_reporter"]
+TELEMETRY_BOX_WIDTH: int = _TR["box_width"]
+TELEMETRY_BAR_WIDTH: int = _TR["bar_width"]
+TELEMETRY_EMPTY_TITLE: str = _TR["empty_state"]["title"]
+TELEMETRY_EMPTY_LINES: list[str] = _TR["empty_state"]["lines"]
+TELEMETRY_SECTION_LABELS: dict[str, str] = _TR["section_labels"]
+TELEMETRY_ACTIVITY_ICONS: dict[str, str] = _TR["activity_icons"]
+
+# ── antigravity_agent_template ────────────────────────────────────────────────
+_AGT_FILE = _ROOT / "src" / "config" / "antigravity_agent_template.json"
+ANTIGRAVITY_AGENT_TEMPLATE: dict = json.loads(_AGT_FILE.read_text(encoding="utf-8"))
+
+# ── adapters_config ───────────────────────────────────────────────────────────
+_ADAPT_FILE = _ROOT / "src" / "config" / "adapters_config.json"
+ADAPTERS_CONFIG: dict = json.loads(_ADAPT_FILE.read_text(encoding="utf-8"))

higpertext/kernel/application/__init__.py

@@ -0,0 +1,13 @@
+# Application layer init
+from higpertext.kernel.application.governance import GovernanceEnforcer, ExceptionRegistry
+from higpertext.kernel.application.agent_registry import RegisterAgentUseCase, ListAgentsUseCase, SyncAgentUseCase
+from higpertext.kernel.application.env_runtime import EnvironmentService
+from higpertext.kernel.application.commit_reporter import CommitParser, ImpactAnalyzer, ReportBuilder, CommitAnalysis
+from higpertext.kernel.application.roadmap_reporter import ProgressAnalyzer, RoadmapParser, RoadmapReportBuilder, RoadmapAnalysis
+from higpertext.kernel.application.profile_learner import ProfileExtractor, ProfileUpdater, WeightsCalibrator
+from higpertext.kernel.application.profile_use_cases import GetAgentContextUseCase, ValidateProfileUseCase
+from higpertext.kernel.application.ports import ICapabilityRepository, IProfileRepository, ISessionRepository, IWorkflowRepository
+from higpertext.kernel.application.telemetry import TelemetryCollector, TelemetryAggregator, get_collector
+from higpertext.kernel.application.context_engine import ContextAssembler, EfficiencyMeter, TaskDecomposer
+from higpertext.kernel.application.semantic_engine import ClusterService, ContextRanker, GraphBuilder
+

higpertext/kernel/application/agent_registry.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+from datetime import datetime, timezone
+from pathlib import Path
+import json
+import shutil
+
+from higpertext.kernel.config_paths import WORKSPACE_DIR_NAME
+from higpertext.kernel.domain.agent_registry import AgentRecord, SyncResult, IAgentRegistryRepository
+
+# Expuestos para mocking en tests
+try:
+    from higpertext.kernel.application.hook_renderer import HookRenderer
+    from higpertext.kernel.application.skill_hook_compiler import SkillHookCompiler
+except ImportError:
+    HookRenderer = None  # type: ignore
+    SkillHookCompiler = None  # type: ignore
+
+
+class RegisterAgentUseCase:
+    def __init__(self, repo: IAgentRegistryRepository) -> None:
+        self._repo = repo
+
+    def execute(self, name: str, path: str, profile: str) -> AgentRecord:
+        if not Path(path).exists():
+            raise ValueError(f"path does not exist: {path}")
+        if self._repo.find_by_name(name) is not None:
+            raise ValueError(f"Agent '{name}' already registered")
+        record = AgentRecord(
+            name=name,
+            path=path,
+            profile=profile,
+            registered_at=datetime.now(tz=timezone.utc).isoformat(),
+        )
+        agents = self._repo.load()
+        self._repo.save([*agents, record])
+        return record
+
+
+class ListAgentsUseCase:
+    def __init__(self, repo: IAgentRegistryRepository) -> None:
+        self._repo = repo
+
+    def execute(self) -> list[AgentRecord]:
+        return self._repo.load()
+
+
+class SyncAgentUseCase:
+    def __init__(self, repo: IAgentRegistryRepository, engine_root: Path) -> None:
+        self._repo = repo
+        self._engine_root = engine_root
+
+    def execute(self, name: str | None, assistant: str) -> list[SyncResult]:
+        agents = self._repo.load()
+        targets = [a for a in agents if name is None or a.name == name]
+        return [self._sync_one(rec, assistant) for rec in targets]
+
+    def _sync_one(self, rec: AgentRecord, assistant: str) -> SyncResult:
+        try:
+            agent_path = Path(rec.path)
+            caps = self._read_capabilities(rec.profile)
+            self._seed_hook_definitions(agent_path)
+            if SkillHookCompiler and HookRenderer:
+                SkillHookCompiler(agent_path).compile(rec.profile, caps)
+                HookRenderer(agent_path).render(assistant, rec.profile)
+            self._copy_profile(rec.profile, agent_path)
+            return SyncResult(name=rec.name, success=True, message="ok")
+        except Exception as exc:
+            return SyncResult(name=rec.name, success=False, message=str(exc))
+
+    def _seed_hook_definitions(self, agent_path: Path) -> None:
+        """Copia las definiciones de hooks del motor al hooks_config del agente."""
+        motor_cfg = self._engine_root / WORKSPACE_DIR_NAME / "config" / "hooks_config.json"
+        agent_cfg = agent_path / WORKSPACE_DIR_NAME / "config" / "hooks_config.json"
+        if not motor_cfg.exists() or not agent_cfg.exists():
+            return
+        try:
+            motor_data = json.loads(motor_cfg.read_text(encoding="utf-8"))
+            agent_data = json.loads(agent_cfg.read_text(encoding="utf-8"))
+            agent_data["hooks"] = motor_data.get("hooks", [])
+            agent_cfg.write_text(
+                json.dumps(agent_data, indent=2, ensure_ascii=False), encoding="utf-8"
+            )
+        except (OSError, json.JSONDecodeError):
+            pass
+
+    def _read_capabilities(self, profile: str) -> list[str]:
+        prof_file = self._engine_root / "src" / "config" / "profiles" / f"{profile}.json"
+        if not prof_file.exists():
+            return []
+        try:
+            data = json.loads(prof_file.read_text(encoding="utf-8"))
+            return data.get("capabilities", [])
+        except (OSError, json.JSONDecodeError):
+            return []
+
+    def _copy_profile(self, profile: str, agent_path: Path) -> None:
+        src = self._engine_root / "src" / "config" / "profiles" / f"{profile}.json"
+        if not src.exists():
+            return
+        dest_dir = agent_path / "src" / "config" / "profiles"
+        dest_dir.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(src, dest_dir / f"{profile}.json")

higpertext/kernel/application/capability_manager.py

@@ -0,0 +1,61 @@
+"""higpertext Capability Manager — loads and lists capability definitions (Application)."""
+from higpertext.kernel.config_paths import WORKSPACE_DIR_NAME
+
+import os
+import json
+from pathlib import Path
+
+
+class CapabilityManager:
+    def __init__(self, capabilities_dir: Path):
+        self.capabilities_dir = capabilities_dir
+
+    def _get_custom_capabilities_dir(self) -> Path:
+        project_root = Path(os.getcwd()).resolve()
+        return project_root / WORKSPACE_DIR_NAME / "capabilities"
+
+    def _get_all_capability_files(self) -> list:
+        files = list(self.capabilities_dir.rglob("*.json"))
+        custom_dir = self._get_custom_capabilities_dir()
+        if custom_dir.exists():
+            files.extend(custom_dir.rglob("*.json"))
+        return files
+
+    def load_capability(self, capability_id: str) -> dict:
+        custom_dir = self._get_custom_capabilities_dir()
+        for file in self._get_all_capability_files():
+            try:
+                with open(file, "r", encoding="utf-8") as f:
+                    cap = json.load(f)
+                    if (
+                        cap.get("id") == capability_id
+                        or cap.get("id", "").split(".")[-1] == capability_id
+                    ):
+                        # Anota el directorio base para resolución de entrypoint
+                        if custom_dir in file.parents:
+                            cap.setdefault("_base_dir", str(file.parent))
+                        return cap
+            except json.JSONDecodeError:
+                continue
+        raise FileNotFoundError(f"Capacidad no encontrada: {capability_id}")
+
+    def list_capabilities(self) -> list:
+        caps = []
+        for file in self._get_all_capability_files():
+            try:
+                with open(file, "r", encoding="utf-8") as f:
+                    cap = json.load(f)
+                    caps.append({"id": cap.get("id"), "name": cap.get("name")})
+            except json.JSONDecodeError:
+                continue
+        return caps
+
+    def get_all_capabilities_data(self) -> list:
+        caps = []
+        for file in self._get_all_capability_files():
+            try:
+                with open(file, "r", encoding="utf-8") as f:
+                    caps.append(json.load(f))
+            except json.JSONDecodeError:
+                continue
+        return caps