paisanos-qa-core 0.1.0

package/bin/paisanos-qa.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/cli.js';

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { program } from 'commander';
+import prompts from 'prompts';
+import { installCoreRules, getInstalledMcpPackages, getPackageBinPath } from './install.js';
+const MODULE_BINS = {
+    'paisanos-figma-mcp-qa': 'mcp-figma-qa',
+    'paisanos-playwright-mcp': 'playwright-mcp-init',
+    'paisanos-maestro-mcp': 'maestro-mcp-init',
+};
+const MODULE_LABELS = {
+    'paisanos-figma-mcp-qa': 'Design (Figma MCP, design validation)',
+    'paisanos-playwright-mcp': 'Web (Playwright E2E)',
+    'paisanos-maestro-mcp': 'Mobile (Maestro)',
+};
+program
+    .name('paisanos-qa')
+    .description('Bootstrap QA rules and MCP config for Cursor. Choose what to install.')
+    .option('-C, --cwd <path>', 'Project root (default: current directory)')
+    .option('--core', 'Install only core rules (no prompt)')
+    .option('--design', 'Include Design/Figma MCP')
+    .option('--web', 'Include Web/Playwright MCP')
+    .option('--mobile', 'Include Mobile/Maestro MCP')
+    .option('--all', 'Include all: Design, Web, Mobile')
+    .action(async (opts) => {
+    const cwd = opts.cwd ? resolve(process.cwd(), opts.cwd) : process.cwd();
+    if (!existsSync(resolve(cwd, 'package.json'))) {
+        console.error('Error: No package.json found. Run from project root.');
+        process.exit(1);
+    }
+    const installed = getInstalledMcpPackages(cwd);
+    let selected = [];
+    if (opts.core) {
+        selected = [];
+    }
+    else if (opts.all) {
+        selected = installed;
+    }
+    else if (opts.design || opts.web || opts.mobile) {
+        if (opts.design && installed.includes('paisanos-figma-mcp-qa'))
+            selected.push('paisanos-figma-mcp-qa');
+        if (opts.web && installed.includes('paisanos-playwright-mcp'))
+            selected.push('paisanos-playwright-mcp');
+        if (opts.mobile && installed.includes('paisanos-maestro-mcp'))
+            selected.push('paisanos-maestro-mcp');
+    }
+    else {
+        const allPkgs = ['paisanos-figma-mcp-qa', 'paisanos-playwright-mcp', 'paisanos-maestro-mcp'];
+        const choices = allPkgs.map((pkg) => {
+            const isInstalled = installed.includes(pkg);
+            return {
+                title: MODULE_LABELS[pkg],
+                value: pkg,
+                description: isInstalled ? 'installed' : 'pnpm add -D ' + pkg,
+                disabled: !isInstalled,
+            };
+        });
+        const { modules } = await prompts({
+            type: 'multiselect',
+            name: 'modules',
+            message: 'What would you like to set up? (Core rules always installed)',
+            choices,
+            min: 0,
+            hint: 'Space to select, Enter to confirm. Install packages first for more options.',
+        });
+        if (modules === undefined) {
+            console.log('Cancelled.');
+            process.exit(0);
+        }
+        selected = modules.filter((m) => installed.includes(m));
+    }
+    console.log('\nInstalling QA Core rules...');
+    const coreInstalled = installCoreRules(cwd);
+    for (const p of coreInstalled) {
+        console.log(`  ${p}`);
+    }
+    for (const pkg of selected) {
+        const binName = MODULE_BINS[pkg];
+        if (!binName)
+            continue;
+        const binPath = getPackageBinPath(cwd, pkg, binName);
+        if (!binPath) {
+            console.warn(`\nWarning: Could not find bin ${binName} for ${pkg}`);
+            continue;
+        }
+        console.log(`\nRunning ${MODULE_LABELS[pkg]}...`);
+        await new Promise((resolvePromise, reject) => {
+            const child = spawn(process.execPath, [binPath], {
+                cwd,
+                stdio: 'inherit',
+            });
+            child.on('close', (code) => {
+                if (code === 0)
+                    resolvePromise();
+                else
+                    reject(new Error(`${binName} exited with ${code}`));
+            });
+        });
+    }
+    const notInstalled = selected.filter((p) => !installed.includes(p));
+    if (notInstalled.length > 0) {
+        console.log('\nTo install selected modules:');
+        for (const pkg of notInstalled) {
+            console.log(`  pnpm add -D ${pkg}`);
+        }
+    }
+    console.log('\nDone.');
+});
+program.parse();

package/dist/install.d.ts

@@ -0,0 +1,4 @@
+export declare function installCoreRules(projectRoot: string): string[];
+export declare function isPackageInstalled(projectRoot: string, packageName: string): boolean;
+export declare function getInstalledMcpPackages(projectRoot: string): string[];
+export declare function getPackageBinPath(projectRoot: string, packageName: string, binName: string): string | null;

package/dist/install.js

@@ -0,0 +1,64 @@
+import { copyFileSync, mkdirSync, existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = join(__dirname, '..');
+const RULES_SRC = join(PACKAGE_ROOT, 'rules');
+export function installCoreRules(projectRoot) {
+    const installed = [];
+    const cursorDir = join(projectRoot, '.cursor');
+    const rulesDir = join(cursorDir, 'rules', 'rules-kit');
+    const globalDir = join(rulesDir, 'global');
+    const sharedDir = join(rulesDir, 'shared');
+    mkdirSync(globalDir, { recursive: true });
+    mkdirSync(sharedDir, { recursive: true });
+    const globalRules = readdirSync(join(RULES_SRC, 'global')).filter((f) => f.endsWith('.mdc'));
+    for (const name of globalRules) {
+        const src = join(RULES_SRC, 'global', name);
+        const dest = join(globalDir, name);
+        copyFileSync(src, dest);
+        installed.push(`.cursor/rules/rules-kit/global/${name}`);
+    }
+    const sharedRules = readdirSync(join(RULES_SRC, 'shared')).filter((f) => f.endsWith('.mdc'));
+    for (const name of sharedRules) {
+        const src = join(RULES_SRC, 'shared', name);
+        const dest = join(sharedDir, name);
+        copyFileSync(src, dest);
+        installed.push(`.cursor/rules/rules-kit/shared/${name}`);
+    }
+    return installed;
+}
+const MCP_PACKAGES = ['paisanos-figma-mcp-qa', 'paisanos-playwright-mcp', 'paisanos-maestro-mcp'];
+export function isPackageInstalled(projectRoot, packageName) {
+    const paths = [
+        join(projectRoot, 'node_modules', packageName, 'package.json'),
+        join(projectRoot, 'node_modules', 'paisanos-qa', 'node_modules', packageName, 'package.json'),
+    ];
+    return paths.some((p) => existsSync(p));
+}
+export function getInstalledMcpPackages(projectRoot) {
+    const installed = [];
+    for (const pkg of MCP_PACKAGES) {
+        if (isPackageInstalled(projectRoot, pkg)) {
+            installed.push(pkg);
+        }
+    }
+    return installed;
+}
+export function getPackageBinPath(projectRoot, packageName, binName) {
+    const possibleRoots = [
+        join(projectRoot, 'node_modules', packageName),
+        join(projectRoot, 'node_modules', 'paisanos-qa', 'node_modules', packageName),
+    ];
+    for (const pkgRoot of possibleRoots) {
+        const pkgJsonPath = join(pkgRoot, 'package.json');
+        if (!existsSync(pkgJsonPath))
+            continue;
+        const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
+        const binPath = pkg.bin?.[binName];
+        if (binPath) {
+            return join(pkgRoot, binPath);
+        }
+    }
+    return null;
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "paisanos-qa-core",
+  "version": "0.1.0",
+  "description": "QA rules and criteria - cross-product denominator for Paisanos",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "paisanos-qa": "./bin/paisanos-qa.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "rules"
+  ],
+  "keywords": [
+    "qa",
+    "cursor",
+    "rules",
+    "testing"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^12",
+    "prompts": "^2.4.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "@types/prompts": "^2.4.9",
+    "typescript": "^5"
+  },
+  "scripts": {
+    "build": "tsc"
+  }
+}

package/rules/global/auto-test.mdc

@@ -0,0 +1,37 @@
+---
+projectPath: ./
+cursorPath: .
+description: Guidelines for automated testing
+globs: **/*
+alwaysApply: true
+---
+# Automated Testing
+
+Run the test suite after each change and fix issues until all tests pass.
+
+## Testing Workflow
+
+1. **Run Tests Frequently**: Execute tests after implementing each logical component.
+2. **Fix Issues Immediately**: Address test failures as soon as they appear.
+3. **Regression Testing**: Ensure existing functionality remains intact.
+4. **Test Coverage**: Add new tests when implementing new features.
+
+## Common Test Commands
+
+```bash
+# Framework-specific test commands
+npm test                 # Node.js/JavaScript
+php artisan test        # Laravel
+ng test                 # Angular
+mvn test                # Java/Maven
+pytest                  # Python
+go test ./...           # Go
+```
+
+## Test-Driven Development
+
+Consider adopting TDD principles:
+
+1. Write a failing test first
+2. Implement the minimal code to pass the test
+3. Refactor while keeping tests passing

package/rules/global/best-practices.mdc

@@ -0,0 +1,66 @@
+---
+projectPath: ./
+cursorPath: .
+description: Global best practices for any development project
+globs: **/*
+alwaysApply: true
+---
+# Global Best Practices
+
+This document defines best practices applicable to any development project, regardless of the technology stack used.
+
+## General Principles
+
+-   **Code Quality**: Maintain high quality standards throughout all code.
+-   **Documentation**: Update documentation when functionality changes.
+-   **Testing**: Implement tests for all new or modified code.
+-   **Single Responsibility**: Each component should have a single responsibility.
+-   **DRY (Don't Repeat Yourself)**: Avoid duplication of code and logic.
+
+## Code Development and Modification
+
+When creating or modifying any component of the system, follow these guidelines:
+
+### Development Process
+
+1. **Context Understanding**: Fully understand the problem before writing code.
+2. **Prior Design**: Design the solution before implementing it.
+3. **Incremental Development**: Implement in small, verifiable increments.
+4. **Code Review**: Review code before considering it complete.
+5. **Refactoring**: Improve existing code without changing its behavior.
+
+### Testing
+
+1. **Test First**: Consider writing tests before implementing code (TDD when possible).
+2. **Coverage**: Ensure new features have adequate tests.
+3. **Automation**: Run tests automatically before committing changes.
+4. **Verification**: Ensure all tests pass before finalizing.
+
+### Quality and Maintenance
+
+1. **Error Handling**: Implement appropriate error and exception handling.
+2. **Logging**: Add appropriate logs to facilitate debugging and monitoring.
+3. **Security**: Consider security implications in every change.
+4. **Performance**: Evaluate the performance impact of changes made.
+
+## Source Code Management
+
+1. **Version Control**: Properly use the version control system.
+2. **Small Commits**: Make small, focused commits with specific purposes.
+3. **Descriptive Messages**: Write clear and descriptive commit messages.
+4. **Working Branches**: Use branches for features, fixes, or tasks.
+5. **Pull Requests**: Request code review through pull requests.
+
+## Problem Solving
+
+1. **Root Cause Analysis**: Identify the fundamental cause of problems.
+2. **Durable Solutions**: Implement solutions that address the root problem.
+3. **Solution Documentation**: Document complex problems and their solutions.
+4. **Continuous Learning**: Learn from mistakes and continuously improve.
+
+## Teamwork
+
+1. **Clear Communication**: Communicate changes and design decisions to the team.
+2. **Collaboration**: Collaborate with other team members on complex problems.
+3. **Knowledge Sharing**: Document and share knowledge with the team.
+4. **Code Reviews**: Participate in code reviews constructively.

package/rules/global/code-standards.mdc

@@ -0,0 +1,17 @@
+---
+projectPath: ./
+cursorPath: .
+description: General code formatting standards
+globs: **/*
+alwaysApply: true
+---
+# Global Code Standards
+
+-   Follow consistent code formatting across the entire project.
+-   Use meaningful variable and function names that explain their purpose.
+-   Keep functions small and focused on a single responsibility.
+-   Add meaningful comments for complex logic, but avoid obvious comments.
+-   Remove debug code, commented-out code and console logs before committing.
+-   Use proper indentation (spaces or tabs) consistently throughout the project.
+-   Follow the language/framework's standard style guide.
+-   Avoid deep nesting of conditionals and loops.

package/rules/global/file-guard.mdc

@@ -0,0 +1,36 @@
+---
+projectPath: ./
+cursorPath: .
+description: File operation guidelines to prevent content loss
+globs: **/*
+alwaysApply: true
+---
+# File Management Guard
+
+Before creating a file, check if it already exists. If it exists and there is no explicit instruction to overwrite, merge content instead of replacing.
+
+## Best Practices for File Operations
+
+1. **Check Existence**: Always verify if a file exists before creating it.
+2. **Preserve Content**: When a file exists, preserve important elements:
+
+    - Comments and documentation
+    - Existing imports
+    - License headers
+    - Configuration settings
+
+3. **Merge Strategies**:
+
+    - For code files: Add new functions, classes, or methods without removing existing ones
+    - For configuration files: Add new settings while preserving existing ones
+    - For documentation: Append new information or integrate it with existing content
+
+4. **Communicate Changes**: When modifying existing files, document the nature of the changes.
+
+## When to Overwrite
+
+Only overwrite files when:
+
+1. Explicitly instructed to do so
+2. The file is known to be a generated file that should be recreated
+3. The entire purpose of the file is being changed

package/rules/global/git-commit-guidelines.mdc

@@ -0,0 +1,227 @@
+---
+projectPath: ./
+cursorPath: .
+alwaysApply: true
+globs: **/*
+---
+# Git Commit Guidelines - CRITICAL VERSION CONTROL
+
+## ⚠️ CRITICAL WARNING - BREAKING CHANGES
+
+**NEVER use `BREAKING CHANGE:` in commit messages unless it's a REAL breaking change that requires users to modify their code!**
+
+This project uses semantic-release which automatically triggers version bumps:
+
+| Type               | Emoji | Example                                 | Version Impact | Risk Level       |
+| ------------------ | ----- | --------------------------------------- | -------------- | ---------------- |
+| `fix:`             | 🐛    | `fix(payment): 🐛 handle timeout error` | PATCH          | ✅ Safe          |
+| `feat:`            | ✨    | `feat(api): ✨ add user authentication` | MINOR          | ✅ Safe          |
+| `docs:`            | 📝    | `docs(readme): 📝 clarify setup`        | No version     | ✅ Safe          |
+| `refactor:`        | ♻️    | `refactor(core): ♻️ extract helper`     | No version     | ✅ Safe          |
+| `test:`            | ✅    | `test(utils): ✅ edge cases for parser` | No version     | ✅ Safe          |
+| `chore:`           | 🔧    | `chore(ci): 🔧 bump node version`       | No version     | ✅ Safe          |
+| `BREAKING CHANGE:` | 🚨    | Any commit with this footer             | MAJOR          | 🚨 **DANGEROUS** |
+
+## ⚠️ Breaking Changes (MAJOR version) - USE WITH EXTREME CAUTION
+
+**WARNING**: Only use `BREAKING CHANGE:` when users MUST modify their code to continue using the project.
+
+### 🚨 Real Breaking Changes (Only when absolutely necessary):
+
+```bash
+feat: ✨ redesign authentication system
+
+Complete overhaul of auth flow and API structure
+
+BREAKING CHANGE: Auth token format changed, all clients must update their integration
+```
+
+### ❌ WRONG - These are NOT breaking changes:
+
+```bash
+# ❌ Adding new features is NOT breaking
+feat: ✨ add new dashboard feature
+
+BREAKING CHANGE: Added new dashboard  # WRONG!
+
+# ❌ Improving existing features is NOT breaking
+feat: ✨ improve performance
+
+BREAKING CHANGE: Better caching system  # WRONG!
+
+# ❌ Internal refactoring is NOT breaking
+refactor: ♻️ reorganize code structure
+
+BREAKING CHANGE: Changed internal structure  # WRONG!
+```
+
+### ❌ Dangerous Patterns to AVOID:
+
+```bash
+# DON'T use exclamation mark in type
+feat!: ✨ breaking change
+
+# DON'T add BREAKING CHANGE for non-breaking changes
+feat: 🎉 add cool new feature
+
+BREAKING CHANGE: Users now have more options  # NOT BREAKING!
+```
+
+## **Semantic Versioning Impact**
+
+| Version Type       | When to Use                       | Result                    | Example                          |
+| ------------------ | --------------------------------- | ------------------------- | -------------------------------- |
+| **PATCH** (v1.0.1) | Bug fixes, backward-compatible    | `fix:` type               | `fix: 🐛 handle null values`     |
+| **MINOR** (v1.1.0) | New features, backward-compatible | `feat:` type              | `feat: ✨ add user dashboard`    |
+| **MAJOR** (v2.0.0) | 🚨 Breaking changes only          | `BREAKING CHANGE:` footer | Only when users must change code |
+
+### 🎯 Safe Approach (Recommended):
+
+-   **Default to `fix:`** when in doubt
+-   **Use `feat:`** for new functionality
+-   **NEVER use `BREAKING CHANGE:`** unless absolutely certain
+
+## Author Identity Rules
+
+To clearly differentiate the origin of each commit, **ALWAYS** use `--author` according to context:
+
+### Human Developer Commits
+
+Commits made directly by human developers:
+
+```bash
+# Use developer's normal identity (without --author)
+git commit -m "feat(auth): ✨ implement OAuth login"
+```
+
+### AI Assistant Commits
+
+Commits made by AI assistants (Cursor, Claude, ChatGPT, etc.):
+
+```bash
+# MANDATORY use --author with AI identification
+git commit --author="Claude AI <claude.ai@assistant.local>" -m "feat(api): ✨ add user validation"
+git commit --author="Cursor AI <cursor.ai@assistant.local>" -m "fix(auth): 🐛 handle token expiry"
+```
+
+### Available AI Author Formats:
+
+-   `Agent AI <agent.ai@assistant.local>` - For general AI assistants
+-   `Claude AI <claude.ai@assistant.local>` - For Claude/Sonnet
+-   `Cursor AI <cursor.ai@assistant.local>` - For Cursor IDE AI
+-   `ChatGPT AI <chatgpt.ai@assistant.local>` - For ChatGPT
+-   `Copilot AI <copilot.ai@assistant.local>` - For GitHub Copilot
+
+### 🤖 AI Assistant Commit Guidelines:
+
+**CRITICAL RULES for AI Assistants:**
+
+1. **ALWAYS use `--author="Agent AI <agent.ai@assistant.local>"`**
+2. **Prefer `fix:` over `feat:` when uncertain**
+3. **NEVER use `BREAKING CHANGE:` without explicit user confirmation**
+4. **Keep commit messages concise and descriptive**
+5. **When in doubt, ask the user before committing**
+
+```bash
+# ✅ CORRECT AI commit examples:
+git commit --author="Agent AI <agent.ai@assistant.local>" -m "fix: 🐛 correct validation logic"
+git commit --author="Agent AI <agent.ai@assistant.local>" -m "feat: ✨ add new component"
+git commit --author="Agent AI <agent.ai@assistant.local>" -m "docs: 📝 update README"
+
+# ❌ NEVER do this without user approval:
+git commit --author="Agent AI <agent.ai@assistant.local>" -m "feat: ✨ redesign API
+
+BREAKING CHANGE: Changed endpoint structure"
+```
+
+### Automated System Commits
+
+Automatic commits (semantic-release, bots, CI/CD):
+
+```bash
+# These systems already configure their own author automatically
+# No manual action required
+```
+
+### Important Notes
+
+-   **Avatar Display**: Avatar is determined by email. Emails not associated with GitHub accounts will show default avatar
+-   **Consistency**: Maintain consistency in AI email format: `<ai-name>.ai@assistant.local`
+-   **Transparency**: This practice improves transparency and traceability of collaborative development
+
+## 📚 Project History & Lessons Learned
+
+### ⚠️ Previous Versioning Issues:
+
+This project has experienced accidental major version bumps due to incorrect `BREAKING CHANGE:` usage:
+
+-   **v3.0.0**: Accidentally triggered by incorrect `BREAKING CHANGE:` in commit
+-   **v3.0.1**: Another accidental major bump
+-   **Current version**: v3.3.1+ (continuing from accidental major versions)
+
+### 🎯 Lessons Learned:
+
+1. **`BREAKING CHANGE:` is extremely powerful** - it immediately triggers major version
+2. **Most changes are NOT breaking** - adding features, improving performance, refactoring
+3. **When in doubt, use `fix:` or `feat:`** - these are safer options
+4. **Breaking changes require user code modifications** - not just "big changes"
+
+### 🔒 Current Policy:
+
+-   **Default to `fix:`** for improvements and corrections
+-   **Use `feat:`** only for clear new functionality
+-   **Avoid `BREAKING CHANGE:`** unless users must modify their code to continue using the project
+
+## BREAKING CHANGE Best Practices (Use Sparingly)
+
+**Only when users MUST change their code:**
+
+1. **Keep title short**: Under 72 characters
+2. **Use blank line**: Separate title from BREAKING CHANGE
+3. **Be specific**: Explain what changed and impact
+4. **Add context**: Include migration notes if needed
+5. **Get approval**: Always get explicit user approval before using
+
+### Examples:
+
+```bash
+# Good for major feature
+feat: 🎉 redesign user interface
+
+New component library and design system
+
+BREAKING CHANGE: Button component props changed, see migration guide
+
+# Good for simple breaking change
+feat: ✨ update API endpoints
+
+BREAKING CHANGE: All endpoints now require v2 prefix
+```
+
+## Release Guidelines
+
+### When NOT to Create Releases
+
+-   **Default Behavior**: Do NOT create releases unless explicitly requested
+-   **Check Existing Automation**: Before attempting any release, verify if automation already exists:
+    -   GitHub Actions workflows (`.github/workflows/`)
+    -   GitLab CI/CD pipelines (`.gitlab-ci.yml`)
+    -   `semantic-release` in `package.json` dependencies
+    -   Other automated release tools
+
+### When to Create Releases
+
+Only create releases when:
+
+1. **Explicitly requested** by the user
+2. **No existing automation** is found
+3. **Manual release process** is confirmed to be needed
+
+### Release Verification Commands
+
+```bash
+# Check for existing automation
+ls .github/workflows/
+cat package.json | grep semantic-release
+cat .gitlab-ci.yml 2>/dev/null || echo "No GitLab CI found"
+```

package/rules/global/log-process.mdc

@@ -0,0 +1,111 @@
+---
+projectPath: ./
+cursorPath: .
+description: Guidelines for process logging
+globs: **/*
+alwaysApply: true
+---
+# Task Process Logging
+
+For long or complex tasks, maintain a detailed log in `docs/logs-process/YYYY-MM-DD_<task-name>.md`. This practice improves task tracking, knowledge sharing, and project documentation.
+
+## Log Structure
+
+Each process log should include:
+
+1. **Title**: Clear description of the task with date
+2. **Objectives**: What you are trying to accomplish
+3. **Prerequisites**: Requirements and dependencies
+4. **Task Breakdown**: Checklist of subtasks
+5. **Process Notes**: Observations made during implementation
+6. **Problems & Solutions**: Issues encountered and how they were resolved
+7. **Decisions**: Important decisions and their rationale
+8. **Result**: Final outcome and verification steps
+9. **Future Considerations**: Notes for future improvements
+
+## Log Template
+
+```markdown
+# Task: [Task Name] - YYYY-MM-DD
+
+## Objectives
+
+-   Primary objective
+-   Secondary objectives
+
+## Prerequisites
+
+-   Required tools
+-   Required permissions/access
+-   Related documentation
+
+## Task Breakdown
+
+-   [ ] Step 1: [Description]
+-   [ ] Step 2: [Description]
+-   [ ] Step 3: [Description]
+
+## Process Notes
+
+-   [Timestamp] Observation or implementation detail
+-   [Timestamp] Another observation
+
+## Problems & Solutions
+
+### Problem 1: [Problem description]
+
+-   Attempted solution 1: [Result]
+-   Attempted solution 2: [Result]
+-   Final solution: [Implementation details]
+
+### Problem 2: [Problem description]
+
+-   Solution: [Implementation details]
+
+## Decisions
+
+-   Decision 1: [What was decided]
+    Rationale: [Why this choice was made]
+    Alternatives considered: [What else was considered]
+
+## Result
+
+-   Success/Partial success/Failure
+-   Verification steps performed
+-   Evidence of completion
+
+## Future Considerations
+
+-   Potential improvements
+-   Related tasks that should be considered later
+```
+
+## Best Practices
+
+1. **Real-time Updates**: Update the log while working on the task, not after completion
+2. **Detailed Problems**: Document all encountered problems, even if solved quickly
+3. **Command Logging**: Record exact commands used for future reference
+4. **Versioning**: Include version numbers of tools/libraries used
+5. **Screenshots**: Include screenshots of important states or errors
+6. **Time Tracking**: Note timestamps for major steps to help estimate similar tasks
+
+## When to Create Process Logs
+
+Create logs for:
+
+-   System architecture changes
+-   Complex bug fixes
+-   Major feature implementations
+-   Configuration changes
+-   Data migrations
+-   Performance optimizations
+-   Security-related changes
+-   Anything that might need to be referred to later
+
+## Integration with Workflow
+
+1. Create log file at task initiation
+2. Update throughout implementation
+3. Review and finalize before marking task complete
+4. Reference in commit messages and pull requests
+5. Share with team members for knowledge transfer

package/rules/global/quality-assurance.mdc

@@ -0,0 +1,102 @@
+---
+projectPath: ./
+cursorPath: .
+description: Quality control practices for all projects
+globs: **/*
+alwaysApply: true
+---
+# Project Quality Assurance
+
+This document unifies quality control practices applicable to any project, regardless of the technology stack used.
+
+## Quality Principles
+
+1. **Continuous Verification**: Constantly verify code quality throughout development.
+2. **Error Prevention**: Preventing errors is better than correcting them later.
+3. **Continuous Improvement**: Continually seek ways to improve processes and code.
+4. **Documentation**: Maintain accurate documentation of processes and decisions.
+
+## Automated Testing
+
+-   **Regular Execution**: Run automated test suites after each significant change.
+-   **Problem Resolution**: Don't consider a change complete until all tests pass.
+-   **Coverage**: Add new tests for new or modified code.
+-   **Regression**: Ensure changes don't break existing functionality.
+
+```bash
+# Run tests and verify all pass
+npm run test
+
+# Framework-specific test commands
+php artisan test        # Laravel
+ng test                 # Angular
+pytest                  # Python
+go test ./...           # Go
+```
+
+## Process Logging
+
+For complex or long-running tasks, maintain a process log:
+
+1. **Checklist Creation**: Create a log file in `docs/logs-process/`.
+2. **Naming Convention**: Use the format `YYYY-MM-DD_task-description.md`.
+3. **Content Structure**:
+    - Objectives and scope of the task
+    - List of subtasks with checkboxes
+    - Problems encountered and solutions applied
+    - Decisions made and their justification
+
+Example:
+
+```markdown
+# Authentication Implementation - 2024-08-15
+
+## Objectives
+
+-   Implement email/password login
+-   Add OAuth authentication
+-   Implement password recovery
+
+## Tasks
+
+-   [x] Create user models and migrations
+-   [x] Implement authentication controller
+-   [ ] Configure OAuth providers
+-   [ ] Implement password recovery emails
+
+## Problems and Solutions
+
+-   Problem: Conflict with session storage
+    Solution: Use database-based storage
+```
+
+## File Management
+
+When creating or modifying files in the project:
+
+1. **Existence Verification**: Check if the file already exists before creating it.
+2. **Content Preservation**:
+    - If it exists and there's no explicit instruction to overwrite, merge changes.
+    - Preserve important aspects of the existing file (comments, structure).
+3. **Duplication Prevention**: Avoid creating duplicate files or files with similar functionality.
+4. **Appropriate Location**: Ensure files are created in the correct location according to the project structure.
+
+## Code Review
+
+1. **Self-Review**: Review your own code before considering it complete.
+2. **Verification Checklist**:
+    - Does the code follow project conventions?
+    - Is it adequately tested?
+    - Is documentation updated?
+    - Have edge cases been considered?
+    - Is performance acceptable?
+
+## Task Completion
+
+Consider a task complete only when:
+
+1. All automated tests pass.
+2. It is properly documented.
+3. The process log is updated (if applicable).
+4. A code review has been performed.
+5. Changes are ready to be deployed to production.

package/rules/shared/user-credential-management.mdc

@@ -0,0 +1,391 @@
+---
+projectPath: ./
+cursorPath: .
+description: User credential and test data management rules
+globs: users/**/*,config/**/*,flows/**/*
+alwaysApply: true
+---
+# User Credential Management
+
+Best practices for managing test users, credentials, and sensitive test data.
+
+## Critical Security Rules
+
+### 1. **NEVER commit real credentials**
+```yaml
+# ❌ WRONG: Real credentials in flow file
+- inputText: "real.user@email.com"
+- inputText: "RealPassword123!"
+
+# ✅ CORRECT: Use variables
+- inputText: "${EMAIL}"
+- inputText: "${PASSWORD}"
+```
+
+### 2. **Use environment variables**
+```yaml
+# config/users.yaml or flows/users/*.yml
+email: "${EMAIL}"  # From environment
+password: "${PASSWORD}"  # From environment
+```
+
+### 3. **Keep credentials in gitignored files**
+```gitignore
+# .gitignore should include:
+.env
+.env.local
+.env.*.local
+config/credentials.yaml
+config/users.yaml
+users/*-credentials.yml
+```
+
+## User Management System
+
+### User File Structure
+
+```yaml
+# users/socioActivoAbono.yml
+email: "socio.activo.abono@test.bocajuniors.com"
+password: "Test123!Pass"
+attributes:
+  tipoSocio: "ACTIVO"
+  modalidadPago: "ABONO"
+  tieneDeuda: false
+  tieneGrupoFamiliar: false
+  credentials:
+    dni: "12345678"
+    numeroSocio: "123456"
+```
+
+### User Types in This Project
+
+#### 1. Socio Activo (Active Member)
+```yaml
+# users/socioActivoAbono.yml
+tipoSocio: "ACTIVO"
+modalidadPago: "ABONO"
+tieneAbono: true
+```
+
+#### 2. Socio Vitalicio (VIP Lifetime Member)
+```yaml
+# users/socioVitaAbono.yml
+tipoSocio: "VITALICIO"
+modalidadPago: "ABONO"
+tieneAbono: true
+prioridad: "ALTA"
+```
+
+#### 3. Socio con Deuda (Member with Debt)
+```yaml
+# users/socioConDeudaPaypal.yml
+tipoSocio: "ACTIVO"
+tieneDeuda: true
+metodoPago: "PAYPAL"
+montoDeuda: 15000
+```
+
+#### 4. Socio Adherente (Associate Member)
+```yaml
+# users/socioAdherenteNo.yml
+tipoSocio: "ADHERENTE"
+tieneAbono: false
+accesoReservas: "WEB_ONLY"
+```
+
+#### 5. Socio con Grupo Familiar (Member with Family Group)
+```yaml
+# users/socioConGrupoFamiliar.yml
+tipoSocio: "ACTIVO"
+tieneGrupoFamiliar: true
+familiares:
+  - nombre: "Familiar 1"
+    tipoSocio: "ADHERENTE"
+  - nombre: "Familiar 2"
+    tipoSocio: "ADHERENTE"
+```
+
+## User Selection Script
+
+### Using get-user.js
+
+```javascript
+// scripts/get-user.js
+const fs = require('fs');
+const yaml = require('js-yaml');
+
+function getUser(userType) {
+  const userFile = `./users/${userType}.yml`;
+  if (!fs.existsSync(userFile)) {
+    throw new Error(`User file not found: ${userFile}`);
+  }
+  
+  const userConfig = yaml.load(fs.readFileSync(userFile, 'utf8'));
+  return {
+    email: userConfig.email,
+    password: userConfig.password,
+    attributes: userConfig.attributes
+  };
+}
+
+module.exports = getUser;
+```
+
+### Usage in Tests
+
+```bash
+# Get user credentials for testing
+node scripts/get-user.js socioActivoAbono
+# Output: email and password for test execution
+
+# Use in Maestro test
+maestro test \
+  --env EMAIL=$(node scripts/get-user.js socioActivoAbono --field email) \
+  --env PASSWORD=$(node scripts/get-user.js socioActivoAbono --field password) \
+  flows/test.yaml
+```
+
+## User Sync System
+
+### Syncing Users from External Source
+
+```javascript
+// scripts/sync-users.js
+// Syncs user configurations from external source (API, database, etc.)
+
+const syncUsers = async () => {
+  // Fetch users from external source
+  const users = await fetchUsersFromAPI();
+  
+  // Save to local user files
+  for (const user of users) {
+    const userFile = `./users/${user.type}.yml`;
+    const userData = {
+      email: user.email,
+      password: user.password, // Should be test credentials only
+      attributes: user.attributes
+    };
+    
+    fs.writeFileSync(userFile, yaml.dump(userData));
+  }
+};
+```
+
+### Best Practices for User Sync
+
+1. **Only sync test credentials**: Never sync production credentials
+2. **Validate user data**: Ensure required fields are present
+3. **Log sync operations**: Track when users were last synced
+4. **Use staging environment**: Sync from staging/test environment only
+
+## Credential Rotation
+
+### When to Rotate Credentials
+
+1. **Regular Schedule**: Every 90 days minimum
+2. **After Team Changes**: When team members leave
+3. **After Security Incidents**: Immediately if credentials compromised
+4. **CI/CD Updates**: When updating CI/CD pipelines
+
+### Rotation Process
+
+```bash
+# 1. Generate new credentials in test system
+# 2. Update user files
+# 3. Update CI/CD secrets
+# 4. Notify team
+# 5. Verify all tests still pass
+# 6. Invalidate old credentials
+```
+
+## Environment-Specific Configuration
+
+### Development Environment
+```yaml
+# config/users.yaml (for dev)
+defaultUser:
+  email: "dev.tester@test.local"
+  password: "DevTest123!"
+```
+
+### CI/CD Environment
+```yaml
+# Use environment variables in CI
+# Set in GitHub Actions secrets / GitLab CI variables
+EMAIL: ${{ secrets.TEST_USER_EMAIL }}
+PASSWORD: ${{ secrets.TEST_USER_PASSWORD }}
+```
+
+### Staging Environment
+```yaml
+# config/users-staging.yaml
+defaultUser:
+  email: "staging.tester@staging.bocajuniors.com"
+  password: "${STAGING_PASSWORD}"  # From environment
+```
+
+## Test Data Management
+
+### Sensitive Test Data
+
+```yaml
+# ❌ WRONG: Hardcoded payment data
+cardNumber: "4111111111111111"
+cvv: "123"
+expiry: "12/25"
+
+# ✅ CORRECT: Variables or test data generators
+cardNumber: "${TEST_CARD_NUMBER}"
+cvv: "${TEST_CVV}"
+expiry: "${TEST_EXPIRY}"
+```
+
+### Test Data Generators
+
+```javascript
+// utils/test-data-generator.js
+const generateTestCard = () => ({
+  number: "4111111111111111", // Test card number
+  cvv: "123",
+  expiry: "12/25",
+  name: "TEST CARDHOLDER"
+});
+
+const generateTestUser = (type) => ({
+  email: `test.${type}.${Date.now()}@test.local`,
+  password: `Test${Math.random().toString(36).slice(-8)}!`,
+  type: type
+});
+```
+
+## User Access Control
+
+### User Permission Matrix
+
+| User Type | Match Reservations | Payment Methods | Family Group | Priority Access |
+|-----------|-------------------|-----------------|--------------|-----------------|
+| Activo    | ✅ Web + Internal | ✅ All          | ✅ Yes       | ⭐ Normal      |
+| Vitalicio | ✅ All + Priority | ✅ All          | ✅ Yes       | ⭐⭐⭐ High   |
+| Adherente | ✅ Web Only       | ✅ Limited      | ❌ No        | ⭐ Low         |
+| Con Deuda | ❌ Blocked        | ✅ Payment Only | ✅ Yes       | ⭐ Low         |
+
+### Testing Access Control
+
+```yaml
+# Test that user can access feature
+- runFlow:
+    file: flows/common/login.yaml
+    env:
+      USER_TYPE: "socioVitalicio"
+- tapOn: "Reservas VIP"
+- assertVisible: "Plateas disponibles"
+
+# Test that user CANNOT access feature
+- runFlow:
+    file: flows/common/login.yaml
+    env:
+      USER_TYPE: "socioAdherente"
+- assertNotVisible: "Reservas VIP"
+- assertVisible: "Acceso no autorizado"
+```
+
+## Credential Storage Best Practices
+
+### 1. **Use config/users.yaml as template only**
+```yaml
+# config/users.yaml (committed to repo)
+defaultUser:
+  email: "${EMAIL}"  # Placeholder
+  password: "${PASSWORD}"  # Placeholder
+  
+# config/users.local.yaml (gitignored, actual credentials)
+defaultUser:
+  email: "actual.email@test.com"
+  password: "ActualPassword123!"
+```
+
+### 2. **Use .env files for local development**
+```bash
+# .env.local (gitignored)
+TEST_USER_EMAIL=test.user@example.com
+TEST_USER_PASSWORD=TestPassword123!
+ADMIN_USER_EMAIL=admin@example.com
+ADMIN_USER_PASSWORD=AdminPass123!
+```
+
+### 3. **Use CI/CD secrets for pipelines**
+```yaml
+# .github/workflows/test.yml
+- name: Run Tests
+  env:
+    EMAIL: ${{ secrets.TEST_USER_EMAIL }}
+    PASSWORD: ${{ secrets.TEST_USER_PASSWORD }}
+  run: maestro test flows/
+```
+
+## Audit and Compliance
+
+### Logging User Usage
+```javascript
+// Log which user credentials are used in tests
+const logUserAccess = (userType, testName) => {
+  console.log(`[${new Date().toISOString()}] Test: ${testName}, User: ${userType}`);
+  // Can be extended to write to audit log
+};
+```
+
+### Credential Compliance Checklist
+- [ ] No production credentials in test environment
+- [ ] All credentials are in gitignored files
+- [ ] CI/CD uses secret management
+- [ ] Credentials rotated regularly
+- [ ] Access logs maintained
+- [ ] Team has minimal necessary access
+- [ ] Credentials are encrypted at rest
+
+## Emergency Procedures
+
+### If Credentials Are Compromised
+
+1. **Immediate Actions**:
+   ```bash
+   # 1. Rotate all affected credentials
+   # 2. Review access logs
+   # 3. Notify security team
+   # 4. Update all systems with new credentials
+   ```
+
+2. **Investigation**:
+   - Check git history for accidental commits
+   - Review CI/CD logs
+   - Check for unauthorized access
+   - Document incident
+
+3. **Prevention**:
+   - Enable git hooks to prevent credential commits
+   - Use secret scanning tools
+   - Educate team on best practices
+
+## Summary Checklist
+
+Before adding new test user:
+- [ ] User credentials are test-only (not production)
+- [ ] User file follows naming convention
+- [ ] User attributes are documented
+- [ ] Credentials use environment variables where possible
+- [ ] User file is added to .gitignore if contains real credentials
+
+Before committing code:
+- [ ] No hardcoded credentials in code
+- [ ] No real emails or passwords visible
+- [ ] Test data uses variables
+- [ ] Sensitive files are gitignored
+- [ ] CI/CD secrets are configured
+
+Regular maintenance:
+- [ ] Review user access quarterly
+- [ ] Rotate credentials regularly
+- [ ] Remove unused test users
+- [ ] Audit credential usage
+- [ ] Update documentation