Development Standards

To keep paiOS maintainable and high-quality, the project follows a set of core principles and standards. Whether you are using AI tools or writing code manually, these rules apply.

Core Principles

The project values code that is easy to read, test, and maintain. These principles serve as a compass, not a set of rigid laws.

The Pragmatic Mindset

• KISS (Keep It Simple, Stupid): Avoid over-engineering. Always choose the simplest solution.
• 80/20 Rule (Pareto Principle): Focus on the 20 percent of effort that provides 80 percent of the value.
• Pragmatic Utility: Prioritize usefulness over code perfection. Ask: “Does this help the user?”
• Low-hanging Fruits First: Start with quick wins that deliver immediate value.
• Don’t Reinvent the Wheel: Use existing, proven solutions. Only build custom when necessary.
• Flexibility and Agility: Stay adaptable. Avoid locking into rigid patterns too early.

Quality Through Early Detection

• Shift Left: Find and fix issues as early as possible in the development cycle.
• Rule of 10: A bug found in development costs 1x, in testing 10x, in production 100x. Invest early.
• CI is the Safety Net: Automated checks (fmt, clippy, tests) catch issues before they reach humans.

Code Quality

• SOLID: Ensure designs are flexible and robust.
• Clean Code: Write code for humans first. Use descriptive names and small functions.
• Hexagonal Architecture: Maintain clear boundaries between core, ports, and adapters (Engine, HAL, RPC). See Architecture Documentation.

Code Style

General Rules

• Follow the rules defined in .cursorrules.
• Contributors must sign our CLA (one-time). See CLA Guide.

Rust Style

• Use rustfmt and clippy (zero warnings target).
• Documentation comments (/// or //!) are required for all public and significant internal items.
• For stack vs heap, generics vs Box<dyn Trait>, and embedded-friendly choices, see Rust Style and Best Practices.

Definition of Done (DoD)

All changes must meet these requirements before they can be merged:

1. Correctness & Quality

• Code builds without errors (cargo build).
• All tests pass (cargo test).
• No clippy warnings.
• Solution follows KISS and Hexagonal Architecture principles.

2. Documentation

• User/Integration: New features or API changes are documented in Starlight.
• Internal: Complex logic is explained via Rust doc comments.
• Sync: Documentation is regenerated and verified via npm run build in the docs/ folder.
• See the Documentation Guide for details.

3. Compliance

• CLA has been signed (first-time contributors).
• Dependencies are license-compliant (cargo deny).
• No sensitive data committed.