@lucapimenta/copy-chief-black 1.0.0

package/framework/workflows/validation-workflow.md

@@ -0,0 +1,111 @@
+# Validation Workflow
+
+> Quando e como usar subagents para validação de copy.
+> **v2.0:** general-purpose obrigatório (custom types NAO herdam MCPs)
+
+## WARNING: Subagent Type
+
+> **SEMPRE usar `subagent_type="general-purpose"` para tasks de validação.**
+> O tipo `reviewer` NÃO tem acesso a MCPs (black_validation, layered_review, etc) no runtime.
+> Custom subagent types recebem apenas Read, Write — sem ToolSearch para carregar deferred tools.
+
+## Quando Usar
+
+- Validação de hooks
+- Review de body copy
+- Verificação de consistência
+- Quality gates antes de publicar
+- Qualquer validação de copy produzida
+
+## Pré-requisitos
+
+Antes de invocar subagent de validação, GARANTIR que existe:
+- Copy produzida (draft)
+- Briefing para comparação
+- VOC para verificar autenticidade
+
+## Como Invocar
+
+```
+Task(
+  subagent_type="general-purpose",
+  prompt="Validar [tipo de copy].
+         Copy: [caminho do draft]
+         Briefing: [caminho do helix]
+         VOC: [caminho do language-patterns]
+
+         INSTRUÇÃO: Use ToolSearch para carregar MCP copywriting tools.
+         Execute blind_critic, emotional_stress_test e black_validation."
+)
+```
+
+## Workflow Padrão
+
+```
+1. INVOCAR general-purpose com copy a validar
+2. AGUARDAR retorno (score + veredicto)
+3. SE PASS (≥14/16) → finalizar
+4. SE PASS_WITH_CONCERNS (≥12/16) → publicar com nota
+5. SE NEEDS_REVISION (<12/16) → invocar general-purpose com issues
+```
+
+## Exemplo: Validar Hook
+
+```
+Task(
+  subagent_type="general-purpose",
+  prompt="Validar hook de Meta Ads.
+         Copy: concursos/hacker/production/creatives/meta/drafts/hook-01.md
+         Briefing: concursos/hacker/briefings/helix-complete.md
+         VOC: concursos/hacker/research/voc/processed/language-patterns.md
+
+         Use ToolSearch para carregar copywriting MCP e execute:
+         1. blind_critic no hook
+         2. emotional_stress_test (genericidade ≥8)
+         3. Retorne score + veredicto"
+)
+```
+
+## Checklists Aplicados
+
+| Checklist | Max | Mínimo |
+|-----------|-----|--------|
+| Hook (6-Question) | 6 | 4 |
+| Body (5-Point) | 5 | 4 |
+| Consistency (5-Point) | 5 | 4 |
+| **TOTAL** | **16** | **12** |
+
+## Verdicts
+
+| Score | Veredicto | Ação |
+|-------|-----------|------|
+| 14-16 | PASS | Pronto para uso |
+| 12-13 | PASS_WITH_CONCERNS | Publicar, mas melhorar |
+| <12 | NEEDS_REVISION | Refazer antes de publicar |
+
+## Outputs Esperados
+
+```
+{oferta}/production/reviews/
+└── {type}-review-{date}.md
+```
+
+## Fluxo de Revisão
+
+```
+Draft → General-Purpose (reviewer prompt) → Veredicto
+                     ↓
+            PASS ────────────→ Final
+            CONCERNS ────────→ Final (com notas)
+            REVISION ────────→ General-Purpose (copywriter prompt) → Draft → Reviewer
+```
+
+## Próximo Passo
+
+Após PASS → Mover draft para `final/` e publicar.
+
+---
+
+*v2.0 - Fix: reviewer → general-purpose (custom types sem MCPs)*
+*BSSF Score 9.2, GBS 95%*
+*Atualizado: 2026-02-20*

package/installer/doctor.js

@@ -0,0 +1,142 @@
+/**
+ * Copy Chief BLACK — Doctor
+ * Diagnoses environment and configuration issues
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const platform = require('../lib/platform');
+
+async function doctor() {
+  console.log('Copy Chief BLACK — Doctor\n');
+  console.log('Platform:', process.platform, process.arch);
+  console.log('Node:', process.versions.node);
+  console.log('Home:', platform.homeDir());
+  console.log('Claude Home:', platform.claudeHome());
+  console.log('');
+
+  // 1. Node.js version
+  const nodeVer = parseInt(process.versions.node.split('.')[0], 10);
+  check('Node.js >= 18', nodeVer >= 18, `Found v${process.versions.node}`);
+
+  // 2. Git
+  let gitVer = null;
+  try {
+    gitVer = execSync('git --version', { stdio: 'pipe' }).toString().trim();
+    check('Git available', true, gitVer);
+  } catch {
+    check('Git available', false, 'Not found in PATH');
+  }
+
+  // 3. Claude Code
+  const claude = platform.findExecutable('claude');
+  check('Claude Code CLI', !!claude, claude || 'Not found — install: npm i -g @anthropic-ai/claude-code');
+
+  // 4. Bun (optional)
+  const bun = platform.findExecutable('bun');
+  check('Bun runtime (optional)', !!bun, bun || 'Not found — only needed for TS hooks without transpilation');
+
+  // 5. settings.json
+  const settingsPath = path.join(platform.claudeHome(), 'settings.json');
+  check('settings.json exists', fs.existsSync(settingsPath));
+
+  if (fs.existsSync(settingsPath)) {
+    try {
+      const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+
+      // Check for bun references
+      const content = fs.readFileSync(settingsPath, 'utf8');
+      const bunRefs = (content.match(/bun run/g) || []).length;
+      check('No bun references in settings', bunRefs === 0, bunRefs > 0 ? `${bunRefs} hooks still use "bun run"` : '');
+
+      // Check for hardcoded paths
+      const hardcoded = (content.match(/\/Users\//g) || []).length;
+      check('No hardcoded user paths', hardcoded === 0, hardcoded > 0 ? `${hardcoded} hardcoded /Users/ paths` : '');
+
+      // Check PATH
+      if (settings.env && settings.env.PATH) {
+        const pathNode = settings.env.PATH.split(path.delimiter).some(p => {
+          try { return fs.existsSync(path.join(p, platform.isWindows() ? 'node.exe' : 'node')); }
+          catch { return false; }
+        });
+        check('PATH contains node', pathNode);
+      }
+
+      // Check hooks count
+      let hookCount = 0;
+      if (settings.hooks) {
+        for (const matchers of Object.values(settings.hooks)) {
+          if (!Array.isArray(matchers)) continue;
+          for (const m of matchers) {
+            if (m.hooks) hookCount += m.hooks.length;
+          }
+        }
+      }
+      check(`Hooks registered (${hookCount})`, hookCount > 0);
+
+    } catch (e) {
+      check('settings.json valid JSON', false, e.message);
+    }
+  }
+
+  // 6. AIOS Core
+  const aiosCore = platform.aiosCoreDir();
+  check('.aios-core directory', fs.existsSync(aiosCore));
+  check('.aios-core/node_modules', fs.existsSync(path.join(aiosCore, 'node_modules')));
+
+  // 7. js-yaml
+  try {
+    platform.getYaml();
+    check('js-yaml loadable', true);
+  } catch {
+    check('js-yaml loadable', false, 'Run: cd ~/.claude/.aios-core && npm install');
+  }
+
+  // 8. Hooks directory
+  const hooksDir = platform.hooksDir();
+  if (fs.existsSync(hooksDir)) {
+    const files = fs.readdirSync(hooksDir);
+    const cjs = files.filter(f => f.endsWith('.cjs')).length;
+    const ts = files.filter(f => f.endsWith('.ts')).length;
+    const js = files.filter(f => f.endsWith('.js')).length;
+    const sh = files.filter(f => f.endsWith('.sh')).length;
+    console.log(`\n  Hooks breakdown: ${cjs} .cjs, ${js} .js, ${ts} .ts, ${sh} .sh`);
+
+    if (sh > 0 && platform.isWindows()) {
+      console.log(`  ⚠️  ${sh} shell scripts found — these won't work on Windows without bash`);
+    }
+    if (ts > 0 && !bun) {
+      console.log(`  ⚠️  ${ts} TypeScript hooks found — need transpilation (no bun available)`);
+    }
+
+    // Check for /dev/stdin usage
+    let stdinCount = 0;
+    for (const f of files) {
+      if (f.endsWith('.sh') || f.endsWith('.md') || f.endsWith('.json') || f.endsWith('.lock')) continue;
+      try {
+        const content = fs.readFileSync(path.join(hooksDir, f), 'utf8');
+        if (content.includes('/dev/stdin')) stdinCount++;
+      } catch {}
+    }
+    if (stdinCount > 0) {
+      console.log(`  ⚠️  ${stdinCount} hooks use /dev/stdin (Windows incompatible)`);
+    }
+  }
+
+  // 9. Ecosystem
+  const eco = platform.ecosystemRoot();
+  check('Ecosystem directory', fs.existsSync(eco), eco);
+  check('.synapse/ exists', fs.existsSync(path.join(eco, '.synapse')));
+
+  console.log('\nDone.');
+}
+
+function check(label, ok, detail) {
+  const icon = ok ? '✓' : '✗';
+  const msg = detail ? ` (${detail})` : '';
+  console.log(`  ${icon} ${label}${msg}`);
+}
+
+module.exports = { doctor };

package/installer/install.js

@@ -0,0 +1,272 @@
+/**
+ * Copy Chief BLACK — Installer
+ * Installs framework into ~/.claude/ with cross-platform support
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const platform = require('../lib/platform');
+const settingsBuilder = require('../lib/settings-builder');
+
+const REQUIRED_NODE_VERSION = 18;
+const FRAMEWORK_DIR = path.join(__dirname, '..', 'framework');
+
+async function install(opts = {}) {
+  console.log('Copy Chief BLACK — Installer v1.0\n');
+
+  // Step 1: Check prerequisites
+  console.log('[1/9] Checking prerequisites...');
+  checkPrerequisites();
+
+  // Step 2: Backup existing installation
+  const claudeHome = platform.claudeHome();
+  if (fs.existsSync(claudeHome) && opts.backup !== false) {
+    console.log('[2/9] Backing up existing ~/.claude/...');
+    backup(claudeHome);
+  } else {
+    console.log('[2/9] No existing installation found (or --no-backup)');
+  }
+
+  // Step 3: Copy framework files
+  console.log('[3/9] Copying framework files...');
+  copyFramework(claudeHome, opts.force);
+
+  // Step 4: Install Node dependencies
+  console.log('[4/9] Installing dependencies...');
+  installDeps(claudeHome);
+
+  // Step 5: Transpile TypeScript hooks
+  console.log('[5/9] Transpiling TypeScript hooks...');
+  transpileHooks(claudeHome);
+
+  // Step 6: Generate settings.json + mcp.json
+  console.log('[6/10] Generating settings.json...');
+  const ecoRoot = opts.ecosystem || platform.ecosystemRoot();
+  settingsBuilder.writeSettings({ ecosystemRoot: ecoRoot, force: opts.force });
+  console.log('[7/10] Generating mcp.json...');
+  settingsBuilder.writeMcpJson({ ecosystemRoot: ecoRoot, apifyToken: opts.apifyToken, force: opts.force });
+
+  // Step 8: Scaffold ecosystem
+  console.log('[8/10] Scaffolding ecosystem...');
+  scaffoldEcosystem(ecoRoot);
+
+  // Step 9: Create runtime directories
+  console.log('[9/10] Creating runtime directories...');
+  createRuntimeDirs(claudeHome, ecoRoot);
+
+  // Step 10: Verify
+  console.log('[10/10] Verifying installation...');
+  const { verify } = require('./verify');
+  const ok = await verify({ quiet: true });
+
+  if (ok) {
+    console.log('\n✅ Copy Chief BLACK installed successfully!');
+    console.log(`   Claude Home: ${claudeHome}`);
+    console.log(`   Ecosystem:   ${ecoRoot}`);
+    console.log('\n   Start Claude Code in your ecosystem directory to begin.');
+  } else {
+    console.log('\n⚠️  Installation completed with warnings. Run: copy-chief-black doctor');
+  }
+}
+
+function checkPrerequisites() {
+  // Node version
+  const nodeVersion = parseInt(process.versions.node.split('.')[0], 10);
+  if (nodeVersion < REQUIRED_NODE_VERSION) {
+    console.error(`❌ Node.js ${REQUIRED_NODE_VERSION}+ required (found ${process.versions.node})`);
+    process.exit(1);
+  }
+  console.log(`   Node.js ${process.versions.node} ✓`);
+
+  // Git
+  try {
+    execSync('git --version', { stdio: 'pipe' });
+    console.log('   Git ✓');
+  } catch {
+    console.error('❌ Git is required but not found in PATH');
+    process.exit(1);
+  }
+
+  // Claude Code (optional)
+  const claudeBin = platform.findExecutable('claude');
+  if (claudeBin) {
+    console.log('   Claude Code ✓');
+  } else {
+    console.log('   Claude Code not found (install separately: npm install -g @anthropic-ai/claude-code)');
+  }
+}
+
+function backup(claudeHome) {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  const backupDir = `${claudeHome}-backup-${timestamp}`;
+  fs.cpSync(claudeHome, backupDir, { recursive: true });
+  console.log(`   Backup created: ${backupDir}`);
+}
+
+function copyFramework(claudeHome, force) {
+  if (!fs.existsSync(FRAMEWORK_DIR)) {
+    console.log('   Framework directory not found — skipping (dev mode)');
+    return;
+  }
+
+  // ALL framework directories — nothing missing
+  const items = [
+    // Core engine
+    '.aios-core', 'hooks', 'scripts',
+    // Agents & squad
+    'agents', 'copy-squad',
+    // Plugins & schemas
+    'plugins', 'schemas',
+    // Skills & commands
+    'skills', 'commands',
+    // Knowledge & reference
+    'knowledge', 'reference', 'references', 'dossiers', 'experts',
+    // Config
+    'config', 'checklists', 'rules', 'data',
+    // Templates & workflows
+    'templates', 'workflows',
+    // Runtime data (seeded, grows over time)
+    'stories', 'gotchas', 'learned-patterns', 'ids',
+    // Documentation
+    'docs',
+    // Tests
+    'tests',
+  ];
+
+  for (const item of items) {
+    const src = path.join(FRAMEWORK_DIR, item);
+    const dest = path.join(claudeHome, item);
+
+    if (!fs.existsSync(src)) continue;
+
+    if (fs.existsSync(dest) && !force) {
+      // Merge: copy new files, don't overwrite existing
+      copyNewFiles(src, dest);
+      console.log(`   Merged: ${item}/`);
+    } else {
+      fs.cpSync(src, dest, { recursive: true });
+      console.log(`   Copied: ${item}/`);
+    }
+  }
+
+  // Copy root config files
+  const rootFiles = [
+    'CLAUDE.md', 'constitution.md', 'core-config.yaml', 'manifest.yaml',
+    'manifest.json', 'framework-config.yaml', 'synapse-manifest.yaml',
+    'copy-surface-criteria.yaml', 'registry.yaml',
+    'CHANGELOG.md', 'COPY-CHIEF-INDEX.md', 'COPY-DOCS-INDEX.md',
+    'ecosystem-status.md', 'orchestrator.md', 'QUICK-REFERENCE.md',
+    'RUNBOOK.md', 'WORKFLOW-CANONICO.md',
+    'GUIA-ECOSSISTEMA.md', 'GUIA-INSTALACAO.md', 'GUIA-USO-ECOSSISTEMA.md',
+  ];
+  for (const file of rootFiles) {
+    const src = path.join(FRAMEWORK_DIR, file);
+    const dest = path.join(claudeHome, file);
+    if (fs.existsSync(src) && (force || !fs.existsSync(dest))) {
+      fs.copyFileSync(src, dest);
+    }
+  }
+  console.log(`   Root config files ✓`);
+}
+
+function copyNewFiles(src, dest) {
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyNewFiles(srcPath, destPath);
+    } else if (!fs.existsSync(destPath)) {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function installDeps(claudeHome) {
+  const aiosCore = path.join(claudeHome, '.aios-core');
+  const pkgJson = path.join(aiosCore, 'package.json');
+
+  if (!fs.existsSync(pkgJson)) {
+    // Create minimal package.json
+    const pkg = { name: 'aios-core', version: '1.0.0', private: true, dependencies: { 'js-yaml': '^4.1.1' } };
+    fs.mkdirSync(aiosCore, { recursive: true });
+    fs.writeFileSync(pkgJson, JSON.stringify(pkg, null, 2));
+  }
+
+  try {
+    execSync('npm install --production', { cwd: aiosCore, stdio: 'pipe' });
+    console.log('   js-yaml installed ✓');
+  } catch (e) {
+    console.error(`   ⚠️  npm install failed: ${e.message}`);
+  }
+}
+
+function transpileHooks(claudeHome) {
+  const { transpileAll } = require('./transpile');
+  return transpileAll({ force: false });
+}
+
+function scaffoldEcosystem(ecoRoot) {
+  if (fs.existsSync(path.join(ecoRoot, '.synapse'))) {
+    console.log('   Ecosystem already exists');
+    return;
+  }
+
+  const scaffoldDir = path.join(__dirname, '..', 'templates', 'ecosystem');
+  if (fs.existsSync(scaffoldDir)) {
+    fs.cpSync(scaffoldDir, ecoRoot, { recursive: true });
+    console.log(`   Scaffolded: ${ecoRoot}`);
+  } else {
+    // Create minimal structure
+    const dirs = [
+      '.synapse/manifest',
+      '.synapse/constitution',
+      '.claude/rules/offers',
+      'squads/copy-chief/workflows',
+      'squads/copy-chief/checklists',
+      'squads/copy-chief/data/craft',
+    ];
+    for (const dir of dirs) {
+      fs.mkdirSync(path.join(ecoRoot, dir), { recursive: true });
+    }
+    // Init git
+    try {
+      execSync('git init', { cwd: ecoRoot, stdio: 'pipe' });
+    } catch { /* already a repo */ }
+    console.log(`   Created minimal ecosystem at: ${ecoRoot}`);
+  }
+}
+
+function createRuntimeDirs(claudeHome, ecoRoot) {
+  const dirs = [
+    path.join(claudeHome, 'logs'),
+    path.join(claudeHome, 'session-state'),
+    path.join(claudeHome, 'session-env'),
+    path.join(claudeHome, 'session-digests'),
+    path.join(claudeHome, 'agent-memory'),
+    path.join(claudeHome, 'projects'),
+    path.join(claudeHome, 'plans'),
+    path.join(claudeHome, 'cache'),
+    path.join(claudeHome, 'debug'),
+    path.join(claudeHome, 'production-logs'),
+    path.join(claudeHome, 'production-loops'),
+    path.join(claudeHome, 'shell-snapshots'),
+    path.join(claudeHome, 'paste-cache'),
+    path.join(claudeHome, 'memory'),
+    path.join(claudeHome, 'artifacts'),
+    path.join(claudeHome, 'file-history'),
+  ];
+  for (const dir of dirs) {
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+      console.log(`   Created: ${path.relative(claudeHome, dir)}/`);
+    }
+  }
+}
+
+module.exports = { install };

package/installer/new-offer.js

@@ -0,0 +1,108 @@
+/**
+ * Copy Chief BLACK — New Offer Scaffold
+ * Creates a new offer project structure
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const platform = require('../lib/platform');
+
+async function newOffer(niche, name, opts = {}) {
+  const eco = platform.ecosystemRoot();
+  const offerDir = path.join(eco, niche, name);
+
+  if (fs.existsSync(offerDir)) {
+    console.error(`❌ Offer already exists: ${offerDir}`);
+    process.exit(1);
+  }
+
+  console.log(`Creating offer: ${niche}/${name}\n`);
+
+  // Create directory structure
+  const dirs = [
+    '',
+    'research/raw',
+    'research/processed',
+    'briefings/phases',
+    'production/vsl',
+    'production/landing-page',
+    'production/creatives',
+    'production/emails',
+    'swipes/vsl',
+    'swipes/criativos',
+    '.aios',
+  ];
+
+  for (const dir of dirs) {
+    fs.mkdirSync(path.join(offerDir, dir), { recursive: true });
+  }
+
+  // Create CONTEXT.md
+  const yaml = platform.getYaml();
+  const context = `# ${name} - Contexto da Oferta
+
+## Produto
+- **Tipo:** ${opts.template === 'quiz' ? 'Quiz Funnel' : 'VSL -> Checkout'}
+- **Nicho:** ${niche}
+- **Sub-nicho:** [definir]
+- **Ticket:** [definir]
+- **Funil:** ${opts.template === 'quiz' ? 'Quiz -> VSL -> Checkout' : 'VSL -> Checkout'}
+- **Expert:** [definir]
+
+## Mecanismo
+- **MUP:** [a definir]
+- **MUS:** [a definir]
+
+## Avatar Primario
+[a definir]
+
+## Quality Gates
+| Gate | Status |
+|------|--------|
+| Research | NOT_STARTED |
+| Briefing | NOT_STARTED |
+| Production | NOT_STARTED |
+`;
+  fs.writeFileSync(path.join(offerDir, 'CONTEXT.md'), context);
+
+  // Create mecanismo-unico.yaml
+  const mecanismo = {
+    version: '1.0',
+    offer: name,
+    niche: niche,
+    mup: { name: null, description: null, status: 'DRAFT' },
+    mus: { name: null, description: null, gimmick_name: null, status: 'DRAFT' },
+    paradigm_shift: null,
+    authority_hook: null,
+  };
+  platform.writeYaml(path.join(offerDir, 'mecanismo-unico.yaml'), mecanismo);
+
+  // Create helix-state.yaml
+  const helixState = {
+    offer: name,
+    niche: niche,
+    phases: Object.fromEntries(
+      Array.from({ length: 10 }, (_, i) => [`phase_${String(i + 1).padStart(2, '0')}`, { status: 'NOT_STARTED', confidence: 0 }])
+    ),
+  };
+  platform.writeYaml(path.join(offerDir, 'helix-state.yaml'), helixState);
+
+  // Create project_state.yaml
+  const projectState = {
+    offer: name,
+    niche: niche,
+    current_phase: 'research',
+    gates: { research: 'NOT_STARTED', briefing: 'NOT_STARTED', production: 'NOT_STARTED' },
+    created: new Date().toISOString(),
+  };
+  platform.writeYaml(path.join(offerDir, 'project_state.yaml'), projectState);
+
+  console.log(`✅ Offer scaffolded: ${offerDir}`);
+  console.log('\nNext steps:');
+  console.log(`  1. Edit ${niche}/${name}/CONTEXT.md with product details`);
+  console.log(`  2. cd ${offerDir}`);
+  console.log('  3. Start Claude Code and run: /next-action');
+}
+
+module.exports = { newOffer };