# How to Document Vibe-Coded Apps for Code Review: The AI Shipping Kit Method

> Streamline vibe-coded app code reviews with the AI Shipping Kit. Document system intent, permissions, secrets, and tests effortlessly for faster, more effective reviews.

- Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills)
- Tags: how-to-guide
- Published: 2026-06-19

---

**The AI Shipping Kit (`pm-ai-shipping`) converts vibe-coded repositories into review-ready shipping packets by enforcing a standardized documentation set that captures system intent, permission boundaries, secret locations, and test coverage, enabling human reviewers to compare documented assumptions against actual code implementation.**

Vibe-coded applications—generated by AI agents focused on immediate output rather than architectural intent—often lack durable records of **what the system is supposed to do**, **who can perform which actions**, and **where sensitive data lives**. The `phuryn/pm-skills` repository solves this through the **AI Shipping Kit**, a plugin that transforms opaque AI-generated code into auditable, review-ready artifacts using the `shipping-artifacts` skill and the `/ship-check` command workflow.

## Core Documentation Requirements

The `shipping-artifacts` skill, defined 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 core documents that establish the baseline for any code review. These files create a paper trail of intent that reviewers can verify against the implementation.

### architecture.md

This document captures the high-level system overview, technology stack, authentication and session flows, trust-boundary diagrams, known risks, and architectural assumptions. It serves as the root of the documentation set, with cross-references to all other artifacts.

### flows.md

**flows.md** maps end-to-end user journeys using the actor → precondition → success pattern, documenting authorization checks at each step and trust-boundary crossings. This reveals *where* and *in what order* the system enforces security controls, making it essential for security reviews.

### permissions.md

This file defines the roles and claims matrix, scope derivation logic, and resource × operation × role mappings. It includes row-level security details and serves as the baseline for access-control audits.

### variables.md

**variables.md** catalogs configuration names, usage locations, scope (server vs. client), sources (environment variables vs. secret stores), rotation plans, and risk ratings. This surface enables reviewers to detect secret leaks and PII exposure risks.

### tests.md

The verification map ties documented rules to existing test coverage, proposed tests, and uncovered gaps. This demonstrates whether the documented intent is actually enforced by automated verification.

## Conditional Documentation for Specific Capabilities

The `shipping-artifacts` skill dynamically adds documentation only when relevant capabilities exist in the codebase. These conditional documents prevent boilerplate while ensuring critical domains are captured.

### emails.md

Include this when the application sends transactional or automated email. It documents the queue → processor → provider path, template handling, retry/back-off strategies, and failure handling mechanisms.

### cron.md

Required for scheduled or background jobs, this inventory lists job schedules, associated secrets, idempotency guarantees, authentication contexts, and run logs.

### seo.md

For public or indexable routes (SPAs, bot-facing endpoints), this document captures meta-tag strategy, route-to-SEO mapping, sanitization rules, and bot-vs-human routing logic.

### automation.md

When the app contains embedded AI agents, tool-calling features, webhooks, or other automation, this file specifies triggers, owners, tool surfaces, prompt vs. hard guardrails, output contracts, approval gates, logging, and kill-switches.

## The Shipping Workflow

Running the **`/ship-check`** command orchestrates the complete documentation and audit pipeline. This workflow is defined in [`pm-ai-shipping/commands/ship-check.md`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/commands/ship-check.md) and produces a final shipping packet suitable for human sign-off.

1. **Document the system** – Invoke `/document-app` (or use an existing `/documentation/` folder) to generate the core and conditional documentation set.

2. **Wire agent context** – Generate [`CLAUDE.md`](https://github.com/phuryn/pm-skills/blob/main/CLAUDE.md) and [`AGENTS.md`](https://github.com/phuryn/pm-skills/blob/main/AGENTS.md) derived from system docs, establishing clear operating boundaries for subsequent AI coding agents.

3. **Security audit** – Run `/security-audit-static`, which applies the **`intended-vs-implemented`** skill to locate gaps between documented rules and actual code.

4. **Performance audit** – Run `/performance-audit-static` to surface over-fetching, missing database indexes, and caching opportunities.

5. **Derive test coverage** – Run `/derive-tests` to create [`tests.md`](https://github.com/phuryn/pm-skills/blob/main/tests.md), mapping every documented rule to existing tests, proposed tests, or coverage gaps.

6. **Compile the shipping packet** – A markdown summary listing documentation status, agent context, test coverage, security and performance findings, launch blockers, and next actions.

## Why Documentation Matters for Code Review

The shipping packet transforms vibe-coded apps from opaque black boxes into auditable systems. **Intent equals recorded intent**—reviewers can compare the *intended* behavior (documented in [`architecture.md`](https://github.com/phuryn/pm-skills/blob/main/architecture.md) and [`flows.md`](https://github.com/phuryn/pm-skills/blob/main/flows.md)) against the *implemented* behavior (actual code).

The **gap detection** capability surfaces missing authentication checks, undocumented side-effects, or secret exposures by comparing documentation against implementation using the `intended-vs-implemented` skill. **Test-coverage visibility** via [`tests.md`](https://github.com/phuryn/pm-skills/blob/main/tests.md) shows which rules are verified, which are only proposed, and which remain completely untested.

Finally, the packet provides **auditability**—a single, reproducible artifact that humans can sign off on, ensuring compliance, security, and performance standards are met before merge.

## Implementation Guide

To document a vibe-coded repository located at `./my-app`, execute the following commands:

```bash

# Generate core and conditional documentation

/document-app ./my-app

# Run the full shipping sequence (produces the complete packet)

/ship-check ./my-app

```

For granular control, invoke individual stages directly:

```bash

# Document only (creates /documentation/*.md files)

/document-app ./my-app

# Generate test coverage mapping after docs exist

/derive-tests ./my-app

# Run static security analysis

/security-audit-static ./my-app

# Run static performance analysis

/performance-audit-static ./my-app

```

The resulting [`shipping-packet.md`](https://github.com/phuryn/pm-skills/blob/main/shipping-packet.md) generated by `/ship-check` follows this structure:

```markdown

## Shipping Packet: my-app

### Documentation Inventory

| Doc            | Status | Notes |
|----------------|--------|-------|
| architecture.md| present| |
| flows.md       | present| |
| permissions.md | present| |
| variables.md   | present| |
| tests.md       | present| |
| emails.md      | n/a    | No email sending |
| cron.md        | present| Background jobs listed |
| seo.md         | n/a    | SPA without public routes |
| automation.md  | present| AI agents embedded |

```

## Summary

- **Vibe-coded apps** require explicit documentation because AI agents prioritize output over architectural intent.
- The **AI Shipping Kit** (`pm-ai-shipping`) enforces a **core documentation set** ([`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), [`tests.md`](https://github.com/phuryn/pm-skills/blob/main/tests.md)) plus **conditional docs** for specific capabilities.
- The **`/ship-check`** command orchestrates the full workflow, generating agent context files and running security and performance audits.
- The **`intended-vs-implemented`** skill bridges the gap between documented intent and actual code, surfacing security holes and missing tests.
- All artifacts are defined 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) and executed via commands in `pm-ai-shipping/commands/`.

## Frequently Asked Questions

### What makes vibe-coded apps particularly difficult to review?

Vibe-coded applications are generated by AI agents that optimize for functional output rather than maintainable architecture. According to the `phuryn/pm-skills` source code, this creates a "durability gap" where the system lacks records of **what it is supposed to do**, **who can do what**, **where secrets live**, and **which rules are enforced**. Without these anchors, reviewers cannot verify if the implementation matches the intended design.

### How does the intended-vs-implemented skill detect security gaps?

The `intended-vs-implemented` skill, invoked via `/security-audit-static`, performs a static analysis comparing the documented rules in [`flows.md`](https://github.com/phuryn/pm-skills/blob/main/flows.md) and [`permissions.md`](https://github.com/phuryn/pm-skills/blob/main/permissions.md) against the actual code implementation. It surfaces discrepancies such as missing authorization checks at trust boundaries, undocumented side-effects like database writes or external API calls, and secret exposures that violate the [`variables.md`](https://github.com/phuryn/pm-skills/blob/main/variables.md) risk classifications.

### Can I run individual audit stages without executing the full workflow?

Yes. While `/ship-check` runs the complete pipeline, you can invoke individual commands for targeted analysis. Use `/document-app` to generate documentation only, `/derive-tests` to create test coverage maps, `/security-audit-static` for security gap analysis, or `/performance-audit-static` to identify over-fetching and missing indexes. Each command operates independently as documented in `pm-ai-shipping/commands/`.

### What happens if my app doesn't use email or cron jobs?

The `shipping-artifacts` skill automatically excludes irrelevant conditional documents. If the codebase lacks email capabilities, [`emails.md`](https://github.com/phuryn/pm-skills/blob/main/emails.md) will be marked as "n/a" in the final shipping packet rather than left empty or templated. This keeps the documentation lean while ensuring that if these capabilities are added later, the requirement to document them is enforced in subsequent `/ship-check` runs.