@heyai-rules/pilo-masterkit 2.1.0 → 3.1.0

package/.agent/rules/WORKFLOW_ORCHESTRATION.md

@@ -1,55 +1,55 @@
-# 🔄 Workflow Orchestration Protocols
-
-This document defines the advanced operational workflows for the Pilo Masterkit. These rules ensure autonomy, elegance, and continuous self-improvement.
-
----
-
-## 1. Plan Mode Default
-- **Trigger**: Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions).
-- **Control**: If something goes sideways, **STOP and re-plan immediately** — don't keep pushing.
-- **Verification**: Use plan mode for verification steps, not just building.
-- **Spec First**: Write detailed specs upfront to reduce ambiguity.
-
-## 2. Subagent Strategy
-- **Clean Context**: Use subagents liberally to keep main context window clean.
-- **Delegation**: Offload research, exploration, and parallel analysis to specialized subagents.
-- **Scale**: For complex problems, throw more compute at it via multiple parallel subagents.
-- **Focus**: One specific task per subagent for maximum accuracy.
-
-## 3. Self-Improvement Loop
-- **Memory Update**: After ANY correction from the user: update `.agent/tasks/lessons.md` with the new pattern.
-- **Preventive Rules**: Write rules for yourself in this project to prevent repeating the same mistake.
-- **Iteration**: Ruthlessly iterate on these lessons until the mistake rate drops.
-- **Awareness**: Review previous lessons at the start of every session.
-
-## 4. Verification Before Done
-- **No Assumptions**: Never mark a task complete without proving it works.
-- **Diff Analysis**: Diff behavior between the original code and your changes.
-- **Peer Review**: Ask yourself: *"Would a staff engineer approve this change?"*.
-- **Demonstration**: Run tests, check logs, and clearly demonstrate correctness to the user.
-
-## 5. Demand Elegance (Balanced)
-- **Pause & Reflect**: For non-trivial changes, pause and ask: *"Is there a more elegant way?"*.
-- **Refinement**: If a fix feels hacky: *"Knowing everything I know, implement the elegant solution instead"*.
-- **Practicality**: Skip this for simple, obvious fixes — do not over-engineer.
-- **Self-Critique**: Challenge your own work before presenting it.
-
-## 6. Autonomous Bug Fixing
-- **Direct Resolution**: When given a bug report: just fix it. Don't ask for hand-holding.
-- **Root Cause**: Identify logs, errors, or failing tests — then resolve them thoroughly.
-- **Minimal User Burden**: Aim for zero context switching required from the user.
-- **CI Ownership**: Fix failing CI tests automatically without being told how.
-
----
-
-## Task Management Lifecycle
-
-1. **Plan First**: Write the plan to `.agent/tasks/todo.md` with checkable items.
-2. **Verify Plan**: Check in with the user (if required) before starting implementation.
-3. **Track Progress**: Mark items as complete as you progress.
-4. **Explain Changes**: Provide a high-level summary at each major step.
-5. **Document Results**: Add a "Review" section to `.agent/tasks/todo.md` after completion.
-6. **Capture Lessons**: Update `.agent/tasks/lessons.md` immediately after any corrections.
-
----
-> *"Efficiency is doing things right; effectiveness is doing the right things."*
+# 🔄 Workflow Orchestration Protocols
+
+This document defines the advanced operational workflows for the Pilo Masterkit. These rules ensure autonomy, elegance, and continuous self-improvement.
+
+---
+
+## 1. Plan Mode Default
+- **Trigger**: Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions).
+- **Control**: If something goes sideways, **STOP and re-plan immediately** — don't keep pushing.
+- **Verification**: Use plan mode for verification steps, not just building.
+- **Spec First**: Write detailed specs upfront to reduce ambiguity.
+
+## 2. Subagent Strategy
+- **Clean Context**: Use subagents liberally to keep main context window clean.
+- **Delegation**: Offload research, exploration, and parallel analysis to specialized subagents.
+- **Scale**: For complex problems, throw more compute at it via multiple parallel subagents.
+- **Focus**: One specific task per subagent for maximum accuracy.
+
+## 3. Self-Improvement Loop
+- **Memory Update**: After ANY correction from the user: update `.agent/tasks/lessons.md` with the new pattern.
+- **Preventive Rules**: Write rules for yourself in this project to prevent repeating the same mistake.
+- **Iteration**: Ruthlessly iterate on these lessons until the mistake rate drops.
+- **Awareness**: Review previous lessons at the start of every session.
+
+## 4. Verification Before Done
+- **No Assumptions**: Never mark a task complete without proving it works.
+- **Diff Analysis**: Diff behavior between the original code and your changes.
+- **Peer Review**: Ask yourself: *"Would a staff engineer approve this change?"*.
+- **Demonstration**: Run tests, check logs, and clearly demonstrate correctness to the user.
+
+## 5. Demand Elegance (Balanced)
+- **Pause & Reflect**: For non-trivial changes, pause and ask: *"Is there a more elegant way?"*.
+- **Refinement**: If a fix feels hacky: *"Knowing everything I know, implement the elegant solution instead"*.
+- **Practicality**: Skip this for simple, obvious fixes — do not over-engineer.
+- **Self-Critique**: Challenge your own work before presenting it.
+
+## 6. Autonomous Bug Fixing
+- **Direct Resolution**: When given a bug report: just fix it. Don't ask for hand-holding.
+- **Root Cause**: Identify logs, errors, or failing tests — then resolve them thoroughly.
+- **Minimal User Burden**: Aim for zero context switching required from the user.
+- **CI Ownership**: Fix failing CI tests automatically without being told how.
+
+---
+
+## Task Management Lifecycle
+
+1. **Plan First**: Write the plan to `.agent/tasks/todo.md` with checkable items.
+2. **Verify Plan**: Check in with the user (if required) before starting implementation.
+3. **Track Progress**: Mark items as complete as you progress.
+4. **Explain Changes**: Provide a high-level summary at each major step.
+5. **Document Results**: Add a "Review" section to `.agent/tasks/todo.md` after completion.
+6. **Capture Lessons**: Update `.agent/tasks/lessons.md` immediately after any corrections.
+
+---
+> *"Efficiency is doing things right; effectiveness is doing the right things."*

package/.agent/rules/common/agents.md

@@ -1,50 +1,50 @@
-# Agent Orchestration
-
-## Available Agents
-
-Located in `~/.claude/agents/`:
-
-| Agent | Purpose | When to Use |
-|-------|---------|-------------|
-| planner | Implementation planning | Complex features, refactoring |
-| architect | System design | Architectural decisions |
-| tdd-guide | Test-driven development | New features, bug fixes |
-| code-reviewer | Code review | After writing code |
-| security-reviewer | Security analysis | Before commits |
-| build-error-resolver | Fix build errors | When build fails |
-| e2e-runner | E2E testing | Critical user flows |
-| refactor-cleaner | Dead code cleanup | Code maintenance |
-| doc-updater | Documentation | Updating docs |
-| rust-reviewer | Rust code review | Rust projects |
-
-## Immediate Agent Usage
-
-No user prompt needed:
-1. Complex feature requests - Use **planner** agent
-2. Code just written/modified - Use **code-reviewer** agent
-3. Bug fix or new feature - Use **tdd-guide** agent
-4. Architectural decision - Use **architect** agent
-
-## Parallel Task Execution
-
-ALWAYS use parallel Task execution for independent operations:
-
-```markdown
-# GOOD: Parallel execution
-Launch 3 agents in parallel:
-1. Agent 1: Security analysis of auth module
-2. Agent 2: Performance review of cache system
-3. Agent 3: Type checking of utilities
-
-# BAD: Sequential when unnecessary
-First agent 1, then agent 2, then agent 3
-```
-
-## Multi-Perspective Analysis
-
-For complex problems, use split role sub-agents:
-- Factual reviewer
-- Senior engineer
-- Security expert
-- Consistency reviewer
-- Redundancy checker
+# Agent Orchestration
+
+## Available Agents
+
+Located in `~/.claude/agents/`:
+
+| Agent | Purpose | When to Use |
+|-------|---------|-------------|
+| planner | Implementation planning | Complex features, refactoring |
+| architect | System design | Architectural decisions |
+| tdd-guide | Test-driven development | New features, bug fixes |
+| code-reviewer | Code review | After writing code |
+| security-reviewer | Security analysis | Before commits |
+| build-error-resolver | Fix build errors | When build fails |
+| e2e-runner | E2E testing | Critical user flows |
+| refactor-cleaner | Dead code cleanup | Code maintenance |
+| doc-updater | Documentation | Updating docs |
+| rust-reviewer | Rust code review | Rust projects |
+
+## Immediate Agent Usage
+
+No user prompt needed:
+1. Complex feature requests - Use **planner** agent
+2. Code just written/modified - Use **code-reviewer** agent
+3. Bug fix or new feature - Use **tdd-guide** agent
+4. Architectural decision - Use **architect** agent
+
+## Parallel Task Execution
+
+ALWAYS use parallel Task execution for independent operations:
+
+```markdown
+# GOOD: Parallel execution
+Launch 3 agents in parallel:
+1. Agent 1: Security analysis of auth module
+2. Agent 2: Performance review of cache system
+3. Agent 3: Type checking of utilities
+
+# BAD: Sequential when unnecessary
+First agent 1, then agent 2, then agent 3
+```
+
+## Multi-Perspective Analysis
+
+For complex problems, use split role sub-agents:
+- Factual reviewer
+- Senior engineer
+- Security expert
+- Consistency reviewer
+- Redundancy checker

package/.agent/rules/common/code-review.md

@@ -1,124 +1,124 @@
-# Code Review Standards
-
-## Purpose
-
-Code review ensures quality, security, and maintainability before code is merged. This rule defines when and how to conduct code reviews.
-
-## When to Review
-
-**MANDATORY review triggers:**
-
-- After writing or modifying code
-- Before any commit to shared branches
-- When security-sensitive code is changed (auth, payments, user data)
-- When architectural changes are made
-- Before merging pull requests
-
-**Pre-Review Requirements:**
-
-Before requesting review, ensure:
-
-- All automated checks (CI/CD) are passing
-- Merge conflicts are resolved
-- Branch is up to date with target branch
-
-## Review Checklist
-
-Before marking code complete:
-
-- [ ] Code is readable and well-named
-- [ ] Functions are focused (<50 lines)
-- [ ] Files are cohesive (<800 lines)
-- [ ] No deep nesting (>4 levels)
-- [ ] Errors are handled explicitly
-- [ ] No hardcoded secrets or credentials
-- [ ] No console.log or debug statements
-- [ ] Tests exist for new functionality
-- [ ] Test coverage meets 80% minimum
-
-## Security Review Triggers
-
-**STOP and use security-reviewer agent when:**
-
-- Authentication or authorization code
-- User input handling
-- Database queries
-- File system operations
-- External API calls
-- Cryptographic operations
-- Payment or financial code
-
-## Review Severity Levels
-
-| Level | Meaning | Action |
-|-------|---------|--------|
-| CRITICAL | Security vulnerability or data loss risk | **BLOCK** - Must fix before merge |
-| HIGH | Bug or significant quality issue | **WARN** - Should fix before merge |
-| MEDIUM | Maintainability concern | **INFO** - Consider fixing |
-| LOW | Style or minor suggestion | **NOTE** - Optional |
-
-## Agent Usage
-
-Use these agents for code review:
-
-| Agent | Purpose |
-|-------|---------|
-| **code-reviewer** | General code quality, patterns, best practices |
-| **security-reviewer** | Security vulnerabilities, OWASP Top 10 |
-| **typescript-reviewer** | TypeScript/JavaScript specific issues |
-| **python-reviewer** | Python specific issues |
-| **go-reviewer** | Go specific issues |
-| **rust-reviewer** | Rust specific issues |
-
-## Review Workflow
-
-```
-1. Run git diff to understand changes
-2. Check security checklist first
-3. Review code quality checklist
-4. Run relevant tests
-5. Verify coverage >= 80%
-6. Use appropriate agent for detailed review
-```
-
-## Common Issues to Catch
-
-### Security
-
-- Hardcoded credentials (API keys, passwords, tokens)
-- SQL injection (string concatenation in queries)
-- XSS vulnerabilities (unescaped user input)
-- Path traversal (unsanitized file paths)
-- CSRF protection missing
-- Authentication bypasses
-
-### Code Quality
-
-- Large functions (>50 lines) - split into smaller
-- Large files (>800 lines) - extract modules
-- Deep nesting (>4 levels) - use early returns
-- Missing error handling - handle explicitly
-- Mutation patterns - prefer immutable operations
-- Missing tests - add test coverage
-
-### Performance
-
-- N+1 queries - use JOINs or batching
-- Missing pagination - add LIMIT to queries
-- Unbounded queries - add constraints
-- Missing caching - cache expensive operations
-
-## Approval Criteria
-
-- **Approve**: No CRITICAL or HIGH issues
-- **Warning**: Only HIGH issues (merge with caution)
-- **Block**: CRITICAL issues found
-
-## Integration with Other Rules
-
-This rule works with:
-
-- [testing.md](testing.md) - Test coverage requirements
-- [security.md](security.md) - Security checklist
-- [git-workflow.md](git-workflow.md) - Commit standards
-- [agents.md](agents.md) - Agent delegation
+# Code Review Standards
+
+## Purpose
+
+Code review ensures quality, security, and maintainability before code is merged. This rule defines when and how to conduct code reviews.
+
+## When to Review
+
+**MANDATORY review triggers:**
+
+- After writing or modifying code
+- Before any commit to shared branches
+- When security-sensitive code is changed (auth, payments, user data)
+- When architectural changes are made
+- Before merging pull requests
+
+**Pre-Review Requirements:**
+
+Before requesting review, ensure:
+
+- All automated checks (CI/CD) are passing
+- Merge conflicts are resolved
+- Branch is up to date with target branch
+
+## Review Checklist
+
+Before marking code complete:
+
+- [ ] Code is readable and well-named
+- [ ] Functions are focused (<50 lines)
+- [ ] Files are cohesive (<800 lines)
+- [ ] No deep nesting (>4 levels)
+- [ ] Errors are handled explicitly
+- [ ] No hardcoded secrets or credentials
+- [ ] No console.log or debug statements
+- [ ] Tests exist for new functionality
+- [ ] Test coverage meets 80% minimum
+
+## Security Review Triggers
+
+**STOP and use security-reviewer agent when:**
+
+- Authentication or authorization code
+- User input handling
+- Database queries
+- File system operations
+- External API calls
+- Cryptographic operations
+- Payment or financial code
+
+## Review Severity Levels
+
+| Level | Meaning | Action |
+|-------|---------|--------|
+| CRITICAL | Security vulnerability or data loss risk | **BLOCK** - Must fix before merge |
+| HIGH | Bug or significant quality issue | **WARN** - Should fix before merge |
+| MEDIUM | Maintainability concern | **INFO** - Consider fixing |
+| LOW | Style or minor suggestion | **NOTE** - Optional |
+
+## Agent Usage
+
+Use these agents for code review:
+
+| Agent | Purpose |
+|-------|---------|
+| **code-reviewer** | General code quality, patterns, best practices |
+| **security-reviewer** | Security vulnerabilities, OWASP Top 10 |
+| **typescript-reviewer** | TypeScript/JavaScript specific issues |
+| **python-reviewer** | Python specific issues |
+| **go-reviewer** | Go specific issues |
+| **rust-reviewer** | Rust specific issues |
+
+## Review Workflow
+
+```
+1. Run git diff to understand changes
+2. Check security checklist first
+3. Review code quality checklist
+4. Run relevant tests
+5. Verify coverage >= 80%
+6. Use appropriate agent for detailed review
+```
+
+## Common Issues to Catch
+
+### Security
+
+- Hardcoded credentials (API keys, passwords, tokens)
+- SQL injection (string concatenation in queries)
+- XSS vulnerabilities (unescaped user input)
+- Path traversal (unsanitized file paths)
+- CSRF protection missing
+- Authentication bypasses
+
+### Code Quality
+
+- Large functions (>50 lines) - split into smaller
+- Large files (>800 lines) - extract modules
+- Deep nesting (>4 levels) - use early returns
+- Missing error handling - handle explicitly
+- Mutation patterns - prefer immutable operations
+- Missing tests - add test coverage
+
+### Performance
+
+- N+1 queries - use JOINs or batching
+- Missing pagination - add LIMIT to queries
+- Unbounded queries - add constraints
+- Missing caching - cache expensive operations
+
+## Approval Criteria
+
+- **Approve**: No CRITICAL or HIGH issues
+- **Warning**: Only HIGH issues (merge with caution)
+- **Block**: CRITICAL issues found
+
+## Integration with Other Rules
+
+This rule works with:
+
+- [testing.md](testing.md) - Test coverage requirements
+- [security.md](security.md) - Security checklist
+- [git-workflow.md](git-workflow.md) - Commit standards
+- [agents.md](agents.md) - Agent delegation

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

@@ -1,48 +1,48 @@
-# Coding Style
-
-## Immutability (CRITICAL)
-
-ALWAYS create new objects, NEVER mutate existing ones:
-
-```
-// Pseudocode
-WRONG:  modify(original, field, value) → changes original in-place
-CORRECT: update(original, field, value) → returns new copy with change
-```
-
-Rationale: Immutable data prevents hidden side effects, makes debugging easier, and enables safe concurrency.
-
-## File Organization
-
-MANY SMALL FILES > FEW LARGE FILES:
-- High cohesion, low coupling
-- 200-400 lines typical, 800 max
-- Extract utilities from large modules
-- Organize by feature/domain, not by type
-
-## Error Handling
-
-ALWAYS handle errors comprehensively:
-- Handle errors explicitly at every level
-- Provide user-friendly error messages in UI-facing code
-- Log detailed error context on the server side
-- Never silently swallow errors
-
-## Input Validation
-
-ALWAYS validate at system boundaries:
-- Validate all user input before processing
-- Use schema-based validation where available
-- Fail fast with clear error messages
-- Never trust external data (API responses, user input, file content)
-
-## Code Quality Checklist
-
-Before marking work complete:
-- [ ] Code is readable and well-named
-- [ ] Functions are small (<50 lines)
-- [ ] Files are focused (<800 lines)
-- [ ] No deep nesting (>4 levels)
-- [ ] Proper error handling
-- [ ] No hardcoded values (use constants or config)
-- [ ] No mutation (immutable patterns used)
+# Coding Style
+
+## Immutability (CRITICAL)
+
+ALWAYS create new objects, NEVER mutate existing ones:
+
+```
+// Pseudocode
+WRONG:  modify(original, field, value) → changes original in-place
+CORRECT: update(original, field, value) → returns new copy with change
+```
+
+Rationale: Immutable data prevents hidden side effects, makes debugging easier, and enables safe concurrency.
+
+## File Organization
+
+MANY SMALL FILES > FEW LARGE FILES:
+- High cohesion, low coupling
+- 200-400 lines typical, 800 max
+- Extract utilities from large modules
+- Organize by feature/domain, not by type
+
+## Error Handling
+
+ALWAYS handle errors comprehensively:
+- Handle errors explicitly at every level
+- Provide user-friendly error messages in UI-facing code
+- Log detailed error context on the server side
+- Never silently swallow errors
+
+## Input Validation
+
+ALWAYS validate at system boundaries:
+- Validate all user input before processing
+- Use schema-based validation where available
+- Fail fast with clear error messages
+- Never trust external data (API responses, user input, file content)
+
+## Code Quality Checklist
+
+Before marking work complete:
+- [ ] Code is readable and well-named
+- [ ] Functions are small (<50 lines)
+- [ ] Files are focused (<800 lines)
+- [ ] No deep nesting (>4 levels)
+- [ ] Proper error handling
+- [ ] No hardcoded values (use constants or config)
+- [ ] No mutation (immutable patterns used)

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

@@ -1,44 +1,44 @@
-# Development Workflow
-
-> This file extends [common/git-workflow.md](./git-workflow.md) with the full feature development process that happens before git operations.
-
-The Feature Implementation Workflow describes the development pipeline: research, planning, TDD, code review, and then committing to git.
-
-## Feature Implementation Workflow
-
-0. **Research & Reuse** _(mandatory before any new implementation)_
-   - **GitHub code search first:** Run `gh search repos` and `gh search code` to find existing implementations, templates, and patterns before writing anything new.
-   - **Library docs second:** Use Context7 or primary vendor docs to confirm API behavior, package usage, and version-specific details before implementing.
-   - **Exa only when the first two are insufficient:** Use Exa for broader web research or discovery after GitHub search and primary docs.
-   - **Check package registries:** Search npm, PyPI, crates.io, and other registries before writing utility code. Prefer battle-tested libraries over hand-rolled solutions.
-   - **Search for adaptable implementations:** Look for open-source projects that solve 80%+ of the problem and can be forked, ported, or wrapped.
-   - Prefer adopting or porting a proven approach over writing net-new code when it meets the requirement.
-
-1. **Plan First**
-   - Use **planner** agent to create implementation plan
-   - Generate planning docs before coding: PRD, architecture, system_design, tech_doc, task_list
-   - Identify dependencies and risks
-   - Break down into phases
-
-2. **TDD Approach**
-   - Use **tdd-guide** agent
-   - Write tests first (RED)
-   - Implement to pass tests (GREEN)
-   - Refactor (IMPROVE)
-   - Verify 80%+ coverage
-
-3. **Code Review**
-   - Use **code-reviewer** agent immediately after writing code
-   - Address CRITICAL and HIGH issues
-   - Fix MEDIUM issues when possible
-
-4. **Commit & Push**
-   - Detailed commit messages
-   - Follow conventional commits format
-   - See [git-workflow.md](./git-workflow.md) for commit message format and PR process
-
-5. **Pre-Review Checks**
-   - Verify all automated checks (CI/CD) are passing
-   - Resolve any merge conflicts
-   - Ensure branch is up to date with target branch
-   - Only request review after these checks pass
+# Development Workflow
+
+> This file extends [common/git-workflow.md](./git-workflow.md) with the full feature development process that happens before git operations.
+
+The Feature Implementation Workflow describes the development pipeline: research, planning, TDD, code review, and then committing to git.
+
+## Feature Implementation Workflow
+
+0. **Research & Reuse** _(mandatory before any new implementation)_
+   - **GitHub code search first:** Run `gh search repos` and `gh search code` to find existing implementations, templates, and patterns before writing anything new.
+   - **Library docs second:** Use Context7 or primary vendor docs to confirm API behavior, package usage, and version-specific details before implementing.
+   - **Exa only when the first two are insufficient:** Use Exa for broader web research or discovery after GitHub search and primary docs.
+   - **Check package registries:** Search npm, PyPI, crates.io, and other registries before writing utility code. Prefer battle-tested libraries over hand-rolled solutions.
+   - **Search for adaptable implementations:** Look for open-source projects that solve 80%+ of the problem and can be forked, ported, or wrapped.
+   - Prefer adopting or porting a proven approach over writing net-new code when it meets the requirement.
+
+1. **Plan First**
+   - Use **planner** agent to create implementation plan
+   - Generate planning docs before coding: PRD, architecture, system_design, tech_doc, task_list
+   - Identify dependencies and risks
+   - Break down into phases
+
+2. **TDD Approach**
+   - Use **tdd-guide** agent
+   - Write tests first (RED)
+   - Implement to pass tests (GREEN)
+   - Refactor (IMPROVE)
+   - Verify 80%+ coverage
+
+3. **Code Review**
+   - Use **code-reviewer** agent immediately after writing code
+   - Address CRITICAL and HIGH issues
+   - Fix MEDIUM issues when possible
+
+4. **Commit & Push**
+   - Detailed commit messages
+   - Follow conventional commits format
+   - See [git-workflow.md](./git-workflow.md) for commit message format and PR process
+
+5. **Pre-Review Checks**
+   - Verify all automated checks (CI/CD) are passing
+   - Resolve any merge conflicts
+   - Ensure branch is up to date with target branch
+   - Only request review after these checks pass