@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.
Files changed (41) hide show
  1. package/package.json +2 -2
  2. package/src/agent/anthropic-agent.mjs +35 -2
  3. package/src/api/github-rest.mjs +23 -0
  4. package/src/cli.mjs +23 -0
  5. package/src/commands/code-review.mjs +31 -17
  6. package/src/commands/decompose.mjs +75 -4
  7. package/src/commands/doctor.mjs +43 -3
  8. package/src/commands/implement.mjs +39 -6
  9. package/src/commands/init.mjs +147 -29
  10. package/src/commands/merge.mjs +11 -8
  11. package/src/commands/move.mjs +4 -7
  12. package/src/commands/order.mjs +2 -2
  13. package/src/commands/qa.mjs +22 -21
  14. package/src/commands/repair-stage.mjs +2 -5
  15. package/src/commands/story.mjs +2 -2
  16. package/src/commands/task.mjs +2 -2
  17. package/src/commands/triage.mjs +2 -5
  18. package/src/commands/update.mjs +31 -8
  19. package/src/commands/validate.mjs +2 -5
  20. package/src/commands/workspace.mjs +112 -0
  21. package/src/config.mjs +19 -0
  22. package/src/lib/artifact-pr.mjs +1 -1
  23. package/src/lib/claude.mjs +4 -0
  24. package/src/lib/decomposition-doc.mjs +56 -3
  25. package/src/lib/dependency-map.mjs +3 -0
  26. package/src/lib/flow-run.mjs +14 -3
  27. package/src/lib/pr-link.mjs +65 -10
  28. package/src/lib/pr-ready.mjs +6 -2
  29. package/src/lib/project-root.mjs +51 -0
  30. package/src/lib/repo-role.mjs +102 -0
  31. package/src/lib/workspace.mjs +151 -0
  32. package/src/plugin/.claude-plugin/plugin.json +1 -1
  33. package/src/plugin/skills/decompose/SKILL.md +1 -0
  34. package/src/plugin/skills/decompose/model-prompt.feature.md +4 -2
  35. package/src/plugin/skills/implement/SKILL.md +1 -1
  36. package/src/plugin/skills/setup/SKILL.md +12 -0
  37. package/src/setup/files.mjs +35 -13
  38. package/src/templates/skill/SKILL.md +14 -1
  39. package/src/templates/workflows/code/code-review.yml +60 -0
  40. package/src/templates/workflows/code/qa.yml +59 -0
  41. 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.35.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 `dependsOn` que você devolver determinam a ordem real de execução do time.
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
 
@@ -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
- export async function setupFiles(token, owner, repo, spinner) {
8
- spinner.message('Verificando repositório...');
9
- const initialized = await isRepoInitialized(token, owner, repo);
10
- if (!initialized) {
11
- throw new Error(
12
- `O repositório ${owner}/${repo} está vazio (sem commits).\n` +
13
- `Inicialize-o com um commit antes de continuar:\n` +
14
- ` gh repo clone ${owner}/${repo} && cd ${repo}\n` +
15
- ` git commit --allow-empty -m "chore: initial commit" && git push`
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
- const filesToCreate = [
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 }}