What Is the pm-ai-shipping Plugin? A Complete Guide to Safe AI Code Shipping

The pm-ai-shipping plugin is a Product Management toolkit that adds skills and commands for converting AI-generated (vibe-coded) applications into review-ready shipping packets by restoring auditability and documenting system intent.

The pm-ai-shipping plugin is part of the phuryn/pm-skills repository and addresses a critical gap in modern AI-assisted development. While generative AI agents can produce functional code rapidly, they typically leave no durable record of architectural intent, security requirements, or testing expectations—making human review nearly impossible.

The Core Problem: Why AI-Generated Code Lacks Reviewability

AI-generated code arrives without intent documentation. When an agent writes a feature, it rarely documents what the system is supposed to do, which permissions are required, where secrets should live, or which tests validate the behavior. Without this "intended state" record, neither human reviewers nor automated auditors can reliably determine if the application is safe to ship.

The plugin solves this by bridging the gap between "what the AI says it built" and "what the code actually does."

How the pm-ai-shipping Plugin Restores Auditability

The plugin implements four core capabilities defined in the pm-ai-shipping/skills/shipping-artifacts/SKILL.md and pm-ai-shipping/skills/intended-vs-implemented/SKILL.md specifications:

Documenting System Intent

The /document-app command reverse-engineers the codebase into structured markdown files including architecture.md, flows.md, permissions.md, variables.md, and conditional docs like emails.md or cron.md. This creates the "intended-state" half of any audit trail.

Deriving Test Coverage Maps

The /derive-tests command scans existing test files and matches them against documented rules, producing tests.md with sections for Existing coverage, Proposed tests, and Gaps. This generates the verification map needed to validate intent against implementation.

Running Static Security and Performance Audits

The plugin performs evidence-based risk assessment through:

• /security-audit-static – Cross-references the codebase against documented security rules in pm-ai-shipping/commands/security-audit-static.md, only reporting findings backed by documented intent.
• /performance-audit-static – Identifies over-fetching, missing indexes, and caching opportunities ranked by effort and impact, as defined in pm-ai-shipping/commands/performance-audit-static.md.

Compiling the Shipping Packet

The /ship-check command orchestrates the entire pipeline and packages all generated markdown files into a documentation/ directory, creating a single consumable artifact that reviewers can evaluate without inferring intent from source code alone.

Complete Workflow: Using the pm-ai-shipping Commands

All commands support the long form /pm-ai-shipping:<command> or short / <command> syntax.

Full Shipping Pipeline

Run the complete workflow to generate documentation, tests, audits, and the final packet:

/pm-ai-shipping:ship-check

This executes:

1. /document-app – Generates core and conditional documentation.
2. /derive-tests – Creates the tests.md verification map.
3. /security-audit-static – Performs static security analysis.
4. /performance-audit-static – Performs static performance analysis.
5. Packages everything into documentation/ for reviewer hand-off.

Document Application Only

Generate just the documentation artifacts without running audits:

/pm-ai-shipping:document-app

This creates architecture.md, flows.md, permissions.md, variables.md, tests.md, and applicable conditional docs (emails.md, cron.md, seo.md, automation.md).

Generate Test Coverage Map

Build the verification map that ties tests to documented intent:

/pm-ai-shipping:derive-tests

This produces tests.md mapping existing tests to rules and identifying coverage gaps.

Run Static Security Audit

Execute an evidence-based security review:

/pm-ai-shipping:security-audit-static

Outputs a list of findings, each tied to a specific rule from the intent documentation.

Run Static Performance Audit

Identify optimization opportunities:

/pm-ai-shipping:performance-audit-static

Detects over-fetching, missing indexes, and caching opportunities with effort/impact rankings.

Key Implementation Files

The plugin structure follows the pm-ai-shipping/.claude-plugin/plugin.json manifest consumed by the pm-skills framework:

• pm-ai-shipping/README.md – High-level overview and installation guide.
• pm-ai-shipping/skills/shipping-artifacts/SKILL.md – Detailed specification for the documentation set (core and conditional docs).
• pm-ai-shipping/skills/intended-vs-implemented/SKILL.md – Methodology for comparing documented intent with actual code.
• pm-ai-shipping/commands/ship-check.md – Orchestrates the full shipping pipeline.
• pm-ai-shipping/commands/document-app.md – Generates core documentation from the repository.
• pm-ai-shipping/commands/derive-tests.md – Builds the tests.md verification map.
• pm-ai-shipping/commands/security-audit-static.md – Static security audit implementation.
• pm-ai-shipping/commands/performance-audit-static.md – Static performance audit implementation.

Summary

• The pm-ai-shipping plugin solves the reviewability crisis in AI-generated code by documenting system intent that agents typically omit.
• It generates durable documentation through the shipping-artifacts skill, creating architecture, flows, permissions, and variables files.
• The derive-tests command creates a verification map that links existing tests to documented intent, exposing coverage gaps.
• Static audits cross-reference code against documented rules rather than generic heuristics, producing evidence-backed findings.
• The ship-check command compiles everything into a reviewer-ready packet, enabling safe, auditable releases of vibe-coded applications.

Frequently Asked Questions

What is the difference between /document-app and /ship-check?

The /document-app command generates only the documentation artifacts (architecture, flows, permissions, and variables) without running audits or creating the final package. The /ship-check command runs the complete pipeline including documentation generation, test derivation, security and performance audits, and packages everything into the documentation/ directory. Use /document-app when you only need intent documentation, and /ship-check when preparing a final reviewer hand-off.

How does pm-ai-shipping handle test coverage gaps?

The /derive-tests command, defined in pm-ai-shipping/commands/derive-tests.md, scans the repository's test files and matches them against rules documented in tests.md. It categorizes results into three sections: Existing coverage (tests that validate documented intent), Proposed tests (missing tests needed to cover documented rules), and Gaps (areas where intent exists but no tests cover the behavior).

Can I use pm-ai-shipping with non-AI-generated code?

Yes. While the plugin specifically addresses the "vibe-coding" problem of missing intent documentation, it works effectively on any codebase requiring audit trails or shipping documentation. The methodology of comparing intended state against implementation, defined in pm-ai-shipping/skills/intended-vs-implemented/SKILL.md, applies universally to software requiring formal review processes.

Where does the plugin store generated documentation?

All generated files are written to a documentation/ directory at the repository root. This includes the core artifacts (architecture.md, flows.md, permissions.md, variables.md, tests.md), conditional docs (emails.md, cron.md, etc. when applicable), and audit reports. The ship-check command ensures this directory contains the complete shipping packet ready for reviewer consumption.

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