How the /ship-check Command Audits AI-Built Code: A 6-Step Pipeline

The /ship-check command audits AI-built code by orchestrating six specialist commands that document system architecture, establish agent context, run static security and performance audits, derive test coverage maps, and compile everything into a reviewer-ready shipping packet.

The phuryn/pm-skills repository provides a command framework for shipping production-ready code generated by AI assistants. The /ship-check command serves as the central orchestrator that transforms raw AI-generated repositories into validated, human-reviewable artifacts through a tightly sequenced audit pipeline.

Step 1: Document the System Intent

The audit begins by ensuring up-to-date design documentation exists. The command invokes /document-app and applies the shipping-artifacts skill to capture critical system aspects: architecture diagrams, data flows, permission models, and environment variables. This establishes the "documented intent" baseline against which all subsequent audits compare the actual implementation.

Step 2: Generate Agent Operating Context

Next, /ship-check generates fresh agent context files. According to pm-ai-shipping/commands/ship-check.md (lines 24-31), the command creates CLAUDE.md and an accompanying AGENTS.md derived from the system documentation. These files define trust boundaries and operational constraints for subsequent AI coding agents, explicitly stating what the system is and which components may be touched.

Step 3: Execute Static Security Audit

The command runs /security-audit-static to map entry points to trust boundaries and inspect high-value paths including authentication and data access. As implemented in pm-ai-shipping/commands/security-audit-static.md (lines 26-48), this audit cross-references documented intent against actual implementation and applies self-refutation to each candidate finding. Surviving findings are grouped by severity (Critical, High, Medium, Low) and formatted into a standardized security report.

Step 4: Run Static Performance Audit

The pipeline executes /performance-audit-static to detect efficiency issues including over-fetching, missing database indexes, and caching gaps. The audit summarizes recommendations with associated effort levels (low, medium, high) and priority rankings, providing actionable optimization paths before shipping.

Step 5: Derive Test Coverage Maps

The /derive-tests command transforms documented rules and audit gaps into a tests.md coverage map. As detailed in pm-ai-shipping/commands/ship-check.md (lines 40-43), this map categorizes verification status: rules pinned by existing tests, proposed rules awaiting tests, and completely unverified boundary rules. This ensures every security and performance finding can be traced to a testable requirement.

Step 6: Compile the Shipping Packet

Finally, the command aggregates all artifacts into a single markdown packet. According to pm-ai-shipping/commands/ship-check.md (lines 71-76), this hand-off compiler does not re-run audits but records their outputs alongside documentation status and launch blockers. The packet contains:

• Documentation inventory (present/missing status)
• Agent context status (CLAUDE.md/AGENTS.md creation confirmation)
• Test-coverage summary with verification gaps
• Security findings with severity counts
• Performance recommendations with effort estimates
• Launch blockers (unresolved critical/high items)
• Recommended next actions

This "documented == implemented" validation loop ensures the audit is robust for AI-generated code.

Usage Examples

Run the audit against the entire repository:

/ship-check

Target a specific service or directory:

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

The command outputs a structured shipping packet. For example:

## Shipping Packet: supabase/functions

### Documentation Inventory

| Doc | Status | Notes |
|-----|--------|-------|
| architecture.md | present | ✅ |
| permissions.md   | missing  | ❗️ |

### Agent Context

CLAUDE.md / AGENTS.md: created

### Test Coverage

- 5 rules pinned by existing tests
- 3 proposed rules without tests
- 2 unverified boundary rules

### Security Summary

- Critical: 2 (unauthenticated DB query, insecure webhook)
- High: 4 (SSRF, missing role checks)

### Performance Summary

- Over‑fetching on /users endpoint (recommend index, effort: low)
- Missing cache on /stats (recommend redis, effort: medium)

### Launch Blockers

- Unresolved Critical DB query – must be fixed before shipping

### Recommended Next Actions

- Run `/document-app` to add missing permissions.md
- Fix the two critical findings, then re‑run `/ship-check`

Key Implementation Files

The audit pipeline is implemented across these files:

File	Role
pm-ai-shipping/commands/ship-check.md	Orchestrates the six-step shipping sequence (lines 6-46)
pm-ai-shipping/commands/security-audit-static.md	Implements static security auditing with intent-versus-implementation validation and self-refutation logic (lines 26-48)
pm-ai-shipping/commands/performance-audit-static.md	Performs static performance analysis for database and caching optimizations
pm-ai-shipping/commands/document-app.md	Generates system documentation feeding the audit baseline
pm-ai-shipping/commands/derive-tests.md	Produces the tests.md coverage map from documented intent
pm-ai-shipping/skills/shipping-artifacts/SKILL.md	Defines required architecture, flow, permission, and variable artifacts

Summary

• The /ship-check command runs a six-step pipeline that documents, audits, and compiles AI-generated code into shipping packets.
• It generates agent context files (CLAUDE.md, AGENTS.md) to establish trust boundaries for future AI agents.
• Static security auditing maps entry points to trust boundaries and self-refutes findings against documented intent.
• Test coverage mapping converts audit gaps into verifiable rules in tests.md.
• The final shipping packet acts as a hand-off compiler for human reviewers, recording launch blockers and next actions without re-running audits.

Frequently Asked Questions

What makes the /ship-check audit robust for AI-generated code?

The audit enforces a "documented == implemented" validation loop. By generating CLAUDE.md context files and cross-referencing every security finding against documented intent, the command ensures that AI-generated implementations align with specified architecture and trust boundaries. Self-refutation logic in the security audit eliminates false positives before they reach the shipping packet.

How does the shipping packet differ from running individual audit commands?

The shipping packet acts as a hand-off compiler that records outputs rather than re-executing audits. As implemented in pm-ai-shipping/commands/ship-check.md (lines 71-76), it aggregates documentation status, security findings, performance recommendations, and launch blockers into a single markdown file designed for human review and sign-off decisions.

What triggers a "launch blocker" in the audit?

Launch blockers are unresolved Critical or High severity security findings that must be fixed before shipping. The packet explicitly lists these items—such as unauthenticated database queries or insecure webhooks—alongside the specific files and lines where they occur, requiring remediation before the code can be approved.

Can /ship-check audit specific parts of a codebase?

Yes. The command accepts path or service arguments to target specific directories. For example, /ship-check supabase/functions runs the six-step audit pipeline exclusively against the Supabase functions directory, generating a focused shipping packet for that subsystem rather than the entire repository.

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