@heyai-rules/pilo-masterkit 1.2.2 → 3.1.0

package/.agent/rules/rust/testing.md

@@ -0,0 +1,154 @@
+---
+paths:
+  - "**/*.rs"
+---
+# Rust Testing
+
+> This file extends [common/testing.md](../common/testing.md) with Rust-specific content.
+
+## Test Framework
+
+- **`#[test]`** with `#[cfg(test)]` modules for unit tests
+- **rstest** for parameterized tests and fixtures
+- **proptest** for property-based testing
+- **mockall** for trait-based mocking
+- **`#[tokio::test]`** for async tests
+
+## Test Organization
+
+```text
+my_crate/
+├── src/
+│   ├── lib.rs           # Unit tests in #[cfg(test)] modules
+│   ├── auth/
+│   │   └── mod.rs       # #[cfg(test)] mod tests { ... }
+│   └── orders/
+│       └── service.rs   # #[cfg(test)] mod tests { ... }
+├── tests/               # Integration tests (each file = separate binary)
+│   ├── api_test.rs
+│   ├── db_test.rs
+│   └── common/          # Shared test utilities
+│       └── mod.rs
+└── benches/             # Criterion benchmarks
+    └── benchmark.rs
+```
+
+Unit tests go inside `#[cfg(test)]` modules in the same file. Integration tests go in `tests/`.
+
+## Unit Test Pattern
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn creates_user_with_valid_email() {
+        let user = User::new("Alice", "alice@example.com").unwrap();
+        assert_eq!(user.name, "Alice");
+    }
+
+    #[test]
+    fn rejects_invalid_email() {
+        let result = User::new("Bob", "not-an-email");
+        assert!(result.is_err());
+        assert!(result.unwrap_err().to_string().contains("invalid email"));
+    }
+}
+```
+
+## Parameterized Tests
+
+```rust
+use rstest::rstest;
+
+#[rstest]
+#[case("hello", 5)]
+#[case("", 0)]
+#[case("rust", 4)]
+fn test_string_length(#[case] input: &str, #[case] expected: usize) {
+    assert_eq!(input.len(), expected);
+}
+```
+
+## Async Tests
+
+```rust
+#[tokio::test]
+async fn fetches_data_successfully() {
+    let client = TestClient::new().await;
+    let result = client.get("/data").await;
+    assert!(result.is_ok());
+}
+```
+
+## Mocking with mockall
+
+Define traits in production code; generate mocks in test modules:
+
+```rust
+// Production trait — pub so integration tests can import it
+pub trait UserRepository {
+    fn find_by_id(&self, id: u64) -> Option<User>;
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use mockall::predicate::eq;
+
+    mockall::mock! {
+        pub Repo {}
+        impl UserRepository for Repo {
+            fn find_by_id(&self, id: u64) -> Option<User>;
+        }
+    }
+
+    #[test]
+    fn service_returns_user_when_found() {
+        let mut mock = MockRepo::new();
+        mock.expect_find_by_id()
+            .with(eq(42))
+            .times(1)
+            .returning(|_| Some(User { id: 42, name: "Alice".into() }));
+
+        let service = UserService::new(Box::new(mock));
+        let user = service.get_user(42).unwrap();
+        assert_eq!(user.name, "Alice");
+    }
+}
+```
+
+## Test Naming
+
+Use descriptive names that explain the scenario:
+- `creates_user_with_valid_email()`
+- `rejects_order_when_insufficient_stock()`
+- `returns_none_when_not_found()`
+
+## Coverage
+
+- Target 80%+ line coverage
+- Use **cargo-llvm-cov** for coverage reporting
+- Focus on business logic — exclude generated code and FFI bindings
+
+```bash
+cargo llvm-cov                       # Summary
+cargo llvm-cov --html                # HTML report
+cargo llvm-cov --fail-under-lines 80 # Fail if below threshold
+```
+
+## Testing Commands
+
+```bash
+cargo test                       # Run all tests
+cargo test -- --nocapture        # Show println output
+cargo test test_name             # Run tests matching pattern
+cargo test --lib                 # Unit tests only
+cargo test --test api_test       # Specific integration test (tests/api_test.rs)
+cargo test --doc                 # Doc tests only
+```
+
+## References
+
+See skill: `rust-testing` for comprehensive testing patterns including property-based testing, fixtures, and benchmarking with Criterion.

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

@@ -0,0 +1,47 @@
+---
+paths:
+  - "**/*.swift"
+  - "**/Package.swift"
+---
+# Swift Coding Style
+
+> This file extends [common/coding-style.md](../common/coding-style.md) with Swift specific content.
+
+## Formatting
+
+- **SwiftFormat** for auto-formatting, **SwiftLint** for style enforcement
+- `swift-format` is bundled with Xcode 16+ as an alternative
+
+## Immutability
+
+- Prefer `let` over `var` — define everything as `let` and only change to `var` if the compiler requires it
+- Use `struct` with value semantics by default; use `class` only when identity or reference semantics are needed
+
+## Naming
+
+Follow [Apple API Design Guidelines](https://www.swift.org/documentation/api-design-guidelines/):
+
+- Clarity at the point of use — omit needless words
+- Name methods and properties for their roles, not their types
+- Use `static let` for constants over global constants
+
+## Error Handling
+
+Use typed throws (Swift 6+) and pattern matching:
+
+```swift
+func load(id: String) throws(LoadError) -> Item {
+    guard let data = try? read(from: path) else {
+        throw .fileNotFound(id)
+    }
+    return try decode(data)
+}
+```
+
+## Concurrency
+
+Enable Swift 6 strict concurrency checking. Prefer:
+
+- `Sendable` value types for data crossing isolation boundaries
+- Actors for shared mutable state
+- Structured concurrency (`async let`, `TaskGroup`) over unstructured `Task {}`

package/.agent/rules/swift/hooks.md

@@ -0,0 +1,20 @@
+---
+paths:
+  - "**/*.swift"
+  - "**/Package.swift"
+---
+# Swift Hooks
+
+> This file extends [common/hooks.md](../common/hooks.md) with Swift specific content.
+
+## PostToolUse Hooks
+
+Configure in `~/.claude/settings.json`:
+
+- **SwiftFormat**: Auto-format `.swift` files after edit
+- **SwiftLint**: Run lint checks after editing `.swift` files
+- **swift build**: Type-check modified packages after edit
+
+## Warning
+
+Flag `print()` statements — use `os.Logger` or structured logging instead for production code.

package/.agent/rules/swift/patterns.md

@@ -0,0 +1,66 @@
+---
+paths:
+  - "**/*.swift"
+  - "**/Package.swift"
+---
+# Swift Patterns
+
+> This file extends [common/patterns.md](../common/patterns.md) with Swift specific content.
+
+## Protocol-Oriented Design
+
+Define small, focused protocols. Use protocol extensions for shared defaults:
+
+```swift
+protocol Repository: Sendable {
+    associatedtype Item: Identifiable & Sendable
+    func find(by id: Item.ID) async throws -> Item?
+    func save(_ item: Item) async throws
+}
+```
+
+## Value Types
+
+- Use structs for data transfer objects and models
+- Use enums with associated values to model distinct states:
+
+```swift
+enum LoadState<T: Sendable>: Sendable {
+    case idle
+    case loading
+    case loaded(T)
+    case failed(Error)
+}
+```
+
+## Actor Pattern
+
+Use actors for shared mutable state instead of locks or dispatch queues:
+
+```swift
+actor Cache<Key: Hashable & Sendable, Value: Sendable> {
+    private var storage: [Key: Value] = [:]
+
+    func get(_ key: Key) -> Value? { storage[key] }
+    func set(_ key: Key, value: Value) { storage[key] = value }
+}
+```
+
+## Dependency Injection
+
+Inject protocols with default parameters — production uses defaults, tests inject mocks:
+
+```swift
+struct UserService {
+    private let repository: any UserRepository
+
+    init(repository: any UserRepository = DefaultUserRepository()) {
+        self.repository = repository
+    }
+}
+```
+
+## References
+
+See skill: `swift-actor-persistence` for actor-based persistence patterns.
+See skill: `swift-protocol-di-testing` for protocol-based DI and testing.

package/.agent/rules/swift/security.md

@@ -0,0 +1,33 @@
+---
+paths:
+  - "**/*.swift"
+  - "**/Package.swift"
+---
+# Swift Security
+
+> This file extends [common/security.md](../common/security.md) with Swift specific content.
+
+## Secret Management
+
+- Use **Keychain Services** for sensitive data (tokens, passwords, keys) — never `UserDefaults`
+- Use environment variables or `.xcconfig` files for build-time secrets
+- Never hardcode secrets in source — decompilation tools extract them trivially
+
+```swift
+let apiKey = ProcessInfo.processInfo.environment["API_KEY"]
+guard let apiKey, !apiKey.isEmpty else {
+    fatalError("API_KEY not configured")
+}
+```
+
+## Transport Security
+
+- App Transport Security (ATS) is enforced by default — do not disable it
+- Use certificate pinning for critical endpoints
+- Validate all server certificates
+
+## Input Validation
+
+- Sanitize all user input before display to prevent injection
+- Use `URL(string:)` with validation rather than force-unwrapping
+- Validate data from external sources (APIs, deep links, pasteboard) before processing

package/.agent/rules/swift/testing.md

@@ -0,0 +1,45 @@
+---
+paths:
+  - "**/*.swift"
+  - "**/Package.swift"
+---
+# Swift Testing
+
+> This file extends [common/testing.md](../common/testing.md) with Swift specific content.
+
+## Framework
+
+Use **Swift Testing** (`import Testing`) for new tests. Use `@Test` and `#expect`:
+
+```swift
+@Test("User creation validates email")
+func userCreationValidatesEmail() throws {
+    #expect(throws: ValidationError.invalidEmail) {
+        try User(email: "not-an-email")
+    }
+}
+```
+
+## Test Isolation
+
+Each test gets a fresh instance — set up in `init`, tear down in `deinit`. No shared mutable state between tests.
+
+## Parameterized Tests
+
+```swift
+@Test("Validates formats", arguments: ["json", "xml", "csv"])
+func validatesFormat(format: String) throws {
+    let parser = try Parser(format: format)
+    #expect(parser.isValid)
+}
+```
+
+## Coverage
+
+```bash
+swift test --enable-code-coverage
+```
+
+## Reference
+
+See skill: `swift-protocol-di-testing` for protocol-based dependency injection and mock patterns with Swift Testing.

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

@@ -0,0 +1,199 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+---
+# TypeScript/JavaScript Coding Style
+
+> This file extends [common/coding-style.md](../common/coding-style.md) with TypeScript/JavaScript specific content.
+
+## Types and Interfaces
+
+Use types to make public APIs, shared models, and component props explicit, readable, and reusable.
+
+### Public APIs
+
+- Add parameter and return types to exported functions, shared utilities, and public class methods
+- Let TypeScript infer obvious local variable types
+- Extract repeated inline object shapes into named types or interfaces
+
+```typescript
+// WRONG: Exported function without explicit types
+export function formatUser(user) {
+  return `${user.firstName} ${user.lastName}`
+}
+
+// CORRECT: Explicit types on public APIs
+interface User {
+  firstName: string
+  lastName: string
+}
+
+export function formatUser(user: User): string {
+  return `${user.firstName} ${user.lastName}`
+}
+```
+
+### Interfaces vs. Type Aliases
+
+- Use `interface` for object shapes that may be extended or implemented
+- Use `type` for unions, intersections, tuples, mapped types, and utility types
+- Prefer string literal unions over `enum` unless an `enum` is required for interoperability
+
+```typescript
+interface User {
+  id: string
+  email: string
+}
+
+type UserRole = 'admin' | 'member'
+type UserWithRole = User & {
+  role: UserRole
+}
+```
+
+### Avoid `any`
+
+- Avoid `any` in application code
+- Use `unknown` for external or untrusted input, then narrow it safely
+- Use generics when a value's type depends on the caller
+
+```typescript
+// WRONG: any removes type safety
+function getErrorMessage(error: any) {
+  return error.message
+}
+
+// CORRECT: unknown forces safe narrowing
+function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message
+  }
+
+  return 'Unexpected error'
+}
+```
+
+### React Props
+
+- Define component props with a named `interface` or `type`
+- Type callback props explicitly
+- Do not use `React.FC` unless there is a specific reason to do so
+
+```typescript
+interface User {
+  id: string
+  email: string
+}
+
+interface UserCardProps {
+  user: User
+  onSelect: (id: string) => void
+}
+
+function UserCard({ user, onSelect }: UserCardProps) {
+  return <button onClick={() => onSelect(user.id)}>{user.email}</button>
+}
+```
+
+### JavaScript Files
+
+- In `.js` and `.jsx` files, use JSDoc when types improve clarity and a TypeScript migration is not practical
+- Keep JSDoc aligned with runtime behavior
+
+```javascript
+/**
+ * @param {{ firstName: string, lastName: string }} user
+ * @returns {string}
+ */
+export function formatUser(user) {
+  return `${user.firstName} ${user.lastName}`
+}
+```
+
+## Immutability
+
+Use spread operator for immutable updates:
+
+```typescript
+interface User {
+  id: string
+  name: string
+}
+
+// WRONG: Mutation
+function updateUser(user: User, name: string): User {
+  user.name = name // MUTATION!
+  return user
+}
+
+// CORRECT: Immutability
+function updateUser(user: Readonly<User>, name: string): User {
+  return {
+    ...user,
+    name
+  }
+}
+```
+
+## Error Handling
+
+Use async/await with try-catch and narrow unknown errors safely:
+
+```typescript
+interface User {
+  id: string
+  email: string
+}
+
+declare function riskyOperation(userId: string): Promise<User>
+
+function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message
+  }
+
+  return 'Unexpected error'
+}
+
+const logger = {
+  error: (message: string, error: unknown) => {
+    // Replace with your production logger (for example, pino or winston).
+  }
+}
+
+async function loadUser(userId: string): Promise<User> {
+  try {
+    const result = await riskyOperation(userId)
+    return result
+  } catch (error: unknown) {
+    logger.error('Operation failed', error)
+    throw new Error(getErrorMessage(error))
+  }
+}
+```
+
+## Input Validation
+
+Use Zod for schema-based validation and infer types from the schema:
+
+```typescript
+import { z } from 'zod'
+
+const userSchema = z.object({
+  email: z.string().email(),
+  age: z.number().int().min(0).max(150)
+})
+
+type UserInput = z.infer<typeof userSchema>
+
+const validated: UserInput = userSchema.parse(input)
+```
+
+## Console.log
+
+- No `console.log` statements in production code
+- Use proper logging libraries instead
+- See hooks for automatic detection

package/.agent/rules/typescript/hooks.md

@@ -0,0 +1,22 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+---
+# TypeScript/JavaScript Hooks
+
+> This file extends [common/hooks.md](../common/hooks.md) with TypeScript/JavaScript specific content.
+
+## PostToolUse Hooks
+
+Configure in `~/.claude/settings.json`:
+
+- **Prettier**: Auto-format JS/TS files after edit
+- **TypeScript check**: Run `tsc` after editing `.ts`/`.tsx` files
+- **console.log warning**: Warn about `console.log` in edited files
+
+## Stop Hooks
+
+- **console.log audit**: Check all modified files for `console.log` before session ends

package/.agent/rules/typescript/patterns.md

@@ -0,0 +1,52 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+---
+# TypeScript/JavaScript Patterns
+
+> This file extends [common/patterns.md](../common/patterns.md) with TypeScript/JavaScript specific content.
+
+## API Response Format
+
+```typescript
+interface ApiResponse<T> {
+  success: boolean
+  data?: T
+  error?: string
+  meta?: {
+    total: number
+    page: number
+    limit: number
+  }
+}
+```
+
+## Custom Hooks Pattern
+
+```typescript
+export function useDebounce<T>(value: T, delay: number): T {
+  const [debouncedValue, setDebouncedValue] = useState<T>(value)
+
+  useEffect(() => {
+    const handler = setTimeout(() => setDebouncedValue(value), delay)
+    return () => clearTimeout(handler)
+  }, [value, delay])
+
+  return debouncedValue
+}
+```
+
+## Repository Pattern
+
+```typescript
+interface Repository<T> {
+  findAll(filters?: Filters): Promise<T[]>
+  findById(id: string): Promise<T | null>
+  create(data: CreateDto): Promise<T>
+  update(id: string, data: UpdateDto): Promise<T>
+  delete(id: string): Promise<void>
+}
+```

package/.agent/rules/typescript/security.md

@@ -0,0 +1,28 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+---
+# TypeScript/JavaScript Security
+
+> This file extends [common/security.md](../common/security.md) with TypeScript/JavaScript specific content.
+
+## Secret Management
+
+```typescript
+// NEVER: Hardcoded secrets
+const apiKey = "sk-proj-xxxxx"
+
+// ALWAYS: Environment variables
+const apiKey = process.env.OPENAI_API_KEY
+
+if (!apiKey) {
+  throw new Error('OPENAI_API_KEY not configured')
+}
+```
+
+## Agent Support
+
+- Use **security-reviewer** skill for comprehensive security audits

package/.agent/rules/typescript/testing.md

@@ -0,0 +1,18 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+---
+# TypeScript/JavaScript Testing
+
+> This file extends [common/testing.md](../common/testing.md) with TypeScript/JavaScript specific content.
+
+## E2E Testing
+
+Use **Playwright** as the E2E testing framework for critical user flows.
+
+## Agent Support
+
+- **e2e-runner** - Playwright E2E testing specialist