maestro-skills 0.1.1

package/skills/maestro/scripts/concept_gaps.py

@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+"""Detect prompt concepts that lack local skill coverage (discover via find-skills)."""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Callable
+
+MAX_DISCOVER_GAPS = 2
+
+STOPWORDS: frozenset[str] = frozenset(
+    {
+        "ui",
+        "ux",
+        "app",
+        "web",
+        "api",
+        "codigo",
+        "código",
+        "alteracao",
+        "alteração",
+        "fazer",
+        "vamos",
+        "projeto",
+        "sistema",
+        "pagina",
+        "página",
+        "tela",
+        "componente",
+        "frontend",
+        "backend",
+        "nova",
+        "novo",
+        "uma",
+        "uns",
+        "the",
+        "and",
+        "for",
+        "with",
+    }
+)
+
+IMPLEMENTATION_VERB_PATTERN = re.compile(
+    r"\b(?:colocar|usar|implementar|adicionar|integrar|instalar|"
+    r"add|use|implement|integrate|install)\s+"
+    r"([a-z][a-z0-9._/-]*)",
+    re.IGNORECASE,
+)
+
+HYPHENATED_PATTERN = re.compile(r"\b([a-z][a-z0-9]*(?:-[a-z0-9]+)+)\b", re.IGNORECASE)
+
+CAMEL_CASE_PATTERN = re.compile(r"\b([a-z]+(?:[A-Z][a-z0-9]+)+)\b")
+
+CONCEPT_GAP_SCORE_THRESHOLD = 1.5
+
+
+def _normalize_term(term: str) -> str:
+    return term.strip().lower().replace("_", "-")
+
+
+def is_stopword(term: str) -> bool:
+    normalized = _normalize_term(term)
+    if len(normalized) < 3:
+        return True
+    if normalized in STOPWORDS:
+        return True
+    parts = normalized.split("-")
+    return len(parts) == 1 and normalized in STOPWORDS
+
+
+def _concept_specificity(term: str) -> int:
+    normalized = _normalize_term(term)
+    score = 0
+    if "-" in normalized:
+        score += 3
+    if any(ch.isupper() for ch in term):
+        score += 2
+    if "." in normalized:
+        score += 2
+    if len(normalized) >= 8:
+        score += 1
+    return score
+
+
+def extract_concept_candidates(query: str) -> list[str]:
+    """Extract salient implementable concepts from the user prompt."""
+    seen: set[str] = set()
+    ordered: list[str] = []
+
+    def add(raw: str) -> None:
+        term = _normalize_term(raw)
+        if not term or is_stopword(term):
+            return
+        if term in seen:
+            return
+        seen.add(term)
+        ordered.append(term)
+
+    for match in IMPLEMENTATION_VERB_PATTERN.finditer(query):
+        add(match.group(1))
+
+    for pattern in (HYPHENATED_PATTERN, CAMEL_CASE_PATTERN):
+        for match in pattern.finditer(query):
+            add(match.group(1))
+
+    ordered.sort(key=_concept_specificity, reverse=True)
+    return ordered
+
+
+def _result_covers_term(term: str, results: list[dict[str, Any]]) -> bool:
+    normalized = _normalize_term(term)
+    compact = normalized.replace("-", "")
+    for skill in results:
+        blob = " ".join(
+            [
+                str(skill.get("name", "")),
+                str(skill.get("folder", "")),
+                str(skill.get("description", "")),
+                " ".join(str(t) for t in (skill.get("tags") or [])),
+            ]
+        ).lower()
+        blob_compact = blob.replace("-", "").replace("_", "")
+        if normalized in blob or compact in blob_compact:
+            return True
+    return False
+
+
+def _top_score_for_term(
+    term: str,
+    pool: list[dict[str, Any]],
+    skill_document: Callable[[dict[str, Any]], str],
+    expand_query: Callable[[str], str],
+) -> float:
+    from bm25 import BM25
+
+    if not pool:
+        return 0.0
+
+    documents = [skill_document(skill) for skill in pool]
+    bm25 = BM25()
+    bm25.fit(documents)
+    ranked = bm25.score(expand_query(term))
+    positive = [score for _, score in ranked if score > 0]
+    return max(positive) if positive else 0.0
+
+
+def find_concept_gaps(
+    query: str,
+    results: list[dict[str, Any]],
+    pool: list[dict[str, Any]],
+    skill_document: Callable[[dict[str, Any]], str],
+    expand_query: Callable[[str], str],
+) -> tuple[list[str], list[str]]:
+    """
+    Return (gaps_for_discover, gap_notes).
+
+    gaps_for_discover: up to MAX_DISCOVER_GAPS concepts needing find-skills.
+    gap_notes: additional concepts beyond the limit (for graph annotations).
+    """
+    candidates = extract_concept_candidates(query)
+    if not candidates:
+        return [], []
+
+    confirmed: list[str] = []
+    for term in candidates:
+        if _result_covers_term(term, results):
+            continue
+        term_score = _top_score_for_term(term, pool, skill_document, expand_query)
+        if term_score >= CONCEPT_GAP_SCORE_THRESHOLD:
+            continue
+        confirmed.append(term)
+
+    gaps = confirmed[:MAX_DISCOVER_GAPS]
+    notes = confirmed[MAX_DISCOVER_GAPS:]
+    return gaps, notes
+
+
+def build_discover_queries(
+    gaps: list[str],
+    full_query: str,
+    domain: str,
+) -> list[str]:
+    """Build npx skills find queries for each concept gap."""
+    context_tokens: list[str] = []
+    if domain and domain not in {"general", "meta"}:
+        context_tokens.append(domain.replace("-", " "))
+    for token in re.findall(r"[a-z]{4,}", full_query.lower()):
+        if token not in STOPWORDS and token not in context_tokens:
+            context_tokens.append(token)
+
+    context = " ".join(context_tokens[:4])
+    queries: list[str] = []
+    for gap in gaps:
+        query = f"{gap} {context}".strip()
+        queries.append(query)
+    return queries

package/skills/maestro/scripts/domains.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""Domain taxonomy and classification for maestro."""
+
+from __future__ import annotations
+
+DOMAINS: list[str] = [
+    "web",
+    "data-viz",
+    "analytics",
+    "design",
+    "creative",
+    "devops-git",
+    "video-media",
+    "integrations",
+    "security",
+    "meta",
+    "general",
+]
+
+DOMAIN_KEYWORDS: dict[str, list[str]] = {
+    "web": [
+        "react", "nextjs", "next.js", "frontend", "backend", "api", "typescript",
+        "javascript", "shadcn", "stripe", "supabase", "postgres", "tailwind",
+        "component", "browser", "testing", "debug", "remix", "vue", "svelte",
+        "html", "css", "web app", "full-stack", "auth", "payment",
+    ],
+    "data-viz": [
+        "chart", "graph", "visualization", "dashboard", "d3", "canvas", "threejs",
+        "geospatial", "map", "gantt", "diagram", "scrollytelling", "plot",
+        "accessibility", "svg", "webgl", "painel",
+    ],
+    "analytics": [
+        "data quality", "kpi", "jupyter", "notebook", "metric", "report",
+        "analytics", "business context", "market sizing", "validate data",
+        "pandas", "sql", "spreadsheet", "excel",
+    ],
+    "design": [
+        "prototype", "ideate", "audit", "design qa", "ux research", "figma",
+        "mockup", "wireframe", "ui", "ux", "product design", "url-to-code",
+        "image-to-code", "user flow", "onboarding", "superdesign", "design system",
+        "interface", "layout",
+    ],
+    "security": [
+        "security", "cybersecurity", "forensics", "malware", "pentest",
+        "penetration", "threat", "incident response", "mitre", "attack",
+        "vulnerability", "siem", "dfir", "red team", "blue team", "seguranca",
+        "forense", "volatility",
+    ],
+    "creative": [
+        "moodboard", "logo", "ads", "brand", "creative", "shot", "scene",
+        "positioning", "offer", "generative polish", "explorer",
+    ],
+    "devops-git": [
+        "github", "git", "pull request", "ci", "cd", "commit", "merge",
+        "workflow", "actions", "yeet", "fix ci", "address comments",
+        "failing check", "actions check", "quebrado", "falhando", "pipeline",
+    ],
+    "video-media": [
+        "remotion", "video", "animation", "render", "composition", "ffmpeg",
+        "media", "audio",
+    ],
+    "integrations": [
+        "twilio", "zoom", "slack", "notion", "airtable", "jira", "linear",
+        "stripe api", "webhook", "oauth", "sdk", "mcp", "salesforce",
+        "hubspot", "intercom",
+    ],
+    "meta": [
+        "skill creator", "skill installer", "plugin creator", "create skill",
+        "openai docs", "imagegen", "context7", "documentation library",
+    ],
+}
+
+NAME_PREFIX_DOMAIN: list[tuple[str, str]] = [
+    ("build-web-data-visualization-", "data-viz"),
+    ("data-analytics-", "analytics"),
+    ("product-design-", "design"),
+    ("creative-production-", "creative"),
+    ("gh-", "devops-git"),
+    ("netlify-", "web"),
+    ("twilio-", "integrations"),
+    ("zoom-", "integrations"),
+    ("figma-", "design"),
+    ("codex-", "meta"),
+]
+
+HUB_SKILLS: set[str] = {
+    "index",
+    "product-design-index",
+    "data-visualization",
+    "build-web-data-visualization-data-visualization",
+    "explore",
+}
+
+
+def _text_blob(name: str, description: str) -> str:
+    return f"{name} {description}".lower()
+
+
+def classify_skill(name: str, description: str) -> str:
+    if name.lower() == "superdesign":
+        return "design"
+
+    blob = _text_blob(name, description)
+    for prefix, domain in NAME_PREFIX_DOMAIN:
+        if name.lower().startswith(prefix):
+            return domain
+
+    scores = {domain: 0 for domain in DOMAINS}
+    for domain, keywords in DOMAIN_KEYWORDS.items():
+        for kw in keywords:
+            if kw in blob:
+                scores[domain] += 1
+
+    best = max(scores, key=scores.get)
+    if scores[best] > 0:
+        return best
+    return "general"
+
+
+def classify_query(query: str) -> tuple[str, dict[str, int]]:
+    query_lower = query.lower()
+    scores = {domain: 0 for domain in DOMAINS}
+    for domain, keywords in DOMAIN_KEYWORDS.items():
+        for kw in keywords:
+            if kw in query_lower:
+                scores[domain] += 1
+
+    best = max(scores, key=scores.get)
+    if scores[best] == 0:
+        return "general", scores
+    return best, scores
+
+
+def domain_label(domain: str) -> str:
+    labels = {
+        "web": "Web / apps",
+        "data-viz": "Data visualization",
+        "analytics": "Data analytics",
+        "design": "Product design",
+        "creative": "Creative production",
+        "devops-git": "Git / CI / DevOps",
+        "video-media": "Video / media",
+        "integrations": "Integrations / SDKs",
+        "security": "Cybersecurity",
+        "meta": "Meta / tooling",
+        "general": "General",
+    }
+    return labels.get(domain, domain)

package/skills/maestro/scripts/intents.py

@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""Workflow intent profiles that boost BM25 matches beyond raw text similarity."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+INTENT_PROFILES: list[dict[str, Any]] = [
+    {
+        "name": "root-cause-debugging",
+        "task_patterns": [
+            r"\b(root[- ]?cause|debug|bug|bugs?|crash|exception|traceback)\b",
+            r"\b(failing tests?|test failures?)\b",
+            r"\b(depurar|depuracao|raiz|falhando|erro|bug)\b",
+        ],
+        "skill_patterns": [
+            r"systematic-debugging",
+            r"root[- ]?cause",
+            r"troubleshooting",
+            r"problem-solving",
+        ],
+        "score_multiplier": 1.45,
+        "min_boost": 1.5,
+        "suggested_mode": "auto-load",
+    },
+    {
+        "name": "frontend-design",
+        "task_patterns": [
+            r"\b(landing page|redesign|ui|frontend|visual design|superdesign)\b",
+            r"\b(dashboard|mockup|wireframe|figma)\b",
+            r"\b(interface|layout|design system)\b",
+        ],
+        "skill_patterns": [
+            r"superdesign",
+            r"shadcn",
+            r"frontend",
+            r"ui-ux",
+            r"design",
+            r"mockup",
+        ],
+        "score_multiplier": 1.4,
+        "min_boost": 1.2,
+        "suggested_mode": "auto-load",
+    },
+    {
+        "name": "devops-ci",
+        "task_patterns": [
+            r"\b(ci|github actions|pull request|pr|pipeline)\b",
+            r"\b(falhando|quebrado|fix ci)\b",
+        ],
+        "skill_patterns": [
+            r"gh-fix-ci",
+            r"github",
+            r"yeet",
+            r"ci",
+        ],
+        "score_multiplier": 1.35,
+        "min_boost": 1.0,
+        "suggested_mode": "auto-load",
+    },
+    {
+        "name": "security-forensics",
+        "task_patterns": [
+            r"\b(forensics|volatility|memory dump|credential|mitre|dfir)\b",
+            r"\b(seguranca|forense|malware|incident)\b",
+        ],
+        "skill_patterns": [
+            r"forensics",
+            r"volatility",
+            r"credential",
+            r"malware",
+            r"incident-response",
+        ],
+        "score_multiplier": 1.5,
+        "min_boost": 2.0,
+        "suggested_mode": "auto-load",
+    },
+    {
+        "name": "skill-discovery",
+        "task_patterns": [
+            r"\bfind (a )?skill\b",
+            r"\bnpx skills\b",
+            r"\bskills\.sh\b",
+            r"\btem skill (para|de)\b",
+            r"\binstalar skill\b",
+            r"\bis there a skill\b",
+            r"\bdiscover (agent )?skills\b",
+        ],
+        "skill_patterns": [
+            r"find-skills",
+            r"create-skill",
+            r"skill-creator",
+            r"skill-installer",
+        ],
+        "score_multiplier": 2.0,
+        "min_boost": 3.0,
+        "suggested_mode": "auto-load",
+    },
+]
+
+FORCE_DISCOVER_PATTERNS: list[str] = [
+    r"\bfind (a )?skill\b",
+    r"\bnpx skills\b",
+    r"\bskills\.sh\b",
+    r"\btem skill (para|de)\b",
+    r"\binstalar skill\b",
+    r"\bis there a skill\b",
+    r"\bdiscover (agent )?skills\b",
+]
+
+BYPASS_PATTERNS = [
+    r"^\s*(hi|hello|hey|oi|ola|olá)\b",
+    r"^\s*(what time|que horas)\b",
+]
+
+
+def matches_any_pattern(text: str, patterns: list[str]) -> bool:
+    return any(re.search(pattern, text, re.IGNORECASE) for pattern in patterns)
+
+
+def is_bypass_task(task: str) -> bool:
+    task_lower = task.strip().lower()
+    if not task_lower:
+        return False
+    return matches_any_pattern(task_lower, BYPASS_PATTERNS)
+
+
+def is_force_discover(task: str) -> bool:
+    if is_bypass_task(task):
+        return False
+    return matches_any_pattern(task, FORCE_DISCOVER_PATTERNS)
+
+
+def task_intents(task: str) -> list[dict[str, Any]]:
+    if is_bypass_task(task):
+        return []
+    return [
+        profile
+        for profile in INTENT_PROFILES
+        if matches_any_pattern(task, list(profile.get("task_patterns", [])))
+    ]
+
+
+def apply_intent_boost(
+    score: float,
+    skill_name: str,
+    skill_text: str,
+    intents: list[dict[str, Any]],
+) -> tuple[float, list[str], str]:
+    adjusted = score
+    matched: list[str] = []
+    suggested_mode = ""
+    searchable = f"{skill_name} {skill_text}".lower()
+
+    for profile in intents:
+        if not matches_any_pattern(searchable, list(profile.get("skill_patterns", []))):
+            continue
+        matched.append(str(profile.get("name", "")))
+        multiplier = float(profile.get("score_multiplier", 1.0))
+        min_boost = float(profile.get("min_boost", 0.0))
+        adjusted = max(adjusted * multiplier, min_boost)
+        mode = str(profile.get("suggested_mode", "") or "")
+        if mode:
+            suggested_mode = mode
+
+    return adjusted, [name for name in matched if name], suggested_mode

package/skills/maestro/scripts/maestro_paths.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+"""Shared paths for Maestro (multi-agent, agent-agnostic home)."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+MAESTRO_HOME = Path(os.environ.get("MAESTRO_HOME", Path.home() / ".maestro"))
+MANIFEST_PATH = MAESTRO_HOME / "skills-manifest.json"
+EXCLUDE_PATH = MAESTRO_HOME / "maestro-exclude.txt"
+CONFIG_PATH = MAESTRO_HOME / "config.json"
+
+LEGACY_CURSOR_HOME = Path(os.environ.get("CURSOR_HOME", Path.home() / ".cursor"))
+LEGACY_MANIFEST_PATH = LEGACY_CURSOR_HOME / "skills-manifest.json"
+LEGACY_EXCLUDE_PATH = LEGACY_CURSOR_HOME / "maestro-exclude.txt"
+
+# (skills directory, scope label)
+GLOBAL_SKILL_ROOTS: list[tuple[Path, str]] = [
+    (Path.home() / ".cursor" / "skills", "cursor"),
+    (Path.home() / ".claude" / "skills", "claude"),
+    (Path.home() / ".codex" / "skills", "codex"),
+    (Path.home() / ".agents" / "skills", "agents"),
+]
+
+
+def project_skill_roots(project_root: Path) -> list[tuple[Path, str]]:
+    root = project_root.resolve()
+    return [
+        (root / ".cursor" / "skills", "project-cursor"),
+        (root / ".claude" / "skills", "project-claude"),
+        (root / ".codex" / "skills", "project-codex"),
+        (root / ".agents" / "skills", "project-agents"),
+    ]
+
+
+def all_skill_roots(project_root: Path | None = None) -> list[tuple[Path, str]]:
+    roots = list(GLOBAL_SKILL_ROOTS)
+    if project_root:
+        roots.extend(project_skill_roots(project_root))
+    return roots

package/skills/maestro/scripts/route_tasks.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""Batch route decomposed tasks using the fast manifest-based search engine."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+sys.path.insert(0, str(SCRIPT_DIR))
+
+from search_skills import DEFAULT_MANIFEST, load_manifest, search_skills  # noqa: E402
+
+
+def route_batch(
+    tasks: list[str],
+    manifest_path: Path,
+) -> dict:
+    manifest = load_manifest(manifest_path)
+    results = [
+        search_skills(task.strip(), manifest)
+        for task in tasks
+        if task.strip()
+    ]
+
+    all_gaps: list[str] = []
+    all_gap_notes: list[str] = []
+    discover_triggered = False
+    for result in results:
+        discover = result.get("discover", {})
+        if discover.get("triggered"):
+            discover_triggered = True
+        for gap in discover.get("gaps", []):
+            if gap not in all_gaps:
+                all_gaps.append(gap)
+        for note in discover.get("gap_notes", []):
+            if note not in all_gap_notes:
+                all_gap_notes.append(note)
+
+    priorities = [r.get("routing", {}).get("priority", "P3") for r in results]
+    if "P0" in priorities:
+        batch_priority, batch_decision = "P0", "recommend"
+    elif "P1" in priorities:
+        batch_priority, batch_decision = "P1", "auto-load"
+    elif "P2" in priorities:
+        batch_priority, batch_decision = "P2", "optional-load"
+    else:
+        batch_priority, batch_decision = "P3", "bypass"
+
+    return {
+        "batch": True,
+        "task_count": len(results),
+        "routing": {
+            "priority": batch_priority,
+            "decision": batch_decision,
+            "report_policy": "report" if batch_priority == "P0" else "silent",
+        },
+        "results": results,
+        "discover": {
+            "triggered": discover_triggered,
+            "gaps": all_gaps,
+            "gap_notes": all_gap_notes,
+        },
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Route decomposed tasks to skills")
+    parser.add_argument(
+        "tasks",
+        nargs="*",
+        help="Task strings; omit and use stdin for batch mode",
+    )
+    parser.add_argument("--manifest", default=str(DEFAULT_MANIFEST))
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args()
+
+    if args.tasks:
+        tasks = args.tasks
+    else:
+        tasks = [line.strip() for line in sys.stdin if line.strip()]
+
+    payload = route_batch(tasks, Path(args.manifest))
+
+    if args.json or not sys.stdout.isatty():
+        print(json.dumps(payload, indent=2, ensure_ascii=False))
+    else:
+        for result in payload["results"]:
+            top = result["results"][0]["name"] if result.get("results") else "(none)"
+            routing = result.get("routing", {})
+            print(
+                f"- {result['query']}: {top} "
+                f"[{routing.get('priority')} / {routing.get('decision')}]"
+            )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())