@spec-wave/cli 0.35.0 → 1.0.2

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 (42) 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 +42 -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/repo.mjs +103 -0
  16. package/src/commands/story.mjs +2 -2
  17. package/src/commands/task.mjs +2 -2
  18. package/src/commands/triage.mjs +2 -5
  19. package/src/commands/update.mjs +31 -8
  20. package/src/commands/validate.mjs +2 -5
  21. package/src/commands/workspace.mjs +112 -0
  22. package/src/config.mjs +19 -0
  23. package/src/lib/artifact-pr.mjs +1 -1
  24. package/src/lib/claude.mjs +4 -0
  25. package/src/lib/decomposition-doc.mjs +56 -3
  26. package/src/lib/dependency-map.mjs +3 -0
  27. package/src/lib/flow-run.mjs +14 -3
  28. package/src/lib/pr-link.mjs +65 -10
  29. package/src/lib/pr-ready.mjs +6 -2
  30. package/src/lib/project-root.mjs +51 -0
  31. package/src/lib/repo-role.mjs +169 -0
  32. package/src/lib/workspace.mjs +151 -0
  33. package/src/plugin/.claude-plugin/plugin.json +1 -1
  34. package/src/plugin/skills/decompose/SKILL.md +1 -0
  35. package/src/plugin/skills/decompose/model-prompt.feature.md +4 -2
  36. package/src/plugin/skills/implement/SKILL.md +1 -1
  37. package/src/plugin/skills/setup/SKILL.md +19 -0
  38. package/src/setup/files.mjs +35 -13
  39. package/src/templates/skill/SKILL.md +21 -1
  40. package/src/templates/workflows/code/code-review.yml +60 -0
  41. package/src/templates/workflows/code/qa.yml +59 -0
  42. package/src/templates/workflows/pr-events.yml +116 -0
@@ -0,0 +1,169 @@
1
+ // Papel do repositório no Project (RFC-005): um Project tem UM repositório
2
+ // hub — onde nascem as issues, os documentos e os workflows — e N repositórios
3
+ // de código, onde só acontecem branch e PR. Mono-repo é o caso degenerado:
4
+ // um hub sem repos de código, que é exatamente o estado de toda instalação
5
+ // anterior à RFC. Por isso a AUSÊNCIA de `role` no .spec-wave.json significa
6
+ // hub, e nenhum config antigo precisa ser regravado.
7
+ //
8
+ // hub: { role: 'hub', repositories: [{ slug, owner, repo }] } (repositories opcional)
9
+ // code: { role: 'code', hub: { owner, repo } }
10
+ //
11
+ // Funções PURAS — testáveis sem rede nem disco.
12
+
13
+ export const REPO_ROLES = ['hub', 'code'];
14
+ export const DEFAULT_REPO_ROLE = 'hub';
15
+
16
+ // Mesma regra do slug da UI (shared/src/projectRepos.ts): minúsculas,
17
+ // [a-z0-9-], até 39 caracteres — o limite de um login do GitHub. O slug vai
18
+ // na label `repo:<slug>` e é IMUTÁVEL depois do primeiro vínculo, porque está
19
+ // gravado em issues.
20
+ const REPO_SLUG_RE = /^[a-z0-9](?:[a-z0-9-]{0,38})$/;
21
+
22
+ export function isValidRepoSlug(slug) {
23
+ return typeof slug === 'string' && REPO_SLUG_RE.test(slug);
24
+ }
25
+
26
+ /** @returns {'hub'|'code'} */
27
+ export function configuredRole(config) {
28
+ const role = String(config?.role || '').toLowerCase();
29
+ return REPO_ROLES.includes(role) ? role : DEFAULT_REPO_ROLE;
30
+ }
31
+
32
+ export function isCodeRepo(config) {
33
+ return configuredRole(config) === 'code';
34
+ }
35
+
36
+ /**
37
+ * O hub declarado por um repo de código, ou null quando o config não é de
38
+ * repo de código ou está incompleto.
39
+ * @returns {{ owner: string, repo: string }|null}
40
+ */
41
+ export function declaredHub(config) {
42
+ if (!isCodeRepo(config)) return null;
43
+ const hub = config?.hub;
44
+ if (!hub?.owner || !hub?.repo) return null;
45
+ return { owner: String(hub.owner), repo: String(hub.repo) };
46
+ }
47
+
48
+ /**
49
+ * Repositórios de código vinculados ao hub, já validados. Entradas
50
+ * malformadas são descartadas em vez de derrubar o comando — o hub continua
51
+ * funcionando como mono-repo enquanto o vínculo não estiver completo.
52
+ * @returns {{ slug: string, owner: string, repo: string }[]}
53
+ */
54
+ export function codeRepositories(config) {
55
+ if (isCodeRepo(config)) return [];
56
+ const list = Array.isArray(config?.repositories) ? config.repositories : [];
57
+ const out = [];
58
+ const seen = new Set();
59
+ for (const entry of list) {
60
+ if (!isValidRepoSlug(entry?.slug) || !entry?.owner || !entry?.repo) continue;
61
+ if (seen.has(entry.slug)) continue;
62
+ seen.add(entry.slug);
63
+ out.push({ slug: entry.slug, owner: String(entry.owner), repo: String(entry.repo) });
64
+ }
65
+ return out;
66
+ }
67
+
68
+ export function repositoryBySlug(config, slug) {
69
+ return codeRepositories(config).find(r => r.slug === slug) || null;
70
+ }
71
+
72
+ /**
73
+ * `owner/repo` → { owner, repo }; null para qualquer outra forma. É a
74
+ * gramática de `--repo`, `--hub` e `--pr-repo`.
75
+ */
76
+ export function parseRepoRef(value) {
77
+ const m = /^([\w.-]+)\/([\w.-]+)$/.exec(String(value ?? '').trim());
78
+ return m ? { owner: m[1], repo: m[2] } : null;
79
+ }
80
+
81
+ /** A label que uma Story usa para declarar que toca este repositório. */
82
+ export const REPO_LABEL_PREFIX = 'repo:';
83
+
84
+ export function repoLabel(slug) {
85
+ return `${REPO_LABEL_PREFIX}${slug}`;
86
+ }
87
+
88
+ /** Cor e descrição únicas: `repo link`, `decompose --apply` e a UI criam a mesma label. */
89
+ export function repoLabelSpec(slug) {
90
+ return { name: repoLabel(slug), color: '0e8a16', description: `Story toca o repositório ${slug}` };
91
+ }
92
+
93
+ /**
94
+ * Vincula um repositório de código ao hub (função PURA — devolve um config
95
+ * novo). Recusa o que a label tornaria irreversível: o slug é IMUTÁVEL depois
96
+ * do primeiro vínculo, então o mesmo slug só aceita o MESMO repo; e um repo já
97
+ * vinculado sob outro slug não ganha um segundo nome.
98
+ *
99
+ * @param {object} config .spec-wave.json do hub
100
+ * @param {{slug: string, owner: string, repo: string}} entry
101
+ * @returns {{ config: object, changed: boolean, error: string|null }}
102
+ */
103
+ export function linkRepository(config, { slug, owner, repo }) {
104
+ if (isCodeRepo(config)) {
105
+ return { config, changed: false, error: 'este repositório é de código (role "code"); o vínculo é registrado no hub.' };
106
+ }
107
+ if (!isValidRepoSlug(slug)) {
108
+ return { config, changed: false, error: `slug inválido "${slug}": minúsculas, [a-z0-9-], até 39 caracteres, começando por letra ou dígito.` };
109
+ }
110
+ if (!owner || !repo) return { config, changed: false, error: 'informe o repositório como owner/repo.' };
111
+ const same = (a, b) => String(a).toLowerCase() === String(b).toLowerCase();
112
+ if (config?.owner && config?.repo && same(config.owner, owner) && same(config.repo, repo)) {
113
+ return { config, changed: false, error: `${owner}/${repo} é o próprio hub — o hub não se vincula a si mesmo.` };
114
+ }
115
+ const current = codeRepositories(config);
116
+ const bySlug = current.find(r => r.slug === slug);
117
+ if (bySlug && same(bySlug.owner, owner) && same(bySlug.repo, repo)) {
118
+ return { config, changed: false, error: null };
119
+ }
120
+ if (bySlug) {
121
+ return {
122
+ config, changed: false,
123
+ error: `o slug "${slug}" já aponta para ${bySlug.owner}/${bySlug.repo} e é imutável (está nas labels repo:${slug}). Use outro slug ou desvincule antes.`,
124
+ };
125
+ }
126
+ const byRepo = current.find(r => same(r.owner, owner) && same(r.repo, repo));
127
+ if (byRepo) {
128
+ return { config, changed: false, error: `${owner}/${repo} já está vinculado como "${byRepo.slug}".` };
129
+ }
130
+ // Preserva as entradas como estão no arquivo (a UI pode gravar campos além
131
+ // de slug/owner/repo); `current` serviu só para as checagens.
132
+ const raw = Array.isArray(config?.repositories) ? config.repositories : [];
133
+ return {
134
+ config: { ...config, repositories: [...raw, { slug, owner, repo }] },
135
+ changed: true,
136
+ error: null,
137
+ };
138
+ }
139
+
140
+ /**
141
+ * Desvincula pelo slug (função PURA). As labels `repo:<slug>` já aplicadas em
142
+ * issues NÃO são tocadas — são histórico, e o `update` nunca as classifica
143
+ * como órfãs (§3.3).
144
+ *
145
+ * @returns {{ config: object, changed: boolean, error: string|null }}
146
+ */
147
+ export function unlinkRepository(config, slug) {
148
+ if (!codeRepositories(config).some(r => r.slug === slug)) {
149
+ return { config, changed: false, error: `não há repositório vinculado com o slug "${slug}".` };
150
+ }
151
+ const raw = Array.isArray(config?.repositories) ? config.repositories : [];
152
+ return { config: { ...config, repositories: raw.filter(r => r?.slug !== slug) }, changed: true, error: null };
153
+ }
154
+
155
+ /**
156
+ * Slugs declarados pelas labels de uma issue, na ordem em que aparecem.
157
+ * A label é a fonte de verdade (§3.3) — o campo do board é só espelho.
158
+ * @param {Array<string|{name?: string}>} labels
159
+ */
160
+ export function repoSlugsFromLabels(labels) {
161
+ const out = [];
162
+ for (const l of labels || []) {
163
+ const name = typeof l === 'string' ? l : l?.name;
164
+ if (!name || !name.startsWith(REPO_LABEL_PREFIX)) continue;
165
+ const slug = name.slice(REPO_LABEL_PREFIX.length);
166
+ if (isValidRepoSlug(slug) && !out.includes(slug)) out.push(slug);
167
+ }
168
+ return out;
169
+ }
@@ -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.2",
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,25 @@ 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 do vínculo **no hub**:
40
+
41
+ ```bash
42
+ npx @spec-wave/cli@latest repo link <slug> <owner/api> # dentro do hub
43
+ npx @spec-wave/cli@latest repo list
44
+ ```
45
+
46
+ `repo link` grava `{ slug, owner, repo }` em `repositories[]` do `.spec-wave.json` local do hub (commite depois — os workflows leem a branch default) e cria a label `repo:<slug>`. Slug em `[a-z0-9-]`, até 39 caracteres, **imutável** depois do primeiro vínculo; `repo unlink <slug>` remove a entrada sem tocar nas labels já aplicadas. Os PRs do repo de código vinculam a Story com `Closes <owner>/<hub>#<n>`.
28
47
 
29
48
  ## Passos
30
49
 
@@ -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,25 @@ 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 do vínculo **no hub**:
564
+
565
+ ```bash
566
+ npx @spec-wave/cli@latest repo link <slug> <owner/api> # dentro do hub
567
+ npx @spec-wave/cli@latest repo list
568
+ ```
569
+
570
+ `repo link` grava `{ slug, owner, repo }` em `repositories[]` do `.spec-wave.json` local do hub (commite depois — os workflows leem a branch default) e cria a label `repo:<slug>`. Slug em `[a-z0-9-]`, até 39 caracteres, **imutável** depois do primeiro vínculo; `repo unlink <slug>` remove a entrada sem tocar nas labels já aplicadas. Os PRs do repo de código vinculam a Story com `Closes <owner>/<hub>#<n>`.
552
571
 
553
572
  #### Passos
554
573
 
@@ -999,6 +1018,7 @@ Corpo técnico.
999
1018
 
1000
1019
  - a **posição** manda, não o número escrito — inserir uma Story no meio sem renumerar funciona
1001
1020
  - `**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
1021
+ - `**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
1022
  - o corpo aceita markdown livre (`## Backend`, cercas de código) — só `## Story N` e `### Task N.M` são estrutura
1003
1023
  - **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
1024
 
@@ -1068,7 +1088,7 @@ Outros tipos (Spike, Epic) → o comando **recusa**.
1068
1088
  ```bash
1069
1089
  npx @spec-wave/cli@latest implement <número>
1070
1090
  ```
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}`.
1091
+ 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
1092
 
1073
1093
  Use `--feature-dir docs/features/<slug>` se a resolução automática falhar e você quiser anexar `spec.md`/`plan.md`.
1074
1094
 
@@ -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 }}