# What Is the Three-Layer System in the PM Skills Marketplace Architecture? > Understand the three layer system in the PM Skills Marketplace architecture. This structure ensures code reviewability, auditability, and test coverage for AI-generated codebases. - Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills) - Tags: deep-dive - Published: 2026-06-21 --- **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`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/skills/shipping-artifacts/SKILL.md), this layer includes the following required files: - **[`architecture.md`](https://github.com/phuryn/pm-skills/blob/main/architecture.md)** – System design and high-level structure - **[`flows.md`](https://github.com/phuryn/pm-skills/blob/main/flows.md)** – End-to-end user and data flows - **[`permissions.md`](https://github.com/phuryn/pm-skills/blob/main/permissions.md)** – Access-control matrix and authorization rules - **[`variables.md`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file, conditional documents include: - **[`emails.md`](https://github.com/phuryn/pm-skills/blob/main/emails.md)** – Email templates and transaction pipelines - **[`cron.md`](https://github.com/phuryn/pm-skills/blob/main/cron.md)** – Scheduled jobs and batch processing - **[`seo.md`](https://github.com/phuryn/pm-skills/blob/main/seo.md)** – Search engine optimization routes and metadata - **[`automation.md`](https://github.com/phuryn/pm-skills/blob/main/automation.md)** – Embedded agents and workflow automations If a capability is absent, the system records this explicitly in [`architecture.md`](https://github.com/phuryn/pm-skills/blob/main/architecture.md) (e.g., "No scheduled work – no [`cron.md`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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: ```bash /pm-ai-shipping:document-app ``` This command produces [`architecture.md`](https://github.com/phuryn/pm-skills/blob/main/architecture.md), [`flows.md`](https://github.com/phuryn/pm-skills/blob/main/flows.md), [`permissions.md`](https://github.com/phuryn/pm-skills/blob/main/permissions.md), [`variables.md`](https://github.com/phuryn/pm-skills/blob/main/variables.md), and any relevant conditional documents (e.g., [`cron.md`](https://github.com/phuryn/pm-skills/blob/main/cron.md) if scheduled jobs exist) based on the current codebase state. Derive the test-coverage map from the documentation and existing tests: ```bash /pm-ai-shipping:derive-tests ``` This emits [`tests.md`](https://github.com/phuryn/pm-skills/blob/main/tests.md) containing the linked inventory of existing, proposed, and gap tests, connecting documented intent to implementation verification. Execute the complete audit workflow: ```bash /pm-ai-shipping:ship-check ``` As implemented in [`pm-ai-shipping/commands/ship-check.md`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/skills/shipping-artifacts/SKILL.md) – Defines the three-layer documentation structure, core documents, conditional documents, and the [`tests.md`](https://github.com/phuryn/pm-skills/blob/main/tests.md) format - [`pm-ai-shipping/skills/intended-vs-implemented/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/commands/document-app.md) – Automates generation of core and conditional documentation - [`pm-ai-shipping/commands/derive-tests.md`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/commands/derive-tests.md) – Generates the third-layer test-coverage map - [`pm-ai-shipping/commands/ship-check.md`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/commands/ship-check.md) – Orchestrates the full three-layer audit workflow - [`README.md`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/architecture.md), [`flows.md`](https://github.com/phuryn/pm-skills/blob/main/flows.md), [`permissions.md`](https://github.com/phuryn/pm-skills/blob/main/permissions.md), [`variables.md`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/cron.md) is absent, the system explicitly notes "No scheduled work" in [`architecture.md`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/skills/shipping-artifacts/SKILL.md), which specifies the required core documents, conditional document rules, and the [`tests.md`](https://github.com/phuryn/pm-skills/blob/main/tests.md) structure. Implementation details for generating each layer appear in [`pm-ai-shipping/commands/document-app.md`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/commands/document-app.md) (layers 1–2) and [`pm-ai-shipping/commands/derive-tests.md`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/commands/derive-tests.md) (layer 3).