sinapse-ai 1.23.0 → 1.25.0

package/scripts/research/generate-react-bits-catalog.mjs

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, statSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const args = process.argv.slice(2);
+const valueOf = flag => {
+  const index = args.indexOf(flag);
+  return index === -1 ? undefined : args[index + 1];
+};
+
+const repo = resolve(valueOf('--repo') || '../.tmp-react-bits-research');
+const output = resolve(valueOf('--output') || 'docs/framework/react-bits');
+const infoPath = join(repo, 'src', 'constants', 'Information.js');
+
+if (!existsSync(join(repo, '.git')) || !existsSync(infoPath)) {
+  throw new Error(`React Bits checkout not found or incomplete: ${repo}`);
+}
+
+const sha = execFileSync('git', ['-C', repo, 'rev-parse', 'HEAD'], { encoding: 'utf8' }).trim();
+const commitDate = execFileSync('git', ['-C', repo, 'show', '-s', '--format=%cI', 'HEAD'], {
+  encoding: 'utf8'
+}).trim();
+const { componentMetadata, VARIANTS } = await import(`${pathToFileURL(infoPath).href}?sha=${sha}`);
+
+if (!componentMetadata || !Array.isArray(VARIANTS) || VARIANTS.length !== 4) {
+  throw new Error('Required React Bits metadata exports are missing or changed');
+}
+
+const categories = ['Animations', 'TextAnimations', 'Components', 'Backgrounds'];
+const categorySlugs = {
+  Animations: 'animations',
+  TextAnimations: 'text-animations',
+  Components: 'components',
+  Backgrounds: 'backgrounds'
+};
+
+const walk = directory =>
+  readdirSync(directory, { withFileTypes: true }).flatMap(entry => {
+    const path = join(directory, entry.name);
+    return entry.isDirectory() ? walk(path) : [path];
+  });
+
+const codeMetadataFiles = walk(join(repo, 'src', 'constants', 'code')).filter(path => path.endsWith('.js'));
+const codeMetadata = new Map();
+
+for (const path of codeMetadataFiles) {
+  const source = readFileSync(path, 'utf8');
+  const sourceMatch = source.match(/@(?:content|ts-default)\/([^/]+)\/([^/]+)\//);
+  if (!sourceMatch) continue;
+  const dependencyMatch = source.match(/dependencies\s*:\s*([`'"])([\s\S]*?)\1/);
+  const dependencies = dependencyMatch
+    ? dependencyMatch[2].replace(/^\s*(?:npm|pnpm|yarn|bun)\s+(?:i|install|add)\s+/, '').trim()
+    : '';
+  codeMetadata.set(`${sourceMatch[1]}/${sourceMatch[2]}`.toLowerCase(), { dependencies, path });
+}
+
+const findComponentDirectory = (category, name) => {
+  const root = join(repo, 'src', 'ts-default', category);
+  const match = readdirSync(root, { withFileTypes: true }).find(
+    entry => entry.isDirectory() && entry.name.toLowerCase() === name.toLowerCase()
+  );
+  if (!match) throw new Error(`Missing TS source directory for ${category}/${name}`);
+  return join(root, match.name);
+};
+
+const extractProps = source => {
+  const blocks = [];
+  const declarations = /(?:type|interface)\s+\w*Props\w*(?:\s+extends[^\{]+)?\s*(?:=\s*)?\{/g;
+  for (const match of source.matchAll(declarations)) {
+    let depth = 1;
+    let cursor = match.index + match[0].length;
+    const start = cursor;
+    while (cursor < source.length && depth > 0) {
+      if (source[cursor] === '{') depth += 1;
+      if (source[cursor] === '}') depth -= 1;
+      cursor += 1;
+    }
+    blocks.push(source.slice(start, cursor - 1));
+  }
+
+  const props = new Set();
+  for (const block of blocks) {
+    for (const line of block.split('\n')) {
+      const match = line.match(/^\s*(?:readonly\s+)?([A-Za-z_$][\w$]*)\??\s*:/);
+      if (match) props.add(match[1]);
+    }
+  }
+  return [...props];
+};
+
+const escapeCell = value => String(value || '').replaceAll('|', '\\|').replaceAll('\n', ' ');
+const entries = Object.entries(componentMetadata).map(([key, metadata]) => {
+  const directory = findComponentDirectory(metadata.category, metadata.name);
+  const sourceFile = readdirSync(directory).find(file => file.endsWith('.tsx'));
+  if (!sourceFile) throw new Error(`Missing TSX source for ${key}`);
+  const source = readFileSync(join(directory, sourceFile), 'utf8');
+  const demoPath = join(repo, 'src', 'demo', metadata.category, `${metadata.name}Demo.jsx`);
+  const demo = existsSync(demoPath) ? readFileSync(demoPath, 'utf8') : '';
+  const demoProps = [...demo.matchAll(/\bname\s*:\s*['"]([^'"]+)['"]/g)].map(match => match[1]);
+  const props = [...new Set(demoProps.length ? demoProps : extractProps(source))];
+  const code = codeMetadata.get(key.toLowerCase()) || codeMetadata.get(
+    `${metadata.category}/${basename(directory)}`.toLowerCase()
+  );
+  if (!code) throw new Error(`Missing code metadata for ${key}`);
+
+  const variantConfig = {
+    'JS-CSS': { root: 'content', extension: 'jsx' },
+    'JS-TW': { root: 'tailwind', extension: 'jsx' },
+    'TS-CSS': { root: 'ts-default', extension: 'tsx' },
+    'TS-TW': { root: 'ts-tailwind', extension: 'tsx' }
+  };
+  const declaredVariants = metadata.variants || VARIANTS;
+  const variants = Object.fromEntries(declaredVariants.map(variant => {
+    const config = variantConfig[variant];
+    const sourcePath = join(repo, 'src', config.root, metadata.category, basename(directory), `${basename(directory)}.${config.extension}`);
+    const registryPath = join(repo, 'public', 'r', `${metadata.name}-${variant}.json`);
+    if (!existsSync(sourcePath) || !existsSync(registryPath)) throw new Error(`Missing published variant ${key}/${variant}`);
+    const registry = JSON.parse(readFileSync(registryPath, 'utf8'));
+    const sourceBytes = statSync(sourcePath).size;
+    return [variant, {
+      source: sourcePath.slice(repo.length + 1).replaceAll('\\', '/'),
+      sourceBytes,
+      functional: sourceBytes > 0,
+      dependencies: registry.dependencies || [],
+      registryDependencies: registry.registryDependencies || []
+    }];
+  }));
+
+  return {
+    key,
+    ...metadata,
+    documentedDependencies: code.dependencies ? code.dependencies.split(/\s+/).filter(Boolean) : [],
+    dependencies: [...new Set(Object.values(variants).flatMap(variant => variant.dependencies))],
+    props,
+    variants,
+    sourceDirectory: basename(directory),
+    sourceFile
+  };
+});
+
+mkdirSync(output, { recursive: true });
+for (const category of categories) {
+  const list = entries.filter(entry => entry.category === category).sort((a, b) => a.name.localeCompare(b.name));
+  const lines = [
+    `# React Bits - ${category}`,
+    '',
+    `> Snapshot oficial: \`${sha}\` (${commitDate}). Total nesta categoria: **${list.length}**.`,
+    '',
+    'Cada item abaixo aponta para a documentacao e para o codigo TypeScript/CSS oficial fixado no commit pesquisado.',
+    '',
+    '| Componente | O que faz | Dependencias | Props publicas | Variantes |',
+    '|---|---|---|---|---|'
+  ];
+
+  for (const entry of list) {
+    const sourceUrl = `https://github.com/DavidHDev/react-bits/tree/${sha}/src/ts-default/${entry.category}/${entry.sourceDirectory}`;
+    const label = `[${entry.name}](${entry.docsUrl}) ([fonte](${sourceUrl}))`;
+    const props = entry.props.length ? entry.props.map(prop => `\`${prop}\``).join(', ') : 'children / DOM props';
+    const variantStatus = Object.entries(entry.variants)
+      .map(([variant, details]) => details.functional ? variant : `${variant} (VAZIA no upstream)`)
+      .join(', ');
+    const dependencies = entry.dependencies.length ? entry.dependencies.join(' ') : 'none';
+    lines.push(
+      `| ${label} | ${escapeCell(entry.description)} | \`${escapeCell(dependencies)}\` | ${escapeCell(props)} | ${variantStatus} |`
+    );
+  }
+
+  lines.push('', '## Comandos por componente', '');
+  lines.push('Substituir `<Component>` pelo nome exato da primeira coluna:');
+  lines.push('', '```bash');
+  lines.push('npx shadcn@latest add @react-bits/<Component>-TS-TW');
+  lines.push('npx shadcn@latest add https://reactbits.dev/r/<Component>-TS-TW');
+  lines.push('npx jsrepo@latest add https://reactbits.dev/r/<Component>-TS-TW');
+  lines.push('```', '');
+  writeFileSync(join(output, `${categorySlugs[category]}.md`), `${lines.join('\n')}\n`);
+}
+
+const dependencyCounts = new Map();
+for (const entry of entries) {
+  const packages = entry.dependencies;
+  for (const packageName of packages) dependencyCounts.set(packageName, (dependencyCounts.get(packageName) || 0) + 1);
+}
+
+const incompleteVariants = entries.flatMap(entry => Object.entries(entry.variants)
+  .filter(([, details]) => !details.functional)
+  .map(([variant, details]) => ({ component: entry.name, category: entry.category, variant, source: details.source })));
+
+const summary = {
+  source: 'https://github.com/DavidHDev/react-bits',
+  sha,
+  commitDate,
+  total: entries.length,
+  categories: Object.fromEntries(categories.map(category => [category, entries.filter(item => item.category === category).length])),
+  variants: VARIANTS,
+  registryItems: entries.reduce((total, entry) => total + Object.keys(entry.variants).length, 0),
+  documentedProps: entries.reduce((total, entry) => total + entry.props.length, 0),
+  incompleteVariants,
+  dependencies: Object.fromEntries([...dependencyCounts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])))
+};
+writeFileSync(join(output, 'catalog-summary.json'), `${JSON.stringify(summary, null, 2)}\n`);
+writeFileSync(join(output, 'inventory.json'), `${JSON.stringify({ ...summary, components: entries }, null, 2)}\n`);
+
+process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);

package/scripts/sync-provider-adapters.js

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+const {
+  collectNativeAgentDefinitions,
+  readCodexCatalog,
+  syncCodexNativeAgents,
+} = require('../.codex/scripts/sync-codex-native');
+const { resolveCodexAgent } = require('../.codex/scripts/resolve-codex-agent');
+
+const PROJECT_ROOT = path.resolve(__dirname, '..');
+const CLAUDE_AGENTS_DIR = '.claude/agents';
+const CLAUDE_SKILLS_DIR = '.claude/skills';
+
+function writeFileAtomically(filePath, content) {
+  const temporaryPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  let handle;
+  try {
+    handle = fs.openSync(temporaryPath, 'wx', 0o600);
+    fs.writeFileSync(handle, content, 'utf8');
+    fs.fsyncSync(handle);
+    fs.closeSync(handle);
+    handle = undefined;
+    fs.renameSync(temporaryPath, filePath);
+  } finally {
+    if (handle !== undefined) fs.closeSync(handle);
+    try { fs.unlinkSync(temporaryPath); } catch { /* already published or cleanup is best-effort */ }
+  }
+}
+
+function writeFileIfChanged(filePath, content) {
+  let existing = null;
+  try {
+    existing = fs.readFileSync(filePath, 'utf8');
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  if (existing !== null && existing.replace(/\r\n/g, '\n') === content.replace(/\r\n/g, '\n')) {
+    return 'unchanged';
+  }
+  const status = existing === null ? 'created' : 'updated';
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  writeFileAtomically(filePath, content);
+  return status;
+}
+
+function claudeAgentFileName(definition) {
+  return `sinapse-${definition.id}.md`;
+}
+
+function renderClaudeAgent(definition) {
+  const orchestratorRule = /-orqx$/.test(definition.id) || definition.id === 'snps-orqx'
+    ? 'You coordinate and delegate domain execution; do not perform specialist work directly.'
+    : 'Work only within the authority declared by the canonical agent.';
+  return [
+    '---',
+    `name: ${definition.name}`,
+    `description: ${JSON.stringify(definition.description)}`,
+    '---',
+    '',
+    `# SINAPSE Claude Adapter: ${definition.name}`,
+    '',
+    `Read and follow \`${definition.sourcePath}\` as the canonical source of truth.`,
+    'Adopt its persona, authority boundaries, activation protocol, declared dependencies,',
+    'task inputs, outputs, gates and verification requirements.',
+    orchestratorRule,
+    'Resolve requested commands only from dependencies declared by the canonical source.',
+    'Use Claude Code native subagents or teams for delegation; never start a nested CLI.',
+    'Follow project CLAUDE.md and the SINAPSE Constitution before acting.',
+    '',
+  ].join('\n');
+}
+
+function parseSkillMetadata(content) {
+  const match = String(content).match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) throw new Error('Skill is missing YAML frontmatter');
+  const metadata = yaml.load(match[1]);
+  if (!metadata?.name || !metadata?.description) throw new Error('Skill frontmatter is incomplete');
+  return metadata;
+}
+
+function renderClaudeWorkflowSkill(skillId, description) {
+  if (skillId === 'sinapse-loop') {
+    return [
+      '---', `name: ${skillId}`, `description: ${description}`, '---', '',
+      '# SINAPSE Bounded Loop for Claude Code', '',
+      'Activate only when the user explicitly requests this loop. Obtain a verifiable',
+      'completion criterion, then repeat inspect -> delegate correction -> verify for at',
+      'most three iterations. Stop on completion, block, user stop, or iteration three.',
+      'Use Claude Code native subagents; never launch a nested Claude or Codex process.', '',
+    ].join('\n');
+  }
+  return [
+    '---', `name: ${skillId}`, `description: ${description}`, '---', '',
+    '# SINAPSE Spec-Driven Workflow for Claude Code', '',
+    'Read `.sinapse-ai/development/workflows/spec-pipeline.yaml` and its referenced task',
+    'contracts. Follow PRD -> Epic -> Story -> Validation -> Implementation, delegating',
+    'each phase through Claude Code native subagents. A task contract controls inputs,',
+    'outputs, gates and verification. Never implement before a validated Ready story.', '',
+  ].join('\n');
+}
+
+function renderClaudeGenericSkill(skillId, description) {
+  return [
+    '---', `name: ${skillId}`, `description: ${description.replace(/Codex/g, 'Claude Code')}`, '---', '',
+    '# SINAPSE Parametric Agent Activator for Claude Code', '',
+    'Use the agent ID supplied with this skill. Find the matching project subagent by its',
+    '`name` frontmatter under `.claude/agents/sinapse-*.md`. Reject unknown IDs instead',
+    'of guessing. Invoke that native subagent with `@<name>` when delegation is',
+    'appropriate, and preserve its canonical authority and task contracts.', '',
+  ].join('\n');
+}
+
+function renderClaudeAgentSkill(skillId, description, projectRoot) {
+  const resolved = resolveCodexAgent(skillId, projectRoot);
+  const publicName = resolved.agentId === 'snps-orqx' ? 'sinapse-orqx' : resolved.agentId;
+  return [
+    '---', `name: ${skillId}`, `description: ${description.replace(/Codex/g, 'Claude Code')}`, '---', '',
+    `# SINAPSE Claude Activation: ${publicName}`, '',
+    `Read \`${resolved.sourceOfTruth}\` as the canonical source of truth.`,
+    `Use the native Claude subagent \`@agent-${publicName}\` for isolated delegation,`,
+    'or adopt the same persona in the current context when the workflow must remain here.',
+    'Follow declared dependencies and authority boundaries. Never invoke a nested CLI.', '',
+  ].join('\n');
+}
+
+function collectClaudeSkills(projectRoot = PROJECT_ROOT) {
+  const catalog = readCodexCatalog(projectRoot);
+  const skillIds = [...new Set([
+    ...catalog.expectedSkillIds,
+    ...catalog.publicAliasSkillIds,
+    catalog.genericAgentSkillId,
+  ])].sort();
+
+  return skillIds.map((skillId) => {
+    const nativePath = path.join(projectRoot, '.agents', 'skills', skillId, 'SKILL.md');
+    const metadata = parseSkillMetadata(fs.readFileSync(nativePath, 'utf8'));
+    let content;
+    if (skillId === catalog.genericAgentSkillId) {
+      content = renderClaudeGenericSkill(skillId, metadata.description);
+    } else if (skillId === 'sinapse-loop' || skillId === 'sinapse-spec-driven') {
+      content = renderClaudeWorkflowSkill(skillId, metadata.description);
+    } else {
+      content = renderClaudeAgentSkill(skillId, metadata.description, projectRoot);
+    }
+    return { skillId, content };
+  });
+}
+
+function syncClaudeNative(projectRoot = PROJECT_ROOT) {
+  const definitions = collectNativeAgentDefinitions(projectRoot);
+  const skills = collectClaudeSkills(projectRoot);
+  const summary = {
+    agents: { total: definitions.length, created: 0, updated: 0, unchanged: 0 },
+    skills: { total: skills.length, created: 0, updated: 0, unchanged: 0 },
+  };
+
+  for (const definition of definitions) {
+    const target = path.join(projectRoot, CLAUDE_AGENTS_DIR, claudeAgentFileName(definition));
+    summary.agents[writeFileIfChanged(target, renderClaudeAgent(definition))] += 1;
+  }
+  for (const skill of skills) {
+    const target = path.join(projectRoot, CLAUDE_SKILLS_DIR, skill.skillId, 'SKILL.md');
+    summary.skills[writeFileIfChanged(target, skill.content)] += 1;
+  }
+  writeFileIfChanged(
+    path.join(projectRoot, '.claude', 'skill-manifest.json'),
+    `${JSON.stringify({ version: 1, skillIds: skills.map((skill) => skill.skillId).sort() }, null, 2)}\n`,
+  );
+  return summary;
+}
+
+function syncProviderAdapters(projectRoot = PROJECT_ROOT, options = {}) {
+  const codex = syncCodexNativeAgents(projectRoot, options);
+  const claude = syncClaudeNative(projectRoot);
+  return { codex, claude };
+}
+
+function main() {
+  try {
+    const expandedSkills = process.argv.slice(2).includes('--expanded-skills');
+    console.log(JSON.stringify(syncProviderAdapters(PROJECT_ROOT, { expandedSkills }), null, 2));
+  } catch (error) {
+    console.error(`[sync-provider-adapters] ${error.message}`);
+    process.exitCode = 1;
+  }
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  CLAUDE_AGENTS_DIR,
+  CLAUDE_SKILLS_DIR,
+  claudeAgentFileName,
+  renderClaudeAgent,
+  collectClaudeSkills,
+  syncClaudeNative,
+  syncProviderAdapters,
+};

package/scripts/validate-provider-adapters.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+const { validateNativeCodex } = require('../.codex/scripts/validate-codex-native');
+
+const PROJECT_ROOT = path.resolve(__dirname, '..');
+
+function parseFrontmatter(content) {
+  const match = String(content).match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) throw new Error('missing YAML frontmatter');
+  const metadata = yaml.load(match[1]);
+  if (!metadata || typeof metadata !== 'object') throw new Error('invalid YAML frontmatter');
+  return metadata;
+}
+
+function validateClaudeNative(projectRoot = PROJECT_ROOT) {
+  const errors = [];
+  const agentsDir = path.join(projectRoot, '.claude', 'agents');
+  const agentFiles = fs.existsSync(agentsDir)
+    ? fs.readdirSync(agentsDir).filter((file) => /^sinapse-.+\.md$/.test(file)).sort()
+    : [];
+  const manifestPath = path.join(projectRoot, '.claude', 'skill-manifest.json');
+  let expectedSkills = [];
+  try {
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    expectedSkills = (manifest.skillIds || []).map((skillId) => ({ skillId }));
+    if (expectedSkills.length !== 36) errors.push(`Claude skill manifest must contain 36 IDs, found ${expectedSkills.length}`);
+  } catch (error) {
+    errors.push(`Claude skill manifest: ${error.message}`);
+  }
+
+  if (agentFiles.length !== 172) errors.push(`Claude native inventory must contain 172 agents, found ${agentFiles.length}`);
+  const claudeNames = new Set();
+  let claudeAgents = 0;
+  for (const file of agentFiles) {
+    const relativePath = path.join('.claude', 'agents', file);
+    const filePath = path.join(projectRoot, relativePath);
+    claudeAgents += 1;
+    try {
+      const content = fs.readFileSync(filePath, 'utf8');
+      const metadata = parseFrontmatter(content);
+      if (!String(metadata.name || '').trim()) errors.push(`${relativePath} has no name`);
+      if (!String(metadata.description || '').trim()) errors.push(`${relativePath} has no description`);
+      if (claudeNames.has(metadata.name)) errors.push(`Duplicate Claude native agent name: ${metadata.name}`);
+      claudeNames.add(metadata.name);
+      const sourceMatch = content.match(/`((?:\.sinapse-ai\/development\/agents|squads\/[^/]+\/agents)\/[^`]+\.md)`/);
+      if (!sourceMatch) errors.push(`${relativePath} does not declare a canonical source`);
+      else if (!fs.existsSync(path.join(projectRoot, sourceMatch[1]))) errors.push(`${relativePath} points to missing ${sourceMatch[1]}`);
+      if (/[A-Za-z]:[\\/]/.test(content)) errors.push(`${relativePath} contains a personal absolute path`);
+    } catch (error) {
+      errors.push(`${relativePath}: ${error.message}`);
+    }
+  }
+
+  let claudeSkills = 0;
+  for (const expected of expectedSkills) {
+    const relativePath = path.join('.claude', 'skills', expected.skillId, 'SKILL.md');
+    const filePath = path.join(projectRoot, relativePath);
+    if (!fs.existsSync(filePath)) {
+      errors.push(`Missing Claude native skill: ${relativePath}`);
+      continue;
+    }
+    claudeSkills += 1;
+    try {
+      const metadata = parseFrontmatter(fs.readFileSync(filePath, 'utf8'));
+      if (metadata.name !== expected.skillId) errors.push(`${relativePath} has incorrect name ${metadata.name}`);
+    } catch (error) {
+      errors.push(`${relativePath}: ${error.message}`);
+    }
+  }
+
+  for (const name of ['claude-mastery-chief', 'swarm-orqx', 'sinapse-orqx', 'meta-ads-specialist']) {
+    if (!claudeNames.has(name)) errors.push(`Claude native inventory is missing ${name}`);
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    metrics: {
+      canonicalAgents: agentFiles.length,
+      claudeAgents,
+      claudeSkills,
+    },
+  };
+}
+
+function validateProviderAdapters(projectRoot = PROJECT_ROOT) {
+  const claude = validateClaudeNative(projectRoot);
+  const codex = validateNativeCodex(projectRoot);
+  const errors = [
+    ...claude.errors.map((error) => `Claude: ${error}`),
+    ...codex.errors.map((error) => `Codex: ${error}`),
+  ];
+  const pkg = JSON.parse(fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf8'));
+  for (const entry of ['.claude/agents/', '.claude/skills/', '.agents/skills/', '.codex/agents/']) {
+    if (!pkg.files.includes(entry)) errors.push(`package.json files[] is missing ${entry}`);
+  }
+  return {
+    ok: errors.length === 0,
+    errors,
+    metrics: {
+      ...claude.metrics,
+      codexAgents: codex.metrics.nativeAgents,
+      codexSkills: codex.metrics.nativeSkills,
+    },
+  };
+}
+
+function main() {
+  const json = process.argv.slice(2).includes('--json');
+  const result = validateProviderAdapters();
+  if (json) console.log(JSON.stringify(result, null, 2));
+  else if (result.ok) {
+    console.log(`OK provider adapters (${result.metrics.canonicalAgents} agents; Claude ${result.metrics.claudeSkills} skills; Codex ${result.metrics.codexSkills} skills)`);
+  } else {
+    console.error(['Provider adapter validation failed', ...result.errors.map((error) => `- ${error}`)].join('\n'));
+  }
+  if (!result.ok) process.exitCode = 1;
+}
+
+if (require.main === module) main();
+
+module.exports = { parseFrontmatter, validateClaudeNative, validateProviderAdapters };

package/squads/squad-animations/knowledge-base/react-bits-operational-guide.md

@@ -0,0 +1,43 @@
+# React Bits - operational guide
+
+> Fonte canônica: `docs/framework/react-bits/index.md`.
+> Snapshot: `DavidHDev/react-bits@3acbd54115330a42e39f63dda2d4859e998b6684`.
+
+## Contrato de uso
+
+React Bits é um catálogo de código copiável, não um pacote monolítico. Usar a base
+para descobrir o componente, confirmar API e dependências, escolher uma das quatro
+variantes, instalar/copiar a fonte oficial e adaptar o código ao projeto.
+
+Carregar sob demanda os quatro catálogos e o playbook em
+`docs/framework/react-bits/`.
+
+## Roteamento interno
+
+| Necessidade                         | Delegar para                     |
+| ----------------------------------- | -------------------------------- |
+| intenção, shortlist e especificação | `animation-interpreter`          |
+| CSS, SVG e microinteração           | `css-motion-artist`              |
+| timing, easing e composição         | `motion-choreographer`           |
+| scroll e narrativa                  | `scroll-narrative-engineer`      |
+| Three/R3F/WebGL                     | `threejs-architect`              |
+| OGL/GLSL/shaders                    | `shader-artist`                  |
+| partículas e física                 | `generative-particle-engineer`   |
+| performance, mobile e a11y          | `animation-performance-engineer` |
+
+## Regras invioláveis
+
+1. Selecionar pela função na experiência, não por novidade.
+2. Consultar fonte oficial e catálogo antes de afirmar props ou dependências.
+3. Rodar `npm view <pacote>` para cada dependência antes de instalar.
+4. Preferir `TS-TW` ou `TS-CSS` em projetos TypeScript.
+5. Criar wrapper local e adaptar design tokens, conteúdo e breakpoints.
+6. Implementar cleanup, reduced motion, fallback estático e semântica/foco.
+7. Medir no mobile e impedir múltiplos owners de scroll, cursor ou render loop.
+8. Não redistribuir componentes como biblioteca, bundle ou port; respeitar a licença.
+
+## Atualização
+
+Atualizar o checkout oficial por fast-forward e executar
+`scripts/research/generate-react-bits-catalog.mjs`. A nova base só é válida quando o
+gerador confirma paridade com `componentMetadata` e registra o novo SHA.

package/squads/squad-animations/squad.yaml

@@ -15,16 +15,16 @@ metadata:
   updated_at: "2026-03-15"
   created_by: "squad-creator (Craft)"
   agents_count: 9
-  tasks_count: 75
-  knowledge_bases_count: 14
+  tasks_count: 76
+  knowledge_bases_count: 16
   workflows_count: 5
   checklists_count: 3
   templates_count: 5
-  total_files: 114
+  total_files: 116
   agents: 9
-  tasks: 75
+  tasks: 76
   workflows: 0
-  knowledge_bases: 15
+  knowledge_bases: 16
   checklists: 3
   templates: 5
   preferences: 0
@@ -40,6 +40,7 @@ agents:
       - review-animation-quality
       - manage-animation-pipeline
       - generate-animation-report
+      - orchestrate-react-bits-frontend
 
   - id: animation-interpreter
     name: Decoder
@@ -206,6 +207,10 @@ knowledge_bases:
     file: knowledge-base/unicorn-studio-pipeline.md
     description: "Pipeline programatico Unicorn Studio — JSON templates, endpoints publicos, image swap, brand-aware parameters, SDK integration"
 
+  - name: react-bits-operational-guide
+    file: knowledge-base/react-bits-operational-guide.md
+    description: "Roteamento e guardrails para selecionar, instalar, adaptar, combinar e auditar componentes React Bits"
+
 workflows:
   - name: prompt-to-animation-cycle
     file: workflows/prompt-to-animation-cycle.yaml

package/squads/squad-animations/tasks/orchestrate-react-bits-frontend.md

@@ -0,0 +1,60 @@
+---
+task: orchestrate-react-bits-frontend
+responsavel: '@animations-orqx'
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+
+Entrada:
+  - campo: frontend_objective
+    tipo: object
+    origem: 'user_request_or_design_spec'
+    obrigatorio: true
+
+Saida:
+  - campo: react_bits_delivery
+    tipo: code_and_report
+    destino: 'review-animation-quality'
+
+Checklist:
+  - '[ ] Traduzir objetivo visual em funcao de experiencia'
+  - '[ ] Consultar catalogo React Bits e formar shortlist'
+  - '[ ] Delegar implementacao ao especialista correto'
+  - '[ ] Verificar dependencias antes da instalacao'
+  - '[ ] Adaptar tokens, conteudo, responsividade e lifecycle'
+  - '[ ] Validar reduced motion, acessibilidade e performance mobile'
+  - '[ ] Registrar componente, variante, origem e customizacoes'
+---
+
+# Task: Orchestrate React Bits Frontend
+
+## Objetivo
+
+Selecionar, instalar, adaptar, combinar e auditar componentes oficiais do React Bits
+para entregar uma experiência de frontend intencional, acessível e performática.
+
+## Conhecimento obrigatório
+
+Ler `../knowledge-base/react-bits-operational-guide.md` e carregar apenas os catálogos
+de `docs/framework/react-bits/` relevantes ao pedido.
+
+## Execução
+
+1. Classificar a função do efeito: hierarquia, orientação, feedback, continuidade,
+   atmosfera ou delight.
+2. Formar shortlist de até três itens usando descrição, props, motor e custo técnico.
+3. Explicar a escolha e o orçamento de atenção/performance.
+4. Delegar implementação conforme o roteamento da KB; o orquestrador não implementa.
+5. Antes de instalar, verificar cada dependência oficial com `npm view`.
+6. Escolher a variante que preserva o stack do projeto e integrar em wrapper local.
+7. Adaptar tokens, copy, semântica, breakpoints, qualidade e fallbacks.
+8. Delegar auditoria a `animation-performance-engineer` e revisão final ao pipeline.
+
+## Critérios de qualidade
+
+- Fonte, componente e variante rastreáveis.
+- Nenhuma dependência desnecessária ou não verificada.
+- Conteúdo acessível sem animação e estado final imediato em reduced motion.
+- Cleanup completo de RAF, timers, observers, listeners e recursos GPU.
+- Mobile funcional com fallback quando o efeito exceder o orçamento.
+- Licença respeitada; componentes não são redistribuídos como produto isolado.