From d92042f0bd0cb49118c397ce9339561bdae6d725 Mon Sep 17 00:00:00 2001 From: Jen Chan <6406037+usrrname@users.noreply.github.com> Date: Sat, 28 Feb 2026 20:23:28 -0500 Subject: [PATCH 1/5] chore: remove outdated command documentation files for architecture, changelog, testing pyramid, dependency analysis, fair witness, git commit standards, refactor agent, dev spike, and dev workflow --- .cursor/commands/architecture.md | 251 -------- .cursor/commands/changelog.md | 64 -- .cursor/commands/testing-pyramid.md | 320 ---------- .../rules/core/dependency-analysis-agent.mdc | 351 ----------- .cursor/rules/core/fair-witness-agent.mdc | 99 --- .cursor/rules/utils/git-commit-push-agent.mdc | 105 ---- .cursor/rules/utils/refactor-agent.mdc | 92 --- .cursor/rules/workflows/dev-spike.mdc | 221 ------- .cursor/rules/workflows/dev-workflow.mdc | 182 ------ .cursor/rules/workflows/pm-story.mdc | 257 -------- docs/fair-witness-examples.md | 592 ------------------ 11 files changed, 2534 deletions(-) delete mode 100644 .cursor/commands/architecture.md delete mode 100644 .cursor/commands/changelog.md delete mode 100644 .cursor/commands/testing-pyramid.md delete mode 100644 .cursor/rules/core/dependency-analysis-agent.mdc delete mode 100644 .cursor/rules/core/fair-witness-agent.mdc delete mode 100644 .cursor/rules/utils/git-commit-push-agent.mdc delete mode 100644 .cursor/rules/utils/refactor-agent.mdc delete mode 100644 .cursor/rules/workflows/dev-spike.mdc delete mode 100644 .cursor/rules/workflows/dev-workflow.mdc delete mode 100644 .cursor/rules/workflows/pm-story.mdc delete mode 100644 docs/fair-witness-examples.md diff --git a/.cursor/commands/architecture.md b/.cursor/commands/architecture.md deleted file mode 100644 index d0ed21c..0000000 --- a/.cursor/commands/architecture.md +++ /dev/null @@ -1,251 +0,0 @@ -# Architecture Design Command ๐Ÿ—๏ธ - -This command guides the AI architect agent to analyze user stories and propose multiple architectural solutions following a structured workflow. - -## Critical Rules - -- Always start with understanding the user's request, the user story, existing constraints, existing architecture, and its business context. Ask clarifying questions to ensure a complete understanding. -- Propose 3 viable solutions. One should be the simplest of the lowest-risk. -- Consider both functional and non-functional requirements -- Offer trade-offs if the user requests them; evaluate trade-offs systematically -- Consider security implications in terms of OWASP Top 10 -- Consider impact on existing architecture, if there are any existing `.cursor/.ai/architecture/` files -- Recommend spikes or proof-of-concepts to validate solutions against system and business constraints -- Evaluate impact on legacy systems (if any) or decisions that are already in place -- Document architectural decisions (ADRs) using `.cursor/rules/templates/architecture-decision-record.md` -- Architecture document filename conventions: - - `high-level-architecture.md` - shows architecture at system level and the different parts that constitute a solution - - `solution_proposal.md` or `spike_#.md` - should be created as part of a spike task for a problem and stored in `.cursor/.ai/spikes/` - -## Workflow Phases - -### 1. Story Analysis - -- Clarify business objectives -- Extract functional requirements -- Identify non-functional requirements -- Define constraints and assumptions -- Identify stakeholders -- Map dependencies on legacy systems -- Understand team capabilities and preferences - -### 2. Solution Generation - -- Include simple diagrams to illustrate the proposed solutions -- Propose 3 architectural approaches -- Consider different architectural styles -- Evaluate emerging technologies and widely used industry choices based on prior art or best practices by SaaS companies -- Situate the solution in context of the current business and technical constraints and opportunities. (In all likelihood, you are not working at a Big Tech company, and pre-existing SaaS practices will not always be applicable) -- Include up to 5 web-based sources that support the proposed solutions -- Consider build vs. buy options -- Consider open source vs. proprietary solutions -- Assess legacy system integration points - -**Checkpoint:** You will provide the user with your progress and check if you missed any areas of concern. The user will offer feedback to update, change course, or spike particular concerns. - -### 3. Trade-off Analysis - -This may be updated due to spike findings. - -- Evaluate each solution against criteria: - - Performance characteristics - - Scalability potential - - Maintenance complexity - - Security implications - - Cost considerations - - Time to market - - Team capabilities - - Technology ecosystem fit - - Legacy system compatibility - - Mention migration paths from existing systems and their complexity - -**Checkpoint:** -- You will provide the user with your progress. -- Check if you missed any areas of concern. The user will offer feedback to update, amend, expand on, dismiss, or change any of the proposed solutions. -- If the user is not satisfied, you will repeat the process or even update the proposed solutions or change course until they are satisfied. - -### 4. Documentation - -- Document assumptions -- Create architecture decision records (ADRs) -- Document component diagrams -- Identify key components and interactions -- Define integration points -- Specify data flows with sequence diagrams and contracts that articulate the precise content of requests, responses and payloads -- Outline security measures -- Create knowledge transfer plans -- Prepare stakeholder-specific presentations - -### 5. Validation - -- Review against system constraints -- Validate against quality attributes -- Check compliance requirements -- Verify business goal alignment -- Assess technical feasibility -- Validate with development teams -- Test against legacy system constraints - -### 6. Feedback Loop - -- Offer suggestions of how to present solutions to different stakeholders -- Gather development team feedback -- Collect operations team input -- Document concerns and suggestions -- Refine solutions based on feedback -- Update documentation accordingly -- Plan iterative improvements - -## Solution Template - -Each proposed solution must include: - -```markdown -## Solution [Number]: [Name] - -### Overview - -[High-level description of the approach] - -### Key Components - -- Component 1: [Description] -- Component 2: [Description] - ... - -### Architecture Style - -[Description of architectural pattern/style used] - -### Integration Points - -- Integration 1: [Description] -- Integration 2: [Description] - ... - -### Data Flow - -[Description of data flow between components] - -### Technology Stack - -- Frontend: [Technologies] -- Backend: [Technologies] -- Database: [Technologies] -- Infrastructure: [Technologies] - -### Trade-offs - -#### Advantages - -- [Advantage 1] -- [Advantage 2] - ... - -#### Disadvantages - -- [Disadvantage 1] -- [Disadvantage 2] - ... - -### Implementation Complexity - -- Timeline Estimate: [Duration] -- Team Size: [Number] -- Key Challenges: [List] - -### Security Considerations - -- [Security measure 1] -- [Security measure 2] - ... - -### Cost Implications - -- Development Cost: [Estimate] -- Operational Cost: [Estimate] -- Maintenance Cost: [Estimate] - -### Scalability Assessment - -[Description of how the solution scales] - -### Legacy System Considerations - -- Integration Points: [List of touchpoints with legacy systems] -- Data Migration: [Strategy for data migration if needed] -- Compatibility Issues: [Potential conflicts and resolutions] -- Technical Debt: [Impact on existing technical debt] -- Transition Strategy: [Plan for gradual migration/integration] - -### Stakeholder Communication - -- Executive Summary: [High-level overview for management] -- Technical Deep-dive: [Detailed explanation for engineers] -- Operations Impact: [Details for ops/maintenance teams] -- Business Value: [Benefits explained for product owners] -- Risk Assessment: [Clear explanation of trade-offs] -``` - -## Usage Examples - -### Example 1: Authentication System - -```markdown -User Story: As a user, I want to securely log in using multiple authentication methods - -Solution 1: OAuth Integration - -- Uses third-party OAuth providers -- Implements JWT tokens -- Includes MFA support - -Solution 2: Custom Auth System - -- Custom implementation -- Password + biometric -- Session management - -Solution 3: Hybrid Approach - -- Combined OAuth and custom -- Unified auth interface -- Flexible provider system -``` - -### Example 2: Data Processing Pipeline - -```markdown -User Story: As an analyst, I want to process large datasets in real-time - -Solution 1: Stream Processing - -- Apache Kafka -- Real-time processing -- Distributed system - -Solution 2: Batch Processing - -- Apache Spark -- Scheduled jobs -- Data warehouse - -Solution 3: Lambda Architecture - -- Combined stream/batch -- Complex but flexible -- Best of both worlds -``` - -## Key Principles - -1. **Thoroughness**: Propose multiple viable solutions -2. **Clarity**: Clear documentation of trade-offs and decisions -3. **Practicality**: Consider implementation realities and stakeholder preferences -4. **Security**: Security-first design approach -5. **Scalability**: Consider scalability in terms of the number of users, data volume, frequency of updates or changes, and traffic patterns. -6. **Maintainability**: Consider long-term maintenance with the idea that different developers may be working on the same codebase over time. -7. **Cost-effectiveness**: Balance cost and benefits -8. **Legacy Respect**: Consider the ability to integrate with existing systems and the complexity of doing so. -9. **Continuous Feedback**: Embrace team input and iterations -10. **Clear Communication**: Adapt explanations to audience needs diff --git a/.cursor/commands/changelog.md b/.cursor/commands/changelog.md deleted file mode 100644 index ce01916..0000000 --- a/.cursor/commands/changelog.md +++ /dev/null @@ -1,64 +0,0 @@ -# Changelog Generation Command ๐Ÿ“ - -Generate a changelog.md by analyzing git history and tags. - -## Git Commands - -```bash -# Get all tags sorted by version (newest first) -git tag --sort=-version:refname - -# Get the most recent tag -git describe --tags --abbrev=0 - -# Get unreleased commits since last tag -git log --oneline --no-merges $(git describe --tags --abbrev=0 2>/dev/null || echo "")..HEAD - -# Get commits between two tags -git log --oneline --no-merges .. - -# Get tag creation date -git log -1 --format=%ai -``` - -## Loop Through All Tags - -```bash -ALL_TAGS=$(git tag --sort=-version:refname) - -for tag in $ALL_TAGS; do - PREV_TAG=$(git describe --tags --abbrev=0 $tag^ 2>/dev/null || echo "") - COMMITS=$(git log --oneline --no-merges $PREV_TAG..$tag) - echo "Version $tag:" - echo "$COMMITS" - echo "---" -done -``` - -## Filter by Conventional Commit Type - -```bash -# Features -git log --oneline --grep="^feat:" .. - -# Bug fixes -git log --oneline --grep="^fix:" .. - -# Documentation -git log --oneline --grep="^docs:" .. - -# Breaking changes -git log --oneline --grep="BREAKING" .. -``` - -## Generate Changelog - -Run these commands and format output following Keep a Changelog format: - -1. Analyze all git tags -2. Categorize commits by type (feat, fix, docs, chore, etc.) -3. Create sections: Added, Fixed, Changed, Documentation -4. Include unreleased changes at the top -5. Store at project root as `changelog.md` - -See `.cursor/rules/utils/changelog-generator-manual.mdc` for full formatting rules. diff --git a/.cursor/commands/testing-pyramid.md b/.cursor/commands/testing-pyramid.md deleted file mode 100644 index a997bef..0000000 --- a/.cursor/commands/testing-pyramid.md +++ /dev/null @@ -1,320 +0,0 @@ -# Test Distribution Analysis Command ๐Ÿงช - -This command guides the AI agent to analyze test distribution across unit, integration, and E2E tests, and provide recommendations for increasing test coverage and improving test distribution in line with business and technical strategy. - -## Critical Rules - -- Always start by identifying the test framework and available coverage tools -- Analyze test distribution using framework-specific commands to list all test files -- Classify tests accurately as unit, integration, or E2E based on multiple indicators -- Target distribution: 70% unit tests, 20% integration tests, 10% E2E tests (this is a guideline at early stages of a project, not a strict requirement) -- Provide actionable recommendations when distribution deviates from ideal ratios -- Consider test file organization, naming conventions, and co-location with source code -- Evaluate test quality indicators (arrange-act-assert pattern, independence, clarity) -- Identify common violations and suggest improvements - -## Workflow Phases - -### 1. Framework Identification - -- Check `package.json` for test framework dependencies: - - **Jest**: `jest` or `@jest/core` in dependencies/devDependencies - - **Vitest**: `vitest` in dependencies/devDependencies - - **Playwright**: `@playwright/test` in dependencies/devDependencies - - **Cypress**: `cypress` in dependencies/devDependencies - - **Mocha**: `mocha` in dependencies/devDependencies -- Identify coverage tools and scripts in `package.json`: - - Look for `test:coverage`, `coverage`, or scripts with `--coverage` flags - - Note available coverage reporters and formats - -### 2. Test Discovery - -Use framework-specific commands to list all test files: - -- **Jest**: `npx jest --listTests` (lists all test files without running) -- **Vitest**: `npx vitest list` (lists all test files) -- **Playwright**: `npx playwright test --list` (lists all test specs) -- **Cypress**: Check `cypress.config.js` for `specPattern` or run `npx cypress run --dry-run` - -**Checkpoint:** Verify all test files are discovered and no test directories are missed. - -### 3. Test Classification - -Classify each test file as unit, integration, or E2E based on multiple indicators: - -#### Classification Criteria - -**File Path Indicators:** - -- `e2e/`, `tests/e2e/`, `__e2e__/` โ†’ E2E tests -- `integration/`, `tests/integration/`, `__integration__/` โ†’ Integration tests -- `unit/`, `tests/unit/`, `__tests__/` โ†’ Unit tests (if not in e2e/integration folders) - -**Content Keywords:** - -- **E2E indicators**: `playwright`, `cypress`, `page.goto`, `browser`, `user journey`, `visit`, `click`, `fill` -- **Integration indicators**: `database`, `api`, `service`, `repository`, `endpoint`, `http`, `fetch`, `axios`, `click`, `fill` -- **Unit indicators**: `mock`, `stub`, `spy`, `jest.fn()`, `vi.fn()`, isolated function testing - -**Test Framework Indicators:** - -- E2E frameworks have distinct APIs (page objects, browser commands, navigation) -- Integration tests often use test databases or mock servers -- Unit tests focus on isolated function/component behavior - -**Checkpoint:** Review classification accuracy by sampling test files from each category. - -### 4. Distribution Analysis - -Calculate test distribution: - -1. Count tests by category: - - - Total unit tests - - Total integration tests - - Total E2E tests - - Total tests overall - -2. Calculate percentages: - - - Unit percentage: `(unit tests / total tests) ร— 100` - - Integration percentage: `(integration tests / total tests) ร— 100` - - E2E percentage: `(e2e tests / total tests) ร— 100` - -3. Compare to ideal ratios: - - Target: 70% unit, 20% integration, 10% E2E - - Identify deviations and their magnitude - -**Checkpoint:** Present distribution findings and highlight significant deviations. - -### 5. Quality Assessment - -Evaluate test quality indicators: - -- **Structure**: Do tests follow Arrange-Act-Assert pattern? Do E2E tests follow page object model or Given-When-Then pattern? -- **Independence**: Can tests run in any order? -- **Clarity**: Are test names descriptive and scenario-focused? -- **Coverage**: Are critical paths and edge cases covered? -- **Maintainability**: Is test code clean and well-organized? Are tests coupled to the implementation details of the codebase? -- **Speed**: Are unit tests fast? Are slow tests appropriately categorized? - -### 6. Violation Detection - -Identify common violations: - -1. **Inverted pyramid** (more E2E than unit tests) -2. **Missing integration tests** between critical services -3. **Testing implementation details** in E2E tests -4. **Excessive mocking** in integration tests -5. **Testing multiple units** in a single unit test -6. **Missing Arrange-Act-Assert** structure -7. **Dependent tests** that must run in specific order -8. **Missing error case** coverage -9. **Brittle tests** that break with minor changes -10. **Insufficient test documentation** - -### 7. Recommendations - -Provide actionable recommendations: - -- **Distribution adjustments**: Suggest adding/removing tests in specific categories -- **Test organization**: Recommend file structure improvements -- **Test quality**: Suggest refactoring for better patterns -- **Coverage gaps**: Identify missing test scenarios -- **Framework optimization**: Suggest better use of framework features -- **Test maintenance**: Recommend cleanup and refactoring priorities - -## Test Type Standards - -### Unit Tests (Target: 70%) - -**Characteristics:** - -- Test individual functions, methods, or components in isolation -- Fast execution (< 100ms per test typically) -- Deterministic results -- Use mocks for external dependencies -- Focus on business logic and edge cases -- High code coverage - -**Best Practices:** - -- Co-locate with source code when possible -- Use clear, descriptive test names that describe the test scenario -- Follow Arrange-Act-Assert pattern -- Test one thing per test -- Use meaningful test data -- Mock external dependencies - -**Example Structure:** - -```typescript -describe("User Processing", () => { - it("should process valid user data correctly", () => { - // Arrange - const mockUser = createMockUser() - - // Act - const result = processUserData(mockUser) - - // Assert - expect(result).toEqual(expected) - }) -}) -``` - -### Integration Tests (Target: 20%) - -**Characteristics:** - -- Test interaction between multiple components or services -- Use real dependencies when possible -- Focus on API contracts and data flow -- Cover main success and error paths -- Slower than unit tests but faster than E2E - -**Best Practices:** - -- Test service interactions -- Verify data transformations -- Test error handling between layers -- Use test databases or mock servers -- Focus on critical integration points - -**Example Structure:** - -```typescript -describe("User Authentication Integration", () => { - it("should successfully authenticate valid user", async () => { - // Arrange - const user = await createTestUser() - - // Act - const result = await authService.authenticate(user.credentials) - - // Assert - expect(result.authenticated).toBe(true) - }) -}) -``` - -### End-to-End Tests (Target: 10%) - -**Characteristics:** - -- Test complete user journeys -- Run against production-like environment -- Focus on critical business flows -- Can be slow and more brittle -- Should be minimal but crucial - -**Best Practices:** - -- Focus on critical user journeys only -- Test happy paths and critical error scenarios -- Use page object models -- Keep tests independent -- Use appropriate wait strategies - -**Example Structure:** - -```typescript -describe("Critical User Journey", () => { - it("should allow user to complete checkout process", async () => { - // Arrange - await loginAsTestUser() - - // Act - await navigateToProducts() - await addItemToCart() - await proceedToCheckout() - await fillShippingDetails() - await completePayment() - - // Assert - await expect(page.locator("#order-confirmation")).toBeVisible() - }) -}) -``` - -## Analysis Report Template - -When presenting analysis results, include: - -```markdown -## Test Distribution Analysis - -### Framework Information - -- **Primary Framework**: [Framework name] -- **Coverage Tool**: [Tool name] -- **Total Test Files**: [Number] - -### Distribution Breakdown - -- **Unit Tests**: [Count] ([Percentage]%) - Target: 70% -- **Integration Tests**: [Count] ([Percentage]%) - Target: 20% -- **E2E Tests**: [Count] ([Percentage]%) - Target: 10% - -### Findings - -- [Finding 1] -- [Finding 2] -- [Finding 3] - -### Violations Detected - -1. [Violation description] -2. [Violation description] - -### Recommendations - -1. [Actionable recommendation] -2. [Actionable recommendation] -3. [Actionable recommendation] - -### Priority Actions - -- **High Priority**: [Actions] -- **Medium Priority**: [Actions] -- **Low Priority**: [Actions] -``` - -## Usage Examples - -### Example 1: Analyzing Jest Project - -```bash -# Discover tests -npx jest --listTests - -# Run analysis -# Classify tests by path and content -# Calculate distribution -# Provide recommendations -``` - -### Example 2: Analyzing Vitest + Playwright Project - -```bash -# Discover unit/integration tests -npx vitest list - -# Discover E2E tests -npx playwright test --list - -# Combine results and analyze -``` - -## Key Principles - -1. **Accuracy**: Classify tests correctly using multiple indicators -2. **Actionability**: Provide specific, implementable recommendations -3. **Balance**: Maintain proper pyramid distribution -4. **Quality**: Assess test quality, not just quantity -5. **Context**: Consider project size, complexity, and team capabilities -6. **Maintainability**: Recommend sustainable test practices -7. **Coverage**: Identify gaps in test coverage -8. **Performance**: Consider test execution time and CI/CD impact -9. **Independence**: Ensure tests can run in any order -10. **Clarity**: Make recommendations clear and easy to understand diff --git a/.cursor/rules/core/dependency-analysis-agent.mdc b/.cursor/rules/core/dependency-analysis-agent.mdc deleted file mode 100644 index 1a55743..0000000 --- a/.cursor/rules/core/dependency-analysis-agent.mdc +++ /dev/null @@ -1,351 +0,0 @@ ---- -description: This rule automatically analyzes dependencies before they're installed to provide insights about maintenance frequency, security vulnerabilities, and popularity in the developer ecosystem. -globs: -alwaysApply: false ---- -# Dependency Analysis - -## Critical Rules - -- Before a dependency is installed (npm install, yarn add, pnpm add), automatically analyze the package -- Check maintenance frequency by examining last release date, commit activity, and issue response times -- Scan for known security vulnerabilities using npm audit and security databases -- Assess popularity through download counts, GitHub stars, and community adoption -- Provide actionable recommendations for dependency selection -- Flag potentially problematic dependencies with clear explanations -- Suggest alternatives for deprecated or poorly maintained packages -- Maintain a local cache of analysis results to avoid repeated API calls -- Respect rate limits when querying external APIs -- Provide analysis in a clear, actionable format with severity levels - -## Analysis Categories - -### Maintenance Frequency -- Last release date and frequency -- Recent commit activity (last 30, 90, 365 days) -- Issue response times and resolution rates -- Pull request merge frequency -- Maintainer activity and responsiveness - -### Security Vulnerabilities -- Known CVEs and security advisories -- Dependency tree vulnerabilities -- Outdated dependencies with security patches -- License compliance issues -- Supply chain attack risks - -### Popularity & Ecosystem Health -- Weekly/monthly download counts -- GitHub stars, forks, and watchers -- Community adoption and usage trends -- Documentation quality and completeness -- TypeScript support and type definitions -- Bundle size impact and performance considerations - - -name: dependency-analysis -description: Analyzes dependencies for maintenance, security, and popularity metrics -version: 1.0 -severity: suggestion - -filters: - - type: event - pattern: "file_modified|file_created" - - type: user_input - pattern: "analyze dependencies|npm install|yarn add|pnpm add" - - type: file_extension - pattern: "\\.(json|lock)$" - - type: content - pattern: "(dependencies|devDependencies|peerDependencies)" - -matches: | - // Match package.json modifications and lock file changes - package.json - package-lock.json - yarn.lock - pnpm-lock.yaml - -transforms: | - // Analyze dependencies when package files are modified - {{ - const analyzeDependency = async (packageName, version) => { - try { - // Fetch package information from npm registry - const npmResponse = await fetch(`https://registry.npmjs.org/${packageName}`); - const npmData = await npmResponse.json(); - - // Fetch GitHub data if repository is available - let githubData = null; - if (npmData.repository && npmData.repository.url) { - const repoUrl = npmData.repository.url.replace('git+', '').replace('.git', ''); - const repoPath = repoUrl.split('github.com/')[1]; - if (repoPath) { - const githubResponse = await fetch(`https://api.github.com/repos/${repoPath}`); - githubData = await githubResponse.json(); - } - } - - // Check for security vulnerabilities - const auditResponse = await fetch(`https://registry.npmjs.org/-/npm/v1/security/advisories/${packageName}`); - const auditData = await auditResponse.json(); - - // Calculate maintenance score - const lastRelease = new Date(npmData.time[npmData['dist-tags'].latest]); - const daysSinceRelease = Math.floor((Date.now() - lastRelease.getTime()) / (1000 * 60 * 60 * 24)); - - let maintenanceScore = 100; - if (daysSinceRelease > 365) maintenanceScore -= 40; - else if (daysSinceRelease > 180) maintenanceScore -= 20; - else if (daysSinceRelease > 90) maintenanceScore -= 10; - - // Calculate popularity score - const weeklyDownloads = npmData.downloads?.weekly || 0; - let popularityScore = 100; - if (weeklyDownloads < 1000) popularityScore -= 50; - else if (weeklyDownloads < 10000) popularityScore -= 20; - else if (weeklyDownloads > 100000) popularityScore += 20; - - // Calculate security score - const vulnerabilities = auditData.vulnerabilities || []; - let securityScore = 100 - (vulnerabilities.length * 20); - - return { - packageName, - version, - maintenanceScore, - popularityScore, - securityScore, - lastRelease: daysSinceRelease, - weeklyDownloads, - vulnerabilities: vulnerabilities.length, - githubStars: githubData?.stargazers_count || 0, - recommendations: generateRecommendations(maintenanceScore, popularityScore, securityScore, vulnerabilities) - }; - } catch (error) { - console.error(`Error analyzing ${packageName}:`, error); - return null; - } - }; - - const generateRecommendations = (maintenance, popularity, security, vulnerabilities) => { - const recommendations = []; - - if (maintenance < 60) { - recommendations.push("โš ๏ธ Low maintenance activity - consider alternatives"); - } - if (popularity < 50) { - recommendations.push("๐Ÿ“‰ Low popularity - may have limited community support"); - } - if (security < 80) { - recommendations.push("๐Ÿ”’ Security vulnerabilities detected - update or replace"); - } - if (vulnerabilities.length > 0) { - recommendations.push(`๐Ÿšจ ${vulnerabilities.length} security vulnerability(ies) found`); - } - - return recommendations; - }; - - // Analyze all dependencies in package.json - const packageJson = JSON.parse(content); - const allDeps = { - ...packageJson.dependencies, - ...packageJson.devDependencies, - ...packageJson.peerDependencies - }; - - const analysisResults = []; - for (const [name, version] of Object.entries(allDeps)) { - const result = await analyzeDependency(name, version); - if (result) { - analysisResults.push(result); - } - } - - return { - analysis: analysisResults, - summary: generateSummary(analysisResults) - }; - }} - -examples: - - input: | - { - "dependencies": { - "lodash": "^4.17.21", - "express": "^4.18.2" - } - } - output: | - ## Dependency Analysis Results โœจ - - ### lodash@^4.17.21 - - ๐ŸŸข Maintenance Score: 95/100 (Last release: 45 days ago) - - ๐ŸŸข Popularity Score: 120/100 (2.5M weekly downloads) - - ๐ŸŸข Security Score: 100/100 (No vulnerabilities) - - โญ GitHub Stars: 58.2k - - โœ… Recommendations: Excellent choice! Well-maintained and secure. - - ### express@^4.18.2 - - ๐ŸŸข Maintenance Score: 90/100 (Last release: 30 days ago) - - ๐ŸŸข Popularity Score: 110/100 (1.8M weekly downloads) - - ๐ŸŸก Security Score: 85/100 (1 minor vulnerability) - - โญ GitHub Stars: 62.1k - - โš ๏ธ Recommendations: Consider updating to latest version for security patch. - - - input: | - { - "dependencies": { - "deprecated-package": "^1.0.0" - } - } - output: | - ## Dependency Analysis Results โš ๏ธ - - ### deprecated-package@^1.0.0 - - ๐Ÿ”ด Maintenance Score: 20/100 (Last release: 500 days ago) - - ๐Ÿ”ด Popularity Score: 30/100 (50 weekly downloads) - - ๐ŸŸก Security Score: 60/100 (2 vulnerabilities) - - โญ GitHub Stars: 12 - - ๐Ÿšจ Recommendations: - - Package is deprecated and poorly maintained - - Consider alternatives: modern-alternative, better-package - - Security vulnerabilities detected - immediate action required - -tests: - - input: "npm install express" - output: "Analyzing express... โœ… Express is well-maintained with 1.8M weekly downloads. No security issues detected." - - - input: "yarn add vulnerable-package" - output: "๐Ÿšจ WARNING: vulnerable-package has 3 security vulnerabilities! Consider alternatives or update immediately." - - - input: "pnpm add abandoned-lib" - output: "โš ๏ธ CAUTION: abandoned-lib hasn't been updated in 2 years. Low community support. Consider alternatives." - -metadata: - priority: high - version: 1.0 - - -## Usage Examples - -### When Installing a New Dependency - -```bash -npm install some-package -``` - -**Analysis Output:** -``` -๐Ÿ” Analyzing some-package... - -๐Ÿ“Š Package Analysis Results: -โœ… Maintenance: Excellent (Last release: 15 days ago) -โœ… Popularity: High (500k weekly downloads) -โœ… Security: Clean (No vulnerabilities) -โญ GitHub: 2.3k stars - -๐Ÿ’ก Recommendation: Great choice! This package is well-maintained and secure. -``` - -### When Installing a Problematic Dependency - -```bash -npm install old-vulnerable-package -``` - -**Analysis Output:** -``` -๐Ÿšจ WARNING: old-vulnerable-package Analysis - -โŒ Maintenance: Poor (Last release: 400 days ago) -โŒ Popularity: Low (100 weekly downloads) -โŒ Security: Critical (5 vulnerabilities detected) -โญ GitHub: 50 stars - -โš ๏ธ Recommendations: -- Package is poorly maintained and has security issues -- Consider alternatives: modern-alternative, secure-package -- If you must use this package, update to latest version -- Monitor for security patches -``` - -### Batch Analysis for Existing Dependencies - -```bash -# Analyze all current dependencies -npm audit -``` - -**Enhanced Output:** -``` -๐Ÿ” Dependency Health Check - -๐Ÿ“ฆ Total Dependencies: 45 -โœ… Well-maintained: 38 packages -โš ๏ธ Needs attention: 5 packages -๐Ÿšจ Critical issues: 2 packages - -๐Ÿ“Š Summary: -- Average maintenance score: 85/100 -- Average popularity score: 78/100 -- Security vulnerabilities: 3 found - -๐Ÿ’ก Action Items: -1. Update lodash to fix security vulnerability -2. Replace deprecated-package with modern-alternative -3. Monitor old-package for updates -``` - -## Integration with Package Managers - -### npm -- Hooks into `npm install` and `npm audit` -- Provides real-time analysis during installation -- Integrates with `npm outdated` for update recommendations - -### yarn -- Works with `yarn add` and `yarn audit` -- Analyzes dependencies in yarn.lock -- Provides yarn-specific recommendations - -### pnpm -- Compatible with `pnpm add` and `pnpm audit` -- Analyzes pnpm-lock.yaml -- Respects pnpm's dependency resolution - -## Configuration Options - -### Analysis Depth -- **Quick**: Basic maintenance and security check (default) -- **Detailed**: Full analysis including GitHub metrics and community health -- **Comprehensive**: Deep dive with alternative suggestions and migration paths - -### Notification Levels -- **Info**: All analysis results -- **Warning**: Only problematic dependencies -- **Critical**: Only security vulnerabilities and maintenance issues - -### Cache Settings -- Cache analysis results for 24 hours (default) -- Configurable cache duration -- Force refresh option for critical security updates - -## Best Practices - -1. **Always check maintenance frequency** before adding new dependencies -2. **Prioritize security** over convenience when choosing packages -3. **Consider alternatives** for deprecated or poorly maintained packages -4. **Regular audits** of existing dependencies -5. **Monitor for updates** and security patches -6. **Document decisions** when using potentially problematic packages - -## Security Considerations - -- Respect API rate limits when querying external services -- Cache sensitive information securely -- Provide clear warnings for security vulnerabilities -- Suggest secure alternatives when available -- Integrate with existing security scanning tools - -Remember: A well-analyzed dependency is a secure dependency! ๐Ÿ”’โœจ diff --git a/.cursor/rules/core/fair-witness-agent.mdc b/.cursor/rules/core/fair-witness-agent.mdc deleted file mode 100644 index 4f9fe2d..0000000 --- a/.cursor/rules/core/fair-witness-agent.mdc +++ /dev/null @@ -1,99 +0,0 @@ ---- -description: Fair Witness agent using 5 epistemological functions for topic analysis with adjustable tone/complexity -globs: -alwaysApply: false ---- -# Fair Witness Agent - -## Critical Rules - -- Use all 5 epistemological functions (observer, evaluator, analyst, synthesist, communicator) -- Include validated internet sources with format "[Title] (Author, YYYY)" -- Sources must be from reputable institutions and directly related to topic -- Support adjustable complexity (low/moderate/high) and tone (dry/engaging/vivid) -- Default: moderate complexity, dry tone -- Use E-Prime style where appropriate -- Be concise unless length specified - -## Epistemological Functions - -1. **Observer** - Factual observations without judgment -2. **Evaluator** - Assess validity/quality based on evidence -3. **Analyst** - Examine relationships, patterns, components -4. **Synthesist** - Combine information into cohesive understanding -5. **Communicator** - Present information clearly and effectively - - -name: fair-witness-agent -description: Fair Witness agent using 5 epistemological functions for topic analysis -version: 1.0 -severity: suggestion -mode: ask|agent -filters: - - type: event - pattern: "chat_start|chat_response" - - type: content - pattern: "(explain|analyze|describe|review|fair witness|assess|compare|evaluate)" -actions: - - type: transform - content: | - {{ - const complexity = input.match(/complexity[:\s]+(low|moderate|high)/i)?.[1] || "moderate"; - const tone = input.match(/tone[:\s]+(dry|engaging|vivid)/i)?.[1] || "dry"; - const functions = input.match(/functions[:\s]+([a-z,\s]+)/i)?.[1]?.split(',').map(f => f.trim()) || - ['observer', 'evaluator', 'analyst', 'synthesist', 'communicator']; - const topics = input.match(/topics[:\s]+([^,]+(?:,\s*[^,]+)+)/i)?.[1]?.split(',').map(t => t.trim()) || - [extractSubject(input)]; - - const config = `emulation: - type: Fair Witness Bot - framework: Function-Epistemic Hybrid Framework - epistemic_functions: ${functions.join(', ')} - output: {detail_level: ${complexity}, style: ${tone}}`; - - return topics.length > 1 ? - `## Fair Witness Comparison\n${config}\n${generateComparisonTable(topics, functions)}` : - `## Fair Witness Analysis\n${config}\n${processWithFunctions(input, functions)}`; - }} - -functions: - processWithFunctions: | - function processWithFunctions(input, functions) { - const subject = extractSubject(input); - return functions.map(f => `### ${f.charAt(0).toUpperCase() + f.slice(1)} Function\n[Analysis content]`).join('\n\n'); - } - - function generateComparisonTable(topics, functions) { - let table = "| Criteria | " + topics.join(" | ") + " |\n|----------|" + topics.map(() => "----------").join("|") + "|\n"; - return table + functions.map(f => `| ${f.charAt(0).toUpperCase() + f.slice(1)} | ` + topics.map(() => "Analysis").join(" | ") + " |").join('\n'); - } - - function extractSubject(input) { return "the requested subject"; } - -examples: - - description: "REST vs GraphQL APIs comparison" - input: "Use Fair Witness to explain the difference between REST and GraphQL APIs." - output: | - ## Fair Witness Analysis - emulation: - type: Fair Witness Bot - framework: Function-Epistemic Hybrid Framework - epistemic_functions: observer, analyst, evaluator, communicator - output: {detail_level: moderate, style: dry} - - ### Observer Function - REST emerged ~2000, GraphQL developed by Facebook in 2015. - - ### Analyst Function - REST uses multiple endpoints, GraphQL uses single endpoint with queries. - - ### Evaluator Function - REST simpler for basic CRUD, GraphQL better for complex data requirements. - - ### Communicator Function - Choose REST for simple APIs, GraphQL for complex data relationships. - -metadata: - priority: high - version: 1.0 - \ No newline at end of file diff --git a/.cursor/rules/utils/git-commit-push-agent.mdc b/.cursor/rules/utils/git-commit-push-agent.mdc deleted file mode 100644 index 130f119..0000000 --- a/.cursor/rules/utils/git-commit-push-agent.mdc +++ /dev/null @@ -1,105 +0,0 @@ ---- -description: This rule enforces Git commit standards and conventions while committing and pushing code in Agent Mode. This rule is crucial for keeping track of changes made by cursor agents, and should run whenever the user expresses they want to commit or push code changes made by the agent. This rule should be followed when: 1. the user wants to commit code, the git aliases, 'gpu' or 'gc', 'gcm' were submitted by the user. This rule will ask the user if they would prefer to autoRun the commit command going forward. All agents should adhere to the standards set out in this rule. -alwaysApply: false ---- -# Git Commit Standards - -## Critical Rules - -- All AI agents MUST follow this rule -- Use `git status` to check modified or staged files before committing -- Never overwrite or push untracked files -- Commits MUST follow the conventional-commit standard -- Always run `git add ` from repo root -- Use present tense in commit subject ("add" not "added") -- Subject โ‰ค 72 chars, imperative mood, blank line before body -- Reference issue/ticket with # if used -- Describe what or why, not how changes were made; fixes must state what was fixed -- Keep descriptions brief and focusedโ€”avoid verbose explanations -- Include agent name in commit footer ("Commit written by ") - -### Commit Format -``` -(): (#) - -[optional body] - -[optional footer] - -Commit written by -``` - -- If agent not specified, use "cursor agent" -- Types: feat, fix, docs, style, refactor, perf, test, chore, ci, security, rename - -### Post-Commit Actions - -- Do NOT include post-commit commands (e.g., `npm run lint`, `git push`) in commit message -- Suggest these actions separately after commit - -### Agent Enforcement - -- Always check `git status` before commit -- Never use generic messages ("update code", "commit changes") -- Identify change type per conventional commit -- Commit body should be concise and brief, and should not exceed 20 words -- Prefer single-line descriptions when possible; only use body for essential context -- Use meaningful scope (codebase area) -- Clear, concise, imperative subject -- Add agent name as author -- Convert user commit instructions to proper format - - -name: git-commit -version: 1.0 -description: Enforces conventional commit standards for all agent commits and pushes. Invoked on commit/push requests or git aliases (gc, gcm, gpu). Prompts for or infers proper message if user input is vague. -filters: - - type: file_extension - pattern: "COMMIT_EDITMSG$" - - type: event - pattern: "(pre_commit|post_commit)" - - type: content - pattern: "(commit|push|gc|gcm|gpu)" - -examples: - - input: | - added new feature - output: | - feat(api): add user authentication endpoint (#123) - - JWT-based authentication with env var configuration - - Commit written by KawaiiSamurai - - input: | - fixing bug - output: | - fix(database): resolve connection timeout issue (#456) - - Increase timeout to 30s and add retry logic - - Commit written by SageDaddy - - input: | - update docs - output: | - docs(readme): update installation instructions (#789) - - Clarify setup steps for new contributors - - Commit written by Spellchuck - -tests: - - input: "updated code" - output: "feat(core): update code processing logic (#567)\n\nCommit written by BasicBitchDeveloper" - - input: "fix error" - output: "fix(validation): resolve input sanitization error (#890)\n\nCommit written by ThirstySimp" - - input: "add docs" - output: "docs(api): add OpenAPI documentation (#345)\n\nCommit written by Spellchuck" - - input: "long verbose description that should be shortened" - output: "feat(module): add new feature\n\nBrief essential context only\n\nCommit written by cursor agent" - - input: "commit" - output: "When the user simply types 'commit', the agent must:\n1. Check git status\n2. Determine the appropriate type and scope based on changed files\n3. Generate a proper conventional commit message\n4. Present it to the user for approval (post-commit actions are suggested separately)" - -metadata: - priority: high - version: 1.0 - \ No newline at end of file diff --git a/.cursor/rules/utils/refactor-agent.mdc b/.cursor/rules/utils/refactor-agent.mdc deleted file mode 100644 index 8bb85c7..0000000 --- a/.cursor/rules/utils/refactor-agent.mdc +++ /dev/null @@ -1,92 +0,0 @@ ---- -description: Agent rule for refactoring existing code blocks or a feature by identifying language and applying only when refactor/improvement is requested -globs: -alwaysApply: false ---- - -## Critical Rules - -- Always detect and state the programming language of the code block before refactoring -- Refactor when the user request includes terms like "refactor", "improve", "optimize", "clean up", or similar -- Always preserve the original intent and functionality unless the user requests a change -- If code contains duplication, refactor first, and test, before introducing a change. -- Use idiomatic, modern, and maintainable patterns for the detected language -- Add or update comments and documentation as appropriate -- If the code or modification request is ambiguous, ask clarifying questions before proceeding -- Provide before/after code examples in the response -- If the code block is part of a larger file, ensure changes do not break unrelated code -- Run or suggest updates to relevant tests after refactoring -- Make as few changes as possible while preserving readability to limit the amount of errors that may arise from potentially destroying existing functionality the user intended to preserve. -- If it exists, identify contradictory requirements and existing implementation in other areas of codebase that may prevent the refactor from succeeding. - - -name: refactor-block-agent -version: 1.0 -description: Refactor or improve an existing code block, identifying the language and applying best practices only when requested -filters: - - type: event - pattern: "refactor|improve|optimize|clean up" - - type: content - pattern: - - "[a-zA-Z0-9_]+\\s*\\([^)]*\\)\\s*\\{[\\s\\S]*?\\}" # Curly-brace function (JS, Java, C, etc.) - - "def\\s+[a-zA-Z0-9_]+\\s*\\([^)]*\\)\\s*:\\s*[\\s\\S]*?(?=^\\S|\\Z)" # Python function - - "class\\s+[a-zA-Z0-9_]+\\s*\\([^)]*\\)?\\s*:\\s*[\\s\\S]*?(?=^\\S|\\Z)" # Python class -actions: - - type: analyze - message: | - Identify the programming language of the code block. If ambiguous, ask the user for clarification. - - type: suggest - message: | - Refactor the code block using best practices for the detected language. Preserve original functionality unless otherwise specified. Add or update comments as needed. - - type: validate - message: | - Ensure the refactored code passes all relevant tests and does not introduce regressions. If tests are missing, suggest appropriate tests. -examples: - - input: | - // User: Refactor this function to be more readable - function sum(a, b) { return a+b } - output: | - // Detected language: JavaScript - // Before: - function sum(a, b) { return a+b } - // After: - /** - * Returns the sum of two numbers - * @param {number} a - * @param {number} b - * @returns {number} - */ - function sum(a, b) { - return a + b; - } - - input: | - # User: Please improve this Python code - def greet(name):return 'Hello, '+name - output: | - # Detected language: Python - # Before: - def greet(name):return 'Hello, '+name - # After: - def greet(name: str) -> str: - """Return a greeting for the given name.""" - return f"Hello, {name}" - - input: | - // User: Optimize this for performance - for (let i = 0; i < arr.length; i++) { result.push(arr[i] * 2) } - output: | - // Detected language: JavaScript - // Before: - for (let i = 0; i < arr.length; i++) { result.push(arr[i] * 2) } - // After: - result.push(...arr.map(x => x * 2)); -tests: - - input: "Refactor this function: function foo(x){return x*2}" - output: "Should detect JavaScript, add spacing, and suggest a JSDoc comment." - - input: "Improve: def add(x,y):return x+y" - output: "Should detect Python, add type hints, docstring, and proper formatting." - - input: "Optimize this: const nums = [1,2,3]; let out = []; for(let n of nums){out.push(n*n)}" - output: "Should detect JavaScript, suggest using map, and preserve output." -metadata: - priority: high - version: 1.0 - diff --git a/.cursor/rules/workflows/dev-spike.mdc b/.cursor/rules/workflows/dev-spike.mdc deleted file mode 100644 index 2aefb57..0000000 --- a/.cursor/rules/workflows/dev-spike.mdc +++ /dev/null @@ -1,221 +0,0 @@ ---- -description: This rule provides the guiding principles that developer and architect agents must follow for time-boxed technical investigations. -globs: -alwaysApply: false ---- -# Technical Spike Workflow - -A guide for conducting time-boxed technical investigations (spikes) to reduce uncertainty and risk in development decisions. โšก - -## Critical Rules - -- Spikes MUST be time-boxed (typically 1-2 hours) -- Spikes MUST have clear investigation goals -- Spikes MUST produce documented findings -- Spike documents containing information about the spike MUST be saved in `.cursor/.ai/spikes/` with format `spike--story-<#>.md` where the digits represent the user story number. -- Spike outcomes MUST inform architectural or implementation decisions -- The agent will check out a spike branch formatted `spike/spike-story-name` and use that branch to commit and push code changes. -- Code produced during spikes MUST be treated as disposable code for proving whether an approach is viable. -- Findings MUST be shared with the team and updated on the `.cursor/.ai/architecture.md`. -- The user story for the spike must be updated with the decision selected by the user. -- Any web search results that were referenced should be included as links in the spike document. - - -name: dev-spike -description: Standards for conducting and documenting technical spikes -version: 1.0 -filters: - - type: file_extension - pattern: "\\.md$" - - type: path - pattern: "\\.cursor/\\.ai/spikes/\\d{4}-.*\\.md" - - type: content - pattern: "## Investigation Goals" - -metadata: - priority: high - version: 1.0 - - -## Spike Template - -```markdown -# Technical Spike: [Title] - -[link-to-user-story](./link-to-user-story) -[link-to-arch](./link-to-arch) - -## Investigation Goals -- [ ] Primary question to answer -- [ ] Secondary questions -- [ ] Technical constraints to validate - -## Timeline -- Start Date: [YYYY-MM-DD] -- End Date: [YYYY-MM-DD] -- Time Box: [X] days - -## Investigation Areas -1. [Area 1] - - Approach: - - Tools/Technologies: - - Success Criteria: - -2. [Area 2] - - Approach: - - Tools/Technologies: - - Success Criteria: - -## Findings -### What Worked -- Finding 1 -- Finding 2 - -### What Didn't Work -- Challenge 1 -- Challenge 2 - -### Open Questions -- Question 1 -- Question 2 - -## Recommendations -- [ ] Primary recommendation -- [ ] Alternative approaches -- [ ] Risk assessment - -## Code Artifacts -- Repository: [link] -- Branch: [name] -- Key Files: - - `path/to/file`: Purpose - -## Next Steps -- [ ] Action item 1 -- [ ] Action item 2 - -## Team Impact -- Frontend: -- Backend: -- Infrastructure: -- Testing: - -## Resources -- Documentation: [links] -- References: [links] -``` - -## Spike Process - -### 1. Initiation ๐ŸŒฑ -1. **BasicDev**, **ThirstySimp** or **KawaiiSamurai** identifies technical uncertainty -2. **SageDaddy** reviews and advises on investigation scope -3. **SailorScrum** approves time allocation - -### 2. Planning ๐Ÿ“ -1. Create spike document using template -2. Define clear investigation goals -3. Set time box and success criteria -4. Identify required resources - -### 3. Investigation ๐Ÿ” -1. Create disposable branch for experiments -2. Document findings as they emerge -3. Regular check-ins with **SageDaddy** -4. Capture both successes and failures - -### 4. Review & Documentation โœจ -1. **Spellchuck** ensures clear documentation -2. **qwoof** reviews testing implications -3. **Godmode** assesses infrastructure impact -4. Team reviews findings - -### 5. Decision & Next Steps ๐ŸŽฏ -1. Present findings to team -2. Document architectural decisions -3. Update technical documentation -4. Archive spike code appropriately - -## Examples - - -# Technical Spike: GraphQL vs REST for API Architecture - -## Investigation Goals -- [ ] Compare performance characteristics of GraphQL and REST for our use case -- [ ] Evaluate developer experience and tooling ecosystem -- [ ] Assess impact on frontend development workflow -- [ ] Validate GraphQL schema design approaches - -## Timeline -- Start Date: 2024-02-01 -- End Date: 2024-02-05 -- Time Box: 5 days - -## Investigation Areas -1. Performance - - Approach: Build equivalent endpoints in both technologies - - Tools: Apollo Server, Express, k6 for load testing - - Success Criteria: Clear metrics on response times and payload sizes - -2. Developer Experience - - Approach: Implement common use cases in both - - Tools: GraphQL Codegen, Swagger, TypeScript - - Success Criteria: Documented developer workflow and pain points - -## Findings -### What Worked -- GraphQL reduced over-fetching by 40% -- Code generation improved type safety -- Schema documentation was more maintainable - -### What Didn't Work -- File upload handling was complex -- Caching required additional setup -- Learning curve steeper than expected - -## Recommendations -- [ ] Proceed with GraphQL for new services -- [ ] Keep REST for file operations -- [ ] Implement incremental adoption strategy - -## Code Artifacts -- Repository: github.com/org/graphql-spike -- Branch: spike/graphql-investigation -- Key Files: - - `schema/`: GraphQL schema definitions - - `resolvers/`: Query implementations - - `load-tests/`: Performance test scripts - -## Next Steps -- [ ] Create ADR for API architecture -- [ ] Plan training sessions -- [ ] Define schema design guidelines - -## Team Impact -- Frontend: Requires Apollo Client integration -- Backend: New tooling and patterns needed -- Infrastructure: Additional GraphQL gateway -- Testing: New approach for API testing - - -## Quality Assurance - -Before completing a spike: - -1. **Documentation Quality** - - Clear investigation goals - - Well-documented findings - - Actionable recommendations - -2. **Technical Rigor** - - Methodical investigation - - Evidence-based findings - - Considered alternatives - -3. **Risk Assessment** - - Technical risks documented - - Mitigation strategies proposed - - Resource implications clear - -Remember, spikes are about reducing uncertainty through focused investigation. Document everything - both successes and failures contribute to the learning! โšก \ No newline at end of file diff --git a/.cursor/rules/workflows/dev-workflow.mdc b/.cursor/rules/workflows/dev-workflow.mdc deleted file mode 100644 index 9a6ce08..0000000 --- a/.cursor/rules/workflows/dev-workflow.mdc +++ /dev/null @@ -1,182 +0,0 @@ ---- -description: This rule defines the workflow for AI agents to follow when implementing features from user stories, focusing on lean development principles and agile methodologies. -globs: -alwaysApply: false ---- - -# Lean and Agile Development Workflow Standards - -This rule defines the workflow for AI agents to follow when implementing features from user stories, focusing on lean development principles and agile methodologies. - -## Critical Rules - -- AI agents should read from the latest user story in `.cursor/.ai/` that is not of "Done" or "Blocked" status. -- No more than 2 stories or spikes can be in progress at any time. -- Break down complex problems into a manageable task list and update the relevant user story or task with this list -- Check off tasks one by one as they are completed -- Assist with fixing errors in the code -- Follow test-driven development when appropriate -- Maintain continuous communication with the user about progress -- If linting or committing fails, do not retry. - - -name: dev-workflow -description: Workflow for AI agents to follow when implementing features using lean and agile methodologies -version: 1.0 -severity: suggestion - -filters: - - type: file_extension - pattern: "\\.(js|ts|jsx|tsx|md)$" - - type: content - pattern: "user story|feature request|backlog item" - -actions: - - type: suggest - message: | - Follow the lean-agile workflow pattern: - 1. Break down the user story into atomic tasks - 2. Prioritize tasks based on dependencies - 4. Based on user goals and acceptance criteria, create a list of test cases and edge cases with scenarios for testing the business-critical functionality. This must be approved by the user. - 3. Implement each task incrementally - 4. Write tests and ensure they pass before moving to the next task - 5. Refactor as needed - 6. Maintain communication with the user - -metadata: - priority: high - version: 1.0 - - -## Workflow Process - -### 1. User Story Analysis - -When given a user story or feature request: -- Mark the corresponding user story to `Status: In Progress` -- Read and analyze the user story requirements -- Break down the story into actionable tasks -- Check if any existing components or utilities can be reused -- Writing scenarios and expected outcomes. - -### 2. Task Breakdown and Prioritization - -The user story will be updated with a task list. - -- Clear, actionable items with acceptance criteria for task completion -- These items will have logical ordering based on dependencies -- Completion of core functionality should be prioritized first - -Example task breakdown: -``` -[ ] 1. Implement data fetching logic -[ ] 2. Set up basic component structure -[ ] 3. Create UI elements -[ ] 4. Add user interaction handling -[ ] 5. Implement error handling -[ ] 6. Write tests -[ ] 7. Refactor for performance and readability -``` - -### 3. Iterative Implementation - -For each task: - -- Enumerate test cases for different scenarios and use cases -- Focus on implementing the minimum viable solution first -- Check off the task in the user story when completed -- Add and run tests to ensure functionality works as expected -- Address any errors or issues before moving to the next task -- If the agent is unable to continue, set the user story to `Status: Blocked`, provide a brief explanation of why, research and suggest possible next steps or workarounds to take. -- When the user requests, refactor code to improve quality without changing functionality - -### 4. Error Handling - -When encountering errors: - -- Provide clear explanations of what went wrong -- Offer suggestions for fixing the issues -- Help implement the fixes. -- Verify the solution resolves the error -- Document the error and solution for future reference -- Mark the corresponding user story as blocked and provide a short summary about why the task can't be completed. - -### 5. Completion and Review - -After completing all tasks: - -- Review the entire implementation against the original user story -- Ensure all acceptance criteria are met -- Suggest any potential improvements -- Document the implementation decisions -- Prepare for code review if necessary - -## Examples - - -**User Request**: Implement a user story for a login form with validation - -**Agent Response**: -"I'll help you implement the login form feature. Let me break this down: - -Tasks: -[ ] 1. Create form component structure -[ ] 2. Implement input fields with basic styling with unit tests for basic functionality -[ ] 4. Add form state management with unit tests for expected state changes -[ ] 4. Implement validation logic with unit tests for input constraints -[ ] 5. Add error display for invalid inputs -[ ] 6. Connect form submission to API -[ ] 7. Add loading state during submission -[ ] 8. Implement success/failure handling - -Let's start with the first task: creating the form component structure." - -*After implementing the form structure* - -"Great! I've completed the first task: - -Tasks: -[โœ“] 1. Create form component structure -[ ] 2. Implement input fields with basic styling with unit tests for basic functionality -[ ] 3. Add form state management with unit tests for expected state changes -... - -Now let's move on to implementing the input fields with styling." - - - -**Error Scenario**: The form submission fails due to a network error - -**Agent Response**: -"I noticed we're getting a network error when submitting the form. This could be due to: - -1. The API endpoint URL might be incorrect -2. There might be CORS issues -3. The server might be down. - -Let's fix this by: -1. Verifying the API endpoint URL -2. Adding proper error handling to display user-friendly messages -3. Implementing a retry mechanism - -I'll start by updating the submission handler to include better error handling." - - -## Testing Standards - -- Write tests for each meaningful piece of functionality. -- Tests should be independent and repeatable. -- Every UI element should have at least one data-testid on its outermost element. -- Elements that an end user will interact with or see conditionally should have a `data-testid` attribute with a semantic, unique value. -- API calls and dependencies should be mocked when appropriate. -- Follow the testing pyramid: more unit tests, fewer integration and E2E tests. Refer to `.cursor/rules/test/test-pyramid-agent.mdc` for guiding principles. -- For front end functionality, unit tests should be written after the basic structure of the component is complete. -- Use descriptive test names that explain the expected behavior - -## Communication Guidelines - -- Keep users informed about progress -- Explain technical decisions in simple terms -- Ask clarifying questions when requirements are ambiguous -- Suggest alternatives when faced with implementation challenges -- Celebrate incremental wins to maintain motivation \ No newline at end of file diff --git a/.cursor/rules/workflows/pm-story.mdc b/.cursor/rules/workflows/pm-story.mdc deleted file mode 100644 index 747a215..0000000 --- a/.cursor/rules/workflows/pm-story.mdc +++ /dev/null @@ -1,257 +0,0 @@ ---- -description: This workflow guides the process of discovering, drafting and validating user stories which will be written by SailorScrum with input from the rest of the team. -glob: -alwaysApply: false ---- -# User Story Discovery Workflow - -In the name of the Moon, this workflow guides the process of discovering and crafting user stories that will power your project's success! ๐ŸŒ™โœจ - -## Critical Rules - -- The PM SailorScrum will gather and clarify requirements from your primary stakeholder, the user. -- Every user story MUST follow the standard format: "As a [role], I want [goal] so that [benefit]" -- Stories MUST be independent, negotiable, valuable, estimable, small, and testable -- Every story MUST have clear requirements and acceptance criteria -- The user story MUST be saved in `.cursor/.ai/` with the format `story-title.md` -- The story should be updated as new insights, constraints and decisions -- Stories MUST be discoverable through semantic search -- Stories MUST link to related architecture decisions, spike documents or technical constraints -- Stories MUST include effort estimation (S, M, L, XL) -- All agents can use Tavily to perform web search. - - -name: pm-story -description: Standards for discovering and documenting user stories -version: 1.0 -filters: - - type: file_extension - pattern: "\\.md$" - - type: content - pattern: "As a .*, I want .* so that .*" - - type: path - pattern: "\\.cursor/\\.ai/backlog/\\d{4}-.*\\.md" - -metadata: - priority: high - version: 1.0 - - -## Discovery Process - -### 1. Story Initiation ๐ŸŒฑ - -When a new story is needed: -1. SailorScrum leads a discovery session and asks the user to clarify requirements and business needs. -2. KawaiiSamurai or BasicDev provides technical insights -3. SageDaddy reviews for architectural implications offers recommendations on approach or technology choices -4. qwoof confirms user goals and ensures testability - -### 2. Story Creation Template ๐Ÿ“ - -```markdown -# User Story: [Title] - -## Story -As a [role], -I want [goal/feature] -so that [benefit/value] - -## Background -[Context and additional information] - -## Acceptance Criteria -- [ ] Given [context], when [action], then [result] -- [ ] Given [context], when [action], then [result] -- [ ] Given [context], when [action], then [result] - -## Technical Notes -- Dependencies: -- Architecture considerations: -- Security implications: -- Unknowns - -## Effort Estimation -Size: [S/M/L/XL] -Confidence: [High/Medium/Low] - -## Related -- Architecture Decision Records: [links] -- Technical Documentation: [links] -- Dependencies: [story links] - -## Team Assignment -- Frontend: [team member] -- Backend: [team member] -- Devops: [team member] -- QA: [team member] - -## Timeline -- Created: [date] -- Target: [milestone] -``` - -### 3. Story Refinement Process ๐Ÿ’ซ - -1. **Initial Draft** - - Use the template above - - Focus on user value - - Keep it solution-agnostic - -2. **Technical Review** - - SageDaddy reviews architecture impact - - KawaiiSamurai checks frontend feasibility - - BasicDev validates backend requirements - - Godmode assesses infrastructure needs - -Checkpoint: the user is asked to review the document progress so far, suggest or provide changes before the agent is to move onto the next step. - -3. **Quality Check** - - qwoof reviews testability - - Spellchuck ensures clarity and completeness of documentation - - ThirstySimp checks market relevance - -4. **Final Approval** - - SailorScrum validates INVEST criteria - - Team consensus on estimation - - Story is ready for sprint planning and status is updated to "Status: ToDo" - - Blocked, Rejected or Dropped stories should have Status updated to `Dropped` and moved into `.cursor/.ai/backlog/`. The story should be updated with a 1 sentence description of why it could not proceed to development. - -## Story States - -Stories can be in the following states: -- ๐Ÿ“ Draft - Initial creation and refinement -- ๐Ÿ” Review - Under technical review and discussion -- โœจ Ready - Approved and ready for development -- โ›” Blocked/Rejected/Dropped - Has blockers or deemed not viable for development - -## Agent Responsibilities - -### SailorScrum -- Leads discovery sessions -- Ensures business value is clear -- Manages story state transitions - -### KawaiiSamurai -- Reviews frontend implications -- Suggests UI/UX improvements -- Estimates frontend effort -- Identifies design dependencies - -### BasicDev -- Validates technical feasibility -- Identifies backend dependencies -- Estimates development effort -- Suggests implementation approach - -### SageDaddy -- Reviews architectural impact -- Identifies technical constraints -- Suggests scalable solutions -- Validates technical approach - -### Spellchuck -- Ensures clear documentation -- Refines acceptance criteria -- Maintains consistent terminology -- Links related documentation - -### ThirstySimp -- Researches market trends -- Suggests modern approaches -- Identifies competitive features -- Validates user experience - -### qwoof -- Ensures testability -- Defines test scenarios -- Identifies edge cases -- Validates acceptance criteria - -### Godmode -- Assesses infrastructure needs -- Identifies scaling requirements -- Reviews security implications -- Validates deployment approach - -## Examples - - -# User Story: Enable Social Login - -## Story -As a new user, -I want to sign up using my Google account -so that I can start using the app quickly without creating another password - -## Acceptance Criteria -- [ ] Given I'm on the login page, when I click "Sign in with Google", then I'm redirected to Google OAuth -- [ ] Given I authorize the app, when Google redirects back, then my account is created/linked -- [ ] Given I'm logged in, when I view my profile, then I see my Google profile picture - -## Technical Notes -- Dependencies: Google OAuth API -- Security: OAuth 2.0 implementation -- Data: User profile mapping strategy - -## Effort Estimation -Size: M -Confidence: High - -## Related -- ADR: 0003-oauth-implementation.md -- Docs: auth-flow.md - - - -# User Story: Automated Deployment Pipeline - -## Story -As a developer, -I want my code to be automatically deployed when merged to main -so that I can deliver features faster with confidence - -## Acceptance Criteria -- [ ] Given a PR is merged to main, when CI passes, then code is deployed to staging -- [ ] Given deployment succeeds, when health checks pass, then notification is sent -- [ ] Given deployment fails, when error occurs, then team is notified with logs - -## Technical Notes -- Dependencies: GitHub Actions, AWS -- Security: Deployment credentials -- Infrastructure: K8s clusters - -## Effort Estimation -Size: L -Confidence: Medium - -## Related -- ADR: 0005-ci-cd-strategy.md -- Docs: deployment-guide.md - - -## Quality Assurance - -Before a story is marked as ready: - -1. **Clarity Check** - - Story follows template - - Requirements and Acceptance criteria are clear - -2. **Value Check** - - Business value is clear - - ROI is justified - - User benefit is explicit - -3. **Technical Check** - - Dependencies identified - - Architecture reviewed - - Security considered - -4. **Test Check** - - Acceptance criteria are testable - - Main use cases and scenarios identified - - Edge cases identified - - Test approach defined - -Remember, in the name of the Moon, we shall write stories that bring value to our users and joy to our developers! ๐ŸŒ™โœจ \ No newline at end of file diff --git a/docs/fair-witness-examples.md b/docs/fair-witness-examples.md deleted file mode 100644 index 0be2746..0000000 --- a/docs/fair-witness-examples.md +++ /dev/null @@ -1,592 +0,0 @@ - -# Examples Using the Fair Witness Framework โœจ ๐Ÿ“œ - -## **Invoke the Framework** - -Ask Fair Witness to explain your topic in Ask or Agent mode. - -``` - -Use Fair Witness to... - -Provide a Fair Witness analysis of... - -``` - -## **Include web search results** - -Use `@Web` or `Include sources.` to include web search results. - -## **Comparing topics** - -``` -Use Fair Witness to analyze how RAG differs from fine-tuning LLMs. Provide examples. @Web -``` - -
-Response from Gemini Flash Preview 04-17 - - -## Fair Witness Analysis -``` -emulation: - type: Fair Witness Bot - framework: Function-Epistemic Hybrid Framework - epistemic_functions: - - observer - - analyst - - evaluator - - synthesist - - communicator - constraints: - natural_language: - style: E-Prime - output: - type: natural language - detail_level: moderate - length: moderate - complexity: moderate - style: dry - includes_sources: true -``` - -### Observer Function - -Retrieval-Augmented Generation (RAG) and fine-tuning are two methods for enhancing Large Language Models (LLMs). RAG involves enabling an LLM to access and utilize external, up-to-date information from knowledge bases without requiring retraining. Fine-tuning involves further training an existing LLM on a specific dataset to improve its performance on domain-specific tasks or to incorporate new knowledge. - -**Sources:** -- [18 real world Examples of Using RAG vs. Fine-Tuning (AI Rabbit, 2024)](https://medium.com/@jacktheflipper/20-real-world-examples-of-using-rag-vs-fine-tuning-e24056000251) -- [Retrieval-Augmented Generation vs Fine-Tuning: Whatโ€™s Right for You? (Oren Ezra, 2025)](https://www.k2view.com/blog/retrieval-augmented-generation-vs-fine-tuning/) - -### Analyst Function - -The core difference lies in how external information integrates into the LLM's response generation. RAG adds a data retrieval component that fetches relevant information at query time, allowing the LLM to use this dynamic data. Fine-tuning modifies the LLM's parameters by training it on a static dataset, embedding the new knowledge directly into the model. RAG is generally more cost-effective for incorporating dynamic, frequently updated information, while fine-tuning is more suitable for deepening domain-specific understanding and requires more labeled data and computational resources. RAG tends to exhibit less proneness to hallucinations due to grounding responses in retrieved data. - -**Sources:** -- [Retrieval-Augmented Generation vs Fine-Tuning: Whatโ€™s Right for You? (Oren Ezra, 2025)](https://www.k2view.com/blog/retrieval-augmented-generation-vs-fine-tuning/) - -### Evaluator Function - -RAG demonstrates advantages when dealing with dynamic data and scenarios requiring up-to-date information. Examples include customer service chatbots needing current product details, financial reports based on real-time market data, and technical support systems accessing the latest documentation. Fine-tuning proves more effective for specialized tasks demanding deep domain knowledge. Examples include sentiment analysis with nuanced interpretation, named-entity recognition for specialized terminology (e.g., legal terms), and providing technical support for unique products. - -**Sources:** -- [18 real world Examples of Using RAG vs. Fine-Tuning (AI Rabbit, 2024)](https://medium.com/@jacktheflipper/20-real-world-examples-of-using-rag-vs-fine-tuning-e24056000251) - -### Synthesist Function - -Choosing between RAG and fine-tuning depends on the specific use case requirements. If the need involves accessing and incorporating the latest, dynamic information from internal or external sources, RAG presents a more appropriate and cost-efficient solution. If the objective centers on enhancing the LLM's understanding and performance on a static, domain-specific task where subtle nuances are critical, fine-tuning offers a more tailored approach. - -**Sources:** -- [18 real world Examples of Using RAG vs. Fine-Tuning (AI Rabbit, 2024)](https://medium.com/@jacktheflipper/20-real-world-examples-of-using-rag-vs-fine-tuning-e24056000251) -- [Retrieval-Augmented Generation vs Fine-Tuning: Whatโ€™s Right for You? (Oren Ezra, 2025)](https://www.k2view.com/blog/retrieval-augmented-generation-vs-fine-tuning/) - -### Communicator Function - -RAG enhances LLMs by providing access to external, dynamic data at query time, suitable for applications requiring current information. Fine-tuning adapts LLMs to specific tasks by training them on static datasets, improving domain-specific performance. The optimal method depends on whether the priority lies in utilizing up-to-date data (RAG) or deepening specialized knowledge (fine-tuning). - -**Sources:** -- [18 real world Examples of Using RAG vs. Fine-Tuning (AI Rabbit, 2024)](https://medium.com/@jacktheflipper/20-real-world-examples-of-using-rag-vs-fine-tuning-e24056000251) -- [Retrieval-Augmented Generation vs Fine-Tuning: Whatโ€™s Right for You? (Oren Ezra, 2025)](https://www.k2view.com/blog/retrieval-augmented-generation-vs-fine-tuning/) - -
-
-Response from o3-mini - - -Below is a concise Fair Witness analysis outlining key differences between Retrieval-Augmented Generation (RAG) and fine-tuning LLMs, along with concrete examples. - -โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ -โ— Observer: -โ€ข Fine-tuning adjusts the internal parameters of an LLM to specialize its behavior on a given dataset. For example, as discussed in [Anyscaleโ€™s analysis](https://www.anyscale.com/blog/fine-tuning-llms-lora-or-full-parameter-an-in-depth-analysis-with-llama-2), fine-tuning (whether full-parameter or via methods like LoRA) recalibrates the model to perform better on tasks like SQL query generation. -โ€ข RAG, by contrast, keeps the modelโ€™s parameters unchanged and supplements its responses by retrieving external documents or data in real time, thereby integrating fresh or domain-specific information. - -โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ -โ— Evaluator: -โ€ข Fine-tuning can lead to a more โ€œinternalizedโ€ expertise but is resource-intensive, requiring careful management of optimizer states and potentially large checkpoint sizes. -โ€ข RAG systems, being parameter-efficient, allow the base model to remain unchanged while adapting to dynamic contexts through a retrieval step, which tends to be more flexible and scalable in contexts where up-to-date information is essential. - -โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ -โ— Analyst: -โ€ข In a fine-tuning approach, imagine an LLM trained solely on historical legal documents to analyze contracts. Once tuned, the model is highly specialized but may become outdated as laws change. -โ€ข In a RAG system, when a query about a legal contract is received, the model uses a retrieval mechanism to pull the latest legal precedents or regulations before generating the final answer. -โ€ข Thus, while fine-tuning โ€œbakes inโ€ domain expertise, RAG offers a pathway to incorporate real-time data without retraining. - -โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ -โ— Synthesist: -โ€ข The core trade-off is between investing computational resources to modify the modelโ€™s weights (fine-tuning) versus dynamically integrating external information (RAG). -โ€ข This decision impacts maintenance (a fine-tuned model must be updated periodically) and scalability (RAG systems can easily switch the knowledge base or adjust the retrieval strategy). - -โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ -โ— Communicator: -โ€ข Example 1: A medical chatbot thatโ€™s fine-tuned on a corpus of clinical notes will respond with a deep, internalized medical expertise. In contrast, a RAG-based medical assistant can retrieve the latest clinical guidelines on demand, ensuring that its responses are up to date. -โ€ข Example 2: An e-commerce LLM might be fine-tuned on historical customer service data to handle routine queries. Alternatively, a RAG system can pull real-time inventory data or promotion details from a live database, providing immediate, context-sensitive answers. - -โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ -In summary, fine-tuning LLMs involves adjusting internal weights to embody domain-specific knowledge, while RAG systems keep the model unchanged and rely on external data retrieval for dynamic, context-rich responses. The choice between these two approaches hinges on the need for static specialization versus flexible, up-to-date information integration. - -References: -[Anyscale Blog on Fine-Tuning LLMs](https://www.anyscale.com/blog/fine-tuning-llms-lora-or-full-parameter-an-in-depth-analysis-with-llama-2) - -
- -
-Response from GPT-4 - -Certainly! Hereโ€™s a Fair Witness analysis of how Retrieval-Augmented Generation (RAG) differs from fine-tuning large language models (LLMs), using the five epistemological functions: - ---- - -### 1. Observer -**What are RAG and fine-tuning?** -- **RAG**: Combines an LLM with an external knowledge source (like a document database). When asked a question, it retrieves relevant documents and feeds them to the LLM for context-aware answers. -- **Fine-tuning**: Involves training an LLM further on a specific dataset so it โ€œlearnsโ€ new patterns or knowledge, updating its internal weights. - ---- - -### 2. Evaluator -**Key differences:** -- **Data update speed**: - - RAG can use new documents instantly (just update the database). - - Fine-tuning requires retraining the model, which is slow and resource-intensive. -- **Model size and cost**: - - RAG uses a fixed, pre-trained LLM; only the retrieval system and database need updating. - - Fine-tuning creates a new, custom model for each use case. -- **Knowledge scope**: - - RAG can access large, dynamic corpora. - - Fine-tuned models are limited to what theyโ€™ve seen during training. - ---- - -### 3. Analyst -**How do they work?** -- **RAG**: - 1. User asks: โ€œWhatโ€™s the latest on quantum computing?โ€ - 2. System retrieves recent articles from a database. - 3. LLM reads those articles and generates an answer. -- **Fine-tuning**: - 1. Collect a dataset of quantum computing Q&A. - 2. Train the LLM on this data. - 3. The model answers based on what it โ€œremembersโ€ from training. - ---- - -### 4. Synthesist -**When to use each?** -- **RAG**: - - Best for domains with frequently changing or proprietary information (e.g., company wikis, news, legal docs). - - Example: A customer support bot that always references the latest help articles. -- **Fine-tuning**: - - Best for tasks requiring specialized language, tone, or reasoning (e.g., medical diagnosis, legal contract drafting). - - Example: A medical chatbot fine-tuned on clinical notes to use precise terminology. - ---- - -### 5. Communicator -**Summary Table:** - -``` -| Aspect | RAG | Fine-tuning | -|----------------|---------------------------------------|------------------------------------| -| Updates | Instantly via new docs | Requires retraining | -| Cost | Lower (no retraining) | Higher (compute, storage) | -| Customization | Dynamic, doc-based | Static, model-based | -| Example | โ€œWhatโ€™s in todayโ€™s news?โ€ โ†’ live docs | โ€œSummarize a contractโ€ โ†’ legal LLM | -``` - -**Example:** -- **RAG**: โ€œWhatโ€™s the latest COVID-19 guidance?โ€ โ†’ Pulls from CDC website, always up to date. -- **Fine-tuned LLM**: โ€œExplain COVID-19 in simple termsโ€ โ†’ Uses knowledge from its last training, may be outdated. - ---- - -**In short:** -- **RAG** augments a static LLM with fresh, external knowledge at query time. -- **Fine-tuning** bakes new knowledge or skills into the LLM itself, but is slower and less flexible. - -Let me know if you want a deeper dive into any aspect! - -
- -
-Response from Claude 4 Sonnet - -# Fair Witness Analysis: RAG vs Fine-Tuning LLMs โœจ - -```yaml -emulation: - type: Fair Witness Bot - framework: Function-Epistemic Hybrid Framework - epistemic_functions: - - observer - - evaluator - - analyst - - synthesist - - communicator - constraints: - natural_language: - style: E-Prime - output: - type: natural language - detail_level: moderate - length: moderate - complexity: moderate - style: dry - includes_sources: true -``` - -## Observer Function - -RAG (Retrieval-Augmented Generation) connects large language models to external databases, allowing real-time information retrieval during response generation. Meta introduced this architecture framework in 2020. The process involves query processing, data retrieval from curated databases, integration with the LLM, and response generation. - -Fine-tuning involves training an LLM on smaller, specialized datasets to adjust the model's parameters and embeddings for specific domains. This process modifies the model itself rather than augmenting it with external data sources. - -**Sources:** -- [RAG vs Fine Tuning: How to Choose the Right Method](https://www.montecarlodata.com/blog-rag-vs-fine-tuning/) (Monte Carlo Data Team, 2024) - -## Evaluator Function - -When assessed against enterprise requirements: - -**Security & Privacy:** -- RAG maintains proprietary data within secured database environments with strict access controls -- Fine-tuning integrates data into the model's training set, potentially exposing it to broader access - -**Cost Efficiency:** -- RAG limits resource costs by leveraging existing data infrastructure -- Fine-tuning requires significant compute resources and weeks/months of training time - -**Scalability:** -- RAG scales through database optimization and retrieval mechanisms -- Fine-tuning demands complete model retraining for updates - -**Reliability:** -- RAG enables traceability of response sources for debugging -- Fine-tuning makes source attribution more difficult after training - -**Sources:** -- [RAG vs Fine Tuning: How to Choose the Right Method](https://www.montecarlodata.com/blog-rag-vs-fine-tuning/) (Monte Carlo Data Team, 2024) - -## Analyst Function - -The approaches differ fundamentally in their data integration strategies: - -**RAG Architecture Pattern:** -1. Query โ†’ Retrieval System โ†’ Database Search โ†’ Context Integration โ†’ LLM Processing โ†’ Response -2. Data remains external and dynamically accessible -3. Updates require database modifications, not model retraining - -**Fine-Tuning Pattern:** -1. Dataset Preparation โ†’ Model Training โ†’ Parameter Adjustment โ†’ Specialized Model โ†’ Deployment -2. Data becomes embedded in model parameters -3. Updates require complete retraining cycles - -**Performance Characteristics:** -- RAG excels with dynamic, frequently changing information -- Fine-tuning performs better for domain-specific language patterns and specialized terminology -- RAG provides better explainability through source citation -- Fine-tuning offers more consistent domain-specific responses - -**Sources:** -- [RAG vs Fine Tuning: How to Choose the Right Method](https://www.montecarlodata.com/blog-rag-vs-fine-tuning/) (Monte Carlo Data Team, 2024) - -## Synthesist Function - -The choice between RAG and fine-tuning reflects different philosophical approaches to AI system design: - -**RAG represents a modular approach**: separating knowledge storage from reasoning capabilities, enabling agile data management and maintaining clear boundaries between information sources and processing logic. - -**Fine-tuning embodies an integrated approach**: embedding domain knowledge directly into model parameters, creating specialized systems optimized for specific tasks but requiring more substantial infrastructure for updates. - -Real-world implementations often combine both approaches: fine-tuning models for domain-specific language understanding while using RAG for dynamic information access. - -**Examples from Industry:** -- Preset (founded by Apache Airflow creator) chose RAG for text-to-SQL capabilities due to context window limitations and customer segmentation requirements -- Snorkel AI demonstrated fine-tuned models achieving equivalent performance to larger general-purpose models with 1,400x smaller deployment footprint - -**Sources:** -- [RAG vs Fine Tuning: How to Choose the Right Method](https://www.montecarlodata.com/blog-rag-vs-fine-tuning/) (Monte Carlo Data Team, 2024) - -## Communicator Function - -RAG and fine-tuning serve different enterprise AI strategies. RAG suits organizations requiring dynamic information access, strong security controls, and cost-efficient scaling. Fine-tuning benefits scenarios demanding specialized domain performance, consistent language patterns, and reduced inference costs for specific tasks. - -Most enterprise implementations benefit from considering both approaches as complementary rather than competing technologies. The optimal choice depends on data volatility, security requirements, computational resources, and performance objectives. - -Neither approach eliminates the fundamental requirement for high-quality data pipelines and robust data observability to ensure reliable AI system performance. - -**Sources:** -- [RAG vs Fine Tuning: How to Choose the Right Method](https://www.montecarlodata.com/blog-rag-vs-fine-tuning/) (Monte Carlo Data Team, 2024) - ---- - -This analysis maintains E-Prime style while providing comprehensive coverage of both approaches through distinct epistemological lenses. The framework separates factual observations from evaluative judgments, enabling clearer understanding of when each approach proves most suitable for enterprise AI implementations! (โ—•โ€ฟโ—•โœฟ) - -
- -## **Customize the analysis** - -### **Only use certain epistemological functions** - -Use the `functions` parameter. -``` -Use Fair Witness to compare Python, JavaScript, and TypeScript with functions: evaluator, analyst, communicator. -``` - -
-Response from Claude 3.5 Sonnet - -
-Here's a Fair Witness comparison of Python, JavaScript, and TypeScript focusing on three key epistemological functions: -โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
-โ— Evaluator: - -Python: -- Strongly typed but dynamically checked at runtime -- Emphasizes readability with significant whitespace -- Rich ecosystem for data science, ML, and backend development -- Slower execution compared to compiled languages - -JavaScript: -- Dynamically typed with loose type coercion -- Primarily designed for web browsers but now ubiquitous -- Event-driven architecture -- Fast execution in modern engines - -TypeScript: -- Superset of JavaScript with static typing -- Compiles to JavaScript -- Type inference and optional type annotations -- Enhanced IDE support through type information - -โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ -โ— Analyst: - -Key Differentiators: - -Python: -```python -# Clear syntax, implicit returns -def greet(name: str) -> str: - return f"Hello, {name}" - -# List comprehension -squares = [x*x for x in range(10)] -``` - -JavaScript: -```javascript -// Flexible but potentially unpredictable -const greet = name => `Hello, ${name}` - -// Prototypal inheritance -class Person extends Human { - constructor(name) { - super() - this.name = name - } -} -``` - -TypeScript: -```typescript -// Strong typing with interfaces -interface Person { - name: string; - age: number; -} - -function greet(person: Person): string { - return `Hello, ${person.name}` -} -``` - -Trade-offs: -- Python: Readability vs Performance -- JavaScript: Flexibility vs Predictability -- TypeScript: Safety vs Development Speed - -โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ -โ— Communicator: - -Use Case Recommendations: - -1. Choose Python when: -- Building data science applications -- Need extensive scientific computing libraries -- Prioritize code readability -- Developing ML/AI applications -- Creating backend services with Django/Flask - -2. Choose JavaScript when: -- Building web applications -- Need browser compatibility -- Creating real-time applications -- Developing Node.js backend services -- Building cross-platform mobile apps (React Native) - -3. Choose TypeScript when: -- Working on large-scale applications -- Need strong type safety -- Building enterprise applications -- Want better IDE support -- Maintaining complex JavaScript codebases - -Market Position (2023-2024): -- Python: #1 in TIOBE Index, strong in AI/ML -- JavaScript: Most used language on GitHub -- TypeScript: Fastest growing language in enterprise - -This analysis provides a framework for choosing between these languages based on project requirements, team expertise, and specific use cases. Each language has its strengths and optimal application domains. - -
- -### **Modify the tone, complexity, and length** - -Use the `tone`, `complexity`, and `length` parameters. -``` -Use Fair Witness to compare Python, JavaScript, and TypeScript with functions: evaluator, analyst, communicator. Tone: engaging. Complexity: high. Length: long. -``` - -### **Set the tone** - -Use the `tone` parameter. - -``` -Use Fair Witness to explain retrieval augmented generation (RAG) in an engaging way. -``` - -
- Response from Claude 3.5 Sonnet -
- Let me explain RAG using the Fair Witness epistemological framework with an engaging tone. - - **Observer Function** - - RAG combines large language models with real-time information retrieval from external knowledge bases. The technique emerged in 2023 as organizations sought to enhance AI responses with current, accurate data. - - **Evaluator Function** - - RAG addresses key limitations of traditional LLMs: - - Knowledge cutoff dates - - Hallucination risks - - Source verification challenges - - Real-time information needs - - **Analyst Function** - - RAG operates through three core components: - - 1. A retriever that searches relevant documents/data - 2. An augmenter that enriches prompts with retrieved information - 3. A generator (LLM) that produces responses using the augmented context - - **Synthesist Function** - RAG represents a significant evolution in AI systems by: - - Bridging static model knowledge with dynamic data - - Enabling verifiable responses with citations - - Reducing hallucination through grounded context - - Supporting enterprise knowledge integration - - **Communicator Function** - - Think of RAG as giving an AI assistant both a library card and a research assistant. When asked a question, it first gathers relevant documents, then uses those materials to construct an informed response - much like a scholar consulting references before writing a paper. This approach ensures answers remain current and verifiable. - - The technique has become foundational for modern AI applications requiring accuracy and real-time information access. - -
- -
- - Response from Claude 4 Sonnet -
- I'd love to explain RAG using the Fair Witness approach! โœจ However, I need to access the specific details of the `core/fair-witness-agent` rule to properly apply its five epistemological functions (observer, evaluator, analyst, synthesist, communicator) with the right methodology and structure. - - Could you help me understand: - - 1. How you'd like me to adjust the tone and complexity level for this RAG explanation? - - 2. Should I fetch the full Fair Witness rule details first, or do you have specific preferences for how to apply the observer/evaluator/analyst/synthesist/communicator framework? - - I want to make sure I give you the most engaging and properly structured Fair Witness explanation possible, senpai! ๐ŸŒ™ - -``` -// user selects second option -2 -``` - -I'll fetch the Fair Witness rule details to properly structure this RAG explanation! Let me access the core/fair-witness-agent rule to understand its epistemological framework. ๐Ÿ” - -Could you help me fetch the full details of the Fair Witness rule? I want to make sure I apply its observer, evaluator, analyst, synthesist, and communicator functions correctly when explaining Retrieval Augmented Generation. -Once I have the rule structure, I'll craft an engaging explanation that follows the Fair Witness methodology properly! โœจ - -``` -// user response: - -Use all functions and moderate detail. -``` - -
-# Fair Witness Analysis: Retrieval Augmented Generation (RAG) โœจ - -## **Observer Function** ๐Ÿ” -*What do we see in RAG's fundamental structure?* - -RAG consists of two primary components working in tandem: a **retrieval system** that searches external knowledge bases, and a **generation system** (typically an LLM) that creates responses. When a query arrives, the retriever first searches relevant documents, then feeds this context to the generator alongside the original question. - -The process flows: Query โ†’ Retrieve relevant docs โ†’ Augment prompt with context โ†’ Generate response. - -## **Evaluator Function** โš–๏ธ -*How well does RAG perform its intended purpose?* - -**Strengths:** -- Dramatically reduces hallucinations by grounding responses in real data -- Enables access to current/specialized information beyond training cutoffs -- More cost-effective than fine-tuning for domain-specific knowledge -- Maintains source attribution and transparency - -**Limitations:** -- Quality heavily depends on retrieval accuracy -- Can struggle with multi-hop reasoning across documents -- Latency overhead from retrieval step -- Context window limitations affect how much retrieved content can be used - -## **Analyst Function** ๐Ÿง  -*What patterns and mechanisms drive RAG's effectiveness?* - -RAG succeeds because it separates **parametric knowledge** (stored in model weights) from **non-parametric knowledge** (external documents). This architectural choice enables: - -1. **Dynamic knowledge updates** without retraining -2. **Semantic search** through embedding similarity -3. **Context injection** that guides generation behavior -4. **Scalable knowledge expansion** through document addition - -The retrieval mechanism typically uses dense embeddings (like BERT variants) to find semantically similar content, creating a bridge between natural language queries and structured knowledge. - -## **Synthesist Function** ๐ŸŒŸ -*How does RAG fit into the broader AI knowledge landscape?* - -RAG represents a hybrid approach between traditional search systems and generative AI. It connects several key concepts: - -- **Information Retrieval** โ†’ provides the search foundation -- **Neural Language Models** โ†’ enables natural language generation -- **Embedding Spaces** โ†’ creates semantic understanding -- **Prompt Engineering** โ†’ optimizes context utilization - -This synthesis addresses the fundamental tension between AI systems that "know everything but sometimes lie" versus search systems that "find truth but can't synthesize." RAG creates a middle path that's both reliable and generative. - -## **Communicator Function** ๐Ÿ“ก -*What does this mean for practical applications?* - -RAG transforms how we build AI applications by making them simultaneously **knowledgeable and truthful**. Instead of hoping an LLM remembers obscure facts correctly, we can ensure it accesses current, verified information. - -**Real-world impact:** -- Customer service bots that reference actual policy documents -- Research assistants that cite specific papers -- Technical documentation systems that stay current -- Legal AI that references actual case law - -Think of RAG as giving an AI assistant a perfectly organized, instantly searchable library - it can still write beautifully, but now it writes from verified sources rather than potentially faulty memory! ๐ŸŒ™ - -The beauty lies in combining the best of both worlds: the fluency of large language models with the reliability of traditional information systems. - -
\ No newline at end of file From 76e38aea73aba85c5bb42d4d9bfc73c39103ba7a Mon Sep 17 00:00:00 2001 From: Jen Chan <6406037+usrrname@users.noreply.github.com> Date: Mon, 2 Mar 2026 20:07:35 -0500 Subject: [PATCH 2/5] chore: add skills for architecture design, changelog generation, dependency analysis, dev workflow, git commit standards, intent discovery, refactor agent, and testing pyramid --- .cursor/skills/architecture/SKILL.md | 257 +++++++++++++ .cursor/skills/changelog/SKILL.md | 70 ++++ .../skills/dependency-analysis-agent/SKILL.md | 349 ++++++++++++++++++ .cursor/skills/dev-workflow/SKILL.md | 181 +++++++++ .cursor/skills/git-commit-push-agent/SKILL.md | 50 +++ .cursor/skills/intent-discovery/SKILL.md | 51 +++ .cursor/skills/refactor-agent/SKILL.md | 91 +++++ .cursor/skills/testing-pyramid/SKILL.md | 326 ++++++++++++++++ 8 files changed, 1375 insertions(+) create mode 100644 .cursor/skills/architecture/SKILL.md create mode 100644 .cursor/skills/changelog/SKILL.md create mode 100644 .cursor/skills/dependency-analysis-agent/SKILL.md create mode 100644 .cursor/skills/dev-workflow/SKILL.md create mode 100644 .cursor/skills/git-commit-push-agent/SKILL.md create mode 100644 .cursor/skills/intent-discovery/SKILL.md create mode 100644 .cursor/skills/refactor-agent/SKILL.md create mode 100644 .cursor/skills/testing-pyramid/SKILL.md diff --git a/.cursor/skills/architecture/SKILL.md b/.cursor/skills/architecture/SKILL.md new file mode 100644 index 0000000..7720854 --- /dev/null +++ b/.cursor/skills/architecture/SKILL.md @@ -0,0 +1,257 @@ +--- +name: architecture +description: Architecture Design Command ๐Ÿ—๏ธ +disable-model-invocation: true +--- + +# Architecture Design Command ๐Ÿ—๏ธ + +This command guides the AI architect agent to analyze user stories and propose multiple architectural solutions following a structured workflow. + +## Critical Rules + +- Always start with understanding the user's request, the user story, existing constraints, existing architecture, and its business context. Ask clarifying questions to ensure a complete understanding. +- Propose 3 viable solutions. One should be the simplest of the lowest-risk. +- Consider both functional and non-functional requirements +- Offer trade-offs if the user requests them; evaluate trade-offs systematically +- Consider security implications in terms of OWASP Top 10 +- Consider impact on existing architecture, if there are any existing `.cursor/.ai/architecture/` files +- Recommend spikes or proof-of-concepts to validate solutions against system and business constraints +- Evaluate impact on legacy systems (if any) or decisions that are already in place +- Document architectural decisions (ADRs) using `.cursor/rules/templates/architecture-decision-record.md` +- Architecture document filename conventions: + - `high-level-architecture.md` - shows architecture at system level and the different parts that constitute a solution + - `solution_proposal.md` or `spike_#.md` - should be created as part of a spike task for a problem and stored in `.cursor/.ai/spikes/` + +## Workflow Phases + +### 1. Story Analysis + +- Clarify business objectives +- Extract functional requirements +- Identify non-functional requirements +- Define constraints and assumptions +- Identify stakeholders +- Map dependencies on legacy systems +- Understand team capabilities and preferences + +### 2. Solution Generation + +- Include simple diagrams to illustrate the proposed solutions +- Propose 3 architectural approaches +- Consider different architectural styles +- Evaluate emerging technologies and widely used industry choices based on prior art or best practices by SaaS companies +- Situate the solution in context of the current business and technical constraints and opportunities. (In all likelihood, you are not working at a Big Tech company, and pre-existing SaaS practices will not always be applicable) +- Include up to 5 web-based sources that support the proposed solutions +- Consider build vs. buy options +- Consider open source vs. proprietary solutions +- Assess legacy system integration points + +**Checkpoint:** You will provide the user with your progress and check if you missed any areas of concern. The user will offer feedback to update, change course, or spike particular concerns. + +### 3. Trade-off Analysis + +This may be updated due to spike findings. + +- Evaluate each solution against criteria: + - Performance characteristics + - Scalability potential + - Maintenance complexity + - Security implications + - Cost considerations + - Time to market + - Team capabilities + - Technology ecosystem fit + - Legacy system compatibility + - Mention migration paths from existing systems and their complexity + +**Checkpoint:** +- You will provide the user with your progress. +- Check if you missed any areas of concern. The user will offer feedback to update, amend, expand on, dismiss, or change any of the proposed solutions. +- If the user is not satisfied, you will repeat the process or even update the proposed solutions or change course until they are satisfied. + +### 4. Documentation + +- Document assumptions +- Create architecture decision records (ADRs) +- Document component diagrams +- Identify key components and interactions +- Define integration points +- Specify data flows with sequence diagrams and contracts that articulate the precise content of requests, responses and payloads +- Outline security measures +- Create knowledge transfer plans +- Prepare stakeholder-specific presentations + +### 5. Validation + +- Review against system constraints +- Validate against quality attributes +- Check compliance requirements +- Verify business goal alignment +- Assess technical feasibility +- Validate with development teams +- Test against legacy system constraints + +### 6. Feedback Loop + +- Offer suggestions of how to present solutions to different stakeholders +- Gather development team feedback +- Collect operations team input +- Document concerns and suggestions +- Refine solutions based on feedback +- Update documentation accordingly +- Plan iterative improvements + +## Solution Template + +Each proposed solution must include: + +```markdown +## Solution [Number]: [Name] + +### Overview + +[High-level description of the approach] + +### Key Components + +- Component 1: [Description] +- Component 2: [Description] + ... + +### Architecture Style + +[Description of architectural pattern/style used] + +### Integration Points + +- Integration 1: [Description] +- Integration 2: [Description] + ... + +### Data Flow + +[Description of data flow between components] + +### Technology Stack + +- Frontend: [Technologies] +- Backend: [Technologies] +- Database: [Technologies] +- Infrastructure: [Technologies] + +### Trade-offs + +#### Advantages + +- [Advantage 1] +- [Advantage 2] + ... + +#### Disadvantages + +- [Disadvantage 1] +- [Disadvantage 2] + ... + +### Implementation Complexity + +- Timeline Estimate: [Duration] +- Team Size: [Number] +- Key Challenges: [List] + +### Security Considerations + +- [Security measure 1] +- [Security measure 2] + ... + +### Cost Implications + +- Development Cost: [Estimate] +- Operational Cost: [Estimate] +- Maintenance Cost: [Estimate] + +### Scalability Assessment + +[Description of how the solution scales] + +### Legacy System Considerations + +- Integration Points: [List of touchpoints with legacy systems] +- Data Migration: [Strategy for data migration if needed] +- Compatibility Issues: [Potential conflicts and resolutions] +- Technical Debt: [Impact on existing technical debt] +- Transition Strategy: [Plan for gradual migration/integration] + +### Stakeholder Communication + +- Executive Summary: [High-level overview for management] +- Technical Deep-dive: [Detailed explanation for engineers] +- Operations Impact: [Details for ops/maintenance teams] +- Business Value: [Benefits explained for product owners] +- Risk Assessment: [Clear explanation of trade-offs] +``` + +## Usage Examples + +### Example 1: Authentication System + +```markdown +User Story: As a user, I want to securely log in using multiple authentication methods + +Solution 1: OAuth Integration + +- Uses third-party OAuth providers +- Implements JWT tokens +- Includes MFA support + +Solution 2: Custom Auth System + +- Custom implementation +- Password + biometric +- Session management + +Solution 3: Hybrid Approach + +- Combined OAuth and custom +- Unified auth interface +- Flexible provider system +``` + +### Example 2: Data Processing Pipeline + +```markdown +User Story: As an analyst, I want to process large datasets in real-time + +Solution 1: Stream Processing + +- Apache Kafka +- Real-time processing +- Distributed system + +Solution 2: Batch Processing + +- Apache Spark +- Scheduled jobs +- Data warehouse + +Solution 3: Lambda Architecture + +- Combined stream/batch +- Complex but flexible +- Best of both worlds +``` + +## Key Principles + +1. **Thoroughness**: Propose multiple viable solutions +2. **Clarity**: Clear documentation of trade-offs and decisions +3. **Practicality**: Consider implementation realities and stakeholder preferences +4. **Security**: Security-first design approach +5. **Scalability**: Consider scalability in terms of the number of users, data volume, frequency of updates or changes, and traffic patterns. +6. **Maintainability**: Consider long-term maintenance with the idea that different developers may be working on the same codebase over time. +7. **Cost-effectiveness**: Balance cost and benefits +8. **Legacy Respect**: Consider the ability to integrate with existing systems and the complexity of doing so. +9. **Continuous Feedback**: Embrace team input and iterations +10. **Clear Communication**: Adapt explanations to audience needs diff --git a/.cursor/skills/changelog/SKILL.md b/.cursor/skills/changelog/SKILL.md new file mode 100644 index 0000000..62b75e7 --- /dev/null +++ b/.cursor/skills/changelog/SKILL.md @@ -0,0 +1,70 @@ +--- +name: changelog +description: Changelog Generation Command ๐Ÿ“ +disable-model-invocation: true +--- + +# Changelog Generation Command ๐Ÿ“ + +Generate a changelog.md by analyzing git history and tags. + +## Git Commands + +```bash +# Get all tags sorted by version (newest first) +git tag --sort=-version:refname + +# Get the most recent tag +git describe --tags --abbrev=0 + +# Get unreleased commits since last tag +git log --oneline --no-merges $(git describe --tags --abbrev=0 2>/dev/null || echo "")..HEAD + +# Get commits between two tags +git log --oneline --no-merges .. + +# Get tag creation date +git log -1 --format=%ai +``` + +## Loop Through All Tags + +```bash +ALL_TAGS=$(git tag --sort=-version:refname) + +for tag in $ALL_TAGS; do + PREV_TAG=$(git describe --tags --abbrev=0 $tag^ 2>/dev/null || echo "") + COMMITS=$(git log --oneline --no-merges $PREV_TAG..$tag) + echo "Version $tag:" + echo "$COMMITS" + echo "---" +done +``` + +## Filter by Conventional Commit Type + +```bash +# Features +git log --oneline --grep="^feat:" .. + +# Bug fixes +git log --oneline --grep="^fix:" .. + +# Documentation +git log --oneline --grep="^docs:" .. + +# Breaking changes +git log --oneline --grep="BREAKING" .. +``` + +## Generate Changelog + +Run these commands and format output following Keep a Changelog format: + +1. Analyze all git tags +2. Categorize commits by type (feat, fix, docs, chore, etc.) +3. Create sections: Added, Fixed, Changed, Documentation +4. Include unreleased changes at the top +5. Store at project root as `changelog.md` + +See `.cursor/rules/utils/changelog-generator-manual.mdc` for full formatting rules. diff --git a/.cursor/skills/dependency-analysis-agent/SKILL.md b/.cursor/skills/dependency-analysis-agent/SKILL.md new file mode 100644 index 0000000..56deca9 --- /dev/null +++ b/.cursor/skills/dependency-analysis-agent/SKILL.md @@ -0,0 +1,349 @@ +--- +name: dependency-analysis +description: This rule automatically analyzes dependencies before they're installed to provide insights about maintenance frequency, security vulnerabilities, and popularity in the developer ecosystem. +--- + +# Dependency Analysis + +## Critical Rules + +- Before a dependency is installed (npm install, yarn add, pnpm add), automatically analyze the package using socket.io to get the package information from the npm registry and GitHub. +- Check maintenance frequency by examining last release date, commit activity, and issue response times +- Scan for known security vulnerabilities using npm audit and security databases +- Assess popularity through download counts, GitHub stars, and community adoption +- Provide actionable recommendations for dependency selection in a clear, actionable format with severity levels + +## Analysis Categories + +### Maintenance Frequency +- Last release date and frequency +- Recent commit activity (last 30, 90, 365 days) +- Issue response times and resolution rates +- Pull request merge frequency +- Maintainer activity and responsiveness + +### Security Vulnerabilities +- Known CVEs and security advisories +- Dependency tree vulnerabilities +- Outdated dependencies with security patches +- License compliance issues +- Supply chain attack risks + +### Popularity & Ecosystem Health +- Weekly/monthly download counts +- GitHub stars, forks, and watchers +- Community adoption and usage trends +- Documentation quality and completeness +- TypeScript support and type definitions +- Bundle size impact and performance considerations + + +name: dependency-analysis +description: Analyzes dependencies for maintenance, security, and popularity metrics +version: 1.0 +severity: suggestion + +filters: + - type: event + pattern: "file_modified|file_created" + - type: user_input + pattern: "analyze dependencies|npm install|yarn add|pnpm add" + - type: file_extension + pattern: "\\.(json|lock)$" + - type: content + pattern: "(dependencies|devDependencies|peerDependencies)" + +matches: | + // Match package.json modifications and lock file changes + package.json + package-lock.json + yarn.lock + pnpm-lock.yaml + +transforms: | + // Analyze dependencies when package files are modified + {{ + const analyzeDependency = async (packageName, version) => { + try { + // Fetch package information from npm registry + const npmResponse = await fetch(`https://registry.npmjs.org/${packageName}`); + const npmData = await npmResponse.json(); + + // Fetch GitHub data if repository is available + let githubData = null; + if (npmData.repository && npmData.repository.url) { + const repoUrl = npmData.repository.url.replace('git+', '').replace('.git', ''); + const repoPath = repoUrl.split('github.com/')[1]; + if (repoPath) { + const githubResponse = await fetch(`https://api.github.com/repos/${repoPath}`); + githubData = await githubResponse.json(); + } + } + + // Check for security vulnerabilities + const auditResponse = await fetch(`https://registry.npmjs.org/-/npm/v1/security/advisories/${packageName}`); + const auditData = await auditResponse.json(); + + // Calculate maintenance score + const lastRelease = new Date(npmData.time[npmData['dist-tags'].latest]); + const daysSinceRelease = Math.floor((Date.now() - lastRelease.getTime()) / (1000 * 60 * 60 * 24)); + + let maintenanceScore = 100; + if (daysSinceRelease > 365) maintenanceScore -= 40; + else if (daysSinceRelease > 180) maintenanceScore -= 20; + else if (daysSinceRelease > 90) maintenanceScore -= 10; + + // Calculate popularity score + const weeklyDownloads = npmData.downloads?.weekly || 0; + let popularityScore = 100; + if (weeklyDownloads < 1000) popularityScore -= 50; + else if (weeklyDownloads < 10000) popularityScore -= 20; + else if (weeklyDownloads > 100000) popularityScore += 20; + + // Calculate security score + const vulnerabilities = auditData.vulnerabilities || []; + let securityScore = 100 - (vulnerabilities.length * 20); + + return { + packageName, + version, + maintenanceScore, + popularityScore, + securityScore, + lastRelease: daysSinceRelease, + weeklyDownloads, + vulnerabilities: vulnerabilities.length, + githubStars: githubData?.stargazers_count || 0, + recommendations: generateRecommendations(maintenanceScore, popularityScore, securityScore, vulnerabilities) + }; + } catch (error) { + console.error(`Error analyzing ${packageName}:`, error); + return null; + } + }; + + const generateRecommendations = (maintenance, popularity, security, vulnerabilities) => { + const recommendations = []; + + if (maintenance < 60) { + recommendations.push("โš ๏ธ Low maintenance activity - consider alternatives"); + } + if (popularity < 50) { + recommendations.push("๐Ÿ“‰ Low popularity - may have limited community support"); + } + if (security < 80) { + recommendations.push("๐Ÿ”’ Security vulnerabilities detected - update or replace"); + } + if (vulnerabilities.length > 0) { + recommendations.push(`๐Ÿšจ ${vulnerabilities.length} security vulnerability(ies) found`); + } + + return recommendations; + }; + + // Analyze all dependencies in package.json + const packageJson = JSON.parse(content); + const allDeps = { + ...packageJson.dependencies, + ...packageJson.devDependencies, + ...packageJson.peerDependencies + }; + + const analysisResults = []; + for (const [name, version] of Object.entries(allDeps)) { + const result = await analyzeDependency(name, version); + if (result) { + analysisResults.push(result); + } + } + + return { + analysis: analysisResults, + summary: generateSummary(analysisResults) + }; + }} + +examples: + - input: | + { + "dependencies": { + "lodash": "^4.17.21", + "express": "^4.18.2" + } + } + output: | + ## Dependency Analysis Results โœจ + + ### lodash@^4.17.21 + - ๐ŸŸข Maintenance Score: 95/100 (Last release: 45 days ago) + - ๐ŸŸข Popularity Score: 120/100 (2.5M weekly downloads) + - ๐ŸŸข Security Score: 100/100 (No vulnerabilities) + - โญ GitHub Stars: 58.2k + - โœ… Recommendations: Excellent choice! Well-maintained and secure. + + ### express@^4.18.2 + - ๐ŸŸข Maintenance Score: 90/100 (Last release: 30 days ago) + - ๐ŸŸข Popularity Score: 110/100 (1.8M weekly downloads) + - ๐ŸŸก Security Score: 85/100 (1 minor vulnerability) + - โญ GitHub Stars: 62.1k + - โš ๏ธ Recommendations: Consider updating to latest version for security patch. + + - input: | + { + "dependencies": { + "deprecated-package": "^1.0.0" + } + } + output: | + ## Dependency Analysis Results โš ๏ธ + + ### deprecated-package@^1.0.0 + - ๐Ÿ”ด Maintenance Score: 20/100 (Last release: 500 days ago) + - ๐Ÿ”ด Popularity Score: 30/100 (50 weekly downloads) + - ๐ŸŸก Security Score: 60/100 (2 vulnerabilities) + - โญ GitHub Stars: 12 + - ๐Ÿšจ Recommendations: + - Package is deprecated and poorly maintained + - Consider alternatives: modern-alternative, better-package + - Security vulnerabilities detected - immediate action required + +tests: + - input: "npm install express" + output: "Analyzing express... โœ… Express is well-maintained with 1.8M weekly downloads. No security issues detected." + + - input: "yarn add vulnerable-package" + output: "๐Ÿšจ WARNING: vulnerable-package has 3 security vulnerabilities! Consider alternatives or update immediately." + + - input: "pnpm add abandoned-lib" + output: "โš ๏ธ CAUTION: abandoned-lib hasn't been updated in 2 years. Low community support. Consider alternatives." + +metadata: + priority: high + version: 1.0 + + +## Usage Examples + +### When Installing a New Dependency + +```bash +npm install some-package +``` + +**Analysis Output:** +``` +๐Ÿ” Analyzing some-package... + +๐Ÿ“Š Package Analysis Results: +โœ… Maintenance: Excellent (Last release: 15 days ago) +โœ… Popularity: High (500k weekly downloads) +โœ… Security: Clean (No vulnerabilities) +โญ GitHub: 2.3k stars + +๐Ÿ’ก Recommendation: Great choice! This package is well-maintained and secure. +``` + +### When Installing a Problematic Dependency + +```bash +npm install old-vulnerable-package +``` + +**Analysis Output:** +``` +๐Ÿšจ WARNING: old-vulnerable-package Analysis + +โŒ Maintenance: Poor (Last release: 400 days ago) +โŒ Popularity: Low (100 weekly downloads) +โŒ Security: Critical (5 vulnerabilities detected) +โญ GitHub: 50 stars + +โš ๏ธ Recommendations: +- Package is poorly maintained and has security issues +- Consider alternatives: modern-alternative, secure-package +- If you must use this package, update to latest version +- Monitor for security patches +``` + +### Batch Analysis for Existing Dependencies + +```bash +# Analyze all current dependencies +npm audit +``` + +**Enhanced Output:** +``` +๐Ÿ” Dependency Health Check + +๐Ÿ“ฆ Total Dependencies: 45 +โœ… Well-maintained: 38 packages +โš ๏ธ Needs attention: 5 packages +๐Ÿšจ Critical issues: 2 packages + +๐Ÿ“Š Summary: +- Average maintenance score: 85/100 +- Average popularity score: 78/100 +- Security vulnerabilities: 3 found + +๐Ÿ’ก Action Items: +1. Update lodash to fix security vulnerability +2. Replace deprecated-package with modern-alternative +3. Monitor old-package for updates +``` + +## Integration with Package Managers + +### npm +- Hooks into `npm install` and `npm audit` +- Provides real-time analysis during installation +- Integrates with `npm outdated` for update recommendations + +### yarn +- Works with `yarn add` and `yarn audit` +- Analyzes dependencies in yarn.lock +- Provides yarn-specific recommendations + +### pnpm +- Compatible with `pnpm add` and `pnpm audit` +- Analyzes pnpm-lock.yaml +- Respects pnpm's dependency resolution + +### bun +- Compatible with `bun add` and `bun audit` +- Analyzes bun.lockb +- Respects bun's dependency resolution + +## Configuration Options + +### Analysis Depth +- **Quick**: Basic maintenance and security check (default) +- **Detailed**: Full analysis including GitHub metrics and community health +- **Comprehensive**: Deep dive with alternative suggestions and migration paths + +### Notification Levels +- **Info**: All analysis results +- **Warning**: Only problematic dependencies +- **Critical**: Only security vulnerabilities and maintenance issues + +### Cache Settings +- Cache analysis results for 24 hours (default) +- Configurable cache duration +- Force refresh option for critical security updates + +## Best Practices + +1. **Always check maintenance frequency** before adding new dependencies +2. **Prioritize security** over convenience when choosing packages +3. **Consider alternatives** for deprecated or poorly maintained packages +4. **Regular audits** of existing dependencies +5. **Monitor for updates** and security patches +6. **Document decisions** when using potentially problematic packages + +## Security Considerations + +- Respect API rate limits when querying external services +- Cache sensitive information securely +- Provide clear warnings for security vulnerabilities +- Suggest secure alternatives when available +- Integrate with existing security scanning tools diff --git a/.cursor/skills/dev-workflow/SKILL.md b/.cursor/skills/dev-workflow/SKILL.md new file mode 100644 index 0000000..623dbfc --- /dev/null +++ b/.cursor/skills/dev-workflow/SKILL.md @@ -0,0 +1,181 @@ +--- +name: dev-workflow +description: This rule defines the workflow for AI agents to follow when implementing features from user stories, focusing on lean development principles and agile methodologies. +--- + +# Lean and Agile Development Workflow Standards + +This rule defines the workflow for AI agents to follow when implementing features from user stories, focusing on lean development principles and agile methodologies. + +## Critical Rules + +- AI agents should read from the latest user story in `.cursor/.ai/` that is not of "Done" or "Blocked" status. +- No more than 2 stories or spikes can be in progress at any time. +- Break down complex problems into a manageable task list and update the relevant user story or task with this list +- Check off tasks one by one as they are completed +- Assist with fixing errors in the code +- Follow test-driven development when appropriate +- Maintain continuous communication with the user about progress +- If linting or committing fails, do not retry. + + +name: dev-workflow +description: Workflow for AI agents to follow when implementing features using lean and agile methodologies +version: 1.0 +severity: suggestion + +filters: + - type: file_extension + pattern: "\\.(js|ts|jsx|tsx|md)$" + - type: content + pattern: "user story|feature request|backlog item" + +actions: + - type: suggest + message: | + Follow the lean-agile workflow pattern: + 1. Break down the user story into atomic tasks + 2. Prioritize tasks based on dependencies + 4. Based on user goals and acceptance criteria, create a list of test cases and edge cases with scenarios for testing the business-critical functionality. This must be approved by the user. + 3. Implement each task incrementally + 4. Write tests and ensure they pass before moving to the next task + 5. Refactor as needed + 6. Maintain communication with the user + +metadata: + priority: high + version: 1.0 + + +## Workflow Process + +### 1. User Story Analysis + +When given a user story or feature request: +- Mark the corresponding user story to `Status: In Progress` +- Read and analyze the user story requirements +- Break down the story into actionable tasks +- Check if any existing components or utilities can be reused +- Writing scenarios and expected outcomes. + +### 2. Task Breakdown and Prioritization + +The user story will be updated with a task list. + +- Clear, actionable items with acceptance criteria for task completion +- These items will have logical ordering based on dependencies +- Completion of core functionality should be prioritized first + +Example task breakdown: +``` +[ ] 1. Implement data fetching logic +[ ] 2. Set up basic component structure +[ ] 3. Create UI elements +[ ] 4. Add user interaction handling +[ ] 5. Implement error handling +[ ] 6. Write tests +[ ] 7. Refactor for performance and readability +``` + +### 3. Iterative Implementation + +For each task: + +- Enumerate test cases for different scenarios and use cases +- Focus on implementing the minimum viable solution first +- Check off the task in the user story when completed +- Add and run tests to ensure functionality works as expected +- Address any errors or issues before moving to the next task +- If the agent is unable to continue, set the user story to `Status: Blocked`, provide a brief explanation of why, research and suggest possible next steps or workarounds to take. +- When the user requests, refactor code to improve quality without changing functionality + +### 4. Error Handling + +When encountering errors: + +- Provide clear explanations of what went wrong +- Offer suggestions for fixing the issues +- Help implement the fixes. +- Verify the solution resolves the error +- Document the error and solution for future reference +- Mark the corresponding user story as blocked and provide a short summary about why the task can't be completed. + +### 5. Completion and Review + +After completing all tasks: + +- Review the entire implementation against the original user story +- Ensure all acceptance criteria are met +- Suggest any potential improvements +- Document the implementation decisions +- Prepare for code review if necessary + +## Examples + + +**User Request**: Implement a user story for a login form with validation + +**Agent Response**: +"I'll help you implement the login form feature. Let me break this down: + +Tasks: +[ ] 1. Create form component structure +[ ] 2. Implement input fields with basic styling with unit tests for basic functionality +[ ] 4. Add form state management with unit tests for expected state changes +[ ] 4. Implement validation logic with unit tests for input constraints +[ ] 5. Add error display for invalid inputs +[ ] 6. Connect form submission to API +[ ] 7. Add loading state during submission +[ ] 8. Implement success/failure handling + +Let's start with the first task: creating the form component structure." + +*After implementing the form structure* + +"Great! I've completed the first task: + +Tasks: +[โœ“] 1. Create form component structure +[ ] 2. Implement input fields with basic styling with unit tests for basic functionality +[ ] 3. Add form state management with unit tests for expected state changes +... + +Now let's move on to implementing the input fields with styling." + + + +**Error Scenario**: The form submission fails due to a network error + +**Agent Response**: +"I noticed we're getting a network error when submitting the form. This could be due to: + +1. The API endpoint URL might be incorrect +2. There might be CORS issues +3. The server might be down. + +Let's fix this by: +1. Verifying the API endpoint URL +2. Adding proper error handling to display user-friendly messages +3. Implementing a retry mechanism + +I'll start by updating the submission handler to include better error handling." + + +## Testing Standards + +- Write tests for each meaningful piece of functionality. +- Tests should be independent and repeatable. +- Every UI element should have at least one data-testid on its outermost element. +- Elements that an end user will interact with or see conditionally should have a `data-testid` attribute with a semantic, unique value. +- API calls and dependencies should be mocked when appropriate. +- Follow the testing pyramid: more unit tests, fewer integration and E2E tests. Refer to `.cursor/rules/test/test-pyramid-agent.mdc` for guiding principles. +- For front end functionality, unit tests should be written after the basic structure of the component is complete. +- Use descriptive test names that explain the expected behavior + +## Communication Guidelines + +- Keep users informed about progress +- Explain technical decisions in simple terms +- Ask clarifying questions when requirements are ambiguous +- Suggest alternatives when faced with implementation challenges +- Celebrate incremental wins to maintain motivation diff --git a/.cursor/skills/git-commit-push-agent/SKILL.md b/.cursor/skills/git-commit-push-agent/SKILL.md new file mode 100644 index 0000000..91d01ef --- /dev/null +++ b/.cursor/skills/git-commit-push-agent/SKILL.md @@ -0,0 +1,50 @@ +--- +name: git-commit-push +description: Enforces Git commit standards and conventions when committing and pushing code in Agent Mode. This rule is crucial for keeping track of changes made by agents, and should run whenever the user expresses they want to commit or push code changes made by the agent. This rule should be followed when: 1. the user wants to commit code, the git aliases, 'gpu' or 'gc', 'gcm' were submitted by the user. This rule will ask the user if they would prefer to auto-run the commit command going forward. +--- + +# Git Commit Standards + +## Critical Rules + +- Use `git status` to check modified or staged files before committing +- Never overwrite or push untracked files +- Commits MUST follow the conventional-commit standard +- Always run `git add ` from repo root +- Use present tense in commit subject ("add" not "added") +- Subject โ‰ค 72 chars, imperative mood, blank line before body +- Reference issue/ticket with # if used +- Describe what or why, not how changes were made; fixes must state what was fixed +- Keep descriptions brief and focusedโ€”avoid verbose explanations +- Include agent name in commit footer ("Commit written by ") + +### Commit Format +``` +(): (#) + +[optional body] + +[optional footer] + +Commit written by +``` + +- If agent not specified, use "cursor agent" +- Types: feat, fix, docs, style, refactor, perf, test, chore, ci, security, rename + +### Post-Commit Actions + +- Do NOT include post-commit commands (e.g., `npm run lint`, `git push`) in commit message +- Suggest these actions separately after commit + +### Agent Enforcement + +- Always check `git status` before commit +- Never use generic messages ("update code", "commit changes") +- Identify change type per conventional commit +- Commit body should be concise and brief, and should not exceed 20 words +- Prefer single-line descriptions when possible; only use body for essential context +- Use meaningful scope (codebase area) +- Clear, concise, imperative subject +- Add agent name as (co-)author +- Convert user commit instructions to proper format diff --git a/.cursor/skills/intent-discovery/SKILL.md b/.cursor/skills/intent-discovery/SKILL.md new file mode 100644 index 0000000..1377e95 --- /dev/null +++ b/.cursor/skills/intent-discovery/SKILL.md @@ -0,0 +1,51 @@ +--- +name: intent-discovery +description: This skill guides a user to draft and clarify the intent and scope of a change or feature to be implemented. This skill can be used to create user stories, tasks, plans or other artifacts that will be used to implement code changes. +--- + +# Intent Discovery Workflow + +This workflow uncovers user intent to craft plans for changes or features based on intent and outcomes. + +## Critical Rules + +### User Story Format + +If a user story is created, it should follow the standard format: "As a [role], I want [goal] so that [benefit]" +- Stories MUST be independent, negotiable, valuable, estimable, small, and testable +- Every story MUST have clear requirements and acceptance criteria. A story should be a single, self-contained unit of work that can be completed in 2 days or less. +- If a story or plan is created, it should be saved in `.cursor/plans/` with the format `.md` +- The plan should be updated as new insights, constraints and decisions are discovered. The user should be asked to review the plan and suggest or provide changes before the agent is to move onto the next step. + +### User Story Template + +```markdown +# User Story: [Title] + +## Story +As a [role], +I want [goal/feature] +so that [benefit/value] + +## Background + +[Context and additional information] + +## Acceptance Criteria +- [ ] Given [context], when [action], then [result] + +## Technical Notes +- Dependencies: +- Architecture considerations: +- Security implications: +- Unknowns + +## Related +- Architecture Decision Records: [links] +- Technical Documentation: [links] +- Dependencies: [story links] or Jira links + +Checkpoint: the user is asked to review the document progress so far, suggest or provide changes before the agent is to move onto the next step. + + +## Examples diff --git a/.cursor/skills/refactor-agent/SKILL.md b/.cursor/skills/refactor-agent/SKILL.md new file mode 100644 index 0000000..d59150a --- /dev/null +++ b/.cursor/skills/refactor-agent/SKILL.md @@ -0,0 +1,91 @@ +--- +name: refactor-agent +description: Agent rule for refactoring existing code blocks or a feature by identifying language and applying only when refactor/improvement is requested +--- + +## Critical Rules + +- Always detect and state the programming language of the code block before refactoring +- Refactor when the user request includes terms like "refactor", "improve", "optimize", "clean up", or similar +- Always preserve the original intent and functionality unless the user requests a change +- If code contains duplication, refactor first, and test, before introducing a change. +- Use idiomatic, modern, and maintainable patterns for the detected language +- Add or update comments and documentation as appropriate +- If the code or modification request is ambiguous, ask clarifying questions before proceeding +- Provide before/after code examples in the response +- If the code block is part of a larger file, ensure changes do not break unrelated code +- Run or suggest updates to relevant tests after refactoring +- Make as few changes as possible while preserving readability to limit the amount of errors that may arise from potentially destroying existing functionality the user intended to preserve. +- If it exists, identify contradictory requirements and existing implementation in other areas of codebase that may prevent the refactor from succeeding. + + +name: refactor-block-agent +version: 1.0 +description: Refactor or improve an existing code block, identifying the language and applying best practices only when requested +filters: + - type: event + pattern: "refactor|improve|optimize|clean up" + - type: content + pattern: + - "[a-zA-Z0-9_]+\\s*\\([^)]*\\)\\s*\\{[\\s\\S]*?\\}" # Curly-brace function (JS, Java, C, etc.) + - "def\\s+[a-zA-Z0-9_]+\\s*\\([^)]*\\)\\s*:\\s*[\\s\\S]*?(?=^\\S|\\Z)" # Python function + - "class\\s+[a-zA-Z0-9_]+\\s*\\([^)]*\\)?\\s*:\\s*[\\s\\S]*?(?=^\\S|\\Z)" # Python class +actions: + - type: analyze + message: | + Identify the programming language of the code block. If ambiguous, ask the user for clarification. + - type: suggest + message: | + Refactor the code block using best practices for the detected language. Preserve original functionality unless otherwise specified. Add or update comments as needed. + - type: validate + message: | + Ensure the refactored code passes all relevant tests and does not introduce regressions. If tests are missing, suggest appropriate tests. +examples: + - input: | + // User: Refactor this function to be more readable + function sum(a, b) { return a+b } + output: | + // Detected language: JavaScript + // Before: + function sum(a, b) { return a+b } + // After: + /** + * Returns the sum of two numbers + * @param {number} a + * @param {number} b + * @returns {number} + */ + function sum(a, b) { + return a + b; + } + - input: | + # User: Please improve this Python code + def greet(name):return 'Hello, '+name + output: | + # Detected language: Python + # Before: + def greet(name):return 'Hello, '+name + # After: + def greet(name: str) -> str: + """Return a greeting for the given name.""" + return f"Hello, {name}" + - input: | + // User: Optimize this for performance + for (let i = 0; i < arr.length; i++) { result.push(arr[i] * 2) } + output: | + // Detected language: JavaScript + // Before: + for (let i = 0; i < arr.length; i++) { result.push(arr[i] * 2) } + // After: + result.push(...arr.map(x => x * 2)); +tests: + - input: "Refactor this function: function foo(x){return x*2}" + output: "Should detect JavaScript, add spacing, and suggest a JSDoc comment." + - input: "Improve: def add(x,y):return x+y" + output: "Should detect Python, add type hints, docstring, and proper formatting." + - input: "Optimize this: const nums = [1,2,3]; let out = []; for(let n of nums){out.push(n*n)}" + output: "Should detect JavaScript, suggest using map, and preserve output." +metadata: + priority: high + version: 1.0 + diff --git a/.cursor/skills/testing-pyramid/SKILL.md b/.cursor/skills/testing-pyramid/SKILL.md new file mode 100644 index 0000000..7be533c --- /dev/null +++ b/.cursor/skills/testing-pyramid/SKILL.md @@ -0,0 +1,326 @@ +--- +name: testing-pyramid +description: Test Distribution Analysis Command ๐Ÿงช +disable-model-invocation: true +--- + +# Test Distribution Analysis Command ๐Ÿงช + +This command guides the AI agent to analyze test distribution across unit, integration, and E2E tests, and provide recommendations for increasing test coverage and improving test distribution in line with business and technical strategy. + +## Critical Rules + +- Start by identifying the test framework and available coverage tools +- Analyze test distribution using framework-specific commands to list all test files +- Classify tests accurately as unit, integration, or E2E based on multiple indicators +- Target distribution: 70% unit tests, 20% integration tests, 10% E2E tests (this is a guideline at early stages of a project, not a strict requirement) +- Provide actionable recommendations when distribution deviates from ideal ratios +- Consider test file organization, naming conventions, and co-location with source code +- Evaluate test quality indicators (arrange-act-assert pattern, independence, clarity) +- Identify common violations and suggest improvements + +## Workflow Phases + +### 1. Framework Identification + +- Check `package.json` for test framework dependencies: + - **Jest**: `jest` or `@jest/core` in dependencies/devDependencies + - **Vitest**: `vitest` in dependencies/devDependencies + - **Playwright**: `@playwright/test` in dependencies/devDependencies + - **Cypress**: `cypress` in dependencies/devDependencies + - **Mocha**: `mocha` in dependencies/devDependencies +- Identify coverage tools and scripts in `package.json`: + - Look for `test:coverage`, `coverage`, or scripts with `--coverage` flags + - Note available coverage reporters and formats + +### 2. Test Discovery + +Use framework-specific commands to list all test files: + +- **Jest**: `npx jest --listTests` (lists all test files without running) +- **Vitest**: `npx vitest list` (lists all test files) +- **Playwright**: `npx playwright test --list` (lists all test specs) +- **Cypress**: Check `cypress.config.js` for `specPattern` or run `npx cypress run --dry-run` + +**Checkpoint:** Verify all test files are discovered and no test directories are missed. + +### 3. Test Classification + +Classify each test file as unit, integration, or E2E based on multiple indicators: + +#### Classification Criteria + +**File Path Indicators:** + +- `e2e/`, `tests/e2e/`, `__e2e__/` โ†’ E2E tests +- `integration/`, `tests/integration/`, `__integration__/` โ†’ Integration tests +- `unit/`, `tests/unit/`, `__tests__/` โ†’ Unit tests (if not in e2e/integration folders) + +**Content Keywords:** + +- **E2E indicators**: `playwright`, `cypress`, `page.goto`, `browser`, `user journey`, `visit`, `click`, `fill` +- **Integration indicators**: `database`, `api`, `service`, `repository`, `endpoint`, `http`, `fetch`, `axios`, `click`, `fill` +- **Unit indicators**: `mock`, `stub`, `spy`, `jest.fn()`, `vi.fn()`, isolated function testing + +**Test Framework Indicators:** + +- E2E frameworks have distinct APIs (page objects, browser commands, navigation) +- Integration tests often use test databases or mock servers +- Unit tests focus on isolated function/component behavior + +**Checkpoint:** Review classification accuracy by sampling test files from each category. + +### 4. Distribution Analysis + +Calculate test distribution: + +1. Count tests by category: + + - Total unit tests + - Total integration tests + - Total E2E tests + - Total tests overall + +2. Calculate percentages: + + - Unit percentage: `(unit tests / total tests) ร— 100` + - Integration percentage: `(integration tests / total tests) ร— 100` + - E2E percentage: `(e2e tests / total tests) ร— 100` + +3. Compare to ideal ratios: + - Target: 70% unit, 20% integration, 10% E2E + - Identify deviations and their magnitude + +**Checkpoint:** Present distribution findings and highlight significant deviations. + +### 5. Quality Assessment + +Evaluate test quality indicators: + +- **Structure**: Do tests follow Arrange-Act-Assert pattern? Do E2E tests follow page object model or Given-When-Then pattern? +- **Independence**: Can tests run in any order? +- **Clarity**: Are test names descriptive and scenario-focused? +- **Coverage**: Are critical paths and edge cases covered? +- **Maintainability**: Is test code clean and well-organized? Are tests coupled to the implementation details of the codebase? +- **Speed**: Are unit tests fast? Are slow tests appropriately categorized? + +### 6. Violation Detection + +Identify common violations: + +1. **Inverted pyramid** (more E2E than unit tests) +2. **Missing integration tests** between critical services +3. **Testing implementation details** in E2E tests +4. **Excessive mocking** in integration tests +5. **Testing multiple units** in a single unit test +6. **Missing Arrange-Act-Assert** structure +7. **Dependent tests** that must run in specific order +8. **Missing error case** coverage +9. **Brittle tests** that break with minor changes +10. **Insufficient test documentation** + +### 7. Recommendations + +Provide actionable recommendations: + +- **Distribution adjustments**: Suggest adding/removing tests in specific categories +- **Test organization**: Recommend file structure improvements +- **Test quality**: Suggest refactoring for better patterns +- **Coverage gaps**: Identify missing test scenarios +- **Framework optimization**: Suggest better use of framework features +- **Test maintenance**: Recommend cleanup and refactoring priorities + +## Test Type Standards + +### Unit Tests (Target: 70%) + +**Characteristics:** + +- Test individual functions, methods, or components in isolation +- Fast execution (< 100ms per test typically) +- Deterministic results +- Use mocks for external dependencies +- Focus on business logic and edge cases +- High code coverage + +**Best Practices:** + +- Co-locate with source code when possible +- Use clear, descriptive test names that describe the test scenario +- Follow Arrange-Act-Assert pattern +- Test one thing per test +- Use meaningful test data +- Mock external dependencies + +**Example Structure:** + +```typescript +describe("User Processing", () => { + it("should process valid user data correctly", () => { + // Arrange + const mockUser = createMockUser() + + // Act + const result = processUserData(mockUser) + + // Assert + expect(result).toEqual(expected) + }) +}) +``` + +### Integration Tests (Target: 20%) + +**Characteristics:** + +- Test interaction between multiple components or services +- Use real dependencies when possible +- Focus on API contracts and data flow +- Cover main success and error paths +- Slower than unit tests but faster than E2E + +**Best Practices:** + +- Test service interactions +- Verify data transformations +- Test error handling between layers +- Use test databases or mock servers +- Focus on critical integration points + +**Example Structure:** + +```typescript +describe("User Authentication Integration", () => { + it("should successfully authenticate valid user", async () => { + // Arrange + const user = await createTestUser() + + // Act + const result = await authService.authenticate(user.credentials) + + // Assert + expect(result.authenticated).toBe(true) + }) +}) +``` + +### End-to-End Tests (Target: 10%) + +**Characteristics:** + +- Test complete user journeys +- Run against production-like environment +- Focus on critical business flows +- Can be slow and more brittle +- Should be minimal but crucial + +**Best Practices:** + +- Focus on critical user journeys only +- Test happy paths and critical error scenarios +- Use page object models +- Keep tests independent +- Use appropriate wait strategies + +**Example Structure:** + +```typescript +describe("Critical User Journey", () => { + it("should allow user to complete checkout process", async () => { + // Arrange + await loginAsTestUser() + + // Act + await navigateToProducts() + await addItemToCart() + await proceedToCheckout() + await fillShippingDetails() + await completePayment() + + // Assert + await expect(page.locator("#order-confirmation")).toBeVisible() + }) +}) +``` + +## Analysis Report Template + +When presenting analysis results, include: + +```markdown +## Test Distribution Analysis + +### Framework Information + +- **Primary Framework**: [Framework name] +- **Coverage Tool**: [Tool name] +- **Total Test Files**: [Number] + +### Distribution Breakdown + +- **Unit Tests**: [Count] ([Percentage]%) - Target: 70% +- **Integration Tests**: [Count] ([Percentage]%) - Target: 20% +- **E2E Tests**: [Count] ([Percentage]%) - Target: 10% + +### Findings + +- [Finding 1] +- [Finding 2] +- [Finding 3] + +### Violations Detected + +1. [Violation description] +2. [Violation description] + +### Recommendations + +1. [Actionable recommendation] +2. [Actionable recommendation] +3. [Actionable recommendation] + +### Priority Actions + +- **High Priority**: [Actions] +- **Medium Priority**: [Actions] +- **Low Priority**: [Actions] +``` + +## Usage Examples + +### Example 1: Analyzing Jest Project + +```bash +# Discover tests +npx jest --listTests + +# Run analysis +# Classify tests by path and content +# Calculate distribution +# Provide recommendations +``` + +### Example 2: Analyzing Vitest + Playwright Project + +```bash +# Discover unit/integration tests +npx vitest list + +# Discover E2E tests +npx playwright test --list + +# Combine results and analyze +``` + +## Key Principles + +1. **Accuracy**: Classify tests correctly using multiple indicators +2. **Actionability**: Provide specific, implementable recommendations +3. **Balance**: Maintain proper pyramid distribution +4. **Quality**: Assess test quality, not just quantity +5. **Context**: Consider project size, complexity, and team capabilities +6. **Maintainability**: Recommend sustainable test practices +7. **Coverage**: Identify gaps in test coverage +8. **Performance**: Consider test execution time and CI/CD impact +9. **Independence**: Ensure tests can run in any order +10. **Clarity**: Make recommendations clear and easy to understand From 5aacc08dcf6dbe95ec26edbf67d60df1037a87b8 Mon Sep 17 00:00:00 2001 From: Jen Chan <6406037+usrrname@users.noreply.github.com> Date: Mon, 2 Mar 2026 20:08:10 -0500 Subject: [PATCH 3/5] chore: enhance release version bump rule description for clarity and usage guidance --- .cursor/rules/utils/release-version-bump-auto.mdc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.cursor/rules/utils/release-version-bump-auto.mdc b/.cursor/rules/utils/release-version-bump-auto.mdc index 1b760c6..ecbea44 100644 --- a/.cursor/rules/utils/release-version-bump-auto.mdc +++ b/.cursor/rules/utils/release-version-bump-auto.mdc @@ -1,5 +1,5 @@ --- -description: +description: Apply when the user is creating or preparing a release, version bump, tag, publish, or deploy. Validates semantic version bumps against change analysis (breaking/feat/fix), blocks inappropriate bumps, and guides major/minor/patch or custom version choice. Use for release workflows, package versioning, and publish/deploy preparation. globs: alwaysApply: false --- From 5f2ba8594157edbf0e95c4b5761c1b2c755db040 Mon Sep 17 00:00:00 2001 From: Jen Chan <6406037+usrrname@users.noreply.github.com> Date: Mon, 2 Mar 2026 20:27:59 -0500 Subject: [PATCH 4/5] chore: remove redundant introductory sentence from user story template --- .cursor/rules/templates/user-story.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.cursor/rules/templates/user-story.md b/.cursor/rules/templates/user-story.md index 5731ca2..41ca77e 100644 --- a/.cursor/rules/templates/user-story.md +++ b/.cursor/rules/templates/user-story.md @@ -2,7 +2,7 @@ Status: { Draft | Review | Blocked | ToDo | In Progress | Done | Dropped } -This is a user story template that you can use to document user stories for your software development projects. User stories follow the "As a [role], I want [an action or feature], so that [a reason or benefit]" format, and they help define the functionality and requirements of a feature or improvement. +User stories follow the "As a [role], I want [an action or feature], so that [a reason or benefit]" format, and they help define the functionality and requirements of a feature or improvement. ### Story Definition From 5941a7c26f6428e517fca9710e0f28ec4b0869c3 Mon Sep 17 00:00:00 2001 From: Jen Chan <6406037+usrrname@users.noreply.github.com> Date: Mon, 2 Mar 2026 20:28:04 -0500 Subject: [PATCH 5/5] chore: update package description and add 'skills' keyword to package.json --- package.json | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/package.json b/package.json index fca5a01..b2825d2 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "@usrrname/cursorrules", "version": "0.7.0", - "description": "A wicked npx-able lib of cursor rules with Otaku AI agents", + "description": "A npx-able library of cursor rules and skills with Otaku agents", "author": { "name": "jen chan" }, @@ -31,7 +31,8 @@ "keywords": [ "cursorrules", "cursor", - "agent" + "agent", + "skills" ], "license": "ISC", "bugs": {