plan-flow-skill 1.0.0

package/rules/languages/python-patterns.mdc

@@ -0,0 +1,188 @@
+---
+description: "Python best practices including type hints and PEP 8 conventions"
+globs: ["**/*.py"]
+alwaysApply: false
+---
+
+# Python Best Practices & Patterns
+
+## 1. Follow PEP 8 Style Guide
+
+Follow PEP 8 conventions. Key naming reminders:
+
+- Variables and functions: `lower_case_with_underscores`
+- Classes: `CapWords`
+- Constants: `UPPER_CASE_WITH_UNDERSCORES`
+- Private members: `_leading_underscore`
+
+## 2. Use Type Hints
+
+Add type annotations for clarity and IDE support:
+
+```python
+from typing import Optional, List, Dict
+
+def get_user(user_id: int) -> Optional[Dict[str, str]]:
+    """Fetch user by ID, returns None if not found."""
+    ...
+
+def process_items(items: List[str]) -> Dict[str, int]:
+    return {item: len(item) for item in items}
+```
+
+## 3. Utilize Dataclasses for Structured Data
+
+```python
+from dataclasses import dataclass, field
+from typing import List
+
+@dataclass
+class User:
+    id: int
+    name: str
+    email: str
+    active: bool = True
+    roles: List[str] = field(default_factory=list)
+
+@dataclass(frozen=True)  # Immutable
+class Config:
+    api_url: str
+    timeout: int = 30
+```
+
+## 4. Write Modular Functions
+
+Break down code into focused functions with single responsibility:
+
+```python
+def calculate_total_price(items: List[Item]) -> float:
+    return sum(item.price for item in items)
+
+def validate_order(customer: Customer, items: List[Item]) -> bool:
+    return customer.is_active and len(items) > 0
+```
+
+## 5. Avoid Magic Numbers and Strings
+
+Use enums and named constants:
+
+```python
+from enum import Enum, auto
+from http import HTTPStatus
+
+class OrderStatus(Enum):
+    PENDING = auto()
+    APPROVED = auto()
+
+if status == OrderStatus.APPROVED:
+    send_email()
+
+if response.status_code == HTTPStatus.OK:
+    process_data()
+```
+
+## 6. Use Context Managers for Resource Management
+
+```python
+from contextlib import contextmanager
+
+@contextmanager
+def database_connection(url: str):
+    conn = create_connection(url)
+    try:
+        yield conn
+    finally:
+        conn.close()
+```
+
+## 7. Implement Custom Exceptions
+
+```python
+class ValidationError(Exception):
+    def __init__(self, message: str, field: str = None):
+        self.message = message
+        self.field = field
+        super().__init__(self.message)
+
+class NotFoundError(Exception):
+    pass
+```
+
+## 8. Async/Await for I/O Operations
+
+```python
+import asyncio
+
+async def fetch_data(url: str) -> dict:
+    async with aiohttp.ClientSession() as session:
+        async with session.get(url) as response:
+            return await response.json()
+
+async def fetch_all(urls: List[str]) -> List[dict]:
+    tasks = [fetch_data(url) for url in urls]
+    return await asyncio.gather(*tasks)
+```
+
+## 9. Use Dependency Injection
+
+Favor dependency injection for testable code:
+
+```python
+from abc import ABC, abstractmethod
+
+class EmailService(ABC):
+    @abstractmethod
+    def send(self, to: str, subject: str, body: str) -> bool:
+        pass
+
+class UserService:
+    def __init__(self, email_service: EmailService):
+        self._email_service = email_service
+```
+
+## 10. Use Logging Instead of Print
+
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+
+def process_data(data: dict) -> None:
+    logger.debug(f"Processing data: {data}")
+    try:
+        result = transform(data)
+        logger.info(f"Successfully processed {len(result)} items")
+    except Exception as e:
+        logger.exception(f"Error processing data: {e}")
+        raise
+```
+
+## 11. Use Pydantic for Data Validation
+
+```python
+from pydantic import BaseModel, EmailStr, validator
+
+class UserCreate(BaseModel):
+    name: str
+    email: EmailStr
+
+    @validator("name")
+    def name_must_not_be_empty(cls, v):
+        if not v.strip():
+            raise ValueError("Name cannot be empty")
+        return v.strip()
+```
+
+## 12. Use Pathlib for File Operations
+
+```python
+from pathlib import Path
+
+file_path = Path(__file__).parent / "data" / "file.txt"
+
+if file_path.exists():
+    content = file_path.read_text()
+
+for py_file in Path(".").glob("**/*.py"):
+    print(py_file.name)
+```

package/rules/languages/typescript-patterns.mdc

@@ -0,0 +1,128 @@
+---
+description: "TypeScript best practices and strict typing patterns"
+globs: ["**/*.ts", "**/*.tsx"]
+alwaysApply: false
+---
+
+# TypeScript Best Practices & Patterns
+
+## 1. Enable Strict Type-Checking
+
+Ensure `strict: true` is enabled in `tsconfig.json` for rigorous type-checking.
+
+## 2. Prefer Interfaces for Object Shapes
+
+Use interfaces to define object structures:
+
+```typescript
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+```
+
+Reserve type aliases for unions, intersections, and complex type compositions.
+
+## 3. Utilize Discriminated Unions for State Management
+
+Model exclusive states with discriminated unions:
+
+```typescript
+type RequestState =
+  | { status: "idle" }
+  | { status: "loading" }
+  | { status: "success"; data: User }
+  | { status: "error"; error: Error };
+```
+
+## 4. Leverage Generics for Reusable Components
+
+Use generics for flexible, type-safe components:
+
+```typescript
+class Cache<T> {
+  private data: Map<string, T> = new Map();
+  set(key: string, value: T): void { this.data.set(key, value); }
+  get(key: string): T | undefined { return this.data.get(key); }
+}
+```
+
+## 5. Implement Custom Error Types
+
+```typescript
+class ValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ValidationError";
+  }
+}
+```
+
+## 6. Utilize Utility Types
+
+Use TypeScript's built-in utility types: `Partial<T>`, `Required<T>`, `Readonly<T>`, `Pick<T, K>`, `Omit<T, K>`, `Record<K, T>`.
+
+## 7. Avoid the `any` Type
+
+Use `unknown` with type guards instead of `any`:
+
+```typescript
+let value: unknown;
+
+if (typeof value === "string") {
+  console.log(value.toUpperCase());
+}
+```
+
+## 8. Enable Null Safety
+
+Use optional chaining and nullish coalescing:
+
+```typescript
+const name = user?.profile?.name;
+const displayName = name ?? "Anonymous";
+```
+
+## 9. Prefer `const` Assertions for Literal Types
+
+```typescript
+const roles = ["admin", "user", "guest"] as const;
+const response = { status: "active", code: 200 } as const;
+```
+
+## 10. Use Type Guards for Runtime Type Checking
+
+```typescript
+function isDog(animal: Dog | Cat): animal is Dog {
+  return (animal as Dog).bark !== undefined;
+}
+```
+
+## 11. Prefer Immutability
+
+Use `readonly` and `ReadonlyArray` for immutable data:
+
+```typescript
+interface Config {
+  readonly apiUrl: string;
+  readonly timeout: number;
+}
+
+function processItems(items: ReadonlyArray<string>) {
+  // items.push('new'); // Error
+}
+```
+
+## 12. Use `satisfies` Operator
+
+Validate types while preserving narrower types:
+
+```typescript
+type Colors = "red" | "green" | "blue";
+
+const palette = {
+  primary: "red",
+  secondary: "blue",
+} satisfies Record<string, Colors>;
+```

package/rules/patterns/_index.mdc

@@ -0,0 +1,185 @@
+---
+description: "Summary index for patterns - load this to see available references"
+alwaysApply: false
+---
+
+# Patterns Index
+
+## Overview
+
+Pattern files provide templates, examples, and guidelines for specific workflows. This is the largest category covering discovery, planning, testing, code review, and contracts.
+
+**Total Files**: 9 files, ~3,145 lines
+**Reference Codes**: PTN-CON-1 through PTN-PR-6
+
+---
+
+## Reference Codes
+
+### Contract Patterns (`contract-patterns.mdc`)
+
+| Code | Description | Source | Lines |
+|------|-------------|--------|-------|
+| PTN-CON-1 | Contract document structure and required sections | contract-patterns.mdc | 24-44 |
+| PTN-CON-2 | Allowed patterns (TypeScript interfaces, status codes, auth examples) | contract-patterns.mdc | 47-171 |
+| PTN-CON-3 | Forbidden patterns (no hardcoded secrets, generic types) | contract-patterns.mdc | 173-250 |
+| PTN-CON-4 | FE integration guidelines (state management, caching) | contract-patterns.mdc | 252-283 |
+
+### Discovery Patterns (`discovery-patterns.mdc`)
+
+| Code | Description | Source | Lines |
+|------|-------------|--------|-------|
+| PTN-DIS-1 | What is discovery + folder structure | discovery-patterns.mdc | 14-47 |
+| PTN-DIS-2 | Naming conventions + question status tracking | discovery-patterns.mdc | 49-88 |
+| PTN-DIS-3 | Requirements categories (FR, NFR, Constraints) | discovery-patterns.mdc | 90-109 |
+| PTN-DIS-4 | Allowed discovery patterns | discovery-patterns.mdc | 112-213 |
+| PTN-DIS-5 | Forbidden discovery patterns | discovery-patterns.mdc | 215-298 |
+
+### Discovery Templates (`discovery-templates.mdc`)
+
+| Code | Description | Source | Lines |
+|------|-------------|--------|-------|
+| PTN-DIST-1 | Discovery document template | discovery-templates.mdc | 12-94 |
+| PTN-DIST-2 | Spike template | discovery-templates.mdc | 96-162 |
+| PTN-DIST-3 | Question format examples (functional, technical, UI/UX) | discovery-templates.mdc | 164-215 |
+| PTN-DIST-4 | Referenced documents analysis example | discovery-templates.mdc | 217-242 |
+| PTN-DIST-5 | Requirements gathering example | discovery-templates.mdc | 244-279 |
+| PTN-DIST-6 | Risks and proposed approach examples | discovery-templates.mdc | 281-330 |
+
+### Jest Patterns (`jest-patterns.mdc`)
+
+| Code | Description | Source | Lines |
+|------|-------------|--------|-------|
+| PTN-JEST-1 | File naming conventions and test location | jest-patterns.mdc | 12-56 |
+| PTN-JEST-2 | Test structure (AAA pattern, describe/it blocks) | jest-patterns.mdc | 58-91 |
+| PTN-JEST-3 | Server and client test setup | jest-patterns.mdc | 93-160 |
+| PTN-JEST-4 | Mock factories and mocking dependencies | jest-patterns.mdc | 162-301 |
+| PTN-JEST-5 | Testing async code, errors, hooks, browser APIs | jest-patterns.mdc | 303-412 |
+| PTN-JEST-6 | Forbidden testing patterns | jest-patterns.mdc | 414-481 |
+
+### Plans Patterns (`plans-patterns.mdc`)
+
+| Code | Description | Source | Lines |
+|------|-------------|--------|-------|
+| PTN-PLN-1 | Workflow folder structure | plans-patterns.mdc | 14-31 |
+| PTN-PLN-2 | Allowed planning patterns (12 patterns) | plans-patterns.mdc | 39-142 |
+| PTN-PLN-3 | Forbidden planning patterns (13 patterns) | plans-patterns.mdc | 144-223 |
+
+### Plans Templates (`plans-templates.mdc`)
+
+| Code | Description | Source | Lines |
+|------|-------------|--------|-------|
+| PTN-PLNT-1 | Plan document template | plans-templates.mdc | 12-95 |
+| PTN-PLNT-2 | Phase templates (types, backend, store, UI, integration, tests) | plans-templates.mdc | 98-188 |
+| PTN-PLNT-3 | Key changes and complexity summary examples | plans-templates.mdc | 190-238 |
+
+### Pytest Patterns (`pytest-patterns.mdc`)
+
+| Code | Description | Source | Lines |
+|------|-------------|--------|-------|
+| PTN-PYTEST-1 | File naming and test structure | pytest-patterns.mdc | 12-77 |
+| PTN-PYTEST-2 | Fixtures and factory fixtures | pytest-patterns.mdc | 79-173 |
+| PTN-PYTEST-3 | Mocking (basic, class instances, async) | pytest-patterns.mdc | 175-241 |
+| PTN-PYTEST-4 | Parametrized tests | pytest-patterns.mdc | 243-276 |
+| PTN-PYTEST-5 | Testing exceptions and context managers | pytest-patterns.mdc | 278-347 |
+| PTN-PYTEST-6 | Async testing and forbidden patterns | pytest-patterns.mdc | 349-457 |
+
+### Review Code Templates (`review-code-templates.mdc`)
+
+| Code | Description | Source | Lines |
+|------|-------------|--------|-------|
+| PTN-REV-1 | Code review output format template | review-code-templates.mdc | 12-192 |
+| PTN-REV-2 | Pattern conflict example | review-code-templates.mdc | 196-232 |
+| PTN-REV-3 | Rule update recommendation example | review-code-templates.mdc | 234-284 |
+| PTN-REV-4 | Finding example | review-code-templates.mdc | 286-316 |
+
+### PR Review Patterns (`review-pr-patterns.mdc`)
+
+| Code | Description | Source | Lines |
+|------|-------------|--------|-------|
+| PTN-PR-1 | General PR review checklist | review-pr-patterns.mdc | 32-74 |
+| PTN-PR-2 | TypeScript PR review patterns | review-pr-patterns.mdc | 76-116 |
+| PTN-PR-3 | Python PR review patterns | review-pr-patterns.mdc | 118-163 |
+| PTN-PR-4 | Forbidden patterns to catch in reviews | review-pr-patterns.mdc | 165-253 |
+| PTN-PR-5 | Allowed patterns to encourage | review-pr-patterns.mdc | 255-310 |
+| PTN-PR-6 | Review comment templates and approval criteria | review-pr-patterns.mdc | 312-371 |
+
+---
+
+## When to Expand
+
+### Discovery Workflow
+
+| Code | Expand When |
+|------|-------------|
+| PTN-DIS-1 | Starting discovery, need folder structure | 
+| PTN-DIS-3 | Categorizing requirements (FR, NFR, C) |
+| PTN-DIST-1 | Creating a discovery document |
+| PTN-DIST-5 | Need requirements gathering example |
+
+### Planning Workflow
+
+| Code | Expand When |
+|------|-------------|
+| PTN-PLN-1 | Need folder structure reference |
+| PTN-PLN-2 | Need allowed planning patterns |
+| PTN-PLNT-1 | Creating a new plan document |
+| PTN-PLNT-2 | Need phase templates |
+
+### Testing (Jest)
+
+| Code | Expand When |
+|------|-------------|
+| PTN-JEST-1 | Setting up test file naming |
+| PTN-JEST-2 | Need test structure example |
+| PTN-JEST-3 | Setting up server/client tests |
+| PTN-JEST-4 | Need mock factory examples |
+
+### Testing (Pytest)
+
+| Code | Expand When |
+|------|-------------|
+| PTN-PYTEST-1 | Setting up pytest file structure |
+| PTN-PYTEST-2 | Need fixture examples |
+| PTN-PYTEST-3 | Need mocking examples |
+| PTN-PYTEST-4 | Need parametrized test examples |
+
+### Code Review
+
+| Code | Expand When |
+|------|-------------|
+| PTN-REV-1 | Creating code review output |
+| PTN-PR-1 | Need general PR checklist |
+| PTN-PR-2 | Reviewing TypeScript code |
+| PTN-PR-3 | Reviewing Python code |
+
+### Contracts
+
+| Code | Expand When |
+|------|-------------|
+| PTN-CON-1 | Creating a new contract document |
+| PTN-CON-2 | Need contract pattern examples |
+| PTN-CON-4 | Need FE integration guidance |
+
+---
+
+## Quick Reference by Category
+
+### Discovery
+- **PTN-DIS-***: Discovery patterns and rules
+- **PTN-DIST-***: Discovery templates and examples
+
+### Planning
+- **PTN-PLN-***: Planning patterns and rules
+- **PTN-PLNT-***: Plan templates
+
+### Testing
+- **PTN-JEST-***: Jest testing patterns (JS/TS)
+- **PTN-PYTEST-***: Pytest testing patterns (Python)
+
+### Reviews
+- **PTN-REV-***: Code review templates
+- **PTN-PR-***: PR review patterns
+
+### Contracts
+- **PTN-CON-***: Integration contract patterns