@spec-wave/cli 0.34.2 → 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/protocol/qa-result.v1.json +9 -0
- package/src/agent/anthropic-agent.mjs +35 -2
- package/src/api/github-graphql.mjs +60 -2
- package/src/api/github-rest.mjs +23 -0
- package/src/cli.mjs +23 -0
- package/src/commands/code-review.mjs +71 -60
- package/src/commands/decompose.mjs +75 -4
- package/src/commands/doctor.mjs +105 -4
- package/src/commands/implement.mjs +82 -10
- package/src/commands/init.mjs +147 -29
- package/src/commands/merge.mjs +56 -4
- package/src/commands/move.mjs +4 -7
- package/src/commands/order.mjs +2 -2
- package/src/commands/qa-run.mjs +140 -19
- 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/bug-doc.mjs +6 -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/doc-paths.mjs +6 -1
- package/src/lib/flow-run.mjs +14 -3
- package/src/lib/pr-link.mjs +109 -0
- package/src/lib/pr-ready.mjs +146 -0
- package/src/lib/project-root.mjs +51 -0
- package/src/lib/qa-exec.mjs +73 -0
- package/src/lib/qa-report.mjs +172 -8
- 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 +2 -2
- package/src/plugin/skills/merge/SKILL.md +3 -2
- package/src/plugin/skills/qa/SKILL.md +6 -1
- package/src/plugin/skills/qa-executor/SKILL.md +43 -1
- package/src/plugin/skills/setup/SKILL.md +12 -0
- package/src/setup/files.mjs +35 -13
- package/src/templates/skill/SKILL.md +27 -5
- package/src/templates/skill/core.md +5 -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,102 @@
|
|
|
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
|
+
/**
|
|
89
|
+
* Slugs declarados pelas labels de uma issue, na ordem em que aparecem.
|
|
90
|
+
* A label é a fonte de verdade (§3.3) — o campo do board é só espelho.
|
|
91
|
+
* @param {Array<string|{name?: string}>} labels
|
|
92
|
+
*/
|
|
93
|
+
export function repoSlugsFromLabels(labels) {
|
|
94
|
+
const out = [];
|
|
95
|
+
for (const l of labels || []) {
|
|
96
|
+
const name = typeof l === 'string' ? l : l?.name;
|
|
97
|
+
if (!name || !name.startsWith(REPO_LABEL_PREFIX)) continue;
|
|
98
|
+
const slug = name.slice(REPO_LABEL_PREFIX.length);
|
|
99
|
+
if (isValidRepoSlug(slug) && !out.includes(slug)) out.push(slug);
|
|
100
|
+
}
|
|
101
|
+
return out;
|
|
102
|
+
}
|
|
@@ -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
|
|
|
@@ -87,7 +87,7 @@ npx @spec-wave/cli@latest story review <n> # Etapa 👀 Code Review, Status Tod
|
|
|
87
87
|
|
|
88
88
|
Se abre PR e onde faz push depende do **modo de entrega** — o contexto montado já diz qual é (não adivinhe pelo tipo de issue):
|
|
89
89
|
|
|
90
|
-
- **`pr-stack`** (fluxo manual padrão): abra o **Pull Request da Story como rascunho** (`gh pr create --draft`) antes de mover a Story. Numa Feature com várias Stories os PRs ficam **empilhados** (cada um baseado no anterior) — o merge é ordem-dependente; use `spec-wave merge <feature>`, nunca `--delete-branch` manual num PR da pilha.
|
|
90
|
+
- **`pr-stack`** (fluxo manual padrão): abra o **Pull Request da Story como rascunho** (`gh pr create --draft`), com `Closes #<story>` no corpo, antes de mover a Story. Numa Feature com várias Stories os PRs ficam **empilhados** (cada um baseado no anterior) — o merge é ordem-dependente; use `spec-wave merge <feature>`, nunca `--delete-branch` manual num PR da pilha. **Deixe todos em rascunho até o fim:** o rascunho é o sinal de "feature ainda em andamento" (o GitHub bloqueia o merge), e quando a última Story concluir o próprio `implement` marca todos os PRs da Feature como prontos de uma vez. **Não tire nenhum do rascunho à mão.**
|
|
91
91
|
- **`agent`** (rodando sob o `dev-agent`): **NÃO crie branch, NÃO abra PR** — faça só o commit e o push no branch atual. O daemon mantém um único branch (`agent/issue-<n>`) e é ele quem abre o PR ao final, para a Feature inteira. Abrir um PR por Story aqui cria um branch lateral (`agent/issue-<n>-story-<m>`) cujo trabalho não entra no PR do agente.
|
|
92
92
|
|
|
93
93
|
**A Feature só avança** para 👀 Code Review quando **TODAS** as suas Stories já estiverem lá. Enquanto houver Story pendente, deixe a Feature em 🚧 Desenvolvimento. No modo Feature isso acontece dentro da mesma execução.
|
|
@@ -23,14 +23,15 @@ O `implement` empilha os PRs de propósito (cada Story revisável sozinha, diff
|
|
|
23
23
|
|
|
24
24
|
- **Sem `--yes` nada é mergeado** — a saída é o plano: a fila na ordem, qual base será reapontada, o que já está mergeado.
|
|
25
25
|
- O **plano** calcula a ordem pelas fontes locais (dependency-map.json/decomposition.md/corpo — barato); a **execução com `--yes` reconsulta tudo FRESCO da API**, incluindo o blocked_by nativo: merge de pilha é irreversível e não decide com cache.
|
|
26
|
-
- **PR em rascunho bloqueia o plano inteiro
|
|
26
|
+
- **PR em rascunho bloqueia o plano inteiro** — e é assim que se sabe que a feature ainda está em desenvolvimento. Quem tira do rascunho é o `implement`, quando a **última** Story da Feature entra em Code Review: aí todos os PRs da Feature ficam prontos de uma vez. Um PR ainda em rascunho aqui significa que a Feature não terminou (ou que o desrascunho falhou e avisou) — o `merge` não marca por você, de propósito.
|
|
27
27
|
- **Rodar de novo retoma.** PR mergeado sai do plano sozinho; uma falha no meio (check pendente, conflito) para a fila com as branches dos dependentes intactas.
|
|
28
|
+
- **PRs empilhados são achados pelo corpo** quando preciso: o GitHub só registra o vínculo nativo (`closedByPullRequestsReferences`) quando a base do PR é a default — numa pilha, só o PR de baixo. Para Stories sem vínculo nativo, o comando parseia o `Closes #N` do corpo dos PRs abertos (mesma régua do code-review). Garanta que cada PR da pilha tem `Closes #<story>` no corpo.
|
|
28
29
|
- Story **sem PR** vira aviso, não bloqueio — mas se um PR da fila depende do código dela, o merge leva esse código junto; confira antes de confirmar.
|
|
29
30
|
- Cada PR da fila é conferido contra o trailer `Spec-Wave-Story: #<n>` (rastro do `implement`, best-effort — nunca bloqueia): PR sem nenhum commit com o trailer certo vira aviso, vale conferir se é mesmo o trabalho daquela Story antes de mergear.
|
|
30
31
|
|
|
31
32
|
## Passos
|
|
32
33
|
|
|
33
|
-
1. Confirme que os PRs da Feature foram revisados e
|
|
34
|
+
1. Confirme que os PRs da Feature foram revisados e estão fora do rascunho — o `implement` já os marca ao concluir a última Story. Se algum continua em rascunho, confira se a Feature terminou mesmo antes de marcar à mão (`gh pr ready <n>`).
|
|
34
35
|
2. Rode sem `--yes` e apresente o plano ao usuário — ordem, retargets, avisos.
|
|
35
36
|
3. Com o ok, rode com `--yes`.
|
|
36
37
|
4. Confira o desfecho na saída: N PRs mergeados, board em 🧪 QA (o próprio comando confirma as escritas do board; se algum falhar, ele indica o `run --pr` de reparo).
|
|
@@ -30,13 +30,18 @@ Confirme que existe `.spec-wave.json` no repositório (senão → skill **setup*
|
|
|
30
30
|
"command": "claude -p \"Execute o QA descrito em {contextFile}\"",
|
|
31
31
|
"setup": "npm ci && npm run build",
|
|
32
32
|
"env": { "BASE_URL": "http://localhost:3000" },
|
|
33
|
-
"defaultBugPriority": "P2"
|
|
33
|
+
"defaultBugPriority": "P2",
|
|
34
|
+
"platform": "web",
|
|
35
|
+
"web": { "evidence": "playwright" },
|
|
36
|
+
"mobile": { "evidence": "maestro", "appId": "com.exemplo.app", "device": "emulator-5554" }
|
|
34
37
|
}
|
|
35
38
|
}
|
|
36
39
|
```
|
|
37
40
|
|
|
38
41
|
Placeholders: `{contextFile} {qaPlanFile} {specFile} {issue} {type} {title}`. Sem `qa.command`, o comando monta o contexto, imprime como configurar e **não executa** — não é erro.
|
|
39
42
|
|
|
43
|
+
**Evidência visual (opcional):** `qa.platform` (`web` padrão | `mobile`) escolhe quem grava vídeo/foto por cenário — Playwright (`qa.web.evidence`) ou Maestro (`qa.mobile.evidence`, com `appId`/`device`); `"none"` desliga. O executor grava em `.spec-wave/qa-evidence-<n>/cenario-<N>/`, e o `qa` publica em `docs/features/<slug>/qa/cenario-<N>/` (Bug: `docs/bugs/<slug>/qa/`) num commit direto na branch, linkado no relatório e no `bug.md`. Teto de **4 MB por arquivo**; ferramenta ausente só omite a mídia — nunca bloqueia o veredito. O `doctor` confere a plataforma e se a ferramenta está no PATH.
|
|
44
|
+
|
|
40
45
|
## 1. Gerar o plano (Feature)
|
|
41
46
|
|
|
42
47
|
```bash
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: spec-wave-qa-executor
|
|
3
|
-
description: "Use quando você for o agente EXECUTOR de QA do spec-wave — acionado via `qa.command` com um contexto `.spec-wave/qa-<n>.md`. Executa os cenários um a um, registra evidência bruta e grava o veredito em `.spec-wave/qa-result-<n>.json`. NUNCA corrige código nem escreve no GitHub. Gatilhos: 'execute o QA descrito em', contexto de QA do spec-wave, arquivo qa-<n>.md."
|
|
3
|
+
description: "Use quando você for o agente EXECUTOR de QA do spec-wave — acionado via `qa.command` com um contexto `.spec-wave/qa-<n>.md`. Executa os cenários um a um, registra evidência bruta (texto e, quando configurado, vídeo/foto via Maestro ou Playwright) e grava o veredito em `.spec-wave/qa-result-<n>.json`. NUNCA corrige código nem escreve no GitHub. Gatilhos: 'execute o QA descrito em', contexto de QA do spec-wave, arquivo qa-<n>.md."
|
|
4
4
|
allowed-tools:
|
|
5
5
|
- Bash
|
|
6
6
|
- Read
|
|
@@ -67,6 +67,48 @@ caminho exato está no contexto:
|
|
|
67
67
|
- A CLI **recusa** o arquivo fora do contrato (schema em
|
|
68
68
|
`protocol/qa-result.v1.json` do pacote `@spec-wave/cli`) — e arquivo ausente é
|
|
69
69
|
falha alta: nada é aprovado nem reprovado sem ele.
|
|
70
|
+
- `evidenceFiles` é **opcional** — a evidência visual da seção abaixo. Nunca
|
|
71
|
+
substitui `evidencia` (texto), que segue obrigatória nas mesmas regras.
|
|
72
|
+
|
|
73
|
+
## Evidência visual (vídeo/foto)
|
|
74
|
+
|
|
75
|
+
O contexto traz uma seção **Evidência visual** com a plataforma
|
|
76
|
+
(`qa.platform`: `web` | `mobile`), a ferramenta (`playwright` | `maestro` |
|
|
77
|
+
nenhuma), o `appId`/`device` do mobile, a `BASE_URL` do `qa.env` e o diretório
|
|
78
|
+
de **staging** (`.spec-wave/qa-evidence-<n>/`). Você não precisa reler o
|
|
79
|
+
`.spec-wave.json`.
|
|
80
|
+
|
|
81
|
+
1. **Grave por cenário, a partir dos Passos/Critério:**
|
|
82
|
+
- `mobile` → sintetize um **flow Maestro mínimo** para o cenário (abrir o
|
|
83
|
+
`appId`, executar os passos, asserir o esperado) e rode-o **com gravação
|
|
84
|
+
de vídeo**; tire ao menos uma captura do estado final.
|
|
85
|
+
- `web` → sintetize um **script Playwright descartável** (arquivo
|
|
86
|
+
temporário, fora do repositório — **nunca commitado**) contra a
|
|
87
|
+
`BASE_URL`, com vídeo e screenshot habilitados.
|
|
88
|
+
- **Confira as flags/API da versão instalada** (`maestro --help`,
|
|
89
|
+
`maestro record --help`, `npx playwright --version` + docs da versão) —
|
|
90
|
+
as duas ferramentas mudam a gravação entre versões; não assuma.
|
|
91
|
+
2. **Copie os artefatos para `<staging>/cenario-<N>/`** (N = número POSICIONAL
|
|
92
|
+
do cenário), **arquivos planos, sem subpasta**. Nome: letras, dígitos,
|
|
93
|
+
ponto, hífen e sublinhado — sem espaço, sem barra, sem começar com ponto.
|
|
94
|
+
Extensões aceitas: `mp4 webm mov png jpg jpeg gif webp`.
|
|
95
|
+
3. **Teto DURO: 4 MB por arquivo.** A UI serve cada arquivo por uma Lambda
|
|
96
|
+
síncrona; acima disso ela mostra "sem prévia" e a CLI nem publica. Grave
|
|
97
|
+
clipes **curtos e em baixa resolução** (webm ou mp4 comprimido; screenshot
|
|
98
|
+
em png/webp). Se o vídeo passou do teto, recomprima ou corte antes de copiar.
|
|
99
|
+
4. **Referencie em `evidenceFiles`** do cenário, só o **nome** do arquivo:
|
|
100
|
+
|
|
101
|
+
```json
|
|
102
|
+
{ "cenario": 2, "verdict": "fail", "evidencia": "500 — TypeError…",
|
|
103
|
+
"evidenceFiles": ["gravacao.webm", "final.png"] }
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
A CLI copia para `docs/features/<slug>/qa/cenario-<N>/` (ou
|
|
107
|
+
`docs/bugs/<slug>/qa/`), comita na branch e linka no relatório e no bug.md.
|
|
108
|
+
5. **Ferramenta ausente ou gravação que falhou NÃO é `blocked`.** Execute o
|
|
109
|
+
cenário do mesmo jeito, registre a `evidencia` em texto e **omita**
|
|
110
|
+
`evidenceFiles`. Evidência visual é enriquecimento; o veredito nunca depende
|
|
111
|
+
dela. Com a gravação desligada no contexto (`none`), não grave nada.
|
|
70
112
|
|
|
71
113
|
## Setup do ambiente
|
|
72
114
|
|
|
@@ -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 = [
|
|
@@ -293,7 +293,7 @@ Sem flags. Roda um checklist de diagnóstico no repositório atual: token GitHub
|
|
|
293
293
|
| `--yes` | boolean | Executa os merges. **Sem ela, só mostra o plano** (fila na ordem, retargets, avisos). |
|
|
294
294
|
| `--keep-branches` | boolean | Não apaga as branches das Stories após o merge. |
|
|
295
295
|
|
|
296
|
-
> O `implement` empilha os PRs (cada um baseado no anterior) e o merge da pilha é **ordem-dependente**: `--delete-branch` no primeiro PR fecha o segundo. Este comando encapsula a sequência segura — para cada PR na ordem topológica das Stories: reaponta a base para a default, mergeia com **merge commit**, atualiza o board (**merge move até 🧪 QA**) e **só no fim** apaga as branches. **PR em rascunho bloqueia o plano inteiro**
|
|
296
|
+
> O `implement` empilha os PRs (cada um baseado no anterior) e o merge da pilha é **ordem-dependente**: `--delete-branch` no primeiro PR fecha o segundo. Este comando encapsula a sequência segura — para cada PR na ordem topológica das Stories: reaponta a base para a default, mergeia com **merge commit**, atualiza o board (**merge move até 🧪 QA**) e **só no fim** apaga as branches. **PR em rascunho bloqueia o plano inteiro** — e é assim que se sabe que a Feature ainda está em desenvolvimento: quem tira do rascunho é o `implement`, ao concluir a última Story, para todos os PRs da Feature de uma vez. Rodar de novo **retoma**: PR mergeado sai do plano. Use após a revisão, em vez de mergear à mão com `gh`.
|
|
297
297
|
|
|
298
298
|
### `@spec-wave/cli qa <issue>` — executa o plano de QA localmente (e `qa --pr-number <n>` no Action)
|
|
299
299
|
| Flag/Arg | Tipo | Descrição |
|
|
@@ -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
|
|
|
@@ -1096,7 +1109,7 @@ npx @spec-wave/cli@latest story review <n> # Etapa 👀 Code Review, Status Tod
|
|
|
1096
1109
|
|
|
1097
1110
|
Se abre PR e onde faz push depende do **modo de entrega** — o contexto montado já diz qual é (não adivinhe pelo tipo de issue):
|
|
1098
1111
|
|
|
1099
|
-
- **`pr-stack`** (fluxo manual padrão): abra o **Pull Request da Story como rascunho** (`gh pr create --draft`) antes de mover a Story. Numa Feature com várias Stories os PRs ficam **empilhados** (cada um baseado no anterior) — o merge é ordem-dependente; use `spec-wave merge <feature>`, nunca `--delete-branch` manual num PR da pilha.
|
|
1112
|
+
- **`pr-stack`** (fluxo manual padrão): abra o **Pull Request da Story como rascunho** (`gh pr create --draft`), com `Closes #<story>` no corpo, antes de mover a Story. Numa Feature com várias Stories os PRs ficam **empilhados** (cada um baseado no anterior) — o merge é ordem-dependente; use `spec-wave merge <feature>`, nunca `--delete-branch` manual num PR da pilha. **Deixe todos em rascunho até o fim:** o rascunho é o sinal de "feature ainda em andamento" (o GitHub bloqueia o merge), e quando a última Story concluir o próprio `implement` marca todos os PRs da Feature como prontos de uma vez. **Não tire nenhum do rascunho à mão.**
|
|
1100
1113
|
- **`agent`** (rodando sob o `dev-agent`): **NÃO crie branch, NÃO abra PR** — faça só o commit e o push no branch atual. O daemon mantém um único branch (`agent/issue-<n>`) e é ele quem abre o PR ao final, para a Feature inteira. Abrir um PR por Story aqui cria um branch lateral (`agent/issue-<n>-story-<m>`) cujo trabalho não entra no PR do agente.
|
|
1101
1114
|
|
|
1102
1115
|
**A Feature só avança** para 👀 Code Review quando **TODAS** as suas Stories já estiverem lá. Enquanto houver Story pendente, deixe a Feature em 🚧 Desenvolvimento. No modo Feature isso acontece dentro da mesma execução.
|
|
@@ -1139,13 +1152,18 @@ Confirme que existe `.spec-wave.json` no repositório (senão → skill **setup*
|
|
|
1139
1152
|
"command": "claude -p \"Execute o QA descrito em {contextFile}\"",
|
|
1140
1153
|
"setup": "npm ci && npm run build",
|
|
1141
1154
|
"env": { "BASE_URL": "http://localhost:3000" },
|
|
1142
|
-
"defaultBugPriority": "P2"
|
|
1155
|
+
"defaultBugPriority": "P2",
|
|
1156
|
+
"platform": "web",
|
|
1157
|
+
"web": { "evidence": "playwright" },
|
|
1158
|
+
"mobile": { "evidence": "maestro", "appId": "com.exemplo.app", "device": "emulator-5554" }
|
|
1143
1159
|
}
|
|
1144
1160
|
}
|
|
1145
1161
|
```
|
|
1146
1162
|
|
|
1147
1163
|
Placeholders: `{contextFile} {qaPlanFile} {specFile} {issue} {type} {title}`. Sem `qa.command`, o comando monta o contexto, imprime como configurar e **não executa** — não é erro.
|
|
1148
1164
|
|
|
1165
|
+
**Evidência visual (opcional):** `qa.platform` (`web` padrão | `mobile`) escolhe quem grava vídeo/foto por cenário — Playwright (`qa.web.evidence`) ou Maestro (`qa.mobile.evidence`, com `appId`/`device`); `"none"` desliga. O executor grava em `.spec-wave/qa-evidence-<n>/cenario-<N>/`, e o `qa` publica em `docs/features/<slug>/qa/cenario-<N>/` (Bug: `docs/bugs/<slug>/qa/`) num commit direto na branch, linkado no relatório e no `bug.md`. Teto de **4 MB por arquivo**; ferramenta ausente só omite a mídia — nunca bloqueia o veredito. O `doctor` confere a plataforma e se a ferramenta está no PATH.
|
|
1166
|
+
|
|
1149
1167
|
#### 1. Gerar o plano (Feature)
|
|
1150
1168
|
|
|
1151
1169
|
```bash
|
|
@@ -1535,7 +1553,7 @@ utilitários de board estão flag a flag na *Referência da CLI* acima. Rode
|
|
|
1535
1553
|
- **`merge`** — Use para mergear os PRs empilhados das Stories de uma Feature do spec-wave, na ordem das dependências, movendo o board até 🧪 QA. Gatilhos: 'mergeia os PRs da feature 12', 'integra as stories', 'os PRs estão revisados, pode mergear', 'qual a ordem de merge?'. Use DEPOIS da revisão humana (PRs marcados como prontos). NÃO mergeie PRs de pilha à mão com --delete-branch — é o que fecha o PR dependente.
|
|
1536
1554
|
- **`run`** — Use para conduzir o fluxo do spec-wave LOCALMENTE, sem gastar minutos de GitHub Actions: `spec-wave run <issue>` executa nesta máquina o passo que a label dispararia (spec, plan, crítica, validate, decompose, apply) e `spec-wave mode local|actions` alterna entre os dois mundos. Gatilhos: 'rodar o spec-wave local', 'qual o próximo passo da issue 12', 'sem gastar Actions', 'desligar os workflows', 'trocar para execução local'.
|
|
1537
1555
|
- **`qa-lead`** — Use para orquestrar o QA de uma TRILHA inteira (milestone) do spec-wave — preparar os planos de todas as Features (`qa-lead plan`), executar o ciclo com containers paralelos (`qa-lead run`) e consultar relatórios de ciclo (`qa-lead report`). Gatilhos: 'rodar o QA do milestone', 'QA da release', 'trilha de QA', 'relatório de QA do ciclo'.
|
|
1538
|
-
- **`qa-executor`** — Use quando você for o agente EXECUTOR de QA do spec-wave — acionado via `qa.command` com um contexto `.spec-wave/qa-<n>.md`. Executa os cenários um a um, registra evidência bruta e grava o veredito em `.spec-wave/qa-result-<n>.json`. NUNCA corrige código nem escreve no GitHub. Gatilhos: 'execute o QA descrito em', contexto de QA do spec-wave, arquivo qa-<n>.md.
|
|
1556
|
+
- **`qa-executor`** — Use quando você for o agente EXECUTOR de QA do spec-wave — acionado via `qa.command` com um contexto `.spec-wave/qa-<n>.md`. Executa os cenários um a um, registra evidência bruta (texto e, quando configurado, vídeo/foto via Maestro ou Playwright) e grava o veredito em `.spec-wave/qa-result-<n>.json`. NUNCA corrige código nem escreve no GitHub. Gatilhos: 'execute o QA descrito em', contexto de QA do spec-wave, arquivo qa-<n>.md.
|
|
1539
1557
|
- **`task`** — Use para iniciar ou concluir uma Task do spec-wave no board: task start move para 🚧 Desenvolvimento com Status In Progress, task done move para 🎉 Done. Gatilhos: 'comecei a task 56', 'terminei a task 56', 'marcar task como feita'. Prefira sempre este comando a mexer no board via GraphQL ou gh — ele embute a regra de uma única Task In Progress por Story.
|
|
1540
1558
|
- **`story`** — Use para mandar uma Story do spec-wave para 👀 Code Review depois de implementar todas as suas Tasks e abrir o PR. Gatilhos: 'terminei a story 34', 'mandar a story para review', 'story pronta para code review'. Prefira este comando a mutações GraphQL manuais no board.
|
|
1541
1559
|
- **`move`** — Use para mover qualquer item do board spec-wave — Feature, Story, Task, Bug ou RFC — para uma Etapa, quando task start|done e story review não cobrem o movimento (ex.: mover uma Feature para Homologação ou Deploy). Gatilhos: 'mover a feature 12 para homologação', 'passar para deploy', 'avançar o card'. Prefira este comando a gh api graphql manual: a Etapa nunca retrocede, e isso é regra do fluxo, não limitação.
|
|
@@ -1617,6 +1635,10 @@ docs/
|
|
|
1617
1635
|
escrito pelo decompose --apply e atualizado por
|
|
1618
1636
|
`order --sync`. É o que deixa order/implement/merge
|
|
1619
1637
|
consultarem a ordem sem pagar a API por Story
|
|
1638
|
+
qa/
|
|
1639
|
+
cenario-<n>/ ← evidência VISUAL (vídeo/foto) do cenário N, publicada
|
|
1640
|
+
por `spec-wave qa` (Maestro no mobile, Playwright na
|
|
1641
|
+
web); arquivos planos, ≤ 4 MB cada. Bug: docs/bugs/<slug>/qa/
|
|
1620
1642
|
rfcs/
|
|
1621
1643
|
<slug-do-rfc>/
|
|
1622
1644
|
decomposition.md ← mesmo papel, com "## Task N" (RFC não usa spec/plan)
|