What Is the Three-Layer System in the PM Skills Marketplace Architecture?

The three-layer system structures AI-generated codebases into core documentation, conditional documentation, and a test-coverage map to ensure every line of code is reviewable, auditable, and covered by tests.

The phuryn/pm-skills repository implements this architectural pattern within its AI Shipping Kit to bridge the gap between rapid AI code generation and enterprise-grade software delivery. By separating fixed system intent from optional capabilities and verification evidence, the three-layer system enables automated security audits and reliable handoffs between AI agents and human reviewers.

Layer 1: Core Documentation

The first layer captures the immutable design intent of the application. According to pm-ai-shipping/skills/shipping-artifacts/SKILL.md, this layer includes the following required files:

• architecture.md – System design and high-level structure
• flows.md – End-to-end user and data flows
• permissions.md – Access-control matrix and authorization rules
• variables.md – Environment configuration and secret-management plans

These files establish the single source of truth for what the system should do. They provide reviewers with a stable foundation for security and performance audits before any code is examined.

Layer 2: Conditional Documentation

The second layer documents optional subsystems only when they exist in the codebase. As defined in the same SKILL.md file, conditional documents include:

• emails.md – Email templates and transaction pipelines
• cron.md – Scheduled jobs and batch processing
• seo.md – Search engine optimization routes and metadata
• automation.md – Embedded agents and workflow automations

If a capability is absent, the system records this explicitly in architecture.md (e.g., "No scheduled work – no cron.md") rather than creating phantom files. This approach keeps documentation honest and compact, preventing false-positive audit findings while maintaining an accurate inventory of actual system capabilities.

Layer 3: Test-Coverage Map

The third layer closes the loop between intent and implementation with tests.md. This file serves as an inventory linking every rule in the core and conditional documentation to concrete test enforcements. The derive-tests command generates this document with three distinct sections:

1. Existing tests – Currently implemented verification
2. Proposed tests – Coverage gaps identified but not yet filled
3. Uncovered gaps – Documented requirements lacking any test coverage

By maintaining this mapping, auditors can instantly verify which documented guarantees are enforced by code and which remain theoretical.

How the Three-Layer System Works in Practice

The AI Shipping Kit provides specific commands to generate and validate these layers. These commands are implemented in the pm-ai-shipping/commands/ directory and orchestrate the workflow from documentation to audit.

Generate the core and conditional documentation layers:

/pm-ai-shipping:document-app

This command produces architecture.md, flows.md, permissions.md, variables.md, and any relevant conditional documents (e.g., cron.md if scheduled jobs exist) based on the current codebase state.

Derive the test-coverage map from the documentation and existing tests:

/pm-ai-shipping:derive-tests

This emits tests.md containing the linked inventory of existing, proposed, and gap tests, connecting documented intent to implementation verification.

Execute the complete audit workflow:

/pm-ai-shipping:ship-check

As implemented in pm-ai-shipping/commands/ship-check.md, this command combines the three documentation layers with static security and performance audits to verify that the code matches the documented architecture.

Key Source Files

The three-layer system is encoded throughout the phuryn/pm-skills repository. These specific files define the contracts and automation:

• pm-ai-shipping/skills/shipping-artifacts/SKILL.md – Defines the three-layer documentation structure, core documents, conditional documents, and the tests.md format
• pm-ai-shipping/skills/intended-vs-implemented/SKILL.md – Implements the audit logic that compares documented intent (layers 1 and 2) against actual code
• pm-ai-shipping/commands/document-app.md – Automates generation of core and conditional documentation
• pm-ai-shipping/commands/derive-tests.md – Generates the third-layer test-coverage map
• pm-ai-shipping/commands/ship-check.md – Orchestrates the full three-layer audit workflow
• README.md – Provides high-level overview of the AI Shipping Kit and plugin ecosystem

Summary

The three-layer system in the PM Skills Marketplace architecture transforms AI-generated code into auditable, production-ready software through:

• Reviewability – Core documentation (architecture.md, flows.md, permissions.md, variables.md) provides a single source of truth for system intent
• Completeness – Conditional documentation ensures only existing capabilities are documented, eliminating phantom files
• Verification – The tests.md coverage map links every documented requirement to existing, proposed, or missing tests
• Automated auditing – The intended-vs-implemented skill automatically detects gaps between documentation and code
• Incremental extensibility – New capabilities automatically trigger conditional documentation updates without breaking existing pipelines

Frequently Asked Questions

What problem does the three-layer system solve?

The three-layer system solves the auditability gap in AI-generated codebases. Without structured documentation, reviewers cannot verify that AI-generated code matches business requirements or security policies. By separating core intent (layer 1), optional features (layer 2), and test evidence (layer 3), the system enables automated tools like /pm-ai-shipping:ship-check to validate that every documented rule has corresponding implementation and test coverage.

How does conditional documentation prevent documentation drift?

Conditional documentation only generates files when the corresponding capability exists in the codebase. If cron.md is absent, the system explicitly notes "No scheduled work" in architecture.md rather than creating an empty placeholder. This prevents phantom files that could confuse security audits or imply untested functionality exists, ensuring the documentation remains an accurate reflection of deployed code.

What is the relationship between the three layers and the ship-check command?

The /pm-ai-shipping:ship-check command consumes all three layers to perform a comprehensive audit. It reads the core and conditional documentation to establish intended behavior, then compares this against the test-coverage map (tests.md) and actual code to identify discrepancies. This integration enables the "intended vs. implemented" verification workflow defined in pm-ai-shipping/skills/intended-vs-implemented/SKILL.md.

Where is the three-layer system defined in the source code?

The canonical definition resides in pm-ai-shipping/skills/shipping-artifacts/SKILL.md, which specifies the required core documents, conditional document rules, and the tests.md structure. Implementation details for generating each layer appear in pm-ai-shipping/commands/document-app.md (layers 1–2) and pm-ai-shipping/commands/derive-tests.md (layer 3).

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