maestro-skills 0.1.1

package/packages/maestro-skills/README.md

@@ -0,0 +1,37 @@
+# maestro-skills
+
+CLI de instalação interativa do Maestro — estilo `npx ctx7 setup`.
+
+## Instalação
+
+```bash
+npx maestro-skills setup
+```
+
+Fallback (bin curto `maestro`):
+
+```bash
+npx @rodovalhofs/maestro setup
+```
+
+## Agentes suportados (v1)
+
+| Agente | Pasta global | Flag |
+|--------|--------------|------|
+| Cursor | `~/.cursor/skills` | `--cursor` |
+| Claude Code | `~/.claude/skills` | `--claude` |
+| Codex | `~/.codex/skills` | `--codex` |
+| Universal | `~/.agents/skills` | `--universal` |
+
+## Comandos
+
+```bash
+npx maestro-skills setup              # interativo
+npx maestro-skills setup --codex -y   # só Codex, sem prompts
+npx maestro-skills setup --project    # só o projeto atual
+npx maestro-skills remove             # desinstalar
+```
+
+Índice de skills: `~/.maestro/skills-manifest.json`
+
+Documentação completa: [docs/maestro-skills-cli.md](../../docs/maestro-skills-cli.md)

package/packages/maestro-skills/agents.json

@@ -0,0 +1,36 @@
+{
+  "agents": [
+    {
+      "id": "cursor",
+      "label": "Cursor",
+      "globalSkillsDir": ".cursor/skills",
+      "projectSkillsDir": ".cursor/skills",
+      "detectDirs": [".cursor"],
+      "skillsCliAgent": "cursor"
+    },
+    {
+      "id": "claude",
+      "label": "Claude Code",
+      "globalSkillsDir": ".claude/skills",
+      "projectSkillsDir": ".claude/skills",
+      "detectDirs": [".claude"],
+      "skillsCliAgent": "claude"
+    },
+    {
+      "id": "codex",
+      "label": "Codex",
+      "globalSkillsDir": ".codex/skills",
+      "projectSkillsDir": ".codex/skills",
+      "detectDirs": [".codex"],
+      "skillsCliAgent": "codex"
+    },
+    {
+      "id": "universal",
+      "label": "Universal (~/.agents/skills)",
+      "globalSkillsDir": ".agents/skills",
+      "projectSkillsDir": ".agents/skills",
+      "detectDirs": [".agents"],
+      "skillsCliAgent": null
+    }
+  ]
+}

package/packages/maestro-skills/bin/cli.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { runRemove } from "../lib/remove.js";
+import { runSetup } from "../lib/setup.js";
+
+const program = new Command();
+
+program
+  .name("maestro-skills")
+  .description("Install and configure the Maestro skill orchestrator for multiple AI agents")
+  .version("0.1.1");
+
+program
+  .command("setup")
+  .description("Interactive setup — choose agents, scope, and build manifest")
+  .option("--project", "Install only in the current project")
+  .option("--cursor", "Target Cursor only")
+  .option("--claude", "Target Claude Code only")
+  .option("--codex", "Target Codex only")
+  .option("--universal", "Target ~/.agents/skills only")
+  .option("-y, --yes", "Skip prompts (defaults: detected agents, no skills.sh)")
+  .option("--no-skills-registry", "Skip skills.sh registration prompt")
+  .action(async (opts) => {
+    await runSetup(opts);
+  });
+
+program
+  .command("remove")
+  .description("Remove Maestro skill from selected agents")
+  .option("-y, --yes", "Remove from all last-known destinations without prompts")
+  .option("--all", "Consider all known agent paths")
+  .option("--clean-home", "With --yes, also remove ~/.maestro/")
+  .action(async (opts) => {
+    await runRemove(opts);
+  });
+
+program.parseAsync(process.argv);

package/packages/maestro-skills/lib/detect-agents.js

@@ -0,0 +1,28 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { loadAgents } from "./paths.js";
+
+export function detectAgents({ project = false, cwd = process.cwd() } = {}) {
+  const agents = loadAgents();
+  const base = project ? cwd : homedir();
+
+  return agents.map((agent) => {
+    const detected = agent.detectDirs.some((dir) => existsSync(join(base, dir)));
+    return {
+      ...agent,
+      detected: detected || !project,
+      skillsPath: join(base, project ? agent.projectSkillsDir : agent.globalSkillsDir),
+    };
+  });
+}
+
+export function filterAgentsByFlags(agents, flags) {
+  const ids = [];
+  if (flags.cursor) ids.push("cursor");
+  if (flags.claude) ids.push("claude");
+  if (flags.codex) ids.push("codex");
+  if (flags.universal) ids.push("universal");
+  if (!ids.length) return agents;
+  return agents.filter((a) => ids.includes(a.id));
+}

package/packages/maestro-skills/lib/install.js

@@ -0,0 +1,58 @@
+import { cpSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getMaestroPaths, skillSourceDir } from "./paths.js";
+
+export function copySkillTo(destDir) {
+  const src = skillSourceDir();
+  const dest = join(destDir, "maestro");
+  rmSync(dest, { recursive: true, force: true });
+  mkdirSync(dirname(dest), { recursive: true });
+  cpSync(src, dest, { recursive: true });
+  const pycache = join(dest, "scripts", "__pycache__");
+  if (existsSync(pycache)) rmSync(pycache, { recursive: true, force: true });
+  return dest;
+}
+
+export function migrateLegacyFiles() {
+  const paths = getMaestroPaths();
+  mkdirSync(paths.home, { recursive: true });
+  const migrated = [];
+
+  if (!existsSync(paths.manifest) && existsSync(paths.legacyManifest)) {
+    renameSync(paths.legacyManifest, paths.manifest);
+    migrated.push("skills-manifest.json");
+  }
+  if (!existsSync(paths.exclude) && existsSync(paths.legacyExclude)) {
+    renameSync(paths.legacyExclude, paths.exclude);
+    migrated.push("maestro-exclude.txt");
+  }
+
+  const example = join(skillSourceDir(), "maestro-exclude.example.txt");
+  if (!existsSync(paths.exclude) && existsSync(example)) {
+    cpSync(example, paths.exclude);
+    migrated.push("maestro-exclude.txt (from example)");
+  }
+
+  return migrated;
+}
+
+export function saveSetupConfig(config) {
+  const { config: configPath } = getMaestroPaths();
+  mkdirSync(dirname(configPath), { recursive: true });
+  writeFileSync(configPath, JSON.stringify(config, null, 2), "utf8");
+}
+
+export function loadSetupConfig() {
+  const { config: configPath } = getMaestroPaths();
+  if (!existsSync(configPath)) return null;
+  return JSON.parse(readFileSync(configPath, "utf8"));
+}
+
+export function removeSkillFrom(destDir) {
+  const dest = join(destDir, "maestro");
+  if (existsSync(dest)) {
+    rmSync(dest, { recursive: true, force: true });
+    return true;
+  }
+  return false;
+}

package/packages/maestro-skills/lib/paths.js

@@ -0,0 +1,42 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = join(__dirname, "..");
+
+export function getMaestroHome() {
+  return process.env.MAESTRO_HOME || join(homedir(), ".maestro");
+}
+
+export function getMaestroPaths() {
+  const home = getMaestroHome();
+  return {
+    home,
+    manifest: join(home, "skills-manifest.json"),
+    exclude: join(home, "maestro-exclude.txt"),
+    config: join(home, "config.json"),
+    legacyManifest: join(homedir(), ".cursor", "skills-manifest.json"),
+    legacyExclude: join(homedir(), ".cursor", "maestro-exclude.txt"),
+  };
+}
+
+export function loadAgents() {
+  const raw = readFileSync(join(PACKAGE_ROOT, "agents.json"), "utf8");
+  return JSON.parse(raw).agents;
+}
+
+export function resolveSkillsDir(agent, { project = false, cwd = process.cwd() } = {}) {
+  const base = project ? cwd : homedir();
+  const rel = project ? agent.projectSkillsDir : agent.globalSkillsDir;
+  return join(base, rel);
+}
+
+export function skillSourceDir() {
+  return join(PACKAGE_ROOT, "skill");
+}
+
+export function bundledBuildManifest() {
+  return join(skillSourceDir(), "scripts", "build_manifest.py");
+}

package/packages/maestro-skills/lib/remove.js

@@ -0,0 +1,71 @@
+import * as p from "@clack/prompts";
+import { rmSync, existsSync } from "node:fs";
+import { loadSetupConfig, removeSkillFrom } from "./install.js";
+import { getMaestroPaths } from "./paths.js";
+import { detectAgents } from "./detect-agents.js";
+
+export async function runRemove(options) {
+  p.intro("Maestro remove");
+
+  const config = loadSetupConfig();
+  let targets = config?.agents || [];
+
+  if (!targets.length || options.all) {
+    const agents = detectAgents({ project: false });
+    targets = agents.map((a) => ({
+      id: a.id,
+      label: a.label,
+      path: `${a.skillsPath}/maestro`.replace(/\\/g, "/"),
+      skillsPath: a.skillsPath,
+    }));
+  }
+
+  if (!options.yes) {
+    const selected = await p.multiselect({
+      message: "Remove Maestro skill from:",
+      options: targets.map((t) => ({
+        value: t.id,
+        label: t.label,
+        hint: t.skillsPath || t.path,
+      })),
+      required: true,
+      initialValues: targets.map((t) => t.id),
+    });
+    if (p.isCancel(selected)) {
+      p.cancel("Remove cancelled.");
+      process.exit(0);
+    }
+    targets = targets.filter((t) => selected.includes(t.id));
+  }
+
+  let cleanHome = false;
+  if (!options.yes) {
+    const clean = await p.confirm({
+      message: "Also remove ~/.maestro/ (manifest, exclude, config)?",
+      initialValue: false,
+    });
+    if (p.isCancel(clean)) {
+      p.cancel("Remove cancelled.");
+      process.exit(0);
+    }
+    cleanHome = Boolean(clean);
+  } else if (options.cleanHome) {
+    cleanHome = true;
+  }
+
+  for (const t of targets) {
+    const dir = t.skillsPath || t.path.replace(/\/maestro$/, "");
+    const removed = removeSkillFrom(dir);
+    p.log.info(removed ? `Removed ${dir}/maestro` : `Not found: ${dir}/maestro`);
+  }
+
+  if (cleanHome) {
+    const { home } = getMaestroPaths();
+    if (existsSync(home)) {
+      rmSync(home, { recursive: true, force: true });
+      p.log.info(`Removed ${home}`);
+    }
+  }
+
+  p.outro("Maestro removed.");
+}

package/packages/maestro-skills/lib/run-manifest.js

@@ -0,0 +1,92 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { bundledBuildManifest, getMaestroPaths } from "./paths.js";
+
+function pythonCommand() {
+  if (process.platform === "win32") {
+    const py = spawnSync("py", ["-3", "--version"], { encoding: "utf8" });
+    if (py.status === 0) return ["py", "-3"];
+  }
+  const python3 = spawnSync("python3", ["--version"], { encoding: "utf8" });
+  if (python3.status === 0) return ["python3"];
+  const python = spawnSync("python", ["--version"], { encoding: "utf8" });
+  if (python.status === 0) return ["python"];
+  return null;
+}
+
+export function runBuildManifest({ projectRoot = process.cwd(), quiet = false } = {}) {
+  const script = bundledBuildManifest();
+  if (!existsSync(script)) {
+    return { ok: false, error: `build_manifest.py not found at ${script}` };
+  }
+
+  const py = pythonCommand();
+  if (!py) {
+    return {
+      ok: false,
+      error: "Python 3.12+ not found. Install Python and ensure `py -3` or `python3` works.",
+    };
+  }
+
+  const { manifest } = getMaestroPaths();
+  const args = [...py, script, "--project-root", projectRoot, "--output", manifest];
+  const result = spawnSync(args[0], args.slice(1), {
+    encoding: "utf8",
+    stdio: quiet ? "pipe" : "inherit",
+  });
+
+  if (result.status !== 0) {
+    return {
+      ok: false,
+      error: result.stderr || `build_manifest exited with code ${result.status}`,
+    };
+  }
+
+  const line = (result.stdout || "").trim().split("\n").pop();
+  return { ok: true, message: line || `Manifest written to ${manifest}` };
+}
+
+export async function registerOnSkillsSh(agents, { yes = false } = {}) {
+  const withCli = agents.filter((a) => a.skillsCliAgent);
+  if (!withCli.length) return { ok: true, skipped: true };
+
+  const args = [
+    "skills",
+    "add",
+    "rodovalhofs/maestro",
+    "--skill",
+    "maestro",
+    "-g",
+    "-y",
+  ];
+
+  for (const agent of withCli) {
+    args.push("-a", agent.skillsCliAgent);
+  }
+
+  const uniqueAgents = [...new Set(withCli.map((a) => a.skillsCliAgent))];
+  const finalArgs = [
+    "skills",
+    "add",
+    "rodovalhofs/maestro",
+    "--skill",
+    "maestro",
+    "-g",
+    "-y",
+    ...uniqueAgents.flatMap((a) => ["-a", a]),
+  ];
+
+  const result = spawnSync("npx", finalArgs, {
+    encoding: "utf8",
+    stdio: yes ? "pipe" : "inherit",
+    shell: process.platform === "win32",
+  });
+
+  if (result.status !== 0) {
+    return {
+      ok: false,
+      error: "npx skills add failed (optional step). Install Node.js or run manually.",
+    };
+  }
+  return { ok: true };
+}

package/packages/maestro-skills/lib/setup.js

@@ -0,0 +1,115 @@
+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) {
+    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.skillsPath,
+      })),
+      required: true,
+      initialValues: agents.filter((a) => a.detected).map((a) => a.id),
+    });
+    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));
+    }
+  }
+
+  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 });
+  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/packages/maestro-skills/package.json

@@ -0,0 +1,47 @@
+{
+  "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",
+    "directory": "packages/maestro-skills"
+  },
+  "homepage": "https://github.com/rodovalhofs/maestro#installation",
+  "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",
+    "test": "node --test test/agents.test.js"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.10.1",
+    "commander": "^13.1.0"
+  }
+}

package/packages/maestro-skills/test/agents.test.js

@@ -0,0 +1,17 @@
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const agents = JSON.parse(
+  readFileSync(join(__dirname, "..", "agents.json"), "utf8"),
+).agents;
+
+test("agents.json includes codex", () => {
+  const codex = agents.find((a) => a.id === "codex");
+  assert.ok(codex);
+  assert.equal(codex.globalSkillsDir, ".codex/skills");
+  assert.equal(codex.skillsCliAgent, "codex");
+});

package/packages/rodovalhofs-maestro/agents.json

@@ -0,0 +1,36 @@
+{
+  "agents": [
+    {
+      "id": "cursor",
+      "label": "Cursor",
+      "globalSkillsDir": ".cursor/skills",
+      "projectSkillsDir": ".cursor/skills",
+      "detectDirs": [".cursor"],
+      "skillsCliAgent": "cursor"
+    },
+    {
+      "id": "claude",
+      "label": "Claude Code",
+      "globalSkillsDir": ".claude/skills",
+      "projectSkillsDir": ".claude/skills",
+      "detectDirs": [".claude"],
+      "skillsCliAgent": "claude"
+    },
+    {
+      "id": "codex",
+      "label": "Codex",
+      "globalSkillsDir": ".codex/skills",
+      "projectSkillsDir": ".codex/skills",
+      "detectDirs": [".codex"],
+      "skillsCliAgent": "codex"
+    },
+    {
+      "id": "universal",
+      "label": "Universal (~/.agents/skills)",
+      "globalSkillsDir": ".agents/skills",
+      "projectSkillsDir": ".agents/skills",
+      "detectDirs": [".agents"],
+      "skillsCliAgent": null
+    }
+  ]
+}

package/packages/rodovalhofs-maestro/bin/cli.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { runRemove } from "../lib/remove.js";
+import { runSetup } from "../lib/setup.js";
+
+const program = new Command();
+program.name("maestro").description("Maestro skill orchestrator (@rodovalhofs/maestro)").version("0.1.0");
+program.command("setup").description("Interactive setup").option("--project").option("--cursor").option("--claude").option("--codex").option("--universal").option("-y, --yes").option("--no-skills-registry").action(runSetup);
+program.command("remove").description("Remove Maestro").option("-y, --yes").option("--all").option("--clean-home").action(runRemove);
+program.parseAsync(process.argv);

package/packages/rodovalhofs-maestro/lib/detect-agents.js

@@ -0,0 +1,28 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { loadAgents } from "./paths.js";
+
+export function detectAgents({ project = false, cwd = process.cwd() } = {}) {
+  const agents = loadAgents();
+  const base = project ? cwd : homedir();
+
+  return agents.map((agent) => {
+    const detected = agent.detectDirs.some((dir) => existsSync(join(base, dir)));
+    return {
+      ...agent,
+      detected: detected || !project,
+      skillsPath: join(base, project ? agent.projectSkillsDir : agent.globalSkillsDir),
+    };
+  });
+}
+
+export function filterAgentsByFlags(agents, flags) {
+  const ids = [];
+  if (flags.cursor) ids.push("cursor");
+  if (flags.claude) ids.push("claude");
+  if (flags.codex) ids.push("codex");
+  if (flags.universal) ids.push("universal");
+  if (!ids.length) return agents;
+  return agents.filter((a) => ids.includes(a.id));
+}