devflow-kit 0.3.2 → 0.4.0

package/src/claude/skills/devflow/code-smell/SKILL.md

@@ -0,0 +1,428 @@
+---
+name: code-smell
+description: Automatically detect anti-patterns, fake solutions, and workarounds when implementing functionality. Use when adding new features, reviewing code changes, or when suspicious patterns appear. Enforces honest, production-ready solutions.
+allowed-tools: Read, Grep, Glob
+---
+
+# Code Smell Skill
+
+## Purpose
+
+Detect and prevent anti-patterns that indicate fake solutions or workarounds:
+1. **Hardcoded data** - Simulating functionality instead of implementing
+2. **Missing labels** - Workarounds without clear documentation
+3. **Fake solutions** - Code that pretends to work but doesn't
+4. **Magic values** - Unexplained constants and configuration
+
+## When This Skill Activates
+
+Automatically triggers when:
+- New functionality is being implemented
+- Code changes are being made
+- Mock data or test fixtures appear outside tests
+- Comments suggesting temporary solutions
+- Configuration or constants are added
+
+## Critical Anti-Patterns
+
+### 1. Hardcoded Data Detection (FAKE SOLUTIONS)
+
+**CRITICAL**: Never hardcode responses to simulate working functionality.
+
+```typescript
+// ❌ VIOLATION: Fake solution pretending to work
+async function getUserProfile(userId: string): Promise<UserProfile> {
+  // HACK: Hardcoded response until API is ready
+  return {
+    id: userId,
+    name: "John Doe",
+    email: "john@example.com",
+    avatar: "https://example.com/default.jpg"
+  };
+}
+
+// ❌ VIOLATION: Mock data masquerading as real functionality
+async function fetchRecommendations(userId: string): Promise<Product[]> {
+  // TODO: Connect to recommendation engine
+  return [
+    { id: "1", name: "Product 1", price: 99.99 },
+    { id: "2", name: "Product 2", price: 149.99 }
+  ];
+}
+
+// ✅ CORRECT: Honest implementation or explicit mock
+async function getUserProfile(userId: string): Promise<Result<UserProfile, Error>> {
+  try {
+    const response = await api.get(`/users/${userId}`);
+    return { ok: true, value: response.data };
+  } catch (error) {
+    return { ok: false, error };
+  }
+}
+
+// ✅ CORRECT: Clearly labeled mock for testing
+// MOCK: For development only, not production-ready
+async function getUserProfileMock(userId: string): Promise<UserProfile> {
+  return {
+    id: userId,
+    name: "Test User",
+    email: "test@example.com"
+  };
+}
+```
+
+**Detection patterns:**
+- Hardcoded return objects in business functions
+- Static arrays/objects returned from "fetch" functions
+- Functions with only return statements (no actual logic)
+- Comments like "TODO: implement" with fake data below
+- Default values that look like real data
+
+### 2. Missing Label Detection (UNDOCUMENTED WORKAROUNDS)
+
+**CRITICAL**: All workarounds, hacks, and temporary solutions MUST be labeled.
+
+```typescript
+// ❌ VIOLATION: Workaround without label
+function processPayment(amount: number): boolean {
+  // Skip validation for now
+  return true;
+}
+
+// ❌ VIOLATION: Temporary fix without documentation
+async function syncData() {
+  await sleep(1000); // Wait for previous operation
+  await performSync();
+}
+
+// ❌ VIOLATION: Hack without explanation
+function getUserPermissions(userId: string): string[] {
+  if (userId === "admin") return ["*"]; // Give admin all permissions
+  return ["read"];
+}
+
+// ✅ CORRECT: Clearly labeled workaround
+function processPayment(amount: number): boolean {
+  // TEMPORARY: Validation disabled until payment gateway integration complete
+  // TODO: Add amount validation, currency checks, fraud detection
+  // Target: Sprint 23 (2025-11-15)
+  // Ticket: PAY-456
+  return true;
+}
+
+// ✅ CORRECT: Documented hack with rationale
+async function syncData() {
+  // HACK: Sleep required due to race condition in legacy sync system
+  // Root cause: Event system doesn't guarantee order
+  // Proper fix: Implement event sequencing (3-week effort)
+  // Acceptable: Race condition occurs <0.1% of operations
+  await sleep(1000);
+  await performSync();
+}
+
+// ✅ CORRECT: Explicit exception with justification
+function getUserPermissions(userId: string): string[] {
+  // ARCHITECTURE EXCEPTION: Hardcoded admin check
+  // Justification: Permission system must work if database is down
+  // Security review: Approved 2025-09-01 (ticket SEC-789)
+  if (userId === "admin") return ["*"];
+  return ["read"];
+}
+```
+
+**Required labels:**
+- `HACK:` - Workaround for specific problem
+- `MOCK:` - Fake data for testing/development
+- `TODO:` - Work that needs to be done
+- `TEMPORARY:` - Short-term solution with deadline
+- `NOT-PRODUCTION:` - Code that should never ship
+- `ARCHITECTURE EXCEPTION:` - Violates pattern with justification
+
+**Detection patterns:**
+- Comments without required labels
+- Suspicious code without documentation
+- Empty catch blocks without explanation
+- Early returns without rationale
+- Magic numbers without explanation
+
+### 3. Fake Functionality Detection (DECEPTIVE CODE)
+
+**CRITICAL**: Code must actually work or be clearly marked as non-functional.
+
+```typescript
+// ❌ VIOLATION: Pretending to validate but doing nothing
+function validateEmail(email: string): boolean {
+  // Just accept anything for now
+  return true;
+}
+
+// ❌ VIOLATION: Fake error handling
+async function sendEmail(to: string, subject: string, body: string): Promise<void> {
+  try {
+    // TODO: Implement SMTP
+    console.log(`Email sent to ${to}`);
+  } catch (error) {
+    // Ignore errors
+  }
+}
+
+// ❌ VIOLATION: Simulated async operation
+async function fetchData(url: string): Promise<any> {
+  await new Promise(resolve => setTimeout(resolve, 100)); // Fake loading time
+  return { success: true, data: [] }; // Fake response
+}
+
+// ✅ CORRECT: Honest unimplemented function
+function validateEmail(email: string): Result<boolean, Error> {
+  return {
+    ok: false,
+    error: new Error('NOT-IMPLEMENTED: Email validation pending regex pattern approval')
+  };
+}
+
+// ✅ CORRECT: Real implementation or clear mock
+// MOCK: Email service for development (replace before production)
+async function sendEmailMock(to: string, subject: string, body: string): Promise<Result<void, Error>> {
+  console.log(`[MOCK EMAIL] To: ${to}, Subject: ${subject}`);
+  return { ok: true, value: undefined };
+}
+
+// Real implementation
+async function sendEmailReal(to: string, subject: string, body: string): Promise<Result<void, Error>> {
+  try {
+    await smtpClient.send({ to, subject, body });
+    return { ok: true, value: undefined };
+  } catch (error) {
+    return { ok: false, error: error as Error };
+  }
+}
+```
+
+**Detection patterns:**
+- Functions that return `true` with no logic
+- Empty try/catch blocks
+- Console.log masquerading as functionality
+- setTimeout used to simulate async operations
+- Functions with only TODO comments inside
+
+### 4. Magic Value Detection (UNEXPLAINED CONSTANTS)
+
+**CRITICAL**: All magic values must be explained with constants or comments.
+
+```typescript
+// ❌ VIOLATION: Magic numbers
+function calculateDiscount(price: number, userLevel: number): number {
+  if (userLevel >= 5) {
+    return price * 0.15;
+  } else if (userLevel >= 3) {
+    return price * 0.10;
+  }
+  return 0;
+}
+
+// ❌ VIOLATION: Magic strings
+function getUserRole(userId: string): string {
+  const user = getUser(userId);
+  if (user.permissions.includes("admin_access")) {
+    return "admin";
+  }
+  return "user";
+}
+
+// ❌ VIOLATION: Magic configuration
+setTimeout(() => {
+  retryOperation();
+}, 5000);
+
+// ✅ CORRECT: Named constants with documentation
+const USER_LEVEL_THRESHOLD = {
+  PREMIUM: 5,      // Premium tier: $50/month subscribers
+  STANDARD: 3,     // Standard tier: $20/month subscribers
+  FREE: 0          // Free tier
+} as const;
+
+const DISCOUNT_RATE = {
+  PREMIUM: 0.15,   // 15% discount for premium users
+  STANDARD: 0.10,  // 10% discount for standard users
+  NONE: 0
+} as const;
+
+function calculateDiscount(price: number, userLevel: number): number {
+  if (userLevel >= USER_LEVEL_THRESHOLD.PREMIUM) {
+    return price * DISCOUNT_RATE.PREMIUM;
+  } else if (userLevel >= USER_LEVEL_THRESHOLD.STANDARD) {
+    return price * DISCOUNT_RATE.STANDARD;
+  }
+  return DISCOUNT_RATE.NONE;
+}
+
+// ✅ CORRECT: Explicit role constants
+enum UserRole {
+  ADMIN = "admin",
+  USER = "user"
+}
+
+const PERMISSION_ROLE_MAP = {
+  "admin_access": UserRole.ADMIN,
+  "user_access": UserRole.USER
+} as const;
+
+// ✅ CORRECT: Configuration with rationale
+const RETRY_CONFIG = {
+  // Retry after 5 seconds to allow rate limit reset
+  // Based on API documentation: 10 requests per minute
+  DELAY_MS: 5000,
+  MAX_ATTEMPTS: 3
+} as const;
+```
+
+**Detection patterns:**
+- Numeric literals in business logic (except 0, 1, -1)
+- String literals compared in conditionals
+- Unexplained timeouts or delays
+- Array indices without explanation
+- Percentage or ratio calculations without constants
+
+## Code Smell Report Format
+
+```markdown
+🚨 CODE SMELLS DETECTED
+
+## 🔴 CRITICAL - Fake Solution
+**File**: src/services/user.ts:45
+**Issue**: Hardcoded user data pretending to fetch from API
+**Evidence**:
+```typescript
+async function getUserProfile(userId: string) {
+  return { id: userId, name: "John Doe", email: "john@example.com" };
+}
+```
+**Problem**: This code pretends to work but returns fake data
+**Impact**: Will fail in production, misleads other developers
+**Action**: Either implement real API call or label as MOCK
+
+## 🔴 CRITICAL - Unlabeled Workaround
+**File**: src/utils/sync.ts:23
+**Issue**: Sleep statement without explanation
+**Evidence**:
+```typescript
+await sleep(1000);
+await performSync();
+```
+**Problem**: Workaround without documentation of why it's needed
+**Required**: Add HACK: label explaining race condition
+**Action**: Document the workaround or fix the root cause
+
+## 🔴 CRITICAL - Deceptive Validation
+**File**: src/validation/email.ts:12
+**Issue**: Validation function that doesn't validate
+**Evidence**:
+```typescript
+function validateEmail(email: string): boolean {
+  return true; // Accept anything for now
+}
+```
+**Problem**: Function name promises validation but does nothing
+**Impact**: Security risk, data quality issues
+**Action**: Implement validation or return NotImplementedError
+
+## 🟡 HIGH - Magic Values
+**File**: src/billing/discount.ts:34
+**Issue**: Unexplained discount percentages
+**Evidence**:
+```typescript
+if (userLevel >= 5) return price * 0.15;
+```
+**Problem**: Magic numbers without explanation
+**Action**: Extract to named constants with documentation
+
+## 📊 Summary
+- **Critical**: 8 fake solutions detected
+- **Critical**: 5 unlabeled workarounds
+- **High**: 12 magic values
+- **Files affected**: 9
+
+## 🛑 HONESTY CHECK FAILED
+
+This code violates the "NO FAKE SOLUTIONS" principle:
+- Functions pretend to work but return hardcoded data
+- Workarounds exist without clear documentation
+- Magic values indicate rushed implementation
+
+## ✅ Required Actions
+
+1. **Label all workarounds** - Add HACK:/TEMPORARY:/MOCK: labels
+2. **Remove fake solutions** - Implement real functionality or mark as NOT-PRODUCTION
+3. **Document magic values** - Extract to named constants
+4. **Be transparent** - If something doesn't work, say so clearly
+
+## 🎯 Example Fix
+
+Before:
+```typescript
+async function getRecommendations(userId: string) {
+  return [{ id: "1", name: "Product 1" }];
+}
+```
+
+After (honest):
+```typescript
+// MOCK: Recommendations service not yet implemented
+// TODO: Integrate with ML recommendation engine (ticket: REC-123)
+// Target: Sprint 25
+// NOT-PRODUCTION: This will fail in production
+async function getRecommendationsMock(userId: string): Promise<Product[]> {
+  return [
+    { id: "1", name: "Mock Product 1", price: 99.99 }
+  ];
+}
+
+// Proper implementation
+async function getRecommendations(userId: string): Promise<Result<Product[], Error>> {
+  return {
+    ok: false,
+    error: new Error('NOT-IMPLEMENTED: Awaiting ML service deployment')
+  };
+}
+```
+```
+
+## Integration with Quality Gates
+
+This skill prevents:
+- Merging fake functionality to main branch
+- Deploying unlabeled workarounds to production
+- Shipping code that pretends to work
+- Accumulating technical debt without documentation
+
+## Red Flags - Immediate Stop
+
+Stop immediately if you detect:
+- Multiple fake solutions in same PR
+- Production code with MOCK: labels
+- Security-critical functions returning true without logic
+- Database operations with hardcoded responses
+- API clients returning static data
+
+## Success Criteria
+
+Code passes smell check when:
+- ✅ No hardcoded return data in business logic
+- ✅ All workarounds have required labels
+- ✅ All fake/mock code clearly marked
+- ✅ Magic values extracted to named constants
+- ✅ Comments include rationale and timeline
+- ✅ Functions do what their names promise
+
+## Philosophy Enforcement
+
+This skill enforces the core principle:
+
+**"NO FAKE SOLUTIONS - Never hardcode responses or data to simulate working functionality"**
+
+Code must either:
+1. Work correctly (real implementation)
+2. Fail honestly (return error explaining what's missing)
+3. Be clearly labeled (MOCK:, TEMPORARY:, NOT-PRODUCTION:)
+
+No middle ground. No deception.

package/src/claude/skills/devflow/debug/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: debug
+description: Auto-launch systematic debugging when errors, crashes, or failures occur. Use when encountering exceptions, failed tests, build errors, or unexpected behavior that needs investigation.
+allowed-tools: Task
+---
+
+# Debug Skill - Auto-Dispatcher
+
+**Purpose**: Detect when systematic debugging is needed and auto-launch the debug agent.
+
+## When to Activate
+
+Auto-activates when:
+- Errors or exceptions encountered
+- Tests failing
+- Build/compilation errors
+- Application crashes
+- Unexpected behavior needs investigation
+- User mentions "broken", "not working", "failing"
+
+## Lightweight Assessment
+
+```markdown
+Quick check (don't do heavy analysis):
+1. Is this a simple typo/syntax error? → Fix inline
+2. Is this a complex/unclear issue? → Launch debug agent
+3. Are there multiple potential causes? → Launch debug agent
+```
+
+## Decision Logic
+
+**Fix inline** (simple issues):
+- Syntax errors with clear fix
+- Typos in variable names
+- Missing imports
+- Simple logic errors
+
+**Launch debug agent** (complex issues):
+- Unknown root cause
+- Multiple symptoms
+- Intermittent failures
+- Performance degradation
+- System-level issues
+- Requires investigation
+
+## Auto-Launch Debug Agent
+
+When debugging is needed:
+
+```
+I've detected [error type] that requires systematic debugging.
+
+**Issue**: [brief description]
+**Symptoms**: [what's happening]
+
+Launching debug agent for systematic investigation...
+```
+
+Then launch the debug agent using Task tool:
+
+```
+Task(
+  subagent_type="debug",
+  description="Debug systematic analysis",
+  prompt="Systematically debug the following issue: [issue description].
+
+  Current symptoms: [symptoms]
+  Error messages: [if any]
+  Context: [relevant context]"
+)
+```
+
+## Post-Agent Summary
+
+After agent completes, summarize key findings:
+
+```markdown
+🔍 **Debug Session Complete**
+
+**Root Cause**: [from agent findings]
+**Fix Applied**: [solution]
+**Prevention**: [how to avoid]
+**Documentation**: `.docs/debug/[session-id].md`
+```
+
+## Examples
+
+**Example 1: Simple - Fix Inline**
+```
+User: "Getting error: Cannot find module 'fs'"
+Skill: "Missing import. Adding: import fs from 'fs'"
+[Fixes inline, no agent needed]
+```
+
+**Example 2: Complex - Launch Agent**
+```
+User: "Tests passing locally but failing in CI"
+Skill: "This requires investigation of environment differences.
+Launching debug agent..."
+[Launches debug agent for systematic analysis]
+```
+
+**Example 3: Unclear - Launch Agent**
+```
+User: "App crashes randomly after 5 minutes"
+Skill: "Intermittent crash requires systematic debugging.
+Launching debug agent to investigate..."
+[Launches debug agent]
+```
+
+## Key Points
+
+- **Lightweight**: Skill does minimal assessment (~20 lines)
+- **Smart dispatch**: Knows when to fix vs investigate
+- **No heavy analysis**: Delegates to debug agent
+- **Autonomous**: Auto-launches without asking
+- **Clean context**: Main session stays focused
+
+This keeps the main session clean while ensuring systematic debugging happens when needed.