@spec-wave/cli 1.0.2 → 1.0.4

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 (37) hide show
  1. package/package.json +1 -1
  2. package/src/api/auth.mjs +29 -1
  3. package/src/commands/code-review.mjs +3 -1
  4. package/src/commands/decompose.mjs +1 -1
  5. package/src/commands/doctor.mjs +54 -20
  6. package/src/commands/generate-bug.mjs +1 -0
  7. package/src/commands/generate-plan.mjs +1 -0
  8. package/src/commands/generate-qa-plan.mjs +1 -0
  9. package/src/commands/generate-spec.mjs +1 -0
  10. package/src/commands/implement.mjs +31 -3
  11. package/src/commands/init.mjs +4 -1
  12. package/src/commands/merge.mjs +157 -59
  13. package/src/commands/run.mjs +16 -0
  14. package/src/commands/workspace.mjs +5 -1
  15. package/src/lib/claude.mjs +14 -0
  16. package/src/lib/pr-ready.mjs +43 -21
  17. package/src/lib/workspace.mjs +64 -0
  18. package/src/plugin/.claude-plugin/plugin.json +1 -1
  19. package/src/plugin/skills/bug/model-prompt.md +2 -0
  20. package/src/plugin/skills/decompose/model-prompt.feature.md +2 -0
  21. package/src/plugin/skills/decompose/model-prompt.rfc.md +2 -0
  22. package/src/plugin/skills/merge/SKILL.md +1 -0
  23. package/src/plugin/skills/plan/model-prompt.md +2 -0
  24. package/src/plugin/skills/qa/model-prompt.md +2 -0
  25. package/src/plugin/skills/setup/SKILL.md +9 -0
  26. package/src/plugin/skills/spec/model-prompt.md +2 -0
  27. package/src/templates/skill/SKILL.md +9 -0
  28. package/src/templates/workflows/code/code-review.yml +25 -7
  29. package/src/templates/workflows/code/qa.yml +24 -6
  30. package/src/templates/workflows/code-review.yml +16 -1
  31. package/src/templates/workflows/decompose.yml +30 -2
  32. package/src/templates/workflows/generate-bug.yml +27 -1
  33. package/src/templates/workflows/generate-plan.yml +27 -1
  34. package/src/templates/workflows/generate-qa-plan.yml +28 -2
  35. package/src/templates/workflows/generate-spec.yml +27 -1
  36. package/src/templates/workflows/pr-events.yml +35 -8
  37. package/src/templates/workflows/qa.yml +15 -1
@@ -24,6 +24,8 @@ Um RFC não passa por spec/plan — ele é a proposta em si. Por isso não há c
24
24
  ## Exploração antes de decompor
25
25
 
26
26
  Você tem `Read`, `Glob` e `Grep` no repositório. Um RFC quase sempre descreve mudança em algo que já existe — localize esse algo antes de listar tasks, e nomeie na `body` os arquivos e áreas que cada task vai tocar.
27
+
28
+ Se a entrada trouxer a seção **Workspace multi-repo**, o código NÃO está neste repositório (o hub só guarda documentação): está nos diretórios listados ali, um por repositório de código. Aponte `Glob`/`Grep`/`Read` para esses caminhos absolutos (parâmetro `path`) — a partir da raiz do hub eles ficam fora da busca.
27
29
  <!-- /requires-tools -->
28
30
  ## Contrato de saída
29
31
 
@@ -26,6 +26,7 @@ O `implement` empilha os PRs de propósito (cada Story revisável sozinha, diff
26
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
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.
29
+ - **Multi-repo (RFC-005): a pilha é POR REPOSITÓRIO.** Uma Story que declara N repos (labels `repo:<slug>`) tem N PRs — um por repositório, cada um com `Closes <owner>/<hub>#<story>` no corpo — e isso não é ambíguo; ambíguo é mais de um PR aberto no **mesmo** repositório. O comando lista os PRs abertos do hub e de cada repo de código da Feature, reaponta a base para a default **daquele** repo, mergeia lá, apaga a branch lá e move o board com `--pr-repo`. A head de um PR só é base válida no mesmo repositório (Story 1 no `api` e Story 2 no `web` são duas raízes). Entre o primeiro e o último PR de uma Story cross-repo existe uma janela em que `api` já mergeou e `web` não — aceita conscientemente (§3.4); uma falha no meio para a fila e rodar de novo retoma.
29
30
  - 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.
30
31
  - 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.
31
32
 
@@ -26,6 +26,8 @@ Você recebe um payload JSON com:
26
26
  Você tem `Read`, `Glob` e `Grep` no repositório de destino. Use-os: localize os módulos, endpoints, migrations e componentes que esta Feature vai tocar, e ancore o plano nos **caminhos e nomes reais** que encontrar. Um plano que cita `src/services/pedido.ts` porque leu o arquivo vale muito mais que um que inventa `PedidoService`.
27
27
 
28
28
  O `tech_context` continua sendo a fronteira do que você pode propor — explorar o repositório serve para ser preciso dentro dela, não para ampliá-la.
29
+
30
+ Se a entrada trouxer a seção **Workspace multi-repo**, o código NÃO está neste repositório (o hub só guarda documentação): está nos diretórios listados ali, um por repositório de código. Aponte `Glob`/`Grep`/`Read` para esses caminhos absolutos (parâmetro `path`) — a partir da raiz do hub eles ficam fora da busca — e, no detalhamento por camada, diga em qual repositório cada mudança acontece.
29
31
  <!-- /requires-tools -->
30
32
  ## Estrutura obrigatória
31
33
 
@@ -59,6 +59,8 @@ Regras do formato:
59
59
  ## Exploração antes de escrever
60
60
 
61
61
  Você tem `Read`, `Glob` e `Grep` no repositório. Use-os para ancorar os passos no que existe de verdade: os endpoints reais (rotas registradas), os comandos reais (scripts do package.json, Makefile), os seeds/fixtures disponíveis. Um passo `GET /api/pedidos` só vale se essa rota existe com esse nome. Não gaste mais do que o necessário: explore o suficiente para os passos serem executáveis, e então escreva o documento completo.
62
+
63
+ Se a entrada trouxer a seção **Workspace multi-repo**, o código NÃO está neste repositório (o hub só guarda documentação): está nos diretórios listados ali, um por repositório de código. Aponte `Glob`/`Grep`/`Read` para esses caminhos absolutos (parâmetro `path`) — a partir da raiz do hub eles ficam fora da busca — e diga em qual repositório cada cenário roda.
62
64
  <!-- /requires-tools -->
63
65
 
64
66
  ## O que NÃO fazer
@@ -45,6 +45,15 @@ npx @spec-wave/cli@latest repo list
45
45
 
46
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>`.
47
47
 
48
+ ### Autenticação dos workflows: GitHub App ou PATs
49
+
50
+ Os workflows precisam de um token que atravesse repositórios e mexa no Project. Dois modos, e o `doctor` diz qual está em uso:
51
+
52
+ - **GitHub App da organização** (preferido): secrets `SPEC_WAVE_APP_ID` e `SPEC_WAVE_APP_PRIVATE_KEY` (PEM completo) no hub **e** nos repos de código, com a App instalada em todos eles. Permissões mínimas: Issues RW, Contents RW, Pull requests RW, Metadata R, Projects (org) RW. Cada workflow gera um token por run (`actions/create-github-app-token`) — quem sai da org não derruba o fluxo, e `GH_PR_TOKEN` deixa de ser necessário (PR aberto por App dispara workflows).
53
+ - **PATs** (modo original): `GH_PROJECT_TOKEN` (escopos `repo` + `project`), `GH_PR_TOKEN` quando a org proíbe o `GITHUB_TOKEN` de abrir PR, e `SPEC_WAVE_HUB_TOKEN` no repo de código. Com a App configurada, esses viram fallback.
54
+
55
+ `init` e `doctor` aceitam token de instalação de App (`ghs_…`) — sem escopos legíveis, a verificação é funcional (acesso ao repo e ao Project).
56
+
48
57
  ## Passos
49
58
 
50
59
  1. **Já configurado?** Leia `.spec-wave.json` (Read) ou rode `npx @spec-wave/cli@latest info`. Se existir, mostre `project.url` e `version` e **confirme com o usuário** antes de reconfigurar.
@@ -25,6 +25,8 @@ Você recebe um payload JSON com:
25
25
  Você tem `Read`, `Glob` e `Grep` no repositório de destino. Antes de escrever qualquer seção, procure o que já existe: specs de features vizinhas em `docs/features/`, modelos de domínio, endpoints e telas relacionados. Uma spec ancorada no que o sistema já faz vale mais que uma escrita no vácuo.
26
26
 
27
27
  Isso **não** autoriza inventar regras a partir do código: o código mostra o que existe, não o que o negócio quer. Continue marcando lacunas de negócio com `[TODO: requer esclarecimento do PO]`.
28
+
29
+ Se a entrada trouxer a seção **Workspace multi-repo**, o código NÃO está neste repositório (o hub só guarda documentação): está nos diretórios listados ali, um por repositório de código. Aponte `Glob`/`Grep`/`Read` para esses caminhos absolutos (parâmetro `path`) — a partir da raiz do hub eles ficam fora da busca. As specs vizinhas continuam em `docs/features/` do hub.
28
30
  <!-- /requires-tools -->
29
31
 
30
32
  ## Estrutura obrigatória
@@ -569,6 +569,15 @@ npx @spec-wave/cli@latest repo list
569
569
 
570
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>`.
571
571
 
572
+ ##### Autenticação dos workflows: GitHub App ou PATs
573
+
574
+ Os workflows precisam de um token que atravesse repositórios e mexa no Project. Dois modos, e o `doctor` diz qual está em uso:
575
+
576
+ - **GitHub App da organização** (preferido): secrets `SPEC_WAVE_APP_ID` e `SPEC_WAVE_APP_PRIVATE_KEY` (PEM completo) no hub **e** nos repos de código, com a App instalada em todos eles. Permissões mínimas: Issues RW, Contents RW, Pull requests RW, Metadata R, Projects (org) RW. Cada workflow gera um token por run (`actions/create-github-app-token`) — quem sai da org não derruba o fluxo, e `GH_PR_TOKEN` deixa de ser necessário (PR aberto por App dispara workflows).
577
+ - **PATs** (modo original): `GH_PROJECT_TOKEN` (escopos `repo` + `project`), `GH_PR_TOKEN` quando a org proíbe o `GITHUB_TOKEN` de abrir PR, e `SPEC_WAVE_HUB_TOKEN` no repo de código. Com a App configurada, esses viram fallback.
578
+
579
+ `init` e `doctor` aceitam token de instalação de App (`ghs_…`) — sem escopos legíveis, a verificação é funcional (acesso ao repo e ao Project).
580
+
572
581
  #### Passos
573
582
 
574
583
  1. **Já configurado?** Leia `.spec-wave.json` (Read) ou rode `npx @spec-wave/cli@latest info`. Se existir, mostre `project.url` e `version` e **confirme com o usuário** antes de reconfigurar.
@@ -12,9 +12,11 @@ name: Code Review
12
12
  # template empacotado, e um hub embutido o marcaria como desatualizado para
13
13
  # sempre.
14
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.
15
+ # Token para despachar (o repository_dispatch exige escrita em Contents NO
16
+ # HUB; o GITHUB_TOKEN só enxerga este repositório): a GitHub App da
17
+ # organização (SPEC_WAVE_APP_ID + SPEC_WAVE_APP_PRIVATE_KEY, instalada nos
18
+ # dois repos) emite um token restrito ao hub; sem ela, o secret
19
+ # SPEC_WAVE_HUB_TOKEN (PAT) continua valendo.
18
20
  on:
19
21
  pull_request:
20
22
  types: [opened, reopened]
@@ -23,6 +25,10 @@ concurrency:
23
25
  group: spec-wave-dispatch-${{ github.event.pull_request.number }}
24
26
  cancel-in-progress: false
25
27
 
28
+ # `secrets` não entra em `if`; a presença da GitHub App vira env.
29
+ env:
30
+ SPEC_WAVE_APP_PRESENT: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY != '' }}
31
+
26
32
  jobs:
27
33
  dispatch:
28
34
  # PR de documento (`spec-wave/*`) não é PR de implementação.
@@ -37,12 +43,24 @@ jobs:
37
43
  - id: hub
38
44
  name: Lê o hub do .spec-wave.json
39
45
  run: |
40
- hub="$(jq -r '"\(.hub.owner // "")/\(.hub.repo // "")"' .spec-wave.json)"
41
- if [ "$hub" = "/" ]; then
46
+ owner="$(jq -r '.hub.owner // ""' .spec-wave.json)"
47
+ name="$(jq -r '.hub.repo // ""' .spec-wave.json)"
48
+ if [ -z "$owner" ] || [ -z "$name" ]; then
42
49
  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
50
  exit 1
44
51
  fi
45
- echo "repo=$hub" >> "$GITHUB_OUTPUT"
52
+ echo "owner=$owner" >> "$GITHUB_OUTPUT"
53
+ echo "name=$name" >> "$GITHUB_OUTPUT"
54
+ echo "repo=$owner/$name" >> "$GITHUB_OUTPUT"
55
+
56
+ - id: app
57
+ if: env.SPEC_WAVE_APP_PRESENT == 'true'
58
+ uses: actions/create-github-app-token@v2
59
+ with:
60
+ app-id: ${{ secrets.SPEC_WAVE_APP_ID }}
61
+ private-key: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY }}
62
+ owner: ${{ steps.hub.outputs.owner }}
63
+ repositories: ${{ steps.hub.outputs.name }}
46
64
 
47
65
  - name: Avisa o hub (repository_dispatch)
48
66
  run: |
@@ -57,4 +75,4 @@ jobs:
57
75
  }
58
76
  PAYLOAD
59
77
  env:
60
- GH_TOKEN: ${{ secrets.SPEC_WAVE_HUB_TOKEN }}
78
+ GH_TOKEN: ${{ steps.app.outputs.token || secrets.SPEC_WAVE_HUB_TOKEN }}
@@ -6,8 +6,10 @@ name: QA
6
6
  # de review e de merge acontecem SÓ aqui, no repo do PR.
7
7
  #
8
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.
9
+ # que explica por que o YAML não pode carimbá-lo). Token para despachar: a
10
+ # GitHub App da organização (SPEC_WAVE_APP_ID + SPEC_WAVE_APP_PRIVATE_KEY),
11
+ # quando configurada; senão o secret SPEC_WAVE_HUB_TOKEN (PAT com escrita em
12
+ # Contents no hub).
11
13
  on:
12
14
  pull_request_review:
13
15
  types: [submitted]
@@ -18,6 +20,10 @@ concurrency:
18
20
  group: spec-wave-dispatch-qa-${{ github.event.pull_request.number }}
19
21
  cancel-in-progress: false
20
22
 
23
+ # `secrets` não entra em `if`; a presença da GitHub App vira env.
24
+ env:
25
+ SPEC_WAVE_APP_PRESENT: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY != '' }}
26
+
21
27
  jobs:
22
28
  dispatch:
23
29
  # PR de documento (`spec-wave/*`) não é PR de implementação, e aprovar o
@@ -36,12 +42,24 @@ jobs:
36
42
  - id: hub
37
43
  name: Lê o hub do .spec-wave.json
38
44
  run: |
39
- hub="$(jq -r '"\(.hub.owner // "")/\(.hub.repo // "")"' .spec-wave.json)"
40
- if [ "$hub" = "/" ]; then
45
+ owner="$(jq -r '.hub.owner // ""' .spec-wave.json)"
46
+ name="$(jq -r '.hub.repo // ""' .spec-wave.json)"
47
+ if [ -z "$owner" ] || [ -z "$name" ]; then
41
48
  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
49
  exit 1
43
50
  fi
44
- echo "repo=$hub" >> "$GITHUB_OUTPUT"
51
+ echo "owner=$owner" >> "$GITHUB_OUTPUT"
52
+ echo "name=$name" >> "$GITHUB_OUTPUT"
53
+ echo "repo=$owner/$name" >> "$GITHUB_OUTPUT"
54
+
55
+ - id: app
56
+ if: env.SPEC_WAVE_APP_PRESENT == 'true'
57
+ uses: actions/create-github-app-token@v2
58
+ with:
59
+ app-id: ${{ secrets.SPEC_WAVE_APP_ID }}
60
+ private-key: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY }}
61
+ owner: ${{ steps.hub.outputs.owner }}
62
+ repositories: ${{ steps.hub.outputs.name }}
45
63
 
46
64
  - name: Avisa o hub (repository_dispatch)
47
65
  run: |
@@ -56,4 +74,4 @@ jobs:
56
74
  }
57
75
  PAYLOAD
58
76
  env:
59
- GH_TOKEN: ${{ secrets.SPEC_WAVE_HUB_TOKEN }}
77
+ GH_TOKEN: ${{ steps.app.outputs.token || secrets.SPEC_WAVE_HUB_TOKEN }}
@@ -67,6 +67,9 @@ jobs:
67
67
  issues: write
68
68
  pull-requests: write
69
69
  contents: read
70
+ # `secrets` não entra em `if`; a presença da GitHub App vira env do job.
71
+ env:
72
+ SPEC_WAVE_APP_PRESENT: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY != '' }}
70
73
 
71
74
  steps:
72
75
  - uses: actions/checkout@v5
@@ -78,9 +81,21 @@ jobs:
78
81
  - name: Instala a CLI
79
82
  run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
80
83
 
84
+ # Token de GitHub App da organização, quando configurada
85
+ # (SPEC_WAVE_APP_ID + SPEC_WAVE_APP_PRIVATE_KEY): substitui os PATs
86
+ # pessoais — quem sai da org não derruba o fluxo. Sem os secrets o step
87
+ # é pulado, `steps.app.outputs.token` fica vazio e os PATs continuam
88
+ # valendo pelo `||` abaixo.
89
+ - id: app
90
+ if: env.SPEC_WAVE_APP_PRESENT == 'true'
91
+ uses: actions/create-github-app-token@v2
92
+ with:
93
+ app-id: ${{ secrets.SPEC_WAVE_APP_ID }}
94
+ private-key: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY }}
95
+
81
96
  - name: Move Feature to Code Review
82
97
  run: spec-wave code-review --pr-number ${{ github.event.pull_request.number }}
83
98
  env:
84
99
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
85
- PROJECT_TOKEN: ${{ secrets.GH_PROJECT_TOKEN }}
100
+ PROJECT_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN }}
86
101
  GITHUB_REPOSITORY: ${{ github.repository }}
@@ -68,6 +68,9 @@ jobs:
68
68
  # approve pull requests" estiver ligado (Settings → Actions → General) —
69
69
  # desligado por padrão em muitas organizações. `GH_PR_TOKEN` é a saída.
70
70
  pull-requests: write
71
+ # `secrets` não entra em `if`; a presença da GitHub App vira env do job.
72
+ env:
73
+ SPEC_WAVE_APP_PRESENT: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY != '' }}
71
74
 
72
75
  steps:
73
76
  - uses: actions/checkout@v5
@@ -81,6 +84,31 @@ jobs:
81
84
  - name: Instala a CLI
82
85
  run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
83
86
 
87
+ # Token de GitHub App da organização, quando configurada
88
+ # (SPEC_WAVE_APP_ID + SPEC_WAVE_APP_PRIVATE_KEY): substitui os PATs
89
+ # pessoais — quem sai da org não derruba o fluxo. Sem os secrets o step
90
+ # é pulado, `steps.app.outputs.token` fica vazio e os PATs continuam
91
+ # valendo pelo `||` abaixo.
92
+ - id: app
93
+ if: env.SPEC_WAVE_APP_PRESENT == 'true'
94
+ uses: actions/create-github-app-token@v2
95
+ with:
96
+ app-id: ${{ secrets.SPEC_WAVE_APP_ID }}
97
+ private-key: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY }}
98
+
99
+ # Multi-repo (RFC-005 §7.2): clona em .spec-wave/repos/<slug>/ os repos
100
+ # de código que a issue declara (labels repo:<slug>; a Feature agrega as
101
+ # Stories), para o modelo ler CÓDIGO e não só o markdown do hub. Só no
102
+ # RASCUNHO — o apply não chama o modelo. Sem repo declarado só avisa. O
103
+ # GITHUB_TOKEN só enxerga este repositório — para clonar os outros vai o
104
+ # GH_PROJECT_TOKEN, quando existir.
105
+ - name: Monta o workspace multi-repo
106
+ if: github.event.label.name != 'spec-wave:decompose-apply'
107
+ run: spec-wave workspace prepare --issue ${{ github.event.issue.number }}
108
+ env:
109
+ GITHUB_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN || secrets.GITHUB_TOKEN }}
110
+ GITHUB_REPOSITORY: ${{ github.repository }}
111
+
84
112
  - name: Decompose into Stories and Tasks
85
113
  run: >
86
114
  spec-wave decompose
@@ -88,8 +116,8 @@ jobs:
88
116
  ${{ github.event.label.name == 'spec-wave:decompose-apply' && '--apply' || '' }}
89
117
  env:
90
118
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
91
- GH_PR_TOKEN: ${{ secrets.GH_PR_TOKEN }}
92
- PROJECT_TOKEN: ${{ secrets.GH_PROJECT_TOKEN }}
119
+ GH_PR_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PR_TOKEN }}
120
+ PROJECT_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN }}
93
121
  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
94
122
  CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
95
123
  OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
@@ -52,6 +52,9 @@ jobs:
52
52
  # approve pull requests" estiver ligado (Settings → Actions → General) —
53
53
  # desligado por padrão em muitas organizações. `GH_PR_TOKEN` é a saída.
54
54
  pull-requests: write
55
+ # `secrets` não entra em `if`; a presença da GitHub App vira env do job.
56
+ env:
57
+ SPEC_WAVE_APP_PRESENT: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY != '' }}
55
58
 
56
59
  steps:
57
60
  - uses: actions/checkout@v5
@@ -65,11 +68,34 @@ jobs:
65
68
  - name: Instala a CLI
66
69
  run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
67
70
 
71
+ # Token de GitHub App da organização, quando configurada
72
+ # (SPEC_WAVE_APP_ID + SPEC_WAVE_APP_PRIVATE_KEY): substitui os PATs
73
+ # pessoais — quem sai da org não derruba o fluxo. Sem os secrets o step
74
+ # é pulado, `steps.app.outputs.token` fica vazio e os PATs continuam
75
+ # valendo pelo `||` abaixo.
76
+ - id: app
77
+ if: env.SPEC_WAVE_APP_PRESENT == 'true'
78
+ uses: actions/create-github-app-token@v2
79
+ with:
80
+ app-id: ${{ secrets.SPEC_WAVE_APP_ID }}
81
+ private-key: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY }}
82
+
83
+ # Multi-repo (RFC-005 §7.2): clona em .spec-wave/repos/<slug>/ os repos
84
+ # de código que a issue declara (labels repo:<slug>), para o modelo ler
85
+ # CÓDIGO e não só o markdown do hub. Sem repo declarado só avisa. O
86
+ # GITHUB_TOKEN só enxerga este repositório — para clonar os outros vai o
87
+ # GH_PROJECT_TOKEN, quando existir.
88
+ - name: Monta o workspace multi-repo
89
+ run: spec-wave workspace prepare --issue ${{ github.event.issue.number }}
90
+ env:
91
+ GITHUB_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN || secrets.GITHUB_TOKEN }}
92
+ GITHUB_REPOSITORY: ${{ github.repository }}
93
+
68
94
  - name: Generate bug.md
69
95
  run: spec-wave generate-bug --issue-number ${{ github.event.issue.number }}
70
96
  env:
71
97
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
72
- GH_PR_TOKEN: ${{ secrets.GH_PR_TOKEN }}
98
+ GH_PR_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PR_TOKEN }}
73
99
  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
74
100
  CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
75
101
  OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
@@ -62,6 +62,9 @@ jobs:
62
62
  # approve pull requests" estiver ligado (Settings → Actions → General) —
63
63
  # desligado por padrão em muitas organizações. `GH_PR_TOKEN` é a saída.
64
64
  pull-requests: write
65
+ # `secrets` não entra em `if`; a presença da GitHub App vira env do job.
66
+ env:
67
+ SPEC_WAVE_APP_PRESENT: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY != '' }}
65
68
 
66
69
  steps:
67
70
  - uses: actions/checkout@v5
@@ -75,11 +78,34 @@ jobs:
75
78
  - name: Instala a CLI
76
79
  run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
77
80
 
81
+ # Token de GitHub App da organização, quando configurada
82
+ # (SPEC_WAVE_APP_ID + SPEC_WAVE_APP_PRIVATE_KEY): substitui os PATs
83
+ # pessoais — quem sai da org não derruba o fluxo. Sem os secrets o step
84
+ # é pulado, `steps.app.outputs.token` fica vazio e os PATs continuam
85
+ # valendo pelo `||` abaixo.
86
+ - id: app
87
+ if: env.SPEC_WAVE_APP_PRESENT == 'true'
88
+ uses: actions/create-github-app-token@v2
89
+ with:
90
+ app-id: ${{ secrets.SPEC_WAVE_APP_ID }}
91
+ private-key: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY }}
92
+
93
+ # Multi-repo (RFC-005 §7.2): clona em .spec-wave/repos/<slug>/ os repos
94
+ # de código que a issue declara (labels repo:<slug>; a Feature agrega as
95
+ # Stories), para o modelo ler CÓDIGO e não só o markdown do hub. Sem repo
96
+ # declarado só avisa. O GITHUB_TOKEN só enxerga este repositório — para
97
+ # clonar os outros vai o GH_PROJECT_TOKEN, quando existir.
98
+ - name: Monta o workspace multi-repo
99
+ run: spec-wave workspace prepare --issue ${{ github.event.issue.number }}
100
+ env:
101
+ GITHUB_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN || secrets.GITHUB_TOKEN }}
102
+ GITHUB_REPOSITORY: ${{ github.repository }}
103
+
78
104
  - name: Generate plan.md
79
105
  run: spec-wave generate-plan --issue-number ${{ github.event.issue.number }}
80
106
  env:
81
107
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
82
- GH_PR_TOKEN: ${{ secrets.GH_PR_TOKEN }}
108
+ GH_PR_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PR_TOKEN }}
83
109
  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
84
110
  CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
85
111
  OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
@@ -39,6 +39,9 @@ jobs:
39
39
  # `pull-requests: write` o commit existe e o PR não.
40
40
  contents: write
41
41
  pull-requests: write
42
+ # `secrets` não entra em `if`; a presença da GitHub App vira env do job.
43
+ env:
44
+ SPEC_WAVE_APP_PRESENT: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY != '' }}
42
45
 
43
46
  steps:
44
47
  - uses: actions/checkout@v5
@@ -52,12 +55,35 @@ jobs:
52
55
  - name: Instala a CLI
53
56
  run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
54
57
 
58
+ # Token de GitHub App da organização, quando configurada
59
+ # (SPEC_WAVE_APP_ID + SPEC_WAVE_APP_PRIVATE_KEY): substitui os PATs
60
+ # pessoais — quem sai da org não derruba o fluxo. Sem os secrets o step
61
+ # é pulado, `steps.app.outputs.token` fica vazio e os PATs continuam
62
+ # valendo pelo `||` abaixo.
63
+ - id: app
64
+ if: env.SPEC_WAVE_APP_PRESENT == 'true'
65
+ uses: actions/create-github-app-token@v2
66
+ with:
67
+ app-id: ${{ secrets.SPEC_WAVE_APP_ID }}
68
+ private-key: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY }}
69
+
70
+ # Multi-repo (RFC-005 §7.2): clona em .spec-wave/repos/<slug>/ os repos
71
+ # de código que a issue declara (labels repo:<slug>; a Feature agrega as
72
+ # Stories), para o modelo ler CÓDIGO e não só o markdown do hub. Sem repo
73
+ # declarado só avisa. O GITHUB_TOKEN só enxerga este repositório — para
74
+ # clonar os outros vai o GH_PROJECT_TOKEN, quando existir.
75
+ - name: Monta o workspace multi-repo
76
+ run: spec-wave workspace prepare --issue ${{ github.event.issue.number }}
77
+ env:
78
+ GITHUB_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN || secrets.GITHUB_TOKEN }}
79
+ GITHUB_REPOSITORY: ${{ github.repository }}
80
+
55
81
  - name: Generate QA plan
56
82
  run: spec-wave generate-qa-plan --issue-number ${{ github.event.issue.number }}
57
83
  env:
58
84
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
59
- GH_PR_TOKEN: ${{ secrets.GH_PR_TOKEN }}
60
- PROJECT_TOKEN: ${{ secrets.GH_PROJECT_TOKEN }}
85
+ GH_PR_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PR_TOKEN }}
86
+ PROJECT_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN }}
61
87
  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
62
88
  CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
63
89
  OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
@@ -62,6 +62,9 @@ jobs:
62
62
  # approve pull requests" estiver ligado (Settings → Actions → General) —
63
63
  # desligado por padrão em muitas organizações. `GH_PR_TOKEN` é a saída.
64
64
  pull-requests: write
65
+ # `secrets` não entra em `if`; a presença da GitHub App vira env do job.
66
+ env:
67
+ SPEC_WAVE_APP_PRESENT: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY != '' }}
65
68
 
66
69
  steps:
67
70
  - uses: actions/checkout@v5
@@ -75,11 +78,34 @@ jobs:
75
78
  - name: Instala a CLI
76
79
  run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
77
80
 
81
+ # Token de GitHub App da organização, quando configurada
82
+ # (SPEC_WAVE_APP_ID + SPEC_WAVE_APP_PRIVATE_KEY): substitui os PATs
83
+ # pessoais — quem sai da org não derruba o fluxo. Sem os secrets o step
84
+ # é pulado, `steps.app.outputs.token` fica vazio e os PATs continuam
85
+ # valendo pelo `||` abaixo.
86
+ - id: app
87
+ if: env.SPEC_WAVE_APP_PRESENT == 'true'
88
+ uses: actions/create-github-app-token@v2
89
+ with:
90
+ app-id: ${{ secrets.SPEC_WAVE_APP_ID }}
91
+ private-key: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY }}
92
+
93
+ # Multi-repo (RFC-005 §7.2): clona em .spec-wave/repos/<slug>/ os repos
94
+ # de código que a issue declara (labels repo:<slug>; a Feature agrega as
95
+ # Stories), para o modelo ler CÓDIGO e não só o markdown do hub. Sem repo
96
+ # declarado só avisa. O GITHUB_TOKEN só enxerga este repositório — para
97
+ # clonar os outros vai o GH_PROJECT_TOKEN, quando existir.
98
+ - name: Monta o workspace multi-repo
99
+ run: spec-wave workspace prepare --issue ${{ github.event.issue.number }}
100
+ env:
101
+ GITHUB_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN || secrets.GITHUB_TOKEN }}
102
+ GITHUB_REPOSITORY: ${{ github.repository }}
103
+
78
104
  - name: Generate spec.md
79
105
  run: spec-wave generate-spec --issue-number ${{ github.event.issue.number }}
80
106
  env:
81
107
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
82
- GH_PR_TOKEN: ${{ secrets.GH_PR_TOKEN }}
108
+ GH_PR_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PR_TOKEN }}
83
109
  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
84
110
  CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
85
111
  OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
@@ -8,9 +8,11 @@ name: PR Events
8
8
  # nunca dispara e não custa nada.
9
9
  #
10
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.
11
+ # isso a CLI recebe um token que atravessa repositórios também como
12
+ # GITHUB_TOKEN — o da GitHub App da organização (SPEC_WAVE_APP_ID +
13
+ # SPEC_WAVE_APP_PRIVATE_KEY), quando configurada, senão o GH_PROJECT_TOKEN
14
+ # (PAT com repo + project). Sem nenhum dos dois, cai no GITHUB_TOKEN, que
15
+ # ainda lê PR de repo público mas não comenta.
14
16
  on:
15
17
  repository_dispatch:
16
18
  types: [spec-wave-pr]
@@ -21,6 +23,10 @@ concurrency:
21
23
  group: spec-wave-pr-${{ github.event.client_payload.pr_repo }}-${{ github.event.client_payload.pr_number }}
22
24
  cancel-in-progress: false
23
25
 
26
+ # `secrets` não entra em `if`; a presença da GitHub App vira env.
27
+ env:
28
+ SPEC_WAVE_APP_PRESENT: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY != '' }}
29
+
24
30
  jobs:
25
31
  # Descobre a Feature-alvo ANTES de tocar no board, para dar a chave de
26
32
  # concurrency ao job seguinte — mesmo desenho do code-review.yml local.
@@ -44,6 +50,13 @@ jobs:
44
50
  - name: Instala a CLI
45
51
  run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
46
52
 
53
+ - id: app
54
+ if: env.SPEC_WAVE_APP_PRESENT == 'true'
55
+ uses: actions/create-github-app-token@v2
56
+ with:
57
+ app-id: ${{ secrets.SPEC_WAVE_APP_ID }}
58
+ private-key: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY }}
59
+
47
60
  - id: resolve
48
61
  run: >
49
62
  spec-wave code-review
@@ -51,7 +64,7 @@ jobs:
51
64
  --pr-repo ${{ github.event.client_payload.pr_repo }}
52
65
  --resolve-only
53
66
  env:
54
- GITHUB_TOKEN: ${{ secrets.GH_PROJECT_TOKEN || secrets.GITHUB_TOKEN }}
67
+ GITHUB_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN || secrets.GITHUB_TOKEN }}
55
68
  GITHUB_REPOSITORY: ${{ github.repository }}
56
69
 
57
70
  move:
@@ -79,14 +92,21 @@ jobs:
79
92
  - name: Instala a CLI
80
93
  run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
81
94
 
95
+ - id: app
96
+ if: env.SPEC_WAVE_APP_PRESENT == 'true'
97
+ uses: actions/create-github-app-token@v2
98
+ with:
99
+ app-id: ${{ secrets.SPEC_WAVE_APP_ID }}
100
+ private-key: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY }}
101
+
82
102
  - name: Move Feature to Code Review
83
103
  run: >
84
104
  spec-wave code-review
85
105
  --pr-number ${{ github.event.client_payload.pr_number }}
86
106
  --pr-repo ${{ github.event.client_payload.pr_repo }}
87
107
  env:
88
- GITHUB_TOKEN: ${{ secrets.GH_PROJECT_TOKEN || secrets.GITHUB_TOKEN }}
89
- PROJECT_TOKEN: ${{ secrets.GH_PROJECT_TOKEN }}
108
+ GITHUB_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN || secrets.GITHUB_TOKEN }}
109
+ PROJECT_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN }}
90
110
  GITHUB_REPOSITORY: ${{ github.repository }}
91
111
 
92
112
  qa:
@@ -105,12 +125,19 @@ jobs:
105
125
  - name: Instala a CLI
106
126
  run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
107
127
 
128
+ - id: app
129
+ if: env.SPEC_WAVE_APP_PRESENT == 'true'
130
+ uses: actions/create-github-app-token@v2
131
+ with:
132
+ app-id: ${{ secrets.SPEC_WAVE_APP_ID }}
133
+ private-key: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY }}
134
+
108
135
  - name: Move Feature to QA
109
136
  run: >
110
137
  spec-wave qa
111
138
  --pr-number ${{ github.event.client_payload.pr_number }}
112
139
  --pr-repo ${{ github.event.client_payload.pr_repo }}
113
140
  env:
114
- GITHUB_TOKEN: ${{ secrets.GH_PROJECT_TOKEN || secrets.GITHUB_TOKEN }}
115
- PROJECT_TOKEN: ${{ secrets.GH_PROJECT_TOKEN }}
141
+ GITHUB_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN || secrets.GITHUB_TOKEN }}
142
+ PROJECT_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN }}
116
143
  GITHUB_REPOSITORY: ${{ github.repository }}
@@ -42,6 +42,9 @@ jobs:
42
42
  issues: write
43
43
  pull-requests: write
44
44
  contents: read
45
+ # `secrets` não entra em `if`; a presença da GitHub App vira env do job.
46
+ env:
47
+ SPEC_WAVE_APP_PRESENT: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY != '' }}
45
48
 
46
49
  steps:
47
50
  - uses: actions/checkout@v5
@@ -53,10 +56,21 @@ jobs:
53
56
  - name: Instala a CLI
54
57
  run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
55
58
 
59
+ # Token de GitHub App da organização, quando configurada
60
+ # (SPEC_WAVE_APP_ID + SPEC_WAVE_APP_PRIVATE_KEY): substitui os PATs
61
+ # pessoais — quem sai da org não derruba o fluxo. Sem os secrets o step
62
+ # é pulado, `steps.app.outputs.token` fica vazio e os PATs continuam
63
+ # valendo pelo `||` abaixo.
64
+ - id: app
65
+ if: env.SPEC_WAVE_APP_PRESENT == 'true'
66
+ uses: actions/create-github-app-token@v2
67
+ with:
68
+ app-id: ${{ secrets.SPEC_WAVE_APP_ID }}
69
+ private-key: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY }}
56
70
 
57
71
  - name: Move Feature to QA
58
72
  run: spec-wave qa --pr-number ${{ github.event.pull_request.number }}
59
73
  env:
60
74
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
61
- PROJECT_TOKEN: ${{ secrets.GH_PROJECT_TOKEN }}
75
+ PROJECT_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN }}
62
76
  GITHUB_REPOSITORY: ${{ github.repository }}