# How the shipping-artifacts Skill Documents Vibe-Coded Applications for Review > Learn how the shipping-artifacts skill automatically documents vibe-coded applications with architecture, flows, permissions, variables, and test files, simplifying review processes. - Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills) - Tags: how-to-guide - Published: 2026-06-16 --- **The shipping-artifacts skill generates five mandatory documentation files—[`architecture.md`](https://github.com/phuryn/pm-skills/blob/main/architecture.md), [`flows.md`](https://github.com/phuryn/pm-skills/blob/main/flows.md), [`permissions.md`](https://github.com/phuryn/pm-skills/blob/main/permissions.md), [`variables.md`](https://github.com/phuryn/pm-skills/blob/main/variables.md), and [`tests.md`](https://github.com/phuryn/pm-skills/blob/main/tests.md)—plus conditional add-ons, transforming AI-generated code into reviewable artifacts with explicit security boundaries and test coverage maps.** The `phuryn/pm-skills` repository provides structured skills for AI-assisted project management, with the **shipping-artifacts** skill specifically designed to solve the documentation gap in "vibe-coded" (AI-generated) applications. This skill enforces a reproducible documentation standard that captures system architecture, security boundaries, and verification requirements essential for human review. ## Mandatory Core Documentation Set The skill definition in [`pm-ai-shipping/skills/shipping-artifacts/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/skills/shipping-artifacts/SKILL.md) mandates five foundational documents that every vibe-coded application must produce. These files establish the single source of truth for reviewers. ### architecture.md This file provides the high-level system overview including the tech stack, authentication flow, trust boundaries, and a "known risks" table. It serves as the entry point for reviewers and indexes related documentation. ### flows.md Documents step-by-step, permission-aware user journeys. Each flow explicitly shows where authentication checks occur, where side-effects trigger, and where trust boundaries are crossed. ### permissions.md Contains the roles and claims matrix alongside any row-level security rules governing data access. ### variables.md Inventory table of configuration values and secrets, documenting their scope, source, rotation plan, and risk rating. ### tests.md Generated by the `/derive-tests` command (defined in [`pm-ai-shipping/commands/derive-tests.md`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/commands/derive-tests.md)), this verification map links each documented rule to existing tests, proposed tests, and uncovered gaps. ## Conditional Documentation for Optional Capabilities The skill dynamically adds documentation only when specific capabilities exist in the codebase. When a capability is absent, the generator inserts a single "No X" line in [`architecture.md`](https://github.com/phuryn/pm-skills/blob/main/architecture.md) to maintain documentation honesty. ### emails.md Required when the application implements notification pipelines. Documents templates, retry logic, and failure handling. ### cron.md Required for scheduled jobs. Covers idempotency guarantees, execution frequency, and secret usage patterns. ### seo.md Documents SEO and metadata handling for public-facing routes. ### automation.md Required for embedded AI agents or LLM workflows. Details webhooks, guardrails, and automation boundaries. ## Workflow Commands and Usage The skill integrates into the AI-shipping kit through specific slash commands defined in the repository's command definitions. To generate the complete documentation set: ```bash /pm-ai-shipping:document-app ``` This command reverse-engineers the codebase to populate the core and conditional documentation files. To build the test coverage map: ```bash /pm-ai-shipping:derive-tests ``` For the complete pipeline including audits: ```bash /pm-ai-shipping:ship-check ``` These commands are documented in [`pm-ai-shipping/commands/document-app.md`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/commands/document-app.md), [`pm-ai-shipping/commands/derive-tests.md`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/commands/derive-tests.md), and [`pm-ai-shipping/commands/ship-check.md`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/commands/ship-check.md) respectively. ## Verification Through Intended-State Audits After documentation generation, the companion **intended-vs-implemented** skill compares the documented state against the actual codebase. This audit surfaces gaps that static scanners miss because they lack an intent model, ensuring the documentation accurately reflects deployed logic. ## Summary - The **shipping-artifacts** skill enforces five mandatory documentation files: [`architecture.md`](https://github.com/phuryn/pm-skills/blob/main/architecture.md), [`flows.md`](https://github.com/phuryn/pm-skills/blob/main/flows.md), [`permissions.md`](https://github.com/phuryn/pm-skills/blob/main/permissions.md), [`variables.md`](https://github.com/phuryn/pm-skills/blob/main/variables.md), and [`tests.md`](https://github.com/phuryn/pm-skills/blob/main/tests.md) - Conditional files ([`emails.md`](https://github.com/phuryn/pm-skills/blob/main/emails.md), [`cron.md`](https://github.com/phuryn/pm-skills/blob/main/cron.md), [`seo.md`](https://github.com/phuryn/pm-skills/blob/main/seo.md), [`automation.md`](https://github.com/phuryn/pm-skills/blob/main/automation.md)) are generated only when relevant capabilities exist - The `/document-app` command reverse-engineers code to produce documentation, while `/derive-tests` creates the verification map - Intended-state audits compare documentation against actual implementation to identify drift ## Frequently Asked Questions ### What is a "vibe-coded" application? A vibe-coded application is software generated primarily through AI assistance, often produced rapidly through conversational prompts rather than traditional hand-coding. The shipping-artifacts skill addresses the documentation debt these applications typically accumulate by enforcing structured documentation standards. ### How does the skill handle missing capabilities? When an application lacks specific features like email or cron jobs, the skill inserts a "No X" declaration in [`architecture.md`](https://github.com/phuryn/pm-skills/blob/main/architecture.md) rather than omitting the section entirely. This ensures reviewers can confirm the absence of functionality rather than assuming documentation is incomplete. ### What is the difference between `/document-app` and `/ship-check`? The `/document-app` command generates only the documentation files, while `/ship-check` runs the complete pipeline including documentation generation, intended-vs-implemented audits, and test coverage analysis as defined in [`pm-ai-shipping/commands/ship-check.md`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/commands/ship-check.md). ### Where are the skill definitions stored? The core skill definition resides in [`pm-ai-shipping/skills/shipping-artifacts/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/skills/shipping-artifacts/SKILL.md), with command implementations in `pm-ai-shipping/commands/` and the kit overview in [`pm-ai-shipping/README.md`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/README.md).