claudify-agent 0.0.0-stage → 1.0.0

package/.claude/skills/learning-loop/SKILL.md

@@ -0,0 +1,308 @@
+# SKILL.md: Learning Loop
+
+## Description
+Analyzes plan metrics to identify patterns, detect repeated mistakes, and suggest continuous improvements based on historical execution data.
+
+## When to Use
+- Weekly review of plan performance
+- After detecting repeated failures
+- When plan accuracy drops below threshold
+- Proactive optimization of workflows
+
+## Capabilities
+- Pattern recognition from metrics
+- Anti-pattern detection
+- Repeated mistake identification
+- Trend analysis
+- Improvement recommendations
+- Rule update suggestions
+
+## Commands
+/learning-loop-analyze: Full pattern analysis
+/learning-loop-weekly: Weekly performance review
+/learning-loop-suggest: Generate improvement suggestions
+/learning-loop-patterns: Show detected anti-patterns
+
+## Workflows
+
+### Weekly Analysis Workflow
+
+1. **Load Metrics** (30s)
+   ```bash
+   Read: .cursor/plan-metrics.json
+   ```
+   - Last 10-20 plan executions
+   - Extract key metrics
+
+2. **Pattern Detection** (60s)
+   - Run anti-pattern detection rules
+   - Identify repeated mistakes
+   - Calculate trends
+
+3. **Analysis Report** (30s)
+   ```markdown
+   ## Weekly Learning Report
+   
+   ### Performance Summary
+   - Avg Accuracy: X% (trend: ↑/↓/→)
+   - Avg Iterations: X (target: <2)
+   - Tool Efficiency: X% (target: >70%)
+   
+   ### Detected Anti-Patterns
+   1. [SEVERITY] Pattern name
+      - Suggestion: ...
+   
+   ### Repeated Mistakes
+   - Mistake 1 (count: X)
+   - Mistake 2 (count: X)
+   
+   ### Top 3 Improvements
+   1. [Action item]
+   2. [Action item]
+   3. [Action item]
+   
+   ### Rule Update Suggestions
+   - Suggest updating: .cursor/rules/[file]
+   - Reason: [pattern detected]
+   ```
+
+4. **Action Items** (30s)
+   - Prioritize top 3 improvements
+   - Create tasks for rule updates
+   - Schedule follow-up review
+
+### Anti-Pattern Detection
+
+The skill detects these anti-patterns automatically:
+
+1. **Over-Engineering** (High)
+   - Using expensive tools when cheap alternatives work
+   - Detection: avg tool efficiency < 50% over 3 plans
+   - Fix: Follow tool escalation protocol
+
+2. **Planning Without Research** (Critical)
+   - Creating plans without SemanticSearch
+   - Detection: No SemanticSearch in last 3 plans
+   - Fix: Always research before planning
+
+3. **Repeated Execution Failures** (Critical)
+   - Multiple consecutive low-accuracy plans
+   - Detection: 2+ plans with <60% accuracy
+   - Fix: Improve validation process
+
+4. **MCP Overuse** (Medium)
+   - Using MCP tools unnecessarily
+   - Detection: High MCP usage + low accuracy
+   - Fix: Use MCP only when essential
+
+5. **Skipping Validation** (High)
+   - Not running ReadLints/tests
+   - Detection: No validation tools in 3 plans
+   - Fix: Auto-validate after changes
+
+6. **Context Bloat** (Medium)
+   - Loading too much context
+   - Detection: Low efficiency + high iterations
+   - Fix: Apply tiered injection, minimalism
+
+### Trend Analysis
+
+Analyzes performance trends:
+
+```typescript
+if (secondHalfAvg > firstHalfAvg + 5) {
+  trend = "improving";
+  // Reinforce what's working
+} else if (secondHalfAvg < firstHalfAvg - 5) {
+  trend = "declining";
+  // Investigate root causes
+} else {
+  trend = "stable";
+  // Look for optimization opportunities
+}
+```
+
+## Examples
+
+### Example 1: Weekly Review
+
+User: "/learning-loop-weekly"
+
+Agent analyzes last 10 plans:
+
+```markdown
+## Weekly Learning Report (Mar 23-30, 2026)
+
+### Performance Summary
+- Avg Accuracy: 82.5% (↑ +5.2% from last week)
+- Avg Iterations: 1.8 (↓ -0.5, improving)
+- Tool Efficiency: 75.0% (→ stable)
+- Avg Parallel Subagents: 2.3
+
+### Wins This Week
+✅ Accuracy improved above 80% threshold
+✅ Iteration count decreasing
+✅ MCP usage correlated with success
+
+### Detected Anti-Patterns
+1. [MEDIUM] MCP Overuse (2 occurrences)
+   - Suggestion: Use MCP tools only when essential
+
+### Repeated Mistakes
+- None detected this week 🎉
+
+### Top 3 Improvements
+1. Continue current research practices
+2. Reduce MCP usage for simple tasks
+3. Document successful patterns
+
+### Rule Updates
+No updates needed this week
+```
+
+### Example 2: Pattern Detection
+
+User: "/learning-loop-patterns"
+
+Agent detects patterns:
+
+```markdown
+## Detected Anti-Patterns
+
+### 1. [CRITICAL] Planning Without Research
+**Occurrences**: 3 times in last 5 plans
+**Impact**: Avg accuracy 58% (vs 82% when researched)
+**Suggestion**: Always use SemanticSearch before planning
+
+### 2. [HIGH] Skipping Validation
+**Occurrences**: 4 times in last 5 plans
+**Impact**: 75% of unvalidated plans had lints
+**Suggestion**: Enable auto-validate hook
+
+### Recommended Actions
+1. Add rule: "Always research before planning"
+2. Enable auto-validate in hooks.config.json
+3. Create checklist for plan creation
+```
+
+### Example 3: Improvement Suggestions
+
+User: "/learning-loop-suggest"
+
+Agent generates suggestions:
+
+```markdown
+## Improvement Suggestions
+
+### Immediate (This Week)
+1. **Add pre-plan research step**
+   - Time cost: +2 min per plan
+   - Benefit: +20% accuracy improvement
+   
+2. **Enable automatic validation**
+   - Already configured, just use it
+   - Benefit: Catch 100% of lint issues
+
+3. **Reduce MCP tool usage**
+   - Current: 4.2 MCP tools/plan
+   - Target: 2.0 MCP tools/plan
+   - Savings: ~30% token cost
+
+### Medium-term (This Month)
+1. Create validation checklist
+2. Document successful patterns
+3. Update anti-pattern detection rules
+
+### Long-term (This Quarter)
+1. Integrate with CI/CD metrics
+2. A/B test different workflows
+3. Build pattern recognition dashboard
+```
+
+## Best Practices
+
+### 1. Review Weekly
+- Schedule fixed time (e.g., Friday 4pm)
+- Review last 10 plans
+- Identify top 3 improvements
+- Update rules if needed
+
+### 2. Act on Patterns
+- Don't just detect - fix
+- Prioritize critical patterns first
+- Track improvement over time
+
+### 3. Keep Rules Minimal
+- Only add rules for repeated patterns
+- Keep rules under 20 lines
+- Use references over content
+
+### 4. Measure Impact
+- Before/after comparisons
+- Track metric changes
+- Adjust based on data
+
+## Anti-Patterns
+
+### ❌ Ignoring Detected Patterns
+Bad: Detect patterns but don't act  
+Good: Create action items, track fixes
+
+### ❌ Over-Analyzing
+Bad: Analyze every single plan  
+Good: Weekly batch analysis
+
+### ❌ Too Many Rules
+Bad: Add rule for every mistake  
+Good: Only for repeated patterns (3+ occurrences)
+
+### ❌ No Follow-up
+Bad: Generate suggestions, forget them  
+Good: Schedule follow-up review
+
+## Troubleshooting
+
+### Not Enough Data
+**Problem**: Less than 3 plans to analyze
+
+**Solution**: 
+- Wait for more data
+- Run analysis after 10+ plans
+- Use qualitative feedback initially
+
+### False Positive Patterns
+**Problem**: Pattern detected but not actually an issue
+
+**Solution**:
+- Adjust detection thresholds
+- Add exception rules
+- Manual review before acting
+
+### No Patterns Detected
+**Problem**: Analysis shows no patterns
+
+**Solution**:
+- Check if thresholds too strict
+- Look for subtle patterns
+- Consider qualitative feedback
+
+## Metrics Reference
+
+### Key Metrics Tracked
+- `plan_accuracy`: % of plan followed correctly
+- `iteration_count`: Number of /grind loops
+- `tool_efficiency`: Cost-weighted tool score
+- `parallel_subagents`: Number of parallel explorations
+- `mcp_usage`: MCP server utilization
+- `cost_estimate`: Estimated token consumption
+
+### Thresholds
+- **Excellent**: Accuracy >90%, Iterations <2, Efficiency >80%
+- **Good**: Accuracy 70-90%, Iterations 2-3, Efficiency 60-80%
+- **Needs Work**: Accuracy <70%, Iterations >3, Efficiency <60%
+
+## Related Documentation
+- `AGENT-INSTRUCTION-BEST-PRACTICES.md` - Core research
+- `.cursor/hooks.config.json` - Configuration
+- `.cursor/plan-metrics.json` - Historical data
+- `.cursor/docs/PLAN-MODE-OPTIMIZATION.md` - Plan mode guide

package/.claude/skills/mcp-mastery/SKILL.md

@@ -0,0 +1,214 @@
+# SKILL.md: MCP Server Mastery
+
+## Description
+Automatic selection and optimal use of available MCP servers for maximum efficiency. Activates automatically based on task analysis in debug mode.
+
+## When to Use (Automatic Triggers)
+**This skill activates AUTOMATICALLY when**:
+- Any task involving browser automation
+- GitHub operations (PRs, issues)
+- Code quality checks
+- Library/framework documentation needs
+- Performance optimization tasks
+- E2E testing requirements
+
+**No manual activation needed** - MCP selection happens automatically based on:
+- User request keywords
+- File patterns being modified
+- Task complexity and type
+- Error patterns detected
+
+## Available MCP Servers
+
+### 1. cursor-ide-browser
+**Capabilities**:
+- Browser automation (navigate, click, fill, scroll)
+- Visual verification (screenshots, snapshots)
+- Performance profiling (CPU, timing)
+- Console/network inspection
+
+**Automatic Triggers**:
+- User mentions: "UI", "visual", "frontend", "browser test"
+- Changes to: `components/`, `app/`, `pages/`
+- Task involves: Design matching, E2E testing
+
+**Optimal Usage Pattern**:
+```
+1. browser_snapshot (take_screenshot: true)
+2. Identify refs from snapshot
+3. Interact via refs (browser_click, browser_fill)
+4. browser_take_screenshot (verify)
+5. Use performance profiling if optimization mentioned
+```
+
+**Cost**: High → Use sparingly, only when visual verification needed
+
+### 2. user-github
+**Capabilities**:
+- Issue/PR management
+- Repository operations
+- Code review automation
+- Branch management
+
+**Automatic Triggers**:
+- User mentions: "PR", "issue", "branch", "commit"
+- Commands: `/pr`, `/fix-issue`, `/review`
+
+**Optimal Usage Pattern**:
+```
+1. Fetch issue/PR details
+2. Implement changes
+3. Run tests/lints
+4. Create/update PR automatically
+5. Link issues
+```
+
+**Cost**: Moderate → Use for all git operations
+
+### 3. user-ESLint
+**Capabilities**:
+- Automatic linting
+- Auto-fix issues
+- Quality reporting
+
+**Automatic Triggers**:
+- After EVERY substantive code change
+- User mentions: "lint", "quality", "errors"
+
+**Optimal Usage Pattern**:
+```
+1. Run ESLint on changed files (automatic)
+2. Apply auto-fixes
+3. Report remaining issues
+4. Fix before committing
+```
+
+**Cost**: Low → Run automatically after all edits
+
+### 4. user-context7
+**Capabilities**:
+- Fetch current library docs
+- API syntax verification
+- Setup/configuration guides
+- Version-specific information
+
+**Automatic Triggers**:
+- Questions about libraries/frameworks
+- Setup/configuration needed
+- API syntax uncertain
+
+**Optimal Usage Pattern**:
+```
+1. Fetch docs BEFORE implementing
+2. Verify current best practices
+3. Apply to implementation
+4. Cite doc source
+```
+
+**Cost**: Low → Fetch proactively for library work
+
+### 5. user-chrome-devtools
+**Capabilities**:
+- Lighthouse audits
+- Performance metrics
+- Accessibility checks
+
+**Automatic Triggers**:
+- User mentions: "performance", "lighthouse", "accessibility"
+- Optimization tasks
+
+**Cost**: Moderate → Use for performance audits
+
+### 6. user-playwright / user-selenium
+**Capabilities**:
+- Cross-browser testing
+- E2E automation
+- Accessibility testing
+
+**Automatic Triggers**:
+- E2E testing needed
+- Cross-browser verification
+- Accessibility compliance
+
+**Cost**: High → Use for comprehensive testing
+
+## MCP Selection Decision Tree
+
+```
+Task involves browser/UI?
+├─ Yes → cursor-ide-browser
+│  └─ Performance audit? → user-chrome-devtools
+│  └─ E2E tests? → user-playwright
+└─ No
+   ├─ GitHub operations? → user-github
+   ├─ Code quality? → user-ESLint (automatic)
+   ├─ Library docs? → user-context7
+   └─ None → Standard tools only
+```
+
+## Cost Optimization Rules (Automatically Enforced)
+
+1. **Always run user-ESLint** after code changes (low cost, high value)
+2. **Fetch user-context7** before library implementation (prevents errors)
+3. **Use cursor-ide-browser** only when visual verification essential
+4. **Prefer user-github** over manual git commands (automation)
+5. **Run performance audits** only when performance mentioned
+6. **Start with Tier 1 MCPs** (cheap) before Tier 2-3 (expensive)
+7. **Chain MCPs automatically** for complex workflows (see examples)
+8. **Track MCP usage** in .cursor/mcp-usage-log.md for optimization
+
+## Debug Mode Auto-Triggers
+
+**In debug mode, these triggers are AUTOMATICALLY monitored**:
+
+```
+File Change Detection:
+- components/**, app/**, pages/** → cursor-ide-browser
+- __tests__/**, e2e/** → user-playwright
+- *.ts, *.tsx → user-ESLint (after changes)
+
+Keyword Detection:
+- "PR", "issue", "branch" → user-github
+- "lint", "quality" → user-ESLint
+- "how to", "docs", "API" → user-context7
+- "performance", "optimize" → user-chrome-devtools + cursor-ide-browser
+
+Error Detection:
+- ESLint errors → user-ESLint (auto-fix mode)
+- Test failures → user-playwright (debug mode)
+- Build errors → user-context7 (fetch build docs)
+```
+
+## Examples
+
+### Example 1: UI Feature Development
+
+User: "Add dark mode toggle to settings"
+
+MCP Sequence:
+1. **user-context7**: Fetch Tailwind dark mode docs
+2. **cursor-ide-browser**: 
+   - Navigate to settings page
+   - Verify toggle renders correctly
+   - Screenshot for confirmation
+3. **user-ESLint**: Check code quality (automatic)
+
+### Example 2: Bug Fix Workflow
+
+User: "Fix checkout issue #456"
+
+MCP Sequence:
+1. **user-github**: Fetch issue #456 details
+2. **user-context7**: Check payment library docs
+3. **user-ESLint**: Verify fix quality (automatic)
+4. **user-github**: Create PR linking issue
+
+### Example 3: Performance Optimization
+
+User: "Optimize dashboard loading"
+
+MCP Sequence:
+1. **user-chrome-devtools**: Run Lighthouse audit
+2. **cursor-ide-browser**: Profile CPU usage
+3. **user-context7**: Fetch React optimization docs
+4. **user-chrome-devtools**: Re-run audit to verify improvement

package/.claude/skills/nestjs-guide/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: nestjs-guide
+description: Comprehensive enterprise guide for NestJS backends covering modular architecture, TypeORM/Prisma transactions, dependency injection, validation pipes, guards, interceptors, and error handling.
+---
+
+# NestJS Enterprise Backend Engineering Guide
+
+## Quick Start
+When architecting NestJS microservices and APIs:
+1. **Modules as Domain Boundaries**: Separate features cleanly (`UsersModule`, `PaymentsModule`). Never dump everything into `AppModule`.
+2. **DTO Validation**: Enforce strict `ValidationPipe` with `whitelist: true` and `forbidNonWhitelisted: true`.
+3. **Stateless Services**: Default to `Scope.DEFAULT` (Singleton). Never store user request state inside service instance properties.
+4. **Transactions via QueryRunner / $transaction**: Always handle atomic operations explicitly. Never leave transactions dangling without rollback.
+5. **Thin Controllers, Rich Services**: Controllers handle HTTP protocol concerns only. Business logic belongs strictly in Services.
+
+---
+
+## 1. Enterprise Module Architecture
+
+```text
+src/
+├── common/                   # Cross-cutting concerns
+│   ├── decorators/           # Custom parameter decorators (@CurrentUser(), @Public())
+│   ├── filters/              # Global HttpExceptionFilter
+│   ├── guards/               # AuthGuard, RolesGuard
+│   ├── interceptors/         # LoggingInterceptor, TransformInterceptor
+│   └── pipes/                # Custom validation/parse pipes
+├── modules/
+│   ├── auth/
+│   │   ├── dto/
+│   │   ├── guards/
+│   │   ├── auth.controller.ts
+│   │   ├── auth.service.ts
+│   │   └── auth.module.ts
+│   └── orders/
+│       ├── dto/
+│       │   ├── create-order.dto.ts
+│       │   └── order-response.dto.ts
+│       ├── entities/
+│       │   └── order.entity.ts
+│       ├── orders.controller.ts
+│       ├── orders.service.ts
+│       └── orders.module.ts
+├── config/                   # Configuration namespaces via @nestjs/config
+├── app.module.ts
+└── main.go / main.ts
+```
+
+---
+
+## 2. Robust Input Validation (Zero-Trust Boundaries)
+
+```typescript
+// src/modules/orders/dto/create-order.dto.ts
+import { IsUUID, IsNumber, Min, IsArray, ValidateNested, ArrayMinSize } from 'class-validator';
+import { Type } from 'class-transformer';
+
+export class OrderItemDto {
+  @IsUUID('4')
+  productId: string;
+
+  @IsNumber({ maxDecimalPlaces: 0 })
+  @Min(1)
+  quantity: number;
+
+  @IsNumber({ maxDecimalPlaces: 2 })
+  @Min(0)
+  unitPrice: number;
+}
+
+export class CreateOrderDto {
+  @IsUUID('4')
+  customerId: string;
+
+  @IsArray()
+  @ArrayMinSize(1)
+  @ValidateNested({ each: true })
+  @Type(() => OrderItemDto)
+  items: OrderItemDto[];
+}
+```
+
+### Main.ts Bootstrap Guard
+```typescript
+import { NestFactory } from '@nestjs/core';
+import { ValidationPipe, Logger } from '@nestjs/common';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  
+  app.useGlobalPipes(
+    new ValidationPipe({
+      whitelist: true,              // Strips unexpected payload keys
+      forbidNonWhitelisted: true,   // Throws 400 if malicious unexpected fields are sent
+      transform: true,              // Automatically maps incoming JSON into TS DTO instances
+      transformOptions: { enableImplicitConversion: true },
+    }),
+  );
+
+  await app.listen(process.env.PORT ?? 3000);
+  Logger.log(`Application is running on: ${await app.getUrl()}`);
+}
+bootstrap();
+```
+
+---
+
+## 3. Database Transactions with Pessimistic Locking (TypeORM)
+
+```typescript
+@Injectable()
+export class OrdersService {
+  constructor(private readonly dataSource: DataSource) {}
+
+  async processOrderPayment(orderId: string, amount: number): Promise<void> {
+    const queryRunner = this.dataSource.createQueryRunner();
+    await queryRunner.connect();
+    await queryRunner.startTransaction();
+
+    try {
+      // 1. Lock the order row exclusively to prevent concurrent double-payments
+      const order = await queryRunner.manager.findOne(OrderEntity, {
+        where: { id: orderId },
+        lock: { mode: 'pessimistic_write' },
+      });
+
+      if (!order) {
+        throw new NotFoundException(`Order with ID ${orderId} not found`);
+      }
+
+      if (order.status === OrderStatus.PAID) {
+        throw new ConflictException(`Order ${orderId} has already been settled`);
+      }
+
+      // 2. Perform state changes
+      order.status = OrderStatus.PAID;
+      order.paidAt = new Date();
+      await queryRunner.manager.save(order);
+
+      // 3. Record ledger entry
+      const ledgerEntry = queryRunner.manager.create(PaymentLedgerEntity, {
+        orderId,
+        amount,
+        status: 'SUCCESS',
+      });
+      await queryRunner.manager.save(ledgerEntry);
+
+      // 4. Commit all operations atomically
+      await queryRunner.commitTransaction();
+    } catch (err) {
+      // Rollback on any failure
+      await queryRunner.rollbackTransaction();
+      throw err;
+    } finally {
+      // Always release query runner back to the connection pool
+      await queryRunner.release();
+    }
+  }
+}
+```
+
+---
+
+## 4. Global Exception Filter (Consistent Error Responses)
+
+```typescript
+@Catch()
+export class AllExceptionsFilter implements ExceptionFilter {
+  private readonly logger = new Logger(AllExceptionsFilter.name);
+
+  catch(exception: unknown, host: ArgumentsHost) {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse<Response>();
+    const request = ctx.getRequest<Request>();
+
+    const status =
+      exception instanceof HttpException
+        ? exception.getStatus()
+        : HttpStatus.INTERNAL_SERVER_ERROR;
+
+    const message =
+      exception instanceof HttpException
+        ? exception.getResponse()
+        : 'Internal server error';
+
+    this.logger.error(`HTTP Status: ${status} Error Message: ${JSON.stringify(message)}`);
+
+    response.status(status).json({
+      statusCode: status,
+      timestamp: new Date().toISOString(),
+      path: request.url,
+      error: typeof message === 'object' ? message : { message },
+    });
+  }
+}
+```