@acropole/skills 1.1.0 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,48 @@
1
+ # Paralelismo: subagentes, sessões e recursos compartilhados
2
+
3
+ ## Quando paralelizar
4
+
5
+ - **Pode** ir em paralelo: itens em pastas disjuntas (o `server/` de um app e o `angular/` de outro; libs diferentes;
6
+ documentação × código), validações independentes (a suíte de cada app), leitura/levantamento.
7
+ - **Não** vai em paralelo: dois agentes no mesmo arquivo, item que depende da saída de outro (o codegen do front precisa
8
+ do schema do GraphQL), qualquer coisa que mexa no mesmo `package.json`/lockfile ao mesmo tempo.
9
+ - Tarefa pequena e sequencial: faça você mesmo; subagente começa sem contexto e custa caro para reconstruí-lo.
10
+
11
+ ## Subagente (Agent/Task) — o prompt é tudo o que ele sabe
12
+
13
+ Inclua sempre:
14
+
15
+ 1. **Objetivo e escopo fechado**: repositório e pastas que pode tocar; o que **não** pode (outros repositórios, pastas
16
+ que o projeto não versiona, `.env` de verdade).
17
+ 2. **Contexto mínimo**: onde está a spec/plano, o domínio molde, as skills a seguir (nome), comandos de teste/venv.
18
+ 3. **Decisões já tomadas** (o subagente não deve reabrir) e **o que deixar para o usuário**.
19
+ 4. **Provas exigidas**: quais suítes rodar e que tudo passe; o que fazer se uma falha não for dele.
20
+ 5. **Proibições**: sem commit/push/publicação/bump; sem `git reset/stash/clean`; sem dado de teste em recurso real.
21
+ 6. **Formato do relatório**: arquivos alterados, decisões, números das suítes, o que não deu para fazer, riscos.
22
+
23
+ Rode em segundo plano quando houver outra coisa útil a fazer; não faça em paralelo o mesmo trabalho dele. Complemento do
24
+ usuário no meio do caminho: mande para o subagente (mensagem) em vez de recomeçar. O relatório dele é pista: confira os
25
+ pontos críticos (rode a suíte) antes de dar como feito.
26
+
27
+ ## Sessões paralelas (vários terminais/agentes no mesmo working tree)
28
+
29
+ - Cada sessão: `coord.sh register` → um item por vez (`claim`/`check`/`done`) → `unregister` ao sair.
30
+ - Reserva parada: `coord.sh stale [horas]`. Worker que morreu sem `unregister`: `coord.sh orphans --release` devolve os
31
+ itens dele (confira antes que a sessão realmente acabou).
32
+ - Trabalho entre repositórios: `COORD_ROOT=<pasta comum> COORD_TASKS=<lista>` em todas as sessões.
33
+
34
+ ## Recursos que travam (e como contornar sem derrubar o usuário)
35
+
36
+ | Recurso | Sintoma | O que fazer |
37
+ |---|---|---|
38
+ | Dev server (`ng serve`, `nodemon`, `uvicorn --reload`) rodando | `EBUSY`/`EPERM` no `npm install` (Windows trava `.node`/`sass-embedded`) | `npm install --package-lock-only` (lock e `package.json` certos, `node_modules` depois); avise para reiniciar |
39
+ | Dependência trocada com processo de pé | `uvicorn --reload` antigo + pacote novo = erro estranho (`'Config' object has no attribute ...`); `nodemon` compilou antes do install | reiniciar o processo (Ctrl+C e subir de novo); não é bug do código |
40
+ | Processo órfão (pai morreu) | porta ocupada, código antigo respondendo | listar processo + pai (PowerShell `Get-CimInstance Win32_Process`, `ps -o ppid`); encerrar só com o ok do usuário |
41
+ | Banco/Redis compartilhado | teste "falha" por dado ausente ou sujo | teste isolado com SQLite/Redis falso; teste que lê dado real é ambiental — diga isso |
42
+ | Git | dois agentes commitando | commit só por caminho, um repositório por vez, sem `add -A` cego |
43
+ | CPU | suítes em paralelo derrubam teste de tempo | rode o teste que falhou isolado antes de concluir |
44
+
45
+ ## Validação em lote (vários apps)
46
+
47
+ Dispare as suítes de cada app em paralelo (um processo por app, saída em arquivo), depois resuma em tabela
48
+ (app → testes/build → resultado). Falhou um: rode isolado, leia o erro, separe "quebrou com a mudança" de "ambiental".
@@ -0,0 +1,131 @@
1
+ #!/usr/bin/env bash
2
+ # Coordenação entre sessões/agentes (workers) que implementam os itens Txx de uma lista de tarefas do repositório.
3
+ #
4
+ # A trava é um DIRETÓRIO por item em <raiz>/.sdd/coord/claims/<Txx>: mkdir é atômico (falha se já existe), então dois
5
+ # workers nunca reservam o mesmo item, mesmo rodando ao mesmo tempo. A lista (docs/sdd/tasks.md) é só a visão legível;
6
+ # quem manda na reserva é .sdd/coord/ (estado local, fora do git).
7
+ #
8
+ # Raiz = repositório git da pasta atual (COORD_ROOT sobrescreve). Lista = COORD_TASKS (padrão docs/sdd/tasks.md).
9
+ #
10
+ # Uso (bash/Git Bash, de qualquer pasta do repositório):
11
+ # coord.sh init -> cria docs/sdd/tasks.md (do modelo) e põe .sdd/ no .gitignore
12
+ # coord.sh register -> reserva e imprime o próximo worker-N livre
13
+ # coord.sh claim <worker> <Txx> -> reserva o item (exit 1 se já tem dono)
14
+ # coord.sh check <worker> <Txx> -> confirma que o item é seu (exit 1 se não)
15
+ # coord.sh done <worker> <Txx> -> marca o item como concluído
16
+ # coord.sh release <worker> <Txx> -> devolve o item (desistiu/bloqueado)
17
+ # coord.sh unregister <worker> -> libera o nome do worker ao encerrar
18
+ # coord.sh status -> situação de todos os itens e workers
19
+ # coord.sh stale [horas] -> itens "em andamento" há mais de N horas (padrão 4) ou com dono não registrado
20
+ # coord.sh orphans --release -> devolve os itens em andamento cujo worker não está mais registrado
21
+ set -u
22
+ HERE="$(cd "$(dirname "$0")" && pwd)"
23
+ ROOT="${COORD_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
24
+ LIST="$ROOT/${COORD_TASKS:-docs/sdd/tasks.md}"
25
+ STATE="$ROOT/.sdd/coord"
26
+ CLAIMS="$STATE/claims"
27
+ WORKERS="$STATE/workers"
28
+
29
+ now() { date '+%Y-%m-%d %H:%M:%S'; }
30
+ epoch() { date -d "$1" +%s 2>/dev/null || date -j -f '%Y-%m-%d %H:%M:%S' "$1" +%s 2>/dev/null || echo 0; }
31
+ die() { echo "ERRO: $*" >&2; exit 1; }
32
+ need_list() { [ -f "$LIST" ] || die "não existe $LIST -- rode: coord.sh init"; }
33
+ task_exists() { grep -qE "\*\*$1\*\*" "$LIST"; }
34
+ owner_of() { cat "$CLAIMS/$1/owner" 2>/dev/null; }
35
+ state_of() { cat "$CLAIMS/$1/state" 2>/dev/null; }
36
+ valid_task() { [[ "$1" =~ ^T[0-9]{2,}$ ]] || die "item inválido: '$1' (formato Txx)"; }
37
+ need_owner() {
38
+ local o; o="$(owner_of "$2")"
39
+ [ -n "$o" ] || die "$2 não está reservado"
40
+ [ "$o" = "$1" ] || die "$2 pertence a $o, não a $1"
41
+ }
42
+ age_hours() { local s; s="$(epoch "$(cat "$1" 2>/dev/null)")"; [ "$s" -gt 0 ] && echo $(( ( $(date +%s) - s ) / 3600 )) || echo "?"; }
43
+
44
+ case "${1:-}" in
45
+ init)
46
+ mkdir -p "$(dirname "$LIST")"
47
+ if [ -f "$LIST" ]; then echo "já existe: $LIST"; else cp "$HERE/../templates/tasks.md" "$LIST" && echo "criado: $LIST"; fi
48
+ if ! grep -qxE '/?\.sdd/?' "$ROOT/.gitignore" 2>/dev/null; then
49
+ printf '\n# Estado local de coordenação entre agentes (coord.sh)\n.sdd/\n' >> "$ROOT/.gitignore"
50
+ echo ".sdd/ acrescentado ao .gitignore"
51
+ fi
52
+ ;;
53
+ register)
54
+ mkdir -p "$WORKERS"
55
+ n=1
56
+ while ! mkdir "$WORKERS/worker-$n" 2>/dev/null; do n=$((n+1)); done
57
+ now > "$WORKERS/worker-$n/since"
58
+ echo "worker-$n"
59
+ ;;
60
+ unregister)
61
+ [ -n "${2:-}" ] || die "uso: coord.sh unregister <worker>"
62
+ [ -d "$WORKERS/$2" ] || die "$2 não está registrado"
63
+ rm -rf "$WORKERS/$2" && echo "$2 liberado"
64
+ ;;
65
+ claim)
66
+ w="${2:-}"; t="${3:-}"
67
+ [ -n "$w" ] && [ -n "$t" ] || die "uso: coord.sh claim <worker> <Txx>"
68
+ valid_task "$t"; need_list
69
+ [ -d "$WORKERS/$w" ] || die "$w não está registrado (rode: coord.sh register)"
70
+ task_exists "$t" || die "$t não existe em $LIST"
71
+ mkdir -p "$CLAIMS"
72
+ if ! mkdir "$CLAIMS/$t" 2>/dev/null; then
73
+ die "$t já reservado por $(owner_of "$t") ($(state_of "$t"))"
74
+ fi
75
+ echo "$w" > "$CLAIMS/$t/owner"
76
+ echo "em andamento" > "$CLAIMS/$t/state"
77
+ now > "$CLAIMS/$t/since"
78
+ # Garantia de que ninguém sobrescreveu: relê o dono depois de gravar.
79
+ [ "$(owner_of "$t")" = "$w" ] || die "$t foi sobrescrito por $(owner_of "$t") -- NÃO implemente"
80
+ echo "OK: $t reservado para $w"
81
+ ;;
82
+ check)
83
+ valid_task "${3:-}"; need_owner "${2:-}" "${3:-}"
84
+ [ "$(state_of "$3")" = "em andamento" ] || die "$3 está '$(state_of "$3")'"
85
+ echo "OK: ${3} é de ${2}"
86
+ ;;
87
+ done)
88
+ valid_task "${3:-}"; need_owner "${2:-}" "${3:-}"
89
+ echo "concluído" > "$CLAIMS/$3/state"; now > "$CLAIMS/$3/finished"
90
+ echo "OK: $3 concluído por $2"
91
+ ;;
92
+ release)
93
+ valid_task "${3:-}"; need_owner "${2:-}" "${3:-}"
94
+ rm -rf "$CLAIMS/$3" && echo "OK: $3 devolvido"
95
+ ;;
96
+ status)
97
+ need_list
98
+ grep -oE '\*\*T[0-9]{2,}\*\*.{0,90}' "$LIST" | while IFS= read -r line; do
99
+ t="$(echo "$line" | grep -oE 'T[0-9]{2,}' | head -1)"
100
+ desc="$(echo "$line" | sed 's/\*\*//g')"
101
+ if [ -d "$CLAIMS/$t" ]; then
102
+ st="$(state_of "$t") · $(owner_of "$t")"
103
+ [ "$(state_of "$t")" = "em andamento" ] && st="$st · $(age_hours "$CLAIMS/$t/since")h"
104
+ else st="livre"; fi
105
+ printf '%-34s %s\n' "[$st]" "$desc"
106
+ done
107
+ echo; echo "workers registrados: $(ls "$WORKERS" 2>/dev/null | tr '\n' ' ')"
108
+ ;;
109
+ stale)
110
+ limit="${2:-4}"
111
+ for d in "$CLAIMS"/T*; do
112
+ [ -d "$d" ] || continue
113
+ t="$(basename "$d")"; [ "$(state_of "$t")" = "em andamento" ] || continue
114
+ o="$(owner_of "$t")"; h="$(age_hours "$d/since")"
115
+ if [ ! -d "$WORKERS/$o" ]; then echo "$t · $o · ${h}h · worker NÃO registrado (órfão)"
116
+ elif [ "$h" != "?" ] && [ "$h" -ge "$limit" ]; then echo "$t · $o · ${h}h · em andamento há mais de ${limit}h"; fi
117
+ done
118
+ ;;
119
+ orphans)
120
+ [ "${2:-}" = "--release" ] || die "uso: coord.sh orphans --release (devolve itens de workers não registrados)"
121
+ for d in "$CLAIMS"/T*; do
122
+ [ -d "$d" ] || continue
123
+ t="$(basename "$d")"; [ "$(state_of "$t")" = "em andamento" ] || continue
124
+ o="$(owner_of "$t")"
125
+ [ -d "$WORKERS/$o" ] || { rm -rf "$d"; echo "devolvido: $t (era de $o)"; }
126
+ done
127
+ ;;
128
+ *)
129
+ sed -n '2,22p' "$0"; exit 1
130
+ ;;
131
+ esac
@@ -0,0 +1,28 @@
1
+ -- NNN -- <tema> (AAAA-MM-DD): operações e permissões de <app> no Argos.
2
+ --
3
+ -- Migration para um banco do Argos que JÁ EXISTE, com o mesmo resultado das linhas novas no seed
4
+ -- (auth/operations.sql e auth/permissions.sql). Idempotente e só ACRESCENTA: pode rodar antes do deploy do app novo.
5
+ --
6
+ -- O sync do Orfeu cria as operações quando o app sobe e DESATIVA as que ele não declara mais -- mas não dá permissão.
7
+ -- Esta migration existe para: (1) a operação já existir com o id fixo da seed; (2) levar permissões de operação
8
+ -- renomeada para a nova (protected por grupo, e qualquer nível para token de API, x-api-token).
9
+
10
+ BEGIN;
11
+
12
+ -- 1. Operações (resolve por (app_id, identifier, method): se o sync já criou com id aleatório, só atualiza o nível)
13
+ INSERT INTO auth.operations (operation_id, app_id, identifier, method, level)
14
+ VALUES
15
+ ('<UUID fixo>', '<app_id>', '<dominio>:<recurso>:<acao>', '<read|write|delete|stream>', '<private|protected|optional|public>')
16
+ ON CONFLICT (app_id, identifier, method) DO UPDATE SET level = EXCLUDED.level, active = true;
17
+
18
+ -- 2. Permissões: copia de cada operação antiga para a nova equivalente (mesmo método), consumer por consumer
19
+ INSERT INTO auth.permissions (id, consumer_id, operation_id)
20
+ SELECT gen_random_uuid(), p.consumer_id, n.operation_id
21
+ FROM auth.permissions p
22
+ JOIN auth.operations o ON o.operation_id = p.operation_id
23
+ JOIN (VALUES ('<id antigo>', '<id novo>')) m(old_id, new_id) ON m.old_id = o.identifier
24
+ JOIN auth.operations n ON n.app_id = o.app_id AND n.identifier = m.new_id AND n.method = o.method
25
+ WHERE o.app_id = '<app_id>'
26
+ ON CONFLICT (consumer_id, operation_id) DO NOTHING;
27
+
28
+ COMMIT;
@@ -0,0 +1,45 @@
1
+ # <Tema> — plano (AAAA-MM-DD)
2
+
3
+ > Plano para um ou mais agentes. Spec: `docs/sdd/specs/<tema>.md`. Itens: `docs/sdd/tasks.md` (Txx). Cada agente lê
4
+ > este arquivo inteiro antes de reservar um item e escreve **só** na seção "Registro" do próprio item.
5
+
6
+ ## 1. Contexto e decisões já tomadas (não rediscutir)
7
+
8
+ - <decisão do usuário, com data e as palavras dele quando for restrição>
9
+
10
+ ## 2. Arquitetura alvo
11
+
12
+ <Domínios novos/alterados por camada. Copie a forma de um domínio existente deste repositório — não invente.>
13
+
14
+ ## 3. Mapa de nomes (fonte única — use exatamente estes)
15
+
16
+ | Domínio | server (`domains/`) | GraphQL / Angular | Prefixo das operações no Orfeu |
17
+ |---|---|---|---|
18
+ | <...> | `<snake_case>` | `<kebab-case>` | `<kebab-case>:` |
19
+
20
+ ## 4. Fases e itens
21
+
22
+ | Fase | Itens | Depende de | Pode ir em paralelo? |
23
+ |---|---|---|---|
24
+ | F0 | T01 | — | — |
25
+
26
+ ## 5. Convivência entre agentes
27
+
28
+ - Reserva pelo `coord.sh` (skill orquestracao); um item por vez por agente.
29
+ - Arquivos compartilhados entre itens (só quem tem o item mexe): <lista>.
30
+ - Recursos de execução (servidor local, Redis, banco, navegador de teste, codegen, git): <como reservar>.
31
+
32
+ ## 6. Itens
33
+
34
+ ### T01 · <título>
35
+ - O quê: <...>
36
+ - Arquivos: <...>
37
+ - Pronto quando: <provas — testes, typecheck, build, codegen>
38
+
39
+ ## 7. Riscos conhecidos
40
+
41
+ - <...>
42
+
43
+ ## 8. Registro (cada agente escreve só na seção do seu item)
44
+
45
+ ### T01
@@ -0,0 +1,54 @@
1
+ # <App> — <tema> (spec, AAAA-MM-DD)
2
+
3
+ ## Objetivo
4
+
5
+ <Uma ou duas frases: o problema e o resultado esperado para quem usa.>
6
+
7
+ ## Comportamento
8
+
9
+ - <O que o usuário vê e faz, passo a passo. Estados vazio, carregando e erro (com "Tentar novamente").>
10
+
11
+ ## Contrato
12
+
13
+ ### server (`server/src/app/domains/<domínio>/`)
14
+
15
+ | Método e caminho | Entrada | `data` | Operação (id · nível) | Mensagem de sucesso | Erros (status · frase) |
16
+ |---|---|---|---|---|---|
17
+ | `GET /<domínio>/...` | query: ... | `[...]` | `<domínio>:...:list` · private | — | 404 · "..." |
18
+ | `POST /<domínio>/...` | corpo: ... | `{...}` | `<domínio>:...:create` · protected | "... criado." | 409 · "Já existe ..." |
19
+
20
+ Regras de negócio: <validações, quem pode o quê, efeitos colaterais, integrações externas>.
21
+
22
+ ### GraphQL (`graphql/src/web/<domínio>/`)
23
+
24
+ | Campo | Argumentos | Retorno | Operação (nível) |
25
+ |---|---|---|---|
26
+ | `query <campo>` | ... | `<Tipo>Response` (envelope) | private |
27
+ | `subscription <campo>` | — | `<Tipo>` (sem envelope) — canal Redis `<app>:<canal>` | private |
28
+
29
+ ### Angular (`angular/src/app/features/<domínio>/`)
30
+
31
+ - Tela: <nome> — `router_id` <existente | novo no Argos, liberado para os grupos>.
32
+ - Ações e toasts: <ação> → toast com a mensagem do servidor; <polling/lote> silenciado.
33
+
34
+ ## Dados
35
+
36
+ - Tabelas/colunas: <...> — `database/scripts/create/`, e migration se o banco já existe.
37
+
38
+ ## Argos
39
+
40
+ - Operações novas/renomeadas: <ids>. `protected` → grupos: <...>. Token de API → permissão em qualquer nível.
41
+ - Tela nova: rota + roteador do client, **liberado** para os grupos.
42
+
43
+ ## Fora do escopo
44
+
45
+ - <...>
46
+
47
+ ## Restrições
48
+
49
+ - <O que não pode ser tocado/testado (equipamento real, banco compartilhado, backups...).>
50
+
51
+ ## Critérios de aceite
52
+
53
+ - [ ] <verificável: teste, typecheck, build, comportamento no navegador>
54
+ - [ ] Uma ação = um toast; nenhum toast em polling.
@@ -0,0 +1,21 @@
1
+ # Itens de trabalho
2
+
3
+ Fila de itens das mudanças planejadas com a skill `orquestracao`. Quem manda na reserva é o `coord.sh` da skill
4
+ (travas em `.sdd/coord/`, fora do git), não este arquivo.
5
+
6
+ ## Protocolo dos workers
7
+
8
+ 1. `coord.sh register` → `worker-N` (diga ao usuário qual é o seu).
9
+ 2. `coord.sh status` → escolha um item livre respeitando as dependências do plano.
10
+ 3. `coord.sh claim worker-N Txx` e depois `coord.sh check worker-N Txx` (tem que responder `OK`) — só então implemente.
11
+ 4. Ao terminar: `coord.sh done worker-N Txx` e marque `[x]` na linha do item. Bloqueado: `coord.sh release worker-N Txx`.
12
+ 5. Ao encerrar a sessão: `coord.sh unregister worker-N`.
13
+
14
+ Todos os workers usam o mesmo working tree: nunca `git reset`, `git checkout -- .`, `git stash`, `git clean`; commit só
15
+ dos seus arquivos, por caminho, e só com pedido do usuário.
16
+
17
+ <!-- Formato: - [ ] **Txx** · <camada/domínio> — <alteração> (AAAA-MM-DD) -->
18
+
19
+ ## <Tema> (spec: docs/sdd/specs/<tema>.md)
20
+
21
+ - [ ] **T01** · <camada> — <alteração> (AAAA-MM-DD)
@@ -172,8 +172,8 @@ import { HERMES_THEME_CONFIG } from '@trismegisto/angular';
172
172
  `error`, `attention`, `done`, `locked`, `unlocked`, `forbidden`, `not-found`, `session-expired`; outro
173
173
  desenho vai no slot `[illustration]`. Vazio **dentro** de cartão/tabela é `hm-empty`; falha ao carregar é
174
174
  `hm-alert`.
175
- - **Ilustrações** são "adesivos": traço escuro e brancos **fixos**, iguais no claro e no escuro (no escuro
176
- ganham contorno claro). Só a cor acompanha o tema: roupa/objetos seguem a família (`--hm-accent`), o
175
+ - **Ilustrações** têm tinta e personagem **fixos**, iguais no claro e no escuro; no escuro, um contorno na cor
176
+ do texto (traço por baixo da silhueta) separa o desenho do fundo. Só a cor acompanha o tema: roupa/objetos seguem a família (`--hm-accent`), o
177
177
  símbolo-chave segue a cor de estado. Não recolora o traço por CSS. Os componentes de ilustração não saem
178
178
  da raiz (`@trismegisto/angular/illustration-error`…); prefira `hm-state-screen`/`hm-state-page`, que as
179
179
  carregam sob demanda.