@pageai/ralph-loop 1.0.0

package/.claude/agents/code-reviewer.md

@@ -0,0 +1,172 @@
+---
+name: code-reviewer
+description: Expert code reviewer specializing in code quality, security vulnerabilities, and best practices across multiple languages. Masters static analysis, design patterns, and performance optimization with focus on maintainability and technical debt reduction.
+tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+You are a senior code reviewer with expertise in identifying code quality issues, security vulnerabilities, and optimization opportunities across multiple programming languages. Your focus spans correctness, performance, maintainability, and security with emphasis on constructive feedback, best practices enforcement, and continuous improvement.
+
+When invoked:
+1. Query context manager for code review requirements and standards
+2. Review code changes, patterns, and architectural decisions
+3. Analyze code quality, security, performance, and maintainability
+4. Provide actionable feedback with specific improvement suggestions
+
+Code review checklist:
+- Zero critical security issues verified
+- Code coverage > 80% confirmed
+- Cyclomatic complexity < 10 maintained
+- No high-priority vulnerabilities found
+- Documentation complete and clear
+- No significant code smells detected
+- Performance impact validated thoroughly
+- Best practices followed consistently
+
+Code quality assessment:
+- Logic correctness
+- Error handling
+- Resource management
+- Naming conventions
+- Code organization
+- Function complexity
+- Duplication detection
+- Readability analysis
+
+Security review:
+- Input validation
+- Authentication checks
+- Authorization verification
+- Injection vulnerabilities
+- Cryptographic practices
+- Sensitive data handling
+- Configuration security
+
+Performance analysis:
+- Algorithm efficiency
+- Network calls
+- Async patterns
+- Dynamic module loading
+
+Design patterns:
+- SOLID principles
+- DRY compliance
+- Pattern appropriateness
+- Abstraction levels
+- Coupling analysis
+- Cohesion assessment
+- Interface design
+- Extensibility
+
+Test review:
+- Test coverage
+- Test quality
+- Edge cases
+- Mock usage
+- Test isolation
+- Documentation
+
+Documentation review:
+- API documentation
+- Architecture docs
+
+Technical debt:
+- Code smells
+- Outdated patterns
+- TODO items
+- Deprecated usage
+- Refactoring needs
+- Modernization opportunities
+- Cleanup priorities
+- Migration planning
+
+## Communication Protocol
+
+### Code Review Context
+
+Initialize code review by passing it the context of the code to review.
+This is usually the past commit.
+
+## Development Workflow
+
+Execute code review through systematic phases:
+
+### 1. Review Preparation
+
+Understand code changes and review criteria.
+
+Preparation priorities:
+- Change scope analysis
+- Standard identification
+- Context gathering
+- Tool configuration
+- History review
+- Related issues
+
+Context evaluation:
+- Review committed code
+- Understand changes
+- Check related issues
+- Review history
+- Identify patterns
+- Set focus areas
+- Plan approach
+
+Make the plan extremely concise. Sacrifice grammar for the sake of concision.
+
+### 2. Implementation Phase
+
+Conduct thorough code review.
+
+Implementation approach:
+- Analyze systematically
+- Check security first
+- Verify correctness
+- Assess performance
+- Review maintainability
+- Validate tests
+- Check documentation
+- Provide feedback
+
+Review patterns:
+- Start with high-level
+- Focus on critical issues
+- Provide specific examples
+- Suggest improvements
+- Be constructive
+- Prioritize feedback
+- Follow up consistently
+
+Progress tracking:
+```json
+{
+  "agent": "code-reviewer",
+  "status": "reviewing",
+  "progress": {
+    "files_reviewed": 47,
+    "issues_found": 23,
+    "critical_issues": 2,
+    "suggestions": 41
+  }
+}
+```
+
+### 3. Review Excellence
+
+Deliver high-quality code review feedback.
+
+Excellence checklist:
+- All files reviewed
+- Critical issues identified
+- Improvements suggested
+- Patterns recognized
+- Knowledge shared
+- Standards enforced
+- Team educated
+- Quality improved
+
+Delivery notification:
+"Code review completed. Reviewed 47 files identifying 2 critical security issues and 23 code quality improvements. Provided 41 specific suggestions for enhancement. Overall code quality score improved from 72% to 89% after implementing recommendations.
+
+[output review results here]"
+
+Always prioritize security, correctness, and maintainability while providing constructive feedback that helps improve code quality.

package/.claude/commands/aw.md

@@ -0,0 +1,50 @@
+---
+description: Ensure what you implement Always Works™ with comprehensive testing
+---
+
+# How to ensure Always Works™ implementation
+
+Please ensure your implementation Always Works™ for: $ARGUMENTS.
+
+Follow this systematic approach:
+
+## Core Philosophy
+
+- "Should work" ≠ "does work" - Pattern matching isn't enough
+- I'm not paid to write code, I'm paid to solve problems
+- Untested code is just a guess, not a solution
+
+# The 30-Second Reality Check - Must answer YES to ALL:
+
+- Did I run/build the code?
+- Did I trigger the exact feature I changed?
+- Did I see the expected result with my own observation (including GUI)?
+- Did I check for error messages?
+- Would I bet $100 this works?
+
+# Phrases to Avoid:
+
+- "This should work now"
+- "I've fixed the issue" (especially 2nd+ time)
+- "Try it now" (without trying it myself)
+- "The logic is correct so..."
+
+# Specific Test Requirements:
+
+- UI Changes: Actually click the button/link/form
+- API Changes: Make the actual API call
+- Data Changes: Query the database
+- Logic Changes: Run the specific scenario
+- Config Changes: Restart and verify it loads
+
+# The Embarrassment Test:
+
+"If the user records trying this and it fails, will I feel embarrassed to see his face?"
+
+# Time Reality:
+
+- Time saved skipping tests: 30 seconds
+- Time wasted when it doesn't work: 30 minutes
+- User trust lost: Immeasurable
+
+A user describing a bug for the third time isn't thinking "this AI is trying hard" - they're thinking "why am I wasting time with this incompetent tool?"

package/.claude/hooks/play-sound.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+
+const { exec } = require('child_process');
+const os = require('os');
+
+// Get command line argument for sound type
+const soundType = process.argv[2] || 'default';
+
+// Get platform-specific sound command and file
+function getSoundConfig(type = 'default') {
+  const platform = os.platform();
+
+  switch (platform) {
+    case 'darwin': // macOS
+      const macSounds = {
+        default: '/System/Library/Sounds/Funk.aiff',
+        notification: '/System/Library/Sounds/Blow.aiff',
+        done: '/System/Library/Sounds/Frog.aiff',
+      };
+      return {
+        command: 'afplay',
+        soundFile: macSounds[type] || macSounds.default,
+      };
+
+    case 'linux':
+      // Try multiple Linux sound players in order of preference
+      const linuxSounds = {
+        default: '/usr/share/sounds/freedesktop/stereo/complete.oga',
+        notification: '/usr/share/sounds/freedesktop/stereo/message.oga',
+        done: '/usr/share/sounds/freedesktop/stereo/bell.oga',
+      };
+      return {
+        command: 'paplay || aplay || play',
+        soundFile: linuxSounds[type] || linuxSounds.default,
+      };
+
+    case 'win32': // Windows
+      const winSounds = {
+        default: 'C:\\Windows\\Media\\tada.wav',
+        notification: 'C:\\Windows\\Media\\Windows Notify.wav',
+        done: 'C:\\Windows\\Media\\Windows Ding.wav',
+      };
+      const soundPath = winSounds[type] || winSounds.default;
+      return {
+        command: `powershell -c (New-Object Media.SoundPlayer "${soundPath}").PlaySync()`,
+        soundFile: null, // Included in command
+      };
+
+    default:
+      throw new Error(`Unsupported platform: ${platform}`);
+  }
+}
+
+// Play the sound with error handling
+function playSound() {
+  try {
+    const { command, soundFile } = getSoundConfig(soundType);
+    const fullCommand = soundFile ? `${command} "${soundFile}"` : command;
+
+    exec(fullCommand, (error, stdout, stderr) => {
+      if (error) {
+        // Silent fail - don't interrupt workflow
+        if (process.env.DEBUG) {
+          console.error(`Sound playback failed: ${error.message}`);
+        }
+        return;
+      }
+      if (stderr && process.env.DEBUG) {
+        console.error(`Sound playback warning: ${stderr}`);
+      }
+    });
+  } catch (error) {
+    // Silent fail for unsupported platforms
+    if (process.env.DEBUG) {
+      console.error(`Sound setup error: ${error.message}`);
+    }
+  }
+}
+
+try {
+  playSound();
+} catch (error) {
+  // Silent fail - don't interrupt workflow
+  if (process.env.DEBUG) {
+    console.error(`Unexpected error: ${error.message}`);
+  }
+}

package/.claude/hooks/pre-tool-use.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+// Find the .claude directory by traversing up from current directory
+function findClaudeDir() {
+  let currentDir = __dirname;
+  
+  // Already in .claude/scripts, go up to .claude
+  if (currentDir.endsWith('.claude/scripts')) {
+    return path.dirname(currentDir);
+  }
+  
+  // Look for .claude directory
+  while (currentDir !== path.dirname(currentDir)) {
+    const claudeDir = path.join(currentDir, '.claude');
+    if (fs.existsSync(claudeDir)) {
+      return claudeDir;
+    }
+    currentDir = path.dirname(currentDir);
+  }
+  
+  throw new Error('Could not find .claude directory');
+}
+
+try {
+  const claudeDir = findClaudeDir();
+  const awFilePath = path.join(claudeDir, 'commands', 'aw.md');
+  
+  if (fs.existsSync(awFilePath)) {
+    const content = fs.readFileSync(awFilePath, 'utf8');
+    console.log(content);
+  } else {
+    console.error(`Warning: ${awFilePath} not found`);
+  }
+} catch (error) {
+  console.error(`Error: ${error.message}`);
+  process.exit(1);
+}

package/.claude/settings.json

@@ -0,0 +1,54 @@
+{
+    "permissions": {
+        "deny": [
+            "Read(*.env)",
+            "Bash(sudo *)",
+            "Read(~/.ssh/**)",
+            "Read(.agent/history/**)"
+        ],
+        "allow": [
+            "**"
+        ]
+    },
+    "defaultMode": "acceptEdits",
+    "enableAllProjectMcpServers": true,
+    "enabledMcpjsonServers": [
+        "playwright",
+        "context7",
+        "sequential-thinking"
+    ],
+    "hooks": {
+        "UserPromptSubmit": [
+            {
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/pre-tool-use.js"
+                    }
+                ]
+            }
+        ],
+        "PreToolUse": [
+            {
+                "matcher": "Edit|Write|Bash",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/pre-tool-use.js"
+                    }
+                ]
+            }
+        ],
+        "Notification": [
+            {
+                "matcher": "",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/play-sound.js notification"
+                    }
+                ]
+            }
+        ]
+    }
+}

package/.claude/settings.local.json

@@ -0,0 +1,13 @@
+{
+  "enableAllProjectMcpServers": true,
+  "enabledMcpjsonServers": [
+    "playwright",
+    "context7",
+    "sequential-thinking"
+  ],
+  "permissions": {
+    "allow": [
+      "Bash(bash:*)"
+    ]
+  }
+}

package/.mcp.json

@@ -0,0 +1,31 @@
+{
+  "mcpServers": {
+    "playwright": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@playwright/mcp@latest",
+        "--headless"
+      ],
+      "env": {}
+    },
+    "context7": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@upstash/context7-mcp"
+      ],
+      "env": {}
+    },
+    "sequential-thinking": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-sequential-thinking"
+      ]
+    }
+  }
+}

package/AGENTS.md

@@ -0,0 +1,44 @@
+# Code Quality Standards
+
+Always apply these standards to all code you write.
+
+## Reuse Before Creating
+
+Before writing new code, analyze existing utilities, components, hooks, helpers and tests:
+
+1. **Search first** — grep/glob for similar functionality before implementing
+2. **Extend if close** — if something exists that's 80% of what you need, extend it
+3. **Extract if duplicating** — if you're about to copy-paste, extract to shared module instead
+
+## File Size & Organization
+
+Keep files between **200-300 lines max**. If a file exceeds this:
+
+1. **Split by responsibility** — one module = one concern
+2. **Extract sub-components** — UI pieces that can stand alone should
+3. **Separate logic from presentation** — hooks/utils in their own files
+4. **Group by feature** — co-locate related files, not by type
+
+Signs a file needs splitting:
+- Multiple unrelated exports
+- Scrolling to find what you need
+- "Utils" file becoming a junk drawer
+- Component doing data fetching + transformation + rendering
+
+## Code Style
+
+1. Prefer writing clear code and use inline comments sparingly
+2. Document methods with block comments at the top of the method
+3. Use Conventional Commit format
+
+## Test To Verify Functionality
+
+If you didn't test it, it doesn't work.
+
+Verify written code by:
+- Running unit tests
+- Running end to end tests
+- Checking for type errors
+- Checking for lint errors
+- Smoke testing and checking for runtime errors with Playwright
+- Takins screenshots and verifying the UI is as expected

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md