maestro-skills 0.1.1 → 0.1.2

package/README.md

@@ -1,300 +1,20 @@
-# Maestro
+# maestro-skills
 
-[![CI](https://github.com/rodovalhofs/maestro/actions/workflows/ci.yml/badge.svg)](https://github.com/rodovalhofs/maestro/actions/workflows/ci.yml)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-
-**Maestro** é um meta-orquestrador de skills para agentes de IA (Cursor, Claude Code, Codex e outros). Você descreve a tarefa; ele descobre quais skills locais usar, monta um **grafo de dependências editável**, pede sua confirmação e só então dispara subagentes com os `SKILL.md` certos.
-
-Se faltar skill no ecossistema (ex.: `skeleton-loader`), o Maestro abre o ramo **Discover** via [find-skills](https://skills.sh/) (`npx skills find`), instala, regenera o índice e roteia de novo.
-
-> Motor **local e rápido** (BM25 + manifest JSON) — sem re-scan do filesystem a cada busca.  
-> Inspirado em ideias de [task-skill-router](https://github.com/wcqxgjy6d8-pixel/task-skill-router).
-
----
-
-## O que o Maestro faz (e o que não faz)
-
-| Faz | Não faz |
-|-----|---------|
-| Analisa seu prompt e busca skills **já instaladas** | Implementar código por conta própria |
-| Monta um grafo de nós (pesquisa → implementação → CI…) | Spawnar subagentes sem você confirmar o grafo |
-| Detecta **lacunas de conceito** (`skeleton-loader`, libs citadas no prompt) | Substituir o agente principal do Cursor |
-| Sugere instalar skills via `npx skills find` quando necessário | Enviar dados para servidores externos |
-| Roteia com prioridade **P0–P3** (auto-load vs recomendar) | Ignorar tarefas de alto risco (deploy, secrets) sem confirmação |
-
-### Em uma frase
-
-O Maestro responde: *“Para esta tarefa, quais skills devo usar, em que ordem, e preciso instalar algo novo?”*
-
----
-
-## Fluxo completo
-
-```text
-Seu prompt
-    │
-    ▼
-build_manifest.py          ← índice local (~/.maestro/skills-manifest.json)
-    │
-    ▼
-search_skills.py             ← BM25 + intents + sinônimos + concept gaps
-    │
-    ├─ match forte, sem lacunas
-    │       └─► Grafo único → você confirma → subagentes executam
-    │
-    └─ discover.triggered
-            │
-            ▼
-        npx skills find      ← pré-busca no ecossistema (skills.sh)
-            │
-            ▼
-        Grafo 1 (Discover + fallback local) → você: ok
-            │
-            ▼
-        find-skills install + build_manifest.py
-            │
-            ▼
-        Grafo 2 (execução) → você: ok
-            │
-            ▼
-        subagentes com SKILL.md explícito → síntese final
-```
-
-### Quando o ramo Discover abre
-
-| Sinal | Exemplo |
-|-------|---------|
-| `weak_match` | Nenhuma skill local confiável para o prompt |
-| `concept_gap` | *“colocar skeleton-loader na UI”* — termo sem skill local |
-| `force_discover` | *“find a skill for changelog”*, `npx skills find` |
-| `single_local_skill` | Só um candidato local e score baixo |
-
-Máximo de **2** gaps por prompt; extras viram nota no grafo para você editar.
-
----
-
-## Instalação
-
-### Opção A — `npx maestro-skills setup` (recomendado)
-
-Setup interativo — escolha agentes e escopo (global ou projeto).
-
-**Se `npx maestro-skills` retornar 404**, o pacote ainda não está no npm registry — use o GitHub (funciona agora):
-
-```bash
-npx github:rodovalhofs/maestro maestro-skills setup
-```
-
-**Após publicação no npm** (v0.1.1+):
+CLI de instalação interativa do [Maestro](https://github.com/rodovalhofs/maestro).
 
 ```bash
 npx maestro-skills setup
 ```
 
-| Agente | Pasta | Flag |
-|--------|-------|------|
-| Cursor | `~/.cursor/skills/maestro` | `--cursor` |
-| Claude Code | `~/.claude/skills/maestro` | `--claude` |
-| Codex | `~/.codex/skills/maestro` | `--codex` |
-| Universal | `~/.agents/skills/maestro` | `--universal` |
-
-Exemplos:
-
-```bash
-npx maestro-skills setup --codex --cursor -y    # Codex + Cursor, sem prompts
-npx maestro-skills setup --project              # só o repo atual
-npx @rodovalhofs/maestro setup                  # fallback (bin curto)
-```
-
-Documentação completa: [docs/maestro-skills-cli.md](docs/maestro-skills-cli.md)
-
-### Opção B — `npx skills add` (catálogo skills.sh)
-
-```bash
-npx skills add rodovalhofs/maestro --skill maestro -g -a cursor -a codex -y
-```
-
-### Opção C — Git clone (manual)
-
-```powershell
-# Windows
-git clone https://github.com/rodovalhofs/maestro.git
-Copy-Item -Recurse -Force maestro\skills\maestro $env:USERPROFILE\.cursor\skills\maestro
-# ou: $env:USERPROFILE\.codex\skills\maestro
-```
-
-```bash
-# macOS / Linux
-git clone https://github.com/rodovalhofs/maestro.git
-cp -r maestro/skills/maestro ~/.cursor/skills/maestro
-# ou: ~/.codex/skills/maestro
-```
-
-### Pós-instalação (obrigatório)
-
-Indexe suas skills locais (todos os agentes):
-
-```bash
-# Windows
-py -3 %USERPROFILE%\.cursor\skills\maestro\scripts\build_manifest.py --project-root .
-
-# macOS / Linux
-python3 ~/.cursor/skills/maestro/scripts/build_manifest.py --project-root .
-```
-
-Manifest gerado em `~/.maestro/skills-manifest.json`.
-
-### Opcional — excluir skills da busca
-
-```bash
-cp ~/.cursor/skills/maestro/maestro-exclude.example.txt ~/.cursor/maestro-exclude.txt
-# edite o arquivo e regenere o manifest
-```
-
----
-
-## Pré-requisitos
-
-| Ferramenta | Obrigatório | Uso |
-|------------|-------------|-----|
-| **Cursor** | Sim | Agent skills em `~/.cursor/skills` e/ou `~/.agents/skills` |
-| **Python 3.12+** | Sim | Scripts de busca e manifest (mesma versão do CI) |
-| **Node.js** | Para Discover | `npx skills find` / `npx skills add` no ramo find-skills |
-
----
-
-## Uso no Cursor
-
-Invoque com **`$maestro`** ou **`/maestro`** + sua tarefa:
-
-```text
-$maestro criar dashboard de vendas com React e gráficos
-$maestro vamos colocar skeleton-loader na tela de produtos
-$maestro corrigir CI quebrado no PR #42
-```
-
-O agente segue o `SKILL.md` do Maestro: busca → grafo editável → confirmação → execução.
-
-### Ferramentas CLI (uso direto ou debug)
-
-**1. Regenerar manifest**
-
-```bash
-py -3 ~/.cursor/skills/maestro/scripts/build_manifest.py --project-root /caminho/do/projeto
-```
-
-**2. Buscar skills para um prompt**
-
-```bash
-py -3 ~/.cursor/skills/maestro/scripts/search_skills.py "criar dashboard react" --json
-```
-
-Campos úteis no JSON:
-
-| Campo | Significado |
-|-------|-------------|
-| `results` | Skills locais ranqueadas (score, confidence, path) |
-| `routing` | `P0`–`P3` e decisão (`auto-load`, `recommend`, `bypass`) |
-| `discover` | `triggered`, `reasons`, `gaps`, `queries`, `local_fallback` |
-| `weak_match` | Match local fraco — pode pedir domínio ou Discover |
-
-**3. Rotear sub-tarefas (grafo decomposto)**
-
-```bash
-printf '%s\n' "design UI" "fix CI" | py -3 ~/.cursor/skills/maestro/scripts/route_tasks.py --json
-```
-
-**Domínios** (`--domain`): `web`, `data-viz`, `analytics`, `design`, `creative`, `devops-git`, `video-media`, `integrations`, `security`, `meta`, `general`.
-
----
-
-## Exemplos de comportamento
-
-### Tarefa com skill local clara
-
-```text
-Prompt: corrigir CI quebrado no PR
-→ discover.triggered: false
-→ top: gh-fix-ci, github
-→ Grafo: 1 nó → você confirma → subagente executa
-```
-
-### Conceito sem skill local
-
-```text
-Prompt: vamos colocar skeleton-loader na UI
-→ discover.triggered: true (concept_gap: skeleton-loader)
-→ npx skills find "skeleton-loader ui web"
-→ Grafo 1 com Discover → install → Grafo 2 → implementação
-```
-
-### Descoberta explícita
-
-```text
-Prompt: find a skill for changelog
-→ discover.triggered: true (force_discover)
-→ find-skills busca no skills.sh
-```
-
----
-
-## O que há neste repositório
-
-| Pasta | Conteúdo |
-|-------|----------|
-| `skills/maestro/` | Skill Cursor + scripts Python (`search_skills`, `concept_gaps`, …) |
-| `tests/` | 18+ testes do motor de busca |
-| `docs/` | Fluxo GitHub genérico (Issues + PR + CI) |
-| `templates/` | Issue templates, PR template e workflows para copiar em outros projetos |
-
-```text
-maestro/
-├── .github/workflows/ci.yml
-├── skills/maestro/
-│   ├── SKILL.md              ← regras do orquestrador
-│   ├── maestro-exclude.example.txt
-│   └── scripts/
-│       ├── build_manifest.py
-│       ├── search_skills.py
-│       ├── concept_gaps.py
-│       ├── route_tasks.py
-│       └── …
-├── tests/
-├── docs/github-workflow.md
-└── templates/
-```
-
----
-
-## Testes
-
-```bash
-py -3 -m unittest discover -s tests -v
-```
-
----
-
-## Templates GitHub
-
-Copie workflows e templates de Issue/PR para outro repositório:
-
-```powershell
-# Atenção: sobrescreve .github/ no destino
-.\scripts\sync-templates.ps1 -TargetRepo "C:\caminho\do\seu\projeto"
-```
-
-Detalhes: [docs/github-workflow.md](docs/github-workflow.md)
-
----
-
-## Contribuir
-
-Veja [CONTRIBUTING.md](CONTRIBUTING.md). Issues e PRs são bem-vindos.
-
-## Segurança
+[![npm](https://img.shields.io/npm/v/maestro-skills)](https://www.npmjs.com/package/maestro-skills)
 
-Veja [SECURITY.md](SECURITY.md). O Maestro lê apenas pastas locais de skills; revise pacotes de `npx skills find` antes de instalar.
+## Agentes
 
-## Licença
+| Agente | Flag |
+|--------|------|
+| Cursor | `--cursor` |
+| Claude Code | `--claude` |
+| Codex | `--codex` |
+| Universal | `--universal` |
 
-[MIT](LICENSE) — Copyright (c) 2026 Yuri Rodovalho
+Docs: [maestro-skills-cli.md](../../docs/maestro-skills-cli.md)

package/{packages/maestro-skills/bin → bin}/cli.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 import { Command } from "commander";
 import { runRemove } from "../lib/remove.js";
 import { runSetup } from "../lib/setup.js";
@@ -8,7 +8,7 @@ const program = new Command();
 program
   .name("maestro-skills")
   .description("Install and configure the Maestro skill orchestrator for multiple AI agents")
-  .version("0.1.1");
+  .version("0.1.2");
 
 program
   .command("setup")

package/{packages/rodovalhofs-maestro/lib → lib}/paths.js

@@ -1,10 +1,10 @@
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const PACKAGE_ROOT = join(__dirname, "..");
+const PACKAGE_ROOT = resolve(__dirname, "..");
 
 export function getMaestroHome() {
   return process.env.MAESTRO_HOME || join(homedir(), ".maestro");
@@ -33,8 +33,29 @@ export function resolveSkillsDir(agent, { project = false, cwd = process.cwd() }
   return join(base, rel);
 }
 
+/** Resolve bundled skill folder (works for npm pack and monorepo-root publish). */
 export function skillSourceDir() {
-  return join(PACKAGE_ROOT, "skill");
+  const candidates = [];
+
+  let dir = PACKAGE_ROOT;
+  for (let i = 0; i < 5; i++) {
+    candidates.push(
+      join(dir, "skill"),
+      join(dir, "skills", "maestro"),
+    );
+    dir = resolve(dir, "..");
+  }
+
+  for (const candidate of candidates) {
+    if (existsSync(join(candidate, "SKILL.md"))) {
+      return candidate;
+    }
+  }
+
+  throw new Error(
+    `Skill source not found (expected SKILL.md under ${join(PACKAGE_ROOT, "skill")}). ` +
+      "Reinstall with: npx maestro-skills@latest setup",
+  );
 }
 
 export function bundledBuildManifest() {

package/{packages/maestro-skills/lib → lib}/run-manifest.js

@@ -1,5 +1,6 @@
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
+import { join } from "node:path";
 import { bundledBuildManifest, getMaestroPaths } from "./paths.js";
 
 function pythonCommand() {
@@ -14,8 +15,15 @@ function pythonCommand() {
   return null;
 }
 
-export function runBuildManifest({ projectRoot = process.cwd(), quiet = false } = {}) {
-  const script = bundledBuildManifest();
+export function runBuildManifest({
+  projectRoot = process.cwd(),
+  quiet = false,
+  installedSkillPath = null,
+} = {}) {
+  let script = bundledBuildManifest();
+  if (!existsSync(script) && installedSkillPath) {
+    script = join(installedSkillPath, "scripts", "build_manifest.py");
+  }
   if (!existsSync(script)) {
     return { ok: false, error: `build_manifest.py not found at ${script}` };
   }

package/lib/setup.js

@@ -0,0 +1,130 @@
+import * as p from "@clack/prompts";
+import { detectAgents, filterAgentsByFlags } from "./detect-agents.js";
+import {
+  copySkillTo,
+  migrateLegacyFiles,
+  saveSetupConfig,
+} from "./install.js";
+import { getMaestroPaths } from "./paths.js";
+import { registerOnSkillsSh, runBuildManifest } from "./run-manifest.js";
+
+export async function runSetup(options) {
+  const project = Boolean(options.project);
+  const cwd = process.cwd();
+
+  p.intro(project ? "Maestro setup (this project)" : "Maestro setup (global)");
+
+  let agents = detectAgents({ project, cwd });
+  agents = filterAgentsByFlags(agents, options);
+
+  if (!options.cursor && !options.claude && !options.codex && !options.universal && !options.yes) {
+    p.note(
+      "↑↓ navegar · Espaço selecionar/desmarcar · Enter confirmar",
+      "Atalhos do teclado",
+    );
+
+    const selected = await p.multiselect({
+      message: "Which agents should receive the Maestro skill?",
+      options: agents.map((a) => ({
+        value: a.id,
+        label: a.label,
+        hint: a.detected ? `${a.skillsPath} (detected)` : a.skillsPath,
+      })),
+      required: true,
+      initialValues: [],
+    });
+    if (p.isCancel(selected)) {
+      p.cancel("Setup cancelled.");
+      process.exit(0);
+    }
+    agents = agents.filter((a) => selected.includes(a.id));
+  } else if (options.cursor || options.claude || options.codex || options.universal) {
+    agents = filterAgentsByFlags(agents, options);
+  } else if (options.yes) {
+    agents = agents.filter((a) => a.detected);
+    if (!agents.length) agents = detectAgents({ project, cwd });
+  }
+
+  if (!agents.length) {
+    p.cancel("No agents selected.");
+    process.exit(1);
+  }
+
+  let registerSkillsSh = false;
+  if (!options.yes && !options.noSkillsRegistry) {
+    const reg = await p.confirm({
+      message: "Register install on skills.sh via npx skills add? (optional telemetry)",
+      initialValue: false,
+    });
+    if (p.isCancel(reg)) {
+      p.cancel("Setup cancelled.");
+      process.exit(0);
+    }
+    registerSkillsSh = Boolean(reg);
+  }
+
+  const spinner = p.spinner();
+  const installed = [];
+
+  for (const agent of agents) {
+    spinner.start(`Installing Maestro for ${agent.label}…`);
+    try {
+      const dest = copySkillTo(agent.skillsPath);
+      installed.push({ id: agent.id, label: agent.label, path: dest });
+      spinner.stop(`Installed → ${dest}`);
+    } catch (err) {
+      spinner.stop(`Failed for ${agent.label}`);
+      p.log.error(String(err.message || err));
+    }
+  }
+
+  if (!installed.length) {
+    p.cancel("Setup failed — Maestro skill was not installed for any agent.");
+    process.exit(1);
+  }
+
+  const migrated = migrateLegacyFiles();
+  if (migrated.length) {
+    p.log.info(`Migrated legacy files: ${migrated.join(", ")}`);
+  }
+
+  spinner.start("Building skills manifest…");
+  const manifestResult = runBuildManifest({
+    projectRoot: cwd,
+    quiet: true,
+    installedSkillPath: installed[0]?.path,
+  });
+  if (manifestResult.ok) {
+    spinner.stop(manifestResult.message);
+  } else {
+    spinner.stop("Manifest build failed");
+    p.log.warn(manifestResult.error);
+  }
+
+  if (registerSkillsSh) {
+    spinner.start("Registering on skills.sh…");
+    const reg = await registerOnSkillsSh(agents, { yes: options.yes });
+    if (reg.ok && !reg.skipped) spinner.stop("Registered on skills.sh");
+    else if (!reg.ok) {
+      spinner.stop("skills.sh registration skipped");
+      p.log.warn(reg.error);
+    } else spinner.stop("No skills CLI agents selected");
+  }
+
+  const paths = getMaestroPaths();
+  saveSetupConfig({
+    version: 1,
+    installedAt: new Date().toISOString(),
+    scope: project ? "project" : "global",
+    projectRoot: project ? cwd : null,
+    agents: installed,
+    maestroHome: paths.home,
+  });
+
+  p.note(
+    installed.map((i) => `${i.label}\n  ${i.path}`).join("\n\n"),
+    "Installed paths",
+  );
+  p.outro("Maestro setup complete. Invoke with $maestro or /maestro in your agent.");
+}
+

package/package.json

@@ -1,35 +1,48 @@
-{
-  "name": "maestro-skills",
-  "version": "0.1.1",
-  "description": "Interactive setup for the Maestro skill orchestrator (multi-agent)",
-  "license": "MIT",
-  "author": "Yuri Rodovalho",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/rodovalhofs/maestro.git"
-  },
-  "homepage": "https://github.com/rodovalhofs/maestro#installation",
-  "bugs": {
-    "url": "https://github.com/rodovalhofs/maestro/issues"
-  },
-  "type": "module",
-  "engines": {
-    "node": ">=18"
-  },
-  "bin": {
-    "maestro-skills": "./packages/maestro-skills/bin/cli.js"
-  },
-  "scripts": {
-    "prepare": "node scripts/sync-skill-to-cli.mjs",
-    "test:py": "python -m unittest discover -s tests -v",
-    "test:js": "npm test --prefix packages/maestro-skills",
-    "test": "npm run test:py && npm run test:js",
-    "publish:cli": "node scripts/sync-skill-to-cli.mjs && npm publish --prefix packages/maestro-skills --access public",
-    "publish:scoped": "node scripts/sync-skill-to-cli.mjs && npm publish --prefix packages/rodovalhofs-maestro --access public"
-  },
-  "dependencies": {
-    "@clack/prompts": "^0.10.1",
-    "commander": "^13.1.0"
-  },
-  "private": false
-}
+{
+  "name": "maestro-skills",
+  "version": "0.1.2",
+  "description": "Interactive setup for the Maestro skill orchestrator (multi-agent)",
+  "license": "MIT",
+  "author": "Yuri Rodovalho",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rodovalhofs/maestro.git",
+    "directory": "packages/maestro-skills"
+  },
+  "homepage": "https://github.com/rodovalhofs/maestro#readme",
+  "bugs": {
+    "url": "https://github.com/rodovalhofs/maestro/issues"
+  },
+  "keywords": [
+    "maestro",
+    "cursor",
+    "claude",
+    "codex",
+    "agent-skills",
+    "skills",
+    "orchestrator"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "maestro-skills": "./bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "skill",
+    "agents.json",
+    "README.md"
+  ],
+  "scripts": {
+    "prepack": "node ../../scripts/sync-skill-to-cli.mjs",
+    "prepublishOnly": "node -e \"const fs=require('fs'); if(!fs.existsSync('skill/SKILL.md')){console.error('Missing skill/ — run sync-skill-to-cli'); process.exit(1)}\"",
+    "test": "node --test test/"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.10.1",
+    "commander": "^13.1.0"
+  }
+}

package/.github/workflows/ci.yml

@@ -1,26 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-jobs:
-  test:
-    name: Testes maestro
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-      - uses: actions/setup-node@v4
-        with:
-          node-version: "20"
-      - run: node scripts/sync-skill-to-cli.mjs
-      - run: python -m unittest discover -s tests -v
-      - run: npm install
-        working-directory: packages/maestro-skills
-      - run: npm test
-        working-directory: packages/maestro-skills

package/.github/workflows/publish-npm.yml

@@ -1,30 +0,0 @@
-name: Publish npm
-
-on:
-  release:
-    types: [published]
-  workflow_dispatch:
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      id-token: write
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: "20"
-          registry-url: "https://registry.npmjs.org"
-      - run: node scripts/sync-skill-to-cli.mjs
-      - run: npm ci
-        working-directory: packages/maestro-skills
-      - run: npm publish --access public
-        working-directory: packages/maestro-skills
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-      - run: npm publish --access public
-        working-directory: packages/rodovalhofs-maestro
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}