# humand-frontend-sandbox Plugin de Claude Code para proyectos generados con [`humand-create-app`](https://github.com/HumandDev/humand-create-app). Diseñado para que usuarios non-técnicos (diseño, CX) puedan crear, explorar y validar mockups funcionales en React sin conocimientos del stack. Proporciona skills de onboarding, rules de comunicación y flujo de trabajo. --- ## Flujo de uso ``` /setup-sandbox → Prepara el entorno de la máquina (solo la primera vez) /bootstrap-react-project → Crea un proyecto nuevo → Abrir nueva conversación desde la carpeta del proyecto /start-project → Levanta el servidor de desarrollo local /plan-project → Genera el plan en Notion (objetivo, flujos, pantallas) /refine-feature → Descompone una pantalla en features antes de implementar /build-feature → Implementa una feature con checkpoint visual + commit /stop-project → Detiene el servidor de desarrollo /cleanup-sandbox → Desinstala lo que el setup instaló (opcional) ``` --- ## Rules | Archivo | Aplica a | Descripción | |---------|----------|-------------| | `rules/file-types/sandbox-preflight.md` | siempre | Pre-flight obligatorio: leer COMPONENTS.md, newTokens.ts y types.ts antes de planear o codear | | `rules/file-types/sandbox.md` | `src/**/*.{ts,tsx}` | Stack, estructura de carpetas, routing y nav | | `rules/file-types/sandbox-components.md` | `src/**/*.{ts,tsx}` | material-hu first, Form variants, snackbar obligatorio en mutations, layers, descubrimiento de componentes | | `rules/file-types/sandbox-styling.md` | `src/**/*.{ts,tsx}` | Tokens de color, verificación de paths, border radius | | `rules/workflows/api-debugging.md` | — | Protocolo curl-first al debuggear fallos de API — reproducir antes de tocar código | | `rules/workflows/build-feature.md` | — | Flujo técnico para construir una feature dentro de una screen | | `rules/workflows/non-tech-communication.md` | siempre | Sin jerga técnica, instrucciones explícitas, errores traducidos | | `rules/workflows/preflight-rules-check.md` | — | Lista de rules que el agente debe leer antes de generar archivos del proyecto | | `rules/workflows/sandbox-workflow.md` | siempre | Plan antes de código, checkpoints visuales, commits en español, continuidad de sesión | --- ## Skills ### Onboarding | Skill | Descripción | |-------|-------------| | `/setup-sandbox` | Detecta el OS y ejecuta `scripts/setup-env.sh` (Mac) o `scripts/setup-env.ps1` (Windows) para instalar nvm, Node 24.11.1, bun, git y gh. Luego configura el token de GitHub Packages con `scripts/setup-github-token.sh/.ps1`. Registra qué instaló en `~/.humand/sandbox-installed.json` | | `/cleanup-sandbox` | Desinstala solo lo que `/setup-sandbox` instaló, leyendo el registry. Nunca toca software preexistente | | `/bootstrap-react-project` | Pregunta nombre y opciones, ejecuta `bunx @humanddev/humand-create-app@latest` e indica al usuario cómo abrir el proyecto en una nueva conversación | ### Ideación y Planificación | Skill | Descripción | |-------|-------------| | `/plan-project` | Crea una página de Notion con el plan del proyecto (objetivo, flujos y lista de pantallas). El usuario la revisa y aprueba antes de que se escriba código. Ver estructura en `skills/plan-project/TEMPLATE.md` | | `/refine-feature` | Toma una pantalla del plan, la descompone en features implementables y detalla componentes, datos y criterios de validación. Usar entre `/plan-project` y `/build-feature` | ### Documentación de proyectos existentes | Skill | Descripción | |-------|-------------| | `/document-project` | Ingeniería inversa de un proyecto existente: escanea `src/`, detecta pantallas y features, entrevista al usuario para llenar huecos y crea la página de Notion + features database con estado `Documentado parcial`. Equivalente a `/plan-project` para proyectos ya escritos | | `/document-feature [name]` | Lee el código de una feature específica, infiere componentes, datos y criterios de validación, y actualiza la entrada en Notion. Soporta `--all` para procesar todas las features en `Documentado parcial` de corrido. Equivalente a `/refine-feature` para código existente | ### Construcción | Skill | Descripción | |-------|-------------| | `/build-feature` | Implementa una feature (ruta + nav + componente). Hace checkpoint visual con el usuario, commitea en español y actualiza Notion | | `/add-super-admin-login` | Agrega login Google SSO (OAuth2 PKCE vía Janus) al proyecto: AuthContext, LoginPage, CallbackPage, ProtectedRoute y botón de logout. Pide `VITE_JANUS_URL` y `VITE_CLIENT_ID` y los escribe en todos los `.env*` existentes. Se dispara cuando el usuario pide "login para un proyecto interno" o "login para super admin" | | `/connect-service` | Integra un servicio externo creando un proxy route en Vercel, un servicio tipado y hooks de react-query. Soporta dos patrones de proxy (fetch-based para REST, SDK-based cuando existe un SDK oficial Node). Los tipos generados viven en `src/types/.ts` — el frontend solo importa tipos, nunca el SDK. Las API keys nunca llegan al browser | | `/setup-supabase` | Crea un proyecto Supabase en la org de Humand, escribe `.env.local` + `.env.example`, genera tipos TypeScript, activa RLS por defecto, corre advisors con autofix automático y delega la creación del proxy a `/connect-service`. Modelo de seguridad: proxy-only (el FE no tiene ninguna key de Supabase). Se invoca manualmente cuando el proyecto necesita base de datos | --- ## Commands | Comando | Descripción | |---------|-------------| | `/tsc-check` | Corre `tsc --noEmit` y explica los errores en español | | `/lint-fix` | Corre `bun run biome:fix` sobre `src/` y confirma que no quedan errores | --- ## Scripts Los scripts viven junto a la skill que los usa y son invocados directamente por el agente — nunca se replican a mano. | Script | OS | Skill | Descripción | |--------|----|-------|-------------| | `setup-sandbox/scripts/setup-env.sh` | Mac | `/setup-sandbox` | Instala Homebrew, nvm, Node 24.11.1, bun, git y gh. Escribe `~/.humand/sandbox-installed.json` progresivamente | | `setup-sandbox/scripts/setup-env.ps1` | Windows | `/setup-sandbox` | Instala Node (vía nvm-windows) y bun automáticamente. Para git, gh y nvm-windows guía al usuario con instrucciones claras | | `setup-sandbox/scripts/setup-github-token.sh` | Mac | `/setup-sandbox` | Guarda el token en `~/.humand/github-token` y actualiza `~/.npmrc` con la entrada `@humanddev` sin pisar otras líneas | | `setup-sandbox/scripts/setup-github-token.ps1` | Windows | `/setup-sandbox` | Equivalente PowerShell del anterior | | `setup-supabase/scripts/scaffold.ts` | Cross-platform | `/setup-supabase` | Escribe `.env.local` + `.env.example`, crea `supabase/migrations/` e instala `@supabase/supabase-js`. Corrido con `bun`; recibe credenciales por flags y por env var (`SUPABASE_SERVICE_ROLE_KEY` nunca se pasa en prompts) | --- ## Stack cubierta - React 18 + TypeScript + Vite - material-hu (Hugo theme, DS components) - React Hook Form + Zod - React Router v6 - Axios + i18n (react-i18next) - Biome (`humand-biome-config`) --- ## Terminología | Término | Definición | |---------|------------| | **Módulo** | Agrupación de alto nivel (e.g. "Onboarding"). Contiene múltiples screens. Equivale a una sección del nav | | **Screen / Pantalla** | Vista completa dentro de un módulo (e.g. "List", "Create", "Edit"). Unidad de trabajo en `/plan-project` y `/refine-feature` | | **Feature** | Parte independiente de una screen que se puede validar visualmente por separado (e.g. "Empty state", "Drawer: nuevo item"). Unidad de trabajo en `/build-feature` | --- ## Decisiones pendientes - **Ubicación en Notion** de las páginas de proyecto — por definir con el equipo - **Estrategia de sharing** — Vercel deploy directo es la opción favorita (ver plan de implementación) - **GitHub App para repos privados** — Engineering debe crear una GitHub App con permisos de lectura sobre `material-hu` y `humand-biome-config`, generar un token y publicarlo en Notion. El token se guarda en `~/.humand/github-token` durante `/setup-sandbox`