Build

# Ralph Loop - Junior Dev Workflow

Implement a full junior developer workflow following the Ralph loop style. This command automates the complete issue-to-PR workflow with test-first development, frequent commits, and thorough validation.

⏱️ **Estimated time**: 20-40 minutes depending on issue complexity and validation cycles

## Prerequisites

Before running this command, ensure:

- **GitHub CLI** (`gh`) is installed and authenticated: `gh auth status`
- **Git** is configured with user name and email: `git config user.name` and `git config user.email` (sets commit author)
- **Bun** is installed: `bun --version`
- **Repository access**: You have write access to the repository
- **Clean state**: Current working directory is clean or changes are stashed/committed

**Note**: The PR author on GitHub will be the user authenticated with `gh` CLI. The commit author is determined by git config settings.

## Configuration

Default configuration (automatically detected or uses these defaults):

- **Repository**: Detected from `git remote get-url origin` or defaults to `marc-aurele-besner/knowyouremoji.com`
- **Main branch**: `main`
- **Max validation attempts**: 5

## Usage

```bash
# Full workflow - pick next available issue
@build

# Work on specific issue (skip milestone/issue selection)
@build --issue <issue-number>

# Or run phases individually for more control:
@build --select-issue    # Phase 1: Issue selection only
@build --setup           # Phase 2: Issue setup (assign + branch)
@build --develop         # Phase 3: Development work
@build --validate        # Phase 4: Run validation and fixes
@build --cicd            # Phase 4.5: Review/update CI/CD workflows
@build --docs            # Phase 4.6: Review/update documentation
@build --pr              # Phase 5: Create pull request

Steps

Phase 0: Initial Setup (Always run first)

1. Detect repository configuration
   • Get repository from git remote: git remote get-url origin | sed 's/.*[:/]//;s/.git$//'
   • Expected format: owner/repo (e.g., marc-aurele-besner/knowyouremoji.com)
   • If detection fails, use default: marc-aurele-besner/knowyouremoji.com
   • Store repository variable for use in all subsequent gh commands
   • Verify authentication: gh auth status
   • Verify git author configuration:
     • Check: git config user.name and git config user.email
     • If not set, configure: git config user.name "Your Name" and git config user.email "your.email@example.com"
     • This ensures all commits have the correct author information

Phase 1: Issue Selection (Skip if --issue parameter provided)

2. Query and select milestone

   • Use gh api "repos/<repo>/milestones?state=open&sort=title&direction=asc" to fetch open milestones
   • Display milestones with their open/closed issue counts
   • Select the first milestone with open issues (sorted by title)
   • If no milestones exist, proceed with all open issues

3. Query open issues from selected milestone

   • Use gh issue list --repo <repo> --state open --assignee "" --milestone "<milestone>" --json number,title,labels,milestone to get unassigned issues
   • Sort issues by:
     1. Category order (SETUP → TYPE → DATA → PAGE → COMBO → INTERPRETER → RATE → SEO → DEPLOY → TEST → AUTH → SUB → HISTORY → SHARE)
     2. Category number (001 before 002)
     3. Priority (P0 > P1 > P2)
     4. Issue number (as tiebreaker)
   • Select the first issue from the sorted list

4. Query full issue details

   • Use gh issue view <issue-number> --repo <repo> --json body,title,labels,assignees,milestone to get complete issue information
   • Store issue number, title, body, labels, and milestone for later use

Phase 2: Issue Setup

5. Assign yourself to the issue

   • Use gh issue edit <issue-number> --repo <repo> --add-assignee "@me" to assign the issue
   • Verify assignment was successful

6. Create branch for the issue

   • Ensure main branch is up to date first: git checkout main && git pull origin main
   • Generate branch name: issue-<issue-number>-<sanitized-title>
     • Sanitize title: lowercase, replace non-alphanumeric with hyphens, limit to 50 chars
     • Example: "SETUP-001: Initialize Next.js" → issue-123-setup-001-initialize-nextjs
   • Check if branch exists locally or remotely
   • If exists locally: git checkout <branch-name>
   • If exists remotely: git checkout -b <branch-name> origin/<branch-name>
   • If new: git checkout -b <branch-name> from main branch

7. Push branch and link to issue

   • Push branch: git push -u origin <branch-name>
   • Add comment to issue: gh issue comment <issue-number> --repo <repo> --body "🔗 Branch created: \`\n\nWorking on this issue."`
   • Link branch via GitHub development field (if supported)

Phase 3: Development (Test-First Approach)

8. Work on the issue with test-first mentality
   • Read issue details carefully to understand requirements
   • For applicable issues:
     • Write tests first (before implementation)
     • Ensure tests cover all requirements from the issue
     • Run tests to confirm they fail (red phase)
   • Implementation approach:
     • Implement code to make tests pass (green phase)
     • Refactor while keeping tests green
     • Maintain 100% test coverage requirement
   • Commit frequently:
     • Commit after each logical unit of work
     • Use descriptive commit messages: feat: <description>, fix: <description>, test: <description>
     • Examples:
       • test: add tests for emoji data loader
       • feat: implement emoji data loader
       • fix: handle edge case in emoji slug generation
   • Push semi-frequently:
     • Push every 3-5 commits or after completing a significant feature
     • Use git push origin <branch-name>
   • Follow project conventions from CLAUDE.md and AGENT.md
   • Reference the issue in commit messages when relevant: `Resolves #<issue-numbe