--- name: constitution description: 'Create/update immutable project governance principles. Triggers: "constitution", "criar constituicao", "principios do projeto", "governance". For point-in-time technical decisions, use ADRs instead.' argument-hint: "[descricao do projeto ou principios desejados]" allowed-tools: - Read - Write - Edit - Glob - Grep --- # Skill: Constituicao do Projeto Crie ou atualize a constituicao do projeto — o documento de principios imutaveis que governa decisoes de arquitetura, qualidade e processo. ## Pre-requisitos **Recomendado**: `/briefing` executado antes. A constituicao deriva principios do contexto do projeto (visao, prioridades, restricoes) — sem briefing, os principios ficam genericos. **Opcional**: `docs/constitution.md` existente (para atualizar em vez de criar do zero). A skill versiona via SemVer (MAJOR/MINOR/PATCH). ## Proximos passos 1. `/specify` — especificar features alinhadas aos principios 2. `/plan` — planos tecnicos vao respeitar a constitution (Constitution Check como gate) 3. `/analyze` — apos ter specs/plans/tasks, validar alinhamento contra a constitution ## Argumentos $ARGUMENTS --- ## FLUXO DE EXECUCAO ``` 1. CONTEXTO Detectar projeto e constituicao existente | 2. COLETA Coletar/derivar principios | 3. GERACAO Preencher template com valores concretos | 4. PROPAGACAO Verificar alinhamento com outros artefatos | 5. SALVAMENTO Salvar e reportar ``` --- ## ETAPA 1: CONTEXTO ### 1.1 Detectar Projeto Leia os seguintes arquivos (se existirem) para entender o contexto: ``` SEMPRE LER (se existirem): -- README.md -- CLAUDE.md -- docs/constitution.md (constituicao existente) -- docs/specs/*/spec.md (specs existentes) -- package.json, go.mod, pyproject.toml (stack tecnica) ``` ### 1.2 Verificar Constituicao Existente Procure constituicao existente nesta ordem: 1. `docs/constitution.md` 2. `constitution.md` Se encontrada: - Carregar conteudo atual - Identificar placeholders `[ALL_CAPS_IDENTIFIER]` nao preenchidos - Propor atualizacoes baseadas no input do usuario Se nao encontrada: - Seguir para coleta de principios (Etapa 2) --- ## ETAPA 2: COLETA DE PRINCIPIOS ### 2.1 Fontes de Principios Analise o argumento fornecido ($ARGUMENTS). Ele pode ser: 1. **Descricao do projeto**: Inferir principios a partir do contexto 2. **Lista de principios**: Usar diretamente 3. **Numero de principios**: Respeitar a quantidade solicitada 4. **Vazio**: Inferir do contexto do projeto e perguntar ao usuario ### 2.2 Derivar Valores Para cada placeholder no template: - Se o usuario forneceu valor: usar diretamente - Se inferivel do contexto (README, docs, stack): derivar e documentar a inferencia - Se desconhecido: marcar como `TODO(): explicacao` e incluir no relatorio ### 2.3 Datas e Versionamento - `RATIFICATION_DATE`: data original de adocao (se desconhecida, perguntar ou marcar TODO) - `LAST_AMENDED_DATE`: data de hoje se mudancas foram feitas - `CONSTITUTION_VERSION`: incrementar seguindo versionamento semantico: - **MAJOR**: Remocao ou redefinicao incompativel de principios - **MINOR**: Novo principio ou expansao material de secao - **PATCH**: Clarificacoes, correcoes de texto, refinamentos nao-semanticos - Se tipo de bump ambiguo: propor raciocinio ao usuario antes de finalizar --- ## ETAPA 3: GERACAO ### 3.1 Template da Constituicao Usar `templates/constitution.md` (mesmo diretorio desta skill) e substituir TODOS os placeholders `[ALL_CAPS]` por texto concreto. Estrutura: - **Core Principles** — 3-5 principios declarativos e testaveis - Secoes opcionais conforme o projeto (ex: Quality Standards, Architecture Decisions) - **Governance** — regras de amendment, versioning, exception handling - Rodape com **Version / Ratified / Last Amended** ### 3.2 Regras de Preenchimento - O usuario pode pedir mais ou menos principios que o template — ajustar conforme necessario - Cada principio deve ser: **declarativo, testavel e livre de linguagem vaga** - Trocar "should" por MUST/SHOULD com rationale quando apropriado - Remover comentarios HTML do template ao preencher - Manter hierarquia de headings exatamente como no template - Nao deixar nenhum placeholder `[...]` sem justificativa explicita - **Formato de obrigacao (gate `converge` depende disto — issue #173):** toda obrigacao de principio (MUST/MUST NOT) se escreve como **linha rotulada iniciando a linha**, nunca como MUST em prosa corrida nem sob prefixo de blockquote (`> `). Formas reconhecidas pelo parser do gate (`extract-must.sh`, regex `_EM_MUST_RE`): ``` **MUST:** RECONHECIDA **MUST NOT:** RECONHECIDA - MUST: RECONHECIDA * MUST NOT: RECONHECIDA **MUST:** RECONHECIDA (indentacao ok) > **MUST:** NAO reconhecida (prefixo de blockquote quebra o rotulo — medido) ``` Um principio cujas obrigacoes so aparecem como "o time MUST fazer X" em prosa corrida, ou dentro de um blockquote, e **invisivel** ao gate `converge` (`extract-must.sh --coverage` reporta `cobertura de MUST: zero-reconhecida` e o achado correspondente entra como `HIGH` na proxima execucao de `converge`) — mesmo que a intencao normativa esteja clara para um leitor humano. **Principio-base obrigatorio (sempre incluir):** toda constituicao gerada DEVE conter um principio NON-NEGOTIABLE de **Veracidade de Dados — Zero Fabricacao**, mesmo que o usuario nao peca. Texto-semente (adaptar ao dominio do projeto) — **bloco de codigo cercado, nunca blockquote** (o prefixo `> ` quebra o reconhecimento do gate `converge` se transcrito verbatim — medido), com a linha `**MUST:**` abrindo as obrigacoes: ``` ### Veracidade de Dados — Zero Fabricacao (NON-NEGOTIABLE) **MUST:** - Nenhum artefato pode conter dado factual inventado. Assinaturas de request/response, URLs/endpoints/querystrings e valores concretos (financeiros, quantidades, status, IDs, datas, resultados de API) so podem ser escritos se vierem de fonte rastreavel (codigo, OpenAPI/Swagger, doc oficial, resposta real observada). Esgotadas as fontes, a acao correta e **bloqueio humano**, nunca suposicao plausivel. Plausibilidade nao e veracidade. ``` Razao: agentes autonomos confabulam dados de sistemas externos sob pressao de entrega; o principio impresso na constituicao do projeto e o que sustenta o bloqueio em vez da invencao. Espelha o Principio VI da constituicao deste toolkit. A linha `**MUST:**` garante `M >= 1` para este principio (nenhuma obrigacao foi adicionada, removida ou enfraquecida — so a marcacao mudou de blockquote para bloco de codigo cercado). --- ## ETAPA 4: PROPAGACAO ### 4.1 Checklist de Consistencia Apos gerar a constituicao, verificar alinhamento com outros artefatos: - [ ] `CLAUDE.md`: Principios refletidos nas instrucoes do projeto? - [ ] `docs/specs/*/plan.md`: Plans existentes referenciam principios? - [ ] `docs/specs/*/tasks.md`: Tasks refletem quality gates da constituicao? ### 4.2 Sync Impact Report Gerar relatorio de impacto (como comentario HTML no topo do arquivo): ```markdown ``` --- ## ETAPA 5: SALVAMENTO ### 5.1 Validacao Final Antes de salvar: - [ ] Nenhum placeholder `[...]` sem justificativa - [ ] Versao consistente com relatorio de impacto - [ ] Datas em formato ISO YYYY-MM-DD - [ ] Principios sao declarativos e testaveis - [ ] Sem trailing whitespace ### 5.2 Salvar Salvar em `docs/constitution.md` (ou caminho especificado pelo usuario). ### 5.3 Relatorio Apresentar ao usuario: - Nova versao e rationale do bump - Principios criados/modificados - Artefatos que precisam atualizacao manual - Sugestao de commit message (ex: `docs: create project constitution v1.0.0`) --- ## EXEMPLOS DE PRINCIPIOS Os exemplos abaixo ilustram formato — adaptar ao dominio do projeto, nao copiar literalmente. **Principios de arquitetura:** - Library-First: Features comecam como bibliotecas standalone - Modularidade: Servicos comunicam via contratos, nao memoria compartilhada - Simplicity: YAGNI — nao abstrair prematuramente **Principios de qualidade:** - Test-First (NON-NEGOTIABLE): TDD obrigatorio, Red-Green-Refactor - Integration Testing: Testes contra sistema real, nao mocks - Observability: Logging estruturado obrigatorio em todas as operacoes criticas **Principios de UX/acessibilidade:** - Component-First: UI construida de componentes reutilizaveis - Accessibility: WCAG 2.1 AA como minimo - Progressive Enhancement: Funcionalidade core funciona sem JS **Principios de seguranca/compliance:** - Security: OWASP Top 10 como baseline - Deny by Default: Permissoes explicitas em vez de implicitas - Data Minimization: Coletar/persistir so o necessario **Principios de processo:** - Documentation: Codigo auto-documentado, comentarios para o "por que" - Reviewable Changes: PRs pequenos e focados, nao merges gigantes --- ## Gotchas ### Principios devem ser declarativos, testaveis e livres de linguagem vaga "Sistema deve ser robusto" nao e principio, e aspiracao. Trocar por MUST/SHOULD com rationale: "MUST: toda operacao de escrita em banco deve ser idempotente (Why: retry sem corrupcao de estado)". ### Versao segue SemVer — e o bump deve ser justificado - MAJOR: remove ou redefine principio de forma incompativel - MINOR: adiciona principio ou expande secao materialmente - PATCH: clarifica texto sem mudar semantica Se o bump e ambiguo, propor rationale ao usuario antes de finalizar — datas e versao sao auditadas. ### Placeholders `[ALL_CAPS]` nao sobrevivem no documento final Todo placeholder no template tem que ser preenchido com conteudo concreto ou marcado como `TODO(): explicacao`. Placeholders nao-resolvidos em produto final e indicador de constituicao incompleta. ### Principios conflitantes invalidam a constituicao Se "Moving Fast" e "Zero Bugs" coexistem como principios MUST, o projeto nao tem governanca — tem contradicao. Detectar conflitos antes de salvar e pedir ao usuario para resolver a tensao (tipicamente promovendo um a MUST e rebaixando outro a SHOULD com trade-off documentado). ### Sync Impact Report e obrigatorio em atualizacoes Bumps MAJOR/MINOR precisam listar quais artefatos (CLAUDE.md, plans, tasks) precisam atualizacao. Sem isso, a constituicao desinterna-se dos outros documentos silenciosamente. ### Blockquote quebra o reconhecimento de MUST pelo gate `converge` (medido) `> **MUST:**` (prefixo de blockquote) **nao** e reconhecido pelo parser de `extract-must.sh` (`_EM_MUST_RE`) — so a forma sem `> ` conta como linha de regra. Isso ja causou regressao real: o texto-semente de Veracidade de Dados desta propria skill viveu em blockquote por um tempo, e uma constituicao gerada a partir dele nascia com `cobertura de MUST: zero-reconhecida` (cobertura zero) mesmo tendo a intencao normativa clara para um leitor humano. Ao escrever ou revisar QUALQUER bloco de obrigacao nesta skill (o principio-base, exemplos de §5, o proprio template), nunca reintroduza o prefixo `> ` num bloco que contem `**MUST:**`/`- MUST:` — use bloco de codigo cercado (` ``` `) ou paragrafo solto. Ver §3.2 "Formato de obrigacao".