@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 +2 -1
- package/bin/install.js +4 -3
- package/package.json +2 -2
- package/skills/acropole/SKILL.md +1 -0
- package/skills/orquestracao/SKILL.md +118 -0
- package/skills/orquestracao/references/paralelismo.md +48 -0
- package/skills/orquestracao/scripts/coord.sh +131 -0
- package/skills/orquestracao/templates/permissoes-argos.sql +28 -0
- package/skills/orquestracao/templates/plan.md +45 -0
- package/skills/orquestracao/templates/spec.md +54 -0
- package/skills/orquestracao/templates/tasks.md +21 -0
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} —
|
|
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.
|
|
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
|
}
|
package/skills/acropole/SKILL.md
CHANGED
|
@@ -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)
|