@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.
- package/README.md +3 -1
- package/bin/install.js +4 -3
- package/package.json +4 -4
- package/skills/acropole/SKILL.md +2 -0
- package/skills/acropole/references/fluxos/tela-nova.md +1 -1
- package/skills/auto-servico/SKILL.md +153 -0
- package/skills/auto-servico/references/diagnostico.md +42 -0
- package/skills/auto-servico/references/roteiros.md +63 -0
- package/skills/auto-servico/references/tools.md +108 -0
- package/skills/orfeu/SKILL.md +1 -1
- 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/skills/trismegisto/SKILL.md +2 -2
- package/skills/trismegisto/references/angular-api.md +649 -505
- package/skills/trismegisto/references/angular-exports.md +530 -130
- package/skills/trismegisto/references/angular-types.md +1 -1
- package/skills/trismegisto/references/angular.md +18 -8
- package/skills/trismegisto/references/catalogo/icones.json +5 -0
- package/skills/trismegisto/references/catalogo/seletores.json +444 -31
- package/skills/trismegisto/references/catalogo/tokens.json +136 -16
- package/skills/trismegisto/references/spine-api.md +36 -38
- package/skills/trismegisto/references/spine.md +3 -2
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,8 @@ 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" |
|
|
26
|
+
| `auto-servico` | MCP do auto-serviço do Argos (argos-mcp): configurar um agente de IA (uma conexão por aplicação, `x-app-token`, escopos), roteiros das tools (tela, acesso, permissões) e diagnóstico | "configura o agente para usar o MCP do Argos", "publica a tela pelo MCP" |
|
|
25
27
|
| `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
28
|
|
|
27
29
|
## 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,17 +1,17 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@acropole/skills",
|
|
3
|
-
"version": "1.
|
|
4
|
-
"description": "Skills e revisores para Claude Code: Angular, Apollo, Express, FastAPI, Trismegisto, Orfeu, Docker, deploy no Hefesto
|
|
3
|
+
"version": "1.3.0",
|
|
4
|
+
"description": "Skills e revisores para Claude Code: Angular, Apollo, Express, FastAPI, Trismegisto, Orfeu, Docker, deploy no Hefesto, documentação das telas e o MCP do auto-serviço do Argos. Instale com: npx @acropole/skills",
|
|
5
5
|
"bin": { "acropole-skills": "bin/install.js" },
|
|
6
6
|
"files": ["bin", "skills", "agents"],
|
|
7
7
|
"engines": { "node": ">=18" },
|
|
8
8
|
"license": "MIT",
|
|
9
9
|
"repository": { "type": "git", "url": "git+https://github.com/xlucvvs/acropole.git" },
|
|
10
|
-
"keywords": ["claude", "claude-code", "skill", "skills", "angular", "apollo", "graphql", "express", "fastapi", "trismegisto", "orfeu", "docker", "hefesto", "deploy", "documentacao", "documentation", "markdown", "agents", "code-review"],
|
|
10
|
+
"keywords": ["claude", "claude-code", "skill", "skills", "angular", "apollo", "graphql", "express", "fastapi", "trismegisto", "orfeu", "docker", "hefesto", "deploy", "documentacao", "documentation", "markdown", "agents", "code-review", "mcp", "argos"],
|
|
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 |
|
|
@@ -58,6 +59,7 @@ acima e pergunte.
|
|
|
58
59
|
| auditoria, operação, `PUBLIC`, `traceparent`, chamada entre serviços | orfeu (+ a skill do serviço) |
|
|
59
60
|
| Dockerfile, imagem, container, `.dockerignore` | docker (+ express/fastapi/angular para a parte de deploy da stack) |
|
|
60
61
|
| deploy, publicar o serviço, Hefesto, ambiente | hefesto → docker |
|
|
62
|
+
| agente de IA no Argos, MCP do auto-serviço, `.mcp.json`/`x-app-token` para um agente, "publica a tela/dá acesso pelo MCP" | auto-servico |
|
|
61
63
|
| "revisa", "confere", antes de abrir PR | este fluxo `revisar` |
|
|
62
64
|
| versões desalinhadas, "não sobe", configuração estranha | este fluxo `doctor` |
|
|
63
65
|
|
|
@@ -9,7 +9,7 @@ schema.
|
|
|
9
9
|
|
|
10
10
|
| # | Passo | Skill | Onde |
|
|
11
11
|
| --- | --- | --- | --- |
|
|
12
|
-
| 1 | **Roteador no Argos**: cadastrar o roteador do client (com descrição), **liberá-lo para os grupos** que devem ver a tela (roteador privado sem liberação não aparece no menu) e anotar o `router_id`. É feito no painel do Argos pelo usuário — peça o id, não crie por código | angular | `SKILL.md` "Receita: tela nova", `references/features.md` |
|
|
12
|
+
| 1 | **Roteador no Argos**: cadastrar o roteador do client (com descrição), **liberá-lo para os grupos** que devem ver a tela (roteador privado sem liberação não aparece no menu) e anotar o `router_id`. É feito no painel do Argos pelo usuário — peça o id, não crie por código. Exceção: com a conexão MCP do auto-serviço **daquela aplicação** configurada, o agente pode criar rota, router e guard pelas tools, com confirmação do usuário (skill **auto-servico**, roteiro "Publicar uma tela nova") | angular / auto-servico | `SKILL.md` "Receita: tela nova", `references/features.md` |
|
|
13
13
|
| 2 | **Operação no backend** que a tela vai chamar (Query/Mutation ou rota REST), com operação do Orfeu, `Method` explícito, `Level` e auditoria. Se ainda não existe, rode antes o fluxo [endpoint-novo](endpoint-novo.md) | apollo / fastapi / express + orfeu | ver endpoint-novo |
|
|
14
14
|
| 3 | **Documento GraphQL** em `src/app/services/<dominio>/<dominio>.graphql` + `npm run codegen` com o GraphQL local de pé (gera `<dominio>.generated.ts`, commitado) | angular | `references/dados.md` |
|
|
15
15
|
| 4 | **Service** `providedIn: 'root'` com `injectGraphqlClient` + `unwrap`; erro vira estado da tela | angular | `SKILL.md` "Dados", `references/dados.md` |
|
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: auto-servico
|
|
3
|
+
description: MCP do auto-serviço do Argos (argos-mcp) — como configurar um agente de IA para administrar o auto-serviço de uma aplicação (rotas, roteamento/telas, grupos e membros, acesso às telas, aplicações backend e permissões por operação, auditoria) e como o agente deve usar as tools. Cada conexão usa um x-app-token pessoal preso a UMA aplicação, então é uma conexão MCP por aplicação. Use ao configurar o .mcp.json/`claude mcp add` para o Argos, ao escrever instruções (CLAUDE.md) para um agente que vai usar esse MCP, quando o pedido for publicar tela, dar acesso a alguém ou revisar permissões de uma aplicação com as tools do argos-mcp disponíveis, ou ao diagnosticar erro dessas tools. Não use para o código de uma tela (angular), para proteger endpoint (orfeu) nem para o painel central de administração do Argos.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# auto-servico
|
|
7
|
+
|
|
8
|
+
O **argos-mcp** é um servidor MCP (Streamable HTTP, `POST <host>/argos/mcp`) que deixa um agente de IA fazer, por
|
|
9
|
+
tools, o mesmo que o administrador de uma aplicação faz na tela de auto-serviço do Argos. Ele não tem banco: toda
|
|
10
|
+
tool vira uma chamada ao `/auto-service` do argos-admin com o token do próprio agente, então valem as mesmas regras
|
|
11
|
+
da tela (rota de template intocável, rota protegida, recurso de outra aplicação = 404, auditoria).
|
|
12
|
+
|
|
13
|
+
Skills relacionadas: **orfeu** (o `x-app-token` e a auditoria do lado dos serviços), **angular** (a tela que usa
|
|
14
|
+
o `router_id` criado aqui), **hefesto** (deploy do próprio argos-mcp).
|
|
15
|
+
|
|
16
|
+
## A regra que muda tudo: um token, uma aplicação
|
|
17
|
+
|
|
18
|
+
O agente se autentica com o **token de aplicação pessoal** (`x-app-token`, `argos_app_…`). O token é preso a:
|
|
19
|
+
|
|
20
|
+
- um **usuário** (as permissões são as dele, recalculadas a cada uso);
|
|
21
|
+
- uma **aplicação** (client): a aplicação em que a pessoa estava logada quando criou o token;
|
|
22
|
+
- um **nível** (badge) escolhido na criação. Para o MCP ele precisa ser **Administrador**.
|
|
23
|
+
|
|
24
|
+
O MCP administra **somente** a aplicação do token. Nenhuma tool recebe a aplicação como argumento; um
|
|
25
|
+
`client_id` mandado pelo agente é descartado. Consequência prática:
|
|
26
|
+
|
|
27
|
+
> **Uma conexão MCP por aplicação.** O nome da conexão diz qual aplicação ela administra, e a IA escolhe a
|
|
28
|
+
> aplicação escolhendo a conexão.
|
|
29
|
+
|
|
30
|
+
Não há "token para todas as aplicações". Isso é de propósito: limita o estrago de um token vazado ou de um
|
|
31
|
+
agente que confundiu a aplicação.
|
|
32
|
+
|
|
33
|
+
## Configurar o cliente
|
|
34
|
+
|
|
35
|
+
### 1. Criar um token por aplicação
|
|
36
|
+
|
|
37
|
+
Para cada aplicação, a pessoa (administradora dela):
|
|
38
|
+
|
|
39
|
+
1. entra **na aplicação** pelo login do Argos (o token herda a aplicação da sessão);
|
|
40
|
+
2. abre *Configurações › Tokens de aplicação*, escolhe o nível **Administrador**, um nome (ex.: `agente-ia`) e a
|
|
41
|
+
validade (até 365 dias);
|
|
42
|
+
3. copia o valor: ele aparece **uma vez só**.
|
|
43
|
+
|
|
44
|
+
O MCP não cria nem renova tokens (um `x-app-token` não pode gerenciar tokens). Revogar na mesma tela derruba o
|
|
45
|
+
agente em até ~1–2 min (cache da validação do token).
|
|
46
|
+
|
|
47
|
+
### 2. Uma conexão por aplicação, token em variável de ambiente
|
|
48
|
+
|
|
49
|
+
`.mcp.json` do projeto (Claude Code expande `${VAR}`; o token **nunca** vai para o arquivo nem para o git):
|
|
50
|
+
|
|
51
|
+
```json
|
|
52
|
+
{
|
|
53
|
+
"mcpServers": {
|
|
54
|
+
"argos-vendas": {
|
|
55
|
+
"type": "http",
|
|
56
|
+
"url": "https://<host>/argos/mcp",
|
|
57
|
+
"headers": { "x-app-token": "${ARGOS_TOKEN_VENDAS}" }
|
|
58
|
+
},
|
|
59
|
+
"argos-compras": {
|
|
60
|
+
"type": "http",
|
|
61
|
+
"url": "https://<host>/argos/mcp",
|
|
62
|
+
"headers": { "x-app-token": "${ARGOS_TOKEN_COMPRAS}" }
|
|
63
|
+
},
|
|
64
|
+
"argos-compras-leitura": {
|
|
65
|
+
"type": "http",
|
|
66
|
+
"url": "https://<host>/argos/mcp",
|
|
67
|
+
"headers": { "x-app-token": "${ARGOS_TOKEN_COMPRAS}", "x-mcp-scopes": "autoservice.*.read" }
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Pela linha de comando: `claude mcp add --transport http argos-vendas https://<host>/argos/mcp --header "x-app-token: $ARGOS_TOKEN_VENDAS"`
|
|
74
|
+
(com `--scope project` grava no `.mcp.json`; sem, fica só para você).
|
|
75
|
+
|
|
76
|
+
- **Nome**: `argos-<aplicação>` (e `-leitura` para a variante só de consulta). As tools aparecem como
|
|
77
|
+
`mcp__argos-vendas__createRoute`: o prefixo deixa explícito onde cada ação cai.
|
|
78
|
+
- **Escopos**: `x-mcp-scopes` só **restringe** (nunca amplia). `autoservice.*.read` = agente de consulta;
|
|
79
|
+
lista completa em [references/tools.md](references/tools.md).
|
|
80
|
+
- **Clientes que não são navegador**: requisição com header `Origin` é recusada (403). Não use o MCP a partir de
|
|
81
|
+
uma página web.
|
|
82
|
+
|
|
83
|
+
### 3. Instruções para o agente (CLAUDE.md do projeto)
|
|
84
|
+
|
|
85
|
+
O servidor já manda as regras gerais no `initialize`. O que é do **seu** ambiente vai no `CLAUDE.md`:
|
|
86
|
+
|
|
87
|
+
```markdown
|
|
88
|
+
## Auto-serviço do Argos (MCP)
|
|
89
|
+
- Uma conexão por aplicação: `argos-vendas`, `argos-compras`, ... Use a da aplicação pedida; se o pedido não
|
|
90
|
+
disser qual, pergunte. Nunca "tente na outra".
|
|
91
|
+
- Comece por `getContext` e confirme o nome da aplicação antes de alterar algo.
|
|
92
|
+
- Antes de tool destrutiva (delete*, revoke*, remove*), mostre o que muda e peça confirmação.
|
|
93
|
+
- Nunca remova o grupo administrador, o acesso dele ou o próprio usuário dele.
|
|
94
|
+
- Secret de `createApp`: entregue só ao usuário, uma vez; nunca repita nem grave em arquivo.
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
## Como o agente deve trabalhar
|
|
98
|
+
|
|
99
|
+
1. **Escolha a conexão** pela aplicação pedida. Pedido ambíguo ("publica a tela de pedidos") com mais de uma
|
|
100
|
+
conexão disponível → pergunte qual aplicação.
|
|
101
|
+
2. **`getContext` primeiro**: confirma aplicação, usuário, escopos e validade da sessão.
|
|
102
|
+
3. **Leia antes de criar**: `listRoutes`/`getRoutingTree` (reaproveite rotas de nível superior), `listGroups`,
|
|
103
|
+
`listAccess`. Não invente ids: todo id vem de uma listagem.
|
|
104
|
+
4. **Siga os roteiros** do próprio servidor (prompts `register-screen`, `onboard-user`, `access-review`) ou os de
|
|
105
|
+
[references/roteiros.md](references/roteiros.md).
|
|
106
|
+
5. **Confirme o destrutivo** e **confira o efeito**: `listAuditEvents` com o `trace_id` devolvido em `_meta`.
|
|
107
|
+
|
|
108
|
+
### Modelo do Argos em uma tabela
|
|
109
|
+
|
|
110
|
+
| Conceito | O que é | Tools |
|
|
111
|
+
| --- | --- | --- |
|
|
112
|
+
| Rota | Um trecho do endereço/menu (`name`, `icon`, `path` em minúsculas e hífen) | `listRoutes`, `createRoute`, `updateRoute`, `deleteRoute` |
|
|
113
|
+
| Router | A tela: composição de rotas em níveis header › navigation › menu › item › submenu › **page**; o id dele é o `router_id` que o front registra | `createRouter`, `updateRouter`, `getRoutingTree`, `reorderRouters` |
|
|
114
|
+
| Acesso | Um grupo entra na aplicação | `listAccess`, `grantGroupAccess`, `revokeGroupAccess` |
|
|
115
|
+
| Guard | Qual router (tela) o grupo daquele acesso vê | `listAccessGuards`, `addAccessGuard`, `removeAccessGuard` |
|
|
116
|
+
| Membro | Usuário do realm dentro de um grupo da aplicação | `searchUsers`, `addGroupMember`, `removeGroupMember` |
|
|
117
|
+
| App | Backend da aplicação (client_credentials) | `listApps`, `createApp`, `listAppOperations` |
|
|
118
|
+
| Consumer / permissão | Grupo vinculado a um backend / operação do backend liberada para ele | `addAppConsumer`, `grantPermission`, `revokePermission` |
|
|
119
|
+
|
|
120
|
+
Tela nova: **rota(s) → router**; router privado (`is_private`) só aparece para o grupo que tiver o **guard** dele.
|
|
121
|
+
Operação de backend só libera depois de **consumer → permissão**.
|
|
122
|
+
|
|
123
|
+
### O que o MCP não faz (e o que dizer ao usuário)
|
|
124
|
+
|
|
125
|
+
- Alterar **outra** aplicação: precisa de outra conexão, com token criado nela.
|
|
126
|
+
- Editar rota/router **de template** (vem do template da aplicação) ou liberar rota **protegida**: só o painel
|
|
127
|
+
central do Argos.
|
|
128
|
+
- Criar/revogar tokens, mexer em realm, client, template ou tipo de grupo: painel central.
|
|
129
|
+
- Criar grupo novo: os grupos vêm vinculados à aplicação pelo painel; o MCP gerencia membros e permissões deles.
|
|
130
|
+
|
|
131
|
+
## Erros
|
|
132
|
+
|
|
133
|
+
Toda falha vem como `{ "error": { "code", "message" } }` (resultado `isError` numa tool). Resumo; detalhes e
|
|
134
|
+
causas em [references/diagnostico.md](references/diagnostico.md):
|
|
135
|
+
|
|
136
|
+
| Código | Leitura rápida |
|
|
137
|
+
| --- | --- |
|
|
138
|
+
| `AUTHENTICATION_ERROR` | Token ausente, expirado, revogado ou dono desativado → novo token |
|
|
139
|
+
| `AUTHORIZATION_ERROR` | Token sem nível Administrador / grupo sem acesso, escopo restrito, ou recurso de template |
|
|
140
|
+
| `VALIDATION_ERROR` | Argumento inválido (`details.issues` diz qual) ou `path` fora do padrão |
|
|
141
|
+
| `RESOURCE_NOT_FOUND` | Id inexistente **ou de outra aplicação** (o servidor não distingue) |
|
|
142
|
+
| `CONFLICT` | Já existe (vínculo, permissão) ou rota protegida |
|
|
143
|
+
| `TIMEOUT` / `INTERNAL_ERROR` | argos-admin lento ou fora; tente de novo, depois veja `/argos/mcp/health` |
|
|
144
|
+
|
|
145
|
+
HTTP 404 com `Mcp-Session-Id` é **sessão expirada**, não erro de dado: o cliente MCP refaz o `initialize` sozinho.
|
|
146
|
+
|
|
147
|
+
## Checklist
|
|
148
|
+
|
|
149
|
+
- [ ] Um token **por aplicação**, criado logado nela, nível **Administrador**, validade curta o bastante
|
|
150
|
+
- [ ] Uma conexão por aplicação, nome `argos-<aplicação>`, token em variável de ambiente (nada no git)
|
|
151
|
+
- [ ] Variante `-leitura` com `x-mcp-scopes: autoservice.*.read` quando o agente só consulta
|
|
152
|
+
- [ ] `CLAUDE.md` com o mapa conexão → aplicação e as regras de confirmação
|
|
153
|
+
- [ ] O agente começa por `getContext`, não inventa id e confere o efeito na auditoria
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# Diagnóstico do argos-mcp
|
|
2
|
+
|
|
3
|
+
Formato de erro (MES): `{ "error": { "code", "message", "details"? } }`. Antes da sessão (credencial, sessão,
|
|
4
|
+
origem) vem no corpo HTTP; dentro de uma tool vem como resultado `isError: true`.
|
|
5
|
+
|
|
6
|
+
## Ao conectar (HTTP)
|
|
7
|
+
|
|
8
|
+
| Sintoma | Causa | Ação |
|
|
9
|
+
| --- | --- | --- |
|
|
10
|
+
| 401 `AUTHENTICATION_ERROR` | Header ausente ou com nome errado (é `x-app-token`, não `Authorization`); token expirado, revogado; dono desativado | Confira o header e a variável de ambiente; crie outro token |
|
|
11
|
+
| 401 com token novo, aplicação de outro realm | O auth-server não lista o argos-mcp e o argos-admin em `INTROSPECT_ANY_REALM_APP_IDS` | Configuração da plataforma (quem administra o Argos) |
|
|
12
|
+
| 403 `AUTHORIZATION_ERROR` "nível Administrador" | Token criado com outro nível, ou o grupo da pessoa não tem acesso à aplicação | Crie o token logado na aplicação, escolhendo **Administrador** |
|
|
13
|
+
| 403 "token não identifica a aplicação" | Token sem aplicação (ex.: token de serviço) | Use um token pessoal (`argos_app_…`) |
|
|
14
|
+
| 403 "Origem não permitida" | Chamada de navegador (header `Origin`) | Use um cliente MCP de linha de comando/desktop |
|
|
15
|
+
| 400 `x-mcp-scopes inválido` | Caractere fora de `a-z . *` no header | Ex.: `autoservice.*.read` |
|
|
16
|
+
| 400 "Mcp-Session-Id obrigatório" | Cliente sem suporte a sessão do Streamable HTTP | Atualize o cliente MCP |
|
|
17
|
+
| 404 com `Mcp-Session-Id` | Sessão expirada (padrão 8 h, nunca além da validade do token), encerrada ou de outro token | Normal: o cliente refaz o `initialize` |
|
|
18
|
+
| 503 `INTERNAL_ERROR` "indisponível" | argos-admin fora ou inacessível pelo argos-mcp | `GET <host>/argos/mcp/health` mostra `admin`/`auth` |
|
|
19
|
+
|
|
20
|
+
## Dentro de uma tool
|
|
21
|
+
|
|
22
|
+
| Código | Causas comuns | Ação |
|
|
23
|
+
| --- | --- | --- |
|
|
24
|
+
| `VALIDATION_ERROR` | Argumento faltando/errado (`details.issues[].path`); id que não é UUID; `path` com `/`, número ou acento; update sem nenhum campo | Corrija o argumento; ids vêm das listagens |
|
|
25
|
+
| `AUTHORIZATION_ERROR` + `details.missing` | Escopo restrito por `x-mcp-scopes` (conexão `-leitura`) | Use a conexão com escrita, se o usuário quiser |
|
|
26
|
+
| `AUTHORIZATION_ERROR` sem `missing` | Rota/router de **template**; liberar rota **protegida**; badge do grupo fora dos `allowed_type_ids` do router (`badge_not_allowed`) | Template e proteção: painel central. Badge: `updateRouter` com `allowed_type_ids` |
|
|
27
|
+
| `RESOURCE_NOT_FOUND` | Id inexistente **ou de outra aplicação** (a resposta é a mesma de propósito); grupo não vinculado à aplicação; usuário de outro realm | Liste de novo na conexão certa |
|
|
28
|
+
| `CONFLICT` | Vínculo/guard/permissão já existe; excluir rota protegida | Trate como "já feito"; proteção só no painel central |
|
|
29
|
+
| `TIMEOUT` | argos-admin demorou mais de 15 s | Tente de novo; persistindo, plataforma |
|
|
30
|
+
| `INTERNAL_ERROR` | Falha no admin ou resposta fora do contrato | Guarde o `_meta.trace_id` e passe para quem opera o Argos |
|
|
31
|
+
|
|
32
|
+
## Conferir o que foi feito
|
|
33
|
+
|
|
34
|
+
`listAuditEvents` com `trace_id` (32 hex do `_meta`) mostra a ação inteira: o evento da requisição ao MCP
|
|
35
|
+
(`actor_type` `app_token`, com o nome da tool) e o evento de cada chamada ao auto-serviço. `getAuditTrace(trace_id)`
|
|
36
|
+
devolve a cadeia na ordem. Sem `from`/`to`, a janela é das últimas 24 h (máximo 31 dias).
|
|
37
|
+
|
|
38
|
+
## Saúde do servidor
|
|
39
|
+
|
|
40
|
+
`GET <host>/argos/mcp/live` (processo), `/ready` e `/health` (argos-admin e argos-auth), `/manifest` (contratos),
|
|
41
|
+
`/metrics` (Prometheus: `mcp_tool_executions_total`, `mcp_tool_failures_total`, ...). Todos públicos e sem dado de
|
|
42
|
+
aplicação.
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# Roteiros do auto-serviço pelo MCP
|
|
2
|
+
|
|
3
|
+
Sequências de tools para as tarefas comuns. Todas começam por `getContext` na conexão da aplicação certa e
|
|
4
|
+
terminam conferindo a auditoria (`listAuditEvents` com o `trace_id` do `_meta` da última tool). Ids sempre vêm de
|
|
5
|
+
uma listagem, nunca de suposição.
|
|
6
|
+
|
|
7
|
+
## Publicar uma tela nova
|
|
8
|
+
|
|
9
|
+
Pedido típico: "publica a tela de Ordens de serviço no menu Operação, para o grupo Atendentes".
|
|
10
|
+
|
|
11
|
+
1. `getRoutingTree` + `listRoutes`: ache o ponto do menu (ex.: a rota `operacao` no nível menu) e veja se a rota da
|
|
12
|
+
página já existe.
|
|
13
|
+
2. `createRoute` para cada nível que faltar. `path` é **um trecho só**, minúsculas e hífen (`ordens-servico`);
|
|
14
|
+
`path` vazio = rota "pasta" (só agrupa o menu).
|
|
15
|
+
3. `createRouter` com `page_id` = rota da página e os níveis acima (`menu_id`, ...). `is_private: true` quando só
|
|
16
|
+
quem tiver guard deve ver. `allowed_type_ids` restringe quais badges podem receber guard da tela.
|
|
17
|
+
4. `listGroups` → id do grupo; `listAccess` → `access_id` dele. Sem acesso: `grantGroupAccess` (confirme antes:
|
|
18
|
+
dá entrada na aplicação inteira).
|
|
19
|
+
5. `addAccessGuard(access_id, router_id)`.
|
|
20
|
+
6. Entregue ao usuário o **`router_id`**: é o id que a tela Angular registra em `features.routes.ts` (skill
|
|
21
|
+
**angular**). O MCP cria o lado do Argos; o código da tela continua sendo do repositório do app.
|
|
22
|
+
|
|
23
|
+
Ordem no menu: `getRoutingTree` devolve os `router_ids` de cada nó; `reorderRouters` recebe, por nível, os ids na
|
|
24
|
+
ordem desejada.
|
|
25
|
+
|
|
26
|
+
## Dar acesso a uma pessoa
|
|
27
|
+
|
|
28
|
+
1. `searchUsers(search)` por nome, usuário ou e-mail. Mais de um resultado → pergunte qual.
|
|
29
|
+
2. `listGroups` → o grupo certo (o tipo/badge dele diz o nível: Administrador, Usuário, ...).
|
|
30
|
+
3. `addGroupMember(group_id, user_id, role?)`. Já membro → só atualiza o papel.
|
|
31
|
+
4. Mostre o que a pessoa passa a ver: `listAccess` + `listAccessGuards` do acesso do grupo e, se houver backends,
|
|
32
|
+
`listAppConsumers`/`listConsumerPermissions`.
|
|
33
|
+
|
|
34
|
+
Tirar acesso é o inverso com `removeGroupMember` (destrutiva: confirme).
|
|
35
|
+
|
|
36
|
+
## Liberar operações de um backend para um grupo
|
|
37
|
+
|
|
38
|
+
1. `listApps` → `app_id`.
|
|
39
|
+
2. `listAppOperations(app_id)` → as operações que o backend registrou (`identifier`, `method`, `level`) e o
|
|
40
|
+
`operation_id` de cada uma. Só existem as que o serviço declarou com o Orfeu (skill **orfeu**); se falta
|
|
41
|
+
operação, o problema é no código do serviço, não no Argos.
|
|
42
|
+
3. `listAppConsumers(app_id)` → consumer do grupo; sem vínculo, `addAppConsumer(app_id, group_id)`.
|
|
43
|
+
4. `grantPermission(consumer_id, operation_id)` para cada operação. Prefira liberar leitura e escrita
|
|
44
|
+
separadamente, conforme o papel do grupo.
|
|
45
|
+
|
|
46
|
+
## Backend novo
|
|
47
|
+
|
|
48
|
+
`createApp(name)` devolve `id` e **`secret` uma única vez**. Entregue os dois ao usuário para o cofre/variáveis
|
|
49
|
+
do serviço (`APP_ID`/`APP_SECRET` do Orfeu) e não repita o secret depois. Em seguida, o serviço sobe, registra as
|
|
50
|
+
operações, e o roteiro acima libera as operações aos grupos.
|
|
51
|
+
|
|
52
|
+
## Revisão de acesso (só leitura)
|
|
53
|
+
|
|
54
|
+
Use a conexão `-leitura` se existir. `listAccess` → para cada acesso, `listAccessGuards`; `listGroupMembers` de
|
|
55
|
+
cada grupo; `listApps` → `listAppConsumers` → `listConsumerPermissions`. Monte a tabela
|
|
56
|
+
grupo → membros → telas → operações e aponte excessos (grupo sem membro, tela sem guard, escrita liberada a grupo
|
|
57
|
+
de consulta). **Proponha**; não remova nada sem o usuário confirmar item a item.
|
|
58
|
+
|
|
59
|
+
## Mais de uma aplicação no mesmo pedido
|
|
60
|
+
|
|
61
|
+
"Libera a tela X nas aplicações Vendas e Compras": faça o roteiro inteiro numa conexão, confira, e repita na
|
|
62
|
+
outra. Ids de uma aplicação **não** valem na outra (rotas, routers, grupos e acessos são por aplicação); nunca
|
|
63
|
+
reaproveite um id entre conexões.
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
# Tools, escopos e resources do argos-mcp
|
|
2
|
+
|
|
3
|
+
Tabela gerada do código do argos-mcp (contrato `1.0.0` de todas as tools). O contrato completo, com JSON Schema
|
|
4
|
+
draft 2020-12 de entrada e saída, sai do próprio servidor: `GET <host>/argos/mcp/manifest` (público) ou
|
|
5
|
+
`tools/list` numa sessão. Nenhuma tool recebe a aplicação: é sempre a do token.
|
|
6
|
+
|
|
7
|
+
Resultado de sucesso: `structuredContent` com o objeto do contrato (o mesmo JSON em `content[0].text`) e
|
|
8
|
+
`_meta.trace_id`/`span_id` para achar a ação na auditoria. Falha: `isError: true` e `{ error: { code, message,
|
|
9
|
+
details? } }` (ver [diagnostico.md](diagnostico.md)).
|
|
10
|
+
|
|
11
|
+
## Identidade (contexto, grupos, membros)
|
|
12
|
+
|
|
13
|
+
| Tool | Escopo | Tipo | Argumentos (obrigatórios em **negrito**) |
|
|
14
|
+
| --- | --- | --- | --- |
|
|
15
|
+
| `getContext` | `autoservice.context.read` | leitura | — |
|
|
16
|
+
| `listGroups` | `autoservice.groups.read` | leitura | — |
|
|
17
|
+
| `searchUsers` | `autoservice.groups.read` | leitura | search, limit |
|
|
18
|
+
| `listGroupMembers` | `autoservice.groups.read` | leitura | **group_id** |
|
|
19
|
+
| `addGroupMember` | `autoservice.groups.write` | escrita | **group_id**, **user_id**, role |
|
|
20
|
+
| `updateGroupMemberRole` | `autoservice.groups.write` | escrita | **group_id**, **user_id**, **role** |
|
|
21
|
+
| `removeGroupMember` | `autoservice.groups.write` | **destrutiva** | **group_id**, **user_id** |
|
|
22
|
+
|
|
23
|
+
## Rotas e roteamento
|
|
24
|
+
|
|
25
|
+
| Tool | Escopo | Tipo | Argumentos (obrigatórios em **negrito**) |
|
|
26
|
+
| --- | --- | --- | --- |
|
|
27
|
+
| `listRoutes` | `autoservice.routes.read` | leitura | — |
|
|
28
|
+
| `getRoute` | `autoservice.routes.read` | leitura | **route_id** |
|
|
29
|
+
| `createRoute` | `autoservice.routes.write` | escrita | **name**, display_name, **icon**, path, info, excludable |
|
|
30
|
+
| `updateRoute` | `autoservice.routes.write` | escrita | **route_id**, name, display_name, icon, path, info, excludable |
|
|
31
|
+
| `deleteRoute` | `autoservice.routes.write` | **destrutiva** | **route_id** |
|
|
32
|
+
| `listRouters` | `autoservice.routing.read` | leitura | — |
|
|
33
|
+
| `getRouter` | `autoservice.routing.read` | leitura | **router_id** |
|
|
34
|
+
| `getRoutingTree` | `autoservice.routing.read` | leitura | — |
|
|
35
|
+
| `createRouter` | `autoservice.routing.write` | escrita | **page_id**, header_id, navigation_id, menu_id, item_id, submenu_id, is_private, description, allowed_type_ids |
|
|
36
|
+
| `updateRouter` | `autoservice.routing.write` | escrita | **router_id**, page_id, header_id, navigation_id, menu_id, item_id, submenu_id, is_private, description, allowed_type_ids |
|
|
37
|
+
| `deleteRouter` | `autoservice.routing.write` | **destrutiva** | **router_id** |
|
|
38
|
+
| `reorderRouters` | `autoservice.routing.write` | escrita | **groups** |
|
|
39
|
+
|
|
40
|
+
## Acesso, aplicações e permissões
|
|
41
|
+
|
|
42
|
+
| Tool | Escopo | Tipo | Argumentos (obrigatórios em **negrito**) |
|
|
43
|
+
| --- | --- | --- | --- |
|
|
44
|
+
| `listAccess` | `autoservice.access.read` | leitura | — |
|
|
45
|
+
| `grantGroupAccess` | `autoservice.access.write` | escrita | **group_id** |
|
|
46
|
+
| `revokeGroupAccess` | `autoservice.access.write` | **destrutiva** | **access_id** |
|
|
47
|
+
| `listAccessGuards` | `autoservice.access.read` | leitura | **access_id** |
|
|
48
|
+
| `addAccessGuard` | `autoservice.access.write` | escrita | **access_id**, **router_id** |
|
|
49
|
+
| `removeAccessGuard` | `autoservice.access.write` | **destrutiva** | **access_id**, **guard_id** |
|
|
50
|
+
| `listApps` | `autoservice.apps.read` | leitura | — |
|
|
51
|
+
| `getApp` | `autoservice.apps.read` | leitura | **app_id** |
|
|
52
|
+
| `createApp` | `autoservice.apps.write` | escrita | **name**, allowed_grants |
|
|
53
|
+
| `updateApp` | `autoservice.apps.write` | escrita | **app_id**, name, allowed_grants, enabled |
|
|
54
|
+
| `deleteApp` | `autoservice.apps.write` | **destrutiva** | **app_id** |
|
|
55
|
+
| `listAppOperations` | `autoservice.apps.read` | leitura | **app_id** |
|
|
56
|
+
| `listAppConsumers` | `autoservice.permissions.read` | leitura | **app_id** |
|
|
57
|
+
| `addAppConsumer` | `autoservice.permissions.write` | escrita | **app_id**, **group_id** |
|
|
58
|
+
| `removeAppConsumer` | `autoservice.permissions.write` | **destrutiva** | **consumer_id** |
|
|
59
|
+
| `listConsumerPermissions` | `autoservice.permissions.read` | leitura | **consumer_id** |
|
|
60
|
+
| `grantPermission` | `autoservice.permissions.write` | escrita | **consumer_id**, **operation_id** |
|
|
61
|
+
| `revokePermission` | `autoservice.permissions.write` | **destrutiva** | **consumer_id**, **permission_id** |
|
|
62
|
+
|
|
63
|
+
## Auditoria
|
|
64
|
+
|
|
65
|
+
| Tool | Escopo | Tipo | Argumentos (obrigatórios em **negrito**) |
|
|
66
|
+
| --- | --- | --- | --- |
|
|
67
|
+
| `listAuditEvents` | `autoservice.audit.read` | leitura | from, to, app_id, user_id, operation, method, outcome, actor_type, trace_id, limit, cursor |
|
|
68
|
+
| `getAuditTrace` | `autoservice.audit.read` | leitura | **trace_id** |
|
|
69
|
+
|
|
70
|
+
## Escopos
|
|
71
|
+
|
|
72
|
+
| Escopo | Permite |
|
|
73
|
+
| --- | --- |
|
|
74
|
+
| `autoservice.context.read` | Ver o client do token, o usuário e a sessão |
|
|
75
|
+
| `autoservice.routes.read` | Listar e ver rotas (telas) do client |
|
|
76
|
+
| `autoservice.routes.write` | Criar, editar e excluir rotas do client |
|
|
77
|
+
| `autoservice.routing.read` | Ver o roteamento (routers) e a árvore do menu |
|
|
78
|
+
| `autoservice.routing.write` | Criar, editar, reordenar e excluir routers |
|
|
79
|
+
| `autoservice.groups.read` | Listar grupos do client, membros e buscar usuários do realm |
|
|
80
|
+
| `autoservice.groups.write` | Adicionar, alterar papel e remover membros dos grupos do client |
|
|
81
|
+
| `autoservice.access.read` | Ver quais grupos acessam o client e quais telas cada um vê |
|
|
82
|
+
| `autoservice.access.write` | Conceder/revogar acesso de grupo ao client e às telas (guards) |
|
|
83
|
+
| `autoservice.apps.read` | Listar e ver as aplicações (backends) do client e suas operações |
|
|
84
|
+
| `autoservice.apps.write` | Criar, editar e excluir aplicações do client |
|
|
85
|
+
| `autoservice.permissions.read` | Ver consumers (grupo x aplicação) e as permissões por operação |
|
|
86
|
+
| `autoservice.permissions.write` | Vincular grupos às aplicações e conceder/revogar operações |
|
|
87
|
+
| `autoservice.audit.read` | Consultar a auditoria das aplicações do client |
|
|
88
|
+
|
|
89
|
+
`x-mcp-scopes` aceita lista (vírgula ou espaço) e curinga por segmento: `autoservice.*.read` (só leitura),
|
|
90
|
+
`autoservice.routes.*`, `autoservice.*`. Escopo desconhecido não amplia nada; caractere inválido = 400.
|
|
91
|
+
|
|
92
|
+
## Resources
|
|
93
|
+
|
|
94
|
+
| URI | Conteúdo |
|
|
95
|
+
| --- | --- |
|
|
96
|
+
| `argos-autoservice://catalog` | Catálogo: tools, resources e prompts com versão, escopos e criticidade |
|
|
97
|
+
| `argos-autoservice://ownership` | Dono e contato do servidor |
|
|
98
|
+
| `argos-autoservice://dependencies` | Do que o MCP depende (argos-admin, argos-auth) |
|
|
99
|
+
| `argos-autoservice://runbooks` · `playbooks` | Diagnóstico e roteiros (o mesmo conteúdo desta skill, do lado do servidor) |
|
|
100
|
+
| `argos-autoservice://client/routes` · `routing-tree` · `groups` · `access` · `apps` | Dados vivos da aplicação do token |
|
|
101
|
+
|
|
102
|
+
## Prompts
|
|
103
|
+
|
|
104
|
+
| Prompt | Argumentos | Para |
|
|
105
|
+
| --- | --- | --- |
|
|
106
|
+
| `register-screen` | **screen**, **path**, icon, group | Publicar uma tela |
|
|
107
|
+
| `onboard-user` | **user**, **group**, role | Dar acesso a uma pessoa |
|
|
108
|
+
| `access-review` | — | Revisão de acesso (só propõe, não altera) |
|
package/skills/orfeu/SKILL.md
CHANGED
|
@@ -75,7 +75,7 @@ o guard **nunca** lê `Authorization: Bearer` (esse header só aparece nas chama
|
|
|
75
75
|
| Header | Quem manda | Validação | Permissão |
|
|
76
76
|
|---|---|---|---|
|
|
77
77
|
| `x-access-token` | usuário numa UI (token do `@orfeu/angular`) | local: JWT + JWKS do realm | grupos do token |
|
|
78
|
-
| `x-app-token` | usuário fora da UI (script, MCP) — token pessoal | introspecção no Argos (cache) | grupos do usuário no client |
|
|
78
|
+
| `x-app-token` | usuário fora da UI (script, MCP) — token pessoal, preso a uma aplicação | introspecção no Argos (cache) | grupos do usuário no client (MCP do auto-serviço: skill **auto-servico**) |
|
|
79
79
|
| `x-api-token` | outro backend / integração | introspecção no Argos (cache) | só as operações concedidas ao token **neste** serviço |
|
|
80
80
|
|
|
81
81
|
| Situação | Resultado |
|
|
@@ -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.
|