agents-templated 2.2.0 → 2.2.2

package/templates/.claude/rules/style.mdc

@@ -0,0 +1,306 @@
+---
+title: "Code Style and Standards"
+description: "Apply when organizing code, naming variables, formatting, or improving code clarity and maintainability"
+alwaysApply: true
+version: "3.0.0"
+tags: ["style", "formatting", "naming", "quality"]
+globs:
+  - "**/*"
+triggers:
+  - "Writing or reviewing code"
+  - "Setting up code formatting rules"
+  - "Naming variables, functions, or files"
+  - "Organizing module structure"
+  - "Refactoring or improving readability"
+---
+
+# Code Style and Standards
+
+Language and framework-agnostic standards for clean, maintainable code.
+
+## General Code Quality
+
+### Core Principles
+
+- **Readability**: Code should be easy to understand without extensive comments
+- **Consistency**: Follow the same patterns throughout the codebase
+- **Simplicity**: Prefer simple solutions to complex ones
+- **SOLID principles**: Single responsibility, Open/closed, Liskov, Interface segregation, Dependency inversion
+- **DRY**: Don't Repeat Yourself - extract common patterns
+
+### Code Review Standards
+
+Code should:
+- Do one thing well
+- Be testable
+- Have no dead code
+- Follow established patterns
+- Include appropriate comments
+- Have meaningful names
+- Handle errors appropriately
+- Consider security implications
+- Consider performance implications
+
+## Naming Conventions
+
+### File Naming
+
+Choose from established conventions:
+
+**Option 1: kebab-case (Recommended)**
+- File names: `user-profile.ts`, `navigation-bar.tsx`, `date-utils.js`
+- Matches URLs and file systems
+- Language-agnostic
+- Easy to type and read
+
+**Option 2: snake_case**
+- File names: `user_profile.py`, `date_utils.go`
+- Common in Python, Go, and Ruby
+- Matches language conventions
+
+**Option 3: PascalCase**
+- File names: `UserProfile.tsx`, `DateUtils.ts`
+- Common in C# and some JavaScript frameworks
+- Use consistently if chosen
+
+**Consistency rule**: Pick ONE and use it throughout the entire project.
+
+### Code Naming
+
+Consistent naming patterns:
+
+**Variables and Functions**
+- Use camelCase: `getUserData`, `isLoading`, `handleSubmit`
+- Use English words (even in non-English projects)
+- Be descriptive: `user` is worse than `currentUser`
+- Avoid abbreviations: `getDesc` vs `getDescription`
+- Prefix booleans with is/has: `isActive`, `hasPermission`
+
+**Constants**
+- Use UPPER_SNAKE_CASE: `MAX_RETRIES`, `API_BASE_URL`
+- Immutable values that don't change
+- Global configuration values
+- Magic numbers should become constants
+
+**Classes/Types/Interfaces**
+- Use PascalCase: `UserProfile`, `ApiResponse`, `DatabaseConfig`
+- Descriptive and specific names
+- Avoid generic names like `Data`, `Info`, `Object`
+
+**Enums**
+- Type name PascalCase: `UserStatus`
+- Values UPPER_SNAKE_CASE: `ACTIVE`, `INACTIVE`
+- Example: `UserStatus.ACTIVE`, `Theme.DARK_MODE`
+
+### Examples
+
+Good naming:
+```
+ getUserById()
+ isValidEmail()
+ parseJsonResponse()
+ calculateProposedDiscount()
+ MAXIMUM_RETRY_ATTEMPTS
+ ValidationError
+```
+
+Bad naming:
+```
+ get()
+ foo(), bar(), x
+ process()
+ u1, u2, s
+ var1, var2
+ handleIt()
+```
+
+## Formatting
+
+### Consistent Formatting
+
+Use automated tools:
+- **Prettier**: JavaScript/TypeScript/CSS/YAML
+- **Black**: Python
+- **gofmt**: Go
+- **rustfmt**: Rust
+- **clang-format**: C/C++
+- Your language's standard formatter
+
+Benefits:
+- No debates about formatting
+- Quick review of actual changes
+- Consistent codebase
+
+### Line Length
+
+- Target: 80-120 characters
+- Maximum: 120-140 characters
+- Avoid scrolling horizontally
+
+### Indentation
+
+Choose ONE and use consistently:
+- **2 spaces**: JavaScript, YAML, some Python
+- **4 spaces**: Python, Java, most languages
+- **Tabs**: If configured, consistently
+
+### Comments & Documentation
+
+Good comments explain:
+- **Why**: The reason for this code
+- **Complex logic**: How it works if not obvious
+- **Edge cases**: Special handling and why
+- **Warnings**: Performance implications or gotchas
+
+Bad comments:
+```
+ // Increment x
+x = x + 1
+
+ // Loop through users
+for (user in users) { ... }
+
+ // This is a variable
+let name = getUserName()
+```
+
+Good comments:
+```
+ // Increment retry counter before exponential backoff
+retryCount = retryCount + 1
+
+ // Process users in batches to prevent memory overload
+for (batch in users.batches()) { ... }
+
+ // Fetch fresh name from API to avoid stale cache
+let name = getUserName()
+```
+
+### Comments vs Code
+
+Let code speak for itself:
+
+Instead of:
+```
+// Get user age
+int age = currentYear - birthYear
+```
+
+Write:
+```
+int age = calculateAge(currentYear, birthYear)
+```
+
+## Code Organization
+
+### Module Organization
+
+Order within files:
+1. **Imports/Dependencies** - at top
+2. **Constants** - module-level constants
+3. **Types/Interfaces** - type definitions
+4. **Functions/Classes** - main code (public first, private after)
+5. **Exports** - explicit exports at end
+
+### Function Organization
+
+Function structure:
+1. **Parameters** - at top
+2. **Early returns** - validate inputs early
+3. **Logic** - main implementation
+4. **Return** - return result
+
+### Class/Object Organization
+
+Class structure:
+1. **Constructor/initializer**
+2. **Public methods**
+3. **Private methods**
+4. **Getters/setters**
+5. **Static methods** (if applicable)
+
+## Type Definitions
+
+### Clear Type Contracts
+
+Document what your types expect:
+
+```
+Define data structures clearly:
+- What fields are required
+- What data types
+- What values are valid
+- Any constraints or rules
+```
+
+### Avoid Magic Values
+
+Instead of magic numbers/strings:
+```
+ if (status === 1) { ... }
+ if (timeout === 60000) { ... }
+
+ const ACTIVE_STATUS = 1
+ const DEFAULT_TIMEOUT_MS = 60000
+ if (status === ACTIVE_STATUS) { ... }
+```
+
+## Error Handling
+
+### Clear Error Messages
+
+Error messages should:
+- Describe what went wrong
+- Explain why (if not obvious)
+- Suggest how to fix
+- Use user-friendly language
+
+Good error messages:
+- "Email format is invalid. Please enter a valid email address."
+- "Password must be at least 8 characters."
+- "User with this email already exists."
+
+Bad error messages:
+- "Error"
+- "Invalid input"
+- "Stack trace here..."
+
+### Error Handling Pattern
+
+Proper error handling:
+1. Catch/handle errors explicitly
+2. Log error with context
+3. Return appropriate error response
+4. Never expose sensitive data
+5. Include error code for client handling
+
+## Security in Code
+
+### Dangerous Patterns to Avoid
+
+Never:
+-  Store secrets in code
+-  Log sensitive data
+-  Dynamic SQL/query construction
+-  Eval user input
+-  Hardcoded API keys
+-  Return sensitive data in errors
+-  Skip input validation
+
+Always:
+-  Validate all inputs
+-  Use parameterized queries
+-  Hash sensitive data
+-  Use environment variables for secrets
+-  Log security events
+-  Encode output appropriately
+
+## Performance Considerations
+
+### Avoid N+1 Queries
+
+Good:
+```
+Get all users once with their posts
+Result: 1 query
+```

package/templates/.claude/rules/system-workflow.mdc

@@ -0,0 +1,69 @@
+---
+title: "System Workflow Orchestration"
+description: "Apply when planning work phases, defining acceptance criteria, or establishing delivery gates and rollback strategies"
+version: "1.0.0"
+tags: ["workflow", "gates", "delivery", "governance"]
+triggers:
+  - "Starting a new feature or major change"
+  - "Planning implementation phases"
+  - "Defining acceptance criteria"
+  - "Establishing rollback procedures"
+  - "Preparing for release or deployment"
+---
+
+## Purpose
+
+Define a repeatable lifecycle so all work is traceable, verifiable, and releasable.
+
+## Workflow Phases
+
+1. Discover
+2. Plan
+3. Implement
+4. Verify
+5. Release
+
+## Phase Requirements
+
+### 1) Discover
+- Capture objective, scope boundaries, constraints, and risk profile.
+- Produce: context summary + assumptions.
+
+### 2) Plan
+- Break work into atomic units and dependency order.
+- Define acceptance criteria and rollback considerations.
+- Produce: execution plan with checkpoints.
+
+### 3) Implement
+- Apply smallest safe changes within declared scope.
+- Keep changes deterministic and reversible when possible.
+- Produce: change summary and affected files.
+
+### 4) Verify
+- Run relevant tests/checks (targeted first, broad second).
+- Confirm security and regression impact.
+- Produce: validation evidence.
+
+### 5) Release
+- Check gates: tests, security posture, migration safety, rollback readiness.
+- Produce: release decision + rollout/rollback steps.
+
+## Required Delivery Artifacts
+
+- Objective and scope
+- Acceptance criteria
+- Risk register
+- Validation evidence
+- Rollback strategy (for non-trivial changes)
+
+## Gate Rules
+
+- Fail any critical gate -> `status: blocked`.
+- Missing rollback for risky changes -> blocked.
+- Missing validation evidence -> blocked.
+
+## Rollback Requirements
+
+- Identify rollback trigger conditions.
+- Provide explicit rollback steps.
+- Keep backups/version references for destructive changes.

package/templates/.claude/rules/testing.mdc

@@ -0,0 +1,308 @@
+---
+title: "Testing Guidelines & Best Practices"
+description: "Apply when adding tests, verifying coverage, or validating quality before deployment. Always required for business logic and critical flows"
+version: "3.0.0"
+tags: ["testing", "quality", "coverage", "e2e", "a11y"]
+triggers:
+  - "User requests tests for business logic"
+  - "Implementing a new feature"
+  - "Fixing a bug"
+  - "Need to verify API endpoints work"
+  - "Checking application behavior"
+  - "Hardening release artifacts"
+  - "CI/CD validation needed before deployment"
+---
+
+# Testing Guidelines & Best Practices
+
+Comprehensive testing patterns for maintaining quality across any technology stack.
+
+## Core Testing Principles
+
+- **Test Pyramid**: More unit tests (80%), fewer integration tests (15%), minimal E2E tests (5%)
+- **Arrange-Act-Assert**: Structure tests clearly with setup, action, and verification
+- **Descriptive Names**: Test names should describe expected behavior
+- **Independent Tests**: Each test should be able to run in isolation
+- **Fast Feedback**: Unit tests should run quickly (<100ms each)
+- **Deterministic**: Tests should pass/fail consistently, not randomly
+
+## Unit Testing
+
+Unit tests verify individual functions, methods, and components in isolation.
+
+### Unit Test Pattern
+
+Unit Test Structure:
+1. Arrange
+   - Set up test data
+   - Mock dependencies
+   - Configure test environment
+
+2. Act
+   - Call the function/method being tested
+   - Perform the action
+
+3. Assert
+   - Verify the result
+   - Check side effects
+   - Validate behavior
+
+### What to Unit Test
+
+- Business logic functions (validation, calculations, transformations)
+- Utility functions (helpers, formatters, parsers)
+- Service/class methods with clear inputs and outputs
+- Error handling and edge cases
+- Complex conditional logic
+
+### Unit Test Examples (Language-Agnostic)
+
+**Example 1: Validation Function**
+Test: Email validation function
+- Test valid email returns true
+- Test invalid email format returns false
+- Test empty string returns false
+- Test whitespace is trimmed
+- Test case-insensitive comparison
+
+**Example 2: Business Logic**
+Test: Calculate discount price
+- Test standard discount percentage
+- Test no discount
+- Test maximum discount cap
+- Test negative prices handled gracefully
+- Test rounding is correct
+
+**Example 3: Error Handling**
+Test: Parse JSON data
+- Test valid JSON parses successfully
+- Test invalid JSON throws appropriate error
+- Test missing required fields throws error
+- Test extra fields are handled
+- Test error messages are helpful
+
+### Mocking & Test Doubles
+
+Use test doubles (mocks, stubs, fakes) for external dependencies:
+
+Mocking Strategy:
+1. Identify external dependencies
+   - Database calls
+   - API calls
+   - File system access
+   - Time/date functions
+   - Random number generation
+
+2. Replace with appropriate test double
+   - Stub: Return fixed value
+   - Mock: Verify it was called correctly
+   - Fake: Simplified working implementation
+
+3. Verify interactions when appropriate
+   - Was the dependency called?
+   - Was it called with correct arguments?
+   - Was it called the right number of times?
+
+## Integration Testing
+
+Integration tests verify that multiple components work together correctly.
+
+### What to Integration Test
+
+- API endpoints (request  response)
+- Database operations (save, query, delete)
+- Service-to-service interactions
+- Authentication and authorization flows
+- Error scenarios and edge cases
+
+### Integration Test Pattern
+
+Integration Test Structure:
+1. Setup
+   - Create test database/data
+   - Mock external services if needed
+   - Set up test user/session
+
+2. Execute
+   - Make API call or trigger operation
+   - Interact with multiple components
+
+3. Verify
+   - Check response status and data
+   - Verify database changes
+   - Check side effects
+
+### Integration Test Examples
+
+**Example 1: User Creation API**
+Test: POST /api/users with valid data
+- Validate request body
+- Create user in database
+- Return created user with ID
+- User can be retrieved afterward
+- Password is hashed (not plaintext)
+
+**Example 2: Authentication Flow**
+Test: User login
+- Validate credentials
+- Create session/token
+- Return session/token to client
+- Can use session to access protected endpoints
+- Session is invalidated on logout
+
+**Example 3: Error Handling**
+Test: Create user with duplicate email
+- Database rejects duplicate
+- API returns 400 Bad Request
+- Error message is appropriate
+- No partial data is written
+
+## End-to-End Testing
+
+E2E tests verify complete user journeys across the entire application.
+
+### What to E2E Test
+
+- Critical user workflows (login, purchase, form submission)
+- Happy path scenarios
+- Common error scenarios
+- Cross-browser compatibility (if applicable)
+- Accessibility requirements
+
+### E2E Test Examples
+
+**Example 1: User Registration**
+Test: New user can register successfully
+1. Navigate to signup page
+2. Fill in email, password, name
+3. Click submit button
+4. Wait for success message
+5. Redirect to dashboard
+6. User can access protected content
+
+**Example 2: Login with Invalid Credentials**
+Test: Login with wrong password
+1. Navigate to login page
+2. Enter email and wrong password
+3. Click login button
+4. See error message "Invalid credentials"
+5. Still on login page (not redirected)
+6. Can try again
+
+**Example 3: Multi-step Workflow**
+Test: User can complete purchase
+1. Navigate to product page
+2. Add item to cart
+3. Navigate to checkout
+4. Enter shipping information
+5. Enter payment information
+6. Submit order
+7. See confirmation page
+8. Receive confirmation email
+
+## Accessibility Testing
+
+Test that your application meets WCAG 2.1 AA standards.
+
+### Automated Accessibility Testing
+
+Use tools to scan for common accessibility violations:
+- Color contrast issues
+- Missing alt text for images
+- Missing labels for form inputs
+- Heading hierarchy problems
+- Missing ARIA attributes
+
+### Manual Accessibility Testing
+
+- Keyboard navigation: Can user navigate with Tab and Enter?
+- Screen reader: Does content make sense when read aloud?
+- Visual clarity: Can text be read at smaller sizes?
+- Color dependency: Is information conveyed without color alone?
+- Responsiveness: Does layout work on different screen sizes?
+
+## Performance Testing
+
+Test performance requirements and regressions.
+
+### Performance Metrics to Monitor
+
+**Web Applications:**
+- First Contentful Paint (FCP)
+- Largest Contentful Paint (LCP)
+- Cumulative Layout Shift (CLS)
+- Time to Interactive (TTI)
+- Page load time
+
+**API Endpoints:**
+- Response time (p50, p95, p99)
+- Throughput (requests per second)
+- Error rate
+- Database query time
+- Memory usage
+
+### Performance Testing Examples
+
+Test: API response time
+- Create 100 users in database
+- Query all users endpoint
+- Measure response time
+- Assert completes in <500ms
+
+Test: Page load performance
+- Navigate to homepage
+- Measure First Contentful Paint
+- Assert completes in <2 seconds
+
+Test: Database query optimization
+- Insert 10,000 records
+- Run query with filter
+- Verify query uses index
+- Measure execution time
+- Assert completes efficiently
+
+## Hardening Verification Testing
+
+When hardening/obfuscation is enabled (see `.claude/rules/hardening.mdc`), require additional validation on hardened artifacts.
+
+### Required Checks for Hardened Builds
+
+- Run core functional regression tests against hardened output, not only non-hardened builds.
+- Run performance checks and compare against accepted budgets (startup, latency, memory as applicable).
+- Validate crash/debug workflow with restricted symbol/mapping artifact access controls.
+- Confirm release evidence includes hardening profile rationale and rollback trigger/steps.
+
+If these checks are missing for a hardening-required profile, release readiness should be treated as blocked.
+
+## Security Testing
+
+Test security requirements and threat scenarios.
+
+### Security Tests
+
+Test: Input Validation
+- SQL injection payloads in fields
+- XSS payloads in fields
+- Extremely long strings
+- Special characters
+- Wrong data types
+
+Test: Authentication
+- Login with wrong password
+- Access protected endpoint without credentials
+- Use expired token
+- Use modified token
+
+Test: Authorization
+- Access another user's data
+- Perform admin operation as regular user
+- Modify resource of different user
+
+Test: Rate Limiting
+- Exceed rate limit on authentication
+- Verify 429 response
+- Verify retry-after header
+
+## Test Organization
+
+Organize tests logically for easy maintenance: