How to Document AI-Built (Vibe-Coded) Applications for Security and Performance Audits

The pm-ai-shipping plugin family provides a systematic documentation workflow that generates reviewable artifacts—architecture.md, flows.md, permissions.md, and variables.md—then cross-references them against your codebase using intended-vs-implemented analysis to drive static security and performance audits.

AI-generated code often lacks a durable record of intent, creating critical blind spots during security and performance reviews. The phuryn/pm-skills repository solves this through the pm-ai-shipping plugin family, which mandates a documentation-first approach that serves as the source of truth for automated audits. This workflow ensures that what the system is supposed to do, which data it handles, and who is authorized to access it are all captured in version-controlled artifacts before any static analysis runs.

Core Documentation Artifacts

The pm-ai-shipping/skills/shipping-artifacts/SKILL.md file defines five mandatory documents that establish the baseline for any audit. These files live in your /documentation directory and provide the structured intent that audit commands consume.

architecture.md

This document captures the high-level system overview, technology stack, authentication flow, and trust-boundary diagram. It includes a "known risks and assumptions" list that serves as the root of your documentation set. All other artifacts cross-reference this file, making it the starting point for human reviewers and automated tools alike.

flows.md

The flows document details permission-relevant journeys using the format: actor → precondition → success outcome. It explicitly maps authorization checks at each step, trust-boundary crossings, and side-effects such as database writes, email dispatches, background jobs, and external API calls. This shows runtime enforcement and complements the static permissions matrix.

permissions.md

This artifact defines roles and claims, scope derivation logic, and a resource × operation × role matrix. It also documents row-level security locations. As defined in pm-ai-shipping/skills/shipping-artifacts/SKILL.md, this file serves as the baseline for any access-control audit, while flows.md visualizes how those permissions are enforced during execution.

variables.md

Configuration and secrets management are documented here in a table format that includes usage locations, sources (environment variables, vaults, etc.), rotation plans, and risk ratings. Auditors use this to verify that no secrets leak to the client and that proper rotation procedures exist.

tests.md

Generated by the /derive-tests command, this verification map ties every rule in your documentation to concrete test artifacts. It catalogs existing coverage, proposed tests, and gaps, providing evidence that "documented equals implemented" before any audit begins.

Conditional Documentation for Specialized Capabilities

When your application includes specific capabilities, the pm-ai-shipping/skills/shipping-artifacts/SKILL.md requires additional targeted documentation:

• emails.md: Required when sending transactional or automated email. Documents the queue → processor → provider chain, templates, retry logic, and failure handling.
• cron.md: Required for background or scheduled jobs. Inventories jobs, schedules, idempotency guarantees, and authentication for internal calls.
• seo.md: Required for public or SPA routes indexed by bots. Covers preview strategies, route-to-SEO mapping, sanitization, and bot-vs-human routing.
• automation.md: Required for embedded agents, LLM-driven workflows, or webhooks. Captures triggers, owners, tool surfaces, steering versus hard guardrails, output contracts, and approval gates.

Bridging the Gap with Intended-vs-Implemented Analysis

Before running audits, the system validates that your code actually implements the documented intent. The pm-ai-shipping/skills/intended-vs-implemented/SKILL.md defines a four-step reconciliation method:

1. Read the documentation (/documentation/*.md) as the source of truth.
2. Collect implementation evidence—concrete lines enforcing each claim (auth checks, query filters, sanitization routines).
3. Classify mismatches—only gaps that cross a trust, cost, data, or tenant boundary are reported.
4. Self-refute—each candidate finding must be disproved with evidence before being kept in the final report.

This process ensures that audit findings are grounded in documented requirements rather than arbitrary code analysis.

Running Static Security Audits

The /security-audit-static command, defined in pm-ai-shipping/commands/security-audit-static.md, performs a static security review that cross-references your documentation artifacts. The audit maps entry points to trust boundaries and dangerous sinks (raw SQL, eval statements, LLM prompts), then inspects the four high-value paths:

• Authorization enforcement
• Data access patterns
• Session and identity management
• Encoding and sanitization

The command applies the intended-vs-implemented self-refutation process, keeping only evidence-backed risks that violate the documented security model.

Running Static Performance Audits

The /performance-audit-static command, documented in pm-ai-shipping/commands/performance-audit-static.md, focuses on three scalability failure modes:

1. Over-fetch—fields retrieved from databases or APIs but never rendered in the UI.
2. Missing/inefficient indexes—identified by analyzing query patterns against your schema.
3. Caching opportunities—for hot read-only data that could be memoized or CDN-cached.

Each finding includes a concrete recommendation, such as a specific SQL index definition or a caching strategy with TTL values.

The Complete Shipping Packet Workflow

For comprehensive coverage, the /ship-check command orchestrates the entire documentation and audit pipeline. As defined in pm-ai-shipping/commands/ship-check.md, this command:

1. Runs /document-app to generate core and conditional documentation.
2. Executes /derive-tests to create the tests.md coverage map.
3. Invokes /security-audit-static for security findings.
4. Invokes /performance-audit-static for performance recommendations.

The result is a shipping packet containing all artifacts and audit reports, ready for human review or downstream AI agents.

Practical Implementation Examples

Run these commands inside a Claude-compatible environment (Claude Code, Claude Cowork, or any CLI loading the pm-ai-shipping plugin):

# Generate documentation for the entire repository

/document-app

# Create test coverage mapping from documentation

/derive-tests

# Run static security audit against documented trust boundaries

/security-audit-static

# Run performance audit on the orders module only

/performance-audit-static src/backend/orders

# Generate complete shipping packet with docs + audits

/ship-check

Target specific subdirectories for micro-service audits:

# Document only Supabase functions

/document-app supabase/functions

# Security audit for payment service only

/security-audit-static payments/

# Complete hand-off packet for Payments micro-service

/ship-check payments/

Summary

• AI-built applications require explicit documentation of intent because generated code lacks human design rationale.
• The pm-ai-shipping plugin family mandates five core artifacts (architecture.md, flows.md, permissions.md, variables.md, tests.md) and four conditional ones based on capabilities.
• The intended-vs-implemented skill reconciles documentation against code, filtering out false positives through self-refutation.
• Static security audits cross-reference documentation to identify trust-boundary violations and dangerous sinks.
• Static performance audits detect over-fetching, missing indexes, and caching opportunities with concrete remediation steps.
• The shipping packet (/ship-check) provides a reproducible, evidence-backed workflow for handing off AI-built code to security and performance reviewers.

Frequently Asked Questions

Why do vibe-coded applications require different documentation approaches?

Vibe-coded applications are built through iterative AI prompting rather than upfront design, resulting in implicit intent that evolves rapidly without written record. Traditional code comments rarely capture the "why" behind AI-generated logic, especially regarding authorization boundaries and data handling assumptions. The pm-ai-shipping framework forces explicit documentation of trust boundaries, permission flows, and variable handling before any audit runs, creating the durable record that security and performance reviewers require.

How does the intended-vs-implemented skill prevent false positives in security audits?

The intended-vs-implemented skill enforces a self-refutation step where each candidate finding must be actively disproved with evidence from the codebase before being reported. By requiring auditors to collect concrete implementation evidence—such as specific lines handling authorization checks or input sanitization—the system filters out theoretical vulnerabilities that are actually mitigated in code. Only gaps that cross documented trust, cost, data, or tenant boundaries and lack implementation evidence are retained in the final report.

What distinguishes core documentation from conditional documentation?

Core documentation (architecture.md, flows.md, permissions.md, variables.md, tests.md) is required for every application because it captures universal concerns: system structure, authorization, data handling, and verification. Conditional documentation (emails.md, cron.md, seo.md, automation.md) is generated only when the relevant capability exists in the codebase, as defined in pm-ai-shipping/skills/shipping-artifacts/SKILL.md. This prevents documentation bloat while ensuring that high-risk capabilities like background jobs or LLM integrations receive targeted scrutiny.

Can I audit specific parts of my codebase rather than the entire application?

Yes. The /document-app, /security-audit-static, and /performance-audit-static commands all accept path arguments to target specific directories. For example, /security-audit-static payments/ focuses the security audit only on the payment service, while /performance-audit-static src/backend/orders analyzes query patterns specifically within the orders module. This scoped approach is useful for micro-service architectures or when iteratively hardening specific components of a larger vibe-coded application.

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