maestro-bundle 1.0.0

package/templates/bundle-frontend-spa/AGENTS.md

@@ -0,0 +1,107 @@
+# Projeto: Frontend SPA (Single Page Application)
+
+Você está construindo uma aplicação frontend moderna com React, TypeScript e Tailwind CSS que consome APIs REST ou GraphQL.
+
+## Specification-Driven Development (SDD)
+
+Este projeto usa **GitHub Spec Kit** para governança. Antes de implementar qualquer demanda:
+
+1. Rodar `/speckit.constitution` — se `.spec/constitution.md` não existir
+2. Rodar `/speckit.specify` — descrever O QUE e POR QUÊ (não como)
+3. Rodar `/speckit.plan` — arquitetura e decisões técnicas
+4. Rodar `/speckit.tasks` — quebrar em tasks atômicas
+5. Rodar `/speckit.implement` — executar as tasks
+
+Nunca pular direto para código. Spec primeiro, código depois.
+
+## References
+
+Documentos de referência que o agente deve consultar quando necessário:
+
+- `references/react-component-patterns.md` — Padrões de componentes React
+- `references/tailwind-design-system.md` — Design system com Tailwind
+- `references/testing-library-guide.md` — Guia de testes com Testing Library
+
+## Stack do projeto
+
+- **Framework:** React 18+ com TypeScript (strict mode)
+- **Bundler:** Vite
+- **Estilização:** Tailwind CSS + Shadcn/UI
+- **Estado:** Zustand (global) + React Query (server state)
+- **Roteamento:** React Router v6+
+- **Forms:** React Hook Form + Zod
+- **HTTP:** Axios
+- **WebSocket:** Socket.io-client (se real-time)
+- **Testes:** Vitest + Testing Library + Playwright (E2E)
+
+## Estrutura do projeto
+
+```
+src/
+├── features/                   # Organizado por feature/domínio
+│   ├── demands/
+│   │   ├── components/         # Componentes da feature
+│   │   │   ├── DemandList.tsx
+│   │   │   ├── DemandCard.tsx
+│   │   │   └── DemandForm.tsx
+│   │   ├── hooks/              # Custom hooks
+│   │   │   └── useDemands.ts
+│   │   ├── services/           # Chamadas API
+│   │   │   └── demandApi.ts
+│   │   ├── types.ts            # Types da feature
+│   │   └── index.ts            # Barrel export
+│   ├── dashboard/
+│   └── auth/
+├── shared/                     # Compartilhado entre features
+│   ├── components/             # Button, Modal, Table, etc.
+│   ├── hooks/                  # useDebounce, useLocalStorage, etc.
+│   ├── lib/                    # api.ts (axios instance), utils
+│   └── types/                  # Types globais
+├── layouts/                    # AppLayout, AuthLayout
+├── routes/                     # Configuração de rotas
+├── config/                     # Constantes, env vars
+├── styles/                     # Globals CSS
+└── tests/
+    ├── e2e/                    # Playwright
+    └── setup.ts                # Vitest setup
+```
+
+## Padrões de código
+
+- Máximo 200 linhas por componente
+- Props tipadas com interface (não type)
+- Um componente = uma responsabilidade
+- Custom hooks para lógica reutilizável
+- Server state no React Query, UI state no Zustand
+- React Hook Form + Zod para formulários
+- Lazy loading por rota
+
+## Padrões de componentes
+
+- Composição > configuração (slots > props booleanas)
+- Container/Presenter para componentes complexos
+- Loading/Error/Empty states em todo componente async
+- Acessibilidade: semantic HTML, aria-labels, keyboard nav
+
+## Git
+
+- Commits: `feat(demands): adicionar filtro por status`
+- Branches: `feature/<feature>-<descricao>`
+- Nunca commitar node_modules, .env, dist/
+
+## Testes
+
+- Vitest + Testing Library: componentes e hooks
+- Playwright: fluxos E2E (login, CRUD, navegação)
+- Cobertura mínima: 70%
+- Testar comportamento, não implementação
+
+## O que NÃO fazer
+
+- Não usar `any` em TypeScript
+- Não fazer fetch dentro do componente (usar React Query)
+- Não duplicar dados da API no estado global
+- Não usar index como key em listas dinâmicas
+- Não criar mega-componentes de 500+ linhas
+- Não ignorar loading/error states
+- Não estilizar com CSS inline quando tem Tailwind

package/templates/bundle-frontend-spa/skills/authentication/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: authentication
+description: Implementar autenticação JWT com login, refresh token e proteção de rotas no frontend e backend. Use quando precisar implementar login, auth, JWT, ou proteção de endpoints.
+---
+
+# Authentication
+
+## Backend — JWT com FastAPI
+
+```python
+from fastapi import Depends, HTTPException, status
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from jose import jwt, JWTError
+from datetime import datetime, timedelta
+
+security = HTTPBearer()
+SECRET_KEY = os.environ["JWT_SECRET"]
+ALGORITHM = "HS256"
+ACCESS_TOKEN_EXPIRE = timedelta(hours=1)
+REFRESH_TOKEN_EXPIRE = timedelta(days=7)
+
+def create_access_token(user_id: str) -> str:
+    payload = {
+        "sub": user_id,
+        "exp": datetime.utcnow() + ACCESS_TOKEN_EXPIRE,
+        "type": "access"
+    }
+    return jwt.encode(payload, SECRET_KEY, algorithm=ALGORITHM)
+
+def create_refresh_token(user_id: str) -> str:
+    payload = {
+        "sub": user_id,
+        "exp": datetime.utcnow() + REFRESH_TOKEN_EXPIRE,
+        "type": "refresh"
+    }
+    return jwt.encode(payload, SECRET_KEY, algorithm=ALGORITHM)
+
+async def get_current_user(credentials: HTTPAuthorizationCredentials = Depends(security)) -> User:
+    try:
+        payload = jwt.decode(credentials.credentials, SECRET_KEY, algorithms=[ALGORITHM])
+        if payload.get("type") != "access":
+            raise HTTPException(status_code=401, detail="Invalid token type")
+        user = await user_repo.find_by_id(payload["sub"])
+        if not user:
+            raise HTTPException(status_code=401, detail="User not found")
+        return user
+    except JWTError:
+        raise HTTPException(status_code=401, detail="Invalid token")
+
+# Endpoint protegido
+@router.get("/me")
+async def get_me(user: User = Depends(get_current_user)):
+    return UserResponse.from_entity(user)
+```
+
+## Frontend — Auth Context
+
+```tsx
+interface AuthState {
+  token: string | null;
+  user: User | null;
+  login: (email: string, password: string) => Promise<void>;
+  logout: () => void;
+  isAuthenticated: boolean;
+}
+
+export const useAuthStore = create<AuthState>((set) => ({
+  token: localStorage.getItem('token'),
+  user: null,
+  isAuthenticated: !!localStorage.getItem('token'),
+
+  login: async (email, password) => {
+    const { access_token, user } = await authApi.login(email, password);
+    localStorage.setItem('token', access_token);
+    set({ token: access_token, user, isAuthenticated: true });
+  },
+
+  logout: () => {
+    localStorage.removeItem('token');
+    set({ token: null, user: null, isAuthenticated: false });
+  },
+}));
+
+// Axios interceptor
+api.interceptors.request.use((config) => {
+  const token = localStorage.getItem('token');
+  if (token) config.headers.Authorization = `Bearer ${token}`;
+  return config;
+});
+```

package/templates/bundle-frontend-spa/skills/component-design/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: component-design
+description: Criar componentes UI reutilizáveis com Tailwind + Shadcn/UI seguindo design system. Use quando for criar componentes de interface, botões, cards, modais, tabelas, ou elementos de UI.
+---
+
+# Component Design
+
+## Princípios
+
+1. **Um componente = uma responsabilidade**
+2. **Props tipadas** com interface TypeScript
+3. **Composição** sobre configuração (slots > props booleanas)
+4. **Acessibilidade** built-in (aria-labels, keyboard nav)
+
+## Componente Base — Template
+
+```tsx
+interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: 'primary' | 'secondary' | 'danger';
+  size?: 'sm' | 'md' | 'lg';
+  loading?: boolean;
+  children: React.ReactNode;
+}
+
+export function Button({
+  variant = 'primary',
+  size = 'md',
+  loading = false,
+  children,
+  disabled,
+  ...props
+}: ButtonProps) {
+  return (
+    <button
+      className={cn(
+        'rounded font-medium transition-colors',
+        variants[variant],
+        sizes[size],
+        (disabled || loading) && 'opacity-50 cursor-not-allowed'
+      )}
+      disabled={disabled || loading}
+      {...props}
+    >
+      {loading ? <Spinner size={size} /> : children}
+    </button>
+  );
+}
+```
+
+## Status Badge — Para tasks e demandas
+
+```tsx
+const statusConfig = {
+  pending: { label: 'Pendente', className: 'bg-gray-100 text-gray-700' },
+  in_progress: { label: 'Em andamento', className: 'bg-blue-100 text-blue-700' },
+  completed: { label: 'Concluído', className: 'bg-green-100 text-green-700' },
+  failed: { label: 'Falhou', className: 'bg-red-100 text-red-700' },
+} as const;
+
+export function StatusBadge({ status }: { status: keyof typeof statusConfig }) {
+  const config = statusConfig[status];
+  return (
+    <span className={cn('px-2 py-1 rounded-full text-xs font-medium', config.className)}>
+      {config.label}
+    </span>
+  );
+}
+```
+
+## Data Table — Com paginação
+
+```tsx
+interface DataTableProps<T> {
+  data: T[];
+  columns: ColumnDef<T>[];
+  pagination: { page: number; size: number; total: number };
+  onPageChange: (page: number) => void;
+}
+
+export function DataTable<T>({ data, columns, pagination, onPageChange }: DataTableProps<T>) {
+  const table = useReactTable({
+    data,
+    columns,
+    getCoreRowModel: getCoreRowModel(),
+  });
+
+  return (
+    <div>
+      <Table>
+        <TableHeader>{/* ... */}</TableHeader>
+        <TableBody>{/* ... */}</TableBody>
+      </Table>
+      <Pagination
+        page={pagination.page}
+        total={pagination.total}
+        size={pagination.size}
+        onChange={onPageChange}
+      />
+    </div>
+  );
+}
+```
+
+## Loading States
+
+Sempre mostrar skeleton enquanto carrega, error state quando falha:
+
+```tsx
+function AsyncContent<T>({ query, children }: { query: UseQueryResult<T>, children: (data: T) => ReactNode }) {
+  if (query.isLoading) return <Skeleton />;
+  if (query.error) return <ErrorState message={query.error.message} />;
+  if (!query.data) return <EmptyState />;
+  return <>{children(query.data)}</>;
+}
+```

package/templates/bundle-frontend-spa/skills/e2e-testing/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: e2e-testing
+description: Criar testes end-to-end com Playwright para fluxos completos da aplicação web. Use quando precisar testar fluxos de usuário, validar integração frontend-backend, ou automatizar testes de interface.
+---
+
+# E2E Testing com Playwright
+
+## Setup
+
+```python
+# tests/e2e/conftest.py
+import pytest
+from playwright.sync_api import sync_playwright
+
+@pytest.fixture(scope="session")
+def browser():
+    with sync_playwright() as p:
+        browser = p.chromium.launch(headless=True)
+        yield browser
+        browser.close()
+
+@pytest.fixture
+def page(browser):
+    context = browser.new_context()
+    page = context.new_page()
+    yield page
+    context.close()
+
+@pytest.fixture
+def authenticated_page(page):
+    page.goto("http://localhost:3000/login")
+    page.fill('[name="email"]', "admin@maestro.local")
+    page.fill('[name="password"]', "admin123")
+    page.click('button[type="submit"]')
+    page.wait_for_url("**/dashboard")
+    return page
+```
+
+## Testes de fluxo
+
+```python
+class TestCreateDemandFlow:
+    def test_should_create_demand_from_dashboard(self, authenticated_page):
+        page = authenticated_page
+
+        # Navegar para demands
+        page.click('a[href="/demands"]')
+        page.wait_for_selector('h1:has-text("Demandas")')
+
+        # Clicar em "Nova"
+        page.click('button:has-text("Nova")')
+        page.wait_for_selector('dialog')
+
+        # Preencher formulário
+        page.fill('[name="title"]', "Criar CRUD de usuários")
+        page.fill('[name="description"]', "Implementar CRUD completo com API e frontend")
+        page.select_option('[name="priority"]', "high")
+
+        # Submeter
+        page.click('button:has-text("Criar")')
+
+        # Verificar criação
+        page.wait_for_selector('text=Demanda criada')
+        assert page.locator('text=Criar CRUD de usuários').is_visible()
+
+    def test_should_show_agent_activity_in_realtime(self, authenticated_page):
+        page = authenticated_page
+        page.goto("http://localhost:3000/dashboard")
+
+        # Verificar feed de atividades
+        feed = page.locator('[data-testid="activity-feed"]')
+        assert feed.is_visible()
+
+        # Verificar métricas
+        assert page.locator('[data-testid="metric-active-agents"]').is_visible()
+        assert page.locator('[data-testid="metric-compliance-rate"]').is_visible()
+```
+
+## Page Objects (para testes complexos)
+
+```python
+class DemandPage:
+    def __init__(self, page):
+        self.page = page
+
+    def navigate(self):
+        self.page.goto("http://localhost:3000/demands")
+        self.page.wait_for_selector('h1:has-text("Demandas")')
+
+    def create(self, title: str, description: str, priority: str = "medium"):
+        self.page.click('button:has-text("Nova")')
+        self.page.fill('[name="title"]', title)
+        self.page.fill('[name="description"]', description)
+        self.page.select_option('[name="priority"]', priority)
+        self.page.click('button:has-text("Criar")')
+        self.page.wait_for_selector('text=Demanda criada')
+
+    def search(self, query: str):
+        self.page.fill('[data-testid="search"]', query)
+        self.page.press('[data-testid="search"]', 'Enter')
+```

package/templates/bundle-frontend-spa/skills/integration-api/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: integration-api
+description: Integrar frontend React com backend API usando React Query, Axios e WebSocket. Use quando precisar conectar frontend com backend, consumir APIs, ou implementar real-time.
+---
+
+# Integração Frontend ↔ Backend
+
+## HTTP Client (Axios)
+
+```typescript
+// shared/lib/api.ts
+import axios from 'axios';
+
+export const api = axios.create({
+  baseURL: import.meta.env.VITE_API_URL || 'http://localhost:8000/api/v1',
+  timeout: 10000,
+});
+
+api.interceptors.response.use(
+  (response) => response.data,
+  (error) => {
+    if (error.response?.status === 401) {
+      useAuthStore.getState().logout();
+      window.location.href = '/login';
+    }
+    return Promise.reject(error.response?.data || error);
+  }
+);
+```
+
+## Service Layer
+
+```typescript
+// features/demands/services/demandApi.ts
+export const demandApi = {
+  list: (params?: { page?: number; size?: number; status?: string }) =>
+    api.get<PaginatedResponse<Demand>>('/demands', { params }),
+
+  get: (id: string) =>
+    api.get<Demand>(`/demands/${id}`),
+
+  create: (data: CreateDemandDto) =>
+    api.post<Demand>('/demands', data),
+
+  update: (id: string, data: UpdateDemandDto) =>
+    api.put<Demand>(`/demands/${id}`, data),
+
+  delete: (id: string) =>
+    api.delete(`/demands/${id}`),
+};
+```
+
+## React Query Hooks
+
+```typescript
+export function useDemands(params?: DemandFilters) {
+  return useQuery({
+    queryKey: ['demands', params],
+    queryFn: () => demandApi.list(params),
+  });
+}
+
+export function useDemand(id: string) {
+  return useQuery({
+    queryKey: ['demands', id],
+    queryFn: () => demandApi.get(id),
+    enabled: !!id,
+  });
+}
+
+export function useCreateDemand() {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: demandApi.create,
+    onSuccess: () => qc.invalidateQueries({ queryKey: ['demands'] }),
+  });
+}
+```
+
+## WebSocket Real-time
+
+```typescript
+// shared/hooks/useWebSocket.ts
+import { io, Socket } from 'socket.io-client';
+
+let socket: Socket | null = null;
+
+export function useAgentEvents(onEvent: (event: TrackingEvent) => void) {
+  useEffect(() => {
+    socket = io(import.meta.env.VITE_WS_URL);
+    socket.on('tracking:event', onEvent);
+    return () => { socket?.disconnect(); };
+  }, [onEvent]);
+}
+```

package/templates/bundle-frontend-spa/skills/react-patterns/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: react-patterns
+description: Implementar padrões React com TypeScript incluindo hooks customizados, composição, render props e HOCs. Use quando for criar componentes React, estruturar features, ou resolver problemas de arquitetura frontend.
+---
+
+# React Patterns
+
+## 1. Custom Hooks — Extrair lógica reutilizável
+
+```tsx
+// hooks/useDemands.ts
+export function useDemands(filters?: DemandFilters) {
+  return useQuery({
+    queryKey: ['demands', filters],
+    queryFn: () => demandApi.list(filters),
+    staleTime: 30_000,
+  });
+}
+
+export function useCreateDemand() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: demandApi.create,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['demands'] });
+      toast.success('Demanda criada');
+    },
+    onError: (err) => toast.error(err.message),
+  });
+}
+```
+
+## 2. Composição > Herança
+
+```tsx
+// Compor componentes pequenos
+function DemandCard({ demand }: { demand: Demand }) {
+  return (
+    <Card>
+      <Card.Header>
+        <Card.Title>{demand.title}</Card.Title>
+        <StatusBadge status={demand.status} />
+      </Card.Header>
+      <Card.Content>
+        <AgentTeamList agents={demand.assignedAgents} />
+      </Card.Content>
+      <Card.Footer>
+        <TaskProgress tasks={demand.tasks} />
+      </Card.Footer>
+    </Card>
+  );
+}
+```
+
+## 3. Container/Presenter
+
+```tsx
+// Container — lógica e estado
+function DemandListContainer() {
+  const { data, isLoading, error } = useDemands();
+  const [selected, setSelected] = useState<string | null>(null);
+
+  if (isLoading) return <Skeleton />;
+  if (error) return <ErrorState message={error.message} />;
+
+  return <DemandList demands={data!} selected={selected} onSelect={setSelected} />;
+}
+
+// Presenter — apenas renderização
+function DemandList({ demands, selected, onSelect }: DemandListProps) {
+  return (
+    <div className="grid gap-4">
+      {demands.map(d => (
+        <DemandCard
+          key={d.id}
+          demand={d}
+          isSelected={d.id === selected}
+          onClick={() => onSelect(d.id)}
+        />
+      ))}
+    </div>
+  );
+}
+```
+
+## 4. Error Boundary
+
+```tsx
+function AppErrorBoundary({ children }: { children: React.ReactNode }) {
+  return (
+    <ErrorBoundary
+      fallback={({ error, resetErrorBoundary }) => (
+        <div className="p-8 text-center">
+          <h2>Algo deu errado</h2>
+          <p>{error.message}</p>
+          <Button onClick={resetErrorBoundary}>Tentar novamente</Button>
+        </div>
+      )}
+    >
+      {children}
+    </ErrorBoundary>
+  );
+}
+```
+
+## 5. Formulários com React Hook Form + Zod
+
+```tsx
+const demandSchema = z.object({
+  title: z.string().min(3, 'Mínimo 3 caracteres'),
+  description: z.string().min(10),
+  priority: z.enum(['low', 'medium', 'high']),
+});
+
+function CreateDemandForm() {
+  const { register, handleSubmit, formState: { errors } } = useForm({
+    resolver: zodResolver(demandSchema),
+  });
+  const createDemand = useCreateDemand();
+
+  return (
+    <form onSubmit={handleSubmit(data => createDemand.mutate(data))}>
+      <Input {...register('title')} error={errors.title?.message} />
+      <Textarea {...register('description')} error={errors.description?.message} />
+      <Select {...register('priority')} options={['low', 'medium', 'high']} />
+      <Button type="submit" loading={createDemand.isPending}>Criar</Button>
+    </form>
+  );
+}
+```

package/templates/bundle-frontend-spa/skills/responsive-layout/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: responsive-layout
+description: Criar layouts responsivos com Tailwind CSS incluindo sidebar, dashboard grid e mobile-first design. Use quando for criar layouts de página, dashboards, ou interfaces responsivas.
+---
+
+# Responsive Layout
+
+## Layout Principal do Maestro
+
+```tsx
+function AppLayout({ children }: { children: React.ReactNode }) {
+  const { sidebarOpen } = useAppStore();
+
+  return (
+    <div className="flex h-screen bg-gray-50">
+      <Sidebar open={sidebarOpen} />
+      <div className="flex-1 flex flex-col overflow-hidden">
+        <Header />
+        <main className="flex-1 overflow-y-auto p-4 md:p-6 lg:p-8">
+          {children}
+        </main>
+      </div>
+    </div>
+  );
+}
+```
+
+## Dashboard Grid
+
+```tsx
+function Dashboard() {
+  return (
+    <div className="space-y-6">
+      {/* Métricas top-level */}
+      <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4">
+        <MetricCard title="Demands Ativas" value={12} icon={<Activity />} />
+        <MetricCard title="Agentes Online" value={8} icon={<Bot />} />
+        <MetricCard title="Compliance Rate" value="94%" icon={<Shield />} />
+        <MetricCard title="Tasks Hoje" value={47} icon={<CheckCircle />} />
+      </div>
+
+      {/* Conteúdo principal */}
+      <div className="grid grid-cols-1 lg:grid-cols-3 gap-6">
+        <div className="lg:col-span-2">
+          <AgentActivityFeed />
+        </div>
+        <div>
+          <ActiveDemandsList />
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+## Breakpoints Tailwind
+
+| Prefix | Min-width | Uso |
+|---|---|---|
+| `sm:` | 640px | Mobile landscape |
+| `md:` | 768px | Tablet |
+| `lg:` | 1024px | Desktop |
+| `xl:` | 1280px | Desktop wide |
+
+Sempre **mobile-first**: escrever para mobile, depois adicionar breakpoints maiores.