@jordyfontoura/skills 0.2.0 → 0.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 CHANGED
@@ -63,9 +63,9 @@ um guia compartilhado, o conflito interrompe toda a instalação antes de gravar
63
63
  incluem os hashes da biblioteca; `status` identifica alterações e ausências nos mesmos guias
64
64
  usados pelos dois agentes. Remover uma skill não deve remover guias usados por outras.
65
65
 
66
- O layout compartilhado é próprio do CLI. O plugin continua usando `knowledge/` na origem;
67
- as cópias manuais em `.agents/skills/` e `.claude/skills/` continuam autocontidas, com guias
68
- em `references/knowledge/`. O CLI não migra automaticamente uma instalação anterior: use
66
+ O CLI usa o namespace `knowledge/harness/`. O plugin e as cópias manuais em `.agents/skills/`
67
+ e `.claude/skills/` usam `knowledge/` na raiz; na adoção manual, copie também essa biblioteca.
68
+ O CLI não migra automaticamente uma instalação anterior: use
69
69
  `atualizar-harness` para comparar adaptações e ajustar os links antes de retirar cópias antigas.
70
70
 
71
71
  ## Escolher conteúdo
@@ -74,9 +74,8 @@ Escolha Codex, Claude Code ou ambos. Diretórios existentes sugerem os agentes,
74
74
  escolha continua editável. Você pode receber recomendações por práticas, escolher no
75
75
  catálogo ou consultar as instruções do plugin completo.
76
76
 
77
- As recomendações começam com `implementar`, `escrever-claro` e `esclarecer`, e acrescentam
78
- skills conforme suas escolhas: aprovação da abordagem, execução direta quando solicitada,
79
- retomada entre sessões, PRs e revisão, pesquisa e requisitos, aceite independente e interfaces.
77
+ As recomendações começam com `implementar` e `redigir`, e acrescentam
78
+ skills conforme suas escolhas: aprovação da abordagem, retomada entre sessões, PRs e revisão, pesquisa e requisitos, aceite independente e interfaces.
80
79
  Você pode desmarcar qualquer recomendação na seleção final.
81
80
 
82
81
  Os papéis `planner`, `evaluator` e `representative` são opcionais. Cada papel acrescenta as
@@ -150,6 +149,10 @@ Arquivos `.env` não são aceitos como configuração. Exemplo de JSON, com IDs
150
149
  }
151
150
  ```
152
151
 
152
+ O objeto também pode trazer a seção opcional `ladders`, com as escadas de `subir-regua`.
153
+ O formato está no [guia de modelos](../docs/MODELS.md#escadas-de-subir-regua); as perguntas
154
+ interativas não criam escadas.
155
+
153
156
  Para gerar a política sem perguntas:
154
157
 
155
158
  ```bash
package/dist/catalog.js CHANGED
@@ -4,9 +4,8 @@ if (payload.schemaVersion !== 2)
4
4
  throw new Error('Versão de catálogo não suportada.');
5
5
  export const scenarios = [
6
6
  { value: 'approval', label: 'Avaliar a abordagem antes de alterar', skills: ['propor', 'entrevistar'] },
7
- { value: 'direct', label: 'Executar direto quando eu pedir', skills: ['fazer-direto'] },
8
7
  { value: 'sessions', label: 'Retomar trabalhos entre sessões', skills: ['passar-contexto', 'andamento'] },
9
- { value: 'reviews', label: 'Trabalhar com PRs e revisões', skills: ['revisar', 'tratar-revisao', 'descrever-pr', 'integrar'] },
8
+ { value: 'reviews', label: 'Trabalhar com PRs e revisões', skills: ['revisar', 'tratar-revisao', 'integrar'] },
10
9
  { value: 'decisions', label: 'Definir requisitos e pesquisar decisões', skills: ['especificar', 'pesquisar-web', 'conselho', 'delegar'] },
11
10
  { value: 'acceptance', label: 'Delegar e verificar o aceite independentemente', skills: ['verificar-aceite', 'delegar', 'escrever-objetivo'] },
12
11
  { value: 'interface', label: 'Experimentar e avaliar interfaces', skills: ['criticar', 'prototipar'] },
@@ -27,7 +26,7 @@ for (const name of [...scenarios.flatMap(s => s.skills), ...Object.values(roleSk
27
26
  throw new Error(`Recomendação aponta para skill ausente: ${name}`);
28
27
  }
29
28
  export function recommend(choices) {
30
- return [...new Set(['implementar', 'escrever-claro', 'esclarecer',
29
+ return [...new Set(['implementar', 'redigir',
31
30
  ...scenarios.filter(s => choices.includes(s.value)).flatMap(s => s.skills)])];
32
31
  }
33
32
  export function selectSkills(skills, roles) {
@@ -46,7 +45,7 @@ export function instructions(skills) {
46
45
  'verificar-aceite': 'Use `verificar-aceite` quando for exigido aceite em contexto independente.',
47
46
  delegar: 'Delegue apenas trabalho autorizado; configurar papéis não autoriza consultas.',
48
47
  'passar-contexto': 'Use `passar-contexto` quando outra sessão precisar retomar o trabalho.',
49
- 'escrever-claro': 'Aplique `escrever-claro` ao redigir textos para leitores.',
48
+ redigir: 'Aplique `redigir` ao escrever ou revisar textos para leitores.',
50
49
  'consultar-conhecimento': 'Use `consultar-conhecimento` para localizar os guias pertinentes na [biblioteca compartilhada](knowledge/harness/README.md), sem carregar todos de uma vez.',
51
50
  };
52
51
  for (const [name, rule] of Object.entries(rules))
package/dist/policy.js CHANGED
@@ -13,6 +13,16 @@ function identifier(value, location) {
13
13
  if (typeof value !== 'string' || value !== value.trim() || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value))
14
14
  throw new Error(`${location}: nome inválido`);
15
15
  }
16
+ function target(candidate, at, concrete) {
17
+ table(candidate, at);
18
+ fields(candidate, ['provider', 'model', 'effort'], ['provider', 'model', 'effort'], at);
19
+ for (const key of ['provider', 'model', 'effort'])
20
+ text(candidate[key], `${at}.${key}`);
21
+ if ((candidate.provider === 'inherit') !== (candidate.model === 'inherit'))
22
+ throw new Error(`${at}: provider e model devem ser herdados ou definidos juntos`);
23
+ if (concrete && candidate.model === 'inherit')
24
+ throw new Error(`${at}: uma alternativa deve identificar provider e model concretos`);
25
+ }
16
26
  function text(value, location, trimmed = true) {
17
27
  // Mesmos espaços de str.strip() no Python; String.trim() trata BOM e U+0085 de outro modo.
18
28
  const strip = (input) => input.replace(/^[\u0009-\u000d\u001c-\u0020\u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]+|[\u0009-\u000d\u001c-\u0020\u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]+$/g, '');
@@ -25,11 +35,38 @@ function text(value, location, trimmed = true) {
25
35
  throw new Error(`${location}: caractere Unicode inválido`);
26
36
  }
27
37
  }
38
+ function validateLadders(ladders) {
39
+ table(ladders, 'ladders');
40
+ if (!Object.keys(ladders).length)
41
+ throw new Error('ladders: deve conter ao menos uma escada');
42
+ for (const [name, ladder] of Object.entries(ladders)) {
43
+ const location = `ladders.${name}`;
44
+ identifier(name, location);
45
+ table(ladder, location);
46
+ fields(ladder, ['when', 'max_cycles', 'stages'], ['when', 'stages'], location);
47
+ text(ladder.when, `${location}.when`, false);
48
+ if (Object.hasOwn(ladder, 'max_cycles') && (!Number.isSafeInteger(ladder.max_cycles) || ladder.max_cycles < 1)) {
49
+ throw new Error(`${location}.max_cycles: deve ser um inteiro positivo`);
50
+ }
51
+ if (!Array.isArray(ladder.stages) || !ladder.stages.length)
52
+ throw new Error(`${location}.stages: deve conter uma lista não vazia`);
53
+ const seen = new Set();
54
+ for (const [index, stage] of ladder.stages.entries()) {
55
+ target(stage, `${location}.stages[${index}]`, true);
56
+ const key = JSON.stringify([stage.provider, stage.model, stage.effort]);
57
+ if (seen.has(key))
58
+ throw new Error(`${location}.stages: etapa repetida`);
59
+ seen.add(key);
60
+ }
61
+ }
62
+ }
28
63
  export function validatePolicyV2(value) {
29
64
  table(value, 'política');
30
65
  if (value.version !== 2)
31
66
  throw new Error('política.version: o gerador aceita somente a versão 2; arquivos v1 existentes são preservados');
32
- fields(value, ['version', 'profiles', 'roles'], ['version', 'profiles', 'roles'], 'política');
67
+ fields(value, ['version', 'profiles', 'roles', 'ladders'], ['version', 'profiles', 'roles'], 'política');
68
+ if (Object.hasOwn(value, 'ladders'))
69
+ validateLadders(value.ladders);
33
70
  table(value.profiles, 'profiles');
34
71
  const profiles = value.profiles;
35
72
  if (!Object.keys(profiles).length)
@@ -43,15 +80,7 @@ export function validatePolicyV2(value) {
43
80
  throw new Error(`${location}.candidates: deve conter uma lista não vazia`);
44
81
  const seen = new Set();
45
82
  for (const [index, candidate] of profile.candidates.entries()) {
46
- const at = `${location}.candidates[${index}]`;
47
- table(candidate, at);
48
- fields(candidate, ['provider', 'model', 'effort'], ['provider', 'model', 'effort'], at);
49
- for (const key of ['provider', 'model', 'effort'])
50
- text(candidate[key], `${at}.${key}`);
51
- if ((candidate.provider === 'inherit') !== (candidate.model === 'inherit'))
52
- throw new Error(`${at}: provider e model devem ser herdados ou definidos juntos`);
53
- if (index > 0 && candidate.model === 'inherit')
54
- throw new Error(`${at}: uma alternativa deve identificar provider e model concretos`);
83
+ target(candidate, `${location}.candidates[${index}]`, index > 0);
55
84
  const key = JSON.stringify([candidate.provider, candidate.model, candidate.effort]);
56
85
  if (seen.has(key))
57
86
  throw new Error(`${location}: alternativa repetida`);
@@ -108,5 +137,14 @@ export function serializePolicy(policy) {
108
137
  }
109
138
  lines.push('');
110
139
  }
140
+ for (const [name, ladder] of Object.entries(policy.ladders ?? {})) {
141
+ lines.push(`[ladders.${name}]`, `when = ${quote(ladder.when)}`);
142
+ if (ladder.max_cycles !== undefined)
143
+ lines.push(`max_cycles = ${ladder.max_cycles}`);
144
+ lines.push('stages = [');
145
+ for (const stage of ladder.stages)
146
+ lines.push(` { provider = ${quote(stage.provider)}, model = ${quote(stage.model)}, effort = ${quote(stage.effort)} },`);
147
+ lines.push(']', '');
148
+ }
111
149
  return lines.join('\n');
112
150
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jordyfontoura/skills",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "description": "Adoção guiada de skills e papéis de engenharia em português.",
5
5
  "license": "Apache-2.0",
6
6
  "type": "module",