argos-harness 0.1.0

package/assets/skills/store-ship/references/pipeline.md

@@ -0,0 +1,198 @@
+# Store Ship — Pipeline Runbook
+
+Full reference for executing a store submission. The SKILL.md contract governs; this file holds the operational detail. Real order: prereqs → scaffold → metadata as code → one-time ASC manual fixes → screenshots (Maestro) → build + submit → final metadata push → manual checklist.
+
+## 1. Prerequisites (verify before anything)
+
+| Item | How to verify | Blocking? |
+|---|---|---|
+| Apple Developer Program membership + App Store Connect app record | ascAppId exists | Yes (iOS) |
+| Play Console developer account + app record | package name registered | Yes (Android) |
+| EAS project linked | `eas init` done, `extra.eas.projectId` in app config | Yes |
+| Privacy policy + support URLs live | Phase 8 output, HTTP 200 | Yes — App Store Connect rejects without them |
+| App Store Connect API key (p8) | stored as EAS secret / local path outside repo | Yes for `eas submit -p ios` |
+| Play service-account JSON with release permission | stored outside repo | Yes for `eas submit -p android` (after first manual upload) |
+| Demo account for App Review | seeded credentials that WORK in production backend | Yes — auth-gated apps are rejected without one |
+| Maestro CLI + Java | `maestro --version` succeeds | Yes (screenshots) |
+| EAS env vars set for every `EXPO_PUBLIC_*` the app consumes | push once with `eas env:push <environment> --path .env.local` (from the app dir); verify with `eas env:list <environment>` cross-checked against `rg -o 'EXPO_PUBLIC_[A-Z_]+' apps/<app>` output | Yes — gitignored `.env` files are NOT uploaded to EAS builds |
+
+Maestro install: `brew install maestro` installs a different, unrelated product — do NOT use it. Install with `curl -Ls "https://get.maestro.mobile.dev" | bash`; it requires Java (`brew install openjdk`). Verify with `maestro --version`.
+
+## 2. eas.json
+
+Start from `assets/eas.template.json`. Key decisions:
+
+- `appVersionSource: "remote"` + `autoIncrement: true` on production — EAS owns build numbers; never hand-bump.
+- Submit profiles reference credentials by path/env, never inline.
+- Android `track: "internal"` first; promote in console or with a later `eas submit --track production`.
+- Pin `"environment": "production" | "preview" | "development"` on each build profile so the matching EAS env set loads at build time. EAS cloud builds do NOT upload gitignored `.env` files — without EAS env vars, every `EXPO_PUBLIC_*` var is undefined and inlined as missing into the bundle (unfixable post-build; requires a rebuild). See §1 for the push/verify commands.
+- First-ever iOS submission: `eas submit` format-validates `submit.<profile>.ios` fields (`ascAppId`, `appleTeamId`, `ascApiKeyId`, `ascApiKeyIssuerId`) before any interactive prompt — `TODO_*` placeholders hard-fail the command before you ever see a login screen. Leave `ios` as an empty object `{}` for the first submission instead: `eas submit` then prompts an Apple ID login and auto-creates the ASC app record. Fill in the real ids afterward for unattended/CI use. JSON has no comments, so this convention lives here, not in the file: an empty `"ios": {}` under `submit.<profile>` means "first submission, not yet wired for CI."
+
+## 3. Metadata as code
+
+### iOS — `eas metadata` (`store/store.config.json`)
+
+Template: `assets/store.config.template.json`. Field limits (hard, validated by `eas metadata:validate`):
+
+| Field | Limit |
+|---|---|
+| title | 30 chars |
+| subtitle | 30 chars |
+| keywords | 100 chars total, comma-separated |
+| description | 4000 chars |
+| promoText | 170 chars (editable without new build) |
+
+The schema field is `promoText`, NOT `promotionalText` — the wrong name fails `eas metadata:push` validation. Allowed `info.<locale>` properties: `title`, `subtitle`, `description`, `keywords`, `releaseNotes`, `promoText`, `marketingUrl`, `supportUrl`, `privacyPolicyText`, `privacyPolicyUrl`, `privacyChoicesUrl`, `screenshots`, `previews`. Notably absent: `copyright`, pricing, content rights — those are never push-able (§4).
+
+Derivation from `docs/product-definition.md`: title = product name; subtitle = the one-line value promise; description = core promise + feature list (§ features) rewritten as user benefits; keywords = domain nouns the target user searches, no competitor names, no duplicates of title words (wasted chars). Locale: use the app's UI language as primary (`es-MX` for Spanish-market apps); add `en-US` only if the app actually ships English.
+
+es-MX copy rule: display fields the user reads (`description`, `promoText`, `subtitle`, Android `short_description`/`full_description`) MUST carry proper Spanish accents. `keywords` are the one field to write deliberately accentless — App Store search normalizes diacritics and users type without accents.
+
+Push: `eas metadata:push` (validates first). Pull existing console state before first push: `eas metadata:pull`.
+
+`metadataPath` wiring: when `store.config.json` lives at repo-root `store/` (this skill's layout), the submit profile in `eas.json` MUST set `"metadataPath": "../../store/store.config.json"` — `eas metadata` otherwise looks for the config next to `eas.json` and reports it missing.
+
+Fresh ASC app: `eas metadata:push` against a just-created App Store Connect app fails with API errors ("must provide versionString", "appInfo relationship missing") until Apple initializes the 1.0 version — which happens once the FIRST binary finishes processing. This is not a config error; retry after TestFlight shows the build processed. If it still fails once the build has processed, see the one-time manual fixes in §4.
+
+Screenshot schema: `apple.info.<locale>.screenshots` maps Apple's `screenshotDisplayType` enum keys — `APP_IPHONE_67`, `APP_IPHONE_65`, `APP_IPHONE_61`, `APP_IPAD_PRO_3GEN_129`, `APP_IPAD_PRO_3GEN_11` are the common ones — to arrays of image paths. EAS local validation does NOT catch a wrong key; only ASC rejects it at push time, and that API error helpfully lists the full enum. Paths resolve relative to the PROJECT DIRECTORY (the app dir where `eas.json` lives), NOT relative to `store.config.json` — with the repo-root `store/` layout:
+
+```json
+"screenshots": {
+  "APP_IPHONE_67": ["../../store/screenshots/ios/iphone-6.9/01-signature.png"]
+}
+```
+
+This is the config shape only — the files don't exist yet until §5 captures them, and the real push (with real paths and the real demo password) is the final push in §6.
+
+### Android — supply tree (`store/android/`)
+
+`eas metadata` does NOT support Play. Keep the fastlane `supply` layout (see `assets/android-supply.template.md`) so it works with fastlane or manual paste:
+
+```
+store/android/metadata/{locale}/
+  title.txt            # 30 chars
+  short_description.txt # 80 chars
+  full_description.txt  # 4000 chars
+  images/phoneScreenshots/ …
+```
+
+Upload: `fastlane supply --metadata_path store/android/metadata` if fastlane is available; otherwise paste once — the repo copy remains the source of truth.
+
+## 4. One-time ASC manual fixes (API-created apps)
+
+Apps auto-created by `eas submit` (the empty `"ios": {}` first-submission convention, §2) often need manual fixes in App Store Connect before metadata syncs cleanly. Two are conditional on the API-creation path; three are ALWAYS manual for every app, API-created or not, because the `eas metadata` schema (§3) has no field for them.
+
+| Fix | Trigger | Symptom if skipped |
+|---|---|---|
+| "1.0 Prepare for Submission" version exists (create if not) | Conditional — check once the first build has processed | "versionString missing", `appInfoLocalizations` relationship errors |
+| App Information → Primary Language = app's locale (e.g. Spanish (Mexico)) | Conditional — same trigger | "Skipping screenshots - locale not found" |
+| Copyright | ALWAYS manual — `apple.copyright` in `store.config.json` triggers a broken version-info PATCH on API-created apps that persists even after the 1.0 version exists | "must provide versionString" keeps failing after the 1.0 version exists |
+| Pricing and availability | ALWAYS manual — not in the `eas metadata` schema | n/a |
+| Content Rights declaration | ALWAYS manual — not in the `eas metadata` schema | n/a |
+
+Fix once in App Store Connect, then re-push metadata (§3). Omit `copyright` from `store.config.json` — the template omits it deliberately (JSON has no comments, so this note lives here).
+
+## 5. Screenshots (Maestro)
+
+### Device matrix
+
+| Store slot | Device | Size | Required |
+|---|---|---|---|
+| iPhone 6.9" | iPhone 16 Pro Max sim | 1320×2868 | Yes (covers smaller sizes since 2024) |
+| iPad 13" | iPad Pro 13" sim | 2064×2752 | Only if `supportsTablet: true` |
+| Play phone | Pixel emulator | ≥1080 wide, 16:9–9:16 | Yes (2–8 shots) |
+| Play 7"/10" tablet | tablet emulator | ≥1080 wide | Only if tablet UI exists |
+
+Device matrix drift: newer Xcode may ship simulator runtimes for only the latest iPhones (e.g. 17-series), so the required 6.9" device (iPhone 16 Pro Max, 1320×2868) may not exist yet — create it: `xcrun simctl create "iPhone 16 Pro Max" <devicetype-id>`. Never substitute a device with a different resolution and never resize images to fit; a wrong-resolution screenshot must be retaken on the correct device.
+
+### Local-backend screenshot env (recommended, self-contained)
+
+Running screenshots against a local Supabase backend avoids polluting shared/staging data and needs no network:
+
+1. `supabase start` — under colima, the `vector` log-shipping container can fail to start; if it does, use `supabase start --exclude vector` instead of debugging it.
+2. After `supabase db push` to the local instance, PostgREST may return `42501 permission denied` on app tables even though the schema is correct — local `db push` does not carry over table GRANTs for the `authenticated` role. Apply `GRANT SELECT` (and any other roles the app needs) on the app tables manually. Re-apply after every `supabase db reset`, since reset wipes GRANTs too.
+3. Pass backend overrides (Supabase URL, anon key) INLINE as env vars to the build command, not via a temp `.env` file — nothing to clean up afterward and no risk of clobbering `.env.local`.
+
+### Procedure
+
+1. Seed demo data first — screenshots of empty states don't sell. Use the project's seed script with a dedicated demo user; pick data that shows the app at its best (populated lists, active membership, real-looking names).
+2. Build a dev/simulator build (`eas build --profile development` or `npx expo run:ios --configuration Release` locally, with backend env vars passed inline). Expo Go screenshots are not acceptable (dev menu chrome, wrong icon). Note: `npx expo run:ios` on a managed app generates `ios/` (verify it's gitignored), rewrites the `package.json` `ios`/`android` scripts to `expo run:*`, and may add `expo-updates` — this is expected native-project scaffolding, not damage; don't "fix" it back on a later run.
+3. Write one Maestro flow per screenshot set from `assets/maestro-flow.template.yaml`: `launchApp` → `waitForAnimationToEnd` → login as demo user → navigate → `takeScreenshot` per key screen. Always wait for animations to end before the FIRST screenshot too — the first frame after launch (and after any navigation) can still show launch-transition chrome, and a shot taken mid-transition needs retaking. 4–6 screens: the signature screen first (it is the store card image), then core loop, then differentiators.
+4. Watch for Keychain/SecureStore state surviving `clearState`: anything the app persists via SecureStore (e.g. a one-shot celebration/onboarding acknowledgement) is NOT reset by Maestro's `clearState` and will not re-trigger on a normal re-run — it needs a fresh simulator or `xcrun simctl erase <device>` to fire again. Write flows so they pass either way (don't assert on a one-shot state that may already be dismissed). One-shot moments make great store screenshots — plan a device reset into the run when you need one.
+5. Run per device: boot the simulator/emulator at the matrix size, `maestro test store/flows/screenshots.yaml -e DEMO_PASSWORD=...` (env values via `-e`, never hardcoded — see SKILL.md hard rules), move output to `store/screenshots/{platform}/{device}/NN-name.png`. Keep the screenshot output directory under `store/` next to `store.config.json` — the config's `screenshots` paths resolve relative to the PROJECT DIRECTORY, not this directory (§3).
+6. Verify: correct resolution, no status-bar clutter (simulator status bar is fine; `xcrun simctl status_bar override` to clean it), no personal data.
+
+Framing (device bezels + captions) is optional; if requested use fastlane `frameit` or skip — plain screenshots are store-compliant.
+
+## 6. Build + submit
+
+```
+eas build --platform all --profile production   # wait for both artifacts
+eas submit -p ios --latest                      # → TestFlight
+eas submit -p android --latest                  # → internal track (fails before first manual AAB upload — expected)
+```
+
+Verify: TestFlight shows the build processing; Play internal track lists the release. Report actual command output, not intent.
+
+`eas submit` ALWAYS runs the submission job on EAS servers — even with `--path <local-ipa>` it uploads your ipa and an EAS worker delivers it to Apple, so the build/submit queue applies either way.
+
+### Queue-free local submission (iOS)
+
+Fully local paths that skip the EAS queue, all present on a standard Mac setup:
+
+- `xcrun altool --upload-app -f <ipa> -t ios` (still shipping in Xcode 26) — auth with an app-specific password (`-u`/`-p`) or an ASC API key (`--apiKey`/`--apiIssuer`, `.p8` at `~/.appstoreconnect/private_keys/AuthKey_<KEYID>.p8`).
+- Transporter.app GUI, or its CLI: `/Applications/Transporter.app/Contents/itms/bin/iTMSTransporter`.
+- `fastlane pilot upload`.
+
+Recommended durable path: create the team's OWN ASC API key (App Manager role, `.p8` in gitignored `secrets/`) — one key powers altool, pilot, and non-interactive automation. Note: the EAS-generated ASC key lives on EAS servers and cannot be downloaded, so it cannot back these local paths.
+
+### `eas build --local`
+
+- Requires fastlane (fails with `spawn fastlane ENOENT`) and CocoaPods installed locally.
+- Credentials, EAS env vars, and remote `autoIncrement` all still sync from EAS servers — a local build is not an offline build.
+- The artifact lands as `build-<timestamp>.ipa` in the app dir.
+- SECURITY: the local build job payload echoed to the terminal embeds the provisioning profile AND the distribution certificate with its password (base64). Build logs are sensitive — never paste them publicly; rotate via `eas credentials` if exposed.
+
+### Wrap the working chain in npm scripts
+
+Once the chain works end to end, freeze it as root `package.json` scripts so future runs are one command: `deploy:<web-surface>` (build + deploy + alias + HTTP-200 verification), `deploy:ios` (preflight fastlane/pods → local build → pick newest `build-*.ipa` → submit), `env:push:mobile`, and `metadata:push`. Deliberately add NO `deploy:android` until a Play presence exists — it would be a dead script.
+
+### Final metadata push (after build + submit)
+
+Screenshots (§5) and the demo password only belong in the config once they're real, and the password should spend the least possible time on disk — so this push is last, not part of the initial metadata authoring in §3:
+
+1. Add the real screenshot paths to `apple.info.<locale>.screenshots` (key/path format in §3).
+2. Inject the real demo account password into `apple.review.demoPassword`.
+3. `eas metadata:push`.
+4. Immediately revert the password field to its placeholder.
+5. Verify with `rg` that no real credential remains in `store/` before committing — this is what keeps the "no credentials in repo" hard rule true.
+
+## 7. Manual checklist (cannot be automated — always deliver)
+
+- App Store Connect: App Privacy questionnaire (data collection declarations — derive answers from what the app actually collects and hands to Supabase/analytics).
+- App Store Connect: age rating questionnaire.
+- App Review notes: demo account credentials + any reviewer instructions (e.g. "accounts are admin-created; use the demo login").
+- Play Console: content rating questionnaire, data safety form, first AAB upload by hand.
+- Both: confirm pricing/availability, territories, and (iOS) the Content Rights declaration — always manual, see §4.
+
+## 8. Troubleshooting
+
+| Symptom | Cause / fix |
+|---|---|
+| `eas metadata:push` auth error | ASC API key missing/expired — recreate in App Store Connect → Users and Access → Keys |
+| Submit rejected: missing privacy URL | Phase 8 not deployed — hard prerequisite |
+| Play submit 403 | service account lacks release permission, or first AAB never uploaded manually |
+| Screenshot wrong size | simulator device ≠ matrix device; do not resize with sips — retake |
+| Metadata rejected for claims | copy promised features the build doesn't have — re-derive from product definition, not marketing wishes |
+| `eas submit` fails instantly, no login prompt | `TODO_*` placeholder ids in `submit.<profile>.ios` — use `"ios": {}` for the first submission (§2) |
+| `maestro --version` not found / wrong tool | installed via `brew install maestro` (wrong product) — reinstall per §1 |
+| PostgREST `42501 permission denied` on local Supabase | table GRANTs missing after local `db push`/`db reset` (§5 local-backend env) |
+| `supabase start` hangs/fails under colima | `vector` container failing (§5 local-backend env) |
+| Screenshot shows launch chrome / blank frame | missing `waitForAnimationToEnd` after `launchApp` or a nav tap (§5 procedure) |
+| One-shot UI (celebration/onboarding) never appears for its screenshot | SecureStore/Keychain survives Maestro `clearState` (§5 procedure step 4) |
+| Build/TestFlight can't reach backend, dev works locally | `EXPO_PUBLIC_*` vars missing at EAS build time — push env vars (§1) and REBUILD |
+| `eas metadata:push` fails: "must provide versionString" / "appInfo relationship missing" | before first build processes: ASC hasn't initialized the 1.0 version yet, retry later; persists after: either the §4 manual fixes are still needed, or `apple.copyright` is set in the config |
+| "Skipping screenshots - locale not found" / `appInfoLocalizations` errors | wrong primary language or no 1.0 version — see §4 |
+| Screenshot key rejected at push time only | wrong `screenshotDisplayType` enum key (e.g. `iphone67`) — must be `APP_IPHONE_67` etc.; EAS local validation doesn't catch it (§3) |
+| `eas metadata:push` validation rejects a field name | field not in the schema (e.g. `promotionalText` — real name is `promoText`, §3) |
+| `eas build --local` fails: `spawn fastlane ENOENT` | fastlane (and CocoaPods) missing locally — install both (§6) |

package/assets/skills/stripe/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: stripe
+description: Integración de pagos con Stripe — selección de API (Checkout/Payment/Setup Intents), claves restringidas, idempotencia y verificación de webhooks. Trigger: al crear cobros, checkout, suscripciones o handlers de webhook de Stripe.
+---
+
+# Stripe — el patrón canónico
+
+Alineado con la skill oficial `stripe-best-practices`. El server manda: la lógica de cobro y las claves `sk_`/`rk_` viven en el backend; el cliente solo toca la publishable key.
+
+## Cuándo usar este skill
+
+Al crear un cobro, checkout, suscripciones, o un handler de webhook de Stripe.
+
+## Qué API usar
+
+| Caso | API |
+|---|---|
+| Pago único on-session | **Checkout Session** |
+| Form propio embebido | Checkout Session + **Payment Element** |
+| Guardar método de pago (sin cobrar) | **Setup Intent** |
+| Suscripciones / recurrente | **Billing** + Checkout Session |
+| Marketplace / plataforma | **Accounts v2** (`/v2/core/accounts`) |
+| Impuestos (IVA/VAT/GST) | **Stripe Tax** + Registrations API |
+
+**Nunca uses la Charges API** (legacy): si te topas con ella, migra a Checkout Session o Payment Intent — no le agregues features.
+
+## Seguridad de claves
+
+Tres tipos: **publishable** (`pk_`, cliente), **secret** (`sk_`, server) y **restricted** (`rk_`, server con scope acotado). Prefiere **`rk_` sobre `sk_`**. Las claves van en env vars; la `sk_`/`rk_` **jamás** entra al bundle del cliente.
+
+## El patrón (server-side)
+
+```ts
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
+  apiVersion: '2026-06-24.dahlia', // fija la última; no dejes el default de la cuenta
+});
+
+// idempotencyKey: reintentar la misma request NO crea un segundo cobro.
+const session = await stripe.checkout.sessions.create(
+  {
+    mode: 'payment',
+    line_items: [{ price: priceId, quantity: 1 }],
+    success_url: `${base}/ok?session_id={CHECKOUT_SESSION_ID}`,
+    cancel_url: `${base}/cancel`,
+    // Sin payment_method_types: deja los dynamic payment methods del Dashboard.
+  },
+  { idempotencyKey: `checkout:${orderId}` },
+);
+```
+
+## Webhooks
+
+El estado real llega por webhook, no por el `success_url`. Verifica **siempre** la firma y hazlo idempotente:
+
+```ts
+// rawBody = cuerpo crudo, NO el JSON parseado (el body-parser rompe la firma).
+const event = stripe.webhooks.constructEvent(rawBody, sig, process.env.STRIPE_WEBHOOK_SECRET!);
+if (await alreadyProcessed(event.id)) return res.sendStatus(200); // el event.id puede repetirse
+```
+
+Responde `2xx` rápido; el trabajo pesado va a una cola.
+
+## Gotchas que muerden
+
+- **`payment_method_types` fijo** apaga los dynamic payment methods del Dashboard. Omítelo (única excepción: Terminal → `['card_present']`); para restringir usa `payment_method_configurations` o `excluded_payment_method_types`.
+- **`automatic_tax: { enabled: true }` sin registro fiscal activo** cobra **cero** impuesto pareciendo habilitado — el error más común y silencioso. Verifica el registro antes.
+- **Montos en la unidad mínima y enteros** (centavos: $10.00 → `1000`). Nunca floats.
+
+## Reglas duras
+
+1. Cobro y claves `sk_`/`rk_` solo en el server (env vars); el cliente solo con `pk_`. Prefiere `rk_` sobre `sk_`.
+2. `apiVersion` fija a la última; nada de default implícito.
+3. Charges API prohibida en código nuevo.
+4. `idempotencyKey` en toda request de creación que mueva dinero.
+5. Webhooks: firma verificada con `rawBody` + handler idempotente por `event.id`.
+6. Sin `payment_method_types` salvo Terminal.
+
+## Antes de declarar listo
+
+- Ninguna `sk_`/`rk_` quedó en el cliente ni en el repo.
+- Cada cobro lleva `idempotencyKey`; el pago se confirma por webhook (firma + idempotente), no por el redirect.
+- Si hay impuestos: registro fiscal activo verificado.
+- El quality gate del repo (`qualityGate.fast` en `argos.config.json`) en verde.

package/assets/skills/tailwind-4/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: tailwind-4
+description: Tailwind CSS 4 patterns and best practices. Trigger: When styling with Tailwind - cn(), theme variables, no var() in className.
+---
+
+## Styling Decision Tree
+
+```
+Tailwind class exists?  → className="..."
+Dynamic value?          → style={{ width: `${x}%` }}
+Conditional styles?     → cn("base", condition && "variant")
+Static only?            → className="..." (no cn() needed)
+Library can't use class?→ style prop with var() constants
+```
+
+## Critical Rules
+
+### Never Use var() in className
+
+```typescript
+// ❌ NEVER: var() in className
+<div className="bg-[var(--color-primary)]" />
+<div className="text-[var(--text-color)]" />
+
+// ✅ ALWAYS: Use Tailwind semantic classes
+<div className="bg-primary" />
+<div className="text-slate-400" />
+```
+
+### Never Use Hex Colors
+
+```typescript
+// ❌ NEVER: Hex colors in className
+<p className="text-[#ffffff]" />
+<div className="bg-[#1e293b]" />
+
+// ✅ ALWAYS: Use Tailwind color classes
+<p className="text-white" />
+<div className="bg-slate-800" />
+```
+
+## The cn() Utility
+
+```typescript
+import { clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+```
+
+### When to Use cn()
+
+```typescript
+// ✅ Conditional classes
+<div className={cn("base-class", isActive && "active-class")} />
+
+// ✅ Merging with potential conflicts
+<button className={cn("px-4 py-2", className)} />  // className might override
+
+// ✅ Multiple conditions
+<div className={cn(
+  "rounded-lg border",
+  variant === "primary" && "bg-blue-500 text-white",
+  variant === "secondary" && "bg-gray-200 text-gray-800",
+  disabled && "opacity-50 cursor-not-allowed"
+)} />
+```
+
+### When NOT to Use cn()
+
+```typescript
+// ❌ Static classes - unnecessary wrapper
+<div className={cn("flex items-center gap-2")} />
+
+// ✅ Just use className directly
+<div className="flex items-center gap-2" />
+```
+
+## Style Constants for Charts/Libraries
+
+When libraries don't accept className (like Recharts):
+
+```typescript
+// ✅ Constants with var() - ONLY for library props
+const CHART_COLORS = {
+  primary: "var(--color-primary)",
+  secondary: "var(--color-secondary)",
+  text: "var(--color-text)",
+  gridLine: "var(--color-border)",
+};
+
+// Usage with Recharts (can't use className)
+<XAxis tick={{ fill: CHART_COLORS.text }} />
+<CartesianGrid stroke={CHART_COLORS.gridLine} />
+```
+
+## Dynamic Values
+
+```typescript
+// ✅ style prop for truly dynamic values
+<div style={{ width: `${percentage}%` }} />
+<div style={{ opacity: isVisible ? 1 : 0 }} />
+
+// ✅ CSS custom properties for theming
+<div style={{ "--progress": `${value}%` } as React.CSSProperties} />
+```
+
+## Common Patterns
+
+### Flexbox
+
+```typescript
+<div className="flex items-center justify-between gap-4" />
+<div className="flex flex-col gap-2" />
+<div className="inline-flex items-center" />
+```
+
+### Grid
+
+```typescript
+<div className="grid grid-cols-3 gap-4" />
+<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-6" />
+```
+
+### Spacing
+
+```typescript
+// Padding
+<div className="p-4" />           // All sides
+<div className="px-4 py-2" />     // Horizontal, vertical
+<div className="pt-4 pb-2" />     // Top, bottom
+
+// Margin
+<div className="m-4" />
+<div className="mx-auto" />       // Center horizontally
+<div className="mt-8 mb-4" />
+```
+
+### Typography
+
+```typescript
+<h1 className="text-2xl font-bold text-white" />
+<p className="text-sm text-slate-400" />
+<span className="text-xs font-medium uppercase tracking-wide" />
+```
+
+### Borders & Shadows
+
+```typescript
+<div className="rounded-lg border border-slate-700" />
+<div className="rounded-full shadow-lg" />
+<div className="ring-2 ring-blue-500 ring-offset-2" />
+```
+
+### States
+
+```typescript
+<button className="hover:bg-blue-600 focus:ring-2 active:scale-95" />
+<input className="focus:border-blue-500 focus:outline-none" />
+<div className="group-hover:opacity-100" />
+```
+
+### Responsive
+
+```typescript
+<div className="w-full md:w-1/2 lg:w-1/3" />
+<div className="hidden md:block" />
+<div className="text-sm md:text-base lg:text-lg" />
+```
+
+### Dark Mode
+
+```typescript
+<div className="bg-white dark:bg-slate-900" />
+<p className="text-gray-900 dark:text-white" />
+```
+
+## Arbitrary Values (Escape Hatch)
+
+```typescript
+// ✅ OK for one-off values not in design system
+<div className="w-[327px]" />
+<div className="top-[117px]" />
+<div className="grid-cols-[1fr_2fr_1fr]" />
+
+// ❌ Don't use for colors - use theme instead
+<div className="bg-[#1e293b]" />  // NO
+```
+
+## Keywords
+tailwind, css, styling, cn, utility classes, responsive

package/assets/skills/tamagui/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: tamagui
+description: UI con Tamagui v4 — styled() + variants, tokens de tema y qué mantiene contento al compiler. Trigger: al crear componentes con estilo, definir el design system o tocar la config/tema.
+---
+
+# Tamagui — el patrón canónico
+
+Componentes con `styled()` y **variants**; estilos por **tokens** de tema (`$`), no por valores hardcodeados. El compiler extrae en build lo que sea estático — el trabajo es no romperlo.
+
+## Cuándo usar este skill
+
+Al crear un componente con estilo, definir tokens/themes del design system, o tocar `createTamagui`.
+
+## Config
+
+```tsx
+import { defaultConfig } from '@tamagui/config/v4'
+import { createTamagui, styled, View } from 'tamagui'
+
+export const config = createTamagui({
+  ...defaultConfig,
+  settings: { ...defaultConfig.settings, styleCompat: 'react-native' },
+})
+declare module 'tamagui' { interface TamaguiCustomConfig extends typeof config {} }
+```
+
+El `declare module` da props tipadas y autocompletado en todo el proyecto. Elige **un solo paquete de import** (`tamagui` o `@tamagui/core`), no ambos.
+
+## styled() + variants (no condicionales inline)
+
+```tsx
+const Box = styled(View, {
+  variants: {
+    tone: { danger: { bg: '$red10' }, ok: { bg: '$green10' } },
+  } as const,
+})
+```
+
+Prefiere variants sobre `bg={isError ? '$red10' : '$green10'}`: los valores runtime rompen el flattening del compiler. Usa `as const` en `variants`.
+
+## Reglas duras
+
+1. **Tokens en props** (`bg="$blue10"`, `p="$4"`, `color="$color"`), nunca `style={{...}}` con variables ni `StyleSheet` de RN (no resuelven tokens).
+2. **No rompas el compiler:** evita valores runtime (`width={w*0.5}`), funciones inline y spreads no deterministas en props de estilo. Muévelos a variants.
+3. **Themes semánticos** (`success`/`warning`/`error`) vía `createThemes`; colorea por contexto con `<Theme name="...">`, no con hex hardcodeado. Al definir el theme, sin `$`; al consumir, con `$`.
+4. **Orden de props = prioridad:** lo que va después de un `{...spread}` gana; en `variants`, la primera listada gana.
+5. **Animaciones:** driver `react-native-reanimated` en native; anima con `enterStyle`/`exitStyle`, `pressStyle`/`hoverStyle` y `AnimatePresence` para salidas.
+6. **Ramifica plataforma con `Adapt`** (Dialog/Sheet), no con `Platform.OS`.
+7. Al envolver un `styled`, usa `.styleable()` para preservar variantes.
+
+## Dev vs prod
+
+`disableExtraction: true` en dev (HMR más rápido); extracción completa en prod. Ignora `.tamagui/` en git.
+
+## Antes de declarar listo
+
+- Estilos por tokens `$`, no hardcodeados ni `style` inline con variables.
+- Lógica condicional de estilo en `variants`, no inline (compiler-friendly).
+- Un solo paquete de import; `declare module` registrado.
+- El quality gate del repo (`qualityGate.fast` en `argos.config.json`) en verde.

package/assets/skills/tanstack-query/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: tanstack-query
+description: Patrones de TanStack Query (React Query) — query keys, mutations, invalidación, staleTime. Trigger: al tocar fetching, cache de servidor o mutaciones de datos remotos.
+---
+
+# TanStack Query — convenciones
+
+## Cuándo usar este skill
+
+Al leer/escribir datos del servidor: un `useQuery`, un `useMutation`, invalidar cache, o paginar. TanStack Query es la fuente de verdad del **estado de servidor** (fetch + cache + revalidación). No lo uses para estado de cliente puro (eso es useState/Redux), ni dupliques su data en otro store.
+
+## El patrón
+
+Query keys estructuradas y centralizadas para invalidar sin strings sueltos:
+
+```ts
+const sessionKeys = {
+  all: ['sessions'] as const,
+  detail: (id: string) => [...sessionKeys.all, id] as const,
+};
+
+const { data, isPending, error } = useQuery({
+  queryKey: sessionKeys.detail(id),
+  queryFn: () => api.getSession(id),
+  staleTime: 30_000,
+  enabled: Boolean(id),
+});
+
+const mutation = useMutation({
+  mutationFn: api.updateSession,
+  onSuccess: () => queryClient.invalidateQueries({ queryKey: sessionKeys.all }),
+});
+```
+
+## Gotchas que muerden
+
+- **Query keys como datos, no strings.** Una factory (`sessionKeys`) evita typos y permite invalidar por prefijo (`sessionKeys.all` invalida todos los detalles).
+- **`staleTime` vs `gcTime`.** `staleTime` decide cuándo refetchea; con `0` (default) refetchea agresivo. Súbelo para data estable y evita parpadeos/llamadas extra.
+- **No espejes la data en useState/Redux.** Lee de `data` directo; copiarla a otro estado crea dos verdades que se desincronizan.
+- **`enabled`** para queries dependientes — no dispares con el id aún `undefined`.
+- **`useQuery` NO tiene `onSuccess`/`onError`/`onSettled`** (v5 los eliminó; solo sobreviven en `useMutation`). Para reaccionar a la data, hazlo en render o con `select`. Es el gotcha #1 al migrar de v4: el callback simplemente nunca corre.
+- **Update optimista completo**: en `onMutate` haz `await queryClient.cancelQueries({ queryKey })` (sin esto, un refetch en vuelo pisa tu update), snapshot con `getQueryData`, aplica con `setQueryData`; restaura el snapshot en `onError`; `invalidateQueries` en `onSettled`.
+- **`isPending` vs `isFetching`**: `isPending` es la primera carga sin data; `isFetching` es cualquier fetch en curso (incluye revalidación). Paginación: `placeholderData: keepPreviousData` (v5 reemplazó `keepPreviousData: true`).
+
+## Reglas duras
+
+1. Estado de servidor vive en Query; no se copia a otro store.
+2. Query keys desde una factory tipada, nunca arrays literales dispersos.
+3. Tras una mutation, invalida las keys afectadas.
+4. `enabled` en queries dependientes; nada de queries con params inválidos.
+5. `staleTime` explícito cuando la data no cambia cada segundo.
+
+## Antes de declarar listo
+
+- Las keys nuevas salen de la factory y se invalidan tras mutar.
+- Ningún dato de query duplicado en useState/Redux.
+- Las queries dependientes usan `enabled`.
+- El quality gate del repo (`qualityGate.fast` en `argos.config.json`) en verde.

package/assets/skills/ticket-intake/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: ticket-intake
+description: Aterrizaje en el repo + pipeline canónico de 8 fases para procesar un ticket (ID, URL o texto pegado) con gates objetivos, en cualquier repo con argos.config.json. Trigger: llega un ticket o una tarea no trivial y hay que auditar, implementar, revisar y abrir el PR.
+---
+
+# ticket-intake — aterrizaje + pipeline de 8 fases
+
+## Cuándo usar este skill
+
+Cuando llega un ticket (ID, URL o texto pegado) y la tarea no es trivial. Orquesta el ciclo encadenando agentes y skills del motor global de Argos con gates objetivos: el contexto que pagas con tokens en una fase queda escrito para la siguiente, sin depender de la memoria del modelo. Los agentes de rol (`ticket-audit`, `explorer`, `implementer`, `reviewer`, las lentes 4R, `commit-pr-pilot`) viven una sola vez en `~/.claude/agents/` y están disponibles en cualquier sesión — pero los hooks globales parametrizados y sus gates automáticos solo disparan dentro de una sesión anclada en la raíz del repo (ver Fase 0).
+
+## Fase 0 — Aterrizaje + Triage
+
+Antes de tocar el ticket, verifica el contexto del repo. No asumas nada de sesiones anteriores.
+
+1. **Sesión anclada**: si el cwd de la sesión está por debajo de la raíz real del repo, Claude Code descubre agentes/skills/hooks solo desde el cwd hacia arriba, nunca hacia abajo — la config que vive en la raíz puede no cargar. Recomienda anclar la sesión en la raíz del repo antes de encarar trabajo no trivial.
+2. **`argos.config.json` presente**: si falta, sugiere correr `argos adopt`. Nunca lo corras unilateralmente — propónlo y espera confirmación explícita del usuario.
+3. **Ficha fresca**: si la ficha del repo (el CLAUDE.md delgado) se ve desactualizada, o el stack/las dependencias del repo divergieron de lo que declara (nueva librería, otro quality gate, otro framework), sugiere `argos adopt --refresh`.
+4. **Repo no clonado**: si el ticket referencia un repo que todavía no existe en esta máquina, primero clónalo respetando las reglas de identidad — el remote debe usar el alias SSH que matchea el workspace correcto (`bonum` / `personal`, según las match rules por remote/path registradas en `~/.argos/workspaces.json`) — y recién ahí corre `argos adopt`.
+5. **Triage propiamente dicho**: `mem_search`, `cat progress/current.md`, `git status`/`git log`. Trivial (≤1 archivo, ≤5 líneas, sin lógica) → salta directo a Fase 5. Si `current.md` no está en `idle` con OTRO ticket, pregunta antes de seguir; nunca dos tickets en paralelo sobre el mismo `current.md`.
+
+**Gate de Fase 0**: no entres al pipeline (Fase 1 en adelante) hasta que 1-3 queden resueltos, o el usuario haya confirmado explícitamente seguir sin ellos a sabiendas de que algún gate automático puede no disparar.
+
+## Pipeline (fases 1–8)
+
+Cada fase escribe en `.claude/progress/` — ruta relativa a la raíz de ESTE repo, nunca al motor global; crea el directorio si no existe. El gate de cada fase es bloqueante.
+
+| Fase | Quién la cubre | Artefacto / Gate |
+|---|---|---|
+| 1 · Context (opc.) | tú: CLI del tracker (`acli` / `jira` / `gh issue view`) | Si solo hay texto pegado, salta a 2 con él. |
+| 2 · AUDIT | agente `ticket-audit` | `audit_<ID>.md`: root cause/approach, archivos, alternativas, preguntas, tasks. **Gate: el usuario lo aprueba.** |
+| 3 · EXPLORE (opc.) | 2-3 agentes `explorer` en un solo mensaje (paralelo real, ver orquestación) | Un `explore_<dim>.md` por dimensión (handler, schema, side-effects, caller, memoria). **Gate: validas que el approach del audit sigue vivo.** |
+| 4 · DESIGN (opc.) | agente `implementer` | Solo si hay patrón o librería nueva: presenta 2-3 approaches con tradeoffs y espera OK explícito. Si no aplica, salta a 5. |
+| 5 · IMPLEMENT | UN agente `implementer` | Lee la ficha del repo (CLAUDE.md delgado) → `audit_<ID>.md` → `explore_*.md` → skill aplicable. Produce `impl_<feature>.md`. **Gate: el quality gate fast del repo — resuelto en runtime desde `qualityGate.fast` en `argos.config.json` o la ficha, nunca un comando asumido — verde en este turno.** |
+| 6 · VERIFY | skill `verify-before-done` (la corre el `implementer`) | `impl_<feature>.md` con "Verify ejecutado en este turno" en exit 0 + smoke del endpoint. Sin evidencia fresca → vuelve a 5. |
+| 7 · REVIEW | agente `reviewer` + skill `review-diff` (+ lentes 4R en paralelo si el diff es de riesgo — ver tabla de perfil en el bloque de orquestación) | `review_<feature>.md`. Two-stage; Stage 1 falla → `CHANGES_REQUESTED`, vuelve a 5 con un `implementer` FRESCO (agente nuevo, no el mismo con el transcript viejo). `APPROVED` → sigue. **Cap: 2 ciclos `CHANGES_REQUESTED` sobre el mismo ticket → escala al usuario en vez de reintentar en loop.** |
+| 8 · PR + CLOSE | agente `commit-pr-pilot` (aplica skill `pr-create`) | Pre-flight del pilot: working tree limpio, no estás en la rama base ni en la `prTarget` del repo (resueltas del `argos.config.json`/ficha), quality gate verde, `gh auth status` ok. PR creado y URL al usuario; luego `mem_save`, entrada en `history.md`, `current.md` a `idle` y `mem_session_summary`. |
+
+## Reglas duras
+
+- **La Fase 2 no se salta en tarea no-trivial** "porque ya entendiste el ticket". El audit es para el `implementer` (y para ti en 3 días); delégalo a `ticket-audit`.
+- **El `implementer` arranca leyendo `audit_<ID>.md`** o pierdes contexto ya pagado con tokens.
+- **El `reviewer` no aprueba sin Stage 1;** la aprobación NO depende del `implementer`.
+- **No hay PR sin `APPROVED`** ni dos tickets en paralelo sobre el mismo `current.md`.
+- **Trivial** = ≤1 archivo, ≤5 líneas, sin lógica.
+- **Sin `argos.config.json` ni ficha**, no asumas un quality gate ni una `prTarget` fija — léelos del repo (o de `package.json`/scripts si ninguno existe) antes de declarar un gate verde, y sugiere `argos adopt` (Fase 0) antes de avanzar.
+
+## Antes de declarar listo
+
+- La Fase 0 corrió: sesión anclada (o advertida), `argos.config.json`/ficha resueltos o el usuario confirmó seguir sin ellos.
+- El ciclo cerró con un PR vía `commit-pr-pilot` (skill `pr-create`) y su URL al usuario; `current.md` en `idle`.
+- Hubo `mem_save` de toda decisión no obvia y `mem_session_summary`.
+- Si fue no-trivial: existen `audit_<ID>.md` aprobado, `impl_<feature>.md` con verify en exit 0 y `review_<feature>.md` en `APPROVED`.
+
+Este skill vive una sola vez en el motor global (`~/.claude/skills/`) y aplica a cualquier repo con `argos.config.json`. Ningún comando de quality gate, rama base/destino o alias de identidad vive hardcodeado aquí: todo se resuelve en runtime leyendo la config o la ficha del repo donde se está trabajando.