From f27985703465adfbf547cdad99eeff6d8daa32b1 Mon Sep 17 00:00:00 2001 From: Iago Laguna Date: Thu, 14 May 2026 15:59:17 -0300 Subject: [PATCH 1/7] chore: bootstrap AI Week artifacts (L1 + L1.5 + L1.7 + L2) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - AGENTS.md com 4 seções obrigatórias + Golden Path mode + skills - CLAUDE.md como symlink para AGENTS.md - .agents/{skills,commands,rules} com 12 skills (specification, implementing, 10x speckit-*) - .claude/* como bridges relativos para .agents/* - .specify/memory/constitution.md (v1.0.0, 5 princípios) - .specify/templates/*.md (5 templates SDD) - .specify/scripts/bash/*.sh (6 scripts: common, create-new-feature, setup-plan, setup-tasks, check-prerequisites, update-agent-context) - .gitignore: /specs e .specify/feature.json Co-Authored-By: Claude Opus 4.7 --- .agents/commands/.gitkeep | 0 .agents/rules/.gitkeep | 0 .agents/skills/implementing/SKILL.md | 54 +++++++++ .agents/skills/specification/SKILL.md | 58 +++++++++ .agents/skills/speckit-analyze/SKILL.md | 42 +++++++ .agents/skills/speckit-checklist/SKILL.md | 52 ++++++++ .agents/skills/speckit-clarify/SKILL.md | 41 +++++++ .agents/skills/speckit-constitution/SKILL.md | 50 ++++++++ .agents/skills/speckit-git-commit/SKILL.md | 61 ++++++++++ .agents/skills/speckit-git-feature/SKILL.md | 46 +++++++ .agents/skills/speckit-implement/SKILL.md | 55 +++++++++ .agents/skills/speckit-plan/SKILL.md | 46 +++++++ .agents/skills/speckit-specify/SKILL.md | 43 +++++++ .agents/skills/speckit-tasks/SKILL.md | 42 +++++++ .claude/commands | 1 + .claude/rules | 1 + .claude/skills | 1 + .gitignore | 6 +- .specify/memory/constitution.md | 95 +++++++++++++++ .specify/scripts/bash/check-prerequisites.sh | 48 ++++++++ .specify/scripts/bash/common.sh | 45 +++++++ .specify/scripts/bash/create-new-feature.sh | 29 +++++ .specify/scripts/bash/setup-plan.sh | 28 +++++ .specify/scripts/bash/setup-tasks.sh | 28 +++++ .specify/scripts/bash/update-agent-context.sh | 36 ++++++ .specify/templates/checklist-template.md | 38 ++++++ .specify/templates/constitution-template.md | 28 +++++ .specify/templates/plan-template.md | 48 ++++++++ .specify/templates/spec-template.md | 60 ++++++++++ .specify/templates/tasks-template.md | 33 +++++ AGENTS.md | 113 ++++++++++++++++++ CLAUDE.md | 1 + 32 files changed, 1228 insertions(+), 1 deletion(-) create mode 100644 .agents/commands/.gitkeep create mode 100644 .agents/rules/.gitkeep create mode 100644 .agents/skills/implementing/SKILL.md create mode 100644 .agents/skills/specification/SKILL.md create mode 100644 .agents/skills/speckit-analyze/SKILL.md create mode 100644 .agents/skills/speckit-checklist/SKILL.md create mode 100644 .agents/skills/speckit-clarify/SKILL.md create mode 100644 .agents/skills/speckit-constitution/SKILL.md create mode 100644 .agents/skills/speckit-git-commit/SKILL.md create mode 100644 .agents/skills/speckit-git-feature/SKILL.md create mode 100644 .agents/skills/speckit-implement/SKILL.md create mode 100644 .agents/skills/speckit-plan/SKILL.md create mode 100644 .agents/skills/speckit-specify/SKILL.md create mode 100644 .agents/skills/speckit-tasks/SKILL.md create mode 120000 .claude/commands create mode 120000 .claude/rules create mode 120000 .claude/skills create mode 100644 .specify/memory/constitution.md create mode 100755 .specify/scripts/bash/check-prerequisites.sh create mode 100755 .specify/scripts/bash/common.sh create mode 100755 .specify/scripts/bash/create-new-feature.sh create mode 100755 .specify/scripts/bash/setup-plan.sh create mode 100755 .specify/scripts/bash/setup-tasks.sh create mode 100755 .specify/scripts/bash/update-agent-context.sh create mode 100644 .specify/templates/checklist-template.md create mode 100644 .specify/templates/constitution-template.md create mode 100644 .specify/templates/plan-template.md create mode 100644 .specify/templates/spec-template.md create mode 100644 .specify/templates/tasks-template.md create mode 100644 AGENTS.md create mode 120000 CLAUDE.md diff --git a/.agents/commands/.gitkeep b/.agents/commands/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/.agents/rules/.gitkeep b/.agents/rules/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/.agents/skills/implementing/SKILL.md b/.agents/skills/implementing/SKILL.md new file mode 100644 index 00000000..da40adaa --- /dev/null +++ b/.agents/skills/implementing/SKILL.md @@ -0,0 +1,54 @@ +--- +name: implementing +description: Implement an approved spec end-to-end in the pickup-points-modal repo — branch, code, tests, lint, typecheck, build, commit, and open a PR following Conventional Commits and the project constitution. +type: skill +--- + +# implementing + +Use esta skill quando o usuário disser "implementa", "implementa essa spec", +"implementa specs/.md", ou pedir execução autônoma a partir de uma +spec já aprovada. + +## Pré-requisitos + +- `specs//spec.md` existe, aprovado pelo usuário. +- Constituição lida ([.specify/memory/constitution.md](../../../.specify/memory/constitution.md)). +- AGENTS.md lido para limites de autonomia. + +Se algum desses faltar, **pare** e peça para o usuário rodar a skill +`specification` primeiro. + +## Fluxo + +1. **Branch.** `git checkout -b feat/` (use `fix/` para + bug fix, `chore/` para tooling). +2. **Quebrar em tasks.** Liste 3–8 tasks concretas em TodoWrite. +3. **Implementar task-a-task.** + - Para cada task: editar arquivos → rodar `yarn lint --fix` → rodar + `yarn test` no escopo afetado → marcar task completa. + - Nunca pule testes. Princípio 2 da constitution. +4. **Lint & types.** Rode `yarn lint` e `yarn lint:ts` antes de commitar. +5. **i18n.** Se adicionou string visível, rode `yarn lint:locales`. + Princípio 3 da constitution. +6. **Build.** `yarn build` precisa passar. +7. **Commit.** Use `speckit-git-commit` para formatar Conventional Commits. +8. **PR.** Abra com `gh pr create` linkando a spec, princípios afetados, + e plano de teste manual. + +## Autonomy limits + +Veja [AGENTS.md](../../../AGENTS.md). Em resumo: + +- **Não tocar** `manifest.json`, `package.json`, `.travis.yml`, + `.github/`, `.vtex/deployment.yaml` sem confirmação explícita. +- **Não publicar.** `vtex publish` e `npm publish` são manuais. +- **Não force-push** na branch que já tem PR aberto. + +## Quando reportar de volta + +Pause e reporte para o usuário quando: + +- O build falhar de um jeito que sugere mudança em dep range. +- O typecheck encontrar problema em código que você não tocou. +- Uma decisão de produto/UX não estiver na spec. diff --git a/.agents/skills/specification/SKILL.md b/.agents/skills/specification/SKILL.md new file mode 100644 index 00000000..87bc2042 --- /dev/null +++ b/.agents/skills/specification/SKILL.md @@ -0,0 +1,58 @@ +--- +name: specification +description: Generate an SDD (Spec Driven Development) document for a new feature in the pickup-points-modal, covering Business Context, Architectural Decisions, and Technical Contract before any code is written. +type: skill +--- + +# specification + +Use esta skill quando o usuário pedir para "criar uma spec", "escrever um SDD", +ou referenciar um arquivo em `specs/`. O entregável é um arquivo +`specs//spec.md` com três seções obrigatórias. + +## Quando usar + +- Feature nova que toca o contrato público do `PickupPointsModal`. +- Mudança de arquitetura (novo container, novo fluxo de estado). +- Refactor com impacto cross-cutting (i18n, fetchers, mapa). + +**Não use** para bug fix pontual ou tweak de estilo — vai direto para +`implementing` ou `speckit-git-commit`. + +## Estrutura do entregável + +```markdown +# Spec: + +## Business Context +- Problema que estamos resolvendo +- Stakeholders (quem pediu, quem é impactado) +- Métricas de sucesso + +## Architectural Decisions +- Componentes/arquivos afetados +- Alternativas consideradas + por que foram descartadas +- Riscos de backward-compatibility (referenciar Principle 1 da constitution) + +## Technical Contract +- Mudanças em props/eventos +- Mudanças em fixtures/mocks +- Plano de testes (golden path + edge cases) +- Plano de i18n (chaves novas, locales tocados) +- Critérios de aceite verificáveis +``` + +## Inputs esperados + +- Descrição em linguagem natural da feature. +- Link para ticket Jira/issue se existir. +- Lista de arquivos suspeitos (se o usuário já investigou). + +## Como aplicar + +1. Ler [.specify/memory/constitution.md](../../../.specify/memory/constitution.md) + para entender princípios vinculantes. +2. Ler [AGENTS.md](../../../AGENTS.md) para limites de autonomia. +3. Esboçar as 3 seções com `TBD` onde faltar input. +4. Apresentar para o usuário antes de criar o arquivo final. +5. Não implementar nada — apenas spec. diff --git a/.agents/skills/speckit-analyze/SKILL.md b/.agents/skills/speckit-analyze/SKILL.md new file mode 100644 index 00000000..0758e12d --- /dev/null +++ b/.agents/skills/speckit-analyze/SKILL.md @@ -0,0 +1,42 @@ +--- +name: speckit-analyze +description: Audit consistency between spec.md, plan.md, tasks.md, and the actual code in the pickup-points-modal — flagging drift, missing tasks, or out-of-spec changes before PR review. +type: skill +--- + +# speckit-analyze + +Auditoria leve antes de abrir o PR. Detecta drift entre os 4 artefatos: +spec → plan → tasks → código. + +## Quando usar + +- Depois de `speckit-implement` e antes do `gh pr create`. +- Quando o autor da spec é diferente do implementador. +- Antes de pedir review humano em feature grande. + +## Checks + +1. **Spec → Plan:** todo critério de aceite da spec aparece como + item no plano? +2. **Plan → Tasks:** todo arquivo listado em "Files to touch" tem ao + menos uma task? +3. **Tasks → Code:** todo arquivo modificado em `git diff` está em + alguma task? +4. **Constitution check:** o diff respeita os 5 princípios? + +## Output + +Relatório em markdown listando: + +- ✅ Items alinhados +- ⚠️ Drift (mudou no código mas não na task / spec) +- ❌ Faltando (criterio de aceite sem implementação) + +Não corrige nada — só reporta. O usuário decide se atualiza spec/plan +ou se reverte o código. + +## Importante + +`speckit-analyze` é **read-only**. Nunca edita spec, plan, tasks ou +código. Se encontrar drift, retorna o relatório e para. diff --git a/.agents/skills/speckit-checklist/SKILL.md b/.agents/skills/speckit-checklist/SKILL.md new file mode 100644 index 00000000..d91de74a --- /dev/null +++ b/.agents/skills/speckit-checklist/SKILL.md @@ -0,0 +1,52 @@ +--- +name: speckit-checklist +description: Generate a per-feature validation checklist (pre-merge gates, manual QA steps, rollback plan) for a pickup-points-modal feature, tailored to the spec and constitution principles. +type: skill +--- + +# speckit-checklist + +Gera um checklist de validação para colocar no PR description ou em +`specs//checklist.md`. Não é genérico — é derivado da spec e dos +princípios da constituição. + +## Quando usar + +- Antes de pedir review humano. +- Em features que tocam checkout-critical paths. + +## Estrutura + +```markdown +# Checklist — + +## Pre-merge gates +- [ ] `yarn lint` passa +- [ ] `yarn lint:ts` passa +- [ ] `yarn test` passa +- [ ] `yarn lint:locales` passa (se mexeu em i18n) +- [ ] `yarn build` passa +- [ ] CHANGELOG atualizado se mudança visível + +## Constitution checks +- [ ] Princípio 1: contrato público preservado ou major bump +- [ ] Princípio 2: testes cobrem golden path + edge case +- [ ] Princípio 3: chaves novas em todos os locales +- [ ] Princípio 4: sem regressão de bundle/TTI +- [ ] Princípio 5: utils novos são puros + +## Manual QA +- [ ] Cenário testado no demo (`yarn start`) +- [ ] Funciona com `searchAddress` vazio +- [ ] Funciona com 0 pickup points retornados +- [ ] Funciona em locale `pt-BR` e `en-US` + +## Rollback plan +- Branch revertível? +- Migração de dados? +- Feature flag? +``` + +## Template + +Veja [.specify/templates/checklist-template.md](../../../.specify/templates/checklist-template.md). diff --git a/.agents/skills/speckit-clarify/SKILL.md b/.agents/skills/speckit-clarify/SKILL.md new file mode 100644 index 00000000..e7a5c8df --- /dev/null +++ b/.agents/skills/speckit-clarify/SKILL.md @@ -0,0 +1,41 @@ +--- +name: speckit-clarify +description: Interactively clarify ambiguous requirements in a spec.md before planning — generates targeted questions for the requester to resolve TBDs in the pickup-points-modal feature spec. +type: skill +--- + +# speckit-clarify + +Gera perguntas focadas para destravar uma spec com TBDs ou ambiguidades. +Roda entre `speckit-specify` e `speckit-plan`. + +## Quando usar + +- `spec.md` tem 2+ `TBD` em campos obrigatórios. +- Critério de aceite vago ("deve funcionar bem"). +- Stakeholder não foi explícito em edge cases. + +## Fluxo + +1. Ler `specs//spec.md`. +2. Identificar lacunas em: + - Business Context (quem, por quê, métrica) + - Architectural Decisions (alternativas, riscos) + - Technical Contract (props, fixtures, i18n, aceite) +3. Gerar **no máximo 5 perguntas** por iteração, em ordem de impacto. +4. Aguardar respostas do usuário. +5. Atualizar `spec.md` com as respostas — preservar o histórico em + `## Clarifications` no fim do arquivo. + +## Perguntas boas + +- Específicas: "O modal deve fechar ao escolher um pickup? Antes ou + depois do confirm?" +- Acionáveis: a resposta muda o plan. +- Únicas: não repete o que já está respondido na spec. + +## Perguntas ruins + +- "Tem mais alguma coisa?" +- "O que você acha?" +- Perguntas que o agente pode responder lendo o código. diff --git a/.agents/skills/speckit-constitution/SKILL.md b/.agents/skills/speckit-constitution/SKILL.md new file mode 100644 index 00000000..6eb9b884 --- /dev/null +++ b/.agents/skills/speckit-constitution/SKILL.md @@ -0,0 +1,50 @@ +--- +name: speckit-constitution +description: Create or amend the project constitution in .specify/memory/constitution.md, capturing binding principles, governance, and ratification metadata for the pickup-points-modal. +type: skill +--- + +# speckit-constitution + +Use para criar ou editar `.specify/memory/constitution.md`. Esse arquivo é a +**fonte de verdade vinculante** — sobrescreve qualquer outro doc em caso +de conflito. + +## Quando usar + +- Primeira vez criando a constituição. +- Adicionando um novo princípio (minor bump). +- Revogando ou reescrevendo um princípio (major bump). +- Atualizando regras de governança. + +## Estrutura obrigatória + +```markdown +# — Project Constitution + +**Version** X.Y.Z | **Ratified** YYYY-MM-DD | **Last Amended** YYYY-MM-DD + +## Principles +### 1. +- Why: ... +- How to apply: ... + +## Governance +- Quem ratifica +- Como propor mudança +- Versionamento (SemVer) +- Auditoria +``` + +## Regras + +- **Sem placeholders.** Nada de `[PROJECT_NAME]`, `[PRINCIPLE_1_NAME]` etc. + no arquivo final. +- **Version sempre presente.** O grep do review (item 9) procura por + `**Version** ... **Ratified**`. +- **Princípios concretos.** Cada um tem `Why` e `How to apply` reais — + bullets vazios falham o item 1b por extensão. + +## Template + +Veja [.specify/templates/constitution-template.md](../../../.specify/templates/constitution-template.md). diff --git a/.agents/skills/speckit-git-commit/SKILL.md b/.agents/skills/speckit-git-commit/SKILL.md new file mode 100644 index 00000000..d9e963bc --- /dev/null +++ b/.agents/skills/speckit-git-commit/SKILL.md @@ -0,0 +1,61 @@ +--- +name: speckit-git-commit +description: Compose Conventional Commits messages and stage the right files for a pickup-points-modal change, respecting CHANGELOG and the constitution's backward-compat principle. +type: skill +--- + +# speckit-git-commit + +Compor commit messages no padrão Conventional Commits do repo. + +## Formato + +``` +(): + + + +