@guilhermefsousa/open-spec-kit 0.0.1

package/templates/agents/skills/setup-project/SKILL.md

@@ -0,0 +1,459 @@
+---
+name: setup-project
+description: "Bootstraps a new project from Confluence demands. Reads PO inputs, generates living docs (Vision, Glossary, Domain), and prepares the spec repo."
+metadata:
+  works_on: [copilot, antigravity, claude]
+argument-hint: "[Confluence space key] or [page ID of the project root]"
+---
+
+# Setup Project
+
+## Objective
+
+Bootstrap a new project from raw PO inputs on Confluence. Generate the initial living documents and prepare the spec repo for the first feature cycle.
+
+## Before you start
+
+1. Read `projects.yml` — if already filled (has repos with status != template):
+   - If argument contains `--force`: proceed (will overwrite existing config and re-create missing pages)
+   - Otherwise: **stop** with message: "Projeto já configurado. Para re-executar, passe `--force` (ex: `/setup MFS --force`)."
+2. **Confluence access — ALWAYS use MCP:**
+   - All Confluence operations (read pages, create pages, labels) MUST use the MCP server (`confluence` in `.mcp.json`).
+   - **Do NOT use curl, fetch, or direct REST calls** — even if `.env` has credentials.
+   - If MCP is not responding → **STOP**: "MCP Confluence não disponível. Execute 'open-spec-kit doctor' para diagnosticar."
+3. **Resolve the argument (space key or page ID):**
+   a. If `projects.yml` has `confluence.root_page_id` → use as page ID (do NOT ask the user)
+   b. If `projects.yml` has `confluence.space` → use as space key
+   c. If neither found → ask the user
+
+## Inputs
+
+- **Argument:** Confluence space key (e.g., `GERFAT`) OR page ID of the project root (e.g., `589824`)
+- PO's raw files in `Demandas/` on Confluence (docs, PDFs, spreadsheets, screenshots — any format)
+
+### How the argument is resolved
+
+The setup supports two Confluence layouts:
+
+**1 space = 1 project (simple):**
+- Argument is a space key (ex: `MFS`, `GERFAT`)
+- All pages are created at the space root
+- `Demandas/` is a top-level page in the space
+
+**1 space = N projects (multi-project):**
+- Argument is the page ID of the project root page (ex: `589824` for "Todo App")
+- All pages are created as children of that root page
+- `Demandas/` is a child of the project root page
+
+**Detection:** if the argument is numeric, treat as page ID. Otherwise, treat as space key.
+
+## Flow
+
+### 1. Resolve project root and read Demands
+
+**Follow EXACTLY this algorithm via MCP, no deviations:**
+
+**1a.** Resolve `ROOT_ID`:
+- If argument is numeric → `ROOT_ID = argument`
+- If argument is text (space key) → `ROOT_ID = space root page`
+- If no argument → read `projects.yml` (`confluence.root_page_id` or `confluence.space`)
+
+**1b.** List DIRECT children of `ROOT_ID` (1 MCP call). Save the list.
+
+**1c.** In the list, find the page titled "Demandas" (case-insensitive). Save as `DEMANDAS_ID`.
+- If not found → **STOP**: "Pasta Demandas/ não encontrada. O PO precisa criá-la."
+
+**1d.** Check demand label. If no `novo` label, add `novo`. Then change to `processando`.
+
+**1e.** List DIRECT children of `DEMANDAS_ID` (1 MCP call). Save as `DEMAND_PAGES`.
+- If empty → **STOP**: "Demandas/ está vazia. O PO precisa adicionar documentos."
+
+**1f.** For EACH page in `DEMAND_PAGES`:
+- Read FULL content (entire body) via MCP
+- Read page attachments via MCP
+- Do **NOT** navigate to sub-pages — read only this level
+
+**Attachment handling:**
+- If an attachment can be read (text, markdown, etc.): read and incorporate
+- If an attachment CANNOT be read (binary, image, PDF that MCP can't parse): register in a "Nao processados" list with filename, format, and parent page. Mark as "NAO PROCESSADO — formato nao suportado pelo MCP. Leitura manual necessaria."
+
+**Call budget:**
+
+| Operation | Calls |
+|-----------|-------|
+| Children of root | 1 |
+| Children of Demandas | 1 |
+| Content of each demand | N (one per page) |
+| **Total** | **2 + N** |
+
+**FORBIDDEN:**
+- Generic CQL searches
+- Listing ancestors
+- Recursive navigation (children of children)
+- Using curl/fetch/direct HTTP
+
+**After reading, compile a structured understanding of:**
+- What the product is and who it serves
+- Business domain rules and flows
+- Existing systems and integrations
+- Key terms and concepts
+- Stack and technology constraints
+- Repos needed (from architecture description, or inferred from stack)
+
+### 2. Read Figma design context (optional)
+
+**Condition**: this step ONLY runs if BOTH conditions are true:
+1. `projects.yml` has a `figma:` section with `file_url` filled
+2. The Figma MCP is available (`figma` server configured in `.mcp.json`)
+
+If either condition fails, **skip silently** — do not report an error or ask for configuration.
+
+**If available:**
+1. Extract the file key from the URL in `projects.yml` → `figma.file_url`
+   - The file key is the segment after `/design/` or `/file/` in the URL (e.g., `https://www.figma.com/design/ABC123/Name` → file key = `ABC123`)
+2. Use `get_design_context` with the file key to get an overview
+3. Use `get_metadata` to get the page/frame structure
+4. Incorporate into the structured understanding (compiled in step 1):
+   - **Screens identified**: list main Figma pages/frames — use to enrich Feature identification (Step 3.5)
+   - **Design system components**: if reusable components exist, register them — use to enrich the Glossário (Step 3.2)
+   - **Visual flows**: if Figma organizes frames into flows (e.g., "Login Flow", "Onboarding"), map them — use to enrich Domínio/Fluxos (Step 3.3)
+   - **Visible text**: labels, placeholders, error messages — use to enrich Regras (validations)
+
+**Do NOT use `get_screenshot`** in this step — the goal is structural context, not visual captures.
+
+When generating the living docs (step 3), reference Figma screens where relevant:
+- In **Fluxos**: "Fluxo visual no Figma: frame '{frame_name}'"
+- In **Visão do Produto**: mention if Figma contains navigable prototypes
+
+**Rule**: Figma is a SUPPLEMENTARY source. It enriches what the PO wrote in `Demandas/`, never replaces it. If Figma shows something that contradicts a PO document, register as "A CONFIRMAR — divergência entre Figma e documento do PO."
+
+### 3. Generate living docs on Confluence
+
+Via MCP Confluence, create these pages **under the project root**, in this order.
+
+**Title prefix (multi-project)**: when the layout is multi-project (argument is a numeric page ID), ALL created page titles must be prefixed with the project acronym (`sigla` field in projects.yml). This avoids title conflicts within the same Confluence space. The project root page does NOT get a prefix (it's already unique by definition).
+
+Title format:
+- Domain pages: `{SIGLA} — Visão do Produto`, `{SIGLA} — Glossário`, etc.
+- Features: `{SIGLA}-NNN - Feature name` (e.g., `FT-001 - Cadastro e Autenticação`)
+
+In simple layout (1 space = 1 project), the prefix is optional — no conflict risk.
+
+**Required emojis**: include the emoji directly IN THE PAGE TITLE (not as a separate parameter — not every API/MCP supports emoji as a separate field):
+- `🎯 {SIGLA} — Visão do Produto`
+- `📖 {SIGLA} — Glossário`
+- `🏛️ {SIGLA} — Domínio`
+- `📏 {SIGLA} — Regras`
+- `🔀 {SIGLA} — Fluxos`
+- `📊 {SIGLA} — Tabelas de Referência`
+- `🔌 {SIGLA} — Integrações`
+- `🚀 Features`
+- `📦 Arquivados`
+- Business features: `🚀 {SIGLA}-NNN - Feature name`
+- Infrastructure feature: `⚙️ {SIGLA}-000 - Infraestrutura e Scaffold`
+
+**Step 3.1 — Visão do Produto** (max 1 page):
+
+Must contain these sections:
+- **O que e**: what the product is (1-2 paragraphs)
+- **Para quem**: target users/personas, expanded beyond a single line
+- **Por que existe**: business motivations
+- **Premissas**: assumptions stated in the PO docs (copy them, don't summarize)
+- **Escopo da v1**: what's in
+- **Fora de escopo**: what's explicitly out
+- **Metricas de sucesso**: if the PO defined metrics, use them. If not, write "Metricas de negocio — A CONFIRMAR. Nao definidas pelo PO." Do NOT invent metrics. Do NOT use functional test criteria as metrics.
+- **Restricoes**: mandatory tech, environment, compliance constraints
+
+**Step 3.2 — Glossario** (table format):
+
+Columns: Termo | Definicao | Contexto de uso
+
+Completeness criteria:
+- Every domain noun mentioned in the PO documents must appear (entities, roles, states, concepts)
+- Every technical component mentioned must appear (infrastructure, protocols, patterns)
+- After building the glossary, **re-read the PO documents in Demandas/** and check: is there any term used more than once that is NOT in the glossary? If yes, add it.
+
+Minimum expected terms for any project:
+- All entities (user, task, list, etc.)
+- All states/enums (status values, priorities, etc.)
+- All roles/personas
+- All infrastructure components (DB, queue, cache, etc.)
+- Domain-specific concepts (ownership, async processing, etc.)
+
+**Step 3.3 — Dominio/** (parent page + 4 children):
+
+**Regras** (table format):
+- Columns: ID | Regra | Fonte | Verificavel
+- ID: sequential (RN-01, RN-02, ...)
+- **Fonte**: MUST reference the PRD section the rule was extracted from (ex: "PRD §9.4 — Gerenciamento de tarefas"). This enables traceability.
+- Verificavel: how to test this rule (concrete, not vague)
+- Group rules by domain area (ownership, auth, entities, etc.)
+- After writing all rules, **re-read the PO documents** looking for "deve", "nao pode", "obrigatorio", "somente", "exclusivamente" — any missed rule must be added
+
+**Fluxos**:
+- One section per business flow
+- Each flow: numbered steps describing the happy path
+- After the numbered steps, add a **Mermaid** `flowchart TD` diagram visualizing the flow. Example:
+  ```mermaid
+  flowchart TD
+      A[Usuário submete formulário] --> B{Dados válidos?}
+      B -->|Sim| C[Salvar no banco]
+      B -->|Não| D[Retornar erros]
+      C --> E[Enviar confirmação]
+  ```
+- **Exceções**: after EVERY flow, list what can go wrong (error cases, edge cases, invalid inputs). Format as a bullet list under "Excecoes" heading. If no exceptions are obvious, write "Excecoes: nenhuma identificada — A CONFIRMAR."
+- If a flow involves async processing, clearly mark the sync/async boundary
+- **Sequence diagram**: if the flow involves **more than 1 system component** (e.g., Frontend, BFF, API, Worker, DB, RabbitMQ), add a **Mermaid `sequenceDiagram`** IN ADDITION to the flowchart, showing component interactions. The **flowchart** shows the LOGIC (decisions, paths). The **sequenceDiagram** shows the EXECUTION (who calls whom, sync vs async). Purely business flows (no technical interaction) only need the flowchart. Example:
+  ```mermaid
+  sequenceDiagram
+      participant FE as Frontend
+      participant BFF as BFF Web
+      participant API as API
+      participant DB as PostgreSQL
+      participant RMQ as RabbitMQ
+      participant WRK as Worker
+
+      FE->>BFF: POST /bills (SSO Corp token)
+      BFF->>API: POST /api/v1/bills (JWT)
+      API->>DB: INSERT bills (status: GERANDO)
+      API->>RMQ: Publish fila_nova_fatura
+      API-->>BFF: 202 Accepted
+      BFF-->>FE: 202 Accepted
+      RMQ->>WRK: Consume fila_nova_fatura
+      WRK->>DB: UPDATE bills (status: GERADA)
+  ```
+
+**Tabelas de Referencia**:
+- All enums, categories, reference data
+- For each enum: if values are defined in the PRD, list them. If inferred, mark "A CONFIRMAR"
+- **State transitions**: if an entity has states (ex: task status), define the valid transitions as a table: "De | Para | Permitido? | Condicao". If the PRD doesn't define transitions, create a proposed table and mark ALL rows as "A CONFIRMAR"
+- After the table, add a **Mermaid** `stateDiagram-v2` visualizing the transitions. Example:
+  ```mermaid
+  stateDiagram-v2
+      [*] --> Aberta
+      Aberta --> EmProgresso
+      EmProgresso --> Concluida
+      EmProgresso --> Bloqueada
+      Bloqueada --> EmProgresso
+      Concluida --> [*]
+  ```
+- Dashboard indicators with calculation formulas
+
+**Integracoes**:
+- Internal components: table with component, technology, responsibility
+- Event flow: producer → broker → consumer → action
+- For each event: define the minimum expected payload fields. Mark as "A CONFIRMAR — payload a definir na spec tecnica"
+- External integrations: list or write "Nenhuma na v1"
+
+**Step 3.4 — Structure pages:**
+- Create `Features/` parent page under the project root if it doesn't exist
+- Create `Arquivados/` parent page under the project root if it doesn't exist
+
+**Step 3.5 — Create initial feature pages:**
+
+**Step 3.5a — Feature 000 — Infraestrutura e Scaffold (mandatory for new projects):**
+
+If `projects.yml` has `status: inception` (new project, no active repos), ALWAYS create as the FIRST feature:
+
+- Title: `⚙️ {SIGLA}-000 - Infraestrutura e Scaffold`
+- Label: `em-discovery`
+- Content (in pt-BR):
+
+```
+| Campo | Valor |
+|-------|-------|
+| ID | {SIGLA}-000 |
+| Depende de | — (nenhuma, esta é a base) |
+| Complexidade | média |
+| Repos envolvidos | {listar todos os repos de projects.yml} |
+
+## Escopo
+
+Criação da infraestrutura base para o projeto:
+- Criação dos repositórios: {listar repos com nome e tipo}
+- Pipeline de CI/CD (build, test, lint) para cada repo
+- Docker Compose para ambiente local (todos os serviços + dependências)
+- Script de criação do banco de dados (DDL completo)
+- Health checks e endpoints de diagnóstico
+- Configuração de variáveis de ambiente (.env, secrets)
+- README com instruções de setup local
+
+## Critério de aceite
+
+- Todos os repos criados e acessíveis
+- `docker-compose up` sobe o ambiente local completo
+- Health check de cada serviço retorna 200
+- Pipeline de CI passa em cada repo (build + tests)
+```
+
+All subsequent features ({SIGLA}-001 onwards) have an implicit dependency on {SIGLA}-000.
+
+**Step 3.5b — Business features:**
+
+Analyze the PO documents in `Demandas/` and identify distinct features/capabilities described. For EACH feature identified:
+
+1. Create a child page under `Features/` with title: `🚀 {SIGLA}-NNN - Feature name` (numbering sequential: 001, 002, ...). E.g., `🚀 FT-001 - Cadastro e Autenticação`, `🚀 TD-003 - Gerenciamento de Tarefas`
+2. Content MUST start with a metadata table:
+   ```
+   | Campo | Valor |
+   |-------|-------|
+   | ID | {SIGLA}-NNN |
+   | Depende de | {SIGLA}-000 (e outras se houver, separadas por vírgula) |
+   | Complexidade | baixa / média / alta |
+   | Repos envolvidos | {quais repos participam} |
+   ```
+   After the table: 1-2 paragraphs extracted from PO documents describing what the feature does.
+3. Add label `em-discovery` (ready for /discovery to process)
+
+If the PO documents describe a SINGLE monolithic system without clear feature boundaries, create ONE feature page covering the full scope and note: "Feature única — considerar quebra em sub-features durante /discovery."
+
+This step ensures /discovery always finds a feature page to work with.
+
+### 4. Set up the spec repo
+
+In the local spec repo:
+
+**Fill `projects.yml`:**
+- Project name, domain, status, team size
+- **Sigla**: `sigla: XX` — short abbreviation (2-4 letters) used as prefix in Confluence titles and feature IDs. Derive from project name (e.g., FinTrack → FT, Todo → TD, CRM → CRM). Ask the dev if ambiguous.
+- Stack (from PO's docs or ask the dev)
+- **VCS**: `vcs: github | gitlab` and `vcs_org: {org/group}` — ask the dev if not obvious from context
+- **Repos**: detect from the PRD what repos will be needed. If the PRD mentions "API .NET", declare a `project-api` repo with stack `dotnet` and status `planned`. If it mentions "React frontend", declare a `project-front` repo with stack `nodejs` and status `planned`. Do NOT leave repos commented out — declare them with `status: planned`.
+- External dependencies
+- Confluence space key and root_page_id (if multi-project layout)
+
+**Create directories:**
+- `docs/lessons/` — empty (used by /dev to log surprises)
+- `docs/decisions/` — empty (used for ADRs)
+
+**Generate `docs/architecture.md` draft:**
+- System components (table: component, technology, responsibility)
+- Data flow diagram — use a **Mermaid** `flowchart` block showing sync (solid arrows `-->`) and async (dotted arrows `-.->`) flows. Example:
+  ```mermaid
+  flowchart LR
+      A[Client] -->|HTTP| B[API]
+      B -->|sync| C[Database]
+      B -.->|async| D[Queue]
+      D -.-> E[Worker]
+  ```
+- Data model — use a **Mermaid** `erDiagram` block for high-level entity relationships. Example:
+  ```mermaid
+  erDiagram
+      Usuario ||--o{ Tarefa : possui
+      Tarefa }o--|| Status : tem
+  ```
+- Events identified (table: event, generates notification?, generates history?)
+- Environment/infrastructure (how it runs)
+- **Decisoes em aberto**: list ALL "A CONFIRMAR" items from all Confluence pages, ranked by impact. High impact = blocks /spec or /dev. Format:
+
+```
+| # | Decisao | Impacto | Bloqueia | Status |
+|---|---------|---------|----------|--------|
+| 1 | Worker separado ou parte da API? | Alto — define repos e CI | /spec | aberta |
+| 2 | Valores do enum de Status | Medio — afeta model e validacao | /dev | aberta |
+```
+
+Status values: `aberta`, `resolvida — [decisão tomada]`. The /discovery updates this column when resolving decisions (exit gate).
+
+Mark sections as "DRAFT — validar com o time"
+
+### MCP failure recovery
+
+If a Confluence page creation fails mid-flow:
+1. Log which pages were successfully created and which failed
+2. Save pending page creations to `docs/pending-confluence-updates.md` with: target parent page, page title, content summary, date
+3. Report to dev: "Setup parcial — {N} de {total} páginas criadas. Páginas faltantes: {list}. Re-execute /setup para tentar criar as faltantes."
+4. On re-execution, check if `docs/pending-confluence-updates.md` exists and attempt to apply pending operations FIRST. Also check which pages already exist (by listing children of the parent page) and only create the missing ones — never duplicate. Remove applied entries from the file.
+
+### 5. Self-review
+
+Before closing the loop, the agent MUST do a self-review:
+
+1. **Re-read the original PO documents in Demandas/** in full
+2. **Compare against each generated page** and check:
+   - Did I miss any section of the PO documents?
+   - Did I miss any term for the glossary?
+   - Did I miss any rule?
+   - Did I miss any flow?
+   - Did I invent anything that isn't in the PO documents?
+3. **Fix any gaps found** by updating the pages
+4. **Report** what was added/fixed in the self-review
+
+### 6. Close the loop
+
+- Change demand label on Confluence: `processando` → `processado`
+- Verify label transition happened (read back the page to confirm)
+- If there are "Nao processados" attachments, add a comment on the demand page listing them
+- Notify Google Chat (if `GCHAT_WEBHOOK_URL` is not set, the script skips silently).
+  **Choose the correct script for the OS:**
+  - Windows (PowerShell): `powershell -ExecutionPolicy Bypass -File ./scripts/notify-gchat.ps1`
+  - Linux/macOS (Bash): `bash ./scripts/notify-gchat.sh`
+
+  Parameters (same for both scripts):
+
+      --card --title "✅ Projeto configurado" --subtitle "{project_name}" --body "📄 <b>Páginas criadas:</b>
+      • Visão do Produto
+      • Glossário ({term_count} termos)
+      • Domínio (Regras, Fluxos, Tabelas, Integrações)
+      • Features ({feature_count} identificadas)
+      • Arquivados
+
+      📊 <b>Métricas:</b>
+      • {rule_count} regras de negócio
+      • {flow_count} fluxos documentados
+      • {open_decisions_count} decisões em aberto ({high_impact_count} alto impacto)" --next "Resolver decisões de alto impacto e rodar /discovery" --button-text "Abrir Visão do Produto" --button-url "{confluence_vision_page_url}"
+
+  Replace `{}` placeholders with actual values from the execution context.
+
+## Rules
+
+1. NEVER invent business context — everything comes from PO's documents
+2. If something is unclear, mark it as "A CONFIRMAR" (not assumed)
+3. **Language**: ALL generated content — Confluence pages AND local files (architecture.md, projects.yml) — MUST be in **Brazilian Portuguese (pt-BR) with correct accents** (e.g., "não" NOT "nao", "autenticação" NOT "autenticacao", "código" NOT "codigo", "é" NOT "e", "já" NOT "ja"). Technical terms stay in English (e.g., RabbitMQ, API, endpoint, status). Tone must be **clear, didactic, and accessible** — as if explaining to someone unfamiliar with the project.
+4. Visão do Produto max 1 page
+5. Glossary entries must have: term + definition + context of use
+6. Domain rules must be verifiable (not vague) and traceable to a PRD section
+7. Every "A CONFIRMAR" must state WHY it's ambiguous (what the PRD says vs. what's missing)
+8. Repos detected from the PO documents must be declared in projects.yml (with status: planned), never commented out
+
+## Quality criteria
+
+The output is considered good when:
+
+- **Glossario**: covers 100% of domain nouns and technical components mentioned in the PO documents
+- **Regras**: every "deve", "nao pode", "obrigatorio" in the PO documents has a corresponding numbered rule
+- **Fluxos**: every flow has a happy path AND exceptions documented
+- **Tabelas**: every enum has values (confirmed or "A CONFIRMAR"), state entities have transition tables
+- **Integracoes**: every async flow has events with producers, consumers, and expected payload fields
+- **Architecture.md**: has an "open decisions" table ranked by impact
+- **projects.yml**: has all detected repos declared (not commented), with stack and status
+- **Self-review**: was performed, gaps were found and fixed (or confirmed none exist)
+
+## Validation checklist
+
+### Prerequisite checks
+- [ ] `Demandas/` exists under project root
+- [ ] `Demandas/` has at least one child page or attachment
+- [ ] Demand label transition: (none/novo) → processando → processado
+
+### Content generated
+- [ ] Visao do Produto: all required sections present (O que é, Para quem, Por que existe, Premissas, Escopo da v1, Fora de escopo, Métricas de sucesso, Restrições)
+- [ ] Glossario: covers all domain terms from PRD (verified by re-read)
+- [ ] Regras: all rules have ID + Fonte (PRD section) + Verificavel
+- [ ] Fluxos: all flows have happy path + exceptions + Mermaid flowchart TD
+- [ ] Tabelas de Referencia: all enums defined, state transitions documented + Mermaid stateDiagram-v2
+- [ ] Integracoes: all events have producer + consumer + expected payload
+- [ ] Features/ page created
+- [ ] Initial feature pages created under Features/ (with label `em-discovery`)
+- [ ] Arquivados/ page created
+
+### Spec repo updated
+- [ ] projects.yml filled with all detected repos (status: planned, not commented)
+- [ ] docs/architecture.md draft with Mermaid diagrams (flowchart, erDiagram) and open decisions table
+
+### Quality gates
+- [ ] Self-review performed (re-read PRD vs. output)
+- [ ] No business context was invented
+- [ ] All ambiguities marked "A CONFIRMAR" with explanation
+- [ ] Unreadable attachments listed as "NAO PROCESSADO"
+- [ ] Demand label changed to `processado` (verified)