@acropole/skills 0.0.0-stage → 1.0.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.
Files changed (90) hide show
  1. package/README.md +180 -2
  2. package/agents/revisor-deploy.md +73 -0
  3. package/agents/revisor-documentacao.md +78 -0
  4. package/agents/revisor-orfeu.md +80 -0
  5. package/agents/revisor-trismegisto.md +81 -0
  6. package/bin/install.js +252 -0
  7. package/package.json +15 -4
  8. package/skills/acropole/SKILL.md +75 -0
  9. package/skills/acropole/references/fluxos/doctor.md +55 -0
  10. package/skills/acropole/references/fluxos/endpoint-novo.md +22 -0
  11. package/skills/acropole/references/fluxos/revisar.md +56 -0
  12. package/skills/acropole/references/fluxos/tela-nova.md +27 -0
  13. package/skills/acropole/scripts/doctor.mjs +439 -0
  14. package/skills/angular/SKILL.md +152 -0
  15. package/skills/angular/references/armadilhas.md +95 -0
  16. package/skills/angular/references/dados.md +251 -0
  17. package/skills/angular/references/estrutura.md +260 -0
  18. package/skills/angular/references/features.md +219 -0
  19. package/skills/angular/references/testes-build.md +230 -0
  20. package/skills/angular/scripts/checar.mjs +182 -0
  21. package/skills/angular/scripts/nucleo.mjs +227 -0
  22. package/skills/apollo/SKILL.md +222 -0
  23. package/skills/apollo/references/armadilhas.md +95 -0
  24. package/skills/apollo/references/envelope-erros.md +120 -0
  25. package/skills/apollo/references/estrutura-bootstrap.md +299 -0
  26. package/skills/apollo/references/schema-resolvers.md +183 -0
  27. package/skills/apollo/references/subscriptions.md +224 -0
  28. package/skills/apollo/references/testes-build.md +180 -0
  29. package/skills/apollo/scripts/checar.mjs +160 -0
  30. package/skills/apollo/scripts/nucleo.mjs +227 -0
  31. package/skills/docker/SKILL.md +102 -0
  32. package/skills/docker/references/modelos.md +251 -0
  33. package/skills/docker/references/porques.md +282 -0
  34. package/skills/documentacao/SKILL.md +146 -0
  35. package/skills/documentacao/references/checklist-coerencia.md +59 -0
  36. package/skills/documentacao/references/ligar-app-novo.md +107 -0
  37. package/skills/documentacao/references/modelo-especificacao.md +51 -0
  38. package/skills/documentacao/references/modelo-readme.md +75 -0
  39. package/skills/documentacao/scripts/checar.mjs +454 -0
  40. package/skills/documentacao/scripts/nucleo.mjs +227 -0
  41. package/skills/express/SKILL.md +154 -0
  42. package/skills/express/references/dados.md +180 -0
  43. package/skills/express/references/estrutura.md +154 -0
  44. package/skills/express/references/middlewares.md +227 -0
  45. package/skills/express/references/rotas-erros.md +274 -0
  46. package/skills/express/references/testes-deploy.md +150 -0
  47. package/skills/express/scripts/checar.mjs +115 -0
  48. package/skills/express/scripts/nucleo.mjs +227 -0
  49. package/skills/fastapi/SKILL.md +129 -0
  50. package/skills/fastapi/references/banco.md +185 -0
  51. package/skills/fastapi/references/estrutura.md +281 -0
  52. package/skills/fastapi/references/integracoes.md +145 -0
  53. package/skills/fastapi/references/rotas-erros.md +140 -0
  54. package/skills/fastapi/references/testes-deploy.md +190 -0
  55. package/skills/fastapi/scripts/checar.mjs +108 -0
  56. package/skills/fastapi/scripts/nucleo.mjs +227 -0
  57. package/skills/hefesto/SKILL.md +119 -0
  58. package/skills/hefesto/references/conceitos.md +131 -0
  59. package/skills/hefesto/references/diagnostico.md +70 -0
  60. package/skills/hefesto/references/fluxo.md +122 -0
  61. package/skills/hefesto/references/preparar-app.md +105 -0
  62. package/skills/orfeu/SKILL.md +162 -0
  63. package/skills/orfeu/references/angular-api.md +201 -0
  64. package/skills/orfeu/references/angular-armadilhas.md +116 -0
  65. package/skills/orfeu/references/angular-recipes.md +474 -0
  66. package/skills/orfeu/references/angular.md +212 -0
  67. package/skills/orfeu/references/diferencas.md +56 -0
  68. package/skills/orfeu/references/node-api.md +348 -0
  69. package/skills/orfeu/references/node-armadilhas.md +158 -0
  70. package/skills/orfeu/references/node-recipes.md +534 -0
  71. package/skills/orfeu/references/node.md +204 -0
  72. package/skills/orfeu/references/python-api.md +346 -0
  73. package/skills/orfeu/references/python-recipes.md +479 -0
  74. package/skills/orfeu/references/python.md +234 -0
  75. package/skills/orfeu/scripts/checar.mjs +126 -0
  76. package/skills/orfeu/scripts/nucleo.mjs +227 -0
  77. package/skills/trismegisto/SKILL.md +194 -0
  78. package/skills/trismegisto/references/angular-api.md +2788 -0
  79. package/skills/trismegisto/references/angular-exports.md +4020 -0
  80. package/skills/trismegisto/references/angular-recipes.md +1883 -0
  81. package/skills/trismegisto/references/angular-types.md +492 -0
  82. package/skills/trismegisto/references/angular.md +390 -0
  83. package/skills/trismegisto/references/catalogo/icones.json +912 -0
  84. package/skills/trismegisto/references/catalogo/seletores.json +7013 -0
  85. package/skills/trismegisto/references/catalogo/tokens.json +240 -0
  86. package/skills/trismegisto/references/spine-api.md +1530 -0
  87. package/skills/trismegisto/references/spine-recipes.md +581 -0
  88. package/skills/trismegisto/references/spine.md +343 -0
  89. package/skills/trismegisto/scripts/checar.mjs +216 -0
  90. package/skills/trismegisto/scripts/nucleo.mjs +227 -0
package/bin/install.js ADDED
@@ -0,0 +1,252 @@
1
+ #!/usr/bin/env node
2
+ // Instalador das skills e dos subagentes revisores da Acrópole para o Claude Code. Sem dependências:
3
+ // copia as pastas de `skills/` para `~/.claude/skills/` e os arquivos de `agents/` para
4
+ // `~/.claude/agents/` (ou `./.claude/...` com --project). Não faz rede, não executa nada além da cópia,
5
+ // nunca escreve fora das pastas das próprias skills e dos arquivos dos próprios agentes.
6
+ 'use strict';
7
+
8
+ const fs = require('fs');
9
+ const path = require('path');
10
+ const os = require('os');
11
+ const { name, version } = require('../package.json');
12
+
13
+ const args = process.argv.slice(2);
14
+ const has = (flag) => args.includes(flag);
15
+ const valueOf = (flag) => {
16
+ const i = args.indexOf(flag);
17
+ return i >= 0 ? args[i + 1] : undefined;
18
+ };
19
+ const fail = (msg) => {
20
+ console.error(`${name}: ${msg}`);
21
+ process.exit(1);
22
+ };
23
+
24
+ const SKILLS_SRC = path.join(__dirname, '..', 'skills');
25
+ const AGENTS_SRC = path.join(__dirname, '..', 'agents');
26
+ const availableSkills = fs.existsSync(SKILLS_SRC)
27
+ ? fs.readdirSync(SKILLS_SRC, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort()
28
+ : [];
29
+ const availableAgents = fs.existsSync(AGENTS_SRC)
30
+ ? fs.readdirSync(AGENTS_SRC, { withFileTypes: true })
31
+ .filter((d) => d.isFile() && d.name.endsWith('.md'))
32
+ .map((d) => d.name.slice(0, -3))
33
+ .sort()
34
+ : [];
35
+
36
+ if (has('--help') || has('-h')) {
37
+ console.log(`${name} ${version}
38
+
39
+ Uso: npx ${name} [opções]
40
+
41
+ (sem opções) instala todas as skills em ~/.claude/skills/ e os agentes em ~/.claude/agents/
42
+ --project usa ./.claude/ (só neste projeto) em vez de ~/.claude/
43
+ --only a,b só as skills/agentes indicados (ex.: --only angular,trismegisto,revisor-trismegisto)
44
+ --no-agents não instala (nem remove, com --uninstall) os agentes revisores
45
+ --uninstall remove as skills e os agentes do pacote (combina com --project, --only, --no-agents)
46
+ --force substitui/remove pasta ou arquivo de mesmo nome que não veio deste pacote
47
+ --status mostra o que está instalado, a versão e se está defasado em relação a ${version}
48
+ --list lista as skills e os agentes do pacote
49
+ --help mostra esta ajuda
50
+
51
+ Skills: ${availableSkills.join(', ')}
52
+ Agentes: ${availableAgents.join(', ') || '(nenhum)'}
53
+
54
+ Atualizar: npx ${name}@latest (o instalador não consulta a rede; quem traz a versão nova é o npx).`);
55
+ process.exit(0);
56
+ }
57
+
58
+ const major = Number(process.versions.node.split('.')[0]);
59
+ if (major < 18) fail(`requer Node 18 ou superior (encontrado ${process.versions.node}).`);
60
+
61
+ if (has('--list')) {
62
+ console.log('skills:');
63
+ for (const s of availableSkills) console.log(` ${s}`);
64
+ console.log('agentes:');
65
+ for (const a of availableAgents) console.log(` ${a}`);
66
+ process.exit(0);
67
+ }
68
+
69
+ const base = has('--project') ? process.cwd() : os.homedir();
70
+ const skillsRoot = path.join(base, '.claude', 'skills');
71
+ const agentsRoot = path.join(base, '.claude', 'agents');
72
+
73
+ // --- Propriedade -----------------------------------------------------------------------------------
74
+ // Skills: as pastas criadas por este pacote levam um arquivo `.acropole`. Sem ele, a pasta é de outra
75
+ // origem e só é substituída/removida com --force.
76
+ // Agentes: são arquivos soltos em `.claude/agents/`, então a posse fica registrada de dois jeitos
77
+ // (qualquer um basta): o manifesto `.acropole-manifest.json` e um comentário-marca logo após o
78
+ // frontmatter do arquivo instalado.
79
+ const SKILL_MARKER = '.acropole';
80
+ const MANIFEST = path.join(agentsRoot, '.acropole-manifest.json');
81
+ const AGENT_MARK_RE = /^<!-- acropole: instalado por (\S+) (\S+) -->$/m;
82
+
83
+ const skillOwnedOrAbsent = (dest) => !fs.existsSync(dest) || fs.existsSync(path.join(dest, SKILL_MARKER));
84
+
85
+ function readManifest() {
86
+ try {
87
+ const data = JSON.parse(fs.readFileSync(MANIFEST, 'utf8'));
88
+ return Array.isArray(data.agents) ? data : { agents: [] };
89
+ } catch {
90
+ return { agents: [] };
91
+ }
92
+ }
93
+ function writeManifest(agents) {
94
+ const list = [...new Set(agents)].sort();
95
+ if (!list.length) {
96
+ fs.rmSync(MANIFEST, { force: true });
97
+ return;
98
+ }
99
+ fs.mkdirSync(agentsRoot, { recursive: true });
100
+ fs.writeFileSync(MANIFEST, `${JSON.stringify({ package: name, version, agents: list }, null, 2)}\n`);
101
+ }
102
+ const agentFile = (agent) => path.join(agentsRoot, `${agent}.md`);
103
+ const agentMark = (file) => {
104
+ try {
105
+ const m = fs.readFileSync(file, 'utf8').match(AGENT_MARK_RE);
106
+ return m ? { pkg: m[1], version: m[2] } : null;
107
+ } catch {
108
+ return null;
109
+ }
110
+ };
111
+ const agentOwnedOrAbsent = (agent, manifest) => {
112
+ const file = agentFile(agent);
113
+ return !fs.existsSync(file) || manifest.agents.includes(agent) || agentMark(file) !== null;
114
+ };
115
+
116
+ /** Insere a marca de posse logo após o frontmatter (o Claude Code lê o frontmatter na 1ª linha). */
117
+ function stampAgent(src) {
118
+ const mark = `<!-- acropole: instalado por ${name} ${version} -->`;
119
+ const m = src.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n/);
120
+ return m ? `${m[0]}${mark}\n${src.slice(m[0].length)}` : `${mark}\n${src}`;
121
+ }
122
+
123
+ // --- Status ----------------------------------------------------------------------------------------
124
+ function compareVersions(a, b) {
125
+ const pa = String(a).split(/[.+-]/).map((n) => parseInt(n, 10) || 0);
126
+ const pb = String(b).split(/[.+-]/).map((n) => parseInt(n, 10) || 0);
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
+ return 0;
129
+ }
130
+ function describe(installed) {
131
+ if (!installed) return 'versão desconhecida';
132
+ 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} — mais nova que este pacote (${version})`;
135
+ return `${installed} — em dia`;
136
+ }
137
+
138
+ if (has('--status')) {
139
+ console.log(`${name} ${version} — ${has('--project') ? 'projeto' : 'usuário'} (${path.join(base, '.claude')})\n`);
140
+ let outdated = 0;
141
+ console.log('skills:');
142
+ for (const s of availableSkills) {
143
+ const dest = path.join(skillsRoot, s);
144
+ if (!fs.existsSync(dest)) console.log(` ${s}: não instalada`);
145
+ else if (!fs.existsSync(path.join(dest, SKILL_MARKER))) console.log(` ${s}: pasta de outra origem (não é deste pacote)`);
146
+ else {
147
+ let v = '';
148
+ try { v = fs.readFileSync(path.join(dest, 'VERSION'), 'utf8').trim(); } catch { /* sem VERSION */ }
149
+ if (v && compareVersions(v, version) < 0) outdated++;
150
+ console.log(` ${s}: ${describe(v)}`);
151
+ }
152
+ }
153
+ const manifest = readManifest();
154
+ console.log('agentes:');
155
+ for (const a of availableAgents) {
156
+ const file = agentFile(a);
157
+ const mark = fs.existsSync(file) ? agentMark(file) : null;
158
+ if (!fs.existsSync(file)) console.log(` ${a}: não instalado`);
159
+ else if (!mark && !manifest.agents.includes(a)) console.log(` ${a}: arquivo de outra origem (não é deste pacote)`);
160
+ else {
161
+ const v = mark ? mark.version : '';
162
+ if (v && compareVersions(v, version) < 0) outdated++;
163
+ console.log(` ${a}: ${describe(v)}`);
164
+ }
165
+ }
166
+ const orphans = manifest.agents.filter((a) => !availableAgents.includes(a) && fs.existsSync(agentFile(a)));
167
+ for (const a of orphans) console.log(` ${a}: instalado por versão anterior, não existe mais no pacote (sai no próximo install)`);
168
+ if (outdated) console.log(`\n${outdated} item(ns) defasado(s). Atualize com: npx ${name}@latest${has('--project') ? ' --project' : ''}`);
169
+ process.exit(0);
170
+ }
171
+
172
+ // --- Seleção ---------------------------------------------------------------------------------------
173
+ let skills = availableSkills;
174
+ let agents = has('--no-agents') ? [] : availableAgents;
175
+ if (has('--only')) {
176
+ const only = valueOf('--only');
177
+ if (!only || only.startsWith('--')) fail('--only precisa de uma lista (ex.: --only angular,orfeu).');
178
+ const wanted = only.split(',').map((s) => s.trim()).filter(Boolean);
179
+ const unknown = wanted.filter((s) => !availableSkills.includes(s) && !availableAgents.includes(s));
180
+ if (unknown.length) {
181
+ fail(`skill/agente desconhecido: ${unknown.join(', ')}. Skills: ${availableSkills.join(', ')}. Agentes: ${availableAgents.join(', ')}`);
182
+ }
183
+ skills = wanted.filter((s) => availableSkills.includes(s));
184
+ agents = has('--no-agents') ? [] : wanted.filter((s) => availableAgents.includes(s));
185
+ }
186
+
187
+ // Tudo é verificado antes de qualquer escrita: nada de instalação parcial.
188
+ const manifest = readManifest();
189
+ const blockedSkills = skills.filter((s) => !skillOwnedOrAbsent(path.join(skillsRoot, s)));
190
+ const blockedAgents = agents.filter((a) => !agentOwnedOrAbsent(a, manifest));
191
+ if ((blockedSkills.length || blockedAgents.length) && !has('--force')) {
192
+ const items = [...blockedSkills.map((s) => path.join(skillsRoot, s)), ...blockedAgents.map(agentFile)];
193
+ fail(
194
+ `já existe skill/agente com o mesmo nome que não foi instalado por este pacote: ${items.join(', ')}\n` +
195
+ 'Para substituir/remover mesmo assim, rode com --force (ou use --only/--no-agents para pular esses).',
196
+ );
197
+ }
198
+
199
+ const uninstall = has('--uninstall');
200
+
201
+ for (const skill of skills) {
202
+ const dest = path.join(skillsRoot, skill);
203
+ // Defesa: o destino é sempre uma pasta de skill direto em `.claude/skills/`.
204
+ if (path.dirname(dest) !== skillsRoot) throw new Error(`destino inesperado: ${dest}`);
205
+ const existed = fs.existsSync(dest);
206
+ fs.rmSync(dest, { recursive: true, force: true });
207
+ if (uninstall) {
208
+ if (existed) console.log(`Removida: ${dest}`);
209
+ continue;
210
+ }
211
+ fs.mkdirSync(skillsRoot, { recursive: true });
212
+ fs.cpSync(path.join(SKILLS_SRC, skill), dest, { recursive: true });
213
+ fs.writeFileSync(path.join(dest, 'VERSION'), `${version}\n`);
214
+ fs.writeFileSync(path.join(dest, SKILL_MARKER), `${name}\n`);
215
+ console.log(`${skill} ${version} instalada em ${dest}`);
216
+ }
217
+
218
+ let owned = manifest.agents.slice();
219
+ for (const agent of agents) {
220
+ const dest = agentFile(agent);
221
+ // Defesa: o destino é sempre um arquivo direto em `.claude/agents/`.
222
+ if (path.dirname(dest) !== agentsRoot) throw new Error(`destino inesperado: ${dest}`);
223
+ if (uninstall) {
224
+ if (fs.existsSync(dest)) {
225
+ fs.rmSync(dest, { force: true });
226
+ console.log(`Removido: ${dest}`);
227
+ }
228
+ owned = owned.filter((a) => a !== agent);
229
+ continue;
230
+ }
231
+ fs.mkdirSync(agentsRoot, { recursive: true });
232
+ fs.writeFileSync(dest, stampAgent(fs.readFileSync(path.join(AGENTS_SRC, `${agent}.md`), 'utf8')));
233
+ owned.push(agent);
234
+ console.log(`${agent} ${version} instalado em ${dest}`);
235
+ }
236
+
237
+ // Agentes de versão anterior que saíram do pacote: são nossos (estão no manifesto), então saem junto.
238
+ if (!has('--no-agents') && !has('--only')) {
239
+ for (const agent of owned.filter((a) => !availableAgents.includes(a))) {
240
+ const dest = agentFile(agent);
241
+ if (path.dirname(dest) === agentsRoot && fs.existsSync(dest)) {
242
+ fs.rmSync(dest, { force: true });
243
+ console.log(`Removido (não existe mais no pacote): ${dest}`);
244
+ }
245
+ owned = owned.filter((a) => a !== agent);
246
+ }
247
+ }
248
+ if (agents.length || owned.length !== manifest.agents.length) writeManifest(owned);
249
+
250
+ if (!uninstall) {
251
+ console.log(`\nPronto. Skills e agentes valem a partir da próxima sessão do Claude Code.\nAtualizar: npx ${name}@latest`);
252
+ }
package/package.json CHANGED
@@ -1,6 +1,17 @@
1
1
  {
2
2
  "name": "@acropole/skills",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.0.0",
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
+ "bin": { "acropole-skills": "bin/install.js" },
6
+ "files": ["bin", "skills", "agents"],
7
+ "engines": { "node": ">=18" },
8
+ "license": "MIT",
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"],
11
+ "scripts": {
12
+ "bump": "node scripts/bump.mjs",
13
+ "sync": "node scripts/sync-generated.mjs",
14
+ "test": "node --test test/install.test.mjs test/integridade.test.mjs"
15
+ },
16
+ "publishConfig": { "access": "public" }
17
+ }
@@ -0,0 +1,75 @@
1
+ ---
2
+ name: acropole
3
+ description: Porta de entrada das skills da Acrópole — descobre a stack do projeto (Angular + Trismegisto, Apollo, Express, FastAPI, Orfeu, Docker/Hefesto), sugere o fluxo certo e encadeia as skills na ordem — tela nova, endpoint novo, revisão com os verificadores e os subagentes revisores, e diagnóstico (doctor) do projeto. Use quando o usuário chamar /acropole, pedir "por onde começo", "qual skill uso", uma tela ou endpoint de ponta a ponta, uma revisão geral, ou um diagnóstico de versões/configuração do projeto.
4
+ user-invocable: true
5
+ argument-hint: "[tela-nova | endpoint-novo | revisar | doctor] [alvo]"
6
+ ---
7
+
8
+ # acropole — fluxos entre as skills
9
+
10
+ As skills da Acrópole cobrem uma parte da stack cada uma. Esta skill não repete regra de nenhuma
11
+ delas: diz **qual** convocar, **em que ordem**, e onde estão os verificadores e os revisores.
12
+
13
+ ## Comandos
14
+
15
+ | Comando | O que faz | Playbook |
16
+ | --- | --- | --- |
17
+ | `/acropole tela-nova [nome]` | Tela Angular de ponta a ponta: Argos → rota → GraphQL → service → componente `hm-*` → operação no backend → testes | [references/fluxos/tela-nova.md](references/fluxos/tela-nova.md) |
18
+ | `/acropole endpoint-novo [recurso]` | Endpoint/resolver no backend com operação do Orfeu, propagação de headers, auditoria e teste | [references/fluxos/endpoint-novo.md](references/fluxos/endpoint-novo.md) |
19
+ | `/acropole revisar [caminho]` | Roda os verificadores das skills sobre o diff/arquivos e chama os subagentes revisores; só relata | [references/fluxos/revisar.md](references/fluxos/revisar.md) |
20
+ | `/acropole doctor [pasta]` | Diagnostica o projeto (versões, `angular.json`, `provideHttpClient`, Dockerfile, `orfeu` Python) | [references/fluxos/doctor.md](references/fluxos/doctor.md) |
21
+
22
+ Com argumento: carregue **só** o playbook do comando e siga-o. Argumento desconhecido: mostre a tabela
23
+ acima e pergunte.
24
+
25
+ ## Sem argumento: menu pelo contexto
26
+
27
+ 1. Leia (só leitura) os manifestos na raiz e, num monorepo, um nível abaixo: `package.json`,
28
+ `angular.json`, `pyproject.toml`, `requirements*.txt`, `Dockerfile`. Não rode install, build nem git
29
+ que escreva.
30
+ 2. Deduza a stack pelas dependências:
31
+ - `@angular/core` + `@trismegisto/*` → front (skills **angular**, **trismegisto**, **orfeu**);
32
+ - `@apollo/server` → **apollo** (+ **express** se tiver `express`); `express` sozinho → **express**;
33
+ - `fastapi` / `orfeu` em `requirements*.txt`/`pyproject.toml` → **fastapi**, **orfeu**;
34
+ - `Dockerfile` → **docker**; configuração de deploy da plataforma → **hefesto**.
35
+ 3. Sugira **2 ou 3** comandos, cada um com uma linha de motivo tirada do que você leu. Exemplos:
36
+ front sem `.claude/skills/*/scripts` rodados → `/acropole revisar src/app`; mais de um pacote com
37
+ versões diferentes → `/acropole doctor`; serviço Python novo sem rotas → `/acropole endpoint-novo`.
38
+ 4. Mostre a tabela de comandos completa abaixo das sugestões.
39
+
40
+ **Nunca execute um fluxo sozinho.** A sugestão é para o usuário confirmar.
41
+
42
+ ## Descoberta: no pedido aparece… → skills convocadas
43
+
44
+ | No pedido aparece… | Skills, nesta ordem |
45
+ | --- | --- |
46
+ | tela, página, listagem, formulário, modal, menu, rota do app | angular → trismegisto → orfeu → documentacao |
47
+ | manual/README da tela, documentação desatualizada, `ESPECIFICACAO.md` | documentacao |
48
+ | botão, cor, tema, ícone, densidade, `hm-*`, `--hm-*`, acessibilidade de tela | trismegisto (+ angular se mexer em estrutura) |
49
+ | login, sessão, guard, token, "usuário não tem acesso", 401/403 | orfeu (+ angular, express, apollo ou fastapi conforme o lado) |
50
+ | query, mutation, subscription, schema GraphQL, resolver | apollo → orfeu (+ angular para o `.graphql`/codegen no front) |
51
+ | rota REST em Node, middleware, Knex | express → orfeu |
52
+ | serviço Python, rota FastAPI, SQLAlchemy, pytest | fastapi → orfeu |
53
+ | auditoria, operação, `PUBLIC`, `traceparent`, chamada entre serviços | orfeu (+ a skill do serviço) |
54
+ | Dockerfile, imagem, container, `.dockerignore` | docker (+ express/fastapi/angular para a parte de deploy da stack) |
55
+ | deploy, publicar o serviço, Hefesto, ambiente | hefesto → docker |
56
+ | "revisa", "confere", antes de abrir PR | este fluxo `revisar` |
57
+ | versões desalinhadas, "não sobe", configuração estranha | este fluxo `doctor` |
58
+
59
+ Ainda não coberto por nenhuma skill: React, Strawberry, Fastify, Django, Flask. Diga isso ao usuário em
60
+ vez de aplicar por analogia o padrão de outra stack.
61
+
62
+ ## Verificadores e revisores
63
+
64
+ - **Verificadores**: `scripts/checar.mjs` dentro de cada skill (Node, sem dependências). Saída
65
+ `arquivo:linha regra mensagem → correção`, `--json` para máquina, código de saída 1 quando acha algo.
66
+ Ficam em `<pasta desta skill>/../<skill>/scripts/checar.mjs` — normalmente
67
+ `~/.claude/skills/<skill>/scripts/checar.mjs`, ou `./.claude/skills/...` quando instalado com
68
+ `--project`. Achado de verificador é pista: confirme lendo o arquivo.
69
+ - **Subagentes revisores** (instalados em `.claude/agents/` pelo mesmo pacote): `revisor-trismegisto`
70
+ (interface), `revisor-documentacao` (doc das telas contra a tela), `revisor-orfeu`
71
+ (segurança/integração), `revisor-deploy` (Dockerfile/entrega). Só leem e
72
+ relatam; quem corrige é a conversa principal, quando o usuário pedir.
73
+ - **Exceção**: `// acropole-ignore-next-line <regra> -- <motivo>` na linha anterior silencia a regra
74
+ naquela linha. Sem motivo, não vale.
75
+ - **Doctor**: `node <pasta desta skill>/scripts/doctor.mjs [pasta] [--json] [--fix]`.
@@ -0,0 +1,55 @@
1
+ # Fluxo: doctor
2
+
3
+ Diagnóstico de configuração do projeto. É manutenção, não revisão de código: não abra arquivos além dos
4
+ que o relatório cita e não rode nenhum outro fluxo como efeito colateral.
5
+
6
+ ## 1. Rode o diagnóstico
7
+
8
+ ```bash
9
+ node <pasta desta skill>/scripts/doctor.mjs --json [pasta]
10
+ ```
11
+
12
+ Sem `[pasta]`, usa o diretório atual e varre até 4 níveis (ignora `node_modules`, `dist`, `.git`,
13
+ `.angular`, `.venv`). Num monorepo, passe a pasta do app quando o usuário nomear um.
14
+
15
+ O que ele confere:
16
+
17
+ | id | O quê | Severidade |
18
+ | --- | --- | --- |
19
+ | `trismegisto-versoes` | todos os `@trismegisto/*` de um `package.json` na mesma versão (declarada e instalada) | avisa |
20
+ | `orfeu-angular-duplicado` | mais de uma cópia de `@orfeu/angular` em `node_modules` | avisa |
21
+ | `styles-ordem` | no `angular.json`, `tokens.css` antes de `core.css` | corrige |
22
+ | `styles-ausente` | app com `@trismegisto/angular` sem `tokens.css`/`core.css` no `styles` | avisa |
23
+ | `http-interceptors` | `provideHttpClient(...)` sem `withInterceptorsFromDi()` | corrige |
24
+ | `docker-cmd-shell` | `CMD`/`ENTRYPOINT` em forma shell, ou `sh -c` sem `exec` | pergunta |
25
+ | `docker-npmrc` | `.npmrc` copiado/gerado na imagem, ou `COPY . .` com `.npmrc` fora do `.dockerignore` | avisa |
26
+ | `orfeu-python-major` | `orfeu` (Python) em major diferente das libs `@orfeu/*` | avisa |
27
+ | `orfeu-python-sem-versao` | `orfeu` em `requirements*.txt`/`pyproject.toml` sem versão fixa | avisa |
28
+
29
+ Saída em texto: `caminho:linha id mensagem → correção`, agrupada por severidade. `--json`: objeto com
30
+ `root`, `findings[]` (`id`, `severity` = `corrige` | `avisa` | `pergunta`, `path`, `line`, `summary`, `fix`) e
31
+ `fixed[]`. Achado não é erro: o código de saída é 0.
32
+
33
+ Lista vazia é o resultado bom: diga em uma linha e pare.
34
+
35
+ ## 2. Aja pela severidade
36
+
37
+ - **`corrige`** — o ajuste tem uma forma só e não altera nada além do que o achado aponta (reordenar
38
+ `styles`, acrescentar `withInterceptorsFromDi()`). Ainda assim **só aplique a pedido do usuário**
39
+ ("corrige", "pode arrumar"): aí rode `node .../doctor.mjs --fix [pasta]` uma vez e relate em uma linha
40
+ o que mudou. Sem pedido, liste e ofereça.
41
+ - **`avisa`** — o usuário precisa saber; a correção dele envolve install/versão/decisão.
42
+ Uma frase por achado com a correção sugerida. Não rode `npm install`/`pip install`.
43
+ - **`pergunta`** — a correção depende do contexto do projeto. Pergunte se o usuário quer a revisão
44
+ (`/acropole revisar <Dockerfile>`, que chama o `revisor-deploy`) e diga qual lacuna ela fecha. Só rode
45
+ se ele pedir.
46
+
47
+ Relate os três grupos de uma vez.
48
+
49
+ ## 3. Limites
50
+
51
+ - Versão "desalinhada" é comparação de texto de versão; não afirme incompatibilidade de API sem ler o
52
+ changelog.
53
+ - O doctor não lê `.env`, `.npmrc` nem cofre — só verifica se o `.npmrc` entra na imagem.
54
+ - Não sabe qual é a última versão publicada (não faz rede). Para atualizar as skills:
55
+ `npx @acropole/skills@latest`; para ver o que está instalado: `npx @acropole/skills --status`.
@@ -0,0 +1,22 @@
1
+ # Fluxo: endpoint novo
2
+
3
+ Rota REST ou Query/Mutation nova num serviço. A estrutura vem da skill do serviço; proteção, auditoria
4
+ e propagação vêm da **orfeu**. Abra a seção indicada antes de escrever.
5
+
6
+ Confirme antes: qual serviço (Apollo, Express ou FastAPI), o recurso, o verbo (leitura, escrita,
7
+ remoção, stream), quem pode executar (público, autenticado, protegido) e se o endpoint chama outro
8
+ serviço próprio ou um terceiro.
9
+
10
+ | # | Passo | Skill | Onde |
11
+ | --- | --- | --- | --- |
12
+ | 1 | **Esqueleto** da rota/resolver nas camadas do serviço (router fino → service → repository; no Apollo, resolver fino que chama o serviço de trás e devolve o envelope como veio) | fastapi / express / apollo | `SKILL.md` "Esqueleto…" de cada uma |
13
+ | 2 | **Operação do Orfeu**: `identifier` + `Method` explícito + `Level`, declarada **antes** da subida. `PUBLIC` só com motivo em comentário | orfeu | `SKILL.md` §2–§3; `references/diferencas.md` se houver Node e Python |
14
+ | 3 | **Propagação**: chamada a serviço próprio com `orfeuHeaders(req|ctx)` / `orfeu_headers(request)` (leva `x-access-token`, `traceparent`, `x-route-id`, `x-client-id`). Terceiro: **sem** esses helpers. Como o próprio serviço: `credential: false` | orfeu | `SKILL.md` §1, `references/node.md` / `references/python.md` |
15
+ | 4 | **Auditoria**: `annotateOperation` / `annotate_operation` com `target_type`, `target_id` e `details` (≤ 4 KB, sem segredo nem dado pessoal sensível). Um evento por serviço | orfeu | `SKILL.md` §5 |
16
+ | 5 | **Envelope e erros** no formato do serviço (`{ status, message, data }`; erros do Orfeu no service) | fastapi / apollo / express | `references/rotas-erros.md` / `references/envelope-erros.md` |
17
+ | 6 | **Teste**: caminho feliz, 401 (sem credencial), 403 (sem permissão) e o erro de negócio principal, com o Orfeu simulado | fastapi / express / apollo + orfeu | `references/testes-*.md`; orfeu recipes "testes" |
18
+ | 7 | **Front** (se houver): `.graphql` + codegen + service — continue no fluxo [tela-nova](tela-nova.md) a partir do passo 3 | angular | — |
19
+ | 8 | **Revisão**: fluxo [revisar](revisar.md) com o `revisor-orfeu` | acropole | — |
20
+
21
+ Fora do código, avise o usuário: quem pode executar uma operação `protected` é configurado **no Argos**
22
+ (grupos), não no código; sem isso a operação nasce negando para todos.
@@ -0,0 +1,56 @@
1
+ # Fluxo: revisar
2
+
3
+ Revisão do que mudou (ou do caminho indicado) com os verificadores das skills e os subagentes
4
+ revisores. **Só relata.** Não corrija nada sem o usuário pedir — nem "de passagem".
5
+
6
+ ## 1. Alvo
7
+
8
+ - Com argumento: o caminho indicado.
9
+ - Sem argumento: os arquivos alterados (`git diff --name-only` e `git status --porcelain`, só leitura).
10
+ Sem git ou sem mudança: pergunte o alvo.
11
+
12
+ ## 2. Verificadores (por tipo de arquivo)
13
+
14
+ Rode só os que se aplicam, cada um uma vez, com `--json`. Procure em `./.claude/skills/<skill>/scripts/`
15
+ e depois em `~/.claude/skills/<skill>/scripts/`.
16
+
17
+ | Arquivos | Verificadores |
18
+ | --- | --- |
19
+ | `.html`, `.scss`, componente `.ts` de app Angular | `trismegisto`, `angular` |
20
+ | tela, rota (`features.routes.ts`) ou `.md` de feature Angular | `documentacao` (sobre a pasta do app) |
21
+ | `.ts` de servidor com `@apollo/server` | `apollo`, `orfeu` |
22
+ | `.ts` de servidor Express | `express`, `orfeu` |
23
+ | `.py` de serviço FastAPI | `fastapi`, `orfeu` |
24
+ | `Dockerfile`, `.dockerignore` | `docker` |
25
+ | configuração de deploy da plataforma | `hefesto` |
26
+
27
+ ```bash
28
+ node ~/.claude/skills/<skill>/scripts/checar.mjs --json <arquivos>
29
+ ```
30
+
31
+ Código de saída 1 = achou algo (não é falha do comando). Verificador ausente: registre em uma linha e
32
+ siga. Linhas com `acropole-ignore-next-line <regra> -- <motivo>` já saem filtradas.
33
+
34
+ ## 3. Revisores
35
+
36
+ Chame em paralelo, só os que se aplicam, passando a lista de arquivos e o JSON dos verificadores:
37
+
38
+ - `revisor-trismegisto` — houve arquivo de interface;
39
+ - `revisor-documentacao` — houve tela ou rota alterada, ou o verificador `documentacao` acusou algo
40
+ (ele confere a doc contra a tela; o registro da revisão fica para depois, com o usuário);
41
+ - `revisor-orfeu` — houve rota, resolver, chamada entre serviços, auditoria ou sessão no front;
42
+ - `revisor-deploy` — houve Dockerfile/deploy.
43
+
44
+ Eles confirmam cada achado lendo o arquivo. Achado de verificador que o revisor não confirmou sai do
45
+ relatório (falso positivo).
46
+
47
+ ## 4. Relatório
48
+
49
+ Um bloco por área (Interface, Documentação, Orfeu, Deploy), em ordem de gravidade, um achado por linha:
50
+
51
+ ```
52
+ caminho:linha problema → correção
53
+ ```
54
+
55
+ Sem achados numa área: uma linha. No fim, pergunte se o usuário quer que você corrija — tudo, só os
56
+ graves, ou nada.
@@ -0,0 +1,27 @@
1
+ # Fluxo: tela nova
2
+
3
+ Tela Angular de ponta a ponta. Cada passo diz **qual skill manda**; os detalhes (nomes de API, exemplos,
4
+ armadilhas) estão nela — abra a seção indicada em vez de escrever de memória.
5
+
6
+ Antes de começar, confirme com o usuário: nome da tela, o que ela lista/edita, quais dados vêm de qual
7
+ serviço, e se o `router_id` já existe no Argos. Não invente `router_id`, nome de operação nem campo de
8
+ schema.
9
+
10
+ | # | Passo | Skill | Onde |
11
+ | --- | --- | --- | --- |
12
+ | 1 | **Roteador no Argos**: cadastrar o roteador do client (com descrição) 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` |
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
+ | 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
+ | 4 | **Service** `providedIn: 'root'` com `injectGraphqlClient` + `unwrap`; erro vira estado da tela | angular | `SKILL.md` "Dados", `references/dados.md` |
16
+ | 5 | **Componente** standalone, OnPush, signals; interface **só** com `hm-*` e tokens `--hm-*`; ícones do catálogo; a11y (label, `intent="danger"`, `(clicked)`) | angular → trismegisto | trismegisto `SKILL.md` §3 e `references/angular.md` §4 ("Preciso de… / Use"), `references/angular-api.md` |
17
+ | 6 | **Registro** em `features.routes.ts` com `id` = `router_id` e `load` lazy | angular | `references/features.md` |
18
+ | 7 | **Sessão e headers**: nada a fazer se o app já tem `provideAuth` e `provideHttpClient(withInterceptorsFromDi())`; confira | orfeu | orfeu `references/angular.md` |
19
+ | 8 | **Testes**: componente por harness (`@trismegisto/angular/testing`), service com cliente simulado; `lint:a11y` | angular + trismegisto | angular `references/testes-build.md`, trismegisto §3.7 |
20
+ | 9 | **Documentação**: `README.md` (e `ESPECIFICACAO.md`, se houver regra a registrar) na pasta da tela, ligado em `document` na rota; verificador da skill sem achados e revisão registrada | documentacao | `SKILL.md` §2–§4, `references/modelo-readme.md` |
21
+ | 10 | **Revisão**: rode o fluxo [revisar](revisar.md) sobre os arquivos novos | acropole | — |
22
+
23
+ Ordem importa: o passo 2 antes do 3 (o codegen precisa do schema), o 5 antes do 6 (registro aponta para
24
+ o componente), o 9 depois do 5 (o README cita os rótulos que estão no template). Se o backend for de outra pessoa/equipe, pare no passo 2 e diga o que falta.
25
+
26
+ Ao terminar, liste os arquivos criados/alterados e o que o usuário precisa fazer fora do código
27
+ (cadastro no Argos, permissão da operação para os grupos no Argos).