claude-code-arcane 1.0.0

package/skills/android-native-dev/references/visual-design.md

@@ -0,0 +1,246 @@
+# Visual Design Guidelines
+
+Detailed specifications for colors, typography, spacing, elevation, and shapes in Material Design 3.
+
+## Color System
+
+### Color Roles (Tokens)
+
+Material Design 3 uses a token-based color system with three accent groups:
+
+| Role | Usage |
+|------|-------|
+| **Primary** | Key components, FAB, prominent buttons |
+| **Secondary** | Less prominent components, filters, chips |
+| **Tertiary** | Accent, complementary elements |
+| **Error** | Error states, destructive actions |
+| **Surface** | Backgrounds, cards, dialogs |
+
+Each role includes variants: base color, onColor, container, onContainer.
+
+### Color Contrast Requirements
+
+| Element | Minimum Contrast Ratio | Notes |
+|---------|----------------------|-------|
+| Body text | **4.5:1** | WCAG AA compliance |
+| Large text (18sp+) | **3:1** | 14sp bold also qualifies |
+| UI components | **3:1** | Icons, borders, controls |
+| Focus indicators | **3:1** | Must be clearly visible |
+
+### Recommended Color Palettes
+
+#### Modern Professional (Business Apps)
+
+| Role | Color | Name |
+|------|-------|------|
+| Primary | #1976D2 | Blue 700 |
+| Secondary | #455A64 | Blue Grey 700 |
+| Tertiary | #00897B | Teal 600 |
+| Background | #FAFAFA | Grey 50 |
+
+#### Vibrant & Playful (Consumer Apps)
+
+| Role | Color | Name |
+|------|-------|------|
+| Primary | #6200EE | Deep Purple |
+| Secondary | #03DAC6 | Teal Accent |
+| Tertiary | #FF5722 | Deep Orange |
+| Background | #FFFFFF | White |
+
+#### Dark & Elegant (Premium Apps)
+
+| Role | Color | Name |
+|------|-------|------|
+| Primary | #BB86FC | Purple 200 |
+| Secondary | #03DAC6 | Teal 200 |
+| Tertiary | #CF6679 | Red 200 |
+| Background | #121212 | Dark surface |
+
+#### Nature & Wellness (Health Apps)
+
+| Role | Color | Name |
+|------|-------|------|
+| Primary | #4CAF50 | Green 500 |
+| Secondary | #8BC34A | Light Green 500 |
+| Tertiary | #FFEB3B | Yellow 500 |
+| Background | #F1F8E9 | Light Green 50 |
+
+#### Finance & Trust (Banking Apps)
+
+| Role | Color | Name |
+|------|-------|------|
+| Primary | #00695C | Teal 800 |
+| Secondary | #37474F | Blue Grey 800 |
+| Tertiary | #FFC107 | Amber 500 |
+| Background | #ECEFF1 | Blue Grey 50 |
+
+### Dark Theme Requirements
+
+- Background: #121212 or darker
+- Surface colors use elevation-based tonal overlay
+- Primary colors should be lighter variants (200-300 range)
+- Maintain contrast ratios in dark mode
+- Test all states (hover, focus, pressed) in dark mode
+
+## Typography System
+
+### Type Scale
+
+| Style | Size | Weight | Line Height | Usage |
+|-------|------|--------|-------------|-------|
+| Display Large | 57sp | 400 | 64sp | Hero text |
+| Display Medium | 45sp | 400 | 52sp | Large headers |
+| Display Small | 36sp | 400 | 44sp | Section headers |
+| Headline Large | 32sp | 400 | 40sp | Screen titles |
+| Headline Medium | 28sp | 400 | 36sp | Subsection titles |
+| Headline Small | 24sp | 400 | 32sp | Card titles |
+| Title Large | 22sp | 400 | 28sp | App bar titles |
+| Title Medium | 16sp | 500 | 24sp | List item titles |
+| Title Small | 14sp | 500 | 20sp | Tabs |
+| Body Large | 16sp | 400 | 24sp | Primary body text |
+| Body Medium | 14sp | 400 | 20sp | Secondary body text |
+| Body Small | 12sp | 400 | 16sp | Captions |
+| Label Large | 14sp | 500 | 20sp | Button text |
+| Label Medium | 12sp | 500 | 16sp | Navigation labels |
+| Label Small | 11sp | 500 | 16sp | Badges |
+
+### Recommended Fonts
+
+| Category | Fonts |
+|----------|-------|
+| Primary | Roboto (system default) |
+| Display | Roboto Serif, Google Sans |
+| Monospace | Roboto Mono, JetBrains Mono |
+
+### Text Readability
+
+- **Line length**: 45-75 characters per line (including spaces)
+- **Paragraph spacing**: 1.5x line height between paragraphs
+- **Letter spacing**: Use default unless brand requires adjustment
+- **Text alignment**: Left-aligned for body text (LTR languages)
+
+## Spacing & Layout
+
+### 8dp Grid System
+
+All spacing values should be multiples of 8dp (with 4dp for fine adjustments).
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| xs | 4dp | Icon padding, fine adjustments |
+| sm | 8dp | Tight spacing, inline elements |
+| md | 16dp | Default padding, card content |
+| lg | 24dp | Section spacing |
+| xl | 32dp | Large gaps, group separation |
+| xxl | 48dp | Screen margins, major sections |
+
+### Component Dimensions
+
+| Component | Height | Min Width | Notes |
+|-----------|--------|-----------|-------|
+| Button | 40dp | 64dp | Touch target 48dp |
+| FAB | 56dp | 56dp | Standard size |
+| Mini FAB | 40dp | 40dp | Secondary actions |
+| Extended FAB | 56dp | 80dp | With text label |
+| Text Field | 56dp | 280dp | Including label |
+| App Bar | 64dp | - | Top app bar |
+| Bottom Nav | 80dp | - | With labels |
+| Nav Rail | - | 80dp | Tablet/desktop |
+| List Item | 56-88dp | - | Depends on content |
+| Chip | 32dp | - | Filter/action chips |
+
+### Touch Targets
+
+| Type | Size | Notes |
+|------|------|-------|
+| Minimum | 48 × 48dp | WCAG requirement |
+| Recommended | 56 × 56dp | Primary actions |
+| Kids apps | 56dp+ | Larger for motor skills |
+| Spacing | 8dp minimum | Between adjacent targets |
+
+## Elevation & Shadows
+
+### Elevation Levels
+
+| Level | Elevation | Usage |
+|-------|-----------|-------|
+| Level 0 | 0dp | Flat surfaces |
+| Level 1 | 1dp | Cards, elevated buttons |
+| Level 2 | 3dp | FAB (resting), raised elements |
+| Level 3 | 6dp | Navigation drawer, bottom sheet |
+| Level 4 | 8dp | FAB (pressed), menus |
+| Level 5 | 12dp | Dialogs, modal surfaces |
+
+### Shadow Guidelines
+
+- Use elevation consistently for same component types
+- Higher elevation = more important/prominent
+- In dark theme, use surface tint instead of shadows
+- Avoid excessive elevation (keeps UI grounded)
+
+## Shape System
+
+### Corner Radius
+
+| Size | Radius | Usage |
+|------|--------|-------|
+| None | 0dp | Sharp edges, dividers |
+| Extra Small | 4dp | Badges, small chips |
+| Small | 8dp | Buttons, chips, small cards |
+| Medium | 12dp | Cards, dialogs, text fields |
+| Large | 16dp | FAB, bottom sheets |
+| Extra Large | 28dp | Large sheets, expanded cards |
+| Full | 50% | Pills, avatars, circular buttons |
+
+### M3 Expressive Shapes
+
+Material 3 Expressive introduces 35 new decorative shapes:
+- Organic curves
+- Asymmetric corners
+- Cut corners
+- Scalloped edges
+
+Use sparingly for brand differentiation and visual interest.
+
+### Shape Consistency Rules
+
+- Same component type = same shape
+- Related components should share shape family
+- Don't mix too many shape styles on one screen
+- Consider shape in dark/light theme transitions
+
+## Icons
+
+### Size Specifications
+
+| Size | Dimensions | Usage |
+|------|------------|-------|
+| Small | 20 × 20dp | Compact UI, inline |
+| Standard | 24 × 24dp | Default for most uses |
+| Large | 40 × 40dp | Emphasis, empty states |
+
+### Icon Guidelines
+
+- **Touch target**: Always wrap in 48dp minimum clickable area
+- **Style**: Outlined (default), Filled (selected/active states)
+- **Stroke width**: 2dp for outlined icons
+- **Optical alignment**: May need visual adjustments
+- **Color**: Use semantic colors (primary, error, etc.)
+
+### Recommended Icon Sets
+
+| Set | Usage |
+|-----|-------|
+| Material Symbols | Recommended, variable font support |
+| Material Icons | Legacy, still widely used |
+
+### Adaptive Icons (App Icon)
+
+| Property | Value |
+|----------|-------|
+| Canvas size | 108 × 108dp |
+| Safe zone | 66 × 66dp (centered circle) |
+| Logo size | 48-66dp |
+| Max display | 72 × 72dp |
+| Layers | Foreground + Background (both 108dp) |
+| Android 13+ | Include monochrome layer for theming |

package/skills/api-design/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: api-design
+description: "API design: REST conventions, OpenAPI, versioning, pagination, error format, GraphQL, webhooks."
+category: "api"
+argument-hint: "[rest|graphql|versioning|docs] [resource-name]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
+---
+# api-design — REST, GraphQL, Versioning & Docs
+
+## MANDATORY WORKFLOW
+
+**Antes de recomendar o generar cualquier diseño, completar estos pasos en orden.**
+
+### Step 0: Gather Requirements
+
+Clarificar (o inferir del contexto si ya fue especificado):
+
+1. **¿API nueva o extensión?** (si es extensión, leer la existente primero)
+2. **Tipos de clientes:** SPA / mobile / third-party / server-to-server
+3. **¿Over-fetch o deeply nested relations?** → influye en REST vs GraphQL
+4. **Auth:** JWT / API Key / OAuth / ninguna
+5. **¿Versioning desde día 1?** ¿Hay clientes externos que no podemos romper?
+
+Si el usuario ya especificó estos valores, saltar directamente al Step 1.
+
+### Step 1: Recomendar approach
+
+Usar la tabla API Style Decision más abajo para elegir REST / GraphQL / gRPC.
+Explicar la elección en 1 oración.
+
+### Step 2: Diseñar + Verificar
+
+Implementar el diseño. Al terminar, validar contra el Checklist al final de este documento.
+
+---
+
+## API Style Decision
+
+| Style | Use when |
+|-------|----------|
+| **REST** | Default. CRUD-dominant, cacheable, broad client support |
+| **GraphQL** | Multiple clients with very different shapes, deep nested relations, significant over-fetch |
+| **gRPC** | Internal service-to-service, streaming, strict contracts, performance-critical |
+
+## REST Conventions
+
+- **URLs:** plural nouns, kebab-case, nesting max 2 levels, no verbs. Pattern: `/api/v1/resources/{id}/sub-resources`
+- **Verbs:** GET (read), POST (create, use Idempotency-Key if critical), PUT (full replace), PATCH (partial), DELETE
+- **Pagination:** cursor keyset over offset (offset drifts with concurrent writes, re-scans rows)
+- **Response wrapper:** `{ "data": [...], "pagination": { "cursor": "...", "hasMore": true } }`
+- **Filtering/sorting:** `?filter[status]=active&sort=-createdAt&fields=id,name`
+- **Dates:** ISO 8601 UTC. **IDs:** opaque (never auto-increment — reveals volume)
+- **Rate limiting headers:** X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After
+
+## Error Format — RFC 9457 Problem Details
+
+Fields: `type` (URI), `title`, `status`, `detail`, `traceId` (log correlation).
+Never invent a custom format. Never expose stack traces in production.
+
+## Schema-first Approach
+
+1. **Recommended:** OpenAPI spec first, generate types + client code
+2. **Alternative (Fastify):** Code-first with Zod, auto-generate OpenAPI via @fastify/swagger
+3. **Monorepo:** Share schemas in `packages/api-types` between backend and frontend
+4. **Tooling:** Lint (Spectral), mock (Prism), docs (Redocly/Scalar)
+
+## Versioning
+
+- **Default:** URL path (`/v1/`) — simple, cacheable, grep-friendly
+- **Non-breaking** (no bump): add optional field, new endpoint, new enum value
+- **Breaking** (requires bump): remove/rename field, change type, change status codes
+
+> → Read references/versioning-deprecation.md for deprecation flow, support windows, and webhook outbound details
+
+## Anti-patterns
+
+> → Read references/anti-patterns.md for 10 common API design anti-patterns with corrections
+
+## Checklist
+- [ ] URLs plural, no verbs, nesting max 2
+- [ ] Correct status codes, RFC 9457 errors with traceId
+- [ ] Cursor pagination with `{ data, pagination }` wrapper
+- [ ] OpenAPI spec up-to-date and linted, generated types in client
+- [ ] Breaking changes trigger version bump
+- [ ] Deprecation headers + usage monitoring on old endpoints
+- [ ] Rate limit headers, auth documented per endpoint
+- [ ] Webhooks signed with HMAC

package/skills/api-design/references/anti-patterns.md

@@ -0,0 +1,14 @@
+# Anti-patterns - API Design
+
+| # | No hacer | Hacer en cambio |
+|---|----------|-----------------|
+| 1 | Verbos en URLs (`/getUser`, `/createOrder`) | Sustantivos plurales: `GET /users`, `POST /orders` |
+| 2 | Status 200 con cuerpo de error | Codigo HTTP correcto (400/401/404/500) + RFC 9457 body |
+| 3 | Formato de error custom inventado | RFC 9457 Problem Details con `type`, `title`, `status`, `traceId` |
+| 4 | OFFSET pagination en tablas grandes | Cursor keyset con `{ data, pagination: { cursor, hasMore } }` |
+| 5 | Breaking change sin version bump | Bump a `/v2/`; mantener `/v1/` con Deprecation + Sunset headers |
+| 6 | 3+ versiones vivas en paralelo | Max 2 versiones; sunset activo sobre la mas vieja |
+| 7 | Stack traces en responses de produccion | Log interno con traceId; response solo incluye `traceId` |
+| 8 | GraphQL sin limites de profundidad/complejidad | depth limit + query complexity scoring obligatorio |
+| 9 | Webhooks sin firma HMAC | `X-Signature: sha256=<hmac>` + reject si delta timestamp >5min |
+| 10 | OpenAPI mantenido a mano (drift con codigo) | Code-first (Zod+swagger) o spec-first con Spectral lint en CI |

package/skills/api-design/references/versioning-deprecation.md

@@ -0,0 +1,23 @@
+# Versioning & Deprecation - API Design
+
+## Versioning
+
+- **Default:** URL path (`/v1/`) — simple, cacheable, grep-friendly
+- **Non-breaking** (no bump): add optional field, new endpoint, new enum value, relax validation
+- **Breaking** (requires bump): remove/rename field, change type, change status codes, tighten validation, change date/ID/pagination format
+
+## Deprecation Flow
+
+1. Announce via changelog + docs
+2. Response headers: `Deprecation: true`, `Sunset: <date>`, `Link: <migration-guide>`
+3. Monitor usage by client_id. Reminders at 1 month and 1 week before sunset
+4. Return `410 Gone` after sunset
+
+**Support windows:** Web 6 months min, Mobile 12 months + min-version forcing, max 2 major versions alive.
+
+## Webhooks Outbound
+
+- HMAC signature: `X-Signature: sha256=<hmac(payload, secret)>`
+- Timestamp anti-replay: reject if delta > 5 min
+- Retry exponential backoff: 1m, 5m, 30m, 2h, 12h
+- Minimal payload + URL for detail fetch; dashboard for failed deliveries

package/skills/api-docs/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: api-docs
+description: "Generate or update API docs from source code. Scans endpoints, extracts methods, routes, params, responses. Trigger: API docs, swagger."
+category: "api"
+argument-hint: "[path to scan, default .]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit
+---
+# API Documentation Generator
+
+Escanea el código fuente para generar documentación de API.
+
+## Process
+
+### 1. Detectar framework y rutas
+
+| Framework | Dónde buscar rutas |
+|-----------|-------------------|
+| Gin (Go) | `engine.GET/POST/PUT/DELETE`, `Group()` |
+| Echo (Go) | `e.GET/POST/PUT/DELETE`, `Group()` |
+| Express (Node) | `router.get/post/put/delete`, `app.use()` |
+| Fastify (Node) | `fastify.get/post`, route schemas |
+| FastAPI (Python) | `@app.get/post`, Pydantic models |
+| Django REST | `urlpatterns`, ViewSets |
+| NestJS | `@Get/@Post` decorators, DTOs |
+
+### 2. Para cada endpoint extraer
+
+- **Método HTTP** (GET, POST, PUT, DELETE, PATCH)
+- **Ruta** con params (`:id`, `{id}`)
+- **Middleware/Guards** (auth, roles requeridos)
+- **Request body** (struct/DTO/schema)
+- **Query params**
+- **Response** (struct de respuesta, status codes)
+- **Descripción** (del comentario o nombre del handler)
+
+### 3. Generar documentación
+
+```markdown
+# API Documentation — [Proyecto]
+**Base URL:** `[detectado de config o .env]`
+**Auth:** [Bearer JWT / API Key / etc.]
+**Última actualización:** [fecha]
+
+---
+
+## [Módulo/Grupo]
+
+### [METHOD] /api/v1/path/:param
+
+**Descripción:** [qué hace]
+**Auth:** [requerido/público] | **Roles:** [admin, coordinator]
+
+**Path params:**
+| Param | Tipo | Descripción |
+|-------|------|-------------|
+
+**Query params:**
+| Param | Tipo | Required | Default | Descripción |
+|-------|------|----------|---------|-------------|
+
+**Request body:**
+```json
+{
+  "field": "type — descripción"
+}
+```
+
+**Responses:**
+| Status | Descripción | Body |
+|--------|-------------|------|
+| 200 | Éxito | `{ ... }` |
+| 400 | Validación | `{ "error": "..." }` |
+| 401 | No autenticado | |
+| 404 | No encontrado | |
+
+---
+```
+
+### 4. Tabla resumen
+
+```markdown
+## Resumen de endpoints
+
+| Método | Ruta | Auth | Roles | Descripción |
+|--------|------|------|-------|-------------|
+| GET | /api/v1/users | Si | admin | Listar usuarios |
+| POST | /api/v1/users | Si | admin | Crear usuario |
+```
+
+### 5. Output
+
+- Mostrar en pantalla
+- Guardar en `docs/API.md` si el usuario lo pide
+
+## Rules
+- Seguir la estructura real del código, no inventar endpoints
+- Si hay OpenAPI/Swagger existente → leerlo y actualizarlo en vez de crear uno nuevo
+- Agrupar endpoints por módulo/recurso
+- En español para descripciones
+- Incluir ejemplos de request/response cuando sea posible inferirlos del código

package/skills/api-versioning/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: api-versioning
+description: "API versioning: breaking/non-breaking changes, deprecation headers, sunset, v2 introduction. Go/Gin, NestJS, Fastify, GraphQL."
+category: "api"
+argument-hint: "[deprecate v1|introduce v2|audit]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit, Task
+---
+# API Versioning
+
+Guía para versionar APIs en backends Educabot (Go + TS) consumidas por web (React+Vite) y mobile (React Native).
+
+## Estrategias
+
+| Estrategia | Ejemplo | Veredicto |
+|---|---|---|
+| **URL path** | `/v1/users` | **Default Educabot** — visible, cacheable, fácil |
+| Header | `API-Version: 2026-01-15` | Complemento opcional (date-based pinning) |
+| Query param | `/users?version=2` | Evitar — ensucia URLs, problemas caché |
+| Content negotiation | `Accept: vnd.educabot.v2+json` | Evitar — over-engineering |
+
+Solo MAJOR cambia URL (`/v1` → `/v2`). MINOR/PATCH transparentes.
+
+## Breaking vs Non-breaking
+
+**Non-breaking** (no requiere v2): agregar campo opcional request/response, nuevo endpoint, nuevo enum value (si clientes toleran desconocidos), relajar validaciones, required → opcional.
+
+**Breaking** (requiere v2): remover campo response, cambiar tipo, renombrar campo/endpoint, cambiar status codes, opcional → required, cambiar formato fechas/IDs/paginación, cambiar semántica, endurecer validaciones.
+
+## Deprecation Flow
+
+1. **Anunciar** — changelog, email, ticket de migración
+2. **Headers en runtime** — `Deprecation: true` + `Sunset: <date>` + `Link: <migration-docs>` + `Warning: 299`
+3. **Monitorear uso** — log hits con user-agent/client_id, dashboard quién usa v1
+4. **Recordatorios** — 1 mes y 1 semana antes del sunset
+5. **Apagar** — `410 Gone` con body apuntando a docs
+
+## Ventanas de Soporte
+
+| Contexto | Ventana |
+|----------|---------|
+| Web (React) | 6 meses |
+| Mobile (RN) | 12 meses + minimum-version forcing |
+| API externa | 12+ meses |
+| Backend interno | Semanas (coordinando deploys) |
+
+Max 2 majors vivas en paralelo. Nunca 3+.
+
+> → Read references/implementation-by-framework.md for implementation patterns per framework (Go, NestJS, Fastify, OpenAPI, GraphQL, Mobile)
+
+> → Read references/anti-patterns-and-checklist.md for anti-patterns list and v2 introduction checklist

package/skills/api-versioning/references/anti-patterns-and-checklist.md

@@ -0,0 +1,27 @@
+# API Versioning — Anti-patterns & Checklist
+
+## Anti-patterns
+
+- Breaking change sin nueva versión
+- Mantener v1/v2/v3/v4 vivas (backport hell) — max 2
+- Versión en body JSON (rompe routing/caché)
+- Sin headers Deprecation/Sunset
+- Versionar internals (auth, healthchecks, webhooks salientes)
+- Bumpear major por non-breaking (inflación)
+- No monitorear uso de v1 -> apagás a ciegas
+- Docs única para todas las versiones
+- Changelog inexistente
+
+## Checklist (introducir v2)
+
+- [ ] Confirmar que es realmente breaking (sección 3)
+- [ ] Se resuelve con campo opcional o endpoint nuevo en v1?
+- [ ] `/v2/` paralelo, reusar dominio/service, duplicar handlers+DTOs
+- [ ] OpenAPI spec separado para v2
+- [ ] Sunset de v1 definido (min 6m, 12m si mobile)
+- [ ] Headers Deprecation+Sunset+Link en v1
+- [ ] Logging hits a v1 + dashboard uso v1 vs v2
+- [ ] Guía de migración publicada antes del anuncio
+- [ ] Contract tests de v1 pasan hasta sunset
+- [ ] Mobile: subir min en /minimum-version antes del sunset
+- [ ] Plan de rollback si v2 explota

package/skills/api-versioning/references/implementation-by-framework.md

@@ -0,0 +1,31 @@
+# API Versioning — Implementation by Framework
+
+## Patrón clave
+
+Dominio sin versión, controllers/DTOs por versión. Handler convierte DTO <-> entidad de dominio. La versión nunca filtra al dominio.
+
+## Go (Gin)
+
+Route groups `/v1`, `/v2` + middleware `DeprecationHeaders()`.
+
+Carpetas: `handlers/v1/`, `handlers/v2/`, `dto/v1/`, `dto/v2/`, `domain/` y `service/` shared.
+
+## NestJS
+
+`enableVersioning({ type: VersioningType.URI })`. Controllers separados `@Controller({ version: '1' })` / `@Controller({ version: '2' })`.
+
+## Fastify
+
+Plugins por versión registrados con `prefix: '/v1'`, `prefix: '/v2'`.
+
+## OpenAPI
+
+Spec separado por major (`openapi-v1.yaml`). Schemas versionados. `deprecated: true` en endpoints.
+
+## GraphQL — NO se versiona
+
+Evoluciona aditivamente: campos nuevos ignorados por clientes viejos. `@deprecated(reason: "Use X. Removed YYYY-MM-DD")`. Monitorear uso de campos deprecados con tracing.
+
+## Mobile (React Native)
+
+Endpoint `/minimum-version` -> `{ "ios": { "min": "2.3.0", "recommended": "2.5.0" } }`. App al iniciar: < min -> bloqueo "actualizá"; < recommended -> banner soft.