diff --git a/.cursor/skills/plan-issue/SKILL.md b/.cursor/skills/plan-issue/SKILL.md index 882ea6d1..1d997d1d 100644 --- a/.cursor/skills/plan-issue/SKILL.md +++ b/.cursor/skills/plan-issue/SKILL.md @@ -3,9 +3,11 @@ name: plan-issue description: >- Transforma ideias humanas em Issues GitHub + planos de intenção em docs/plans/ (persona, fluxo, objetivo, direção suave no código — sem - decisões duras de engenharia). Divide o pedido nas menores tarefas que - ainda fazem sentido. Use quando o usuário pedir /plan-issue, planejar - features, fatiar um pedido em Issues, ou registrar trabalho novo na fila. + decisões duras de engenharia). Se o item muda UI, apresenta no gate um + Cursor canvas com rascunho visual UI/UX. Divide o pedido nas menores + tarefas que ainda fazem sentido. Use quando o usuário pedir /plan-issue, + planejar features, fatiar um pedido em Issues, ou registrar trabalho novo + na fila. disable-model-invocation: true --- @@ -33,6 +35,8 @@ rascunho local (Issue: —) 4. **Promote só depois do plano em `main`.** Nunca flipar para `ready` com o PR ainda aberto — isso recria a race de claim. Caminhos: (A) agente no fim do Passo 6 após merge; (B) Action determinística no merge que lê `Related #N` (OPS18). Ambos idempotentes. 5. **Planos de Issues `in-progress` / `done` / `in-prod` são imutáveis.** Não editar `docs/plans/.md` nem o body de intenção dessas Issues. Refino → **plano + Issue novos** (sucessor; `depends` no pai se fizer sentido). Enquanto a Issue ainda é só `blocked`/`ready` (sem claim), editar o mesmo plano ainda é barato. +**Canvas UI (obrigatório se muda UI):** itens com superfície Impeccable **B / C / D** (ou qualquer mudança do que o usuário vê/toca) devem ter um **Cursor canvas** de rascunho UI/UX no gate — ver [ui-draft-canvas.md](ui-draft-canvas.md). Classe A / sem UI → sem canvas. + ## Divisão com as skills de execução | Skill | Papel | @@ -41,7 +45,7 @@ rascunho local (Issue: —) | **`work-issue`** | Humano supervisiona: claim → plano de **implementação** (Plan mode) → **pausa** para confirmação → executa. | | **`agent-work-issue`** | Pool / autonomia: Issue já claimada → plano de implementação → executa sem pausa → `/simplify` → `capture-review-debts` → PR Ready + auto-merge. | -Aqui **não** se implementa código, **não** se escreve plano de implementação, **não** se roda Impeccable craft/critique/polish. +Aqui **não** se implementa código de produto, **não** se escreve plano de implementação, **não** se roda Impeccable craft/critique/polish. O canvas de rascunho UI/UX é artefato do **gate de intenção**, não entrega de app. **Shaping (não tour):** aplique [shaping.md](shaping.md) em silêncio — appetite, fatia mínima útil, rabbit holes de produto, self-score ≥4 antes de gravar. @@ -54,7 +58,7 @@ Aqui **não** se implementa código, **não** se escreve plano de implementaçã - [ ] 2. Reserva de IDs de uma vez por trilha (roadmap legacy + issuesById()) - [ ] 3. Por item (ordem topológica): classificar → fatiar → explorar só o suficiente → intenção completa - [ ] 4. Sugestão de modelo × effort via model-selection (uma linha por item) -- [ ] 5. GATE: overview do lote + esboços de fluxo (B/C/D) → confirmar/iterar (PARAR aqui até o humano confirmar) +- [ ] 5. GATE: overview do lote + canvas UI/UX (se muda UI) + esboços de fluxo → confirmar/iterar (PARAR aqui até o humano confirmar) - [ ] 6. Registro: register --blocked (se --plan) → PR Related → merge → promote ready ``` @@ -88,10 +92,10 @@ Ordem topológica (dependente cita ID do dependido). Por item: | Decisão de NÃO fazer | Comentário/doc, não Issue | 2. **Explorar o código o mínimo** — só para apontar **direção** (rotas/pastas/domínios prováveis) e evitar duplicar algo já entregue. Não inventar signatures, collections novas como decisão travada, nem diagramas de componentes. -3. **Superfície UI (A–D)** como dica para quem for executar — não semear brief Impeccable completo nem wireframe de implementação. Classe C/D: esboço de fluxo persona (ASCII curto) no gate, não especificação de layout. +3. **Superfície UI (A–D)** como dica para quem for executar — não semear brief Impeccable completo. Classe **B/C/D** (ou qualquer mudança de UI): criar **Cursor canvas** de rascunho UI/UX ([ui-draft-canvas.md](ui-draft-canvas.md) + skill `canvas`) **antes do gate**; ASCII no plano fica opcional. Classe **A** / sem UI: sem canvas. 4. **Dados (intenção)** ou `Dados: N/A`. 5. **Posicionamento:** `P0..P3`, `depends`, appetite, janela eleitoral se relevante, `serializes` se tocar recurso compartilhado (ex. migrations) — sem detalhar a migration. -6. **Plano de intenção** em `docs/plans/.md` via [intention-template.md](intention-template.md). Self-score ≥4/5 ([shaping.md](shaping.md)). +6. **Plano de intenção** em `docs/plans/.md` via [intention-template.md](intention-template.md), com campo **Canvas UI** preenchido (path do `.canvas.tsx` ou `N/A`). Self-score ≥4/5 ([shaping.md](shaping.md)). ### O que é proibido no plano de intenção @@ -109,6 +113,7 @@ Ordem topológica (dependente cita ID do dependido). Por item: - Appetite e fora de escopo (produto) - **Direção provável no codebase** (pastas/rotas/domínios — hipotética, revisável) - Questões em aberto com **Opções + Recomendação de produto** (não de engenharia) +- **Se muda UI:** canvas de rascunho UI/UX no gate ([ui-draft-canvas.md](ui-draft-canvas.md)) + link no plano ## Passo 4 — Modelo × effort @@ -123,10 +128,11 @@ Skill `model-selection`. Registre no cabeçalho (`Model:`) e no gate. Antes de criar Issues **ou** abrir PR de planos: - Overview: ID, título, prio, depends, appetite, modelo, link do plano local -- Esboços de fluxo persona para superfícies B/C/D (se houver) +- **Para cada item que muda UI:** link markdown absoluto do canvas `plan--ui-draft.canvas.tsx` (abrir ao lado do chat) — este é o rascunho visual a validar +- Esboço textual de fluxo só se ajudar; não substitui o canvas quando há UI - Perguntas acumuladas numa rodada, recomendação de produto primeiro -**Pare e espere.** Itere até confirmação explícita do lote. Só então Passo 6. +**Pare e espere.** Itere (incluindo o canvas, se houver UI) até confirmação explícita do lote. Só então Passo 6. ## Passo 6 — Registro (ordem fixa) diff --git a/.cursor/skills/plan-issue/intention-template.md b/.cursor/skills/plan-issue/intention-template.md index 3099db88..88f153aa 100644 --- a/.cursor/skills/plan-issue/intention-template.md +++ b/.cursor/skills/plan-issue/intention-template.md @@ -13,6 +13,7 @@ Issue: # (após `pnpm agent:register`; senão "—") Priority: Model: Impeccable: — +Canvas UI: -ui-draft.canvas.tsx> Appetite: Responsável: — @@ -29,7 +30,8 @@ Responsável: — ### Esboço de fluxo (B/C/D) - + \```text [início] → … → [outcome] @@ -77,6 +79,7 @@ Responsável: — ## Referências - GitHub Issue # +- Canvas UI (gate): - - `AGENTS.md` / `docs/ARCHITECTURE.md` — só se o item toca convenção já travada no repo ```` @@ -84,6 +87,7 @@ Responsável: — Notas: - Alvo: ~60–100 linhas. Mais que isso costuma significar engenharia vazando para a intenção. -- Classe **A:** `Impeccable: A — N/A`; omita esboço de fluxo. +- Classe **A:** `Impeccable: A — N/A`; `Canvas UI: N/A`; omita esboço de fluxo. +- Classe **B/C/D:** canvas obrigatório no gate ([ui-draft-canvas.md](ui-draft-canvas.md)); leia a skill `canvas` ao escrever o `.canvas.tsx`. - Não rode `/impeccable` aqui. - Self-score shaping ≥4/5 antes de gravar. diff --git a/.cursor/skills/plan-issue/shaping.md b/.cursor/skills/plan-issue/shaping.md index 2c553e43..ca7cadca 100644 --- a/.cursor/skills/plan-issue/shaping.md +++ b/.cursor/skills/plan-issue/shaping.md @@ -53,4 +53,6 @@ Armadilhas se alguém “só completar” o desejo humano: 4. Direção no codebase é hipótese (não contrato técnico)? 5. Zero decisões duras de engenharia no plano? +Se o item muda UI: canvas de rascunho no gate ([ui-draft-canvas.md](ui-draft-canvas.md)) antes de registrar — não conta como “engenharia no plano”; é validação visual da intenção. + <4 → corrigir antes de gravar / registrar Issue. diff --git a/.cursor/skills/plan-issue/skills-map.md b/.cursor/skills/plan-issue/skills-map.md index 5b45b2e3..38e58cb8 100644 --- a/.cursor/skills/plan-issue/skills-map.md +++ b/.cursor/skills/plan-issue/skills-map.md @@ -39,6 +39,8 @@ No Teqo: **idea-refine / interview** antes se vago; **spec + plan + tasks** = es `frontend-ui-engineering`, `security-and-hardening`, `performance-optimization`, `code-review-and-quality`, `code-simplification`, `observability-and-instrumentation`, `shipping-and-launch`, `ci-cd-and-automation`, `git-workflow-and-versioning`, `deprecation-and-migration`, `debugging-and-error-recovery`, `browser-testing-with-devtools` — entram em `work-issue` / gates do repo, não no registro da Issue. +**Exceção de superfície:** a skill Cursor **`canvas`** é usada no `plan-issue` só para o **rascunho UI/UX do gate** quando o item muda UI ([ui-draft-canvas.md](ui-draft-canvas.md)). Não é implementação de `/campanha` nem substituto de Impeccable. + ## Precedência quando conflita 1. Convenções Teqo (`AGENTS.md`, access, migrations, Consent fail-closed) diff --git a/.cursor/skills/plan-issue/ui-draft-canvas.md b/.cursor/skills/plan-issue/ui-draft-canvas.md new file mode 100644 index 00000000..0cd9d427 --- /dev/null +++ b/.cursor/skills/plan-issue/ui-draft-canvas.md @@ -0,0 +1,54 @@ +# Canvas de rascunho UI/UX (plan-issue) + +Quando o item **muda UI** (classe Impeccable **B / C / D**, ou qualquer superfície que o usuário vê/toca), o gate **obrigatoriamente** apresenta um **Cursor canvas** com rascunho visual da intenção — não ASCII sozinho, não wireframe de implementação. + +Leia e siga a skill `canvas` (`~/.cursor/skills-cursor/canvas/SKILL.md`) ao criar/editar o arquivo. + +## Quando criar + +| Situação | Canvas? | +| -------- | ------- | +| `Impeccable: A` / N/A sem UI / chore sem superfície | Não | +| Encaixe em tela existente (B) | Sim — estado atual → estado desejado da área tocada | +| Fluxo novo ou redesign local (C/D) | Sim — jornada + telas/estados chave | +| Só copy/label sem rearranjo | Não (a menos que o humano peça ver o contexto) | + +Um canvas por item com UI (ou um canvas do lote com secções por ID, se o lote for pequeno e as superfícies forem do mesmo fluxo). Preferir **um arquivo por item** (`plan--ui-draft.canvas.tsx`). + +## Onde gravar + +Path canônico do IDE (não no repo Teqo): + +`/Users//.cursor/projects//canvases/plan--ui-draft.canvas.tsx` + +Ex.: `plan-c42-ui-draft.canvas.tsx`. Escreva o arquivo com a tool de write; não peça `mkdir`. No chat do gate, linke o path absoluto em markdown. + +## O que mostrar (produto) + +Rascunho de **intenção de uso**, legível sozinho: + +1. **Persona + job** (uma linha). +2. **Jornada** (passos / estados) — o que a pessoa vê e decide. +3. **Layout esquemático** das superfícies tocadas: zonas (lista, detalhe, formulário, mapa, empty, erro), hierarquia de atenção, CTAs primários/secundários. +4. **Estados críticos** se mudarem o aceite (vazio, loading, sem permissão, fail-closed) — só os que importam ao produto. +5. **Fora de escopo visual** em callout curto (o que este item *não* redesenha). + +Use `Stack` / `Grid` / `Row` / `Card` / `Pill` / `Callout` / `Text` / `H1`–`H3` de `cursor/canvas`. Cores só via `useHostTheme()`. Pode usar caixas/`div` com bordas de token para simular regiões de tela — isso é rascunho de UX, não componente do app. + +## O que é proibido no canvas + +- Assinaturas, nomes de arquivos/componentes obrigatórios, schema, migrations +- Brief Impeccable completo, craft/critique/polish, paleta/brand do produto Teqo +- Mock com dados inventados como se fossem métricas reais (“No data”, KPIs zerados) — omita secções sem conteúdo +- Gradientes, emojis, box-shadow, arco-íris (regras da skill canvas) +- Travar o executor numa única forma técnica + +## Relação com o plano em `docs/plans/` + +- No plano: campo **Canvas UI:** link/path do `.canvas.tsx` (ou `N/A — sem UI`). +- Esboço ASCII no markdown vira **opcional** (backup textual); o **canvas é o artefato do gate** para UI. +- O canvas **não** é commitado no repo Teqo por default — é artefato de sessão do gate. Se o humano pedir arquivar no repo, só com pedido explícito (fora do fluxo padrão). + +## Gate + +Antes de `pnpm agent:register`, mostre o overview do lote **e** o(s) canvas de UI. Itere no canvas até o humano confirmar a intenção visual. Só então registre a Issue.