agents-templated 2.2.17 → 2.2.19

package/templates/agents/rules/testing.md

@@ -1,371 +0,0 @@
----
-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"]
----
-
-# 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 `agents/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:
-
-Project Structure:
-tests/
- unit/
-    utils/           # Utility function tests
-    services/        # Business logic tests
-    validators/      # Validation tests
-    formatters/      # Formatter tests
-
- integration/
-    api/            # API endpoint tests
-    database/       # Database operation tests
-    auth/           # Authentication tests
-    services/       # Service integration tests
-
- e2e/
-    auth/           # Authentication flows
-    workflows/      # Critical user journeys
-    forms/          # Form submission flows
-    pages/          # Page components (if applicable)
-
- a11y/               # Accessibility tests
- performance/        # Performance tests
- fixtures/           # Test data
- setup.ts            # Test configuration
-
-## Test Coverage Guidelines
-
-### Coverage Targets
-
-- **Business Logic**: 80%+ coverage required
-- **Controllers/Routes**: 70%+ coverage
-- **Utils/Helpers**: 90%+ coverage
-- **UI Components**: 60%+ coverage
-- **Overall**: 75%+ coverage target
-
-### Coverage Measurement
-
-- Generate coverage reports regularly
-- Track coverage trends over time
-- Identify uncovered critical code
-- The goal is quality, not just high numbers
-
-## Best Practices
-
-### General Best Practices
-
-- Write tests as you write code (TDD or regular)
-- Make tests as simple as production code
-- Use meaningful test names that describe behavior
-- Keep tests focused on one thing
-- Avoid test interdependencies (order shouldn''t matter)
-- Clean up test data (database, files, etc.)
-- Use version control for test data when needed
-
-### Avoiding Common Mistakes
-
-- Testing implementation details instead of behavior
-- Writing tests that are brittle (break on minor changes)
-- Tests that are slower than necessary
-- Not testing error cases and edge cases
-- Skipping security-related tests
-- Skipping accessibility tests
-- Not maintaining tests (let them rot)
-- Testing too much in E2E when unit tests would work
-
----
-
-Remember: **Tests are documentation** of how your code should behave.
-Write clear, concise tests that describe expected behavior.
-Good tests make refactoring and maintenance easier and reduce bugs in production.

package/templates/agents/rules/workflows.md

@@ -1,56 +0,0 @@
----
-title: "Development Workflow Guidelines"
-description: "Apply to optimize development process, running pre-commit checks, enforcing quality gates, and keeping project healthy"
-alwaysApply: false
-version: "3.0.0"
-tags: ["workflow", "quality", "validation", "commit"]
-globs:
-  - "**/*"
----
-
-# Development Workflow Guidelines
-
-Technology-agnostic suggestions for keeping the project healthy and maintaining quality before commits.
-
-## When This Rule Applies
-
-Use this guidance when the user asks about workflow, pre-commit checks, or keeping the project validated. Do not force these steps on every change—treat them as recommended practices.
-
-## Project Health (agents-templated)
-
-If this project was scaffolded with agents-templated:
-
-- **Periodically**: Run `agents-templated validate` to ensure required docs and rules are present; run `agents-templated doctor` for environment and configuration recommendations.
-- **After pulling template updates**: Run `agents-templated update --check-only` to see available updates, then `agents-templated update` if you want to apply them (with backup).
-
-These commands help keep agent rules, documentation, and security patterns in sync.
-
-## Pre-Commit Quality Gates
-
-Before committing, consider running (in order):
-
-1. **Lint** – Your stack’s linter (e.g. ESLint, Pylint, golangci-lint) to catch style and simple issues.
-2. **Type check** – If applicable (TypeScript, mypy, etc.) to catch type errors.
-3. **Tests** – At least the fast test suite (e.g. unit tests) so regressions are caught early.
-4. **Project validation** – For agents-templated projects, `agents-templated validate` can confirm setup is intact.
-
-For high-risk or distributed-client releases, add hardening-specific checks before merge/release:
-
-5. **Hardening profile selection** – Document threat model and selected profile from `agents/rules/hardening.mdc`.
-6. **Post-hardening verification** – Run functional regression and performance checks on hardened artifacts.
-7. **Artifact controls** – Verify restricted handling for symbol/mapping/debug artifacts and confirm rollback path.
-
-Do not commit with failing lint or tests unless the user explicitly requests a WIP commit (e.g. with `--no-verify` or a clear “work in progress” message).
-
-## Commit Messages
-
-- Prefer clear, descriptive messages (e.g. conventional commits: `feat:`, `fix:`, `docs:`).
-- Reference issues or tickets when relevant (e.g. “Closes #123”).
-- Keep the body focused on what changed and why, not how.
-
-## Summary
-
-- Use **agents-templated validate** and **doctor** to maintain project setup and get recommendations.
-- Run **lint**, **type check**, and **tests** before committing when possible.
-- For hardening-required releases, include profile rationale, post-hardening verification evidence, and rollback readiness.
-- Write clear commit messages and reference issues where applicable.

package/templates/agents/skills/README.md

@@ -1,198 +0,0 @@
-# Agent Skills
-
-This directory contains custom skills for your AI agents. Skills extend agent capabilities with specialized knowledge, workflows, and tools for specific domains.
-
-## What is a Skill?
-
-A **skill** is a reusable module that:
-- Defines domain-specific knowledge or workflows
-- Extends agent capabilities for specialized tasks
-- Can be shared across your project or published for others
-
-**Rules** define *how to behave*; **Skills** define *how to execute specific tasks*.
-
-## Getting Started
-
-### Finding Existing Skills
-
-Use the built-in `find-skills` skill to discover skills from the open ecosystem:
-
-```bash
-npx skills find [query]
-```
-
-Examples:
-- `npx skills find react testing`
-- `npx skills find deployment`
-- `npx skills find accessibility`
-
-Browse more at: https://skills.sh/
-
-### Creating a Custom Skill
-
-To create a new skill for your specific domain:
-
-1. **Create a new folder** in this directory:
-   ```
-   .github/skills/my-custom-skill/
-   ```
-
-2. **Create a SKILL.md file** with metadata and instructions:
-   ```markdown
-   ---
-   name: my-custom-skill
-   description: Brief description of what this skill does
-   ---
-
-   # My Custom Skill
-
-   Instructions and examples for using this skill...
-   ```
-
-3. **Reference it** in your agent documentation or `.cursorrules`
-
-### Skill Structure
-
-```
-.github/skills/
-├── find-skills/
-│   └── SKILL.md              # Meta-skill for discovering skills
-├── feature-delivery/
-│   └── SKILL.md              # Systematic feature scoping and execution contracts
-├── bug-triage/
-│   └── SKILL.md              # Reproduction-first debugging and regression workflows
-├── debug-skill/
-│   └── SKILL.md              # Breakpoint-first debugging and execution tracing
-├── secure-code-guardian/
-│   └── SKILL.md              # Secure-by-default coding for auth and input boundaries
-├── feature-forge/
-│   └── SKILL.md              # Requirements forging before implementation starts
-├── error-patterns/
-│   └── SKILL.md              # Persistent debugging memory and known-fix application
-├── app-hardening/
-│   └── SKILL.md              # Risk-based hardening and obfuscation guidance
-├── ui-ux-pro-max/
-│   └── SKILL.md              # Premium UI/UX implementation patterns
-├── emilkowalski-skill/
-│   └── SKILL.md              # Frontend polish and animation quality checks
-├── raphaelsalaja-userinterface-wiki/
-│   └── SKILL.md              # UI hierarchy and interface best-practice playbook
-├── my-custom-skill/
-│   └── SKILL.md              # Your custom skill
-└── README.md                 # This file
-```
-
-## Best Practices
-
-1. **Keep skills focused** - Each skill should handle one domain or workflow
-2. **Document clearly** - Include examples and use cases in SKILL.md
-3. **Name descriptively** - Use kebab-case names that reflect the skill's purpose
-4. **Version your skills** - Include version info in the metadata
-5. **Test before sharing** - Ensure skills work as documented
-
-## Common Skill Categories
-
-Consider creating skills for:
-
-| Category        | Use Case                                 |
-| --------------- | ---------------------------------------- |
-| Web Development | Framework-specific patterns and guidelines |
-| Testing         | Testing strategies and examples          |
-| DevOps          | Deployment, CI/CD, infrastructure        |
-| Documentation   | Doc generation, README templates         |
-| Code Quality    | Code review, refactoring patterns        |
-| Design          | UI/UX, accessibility, design systems    |
-| Productivity    | Workflows, automation, git patterns      |
-
-## Recommended Baseline Skills
-
-- `feature-delivery`: Use when user asks are broad and you need objective, scope, acceptance criteria, and validation plan.
-- `bug-triage`: Use for defects and regressions requiring reproducible evidence, root-cause isolation, and minimal safe patches.
-- `debug-skill`: Use for breakpoint-driven debugging, execution tracing, and variable-state inspection.
-- `secure-code-guardian`: Use for secure-by-default implementation across auth, secrets, and untrusted input.
-- `feature-forge`: Use before coding to turn rough asks into execution-ready requirements and acceptance criteria.
-- `error-patterns`: Use when errors repeat to apply known fixes from lessons-learned and automatically record new resolutions.
-- `app-hardening`: Use for high-risk/distributed runtimes to enforce hardening profile, obfuscation decisions, and release evidence.
-- `shadcn-ui`: Use for shadcn/ui installation, component composition, form patterns, and theme customization.
-- `emilkowalski-skill`: Use for frontend animation, micro-interaction quality, and visual polish passes.
-- `raphaelsalaja-userinterface-wiki`: Use for interface hierarchy, readability, and UX consistency audits.
-
-## Using Skills in Your Project
-
-Skills can be referenced in all your AI assistant configuration files:
-
-### Cursor IDE (`.cursorrules`)
-```
-When the user asks about [domain], use the [skill-name] skill from .github/skills/[skill-name]/SKILL.md
-```
-
-### Claude (`CLAUDE.md`)
-```markdown
-## When Working on [Domain]
-
-Reference the [skill-name] skill in `.github/skills/[skill-name]/SKILL.md` for patterns and guidance.
-```
-
-### GitHub Copilot (`.github/copilot-instructions.md`)
-```markdown
-When helping with [domain-specific task], reference the [skill-name] skill from `.github/skills/[skill-name]/SKILL.md`
-```
-
-### Documentation (`AGENTS.MD`)
-```markdown
-- When working with [domain], see the [skill-name] skill in `.github/skills/[skill-name]/SKILL.md`
-```
-
-**All AI assistants support skill references.** Keep your team aligned by linking to skill files across your configuration files.
-
-3. **Share with your team**:
-   - Commit to version control
-   - Document installation in your README
-
-## Example: Creating a Fastapi Skill
-
-```markdown
----
-name: fastapi-patterns
-description: FastAPI development patterns and best practices for your projects
----
-
-# FastAPI Patterns
-
-Use this skill when working with FastAPI projects.
-
-## Recommended Patterns
-
-### Request Validation
-- Use Pydantic models for all request bodies
-- Validate query parameters with proper typing
-
-### Error Handling
-- Return meaningful HTTP status codes
-- Document error responses in OpenAPI
-
-### Testing
-- Use TestClient for API testing
-- Mock external dependencies
-
-## Project Structure
-
-```
-src/
-├── api/
-│   ├── v1/
-│   │   ├── users/
-│   │   └── posts/
-│   └── dependencies.py
-├── models/
-├── schemas/
-├── database/
-└── main.py
-```
-```
-
-## Resources
-
-- [Skills Documentation](https://skills.sh/)
-- [Creating Skills Guide](https://skills.sh/docs/creating-skills)
-- [Browse Popular Skills](https://skills.sh/explore)

package/templates/agents/skills/api-design/SKILL.md

@@ -1,59 +0,0 @@
----
-name: api-design
-description: REST and GraphQL API design — resource modeling, OpenAPI specs, versioning strategy, error contracts, pagination, and security patterns.
----
-
-# API Design
-
-Use this skill when designing, reviewing, or documenting REST or GraphQL APIs.
-
-## Trigger Conditions
-
-- User asks to design, build, or review an API endpoint or service.
-- Requests involve routes, schemas, data contracts, or API versioning.
-- Pagination, error handling, or authentication patterns are discussed.
-- OpenAPI / Swagger spec generation is needed.
-- Breaking change management or deprecation strategy is required.
-
-## Workflow
-
-### REST APIs
-
-1. Define resource hierarchy and URL structure (`/resources/{id}/sub-resources`).
-2. Apply correct HTTP methods (GET/POST/PUT/PATCH/DELETE) with idempotency notes.
-3. Design request/response schemas with explicit, versioned types.
-4. Define the error contract: `{ error: { code, message, details } }` with HTTP status mapping.
-5. Choose pagination strategy: cursor-based for large/real-time datasets; offset for simple cases.
-6. Document authentication scheme (Bearer token, API key, OAuth2 scopes) per endpoint.
-7. Generate OpenAPI 3.1 spec.
-
-### GraphQL APIs
-
-1. Design schema types, queries, mutations, and subscriptions.
-2. Apply DataLoader pattern to prevent N+1 queries.
-3. Define error types in schema (not just HTTP-layer errors).
-4. Enforce query depth and complexity limits to prevent abuse.
-5. Document field-level deprecation strategy (`@deprecated` directive with migration notes).
-
-### Versioning
-
-- Prefer URI versioning (`/v1/`, `/v2/`) for REST; field deprecation for GraphQL.
-- Never mutate an existing contract in place — breaking changes require a new version.
-- Maintain prior version for at least one deprecation cycle with migration docs.
-
-## Output Contract
-
-- Resource or type definitions
-- Endpoint / operation list with method, path, auth requirement
-- Request/response schema examples (JSON)
-- Error code reference table
-- Pagination strategy description
-- OpenAPI 3.1 spec (REST) or SDL schema (GraphQL)
-
-## Guardrails
-
-- Never expose internal stack traces or DB column names in error responses.
-- Always validate input at the API boundary — never trust client-supplied data.
-- Do not design endpoints that require admin-level credentials from the client.
-- Rate limit all public-facing endpoints.
-- Apply `agents/rules/security.mdc` for all auth and input handling decisions.