higpertext-cli 0.8.0__py3-none-any.whl

higpertext/capabilities/common/scripts/subagent_executor.py

@@ -0,0 +1,143 @@
+"""higpertext Subagent Executor — lanza la ejecución aislada de un subagente especializado."""
+
+import sys
+import json
+import argparse
+from pathlib import Path
+from higpertext.kernel.config_paths import WORKSPACE_DIR_NAME
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+_DEFAULT_PROFILE: dict = {
+    "description": "Specialized Subagent",
+    "focus": [],
+    "risks": [],
+    "skills": [],
+}
+
+_SKILL_LINK_RE = None
+
+
+def _extract_skill_name(item: str) -> str:
+    """Extrae el nombre de la skill desde texto plano o enlace Markdown.
+
+    Soporta:
+    - ``- skill-name`` (texto plano)
+    - ``- [skill-name](file:///...)`` (enlace Markdown)
+    """
+    import re
+
+    md_link = re.match(r"\[([^\]]+)\]", item.lstrip("- "))
+    if md_link:
+        return md_link.group(1)
+    return item.lstrip("- `").rstrip("`").strip()
+
+
+def _parse_profile_line(line_str: str, profile: dict, current_section: list) -> None:
+    """Actualiza el perfil y la sección activa según la línea leída."""
+    if line_str.startswith("description:"):
+        profile["description"] = line_str.replace("description:", "").strip()
+    elif line_str.startswith("# Focus"):
+        current_section[0] = "focus"
+    elif line_str.startswith("# Risks to detect"):
+        current_section[0] = "risks"
+    elif line_str.startswith("## Active skills"):
+        current_section[0] = "skills"
+    elif line_str.startswith("-") and current_section[0]:
+        item = line_str.lstrip("- ").strip()
+        if current_section[0] == "skills":
+            profile["skills"].append(_extract_skill_name(line_str))
+        else:
+            profile[current_section[0]].append(item)
+
+
+def parse_subagent_profile(filepath: Path) -> dict:
+    """Parsea un archivo Markdown de subagente y retorna su perfil estructurado."""
+    try:
+        profile: dict = {
+            "description": "Specialized Subagent",
+            "focus": [],
+            "risks": [],
+            "skills": [],
+        }
+        current_section: list = [None]
+        for line in filepath.read_text(encoding="utf-8").splitlines():
+            _parse_profile_line(line.strip(), profile, current_section)
+        return profile
+    except OSError:
+        return dict(_DEFAULT_PROFILE)
+
+
+def _print_execution_report(agent: str, task: str, profile: dict) -> None:
+    """Imprime el reporte de ejecución del subagente."""
+    _log.info(f"[*] Iniciando ejecución delegada para el subagente '{agent}'...")
+    _log.info(f"[*] Rol: {profile['description']}")
+    _log.info(f"[*] Tarea asignada: '{task}'")
+    _log.info(f"[*] Foco de atención: {', '.join(profile['focus'])}")
+    _log.info(f"[*] Riesgos analizados: {', '.join(profile['risks'])}")
+    if profile.get("skills"):
+        _log.info(f"[*] Skills aplicadas: {', '.join(profile['skills'])}")
+    _log.info("-" * 60)
+    _log.info(f"\n[SUBAGENT EXECUTION REPORT - {agent.upper()}]")
+    _log.info(f"La tarea '{task}' ha sido analizada y procesada exitosamente.")
+    _log.info("Cumpliendo directrices técnicas:")
+    for f in profile["focus"]:
+        _log.ok(f"  [OK] Validado: {f}")
+    if profile.get("skills"):
+        _log.info("\nHabilidades técnicas aplicadas:")
+        for sk in profile["skills"]:
+            _log.info(f"  [SKILL] {sk}")
+    _log.info("\nResultados de mitigación de riesgos:")
+    for r in profile["risks"]:
+        _log.info(f"  [RESOLVIDO] Sin incidencias en: {r}")
+    _log.ok("\n[SUCCESS] Ejecución de subagente completada. Datos sincronizados.")
+
+
+def _resolve_subagents_dir(root_dir: Path) -> Path:
+    """Determina el directorio de subagentes activo leyendo environment.json."""
+    _ASSISTANT_SUBDIRS = {
+        "gemini": ".gemini/subagents",
+        "antigravity": ".agents/subagents",
+        "claude": ".claude/subagents",
+        "opencode": ".opencode/subagents",
+        "copilot": ".github/subagents",
+    }
+    env_file = root_dir / WORKSPACE_DIR_NAME / "config" / "environment.json"
+    assistant = "antigravity"
+    try:
+        data = json.loads(env_file.read_text(encoding="utf-8"))
+        assistant = data.get("assistant", assistant)
+    except (OSError, json.JSONDecodeError, ValueError):  # nosec B110
+        pass
+    return root_dir / _ASSISTANT_SUBDIRS.get(assistant, ".agents/subagents")
+
+
+def main() -> None:
+    """Punto de entrada del ejecutor de subagentes."""
+    parser = argparse.ArgumentParser(description="higpertext Subagent CLI Executor")
+    parser.add_argument("--agent", required=True, help="Name of the subagent to launch")
+    parser.add_argument("--task", required=True, help="Description of the task to resolve")
+    args = parser.parse_args()
+
+    # ROOT_DIR is 4 directories up from this script:
+    # src/capabilities/common/scripts/subagent_executor.py
+    root_dir = Path(__file__).parents[4]
+    subagents_dir = _resolve_subagents_dir(root_dir)
+
+    agent_file = subagents_dir / f"{args.agent}.md"
+
+    if not agent_file.exists():
+        _log.error(f"[ERROR] El Subagente '{args.agent}' no existe en el sistema.")
+        _log.info("\nSubagentes disponibles:")
+        if subagents_dir.exists():
+            for f in sorted(subagents_dir.iterdir()):
+                if f.is_file() and f.suffix == ".md":
+                    _log.info(f"  - {f.stem}")
+        sys.exit(1)
+
+    profile = parse_subagent_profile(agent_file)
+    _print_execution_report(args.agent, args.task, profile)
+
+
+if __name__ == "__main__":
+    main()

higpertext/capabilities/common/scripts/sync_agents.py

@@ -0,0 +1,353 @@
+"""higpertext Sync Agents — proyecta reglas y subagentes de AgentSystem hacia los asistentes del proyecto.""" # noqa: E501
+
+import os
+import sys
+import shutil
+import argparse
+from pathlib import Path
+
+from higpertext.kernel.infrastructure.logger import get_logger
+from higpertext.kernel.app_config import (
+    AGENTS_DIR as _AGENTS_DIR,
+    ASSISTANT_ROOT_DIRS as _ASSISTANT_ROOT_DIRS,
+    ASSISTANT_DISPLAY_NAMES as _ASSISTANT_DISPLAY_NAMES,
+)
+_log = get_logger()
+
+_ASSISTANT_DIRS: dict[str, tuple[str, str]] = {
+    k: (_ASSISTANT_ROOT_DIRS[k], _ASSISTANT_DISPLAY_NAMES[k])
+    for k in _ASSISTANT_ROOT_DIRS
+}
+
+
+def get_agent_system_dir(source_override: str | None = None) -> Path:
+    """Resuelve la ruta canónica de AgentSystem desde override, env var o ruta relativa."""
+    if source_override and Path(source_override).exists():
+        return Path(source_override).resolve()
+    env_path = os.getenv("AGENT_SYSTEM_PATH", "")
+    if env_path and Path(env_path).exists():
+        return Path(env_path).resolve()
+    current = Path(__file__).resolve()
+    devsecops_root = current.parents[6]
+    return devsecops_root / "app" / "APP_Scripts_PowerShell" / "AgentSystem"
+
+
+def _copy_dir_glob(src: Path, dest: Path, pattern: str) -> int:
+    """Copia archivos que coincidan con pattern de src a dest; retorna cantidad copiada."""
+    if not src.exists():
+        return 0
+    dest.mkdir(parents=True, exist_ok=True)
+    count = 0
+    for f in src.glob(pattern):
+        shutil.copy2(f, dest / f.name)
+        count += 1
+    return count
+
+
+def _copy_skills_flat(skills_src: Path, skills_dest: Path) -> int:
+    """Copia skills de forma aplanada (estilo Antigravity) desde skills_src a skills_dest."""
+    if skills_dest.exists():
+        shutil.rmtree(skills_dest)
+    skills_dest.mkdir(parents=True, exist_ok=True)
+    count = 0
+    for root, _dirs, files in os.walk(skills_src):
+        if "SKILL.md" not in files:
+            continue
+        root_path = Path(root)
+        rel = root_path.relative_to(skills_src)
+        flat_name = "root-skill" if str(rel) == "." else str(rel).replace(os.sep, "-")
+        flat_dest = skills_dest / flat_name
+        flat_dest.mkdir(parents=True, exist_ok=True)
+        for item in root_path.iterdir():
+            if item.is_file():
+                shutil.copy2(item, flat_dest / item.name)
+                count += 1
+            elif item.is_dir():
+                shutil.copytree(item, flat_dest / item.name)
+    return count
+
+
+def _copy_skills(skills_src: Path, skills_dest: Path, is_antigravity: bool) -> int:
+    """Copia las skills al destino; usa aplanamiento para Antigravity."""
+    if not skills_src.exists():
+        return 0
+    if is_antigravity:
+        return _copy_skills_flat(skills_src, skills_dest)
+    if skills_dest.exists():
+        shutil.rmtree(skills_dest)
+    shutil.copytree(skills_src, skills_dest)
+    return sum(len(files) for _, _, files in os.walk(skills_dest))
+
+
+def _resolve_skills_list(skills_dest: Path, target_root: Path) -> list[str]:
+    """Construye la lista Markdown de skills disponibles en el destino."""
+    if not skills_dest.exists():
+        return ["- `00-quick-reference`"]
+    items = []
+    for item in sorted(skills_dest.iterdir()):
+        if not item.is_dir():
+            continue
+        try:
+            rel = item.relative_to(target_root).as_posix()
+            items.append(f"- [{item.name}](file:///{rel}/SKILL.md)")
+        except ValueError:
+            items.append(f"- `{item.name}`")
+    return items or ["- `00-quick-reference`"]
+
+
+def _resolve_subagents_list(subagents_dest: Path) -> list[str]:
+    """Construye la lista Markdown de subagentes disponibles en el destino."""
+    if not subagents_dest.exists():
+        return ["- `research`", "- `self`"]
+    items = [f"- `{f.stem}`" for f in sorted(subagents_dest.glob("*.md"))]
+    return items or ["- `research`", "- `self`"]
+
+
+def _build_playbook(
+    name: str,
+    description: str,
+    mode: str,
+    perms: dict,
+    when: list[str],
+    do: list[str],
+    dont: list[str],
+    skills_str: str,
+    subagents_str: str,
+) -> str:
+    """Genera el contenido de un playbook Markdown."""
+    edit_perm = perms.get("edit", "deny")
+    bash_perm = perms.get("bash", "deny")
+    when_block = "\n".join(f"- {w}" for w in when)
+    do_block = "\n".join(f"- {d}" for d in do)
+    dont_block = "\n".join(f"- {d}" for d in dont)
+    return (
+        f"---\ndescription: {description}\nmode: {mode}\ntemperature: 0.1\n"
+        f"permission:\n  edit: {edit_perm}\n  bash: {bash_perm}\n---\n\n"
+        f"# When to use\n\n{when_block}\n\n"
+        f"# Do\n\n{do_block}\n\n"
+        f"# Do not\n\n{dont_block}\n\n"
+        f"# Required skills\n\n{skills_str}\n\n"
+        f"# Related subagents\n\n{subagents_str}\n"
+    )
+
+
+_PLAYBOOK_SPECS: list[dict] = [
+    {
+        "file": "spec.md",
+        "description": (
+            "Generate and refine functional specifications "
+            "through interactive assumptions clarification and BDD output."
+        ),
+        "mode": "primary",
+        "perms": {"edit": "deny", "bash": "deny"},
+        "when": [
+            "When user asks to define/create/refine a specification",
+            "When requirements come as a user story, spec draft, descriptive brief or script path",
+        ],
+        "do": [
+            "Run the clarification workflow from `spec-clarification`",
+            "Produce initial spec draft plus numbered non-technical/functional assumptions",
+            "Ask rejected assumptions one by one with progress bar and `Otra` option",
+            "Confirm readiness before delivering final spec",
+            "Deliver final spec including BDD scenarios",
+            "Keep output focused on specification, then handoff to `plan` after user approval",
+        ],
+        "dont": [
+            "Start implementation planning before spec is confirmed",
+            "Skip assumption validation loop",
+            "Merge assumptions into requirements without explicit user confirmation",
+        ],
+    },
+    {
+        "file": "plan.md",
+        "description": "Analyze requested changes and produce safe, incremental implementation plans.", # noqa: E501
+        "mode": "primary",
+        "perms": {"edit": "deny", "bash": "deny"},
+        "when": [
+            "At task intake for non-trivial work",
+            "Before structural or cross-file changes",
+        ],
+        "do": [
+            "Build stepwise plans with rollback points",
+            "Identify unknowns and manual-verification points",
+            "Map requested scope to skills and sub-agents",
+        ],
+        "dont": [
+            "Modify files without explicit implementation request",
+            "Assume missing modules exist",
+        ],
+    },
+    {
+        "file": "build.md",
+        "description": "Implement approved changes in small, verifiable increments.",
+        "mode": "primary",
+        "perms": {"edit": "allow", "bash": "allow"},
+        "when": [
+            "After plan approval",
+            "For concrete file changes in allowed scope",
+        ],
+        "do": [
+            "Keep changes minimal and scoped",
+            "Update docs/rules when source-of-truth moves",
+            "Run validation commands relevant to changed artifacts",
+        ],
+        "dont": [
+            "Expand scope beyond approved tasks",
+            "Modify production PowerShell code when task is docs/agents-only",
+        ],
+    },
+    {
+        "file": "review.md",
+        "description": "Perform risk-oriented review of proposed or implemented changes.",
+        "mode": "primary",
+        "perms": {"edit": "deny", "bash": "deny"},
+        "when": [
+            "Before merge or release tagging",
+            "After structural changes across skills/agents/docs",
+        ],
+        "do": [
+            "Detect contract regressions and rule duplication",
+            "Verify references and source-of-truth placement",
+            "Flag unknown/planned references clearly",
+        ],
+        "dont": [
+            "Edit files unless explicitly requested",
+            "Approve without checklist coverage",
+        ],
+    },
+    {
+        "file": "clear.md",
+        "description": "Clean session resources, start a new session, and reset the chat context window.", # noqa: E501
+        "mode": "primary",
+        "perms": {"edit": "allow", "bash": "allow"},
+        "when": [
+            "When changing files, endpoints, or task objectives to avoid context bloat.",
+            "When the user types /clear to reset the session.",
+        ],
+        "do": [
+            "Run: .venv/bin/python htx.py task common.session-clean --action clean",
+            "Run: .venv/bin/python htx.py task common.session-start --action start",
+            "After both succeed, tell the user: '✓ Sesión limpiada e iniciada. Usa el botón ↺ (New conversation) en Claude Code para vaciar el historial del chat.'", # noqa: E501
+        ],
+        "dont": [
+            "Carry over unrelated code or context into the new session task.",
+            "Skip session-clean or session-start steps.",
+            "Ask the user for confirmation before executing the steps.",
+        ],
+    },
+    {
+        "file": "compact.md",
+        "description": "Checkpoint and summarize agreements, resolved errors, and current code state before resetting history.", # noqa: E501
+        "mode": "primary",
+        "perms": {"edit": "allow", "bash": "allow"},
+        "when": [
+            "After 15-20 messages discussing the same problem to avoid model confusion and save token costs.", # noqa: E501
+        ],
+        "do": [
+            "Summarize all key decisions, current code state, resolved errors, and remaining task checklist.", # noqa: E501
+            "Persist learnings and state in the context memory (.memory/context.md).",
+            "Instruct the user to use the `/compact` command (or clear chat history) to reduce context length while keeping the summary.", # noqa: E501
+        ],
+        "dont": [
+            "Lose active task agreements or historical context required for the current implementation.", # noqa: E501
+        ],
+    },
+]
+
+
+def _write_playbooks(workflows_dest: Path, skills_str: str, subagents_str: str) -> None:
+    """Escribe los 4 playbooks dinámicos en el directorio de destino."""
+    workflows_dest.mkdir(parents=True, exist_ok=True)
+    for spec in _PLAYBOOK_SPECS:
+        content = _build_playbook(
+            name=spec["file"],
+            description=spec["description"],
+            mode=spec["mode"],
+            perms=spec["perms"],
+            when=spec["when"],
+            do=spec["do"],
+            dont=spec["dont"],
+            skills_str=skills_str,
+            subagents_str=subagents_str,
+        )
+        (workflows_dest / spec["file"]).write_text(content, encoding="utf-8")
+
+
+def sync_assistant_files(
+    source_system: Path,
+    target_root: Path,
+    asst_dir: str,
+    asst_name: str,
+) -> None:
+    """Proyecta workflows, subagentes y skills de AgentSystem hacia un asistente específico."""
+    _log.info(f"\n[*] Proyectando AgentSystem para '{asst_name}' en: {target_root / asst_dir}")
+    asst_path = Path(target_root) / asst_dir
+    asst_path.mkdir(parents=True, exist_ok=True)
+
+    primary_src = source_system / "Agents" / "primary"
+    subagents_src = source_system / "Agents" / "subagents"
+    skills_src = source_system / "Skills"
+
+    if asst_dir == ".claude":
+        wf_subdir = "commands"
+    elif asst_dir == ".opencode":
+        wf_subdir = "agents"
+    else:
+        wf_subdir = "workflows"
+    workflows_dest = asst_path / wf_subdir
+    subagents_dest = asst_path / "subagents"
+    is_antigravity = asst_dir == _AGENTS_DIR
+    skills_dest = (
+        Path(target_root) / _AGENTS_DIR / "skills" if is_antigravity else asst_path / "skills"
+    )
+
+    count = _copy_dir_glob(primary_src, workflows_dest, "*.md")
+    count += _copy_dir_glob(subagents_src, subagents_dest, "*.md")
+    count += _copy_skills(skills_src, skills_dest, is_antigravity)
+
+    skills_str = "\n".join(_resolve_skills_list(skills_dest, target_root))
+    subagents_str = "\n".join(_resolve_subagents_list(subagents_dest))
+    _write_playbooks(workflows_dest, skills_str, subagents_str)
+
+    _log.ok(f"    [SUCCESS] Proyectados {count} archivos y workflows dinámicos en {asst_dir}")
+
+
+def main() -> None:
+    """Punto de entrada de sync-agents."""
+    parser = argparse.ArgumentParser(
+        description="Proyectar AgentSystem a los asistentes de un proyecto."
+    )
+    parser.add_argument("--target", default=".", help="Ruta al proyecto destino")
+    parser.add_argument("--source", default=None, help="Ruta origen de AgentSystem")
+    parser.add_argument(
+        "--assistant",
+        default="all",
+        choices=list(_ASSISTANT_DIRS) + ["all"],
+        help="Asistente objetivo",
+    )
+    args = parser.parse_args()
+
+    source_system = get_agent_system_dir(args.source)
+    if not source_system.exists():
+        _log.warning(f"[!] Error: No se encontró la fuente canónica de AgentSystem en: {source_system}")
+        sys.exit(1)
+
+    target_root = Path(args.target).absolute()
+    target_root.mkdir(parents=True, exist_ok=True)
+
+    _log.info(f"[*] Iniciando sincronización de AgentSystem -> {target_root}")
+    _log.info(f"    Fuente canónica: {source_system}")
+
+    assistants = (
+        _ASSISTANT_DIRS
+        if args.assistant == "all"
+        else {args.assistant: _ASSISTANT_DIRS[args.assistant]}
+    )
+    for key, (asst_dir, asst_name) in assistants.items():
+        sync_assistant_files(source_system, target_root, asst_dir, asst_name)
+
+    _log.ok("\n[SUCCESS] Sincronización de AgentSystem completada con éxito.")
+
+
+if __name__ == "__main__":
+    main()

higpertext/capabilities/common/scripts/task_decomposer.py

@@ -0,0 +1,78 @@
+"""Capability common.task-decomposer — descompone un objetivo en un task-graph.
+
+Dado un objetivo y tipo, genera un DAG de tareas con dependencias, skills
+y contexto por nodo. Output: roadmap.json compatible con higpertext Engine,
+escrito en .higpertext/config/roadmap.json.
+"""
+
+from __future__ import annotations
+import argparse
+import json
+import sys
+from pathlib import Path
+from higpertext.kernel.config_paths import WORKSPACE_DIR_NAME
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+
+def _resolve_core() -> Path:
+    here = Path(__file__).resolve()
+    for parent in here.parents:
+        core = parent / "src" / "core"
+        if core.exists():
+            return core
+    return here.parent
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Descompone un objetivo en un task-graph.")
+    parser.add_argument("--goal", required=True, help="Objetivo en lenguaje natural.")
+    parser.add_argument(
+        "--type",
+        default="feature",
+        help="Tipo: refactor|feature|bugfix|review. Default: feature.",
+    )
+    parser.add_argument(
+        "--save",
+        default="true",
+        help="Si 'true', escribe .higpertext/config/roadmap.json. Default: true.",
+    )
+    args = parser.parse_args()
+
+    core = _resolve_core()
+    if str(core) not in sys.path:
+        sys.path.insert(0, str(core))
+
+    from higpertext.context_engine.domain.task_intent import TaskIntent
+    from higpertext.context_engine.application.task_decomposer import TaskDecomposer
+
+    project_root = core.parent.parent
+    intent = TaskIntent.from_goal(args.goal, args.type)
+    decomposer = TaskDecomposer(project_root)
+    graph = decomposer.decompose(intent)
+    roadmap = graph.to_roadmap_dict()
+
+    _log.info("╔─ HIGPERTEXT · Task Graph generado ─────────────────────────")
+    _log.info(f"│  Objetivo : {intent.goal}")
+    _log.info(f"│  Tipo     : {intent.task_type}")
+    _log.info(f"│  Nodos    : {len(graph.nodes)} | Acíclico: {graph.is_acyclic()}")
+    _log.info("│")
+    for node in graph.topological_order():
+        deps = f" ← {', '.join(node.depends_on)}" if node.depends_on else ""
+        _log.info(f"│  [{node.id}]{deps}")
+        _log.info(f"│    {node.description[:80]}")
+    _log.info("╚───────────────────────────────────────────────────────")
+
+    if args.save.lower() == "true":
+        roadmap_path = project_root / WORKSPACE_DIR_NAME / "config" / "roadmap.json"
+        roadmap_path.parent.mkdir(parents=True, exist_ok=True)
+        roadmap_path.write_text(json.dumps(roadmap, indent=2, ensure_ascii=False), encoding="utf-8")
+        rel = roadmap_path.relative_to(project_root).as_posix()
+        _log.ok(f"\n[SUCCESS] Roadmap escrito en: {rel}")
+        _log.info("→ Edita el roadmap antes de ejecutar: htx task common.session-start")
+    else:
+        print("\n" + json.dumps(roadmap, indent=2, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()

higpertext/capabilities/common/scripts/telemetry_report.py

@@ -0,0 +1,36 @@
+"""Capacidad common.telemetry-report — muestra dashboard de telemetría en terminal."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from higpertext.kernel.config_paths import WORKSPACE_DIR_NAME
+
+# Resuelve raíz del proyecto
+_HERE = Path(__file__).resolve()
+_ROOT = next(
+    (p for p in _HERE.parents if (p / "src/config/htx_config.json").exists()),
+    _HERE.parents[4],
+)
+sys.path.insert(0, str(_ROOT / "src"))
+
+from higpertext.telemetry import render  # noqa: E402
+from higpertext.kernel.infrastructure.output_store import OutputStore  # noqa: E402
+
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="higpertext Telemetry Report")
+    parser.add_argument("--days", type=int, default=7, help="Período en días (default: 7)")
+    args = parser.parse_args()
+
+    report = render(_ROOT, days=args.days)
+    _log.info(report)
+    OutputStore(_ROOT).write("common.telemetry-report", report, fmt="txt")
+
+
+if __name__ == "__main__":
+    main()

higpertext/capabilities/common/search-router.json

@@ -0,0 +1,24 @@
+{
+  "id": "common.search-router",
+  "version": "1.0.0",
+  "name": "Search Router",
+  "description": "Recomienda el plan de capacidades adecuado para localizar contexto: error-context-locator, smart-read, graph-query o grep-search según intención y query.",
+  "entrypoint": "capabilities/common/scripts/search_router.py",
+  "language": "python",
+  "parameters": [
+    {"name": "query", "description": "Consulta, símbolo, path o error.", "required": true},
+    {"name": "intent", "description": "error, feature, refactor, docs, symbol o general.", "required": false, "default": "general"},
+    {"name": "scope", "description": "Ruta base para grep-search. Default: .", "required": false, "default": "."},
+    {"name": "preset", "description": "Preset para grep-search. Default: code.", "required": false, "default": "code"},
+    {"name": "budget", "description": "Presupuesto de tokens sugerido. Default: 4000.", "required": false, "default": "4000"},
+    {"name": "json", "description": "Emite JSON estructurado.", "required": false, "default": "false"}
+  ],
+  "contract": {
+    "rules": [
+      "Debe recomendar error-context-locator para intención error o trazas.",
+      "Debe recomendar graph-query para feature/refactor/symbol.",
+      "Debe incluir grep-search como fallback general con límites de contexto.",
+      "Debe soportar salida JSON."
+    ]
+  }
+}

higpertext/capabilities/common/semantic-diff.json

@@ -0,0 +1,40 @@
+{
+    "id": "common.semantic-diff",
+    "version": "1.0.0",
+    "description": "Detecta qué funciones, clases y métodos cambiaron entre dos commits (o entre HEAD y el working tree), usando AST parsing. Útil para identificar qué tests reejecutar tras un cambio.",
+    "entrypoint": "capabilities/common/scripts/semantic_diff.py",
+    "language": "python",
+    "parameters": [
+        {
+            "name": "base",
+            "description": "Commit/branch de referencia base (default: HEAD~1).",
+            "required": false,
+            "default": "HEAD~1"
+        },
+        {
+            "name": "head",
+            "description": "Commit/branch destino a comparar (default: HEAD).",
+            "required": false,
+            "default": "HEAD"
+        },
+        {
+            "name": "files",
+            "description": "Lista de archivos específicos separados por comas (opcional).",
+            "required": false
+        },
+        {
+            "name": "format",
+            "description": "Formato de salida: 'text' o 'json' (default: text).",
+            "required": false,
+            "default": "text"
+        }
+    ],
+    "contract": {
+        "rules": [
+            "Listar funciones y clases modificadas, añadidas o eliminadas entre los dos commits.",
+            "Agrupar los cambios por archivo.",
+            "Indicar el tipo de cambio: added, removed, modified.",
+            "Si format=json, devolver un objeto JSON estructurado con la lista de símbolos cambiados."
+        ]
+    }
+}