edusquads-cli 0.1.0

package/base/scripts/edusquads_investigar.py

@@ -0,0 +1,279 @@
+#!/usr/bin/env python3
+"""
+Automação Fase 3 do /edusquads investigar.
+
+Escopo desta versão:
+- Gera run_id incremental por data
+- Seleciona playbook por plataforma
+- Cria arquivo de evidência automaticamente
+- Atualiza RUNS-INDEX.md
+- Cria/atualiza arquivo de run com trilha da investigação
+
+Observação:
+A navegação web efetiva continua sendo executada pelo runtime do agente
+(browser tools/Playwright da stack). Este script automatiza a camada
+operacional de artefatos e rastreabilidade.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import re
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+RUNS_DIR = ROOT / "_edusquads" / "runs"
+EVID_DIR = ROOT / "_edusquads" / "evidencias"
+PLAYBOOK_DIR = ROOT / "base" / "playbooks" / "investigacao"
+RUNS_INDEX = RUNS_DIR / "RUNS-INDEX.md"
+
+
+def rel(path: Path) -> str:
+    return path.relative_to(ROOT).as_posix()
+
+
+def detect_platform(target: str, platform_arg: str | None) -> str:
+    if platform_arg:
+        p = platform_arg.lower().strip()
+        aliases = {
+            "instagram": "instagram",
+            "insta": "instagram",
+            "youtube": "youtube",
+            "yt": "youtube",
+            "linkedin": "linkedin",
+            "x": "x-twitter",
+            "twitter": "x-twitter",
+            "x-twitter": "x-twitter",
+        }
+        if p in aliases:
+            return aliases[p]
+
+    t = target.lower()
+    if "instagram.com" in t:
+        return "instagram"
+    if "youtube.com" in t or "youtu.be" in t:
+        return "youtube"
+    if "linkedin.com" in t:
+        return "linkedin"
+    if "x.com" in t or "twitter.com" in t:
+        return "x-twitter"
+    return "instagram"
+
+
+def next_run_id(today: dt.date) -> str:
+    prefix = f"RUN-{today.isoformat()}-"
+    max_n = 0
+    for p in RUNS_DIR.glob(f"{prefix}*.md"):
+        m = re.match(rf"{re.escape(prefix)}(\d{{3}})\.md$", p.name)
+        if m:
+            max_n = max(max_n, int(m.group(1)))
+    return f"{prefix}{max_n + 1:03d}"
+
+
+def ensure_dirs() -> None:
+    RUNS_DIR.mkdir(parents=True, exist_ok=True)
+    EVID_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def append_runs_index(run_id: str, command: str, objective: str, squads: str, status: str, run_file: str) -> None:
+    if not RUNS_INDEX.exists():
+        RUNS_INDEX.write_text(
+            "# Runs do EduSquads\n\n"
+            "Registro cronológico das execuções do sistema `/edusquads`.\n\n"
+            "## Tabela de controle\n"
+            "| run_id | data | comando | objetivo | squads acionados | status | arquivo |\n"
+            "|---|---|---|---|---|---|---|\n",
+            encoding="utf-8",
+        )
+
+    content = RUNS_INDEX.read_text(encoding="utf-8")
+    date_txt = dt.date.today().isoformat()
+    row = f"| {run_id} | {date_txt} | `{command}` | {objective} | {squads} | {status} | `{run_file}` |\n"
+
+    if row in content:
+        return
+
+    lines = content.splitlines(keepends=True)
+    insert_at = len(lines)
+    for i, line in enumerate(lines):
+        if line.startswith("## Regras de registro"):
+            insert_at = i
+            break
+
+    # remove linha em branco imediatamente antes de "## Regras de registro"
+    if insert_at > 0 and lines[insert_at - 1].strip() == "":
+        del lines[insert_at - 1]
+        insert_at -= 1
+
+    lines.insert(insert_at, row)
+    RUNS_INDEX.write_text("".join(lines), encoding="utf-8")
+
+
+def create_evidence(run_id: str, platform: str, target: str, objective: str, depth: str, consent: bool) -> Path:
+    ev_path = EVID_DIR / f"EVIDENCIA-{run_id}-{platform}.md"
+    now = dt.datetime.now().strftime("%Y-%m-%d %H:%M")
+
+    content = f"""# EVIDENCIA-{run_id}-{platform}
+
+## Metadados
+- id_evidencia: EVIDENCIA-{run_id}-{platform}
+- data: {now}
+- run_id: {run_id}
+- comando: /edusquads investigar
+
+## Objetivo da investigação
+- {objective}
+
+## Entrada usada
+- url/perfil/query: {target}
+- plataforma detectada: {platform}
+- profundidade: {depth}
+
+## Playbook aplicado
+- `base/playbooks/investigacao/{platform}.md`
+
+## Links visitados
+- {target}
+
+## Síntese interpretativa
+- (preencher após investigação de navegação)
+
+## Extrações úteis para squads
+- Squad de Estratégia:
+- Squad de Conteúdo:
+- Squad de Copy:
+- Squad de Design:
+
+## Limites da evidência
+- Execução inicial automatizada de artefatos; síntese depende da investigação web concluída.
+
+## Segurança
+- sessão persistida: {'sim' if consent else 'não'}
+- consentimento explícito registrado: {'sim' if consent else 'não'}
+- dados sensíveis removidos: sim
+"""
+    ev_path.write_text(content, encoding="utf-8")
+    return ev_path
+
+
+def create_run(run_id: str, target: str, objective: str, platform: str, evidence_path: Path) -> Path:
+    run_path = RUNS_DIR / f"{run_id}.md"
+    date_txt = dt.date.today().isoformat()
+    content = f"""# {run_id}
+
+## Metadados
+- run_id: {run_id}
+- data: {date_txt}
+- comando: `/edusquads investigar`
+- solicitacao_original: investigação automatizada para {target}
+- status: em-andamento
+
+## Contexto aplicado
+- memória do usuário lida: sim
+- arquivos de referência usados:
+  - `base/protocolo-playwright-edusquads.md`
+  - `base/playbooks/investigacao/{platform}.md`
+
+## Plano executado
+1. Detectar plataforma e selecionar playbook.
+2. Criar artefato de evidência com metadados.
+3. Registrar run no índice de execuções.
+4. Executar investigação web e preencher síntese.
+
+## Squads e agentes acionados
+- squads:
+  - 14-automacao-sistemas
+  - 13-qualidade
+- agentes-chave:
+  - estruturador-de-skills
+  - lider-de-qualidade
+
+## Entregas geradas
+- `{rel(evidence_path)}`
+
+## Checkpoints
+### Checkpoint de estratégia
+- resultado: aprovado
+- observações: objetivo definido e playbook selecionado.
+
+### Checkpoint de produção
+- resultado: em-andamento
+- observações: investigação web pendente de execução completa.
+
+### Checkpoint de qualidade
+- resultado: pendente
+- observações: validação final após preenchimento da síntese.
+
+## Decisões registradas
+- plataforma detectada automaticamente: {platform}
+
+## Pendências / próximos passos
+- executar navegação e preencher síntese interpretativa da evidência.
+- atualizar status para concluído ao finalizar a investigação.
+
+## Evidências
+- arquivos alterados:
+  - `{rel(evidence_path)}`
+- validações realizadas:
+  - geração automática de run_id
+  - seleção automática de playbook
+"""
+    run_path.write_text(content, encoding="utf-8")
+    return run_path
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Fase 3: automação de investigação /edusquads")
+    parser.add_argument("target", help="URL/perfil alvo da investigação")
+    parser.add_argument("--objetivo", required=True, help="Objetivo de negócio da investigação")
+    parser.add_argument("--plataforma", help="instagram|youtube|linkedin|x-twitter")
+    parser.add_argument("--profundidade", default="rápida", choices=["rápida", "profunda"], help="Nível de profundidade")
+    parser.add_argument("--consentimento-sessao", action="store_true", help="Marcar que houve consentimento explícito para persistir sessão")
+    args = parser.parse_args()
+
+    ensure_dirs()
+    today = dt.date.today()
+
+    run_id = next_run_id(today)
+    platform = detect_platform(args.target, args.plataforma)
+
+    playbook = PLAYBOOK_DIR / f"{platform}.md"
+    if not playbook.exists():
+        raise SystemExit(f"Playbook não encontrado: {playbook}")
+
+    ev_path = create_evidence(
+        run_id=run_id,
+        platform=platform,
+        target=args.target,
+        objective=args.objetivo,
+        depth=args.profundidade,
+        consent=args.consentimento_sessao,
+    )
+
+    run_path = create_run(
+        run_id=run_id,
+        target=args.target,
+        objective=args.objetivo,
+        platform=platform,
+        evidence_path=ev_path,
+    )
+
+    append_runs_index(
+        run_id=run_id,
+        command="/edusquads investigar",
+        objective=args.objetivo,
+        squads="14-Automação/Sistema, 13-Qualidade",
+        status="em-andamento",
+        run_file=f"_edusquads/runs/{run_path.name}",
+    )
+
+    print(f"run_id={run_id}")
+    print(f"platform={platform}")
+    print(f"run_file={run_path.as_posix()}")
+    print(f"evidence_file={ev_path.as_posix()}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/base/visao-geral.md

@@ -0,0 +1,46 @@
+# Visão Geral
+
+## O que é o EduSquads
+EduSquads é um sistema para Claude Code que transforma conhecimento de mercado em operação estruturada.
+
+Ele combina:
+- squads
+- agentes
+- skills
+- fundamentos
+- fluxos
+- revisão
+- comando de ativação
+
+## Tese principal
+Agentes genéricos tendem a produzir entregas genéricas.
+Agentes com fundamento, escopo e critério produzem entregas mais consistentes.
+
+## Princípios do sistema
+1. Um agente = uma função principal.
+2. Uma skill = um método reutilizável.
+3. Um squad = uma unidade operacional.
+4. Todo output importante passa por revisão.
+5. Todo fundamento deve ser rastreável a fontes públicas.
+6. Toda doutrina do agente deve ser interpretada, não copiada.
+
+## Estrutura macro
+- Base
+- Biblioteca de especialistas
+- Squads
+- Skills
+- Fluxos
+- Comando `/edusquads`
+
+## Objetivo do comando `/edusquads`
+Ao ser invocado, Claude deve:
+1. entender a operação pedida
+2. mapear quais squads entram
+3. selecionar fundamentos adequados
+4. propor ou montar agentes/skills relevantes
+5. estruturar entregas com critérios de qualidade
+
+## Escala planejada
+- 16 squads
+- até 160 agentes, se mantido o padrão de 10 agentes por squad
+- biblioteca crescente de especialistas por especialidade

package/bin/edusquads.js

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+const args = process.argv.slice(2);
+const command = args.find((a) => !a.startsWith("-")) || "install";
+const force = args.includes("--force");
+const dryRun = args.includes("--dry-run");
+const targetArgIndex = args.findIndex((a) => a === "--target");
+const targetDir =
+  targetArgIndex >= 0 && args[targetArgIndex + 1]
+    ? path.resolve(args[targetArgIndex + 1])
+    : process.cwd();
+
+const PACKAGE_ROOT = path.resolve(__dirname, "..");
+
+const INSTALL_ITEMS = [
+  { src: ".claude/skills/edusquads", dest: ".claude/skills/edusquads" },
+  { src: "base", dest: "base" },
+  { src: "especialistas", dest: "especialistas" },
+  { src: "pesquisa", dest: "pesquisa" },
+  { src: "squads", dest: "squads" },
+  { src: "_edusquads/memoria/USUARIO-ATIVO.md", dest: "_edusquads/memoria/USUARIO-ATIVO.md" },
+  { src: "_edusquads/runs/RUN-MODELO.md", dest: "_edusquads/runs/RUN-MODELO.md" },
+  { src: "_edusquads/runs/RUNS-INDEX.md", dest: "_edusquads/runs/RUNS-INDEX.md" },
+  { src: "_edusquads/evidencias/EVIDENCIA-MODELO.md", dest: "_edusquads/evidencias/EVIDENCIA-MODELO.md" },
+  { src: "carrosseis.md", dest: "carrosseis.md" }
+];
+
+function help() {
+  console.log(`\nEduSquads CLI\n\nUso:\n  npx edusquads-cli install [--target <dir>] [--force] [--dry-run]\n  npx edusquads-cli --help\n\nOpções:\n  --target <dir>  Diretório do projeto de destino (default: diretório atual)\n  --force         Sobrescreve arquivos existentes\n  --dry-run       Simula instalação sem gravar arquivos\n`);
+}
+
+function ensureDir(p) {
+  if (dryRun) return;
+  fs.mkdirSync(p, { recursive: true });
+}
+
+function copyFile(src, dest) {
+  const exists = fs.existsSync(dest);
+  if (exists && !force) return "skipped";
+  ensureDir(path.dirname(dest));
+  if (!dryRun) fs.copyFileSync(src, dest);
+  return exists ? "overwritten" : "created";
+}
+
+function copyDir(src, dest, report) {
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  ensureDir(dest);
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath, report);
+    } else {
+      const status = copyFile(srcPath, destPath);
+      report[status] = (report[status] || 0) + 1;
+    }
+  }
+}
+
+function patchGitignore(target) {
+  const gitignorePath = path.join(target, ".gitignore");
+  const required = [
+    "_edusquads/browser_profile/",
+    "_edusquads/evidencias/"
+  ];
+
+  let current = "";
+  if (fs.existsSync(gitignorePath)) {
+    current = fs.readFileSync(gitignorePath, "utf-8");
+  }
+
+  let changed = false;
+  for (const line of required) {
+    if (!current.includes(line)) {
+      current += (current.endsWith("\n") || current.length === 0 ? "" : "\n") + line + "\n";
+      changed = true;
+    }
+  }
+
+  if (changed && !dryRun) fs.writeFileSync(gitignorePath, current, "utf-8");
+  return changed;
+}
+
+function writeInstallMarker(target) {
+  const markerPath = path.join(target, "_edusquads", "INSTALLATION.json");
+  const payload = {
+    installedAt: new Date().toISOString(),
+    package: "edusquads-cli",
+    version: "0.1.0"
+  };
+  ensureDir(path.dirname(markerPath));
+  if (!dryRun) fs.writeFileSync(markerPath, JSON.stringify(payload, null, 2), "utf-8");
+}
+
+function install() {
+  if (!fs.existsSync(targetDir)) {
+    console.error(`Diretório alvo não existe: ${targetDir}`);
+    process.exit(1);
+  }
+
+  const report = { created: 0, overwritten: 0, skipped: 0 };
+
+  for (const item of INSTALL_ITEMS) {
+    const src = path.join(PACKAGE_ROOT, item.src);
+    const dest = path.join(targetDir, item.dest);
+
+    if (!fs.existsSync(src)) {
+      console.error(`Origem não encontrada no pacote: ${item.src}`);
+      process.exit(1);
+    }
+
+    const stat = fs.statSync(src);
+    if (stat.isDirectory()) {
+      copyDir(src, dest, report);
+    } else {
+      const status = copyFile(src, dest);
+      report[status] = (report[status] || 0) + 1;
+    }
+  }
+
+  const gitignoreChanged = patchGitignore(targetDir);
+  writeInstallMarker(targetDir);
+
+  console.log(`\nEduSquads ${dryRun ? "(simulação) " : ""}instalado em: ${targetDir}`);
+  console.log(`Arquivos criados: ${report.created}`);
+  console.log(`Arquivos sobrescritos: ${report.overwritten}`);
+  console.log(`Arquivos ignorados (já existiam): ${report.skipped}`);
+  console.log(`.gitignore atualizado: ${gitignoreChanged ? "sim" : "não"}`);
+  console.log(`\nNo Claude Code, abra este projeto e use: /edusquads\n`);
+}
+
+if (args.includes("--help") || args.includes("-h")) {
+  help();
+  process.exit(0);
+}
+
+if (!["install", "init"].includes(command)) {
+  console.error(`Comando inválido: ${command}`);
+  help();
+  process.exit(1);
+}
+
+install();