@andespindola/crow-skills 0.10.1 → 0.11.1

package/README.md

@@ -2,10 +2,22 @@
 
 Skills com escopo explícito, conhecimento especializado preservado e fluxos comuns reutilizáveis.
 
-**Versão 0.10.1** ([mudanças](CHANGELOG.md)): o controle de recursos passa a tratar swap e CPU como eixos de pressão (swap quase cheio e carga alta reduzem agentes, jobs e workers; nenhuma recomendação cresce com a pressão), mostra a CPU% dos CLIs de agente, traz `crow-skills resources --exec-prefix` para rodar jobs pesados em prioridade baixa e as regras da crow-behaviour sob pressão (reduzir já, um job pesado por vez, não repetir verificação, validação ampla no CI); os hooks do Codex vão para o `config.toml` quando o `hooks.json` é symlink. A 0.10.0 trouxe o crow-broadcast, que compartilha, de forma passiva, o que cada sessão e cada CLI (Claude Code, Codex, Gemini CLI, Antigravity, Devin, inclusive dentro do Uniflow) está fazendo nesta máquina: repositório, clone, branch, execução crow em andamento e arquivos em edição; o prompt recebe um resumo só quando outra sessão viva está no mesmo repositório, editar um arquivo que outra sessão tocou ou trocar de branch num clone em uso gera aviso (ou bloqueio, se configurado), e `crow-skills broadcast claim` reserva áreas; a crow-behaviour consulta isso antes de planejar e reserva as áreas que delega ([crow-broadcast](docs/broadcast.md)). A 0.9.0 trouxe o controle de memória da máquina: `crow-skills resources` mede memória, pressão e os CLIs de agente em execução e recomenda quantos agentes, jobs pesados e workers rodar em paralelo; a crow-behaviour consulta essa recomendação antes de cada fan-out (sob `warn` reduz, sob `critical` segue sequencial), limita workers de builds e testes, reutiliza um dev server por projeto e encerra o que abriu, e 15 especialistas que sobem processos pesados ganharam a regra correspondente; o hook de prompt e as status lines só avisam quando a máquina está sob pressão. A 0.8.0 trouxe `crow-skills mode on|off`, que liga e desliga a crow-behaviour em todas as sessões e CLIs (Claude Code, Codex, Gemini CLI, Antigravity, Devin) a partir do próximo prompt, com `/crow on|off` dentro da sessão e o indicador `▸▸ crow on` na status line; a crow-behaviour mostra o progresso como a lista de agentes do host (`● main`, `○ dono  atividade`); `crow-skills events` publica um barramento de eventos dos hooks para terminais; `crow-skills autoupdate on` atualiza o CLI e as skills gerenciadas todo dia e no login. A 0.7.1 trouxe as correções da revalidação no Codex às skills especialistas; a 0.7.0 tornou o Uniflow agente de instalação (`--agents uniflow`); a 0.6.1 passou a mostrar o progresso da crow-behaviour na própria conversa; a 0.6.0 trouxe as regras de entrega das 32 skills especialistas, a partir da [validação no Codex](docs/evaluations/2026-10-26-codex.md).
+**Versão 0.11.1** ([mudanças](CHANGELOG.md)): o Codex deixa de mostrar em dobro as skills que o Uniflow já projeta em `~/.codex/skills`. A 0.11.0 trouxe `crow-skills setup --yes`, que configura de uma vez todos os CLIs de agente da máquina, e `crow-skills upgrade --yes`, que atualiza tudo numa só passada; os hooks que o crow-skills grava já saem habilitados (no Codex, aprovados pelo próprio `codex app-server`, só os do crow-skills; `--no-trust` desliga) e `status`/`doctor` mostram se cada CLI vai rodá-los; a ajuda ficou curta e organizada por tarefa. A 0.10.1 passou a tratar swap e CPU como eixos de pressão no controle de recursos (swap quase cheio e carga alta reduzem agentes, jobs e workers; nenhuma recomendação cresce com a pressão), mostrou a CPU% dos CLIs de agente, trouxe `crow-skills resources --exec-prefix` para rodar jobs pesados em prioridade baixa e as regras da crow-behaviour sob pressão (reduzir já, um job pesado por vez, não repetir verificação, validação ampla no CI); os hooks do Codex vão para o `config.toml` quando o `hooks.json` é symlink. A 0.10.0 trouxe o crow-broadcast, que compartilha, de forma passiva, o que cada sessão e cada CLI (Claude Code, Codex, Gemini CLI, Antigravity, Devin, inclusive dentro do Uniflow) está fazendo nesta máquina: repositório, clone, branch, execução crow em andamento e arquivos em edição; o prompt recebe um resumo só quando outra sessão viva está no mesmo repositório, editar um arquivo que outra sessão tocou ou trocar de branch num clone em uso gera aviso (ou bloqueio, se configurado), e `crow-skills broadcast claim` reserva áreas; a crow-behaviour consulta isso antes de planejar e reserva as áreas que delega ([crow-broadcast](docs/broadcast.md)). A 0.9.0 trouxe o controle de memória da máquina: `crow-skills resources` mede memória, pressão e os CLIs de agente em execução e recomenda quantos agentes, jobs pesados e workers rodar em paralelo; a crow-behaviour consulta essa recomendação antes de cada fan-out (sob `warn` reduz, sob `critical` segue sequencial), limita workers de builds e testes, reutiliza um dev server por projeto e encerra o que abriu, e 15 especialistas que sobem processos pesados ganharam a regra correspondente; o hook de prompt e as status lines só avisam quando a máquina está sob pressão. A 0.8.0 trouxe `crow-skills mode on|off`, que liga e desliga a crow-behaviour em todas as sessões e CLIs (Claude Code, Codex, Gemini CLI, Antigravity, Devin) a partir do próximo prompt, com `/crow on|off` dentro da sessão e o indicador `▸▸ crow on` na status line; a crow-behaviour mostra o progresso como a lista de agentes do host (`● main`, `○ dono  atividade`); `crow-skills events` publica um barramento de eventos dos hooks para terminais; `crow-skills autoupdate on` atualiza o CLI e as skills gerenciadas todo dia e no login. A 0.7.1 trouxe as correções da revalidação no Codex às skills especialistas; a 0.7.0 tornou o Uniflow agente de instalação (`--agents uniflow`); a 0.6.1 passou a mostrar o progresso da crow-behaviour na própria conversa; a 0.6.0 trouxe as regras de entrega das 32 skills especialistas, a partir da [validação no Codex](docs/evaluations/2026-10-26-codex.md).
 
 **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).
 
+## Começar
+
+Uma linha configura todos os CLIs de agente da máquina (Claude Code, Codex, Gemini CLI, Antigravity, Devin, Uniflow e o segmento do tmux):
+
+```sh
+brew install andersonflima/tap/crow-skills && crow-skills setup --yes
+# ou, com npm:
+npm install -g @andespindola/crow-skills && crow-skills setup --yes
+```
+
+`setup` detecta cada CLI (binário no PATH ou diretório de configuração), instala todas as skills, o guia, as integrações e os hooks do modo crow já habilitados, liga o modo crow e o autoupdate, e termina com uma tabela por CLI e o doctor. `crow-skills setup --dry-run` mostra o plano sem gravar nada; rodar de novo só corrige o que mudou. Para atualizar tudo depois: `crow-skills upgrade --yes`. `crow-skills` sozinho mostra a ajuda curta e o estado atual; `crow-skills help <comando>` detalha cada comando. Detalhes em [setup, upgrade e ajuda](docs/cli.md#configurar-a-máquina-setup).
+
 ## Uso
 
 1. Escolha pela intenção, estado do projeto, stack e risco. Leia a descrição antes do corpo.
@@ -30,10 +42,12 @@ Exemplos:
 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. No [Uniflow](docs/cli.md#uniflow), `--agents uniflow --global` grava as skills no store dele (`~/.config/uniflow/skills`), sem tocar no resto da configuração. Em `--global`, instalar a crow-behaviour também grava o guia aditivo do agente (claude, codex, gemini, devin) para usar as skills; `--no-guide` desliga. As integrações de interface (status lines do Claude Code, do Codex e do Antigravity, hooks do modo crow em cada CLI, comando `/crow`, segmento tmux) seguem o mesmo fluxo, preservando a configuração existente; `--no-integrations` desliga. O [barramento de eventos](docs/events.md) e a atualização automática (`crow-skills autoupdate on`) estão no [CLI](docs/cli.md).
 
 ```sh
-npm install -g @andespindola/crow-skills@0.10.1
+npm install -g @andespindola/crow-skills@0.11.1
 crow-skills mode
 crow-skills progress
 ./bin/crow-skills list
+./bin/crow-skills groups
+./bin/crow-skills install --group essencial --agents claude,codex --global --dry-run
 ./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

package/catalog.json

@@ -8,6 +8,30 @@
       }
     ]
   },
+  "groups": [
+    {"name": "essencial", "title": "Essencial", "description": "Coordenação e o que serve a quase todo projeto: arquitetura, especificação, depuração, testes e revisão de segurança",
+     "skills": ["crow-behaviour", "crow-architecture", "crow-spec", "crow-debug", "crow-qa", "crow-security-review"]},
+    {"name": "web", "title": "Web", "description": "Interfaces web: direção visual, implementação, acessibilidade, navegador e SEO",
+     "skills": ["crow-frontend", "crow-interface", "crow-design", "crow-accessibility", "crow-browser", "crow-seo"]},
+    {"name": "backend", "title": "Backend", "description": "Serviços, APIs, dados e domínio",
+     "skills": ["crow-backend", "crow-api-test", "crow-postgres", "crow-domain", "crow-architecture"]},
+    {"name": "qualidade", "title": "Qualidade", "description": "Testes, defeitos, desempenho e observabilidade",
+     "skills": ["crow-qa", "crow-debug", "crow-performance", "crow-observe"]},
+    {"name": "seguranca", "title": "Segurança", "description": "Revisão, varredura, prova, modelagem de ameaças, credenciais e apps com LLM",
+     "skills": ["crow-security-review", "crow-security-scan", "crow-security-test", "crow-threat-model", "crow-secrets", "crow-agent-security"]},
+    {"name": "infra", "title": "Infra e entrega", "description": "Infraestrutura, release e coordenação de plataforma",
+     "skills": ["crow-infra", "crow-release", "crow-platform"]},
+    {"name": "mobile", "title": "Mobile", "description": "Apps nativos e mobile",
+     "skills": ["crow-native-mobile"]},
+    {"name": "produto", "title": "Produto", "description": "Descoberta, especificação, crescimento, liderança e coordenação de plataforma",
+     "skills": ["crow-discovery", "crow-spec", "crow-growth", "crow-product-leadership", "crow-platform"]},
+    {"name": "midia-docs", "title": "Mídia e documentos", "description": "Mídia, documentos, planilhas e apresentações",
+     "skills": ["crow-media", "crow-documents"]},
+    {"name": "reverse", "title": "Engenharia reversa", "description": "Análise de código, binário ou protocolo",
+     "skills": ["crow-reverse"]},
+    {"name": "autoria", "title": "Autoria de skills", "description": "Criar ou revisar skills",
+     "skills": ["crow-skill-author"]}
+  ],
   "skills": [
     {
       "name": "crow-behaviour",

package/crow_skills/__init__.py

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

package/crow_skills/autoupdate.py

@@ -13,6 +13,10 @@ Results go to ~/.local/state/crow-skills/autoupdate/state.json (last run and
 a short history), shown by ``autoupdate status``, ``doctor`` and
 ``events snapshot``. Command output of brew/npm/git is never stored or
 printed: only exit codes and versions.
+
+``crow-skills upgrade`` is the same run started by hand (``trigger:
+"upgrade"``); both go through :func:`run`, and ``--dry-run`` of either goes
+through :func:`preview`, which runs nothing and writes nothing.
 """
 from datetime import datetime, timezone
 import json
@@ -289,8 +293,76 @@ def self_upgrade(install, git_pull):
     return {"kind": "unknown", "result": "skipped", "reason": "instalação não reconhecida (brew, npm ou checkout git)"}
 
 
-def skills_update(home):
-    """update --global for every agent with managed installs; modified skills are kept and reported."""
+def preview_self(install, git_pull):
+    """What the self step would do, without running brew/npm/git."""
+    if install["kind"] in ("brew", "npm"):
+        return {"kind": install["kind"], "result": "would_run", "command": list(install["upgrade"]), "before": __version__}
+    if install["kind"] == "git":
+        if not git_pull:
+            return {"kind": "git", "result": "skipped", "reason": "checkout git: atualize com git pull, ou use --git-pull"}
+        return {"kind": "git", "result": "would_run", "command": ["git", "-C", install["root"], "pull", "--ff-only"],
+                "before": __version__, "note": "só se o checkout estiver limpo em main/master"}
+    return {"kind": "unknown", "result": "skipped", "reason": "instalação não reconhecida (brew, npm ou checkout git)"}
+
+
+def broken_projections(agent, home, store, rows):
+    """Uniflow links of this CLI whose store entry was edited or lost files: the CLI may not load them, so
+    upgrade reports them as needing the user (same as setup), with the command that restores the store."""
+    from .guide import broken_fix, store_broken
+    names = set()
+    if any(r["status"] == "uniflow_link" for r in rows):
+        bad = store_broken(home, store)
+        names |= {r["name"] for r in rows if r["status"] == "uniflow_link" and r["name"] in bad}
+    if agent == "codex":
+        from . import projection
+        names |= {n for n, kind in projection.links(home, store).items() if kind == "modified"}
+    return [{"name": n, "status": "uniflow_link_modified", "fix": broken_fix(n)} for n in sorted(names)]
+
+
+def reinstall_behaviour(home, entry, dry_run, trust):
+    """Codex without a working crow-behaviour (its projection is broken, no native copy): install it natively,
+    as setup does, so the guide and hooks keep a coordinator to point to."""
+    from .cli import parser, run as cli_run
+    argv = ["install", "crow-behaviour", "--agents", "codex", "--global", "--json", "--home", str(home),
+            "--dry-run" if dry_run else "--yes"]
+    if not trust:
+        argv.append("--no-trust")
+    data = cli_run(parser().parse_args(argv))
+    if any(c["name"] == "crow-behaviour" and c["action"] != "unchanged" for c in data["changes"]):
+        entry["updated"].append("crow-behaviour")
+        entry["transaction"] = data.get("transaction")
+
+
+def codex_duplicates(home, store, entry, names, dry_run):
+    """Codex sees Uniflow's links in ~/.codex/skills: those names are not updated natively, and intact managed
+    native copies of them are removed through uninstall (backup, transaction). Returns the names to update."""
+    from . import projection
+    from .cli import parser, run as cli_run
+    seen = projection.projected("codex", home, store)
+    if not seen:
+        return names
+    dupes = projection.duplicates(home, store)
+    entry["via_uniflow"] = sorted(set(entry["via_uniflow"]) | seen)
+    entry["kept"] = [k for k in entry["kept"] if k["name"] not in seen]
+    entry["kept"] += [{"name": n, "status": "duplicate_modified"} for n in dupes["modified"]]
+    entry["kept"] += [{"name": n, "status": "duplicate_shared"} for n in dupes["shared"]]
+    if dupes["remove"]:
+        argv = ["uninstall", *dupes["remove"], "--agents", "codex", "--global", "--json", "--home", str(home),
+                "--dry-run" if dry_run else "--yes", "--no-integrations"]
+        try:
+            data = cli_run(parser().parse_args(argv))
+            entry["removed"] = [{"name": c["name"], "reason": "removida: duplicava a projeção do Uniflow"}
+                                for c in data["changes"] if c["action"] != "unchanged"]
+            entry["removal_transaction"] = data.get("transaction")
+        except CrowError as exc:
+            entry["error"] = {"code": exc.code, "message": str(exc)}
+    return [n for n in names if n not in seen]
+
+
+def skills_update(home, trust=True, dry_run=False):
+    """update --global for every agent with managed installs; modified skills are kept and reported.
+
+    dry_run: the same per-agent plan with update --dry-run; "updated" lists what would change."""
     from . import cli
     from .cli import parser, run as cli_run
     from .storage import Store
@@ -313,8 +385,33 @@ def skills_update(home):
         except (CrowError, OSError) as exc:
             results.append({"agent": agent, "error": {"code": getattr(exc, "code", "io_error"), "message": str(exc)}})
             continue
+        from .guide import store_managed
+        store_ok = store_managed(home, store) if any(r["status"] == "uniflow_link" for r in rows) else set()
+        projected = sorted(r["name"] for r in rows if r["status"] == "uniflow_link" and r["name"] in store_ok)
+        if agent == "codex":
+            from . import projection
+            projected = sorted(set(projected) | projection.projected("codex", home, store))  # ~/.codex/skills links
+        broken = broken_projections(agent, home, store, rows)
         rows = [r for r in rows if r["name"] and r["revision"]]
         if not rows:
+            if projected or broken:
+                # Every crow skill here comes from Uniflow's store (updated as agent uniflow): only the guide,
+                # integrations and hooks of this CLI are refreshed.
+                from . import machine
+                entry = {"agent": agent, "target": target["path"], "updated": [], "unchanged": 0, "kept": list(broken), "error": None,
+                         "via_uniflow": projected}
+                if dry_run:
+                    entry["dry_run"] = True
+                try:
+                    if agent == "codex" and "crow-behaviour" in [k["name"] for k in broken]:
+                        reinstall_behaviour(home, entry, dry_run, trust)
+                    extras = machine.refresh_extras(agent, home, dry_run, trust)
+                    entry["guides"] = (extras.get("guides") or {}).get("transaction")
+                except CrowError as exc:
+                    entry["error"] = {"code": exc.code, "message": str(exc)}
+                except (OSError, ValueError, KeyError, TypeError):
+                    entry["error"] = {"code": "io_error", "message": "Falha de leitura/gravação; nada concluído para este agente."}
+                results.append(entry)
             continue
         records = store.state(target["path"])["installed"]
         names, kept = [], []
@@ -325,10 +422,30 @@ def skills_update(home):
                 kept.append({"name": r["name"], "status": "other_origin"})  # update --source or install switches it
             else:
                 names.append(r["name"])
-        entry = {"agent": agent, "target": target["path"], "updated": [], "unchanged": 0, "kept": kept, "error": None}
+        entry = {"agent": agent, "target": target["path"], "updated": [], "unchanged": 0, "kept": kept + list(broken),
+                 "error": None, "via_uniflow": projected}
+        if dry_run:
+            entry["dry_run"] = True
+        if agent == "codex":
+            names = codex_duplicates(home, store, entry, names, dry_run)
+            if "crow-behaviour" in [k["name"] for k in broken] and "crow-behaviour" not in [r["name"] for r in rows]:
+                try:
+                    reinstall_behaviour(home, entry, dry_run, trust)
+                except CrowError as exc:
+                    entry["error"] = {"code": exc.code, "message": str(exc)}
+            if not names and not entry.get("error"):
+                from . import machine
+                try:
+                    machine.refresh_extras(agent, home, dry_run, trust)
+                except CrowError as exc:
+                    entry["error"] = {"code": exc.code, "message": str(exc)}
         if names:
             try:
-                args = parser().parse_args(["update", *names, "--agents", agent, "--global", "--yes", "--json", "--home", str(home)])
+                argv = ["update", *names, "--agents", agent, "--global", "--dry-run" if dry_run else "--yes", "--json",
+                        "--home", str(home)]
+                if not trust:
+                    argv.append("--no-trust")
+                args = parser().parse_args(argv)
                 data = cli_run(args)
                 entry["updated"] = sorted({c["name"] for c in data["changes"] if c["action"] != "unchanged"})
                 entry["unchanged"] = sum(c["action"] == "unchanged" for c in data["changes"])
@@ -342,7 +459,21 @@ def skills_update(home):
     return results
 
 
-def run(store, home, self_step=True, skills_step=True):
+def preview(store, home, self_step=True, skills_step=True, trust=True, git_pull=None):
+    """Dry run shared by autoupdate run --dry-run and upgrade --dry-run: nothing runs, nothing is written."""
+    state = load_state(store)
+    install = detect()
+    result = {"install": install, "applied": False, "dry_run": True,
+              "would": ["atualizar o crow-skills" if self_step else None, "update --global das skills gerenciadas, por agente"]}
+    if self_step:
+        result["self"] = preview_self(install, state.get("git_pull") if git_pull is None else git_pull)
+    if skills_step:
+        result["skills"] = skills_update(home, trust=trust, dry_run=True)
+    return result
+
+
+def run(store, home, self_step=True, skills_step=True, trust=True, git_pull=None, trigger="autoupdate"):
+    """One run (scheduled autoupdate or crow-skills upgrade): self-upgrade, then every agent's update."""
     try:
         import fcntl
     except ImportError as exc:  # pragma: no cover
@@ -361,15 +492,18 @@ def run(store, home, self_step=True, skills_step=True):
             log.write_text("")
         state = load_state(store)
         install = detect()
-        result = {"startedAt": now(), "version": __version__, "install": {"kind": install["kind"]}}
+        result = {"startedAt": now(), "version": __version__, "install": {"kind": install["kind"]}, "trigger": trigger}
         handed_off = False
         if self_step:
-            result["self"] = self_upgrade(install, state.get("git_pull"))
+            result["self"] = self_upgrade(install, state.get("git_pull") if git_pull is None else git_pull)
             after = result["self"].get("after")
             if skills_step and after and after != __version__ and install["launcher"]:
                 # The new version updates the skills (its own snapshot is the new source).
                 try:
-                    done = subprocess.run([install["launcher"], "autoupdate", "run", "--skills-only", "--yes", "--json"],
+                    child_args = [install["launcher"], "autoupdate", "run", "--skills-only", "--yes", "--json"]
+                    if not trust:
+                        child_args.append("--no-trust")
+                    done = subprocess.run(child_args,
                                           capture_output=True, text=True, timeout=1200, stdin=subprocess.DEVNULL,
                                           env=dict(os.environ, CROW_SKILLS_AUTOUPDATE_CHILD="1"))
                     child = json.loads(done.stdout)
@@ -380,7 +514,7 @@ def run(store, home, self_step=True, skills_step=True):
                     result["handoff"] = {"version": after, "ok": False}
                     handed_off = True
         if skills_step and not handed_off:
-            result["skills"] = skills_update(home)
+            result["skills"] = skills_update(home, trust=trust)
         result["endedAt"] = now()
         result["ok"] = (result.get("self", {}).get("result") != "failed"
                         and all(not s.get("error") for s in result.get("skills", []))
@@ -388,7 +522,7 @@ def run(store, home, self_step=True, skills_step=True):
         state = load_state(store)
         state["lastRun"] = result
         history = state.get("history") or []
-        history.append({"startedAt": result["startedAt"], "ok": result["ok"],
+        history.append({"startedAt": result["startedAt"], "ok": result["ok"], "trigger": trigger,
                         "updated": sum(len(s.get("updated") or []) for s in result.get("skills", [])),
                         "self": (result.get("self") or {}).get("result")})
         state["history"] = history[-HISTORY:]