How the shipping-artifacts Skill Documents Vibe-Coded Applications for Review

The shipping-artifacts skill generates five mandatory documentation files—architecture.md, flows.md, permissions.md, variables.md, and tests.md—plus conditional add-ons, transforming AI-generated code into reviewable artifacts with explicit security boundaries and test coverage maps.

The phuryn/pm-skills repository provides structured skills for AI-assisted project management, with the shipping-artifacts skill specifically designed to solve the documentation gap in "vibe-coded" (AI-generated) applications. This skill enforces a reproducible documentation standard that captures system architecture, security boundaries, and verification requirements essential for human review.

Mandatory Core Documentation Set

The skill definition in pm-ai-shipping/skills/shipping-artifacts/SKILL.md mandates five foundational documents that every vibe-coded application must produce. These files establish the single source of truth for reviewers.

architecture.md

This file provides the high-level system overview including the tech stack, authentication flow, trust boundaries, and a "known risks" table. It serves as the entry point for reviewers and indexes related documentation.

flows.md

Documents step-by-step, permission-aware user journeys. Each flow explicitly shows where authentication checks occur, where side-effects trigger, and where trust boundaries are crossed.

permissions.md

Contains the roles and claims matrix alongside any row-level security rules governing data access.

variables.md

Inventory table of configuration values and secrets, documenting their scope, source, rotation plan, and risk rating.

tests.md

Generated by the /derive-tests command (defined in pm-ai-shipping/commands/derive-tests.md), this verification map links each documented rule to existing tests, proposed tests, and uncovered gaps.

Conditional Documentation for Optional Capabilities

The skill dynamically adds documentation only when specific capabilities exist in the codebase. When a capability is absent, the generator inserts a single "No X" line in architecture.md to maintain documentation honesty.

emails.md

Required when the application implements notification pipelines. Documents templates, retry logic, and failure handling.

cron.md

Required for scheduled jobs. Covers idempotency guarantees, execution frequency, and secret usage patterns.

seo.md

Documents SEO and metadata handling for public-facing routes.

automation.md

Required for embedded AI agents or LLM workflows. Details webhooks, guardrails, and automation boundaries.

Workflow Commands and Usage

The skill integrates into the AI-shipping kit through specific slash commands defined in the repository's command definitions.

To generate the complete documentation set:

/pm-ai-shipping:document-app

This command reverse-engineers the codebase to populate the core and conditional documentation files. To build the test coverage map:

/pm-ai-shipping:derive-tests

For the complete pipeline including audits:

/pm-ai-shipping:ship-check

These commands are documented in pm-ai-shipping/commands/document-app.md, pm-ai-shipping/commands/derive-tests.md, and pm-ai-shipping/commands/ship-check.md respectively.

Verification Through Intended-State Audits

After documentation generation, the companion intended-vs-implemented skill compares the documented state against the actual codebase. This audit surfaces gaps that static scanners miss because they lack an intent model, ensuring the documentation accurately reflects deployed logic.

Summary

• The shipping-artifacts skill enforces five mandatory documentation files: architecture.md, flows.md, permissions.md, variables.md, and tests.md
• Conditional files (emails.md, cron.md, seo.md, automation.md) are generated only when relevant capabilities exist
• The /document-app command reverse-engineers code to produce documentation, while /derive-tests creates the verification map
• Intended-state audits compare documentation against actual implementation to identify drift

Frequently Asked Questions

What is a "vibe-coded" application?

A vibe-coded application is software generated primarily through AI assistance, often produced rapidly through conversational prompts rather than traditional hand-coding. The shipping-artifacts skill addresses the documentation debt these applications typically accumulate by enforcing structured documentation standards.

How does the skill handle missing capabilities?

When an application lacks specific features like email or cron jobs, the skill inserts a "No X" declaration in architecture.md rather than omitting the section entirely. This ensures reviewers can confirm the absence of functionality rather than assuming documentation is incomplete.

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

The /document-app command generates only the documentation files, while /ship-check runs the complete pipeline including documentation generation, intended-vs-implemented audits, and test coverage analysis as defined in pm-ai-shipping/commands/ship-check.md.

Where are the skill definitions stored?

The core skill definition resides in pm-ai-shipping/skills/shipping-artifacts/SKILL.md, with command implementations in pm-ai-shipping/commands/ and the kit overview in pm-ai-shipping/README.md.

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