@guilhermefsousa/open-spec-kit 0.1.0

package/templates/agents/agents/spec-hub.agent.md

@@ -0,0 +1,99 @@
+---
+name: spec-agent
+description: "Orquestra o ciclo de especificação: lê contexto do projeto, invoca as skills (/setup, /discovery, /spec, /dev) e coordena agents do Labs quando necessário."
+user-invocable: true
+disable-model-invocation: false
+---
+
+# Spec Agent
+
+O spec-agent é o orquestrador do ciclo de especificação. Ele NÃO gera artefatos diretamente — invoca as skills que fazem o trabalho.
+
+## Step 0 — Antes de qualquer trabalho
+
+Leia estes arquivos na ordem:
+
+1. `projects.yml` — repos, stack, dependências, Confluence space
+2. `docs/architecture.md` — estrutura do sistema
+3. TODOS os arquivos em `docs/lessons/` — aprender com erros passados
+4. TODOS os arquivos em `docs/decisions/` — decisões técnicas
+5. Specs recentes em `specs/` — o que já foi feito
+
+Nunca gere specs sem ter lido o acima.
+
+## Skills disponíveis
+
+| Skill | Comando | O que faz |
+|-------|---------|-----------|
+| Setup | `/setup @space_key` ou `/setup @page_id` | Bootstrap do projeto a partir do Confluence |
+| Discovery | `/discovery` | Análise de demanda, Q&A com PO, gera PRD |
+| Spec | `/spec` | Quebra PRD em specs técnicas (brief, cenários, contratos, tasks) |
+| Dev | `/dev NNN` | Orquestra implementação (TDD, MR, security, docs vivas) |
+
+As instruções completas de cada skill estão em `.agents/skills/*/SKILL.md`.
+
+## Responsabilidades do spec-agent vs Labs agents
+
+| Responsabilidade | Quem faz |
+|-----------------|----------|
+| Specs (brief, scenarios, contracts, tasks, links) | **spec-agent** via `/spec` |
+| ADRs (`docs/decisions/`) | **spec-agent** |
+| Design Document (DD) no Confluence | **`design-doc`** (Labs agent) — fallback: spec-agent via MCP direto |
+| Implementação de código | **`dotnet-engineer` / `nodejs-engineer` / `java-engineer`** (Labs) |
+| Security scan | **`labs-secops-agent`** (Labs) |
+| Code review automatizado | **`labs-code-reviewer`** (Labs) |
+| Trade-offs arquiteturais | **`principal-engineer`** (Labs) |
+
+## Rules
+
+1. Leia contexto existente antes de criar qualquer coisa
+2. Nunca invente contexto de negócio — pergunte ao dev
+3. Brief máx 1 página
+4. Cenários usam Given/When/Then
+5. Tasks agrupadas por repo (ver `projects.yml`)
+6. Cada task = 1 PR
+7. Todo conteúdo em Português (pt-BR) com acentuação correta, termos técnicos em inglês
+8. Aplique lições de `docs/lessons/`
+9. links.md deve linkar pra feature page no Confluence
+
+## Confluence (contexto)
+
+```
+Projeto (Space ou página raiz)
+├── 🎯 Visão do Produto        ← /setup gera
+├── 📖 Glossário                ← /setup gera | /discovery e /dev atualizam
+├── 📐 DD (Design Document)     ← design-doc agent gera | /dev atualiza
+├── Demandas/                   ← PO joga docs aqui
+├── 🚀 Features/                ← /setup cria | /discovery escreve dúvidas + PRD
+├── 🏛️ Domínio/                 ← /setup gera | /dev atualiza
+│   ├── 📏 Regras
+│   ├── 🔀 Fluxos
+│   ├── 📊 Tabelas de Referência
+│   └── 🔌 Integrações
+└── 📦 Arquivados/
+```
+
+## Spec repo (estrutura)
+
+```
+specs/NNN-nome/
+  brief.md                   ← problema + solução (1 página)
+  contracts.md               ← schemas, tipos, regras
+  scenarios.md               ← Given/When/Then (viram testes)
+  tasks.md                   ← tarefas por repo
+  links.md                   ← PRs + link da feature page
+  audit-report.md            ← resultado do self-review do /spec
+  conformance-report.json    ← validação pós-implementação do /dev
+```
+
+## Validation checklist
+
+- [ ] Brief máx 1 página
+- [ ] Todo cenário tem Given/When/Then
+- [ ] Cenários de falha cobertos
+- [ ] Tasks agrupadas por repo (per projects.yml)
+- [ ] Dependências explícitas
+- [ ] Cada task = 1 PR
+- [ ] contracts.md completo
+- [ ] Lições aplicadas
+- [ ] links.md tem link do Confluence

package/templates/agents/rules/hub_structure.instructions.md

@@ -0,0 +1,49 @@
+---
+name: project-structure
+description: Rules for maintaining the spec repo structure and conventions.
+applyTo: '**/*.md'
+---
+
+# Rule: Spec Repo Structure
+
+## Directory conventions
+
+- Specs live under `specs/NNN-short-name/` (sequential numbering)
+- Architecture docs live under `docs/architecture.md`
+- ADRs live under `docs/decisions/ADR-NNN-title.md`
+- Lessons live under `docs/lessons/NNN-short-title.md`
+- Project repo references live in `projects.yml`
+
+## Naming
+
+- Spec directories: `NNN-short-description` (`001-consumer-shipment`)
+- ADR files: `ADR-NNN-short-title.md` (`ADR-001-multi-repo.md`)
+- Lesson files: `NNN-short-title.md` (`001-pool-postgres.md`)
+
+## Spec lifecycle
+
+1. Created: spec directory with brief + scenarios + contracts + tasks
+2. In progress: tasks are checked off, links.md tracks PRs
+3. Done: all tasks checked, spec directory stays (it IS the history)
+
+Specs are NOT archived or moved. The spec directory with checked tasks IS the record.
+
+## What goes where
+
+| Content | Location |
+|---------|----------|
+| Feature specification | `specs/<spec>/brief.md` |
+| Behavioral scenarios | `specs/<spec>/scenarios.md` |
+| Contract definitions | `specs/<spec>/contracts.md` |
+| Implementation tasks | `specs/<spec>/tasks.md` |
+| PR tracking | `specs/<spec>/links.md` |
+| Spec quality audit | `specs/<spec>/audit-report.md` |
+| Implementation conformance | `specs/<spec>/conformance-report.json` |
+| Architecture overview | `docs/architecture.md` |
+| Architecture decisions | `docs/decisions/ADR-NNN.md` |
+| Lessons learned | `docs/lessons/NNN-title.md` |
+| Repo references | `projects.yml` |
+
+## How contracts work
+
+Contract schemas are DEFINED here in `contracts.md` within each spec directory (fields, types, rules, code examples for the project's stack). Code repos IMPLEMENT locally following contracts.md as source of truth.

package/templates/agents/rules/ownership.instructions.md

@@ -0,0 +1,138 @@
+---
+name: artifact-ownership
+description: RACI matrix defining who creates, reads, updates, and validates each artifact. Prevents duplicate responsibility.
+applyTo: '**/*.md'
+---
+
+# Rule: Artifact Ownership (RACI)
+
+Every artifact in this project has exactly **one Owner** (creates it) and at most **one Updater** (can modify it after creation). Other skills may **Read** or **Validate**, but never **Write**.
+
+This rule exists to prevent the "duplicate responsibility" anti-pattern where multiple skills update the same artifact with no clear authority, causing drift and conflicts.
+
+## Confluence Artifacts
+
+| Artifact | Owner (creates) | Updater | Readers | Validators |
+|----------|----------------|---------|---------|------------|
+| Demandas/ labels | /setup | — | /discovery | — |
+| Visão do Produto | /setup | — | all | — |
+| **Glossário** | /setup | **/discovery** (adds domain terms found in PRD analysis, exit gate), **/dev** (post-merge only — adds terms that emerged during implementation and weren't in the PRD) | /spec | /spec (read-only validate — if terms are missing, stop and ask dev to re-run /discovery) |
+| DD (Design Document) | /spec (via `design-doc` agent, fallback: MCP direct) | /dev (via `design-doc` agent, fallback: MCP direct) | — | — |
+| Domínio/Regras | /setup | /dev (post-merge only) | /discovery, /spec | — |
+| Domínio/Fluxos | /setup | /dev (post-merge only) | /discovery | — |
+| Domínio/Tabelas | /setup | — | /discovery | — |
+| Domínio/Integrações | /setup | /dev (post-merge only) | /discovery | — |
+| Features/ (parent) | /setup | — | all | — |
+| Feature pages (content) | /setup + /discovery | /discovery | /spec, /dev | — |
+| Feature labels | each skill at its transition | — | all | — |
+| Arquivados/ | /setup | — | — | — |
+
+## Local Artifacts
+
+| Artifact | Owner (creates) | Updater | Readers | Validators |
+|----------|----------------|---------|---------|------------|
+| `projects.yml` | /setup | /spec (adds planned repos), /dev (repo URLs + status) | all | — |
+| `docs/architecture.md` | /setup | /discovery (resolves decisions) | /spec, /dev | /spec (validates no blockers) |
+| `docs/lessons/` | /dev | /dev | all | — |
+| `docs/decisions/` | manual / spec-agent | — | all | — |
+| `specs/NNN/brief.md` | /spec | — | /dev | — |
+| `specs/NNN/scenarios.md` | /spec | — | /dev | — |
+| `specs/NNN/contracts.md` | /spec | — | /dev | — |
+| `specs/NNN/tasks.md` | /spec | — | /dev | — |
+| `specs/NNN/links.md` | /spec (template) | /dev (MR links) | — | — |
+| `specs/NNN/audit-report.md` | /spec (self-review) | — | /dev (reads before Phase B, blocks if ❌) | — |
+| `specs/NNN/conformance-report.json` | /dev (Phase C.3) | — | CI Guard | — |
+
+## Key Rules
+
+1. **One Writer per artifact** — if two skills both write to the same artifact, one of them is wrong. The matrix above is the source of truth.
+
+2. **Validate ≠ Update** — /spec validates the Glossário (checks all terms are present) but does NOT add terms. If terms are missing, it stops and asks the dev to re-run /discovery.
+
+3. **Post-merge = reality** — when /dev updates Confluence post-merge, it reflects what WAS IMPLEMENTED (merged code), not what was planned. If the implementation diverged from the spec, Confluence must match the code, not the spec.
+
+4. **DD ownership** — the Design Document is owned by the `design-doc` agent (Labs). Skills delegate to it. Only use direct MCP as a fallback when the agent is unavailable.
+
+5. **Labels accumulate** — MCP Confluence only adds labels (no remove). The "current" workflow state is always the most recently added label. Previous labels stay as history.
+
+   **Label state resolution algorithm:** to determine the current state when multiple labels exist, compare label creation timestamps (via metadata da página no Confluence). The label with the highest creation timestamp defines the current state. If timestamps are not available, use the following precedence order (highest wins): `done` > `em-dev` > `em-spec` > `prd-aprovado` > `prd-rejeitado` > `prd-review` > `aguardando-po` > `em-discovery`.
+
+6. **Dual-platform sync (Claude + Copilot)** — this project supports both Claude Code and GitHub Copilot. When modifying agent definitions, rules, or skills, you MUST update both platforms:
+
+   | Source of truth (`.agents/`) | Copilot mirror (`.github/`) |
+   |------------------------------|----------------------------|
+   | `.agents/agents/spec-hub.agent.md` | `.github/agents/spec-hub.agent.md` (update `tools`, `agents`, `mcp-servers` in frontmatter) |
+   | `.agents/rules/ownership.instructions.md` | `.github/instructions/ownership.instructions.md` (update summary tables) |
+   | `.agents/rules/hub_structure.instructions.md` | `.github/instructions/hub_structure.instructions.md` (update structure tables) |
+   | `.agents/skills/*/SKILL.md` | `.github/prompts/*.prompt.md` (update flow steps if changed) |
+   | `.mcp.json` | `.vscode/mcp.json` (update server config — different format: `servers` + `type` field) |
+
+   **`.agents/` is ALWAYS the source of truth.** The `.github/` files are Copilot-compatible mirrors. If in doubt, read `.agents/` first.
+
+   Changes that require sync:
+   - Adding/removing a sub-agent → update `.github/agents/spec-hub.agent.md` frontmatter `agents:` list + `.github/copilot-instructions.md` sub-agents table
+   - Adding/removing a skill → create/update `.github/prompts/` prompt file + `.github/copilot-instructions.md` skills table
+   - Changing RACI matrix → update `.github/instructions/ownership.instructions.md` summary
+   - Changing MCP servers → update `.vscode/mcp.json` (format: `servers` + `type: "stdio"`)
+
+## Label Transitions
+
+### Demandas/ labels (owned by /setup)
+```
+(none) → novo → processando → processado
+```
+
+### Feature labels (sequential flow)
+```
+em-discovery → aguardando-po → prd-review → prd-aprovado → em-spec → em-dev → done
+                     ↑                            |
+                     └──── prd-rejeitado ─────────┘
+```
+
+- `prd-aprovado` is added by the **PO manually** (human gate)
+- `prd-rejeitado` is added by the **PO manually** (triggers /discovery re-run)
+- All other labels are added by the respective skill automatically
+
+## MCP Failure Recovery
+
+All 4 skills must handle MCP failures:
+- /setup: re-execution checks existing pages, creates only missing ones
+- /discovery: saves pending operations to `docs/pending-confluence-updates.md`
+- /spec: saves pending operations to `docs/pending-confluence-updates.md`
+- /dev: saves pending updates to `docs/pending-confluence-updates.md`, retries on next execution
+
+## Architecture Decisions Format
+
+The `docs/architecture.md` "Decisões em Aberto" table uses this schema:
+
+```
+| # | Decisão | Impacto | Bloqueia | Status |
+```
+
+Status values: `aberta`, `resolvida — [decisão tomada]`
+
+Only /discovery updates this column (exit gate). /spec validates that no `aberta` decision blocks /dev.
+
+## links.md PR Table Format
+
+```markdown
+## PRs
+
+| Repo | Branch | MR/PR | Status |
+|------|--------|-------|--------|
+```
+
+Status values: `open`, `em-review`, `merged`, `closed`. Created empty by /spec, filled by /dev.
+
+## Shared Types Between Features
+
+When `contracts.md` defines types that other features will reuse (e.g., ErrorResponse, PaginatedResponse):
+- Mark them in a `## Tipos compartilhados` section
+- Features that USE types from another feature must REFERENCE them ("Ver contracts.md da feature NNN") — never redefine
+
+## Feature Scope Thresholds
+
+Both /discovery and /spec use the same criteria:
+- More than **15 behaviors/requirements** → flag as potentially large
+- Spans **4+ repos** → flag as potentially large
+- This is a suggestion, not a blocker. The PO/dev decides whether to break it up.

package/templates/agents/scripts/notify-gchat.ps1

@@ -0,0 +1,99 @@
+# notify-gchat.ps1 — Envia notificações ao Google Chat via webhook (Windows/PowerShell)
+#
+# Uso simples:
+#   .\scripts\notify-gchat.ps1 -Text "Mensagem simples"
+#
+# Uso com card:
+#   .\scripts\notify-gchat.ps1 -Card `
+#     -Title "✅ Título" `
+#     -Subtitle "Nome do Projeto" `
+#     -Body "Texto principal." `
+#     -Next "Próximo passo" `
+#     -ButtonText "Ver no Confluence" `
+#     -ButtonUrl "https://..."
+
+param(
+    [switch]$Card,
+    [string]$Title = "",
+    [string]$Subtitle = "",
+    [string]$Body = "",
+    [string]$Next = "",
+    [string]$ButtonText = "",
+    [string]$ButtonUrl = "",
+    [string]$Text = ""
+)
+
+# Auto-load .env from project root
+$envFile = Join-Path $PSScriptRoot ".." ".env"
+if (Test-Path $envFile) {
+    Get-Content $envFile | ForEach-Object {
+        if ($_ -match '^\s*([^#][^=]+)=(.*)$') {
+            $name = $Matches[1].Trim()
+            $value = $Matches[2].Trim()
+            if (-not [Environment]::GetEnvironmentVariable($name)) {
+                [Environment]::SetEnvironmentVariable($name, $value, "Process")
+            }
+        }
+    }
+}
+
+$webhookUrl = $env:GCHAT_WEBHOOK_URL
+if (-not $webhookUrl) {
+    Write-Host "[notify-gchat] GCHAT_WEBHOOK_URL nao configurada — notificacao ignorada" -ForegroundColor Yellow
+    exit 0
+}
+
+if ($Card) {
+    $header = @{ title = $Title }
+    if ($Subtitle) { $header.subtitle = $Subtitle }
+
+    $sections = @()
+
+    if ($Body) {
+        $sections += @{ widgets = @(@{ textParagraph = @{ text = $Body } }) }
+    }
+    if ($Next) {
+        $sections += @{
+            widgets = @(@{
+                decoratedText = @{
+                    startIcon = @{ knownIcon = "FLIGHT_ARRIVAL" }
+                    text = "<b>Próximo passo</b>: $Next"
+                }
+            })
+        }
+    }
+    if ($ButtonText -and $ButtonUrl) {
+        $sections += @{
+            widgets = @(@{
+                buttonList = @{
+                    buttons = @(@{
+                        text = $ButtonText
+                        onClick = @{ openLink = @{ url = $ButtonUrl } }
+                    })
+                }
+            })
+        }
+    }
+
+    $card = @{ header = $header }
+    if ($sections.Count -gt 0) { $card.sections = $sections }
+    $payload = @{ cardsV2 = @(@{ cardId = "open-spec-kit-notification"; card = $card }) }
+} else {
+    $payload = @{ text = $Text }
+}
+
+try {
+    $json = $payload | ConvertTo-Json -Depth 10 -Compress
+    $bytes = [System.Text.Encoding]::UTF8.GetBytes($json)
+    $response = Invoke-WebRequest -Uri $webhookUrl -Method POST `
+        -ContentType "application/json; charset=UTF-8" `
+        -Body $bytes -UseBasicParsing -SkipCertificateCheck -TimeoutSec 10
+
+    if ($response.StatusCode -ne 200) {
+        Write-Host "[notify-gchat] Resposta inesperada: $($response.StatusCode)" -ForegroundColor Yellow
+    }
+} catch {
+    Write-Host "[notify-gchat] Falha ao enviar notificacao — continuando normalmente" -ForegroundColor Yellow
+}
+
+exit 0

package/templates/agents/scripts/notify-gchat.sh

@@ -0,0 +1,131 @@
+#!/usr/bin/env bash
+
+# notify-gchat.sh — Send notifications to Google Chat via webhook
+#
+# Usage:
+#   ./scripts/notify-gchat.sh "Simple text message"
+#   ./scripts/notify-gchat.sh --card \
+#     --title "✅ Título" \
+#     --subtitle "Nome do Projeto" \
+#     --body "Texto principal.<br>Com quebras de linha." \
+#     --next "Próximo passo aqui" \
+#     --button-text "Ver no Confluence" \
+#     --button-url "https://..."
+
+# Auto-load .env from project root
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ENV_FILE="$SCRIPT_DIR/../.env"
+if [ -f "$ENV_FILE" ] && [ -z "$GCHAT_WEBHOOK_URL" ]; then
+  set -a
+  source "$ENV_FILE"
+  set +a
+fi
+
+if [ -z "$GCHAT_WEBHOOK_URL" ]; then
+  echo "[notify-gchat] GCHAT_WEBHOOK_URL não configurada — notificação ignorada" >&2
+  exit 0
+fi
+
+CARD_MODE=false
+TITLE=""
+SUBTITLE=""
+BODY=""
+NEXT=""
+BUTTON_TEXT=""
+BUTTON_URL=""
+TEXT_MESSAGE=""
+
+if [ "$1" = "--card" ]; then
+  CARD_MODE=true
+  shift
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --title)       TITLE="$2";       shift 2 ;;
+      --subtitle)    SUBTITLE="$2";    shift 2 ;;
+      --body)        BODY="$2";        shift 2 ;;
+      --next)        NEXT="$2";        shift 2 ;;
+      --button-text) BUTTON_TEXT="$2"; shift 2 ;;
+      --button-url)  BUTTON_URL="$2";  shift 2 ;;
+      *) shift ;;
+    esac
+  done
+else
+  TEXT_MESSAGE="$*"
+fi
+
+# Build and send via Python — avoids bash UTF-8 corruption
+PYTHONIOENCODING=utf-8 python -c "
+import json, sys, subprocess
+
+card_mode = sys.argv[1] == 'true'
+webhook_url = sys.argv[9]
+
+if card_mode:
+    title = sys.argv[2]
+    subtitle = sys.argv[3]
+    body = sys.argv[4]
+    next_step = sys.argv[5]
+    btn_text = sys.argv[6]
+    btn_url = sys.argv[7]
+
+    header = {'title': title}
+    if subtitle:
+        header['subtitle'] = subtitle
+
+    sections = []
+
+    # Section 1: body (main content)
+    if body:
+        sections.append({
+            'widgets': [{'textParagraph': {'text': body}}]
+        })
+
+    # Section 2: next step (highlighted)
+    if next_step:
+        sections.append({
+            'widgets': [{
+                'decoratedText': {
+                    'startIcon': {'knownIcon': 'FLIGHT_ARRIVAL'},
+                    'text': '<b>Próximo passo</b>: ' + next_step
+                }
+            }]
+        })
+
+    # Section 3: button
+    if btn_text and btn_url:
+        sections.append({
+            'widgets': [{
+                'buttonList': {
+                    'buttons': [{
+                        'text': btn_text,
+                        'onClick': {'openLink': {'url': btn_url}}
+                    }]
+                }
+            }]
+        })
+
+    card = {'header': header}
+    if sections:
+        card['sections'] = sections
+
+    payload = {'cardsV2': [{'cardId': 'open-spec-kit-notification', 'card': card}]}
+else:
+    text = sys.argv[8]
+    payload = {'text': text}
+
+data = json.dumps(payload, ensure_ascii=False).encode('utf-8')
+
+result = subprocess.run(
+    ['curl', '-s', '-o', '/dev/null', '--max-time', '10',
+     '-X', 'POST', webhook_url,
+     '-H', 'Content-Type: application/json; charset=UTF-8',
+     '-d', '@-'],
+    input=data,
+    capture_output=True
+)
+
+if result.returncode != 0:
+    print('[notify-gchat] Falha ao enviar notificação — continuando normalmente', file=sys.stderr)
+" "$CARD_MODE" "$TITLE" "$SUBTITLE" "$BODY" "$NEXT" "$BUTTON_TEXT" "$BUTTON_URL" "$TEXT_MESSAGE" "$GCHAT_WEBHOOK_URL" 2>/dev/null
+
+exit 0