# Shipping Artifacts

> Conjunto de documentación que hace revisable una app construida con IA antes de lanzarla: arquitectura, flujos de usuario/permisos, permisos, variables/secretos y cobertura de tests, más docs condicionales.

Fuente: https://skillsagentes.com/skills/phuryn/pm-skills/shipping-artifacts
Markdown: https://skillsagentes.com/skills/phuryn/pm-skills/shipping-artifacts.md

Repositorio: https://github.com/phuryn/pm-skills
Autor: phuryn
Licencia: MIT
Actualizado: el mes pasado
Coste de contexto: 146 tok instalada, 2.2k tok al activarse, 2.2k tok con todos los archivos del bundle
Bundle: 1 archivo, 9 KB
Permisos que pide: ninguno declarado

## Instalación

Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina.

```bash
# Claude Code
npx -y skills add phuryn/pm-skills --skill shipping-artifacts --agent claude-code
# Cursor
npx -y skills add phuryn/pm-skills --skill shipping-artifacts --agent cursor
# Codex
npx -y skills add phuryn/pm-skills --skill shipping-artifacts --agent codex
# Gemini CLI
npx -y skills add phuryn/pm-skills --skill shipping-artifacts --agent gemini
# Windsurf
npx -y skills add phuryn/pm-skills --skill shipping-artifacts --agent windsurf
# Cline
npx -y skills add phuryn/pm-skills --skill shipping-artifacts --agent cline
```

## Qué hace

- Define el núcleo de documentos que toda app revisable necesita: architecture.md, flows.md, permissions.md, variables.md y tests.md
- Añade documentos condicionales solo cuando aplican: emails.md, cron.md, seo.md y automation.md
- Especifica qué debe capturar cada documento y cómo lo usa un revisor o auditor
- Indica que tests.md lo produce /derive-tests, mientras el resto los produce /document-app

## Cuándo usarla

- Documentar una base de código para el traspaso (handoff)
- Mapear los recorridos de usuario y los cruces de límites de confianza
- Planificar la cobertura de tests
- Prepararse para una auditoría de seguridad o rendimiento

## Qué la activa

- "Documenta esta app para el handoff"
- "Mapea los flujos de usuario y permisos de este proyecto"
- "Prepara la documentación para una auditoría de seguridad"

## Archivos

- SKILL.md — 9 KB

## SKILL.md

Reproducido tal cual desde phuryn/pm-skills bajo MIT. Esta sección es el documento original y está en inglés.

# Shipping Artifacts: The Docs That Make AI-Built Code Reviewable

## Purpose

AI agents write code fast, but they leave no durable record of *intent* — what the system is supposed to do, who is allowed to do what, where the secrets live, which rules are actually verified. Without that record, no human (and no auditing agent) can tell whether the code is safe to ship. This skill defines the small set of documents that restore reviewability.

These docs live in `documentation/` at the repo root and are written for two readers: a human reviewer and the next AI coding agent. They are the **intended-state** half of every later audit — a security or performance review is only as good as the intent it can compare the code against.

## How the set is organized

The set is **not** a fixed list — it is a small **core** plus **conditional** docs you add only when the capability exists.

- **Core docs** — every reviewable app has these surfaces, so always produce them.
- **Conditional docs** — include one only if the app actually has that capability. If it doesn't, write a single line in `architecture.md` ("No scheduled work — no `cron.md`.") rather than inventing an empty document. Reviewability comes from an honest map, and "we don't do X" is part of the map.
- Most docs are reverse-engineered from code by `/document-app`. The one exception is `tests.md`, which is *derived from the other docs* by `/derive-tests` — it is the verification map, not a description of a subsystem.

Be brutally honest about the current state without being paranoid. The job is an accurate map, not a clean bill of health. Each doc is short, table-and-bullet heavy, and skips generic theory.

## Core documents

Each entry: file · one-line purpose · what it must capture · how a reviewer uses it.

1. **`architecture.md`** — what the system is and how it hangs together.
   - Must capture: product overview + key assumptions; tech stack; how auth/sessions/claims flow end to end; the trust boundaries (e.g. service-role vs. client); a short **Known risks / assumptions** list (each entry backed by where it shows up in the code, not a generic checklist); a "Related Documents" index of every other doc produced.
   - Reviewer use: the root document — everything else is cross-referenced from here.

2. **`flows.md`** — the journeys where permissions and side effects are actually exercised.
   - Must capture: each load-bearing flow as actor + precondition + success outcome; the step-by-step sequence across UI → server → data → jobs → providers → agents; the **authz check at each protected step** (which claim/role/scope, on which resource, and the expected *deny* case); the **trust-boundary crossings** (browser→server, server→provider, job→app, agent→tool, webhook→app); the state changes and side effects each step causes (writes, emails queued, jobs triggered, outbound calls).
   - Reviewer use: the runtime view a static `permissions.md` matrix can't show — *where* and *in what order* authorization is enforced, and where it can be skipped.
   - **Anti-PRD rule:** a flow that doesn't touch permissions, data integrity, external side effects, money, privacy, or operational safety does not belong here. This is a security/operations map, not a feature spec.

3. **`permissions.md`** — who is allowed to do what.
   - Must capture: roles/claims; where scope is derived (token vs. DB); a resource × operation × role matrix; which tables have row-level security and which rely on code-enforced checks.
   - Reviewer use: the baseline an access-control audit compares the code against. `flows.md` shows it in motion; this is the static reference.

4. **`variables.md`** — configuration and secrets, mapped to risk.
   - Must capture: a table of Name · used-by · scope (server/client) · source · rotation · risk; explicit confirmation that no secret is bundled client-side; a pre-go-live checklist.
   - Reviewer use: the secrets/PII-leak surface and the rotation plan during incident response.

5. **`tests.md`** — the verification map: which documented rules are actually checked, which are only proposed, and which are checked by nothing.
   - Must capture, in three clearly separated sections so the map can't read falsely green:
     - **Existing coverage** — tests that are in the repo *today*, each tied to the rule it pins (so the map reflects reality, not a wish-list).
     - **Proposed tests** — recommended cases not yet written, marked by **test type** (automated unit/integration · guarded live · manual review).
     - **Gaps** — documented rules with no verification at all, ranked by what crossing them exposes.
   - Each row carries: use-case → rule → expected behavior (including the deny/negative case) → evidence source (doc + code) → status (existing / proposed / none). It also notes which checks are CI-required and gate merges to `main`.
   - Reviewer use: the operational form of "documented == implemented" — it shows whether each rule the other docs claim is actually pinned by a test today, only proposed, or unverified.
   - Produced by `/derive-tests` (not `/document-app`), because it is derived from the other docs and the existing test suite rather than read off a subsystem.

## Conditional documents (include only when the capability exists)

6. **`emails.md`** — every notification the system sends. *Include only if the app sends transactional or automated email.*
   - Must capture: the queue → processor → provider path; templates and the variables they accept; retry/backoff behavior; where to look when a send fails.
   - Reviewer use: spotting unvalidated template inputs and PII exposure boundaries.

7. **`cron.md`** — all scheduled work and how to operate it safely. *Include only if scheduled or background jobs exist.*
   - Must capture: an inventory table (job → schedule → function → secrets → limits → retry); how each job stays idempotent; how internal calls authenticate; where to see last runs.
   - Reviewer use: finding forgeable triggers and unbounded background jobs.

8. **`seo.md`** — how a single-page app handles SEO and social previews. *Include only if there are public/indexable or bot-facing routes.*
   - Must capture: the preview approach (static meta / prerender / edge HTML); a route → needs-SEO → public-data-only table; how dynamic metadata is sanitized; bot-vs-human routing.
   - Reviewer use: catching public-data-only violations and metadata injection on bot routes.

9. **`automation.md`** — embedded agents and other automation paths. *Include only if the app embeds AI agents, LLM workflows, tool-calling, webhooks, or external automation.*
   - Must capture, per automation/agent: trigger + owner + whether it runs automatically or only after approval; the inputs it may read and the **exact tools/APIs it may call** (the tool surface is itself a hard guardrail); where **steering** lives (the prompt) vs. the **non-prompt hard guardrails**; the **output contract** back to the app (schema, validation, failure handling); **app-owned side effects vs. agent-owned suggestions**; and the controls — approval gates, audit/timeline logging, rate limits, retries, kill switch.
   - Reviewer use: makes hidden automation paths visible and draws the line between what an agent *proposes* and what the app *enforces* — the highest-risk surface in modern AI-built apps.

## Notes

- Each produced doc adds a reference to itself in `architecture.md` under a "Related Documents" section, so the set stays discoverable.
- Skip any conditional document that doesn't apply, and say so in one line rather than inventing content.
- Keep examples and finished templates out of these docs — they describe *this* system, not the general method.
- The agent operating-context file (`CLAUDE.md` / `AGENTS.md`) is a *different* artifact — instructions derived from these docs, not system documentation. It is produced at the handoff step by `/ship-check`, not here.
- `tests.md` is produced by `/derive-tests`; the rest are produced by `/document-app`.
- Do not include an "updated date" line; the file's history is the source of truth.

## Dónde encaja

- Categoría: [Documentos](https://skillsagentes.com/categorias/documentos.md) — Lee, escribe y transforma archivos PDF, DOCX, XLSX y PPTX.
- Creador: [phuryn](https://skillsagentes.com/creators/phuryn.md) — 0 skills en el directorio
- [Todas las skills](https://skillsagentes.com/skills.md)
- [Ranking de instalaciones](https://skillsagentes.com/ranking.md)

## Otras skills del mismo repositorio

- [Intended Vs Implemented](https://skillsagentes.com/skills/phuryn/pm-skills/intended-vs-implemented.md): Método para encontrar la brecha entre lo que un sistema debería hacer y lo que el código realmente hace, el tipo de bug que los escáneres genéricos no ven por falta de un modelo de intención.
- [Strategy Red Team](https://skillsagentes.com/skills/phuryn/pm-skills/strategy-red-team.md): Hace de red-team de un PRD, roadmap o estrategia: ataca sus supuestos críticos antes de que lo haga la realidad. Defiende y ataca cada afirmación, prioriza por impacto x probabilidad x coste y da el test más barato.
- [Swot Analysis](https://skillsagentes.com/skills/phuryn/pm-skills/swot-analysis.md): Realiza un análisis DAFO detallado (fortalezas, debilidades, oportunidades y amenazas) con recomendaciones accionables.
- [Value Proposition](https://skillsagentes.com/skills/phuryn/pm-skills/value-proposition.md): Diseña una propuesta de valor detallada con una plantilla JTBD de 6 partes (Who, Why, What before, How, What after, Alternatives) para crear o articular por qué elegir tu producto.
- [Cohort Analysis](https://skillsagentes.com/skills/phuryn/pm-skills/cohort-analysis.md): Realiza análisis de cohortes sobre datos de engagement de usuarios: curvas de retención, tendencias de adopción de funcionalidades e insights a nivel de segmento.

---

Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)