# 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/<service>.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`
