devflow-kit 1.8.3 → 2.0.1

package/shared/skills/performance-patterns/references/violations.md

@@ -1,354 +0,0 @@
-# Performance Violation Examples
-
-Extended violation patterns for performance reviews. Reference from main SKILL.md.
-
-## Algorithmic Violations
-
-### N+1 Query Variants
-
-**ORM Eager Loading Missing**
-```typescript
-// VIOLATION: Lazy loading triggers N queries
-const posts = await Post.findAll();
-for (const post of posts) {
-  console.log(post.author.name);  // N additional queries
-}
-```
-
-**GraphQL Resolver N+1**
-```typescript
-// VIOLATION: Resolver called per item
-const resolvers = {
-  Post: {
-    author: async (post) => {
-      return db.users.findById(post.authorId);  // N queries
-    }
-  }
-};
-```
-
-**Nested Loop Queries**
-```typescript
-// VIOLATION: Query inside nested loop
-for (const category of categories) {
-  for (const product of category.products) {
-    const reviews = await db.reviews.findByProductId(product.id);  // N*M queries
-  }
-}
-```
-
-### O(n^2) or Worse Patterns
-
-**Array.includes in Loop**
-```typescript
-// VIOLATION: O(n^2) - includes is O(n)
-function removeDuplicates(items: Item[]) {
-  const unique: Item[] = [];
-  for (const item of items) {
-    if (!unique.some(u => u.id === item.id)) {  // O(n) check each time
-      unique.push(item);
-    }
-  }
-  return unique;
-}
-```
-
-**Nested Array Methods**
-```typescript
-// VIOLATION: O(n*m) - filter inside map
-function matchItems(list1: Item[], list2: Item[]) {
-  return list1.map(item => ({
-    ...item,
-    matches: list2.filter(i => i.category === item.category)  // O(m) per item
-  }));
-}
-```
-
-**String Concatenation in Loop**
-```typescript
-// VIOLATION: O(n^2) string copies
-function buildCsv(rows: string[][]): string {
-  let csv = '';
-  for (const row of rows) {
-    csv += row.join(',') + '\n';  // Creates new string each time
-  }
-  return csv;
-}
-```
-
-### Inefficient Data Structure Usage
-
-**Object.keys/values/entries in Hot Path**
-```typescript
-// VIOLATION: Creates new array on each call
-function findInObject(obj: Record<string, Item>, predicate: (item: Item) => boolean) {
-  for (const key of Object.keys(obj)) {  // Allocates array
-    if (predicate(obj[key])) {
-      return obj[key];
-    }
-  }
-}
-```
-
-**Array as Queue/Stack**
-```typescript
-// VIOLATION: shift() is O(n)
-class Queue<T> {
-  private items: T[] = [];
-
-  dequeue(): T | undefined {
-    return this.items.shift();  // O(n) - reindexes entire array
-  }
-}
-```
-
----
-
-## Database Violations
-
-### Missing Index Patterns
-
-**Unindexed Foreign Key**
-```sql
--- VIOLATION: Joins without index
-SELECT * FROM orders o
-JOIN order_items oi ON o.id = oi.order_id  -- order_id likely unindexed
-WHERE o.customer_id = 123;
-```
-
-**Unindexed Filter Column**
-```typescript
-// VIOLATION: Filters on unindexed column
-const activeUsers = await db.query(
-  'SELECT * FROM users WHERE last_login > ?',  // last_login probably unindexed
-  [thirtyDaysAgo]
-);
-```
-
-**Composite Index Order Wrong**
-```sql
--- Index exists: (customer_id, status)
--- VIOLATION: Query doesn't use index efficiently
-SELECT * FROM orders WHERE status = 'pending';  -- Can't use composite index
-```
-
-### Inefficient Queries
-
-**LIKE with Leading Wildcard**
-```typescript
-// VIOLATION: Can't use index
-const results = await db.query(
-  'SELECT * FROM products WHERE name LIKE ?',
-  ['%laptop%']  // Leading % prevents index usage
-);
-```
-
-**OR Instead of IN**
-```typescript
-// VIOLATION: OR conditions often slower
-const users = await db.query(
-  'SELECT * FROM users WHERE status = ? OR status = ? OR status = ?',
-  ['active', 'pending', 'trial']
-);
-
-// Better: Use IN clause
-const users = await db.query(
-  'SELECT * FROM users WHERE status IN (?, ?, ?)',
-  ['active', 'pending', 'trial']
-);
-```
-
-**Sorting Without Index**
-```typescript
-// VIOLATION: ORDER BY on unindexed column causes filesort
-const recent = await db.query(
-  'SELECT * FROM logs ORDER BY created_at DESC LIMIT 100'  // No index on created_at
-);
-```
-
----
-
-## Memory Violations
-
-### Memory Leak Patterns
-
-**Closure Retaining Large Object**
-```typescript
-// VIOLATION: Closure keeps entire large object alive
-function processLargeData(data: LargeObject) {
-  return () => {
-    console.log(data.id);  // Only needs id, but retains entire data object
-  };
-}
-```
-
-**Timer Without Cleanup**
-```typescript
-// VIOLATION: Interval never cleared
-class Poller {
-  start() {
-    setInterval(() => this.poll(), 1000);  // Runs forever
-  }
-}
-```
-
-**Observable Without Unsubscribe**
-```typescript
-// VIOLATION: Subscription never cleaned up
-class Component {
-  init() {
-    eventBus.subscribe('update', this.handleUpdate);  // Memory leak
-  }
-  // Missing cleanup method
-}
-```
-
-### Large Allocation Patterns
-
-**Spreading in Reduce**
-```typescript
-// VIOLATION: Creates new object on each iteration
-const merged = items.reduce((acc, item) => ({
-  ...acc,  // Copies entire accumulator each time
-  [item.id]: item
-}), {});
-```
-
-**Array.concat in Loop**
-```typescript
-// VIOLATION: Creates new array each iteration
-let all: Item[] = [];
-for (const batch of batches) {
-  all = all.concat(batch);  // O(n^2) total allocations
-}
-```
-
-**JSON Clone in Hot Path**
-```typescript
-// VIOLATION: Full serialization/parsing
-function processItem(item: Item) {
-  const copy = JSON.parse(JSON.stringify(item));  // Expensive!
-  // ... modify copy
-}
-```
-
----
-
-## I/O Violations
-
-### Blocking Operations
-
-**Sync File Operations in Request Handler**
-```typescript
-// VIOLATION: Blocks event loop
-app.get('/config', (req, res) => {
-  const config = fs.readFileSync('./config.json');  // Blocks!
-  res.json(JSON.parse(config));
-});
-```
-
-**Sync Crypto Operations**
-```typescript
-// VIOLATION: CPU-intensive sync operation
-function hashPassword(password: string): string {
-  return crypto.pbkdf2Sync(password, salt, 100000, 64, 'sha512');  // Blocks!
-}
-```
-
-### Sequential vs Parallel
-
-**await in forEach (No Parallelism)**
-```typescript
-// VIOLATION: forEach doesn't wait, unpredictable behavior
-ids.forEach(async (id) => {
-  await processItem(id);  // Fire and forget!
-});
-```
-
-**Sequential Processing When Order Doesn't Matter**
-```typescript
-// VIOLATION: Could be parallel
-async function validateAll(items: Item[]) {
-  const results = [];
-  for (const item of items) {
-    results.push(await validate(item));  // Sequential but independent
-  }
-  return results;
-}
-```
-
-### Redundant Operations
-
-**Same Data Fetched Multiple Times**
-```typescript
-// VIOLATION: Duplicate API calls
-async function buildReport(userId: string) {
-  const user = await getUser(userId);
-  const profile = await getUserProfile(userId);  // Probably same data
-  const permissions = await getUserPermissions(userId);  // Another call
-}
-```
-
-**Cache Miss on Every Request**
-```typescript
-// VIOLATION: No caching strategy
-async function getConfig() {
-  return await fetchFromRemote('/config');  // Network call every time
-}
-```
-
----
-
-## Frontend Violations
-
-### Re-render Patterns
-
-**Inline Object/Array in JSX**
-```tsx
-// VIOLATION: New reference every render
-<Component
-  options={{ show: true, animate: false }}  // New object each render
-  items={[1, 2, 3]}  // New array each render
-/>
-```
-
-**Inline Arrow in JSX**
-```tsx
-// VIOLATION: New function every render
-<Button onClick={() => handleClick(item.id)} />  // New function each render
-```
-
-**Missing Key or Index as Key**
-```tsx
-// VIOLATION: Index as key breaks reconciliation
-{items.map((item, index) => (
-  <Item key={index} {...item} />  // Index key causes issues on reorder
-))}
-```
-
-### Missing Optimization
-
-**Expensive Computation Every Render**
-```tsx
-// VIOLATION: Recalculates on every render
-function Dashboard({ data }) {
-  const stats = computeExpensiveStats(data);  // Runs every render
-  return <Stats data={stats} />;
-}
-```
-
-**Unthrottled Event Handler**
-```tsx
-// VIOLATION: Fires on every scroll pixel
-window.addEventListener('scroll', () => {
-  updateParallax();  // 60+ calls per second
-});
-```
-
-**Large Component Tree Without Code Splitting**
-```tsx
-// VIOLATION: Loads everything upfront
-import HugeChartLibrary from 'huge-chart-lib';
-import RarelyUsedFeature from './RarelyUsedFeature';
-// All loaded even if not used
-```

package/shared/skills/plan-orchestration/SKILL.md

@@ -1,71 +0,0 @@
----
-name: plan-orchestration
-description: Agent orchestration for PLAN intent — codebase orientation, design exploration, gap validation
-user-invocable: false
-allowed-tools: Read, Grep, Glob, Bash, Task, AskUserQuestion
----
-
-# Plan Orchestration
-
-Agent pipeline for PLAN intent in ambient ORCHESTRATED mode. Codebase orientation, targeted exploration, architecture design, and gap validation.
-
-This is a lightweight variant of the Plan phase in `/implement` for ambient ORCHESTRATED mode.
-
-## Iron Law
-
-> **PLANS WITHOUT CODEBASE GROUNDING ARE FANTASIES**
->
-> Orient before architecting. Every design decision must reference existing patterns,
-> real file structures, and actual integration points. A plan that ignores the codebase
-> will fail on contact with implementation.
-
----
-
-## Phase 1: Orient
-
-Spawn `Task(subagent_type="Skimmer")` to get codebase overview relevant to the planning question:
-
-- Existing patterns and conventions in the affected area
-- File structure and module boundaries
-- Test patterns and coverage approach
-- Related prior implementations (similar features, analogous patterns)
-
-## Phase 2: Explore
-
-Based on Skimmer findings, spawn 2-3 `Task(subagent_type="Explore")` agents **in a single message** (parallel execution):
-
-- **Integration explorer**: Examine integration points — APIs, shared types, module boundaries the plan must respect
-- **Pattern explorer**: Find existing implementations of similar features to follow as templates
-- **Constraint explorer**: Identify constraints — test infrastructure, build system, CI requirements, deployment concerns
-
-Adjust explorer focus based on the specific planning question.
-
-## Phase 3: Design
-
-Spawn `Task(subagent_type="Plan")` with combined Skimmer + Explore findings:
-
-- Design implementation approach with file-level specificity
-- Reference existing patterns discovered in Phase 1-2
-- Include: architecture decisions, file changes, new files needed, test strategy
-- Flag any areas where existing patterns conflict with the proposed approach
-
-## Phase 4: Validate
-
-Main session reviews the plan for:
-
-- **Gaps**: Missing files, unhandled edge cases, integration points not addressed
-- **Risks**: Areas where the plan deviates from existing patterns, potential regressions
-- **Ambiguities**: Design choices that need user input
-
-Present plan to user with identified risks. Use AskUserQuestion for any ambiguous design choices.
-
-## Output
-
-Structured plan ready to feed into IMPLEMENT/ORCHESTRATED if user proceeds:
-
-- Goal and scope
-- Architecture decisions with rationale
-- File-level change list (create/modify/delete)
-- Test strategy
-- Risks and mitigations
-- Open questions (if any)

package/shared/skills/python/SKILL.md

@@ -1,188 +0,0 @@
----
-name: python
-description: This skill should be used when the user works with Python files (.py), asks about "type hints", "protocols", "dataclasses", "async/await", "decorators", or discusses Pythonic patterns and data modeling. Provides patterns for type safety, error handling, data modeling, and async programming.
-user-invocable: false
-allowed-tools: Read, Grep, Glob
-activation:
-  file-patterns:
-    - "**/*.py"
-  exclude:
-    - "venv/**"
-    - ".venv/**"
-    - "**/__pycache__/**"
----
-
-# Python Patterns
-
-Reference for Python-specific patterns, type safety, and idioms.
-
-## Iron Law
-
-> **EXPLICIT IS BETTER THAN IMPLICIT**
->
-> Type-hint every function signature. Name every exception. Use dataclasses over raw dicts.
-> Python's flexibility is a strength only when boundaries are explicit. Implicit behavior
-> causes debugging nightmares and makes codebases hostile to newcomers.
-
-## When This Skill Activates
-
-- Working with Python codebases
-- Designing typed APIs with type hints
-- Modeling data with dataclasses or Pydantic
-- Implementing async code
-- Structuring Python packages
-
----
-
-## Type Safety
-
-### Type Hint Everything
-
-```python
-# BAD: def process(data, config): ...
-# GOOD:
-def process(data: list[dict[str, Any]], config: AppConfig) -> ProcessResult:
-    ...
-```
-
-### Use Protocols for Structural Typing
-
-```python
-from typing import Protocol
-
-class Repository(Protocol):
-    def find_by_id(self, id: str) -> User | None: ...
-    def save(self, entity: User) -> User: ...
-
-# Any class with these methods satisfies Repository — no inheritance needed
-```
-
-### Strict Optional Handling
-
-```python
-# BAD: def get_name(user): return user.name
-# GOOD:
-def get_name(user: User | None) -> str:
-    if user is None:
-        return "Anonymous"
-    return user.name
-```
-
----
-
-## Error Handling
-
-### Custom Exception Hierarchies
-
-```python
-class AppError(Exception):
-    """Base application error."""
-
-class NotFoundError(AppError):
-    def __init__(self, entity: str, id: str) -> None:
-        super().__init__(f"{entity} {id} not found")
-        self.entity = entity
-        self.id = id
-
-class ValidationError(AppError):
-    def __init__(self, field: str, message: str) -> None:
-        super().__init__(f"Validation failed for {field}: {message}")
-```
-
-### Context Managers for Resources
-
-```python
-from contextlib import contextmanager
-
-@contextmanager
-def database_transaction(conn: Connection):
-    try:
-        yield conn
-        conn.commit()
-    except Exception:
-        conn.rollback()
-        raise
-```
-
----
-
-## Data Modeling
-
-### Dataclasses Over Raw Dicts
-
-```python
-# BAD: user = {"name": "Alice", "email": "alice@example.com"}
-# GOOD:
-@dataclass(frozen=True)
-class User:
-    name: str
-    email: str
-    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
-```
-
-### Pydantic for Validation at Boundaries
-
-```python
-from pydantic import BaseModel, EmailStr
-
-class CreateUserRequest(BaseModel):
-    name: str
-    email: EmailStr
-    age: int = Field(ge=0, le=150)
-```
-
----
-
-## Pythonic Patterns
-
-```python
-# Comprehensions over loops for transforms
-names = [user.name for user in users if user.active]
-
-# Enumerate over manual index tracking
-for i, item in enumerate(items):
-    process(i, item)
-
-# EAFP: Easier to Ask Forgiveness than Permission
-try:
-    value = mapping[key]
-except KeyError:
-    value = default
-```
-
----
-
-## Anti-Patterns
-
-| Pattern | Bad | Good |
-|---------|-----|------|
-| Bare except | `except:` | `except (ValueError, KeyError):` |
-| Mutable default | `def fn(items=[])` | `def fn(items: list | None = None)` |
-| No type hints | `def process(data)` | `def process(data: DataFrame) -> Result` |
-| String typing | `x: "MyClass"` (without reason) | `from __future__ import annotations` |
-| God class | `class App` with 50 methods | Compose smaller focused classes |
-
----
-
-## Extended References
-
-For additional patterns and examples:
-- `references/violations.md` - Common Python violations
-- `references/patterns.md` - Extended Python patterns
-- `references/detection.md` - Detection patterns for Python issues
-- `references/async.md` - Async Python patterns
-
----
-
-## Checklist
-
-- [ ] All functions have type hints (params + return)
-- [ ] Custom exceptions with meaningful messages
-- [ ] Dataclasses or Pydantic for structured data
-- [ ] No bare `except:` clauses
-- [ ] No mutable default arguments
-- [ ] Context managers for resource management
-- [ ] `from __future__ import annotations` for forward refs
-- [ ] Protocols for structural typing (not ABC unless needed)
-- [ ] Comprehensions for simple transforms
-- [ ] Tests use pytest with fixtures