@spec-wave/cli 0.35.0 → 1.0.1
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/package.json +2 -2
- package/src/agent/anthropic-agent.mjs +35 -2
- package/src/api/github-rest.mjs +23 -0
- package/src/cli.mjs +23 -0
- package/src/commands/code-review.mjs +31 -17
- package/src/commands/decompose.mjs +75 -4
- package/src/commands/doctor.mjs +43 -3
- package/src/commands/implement.mjs +39 -6
- package/src/commands/init.mjs +147 -29
- package/src/commands/merge.mjs +11 -8
- package/src/commands/move.mjs +4 -7
- package/src/commands/order.mjs +2 -2
- package/src/commands/qa.mjs +22 -21
- package/src/commands/repair-stage.mjs +2 -5
- package/src/commands/story.mjs +2 -2
- package/src/commands/task.mjs +2 -2
- package/src/commands/triage.mjs +2 -5
- package/src/commands/update.mjs +31 -8
- package/src/commands/validate.mjs +2 -5
- package/src/commands/workspace.mjs +112 -0
- package/src/config.mjs +19 -0
- package/src/lib/artifact-pr.mjs +1 -1
- package/src/lib/claude.mjs +4 -0
- package/src/lib/decomposition-doc.mjs +56 -3
- package/src/lib/dependency-map.mjs +3 -0
- package/src/lib/flow-run.mjs +14 -3
- package/src/lib/pr-link.mjs +65 -10
- package/src/lib/pr-ready.mjs +6 -2
- package/src/lib/project-root.mjs +51 -0
- package/src/lib/repo-role.mjs +102 -0
- package/src/lib/workspace.mjs +151 -0
- package/src/plugin/.claude-plugin/plugin.json +1 -1
- package/src/plugin/skills/decompose/SKILL.md +1 -0
- package/src/plugin/skills/decompose/model-prompt.feature.md +4 -2
- package/src/plugin/skills/implement/SKILL.md +1 -1
- package/src/plugin/skills/setup/SKILL.md +12 -0
- package/src/setup/files.mjs +35 -13
- package/src/templates/skill/SKILL.md +14 -1
- package/src/templates/workflows/code/code-review.yml +60 -0
- package/src/templates/workflows/code/qa.yml +59 -0
- package/src/templates/workflows/pr-events.yml +116 -0
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
// Workspace multi-repo (RFC-005 §3.5/§7.2): um subdiretório por slug, ao lado
|
|
2
|
+
// do hub. É a peça que unifica o conceito de workspace nos três executores —
|
|
3
|
+
// no dev local resolve a convenção de irmãos, no Action clona, e o
|
|
4
|
+
// `implement` deriva daqui os placeholders {workspaceDir}/{repoDirs}.
|
|
5
|
+
//
|
|
6
|
+
// <workspace>/
|
|
7
|
+
// hub/ ← .spec-wave.json (role: hub), docs/features/<slug>/
|
|
8
|
+
// api/
|
|
9
|
+
// web/
|
|
10
|
+
//
|
|
11
|
+
// Caminho de máquina NUNCA entra no .spec-wave.json commitado. O override local
|
|
12
|
+
// vive em .spec-wave/workspace.json (gitignored) e a CLONAGEM gerenciada em
|
|
13
|
+
// .spec-wave/repos/<slug>/ — dentro do diretório de scratch que já não é
|
|
14
|
+
// versionado. Irmãos e overrides são do dev: nunca são clonados, puxados ou
|
|
15
|
+
// tocados; só mapeados.
|
|
16
|
+
|
|
17
|
+
import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
|
|
18
|
+
import path from 'node:path';
|
|
19
|
+
import { execFileSync } from 'node:child_process';
|
|
20
|
+
import { codeRepositories, repoSlugsFromLabels } from './repo-role.mjs';
|
|
21
|
+
|
|
22
|
+
export const WORKSPACE_OVERRIDE_FILE = path.join('.spec-wave', 'workspace.json');
|
|
23
|
+
export const WORKSPACE_CLONES_DIR = path.join('.spec-wave', 'repos');
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* Slugs que um item toca (função PURA): os das próprias labels; uma Feature,
|
|
27
|
+
* que não declara repo, AGREGA os dos filhos (§5.2 `repoSlugsOfFeature`).
|
|
28
|
+
*
|
|
29
|
+
* @param {object} params
|
|
30
|
+
* @param {Array<string|{name?:string}>} [params.labels]
|
|
31
|
+
* @param {Array<{labels?: Array}>} [params.children]
|
|
32
|
+
* @returns {string[]} ordenados, sem repetição
|
|
33
|
+
*/
|
|
34
|
+
export function slugsForItem({ labels = [], children = [] } = {}) {
|
|
35
|
+
const own = repoSlugsFromLabels(labels);
|
|
36
|
+
if (own.length > 0) return [...own].sort();
|
|
37
|
+
const agg = new Set();
|
|
38
|
+
for (const child of children) {
|
|
39
|
+
for (const slug of repoSlugsFromLabels(child?.labels)) agg.add(slug);
|
|
40
|
+
}
|
|
41
|
+
return [...agg].sort();
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* Onde cada repositório fica (função PURA — `exists` é injetável).
|
|
46
|
+
*
|
|
47
|
+
* Por slug, nesta ordem: override em .spec-wave/workspace.json → irmão
|
|
48
|
+
* (`<pai do hub>/<slug>`) → clone gerenciado (`<hub>/.spec-wave/repos/<slug>`).
|
|
49
|
+
* Slug fora de `repositories[]` volta em `unknown`, nunca vira diretório.
|
|
50
|
+
*
|
|
51
|
+
* @param {object} params
|
|
52
|
+
* @param {string} params.root raiz do hub (diretório do .spec-wave.json)
|
|
53
|
+
* @param {object} params.config .spec-wave.json do hub
|
|
54
|
+
* @param {string[]} params.slugs
|
|
55
|
+
* @param {{dirs?: Record<string,string>}|null} [params.override]
|
|
56
|
+
* @param {(p: string) => boolean} [params.exists]
|
|
57
|
+
* @returns {{ hubDir: string, workspaceDir: string, unknown: string[],
|
|
58
|
+
* repos: Array<{slug:string, owner:string, repo:string, dir:string,
|
|
59
|
+
* source:'override'|'sibling'|'clone', present:boolean}> }}
|
|
60
|
+
*/
|
|
61
|
+
export function resolveWorkspaceLayout({ root, config, slugs = [], override = null, exists = existsSync }) {
|
|
62
|
+
const hubDir = path.resolve(root);
|
|
63
|
+
const workspaceDir = path.dirname(hubDir);
|
|
64
|
+
const known = new Map(codeRepositories(config).map(r => [r.slug, r]));
|
|
65
|
+
const repos = [];
|
|
66
|
+
const unknown = [];
|
|
67
|
+
for (const slug of slugs) {
|
|
68
|
+
const meta = known.get(slug);
|
|
69
|
+
if (!meta) { unknown.push(slug); continue; }
|
|
70
|
+
const overridden = override?.dirs?.[slug];
|
|
71
|
+
if (typeof overridden === 'string' && overridden.trim()) {
|
|
72
|
+
const dir = path.resolve(hubDir, overridden.trim());
|
|
73
|
+
repos.push({ ...meta, dir, source: 'override', present: exists(dir) });
|
|
74
|
+
continue;
|
|
75
|
+
}
|
|
76
|
+
const sibling = path.join(workspaceDir, slug);
|
|
77
|
+
if (exists(sibling)) {
|
|
78
|
+
repos.push({ ...meta, dir: sibling, source: 'sibling', present: true });
|
|
79
|
+
continue;
|
|
80
|
+
}
|
|
81
|
+
const managed = path.join(hubDir, WORKSPACE_CLONES_DIR, slug);
|
|
82
|
+
repos.push({ ...meta, dir: managed, source: 'clone', present: exists(managed) });
|
|
83
|
+
}
|
|
84
|
+
return { hubDir, workspaceDir, repos, unknown };
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/** Override local (`{ "dirs": { "<slug>": "<caminho>" } }`), ou null. */
|
|
88
|
+
export function readWorkspaceOverride(root) {
|
|
89
|
+
try {
|
|
90
|
+
const parsed = JSON.parse(readFileSync(path.join(root, WORKSPACE_OVERRIDE_FILE), 'utf-8'));
|
|
91
|
+
return parsed && typeof parsed === 'object' ? parsed : null;
|
|
92
|
+
} catch {
|
|
93
|
+
return null;
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* Valor do placeholder `{repoDirs}` do implement: `slug=/dir slug=/dir`,
|
|
99
|
+
* separado por espaço — legível num shell e trivial de partir num script.
|
|
100
|
+
*/
|
|
101
|
+
export function renderRepoDirs(repos = []) {
|
|
102
|
+
return repos.map(r => `${r.slug}=${r.dir}`).join(' ');
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
function cloneUrl({ owner, repo }, token) {
|
|
106
|
+
// Token na URL só no Action, onde o clone é descartável; localmente o git
|
|
107
|
+
// usa o credential helper do dev (o do gh, normalmente).
|
|
108
|
+
return token
|
|
109
|
+
? `https://x-access-token:${token}@github.com/${owner}/${repo}.git`
|
|
110
|
+
: `https://github.com/${owner}/${repo}.git`;
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
function defaultGit(args) {
|
|
114
|
+
return execFileSync('git', args, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
/**
|
|
118
|
+
* Materializa o workspace: clona o que falta e é de fonte `clone`. Irmão ou
|
|
119
|
+
* override ausente é AVISO — o diretório é do dev, não desta CLI.
|
|
120
|
+
*
|
|
121
|
+
* @param {object} params
|
|
122
|
+
* @param {ReturnType<typeof resolveWorkspaceLayout>} params.layout
|
|
123
|
+
* @param {string|null} [params.token] só no Action (vai para a URL do clone)
|
|
124
|
+
* @param {boolean} [params.shallow] `--depth 1` — leitura pelos prompts
|
|
125
|
+
* @param {(args: string[]) => string} [params.git] injetável nos testes
|
|
126
|
+
* @param {{warn: Function, info: Function}} [params.log]
|
|
127
|
+
* @returns {Promise<{ cloned: string[], missing: string[] }>}
|
|
128
|
+
*/
|
|
129
|
+
export async function prepareWorkspace({ layout, token = null, shallow = false, git = defaultGit, log = console }) {
|
|
130
|
+
const cloned = [];
|
|
131
|
+
const missing = [];
|
|
132
|
+
for (const r of layout.repos) {
|
|
133
|
+
if (r.present) continue;
|
|
134
|
+
if (r.source !== 'clone') {
|
|
135
|
+
missing.push(r.slug);
|
|
136
|
+
log.warn(`${r.slug}: ${r.dir} não existe (${r.source === 'override' ? 'override em ' + WORKSPACE_OVERRIDE_FILE : 'irmão do hub'}) — clone você mesmo ou remova o override.`);
|
|
137
|
+
continue;
|
|
138
|
+
}
|
|
139
|
+
mkdirSync(path.dirname(r.dir), { recursive: true });
|
|
140
|
+
// Diretório auto-ignorado: um clone inteiro dentro do hub não pode virar
|
|
141
|
+
// "untracked" à espera de um `git add .` — e o hub não tem template de
|
|
142
|
+
// .gitignore para depender dele.
|
|
143
|
+
const ignore = path.join(path.dirname(r.dir), '.gitignore');
|
|
144
|
+
if (!existsSync(ignore)) writeFileSync(ignore, '*\n');
|
|
145
|
+
log.info(`Clonando ${r.owner}/${r.repo} em ${r.dir}...`);
|
|
146
|
+
git(['clone', '--quiet', ...(shallow ? ['--depth', '1'] : []), cloneUrl(r, token), r.dir]);
|
|
147
|
+
r.present = true;
|
|
148
|
+
cloned.push(r.slug);
|
|
149
|
+
}
|
|
150
|
+
return { cloned, missing };
|
|
151
|
+
}
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "spec-wave",
|
|
3
3
|
"displayName": "Spec Wave",
|
|
4
|
-
"version": "0.
|
|
4
|
+
"version": "1.0.1",
|
|
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",
|
|
@@ -94,6 +94,7 @@ Corpo técnico.
|
|
|
94
94
|
|
|
95
95
|
- a **posição** manda, não o número escrito — inserir uma Story no meio sem renumerar funciona
|
|
96
96
|
- `**Depende de:**` aceita **irmãs** (`Story 1, Story 3`, 1-based, só para trás — apontar para si mesma ou para frente é **erro**, não filtro silencioso) e **issues de outras Features** (`#412`, que precisam JÁ existir); as duas formas convivem na mesma linha (`Story 1, #412`), e `—` significa nenhuma
|
|
97
|
+
- `**Repos:** api, web` (opcional, **só no multi-repo** — RFC-005): os slugs de `repositories[]` do `.spec-wave.json` do hub que a Story toca. No apply viram labels `repo:<slug>` na Story **e nas Tasks**; slug que o hub não conhece reprova o rascunho **antes** de criar qualquer issue. Sem a linha, nenhum repo é declarado (mono-repo)
|
|
97
98
|
- o corpo aceita markdown livre (`## Backend`, cercas de código) — só `## Story N` e `### Task N.M` são estrutura
|
|
98
99
|
- **para gerar outro rascunho do zero:** feche o Pull Request e apague a branch `spec-wave/<n>-decompose` (ou apague o arquivo, se já foi mergeado) e reaplique `spec-wave:decompose`
|
|
99
100
|
|
|
@@ -5,7 +5,7 @@ description: Decompõe uma Feature em Stories ordenadas, cada uma com suas Tasks
|
|
|
5
5
|
tools: [Read, Glob, Grep]
|
|
6
6
|
maxTurns: 30
|
|
7
7
|
json:
|
|
8
|
-
shape: '{"stories": [{"title": "...", "userStory": "...", "body": "...", "dependsOn": [0], "tasks": [{"title": "...", "body": "..."}]}]}'
|
|
8
|
+
shape: '{"stories": [{"title": "...", "userStory": "...", "body": "...", "dependsOn": [0], "repos": ["api"], "tasks": [{"title": "...", "body": "..."}]}]}'
|
|
9
9
|
retries: 1
|
|
10
10
|
---
|
|
11
11
|
|
|
@@ -39,6 +39,7 @@ Responda APENAS com JSON válido neste formato:
|
|
|
39
39
|
"userStory": "Como <perfil>, quero <objetivo>, para <benefício>",
|
|
40
40
|
"body": "Descrição complementar da story com contexto e critérios de aceite relevantes",
|
|
41
41
|
"dependsOn": [0],
|
|
42
|
+
"repos": ["api"],
|
|
42
43
|
"tasks": [
|
|
43
44
|
{
|
|
44
45
|
"title": "Título técnico curto da task (sem prefixo)",
|
|
@@ -60,10 +61,11 @@ Responda APENAS com JSON válido neste formato:
|
|
|
60
61
|
- Gere entre 3 e 7 Stories por Feature
|
|
61
62
|
- Ordene as stories na sequência de implementação — a ORDEM da lista importa
|
|
62
63
|
- `dependsOn` (opcional): índices 0-based das stories ANTERIORES na lista das quais esta story depende. Referencie apenas índices menores que o da própria story. Use `[]` quando a story puder ser feita em paralelo (sem dependências); se omitido, assume-se dependência da story anterior (sequencial)
|
|
64
|
+
- `repos` (opcional): **só** quando a entrada trouxer a seção "Repositórios de código". São os slugs dos repositórios que a story toca, copiados EXATAMENTE da lista (uma story pode tocar mais de um). Sem essa seção, **omita o campo** — o projeto é mono-repo
|
|
63
65
|
- Escreva títulos e corpos em português (pt-BR). Não use caracteres de outros alfabetos (CJK, cirílico, árabe, tailandês).
|
|
64
66
|
|
|
65
67
|
## O que acontece com a sua saída
|
|
66
68
|
|
|
67
|
-
Cada story vira uma issue `[STORY]` e cada task uma issue `[TASK]` vinculada como sub-issue, posicionadas na etapa **✅ Ready** do board. As dependências viram a relação nativa `blocked_by` do GitHub e uma linha "Depende de: #N" no corpo. Ou seja: a ordem e o `
|
|
69
|
+
Cada story vira uma issue `[STORY]` e cada task uma issue `[TASK]` vinculada como sub-issue, posicionadas na etapa **✅ Ready** do board. As dependências viram a relação nativa `blocked_by` do GitHub e uma linha "Depende de: #N" no corpo; `repos` vira a label `repo:<slug>` na Story e nas suas Tasks — é por ela que o time sabe em que repositório abrir o PR. Ou seja: a ordem, o `dependsOn` e o `repos` que você devolver determinam a execução real do time.
|
|
68
70
|
|
|
69
71
|
Antes disso, uma crítica adversarial audita as stories contra a spec e o plan (ver a skill `critique-stories`). Achados graves cancelam a criação — nenhuma issue é aberta.
|
|
@@ -59,7 +59,7 @@ Outros tipos (Spike, Epic) → o comando **recusa**.
|
|
|
59
59
|
```bash
|
|
60
60
|
npx @spec-wave/cli@latest implement <número>
|
|
61
61
|
```
|
|
62
|
-
Se **não** estiver configurado, o comando só monta o contexto e mostra como configurar. Ajude a definir o template — placeholders disponíveis: `{tasksFile} {specFile} {planFile} {issue} {type} {title}`.
|
|
62
|
+
Se **não** estiver configurado, o comando só monta o contexto e mostra como configurar. Ajude a definir o template — placeholders disponíveis: `{tasksFile} {specFile} {planFile} {issue} {type} {title} {workspaceDir} {repoDirs}`. Os dois últimos são do multi-repo (RFC-005): `{workspaceDir}` é o diretório pai do hub e `{repoDirs}` lista `slug=/caminho` por repositório que a issue declara (label `repo:<slug>`) — vazio no mono-repo. Se algum repo estiver ausente, o comando avisa: rode `npx @spec-wave/cli@latest workspace prepare --issue <número>` antes.
|
|
63
63
|
|
|
64
64
|
Use `--feature-dir docs/features/<slug>` se a resolução automática falhar e você quiser anexar `spec.md`/`plan.md`.
|
|
65
65
|
|
|
@@ -25,6 +25,18 @@ Você dirige o `init` **com flags**. Nunca rode `npx @spec-wave/cli@latest init`
|
|
|
25
25
|
| `--skip-labels` | flag | Pula as labels. |
|
|
26
26
|
| `--skip-files` | flag | Pula workflows + issue templates. |
|
|
27
27
|
| `--dry-run` | flag | Simula sem alterar nada. |
|
|
28
|
+
| `--role <hub\|code>` | string | Papel do repo no Project (RFC-005). Default `hub`. |
|
|
29
|
+
| `--hub <owner/repo>` | string | Só com `--role code`: o hub a que este repo de código pertence. |
|
|
30
|
+
|
|
31
|
+
### Repositório de código (multi-repo, RFC-005)
|
|
32
|
+
|
|
33
|
+
Um Project tem **um** hub (issues, docs, labels, Project, workflows do fluxo) e N repos de código, onde só acontecem branch e PR. Para vincular um repo de código:
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
npx @spec-wave/cli@latest init --role code --repo <owner/api> --hub <owner/hub>
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Isso grava **só** dois despachantes (`code-review.yml`, `qa.yml`, que avisam o hub por `repository_dispatch`) e um `.spec-wave.json` com `role: "code"` e `hub`. Nada de labels, Project, issue templates ou secret de IA. Depois: o secret `SPEC_WAVE_HUB_TOKEN` no repo de código (token com escrita em Contents no hub), `spec-wave update` no hub (instala o `pr-events.yml`), e o registro em `repositories[]` do `.spec-wave.json` do hub — `{ slug, owner, repo }`, slug em `[a-z0-9-]`, imutável. Os PRs do repo de código vinculam a Story com `Closes <owner>/<hub>#<n>`.
|
|
28
40
|
|
|
29
41
|
## Passos
|
|
30
42
|
|
package/src/setup/files.mjs
CHANGED
|
@@ -1,24 +1,28 @@
|
|
|
1
1
|
import { upsertFile, getFileContent, isRepoInitialized } from '../api/github-rest.mjs';
|
|
2
|
-
import { WORKFLOW_FILES } from '../config.mjs';
|
|
2
|
+
import { WORKFLOW_FILES, CODE_WORKFLOW_FILES } from '../config.mjs';
|
|
3
3
|
// readTemplate resolve {{CLI_VERSION}} — é o que fixa a versão da CLI nos
|
|
4
4
|
// workflows gravados no repo-alvo (ver src/lib/templates.mjs).
|
|
5
5
|
import { readTemplate } from '../lib/templates.mjs';
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
7
|
+
/**
|
|
8
|
+
* Arquivos que um repositório recebe, por papel (RFC-005 §7.5). O repo de
|
|
9
|
+
* código recebe SÓ os despachantes — sem issue templates, sem tech_context,
|
|
10
|
+
* sem os outros sete workflows. Função PURA (só lê templates do pacote).
|
|
11
|
+
*
|
|
12
|
+
* @param {'hub'|'code'} role
|
|
13
|
+
* @returns {Array<{path: string, content: string, message: string}>}
|
|
14
|
+
*/
|
|
15
|
+
export function repoFilesFor(role) {
|
|
16
|
+
if (role === 'code') {
|
|
17
|
+
return CODE_WORKFLOW_FILES.map((file) => ({
|
|
18
|
+
path: `.github/workflows/${file}`,
|
|
19
|
+
content: readTemplate('workflows', 'code', file),
|
|
20
|
+
message: `chore: add ${file.replace(/\.yml$/, '')} dispatcher [spec-wave]`,
|
|
21
|
+
}));
|
|
17
22
|
}
|
|
18
|
-
|
|
19
23
|
// Workflows vêm de WORKFLOW_FILES (config.mjs, fonte única) — adicionar um
|
|
20
24
|
// workflow novo lá basta para o init (e o update) instalarem.
|
|
21
|
-
|
|
25
|
+
return [
|
|
22
26
|
{
|
|
23
27
|
path: '.github/ISSUE_TEMPLATE/plan-template.md',
|
|
24
28
|
content: readTemplate('issue', 'plan-template.md'),
|
|
@@ -35,6 +39,21 @@ export async function setupFiles(token, owner, repo, spinner) {
|
|
|
35
39
|
message: `chore: add ${file.replace(/\.yml$/, '')} workflow [spec-wave]`,
|
|
36
40
|
})),
|
|
37
41
|
];
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
export async function setupFiles(token, owner, repo, spinner, { role = 'hub' } = {}) {
|
|
45
|
+
spinner.message('Verificando repositório...');
|
|
46
|
+
const initialized = await isRepoInitialized(token, owner, repo);
|
|
47
|
+
if (!initialized) {
|
|
48
|
+
throw new Error(
|
|
49
|
+
`O repositório ${owner}/${repo} está vazio (sem commits).\n` +
|
|
50
|
+
`Inicialize-o com um commit antes de continuar:\n` +
|
|
51
|
+
` gh repo clone ${owner}/${repo} && cd ${repo}\n` +
|
|
52
|
+
` git commit --allow-empty -m "chore: initial commit" && git push`
|
|
53
|
+
);
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
const filesToCreate = repoFilesFor(role);
|
|
38
57
|
|
|
39
58
|
for (let i = 0; i < filesToCreate.length; i++) {
|
|
40
59
|
const file = filesToCreate[i];
|
|
@@ -42,6 +61,9 @@ export async function setupFiles(token, owner, repo, spinner) {
|
|
|
42
61
|
await upsertFile(token, owner, repo, file.path, file.content, file.message);
|
|
43
62
|
}
|
|
44
63
|
|
|
64
|
+
// O tech_context é do hub: é lá que os prompts o leem.
|
|
65
|
+
if (role === 'code') return;
|
|
66
|
+
|
|
45
67
|
// Arquivos de config criados apenas se ainda não existirem, para não
|
|
46
68
|
// sobrescrever ajustes manuais (tech_context.yml é editado pelo time).
|
|
47
69
|
const configFiles = [
|
|
@@ -549,6 +549,18 @@ Você dirige o `init` **com flags**. Nunca rode `npx @spec-wave/cli@latest init`
|
|
|
549
549
|
| `--skip-labels` | flag | Pula as labels. |
|
|
550
550
|
| `--skip-files` | flag | Pula workflows + issue templates. |
|
|
551
551
|
| `--dry-run` | flag | Simula sem alterar nada. |
|
|
552
|
+
| `--role <hub\|code>` | string | Papel do repo no Project (RFC-005). Default `hub`. |
|
|
553
|
+
| `--hub <owner/repo>` | string | Só com `--role code`: o hub a que este repo de código pertence. |
|
|
554
|
+
|
|
555
|
+
##### Repositório de código (multi-repo, RFC-005)
|
|
556
|
+
|
|
557
|
+
Um Project tem **um** hub (issues, docs, labels, Project, workflows do fluxo) e N repos de código, onde só acontecem branch e PR. Para vincular um repo de código:
|
|
558
|
+
|
|
559
|
+
```bash
|
|
560
|
+
npx @spec-wave/cli@latest init --role code --repo <owner/api> --hub <owner/hub>
|
|
561
|
+
```
|
|
562
|
+
|
|
563
|
+
Isso grava **só** dois despachantes (`code-review.yml`, `qa.yml`, que avisam o hub por `repository_dispatch`) e um `.spec-wave.json` com `role: "code"` e `hub`. Nada de labels, Project, issue templates ou secret de IA. Depois: o secret `SPEC_WAVE_HUB_TOKEN` no repo de código (token com escrita em Contents no hub), `spec-wave update` no hub (instala o `pr-events.yml`), e o registro em `repositories[]` do `.spec-wave.json` do hub — `{ slug, owner, repo }`, slug em `[a-z0-9-]`, imutável. Os PRs do repo de código vinculam a Story com `Closes <owner>/<hub>#<n>`.
|
|
552
564
|
|
|
553
565
|
#### Passos
|
|
554
566
|
|
|
@@ -999,6 +1011,7 @@ Corpo técnico.
|
|
|
999
1011
|
|
|
1000
1012
|
- a **posição** manda, não o número escrito — inserir uma Story no meio sem renumerar funciona
|
|
1001
1013
|
- `**Depende de:**` aceita **irmãs** (`Story 1, Story 3`, 1-based, só para trás — apontar para si mesma ou para frente é **erro**, não filtro silencioso) e **issues de outras Features** (`#412`, que precisam JÁ existir); as duas formas convivem na mesma linha (`Story 1, #412`), e `—` significa nenhuma
|
|
1014
|
+
- `**Repos:** api, web` (opcional, **só no multi-repo** — RFC-005): os slugs de `repositories[]` do `.spec-wave.json` do hub que a Story toca. No apply viram labels `repo:<slug>` na Story **e nas Tasks**; slug que o hub não conhece reprova o rascunho **antes** de criar qualquer issue. Sem a linha, nenhum repo é declarado (mono-repo)
|
|
1002
1015
|
- o corpo aceita markdown livre (`## Backend`, cercas de código) — só `## Story N` e `### Task N.M` são estrutura
|
|
1003
1016
|
- **para gerar outro rascunho do zero:** feche o Pull Request e apague a branch `spec-wave/<n>-decompose` (ou apague o arquivo, se já foi mergeado) e reaplique `spec-wave:decompose`
|
|
1004
1017
|
|
|
@@ -1068,7 +1081,7 @@ Outros tipos (Spike, Epic) → o comando **recusa**.
|
|
|
1068
1081
|
```bash
|
|
1069
1082
|
npx @spec-wave/cli@latest implement <número>
|
|
1070
1083
|
```
|
|
1071
|
-
Se **não** estiver configurado, o comando só monta o contexto e mostra como configurar. Ajude a definir o template — placeholders disponíveis: `{tasksFile} {specFile} {planFile} {issue} {type} {title}`.
|
|
1084
|
+
Se **não** estiver configurado, o comando só monta o contexto e mostra como configurar. Ajude a definir o template — placeholders disponíveis: `{tasksFile} {specFile} {planFile} {issue} {type} {title} {workspaceDir} {repoDirs}`. Os dois últimos são do multi-repo (RFC-005): `{workspaceDir}` é o diretório pai do hub e `{repoDirs}` lista `slug=/caminho` por repositório que a issue declara (label `repo:<slug>`) — vazio no mono-repo. Se algum repo estiver ausente, o comando avisa: rode `npx @spec-wave/cli@latest workspace prepare --issue <número>` antes.
|
|
1072
1085
|
|
|
1073
1086
|
Use `--feature-dir docs/features/<slug>` se a resolução automática falhar e você quiser anexar `spec.md`/`plan.md`.
|
|
1074
1087
|
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
name: Code Review
|
|
2
|
+
|
|
3
|
+
# Repositório de CÓDIGO (RFC-005 §7.1): este workflow não roda a CLI nem toca
|
|
4
|
+
# no board. Ele só avisa o hub — onde vivem as issues e o GitHub Project — que
|
|
5
|
+
# um PR foi aberto aqui. O hub recebe o aviso em pr-events.yml e faz o resto,
|
|
6
|
+
# dentro da trava por item que o serializa com o decompose. `concurrency` do
|
|
7
|
+
# GitHub é por repositório: com N repos de código, só centralizar no hub
|
|
8
|
+
# devolve a serialização.
|
|
9
|
+
#
|
|
10
|
+
# O hub é lido do .spec-wave.json deste repositório em tempo de execução, e
|
|
11
|
+
# NÃO carimbado no YAML: o `update` compara este arquivo byte a byte com o
|
|
12
|
+
# template empacotado, e um hub embutido o marcaria como desatualizado para
|
|
13
|
+
# sempre.
|
|
14
|
+
#
|
|
15
|
+
# Precisa do secret SPEC_WAVE_HUB_TOKEN: um token com permissão de escrita em
|
|
16
|
+
# Contents no hub (é o que o repository_dispatch exige). GITHUB_TOKEN não
|
|
17
|
+
# serve — ele só enxerga este repositório.
|
|
18
|
+
on:
|
|
19
|
+
pull_request:
|
|
20
|
+
types: [opened, reopened]
|
|
21
|
+
|
|
22
|
+
concurrency:
|
|
23
|
+
group: spec-wave-dispatch-${{ github.event.pull_request.number }}
|
|
24
|
+
cancel-in-progress: false
|
|
25
|
+
|
|
26
|
+
jobs:
|
|
27
|
+
dispatch:
|
|
28
|
+
# PR de documento (`spec-wave/*`) não é PR de implementação.
|
|
29
|
+
if: "!startsWith(github.event.pull_request.head.ref, 'spec-wave/')"
|
|
30
|
+
runs-on: ubuntu-latest
|
|
31
|
+
permissions:
|
|
32
|
+
contents: read
|
|
33
|
+
|
|
34
|
+
steps:
|
|
35
|
+
- uses: actions/checkout@v5
|
|
36
|
+
|
|
37
|
+
- id: hub
|
|
38
|
+
name: Lê o hub do .spec-wave.json
|
|
39
|
+
run: |
|
|
40
|
+
hub="$(jq -r '"\(.hub.owner // "")/\(.hub.repo // "")"' .spec-wave.json)"
|
|
41
|
+
if [ "$hub" = "/" ]; then
|
|
42
|
+
echo "::error::.spec-wave.json sem hub {owner, repo}. Rode: npx @spec-wave/cli@latest init --role code --repo ${{ github.repository }} --hub <owner/repo>"
|
|
43
|
+
exit 1
|
|
44
|
+
fi
|
|
45
|
+
echo "repo=$hub" >> "$GITHUB_OUTPUT"
|
|
46
|
+
|
|
47
|
+
- name: Avisa o hub (repository_dispatch)
|
|
48
|
+
run: |
|
|
49
|
+
gh api "repos/${{ steps.hub.outputs.repo }}/dispatches" --input - <<'PAYLOAD'
|
|
50
|
+
{
|
|
51
|
+
"event_type": "spec-wave-pr",
|
|
52
|
+
"client_payload": {
|
|
53
|
+
"event": "opened",
|
|
54
|
+
"pr_repo": "${{ github.repository }}",
|
|
55
|
+
"pr_number": ${{ github.event.pull_request.number }}
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
PAYLOAD
|
|
59
|
+
env:
|
|
60
|
+
GH_TOKEN: ${{ secrets.SPEC_WAVE_HUB_TOKEN }}
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
name: QA
|
|
2
|
+
|
|
3
|
+
# Repositório de CÓDIGO (RFC-005 §7.3): despachante fino, sem CLI e sem board.
|
|
4
|
+
# Aprovação formal OU merge do PR viram um aviso ao hub, que move a Feature
|
|
5
|
+
# para 🧪 QA em pr-events.yml. Sem este arquivo nada chega a QA — os eventos
|
|
6
|
+
# de review e de merge acontecem SÓ aqui, no repo do PR.
|
|
7
|
+
#
|
|
8
|
+
# O hub é lido do .spec-wave.json em tempo de execução (ver code-review.yml,
|
|
9
|
+
# que explica por que o YAML não pode carimbá-lo). Precisa do secret
|
|
10
|
+
# SPEC_WAVE_HUB_TOKEN com escrita em Contents no hub.
|
|
11
|
+
on:
|
|
12
|
+
pull_request_review:
|
|
13
|
+
types: [submitted]
|
|
14
|
+
pull_request:
|
|
15
|
+
types: [closed]
|
|
16
|
+
|
|
17
|
+
concurrency:
|
|
18
|
+
group: spec-wave-dispatch-qa-${{ github.event.pull_request.number }}
|
|
19
|
+
cancel-in-progress: false
|
|
20
|
+
|
|
21
|
+
jobs:
|
|
22
|
+
dispatch:
|
|
23
|
+
# PR de documento (`spec-wave/*`) não é PR de implementação, e aprovar o
|
|
24
|
+
# PR da spec moveria a Feature para QA. A última linha aceita os dois
|
|
25
|
+
# eventos: review aprovada, ou PR fechado COM merge (sem merge não conta).
|
|
26
|
+
if: >
|
|
27
|
+
!startsWith(github.event.pull_request.head.ref, 'spec-wave/') &&
|
|
28
|
+
(github.event.review.state == 'approved' || github.event.pull_request.merged == true)
|
|
29
|
+
runs-on: ubuntu-latest
|
|
30
|
+
permissions:
|
|
31
|
+
contents: read
|
|
32
|
+
|
|
33
|
+
steps:
|
|
34
|
+
- uses: actions/checkout@v5
|
|
35
|
+
|
|
36
|
+
- id: hub
|
|
37
|
+
name: Lê o hub do .spec-wave.json
|
|
38
|
+
run: |
|
|
39
|
+
hub="$(jq -r '"\(.hub.owner // "")/\(.hub.repo // "")"' .spec-wave.json)"
|
|
40
|
+
if [ "$hub" = "/" ]; then
|
|
41
|
+
echo "::error::.spec-wave.json sem hub {owner, repo}. Rode: npx @spec-wave/cli@latest init --role code --repo ${{ github.repository }} --hub <owner/repo>"
|
|
42
|
+
exit 1
|
|
43
|
+
fi
|
|
44
|
+
echo "repo=$hub" >> "$GITHUB_OUTPUT"
|
|
45
|
+
|
|
46
|
+
- name: Avisa o hub (repository_dispatch)
|
|
47
|
+
run: |
|
|
48
|
+
gh api "repos/${{ steps.hub.outputs.repo }}/dispatches" --input - <<'PAYLOAD'
|
|
49
|
+
{
|
|
50
|
+
"event_type": "spec-wave-pr",
|
|
51
|
+
"client_payload": {
|
|
52
|
+
"event": "qa",
|
|
53
|
+
"pr_repo": "${{ github.repository }}",
|
|
54
|
+
"pr_number": ${{ github.event.pull_request.number }}
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
PAYLOAD
|
|
58
|
+
env:
|
|
59
|
+
GH_TOKEN: ${{ secrets.SPEC_WAVE_HUB_TOKEN }}
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
name: PR Events
|
|
2
|
+
|
|
3
|
+
# Recebe, de um repositório de CÓDIGO do mesmo Project, o aviso de que um PR
|
|
4
|
+
# foi aberto, aprovado ou mergeado lá (RFC-005 §7.1). O despachante de lá
|
|
5
|
+
# manda um repository_dispatch com { event, pr_repo, pr_number }; tudo que
|
|
6
|
+
# toca o board roda AQUI, no hub, dentro do namespace spec-wave-item-<feature>
|
|
7
|
+
# que serializa com o decompose. Num hub sem repos de código este workflow
|
|
8
|
+
# nunca dispara e não custa nada.
|
|
9
|
+
#
|
|
10
|
+
# Tokens: GITHUB_TOKEN só enxerga este repositório, e o PR está noutro. Por
|
|
11
|
+
# isso a CLI recebe o GH_PROJECT_TOKEN (PAT com repo + project) também como
|
|
12
|
+
# GITHUB_TOKEN — é ele que lê o PR e comenta nele. Sem o secret, cai no
|
|
13
|
+
# GITHUB_TOKEN, que ainda lê PR de repo público mas não comenta.
|
|
14
|
+
on:
|
|
15
|
+
repository_dispatch:
|
|
16
|
+
types: [spec-wave-pr]
|
|
17
|
+
|
|
18
|
+
# Trava por PR de origem: o mesmo PR do mesmo repo não é processado duas
|
|
19
|
+
# vezes ao mesmo tempo. A trava que importa é a do job `move`, por ITEM.
|
|
20
|
+
concurrency:
|
|
21
|
+
group: spec-wave-pr-${{ github.event.client_payload.pr_repo }}-${{ github.event.client_payload.pr_number }}
|
|
22
|
+
cancel-in-progress: false
|
|
23
|
+
|
|
24
|
+
jobs:
|
|
25
|
+
# Descobre a Feature-alvo ANTES de tocar no board, para dar a chave de
|
|
26
|
+
# concurrency ao job seguinte — mesmo desenho do code-review.yml local.
|
|
27
|
+
resolve:
|
|
28
|
+
# Modo de execução: `spec-wave mode local` cria a variável de repositório
|
|
29
|
+
# SPEC_WAVE_EXECUTION=local e este job passa a ser PULADO.
|
|
30
|
+
if: vars.SPEC_WAVE_EXECUTION != 'local' && github.event.client_payload.event == 'opened'
|
|
31
|
+
runs-on: ubuntu-latest
|
|
32
|
+
permissions:
|
|
33
|
+
issues: read
|
|
34
|
+
pull-requests: read
|
|
35
|
+
contents: read
|
|
36
|
+
outputs:
|
|
37
|
+
feature: ${{ steps.resolve.outputs.feature }}
|
|
38
|
+
steps:
|
|
39
|
+
- uses: actions/checkout@v5
|
|
40
|
+
- uses: actions/setup-node@v5
|
|
41
|
+
with:
|
|
42
|
+
node-version: '24'
|
|
43
|
+
|
|
44
|
+
- name: Instala a CLI
|
|
45
|
+
run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
|
|
46
|
+
|
|
47
|
+
- id: resolve
|
|
48
|
+
run: >
|
|
49
|
+
spec-wave code-review
|
|
50
|
+
--pr-number ${{ github.event.client_payload.pr_number }}
|
|
51
|
+
--pr-repo ${{ github.event.client_payload.pr_repo }}
|
|
52
|
+
--resolve-only
|
|
53
|
+
env:
|
|
54
|
+
GITHUB_TOKEN: ${{ secrets.GH_PROJECT_TOKEN || secrets.GITHUB_TOKEN }}
|
|
55
|
+
GITHUB_REPOSITORY: ${{ github.repository }}
|
|
56
|
+
|
|
57
|
+
move:
|
|
58
|
+
needs: resolve
|
|
59
|
+
if: >
|
|
60
|
+
vars.SPEC_WAVE_EXECUTION != 'local' &&
|
|
61
|
+
needs.resolve.outputs.feature != ''
|
|
62
|
+
runs-on: ubuntu-latest
|
|
63
|
+
# MESMO namespace do decompose.yml e do code-review.yml: um decompose-apply
|
|
64
|
+
# em curso na Feature segura este job na fila em vez de disputar a
|
|
65
|
+
# subárvore com ele.
|
|
66
|
+
concurrency:
|
|
67
|
+
group: spec-wave-item-${{ needs.resolve.outputs.feature }}
|
|
68
|
+
cancel-in-progress: false
|
|
69
|
+
permissions:
|
|
70
|
+
issues: write
|
|
71
|
+
pull-requests: write
|
|
72
|
+
contents: read
|
|
73
|
+
steps:
|
|
74
|
+
- uses: actions/checkout@v5
|
|
75
|
+
- uses: actions/setup-node@v5
|
|
76
|
+
with:
|
|
77
|
+
node-version: '24'
|
|
78
|
+
|
|
79
|
+
- name: Instala a CLI
|
|
80
|
+
run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
|
|
81
|
+
|
|
82
|
+
- name: Move Feature to Code Review
|
|
83
|
+
run: >
|
|
84
|
+
spec-wave code-review
|
|
85
|
+
--pr-number ${{ github.event.client_payload.pr_number }}
|
|
86
|
+
--pr-repo ${{ github.event.client_payload.pr_repo }}
|
|
87
|
+
env:
|
|
88
|
+
GITHUB_TOKEN: ${{ secrets.GH_PROJECT_TOKEN || secrets.GITHUB_TOKEN }}
|
|
89
|
+
PROJECT_TOKEN: ${{ secrets.GH_PROJECT_TOKEN }}
|
|
90
|
+
GITHUB_REPOSITORY: ${{ github.repository }}
|
|
91
|
+
|
|
92
|
+
qa:
|
|
93
|
+
if: vars.SPEC_WAVE_EXECUTION != 'local' && github.event.client_payload.event == 'qa'
|
|
94
|
+
runs-on: ubuntu-latest
|
|
95
|
+
permissions:
|
|
96
|
+
issues: write
|
|
97
|
+
pull-requests: write
|
|
98
|
+
contents: read
|
|
99
|
+
steps:
|
|
100
|
+
- uses: actions/checkout@v5
|
|
101
|
+
- uses: actions/setup-node@v5
|
|
102
|
+
with:
|
|
103
|
+
node-version: '24'
|
|
104
|
+
|
|
105
|
+
- name: Instala a CLI
|
|
106
|
+
run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
|
|
107
|
+
|
|
108
|
+
- name: Move Feature to QA
|
|
109
|
+
run: >
|
|
110
|
+
spec-wave qa
|
|
111
|
+
--pr-number ${{ github.event.client_payload.pr_number }}
|
|
112
|
+
--pr-repo ${{ github.event.client_payload.pr_repo }}
|
|
113
|
+
env:
|
|
114
|
+
GITHUB_TOKEN: ${{ secrets.GH_PROJECT_TOKEN || secrets.GITHUB_TOKEN }}
|
|
115
|
+
PROJECT_TOKEN: ${{ secrets.GH_PROJECT_TOKEN }}
|
|
116
|
+
GITHUB_REPOSITORY: ${{ github.repository }}
|