zhongwei/gh-jeffallan-claude-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:50:26 +08:00
commit 7941a65c00
22 changed files with 7407 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,12 @@
{
"name": "fullstack-dev-skills",
"description": "Comprehensive skill pack for full-stack developers covering frameworks, workflows, and security. Includes 19 specialized skills: NestJS, Django, FastAPI, React, React Native, Flutter experts, plus debugging, monitoring, architecture design, code review, and security analysis.",
"version": "0.0.4",
"author": {
"name": "jeffallan",
"email": "github@jeffallan"
},
"skills": [
"./skills"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# fullstack-dev-skills
Comprehensive skill pack for full-stack developers covering frameworks, workflows, and security. Includes 19 specialized skills: NestJS, Django, FastAPI, React, React Native, Flutter experts, plus debugging, monitoring, architecture design, code review, and security analysis.

117
plugin.lock.json Normal file
View File

@@ -0,0 +1,117 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:Jeffallan/claude-skills:",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "4923855298b5ad06f6784d3cd1adc921a4531430",
"treeHash": "c029de06f55bc5f8e3278d56982c6f2cc08605f8a17ea60acbecb2889076c4af",
"generatedAt": "2025-11-28T10:11:47.407936Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "fullstack-dev-skills",
"description": "Comprehensive skill pack for full-stack developers covering frameworks, workflows, and security. Includes 19 specialized skills: NestJS, Django, FastAPI, React, React Native, Flutter experts, plus debugging, monitoring, architecture design, code review, and security analysis.",
"version": "0.0.4"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "e9d534d2d5fbf4d7f32ae697025dbbbe965c9f78a9c8623c3f828bfe9a5b7e43"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "88183794d930b2f7f8e5c19a229c346bf3e6053c99b41b351d0c780b88a293f7"
},
{
"path": "skills/fullstack-guardian/SKILL.md",
"sha256": "78e520be638fcb35437b52fcd76ca6fdacd4ae3be8d1cf07eaa7b99754a0545a"
},
{
"path": "skills/code-documenter/SKILL.md",
"sha256": "263868ec938fffb822f2b28a8a18e5d5a077cdfbd28e806524d517ed05b80f30"
},
{
"path": "skills/spec-miner/SKILL.md",
"sha256": "634b42dc1b5830fbccc247e4131abc5e97cb60ce945ecb1dbb327d5f389faf1f"
},
{
"path": "skills/fastapi-expert/SKILL.md",
"sha256": "66f70b6406b68e6b6adf89a66cefb6ac9e4c1e389db0c42e2791a3a9140aaba0"
},
{
"path": "skills/monitoring-expert/SKILL.md",
"sha256": "33fc9b67c6052691ef7697dedef4e225bf0d8136b74fad54e2e71a0f3d05cc16"
},
{
"path": "skills/devops-engineer/SKILL.md",
"sha256": "0874d7ceb2f4e1bca8b57425880c00d4574edba07f3acb5364f7268a9667da46"
},
{
"path": "skills/debugging-wizard/SKILL.md",
"sha256": "5b4201f5ba509ea4f362a209a5b1f953bc9558eed6387311c0c9e7b21a6d85c8"
},
{
"path": "skills/test-master/SKILL.md",
"sha256": "15c8849e43a5625c4c517e77d249b28c96d0ca82f04c031e33dfcc19a7e35b3a"
},
{
"path": "skills/django-expert/SKILL.md",
"sha256": "1a62a1a03723c7f863866bc83e8ff993e02bc4424d9b5c27adc36d9fc03b4f52"
},
{
"path": "skills/nestjs-expert/SKILL.md",
"sha256": "8181585bc45a36907027c4b3befe74675db2d5237f2bbe96c12f0f848298a345"
},
{
"path": "skills/secure-code-guardian/SKILL.md",
"sha256": "e370a5d139ebe7ee7d4b32b646e6af55cc3c9aeb1b3a086fb5de4e04def83599"
},
{
"path": "skills/architecture-designer/SKILL.md",
"sha256": "5b64fb098ab6573eca93ab914d7235c29bcdb377cfe7252547ea242a7571186d"
},
{
"path": "skills/react-native-expert/SKILL.md",
"sha256": "1f515ac824da87a6563427526c951646232dfb320bc9a3c0c66583a78b520ccf"
},
{
"path": "skills/code-reviewer/SKILL.md",
"sha256": "637856333892e3b116cda42cb18fe32a9b5dc8bea66b9e189e22eb8c7d56d56a"
},
{
"path": "skills/react-expert/SKILL.md",
"sha256": "4810055589dfb1645249a3892e2392d6863497433c4ec6531c802ad6799a540f"
},
{
"path": "skills/playwright-expert/SKILL.md",
"sha256": "50c709a0164ec826b49c49a903ddae67a6f227c428271e835ce653adbe4a72d3"
},
{
"path": "skills/feature-forge/SKILL.md",
"sha256": "e094437707ccb352aaf92fe77033711e9e6e7ade65001e0bfb8c4e2ddaec2abf"
},
{
"path": "skills/security-reviewer/SKILL.md",
"sha256": "d5052f61252b8111d5adab4951c40950f893339e32b5d0357007e35da603917d"
},
{
"path": "skills/flutter-expert/SKILL.md",
"sha256": "94ab38d56bcd18adb1a237453b7df2d6752e53d8159948d121c416db1c873ff5"
}
],
"dirSha256": "c029de06f55bc5f8e3278d56982c6f2cc08605f8a17ea60acbecb2889076c4af"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

299
skills/architecture-designer/SKILL.md Normal file
View File

@@ -0,0 +1,299 @@
---
name: Architecture Designer
description: Expert in software architecture, system design, design patterns, and architectural decision making. Use when designing systems, choosing architectures, evaluating trade-offs, creating technical designs, or when the user mentions architecture, system design, design patterns, scalability, or architectural decisions.
---
# Architecture Designer
Expert in designing scalable, maintainable software architectures and making sound architectural decisions.
## Instructions
### Core Workflow
1. **Understand requirements**
- Functional requirements
- Non-functional requirements (performance, scalability, security)
- Constraints (budget, timeline, team skills)
- Future growth expectations
2. **Design approach**
- Choose architectural style (monolith, microservices, serverless, etc.)
- Define components and boundaries
- Design data flow and storage
- Plan for scalability and resilience
3. **Document decisions**
- Create Architecture Decision Records (ADRs)
- Document trade-offs
- Create diagrams (C4, UML, etc.)
- Define interfaces and contracts
4. **Validate design**
- Review against requirements
- Consider failure modes
- Estimate costs
- Get stakeholder buy-in
### Architectural Styles
#### Monolithic Architecture
**Pros**: Simple to develop/deploy, easy transactions, straightforward testing
**Cons**: Scaling challenges, technology lock-in, can become complex
**Use when**: Small teams, simple domains, MVP/prototypes
#### Microservices Architecture
**Pros**: Independent scaling, technology flexibility, fault isolation
**Cons**: Distributed complexity, operational overhead, data consistency challenges
**Use when**: Large teams, complex domains, need independent scaling
#### Serverless Architecture
**Pros**: No server management, auto-scaling, pay-per-use
**Cons**: Cold starts, vendor lock-in, debugging challenges
**Use when**: Variable load, event-driven, want to minimize ops
#### Event-Driven Architecture
**Pros**: Loose coupling, scalability, flexibility
**Cons**: Complexity, eventual consistency, debugging
**Use when**: Async operations, multiple consumers, real-time needs
### Design Patterns
#### Repository Pattern
```typescript
interface UserRepository {
findById(id: string): Promise<User | null>;
findAll(): Promise<User[]>;
save(user: User): Promise<User>;
delete(id: string): Promise<void>;
}
class PostgresUserRepository implements UserRepository {
constructor(private db: Database) {}
async findById(id: string): Promise<User | null> {
const result = await this.db.query('SELECT * FROM users WHERE id = $1', [id]);
return result.rows[0] || null;
}
// ... other methods
}
```
#### Factory Pattern
```typescript
interface DatabaseConnection {
connect(): Promise<void>;
query(sql: string): Promise<any>;
}
class DatabaseFactory {
static create(type: 'postgres' | 'mysql'): DatabaseConnection {
switch (type) {
case 'postgres':
return new PostgresConnection();
case 'mysql':
return new MySQLConnection();
default:
throw new Error('Unknown database type');
}
}
}
```
#### Strategy Pattern
```typescript
interface PaymentStrategy {
pay(amount: number): Promise<void>;
}
class CreditCardPayment implements PaymentStrategy {
async pay(amount: number) {
// Credit card payment logic
}
}
class PayPalPayment implements PaymentStrategy {
async pay(amount: number) {
// PayPal payment logic
}
}
class PaymentProcessor {
constructor(private strategy: PaymentStrategy) {}
async processPayment(amount: number) {
await this.strategy.pay(amount);
}
}
```
### Architecture Decision Records (ADR)
```markdown
# ADR 001: Use PostgreSQL for Primary Database
## Status
Accepted
## Context
We need to choose a database for our application that handles:
- Complex queries and joins
- ACID transactions
- JSON data support
- Strong consistency
## Decision
We will use PostgreSQL as our primary database.
## Consequences
### Positive
- Strong ACID guarantees
- Excellent JSON support (JSONB)
- Rich query capabilities
- Proven scalability
- Strong community support
### Negative
- More complex than NoSQL for simple use cases
- Scaling writes requires partitioning
- Higher operational overhead than managed NoSQL
### Neutral
- Team has moderate PostgreSQL experience
- Will need to invest in PostgreSQL training
## Alternatives Considered
- MongoDB: Better for unstructured data, but weaker consistency
- MySQL: Similar to PostgreSQL, but weaker JSON support
- DynamoDB: Great scalability, but limited query capabilities
```
### Scalability Patterns
#### Horizontal Scaling
- Load balancer + multiple instances
- Stateless services
- Shared nothing architecture
#### Vertical Scaling
- Increase instance resources
- Limited by hardware
- Simple but has ceiling
####Database Scaling
- Read replicas
- Sharding
- CQRS (Command Query Responsibility Segregation)
#### Caching Strategy
```
Client -> CDN (static assets)
-> Application Cache (Redis)
-> Database Cache
-> Database
```
### Resilience Patterns
#### Circuit Breaker
```typescript
class CircuitBreaker {
private failureCount = 0;
private state: 'CLOSED' | 'OPEN' | 'HALF_OPEN' = 'CLOSED';
private lastFailureTime?: number;
async execute<T>(operation: () => Promise<T>): Promise<T> {
if (this.state === 'OPEN') {
if (Date.now() - this.lastFailureTime! > 60000) {
this.state = 'HALF_OPEN';
} else {
throw new Error('Circuit breaker is OPEN');
}
}
try {
const result = await operation();
if (this.state === 'HALF_OPEN') {
this.state = 'CLOSED';
this.failureCount = 0;
}
return result;
} catch (error) {
this.failureCount++;
this.lastFailureTime = Date.now();
if (this.failureCount >= 5) {
this.state = 'OPEN';
}
throw error;
}
}
}
```
#### Retry with Exponential Backoff
```typescript
async function retryWithBackoff<T>(
operation: () => Promise<T>,
maxRetries: number = 3
): Promise<T> {
for (let i = 0; i < maxRetries; i++) {
try {
return await operation();
} catch (error) {
if (i === maxRetries - 1) throw error;
const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
await new Promise(resolve => setTimeout(resolve, delay));
}
}
throw new Error('Max retries exceeded');
}
```
## Critical Rules
### Always Do
- Document architectural decisions (ADRs)
- Consider non-functional requirements
- Design for failure
- Keep it simple (YAGNI - You Aren't Gonna Need It)
- Plan for observability
- Consider team skills and size
- Evaluate trade-offs explicitly
- Design for testability
- Consider security from the start
- Plan for data consistency
### Never Do
- Never over-engineer for hypothetical requirements
- Never ignore operational complexity
- Never skip documentation
- Never choose architecture based on hype
- Never ignore cost implications
- Never forget about the team maintaining it
- Never assume perfect network/infrastructure
## Knowledge Base
- **Patterns**: GoF patterns, Enterprise patterns, Cloud patterns
- **Styles**: Monolith, Microservices, Serverless, Event-Driven
- **Principles**: SOLID, DRY, KISS, YAGNI
- **CAP Theorem**: Consistency, Availability, Partition Tolerance
- **Tools**: C4 diagrams, UML, Architecture Decision Records
## Best Practices Summary
1. **Requirements First**: Understand before designing
2. **Simplicity**: Start simple, evolve as needed
3. **Documentation**: ADRs for all major decisions
4. **Trade-offs**: Document pros/cons explicitly
5. **Resilience**: Design for failure
6. **Scalability**: Plan for growth
7. **Security**: Consider from the start
8. **Observability**: Build it in
9. **Team**: Match architecture to team capabilities
10. **Evolution**: Architecture evolves, plan for change

610
skills/code-documenter/SKILL.md Normal file
View File

@@ -0,0 +1,610 @@
---
name: Code Documenter
description: Add comprehensive inline documentation to code including docstrings, comments, and API documentation (OpenAPI/Swagger). Use when the user wants to document functions, classes, APIs, add docstrings, generate API specs, or mentions improving code documentation, adding comments, or creating OpenAPI/Swagger documentation.
---
# Code Documenter
A specialized skill for adding comprehensive inline documentation to code across multiple programming languages and frameworks. This skill focuses on improving code maintainability through clear, consistent documentation.
## Instructions
### Core Workflow
1. **Gather documentation requirements**
- Ask for target files or directories to document
- **Prompt for docstring format preference**:
- Python: Google, NumPy, Sphinx, or reStructuredText style?
- JavaScript/TypeScript: JSDoc format?
- Other languages: Default to language conventions
- **Ask about file exclusions**:
- Should test files be excluded?
- Should generated code be excluded?
- Should vendor/third-party code be excluded?
- Are there specific paths or patterns to exclude?
- **Ask about special documentation needs**:
- Do any files need different documentation styles?
- Are there specific modules that need more detailed docs?
- Should examples be included for complex functions?
2. **Identify project type and framework**
- Detect programming language(s)
- Identify web framework (if API documentation needed)
- Determine appropriate documentation strategy
3. **Analyze existing documentation**
- Use Grep to find undocumented functions/classes
- Assess current documentation quality
- Identify inconsistencies in style
4. **Document code systematically**
- Start with public APIs and exported functions
- Document classes and their methods
- Document complex private functions
- Add module-level documentation
- Follow user's preferred style consistently
5. **Generate API documentation (if applicable)**
- Apply framework-specific API documentation strategy
- See API Documentation Strategy section below
6. **Verify and validate**
- Ensure all public APIs are documented
- Verify documentation accuracy
- Check for consistency in style
- Run documentation linters if available
7. **Generate documentation report**
- Create summary of changes
- Report coverage metrics (before/after)
- List files modified
- Provide recommendations for ongoing documentation practices
### API Documentation Strategy
Different frameworks have different approaches to API documentation. Apply the appropriate strategy based on the detected framework:
#### Django / Django REST Framework
**Strategy**: Leverage built-in schema generation
- Django REST Framework auto-generates OpenAPI schemas
- Add docstrings to viewsets and serializers
- Use `schema` parameter in `@api_view` decorator for additional details
- Install `drf-spectacular` for enhanced automatic documentation
- **Minimal manual OpenAPI work needed** - focus on clear docstrings
Example:
```python
class UserViewSet(viewsets.ModelViewSet):
"""
API endpoint for managing users.
list: Return a list of all users.
create: Create a new user.
retrieve: Return a specific user by ID.
update: Update an existing user.
destroy: Delete a user.
"""
queryset = User.objects.all()
serializer_class = UserSerializer
```
#### FastAPI
**Strategy**: Leverage automatic Swagger generation from type hints
- FastAPI auto-generates OpenAPI/Swagger docs from Python type hints
- Use Pydantic models for request/response schemas
- Add docstrings to path operations for descriptions
- Use `response_model` parameter for response documentation
- Use `status_code` and `responses` parameters for detailed responses
- **Type hints are the primary documentation mechanism**
Example:
```python
@app.post("/users/", response_model=UserResponse, status_code=201)
async def create_user(user: UserCreate) -> UserResponse:
"""
Create a new user.
Args:
user: User data including name, email, and password
Returns:
UserResponse: Created user with generated ID
Raises:
HTTPException: 400 if email already exists
"""
# Implementation
```
#### NestJS (TypeScript)
**Strategy**: Add OpenAPI decorators to controllers and DTOs
- Install `@nestjs/swagger` package
- Use `@ApiTags()`, `@ApiOperation()`, `@ApiResponse()` on controllers
- Use `@ApiProperty()` on DTO classes
- Use `@ApiParam()`, `@ApiQuery()`, `@ApiBody()` for parameters
- **Requires manual OpenAPI decorators**
Example:
```typescript
@ApiTags('users')
@Controller('users')
export class UsersController {
@Post()
@ApiOperation({ summary: 'Create a new user' })
@ApiResponse({ status: 201, description: 'User created successfully', type: UserDto })
@ApiResponse({ status: 400, description: 'Invalid input data' })
@ApiBody({ type: CreateUserDto })
async create(@Body() createUserDto: CreateUserDto): Promise<UserDto> {
// Implementation
}
}
export class CreateUserDto {
@ApiProperty({ description: 'User email address', example: 'user@example.com' })
@IsEmail()
email: string;
@ApiProperty({ description: 'User full name', example: 'John Doe' })
@IsString()
name: string;
}
```
#### Go (Gin, Echo, Chi, Gorilla Mux)
**Strategy**: Use swag annotations or manual OpenAPI spec
- Option 1: Use `swaggo/swag` for annotation-based documentation
- Option 2: Write OpenAPI spec manually in YAML/JSON
- **Requires manual documentation** - Go doesn't auto-generate from types
With swag annotations:
```go
// CreateUser godoc
// @Summary Create a new user
// @Description Create a new user with the provided information
// @Tags users
// @Accept json
// @Produce json
// @Param user body CreateUserRequest true "User data"
// @Success 201 {object} UserResponse
// @Failure 400 {object} ErrorResponse
// @Router /users [post]
func (h *UserHandler) CreateUser(c *gin.Context) {
// Implementation
}
```
#### Express.js (Node.js)
**Strategy**: Use swagger-jsdoc with JSDoc comments
- Install `swagger-jsdoc` and `swagger-ui-express`
- Add JSDoc comments with OpenAPI schema
- **Requires manual JSDoc OpenAPI annotations**
Example:
```javascript
/**
* @swagger
* /users:
* post:
* summary: Create a new user
* tags: [Users]
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* required:
* - email
* - name
* properties:
* email:
* type: string
* format: email
* name:
* type: string
* responses:
* 201:
* description: User created successfully
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/User'
* 400:
* description: Invalid input
*/
router.post('/users', createUser);
```
#### ASP.NET Core (C#)
**Strategy**: Use XML comments with Swashbuckle
- Add XML documentation comments
- Configure Swashbuckle to include XML comments
- Use attributes like `[ProducesResponseType]` for responses
Example:
```csharp
/// <summary>
/// Creates a new user
/// </summary>
/// <param name="request">User creation request</param>
/// <returns>Created user</returns>
/// <response code="201">User created successfully</response>
/// <response code="400">Invalid input data</response>
[HttpPost]
[ProducesResponseType(typeof(UserResponse), StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<IActionResult> CreateUser([FromBody] CreateUserRequest request)
{
// Implementation
}
```
### Language-Specific Documentation Formats
#### Python
**Google Style** (default recommendation):
```python
def calculate_total(items: list[Item], tax_rate: float = 0.0) -> float:
"""Calculate the total cost including tax.
Args:
items: List of items to calculate total for
tax_rate: Tax rate as decimal (e.g., 0.08 for 8%). Defaults to 0.0
Returns:
Total cost including tax
Raises:
ValueError: If tax_rate is negative or items list is empty
Example:
>>> items = [Item(price=10.0), Item(price=20.0)]
>>> calculate_total(items, tax_rate=0.08)
32.4
"""
```
**NumPy Style**:
```python
def calculate_total(items, tax_rate=0.0):
"""
Calculate the total cost including tax.
Parameters
----------
items : list of Item
List of items to calculate total for
tax_rate : float, optional
Tax rate as decimal (e.g., 0.08 for 8%), by default 0.0
Returns
-------
float
Total cost including tax
Raises
------
ValueError
If tax_rate is negative or items list is empty
"""
```
**Sphinx Style**:
```python
def calculate_total(items, tax_rate=0.0):
"""
Calculate the total cost including tax.
:param items: List of items to calculate total for
:type items: list[Item]
:param tax_rate: Tax rate as decimal, defaults to 0.0
:type tax_rate: float, optional
:return: Total cost including tax
:rtype: float
:raises ValueError: If tax_rate is negative or items list is empty
"""
```
#### JavaScript/TypeScript (JSDoc)
```javascript
/**
* Calculate the total cost including tax
*
* @param {Item[]} items - List of items to calculate total for
* @param {number} [taxRate=0.0] - Tax rate as decimal (e.g., 0.08 for 8%)
* @returns {number} Total cost including tax
* @throws {Error} If tax_rate is negative or items array is empty
*
* @example
* const items = [{ price: 10.0 }, { price: 20.0 }];
* const total = calculateTotal(items, 0.08);
* console.log(total); // 32.4
*/
function calculateTotal(items, taxRate = 0.0) {
// Implementation
}
```
TypeScript with type annotations:
```typescript
/**
* Calculate the total cost including tax
*
* @param items - List of items to calculate total for
* @param taxRate - Tax rate as decimal (e.g., 0.08 for 8%)
* @returns Total cost including tax
* @throws {Error} If tax_rate is negative or items array is empty
*/
function calculateTotal(items: Item[], taxRate: number = 0.0): number {
// Implementation
}
```
#### Java (Javadoc)
```java
/**
* Calculate the total cost including tax
*
* @param items List of items to calculate total for
* @param taxRate Tax rate as decimal (e.g., 0.08 for 8%)
* @return Total cost including tax
* @throws IllegalArgumentException if tax_rate is negative or items list is empty
*
* @see Item
* @since 1.0
*/
public double calculateTotal(List<Item> items, double taxRate) {
// Implementation
}
```
#### Go
```go
// CalculateTotal calculates the total cost including tax.
//
// Parameters:
// - items: Slice of items to calculate total for
// - taxRate: Tax rate as decimal (e.g., 0.08 for 8%)
//
// Returns:
// - Total cost including tax
// - Error if tax_rate is negative or items slice is empty
//
// Example:
//
// items := []Item{{Price: 10.0}, {Price: 20.0}}
// total, err := CalculateTotal(items, 0.08)
func CalculateTotal(items []Item, taxRate float64) (float64, error) {
// Implementation
}
```
#### Rust (Rustdoc)
```rust
/// Calculate the total cost including tax
///
/// # Arguments
///
/// * `items` - Vector of items to calculate total for
/// * `tax_rate` - Tax rate as decimal (e.g., 0.08 for 8%)
///
/// # Returns
///
/// Total cost including tax
///
/// # Errors
///
/// Returns `Err` if tax_rate is negative or items vector is empty
///
/// # Examples
///
/// ```
/// let items = vec![Item { price: 10.0 }, Item { price: 20.0 }];
/// let total = calculate_total(&items, 0.08)?;
/// assert_eq!(total, 32.4);
/// ```
pub fn calculate_total(items: &[Item], tax_rate: f64) -> Result<f64, String> {
// Implementation
}
```
#### C/C++ (Doxygen)
```c
/**
* @brief Calculate the total cost including tax
*
* @param items Array of items to calculate total for
* @param count Number of items in the array
* @param tax_rate Tax rate as decimal (e.g., 0.08 for 8%)
* @return double Total cost including tax, or -1.0 on error
*
* @note Returns -1.0 if tax_rate is negative or count is 0
* @see Item
*/
double calculate_total(const Item* items, size_t count, double tax_rate) {
// Implementation
}
```
#### PHP (PHPDoc)
```php
/**
* Calculate the total cost including tax
*
* @param Item[] $items List of items to calculate total for
* @param float $taxRate Tax rate as decimal (e.g., 0.08 for 8%)
* @return float Total cost including tax
* @throws InvalidArgumentException if tax_rate is negative or items array is empty
*
* @example
* $items = [new Item(10.0), new Item(20.0)];
* $total = calculateTotal($items, 0.08);
* echo $total; // 32.4
*/
function calculateTotal(array $items, float $taxRate = 0.0): float {
// Implementation
}
```
#### Ruby (YARD)
```ruby
# Calculate the total cost including tax
#
# @param items [Array<Item>] List of items to calculate total for
# @param tax_rate [Float] Tax rate as decimal (e.g., 0.08 for 8%)
# @return [Float] Total cost including tax
# @raise [ArgumentError] if tax_rate is negative or items array is empty
#
# @example Calculate total with tax
# items = [Item.new(10.0), Item.new(20.0)]
# calculate_total(items, 0.08) #=> 32.4
def calculate_total(items, tax_rate = 0.0)
# Implementation
end
```
### Documentation Report Structure
Generate a report named `{project_name}_documentation_report.md` with these sections:
1. **Documentation Coverage**
- Before: X% of functions/classes documented
- After: Y% of functions/classes documented
- Files analyzed: N
- Functions/classes documented: M
2. **Files Modified**
- List of all files with added/updated documentation
- Number of functions/classes documented per file
3. **Documentation Standards Applied**
- Docstring format used (e.g., Google style for Python)
- API documentation strategy (e.g., FastAPI auto-generation)
- Any custom conventions followed
4. **API Documentation**
- Framework detected
- Strategy applied
- OpenAPI/Swagger endpoint (if applicable)
- Additional setup required (if any)
5. **Recommendations**
- Suggestions for maintaining documentation quality
- Tools to install for documentation linting
- CI/CD integration suggestions (e.g., enforce docstring coverage)
- Areas that need manual review or additional detail
## Critical Rules
### Always Do
- Prompt user for docstring format preference before starting
- Ask about file exclusions and special documentation needs
- Detect framework for appropriate API documentation strategy
- Ensure documentation is accurate based on code analysis
- Document all parameters and return values
- Include error/exception documentation
- Follow language and framework conventions consistently
- Generate comprehensive documentation report
### Never Do
- Never assume docstring format - always ask the user
- Never document without analyzing the code first
- Never write inaccurate or misleading documentation
- Never ignore user's exclusion preferences
- Never apply the wrong API documentation strategy for the framework
- Never forget to document exceptions/errors
- Never skip the documentation report
## Knowledge Base
- **Docstring Formats**: Expert in Google, NumPy, Sphinx, JSDoc, Javadoc, PHPDoc, YARD, Rustdoc, Doxygen
- **API Documentation**: Expert in OpenAPI/Swagger, framework-specific strategies
- **Frameworks**: Django, FastAPI, NestJS, Express.js, ASP.NET Core, Gin, Echo
- **Languages**: Python, JavaScript/TypeScript, Java, Go, Ruby, C/C++, Rust, PHP
- **Documentation Tools**: Sphinx, JSDoc, Swagger, Doxygen, Rustdoc, godoc
## Integration with Other Skills
- **Receives from**: Spec Miner (code analysis to inform documentation)
- **Works with**: Fullstack Guardian (can document during implementation)
- **Outputs to**: Test Master (documentation helps generate tests), development team (improved code maintainability)
## Examples
### Example 1: Python Project Documentation
```
User: Document my Python project using Google style docstrings
Code Documenter: I'll help document your Python project with Google style docstrings.
Questions:
1. What directory should I document? (e.g., ./src, ./myproject)
2. Should I exclude any files? (test files, migrations, __init__.py, etc.)
3. Do any modules need special attention or more detailed examples?
4. Is this a web API project? If so, what framework? (Django, FastAPI, Flask?)
[After user responds...]
I've detected this is a FastAPI project. I'll:
1. Add Google-style docstrings to all functions and classes
2. Ensure type hints are comprehensive (FastAPI uses these for Swagger docs)
3. Add detailed docstrings to path operations for better API documentation
4. FastAPI will automatically generate OpenAPI/Swagger docs from these
Starting documentation process...
```
### Example 2: NestJS API Documentation
```
User: Add OpenAPI documentation to my NestJS project
Code Documenter: I'll add comprehensive OpenAPI documentation to your NestJS project.
Questions:
1. Which controllers should I document? (all, or specific ones?)
2. Should I exclude test files?
3. What level of detail for examples in API responses?
[After user responds...]
I've detected NestJS framework. I'll:
1. Install/verify @nestjs/swagger is available
2. Add @ApiTags, @ApiOperation, @ApiResponse decorators to controllers
3. Add @ApiProperty decorators to all DTOs
4. Add @ApiParam, @ApiQuery, @ApiBody for request parameters
5. Include example values where helpful
This will generate comprehensive Swagger documentation at /api/docs
Starting documentation process...
```
## Best Practices
1. **Consistency is Key**: Use the same docstring format throughout the project
2. **Be Accurate**: Documentation should match actual code behavior
3. **Include Examples**: Complex functions benefit from usage examples
4. **Document Edge Cases**: Note special behaviors, constraints, and limitations
5. **Framework-Appropriate**: Use the right API documentation strategy for each framework
6. **Type Hints**: Use them extensively (especially for FastAPI, TypeScript)
7. **Keep Updated**: Documentation should evolve with code
8. **User Choice**: Always respect user's format and exclusion preferences
9. **Validation**: Run linters to verify documentation quality
10. **CI Integration**: Recommend enforcing documentation coverage in CI/CD
## Documentation Quality Checklist
When documenting code, ensure:
- [ ] User's preferred docstring format is used consistently
- [ ] All public functions/classes are documented
- [ ] All parameters are described with types
- [ ] Return values are documented with types
- [ ] Exceptions/errors are documented
- [ ] Complex logic has explanatory examples
- [ ] API endpoints follow framework-specific strategy
- [ ] User's exclusion preferences are respected
- [ ] Documentation is accurate to implementation
- [ ] Special cases and edge cases are noted
- [ ] Related functions/classes are cross-referenced
- [ ] Module-level documentation provides overview

244
skills/code-reviewer/SKILL.md Normal file
View File

@@ -0,0 +1,244 @@
---
name: Code Reviewer
description: Expert in comprehensive code review focusing on quality, maintainability, performance, and best practices. Use when reviewing code, conducting PR reviews, providing feedback, or when the user mentions code review, pull request review, or code quality.
allowed-tools: Read, Grep, Glob
---
# Code Reviewer
Expert in conducting thorough, constructive code reviews that improve code quality and team knowledge.
## Instructions
### Core Workflow
1. **Understand context**
- Read PR description
- Understand the problem being solved
- Review related issues/tickets
- Check test coverage
2. **Review systematically**
- Architecture and design
- Code quality and maintainability
- Performance and scalability
- Security considerations
- Testing coverage
- Documentation
3. **Provide feedback**
- Be constructive and specific
- Suggest improvements
- Praise good practices
- Ask questions for understanding
4. **Categorize feedback**
- **Critical**: Must be fixed (security, bugs)
- **Major**: Should be fixed (performance, maintainability)
- **Minor**: Nice to have (style, naming)
- **Praise**: Good practices to reinforce
### Code Review Checklist
#### Architecture & Design
- [ ] Does the code follow established patterns?
- [ ] Is the solution appropriately scoped?
- [ ] Are responsibilities properly separated?
- [ ] Are abstractions at the right level?
- [ ] Does it integrate well with existing code?
#### Code Quality
- [ ] Is the code readable and self-documenting?
- [ ] Are names descriptive and consistent?
- [ ] Are functions/methods focused and small?
- [ ] Is there appropriate error handling?
- [ ] Is there unnecessary complexity?
- [ ] Are there magic numbers or strings?
- [ ] Is code DRY (Don't Repeat Yourself)?
#### Performance
- [ ] Are there obvious performance issues?
- [ ] Is database access optimized (N+1 queries)?
- [ ] Are expensive operations cached?
- [ ] Is pagination implemented for large datasets?
- [ ] Are there memory leaks?
#### Security
- [ ] Is input validated and sanitized?
- [ ] Are SQL injections prevented?
- [ ] Are XSS attacks prevented?
- [ ] Is authentication/authorization proper?
- [ ] Are secrets properly managed?
- [ ] Is sensitive data logged?
#### Testing
- [ ] Are there adequate unit tests?
- [ ] Do tests cover edge cases?
- [ ] Are integration tests needed?
- [ ] Are tests readable and maintainable?
- [ ] Is test coverage acceptable?
#### Documentation
- [ ] Are complex parts documented?
- [ ] Are public APIs documented?
- [ ] Are README/docs updated if needed?
- [ ] Are breaking changes documented?
### Review Feedback Examples
#### Good Feedback (Specific & Constructive)
```
❌ "This is bad code"
✅ "This function is doing too much. Consider extracting the validation logic into a separate function to improve readability and testability."
❌ "Fix this"
✅ "This could lead to an N+1 query problem. Consider using `select_related('user')` to fetch the user in a single query."
❌ "Use better names"
✅ "The variable name `d` is unclear. Consider renaming to `createdDate` or `dateCreated` to make the intent clearer."
```
#### Praise Good Practices
```
✅ "Great use of early returns to reduce nesting!"
✅ "Nice comprehensive error handling here."
✅ "I like how you extracted this into a reusable hook."
✅ "Excellent test coverage for edge cases!"
```
### Common Code Smells
#### Long Functions/Methods
```typescript
// ❌ Function doing too much
function processOrder(order) {
// 100+ lines of code...
}
// ✅ Break into smaller functions
function processOrder(order) {
validateOrder(order);
calculateTotals(order);
applyDiscounts(order);
processPayment(order);
sendConfirmation(order);
}
```
#### Magic Numbers/Strings
```typescript
// ❌ Magic number
if (user.age >= 18) { ... }
// ✅ Named constant
const MINIMUM_AGE = 18;
if (user.age >= MINIMUM_AGE) { ... }
```
#### Deep Nesting
```typescript
// ❌ Deep nesting
if (user) {
if (user.isActive) {
if (user.hasPermission) {
// do something
}
}
}
// ✅ Early returns
if (!user) return;
if (!user.isActive) return;
if (!user.hasPermission) return;
// do something
```
#### Duplicated Code
```typescript
// ❌ Duplication
function calculateDiscount(user) {
if (user.type === 'premium') {
return user.total * 0.2;
} else if (user.type === 'regular') {
return user.total * 0.1;
}
}
// ✅ Data-driven approach
const DISCOUNT_RATES = {
premium: 0.2,
regular: 0.1,
guest: 0,
};
function calculateDiscount(user) {
const rate = DISCOUNT_RATES[user.type] || 0;
return user.total * rate;
}
```
### Language-Specific Concerns
#### TypeScript/JavaScript
- Type safety (prefer TypeScript)
- Async/await usage
- Error handling in promises
- Memory leaks (event listeners)
- Bundle size implications
#### Python
- PEP 8 compliance
- Type hints usage
- Exception handling
- Generator usage for large datasets
- Context managers for resources
#### Go
- Error handling patterns
- Goroutine leaks
- Defer usage
- Interface design
- Pointer vs value receivers
## Critical Rules
### Always Do
- Be respectful and constructive
- Provide specific examples
- Suggest solutions, not just problems
- Prioritize feedback (critical vs minor)
- Praise good practices
- Ask questions to understand intent
- Consider the full context
- Review tests as thoroughly as code
- Check for security issues
### Never Do
- Never be condescending or rude
- Never nitpick style if linting exists
- Never block on personal preferences
- Never review without understanding context
- Never forget to praise good work
- Never demand perfection
- Never review when angry or rushed
## Knowledge Base
- **Patterns**: Design patterns, anti-patterns
- **Best Practices**: SOLID, DRY, KISS, YAGNI
- **Security**: OWASP Top 10, common vulnerabilities
- **Performance**: Common bottlenecks, optimization
- **Testing**: Test patterns, coverage strategies
## Best Practices Summary
1. **Constructive**: Helpful, not critical
2. **Specific**: Point to exact issues
3. **Prioritized**: Critical to minor
4. **Balanced**: Find positives too
5. **Educational**: Teach, don't just correct
6. **Contextual**: Understand the why
7. **Respectful**: Professional tone
8. **Timely**: Review promptly
9. **Thorough**: Check all aspects
10. **Collaborative**: Discussion, not dictation

253
skills/debugging-wizard/SKILL.md Normal file
View File

@@ -0,0 +1,253 @@
---
name: Debugging Wizard
description: Expert in systematic debugging across all languages and frameworks. Use when debugging issues, troubleshooting errors, investigating bugs, analyzing logs, using debuggers, or when the user mentions debugging, troubleshooting, errors, bugs, or issues.
---
# Debugging Wizard
A specialized skill for systematic debugging and troubleshooting across all programming languages and frameworks.
## Instructions
### Core Workflow
1. **Understand the problem**
- Gather error messages, stack traces, logs
- Identify when the issue started
- Determine reproduction steps
- Understand expected vs actual behavior
2. **Reproduce the issue**
- Create minimal reproducible example
- Document exact steps to reproduce
- Test in different environments
- Isolate variables
3. **Investigate systematically**
- Use appropriate debugging tools
- Add strategic logging/breakpoints
- Test hypotheses methodically
- Eliminate possibilities
4. **Fix and verify**
- Implement fix
- Test thoroughly
- Document the issue and solution
- Add regression tests
### Debugging Strategies
#### The Scientific Method
1. **Observe**: What is happening?
2. **Hypothesize**: Why might this be happening?
3. **Test**: How can we verify the hypothesis?
4. **Analyze**: What did the test reveal?
5. **Iterate**: Repeat until root cause found
#### Binary Search Debugging
- Comment out half the code
- Determine which half has the bug
- Repeat until bug is isolated
#### Rubber Duck Debugging
- Explain the problem out loud (or in writing)
- Often reveals the solution
### Common Debugging Tools
#### TypeScript/JavaScript
```bash
# Node.js debugger
node --inspect app.js
# VS Code debugger (launch.json)
{
"type": "node",
"request": "launch",
"name": "Debug Program",
"program": "${workspaceFolder}/app.ts",
"outFiles": ["${workspaceFolder}/dist/**/*.js"]
}
# Chrome DevTools
# Add 'debugger;' statement in code
debugger;
# Console debugging
console.log('Value:', value);
console.table(arrayOfObjects);
console.trace('Execution path');
```
#### Python
```python
# Built-in debugger
import pdb; pdb.set_trace() # Python < 3.7
breakpoint() # Python >= 3.7
# IPython debugger
from IPdb import set_trace; set_trace()
# Logging
import logging
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger(__name__)
logger.debug(f"Variable value: {var}")
# Print debugging
print(f"DEBUG: {variable}")
import pprint
pprint.pprint(complex_object)
```
#### Go
```go
// Delve debugger
dlv debug main.go
// Print debugging
import "fmt"
fmt.Printf("DEBUG: %+v\n", variable)
// Log debugging
import "log"
log.Printf("Value: %v", value)
```
### Debugging Patterns
#### Stack Trace Analysis
```
Error: Cannot read property 'name' of undefined
at getUserName (app.js:45:18)
at processUser (app.js:32:10)
at main (app.js:15:3)
```
- Start at the top (most recent call)
- Work backwards through the call stack
- Identify the first occurrence in your code
#### Network Debugging
```bash
# cURL with verbose output
curl -v https://api.example.com/users
# Network tab in browser DevTools
# Check: Status code, Headers, Response, Timing
# Proxy tools
# Charles Proxy, Fiddler, mitmproxy
```
#### Database Query Debugging
```sql
-- Add EXPLAIN to understand query execution
EXPLAIN ANALYZE
SELECT * FROM users WHERE email = 'test@example.com';
-- Check slow query log
-- Enable query logging in development
```
### Common Issues and Solutions
#### Race Conditions
```typescript
// Problem: Race condition
let data = null;
fetchData().then(d => data = d);
console.log(data); // null - fetchData not done yet
// Solution: Await the promise
const data = await fetchData();
console.log(data); // Correct value
```
#### Memory Leaks
```typescript
// Problem: Event listener not cleaned up
useEffect(() => {
window.addEventListener('resize', handleResize);
// Missing cleanup!
}, []);
// Solution: Cleanup in effect
useEffect(() => {
window.addEventListener('resize', handleResize);
return () => window.removeEventListener('resize', handleResize);
}, []);
```
#### Off-by-One Errors
```python
# Problem: Missing last item
for i in range(len(items) - 1): # Missing last item!
process(items[i])
# Solution: Correct range
for i in range(len(items)):
process(items[i])
# Better: Iterate directly
for item in items:
process(item)
```
### Debugging Checklist
- [ ] Can you reproduce the issue consistently?
- [ ] Do you have the complete error message/stack trace?
- [ ] Have you checked the logs?
- [ ] Have you tested in isolation?
- [ ] Have you verified inputs/outputs?
- [ ] Have you checked for typos?
- [ ] Have you read the documentation?
- [ ] Have you searched for similar issues?
- [ ] Have you tried the rubber duck method?
- [ ] Have you taken a break and come back fresh?
## Critical Rules
### Always Do
- Reproduce the issue first
- Gather all error messages and logs
- Create minimal reproducible examples
- Test hypotheses systematically
- Document findings
- Add regression tests after fixing
- Commit fixes with clear messages
- Share knowledge with team
### Never Do
- Never guess without testing
- Never make multiple changes at once
- Never skip reproduction steps
- Never assume the problem
- Never ignore warnings
- Never debug in production without backups
- Never commit debug code (console.logs, debugger statements)
## Knowledge Base
- **Tools**: Debuggers, profilers, network analyzers, log aggregators
- **Techniques**: Binary search, rubber duck, scientific method
- **Languages**: TypeScript, Python, Go, Java, etc.
- **Platforms**: Browser DevTools, VS Code, Chrome, Node.js
## Integration with Other Skills
- **Works with**: All development skills
- **Essential for**: Fullstack Guardian, Test Master
## Best Practices Summary
1. **Systematic**: Follow structured approach
2. **Reproducible**: Always reproduce first
3. **Isolated**: Test in isolation
4. **Documented**: Document findings
5. **Tested**: Add regression tests
6. **Tools**: Use appropriate debugging tools
7. **Logs**: Strategic logging
8. **Patience**: Take breaks when stuck
9. **Communication**: Share findings
10. **Learning**: Document for future reference

142
skills/devops-engineer/SKILL.md Normal file
View File

@@ -0,0 +1,142 @@
---
name: DevOps Engineer
description: Automate and optimize software delivery pipelines, manage infrastructure, and ensure operational excellence. Use when working with CI/CD, deployments, infrastructure as code, Docker, Kubernetes, cloud platforms, monitoring, or when the user mentions DevOps, automation, deployment, release management, or infrastructure tasks.
---
# DevOps Engineer
A specialized skill for automating and optimizing the software delivery pipeline, managing infrastructure, and ensuring operational excellence. This skill embodies three distinct personas:
- **Build Engineer (Build Hat)**: Focused on automating the compilation, testing, and packaging of software
- **Release Manager (Deploy Hat)**: Focused on orchestrating and automating the deployment of applications across various environments
- **Site Reliability Engineer (Ops Hat)**: Focused on ensuring the availability, performance, and scalability of systems in production
## Instructions
### Core Workflow
1. **Start by gathering context**
- Ask for the application or feature to be deployed, or the operational task to be performed
- Identify which persona(s) are most relevant to the task
2. **Follow a systematic approach**
- Analyze the current state of the system/infrastructure
- Propose automation or infrastructure changes
- Execute commands using Bash tool
- Verify the outcome
3. **Use appropriate persona indicators**
- Clearly indicate which persona is speaking by using `[Build Hat]`, `[Deploy Hat]`, or `[Ops Hat]` at the beginning of questions or statements
- This helps provide context-specific guidance
4. **Execute and verify**
- Use Bash extensively for build, deployment, and infrastructure management tasks
- Use Read for configuration files, logs, and infrastructure definitions
- Always verify outcomes after making changes
5. **Generate comprehensive summaries**
- At the end of each task, create a markdown summary document
- Name it `{task_name}_devops_summary.md`
- Include these exact sections:
- **Task Description**: What was requested
- **Actions Taken**: Step-by-step actions performed
- **Outcome**: Results of the actions
- **Verification Steps**: How the outcome was verified
- **Next Steps/Recommendations**: Suggestions for follow-up or improvements
## Key Considerations
### Build Hat Focus
- Automate compilation, testing, and packaging
- Optimize build times and resource usage
- Ensure reproducible builds
- Integrate with version control systems
### Deploy Hat Focus
- Orchestrate deployments across environments (dev, staging, production)
- Implement blue-green, canary, or rolling deployment strategies
- Manage configuration for different environments
- Coordinate with teams on release schedules
### Ops Hat Focus
- Monitor system health, performance, and availability
- Implement alerting and incident response procedures
- Ensure scalability and reliability
- Plan for disaster recovery and business continuity
## Critical Rules
### Always Do
- Ask for explicit confirmation before performing critical production deployments or infrastructure changes
- Consider security, scalability, and disaster recovery in all strategies
- Use infrastructure as code principles where applicable
- Document all changes and procedures
- Verify deployments and changes after execution
### Never Do
- Never perform critical production deployments without explicit confirmation
- Never accept vague deployment or operational requirements without clarification
- Never skip security considerations
- Never forget to consider rollback strategies
## Knowledge Base
- **CI/CD**: Expert in designing and implementing continuous integration and continuous delivery pipelines
- **Infrastructure as Code (IaC)**: Knowledgeable in Terraform, CloudFormation, and similar tools for managing infrastructure through code
- **Cloud Platforms**: Understanding of AWS, GCP, Azure concepts and services
- **Containerization**: Familiar with Docker and Kubernetes for application packaging and orchestration
- **Observability**: Best practices for monitoring, logging, and alerting (Prometheus, Grafana, ELK stack, etc.)
## Integration with Other Skills
- **Receives from**: Fullstack Guardian (implemented features), Test Master (tested features)
- **Hands off to**: Operations team, monitoring systems
- **Works with**: All development personas for deployment coordination
## Examples
### Example 1: CI/CD Pipeline Setup
```
[Build Hat] Let's set up a CI/CD pipeline for your application. First, I need to understand:
1. What is your source control system? (Git, GitHub, GitLab, etc.)
2. What is your build tool? (npm, gradle, maven, etc.)
3. What environments do you need? (dev, staging, production)
4. What is your deployment target? (containers, VMs, serverless, etc.)
[Deploy Hat] For deployment strategy, I recommend starting with:
- Automated deployments to dev on every commit
- Manual approval for staging deployments
- Blue-green deployment for production with automated rollback
[Ops Hat] We should also set up:
- Health checks for all services
- Automated alerts for failures
- Log aggregation for debugging
```
### Example 2: Docker Deployment
```
[Build Hat] I'll create a Dockerfile for your application and set up the build process.
[Deploy Hat] For deployment, I'll:
1. Build the Docker image with proper tagging
2. Push to your container registry
3. Update the deployment configuration
4. Roll out the new version with zero downtime
[Ops Hat] After deployment, I'll verify:
- Container health checks are passing
- Resource usage is within expected limits
- Application logs show no errors
- All endpoints are responding correctly
```
## Best Practices
1. **Automation First**: Automate repetitive tasks to reduce human error
2. **Infrastructure as Code**: Manage all infrastructure through version-controlled code
3. **Immutable Infrastructure**: Build new instead of modifying existing infrastructure
4. **Security by Default**: Implement security at every layer
5. **Monitor Everything**: Comprehensive observability is critical
6. **Plan for Failure**: Design systems to be resilient and self-healing
7. **Document Procedures**: Maintain runbooks for common operations and incidents

556
skills/django-expert/SKILL.md Normal file
View File

@@ -0,0 +1,556 @@
---
name: Django Expert
description: Expert in Django web framework for building robust Python applications. Use when working with Django, Django REST Framework, Django ORM, models, views, serializers, middleware, or when the user mentions Django, Python web development, or DRF.
---
# Django Expert
A specialized skill for building production-ready web applications with Django and Django REST Framework. This skill covers MVC architecture, ORM, REST APIs, authentication, and Django best practices.
## Instructions
### Core Workflow
1. **Understand requirements**
- Identify if this is a traditional Django app or REST API (DRF)
- Determine database requirements
- Understand authentication needs
- Identify third-party integrations
2. **Project structure**
- Follow Django app-based architecture
- Separate business logic from views
- Use proper settings management (dev/prod)
- Implement custom user models if needed
3. **Implement features**
- Create models with proper relationships
- Implement views/viewsets following best practices
- Create serializers with proper validation (DRF)
- Add authentication and permissions
- Implement middleware and signals where appropriate
4. **Testing and documentation**
- Write tests using Django's test framework
- Document APIs with drf-spectacular
- Configure for production deployment
### Django Project Structure
```
myproject/
├── manage.py
├── myproject/ # Project root
│ ├── __init__.py
│ ├── settings/ # Split settings
│ │ ├── __init__.py
│ │ ├── base.py
│ │ ├── development.py
│ │ └── production.py
│ ├── urls.py
│ └── wsgi.py
├── apps/ # All Django apps
│ ├── users/
│ │ ├── models.py
│ │ ├── views.py
│ │ ├── serializers.py # DRF
│ │ ├── urls.py
│ │ ├── admin.py
│ │ ├── tests/
│ │ └── managers.py
│ └── products/
└── requirements/
├── base.txt
├── development.txt
└── production.txt
```
### Model Best Practices
```python
from django.db import models
from django.core.validators import MinValueValidator, MaxValueValidator
from django.contrib.auth.models import AbstractUser
# Custom User Model
class User(AbstractUser):
"""Custom user model with additional fields"""
email = models.EmailField(unique=True)
bio = models.TextField(max_length=500, blank=True)
birth_date = models.DateField(null=True, blank=True)
avatar = models.ImageField(upload_to='avatars/', null=True, blank=True)
USERNAME_FIELD = 'email'
REQUIRED_FIELDS = ['username']
class Meta:
ordering = ['-date_joined']
indexes = [
models.Index(fields=['email']),
]
def __str__(self):
return self.email
# Model with relationships
class Product(models.Model):
"""Product model with proper field types and validation"""
name = models.CharField(max_length=200, db_index=True)
slug = models.SlugField(max_length=200, unique=True)
description = models.TextField()
price = models.DecimalField(
max_digits=10,
decimal_places=2,
validators=[MinValueValidator(0)]
)
stock = models.PositiveIntegerField(default=0)
available = models.BooleanField(default=True)
created_by = models.ForeignKey(
User,
on_delete=models.CASCADE,
related_name='products'
)
category = models.ForeignKey(
'Category',
on_delete=models.SET_NULL,
null=True,
related_name='products'
)
tags = models.ManyToManyField('Tag', blank=True)
created_at = models.DateTimeField(auto_now_add=True)
updated_at = models.DateTimeField(auto_now=True)
class Meta:
ordering = ['-created_at']
indexes = [
models.Index(fields=['slug']),
models.Index(fields=['-created_at']),
]
def __str__(self):
return self.name
def get_absolute_url(self):
from django.urls import reverse
return reverse('product-detail', kwargs={'slug': self.slug})
def is_in_stock(self):
return self.available and self.stock > 0
# Custom Manager
class PublishedManager(models.Manager):
def get_queryset(self):
return super().get_queryset().filter(status='published')
class Post(models.Model):
STATUS_CHOICES = [
('draft', 'Draft'),
('published', 'Published'),
]
title = models.CharField(max_length=200)
content = models.TextField()
status = models.CharField(max_length=10, choices=STATUS_CHOICES, default='draft')
objects = models.Manager() # Default manager
published = PublishedManager() # Custom manager
```
### Django REST Framework
```python
# serializers.py
from rest_framework import serializers
from .models import Product, Category
class CategorySerializer(serializers.ModelSerializer):
class Meta:
model = Category
fields = ['id', 'name', 'slug']
class ProductSerializer(serializers.ModelSerializer):
category = CategorySerializer(read_only=True)
category_id = serializers.PrimaryKeyRelatedField(
queryset=Category.objects.all(),
source='category',
write_only=True
)
created_by_email = serializers.EmailField(source='created_by.email', read_only=True)
class Meta:
model = Product
fields = [
'id', 'name', 'slug', 'description', 'price', 'stock',
'available', 'category', 'category_id', 'created_by_email',
'created_at', 'updated_at'
]
read_only_fields = ['slug', 'created_at', 'updated_at']
def validate_price(self, value):
if value < 0:
raise serializers.ValidationError("Price cannot be negative")
return value
def validate(self, data):
# Cross-field validation
if data.get('available') and data.get('stock', 0) == 0:
raise serializers.ValidationError(
"Product cannot be available with zero stock"
)
return data
# views.py (ViewSets)
from rest_framework import viewsets, filters, status
from rest_framework.decorators import action
from rest_framework.response import Response
from rest_framework.permissions import IsAuthenticated, IsAuthenticatedOrReadOnly
from django_filters.rest_framework import DjangoFilterBackend
class ProductViewSet(viewsets.ModelViewSet):
"""
ViewSet for managing products.
list: Get all products
retrieve: Get a single product
create: Create a new product
update: Update a product
destroy: Delete a product
"""
queryset = Product.objects.select_related('category', 'created_by').all()
serializer_class = ProductSerializer
permission_classes = [IsAuthenticatedOrReadOnly]
filter_backends = [DjangoFilterBackend, filters.SearchFilter, filters.OrderingFilter]
filterset_fields = ['category', 'available']
search_fields = ['name', 'description']
ordering_fields = ['price', 'created_at']
lookup_field = 'slug'
def perform_create(self, serializer):
serializer.save(created_by=self.request.user)
@action(detail=True, methods=['post'])
def purchase(self, request, slug=None):
"""Custom action to purchase a product"""
product = self.get_object()
quantity = request.data.get('quantity', 1)
if not product.is_in_stock():
return Response(
{'error': 'Product out of stock'},
status=status.HTTP_400_BAD_REQUEST
)
if product.stock < quantity:
return Response(
{'error': f'Only {product.stock} items available'},
status=status.HTTP_400_BAD_REQUEST
)
# Process purchase logic here
product.stock -= quantity
product.save()
return Response({'message': 'Purchase successful'})
@action(detail=False, methods=['get'])
def low_stock(self, request):
"""Get products with low stock"""
low_stock_products = self.queryset.filter(stock__lt=10, available=True)
serializer = self.get_serializer(low_stock_products, many=True)
return Response(serializer.data)
# urls.py
from rest_framework.routers import DefaultRouter
from .views import ProductViewSet
router = DefaultRouter()
router.register(r'products', ProductViewSet, basename='product')
urlpatterns = router.urls
```
### Authentication & Permissions
```python
# Custom Permission
from rest_framework import permissions
class IsOwnerOrReadOnly(permissions.BasePermission):
"""
Custom permission to only allow owners of an object to edit it.
"""
def has_object_permission(self, request, view, obj):
# Read permissions are allowed to any request
if request.method in permissions.SAFE_METHODS:
return True
# Write permissions are only allowed to the owner
return obj.created_by == request.user
# JWT Authentication (using Simple JWT)
# settings.py
from datetime import timedelta
REST_FRAMEWORK = {
'DEFAULT_AUTHENTICATION_CLASSES': [
'rest_framework_simplejwt.authentication.JWTAuthentication',
],
'DEFAULT_PERMISSION_CLASSES': [
'rest_framework.permissions.IsAuthenticatedOrReadOnly',
],
'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
'PAGE_SIZE': 10,
'DEFAULT_FILTER_BACKENDS': [
'django_filters.rest_framework.DjangoFilterBackend',
],
}
SIMPLE_JWT = {
'ACCESS_TOKEN_LIFETIME': timedelta(minutes=60),
'REFRESH_TOKEN_LIFETIME': timedelta(days=1),
'ROTATE_REFRESH_TOKENS': True,
'BLACKLIST_AFTER_ROTATION': True,
}
# views.py - Auth endpoints
from rest_framework_simplejwt.views import TokenObtainPairView
from rest_framework_simplejwt.serializers import TokenObtainPairSerializer
class CustomTokenObtainPairSerializer(TokenObtainPairSerializer):
@classmethod
def get_token(cls, user):
token = super().get_token(user)
# Add custom claims
token['email'] = user.email
token['is_staff'] = user.is_staff
return token
class CustomTokenObtainPairView(TokenObtainPairView):
serializer_class = CustomTokenObtainPairSerializer
```
### Middleware & Signals
```python
# middleware.py
import logging
logger = logging.getLogger(__name__)
class RequestLoggingMiddleware:
def __init__(self, get_response):
self.get_response = get_response
def __call__(self, request):
# Log request
logger.info(f"{request.method} {request.path}")
response = self.get_response(request)
# Log response
logger.info(f"{request.method} {request.path} - {response.status_code}")
return response
# signals.py
from django.db.models.signals import post_save, pre_delete
from django.dispatch import receiver
from .models import Product
@receiver(post_save, sender=Product)
def product_saved(sender, instance, created, **kwargs):
if created:
# Send notification or perform action when product is created
logger.info(f"New product created: {instance.name}")
else:
# Product was updated
logger.info(f"Product updated: {instance.name}")
@receiver(pre_delete, sender=Product)
def product_deleted(sender, instance, **kwargs):
# Cleanup before deletion
if instance.avatar:
instance.avatar.delete(save=False)
```
### Testing
```python
# tests/test_models.py
from django.test import TestCase
from django.contrib.auth import get_user_model
from apps.products.models import Product, Category
User = get_user_model()
class ProductModelTest(TestCase):
def setUp(self):
self.user = User.objects.create_user(
email='test@example.com',
username='testuser',
password='testpass123'
)
self.category = Category.objects.create(name='Electronics', slug='electronics')
self.product = Product.objects.create(
name='Laptop',
slug='laptop',
description='A great laptop',
price=999.99,
stock=10,
created_by=self.user,
category=self.category
)
def test_product_creation(self):
self.assertEqual(self.product.name, 'Laptop')
self.assertEqual(str(self.product), 'Laptop')
def test_is_in_stock(self):
self.assertTrue(self.product.is_in_stock())
self.product.stock = 0
self.assertFalse(self.product.is_in_stock())
# tests/test_api.py
from rest_framework.test import APITestCase, APIClient
from rest_framework import status
from django.urls import reverse
class ProductAPITest(APITestCase):
def setUp(self):
self.client = APIClient()
self.user = User.objects.create_user(
email='test@example.com',
username='testuser',
password='testpass123'
)
self.category = Category.objects.create(name='Electronics', slug='electronics')
def test_create_product_authenticated(self):
self.client.force_authenticate(user=self.user)
url = reverse('product-list')
data = {
'name': 'New Product',
'description': 'Product description',
'price': 99.99,
'stock': 50,
'category_id': self.category.id
}
response = self.client.post(url, data)
self.assertEqual(response.status_code, status.HTTP_201_CREATED)
self.assertEqual(Product.objects.count(), 1)
self.assertEqual(Product.objects.first().name, 'New Product')
def test_list_products(self):
Product.objects.create(
name='Product 1',
slug='product-1',
description='Description',
price=50.00,
stock=10,
created_by=self.user,
category=self.category
)
url = reverse('product-list')
response = self.client.get(url)
self.assertEqual(response.status_code, status.HTTP_200_OK)
self.assertEqual(len(response.data['results']), 1)
```
### Performance Optimization
```python
# Use select_related and prefetch_related
# Bad
products = Product.objects.all()
for product in products:
print(product.category.name) # N+1 query problem
# Good
products = Product.objects.select_related('category', 'created_by').all()
for product in products:
print(product.category.name) # Single query
# For many-to-many
products = Product.objects.prefetch_related('tags').all()
# Database indexes in models
class Meta:
indexes = [
models.Index(fields=['slug']),
models.Index(fields=['-created_at']),
models.Index(fields=['category', '-created_at']),
]
# Caching with Redis
from django.core.cache import cache
from django.views.decorators.cache import cache_page
@cache_page(60 * 15) # Cache for 15 minutes
def product_list(request):
products = Product.objects.all()
return render(request, 'products/list.html', {'products': products})
# Cache querysets
def get_products():
products = cache.get('all_products')
if products is None:
products = list(Product.objects.select_related('category').all())
cache.set('all_products', products, 60 * 15)
return products
```
## Critical Rules
### Always Do
- Use environment variables for sensitive data
- Implement proper model validation
- Use select_related/prefetch_related to avoid N+1 queries
- Write tests for models, views, and APIs
- Use database indexes for frequently queried fields
- Implement proper authentication and permissions
- Document APIs with drf-spectacular
- Use Django's ORM efficiently
- Handle errors gracefully with proper HTTP status codes
### Never Do
- Never store passwords in plain text
- Never expose Django secret key
- Never use raw SQL unless absolutely necessary
- Never skip migrations
- Never commit sensitive data
- Never trust user input without validation
- Never use DEBUG=True in production
- Never ignore database optimization
## Knowledge Base
- **Django Core**: Models, Views, Templates, Forms, Admin
- **Django REST Framework**: Serializers, ViewSets, Permissions, Authentication
- **ORM**: QuerySets, Managers, Aggregation, F/Q expressions
- **Authentication**: JWT, Session, OAuth
- **Testing**: Django TestCase, APITestCase
- **Performance**: Query optimization, Caching, Database indexing
- **Security**: CSRF, XSS, SQL injection prevention
- **Deployment**: WSGI, Gunicorn, Nginx, Docker
## Integration with Other Skills
- **Works with**: Fullstack Guardian, Test Master, DevOps Engineer
- **Complements**: FastAPI Expert (alternative Python framework), Code Documenter
## Best Practices Summary
1. **Models**: Use proper field types, validators, indexes
2. **Serializers**: Validate thoroughly, use nested serializers wisely
3. **ViewSets**: Use appropriate mixins, implement custom actions
4. **Permissions**: Layer permissions appropriately
5. **Testing**: High test coverage for business logic
6. **Performance**: Query optimization, caching, pagination
7. **Security**: HTTPS, CSRF tokens, proper authentication
8. **Documentation**: DRF self-documenting + drf-spectacular

783
skills/fastapi-expert/SKILL.md Normal file
View File

@@ -0,0 +1,783 @@
---
name: FastAPI Expert
description: Expert in FastAPI framework for building high-performance async Python APIs. Use when working with FastAPI, async Python, Pydantic, type hints, automatic API documentation, WebSockets, or when the user mentions FastAPI, async APIs, or modern Python web development.
---
# FastAPI Expert
A specialized skill for building high-performance, production-ready APIs with FastAPI. This skill covers async programming, Pydantic models, dependency injection, authentication, and FastAPI best practices.
## Instructions
### Core Workflow
1. **Understand requirements**
- Identify API type (REST, WebSockets, GraphQL)
- Determine database needs (async SQLAlchemy, Tortoise-ORM, MongoDB)
- Understand authentication requirements (OAuth2, JWT)
- Identify performance requirements
2. **Project structure**
- Organize with proper router structure
- Implement dependency injection
- Use Pydantic models for validation
- Configure CORS and middleware
3. **Implement features**
- Create path operations with proper type hints
- Implement Pydantic schemas for validation
- Add authentication and authorization
- Use background tasks for async operations
- Implement WebSockets if needed
4. **Testing and documentation**
- Write tests using pytest and httpx
- Leverage automatic Swagger/OpenAPI docs
- Configure for production deployment
### FastAPI Project Structure
```
myapp/
├── main.py # Application entry point
├── core/
│ ├── config.py # Settings with Pydantic
│ ├── security.py # Auth utilities
│ └── dependencies.py # Shared dependencies
├── api/
│ ├── v1/
│ │ ├── __init__.py
│ │ ├── api.py # Main API router
│ │ └── endpoints/
│ │ ├── users.py
│ │ ├── auth.py
│ │ └── items.py
├── models/ # SQLAlchemy models
│ ├── __init__.py
│ ├── user.py
│ └── item.py
├── schemas/ # Pydantic schemas
│ ├── __init__.py
│ ├── user.py
│ └── item.py
├── crud/ # Database operations
│ ├── __init__.py
│ ├── user.py
│ └── item.py
├── db/
│ ├── base.py # Database session
│ └── init_db.py # Initial data
└── tests/
├── conftest.py
├── test_users.py
└── test_auth.py
```
### Configuration with Pydantic Settings
```python
# core/config.py
from pydantic_settings import BaseSettings
from typing import Optional
class Settings(BaseSettings):
# App
PROJECT_NAME: str = "My FastAPI App"
VERSION: str = "1.0.0"
API_V1_STR: str = "/api/v1"
# Security
SECRET_KEY: str
ALGORITHM: str = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES: int = 30
# Database
DATABASE_URL: str
# CORS
BACKEND_CORS_ORIGINS: list[str] = ["http://localhost:3000"]
# Redis
REDIS_HOST: str = "localhost"
REDIS_PORT: int = 6379
class Config:
env_file = ".env"
case_sensitive = True
settings = Settings()
```
### Pydantic Schemas
```python
# schemas/user.py
from pydantic import BaseModel, EmailStr, Field, validator
from typing import Optional
from datetime import datetime
class UserBase(BaseModel):
email: EmailStr
username: str = Field(..., min_length=3, max_length=50)
full_name: Optional[str] = Field(None, max_length=100)
is_active: bool = True
class UserCreate(UserBase):
password: str = Field(..., min_length=8)
@validator('password')
def password_strength(cls, v):
if not any(char.isdigit() for char in v):
raise ValueError('Password must contain at least one digit')
if not any(char.isupper() for char in v):
raise ValueError('Password must contain at least one uppercase letter')
return v
class UserUpdate(BaseModel):
email: Optional[EmailStr] = None
username: Optional[str] = Field(None, min_length=3, max_length=50)
full_name: Optional[str] = Field(None, max_length=100)
password: Optional[str] = Field(None, min_length=8)
class UserInDBBase(UserBase):
id: int
created_at: datetime
updated_at: datetime
class Config:
from_attributes = True # For SQLAlchemy models
class User(UserInDBBase):
"""User response model (excludes password)"""
pass
class UserInDB(UserInDBBase):
"""User model with hashed password"""
hashed_password: str
```
### Database Models (SQLAlchemy)
```python
# models/user.py
from sqlalchemy import Column, Integer, String, Boolean, DateTime
from sqlalchemy.sql import func
from db.base import Base
class User(Base):
__tablename__ = "users"
id = Column(Integer, primary_key=True, index=True)
email = Column(String, unique=True, index=True, nullable=False)
username = Column(String, unique=True, index=True, nullable=False)
full_name = Column(String)
hashed_password = Column(String, nullable=False)
is_active = Column(Boolean, default=True)
is_superuser = Column(Boolean, default=False)
created_at = Column(DateTime(timezone=True), server_default=func.now())
updated_at = Column(DateTime(timezone=True), onupdate=func.now())
# db/base.py
from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
from sqlalchemy.orm import sessionmaker, declarative_base
from core.config import settings
engine = create_async_engine(settings.DATABASE_URL, echo=True)
AsyncSessionLocal = sessionmaker(
engine, class_=AsyncSession, expire_on_commit=False
)
Base = declarative_base()
# Dependency
async def get_db():
async with AsyncSessionLocal() as session:
try:
yield session
await session.commit()
except Exception:
await session.rollback()
raise
finally:
await session.close()
```
### CRUD Operations
```python
# crud/user.py
from sqlalchemy.ext.asyncio import AsyncSession
from sqlalchemy import select
from sqlalchemy.exc import IntegrityError
from models.user import User
from schemas.user import UserCreate, UserUpdate
from core.security import get_password_hash
from fastapi import HTTPException, status
async def get_user(db: AsyncSession, user_id: int) -> User | None:
result = await db.execute(select(User).where(User.id == user_id))
return result.scalar_one_or_none()
async def get_user_by_email(db: AsyncSession, email: str) -> User | None:
result = await db.execute(select(User).where(User.email == email))
return result.scalar_one_or_none()
async def get_users(
db: AsyncSession, skip: int = 0, limit: int = 100
) -> list[User]:
result = await db.execute(select(User).offset(skip).limit(limit))
return result.scalars().all()
async def create_user(db: AsyncSession, user: UserCreate) -> User:
hashed_password = get_password_hash(user.password)
db_user = User(
email=user.email,
username=user.username,
full_name=user.full_name,
hashed_password=hashed_password,
is_active=user.is_active
)
try:
db.add(db_user)
await db.commit()
await db.refresh(db_user)
return db_user
except IntegrityError:
await db.rollback()
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail="User with this email or username already exists"
)
async def update_user(
db: AsyncSession, user_id: int, user_update: UserUpdate
) -> User:
db_user = await get_user(db, user_id)
if not db_user:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail="User not found"
)
update_data = user_update.model_dump(exclude_unset=True)
if "password" in update_data:
update_data["hashed_password"] = get_password_hash(update_data.pop("password"))
for field, value in update_data.items():
setattr(db_user, field, value)
await db.commit()
await db.refresh(db_user)
return db_user
async def delete_user(db: AsyncSession, user_id: int) -> bool:
db_user = await get_user(db, user_id)
if not db_user:
return False
await db.delete(db_user)
await db.commit()
return True
```
### API Endpoints with Proper Type Hints
```python
# api/v1/endpoints/users.py
from fastapi import APIRouter, Depends, HTTPException, status, Query
from sqlalchemy.ext.asyncio import AsyncSession
from typing import Annotated
from db.base import get_db
from schemas.user import User, UserCreate, UserUpdate
from crud import user as crud_user
from core.dependencies import get_current_active_user
router = APIRouter()
@router.post("/", response_model=User, status_code=status.HTTP_201_CREATED)
async def create_user(
*,
db: Annotated[AsyncSession, Depends(get_db)],
user_in: UserCreate,
) -> User:
"""
Create new user.
- **email**: valid email address (unique)
- **username**: 3-50 characters (unique)
- **password**: minimum 8 characters with uppercase, lowercase, and number
- **full_name**: optional full name
"""
# Check if user exists
existing_user = await crud_user.get_user_by_email(db, email=user_in.email)
if existing_user:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail="User with this email already exists",
)
user = await crud_user.create_user(db=db, user=user_in)
return user
@router.get("/", response_model=list[User])
async def read_users(
db: Annotated[AsyncSession, Depends(get_db)],
skip: int = Query(0, ge=0),
limit: int = Query(100, ge=1, le=100),
current_user: Annotated[User, Depends(get_current_active_user)] = None,
) -> list[User]:
"""
Retrieve users with pagination.
- **skip**: number of records to skip (default: 0)
- **limit**: maximum number of records to return (default: 100, max: 100)
"""
users = await crud_user.get_users(db, skip=skip, limit=limit)
return users
@router.get("/{user_id}", response_model=User)
async def read_user(
user_id: int,
db: Annotated[AsyncSession, Depends(get_db)],
) -> User:
"""
Get user by ID.
"""
db_user = await crud_user.get_user(db, user_id=user_id)
if db_user is None:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail="User not found"
)
return db_user
@router.patch("/{user_id}", response_model=User)
async def update_user(
user_id: int,
user_in: UserUpdate,
db: Annotated[AsyncSession, Depends(get_db)],
current_user: Annotated[User, Depends(get_current_active_user)] = None,
) -> User:
"""
Update user.
"""
# Check authorization (users can only update themselves unless admin)
if current_user.id != user_id and not current_user.is_superuser:
raise HTTPException(
status_code=status.HTTP_403_FORBIDDEN,
detail="Not enough permissions"
)
db_user = await crud_user.update_user(db, user_id=user_id, user_update=user_in)
return db_user
@router.delete("/{user_id}", status_code=status.HTTP_204_NO_CONTENT)
async def delete_user(
user_id: int,
db: Annotated[AsyncSession, Depends(get_db)],
current_user: Annotated[User, Depends(get_current_active_user)] = None,
) -> None:
"""
Delete user.
"""
if not current_user.is_superuser:
raise HTTPException(
status_code=status.HTTP_403_FORBIDDEN,
detail="Not enough permissions"
)
success = await crud_user.delete_user(db, user_id=user_id)
if not success:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail="User not found"
)
```
### Authentication with JWT
```python
# core/security.py
from datetime import datetime, timedelta
from typing import Optional
from jose import JWTError, jwt
from passlib.context import CryptContext
from core.config import settings
pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
def verify_password(plain_password: str, hashed_password: str) -> bool:
return pwd_context.verify(plain_password, hashed_password)
def get_password_hash(password: str) -> str:
return pwd_context.hash(password)
def create_access_token(data: dict, expires_delta: Optional[timedelta] = None) -> str:
to_encode = data.copy()
if expires_delta:
expire = datetime.utcnow() + expires_delta
else:
expire = datetime.utcnow() + timedelta(minutes=15)
to_encode.update({"exp": expire})
encoded_jwt = jwt.encode(to_encode, settings.SECRET_KEY, algorithm=settings.ALGORITHM)
return encoded_jwt
# core/dependencies.py
from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer
from jose import JWTError, jwt
from sqlalchemy.ext.asyncio import AsyncSession
from core.config import settings
from core.security import verify_password
from db.base import get_db
from crud import user as crud_user
from schemas.user import User
oauth2_scheme = OAuth2PasswordBearer(tokenUrl=f"{settings.API_V1_STR}/auth/login")
async def get_current_user(
db: AsyncSession = Depends(get_db),
token: str = Depends(oauth2_scheme)
) -> User:
credentials_exception = HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Could not validate credentials",
headers={"WWW-Authenticate": "Bearer"},
)
try:
payload = jwt.decode(token, settings.SECRET_KEY, algorithms=[settings.ALGORITHM])
user_id: int = payload.get("sub")
if user_id is None:
raise credentials_exception
except JWTError:
raise credentials_exception
user = await crud_user.get_user(db, user_id=user_id)
if user is None:
raise credentials_exception
return user
async def get_current_active_user(
current_user: User = Depends(get_current_user)
) -> User:
if not current_user.is_active:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail="Inactive user"
)
return current_user
# api/v1/endpoints/auth.py
from fastapi import APIRouter, Depends, HTTPException, status
from fastapi.security import OAuth2PasswordRequestForm
from sqlalchemy.ext.asyncio import AsyncSession
from datetime import timedelta
from db.base import get_db
from core.config import settings
from core.security import create_access_token, verify_password
from crud import user as crud_user
from schemas.user import User
router = APIRouter()
@router.post("/login")
async def login(
db: AsyncSession = Depends(get_db),
form_data: OAuth2PasswordRequestForm = Depends()
):
"""
OAuth2 compatible token login.
"""
user = await crud_user.get_user_by_email(db, email=form_data.username)
if not user or not verify_password(form_data.password, user.hashed_password):
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Incorrect email or password",
headers={"WWW-Authenticate": "Bearer"},
)
if not user.is_active:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail="Inactive user"
)
access_token_expires = timedelta(minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES)
access_token = create_access_token(
data={"sub": str(user.id)}, expires_delta=access_token_expires
)
return {
"access_token": access_token,
"token_type": "bearer",
"user": User.model_validate(user)
}
@router.get("/me", response_model=User)
async def read_users_me(
current_user: User = Depends(get_current_active_user)
):
"""
Get current user.
"""
return current_user
```
### Background Tasks
```python
from fastapi import BackgroundTasks
from typing import Annotated
def send_email(email: str, message: str):
"""Simulated email sending"""
print(f"Sending email to {email}: {message}")
# Actual email sending logic here
@router.post("/send-notification/")
async def send_notification(
email: str,
background_tasks: BackgroundTasks
):
background_tasks.add_task(send_email, email, "Welcome to our service!")
return {"message": "Notification sent in the background"}
```
### WebSocket Support
```python
from fastapi import WebSocket, WebSocketDisconnect
class ConnectionManager:
def __init__(self):
self.active_connections: list[WebSocket] = []
async def connect(self, websocket: WebSocket):
await websocket.accept()
self.active_connections.append(websocket)
def disconnect(self, websocket: WebSocket):
self.active_connections.remove(websocket)
async def broadcast(self, message: str):
for connection in self.active_connections:
await connection.send_text(message)
manager = ConnectionManager()
@router.websocket("/ws/{client_id}")
async def websocket_endpoint(websocket: WebSocket, client_id: int):
await manager.connect(websocket)
try:
while True:
data = await websocket.receive_text()
await manager.broadcast(f"Client #{client_id} says: {data}")
except WebSocketDisconnect:
manager.disconnect(websocket)
await manager.broadcast(f"Client #{client_id} left the chat")
```
### Main Application Setup
```python
# main.py
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from contextlib import asynccontextmanager
from core.config import settings
from api.v1.api import api_router
from db.base import engine, Base
@asynccontextmanager
async def lifespan(app: FastAPI):
# Startup
async with engine.begin() as conn:
await conn.run_sync(Base.metadata.create_all)
yield
# Shutdown
await engine.dispose()
app = FastAPI(
title=settings.PROJECT_NAME,
version=settings.VERSION,
openapi_url=f"{settings.API_V1_STR}/openapi.json",
lifespan=lifespan
)
# CORS
app.add_middleware(
CORSMiddleware,
allow_origins=settings.BACKEND_CORS_ORIGINS,
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
app.include_router(api_router, prefix=settings.API_V1_STR)
@app.get("/")
async def root():
return {"message": "Welcome to FastAPI"}
@app.get("/health")
async def health_check():
return {"status": "healthy"}
```
### Testing
```python
# tests/conftest.py
import pytest
import pytest_asyncio
from httpx import AsyncClient
from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
from sqlalchemy.orm import sessionmaker
from main import app
from db.base import Base, get_db
from core.config import settings
TEST_DATABASE_URL = "sqlite+aiosqlite:///:memory:"
@pytest_asyncio.fixture
async def db_session():
engine = create_async_engine(TEST_DATABASE_URL, echo=True)
async_session = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
async with engine.begin() as conn:
await conn.run_sync(Base.metadata.create_all)
async with async_session() as session:
yield session
async with engine.begin() as conn:
await conn.run_sync(Base.metadata.drop_all)
await engine.dispose()
@pytest_asyncio.fixture
async def client(db_session):
async def override_get_db():
yield db_session
app.dependency_overrides[get_db] = override_get_db
async with AsyncClient(app=app, base_url="http://test") as ac:
yield ac
app.dependency_overrides.clear()
# tests/test_users.py
import pytest
from httpx import AsyncClient
@pytest.mark.asyncio
async def test_create_user(client: AsyncClient):
response = await client.post(
"/api/v1/users/",
json={
"email": "test@example.com",
"username": "testuser",
"password": "Test123456",
"full_name": "Test User"
}
)
assert response.status_code == 201
data = response.json()
assert data["email"] == "test@example.com"
assert data["username"] == "testuser"
assert "id" in data
assert "hashed_password" not in data
@pytest.mark.asyncio
async def test_read_users(client: AsyncClient):
# Create a user first
await client.post(
"/api/v1/users/",
json={
"email": "test@example.com",
"username": "testuser",
"password": "Test123456"
}
)
# Login to get token
response = await client.post(
"/api/v1/auth/login",
data={"username": "test@example.com", "password": "Test123456"}
)
token = response.json()["access_token"]
# Get users
response = await client.get(
"/api/v1/users/",
headers={"Authorization": f"Bearer {token}"}
)
assert response.status_code == 200
assert len(response.json()) > 0
```
## Critical Rules
### Always Do
- Use type hints everywhere (FastAPI requires them)
- Leverage Pydantic for validation and serialization
- Use async/await for all I/O operations
- Implement proper dependency injection
- Use background tasks for long-running operations
- Document all endpoints (FastAPI auto-generates OpenAPI)
- Handle errors with proper HTTP status codes
- Use environment variables for configuration
- Implement proper authentication and authorization
### Never Do
- Never use synchronous database operations
- Never skip type hints (FastAPI won't work properly)
- Never store passwords in plain text
- Never expose sensitive data in responses
- Never ignore Pydantic validation errors
- Never mix sync and async code improperly
- Never hardcode configuration values
- Never skip error handling
## Knowledge Base
- **FastAPI Core**: Path operations, dependencies, middleware, background tasks
- **Async Python**: asyncio, async/await, async database drivers
- **Pydantic**: Models, validation, serialization, settings management
- **SQLAlchemy**: Async ORM, relationships, migrations with Alembic
- **Authentication**: OAuth2, JWT, password hashing
- **Testing**: pytest, pytest-asyncio, httpx
- **Performance**: Async operations, caching, connection pooling
- **Documentation**: Automatic OpenAPI/Swagger generation
## Integration with Other Skills
- **Works with**: Fullstack Guardian, Test Master, DevOps Engineer
- **Complements**: Django Expert (alternative Python framework), Code Documenter
## Best Practices Summary
1. **Type Hints**: Essential for FastAPI functionality
2. **Async Everything**: Use async for I/O operations
3. **Pydantic Models**: Validate all input/output
4. **Dependency Injection**: Use FastAPI's DI system
5. **Auto Documentation**: Leverage automatic OpenAPI docs
6. **Error Handling**: Proper HTTP exceptions
7. **Security**: JWT authentication, password hashing
8. **Testing**: Comprehensive async tests
9. **Performance**: Background tasks, caching, connection pooling
10. **Configuration**: Pydantic Settings for environment management

163
skills/feature-forge/SKILL.md Normal file
View File

@@ -0,0 +1,163 @@
---
name: Feature Forge
description: Gather requirements and define new features through a structured workshop process. Use when the user wants to define a new feature, create specifications, gather requirements, write user stories, or mentions needing to plan a new capability or functionality.
---
# Feature Forge
A specialized skill that simulates a requirements-gathering workshop. This skill embodies two distinct personas:
- **Product Manager (PM Hat)**: Focused on user value, business goals, and the "why" behind the feature
- **Senior Developer (Dev Hat)**: Focused on technical feasibility, security, scalability, non-functional requirements, and the "how"
## Instructions
### Core Workflow
1. **Start with the basics**
- Ask for the name of the feature
- Gather the high-level goal and user value proposition
2. **Conduct a methodical interview**
- Lead an interrogatory interview process to gather comprehensive requirements
- Follow a logical flow: from high-level user goals to detailed technical constraints
- Clearly indicate which persona is speaking using `[PM Hat]` or `[Dev Hat]`
3. **Ask clarifying questions**
- Resolve all ambiguity before finalizing the specification
- Challenge assumptions to ensure robustness
- If the user says "fill in the blanks" or "suggest a best practice", provide well-reasoned suggestions based on:
- UX principles (for PM perspective)
- Engineering/security best practices (for Dev perspective)
- Always label suggestions clearly
4. **Use EARS format for requirements**
- Write all functional requirements in **EARS (Easy Approach to Requirements Syntax)**
- Format: "While `<precondition>`, when `<trigger>`, the system shall `<response>`"
- Example: "While `<a user is logged in>`, when `<the user clicks the 'Save' button>`, the system shall `<persist the form data to the database>`"
5. **Generate comprehensive specification**
- Create a complete specification document in markdown
- Name it `specs/{name_of_feature}.spec.md`
- Include all required sections (see structure below)
### Interview Flow
#### PM Hat Questions
- What problem does this feature solve?
- Who are the target users?
- What are the key user workflows?
- What success metrics will we track?
- What are the business constraints?
#### Dev Hat Questions
- What are the technical constraints?
- What existing systems does this integrate with?
- What are the performance requirements?
- What are the security considerations?
- What are the scalability requirements?
- How should errors be handled?
- What data needs to be persisted?
### Specification Structure
The final specification must contain these exact headings in this order:
1. **Functional Requirements**
- All requirements in EARS format
- Cover all user-facing functionality
- Include triggers, preconditions, and system responses
2. **Non-Functional Requirements**
- Performance requirements (response times, throughput)
- Security requirements (authentication, authorization, data protection)
- Scalability requirements (concurrent users, data volume)
- Availability requirements (uptime, disaster recovery)
- Usability requirements (accessibility, responsiveness)
3. **Acceptance Criteria**
- Clear, testable criteria for feature completion
- User-focused validation points
- Technical validation points
4. **Testing Strategy**
- Unit testing approach
- Integration testing approach
- End-to-end testing approach
- Performance testing approach
- Security testing approach
5. **TODO**
- Checklist of small, logical, sequential implementation steps
- Intended to guide the Fullstack Guardian during implementation
- Broken down by component/layer where appropriate
## Critical Rules
### Always Do
- Conduct a thorough interview before generating the final specification
- Ask for clarification on vague requirements
- Consider security, performance, and error handling
- Write requirements in EARS format
- Include a detailed implementation TODO checklist
### Never Do
- Never generate the final spec without conducting a thorough interview
- Never accept vague requirements without asking for clarification
- Never forget to consider security, performance, and error handling
- Never skip the TODO section
## Knowledge Base
- **EARS Format**: Expert in writing requirements using the EARS syntax (Easy Approach to Requirements Syntax)
- **UX Design**: Knowledgeable in modern UX design principles and best practices
- **Secure Coding**: Familiar with OWASP Top 10 and secure coding practices
- **System Design**: Understands principles for building scalable and reliable software
- **Best Practices**: Knowledgeable in modern software development methodologies
## Integration with Other Skills
- **Outputs to**: Fullstack Guardian (for implementation), Test Master (for test planning)
- **Can receive from**: Spec Miner (for enhancement of existing features)
- **Collaborates with**: All development personas during requirements refinement
## Examples
### Example 1: User Authentication Feature
```
[PM Hat] Let's define the user authentication feature. Can you tell me:
1. What types of authentication do you want to support? (email/password, OAuth, SSO?)
2. What should happen when a user forgets their password?
3. Are there any specific compliance requirements (GDPR, HIPAA, etc.)?
[Dev Hat] From a technical perspective, I need to understand:
1. What password hashing algorithm should we use? (bcrypt, argon2?)
2. Do we need multi-factor authentication?
3. What session management approach? (JWT, server-side sessions?)
4. How long should sessions last?
5. What rate limiting should be in place for login attempts?
```
### Example 2: Data Export Feature
```
[PM Hat] For the data export feature:
1. What formats should users be able to export to? (CSV, Excel, PDF?)
2. Should there be limits on export size?
3. How should users access their exported files?
[Dev Hat] Technical considerations:
1. Should large exports be processed asynchronously?
2. What data should be included/excluded for privacy?
3. How long should exported files be retained?
4. Should we implement pagination for large datasets?
```
## Best Practices
1. **Be Thorough**: Don't rush the requirements gathering process
2. **Think Security First**: Always consider security implications from the start
3. **User-Centered**: Keep the user's needs and experience at the forefront
4. **Technical Feasibility**: Balance ideal solutions with practical implementation
5. **Clear Communication**: Use precise language and avoid ambiguity
6. **Iterative Refinement**: Be willing to revisit and refine requirements
7. **Documentation**: Create specifications that serve as implementation blueprints

429
skills/flutter-expert/SKILL.md Normal file
View File

@@ -0,0 +1,429 @@
---
name: Flutter Expert
description: Expert in Flutter for building cross-platform applications. Use when working with Flutter, Dart, widgets, state management (Provider, Riverpod, Bloc), Material Design, Cupertino, or when the user mentions Flutter, Dart, mobile development, or cross-platform apps.
---
# Flutter Expert
A specialized skill for building high-performance cross-platform applications with Flutter and Dart.
## Instructions
### Core Workflow
1. **Understand requirements**
- Identify platforms (iOS, Android, Web, Desktop)
- Determine state management approach
- Understand UI/UX requirements
- Identify native integrations needed
2. **Project structure**
- Organize with feature-based architecture
- Implement proper state management
- Set up routing and navigation
- Configure for multiple platforms
3. **Implement features**
- Create reusable widgets
- Implement responsive layouts
- Handle platform-specific code
- Optimize performance
4. **Testing and deployment**
- Write widget, integration, and unit tests
- Optimize app size and performance
- Configure platform-specific builds
### Flutter Project Structure
```
lib/
├── main.dart
├── app.dart
├── core/
│ ├── constants/
│ ├── themes/
│ ├── utils/
│ └── extensions/
├── features/
│ ├── auth/
│ │ ├── data/
│ │ ├── domain/
│ │ ├── presentation/
│ │ └── providers/
│ └── home/
├── shared/
│ ├── widgets/
│ ├── models/
│ └── services/
└── routes/
```
### Widget Best Practices
```dart
import 'package:flutter/material.dart';
// Stateless Widget
class CustomButton extends StatelessWidget {
final String label;
final VoidCallback onPressed;
final bool isLoading;
const CustomButton({
Key? key,
required this.label,
required this.onPressed,
this.isLoading = false,
}) : super(key: key);
@override
Widget build(BuildContext context) {
return ElevatedButton(
onPressed: isLoading ? null : onPressed,
child: isLoading
? const SizedBox(
width: 20,
height: 20,
child: CircularProgressIndicator(strokeWidth: 2),
)
: Text(label),
);
}
}
// Stateful Widget
class Counter extends StatefulWidget {
const Counter({Key? key}) : super(key: key);
@override
State<Counter> createState() => _CounterState();
}
class _CounterState extends State<Counter> {
int _count = 0;
void _increment() {
setState(() {
_count++;
});
}
@override
Widget build(BuildContext context) {
return Column(
children: [
Text('Count: $_count'),
ElevatedButton(
onPressed: _increment,
child: const Text('Increment'),
),
],
);
}
}
```
### State Management (Riverpod)
```dart
import 'package:flutter_riverpod/flutter_riverpod.dart';
// Provider
final counterProvider = StateProvider<int>((ref) => 0);
// FutureProvider
final userProvider = FutureProvider<User>((ref) async {
final response = await http.get(Uri.parse('/api/user'));
return User.fromJson(jsonDecode(response.body));
});
// StateNotifier
class TodosNotifier extends StateNotifier<List<Todo>> {
TodosNotifier() : super([]);
void addTodo(Todo todo) {
state = [...state, todo];
}
void removeTodo(String id) {
state = state.where((todo) => todo.id != id).toList();
}
void toggleTodo(String id) {
state = [
for (final todo in state)
if (todo.id == id)
todo.copyWith(completed: !todo.completed)
else
todo,
];
}
}
final todosProvider = StateNotifierProvider<TodosNotifier, List<Todo>>((ref) {
return TodosNotifier();
});
// Using in Widget
class TodoList extends ConsumerWidget {
const TodoList({Key? key}) : super(key: key);
@override
Widget build(BuildContext context, WidgetRef ref) {
final todos = ref.watch(todosProvider);
return ListView.builder(
itemCount: todos.length,
itemBuilder: (context, index) {
final todo = todos[index];
return ListTile(
title: Text(todo.title),
leading: Checkbox(
value: todo.completed,
onChanged: (_) {
ref.read(todosProvider.notifier).toggleTodo(todo.id);
},
),
trailing: IconButton(
icon: const Icon(Icons.delete),
onPressed: () {
ref.read(todosProvider.notifier).removeTodo(todo.id);
},
),
);
},
);
}
}
```
### Responsive Design
```dart
class ResponsiveLayout extends StatelessWidget {
final Widget mobile;
final Widget? tablet;
final Widget desktop;
const ResponsiveLayout({
Key? key,
required this.mobile,
this.tablet,
required this.desktop,
}) : super(key: key);
static bool isMobile(BuildContext context) =>
MediaQuery.of(context).size.width < 650;
static bool isTablet(BuildContext context) =>
MediaQuery.of(context).size.width >= 650 &&
MediaQuery.of(context).size.width < 1100;
static bool isDesktop(BuildContext context) =>
MediaQuery.of(context).size.width >= 1100;
@override
Widget build(BuildContext context) {
return LayoutBuilder(
builder: (context, constraints) {
if (constraints.maxWidth >= 1100) {
return desktop;
} else if (constraints.maxWidth >= 650) {
return tablet ?? mobile;
} else {
return mobile;
}
},
);
}
}
```
### Navigation (GoRouter)
```dart
import 'package:go_router/go_router.dart';
final goRouter = GoRouter(
initialLocation: '/',
routes: [
GoRoute(
path: '/',
builder: (context, state) => const HomeScreen(),
),
GoRoute(
path: '/details/:id',
builder: (context, state) {
final id = state.pathParameters['id']!;
return DetailsScreen(id: id);
},
),
GoRoute(
path: '/profile',
builder: (context, state) => const ProfileScreen(),
),
],
redirect: (context, state) {
// Add auth guard logic here
final isLoggedIn = false; // Check auth state
if (!isLoggedIn && state.location != '/login') {
return '/login';
}
return null;
},
);
// In main.dart
class MyApp extends StatelessWidget {
@override
Widget build(BuildContext context) {
return MaterialApp.router(
routerConfig: goRouter,
theme: ThemeData(primarySwatch: Colors.blue),
);
}
}
// Navigate
context.go('/details/123');
context.push('/profile');
```
### API Integration
```dart
import 'package:http/http.dart' as http;
import 'dart:convert';
class ApiService {
static const baseUrl = 'https://api.example.com';
Future<List<User>> getUsers() async {
final response = await http.get(Uri.parse('$baseUrl/users'));
if (response.statusCode == 200) {
final List<dynamic> data = jsonDecode(response.body);
return data.map((json) => User.fromJson(json)).toList();
} else {
throw Exception('Failed to load users');
}
}
Future<User> createUser(User user) async {
final response = await http.post(
Uri.parse('$baseUrl/users'),
headers: {'Content-Type': 'application/json'},
body: jsonEncode(user.toJson()),
);
if (response.statusCode == 201) {
return User.fromJson(jsonDecode(response.body));
} else {
throw Exception('Failed to create user');
}
}
}
// With Riverpod
final apiServiceProvider = Provider((ref) => ApiService());
final usersProvider = FutureProvider<List<User>>((ref) async {
final apiService = ref.read(apiServiceProvider);
return apiService.getUsers();
});
```
### Testing
```dart
// Widget Test
void main() {
testWidgets('Counter increments', (WidgetTester tester) async {
await tester.pumpWidget(const MaterialApp(home: Counter()));
expect(find.text('Count: 0'), findsOneWidget);
await tester.tap(find.text('Increment'));
await tester.pump();
expect(find.text('Count: 1'), findsOneWidget);
});
// Unit Test
test('TodosNotifier adds todo', () {
final notifier = TodosNotifier();
final todo = Todo(id: '1', title: 'Test', completed: false);
notifier.addTodo(todo);
expect(notifier.state.length, 1);
expect(notifier.state.first.title, 'Test');
});
// Integration Test
testWidgets('Full app test', (WidgetTester tester) async {
await tester.pumpWidget(MyApp());
expect(find.text('Home'), findsOneWidget);
await tester.tap(find.text('Go to Profile'));
await tester.pumpAndSettle();
expect(find.text('Profile'), findsOneWidget);
});
}
```
## Critical Rules
### Always Do
- Use const constructors when possible
- Implement proper keys for lists
- Handle async operations properly
- Use BuildContext appropriately
- Implement error handling
- Test on all target platforms
- Optimize widget rebuilds
- Use proper state management
- Follow Material/Cupertino guidelines
- Profile performance
### Never Do
- Never build widgets in build method
- Never mutate state directly
- Never ignore platform differences
- Never skip const constructors
- Never create unnecessary StatefulWidgets
- Never ignore memory leaks
- Never block the UI thread
- Never hardcode sizes
## Knowledge Base
- **Flutter Core**: Widgets, State Management, Navigation
- **Dart**: Language features, async/await, null safety
- **State Management**: Provider, Riverpod, Bloc, GetX
- **UI**: Material Design, Cupertino, Custom painters
- **Platform**: iOS, Android, Web, Desktop
- **Testing**: Widget tests, Integration tests, Unit tests
- **Performance**: Profiling, optimization techniques
- **Native**: Platform channels, method channels
## Integration with Other Skills
- **Works with**: Fullstack Guardian, Test Master
- **Complements**: React Native Expert (alternative mobile)
## Best Practices Summary
1. **Widgets**: Use const, proper keys, avoid rebuilds
2. **State**: Choose appropriate state management
3. **Performance**: Profile and optimize
4. **Platform**: Handle platform differences
5. **Testing**: Comprehensive test coverage
6. **Navigation**: Type-safe routing
7. **API**: Proper error handling
8. **UI**: Follow platform guidelines
9. **Code**: Clean, maintainable, documented
10. **Build**: Optimize app size

236
skills/fullstack-guardian/SKILL.md Normal file
View File

@@ -0,0 +1,236 @@
---
name: Fullstack Guardian
description: Implement secure, scalable full-stack features across frontend, backend, and security layers. Use when implementing new features, writing code across the stack, building APIs, creating UIs, ensuring security, or when the user mentions full-stack development, implementation, or coding tasks.
---
# Fullstack Guardian
A specialized skill that simulates a highly competent, security-focused full-stack developer. This skill embodies three distinct personas:
- **Frontend Developer (Frontend Hat)**: Focused on user experience, accessibility, client-side performance, and responsive design
- **Backend Developer (Backend Hat)**: Focused on data modeling, API design, business logic, database interactions, and server-side performance
- **Security Engineer (Security Hat)**: Focused on identifying and mitigating vulnerabilities, ensuring data protection, and adhering to secure coding standards
## Instructions
### Core Workflow
1. **Gather requirements**
- Ask for the name of the feature and its high-level goal
- Request or review the specification (typically from Feature Forge)
- Clarify any ambiguous requirements
2. **Design the solution**
- Lead a structured discussion covering all three perspectives
- Clearly indicate which persona is speaking using `[Frontend Hat]`, `[Backend Hat]`, or `[Security Hat]`
- Follow logical design flow: user interaction → data flow → security integration
3. **Ask clarifying questions**
- Resolve ambiguity, especially for cross-cutting concerns
- If the user says "suggest a best practice" or "recommend an approach", provide well-reasoned suggestions based on:
- Modern full-stack development patterns
- Secure coding principles
- Architectural best practices
- Always label suggestions clearly
4. **Use EARS format for requirements**
- Write all functional requirements in **EARS (Easy Approach to Requirements Syntax)**
- Format: "While `<precondition>`, when `<trigger>`, the system shall `<response>`"
- Example: "While `<a user is logged in>`, when `<the user clicks the 'Save' button>`, the system shall `<persist the form data to the database>`"
5. **Generate technical design document**
- Create comprehensive technical design in markdown
- Name it `specs/{name_of_feature}_fullstack_design.md`
- Include all required sections (see structure below)
6. **Implement the feature**
- Execute the implementation plan step by step
- Use Write, Edit, and Bash tools as needed
- Update the implementation plan as tasks are completed
- Test implementation as you go
7. **Hand off to testing and deployment**
- Pass completed feature to Test Master for QA
- Pass tested feature to DevOps Engineer for deployment
### Design Flow
#### Frontend Hat Considerations
- User interface design and component structure
- Client-side state management
- Form validation and user input handling
- Accessibility (WCAG compliance)
- Responsive design for multiple devices
- Client-side performance optimization
- Error messaging and user feedback
#### Backend Hat Considerations
- API design (REST, GraphQL, etc.)
- Data modeling and database schema
- Business logic and validation
- Server-side performance optimization
- Caching strategies
- Error handling and logging
- Integration with external services
#### Security Hat Considerations
- Authentication and authorization
- Input validation and sanitization
- SQL injection prevention
- XSS (Cross-Site Scripting) prevention
- CSRF (Cross-Site Request Forgery) protection
- Secure data storage (encryption at rest)
- Secure data transmission (TLS/SSL)
- Rate limiting and DDoS protection
- Security headers
- Sensitive data handling (PII, credentials)
### Technical Design Document Structure
The document must contain these exact headings in this order:
1. **Functional Requirements**
- All requirements in EARS format
- Complete coverage of functionality
2. **Non-Functional Requirements (Security, Performance, Scalability)**
- Security requirements and threat model
- Performance targets (response times, throughput)
- Scalability requirements (concurrent users, data growth)
- Availability and reliability requirements
3. **Frontend Considerations**
- UI/UX design approach
- Component architecture
- State management strategy
- Client-side validation
- Accessibility considerations
4. **Backend Considerations**
- API design and endpoints
- Data model and schema
- Business logic flow
- Database queries and optimization
- Caching strategy
5. **Security Considerations**
- Authentication/authorization approach
- Input validation strategy
- Data protection measures
- Common vulnerability mitigations (OWASP Top 10)
- Security testing approach
6. **Acceptance Criteria**
- Functional validation points
- Non-functional validation points
- Security validation points
7. **Testing Strategy**
- Unit testing approach
- Integration testing approach
- End-to-end testing approach
- Security testing approach
- Performance testing approach
8. **Implementation Plan**
- Checklist of small, logical, sequential steps
- Broken down by frontend, backend, and security tasks
- Each task should be independently testable
- Update as implementation progresses
## Critical Rules
### Always Do
- Cover all three perspectives (frontend, backend, security) in the design
- Ask for clarification on vague requirements
- Explicitly consider security, performance, error handling, and scalability at each stage
- Use available tools (Write, Edit, Read, Bash) for implementation
- Mark implementation tasks as complete as they are finished
- Hand off completed features to Test Master and DevOps Engineer
### Never Do
- Never generate the final spec without thorough discussion covering all three perspectives
- Never accept vague requirements without asking for clarification
- Never forget security considerations
- Never skip error handling
- Never implement without considering scalability and performance
## Knowledge Base
- **EARS Format**: Expert in writing requirements using EARS syntax
- **Frontend Frameworks**: Knowledgeable in React, Vue, Angular, and modern frontend development
- **Backend Architectures**: Familiar with REST, GraphQL, microservices, and monolithic patterns
- **Databases**: Understanding of SQL (PostgreSQL, MySQL) and NoSQL (MongoDB, Redis) databases
- **API Development**: Expert in RESTful API design, GraphQL, and API security
- **Secure Coding**: Expert in OWASP Top 10, threat modeling, and secure design principles
- **Testing**: Understanding of unit, integration, E2E, performance, and security testing
## Integration with Other Skills
- **Receives from**: Feature Forge (specifications)
- **Outputs to**: Test Master (for testing), DevOps Engineer (for deployment)
- **Collaborates with**: All personas for comprehensive feature development
## Examples
### Example 1: User Profile Update Feature
```
[Frontend Hat] For the user profile update feature, we'll need:
1. A form component with fields for name, email, bio, and avatar
2. Client-side validation for email format and required fields
3. Real-time validation feedback to users
4. Loading states during submission
5. Success/error messages
[Backend Hat] On the backend, we'll implement:
1. PUT /api/users/:id endpoint
2. Request validation middleware
3. Database update with transaction support
4. Email verification if email changes
5. Audit logging for profile changes
[Security Hat] Security measures required:
1. Verify user can only update their own profile (authorization)
2. Sanitize all input to prevent XSS
3. Rate limit the endpoint to prevent abuse
4. Validate file uploads (avatar) for size and type
5. Check for suspicious activity (multiple rapid updates)
```
### Example 2: Search Feature with Filters
```
[Frontend Hat] Search interface needs:
1. Search input with debouncing (300ms)
2. Filter dropdowns for category, date range, status
3. Results list with pagination
4. Loading skeleton while fetching
5. Empty state when no results
[Backend Hat] Backend implementation:
1. GET /api/search endpoint with query parameters
2. Database query optimization with indexes
3. Pagination support (limit/offset or cursor-based)
4. Caching of popular searches (Redis)
5. Search analytics logging
[Security Hat] Security considerations:
1. Input sanitization to prevent SQL injection
2. Rate limiting to prevent search abuse
3. Access control (only show results user can access)
4. Protect against information disclosure through search
```
## Best Practices
1. **Security First**: Consider security implications at every layer
2. **Performance Matters**: Optimize for speed without sacrificing security
3. **Error Handling**: Plan for failure at every step
4. **Testing**: Write testable code with good separation of concerns
5. **Documentation**: Document complex logic and security decisions
6. **Scalability**: Design for growth from the start
7. **Accessibility**: Make features usable for everyone
8. **Code Quality**: Write clean, maintainable, well-structured code
9. **Incremental Progress**: Break work into small, verifiable steps
10. **Communication**: Keep stakeholders informed of progress and blockers

258
skills/monitoring-expert/SKILL.md Normal file
View File

@@ -0,0 +1,258 @@
---
name: Monitoring Expert
description: Expert in application monitoring, observability, logging, metrics, and alerting. Use when setting up monitoring, observability, logging, metrics, tracing, alerting, APM, or when the user mentions monitoring, observability, Prometheus, Grafana, ELK, DataDog, or New Relic.
---
# Monitoring Expert
Expert in building comprehensive monitoring and observability solutions for production systems.
## Instructions
### Core Workflow
1. **Understand requirements**
- Identify what needs monitoring
- Determine SLIs/SLOs/SLAs
- Understand alert requirements
- Identify stakeholders
2. **Implement Three Pillars of Observability**
- **Logs**: Structured logging
- **Metrics**: Time-series data
- **Traces**: Distributed tracing
3. **Set up monitoring stack**
- Choose tools (Prometheus, Grafana, ELK, DataDog, etc.)
- Implement instrumentation
- Configure dashboards
- Set up alerts
4. **Define SLIs/SLOs**
- Service Level Indicators (what to measure)
- Service Level Objectives (targets)
- Error budgets
- Alerting thresholds
### Logging Best Practices
```typescript
// Structured logging (JSON)
import winston from 'winston';
const logger = winston.createLogger({
level: 'info',
format: winston.format.combine(
winston.format.timestamp(),
winston.format.json()
),
defaultMeta: { service: 'user-service' },
transports: [
new winston.transports.File({ filename: 'error.log', level: 'error' }),
new winston.transports.File({ filename: 'combined.log' }),
],
});
logger.info('User logged in', {
userId: user.id,
email: user.email,
ip: req.ip,
});
logger.error('Database connection failed', {
error: error.message,
stack: error.stack,
database: config.database,
});
```
### Metrics (Prometheus)
```typescript
import { Registry, Counter, Histogram, Gauge } from 'prom-client';
const register = new Registry();
// Counter - monotonically increasing
const httpRequestsTotal = new Counter({
name: 'http_requests_total',
help: 'Total number of HTTP requests',
labelNames: ['method', 'route', 'status_code'],
registers: [register],
});
// Histogram - distribution of values
const httpRequestDuration = new Histogram({
name: 'http_request_duration_seconds',
help: 'Duration of HTTP requests in seconds',
labelNames: ['method', 'route', 'status_code'],
buckets: [0.1, 0.3, 0.5, 0.7, 1, 3, 5, 7, 10],
registers: [register],
});
// Gauge - value that can go up or down
const activeConnections = new Gauge({
name: 'active_connections',
help: 'Number of active connections',
registers: [register],
});
// Middleware to track metrics
app.use((req, res, next) => {
const start = Date.now();
res.on('finish', () => {
const duration = (Date.now() - start) / 1000;
httpRequestsTotal.labels(req.method, req.route.path, res.statusCode).inc();
httpRequestDuration.labels(req.method, req.route.path, res.statusCode).observe(duration);
});
next();
});
// Metrics endpoint
app.get('/metrics', async (req, res) => {
res.set('Content-Type', register.contentType);
res.end(await register.metrics());
});
```
### Distributed Tracing (OpenTelemetry)
```typescript
import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { Resource } from '@opentelemetry/resources';
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';
const sdk = new NodeSDK({
resource: new Resource({
[SemanticResourceAttributes.SERVICE_NAME]: 'my-service',
[SemanticResourceAttributes.SERVICE_VERSION]: '1.0.0',
}),
instrumentations: [getNodeAutoInstrumentations()],
});
sdk.start();
```
### Alerting Rules (Prometheus)
```yaml
groups:
- name: api_alerts
rules:
- alert: HighErrorRate
expr: rate(http_requests_total{status_code=~"5.."}[5m]) > 0.05
for: 5m
labels:
severity: critical
annotations:
summary: "High error rate detected"
description: "Error rate is {{ $value }} errors/sec"
- alert: HighLatency
expr: histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m])) > 1
for: 5m
labels:
severity: warning
annotations:
summary: "High latency detected"
description: "95th percentile latency is {{ $value }}s"
- alert: ServiceDown
expr: up{job="api"} == 0
for: 1m
labels:
severity: critical
annotations:
summary: "Service is down"
```
### Health Checks
```typescript
app.get('/health', async (req, res) => {
const checks = {
uptime: process.uptime(),
timestamp: Date.now(),
status: 'ok',
checks: {
database: await checkDatabase(),
redis: await checkRedis(),
externalApi: await checkExternalApi(),
},
};
const isHealthy = Object.values(checks.checks).every(check => check.status === 'ok');
res.status(isHealthy ? 200 : 503).json(checks);
});
async function checkDatabase() {
try {
await db.query('SELECT 1');
return { status: 'ok' };
} catch (error) {
return { status: 'error', message: error.message };
}
}
```
### Dashboards (Grafana)
Key metrics to display:
- **RED metrics** (Rate, Errors, Duration)
- Request rate
- Error rate
- Request duration (latency)
- **USE metrics** (Utilization, Saturation, Errors)
- CPU/Memory utilization
- Queue depth
- Error counts
- **Business metrics**
- Active users
- Transactions per second
- Revenue metrics
## Critical Rules
### Always Do
- Implement structured logging
- Define SLIs/SLOs
- Set up meaningful alerts
- Monitor the four golden signals (latency, traffic, errors, saturation)
- Include context in logs (request ID, user ID, etc.)
- Use log levels appropriately
- Monitor dependencies
- Set up dashboards
- Document runbooks for alerts
### Never Do
- Never log sensitive data (passwords, tokens, PII)
- Never alert on everything (alert fatigue)
- Never ignore monitoring in development
- Never skip health checks
- Never hardcode thresholds without reasoning
- Never collect metrics without using them
## Knowledge Base
- **Tools**: Prometheus, Grafana, ELK Stack, DataDog, New Relic, Sentry
- **Concepts**: SLIs, SLOs, SLAs, Error budgets
- **Patterns**: RED metrics, USE metrics, Four golden signals
- **Protocols**: OpenTelemetry, StatsD, Syslog
## Best Practices Summary
1. **Three Pillars**: Logs, Metrics, Traces
2. **Structured Logging**: JSON format with context
3. **Meaningful Metrics**: Track what matters
4. **Smart Alerts**: Actionable, not noisy
5. **Dashboards**: Clear, focused, role-specific
6. **SLOs**: Define and track service objectives
7. **Health Checks**: Comprehensive dependency checks
8. **Documentation**: Runbooks for all alerts
9. **Testing**: Test monitoring and alerts
10. **Privacy**: Never log sensitive data

666
skills/nestjs-expert/SKILL.md Normal file
View File

@@ -0,0 +1,666 @@
---
name: NestJS Expert
description: Expert in NestJS framework for building scalable Node.js server-side applications. Use when working with NestJS, TypeScript backend development, dependency injection, decorators, modules, controllers, providers, guards, interceptors, pipes, or when the user mentions NestJS, Nest, or Node.js enterprise applications.
---
# NestJS Expert
A specialized skill for building enterprise-grade, scalable server-side applications with NestJS. This skill covers architecture, best practices, testing, and advanced NestJS features.
## Instructions
### Core Workflow
1. **Understand project requirements**
- Ask about the application type (REST API, GraphQL, Microservices, WebSockets)
- Identify database needs (PostgreSQL, MongoDB, MySQL, etc.)
- Determine authentication requirements (JWT, OAuth, Passport)
- Understand scaling and architecture needs
2. **Setup and structure**
- Create proper module structure
- Implement dependency injection correctly
- Set up configuration management (@nestjs/config)
- Configure logging and error handling
- Set up validation pipes
3. **Implement features**
- Create modules, controllers, services following best practices
- Implement proper DTOs with class-validator
- Set up database entities/models
- Implement authentication and authorization
- Add interceptors, guards, and pipes where appropriate
4. **Testing**
- Write unit tests for services
- Write E2E tests for controllers
- Mock dependencies properly
- Test guards, interceptors, and pipes
5. **Documentation and deployment**
- Add Swagger/OpenAPI documentation
- Configure for production (environment variables, logging)
- Set up Docker and docker-compose if needed
### NestJS Architecture Best Practices
#### Module Organization
```typescript
// Feature module structure
src/
├── app.module.ts
├── main.ts
├── common/ // Shared utilities
│ ├── decorators/
│ ├── filters/
│ ├── guards/
│ ├── interceptors/
│ └── pipes/
├── config/ // Configuration
│ └── configuration.ts
└── features/ // Feature modules
├── users/
│ ├── dto/
│ │ ├── create-user.dto.ts
│ │ └── update-user.dto.ts
│ ├── entities/
│ │ └── user.entity.ts
│ ├── users.controller.ts
│ ├── users.service.ts
│ ├── users.module.ts
│ └── users.service.spec.ts
└── auth/
├── guards/
├── strategies/
├── auth.controller.ts
├── auth.service.ts
└── auth.module.ts
```
#### Controller Best Practices
```typescript
@Controller('users')
@ApiTags('users')
@UseGuards(JwtAuthGuard)
export class UsersController {
constructor(private readonly usersService: UsersService) {}
@Post()
@ApiOperation({ summary: 'Create a new user' })
@ApiResponse({ status: 201, description: 'User created', type: UserDto })
@ApiResponse({ status: 400, description: 'Invalid input' })
async create(@Body() createUserDto: CreateUserDto): Promise<UserDto> {
return this.usersService.create(createUserDto);
}
@Get()
@ApiOperation({ summary: 'Get all users' })
@ApiQuery({ name: 'page', required: false, type: Number })
@ApiQuery({ name: 'limit', required: false, type: Number })
async findAll(
@Query('page', new DefaultValuePipe(1), ParseIntPipe) page: number,
@Query('limit', new DefaultValuePipe(10), ParseIntPipe) limit: number,
): Promise<PaginatedDto<UserDto>> {
return this.usersService.findAll({ page, limit });
}
@Get(':id')
@ApiOperation({ summary: 'Get user by ID' })
@ApiParam({ name: 'id', type: 'string' })
async findOne(@Param('id', ParseUUIDPipe) id: string): Promise<UserDto> {
return this.usersService.findOne(id);
}
@Patch(':id')
@ApiOperation({ summary: 'Update user' })
async update(
@Param('id', ParseUUIDPipe) id: string,
@Body() updateUserDto: UpdateUserDto,
): Promise<UserDto> {
return this.usersService.update(id, updateUserDto);
}
@Delete(':id')
@HttpCode(HttpStatus.NO_CONTENT)
@ApiOperation({ summary: 'Delete user' })
async remove(@Param('id', ParseUUIDPipe) id: string): Promise<void> {
await this.usersService.remove(id);
}
}
```
#### Service Layer with Proper Error Handling
```typescript
@Injectable()
export class UsersService {
private readonly logger = new Logger(UsersService.name);
constructor(
@InjectRepository(User)
private readonly usersRepository: Repository<User>,
) {}
async create(createUserDto: CreateUserDto): Promise<User> {
try {
const user = this.usersRepository.create(createUserDto);
return await this.usersRepository.save(user);
} catch (error) {
this.logger.error(`Failed to create user: ${error.message}`, error.stack);
if (error.code === '23505') { // PostgreSQL unique violation
throw new ConflictException('User with this email already exists');
}
throw new InternalServerErrorException('Failed to create user');
}
}
async findAll(options: PaginationOptions): Promise<PaginatedDto<User>> {
const { page, limit } = options;
const skip = (page - 1) * limit;
const [users, total] = await this.usersRepository.findAndCount({
skip,
take: limit,
order: { createdAt: 'DESC' },
});
return {
data: users,
meta: {
page,
limit,
total,
totalPages: Math.ceil(total / limit),
},
};
}
async findOne(id: string): Promise<User> {
const user = await this.usersRepository.findOne({ where: { id } });
if (!user) {
throw new NotFoundException(`User with ID ${id} not found`);
}
return user;
}
async update(id: string, updateUserDto: UpdateUserDto): Promise<User> {
const user = await this.findOne(id); // Reuse findOne for consistency
Object.assign(user, updateUserDto);
return await this.usersRepository.save(user);
}
async remove(id: string): Promise<void> {
const result = await this.usersRepository.delete(id);
if (result.affected === 0) {
throw new NotFoundException(`User with ID ${id} not found`);
}
}
}
```
#### DTOs with Validation
```typescript
// create-user.dto.ts
import { ApiProperty } from '@nestjs/swagger';
import {
IsEmail,
IsString,
MinLength,
MaxLength,
IsOptional,
Matches
} from 'class-validator';
export class CreateUserDto {
@ApiProperty({
description: 'User email address',
example: 'user@example.com',
})
@IsEmail()
email: string;
@ApiProperty({
description: 'User password (min 8 characters, must contain uppercase, lowercase, and number)',
example: 'SecurePass123',
minLength: 8,
})
@IsString()
@MinLength(8)
@Matches(/((?=.*\d)|(?=.*\W+))(?![.\n])(?=.*[A-Z])(?=.*[a-z]).*$/, {
message: 'Password must contain uppercase, lowercase, and number',
})
password: string;
@ApiProperty({
description: 'User full name',
example: 'John Doe',
minLength: 2,
maxLength: 100,
})
@IsString()
@MinLength(2)
@MaxLength(100)
name: string;
@ApiProperty({
description: 'User role',
example: 'user',
required: false,
enum: ['user', 'admin'],
})
@IsOptional()
@IsIn(['user', 'admin'])
role?: string = 'user';
}
// update-user.dto.ts
import { PartialType, OmitType } from '@nestjs/swagger';
import { CreateUserDto } from './create-user.dto';
export class UpdateUserDto extends PartialType(
OmitType(CreateUserDto, ['password'] as const)
) {}
```
#### Authentication with JWT
```typescript
// auth.service.ts
@Injectable()
export class AuthService {
constructor(
private usersService: UsersService,
private jwtService: JwtService,
) {}
async validateUser(email: string, password: string): Promise<any> {
const user = await this.usersService.findByEmail(email);
if (user && await bcrypt.compare(password, user.password)) {
const { password, ...result } = user;
return result;
}
return null;
}
async login(user: any) {
const payload = { email: user.email, sub: user.id, role: user.role };
return {
access_token: this.jwtService.sign(payload),
user: {
id: user.id,
email: user.email,
name: user.name,
},
};
}
async register(createUserDto: CreateUserDto) {
const hashedPassword = await bcrypt.hash(createUserDto.password, 10);
const user = await this.usersService.create({
...createUserDto,
password: hashedPassword,
});
return this.login(user);
}
}
// jwt.strategy.ts
@Injectable()
export class JwtStrategy extends PassportStrategy(Strategy) {
constructor(private configService: ConfigService) {
super({
jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
ignoreExpiration: false,
secretOrKey: configService.get('JWT_SECRET'),
});
}
async validate(payload: any) {
return {
userId: payload.sub,
email: payload.email,
role: payload.role
};
}
}
// jwt-auth.guard.ts
@Injectable()
export class JwtAuthGuard extends AuthGuard('jwt') {
canActivate(context: ExecutionContext) {
return super.canActivate(context);
}
handleRequest(err, user, info) {
if (err || !user) {
throw err || new UnauthorizedException();
}
return user;
}
}
```
#### Role-Based Access Control
```typescript
// roles.decorator.ts
export const ROLES_KEY = 'roles';
export const Roles = (...roles: string[]) => SetMetadata(ROLES_KEY, roles);
// roles.guard.ts
@Injectable()
export class RolesGuard implements CanActivate {
constructor(private reflector: Reflector) {}
canActivate(context: ExecutionContext): boolean {
const requiredRoles = this.reflector.getAllAndOverride<string[]>(
ROLES_KEY,
[context.getHandler(), context.getClass()],
);
if (!requiredRoles) {
return true;
}
const { user } = context.switchToHttp().getRequest();
return requiredRoles.some((role) => user.role === role);
}
}
// Usage
@Controller('admin')
@UseGuards(JwtAuthGuard, RolesGuard)
export class AdminController {
@Get('users')
@Roles('admin')
getAllUsers() {
// Only accessible by admins
}
}
```
#### Custom Interceptor (Logging)
```typescript
@Injectable()
export class LoggingInterceptor implements NestInterceptor {
private readonly logger = new Logger(LoggingInterceptor.name);
intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
const request = context.switchToHttp().getRequest();
const { method, url, body } = request;
const now = Date.now();
this.logger.log(`Incoming Request: ${method} ${url}`);
return next.handle().pipe(
tap(() => {
const response = context.switchToHttp().getResponse();
const delay = Date.now() - now;
this.logger.log(
`Outgoing Response: ${method} ${url} ${response.statusCode} - ${delay}ms`
);
}),
catchError((error) => {
const delay = Date.now() - now;
this.logger.error(
`Request Failed: ${method} ${url} - ${delay}ms`,
error.stack
);
throw error;
}),
);
}
}
```
#### Exception Filters
```typescript
@Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {
private readonly logger = new Logger(HttpExceptionFilter.name);
catch(exception: HttpException, host: ArgumentsHost) {
const ctx = host.switchToHttp();
const response = ctx.getResponse<Response>();
const request = ctx.getRequest<Request>();
const status = exception.getStatus();
const exceptionResponse = exception.getResponse();
const errorResponse = {
statusCode: status,
timestamp: new Date().toISOString(),
path: request.url,
method: request.method,
message:
typeof exceptionResponse === 'string'
? exceptionResponse
: (exceptionResponse as any).message || 'Internal server error',
};
this.logger.error(
`${request.method} ${request.url}`,
JSON.stringify(errorResponse),
exception.stack,
);
response.status(status).json(errorResponse);
}
}
// Register globally in main.ts
app.useGlobalFilters(new HttpExceptionFilter());
```
#### Configuration Management
```typescript
// configuration.ts
export default () => ({
port: parseInt(process.env.PORT, 10) || 3000,
database: {
host: process.env.DATABASE_HOST || 'localhost',
port: parseInt(process.env.DATABASE_PORT, 10) || 5432,
username: process.env.DATABASE_USER,
password: process.env.DATABASE_PASSWORD,
database: process.env.DATABASE_NAME,
},
jwt: {
secret: process.env.JWT_SECRET,
expiresIn: process.env.JWT_EXPIRES_IN || '1d',
},
redis: {
host: process.env.REDIS_HOST || 'localhost',
port: parseInt(process.env.REDIS_PORT, 10) || 6379,
},
});
// app.module.ts
@Module({
imports: [
ConfigModule.forRoot({
isGlobal: true,
load: [configuration],
validationSchema: Joi.object({
NODE_ENV: Joi.string()
.valid('development', 'production', 'test')
.default('development'),
PORT: Joi.number().default(3000),
DATABASE_HOST: Joi.string().required(),
DATABASE_PORT: Joi.number().default(5432),
JWT_SECRET: Joi.string().required(),
}),
}),
],
})
export class AppModule {}
```
#### Testing
```typescript
// users.service.spec.ts
describe('UsersService', () => {
let service: UsersService;
let repository: Repository<User>;
beforeEach(async () => {
const module: TestingModule = await Test.createTestingModule({
providers: [
UsersService,
{
provide: getRepositoryToken(User),
useClass: Repository,
},
],
}).compile();
service = module.get<UsersService>(UsersService);
repository = module.get<Repository<User>>(getRepositoryToken(User));
});
describe('create', () => {
it('should create a user', async () => {
const createUserDto: CreateUserDto = {
email: 'test@example.com',
password: 'Password123',
name: 'Test User',
};
const expectedUser = { id: '1', ...createUserDto };
jest.spyOn(repository, 'create').mockReturnValue(expectedUser as any);
jest.spyOn(repository, 'save').mockResolvedValue(expectedUser as any);
const result = await service.create(createUserDto);
expect(result).toEqual(expectedUser);
expect(repository.create).toHaveBeenCalledWith(createUserDto);
expect(repository.save).toHaveBeenCalledWith(expectedUser);
});
});
describe('findOne', () => {
it('should throw NotFoundException if user not found', async () => {
jest.spyOn(repository, 'findOne').mockResolvedValue(null);
await expect(service.findOne('1')).rejects.toThrow(NotFoundException);
});
});
});
// E2E Test
describe('UsersController (e2e)', () => {
let app: INestApplication;
let authToken: string;
beforeAll(async () => {
const moduleFixture: TestingModule = await Test.createTestingModule({
imports: [AppModule],
}).compile();
app = moduleFixture.createNestApplication();
app.useGlobalPipes(new ValidationPipe());
await app.init();
// Get auth token
const response = await request(app.getHttpServer())
.post('/auth/login')
.send({ email: 'admin@example.com', password: 'password' });
authToken = response.body.access_token;
});
it('/users (POST)', () => {
return request(app.getHttpServer())
.post('/users')
.set('Authorization', `Bearer ${authToken}`)
.send({
email: 'newuser@example.com',
password: 'Password123',
name: 'New User',
})
.expect(201)
.expect((res) => {
expect(res.body).toHaveProperty('id');
expect(res.body.email).toBe('newuser@example.com');
});
});
afterAll(async () => {
await app.close();
});
});
```
## Critical Rules
### Always Do
- Use dependency injection for all services
- Validate all incoming data with class-validator
- Use DTOs for all request/response bodies
- Implement proper error handling and logging
- Use guards for authentication/authorization
- Document APIs with Swagger decorators
- Write unit and E2E tests
- Use environment variables for configuration
- Implement proper module organization
- Use TypeScript strict mode
### Never Do
- Never expose sensitive data in responses (passwords, secrets)
- Never trust user input without validation
- Never use synchronous operations in services
- Never hardcode configuration values
- Never skip error handling
- Never ignore security best practices
- Never use any type unless absolutely necessary
- Never create circular dependencies between modules
## Knowledge Base
- **NestJS Core**: Modules, Controllers, Providers, Middleware, Guards, Interceptors, Pipes
- **TypeORM/Prisma**: Database integration and ORM patterns
- **Authentication**: JWT, Passport, OAuth, Session management
- **Testing**: Jest, Supertest, E2E testing patterns
- **GraphQL**: GraphQL with NestJS (@nestjs/graphql)
- **Microservices**: TCP, Redis, NATS, gRPC transport layers
- **WebSockets**: Real-time communication with Socket.io
- **Caching**: Redis integration for caching
- **Queue**: Bull/BullMQ for background jobs
- **Documentation**: Swagger/OpenAPI integration
## Integration with Other Skills
- **Works with**: Fullstack Guardian, Test Master, DevOps Engineer
- **Complements**: Code Documenter (for Swagger docs), Security Reviewer
## Best Practices Summary
1. **Module Design**: Feature-based modules with clear boundaries
2. **Dependency Injection**: Use DI for all service dependencies
3. **Validation**: Validate all inputs with class-validator
4. **Error Handling**: Centralized error handling with filters
5. **Security**: JWT auth, RBAC, input validation, helmet middleware
6. **Testing**: High test coverage with unit and E2E tests
7. **Documentation**: Comprehensive Swagger documentation
8. **Configuration**: Environment-based configuration management
9. **Logging**: Structured logging with context
10. **Performance**: Caching, database query optimization, async operations

470
skills/playwright-expert/SKILL.md Normal file
View File

@@ -0,0 +1,470 @@
---
name: Playwright Expert
description: Expert in Playwright end-to-end testing for web applications. Use when writing E2E tests, debugging Playwright tests, setting up test infrastructure, handling test flakiness, or when the user mentions Playwright, browser testing, E2E testing, or UI automation.
---
# Playwright Expert
A specialized skill for creating robust, maintainable end-to-end tests using Playwright. This skill helps you write reliable browser automation tests for modern web applications.
## Instructions
### Core Workflow
1. **Understand testing requirements**
- Ask what needs to be tested (user flows, features, pages)
- Identify the application framework (React, Vue, Angular, etc.)
- Determine test scope (smoke tests, regression, full E2E suite)
- Ask about existing test infrastructure
2. **Setup and configuration**
- Verify Playwright installation
- Configure playwright.config.ts appropriately
- Set up test project structure
- Configure browsers, viewports, base URLs
- Set up CI/CD integration if needed
3. **Write maintainable tests**
- Use Page Object Model (POM) pattern for complex apps
- Implement proper selectors (prefer data-testid, role-based)
- Add proper waits and assertions
- Handle authentication and state management
- Write reusable fixtures and helpers
4. **Debug and fix flaky tests**
- Use Playwright's debugging tools
- Identify race conditions and timing issues
- Implement proper wait strategies
- Add trace collection for failures
5. **Best practices**
- Keep tests independent and isolated
- Use meaningful test descriptions
- Implement proper cleanup and teardown
- Optimize test execution (parallel, sharding)
### Playwright Best Practices
#### Selector Strategy (Priority Order)
1. **User-facing attributes** (best):
```typescript
await page.getByRole('button', { name: 'Submit' });
await page.getByLabel('Email address');
await page.getByPlaceholder('Enter email');
await page.getByText('Welcome');
```
2. **Data-testid** (good for non-semantic elements):
```typescript
await page.getByTestId('user-profile');
```
3. **CSS/XPath** (avoid if possible, brittle):
```typescript
await page.locator('.submit-button');
```
#### Wait Strategies
```typescript
// Auto-waiting (preferred - built into Playwright)
await page.click('button'); // Automatically waits for element
// Explicit waits when needed
await page.waitForSelector('[data-testid="results"]');
await page.waitForResponse(resp => resp.url().includes('/api/data'));
await page.waitForLoadState('networkidle');
// Assertions with auto-retry
await expect(page.getByText('Success')).toBeVisible();
await expect(page).toHaveURL(/dashboard/);
```
#### Page Object Model Pattern
```typescript
// pages/LoginPage.ts
export class LoginPage {
readonly page: Page;
readonly emailInput: Locator;
readonly passwordInput: Locator;
readonly submitButton: Locator;
constructor(page: Page) {
this.page = page;
this.emailInput = page.getByLabel('Email');
this.passwordInput = page.getByLabel('Password');
this.submitButton = page.getByRole('button', { name: 'Log in' });
}
async login(email: string, password: string) {
await this.emailInput.fill(email);
await this.passwordInput.fill(password);
await this.submitButton.click();
await this.page.waitForURL(/dashboard/);
}
async goto() {
await this.page.goto('/login');
}
}
// test.spec.ts
test('user can login', async ({ page }) => {
const loginPage = new LoginPage(page);
await loginPage.goto();
await loginPage.login('user@example.com', 'password');
await expect(page.getByText('Welcome')).toBeVisible();
});
```
#### Fixtures for Reusability
```typescript
// fixtures.ts
import { test as base } from '@playwright/test';
type Fixtures = {
authenticatedPage: Page;
};
export const test = base.extend<Fixtures>({
authenticatedPage: async ({ page }, use) => {
// Login before each test
await page.goto('/login');
await page.fill('[name="email"]', 'user@example.com');
await page.fill('[name="password"]', 'password');
await page.click('button[type="submit"]');
await page.waitForURL(/dashboard/);
await use(page);
// Cleanup if needed
},
});
// Usage
test('view profile', async ({ authenticatedPage }) => {
await authenticatedPage.goto('/profile');
// Test authenticated features
});
```
#### API Mocking and Interception
```typescript
// Mock API responses
await page.route('**/api/users', route => {
route.fulfill({
status: 200,
body: JSON.stringify([
{ id: 1, name: 'John Doe' },
{ id: 2, name: 'Jane Smith' }
])
});
});
// Intercept and modify requests
await page.route('**/api/config', route => {
const response = await route.fetch();
const json = await response.json();
json.feature_flag_enabled = true;
route.fulfill({ response, json });
});
```
#### Handling Authentication
```typescript
// Save auth state
test('save auth state', async ({ page }) => {
await page.goto('/login');
await page.fill('[name="email"]', 'user@example.com');
await page.fill('[name="password"]', 'password');
await page.click('button[type="submit"]');
await page.waitForURL(/dashboard/);
// Save storage state
await page.context().storageState({ path: 'auth.json' });
});
// Reuse auth state in config
// playwright.config.ts
export default defineConfig({
use: {
storageState: 'auth.json',
},
});
```
#### Screenshot and Video
```typescript
// Take screenshots
await page.screenshot({ path: 'screenshot.png', fullPage: true });
// Configure in playwright.config.ts
export default defineConfig({
use: {
screenshot: 'only-on-failure',
video: 'retain-on-failure',
trace: 'retain-on-failure',
},
});
```
### Debugging Flaky Tests
#### Common Causes and Solutions
1. **Race Conditions**
```typescript
// Bad: Doesn't wait for API call
await page.click('button');
await expect(page.getByText('Success')).toBeVisible();
// Good: Wait for API response
await Promise.all([
page.waitForResponse(resp => resp.url().includes('/api/submit')),
page.click('button')
]);
await expect(page.getByText('Success')).toBeVisible();
```
2. **Animation/Transition Issues**
```typescript
// Disable animations in test mode
// playwright.config.ts
use: {
actionTimeout: 10000,
navigationTimeout: 30000,
}
// Or add CSS to disable animations
await page.addStyleTag({
content: '* { animation: none !important; transition: none !important; }'
});
```
3. **Non-deterministic Selectors**
```typescript
// Bad: Order-dependent
await page.locator('.user-card').first().click();
// Good: Specific identifier
await page.getByTestId('user-card-123').click();
```
4. **Timing Issues**
```typescript
// Use Playwright's auto-waiting instead of manual delays
// Bad
await page.click('button');
await page.waitForTimeout(3000); // Arbitrary delay
// Good
await page.click('button');
await page.waitForSelector('[data-testid="result"]');
// or
await expect(page.getByTestId('result')).toBeVisible();
```
### Debug Tools
```typescript
// Debug mode
await page.pause(); // Opens Playwright Inspector
// Slow down execution
test.use({ launchOptions: { slowMo: 100 } });
// Enable verbose logging
DEBUG=pw:api npx playwright test
// Trace viewer (after test runs with trace: 'on')
npx playwright show-trace trace.zip
```
### Configuration Best Practices
```typescript
// playwright.config.ts
export default defineConfig({
testDir: './tests',
fullyParallel: true,
forbidOnly: !!process.env.CI,
retries: process.env.CI ? 2 : 0,
workers: process.env.CI ? 1 : undefined,
reporter: [
['html'],
['json', { outputFile: 'test-results.json' }],
['junit', { outputFile: 'test-results.xml' }]
],
use: {
baseURL: process.env.BASE_URL || 'http://localhost:3000',
trace: 'retain-on-failure',
screenshot: 'only-on-failure',
video: 'retain-on-failure',
},
projects: [
{
name: 'chromium',
use: { ...devices['Desktop Chrome'] },
},
{
name: 'firefox',
use: { ...devices['Desktop Firefox'] },
},
{
name: 'webkit',
use: { ...devices['Desktop Safari'] },
},
// Mobile
{
name: 'Mobile Chrome',
use: { ...devices['Pixel 5'] },
},
],
webServer: {
command: 'npm run dev',
url: 'http://localhost:3000',
reuseExistingServer: !process.env.CI,
},
});
```
### CI/CD Integration
```yaml
# GitHub Actions example
name: Playwright Tests
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: 18
- name: Install dependencies
run: npm ci
- name: Install Playwright Browsers
run: npx playwright install --with-deps
- name: Run Playwright tests
run: npx playwright test
- uses: actions/upload-artifact@v3
if: always()
with:
name: playwright-report
path: playwright-report/
retention-days: 30
```
## Critical Rules
### Always Do
- Use auto-waiting features (don't add arbitrary timeouts)
- Prefer user-facing selectors (getByRole, getByLabel, etc.)
- Keep tests independent (no shared state between tests)
- Use Page Object Model for complex applications
- Add proper assertions (use expect with auto-retry)
- Enable traces and screenshots for debugging
- Run tests in parallel when possible
- Use fixtures for common setup
### Never Do
- Never use `waitForTimeout()` unless absolutely necessary
- Never rely on brittle CSS selectors (prefer data-testid or semantic selectors)
- Never share state between tests
- Never ignore flaky tests (fix them!)
- Never commit `.auth.json` or sensitive data
- Never use `first()`, `last()`, `nth()` without good reason (non-deterministic)
## Knowledge Base
- **Playwright API**: Expert in all Playwright APIs and features
- **Browser Automation**: Deep understanding of browser automation challenges
- **Test Patterns**: Page Object Model, fixtures, custom matchers
- **Debugging**: Proficient in debugging flaky tests and race conditions
- **CI/CD**: Experience integrating Playwright with various CI systems
- **Performance**: Understanding test optimization and parallelization
## Integration with Other Skills
- **Works with**: Test Master (overall testing strategy), React Expert (testing React apps)
- **Complements**: Frontend framework skills for framework-specific testing approaches
## Examples
### Example 1: E2E Test for User Registration
```typescript
import { test, expect } from '@playwright/test';
test.describe('User Registration', () => {
test('successful registration flow', async ({ page }) => {
await page.goto('/register');
// Fill form
await page.getByLabel('Email').fill('newuser@example.com');
await page.getByLabel('Password').fill('SecurePass123!');
await page.getByLabel('Confirm Password').fill('SecurePass123!');
await page.getByLabel(/I agree to the terms/).check();
// Submit and wait for navigation
await page.getByRole('button', { name: 'Sign Up' }).click();
// Verify success
await expect(page).toHaveURL(/dashboard/);
await expect(page.getByText('Welcome')).toBeVisible();
});
test('validates email format', async ({ page }) => {
await page.goto('/register');
await page.getByLabel('Email').fill('invalid-email');
await page.getByLabel('Password').fill('SecurePass123!');
await page.getByRole('button', { name: 'Sign Up' }).click();
await expect(page.getByText('Please enter a valid email')).toBeVisible();
await expect(page).toHaveURL(/register/);
});
});
```
### Example 2: Testing with API Mocking
```typescript
test('displays user list from API', async ({ page }) => {
// Mock the API response
await page.route('**/api/users', route => {
route.fulfill({
status: 200,
contentType: 'application/json',
body: JSON.stringify({
users: [
{ id: 1, name: 'Alice', email: 'alice@example.com' },
{ id: 2, name: 'Bob', email: 'bob@example.com' }
]
})
});
});
await page.goto('/users');
// Verify mocked data is displayed
await expect(page.getByText('Alice')).toBeVisible();
await expect(page.getByText('Bob')).toBeVisible();
});
```
## Best Practices Summary
1. **Selector Priority**: Role > Label > Placeholder > Test ID > CSS/XPath
2. **Waiting**: Use auto-waiting, avoid `waitForTimeout()`
3. **Independence**: Each test should run in isolation
4. **Patterns**: Use Page Object Model for maintainability
5. **Debugging**: Enable traces, screenshots, and videos on failure
6. **Performance**: Run tests in parallel, use sharding for large suites
7. **Stability**: Fix flaky tests immediately, don't retry indefinitely
8. **Assertions**: Use Playwright's expect with built-in retry logic
9. **Authentication**: Save and reuse auth state
10. **CI/CD**: Integrate early, run on every commit

559
skills/react-expert/SKILL.md Normal file
View File

@@ -0,0 +1,559 @@
---
name: React Expert
description: Expert in React for building modern web applications. Use when working with React, React hooks, state management (Redux, Zustand, Context), component architecture, performance optimization, or when the user mentions React, JSX, functional components, hooks, or frontend development.
---
# React Expert
A specialized skill for building production-ready React applications with modern patterns, hooks, performance optimization, and best practices.
## Instructions
### Core Workflow
1. **Understand requirements**
- Identify component needs and hierarchy
- Determine state management requirements (local, Context, Redux, Zustand)
- Understand performance requirements
- Identify routing needs (React Router)
2. **Project structure**
- Organize components logically
- Separate concerns (components, hooks, utils, types)
- Configure TypeScript for type safety
- Set up testing infrastructure
3. **Implement features**
- Create reusable components
- Implement custom hooks
- Manage state appropriately
- Optimize performance (memo, useMemo, useCallback)
- Handle side effects properly
4. **Testing and optimization**
- Write tests with React Testing Library
- Optimize bundle size
- Implement code splitting
- Profile and optimize performance
### React Project Structure
```
src/
├── components/
│ ├── common/ # Reusable components
│ │ ├── Button/
│ │ │ ├── Button.tsx
│ │ │ ├── Button.test.tsx
│ │ │ └── Button.module.css
│ │ └── Input/
│ ├── features/ # Feature-specific components
│ │ ├── auth/
│ │ └── dashboard/
│ └── layout/ # Layout components
│ ├── Header.tsx
│ └── Footer.tsx
├── hooks/ # Custom hooks
│ ├── useAuth.ts
│ ├── useApi.ts
│ └── useLocalStorage.ts
├── contexts/ # Context providers
│ └── AuthContext.tsx
├── store/ # State management (Redux/Zustand)
│ ├── slices/
│ └── store.ts
├── services/ # API services
│ └── api.ts
├── utils/ # Utility functions
│ └── format.ts
├── types/ # TypeScript types
│ └── index.ts
├── pages/ # Page components (if using routing)
│ ├── Home.tsx
│ └── Dashboard.tsx
└── App.tsx
```
### Modern Component Patterns
```typescript
// Functional component with TypeScript
import { FC, useState, useEffect, useMemo, useCallback } from 'react';
interface User {
id: number;
name: string;
email: string;
}
interface UserListProps {
initialUsers?: User[];
onUserSelect?: (user: User) => void;
}
export const UserList: FC<UserListProps> = ({
initialUsers = [],
onUserSelect
}) => {
const [users, setUsers] = useState<User[]>(initialUsers);
const [searchTerm, setSearchTerm] = useState('');
const [loading, setLoading] = useState(false);
// Fetch users on mount
useEffect(() => {
const fetchUsers = async () => {
setLoading(true);
try {
const response = await fetch('/api/users');
const data = await response.json();
setUsers(data);
} catch (error) {
console.error('Failed to fetch users:', error);
} finally {
setLoading(false);
}
};
if (initialUsers.length === 0) {
fetchUsers();
}
}, [initialUsers.length]);
// Memoized filtered users
const filteredUsers = useMemo(() => {
return users.filter(user =>
user.name.toLowerCase().includes(searchTerm.toLowerCase()) ||
user.email.toLowerCase().includes(searchTerm.toLowerCase())
);
}, [users, searchTerm]);
// Memoized callback
const handleUserClick = useCallback((user: User) => {
onUserSelect?.(user);
}, [onUserSelect]);
if (loading) {
return <div>Loading...</div>;
}
return (
<div>
<input
type="text"
placeholder="Search users..."
value={searchTerm}
onChange={(e) => setSearchTerm(e.target.value)}
/>
<ul>
{filteredUsers.map(user => (
<li key={user.id} onClick={() => handleUserClick(user)}>
{user.name} - {user.email}
</li>
))}
</ul>
</div>
);
};
```
### Custom Hooks
```typescript
// useApi.ts - Generic API hook
import { useState, useEffect } from 'react';
interface UseApiOptions<T> {
url: string;
method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
body?: any;
dependencies?: any[];
}
interface UseApiReturn<T> {
data: T | null;
loading: boolean;
error: Error | null;
refetch: () => Promise<void>;
}
export function useApi<T = any>({
url,
method = 'GET',
body,
dependencies = []
}: UseApiOptions<T>): UseApiReturn<T> {
const [data, setData] = useState<T | null>(null);
const [loading, setLoading] = useState(true);
const [error, setError] = useState<Error | null>(null);
const fetchData = async () => {
setLoading(true);
setError(null);
try {
const response = await fetch(url, {
method,
headers: {
'Content-Type': 'application/json',
},
body: body ? JSON.stringify(body) : undefined,
});
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const result = await response.json();
setData(result);
} catch (err) {
setError(err as Error);
} finally {
setLoading(false);
}
};
useEffect(() => {
fetchData();
}, dependencies);
return { data, loading, error, refetch: fetchData };
}
// useLocalStorage.ts
import { useState, useEffect } from 'react';
export function useLocalStorage<T>(key: string, initialValue: T) {
const [storedValue, setStoredValue] = useState<T>(() => {
try {
const item = window.localStorage.getItem(key);
return item ? JSON.parse(item) : initialValue;
} catch (error) {
console.error(error);
return initialValue;
}
});
const setValue = (value: T | ((val: T) => T)) => {
try {
const valueToStore = value instanceof Function ? value(storedValue) : value;
setStoredValue(valueToStore);
window.localStorage.setItem(key, JSON.stringify(valueToStore));
} catch (error) {
console.error(error);
}
};
return [storedValue, setValue] as const;
}
// useDebounce.ts
import { useState, useEffect } from 'react';
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;
}
```
### Context API for State Management
```typescript
// AuthContext.tsx
import { createContext, useContext, useState, useEffect, ReactNode } from 'react';
interface User {
id: number;
name: string;
email: string;
}
interface AuthContextType {
user: User | null;
loading: boolean;
login: (email: string, password: string) => Promise<void>;
logout: () => void;
isAuthenticated: boolean;
}
const AuthContext = createContext<AuthContextType | undefined>(undefined);
export const AuthProvider = ({ children }: { children: ReactNode }) => {
const [user, setUser] = useState<User | null>(null);
const [loading, setLoading] = useState(true);
useEffect(() => {
// Check for existing session
const checkAuth = async () => {
try {
const response = await fetch('/api/auth/me');
if (response.ok) {
const userData = await response.json();
setUser(userData);
}
} catch (error) {
console.error('Auth check failed:', error);
} finally {
setLoading(false);
}
};
checkAuth();
}, []);
const login = async (email: string, password: string) => {
const response = await fetch('/api/auth/login', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ email, password }),
});
if (!response.ok) {
throw new Error('Login failed');
}
const userData = await response.json();
setUser(userData);
};
const logout = () => {
fetch('/api/auth/logout', { method: 'POST' });
setUser(null);
};
return (
<AuthContext.Provider value={{
user,
loading,
login,
logout,
isAuthenticated: !!user,
}}>
{children}
</AuthContext.Provider>
);
};
export const useAuth = () => {
const context = useContext(AuthContext);
if (!context) {
throw new Error('useAuth must be used within AuthProvider');
}
return context;
};
```
### Performance Optimization
```typescript
import { memo, useMemo, useCallback } from 'react';
// Memoized component (only re-renders if props change)
export const ExpensiveComponent = memo(({ data }: { data: any[] }) => {
return (
<div>
{data.map(item => (
<div key={item.id}>{item.name}</div>
))}
</div>
);
});
// Parent component
export const ParentComponent = () => {
const [count, setCount] = useState(0);
const [users, setUsers] = useState([]);
// Memoize expensive calculations
const sortedUsers = useMemo(() => {
return [...users].sort((a, b) => a.name.localeCompare(b.name));
}, [users]);
// Memoize callbacks to prevent child re-renders
const handleUserAdd = useCallback((user) => {
setUsers(prev => [...prev, user]);
}, []);
return (
<div>
<button onClick={() => setCount(count + 1)}>Count: {count}</button>
{/* ExpensiveComponent won't re-render when count changes */}
<ExpensiveComponent data={sortedUsers} />
</div>
);
};
```
### Form Handling with React Hook Form
```typescript
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import * as z from 'zod';
const schema = z.object({
email: z.string().email('Invalid email'),
password: z.string().min(8, 'Password must be at least 8 characters'),
confirmPassword: z.string(),
}).refine((data) => data.password === data.confirmPassword, {
message: "Passwords don't match",
path: ["confirmPassword"],
});
type FormData = z.infer<typeof schema>;
export const RegisterForm = () => {
const {
register,
handleSubmit,
formState: { errors, isSubmitting },
} = useForm<FormData>({
resolver: zodResolver(schema),
});
const onSubmit = async (data: FormData) => {
try {
await fetch('/api/register', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(data),
});
} catch (error) {
console.error('Registration failed:', error);
}
};
return (
<form onSubmit={handleSubmit(onSubmit)}>
<div>
<input {...register('email')} placeholder="Email" />
{errors.email && <span>{errors.email.message}</span>}
</div>
<div>
<input {...register('password')} type="password" placeholder="Password" />
{errors.password && <span>{errors.password.message}</span>}
</div>
<div>
<input {...register('confirmPassword')} type="password" placeholder="Confirm Password" />
{errors.confirmPassword && <span>{errors.confirmPassword.message}</span>}
</div>
<button type="submit" disabled={isSubmitting}>
{isSubmitting ? 'Submitting...' : 'Register'}
</button>
</form>
);
};
```
### Testing with React Testing Library
```typescript
import { render, screen, fireEvent, waitFor } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { UserList } from './UserList';
describe('UserList', () => {
const mockUsers = [
{ id: 1, name: 'John Doe', email: 'john@example.com' },
{ id: 2, name: 'Jane Smith', email: 'jane@example.com' },
];
it('renders users', () => {
render(<UserList initialUsers={mockUsers} />);
expect(screen.getByText('John Doe - john@example.com')).toBeInTheDocument();
expect(screen.getByText('Jane Smith - jane@example.com')).toBeInTheDocument();
});
it('filters users by search term', async () => {
render(<UserList initialUsers={mockUsers} />);
const searchInput = screen.getByPlaceholderText('Search users...');
await userEvent.type(searchInput, 'John');
expect(screen.getByText('John Doe - john@example.com')).toBeInTheDocument();
expect(screen.queryByText('Jane Smith - jane@example.com')).not.toBeInTheDocument();
});
it('calls onUserSelect when user is clicked', async () => {
const onUserSelect = jest.fn();
render(<UserList initialUsers={mockUsers} onUserSelect={onUserSelect} />);
const firstUser = screen.getByText('John Doe - john@example.com');
fireEvent.click(firstUser);
expect(onUserSelect).toHaveBeenCalledWith(mockUsers[0]);
});
it('shows loading state', () => {
render(<UserList />);
expect(screen.getByText('Loading...')).toBeInTheDocument();
});
});
```
## Critical Rules
### Always Do
- Use TypeScript for type safety
- Implement proper error boundaries
- Memoize expensive calculations with useMemo
- Memoize callbacks with useCallback when passing to child components
- Use React.memo for components that render often with same props
- Keep components small and focused
- Extract reusable logic into custom hooks
- Write tests for components
- Use proper key props in lists
- Handle loading and error states
### Never Do
- Never mutate state directly
- Never use index as key in dynamic lists
- Never forget cleanup in useEffect
- Never create functions inside JSX (causes re-renders)
- Never ignore ESLint warnings
- Never use inline styles for everything (use CSS modules or styled-components)
- Never skip error boundaries
- Never ignore accessibility (use semantic HTML, ARIA labels)
## Knowledge Base
- **React Core**: Hooks, Context, Suspense, Error Boundaries
- **State Management**: Redux, Zustand, Jotai, Context API
- **Routing**: React Router, TanStack Router
- **Forms**: React Hook Form, Formik
- **Testing**: React Testing Library, Jest
- **Styling**: CSS Modules, Styled Components, Tailwind CSS
- **Performance**: Code splitting, lazy loading, memoization
- **TypeScript**: Type safety, generics, utility types
## Integration with Other Skills
- **Works with**: Fullstack Guardian, Playwright Expert, Test Master
- **Complements**: React Native Expert (mobile), Code Reviewer
## Best Practices Summary
1. **TypeScript**: Use for all components and hooks
2. **Hooks**: Prefer functional components with hooks
3. **Custom Hooks**: Extract reusable logic
4. **Performance**: Memo, useMemo, useCallback where needed
5. **Testing**: Comprehensive tests with React Testing Library
6. **Accessibility**: Semantic HTML, ARIA labels, keyboard navigation
7. **Code Splitting**: Lazy load routes and heavy components
8. **Error Handling**: Error boundaries for graceful degradation
9. **State Management**: Choose appropriate solution for complexity
10. **Clean Code**: Small, focused, well-named components

442
skills/react-native-expert/SKILL.md Normal file
View File

@@ -0,0 +1,442 @@
---
name: React Native Expert
description: Expert in React Native for building cross-platform mobile applications. Use when working with React Native, Expo, mobile development, native modules, navigation, or when the user mentions React Native, mobile apps, iOS, Android, Expo, or cross-platform development.
---
# React Native Expert
A specialized skill for building production-ready cross-platform mobile applications with React Native and Expo.
## Instructions
### Core Workflow
1. **Understand requirements**
- Identify if using Expo or bare React Native
- Determine platform-specific needs (iOS/Android)
- Understand navigation requirements
- Identify native module needs
2. **Project setup**
- Choose between Expo and bare React Native
- Set up navigation (React Navigation)
- Configure TypeScript
- Set up state management
3. **Implement features**
- Create reusable components
- Implement platform-specific code when needed
- Handle device capabilities (camera, location, etc.)
- Optimize performance for mobile
4. **Testing and deployment**
- Test on both iOS and Android
- Optimize app size and performance
- Configure app deployment (App Store, Google Play)
### React Native Project Structure (Expo)
```
myapp/
├── app/ # App directory (Expo Router)
│ ├── (tabs)/
│ │ ├── index.tsx
│ │ └── profile.tsx
│ ├── _layout.tsx
│ └── +not-found.tsx
├── components/
│ ├── common/
│ └── features/
├── hooks/
│ ├── useAuth.ts
│ └── useAsync.ts
├── services/
│ └── api.ts
├── constants/
│ ├── Colors.ts
│ └── Layout.ts
├── utils/
│ └── storage.ts
├── types/
│ └── index.ts
├── app.json
└── package.json
```
### Component Patterns
```typescript
import { View, Text, StyleSheet, Platform, Pressable } from 'react-native';
import { FC } from 'react';
interface ButtonProps {
title: string;
onPress: () => void;
variant?: 'primary' | 'secondary';
disabled?: boolean;
}
export const Button: FC<ButtonProps> = ({
title,
onPress,
variant = 'primary',
disabled = false,
}) => {
return (
<Pressable
onPress={onPress}
disabled={disabled}
style={({ pressed }) => [
styles.button,
variant === 'primary' ? styles.primaryButton : styles.secondaryButton,
pressed && styles.pressed,
disabled && styles.disabled,
]}
>
<Text style={[
styles.text,
variant === 'primary' ? styles.primaryText : styles.secondaryText
]}>
{title}
</Text>
</Pressable>
);
};
const styles = StyleSheet.create({
button: {
paddingVertical: 12,
paddingHorizontal: 24,
borderRadius: 8,
alignItems: 'center',
justifyContent: 'center',
...Platform.select({
ios: {
shadowColor: '#000',
shadowOffset: { width: 0, height: 2 },
shadowOpacity: 0.25,
shadowRadius: 3.84,
},
android: {
elevation: 5,
},
}),
},
primaryButton: {
backgroundColor: '#007AFF',
},
secondaryButton: {
backgroundColor: '#E5E5EA',
},
pressed: {
opacity: 0.7,
},
disabled: {
opacity: 0.5,
},
text: {
fontSize: 16,
fontWeight: '600',
},
primaryText: {
color: '#FFFFFF',
},
secondaryText: {
color: '#000000',
},
});
```
### Navigation (React Navigation)
```typescript
// app/_layout.tsx (Expo Router)
import { Stack } from 'expo-router';
export default function RootLayout() {
return (
<Stack>
<Stack.Screen name="(tabs)" options={{ headerShown: false }} />
<Stack.Screen name="details/[id]" options={{ title: 'Details' }} />
</Stack>
);
}
// Or with React Navigation
import { NavigationContainer } from '@react-navigation/native';
import { createNativeStackNavigator } from '@react-navigation/native-stack';
type RootStackParamList = {
Home: undefined;
Profile: { userId: string };
Details: { itemId: number };
};
const Stack = createNativeStackNavigator<RootStackParamList>();
export default function App() {
return (
<NavigationContainer>
<Stack.Navigator>
<Stack.Screen name="Home" component={HomeScreen} />
<Stack.Screen name="Profile" component={ProfileScreen} />
<Stack.Screen name="Details" component={DetailsScreen} />
</Stack.Navigator>
</NavigationContainer>
);
}
// Type-safe navigation
import { NativeStackNavigationProp } from '@react-navigation/native-stack';
import { useNavigation } from '@react-navigation/native';
type ProfileScreenNavigationProp = NativeStackNavigationProp<
RootStackParamList,
'Profile'
>;
const ProfileScreen = () => {
const navigation = useNavigation<ProfileScreenNavigationProp>();
const handlePress = () => {
navigation.navigate('Details', { itemId: 42 });
};
return <Button title="Go to Details" onPress={handlePress} />;
};
```
### Platform-Specific Code
```typescript
import { Platform, StyleSheet } from 'react-native';
// Platform check
if (Platform.OS === 'ios') {
// iOS-specific code
} else if (Platform.OS === 'android') {
// Android-specific code
}
// Platform.select
const styles = StyleSheet.create({
container: {
...Platform.select({
ios: {
shadowColor: '#000',
shadowOffset: { width: 0, height: 2 },
shadowOpacity: 0.25,
shadowRadius: 3.84,
},
android: {
elevation: 5,
},
}),
},
});
// Platform-specific files
// Component.ios.tsx
// Component.android.tsx
import Component from './Component'; // Automatically picks correct file
```
### Custom Hooks for Mobile
```typescript
// hooks/useKeyboard.ts
import { useEffect, useState } from 'react';
import { Keyboard, KeyboardEvent } from 'react-native';
export const useKeyboard = () => {
const [keyboardHeight, setKeyboardHeight] = useState(0);
const [isKeyboardVisible, setIsKeyboardVisible] = useState(false);
useEffect(() => {
const showSubscription = Keyboard.addListener(
'keyboardDidShow',
(e: KeyboardEvent) => {
setKeyboardHeight(e.endCoordinates.height);
setIsKeyboardVisible(true);
}
);
const hideSubscription = Keyboard.addListener(
'keyboardDidHide',
() => {
setKeyboardHeight(0);
setIsKeyboardVisible(false);
}
);
return () => {
showSubscription.remove();
hideSubscription.remove();
};
}, []);
return { keyboardHeight, isKeyboardVisible };
};
// hooks/useAppState.ts
import { useEffect, useState, useRef } from 'react';
import { AppState, AppStateStatus } from 'react-native';
export const useAppState = (onChange?: (status: AppStateStatus) => void) => {
const appState = useRef(AppState.currentState);
const [appStateVisible, setAppStateVisible] = useState(appState.current);
useEffect(() => {
const subscription = AppState.addEventListener('change', nextAppState => {
appState.current = nextAppState;
setAppStateVisible(nextAppState);
onChange?.(nextAppState);
});
return () => subscription.remove();
}, [onChange]);
return appStateVisible;
};
```
### Async Storage
```typescript
import AsyncStorage from '@react-native-async-storage/async-storage';
export const storage = {
async getItem<T>(key: string): Promise<T | null> {
try {
const item = await AsyncStorage.getItem(key);
return item ? JSON.parse(item) : null;
} catch (error) {
console.error('Error getting item:', error);
return null;
}
},
async setItem<T>(key: string, value: T): Promise<void> {
try {
await AsyncStorage.setItem(key, JSON.stringify(value));
} catch (error) {
console.error('Error setting item:', error);
}
},
async removeItem(key: string): Promise<void> {
try {
await AsyncStorage.removeItem(key);
} catch (error) {
console.error('Error removing item:', error);
}
},
async clear(): Promise<void> {
try {
await AsyncStorage.clear();
} catch (error) {
console.error('Error clearing storage:', error);
}
},
};
```
### Performance Optimization
```typescript
import { memo, useMemo, useCallback } from 'react';
import { FlatList } from 'react-native';
// Memoized list item
const ListItem = memo(({ item, onPress }: { item: any; onPress: (id: string) => void }) => {
const handlePress = useCallback(() => {
onPress(item.id);
}, [item.id, onPress]);
return (
<Pressable onPress={handlePress}>
<Text>{item.name}</Text>
</Pressable>
);
});
// Optimized FlatList
export const OptimizedList = ({ data }: { data: any[] }) => {
const keyExtractor = useCallback((item: any) => item.id.toString(), []);
const renderItem = useCallback(({ item }: { item: any }) => (
<ListItem item={item} onPress={handleItemPress} />
), []);
const handleItemPress = useCallback((id: string) => {
console.log('Item pressed:', id);
}, []);
return (
<FlatList
data={data}
renderItem={renderItem}
keyExtractor={keyExtractor}
removeClippedSubviews={true}
maxToRenderPerBatch={10}
updateCellsBatchingPeriod={50}
initialNumToRender={10}
windowSize={5}
/>
);
};
```
## Critical Rules
### Always Do
- Use FlatList/SectionList for long lists (not ScrollView)
- Implement proper key extractors
- Use memo/useCallback for list items
- Handle keyboard properly (KeyboardAvoidingView)
- Test on both iOS and Android
- Use SafeAreaView for notch support
- Implement proper loading and error states
- Handle offline scenarios
- Optimize images (use appropriate sizes)
- Use Platform-specific code when needed
### Never Do
- Never use ScrollView for long lists
- Never forget to handle Android back button
- Never ignore platform differences
- Never skip performance profiling
- Never hardcode dimensions (use Dimensions API)
- Never forget to test on real devices
- Never ignore memory leaks
- Never use inline styles extensively (hurts performance)
## Knowledge Base
- **React Native Core**: Components, APIs, Platform-specific code
- **Navigation**: React Navigation, Expo Router
- **State Management**: Redux, Zustand, Context API
- **Storage**: AsyncStorage, MMKV, SecureStore
- **Networking**: fetch, axios, React Query
- **Native Modules**: Creating custom native modules
- **Performance**: FlatList optimization, Reanimated
- **Expo**: Managed workflow, EAS Build, OTA updates
## Integration with Other Skills
- **Works with**: React Expert, Fullstack Guardian, Test Master
- **Complements**: Flutter Expert (alternative mobile framework)
## Best Practices Summary
1. **Performance**: FlatList, memo, useCallback for lists
2. **Platform**: Handle iOS/Android differences
3. **Navigation**: Type-safe navigation
4. **Storage**: AsyncStorage for persistence
5. **Images**: Optimize and cache properly
6. **Keyboard**: Handle keyboard events
7. **Testing**: Test on real devices
8. **Offline**: Handle network failures
9. **Accessibility**: Support screen readers
10. **Updates**: Use OTA updates (Expo)

388
skills/secure-code-guardian/SKILL.md Normal file
View File

@@ -0,0 +1,388 @@
---
name: Secure Code Guardian
description: Expert in writing secure code and preventing vulnerabilities. Use when implementing security features, writing authentication/authorization, handling sensitive data, preventing common vulnerabilities (OWASP Top 10), or when the user mentions secure coding, security, authentication, authorization, or vulnerabilities.
---
# Secure Code Guardian
Expert in writing secure code and implementing security best practices to prevent vulnerabilities.
## Instructions
### Core Workflow
1. **Understand security requirements**
- Authentication needs
- Authorization requirements
- Data sensitivity levels
- Compliance requirements (GDPR, HIPAA, etc.)
- Threat model
2. **Implement security controls**
- Input validation
- Output encoding
- Authentication mechanisms
- Authorization checks
- Encryption (at rest and in transit)
- Secure session management
3. **Prevent OWASP Top 10**
- Injection attacks
- Broken authentication
- Sensitive data exposure
- XML External Entities (XXE)
- Broken access control
- Security misconfiguration
- Cross-Site Scripting (XSS)
- Insecure deserialization
- Using components with known vulnerabilities
- Insufficient logging & monitoring
4. **Secure development practices**
- Principle of least privilege
- Defense in depth
- Fail securely
- Keep security simple
- Don't trust user input
### OWASP Top 10 Prevention
#### 1. SQL Injection Prevention
```typescript
// ❌ Vulnerable to SQL injection
const query = `SELECT * FROM users WHERE email = '${userEmail}'`;
db.query(query);
// ✅ Use parameterized queries
const query = 'SELECT * FROM users WHERE email = $1';
db.query(query, [userEmail]);
// ✅ Or use an ORM
const user = await User.findOne({ where: { email: userEmail } });
```
#### 2. Authentication Best Practices
```typescript
import bcrypt from 'bcrypt';
// Password hashing
async function hashPassword(password: string): Promise<string> {
const saltRounds = 12; // Minimum 10
return await bcrypt.hash(password, saltRounds);
}
// Password verification
async function verifyPassword(password: string, hash: string): Promise<boolean> {
return await bcrypt.compare(password, hash);
}
// Strong password requirements
function isStrongPassword(password: string): boolean {
const minLength = 12;
const hasUpperCase = /[A-Z]/.test(password);
const hasLowerCase = /[a-z]/.test(password);
const hasNumbers = /\d/.test(password);
const hasSpecialChar = /[!@#$%^&*]/.test(password);
return password.length >= minLength &&
hasUpperCase &&
hasLowerCase &&
hasNumbers &&
hasSpecialChar;
}
// Rate limiting for login attempts
const loginAttempts = new Map<string, { count: number; resetTime: number }>();
function checkRateLimit(ip: string): boolean {
const now = Date.now();
const attempts = loginAttempts.get(ip);
if (!attempts || now > attempts.resetTime) {
loginAttempts.set(ip, { count: 1, resetTime: now + 15 * 60 * 1000 }); // 15 min
return true;
}
if (attempts.count >= 5) {
return false; // Too many attempts
}
attempts.count++;
return true;
}
```
#### 3. XSS Prevention
```typescript
// ❌ Vulnerable to XSS
element.innerHTML = userInput;
// ✅ Use textContent or sanitize
element.textContent = userInput;
// Or use a sanitization library
import DOMPurify from 'dompurify';
element.innerHTML = DOMPurify.sanitize(userInput);
// React automatically escapes
<div>{userInput}</div> // Safe
// Backend: Set Content-Security-Policy header
app.use((req, res, next) => {
res.setHeader(
'Content-Security-Policy',
"default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'"
);
next();
});
```
#### 4. CSRF Prevention
```typescript
// Use CSRF tokens
import csrf from 'csurf';
app.use(csrf({ cookie: true }));
app.get('/form', (req, res) => {
res.render('form', { csrfToken: req.csrfToken() });
});
// In form
// <input type="hidden" name="_csrf" value="{{ csrfToken }}">
// For APIs: Use custom headers
// X-CSRF-Token: <token>
```
#### 5. Authorization Best Practices
```typescript
// Role-Based Access Control (RBAC)
enum Role {
USER = 'user',
ADMIN = 'admin',
MODERATOR = 'moderator',
}
interface User {
id: string;
role: Role;
}
function requireRole(allowedRoles: Role[]) {
return (req, res, next) => {
const user: User = req.user;
if (!user) {
return res.status(401).json({ error: 'Not authenticated' });
}
if (!allowedRoles.includes(user.role)) {
return res.status(403).json({ error: 'Insufficient permissions' });
}
next();
};
}
// Usage
app.delete('/users/:id', requireRole([Role.ADMIN]), deleteUser);
// Resource-based authorization
async function canAccessResource(userId: string, resourceId: string): Promise<boolean> {
const resource = await Resource.findById(resourceId);
return resource.ownerId === userId || await isAdmin(userId);
}
app.get('/resource/:id', async (req, res) => {
if (!await canAccessResource(req.user.id, req.params.id)) {
return res.status(403).json({ error: 'Access denied' });
}
// Return resource
});
```
#### 6. Sensitive Data Handling
```typescript
// Environment variables for secrets
const JWT_SECRET = process.env.JWT_SECRET;
const DB_PASSWORD = process.env.DB_PASSWORD;
// Never log sensitive data
// ❌ Don't do this
console.log('User:', user); // May contain password hash
// ✅ Log safely
console.log('User:', { id: user.id, email: user.email });
// Encrypt sensitive data at rest
import crypto from 'crypto';
const algorithm = 'aes-256-gcm';
const key = Buffer.from(process.env.ENCRYPTION_KEY, 'hex');
function encrypt(text: string): { encrypted: string; iv: string; tag: string } {
const iv = crypto.randomBytes(16);
const cipher = crypto.createCipheriv(algorithm, key, iv);
let encrypted = cipher.update(text, 'utf8', 'hex');
encrypted += cipher.final('hex');
return {
encrypted,
iv: iv.toString('hex'),
tag: cipher.getAuthTag().toString('hex'),
};
}
function decrypt(encrypted: string, iv: string, tag: string): string {
const decipher = crypto.createDecipheriv(
algorithm,
key,
Buffer.from(iv, 'hex')
);
decipher.setAuthTag(Buffer.from(tag, 'hex'));
let decrypted = decipher.update(encrypted, 'hex', 'utf8');
decrypted += decipher.final('utf8');
return decrypted;
}
```
#### 7. Security Headers
```typescript
import helmet from 'helmet';
app.use(helmet()); // Sets various security headers
// Or manually:
app.use((req, res, next) => {
res.setHeader('X-Content-Type-Options', 'nosniff');
res.setHeader('X-Frame-Options', 'DENY');
res.setHeader('X-XSS-Protection', '1; mode=block');
res.setHeader('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
next();
});
```
### Input Validation
```typescript
import { z } from 'zod';
// Define schema
const userSchema = z.object({
email: z.string().email(),
password: z.string().min(12),
age: z.number().int().positive().max(150),
website: z.string().url().optional(),
});
// Validate input
function validateUser(data: unknown) {
try {
return userSchema.parse(data);
} catch (error) {
if (error instanceof z.ZodError) {
throw new ValidationError(error.errors);
}
throw error;
}
}
// Sanitize strings
function sanitizeString(input: string): string {
return input
.trim()
.replace(/[<>]/g, '') // Remove < and >
.substring(0, 1000); // Limit length
}
```
### Secure Session Management
```typescript
import session from 'express-session';
import RedisStore from 'connect-redis';
app.use(session({
store: new RedisStore({ client: redisClient }),
secret: process.env.SESSION_SECRET,
resave: false,
saveUninitialized: false,
cookie: {
secure: true, // HTTPS only
httpOnly: true, // No JavaScript access
maxAge: 1000 * 60 * 60 * 24, // 1 day
sameSite: 'strict', // CSRF protection
},
}));
// Regenerate session ID after login
app.post('/login', async (req, res) => {
const user = await authenticateUser(req.body);
req.session.regenerate((err) => {
if (err) {
return res.status(500).json({ error: 'Session error' });
}
req.session.userId = user.id;
res.json({ success: true });
});
});
```
## Critical Rules
### Always Do
- Validate all input
- Use parameterized queries
- Hash passwords with bcrypt/argon2
- Use HTTPS in production
- Implement rate limiting
- Set security headers
- Use least privilege principle
- Encrypt sensitive data
- Log security events
- Keep dependencies updated
### Never Do
- Never trust user input
- Never store passwords in plain text
- Never log sensitive data
- Never use weak encryption (MD5, SHA1 for passwords)
- Never expose stack traces to users
- Never disable security features "temporarily"
- Never hardcode secrets
- Never use predictable IDs for sensitive resources
- Never trust client-side validation alone
## Knowledge Base
- **OWASP Top 10**: Common web vulnerabilities
- **Cryptography**: Hashing, encryption, signing
- **Authentication**: JWT, OAuth, session management
- **Authorization**: RBAC, ABAC, resource-based
- **Standards**: OWASP, NIST, PCI DSS
## Best Practices Summary
1. **Input Validation**: Never trust user input
2. **Authentication**: Strong passwords, MFA, rate limiting
3. **Authorization**: Verify every request
4. **Encryption**: Sensitive data at rest and in transit
5. **Sessions**: Secure configuration
6. **Headers**: Set all security headers
7. **Dependencies**: Keep updated
8. **Logging**: Log security events
9. **Principle of Least Privilege**: Minimum necessary permissions
10. **Defense in Depth**: Multiple layers of security

281
skills/security-reviewer/SKILL.md Normal file
View File

@@ -0,0 +1,281 @@
---
name: Security Reviewer
description: Expert in security code review and static analysis to identify vulnerabilities. Use when performing security reviews, analyzing code for vulnerabilities, using SAST tools, checking for security issues, or when the user mentions security review, vulnerability scan, SAST, or security analysis.
allowed-tools: Read, Grep, Glob, Bash
---
# Security Reviewer
Expert in identifying security vulnerabilities through code review and static analysis.
## Instructions
### Core Workflow
1. **Prepare for review**
- Understand the application
- Identify attack surface
- Review threat model
- Set up SAST tools
2. **Perform analysis**
- Manual code review
- Run SAST tools
- Check dependencies for vulnerabilities
- Review configuration files
- Check for secrets in code
3. **Categorize findings**
- **Critical**: Immediate security risk
- **High**: Significant vulnerability
- **Medium**: Moderate risk
- **Low**: Minor issue
- **Info**: Security improvement
4. **Report findings**
- Document each vulnerability
- Provide proof of concept
- Suggest remediation
- Estimate effort to fix
### Security Review Checklist
#### Authentication & Authorization
- [ ] Strong password requirements?
- [ ] Password hashing with strong algorithm (bcrypt, argon2)?
- [ ] Rate limiting on auth endpoints?
- [ ] MFA available?
- [ ] Session management secure?
- [ ] Authorization checks on all endpoints?
- [ ] JWT tokens validated properly?
#### Input Validation
- [ ] All user input validated?
- [ ] Input sanitized before use?
- [ ] File uploads restricted and validated?
- [ ] SQL injection prevented (parameterized queries)?
- [ ] XSS prevented (output encoding)?
- [ ] Command injection prevented?
#### Data Protection
- [ ] Sensitive data encrypted at rest?
- [ ] HTTPS enforced?
- [ ] Secrets not in code?
- [ ] PII handled according to regulations?
- [ ] Logging doesn't include sensitive data?
#### Configuration
- [ ] Security headers set?
- [ ] CORS configured properly?
- [ ] Debug mode off in production?
- [ ] Error messages don't expose sensitive info?
- [ ] Default credentials changed?
#### Dependencies
- [ ] Dependencies up to date?
- [ ] No known vulnerable dependencies?
- [ ] Dependency scanning in CI/CD?
### SAST Tools
#### JavaScript/TypeScript
```bash
# ESLint with security plugin
npm install --save-dev eslint-plugin-security
# .eslintrc.json
{
"plugins": ["security"],
"extends": ["plugin:security/recommended"]
}
# Semgrep
semgrep --config=auto .
# npm audit
npm audit
npm audit fix
```
#### Python
```bash
# Bandit
pip install bandit
bandit -r . -f json -o security-report.json
# Safety (dependency checking)
pip install safety
safety check
# Semgrep
semgrep --config=auto .
```
#### Go
```bash
# Gosec
go install github.com/securego/gosec/v2/cmd/gosec@latest
gosec ./...
# Go modules vulnerability check
go list -json -m all | nancy sleuth
```
### Secret Scanning
```bash
# TruffleHog
trufflehog git https://github.com/your/repo --json
# gitleaks
gitleaks detect --source . --verbose
# Check for common patterns
grep -r "api_key" .
grep -r "password.*=" .
grep -r "secret.*=" .
```
### Common Vulnerability Patterns
#### SQL Injection
```typescript
// ❌ Vulnerable
const query = `SELECT * FROM users WHERE id = ${userId}`;
// ✅ Secure
const query = 'SELECT * FROM users WHERE id = $1';
db.query(query, [userId]);
```
#### Command Injection
```typescript
// ❌ Vulnerable
const { exec } = require('child_process');
exec(`ping ${userInput}`);
// ✅ Secure (validate and sanitize)
const { execFile } = require('child_process');
if (!/^[\d.]+$/.test(userInput)) {
throw new Error('Invalid IP');
}
execFile('ping', ['-c', '4', userInput]);
```
#### Path Traversal
```typescript
// ❌ Vulnerable
app.get('/file', (req, res) => {
const filePath = path.join(__dirname, 'files', req.query.name);
res.sendFile(filePath);
});
// ✅ Secure
app.get('/file', (req, res) => {
const fileName = path.basename(req.query.name);
const filePath = path.join(__dirname, 'files', fileName);
// Verify file is within allowed directory
if (!filePath.startsWith(path.join(__dirname, 'files'))) {
return res.status(403).send('Access denied');
}
res.sendFile(filePath);
});
```
#### Insecure Deserialization
```typescript
// ❌ Vulnerable
const userData = JSON.parse(req.body.data);
// ✅ Secure (validate)
const userSchema = z.object({
name: z.string(),
email: z.string().email(),
});
try {
const userData = userSchema.parse(JSON.parse(req.body.data));
} catch (error) {
return res.status(400).json({ error: 'Invalid data' });
}
```
### Security Report Template
```markdown
# Security Review Report
## Executive Summary
- Total vulnerabilities found: X
- Critical: X, High: X, Medium: X, Low: X
- Overall risk level: [Critical/High/Medium/Low]
## Findings
### [CRITICAL] SQL Injection in User Search
**Location**: `src/api/users.ts:45`
**Description**: User input is directly concatenated into SQL query
**Impact**: Attacker can extract all database data
**Proof of Concept**:
```
GET /api/users?search=' OR '1'='1
```
**Remediation**: Use parameterized queries
**Effort**: 2 hours
### [HIGH] Weak Password Requirements
**Location**: `src/auth/validation.ts:12`
**Description**: Passwords only require 6 characters
**Impact**: Easy to brute force
**Remediation**: Require minimum 12 characters with complexity
**Effort**: 1 hour
## Recommendations
1. Implement automated SAST in CI/CD
2. Add dependency vulnerability scanning
3. Conduct security training for developers
4. Establish secure code review process
```
## Critical Rules
### Always Do
- Use multiple SAST tools
- Manual review critical paths
- Check for secrets in code
- Scan dependencies
- Verify authentication/authorization
- Test input validation
- Review security configurations
- Document all findings
- Provide remediation guidance
### Never Do
- Never skip manual review
- Never ignore "low" severity issues
- Never assume frameworks handle everything
- Never forget to check dependencies
- Never skip configuration review
- Never test on production
## Knowledge Base
- **OWASP Top 10**: Common vulnerabilities
- **CWE**: Common Weakness Enumeration
- **SAST Tools**: Semgrep, Bandit, ESLint Security, Gosec
- **Dependency Scanning**: npm audit, Safety, Snyk
- **Secret Scanning**: TruffleHog, gitleaks
## Best Practices Summary
1. **Automated**: Use SAST tools
2. **Manual**: Review critical code paths
3. **Dependencies**: Scan for vulnerabilities
4. **Secrets**: Check for exposed secrets
5. **Configuration**: Review security settings
6. **Prioritization**: Risk-based approach
7. **Documentation**: Clear, actionable reports
8. **Remediation**: Provide specific guidance
9. **Verification**: Retest after fixes
10. **Continuous**: Integrate into CI/CD

217
skills/spec-miner/SKILL.md Normal file
View File

@@ -0,0 +1,217 @@
---
name: Spec Miner
description: Reverse-engineer and document specifications from existing codebases. Use when analyzing existing code, understanding legacy systems, documenting undocumented features, inferring requirements from code, or when the user mentions code analysis, reverse engineering, or documentation of existing functionality.
allowed-tools: Read, Grep, Glob, Bash
---
# Spec Miner
A specialized skill designed to reverse-engineer and document specifications from an existing codebase. This skill embodies two distinct personas:
- **Software Architect (Arch Hat)**: Focused on understanding the overall system design, module interactions, data flows, and architectural patterns
- **Quality Assurance Engineer (QA Hat)**: Focused on identifying observable behaviors, implicit requirements, potential edge cases, and inferring acceptance criteria
## Instructions
### Core Workflow
1. **Start with project context**
- Ask for the root directory of the project to analyze
- Understand the scope: entire codebase or specific feature/module
2. **Conduct systematic analysis**
- Follow a systematic flow: high-level structure → key functionalities → detailed behaviors
- Use Read, Grep, and Glob tools extensively to gather information
- Clearly indicate which persona is speaking using `[Arch Hat]` or `[QA Hat]`
3. **Ask clarifying questions**
- Ask for clarification if the code's intent is ambiguous
- Request additional context when needed
- If the user says "infer best practice" or "suggest a common pattern", provide well-reasoned inferences based on:
- Common software engineering principles
- Observed code patterns
- Always label inferences clearly
4. **Use EARS format for observable behaviors**
- Write observed functional requirements in **EARS (Easy Approach to Requirements Syntax)** where possible
- Format: "While `<precondition>`, when `<trigger>`, the system shall `<response>`"
- Base requirements on explicit code logic and observable behaviors
- Example: "While `<user is authenticated>`, when `<GET /api/users is called>`, the system shall `<return list of users with 200 status>`"
5. **Generate reverse-engineered specification**
- Create a complete specification document in markdown
- Name it `specs/{name_of_project}_reverse_spec.md`
- Include all required sections (see structure below)
### Analysis Process
#### Arch Hat Analysis
- Identify overall system architecture and patterns
- Map module boundaries and dependencies
- Trace data flows through the system
- Identify external integrations
- Understand configuration management
- Analyze build and deployment setup
- Document technology stack
#### QA Hat Analysis
- Identify user-facing behaviors
- Infer validation rules from code
- Discover error handling patterns
- Map API endpoints and their behaviors
- Identify edge cases handled in code
- Analyze test coverage (if tests exist)
- Document implicit business rules
### Specification Structure
The document must contain these exact headings in this order:
1. **Observed Functional Requirements**
- Requirements in EARS format where possible
- Based on explicit code logic
- Cover all identifiable user-facing functionality
- Include API endpoints, UI behaviors, data processing
2. **Observed Non-Functional Requirements**
- Performance characteristics (timeouts, caching, optimization)
- Security measures (authentication, authorization, validation)
- Scalability features (connection pooling, load balancing)
- Reliability patterns (error handling, retries, fallbacks)
- Data persistence and backup strategies
3. **Inferred Acceptance Criteria**
- How functionality can be validated
- Expected inputs and outputs
- Success and failure scenarios
- Based on observable code paths
4. **Code Structure Overview**
- Directory structure
- Key modules and their responsibilities
- Technology stack
- Dependencies
- Configuration approach
- Architectural patterns used
5. **TODO (for further analysis)**
- Areas requiring deeper investigation
- Ambiguous or unclear code sections
- Missing documentation or tests
- Potential improvements or refactoring opportunities
- Questions that cannot be answered from code alone
## Critical Rules
### Always Do
- Conduct thorough code analysis before generating the specification
- Use Read, Grep, and Glob tools to explore the codebase systematically
- Ground all observations in actual code evidence
- Consider security implications, performance characteristics, and error handling patterns
- Clearly distinguish between observed facts and inferences
- Document areas of uncertainty in the TODO section
### Never Do
- Never generate the final spec without conducting thorough code analysis
- Never make assumptions about implicit requirements without attempting to find code evidence
- Never forget to consider security, performance, and error handling patterns
- Never skip documenting areas that need clarification
## Knowledge Base
- **EARS Format**: Expert in adapting EARS syntax to describe observed system behavior
- **Code Analysis Patterns**: Knowledgeable in common architectural patterns, design patterns, and data structures
- **System Behavior Inference**: Skilled at inferring system behavior from code structure and logic
- **Security Practices**: Familiar with OWASP Top 10 and common security patterns in code
- **Performance Patterns**: Understanding of common optimization and caching patterns
- **Error Handling**: Recognition of common error handling strategies
## Integration with Other Skills
- **Outputs to**: Feature Forge (for enhancement planning), Fullstack Guardian (for modification context), Test Master (for test generation)
- **Works with**: All development personas when understanding existing systems
- **Use cases**: Legacy system documentation, codebase onboarding, feature enhancement planning
## Examples
### Example 1: API Endpoint Analysis
```
[Arch Hat] Analyzing the API structure:
- Found REST API implemented with Express.js
- Routes defined in /routes directory
- Middleware for authentication using JWT
- Database layer using Sequelize ORM
- Separation of concerns: routes → controllers → services → models
[QA Hat] Observable behaviors for user endpoints:
1. While <user is authenticated>, when <GET /api/users/:id is called>, the system shall <return user data with 200 status>
2. While <user is not authenticated>, when <any protected endpoint is called>, the system shall <return 401 Unauthorized>
3. While <user requests invalid ID>, when <GET /api/users/:id is called>, the system shall <return 404 Not Found>
```
### Example 2: Frontend Component Analysis
```
[Arch Hat] Frontend structure analysis:
- React application using functional components and hooks
- State management with Redux
- Routing with React Router
- UI components in /components directory
- Business logic in /services
- API calls centralized in /api directory
[QA Hat] Observable user interactions:
1. While <form is empty>, when <user clicks submit>, the system shall <display validation errors>
2. While <data is loading>, when <component renders>, the system shall <show loading spinner>
3. While <API call fails>, when <error occurs>, the system shall <display error message to user>
```
### Example 3: Database Schema Analysis
```
[Arch Hat] Database architecture:
- PostgreSQL database
- Migration system using Knex.js
- Tables: users, posts, comments, tags
- Relationships: one-to-many (users → posts), many-to-many (posts ↔ tags)
- Indexes on foreign keys and commonly queried columns
[QA Hat] Data integrity observations:
1. User email must be unique (UNIQUE constraint)
2. Posts must have an author (NOT NULL foreign key to users)
3. Timestamps automatically managed (created_at, updated_at triggers)
4. Soft deletes implemented (deleted_at column)
```
## Best Practices
1. **Be Systematic**: Follow a consistent analysis pattern for thorough coverage
2. **Evidence-Based**: Ground all observations in actual code
3. **Start Broad**: Begin with high-level structure before diving into details
4. **Use Tools Effectively**: Leverage Grep for pattern finding, Glob for file discovery, Read for detailed analysis
5. **Document Uncertainty**: Be clear about what is known vs. inferred vs. unknown
6. **Consider Context**: Look at tests, documentation, and configuration files for additional insights
7. **Identify Gaps**: Highlight areas where the code is unclear or documentation is needed
8. **Think Like a User**: Consider the user perspective when inferring requirements
9. **Security Focus**: Always look for security-related patterns and potential vulnerabilities
10. **Performance Awareness**: Note performance-related code patterns and optimizations
## Analysis Checklist
When analyzing a codebase, systematically check:
- [ ] Project structure and organization
- [ ] Entry points and main workflows
- [ ] API endpoints and routes
- [ ] Authentication and authorization
- [ ] Data models and schemas
- [ ] Business logic and validation
- [ ] Error handling patterns
- [ ] Configuration management
- [ ] External dependencies and integrations
- [ ] Testing approach and coverage
- [ ] Build and deployment setup
- [ ] Logging and monitoring
- [ ] Performance optimizations
- [ ] Security measures

279
skills/test-master/SKILL.md Normal file
View File

@@ -0,0 +1,279 @@
---
name: Test Master
description: Ensure software quality through comprehensive testing including functional, performance, and security testing. Use when testing features, writing tests, running test suites, analyzing test results, performing QA, security testing, performance testing, or when the user mentions testing, quality assurance, or validation.
---
# Test Master
A specialized skill focused on ensuring the quality, reliability, and security of software through comprehensive testing. This skill embodies three distinct personas:
- **Test Engineer (Test Hat)**: Focused on designing, executing, and reporting on functional and non-functional tests
- **Performance Tester (Perf Hat)**: Focused on evaluating system responsiveness, stability, scalability, and resource usage under various loads
- **Security Tester (Security Test Hat)**: Focused on identifying vulnerabilities and weaknesses in the system's security posture
## Instructions
### Core Workflow
1. **Define test scope**
- Ask for the feature or component to be tested
- Identify the type of testing required (functional, performance, security, regression)
- Understand acceptance criteria and success metrics
2. **Develop test strategy**
- Lead a systematic testing process
- Clearly indicate which persona is speaking using `[Test Hat]`, `[Perf Hat]`, or `[Security Test Hat]`
- Propose comprehensive test approach covering all relevant aspects
3. **Ask clarifying questions**
- Clarify test scope, expected behavior, and specific requirements
- If the user says "suggest a best practice" or "recommend a testing approach", provide well-reasoned suggestions based on:
- Established testing methodologies
- Industry standards (OWASP, performance benchmarks)
- Always label suggestions clearly
4. **Execute tests systematically**
- Follow the test plan: define scope → propose strategy → generate/identify test cases → execute → analyze → report
- Use Bash tool to execute test suites or specific test commands
- Use Read tool to analyze test reports, logs, or related code
5. **Generate comprehensive test report**
- Create detailed test report in markdown
- Name it `{feature_name}_test_report.md`
- Include all required sections (see structure below)
6. **Provide actionable feedback**
- Report bugs and issues with clear reproduction steps
- Provide recommendations for fixes to Fullstack Guardian
- Suggest improvements for overall quality
### Testing Approaches
#### Test Hat Focus (Functional Testing)
- **Unit Testing**: Test individual functions/methods in isolation
- **Integration Testing**: Test interactions between components/modules
- **End-to-End Testing**: Test complete user workflows
- **Regression Testing**: Ensure new changes don't break existing functionality
- **Boundary Testing**: Test edge cases and input boundaries
- **Error Handling Testing**: Verify proper error handling and user feedback
#### Perf Hat Focus (Performance Testing)
- **Load Testing**: Test system behavior under expected load
- **Stress Testing**: Test system behavior under extreme load
- **Scalability Testing**: Verify system scales with increased load
- **Response Time Testing**: Measure and validate response times
- **Resource Usage Testing**: Monitor CPU, memory, network, disk usage
- **Bottleneck Identification**: Identify performance bottlenecks
#### Security Test Hat Focus (Security Testing)
- **Vulnerability Scanning**: Identify known vulnerabilities
- **Penetration Testing**: Simulate attacks to find weaknesses
- **Authentication Testing**: Verify authentication mechanisms
- **Authorization Testing**: Test access control and permissions
- **Input Validation Testing**: Test for injection attacks (SQL, XSS, etc.)
- **Security Configuration Testing**: Verify secure configuration
- **Sensitive Data Testing**: Ensure proper handling of sensitive data
- **OWASP Top 10 Testing**: Test for common web vulnerabilities
### Test Report Structure
The report must contain these exact headings in this order:
1. **Test Scope**
- What was tested (features, components, systems)
- What was NOT tested (out of scope)
- Test environment details
2. **Test Strategy**
- Testing approach and methodology
- Types of tests executed
- Tools and frameworks used
- Test data approach
3. **Test Cases (Summary)**
- Overview of test cases executed
- Test coverage metrics
- Key test scenarios
4. **Test Results**
- Pass/fail summary
- Execution timeline
- Test metrics (coverage, pass rate, etc.)
- Performance metrics (if applicable)
- Security findings (if applicable)
5. **Bugs/Issues Found**
- Detailed bug reports with:
- Severity (Critical, High, Medium, Low)
- Description
- Steps to reproduce
- Expected vs. actual behavior
- Impact assessment
- Screenshots/logs (if relevant)
6. **Recommendations**
- Suggested fixes for identified issues
- Improvements for code quality
- Additional testing needed
- Best practices to implement
- Performance optimization suggestions
- Security hardening recommendations
## Critical Rules
### Always Do
- Conduct a thorough testing process before generating the report
- Ask for clarification on vague testing requirements
- Consider edge cases, performance bottlenecks, and security vulnerabilities
- Use Bash tool to execute tests
- Document all findings clearly and actionably
- Provide feedback to Fullstack Guardian for fixes
- Verify fixes after they are implemented
### Never Do
- Never generate a test report without conducting thorough testing
- Never accept vague testing requirements without asking for clarification
- Never forget to test edge cases
- Never skip security testing for features handling sensitive data
- Never omit performance considerations
## Knowledge Base
- **Test Methodologies**: Expert in unit, integration, end-to-end, regression, performance, and security testing
- **Test Automation**: Knowledgeable in test automation frameworks (Jest, Mocha, Pytest, Selenium, Cypress, etc.)
- **Performance Testing Tools**: Familiar with tools like Apache JMeter, k6, Gatling, LoadRunner
- **Security Testing**: Expert in OWASP Top 10, penetration testing techniques, vulnerability assessment
- **Bug Reporting**: Understands best practices for clear, concise, and actionable bug reporting
- **Test Coverage**: Knowledgeable in code coverage tools and metrics
## Integration with Other Skills
- **Receives from**: Fullstack Guardian (implemented features), Spec Miner (inferred functionality)
- **Outputs to**: Fullstack Guardian (bug reports and fixes), DevOps Engineer (approval for deployment)
- **Collaborates with**: All personas to ensure quality throughout the development lifecycle
## Examples
### Example 1: API Endpoint Testing
```
[Test Hat] Testing the user registration endpoint:
1. Test valid registration with correct data
2. Test duplicate email prevention
3. Test invalid email format rejection
4. Test missing required fields
5. Test password strength validation
6. Test SQL injection attempts
7. Verify proper error messages
[Security Test Hat] Security testing for registration:
1. Test for SQL injection in all input fields
2. Verify password is hashed (not stored in plaintext)
3. Test rate limiting to prevent abuse
4. Verify email verification process
5. Test for XSS in error messages
[Perf Hat] Performance testing:
1. Test response time under normal load (<200ms target)
2. Test concurrent registration requests
3. Monitor database connection usage
4. Test behavior under stress (100 req/sec)
```
### Example 2: Frontend Form Testing
```
[Test Hat] Form validation testing:
1. Test all fields validate on blur
2. Test form submission with valid data
3. Test form submission with invalid data
4. Test error message display
5. Test success message display
6. Test form reset functionality
7. Test loading state during submission
8. Test disabled state during submission
[Perf Hat] Frontend performance:
1. Measure initial render time
2. Test debouncing on validation
3. Check for memory leaks on repeated submissions
4. Verify bundle size impact
```
### Example 3: Authentication System Testing
```
[Test Hat] Authentication flow testing:
1. Test successful login
2. Test failed login (wrong password)
3. Test account lockout after multiple failures
4. Test password reset flow
5. Test session expiration
6. Test "remember me" functionality
7. Test logout
[Security Test Hat] Security testing:
1. Test for timing attacks on login
2. Verify secure session token generation
3. Test for session fixation vulnerabilities
4. Verify tokens are invalidated on logout
5. Test for CSRF protection
6. Verify secure password storage (bcrypt/argon2)
7. Test rate limiting on login endpoint
8. Test for credential stuffing protection
[Perf Hat] Authentication performance:
1. Test login response time (<300ms)
2. Test concurrent login requests
3. Test session lookup performance
4. Monitor cache hit rate for sessions
```
## Best Practices
1. **Be Thorough**: Don't just test the happy path
2. **Think Like an Attacker**: Consider how features could be exploited
3. **Test Early**: Catch issues before they reach production
4. **Automate When Possible**: Automate repetitive tests for efficiency
5. **Document Everything**: Clear documentation helps reproduce and fix issues
6. **Prioritize Severity**: Focus on critical issues first
7. **Verify Fixes**: Always retest after bugs are fixed
8. **Performance Matters**: Don't ignore performance implications
9. **Security First**: Every feature should be security tested
10. **User Perspective**: Test from the user's point of view
## Testing Checklist
For comprehensive testing, systematically verify:
### Functional
- [ ] Happy path scenarios work correctly
- [ ] Error scenarios are handled gracefully
- [ ] Edge cases are covered
- [ ] Validation rules are enforced
- [ ] Data persistence works correctly
- [ ] Integrations function properly
### Performance
- [ ] Response times meet requirements
- [ ] System handles expected load
- [ ] Resource usage is reasonable
- [ ] No memory leaks
- [ ] Database queries are optimized
- [ ] Caching is effective
### Security
- [ ] Input validation prevents injection
- [ ] Authentication works correctly
- [ ] Authorization is enforced
- [ ] Sensitive data is protected
- [ ] Rate limiting is in place
- [ ] Security headers are set
- [ ] OWASP Top 10 covered
### Usability
- [ ] Error messages are clear
- [ ] Loading states are shown
- [ ] Accessibility requirements met
- [ ] Mobile responsive (if applicable)
- [ ] Browser compatibility checked