@heyai-rules/pilo-masterkit 1.2.2 → 3.1.0

package/.agent/rules/common/git-workflow.md

@@ -0,0 +1,24 @@
+# Git Workflow
+
+## Commit Message Format
+```
+<type>: <description>
+
+<optional body>
+```
+
+Types: feat, fix, refactor, docs, test, chore, perf, ci
+
+Note: Attribution disabled globally via ~/.claude/settings.json.
+
+## Pull Request Workflow
+
+When creating PRs:
+1. Analyze full commit history (not just latest commit)
+2. Use `git diff [base-branch]...HEAD` to see all changes
+3. Draft comprehensive PR summary
+4. Include test plan with TODOs
+5. Push with `-u` flag if new branch
+
+> For the full development process (planning, TDD, code review) before git operations,
+> see [development-workflow.md](./development-workflow.md).

package/.agent/rules/common/hooks.md

@@ -0,0 +1,30 @@
+# Hooks System
+
+## Hook Types
+
+- **PreToolUse**: Before tool execution (validation, parameter modification)
+- **PostToolUse**: After tool execution (auto-format, checks)
+- **Stop**: When session ends (final verification)
+
+## Auto-Accept Permissions
+
+Use with caution:
+- Enable for trusted, well-defined plans
+- Disable for exploratory work
+- Never use dangerously-skip-permissions flag
+- Configure `allowedTools` in `~/.claude.json` instead
+
+## TodoWrite Best Practices
+
+Use TodoWrite tool to:
+- Track progress on multi-step tasks
+- Verify understanding of instructions
+- Enable real-time steering
+- Show granular implementation steps
+
+Todo list reveals:
+- Out of order steps
+- Missing items
+- Extra unnecessary items
+- Wrong granularity
+- Misinterpreted requirements

package/.agent/rules/common/patterns.md

@@ -0,0 +1,31 @@
+# Common Patterns
+
+## Skeleton Projects
+
+When implementing new functionality:
+1. Search for battle-tested skeleton projects
+2. Use parallel agents to evaluate options:
+   - Security assessment
+   - Extensibility analysis
+   - Relevance scoring
+   - Implementation planning
+3. Clone best match as foundation
+4. Iterate within proven structure
+
+## Design Patterns
+
+### Repository Pattern
+
+Encapsulate data access behind a consistent interface:
+- Define standard operations: findAll, findById, create, update, delete
+- Concrete implementations handle storage details (database, API, file, etc.)
+- Business logic depends on the abstract interface, not the storage mechanism
+- Enables easy swapping of data sources and simplifies testing with mocks
+
+### API Response Format
+
+Use a consistent envelope for all API responses:
+- Include a success/status indicator
+- Include the data payload (nullable on error)
+- Include an error message field (nullable on success)
+- Include metadata for paginated responses (total, page, limit)

package/.agent/rules/common/performance.md

@@ -0,0 +1,55 @@
+# Performance Optimization
+
+## Model Selection Strategy
+
+**Haiku 4.5** (90% of Sonnet capability, 3x cost savings):
+- Lightweight agents with frequent invocation
+- Pair programming and code generation
+- Worker agents in multi-agent systems
+
+**Sonnet 4.6** (Best coding model):
+- Main development work
+- Orchestrating multi-agent workflows
+- Complex coding tasks
+
+**Opus 4.5** (Deepest reasoning):
+- Complex architectural decisions
+- Maximum reasoning requirements
+- Research and analysis tasks
+
+## Context Window Management
+
+Avoid last 20% of context window for:
+- Large-scale refactoring
+- Feature implementation spanning multiple files
+- Debugging complex interactions
+
+Lower context sensitivity tasks:
+- Single-file edits
+- Independent utility creation
+- Documentation updates
+- Simple bug fixes
+
+## Extended Thinking + Plan Mode
+
+Extended thinking is enabled by default, reserving up to 31,999 tokens for internal reasoning.
+
+Control extended thinking via:
+- **Toggle**: Option+T (macOS) / Alt+T (Windows/Linux)
+- **Config**: Set `alwaysThinkingEnabled` in `~/.claude/settings.json`
+- **Budget cap**: `export MAX_THINKING_TOKENS=10000`
+- **Verbose mode**: Ctrl+O to see thinking output
+
+For complex tasks requiring deep reasoning:
+1. Ensure extended thinking is enabled (on by default)
+2. Enable **Plan Mode** for structured approach
+3. Use multiple critique rounds for thorough analysis
+4. Use split role sub-agents for diverse perspectives
+
+## Build Troubleshooting
+
+If build fails:
+1. Use **build-error-resolver** agent
+2. Analyze error messages
+3. Fix incrementally
+4. Verify after each fix

package/.agent/rules/common/security.md

@@ -0,0 +1,29 @@
+# Security Guidelines
+
+## Mandatory Security Checks
+
+Before ANY commit:
+- [ ] No hardcoded secrets (API keys, passwords, tokens)
+- [ ] All user inputs validated
+- [ ] SQL injection prevention (parameterized queries)
+- [ ] XSS prevention (sanitized HTML)
+- [ ] CSRF protection enabled
+- [ ] Authentication/authorization verified
+- [ ] Rate limiting on all endpoints
+- [ ] Error messages don't leak sensitive data
+
+## Secret Management
+
+- NEVER hardcode secrets in source code
+- ALWAYS use environment variables or a secret manager
+- Validate that required secrets are present at startup
+- Rotate any secrets that may have been exposed
+
+## Security Response Protocol
+
+If security issue found:
+1. STOP immediately
+2. Use **security-reviewer** agent
+3. Fix CRITICAL issues before continuing
+4. Rotate any exposed secrets
+5. Review entire codebase for similar issues

package/.agent/rules/common/testing.md

@@ -0,0 +1,29 @@
+# Testing Requirements
+
+## Minimum Test Coverage: 80%
+
+Test Types (ALL required):
+1. **Unit Tests** - Individual functions, utilities, components
+2. **Integration Tests** - API endpoints, database operations
+3. **E2E Tests** - Critical user flows (framework chosen per language)
+
+## Test-Driven Development
+
+MANDATORY workflow:
+1. Write test first (RED)
+2. Run test - it should FAIL
+3. Write minimal implementation (GREEN)
+4. Run test - it should PASS
+5. Refactor (IMPROVE)
+6. Verify coverage (80%+)
+
+## Troubleshooting Test Failures
+
+1. Use **tdd-guide** agent
+2. Check test isolation
+3. Verify mocks are correct
+4. Fix implementation, not tests (unless tests are wrong)
+
+## Agent Support
+
+- **tdd-guide** - Use PROACTIVELY for new features, enforces write-tests-first

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

@@ -0,0 +1,44 @@
+---
+paths:
+  - "**/*.cpp"
+  - "**/*.hpp"
+  - "**/*.cc"
+  - "**/*.hh"
+  - "**/*.cxx"
+  - "**/*.h"
+  - "**/CMakeLists.txt"
+---
+# C++ Coding Style
+
+> This file extends [common/coding-style.md](../common/coding-style.md) with C++ specific content.
+
+## Modern C++ (C++17/20/23)
+
+- Prefer **modern C++ features** over C-style constructs
+- Use `auto` when the type is obvious from context
+- Use `constexpr` for compile-time constants
+- Use structured bindings: `auto [key, value] = map_entry;`
+
+## Resource Management
+
+- **RAII everywhere** — no manual `new`/`delete`
+- Use `std::unique_ptr` for exclusive ownership
+- Use `std::shared_ptr` only when shared ownership is truly needed
+- Use `std::make_unique` / `std::make_shared` over raw `new`
+
+## Naming Conventions
+
+- Types/Classes: `PascalCase`
+- Functions/Methods: `snake_case` or `camelCase` (follow project convention)
+- Constants: `kPascalCase` or `UPPER_SNAKE_CASE`
+- Namespaces: `lowercase`
+- Member variables: `snake_case_` (trailing underscore) or `m_` prefix
+
+## Formatting
+
+- Use **clang-format** — no style debates
+- Run `clang-format -i <file>` before committing
+
+## Reference
+
+See skill: `cpp-coding-standards` for comprehensive C++ coding standards and guidelines.

package/.agent/rules/cpp/hooks.md

@@ -0,0 +1,39 @@
+---
+paths:
+  - "**/*.cpp"
+  - "**/*.hpp"
+  - "**/*.cc"
+  - "**/*.hh"
+  - "**/*.cxx"
+  - "**/*.h"
+  - "**/CMakeLists.txt"
+---
+# C++ Hooks
+
+> This file extends [common/hooks.md](../common/hooks.md) with C++ specific content.
+
+## Build Hooks
+
+Run these checks before committing C++ changes:
+
+```bash
+# Format check
+clang-format --dry-run --Werror src/*.cpp src/*.hpp
+
+# Static analysis
+clang-tidy src/*.cpp -- -std=c++17
+
+# Build
+cmake --build build
+
+# Tests
+ctest --test-dir build --output-on-failure
+```
+
+## Recommended CI Pipeline
+
+1. **clang-format** — formatting check
+2. **clang-tidy** — static analysis
+3. **cppcheck** — additional analysis
+4. **cmake build** — compilation
+5. **ctest** — test execution with sanitizers

package/.agent/rules/cpp/patterns.md

@@ -0,0 +1,51 @@
+---
+paths:
+  - "**/*.cpp"
+  - "**/*.hpp"
+  - "**/*.cc"
+  - "**/*.hh"
+  - "**/*.cxx"
+  - "**/*.h"
+  - "**/CMakeLists.txt"
+---
+# C++ Patterns
+
+> This file extends [common/patterns.md](../common/patterns.md) with C++ specific content.
+
+## RAII (Resource Acquisition Is Initialization)
+
+Tie resource lifetime to object lifetime:
+
+```cpp
+class FileHandle {
+public:
+    explicit FileHandle(const std::string& path) : file_(std::fopen(path.c_str(), "r")) {}
+    ~FileHandle() { if (file_) std::fclose(file_); }
+    FileHandle(const FileHandle&) = delete;
+    FileHandle& operator=(const FileHandle&) = delete;
+private:
+    std::FILE* file_;
+};
+```
+
+## Rule of Five/Zero
+
+- **Rule of Zero**: Prefer classes that need no custom destructor, copy/move constructors, or assignments
+- **Rule of Five**: If you define any of destructor/copy-ctor/copy-assign/move-ctor/move-assign, define all five
+
+## Value Semantics
+
+- Pass small/trivial types by value
+- Pass large types by `const&`
+- Return by value (rely on RVO/NRVO)
+- Use move semantics for sink parameters
+
+## Error Handling
+
+- Use exceptions for exceptional conditions
+- Use `std::optional` for values that may not exist
+- Use `std::expected` (C++23) or result types for expected failures
+
+## Reference
+
+See skill: `cpp-coding-standards` for comprehensive C++ patterns and anti-patterns.

package/.agent/rules/cpp/security.md

@@ -0,0 +1,51 @@
+---
+paths:
+  - "**/*.cpp"
+  - "**/*.hpp"
+  - "**/*.cc"
+  - "**/*.hh"
+  - "**/*.cxx"
+  - "**/*.h"
+  - "**/CMakeLists.txt"
+---
+# C++ Security
+
+> This file extends [common/security.md](../common/security.md) with C++ specific content.
+
+## Memory Safety
+
+- Never use raw `new`/`delete` — use smart pointers
+- Never use C-style arrays — use `std::array` or `std::vector`
+- Never use `malloc`/`free` — use C++ allocation
+- Avoid `reinterpret_cast` unless absolutely necessary
+
+## Buffer Overflows
+
+- Use `std::string` over `char*`
+- Use `.at()` for bounds-checked access when safety matters
+- Never use `strcpy`, `strcat`, `sprintf` — use `std::string` or `fmt::format`
+
+## Undefined Behavior
+
+- Always initialize variables
+- Avoid signed integer overflow
+- Never dereference null or dangling pointers
+- Use sanitizers in CI:
+  ```bash
+  cmake -DCMAKE_CXX_FLAGS="-fsanitize=address,undefined" ..
+  ```
+
+## Static Analysis
+
+- Use **clang-tidy** for automated checks:
+  ```bash
+  clang-tidy --checks='*' src/*.cpp
+  ```
+- Use **cppcheck** for additional analysis:
+  ```bash
+  cppcheck --enable=all src/
+  ```
+
+## Reference
+
+See skill: `cpp-coding-standards` for detailed security guidelines.

package/.agent/rules/cpp/testing.md

@@ -0,0 +1,44 @@
+---
+paths:
+  - "**/*.cpp"
+  - "**/*.hpp"
+  - "**/*.cc"
+  - "**/*.hh"
+  - "**/*.cxx"
+  - "**/*.h"
+  - "**/CMakeLists.txt"
+---
+# C++ Testing
+
+> This file extends [common/testing.md](../common/testing.md) with C++ specific content.
+
+## Framework
+
+Use **GoogleTest** (gtest/gmock) with **CMake/CTest**.
+
+## Running Tests
+
+```bash
+cmake --build build && ctest --test-dir build --output-on-failure
+```
+
+## Coverage
+
+```bash
+cmake -DCMAKE_CXX_FLAGS="--coverage" -DCMAKE_EXE_LINKER_FLAGS="--coverage" ..
+cmake --build .
+ctest --output-on-failure
+lcov --capture --directory . --output-file coverage.info
+```
+
+## Sanitizers
+
+Always run tests with sanitizers in CI:
+
+```bash
+cmake -DCMAKE_CXX_FLAGS="-fsanitize=address,undefined" ..
+```
+
+## Reference
+
+See skill: `cpp-testing` for detailed C++ testing patterns, TDD workflow, and GoogleTest/GMock usage.

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

@@ -0,0 +1,72 @@
+---
+paths:
+  - "**/*.cs"
+  - "**/*.csx"
+---
+# C# Coding Style
+
+> This file extends [common/coding-style.md](../common/coding-style.md) with C#-specific content.
+
+## Standards
+
+- Follow current .NET conventions and enable nullable reference types
+- Prefer explicit access modifiers on public and internal APIs
+- Keep files aligned with the primary type they define
+
+## Types and Models
+
+- Prefer `record` or `record struct` for immutable value-like models
+- Use `class` for entities or types with identity and lifecycle
+- Use `interface` for service boundaries and abstractions
+- Avoid `dynamic` in application code; prefer generics or explicit models
+
+```csharp
+public sealed record UserDto(Guid Id, string Email);
+
+public interface IUserRepository
+{
+    Task<UserDto?> FindByIdAsync(Guid id, CancellationToken cancellationToken);
+}
+```
+
+## Immutability
+
+- Prefer `init` setters, constructor parameters, and immutable collections for shared state
+- Do not mutate input models in-place when producing updated state
+
+```csharp
+public sealed record UserProfile(string Name, string Email);
+
+public static UserProfile Rename(UserProfile profile, string name) =>
+    profile with { Name = name };
+```
+
+## Async and Error Handling
+
+- Prefer `async`/`await` over blocking calls like `.Result` or `.Wait()`
+- Pass `CancellationToken` through public async APIs
+- Throw specific exceptions and log with structured properties
+
+```csharp
+public async Task<Order> LoadOrderAsync(
+    Guid orderId,
+    CancellationToken cancellationToken)
+{
+    try
+    {
+        return await repository.FindAsync(orderId, cancellationToken)
+            ?? throw new InvalidOperationException($"Order {orderId} was not found.");
+    }
+    catch (Exception ex)
+    {
+        logger.LogError(ex, "Failed to load order {OrderId}", orderId);
+        throw;
+    }
+}
+```
+
+## Formatting
+
+- Use `dotnet format` for formatting and analyzer fixes
+- Keep `using` directives organized and remove unused imports
+- Prefer expression-bodied members only when they stay readable

package/.agent/rules/csharp/hooks.md

@@ -0,0 +1,25 @@
+---
+paths:
+  - "**/*.cs"
+  - "**/*.csx"
+  - "**/*.csproj"
+  - "**/*.sln"
+  - "**/Directory.Build.props"
+  - "**/Directory.Build.targets"
+---
+# C# Hooks
+
+> This file extends [common/hooks.md](../common/hooks.md) with C#-specific content.
+
+## PostToolUse Hooks
+
+Configure in `~/.claude/settings.json`:
+
+- **dotnet format**: Auto-format edited C# files and apply analyzer fixes
+- **dotnet build**: Verify the solution or project still compiles after edits
+- **dotnet test --no-build**: Re-run the nearest relevant test project after behavior changes
+
+## Stop Hooks
+
+- Run a final `dotnet build` before ending a session with broad C# changes
+- Warn on modified `appsettings*.json` files so secrets do not get committed

package/.agent/rules/csharp/patterns.md

@@ -0,0 +1,50 @@
+---
+paths:
+  - "**/*.cs"
+  - "**/*.csx"
+---
+# C# Patterns
+
+> This file extends [common/patterns.md](../common/patterns.md) with C#-specific content.
+
+## API Response Pattern
+
+```csharp
+public sealed record ApiResponse<T>(
+    bool Success,
+    T? Data = default,
+    string? Error = null,
+    object? Meta = null);
+```
+
+## Repository Pattern
+
+```csharp
+public interface IRepository<T>
+{
+    Task<IReadOnlyList<T>> FindAllAsync(CancellationToken cancellationToken);
+    Task<T?> FindByIdAsync(Guid id, CancellationToken cancellationToken);
+    Task<T> CreateAsync(T entity, CancellationToken cancellationToken);
+    Task<T> UpdateAsync(T entity, CancellationToken cancellationToken);
+    Task DeleteAsync(Guid id, CancellationToken cancellationToken);
+}
+```
+
+## Options Pattern
+
+Use strongly typed options for config instead of reading raw strings throughout the codebase.
+
+```csharp
+public sealed class PaymentsOptions
+{
+    public const string SectionName = "Payments";
+    public required string BaseUrl { get; init; }
+    public required string ApiKeySecretName { get; init; }
+}
+```
+
+## Dependency Injection
+
+- Depend on interfaces at service boundaries
+- Keep constructors focused; if a service needs too many dependencies, split responsibilities
+- Register lifetimes intentionally: singleton for stateless/shared services, scoped for request data, transient for lightweight pure workers

package/.agent/rules/csharp/security.md

@@ -0,0 +1,58 @@
+---
+paths:
+  - "**/*.cs"
+  - "**/*.csx"
+  - "**/*.csproj"
+  - "**/appsettings*.json"
+---
+# C# Security
+
+> This file extends [common/security.md](../common/security.md) with C#-specific content.
+
+## Secret Management
+
+- Never hardcode API keys, tokens, or connection strings in source code
+- Use environment variables, user secrets for local development, and a secret manager in production
+- Keep `appsettings.*.json` free of real credentials
+
+```csharp
+// BAD
+const string ApiKey = "sk-live-123";
+
+// GOOD
+var apiKey = builder.Configuration["OpenAI:ApiKey"]
+    ?? throw new InvalidOperationException("OpenAI:ApiKey is not configured.");
+```
+
+## SQL Injection Prevention
+
+- Always use parameterized queries with ADO.NET, Dapper, or EF Core
+- Never concatenate user input into SQL strings
+- Validate sort fields and filter operators before using dynamic query composition
+
+```csharp
+const string sql = "SELECT * FROM Orders WHERE CustomerId = @customerId";
+await connection.QueryAsync<Order>(sql, new { customerId });
+```
+
+## Input Validation
+
+- Validate DTOs at the application boundary
+- Use data annotations, FluentValidation, or explicit guard clauses
+- Reject invalid model state before running business logic
+
+## Authentication and Authorization
+
+- Prefer framework auth handlers instead of custom token parsing
+- Enforce authorization policies at endpoint or handler boundaries
+- Never log raw tokens, passwords, or PII
+
+## Error Handling
+
+- Return safe client-facing messages
+- Log detailed exceptions with structured context server-side
+- Do not expose stack traces, SQL text, or filesystem paths in API responses
+
+## References
+
+See skill: `security-review` for broader application security review checklists.

package/.agent/rules/csharp/testing.md

@@ -0,0 +1,46 @@
+---
+paths:
+  - "**/*.cs"
+  - "**/*.csx"
+  - "**/*.csproj"
+---
+# C# Testing
+
+> This file extends [common/testing.md](../common/testing.md) with C#-specific content.
+
+## Test Framework
+
+- Prefer **xUnit** for unit and integration tests
+- Use **FluentAssertions** for readable assertions
+- Use **Moq** or **NSubstitute** for mocking dependencies
+- Use **Testcontainers** when integration tests need real infrastructure
+
+## Test Organization
+
+- Mirror `src/` structure under `tests/`
+- Separate unit, integration, and end-to-end coverage clearly
+- Name tests by behavior, not implementation details
+
+```csharp
+public sealed class OrderServiceTests
+{
+    [Fact]
+    public async Task FindByIdAsync_ReturnsOrder_WhenOrderExists()
+    {
+        // Arrange
+        // Act
+        // Assert
+    }
+}
+```
+
+## ASP.NET Core Integration Tests
+
+- Use `WebApplicationFactory<TEntryPoint>` for API integration coverage
+- Test auth, validation, and serialization through HTTP, not by bypassing middleware
+
+## Coverage
+
+- Target 80%+ line coverage
+- Focus coverage on domain logic, validation, auth, and failure paths
+- Run `dotnet test` in CI with coverage collection enabled where available