maestro-skills 0.1.1

package/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+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

@@ -0,0 +1,30 @@
+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 }}

package/CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contribuindo
+
+Obrigado pelo interesse no Maestro. Este projeto é open source (MIT).
+
+## Como contribuir
+
+1. Faça fork do repositório.
+2. Crie uma branch: `feat/<slug>` ou `fix/<slug>`.
+3. Para mudanças no motor de busca, inclua ou atualize testes em `tests/`.
+4. Rode localmente:
+   ```bash
+   python -m unittest discover -s tests -v
+   ```
+5. Abra um Pull Request para `main` com descrição clara do que mudou e por quê.
+
+## Áreas bem-vindas
+
+- Melhorias no ranking (intents, sinônimos, domínios)
+- Novos casos de teste com fixtures
+- Documentação e exemplos no README / SKILL.md
+- Traduções ou clareza no README
+
+## Estilo de código
+
+- Python 3.12+ compatível
+- Scripts em `skills/maestro/scripts/` devem permanecer sem dependências obrigatórias além da stdlib (PyYAML continua opcional)
+- Mensagens de commit em português ou inglês, descritivas
+
+## Segurança
+
+Veja [SECURITY.md](SECURITY.md) para reporte responsável de vulnerabilidades.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yuri Rodovalho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,300 @@
+# Maestro
+
+[![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+):
+
+```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
+
+Veja [SECURITY.md](SECURITY.md). O Maestro lê apenas pastas locais de skills; revise pacotes de `npx skills find` antes de instalar.
+
+## Licença
+
+[MIT](LICENSE) — Copyright (c) 2026 Yuri Rodovalho

package/SECURITY.md

@@ -0,0 +1,33 @@
+# Política de segurança
+
+## Escopo
+
+Este repositório contém a skill **Maestro** e scripts Python/PowerShell que rodam **localmente** na máquina do usuário. Eles leem pastas de skills (`~/.cursor/skills`, `~/.agents/skills`) e gravam um manifest em `~/.cursor/skills-manifest.json`. Não há servidor, telemetria nem envio de dados para terceiros.
+
+## Versões suportadas
+
+| Versão | Suportada |
+|--------|-----------|
+| `main` | Sim |
+
+## O que reportar
+
+- Execução insegura de comandos ou path traversal nos scripts
+- Leitura/escrita fora dos diretórios documentados sem consentimento do usuário
+- Vulnerabilidades em dependências usadas em CI (GitHub Actions)
+
+**Não** é escopo deste repo: vulnerabilidades em skills de terceiros instaladas na sua máquina, nem no Cursor IDE em si.
+
+## Como reportar
+
+1. **Não** abra Issue pública com detalhes de exploit.
+2. Abra um [Security Advisory](https://github.com/rodovalhofs/maestro/security/advisories/new) no GitHub **ou** envie descrição e passos de reprodução por canal privado acordado com o mantenedor.
+3. Inclua: versão/commit, SO, comando usado e impacto esperado.
+
+Objetivo de resposta inicial: **7 dias úteis**.
+
+## Boas práticas para quem instala
+
+- Revise pacotes retornados por `npx skills find` antes de instalar (`npx skills add`).
+- Use `~/.cursor/maestro-exclude.txt` para excluir skills sensíveis da busca.
+- O script `scripts/sync-templates.ps1` **sobrescreve** `.github/` no repositório destino — confira o `-TargetRepo` antes de executar.

package/docs/github-workflow.md

@@ -0,0 +1,96 @@
+# GitHub — fluxo generico (Issues + PR + CI)
+
+Guia reutilizavel para qualquer repositorio versionado. Copie `templates/` para o seu projeto ou use `scripts/sync-templates.ps1`.
+
+## Fluxo diario
+
+```text
+Issue → branch feat/N-slug → testes locais → build local → push → PR → CI → merge → Issue fecha
+```
+
+### Branch
+
+- Prefixo: `feat/` ou `fix/`
+- Exemplo: `feat/12-dashboard-indicadores`
+- Nunca commitar direto na branch principal (`main` ou `master`)
+
+### Commits
+
+- Mensagem clara em portugues (ou idioma do time): `tipo(escopo): descricao`
+- Referencie a Issue: `Refs #N` no corpo ou `Closes #N` quando o PR fecha a Issue
+
+### Pull request
+
+1. Abra PR em **draft** enquanto trabalha
+2. Rode testes e build localmente antes de marcar ready for review
+3. CI deve ficar verde antes do merge
+4. Use `Closes #N` no PR para fechar a Issue automaticamente
+
+## CI (GitHub Actions)
+
+Ordem recomendada em qualquer repo:
+
+1. **test** — testes automatizados
+2. **build** — compila frontend, empacota artefato, etc. (so se test passou)
+
+Falha no CI:
+
+- Workflow `ci-failure-to-issue.yml` pode abrir Issue com label `ci:falha`
+- Corrija na mesma branch/PR ate verde
+- Nao mergear com CI vermelho
+
+### Adaptar ao seu stack
+
+Edite `templates/.github/workflows/ci.yml`:
+
+- **Node/React:** `npm ci && npm test` / `npm run build`
+- **Python:** `pip install -r requirements.txt && pytest`
+- **Go:** `go test ./...` / `go build ./...`
+
+Mantenha a ordem: job `test` antes do job `build`.
+
+## Project (opcional)
+
+Para times que usam GitHub Projects:
+
+| Coluna | Quando usar |
+|--------|-------------|
+| Backlog | Issue aberta, sem branch |
+| Em progresso | Branch criada, PR draft |
+| Em review | PR ready, CI verde |
+| Concluido | Merge na branch principal |
+
+```bash
+gh project create --owner <org-ou-user> --title "Meu projeto"
+gh project link <NUMERO> --owner <org-ou-user> --repo <repo>
+```
+
+## Labels sugeridas
+
+Veja `templates/labels.json`. Aplicar com:
+
+```bash
+gh label create -f templates/labels.json  # ou script proprio
+```
+
+## Manutencao dos templates
+
+```powershell
+# Na raiz do clone do repositorio maestro
+.\scripts\sync-templates.ps1 -TargetRepo "C:\caminho\do\seu\projeto"
+```
+
+```bash
+# macOS / Linux (PowerShell Core)
+pwsh ./scripts/sync-templates.ps1 -TargetRepo "$HOME/projetos/meu-repo"
+```
+
+Nao versione `templates/` dentro de cada repo de aplicacao; copie para `.github/` local.
+
+## Skills relacionadas (Cursor)
+
+Para agentes que orquestram esse fluxo:
+
+- `github` — triagem de Issues e PRs
+- `yeet` — commit, push e PR draft
+- `gh-fix-ci` — depurar checks do GitHub Actions

package/docs/maestro-skills-cli.md

@@ -0,0 +1,113 @@
+# CLI `maestro-skills`
+
+Instalação interativa do Maestro para vários agentes de IA — um comando, escolha onde instalar.
+
+## Comando principal
+
+**GitHub (funciona sem publicar no npm):**
+
+```bash
+npx github:rodovalhofs/maestro maestro-skills setup
+```
+
+**npm registry** (após `maestro-skills@0.1.1` publicado):
+
+```bash
+npx maestro-skills setup
+```
+
+Equivalente scoped (bin `maestro`):
+
+```bash
+npx @rodovalhofs/maestro setup
+```
+
+## O que o setup faz
+
+1. Detecta agentes no sistema
+2. Você escolhe destinos (multi-select)
+3. Escolhe escopo: **global** (padrão) ou **este projeto** (`--project`)
+4. Copia a skill `maestro/` para cada pasta de skills
+5. Opcional: registra no [skills.sh](https://skills.sh/) via `npx skills add`
+6. Migra manifest legado `~/.cursor/skills-manifest.json` → `~/.maestro/`
+7. Executa `build_manifest.py` (Python 3.12+)
+
+## Agentes suportados
+
+| ID | Agente | Pasta global | CLI flag |
+|----|--------|--------------|----------|
+| `cursor` | Cursor | `~/.cursor/skills/maestro` | `--cursor` |
+| `claude` | Claude Code | `~/.claude/skills/maestro` | `--claude` |
+| `codex` | Codex | `~/.codex/skills/maestro` | `--codex` |
+| `universal` | Universal | `~/.agents/skills/maestro` | `--universal` |
+
+Novos agentes podem ser adicionados em `packages/maestro-skills/agents.json` sem alterar o core do CLI.
+
+## Comandos
+
+```bash
+# Setup interativo (recomendado)
+npx maestro-skills setup
+
+# Só Codex, global, sem prompts
+npx maestro-skills setup --codex -y
+
+# Vários agentes
+npx maestro-skills setup --cursor --claude --codex -y
+
+# Apenas o repositório atual
+npx maestro-skills setup --project
+
+# Desinstalar
+npx maestro-skills remove
+npx maestro-skills remove -y --clean-home
+```
+
+## Layout `~/.maestro/`
+
+```text
+~/.maestro/
+├── skills-manifest.json   # índice único (todos os agentes)
+├── maestro-exclude.txt    # skills ignoradas na busca
+└── config.json            # último setup (destinos, escopo)
+```
+
+O `build_manifest.py` indexa skills de:
+
+- `~/.cursor/skills`
+- `~/.claude/skills`
+- `~/.codex/skills`
+- `~/.agents/skills`
+- `.cursor/skills`, `.claude/skills`, `.codex/skills`, `.agents/skills` do `--project-root`
+
+## Pré-requisitos
+
+- **Node.js 18+** — para o CLI
+- **Python 3.12+** — para gerar o manifest (`py -3` ou `python3`)
+
+## Desenvolvimento
+
+```bash
+# Sincronizar skill canônica → pacotes npm
+node scripts/sync-skill-to-cli.mjs
+
+# Testes Python
+py -3 -m unittest discover -s tests -v
+
+# Testes Node
+cd packages/maestro-skills && npm test
+```
+
+## Publicação npm
+
+O pacote `maestro-skills` precisa ser publicado uma vez para `npx maestro-skills` funcionar sem GitHub.
+
+```bash
+npm login
+npm run publish:cli    # maestro-skills
+npm run publish:scoped # @rodovalhofs/maestro
+```
+
+Ou dispare o workflow **Publish npm** no GitHub Actions (secret `NPM_TOKEN`).
+
+Não inclua tokens, `.env` ou credenciais nos pacotes.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "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
+}