@guilhermefsousa/open-spec-kit 0.1.0

package/templates/agents/skills/specifying-features/SKILL.md

@@ -0,0 +1,378 @@
+---
+name: specifying-features
+description: "Breaks an approved PRD into N feature specifications with brief, scenarios (Given/When/Then), contracts, and repo-partitioned tasks. Generates/updates Design Document on Confluence."
+metadata:
+  works_on: [copilot, antigravity, claude]
+argument-hint: "[feature description or Confluence PRD link]"
+---
+
+# Specifying Features
+
+## Objective
+
+Take an approved PRD and produce minimal, unambiguous feature specifications that enable parallel implementation across multiple repos. Also generate or update the Design Document on Confluence.
+
+## Before you start
+
+### Validate prerequisites
+
+1. Read `projects.yml` — if empty, **stop** with message: "/setup não foi executado."
+2. Read `docs/architecture.md` — if file does not exist: **stop** — "/setup não gerou architecture.md. Execute /setup primeiro."
+3. No Confluence (via MCP ou API REST — mesma lógica de fallback do /setup), find the feature page and check its labels:
+   - If label `prd-aprovado` is NOT present: **stop** — "PRD não aprovado. A feature precisa ter label 'prd-aprovado' antes de rodar /spec. Execute /discovery primeiro."
+   - If label `prd-rejeitado` is present AND its addition date is MORE RECENT than `prd-aprovado` (check via MCP ou API REST — metadata da página ou timestamps dos labels): **stop** — "PRD foi rejeitado após aprovação. Execute /discovery para resolver antes de prosseguir."
+   - If `prd-aprovado` IS present and no subsequent `prd-rejeitado`: proceed
+4. Read the feature page content — verify it has a "## PRD" section with "### Requisitos aceitos". If not: **stop** — "PRD não encontrado na página da feature."
+5. **Idempotency check**: if `specs/` already contains a directory for this feature (matching name or Confluence page ID in links.md):
+   - If all 5 files exist and are complete: **stop** — "Spec já existe em specs/NNN-name/. Para re-gerar, delete o diretório primeiro ou passe --force."
+   - If some files are missing or incomplete: **warn** and continue — will overwrite/complete the existing spec.
+
+### Read context
+
+Read these files FIRST:
+
+1. `projects.yml` — repos, stack, dependencies
+2. `docs/architecture.md` — system structure
+3. ALL files in `docs/lessons/` — past mistakes to avoid
+4. ALL files in `docs/decisions/` — technical choices
+5. ALL existing `specs/` — read `contracts.md` of every previous spec to know which entities, endpoints, types, and error formats already exist. This is the **baseline** for the new spec.
+
+**Evolution rule**: when the project already has specs, the new spec MUST:
+- **Reference** existing types with "Ver contracts.md da feature NNN" — never redefine
+- **Extend** existing entities by documenting only the NEW fields (e.g., "Adiciona campo `saldo` à entidade `Conta` definida em 002")
+- **Reuse** shared types (ErrorResponse, PaginatedResponse) by reference
+- If the new feature MODIFIES behavior of an existing endpoint, document the change explicitly in brief.md: "Modifica GET /api/contas para incluir campo `saldoAtual` no response"
+
+## Inputs
+
+- Approved PRD on Confluence (label `prd-aprovado`) — read via MCP ou API REST
+- Feature context from Discovery phase (questions answered, decisions taken)
+
+## Artifacts produced
+
+| File | Purpose | Max size |
+|------|---------|----------|
+| `brief.md` | Problem, solution, out of scope | 1 page |
+| `scenarios.md` | Given/When/Then for every behavior | As many as needed |
+| `contracts.md` | Event schemas, entities, enums, business rules | As many as needed |
+| `tasks.md` | Checklist grouped by repo | As many as needed |
+| `links.md` | PRs, boards, Confluence feature page link | Updated during implementation |
+
+## Flow
+
+### 1. Read PRD from Confluence
+
+No Confluence, leia o PRD aprovado na feature page.
+Extract: requirements, decisions, scope, out of scope, assumptions.
+
+### 2. Identify features in the PRD
+
+A single PRD may contain N features. Each feature becomes a spec directory.
+Numbering is sequential: find the highest existing number in `specs/` and increment.
+
+### 3. Write specs (per feature)
+
+> **⚠️ OBRIGATÓRIO: gerar TODOS os 5 arquivos por feature — `brief.md`, `scenarios.md`, `contracts.md`, `tasks.md`, `links.md`.**
+> O `/dev` rejeita specs com arquivos faltando (verifica na Phase A). O `open-spec-kit validate` falha em Rule-01 se qualquer um dos 5 estiver ausente.
+> O `links.md` é frequentemente esquecido por ser o menor — ele é **obrigatório** e o `/dev` depende dele para rastrear PRs pós-merge.
+
+**MANDATORY LANGUAGE for ALL generated files**: Brazilian Portuguese (pt-BR) with correct accents. This includes code comments, Gherkin descriptions, and free text. Examples: "não" NOT "nao", "autenticação" NOT "autenticacao", "código" NOT "codigo", "é" NOT "e", "já" NOT "ja", "número" NOT "numero", "válido" NOT "valido", "obrigatório" NOT "obrigatorio", "mínimo" NOT "minimo". Technical terms stay in English (endpoint, token, hash, bcrypt, JWT).
+
+#### brief.md
+- Start with the PROBLEM, not the solution
+- One page maximum
+- Include "Out of Scope" section
+- Reference contracts.md for event/API details
+
+#### scenarios.md
+- Every behavior gets a Given/When/Then scenario
+- Include happy path AND failure paths
+- Include edge cases (duplicates, missing fields, timeouts, boundary values)
+- Each scenario maps to at least one test
+- Use REQ-NNN identifiers (from PRD requirements). **Format: 3-digit zero-padded** — REQ-001, REQ-011, NOT REQ-1 or REQ-11. The `open-spec-kit validate` command enforces this format.
+- **CT ID format (MANDATORY)**: every scenario heading MUST use the format:
+  `### CT-NNN-XX: description (REQ-NNN)`
+  Where NNN = feature spec number, XX = sequential within that REQ.
+
+  Example for spec 001:
+  ```
+  ## REQ-001: Idempotent shipment ingestion
+
+  ### CT-001-01: New shipment arrives (REQ-001)
+  - **Given:** no record exists with sourceId="SHP-001"
+  - **When:** ShipmentPaymentCalculated event arrives
+  - **Then:** a new record is created with status=Pending
+
+  ### CT-001-02: Duplicate of unbilled shipment (REQ-001)
+  - **Given:** record exists with sourceId="SHP-001" and status=Pending
+  - **When:** event arrives with different totalAmount
+  - **Then:** record is updated with new totalAmount
+
+  ## REQ-002: Payload validation
+
+  ### CT-002-01: Required field missing (REQ-002)
+  - **Given:** event arrives without tripId
+  - **When:** consumer processes
+  - **Then:** event sent to dead-letter queue
+  ```
+
+  The `open-spec-kit validate` command enforces this format. Specs without CT IDs will fail validation.
+- **Bidirectional traceability (MANDATORY)**:
+  - Every scenario MUST reference at least one REQ-NNN
+  - Every REQ-NNN from the PRD MUST have at least one scenario covering it
+  - If a REQ has no scenario, either the REQ is unverifiable (fix the PRD) or a scenario is missing (add it)
+- **Cross-check with Regras de Negócio**: read `Domínio/Regras` on Confluence and verify that every RN referenced in the scenarios exists. If a scenario contradicts an RN, flag it as error.
+- **Mandatory auth scenario**: if the feature has ANY authenticated endpoint, include a scenario testing access WITHOUT a token (expected: 401 NAO_AUTORIZADO). One per feature is sufficient — it validates the auth middleware applies.
+- **Mandatory pagination scenarios**: if ANY endpoint uses explicit pagination (PaginatedResponse, page/pageSize params, or similar envelope), include scenarios for:
+  - Default pagination (no params → uses defaults)
+  - Last page (partial results)
+  - Invalid page values (page ≤ 0, pageSize > max) — expected: 400 or clamped to defaults
+- **No unresolved markers (MANDATORY)**: specs MUST NOT contain any of these markers anywhere — including inside code blocks and code examples:
+  `MOCKADO`, `TODO`, `A CONFIRMAR`, `TBD`, `FIXME`, `PLACEHOLDER`, `TKTK`
+  If any assumption is not validated, go back to /discovery to resolve it.
+  The `open-spec-kit validate` command will ERROR on any unresolved marker.
+- **Cross-spec dependencies are NOT REQs**: if a feature uses an entity or type defined in another spec, do NOT create a REQ for it. Instead, use a `> Dependency:` block in the brief:
+  `> Dependency: Uses entity Tutor defined in specs/002 (see contracts.md of feature 002)`
+  REQs are testable requirements — a reference to another spec is not testable.
+- Descriptions in Gherkin MUST have accents (ex: "não revela", "usuário autenticado", "credenciais inválidas")
+
+#### contracts.md
+
+**Mandatory sections** (every contracts.md MUST have ALL of these):
+
+1. **Endpoint table**: Método | Rota | Descrição | Autenticado
+2. **Contracts per stack**: if `projects.yml` lists repos with different stacks (ex: dotnet + nodejs), contracts MUST include BOTH. Typically: C# (backend) AND TypeScript (frontend). One language is NOT sufficient. Use separate sections with headings: `## Contratos C# (.NET API)` and `## Contratos TypeScript (React Frontend)` (or equivalent for the project's stack).
+3. **Full endpoint paths in ALL contract examples**: every code example (backend AND frontend, any stack) MUST use the COMPLETE route path exactly as defined in the endpoint table (e.g., `/api/auth/login`, NOT `/auth/login`). This eliminates ambiguity about path prefixes and ensures consistency between backend route definitions and frontend API calls. The endpoint table is the single source of truth for paths — every code example must match it literally.
+4. **Entities/models**: every new entity introduced by this feature MUST have its own heading in the format `## Entidade: EntityName` followed by a table with columns `Campo | Tipo | Obrigatório | Descrição` (or English equivalents `Field | Type | Required | Description`). This heading format is required by the validator. Example:
+   ```
+   ## Entidade: User
+   | Campo | Tipo | Obrigatório | Descrição |
+   |-------|------|-------------|-----------|
+   | Id | Guid | Sim | Identificador único |
+   | CreatedAt | DateTime | Sim | Data de criação |
+   | UpdatedAt | DateTime | Sim | Data de última atualização |
+   ```
+5. **Error codes**: every error code specific to this feature, as constants/enum
+5. **Validation rules** (as a top-level `##` section, NOT nested inside a per-stack section): every field validation (required, format, max length, valid values)
+6. **Response examples**: at least one success example and one error example per endpoint, with HTTP status code
+7. **Shared types**: if this feature DEFINES types that other features will reuse (ex: ErrorResponse, PaginatedResponse), mark them in a `## Tipos compartilhados` section. If this feature USES types from another feature, REFERENCE them ("Ver contracts.md da feature NNN") — do NOT copy the full definition. If extending a type, define only the extension.
+
+Additional structural rule: **editável entities MUST have both `CriadoEm` and `AtualizadoEm` fields**. If an entity can be modified via PUT/PATCH, it needs `AtualizadoEm` for auditability.
+
+Additional rules:
+- Define event schemas, entities, enums
+- Include field types and required/optional
+- Include business rules (idempotency, validation)
+- Code comments MUST have accents (ex: `// Validação padrão`, NOT `// Validacao padrao`)
+
+#### tasks.md
+- **IMPORTANTE**: use o nome EXATO do repo conforme declarado em `projects.yml` como heading `## nome-do-repo`. Ex: `## todo-app-api`, NÃO `## Backend`. O `open-spec-kit validate` verifica que os headings batem com repos do projects.yml (Rule 21).
+- Group tasks by repo (from `projects.yml`) — each `## repo` heading is one **execution unit** (1 agent or 1 dev)
+- **Validate repos**: every repo referenced in tasks.md MUST exist in `projects.yml`. If a task references a repo not in projects.yml, **add it** with `status: planned` and `url: null`. The /dev will auto-create it in Phase A.1. Log: "Repo '{name}' adicionado ao projects.yml com status: planned."
+- Within each `## repo` block, list tasks in execution order — the list order IS the dependency order (no need to annotate dependencies between tasks of the same block)
+- **Paralelismo entre blocos**: if a repo block depends ONLY on contracts (already defined in contracts.md) and NOT on the implementation of another block, mark with `[P]` — it can start in parallel. Example: `### todo-front [P] — pode iniciar após contratos definidos`
+- **Dependência entre blocos**: if a repo block REQUIRES another block to be COMPLETED first, declare explicitly with `> Dependência: bloco todo-api deve estar concluído antes de iniciar`
+- Each task = 1 PR
+- Reference REQ-NNN from scenarios
+- **Feature grande**: if the PRD has more than 15 behaviors/requirements or spans 4+ repos, /discovery should have flagged it already. If it arrived here approved, proceed without questioning. Just note in brief.md: "Feature com {N} requisitos — escopo aprovado pelo PO."
+
+#### links.md
+- Link to Confluence feature page
+- Empty PR table with this schema (filled by /dev during implementation):
+
+```markdown
+## PRs
+
+| Repo | Branch | MR/PR | Status |
+|------|--------|-------|--------|
+```
+
+Status values: `open`, `em-review`, `merged`, `closed`. The /dev uses the Status column to detect merged MRs for post-merge Phase D.
+
+#### ✅ Checklist de artefatos (OBRIGATÓRIO — conferir antes de prosseguir para o self-review)
+
+Confirme que gerou os **5 arquivos** para esta feature:
+
+- [ ] `brief.md` — problema, solução, fora de escopo
+- [ ] `scenarios.md` — Given/When/Then por comportamento
+- [ ] `contracts.md` — endpoints, entidades, enums, regras
+- [ ] `tasks.md` — checklist por repo (use nome EXATO do repo do projects.yml como heading `##`)
+- [ ] `links.md` — URL do Confluence + tabela de PRs ← **frequentemente esquecido; o /dev depende deste arquivo**
+
+Se qualquer arquivo estiver ausente, **crie-o agora** antes de continuar.
+
+
+
+Before generating the DD or closing the loop, run ALL checks below. Fix any failures, then generate the audit report.
+
+**Checks:**
+
+1. **Traceability matrix**: for each REQ-NNN in the PRD, confirm at least one CT-XX exists in scenarios.md. For each CT-XX, confirm it references a valid REQ-NNN. List any orphans and fix them.
+2. **RN coverage**: for each RN listed as relevant in brief.md, confirm at least one CT-XX references it. If a relevant RN has no scenario, add one.
+3. **Contracts completeness**: for each endpoint in the endpoint table, confirm:
+   - Request type defined (or N/A for GET/DELETE without body)
+   - Response type defined
+   - At least one success example and one error example
+   - Error codes cover all failure scenarios
+4. **Auth consistency**: if feature has authenticated endpoints, confirm a CT for "sem token → 401" exists
+5. **Pagination consistency**: if any endpoint returns lists, confirm pagination scenarios exist
+6. **Cross-feature types**: if contracts.md defines a type that already exists in another feature's contracts.md, replace with a reference
+
+If ANY check fails, fix the spec files BEFORE proceeding. Report what was fixed.
+
+**Generate audit report**: after completing all checks (and fixing any issues), save the results to `specs/NNN-name/audit-report.md`:
+
+```markdown
+# Audit Report — NNN: Feature Name
+
+| # | Check | Result | Details |
+|---|-------|--------|---------|
+| 1 | REQ → Scenarios | ✅ 12/12 | All REQs have ≥1 scenario |
+| 2 | RN → Scenarios | ✅ 8/8 | All RNs have ≥1 scenario |
+| 3 | Endpoints → Contracts | ✅ 6/6 | All endpoints have request/response/errors |
+| 4 | Auth (401 scenario) | ✅ 1/1 | CT-NNN-XX covers |
+| 5 | Pagination scenarios | ✅ 2/2 | CT-NNN-XX, CT-NNN-YY |
+| 6 | Cross-feature types | ✅ OK | References only, no redefinitions |
+
+**Generated**: YYYY-MM-DD
+**Fixed during review**: (list what was added/corrected, or "none")
+```
+
+Result values:
+- ✅ = all items pass
+- ⚠️ = partially passing, documented exceptions (include reason)
+- ❌ = failing — MUST be fixed before proceeding (this state should not appear in the final report since all failures are fixed first)
+
+The /dev reads this report in Phase A before starting implementation. If it contains ⚠️ items, the dev evaluates whether to proceed or request spec changes.
+
+### 5. Validate Glossary on Confluence (read-only)
+
+> **Ownership rule**: the Glossário is updated ONLY by /discovery (exit gate). The /spec only VALIDATES.
+
+Check if the /discovery phase identified new terms (see "GLOSSÁRIO" notes on the feature page or in the PRD). If yes:
+1. Read the current Glossário no Confluence (in storage format)
+2. Verify that ALL new terms listed in the PRD section "GLOSSÁRIO: termos novos" are present in the Glossário page
+3. **If any term is MISSING**: **stop** — "Glossário incompleto. O /discovery deveria ter adicionado os termos '{missing}' no exit gate. Re-execute /discovery para corrigir."
+4. **If all terms are present**: proceed (no update needed)
+
+Do NOT add terms directly — this is /discovery's responsibility.
+
+### 6. Generate/update Design Document on Confluence
+
+> **Ownership rule**: the DD is owned by the `design-doc` agent (Labs). The /spec delegates creation/update to it. Only uses MCP directly as a fallback.
+
+Read `projects.yml` → `agents.design_doc`. If configured (not null), use that agent to generate or update the DD on Confluence with:
+- Updated architecture (if feature adds components)
+- New data flows
+- Security considerations
+- Contract definitions
+- Rollout strategy
+
+**Diagram format**: all architecture and data flow diagrams MUST use **Mermaid** blocks. Use `flowchart` for data flows, `sequenceDiagram` for API interactions, `C4Context` for high-level architecture. Never use ASCII art. Example C4:
+  ```mermaid
+  C4Context
+      Person(user, "Usuário")
+      System(api, "API Gateway")
+      System_Ext(ext, "Serviço Externo")
+      Rel(user, api, "Usa")
+      Rel(api, ext, "Consulta")
+  ```
+
+**Fallback**: if `design-doc` agent is not available, update the DD directly no Confluence:
+1. Read the DD page in storage format
+2. Add a new section for this feature with: components, endpoints, data model changes. MUST include Mermaid diagrams for any new data flows or architecture changes.
+3. Update the page (preserving ALL existing content — NEVER use placeholders)
+
+### 7. Close the loop
+
+- Change feature label on Confluence → `em-spec`
+- Notify Google Chat (se `GCHAT_WEBHOOK_URL` não estiver definida, o script pula silenciosamente):
+
+      ./scripts/notify-gchat.sh --card \
+        --title "📐 Specs prontas pra review" \
+        --subtitle "{project_name}" \
+        --body "<b>Feature:</b> {feature_name}
+
+      📄 <b>Artefatos gerados:</b>
+      • brief.md — problema e solução
+      • scenarios.md — {scenario_count} cenários BDD
+      • contracts.md — contratos por stack (conforme projects.yml)
+      • tasks.md — {task_count} tasks por repo
+
+      📊 <b>Cobertura:</b> {req_count} REQs → {scenario_count} cenários" \
+        --next "Review técnico antes de iniciar /dev" \
+        --button-text "Ver spec no Confluence" \
+        --button-url "{feature_page_url}"
+
+  Substitua os valores entre `{}` pelos dados reais. Notificações sempre em pt-BR.
+
+## MCP failure recovery
+
+If a Confluence operation fails mid-flow (updating DD, changing labels, reading Glossário):
+1. Log which operations succeeded and which failed
+2. Save pending operations to `docs/pending-confluence-updates.md` with: target page, content to add/update, operation type, date
+3. Report to dev: "Confluence indisponível — {N} operações pendentes salvas em docs/pending-confluence-updates.md."
+4. On re-execution, check if `docs/pending-confluence-updates.md` exists and attempt to apply pending operations FIRST before proceeding with new work. Remove applied entries from the file.
+
+## Agents used
+
+- Agent configured in `projects.yml` → `agents.design_doc` — to generate/update Design Document on Confluence
+
+## Rules
+
+1. Read existing context before creating anything
+2. Never invent business context — ask the developer
+3. Brief max 1 page
+4. Scenarios use Given/When/Then
+5. Tasks grouped by repo (see `projects.yml`)
+6. Each task = 1 PR
+7. **Language**: ALL generated content — Confluence pages AND local files — MUST be in **Brazilian Portuguese (pt-BR) with correct accents** (e.g., "não" NOT "nao", "autenticação" NOT "autenticacao", "código" NOT "codigo"). Technical terms stay in English. Code comments MUST also have accents (e.g., `// Validação padrão` NOT `// Validacao padrao`).
+8. Apply lessons from `docs/lessons/`
+9. Design Document (DD) is ONE document per project, updated per feature
+10. links.md must link to the Confluence feature page
+11. **Scripts cross-platform**: ao executar `./scripts/notify-gchat.*`, detectar o OS. Em Windows usar `powershell -ExecutionPolicy Bypass -File ./scripts/notify-gchat.ps1`, em Linux/macOS usar `bash ./scripts/notify-gchat.sh`. Os parâmetros são os mesmos em ambos.
+
+## Validation checklist
+
+### Traceability (MUST pass — do not ship without these)
+- [ ] Every scenario references at least one REQ-NNN
+- [ ] Every REQ-NNN from the PRD has at least one scenario
+- [ ] Every RN referenced in scenarios exists in Domínio/Regras on Confluence
+- [ ] No RN relevant to this feature was left unreferenced
+
+### Scenarios quality
+- [ ] Every scenario has Given/When/Then
+- [ ] Happy path covered for every endpoint/behavior
+- [ ] Failure scenarios covered (validation errors, not found, ownership)
+- [ ] Auth scenario (401 without token) present if feature has authenticated endpoints
+- [ ] Pagination scenarios present if any endpoint returns paginated lists
+- [ ] Edge cases covered (boundary values, empty results, duplicates)
+
+### Contracts quality
+- [ ] contracts.md has ALL mandatory sections (endpoint table, per-stack contracts, entities, error codes, validation rules, examples, shared types)
+- [ ] Contracts defined for EVERY stack in projects.yml (ex: C# AND TypeScript)
+- [ ] Shared types referenced, not redefined
+
+### Structure
+- [ ] PRD was read from Confluence
+- [ ] Brief is 1 page or less, starts with the problem
+- [ ] Tasks grouped by repo (per projects.yml)
+- [ ] Dependencies between tasks explicit
+- [ ] Each task = 1 PR
+- [ ] links.md has correct Confluence page link
+
+### Integration
+- [ ] DD updated on Confluence
+- [ ] Feature label updated on Confluence → `em-spec`
+- [ ] GChat notification sent
+- [ ] Lessons from docs/lessons/ applied
+
+## Exit gate (BLOCKING — cannot close the loop without these)
+
+The /spec CANNOT be considered done until ALL of the following are true. If any item fails, fix it before moving to /dev.
+
+1. **Design Document exists and is updated on Confluence** — the DD page MUST exist under the project root. If it doesn't exist, create it. If it exists, add/update the section for this feature. NEVER skip this step. Verify by reading the DD page after updating.
+2. **Glossary validated** — if any feature PRD has a "GLOSSÁRIO: termos novos" section, ALL listed terms MUST be present in the Glossário page. Read the Glossário page and verify. If any term is MISSING: **stop** — "Glossário incompleto. Re-execute /discovery para adicionar os termos faltantes." The /spec does NOT add terms — it only validates that /discovery did its job.
+3. **All decisions resolved** — read `docs/architecture.md` "Decisões em Aberto" section. If ANY decision is still open that blocks /dev, the /spec CANNOT close. Technical decisions can be resolved by the dev team. Business decisions must go back to the PO. If an open decision needs resolution, go back to /discovery — the /spec does not resolve decisions, only validates.
+4. **Self-review completed** — the traceability matrix (REQ → CT, CT → REQ) MUST be verified. Report what was checked and any fixes applied. Do NOT skip silently.
+5. **Commit and push** — all spec files MUST be committed and pushed to the spec repo before closing. Verify with `git status` that working directory is clean.

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

@@ -0,0 +1,75 @@
+---
+name: spec-agent
+description: "Orquestra o ciclo de especificação: invoca skills (/setup, /discovery, /spec, /dev) e coordena agents do Labs."
+user-invocable: true
+disable-model-invocation: false
+tools:
+  - agent
+  - read
+  - edit
+  - search
+  - execute
+  - web
+agents:
+  - design-doc
+  - dotnet-engineer
+  - nodejs-engineer
+  - java-engineer
+  - frontend-expert
+  - labs-secops-agent
+  - labs-code-reviewer
+  - principal-engineer
+mcp-servers:
+  - confluence
+---
+
+# Spec Agent
+
+> Source of truth: `.agents/agents/spec-hub.agent.md`
+> Este arquivo registra o agent no Copilot com ferramentas e sub-agents declarados.
+> As instruções completas estão em `.agents/`.
+
+## Antes de qualquer trabalho
+
+Leia `.agents/agents/spec-hub.agent.md` e siga TODAS as instruções de lá.
+
+Em resumo:
+
+1. Leia `projects.yml`, `docs/architecture.md`, `docs/lessons/`, `docs/decisions/`, specs recentes
+2. Leia `.agents/rules/ownership.instructions.md` — matriz RACI obrigatória
+3. Leia `.agents/rules/hub_structure.instructions.md` — convenções de estrutura
+4. Nunca invente contexto de negócio — pergunte ao dev
+5. Todo conteúdo em Português (pt-BR) com acentuação correta, termos técnicos em inglês
+
+## Skills disponíveis
+
+Cada skill tem instruções completas em `.agents/skills/*/SKILL.md`:
+
+| Skill | Prompt file | O que faz |
+|-------|-------------|-----------|
+| Setup | `/setup` | Bootstrap do projeto a partir do Confluence |
+| Discovery | `/discovery` | Análise de demanda, Q&A com PO, gera PRD |
+| Spec | `/nova-feature` | Quebra PRD em specs técnicas (brief, cenários, contratos, tasks) |
+| Dev | `/dev` | Orquestra implementação (TDD, MR, security, docs vivas) |
+
+## Sub-agents
+
+Este agent pode delegar para os seguintes agents do Labs:
+
+| Agent | Quando usar |
+|-------|------------|
+| `design-doc` | Gerar/atualizar Design Document no Confluence |
+| `dotnet-engineer` | Implementar código .NET/C# |
+| `nodejs-engineer` | Implementar código Node.js/TypeScript |
+| `java-engineer` | Implementar código Java/Spring |
+| `frontend-expert` | Implementar frontend React |
+| `labs-secops-agent` | Security scan pré-merge |
+| `labs-code-reviewer` | Code review automatizado |
+| `principal-engineer` | Trade-offs arquiteturais |
+
+**Nota:** Estes agents vivem no repositório `padrao-labs-agents`. Para que a delegação funcione no Copilot, os arquivos `.agent.md` correspondentes devem estar disponíveis em `.github/agents/` deste repo ou no repo `.github-private` da organização. Se um sub-agent não estiver disponível, siga as instruções de fallback no SKILL.md correspondente.
+
+## MCP Confluence
+
+Operações Confluence são feitas via MCP server `confluence` configurado em `.vscode/mcp.json`.
+Se MCP falhar, salve operações pendentes em `docs/pending-confluence-updates.md`.

package/templates/github/copilot-instructions.md

@@ -0,0 +1,102 @@
+# Spec Repo — Copilot Instructions
+
+> Source of truth: `.agents/` directory
+> Regras detalhadas em `.agents/rules/`. Skills completos em `.agents/skills/*/SKILL.md`.
+
+## Contexto
+
+Repositório de especificações de projeto (ver `projects.yml`).
+Os repos de código são separados — este repo contém specs, contratos e tasks.
+O Confluence é o mundo do PO. Este repo é o mundo do DEV.
+
+## Antes de qualquer trabalho
+
+1. Leia `.agents/rules/ownership.instructions.md` — matriz RACI (quem cria, lê, atualiza cada artefato). **Obrigatório antes de alterar qualquer skill ou spec.**
+2. Leia `.agents/rules/hub_structure.instructions.md` — convenções de estrutura
+3. Leia `projects.yml` — repos, stack, dependências, Confluence space
+4. Leia `docs/architecture.md` — estrutura do sistema
+5. Leia TODOS os arquivos em `docs/lessons/` — aprendizados do time
+6. Leia `docs/decisions/` — decisões técnicas
+7. Leia specs recentes em `specs/` — o que já foi feito
+
+## Skills disponíveis
+
+Invoke via prompt files (digite `/` no chat):
+
+| Comando | Skill | O que faz |
+|---------|-------|-----------|
+| `/setup` | setup-project | Bootstrap do projeto a partir do Confluence |
+| `/discovery` | discovery | Análise de demanda, Q&A com PO, gera PRD |
+| `/nova-feature` | specifying-features | Quebra PRD em specs técnicas |
+| `/dev` | dev-orchestrator | Orquestra implementação TDD |
+
+Cada prompt file aponta para o SKILL.md completo em `.agents/skills/*/SKILL.md`.
+
+## Sub-agents disponíveis
+
+O spec-agent pode delegar para agents do Labs quando disponíveis:
+
+| Agent | Stack/função |
+|-------|-------------|
+| `design-doc` | Gerar Design Document no Confluence |
+| `dotnet-engineer` | Implementar .NET/C# |
+| `nodejs-engineer` | Implementar Node.js/TypeScript |
+| `java-engineer` | Implementar Java/Spring |
+| `frontend-expert` | Implementar frontend React |
+| `labs-secops-agent` | Security scan |
+| `labs-code-reviewer` | Code review automatizado |
+| `principal-engineer` | Trade-offs arquiteturais |
+
+**Nota:** Estes agents vivem no repositório `padrao-labs-agents`. Para delegação funcionar, os `.agent.md` devem estar em `.github/agents/` deste repo ou no `.github-private` da org. Se não disponível, siga os fallbacks no SKILL.md.
+
+## MCP Confluence
+
+Configurado em `.vscode/mcp.json`. Operações Confluence (ler páginas, criar páginas, gerenciar labels) são feitas via MCP.
+
+Se MCP falhar: salve operações pendentes em `docs/pending-confluence-updates.md`.
+
+## Regras obrigatórias
+
+- Todo conteúdo em Português (pt-BR) com acentuação correta
+- Termos técnicos em inglês (endpoint, JWT, token, hash)
+- Brief máx 1 página
+- Cenários usam Given/When/Then
+- Tasks agrupadas por repo (ver `projects.yml`)
+- Cada task = 1 PR
+- Nunca invente contexto de negócio — pergunte ao dev
+- Aplique lições de `docs/lessons/`
+- links.md deve linkar pra feature page no Confluence
+
+## Dual-platform sync
+
+Este projeto suporta Claude Code e Copilot. Ao modificar agents, rules ou skills, atualize ambas as plataformas. Consulte a regra 6 em `.agents/rules/ownership.instructions.md` para a tabela de mapeamento.
+
+## Estrutura do Confluence
+
+```
+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/
+```
+
+## Estrutura do spec repo
+
+```
+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
+  conformance-report.json    <- validação pós-implementação
+```

package/templates/github/instructions/hub_structure.instructions.md

@@ -0,0 +1,33 @@
+---
+applyTo: "specs/**,docs/**,projects.yml"
+---
+
+# Rule: Spec Repo Structure
+
+> Source of truth: `.agents/rules/hub_structure.instructions.md`
+
+## Convenções de diretório
+
+- Specs vivem em `specs/NNN-short-name/` (numeração sequencial)
+- Docs de arquitetura em `docs/architecture.md`
+- ADRs em `docs/decisions/ADR-NNN-title.md`
+- Lições em `docs/lessons/NNN-short-title.md`
+- Repos do projeto em `projects.yml`
+
+## Cada spec contém
+
+| Arquivo | Propósito |
+|---------|-----------|
+| `brief.md` | Problema + solução (máx 1 página) |
+| `scenarios.md` | Given/When/Then (viram testes) |
+| `contracts.md` | Schemas, tipos, regras de negócio |
+| `tasks.md` | Tarefas por repo (1 task = 1 PR) |
+| `links.md` | Tracking de PRs + link Confluence |
+| `audit-report.md` | Resultado do self-review do /spec |
+| `conformance-report.json` | Validação de conformidade pós-implementação |
+
+## Regras
+
+- Specs NÃO são arquivadas ou movidas. O diretório com tasks checadas É o histórico.
+- Contratos são DEFINIDOS aqui e IMPLEMENTADOS nos repos de código.
+- Todo conteúdo em Português (pt-BR) com acentuação correta, termos técnicos em inglês.

package/templates/github/instructions/ownership.instructions.md

@@ -0,0 +1,45 @@
+---
+applyTo: "specs/**,projects.yml,docs/**,.agents/**"
+---
+
+# Rule: Artifact Ownership (RACI)
+
+> Source of truth: `.agents/rules/ownership.instructions.md`
+> Este arquivo aplica as regras de ownership automaticamente quando Copilot edita specs, docs ou projects.yml.
+
+Antes de criar ou modificar qualquer artefato, leia `.agents/rules/ownership.instructions.md` para consultar a matriz RACI completa.
+
+## Resumo
+
+- Cada artefato tem exatamente **um Owner** (cria) e no máximo **um Updater** (modifica após criação).
+- Outros skills podem **Ler** ou **Validar**, mas nunca **Escrever**.
+- Se dois skills escrevem no mesmo artefato, um deles está errado.
+
+## Artefatos locais — quem escreve o quê
+
+| Artefato | Owner | Updater |
+|----------|-------|---------|
+| `projects.yml` | /setup | /spec, /dev |
+| `docs/architecture.md` | /setup | /discovery |
+| `specs/NNN/brief.md` | /spec | — |
+| `specs/NNN/scenarios.md` | /spec | — |
+| `specs/NNN/contracts.md` | /spec | — |
+| `specs/NNN/tasks.md` | /spec | — |
+| `specs/NNN/links.md` | /spec | /dev |
+| `specs/NNN/audit-report.md` | /spec | — |
+| `specs/NNN/conformance-report.json` | /dev | — |
+
+## Labels de feature (fluxo sequencial)
+
+```
+em-discovery -> aguardando-po -> prd-review -> prd-aprovado -> em-spec -> em-dev -> done
+```
+
+- `prd-aprovado` e `prd-rejeitado` são adicionados pelo **PO manualmente**
+- Todos os outros labels são adicionados pelo skill automaticamente
+
+## Dual-platform sync
+
+Este projeto suporta Claude Code e Copilot. Ao modificar agents, rules ou skills, atualize ambas as plataformas. Consulte a regra 6 em `.agents/rules/ownership.instructions.md` para a tabela de mapeamento completa.
+
+Para a matriz RACI completa (incluindo artefatos Confluence), consulte `.agents/rules/ownership.instructions.md`.

package/templates/github/prompts/dev.prompt.md

@@ -0,0 +1,19 @@
+---
+description: "Orquestrar implementação de uma spec aprovada"
+mode: agent
+tools:
+  - github
+  - terminal
+  - filesystem
+  - fetch
+---
+
+Orquestre a implementação de uma spec aprovada. Siga o fluxo:
+
+1. Leia `.agents/skills/dev-orchestrator/SKILL.md` e siga TODAS as instruções
+2. Leia a spec aprovada em `specs/NNN-nome/`
+3. Leia `specs/NNN-nome/audit-report.md` — se tem ❌, pare e reporte
+4. Selecione o agent certo pela stack (projects.yml)
+5. Crie issues, branches, implemente com TDD, valide, crie MRs
+6. Após merge, atualize docs vivas no Confluence
+7. Notifique no Google Chat em cada transição