wizz-method 1.0.3 → 1.1.0

package/src/squads/traffic-masters/agents/traffic-chief.md

@@ -0,0 +1,97 @@
+# Traffic Chief
+
+> ACTIVATION-NOTICE: You are the Traffic Chief — orchestrator of the Traffic Masters Squad. You do NOT buy media or write ads. You DIAGNOSE traffic problems, ROUTE them to the correct specialist, and REVIEW their output. You think in platforms, funnels, metrics, and creative. Every traffic problem maps to a platform expert or functional specialist.
+
+## COMPLETE AGENT DEFINITION
+
+```yaml
+agent:
+  name: "Traffic Chief"
+  id: traffic-chief
+  title: "Traffic Masters Orchestrator"
+  icon: "🎯"
+  tier: 0
+  squad: traffic-masters
+  role: orchestrator
+
+persona:
+  role: "Traffic Problem Diagnostician & Squad Router"
+  identity: "The central nervous system of the Traffic Masters Squad. Fluent in all major ad platforms and traffic strategies. Diagnoses whether a traffic problem is platform-specific, creative-related, targeting-based, budget-driven, or funnel-connected. Routes to the right expert or specialist."
+  style: "Analytical, metric-driven, diagnostic. Gets to the root cause fast. Speaks in ROAS, CPA, CTR, and funnel stages."
+
+core_diagnostic:
+  step_1: "What's the ACTUAL problem? (Not enough traffic? Wrong traffic? Traffic that doesn't convert?)"
+  step_2: "Which platform(s)? (Facebook, Google, YouTube, TikTok, LinkedIn, multi-platform)"
+  step_3: "Where in the funnel? (Top = awareness/reach, Middle = consideration/clicks, Bottom = conversion)"
+  step_4: "What's the budget level? (<$1K/mo, $1K-$10K, $10K-$100K, $100K+)"
+  step_5: "Route to the right specialist."
+
+routing_logic:
+  platform_specific:
+    facebook_meta:
+      signals: ["Facebook ads", "Meta ads", "Instagram ads", "Reels ads"]
+      route_to: [molly-pittman, depesh-mandalia, ralph-burns]
+    youtube:
+      signals: ["YouTube ads", "pre-roll", "TrueView", "video ads on YouTube"]
+      route_to: tom-breeze
+    google:
+      signals: ["Google Ads", "Search ads", "Performance Max", "Shopping ads"]
+      route_to: kasim-aslam
+    brazil_latam:
+      signals: ["Brazilian market", "LATAM", "Portuguese-speaking", "gestor de trafego"]
+      route_to: pedro-sobral
+
+  function_specific:
+    creative_problem:
+      signals: ["ads not getting clicks", "creative fatigue", "need better ad creative", "low CTR"]
+      route_to: [ad-midas, creative-analyst]
+    scaling_problem:
+      signals: ["can't scale spend", "CPA increases with budget", "diminishing returns"]
+      route_to: [scale-optimizer, depesh-mandalia]
+    tracking_problem:
+      signals: ["attribution issues", "pixel not firing", "iOS tracking", "conversion tracking broken"]
+      route_to: pixel-specialist
+    analysis_problem:
+      signals: ["don't know what's working", "need audit", "can't read the data"]
+      route_to: [performance-analyst, ads-analyst]
+    budget_problem:
+      signals: ["budget allocation", "cashflow for ads", "ROAS targets", "profitability"]
+      route_to: fiscal
+    execution_problem:
+      signals: ["need someone to set up campaigns", "campaign structure", "media buying"]
+      route_to: media-buyer
+
+quality_review:
+  checks:
+    - "Is the offer validated before spending on ads?"
+    - "Is tracking properly set up?"
+    - "Are we testing creatives systematically?"
+    - "Is the CPA sustainable relative to LTV?"
+    - "Are we scaling profitably, not just spending more?"
+    - "Is there a clear funnel from click to conversion?"
+
+commands:
+  - name: diagnose
+    description: "Diagnose the traffic problem and recommend the right specialist"
+  - name: route
+    description: "Route a specific request to the correct traffic agent"
+  - name: review
+    description: "Review any traffic strategy for completeness"
+  - name: roster
+    description: "Show all 16 Traffic Masters agents and their specialties"
+  - name: metrics
+    description: "Quick metrics health check on any campaign"
+```
+
+---
+
+## How the Traffic Chief Routes
+
+1. **Listen to the problem.** What's actually happening with their traffic/ads?
+2. **Identify the platform.** Facebook? Google? YouTube? Multi-platform?
+3. **Identify the function.** Creative? Targeting? Scaling? Tracking? Budget?
+4. **Check the budget level.** Strategy differs at $1K/mo vs. $100K/mo.
+5. **Route to specialist.** Platform expert for strategy, functional agent for execution.
+6. **Review output.** Does it meet ROAS targets? Is it scalable?
+
+The Chief NEVER writes ads, buys media, or sets up campaigns. The Chief DIAGNOSES and ROUTES.

package/src/squads/traffic-masters/squad.yaml

@@ -0,0 +1,59 @@
+name: traffic-masters
+version: "1.0.0"
+short-title: "Traffic Masters"
+description: "Squad de 16 agentes especialistas em trafego pago. Facebook, YouTube, Google Ads, media buying, creative analysis, scaling, tracking."
+author: "Synkra AIOS"
+license: MIT
+slashPrefix: "traffic-masters"
+
+aios:
+  minVersion: "4.0.0"
+  type: squad
+
+tags:
+  - traffic
+  - ads
+  - facebook
+  - google
+  - youtube
+  - media-buying
+  - creative
+  - scaling
+  - tracking
+
+components:
+  agents:
+    - traffic-chief.md
+    - molly-pittman.md
+    - ralph-burns.md
+    - depesh-mandalia.md
+    - nicholas-kusmich.md
+    - tom-breeze.md
+    - kasim-aslam.md
+    - pedro-sobral.md
+    - ad-midas.md
+    - media-buyer.md
+    - performance-analyst.md
+    - creative-analyst.md
+    - scale-optimizer.md
+    - pixel-specialist.md
+    - ads-analyst.md
+    - fiscal.md
+  tasks:
+    - analyze-performance.md
+    - audit-ad-account.md
+    - create-ad-creative.md
+    - create-ad-strategy.md
+    - diagnose.md
+    - manage-budget.md
+    - review.md
+    - scale-campaign.md
+    - setup-tracking.md
+  workflows:
+    - wf-account-audit.yaml
+    - wf-campaign-launch.yaml
+  checklists:
+    - output-quality.md
+
+config:
+  extends: extend

package/tools/installer/commands/install.js

@@ -18,6 +18,18 @@ module.exports = {
       'Comma-separated list of tool/IDE IDs to configure (e.g., "claude-code,cursor"). Required for fresh non-interactive (--yes) installs. Run with --list-tools to see all valid IDs.',
     ],
     ['--list-tools', 'Print all supported tool/IDE IDs (with target directories) and exit.'],
+    [
+      '--areas <areas>',
+      'Comma-separated global-skill areas to install (e.g. "designer,copy,ads"), or "all". Only applies when the wizz module is selected. Default interactive prompt.',
+    ],
+    [
+      '--mcps <mcps>',
+      'Comma-separated MCP ids to write to .mcp.json for the chosen areas, "all", or "none". Unlisted ones are recommended as `claude mcp add` commands. Only with the wizz module.',
+    ],
+    [
+      '--clis <clis>',
+      'Comma-separated CLI ids to install for the chosen areas (e.g. "agent-browser,rtk"), "all", or "none". Already-installed ones are skipped; unlisted ones are recommended. Only with the wizz module.',
+    ],
     [
       '--set <spec>',
       'Set a module config option non-interactively. Spec format: <module>.<key>=<value> (e.g. bmm.project_knowledge=research). Repeatable. Run --list-options to see available keys.',

package/tools/installer/core/config.js

@@ -7,6 +7,9 @@ class Config {
     directory,
     modules,
     ides,
+    selectedAreas,
+    mcpPlan,
+    cliPlan,
     skipPrompts,
     verbose,
     actionType,
@@ -19,6 +22,20 @@ class Config {
     this.directory = directory;
     this.modules = Object.freeze([...modules]);
     this.ides = Object.freeze([...ides]);
+    // Global-skills areas the user chose to install (from skills-registry.yaml).
+    // Empty means "all areas" when skills-lib is installed; see installSkillsLib.
+    this.selectedAreas = Object.freeze([...(selectedAreas || [])]);
+    // MCP plan resolved from the registry for the chosen areas:
+    //   toWrite     — merged into the project .mcp.json (placeholder secrets)
+    //   toRecommend — printed as `claude mcp add ...` for the user to run later
+    // Empty/absent on quick-update or non-wizz installs. See modules/mcp-config.js.
+    this.mcpPlan = mcpPlan || { toWrite: [], toRecommend: [] };
+    // CLI plan resolved from the registry for the chosen areas:
+    //   toInstall        — `install` command run during the install (opt-in)
+    //   toRecommend      — printed for the user to run later
+    //   alreadyInstalled — detected on PATH, reported and skipped
+    // Empty/absent on quick-update or non-wizz installs. See modules/cli-config.js.
+    this.cliPlan = cliPlan || { toInstall: [], toRecommend: [], alreadyInstalled: [] };
     this.skipPrompts = skipPrompts;
     this.verbose = verbose;
     this.actionType = actionType;
@@ -50,6 +67,9 @@ class Config {
       directory: userInput.directory,
       modules,
       ides: userInput.skipIde ? [] : [...(userInput.ides || [])],
+      selectedAreas: userInput.selectedAreas || [],
+      mcpPlan: userInput.mcpPlan || { toWrite: [], toRecommend: [] },
+      cliPlan: userInput.cliPlan || { toInstall: [], toRecommend: [], alreadyInstalled: [] },
       skipPrompts: userInput.skipPrompts || false,
       verbose: userInput.verbose || false,
       actionType: userInput.actionType,

package/tools/installer/core/installer.js

@@ -2,6 +2,9 @@ const path = require('node:path');
 const fs = require('../fs-native');
 const { Manifest } = require('./manifest');
 const { OfficialModules } = require('../modules/official-modules');
+const { installSkillsLib } = require('../modules/skills-lib');
+const { writeMcpConfig, renderAddCommand } = require('../modules/mcp-config');
+const { installClis, renderInstallCommand } = require('../modules/cli-config');
 const { IdeManager } = require('../ide/manager');
 const { FileOps } = require('../file-ops');
 const { Config } = require('./config');
@@ -297,6 +300,103 @@ class Installer {
         this.installedFiles.add(paths.centralConfig());
         this.installedFiles.add(paths.centralUserConfig());
 
+        // Install the global skills library (area-filtered) BEFORE manifests, so
+        // collectSkills discovers `_wizz/skills-lib/<id>` and the verbatim pipeline
+        // carries them into each IDE. Gated on the `wizz` module; additive, so a
+        // failure here warns and never aborts the install.
+        if (!config.isQuickUpdate() && (config.modules || []).includes('wizz')) {
+          message('Installing global skills...');
+          try {
+            const result = await installSkillsLib({
+              wizzDir: paths.wizzDir,
+              selectedAreas: config.selectedAreas || [],
+              trackFile: (p) => this.installedFiles.add(p),
+            });
+            if (result.registry) {
+              addResult('Global skills', 'ok', `${result.copied} installed`);
+            }
+            if (result.skipped.length > 0) {
+              await prompts.log.warn(`Skills no registry sem pasta em skills-lib (ignoradas): ${result.skipped.join(', ')}`);
+            }
+          } catch (error) {
+            await prompts.log.warn(`Falha ao instalar skills globais: ${error.message}`);
+          }
+
+          // Configure recommended MCP servers for the chosen areas. The user's
+          // multiselect already split them into write vs recommend; we merge the
+          // chosen ones into .mcp.json (additive) and print `claude mcp add` for
+          // the rest. Additive + placeholder-secret, so it never clobbers config
+          // or leaks tokens; a failure warns and never aborts the install.
+          const mcpPlan = config.mcpPlan || { toWrite: [], toRecommend: [] };
+          try {
+            const toWrite = mcpPlan.toWrite || [];
+            if (toWrite.length > 0) {
+              message('Configuring MCP servers...');
+              // Intentionally NOT tracked in installedFiles: .mcp.json is a
+              // shared, user-owned config we merge into (it may hold the user's
+              // own servers). Tracking it would expose it to uninstall removal
+              // and manifest hash-management, which must never touch it.
+              const mcpResult = await writeMcpConfig({
+                projectDir: paths.projectRoot,
+                mcps: toWrite,
+              });
+              if (mcpResult.added.length > 0) {
+                addResult('MCP servers', 'ok', `${mcpResult.added.join(', ')} → .mcp.json`);
+              }
+              if (mcpResult.skipped.length > 0) {
+                await prompts.log.info(`MCPs já presentes no .mcp.json (mantidos): ${mcpResult.skipped.join(', ')}`);
+              }
+            }
+            const toRecommend = mcpPlan.toRecommend || [];
+            if (toRecommend.length > 0) {
+              const lines = toRecommend.map((m) => `  ${renderAddCommand(m)}`).join('\n');
+              await prompts.log.info(`MCPs recomendados (rode quando quiser):\n${lines}`);
+            }
+            // Remind only when a written server expects secrets the user must fill.
+            const needsSecrets = toWrite.filter((m) => m.server && m.server.env && Object.keys(m.server.env).length > 0);
+            if (needsSecrets.length > 0) {
+              const vars = [...new Set(needsSecrets.flatMap((m) => Object.values(m.server.env)))];
+              await prompts.log.warn(`Defina as variáveis de ambiente dos MCPs antes de usar: ${vars.join(', ')}`);
+            }
+          } catch (error) {
+            await prompts.log.warn(`Falha ao configurar MCPs: ${error.message}`);
+          }
+
+          // Install/recommend the CLIs the agents shell out to (agent-browser,
+          // rtk). The ui already detected what's present and split the rest into
+          // install-now vs recommend; here we run the chosen install commands and
+          // print the rest. Install runs system commands (npm install -g, curl |
+          // sh) — a failure warns and never aborts the install. CLIs are not
+          // tracked in installedFiles (they live outside the project tree).
+          const cliPlan = config.cliPlan || { toInstall: [], toRecommend: [], alreadyInstalled: [] };
+          try {
+            const alreadyInstalled = cliPlan.alreadyInstalled || [];
+            if (alreadyInstalled.length > 0) {
+              await prompts.log.info(`CLIs já instalados (mantidos): ${alreadyInstalled.map((c) => c.id).join(', ')}`);
+            }
+            const toInstall = cliPlan.toInstall || [];
+            if (toInstall.length > 0) {
+              message('Installing CLIs...');
+              const cliResult = await installClis({ clis: toInstall });
+              if (cliResult.installed.length > 0) {
+                addResult('CLIs', 'ok', `instalados: ${cliResult.installed.join(', ')}`);
+              }
+              for (const f of cliResult.failed) {
+                await prompts.log.warn(
+                  `Falha ao instalar CLI ${f.id}: ${f.error}. Rode manualmente: ${renderInstallCommand(toInstall.find((c) => c.id === f.id) || {})}`,
+                );
+              }
+            }
+            const toRecommend = cliPlan.toRecommend || [];
+            if (toRecommend.length > 0) {
+              const lines = toRecommend.map((c) => `  ${renderInstallCommand(c)}`).join('\n');
+              await prompts.log.info(`CLIs recomendados (rode quando quiser):\n${lines}`);
+            }
+          } catch (error) {
+            await prompts.log.warn(`Falha ao configurar CLIs: ${error.message}`);
+          }
+        }
+
         message('Generating manifests...');
         const manifestGen = new ManifestGenerator();
         const preservedModules = originalConfig._preserveModules || [];

package/tools/installer/core/manifest-generator.js

@@ -112,7 +112,15 @@ class ManifestGenerator {
     this.skillClaimedDirs = new Set();
     const debug = process.env.WIZZ_DEBUG_MANIFEST === 'true';
 
-    for (const moduleName of this.updatedModules) {
+    // Walk every module, plus the global skills pool (`skills-lib`) when present.
+    // skills-lib is intentionally excluded from this.modules (no versioning), so
+    // we append it here as a scan target only.
+    const scanTargets = [...this.updatedModules];
+    if (await fs.pathExists(path.join(this.wizzDir, 'skills-lib'))) {
+      scanTargets.push('skills-lib');
+    }
+
+    for (const moduleName of scanTargets) {
       const modulePath = path.join(this.wizzDir, moduleName);
       if (!(await fs.pathExists(modulePath))) continue;
 
@@ -752,8 +760,11 @@ class ManifestGenerator {
       const entries = await fs.readdir(wizzDir, { withFileTypes: true });
 
       for (const entry of entries) {
-        // Skip if not a directory or is a special directory
-        if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === '_config') {
+        // Skip if not a directory or is a special directory.
+        // `skills-lib` is the global skills pool (no module.yaml, not versioned);
+        // it is walked explicitly by collectSkills, but must NOT be treated as a
+        // module here or writeMainManifest/writeCentralConfig would try to version it.
+        if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === '_config' || entry.name === 'skills-lib') {
           continue;
         }
 

package/tools/installer/modules/cli-config.js

@@ -0,0 +1,145 @@
+// Resolves + installs the command-line tools the agents shell out to.
+//
+// Sibling of modules/mcp-config.js. Where MCPs are *servers* merged into the
+// project's .mcp.json, CLIs are *binaries* the agents call directly (e.g.
+// `agent-browser` for browser verification, `rtk` for token economy). The
+// skills-registry.yaml is the single source of truth for both: each AREA may
+// declare a `clis:` list, plus a top-level `cli_utility:` for cross-cutting
+// tools. Each entry has:
+//   id      — the command name (used to detect + label)
+//   when    — when this CLI helps (same disambiguation role as skills' `when`)
+//   check   — command run to detect if it is ALREADY installed (e.g. `x --version`)
+//   install — command run to install it (e.g. `npm install -g x`, `curl … | sh`)
+//
+// Design rules (deliberately conservative, mirroring mcp-config):
+//   - DETECT FIRST: never reinstall something already on PATH. `check` decides.
+//   - INSTALL IS OPT-IN: the caller (the interactive multiselect / --clis flag)
+//     decides what to actually install; everything else is merely recommended
+//     by printing its `install` command. Nothing runs without an explicit choice.
+//   - NO-OP WHEN ABSENT: missing registry / no CLIs => empty, runs nothing.
+//   - FAILURE NEVER THROWS UPSTREAM: installClis collects failures and returns
+//     them so a bad network / EACCES never aborts the whole install.
+//
+// The install/check commands come from our own registry (not user input), and
+// running them (npm install -g, curl | sh) is inherently a trust-the-source
+// operation — hence install is opt-in and recommend-only by default.
+
+const { exec } = require('node:child_process');
+const { promisify } = require('node:util');
+
+const execAsync = promisify(exec);
+
+/**
+ * Default command runner: runs a shell command, never throws. A non-zero exit
+ * resolves to `{ ok: false, ... }` so callers branch on `ok`, not exceptions.
+ * Uses a shell so registry commands with pipes (`curl … | sh`) work as written.
+ * @param {string} command - Full shell command to run
+ * @param {{timeoutMs?: number}} [opts]
+ * @returns {Promise<{ok: boolean, stdout: string, stderr: string}>}
+ */
+async function defaultExec(command, { timeoutMs = 300_000 } = {}) {
+  try {
+    const { stdout, stderr } = await execAsync(command, { timeout: timeoutMs });
+    return { ok: true, stdout: stdout || '', stderr: stderr || '' };
+  } catch (error) {
+    return { ok: false, stdout: error.stdout || '', stderr: error.stderr || error.message || '' };
+  }
+}
+
+/**
+ * Resolve the recommended CLI entries for the chosen areas, deduped by id.
+ * Empty / undefined / containing 'all' means every area. The cross-cutting
+ * `cli_utility:` tools are always included. Entries missing `id` or `install`
+ * are dropped — a CLI we cannot install is not actionable.
+ *
+ * @param {Object} registry - Parsed skills-registry.yaml
+ * @param {string[]} [selectedAreas] - Area keys to resolve
+ * @returns {Array<{id: string, when: string, check: string, install: string, areas: string[]}>}
+ */
+function resolveClis(registry, selectedAreas) {
+  const byId = new Map();
+  const areas = (registry && registry.areas) || {};
+  const wantAll = !selectedAreas || selectedAreas.length === 0 || selectedAreas.includes('all');
+  const chosen = wantAll ? Object.keys(areas) : selectedAreas;
+
+  const add = (cli, areaKey) => {
+    if (!cli || !cli.id || !cli.install) return; // not actionable without an install command
+    const existing = byId.get(cli.id);
+    if (existing) {
+      if (areaKey && !existing.areas.includes(areaKey)) existing.areas.push(areaKey);
+      return;
+    }
+    byId.set(cli.id, {
+      id: cli.id,
+      when: cli.when || '',
+      check: cli.check || '',
+      install: cli.install,
+      areas: areaKey ? [areaKey] : [],
+    });
+  };
+
+  for (const area of chosen) {
+    for (const cli of (areas[area] && areas[area].clis) || []) add(cli, area);
+  }
+  // Cross-cutting tools are offered regardless of area selection.
+  for (const cli of (registry && registry.cli_utility) || []) add(cli, null);
+
+  return [...byId.values()];
+}
+
+/**
+ * The copy-pasteable install command for a CLI entry — used to recommend the
+ * tools the user chose NOT to install (nothing is lost; they run it later).
+ * @param {{install?: string}} cli - Resolved CLI entry
+ * @returns {string} The install command, or '' if none.
+ */
+function renderInstallCommand(cli) {
+  return (cli && cli.install) || '';
+}
+
+/**
+ * Annotate each CLI with `installed: boolean` by running its `check` command.
+ * Immutable: returns new objects, never mutates the input. An entry without a
+ * `check` cannot be verified, so it is reported as not installed (we offer it
+ * rather than silently assume it is present).
+ *
+ * @param {Array<Object>} clis - Resolved CLI entries
+ * @param {Function} [exec] - Injected runner (command, opts) => {ok,...}
+ * @returns {Promise<Array<Object>>} Copies with an added `installed` flag.
+ */
+async function detectClis(clis, exec = defaultExec) {
+  return Promise.all(
+    (clis || []).map(async (cli) => {
+      if (!cli.check) return { ...cli, installed: false };
+      const res = await exec(cli.check, { timeoutMs: 5000 });
+      return { ...cli, installed: !!res.ok };
+    }),
+  );
+}
+
+/**
+ * Run the install command for each CLI, collecting outcomes. Never throws:
+ * a failed install (network, EACCES, missing command) lands in `failed` with
+ * its error so the caller can warn and continue the broader install.
+ *
+ * @param {Object} args
+ * @param {Array<{id: string, install?: string}>} args.clis - Entries to install
+ * @param {Function} [args.exec] - Injected runner (command, opts) => {ok,...}
+ * @returns {Promise<{installed: string[], failed: Array<{id: string, error: string}>}>}
+ */
+async function installClis({ clis, exec = defaultExec }) {
+  const installed = [];
+  const failed = [];
+  for (const cli of clis || []) {
+    if (!cli.install) {
+      failed.push({ id: cli.id, error: 'sem comando de instalação no registry' });
+      continue;
+    }
+    const res = await exec(cli.install, { timeoutMs: 300_000 });
+    if (res.ok) installed.push(cli.id);
+    else failed.push({ id: cli.id, error: (res.stderr || 'falha desconhecida').trim() });
+  }
+  return { installed, failed };
+}
+
+module.exports = { resolveClis, renderInstallCommand, detectClis, installClis, defaultExec };

package/tools/installer/modules/mcp-config.js

@@ -0,0 +1,137 @@
+// Configures the recommended MCP servers for the chosen skill areas.
+//
+// The skills-registry.yaml is the single source of truth: besides mapping each
+// AREA to its skills, it declares an `mcps:` list per area (plus a top-level
+// `mcp_utility:` for cross-cutting servers like context7). This module reads
+// that registry, resolves the user's chosen areas to a deduped set of MCP
+// entries, and MERGES the selected ones into the project's `.mcp.json`.
+//
+// Design rules (kept deliberately conservative):
+//   - ADDITIVE: an existing server with the same id is never overwritten. The
+//     user's hand-tuned config always wins; we only ADD what is missing.
+//   - SECRETS STAY PLACEHOLDERS: `env` values come straight from the registry
+//     as `${VAR}` placeholders. We never read, infer, or write a real token.
+//   - NO-OP WHEN ABSENT: missing registry / no MCPs => returns empty, writes
+//     nothing. Always safe to call.
+//
+// The caller decides WHICH ids to write (the interactive multiselect) and which
+// to merely recommend; this module exposes the resolution + merge primitives and
+// a `claude mcp add` command renderer for the recommend path.
+
+const path = require('node:path');
+const fs = require('../fs-native');
+
+/**
+ * Resolve the recommended MCP entries for the chosen areas, deduped by id.
+ * Empty / undefined / containing 'all' means every area. The cross-cutting
+ * `mcp_utility:` servers are always included.
+ *
+ * @param {Object} registry - Parsed skills-registry.yaml
+ * @param {string[]} [selectedAreas] - Area keys to resolve
+ * @returns {Array<{id: string, when: string, server: Object, areas: string[]}>}
+ *   One entry per unique MCP id, carrying which area(s) recommended it.
+ */
+function resolveMcps(registry, selectedAreas) {
+  const byId = new Map();
+  const areas = (registry && registry.areas) || {};
+  const wantAll = !selectedAreas || selectedAreas.length === 0 || selectedAreas.includes('all');
+  const chosen = wantAll ? Object.keys(areas) : selectedAreas;
+
+  const add = (mcp, areaKey) => {
+    if (!mcp || !mcp.id || !mcp.server) return;
+    const existing = byId.get(mcp.id);
+    if (existing) {
+      if (areaKey && !existing.areas.includes(areaKey)) existing.areas.push(areaKey);
+      return;
+    }
+    byId.set(mcp.id, {
+      id: mcp.id,
+      when: mcp.when || '',
+      server: mcp.server,
+      areas: areaKey ? [areaKey] : [],
+    });
+  };
+
+  for (const area of chosen) {
+    for (const mcp of (areas[area] && areas[area].mcps) || []) add(mcp, area);
+  }
+  // Cross-cutting servers are offered regardless of area selection.
+  for (const mcp of (registry && registry.mcp_utility) || []) add(mcp, null);
+
+  return [...byId.values()];
+}
+
+/**
+ * Normalize a registry `server` block into the shape written to `.mcp.json`.
+ * Drops empty `args`/`env` so the output stays minimal and diff-friendly.
+ * @param {Object} server - { command, args?, env? } from the registry
+ * @returns {Object} Sanitized server config
+ */
+function toServerConfig(server) {
+  const out = { command: server.command };
+  if (Array.isArray(server.args) && server.args.length > 0) out.args = [...server.args];
+  if (server.env && Object.keys(server.env).length > 0) out.env = { ...server.env };
+  return out;
+}
+
+/**
+ * Render the `claude mcp add` command for an MCP entry — used to recommend
+ * servers the user chose NOT to write (nothing is lost; they can add later).
+ * @param {{id: string, server: Object}} mcp - Resolved MCP entry
+ * @returns {string} A copy-pasteable shell command
+ */
+function renderAddCommand({ id, server }) {
+  const envFlags = Object.entries(server.env || {})
+    .map(([k, v]) => `-e ${k}=${v}`)
+    .join(' ');
+  const args = (server.args || []).join(' ');
+  const cmd = `${server.command}${args ? ` ${args}` : ''}`;
+  return `claude mcp add ${id}${envFlags ? ` ${envFlags}` : ''} -- ${cmd}`.replaceAll(/\s+/g, ' ').trim();
+}
+
+/**
+ * Merge the chosen MCP entries into `<projectDir>/.mcp.json`, additively.
+ * Reads any existing file (preserving unknown keys and existing servers),
+ * adds only ids not already present, and writes back pretty-printed JSON.
+ *
+ * @param {Object} args
+ * @param {string} args.projectDir - Project root where `.mcp.json` lives
+ * @param {Array<{id: string, server: Object}>} args.mcps - Entries to write
+ * @param {(absPath: string) => void} [args.trackFile] - Record the written file
+ * @returns {Promise<{added: string[], skipped: string[], file: string|null}>}
+ *   `added` = ids newly written, `skipped` = ids already present (left intact).
+ */
+async function writeMcpConfig({ projectDir, mcps, trackFile = () => {} }) {
+  if (!mcps || mcps.length === 0) return { added: [], skipped: [], file: null };
+
+  const file = path.join(projectDir, '.mcp.json');
+  let config = {};
+  if (await fs.pathExists(file)) {
+    try {
+      config = JSON.parse(await fs.readFile(file, 'utf8'));
+    } catch (error) {
+      throw new Error(`.mcp.json existe mas não é JSON válido: ${error.message}`);
+    }
+  }
+  if (!config || typeof config !== 'object') config = {};
+  if (!config.mcpServers || typeof config.mcpServers !== 'object') config.mcpServers = {};
+
+  const added = [];
+  const skipped = [];
+  for (const mcp of mcps) {
+    if (Object.prototype.hasOwnProperty.call(config.mcpServers, mcp.id)) {
+      skipped.push(mcp.id); // never clobber the user's existing server
+      continue;
+    }
+    config.mcpServers[mcp.id] = toServerConfig(mcp.server);
+    added.push(mcp.id);
+  }
+
+  if (added.length === 0) return { added, skipped, file };
+
+  await fs.writeJson(file, config, { spaces: 2 });
+  trackFile(file);
+  return { added, skipped, file };
+}
+
+module.exports = { resolveMcps, toServerConfig, renderAddCommand, writeMcpConfig };