@heyai-rules/pilo-masterkit 1.2.2 → 2.1.0

package/.agent/rules/php/patterns.md

@@ -0,0 +1,33 @@
+---
+paths:
+  - "**/*.php"
+  - "**/composer.json"
+---
+# PHP Patterns
+
+> This file extends [common/patterns.md](../common/patterns.md) with PHP specific content.
+
+## Thin Controllers, Explicit Services
+
+- Keep controllers focused on transport: auth, validation, serialization, status codes.
+- Move business rules into application/domain services that are easy to test without HTTP bootstrapping.
+
+## DTOs and Value Objects
+
+- Replace shape-heavy associative arrays with DTOs for requests, commands, and external API payloads.
+- Use value objects for money, identifiers, date ranges, and other constrained concepts.
+
+## Dependency Injection
+
+- Depend on interfaces or narrow service contracts, not framework globals.
+- Pass collaborators through constructors so services are testable without service-locator lookups.
+
+## Boundaries
+
+- Isolate ORM models from domain decisions when the model layer is doing more than persistence.
+- Wrap third-party SDKs behind small adapters so the rest of the codebase depends on your contract, not theirs.
+
+## Reference
+
+See skill: `api-design` for endpoint conventions and response-shape guidance.
+See skill: `laravel-patterns` for Laravel-specific architecture guidance.

package/.agent/rules/php/security.md

@@ -0,0 +1,37 @@
+---
+paths:
+  - "**/*.php"
+  - "**/composer.lock"
+  - "**/composer.json"
+---
+# PHP Security
+
+> This file extends [common/security.md](../common/security.md) with PHP specific content.
+
+## Input and Output
+
+- Validate request input at the framework boundary (`FormRequest`, Symfony Validator, or explicit DTO validation).
+- Escape output in templates by default; treat raw HTML rendering as an exception that must be justified.
+- Never trust query params, cookies, headers, or uploaded file metadata without validation.
+
+## Database Safety
+
+- Use prepared statements (`PDO`, Doctrine, Eloquent query builder) for all dynamic queries.
+- Avoid string-building SQL in controllers/views.
+- Scope ORM mass-assignment carefully and whitelist writable fields.
+
+## Secrets and Dependencies
+
+- Load secrets from environment variables or a secret manager, never from committed config files.
+- Run `composer audit` in CI and review new package maintainer trust before adding dependencies.
+- Pin major versions deliberately and remove abandoned packages quickly.
+
+## Auth and Session Safety
+
+- Use `password_hash()` / `password_verify()` for password storage.
+- Regenerate session identifiers after authentication and privilege changes.
+- Enforce CSRF protection on state-changing web requests.
+
+## Reference
+
+See skill: `laravel-security` for Laravel-specific security guidance.

package/.agent/rules/php/testing.md

@@ -0,0 +1,39 @@
+---
+paths:
+  - "**/*.php"
+  - "**/phpunit.xml"
+  - "**/phpunit.xml.dist"
+  - "**/composer.json"
+---
+# PHP Testing
+
+> This file extends [common/testing.md](../common/testing.md) with PHP specific content.
+
+## Framework
+
+Use **PHPUnit** as the default test framework. If **Pest** is configured in the project, prefer Pest for new tests and avoid mixing frameworks.
+
+## Coverage
+
+```bash
+vendor/bin/phpunit --coverage-text
+# or
+vendor/bin/pest --coverage
+```
+
+Prefer **pcov** or **Xdebug** in CI, and keep coverage thresholds in CI rather than as tribal knowledge.
+
+## Test Organization
+
+- Separate fast unit tests from framework/database integration tests.
+- Use factory/builders for fixtures instead of large hand-written arrays.
+- Keep HTTP/controller tests focused on transport and validation; move business rules into service-level tests.
+
+## Inertia
+
+If the project uses Inertia.js, prefer `assertInertia` with `AssertableInertia` to verify component names and props instead of raw JSON assertions.
+
+## Reference
+
+See skill: `tdd-workflow` for the repo-wide RED -> GREEN -> REFACTOR loop.
+See skill: `laravel-tdd` for Laravel-specific testing patterns (PHPUnit and Pest).

package/.agent/rules/python/coding-style.md

@@ -0,0 +1,42 @@
+---
+paths:
+  - "**/*.py"
+  - "**/*.pyi"
+---
+# Python Coding Style
+
+> This file extends [common/coding-style.md](../common/coding-style.md) with Python specific content.
+
+## Standards
+
+- Follow **PEP 8** conventions
+- Use **type annotations** on all function signatures
+
+## Immutability
+
+Prefer immutable data structures:
+
+```python
+from dataclasses import dataclass
+
+@dataclass(frozen=True)
+class User:
+    name: str
+    email: str
+
+from typing import NamedTuple
+
+class Point(NamedTuple):
+    x: float
+    y: float
+```
+
+## Formatting
+
+- **black** for code formatting
+- **isort** for import sorting
+- **ruff** for linting
+
+## Reference
+
+See skill: `python-patterns` for comprehensive Python idioms and patterns.

package/.agent/rules/python/hooks.md

@@ -0,0 +1,19 @@
+---
+paths:
+  - "**/*.py"
+  - "**/*.pyi"
+---
+# Python Hooks
+
+> This file extends [common/hooks.md](../common/hooks.md) with Python specific content.
+
+## PostToolUse Hooks
+
+Configure in `~/.claude/settings.json`:
+
+- **black/ruff**: Auto-format `.py` files after edit
+- **mypy/pyright**: Run type checking after editing `.py` files
+
+## Warnings
+
+- Warn about `print()` statements in edited files (use `logging` module instead)

package/.agent/rules/python/patterns.md

@@ -0,0 +1,39 @@
+---
+paths:
+  - "**/*.py"
+  - "**/*.pyi"
+---
+# Python Patterns
+
+> This file extends [common/patterns.md](../common/patterns.md) with Python specific content.
+
+## Protocol (Duck Typing)
+
+```python
+from typing import Protocol
+
+class Repository(Protocol):
+    def find_by_id(self, id: str) -> dict | None: ...
+    def save(self, entity: dict) -> dict: ...
+```
+
+## Dataclasses as DTOs
+
+```python
+from dataclasses import dataclass
+
+@dataclass
+class CreateUserRequest:
+    name: str
+    email: str
+    age: int | None = None
+```
+
+## Context Managers & Generators
+
+- Use context managers (`with` statement) for resource management
+- Use generators for lazy evaluation and memory-efficient iteration
+
+## Reference
+
+See skill: `python-patterns` for comprehensive patterns including decorators, concurrency, and package organization.

package/.agent/rules/python/security.md

@@ -0,0 +1,30 @@
+---
+paths:
+  - "**/*.py"
+  - "**/*.pyi"
+---
+# Python Security
+
+> This file extends [common/security.md](../common/security.md) with Python specific content.
+
+## Secret Management
+
+```python
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+api_key = os.environ["OPENAI_API_KEY"]  # Raises KeyError if missing
+```
+
+## Security Scanning
+
+- Use **bandit** for static security analysis:
+  ```bash
+  bandit -r src/
+  ```
+
+## Reference
+
+See skill: `django-security` for Django-specific security guidelines (if applicable).

package/.agent/rules/python/testing.md

@@ -0,0 +1,38 @@
+---
+paths:
+  - "**/*.py"
+  - "**/*.pyi"
+---
+# Python Testing
+
+> This file extends [common/testing.md](../common/testing.md) with Python specific content.
+
+## Framework
+
+Use **pytest** as the testing framework.
+
+## Coverage
+
+```bash
+pytest --cov=src --cov-report=term-missing
+```
+
+## Test Organization
+
+Use `pytest.mark` for test categorization:
+
+```python
+import pytest
+
+@pytest.mark.unit
+def test_calculate_total():
+    ...
+
+@pytest.mark.integration
+def test_database_connection():
+    ...
+```
+
+## Reference
+
+See skill: `python-testing` for detailed pytest patterns and fixtures.

package/.agent/rules/readme.md

@@ -0,0 +1,111 @@
+# Rules
+## Structure
+
+Rules are organized into a **common** layer plus **language-specific** directories:
+
+```
+rules/
+├── common/          # Language-agnostic principles (always install)
+│   ├── coding-style.md
+│   ├── git-workflow.md
+│   ├── testing.md
+│   ├── performance.md
+│   ├── patterns.md
+│   ├── hooks.md
+│   ├── agents.md
+│   └── security.md
+├── typescript/      # TypeScript/JavaScript specific
+├── python/          # Python specific
+├── golang/          # Go specific
+├── web/             # Web and frontend specific
+├── swift/           # Swift specific
+└── php/             # PHP specific
+```
+
+- **common/** contains universal principles — no language-specific code examples.
+- **Language directories** extend the common rules with framework-specific patterns, tools, and code examples. Each file references its common counterpart.
+
+## Installation
+
+### Option 1: Install Script (Recommended)
+
+```bash
+# Install common + one or more language-specific rule sets
+./install.sh typescript
+./install.sh python
+./install.sh golang
+./install.sh web
+./install.sh swift
+./install.sh php
+
+# Install multiple languages at once
+./install.sh typescript python
+```
+
+### Option 2: Manual Installation
+
+> **Important:** Copy entire directories — do NOT flatten with `/*`.
+> Common and language-specific directories contain files with the same names.
+> Flattening them into one directory causes language-specific files to overwrite
+> common rules, and breaks the relative `../common/` references used by
+> language-specific files.
+
+```bash
+# Install common rules (required for all projects)
+cp -r rules/common ~/.claude/rules/common
+
+# Install language-specific rules based on your project's tech stack
+cp -r rules/typescript ~/.claude/rules/typescript
+cp -r rules/python ~/.claude/rules/python
+cp -r rules/golang ~/.claude/rules/golang
+cp -r rules/web ~/.claude/rules/web
+cp -r rules/swift ~/.claude/rules/swift
+cp -r rules/php ~/.claude/rules/php
+
+# Attention ! ! ! Configure according to your actual project requirements; the configuration here is for reference only.
+```
+
+## Rules vs Skills
+
+- **Rules** define standards, conventions, and checklists that apply broadly (e.g., "80% test coverage", "no hardcoded secrets").
+- **Skills** (`skills/` directory) provide deep, actionable reference material for specific tasks (e.g., `python-patterns`, `golang-testing`).
+
+Language-specific rule files reference relevant skills where appropriate. Rules tell you *what* to do; skills tell you *how* to do it.
+
+## Adding a New Language
+
+To add support for a new language (e.g., `rust/`):
+
+1. Create a `rules/rust/` directory
+2. Add files that extend the common rules:
+   - `coding-style.md` — formatting tools, idioms, error handling patterns
+   - `testing.md` — test framework, coverage tools, test organization
+   - `patterns.md` — language-specific design patterns
+   - `hooks.md` — PostToolUse hooks for formatters, linters, type checkers
+   - `security.md` — secret management, security scanning tools
+3. Each file should start with:
+   ```
+   > This file extends [common/xxx.md](../common/xxx.md) with <Language> specific content.
+   ```
+4. Reference existing skills if available, or create new ones under `skills/`.
+
+For non-language domains like `web/`, follow the same layered pattern when there is enough reusable domain-specific guidance to justify a standalone ruleset.
+
+## Rule Priority
+
+When language-specific rules and common rules conflict, **language-specific rules take precedence** (specific overrides general). This follows the standard layered configuration pattern (similar to CSS specificity or `.gitignore` precedence).
+
+- `rules/common/` defines universal defaults applicable to all projects.
+- `rules/golang/`, `rules/python/`, `rules/swift/`, `rules/php/`, `rules/typescript/`, etc. override those defaults where language idioms differ.
+
+### Example
+
+`common/coding-style.md` recommends immutability as a default principle. A language-specific `golang/coding-style.md` can override this:
+
+> Idiomatic Go uses pointer receivers for struct mutation — see [common/coding-style.md](../common/coding-style.md) for the general principle, but Go-idiomatic mutation is preferred here.
+
+### Common rules with override notes
+
+Rules in `rules/common/` that may be overridden by language-specific files are marked with:
+
+> **Language note**: This rule may be overridden by language-specific rules for languages where this pattern is not idiomatic.

package/.agent/rules/rust/coding-style.md

@@ -0,0 +1,151 @@
+---
+paths:
+  - "**/*.rs"
+---
+# Rust Coding Style
+
+> This file extends [common/coding-style.md](../common/coding-style.md) with Rust-specific content.
+
+## Formatting
+
+- **rustfmt** for enforcement — always run `cargo fmt` before committing
+- **clippy** for lints — `cargo clippy -- -D warnings` (treat warnings as errors)
+- 4-space indent (rustfmt default)
+- Max line width: 100 characters (rustfmt default)
+
+## Immutability
+
+Rust variables are immutable by default — embrace this:
+
+- Use `let` by default; only use `let mut` when mutation is required
+- Prefer returning new values over mutating in place
+- Use `Cow<'_, T>` when a function may or may not need to allocate
+
+```rust
+use std::borrow::Cow;
+
+// GOOD — immutable by default, new value returned
+fn normalize(input: &str) -> Cow<'_, str> {
+    if input.contains(' ') {
+        Cow::Owned(input.replace(' ', "_"))
+    } else {
+        Cow::Borrowed(input)
+    }
+}
+
+// BAD — unnecessary mutation
+fn normalize_bad(input: &mut String) {
+    *input = input.replace(' ', "_");
+}
+```
+
+## Naming
+
+Follow standard Rust conventions:
+- `snake_case` for functions, methods, variables, modules, crates
+- `PascalCase` (UpperCamelCase) for types, traits, enums, type parameters
+- `SCREAMING_SNAKE_CASE` for constants and statics
+- Lifetimes: short lowercase (`'a`, `'de`) — descriptive names for complex cases (`'input`)
+
+## Ownership and Borrowing
+
+- Borrow (`&T`) by default; take ownership only when you need to store or consume
+- Never clone to satisfy the borrow checker without understanding the root cause
+- Accept `&str` over `String`, `&[T]` over `Vec<T>` in function parameters
+- Use `impl Into<String>` for constructors that need to own a `String`
+
+```rust
+// GOOD — borrows when ownership isn't needed
+fn word_count(text: &str) -> usize {
+    text.split_whitespace().count()
+}
+
+// GOOD — takes ownership in constructor via Into
+fn new(name: impl Into<String>) -> Self {
+    Self { name: name.into() }
+}
+
+// BAD — takes String when &str suffices
+fn word_count_bad(text: String) -> usize {
+    text.split_whitespace().count()
+}
+```
+
+## Error Handling
+
+- Use `Result<T, E>` and `?` for propagation — never `unwrap()` in production code
+- **Libraries**: define typed errors with `thiserror`
+- **Applications**: use `anyhow` for flexible error context
+- Add context with `.with_context(|| format!("failed to ..."))?`
+- Reserve `unwrap()` / `expect()` for tests and truly unreachable states
+
+```rust
+// GOOD — library error with thiserror
+#[derive(Debug, thiserror::Error)]
+pub enum ConfigError {
+    #[error("failed to read config: {0}")]
+    Io(#[from] std::io::Error),
+    #[error("invalid config format: {0}")]
+    Parse(String),
+}
+
+// GOOD — application error with anyhow
+use anyhow::Context;
+
+fn load_config(path: &str) -> anyhow::Result<Config> {
+    let content = std::fs::read_to_string(path)
+        .with_context(|| format!("failed to read {path}"))?;
+    toml::from_str(&content)
+        .with_context(|| format!("failed to parse {path}"))
+}
+```
+
+## Iterators Over Loops
+
+Prefer iterator chains for transformations; use loops for complex control flow:
+
+```rust
+// GOOD — declarative and composable
+let active_emails: Vec<&str> = users.iter()
+    .filter(|u| u.is_active)
+    .map(|u| u.email.as_str())
+    .collect();
+
+// GOOD — loop for complex logic with early returns
+for user in &users {
+    if let Some(verified) = verify_email(&user.email)? {
+        send_welcome(&verified)?;
+    }
+}
+```
+
+## Module Organization
+
+Organize by domain, not by type:
+
+```text
+src/
+├── main.rs
+├── lib.rs
+├── auth/           # Domain module
+│   ├── mod.rs
+│   ├── token.rs
+│   └── middleware.rs
+├── orders/         # Domain module
+│   ├── mod.rs
+│   ├── model.rs
+│   └── service.rs
+└── db/             # Infrastructure
+    ├── mod.rs
+    └── pool.rs
+```
+
+## Visibility
+
+- Default to private; use `pub(crate)` for internal sharing
+- Only mark `pub` what is part of the crate's public API
+- Re-export public API from `lib.rs`
+
+## References
+
+See skill: `rust-patterns` for comprehensive Rust idioms and patterns.

package/.agent/rules/rust/hooks.md

@@ -0,0 +1,16 @@
+---
+paths:
+  - "**/*.rs"
+  - "**/Cargo.toml"
+---
+# Rust Hooks
+
+> This file extends [common/hooks.md](../common/hooks.md) with Rust-specific content.
+
+## PostToolUse Hooks
+
+Configure in `~/.claude/settings.json`:
+
+- **cargo fmt**: Auto-format `.rs` files after edit
+- **cargo clippy**: Run lint checks after editing Rust files
+- **cargo check**: Verify compilation after changes (faster than `cargo build`)