@spec-wave/cli 1.7.6 → 1.9.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 +1 -1
- package/package.json +1 -1
- package/src/agent/errors.mjs +31 -1
- package/src/agent/openrouter-agent.mjs +25 -2
- package/src/api/github-graphql.mjs +31 -0
- package/src/api/github-rest.mjs +20 -0
- package/src/cli.mjs +103 -36
- package/src/commands/auth-check.mjs +72 -0
- package/src/commands/decompose.mjs +14 -2
- package/src/commands/doctor.mjs +139 -2
- package/src/commands/generate-bug.mjs +6 -6
- package/src/commands/generate-plan.mjs +9 -8
- package/src/commands/generate-qa-plan.mjs +9 -6
- package/src/commands/generate-spec.mjs +12 -7
- package/src/commands/implement.mjs +21 -0
- package/src/commands/init.mjs +2 -2
- package/src/commands/preflight.mjs +38 -2
- package/src/commands/progress.mjs +144 -0
- package/src/commands/relink.mjs +105 -0
- package/src/commands/report-failure.mjs +99 -0
- package/src/commands/retry.mjs +91 -0
- package/src/commands/task.mjs +5 -0
- package/src/commands/update.mjs +70 -0
- package/src/config.mjs +8 -8
- package/src/lib/cited-paths.mjs +89 -0
- package/src/lib/claude.mjs +4 -2
- package/src/lib/cli-line.mjs +153 -0
- package/src/lib/cli-ref.mjs +53 -2
- package/src/lib/failure-report.mjs +319 -0
- package/src/lib/progress-events.mjs +46 -0
- package/src/lib/repo-identity.mjs +55 -0
- package/src/lib/spec-index.mjs +114 -0
- package/src/lib/tech-context.mjs +144 -5
- package/src/plugin/.claude-plugin/plugin.json +1 -1
- package/src/plugin/skills/plan/SKILL.md +1 -1
- package/src/plugin/skills/plan/reference/tech-context.md +12 -4
- package/src/plugin/skills/setup/SKILL.md +1 -1
- package/src/plugin/skills/spec/model-prompt.md +8 -1
- package/src/plugins/scm-github/index.mjs +8 -1
- package/src/plugins/tracker-github-projects/index.mjs +11 -4
- package/src/ports/tracker.mjs +2 -1
- package/src/setup/labels.mjs +5 -3
- package/src/setup/project.mjs +5 -3
- package/src/templates/config/tech_context.yml +29 -25
- package/src/templates/skill/SKILL.md +27 -9
- package/src/templates/skill/core.md +25 -7
- package/src/templates/workflows/code-review.yml +1 -0
- package/src/templates/workflows/critique.yml +11 -0
- package/src/templates/workflows/decompose.yml +27 -0
- package/src/templates/workflows/generate-bug.yml +26 -0
- package/src/templates/workflows/generate-plan.yml +26 -0
- package/src/templates/workflows/generate-qa-plan.yml +27 -0
- package/src/templates/workflows/generate-spec.yml +26 -0
- package/src/templates/workflows/pr-events.yml +5 -0
- package/src/templates/workflows/qa.yml +1 -0
- package/src/templates/workflows/validate.yml +11 -0
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
// Índice das specs vizinhas, entregue PRONTO ao modelo do `generate-spec`.
|
|
2
|
+
//
|
|
3
|
+
// Existe por causa de um padrão medido: num hub com ~24 specs em
|
|
4
|
+
// `docs/features/`, três Features falharam 12 vezes com `error_max_turns`
|
|
5
|
+
// (Read×27–29, Glob×5–12, nenhuma escrita). O prompt mandava "procurar specs
|
|
6
|
+
// vizinhas" e o modelo tentava ler TODAS antes de escrever a primeira linha.
|
|
7
|
+
// O que ele procurava em cada uma era quase sempre o mesmo: do que aquela
|
|
8
|
+
// Feature trata e de quem ela depende. Isso cabe num índice — e o índice custa
|
|
9
|
+
// zero turnos.
|
|
10
|
+
//
|
|
11
|
+
// O índice NÃO substitui a leitura: é o mapa para o modelo escolher as poucas
|
|
12
|
+
// specs que valem um `Read` inteiro.
|
|
13
|
+
|
|
14
|
+
import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
|
|
15
|
+
import path from 'node:path';
|
|
16
|
+
|
|
17
|
+
import { dependencySection } from './spec-audit.mjs';
|
|
18
|
+
|
|
19
|
+
export const SPEC_INDEX_DIR = 'docs/features';
|
|
20
|
+
|
|
21
|
+
// Tetos: o índice é para caber no prompt sem competir com a issue.
|
|
22
|
+
const MAX_ENTRIES = 80;
|
|
23
|
+
const MAX_OBJETIVO = 240;
|
|
24
|
+
const MAX_DEPS = 600;
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* Objetivo declarado na Visão Geral (função PURA): a linha do bullet
|
|
28
|
+
* "Objetivo", ou o primeiro parágrafo da seção quando o bullet não existe.
|
|
29
|
+
*
|
|
30
|
+
* @param {string} markdown
|
|
31
|
+
* @returns {string}
|
|
32
|
+
*/
|
|
33
|
+
export function specObjective(markdown = '') {
|
|
34
|
+
const linhas = String(markdown).split('\n');
|
|
35
|
+
const bullet = linhas.find(l => /^\s*[-*]\s*\**objetivo\**\s*:?/i.test(l));
|
|
36
|
+
if (bullet) return compactar(bullet.replace(/^\s*[-*]\s*\**objetivo\**\s*:?\**\s*/i, ''), MAX_OBJETIVO);
|
|
37
|
+
const inicio = linhas.findIndex(l => /^#\s+vis[aã]o geral/i.test(l.trim()));
|
|
38
|
+
if (inicio === -1) return '';
|
|
39
|
+
const corpo = [];
|
|
40
|
+
for (const l of linhas.slice(inicio + 1)) {
|
|
41
|
+
if (/^#{1,6}\s/.test(l)) break;
|
|
42
|
+
if (!l.trim()) { if (corpo.length) break; continue; }
|
|
43
|
+
corpo.push(l.trim());
|
|
44
|
+
}
|
|
45
|
+
return compactar(corpo.join(' '), MAX_OBJETIVO);
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
function compactar(texto, max) {
|
|
49
|
+
const limpo = String(texto).replace(/\s+/g, ' ').trim();
|
|
50
|
+
return limpo.length > max ? `${limpo.slice(0, max - 1)}…` : limpo;
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/**
|
|
54
|
+
* Entradas do índice a partir do disco. Nunca lança: diretório ausente ou
|
|
55
|
+
* arquivo ilegível somem do índice (o modelo ainda tem `Glob` para achar).
|
|
56
|
+
*
|
|
57
|
+
* @param {string} root raiz do hub
|
|
58
|
+
* @param {{excludeSlug?: string}} [opts] a própria Feature fica de fora
|
|
59
|
+
* @returns {Array<{path: string, objetivo: string, dependencias: string}>}
|
|
60
|
+
*/
|
|
61
|
+
export function collectSpecIndex(root, { excludeSlug = null } = {}) {
|
|
62
|
+
const base = path.join(root || process.cwd(), SPEC_INDEX_DIR);
|
|
63
|
+
if (!existsSync(base)) return [];
|
|
64
|
+
let slugs;
|
|
65
|
+
try {
|
|
66
|
+
slugs = readdirSync(base).filter(s => s !== excludeSlug).sort();
|
|
67
|
+
} catch {
|
|
68
|
+
return [];
|
|
69
|
+
}
|
|
70
|
+
const entradas = [];
|
|
71
|
+
for (const slug of slugs) {
|
|
72
|
+
const abs = path.join(base, slug, 'spec.md');
|
|
73
|
+
try {
|
|
74
|
+
if (!statSync(abs).isFile()) continue;
|
|
75
|
+
const md = readFileSync(abs, 'utf-8');
|
|
76
|
+
const deps = dependencySection(md);
|
|
77
|
+
entradas.push({
|
|
78
|
+
path: `${SPEC_INDEX_DIR}/${slug}/spec.md`,
|
|
79
|
+
objetivo: specObjective(md),
|
|
80
|
+
dependencias: deps == null ? '' : compactar(deps.replace(/^#{1,6}\s+/gm, ''), MAX_DEPS),
|
|
81
|
+
});
|
|
82
|
+
} catch {
|
|
83
|
+
// spec.md ausente ou ilegível nesta Feature — segue sem ela
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
return entradas;
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/**
|
|
90
|
+
* Seção markdown do índice para o prompt (função PURA). Vazio quando não há
|
|
91
|
+
* spec vizinha — aí a seção nem aparece.
|
|
92
|
+
*
|
|
93
|
+
* @param {Array<{path: string, objetivo: string, dependencias: string}>} entradas
|
|
94
|
+
* @returns {string}
|
|
95
|
+
*/
|
|
96
|
+
export function renderSpecIndex(entradas = []) {
|
|
97
|
+
if (!entradas.length) return '';
|
|
98
|
+
const mostradas = entradas.slice(0, MAX_ENTRIES);
|
|
99
|
+
const linhas = [
|
|
100
|
+
'## Índice das specs existentes',
|
|
101
|
+
'',
|
|
102
|
+
`${entradas.length} spec(s) em \`${SPEC_INDEX_DIR}/\`. Use este índice para decidir quais ` +
|
|
103
|
+
'poucas valem um `Read` — não abra todas.',
|
|
104
|
+
'',
|
|
105
|
+
];
|
|
106
|
+
for (const e of mostradas) {
|
|
107
|
+
linhas.push(`- \`${e.path}\` — ${e.objetivo || '(sem objetivo declarado)'}`);
|
|
108
|
+
if (e.dependencias) linhas.push(` - Dependências: ${e.dependencias}`);
|
|
109
|
+
}
|
|
110
|
+
if (entradas.length > mostradas.length) {
|
|
111
|
+
linhas.push('', `(+${entradas.length - mostradas.length} spec(s) fora do índice — use \`Grep\` para achá-las.)`);
|
|
112
|
+
}
|
|
113
|
+
return linhas.join('\n');
|
|
114
|
+
}
|
package/src/lib/tech-context.mjs
CHANGED
|
@@ -21,6 +21,135 @@ const MIGRATION_DIRS = [
|
|
|
21
21
|
|
|
22
22
|
const MAX_MIGRATIONS = 10;
|
|
23
23
|
|
|
24
|
+
// Marcador do scaffold. O `init` grava o template com ele na primeira linha, e
|
|
25
|
+
// enquanto ele existir o arquivo é um FORMULÁRIO, não a descrição do sistema.
|
|
26
|
+
export const TECH_CONTEXT_TEMPLATE_MARKER = 'spec-wave:template';
|
|
27
|
+
|
|
28
|
+
// O marcador só vale ONDE o scaffold o grava: como comentário que abre o
|
|
29
|
+
// arquivo. Casar a string em qualquer lugar bloqueava um arquivo preenchido que
|
|
30
|
+
// apenas a citasse ("# removi o spec-wave:template em 03/11").
|
|
31
|
+
const MARKER_LINE = new RegExp(`^#\\s*${TECH_CONTEXT_TEMPLATE_MARKER}(?![\\w-])`);
|
|
32
|
+
|
|
33
|
+
function hasTemplateMarker(raw) {
|
|
34
|
+
const primeira = String(raw).replace(/^/, '').split(/\r?\n/)
|
|
35
|
+
.find((l) => l.trim() !== '' && l.trim() !== '---');
|
|
36
|
+
return primeira !== undefined && MARKER_LINE.test(primeira.trim());
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
// Algum valor de verdade no YAML? String em branco, lista vazia e null não
|
|
40
|
+
// contam. `system_info.name` também não: o nome do sistema sozinho não descreve
|
|
41
|
+
// stack nenhum, e é o primeiro (às vezes o único) campo que alguém preenche.
|
|
42
|
+
function hasContent(value, caminho = '') {
|
|
43
|
+
if (value == null) return false;
|
|
44
|
+
if (typeof value === 'string') return value.trim() !== '';
|
|
45
|
+
if (Array.isArray(value)) return value.some((v) => hasContent(v, `${caminho}[]`));
|
|
46
|
+
if (typeof value === 'object') {
|
|
47
|
+
return Object.entries(value).some(([k, v]) => {
|
|
48
|
+
const filho = caminho ? `${caminho}.${k}` : k;
|
|
49
|
+
return filho !== 'system_info.name' && hasContent(v, filho);
|
|
50
|
+
});
|
|
51
|
+
}
|
|
52
|
+
return true; // número, booleano, data
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* Por que o tech_context não conta como preenchido — ou `null` se conta.
|
|
57
|
+
* (função PURA)
|
|
58
|
+
*
|
|
59
|
+
* Três formas de não estar preenchido, e as três aconteceram ou são um passo
|
|
60
|
+
* óbvio de quem segue a instrução do próprio scaffold:
|
|
61
|
+
* • `marker` — a linha `# spec-wave:template` ainda abre o arquivo;
|
|
62
|
+
* • `legacy-example` — o EXEMPLO dos scaffolds anteriores, "Order Management
|
|
63
|
+
* System" em NestJS, PostgreSQL e Redis. Ele era sintaticamente perfeito, e
|
|
64
|
+
* foi lido como verdade: num cliente cujo stack é Kotlin Multiplatform +
|
|
65
|
+
* Amplify, as specs e os planos saíram falando de Postgres, Redis e
|
|
66
|
+
* microsserviços, porque ninguém editou o arquivo e nada avisou;
|
|
67
|
+
* • `empty` — nenhum campo além do nome tem valor. É o que sobra quando só a
|
|
68
|
+
* linha do marcador é apagada: sem este critério, `backend: ""` e
|
|
69
|
+
* `rbac_roles: []` entravam no prompt como contexto com autoridade.
|
|
70
|
+
*
|
|
71
|
+
* Um arquivo PREENCHIDO pelo time que por acaso mantenha um valor do exemplo
|
|
72
|
+
* não é template: o critério do exemplo é o par nome + backend, que só
|
|
73
|
+
* coincide se ninguém tocou na seção.
|
|
74
|
+
*
|
|
75
|
+
* @param {string|null} raw texto do arquivo
|
|
76
|
+
* @param {object|null} [parsed] o YAML já parseado (evita parsear duas vezes)
|
|
77
|
+
* @returns {'marker'|'legacy-example'|'empty'|null}
|
|
78
|
+
*/
|
|
79
|
+
export function techContextTemplateReason(raw, parsed = undefined) {
|
|
80
|
+
if (raw == null) return null;
|
|
81
|
+
if (hasTemplateMarker(raw)) return 'marker';
|
|
82
|
+
let ctx = parsed;
|
|
83
|
+
if (ctx === undefined) {
|
|
84
|
+
try { ctx = yaml.load(String(raw)); } catch { return null; }
|
|
85
|
+
}
|
|
86
|
+
const info = ctx?.system_info;
|
|
87
|
+
if (info?.name === 'Order Management System' &&
|
|
88
|
+
info?.stack?.backend === 'Node.js (NestJS v10)') return 'legacy-example';
|
|
89
|
+
return hasContent(ctx) ? null : 'empty';
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/** O tech_context ainda é o template do scaffold? Ver `techContextTemplateReason`. */
|
|
93
|
+
export function isTechContextTemplate(raw, parsed = undefined) {
|
|
94
|
+
return techContextTemplateReason(raw, parsed) !== null;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
// Uma leitura, um parse: estado + conteúdo. `inspectTechContext` devolve só o
|
|
98
|
+
// estado; `readStaticContext` aproveita o `context` em vez de reler o arquivo.
|
|
99
|
+
function readTechContext(cwd) {
|
|
100
|
+
const base = { path: TECH_CONTEXT_PATH, reason: null, error: null, context: null };
|
|
101
|
+
const filePath = path.join(cwd, TECH_CONTEXT_PATH);
|
|
102
|
+
if (!existsSync(filePath)) return { ...base, state: 'missing' };
|
|
103
|
+
let raw;
|
|
104
|
+
let parsed;
|
|
105
|
+
try {
|
|
106
|
+
raw = readFileSync(filePath, 'utf-8');
|
|
107
|
+
parsed = yaml.load(raw);
|
|
108
|
+
} catch (err) {
|
|
109
|
+
return { ...base, state: 'invalid', error: err.message };
|
|
110
|
+
}
|
|
111
|
+
const reason = techContextTemplateReason(raw, parsed);
|
|
112
|
+
if (reason) return { ...base, state: 'template', reason };
|
|
113
|
+
return { ...base, state: 'filled', context: parsed };
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
/**
|
|
117
|
+
* Estado do tech_context no disco: `missing` | `invalid` | `template` | `filled`.
|
|
118
|
+
* `reason` só vem em `template` (ver `techContextTemplateReason`). Nunca lança.
|
|
119
|
+
*
|
|
120
|
+
* @param {string} [cwd]
|
|
121
|
+
* @returns {{state: 'missing'|'invalid'|'template'|'filled', path: string,
|
|
122
|
+
* reason: 'marker'|'legacy-example'|'empty'|null, error: string|null}}
|
|
123
|
+
*/
|
|
124
|
+
export function inspectTechContext(cwd = process.cwd()) {
|
|
125
|
+
const { state, path: p, reason, error } = readTechContext(cwd);
|
|
126
|
+
return { state, path: p, reason, error };
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
/**
|
|
130
|
+
* Texto de orientação quando o arquivo não está preenchido (uma fonte só).
|
|
131
|
+
* O que fazer depende do motivo: mandar apagar a linha do marcador num arquivo
|
|
132
|
+
* antigo, que nunca a teve, deixa o usuário procurando o que não existe.
|
|
133
|
+
*
|
|
134
|
+
* @param {'marker'|'legacy-example'|'empty'|null} [reason]
|
|
135
|
+
*/
|
|
136
|
+
export function techContextTemplateHint(reason = 'marker') {
|
|
137
|
+
const stack = 'o stack REAL do sistema (backend, frontend, banco, infra, autenticação)';
|
|
138
|
+
const fim = ' Enquanto isso, spec e plan são gerados SEM contexto técnico estático — ' +
|
|
139
|
+
'o conteúdo do template nunca é injetado.';
|
|
140
|
+
if (reason === 'legacy-example') {
|
|
141
|
+
return `${TECH_CONTEXT_PATH} ainda traz o EXEMPLO dos scaffolds antigos ` +
|
|
142
|
+
`("Order Management System" em NestJS) (não preenchido): substitua-o por ${stack}.` + fim;
|
|
143
|
+
}
|
|
144
|
+
if (reason === 'empty') {
|
|
145
|
+
return `${TECH_CONTEXT_PATH} está com os campos em branco (não preenchido): ` +
|
|
146
|
+
`descreva ${stack} — só o nome do sistema não basta.` + fim;
|
|
147
|
+
}
|
|
148
|
+
return `${TECH_CONTEXT_PATH} ainda é o template do scaffold (não preenchido): ` +
|
|
149
|
+
`descreva ${stack} e apague a linha \`# ${TECH_CONTEXT_TEMPLATE_MARKER}\` ` +
|
|
150
|
+
'que abre o arquivo.' + fim;
|
|
151
|
+
}
|
|
152
|
+
|
|
24
153
|
// Leitura SILENCIOSA da fonte estática — para quem só consulta (o `audit` lê
|
|
25
154
|
// as decisões de modelagem e ausência não é problema dele). `context: null`
|
|
26
155
|
// distingue "não existe" de "existe vazio"; `error` só em falha de parse.
|
|
@@ -35,15 +164,21 @@ export function loadStaticTechContext(cwd = process.cwd()) {
|
|
|
35
164
|
}
|
|
36
165
|
|
|
37
166
|
// §4.1 — Fonte de verdade estática. Ausência não é erro: segue com {} e avisa.
|
|
167
|
+
// Template não preenchido também vira {} — injetar o exemplo é pior que nada.
|
|
168
|
+
// Devolve também o motivo, para quem monta o aviso na issue.
|
|
38
169
|
function readStaticContext(cwd) {
|
|
39
|
-
const {
|
|
40
|
-
if (
|
|
41
|
-
|
|
170
|
+
const { state, reason, error, context } = readTechContext(cwd);
|
|
171
|
+
if (state === 'filled') return { context, reason: null };
|
|
172
|
+
if (state === 'template') {
|
|
173
|
+
console.warn(`⚠️ ${techContextTemplateHint(reason)}`);
|
|
174
|
+
return { context: {}, reason };
|
|
175
|
+
}
|
|
176
|
+
console.warn(state === 'invalid'
|
|
42
177
|
? `⚠️ Falha ao parsear ${TECH_CONTEXT_PATH}: ${error}. Ignorando.`
|
|
43
178
|
: `⚠️ ${TECH_CONTEXT_PATH} não encontrado. ` +
|
|
44
179
|
`O plano será gerado sem contexto técnico estático. ` +
|
|
45
180
|
`Rode \`spec-wave init\` para gerar o scaffold.`);
|
|
46
|
-
return {};
|
|
181
|
+
return { context: {}, reason: null };
|
|
47
182
|
}
|
|
48
183
|
|
|
49
184
|
// §4.2 — Augmentação dinâmica: migrations recentes + versões exatas de pacotes.
|
|
@@ -132,7 +267,7 @@ function isPlainObject(v) {
|
|
|
132
267
|
|
|
133
268
|
// Monta o tech context completo. `cwd` default = process.cwd() (checkout do Action).
|
|
134
269
|
export function buildTechContext({ issueBody = '', cwd = process.cwd() } = {}) {
|
|
135
|
-
const staticContext = readStaticContext(cwd);
|
|
270
|
+
const { context: staticContext, reason: unfilledReason } = readStaticContext(cwd);
|
|
136
271
|
const dynamic = readDynamicContext(cwd);
|
|
137
272
|
const overrides = parseTechOverride(issueBody);
|
|
138
273
|
const merged = deepMerge(staticContext, overrides);
|
|
@@ -142,6 +277,10 @@ export function buildTechContext({ issueBody = '', cwd = process.cwd() } = {}) {
|
|
|
142
277
|
dynamic,
|
|
143
278
|
overrides,
|
|
144
279
|
merged,
|
|
280
|
+
// O arquivo existe mas é o template: quem gera o documento avisa na issue.
|
|
281
|
+
// `unfilledReason` diz por quê (marcador, exemplo antigo ou campos em branco).
|
|
282
|
+
unfilled: unfilledReason !== null,
|
|
283
|
+
unfilledReason,
|
|
145
284
|
// String pronta para injetar no prompt: contexto efetivo + efêmeros.
|
|
146
285
|
yaml: yaml.dump({ ...merged, _dynamic: dynamic }, { lineWidth: 120 }),
|
|
147
286
|
};
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "spec-wave",
|
|
3
3
|
"displayName": "Spec Wave",
|
|
4
|
-
"version": "1.
|
|
4
|
+
"version": "1.9.0",
|
|
5
5
|
"description": "Fluxo spec-driven no GitHub (RFC-001): Projects v2, labels de gatilho, spec/plan gerados por Action, decomposição em duas etapas e implementação orientada a Stories/Tasks.",
|
|
6
6
|
"author": {
|
|
7
7
|
"name": "Astratech",
|
|
@@ -24,7 +24,7 @@ O plano segue o schema do **RFC-002 §3.2**: **Estratégia Técnica** (com Matri
|
|
|
24
24
|
|
|
25
25
|
1. **A spec existe?** Verifique `docs/features/<slug>/spec.md` — o plano usa a especificação funcional como contexto. Se não existir, gere a spec primeiro (skill **spec**).
|
|
26
26
|
|
|
27
|
-
2. **Garanta o `tech_context`.** Verifique se `.github/config/tech_context.yml` existe (Read). **Se não existir, ajude a criar AGORA** — o passo a passo está em `reference/tech-context.md`, ao lado deste arquivo. Garanta que esteja **commitado e pushado** antes de aplicar a label: o Action lê o arquivo do repositório, não do seu disco local.
|
|
27
|
+
2. **Garanta o `tech_context`.** Verifique se `.github/config/tech_context.yml` existe (Read) e está **preenchido** — o scaffold do `init` é um formulário em branco aberto pela linha `# spec-wave:template`, e nesse estado o plano sai sem contexto técnico. **Se não existir ou não estiver preenchido, ajude a criar AGORA** — o passo a passo está em `reference/tech-context.md`, ao lado deste arquivo. Garanta que esteja **commitado e pushado** antes de aplicar a label: o Action lê o arquivo do repositório, não do seu disco local.
|
|
28
28
|
|
|
29
29
|
3. **Acione**, no modo escolhido:
|
|
30
30
|
```bash
|
|
@@ -2,11 +2,19 @@
|
|
|
2
2
|
|
|
3
3
|
Fonte de verdade **estática** da stack do sistema (RFC-002 §4). O `generate-plan` lê este arquivo para embasar o plano técnico e usar **APENAS** as tecnologias e serviços nele declarados — sem ele, o plano fica genérico e pode inventar APIs inexistentes.
|
|
4
4
|
|
|
5
|
-
O `npx @spec-wave/cli@latest init` gera um **scaffold
|
|
5
|
+
O `npx @spec-wave/cli@latest init` gera um **scaffold em branco** — um formulário, não um exemplo — aberto pela linha `# spec-wave:template`. Use este fluxo quando o arquivo estiver ausente, **não preenchido** ou desatualizado.
|
|
6
|
+
|
|
7
|
+
**Não preenchido** é qualquer um destes três casos, e nos três o `doctor` reprova, o `preflight` bloqueia a rodada e o `generate-plan` gera **sem** contexto técnico estático (avisando na issue):
|
|
8
|
+
|
|
9
|
+
- a linha `# spec-wave:template` ainda abre o arquivo;
|
|
10
|
+
- nenhum campo além de `system_info.name` tem valor (apagar só a linha do marcador não resolve);
|
|
11
|
+
- o arquivo é o **exemplo dos scaffolds antigos** (até a CLI 1.7.x): `name: "Order Management System"` com `backend: "Node.js (NestJS v10)"`. Esse não tem marcador para apagar — o conteúdo é que precisa ser substituído pelo stack real.
|
|
6
12
|
|
|
7
13
|
## Como ajudar a criar
|
|
8
14
|
|
|
9
|
-
1. **
|
|
15
|
+
1. **Leia o que existe:** tente `Read .github/config/tech_context.yml`.
|
|
16
|
+
- **Ausente ou não preenchido** (ver acima) → siga os passos abaixo.
|
|
17
|
+
- **Preenchido** → confirme com o usuário se reflete a stack atual e pule para o fim.
|
|
10
18
|
|
|
11
19
|
2. **Detecte a stack lendo os arquivos do repositório** (use Read — **não invente**):
|
|
12
20
|
|
|
@@ -20,7 +28,7 @@ O `npx @spec-wave/cli@latest init` gera um **scaffold de exemplo** que **deve se
|
|
|
20
28
|
| `Dockerfile` / `docker-compose.yml` / charts Helm | `infra` |
|
|
21
29
|
| enums de RBAC no código | `security.rbac_roles` |
|
|
22
30
|
|
|
23
|
-
3. **Rascunhe** o YAML seguindo EXATAMENTE este schema. Preencha só o que conseguir confirmar; deixe `# TODO` no que faltar:
|
|
31
|
+
3. **Rascunhe** o YAML seguindo EXATAMENTE este schema. Preencha só o que conseguir confirmar; deixe `# TODO` no que faltar, e **apague** a chave que não se aplica ao sistema (valor vazio ou "N/A" é lido como tecnologia):
|
|
24
32
|
|
|
25
33
|
```yaml
|
|
26
34
|
system_info:
|
|
@@ -53,7 +61,7 @@ O `npx @spec-wave/cli@latest init` gera um **scaffold de exemplo** que **deve se
|
|
|
53
61
|
|
|
54
62
|
4. **Mostre o rascunho ao usuário e peça confirmação/ajustes** antes de gravar — ele conhece serviços internos e roles que o código pode não revelar.
|
|
55
63
|
|
|
56
|
-
5. **Grave** com Write em `.github/config/tech_context.yml
|
|
64
|
+
5. **Grave** com Write em `.github/config/tech_context.yml` — **sem** a linha `# spec-wave:template` do scaffold. Ela é o que marca o arquivo como não preenchido; mantê-la bloqueia o `preflight` mesmo com os campos certos.
|
|
57
65
|
|
|
58
66
|
6. **Oriente a commitar e pushar antes de seguir** — o Action lê do repositório, não do disco local. Sugira ao usuário rodar, via prefixo `!`:
|
|
59
67
|
|
|
@@ -93,7 +93,7 @@ Sem essas envs nada muda (instalação normal por `npm install -g`). Com elas, o
|
|
|
93
93
|
|
|
94
94
|
7. O `init` cria o Project, as labels, os workflows, um **scaffold de `.github/config/tech_context.yml`** (só se ainda não existir) e grava o `.spec-wave.json`. Oriente o usuário a fazer `git pull` para trazer os arquivos ao checkout local.
|
|
95
95
|
|
|
96
|
-
8. **
|
|
96
|
+
8. **Preencha o `tech_context.yml`** — o scaffold é um **formulário em branco** aberto pela linha `# spec-wave:template`, e a qualidade do `plan.md` depende dele. Enquanto essa linha existir (ou os campos estiverem vazios) o arquivo conta como **não preenchido**: o `doctor` reprova, o `preflight` bloqueia a rodada e o `generate-plan` gera sem contexto técnico. Ofereça preenchê-lo agora — com o stack real e **sem** a linha do marcador; o passo a passo está na skill **plan** (`reference/tech-context.md`).
|
|
97
97
|
|
|
98
98
|
9. **Secret de IA:** instrua a adicionar em Settings → Secrets → Actions a credencial do provider escolhido: `ANTHROPIC_API_KEY` (Anthropic), `CLAUDE_CODE_OAUTH_TOKEN` (assinatura Claude Pro/Max — gere com `claude setup-token`) ou `OPENROUTER_API_KEY` (OpenRouter).
|
|
99
99
|
|
|
@@ -3,7 +3,7 @@ name: spec
|
|
|
3
3
|
action: spec
|
|
4
4
|
description: Gera a especificação funcional (spec.md) de uma Feature a partir da issue do GitHub.
|
|
5
5
|
tools: [Read, Glob, Grep]
|
|
6
|
-
maxTurns:
|
|
6
|
+
maxTurns: 40
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
# Geração de spec.md
|
|
@@ -24,6 +24,13 @@ Você recebe um payload JSON com:
|
|
|
24
24
|
|
|
25
25
|
Você tem `Read`, `Glob` e `Grep` no repositório de destino. Antes de escrever qualquer seção, procure o que já existe: specs de features vizinhas em `docs/features/`, modelos de domínio, endpoints e telas relacionados. Uma spec ancorada no que o sistema já faz vale mais que uma escrita no vácuo.
|
|
26
26
|
|
|
27
|
+
**Orçamento de exploração.** Os turnos são limitados, e cada chamada de ferramenta gasta um. Um run que explora até o fim do orçamento falha sem entregar nada — pior que uma spec com `[TODO]`.
|
|
28
|
+
|
|
29
|
+
- Quando a entrada trouxer o **Índice das specs existentes**, comece por ele: o objetivo e as dependências de cada spec já estão ali. Abra só as que o índice indica como relacionadas a esta Feature.
|
|
30
|
+
- `Grep` antes de `Read`: procure o termo de domínio e abra apenas os arquivos que casaram.
|
|
31
|
+
- No máximo **12 arquivos lidos por inteiro**. Para arquivo grande, use `Read` com `offset`/`limit` na região que interessa.
|
|
32
|
+
- Quando já souber o suficiente para as seções obrigatórias, pare de explorar e escreva. O que faltar vira `[TODO: requer esclarecimento do PO]`.
|
|
33
|
+
|
|
27
34
|
Isso **não** autoriza inventar regras a partir do código: o código mostra o que existe, não o que o negócio quer. Continue marcando lacunas de negócio com `[TODO: requer esclarecimento do PO]`.
|
|
28
35
|
|
|
29
36
|
Se a entrada trouxer a seção **Workspace multi-repo**, o código NÃO está neste repositório (o hub só guarda documentação): está nos diretórios listados ali, um por repositório de código. Aponte `Glob`/`Grep`/`Read` para esses caminhos absolutos (parâmetro `path`) — a partir da raiz do hub eles ficam fora da busca. As specs vizinhas continuam em `docs/features/` do hub.
|
|
@@ -38,6 +38,7 @@ import {
|
|
|
38
38
|
getRequiredStatusChecks,
|
|
39
39
|
listActionsSecretNames,
|
|
40
40
|
getActionsCanCreatePullRequests,
|
|
41
|
+
getOwnerPlan,
|
|
41
42
|
isRepoInitialized,
|
|
42
43
|
listPullRequestCommitMessages,
|
|
43
44
|
listPullRequestReviews,
|
|
@@ -237,7 +238,7 @@ export function createGithubScm({ link, token, prToken, trackerKind = 'github-pr
|
|
|
237
238
|
getPRClosingIssues, getRateLimit, listIssuePullRequests, listOpenPullRequests,
|
|
238
239
|
markPullRequestReadyForReview,
|
|
239
240
|
getRepoInfo, getRequiredStatusChecks, listActionsSecretNames,
|
|
240
|
-
getActionsCanCreatePullRequests, getFileBytes,
|
|
241
|
+
getActionsCanCreatePullRequests, getOwnerPlan, getFileBytes,
|
|
241
242
|
...api,
|
|
242
243
|
};
|
|
243
244
|
|
|
@@ -316,6 +317,12 @@ export function createGithubScm({ link, token, prToken, trackerKind = 'github-pr
|
|
|
316
317
|
} catch {
|
|
317
318
|
facts.automationCanOpenPullRequest = null; // exige administration:read
|
|
318
319
|
}
|
|
320
|
+
try {
|
|
321
|
+
// Plano da org: decide se secrets de ORGANIZAÇÃO chegam a repo privado.
|
|
322
|
+
facts.ownerPlan = await a.getOwnerPlan(token, owner);
|
|
323
|
+
} catch {
|
|
324
|
+
facts.ownerPlan = null;
|
|
325
|
+
}
|
|
319
326
|
}
|
|
320
327
|
|
|
321
328
|
const quota = (await a.getRateLimit(token)) || {};
|
|
@@ -64,6 +64,7 @@ import {
|
|
|
64
64
|
getItemTextValue,
|
|
65
65
|
setItemText,
|
|
66
66
|
getProjectSnapshot,
|
|
67
|
+
getProjectIdByUrl,
|
|
67
68
|
getRateLimit,
|
|
68
69
|
linkProjectToRepo,
|
|
69
70
|
listProjectItems,
|
|
@@ -184,7 +185,7 @@ export function createGithubTracker({ token, projectToken, owner, repo, project
|
|
|
184
185
|
setIssueMilestone, setIssueState, updateComment, updateIssue, updateLabel, updateMilestone,
|
|
185
186
|
updateMilestoneDescription, getOwnerNodeId, getRepoNodeId,
|
|
186
187
|
addProjectItem, addSubIssue, createProject, createSingleSelectField, createTextField,
|
|
187
|
-
getIssueParent, getItemSingleSelectValue, getItemTextValue, getProjectSnapshot, getRateLimit,
|
|
188
|
+
getIssueParent, getItemSingleSelectValue, getItemTextValue, getProjectSnapshot, getProjectIdByUrl, getRateLimit,
|
|
188
189
|
linkProjectToRepo, listProjectItems, listSubIssues, setItemSingleSelect, setItemText,
|
|
189
190
|
resolveField, getOrgMembershipState, listIssuesByLabel,
|
|
190
191
|
...api,
|
|
@@ -241,15 +242,21 @@ export function createGithubTracker({ token, projectToken, owner, repo, project
|
|
|
241
242
|
kind: TRACKER_KIND,
|
|
242
243
|
capabilities: GITHUB_TRACKER_CAPABILITIES,
|
|
243
244
|
|
|
244
|
-
async setup({ provision = true, title, log } = {}) {
|
|
245
|
+
async setup({ provision = true, title, log, boardUrl = null } = {}) {
|
|
245
246
|
// `provision: false` é LEITURA: devolve o bloco de config que descreve o
|
|
246
247
|
// board como ele está agora. É o que o `refresh --config` precisa, e é a
|
|
247
248
|
// mesma pergunta que um tracker `map-only` responderia relendo os
|
|
248
249
|
// statuses do site — por isso não virou operação separada.
|
|
249
250
|
if (!provision) {
|
|
250
|
-
|
|
251
|
+
// `boardUrl`: lê OUTRO board, apontado pela URL — é o `relink` de um
|
|
252
|
+
// repositório transferido, cujo config ainda guarda o id do board antigo.
|
|
253
|
+
const alvo = boardUrl ? await a.getProjectIdByUrl(ptk, boardUrl) : project?.id;
|
|
254
|
+
if (!alvo) {
|
|
255
|
+
return { config: null, warnings: [`Project ${boardUrl} não encontrado, ou o token não o enxerga.`] };
|
|
256
|
+
}
|
|
257
|
+
const snap = await a.getProjectSnapshot(ptk, alvo);
|
|
251
258
|
if (!snap) {
|
|
252
|
-
return { config: null, warnings: [`Project ${
|
|
259
|
+
return { config: null, warnings: [`Project ${alvo} não encontrado. Ele pode ter sido excluído.`] };
|
|
253
260
|
}
|
|
254
261
|
return {
|
|
255
262
|
config: {
|
package/src/ports/tracker.mjs
CHANGED
|
@@ -60,7 +60,8 @@ import { checkCapabilityKeys } from './capabilities.mjs';
|
|
|
60
60
|
*
|
|
61
61
|
* ── SEMPRE ────────────────────────────────────────────────────────────────
|
|
62
62
|
*
|
|
63
|
-
* @property {(o?: {provision?: boolean, log?: Function}) => Promise<{config: object, warnings: string[]}>} setup
|
|
63
|
+
* @property {(o?: {provision?: boolean, log?: Function, boardUrl?: string}) => Promise<{config: object, warnings: string[]}>} setup
|
|
64
|
+
* `boardUrl` (só com `provision: false`): lê o board apontado pela URL em vez do do config — o `relink`.
|
|
64
65
|
* Provisiona (`boardProvisioning: 'create'`) ou mapeia (`'map-only'`) o board.
|
|
65
66
|
* Devolve o bloco a gravar no `.spec-wave.json` — **nunca escreve o arquivo**:
|
|
66
67
|
* quem serializa é `lib/config-file.mjs`, byte-exato, porque o `update` faz
|
package/src/setup/labels.mjs
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { allLabelsFor } from '../config.mjs';
|
|
2
|
-
import { requireTracker } from '../ports/index.mjs';
|
|
2
|
+
import { DEFAULT_TRACKER_KIND, requireTracker } from '../ports/index.mjs';
|
|
3
3
|
|
|
4
4
|
/**
|
|
5
5
|
* Pausa entre criações de label.
|
|
@@ -16,8 +16,10 @@ const DELAY_MS = 120;
|
|
|
16
16
|
// vale para `devAgent` e as filas extra do dev-agent. No `init` os dois vêm
|
|
17
17
|
// vazios (o config ainda nem foi gravado) e o conjunto é só o do fluxo; quem
|
|
18
18
|
// cria as de modelo/fila depois é o `update`, que já lê o config do repo.
|
|
19
|
-
export async function setupLabels(token, owner, repo, spinner, fileAi, devAgent, { port } = {}) {
|
|
20
|
-
|
|
19
|
+
export async function setupLabels(token, owner, repo, spinner, fileAi, devAgent, { port, kind = DEFAULT_TRACKER_KIND } = {}) {
|
|
20
|
+
// `kind` explícito: no `init` ainda não existe `.spec-wave.json` para o
|
|
21
|
+
// loader descobrir o fornecedor (ver getTracker em ports/index.mjs).
|
|
22
|
+
const tracker = await requireTracker({ token, owner, repo, kind, deps: { tracker: port } });
|
|
21
23
|
const labels = allLabelsFor(fileAi, devAgent);
|
|
22
24
|
await tracker.ensureTags({
|
|
23
25
|
tags: labels,
|
package/src/setup/project.mjs
CHANGED
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
// a chama com um spinner do Clack, e trocar o formato do progresso do `init`
|
|
14
14
|
// seria mudança de comportamento numa fase que promete não ter nenhuma.
|
|
15
15
|
|
|
16
|
-
import { requireTracker } from '../ports/index.mjs';
|
|
16
|
+
import { DEFAULT_TRACKER_KIND, requireTracker } from '../ports/index.mjs';
|
|
17
17
|
|
|
18
18
|
/**
|
|
19
19
|
* Cria o GitHub Project e os campos do RFC-001.
|
|
@@ -26,8 +26,10 @@ import { requireTracker } from '../ports/index.mjs';
|
|
|
26
26
|
* @param {{port?: object}} [opts] injeção da porta, para teste
|
|
27
27
|
* @returns {Promise<{projectId, projectNumber, projectUrl, fields, linkWarning?}>}
|
|
28
28
|
*/
|
|
29
|
-
export async function setupProject(token, owner, repo, projectTitle, spinner, { port } = {}) {
|
|
30
|
-
|
|
29
|
+
export async function setupProject(token, owner, repo, projectTitle, spinner, { port, kind = DEFAULT_TRACKER_KIND } = {}) {
|
|
30
|
+
// `kind` explícito: no `init` ainda não existe `.spec-wave.json` para o
|
|
31
|
+
// loader descobrir o fornecedor (ver getTracker em ports/index.mjs).
|
|
32
|
+
const tracker = await requireTracker({ token, owner, repo, kind, deps: { tracker: port } });
|
|
31
33
|
const { config, warnings } = await tracker.setup({
|
|
32
34
|
provision: true,
|
|
33
35
|
title: projectTitle,
|
|
@@ -1,3 +1,9 @@
|
|
|
1
|
+
# spec-wave:template — APAGUE ESTA LINHA depois de preencher o arquivo com o stack REAL.
|
|
2
|
+
#
|
|
3
|
+
# Enquanto esta linha existir, o arquivo é tratado como NÃO PREENCHIDO: o
|
|
4
|
+
# `doctor` e o `preflight` reprovam, e o `generate-plan` não o injeta no prompt
|
|
5
|
+
# (um stack de exemplo lido como verdade produz plano para o sistema errado).
|
|
6
|
+
#
|
|
1
7
|
# tech_context.yml — Fonte de verdade estática do sistema (RFC-002 §4)
|
|
2
8
|
#
|
|
3
9
|
# O comando `generate-plan` lê este arquivo para embasar o plano técnico, usando
|
|
@@ -7,39 +13,37 @@
|
|
|
7
13
|
# migrations recentes e as versões exatas de pacotes (package.json) em tempo de
|
|
8
14
|
# execução. Para desvios pontuais, adicione uma seção `## Tech Override` no corpo
|
|
9
15
|
# da issue da Feature — ela é mesclada (deep-merge) sobre esta config.
|
|
16
|
+
#
|
|
17
|
+
# Preencha só o que existe. Chave que não se aplica ao sistema: apague-a
|
|
18
|
+
# (não deixe "N/A" — o modelo lê o valor como tecnologia).
|
|
10
19
|
|
|
11
20
|
system_info:
|
|
12
|
-
name: "
|
|
21
|
+
name: "" # ex.: "Gestão de Pedidos"
|
|
13
22
|
stack:
|
|
14
|
-
backend: "Node.js (NestJS v10)"
|
|
15
|
-
frontend: "React 18
|
|
16
|
-
database: "PostgreSQL 15"
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
infra: "Kubernetes (EKS) + Helm"
|
|
20
|
-
architecture: "Microservices via API Gateway"
|
|
23
|
+
backend: "" # ex.: "Node.js (NestJS v10)", "Kotlin (Ktor)", "AWS Amplify Gen 2 (Lambda)"
|
|
24
|
+
frontend: "" # ex.: "React 18 com Vite", "Compose Multiplatform"
|
|
25
|
+
database: "" # ex.: "PostgreSQL 15", "DynamoDB"
|
|
26
|
+
infra: "" # ex.: "Kubernetes (EKS) + Helm", "AWS Amplify"
|
|
27
|
+
architecture: "" # ex.: "Monólito modular", "Microsserviços via API Gateway"
|
|
21
28
|
|
|
22
29
|
security:
|
|
23
|
-
auth_protocol: "JWT (Access/Refresh)"
|
|
24
|
-
rbac_roles: [
|
|
30
|
+
auth_protocol: "" # ex.: "JWT (Access/Refresh)", "Amazon Cognito"
|
|
31
|
+
rbac_roles: [] # ex.: ["ADMIN", "OPERADOR"]
|
|
25
32
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
columns: "id, number, status, capacity"
|
|
31
|
-
- table: "products"
|
|
32
|
-
columns: "id, name, category, price, stock"
|
|
33
|
+
# Tabelas/coleções que as features costumam tocar (opcional).
|
|
34
|
+
# database_schemas:
|
|
35
|
+
# - table: "users"
|
|
36
|
+
# columns: "id, name, email, role"
|
|
33
37
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
38
|
+
# Serviços existentes que as features podem consumir (opcional).
|
|
39
|
+
# existing_services:
|
|
40
|
+
# - name: "Inventory API"
|
|
41
|
+
# endpoint: "/api/inventory/{productId}/availability"
|
|
42
|
+
# auth: "mTLS"
|
|
39
43
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
44
|
+
# Bibliotecas internas (opcional).
|
|
45
|
+
# internal_libraries:
|
|
46
|
+
# - "shared-logger"
|
|
43
47
|
|
|
44
48
|
# Decisões de modelagem de recursos COMPARTILHADOS entre features (opcional).
|
|
45
49
|
#
|