devflow-kit 0.9.0 → 1.0.0

package/shared/skills/documentation-patterns/references/patterns.md

@@ -0,0 +1,189 @@
+# Correct Documentation Patterns
+
+Extended examples of proper documentation. See parent `SKILL.md` for brief examples and severity guidelines.
+
+---
+
+## Code Documentation Patterns
+
+### Proper JSDoc for Complex Functions
+
+```typescript
+/**
+ * Calculates prorated billing amount when switching plans mid-cycle.
+ *
+ * @param plan - The new plan to prorate to
+ * @param startDate - When the new plan starts
+ * @param endDate - End of current billing cycle
+ * @param previousPlan - Optional previous plan for credit calculation
+ * @returns Prorated amount in cents (can be negative for downgrades)
+ *
+ * @example
+ * // Upgrading mid-month
+ * calculateProratedAmount(premiumPlan, new Date('2024-01-15'), new Date('2024-01-31'))
+ * // Returns: 1645 (cents)
+ *
+ * @throws {InvalidDateRangeError} If startDate is after endDate
+ */
+export function calculateProratedAmount(
+  plan: Plan,
+  startDate: Date,
+  endDate: Date,
+  previousPlan?: Plan
+): number {
+  // ...
+}
+```
+
+**Key elements**: Purpose, all params, return type with units, example usage, error conditions.
+
+### Comments That Explain "Why"
+
+```typescript
+// Filter to active users only - inactive users should not receive
+// promotional emails per GDPR consent requirements
+const activeUsers = users.filter(u => u.active);
+```
+
+**Key elements**: Business reason (GDPR), not mechanical description.
+
+### Algorithm Documentation
+
+```typescript
+/**
+ * Schedules tasks using weighted shortest job first (WSJF) algorithm.
+ *
+ * Priority score = (priority * urgency) / duration
+ * Higher scores are scheduled first.
+ *
+ * Tasks are placed starting 1.5x their duration before deadline
+ * to allow buffer for overruns.
+ *
+ * @see https://www.scaledagileframework.com/wsjf/
+ */
+function schedule(tasks: Task[]): Schedule {
+  // ...
+}
+```
+
+**Key elements**: Algorithm name, formula explanation, rationale for magic numbers, external reference.
+
+---
+
+## API Documentation Patterns
+
+### Complete Parameter Documentation
+
+```typescript
+/**
+ * Creates a new subscription for a user.
+ *
+ * @param userId - The unique identifier of the user
+ * @param planId - The plan to subscribe to (from /plans endpoint)
+ * @param options - Optional configuration
+ * @param options.trialDays - Number of trial days (default: 0, max: 30)
+ * @param options.couponCode - Discount coupon to apply
+ * @param options.startDate - When to start (default: now)
+ *
+ * @returns The created subscription with payment details
+ *
+ * @throws {UserNotFoundError} If userId doesn't exist
+ * @throws {PlanNotFoundError} If planId doesn't exist
+ * @throws {InvalidCouponError} If coupon is expired or invalid
+ */
+async function createSubscription(
+  userId: string,
+  planId: string,
+  options?: SubscriptionOptions
+): Promise<Subscription>;
+```
+
+**Key elements**: All params including nested options, defaults, constraints, all error types.
+
+### Return Value Documentation
+
+```typescript
+/**
+ * Fetches aggregated analytics data for the date range.
+ *
+ * @param range - Start and end dates for the query
+ * @returns Analytics data including:
+ *   - totalVisitors: Unique visitor count
+ *   - pageViews: Total page view count
+ *   - bounceRate: Percentage (0-100) of single-page sessions
+ *   - avgSessionDuration: Average session length in seconds
+ *   - topPages: Array of {path, views} sorted by views desc
+ */
+async function getAnalytics(range: DateRange): Promise<Analytics>;
+```
+
+**Key elements**: Shape of return object, units (percentage, seconds), sorting order.
+
+### Error Documentation
+
+```typescript
+/**
+ * Transfers funds between accounts.
+ *
+ * @throws {InsufficientFundsError} If source account balance < amount
+ * @throws {AccountNotFoundError} If either account doesn't exist
+ * @throws {AccountFrozenError} If either account is frozen
+ * @throws {TransferLimitError} If amount exceeds daily transfer limit
+ * @throws {SameAccountError} If from === to
+ */
+async function transferFunds(from: string, to: string, amount: number): Promise<void>;
+```
+
+**Key elements**: All possible error types with conditions that trigger them.
+
+---
+
+## Alignment Patterns
+
+### Constants Instead of Magic Numbers
+
+```typescript
+const MAX_RETRIES = 5;
+
+// Retries up to MAX_RETRIES times with exponential backoff
+async function fetchWithRetry(url: string) {
+  for (let i = 0; i < MAX_RETRIES; i++) { /* ... */ }
+}
+```
+
+**Key elements**: Named constant keeps comment and code in sync automatically.
+
+### Up-to-Date README
+
+```markdown
+## Installation
+npm install mypackage@^2.0.0
+
+## Usage
+import { newFunction } from 'mypackage';
+await newFunction({ /* new options */ });
+
+## Migration from v1
+See [MIGRATION.md](./MIGRATION.md) for upgrade instructions.
+```
+
+**Key elements**: Correct version, working examples, migration guidance.
+
+### Proper Changelog
+
+```markdown
+## [2.0.0] - 2024-01-15
+
+### Breaking Changes
+- `createUser()` now returns `Promise<Result<User>>` instead of `Promise<User>`
+- Removed deprecated `oldFunction()` - use `newFunction()` instead
+- Minimum Node.js version is now 18
+
+### Added
+- New `validateUser()` function for input validation
+
+### Changed
+- Improved error messages for authentication failures
+```
+
+**Key elements**: Breaking changes highlighted first, migration hints, categorized changes.

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

@@ -0,0 +1,163 @@
+# Documentation Violation Examples
+
+Extended examples of documentation anti-patterns. See parent `SKILL.md` for brief examples and severity guidelines.
+
+---
+
+## Code Documentation Violations
+
+### Missing Docstrings/JSDoc
+
+```typescript
+// VIOLATION: Complex function without documentation
+export function calculateProratedAmount(
+  plan: Plan,
+  startDate: Date,
+  endDate: Date,
+  previousPlan?: Plan
+): number {
+  // 50 lines of complex billing logic...
+}
+```
+
+**Why it's a problem**: Complex billing logic with edge cases (negative amounts for downgrades, credit calculations) is impossible to use correctly without documentation.
+
+### Outdated Comments
+
+```typescript
+// VIOLATION: Comment doesn't match code
+// Returns user's full name
+function getDisplayName(user: User): string {
+  return user.username;  // Actually returns username, not full name!
+}
+
+// VIOLATION: TODO that's been done
+// TODO: Add validation
+function processInput(input: string) {
+  if (!isValid(input)) throw new Error('Invalid');  // Validation exists!
+  // ...
+}
+```
+
+**Why it's a problem**: Misleading comments cause bugs when developers trust them over reading the code.
+
+### Comments Explaining "What" Instead of "Why"
+
+```typescript
+// VIOLATION: Describes what code does (obvious from code)
+// Loop through users
+for (const user of users) {
+  // Check if user is active
+  if (user.active) {
+    // Add user to list
+    activeUsers.push(user);
+  }
+}
+```
+
+**Why it's a problem**: These comments add noise without value. The code already says what it does.
+
+### Complex Code Without Explanation
+
+```typescript
+// VIOLATION: Magic algorithm without explanation
+function schedule(tasks: Task[]): Schedule {
+  return tasks
+    .sort((a, b) => (b.priority * b.urgency) / b.duration - (a.priority * a.urgency) / a.duration)
+    .reduce((schedule, task) => {
+      const slot = findSlot(schedule, task, task.deadline - task.duration * 1.5);
+      return slot ? addToSchedule(schedule, task, slot) : schedule;
+    }, emptySchedule());
+}
+```
+
+**Why it's a problem**: The WSJF algorithm and 1.5x buffer are non-obvious. Future maintainers will be confused or afraid to modify.
+
+---
+
+## API Documentation Violations
+
+### Missing Parameter Descriptions
+
+```typescript
+// VIOLATION: Parameters unexplained
+/**
+ * Creates a new subscription.
+ */
+async function createSubscription(
+  userId: string,
+  planId: string,
+  options?: SubscriptionOptions
+): Promise<Subscription>;
+```
+
+**Why it's a problem**: Callers don't know valid values for `planId`, what `options` are available, or constraints on parameters.
+
+### Missing Return Value Documentation
+
+```typescript
+// VIOLATION: Return shape unknown
+/**
+ * Fetches analytics data.
+ */
+async function getAnalytics(range: DateRange): Promise<Analytics>;
+```
+
+**Why it's a problem**: Consumers must read implementation to understand the shape of `Analytics`.
+
+### Missing Error Documentation
+
+```typescript
+// VIOLATION: Errors not documented
+async function transferFunds(from: string, to: string, amount: number): Promise<void>;
+```
+
+**Why it's a problem**: Callers don't know what errors to catch or handle. They'll either catch everything or miss important cases.
+
+---
+
+## Alignment Violations
+
+### Code-Comment Drift
+
+```typescript
+// BEFORE: Comment matches
+// Retries up to 3 times with exponential backoff
+async function fetchWithRetry(url: string) {
+  for (let i = 0; i < 3; i++) { /* ... */ }
+}
+
+// AFTER: Code changed, comment didn't
+// Retries up to 3 times with exponential backoff
+async function fetchWithRetry(url: string) {
+  for (let i = 0; i < 5; i++) { /* ... */ }  // Now 5 retries!
+}
+```
+
+**Why it's a problem**: Developers relying on the comment will expect different behavior than actual.
+
+### Stale README
+
+```markdown
+<!-- VIOLATION: README doesn't reflect reality -->
+
+## Installation
+npm install mypackage
+
+## Usage
+const { oldFunction } = require('mypackage');
+oldFunction(); // This function was removed!
+```
+
+**Why it's a problem**: New users follow outdated instructions and immediately hit errors.
+
+### Missing Changelog Entries
+
+```markdown
+<!-- VIOLATION: Breaking change not documented -->
+
+## [2.0.0] - 2024-01-15
+- Updated dependencies
+```
+
+**Why it's a problem**: Users upgrading have no warning about breaking changes and no migration path.

package/shared/skills/frontend-design/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: frontend-design
+description: This skill should be used when the user asks to "design a component", "pick colors", "improve typography", "fix spacing", "choose a layout", or discusses visual design, CSS, styling decisions, or responsive interfaces. Provides patterns for typography scales, color systems, spacing, and production-grade UI design.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+activation:
+  file-patterns:
+    - "**/*.tsx"
+    - "**/*.jsx"
+    - "**/*.css"
+    - "**/*.scss"
+    - "**/tailwind.config.*"
+  exclude:
+    - "node_modules/**"
+    - "**/*.test.*"
+    - "**/*.spec.*"
+---
+
+# Frontend Design Patterns
+
+Reference for intentional visual design, following Anthropic's 4 Dimensions framework. Focus on deliberate aesthetic choices over default slop.
+
+## Iron Law
+
+> **AESTHETICS MUST HAVE INTENT**
+>
+> Every visual choice must be justified. Default styles, copied gradients, and
+> "looks modern" are not justifications. If you cannot explain why a specific
+> font, color, or animation exists, it's design debt. Good design is invisible
+> because it serves purpose, not because it copies trends.
+
+## When This Skill Activates
+
+- Creating or styling UI components
+- Reviewing CSS, Tailwind, or styled-components
+- Discussing typography, color schemes, or layouts
+- Building design systems or component libraries
+- Evaluating visual consistency
+
+---
+
+## 1. Typography Intent
+
+### Font Personality Must Match Product
+
+```css
+/* CORRECT: Deliberate choice with rationale */
+/* Product: Developer documentation - needs readability */
+font-family: 'IBM Plex Mono', 'JetBrains Mono', monospace;
+
+/* VIOLATION: Inter because "everyone uses it" */
+font-family: 'Inter', sans-serif; /* Why? What does it communicate? */
+```
+
+### Clear Hierarchy
+
+```css
+/* CORRECT: Distinct visual hierarchy */
+.heading-1 { font-size: 2.5rem; font-weight: 700; letter-spacing: -0.02em; }
+.heading-2 { font-size: 1.75rem; font-weight: 600; letter-spacing: -0.01em; }
+.body { font-size: 1rem; font-weight: 400; line-height: 1.6; }
+.caption { font-size: 0.875rem; font-weight: 400; color: var(--text-muted); }
+
+/* VIOLATION: No hierarchy - everything similar */
+.text { font-size: 1rem; }
+.text-big { font-size: 1.1rem; }
+```
+
+### Line Height Tuning
+
+```css
+/* CORRECT: Context-appropriate line height */
+.heading { line-height: 1.2; }  /* Tight for short headings */
+.body { line-height: 1.6; }     /* Comfortable for reading */
+.code { line-height: 1.4; }     /* Balanced for code */
+
+/* VIOLATION: Universal line height */
+* { line-height: 1.5; }
+```
+
+---
+
+## 2. Color and Theme
+
+### Deliberate Palette
+
+```css
+/* CORRECT: Semantic color system with clear purpose */
+:root {
+  --color-primary: #0066cc;     /* Actions, links - trust/stability */
+  --color-success: #0a6640;     /* Positive outcomes */
+  --color-warning: #b35900;     /* Attention needed */
+  --color-error: #c41e3a;       /* Errors, destructive */
+  --color-neutral-900: #1a1a1a; /* Primary text */
+  --color-neutral-500: #6b7280; /* Secondary text */
+  --color-neutral-100: #f5f5f5; /* Backgrounds */
+}
+
+/* VIOLATION: Random hex values without system */
+.button { background: #4f46e5; }
+.link { color: #3b82f6; }
+.alert { background: #ef4444; }
+```
+
+### Light/Dark as First-Class
+
+```css
+/* CORRECT: Design for both modes intentionally */
+:root {
+  --bg-primary: #ffffff;
+  --text-primary: #1a1a1a;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg-primary: #0f0f0f;
+    --text-primary: #f5f5f5;
+  }
+}
+
+/* VIOLATION: Dark mode as afterthought */
+.dark-mode { filter: invert(1); }
+```
+
+---
+
+## 3. Motion and Animation
+
+### State Communication
+
+```css
+/* CORRECT: Animation communicates state change */
+.button {
+  transition: transform 0.1s ease-out, background 0.15s ease;
+}
+.button:active {
+  transform: scale(0.98); /* Feedback: "I received your click" */
+}
+
+/* VIOLATION: Animation for decoration */
+.button {
+  animation: pulse 2s infinite; /* Why is it pulsing? */
+}
+```
+
+### Consistent Timing
+
+```css
+/* CORRECT: Timing scale for consistency */
+:root {
+  --duration-fast: 100ms;   /* Micro-interactions */
+  --duration-normal: 200ms; /* Standard transitions */
+  --duration-slow: 300ms;   /* Complex animations */
+  --easing-default: cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+/* VIOLATION: Random durations */
+.modal { transition: 0.35s; }
+.dropdown { transition: 0.2s; }
+.tooltip { transition: 0.15s; }
+```
+
+### Appropriate Duration
+
+| Element | Duration | Rationale |
+|---------|----------|-----------|
+| Hover states | 100-150ms | Immediate feedback |
+| Dropdowns | 150-200ms | Quick but perceptible |
+| Modals | 200-300ms | Significant context change |
+| Page transitions | 300-500ms | Major navigation |
+
+---
+
+## 4. Spatial Composition
+
+### Consistent Spacing Scale
+
+```css
+/* CORRECT: Mathematical spacing system */
+:root {
+  --space-1: 0.25rem;  /* 4px */
+  --space-2: 0.5rem;   /* 8px */
+  --space-3: 0.75rem;  /* 12px */
+  --space-4: 1rem;     /* 16px */
+  --space-6: 1.5rem;   /* 24px */
+  --space-8: 2rem;     /* 32px */
+  --space-12: 3rem;    /* 48px */
+}
+
+/* VIOLATION: Magic numbers */
+.card { padding: 18px 22px; margin-bottom: 13px; }
+```
+
+### Whitespace With Purpose
+
+```css
+/* CORRECT: Whitespace creates visual grouping */
+.section { margin-bottom: var(--space-12); }
+.section-header { margin-bottom: var(--space-6); }
+.paragraph { margin-bottom: var(--space-4); }
+
+/* VIOLATION: Uniform spacing (no hierarchy) */
+* + * { margin-top: 1rem; }
+```
+
+---
+
+## AI Slop Detection
+
+Flag these patterns - they indicate thoughtless defaults:
+
+| Pattern | Problem |
+|---------|---------|
+| Purple-to-pink gradient | Copied from templates without brand justification |
+| `font-family: Inter` without rationale | Default choice, not intentional |
+| Everything centered | No visual hierarchy or flow |
+| `rounded-xl` on everything | Border radius should vary by context |
+| Shadows on everything | Elevation should be meaningful |
+| Generic "hero section" with gradient | Template copy, not designed |
+| `animate-pulse` on buttons | Meaningless attention grab |
+| Glassmorphism everywhere | Trend following, not purpose |
+
+---
+
+## Extended References
+
+For additional patterns and examples:
+- `references/violations.md` - Extended design anti-patterns
+- `references/patterns.md` - Extended correct patterns
+- `references/detection.md` - Grep patterns for finding issues
+
+---
+
+## Severity Guidelines
+
+| Severity | Criteria |
+|----------|----------|
+| CRITICAL | No design system (random values everywhere) |
+| HIGH | Inconsistent spacing/typography, broken dark mode |
+| MEDIUM | Missing hover states, poor visual hierarchy |
+| LOW | Could improve animation timing, minor inconsistencies |
+
+---
+
+## Checklist
+
+- [ ] Typography choices have documented rationale
+- [ ] Color palette is semantic (not arbitrary hex)
+- [ ] Dark/light modes both intentionally designed
+- [ ] Spacing follows consistent scale
+- [ ] Animations communicate state (not decoration)
+- [ ] No "AI slop" patterns present
+- [ ] Visual hierarchy is clear
+- [ ] Responsive behavior is intentional