Instructions

gh

gh auth login

Workflow

1. Identify the Next Task: Instead of reading a progress markdown file, run

   gh issue list --label "user-story" --limit 1 --search "sort:created-asc"

   to grab the next available issue in creation order (lowest issue number first, matching PRD story order). Note the issue number, title, and body (which contains the Acceptance Criteria).
2. State Management: Before starting work, assign the issue to yourself (or the current user) using

   gh issue edit <issue-number> --add-assignee "@me"

   . This provides visibility and prevents conflicts.
3. Branching: Follow standard Git flow. Create and checkout a new branch based on the issue number:

   git checkout -b feature/us-<issue-number>

   .
4. Execute: Implement the code, configuration, or changes required to complete that single user story.
   • Ensure you fulfill all of the listed Acceptance Criteria in the GitHub issue body.
   • Write unit tests or perform browser verification if required.
   • Update any relevant documentation.
   • Important: If you cannot complete the entire story within ~2 hours of effort, or if you identify missing requirements or technical blockers during implementation, do NOT continue. Move to step 5 (Handling Blockers) instead.
5. Handling Blockers: If you encounter missing requirements, ambiguity, or blockers that prevent completion, add a comment to the issue detailing the blocker using

   gh issue comment <issue-number> --body "<Details>"

   , add a

   blocked

   label using

   gh issue edit <issue-number> --add-label "blocked"

   , and stop work on this issue.
6. Self-Review: Before considering the task complete, perform this specific checklist:
   • For each Acceptance Criterion listed in the issue, is there code implementing it? (Check each one individually.)
   • Are there new tests? Run them locally to verify they pass.
   • Do the tests exercise the core feature (not just superficial checks)?
   • Do the tests cover the happy path AND relevant error cases?
   • If all checkboxes pass, proceed to step 7. If any fail, return to step 4 to address gaps.
7. Commit Code: Once your user story or chunk is complete, you must commit your changes to your feature branch.
   • Do not use

     git commit -a

     . Select files manually.
8. Pull Request & Linking:
   • Push the branch:

     git push -u origin HEAD

     .
   • Create a Pull Request using a heredoc to ensure newlines render correctly:
     bash

     gh pr create --title "feat: <issue-title>" --body "$(cat <<'EOF'
     Closes #<issue-number>
     
     ### Summary
     <Summary of work done>
     EOF
     )"

     Include

     Closes #<issue-number>

     so merging the PR automatically closes the issue.

Loop Completion Mechanism

gh issue list --label "user-story" --limit 1 --search "sort:created-asc"

[RALPH_LOOP_DONE_MARKER]

• Complete exactly one user story or task per invocation. Do not attempt to complete multiple user stories.
• If all user stories are done, you MUST output the completion marker so the loop knows to stop.

Examples

1. Run

   gh issue list --label "user-story" --limit 1 --search "sort:created-asc"

   . Returns Issue #12: "Add priority selector".
2. Assign:

   gh issue edit 12 --add-assignee "@me"

   .
3. Branch:

   git checkout -b feature/us-12

   .
4. Implement the feature and write tests.
5. Review the code to ensure it meets Acceptance Criteria in Issue #12.
6. Commit:

   git add src/components/TaskEdit.tsx

   and

   git commit -m "feat: add priority selector (US-002)"

   .
7. Push:

   git push -u origin HEAD

   .
8. Create PR:
   bash

   gh pr create --title "feat: Add priority selector" --body "$(cat <<'EOF'
   Closes #12
   
   ### Summary
   Added priority selector to task edit.
   EOF
   )"