How the /ship-check Command Generates a Reviewer-Ready Shipping Packet for AI-Built Code

The /ship-check command orchestrates a six-stage pipeline that transforms Vibe-coded repositories into a single, human-readable shipping packet by coordinating documentation generation, security audits, performance checks, and test coverage mapping.

The phuryn/pm-skills repository provides a structured framework for validating AI-generated code before it reaches production. At its core, the /ship-check command, defined in pm-ai-shipping/commands/ship-check.md, does not perform audits itself but rather coordinates specialist commands and skills to produce a consolidated hand-off document for human reviewers.

The Six-Stage Pipeline Architecture

The command executes six strictly ordered steps, each building on artifacts from the previous stage. This sequential dependency ensures that missing documentation is flagged early and that every security or performance finding is automatically mapped to test requirements.

Step 1: Document the System

The pipeline begins by invoking /document-app, which utilizes the shipping-artifacts skill located at pm-ai-shipping/skills/shipping-artifacts/SKILL.md. This step generates or refreshes the core documentation set: architecture.md, flows.md, permissions.md, and variables.md, along with optional files such as emails.md, cron.md, seo.md, and automation.md. These documents establish the intended state of the system, which subsequent audits use as a baseline for comparison.

Step 2: Wire the Agent Operating Context

Next, the command produces the operating-context files CLAUDE.md and AGENTS.md. According to the implementation in pm-ai-shipping/commands/ship-check.md (lines 28-31), these files encode trust boundaries, guardrails, and explicit "what may not be touched" rules derived from the documentation created in Step 1. This establishes the safety perimeter for AI agents working within the repository.

Step 3: Security Audit with Intended-vs-Implemented Analysis

The pipeline executes /security-audit-static and applies the intended-vs-implemented skill from pm-ai-shipping/skills/intended-vs-implemented/SKILL.md. This comparison validates the actual code against the documented intent in permissions.md, flows.md, and architecture.md, identifying discrepancies where implementation diverges from specification.

Step 4: Static Performance Audit

The command runs /performance-audit-static to detect over-fetching, missing database indexes, and caching issues. This static analysis operates on the codebase without requiring runtime execution, catching performance anti-patterns before they reach production.

Step 5: Derive the Test-Coverage Map

Using /derive-tests, the pipeline transforms documented rules and audit findings into tests.md, a structured coverage map. This artifact categorizes every rule as pinned by existing tests, proposed but unwritten, guarded-live/manual, or completely unverified, providing a clear gap analysis for the development team.

Step 6: Compile the Shipping Packet

Finally, the synthesis logic in pm-ai-shipping/commands/ship-check.md (lines 44-69) aggregates all preceding outputs into a single markdown packet. This compilation includes the documentation inventory, agent-context status, test coverage summary, security and performance summaries, a launch-blocker list of unresolved critical/high items, and recommended next actions.

Usage Examples

Run the complete pipeline on the entire repository:

/ship-check

Target a specific service or sub-path:

/ship-check payments-service
/ship-check supabase/functions

Execute the full pipeline manually for debugging purposes:

/document-app
/ship-check

Anatomy of the Generated Shipping Packet

The final artifact is a hand-off document that consolidates scattered audit logs into a structured report. Below is an excerpt showing the format produced by the compilation step:

## Shipping Packet: my-repo / payments-service

### Documentation Inventory

| Doc               | Status (present / stale / missing / n/a) | Notes |
|-------------------|-------------------------------------------|-------|
| architecture.md   | present                                   |       |
| permissions.md    | present                                   |       |
| flows.md          | missing                                   | Run `/document-app` |
| variables.md      | present                                   |       |

### Agent Context

CLAUDE.md / AGENTS.md: created

### Test Coverage

- Rules pinned by tests: 12
- Proposed but not yet written: 8
- Guarded-live/manual: 3
- Unverified rules: 5

### Security Summary

- Critical: 0
- High: 1 (SQL injection risk in `order/create`)

### Performance Summary

- Over-fetching in `GET /orders`: recommendation to add pagination
- Missing index on `orders.user_id`: priority high

### Launch Blockers

- Unresolved High: SQL injection risk in `order/create`

### Recommended Next Actions

- Fix the SQL injection issue (owner: backend-lead)
- Re-run `/derive-tests` after the fix

Key Source Files and Implementation Details

The orchestration logic resides in pm-ai-shipping/commands/ship-check.md, while the underlying capabilities are implemented across the following files:

• pm-ai-shipping/commands/document-app.md – Generates system documentation via the shipping-artifacts skill
• pm-ai-shipping/commands/security-audit-static.md – Static security analysis using the intended-vs-implemented skill
• pm-ai-shipping/commands/performance-audit-static.md – Performance bottleneck detection
• pm-ai-shipping/commands/derive-tests.md – Coverage mapping to tests.md
• pm-ai-shipping/skills/shipping-artifacts/SKILL.md – Documentation generation algorithms
• pm-ai-shipping/skills/intended-vs-implemented/SKILL.md – Comparison logic between specification and code

Summary

• The /ship-check command coordinates six sequential stages rather than executing audits directly.
• Each step depends on artifacts from the previous stage, ensuring documentation precedes security and performance validation.
• The final shipping packet consolidates documentation status, test coverage gaps, security findings, performance issues, and launch blockers into a single reviewer-ready document.
• Human reviewers receive a structured hand-off artifact that proves the code's intent is documented, audited, and mapped to verification tests.

Frequently Asked Questions

What is the difference between /ship-check and running individual audit commands?

/ship-check is an orchestration layer that manages dependencies between documentation, context files, and audits, whereas individual commands like /security-audit-static or /performance-audit-static perform specific technical analyses. The /ship-check command ensures that security audits run only after system intent is documented, and that test coverage maps are generated only after audit findings are available.

Can I run /ship-check on partial codebases or specific directories?

Yes. The command accepts an optional path argument, allowing you to generate a shipping packet for a specific service or subdirectory. For example, /ship-check payments-service validates only the payments-service folder while maintaining the same six-stage pipeline and documentation requirements.

How does the command handle missing documentation?

If required documentation (such as flows.md or architecture.md) is missing or stale, the pipeline highlights this in the final packet's Documentation Inventory section with a status of "missing" and includes a note to run /document-app. Because Step 1 runs before security and performance audits, missing documentation is flagged before those expensive checks execute.

What criteria determine a "launch blocker" in the shipping packet?

Launch blockers are unresolved findings marked as Critical or High severity from the security and performance audits. These items appear in the Launch Blockers section of the packet and must be resolved before the code is considered safe for production deployment. The packet explicitly assigns ownership and recommends next actions for each blocker.

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