@andespindola/crow-skills 0.3.0 → 0.4.0

package/README.md

@@ -2,6 +2,8 @@
 
 Skills com escopo explícito, conhecimento especializado preservado e fluxos comuns reutilizáveis.
 
+**Versão 0.4.0** ([mudanças](CHANGELOG.md)): crow-behaviour com paridade de orquestração, ledger de progresso, `crow-skills progress` e integrações de interface por agente.
+
 **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
@@ -12,7 +14,7 @@ Skills com escopo explícito, conhecimento especializado preservado e fluxos com
 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).
+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. Em tarefa substantiva ela mantém um ledger de progresso (`.crow/runs/`), mostra um resumo por fase no chat e, dentro do tmux, um painel ao vivo com `crow-skills progress --watch`. 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.
@@ -25,9 +27,11 @@ Exemplos:
 
 ## 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. 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.
+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. 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 line do Claude Code e do Codex, segmento tmux) seguem o mesmo fluxo, preservando a configuração existente; `--no-integrations` desliga.
 
 ```sh
+npm install -g @andespindola/crow-skills@0.4.0
+crow-skills progress
 ./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
@@ -36,7 +40,7 @@ O pacote de cada skill é somente sua pasta em `skills/`. O [CLI crow-skills](do
 
 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.
+Os nomes têm prefixo `crow-` para coexistir com o catálogo anterior. Não há instalação global automática nem auto-update; em `--global`, a única reconfiguração de agentes é o guia aditivo e as integrações de interface, ambos desligáveis (`--no-guide`, `--no-integrations`). 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.
 

package/crow_skills/__init__.py

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

package/crow_skills/cli.py

@@ -7,12 +7,14 @@ import sys
 
 from . import __version__
 from . import guide
+from . import integrations
+from . import progress
 from .agents import AGENTS, destinations, inventory
 from .source import CrowError, Source, valid_name
 from .storage import Store, checked
 
 DEFAULT_SOURCE = Path(__file__).resolve().parents[1]
-MUTATIONS = {"install", "update", "uninstall", "rollback", "recover", "guide"}
+MUTATIONS = {"install", "update", "uninstall", "rollback", "recover", "guide", "integrations"}
 
 
 class Parser(argparse.ArgumentParser):
@@ -54,10 +56,18 @@ def parser():
             child.add_argument("--with-handoffs", action="store_true", help="Incluir apenas handoffs diretos opcionais do catálogo")
         child.add_argument("--overwrite-modified", action="store_true", help="Autorizar backup e substituição/remoção de edições locais")
         child.add_argument("--no-guide", action="store_true", help="Não aplicar/atualizar/remover o guia do agente (--global)")
+        child.add_argument("--no-integrations", action="store_true",
+                           help="Não aplicar/remover as integrações de interface (status line, tmux) em --global")
     child = sub.add_parser("guide", parents=[common], help="Instruções gerenciadas para o agente usar as skills instaladas")
     child.add_argument("action", choices=("install", "status", "uninstall"))
     child.add_argument("--replace", action="store_true", help="Autorizar backup e substituição de conteúdo não gerenciado no caminho do guia")
     child.add_argument("--overwrite-modified", action="store_true", help="Autorizar backup e substituição/remoção de guia editado")
+    child = sub.add_parser("integrations", parents=[common], help="Status line/tmux que mostram a execução crow-behaviour ativa")
+    child.add_argument("action", choices=("install", "status", "uninstall"))
+    child = sub.add_parser("progress", parents=[common], help="Painel de progresso da execução crow-behaviour (ledger, barras, tokens)")
+    child.add_argument("--watch", action="store_true", help="Redesenhar até a execução terminar ou Ctrl-C")
+    child.add_argument("--run", help="ID da execução; padrão: a ativa mais recente do diretório")
+    child.add_argument("--cwd", help="Diretório da execução; padrão: o atual")
     for name in ("rollback", "recover"):
         child = sub.add_parser(name, parents=[common])
         child.add_argument("--transaction", required=name == "rollback")
@@ -228,6 +238,84 @@ def apply_chain(store, plan, gplan, home):
         raise
 
 
+def behaviour_agents(home, store, plan=None):
+    """Agents with a verified guide mechanism that have crow-behaviour after the plan applies."""
+    touched = {}
+    for item in (plan or {}).get("items", []):
+        added, removed = touched.setdefault(os.path.abspath(item["target"]), (set(), set()))
+        (removed if item["new"] is None else added).add(item["name"])
+    result = []
+    for agent in guide.MECHANISMS:
+        path = os.path.abspath(destinations(agent, home)[0]["path"])
+        added, removed = touched.get(path, (set(), set()))
+        if "crow-behaviour" in (set(guide.managed_skills(agent, home, store)) | added) - removed:
+            result.append(agent)
+    return result
+
+
+def integrations_preview(args, home, store, plan):
+    """Integrations follow the skills in --global unless --no-integrations ("disabled" otherwise)."""
+    if getattr(args, "no_integrations", False):
+        return {"changes": [], "skipped": [{"integration": "*", "reason": "--no-integrations: integrações não alteradas."}], "disabled": True}
+    if getattr(args, "project", None) or getattr(args, "dest", None):
+        return {"changes": [], "skipped": [{"integration": "*", "reason": "Integrações de interface só existem no escopo do usuário (--global)."}],
+                "disabled": True}
+    return integrations.sync(store, home, integration_agents(args, home, store, plan), dry_run=True)
+
+
+def integration_agents(args, home, store, plan=None, selected=None):
+    """Agents whose integrations should exist: crow-behaviour present and either selected now
+    or already integrated (like the guide, a shared-root install does not opt codex in)."""
+    if selected is None:
+        selected = [a for t in destinations(getattr(args, "agents", None), home) for a in t["agents"]] if getattr(args, "agents", None) else []
+    try:
+        owners = {a for name in integrations.load_state(store)["integrations"] for a in integrations.OWNERS.get(name, ())}
+    except CrowError:
+        owners = set()
+    return [a for a in behaviour_agents(home, store, plan) if a in selected or a in owners]
+
+
+def integrations_command(args, home, store, interactive):
+    if args.action == "status":
+        return {"integrations": integrations.status(store, home)}
+    if not getattr(args, "global_scope", False):
+        raise CrowError("usage", "integrations " + args.action + " exige --global explícito (único escopo suportado).")
+    wanted = []
+    if args.action == "install":
+        wanted = integration_agents(args, home, store) if getattr(args, "agents", None) else behaviour_agents(home, store)
+    if args.action == "install" and not wanted:
+        raise CrowError("guide_requires_skill", "crow-behaviour não está instalada para nenhum agente; instale antes: "
+                        "crow-skills install crow-behaviour --agents claude --global --yes")
+    preview = integrations.sync(store, home, wanted, dry_run=True)
+    if preview["changes"]:
+        authorize(args, interactive, preview)
+    if getattr(args, "dry_run", False):
+        return {**preview, "applied": False}
+    return {**integrations.sync(store, home, wanted), "applied": True}
+
+
+def progress_command(args, home):
+    cwd = getattr(args, "cwd", None) or os.getcwd()
+    if args.watch:
+        if getattr(args, "json", False):
+            raise CrowError("usage", "--watch não combina com --json.")
+        progress.watch(cwd, home, args.run)
+        return None
+    run, usage = progress.snapshot(cwd, home, args.run)
+    data = progress.as_json(run, usage)
+    data["text"] = progress.render(run, usage, color=False, unicode=progress.unicode_ok()) if run else None
+    return data
+
+
+def resync_integrations(home, store):
+    """After rollback/recover, drop integrations whose agents no longer have crow-behaviour."""
+    try:
+        if integrations.load_state(store)["integrations"]:
+            integrations.sync(store, home, integration_agents(None, home, store, selected=[]))
+    except CrowError:
+        pass  # Reported by status/doctor; never turns a completed rollback into a failure.
+
+
 def linked_guides(store, txid):
     """Committed guide transactions that completed the given skills transaction."""
     return [t["id"] for t in store.transactions() if t.get("kind") == "guide" and t.get("linked") == txid and t["phase"] == "committed"]
@@ -247,6 +335,10 @@ def run(args):
         return {"agents": inventory(home), "note": "Detecção por PATH/diretórios não comprova carregamento da skill."}
     if args.command == "guide":
         return guide_command(args, home, store, interactive)
+    if args.command == "integrations":
+        return integrations_command(args, home, store, interactive)
+    if args.command == "progress":
+        return progress_command(args, home)
     if args.command in ("status", "doctor"):
         targets = scope(args, home, read=True)
         rows = store.status(targets)
@@ -254,7 +346,11 @@ def run(args):
         global_view = not (getattr(args, "project", None) or getattr(args, "dest", None))
         names = [n.strip() for n in getattr(args, "agents", "").split(",")] if getattr(args, "agents", None) else list(guide.MECHANISMS)
         guides = guide.status(store, home, names) if global_view else []
-        result = {"installations": rows, "guides": guides, "pending_transactions": pending,
+        try:
+            ui = integrations.status(store, home) if global_view else []
+        except CrowError as exc:
+            ui = [{"integration": "*", "status": "unsafe", "note": str(exc)}]
+        result = {"installations": rows, "guides": guides, "integrations": ui, "pending_transactions": pending,
                   "activation_verified": False, "reload_hint": "Peça ao host para recarregar/listar skills; reinicie a sessão se necessário."}
         if args.command == "doctor":
             result.update(healthy=not pending and all(r["status"] not in ("modified", "missing", "unsafe") for r in rows + guides),
@@ -290,6 +386,7 @@ def run(args):
                 store.rollback(txid, recovery=args.command == "recover")
             for txid in follow:
                 store.rollback(txid)
+            resync_integrations(home, store)
         return {**summary, "dry_run": getattr(args, "dry_run", False), "applied": not getattr(args, "dry_run", False)}
     source = None
     if args.command != "uninstall":
@@ -328,14 +425,22 @@ def run(args):
             names.extend(n for n in source.catalog[name]["next"] if n not in names)
     plan = store.plan(args.command, names, targets, source, getattr(args, "replace", False), args.overwrite_modified)
     guides, gplan = guide_sync(args, home, store, args.command, targets, plan, source)
+    ui = integrations_preview(args, home, store, plan)
     summary = {"changes": plan["changes"], "revision": source.revision if source else None,
                "relationships": {n: source.related(n) for n in names} if source else {},
-               "guides": guides, "handoffs_are_optional": True, "activation_verified": False}
-    if plan["items"] or (gplan and gplan["items"]):
+               "guides": guides, "integrations": ui, "handoffs_are_optional": True, "activation_verified": False}
+    if plan["items"] or (gplan and gplan["items"]) or ui.get("changes"):
         authorize(args, interactive, summary)
     txid = None
     if not getattr(args, "dry_run", False):
         txid, guides["transaction"] = apply_chain(store, plan, gplan, home)
+        if not ui.get("disabled"):
+            # Best effort after the skills/guide transactions; a refusal is reported, never undoes them.
+            try:
+                summary["integrations"] = integrations.sync(store, home, integration_agents(args, home, store))
+            except (CrowError, OSError) as exc:
+                summary["integrations"] = {"changes": [], "skipped": [{"integration": "*", "reason": "Integrações não aplicadas (" +
+                                                                       (str(exc) or "falha de gravação") + "); skills e guia mantidos."}]}
     return {**summary, "transaction": txid, "dry_run": getattr(args, "dry_run", False),
             "applied": not getattr(args, "dry_run", False),
             "reload_hint": ("Somente preview; nada instalado." if getattr(args, "dry_run", False) else
@@ -346,6 +451,9 @@ def emit(command, data, machine):
     envelope = {"schema_version": 1, "ok": True, "command": command, "data": data}
     if machine:
         print(json.dumps(envelope, ensure_ascii=False, separators=(",", ":")))
+    elif command == "progress":
+        if data is not None:
+            print(data["text"] or "crow: nenhuma execução registrada neste diretório.")
     elif command == "list":
         print("Fonte: " + data["revision"])
         for item in data["skills"]: