argos-harness 0.1.0

package/assets/skills/skill-creator/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: skill-creator
+description: Create LLM-first skills with valid frontmatter. Trigger: new skills, agent instructions, documenting AI usage patterns.
+---
+
+## Activation Contract
+
+Create a skill when:
+- A pattern is used repeatedly and AI needs guidance
+- Project-specific conventions differ from generic best practices
+- Complex workflows need step-by-step instructions
+- Decision trees help AI choose the right approach
+
+Do not create a skill when the pattern is trivial, one-off, or better served by normal documentation.
+
+## Hard Rules
+
+- When working in this repo, first follow `docs/skill-style-guide.md` as the normative source before creating or updating skills.
+- Use `references/skill-style-guide.md` as the bundled local copy of that guide when `docs/skill-style-guide.md` is unavailable.
+- If neither guide is available, use the compact inline rules below.
+- A skill is a runtime instruction contract for an LLM, not human documentation.
+- Do not add a `Keywords` section; preserve essential trigger words in `description`.
+- References must point to local files.
+- Keep the skill body concise: target 180–450 tokens, recommended max 700, hard max 1000.
+
+## Decision Gates
+
+| Need | Action |
+|------|--------|
+| Code templates, schemas, fixtures, generated examples | Put them in `assets/` |
+| Conceptual detail, edge cases, existing docs | Put local links in `references/` |
+| Long explanation in `SKILL.md` | Move it to a supporting file |
+| Multiple meaningful paths | Add a compact decision table |
+
+## Execution Steps
+
+1. Check whether `docs/skill-style-guide.md` exists; if it does, apply it before the bundled local copy or inline fallback rules.
+2. If the repo guide is unavailable, read `references/skill-style-guide.md` and apply it before the inline fallback rules.
+3. Confirm the skill does not already exist and the pattern is reusable.
+4. Create or update `assets/skills/{skill-name}/SKILL.md` using this required structure:
+
+```
+assets/skills/{skill-name}/
+├── SKILL.md              # Required - main skill file
+├── assets/               # Optional - templates, schemas, examples
+│   ├── template.py
+│   └── schema.json
+└── references/           # Optional - links to local docs
+    └── docs.md           # Points to docs/developer-guide/*.mdx
+```
+5. Use this frontmatter shape:
+
+```markdown
+---
+name: {skill-name}
+description: "Trigger: {essential trigger words users or agents will say}. {What this skill does}."
+---
+```
+6. Write sections in this order: Activation Contract, Hard Rules, Decision Gates, Execution Steps, Output Contract, References.
+7. There is no per-repo registration step: skills live once in the global motor (`packages/cli/assets/skills/`) and Argos detects them dynamically. Do not add a registration entry in any repo's `AGENTS.md`.
+
+## Inline Fallback Rules
+
+- `description` MUST be one physical line, quoted, YAML-safe, and include essential trigger words first.
+- `description` SHOULD be <=160 chars and MUST be <=250 chars.
+- Frontmatter MUST include exactly `name` and `description` — no other fields.
+- Use imperative instructions, not tutorials or background prose.
+- Put supporting material in `assets/` or `references/`, not the main skill body.
+
+Good:
+
+```yaml
+description: "Trigger: Jira task, ticket, issue, task creation. Create Jira tasks in the team format."
+```
+
+Bad:
+
+```yaml
+description: >
+  Create Jira tasks in the team format.
+  Trigger: Jira task, ticket, issue, or task creation.
+Keywords: jira, task
+```
+
+## Output Contract
+
+Return:
+- Files created or modified.
+- Whether the repo style guide or inline fallback rules were used.
+- Any supporting files added under `assets/` or `references/`.
+
+## References
+
+- `docs/skill-style-guide.md` — normative LLM-first skill style guide for this repo.
+- `references/skill-style-guide.md` — bundled local copy for the global skill when the repo doc is unavailable.
+
+_Adapted from a skill originally authored by gentleman-programming._

package/assets/skills/skill-creator/assets/SKILL-TEMPLATE.md

@@ -0,0 +1,68 @@
+---
+name: {skill-name}
+description: "Trigger: {essential trigger words users or agents will say}. {What this skill does}."
+---
+
+## Activation Contract
+
+Use this skill when:
+- {Condition 1}
+- {Condition 2}
+- {Condition 3}
+
+---
+
+## Hard Rules
+
+{The MOST important rules - what AI MUST follow}
+
+### Pattern 1: {Name}
+
+```{language}
+{code example}
+```
+
+### Pattern 2: {Name}
+
+```{language}
+{code example}
+```
+
+---
+
+## Decision Gates
+
+```
+{Question 1}? → {Action A}
+{Question 2}? → {Action B}
+Otherwise    → {Default action}
+```
+
+---
+
+## Execution Steps
+
+### Example 1: {Description}
+
+```{language}
+{minimal, focused example}
+```
+
+### Example 2: {Description}
+
+```{language}
+{minimal, focused example}
+```
+
+---
+
+## Output Contract
+
+{What this skill returns when it finishes: files touched, decisions made, anything flagged for human review.}
+
+---
+
+## References
+
+- **Templates**: See [assets/](assets/) for {description of templates}
+- **Documentation**: See [references/](references/) for local developer guide links

package/assets/skills/skill-creator/references/skill-style-guide.md

@@ -0,0 +1,79 @@
+# LLM-first Skill Style Guide
+
+Use this guide when creating or refactoring skills in this repo. A skill is a **runtime instruction contract for an LLM**, not human-facing documentation: it tells the model when to activate, what rules are non-negotiable, how to decide, what to do, and what to return.
+
+## Required Structure
+
+Every `SKILL.md` MUST use this order unless a section is truly irrelevant:
+
+1. **Frontmatter** — complete metadata for skill discovery.
+2. **Activation Contract** — exact situations that load the skill.
+3. **Hard Rules** — constraints the LLM MUST NOT violate.
+4. **Decision Gates** — short tables or bullets for branching choices.
+5. **Execution Steps** — ordered operational workflow.
+6. **Output Contract** — required final format or artifacts.
+7. **References** — local files only; supporting detail lives outside the skill.
+
+`## Compact Rules` is not required. Argos loads the full `SKILL.md` as the source of truth.
+
+## Frontmatter Rules
+
+- `description` MUST be one physical line, YAML-safe, and quoted.
+- Put trigger words first: `"Trigger: ... . {What the skill does}."`
+- `description` SHOULD be <=160 chars and MUST be <=250 chars.
+- Frontmatter has exactly two fields: `name` and `description`. Do not add `license`, `metadata`, `type`, or any other field.
+- Do NOT add a `Keywords` section; discovery uses frontmatter.
+
+## Body Budget
+
+- Target **180–450 tokens** for the skill body.
+- Recommended maximum: **700 tokens**.
+- Hard maximum: **1000 tokens**. Move examples, schemas, and background into `assets/` or `references/`.
+
+## Writing Rules
+
+### DO
+
+- Write imperative runtime instructions: "Load X", "Check Y", "Return Z".
+- Lead with the activation trigger and hard constraints.
+- Use compact tables for decision gates.
+- Keep examples minimal and executable.
+- Link to local supporting files for details.
+
+### DON'T
+
+- Explain history, motivation, or tutorial background.
+- Duplicate long docs inside the skill.
+- Add generic advice the LLM cannot execute.
+- Use external URLs as primary references.
+- Hide critical rules below examples.
+
+## Supporting Files
+
+- Use `assets/` for templates, schemas, fixtures, or generated examples.
+- Use `references/` for local docs that explain concepts or edge cases.
+- Keep references stable and relative to the skill directory when possible.
+
+## Registry Behavior
+
+- Argos indexes the skills automatically by reading the directories under `assets/skills/` — no manual refresh command is needed.
+- Discovery reads `name`, `description` trigger text, and the exact `SKILL.md` path.
+- Delegators pass matching paths to subagents, and subagents read the full skill before work.
+- Use `skill-improver` to audit and refactor existing skills against this guide.
+
+## Quality Gates
+
+- Frontmatter is complete, quoted, single-line, and trigger-preserving.
+- Required sections exist in the expected order.
+- Hard rules are testable or observable.
+- Decision gates cover meaningful forks only.
+- Output contract tells the LLM exactly what to return.
+- References point to local files.
+
+## Refactor Checklist
+
+- [ ] Move explanatory prose to local references.
+- [ ] Collapse repeated rules into one hard rule.
+- [ ] Replace prose branches with a decision table.
+- [ ] Trim examples to the smallest useful case.
+- [ ] Recheck description length and trigger words.

package/assets/skills/skill-improver/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: skill-improver
+description: Audit and upgrade existing LLM-first skills. Trigger: improve skills, audit skills, refactor skills, skill quality.
+---
+
+## Activation Contract
+
+Use this skill when asked to audit, refactor, normalize, or improve existing `SKILL.md` files. Use `skill-creator` instead when creating a brand-new skill from a reusable pattern.
+
+## Hard Rules
+
+- Treat `docs/skill-style-guide.md` as the normative style contract when it exists.
+- Use `references/skill-style-guide.md` as the bundled local copy when `docs/skill-style-guide.md` is unavailable.
+- Treat `SKILL.md` as the source of truth; preserve author intent, critical rules, activation semantics, and output requirements.
+- Default to audit-only. Modify files only when the user explicitly asks to apply improvements.
+- Never delete meaningful content silently; move long explanation, examples, templates, or schemas into local `references/` or `assets/`.
+- Do not invent triggers, policies, or domain rules. Mark ambiguous cases for human review.
+
+## Decision Gates
+
+| Situation | Action |
+| --- | --- |
+| Missing or invalid frontmatter | Fix `name` and quoted one-line `description` — the only two allowed fields |
+| Skill reads like tutorial docs | Convert to runtime instructions and move background to `references/` |
+| Body exceeds budget | Preserve rules, move examples/background to supporting files |
+| Branching logic hidden in prose | Convert to a compact decision table |
+| Rules conflict or intent is unclear | Report the issue; do not rewrite that rule automatically |
+
+## Execution Steps
+
+1. Read `docs/skill-style-guide.md`; if unavailable, read `references/skill-style-guide.md`; if neither exists, enforce the core LLM-first structure: frontmatter, Activation Contract, Hard Rules, Decision Gates, Execution Steps, Output Contract, References.
+2. Scan the skill directories under `assets/skills/` for `*/SKILL.md` to select skills to audit.
+3. For each selected skill, audit frontmatter, trigger clarity, section order, body budget, actionability, decision gates, output contract, and local references.
+4. Return an audit report grouped by skill with severity and exact proposed changes.
+5. In apply mode, edit only safe issues, preserve content, and create supporting files when needed. There is no per-repo registration or refresh step to run afterward: skills live once in the global motor and Argos detects them dynamically.
+
+## Output Contract
+
+Return:
+- Skills audited and paths used.
+- Issues found, grouped by severity.
+- Files changed, if apply mode was requested.
+- Ambiguities that need human review.
+
+## References
+
+- `docs/skill-style-guide.md` — normative LLM-first skill style guide for this repo.
+- `references/skill-style-guide.md` — bundled local copy for the global skill when the repo doc is unavailable.
+
+_Adapted from a skill originally authored by gentleman-programming._

package/assets/skills/skill-improver/references/skill-style-guide.md

@@ -0,0 +1,79 @@
+# LLM-first Skill Style Guide
+
+Use this guide when creating or refactoring skills in this repo. A skill is a **runtime instruction contract for an LLM**, not human-facing documentation: it tells the model when to activate, what rules are non-negotiable, how to decide, what to do, and what to return.
+
+## Required Structure
+
+Every `SKILL.md` MUST use this order unless a section is truly irrelevant:
+
+1. **Frontmatter** — complete metadata for skill discovery.
+2. **Activation Contract** — exact situations that load the skill.
+3. **Hard Rules** — constraints the LLM MUST NOT violate.
+4. **Decision Gates** — short tables or bullets for branching choices.
+5. **Execution Steps** — ordered operational workflow.
+6. **Output Contract** — required final format or artifacts.
+7. **References** — local files only; supporting detail lives outside the skill.
+
+`## Compact Rules` is not required. Argos loads the full `SKILL.md` as the source of truth.
+
+## Frontmatter Rules
+
+- `description` MUST be one physical line, YAML-safe, and quoted.
+- Put trigger words first: `"Trigger: ... . {What the skill does}."`
+- `description` SHOULD be <=160 chars and MUST be <=250 chars.
+- Frontmatter has exactly two fields: `name` and `description`. Do not add `license`, `metadata`, `type`, or any other field.
+- Do NOT add a `Keywords` section; discovery uses frontmatter.
+
+## Body Budget
+
+- Target **180–450 tokens** for the skill body.
+- Recommended maximum: **700 tokens**.
+- Hard maximum: **1000 tokens**. Move examples, schemas, and background into `assets/` or `references/`.
+
+## Writing Rules
+
+### DO
+
+- Write imperative runtime instructions: "Load X", "Check Y", "Return Z".
+- Lead with the activation trigger and hard constraints.
+- Use compact tables for decision gates.
+- Keep examples minimal and executable.
+- Link to local supporting files for details.
+
+### DON'T
+
+- Explain history, motivation, or tutorial background.
+- Duplicate long docs inside the skill.
+- Add generic advice the LLM cannot execute.
+- Use external URLs as primary references.
+- Hide critical rules below examples.
+
+## Supporting Files
+
+- Use `assets/` for templates, schemas, fixtures, or generated examples.
+- Use `references/` for local docs that explain concepts or edge cases.
+- Keep references stable and relative to the skill directory when possible.
+
+## Registry Behavior
+
+- Argos indexes the skills automatically by reading the directories under `assets/skills/` — no manual refresh command is needed.
+- Discovery reads `name`, `description` trigger text, and the exact `SKILL.md` path.
+- Delegators pass matching paths to subagents, and subagents read the full skill before work.
+- Use `skill-improver` to audit and refactor existing skills against this guide.
+
+## Quality Gates
+
+- Frontmatter is complete, quoted, single-line, and trigger-preserving.
+- Required sections exist in the expected order.
+- Hard rules are testable or observable.
+- Decision gates cover meaningful forks only.
+- Output contract tells the LLM exactly what to return.
+- References point to local files.
+
+## Refactor Checklist
+
+- [ ] Move explanatory prose to local references.
+- [ ] Collapse repeated rules into one hard rule.
+- [ ] Replace prose branches with a decision table.
+- [ ] Trim examples to the smallest useful case.
+- [ ] Recheck description length and trigger words.

package/assets/skills/socketio/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: socketio
+description: Patrones de Socket.IO en un servicio Node — namespaces, rooms, auth en el handshake, eventos tipados, cleanup. Trigger: al tocar realtime, gateways o handlers de socket.
+---
+
+# Socket.IO — convenciones del servicio
+
+## Cuándo usar este skill
+
+Al agregar o tocar realtime: un namespace, un evento, autenticación de conexión, o broadcast a un room. Socket.IO sobre el HTTP server de Express. La regla base: el handler de socket es una capa de transporte, no de negocio — delega al mismo service/controller que usan las rutas HTTP.
+
+## El patrón
+
+```ts
+io.of('/sessions').use(authSocket).on('connection', (socket) => {
+  socket.join(`session:${socket.data.sessionId}`);
+
+  socket.on('message:send', async (dto, ack) => {
+    try {
+      const saved = await messageService.create(socket.data.userId, dto);
+      io.to(`session:${socket.data.sessionId}`).emit('message:new', saved); // room de socket.data, no del payload
+      ack?.({ ok: true, id: saved._id });
+    } catch (err) {
+      ack?.({ ok: false, error: toClientError(err) });
+    }
+  });
+
+  socket.on('disconnect', () => { /* cleanup timers/subscriptions */ });
+});
+```
+
+`authSocket` valida el token en `socket.handshake.auth.token` y rellena `socket.data` (userId/sessionId). Nunca confíes en un id que venga en el payload del evento sin cruzarlo contra `socket.data`.
+
+## Gotchas que muerden
+
+- **Rooms, no broadcast global.** `io.emit` manda a todos los conectados; usa `io.to(room)` / `socket.to(room)` para no filtrar datos entre sesiones/tenants.
+- **`socket.emit` vs `io.to(...).emit`.** `socket.emit` responde solo al emisor; para incluirte y al resto del room usa `io.to(room)`, para excluirte usa `socket.to(room)`.
+- **Listeners colgados.** Toda suscripción/intervalo creado en `connection` se limpia en `disconnect`, o se filtra memoria.
+- **Errores.** Un throw dentro de un handler no llega al cliente: reporta vía el callback `ack` o un evento `error:*`, nunca dejes la promesa sin catch.
+- **Auth en el handshake**, no por evento — rechaza en el middleware `.use()` antes de `connection`.
+- **Tipa el `Server`/`Socket`** con las 4 interfaces (`Server<ClientToServerEvents, ServerToClientEvents, InterServerEvents, SocketData>`): autocompletado y type-check de payloads y acks. `socket.data` se tipa vía `SocketData`, no `any`.
+- **Multi-instancia ⇒ adapter (Redis) + sticky sessions.** Sin adapter, `io.to(room)` solo alcanza a los sockets de **este** proceso (broadcasts perdidos al escalar); sin sticky, el long-polling da "Session ID unknown".
+- **Acks que esperan respuesta usan timeout**: `socket.timeout(ms).emitWithAck(...)`. Sin timeout, un ack ausente cuelga/leakea.
+
+## Reglas duras
+
+1. El handler delega al service; nada de queries ni lógica de negocio inline.
+2. Identidad desde `socket.data` (poblado en auth), nunca desde el payload.
+3. Emite a un room específico; `io.emit` global solo para health/system.
+4. Cada `on(...)` con efectos secundarios tiene su cleanup en `disconnect`.
+5. Errores al cliente vía `ack`/evento `error`, con el mismo `ApiError` mapeado que HTTP.
+
+## Antes de declarar listo
+
+- Los eventos nuevos validan su input igual que un endpoint HTTP.
+- Ningún `io.emit` global salvo señales de sistema; el resto va por room.
+- Auth resuelta en el middleware del namespace, no dentro de los handlers.
+- El quality gate del repo (`qualityGate.fast` en `argos.config.json`) en verde.

package/assets/skills/spec-bootstrap/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: spec-bootstrap
+description: Scaffoldea un spec SDD completo (requirements/design/tasks) con EARS y trazabilidad R<n>↔test. Trigger: arrancar una feature de alcance real, spec SDD, requirements/design/tasks, EARS, antes de escribir código.
+---
+
+# spec-bootstrap — arranque de un spec SDD
+
+## Cuándo usar este skill
+
+Al iniciar trabajo SDD-scope (feature nueva completa, cambios en auth/seguridad/datos sensibles, scope > ~2 días — ver el bloque **Spec Driven Development** en `CLAUDE.md`). No lo uses para bugfixes, ajustes de UI o refactors aislados: esos van directo.
+
+Produce `requirements.md`, `design.md` y `tasks.md` en el directorio de specs del repo (definido en la ficha del repo — CLAUDE.md — o en `argos.config.json`), listos para que el orquestador los descomponga. El scaffolding lo hace el agente principal (o el `researcher`), no un subagente que nestee.
+
+## Orden
+
+1. **requirements.md primero.** Sin requisitos claros no hay diseño. Deriva del ticket/pedido; cada requisito es EARS con id `R<n>`.
+2. **design.md** — cómo cumplir esos `R<n>`: componentes afectados, contratos, decisiones y trade-offs. Referencia los `R<n>` que cada decisión satisface.
+3. **tasks.md** — lotes de 1-3 tasks; cada task lista los `R<n>` que cubre y su(s) test(s).
+
+## Plantillas
+
+`requirements.md`:
+```md
+# <Feature> — Requirements
+
+## Contexto
+<1-2 líneas: qué problema resuelve y para quién.>
+
+## Requisitos (EARS)
+- **R1** — El sistema DEBE <acción observable>.
+- **R2** — CUANDO <evento>, el sistema DEBE <acción>.
+- **R3** — SI <condición no deseada> ENTONCES el sistema DEBE <acción de contención>.
+```
+
+`design.md`:
+```md
+# <Feature> — Design
+
+## Enfoque
+<Arquitectura elegida y por qué. Trade-offs descartados.>
+
+## Componentes
+- <archivo/módulo> — <responsabilidad> — cubre R<n>.
+
+## Decisiones
+- <decisión no obvia> — <razón>.
+```
+
+`tasks.md`:
+```md
+# <Feature> — Tasks
+
+- [ ] **T1** (R1, R2) — <qué se implementa> · test: <archivo>::<caso> con `// Covers: R1, R2`
+- [ ] **T2** (R3) — <qué se implementa> · test: <archivo>::<caso> con `// Covers: R3`
+```
+
+## Reglas duras
+
+- **Cero placeholders sin resolver.** No dejes `<...>` en el spec final; si no sabes un dato, es una pregunta al usuario, no un hueco.
+- **Todo `R<n>` termina en ≥1 task y ≥1 test.** Un requisito sin task ni test no es trazable → no entra al spec.
+- **El tracking vive en `tasks.md`, no en herramientas de tareas efímeras/externas.** Ver el bloque SDD.
+- **Self-review antes de cerrar el scaffolding:** ¿cada `R<n>` es una sola acción testeable? ¿cada task apunta a `R<n>` reales? ¿el design cubre todos los `R<n>`? Si algo falla, corrígelo antes de pasar el spec a quien coordine la feature.

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

@@ -0,0 +1,52 @@
+---
+name: store-ship
+description: Trigger: store deploy, publish app, App Store, Play Store, eas submit, store metadata, store screenshots, subir a tiendas, publicar app. Automate store submission for Expo apps: EAS build/submit, metadata as code, Maestro screenshots.
+---
+
+# Store Ship
+
+## Activation Contract
+
+Activate when an Expo/React Native app must be built, prepared, or submitted to the App Store / Play Store: metadata, screenshots, builds, or the whole pipeline. Also the Phase 10 executor of `app-builder`.
+
+## Hard Rules
+
+- All store artifacts live in the repo under `store/` — metadata and screenshots are code, never console-only state.
+- Derive ALL copy (title, subtitle, description, keywords) from `docs/product-definition.md`; never invent product claims. Respect limits: iOS subtitle/keywords 30/100 chars, Play title/short/full 30/80/4000 chars.
+- Never store credentials in the repo: Apple App Store Connect API key and Play service-account JSON go in env/EAS secrets; `store/` must be committable. Maestro flows must never hardcode credentials either, even local seed ones — inject with `${VAR}` and `maestro test -e KEY=value`, with the run command in the flow header comment. Same rule for the `store.config.json` demo password: inject→push→revert→verify, never committed — `references/pipeline.md` §6.
+- Do not claim full automation of one-time console steps (App Privacy questionnaire, content rating, first Play AAB upload) — surface them as a manual checklist instead.
+- Screenshots come from real app runs (Maestro on simulator/emulator with seeded demo data), not mockups.
+
+## Decision Gates
+
+| Situation | Route |
+|---|---|
+| Expo managed app | EAS: `eas build` + `eas submit` + `eas metadata` (iOS) |
+| Bare RN / non-Expo | fastlane (`deliver`/`supply`/`snapshot`) — same `store/` layout |
+| Play metadata (eas metadata is iOS-only) | fastlane `supply` structure in `store/android/`, uploaded via fastlane or console paste |
+| First-ever Play submission | Manual AAB upload in Play Console (Google requirement), then `eas submit` for updates |
+| Tablet screenshots | Only if `supportsTablet` (iPad) / tablet layouts exist (Play) |
+| EAS submit queue busy / need local, queue-free iOS upload | `xcrun altool --upload-app`, Transporter, or `fastlane pilot upload` with the team's own ASC API key — see "Queue-free local submission" in `references/pipeline.md` §6 |
+
+## Execution Steps
+
+1. Read `references/pipeline.md`; check prereqs incl. EAS env vars (Phase 8).
+2. Scaffold `store/` and `eas.json` from `assets/` templates; fill submit profiles.
+3. Author metadata from the product definition: `store/store.config.json` (iOS) + `store/android/` supply tree; push once for text fields (no screenshots/password yet).
+4. One-time ASC manual fixes for API-created apps: 1.0 version, primary language, copyright, pricing, content rights — pipeline §4.
+5. Screenshots: seed demo data, write Maestro flows from `assets/maestro-flow.template.yaml`, run the device matrix, output to `store/screenshots/{platform}/{device}/`.
+6. Build + submit: `eas build --profile production`, `eas submit` (queue) or the queue-free local path; verify TestFlight / Play internal track.
+7. Final metadata push: real screenshots + demo password inject → push → revert → `rg`-verify — pipeline §6.
+8. Print the manual-steps checklist and persist the run outcome (engram or decision log).
+
+## Output Contract
+
+Return: files created under `store/`, commands run with results, screenshot inventory per device, the final metadata push result, and the remaining manual checklist. Never report "submitted" without the `eas submit` output.
+
+## References
+
+- `references/pipeline.md` — full runbook: prereqs, eas.json profiles, metadata fields/limits, device matrix, seeding, troubleshooting.
+- `assets/eas.template.json` — build+submit profiles.
+- `assets/store.config.template.json` — iOS metadata as code.
+- `assets/maestro-flow.template.yaml` — screenshot flow pattern.
+- `assets/android-supply.template.md` — Play metadata tree.

package/assets/skills/store-ship/assets/android-supply.template.md

@@ -0,0 +1,22 @@
+# Play supply tree template
+
+`eas metadata` is iOS-only. Keep Play metadata in the fastlane `supply` layout so it
+uploads with fastlane when available and stays diff-able either way:
+
+```
+store/android/metadata/
+└── es-MX/                       # primary locale = app UI language
+    ├── title.txt                # max 30 chars
+    ├── short_description.txt    # max 80 chars — the search-result hook
+    ├── full_description.txt     # max 4000 chars — derive from product definition
+    ├── video.txt                # optional YouTube URL, else empty
+    └── images/
+        ├── icon.png             # 512x512
+        ├── featureGraphic.png   # 1024x500 — required for store listing
+        ├── phoneScreenshots/    # 2–8, ≥1080px wide, from the Maestro run
+        ├── sevenInchScreenshots/   # only if tablet UI exists
+        └── tenInchScreenshots/     # only if tablet UI exists
+```
+
+Upload: `fastlane supply --metadata_path store/android/metadata --skip_upload_apk true --skip_upload_aab true`
+(first release: paste manually in Play Console; the repo copy remains the source of truth).

package/assets/skills/store-ship/assets/eas.template.json

@@ -0,0 +1,32 @@
+{
+  "cli": {
+    "version": ">= 13.0.0",
+    "appVersionSource": "remote"
+  },
+  "build": {
+    "development": {
+      "developmentClient": true,
+      "distribution": "internal",
+      "environment": "development"
+    },
+    "preview": {
+      "distribution": "internal",
+      "channel": "preview",
+      "environment": "preview"
+    },
+    "production": {
+      "autoIncrement": true,
+      "channel": "production",
+      "environment": "production"
+    }
+  },
+  "submit": {
+    "production": {
+      "ios": {},
+      "android": {
+        "serviceAccountKeyPath": "../secrets/play-service-account.json",
+        "track": "internal"
+      }
+    }
+  }
+}

package/assets/skills/store-ship/assets/maestro-flow.template.yaml

@@ -0,0 +1,27 @@
+# Screenshot flow — one per screenshot set. Run against a seeded demo account
+# on the device matrix in references/pipeline.md (never Expo Go).
+# Never hardcode credentials, even local seed ones — inject via -e:
+# maestro test store/flows/screenshots.yaml -e DEMO_PASSWORD=your-local-seed-password
+appId: com.example.app
+---
+- launchApp:
+    clearState: true
+# Launch-transition chrome can still be on screen right after launchApp —
+# wait before the app is considered ready, and again before any screenshot.
+- waitForAnimationToEnd
+- assertVisible: "LOGIN_SCREEN_MARKER"
+- tapOn: "EMAIL_FIELD_HINT"
+- inputText: "demo@example.com"
+- tapOn: "PASSWORD_FIELD_HINT"
+- inputText: "${DEMO_PASSWORD}"
+- tapOn: "LOGIN_CTA"
+- waitForAnimationToEnd
+# 1 — signature screen first: it becomes the store card image
+- takeScreenshot: store/screenshots/tmp/01-signature
+# 2..N — core loop, then differentiators
+- tapOn: "TAB_2"
+- waitForAnimationToEnd
+- takeScreenshot: store/screenshots/tmp/02-core-loop
+- tapOn: "TAB_3"
+- waitForAnimationToEnd
+- takeScreenshot: store/screenshots/tmp/03-differentiator

package/assets/skills/store-ship/assets/store.config.template.json

@@ -0,0 +1,28 @@
+{
+  "configVersion": 0,
+  "apple": {
+    "info": {
+      "es-MX": {
+        "title": "APP_NAME_MAX_30",
+        "subtitle": "VALUE_PROMISE_MAX_30",
+        "description": "FULL_DESCRIPTION_MAX_4000\n\nDerive from docs/product-definition.md: core promise first, then features as user benefits.",
+        "keywords": ["domain", "nouns", "users", "search", "max-100-chars-total"],
+        "promoText": "PROMO_MAX_170_EDITABLE_WITHOUT_NEW_BUILD",
+        "marketingUrl": "https://example.com",
+        "supportUrl": "https://example.com/support",
+        "privacyPolicyUrl": "https://example.com/privacy"
+      }
+    },
+    "categories": ["PRIMARY_CATEGORY"],
+    "review": {
+      "firstName": "REVIEWER_CONTACT_FIRST",
+      "lastName": "REVIEWER_CONTACT_LAST",
+      "email": "contact@example.com",
+      "phone": "+521234567890",
+      "demoUsername": "demo@example.com",
+      "demoPassword": "SET_VIA_SECRET_BEFORE_PUSH",
+      "demoRequired": true,
+      "notes": "Accounts are admin-created; use the demo login above."
+    }
+  }
+}