PMP-002 Engineering Standards¶
PMP-002 is the authoritative engineering standard for PotatoLabs.
It defines the engineering rules that apply to PotatoLabs products and development teams, including source-code organization, git conventions, branching, testing, review, dependencies, security, observability, and AI-assisted development.
Purpose and scope¶
These standards apply to product codebases, supporting services, and engineering workflows unless a product-specific or platform-specific exception is explicitly documented.
They do not replace PMP-001 architecture rules. They also do not replace future lifecycle or product standards where those apply.
Standard levels¶
- Mandatory standards: required for PotatoLabs work unless an approved exception exists
- Recommended practices: preferred defaults that teams should adopt when practical
- Platform capabilities: services or tooling the platform can provide, but not every product must use
- Product-specific decisions: choices that remain within a product boundary unless they violate PMP-001 or PMP-002
Covered areas¶
- Engineering Principles
- Coding Standards
- Repository Standards
- Git Conventions
- Branching Strategy
- Testing Strategy
- Code Review
- Dependency Management
- Security Engineering
- AI-Assisted Development
- Engineering Exceptions
Engineering principles¶
- Prefer clarity over cleverness
- Keep product boundaries explicit
- Make changes reproducible and reviewable
- Treat tests as a contract, not an afterthought
- Keep dependencies minimal and justified
- Fail safely and log usefully
- Document decisions that affect future maintainability
- Use AI as an accelerator, not as an authority
Source-code organization¶
Source code should be organized so that ownership and runtime boundaries are easy to identify.
Recommended patterns include:
- Separate application code from tests
- Keep configuration close to the code that consumes it
- Isolate shared libraries from product-specific modules
- Group domain logic by responsibility rather than by incidental technical layer when that improves clarity
Documentation requirements¶
Engineering work must be documented where the code alone would not make the intent obvious.
At minimum, document:
- Non-obvious design choices
- Public or internal interfaces with compatibility expectations
- Operational requirements
- Security-sensitive behavior
- Exceptions to these standards
Build reproducibility¶
Builds should be reproducible from source and documented inputs.
A reproducible build should not depend on undocumented manual state.
CI/CD engineering standards¶
CI/CD pipelines should automate the checks that matter for safety and repeatability, including validation, tests, builds, and release gates where applicable.
PMP-003 defines the lifecycle rules that connect engineering work to development flow, while PMP-001 defines the architecture boundaries the pipeline must respect.
Engineering exceptions¶
An exception is allowed only when:
- The standard would block necessary work
- The exception is documented
- The risk is understood
- The scope is limited
- There is a plan to remove or revisit the exception
Exceptions must not silently become the new standard.