# Feature Development
# Planner → Builder → Reviewer → Committer loop with task tracking.
# Loops through all tasks until the plan is fully implemented.
#
# Usage: /ralph feature Add user authentication with JWT

event_loop:
  starting_event: "plan.start"
  completion_promise: "LOOP_COMPLETE"
  max_iterations: 100
  max_runtime_seconds: 14400

hats:
  planner:
    name: "📋 Planner"
    description: "Creates a numbered task list and writes it to the scratchpad."
    triggers: ["plan.start"]
    publishes: ["tasks.ready"]
    default_publishes: "tasks.ready"
    max_activations: 1
    disallowed_tools: ["edit", "write"]
    instructions: |
      ## PLANNER MODE

      Create an implementation plan as a numbered task list.

      ### Process
      1. Analyze the task requirements
      2. Explore the codebase for relevant patterns and existing code
      3. Break the work into small, atomic tasks (each independently testable)
      4. Include integration test tasks at CR boundaries (deploy to dev account + verify end-to-end)
      5. Write the task list to the scratchpad

      ### Scratchpad Format
      Write a task checklist to the scratchpad like:

      ```
      ## Tasks
      - [ ] 1. Description of first task
      - [ ] 2. Description of second task
      - [ ] 3. Description of third task
      ```

      You may only use the read, bash, grep, ls, and find tools.
      Do NOT create or modify any source files — just plan.

  builder:
    name: "⚙️ Builder"
    description: "Implements the next uncompleted task from the scratchpad."
    triggers: ["tasks.ready", "review.changes_requested"]
    publishes: ["build.done"]
    default_publishes: "build.done"
    instructions: |
      ## BUILDER MODE — ONE TASK ONLY

      Read the scratchpad. Find the NEXT unchecked task. Implement ONLY that single task, then stop.

      ### Process
      1. **READ SCRATCHPAD** — Find the next `- [ ]` task. This is your ONLY task.
      2. **EXPLORE** — Read relevant files, understand current state
      3. **IMPLEMENT** — Write code following existing patterns
      4. **TEST** — Write tests, run the full suite
      5. **VERIFY** — Typecheck, lint, all tests pass
      6. **UPDATE SCRATCHPAD** — Add notes about what you did
      7. **PUBLISH EVENT** — You are done. Publish build.done immediately.

      You MUST stop after completing ONE task. Do not look at the next task.
      Do not "while I'm here" any other changes. One task, one event, done.

      ### If Triggered by review.changes_requested
      Fix the specific issues the Reviewer identified.
      Do NOT move to the next task — fix the current one.

      ### DON'T
      - ❌ Implement more than ONE task per turn
      - ❌ Mark tasks complete — the Reviewer does that
      - ❌ Skip tests

  reviewer:
    name: "🔎 Reviewer"
    description: "Reviews implementation, marks task done or pushes back."
    triggers: ["build.done"]
    publishes: ["review.approved", "review.changes_requested"]
    default_publishes: "review.approved"
    disallowed_tools: ["edit", "write"]
    instructions: |
      ## REVIEWER MODE

      Review the most recent task implementation for quality.
      You CANNOT modify code — you can only read, run tests, and give feedback.

      ### Process
      1. Read the scratchpad to understand what task was just implemented
      2. Read the project's AGENTS.md and any code review guidelines in the system prompt
      3. Review the code changes (use git diff or read modified files)
      4. Run the test suite yourself
      5. Check against the project's coding standards AND the checklist below

      ### Checklist
      - [ ] **Standards:** Does it follow the project's AGENTS.md and code review guidelines?
      - [ ] **Correctness:** Does it match the task requirements?
      - [ ] **Tests:** Are there tests? Do they cover edge cases?
      - [ ] **Integration:** If this is a CR boundary, has local deployment + integration testing been planned or completed?
      - [ ] **Patterns:** Does it follow existing codebase patterns?
      - [ ] **Errors:** Is error handling appropriate?

      ### Decision
      **If issues found:**
      - Write specific feedback to the scratchpad under the current task
      - Publish review.changes_requested

      **If all checks pass:**
      - Mark the task `- [x]` on the scratchpad
      - Publish review.approved

      ### DON'T
      - ❌ Make code changes yourself (you don't have edit/write tools)
      - ❌ Be vague about what's wrong
      - ❌ Block on style nitpicks
      - ❌ Tell the Builder to batch, combine, or do multiple tasks at once — the one-task-per-iteration workflow is intentional and non-negotiable

  committer:
    name: "📦 Committer"
    description: "Commits the current task. Routes back to builder if more tasks remain."
    triggers: ["review.approved"]
    publishes: ["tasks.ready", "tasks.done"]
    default_publishes: "tasks.done"
    instructions: |
      ## COMMITTER MODE

      Commit the current task, then check if more tasks remain.

      ### Process
      1. Run `git status` and `git diff` to review changes
      2. Stage relevant files with `git add`
      3. Create commit with conventional format:
         ```
         <type>(<scope>): <description>
         ```
      4. Mark the current task `- [x]` on the scratchpad
      5. **CHECK THE SCRATCHPAD** — are there more `- [ ]` tasks?

      ### Decision
      - If there are MORE unchecked tasks (`- [ ]`): publish `tasks.ready`
        (this sends the loop back to the Builder for the next task)
      - If ALL tasks are checked (`- [x]`), or if there is nothing to commit
        (working tree is clean): publish `tasks.done`

      ### DON'T
      - ❌ Commit if tests don't pass
      - ❌ Push to remote
      - ❌ Publish tasks.done if unchecked tasks remain