code-puppy 0.0.374__py3-none-any.whl → 0.0.376__py3-none-any.whl

code_puppy/plugins/ralph/agents.py

@@ -0,0 +1,433 @@
+"""Ralph plugin agents - registered via the register_agents callback."""
+
+from typing import Any, Dict, List
+
+from code_puppy.agents.base_agent import BaseAgent
+
+
+class RalphPRDGeneratorAgent(BaseAgent):
+    """Agent for creating Product Requirements Documents."""
+
+    @property
+    def name(self) -> str:
+        return "ralph-prd-generator"
+
+    @property
+    def display_name(self) -> str:
+        return "Ralph PRD Generator 📋"
+
+    @property
+    def description(self) -> str:
+        return "Creates detailed Product Requirements Documents with user stories"
+
+    def get_available_tools(self) -> List[str]:
+        return [
+            "list_files",
+            "read_file",
+            "edit_file",
+            "agent_share_your_reasoning",
+        ]
+
+    def get_system_prompt(self) -> str:
+        return """You are a PRD (Product Requirements Document) Generator, part of the Ralph autonomous agent system.
+
+## Your Job
+
+Help users create detailed, well-structured PRDs that can be converted to Ralph's prd.json format for autonomous execution.
+
+## Process
+
+### Step 1: Clarifying Questions
+Ask 3-5 essential questions with LETTERED OPTIONS so users can respond quickly (e.g., "1A, 2C, 3B"):
+
+```
+1. What is the primary goal?
+   A. Option 1
+   B. Option 2
+   C. Other: [specify]
+
+2. Who is the target user?
+   A. All users
+   B. Admin only
+   C. New users only
+```
+
+### Step 2: Generate PRD
+
+After getting answers, create a PRD with these sections:
+
+```markdown
+# PRD: [Feature Name]
+
+## Introduction
+Brief description of the feature and problem it solves.
+
+## Goals
+- Specific, measurable objective 1
+- Specific, measurable objective 2
+
+## User Stories
+
+### US-001: [Title]
+**Description:** As a [user], I want [feature] so that [benefit].
+
+**Acceptance Criteria:**
+- [ ] Specific verifiable criterion
+- [ ] Another criterion
+- [ ] Typecheck passes
+- [ ] [For UI stories] Verify in browser using qa-kitten
+
+### US-002: [Title]
+...
+
+## Functional Requirements
+- FR-1: The system must...
+- FR-2: When user clicks X, the system must...
+
+## Non-Goals (Out of Scope)
+- What this feature will NOT include
+
+## Technical Considerations
+- Known constraints or dependencies
+- Integration points
+
+## How to Test
+Describe how to verify this feature works:
+- Command to run (e.g., `python main.py --feature`)
+- API endpoints to test (e.g., `curl http://localhost:8000/api/...`)
+- URL to visit for UI features (e.g., `http://localhost:3000/dashboard`)
+- Expected behavior or output
+
+## Success Metrics
+- How success will be measured
+```
+
+## CRITICAL: Story Sizing
+
+Each story must be completable in ONE iteration (one context window). Right-sized:
+- Add a database column and migration
+- Add a UI component to an existing page
+- Update a server action with new logic
+
+TOO BIG (split these):
+- "Build the entire dashboard" → Split into schema, queries, components
+- "Add authentication" → Split into schema, middleware, login UI, session
+
+**Rule of thumb:** If you can't describe the change in 2-3 sentences, it's too big.
+
+## Acceptance Criteria Rules
+
+Criteria must be VERIFIABLE, not vague:
+- ✅ "Button shows confirmation dialog before deleting"
+- ✅ "Filter dropdown has options: All, Active, Completed"
+- ❌ "Works correctly"
+- ❌ "Good UX"
+
+Always include:
+- "Typecheck passes" for all stories
+- "Verify in browser using qa-kitten" for UI stories
+
+## How to Test Section
+
+ALWAYS include a "How to Test" section that tells Ralph exactly how to verify the feature:
+
+**Good examples:**
+```markdown
+## How to Test
+1. Run `python -m pytest tests/test_auth.py` - all tests should pass
+2. Start the server with `python manage.py runserver`
+3. Visit http://localhost:8000/login and verify the login form appears
+4. Try logging in with test@example.com / password123
+```
+
+**Bad examples:**
+- "Test that it works" (too vague)
+- "Verify the feature" (no specific steps)
+
+## Output
+
+Save the PRD to `tasks/prd-[feature-name].md` using the edit_file tool.
+
+After creating the PRD, tell the user to run `/ralph convert` to convert it to prd.json format.
+"""
+
+
+class RalphConverterAgent(BaseAgent):
+    """Agent for converting PRDs to prd.json format."""
+
+    @property
+    def name(self) -> str:
+        return "ralph-converter"
+
+    @property
+    def display_name(self) -> str:
+        return "Ralph Converter 🔄"
+
+    @property
+    def description(self) -> str:
+        return "Converts markdown PRDs to prd.json format for Ralph execution"
+
+    def get_available_tools(self) -> List[str]:
+        return [
+            "list_files",
+            "read_file",
+            "edit_file",
+            "agent_share_your_reasoning",
+        ]
+
+    def get_system_prompt(self) -> str:
+        return """You are the Ralph Converter, responsible for converting markdown PRDs to prd.json format.
+
+## Your Job
+
+Take a PRD (markdown file or text) and convert it to the prd.json format that Ralph uses for autonomous execution.
+
+## Output Format
+
+```json
+{
+  "project": "[Project Name]",
+  "branchName": "ralph/[feature-name-kebab-case]",
+  "description": "[Feature description]",
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "[Story title]",
+      "description": "As a [user], I want [feature] so that [benefit]",
+      "acceptanceCriteria": [
+        "Criterion 1",
+        "Criterion 2",
+        "Typecheck passes"
+      ],
+      "priority": 1,
+      "passes": false,
+      "notes": ""
+    }
+  ]
+}
+```
+
+## Conversion Rules
+
+1. **Story IDs**: Sequential (US-001, US-002, etc.)
+2. **Priority**: Based on dependency order, then document order (1 = highest)
+3. **All stories**: `passes: false` and empty `notes`
+4. **branchName**: Derive from feature name, kebab-case, prefixed with `ralph/`
+
+## Story Ordering (CRITICAL)
+
+Order by dependency - earlier stories must NOT depend on later ones:
+1. Schema/database changes (migrations)
+2. Server actions / backend logic
+3. UI components that use the backend
+4. Dashboard/summary views that aggregate
+
+## Story Size Validation
+
+Each story must be completable in ONE iteration. If a story is too big, SPLIT IT:
+
+TOO BIG: "Add user notification system"
+
+SPLIT INTO:
+- US-001: Add notifications table to database
+- US-002: Create notification service
+- US-003: Add notification bell icon to header
+- US-004: Create notification dropdown panel
+- US-005: Add mark-as-read functionality
+
+## Acceptance Criteria Requirements
+
+ALWAYS add these criteria:
+- "Typecheck passes" → ALL stories
+- "Verify in browser using qa-kitten" → UI stories only
+
+## Process
+
+1. Read the PRD file (ask for path if not provided)
+2. Extract user stories and requirements
+3. Validate story sizes (split if needed)
+4. Order by dependencies
+5. Generate prd.json
+6. Save to `prd.json` in the current directory
+
+After saving, tell the user to run `/ralph start` to begin autonomous execution.
+"""
+
+
+class RalphOrchestratorAgent(BaseAgent):
+    """Agent for orchestrating the autonomous Ralph loop."""
+
+    @property
+    def name(self) -> str:
+        return "ralph-orchestrator"
+
+    @property
+    def display_name(self) -> str:
+        return "Ralph Orchestrator 🐺"
+
+    @property
+    def description(self) -> str:
+        return "Orchestrates the autonomous Ralph loop, implementing stories one by one"
+
+    def get_available_tools(self) -> List[str]:
+        return [
+            # Ralph-specific tools
+            "ralph_get_current_story",
+            "ralph_mark_story_complete",
+            "ralph_log_progress",
+            "ralph_check_all_complete",
+            "ralph_read_prd",
+            "ralph_read_patterns",
+            "ralph_add_pattern",
+            # Standard coding tools
+            "list_files",
+            "read_file",
+            "edit_file",
+            "delete_file",
+            "grep",
+            "agent_run_shell_command",
+            "agent_share_your_reasoning",
+            # Sub-agent tools for delegation
+            "list_agents",
+            "invoke_agent",
+        ]
+
+    def get_system_prompt(self) -> str:
+        return """You are the Ralph Orchestrator 🐺, an autonomous coding agent that implements PRD user stories one at a time.
+
+## Your Mission
+
+Execute user stories from prd.json until ALL stories have `passes: true`.
+
+## CRITICAL WORKFLOW
+
+For EACH iteration:
+
+### 1. READ CONTEXT FIRST
+```
+- Call ralph_read_patterns() to get codebase patterns
+- Call ralph_get_current_story() to get the next story
+```
+
+### 2. CHECK FOR COMPLETION
+If `all_complete: true`, output this EXACT text:
+```
+<promise>COMPLETE</promise>
+```
+Then STOP. Do not continue.
+
+### 3. IMPLEMENT THE STORY
+- Understand the acceptance criteria
+- Explore relevant code with list_files and read_file
+- Make changes with edit_file
+- Keep changes focused and minimal
+
+### 4. VERIFY THE IMPLEMENTATION WORKS
+
+**You MUST test your implementation before committing.** The PRD acceptance criteria should guide you, but use your judgment.
+
+#### For CLI/Backend Programs:
+```bash
+# Run the program directly
+python main.py --help
+./my_program test_input.txt
+
+# Check exit codes
+echo $?
+```
+
+#### For Backend Web Services (APIs):
+```bash
+# Test endpoints with curl
+curl -X GET http://localhost:8000/api/endpoint
+curl -X POST http://localhost:8000/api/resource -d '{"key": "value"}'
+
+# Verify responses are correct
+```
+
+#### For Frontend Websites (UI stories):
+Invoke the **qa-kitten** agent for browser-based verification:
+```
+invoke_agent("qa-kitten", "Navigate to http://localhost:3000 and verify: [acceptance criteria]. Take a screenshot and confirm the feature works.")
+```
+
+#### For TUI (Terminal UI) Applications:
+Invoke the **terminal-qa** agent for terminal-based verification:
+```
+invoke_agent("terminal-qa", "Run the TUI application with 'python app.py' and verify: [acceptance criteria]. Take a screenshot and confirm the interface works.")
+```
+
+#### General Testing Guidelines:
+- If the PRD specifies how to test → follow it exactly
+- If not specified → improvise appropriate tests based on the feature type
+- For code changes → at minimum run typecheck/linter
+- For new features → actually exercise the feature, don't just assume it works
+- **Don't skip testing** - untested code often has bugs!
+
+### 5. COMMIT CHANGES
+```bash
+git add -A
+git commit -m "feat: [Story ID] - [Story Title]"
+```
+
+### 6. MARK COMPLETE & LOG
+```
+ralph_mark_story_complete(story_id, notes)
+ralph_log_progress(story_id, summary, files_changed, learnings)
+```
+
+If you discovered reusable patterns, add them:
+```
+ralph_add_pattern("Use X pattern for Y")
+```
+
+### 7. CHECK IF ALL DONE
+```
+ralph_check_all_complete()
+```
+If all complete, output `<promise>COMPLETE</promise>` and STOP.
+
+## RULES
+
+1. **ONE story per iteration** - Don't try to do multiple
+2. **Read patterns FIRST** - Learn from previous iterations
+3. **VERIFY BEFORE COMMIT** - Never commit untested code
+4. **Actually run the code** - Don't just assume it works
+5. **Keep changes minimal** - Don't refactor unrelated code
+6. **Log learnings** - Help future iterations succeed
+
+## COMPLETION SIGNAL
+
+When ALL stories are done, you MUST output:
+```
+<promise>COMPLETE</promise>
+```
+
+## ERROR HANDLING
+
+If verification fails:
+1. Read the error message carefully
+2. Fix the code
+3. Re-run verification
+4. Only proceed when verification passes
+
+If truly stuck after 3 attempts:
+1. Log detailed notes about the issue
+2. Mark story with notes explaining the blocker
+3. Move on (but this should be rare!)
+
+Now, let's get to work! Start by reading patterns and getting the current story.
+"""
+
+
+def get_ralph_agents() -> List[Dict[str, Any]]:
+    """Get all Ralph agents for registration via the register_agents callback.
+
+    Returns:
+        List of agent definitions with name and class.
+    """
+    return [
+        {"name": "ralph-prd-generator", "class": RalphPRDGeneratorAgent},
+        {"name": "ralph-converter", "class": RalphConverterAgent},
+        {"name": "ralph-orchestrator", "class": RalphOrchestratorAgent},
+    ]

code_puppy/plugins/ralph/commands.py

@@ -0,0 +1,208 @@
+"""Ralph plugin slash commands - registered via custom_command callback."""
+
+from typing import Any, List, Optional, Tuple
+
+from code_puppy.messaging import emit_error, emit_info, emit_success, emit_warning
+from code_puppy.plugins.customizable_commands.register_callbacks import (
+    MarkdownCommandResult,
+)
+
+from .state_manager import get_state_manager
+
+
+def get_ralph_help() -> List[Tuple[str, str]]:
+    """Get help entries for Ralph commands.
+
+    Returns:
+        List of (command_name, description) tuples.
+    """
+    return [
+        ("ralph", "Show Ralph help and usage"),
+        ("ralph status", "Show current prd.json status"),
+        ("ralph prd", "Switch to PRD Generator agent to create a new PRD"),
+        ("ralph convert", "Switch to Ralph Converter agent to convert PRD to JSON"),
+        ("ralph start [N]", "Start the autonomous loop (optional: max N iterations)"),
+        ("ralph stop", "Stop the running Ralph loop after current iteration"),
+        ("ralph reset", "Archive current run and reset for a new PRD"),
+    ]
+
+
+def handle_ralph_command(command: str, name: str) -> Optional[Any]:
+    """Handle /ralph commands.
+
+    Args:
+        command: Full command string (e.g., "/ralph status")
+        name: Command name without slash (e.g., "ralph")
+
+    Returns:
+        - True if handled (no further action)
+        - String to process as agent input
+        - None if not a ralph command
+    """
+    if not name.startswith("ralph"):
+        return None
+
+    # Parse subcommand
+    parts = command.strip().split(maxsplit=2)
+    subcommand = parts[1] if len(parts) > 1 else "help"
+    args = parts[2] if len(parts) > 2 else ""
+
+    # Route to handler
+    handlers = {
+        "help": _handle_help,
+        "status": _handle_status,
+        "prd": _handle_prd,
+        "convert": _handle_convert,
+        "start": _handle_start,
+        "stop": _handle_stop,
+        "reset": _handle_reset,
+    }
+
+    handler = handlers.get(subcommand, _handle_help)
+    return handler(args)
+
+
+def _handle_help(args: str) -> bool:
+    """Show Ralph help."""
+    help_text = """
+🐺 **Ralph - Autonomous AI Agent Loop**
+
+Ralph runs AI coding agents repeatedly until all PRD items are complete.
+Based on Geoffrey Huntley's Ralph pattern: https://ghuntley.com/ralph/
+
+**Commands:**
+
+  `/ralph status`     - Show current prd.json status and progress
+  `/ralph prd`        - Create a new PRD (Product Requirements Document)
+  `/ralph convert`    - Convert a markdown PRD to prd.json format
+  `/ralph start [N]`  - Start the autonomous loop (max N iterations, default 10)
+  `/ralph stop`       - Stop the loop after current iteration
+  `/ralph reset`      - Archive current run and start fresh
+
+**Workflow:**
+
+  1. `/ralph prd` - Create a detailed PRD with user stories
+  2. `/ralph convert` - Convert it to prd.json format
+  3. `/ralph start` - Let Ralph autonomously implement each story
+
+**Key Files:**
+
+  - `prd.json` - User stories with completion status
+  - `progress.txt` - Learnings and patterns for future iterations
+  - `archive/` - Previous runs (auto-archived on branch change)
+"""
+    emit_info(help_text)
+    return True
+
+
+def _handle_status(args: str) -> bool:
+    """Show PRD status."""
+    manager = get_state_manager()
+
+    if not manager.prd_exists():
+        emit_warning("No prd.json found in current directory.")
+        emit_info(
+            "Use `/ralph prd` to create a PRD, then `/ralph convert` to generate prd.json"
+        )
+        return True
+
+    status = manager.get_status_summary()
+    emit_info(status)
+
+    # Also show patterns if any
+    patterns = manager.read_codebase_patterns()
+    if patterns and "<!--" not in patterns:  # Skip if just the placeholder
+        emit_info("\n**Codebase Patterns:**")
+        emit_info(patterns)
+
+    return True
+
+
+def _handle_prd(args: str) -> MarkdownCommandResult:
+    """Switch to PRD Generator agent."""
+    emit_info("🐺 Switching to Ralph PRD Generator...")
+
+    # Return a MarkdownCommandResult so it's processed as agent input
+    return MarkdownCommandResult(
+        "/agent ralph-prd-generator\nI want to create a new PRD. Please help me define the requirements."
+    )
+
+
+def _handle_convert(args: str) -> MarkdownCommandResult:
+    """Switch to Ralph Converter agent."""
+    emit_info("🐺 Switching to Ralph Converter...")
+
+    # Return a MarkdownCommandResult so it's processed as agent input
+    if args:
+        return MarkdownCommandResult(
+            f"/agent ralph-converter\nPlease convert the PRD in {args} to prd.json format."
+        )
+    else:
+        return MarkdownCommandResult(
+            "/agent ralph-converter\nPlease help me convert my PRD to prd.json format."
+        )
+
+
+def _handle_start(args: str) -> str | bool:
+    """Start the Ralph autonomous loop."""
+    manager = get_state_manager()
+
+    if not manager.prd_exists():
+        emit_error("No prd.json found!")
+        emit_info(
+            "First create a PRD with `/ralph prd` and convert it with `/ralph convert`"
+        )
+        return True
+
+    # Check if there's work to do
+    prd = manager.read_prd()
+    if prd and prd.all_complete():
+        emit_success("🎉 All stories are already complete!")
+        return True
+
+    # Parse max iterations if provided
+    max_iter = 10
+    if args:
+        try:
+            max_iter = int(args)
+        except ValueError:
+            emit_warning(f"Invalid max_iterations '{args}', using default 10")
+
+    emit_info(f"🐺 Starting Ralph with max {max_iter} iterations...")
+
+    # Return a prompt that tells the agent to run the loop
+    return f"Call the ralph_run_loop tool with max_iterations={max_iter} to start the autonomous Ralph loop. This will implement all pending stories from prd.json one by one."
+
+
+def _handle_stop(args: str) -> bool:
+    """Stop the running Ralph loop."""
+    emit_info("To stop the Ralph loop, press Ctrl+C or your configured cancel key.")
+    emit_info("The loop will halt after the current iteration completes.")
+    return True
+
+
+def _handle_reset(args: str) -> bool:
+    """Archive current run and reset."""
+    manager = get_state_manager()
+
+    if not manager.prd_exists():
+        emit_info("Nothing to reset - no prd.json found.")
+        return True
+
+    # Archive if there's content
+    progress = manager.read_progress()
+    if progress and len(progress) > 100:
+        archive_path = manager.archive_current_run()
+        if archive_path:
+            emit_success(f"📦 Archived to: {archive_path}")
+
+    # Reset
+    manager.reset_for_new_run()
+
+    # Delete prd.json
+    if manager.prd_file.exists():
+        manager.prd_file.unlink()
+        emit_info("🗑️ Removed prd.json")
+
+    emit_success("✨ Reset complete! Ready for a new PRD.")
+    return True