@acropole/skills 1.1.0 → 1.2.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.
package/README.md CHANGED
@@ -5,7 +5,7 @@ cobrindo a stack da plataforma: apps Angular com o design system Trismegisto, ga
5
5
  e servidores Express em Node, serviços FastAPI em Python, autorização/auditoria com o SDK Orfeu,
6
6
  Dockerfiles e deploy pelo Hefesto.
7
7
 
8
- Cada skill cobre uma parte da stack e elas se complementam: numa tela Angular entram `angular`,
8
+ Cada skill cobre uma parte da stack e elas se complementam (a `orquestracao` encadeia todas numa mudança grande): numa tela Angular entram `angular`,
9
9
  `trismegisto` e `orfeu`; num resolver GraphQL, `apollo`, `express` e `orfeu`; no deploy, `docker` e
10
10
  `hefesto`; ao mexer numa tela, `documentacao` mantém o manual dela em dia. A skill `acropole` é a porta de entrada: descobre a stack e encadeia as outras.
11
11
 
@@ -22,6 +22,7 @@ Cada skill cobre uma parte da stack e elas se complementam: numa tela Angular en
22
22
  | `fastapi` | Serviços Python com FastAPI: domínios, settings, SQLAlchemy, envelope, pytest | "adiciona o domínio de faturas no serviço Python" |
23
23
  | `docker` | Dockerfile e `.dockerignore` (Angular estático, Node, Python): multi-stage, CMD exec, não-root, healthcheck | "escreve o Dockerfile desse serviço", "o container demora a parar" |
24
24
  | `hefesto` | Deploy pela plataforma Hefesto: aplicação, ambientes, variáveis, deploy/redeploy, rollback, diagnóstico | "prepara esse app para subir no Hefesto", "o deploy falhou" |
25
+ | `orquestracao` | Mudança grande do pedido à entrega (spec → plano em itens Txx → execução por vários agentes/sessões com reserva atômica via `coord.sh` → provas → Argos → fechamento) e como paralelizar com subagentes | "faz a spec e o plano", "paraleliza entre agentes", "distribui esses itens" |
25
26
  | `documentacao` | Manual das telas Angular: `README.md`/`ESPECIFICACAO.md` ligados no `document` da rota, loader `.md`, revisão da doc a cada mudança da tela (registro de revisão em `.documentacao.json`) | "documenta a tela de pedidos", "a doc dessa tela ainda vale?" |
26
27
 
27
28
  ## Subagentes revisores
package/bin/install.js CHANGED
@@ -127,10 +127,11 @@ function compareVersions(a, b) {
127
127
  for (let i = 0; i < 3; i++) if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) < (pb[i] || 0) ? -1 : 1;
128
128
  return 0;
129
129
  }
130
- function describe(installed) {
130
+ function describe(installed, feminino = true) {
131
+ const defasado = feminino ? 'defasada' : 'defasado';
131
132
  if (!installed) return 'versão desconhecida';
132
133
  const c = compareVersions(installed, version);
133
- if (c < 0) return `${installed} — defasada (este pacote é ${version}; atualize com npx ${name}@latest)`;
134
+ if (c < 0) return `${installed} — ${defasado} (este pacote é ${version}; atualize com npx ${name}@latest)`;
134
135
  if (c > 0) return `${installed} — mais nova que este pacote (${version})`;
135
136
  return `${installed} — em dia`;
136
137
  }
@@ -160,7 +161,7 @@ if (has('--status')) {
160
161
  else {
161
162
  const v = mark ? mark.version : '';
162
163
  if (v && compareVersions(v, version) < 0) outdated++;
163
- console.log(` ${a}: ${describe(v)}`);
164
+ console.log(` ${a}: ${describe(v, false)}`);
164
165
  }
165
166
  }
166
167
  const orphans = manifest.agents.filter((a) => !availableAgents.includes(a) && fs.existsSync(agentFile(a)));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@acropole/skills",
3
- "version": "1.1.0",
3
+ "version": "1.2.0",
4
4
  "description": "Skills e revisores para Claude Code: Angular, Apollo, Express, FastAPI, Trismegisto, Orfeu, Docker, deploy no Hefesto e documentação das telas. Instale com: npx @acropole/skills",
5
5
  "bin": { "acropole-skills": "bin/install.js" },
6
6
  "files": ["bin", "skills", "agents"],
@@ -11,7 +11,7 @@
11
11
  "scripts": {
12
12
  "bump": "node scripts/bump.mjs",
13
13
  "sync": "node scripts/sync-generated.mjs",
14
- "test": "node --test test/install.test.mjs test/integridade.test.mjs"
14
+ "test": "node --test test/install.test.mjs test/integridade.test.mjs test/coord.test.mjs"
15
15
  },
16
16
  "publishConfig": { "access": "public" }
17
17
  }
@@ -47,6 +47,7 @@ acima e pergunte.
47
47
 
48
48
  | No pedido aparece… | Skills, nesta ordem |
49
49
  | --- | --- |
50
+ | mudança grande (várias camadas/apps), spec, plano, "paraleliza", itens Txx para vários agentes | orquestracao (+ as skills de cada camada) |
50
51
  | app novo, estrutura do projeto, "segue o padrão?", pastas/portas/ambientes, divergência entre apps | `references/arquitetura.md` (+ o fluxo `app-novo` para criar) |
51
52
  | tela, página, listagem, formulário, modal, menu, rota do app | angular → trismegisto → orfeu → documentacao |
52
53
  | manual/README da tela, documentação desatualizada, `ESPECIFICACAO.md` | documentacao |
@@ -0,0 +1,118 @@
1
+ ---
2
+ name: orquestracao
3
+ description: Orquestra uma mudança grande do pedido à entrega no estilo spec-driven — especificação do contrato nas camadas (server, GraphQL, Angular, banco, Argos), plano em itens Txx, execução por vários agentes/sessões em paralelo com reserva atômica de itens (scripts/coord.sh), verificação com provas e fechamento. Use quando o pedido atravessa mais de uma camada ou mais de um app, quando for dividir trabalho entre subagentes ou sessões paralelas, quando o usuário pedir "spec", "plano", "SDD", "paraleliza", "orquestra", ou quando houver uma lista de itens Txx a distribuir entre workers.
4
+ ---
5
+
6
+ # orquestracao
7
+
8
+ Leva uma mudança grande do pedido à entrega, com vários agentes trabalhando ao mesmo tempo sem pisar um no outro.
9
+ Esta skill diz **o que fazer, em que ordem e como dividir**; o **como** de cada camada está nas skills da stack
10
+ (`angular`, `trismegisto`, `apollo`, `express`, `fastapi`, `orfeu`, `docker`, `hefesto`, `documentacao`) e o desenho
11
+ do app inteiro na skill `acropole` (`references/arquitetura.md`). Carregue a skill da camada antes de mexer nela.
12
+
13
+ Responda em português. Pergunte só o que é decisão do usuário (escopo, nível de acesso, regra de negócio, apagar algo);
14
+ o resto resolva com o padrão e diga o que escolheu.
15
+
16
+ ## Ordem de dependência de uma mudança
17
+
18
+ ```
19
+ server/ (regra, banco, envelope, @operation) → graphql/ (repasse, operation()) → angular/ (tela, service, toast)
20
+ ↘ database/ (schema, seed, migration) Argos (operações, permissões, rotas) ↙
21
+ ```
22
+
23
+ ## Onde fica cada coisa (no repositório do app)
24
+
25
+ | O quê | Onde | Git |
26
+ |---|---|---|
27
+ | Itens de trabalho (Txx) e protocolo dos workers | `docs/sdd/tasks.md` (de `templates/tasks.md`) | versionado |
28
+ | Pendências e decisões em aberto | `docs/sdd/pending.md` | versionado |
29
+ | Specs | `docs/sdd/specs/<tema>.md` (de `templates/spec.md`) | versionado |
30
+ | Planos para vários agentes | `docs/sdd/plans/<tema>.md` (de `templates/plan.md`) | versionado |
31
+ | Travas de coordenação | `.sdd/coord/` (criado pelo `coord.sh`) | **fora do git** |
32
+
33
+ `coord.sh` = `bash <pasta desta skill>/scripts/coord.sh` (instalada: `~/.claude/skills/orquestracao/scripts/coord.sh`,
34
+ ou `./.claude/skills/...` com `--project`). Ele acha a raiz pelo git da pasta atual; `coord.sh init` cria a lista e põe
35
+ `.sdd/` no `.gitignore`. Trabalho que atravessa vários repositórios: uma lista por repositório, ou `COORD_ROOT` apontando
36
+ para uma pasta comum (e `COORD_TASKS` para a lista).
37
+
38
+ ## Fase 0 — Contexto (antes de qualquer arquivo)
39
+
40
+ 1. README/`CLAUDE.md` do repositório e das pastas que vai tocar.
41
+ 2. `docs/sdd/pending.md` e `docs/sdd/tasks.md`: o pedido pode já estar descrito ou bloqueado por uma decisão.
42
+ 3. Trabalho em andamento: `coord.sh status` (e `coord.sh stale` para reserva parada/órfã). Não mexa em
43
+ arquivo/recurso reservado por outro worker.
44
+ 4. O domínio mais parecido já existente nas camadas: ele é o molde.
45
+ 5. `git status` de cada repositório envolvido: mudança pendente que não é sua não entra no seu commit.
46
+
47
+ ## Fase 1 — Especificação (o quê)
48
+
49
+ `docs/sdd/specs/<tema>.md` a partir de `templates/spec.md`. Define o **contrato**, não o código: comportamento
50
+ observável; rotas do server (método, caminho, entrada, `data`, operação e nível, mensagens e erros); campos do GraphQL e
51
+ canais; telas, ações e toasts do Angular (`router_id` se tela nova); dados; Argos (operações, níveis, grupos, tokens,
52
+ rotas liberadas); fora do escopo, restrições e critérios de aceite verificáveis. Um nome por domínio nas camadas
53
+ (`pedidos` / `pedidos` / `pedidos:*`). Mostre ao usuário quando houver decisão dele dentro; senão siga.
54
+
55
+ ## Fase 2 — Plano (como, em itens)
56
+
57
+ - Itens `Txx` (próximo número livre) em `docs/sdd/tasks.md`: `- [ ] **Txx** · <camada/domínio> — <alteração> (data)`.
58
+ **Um item = uma entrega verificável**, de preferência uma camada de um domínio (ou um app, numa mudança entre apps).
59
+ - Ordem: server → GraphQL → Angular → banco/Argos → fechamento. Itens de pastas **disjuntas** podem ir em paralelo.
60
+ - Trabalho para vários agentes: `docs/sdd/plans/<tema>.md` (de `templates/plan.md`) com decisões tomadas, mapa de
61
+ nomes, dependências, arquivos compartilhados e uma seção "Registro" por item.
62
+
63
+ ## Fase 3 — Execução (um ou vários workers)
64
+
65
+ Para cada item:
66
+
67
+ 1. Reservar: `coord.sh register` (uma vez por sessão) → `coord.sh claim <worker> Txx` → `coord.sh check <worker> Txx`
68
+ responde `OK` → só então implementar.
69
+ 2. Implementar seguindo a skill da camada.
70
+ 3. Provas da camada (Fase 4) passando.
71
+ 4. Registrar no plano (seção do item) ou na resposta: o que mudou, provas, o que ficou para o usuário.
72
+ 5. `coord.sh done <worker> Txx` e `[x]` na linha. Bloqueado: `coord.sh release`. Ao encerrar: `coord.sh unregister`.
73
+
74
+ Como dividir entre subagentes/sessões, o que vai no prompt de cada um e os recursos que travam (dev server segurando
75
+ `node_modules`, banco e Redis compartilhados, git): [references/paralelismo.md](references/paralelismo.md).
76
+
77
+ ## Fase 4 — Verificação (provas, não impressão)
78
+
79
+ | Camada | Prova |
80
+ |---|---|
81
+ | server | `pytest` inteiro (ambiente recriado do zero se mudou dependência) |
82
+ | GraphQL | `tsc --noEmit`, `vitest`, `build`; todo campo com `operation()` |
83
+ | Angular | codegen sem erro, `ng test`, `ng build`, `lint:a11y` |
84
+ | banco | `python build.py` e a suíte da pasta (PGlite) |
85
+ | ponta a ponta | serviços locais de pé com o código novo; o usuário valida no navegador |
86
+
87
+ Relate falha como falha, com a saída. Teste que depende de dado/ambiente externo (Redis real, equipamento): diga qual e
88
+ por quê; rode-o isolado antes de concluir que a mudança quebrou algo (carga de várias suítes em paralelo derruba teste de
89
+ tempo).
90
+
91
+ ## Fase 5 — Argos (permissões e telas)
92
+
93
+ - O sync do Orfeu cria as operações novas e **desativa** as que o app não declara mais; **não dá permissão**.
94
+ `protected` precisa de permissão por grupo; **token de API (`x-api-token`) precisa de permissão em qualquer nível**;
95
+ operação renomeada perde as permissões da antiga (`templates/permissoes-argos.sql` leva para a nova).
96
+ - Tela nova: rota e roteador do client **e** a liberação do roteador para os grupos (sem ela o menu vem vazio);
97
+ `router_id` no `features.routes.ts`. Client novo: redirect URIs (inclusive `localhost`) e acesso dos grupos.
98
+ - Banco de produção: só leitura. Quem aplica migration é o usuário, no deploy.
99
+
100
+ ## Fase 6 — Fechamento
101
+
102
+ - `docs/sdd/pending.md`: apague o resolvido; registre o que ficou (decisões do usuário, dívidas) com **o quê / onde /
103
+ o que falta**.
104
+ - README/`CLAUDE.md` que mudaram de verdade; variáveis de ambiente novas (lista para o deploy).
105
+ - Relatório ao usuário: o que foi feito, provas (números), o que é dele (validar no navegador, Argos, deploy, commits).
106
+
107
+ ## Regras que não se quebram
108
+
109
+ - **Sem commit nem push** sem pedido explícito (vale só para aquele pedido). Commit, quando pedido: confira antes o
110
+ `git status` — mudança de outra pessoa ou pasta que o projeto não versiona por combinado não entra sem confirmação;
111
+ um commit por repositório, mensagem no padrão do repositório.
112
+ - Working tree compartilhado: nunca `git reset/stash/clean/checkout -- .`.
113
+ - Banco, Redis e serviços compartilhados não recebem dado de teste: SQLite em memória, Redis falso, mocks.
114
+ - Credencial nunca em código, log ou resposta; ao mexer em `.env`, não imprima valores. Segredo gerado para o usuário
115
+ vai para arquivo fora de qualquer repositório.
116
+ - Processo do usuário (dev server, Argos local) não se derruba sem pedir; diga qual processo e por quê.
117
+ - Mudança fora do escopo do item (outro repositório, desenho novo): proponha antes de fazer.
118
+ - Ações reais em servidores/containers (deploy, rollback, restart) não se testam contra ambiente real: mocks.
@@ -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)