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

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, 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 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 and 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, 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 and 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 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:

# 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:

# 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 generated by /ship-check follows this structure:

## 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, flows.md, permissions.md, variables.md, 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 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 and 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}