PROMPT.md

PROMPT.md

RaidCoffee Development Agent - Autonomous Task Executor

@ralph-loop-control/plan-tasks.json @ralph-loop-control/plan-completed-tasks.json @ralph-loop-control/activity.md @CLAUDE.md

We are building the RaidCoffee frontend application based on the specifications in ralph-loop-control/plan-tasks.json.

Startup Procedure

1. Read ralph-loop-control/activity.md to understand recent progress and context
2. Read CLAUDE.md for development guidelines and conventions
3. Open ralph-loop-control/plan-tasks.json and select the SINGLE highest priority task where passes is false
   • Priority order: Foundation tasks first, then dependent tasks
   • Check the dependencies field - only work on tasks whose dependencies are ALL marked passes: true

Task Execution Rules

CRITICAL: Work on exactly ONE task per iteration

For Frontend Tasks (Next.js)

1. Navigate to the frontend/ directory (or use make commands from project root)
2. If this is the first task, initialize the project:

   cd frontend && bunx create-next-app@latest . --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"

3. Implement the specific task requirements
4. Run type checking: make fe-type-check
5. Run linting: make fe-lint
6. Run all frontend checks: make fe-check
7. If tests exist, run them: make fe-test
8. Use the Playwright MCP to test if the integration between frontend and backend is working accordingly

For Backend Tasks (Python)

1. Use make commands from project root (preferred):
   • Type check: make be-mypy
   • Run tests: make be-test
   • Run linter: make be-lint
   • Run all checks: make be-check
2. Or use UV directly: cd backend && uv run <command>

Verification Process

After implementing a task:

1. Start the local development server (if applicable):

   • Full stack: make dev (starts infra + runs migrations + starts backend on port 8000 + frontend on port 3001)
   • Backend only: make be-dev (port 8000)
   • Frontend only: make fe-dev (port 3001)
   • Infrastructure only: make up-infra (postgres + valkey)

2. Use specialized agents:

   • Frontend
     • nextjs-developer - for App Router features
     • react-specialist - fpr React 19 components
     • typescript-pro - for type safety
     • test-automator - for Vitest
   • Backend
     • python-pro - para código Python 3.13+ com type hints
     • postgres-pro - para otimizações do banco
     • api-designer - para design de endpoints REST
     • database-optimizer - para queries SQLAlchemy eficientes

3. Use Playwright MCP for visual verification (for tasks with UI output):

   • Navigate to the URL: mcp__playwright__browser_navigate with url: "http://localhost:3001/..."
   • Take a snapshot: mcp__playwright__browser_snapshot to capture page accessibility tree
   • Take a screenshot: mcp__playwright__browser_take_screenshot with filename: "screenshots/XX-YY.png"
   • Screenshot naming convention: {epic-number}-{task-number}.png (e.g., 01-01.png, 02-03.png)
   • Always put screenshots in screenshots folder
   • Verify the implementation visually matches requirements

   IMPORTANT: Screenshots are REQUIRED for tasks that produce visual output (pages, components, UI changes). For non-visual tasks (configuration, dependencies, types, utilities), document "N/A - No visual output" in activity.md.

4. Update ralph-loop-control/activity.md with a dated progress entry including:

   • Task ID that was completed
   • What was implemented
   • Screenshot filename (or "N/A - No visual output" for non-visual tasks)
   • Any relevant notes

5. Remove task from ralph-loop-control/plan-tasks.json:

   • Move the task from ralph-loop-control/plan-tasks.json to ralph-loop-control/plan-completed-tasks.json
   • Set passes to true for the completed task
   • Update completed_at timestamp

6. Make a git commit and open a pull request:

   • Create a semantic branch with all code changes
   • name the branch after the field branch_name
   • Use the /commit command to make a commit
   • Open up a PR in github
   • Use the /pr-review-toolkit:review-pr agent or python-code-review-engineer agent to review the code and apply the findings
   • Run the code-simplifier agent to review all PR changes and apply the findings
   • Fix all problems
   • Push branch to remote
   • Change back to main branch

Constraints

• Do NOT run git init - the repository is already initialized
• Do NOT include files from ralph-loop-control folder in the branch and PR
• Do NOT change git remotes
• Do NOT work on multiple tasks in a single iteration
• Do NOT skip dependency checks
• Prefer make commands when available (see make help)
• lsp Use the LSP servers for the available languages for semantic code retrieval and editing tools, always use for python and typescript code
• context7 for up to date documentation on third party code and libraries
• rg: Use 'rg --files | rg pattern' or 'rg --files -g pattern' instead of 'find -name' for better performance
• Agents/Subagents: If there is a specialized agent/subagent to solve a problem or better meet a need, always use that agent

Completion Signal

When there is no task in the ralph-loop-control/plan-tasks.json file, output:

COMPLETE

Error Handling

If a task cannot be completed:

1. Document the error in activity.md
2. Keep passes: false for that task
3. Add a blocked_reason field to the task
4. Proceed to the next available task (if any)

ralph.sh

#!/bin/bash

# Ralph Wiggum - Autonomous Development Loop for RaidCoffee
#
# This script runs Claude Code in a loop, executing one task per iteration
# from plan.md until all tasks are complete.
#
# Usage: ./ralph.sh <max_iterations>
# Example: ./ralph.sh 20

set -e

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color

# Check arguments
if [ -z "$1" ]; then
  echo -e "${RED}Error: Missing iterations argument${NC}"
  echo "Usage: $0 <max_iterations>"
  echo "Example: $0 20"
  exit 1
fi

MAX_ITERATIONS=$1

# Validate number
if ! [[ "$MAX_ITERATIONS" =~ ^[0-9]+$ ]] || [ "$MAX_ITERATIONS" -lt 1 ]; then
  echo -e "${RED}Error: Iterations must be a positive integer${NC}"
  exit 1
fi

echo -e "${BLUE}╔════════════════════════════════════════════════════════════╗${NC}"
echo -e "${BLUE}║         Ralph Wiggum - RaidCoffee Development Loop         ║${NC}"
echo -e "${BLUE}╠════════════════════════════════════════════════════════════╣${NC}"
echo -e "${BLUE}║ Max Iterations: ${YELLOW}$MAX_ITERATIONS${BLUE}                                      ║${NC}"
echo -e "${BLUE}║ Project: RaidCoffee Frontend                               ║${NC}"
echo -e "${BLUE}╚════════════════════════════════════════════════════════════╝${NC}"
echo ""

# Ensure screenshots directory exists
mkdir -p screenshots

# Ensure we're in the project root
if [ ! -f "./ralph-loop-control/PROMPT.md" ] || [ ! -f "ralph-loop-control/plan-tasks.json" ]; then
  echo -e "${RED}Error: PROMPT.md or plan-tasks.json not found${NC}"
  echo "Please run this script from the project root directory."
  exit 1
fi

# Check if PROMPT.md is not empty
if [ ! -s "./ralph-loop-control/PROMPT.md" ]; then
  echo -e "${RED}Error: PROMPT.md is empty${NC}"
  exit 1
fi

# Start the loop
for ((i=1; i<=MAX_ITERATIONS; i++)); do
  echo ""
  echo -e "${YELLOW}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
  echo -e "${GREEN}Iteration $i of $MAX_ITERATIONS${NC}"
  echo -e "${YELLOW}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
  echo ""
  echo -e "${BLUE}Starting Claude Code at $(date '+%Y-%m-%d %H:%M:%S')...${NC}"
  echo ""

  # Run Claude Code with PROMPT.md content
  # Using tee to show output in real-time while capturing it for completion check
  # The output is streamed to terminal AND saved to a temp file
  TEMP_OUTPUT=$(mktemp)

  # Run claude and stream output in real-time while capturing to file
  # Using || true to prevent script exit on non-zero return codes
  claude --verbose --dangerously-skip-permissions -p "$(cat ./ralph-loop-control/PROMPT.md)" --output-format stream-json 2>&1 | tee "$TEMP_OUTPUT" || true

  # Read the captured output for completion check
  result=$(cat "$TEMP_OUTPUT")
  rm -f "$TEMP_OUTPUT"

  # Check for completion signal
  if [[ "$result" == *"<promise>COMPLETE</promise>"* ]]; then
    echo ""
    echo -e "${GREEN}╔════════════════════════════════════════════════════════════╗${NC}"
    echo -e "${GREEN}║                    ALL TASKS COMPLETE!                     ║${NC}"
    echo -e "${GREEN}╠════════════════════════════════════════════════════════════╣${NC}"
    echo -e "${GREEN}║ Finished after $i iteration(s)                             ${NC}"
    echo -e "${GREEN}║ Time: $(date '+%Y-%m-%d %H:%M:%S')                          ${NC}"
    echo -e "${GREEN}╚════════════════════════════════════════════════════════════╝${NC}"
    exit 0
  fi

  echo ""
  echo -e "${BLUE}--- End of iteration $i ---${NC}"
  echo ""

  # Small delay between iterations to avoid rate limiting
  if [ "$i" -lt "$MAX_ITERATIONS" ]; then
    echo -e "${YELLOW}Waiting 5 seconds before next iteration...${NC}"
    sleep 5
  fi
done

echo ""
echo -e "${YELLOW}╔════════════════════════════════════════════════════════════╗${NC}"
echo -e "${YELLOW}║              MAX ITERATIONS REACHED ($MAX_ITERATIONS)                ║${NC}"
echo -e "${YELLOW}╠════════════════════════════════════════════════════════════╣${NC}"
echo -e "${YELLOW}║ Some tasks may still be incomplete.                       ║${NC}"
echo -e "${YELLOW}║ Check plan.md for current status.                         ║${NC}"
echo -e "${YELLOW}║ Run again with more iterations if needed.                 ║${NC}"
echo -e "${YELLOW}╚════════════════════════════════════════════════════════════╝${NC}"
exit 1