🦖 Raptor

Spec-Driven Development para apps React Native — com governança, rastreabilidade e verificação reais

Raptor transforma uma ideia em linguagem natural numa especificação rica e sem pontas soltas e conduz, fase a fase, até o código verificado — sempre com um humano no comando das aprovações. Ele não escreve a spec nem o código sozinho: ele orquestra o ciclo, aplica gates que bloqueiam transições incompletas, mantém uma trilha de auditoria e materializa slash commands para o seu agente de IA (Claude Code, Cursor, Copilot, Codex, Gemini, Antigravity) executar.

O diferencial é a ponta de verificação: o Raptor mede a realidade do app (acessibilidade, performance, permissões de loja, versões mínimas de SO) e compara com o que a spec prometeu.

npm install -g raptor-aios
cd meu-app-react-native
raptor setup        # 🧭 assistente guiado: IA/IDE, preset, Jira/Figma (ou 'raptor init' direto)
raptor new login-biometrico -d "Permitir login com Face ID / digital"
#  → cria a feature E já troca para a branch feat/001-login-biometrico

📑 Índice

• 🤔 O que é Spec-Driven Development
• ⚡ Instalação
• 🚀 Primeiros passos (5 minutos)
• 🔄 O ciclo SDD
• 🌿 Branch & commit automáticos
• 💬 Os slash commands explicados
• 📱 Fluxo correto com React Native
• 🛡️ Gates: o que bloqueia o quê
• 🔬 A ponta de verificação (verify)
• 🧰 Capacidades do Raptor
• 📖 Referência de comandos CLI
• 🗂️ Estrutura criada no projeto
• 📚 Documentação & glossário
• 🛠️ Desenvolvimento local
• ⚖️ Governança & contribuição

🤔 O que é Spec-Driven Development

No fluxo tradicional, o código vem primeiro e a documentação (quando existe) vem depois. O Spec-Driven Development (SDD) inverte isso: a especificação é o artefato central e tudo flui a partir dela — plano técnico, tarefas, código e testes. A spec deixa de ser papel descartável e vira o contrato que o agente de IA executa.

O Raptor leva o SDD a sério para o mundo mobile, adicionando o que falta para uso em equipe:

| Pilar | O que entrega | | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 🧭 Governança como código | Uma constituição com artigos imutáveis (RAPTOR-CORE) e um preset opinativo para mobile (M1–M6). Nada de plan/tasks/implement sem aprovação humana registrada. | | 📜 Trilha de auditoria | Cada passo emite eventos em audit.jsonl, validáveis contra um JSON Schema canônico. | | 🔗 Rastreabilidade código↔spec (M7) | Cada artefato de código aponta para os critérios de aceitação que satisfaz, com evidência pareada (code + test). | | 🔬 Verificação real | verify a11y/perf/stores/os-matrix medem o app de verdade e comparam com o que a spec/plan declararam. | | 🤖 Agnóstico de agente | Materializa slash commands para Claude Code, Cursor, Copilot, Codex, Gemini e Antigravity. | | ✨ Specs sem pontas soltas | A spec nasce preenchida (defaults informados), com teto de 3 dúvidas de alto impacto, e um /raptor-clarify investigativo que caça lacunas antes do planejamento. | | 🌿 Branch & commit sob controle | Cada feature ganha sua branch (feat/001-…) automaticamente, e hooks warn-only alertam sobre arquivos sensíveis ou fora do contexto — sem travar seu fluxo git. | | 💬 Erros que ensinam | Comando errado vira sugestão (did you mean), e argumentos/flags faltando mostram uso + exemplo concreto + flags — em vez de um dump genérico. |

⚡ Instalação

Requer Node.js ≥ 20.

# Instalação global (recomendado)
npm install -g raptor-aios

# …ou sem instalar nada:
npx raptor-aios init

O binário instalado chama-se raptor:

raptor --version
raptor doctor      # 🩺 checagem de saúde do ambiente e do projeto

🚀 Primeiros passos (5 minutos)

💡 Rode estes comandos dentro da pasta do seu projeto React Native.

1️⃣ Inicialize o Raptor

A forma guiada — um assistente interativo (navegação por setas) que apresenta o Raptor e coleta IA/IDE, preset e integrações Jira/Figma:

raptor setup

Ou, direto e não-interativo (ideal para CI/scripts):

raptor init --ai=claude-code --preset=mobile-opinionated

Qualquer um cria a pasta .raptor/, a constituição do projeto, e materializa os slash commands em .claude/commands/ (ou .cursor/, etc., conforme o agente).

| Flag | Para que serve | | ----------------------------- | ------------------------------------------------------------------------------------------------------------ | | --ai=<agente> | Qual agente receberá os slash commands: claude-code, cursor, copilot, codex, gemini, antigravity | | --preset=mobile-opinionated | Ativa os gates de qualidade mobile (M1–M6) | | --with-ci | Gera um workflow de CI em .github/workflows/ | | --no-git | Não inicializa/usa git (para sandboxes) |

2️⃣ Crie sua primeira feature

raptor new home-screen -d "Tela inicial com status de disponibilidade e mapa"

A flag -d/--desc captura sua descrição em linguagem natural — a spec já nasce preenchida com Summary, user stories, requisitos e critérios de aceitação, em vez de um esqueleto vazio.

3️⃣ Refine a spec com seu agente

No seu agente de IA, digite:

/raptor-specify Tela inicial: mostra se o entregador está disponível,
um mapa com a posição atual e um botão de "ficar online".

O agente preenche o template canônico, adota defaults sensatos e marca no máximo 3 dúvidas de alto impacto. Resolva-as com:

/raptor-clarify

4️⃣ Aprove → planeje → tarefas → implemente → verifique

raptor approve home-screen --artifact spec
raptor plan home-screen        # roda os gates Phase -1 (C1–C5 + M1–M6)
raptor approve home-screen --artifact plan --phase-minus-one passed
raptor tasks home-screen
raptor approve home-screen --artifact tasks
raptor implement home-screen --task T001 --files src/Home.tsx --acceptance AC-1 --kind code
raptor verify home-screen      # ✅ todos os gates

🔄 O ciclo SDD

O Raptor implementa 9 fases, cada uma com um slash command rico (executado pelo agente) e, quando aplicável, um comando de CLI que registra a auditoria e roda os gates.

flowchart LR
    A([🧭 constitution]) --> B([📝 specify])
    B --> C([❓ clarify])
    C --> D([🏗️ plan])
    D --> E([✅ tasks])
    E --> F([🔍 analyze])
    F --> G([📋 checklist])
    G --> H([⚙️ implement])
    H --> I([🔬 verify])
    I --> J([🎫 taskstoissues])

    classDef spec fill:#fee2e2,stroke:#ef4444,color:#7f1d1d;
    classDef build fill:#dbeafe,stroke:#3b82f6,color:#1e3a8a;
    classDef check fill:#dcfce7,stroke:#22c55e,color:#14532d;
    class A,B,C spec;
    class D,E,H build;
    class F,G,I,J check;

| # | Fase | Comando CLI | Slash command | O que produz | | --- | -------------- | ---------------------- | ----------------------- | ---------------------------------------------------- | | 1 | 🧭 Constituição | (gerada no init) | /raptor-constitution | Princípios imutáveis do projeto | | 2 | 📝 Especificar | raptor new | /raptor-specify | spec.md (problema, user stories, FRs, AC) | | 3 | ❓ Clarificar | raptor clarify | /raptor-clarify | Resolve dúvidas de alto impacto | | 4 | 🏗️ Planejar | raptor plan | /raptor-plan | plan.md + artefatos de design + Phase -1 gates | | 5 | ✅ Tarefas | raptor tasks | /raptor-tasks | tasks.md decompondo o plano | | 6 | 🔍 Analisar | raptor analyze | /raptor-analyze | Relatório de drift, cobertura e órfãos | | 7 | 📋 Checklist | raptor checklist | /raptor-checklist | Checklists temáticos (a11y, segurança…) | | 8 | ⚙️ Implementar | raptor implement | /raptor-implement | Código + evidência rastreável (M7) | | 9 | 🎫 Issues | raptor taskstoissues | /raptor-taskstoissues | Exporta tarefas para um tracker |

Cada transição passa por gates e dispara hooks. Aprovações exigem um humano identificável (via git config user.email).

🌿 Branch & commit automáticos

Isolamento e coerência sem configurar nada — o init já deixa tudo pronto.

Uma branch por unidade de trabalho

raptor new cria e troca para a branch certa, sempre ramificando de main:

| Você roda | Branch criada | | -------------------------------------- | --------------------------------------------------- | | raptor new home-screen | feat/001-home-screen | | raptor new login-error --kind=bugfix | bugfix/002-login-error | | raptor new refactor-auth --kind=debt | debt/003-refactor-auth | | raptor new login --jira APP-1234 | feat/004-login.app-1234 (tipo inferido do Jira) |

Numeração sequencial global, prefixo por tipo (feat/bugfix/debt), e a chave do Jira no fim quando houver. Já vem ligado (git.branch_per_feature); desligue com --no-branch num comando ou no_git no projeto.

Commits coerentes, sem travar seu fluxo

O init instala git hooks que apenas avisam (nunca bloqueiam) ao commitar e ao pushar:

• ⚠️ Arquivos sensíveis staged — migrations/DB, .env, segredos, lockfiles, CI.
• ⚠️ Arquivos fora do contexto da feature ativa — comparados ao que ela já tocou.
• ⚠️ Mensagem fora da convenção — tipo conventional, alinhamento com o kind da branch, autoria de IA.

raptor commit -m "feat: tela home"   # confere os sensíveis e commita (com trailers de rastreio)
raptor scan                          # checagem avulsa do que está staged (warn-only, sai 0)

Para a análise semântica ("essa mudança realmente serve à feature?"), rode /raptor-commit-review no seu agente — ele lê a spec + o diff e aconselha. Tudo é advisory: o Raptor mostra, você decide.

📌 Convenção de commit: Conventional Commits, mensagens em pt-BR, autoria sempre do humano que aprova (nunca de IA). Detalhes em CONTRIBUTING.md.

💬 Os slash commands explicados

Você os executa dentro do seu agente de IA. São prompts versionados e ricos: cada um sabe ler os artefatos certos, rodar scripts e parar para sua revisão.

🧭 /raptor-constitution

Cria ou atualiza os princípios do projeto (.raptor/memory/constitution.md). É o "contrato social" que todas as fases seguintes respeitam. Use no início, ou quando quiser ratificar uma mudança de regra (com bump de versão).

📝 /raptor-specify

Transforma sua descrição em linguagem natural numa spec estruturada. Adota defaults informados (retenção de dados, performance, acessibilidade…) em vez de perguntar tudo, registra cada suposição em Assumptions, e mantém no máximo 3 [NEEDS CLARIFICATION] de alto impacto. Faz auto-validação contra um checklist embutido antes de te entregar.

/raptor-specify Login com biometria; cair para senha quando indisponível.

❓ /raptor-clarify

Investigativo, não um varredor de marcadores. Faz um coverage map de 9 categorias (escopo, dados, UX, requisitos não-funcionais, integrações, edge cases, restrições, terminologia, sinais de conclusão), elege as ≤5 perguntas de maior impacto, e as apresenta com recomendação (opções A/B/C + "recomendado"). Integra cada resposta na seção certa e re-valida o checklist (9/13 → 13/13).

🏗️ /raptor-plan

Traduz a spec em decisões técnicas: stack, arquitetura, modelo de dados, contratos e quickstart. Roda o Constitution Check (antes e depois do design) e os Phase -1 gates. Não inventa onde a spec tem dúvidas em aberto.

✅ /raptor-tasks

Decompõe o plano em um checklist executável (T001, T002…), agrupado por user story e em ordem de dependência. Marca tarefas paralelizáveis com [P] e liga cada uma a uma user story [US#].

🔍 /raptor-analyze

Auditoria cruzada spec ↔ plan ↔ tasks: cada user story tem decisão no plano? cada decisão tem tarefa? há órfãos? Gera uma matriz de rastreabilidade com erros/avisos.

📋 /raptor-checklist

Gera checklists de qualidade temáticos (code quality, testes, segurança, performance, documentação, acessibilidade, mobile, observabilidade) antes de liberar a implementação.

⚙️ /raptor-implement

Executa as tarefas em ordem de fase, respeitando paralelização e (se exigido) TDD. Marca cada tarefa [x] ao concluir e registra a evidência M7 (qual arquivo cobre qual critério de aceitação).

🎫 /raptor-taskstoissues

Converte as tarefas em issues de um tracker (GitHub via MCP, Jira via integração).

🌿 /raptor-commit-review

Revisão semântica das mudanças pendentes antes de commitar: lê o spec.md da feature + o diff e julga se cada arquivo realmente serve à demanda — o que regex não pega. Sinaliza o que parece fora de escopo ou sensível e só aconselha (não commita nada).

📱 Fluxo correto com React Native

O Raptor foi desenhado para o ciclo real de quem constrói apps React Native (CLI bare, não-Expo) — do design ao device.

sequenceDiagram
    actor Dev as 👤 Você
    participant AI as 🤖 Agente
    participant R as 🦖 Raptor
    participant App as 📱 Emulador/Device

    Dev->>R: raptor new home -d "..."
    Dev->>AI: /raptor-specify (descreve a tela)
    AI->>R: escreve spec.md (stores + a11y)
    Dev->>AI: /raptor-clarify (resolve dúvidas)
    Dev->>R: raptor approve --artifact spec
    Dev->>AI: /raptor-plan (tokens do Figma → decisões)
    Dev->>R: raptor plan + approve (Phase -1)
    Dev->>AI: /raptor-tasks
    Dev->>AI: /raptor-implement (escreve .tsx + testes)
    AI->>R: raptor implement (registra evidência M7)
    Dev->>App: roda o app (Metro + adb)
    Dev->>R: raptor verify a11y / perf / stores
    R->>App: mede a realidade (adb am start -W, manifests)
    R-->>Dev: ✅ bate com a spec / ⚠️ diverge

Passo a passo a partir de um design Figma

# 0. Pré-requisitos do device (uma vez por sessão)
adb reverse tcp:8081 tcp:8081     # Metro acessível ao app
npx react-native run-android      # ou run-ios

# 1. Spec — user stories, FRs, AC + frontmatter stores/a11y (M1/M3)
raptor new home-disponivel -d "Tela home com status, mapa e botão de ficar online"
#  → /raptor-specify e /raptor-clarify no agente
raptor approve home-disponivel --artifact spec

# 2. Plan — tokens do Figma, decisões, frontmatter privacy/os_matrix/perf_budget (M2/M4/M5/M6)
raptor plan home-disponivel
raptor approve home-disponivel --artifact plan --phase-minus-one passed
raptor verify home-disponivel                    # 24 pass / 0 fail

# 3. Tasks — T001..T0nn com tags [US#] [AC-#]
raptor tasks home-disponivel
raptor approve home-disponivel --artifact tasks
raptor analyze home-disponivel                   # 0 findings

# 4. Implement — cada task registra evidência (M7)
raptor implement home-disponivel --task T004 --files src/components/Header.tsx --acceptance AC-1,AC-2 --kind code
raptor implement home-disponivel --task T004 --files __tests__/Header.test.tsx --acceptance AC-1,AC-2 --kind test --amend

# 5. Verificação real (mede o app no device)
raptor verify a11y home-disponivel               # scan WCAG AA do JSX
raptor verify stores home-disponivel --fix       # permissões nativas vs spec
raptor verify os-matrix home-disponivel          # versões mínimas vs Gradle/Podfile
raptor verify perf home-disponivel               # TTFI real via adb

💡 Dica RN: verify perf faz cold-start real com adb am start -W — precisa do Metro acessível (adb reverse tcp:8081 tcp:8081). verify stores --fix adiciona permissões faltantes ao AndroidManifest.xml/Info.plist.

🛡️ Gates: o que bloqueia o quê

Gates são checagens versionadas com um nível: 🔴 critical (bloqueia, imutável), 🟡 required (bloqueia, do preset) ou 🔵 advisory (só avisa).

🔴 C1–C5 — RAPTOR-CORE (críticos, imutáveis)

| Artigo | Gate | Valida | | ------ | ----------------------------- | ------------------------------------------------------------------- | | C1 | gate.spec.exists | A feature tem spec.md aprovada que governa o plano | | C2 | gate.audit.complete | audit.jsonl existe e está bem-formado | | C3 | gate.plan.approved | Plano aprovado + phase_minus_one: passed antes de tasks/implement | | C4 | gate.constitution.integrity | O bloco RAPTOR-CORE não foi adulterado (hash) | | C5 | (no approve) | Aprovação de criticals exige humano identificável |

✨ Prontidão da spec (novo)

| Gate | Nível | Valida | | -------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------- | | gate.spec.clarifications | 🟡 required | Não há [NEEDS CLARIFICATION] não resolvidos | | gate.spec.ready | 🟡 required | Spec coesa: toda user story tem AC, AC espelhado no frontmatter, Success Criteria mensuráveis, sem [PREENCHER] |

📱 M1–M6 — preset mobile-opinionated

Cada gate exige campos no frontmatter de spec.md ou plan.md — declarativos, verificáveis e (para alguns) mensuráveis via verify.

| Gate | Nível | Exige no frontmatter | Verificável por | | --------------------------------------------- | ----- | --------------------------------------------------------------------------------------------------------------------- | ------------------ | | M1 — App/Play Store Compliance | 🟡 | spec.stores.ios_permissions, .android_permissions (ou stores.no_restricted_apis: "<motivo>" p/ opt-out honesto) | verify stores | | M2 — Privacidade & Residência (LGPD/GDPR) | 🟡 | plan.privacy.lawful_basis, .residency, .retention | — | | M3 — Acessibilidade (WCAG AA) | 🟡 | spec.a11y.wcag_level, .criteria | verify a11y | | M4 — Matriz de SO | 🟡 | plan.os_matrix.ios_min, .android_min | verify os-matrix | | M5 — Orçamento de Performance | 🟡 | plan.perf_budget.ttfi_ms, .interactions_ms | verify perf | | M6 — Crash-Free SLO & Observabilidade | 🔵 | plan.crash_free_slo (≥99.5), plan.observability.provider | — |

🔗 M7 — Rastreabilidade código↔spec

| Gate | Nível | Valida | | --------------------------------- | ----- | ------------------------------------------------------------------- | | gate.m7.code_traces_acceptance | 🔴 | Todo artefato em impl-log.md aponta para ≥1 critério de aceitação | | gate.m7.acceptance_has_coverage | 🟡 | Todo [AC-N] da spec tem cobertura | | gate.m7.code_tested | 🟡 | Toda task que produz code tem teste pareado | | gate.m7.coverage_evidence_valid | 🟡 | Cada AC tem evidência pareada (code + test/integration/e2e) | | gate.m7.diff_hash_matches | 🟡 | O hash declarado bate com o conteúdo do arquivo |

acceptance:
  ids: [AC-1, AC-2]
stores:                       # M1
  ios_permissions:
    - NSLocationWhenInUseUsageDescription — posição no mapa da home
  android_permissions:
    - android.permission.ACCESS_FINE_LOCATION — posição no mapa
    - android.permission.POST_NOTIFICATIONS — alertas de entrega
a11y:                         # M3
  wcag_level: AA
  criteria:
    - Todos os controles expõem labels e roles acessíveis.
    - Contraste de texto ≥ 4.5:1; alvos de toque ≥ 44dp.

privacy:                      # M2
  lawful_basis: LGPD Art. 7 V (execução de contrato)
  residency: br-southeast
  retention: cache no dispositivo; não persistido além da sessão
os_matrix:                    # M4
  ios_min: "15.1"
  android_min: "7.0"
perf_budget:                  # M5
  ttfi_ms: 2000
  interactions_ms: 100
crash_free_slo: 99.9          # M6
observability:
  provider: Sentry React Native

🧯 Feature sem APIs restritas? Não invente permissões. Há dois caminhos honestos e auditáveis para o M1:

1. Opt-out no spec — deixe as listas vazias e declare stores.no_restricted_apis: "<motivo>" (espelha a11y.wcag_level: "n/a" e perf_budget.scope: "none").
2. Override por ADR — registre um ADR aceito em .raptor/memory/decisions.md com Overrides: gate.mobile.stores; o verify o lê em runtime e marca o gate como ⊝ overridden by ADR-NNN. Gates críticos nunca são waivados por ADR (exigem assinatura humana).

## ADR-001: Feature sem APIs restritas de OS
- Status: accepted
- Overrides: gate.mobile.stores
- Justification: Regras de negócio puras; não toca camera/location/etc.

🔬 A ponta de verificação (verify)

Declarar não é cumprir. O Raptor mede e compara com o declarado:

| Comando | Artigo | Como mede | | ----------------------------------- | --------- | ---------------------------------------------------------------------------------------- | | raptor verify a11y <feat> | M3 | Scan estático do JSX (labels/roles/contraste/touch targets) vs declaração WCAG | | raptor verify perf <feat> | M5 | Cold-start real no Android (adb am start -W), mediana vs perf_budget.ttfi_ms | | raptor verify stores <feat> | M1 | Compara spec.stores com AndroidManifest.xml/Info.plist; --fix adiciona faltantes | | raptor verify os-matrix <feat> | M4 | Compara plan.os_matrix com Gradle/Podfile; --fix alinha | | raptor verify architecture <feat> | M8 (exp.) | Checagem estática de arquitetura limpa sobre o grafo de imports | | raptor verify <feat> | — | Roda todos os gates da feature de uma vez |

🧪 Exemplo real: verify stores detectou que ACCESS_FINE_LOCATION e POST_NOTIFICATIONS estavam na spec mas ausentes do AndroidManifest.xml — e --fix corrigiu. verify perf mediu TTFI mediano de 957ms contra orçamento de 2000ms.

🧰 Capacidades do Raptor

| Capacidade | Para que serve | Comandos | | ----------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | 🎚️ Presets | Conjuntos reusáveis de artigos + gates, empilháveis. Bundled: mobile-opinionated (M1–M6), gol-smiles (G1–G6, empilha sobre mobile), lean. | raptor preset list · add · info · remove | | 🔁 Workflows | Orquestram o ciclo via YAML, com gates de revisão humana. Bundled: sdd-cycle, sdd-cycle-quick. | raptor workflow catalog · run · status · resume · list | | 🤖 Agentes | Materializa os slash commands por agente. | raptor add-agent · raptor list-agents | | 🧠 Skills | Habilidades reusáveis materializadas para os agentes. | raptor skill add · list · sync · remove | | 🔌 MCP | Registra servidores MCP e materializa nas configs nativas dos agentes. | raptor mcp add · list · sync · remove | | 🪝 Hooks | Scripts disparados em 34 pontos do ciclo (before_*/after_* de 17 comandos). | raptor hook list · run | | 📦 Extensões | Pacotes self-contained (templates/gates/hooks/workflows). | raptor extension add · list · info · remove | | 🎟️ Jira | Puxa issues do Jira (somente leitura) para semear specs. | raptor jira connect · status · pull · disconnect | | 🎨 Figma / Design | Captura determinística de tokens/telas/assets/fontes do Figma (provider figma-rest + PAT) e semeia design/. | raptor design connect · status · pull · sync · disconnect | | 📜 Auditoria & trace | Consulta a trilha de eventos e a rastreabilidade. | raptor audit query · show · raptor trace |

🎟️ Integração com Jira

raptor jira connect                 # OAuth/PKCE contra o Atlassian hosted
raptor jira pull APP-1234           # importa a issue
raptor new login --jira APP-1234    # semeia a spec a partir da issue

📖 Como o card é capturado por inteiro (campos ricos, links de Figma) e redistribuído na spec — com os gates cobrando: veja docs/jira-spec-enrichment.md.

🎨 Integração com Figma (design determinístico)

Em vez de o link do Figma virar só uma URL na spec, o Raptor captura o design de forma determinística e semeia a pasta design/ — espelhando o modelo do Jira (Raptor captura, agente redistribui).

raptor design connect               # provider figma-rest (Personal Access Token) — default, CI-friendly
raptor new home --figma <url-figma> # captura tokens/telas/assets/fontes e semeia design/
raptor design sync home             # re-captura idempotente (nunca sobrescreve o refino)

O provider figma-rest usa a REST API da Figma com um PAT (${FIGMA_TOKEN} no raptor.yml), é determinístico e roda em CI. A captura gera design/tokens.json (colors/typography/spacing/radii), design/screens/<slug>.md (frames de topo) e design/assets-manifest.json (assets baixados com SHA-256, guarda anti-SSRF). Quando há captura real, os prompts fazem o flip REDISTRIBUIR: o agente passa a refinar e redistribuir os artefatos em disco em vez de "olhar o Figma" — cobrado pelo gate.design.ready.

📖 Detalhes, providers e limitações: docs/design-figma-sync.md e docs/design-gate.md.

📖 Referência de comandos CLI

🔄 Ciclo         setup · init · new · clarify · plan · tasks · analyze · checklist · implement · approve · taskstoissues
🌿 Branch/commit commit · scan
🔬 Verificação   verify · verify a11y · verify perf · verify stores · verify os-matrix
                 verify architecture · verify audit · verify constitution
                 verify tangerina · verify arch · verify i18n   (preset gol-smiles)
📊 Status        status · doctor · trace · audit query · audit show
⚖️ Governança    gate list · gate approve · gate skip · repair constitution · hotfix · resync · upgrade
🧩 Extensão      preset … · workflow … · skill … · mcp … · hook … · extension …
                 add-agent · list-agents · add-extension
🎟️ Jira          jira connect · status · pull · disconnect
🎨 Figma/Design  design connect · status · pull · sync · disconnect

Rode raptor <comando> --help para os detalhes (flags, exemplos) de cada um.

💬 Quando você erra um comando

O Raptor corrige a rota em vez de só reclamar. Comando digitado errado vira sugestão do mais próximo:

$ raptor implment
✗ Comando implment não encontrado.

Você quis dizer:
  raptor implement

Detalhes:  raptor implement --help

Argumento ou flag faltando mostra como usar — com um exemplo concreto e as flags disponíveis:

$ raptor implement
✗ Missing 1 required arg: feature

Uso esperado:
  raptor implement FEATURE [flags]

Exemplo:
  raptor implement 001-login

Flags disponíveis:
  --task        Task id (e.g. T001) to mark completed
  --files       Comma-separated list of repo-relative paths ...
  ...

As cores são sutis e só aparecem no terminal — em pipes/CI a saída é texto puro, e NO_COLOR=1 desliga tudo.

🗂️ Estrutura criada no projeto

.raptor/
├── constitution.md          # 🧭 RAPTOR-CORE (C4) + artigos do preset
├── raptor.yml               # ⚙️ config (preset, ai, git.branch_per_feature, commit_trailer)
├── raptor.manifest.json     # 📋 manifest de instalação
├── agents.yml · skills.yml · mcp.yml
├── specs/<NNN-slug>/        # 📝 spec.md · plan.md · tasks.md · impl-log.md · audit.jsonl · checklists/ · design/ (tokens.json · screens/ · assets-manifest.json)
├── templates/               # 🧱 cópia bundlada (commands/*.md + *-template.md)
├── memory/                  # 🧠 constitution copy · amendments.log · decisions.md · glossary.md
├── extensions/ · workflows/ · presets/ · hooks/ · scripts/ · cache/
CLAUDE.md                    # 📎 bloco de contexto do agente
.claude/commands/            # 💬 slash commands materializados (raptor-specify.md, raptor-commit-review.md, …)
.git/hooks/                  # 🪝 pre-commit · commit-msg · pre-push (warn-only, via --with-hooks)
.github/workflows/           # 🔁 CI opcional (--with-ci) — inclui o job advisory-scan

📚 Documentação & glossário

Comece pelo 📖 Glossário Canônico — a referência normativa de todos os termos, gates, hierarquias e anti-padrões do Raptor (Gate, ADR, Override, Canonical, Preset, M1–M8, C1–C5, traceability…). É a base de onboarding para usuários, mantenedores e agentes IA.

| Documento | Sobre | | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | | 📖 docs/glossary.md | Glossário canônico: conceitos, hierarquias, catálogo de 48 gates e de comandos CLI | | 🧭 docs/setup-wizard.md | Assistente de instalação raptor setup: onboarding, IA/IDE, preset, Jira/Figma | | 🛡️ docs/readiness-gates.md | Gates de prontidão (spec/plan/tasks.ready) em detalhe | | 🎨 docs/design-figma-sync.md | Captura determinística do Figma (figma-rest): tokens/telas/assets/fontes + flip REDISTRIBUIR | | 🎨 docs/design-gate.md | Design gate, integração Figma e assets-manifest.json | | 🔗 docs/artifact-chain.md | Cadeia de artefatos e rastreabilidade spec→plan→tasks→código | | 🎟️ docs/jira-spec-enrichment.md | Enriquecimento de spec a partir de cards do Jira | | 📐 docs/templates-architecture.md | Dualidade de templates (.hbs vs *-template.md) e Priority Stack | | ✅ docs/spec-kit-parity.md | Paridade com o GitHub Spec Kit |

Hierarquia de governança (quem manda)

flowchart TD
    A["🧭 Constitution — Artigos C1–C5<br/><i>inviolável; só major release altera o core</i>"]
    B["🔎 Phase -1 / Constitution Check<br/><i>confronta decisões com a constituição</i>"]
    C["🛡️ Gates — 🔴 critical &gt; 🟡 required &gt; 🔵 advisory"]
    D["📝 ADR / Override<br/><i>dispensa required/advisory; nunca critical</i>"]
    E["👤 Human Review (C5)<br/><i>veto humano nos críticos</i>"]
    A --> B --> C --> D --> E

    classDef law fill:#fee2e2,stroke:#ef4444,color:#7f1d1d;
    classDef enf fill:#fef9c3,stroke:#eab308,color:#713f12;
    classDef human fill:#dcfce7,stroke:#22c55e,color:#14532d;
    class A,B law;
    class C,D enf;
    class E human;

Customização sem fork segue a Priority Stack: overrides do projeto → presets → extensions → core. Detalhes e justificativa de cada nível no glossário.

🛠️ Desenvolvimento local

Monorepo pnpm (packages/core = @raptor/core, packages/cli = binário raptor).

pnpm install
pnpm build
pnpm -r test && pnpm test:e2e     # ~1374 testes (1071 core + 258 cli + 45 e2e)

# usar a CLI local em outro projeto:
cd packages/cli && npm link        # ou: pnpm link --global

Publicar no npm (pacote único raptor-aios, com o core vendorizado):

pnpm build
node scripts/prepare-npm.mjs       # monta build/npm/ autossuficiente
cd build/npm && npm publish        # requer `npm login`

⚖️ Governança & contribuição

• 📜 GOVERNANCE.md — modelo de governança e emendas constitucionais.
• 🤝 CONTRIBUTING.md — convenção de commits (Conventional Commits, pt-BR, autoria humana; DCO opcional).
• 📄 Licença: MIT.

🦖 Raptor — velocidade cirúrgica na caça pela especificação perfeita.