flyee 0.1.0

package/core/skills/design-system-enforcement/SKILL.md

@@ -0,0 +1,339 @@
+---
+name: design-system-enforcement
+description: Garante que código UI usa Design System desde a criação. Aplica-se durante TDD GREEN phase e qualquer criação de componente UI.
+---
+
+# Design System Enforcement
+
+> **Regra:** Todo código UI DEVE usar o Design System desde a criação, não apenas na fase de "styling".
+
+---
+
+## 🚨 Quando Esta Skill se Aplica
+
+| Situação | Aplica? |
+|----------|---------|
+| TDD GREEN phase com componente UI | ✅ SIM |
+| Criação de nova página | ✅ SIM |
+| Criação de novo componente | ✅ SIM |
+| Código backend/API | ❌ NÃO |
+| Testes unitários | ❌ NÃO |
+
+---
+
+## 📋 Pré-requisitos (OBRIGATÓRIO)
+
+ANTES de escrever qualquer código UI:
+
+```markdown
+[ ] CSS Variables instaladas em src/app/globals.css (ou equivalente)
+[ ] design-system/{projeto}/MASTER.md lido e carregado
+[ ] design-system/{projeto}/layout/SHARED-LAYOUT.md lido (se Header, Footer, Menu, ou layout global)
+[ ] design-system/{projeto}/pages/PAGE-SPEC-{página}.md lido (se implementando seção de página)
+[ ] Conhecimento dos anti-patterns do workflow /ui-ux-pro-max
+```
+
+> [!CAUTION]
+> **FALHA QUE GEROU ESTA EXPANSÃO:** MASTER.md sozinho cobre tokens CSS (cores, tipografia,
+> spacing). Mas elementos estruturais (quais ícones no header, quantas colunas no footer,
+> tipo de mobile menu) estão nos specs de layout/página. Sem lê-los, o agente implementa
+> com base em padrões genéricos em vez do design aprovado.
+
+**Se CSS Variables NÃO existem:**
+1. Abrir `design-system/{projeto}/MASTER.md`
+2. Copiar seção de tokens/variáveis CSS
+3. Colar em `globals.css`
+4. Definir body styling base
+
+---
+
+## 🎨 Durante Criação de Componente
+
+Para CADA elemento visual criado:
+
+| Aspecto | ✅ Correto | ❌ Errado |
+|---------|-----------|----------|
+| **Cores** | `style={{ color: 'var(--lime)' }}` | `style={{ color: '#CFFF00' }}` |
+| **Background** | `var(--bg-card)` | `#111111` ou `bg-gray-900` |
+| **Bordas** | `var(--radius-md)` | `12px` hardcoded |
+| **Fontes** | Font do MASTER.md | Arial, sans-serif |
+| **Ícones** | `<Home size={20} />` (Lucide) | `🏠` emoji |
+| **Interação** | `className="cursor-pointer"` | Sem cursor |
+| **Glass** | `backdrop-filter: blur(16px)` + overlay | `background-color: var(--bg-card)` solid ⭐ |
+| **Shadows** | `var(--shadow-md)` | `box-shadow: 0 4px 12px...` hardcoded |
+
+---
+
+## 💠 Efeitos Visuais (MASTER.md § Efeitos Visuais)
+
+> [!CAUTION]
+> **FALHA QUE GEROU ESTA SEÇÃO:** Dashboard UI foi criado com cores sólidas
+> (`background-color: var(--color-bg-secondary)`) sem aplicar glassmorphism
+> (`backdrop-filter: blur(16px)`, `var(--color-overlay-*)`) definido no MASTER.md.
+> O agente tecnicamente "usou CSS variables" (satisfazendo as regras anteriores),
+> mas ignorou completamente a seção de Efeitos Visuais.
+> Resultado: dashboard visualmente plano, sem a estética premium das referências.
+
+**Se MASTER.md define Efeitos Visuais (glassmorphism, gradientes, glows, etc.), então:**
+
+| Componente | Efeito Obrigatório | Implementação |
+|------------|-------------------|---------------|
+| **Cards** (KPI, Project, etc.) | Glassmorphism | `backdrop-filter: blur()` + `var(--color-overlay-05)` + border translúcida |
+| **Sidebar** | Glass ou surface | `backdrop-filter: blur()` ou `var(--color-bg-secondary)` se spec permitir opaco |
+| **TopBar / Header** | Glass com blur | `backdrop-filter: blur()` para visual premium |
+| **Modals / Dropdowns** | Elevated glass | `var(--shadow-lg)` + `backdrop-filter` |
+| **Hover states** | Micro-animation | `transform`, `box-shadow`, `border-color` com transition |
+
+**Anti-patterns de Efeitos:**
+
+| ❌ Errado | ✅ Correto |
+|----------|----------|
+| `background-color: var(--bg-card)` sem blur | `background: var(--color-overlay-05); backdrop-filter: blur(16px)` |
+| Card sem shadow alguma | `box-shadow: var(--shadow-md)` |
+| Hover sem feedback visual | `transition: all 200ms; transform: translateY(-2px)` |
+| Border opaca | `border: 1px solid var(--color-overlay-08)` |
+
+---
+
+## 🏗️ Anatomia de Layout (Reference Matching)
+
+> [!IMPORTANT]
+> **REFERENCE MODE:** Quando `frontend-specialist.md` ativa o Reference Mode,
+> esta seção é a mais crítica. A análise de anatomia abaixo é **OBRIGATÓRIA**
+> e deve ser feita ANTES de escrever qualquer CSS. Regras anti-template e
+> anti-safe-harbor do frontend-specialist são SUSPENSAS em Reference Mode.
+
+> [!CAUTION]
+> **FALHA QUE GEROU ESTA SEÇÃO:** Dashboard Sidebar e TopBar foram implementados
+> como "floating pills" com `border-radius: 32px` e `gap: 1.5rem` descolados das bordas,
+> quando a referência SphereUI mostrava claramente componentes **edge-to-edge**
+> (sidebar colada à borda esquerda, topbar como faixa horizontal contínua).
+> O agente "olhou" a referência mas não analisou a anatomia espacial — pulou direto
+> para escrever CSS baseado em suposições genéricas.
+
+**ANTES de implementar qualquer layout, o agente DEVE:**
+
+1. **Descrever textualmente** o que vê na referência visual (se disponível):
+   ```markdown
+   ## Análise da Referência — {componente}
+   - Sidebar: [edge-to-edge | floating | pill]
+   - Sidebar border-radius: [nenhum nas bordas da viewport | apenas interno | todos os lados]
+   - TopBar: [faixa contínua acima do conteúdo | se estende sobre sidebar | pill flutuante]
+   - Toggle collapse: [header da sidebar | topbar | inline no conteúdo]
+   - Elementos colam na viewport? [sim — top/left/bottom | não — margin ao redor]
+   ```
+2. **Comparar** com o que está implementando
+3. **Se não houver referência visual:** Perguntar ao usuário ou seguir o PAGE-SPEC
+
+**Checklist de Anatomia Espacial:**
+
+| Aspecto | Pergunta | Impacto se errado |
+|---------|----------|-------------------|
+| **Ancoragem** | O componente encosta na borda da viewport? | Edge-to-edge vs floating pill |
+| **Border-radius** | Quais cantos são arredondados? | Todos = floating. Apenas internos = encostado na borda |
+| **Span** | TopBar cobre toda a largura ou só o conteúdo? | Layout em colunas (sidebar + main) vs layout unificado |
+| **Toggle position** | O collapse está no header da sidebar ou no topbar? | Afeta onde o botão é renderizado |
+| **Height** | Sidebar tem height: 100vh ou height: auto? | Scroll behavior e ancoragem |
+
+---
+
+## 🎨 Premium Styling in GREEN Phase
+
+> [!CAUTION]
+> Components MUST be created with **final premium styling** (glassmorphism, gradients, glows,
+> backdrop-blur, micro-animations) during the GREEN phase of TDD, not after.
+> Phase 5.3 is for **validation and fine-tuning only**, not for applying styles from scratch.
+
+| Principle | Correct | Wrong |
+|-----------|---------|-------|
+| Glass cards | `backdrop-filter: blur(16px)` + overlay from start | Solid `var(--bg-card)`, plan to "style later" |
+| Shadows | `var(--shadow-md)` on creation | Plain flat card, add shadows in Phase 5.3 |
+| Animations | `transition: all 200ms` on hover from start | Static element, add motion later |
+| Gradients | Apply gradient as defined in MASTER.md | Solid background color as placeholder |
+
+> **Historical Lesson:** Pricing Page was created with basic styles (solid colors, no glassmorphism, no animations)
+> during TDD GREEN. Result: complete rework of 5 CSS files in Phase 5.3 to match Landing Page premium level.
+
+---
+
+## 📖 UI Spec Reading Gate
+
+> [!CAUTION]
+> **Before writing any UI code (GREEN phase), the agent MUST read ALL applicable specs.**
+> Do NOT implement based on inference or memory.
+
+**Mandatory checklist before GREEN (for tasks involving UI):**
+
+```markdown
+⚠️ UI SPEC READING GATE — Task: {title}
+
+[ ] MASTER.md read — Colors section (CSS tokens)
+[ ] MASTER.md read — Typography section
+[ ] MASTER.md read — Visual Effects section (glassmorphism, shadows, micro-animations) ⭐
+[ ] MASTER.md read — Components section (if creating button, input, card, etc.)
+[ ] SHARED-LAYOUT.md read (if component is Header, Footer, Mobile Menu, or shared layout)
+[ ] PAGE-SPEC-{page}.md read (if implementing a section of a specific page)
+[ ] Required elements identified (list extracted from spec)
+[ ] Responsiveness/breakpoints noted
+
+❌ If ANY applicable item unchecked → DO NOT IMPLEMENT
+✅ All checked → Proceed with GREEN
+```
+
+**Component → Spec mapping:**
+
+| Component | Required Specs |
+|-----------|---------------|
+| Header / Navbar | `SHARED-LAYOUT.md` §1 |
+| Footer | `SHARED-LAYOUT.md` §2 |
+| Mobile Menu | `SHARED-LAYOUT.md` §3 |
+| Dashboard Layout | `SHARED-LAYOUT.md` §4 + `PAGE-SPEC-Dashboard.md` |
+| Dashboard Sections | `PAGE-SPEC-Dashboard.md` + `MASTER.md` §Visual Effects |
+| LP Sections | `PAGE-SPEC-Landing.md` + `SHARED-LAYOUT.md` §1-§2 |
+| Pricing Sections | `PAGE-SPEC-Pricing.md` |
+| UI Primitives (Button, Input) | `MASTER.md` only |
+
+> **Historical Lesson:** Landing Page was developed without reading SHARED-LAYOUT.md.
+> Header shipped without scroll shadow, search, github, language, theme, and login icons.
+> Footer shipped with 3 columns instead of 4. Mobile menu was dropdown inline instead of slide-in sheet.
+> Result: complete rework of Header and Footer.
+
+> **Historical Lesson (v2):** Dashboard UI was created with solid colors (`var(--color-bg-secondary)`)
+> without applying glassmorphism defined in the "Visual Effects" section of MASTER.md.
+> The agent read MASTER.md but focused only on tokens (colors, typography), ignoring visual effects.
+> Fix: checklist now lists EACH section of MASTER.md separately, with ⭐ on Visual Effects.
+
+---
+
+## 🧩 Component Classification
+
+> [!CAUTION]
+> **Before creating ANY UI component, classify it first.**
+> A reusable component MUST be created in `src/components/ui/` from the start.
+
+**Decision tree:**
+
+| Question | If YES | If NO |
+|----------|--------|-------|
+| Can this be used in 2+ pages/features? | → `src/components/ui/` + own CSS Module | Continue ↓ |
+| Is the logic/visual generic enough for another dev to reuse? | → `src/components/ui/` | Continue ↓ |
+| Does it only make sense inside 1 feature? | → `src/components/{feature}/` | Continue ↓ |
+| Is it used in the app shell (topbar, sidebar)? | → `src/components/layout/` | `src/components/{feature}/` |
+
+| Type | Location | CSS |
+|------|----------|-----|
+| **Reusable** | `src/components/ui/` | Own CSS Module |
+| **Feature-specific** | `src/components/{feature}/` | Feature CSS or Module |
+| **Shared layout** | `src/components/layout/` | Own CSS Module |
+
+> **Historical Lesson:** `ReviewCard` and `IconButton` were created inline (Tailwind) inside feature folders.
+> They had to be moved, refactored, and reconnected to the Design System in a separate session — avoidable rework.
+
+---
+
+## ✅ Checklist por Componente
+
+Antes de considerar um componente "pronto":
+
+```markdown
+Para: {ComponentName}
+
+### Variáveis CSS
+[ ] Todas as cores usam var(--xxx)
+[ ] Backgrounds usam var(--bg-xxx)
+[ ] Border-radius usa var(--radius-xxx)
+
+### Efeitos Visuais (se MASTER.md define) ⭐
+[ ] Cards/surfaces usam glassmorphism (backdrop-filter + overlay) conforme MASTER.md
+[ ] Shadows aplicadas conforme nível de elevação (sm/md/lg)
+[ ] Hover states têm micro-animações (transition, transform)
+[ ] Borders usam overlay variables (var(--color-overlay-08))
+
+### Tipografia
+[ ] Font-family definida no MASTER.md ou herdada do body
+[ ] Font-sizes seguem escala do Design System
+
+### Ícones
+[ ] Nenhum emoji usado como ícone
+[ ] Ícones de Lucide React ou Heroicons
+
+### Interação
+[ ] cursor-pointer em elementos clicáveis
+[ ] Hover states com feedback visual
+[ ] Transitions suaves (150-300ms)
+
+### Acessibilidade
+[ ] role="xxx" onde apropriado
+[ ] aria-label em ícones/botões sem texto
+```
+
+---
+
+## 🔴 Gate de Saída
+
+Componente só está "pronto para commit" quando:
+
+```markdown
+[ ] Usa APENAS variáveis do Design System
+[ ] Sem cores/valores hardcoded
+[ ] Sem emojis como ícones
+[ ] cursor-pointer em clicáveis
+[ ] Efeitos visuais aplicados conforme MASTER.md (glassmorphism, shadows, animations) ⭐
+[ ] Passou no ui_antipattern_check.py (se disponível)
+```
+
+---
+
+## 🔗 Workflows que Referenciam Esta Skill
+
+| Workflow | Fase |
+|----------|------|
+| `/new-project` | Phase 4 (TDD GREEN) |
+| `/new-task` | Fase 3.5 (TDD) |
+| `/legacy-project` | Phase 6 (Testes) |
+
+---
+
+## 📝 Exemplo Prático
+
+### ❌ Errado (hardcoded)
+
+```tsx
+export default function Card() {
+  return (
+    <div style={{ 
+      backgroundColor: '#111111',  // ❌ hardcoded
+      color: 'white',              // ❌ hardcoded
+      borderRadius: '12px'         // ❌ hardcoded
+    }}>
+      <span>🚀</span>  {/* ❌ emoji como ícone */}
+      <button>Click</button>  {/* ❌ sem cursor-pointer */}
+    </div>
+  )
+}
+```
+
+### ✅ Correto (Design System)
+
+```tsx
+import { Rocket } from 'lucide-react'
+
+export default function Card() {
+  return (
+    <div style={{ 
+      backgroundColor: 'var(--bg-card)',
+      color: 'var(--text-primary)',
+      borderRadius: 'var(--radius-md)'
+    }}>
+      <Rocket size={20} style={{ color: 'var(--lime)' }} />
+      <button className="cursor-pointer hover:opacity-80 transition-opacity">
+        Click
+      </button>
+    </div>
+  )
+}
+```
+
+---
+
+> **Lembre-se:** O Design System é lei. Não há exceções para "fazer rápido" ou "ajustar depois".

package/core/skills/doc.md

@@ -0,0 +1,177 @@
+# Antigravity Skills
+
+> **Hướng dẫn tạo và sử dụng Skills trong Antigravity Kit**
+
+---
+
+## 📋 Giới thiệu
+
+Mặc dù các mô hình cơ bản của Antigravity (như Gemini) là những mô hình đa năng mạnh mẽ, nhưng chúng không biết ngữ cảnh dự án cụ thể hoặc các tiêu chuẩn của nhóm bạn. Việc tải từng quy tắc hoặc công cụ vào cửa sổ ngữ cảnh của tác nhân sẽ dẫn đến tình trạng "phình to công cụ", chi phí cao hơn, độ trễ và sự nhầm lẫn.
+
+**Antigravity Skills** giải quyết vấn đề này thông qua tính năng **Progressive Disclosure**. Kỹ năng là một gói kiến thức chuyên biệt, ở trạng thái không hoạt động cho đến khi cần. Thông tin này chỉ được tải vào ngữ cảnh của tác nhân khi yêu cầu cụ thể của bạn khớp với nội dung mô tả của kỹ năng.
+
+---
+
+## 📁 Cấu trúc và Phạm vi
+
+Kỹ năng là các gói dựa trên thư mục. Bạn có thể xác định các phạm vi này tuỳ thuộc vào nhu cầu:
+
+| Phạm vi | Đường dẫn | Mô tả |
+|---------|-----------|-------|
+| **Workspace** | `<workspace-root>/.agent/skills/` | Chỉ có trong một dự án cụ thể |
+
+### Cấu trúc thư mục kỹ năng
+
+```
+my-skill/
+├── SKILL.md      # (Required) Metadata & instructions
+├── scripts/      # (Optional) Python or Bash scripts
+├── references/   # (Optional) Text, documentation, templates
+└── assets/       # (Optional) Images or logos
+```
+
+---
+
+## 🔍 Ví dụ 1: Code Review Skill
+
+Đây là một kỹ năng chỉ có hướng dẫn (instruction-only), chỉ cần tạo file `SKILL.md`.
+
+### Bước 1: Tạo thư mục
+
+```bash
+mkdir -p ~/.gemini/antigravity/skills/code-review
+```
+
+### Bước 2: Tạo SKILL.md
+
+```markdown
+---
+name: code-review
+description: Reviews code changes for bugs, style issues, and best practices. Use when reviewing PRs or checking code quality.
+---
+
+# Code Review Skill
+
+When reviewing code, follow these steps:
+
+## Review checklist
+
+1. **Correctness**: Does the code do what it's supposed to?
+2. **Edge cases**: Are error conditions handled?
+3. **Style**: Does it follow project conventions?
+4. **Performance**: Are there obvious inefficiencies?
+
+## How to provide feedback
+
+- Be specific about what needs to change
+- Explain why, not just what
+- Suggest alternatives when possible
+```
+
+> **Lưu ý**: File `SKILL.md` chứa siêu dữ liệu (name, description) ở trên cùng, sau đó là các chỉ dẫn. Agent sẽ chỉ đọc siêu dữ liệu và chỉ tải hướng dẫn khi cần.
+
+### Dùng thử
+
+Tạo file `demo_bad_code.py`:
+
+```python
+import time
+
+def get_user_data(users, id):
+    # Find user by ID
+    for u in users:
+        if u['id'] == id:
+            return u
+    return None
+
+def process_payments(items):
+    total = 0
+    for i in items:
+        # Calculate tax
+        tax = i['price'] * 0.1
+        total = total + i['price'] + tax
+        time.sleep(0.1)  # Simulate slow network call
+    return total
+
+def run_batch():
+    users = [{'id': 1, 'name': 'Alice'}, {'id': 2, 'name': 'Bob'}]
+    items = [{'price': 10}, {'price': 20}, {'price': 100}]
+    
+    u = get_user_data(users, 3)
+    print("User found: " + u['name'])  # Will crash if None
+    
+    print("Total: " + str(process_payments(items)))
+
+if __name__ == "__main__":
+    run_batch()
+```
+
+**Prompt**: `review the @demo_bad_code.py file`
+
+Agent sẽ tự động xác định kỹ năng `code-review`, tải thông tin và thực hiện theo hướng dẫn.
+
+---
+
+## 📄 Ví dụ 2: License Header Skill
+
+Kỹ năng này sử dụng file tham chiếu (reference file) trong thư mục `resources/`.
+
+### Bước 1: Tạo thư mục
+
+```bash
+mkdir -p .agent/skills/license-header-adder/resources
+```
+
+### Bước 2: Tạo file template
+
+**`.agent/skills/license-header-adder/resources/HEADER.txt`**:
+
+```
+/*
+ * Copyright (c) 2026 YOUR_COMPANY_NAME LLC.
+ * All rights reserved.
+ * This code is proprietary and confidential.
+ */
+```
+
+### Bước 3: Tạo SKILL.md
+
+**`.agent/skills/license-header-adder/SKILL.md`**:
+
+```markdown
+---
+name: license-header-adder
+description: Adds the standard corporate license header to new source files.
+---
+
+# License Header Adder
+
+This skill ensures that all new source files have the correct copyright header.
+
+## Instructions
+
+1. **Read the Template**: Read the content of `resources/HEADER.txt`.
+2. **Apply to File**: When creating a new file, prepend this exact content.
+3. **Adapt Syntax**: 
+   - For C-style languages (Java, TS), keep the `/* */` block.
+   - For Python/Shell, convert to `#` comments.
+```
+
+### Dùng thử
+
+**Prompt**: `Create a new Python script named data_processor.py that prints 'Hello World'.`
+
+Agent sẽ đọc template, chuyển đổi comments theo kiểu Python và tự động thêm vào đầu file.
+
+---
+
+## 🎯 Kết luận
+
+Bằng cách tạo Skills, bạn đã biến mô hình AI đa năng thành một chuyên gia cho dự án của mình:
+
+- ✅ Hệ thống hoá các best practices
+- ✅ Tuân theo quy tắc đánh giá code
+- ✅ Tự động thêm license headers
+- ✅ Agent tự động biết cách làm việc với nhóm của bạn
+
+Thay vì liên tục nhắc AI "nhớ thêm license" hoặc "sửa format commit", giờ đây Agent sẽ tự động thực hiện!

package/core/skills/document-registry/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: document-registry
+description: Protocolo para manter docs/INDEX.md atualizado como fonte de verdade de todos os documentos do projeto. Obrigatório em toda fase que cria ou consome documentação. Usado por new-project, legacy-project, new-task e qualquer workflow que gere artefatos.
+---
+
+# Skill: document-registry
+
+## Propósito
+
+`docs/INDEX.md` é o **único ponto de entrada** para que agentes saibam o que existe no projeto sem precisar varrer o sistema de arquivos. Este skill define como mantê-lo correto.
+
+> [!IMPORTANT]
+> **REGRA DO AGENTE:** Antes de buscar qualquer documento, verificar `docs/INDEX.md`.
+> Se o INDEX não existir → executar `project-foundation` primeiro.
+
+---
+
+## 1. Antes de Buscar Documentos (READ)
+
+Ao iniciar qualquer fase ou task que precise de contexto:
+
+```
+1. Ler docs/INDEX.md
+2. Identificar entries relevantes pelo tipo ou doc_id
+3. Seguir o path listado — NÃO buscar o arquivo por nome em todo o fs
+4. Verificar o status: draft | review | approved | superseded
+   → draft: usar com cautela, não é fonte de verdade
+   → review: aguardar aprovação antes de implementar
+   → approved: implementar com confiança
+   → superseded: NÃO usar — ver "replaced_by" no INDEX
+```
+
+---
+
+## 2. Ao Criar um Documento (WRITE)
+
+Toda vez que um documento for criado, adicionar uma entry no INDEX **imediatamente**:
+
+### Formato da Entry
+
+```markdown
+| {doc_id} | {Type} | [{basename}]({relative-path}) | draft | {version} | — |
+```
+
+### Campos Obrigatórios
+
+| Campo | Formato | Exemplo |
+|-------|---------|---------|
+| `doc_id` | `{TYPE}-{slug}` | `PRD-flyee`, `SDD-auth`, `FLOW-login` |
+| `Type` | PRD, SDD, Design System, OpenAPI, Flow, ADR, Handover, Test Guide, Page Spec | `Flow` |
+| Path | Relativo ao `/docs/` | `flows/auth/login.md` |
+| Status | `draft` (default ao criar) | `draft` |
+| Version | `"1.0"` ao criar | `"1.0"` |
+| `approved_at` | `—` (vazio ao criar) | `—` |
+
+### Tipos de Documentos e doc_id Padrão
+
+| Tipo | doc_id padrão | Exemplo |
+|------|--------------|---------|
+| PRD | `PRD-{slug}` | `PRD-flyee` |
+| SDD (Software Design Doc) | `SDD-{slug}-{módulo}` | `SDD-flyee-auth` |
+| Design System | `DS-{slug}` | `DS-flyee` |
+| OpenAPI Spec | `API-{slug}` | `API-flyee` |
+| Flow documentation | `FLOW-{slug}` | `FLOW-login` |
+| ADR | `ADR-{NNN}-{slug}` | `ADR-001-redis` |
+| Handover | `HANDOVER-{escopo}` | `HANDOVER-auth` |
+| Test Guide | `TESTGUIDE-{escopo}` | `TESTGUIDE-auth` |
+| Page Spec | `PAGESPEC-{page}` | `PAGESPEC-dashboard` |
+| Retrospective | `RETRO-{slug}-v{N}` | `RETRO-flyee-v1` |
+| Security Policy | `SECURITY` | `SECURITY` |
+| Legacy Analysis | `LEGACY-ANALYSIS` | `LEGACY-ANALYSIS` |
+
+---
+
+## 3. Ao Aprovar um Documento (STATUS UPDATE)
+
+Quando o usuário aprovar um documento:
+
+```
+1. Abrir docs/INDEX.md
+2. Localizar a entry pelo doc_id
+3. Atualizar: status → approved, approved_at → YYYY-MM-DD
+4. Se substituindo versão anterior: marcar antiga como superseded, adicionar campo replaced_by
+```
+
+---
+
+## 4. Ao Superseder um Documento
+
+```
+1. Marcar entry antiga: status → superseded
+2. Adicionar coluna implied "replaced_by: {novo_doc_id}"
+3. Adicionar nova entry com nova versão
+4. NÃO deletar a entry antiga do INDEX — histórico é valioso
+```
+
+---
+
+## 5. Checklist por Fase
+
+### Fases que CRIAM documentos (devem atualizar INDEX):
+- `project-foundation` → README, .env.example, SECURITY, INDEX, ADR-000
+- `new-project` Phase 1 → PRD
+- `new-project` Phase 2 → SDD
+- `new-project` Phase 2.5 → Design System
+- `new-project` Phase 2.65 → Content docs
+- `new-project` Phase 2.8 → Page Specs
+- `legacy-project` Phase 4 (loop) → Flow docs
+- `legacy-project` Phase 5 → SDD by module
+- `legacy-project` Phase 5.5 → Design System
+- `legacy-project` Phase 5.6 → Security ADR (se issues encontrados)
+- `legacy-project` Phase 7.5 → ADRs
+- `legacy-project` Phase 8 → Handover + Test Guide
+
+### Fases que CONSOMEM documentos (devem ler INDEX primeiro):
+- Qualquer fase de implementação
+- `context-gathering-patterns` (verificar INDEX antes de buscar docs)
+- `new-task` Fase -1 e Fase 1 (histórico + contexto)
+
+---
+
+## 6. Anti-Patterns
+
+| ❌ Proibido | ✅ Correto |
+|------------|-----------|
+| Buscar `find docs/ -name "*.md"` para achar documentos | Ler `docs/INDEX.md` primeiro |
+| Criar documento sem adicionar ao INDEX | Criar + entry no INDEX imediatamente |
+| Usar documento com status `draft` como fonte de verdade | Verificar status antes de implementar |
+| Deletar entries do INDEX | Marcar como `superseded` (nunca deletar) |
+| Criar documento com `doc_id` duplicado | Verificar INDEX antes de criar |