argos-harness 0.1.0

package/assets/skills/pytest/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: pytest
+description: Pytest testing patterns for Python. Trigger: When writing Python tests - fixtures, mocking, markers.
+---
+
+## Basic Test Structure
+
+```python
+import pytest
+
+class TestUserService:
+    def test_create_user_success(self):
+        user = create_user(name="John", email="john@test.com")
+        assert user.name == "John"
+        assert user.email == "john@test.com"
+
+    def test_create_user_invalid_email_fails(self):
+        with pytest.raises(ValueError, match="Invalid email"):
+            create_user(name="John", email="invalid")
+```
+
+## Fixtures
+
+```python
+import pytest
+
+@pytest.fixture
+def user():
+    """Create a test user."""
+    return User(name="Test User", email="test@example.com")
+
+@pytest.fixture
+def authenticated_client(client, user):
+    """Client with authenticated user."""
+    client.force_login(user)
+    return client
+
+# Fixture with teardown
+@pytest.fixture
+def temp_file():
+    path = Path("/tmp/test_file.txt")
+    path.write_text("test content")
+    yield path  # Test runs here
+    path.unlink()  # Cleanup after test
+
+# Fixture scopes
+@pytest.fixture(scope="module")  # Once per module
+@pytest.fixture(scope="class")   # Once per class
+@pytest.fixture(scope="session") # Once per test session
+```
+
+## conftest.py
+
+```python
+# tests/conftest.py - Shared fixtures
+import pytest
+
+@pytest.fixture
+def db_session():
+    session = create_session()
+    yield session
+    session.rollback()
+
+@pytest.fixture
+def api_client():
+    return TestClient(app)
+```
+
+## Mocking
+
+```python
+from unittest.mock import patch, MagicMock
+
+class TestPaymentService:
+    def test_process_payment_success(self):
+        with patch("services.payment.stripe_client") as mock_stripe:
+            mock_stripe.charge.return_value = {"id": "ch_123", "status": "succeeded"}
+
+            result = process_payment(amount=100)
+
+            assert result["status"] == "succeeded"
+            mock_stripe.charge.assert_called_once_with(amount=100)
+
+    def test_process_payment_failure(self):
+        with patch("services.payment.stripe_client") as mock_stripe:
+            mock_stripe.charge.side_effect = PaymentError("Card declined")
+
+            with pytest.raises(PaymentError):
+                process_payment(amount=100)
+
+# MagicMock for complex objects
+def test_with_mock_object():
+    mock_user = MagicMock()
+    mock_user.id = "user-123"
+    mock_user.name = "Test User"
+    mock_user.is_active = True
+
+    result = get_user_info(mock_user)
+    assert result["name"] == "Test User"
+```
+
+## Parametrize
+
+```python
+@pytest.mark.parametrize("input,expected", [
+    ("hello", "HELLO"),
+    ("world", "WORLD"),
+    ("pytest", "PYTEST"),
+])
+def test_uppercase(input, expected):
+    assert input.upper() == expected
+
+@pytest.mark.parametrize("email,is_valid", [
+    ("user@example.com", True),
+    ("invalid-email", False),
+    ("", False),
+    ("user@.com", False),
+])
+def test_email_validation(email, is_valid):
+    assert validate_email(email) == is_valid
+```
+
+## Markers
+
+```python
+# pytest.ini or pyproject.toml
+[tool.pytest.ini_options]
+markers = [
+    "slow: marks tests as slow",
+    "integration: marks integration tests",
+]
+
+# Usage
+@pytest.mark.slow
+def test_large_data_processing():
+    ...
+
+@pytest.mark.integration
+def test_database_connection():
+    ...
+
+@pytest.mark.skip(reason="Not implemented yet")
+def test_future_feature():
+    ...
+
+@pytest.mark.skipif(sys.platform == "win32", reason="Unix only")
+def test_unix_specific():
+    ...
+
+# Run specific markers
+# pytest -m "not slow"
+# pytest -m "integration"
+```
+
+## Async Tests
+
+```python
+import pytest
+
+@pytest.mark.asyncio
+async def test_async_function():
+    result = await async_fetch_data()
+    assert result is not None
+```
+
+## Commands
+
+```bash
+pytest                          # Run all tests
+pytest -v                       # Verbose output
+pytest -x                       # Stop on first failure
+pytest -k "test_user"           # Filter by name
+pytest -m "not slow"            # Filter by marker
+pytest --cov=src                # With coverage
+pytest -n auto                  # Parallel (pytest-xdist)
+pytest --tb=short               # Short traceback
+```
+
+## Keywords
+pytest, python, testing, fixtures, mocking, parametrize, markers

package/assets/skills/react-19/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: react-19
+description: React 19 patterns with React Compiler. Trigger: When writing React components - no useMemo/useCallback needed.
+---
+
+## No Manual Memoization (REQUIRED)
+
+```typescript
+// ✅ React Compiler handles optimization automatically
+function Component({ items }) {
+  const filtered = items.filter(x => x.active);
+  const sorted = filtered.sort((a, b) => a.name.localeCompare(b.name));
+
+  const handleClick = (id) => {
+    console.log(id);
+  };
+
+  return <List items={sorted} onClick={handleClick} />;
+}
+
+// ❌ NEVER: Manual memoization
+const filtered = useMemo(() => items.filter(x => x.active), [items]);
+const handleClick = useCallback((id) => console.log(id), []);
+```
+
+## Imports (REQUIRED)
+
+```typescript
+// ✅ ALWAYS: Named imports
+import { useState, useEffect, useRef } from "react";
+
+// ❌ NEVER
+import React from "react";
+import * as React from "react";
+```
+
+## Server Components First
+
+```typescript
+// ✅ Server Component (default) - no directive
+export default async function Page() {
+  const data = await fetchData();
+  return <ClientComponent data={data} />;
+}
+
+// ✅ Client Component - only when needed
+"use client";
+export function Interactive() {
+  const [state, setState] = useState(false);
+  return <button onClick={() => setState(!state)}>Toggle</button>;
+}
+```
+
+## When to use "use client"
+
+- useState, useEffect, useRef, useContext
+- Event handlers (onClick, onChange)
+- Browser APIs (window, localStorage)
+
+## use() Hook
+
+```typescript
+import { use } from "react";
+
+// Read promises (suspends until resolved)
+function Comments({ promise }) {
+  const comments = use(promise);
+  return comments.map(c => <div key={c.id}>{c.text}</div>);
+}
+
+// Conditional context (not possible with useContext!)
+function Theme({ showTheme }) {
+  if (showTheme) {
+    const theme = use(ThemeContext);
+    return <div style={{ color: theme.primary }}>Themed</div>;
+  }
+  return <div>Plain</div>;
+}
+```
+
+## Actions & useActionState
+
+```typescript
+"use server";
+async function submitForm(formData: FormData) {
+  await saveToDatabase(formData);
+  revalidatePath("/");
+}
+
+// With pending state
+import { useActionState } from "react";
+
+function Form() {
+  const [state, action, isPending] = useActionState(submitForm, null);
+  return (
+    <form action={action}>
+      <button disabled={isPending}>
+        {isPending ? "Saving..." : "Save"}
+      </button>
+    </form>
+  );
+}
+```
+
+## ref as Prop (No forwardRef)
+
+```typescript
+// ✅ React 19: ref is just a prop
+function Input({ ref, ...props }) {
+  return <input ref={ref} {...props} />;
+}
+
+// ❌ Old way (unnecessary now)
+const Input = forwardRef((props, ref) => <input ref={ref} {...props} />);
+```
+
+## Keywords
+react, react 19, compiler, useMemo, useCallback, server components, use hook

package/assets/skills/react-hook-form/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: react-hook-form
+description: Patrones de React Hook Form en React+TS — register vs Controller, zodResolver, errores por campo, re-renders. Trigger: al crear o tocar formularios con RHF.
+---
+
+# React Hook Form — convenciones
+
+## Cuándo usar este skill
+
+Al crear o tocar un formulario con RHF: validación con Zod, submit, errores, o cablear inputs de una lib controlada (Mantine/MUI `Select`, `DatePicker`). RHF es la fuente de verdad del form — no dupliques sus valores en `useState`. Ventaja sobre Formik: los inputs nativos van **uncontrolled** (vía refs), así que teclear no re-renderiza el form entero.
+
+## El patrón
+
+Uncontrolled por defecto + Zod como schema + `Controller` **solo** donde el input no emite un evento DOM nativo.
+
+```tsx
+const schema = z.object({ email: z.string().email(), role: z.enum(['coach', 'coachee']) });
+type FormValues = z.infer<typeof schema>;
+
+const { register, control, handleSubmit, formState: { errors, isSubmitting } } =
+  useForm<FormValues>({ resolver: zodResolver(schema), defaultValues: { email: '', role: 'coachee' } });
+
+<TextInput error={errors.email?.message} {...register('email')} />  // nativo → register
+// Select de Mantine (onChange da el valor, no un event) → Controller:
+<Controller control={control} name="role" render={({ field, fieldState }) => (
+  <Select data={['coach','coachee']} error={fieldState.error?.message} {...field} />
+)} />
+```
+
+## Gotchas que muerden
+
+- **`register` por defecto; `Controller` es la excepción.** Un input que reenvía `ref` y dispara `onChange` con un evento DOM (texto, textarea, checkbox nativo, `<TextInput>` de Mantine) va con `{...register('campo')}`. Envolverlo en `Controller` re-introduce el re-render por tecla que RHF existe para evitar.
+- **Cuándo SÍ va `Controller`:** componentes cuyo `onChange` entrega el **valor directo** — Mantine `Select`/`MultiSelect`/`NumberInput`/`DateInput`, todo MUI, `react-select`. Cablea `field.value`/`onChange`/`onBlur`/`ref`; el error sale de `fieldState.error?.message`.
+- **`defaultValues` no es opcional.** Sin él, un campo arranca `undefined` → warning "uncontrolled to controlled" (`Controller` con `undefined` es inválido: usa `null`/`''`). Para edición async usa `reset(data)` en un `useEffect`, no valores a mano en cada render.
+- **`watch()` re-renderiza todo.** Para leer en submit usa `getValues('campo')`; para que un hijo dependa de un campo, `useWatch({ control, name })` en ese hijo. `watch()` global en un form grande es anti-patrón.
+- **Números: `register('age', { valueAsNumber: true })`.** Sin esto un `type="number"` entrega **string** y tu `z.number()` falla. Corre antes del resolver, así validas con `z.number()` directo.
+- **`useFieldArray` con `key={field.id}`, nunca el índice** (corrompe el estado al reordenar). Error de servidor con `setError('root.server', …)`, no en un campo.
+
+## Reglas duras
+
+1. Validación en schema Zod vía `zodResolver`; tipo por `z.infer`. Nada de `rules` inline ni tipos paralelos.
+2. `register` por defecto; `Controller` solo para inputs sin evento DOM nativo.
+3. `defaultValues` siempre; edición async con `reset(data)`, sin `useState` espejo.
+4. `getValues`/`useWatch` para leer sin re-render; `isSubmitting` deshabilita el botón.
+
+## Tabla rápida
+
+| Input | Cómo cablear |
+|---|---|
+| Texto / textarea / checkbox nativo | `{...register('campo')}` |
+| Número | `register('n', { valueAsNumber: true })` |
+| Select / Date / Number de Mantine/MUI | `<Controller>` + `{...field}` |
+| Lista dinámica | `useFieldArray` + `key={field.id}` |
+
+## Antes de declarar listo
+
+- Zod + `zodResolver`, tipo por `z.infer`; `Controller` para inputs controlados, `register` para texto; sin `useState` espejo.
+- `defaultValues` seteado; sin warnings "uncontrolled to controlled". Submit con `handleSubmit` + `isSubmitting`.
+- El quality gate del repo (`qualityGate.fast` en `argos.config.json`) en verde.

package/assets/skills/react-router/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: react-router
+description: Patrones de React Router (v6/v7) — rutas anidadas, loaders, navegación, params y guards. Trigger: al crear rutas, leer params, redirigir o proteger vistas.
+---
+
+# React Router — convenciones
+
+## Cuándo usar este skill
+
+Al tocar navegación: declarar una ruta, leer un param, redirigir, proteger una vista por rol, o cablear links. React Router es la fuente de verdad de **en qué URL estás y a dónde vas** — no dupliques la ruta en estado propio ni parsees `window.location` a mano.
+
+## El patrón
+
+Rutas anidadas con layout compartido vía `<Outlet />`; navegación por hooks, no por mutar `window.location`:
+
+```tsx
+const router = createBrowserRouter([
+  {
+    path: '/',
+    element: <AppLayout />,           // renderiza <Outlet /> para los hijos
+    children: [
+      { index: true, element: <Home /> },
+      { path: 'sessions/:id', element: <SessionDetail /> },
+      { path: '*', element: <NotFound /> },
+    ],
+  },
+]);
+
+function SessionDetail() {
+  const { id } = useParams();                 // string | undefined, siempre
+  const navigate = useNavigate();
+  const [params, setParams] = useSearchParams();
+  // ...
+  navigate('/sessions', { replace: true });   // no <a href> manual
+}
+```
+
+## Gotchas que muerden
+
+- **`useParams()` siempre da `string | undefined`.** Nunca `number`. Convierte y valida (`Number(id)`, guard) antes de usarlo como id; una ruta mal tecleada no lanza, solo llega `undefined`.
+- **Navegar imperativo con `useNavigate`, no `window.location`.** `window.location.href = …` recarga toda la SPA y tira el estado. Para volver: `navigate(-1)`; para redirigir sin dejar historial: `{ replace: true }`.
+- **`<NavLink>` para tabs/menús, `<Link>` para el resto.** `NavLink` expone `isActive` en `className`/`style`/children; no reimplementes "está activo" comparando `pathname` a mano.
+- **Search params son la URL, no `useState`.** Filtros/paginación viven en `useSearchParams` para que la vista sea linkeable y sobreviva al refresh. `setParams` reemplaza TODO el query — clona lo actual si solo cambias una clave.
+- **Ruta protegida = un wrapper con `<Navigate>`, no un `if` suelto.** `if (!user) return <Navigate to="/login" replace />;` dentro de un guard/layout. Redirigir desde un `useEffect` parpadea la vista privada un frame.
+- **Rutas relativas anidan; un `/` inicial las hace absolutas.** Dentro de `sessions/:id`, `navigate('edit')` va a `sessions/:id/edit`; `navigate('/edit')` va a la raíz. Es el error #1 al mover un componente de nivel.
+
+## Reglas duras
+
+1. Navegación por `useNavigate`/`<Link>`/`<NavLink>`; nunca `window.location` ni `<a href>` interno.
+2. `useParams` se valida antes de usar (puede ser `undefined`); ids numéricos se convierten explícito.
+3. Estado de filtros/paginación en `useSearchParams`, no en `useState` espejo.
+4. Vistas protegidas por un guard con `<Navigate replace>`, no por `if` + efecto.
+5. Layouts compartidos con rutas anidadas + `<Outlet />`; nada de repetir el chrome por página.
+
+## Antes de declarar listo
+
+- Sin `window.location`/`<a href>` para navegación interna; links con `<Link>`/`<NavLink>`.
+- Params validados; el estado de la URL (filtros, tab) vive en search params.
+- Rutas protegidas redirigen con `<Navigate replace>`; sin parpadeo de la vista privada.
+- El quality gate del repo (`qualityGate.fast` en `argos.config.json`) en verde.

package/assets/skills/redux-toolkit/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: redux-toolkit
+description: Patrones de Redux Toolkit en React+TS — slices, store tipado, hooks tipados, async thunks, selectores. Trigger: al tocar estado global, slices o el store.
+---
+
+# Redux Toolkit — convenciones
+
+## Cuándo usar este skill
+
+Al crear o tocar un slice, el store, async thunks, o leer/escribir estado global. RTK es el estándar — nada de `createStore` pelado, action types a mano, ni `connect`. Estado de servidor (fetch/cache) NO va aquí: eso es TanStack Query. Redux es para estado de cliente compartido (sesión, UI cross-página, carrito).
+
+## El patrón
+
+```ts
+const slice = createSlice({
+  name: 'session',
+  initialState,
+  reducers: {
+    setActive(state, action: PayloadAction<Session>) {
+      state.active = action.payload; // Immer: "mutas" un draft, no el real
+    },
+  },
+  extraReducers: (b) => {
+    b.addCase(loadSession.fulfilled, (s, a) => { s.active = a.payload; });
+  },
+});
+export const { setActive } = slice.actions;
+```
+
+Store + hooks tipados una sola vez, y se usan en toda la app:
+
+```ts
+export const useAppDispatch = useDispatch.withTypes<AppDispatch>();     // patrón vigente (RTK 2 / react-redux 9)
+export const useAppSelector = useSelector.withTypes<RootState>();       // no el viejo TypedUseSelectorHook
+```
+
+## Gotchas que muerden
+
+- **Immer solo dentro de `createSlice`.** Ahí "mutas" el draft; fuera de un reducer, mutar el state es un bug. No retornes Y mutes en el mismo reducer.
+- **Selectores memoizados** con `createSelector` cuando derivan/transforman — un selector que crea un array/objeto nuevo en cada llamada re-renderiza siempre.
+- **`useSelector` devuelve la referencia**: selecciona lo mínimo, no el slice entero. Si necesitas varios campos, envuelve con `useShallow(...)` (react-redux 9) para comparar superficial y no re-renderizar de más.
+- **Efectos reactivos → `createListenerMiddleware`**, no un `useEffect` espiando el store ni sagas. Reacciona a una acción/cambio de estado desde el middleware.
+- **Colecciones por id → `createEntityAdapter`**: `selectAll`/`selectById` memoizados gratis, CRUD normalizado, sin arreglos a mano.
+- **Async**: `createAsyncThunk` simple; si es data de API que cacheas/invalidas, evalúa RTK Query. `extraReducers` con builder callback (`(b) => b.addCase(...)`), la forma-objeto se eliminó en RTK 2.
+- **No-serializables** (Date, Map, funciones) fuera del store; rompen devtools y persistencia.
+
+## Reglas duras
+
+1. Estado global solo vía slices de RTK; nada de Context improvisado para lo mismo.
+2. Hooks `useAppDispatch`/`useAppSelector` tipados, nunca los crudos sin tipo.
+3. Selecciona lo mínimo y memoiza los derivados con `createSelector`.
+4. Estado de servidor no vive en Redux — eso es cache de queries.
+5. Solo valores serializables en el store.
+
+## Antes de declarar listo
+
+- El slice nuevo expone acciones tipadas y se consume con los hooks tipados.
+- Los selectores derivados están memoizados; los componentes seleccionan lo mínimo.
+- Nada de data de API duplicada en el store si ya hay capa de queries.
+- El quality gate del repo (`qualityGate.fast` en `argos.config.json`) en verde.

package/assets/skills/review-diff/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: review-diff
+description: Checklist de code review por dimensiones agnósticas al stack (tipos, capa de datos, errores, seguridad, hardcode, naming, dead code, quality gate) con severidades CRÍTICO/ALTO/MEDIO. Trigger: revisar un diff staged, una branch contra su rama base, o un PR puntual.
+---
+
+# Code review — checklist de un diff
+
+Aplica esta checklist a un diff (staged, branch vs la rama base del repo, o un PR puntual). El esqueleto es agnóstico al stack. Las reglas bespoke de un repo (patrones de su UI lib, convenciones de su capa de datos, anti-patterns propios) no se editan en este skill — viven en la ficha del repo (CLAUDE.md delgado) o en `argos.config.json`, y se leen en runtime.
+
+## Cómo reportar
+
+Una línea por hallazgo, ordenadas CRÍTICO → ALTO → MEDIO:
+
+```
+[CRÍTICO] <archivo>:<línea> — <descripción concreta y verificable>
+[ALTO]    <archivo>:<línea> — <descripción>
+[MEDIO]   <archivo>:<línea> — <descripción>
+```
+
+- **CRÍTICO** — rompe build, corrompe data, agujero de seguridad, contrato que no compila. *Bloquea el merge.*
+- **ALTO** — bug funcional probable, regresión, error no manejado visible al usuario, violación dura de una convención del repo. *Bloquea el merge.*
+- **MEDIO** — legibilidad, naming, doc faltante, hardcode menor, dead code. *No bloquea; se lista.*
+
+Si no llega a MEDIO, no lo reportes. Nada de "nitpick" ni "consider also". (Mapea al `reviewer`: CRÍTICO/ALTO = confidence ≥80, bloquean; MEDIO = observación informativa 50-79.)
+
+## 0. Pre-pasada (antes de leer línea por línea)
+
+- ¿El diff toca infra/config (`tsconfig*`, config de lint/build, `.env*`, CI, `settings.json`)? Flag → validar que el cambio es intencional.
+- ¿Borra archivos? Verifica que no queden imports residuales (`grep -rn "<archivo>"`).
+- ¿Mezcla cambios no relacionados (feature + refactor + format-only)? → MEDIO, pide separar.
+
+## 1. Tipos y contratos
+
+- `any` explícito en código nuevo sin justificación (`// any justificado: <razón>`) → ALTO.
+- Cast (`as Foo`) sin razón documentada → MEDIO; cast que oculta un tipo que en realidad no calza → CRÍTICO.
+- Tipo/interface desactualizado vs lo que el código consume (accede a un campo que el tipo no declara) → CRÍTICO.
+- Datos externos (respuesta de red, input de usuario, env) consumidos sin validar ni normalizar → ALTO.
+
+## 2. Capa de datos / lógica
+
+- Defaults explícitos para nullables que el consumidor usa directo (`?? …`) → ALTO si falta.
+- Funciones que deberían ser puras (transformadores/adapters) con side-effects (I/O, estado global) → CRÍTICO.
+- Valor de fuente externa (status/enum desconocido) asignado crudo a un tipo cerrado → ALTO.
+
+## 3. Manejo de errores
+
+- `catch` que se traga el error sin propagar ni reportar → ALTO.
+- Operación que puede fallar (red, parse, IO) sin manejo, con el fallo visible al usuario → ALTO.
+- Loading/spinner que nunca se apaga en el path de error → ALTO.
+
+## 4. Seguridad y autorización
+
+- Secretos/tokens/credenciales en código (no en config/env) → CRÍTICO.
+- Decisión de autorización solo en el cliente, sin validación del backend → ALTO.
+- Datos sensibles en storage del cliente más allá de lo necesario → ALTO.
+
+## 5. Sin hardcode
+
+- URLs de API / endpoints literales en vez del canal de config del repo → CRÍTICO.
+- Strings de estado/rol o listas de opciones duplicadas en vez de derivarlas de una fuente única → MEDIO.
+- Fechas/formatos armados a mano en vez del util del repo → MEDIO.
+
+## 6. Naming y estructura
+
+- Archivo en la carpeta equivocada según la convención del repo (componente compartido en `pages/`, etc.) → ALTO.
+- Casing/sufijos que rompen la convención del repo → MEDIO.
+- Convención de migración rota (cuando conviven código nuevo y legacy y hay un sufijo/carpeta esperado) → ALTO.
+
+## 7. Dead code y debug
+
+- `console.log` / print de debug sin guard en código que se mergea → MEDIO (en código nuevo: ALTO).
+- Imports o variables sin usar → MEDIO.
+- Código comentado entero / `if (false)` / `// TODO: borrar` sin issue → MEDIO.
+
+## 8. Quality gate (corrido en este turno, no asumido)
+
+- El quality gate fast del repo pasa → CRÍTICO si falla. El comando concreto no vive en este skill: resuélvelo leyendo `qualityGate.fast` en el `argos.config.json` del repo o su ficha (CLAUDE.md delgado).
+- Cero errores/warnings nuevos vs baseline → ALTO si el diff los agrega.
+
+## 9. Commit y PR
+
+- Commits siguen la convención del repo → MEDIO si rompe.
+- Cambios a manifest/lockfile sin razón clara en la descripción → ALTO.
+
+## Áreas críticas
+
+Presta atención extra si el diff toca las áreas críticas que declara el repo (`project.criticalAreas` en su `argos.config.json`, resuelto también en la ficha). Un hallazgo en esas zonas sube un nivel de severidad.
+
+## Output
+
+1. Lista plana con severidades, ordenada CRÍTICO → ALTO → MEDIO. Cada línea con `archivo:línea`.
+2. Si no hay hallazgos: `Sin observaciones.`
+3. Nada de resumen, "good job", ni sugerencias fuera del checklist.
+4. Si encuentras un patrón de bug nuevo que no está aquí, guárdalo (memoria / nota) para próximas reviews.
+
+## Conexión con el harness
+
+- `reviewer`: aplica este skill en la Pasada 2 (code quality). CRÍTICO/ALTO mapean a issues con confidence ≥80 (bloquean APPROVED); MEDIO a observaciones informativas (50-79).
+- `verify-before-done`: el quality gate del §8 se corre en este turno, no se asume del informe del implementer.
+
+Este skill vive una sola vez en el motor global y aplica a cualquier repo con `argos.config.json`. Las reglas bespoke de un stack/dominio concreto (componentes prohibidos de una UI lib, headers obligatorios de un cliente HTTP, reglas de forms propias, anti-patterns auto-CRÍTICO del repo) no se agregan a este archivo: van en la ficha del repo o en la config, y se leen en runtime al revisar ese repo específico.

package/assets/skills/ship-docs/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: ship-docs
+description: Generate repo-grounded README.md + DEPLOYMENT.md for a built app. Trigger: README, deployment guide, deploy docs, ship docs, runbook, how to deploy, documentar despliegue, handoff docs.
+---
+
+## Activation Contract
+
+Activate when a built app needs handoff/ship documentation — a README and a deployment runbook — or the user asks for deploy docs. This is the FINAL documentation layer (app-builder's closing phase). Do NOT activate for inline code comments, API reference generation, or a design doc for unbuilt work.
+
+## Hard Rules
+
+- Ground EVERYTHING in the real repo. Before writing a line, read: root + workspace `package.json` (name, scripts, deps → real stack), the monorepo layout, `app.json`/`app.config`, migrations dir, `.env.example` / env usage, CI config. Never emit generic boilerplate or invented commands.
+- Every command in the docs MUST exist (a real npm script, a real CLI the repo uses). Verify; if a step needs a tool the repo lacks, say so explicitly, don't fabricate.
+- Two documents, never merged: README (clone → run locally) and DEPLOYMENT.md (ship → production runbook). Mixing buries both.
+- Secrets never appear in docs or git. Reference env vars by name; point to `.env.example`; call out where real secrets live (host dashboard, EAS secrets).
+- Write for a teammate who just cloned and knows nothing. Apply cognitive-doc-design: scannable headers, one concept per section, copy-pasteable ordered steps, prerequisites before actions.
+- DEPLOYMENT.md is a RUNBOOK: ordered, numbered, each step's command + expected result + how to verify. Include rollback and a post-deploy checklist.
+
+## Decision Gates
+
+| Repo shape | Deploy sections to include |
+|---|---|
+| Backend (Supabase/DB/API) present | Backend deploy: create project, apply migrations, seed, email/template + auth config, env vars |
+| Web app present | Web deploy: host (Vercel/Netlify/…), build command, env vars, custom domain |
+| Mobile (Expo/RN) present | Mobile: EAS build/submit, store (App Store Connect / Play), TestFlight, required public URLs |
+| Only one of the above | Include only that section; do not template absent stacks |
+
+## Execution Steps
+
+1. Read `references/ship-docs-playbook.md` for the section checklists.
+2. Harvest repo facts (scripts, layout, stack, migrations, app config, env keys). Derive, don't assume.
+3. Write `README.md`: one-line what + why; architecture (shared packages / the "brain"); repo layout; prerequisites (versions); local setup as ordered steps (backend up, env, install, run each app); scripts table; testing; troubleshooting for the repo's known gotchas.
+4. Write `DEPLOYMENT.md`: env-var reference table (name · where used · where the real value lives); then a numbered runbook per present stack (gate table above); post-deploy checklist; rollback.
+5. Ensure `.env.example` lists every env key the code reads (add missing keys). Never commit real `.env`.
+6. Verify: every referenced script/command exists; links resolve; no secret literals.
+
+## Output Contract
+
+Return: files created (README.md, DEPLOYMENT.md, .env.example changes); which stacks were detected and documented; any command/tool the repo lacks that a deploy step needs (flagged, not faked); repo style guide vs inline fallback used.
+
+## References
+
+- `references/ship-docs-playbook.md` — per-stack section checklists (backend / web / mobile), env-table shape, runbook and rollback patterns.
+
+_Adapted from a skill originally authored by ricardomarin._

package/assets/skills/ship-docs/references/ship-docs-playbook.md

@@ -0,0 +1,31 @@
+# Ship Docs Playbook
+
+Section checklists for README.md + DEPLOYMENT.md. Every item is repo-derived — read the files, don't assume.
+
+## README.md skeleton
+
+1. **Title + one-liner** — what the app is and who it's for, one sentence.
+2. **Architecture** — the shared "brain" (domain/data/token packages), what's platform-specific, why it's structured this way. One paragraph + a layout tree.
+3. **Repo layout** — `apps/*`, `packages/*`, backend dir, with a one-line purpose each.
+4. **Prerequisites** — exact versions/tools the repo needs (Node, package manager, Xcode/Android SDK if mobile, backend CLI, Docker if used). Read `engines`, lockfile, config.
+5. **Local setup — ordered steps**: (a) start the backend/local stack, (b) copy `.env.example` → `.env` per app and where to get values, (c) install, (d) run each app (the real scripts), (e) first-run notes (seed, migrations, test login).
+6. **Scripts** — a table of the actual root/workspace scripts and what each does.
+7. **Testing** — how to run the real test targets; what they cover.
+8. **Troubleshooting** — the repo's KNOWN gotchas (monorepo symlink/postinstall quirks, native-module version pins, cache-clear flags). Pull from the project's own notes.
+
+## DEPLOYMENT.md skeleton (runbook)
+
+1. **Overview** — the deploy targets (backend, web, mobile) and their order of dependency.
+2. **Environment variables** — a table: `NAME | consumed by (app) | where the real value lives`. Split public (client) vs secret (server/build). Never inline values.
+3. **Backend** (if present) — create the cloud project; link CLI; push migrations (real command); seed if applicable; auth/email templates & redirect URLs to replicate from local config; obtain prod URL + anon key; note service-role stays server-only.
+4. **Web** (if present) — host, framework preset, build command + output dir (from the real build script), env vars to set in the host, SPA rewrite/routing config, custom domain, the public URLs the app must expose (e.g. privacy/support).
+5. **Mobile** (if present) — bundle IDs; EAS setup (`eas build:configure`); EAS secrets for env; `eas build` per platform; `eas submit`; App Store Connect / Play listing needs (privacy URL, support URL — point at the web deploy); TestFlight/internal track for the pilot.
+6. **Post-deploy checklist** — smoke each surface against prod; verify auth end-to-end; confirm the recovery/email flows work with prod templates; check the public URLs resolve.
+7. **Rollback** — how to revert each surface (redeploy previous, migration-down caveats, store rollback limits).
+
+## Rules of thumb
+
+- If the repo has a local backend config (e.g. `config.toml`, email templates), the deploy doc must say "replicate this in the cloud project" and point at the exact file — otherwise prod silently diverges (e.g. OTP email showing a link instead of a code).
+- Prefer linking a real `.env.example` over listing keys twice.
+- Flag every place a human decision is required (choose host, buy domain, Apple account) as a **[you decide]** callout — don't pretend it's automatic.
+- Keep commands copy-pasteable: one command per line, real flags, expected output noted.