maestro-skills 0.1.1

package/skills/maestro/scripts/routing.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""P0-P3 routing decisions for maestro skill matches."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+AUTO_LOAD_CONFIDENCE = 0.22
+OPTIONAL_LOAD_CONFIDENCE = 0.12
+REFERENCE_BM25_SCORE = 8.0
+
+HIGH_RISK_PATTERNS = [
+    r"config\b", r"\.env", r"auth", r"delete", r"remove", r"rm\s",
+    r"push\s+--force", r"deploy", r"secret", r"password", r"token",
+    r"excluir", r"remover", r"deletar", r"deploy", r"producao", r"produção",
+    r"\bPOST\b", r"\bPUT\b", r"\bDELETE\b",
+]
+
+VALID_MODES = {"auto-load", "recommend", "bypass"}
+
+
+def bm25_to_confidence(score: float) -> float:
+    """Map BM25 score to 0-1 confidence without external calibration."""
+    if score <= 0:
+        return 0.0
+    return min(1.0, score / REFERENCE_BM25_SCORE)
+
+
+def is_high_risk(task: str) -> bool:
+    task_lower = task.lower()
+    return any(re.search(pat, task_lower, re.IGNORECASE) for pat in HIGH_RISK_PATTERNS)
+
+
+def select_mode(
+    confidence: float,
+    high_risk: bool,
+    suggested_mode: str = "",
+    bypass: bool = False,
+) -> str:
+    if bypass:
+        return "bypass"
+    if high_risk:
+        return "recommend"
+    if suggested_mode in VALID_MODES:
+        return suggested_mode
+    if confidence >= AUTO_LOAD_CONFIDENCE:
+        return "auto-load"
+    if confidence >= OPTIONAL_LOAD_CONFIDENCE:
+        return "recommend"
+    return "recommend"
+
+
+def build_routing(
+    task: str,
+    matches: list[dict[str, Any]],
+    high_risk: bool,
+    bypass: bool = False,
+) -> dict[str, Any]:
+    if bypass or not matches:
+        return {
+            "priority": "P3",
+            "decision": "bypass",
+            "reason": "Simple or answer-only task; proceed without skill routing.",
+            "load_limit": 0,
+            "report_policy": "silent",
+        }
+
+    if high_risk:
+        return {
+            "priority": "P0",
+            "decision": "recommend",
+            "reason": "High-risk task; confirm before side effects.",
+            "load_limit": 1,
+            "report_policy": "report",
+        }
+
+    top = matches[0]
+    confidence = float(top.get("confidence", 0))
+    mode = str(top.get("mode", "recommend"))
+
+    if mode == "auto-load" and confidence >= AUTO_LOAD_CONFIDENCE:
+        return {
+            "priority": "P1",
+            "decision": "auto-load",
+            "reason": "Strong workflow match.",
+            "load_limit": 3,
+            "report_policy": "silent",
+        }
+
+    if confidence >= OPTIONAL_LOAD_CONFIDENCE:
+        return {
+            "priority": "P2",
+            "decision": "optional-load",
+            "reason": "Medium confidence; use skill only if it changes execution.",
+            "load_limit": 2,
+            "report_policy": "silent",
+        }
+
+    return {
+        "priority": "P3",
+        "decision": "bypass",
+        "reason": "No strong installed skill match.",
+        "load_limit": 0,
+        "report_policy": "silent",
+    }

package/skills/maestro/scripts/search_skills.py

@@ -0,0 +1,287 @@
+#!/usr/bin/env python3
+"""Hybrid BM25 + intent routing search for maestro (manifest-only, fast)."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+sys.path.insert(0, str(SCRIPT_DIR))
+
+from bm25 import BM25  # noqa: E402
+from concept_gaps import build_discover_queries, find_concept_gaps  # noqa: E402
+from domains import DOMAINS, HUB_SKILLS, classify_query, domain_label  # noqa: E402
+from intents import apply_intent_boost, is_bypass_task, is_force_discover, task_intents  # noqa: E402
+from routing import (  # noqa: E402
+    bm25_to_confidence,
+    build_routing,
+    is_high_risk,
+    select_mode,
+)
+from maestro_paths import LEGACY_MANIFEST_PATH, MANIFEST_PATH  # noqa: E402
+from synonyms import expand_query  # noqa: E402
+
+
+def default_manifest_path() -> Path:
+    if MANIFEST_PATH.is_file():
+        return MANIFEST_PATH
+    if LEGACY_MANIFEST_PATH.is_file():
+        return LEGACY_MANIFEST_PATH
+    return MANIFEST_PATH
+
+
+DEFAULT_MANIFEST = default_manifest_path()
+WEAK_SCORE_THRESHOLD = 1.5
+WEAK_SPREAD_RATIO = 0.10
+DEFAULT_MAX_RESULTS = 5
+
+
+def load_manifest(path: Path) -> dict:
+    if not path.is_file():
+        raise FileNotFoundError(
+            f"Manifest not found: {path}. Run: python build_manifest.py"
+        )
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def skill_document(skill: dict[str, Any]) -> str:
+    tags = skill.get("tags") or []
+    tag_text = " ".join(str(t) for t in tags) if isinstance(tags, list) else str(tags)
+    return (
+        f"{skill['name']} {skill.get('folder', '')} "
+        f"{skill.get('description', '')} {tag_text} {skill.get('domain', '')}"
+    )
+
+
+def build_discover(
+    query: str,
+    results: list[dict[str, Any]],
+    pool: list[dict[str, Any]],
+    *,
+    weak: bool,
+    force_discover: bool,
+    bypass: bool,
+    domain: str,
+) -> dict[str, Any]:
+    if bypass:
+        return {
+            "triggered": False,
+            "reasons": [],
+            "force_discover": False,
+            "gaps": [],
+            "gap_notes": [],
+            "queries": [],
+            "local_fallback": None,
+        }
+
+    gaps, gap_notes = find_concept_gaps(
+        query, results, pool, skill_document, expand_query
+    )
+
+    reasons: list[str] = []
+    if force_discover:
+        reasons.append("force_discover")
+    if weak:
+        reasons.append("weak_match")
+    if len(results) == 1 and (
+        weak or results[0]["score"] < WEAK_SCORE_THRESHOLD
+    ):
+        reasons.append("single_local_skill")
+    if gaps:
+        reasons.append("concept_gap")
+
+    triggered = bool(reasons)
+    queries: list[str] = []
+    if gaps:
+        queries = build_discover_queries(gaps, query, domain)
+    elif triggered:
+        queries = [query]
+
+    local_fallback: dict[str, str] | None = None
+    if results:
+        local_fallback = {
+            "name": str(results[0]["name"]),
+            "path": str(results[0].get("path", "")),
+        }
+
+    return {
+        "triggered": triggered,
+        "reasons": reasons,
+        "force_discover": force_discover,
+        "gaps": gaps,
+        "gap_notes": gap_notes,
+        "queries": queries,
+        "local_fallback": local_fallback,
+    }
+
+
+def search_skills(
+    query: str,
+    manifest: dict,
+    domain: str | None = None,
+    max_results: int = DEFAULT_MAX_RESULTS,
+    include_hubs: bool = True,
+) -> dict:
+    skills = manifest.get("skills", [])
+    if not skills:
+        return {"error": "empty_manifest", "query": query}
+
+    bypass = is_bypass_task(query)
+    high_risk = is_high_risk(query)
+    force_discover = is_force_discover(query)
+    intents = task_intents(query)
+    expanded_query = expand_query(query)
+
+    detected_domain, domain_scores = classify_query(query)
+    active_domain = domain or detected_domain
+
+    pool = skills
+    if active_domain != "general":
+        domain_pool = [s for s in skills if s.get("domain") == active_domain]
+        if len(domain_pool) >= 3:
+            pool = domain_pool
+
+    documents = [skill_document(s) for s in pool]
+    bm25 = BM25()
+    bm25.fit(documents)
+    ranked = bm25.score(expanded_query)
+
+    results: list[dict[str, Any]] = []
+    for idx, score in ranked:
+        if score <= 0:
+            continue
+        skill = pool[idx]
+        if not include_hubs and skill["name"] in HUB_SKILLS:
+            continue
+
+        skill_text = skill_document(skill)
+        adjusted, intent_boosts, suggested_mode = apply_intent_boost(
+            score, skill["name"], skill_text, intents
+        )
+        confidence = bm25_to_confidence(adjusted)
+        mode = select_mode(confidence, high_risk, suggested_mode, bypass=bypass)
+
+        entry: dict[str, Any] = {
+            **skill,
+            "score": round(adjusted, 4),
+            "bm25_score": round(score, 4),
+            "confidence": round(confidence, 3),
+            "mode": mode,
+            "installed": True,
+        }
+        if intent_boosts:
+            entry["intent_boosts"] = intent_boosts
+        results.append(entry)
+
+    results.sort(key=lambda item: item["score"], reverse=True)
+    results = results[:max_results]
+
+    routing = build_routing(query, results, high_risk, bypass=bypass)
+
+    weak = False
+    weak_reasons: list[str] = []
+    if not results and not bypass:
+        weak = True
+        weak_reasons.append("no_results")
+    elif results:
+        top = results[0]["score"]
+        if top < WEAK_SCORE_THRESHOLD:
+            weak = True
+            weak_reasons.append("low_top_score")
+        if len(results) >= 3:
+            third = results[2]["score"]
+            if top > 0 and (top - third) / top < WEAK_SPREAD_RATIO:
+                weak = True
+                weak_reasons.append("tight_spread")
+
+    discover = build_discover(
+        query,
+        results,
+        pool,
+        weak=weak,
+        force_discover=force_discover,
+        bypass=bypass,
+        domain=active_domain,
+    )
+
+    return {
+        "query": query,
+        "expanded_query": expanded_query,
+        "domain": active_domain,
+        "domain_label": domain_label(active_domain),
+        "detected_domain": detected_domain,
+        "domain_scores": domain_scores,
+        "available_domains": DOMAINS,
+        "weak_match": weak,
+        "weak_reasons": weak_reasons,
+        "high_risk": high_risk,
+        "routing": routing,
+        "count": len(results),
+        "results": results,
+        "discover": discover,
+    }
+
+
+def format_text(payload: dict) -> str:
+    if "error" in payload:
+        return f"Error: {payload['error']}"
+
+    routing = payload.get("routing", {})
+    lines = [
+        f"Domain: {payload['domain_label']} ({payload['domain']})",
+        f"Query: {payload['query']}",
+        f"Routing: {routing.get('priority')} / {routing.get('decision')}",
+        f"Weak match: {payload['weak_match']}",
+    ]
+    if payload.get("weak_reasons"):
+        lines.append(f"Weak reasons: {', '.join(payload['weak_reasons'])}")
+
+    discover = payload.get("discover", {})
+    if discover.get("triggered"):
+        lines.append(f"Discover: {', '.join(discover.get('reasons', []))}")
+        if discover.get("gaps"):
+            lines.append(f"Concept gaps: {', '.join(discover['gaps'])}")
+        if discover.get("queries"):
+            lines.append(f"Find queries: {', '.join(discover['queries'])}")
+
+    lines.append("")
+    for i, skill in enumerate(payload.get("results", []), 1):
+        lines.append(
+            f"{i}. {skill['name']} (score={skill['score']}, "
+            f"confidence={skill.get('confidence')}, mode={skill.get('mode')})"
+        )
+        lines.append(f"   path: {skill['path']}")
+
+    return "\n".join(lines)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Search skills for maestro")
+    parser.add_argument("query", help="User prompt to match against skills")
+    parser.add_argument("--domain", default=None, choices=DOMAINS)
+    parser.add_argument("--max-results", type=int, default=DEFAULT_MAX_RESULTS)
+    parser.add_argument("--manifest", default=str(DEFAULT_MANIFEST))
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args()
+
+    manifest = load_manifest(Path(args.manifest))
+    payload = search_skills(
+        args.query,
+        manifest,
+        domain=args.domain,
+        max_results=args.max_results,
+    )
+
+    if args.json:
+        print(json.dumps(payload, indent=2, ensure_ascii=False))
+    else:
+        print(format_text(payload))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/maestro/scripts/synonyms.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+"""Query expansion synonyms for maestro skill search (EN + PT partial)."""
+
+from __future__ import annotations
+
+import re
+
+DEFAULT_SYNONYMS: dict[str, list[str]] = {
+    "test": ["teste", "testes", "unitario", "unittest", "falhando", "failing"],
+    "debug": ["depurar", "depuracao", "bug", "erro", "root cause", "raiz", "falha"],
+    "build": ["compilar", "build", "construir"],
+    "review": ["revisar", "revisao", "code review", "auditoria"],
+    "audit": ["auditoria", "auditar"],
+    "design": ["design", "ui", "ux", "interface", "layout", "visual"],
+    "dashboard": ["painel", "dashboard", "grafico"],
+    "security": ["seguranca", "cybersecurity", "infosec"],
+    "forensics": ["forense", "forensics", "volatility", "memoria"],
+    "deploy": ["deploy", "publicar", "implantar"],
+    "github": ["git", "pull request", "pr", "ci", "actions"],
+    "docs": ["documentacao", "readme", "documentar"],
+    "auth": ["autenticacao", "login", "oauth"],
+    "skill": ["skill", "habilidade"],
+    "superdesign": ["superdesign", "design system"],
+}
+
+
+def expand_query(text: str, extra: dict[str, list[str]] | None = None) -> str:
+    """Append canonical terms when synonym phrases appear in the query."""
+    synonyms = {**DEFAULT_SYNONYMS, **(extra or {})}
+    lowered = text.lower()
+    tokens = set(re.findall(r"[a-z0-9]{3,}", lowered))
+    extra_terms: list[str] = []
+
+    for canonical, values in synonyms.items():
+        canon = canonical.lower()
+        if canon in tokens or canon in lowered:
+            extra_terms.append(canon)
+            continue
+        for value in values:
+            value_text = value.lower().strip()
+            if value_text and value_text in lowered:
+                extra_terms.append(canon)
+                break
+
+    if not extra_terms:
+        return text
+    return f"{text} {' '.join(sorted(set(extra_terms)))}"

package/templates/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,34 @@
+name: Bug
+description: Algo quebrou ou comportamento incorreto
+title: "fix(escopo): "
+labels: ["tipo: bug"]
+body:
+  - type: markdown
+    attributes:
+      value: Descreva o problema com passos para reproduzir.
+  - type: textarea
+    id: descricao
+    attributes:
+      label: Descricao
+      description: O que acontece vs o esperado?
+    validations:
+      required: true
+  - type: textarea
+    id: reproduzir
+    attributes:
+      label: Passos para reproduzir
+      placeholder: |
+        1. Passo um
+        2. Passo dois
+    validations:
+      required: true
+  - type: dropdown
+    id: prioridade
+    attributes:
+      label: Prioridade
+      options:
+        - alta
+        - media
+        - baixa
+    validations:
+      required: true

package/templates/.github/ISSUE_TEMPLATE/chore.yml

@@ -0,0 +1,17 @@
+name: Chore
+description: Docs, CI, refactor, dependencias
+title: "chore(escopo): "
+labels: ["tipo: chore"]
+body:
+  - type: textarea
+    id: tarefa
+    attributes:
+      label: O que fazer
+    validations:
+      required: true
+  - type: textarea
+    id: motivo
+    attributes:
+      label: Por que
+    validations:
+      required: true

package/templates/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

package/templates/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,27 @@
+name: Feature
+description: Nova funcionalidade ou melhoria
+title: "feat(escopo): "
+labels: ["tipo: feature"]
+body:
+  - type: markdown
+    attributes:
+      value: Defina objetivo, escopo e o que fica fora.
+  - type: textarea
+    id: objetivo
+    attributes:
+      label: Objetivo
+    validations:
+      required: true
+  - type: textarea
+    id: escopo
+    attributes:
+      label: Escopo (checklist)
+      placeholder: |
+        - [ ] Item 1
+        - [ ] Item 2
+    validations:
+      required: true
+  - type: textarea
+    id: fora
+    attributes:
+      label: Fora de escopo

package/templates/.github/workflows/ci-failure-to-issue.yml

@@ -0,0 +1,47 @@
+name: CI falha → Issue
+
+on:
+  workflow_run:
+    workflows: [CI]
+    types: [completed]
+
+permissions:
+  issues: write
+
+jobs:
+  abrir-issue:
+    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v7
+        with:
+          script: |
+            const run = context.payload.workflow_run;
+            const title = `ci: falha no workflow ${run.name} (${run.head_branch})`;
+            const body = [
+              'Pipeline CI falhou. Corrija e reabra o PR ate ficar verde.',
+              '',
+              `- **Workflow:** ${run.name}`,
+              `- **Branch:** ${run.head_branch}`,
+              `- **Commit:** ${run.head_sha}`,
+              `- **Run:** ${run.html_url}`,
+              '',
+              'Label sugerida: `ci:falha`'
+            ].join('\n');
+
+            const { data: existing } = await github.rest.search.issuesAndPullRequests({
+              q: `repo:${context.repo.owner}/${context.repo.repo} is:issue is:open label:ci:falha "${run.head_branch}" in:title`
+            });
+
+            if (existing.total_count > 0) {
+              core.info('Issue aberta ja existe para esta branch.');
+              return;
+            }
+
+            await github.rest.issues.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              title,
+              body,
+              labels: ['ci:falha', 'tipo: chore']
+            });

package/templates/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Rodar testes
+        run: |
+          echo "Substitua por: npm test, pytest, go test ./..., etc."
+          exit 0
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build
+        run: |
+          echo "Substitua por: npm run build, docker build, etc."
+          exit 0

package/templates/CONTRIBUTING.md

@@ -0,0 +1,22 @@
+# Contribuicao — fluxo Issues + PR
+
+## Regra geral
+
+1. Abra ou referencie uma **Issue** descrevendo objetivo e escopo.
+2. Crie branch `feat/<numero>-<slug>` ou `fix/<numero>-<slug>`.
+3. Commits descritivos: `tipo(escopo): descricao` + `Refs #N` ou `Closes #N`.
+4. Abra **PR draft**; quando CI e testes locais passarem, marque ready for review.
+5. Merge na branch principal fecha a Issue (`Closes #N` no PR).
+
+## CI — ordem obrigatoria
+
+O pipeline roda **testes primeiro**, depois **build**. Se falhar:
+
+- O PR nao deve ser mergeado.
+- Abra ou atualize Issue com label `ci:falha` ate ficar verde.
+
+## Project (opcional)
+
+Se o time usar GitHub Projects, vincule Issues e PRs ao board do projeto.
+
+Colunas sugeridas: Backlog → Em progresso → Em review → Concluido.

package/templates/labels.json

@@ -0,0 +1,12 @@
+[
+  { "name": "tipo: bug", "color": "E84C3D", "description": "Correcao de erro" },
+  { "name": "tipo: feature", "color": "3D8BF7", "description": "Nova funcionalidade" },
+  { "name": "tipo: docs", "color": "737373", "description": "Documentacao" },
+  { "name": "tipo: chore", "color": "163475", "description": "Manutencao, deps, CI" },
+  { "name": "prioridade: alta", "color": "F4B30F", "description": "Bloqueia operacao" },
+  { "name": "prioridade: media", "color": "66C94B", "description": "Importante, nao urgente" },
+  { "name": "prioridade: baixa", "color": "EDF2F8", "description": "Pode esperar" },
+  { "name": "ci:falha", "color": "E84C3D", "description": "Pipeline CI falhou — corrigir antes do merge" },
+  { "name": "status: em-progresso", "color": "3D8BF7", "description": "Em desenvolvimento" },
+  { "name": "status: em-review", "color": "F4B30F", "description": "PR aberto aguardando merge" }
+]

package/templates/pull_request_template.md

@@ -0,0 +1,18 @@
+## Resumo
+
+<!-- O que mudou e por que (1-3 frases) -->
+
+## Issue
+
+Closes #
+
+## Checklist
+
+- [ ] Branch `feat/<numero>-<slug>` ou `fix/<numero>-<slug>` (nunca commit direto na branch principal)
+- [ ] Testes locais passaram **antes** do build
+- [ ] CI verde (job `test` antes do `build`)
+- [ ] Docs atualizadas se mudou API, comando ou regra de negocio
+
+## Como testar
+
+<!-- Comandos ou passos manuais -->