@joelbonito/mcp-server 5.1.6 → 5.2.0

package/dist/core/resources.js

@@ -33,6 +33,77 @@ export function registerResources(server, cache) {
         }
         return { contents: [{ uri: uri.href, text: skill.raw, mimeType: "text/markdown" }] };
     });
+    // Static: condensed system prompt with operational rules
+    server.resource("system-prompt", "inove://system-prompt", { mimeType: "text/markdown", description: "Condensed operational rules (Socratic Gate, routing, clean code). Inject into system prompt for full framework behavior." }, () => {
+        const agentList = [...cache.agents.values()]
+            .map((a) => `| \`${a.meta.name}\` | ${a.meta.description} | ${a.meta.skills.join(", ")} |`)
+            .join("\n");
+        const workflowList = [...cache.workflows.entries()]
+            .map(([name, w]) => `| \`/${name}\` | ${w.meta.description} |`)
+            .join("\n");
+        const prompt = `# Inove AI Framework — Operational Rules
+
+> Injected via MCP. These rules govern how you operate with the framework.
+
+## Routing Protocol
+
+When the user asks for help, detect the domain from their request and activate the appropriate agent using the \`activate_agent\` tool. Use \`route_task\` if unsure which agent to pick.
+
+## Socratic Gate (MANDATORY)
+
+For ALL requests involving code, STOP and ASK first:
+
+| Request Type | Strategy | Action |
+|---|---|---|
+| New Feature / Build | Deep Discovery | ASK minimum 3 strategic questions |
+| Edit / Bug Fix | Diagnosis | Present DIAGNOSIS + PROPOSAL → wait for approval → only then edit |
+| Vague / Simple | Clarification | Ask Purpose, Users and Scope |
+
+**Never assume.** If 1% is undefined, ASK.
+
+## Clean Code (Global)
+
+- Concise, self-documenting code
+- No over-engineering
+- Tests mandatory (Unit > Integration > E2E)
+- Comments in English, variables/functions in English
+- Respond in user's language
+
+## Workflow Invocation
+
+Use the \`execute_workflow\` tool to run slash commands. Available workflows:
+
+| Command | Description |
+|---|---|
+${workflowList}
+
+## Agent Activation
+
+Use the \`activate_agent\` tool to load an agent's persona, rules and skills. Available agents:
+
+| Agent | Description | Skills |
+|---|---|---|
+${agentList}
+
+## Backlog Integration
+
+When the user says "implement Epic X" or "implement Story Y.Z":
+
+1. Read backlog: \`docs/BACKLOG.md\`
+2. If \`docs/stories/\` doesn't exist, suggest running \`shard_epic.py shard\`
+3. Detect domain → Activate appropriate agent
+4. Implement following agent rules
+5. After completion, update progress
+
+## Post-Define Flow
+
+After \`/define\` or \`/readiness\`:
+1. \`/track\` — Initialize tracking
+2. \`shard_epic.py shard\` — Split backlog into story files
+3. Start implementing Story 1.1
+`;
+        return { contents: [{ uri: "inove://system-prompt", text: prompt, mimeType: "text/markdown" }] };
+    });
     // Template: individual workflow
     server.resource("workflow", new ResourceTemplate("inove://workflows/{name}", { list: undefined }), { mimeType: "text/markdown", description: "Full content of a specific workflow" }, (uri, { name }) => {
         const workflow = cache.workflows.get(name);

package/dist/core/tools.js

@@ -56,6 +56,42 @@ export function registerTools(server, cache) {
         const result = routeTask(request, cache);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
+    // execute_workflow — simulates /slash invocation for MCP clients
+    server.tool("execute_workflow", "Execute a framework workflow (slash command). Returns the full workflow instructions for the AI to follow. Use this instead of typing /define, /debug, etc.", {
+        name: z.string().min(1).max(100).describe("Workflow name without slash (e.g. 'define', 'debug', 'create')"),
+        arguments: z.string().max(10000).optional().describe("Arguments to pass to the workflow (e.g. 'App de gestao de tarefas')"),
+    }, ({ name, arguments: args }) => {
+        const workflow = cache.workflows.get(name);
+        if (!workflow) {
+            const available = [...cache.workflows.keys()].join(", ");
+            return { content: [{ type: "text", text: `Workflow "${name}" not found. Available: ${available}` }], isError: true };
+        }
+        const header = `# Executing /${name}${args ? ` ${args}` : ""}\n\n> Follow the instructions below to execute this workflow.\n\n---\n\n`;
+        const footer = args ? `\n\n---\n\n## Arguments Provided\n\n\`\`\`\n${args}\n\`\`\`\n\nApply the workflow above using these arguments.` : "";
+        return { content: [{ type: "text", text: header + workflow.raw + footer }] };
+    });
+    // activate_agent — loads agent persona, rules and skills for MCP clients
+    server.tool("activate_agent", "Activate a specialist agent. Returns the agent's full persona, rules and loaded skills. Use this to adopt agent behavior (e.g. @frontend-specialist, @debugger).", {
+        name: z.string().min(1).max(100).describe("Agent name (e.g. 'frontend-specialist', 'debugger', 'security-auditor')"),
+    }, ({ name }) => {
+        const agent = cache.agents.get(name);
+        if (!agent) {
+            const available = [...cache.agents.keys()].join(", ");
+            return { content: [{ type: "text", text: `Agent "${name}" not found. Available: ${available}` }], isError: true };
+        }
+        // Load all skills referenced by the agent
+        const skillContents = agent.meta.skills
+            .map((skillName) => {
+            const skill = cache.skills.get(skillName);
+            if (!skill)
+                return null;
+            return `\n---\n\n## Skill: ${skillName}\n\n${skill.raw}`;
+        })
+            .filter(Boolean)
+            .join("\n");
+        const header = `# Agent Activated: @${name}\n\n> You are now operating as **${name}**. Follow the persona, rules and skills below.\n> Loaded ${agent.meta.skills.length} skill(s): ${agent.meta.skills.join(", ")}\n\n---\n\n`;
+        return { content: [{ type: "text", text: header + agent.raw + skillContents }] };
+    });
     // search_content
     server.tool("search_content", "Full-text search across all framework content (agents, skills, workflows)", {
         query: z.string().min(1).max(5000).describe("Search query"),

package/dist/registry.js

@@ -317,7 +317,7 @@ export const EMBEDDED_WORKFLOWS = {
     "context": "---\ndescription: Cria documento de Project Context que cristaliza padrões técnicos, convenções e regras do projeto para garantir consistência.\n---\n\n# Workflow: /context\n\n> **Propósito:** Documentar TODOS os padrões técnicos, convenções e regras \"óbvias demais para mencionar\" que garantem consistência no projeto.\n\n## Quando Usar\n\n- No início de um novo projeto (após `/define`)\n- Quando um novo desenvolvedor (humano ou IA) entra no projeto\n- Quando há necessidade de padronizar decisões técnicas\n\n## Regras Críticas\n\n1. **SEJA EXPLÍCITO** - Documente até o \"óbvio\"\n2. **INCLUA EXEMPLOS** - Código > Descrição\n3. **MANTENHA ATUALIZADO** - Documento vivo\n4. **UNIFIQUE PADRÕES** - Uma fonte de verdade\n\n---\n\n## Fluxo de Execução\n\n### Fase 0: Coleta de Informações\n\nPergunte ao usuário sobre preferências técnicas:\n\n```markdown\n🔧 Para criar o Project Context, preciso entender suas preferências:\n\n### Stack Técnica\n1. **Frontend:** (React, Vue, Next.js, Svelte, etc.)\n2. **Backend:** (Node.js, Python, Go, etc.)\n3. **Database:** (PostgreSQL, MongoDB, Firebase, Supabase, etc.)\n4. **Linguagem principal:** (TypeScript, JavaScript, Python, etc.)\n\n### Convenções\n5. **Idioma do código:** (variáveis/funções em inglês ou português?)\n6. **Idioma dos comentários:** (português ou inglês?)\n7. **Idioma da UI:** (português, inglês, multi-idioma?)\n\n### Preferências\n8. **CSS Framework:** (Tailwind, CSS Modules, Styled Components?)\n9. **Validação de dados:** (Zod, Yup, Joi, nativa?)\n10. **Testes:** (Jest, Vitest, Playwright, Cypress?)\n```\n\n---\n\n### Fase 1: Criar Documento\n\n**Output:** `docs/PROJECT-CONTEXT.md`\n\n```markdown\n# Project Context: {Nome do Projeto}\n\n> **Propósito:** Documento de referência para padrões técnicos e convenções do projeto.\n> Todos os desenvolvedores (humanos e IA) DEVEM seguir estas regras.\n\n## Metadados\n- **Criado em:** {YYYY-MM-DD}\n- **Última atualização:** {YYYY-MM-DD}\n- **Versão:** 1.0\n\n---\n\n## 1. Stack Técnica\n\n### 1.1 Versões Obrigatórias\n\n| Tecnologia | Versão | Notas |\n|------------|--------|-------|\n| Node.js | >= 18.x | LTS recomendado |\n| {Framework} | {versão} | |\n| TypeScript | >= 5.0 | strict mode ON |\n| {Database} | {versão} | |\n\n### 1.2 Dependências Core\n\n```json\n{\n  \"dependencies\": {\n    \"react\": \"^18.2.0\",\n    \"next\": \"^14.0.0\",\n    // ... outras\n  },\n  \"devDependencies\": {\n    \"typescript\": \"^5.3.0\",\n    \"eslint\": \"^8.0.0\",\n    // ... outras\n  }\n}\n```\n\n### 1.3 Configuração TypeScript\n\n```json\n// tsconfig.json - Configuração obrigatória\n{\n  \"compilerOptions\": {\n    \"strict\": true,\n    \"noImplicitAny\": true,\n    \"strictNullChecks\": true,\n    \"noUnusedLocals\": true,\n    \"noUnusedParameters\": true,\n    \"exactOptionalPropertyTypes\": true\n  }\n}\n```\n\n**Regra:** Nenhum `any` permitido sem comentário justificativo.\n\n```typescript\n// ❌ PROIBIDO\nconst data: any = fetchData();\n\n// ✅ PERMITIDO (com justificativa)\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nconst legacyData: any = externalLibrary.getData(); // API legada sem tipos\n```\n\n---\n\n## 2. Estrutura de Diretórios\n\n```\n{projeto}/\n├── src/\n│   ├── app/                    # Pages (App Router) ou routes\n│   ├── components/\n│   │   ├── ui/                 # Componentes base (Button, Input, etc.)\n│   │   ├── features/           # Componentes de features específicas\n│   │   └── layouts/            # Layouts reutilizáveis\n│   ├── hooks/                  # Custom hooks (prefixo use)\n│   ├── lib/                    # Utilitários e helpers\n│   ├── services/               # Integrações com APIs/backends\n│   ├── stores/                 # Estado global (Zustand/Redux/Context)\n│   ├── types/                  # Definições TypeScript\n│   └── styles/                 # Estilos globais\n├── tests/                      # Testes (espelha estrutura de src/)\n├── public/                     # Assets estáticos\n├── docs/                       # Documentação (NUNCA em src/)\n│   ├── planning/               # Docs de planejamento\n│   └── api/                    # Documentação de API\n├── scripts/                    # Scripts de automação\n└── .agents/                     # Framework Inove AI\n```\n\n### Regras de Organização\n\n| Tipo de Arquivo | Localização | Exemplo |\n|-----------------|-------------|---------|\n| Componentes React | `src/components/` | `UserCard.tsx` |\n| Hooks customizados | `src/hooks/` | `useAuth.ts` |\n| Tipos TypeScript | `src/types/` | `user.types.ts` |\n| Utilitários | `src/lib/` | `formatDate.ts` |\n| Serviços/API | `src/services/` | `authService.ts` |\n| Testes | `tests/` ou `__tests__/` | `UserCard.test.tsx` |\n| Documentação | `docs/` | NUNCA em `src/` |\n\n---\n\n## 3. Convenções de Nomenclatura\n\n### 3.1 Arquivos e Pastas\n\n| Tipo | Convenção | Exemplo |\n|------|-----------|---------|\n| Componentes React | PascalCase | `UserProfile.tsx` |\n| Hooks | camelCase + prefixo use | `useAuth.ts` |\n| Utilitários | camelCase | `formatCurrency.ts` |\n| Tipos | camelCase + sufixo .types | `user.types.ts` |\n| Constantes | camelCase ou kebab-case | `constants.ts` |\n| Testes | mesmo nome + .test | `UserProfile.test.tsx` |\n| CSS Modules | kebab-case | `user-profile.module.css` |\n| Pastas | kebab-case | `user-management/` |\n\n### 3.2 Código\n\n| Tipo | Convenção | Exemplo |\n|------|-----------|---------|\n| Variáveis | camelCase | `userName`, `isLoading` |\n| Constantes | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT`, `API_URL` |\n| Funções | camelCase | `getUserById()`, `formatDate()` |\n| Classes | PascalCase | `UserService`, `AuthError` |\n| Interfaces | PascalCase + prefixo I (opcional) | `User` ou `IUser` |\n| Types | PascalCase | `UserRole`, `ApiResponse` |\n| Enums | PascalCase | `UserStatus.Active` |\n| Componentes | PascalCase | `<UserCard />` |\n| Props | PascalCase + sufixo Props | `UserCardProps` |\n| Hooks | camelCase + prefixo use | `useAuth()` |\n| Eventos | camelCase + prefixo handle/on | `handleClick`, `onSubmit` |\n\n### 3.3 Database (Firestore/SQL)\n\n| Tipo | Convenção | Exemplo |\n|------|-----------|---------|\n| Collections/Tables | snake_case, plural | `user_sessions`, `order_items` |\n| Fields/Columns | camelCase | `createdAt`, `userId` |\n| Índices | idx_{table}_{columns} | `idx_users_email` |\n| Foreign Keys | {table}_id | `user_id`, `order_id` |\n\n---\n\n## 4. Padrões de Código\n\n### 4.1 Componentes React\n\n```tsx\n// ✅ Estrutura padrão de componente\nimport { type FC } from 'react';\nimport { cn } from '@/lib/utils';\n\ninterface UserCardProps {\n  user: User;\n  variant?: 'default' | 'compact';\n  onSelect?: (user: User) => void;\n}\n\nexport const UserCard: FC<UserCardProps> = ({\n  user,\n  variant = 'default',\n  onSelect,\n}) => {\n  // 1. Hooks primeiro\n  const [isHovered, setIsHovered] = useState(false);\n\n  // 2. Handlers\n  const handleClick = useCallback(() => {\n    onSelect?.(user);\n  }, [onSelect, user]);\n\n  // 3. Render helpers (se necessário)\n  const renderBadge = () => {\n    if (!user.isPremium) return null;\n    return <Badge variant=\"premium\">Premium</Badge>;\n  };\n\n  // 4. Return JSX\n  return (\n    <div\n      className={cn(\n        'rounded-lg border p-4',\n        variant === 'compact' && 'p-2'\n      )}\n      onClick={handleClick}\n    >\n      <h3>{user.name}</h3>\n      {renderBadge()}\n    </div>\n  );\n};\n```\n\n### 4.2 Custom Hooks\n\n```tsx\n// ✅ Estrutura padrão de hook\nimport { useState, useEffect, useCallback } from 'react';\n\ninterface UseAuthReturn {\n  user: User | null;\n  isLoading: boolean;\n  error: Error | null;\n  login: (credentials: Credentials) => Promise<void>;\n  logout: () => Promise<void>;\n}\n\nexport function useAuth(): UseAuthReturn {\n  const [user, setUser] = useState<User | null>(null);\n  const [isLoading, setIsLoading] = useState(true);\n  const [error, setError] = useState<Error | null>(null);\n\n  useEffect(() => {\n    // Setup subscription\n    const unsubscribe = authService.onAuthChange(setUser);\n    setIsLoading(false);\n    return () => unsubscribe();\n  }, []);\n\n  const login = useCallback(async (credentials: Credentials) => {\n    setIsLoading(true);\n    setError(null);\n    try {\n      const user = await authService.login(credentials);\n      setUser(user);\n    } catch (err) {\n      setError(err instanceof Error ? err : new Error('Login failed'));\n      throw err;\n    } finally {\n      setIsLoading(false);\n    }\n  }, []);\n\n  const logout = useCallback(async () => {\n    await authService.logout();\n    setUser(null);\n  }, []);\n\n  return { user, isLoading, error, login, logout };\n}\n```\n\n### 4.3 Services\n\n```tsx\n// ✅ Estrutura padrão de service\nimport { z } from 'zod';\nimport { db } from '@/lib/firebase';\n\n// Schema de validação\nconst UserSchema = z.object({\n  id: z.string().uuid(),\n  email: z.string().email(),\n  name: z.string().min(2).max(100),\n  role: z.enum(['user', 'admin']),\n});\n\ntype User = z.infer<typeof UserSchema>;\n\nexport const userService = {\n  async getById(id: string): Promise<User | null> {\n    const doc = await db.collection('users').doc(id).get();\n    if (!doc.exists) return null;\n\n    const data = doc.data();\n    return UserSchema.parse({ id: doc.id, ...data });\n  },\n\n  async create(input: Omit<User, 'id'>): Promise<User> {\n    // Valida input\n    const validated = UserSchema.omit({ id: true }).parse(input);\n\n    // Cria documento\n    const ref = await db.collection('users').add({\n      ...validated,\n      createdAt: new Date(),\n    });\n\n    return { id: ref.id, ...validated };\n  },\n\n  async update(id: string, input: Partial<User>): Promise<void> {\n    const validated = UserSchema.partial().parse(input);\n    await db.collection('users').doc(id).update({\n      ...validated,\n      updatedAt: new Date(),\n    });\n  },\n};\n```\n\n---\n\n## 5. Validação de Dados\n\n### 5.1 Regra Geral\n\n> **TODA entrada externa DEVE ser validada antes de processamento.**\n\nEntradas externas incluem:\n- Dados de formulários\n- Query parameters\n- Request bodies\n- Dados de APIs externas\n- Dados do localStorage/sessionStorage\n\n### 5.2 Biblioteca Padrão: Zod\n\n```typescript\nimport { z } from 'zod';\n\n// Schema de validação\nconst CreateUserSchema = z.object({\n  email: z.string().email('Email inválido'),\n  password: z.string().min(8, 'Senha deve ter no mínimo 8 caracteres'),\n  name: z.string().min(2).max(100),\n  age: z.number().int().positive().optional(),\n});\n\n// Uso em API route\nexport async function POST(request: Request) {\n  const body = await request.json();\n\n  // Validação\n  const result = CreateUserSchema.safeParse(body);\n\n  if (!result.success) {\n    return Response.json(\n      { error: result.error.flatten() },\n      { status: 400 }\n    );\n  }\n\n  // result.data é tipado e validado\n  const user = await userService.create(result.data);\n  return Response.json(user, { status: 201 });\n}\n```\n\n### 5.3 Validação em Formulários\n\n```tsx\nimport { useForm } from 'react-hook-form';\nimport { zodResolver } from '@hookform/resolvers/zod';\n\nconst formSchema = z.object({\n  email: z.string().email(),\n  password: z.string().min(8),\n});\n\ntype FormData = z.infer<typeof formSchema>;\n\nfunction LoginForm() {\n  const form = useForm<FormData>({\n    resolver: zodResolver(formSchema),\n    defaultValues: { email: '', password: '' },\n  });\n\n  const onSubmit = (data: FormData) => {\n    // data já está validado e tipado\n  };\n\n  return (\n    <form onSubmit={form.handleSubmit(onSubmit)}>\n      {/* ... */}\n    </form>\n  );\n}\n```\n\n---\n\n## 6. Tratamento de Erros\n\n### 6.1 Estrutura de Erro Padrão\n\n```typescript\n// types/errors.ts\ninterface AppError {\n  code: string;           // Ex: 'AUTH_001', 'DB_002'\n  message: string;        // Mensagem técnica (para logs/devs)\n  userMessage: string;    // Mensagem amigável (para UI)\n  details?: unknown;      // Dados adicionais\n  stack?: string;         // Stack trace (apenas em dev)\n}\n\n// Códigos de erro por categoria\nconst ErrorCodes = {\n  // Autenticação (AUTH_XXX)\n  AUTH_001: 'Token expirado',\n  AUTH_002: 'Credenciais inválidas',\n  AUTH_003: 'Permissão negada',\n\n  // Database (DB_XXX)\n  DB_001: 'Registro não encontrado',\n  DB_002: 'Violação de constraint',\n\n  // Validação (VAL_XXX)\n  VAL_001: 'Dados inválidos',\n  VAL_002: 'Campo obrigatório',\n\n  // External (EXT_XXX)\n  EXT_001: 'API externa indisponível',\n  EXT_002: 'Rate limit atingido',\n} as const;\n```\n\n### 6.2 Lançando Erros\n\n```typescript\n// ✅ Correto\nthrow new AppError({\n  code: 'AUTH_001',\n  message: 'JWT token expired at 2024-01-15T10:30:00Z',\n  userMessage: 'Sua sessão expirou. Por favor, faça login novamente.',\n});\n\n// ❌ Evitar\nthrow new Error('Token expired');  // Sem contexto\nthrow 'Something went wrong';      // Nunca throw string\n```\n\n### 6.3 Capturando Erros\n\n```typescript\n// Em services\nasync function fetchUser(id: string) {\n  try {\n    const response = await api.get(`/users/${id}`);\n    return response.data;\n  } catch (error) {\n    if (error instanceof AxiosError) {\n      if (error.response?.status === 404) {\n        throw new AppError({\n          code: 'DB_001',\n          message: `User ${id} not found`,\n          userMessage: 'Usuário não encontrado',\n        });\n      }\n    }\n    // Re-throw erros desconhecidos\n    throw error;\n  }\n}\n```\n\n---\n\n## 7. Segurança\n\n### 7.1 Princípio Fundamental\n\n> **NUNCA confie no cliente. Valide TUDO no servidor.**\n\n### 7.2 Checklist de Segurança\n\n- [ ] Validar TODOS os inputs no backend\n- [ ] Usar prepared statements/parameterized queries\n- [ ] Sanitizar outputs (XSS)\n- [ ] Implementar rate limiting\n- [ ] Usar HTTPS em produção\n- [ ] Não expor stack traces em produção\n- [ ] Não logar dados sensíveis\n- [ ] Usar variáveis de ambiente para secrets\n\n### 7.3 Dados Sensíveis\n\n| Dado | Tratamento |\n|------|------------|\n| Senhas | NUNCA armazenar em plain text. Usar bcrypt/argon2 |\n| Tokens de API | Variáveis de ambiente. NUNCA no código |\n| PII (emails, CPF) | Mascarar em logs: `j***@email.com` |\n| Cartões de crédito | Usar tokenização. NUNCA armazenar completo |\n\n### 7.4 Autenticação\n\n```typescript\n// ✅ Verificar auth em TODA rota protegida\nexport async function GET(request: Request) {\n  const session = await getSession(request);\n\n  if (!session?.user) {\n    return Response.json(\n      { error: 'Unauthorized' },\n      { status: 401 }\n    );\n  }\n\n  // Verificar permissões específicas\n  if (!hasPermission(session.user, 'read:users')) {\n    return Response.json(\n      { error: 'Forbidden' },\n      { status: 403 }\n    );\n  }\n\n  // Continuar...\n}\n```\n\n---\n\n## 8. Git Workflow\n\n### 8.1 Branches\n\n| Branch | Propósito | Proteção |\n|--------|-----------|----------|\n| `main` | Produção | Protected, require PR |\n| `develop` | Staging/Preview | Protected |\n| `feature/*` | Novas features | - |\n| `fix/*` | Bug fixes | - |\n| `hotfix/*` | Fixes urgentes em prod | Merge direto em main |\n\n### 8.2 Nomenclatura de Branch\n\n```\nfeature/STORY-1.1-user-authentication\nfix/ISSUE-123-login-redirect-bug\nhotfix/critical-payment-error\nchore/update-dependencies\ndocs/add-api-documentation\n```\n\n### 8.3 Conventional Commits\n\n```\n<type>(<scope>): <description>\n\n[optional body]\n\n[optional footer]\n```\n\n**Types:**\n| Type | Descrição |\n|------|-----------|\n| `feat` | Nova feature |\n| `fix` | Bug fix |\n| `docs` | Documentação |\n| `style` | Formatação (não afeta código) |\n| `refactor` | Refatoração |\n| `test` | Adição/modificação de testes |\n| `chore` | Tarefas de manutenção |\n| `perf` | Melhorias de performance |\n\n**Exemplos:**\n```\nfeat(auth): add Google OAuth login\nfix(dashboard): correct chart rendering on mobile\ndocs(readme): update installation instructions\nrefactor(api): extract validation middleware\ntest(users): add unit tests for UserService\nchore(deps): update react to v18.3\n```\n\n### 8.4 Pre-commit Hooks\n\n```bash\n# .husky/pre-commit\nnpm run lint\nnpm run type-check\nnpm run test:changed\n```\n\n---\n\n## 9. Testes\n\n### 9.1 Estratégia\n\n| Tipo | Cobertura | Ferramentas |\n|------|-----------|-------------|\n| Unit | 80%+ de funções/hooks | Jest/Vitest |\n| Integration | Fluxos críticos | Testing Library |\n| E2E | Happy paths principais | Playwright/Cypress |\n\n### 9.2 Estrutura de Teste\n\n```typescript\n// UserCard.test.tsx\nimport { render, screen, fireEvent } from '@testing-library/react';\nimport { UserCard } from './UserCard';\n\ndescribe('UserCard', () => {\n  const mockUser = {\n    id: '1',\n    name: 'John Doe',\n    email: 'john@example.com',\n  };\n\n  it('renders user name', () => {\n    render(<UserCard user={mockUser} />);\n    expect(screen.getByText('John Doe')).toBeInTheDocument();\n  });\n\n  it('calls onSelect when clicked', () => {\n    const onSelect = jest.fn();\n    render(<UserCard user={mockUser} onSelect={onSelect} />);\n\n    fireEvent.click(screen.getByRole('article'));\n\n    expect(onSelect).toHaveBeenCalledWith(mockUser);\n  });\n\n  describe('when user is premium', () => {\n    it('shows premium badge', () => {\n      render(<UserCard user={{ ...mockUser, isPremium: true }} />);\n      expect(screen.getByText('Premium')).toBeInTheDocument();\n    });\n  });\n});\n```\n\n### 9.3 Convenções\n\n- Arquivos de teste: `*.test.ts` ou `*.spec.ts`\n- Localização: junto ao arquivo ou em `__tests__/`\n- Nomenclatura: descreva o comportamento, não a implementação\n\n```typescript\n// ✅ Bom\nit('shows error message when email is invalid')\nit('disables submit button while loading')\n\n// ❌ Ruim\nit('sets error state to true')\nit('calls setIsLoading(true)')\n```\n\n---\n\n## 10. Ambiente de Desenvolvimento\n\n### 10.1 Variáveis de Ambiente\n\n```bash\n# .env.local (NUNCA commitar)\nDATABASE_URL=postgresql://...\nAPI_SECRET_KEY=sk-...\nNEXT_PUBLIC_API_URL=http://localhost:3000/api\n\n# .env.example (commitar - template)\nDATABASE_URL=postgresql://user:pass@localhost:5432/db\nAPI_SECRET_KEY=your-secret-key-here\nNEXT_PUBLIC_API_URL=http://localhost:3000/api\n```\n\n**Regras:**\n- Prefixo `NEXT_PUBLIC_` para variáveis expostas ao cliente\n- NUNCA commitar `.env.local` ou `.env.production`\n- SEMPRE manter `.env.example` atualizado\n\n### 10.2 Scripts NPM\n\n```json\n{\n  \"scripts\": {\n    \"dev\": \"next dev\",\n    \"build\": \"next build\",\n    \"start\": \"next start\",\n    \"lint\": \"eslint . --ext .ts,.tsx\",\n    \"lint:fix\": \"eslint . --ext .ts,.tsx --fix\",\n    \"type-check\": \"tsc --noEmit\",\n    \"test\": \"vitest\",\n    \"test:watch\": \"vitest --watch\",\n    \"test:coverage\": \"vitest --coverage\",\n    \"e2e\": \"playwright test\",\n    \"validate\": \"npm run lint && npm run type-check && npm run test\"\n  }\n}\n```\n\n---\n\n## Changelog\n\n| Data | Versão | Alterações |\n|------|--------|------------|\n| {YYYY-MM-DD} | 1.0 | Documento inicial |\n```\n\n---\n\n## Pós-Execução\n\n```markdown\n## 📋 Project Context Criado!\n\n**Arquivo:** `docs/PROJECT-CONTEXT.md`\n\n### O que foi documentado:\n- Stack técnica e versões\n- Estrutura de diretórios\n- Convenções de nomenclatura\n- Padrões de código (componentes, hooks, services)\n- Validação de dados\n- Tratamento de erros\n- Regras de segurança\n- Git workflow\n- Estratégia de testes\n- Ambiente de desenvolvimento\n\n### Próximos Passos:\n1. Revisar e ajustar conforme preferências do time\n2. Compartilhar com todos os desenvolvedores\n3. Configurar linters/formatters para enforcement automático\n4. Adicionar ao onboarding de novos membros\n```\n",
     "create": "---\ndescription: Create new application command. Triggers App Builder skill and starts interactive dialogue with user.\n---\n\n# /create - Create Application\n\n$ARGUMENTS\n\n---\n\n## Regras Críticas\n\n1. **ANÁLISE PRIMEIRO** — Sempre entender o pedido do usuário antes de gerar código.\n2. **APROVAÇÃO OBRIGATÓRIA** — Apresentar o plano ao usuário e aguardar confirmação antes de construir.\n3. **AGENTES ESPECIALIZADOS** — Delegar para agentes corretos (database-architect, backend-specialist, frontend-specialist).\n4. **PREVIEW AUTOMÁTICO** — Ao finalizar, iniciar preview para o usuário validar visualmente.\n5. **PADRÕES DO PROJETO** — Respeitar tech stack e convenções definidas no projeto.\n\n## Fluxo de Execução\n\nThis command starts a new application creation process.\n\n### Steps:\n\n1. **Request Analysis**\n   - Understand what the user wants\n   - If information is missing, use `brainstorming` skill to ask\n\n2. **Project Planning**\n   - Use `project-planner` agent for task breakdown\n   - Determine tech stack\n   - Plan file structure\n   - Create plan file and proceed to building\n\n3. **Application Building (After Approval)**\n   - Orchestrate with `app-builder` skill\n   - Coordinate expert agents:\n     - `database-architect` → Schema\n     - `backend-specialist` → API\n     - `frontend-specialist` → UI\n\n4. **Preview**\n   - Start with `auto_preview.py` when complete\n   - Present URL to user\n\n---\n\n## Usage Examples\n\n```\n/create blog site\n/create e-commerce app with product listing and cart\n/create todo app\n/create Instagram clone\n/create crm system with customer management\n```\n\n---\n\n## Before Starting\n\nIf request is unclear, ask these questions:\n- What type of application?\n- What are the basic features?\n- Who will use it?\n\nUse defaults, add details later.\n",
     "debug": "---\ndescription: Debugging command. Activates DEBUG mode for systematic problem investigation.\n---\n\n# /debug - Systematic Problem Investigation\n\n$ARGUMENTS\n\n---\n\n## Purpose\n\nThis command activates DEBUG mode for systematic investigation of issues, errors, or unexpected behavior.\n\n---\n\n## Regras Críticas\n\n1. **PERGUNTAR ANTES DE ASSUMIR** — Coletar contexto completo do erro antes de investigar.\n2. **HIPÓTESES ORDENADAS** — Listar causas possíveis por ordem de probabilidade.\n3. **MÉTODO ELIMINATÓRIO** — Testar cada hipótese sistematicamente, nunca adivinhar.\n4. **EXPLICAR A CAUSA RAIZ** — Não apenas corrigir, mas explicar o porquê do problema.\n5. **PREVENIR RECORRÊNCIA** — Adicionar testes ou validações para evitar o mesmo bug no futuro.\n\n## Fluxo de Execução\n\nWhen `/debug` is triggered:\n\n1. **Gather information**\n   - Error message\n   - Reproduction steps\n   - Expected vs actual behavior\n   - Recent changes\n\n2. **Form hypotheses**\n   - List possible causes\n   - Order by likelihood\n\n3. **Investigate systematically**\n   - Test each hypothesis\n   - Check logs, data flow\n   - Use elimination method\n\n4. **Fix and prevent**\n   - Apply fix\n   - Explain root cause\n   - Add prevention measures\n\n---\n\n## Output Format\n\n```markdown\n## 🔍 Debug: [Issue]\n\n### 1. Symptom\n[What's happening]\n\n### 2. Information Gathered\n- Error: `[error message]`\n- File: `[filepath]`\n- Line: [line number]\n\n### 3. Hypotheses\n1. ❓ [Most likely cause]\n2. ❓ [Second possibility]\n3. ❓ [Less likely cause]\n\n### 4. Investigation\n\n**Testing hypothesis 1:**\n[What I checked] → [Result]\n\n**Testing hypothesis 2:**\n[What I checked] → [Result]\n\n### 5. Root Cause\n🎯 **[Explanation of why this happened]**\n\n### 6. Fix\n```[language]\n// Before\n[broken code]\n\n// After\n[fixed code]\n```\n\n### 7. Prevention\n🛡️ [How to prevent this in the future]\n```\n\n---\n\n## Examples\n\n```\n/debug login not working\n/debug API returns 500\n/debug form doesn't submit\n/debug data not saving\n```\n\n---\n\n## Key Principles\n\n- **Ask before assuming** - get full error context\n- **Test hypotheses** - don't guess randomly\n- **Explain why** - not just what to fix\n- **Prevent recurrence** - add tests, validation\n",
-    "define": "---\ndescription: Cria documentacao de projeto estruturada em 9 etapas (Brief, PRD, UX Concept, Architecture, Security, Stack, Design System, Backlog) com GAP Analysis integrada usando agentes especializados.\n---\n\n# Workflow: /define\n\n> **Proposito:** Planejamento completo e PRECISO para projetos \"do zero\". Gera documentacao tecnica detalhada, acionavel e com GAP Analysis integrada em cada dimensao.\n\n## Regras Criticas\n\n1. **NAO ESCREVA CODIGO** — Este workflow gera apenas documentacao.\n2. **SEQUENCIAL** — Cada documento depende dos anteriores.\n3. **SOCRATIC GATE OBRIGATORIO** — Pergunte ANTES de criar.\n4. **PRECISAO TECNICA** — Documentos devem ser especificos, nao genericos.\n5. **VALIDACAO CONTINUA** — Confirme entendimento antes de cada fase.\n6. **GAP ANALYSIS OBRIGATORIO** — Todos os documentos (exceto Brief) DEVEM incluir secao de GAP.\n7. **REVISAO POS-GERACAO** — Documentos gerados pelo Antigravity DEVEM ser revisados por Claude Code/Codex usando a skill `doc-review`.\n\n---\n\n## Estrutura de Documentos\n\n| Fase | Documento | Agente | Skills | GAP |\n|------|-----------|--------|--------|-----|\n| 0 | Discovery | (entrevista) | brainstorming | - |\n| 1 | Brief | `product-manager` | brainstorming, plan-writing | Nenhum |\n| 2 | PRD | `product-owner` | plan-writing, gap-analysis | Produto/Negocio |\n| 3 | UX Concept | `ux-researcher` | ux-research, frontend-design, gap-analysis | Experiencia |\n| 3.5 | Visual Mockups | `frontend-specialist` | stitch-ui-design, frontend-design | Visual |\n| 4 | Architecture | `project-planner` | architecture, system-design, gap-analysis | Infraestrutura |\n| 5 | Security | `security-auditor` | vulnerability-scanner, gap-analysis | Seguranca |\n| 6 | Stack | `project-planner` | app-builder, architecture, gap-analysis | Tecnologia |\n| 7 | Design System | `frontend-specialist` | frontend-design, tailwind-patterns, gap-analysis | Design |\n| 8 | Backlog | `product-owner` | plan-writing, gap-analysis | Consolidacao |\n\n---\n\n## Fluxo de Execucao\n\n### Fase 0: Setup e Discovery (OBRIGATORIO)\n\n> **Objetivo:** Criar a estrutura organizacional de documentacao e extrair informacoes do projeto.\n\n**1. Setup da Estrutura de Documentacao**\n\nAntes de qualquer pergunta, execute:\n\n```bash\nmkdir -p docs/00-Contexto docs/01-Planejamento docs/02-Requisitos docs/03-Arquitetura/ADRs docs/04-API docs/08-Logs-Sessoes\necho \"# Documentacao de Planejamento\" > docs/01-Planejamento/README.md\n```\n\n> **Nota:** O `/define` cria a estrutura numerada (`docs/01-Planejamento/`). Projetos que nao passaram pelo `/define` podem usar `docs/planning/`. Ambos sao aceitos — ver tabela de aliases em `INSTRUCTIONS.md`.\n\n**Estrutura Alvo:**\n- `docs/00-Contexto/` (Context, Readiness)\n- `docs/01-Planejamento/` (Brief, PRD, UX Concept, Architecture, Stack, Design System)\n- `docs/02-Requisitos/` (Stories, Journeys)\n- `docs/03-Arquitetura/` (ADRs, Diagramas)\n- `docs/08-Logs-Sessoes/` (Logs diarios)\n\n---\n\n**2. Entrevista de Discovery**\n\nConduza a entrevista estruturada:\n\n```markdown\n## Discovery: Entendendo Seu Projeto\n\nVou fazer algumas perguntas para garantir que a documentacao seja precisa e util.\n\n### Bloco 1: Problema e Contexto\n1. **Qual problema especifico este sistema resolve?**\n   - Descreva uma situacao real onde esse problema acontece\n\n2. **Como esse problema e resolvido hoje (se existir solucao atual)?**\n   - Quais sao as limitacoes da solucao atual?\n\n### Bloco 2: Usuarios e Casos de Uso\n3. **Quem sao os usuarios principais?** (Seja especifico)\n   - Exemplo: \"Gerentes de RH em empresas de 50-200 funcionarios\" vs \"usuarios\"\n\n4. **Descreva 3 cenarios de uso tipicos:**\n   - Cenario 1: [Quem] quer [fazer o que] para [alcancar qual resultado]\n   - Cenario 2: ...\n   - Cenario 3: ...\n\n### Bloco 3: Funcionalidades Core\n5. **Liste as 5 funcionalidades ESSENCIAIS do MVP (em ordem de prioridade):**\n   - Para cada uma, descreva o que o usuario deve conseguir fazer\n\n6. **O que NAO faz parte do MVP?** (Igualmente importante)\n   - Funcionalidades que podem esperar versoes futuras\n\n### Bloco 4: Restricoes Tecnicas\n7. **Stack tecnica preferida ou obrigatoria:**\n   - Frontend: (React, Vue, Next.js, etc.)\n   - Backend: (Node, Python, etc.)\n   - Database: (PostgreSQL, MongoDB, Firebase, etc.)\n   - Hosting: (Vercel, AWS, etc.)\n\n8. **Integracoes obrigatorias:**\n   - APIs externas (pagamento, email, auth, etc.)\n   - Sistemas legados\n\n### Bloco 5: Contexto de Negocio\n9. **Modelo de monetizacao (se aplicavel):**\n   - Free, Freemium, Subscription, One-time, etc.\n\n10. **Metricas de sucesso (como saberemos que funcionou?):**\n    - Metricas quantitativas (ex: 100 usuarios em 30 dias)\n    - Metricas qualitativas (ex: NPS > 8)\n\n### Bloco 6: Contexto Existente (Para GAP Analysis)\n11. **Existe algo ja construido?** (codigo, prototipos, docs)\n    - Se sim: qual o estado atual? O que funciona? O que nao funciona?\n    - Se nao: e um projeto 100% greenfield?\n\n12. **Existem sistemas legados que precisam ser considerados?**\n    - Integracoes obrigatorias com sistemas existentes\n    - Migracoes de dados necessarias\n\n13. **O projeto tem interface visual (web, mobile, desktop)?**\n    - Se sim: quais tipos de tela? (dashboard, landing, formularios, etc.)\n    - Se nao: e uma API pura, CLI tool, ou backend-only?\n    - **Guardar resposta como flag `HAS_UI=true/false`**\n```\n\n**REGRA:** NAO prossiga ate ter respostas claras para TODAS as perguntas.\n\nSe o usuario for vago, faca follow-up:\n```markdown\nPreciso de mais detalhes sobre [X]. Voce mencionou \"[resposta vaga]\", mas:\n- Quantos [usuarios/registros/etc] voce espera?\n- Com que frequencia [acao] acontece?\n- Qual e o impacto se [cenario de falha]?\n```\n\n---\n\n### Fase 1: Product Brief\n\n**Agente:** `product-manager`\n**Output:** `docs/01-Planejamento/01-product-brief.md`\n**Skills:** `brainstorming`, `plan-writing`\n\n```markdown\n# Product Brief: {Nome do Projeto}\n\n## Metadados\n- **Data de criacao:** {YYYY-MM-DD}\n- **Autor:** AI Product Manager\n- **Versao:** 1.0\n- **Status:** Draft | Em Revisao | Aprovado\n\n---\n\n## 1. Visao do Produto\n\n### 1.1 Declaracao de Visao\n> \"Para [PUBLICO-ALVO] que [TEM NECESSIDADE], o [NOME DO PRODUTO] e um [CATEGORIA] que [BENEFICIO PRINCIPAL]. Diferente de [ALTERNATIVA], nosso produto [DIFERENCIAL].\"\n\n### 1.2 Elevator Pitch (30 segundos)\n[Versao expandida da visao para apresentacao rapida]\n\n---\n\n## 2. Problema\n\n### 2.1 Declaracao do Problema\n| Aspecto | Descricao |\n|---------|-----------|\n| **O problema** | [Descricao especifica] |\n| **Afeta** | [Quem sofre com isso - seja especifico] |\n| **O impacto e** | [Consequencias mensuraveis] |\n| **Hoje e resolvido por** | [Solucoes atuais e suas limitacoes] |\n\n### 2.2 Evidencias do Problema\n- [Dado/Estatistica 1 que comprova o problema]\n- [Dado/Estatistica 2]\n- [Citacao/Feedback de usuario potencial]\n\n### 2.3 Consequencias de Nao Resolver\n- Curto prazo: [O que acontece em semanas]\n- Medio prazo: [O que acontece em meses]\n- Longo prazo: [O que acontece em anos]\n\n---\n\n## 3. Solucao\n\n### 3.1 Descricao da Solucao\n[2-3 paragrafos explicando como o produto resolve o problema]\n\n### 3.2 Proposta de Valor Unica (UVP)\n| Diferencial | Como entregamos | Beneficio para usuario |\n|-------------|-----------------|----------------------|\n| [Diferencial 1] | [Implementacao] | [Resultado] |\n| [Diferencial 2] | [Implementacao] | [Resultado] |\n| [Diferencial 3] | [Implementacao] | [Resultado] |\n\n### 3.3 Funcionalidades Core do MVP\n| # | Funcionalidade | Descricao | Justificativa (Por que MVP?) |\n|---|----------------|-----------|------------------------------|\n| 1 | [Nome] | [O que faz] | [Por que e essencial] |\n| 2 | [Nome] | [O que faz] | [Por que e essencial] |\n| 3 | [Nome] | [O que faz] | [Por que e essencial] |\n| 4 | [Nome] | [O que faz] | [Por que e essencial] |\n| 5 | [Nome] | [O que faz] | [Por que e essencial] |\n\n### 3.4 Fora do Escopo (Explicitamente)\n| Funcionalidade | Por que nao esta no MVP | Versao planejada |\n|----------------|-------------------------|------------------|\n| [Feature A] | [Motivo] | v1.1 |\n| [Feature B] | [Motivo] | v2.0 |\n\n---\n\n## 4. Publico-Alvo\n\n### 4.1 Persona Primaria\n| Atributo | Descricao |\n|----------|-----------|\n| **Nome ficticio** | [Ex: \"Carlos, o RH Sobrecarregado\"] |\n| **Cargo/Papel** | [Funcao especifica] |\n| **Empresa/Contexto** | [Tamanho, setor, regiao] |\n| **Objetivos** | [O que quer alcancar] |\n| **Frustracoes** | [Dores atuais] |\n| **Comportamento digital** | [Como usa tecnologia] |\n| **Quote caracteristica** | [\"Frase que essa pessoa diria\"] |\n\n### 4.2 Persona Secundaria (se houver)\n[Mesmo formato]\n\n### 4.3 Anti-Persona (Quem NAO e nosso usuario)\n[Descreva quem nao deve usar o produto e por que]\n\n---\n\n## 5. Metricas de Sucesso\n\n### 5.1 North Star Metric\n> **A unica metrica que define sucesso:** [Metrica + meta]\n\n### 5.2 Metricas de Acompanhamento\n| Categoria | Metrica | Meta MVP | Como medir |\n|-----------|---------|----------|------------|\n| **Aquisicao** | [Ex: Sign-ups/semana] | [Ex: 50] | [Ferramenta] |\n| **Ativacao** | [Ex: % que completa onboarding] | [Ex: 60%] | [Ferramenta] |\n| **Retencao** | [Ex: % volta em 7 dias] | [Ex: 40%] | [Ferramenta] |\n| **Receita** | [Ex: MRR] | [Ex: $1000] | [Ferramenta] |\n| **Referencia** | [Ex: NPS] | [Ex: > 30] | [Ferramenta] |\n\n### 5.3 Criterios de Sucesso do MVP\nO MVP sera considerado bem-sucedido se:\n- [ ] [Criterio 1 - especifico e mensuravel]\n- [ ] [Criterio 2]\n- [ ] [Criterio 3]\n\n---\n\n## 6. Riscos e Mitigacoes\n\n| Risco | Probabilidade | Impacto | Mitigacao |\n|-------|---------------|---------|-----------|\n| [Risco tecnico 1] | Alta/Media/Baixa | Alto/Medio/Baixo | [Plano] |\n| [Risco de mercado 1] | Alta/Media/Baixa | Alto/Medio/Baixo | [Plano] |\n| [Risco de execucao 1] | Alta/Media/Baixa | Alto/Medio/Baixo | [Plano] |\n\n---\n\n## Aprovacoes\n\n| Papel | Nome | Status | Data |\n|-------|------|--------|------|\n| Product Owner | [Nome/Usuario] | Pendente | - |\n| Tech Lead | [Nome/Usuario] | Pendente | - |\n```\n\n**CHECKPOINT:**\n```markdown\nDocumento gerado: docs/01-Planejamento/01-product-brief.md\n\nPor favor, revise o Product Brief e responda:\n- ok — Aprovar e continuar para PRD\n- editar [secao] — Ajustar secao especifica (ex: \"editar personas\")\n- cancelar — Parar o workflow\n\nPerguntas de validacao:\n1. A visao do produto captura sua ideia corretamente?\n2. As personas representam seus usuarios reais?\n3. As metricas de sucesso sao realistas?\n```\n\n**AGUARDE** resposta antes de prosseguir.\n\n---\n\n### Fase 2: PRD (Product Requirements Document)\n\n**Agente:** `product-owner`\n**Output:** `docs/01-Planejamento/02-prd.md`\n**Skills:** `plan-writing`, `gap-analysis`\n**Referencia:** Leia `01-product-brief.md` antes de comecar\n\n```markdown\n# PRD: {Nome do Projeto}\n\n## Metadados\n- **Baseado em:** 01-product-brief.md\n- **Data:** {YYYY-MM-DD}\n- **Versao:** 1.0\n\n---\n\n## 1. Requisitos Funcionais\n\n### Legenda de Prioridade\n- **P0 (Critico):** Sem isso, o produto nao funciona. Bloqueador de lancamento.\n- **P1 (Importante):** Essencial para a proposta de valor. Pode lancar sem, mas prejudica.\n- **P2 (Desejavel):** Melhora a experiencia, mas nao e essencial para MVP.\n\n---\n\n### RF01: [Nome do Requisito]\n| Campo | Valor |\n|-------|-------|\n| **ID** | RF01 |\n| **Titulo** | [Nome claro e descritivo] |\n| **Descricao** | Como [PERSONA], eu quero [ACAO] para que [BENEFICIO] |\n| **Prioridade** | P0 / P1 / P2 |\n| **Epico relacionado** | [Nome do Epico] |\n\n**Criterios de Aceite (Gherkin):**\n```gherkin\nDADO que [contexto/pre-condicao]\nQUANDO [acao do usuario]\nENTAO [resultado esperado]\nE [resultado adicional se houver]\n```\n\n**Casos de Borda:**\n- [ ] [Cenario limite 1 e comportamento esperado]\n- [ ] [Cenario limite 2 e comportamento esperado]\n\n**Regras de Negocio:**\n- RN01: [Regra especifica]\n- RN02: [Regra especifica]\n\n**Dependencias:**\n- Depende de: [RF## se houver]\n- Bloqueia: [RF## se houver]\n\n---\n\n[Repetir para cada RF]\n\n---\n\n## 2. Requisitos Nao-Funcionais\n\n### RNF01: Performance\n| Aspecto | Requisito | Como medir |\n|---------|-----------|------------|\n| Tempo de carregamento inicial | < 3 segundos (LCP) | Lighthouse |\n| Tempo de resposta de API | < 200ms (p95) | APM |\n| Time to Interactive | < 5 segundos | Lighthouse |\n\n### RNF02: Escalabilidade\n| Aspecto | Requisito MVP | Requisito v1.0 |\n|---------|---------------|----------------|\n| Usuarios simultaneos | [N] | [N] |\n| Requisicoes/minuto | [N] | [N] |\n| Dados armazenados | [N]GB | [N]GB |\n\n### RNF03: Seguranca\n| Requisito | Implementacao |\n|-----------|---------------|\n| Autenticacao | [JWT / Session / OAuth] |\n| Autorizacao | [RBAC / ABAC] |\n| Criptografia em transito | TLS 1.3 |\n| Conformidade | [LGPD / GDPR se aplicavel] |\n\n### RNF04: Acessibilidade\n- **Nivel WCAG:** AA\n- **Leitores de tela:** Compativel\n- **Navegacao por teclado:** Completa\n\n---\n\n## 3. Fluxos de Usuario (User Journeys)\n\n### Fluxo 1: [Nome do Fluxo Principal]\n\n**Objetivo:** [O que o usuario quer alcancar]\n**Persona:** [Qual persona]\n\n```mermaid\nflowchart TD\n    A[Inicio] --> B{Condicao?}\n    B -->|Sim| C[Acao]\n    B -->|Nao| D[Alternativa]\n    C --> E[Resultado]\n```\n\n**Passos detalhados:**\n| # | Acao do Usuario | Resposta do Sistema | Dados envolvidos |\n|---|-----------------|---------------------|------------------|\n| 1 | [Acao] | [Resposta] | [Entidades] |\n\n---\n\n## 4. Regras de Negocio Globais\n\n### RN-G01: [Nome da Regra]\n- **Descricao:** [O que a regra define]\n- **Condicao:** SE [condicao]\n- **Acao:** ENTAO [resultado]\n- **Excecao:** EXCETO QUANDO [excecao]\n- **Afeta:** [Quais RFs sao impactados]\n\n---\n\n## 5. Integracoes\n\n### INT01: [Nome da Integracao]\n| Campo | Valor |\n|-------|-------|\n| **Servico** | [Nome do servico externo] |\n| **Proposito** | [Para que e usado] |\n| **Tipo** | REST API / Webhook / SDK / OAuth |\n| **Autenticacao** | API Key / OAuth2 / JWT |\n| **Rate Limits** | [Limites conhecidos] |\n| **Fallback** | [O que fazer se falhar] |\n\n---\n\n## 6. Matriz de Rastreabilidade\n\n| Requisito | Epico | User Story | Criterio de Teste |\n|-----------|-------|------------|-------------------|\n| RF01 | Epic 1 | Story 1.1 | TC001, TC002 |\n\n---\n\n## 7. GAP Analysis: Produto e Negocio\n\n> Skill: `gap-analysis` — Dimensao: Product/Business\n\n### 7.1 Feature Coverage\n| Feature | Expectativa de Mercado | Estado Atual | GAP | Prioridade |\n|---------|----------------------|--------------|-----|------------|\n| [Feature A] | [O que concorrentes oferecem] | [O que temos] | [Delta] | P0/P1/P2 |\n\n### 7.2 Capability Assessment\n| Capacidade | Nivel Necessario | Nivel Atual | GAP | Esforco |\n|------------|-----------------|-------------|-----|---------|\n| [Capacidade] | [Alvo] | [Atual] | [Delta] | S/M/L/XL |\n\n### 7.3 Metrics GAP\n| Metrica | Valor Atual | Valor Alvo | GAP | Estrategia |\n|---------|------------|------------|-----|-----------|\n| [Metrica] | [Atual ou N/A] | [Alvo] | [Delta] | [Como fechar] |\n\n### 7.4 GAP Inventory\n| ID | Area | AS-IS | TO-BE | GAP | Severidade | Prioridade |\n|----|------|-------|-------|-----|------------|------------|\n| G-PRD-01 | [Area] | [Atual] | [Necessario] | [O que falta] | Critical/High/Medium/Low | P0/P1/P2 |\n\n---\n\n## Glossario\n\n| Termo | Definicao |\n|-------|-----------|\n| [Termo 1] | [Definicao clara] |\n```\n\n**CHECKPOINT:**\n```markdown\nDocumento gerado: docs/01-Planejamento/02-prd.md\n\nPor favor, revise o PRD e responda:\n- ok — Aprovar e continuar para UX Concept\n- editar [requisito] — Ajustar requisito especifico\n- cancelar — Parar o workflow\n\nPerguntas de validacao:\n1. Os requisitos funcionais cobrem todos os cenarios?\n2. Os criterios de aceite sao verificaveis?\n3. Os GAPs de produto sao relevantes?\n```\n\n**AGUARDE** resposta antes de prosseguir.\n\n---\n\n### Fase 3: UX Concept\n\n**Agente:** `ux-researcher`\n**Output:** `docs/01-Planejamento/03-ux-concept.md`\n**Skills:** `ux-research`, `frontend-design`, `gap-analysis`\n**Referencia:** Leia `01-product-brief.md` e `02-prd.md`\n\n```markdown\n# UX Concept: {Nome do Projeto}\n\n## Metadados\n- **Baseado em:** 01-product-brief.md, 02-prd.md\n- **Data:** {YYYY-MM-DD}\n- **Autor:** AI UX Researcher\n- **Versao:** 1.0\n\n---\n\n## 1. Estrategia de UX\n\n### 1.1 Visao da Experiencia\n> [Uma frase descrevendo a experiencia ideal]\n\n### 1.2 Principios de UX\n1. **[Principio]:** [Como se aplica]\n2. **[Principio]:** [Como se aplica]\n3. **[Principio]:** [Como se aplica]\n\n### 1.3 Metricas de Experiencia\n| Metrica | Alvo | Como Medir |\n|---------|------|-----------|\n| Task Success Rate | > 90% | Testes de usabilidade |\n| Tempo na Tarefa Principal | < [N]s | Analytics |\n| Taxa de Erro | < 5% | Logs |\n| SUS Score | > 70 | Survey |\n\n---\n\n## 2. Arquitetura de Informacao\n\n### 2.1 Mapa da Aplicacao\n\n```mermaid\ngraph TD\n    A[Landing] --> B{Autenticado?}\n    B -->|Nao| C[Login/Register]\n    B -->|Sim| D[Dashboard]\n    D --> E[Secao A]\n    D --> F[Secao B]\n    D --> G[Configuracoes]\n```\n\n### 2.2 Padrao de Navegacao\n| Padrao | Justificativa | Lei UX |\n|--------|--------------|--------|\n| [Padrao] | [Por que] | [Lei aplicada] |\n\n### 2.3 Organizacao de Conteudo\n| Secao | Tipos de Conteudo | Prioridade | Frequencia |\n|-------|-------------------|------------|-----------|\n| [Secao] | [Tipos] | Primary/Secondary | Alta/Media/Baixa |\n\n---\n\n## 3. User Flows\n\n### 3.1 Flow: [Fluxo Principal]\n\n**Objetivo:** [O que o usuario quer]\n**Persona:** [Qual persona]\n\n```mermaid\nflowchart TD\n    START([Inicio]) --> A[Tela: Landing]\n    A --> B{Tem conta?}\n    B -->|Sim| C[Tela: Login]\n    B -->|Nao| D[Tela: Registro]\n    C --> E{Valido?}\n    E -->|Sim| F[Tela: Dashboard]\n    E -->|Nao| G[Erro]\n    G --> C\n    D --> H[Onboarding]\n    H --> F\n```\n\n**Passos:**\n| Step | Acao | Resposta | Tela | Lei UX |\n|------|------|---------|------|--------|\n| 1 | [Acao] | [Resposta] | [Tela] | [Lei] |\n\n### 3.2 Fluxos de Erro\n[Cenarios de erro e recuperacao]\n\n---\n\n## 4. Descricoes de Tela (Wireframes Textuais)\n\n### 4.1 Tela: [Nome]\n**Proposito:** [Por que existe]\n**Entrada:** [Como chega]\n**Saida:** [Para onde vai]\n\n**Layout:**\n```\n+--------------------------------------------------+\n| [Header: Logo | Navegacao | Menu Usuario]        |\n+--------------------------------------------------+\n| [Sidebar]  | [Area de Conteudo Principal]         |\n|            |                                      |\n|            | [Titulo da Secao]                    |\n|            | [Conteudo]                            |\n|            |                                      |\n|            | [Barra de Acoes: CTA Primario]       |\n+--------------------------------------------------+\n```\n\n**Elementos:**\n| Elemento | Tipo | Comportamento | Prioridade |\n|----------|------|--------------|------------|\n| [Elemento] | [Tipo] | [Interacao] | Primary/Secondary |\n\n**Estados:**\n| Estado | Trigger | Display |\n|--------|---------|---------|\n| Vazio | Sem dados | [Mensagem + CTA] |\n| Carregando | Fetch | [Skeleton] |\n| Erro | Falha | [Mensagem + retry] |\n| Sucesso | Acao ok | [Confirmacao] |\n\n---\n\n## 5. Avaliacao Heuristica (Nielsen's 10)\n\n| # | Heuristica | Status | Problemas | Severidade (0-4) | Fix |\n|---|-----------|--------|-----------|-------------------|-----|\n| 1 | Visibilidade do Status | Pass/Fail | [Issue] | [0-4] | [Fix] |\n| 2 | Correspondencia Sistema-Mundo | Pass/Fail | [Issue] | [0-4] | [Fix] |\n| 3 | Controle e Liberdade | Pass/Fail | [Issue] | [0-4] | [Fix] |\n| 4 | Consistencia e Padroes | Pass/Fail | [Issue] | [0-4] | [Fix] |\n| 5 | Prevencao de Erros | Pass/Fail | [Issue] | [0-4] | [Fix] |\n| 6 | Reconhecimento vs Memorizacao | Pass/Fail | [Issue] | [0-4] | [Fix] |\n| 7 | Flexibilidade e Eficiencia | Pass/Fail | [Issue] | [0-4] | [Fix] |\n| 8 | Estetica Minimalista | Pass/Fail | [Issue] | [0-4] | [Fix] |\n| 9 | Recuperacao de Erros | Pass/Fail | [Issue] | [0-4] | [Fix] |\n| 10 | Ajuda e Documentacao | Pass/Fail | [Issue] | [0-4] | [Fix] |\n\n---\n\n## 6. Mapa de Friccao\n\n| Fluxo | Passo | Tipo | Severidade (1-5) | Causa | Solucao | Prioridade |\n|-------|-------|------|------------------|-------|---------|------------|\n| [Fluxo] | [Passo] | Cognitiva/Interacao/Emocional | [1-5] | [Causa] | [Fix] | P0/P1/P2 |\n\n---\n\n## 7. Acessibilidade\n\n| Categoria | Criterio | Nivel | Status | Notas |\n|----------|----------|-------|--------|-------|\n| Perceptivel | Contraste 4.5:1 | AA | Pass/Fail | |\n| Operavel | Navegacao teclado | A | Pass/Fail | |\n| Compreensivel | Erros claros | A | Pass/Fail | |\n\n---\n\n## 8. GAP Analysis: Experiencia do Usuario\n\n> Skill: `gap-analysis` — Dimensao: Experience\n\n### 8.1 Flow Assessment\n| User Flow | Estado Atual | Estado Ideal | Friccoes | Severidade |\n|-----------|-------------|-------------|----------|------------|\n| [Fluxo] | [Atual] | [Ideal] | [Friccoes] | Critical/High/Medium/Low |\n\n### 8.2 UX Pattern Coverage\n| Padrao | Standard | Atual | GAP | Impacto |\n|--------|---------|-------|-----|---------|\n| Onboarding | [Best practice] | [O que existe] | [Falta] | High/Medium/Low |\n| Empty States | [Best practice] | [O que existe] | [Falta] | High/Medium/Low |\n\n### 8.3 Accessibility GAP\n| WCAG Criterion | Necessario | Atual | GAP | Fix |\n|----------------|----------|-------|-----|-----|\n| [Criterio] | AA | [Atual] | [Delta] | [Fix] |\n\n### 8.4 GAP Inventory\n| ID | Area | AS-IS | TO-BE | GAP | Severidade | Prioridade |\n|----|------|-------|-------|-----|------------|------------|\n| G-UX-01 | [Area] | [Atual] | [Necessario] | [Falta] | [Severidade] | P0/P1/P2 |\n```\n\n**CHECKPOINT:**\n```markdown\nDocumento gerado: docs/01-Planejamento/03-ux-concept.md\n\nPor favor, revise o UX Concept e responda:\n- ok — Aprovar e continuar para Architecture\n- editar [secao] — Ajustar secao especifica\n- cancelar — Parar o workflow\n```\n\n**AGUARDE** resposta antes de prosseguir.\n\n---\n\n### Fase 3.5: Visual Mockups [OBRIGATORIO se projeto tem UI]\n\n> **SKIP:** Apenas se o projeto NAO tem interface visual (API pura, CLI tool, backend-only).\n> **Para todos os projetos com UI:** Esta fase e OBRIGATORIA. Nao avancar para Fase 4 sem mockups aprovados.\n>\n> **Condicao de Ativacao:** HAS_UI=true (definido na Fase 0, pergunta #13)\n\n**Agente:** `frontend-specialist`\n**Output:** `docs/01-Planejamento/03.5-visual-mockups.md`\n**Skills:** `stitch-ui-design`, `frontend-design`\n**Referencia:** Leia `01-product-brief.md` e `03-ux-concept.md`\n\n**GATE DE BLOQUEIO (INVIOLAVEL):**\n> Se HAS_UI=true, a Fase 4 (Architecture) esta **BLOQUEADA** ate que:\n> 1. O arquivo `docs/01-Planejamento/03.5-visual-mockups.md` exista E tenha conteudo\n> 2. **TODAS** as telas identificadas no UX Concept tenham prototipo correspondente\n> 3. O usuario aprove os mockups com \"ok\"\n>\n> **Cobertura total obrigatoria:** O agente NAO pode se contentar com prototipar 1 ou 2 telas.\n> Cada tela documentada na Section 4 do UX Concept DEVE ter seu prototipo gerado.\n\n**Processo:**\n\n1. **Verificar disponibilidade do Stitch MCP**\n   - Invocar `mcp__stitch__list_projects` para confirmar conectividade\n   - **Se Stitch DISPONIVEL:** Uso e OBRIGATORIO — gerar prototipos via Stitch para TODAS as telas\n   - **Se Stitch NAO DISPONIVEL e HAS_UI=true:** **PARAR** e informar usuario para configurar Stitch MCP antes de continuar\n   - Se HAS_UI=false: pular para Fase 4\n\n2. **Extrair lista completa de telas**\n   - Ler Section 4 do UX Concept (Descricoes de Tela / Wireframes Textuais)\n   - Ler Section 3 (User Flows) para identificar telas referenciadas nos fluxos\n   - Ler PRD Section 3 (Fluxos de Usuario) para telas de edge case\n   - **Montar lista exaustiva:** Cada tela = 1 item obrigatorio para prototipagem\n   - Incluir telas de estado: Empty, Error, Loading, Success (para telas criticas)\n   - Incluir telas de edge case: 404, Offline, Permission Denied (se documentadas)\n\n3. **Criar projeto Stitch**\n   - Invocar `mcp__stitch__create_project` com titulo do projeto\n   - Registrar Project ID\n\n4. **Converter wireframes em prompts**\n   - Carregar skill `stitch-ui-design` → ler `wireframe-to-prompt.md`\n   - Aplicar algoritmo de conversao de 7 passos para CADA tela da lista\n\n5. **Gerar TODAS as telas via Stitch**\n   - Telas-chave (Dashboard, Landing, Onboarding): GEMINI_3_PRO + MOBILE + DESKTOP\n   - Telas secundarias (Settings, Lists, Forms): GEMINI_3_FLASH + MOBILE\n   - Respeitar regras anti-cliche do `@frontend-specialist`\n   - **NAO parar ate que todas as telas da lista estejam geradas**\n\n6. **Validar cobertura (OBRIGATORIO antes do checkpoint)**\n   - Comparar lista de telas extraida (passo 2) com telas geradas (passo 5)\n   - Se alguma tela da lista NAO tem prototipo: **GERAR** antes de prosseguir\n   - Preencher tabela de cobertura no documento de output (ver template abaixo)\n\n6. **Documentar resultados**\n   - Criar arquivo de output com template abaixo\n\n```markdown\n# Visual Mockups: {Nome do Projeto}\n\n## Metadados\n- **Baseado em:** 03-ux-concept.md\n- **Data:** {YYYY-MM-DD}\n- **Autor:** AI Frontend Specialist (via Stitch MCP)\n- **Stitch Project ID:** {project_id}\n\n---\n\n## Telas Geradas\n\n| # | Tela | Device | Screen ID | Modelo | Status |\n|---|------|--------|-----------|--------|--------|\n| 1 | [Nome] | MOBILE | [id] | PRO | Pendente |\n| 2 | [Nome] | DESKTOP | [id] | FLASH | Pendente |\n\n---\n\n## Cobertura\n\n| Tela do UX Concept | MOBILE | DESKTOP | Estados |\n|---------------------|--------|---------|---------|\n| [Tela 1] | Sim | Sim | Success |\n| [Tela 2] | Sim | Nao | Success, Empty |\n\n---\n\n## Insights para Design System\n\n- **Cor primaria observada:** [cor dos mockups]\n- **Estilo tipografico:** [serif/sans/display]\n- **Geometria:** [sharp/rounded/mixed]\n- **Padroes notaveis:** [padroes de UI dos mockups]\n\n---\n\n## Notas\n- Mockups sao referencia visual, nao source of truth\n- Design System (Fase 7) formaliza as decisoes de design\n- IDs de telas podem ser usados para iteracao futura via Stitch\n```\n\n**CHECKPOINT:**\n```markdown\nDocumento gerado: docs/01-Planejamento/03.5-visual-mockups.md\n\n**Cobertura de Telas:**\n- Total de telas no UX Concept: [N]\n- Telas prototipadas via Stitch: [N]\n- Cobertura: [N/N] = [100%]\n\nForam geradas [N] telas visuais via Stitch MCP.\n\nPor favor, revise os mockups e responda:\n- ok — Aprovar e continuar para Architecture\n- refinar [tela] — Regenerar tela especifica com feedback\n- faltou [tela] — Adicionar tela que nao foi prototipada\n- cancelar — Parar o workflow\n\n> **GATE DE BLOQUEIO:** Se cobertura < 100%, BLOQUEAR avanco para Fase 4.\n> Gerar telas faltantes antes de pedir aprovacao.\n```\n\n**AGUARDE** resposta antes de prosseguir.\n\n---\n\n### Fase 4: Architecture\n\n**Agente:** `project-planner`\n**Output:** `docs/01-Planejamento/04-architecture.md`\n**Skills:** `architecture`, `system-design`, `gap-analysis`\n**Referencia:** Leia todos os documentos anteriores\n\n```markdown\n# Architecture: {Nome do Projeto}\n\n## Metadados\n- **Baseado em:** Brief, PRD, UX Concept\n- **Data:** {YYYY-MM-DD}\n- **Versao:** 1.0\n\n---\n\n## 1. System Context (C4 Level 1)\n\n### 1.1 Atores\n| Ator | Tipo | Descricao | Interacao |\n|------|------|-----------|-----------|\n| [Ator] | Pessoa/Sistema | [Quem] | [Como interage] |\n\n### 1.2 Sistemas Externos\n| Sistema | Protocolo | Dados Trocados |\n|---------|----------|----------------|\n| [Sistema] | REST/gRPC | [Dados] |\n\n### 1.3 Diagrama de Contexto\n```mermaid\ngraph TB\n    U[Usuario] -->|HTTPS| S[Sistema]\n    S -->|REST| E1[API Externa]\n    S -->|SQL| DB[(Database)]\n```\n\n---\n\n## 2. Container Diagram (C4 Level 2)\n\n| Container | Tecnologia | Proposito | Comunica Com |\n|-----------|------------|---------|--------------|\n| Web App | [Tech] | UI | API Server |\n| API Server | [Tech] | Logica | Database |\n| Database | [Tech] | Storage | API Server |\n\n```mermaid\ngraph TB\n    WEB[Web App] -->|HTTPS| API[API Server]\n    API --> DB[(Database)]\n    API --> CACHE[(Cache)]\n```\n\n---\n\n## 3. Padrao Arquitetural\n\n### 3.1 Decisoes\n| Aspecto | Decisao | Justificativa |\n|---------|---------|---------------|\n| Padrao | [Monolith/Microservices/etc.] | [Por que] |\n| Comunicacao | [REST/GraphQL/gRPC] | [Por que] |\n| Renderizacao | [SSR/SSG/SPA] | [Por que] |\n\n### 3.2 ADRs\n\n#### ADR-001: [Titulo]\n**Status:** Accepted\n**Contexto:** [Situacao]\n**Decisao:** [O que e por que]\n**Alternativas:**\n| Alternativa | Pros | Contras | Motivo Rejeicao |\n|------------|------|---------|-----------------|\n| [Opcao A] | [Pros] | [Contras] | [Razao] |\n**Consequencias:** [Positivas e negativas]\n\n---\n\n## 4. Database Design\n\n### 4.1 Diagrama ER\n```mermaid\nerDiagram\n    USER ||--o{ ENTITY : \"has many\"\n    USER {\n        uuid id PK\n        string email UK\n        string name\n        timestamp created_at\n    }\n```\n\n### 4.2 Schemas Detalhados\n\n#### Tabela: users\n| Coluna | Tipo | Constraints | Default | Descricao |\n|--------|------|-------------|---------|-----------|\n| id | UUID | PK | gen_random_uuid() | ID unico |\n| email | VARCHAR(255) | UNIQUE, NOT NULL | - | Email |\n| created_at | TIMESTAMP | NOT NULL | now() | Criacao |\n\n**Indices:**\n| Nome | Colunas | Tipo | Proposito |\n|------|---------|------|-----------|\n| users_pkey | id | PRIMARY | PK |\n| users_email_key | email | UNIQUE | Busca |\n\n[Repetir para cada tabela]\n\n### 4.3 Relacionamentos\n| Origem | Destino | Tipo | FK | On Delete |\n|--------|---------|------|-----|-----------|\n| users | [entity] | 1:N | [entity].user_id | RESTRICT |\n\n### 4.4 Migrations\n1. `001_create_users.sql`\n2. `002_create_[entities].sql`\n3. `003_add_indexes.sql`\n\n---\n\n## 5. Integracoes e Data Flow\n\n### 5.1 Inventario\n| Integracao | Proposito | Protocolo | Auth | Fallback | Prioridade |\n|-----------|---------|----------|------|----------|----------|\n| [Servico] | [Para que] | REST | API Key | [Fallback] | MVP |\n\n### 5.2 Data Flow\n| Fluxo | Origem | Destino | Dados | Frequencia |\n|-------|--------|---------|-------|-----------|\n| [Fluxo] | [De] | [Para] | [Dados] | [Freq] |\n\n---\n\n## 6. Seguranca\n\n### 6.1 Autenticacao e Autorizacao\n| Aspecto | Decisao | Justificativa |\n|---------|---------|---------------|\n| Metodo | [JWT/Session/OAuth] | [Por que] |\n| Modelo | [RBAC/ABAC] | [Por que] |\n\n### 6.2 Checklist\n- [ ] Auth strategy definida (ADR)\n- [ ] Rate limiting planejado\n- [ ] Validacao de input\n- [ ] CORS configurado\n- [ ] Gestao de secrets\n- [ ] HTTPS obrigatorio\n\n---\n\n## 7. Infraestrutura\n\n### 7.1 Ambientes\n| Ambiente | URL | Database | Deploy Trigger |\n|----------|-----|----------|---------------|\n| Dev | localhost | Local | Manual |\n| Staging | staging.app.com | Copia | PR merge |\n| Production | app.com | Producao | Release |\n\n### 7.2 Scaling\n| Nivel | Usuarios | Estrategia |\n|-------|---------|-----------|\n| Launch | 0-100 | Single instance |\n| Growth | 100-1K | Horizontal |\n| Scale | 1K-10K | Distributed |\n\n### 7.3 Observabilidade\n| Camada | Monitorar | Ferramentas | Prioridade |\n|--------|----------|-------------|----------|\n| App | Erros, latencia | Sentry | P0 |\n| Infra | CPU, memoria | Platform | P1 |\n| Business | Signups | PostHog | P1 |\n\n---\n\n## 8. GAP Analysis: Infraestrutura\n\n> Skill: `gap-analysis` — Dimensao: Infrastructure\n\n### 8.1 Architecture Assessment\n| Componente | Atual | Necessario | GAP | Esforco |\n|-----------|-------|-----------|-----|---------|\n| [Componente] | [Atual] | [Necessario] | [Delta] | S/M/L/XL |\n\n### 8.2 Scalability Assessment\n| Dimensao | Atual | 6mo | 12mo | GAP |\n|----------|-------|-----|------|-----|\n| Usuarios | [N] | [N] | [N] | [Delta] |\n\n### 8.3 Technical Debt\n| Debito | Impacto | Risco Futuro | Esforco | Prioridade |\n|--------|---------|-------------|---------|------------|\n| [Debito] | [Impacto] | [Risco] | S/M/L/XL | P0/P1/P2 |\n\n### 8.4 GAP Inventory\n| ID | Area | AS-IS | TO-BE | GAP | Severidade | Prioridade |\n|----|------|-------|-------|-----|------------|------------|\n| G-ARCH-01 | [Area] | [Atual] | [Necessario] | [Falta] | [Severidade] | P0/P1/P2 |\n```\n\n**CHECKPOINT:**\n```markdown\nDocumento gerado: docs/01-Planejamento/04-architecture.md\n\nPor favor, revise e responda: ok / editar [secao] / cancelar\n```\n\n**AGUARDE** resposta antes de prosseguir.\n\n---\n\n### Fase 5: Security\n\n**Agente:** `security-auditor`\n**Output:** `docs/01-Planejamento/05-security.md`\n**Skills:** `vulnerability-scanner`, `gap-analysis`\n**Referencia:** Leia Brief, PRD, UX Concept e Architecture\n\n```markdown\n# Security: {Nome do Projeto}\n\n## Metadados\n- **Baseado em:** Brief, PRD, UX Concept, Architecture\n- **Data:** {YYYY-MM-DD}\n- **Autor:** AI Security Auditor\n- **Versao:** 1.0\n\n---\n\n## 1. Security Overview\n\n### 1.1 Classificacao do Sistema\n| Aspecto | Valor |\n|---------|-------|\n| **Dados sensiveis** | Sim/Nao — [Que tipo: PII, financeiro, saude] |\n| **Compliance obrigatorio** | [LGPD / GDPR / SOC2 / HIPAA / Nenhum] |\n| **Nivel de risco** | Critico / Alto / Medio / Baixo |\n| **Exposicao** | Internet-facing / Intranet / Hybrid |\n\n### 1.2 Principios de Seguranca\n1. **Defense in Depth** — Multiplas camadas de protecao\n2. **Least Privilege** — Minimo acesso necessario\n3. **Zero Trust** — Nunca confiar, sempre verificar\n4. **Secure by Default** — Seguro na configuracao padrao\n\n---\n\n## 2. Threat Model\n\n### 2.1 Atores de Ameaca\n| Ator | Motivacao | Capacidade | Probabilidade |\n|------|-----------|-----------|---------------|\n| Script Kiddie | Vandalismo | Baixa (ferramentas automaticas) | Alta |\n| Atacante Externo | Dados/Financeiro | Media (exploits conhecidos) | Media |\n| Insider Malicioso | Dados/Sabotagem | Alta (acesso interno) | Baixa |\n| Competidor | Espionagem | Media | Baixa |\n\n### 2.2 Superficie de Ataque\n| Superficie | Componentes Expostos | Risco | Mitigacao |\n|-----------|---------------------|-------|-----------|\n| **Web Frontend** | Formularios, uploads, URLs | [Risco] | [Mitigacao] |\n| **API** | Endpoints publicos, auth | [Risco] | [Mitigacao] |\n| **Database** | Queries, stored data | [Risco] | [Mitigacao] |\n| **Integracoes** | APIs terceiros, webhooks | [Risco] | [Mitigacao] |\n| **Infraestrutura** | DNS, CDN, hosting | [Risco] | [Mitigacao] |\n\n### 2.3 Diagrama de Ameacas (STRIDE)\n```mermaid\ngraph TB\n    subgraph \"Trust Boundary: Internet\"\n        USER[Usuario] -->|HTTPS| WAF[WAF/CDN]\n    end\n    subgraph \"Trust Boundary: Application\"\n        WAF --> WEB[Web App]\n        WEB --> API[API Server]\n    end\n    subgraph \"Trust Boundary: Data\"\n        API --> DB[(Database)]\n        API --> CACHE[(Cache)]\n    end\n    style WAF fill:#f9f,stroke:#333\n    style API fill:#ff9,stroke:#333\n    style DB fill:#9ff,stroke:#333\n```\n\n---\n\n## 3. OWASP Top 10 Assessment\n\n| # | Vulnerabilidade | Aplicavel? | Risco | Mitigacao Planejada | Status |\n|---|----------------|-----------|-------|---------------------|--------|\n| A01 | Broken Access Control | Sim/Nao | [Risco] | [Mitigacao] | Planejado/Implementado |\n| A02 | Cryptographic Failures | Sim/Nao | [Risco] | [Mitigacao] | Planejado/Implementado |\n| A03 | Injection (SQL, XSS, etc) | Sim/Nao | [Risco] | [Mitigacao] | Planejado/Implementado |\n| A04 | Insecure Design | Sim/Nao | [Risco] | [Mitigacao] | Planejado/Implementado |\n| A05 | Security Misconfiguration | Sim/Nao | [Risco] | [Mitigacao] | Planejado/Implementado |\n| A06 | Vulnerable Components | Sim/Nao | [Risco] | [Mitigacao] | Planejado/Implementado |\n| A07 | Auth & Identity Failures | Sim/Nao | [Risco] | [Mitigacao] | Planejado/Implementado |\n| A08 | Software & Data Integrity | Sim/Nao | [Risco] | [Mitigacao] | Planejado/Implementado |\n| A09 | Security Logging & Monitoring | Sim/Nao | [Risco] | [Mitigacao] | Planejado/Implementado |\n| A10 | Server-Side Request Forgery | Sim/Nao | [Risco] | [Mitigacao] | Planejado/Implementado |\n\n---\n\n## 4. Autenticacao e Autorizacao\n\n### 4.1 Estrategia de Auth\n| Aspecto | Decisao | Justificativa |\n|---------|---------|---------------|\n| Metodo | [JWT / Session / OAuth 2.0 / Passkeys] | [Por que] |\n| Provider | [Clerk / Auth0 / NextAuth / Custom] | [Por que] |\n| MFA | [Sim/Nao] — [TOTP / SMS / WebAuthn] | [Por que] |\n| Session Duration | [Tempo] | [Por que] |\n| Refresh Strategy | [Rotation / Sliding / Fixed] | [Por que] |\n\n### 4.2 Modelo de Autorizacao\n| Aspecto | Decisao |\n|---------|---------|\n| Modelo | [RBAC / ABAC / ReBAC] |\n| Roles | [Admin, User, Viewer, etc.] |\n| Granularidade | [Por recurso / Por acao / Por campo] |\n\n### 4.3 Matriz de Permissoes\n| Recurso | Admin | User | Viewer | Anonimo |\n|---------|-------|------|--------|---------|\n| [Recurso A] | CRUD | CR | R | - |\n| [Recurso B] | CRUD | CRU | R | R |\n| [Admin Panel] | CRUD | - | - | - |\n\n---\n\n## 5. Protecao de Dados\n\n### 5.1 Classificacao de Dados\n| Dado | Classificacao | Armazenamento | Encriptacao | Retencao |\n|------|-------------|---------------|-------------|----------|\n| Password | Critico | Hash (bcrypt/argon2) | At rest | Indefinido |\n| Email | PII | Plaintext | At rest + transit | Ate exclusao |\n| Tokens | Critico | Memory/HttpOnly cookie | Transit | Session duration |\n| Logs | Interno | Log service | Transit | 90 dias |\n\n### 5.2 Compliance\n| Regulamento | Aplicavel? | Requisitos Chave | Status |\n|-------------|-----------|-----------------|--------|\n| LGPD | Sim/Nao | Consentimento, direito ao esquecimento, DPO | [Status] |\n| GDPR | Sim/Nao | Same + data portability, DPA | [Status] |\n| SOC 2 | Sim/Nao | Security, availability, processing integrity | [Status] |\n\n### 5.3 Privacy by Design\n- [ ] Coleta minima de dados (so o necessario)\n- [ ] Consentimento explicito para dados sensiveis\n- [ ] Direito de exclusao implementado\n- [ ] Exportacao de dados do usuario\n- [ ] Logs de acesso a dados pessoais\n- [ ] Anonimizacao de dados em ambientes nao-producao\n\n---\n\n## 6. Seguranca de API\n\n### 6.1 Protecoes\n| Protecao | Implementacao | Configuracao |\n|----------|---------------|-------------|\n| Rate Limiting | [Lib/Service] | [Limites por endpoint] |\n| Input Validation | [Zod / Joi / custom] | Schema-based |\n| CORS | [Configuracao] | [Origins permitidas] |\n| CSRF Protection | [Token / SameSite] | [Estrategia] |\n| Content Security Policy | [Headers] | [Diretivas] |\n| HTTP Security Headers | [Helmet / custom] | HSTS, X-Frame, etc. |\n\n### 6.2 Endpoints Sensiveis\n| Endpoint | Risco | Protecoes Especificas |\n|----------|-------|----------------------|\n| POST /auth/login | Brute force | Rate limit, captcha apos N falhas |\n| POST /auth/register | Spam accounts | Rate limit, email verification |\n| DELETE /users/:id | Data loss | Auth + confirmation + soft delete |\n| GET /admin/* | Privilege escalation | RBAC + IP whitelist |\n\n---\n\n## 7. Seguranca de Infraestrutura\n\n### 7.1 Network Security\n| Camada | Protecao | Ferramenta |\n|--------|----------|-----------|\n| Edge | WAF, DDoS protection | [Cloudflare / AWS WAF] |\n| Transport | TLS 1.3, HSTS | [Auto / Manual] |\n| Application | CSP, CORS | [Headers config] |\n| Data | Encryption at rest | [DB encryption / disk] |\n\n### 7.2 Secret Management\n| Secret | Armazenamento | Rotacao | Acesso |\n|--------|---------------|---------|--------|\n| API Keys | [Env vars / Vault] | [Frequencia] | [Quem] |\n| DB Credentials | [Env vars / Vault] | [Frequencia] | [Quem] |\n| JWT Secret | [Env vars / Vault] | [Frequencia] | [Quem] |\n| Encryption Keys | [KMS / Vault] | [Frequencia] | [Quem] |\n\n---\n\n## 8. Incident Response Plan\n\n### 8.1 Classificacao de Incidentes\n| Severidade | Definicao | Tempo de Resposta | Exemplo |\n|-----------|-----------|-------------------|---------|\n| P0 - Critico | Data breach, system down | Imediato | Vazamento de dados |\n| P1 - Alto | Vulnerabilidade explorada | < 4h | SQL injection detectado |\n| P2 - Medio | Vulnerabilidade descoberta | < 24h | Dependencia com CVE |\n| P3 - Baixo | Best practice violation | < 1 semana | Header faltando |\n\n### 8.2 Procedimento\n1. **Detectar** — Monitoring, alerts, reports\n2. **Conter** — Isolar sistema afetado\n3. **Investigar** — Root cause analysis\n4. **Remediar** — Fix + deploy\n5. **Comunicar** — Stakeholders + usuarios (se necessario)\n6. **Prevenir** — Post-mortem + melhorias\n\n---\n\n## 9. Security Testing Plan\n\n| Tipo | Ferramenta | Frequencia | Responsavel |\n|------|-----------|-----------|-------------|\n| SAST (Static Analysis) | [ESLint security / Semgrep] | Cada PR | CI/CD |\n| Dependency Audit | [npm audit / Snyk] | Diario | CI/CD |\n| DAST (Dynamic Analysis) | [OWASP ZAP] | Semanal | Security |\n| Penetration Testing | [Manual / Bug bounty] | Trimestral | External |\n| Secret Scanning | [GitGuardian / trufflehog] | Cada commit | CI/CD |\n\n---\n\n## 10. GAP Analysis: Seguranca\n\n> Skill: `gap-analysis` — Dimensao: Security\n\n### 10.1 OWASP Coverage\n| Vulnerabilidade OWASP | Mitigacao Necessaria | Estado Atual | GAP | Prioridade |\n|----------------------|---------------------|-------------|-----|------------|\n| A01: Broken Access Control | RBAC + RLS | [Atual] | [Delta] | P0/P1/P2 |\n| A03: Injection | Input validation + ORM | [Atual] | [Delta] | P0/P1/P2 |\n| A07: Auth Failures | MFA + session mgmt | [Atual] | [Delta] | P0/P1/P2 |\n\n### 10.2 Compliance GAP\n| Requisito | Regulamento | Estado Atual | Estado Necessario | GAP | Esforco |\n|-----------|-----------|-------------|------------------|-----|---------|\n| Consentimento | LGPD | [Atual] | [Necessario] | [Delta] | S/M/L/XL |\n| Data Encryption | LGPD/GDPR | [Atual] | [Necessario] | [Delta] | S/M/L/XL |\n\n### 10.3 Security Controls GAP\n| Controle | Necessario | Existe | Status | GAP | Prioridade |\n|----------|----------|--------|--------|-----|------------|\n| WAF | Sim/Nao | Sim/Nao | [Status] | [Delta] | P0/P1/P2 |\n| Rate Limiting | Sim/Nao | Sim/Nao | [Status] | [Delta] | P0/P1/P2 |\n| Secret Rotation | Sim/Nao | Sim/Nao | [Status] | [Delta] | P0/P1/P2 |\n| Audit Logging | Sim/Nao | Sim/Nao | [Status] | [Delta] | P0/P1/P2 |\n\n### 10.4 GAP Inventory\n| ID | Area | AS-IS | TO-BE | GAP | Severidade | Prioridade |\n|----|------|-------|-------|-----|------------|------------|\n| G-SEC-01 | [Area] | [Atual] | [Necessario] | [Falta] | [Severidade] | P0/P1/P2 |\n```\n\n**CHECKPOINT:**\n```markdown\nDocumento gerado: docs/01-Planejamento/05-security.md\n\nPor favor, revise e responda: ok / editar [secao] / cancelar\n```\n\n**AGUARDE** resposta antes de prosseguir.\n\n---\n\n### Fase 6: Stack\n\n**Agente:** `project-planner`\n**Output:** `docs/01-Planejamento/06-stack.md`\n**Skills:** `app-builder`, `architecture`, `gap-analysis`\n**Referencia:** Leia todos os documentos anteriores (especialmente Architecture e Security)\n\n```markdown\n# Stack: {Nome do Projeto}\n\n## Metadados\n- **Baseado em:** Brief, PRD, Architecture\n- **Data:** {YYYY-MM-DD}\n- **Versao:** 1.0\n\n---\n\n## 1. Stack por Camada\n\n| Camada | Tecnologia | Versao | Justificativa | Alternativas |\n|--------|------------|--------|---------------|-------------|\n| Framework Frontend | [Tech] | [Versao] | [Por que] | [Alt] |\n| Linguagem | [Tech] | [Versao] | [Por que] | [Alt] |\n| Styling | [Tech] | [Versao] | [Por que] | [Alt] |\n| State Management | [Tech] | [Versao] | [Por que] | [Alt] |\n| Backend Runtime | [Tech] | [Versao] | [Por que] | [Alt] |\n| Database | [Tech] | [Versao] | [Por que] | [Alt] |\n| ORM | [Tech] | [Versao] | [Por que] | [Alt] |\n| Auth | [Provider] | [-] | [Por que] | [Alt] |\n| Hosting | [Platform] | [-] | [Por que] | [Alt] |\n\n---\n\n## 2. Compatibilidade\n\n### 2.1 Matriz de Compatibilidade\n| Pacote A | Pacote B | Compativel? | Notas |\n|----------|----------|-------------|-------|\n| [A] | [B] | Sim/Nao | [Notas] |\n\n### 2.2 Deprecation Watch\n| Tecnologia | Versao Atual | EOL | Acao |\n|------------|-------------|-----|------|\n| [Tech] | [Versao] | [Data] | [Acao] |\n\n---\n\n## 3. Dependencias\n\n### 3.1 Core (dependencies)\n| Pacote | Versao | Proposito | Tamanho |\n|--------|--------|---------|---------|\n| [Pacote] | [Versao] | [Para que] | [KB] |\n\n### 3.2 Dev (devDependencies)\n| Pacote | Versao | Proposito |\n|--------|--------|---------|\n| [Pacote] | [Versao] | [Para que] |\n\n---\n\n## 4. Tooling\n\n### 4.1 Developer Experience\n| Ferramenta | Proposito | Config |\n|------------|---------|-------|\n| ESLint | Linting | eslint.config.js |\n| Prettier | Formatting | .prettierrc |\n| TypeScript | Types | tsconfig.json |\n\n### 4.2 Testing Stack\n| Tipo | Ferramenta | Config |\n|------|-----------|-------|\n| Unit | [Vitest/Jest] | vitest.config.ts |\n| E2E | [Playwright] | playwright.config.ts |\n\n### 4.3 CI/CD\n| Stage | Ferramenta | Trigger |\n|-------|-----------|---------|\n| Build | [Tool] | PR/Push |\n| Test | [Tool] | PR |\n| Deploy | [Platform] | Merge to main |\n\n---\n\n## 5. Estrutura de Arquivos\n\n```\nproject/\n├── src/\n│   ├── app/            # Pages / Routes\n│   ├── components/     # Shared components\n│   ├── lib/            # Utilities\n│   ├── hooks/          # Custom hooks\n│   ├── services/       # API clients\n│   ├── types/          # TypeScript types\n│   └── styles/         # Global styles\n├── prisma/             # Database\n├── public/             # Static assets\n├── tests/              # Tests\n└── docs/               # Documentation\n```\n\n---\n\n## 6. GAP Analysis: Tecnologia\n\n> Skill: `gap-analysis` — Dimensao: Technology\n\n### 6.1 Stack Atual vs Necessaria\n| Camada | Atual | Necessaria | Motivo | Esforco |\n|--------|-------|-----------|--------|---------|\n| [Camada] | [Atual/N/A] | [Necessaria] | [Por que] | S/M/L/XL |\n\n### 6.2 Versoes e Deprecations\n| Tech | Atual | Ultima Estavel | EOL | Acao |\n|------|-------|---------------|-----|------|\n| [Tech] | [Atual] | [Ultima] | [Data] | [Acao] |\n\n### 6.3 Bibliotecas Faltantes\n| Necessidade | Solucao | Alternativas | Prioridade |\n|-------------|---------|-------------|------------|\n| [Need] | [Lib] | [Alt] | P0/P1/P2 |\n\n### 6.4 GAP Inventory\n| ID | Area | AS-IS | TO-BE | GAP | Severidade | Prioridade |\n|----|------|-------|-------|-----|------------|------------|\n| G-STACK-01 | [Area] | [Atual] | [Necessario] | [Falta] | [Severidade] | P0/P1/P2 |\n```\n\n**CHECKPOINT:**\n```markdown\nDocumento gerado: docs/01-Planejamento/06-stack.md\n\nPor favor, revise e responda: ok / editar [secao] / cancelar\n```\n\n**AGUARDE** resposta antes de prosseguir.\n\n---\n\n### Fase 7: Design System\n\n**Agente:** `frontend-specialist`\n**Output:** `docs/01-Planejamento/07-design-system.md`\n**Skills:** `frontend-design`, `tailwind-patterns`, `gap-analysis`\n**Referencia:** Leia TODOS os documentos anteriores\n\n```markdown\n# Design System: {Nome do Projeto}\n\n## Metadados\n- **Baseado em:** Brief, PRD, UX Concept, Stack\n- **Data:** {YYYY-MM-DD}\n- **Framework CSS:** [Tailwind / CSS Modules / etc.]\n\n---\n\n## 1. Fundamentos\n\n### 1.1 Principios de Design\n1. **[Principio 1]:** [Descricao]\n2. **[Principio 2]:** [Descricao]\n3. **[Principio 3]:** [Descricao]\n\n### 1.2 Tom Visual\n- **Personalidade:** [Ex: Profissional mas acessivel]\n- **Sensacao:** [Ex: Confianca, modernidade]\n\n---\n\n## 2. Paleta de Cores\n\n### 2.1 Cores Primarias\n| Token | Hex | RGB | Uso |\n|-------|-----|-----|-----|\n| --color-primary-50 | #[HEX] | rgb(R,G,B) | Backgrounds |\n| --color-primary-500 | #[HEX] | rgb(R,G,B) | Botoes, links |\n| --color-primary-600 | #[HEX] | rgb(R,G,B) | Hover |\n| --color-primary-900 | #[HEX] | rgb(R,G,B) | Texto |\n\n### 2.2 Cores Semanticas\n| Token | Hex | Uso |\n|-------|-----|-----|\n| --color-success | #[HEX] | Confirmacoes |\n| --color-warning | #[HEX] | Alertas |\n| --color-error | #[HEX] | Erros |\n| --color-info | #[HEX] | Informacoes |\n\n### 2.3 Cores Neutras\n| Token | Hex | Uso |\n|-------|-----|-----|\n| --color-gray-50 | #[HEX] | Background |\n| --color-gray-200 | #[HEX] | Bordas |\n| --color-gray-600 | #[HEX] | Texto secundario |\n| --color-gray-900 | #[HEX] | Texto principal |\n\n### 2.4 Dark Mode (se aplicavel)\n| Light | Dark | Mapeamento |\n|-------|------|------------|\n| gray-50 | gray-900 | Background |\n| gray-900 | gray-50 | Texto |\n\n---\n\n## 3. Tipografia\n\n### 3.1 Familias\n| Proposito | Fonte | Fallback |\n|-----------|-------|----------|\n| Headlines | [Fonte] | system-ui |\n| Body | [Fonte] | system-ui |\n| Code | [Fonte] | monospace |\n\n### 3.2 Escala\n| Token | Tamanho | Line Height | Uso |\n|-------|---------|-------------|-----|\n| --text-xs | 12px | 1.5 | Labels |\n| --text-sm | 14px | 1.5 | Body small |\n| --text-base | 16px | 1.5 | Body |\n| --text-lg | 18px | 1.5 | Body large |\n| --text-xl | 20px | 1.4 | H4 |\n| --text-2xl | 24px | 1.3 | H3 |\n| --text-3xl | 30px | 1.2 | H2 |\n| --text-4xl | 36px | 1.1 | H1 |\n\n---\n\n## 4. Espacamento (Base 8px)\n\n| Token | Valor | Uso |\n|-------|-------|-----|\n| --space-1 | 4px | Gaps minimos |\n| --space-2 | 8px | Padding interno |\n| --space-4 | 16px | Cards, botoes |\n| --space-6 | 24px | Secoes |\n| --space-8 | 32px | Blocos |\n| --space-12 | 48px | Secoes maiores |\n\n---\n\n## 5. Layout\n\n### Breakpoints\n| Nome | Min-width | Uso |\n|------|-----------|-----|\n| sm | 640px | Tablet portrait |\n| md | 768px | Tablet landscape |\n| lg | 1024px | Desktop |\n| xl | 1280px | Desktop grande |\n\n### Grid: 12 colunas, gutter 24px (desktop) / 16px (mobile)\n\n---\n\n## 6. Componentes\n\n### Buttons\n| Variante | Uso |\n|----------|-----|\n| Primary | Acao principal |\n| Secondary | Acoes secundarias |\n| Outline | Acoes terciarias |\n| Ghost | Acoes sutis |\n| Destructive | Acoes perigosas |\n\n**Estados:** Default, Hover, Active, Focus, Disabled, Loading\n**Tamanhos:** Small (32px), Default (40px), Large (48px)\n\n### Inputs\n**Tipos:** Text, Textarea, Select, Checkbox, Radio, Toggle\n**Estados:** Default, Hover, Focus, Error, Disabled\n\n### Cards, Modals, Alerts, Tables, Tooltips, Skeletons\n[Especificar variantes, tamanhos e estados para cada]\n\n---\n\n## 7. Iconografia\n- **Biblioteca:** [Heroicons / Lucide / Phosphor]\n- **Tamanhos:** 16px, 20px, 24px\n\n---\n\n## 8. Animacoes\n| Duracao | Valor | Uso |\n|---------|-------|-----|\n| Fast | 100ms | Hovers |\n| Default | 200ms | Transicoes |\n| Slow | 300ms | Modais |\n\n---\n\n## 9. Acessibilidade\n- [ ] Contraste 4.5:1 texto\n- [ ] Contraste 3:1 graficos\n- [ ] Focus states visiveis\n- [ ] Labels em inputs\n- [ ] Navegacao teclado\n\n---\n\n## 10. GAP Analysis: Design\n\n> Skill: `gap-analysis` — Dimensao: Design\n\n### 10.1 Component Coverage\n| Componente | Necessario | Existe | GAP | Prioridade |\n|-----------|-----------|--------|-----|------------|\n| [Comp] | Sim | Sim/Nao | [Delta] | P0/P1/P2 |\n\n### 10.2 Token Coverage\n| Categoria | Definidos | Faltantes | % |\n|----------|----------|----------|---|\n| Cores | [N] | [N] | [%] |\n| Tipografia | [N] | [N] | [%] |\n| Espacamento | [N] | [N] | [%] |\n\n### 10.3 GAP Inventory\n| ID | Area | AS-IS | TO-BE | GAP | Severidade | Prioridade |\n|----|------|-------|-------|-----|------------|------------|\n| G-DS-01 | [Area] | [Atual] | [Necessario] | [Falta] | [Severidade] | P0/P1/P2 |\n```\n\n**CHECKPOINT:**\n```markdown\nDocumento gerado: docs/01-Planejamento/07-design-system.md\n\nPor favor, revise e responda: ok / editar [secao] / cancelar\n```\n\n**AGUARDE** resposta antes de prosseguir.\n\n---\n\n### Fase 8: Backlog (Consolidacao de GAPs)\n\n**Agente:** `product-owner`\n**Output:** `docs/BACKLOG.md`\n**Skills:** `plan-writing`, `gap-analysis`\n**Referencia:** Leia TODOS os 7 documentos anteriores\n\n```markdown\n# Backlog: {Nome do Projeto}\n\n> Gerado a partir dos documentos de planejamento com GAPs consolidados.\n\n**Ultima Atualizacao:** {YYYY-MM-DD HH:MM}\n**Total de Tarefas:** {N}\n**Progresso:** 0%\n\n---\n\n## Indice de Epicos\n\n| # | Epico | Stories | Status |\n|---|-------|---------|--------|\n| 1 | [Nome] | {N} | TODO |\n| 2 | [Nome] | {N} | TODO |\n| 3 | [Nome] | {N} | TODO |\n\n---\n\n## Epic 1: {Nome}\n\n> **Objetivo:** {Descricao}\n> **Requisitos:** RF01, RF02\n> **GAPs:** G-PRD-01, G-ARCH-01\n\n### Story 1.1: {Titulo}\n\n**Como** {persona}, **quero** {acao} **para** {beneficio}.\n\n**Criterios de Aceite:**\n- [ ] {Criterio 1}\n- [ ] {Criterio 2}\n\n**Subtarefas:**\n- [ ] **1.1.1:** {Subtarefa}\n- [ ] **1.1.2:** {Subtarefa}\n\n**Dependencias:** Nenhuma | Story X.Y\n**Estimativa:** P/M/G\n**GAPs resolvidos:** [IDs]\n\n---\n\n[Repetir para cada Story e Epic]\n\n---\n\n## Consolidated GAP Summary\n\n### Por Severidade\n| Severidade | Produto | UX | Arquitetura | Seguranca | Stack | Design | Total |\n|-----------|---------|-----|------------|-----------|-------|--------|-------|\n| Critical | [N] | [N] | [N] | [N] | [N] | [N] | [N] |\n| High | [N] | [N] | [N] | [N] | [N] | [N] | [N] |\n| Medium | [N] | [N] | [N] | [N] | [N] | [N] | [N] |\n| Low | [N] | [N] | [N] | [N] | [N] | [N] | [N] |\n\n### GAP-to-Task Mapping\n| GAP ID | Origem | Epic | Story | Prioridade | Status |\n|--------|--------|------|-------|------------|--------|\n| G-PRD-01 | PRD | Epic 1 | Story 1.1 | P0 | TODO |\n| G-UX-01 | UX Concept | Epic 2 | Story 2.2 | P1 | TODO |\n| G-ARCH-01 | Architecture | Epic 1 | Story 1.3 | P0 | TODO |\n| G-SEC-01 | Security | Epic 1 | Story 1.2 | P0 | TODO |\n| G-STACK-01 | Stack | Epic 3 | Story 3.1 | P1 | TODO |\n| G-DS-01 | Design System | Epic 2 | Story 2.4 | P2 | TODO |\n\n### Roadmap para Fechar GAPs\n| Fase | GAPs | Milestone | Dependencias |\n|------|------|-----------|-------------|\n| Foundation | G-PRD-01, G-ARCH-01, G-STACK-01 | Infra pronta | Nenhuma |\n| Core | G-UX-01, G-PRD-02 | Fluxos principais | Foundation |\n| Polish | G-DS-01, G-UX-03 | Consistencia | Core |\n\n---\n\n## Progresso\n\n| Epico | Total | Done | In Progress | TODO | % |\n|-------|-------|------|------------|------|---|\n| Epic 1 | {N} | 0 | 0 | {N} | 0% |\n| **TOTAL** | **{N}** | **0** | **0** | **{N}** | **0%** |\n\n```\n[                    ] 0% (0/{N} stories)\n```\n\n---\n\n## Dependencias\n\n```mermaid\nflowchart LR\n    S1.1[Story 1.1] --> S1.2[Story 1.2]\n    S1.1 --> S2.1[Story 2.1]\n```\n\n---\n\n## Ordem de Execucao\n\n1. **Foundation:** Story 1.1, 1.2\n2. **Core:** Story 2.1, 2.2, 2.3\n3. **Polish:** Story 3.1, 3.2\n4. **Launch:** Story 4.1\n\n---\n\n## Changelog\n| Data | Alteracao | Autor |\n|------|-----------|-------|\n| {YYYY-MM-DD} | Backlog criado | AI Product Owner |\n```\n\n---\n\n## Pos-Execucao\n\nApos criar todos os 8 documentos:\n\n### Geracao Automatica de HANDOFF.md\n\nQuando executado pelo Gemini CLI (Flow B), gerar automaticamente `docs/HANDOFF.md`:\n\n```markdown\n# HANDOFF — Gemini → Codex\n- Data: {YYYY-MM-DD}\n- Projeto: {nome}\n- Status: PRONTO PARA IMPLEMENTACAO\n\n## Documentos Prontos\n- [x] Brief: docs/01-Planejamento/01-product-brief.md\n- [x] PRD: docs/01-Planejamento/02-prd.md\n- [x] UX Concept: docs/01-Planejamento/03-ux-concept.md\n- [x] Visual Mockups: docs/01-Planejamento/03.5-visual-mockups.md (se HAS_UI)\n- [x] Architecture: docs/01-Planejamento/04-architecture.md\n- [x] Security: docs/01-Planejamento/05-security.md\n- [x] Stack: docs/01-Planejamento/06-stack.md\n- [x] Design System: docs/01-Planejamento/07-design-system.md\n- [x] Backlog: docs/BACKLOG.md\n\n## Prioridades de Implementacao\n1. {Epic 1} [P0]\n2. {Epic 2} [P0]\n3. ...\n\n## Decisoes Tecnicas Importantes\n- Stack: {extraido do 06-stack.md}\n- Auth: {extraido do 05-security.md}\n- ...\n\n## Notas para o Implementador\n- Ler este documento ANTES de comecar qualquer implementacao\n- Seguir a ordem de execucao definida no Backlog\n- Nao alterar documentos de planejamento\n```\n\n> **Regra:** O HANDOFF.md e gerado automaticamente. No Claude Code (Flow A), este passo e opcional pois o mesmo agente faz planning + implementacao.\n\n### Sharding Recomendado\n\nApos gerar o BACKLOG.md, sugerir ao usuario:\n\n```bash\npython3 .agents/scripts/shard_epic.py shard\n```\n\nIsso divide o backlog em arquivos individuais por story em `docs/stories/`, permitindo que as IAs trabalhem com contexto focado.\n\n### Resumo Final\n\n```markdown\n## Workflow /define Concluido!\n\n### Documentos Gerados:\n1. docs/01-Planejamento/01-product-brief.md — Visao e contexto\n2. docs/01-Planejamento/02-prd.md — Requisitos + GAP produto\n3. docs/01-Planejamento/03-ux-concept.md — UX + GAP experiencia\n3.5. docs/01-Planejamento/03.5-visual-mockups.md — Mockups visuais (se HAS_UI)\n4. docs/01-Planejamento/04-architecture.md — Arquitetura + DB + GAP infra\n5. docs/01-Planejamento/05-security.md — Seguranca + GAP security\n6. docs/01-Planejamento/06-stack.md — Stack + GAP tecnologia\n7. docs/01-Planejamento/07-design-system.md — Design + GAP design\n8. docs/BACKLOG.md — Backlog + GAPs consolidados\n9. docs/HANDOFF.md — Handoff para implementacao (se Flow B)\n\n### Proximo Passo: Revisao\nDocumentos devem ser revisados com skill `doc-review` por Claude Code ou Codex.\n\n### Apos Revisao:\n1. /track — Inicializar tracking\n2. implementar Story 1.1 — Comecar implementacao\n\nNAO inicio implementacao sem aprovacao explicita.\n```\n\n---\n\n## Regras de Qualidade\n\n### Documentacao Deve:\n1. **Ser Especifica** — Sem \"varios\", \"alguns\", \"etc\"\n2. **Ser Mensuravel** — Numeros, metricas, limites\n3. **Ser Acionavel** — Executavel ou verificavel\n4. **Ser Consistente** — Mesmos termos em todos os docs\n5. **Ser Rastreavel** — Requisitos -> Stories -> Tasks\n6. **Ter GAP Analysis** — Todos os docs exceto Brief\n\n### Anti-Padroes:\n- \"Sistema deve ser rapido\" -> \"API < 200ms (p95)\"\n- \"Usuarios fazem coisas\" -> \"Usuario cria ate 10 projetos\"\n- Omitir GAP -> Identificar gaps em TODAS as dimensoes (produto, UX, infra, seguranca, tech, design)\n\n---\n\n## Fluxo de Revisao\n\n| Gerador | Revisor | Skill |\n|---------|---------|-------|\n| Antigravity | Claude Code / Codex | `doc-review` |\n\n### Processo:\n1. Revisor le TODOS os documentos\n2. Aplica checklist `doc-review` (5 fases)\n3. Gera Review Report\n4. NEEDS REVISION -> lista issues\n5. APPROVED -> pronto para implementacao\n",
+    "define": "---\ndescription: Cria documentacao de projeto estruturada em 9 etapas (Brief, PRD, UX Concept, Architecture, Security, Stack, Design System, Backlog) com GAP Analysis integrada usando agentes especializados.\n---\n\n# Workflow: /define\n\n> **Proposito:** Planejamento completo e PRECISO para projetos \"do zero\". Gera documentacao tecnica detalhada, acionavel e com GAP Analysis integrada em cada dimensao.\n\n## Regras Criticas\n\n1. **NAO ESCREVA CODIGO** — Este workflow gera apenas documentacao.\n2. **SEQUENCIAL** — Cada documento depende dos anteriores.\n3. **SOCRATIC GATE OBRIGATORIO** — Pergunte ANTES de criar.\n4. **PRECISAO TECNICA** — Documentos devem ser especificos, nao genericos.\n5. **VALIDACAO CONTINUA** — Confirme entendimento antes de cada fase.\n6. **GAP ANALYSIS OBRIGATORIO** — Todos os documentos (exceto Brief) DEVEM incluir secao de GAP.\n7. **REVISAO POS-GERACAO** — Documentos gerados pelo Antigravity DEVEM ser revisados por Claude Code/Codex usando a skill `doc-review`.\n\n---\n\n## Estrutura de Documentos\n\n| Fase | Documento | Agente | Skills | GAP |\n|------|-----------|--------|--------|-----|\n| 0 | Discovery | (entrevista) | brainstorming | - |\n| 1 | Brief | `product-manager` | brainstorming, plan-writing | Nenhum |\n| 2 | PRD | `product-owner` | plan-writing, gap-analysis | Produto/Negocio |\n| 3 | UX Concept | `ux-researcher` | ux-research, frontend-design, gap-analysis | Experiencia |\n| 3.5 | Visual Mockups | `frontend-specialist` | stitch-ui-design, frontend-design | Visual |\n| 4 | Architecture | `project-planner` | architecture, system-design, gap-analysis | Infraestrutura |\n| 5 | Security | `security-auditor` | vulnerability-scanner, gap-analysis | Seguranca |\n| 6 | Stack | `project-planner` | app-builder, architecture, gap-analysis | Tecnologia |\n| 7 | Design System | `frontend-specialist` | frontend-design, tailwind-patterns, gap-analysis | Design |\n| 8 | Backlog | `product-owner` | plan-writing, gap-analysis | Consolidacao |\n\n---\n\n## Fluxo de Execucao\n\n### Fase 0: Setup e Discovery (OBRIGATORIO)\n\n> **Objetivo:** Criar a estrutura organizacional de documentacao e extrair informacoes do projeto.\n\n**1. Setup da Estrutura de Documentacao**\n\nAntes de qualquer pergunta, execute:\n\n```bash\nmkdir -p docs/00-Contexto docs/01-Planejamento docs/02-Requisitos docs/03-Arquitetura/ADRs docs/04-API docs/08-Logs-Sessoes\necho \"# Documentacao de Planejamento\" > docs/01-Planejamento/README.md\n```\n\n> **Nota:** O `/define` cria a estrutura numerada (`docs/01-Planejamento/`). Projetos que nao passaram pelo `/define` podem usar `docs/planning/`. Ambos sao aceitos — ver tabela de aliases em `INSTRUCTIONS.md`.\n\n**Estrutura Alvo:**\n- `docs/00-Contexto/` (Context, Readiness)\n- `docs/01-Planejamento/` (Brief, PRD, UX Concept, Architecture, Stack, Design System)\n- `docs/02-Requisitos/` (Stories, Journeys)\n- `docs/03-Arquitetura/` (ADRs, Diagramas)\n- `docs/08-Logs-Sessoes/` (Logs diarios)\n\n---\n\n**2. Entrevista de Discovery**\n\nConduza a entrevista estruturada:\n\n```markdown\n## Discovery: Entendendo Seu Projeto\n\nVou fazer algumas perguntas para garantir que a documentacao seja precisa e util.\n\n### Bloco 1: Problema e Contexto\n1. **Qual problema especifico este sistema resolve?**\n   - Descreva uma situacao real onde esse problema acontece\n\n2. **Como esse problema e resolvido hoje (se existir solucao atual)?**\n   - Quais sao as limitacoes da solucao atual?\n\n### Bloco 2: Usuarios e Casos de Uso\n3. **Quem sao os usuarios principais?** (Seja especifico)\n   - Exemplo: \"Gerentes de RH em empresas de 50-200 funcionarios\" vs \"usuarios\"\n\n4. **Descreva 3 cenarios de uso tipicos:**\n   - Cenario 1: [Quem] quer [fazer o que] para [alcancar qual resultado]\n   - Cenario 2: ...\n   - Cenario 3: ...\n\n### Bloco 3: Funcionalidades Core\n5. **Liste as 5 funcionalidades ESSENCIAIS do MVP (em ordem de prioridade):**\n   - Para cada uma, descreva o que o usuario deve conseguir fazer\n\n6. **O que NAO faz parte do MVP?** (Igualmente importante)\n   - Funcionalidades que podem esperar versoes futuras\n\n### Bloco 4: Restricoes Tecnicas\n7. **Stack tecnica preferida ou obrigatoria:**\n   - Frontend: (React, Vue, Next.js, etc.)\n   - Backend: (Node, Python, etc.)\n   - Database: (PostgreSQL, MongoDB, Firebase, etc.)\n   - Hosting: (Vercel, AWS, etc.)\n\n8. **Integracoes obrigatorias:**\n   - APIs externas (pagamento, email, auth, etc.)\n   - Sistemas legados\n\n### Bloco 5: Contexto de Negocio\n9. **Modelo de monetizacao (se aplicavel):**\n   - Free, Freemium, Subscription, One-time, etc.\n\n10. **Metricas de sucesso (como saberemos que funcionou?):**\n    - Metricas quantitativas (ex: 100 usuarios em 30 dias)\n    - Metricas qualitativas (ex: NPS > 8)\n\n### Bloco 6: Contexto Existente (Para GAP Analysis)\n11. **Existe algo ja construido?** (codigo, prototipos, docs)\n    - Se sim: qual o estado atual? O que funciona? O que nao funciona?\n    - Se nao: e um projeto 100% greenfield?\n\n12. **Existem sistemas legados que precisam ser considerados?**\n    - Integracoes obrigatorias com sistemas existentes\n    - Migracoes de dados necessarias\n\n13. **O projeto tem interface visual (web, mobile, desktop)?**\n    - Se sim: quais tipos de tela? (dashboard, landing, formularios, etc.)\n    - Se nao: e uma API pura, CLI tool, ou backend-only?\n    - **Guardar resposta como flag `HAS_UI=true/false`**\n```\n\n**REGRA:** NAO prossiga ate ter respostas claras para TODAS as perguntas.\n\nSe o usuario for vago, faca follow-up:\n```markdown\nPreciso de mais detalhes sobre [X]. Voce mencionou \"[resposta vaga]\", mas:\n- Quantos [usuarios/registros/etc] voce espera?\n- Com que frequencia [acao] acontece?\n- Qual e o impacto se [cenario de falha]?\n```\n\n---\n\n### Fase 1: Product Brief\n\n**Agente:** `product-manager`\n**Output:** `docs/01-Planejamento/01-product-brief.md`\n**Skills:** `brainstorming`, `plan-writing`\n\n```markdown\n# Product Brief: {Nome do Projeto}\n\n## Metadados\n- **Data de criacao:** {YYYY-MM-DD}\n- **Autor:** AI Product Manager\n- **Versao:** 1.0\n- **Status:** Draft | Em Revisao | Aprovado\n\n---\n\n## 1. Visao do Produto\n\n### 1.1 Declaracao de Visao\n> \"Para [PUBLICO-ALVO] que [TEM NECESSIDADE], o [NOME DO PRODUTO] e um [CATEGORIA] que [BENEFICIO PRINCIPAL]. Diferente de [ALTERNATIVA], nosso produto [DIFERENCIAL].\"\n\n### 1.2 Elevator Pitch (30 segundos)\n[Versao expandida da visao para apresentacao rapida]\n\n---\n\n## 2. Problema\n\n### 2.1 Declaracao do Problema\n| Aspecto | Descricao |\n|---------|-----------|\n| **O problema** | [Descricao especifica] |\n| **Afeta** | [Quem sofre com isso - seja especifico] |\n| **O impacto e** | [Consequencias mensuraveis] |\n| **Hoje e resolvido por** | [Solucoes atuais e suas limitacoes] |\n\n### 2.2 Evidencias do Problema\n- [Dado/Estatistica 1 que comprova o problema]\n- [Dado/Estatistica 2]\n- [Citacao/Feedback de usuario potencial]\n\n### 2.3 Consequencias de Nao Resolver\n- Curto prazo: [O que acontece em semanas]\n- Medio prazo: [O que acontece em meses]\n- Longo prazo: [O que acontece em anos]\n\n---\n\n## 3. Solucao\n\n### 3.1 Descricao da Solucao\n[2-3 paragrafos explicando como o produto resolve o problema]\n\n### 3.2 Proposta de Valor Unica (UVP)\n| Diferencial | Como entregamos | Beneficio para usuario |\n|-------------|-----------------|----------------------|\n| [Diferencial 1] | [Implementacao] | [Resultado] |\n| [Diferencial 2] | [Implementacao] | [Resultado] |\n| [Diferencial 3] | [Implementacao] | [Resultado] |\n\n### 3.3 Funcionalidades Core do MVP\n| # | Funcionalidade | Descricao | Justificativa (Por que MVP?) |\n|---|----------------|-----------|------------------------------|\n| 1 | [Nome] | [O que faz] | [Por que e essencial] |\n| 2 | [Nome] | [O que faz] | [Por que e essencial] |\n| 3 | [Nome] | [O que faz] | [Por que e essencial] |\n| 4 | [Nome] | [O que faz] | [Por que e essencial] |\n| 5 | [Nome] | [O que faz] | [Por que e essencial] |\n\n### 3.4 Fora do Escopo (Explicitamente)\n| Funcionalidade | Por que nao esta no MVP | Versao planejada |\n|----------------|-------------------------|------------------|\n| [Feature A] | [Motivo] | v1.1 |\n| [Feature B] | [Motivo] | v2.0 |\n\n---\n\n## 4. Publico-Alvo\n\n### 4.1 Persona Primaria\n| Atributo | Descricao |\n|----------|-----------|\n| **Nome ficticio** | [Ex: \"Carlos, o RH Sobrecarregado\"] |\n| **Cargo/Papel** | [Funcao especifica] |\n| **Empresa/Contexto** | [Tamanho, setor, regiao] |\n| **Objetivos** | [O que quer alcancar] |\n| **Frustracoes** | [Dores atuais] |\n| **Comportamento digital** | [Como usa tecnologia] |\n| **Quote caracteristica** | [\"Frase que essa pessoa diria\"] |\n\n### 4.2 Persona Secundaria (se houver)\n[Mesmo formato]\n\n### 4.3 Anti-Persona (Quem NAO e nosso usuario)\n[Descreva quem nao deve usar o produto e por que]\n\n---\n\n## 5. Metricas de Sucesso\n\n### 5.1 North Star Metric\n> **A unica metrica que define sucesso:** [Metrica + meta]\n\n### 5.2 Metricas de Acompanhamento\n| Categoria | Metrica | Meta MVP | Como medir |\n|-----------|---------|----------|------------|\n| **Aquisicao** | [Ex: Sign-ups/semana] | [Ex: 50] | [Ferramenta] |\n| **Ativacao** | [Ex: % que completa onboarding] | [Ex: 60%] | [Ferramenta] |\n| **Retencao** | [Ex: % volta em 7 dias] | [Ex: 40%] | [Ferramenta] |\n| **Receita** | [Ex: MRR] | [Ex: $1000] | [Ferramenta] |\n| **Referencia** | [Ex: NPS] | [Ex: > 30] | [Ferramenta] |\n\n### 5.3 Criterios de Sucesso do MVP\nO MVP sera considerado bem-sucedido se:\n- [ ] [Criterio 1 - especifico e mensuravel]\n- [ ] [Criterio 2]\n- [ ] [Criterio 3]\n\n---\n\n## 6. Riscos e Mitigacoes\n\n| Risco | Probabilidade | Impacto | Mitigacao |\n|-------|---------------|---------|-----------|\n| [Risco tecnico 1] | Alta/Media/Baixa | Alto/Medio/Baixo | [Plano] |\n| [Risco de mercado 1] | Alta/Media/Baixa | Alto/Medio/Baixo | [Plano] |\n| [Risco de execucao 1] | Alta/Media/Baixa | Alto/Medio/Baixo | [Plano] |\n\n---\n\n## Aprovacoes\n\n| Papel | Nome | Status | Data |\n|-------|------|--------|------|\n| Product Owner | [Nome/Usuario] | Pendente | - |\n| Tech Lead | [Nome/Usuario] | Pendente | - |\n```\n\n**CHECKPOINT:**\n```markdown\nDocumento gerado: docs/01-Planejamento/01-product-brief.md\n\nPor favor, revise o Product Brief e responda:\n- ok — Aprovar e continuar para PRD\n- editar [secao] — Ajustar secao especifica (ex: \"editar personas\")\n- cancelar — Parar o workflow\n\nPerguntas de validacao:\n1. A visao do produto captura sua ideia corretamente?\n2. As personas representam seus usuarios reais?\n3. As metricas de sucesso sao realistas?\n```\n\n**AGUARDE** resposta antes de prosseguir.\n\n---\n\n### Fase 2: PRD (Product Requirements Document)\n\n**Agente:** `product-owner`\n**Output:** `docs/01-Planejamento/02-prd.md`\n**Skills:** `plan-writing`, `gap-analysis`\n**Referencia:** Leia `01-product-brief.md` antes de comecar\n\n```markdown\n# PRD: {Nome do Projeto}\n\n## Metadados\n- **Baseado em:** 01-product-brief.md\n- **Data:** {YYYY-MM-DD}\n- **Versao:** 1.0\n\n---\n\n## 1. Requisitos Funcionais\n\n### Legenda de Prioridade\n- **P0 (Critico):** Sem isso, o produto nao funciona. Bloqueador de lancamento.\n- **P1 (Importante):** Essencial para a proposta de valor. Pode lancar sem, mas prejudica.\n- **P2 (Desejavel):** Melhora a experiencia, mas nao e essencial para MVP.\n\n---\n\n### RF01: [Nome do Requisito]\n| Campo | Valor |\n|-------|-------|\n| **ID** | RF01 |\n| **Titulo** | [Nome claro e descritivo] |\n| **Descricao** | Como [PERSONA], eu quero [ACAO] para que [BENEFICIO] |\n| **Prioridade** | P0 / P1 / P2 |\n| **Epico relacionado** | [Nome do Epico] |\n\n**Criterios de Aceite (Gherkin):**\n```gherkin\nDADO que [contexto/pre-condicao]\nQUANDO [acao do usuario]\nENTAO [resultado esperado]\nE [resultado adicional se houver]\n```\n\n**Casos de Borda:**\n- [ ] [Cenario limite 1 e comportamento esperado]\n- [ ] [Cenario limite 2 e comportamento esperado]\n\n**Regras de Negocio:**\n- RN01: [Regra especifica]\n- RN02: [Regra especifica]\n\n**Dependencias:**\n- Depende de: [RF## se houver]\n- Bloqueia: [RF## se houver]\n\n---\n\n[Repetir para cada RF]\n\n---\n\n## 2. Requisitos Nao-Funcionais\n\n### RNF01: Performance\n| Aspecto | Requisito | Como medir |\n|---------|-----------|------------|\n| Tempo de carregamento inicial | < 3 segundos (LCP) | Lighthouse |\n| Tempo de resposta de API | < 200ms (p95) | APM |\n| Time to Interactive | < 5 segundos | Lighthouse |\n\n### RNF02: Escalabilidade\n| Aspecto | Requisito MVP | Requisito v1.0 |\n|---------|---------------|----------------|\n| Usuarios simultaneos | [N] | [N] |\n| Requisicoes/minuto | [N] | [N] |\n| Dados armazenados | [N]GB | [N]GB |\n\n### RNF03: Seguranca\n| Requisito | Implementacao |\n|-----------|---------------|\n| Autenticacao | [JWT / Session / OAuth] |\n| Autorizacao | [RBAC / ABAC] |\n| Criptografia em transito | TLS 1.3 |\n| Conformidade | [LGPD / GDPR se aplicavel] |\n\n### RNF04: Acessibilidade\n- **Nivel WCAG:** AA\n- **Leitores de tela:** Compativel\n- **Navegacao por teclado:** Completa\n\n---\n\n## 3. Fluxos de Usuario (User Journeys)\n\n### Fluxo 1: [Nome do Fluxo Principal]\n\n**Objetivo:** [O que o usuario quer alcancar]\n**Persona:** [Qual persona]\n\n```mermaid\nflowchart TD\n    A[Inicio] --> B{Condicao?}\n    B -->|Sim| C[Acao]\n    B -->|Nao| D[Alternativa]\n    C --> E[Resultado]\n```\n\n**Passos detalhados:**\n| # | Acao do Usuario | Resposta do Sistema | Dados envolvidos |\n|---|-----------------|---------------------|------------------|\n| 1 | [Acao] | [Resposta] | [Entidades] |\n\n---\n\n## 4. Regras de Negocio Globais\n\n### RN-G01: [Nome da Regra]\n- **Descricao:** [O que a regra define]\n- **Condicao:** SE [condicao]\n- **Acao:** ENTAO [resultado]\n- **Excecao:** EXCETO QUANDO [excecao]\n- **Afeta:** [Quais RFs sao impactados]\n\n---\n\n## 5. Integracoes\n\n### INT01: [Nome da Integracao]\n| Campo | Valor |\n|-------|-------|\n| **Servico** | [Nome do servico externo] |\n| **Proposito** | [Para que e usado] |\n| **Tipo** | REST API / Webhook / SDK / OAuth |\n| **Autenticacao** | API Key / OAuth2 / JWT |\n| **Rate Limits** | [Limites conhecidos] |\n| **Fallback** | [O que fazer se falhar] |\n\n---\n\n## 6. Matriz de Rastreabilidade\n\n| Requisito | Epico | User Story | Criterio de Teste |\n|-----------|-------|------------|-------------------|\n| RF01 | Epic 1 | Story 1.1 | TC001, TC002 |\n\n---\n\n## 7. GAP Analysis: Produto e Negocio\n\n> Skill: `gap-analysis` — Dimensao: Product/Business\n\n### 7.1 Feature Coverage\n| Feature | Expectativa de Mercado | Estado Atual | GAP | Prioridade |\n|---------|----------------------|--------------|-----|------------|\n| [Feature A] | [O que concorrentes oferecem] | [O que temos] | [Delta] | P0/P1/P2 |\n\n### 7.2 Capability Assessment\n| Capacidade | Nivel Necessario | Nivel Atual | GAP | Esforco |\n|------------|-----------------|-------------|-----|---------|\n| [Capacidade] | [Alvo] | [Atual] | [Delta] | S/M/L/XL |\n\n### 7.3 Metrics GAP\n| Metrica | Valor Atual | Valor Alvo | GAP | Estrategia |\n|---------|------------|------------|-----|-----------|\n| [Metrica] | [Atual ou N/A] | [Alvo] | [Delta] | [Como fechar] |\n\n### 7.4 GAP Inventory\n| ID | Area | AS-IS | TO-BE | GAP | Severidade | Prioridade |\n|----|------|-------|-------|-----|------------|------------|\n| G-PRD-01 | [Area] | [Atual] | [Necessario] | [O que falta] | Critical/High/Medium/Low | P0/P1/P2 |\n\n---\n\n## Glossario\n\n| Termo | Definicao |\n|-------|-----------|\n| [Termo 1] | [Definicao clara] |\n```\n\n**CHECKPOINT:**\n```markdown\nDocumento gerado: docs/01-Planejamento/02-prd.md\n\nPor favor, revise o PRD e responda:\n- ok — Aprovar e continuar para UX Concept\n- editar [requisito] — Ajustar requisito especifico\n- cancelar — Parar o workflow\n\nPerguntas de validacao:\n1. Os requisitos funcionais cobrem todos os cenarios?\n2. Os criterios de aceite sao verificaveis?\n3. Os GAPs de produto sao relevantes?\n```\n\n**AGUARDE** resposta antes de prosseguir.\n\n---\n\n### Fase 3: UX Concept\n\n**Agente:** `ux-researcher`\n**Output:** `docs/01-Planejamento/03-ux-concept.md`\n**Skills:** `ux-research`, `frontend-design`, `gap-analysis`\n**Referencia:** Leia `01-product-brief.md` e `02-prd.md`\n\n```markdown\n# UX Concept: {Nome do Projeto}\n\n## Metadados\n- **Baseado em:** 01-product-brief.md, 02-prd.md\n- **Data:** {YYYY-MM-DD}\n- **Autor:** AI UX Researcher\n- **Versao:** 1.0\n\n---\n\n## 1. Estrategia de UX\n\n### 1.1 Visao da Experiencia\n> [Uma frase descrevendo a experiencia ideal]\n\n### 1.2 Principios de UX\n1. **[Principio]:** [Como se aplica]\n2. **[Principio]:** [Como se aplica]\n3. **[Principio]:** [Como se aplica]\n\n### 1.3 Metricas de Experiencia\n| Metrica | Alvo | Como Medir |\n|---------|------|-----------|\n| Task Success Rate | > 90% | Testes de usabilidade |\n| Tempo na Tarefa Principal | < [N]s | Analytics |\n| Taxa de Erro | < 5% | Logs |\n| SUS Score | > 70 | Survey |\n\n---\n\n## 2. Arquitetura de Informacao\n\n### 2.1 Mapa da Aplicacao\n\n```mermaid\ngraph TD\n    A[Landing] --> B{Autenticado?}\n    B -->|Nao| C[Login/Register]\n    B -->|Sim| D[Dashboard]\n    D --> E[Secao A]\n    D --> F[Secao B]\n    D --> G[Configuracoes]\n```\n\n### 2.2 Padrao de Navegacao\n| Padrao | Justificativa | Lei UX |\n|--------|--------------|--------|\n| [Padrao] | [Por que] | [Lei aplicada] |\n\n### 2.3 Organizacao de Conteudo\n| Secao | Tipos de Conteudo | Prioridade | Frequencia |\n|-------|-------------------|------------|-----------|\n| [Secao] | [Tipos] | Primary/Secondary | Alta/Media/Baixa |\n\n---\n\n## 3. User Flows\n\n### 3.1 Flow: [Fluxo Principal]\n\n**Objetivo:** [O que o usuario quer]\n**Persona:** [Qual persona]\n\n```mermaid\nflowchart TD\n    START([Inicio]) --> A[Tela: Landing]\n    A --> B{Tem conta?}\n    B -->|Sim| C[Tela: Login]\n    B -->|Nao| D[Tela: Registro]\n    C --> E{Valido?}\n    E -->|Sim| F[Tela: Dashboard]\n    E -->|Nao| G[Erro]\n    G --> C\n    D --> H[Onboarding]\n    H --> F\n```\n\n**Passos:**\n| Step | Acao | Resposta | Tela | Lei UX |\n|------|------|---------|------|--------|\n| 1 | [Acao] | [Resposta] | [Tela] | [Lei] |\n\n### 3.2 Fluxos de Erro\n[Cenarios de erro e recuperacao]\n\n---\n\n## 4. Descricoes de Tela (Wireframes Textuais)\n\n### 4.1 Tela: [Nome]\n**Proposito:** [Por que existe]\n**Entrada:** [Como chega]\n**Saida:** [Para onde vai]\n\n**Layout:**\n```\n+--------------------------------------------------+\n| [Header: Logo | Navegacao | Menu Usuario]        |\n+--------------------------------------------------+\n| [Sidebar]  | [Area de Conteudo Principal]         |\n|            |                                      |\n|            | [Titulo da Secao]                    |\n|            | [Conteudo]                            |\n|            |                                      |\n|            | [Barra de Acoes: CTA Primario]       |\n+--------------------------------------------------+\n```\n\n**Elementos:**\n| Elemento | Tipo | Comportamento | Prioridade |\n|----------|------|--------------|------------|\n| [Elemento] | [Tipo] | [Interacao] | Primary/Secondary |\n\n**Estados:**\n| Estado | Trigger | Display |\n|--------|---------|---------|\n| Vazio | Sem dados | [Mensagem + CTA] |\n| Carregando | Fetch | [Skeleton] |\n| Erro | Falha | [Mensagem + retry] |\n| Sucesso | Acao ok | [Confirmacao] |\n\n---\n\n## 5. Avaliacao Heuristica (Nielsen's 10)\n\n| # | Heuristica | Status | Problemas | Severidade (0-4) | Fix |\n|---|-----------|--------|-----------|-------------------|-----|\n| 1 | Visibilidade do Status | Pass/Fail | [Issue] | [0-4] | [Fix] |\n| 2 | Correspondencia Sistema-Mundo | Pass/Fail | [Issue] | [0-4] | [Fix] |\n| 3 | Controle e Liberdade | Pass/Fail | [Issue] | [0-4] | [Fix] |\n| 4 | Consistencia e Padroes | Pass/Fail | [Issue] | [0-4] | [Fix] |\n| 5 | Prevencao de Erros | Pass/Fail | [Issue] | [0-4] | [Fix] |\n| 6 | Reconhecimento vs Memorizacao | Pass/Fail | [Issue] | [0-4] | [Fix] |\n| 7 | Flexibilidade e Eficiencia | Pass/Fail | [Issue] | [0-4] | [Fix] |\n| 8 | Estetica Minimalista | Pass/Fail | [Issue] | [0-4] | [Fix] |\n| 9 | Recuperacao de Erros | Pass/Fail | [Issue] | [0-4] | [Fix] |\n| 10 | Ajuda e Documentacao | Pass/Fail | [Issue] | [0-4] | [Fix] |\n\n---\n\n## 6. Mapa de Friccao\n\n| Fluxo | Passo | Tipo | Severidade (1-5) | Causa | Solucao | Prioridade |\n|-------|-------|------|------------------|-------|---------|------------|\n| [Fluxo] | [Passo] | Cognitiva/Interacao/Emocional | [1-5] | [Causa] | [Fix] | P0/P1/P2 |\n\n---\n\n## 7. Acessibilidade\n\n| Categoria | Criterio | Nivel | Status | Notas |\n|----------|----------|-------|--------|-------|\n| Perceptivel | Contraste 4.5:1 | AA | Pass/Fail | |\n| Operavel | Navegacao teclado | A | Pass/Fail | |\n| Compreensivel | Erros claros | A | Pass/Fail | |\n\n---\n\n## 8. GAP Analysis: Experiencia do Usuario\n\n> Skill: `gap-analysis` — Dimensao: Experience\n\n### 8.1 Flow Assessment\n| User Flow | Estado Atual | Estado Ideal | Friccoes | Severidade |\n|-----------|-------------|-------------|----------|------------|\n| [Fluxo] | [Atual] | [Ideal] | [Friccoes] | Critical/High/Medium/Low |\n\n### 8.2 UX Pattern Coverage\n| Padrao | Standard | Atual | GAP | Impacto |\n|--------|---------|-------|-----|---------|\n| Onboarding | [Best practice] | [O que existe] | [Falta] | High/Medium/Low |\n| Empty States | [Best practice] | [O que existe] | [Falta] | High/Medium/Low |\n\n### 8.3 Accessibility GAP\n| WCAG Criterion | Necessario | Atual | GAP | Fix |\n|----------------|----------|-------|-----|-----|\n| [Criterio] | AA | [Atual] | [Delta] | [Fix] |\n\n### 8.4 GAP Inventory\n| ID | Area | AS-IS | TO-BE | GAP | Severidade | Prioridade |\n|----|------|-------|-------|-----|------------|------------|\n| G-UX-01 | [Area] | [Atual] | [Necessario] | [Falta] | [Severidade] | P0/P1/P2 |\n```\n\n**CHECKPOINT:**\n```markdown\nDocumento gerado: docs/01-Planejamento/03-ux-concept.md\n\nPor favor, revise o UX Concept e responda:\n- ok — Aprovar e continuar para Architecture\n- editar [secao] — Ajustar secao especifica\n- cancelar — Parar o workflow\n```\n\n**AGUARDE** resposta antes de prosseguir.\n\n---\n\n### Fase 3.5: Visual Mockups [OBRIGATORIO se projeto tem UI]\n\n> **SKIP:** Apenas se o projeto NAO tem interface visual (API pura, CLI tool, backend-only).\n> **Para todos os projetos com UI:** Esta fase e OBRIGATORIA. Nao avancar para Fase 4 sem mockups aprovados.\n>\n> **Condicao de Ativacao:** HAS_UI=true (definido na Fase 0, pergunta #13)\n\n**Agente:** `frontend-specialist`\n**Output:** `docs/01-Planejamento/03.5-visual-mockups.md`\n**Skills:** `stitch-ui-design`, `frontend-design`\n**Referencia:** Leia `01-product-brief.md` e `03-ux-concept.md`\n\n**GATE DE BLOQUEIO (INVIOLAVEL):**\n> Se HAS_UI=true, a Fase 4 (Architecture) esta **BLOQUEADA** ate que:\n> 1. O arquivo `docs/01-Planejamento/03.5-visual-mockups.md` exista E tenha conteudo\n> 2. **TODAS** as telas identificadas no UX Concept tenham prototipo correspondente\n> 3. O usuario aprove os mockups com \"ok\"\n>\n> **Cobertura total obrigatoria:** O agente NAO pode se contentar com prototipar 1 ou 2 telas.\n> Cada tela documentada na Section 4 do UX Concept DEVE ter seu prototipo gerado.\n\n**Processo:**\n\n1. **Verificar disponibilidade do Stitch MCP**\n   - Invocar `mcp__stitch__list_projects` para confirmar conectividade\n   - **Se Stitch DISPONIVEL:** Uso e OBRIGATORIO — gerar prototipos via Stitch para TODAS as telas\n   - **Se Stitch NAO DISPONIVEL e HAS_UI=true:** **PARAR** e informar usuario para configurar Stitch MCP antes de continuar\n   - Se HAS_UI=false: pular para Fase 4\n\n2. **Extrair lista completa de telas**\n   - Ler Section 4 do UX Concept (Descricoes de Tela / Wireframes Textuais)\n   - Ler Section 3 (User Flows) para identificar telas referenciadas nos fluxos\n   - Ler PRD Section 3 (Fluxos de Usuario) para telas de edge case\n   - **Montar lista exaustiva:** Cada tela = 1 item obrigatorio para prototipagem\n   - Incluir telas de estado: Empty, Error, Loading, Success (para telas criticas)\n   - Incluir telas de edge case: 404, Offline, Permission Denied (se documentadas)\n\n3. **Criar projeto Stitch**\n   - Invocar `mcp__stitch__create_project` com titulo do projeto\n   - Registrar Project ID\n\n4. **Converter wireframes em prompts**\n   - Carregar skill `stitch-ui-design` → ler `wireframe-to-prompt.md`\n   - Aplicar algoritmo de conversao de 7 passos para CADA tela da lista\n\n5. **Gerar TODAS as telas via Stitch**\n   - Telas-chave (Dashboard, Landing, Onboarding): GEMINI_3_PRO + MOBILE + DESKTOP\n   - Telas secundarias (Settings, Lists, Forms): GEMINI_3_FLASH + MOBILE\n   - Respeitar regras anti-cliche do `@frontend-specialist`\n   - **NAO parar ate que todas as telas da lista estejam geradas**\n\n6. **Validar cobertura (OBRIGATORIO antes do checkpoint)**\n   - Comparar lista de telas extraida (passo 2) com telas geradas (passo 5)\n   - Se alguma tela da lista NAO tem prototipo: **GERAR** antes de prosseguir\n   - Preencher tabela de cobertura no documento de output (ver template abaixo)\n\n6. **Documentar resultados**\n   - Criar arquivo de output com template abaixo\n\n```markdown\n# Visual Mockups: {Nome do Projeto}\n\n## Metadados\n- **Baseado em:** 03-ux-concept.md\n- **Data:** {YYYY-MM-DD}\n- **Autor:** AI Frontend Specialist (via Stitch MCP)\n- **Stitch Project ID:** {project_id}\n\n---\n\n## Telas Geradas\n\n| # | Tela | Device | Screen ID | Modelo | Status |\n|---|------|--------|-----------|--------|--------|\n| 1 | [Nome] | MOBILE | [id] | PRO | Pendente |\n| 2 | [Nome] | DESKTOP | [id] | FLASH | Pendente |\n\n---\n\n## Cobertura\n\n| Tela do UX Concept | MOBILE | DESKTOP | Estados |\n|---------------------|--------|---------|---------|\n| [Tela 1] | Sim | Sim | Success |\n| [Tela 2] | Sim | Nao | Success, Empty |\n\n---\n\n## Insights para Design System\n\n- **Cor primaria observada:** [cor dos mockups]\n- **Estilo tipografico:** [serif/sans/display]\n- **Geometria:** [sharp/rounded/mixed]\n- **Padroes notaveis:** [padroes de UI dos mockups]\n\n---\n\n## Notas\n- Mockups sao referencia visual, nao source of truth\n- Design System (Fase 7) formaliza as decisoes de design\n- IDs de telas podem ser usados para iteracao futura via Stitch\n```\n\n**CHECKPOINT:**\n```markdown\nDocumento gerado: docs/01-Planejamento/03.5-visual-mockups.md\n\n**Cobertura de Telas:**\n- Total de telas no UX Concept: [N]\n- Telas prototipadas via Stitch: [N]\n- Cobertura: [N/N] = [100%]\n\nForam geradas [N] telas visuais via Stitch MCP.\n\nPor favor, revise os mockups e responda:\n- ok — Aprovar e continuar para Architecture\n- refinar [tela] — Regenerar tela especifica com feedback\n- faltou [tela] — Adicionar tela que nao foi prototipada\n- cancelar — Parar o workflow\n\n> **GATE DE BLOQUEIO:** Se cobertura < 100%, BLOQUEAR avanco para Fase 4.\n> Gerar telas faltantes antes de pedir aprovacao.\n```\n\n**AGUARDE** resposta antes de prosseguir.\n\n---\n\n### Fase 4: Architecture\n\n**Agente:** `project-planner`\n**Output:** `docs/01-Planejamento/04-architecture.md`\n**Skills:** `architecture`, `system-design`, `gap-analysis`\n**Referencia:** Leia todos os documentos anteriores\n\n```markdown\n# Architecture: {Nome do Projeto}\n\n## Metadados\n- **Baseado em:** Brief, PRD, UX Concept\n- **Data:** {YYYY-MM-DD}\n- **Versao:** 1.0\n\n---\n\n## 1. System Context (C4 Level 1)\n\n### 1.1 Atores\n| Ator | Tipo | Descricao | Interacao |\n|------|------|-----------|-----------|\n| [Ator] | Pessoa/Sistema | [Quem] | [Como interage] |\n\n### 1.2 Sistemas Externos\n| Sistema | Protocolo | Dados Trocados |\n|---------|----------|----------------|\n| [Sistema] | REST/gRPC | [Dados] |\n\n### 1.3 Diagrama de Contexto\n```mermaid\ngraph TB\n    U[Usuario] -->|HTTPS| S[Sistema]\n    S -->|REST| E1[API Externa]\n    S -->|SQL| DB[(Database)]\n```\n\n---\n\n## 2. Container Diagram (C4 Level 2)\n\n| Container | Tecnologia | Proposito | Comunica Com |\n|-----------|------------|---------|--------------|\n| Web App | [Tech] | UI | API Server |\n| API Server | [Tech] | Logica | Database |\n| Database | [Tech] | Storage | API Server |\n\n```mermaid\ngraph TB\n    WEB[Web App] -->|HTTPS| API[API Server]\n    API --> DB[(Database)]\n    API --> CACHE[(Cache)]\n```\n\n---\n\n## 3. Padrao Arquitetural\n\n### 3.1 Decisoes\n| Aspecto | Decisao | Justificativa |\n|---------|---------|---------------|\n| Padrao | [Monolith/Microservices/etc.] | [Por que] |\n| Comunicacao | [REST/GraphQL/gRPC] | [Por que] |\n| Renderizacao | [SSR/SSG/SPA] | [Por que] |\n\n### 3.2 ADRs\n\n#### ADR-001: [Titulo]\n**Status:** Accepted\n**Contexto:** [Situacao]\n**Decisao:** [O que e por que]\n**Alternativas:**\n| Alternativa | Pros | Contras | Motivo Rejeicao |\n|------------|------|---------|-----------------|\n| [Opcao A] | [Pros] | [Contras] | [Razao] |\n**Consequencias:** [Positivas e negativas]\n\n---\n\n## 4. Database Design\n\n### 4.1 Diagrama ER\n```mermaid\nerDiagram\n    USER ||--o{ ENTITY : \"has many\"\n    USER {\n        uuid id PK\n        string email UK\n        string name\n        timestamp created_at\n    }\n```\n\n### 4.2 Schemas Detalhados\n\n#### Tabela: users\n| Coluna | Tipo | Constraints | Default | Descricao |\n|--------|------|-------------|---------|-----------|\n| id | UUID | PK | gen_random_uuid() | ID unico |\n| email | VARCHAR(255) | UNIQUE, NOT NULL | - | Email |\n| created_at | TIMESTAMP | NOT NULL | now() | Criacao |\n\n**Indices:**\n| Nome | Colunas | Tipo | Proposito |\n|------|---------|------|-----------|\n| users_pkey | id | PRIMARY | PK |\n| users_email_key | email | UNIQUE | Busca |\n\n[Repetir para cada tabela]\n\n### 4.3 Relacionamentos\n| Origem | Destino | Tipo | FK | On Delete |\n|--------|---------|------|-----|-----------|\n| users | [entity] | 1:N | [entity].user_id | RESTRICT |\n\n### 4.4 Migrations\n1. `001_create_users.sql`\n2. `002_create_[entities].sql`\n3. `003_add_indexes.sql`\n\n---\n\n## 5. Integracoes e Data Flow\n\n### 5.1 Inventario\n| Integracao | Proposito | Protocolo | Auth | Fallback | Prioridade |\n|-----------|---------|----------|------|----------|----------|\n| [Servico] | [Para que] | REST | API Key | [Fallback] | MVP |\n\n### 5.2 Data Flow\n| Fluxo | Origem | Destino | Dados | Frequencia |\n|-------|--------|---------|-------|-----------|\n| [Fluxo] | [De] | [Para] | [Dados] | [Freq] |\n\n---\n\n## 6. Seguranca\n\n### 6.1 Autenticacao e Autorizacao\n| Aspecto | Decisao | Justificativa |\n|---------|---------|---------------|\n| Metodo | [JWT/Session/OAuth] | [Por que] |\n| Modelo | [RBAC/ABAC] | [Por que] |\n\n### 6.2 Checklist\n- [ ] Auth strategy definida (ADR)\n- [ ] Rate limiting planejado\n- [ ] Validacao de input\n- [ ] CORS configurado\n- [ ] Gestao de secrets\n- [ ] HTTPS obrigatorio\n\n---\n\n## 7. Infraestrutura\n\n### 7.1 Ambientes\n| Ambiente | URL | Database | Deploy Trigger |\n|----------|-----|----------|---------------|\n| Dev | localhost | Local | Manual |\n| Staging | staging.app.com | Copia | PR merge |\n| Production | app.com | Producao | Release |\n\n### 7.2 Scaling\n| Nivel | Usuarios | Estrategia |\n|-------|---------|-----------|\n| Launch | 0-100 | Single instance |\n| Growth | 100-1K | Horizontal |\n| Scale | 1K-10K | Distributed |\n\n### 7.3 Observabilidade\n| Camada | Monitorar | Ferramentas | Prioridade |\n|--------|----------|-------------|----------|\n| App | Erros, latencia | Sentry | P0 |\n| Infra | CPU, memoria | Platform | P1 |\n| Business | Signups | PostHog | P1 |\n\n---\n\n## 8. GAP Analysis: Infraestrutura\n\n> Skill: `gap-analysis` — Dimensao: Infrastructure\n\n### 8.1 Architecture Assessment\n| Componente | Atual | Necessario | GAP | Esforco |\n|-----------|-------|-----------|-----|---------|\n| [Componente] | [Atual] | [Necessario] | [Delta] | S/M/L/XL |\n\n### 8.2 Scalability Assessment\n| Dimensao | Atual | 6mo | 12mo | GAP |\n|----------|-------|-----|------|-----|\n| Usuarios | [N] | [N] | [N] | [Delta] |\n\n### 8.3 Technical Debt\n| Debito | Impacto | Risco Futuro | Esforco | Prioridade |\n|--------|---------|-------------|---------|------------|\n| [Debito] | [Impacto] | [Risco] | S/M/L/XL | P0/P1/P2 |\n\n### 8.4 GAP Inventory\n| ID | Area | AS-IS | TO-BE | GAP | Severidade | Prioridade |\n|----|------|-------|-------|-----|------------|------------|\n| G-ARCH-01 | [Area] | [Atual] | [Necessario] | [Falta] | [Severidade] | P0/P1/P2 |\n```\n\n**CHECKPOINT:**\n```markdown\nDocumento gerado: docs/01-Planejamento/04-architecture.md\n\nPor favor, revise e responda: ok / editar [secao] / cancelar\n```\n\n**AGUARDE** resposta antes de prosseguir.\n\n---\n\n### Fase 5: Security\n\n**Agente:** `security-auditor`\n**Output:** `docs/01-Planejamento/05-security.md`\n**Skills:** `vulnerability-scanner`, `gap-analysis`\n**Referencia:** Leia Brief, PRD, UX Concept e Architecture\n\n```markdown\n# Security: {Nome do Projeto}\n\n## Metadados\n- **Baseado em:** Brief, PRD, UX Concept, Architecture\n- **Data:** {YYYY-MM-DD}\n- **Autor:** AI Security Auditor\n- **Versao:** 1.0\n\n---\n\n## 1. Security Overview\n\n### 1.1 Classificacao do Sistema\n| Aspecto | Valor |\n|---------|-------|\n| **Dados sensiveis** | Sim/Nao — [Que tipo: PII, financeiro, saude] |\n| **Compliance obrigatorio** | [LGPD / GDPR / SOC2 / HIPAA / Nenhum] |\n| **Nivel de risco** | Critico / Alto / Medio / Baixo |\n| **Exposicao** | Internet-facing / Intranet / Hybrid |\n\n### 1.2 Principios de Seguranca\n1. **Defense in Depth** — Multiplas camadas de protecao\n2. **Least Privilege** — Minimo acesso necessario\n3. **Zero Trust** — Nunca confiar, sempre verificar\n4. **Secure by Default** — Seguro na configuracao padrao\n\n---\n\n## 2. Threat Model\n\n### 2.1 Atores de Ameaca\n| Ator | Motivacao | Capacidade | Probabilidade |\n|------|-----------|-----------|---------------|\n| Script Kiddie | Vandalismo | Baixa (ferramentas automaticas) | Alta |\n| Atacante Externo | Dados/Financeiro | Media (exploits conhecidos) | Media |\n| Insider Malicioso | Dados/Sabotagem | Alta (acesso interno) | Baixa |\n| Competidor | Espionagem | Media | Baixa |\n\n### 2.2 Superficie de Ataque\n| Superficie | Componentes Expostos | Risco | Mitigacao |\n|-----------|---------------------|-------|-----------|\n| **Web Frontend** | Formularios, uploads, URLs | [Risco] | [Mitigacao] |\n| **API** | Endpoints publicos, auth | [Risco] | [Mitigacao] |\n| **Database** | Queries, stored data | [Risco] | [Mitigacao] |\n| **Integracoes** | APIs terceiros, webhooks | [Risco] | [Mitigacao] |\n| **Infraestrutura** | DNS, CDN, hosting | [Risco] | [Mitigacao] |\n\n### 2.3 Diagrama de Ameacas (STRIDE)\n```mermaid\ngraph TB\n    subgraph \"Trust Boundary: Internet\"\n        USER[Usuario] -->|HTTPS| WAF[WAF/CDN]\n    end\n    subgraph \"Trust Boundary: Application\"\n        WAF --> WEB[Web App]\n        WEB --> API[API Server]\n    end\n    subgraph \"Trust Boundary: Data\"\n        API --> DB[(Database)]\n        API --> CACHE[(Cache)]\n    end\n    style WAF fill:#f9f,stroke:#333\n    style API fill:#ff9,stroke:#333\n    style DB fill:#9ff,stroke:#333\n```\n\n---\n\n## 3. OWASP Top 10 Assessment\n\n| # | Vulnerabilidade | Aplicavel? | Risco | Mitigacao Planejada | Status |\n|---|----------------|-----------|-------|---------------------|--------|\n| A01 | Broken Access Control | Sim/Nao | [Risco] | [Mitigacao] | Planejado/Implementado |\n| A02 | Cryptographic Failures | Sim/Nao | [Risco] | [Mitigacao] | Planejado/Implementado |\n| A03 | Injection (SQL, XSS, etc) | Sim/Nao | [Risco] | [Mitigacao] | Planejado/Implementado |\n| A04 | Insecure Design | Sim/Nao | [Risco] | [Mitigacao] | Planejado/Implementado |\n| A05 | Security Misconfiguration | Sim/Nao | [Risco] | [Mitigacao] | Planejado/Implementado |\n| A06 | Vulnerable Components | Sim/Nao | [Risco] | [Mitigacao] | Planejado/Implementado |\n| A07 | Auth & Identity Failures | Sim/Nao | [Risco] | [Mitigacao] | Planejado/Implementado |\n| A08 | Software & Data Integrity | Sim/Nao | [Risco] | [Mitigacao] | Planejado/Implementado |\n| A09 | Security Logging & Monitoring | Sim/Nao | [Risco] | [Mitigacao] | Planejado/Implementado |\n| A10 | Server-Side Request Forgery | Sim/Nao | [Risco] | [Mitigacao] | Planejado/Implementado |\n\n---\n\n## 4. Autenticacao e Autorizacao\n\n### 4.1 Estrategia de Auth\n| Aspecto | Decisao | Justificativa |\n|---------|---------|---------------|\n| Metodo | [JWT / Session / OAuth 2.0 / Passkeys] | [Por que] |\n| Provider | [Clerk / Auth0 / NextAuth / Custom] | [Por que] |\n| MFA | [Sim/Nao] — [TOTP / SMS / WebAuthn] | [Por que] |\n| Session Duration | [Tempo] | [Por que] |\n| Refresh Strategy | [Rotation / Sliding / Fixed] | [Por que] |\n\n### 4.2 Modelo de Autorizacao\n| Aspecto | Decisao |\n|---------|---------|\n| Modelo | [RBAC / ABAC / ReBAC] |\n| Roles | [Admin, User, Viewer, etc.] |\n| Granularidade | [Por recurso / Por acao / Por campo] |\n\n### 4.3 Matriz de Permissoes\n| Recurso | Admin | User | Viewer | Anonimo |\n|---------|-------|------|--------|---------|\n| [Recurso A] | CRUD | CR | R | - |\n| [Recurso B] | CRUD | CRU | R | R |\n| [Admin Panel] | CRUD | - | - | - |\n\n---\n\n## 5. Protecao de Dados\n\n### 5.1 Classificacao de Dados\n| Dado | Classificacao | Armazenamento | Encriptacao | Retencao |\n|------|-------------|---------------|-------------|----------|\n| Password | Critico | Hash (bcrypt/argon2) | At rest | Indefinido |\n| Email | PII | Plaintext | At rest + transit | Ate exclusao |\n| Tokens | Critico | Memory/HttpOnly cookie | Transit | Session duration |\n| Logs | Interno | Log service | Transit | 90 dias |\n\n### 5.2 Compliance\n| Regulamento | Aplicavel? | Requisitos Chave | Status |\n|-------------|-----------|-----------------|--------|\n| LGPD | Sim/Nao | Consentimento, direito ao esquecimento, DPO | [Status] |\n| GDPR | Sim/Nao | Same + data portability, DPA | [Status] |\n| SOC 2 | Sim/Nao | Security, availability, processing integrity | [Status] |\n\n### 5.3 Privacy by Design\n- [ ] Coleta minima de dados (so o necessario)\n- [ ] Consentimento explicito para dados sensiveis\n- [ ] Direito de exclusao implementado\n- [ ] Exportacao de dados do usuario\n- [ ] Logs de acesso a dados pessoais\n- [ ] Anonimizacao de dados em ambientes nao-producao\n\n---\n\n## 6. Seguranca de API\n\n### 6.1 Protecoes\n| Protecao | Implementacao | Configuracao |\n|----------|---------------|-------------|\n| Rate Limiting | [Lib/Service] | [Limites por endpoint] |\n| Input Validation | [Zod / Joi / custom] | Schema-based |\n| CORS | [Configuracao] | [Origins permitidas] |\n| CSRF Protection | [Token / SameSite] | [Estrategia] |\n| Content Security Policy | [Headers] | [Diretivas] |\n| HTTP Security Headers | [Helmet / custom] | HSTS, X-Frame, etc. |\n\n### 6.2 Endpoints Sensiveis\n| Endpoint | Risco | Protecoes Especificas |\n|----------|-------|----------------------|\n| POST /auth/login | Brute force | Rate limit, captcha apos N falhas |\n| POST /auth/register | Spam accounts | Rate limit, email verification |\n| DELETE /users/:id | Data loss | Auth + confirmation + soft delete |\n| GET /admin/* | Privilege escalation | RBAC + IP whitelist |\n\n---\n\n## 7. Seguranca de Infraestrutura\n\n### 7.1 Network Security\n| Camada | Protecao | Ferramenta |\n|--------|----------|-----------|\n| Edge | WAF, DDoS protection | [Cloudflare / AWS WAF] |\n| Transport | TLS 1.3, HSTS | [Auto / Manual] |\n| Application | CSP, CORS | [Headers config] |\n| Data | Encryption at rest | [DB encryption / disk] |\n\n### 7.2 Secret Management\n| Secret | Armazenamento | Rotacao | Acesso |\n|--------|---------------|---------|--------|\n| API Keys | [Env vars / Vault] | [Frequencia] | [Quem] |\n| DB Credentials | [Env vars / Vault] | [Frequencia] | [Quem] |\n| JWT Secret | [Env vars / Vault] | [Frequencia] | [Quem] |\n| Encryption Keys | [KMS / Vault] | [Frequencia] | [Quem] |\n\n---\n\n## 8. Incident Response Plan\n\n### 8.1 Classificacao de Incidentes\n| Severidade | Definicao | Tempo de Resposta | Exemplo |\n|-----------|-----------|-------------------|---------|\n| P0 - Critico | Data breach, system down | Imediato | Vazamento de dados |\n| P1 - Alto | Vulnerabilidade explorada | < 4h | SQL injection detectado |\n| P2 - Medio | Vulnerabilidade descoberta | < 24h | Dependencia com CVE |\n| P3 - Baixo | Best practice violation | < 1 semana | Header faltando |\n\n### 8.2 Procedimento\n1. **Detectar** — Monitoring, alerts, reports\n2. **Conter** — Isolar sistema afetado\n3. **Investigar** — Root cause analysis\n4. **Remediar** — Fix + deploy\n5. **Comunicar** — Stakeholders + usuarios (se necessario)\n6. **Prevenir** — Post-mortem + melhorias\n\n---\n\n## 9. Security Testing Plan\n\n| Tipo | Ferramenta | Frequencia | Responsavel |\n|------|-----------|-----------|-------------|\n| SAST (Static Analysis) | [ESLint security / Semgrep] | Cada PR | CI/CD |\n| Dependency Audit | [npm audit / Snyk] | Diario | CI/CD |\n| DAST (Dynamic Analysis) | [OWASP ZAP] | Semanal | Security |\n| Penetration Testing | [Manual / Bug bounty] | Trimestral | External |\n| Secret Scanning | [GitGuardian / trufflehog] | Cada commit | CI/CD |\n\n---\n\n## 10. GAP Analysis: Seguranca\n\n> Skill: `gap-analysis` — Dimensao: Security\n\n### 10.1 OWASP Coverage\n| Vulnerabilidade OWASP | Mitigacao Necessaria | Estado Atual | GAP | Prioridade |\n|----------------------|---------------------|-------------|-----|------------|\n| A01: Broken Access Control | RBAC + RLS | [Atual] | [Delta] | P0/P1/P2 |\n| A03: Injection | Input validation + ORM | [Atual] | [Delta] | P0/P1/P2 |\n| A07: Auth Failures | MFA + session mgmt | [Atual] | [Delta] | P0/P1/P2 |\n\n### 10.2 Compliance GAP\n| Requisito | Regulamento | Estado Atual | Estado Necessario | GAP | Esforco |\n|-----------|-----------|-------------|------------------|-----|---------|\n| Consentimento | LGPD | [Atual] | [Necessario] | [Delta] | S/M/L/XL |\n| Data Encryption | LGPD/GDPR | [Atual] | [Necessario] | [Delta] | S/M/L/XL |\n\n### 10.3 Security Controls GAP\n| Controle | Necessario | Existe | Status | GAP | Prioridade |\n|----------|----------|--------|--------|-----|------------|\n| WAF | Sim/Nao | Sim/Nao | [Status] | [Delta] | P0/P1/P2 |\n| Rate Limiting | Sim/Nao | Sim/Nao | [Status] | [Delta] | P0/P1/P2 |\n| Secret Rotation | Sim/Nao | Sim/Nao | [Status] | [Delta] | P0/P1/P2 |\n| Audit Logging | Sim/Nao | Sim/Nao | [Status] | [Delta] | P0/P1/P2 |\n\n### 10.4 GAP Inventory\n| ID | Area | AS-IS | TO-BE | GAP | Severidade | Prioridade |\n|----|------|-------|-------|-----|------------|------------|\n| G-SEC-01 | [Area] | [Atual] | [Necessario] | [Falta] | [Severidade] | P0/P1/P2 |\n```\n\n**CHECKPOINT:**\n```markdown\nDocumento gerado: docs/01-Planejamento/05-security.md\n\nPor favor, revise e responda: ok / editar [secao] / cancelar\n```\n\n**AGUARDE** resposta antes de prosseguir.\n\n---\n\n### Fase 6: Stack\n\n**Agente:** `project-planner`\n**Output:** `docs/01-Planejamento/06-stack.md`\n**Skills:** `app-builder`, `architecture`, `gap-analysis`\n**Referencia:** Leia todos os documentos anteriores (especialmente Architecture e Security)\n\n```markdown\n# Stack: {Nome do Projeto}\n\n## Metadados\n- **Baseado em:** Brief, PRD, Architecture\n- **Data:** {YYYY-MM-DD}\n- **Versao:** 1.0\n\n---\n\n## 1. Stack por Camada\n\n| Camada | Tecnologia | Versao | Justificativa | Alternativas |\n|--------|------------|--------|---------------|-------------|\n| Framework Frontend | [Tech] | [Versao] | [Por que] | [Alt] |\n| Linguagem | [Tech] | [Versao] | [Por que] | [Alt] |\n| Styling | [Tech] | [Versao] | [Por que] | [Alt] |\n| State Management | [Tech] | [Versao] | [Por que] | [Alt] |\n| Backend Runtime | [Tech] | [Versao] | [Por que] | [Alt] |\n| Database | [Tech] | [Versao] | [Por que] | [Alt] |\n| ORM | [Tech] | [Versao] | [Por que] | [Alt] |\n| Auth | [Provider] | [-] | [Por que] | [Alt] |\n| Hosting | [Platform] | [-] | [Por que] | [Alt] |\n\n---\n\n## 2. Compatibilidade\n\n### 2.1 Matriz de Compatibilidade\n| Pacote A | Pacote B | Compativel? | Notas |\n|----------|----------|-------------|-------|\n| [A] | [B] | Sim/Nao | [Notas] |\n\n### 2.2 Deprecation Watch\n| Tecnologia | Versao Atual | EOL | Acao |\n|------------|-------------|-----|------|\n| [Tech] | [Versao] | [Data] | [Acao] |\n\n---\n\n## 3. Dependencias\n\n### 3.1 Core (dependencies)\n| Pacote | Versao | Proposito | Tamanho |\n|--------|--------|---------|---------|\n| [Pacote] | [Versao] | [Para que] | [KB] |\n\n### 3.2 Dev (devDependencies)\n| Pacote | Versao | Proposito |\n|--------|--------|---------|\n| [Pacote] | [Versao] | [Para que] |\n\n---\n\n## 4. Tooling\n\n### 4.1 Developer Experience\n| Ferramenta | Proposito | Config |\n|------------|---------|-------|\n| ESLint | Linting | eslint.config.js |\n| Prettier | Formatting | .prettierrc |\n| TypeScript | Types | tsconfig.json |\n\n### 4.2 Testing Stack\n| Tipo | Ferramenta | Config |\n|------|-----------|-------|\n| Unit | [Vitest/Jest] | vitest.config.ts |\n| E2E | [Playwright] | playwright.config.ts |\n\n### 4.3 CI/CD\n| Stage | Ferramenta | Trigger |\n|-------|-----------|---------|\n| Build | [Tool] | PR/Push |\n| Test | [Tool] | PR |\n| Deploy | [Platform] | Merge to main |\n\n---\n\n## 5. Estrutura de Arquivos\n\n```\nproject/\n├── src/\n│   ├── app/            # Pages / Routes\n│   ├── components/     # Shared components\n│   ├── lib/            # Utilities\n│   ├── hooks/          # Custom hooks\n│   ├── services/       # API clients\n│   ├── types/          # TypeScript types\n│   └── styles/         # Global styles\n├── prisma/             # Database\n├── public/             # Static assets\n├── tests/              # Tests\n└── docs/               # Documentation\n```\n\n---\n\n## 6. GAP Analysis: Tecnologia\n\n> Skill: `gap-analysis` — Dimensao: Technology\n\n### 6.1 Stack Atual vs Necessaria\n| Camada | Atual | Necessaria | Motivo | Esforco |\n|--------|-------|-----------|--------|---------|\n| [Camada] | [Atual/N/A] | [Necessaria] | [Por que] | S/M/L/XL |\n\n### 6.2 Versoes e Deprecations\n| Tech | Atual | Ultima Estavel | EOL | Acao |\n|------|-------|---------------|-----|------|\n| [Tech] | [Atual] | [Ultima] | [Data] | [Acao] |\n\n### 6.3 Bibliotecas Faltantes\n| Necessidade | Solucao | Alternativas | Prioridade |\n|-------------|---------|-------------|------------|\n| [Need] | [Lib] | [Alt] | P0/P1/P2 |\n\n### 6.4 GAP Inventory\n| ID | Area | AS-IS | TO-BE | GAP | Severidade | Prioridade |\n|----|------|-------|-------|-----|------------|------------|\n| G-STACK-01 | [Area] | [Atual] | [Necessario] | [Falta] | [Severidade] | P0/P1/P2 |\n```\n\n**CHECKPOINT:**\n```markdown\nDocumento gerado: docs/01-Planejamento/06-stack.md\n\nPor favor, revise e responda: ok / editar [secao] / cancelar\n```\n\n**AGUARDE** resposta antes de prosseguir.\n\n---\n\n### Fase 7: Design System\n\n**Agente:** `frontend-specialist`\n**Output:** `docs/01-Planejamento/07-design-system.md`\n**Skills:** `frontend-design`, `tailwind-patterns`, `gap-analysis`\n**Referencia:** Leia TODOS os documentos anteriores\n\n```markdown\n# Design System: {Nome do Projeto}\n\n## Metadados\n- **Baseado em:** Brief, PRD, UX Concept, Stack\n- **Data:** {YYYY-MM-DD}\n- **Framework CSS:** [Tailwind / CSS Modules / etc.]\n\n---\n\n## 1. Fundamentos\n\n### 1.1 Principios de Design\n1. **[Principio 1]:** [Descricao]\n2. **[Principio 2]:** [Descricao]\n3. **[Principio 3]:** [Descricao]\n\n### 1.2 Tom Visual\n- **Personalidade:** [Ex: Profissional mas acessivel]\n- **Sensacao:** [Ex: Confianca, modernidade]\n\n---\n\n## 2. Paleta de Cores\n\n### 2.1 Cores Primarias\n| Token | Hex | RGB | Uso |\n|-------|-----|-----|-----|\n| --color-primary-50 | #[HEX] | rgb(R,G,B) | Backgrounds |\n| --color-primary-500 | #[HEX] | rgb(R,G,B) | Botoes, links |\n| --color-primary-600 | #[HEX] | rgb(R,G,B) | Hover |\n| --color-primary-900 | #[HEX] | rgb(R,G,B) | Texto |\n\n### 2.2 Cores Semanticas\n| Token | Hex | Uso |\n|-------|-----|-----|\n| --color-success | #[HEX] | Confirmacoes |\n| --color-warning | #[HEX] | Alertas |\n| --color-error | #[HEX] | Erros |\n| --color-info | #[HEX] | Informacoes |\n\n### 2.3 Cores Neutras\n| Token | Hex | Uso |\n|-------|-----|-----|\n| --color-gray-50 | #[HEX] | Background |\n| --color-gray-200 | #[HEX] | Bordas |\n| --color-gray-600 | #[HEX] | Texto secundario |\n| --color-gray-900 | #[HEX] | Texto principal |\n\n### 2.4 Dark Mode (se aplicavel)\n| Light | Dark | Mapeamento |\n|-------|------|------------|\n| gray-50 | gray-900 | Background |\n| gray-900 | gray-50 | Texto |\n\n---\n\n## 3. Tipografia\n\n### 3.1 Familias\n| Proposito | Fonte | Fallback |\n|-----------|-------|----------|\n| Headlines | [Fonte] | system-ui |\n| Body | [Fonte] | system-ui |\n| Code | [Fonte] | monospace |\n\n### 3.2 Escala\n| Token | Tamanho | Line Height | Uso |\n|-------|---------|-------------|-----|\n| --text-xs | 12px | 1.5 | Labels |\n| --text-sm | 14px | 1.5 | Body small |\n| --text-base | 16px | 1.5 | Body |\n| --text-lg | 18px | 1.5 | Body large |\n| --text-xl | 20px | 1.4 | H4 |\n| --text-2xl | 24px | 1.3 | H3 |\n| --text-3xl | 30px | 1.2 | H2 |\n| --text-4xl | 36px | 1.1 | H1 |\n\n---\n\n## 4. Espacamento (Base 8px)\n\n| Token | Valor | Uso |\n|-------|-------|-----|\n| --space-1 | 4px | Gaps minimos |\n| --space-2 | 8px | Padding interno |\n| --space-4 | 16px | Cards, botoes |\n| --space-6 | 24px | Secoes |\n| --space-8 | 32px | Blocos |\n| --space-12 | 48px | Secoes maiores |\n\n---\n\n## 5. Layout\n\n### Breakpoints\n| Nome | Min-width | Uso |\n|------|-----------|-----|\n| sm | 640px | Tablet portrait |\n| md | 768px | Tablet landscape |\n| lg | 1024px | Desktop |\n| xl | 1280px | Desktop grande |\n\n### Grid: 12 colunas, gutter 24px (desktop) / 16px (mobile)\n\n---\n\n## 6. Componentes\n\n### Buttons\n| Variante | Uso |\n|----------|-----|\n| Primary | Acao principal |\n| Secondary | Acoes secundarias |\n| Outline | Acoes terciarias |\n| Ghost | Acoes sutis |\n| Destructive | Acoes perigosas |\n\n**Estados:** Default, Hover, Active, Focus, Disabled, Loading\n**Tamanhos:** Small (32px), Default (40px), Large (48px)\n\n### Inputs\n**Tipos:** Text, Textarea, Select, Checkbox, Radio, Toggle\n**Estados:** Default, Hover, Focus, Error, Disabled\n\n### Cards, Modals, Alerts, Tables, Tooltips, Skeletons\n[Especificar variantes, tamanhos e estados para cada]\n\n---\n\n## 7. Iconografia\n- **Biblioteca:** [Heroicons / Lucide / Phosphor]\n- **Tamanhos:** 16px, 20px, 24px\n\n---\n\n## 8. Animacoes\n| Duracao | Valor | Uso |\n|---------|-------|-----|\n| Fast | 100ms | Hovers |\n| Default | 200ms | Transicoes |\n| Slow | 300ms | Modais |\n\n---\n\n## 9. Acessibilidade\n- [ ] Contraste 4.5:1 texto\n- [ ] Contraste 3:1 graficos\n- [ ] Focus states visiveis\n- [ ] Labels em inputs\n- [ ] Navegacao teclado\n\n---\n\n## 10. GAP Analysis: Design\n\n> Skill: `gap-analysis` — Dimensao: Design\n\n### 10.1 Component Coverage\n| Componente | Necessario | Existe | GAP | Prioridade |\n|-----------|-----------|--------|-----|------------|\n| [Comp] | Sim | Sim/Nao | [Delta] | P0/P1/P2 |\n\n### 10.2 Token Coverage\n| Categoria | Definidos | Faltantes | % |\n|----------|----------|----------|---|\n| Cores | [N] | [N] | [%] |\n| Tipografia | [N] | [N] | [%] |\n| Espacamento | [N] | [N] | [%] |\n\n### 10.3 GAP Inventory\n| ID | Area | AS-IS | TO-BE | GAP | Severidade | Prioridade |\n|----|------|-------|-------|-----|------------|------------|\n| G-DS-01 | [Area] | [Atual] | [Necessario] | [Falta] | [Severidade] | P0/P1/P2 |\n```\n\n**CHECKPOINT:**\n```markdown\nDocumento gerado: docs/01-Planejamento/07-design-system.md\n\nPor favor, revise e responda: ok / editar [secao] / cancelar\n```\n\n**AGUARDE** resposta antes de prosseguir.\n\n---\n\n### Fase 8: Backlog (Consolidacao de GAPs)\n\n**Agente:** `product-owner`\n**Output:** `docs/BACKLOG.md`\n**Skills:** `plan-writing`, `gap-analysis`\n**Referencia:** Leia TODOS os 7 documentos anteriores\n\n```markdown\n# Backlog: {Nome do Projeto}\n\n> Gerado a partir dos documentos de planejamento com GAPs consolidados.\n\n**Ultima Atualizacao:** {YYYY-MM-DD HH:MM}\n**Total de Tarefas:** {N}\n**Progresso:** 0%\n\n---\n\n## Indice de Epicos\n\n| # | Epico | Stories | Status |\n|---|-------|---------|--------|\n| 1 | [Nome] | {N} | TODO |\n| 2 | [Nome] | {N} | TODO |\n| 3 | [Nome] | {N} | TODO |\n\n---\n\n## Epic 1: {Nome}\n\n> **Objetivo:** {Descricao}\n> **Requisitos:** RF01, RF02\n> **GAPs:** G-PRD-01, G-ARCH-01\n\n### Story 1.1: {Titulo}\n\n**Como** {persona}, **quero** {acao} **para** {beneficio}.\n\n**Criterios de Aceite:**\n- [ ] {Criterio 1}\n- [ ] {Criterio 2}\n\n**Subtarefas:**\n- [ ] **1.1.1:** {Subtarefa}\n- [ ] **1.1.2:** {Subtarefa}\n\n**Dependencias:** Nenhuma | Story X.Y\n**Estimativa:** P/M/G\n**GAPs resolvidos:** [IDs]\n\n---\n\n[Repetir para cada Story e Epic]\n\n---\n\n## Consolidated GAP Summary\n\n### Por Severidade\n| Severidade | Produto | UX | Arquitetura | Seguranca | Stack | Design | Total |\n|-----------|---------|-----|------------|-----------|-------|--------|-------|\n| Critical | [N] | [N] | [N] | [N] | [N] | [N] | [N] |\n| High | [N] | [N] | [N] | [N] | [N] | [N] | [N] |\n| Medium | [N] | [N] | [N] | [N] | [N] | [N] | [N] |\n| Low | [N] | [N] | [N] | [N] | [N] | [N] | [N] |\n\n### GAP-to-Task Mapping\n| GAP ID | Origem | Epic | Story | Prioridade | Status |\n|--------|--------|------|-------|------------|--------|\n| G-PRD-01 | PRD | Epic 1 | Story 1.1 | P0 | TODO |\n| G-UX-01 | UX Concept | Epic 2 | Story 2.2 | P1 | TODO |\n| G-ARCH-01 | Architecture | Epic 1 | Story 1.3 | P0 | TODO |\n| G-SEC-01 | Security | Epic 1 | Story 1.2 | P0 | TODO |\n| G-STACK-01 | Stack | Epic 3 | Story 3.1 | P1 | TODO |\n| G-DS-01 | Design System | Epic 2 | Story 2.4 | P2 | TODO |\n\n### Roadmap para Fechar GAPs\n| Fase | GAPs | Milestone | Dependencias |\n|------|------|-----------|-------------|\n| Foundation | G-PRD-01, G-ARCH-01, G-STACK-01 | Infra pronta | Nenhuma |\n| Core | G-UX-01, G-PRD-02 | Fluxos principais | Foundation |\n| Polish | G-DS-01, G-UX-03 | Consistencia | Core |\n\n---\n\n## Progresso\n\n| Epico | Total | Done | In Progress | TODO | % |\n|-------|-------|------|------------|------|---|\n| Epic 1 | {N} | 0 | 0 | {N} | 0% |\n| **TOTAL** | **{N}** | **0** | **0** | **{N}** | **0%** |\n\n```\n[                    ] 0% (0/{N} stories)\n```\n\n---\n\n## Dependencias\n\n```mermaid\nflowchart LR\n    S1.1[Story 1.1] --> S1.2[Story 1.2]\n    S1.1 --> S2.1[Story 2.1]\n```\n\n---\n\n## Ordem de Execucao\n\n1. **Foundation:** Story 1.1, 1.2\n2. **Core:** Story 2.1, 2.2, 2.3\n3. **Polish:** Story 3.1, 3.2\n4. **Launch:** Story 4.1\n\n---\n\n## Changelog\n| Data | Alteracao | Autor |\n|------|-----------|-------|\n| {YYYY-MM-DD} | Backlog criado | AI Product Owner |\n```\n\n---\n\n## Pos-Execucao\n\nApos criar todos os 8 documentos:\n\n### Geracao Automatica de HANDOFF.md\n\nQuando executado pelo Gemini CLI (Flow B), gerar automaticamente `docs/HANDOFF.md`:\n\n```markdown\n# HANDOFF — Gemini → Codex\n- Data: {YYYY-MM-DD}\n- Projeto: {nome}\n- Status: PRONTO PARA IMPLEMENTACAO\n\n## Documentos Prontos\n- [x] Brief: docs/01-Planejamento/01-product-brief.md\n- [x] PRD: docs/01-Planejamento/02-prd.md\n- [x] UX Concept: docs/01-Planejamento/03-ux-concept.md\n- [x] Visual Mockups: docs/01-Planejamento/03.5-visual-mockups.md (se HAS_UI)\n- [x] Architecture: docs/01-Planejamento/04-architecture.md\n- [x] Security: docs/01-Planejamento/05-security.md\n- [x] Stack: docs/01-Planejamento/06-stack.md\n- [x] Design System: docs/01-Planejamento/07-design-system.md\n- [x] Backlog: docs/BACKLOG.md\n\n## Prioridades de Implementacao\n1. {Epic 1} [P0]\n2. {Epic 2} [P0]\n3. ...\n\n## Decisoes Tecnicas Importantes\n- Stack: {extraido do 06-stack.md}\n- Auth: {extraido do 05-security.md}\n- ...\n\n## Notas para o Implementador\n- Ler este documento ANTES de comecar qualquer implementacao\n- Seguir a ordem de execucao definida no Backlog\n- Nao alterar documentos de planejamento\n```\n\n> **Regra:** O HANDOFF.md e gerado automaticamente. No Claude Code (Flow A), este passo e opcional pois o mesmo agente faz planning + implementacao.\n\n### Sharding Recomendado\n\nApos gerar o BACKLOG.md, sugerir ao usuario:\n\n```bash\npython3 .agents/scripts/shard_epic.py shard\n```\n\nIsso divide o backlog em arquivos individuais por story em `docs/stories/`, permitindo que as IAs trabalhem com contexto focado.\n\n### Resumo Final\n\n```markdown\n## Workflow /define Concluido!\n\n### Documentos Gerados:\n1. docs/01-Planejamento/01-product-brief.md — Visao e contexto\n2. docs/01-Planejamento/02-prd.md — Requisitos + GAP produto\n3. docs/01-Planejamento/03-ux-concept.md — UX + GAP experiencia\n3.5. docs/01-Planejamento/03.5-visual-mockups.md — Mockups visuais (se HAS_UI)\n4. docs/01-Planejamento/04-architecture.md — Arquitetura + DB + GAP infra\n5. docs/01-Planejamento/05-security.md — Seguranca + GAP security\n6. docs/01-Planejamento/06-stack.md — Stack + GAP tecnologia\n7. docs/01-Planejamento/07-design-system.md — Design + GAP design\n8. docs/BACKLOG.md — Backlog + GAPs consolidados\n9. docs/HANDOFF.md — Handoff para implementacao (se Flow B)\n\n### Proximo Passo: Revisao\nDocumentos devem ser revisados com skill `doc-review` por Claude Code ou Codex.\n\n### Apos Revisao:\n1. /track — Inicializar tracking\n2. `python3 .agents/scripts/shard_epic.py shard` — Fatiar backlog em story files\n3. implementar Story 1.1 — Comecar implementacao\n\nNAO inicio implementacao sem aprovacao explicita.\n```\n\n---\n\n## Regras de Qualidade\n\n### Documentacao Deve:\n1. **Ser Especifica** — Sem \"varios\", \"alguns\", \"etc\"\n2. **Ser Mensuravel** — Numeros, metricas, limites\n3. **Ser Acionavel** — Executavel ou verificavel\n4. **Ser Consistente** — Mesmos termos em todos os docs\n5. **Ser Rastreavel** — Requisitos -> Stories -> Tasks\n6. **Ter GAP Analysis** — Todos os docs exceto Brief\n\n### Anti-Padroes:\n- \"Sistema deve ser rapido\" -> \"API < 200ms (p95)\"\n- \"Usuarios fazem coisas\" -> \"Usuario cria ate 10 projetos\"\n- Omitir GAP -> Identificar gaps em TODAS as dimensoes (produto, UX, infra, seguranca, tech, design)\n\n---\n\n## Fluxo de Revisao\n\n| Gerador | Revisor | Skill |\n|---------|---------|-------|\n| Antigravity | Claude Code / Codex | `doc-review` |\n\n### Processo:\n1. Revisor le TODOS os documentos\n2. Aplica checklist `doc-review` (5 fases)\n3. Gera Review Report\n4. NEEDS REVISION -> lista issues\n5. APPROVED -> pronto para implementacao\n",
     "deploy": "---\ndescription: Deployment command for production releases. Pre-flight checks and deployment execution.\n---\n\n# /deploy - Production Deployment\n\n$ARGUMENTS\n\n---\n\n## Purpose\n\nThis command handles production deployment with pre-flight checks, deployment execution, and verification.\n\n---\n\n## Sub-commands\n\n```\n/deploy            - Interactive deployment wizard\n/deploy check      - Run pre-deployment checks only\n/deploy preview    - Deploy to preview/staging\n/deploy production - Deploy to production\n/deploy rollback   - Rollback to previous version\n```\n\n---\n\n## Regras Críticas\n\n1. **CHECKLIST OBRIGATÓRIO** — Nunca fazer deploy sem passar pelo pre-flight checklist completo.\n2. **ZERO ERROS** — TypeScript, ESLint e testes devem estar passando antes do deploy.\n3. **SEM SEGREDOS NO CÓDIGO** — Verificar que não há secrets hardcoded antes de publicar.\n4. **HEALTH CHECK PÓS-DEPLOY** — Sempre verificar saúde da aplicação após o deploy.\n5. **ROLLBACK DISPONÍVEL** — Manter versão anterior acessível para rollback imediato se necessário.\n\n## Fluxo de Execução\n\n### Pre-Deployment Checklist\n\nBefore any deployment:\n\n```markdown\n## 🚀 Pre-Deploy Checklist\n\n### Code Quality\n- [ ] No TypeScript errors (`npx tsc --noEmit`)\n- [ ] ESLint passing (`npx eslint .`)\n- [ ] All tests passing (`npm test`)\n\n### Security\n- [ ] No hardcoded secrets\n- [ ] Environment variables documented\n- [ ] Dependencies audited (`npm audit`)\n\n### Performance\n- [ ] Bundle size acceptable\n- [ ] No console.log statements\n- [ ] Images optimized\n\n### Documentation\n- [ ] README updated\n- [ ] CHANGELOG updated\n- [ ] API docs current\n\n### Ready to deploy? (y/n)\n```\n\n---\n\n## Deployment Flow\n\n```\n┌─────────────────┐\n│  /deploy        │\n└────────┬────────┘\n         │\n         ▼\n┌─────────────────┐\n│  Pre-flight     │\n│  checks         │\n└────────┬────────┘\n         │\n    Pass? ──No──► Fix issues\n         │\n        Yes\n         │\n         ▼\n┌─────────────────┐\n│  Build          │\n│  application    │\n└────────┬────────┘\n         │\n         ▼\n┌─────────────────┐\n│  Deploy to      │\n│  platform       │\n└────────┬────────┘\n         │\n         ▼\n┌─────────────────┐\n│  Health check   │\n│  & verify       │\n└────────┬────────┘\n         │\n         ▼\n┌─────────────────┐\n│  ✅ Complete    │\n└─────────────────┘\n```\n\n---\n\n## Output Format\n\n### Successful Deploy\n\n```markdown\n## 🚀 Deployment Complete\n\n### Summary\n- **Version:** v1.2.3\n- **Environment:** production\n- **Duration:** 47 seconds\n- **Platform:** Vercel\n\n### URLs\n- 🌐 Production: https://app.example.com\n- 📊 Dashboard: https://vercel.com/project\n\n### What Changed\n- Added user profile feature\n- Fixed login bug\n- Updated dependencies\n\n### Health Check\n✅ API responding (200 OK)\n✅ Database connected\n✅ All services healthy\n```\n\n### Failed Deploy\n\n```markdown\n## ❌ Deployment Failed\n\n### Error\nBuild failed at step: TypeScript compilation\n\n### Details\n```\nerror TS2345: Argument of type 'string' is not assignable...\n```\n\n### Resolution\n1. Fix TypeScript error in `src/services/user.ts:45`\n2. Run `npm run build` locally to verify\n3. Try `/deploy` again\n\n### Rollback Available\nPrevious version (v1.2.2) is still active.\nRun `/deploy rollback` if needed.\n```\n\n---\n\n## Platform Support\n\n| Platform | Command | Notes |\n|----------|---------|-------|\n| Vercel | `vercel --prod` | Auto-detected for Next.js |\n| Railway | `railway up` | Needs Railway CLI |\n| Fly.io | `fly deploy` | Needs flyctl |\n| Docker | `docker compose up -d` | For self-hosted |\n\n---\n\n## Examples\n\n```\n/deploy\n/deploy check\n/deploy preview\n/deploy production --skip-tests\n/deploy rollback\n```\n",
     "enhance": "---\ndescription: Add or update features in existing application. Used for iterative development.\n---\n\n# /enhance - Update Application\n\n$ARGUMENTS\n\n---\n\n## Regras Críticas\n\n1. **ESTADO ATUAL PRIMEIRO** — Sempre carregar e entender o estado atual do projeto antes de modificar.\n2. **APROVAÇÃO PARA MUDANÇAS GRANDES** — Apresentar plano ao usuário para alterações que afetam muitos arquivos.\n3. **CONFLITOS ALERTADOS** — Avisar quando o pedido conflita com tecnologias existentes no projeto.\n4. **COMMIT POR MUDANÇA** — Registrar cada alteração com git para rastreabilidade.\n5. **PREVIEW ATUALIZADO** — Garantir que o preview reflita as mudanças após aplicação.\n\n## Fluxo de Execução\n\nThis command adds features or makes updates to existing application.\n\n### Steps:\n\n1. **Understand Current State**\n   - Load project state with `python3 .agents/scripts/project_analyzer.py info`\n   - Understand existing features, tech stack\n\n2. **Plan Changes**\n   - Determine what will be added/changed\n   - Detect affected files\n   - Check dependencies\n\n3. **Present Plan to User** (for major changes)\n   ```\n   \"To add admin panel:\n   - I'll create 15 new files\n   - Update 8 files\n   - Takes ~10 minutes\n   \n   Should I start?\"\n   ```\n\n4. **Apply**\n   - Call relevant agents\n   - Make changes\n   - Test\n\n5. **Update Preview**\n   - Hot reload or restart\n\n---\n\n## Usage Examples\n\n```\n/enhance add dark mode\n/enhance build admin panel\n/enhance integrate payment system\n/enhance add search feature\n/enhance edit profile page\n/enhance make responsive\n```\n\n---\n\n## Caution\n\n- Get approval for major changes\n- Warn on conflicting requests (e.g., \"use Firebase\" when project uses PostgreSQL)\n- Commit each change with git\n",
     "finish": "---\ndescription: Marca uma tarefa do backlog como concluída. Uso: /finish {ID}\n---\n\n# Workflow: /finish\n\n> **Propósito:** Automatizar a baixa de tarefas no backlog. Usado por agentes ao finalizar suas tarefas ou pelo usuário manualmente.\n\n## Argumentos\n\n- `task_id`: O identificador da tarefa (ex: \"3.1\", \"Epic 2\").\n\n## Regras Críticas\n\n1. **ID OBRIGATÓRIO** — O `task_id` deve ser fornecido; não inferir automaticamente.\n2. **IDEMPOTENTE** — Marcar a mesma tarefa múltiplas vezes não causa erro.\n3. **PROGRESSO ATUALIZADO** — Sempre executar o progress_tracker após marcar a tarefa.\n\n## Fluxo de Execução\n\n// turbo\n1. Executar o script de atualização\n   Run: python3 .agents/scripts/finish_task.py \"{task_id}\"\n\n// turbo\n2. Atualizar a barra de progresso visual\n   Run: python3 .agents/scripts/progress_tracker.py\n\n// turbo\n3. Se `docs/stories/` existir, sincronizar status dos shards\n   Run: python3 .agents/scripts/shard_epic.py sync\n\n## Exemplos de Uso\n\n- **Manual:** `/finish 3.1`\n- **Agente:** `run_command: /finish \"Story 5.2\"`\n",
@@ -329,7 +329,7 @@ export const EMBEDDED_WORKFLOWS = {
     "orchestrate": "---\ndescription: Coordinate multiple agents for complex tasks. Use for multi-perspective analysis, comprehensive reviews, or tasks requiring different domain expertise.\n---\n\n# Multi-Agent Orchestration\n\nYou are now in **ORCHESTRATION MODE**. Your task: coordinate specialized agents to solve this complex problem.\n\n## Task to Orchestrate\n$ARGUMENTS\n\n---\n\n## Regras Críticas\n\n1. **MÍNIMO 3 AGENTES** — Orquestração exige no mínimo 3 agentes diferentes; menos que isso é delegação simples.\n2. **2 FASES OBRIGATÓRIAS** — Fase 1 (Planejamento) deve ser concluída e aprovada antes da Fase 2 (Implementação).\n3. **APROVAÇÃO DO USUÁRIO** — Nunca prosseguir para implementação sem aprovação explícita do plano.\n4. **CONTEXTO COMPLETO** — Ao invocar sub-agentes, passar contexto completo (pedido original, decisões, trabalho anterior).\n5. **VERIFICAÇÃO FINAL** — O último agente deve executar scripts de verificação (security_scan, lint_runner).\n\n## 🔴 CRITICAL: Minimum Agent Requirement\n\n> ⚠️ **ORCHESTRATION = MINIMUM 3 DIFFERENT AGENTS**\n> \n> If you use fewer than 3 agents, you are NOT orchestrating - you're just delegating.\n> \n> **Validation before completion:**\n> - Count invoked agents\n> - If `agent_count < 3` → STOP and invoke more agents\n> - Single agent = FAILURE of orchestration\n\n### Agent Selection Matrix\n\n| Task Type | REQUIRED Agents (minimum) |\n|-----------|---------------------------|\n| **Web App** | frontend-specialist, backend-specialist, test-engineer |\n| **API** | backend-specialist, security-auditor, test-engineer |\n| **UI/Design** | frontend-specialist, seo-specialist, performance-optimizer |\n| **Database** | database-architect, backend-specialist, security-auditor |\n| **Full Stack** | project-planner, frontend-specialist, backend-specialist, devops-engineer |\n| **Debug** | debugger, explorer-agent, test-engineer |\n| **Product/Planning** | product-manager, product-owner, project-planner |\n| **UX/Research** | ux-researcher, frontend-specialist, product-manager |\n| **QA/Automation** | qa-automation-engineer, test-engineer, devops-engineer |\n| **Legacy/Refactoring** | code-archaeologist, debugger, test-engineer |\n| **Security** | security-auditor, penetration-tester, devops-engineer |\n\n---\n\n## Pre-Flight: Mode Check\n\n| Current Mode | Task Type | Action |\n|--------------|-----------|--------|\n| **plan** | Any | ✅ Proceed with planning-first approach |\n| **edit** | Simple execution | ✅ Proceed directly |\n| **edit** | Complex/multi-file | ⚠️ Ask: \"This task requires planning. Switch to plan mode?\" |\n| **ask** | Any | ⚠️ Ask: \"Ready to orchestrate. Switch to edit or plan mode?\" |\n\n---\n\n## 🔴 STRICT 2-PHASE ORCHESTRATION\n\n### PHASE 1: PLANNING (Sequential - NO parallel agents)\n\n| Step | Agent | Action |\n|------|-------|--------|\n| 1 | `project-planner` | Create docs/PLAN.md |\n| 2 | (optional) `explorer-agent` | Codebase discovery if needed |\n\n> 🔴 **NO OTHER AGENTS during planning!** Only project-planner and explorer-agent.\n\n### ⏸️ CHECKPOINT: User Approval\n\n```\nAfter PLAN.md is complete, ASK:\n\n\"✅ Plan created: docs/PLAN.md\n\nDo you approve? (Y/N)\n- Y: Implementation starts\n- N: I'll revise the plan\"\n```\n\n> 🔴 **DO NOT proceed to Phase 2 without explicit user approval!**\n\n### PHASE 2: IMPLEMENTATION (Parallel agents after approval)\n\n| Parallel Group | Agents |\n|----------------|--------|\n| Foundation | `database-architect`, `security-auditor` |\n| Core | `backend-specialist`, `frontend-specialist` |\n| Polish | `test-engineer`, `devops-engineer` |\n\n> ✅ After user approval, invoke multiple agents in PARALLEL.\n\n## Available Agents (21 total)\n\n| Agent | Domain | Use When |\n|-------|--------|----------|\n| `project-planner` | Planning | Task breakdown, PLAN.md |\n| `explorer-agent` | Discovery | Codebase mapping |\n| `frontend-specialist` | UI/UX | React, Vue, CSS, HTML |\n| `backend-specialist` | Server | API, Node.js, Python |\n| `database-architect` | Data | SQL, NoSQL, Schema |\n| `security-auditor` | Security | Vulnerabilities, Auth |\n| `penetration-tester` | Security | Active testing |\n| `test-engineer` | Testing | Unit, E2E, Coverage |\n| `devops-engineer` | Ops | CI/CD, Docker, Deploy |\n| `mobile-developer` | Mobile | React Native, Flutter |\n| `performance-optimizer` | Speed | Lighthouse, Profiling |\n| `seo-specialist` | SEO | Meta, Schema, Rankings |\n| `documentation-writer` | Docs | README, API docs |\n| `debugger` | Debug | Error analysis |\n| `game-developer` | Games | Unity, Godot |\n| `product-manager` | Product | Requirements, user stories, acceptance criteria |\n| `product-owner` | Strategy | Strategic planning, PRD, roadmap, backlog prioritization |\n| `ux-researcher` | UX | UX research, user flows, wireframes, usability analysis |\n| `code-archaeologist` | Legacy | Legacy code analysis, refactoring, reverse engineering |\n| `qa-automation-engineer` | QA | E2E test automation, Playwright, CI pipelines |\n| `orchestrator` | Meta | Coordination |\n\n---\n\n## Fluxo de Execução\n\n### Orchestration Protocol\n\n### Step 1: Analyze Task Domains\nIdentify ALL domains this task touches:\n```\n□ Security     → security-auditor, penetration-tester\n□ Backend/API  → backend-specialist\n□ Frontend/UI  → frontend-specialist\n□ Database     → database-architect\n□ Testing      → test-engineer\n□ DevOps       → devops-engineer\n□ Mobile       → mobile-developer\n□ Performance  → performance-optimizer\n□ SEO          → seo-specialist\n□ Planning     → project-planner\n□ Product      → product-manager, product-owner\n□ UX Research  → ux-researcher\n□ Legacy       → code-archaeologist\n□ QA Automation → qa-automation-engineer\n```\n\n### Step 2: Phase Detection\n\n| If Plan Exists | Action |\n|----------------|--------|\n| NO `docs/PLAN.md` | → Go to PHASE 1 (planning only) |\n| YES `docs/PLAN.md` + user approved | → Go to PHASE 2 (implementation) |\n\n### Step 3: Execute Based on Phase\n\n**PHASE 1 (Planning):**\n```\nUse the project-planner agent to create PLAN.md\n→ STOP after plan is created\n→ ASK user for approval\n```\n\n**PHASE 2 (Implementation - after approval):**\n```\nInvoke agents in PARALLEL:\nUse the frontend-specialist agent to [task]\nUse the backend-specialist agent to [task]\nUse the test-engineer agent to [task]\n```\n\n**🔴 CRITICAL: Context Passing (MANDATORY)**\n\nWhen invoking ANY subagent, you MUST include:\n\n1. **Original User Request:** Full text of what user asked\n2. **Decisions Made:** All user answers to Socratic questions\n3. **Previous Agent Work:** Summary of what previous agents did\n4. **Current Plan State:** If plan files exist in workspace, include them\n\n**Example with FULL context:**\n```\nUse the project-planner agent to create PLAN.md:\n\n**CONTEXT:**\n- User Request: \"Öğrenciler için sosyal platform, mock data ile\"\n- Decisions: Tech=Vue 3, Layout=Grid Widget, Auth=Mock, Design=Genç Dinamik\n- Previous Work: Orchestrator asked 6 questions, user chose all options\n- Current Plan: playful-roaming-dream.md exists in workspace with initial structure\n\n**TASK:** Create detailed PLAN.md based on ABOVE decisions. Do NOT infer from folder name.\n```\n\n> ⚠️ **VIOLATION:** Invoking subagent without full context = subagent will make wrong assumptions!\n\n\n### Step 4: Verification (MANDATORY)\nThe LAST agent must run appropriate verification scripts:\n```bash\npython .agents/skills/vulnerability-scanner/scripts/security_scan.py .\npython .agents/skills/lint-and-validate/scripts/lint_runner.py .\n```\n\n### Step 5: Synthesize Results\nCombine all agent outputs into unified report.\n\n---\n\n## Output Format\n\n```markdown\n## 🎼 Orchestration Report\n\n### Task\n[Original task summary]\n\n### Mode\n[Current Antigravity Agent mode: plan/edit/ask]\n\n### Agents Invoked (MINIMUM 3)\n| # | Agent | Focus Area | Status |\n|---|-------|------------|--------|\n| 1 | project-planner | Task breakdown | ✅ |\n| 2 | frontend-specialist | UI implementation | ✅ |\n| 3 | test-engineer | Verification scripts | ✅ |\n\n### Verification Scripts Executed\n- [x] security_scan.py → Pass/Fail\n- [x] lint_runner.py → Pass/Fail\n\n### Key Findings\n1. **[Agent 1]**: Finding\n2. **[Agent 2]**: Finding\n3. **[Agent 3]**: Finding\n\n### Deliverables\n- [ ] PLAN.md created\n- [ ] Code implemented\n- [ ] Tests passing\n- [ ] Scripts verified\n\n### Summary\n[One paragraph synthesis of all agent work]\n```\n\n---\n\n## 🔴 EXIT GATE\n\nBefore completing orchestration, verify:\n\n1. ✅ **Agent Count:** `invoked_agents >= 3`\n2. ✅ **Scripts Executed:** At least `security_scan.py` ran\n3. ✅ **Report Generated:** Orchestration Report with all agents listed\n\n> **If any check fails → DO NOT mark orchestration complete. Invoke more agents or run scripts.**\n\n---\n\n**Begin orchestration now. Select 3+ agents, execute sequentially, run verification scripts, synthesize results.**\n",
     "plan": "---\ndescription: Create project plan using project-planner agent. No code writing - only plan file generation.\n---\n\n# /plan - Project Planning Mode\n\n$ARGUMENTS\n\n---\n\n## 🔴 CRITICAL RULES\n\n1. **NO CODE WRITING** - This command creates plan file only\n2. **Use project-planner agent** - NOT Antigravity Agent's native Plan mode\n3. **Socratic Gate** - Ask clarifying questions before planning\n4. **Dynamic Naming** - Plan file named based on task\n\n---\n\n## Task\n\nUse the `project-planner` agent with this context:\n\n```\nCONTEXT:\n- User Request: $ARGUMENTS\n- Mode: PLANNING ONLY (no code)\n- Output: docs/PLAN-{task-slug}.md (dynamic naming)\n\nNAMING RULES:\n1. Extract 2-3 key words from request\n2. Lowercase, hyphen-separated\n3. Max 30 characters\n4. Example: \"e-commerce cart\" → PLAN-ecommerce-cart.md\n\nRULES:\n1. Follow project-planner.md Phase -1 (Context Check)\n2. Follow project-planner.md Phase 0 (Socratic Gate)\n3. Create PLAN-{slug}.md with task breakdown\n4. DO NOT write any code files\n5. REPORT the exact file name created\n```\n\n---\n\n## Fluxo de Execução\n\n1. **Receber pedido** — Capturar o `$ARGUMENTS` do usuário.\n2. **Socratic Gate** — Fazer perguntas de clarificação (Phase 0 do project-planner).\n3. **Gerar slug** — Extrair 2-3 palavras-chave para nomear o arquivo do plano.\n4. **Criar PLAN.md** — Usar o agente `project-planner` para gerar o plano completo.\n5. **Reportar** — Informar ao usuário o arquivo criado e os próximos passos.\n\n---\n\n## Expected Output\n\n| Deliverable | Location |\n|-------------|----------|\n| Project Plan | `docs/PLAN-{task-slug}.md` |\n| Task Breakdown | Inside plan file |\n| Agent Assignments | Inside plan file |\n| Verification Checklist | Phase X in plan file |\n\n---\n\n## After Planning\n\nTell user:\n```\n[OK] Plan created: docs/PLAN-{slug}.md\n\nNext steps:\n- Review the plan\n- Run `/create` to start implementation\n- Or modify plan manually\n```\n\n---\n\n## Naming Examples\n\n| Request | Plan File |\n|---------|-----------|\n| `/plan e-commerce site with cart` | `docs/PLAN-ecommerce-cart.md` |\n| `/plan mobile app for fitness` | `docs/PLAN-fitness-app.md` |\n| `/plan add dark mode feature` | `docs/PLAN-dark-mode.md` |\n| `/plan fix authentication bug` | `docs/PLAN-auth-fix.md` |\n| `/plan SaaS dashboard` | `docs/PLAN-saas-dashboard.md` |\n\n---\n\n## Usage\n\n```\n/plan e-commerce site with cart\n/plan mobile app for fitness tracking\n/plan SaaS dashboard with analytics\n```\n",
     "preview": "---\ndescription: Preview server start, stop, and status check. Local development server management.\n---\n\n# /preview - Preview Management\n\n$ARGUMENTS\n\n---\n\n## Regras Críticas\n\n1. **PORTA VERIFICADA** — Sempre verificar se a porta está livre antes de iniciar o servidor.\n2. **HEALTH CHECK** — Confirmar que o servidor está respondendo antes de informar sucesso.\n3. **CONFLITO TRATADO** — Se a porta estiver em uso, oferecer alternativas ao usuário.\n4. **SCRIPT OFICIAL** — Usar `auto_preview.py` para gerenciar o servidor de preview.\n\n## Fluxo de Execução\n\nManage preview server: start, stop, status check.\n\n### Commands\n\n```\n/preview           - Show current status\n/preview start     - Start server\n/preview stop      - Stop server\n/preview restart   - Restart\n/preview check     - Health check\n```\n\n---\n\n## Usage Examples\n\n### Start Server\n```\n/preview start\n\nResponse:\n🚀 Starting preview...\n   Port: 3000\n   Type: Next.js\n\n✅ Preview ready!\n   URL: http://localhost:3000\n```\n\n### Status Check\n```\n/preview\n\nResponse:\n=== Preview Status ===\n\n🌐 URL: http://localhost:3000\n📁 Project: C:/projects/my-app\n🏷️ Type: nextjs\n💚 Health: OK\n```\n\n### Port Conflict\n```\n/preview start\n\nResponse:\n⚠️ Port 3000 is in use.\n\nOptions:\n1. Start on port 3001\n2. Close app on 3000\n3. Specify different port\n\nWhich one? (default: 1)\n```\n\n---\n\n## Technical\n\nAuto preview uses `auto_preview.py` script:\n\n```bash\npython3 .agents/scripts/auto_preview.py start [port]\npython3 .agents/scripts/auto_preview.py stop\npython3 .agents/scripts/auto_preview.py status\n```\n\n",
-    "readiness": "---\ndescription: Valida se toda a documentação está completa e alinhada antes de iniciar implementação. Gera relatório de prontidão.\n---\n\n# Workflow: /readiness\n\n> **Propósito:** Verificar que TODA a documentação necessária existe, está completa e alinhada antes de escrever qualquer código.\n\n## Quando Usar\n\nExecute `/readiness` APÓS completar o `/define` e ANTES de começar a implementação.\n\n## Regras Críticas\n\n1. **NÃO APROVE** se houver gaps críticos\n2. **DOCUMENTE** todas as inconsistências encontradas\n3. **SUGIRA CORREÇÕES** para cada problema\n4. **GERE RELATÓRIO** estruturado ao final\n\n---\n\n## Fluxo de Execução\n\n### Fase 1: Inventário de Documentos\n\nVerifique a existência de todos os documentos obrigatórios:\n\n> **Resolução de caminhos:** Procurar primeiro em `docs/01-Planejamento/`. Se não existir, procurar em `docs/planning/` (alias aceito). Em scripts Python, usar `resolve_doc_file(\"planejamento\", \"<ficheiro>\")` de `platform_compat.py`.\n\n```markdown\n## 📋 Inventário de Documentos\n\n### Documentos Core (Obrigatórios)\n| Documento | Path (oficial / alias) | Status |\n|-----------|------|--------|\n| Product Brief | `docs/01-Planejamento/01-product-brief.md` | ✅ Encontrado / ❌ Faltando |\n| PRD | `docs/01-Planejamento/02-prd.md` | ✅ / ❌ |\n| UX Concept | `docs/01-Planejamento/03-ux-concept.md` | ✅ / ❌ |\n| Architecture | `docs/01-Planejamento/04-architecture.md` | ✅ / ❌ |\n| Security | `docs/01-Planejamento/05-security.md` | ✅ / ❌ |\n| Stack | `docs/01-Planejamento/06-stack.md` | ✅ / ❌ |\n| Design System | `docs/01-Planejamento/07-design-system.md` | ✅ / ❌ |\n| Backlog | `docs/BACKLOG.md` | ✅ / ❌ |\n\n### Documentos Condicionais\n| Documento | Path (oficial / alias) | Obrigatorio | Status |\n|-----------|------|-------------|--------|\n| Visual Mockups | `docs/01-Planejamento/03.5-visual-mockups.md` | Se HAS_UI | ✅ / ❌ |\n\n> **Regra:** Se o projeto tem interface visual (HAS_UI=true) e o ficheiro de mockups nao existe, o status e **NAO PRONTO**. Resolver antes de avancar.\n\n### Documentos Complementares (Recomendados)\n| Documento | Path (oficial / alias) | Status |\n|-----------|------|--------|\n| User Journeys | `docs/01-Planejamento/user-journeys.md` | ✅ / ❌ / ⚠️ Não criado |\n| Project Context | `docs/PROJECT-CONTEXT.md` | ✅ / ❌ / ⚠️ Não criado |\n| Readiness | `docs/01-Planejamento/IMPLEMENTATION-READINESS.md` | ✅ / ❌ / ⚠️ Não criado |\n\n### Resultado do Inventário\n- **Documentos obrigatórios:** X/8 ✅\n- **Documentos complementares:** Y/3 ✅\n- **Status:** ✅ Completo / ⚠️ Parcial / ❌ Incompleto\n```\n\n---\n\n### Fase 2: Validação de Cobertura (Rastreabilidade)\n\nVerifique se TODOS os requisitos funcionais têm cobertura no backlog:\n\n```markdown\n## 🔗 Validação de Rastreabilidade\n\n### Matriz FR → Epic → Story\n\n| Requisito | Descrição | Epic | Story | Status |\n|-----------|-----------|------|-------|--------|\n| RF01 | [Descrição curta] | Epic 1 | Story 1.1 | ✅ Coberto |\n| RF02 | [Descrição curta] | Epic 1 | Story 1.2 | ✅ Coberto |\n| RF03 | [Descrição curta] | - | - | ❌ SEM COBERTURA |\n| RF04 | [Descrição curta] | Epic 2 | Story 2.1, 2.2 | ✅ Coberto |\n| ... | ... | ... | ... | ... |\n\n### Estatísticas\n- **Total de FRs:** {N}\n- **FRs cobertos:** {X}\n- **FRs sem cobertura:** {Y}\n- **Cobertura:** {X/N * 100}%\n\n### FRs Sem Cobertura (Ação Necessária)\n1. **RF03:** [Descrição]\n   - **Sugestão:** Criar Story no Epic X para cobrir este requisito\n\n### Stories Órfãs (Sem FR correspondente)\n| Story | Descrição | Ação Sugerida |\n|-------|-----------|---------------|\n| Story 3.5 | [Desc] | Vincular a RF existente ou remover |\n```\n\n---\n\n### Fase 3: Validação de Qualidade\n\nVerifique se cada documento atende aos padrões de qualidade:\n\n```markdown\n## 📊 Validação de Qualidade\n\n### 3.1 Product Brief\n| Critério | Status | Observação |\n|----------|--------|------------|\n| Visão do produto clara | ✅ / ❌ | |\n| Problema específico (não genérico) | ✅ / ❌ | |\n| Personas com detalhes concretos | ✅ / ❌ | |\n| Métricas de sucesso quantificadas | ✅ / ❌ | Ex: \"< 3 dias\" não apenas \"rápido\" |\n| Anti-persona definida | ✅ / ❌ / ⚠️ | |\n| Riscos identificados | ✅ / ❌ | |\n\n### 3.2 PRD\n| Critério | Status | Observação |\n|----------|--------|------------|\n| Todos FRs têm ID único | ✅ / ❌ | RF01, RF02, ... |\n| Todos FRs têm prioridade (P0/P1/P2) | ✅ / ❌ | |\n| Acceptance Criteria em formato BDD | ✅ / ❌ | Given/When/Then |\n| Casos de borda documentados | ✅ / ❌ | |\n| Requisitos não-funcionais presentes | ✅ / ❌ | Performance, Segurança, etc. |\n| Fluxos de usuário com diagramas | ✅ / ❌ | Mermaid ou descrição |\n| Integrações especificadas | ✅ / ❌ / N/A | |\n\n### 3.3 Design System\n| Critério | Status | Observação |\n|----------|--------|------------|\n| Paleta de cores com Hex | ✅ / ❌ | |\n| Escala tipográfica completa | ✅ / ❌ | |\n| Espaçamento definido | ✅ / ❌ | |\n| Componentes base documentados | ✅ / ❌ | Buttons, Inputs, Cards, Modal |\n| Estados de componentes | ✅ / ❌ | Hover, Focus, Disabled, Loading |\n| Breakpoints responsivos | ✅ / ❌ | |\n| Acessibilidade considerada | ✅ / ❌ | Contraste, ARIA |\n\n### 3.4 Database Design\n| Critério | Status | Observação |\n|----------|--------|------------|\n| Diagrama ER presente | ✅ / ❌ | Mermaid ou similar |\n| Todas entidades com campos tipados | ✅ / ❌ | |\n| Constraints documentadas | ✅ / ❌ | NOT NULL, UNIQUE, etc. |\n| Índices planejados | ✅ / ❌ | |\n| Relacionamentos claros | ✅ / ❌ | 1:N, N:N com FKs |\n| Security Rules/RLS definidas | ✅ / ❌ | |\n| Migrations planejadas | ✅ / ❌ | |\n\n### 3.5 Backlog\n| Critério | Status | Observação |\n|----------|--------|------------|\n| Épicos com objetivo claro | ✅ / ❌ | |\n| Stories no formato \"Como...quero...para\" | ✅ / ❌ | |\n| Todas stories têm Acceptance Criteria | ✅ / ❌ | |\n| Subtarefas técnicas definidas | ✅ / ❌ | |\n| Dependências entre stories mapeadas | ✅ / ❌ | |\n| Ordem de execução sugerida | ✅ / ❌ | |\n```\n\n---\n\n### Fase 4: Validação de Alinhamento\n\nVerifique consistência entre documentos:\n\n```markdown\n## 🔄 Validação de Alinhamento\n\n### PRD ↔ Product Brief\n| Aspecto | Brief | PRD | Alinhado? |\n|---------|-------|-----|-----------|\n| Público-alvo | [Persona X] | [Mesma persona em FRs] | ✅ / ❌ |\n| Funcionalidades core | [Lista] | [FRs correspondentes] | ✅ / ❌ |\n| Métricas de sucesso | [KPIs] | [RNFs correspondentes] | ✅ / ❌ |\n\n### PRD ↔ Database\n| Aspecto | PRD | Database | Alinhado? |\n|---------|-----|----------|-----------|\n| RF01: [Cadastro de X] | Descreve campos A, B, C | Tabela X tem A, B, C | ✅ / ❌ |\n| RF05: [Relatório de Y] | Precisa de dados Z | Índice em Z existe | ✅ / ❌ |\n\n### PRD ↔ Design System\n| Aspecto | PRD | Design | Alinhado? |\n|---------|-----|--------|-----------|\n| RF03: Modal de confirmação | Menciona modal | Modal spec existe | ✅ / ❌ |\n| RF07: Tabela paginada | Menciona tabela | Table + Pagination specs | ✅ / ❌ |\n\n### Design ↔ Backlog\n| Componente | Design System | Story Correspondente | Alinhado? |\n|------------|---------------|---------------------|-----------|\n| Button Primary | Documentado | Story X.Y menciona | ✅ / ❌ |\n| StatsCard | Documentado | Story X.Y menciona | ✅ / ❌ |\n\n### Inconsistências Encontradas\n| # | Tipo | Documento A | Documento B | Problema | Sugestão |\n|---|------|-------------|-------------|----------|----------|\n| 1 | Desalinhamento | PRD RF06 | Backlog | RF06 marcado P1 no PRD, adiado no Backlog | Atualizar prioridade no PRD |\n| 2 | Campo faltando | PRD RF09 | Database | RF09 menciona LTV, Database não tem campo | Adicionar campo calculado |\n```\n\n---\n\n### Fase 5: Validação de Completude de Stories\n\nVerifique se cada story está pronta para implementação:\n\n```markdown\n## ✅ Validação de Stories (Dev-Ready)\n\n### Checklist por Story\n\n#### Story 1.1: [Título]\n| Critério | Status |\n|----------|--------|\n| Descrição clara (Como/Quero/Para) | ✅ / ❌ |\n| Acceptance Criteria em BDD | ✅ / ❌ |\n| Subtarefas técnicas definidas | ✅ / ❌ |\n| Dependências identificadas | ✅ / ❌ |\n| Componentes UI mapeados no Design System | ✅ / ❌ |\n| Entidades de dados mapeadas no Database | ✅ / ❌ |\n| **Status:** | ✅ Dev-Ready / ⚠️ Precisa Ajustes |\n\n#### Story 1.2: [Título]\n[Mesmo formato]\n\n### Resumo de Stories\n| Status | Quantidade | Percentual |\n|--------|------------|------------|\n| ✅ Dev-Ready | X | Y% |\n| ⚠️ Precisa Ajustes | Z | W% |\n| ❌ Não Pronta | N | M% |\n```\n\n---\n\n### Fase 6: Relatório Final\n\nGere o relatório consolidado:\n\n```markdown\n# 📋 Implementation Readiness Report\n\n**Projeto:** {Nome do Projeto}\n**Data:** {YYYY-MM-DD}\n**Gerado por:** AI Project Validator\n\n---\n\n## Executive Summary\n\n| Categoria | Score | Status |\n|-----------|-------|--------|\n| Inventário de Docs | X/5 | ✅ / ⚠️ / ❌ |\n| Cobertura de FRs | Y% | ✅ / ⚠️ / ❌ |\n| Qualidade dos Docs | Z/20 critérios | ✅ / ⚠️ / ❌ |\n| Alinhamento | W inconsistências | ✅ / ⚠️ / ❌ |\n| Stories Dev-Ready | N% | ✅ / ⚠️ / ❌ |\n\n---\n\n## Status Geral\n\n### ✅ PRONTO PARA IMPLEMENTAÇÃO\n*Todos os critérios foram atendidos. O projeto pode iniciar a fase de desenvolvimento.*\n\n### ⚠️ PRONTO COM RESSALVAS\n*O projeto pode iniciar, mas os seguintes pontos devem ser resolvidos durante o desenvolvimento:*\n1. [Issue menor 1]\n2. [Issue menor 2]\n\n### ❌ NÃO PRONTO - BLOQUEADORES\n*Os seguintes problemas DEVEM ser resolvidos antes de iniciar:*\n1. **[Bloqueador 1]:** [Descrição + Ação necessária]\n2. **[Bloqueador 2]:** [Descrição + Ação necessária]\n\n---\n\n## Issues Detalhados\n\n### Críticos (Bloqueadores) 🔴\n| # | Problema | Impacto | Ação Necessária |\n|---|----------|---------|-----------------|\n| 1 | [Descrição] | [Alto/Médio] | [O que fazer] |\n\n### Importantes (Devem ser resolvidos) 🟡\n| # | Problema | Impacto | Ação Necessária |\n|---|----------|---------|-----------------|\n| 1 | [Descrição] | [Médio] | [O que fazer] |\n\n### Menores (Nice to fix) 🟢\n| # | Problema | Impacto | Ação Sugerida |\n|---|----------|---------|---------------|\n| 1 | [Descrição] | [Baixo] | [Sugestão] |\n\n---\n\n## Próximos Passos\n\n### Se PRONTO:\n1. Rodar `/track` para inicializar tracking\n2. Começar com `implementar Story 1.1`\n3. Seguir ordem de execução sugerida no Backlog\n\n### Se NÃO PRONTO:\n1. Resolver bloqueadores listados acima\n2. Atualizar documentação correspondente\n3. Rodar `/readiness` novamente\n\n---\n\n## Changelog do Relatório\n\n| Data | Versão | Mudanças |\n|------|--------|----------|\n| {YYYY-MM-DD} | 1.0 | Relatório inicial |\n```\n\n**Output:** Salvar em `docs/01-Planejamento/IMPLEMENTATION-READINESS.md` (ou `docs/planning/` se alias ativo)\n\n---\n\n## Pós-Execução\n\n```markdown\n## Relatório de Prontidão Gerado!\n\n📄 Arquivo: `docs/01-Planejamento/IMPLEMENTATION-READINESS.md` (ou `docs/planning/`)\n\n### Resultado: [STATUS]\n\n[Se PRONTO]\n✅ Documentação completa e alinhada!\n🚀 Você pode iniciar a implementação com `implementar Story 1.1`\n\n[Se NÃO PRONTO]\n❌ Foram encontrados {N} bloqueadores que precisam ser resolvidos.\n📝 Revise o relatório e corrija os issues listados.\n🔄 Após correções, rode `/readiness` novamente.\n```\n\n---\n\n## Geracao Automatica de HANDOFF.md\n\nQuando a validacao resultar em **PRONTO** (Flow B — Gemini → Codex):\n\n1. Gerar automaticamente `docs/HANDOFF.md` com:\n   - Lista de todos os documentos prontos (com paths)\n   - Prioridades de implementacao (extraidas do Backlog)\n   - Decisoes tecnicas importantes (extraidas de Architecture + Stack + Security)\n   - Notas para o implementador\n2. Informar ao usuario que o HANDOFF esta pronto para o Codex\n\n> **Regra:** O HANDOFF.md so e gerado quando o status e PRONTO ou PRONTO COM RESSALVAS.\n> No Claude Code (Flow A), este passo e opcional.\n",
+    "readiness": "---\ndescription: Valida se toda a documentação está completa e alinhada antes de iniciar implementação. Gera relatório de prontidão.\n---\n\n# Workflow: /readiness\n\n> **Propósito:** Verificar que TODA a documentação necessária existe, está completa e alinhada antes de escrever qualquer código.\n\n## Quando Usar\n\nExecute `/readiness` APÓS completar o `/define` e ANTES de começar a implementação.\n\n## Regras Críticas\n\n1. **NÃO APROVE** se houver gaps críticos\n2. **DOCUMENTE** todas as inconsistências encontradas\n3. **SUGIRA CORREÇÕES** para cada problema\n4. **GERE RELATÓRIO** estruturado ao final\n\n---\n\n## Fluxo de Execução\n\n### Fase 1: Inventário de Documentos\n\nVerifique a existência de todos os documentos obrigatórios:\n\n> **Resolução de caminhos:** Procurar primeiro em `docs/01-Planejamento/`. Se não existir, procurar em `docs/planning/` (alias aceito). Em scripts Python, usar `resolve_doc_file(\"planejamento\", \"<ficheiro>\")` de `platform_compat.py`.\n\n```markdown\n## 📋 Inventário de Documentos\n\n### Documentos Core (Obrigatórios)\n| Documento | Path (oficial / alias) | Status |\n|-----------|------|--------|\n| Product Brief | `docs/01-Planejamento/01-product-brief.md` | ✅ Encontrado / ❌ Faltando |\n| PRD | `docs/01-Planejamento/02-prd.md` | ✅ / ❌ |\n| UX Concept | `docs/01-Planejamento/03-ux-concept.md` | ✅ / ❌ |\n| Architecture | `docs/01-Planejamento/04-architecture.md` | ✅ / ❌ |\n| Security | `docs/01-Planejamento/05-security.md` | ✅ / ❌ |\n| Stack | `docs/01-Planejamento/06-stack.md` | ✅ / ❌ |\n| Design System | `docs/01-Planejamento/07-design-system.md` | ✅ / ❌ |\n| Backlog | `docs/BACKLOG.md` | ✅ / ❌ |\n\n### Documentos Condicionais\n| Documento | Path (oficial / alias) | Obrigatorio | Status |\n|-----------|------|-------------|--------|\n| Visual Mockups | `docs/01-Planejamento/03.5-visual-mockups.md` | Se HAS_UI | ✅ / ❌ |\n\n> **Regra:** Se o projeto tem interface visual (HAS_UI=true) e o ficheiro de mockups nao existe, o status e **NAO PRONTO**. Resolver antes de avancar.\n\n### Documentos Complementares (Recomendados)\n| Documento | Path (oficial / alias) | Status |\n|-----------|------|--------|\n| User Journeys | `docs/01-Planejamento/user-journeys.md` | ✅ / ❌ / ⚠️ Não criado |\n| Project Context | `docs/PROJECT-CONTEXT.md` | ✅ / ❌ / ⚠️ Não criado |\n| Readiness | `docs/01-Planejamento/IMPLEMENTATION-READINESS.md` | ✅ / ❌ / ⚠️ Não criado |\n\n### Resultado do Inventário\n- **Documentos obrigatórios:** X/8 ✅\n- **Documentos complementares:** Y/3 ✅\n- **Status:** ✅ Completo / ⚠️ Parcial / ❌ Incompleto\n```\n\n---\n\n### Fase 2: Validação de Cobertura (Rastreabilidade)\n\nVerifique se TODOS os requisitos funcionais têm cobertura no backlog:\n\n```markdown\n## 🔗 Validação de Rastreabilidade\n\n### Matriz FR → Epic → Story\n\n| Requisito | Descrição | Epic | Story | Status |\n|-----------|-----------|------|-------|--------|\n| RF01 | [Descrição curta] | Epic 1 | Story 1.1 | ✅ Coberto |\n| RF02 | [Descrição curta] | Epic 1 | Story 1.2 | ✅ Coberto |\n| RF03 | [Descrição curta] | - | - | ❌ SEM COBERTURA |\n| RF04 | [Descrição curta] | Epic 2 | Story 2.1, 2.2 | ✅ Coberto |\n| ... | ... | ... | ... | ... |\n\n### Estatísticas\n- **Total de FRs:** {N}\n- **FRs cobertos:** {X}\n- **FRs sem cobertura:** {Y}\n- **Cobertura:** {X/N * 100}%\n\n### FRs Sem Cobertura (Ação Necessária)\n1. **RF03:** [Descrição]\n   - **Sugestão:** Criar Story no Epic X para cobrir este requisito\n\n### Stories Órfãs (Sem FR correspondente)\n| Story | Descrição | Ação Sugerida |\n|-------|-----------|---------------|\n| Story 3.5 | [Desc] | Vincular a RF existente ou remover |\n```\n\n---\n\n### Fase 3: Validação de Qualidade\n\nVerifique se cada documento atende aos padrões de qualidade:\n\n```markdown\n## 📊 Validação de Qualidade\n\n### 3.1 Product Brief\n| Critério | Status | Observação |\n|----------|--------|------------|\n| Visão do produto clara | ✅ / ❌ | |\n| Problema específico (não genérico) | ✅ / ❌ | |\n| Personas com detalhes concretos | ✅ / ❌ | |\n| Métricas de sucesso quantificadas | ✅ / ❌ | Ex: \"< 3 dias\" não apenas \"rápido\" |\n| Anti-persona definida | ✅ / ❌ / ⚠️ | |\n| Riscos identificados | ✅ / ❌ | |\n\n### 3.2 PRD\n| Critério | Status | Observação |\n|----------|--------|------------|\n| Todos FRs têm ID único | ✅ / ❌ | RF01, RF02, ... |\n| Todos FRs têm prioridade (P0/P1/P2) | ✅ / ❌ | |\n| Acceptance Criteria em formato BDD | ✅ / ❌ | Given/When/Then |\n| Casos de borda documentados | ✅ / ❌ | |\n| Requisitos não-funcionais presentes | ✅ / ❌ | Performance, Segurança, etc. |\n| Fluxos de usuário com diagramas | ✅ / ❌ | Mermaid ou descrição |\n| Integrações especificadas | ✅ / ❌ / N/A | |\n\n### 3.3 Design System\n| Critério | Status | Observação |\n|----------|--------|------------|\n| Paleta de cores com Hex | ✅ / ❌ | |\n| Escala tipográfica completa | ✅ / ❌ | |\n| Espaçamento definido | ✅ / ❌ | |\n| Componentes base documentados | ✅ / ❌ | Buttons, Inputs, Cards, Modal |\n| Estados de componentes | ✅ / ❌ | Hover, Focus, Disabled, Loading |\n| Breakpoints responsivos | ✅ / ❌ | |\n| Acessibilidade considerada | ✅ / ❌ | Contraste, ARIA |\n\n### 3.4 Database Design\n| Critério | Status | Observação |\n|----------|--------|------------|\n| Diagrama ER presente | ✅ / ❌ | Mermaid ou similar |\n| Todas entidades com campos tipados | ✅ / ❌ | |\n| Constraints documentadas | ✅ / ❌ | NOT NULL, UNIQUE, etc. |\n| Índices planejados | ✅ / ❌ | |\n| Relacionamentos claros | ✅ / ❌ | 1:N, N:N com FKs |\n| Security Rules/RLS definidas | ✅ / ❌ | |\n| Migrations planejadas | ✅ / ❌ | |\n\n### 3.5 Backlog\n| Critério | Status | Observação |\n|----------|--------|------------|\n| Épicos com objetivo claro | ✅ / ❌ | |\n| Stories no formato \"Como...quero...para\" | ✅ / ❌ | |\n| Todas stories têm Acceptance Criteria | ✅ / ❌ | |\n| Subtarefas técnicas definidas | ✅ / ❌ | |\n| Dependências entre stories mapeadas | ✅ / ❌ | |\n| Ordem de execução sugerida | ✅ / ❌ | |\n```\n\n---\n\n### Fase 4: Validação de Alinhamento\n\nVerifique consistência entre documentos:\n\n```markdown\n## 🔄 Validação de Alinhamento\n\n### PRD ↔ Product Brief\n| Aspecto | Brief | PRD | Alinhado? |\n|---------|-------|-----|-----------|\n| Público-alvo | [Persona X] | [Mesma persona em FRs] | ✅ / ❌ |\n| Funcionalidades core | [Lista] | [FRs correspondentes] | ✅ / ❌ |\n| Métricas de sucesso | [KPIs] | [RNFs correspondentes] | ✅ / ❌ |\n\n### PRD ↔ Database\n| Aspecto | PRD | Database | Alinhado? |\n|---------|-----|----------|-----------|\n| RF01: [Cadastro de X] | Descreve campos A, B, C | Tabela X tem A, B, C | ✅ / ❌ |\n| RF05: [Relatório de Y] | Precisa de dados Z | Índice em Z existe | ✅ / ❌ |\n\n### PRD ↔ Design System\n| Aspecto | PRD | Design | Alinhado? |\n|---------|-----|--------|-----------|\n| RF03: Modal de confirmação | Menciona modal | Modal spec existe | ✅ / ❌ |\n| RF07: Tabela paginada | Menciona tabela | Table + Pagination specs | ✅ / ❌ |\n\n### Design ↔ Backlog\n| Componente | Design System | Story Correspondente | Alinhado? |\n|------------|---------------|---------------------|-----------|\n| Button Primary | Documentado | Story X.Y menciona | ✅ / ❌ |\n| StatsCard | Documentado | Story X.Y menciona | ✅ / ❌ |\n\n### Inconsistências Encontradas\n| # | Tipo | Documento A | Documento B | Problema | Sugestão |\n|---|------|-------------|-------------|----------|----------|\n| 1 | Desalinhamento | PRD RF06 | Backlog | RF06 marcado P1 no PRD, adiado no Backlog | Atualizar prioridade no PRD |\n| 2 | Campo faltando | PRD RF09 | Database | RF09 menciona LTV, Database não tem campo | Adicionar campo calculado |\n```\n\n---\n\n### Fase 5: Validação de Completude de Stories\n\nVerifique se cada story está pronta para implementação:\n\n```markdown\n## ✅ Validação de Stories (Dev-Ready)\n\n### Checklist por Story\n\n#### Story 1.1: [Título]\n| Critério | Status |\n|----------|--------|\n| Descrição clara (Como/Quero/Para) | ✅ / ❌ |\n| Acceptance Criteria em BDD | ✅ / ❌ |\n| Subtarefas técnicas definidas | ✅ / ❌ |\n| Dependências identificadas | ✅ / ❌ |\n| Componentes UI mapeados no Design System | ✅ / ❌ |\n| Entidades de dados mapeadas no Database | ✅ / ❌ |\n| **Status:** | ✅ Dev-Ready / ⚠️ Precisa Ajustes |\n\n#### Story 1.2: [Título]\n[Mesmo formato]\n\n### Resumo de Stories\n| Status | Quantidade | Percentual |\n|--------|------------|------------|\n| ✅ Dev-Ready | X | Y% |\n| ⚠️ Precisa Ajustes | Z | W% |\n| ❌ Não Pronta | N | M% |\n```\n\n---\n\n### Fase 6: Relatório Final\n\nGere o relatório consolidado:\n\n```markdown\n# 📋 Implementation Readiness Report\n\n**Projeto:** {Nome do Projeto}\n**Data:** {YYYY-MM-DD}\n**Gerado por:** AI Project Validator\n\n---\n\n## Executive Summary\n\n| Categoria | Score | Status |\n|-----------|-------|--------|\n| Inventário de Docs | X/5 | ✅ / ⚠️ / ❌ |\n| Cobertura de FRs | Y% | ✅ / ⚠️ / ❌ |\n| Qualidade dos Docs | Z/20 critérios | ✅ / ⚠️ / ❌ |\n| Alinhamento | W inconsistências | ✅ / ⚠️ / ❌ |\n| Stories Dev-Ready | N% | ✅ / ⚠️ / ❌ |\n\n---\n\n## Status Geral\n\n### ✅ PRONTO PARA IMPLEMENTAÇÃO\n*Todos os critérios foram atendidos. O projeto pode iniciar a fase de desenvolvimento.*\n\n### ⚠️ PRONTO COM RESSALVAS\n*O projeto pode iniciar, mas os seguintes pontos devem ser resolvidos durante o desenvolvimento:*\n1. [Issue menor 1]\n2. [Issue menor 2]\n\n### ❌ NÃO PRONTO - BLOQUEADORES\n*Os seguintes problemas DEVEM ser resolvidos antes de iniciar:*\n1. **[Bloqueador 1]:** [Descrição + Ação necessária]\n2. **[Bloqueador 2]:** [Descrição + Ação necessária]\n\n---\n\n## Issues Detalhados\n\n### Críticos (Bloqueadores) 🔴\n| # | Problema | Impacto | Ação Necessária |\n|---|----------|---------|-----------------|\n| 1 | [Descrição] | [Alto/Médio] | [O que fazer] |\n\n### Importantes (Devem ser resolvidos) 🟡\n| # | Problema | Impacto | Ação Necessária |\n|---|----------|---------|-----------------|\n| 1 | [Descrição] | [Médio] | [O que fazer] |\n\n### Menores (Nice to fix) 🟢\n| # | Problema | Impacto | Ação Sugerida |\n|---|----------|---------|---------------|\n| 1 | [Descrição] | [Baixo] | [Sugestão] |\n\n---\n\n## Próximos Passos\n\n### Se PRONTO:\n1. Rodar `/track` para inicializar tracking\n2. Rodar `python3 .agents/scripts/shard_epic.py shard` para fatiar backlog em stories\n3. Começar com `implementar Story 1.1`\n4. Seguir ordem de execução sugerida no Backlog\n\n### Se NÃO PRONTO:\n1. Resolver bloqueadores listados acima\n2. Atualizar documentação correspondente\n3. Rodar `/readiness` novamente\n\n---\n\n## Changelog do Relatório\n\n| Data | Versão | Mudanças |\n|------|--------|----------|\n| {YYYY-MM-DD} | 1.0 | Relatório inicial |\n```\n\n**Output:** Salvar em `docs/01-Planejamento/IMPLEMENTATION-READINESS.md` (ou `docs/planning/` se alias ativo)\n\n---\n\n## Pós-Execução\n\n```markdown\n## Relatório de Prontidão Gerado!\n\n📄 Arquivo: `docs/01-Planejamento/IMPLEMENTATION-READINESS.md` (ou `docs/planning/`)\n\n### Resultado: [STATUS]\n\n[Se PRONTO]\n✅ Documentação completa e alinhada!\n🚀 Você pode iniciar a implementação com `implementar Story 1.1`\n\n[Se NÃO PRONTO]\n❌ Foram encontrados {N} bloqueadores que precisam ser resolvidos.\n📝 Revise o relatório e corrija os issues listados.\n🔄 Após correções, rode `/readiness` novamente.\n```\n\n---\n\n## Geracao Automatica de HANDOFF.md\n\nQuando a validacao resultar em **PRONTO** (Flow B — Gemini → Codex):\n\n1. Gerar automaticamente `docs/HANDOFF.md` com:\n   - Lista de todos os documentos prontos (com paths)\n   - Prioridades de implementacao (extraidas do Backlog)\n   - Decisoes tecnicas importantes (extraidas de Architecture + Stack + Security)\n   - Notas para o implementador\n2. Informar ao usuario que o HANDOFF esta pronto para o Codex\n\n> **Regra:** O HANDOFF.md so e gerado quando o status e PRONTO ou PRONTO COM RESSALVAS.\n> No Claude Code (Flow A), este passo e opcional.\n",
     "release": "---\ndescription: Finaliza projeto e gera release. Valida conclusao, gera changelog e prepara artefatos de lancamento.\n---\n\n# Workflow: /release\n\n> **Proposito:** Finalizar formalmente um projeto (MVP ou Producao) apos conclusao de todas as tarefas do backlog. Valida criterios de conclusao, gera artefatos de release e documenta o lancamento.\n\n## Argumentos\n\n```\n/release                   - Release padrao (verifica backlog 100%)\n/release mvp               - Release MVP (permite backlog parcial com P0 completos)\n/release --version X.Y.Z   - Especifica versao manualmente\n/release --dry-run         - Simula release sem criar artefatos\n```\n\n---\n\n## Regras Criticas\n\n1. **BACKLOG VERIFICADO** — Nao liberar sem verificar status do backlog.\n2. **TESTES OBRIGATORIOS** — Deve haver execucao de `/test-book --validate` aprovada.\n3. **REVIEW APROVADO** — Ultima revisao de codigo deve estar APPROVED.\n4. **CHANGELOG GERADO** — Todo release deve ter changelog documentado.\n5. **TAG CRIADA** — Versao deve ser taggeada no git.\n\n---\n\n## Checklist de Conclusao\n\n### Para MVP\n\n| # | Criterio | Obrigatorio | Verificacao |\n|---|----------|-------------|-------------|\n| 1 | Todos os Epics P0 concluidos | Sim | `docs/BACKLOG.md` sem `[ ]` em P0 |\n| 2 | Testes P0 passando | Sim | `/test-book --validate` |\n| 3 | Sem issues BLOCKING no review | Sim | `docs/reviews/` ultimo relatorio |\n| 4 | Documentacao basica presente | Sim | README.md atualizado |\n| 5 | Variaveis de ambiente documentadas | Sim | .env.example presente |\n\n### Para Producao\n\n| # | Criterio | Obrigatorio | Verificacao |\n|---|----------|-------------|-------------|\n| 1 | 100% do backlog concluido | Sim | `docs/BACKLOG.md` |\n| 2 | Todos os testes passando | Sim | `/test-book --validate` |\n| 3 | Review APPROVED | Sim | `docs/reviews/` |\n| 4 | Documentacao completa | Sim | README, API docs, guias |\n| 5 | Seguranca auditada | Sim | Scan de vulnerabilidades |\n| 6 | Performance validada | Recomendado | Metricas de carga |\n| 7 | Rollback testado | Recomendado | Procedimento documentado |\n\n---\n\n## Fluxo de Execucao\n\n### Fase 1: Verificar Backlog\n\n```bash\n# Verificar progresso\npython3 .agents/scripts/progress_tracker.py\n\n# Para MVP: verificar apenas P0\n# Para Producao: verificar 100%\n```\n\n**Criterio de Parada:**\n- MVP: Se algum Epic P0 incompleto → ERRO\n- Producao: Se qualquer tarefa incompleta → ERRO\n\n---\n\n### Fase 2: Validar Testes\n\n```bash\n# Executar caderno de testes\n/test-book --validate\n```\n\n**Criterio de Parada:**\n- Se houver testes BLOCKING falhando → ERRO\n- Se taxa de aprovacao < 95% → WARNING (perguntar se continua)\n\n---\n\n### Fase 3: Verificar Review\n\n```bash\n# Verificar ultimo review\nls -la docs/reviews/ | tail -1\n```\n\n**Criterio de Parada:**\n- Se ultimo review for NEEDS FIXES ou BLOCKED → ERRO\n- Se nenhum review existir → WARNING (recomendar executar `/review`)\n\n---\n\n### Fase 4: Determinar Versao\n\nSe `--version` nao foi especificado:\n\n1. Ler versao atual de `package.json`\n2. Sugerir bump baseado no tipo de mudancas:\n   - Major (X.0.0): Breaking changes\n   - Minor (0.X.0): Novas features\n   - Patch (0.0.X): Bug fixes\n\n```bash\n# Ler versao atual\ncat package.json | grep '\"version\"'\n```\n\n---\n\n### Fase 5: Gerar Changelog\n\nCriar `CHANGELOG.md` ou atualizar existente:\n\n```markdown\n# Changelog\n\n## [X.Y.Z] - YYYY-MM-DD\n\n### Added\n- [Lista de features do backlog marcadas como novas]\n\n### Changed\n- [Lista de melhorias/refatoracoes]\n\n### Fixed\n- [Lista de bugs corrigidos]\n\n### Security\n- [Lista de correcoes de seguranca]\n\n### Breaking Changes\n- [Lista de mudancas que quebram compatibilidade]\n```\n\n**Fonte de dados:**\n- `docs/BACKLOG.md` (features)\n- `git log --oneline` (commits desde ultima tag)\n- `docs/reviews/` (issues corrigidos)\n\n---\n\n### Fase 6: Atualizar Versao\n\n```bash\n# Atualizar package.json\nnpm version X.Y.Z --no-git-tag-version\n\n# Ou manualmente editar package.json\n```\n\n---\n\n### Fase 7: Criar Tag e Commit\n\n```bash\n# Commit de release\ngit add .\ngit commit -m \"chore: release vX.Y.Z\"\n\n# Criar tag\ngit tag -a vX.Y.Z -m \"Release vX.Y.Z\"\n```\n\n---\n\n### Fase 8: Gerar Release Notes\n\nCriar arquivo `docs/releases/vX.Y.Z.md`:\n\n```markdown\n# Release Notes - vX.Y.Z\n\n**Data:** YYYY-MM-DD\n**Tipo:** MVP / Production\n**Autor:** [Agente que executou]\n\n---\n\n## Resumo\n\n[Descricao breve do que esta release inclui]\n\n---\n\n## Epics Incluidos\n\n| Epic | Descricao | Stories |\n|------|-----------|---------|\n| 1 | [Nome] | [N] concluidas |\n\n---\n\n## Metricas\n\n- **Total de Stories:** [N]\n- **Testes Executados:** [N]\n- **Taxa de Aprovacao:** [%]\n- **Issues Resolvidos:** [N]\n\n---\n\n## Proximos Passos\n\n- [Lista de melhorias futuras ou Epics P1/P2 pendentes]\n\n---\n\n## Verificacao\n\n- [x] Backlog verificado\n- [x] Testes validados\n- [x] Review aprovado\n- [x] Changelog gerado\n- [x] Tag criada\n```\n\n---\n\n### Fase 9: Notificar Conclusao\n\nExibir resumo final:\n\n```\n========================================\n         RELEASE CONCLUIDO\n========================================\n\nProjeto: [Nome]\nVersao: vX.Y.Z\nTipo: MVP / Production\nData: YYYY-MM-DD\n\nArtefatos Gerados:\n  - CHANGELOG.md (atualizado)\n  - docs/releases/vX.Y.Z.md\n  - Git tag: vX.Y.Z\n\nProximos passos:\n  - git push origin main --tags\n  - Publicar release notes\n  - Notificar stakeholders\n\n========================================\n```\n\n---\n\n## Modo --dry-run\n\nQuando executado com `--dry-run`:\n\n1. Executar todas as verificacoes\n2. Mostrar o que SERIA feito\n3. NAO criar commits, tags ou arquivos\n4. Util para validar antes de release real\n\n---\n\n## Integracao com Fluxo\n\n```\nBacklog 100% (ou P0 para MVP)\n        |\n        v\n  /test-book --validate\n        |\n   PASS?---> /review\n        |        |\n       NO      APPROVED?\n        |        |\n    Fix Tests   YES\n        |        |\n        +--------+\n                 |\n                 v\n            /release\n                 |\n                 v\n        Artefatos Gerados\n                 |\n                 v\n           git push --tags\n                 |\n                 v\n         Projeto Concluido\n```\n\n---\n\n## Exemplos de Uso\n\n```bash\n# Release padrao de producao\n/release\n\n# Release MVP (apenas P0)\n/release mvp\n\n# Release com versao especifica\n/release --version 2.0.0\n\n# Simular release\n/release --dry-run\n\n# Release MVP com versao\n/release mvp --version 1.0.0-mvp\n```\n\n---\n\n## Erros Comuns\n\n| Erro | Causa | Solucao |\n|------|-------|---------|\n| \"Backlog incompleto\" | Tarefas pendentes | Completar ou usar `mvp` |\n| \"Testes falhando\" | Caderno com falhas | Corrigir e re-executar |\n| \"Nenhum review encontrado\" | Pasta reviews vazia | Executar `/review` |\n| \"Versao ja existe\" | Tag duplicada | Usar versao diferente |\n\n---\n\n## Arquivos Gerados\n\n| Arquivo | Descricao |\n|---------|-----------|\n| `CHANGELOG.md` | Historico de mudancas |\n| `docs/releases/vX.Y.Z.md` | Release notes detalhado |\n| `package.json` | Versao atualizada |\n| Git tag `vX.Y.Z` | Marcador de versao |\n\n---\n\n*Skills relacionadas: `.agents/skills/deployment-procedures/SKILL.md`*\n",
     "review": "---\ndescription: Revisao de codigo pos-sprint. Aplica checklist de qualidade, seguranca e boas praticas ao codigo implementado.\n---\n\n# Workflow: /review\n\n> **Proposito:** Realizar revisao de codigo apos cada sprint ou sessao de implementacao, garantindo qualidade antes de seguir para proxima etapa.\n\n## Argumentos\n\n```\n/review                    - Revisar todos os arquivos modificados na sessao\n/review [file/folder]      - Revisar arquivo ou pasta especifica\n/review --last-commit      - Revisar apenas ultimo commit\n/review --sprint           - Revisar todos os commits da sprint atual\n```\n\n---\n\n## Regras Criticas\n\n1. **NUNCA PULAR REVISAO** — Toda sprint deve terminar com revisao antes de `/finish`.\n2. **BLOQUEADORES PRIMEIRO** — Issues marcadas como BLOCKING devem ser resolvidas antes de prosseguir.\n3. **DOCUMENTAR DECISOES** — Justificar quando um \"problema\" e aceito intencionalmente.\n4. **USAR SKILL** — Sempre carregar `.agents/skills/code-review-checklist/SKILL.md`.\n\n---\n\n## Fluxo de Execucao\n\n### Fase 1: Identificar Escopo\n\n```bash\n# Listar arquivos modificados\ngit diff --name-only HEAD~5\n\n# Ou para commits da sprint (desde ultimo merge/tag)\ngit log --oneline --since=\"1 week ago\" --name-only\n```\n\n**Output esperado:** Lista de arquivos para revisar.\n\n---\n\n### Fase 2: Carregar Checklist\n\nLer e aplicar: `.agents/skills/code-review-checklist/SKILL.md`\n\n**Categorias de Revisao:**\n1. Correctness (bugs, edge cases)\n2. Security (injection, XSS, secrets)\n3. Performance (N+1, loops, cache)\n4. Code Quality (naming, DRY, SOLID)\n5. Testing (cobertura, edge cases)\n\n---\n\n### Fase 3: Revisar Cada Arquivo\n\nPara cada arquivo modificado:\n\n1. **Ler o arquivo** com contexto de mudancas\n2. **Aplicar checklist** item por item\n3. **Registrar issues** com severidade\n\n**Formato de Issues:**\n\n```markdown\n### [filename.ts]\n\n| # | Severidade | Linha | Issue | Sugestao |\n|---|-----------|-------|-------|----------|\n| 1 | 🔴 BLOCKING | 45 | SQL injection em query | Usar prepared statements |\n| 2 | 🟡 MAJOR | 78 | Funcao com 150 linhas | Dividir em funcoes menores |\n| 3 | 🟢 MINOR | 12 | Variavel `data` pouco descritiva | Renomear para `userData` |\n```\n\n---\n\n### Fase 4: Gerar Relatorio\n\nCriar relatorio em `docs/reviews/YYYY-MM-DD-review.md`:\n\n```markdown\n# Code Review Report\n\n**Data:** {YYYY-MM-DD}\n**Revisor:** {Claude Code / Codex / Antigravity}\n**Escopo:** {Descricao do que foi revisado}\n\n---\n\n## Resumo\n\n| Severidade | Quantidade | Resolvidos |\n|------------|-----------|------------|\n| 🔴 BLOCKING | [N] | [N] |\n| 🟡 MAJOR | [N] | [N] |\n| 🟢 MINOR | [N] | [N] |\n\n**Veredicto:** APPROVED / NEEDS FIXES / BLOCKED\n\n---\n\n## Issues por Arquivo\n\n[Lista de issues conforme Fase 3]\n\n---\n\n## Acoes Requeridas\n\n1. [ ] [Issue BLOCKING 1 - descricao]\n2. [ ] [Issue BLOCKING 2 - descricao]\n\n---\n\n## Notas do Revisor\n\n[Observacoes gerais, padroes bons encontrados, sugestoes de melhoria]\n```\n\n---\n\n### Fase 5: Resolver e Fechar\n\n1. **Se APPROVED:** Prosseguir para `/finish`\n2. **Se NEEDS FIXES:**\n   - Corrigir issues MAJOR e BLOCKING\n   - Re-executar `/review` nos arquivos corrigidos\n3. **Se BLOCKED:**\n   - NAO prosseguir ate resolver todos os BLOCKING\n   - Notificar usuario sobre problemas criticos\n\n---\n\n## Integracao com Fluxo\n\n```\nSprint Implementation\n        |\n        v\n    /review\n        |\n   +----+----+\n   |         |\nAPPROVED  NEEDS FIXES\n   |         |\n   v         v\n/finish   Fix Issues\n   |         |\n   v         +---> /review (loop)\nNext Sprint\n```\n\n---\n\n## Exemplos de Uso\n\n```bash\n# Revisao padrao apos implementacao\n/review\n\n# Revisar apenas o servico de auth\n/review src/services/auth/\n\n# Revisar ultimo commit antes de push\n/review --last-commit\n\n# Revisao completa da sprint\n/review --sprint\n```\n\n---\n\n## Checklist Rapido (Memoria)\n\n### Security\n- [ ] Input validado/sanitizado\n- [ ] Sem SQL/NoSQL injection\n- [ ] Sem XSS ou CSRF\n- [ ] Sem secrets hardcoded\n- [ ] Outputs sanitizados\n\n### Performance\n- [ ] Sem N+1 queries\n- [ ] Loops otimizados\n- [ ] Cache apropriado\n- [ ] Bundle size considerado\n\n### Quality\n- [ ] Nomes claros e descritivos\n- [ ] DRY - sem duplicacao\n- [ ] Funcoes pequenas e focadas\n- [ ] Tipos corretos (sem `any`)\n\n### Testing\n- [ ] Testes para codigo novo\n- [ ] Edge cases cobertos\n- [ ] Mocks para dependencias externas\n\n---\n\n## Metricas de Qualidade\n\n| Metrica | Alvo | Como Medir |\n|---------|------|------------|\n| Issues BLOCKING | 0 | Contagem no relatorio |\n| Issues MAJOR | < 3 por arquivo | Contagem no relatorio |\n| Cobertura de testes | > 80% | Coverage tool |\n| Funcoes > 50 linhas | 0 | Linter/analise |\n| `any` types | 0 | TypeScript strict |\n\n---\n\n## Automacao Sugerida\n\n```bash\n# Pre-commit hook (opcional)\n# .git/hooks/pre-commit\n\n#!/bin/bash\necho \"Running quick review checks...\"\nnpm run lint\nnpm run type-check\nnpm run test -- --coverage --passWithNoTests\n```\n\n---\n\n*Skill relacionada: `.agents/skills/code-review-checklist/SKILL.md`*\n",
     "squad": "---\ndescription: Manage squads - reusable packages of agents, skills, and workflows for specific domains.\n---\n\n# Workflow: /squad\n\n> **Purpose:** Create, manage, and activate squads - reusable packages of agents + skills + workflows for specific domains.\n\n## Commands\n\n```\n/squad create <name>                    # Interactive creation with Socratic Gate\n/squad create <name> --from-docs <path> # Auto-generate from PRD/Brief\n/squad list                             # List all squads\n/squad activate <name>                  # Activate in framework\n/squad deactivate <name>                # Deactivate\n/squad validate <name>                  # Validate integrity\n```\n\n---\n\n## Flow: /squad create\n\n### Step 1: Socratic Discovery\n\nBefore creating a squad, ask:\n\n1. **What domain does this squad cover?** (e.g., social media, e-commerce, analytics)\n2. **What agents are needed?** (lead agent + specialists)\n3. **What domain knowledge (skills) should be included?**\n4. **Are there workflows specific to this domain?**\n5. **Which platforms should support this squad?** (Claude Code, Gemini, Codex)\n\n### Step 2: Create Structure\n\n```bash\npython3 .agents/scripts/squad_manager.py create <name> --template specialist\n```\n\n### Step 3: Generate Components\n\nBased on discovery answers:\n1. Create agent files in `squads/<name>/agents/`\n2. Create skill SKILL.md files in `squads/<name>/skills/`\n3. Create workflow files in `squads/<name>/workflows/`\n4. Update `squad.yaml` with all component references\n\n### Step 4: Validate\n\n```bash\npython3 .agents/scripts/squad_manager.py validate <name>\n```\n\n### Step 5: Activate (Optional)\n\n```bash\npython3 .agents/scripts/squad_manager.py activate <name>\n```\n\n---\n\n## Flow: /squad create --from-docs\n\nWhen a PRD or Brief exists, auto-extract:\n1. **Agents** from identified domains in the PRD\n2. **Skills** from technical requirements\n3. **Workflows** from process requirements\n\n---\n\n## Flow: /squad list\n\n```bash\npython3 .agents/scripts/squad_manager.py list\n```\n\nShows: name, version, components count, active/inactive status.\n\n---\n\n## Flow: /squad activate\n\n```bash\npython3 .agents/scripts/squad_manager.py activate <name>\n```\n\nCreates symlinks from `.agents/` to squad components. Activated squads are treated as native framework components.\n\n---\n\n## Flow: /squad deactivate\n\n```bash\npython3 .agents/scripts/squad_manager.py deactivate <name>\n```\n\nRemoves symlinks. Squad files remain in `squads/<name>/`.\n\n---\n\n## Flow: /squad validate\n\n```bash\npython3 .agents/scripts/squad_manager.py validate <name>\n```\n\nChecks:\n- squad.yaml has required fields\n- All declared agents have files with frontmatter\n- All declared skills have SKILL.md\n- All declared workflows have files\n- Core skill dependencies exist in framework\n",
@@ -340,5 +340,5 @@ export const EMBEDDED_WORKFLOWS = {
     "ui-ux-pro-max": "---\ndescription: AI-powered design intelligence with 50+ styles, 95+ color palettes, and automated design system generation\n---\n\n# ui-ux-pro-max\n\nComprehensive design guide for web and mobile applications. Contains 50+ styles, 97 color palettes, 57 font pairings, 99 UX guidelines, and 25 chart types across 9 technology stacks. Searchable database with priority-based recommendations.\n\n## Prerequisites\n\nCheck if Python is installed:\n\n```bash\npython3 --version || python --version\n```\n\nIf Python is not installed, install it based on user's OS:\n\n**macOS:**\n```bash\nbrew install python3\n```\n\n**Ubuntu/Debian:**\n```bash\nsudo apt update && sudo apt install python3\n```\n\n**Windows:**\n```powershell\nwinget install Python.Python.3.12\n```\n\n---\n\n## Regras Críticas\n\n1. **SEM EMOJIS COMO ÍCONES** — Usar SVG icons (Heroicons, Lucide, Simple Icons), nunca emojis na UI.\n2. **DESIGN SYSTEM OBRIGATÓRIO** — Sempre gerar design system com `--design-system` antes de implementar.\n3. **CONTRASTE VERIFICADO** — Texto deve ter contraste mínimo de 4.5:1 em ambos os modos (light/dark).\n4. **CURSOR POINTER** — Todos os elementos clicáveis devem ter `cursor-pointer`.\n5. **RESPONSIVO TESTADO** — Verificar em 375px, 768px, 1024px e 1440px antes de entregar.\n\n## Fluxo de Execução\n\nWhen user requests UI/UX work (design, build, create, implement, review, fix, improve), follow this workflow:\n\n### Step 1: Analyze User Requirements\n\nExtract key information from user request:\n- **Product type**: SaaS, e-commerce, portfolio, dashboard, landing page, etc.\n- **Style keywords**: minimal, playful, professional, elegant, dark mode, etc.\n- **Industry**: healthcare, fintech, gaming, education, etc.\n- **Stack**: React, Vue, Next.js, or default to `html-tailwind`\n\n### Step 2: Generate Design System (REQUIRED)\n\n**Always start with `--design-system`** to get comprehensive recommendations with reasoning:\n\n```bash\npython3 .agents/.shared/ui-ux-pro-max/scripts/search.py \"<product_type> <industry> <keywords>\" --design-system [-p \"Project Name\"]\n```\n\nThis command:\n1. Searches 5 domains in parallel (product, style, color, landing, typography)\n2. Applies reasoning rules from `ui-reasoning.csv` to select best matches\n3. Returns complete design system: pattern, style, colors, typography, effects\n4. Includes anti-patterns to avoid\n\n**Example:**\n```bash\npython3 .agents/.shared/ui-ux-pro-max/scripts/search.py \"beauty spa wellness service\" --design-system -p \"Serenity Spa\"\n```\n\n### Step 2b: Persist Design System (Master + Overrides Pattern)\n\nTo save the design system for hierarchical retrieval across sessions, add `--persist`:\n\n```bash\npython3 .agents/.shared/ui-ux-pro-max/scripts/search.py \"<query>\" --design-system --persist -p \"Project Name\"\n```\n\nThis creates:\n- `design-system/MASTER.md` — Global Source of Truth with all design rules\n- `design-system/pages/` — Folder for page-specific overrides\n\n**With page-specific override:**\n```bash\npython3 .agents/.shared/ui-ux-pro-max/scripts/search.py \"<query>\" --design-system --persist -p \"Project Name\" --page \"dashboard\"\n```\n\nThis also creates:\n- `design-system/pages/dashboard.md` — Page-specific deviations from Master\n\n**How hierarchical retrieval works:**\n1. When building a specific page (e.g., \"Checkout\"), first check `design-system/pages/checkout.md`\n2. If the page file exists, its rules **override** the Master file\n3. If not, use `design-system/MASTER.md` exclusively\n\n### Step 2c: Visual Preview with Stitch [REQUIRED]\n\nAfter generating the design system, create visual mockups to validate design tokens:\n\n1. **Check Stitch MCP availability:** Call `mcp__stitch__list_projects` to confirm connectivity. If Stitch is not available, **STOP** and inform the user to configure Stitch MCP before continuing.\n2. **Create or find project:** Use `mcp__stitch__create_project` with the project name\n3. **Generate key screens:** Use design system tokens (colors, typography, geometry) in the Stitch prompt\n   - Embed actual token values: `\"primary color #e8590c, heading font DM Sans, 2px border radius\"`\n   - Generate 1-2 representative screens (e.g., main dashboard + landing hero)\n   - Use `GEMINI_3_PRO` for best quality\n4. **Validate visual coherence:**\n   - Do the generated screens look cohesive with the design tokens?\n   - Does the color palette work in a real UI context?\n   - Is the typography hierarchy visible?\n5. **Iterate if needed:**\n   - If mockups reveal token issues, adjust the design system and regenerate\n   - Load `stitch-ui-design` skill for detailed prompt engineering guidance\n\n> **Skill:** Load `stitch-ui-design` for prompt templates and anti-cliche rules.\n> **Note:** This step validates the design system visually and is REQUIRED for all UI projects.\n\n### Step 3: Supplement with Detailed Searches (as needed)\n\nAfter getting the design system, use domain searches to get additional details:\n\n```bash\npython3 .agents/.shared/ui-ux-pro-max/scripts/search.py \"<keyword>\" --domain <domain> [-n <max_results>]\n```\n\n**When to use detailed searches:**\n\n| Need | Domain | Example |\n|------|--------|---------|\n| More style options | `style` | `--domain style \"glassmorphism dark\"` |\n| Chart recommendations | `chart` | `--domain chart \"real-time dashboard\"` |\n| UX best practices | `ux` | `--domain ux \"animation accessibility\"` |\n| Alternative fonts | `typography` | `--domain typography \"elegant luxury\"` |\n| Landing structure | `landing` | `--domain landing \"hero social-proof\"` |\n\n### Step 4: Stack Guidelines (Default: html-tailwind)\n\nGet implementation-specific best practices. If user doesn't specify a stack, **default to `html-tailwind`**.\n\n```bash\npython3 .agents/.shared/ui-ux-pro-max/scripts/search.py \"<keyword>\" --stack html-tailwind\n```\n\nAvailable stacks: `html-tailwind`, `react`, `nextjs`, `vue`, `svelte`, `swiftui`, `react-native`, `flutter`, `shadcn`, `jetpack-compose`\n---\n\n## Search Reference\n\n### Available Domains\n\n| Domain | Use For | Example Keywords |\n|--------|---------|------------------|\n| `product` | Product type recommendations | SaaS, e-commerce, portfolio, healthcare, beauty, service |\n| `style` | UI styles, colors, effects | glassmorphism, minimalism, dark mode, brutalism |\n| `typography` | Font pairings, Google Fonts | elegant, playful, professional, modern |\n| `color` | Color palettes by product type | saas, ecommerce, healthcare, beauty, fintech, service |\n| `landing` | Page structure, CTA strategies | hero, hero-centric, testimonial, pricing, social-proof |\n| `chart` | Chart types, library recommendations | trend, comparison, timeline, funnel, pie |\n| `ux` | Best practices, anti-patterns | animation, accessibility, z-index, loading |\n| `react` | React/Next.js performance | waterfall, bundle, suspense, memo, rerender, cache |\n| `web` | Web interface guidelines | aria, focus, keyboard, semantic, virtualize |\n| `prompt` | AI prompts, CSS keywords | (style name) |\n\n### Available Stacks\n\n| Stack | Focus |\n|-------|-------|\n| `html-tailwind` | Tailwind utilities, responsive, a11y (DEFAULT) |\n| `react` | State, hooks, performance, patterns |\n| `nextjs` | SSR, routing, images, API routes |\n| `vue` | Composition API, Pinia, Vue Router |\n| `svelte` | Runes, stores, SvelteKit |\n| `swiftui` | Views, State, Navigation, Animation |\n| `react-native` | Components, Navigation, Lists |\n| `flutter` | Widgets, State, Layout, Theming |\n| `shadcn` | shadcn/ui components, theming, forms, patterns |\n| `jetpack-compose` | Composables, Modifiers, State Hoisting, Recomposition |\n\n---\n\n## Example Workflow\n\n**User request:** \"Làm landing page cho dịch vụ chăm sóc da chuyên nghiệp\"\n\n### Step 1: Analyze Requirements\n- Product type: Beauty/Spa service\n- Style keywords: elegant, professional, soft\n- Industry: Beauty/Wellness\n- Stack: html-tailwind (default)\n\n### Step 2: Generate Design System (REQUIRED)\n\n```bash\npython3 .agents/.shared/ui-ux-pro-max/scripts/search.py \"beauty spa wellness service elegant\" --design-system -p \"Serenity Spa\"\n```\n\n**Output:** Complete design system with pattern, style, colors, typography, effects, and anti-patterns.\n\n### Step 3: Supplement with Detailed Searches (as needed)\n\n```bash\n# Get UX guidelines for animation and accessibility\npython3 .agents/.shared/ui-ux-pro-max/scripts/search.py \"animation accessibility\" --domain ux\n\n# Get alternative typography options if needed\npython3 .agents/.shared/ui-ux-pro-max/scripts/search.py \"elegant luxury serif\" --domain typography\n```\n\n### Step 4: Stack Guidelines\n\n```bash\npython3 .agents/.shared/ui-ux-pro-max/scripts/search.py \"layout responsive form\" --stack html-tailwind\n```\n\n**Then:** Synthesize design system + detailed searches and implement the design.\n\n---\n\n## Output Formats\n\nThe `--design-system` flag supports two output formats:\n\n```bash\n# ASCII box (default) - best for terminal display\npython3 .agents/.shared/ui-ux-pro-max/scripts/search.py \"fintech crypto\" --design-system\n\n# Markdown - best for documentation\npython3 .agents/.shared/ui-ux-pro-max/scripts/search.py \"fintech crypto\" --design-system -f markdown\n```\n\n---\n\n## Tips for Better Results\n\n1. **Be specific with keywords** - \"healthcare SaaS dashboard\" > \"app\"\n2. **Search multiple times** - Different keywords reveal different insights\n3. **Combine domains** - Style + Typography + Color = Complete design system\n4. **Always check UX** - Search \"animation\", \"z-index\", \"accessibility\" for common issues\n5. **Use stack flag** - Get implementation-specific best practices\n6. **Iterate** - If first search doesn't match, try different keywords\n\n---\n\n## Common Rules for Professional UI\n\nThese are frequently overlooked issues that make UI look unprofessional:\n\n### Icons & Visual Elements\n\n| Rule | Do | Don't |\n|------|----|----- |\n| **No emoji icons** | Use SVG icons (Heroicons, Lucide, Simple Icons) | Use emojis like 🎨 🚀 ⚙️ as UI icons |\n| **Stable hover states** | Use color/opacity transitions on hover | Use scale transforms that shift layout |\n| **Correct brand logos** | Research official SVG from Simple Icons | Guess or use incorrect logo paths |\n| **Consistent icon sizing** | Use fixed viewBox (24x24) with w-6 h-6 | Mix different icon sizes randomly |\n\n### Interaction & Cursor\n\n| Rule | Do | Don't |\n|------|----|----- |\n| **Cursor pointer** | Add `cursor-pointer` to all clickable/hoverable cards | Leave default cursor on interactive elements |\n| **Hover feedback** | Provide visual feedback (color, shadow, border) | No indication element is interactive |\n| **Smooth transitions** | Use `transition-colors duration-200` | Instant state changes or too slow (>500ms) |\n\n### Light/Dark Mode Contrast\n\n| Rule | Do | Don't |\n|------|----|----- |\n| **Glass card light mode** | Use `bg-white/80` or higher opacity | Use `bg-white/10` (too transparent) |\n| **Text contrast light** | Use `#0F172A` (slate-900) for text | Use `#94A3B8` (slate-400) for body text |\n| **Muted text light** | Use `#475569` (slate-600) minimum | Use gray-400 or lighter |\n| **Border visibility** | Use `border-gray-200` in light mode | Use `border-white/10` (invisible) |\n\n### Layout & Spacing\n\n| Rule | Do | Don't |\n|------|----|----- |\n| **Floating navbar** | Add `top-4 left-4 right-4` spacing | Stick navbar to `top-0 left-0 right-0` |\n| **Content padding** | Account for fixed navbar height | Let content hide behind fixed elements |\n| **Consistent max-width** | Use same `max-w-6xl` or `max-w-7xl` | Mix different container widths |\n\n---\n\n## Pre-Delivery Checklist\n\nBefore delivering UI code, verify these items:\n\n### Visual Quality\n- [ ] No emojis used as icons (use SVG instead)\n- [ ] All icons from consistent icon set (Heroicons/Lucide)\n- [ ] Brand logos are correct (verified from Simple Icons)\n- [ ] Hover states don't cause layout shift\n- [ ] Use theme colors directly (bg-primary) not var() wrapper\n\n### Interaction\n- [ ] All clickable elements have `cursor-pointer`\n- [ ] Hover states provide clear visual feedback\n- [ ] Transitions are smooth (150-300ms)\n- [ ] Focus states visible for keyboard navigation\n\n### Light/Dark Mode\n- [ ] Light mode text has sufficient contrast (4.5:1 minimum)\n- [ ] Glass/transparent elements visible in light mode\n- [ ] Borders visible in both modes\n- [ ] Test both modes before delivery\n\n### Layout\n- [ ] Floating elements have proper spacing from edges\n- [ ] No content hidden behind fixed navbars\n- [ ] Responsive at 375px, 768px, 1024px, 1440px\n- [ ] No horizontal scroll on mobile\n\n### Accessibility\n- [ ] All images have alt text\n- [ ] Form inputs have labels\n- [ ] Color is not the only indicator\n- [ ] `prefers-reduced-motion` respected\n\n### Visual Validation (if Stitch was used in Step 2c)\n- [ ] Generated mockups align with design system tokens (colors, typography, geometry)\n- [ ] Key screens (dashboard, landing) have both MOBILE and DESKTOP variants\n- [ ] No purple, glassmorphism, or standard hero split in mockups (anti-cliche check)\n- [ ] Stitch project ID and screen IDs documented for future reference"
 };
 export const EMBEDDED_ARCHITECTURE = "# Inove AI Framework - Architecture\n\n> Multi-agent AI development framework with 22 agents, 42 skills, 25 workflows, and multi-platform support.\n\n---\n\n## 1. Overview\n\nInove AI Framework is a modular system that enhances AI coding assistants with:\n\n- **22 Specialist Agents** -- Role-based AI personas for different domains\n- **42 Skills** -- Domain-specific knowledge modules loaded on demand\n- **25 Workflows** -- Slash command procedures for structured processes\n- **22 Scripts** -- Python/Bash automation for task tracking, sessions, and validation\n- **Multi-Platform Support** -- Claude Code, Codex CLI, and Antigravity/Gemini\n\nThe canonical source of truth lives in `.agents/`. Other platforms access it through symlinks.\n\n---\n\n## 2. Directory Structure\n\n```\n.agents/\n├── ARCHITECTURE.md              # This file\n├── INSTRUCTIONS.md              # Canonical instructions (synced to CLAUDE.md, AGENTS.md)\n├── agents/                      # 22 specialist agents\n│   ├── orchestrator.md\n│   ├── project-planner.md\n│   ├── product-manager.md\n│   ├── product-owner.md\n│   ├── frontend-specialist.md\n│   ├── backend-specialist.md\n│   ├── database-architect.md\n│   ├── mobile-developer.md\n│   ├── security-auditor.md\n│   ├── penetration-tester.md\n│   ├── debugger.md\n│   ├── devops-engineer.md\n│   ├── test-engineer.md\n│   ├── qa-automation-engineer.md\n│   ├── documentation-writer.md\n│   ├── code-archaeologist.md\n│   ├── performance-optimizer.md\n│   ├── seo-specialist.md\n│   ├── game-developer.md\n│   ├── ux-researcher.md\n│   └── explorer-agent.md\n├── skills/                      # 41 skill modules\n│   ├── api-patterns/\n│   ├── app-builder/\n│   │   └── templates/           # 13 project templates\n│   ├── architecture/\n│   ├── ...                      # (see Skills section below)\n│   └── webapp-testing/\n├── workflows/                   # 22 slash command workflows\n│   ├── brainstorm.md\n│   ├── context.md\n│   ├── ...                      # (see Workflows section below)\n│   └── ui-ux-pro-max.md\n├── scripts/                     # 22 automation scripts\n│   ├── auto_finish.py\n│   ├── dashboard.py\n│   ├── ...                      # (see Scripts section below)\n│   └── verify_all.py\n├── config/                      # Platform-specific configuration\n│   ├── codex.toml\n│   └── mcp.json\n├── rules/                       # Global rules\n│   └── GEMINI.md\n└── .shared/                     # Shared data resources\n    └── ui-ux-pro-max/\n        ├── data/                # 13 CSV datasets + 12 stack CSVs\n        └── scripts/             # Python scripts (core, design_system, search)\n```\n\n---\n\n## 3. Agents (21)\n\nEach agent is a Markdown file in `.agents/agents/` defining a persona, rules, and skill dependencies.\n\n| Agent | Focus | Skills |\n| ----- | ----- | ------ |\n| `orchestrator` | Multi-agent coordination | parallel-agents, behavioral-modes, plan-writing, brainstorming, architecture, lint-and-validate, powershell-windows, bash-linux |\n| `project-planner` | Discovery, architecture, task planning | app-builder, plan-writing, brainstorming, architecture, system-design, gap-analysis |\n| `product-manager` | Requirements, user stories | plan-writing, brainstorming |\n| `product-owner` | Strategy, backlog, MVP, GAP analysis | plan-writing, brainstorming, gap-analysis, doc-review |\n| `frontend-specialist` | Web UI/UX, React, Next.js | nextjs-react-expert, web-design-guidelines, tailwind-patterns, frontend-design, lint-and-validate, gap-analysis |\n| `backend-specialist` | APIs, Node.js, Python, business logic | nodejs-best-practices, python-patterns, api-patterns, database-design, mcp-builder, lint-and-validate, powershell-windows, bash-linux |\n| `database-architect` | Schema design, queries, migrations | database-design |\n| `mobile-developer` | iOS, Android, React Native | mobile-design |\n| `security-auditor` | Security compliance, OWASP | vulnerability-scanner, red-team-tactics, api-patterns, gap-analysis |\n| `penetration-tester` | Offensive security testing | vulnerability-scanner, red-team-tactics, api-patterns |\n| `debugger` | Root cause analysis | systematic-debugging |\n| `devops-engineer` | CI/CD, Docker, infrastructure | deployment-procedures, server-management, powershell-windows, bash-linux |\n| `test-engineer` | Testing strategies | testing-patterns, tdd-workflow, webapp-testing, code-review-checklist, lint-and-validate |\n| `qa-automation-engineer` | E2E testing, CI pipelines | webapp-testing, testing-patterns, lint-and-validate |\n| `documentation-writer` | Manuals, technical docs | documentation-templates |\n| `code-archaeologist` | Legacy code, refactoring | code-review-checklist |\n| `performance-optimizer` | Speed, Web Vitals | performance-profiling |\n| `seo-specialist` | SEO, visibility, GEO | seo-fundamentals, geo-fundamentals |\n| `game-developer` | Game logic, mechanics | game-development |\n| `ux-researcher` | UX research, user flows, wireframes | ux-research, frontend-design, stitch-ui-design, gap-analysis |\n| `explorer-agent` | Codebase analysis, discovery | architecture, plan-writing, brainstorming, systematic-debugging |\n\n> **Note:** All agents implicitly load `clean-code` as a Tier 0 (mandatory) skill.\n\n---\n\n## 4. Skills (41)\n\nSkills are modular knowledge domains in `.agents/skills/`. Each contains at minimum a `SKILL.md` file, and optionally `scripts/` and `references/` subdirectories.\n\n### Frontend and UI\n\n| Skill | Description |\n| ----- | ----------- |\n| `nextjs-react-expert` | Next.js/React performance patterns and optimization rules |\n| `tailwind-patterns` | Tailwind CSS utility patterns and best practices |\n| `frontend-design` | UI/UX patterns, design systems, color/typography systems |\n| `web-design-guidelines` | UI audit against Web Interface Guidelines |\n| `stitch-ui-design` | Stitch MCP integration for generating high-fidelity UI designs from textual wireframes |\n\n### Backend and API\n\n| Skill | Description |\n| ----- | ----------- |\n| `api-patterns` | REST, GraphQL, tRPC design patterns and documentation |\n| `nodejs-best-practices` | Node.js async patterns, modules, error handling |\n| `python-patterns` | Python standards, FastAPI, idiomatic patterns |\n\n### Database\n\n| Skill | Description |\n| ----- | ----------- |\n| `database-design` | Schema design, indexing, migrations, ORM selection, optimization |\n\n### Architecture and Planning\n\n| Skill | Description |\n| ----- | ----------- |\n| `app-builder` | Full-stack app scaffolding with 13 project templates |\n| `architecture` | System design patterns, trade-off analysis, context discovery |\n| `system-design` | Large-scale system design patterns |\n| `plan-writing` | Task planning and breakdown |\n| `brainstorming` | Socratic questioning and dynamic exploration |\n| `gap-analysis` | Identify gaps in product, UX, infrastructure, security, and tech |\n\n### Testing and Quality\n\n| Skill | Description |\n| ----- | ----------- |\n| `testing-patterns` | Jest, Vitest, testing strategies |\n| `webapp-testing` | E2E testing with Playwright |\n| `tdd-workflow` | Test-driven development methodology |\n| `code-review-checklist` | Code review standards and checklists |\n| `lint-and-validate` | Linting, type coverage, validation scripts |\n\n### Security\n\n| Skill | Description |\n| ----- | ----------- |\n| `vulnerability-scanner` | Security auditing, OWASP checklists |\n| `red-team-tactics` | Offensive security techniques |\n\n### Mobile\n\n| Skill | Description |\n| ----- | ----------- |\n| `mobile-design` | Mobile UI/UX, platform-specific patterns (iOS/Android), debugging |\n\n### Game Development\n\n| Skill | Description |\n| ----- | ----------- |\n| `game-development` | 2D/3D games, multiplayer, VR/AR, game design, audio |\n\n### SEO and Growth\n\n| Skill | Description |\n| ----- | ----------- |\n| `seo-fundamentals` | SEO, E-E-A-T, Core Web Vitals optimization |\n| `geo-fundamentals` | Generative Engine Optimization (GEO) |\n\n### UX Research\n\n| Skill | Description |\n| ----- | ----------- |\n| `ux-research` | UX research methodology, user flows, usability testing |\n\n### DevOps and Infrastructure\n\n| Skill | Description |\n| ----- | ----------- |\n| `deployment-procedures` | CI/CD workflows, deploy procedures |\n| `server-management` | Infrastructure management, monitoring |\n\n### Shell and CLI\n\n| Skill | Description |\n| ----- | ----------- |\n| `bash-linux` | Linux commands, shell scripting |\n| `powershell-windows` | Windows PowerShell scripting |\n\n### Performance\n\n| Skill | Description |\n| ----- | ----------- |\n| `performance-profiling` | Web Vitals, Lighthouse audits, profiling |\n\n### Documentation\n\n| Skill | Description |\n| ----- | ----------- |\n| `documentation-templates` | README, API docs, ADR, changelog templates |\n| `doc-review` | Document review and validation |\n\n### Internationalization\n\n| Skill | Description |\n| ----- | ----------- |\n| `i18n-localization` | Internationalization patterns and i18n checking |\n\n### Agent Behavior and Coordination\n\n| Skill | Description |\n| ----- | ----------- |\n| `behavioral-modes` | Agent persona modes and behavioral configuration |\n| `parallel-agents` | Multi-agent coordination patterns |\n| `intelligent-routing` | Request routing to appropriate agents |\n\n### Cross-Cutting\n\n| Skill | Description |\n| ----- | ----------- |\n| `clean-code` | Pragmatic coding standards (mandatory Tier 0 for all agents) |\n| `systematic-debugging` | Root cause analysis, troubleshooting methodology |\n| `mcp-builder` | Model Context Protocol server/tool building |\n\n### App Builder Templates (13)\n\nThe `app-builder` skill includes a `templates/` subdirectory with scaffolding for:\n\n| Template | Stack |\n| -------- | ----- |\n| `astro-static` | Astro static site |\n| `chrome-extension` | Chrome browser extension |\n| `cli-tool` | Command-line tool |\n| `electron-desktop` | Electron desktop app |\n| `express-api` | Express.js REST API |\n| `flutter-app` | Flutter cross-platform app |\n| `monorepo-turborepo` | Turborepo monorepo setup |\n| `nextjs-fullstack` | Next.js full-stack app |\n| `nextjs-saas` | Next.js SaaS starter |\n| `nextjs-static` | Next.js static site |\n| `nuxt-app` | Nuxt.js application |\n| `python-fastapi` | Python FastAPI backend |\n| `react-native-app` | React Native mobile app |\n\n---\n\n## 5. Workflows (22)\n\nSlash command procedures in `.agents/workflows/`. Invoke with `/command`.\n\n| Command | Description |\n| ------- | ----------- |\n| `/define` | Full project planning in 9 phases with GAP Analysis |\n| `/journeys` | Document user journeys and flows |\n| `/context` | Create project context and technical conventions |\n| `/readiness` | Validate readiness for implementation |\n| `/brainstorm` | Socratic exploration and ideation |\n| `/create` | Create new features with guided implementation |\n| `/debug` | Systematic debugging workflow |\n| `/enhance` | Improve and refactor existing code |\n| `/deploy` | Application deployment procedure |\n| `/test` | Generate and run tests |\n| `/plan` | Task breakdown and planning |\n| `/orchestrate` | Multi-agent coordination |\n| `/preview` | Preview changes before applying |\n| `/track` | Update task progress |\n| `/status` | Consolidated project dashboard |\n| `/log` | Record session activity |\n| `/finish` | Mark tasks as complete |\n| `/review` | Post-sprint code review and quality checks |\n| `/test-book` | Generate or update testing notebook artifacts |\n| `/release` | Final release workflow for MVP or production |\n| `/ui-ux-pro-max` | Design system workflow with styles, palettes, and fonts |\n| `/squad` | Manage squads: reusable packages of agents, skills, and workflows |\n\n---\n\n## 6. Scripts (22)\n\nAutomation scripts in `.agents/scripts/` for task management, validation, and session tracking.\n\n### Task and Progress Management\n\n| Script | Description |\n| ------ | ----------- |\n| `finish_task.py` | Mark a backlog task as complete |\n| `auto_finish.py` | Automated task completion protocol |\n| `progress_tracker.py` | Update and display progress bar |\n| `checklist.py` | Priority-based validation (security, lint, types, tests, UX, SEO) |\n| `shard_epic.py` | Split backlog into individual story files (shard/sync/status/clean) |\n\n### Session Management\n\n| Script | Description |\n| ------ | ----------- |\n| `auto_session.py` | Start/stop session tracking |\n| `session_logger.py` | Log session activity |\n| `project_analyzer.py` | Analyze project state and tech stack |\n\n### Dashboard and Metrics\n\n| Script | Description |\n| ------ | ----------- |\n| `dashboard.py` | Consolidated project dashboard view |\n| `metrics.py` | Generate insights and metrics |\n\n### Multi-Agent Coordination\n\n| Script | Description |\n| ------ | ----------- |\n| `lock_manager.py` | File lock management for multi-agent work |\n| `sync_tracker.py` | Synchronization tracking between agents |\n| `platform_compat.py` | Auto-detect active AI platform (claude_code, codex, unknown) |\n\n### Validation\n\n| Script | Description |\n| ------ | ----------- |\n| `verify_all.py` | Comprehensive pre-deployment verification (all checks) |\n| `validate_installation.py` | Verify framework installation and setup |\n| `validate_traceability.py` | Validate backlog-to-code traceability |\n| `_check_runner.py` | Shared check runner utilities for verification scripts |\n\n### Notifications and Previews\n\n| Script | Description |\n| ------ | ----------- |\n| `notifier.py` | Send notifications on task events |\n| `reminder_system.py` | Scheduled reminders for pending tasks |\n| `auto_preview.py` | Automated preview generation |\n| `generate_web_data.py` | Generate JSON data artifacts for web docs/dashboard |\n\n### Squads and Recovery\n\n| Script | Description |\n| ------ | ----------- |\n| `squad_manager.py` | Create, validate, activate, deactivate, and export squads |\n| `recovery.py` | Retry with exponential backoff, safe execution with rollback, git checkpoints |\n\n### Git Hooks\n\n| Script | Description |\n| ------ | ----------- |\n| `install_git_hooks.sh` | Install pre-commit and post-commit hooks |\n\n---\n\n## 7. Multi-Platform Support\n\nInove AI Framework runs on three AI platforms simultaneously. The canonical source is `.agents/`, and each platform accesses it through symlinks or direct references.\n\n### Platform Configuration\n\n| Platform | Instruction File | Agents Path | Skills Path | Workflows Path |\n| -------- | ---------------- | ----------- | ----------- | -------------- |\n| Claude Code | `CLAUDE.md` | `.claude/agents/` -> `.agents/agents/` | `.claude/skills/` -> `.agents/skills/` | `.agents/workflows/` (direct) |\n| Codex CLI | `AGENTS.md` | `.codex/agents/` -> `.agents/agents/` | `.codex/skills/` -> `.agents/skills/` | `.codex/prompts/` -> `.agents/workflows/` |\n| Antigravity/Gemini | `GEMINI.md` | `.agents/agents/` (direct) | `.agents/skills/` (direct) | `.agents/workflows/` (direct) |\n\n### Symlink Map\n\n```\n.claude/\n├── agents  -> ../.agents/agents     (symlink)\n├── skills  -> ../.agents/skills     (symlink)\n├── project_instructions.md\n├── settings.json\n└── settings.local.json\n\n.codex/\n├── agents  -> ../.agents/agents     (symlink)\n├── skills  -> ../.agents/skills     (symlink)\n├── prompts -> ../.agents/workflows  (symlink)\n└── config.toml\n```\n\n### Platform Detection\n\nScripts auto-detect the active platform:\n\n```python\nfrom platform_compat import get_agent_source\nsource = get_agent_source()  # Returns 'claude_code', 'codex', or 'unknown'\n```\n\nEnvironment variable override:\n\n```bash\nexport AGENT_SOURCE=claude_code   # For Claude Code\nexport AGENT_SOURCE=codex         # For Codex CLI\nexport AGENT_SOURCE=antigravity   # For Antigravity/Gemini\n```\n\n### Platform-Specific Config\n\n| File | Platform | Purpose |\n| ---- | -------- | ------- |\n| `.agents/config/codex.toml` | Codex CLI | Codex-specific configuration |\n| `.agents/config/mcp.json` | All | Model Context Protocol server configuration |\n| `.agents/rules/GEMINI.md` | Antigravity/Gemini | Gemini-specific rules and instructions |\n\n---\n\n## 8. Shared Resources\n\n### UI/UX Pro Max Data (`.agents/.shared/ui-ux-pro-max/`)\n\nA curated dataset of design system references used by the `/ui-ux-pro-max` workflow.\n\n#### Data CSVs (`.shared/ui-ux-pro-max/data/`)\n\n| File | Content |\n| ---- | ------- |\n| `styles.csv` | Design style references |\n| `colors.csv` | Color palettes |\n| `typography.csv` | Font pairings |\n| `icons.csv` | Icon sets |\n| `charts.csv` | Chart/data visualization patterns |\n| `landing.csv` | Landing page patterns |\n| `products.csv` | Product page patterns |\n| `prompts.csv` | AI prompt templates for design |\n| `react-performance.csv` | React performance rules |\n| `ui-reasoning.csv` | UI decision reasoning data |\n| `ux-guidelines.csv` | UX guideline references |\n| `web-interface.csv` | Web interface patterns |\n\n#### Stack-Specific Data (`.shared/ui-ux-pro-max/data/stacks/`)\n\nFramework-specific implementation patterns:\n\n| File | Framework |\n| ---- | --------- |\n| `react.csv` | React |\n| `nextjs.csv` | Next.js |\n| `vue.csv` | Vue.js |\n| `nuxtjs.csv` | Nuxt.js |\n| `nuxt-ui.csv` | Nuxt UI |\n| `svelte.csv` | Svelte |\n| `flutter.csv` | Flutter |\n| `react-native.csv` | React Native |\n| `swiftui.csv` | SwiftUI |\n| `jetpack-compose.csv` | Jetpack Compose |\n| `shadcn.csv` | shadcn/ui |\n| `html-tailwind.csv` | HTML + Tailwind CSS |\n\n#### Python Scripts (`.shared/ui-ux-pro-max/scripts/`)\n\n| Script | Purpose |\n| ------ | ------- |\n| `core.py` | Core utilities for data loading and processing |\n| `design_system.py` | Design system generation from CSV data |\n| `search.py` | Search across design data |\n\n---\n\n## 9. Squad System\n\nSquads are reusable packages of agents + skills + workflows for specific domains.\n\n### Structure\n\n```\nsquads/\n├── README.md                    # Documentation\n├── .templates/                  # Templates for creation\n│   ├── basic/                   # Minimal template\n│   └── specialist/              # Full template with skills + workflows\n└── <name>/                      # User-created squads\n    ├── squad.yaml               # Required manifest\n    ├── agents/                  # Squad agents\n    ├── skills/                  # Squad skills\n    ├── workflows/               # Squad workflows\n    └── config/                  # Optional configuration\n```\n\n### Activation\n\nWhen a squad is activated via `squad_manager.py activate <name>`, symlinks are created:\n- `.agents/agents/<agent>.md` -> `../../squads/<name>/agents/<agent>.md`\n- `.agents/skills/<skill>/` -> `../../squads/<name>/skills/<skill>/`\n- `.agents/workflows/<wf>.md` -> `../../squads/<name>/workflows/<wf>.md`\n\nThis makes squad components visible to the framework without code changes.\n\n### Recovery System\n\nThe `recovery.py` module provides resilience utilities:\n- `with_retry(fn, max_attempts=3, backoff=2)` — Retry with exponential backoff\n- `safe_execute(command, rollback_fn=None)` — Execute with rollback on failure\n- `git_checkpoint(label)` / `git_rollback(label)` — Git stash checkpoints\n\nUsed by: `checklist.py`, `auto_preview.py`, `finish_task.py`\n\n---\n\n## Skill Loading Protocol\n\n```\nUser Request\n    |\n    v\nDetect Domain -> Match Agent -> Read agent .md frontmatter\n                                    |\n                                    v\n                              Load skill SKILL.md files\n                                    |\n                                    v\n                              Load scripts/ (if present)\n                                    |\n                                    v\n                              Apply agent persona + rules\n```\n\n### Skill File Structure\n\n```\nskill-name/\n├── SKILL.md           # Required: Metadata, instructions, rules\n├── scripts/           # Optional: Python/Bash validation scripts\n├── references/        # Optional: Templates, supplementary docs\n└── *.md               # Optional: Additional topic-specific docs\n```\n\n---\n\n## Statistics\n\n| Metric | Count |\n| ------ | ----- |\n| Agents | 21 (core) + N (squads) |\n| Skills | 41 (core) + N (squads) |\n| Workflows | 22 |\n| Scripts | 22 |\n| App Templates | 13 |\n| Shared Data CSVs | 13 (general) + 12 (stack-specific) |\n| Supported Platforms | 3 (Claude Code, Codex CLI, Antigravity/Gemini) |\n";
-export const EMBEDDED_INSTRUCTIONS = "# INSTRUCTIONS.md - Instruções Compartilhadas do Inove AI Framework\n\n> Este arquivo contém as instruções compartilhadas para Claude Code e Codex CLI.\n> É carregado automaticamente por ambas as ferramentas.\n\n## Sobre Este Projeto\n\n**Inove AI Framework** é um kit de desenvolvimento AI com sistema multi-agent (Claude Code + Codex CLI + Antigravity/Gemini) que fornece:\n\n- **22 Agentes Especializados** para diferentes domínios\n- **42 Skills Modulares** carregadas sob demanda\n- **25 Workflows** (slash commands) para processos estruturados\n- **Sistema Multi-Agent** com sincronização de locks e ownership\n\n---\n\n## Estrutura do Framework\n\n```\n.agents/\n├── agents/           # 22 agentes especializados\n├── skills/           # 41 módulos de conhecimento\n├── workflows/        # 25 workflows (slash commands)\n├── scripts/          # Automação Python\n├── config/           # Configurações por plataforma\n└── ARCHITECTURE.md   # Documentação técnica\n```\n\n---\n\n## Protocolo de Roteamento Inteligente\n\n### 1. Detecção de Domínio (AUTOMÁTICO)\n\n| Palavras-chave | Domínio | Agente Primário |\n|----------------|---------|-----------------|\n| \"UI\", \"componente\", \"página\", \"frontend\" | Frontend | `frontend-specialist` |\n| \"API\", \"endpoint\", \"backend\", \"servidor\" | Backend | `backend-specialist` |\n| \"database\", \"schema\", \"query\", \"migração\" | Database | `database-architect` |\n| \"mobile\", \"iOS\", \"Android\", \"React Native\" | Mobile | `mobile-developer` |\n| \"auth\", \"segurança\", \"vulnerabilidade\" | Security | `security-auditor` |\n| \"bug\", \"erro\", \"não funciona\", \"debug\" | Debug | `debugger` |\n| \"unit test\", \"TDD\", \"cobertura\", \"jest\", \"vitest\", \"pytest\" | Unit/Integration Testing | `test-engineer` |\n| \"e2e\", \"playwright\", \"cypress\", \"pipeline\", \"regressão\", \"automated test\" | E2E/QA Pipeline | `qa-automation-engineer` |\n| \"deploy\", \"docker\", \"infraestrutura\" | DevOps | `devops-engineer` |\n| \"requisitos\", \"user story\", \"backlog\", \"MVP\" | Product | `product-owner` |\n| \"UX\", \"user flow\", \"wireframe\", \"jornada\", \"usabilidade\" | UX Research | `ux-researcher` |\n\n### 2. Ativação de Agente (OBRIGATÓRIO)\n\nQuando um domínio for detectado:\n\n1. **Ler arquivo do agente:** `.agents/agents/{agent}.md`\n2. **Anunciar ativação:**\n   ```\n   🤖 Ativando @{nome-do-agente}...\n   📖 Carregando regras e protocolos\n   ```\n3. **Carregar skills** do frontmatter do agente\n4. **Aplicar persona e regras** do agente\n\n---\n\n## Workflows Disponíveis (Slash Commands)\n\n| Comando | Descrição | Quando Usar |\n|---------|-----------|-------------|\n| `/define` | Planejamento completo em 9 fases com GAP Analysis | Novos projetos do zero |\n| `/journeys` | Documentar jornadas de usuário | Contextualizar requisitos |\n| `/context` | Criar Project Context | Padronizar convenções técnicas |\n| `/readiness` | Validar prontidão para implementação | Antes de começar a codar |\n| `/brainstorm` | Exploração Socrática | Ideação e descoberta |\n| `/create` | Criar novas features | Implementação guiada |\n| `/debug` | Debug sistemático | Resolução de bugs |\n| `/enhance` | Melhorar código existente | Refatoração |\n| `/deploy` | Deploy de aplicação | Publicação |\n| `/test` | Gerar e rodar testes | Quality assurance |\n| `/track` | Atualizar progresso | Tracking de tarefas |\n| `/status` | Dashboard consolidado | Visão geral |\n| `/log` | Registrar sessões | Documentação |\n| `/finish` | Marcar tarefas completas | Conclusão |\n| `/orchestrate` | Coordenação multi-agente | Tarefas que requerem múltiplos agentes |\n| `/plan` | Planejamento rápido de tarefas | Plano leve (alternativa ao /define) |\n| `/preview` | Gerenciar servidor de preview | Start/stop/restart do dev server |\n| `/ui-ux-pro-max` | Design system avançado com base de dados | UI/UX com paletas, tipografia, estilos |\n| `/review` | Revisão de código pós-sprint | Após implementação, antes de /finish |\n| `/test-book` | Gerar/atualizar Caderno de Testes | Antes de finalizar MVP ou release |\n| `/release` | Finalizar projeto e gerar release | Conclusão de MVP ou Produção |\n| `/squad` | Gerenciar squads de agentes | Criação e ativação de squads |\n\n**Como usar:**\n```\n/define App de gestão de tarefas\n/debug O login não está funcionando\n/track\n```\n\n---\n\n## Protocolo Auto-Finish (OBRIGATÓRIO)\n\nApós completar QUALQUER tarefa do `docs/BACKLOG.md`:\n\n```bash\npython3 .agents/scripts/finish_task.py \"{task_id}\"\npython3 .agents/scripts/progress_tracker.py\n```\n\nInformar ao usuário:\n```\n✅ Task {task_id} marcada como completa\n📊 Progresso atualizado: {percentual}%\n🎯 Próxima tarefa: {nome_proxima_tarefa}\n```\n\n---\n\n## Integração com Backlog\n\nQuando o usuário disser \"implementar Epic X\" ou \"implementar Story Y.Z\":\n\n1. **Ler backlog:** `docs/BACKLOG.md`\n2. **Identificar detalhes** da tarefa\n3. **Detectar domínio** → Ativar agente apropriado\n4. **Implementar** seguindo regras do agente\n5. **Auto-finish** usando scripts\n6. **Atualizar progresso**\n\n---\n\n## Regras Universais (TIER 0)\n\n### Clean Code (Mandatório Global)\n\nTodo código DEVE seguir `.agents/skills/clean-code/SKILL.md`:\n\n- Código conciso e auto-documentado\n- Sem over-engineering\n- Testes obrigatórios (Unit > Integration > E2E)\n- Performance medida antes de otimizar\n\n### Tratamento de Idioma\n\n- **Prompt do usuário** em PT-BR → Responder em PT-BR\n- **Comentários de código** → Sempre em inglês\n- **Variáveis/funções** → Sempre em inglês\n\n\n### Socratic Gate\n\nPara requisições complexas, PERGUNTAR antes de implementar:\n\n- Propósito e escopo\n- Casos de borda\n- Implicações de performance\n- Considerações de segurança\n\n---\n\n## Registro de Sessoes de Trabalho (OBRIGATORIO)\n\n### Objetivo\nRastrear sessões de trabalho e gerar um relatório diário consolidado em Markdown.\n\n### Regras de Operação\n1. **Fonte Única:** SEMPRE use `auto_session.py` para gerir sessões. NUNCA edite os logs manualmente.\n2. **Abertura:** Use o comando start no início de cada sessão de trabalho.\n3. **Encerramento:** Ao concluir entregas ou terminar a interação, use o comando end passando a lista exata do que construiu/modificou.\n4. **Fechamento Automático:** O script cuida do cabeçalho, cálculo do resumo do dia e índice do README.\n\n### Comandos\n\n```bash\npython3 .agents/scripts/auto_session.py start --agent <claude_code|codex|antigravity>  # Abrir sessão\npython3 .agents/scripts/auto_session.py end --activities \"ativ1; ativ2\"                 # Fechar sessão\npython3 .agents/scripts/auto_session.py status                                          # Ver sessão ativa\n```\n\n### Critérios de Qualidade\nA saída da descrição das atividades enviadas à flag `--activities` deve ser curta e objetiva. Abstê-se de logar dados sensíveis.\n\n---\n\n## 📂 Organização de Documentação (OBRIGATÓRIO)\n\nA documentação DEVE seguir esta estrutura de pastas. Não crie arquivos soltos na raiz de `docs/` (exceto BACKLOG.md).\n\n**Padrão oficial** (criado pelo `/define`):\n\n```bash\ndocs/\n├── 00-Contexto/        # Contexto do projeto e regras\n│   ├── CONTEXT.md      # Gerado por /context\n│   └── READINESS.md    # Gerado por /readiness\n├── 01-Planejamento/    # Artefatos executivos do /define\n│   ├── 01-product-brief.md\n│   ├── 02-prd.md\n│   ├── 03-design-system.md\n│   ├── 04-database-schema.md\n│   └── 05-roadmap-backlog.md\n├── 02-Requisitos/      # Detalhamento funcional\n│   ├── User-Stories.md\n│   └── Jornadas.md     # Gerado por /journeys\n├── 03-Arquitetura/     # Técnicos e Decisões\n│   ├── ADRs/           # Architecture Decision Records\n│   └── Diagramas/      # Mermaid/PlantUML (fluxos, classes)\n├── 04-API/            # Contratos de Interface\n│   └── Endpoints.md    # OpenAPI ou Docs REST\n├── 08-Logs-Sessoes/    # Logs de Sessão de Trabalho\n│   └── {ANO}/{DATA}.md # Logs diários\n└── BACKLOG.md          # Backlog Mestre (Raiz)\n```\n\n**Aliases aceitos** (fallback legado / projetos sem `/define`):\n\n| Oficial (padrão)     | Alias aceito          |\n|----------------------|-----------------------|\n| `docs/01-Planejamento/` | `docs/planning/`   |\n| `docs/00-Contexto/`     | `docs/context/`    |\n| `docs/02-Requisitos/`   | `docs/requirements/` |\n| `docs/03-Arquitetura/`  | `docs/architecture/` |\n| `docs/04-API/`          | `docs/api/`        |\n| `docs/08-Logs-Sessoes/` | `docs/logs/`       |\n\n> **Resolução:** Ao procurar documentos, tente primeiro o caminho oficial. Se não existir, tente o alias. Use `resolve_doc_path()` / `resolve_doc_file()` de `platform_compat.py` em scripts Python.\n\n**Regra:** Ao criar documentos, sempre verifique se a pasta existe. Se não existir, crie-a.\n\n---\n\n## Compatibilidade Multi-Plataforma\n\nEste framework suporta **três ferramentas AI simultaneamente**:\n\n| Ferramenta | Arquivo de Instrução | Skills Location | Config |\n|------------|---------------------|-----------------|--------|\n| Claude Code | `CLAUDE.md` | `.agents/skills/` | N/A |\n| Codex CLI | `AGENTS.md` | `.codex/skills/` (symlink) | `.agents/config/codex.toml` |\n| Antigravity/Gemini | `GEMINI.md` | `.agents/skills/` | N/A |\n\n### Symlinks Nativos\n\nCada plataforma acessa os mesmos recursos via caminhos nativos (symlinks para `.agents/`):\n\n| Plataforma | Agents | Skills | Workflows |\n|------------|--------|--------|-----------|\n| Claude Code | `.claude/agents/` | `.claude/skills/` | `.agents/workflows/` |\n| Codex CLI | `.codex/agents/` | `.codex/skills/` | `.codex/prompts/` |\n| Antigravity | `.agents/agents/` | `.agents/skills/` | `.agents/workflows/` |\n\n> **Fonte canônica:** `.agents/` — todos os symlinks apontam para lá.\n\n### Detecção Automática de Plataforma\n\nOs scripts Python detectam automaticamente qual ferramenta está executando:\n\n```python\nfrom platform_compat import get_agent_source\nsource = get_agent_source()  # 'claude_code', 'codex', ou 'unknown'\n```\n\n## Sistema Multi-Agent\n\nEste framework suporta múltiplos agentes AI trabalhando simultaneamente:\n\n### Identificação de Fonte\n```bash\n# Para Antigravity/Gemini\nexport AGENT_SOURCE=antigravity\n\n# Para Claude Code\nexport AGENT_SOURCE=claude_code\n\n# Para Codex CLI\nexport AGENT_SOURCE=codex\n```\n\n### Lock Manager\n```bash\npython3 .agents/scripts/lock_manager.py list      # Ver locks ativos\npython3 .agents/scripts/lock_manager.py cleanup   # Limpar locks expirados\n```\n\n### Ownership e Modelo Preferencial de Epics\n\nFormato no BACKLOG.md:\n```markdown\n## Epic 1: Nome [OWNER: claude_code] [MODEL: opus-4-5]\n```\n\n| Campo | Descrição | Valores |\n|-------|-----------|---------|\n| `OWNER` | Agente/ferramenta responsável | `claude_code`, `antigravity`, `codex` |\n| `MODEL` | Modelo AI preferencial | `opus-4-5`, `sonnet`, `haiku`, `gemini-2.0` |\n\n---\n\n## Scripts Úteis\n\n| Script | Comando | Descrição |\n|--------|---------|-----------|\n| Dashboard | `python3 .agents/scripts/dashboard.py` | Visão consolidada |\n| Progresso | `python3 .agents/scripts/progress_tracker.py` | Atualizar barra |\n| Sessão | `python3 .agents/scripts/auto_session.py start` | Iniciar sessão |\n| Finish | `python3 .agents/scripts/finish_task.py \"Epic-1\"` | Marcar completo |\n| Métricas | `python3 .agents/scripts/metrics.py` | Insights |\n| Validar | `python3 .agents/scripts/validate_installation.py` | Verificar setup |\n| Rastreabilidade | `python3 .agents/scripts/validate_traceability.py` | Validar cobertura |\n| Projeto | `python3 .agents/scripts/project_analyzer.py status` | Analisar tech stack |\n| Web Data | `python3 .agents/scripts/generate_web_data.py` | Gerar JSONs do site |\n| Checklist | `python3 .agents/scripts/checklist.py .` | Validação incremental |\n| Verificar Tudo | `python3 .agents/scripts/verify_all.py .` | Verificação completa |\n| Squad Manager | `python3 .agents/scripts/squad_manager.py list` | Gerenciar squads |\n| Recovery | `python3 .agents/scripts/recovery.py checkpoint <label>` | Retry + rollback |\n| Shard Epic | `python3 .agents/scripts/shard_epic.py shard` | Fatiar backlog em stories |\n\n---\n\n## Sistema de Squads\n\nSquads são pacotes reutilizáveis de agentes+skills+workflows para domínios específicos.\nSquads ficam em `squads/<nome>/` com manifesto `squad.yaml`. Detalhes em `squads/README.md`.\n\n| Comando | Descrição |\n|---------|-----------|\n| `/squad create <name>` | Criar novo squad |\n| `/squad list` | Listar squads |\n| `/squad activate <name>` | Ativar no framework |\n| `/squad deactivate <name>` | Desativar |\n\n---\n\n### Stitch MCP (Projetos com UI)\n\nPara TODOS os projetos com interface visual (HAS_UI=true):\n\n| Cenário | Comportamento |\n|---------|---------------|\n| Stitch MCP **disponível** + HAS_UI=true | **OBRIGATÓRIO** gerar protótipos via Stitch para **TODAS** as telas do sistema |\n| Stitch MCP **não disponível** + HAS_UI=true | **PARAR** e informar usuário para configurar Stitch antes de continuar |\n| HAS_UI=false | Fase 3.5 ignorada |\n\n**Regras de Cobertura Total:**\n- `/define` Fase 3.5: Prototipar **TODAS** as telas identificadas no UX Concept (não apenas 1 ou 2)\n- `/ui-ux-pro-max` Step 2c: Preview visual é OBRIGATÓRIO\n- `/readiness`: Valida existência de mockups E cobertura completa\n- **Gate de Bloqueio:** Fase 4 (Architecture) é BLOQUEADA até cobertura 100% das telas\n\nProjetos sem UI (API, CLI, backend-only): Stitch é ignorado.\n\n---\n\n### Recovery System\n\nScripts críticos usam retry automático e git checkpoint para operações seguras.\nMódulo: `.agents/scripts/recovery.py`\n\n---\n\n## Inicialização de Sessão\n\n> **PULO DO GATO (Context State):** Sempre que iniciar o trabalho com o usuário, **leia silenciosamente o arquivo `docs/PROJECT_STATUS.md`** (se existir). Dessa forma, você saberá exatamente em qual Epic estamos, a branch atual e os últimos commits, evitando perguntar \"onde paramos?\".\n\nToda conversa começa com:\n\n```\n✅ Project Instructions carregadas\n✅ Protocolo Inove AI Framework ativo\n✅ 22 agentes disponíveis\n✅ 42 skills disponíveis\n✅ 25 workflows disponíveis\n✅ Roteamento inteligente habilitado\n\n🎯 Pronto para trabalhar. O que devo fazer?\n```\n\n---\n\n## Referência Rápida de Agentes\n\n| Agente | Arquivo | Skills Primárias |\n|--------|---------|------------------|\n| `orchestrator` | `.agents/agents/orchestrator.md` | Coordenação multi-agente |\n| `project-planner` | `.agents/agents/project-planner.md` | Planejamento, discovery |\n| `product-manager` | `.agents/agents/product-manager.md` | Requisitos, user stories |\n| `frontend-specialist` | `.agents/agents/frontend-specialist.md` | React, UI/UX, Tailwind |\n| `backend-specialist` | `.agents/agents/backend-specialist.md` | APIs, Node.js, lógica |\n| `database-architect` | `.agents/agents/database-architect.md` | Schemas, Prisma, queries |\n| `mobile-developer` | `.agents/agents/mobile-developer.md` | iOS, Android, RN |\n| `security-auditor` | `.agents/agents/security-auditor.md` | Auth, OWASP, compliance |\n| `debugger` | `.agents/agents/debugger.md` | Root cause analysis |\n| `devops-engineer` | `.agents/agents/devops-engineer.md` | CI/CD, Docker, infra |\n| `test-engineer` | `.agents/agents/test-engineer.md` | Estratégias de teste |\n| `qa-automation-engineer` | `.agents/agents/qa-automation-engineer.md` | E2E, automação |\n| `documentation-writer` | `.agents/agents/documentation-writer.md` | Manuais, docs |\n| `code-archaeologist` | `.agents/agents/code-archaeologist.md` | Refatoração legacy |\n| `performance-optimizer` | `.agents/agents/performance-optimizer.md` | Otimizações |\n| `seo-specialist` | `.agents/agents/seo-specialist.md` | SEO, visibilidade |\n| `penetration-tester` | `.agents/agents/penetration-tester.md` | Security testing |\n| `game-developer` | `.agents/agents/game-developer.md` | Game logic |\n| `product-owner` | `.agents/agents/product-owner.md` | Requisitos, backlog, MVP |\n| `explorer-agent` | `.agents/agents/explorer-agent.md` | Análise de codebase |\n| `ux-researcher` | `.agents/agents/ux-researcher.md` | UX research, user flows, wireframes |\n\n---\n\n## Exemplo de Fluxo Completo\n\n**Usuário:** \"Implementar Epic 1: Autenticação de Usuários\"\n\n**Claude:**\n1. 🔍 Domínio detectado: Security + Backend\n2. 🤖 Ativando agentes:\n   - @security-auditor (líder)\n   - @backend-specialist (suporte)\n3. 📖 Carregando skills: vulnerability-scanner, api-patterns\n4. [Implementa código seguindo regras dos agentes]\n5. ✅ Implementação completa\n6. 🔧 Executando: `python3 .agents/scripts/finish_task.py \"Epic 1\"`\n7. 📊 Progresso: 25% (1/4 epics concluídos)\n\n**Usuário:** `/define App de gestão de tarefas`\n\n**Claude (ou Antigravity):**\n1. Fase 0: Discovery (12 perguntas estruturadas)\n2. Fase 1: Brief (`product-manager`)\n3. Fase 2: PRD + GAP Produto (`product-owner`)\n4. Fase 3: UX Concept + GAP UX (`ux-researcher`)\n5. Fase 4: Architecture + DB + GAP Infra (`project-planner`)\n6. Fase 5: Security + GAP Segurança (`security-auditor`)\n7. Fase 6: Stack + GAP Tech (`project-planner`)\n8. Fase 7: Design System + GAP Design (`frontend-specialist`)\n9. Fase 8: Backlog + GAPs consolidados (`product-owner`)\n10. Revisão: Claude Code/Codex valida com skill `doc-review`\n";
+export const EMBEDDED_INSTRUCTIONS = "# INSTRUCTIONS.md - Instruções Compartilhadas do Inove AI Framework\n\n> Este arquivo contém as instruções compartilhadas para Claude Code e Codex CLI.\n> É carregado automaticamente por ambas as ferramentas.\n\n## Sobre Este Projeto\n\n**Inove AI Framework** é um kit de desenvolvimento AI com sistema multi-agent (Claude Code + Codex CLI + Antigravity/Gemini) que fornece:\n\n- **22 Agentes Especializados** para diferentes domínios\n- **42 Skills Modulares** carregadas sob demanda\n- **25 Workflows** (slash commands) para processos estruturados\n- **Sistema Multi-Agent** com sincronização de locks e ownership\n\n---\n\n## Estrutura do Framework\n\n```\n.agents/\n├── agents/           # 22 agentes especializados\n├── skills/           # 41 módulos de conhecimento\n├── workflows/        # 25 workflows (slash commands)\n├── scripts/          # Automação Python\n├── config/           # Configurações por plataforma\n└── ARCHITECTURE.md   # Documentação técnica\n```\n\n---\n\n## Protocolo de Roteamento Inteligente\n\n### 1. Detecção de Domínio (AUTOMÁTICO)\n\n| Palavras-chave | Domínio | Agente Primário |\n|----------------|---------|-----------------|\n| \"UI\", \"componente\", \"página\", \"frontend\" | Frontend | `frontend-specialist` |\n| \"API\", \"endpoint\", \"backend\", \"servidor\" | Backend | `backend-specialist` |\n| \"database\", \"schema\", \"query\", \"migração\" | Database | `database-architect` |\n| \"mobile\", \"iOS\", \"Android\", \"React Native\" | Mobile | `mobile-developer` |\n| \"auth\", \"segurança\", \"vulnerabilidade\" | Security | `security-auditor` |\n| \"bug\", \"erro\", \"não funciona\", \"debug\" | Debug | `debugger` |\n| \"unit test\", \"TDD\", \"cobertura\", \"jest\", \"vitest\", \"pytest\" | Unit/Integration Testing | `test-engineer` |\n| \"e2e\", \"playwright\", \"cypress\", \"pipeline\", \"regressão\", \"automated test\" | E2E/QA Pipeline | `qa-automation-engineer` |\n| \"deploy\", \"docker\", \"infraestrutura\" | DevOps | `devops-engineer` |\n| \"requisitos\", \"user story\", \"backlog\", \"MVP\" | Product | `product-owner` |\n| \"UX\", \"user flow\", \"wireframe\", \"jornada\", \"usabilidade\" | UX Research | `ux-researcher` |\n\n### 2. Ativação de Agente (OBRIGATÓRIO)\n\nQuando um domínio for detectado:\n\n1. **Ler arquivo do agente:** `.agents/agents/{agent}.md`\n2. **Anunciar ativação:**\n   ```\n   🤖 Ativando @{nome-do-agente}...\n   📖 Carregando regras e protocolos\n   ```\n3. **Carregar skills** do frontmatter do agente\n4. **Aplicar persona e regras** do agente\n\n---\n\n## Workflows Disponíveis (Slash Commands)\n\n| Comando | Descrição | Quando Usar |\n|---------|-----------|-------------|\n| `/define` | Planejamento completo em 9 fases com GAP Analysis | Novos projetos do zero |\n| `/journeys` | Documentar jornadas de usuário | Contextualizar requisitos |\n| `/context` | Criar Project Context | Padronizar convenções técnicas |\n| `/readiness` | Validar prontidão para implementação | Antes de começar a codar |\n| `/brainstorm` | Exploração Socrática | Ideação e descoberta |\n| `/create` | Criar novas features | Implementação guiada |\n| `/debug` | Debug sistemático | Resolução de bugs |\n| `/enhance` | Melhorar código existente | Refatoração |\n| `/deploy` | Deploy de aplicação | Publicação |\n| `/test` | Gerar e rodar testes | Quality assurance |\n| `/track` | Atualizar progresso | Tracking de tarefas |\n| `/status` | Dashboard consolidado | Visão geral |\n| `/log` | Registrar sessões | Documentação |\n| `/finish` | Marcar tarefas completas | Conclusão |\n| `/orchestrate` | Coordenação multi-agente | Tarefas que requerem múltiplos agentes |\n| `/plan` | Planejamento rápido de tarefas | Plano leve (alternativa ao /define) |\n| `/preview` | Gerenciar servidor de preview | Start/stop/restart do dev server |\n| `/ui-ux-pro-max` | Design system avançado com base de dados | UI/UX com paletas, tipografia, estilos |\n| `/review` | Revisão de código pós-sprint | Após implementação, antes de /finish |\n| `/test-book` | Gerar/atualizar Caderno de Testes | Antes de finalizar MVP ou release |\n| `/release` | Finalizar projeto e gerar release | Conclusão de MVP ou Produção |\n| `/squad` | Gerenciar squads de agentes | Criação e ativação de squads |\n\n**Como usar:**\n```\n/define App de gestão de tarefas\n/debug O login não está funcionando\n/track\n```\n\n---\n\n## Protocolo Auto-Finish (OBRIGATÓRIO)\n\nApós completar QUALQUER tarefa do `docs/BACKLOG.md`:\n\n```bash\npython3 .agents/scripts/finish_task.py \"{task_id}\"\npython3 .agents/scripts/progress_tracker.py\n```\n\nInformar ao usuário:\n```\n✅ Task {task_id} marcada como completa\n📊 Progresso atualizado: {percentual}%\n🎯 Próxima tarefa: {nome_proxima_tarefa}\n```\n\n---\n\n## Integração com Backlog\n\nQuando o usuário disser \"implementar Epic X\" ou \"implementar Story Y.Z\":\n\n1. **Ler backlog:** `docs/BACKLOG.md`\n2. **Verificar shards:** Se `docs/stories/` não existir, executar `python3 .agents/scripts/shard_epic.py shard` antes de continuar\n3. **Identificar detalhes** da tarefa\n4. **Detectar domínio** → Ativar agente apropriado\n5. **Implementar** seguindo regras do agente\n6. **Auto-finish** usando scripts\n7. **Atualizar progresso**\n\n> **Regra:** Após `/define` ou `/readiness`, se `docs/stories/` não existir, executar `python3 .agents/scripts/shard_epic.py shard` automaticamente antes de iniciar qualquer implementação.\n\n---\n\n## Regras Universais (TIER 0)\n\n### Clean Code (Mandatório Global)\n\nTodo código DEVE seguir `.agents/skills/clean-code/SKILL.md`:\n\n- Código conciso e auto-documentado\n- Sem over-engineering\n- Testes obrigatórios (Unit > Integration > E2E)\n- Performance medida antes de otimizar\n\n### Tratamento de Idioma\n\n- **Prompt do usuário** em PT-BR → Responder em PT-BR\n- **Comentários de código** → Sempre em inglês\n- **Variáveis/funções** → Sempre em inglês\n\n\n### Socratic Gate\n\nPara requisições complexas, PERGUNTAR antes de implementar:\n\n- Propósito e escopo\n- Casos de borda\n- Implicações de performance\n- Considerações de segurança\n\n---\n\n## Registro de Sessoes de Trabalho (OBRIGATORIO)\n\n### Objetivo\nRastrear sessões de trabalho e gerar um relatório diário consolidado em Markdown.\n\n### Regras de Operação\n1. **Fonte Única:** SEMPRE use `auto_session.py` para gerir sessões. NUNCA edite os logs manualmente.\n2. **Abertura:** Use o comando start no início de cada sessão de trabalho.\n3. **Encerramento:** Ao concluir entregas ou terminar a interação, use o comando end passando a lista exata do que construiu/modificou.\n4. **Fechamento Automático:** O script cuida do cabeçalho, cálculo do resumo do dia e índice do README.\n\n### Comandos\n\n```bash\npython3 .agents/scripts/auto_session.py start --agent <claude_code|codex|antigravity>  # Abrir sessão\npython3 .agents/scripts/auto_session.py end --activities \"ativ1; ativ2\"                 # Fechar sessão\npython3 .agents/scripts/auto_session.py status                                          # Ver sessão ativa\n```\n\n### Critérios de Qualidade\nA saída da descrição das atividades enviadas à flag `--activities` deve ser curta e objetiva. Abstê-se de logar dados sensíveis.\n\n---\n\n## 📂 Organização de Documentação (OBRIGATÓRIO)\n\nA documentação DEVE seguir esta estrutura de pastas. Não crie arquivos soltos na raiz de `docs/` (exceto BACKLOG.md).\n\n**Padrão oficial** (criado pelo `/define`):\n\n```bash\ndocs/\n├── 00-Contexto/        # Contexto do projeto e regras\n│   ├── CONTEXT.md      # Gerado por /context\n│   └── READINESS.md    # Gerado por /readiness\n├── 01-Planejamento/    # Artefatos executivos do /define\n│   ├── 01-product-brief.md\n│   ├── 02-prd.md\n│   ├── 03-design-system.md\n│   ├── 04-database-schema.md\n│   └── 05-roadmap-backlog.md\n├── 02-Requisitos/      # Detalhamento funcional\n│   ├── User-Stories.md\n│   └── Jornadas.md     # Gerado por /journeys\n├── 03-Arquitetura/     # Técnicos e Decisões\n│   ├── ADRs/           # Architecture Decision Records\n│   └── Diagramas/      # Mermaid/PlantUML (fluxos, classes)\n├── 04-API/            # Contratos de Interface\n│   └── Endpoints.md    # OpenAPI ou Docs REST\n├── 08-Logs-Sessoes/    # Logs de Sessão de Trabalho\n│   └── {ANO}/{DATA}.md # Logs diários\n└── BACKLOG.md          # Backlog Mestre (Raiz)\n```\n\n**Aliases aceitos** (fallback legado / projetos sem `/define`):\n\n| Oficial (padrão)     | Alias aceito          |\n|----------------------|-----------------------|\n| `docs/01-Planejamento/` | `docs/planning/`   |\n| `docs/00-Contexto/`     | `docs/context/`    |\n| `docs/02-Requisitos/`   | `docs/requirements/` |\n| `docs/03-Arquitetura/`  | `docs/architecture/` |\n| `docs/04-API/`          | `docs/api/`        |\n| `docs/08-Logs-Sessoes/` | `docs/logs/`       |\n\n> **Resolução:** Ao procurar documentos, tente primeiro o caminho oficial. Se não existir, tente o alias. Use `resolve_doc_path()` / `resolve_doc_file()` de `platform_compat.py` em scripts Python.\n\n**Regra:** Ao criar documentos, sempre verifique se a pasta existe. Se não existir, crie-a.\n\n---\n\n## Compatibilidade Multi-Plataforma\n\nEste framework suporta **três ferramentas AI simultaneamente**:\n\n| Ferramenta | Arquivo de Instrução | Skills Location | Config |\n|------------|---------------------|-----------------|--------|\n| Claude Code | `CLAUDE.md` | `.agents/skills/` | N/A |\n| Codex CLI | `AGENTS.md` | `.codex/skills/` (symlink) | `.agents/config/codex.toml` |\n| Antigravity/Gemini | `GEMINI.md` | `.agents/skills/` | N/A |\n\n### Symlinks Nativos\n\nCada plataforma acessa os mesmos recursos via caminhos nativos (symlinks para `.agents/`):\n\n| Plataforma | Agents | Skills | Workflows |\n|------------|--------|--------|-----------|\n| Claude Code | `.claude/agents/` | `.claude/skills/` | `.agents/workflows/` |\n| Codex CLI | `.codex/agents/` | `.codex/skills/` | `.codex/prompts/` |\n| Antigravity | `.agents/agents/` | `.agents/skills/` | `.agents/workflows/` |\n\n> **Fonte canônica:** `.agents/` — todos os symlinks apontam para lá.\n\n### Detecção Automática de Plataforma\n\nOs scripts Python detectam automaticamente qual ferramenta está executando:\n\n```python\nfrom platform_compat import get_agent_source\nsource = get_agent_source()  # 'claude_code', 'codex', ou 'unknown'\n```\n\n## Sistema Multi-Agent\n\nEste framework suporta múltiplos agentes AI trabalhando simultaneamente:\n\n### Identificação de Fonte\n```bash\n# Para Antigravity/Gemini\nexport AGENT_SOURCE=antigravity\n\n# Para Claude Code\nexport AGENT_SOURCE=claude_code\n\n# Para Codex CLI\nexport AGENT_SOURCE=codex\n```\n\n### Lock Manager\n```bash\npython3 .agents/scripts/lock_manager.py list      # Ver locks ativos\npython3 .agents/scripts/lock_manager.py cleanup   # Limpar locks expirados\n```\n\n### Ownership e Modelo Preferencial de Epics\n\nFormato no BACKLOG.md:\n```markdown\n## Epic 1: Nome [OWNER: claude_code] [MODEL: opus-4-5]\n```\n\n| Campo | Descrição | Valores |\n|-------|-----------|---------|\n| `OWNER` | Agente/ferramenta responsável | `claude_code`, `antigravity`, `codex` |\n| `MODEL` | Modelo AI preferencial | `opus-4-5`, `sonnet`, `haiku`, `gemini-2.0` |\n\n---\n\n## Scripts Úteis\n\n| Script | Comando | Descrição |\n|--------|---------|-----------|\n| Dashboard | `python3 .agents/scripts/dashboard.py` | Visão consolidada |\n| Progresso | `python3 .agents/scripts/progress_tracker.py` | Atualizar barra |\n| Sessão | `python3 .agents/scripts/auto_session.py start` | Iniciar sessão |\n| Finish | `python3 .agents/scripts/finish_task.py \"Epic-1\"` | Marcar completo |\n| Métricas | `python3 .agents/scripts/metrics.py` | Insights |\n| Validar | `python3 .agents/scripts/validate_installation.py` | Verificar setup |\n| Rastreabilidade | `python3 .agents/scripts/validate_traceability.py` | Validar cobertura |\n| Projeto | `python3 .agents/scripts/project_analyzer.py status` | Analisar tech stack |\n| Web Data | `python3 .agents/scripts/generate_web_data.py` | Gerar JSONs do site |\n| Checklist | `python3 .agents/scripts/checklist.py .` | Validação incremental |\n| Verificar Tudo | `python3 .agents/scripts/verify_all.py .` | Verificação completa |\n| Squad Manager | `python3 .agents/scripts/squad_manager.py list` | Gerenciar squads |\n| Recovery | `python3 .agents/scripts/recovery.py checkpoint <label>` | Retry + rollback |\n| Shard Epic | `python3 .agents/scripts/shard_epic.py shard` | Fatiar backlog em stories |\n\n---\n\n## Sistema de Squads\n\nSquads são pacotes reutilizáveis de agentes+skills+workflows para domínios específicos.\nSquads ficam em `squads/<nome>/` com manifesto `squad.yaml`. Detalhes em `squads/README.md`.\n\n| Comando | Descrição |\n|---------|-----------|\n| `/squad create <name>` | Criar novo squad |\n| `/squad list` | Listar squads |\n| `/squad activate <name>` | Ativar no framework |\n| `/squad deactivate <name>` | Desativar |\n\n---\n\n### Stitch MCP (Projetos com UI)\n\nPara TODOS os projetos com interface visual (HAS_UI=true):\n\n| Cenário | Comportamento |\n|---------|---------------|\n| Stitch MCP **disponível** + HAS_UI=true | **OBRIGATÓRIO** gerar protótipos via Stitch para **TODAS** as telas do sistema |\n| Stitch MCP **não disponível** + HAS_UI=true | **PARAR** e informar usuário para configurar Stitch antes de continuar |\n| HAS_UI=false | Fase 3.5 ignorada |\n\n**Regras de Cobertura Total:**\n- `/define` Fase 3.5: Prototipar **TODAS** as telas identificadas no UX Concept (não apenas 1 ou 2)\n- `/ui-ux-pro-max` Step 2c: Preview visual é OBRIGATÓRIO\n- `/readiness`: Valida existência de mockups E cobertura completa\n- **Gate de Bloqueio:** Fase 4 (Architecture) é BLOQUEADA até cobertura 100% das telas\n\nProjetos sem UI (API, CLI, backend-only): Stitch é ignorado.\n\n---\n\n### Recovery System\n\nScripts críticos usam retry automático e git checkpoint para operações seguras.\nMódulo: `.agents/scripts/recovery.py`\n\n---\n\n## Inicialização de Sessão\n\n> **PULO DO GATO (Context State):** Sempre que iniciar o trabalho com o usuário, **leia silenciosamente o arquivo `docs/PROJECT_STATUS.md`** (se existir). Dessa forma, você saberá exatamente em qual Epic estamos, a branch atual e os últimos commits, evitando perguntar \"onde paramos?\".\n\nToda conversa começa com:\n\n```\n✅ Project Instructions carregadas\n✅ Protocolo Inove AI Framework ativo\n✅ 22 agentes disponíveis\n✅ 42 skills disponíveis\n✅ 25 workflows disponíveis\n✅ Roteamento inteligente habilitado\n\n🎯 Pronto para trabalhar. O que devo fazer?\n```\n\n---\n\n## Referência Rápida de Agentes\n\n| Agente | Arquivo | Skills Primárias |\n|--------|---------|------------------|\n| `orchestrator` | `.agents/agents/orchestrator.md` | Coordenação multi-agente |\n| `project-planner` | `.agents/agents/project-planner.md` | Planejamento, discovery |\n| `product-manager` | `.agents/agents/product-manager.md` | Requisitos, user stories |\n| `frontend-specialist` | `.agents/agents/frontend-specialist.md` | React, UI/UX, Tailwind |\n| `backend-specialist` | `.agents/agents/backend-specialist.md` | APIs, Node.js, lógica |\n| `database-architect` | `.agents/agents/database-architect.md` | Schemas, Prisma, queries |\n| `mobile-developer` | `.agents/agents/mobile-developer.md` | iOS, Android, RN |\n| `security-auditor` | `.agents/agents/security-auditor.md` | Auth, OWASP, compliance |\n| `debugger` | `.agents/agents/debugger.md` | Root cause analysis |\n| `devops-engineer` | `.agents/agents/devops-engineer.md` | CI/CD, Docker, infra |\n| `test-engineer` | `.agents/agents/test-engineer.md` | Estratégias de teste |\n| `qa-automation-engineer` | `.agents/agents/qa-automation-engineer.md` | E2E, automação |\n| `documentation-writer` | `.agents/agents/documentation-writer.md` | Manuais, docs |\n| `code-archaeologist` | `.agents/agents/code-archaeologist.md` | Refatoração legacy |\n| `performance-optimizer` | `.agents/agents/performance-optimizer.md` | Otimizações |\n| `seo-specialist` | `.agents/agents/seo-specialist.md` | SEO, visibilidade |\n| `penetration-tester` | `.agents/agents/penetration-tester.md` | Security testing |\n| `game-developer` | `.agents/agents/game-developer.md` | Game logic |\n| `product-owner` | `.agents/agents/product-owner.md` | Requisitos, backlog, MVP |\n| `explorer-agent` | `.agents/agents/explorer-agent.md` | Análise de codebase |\n| `ux-researcher` | `.agents/agents/ux-researcher.md` | UX research, user flows, wireframes |\n\n---\n\n## Exemplo de Fluxo Completo\n\n**Usuário:** \"Implementar Epic 1: Autenticação de Usuários\"\n\n**Claude:**\n1. 🔍 Domínio detectado: Security + Backend\n2. 🤖 Ativando agentes:\n   - @security-auditor (líder)\n   - @backend-specialist (suporte)\n3. 📖 Carregando skills: vulnerability-scanner, api-patterns\n4. [Implementa código seguindo regras dos agentes]\n5. ✅ Implementação completa\n6. 🔧 Executando: `python3 .agents/scripts/finish_task.py \"Epic 1\"`\n7. 📊 Progresso: 25% (1/4 epics concluídos)\n\n**Usuário:** `/define App de gestão de tarefas`\n\n**Claude (ou Antigravity):**\n1. Fase 0: Discovery (12 perguntas estruturadas)\n2. Fase 1: Brief (`product-manager`)\n3. Fase 2: PRD + GAP Produto (`product-owner`)\n4. Fase 3: UX Concept + GAP UX (`ux-researcher`)\n5. Fase 4: Architecture + DB + GAP Infra (`project-planner`)\n6. Fase 5: Security + GAP Segurança (`security-auditor`)\n7. Fase 6: Stack + GAP Tech (`project-planner`)\n8. Fase 7: Design System + GAP Design (`frontend-specialist`)\n9. Fase 8: Backlog + GAPs consolidados (`product-owner`)\n10. Revisão: Claude Code/Codex valida com skill `doc-review`\n";
 //# sourceMappingURL=registry.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joelbonito/mcp-server",
-  "version": "5.1.6",
+  "version": "5.2.0",
   "description": "MCP server for Inove AI Framework — agents, skills, and workflows as MCP resources, tools and prompts",
   "license": "MIT",
   "author": "Inove AI <hello@inove.ai>",