@andespindola/crow-skills 0.1.0

package/README.md

@@ -0,0 +1,62 @@
+# crow-skills
+
+Skills com escopo explícito, conhecimento especializado preservado e fluxos comuns reutilizáveis.
+
+**Reconstrução em andamento.** A primeira versão com 32 contratos genéricos não atende à preservação de capacidades solicitada. Não use esse número nem o mapeamento por categoria como prova de substituição das originais. A revisão passa a abranger cada definição e seus recursos, modos e dependências, sem número fixo de skills ou limite artificial de linhas. Veja [critérios e progresso](docs/reconstruction.md).
+
+## Uso
+
+1. Escolha pela intenção, estado do projeto, stack e risco. Leia a descrição antes do corpo.
+2. Para uma tarefa localizada, use a especialista. Para uma iniciativa transversal, comece em `crow-platform`.
+3. Reutilize artefatos válidos; não repita discovery, perguntas, testes ou documentos concluídos.
+4. Entregue o artefato com alvo/revisão, evidência e pendências. Desconhecido não significa aprovado.
+5. Carregue outra skill só quando houver decisão distinta a tomar. Handoffs são opcionais, não dependências ocultas.
+
+Para adotar uma atuação mais coordenada em qualquer domínio, use `crow-behaviour`: tarefas substantivas recebem plano, delegação suportada, verificação e síntese; conversa e ajustes triviais continuam diretos. A skill adapta o comportamento às ferramentas reais, inclusive execução sequencial, sem depender do Workflow do Claude. Ela não muda o modelo/effort nem força carregamento automático pelo host. [Escopo e evidência](analysis/crow-behaviour.md).
+
+Exemplos:
+- Plataforma nova: `crow-platform` coordena; `crow-discovery` e `crow-spec` definem o que falta; as especialistas implementam/verificam por fatia.
+- Bug conhecido: `crow-debug`; sem workshop de produto.
+- Endpoint: `crow-backend` implementa, `crow-api-test` verifica o contrato, `crow-security-review` revisa se o risco exigir.
+- Dados Postgres: `crow-postgres` + teste do efeito real; não precisa carregar toda a biblioteca.
+- Revisão: `crow-security-review` não modifica ou executa o alvo. Implementação é outra tarefa.
+
+[Catálogo e ownership](docs/catalog.md) · [Playbooks](docs/playbooks.md) · [Contrato de composição](docs/composition.md) · [Migração](docs/migration.md)
+
+## Instalação e portabilidade
+
+O pacote de cada skill é somente sua pasta em `skills/`. O [CLI crow-skills](docs/cli.md) instala cópias completas e versionadas em agentes/escopos explícitos, com preview, saída JSON, detecção de conflitos e recuperação. Requer Python 3.10+; Git para fontes em clone, Node 18+ para o launcher npm; mutações em macOS/Linux. A distribuição npm privada `@andespindola/crow-skills` inclui um snapshot completo das skills, sem clone ou hooks que as instalem automaticamente.
+
+```sh
+./bin/crow-skills list
+./bin/crow-skills install crow-behaviour --agents claude,codex --global --dry-run
+./bin/crow-skills install crow-behaviour --agents claude,codex --global --yes --json
+./bin/crow-skills related crow-backend --agents claude --global
+```
+
+Também é possível copiar/referenciar manualmente as pastas escolhidas no diretório suportado pelo host. Para symlink manual, mantenha o checkout no mesmo caminho. O CLI v0.1 só instala cópias; não sobrescreve conflitos ou edições sem opção explícita e backup.
+
+Os nomes têm prefixo `crow-` para coexistir com o catálogo anterior. Não há instalação global automática, auto-update ou reconfiguração de agentes. O CLI mostra complementaridade por role/owner/handoffs e overlays, mas só instala as selecionadas; `--with-handoffs` é opt-in para handoffs diretos. Operações especializadas podem depender de ferramentas explicitamente documentadas: `crow-interface`, por exemplo, inclui adaptador de motor versionado e instalação explícita dessa dependência. A descoberta depende do runtime; presença do arquivo não prova carregamento.
+
+Cada pacote mantém suas referências locais e declara dependências operacionais. Os nomes de próximos responsáveis são sugestões, não downloads implícitos. Sem ferramenta necessária, entregue somente o que puder comprovar e descreva a capacidade não executada, em vez de alegar equivalência.
+
+Criar/disponibilizar o CLI **não instala nem substitui** as skills locais de nenhum agente. Instalação, migração global e remoção de aliases antigos são operações explícitas, não efeitos de executar list/status/doctor ou de atualizar este checkout.
+
+## Verificação
+
+Python 3.10+; somente biblioteca padrão:
+
+```sh
+python3 scripts/check.py
+python3 -m unittest discover -s tests -v
+```
+
+O checker verifica frontmatter no subconjunto YAML simples usado aqui, catálogo, owners únicos, referências locais autocontidas, handoffs válidos, placeholders e exposição de caminhos privados/credenciais. Não impõe limites artificiais ao corpo, não interpreta instruções das skills nem chama ferramentas externas.
+
+Os testes incluem mutações do pacote e invariantes de composição. Não medem a qualidade das respostas de um modelo. Avaliações comportamentais observadas, quando disponíveis, ficam em [docs/evaluations](docs/evaluations/README.md); não confundir texto esperado de fixture com teste executado por agente.
+
+## Manutenção
+
+Fonte canônica: SKILL.md para instruções, catalog.json para papel/ownership/handoffs. O checker exige sincronismo de nome, descrição e saída. Altere o menor escopo que resolve a falha demonstrada. Veja [CONTRIBUTING.md](CONTRIBUTING.md).
+
+Sem alegação de ganho percentual ou auditoria integral da biblioteca anterior. [Proveniência e limites](docs/provenance.md).

package/bin/npm-crow-skills.cjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+'use strict';
+const { spawnSync } = require('node:child_process');
+const { resolve } = require('node:path');
+
+const args = process.argv.slice(2);
+const python = process.env.CROW_SKILLS_PYTHON || 'python3';
+// A direct Python entry file avoids importing from the caller's CWD/PYTHONPATH.
+const entry = resolve(__dirname, '..', 'crow_skills', 'npm_entry.py');
+const result = spawnSync(python, ['-I', entry, ...args], { stdio: 'inherit', shell: false });
+if (result.error) {
+  const error = { code: 'python_unavailable', message: 'Python 3.10+ é necessário. Instale-o ou defina CROW_SKILLS_PYTHON para o executável.' };
+  if (args.includes('--json')) process.stdout.write(JSON.stringify({ schema_version: 1, ok: false, command: null, error }) + '\n');
+  else process.stderr.write(error.message + '\n');
+  process.exitCode = 1;
+} else if (result.signal) {
+  process.exitCode = result.signal === 'SIGINT' ? 130 : 1;
+} else {
+  process.exitCode = result.status === null ? 1 : result.status;
+}

package/catalog.json

@@ -0,0 +1,398 @@
+{
+  "version": 1,
+  "composition": {
+    "overlays": [
+      {
+        "skill": "crow-behaviour",
+        "roles": ["coordinator", "specialist", "reviewer"]
+      }
+    ]
+  },
+  "skills": [
+    {
+      "name": "crow-behaviour",
+      "title": "Atuação coordenada",
+      "description": "Aplique um modo de atuação orientado a orquestração, profundidade e verificação em tarefas substantivas. Decomponha, delegue com as capacidades reais do agente e sintetize evidências. Em conversa ou ajustes triviais, responda diretamente; não simule agentes nem altere permissões.",
+      "role": "coordinator",
+      "owns": "execution-ledger",
+      "next": []
+    },
+    {
+      "name": "crow-platform",
+      "title": "Entrega de plataforma",
+      "description": "Coordene uma plataforma ou iniciativa que atravessa produto, design, engenharia e operação. Não use para um bug ou ajuste isolado.",
+      "role": "coordinator",
+      "owns": "delivery-map",
+      "next": [
+        "crow-discovery",
+        "crow-spec",
+        "crow-architecture",
+        "crow-release"
+      ]
+    },
+    {
+      "name": "crow-discovery",
+      "title": "Problema e decisão de produto",
+      "description": "Investigue um problema de produto, segmento e hipótese antes de comprometer uma solução. Não reabra discovery para um bug conhecido.",
+      "role": "specialist",
+      "owns": "problem-brief",
+      "next": [
+        "crow-spec",
+        "crow-growth"
+      ]
+    },
+    {
+      "name": "crow-spec",
+      "title": "Escopo e critérios de aceite",
+      "description": "Transforme uma decisão de produto em uma especificação enxuta, fatias de release e critérios testáveis. Não conduz pesquisa de mercado.",
+      "role": "specialist",
+      "owns": "feature-spec",
+      "next": [
+        "crow-domain",
+        "crow-design",
+        "crow-qa"
+      ]
+    },
+    {
+      "name": "crow-domain",
+      "title": "Vocabulário e invariantes",
+      "description": "Resolva conceitos, identidades, estados e invariantes do domínio durante o desenho. Não use como gerador de arquitetura técnica.",
+      "role": "specialist",
+      "owns": "domain-glossary",
+      "next": [
+        "crow-architecture",
+        "crow-backend",
+        "crow-postgres"
+      ]
+    },
+    {
+      "name": "crow-architecture",
+      "title": "Interfaces e decisões de engenharia",
+      "description": "Desenhe ou revise módulos e interfaces para uma mudança real. Use também para documentar arquitetura existente, separando observado de proposto.",
+      "role": "specialist",
+      "owns": "architecture-note",
+      "next": [
+        "crow-threat-model",
+        "crow-backend",
+        "crow-frontend",
+        "crow-qa"
+      ]
+    },
+    {
+      "name": "crow-design",
+      "title": "Direção visual e contrato de UI",
+      "description": "Defina o contrato de experiência visual, fluxos, tokens e estados para implementação. Entrega brief/decisões, sem editar a interface nem repetir discovery resolvido.",
+      "role": "specialist",
+      "owns": "design-contract",
+      "next": [
+        "crow-frontend",
+        "crow-accessibility"
+      ]
+    },
+    {
+      "name": "crow-frontend",
+      "title": "Interface implementada",
+      "description": "Implemente componentes e jornadas web com contrato de dados e estados completos. Não redefine a direção visual nem escolhe framework por padrão.",
+      "role": "specialist",
+      "owns": "ui-change",
+      "next": [
+        "crow-api-test",
+        "crow-accessibility",
+        "crow-performance"
+      ]
+    },
+    {
+      "name": "crow-backend",
+      "title": "Serviço e regras de negócio",
+      "description": "Implemente APIs, jobs e regras no backend da stack existente, com validação, autorização e efeitos controlados. Não projeta a plataforma inteira.",
+      "role": "specialist",
+      "owns": "service-change",
+      "next": [
+        "crow-postgres",
+        "crow-api-test",
+        "crow-security-review"
+      ]
+    },
+    {
+      "name": "crow-postgres",
+      "title": "Dados Postgres",
+      "description": "Desenhe migrations, consultas e controles Postgres quando essa for a base do projeto. Não substitui autorização da aplicação.",
+      "role": "specialist",
+      "owns": "db-change",
+      "next": [
+        "crow-api-test",
+        "crow-performance",
+        "crow-release"
+      ]
+    },
+    {
+      "name": "crow-threat-model",
+      "title": "Ameaças do desenho",
+      "description": "Modele ativos, fluxos, fronteiras de confiança e abuso para um desenho ou mudança de risco. Não executa ataques nem certifica segurança.",
+      "role": "reviewer",
+      "owns": "threat-register",
+      "next": [
+        "crow-security-review",
+        "crow-agent-security",
+        "crow-qa"
+      ]
+    },
+    {
+      "name": "crow-security-review",
+      "title": "Revisão de segurança",
+      "description": "Revise plano, código ou diff em busca de violações concretas de confiança e valide alegações. Não é revisão estética nem pentest ativo.",
+      "role": "reviewer",
+      "owns": "security-findings",
+      "next": [
+        "crow-security-scan",
+        "crow-security-test",
+        "crow-qa"
+      ]
+    },
+    {
+      "name": "crow-security-scan",
+      "title": "Scans e evidência estática",
+      "description": "Execute ou analise SAST, dependências, imagens e IaC conforme o alvo; normalize e compare resultados. Não confirma explorabilidade nem faz autofix.",
+      "role": "specialist",
+      "owns": "scan-evidence",
+      "next": [
+        "crow-security-review"
+      ]
+    },
+    {
+      "name": "crow-agent-security",
+      "title": "Limites de agentes e LLMs",
+      "description": "Revise apps com LLM, ferramentas, fontes externas e memória para injeção, autoridade excessiva e efeitos inseguros. Não tenta contornar controles de terceiros.",
+      "role": "reviewer",
+      "owns": "agent-controls",
+      "next": [
+        "crow-threat-model",
+        "crow-security-review",
+        "crow-secrets"
+      ]
+    },
+    {
+      "name": "crow-secrets",
+      "title": "Ciclo de vida de credenciais",
+      "description": "Revise ou ajuste armazenamento, escopo, entrega e rotação de credenciais no escopo pedido. Nunca exibe valores nem cria cópias em documentação.",
+      "role": "specialist",
+      "owns": "secret-plan",
+      "next": [
+        "crow-release",
+        "crow-observe"
+      ]
+    },
+    {
+      "name": "crow-qa",
+      "title": "Verificação de comportamento",
+      "description": "Planeje e execute verificações por risco e critérios de aceite, escolhendo camadas sem duplicar toda a suíte. Não é automação pontual de navegação.",
+      "role": "specialist",
+      "owns": "test-evidence",
+      "next": [
+        "crow-api-test",
+        "crow-accessibility",
+        "crow-release"
+      ]
+    },
+    {
+      "name": "crow-api-test",
+      "title": "Contrato e autorização de API",
+      "description": "Crie ou execute testes de API de sucesso, schema, erro e autorização. Não substitui Pact entre equipes nem navegação de UI.",
+      "role": "specialist",
+      "owns": "api-evidence",
+      "next": [
+        "crow-qa",
+        "crow-security-review"
+      ]
+    },
+    {
+      "name": "crow-accessibility",
+      "title": "Uso acessível da jornada",
+      "description": "Valide e corrija semântica, teclado, foco, leitura assistiva e autenticação de uma interface real. Não certifica conformidade completa por scanner.",
+      "role": "specialist",
+      "owns": "a11y-evidence",
+      "next": [
+        "crow-frontend",
+        "crow-qa"
+      ]
+    },
+    {
+      "name": "crow-performance",
+      "title": "Otimização com evidência",
+      "description": "Investigue lentidão e valide otimizações web, API, banco ou nativas com workload controlado. Não reporta ganho com um único antes/depois.",
+      "role": "specialist",
+      "owns": "perf-evidence",
+      "next": [
+        "crow-debug",
+        "crow-frontend",
+        "crow-postgres",
+        "crow-observe"
+      ]
+    },
+    {
+      "name": "crow-debug",
+      "title": "Reprodução e causa do bug",
+      "description": "Diagnostique um defeito a partir de reprodução e hipóteses falsificáveis, corrigindo a causa com regressão. Não reabre estratégia de produto.",
+      "role": "specialist",
+      "owns": "bug-fix",
+      "next": [
+        "crow-qa",
+        "crow-performance",
+        "crow-architecture"
+      ]
+    },
+    {
+      "name": "crow-infra",
+      "title": "Workload e infraestrutura",
+      "description": "Planeje ou altere infra/IaC da plataforma existente com validação, custo e recuperação proporcionais. Não impõe Kubernetes ou multi-cloud.",
+      "role": "specialist",
+      "owns": "infra-plan",
+      "next": [
+        "crow-release",
+        "crow-secrets",
+        "crow-security-review"
+      ]
+    },
+    {
+      "name": "crow-release",
+      "title": "Promoção e recuperação",
+      "description": "Prepare ou execute release/deploy no fluxo real do repo, com artefato identificado, gates e recuperação. Não considera plano ou CI verde prova de deploy.",
+      "role": "specialist",
+      "owns": "release-evidence",
+      "next": [
+        "crow-qa",
+        "crow-observe"
+      ]
+    },
+    {
+      "name": "crow-observe",
+      "title": "Sinais e operação",
+      "description": "Configure ou avalie logs, métricas, traces, alertas e runbooks para detectar falhas e orientar resposta. Não cria um stack de observabilidade sem demanda.",
+      "role": "specialist",
+      "owns": "observability-change",
+      "next": [
+        "crow-debug",
+        "crow-performance",
+        "crow-release"
+      ]
+    },
+    {
+      "name": "crow-seo",
+      "title": "Saída pública e descoberta",
+      "description": "Revise conteúdo e saída técnica de páginas públicas para busca, coerência e indexação. Não otimiza área logada nem promete ranking.",
+      "role": "specialist",
+      "owns": "seo-change",
+      "next": [
+        "crow-frontend",
+        "crow-growth"
+      ]
+    },
+    {
+      "name": "crow-media",
+      "title": "Artefatos de imagem, áudio e vídeo",
+      "description": "Crie ou edite mídia a partir de brief e assets autorizados, preservando fontes e validando o arquivo final. Não exige um fornecedor específico.",
+      "role": "specialist",
+      "owns": "media-artifact",
+      "next": [
+        "crow-documents",
+        "crow-design"
+      ]
+    },
+    {
+      "name": "crow-documents",
+      "title": "Documentos e entregáveis",
+      "description": "Crie ou edite documentos, planilhas, apresentações ou HTML a partir de conteúdo real, validando conteúdo e formato final. Não usa exportadores irrelevantes.",
+      "role": "specialist",
+      "owns": "document-artifact",
+      "next": [
+        "crow-design",
+        "crow-media"
+      ]
+    },
+    {
+      "name": "crow-skill-author",
+      "title": "Manutenção de skills",
+      "description": "Crie ou revise uma skill com escopo único, descoberta precisa e validação de uso isolado e em composição. Não instala automaticamente pacotes de terceiros.",
+      "role": "specialist",
+      "owns": "skill-package",
+      "next": [
+        "crow-security-review"
+      ]
+    },
+    {
+      "name": "crow-reverse",
+      "title": "Compreensão de artefatos",
+      "description": "Analise código, binário ou protocolo em escopo para compreender comportamento e interoperabilidade, preservando a evidência. Não modifica controles de terceiros por padrão.",
+      "role": "specialist",
+      "owns": "reverse-report",
+      "next": [
+        "crow-security-review",
+        "crow-native-mobile"
+      ]
+    },
+    {
+      "name": "crow-security-test",
+      "title": "Verificação dinâmica autorizada",
+      "description": "Valide dinamicamente uma hipótese de segurança em ativos autorizados com escopo, limites e evidência mínimos. Não faz varredura ou DoS por padrão.",
+      "role": "specialist",
+      "owns": "security-test-evidence",
+      "next": [
+        "crow-security-review",
+        "crow-qa"
+      ]
+    },
+    {
+      "name": "crow-growth",
+      "title": "Decisões de crescimento",
+      "description": "Avalie posicionamento, preço, aquisição, retenção e economia de produto com dados disponíveis e experimentos. Não escreve implementação nem inventa métricas.",
+      "role": "specialist",
+      "owns": "growth-decision",
+      "next": [
+        "crow-discovery",
+        "crow-spec",
+        "crow-seo"
+      ]
+    },
+    {
+      "name": "crow-product-leadership",
+      "title": "Decisão e coordenação de produto",
+      "description": "Estruture alinhamento de stakeholders, responsabilidades e desenvolvimento profissional em produto quando solicitado. Não assume autoridade sobre pessoas.",
+      "role": "specialist",
+      "owns": "leadership-plan",
+      "next": [
+        "crow-spec",
+        "crow-growth"
+      ]
+    },
+    {
+      "name": "crow-native-mobile",
+      "title": "Aplicação nativa e mobile",
+      "description": "Implemente ou diagnostique fluxos nativos/mobile na stack existente, respeitando lifecycle, permissões e plataforma. Não aplica regras web indiscriminadamente.",
+      "role": "specialist",
+      "owns": "native-change",
+      "next": [
+        "crow-api-test",
+        "crow-performance",
+        "crow-release"
+      ]
+    },
+    {
+      "name": "crow-browser",
+      "title": "Automação pontual de browser",
+      "description": "Inspecione e opere uma página com ferramentas de browser disponíveis, usando estado observado e respeitando efeitos. Não gera suíte E2E por padrão.",
+      "role": "specialist",
+      "owns": "browser-evidence",
+      "next": [
+        "crow-qa"
+      ]
+    },
+    {
+      "name": "crow-interface",
+      "title": "Experiência de interface",
+      "description": "Crie, revise ou refine a experiência visual de interfaces web e nativas, com modos distintos de planejamento, crítica, auditoria, implementação e variantes live. Não implementa backend nem integração de dados por efeito colateral.",
+      "role": "specialist",
+      "owns": "interface-result",
+      "next": ["crow-design", "crow-frontend", "crow-accessibility", "crow-performance"]
+    }
+  ]
+}

package/crow_skills/__init__.py

@@ -0,0 +1,3 @@
+"""Portable, local-first installer for the crow-skills catalogue."""
+
+__version__ = "0.1.0"

package/crow_skills/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

package/crow_skills/agents.py

@@ -0,0 +1,45 @@
+"""Explicit destination adapters; detection never launches an agent."""
+from pathlib import Path
+import os
+import shutil
+from .source import CrowError
+
+AGENTS = {
+    "codex": (".agents/skills", ".agents/skills", "codex"),
+    "claude": (".claude/skills", ".claude/skills", "claude"),
+    "gemini": (".gemini/skills", ".gemini/skills", "gemini"),
+    "devin": (".config/devin/skills", ".devin/skills", "devin"),
+    "shared": (".agents/skills", ".agents/skills", None),
+}
+
+
+def destinations(names, home, project=None, custom=None):
+    if custom:
+        if names:
+            raise CrowError("usage", "--dest e --agents não podem ser combinados.")
+        return [{"path": str(Path(custom).expanduser().absolute()), "agents": ["custom"]}]
+    if not names:
+        raise CrowError("usage", "Selecione --agents; não há instalação implícita em todos os agentes.")
+    selected = names.split(",") if isinstance(names, str) else names
+    result = {}
+    for name in selected:
+        name = name.strip()
+        if name not in AGENTS:
+            raise CrowError("unknown_agent", "Agente desconhecido: " + name)
+        user_path, project_path, _ = AGENTS[name]
+        path = (Path(project) / project_path) if project else (home / user_path)
+        # Respect explicit XDG config, but isolate it when --home selects another profile.
+        if name == "devin" and not project and home == Path.home().resolve() and os.getenv("XDG_CONFIG_HOME"):
+            path = Path(os.environ["XDG_CONFIG_HOME"]).expanduser() / "devin/skills"
+        key = str(path.absolute())
+        result.setdefault(key, {"path": key, "agents": []})
+        if name not in result[key]["agents"]:
+            result[key]["agents"].append(name)
+    return list(result.values())
+
+
+def inventory(home):
+    return [{"name": name, "executable_found": bool(binary and shutil.which(binary)),
+             "global_path": str(home / user), "project_path": project,
+             "activation_verified": False}
+            for name, (user, project, binary) in AGENTS.items()]