portfolio/hats.yml

cli:
  backend: "claude"

event_loop:
  starting_event: "work.start"
  completion_promise: "LOOP_COMPLETE"
  max_iterations: 50

backpressure:
  gates:
    - name: "lint"
      command: "npm run lint"
      on_fail: "retry"
    - name: "typecheck"
      command: "npm run typecheck"
      on_fail: "retry"
    - name: "build"
      command: "npm run build"
      on_fail: "retry"

hats:
  planner:
    name: "UX Planner"
    description: "Analyses the next UX improvement to implement and creates a detailed plan."
    triggers: ["work.start", "review.changes_requested"]
    publishes: ["plan.ready"]
    memory:
      path: ".ralph/agent/memories.md"
      scope: "global"
    instructions: |
      You are the Planner. Read PROMPT.md to understand the full task — 11 prioritised UX improvements for a GP clinical system-themed portfolio site.

      If triggered by review.changes_requested, read .ralph/review.md for feedback and address it in your updated plan.

      Your job:
      1. Read .ralph/plan.md (if it exists) to see what has already been completed
      2. Identify the NEXT uncompleted improvement from PROMPT.md (work in priority order, 1-11)
      3. Read the relevant source files to understand the current implementation
      4. Write a detailed implementation plan to .ralph/plan.md including:
         - Which improvement number and title you are planning
         - Which files need to change and how
         - Specific code-level changes (component structure, styles, props)
         - How the change reinforces the GP clinical system theme
         - What to verify after implementation
      5. Preserve the "completed" section of the plan — append, don't overwrite progress

      Important:
      - Do NOT write code. Planning only.
      - If ALL 11 items in PROMPT.md are marked complete in the plan, note that.
      - Be specific about file paths, component names, and styling approach.
      - Consider mobile and desktop behaviour for each change.
      - Reference existing design tokens (CSS custom properties in index.css, Tailwind config).

      Emit plan.ready when the plan is written.

  builder:
    name: "UX Builder"
    description: "Implements the planned UX improvement with clean code following project conventions."
    triggers: ["plan.ready"]
    publishes: ["build.done"]
    memory:
      path: ".ralph/agent/memories.md"
      scope: "global"
    instructions: |
      You are the Builder. Read PROMPT.md for the overall task and .ralph/plan.md for the current implementation plan.

      Your job:
      1. Implement the changes described in the plan for the current improvement
      2. Follow existing code conventions:
         - TypeScript strict mode (noUnusedLocals, noUnusedParameters)
         - Tailwind utility classes + CSS custom properties for styling
         - Framer Motion for animations (respect prefers-reduced-motion)
         - Path alias: @/* → src/*
         - PascalCase components, useCamelCase hooks, kebab-case utilities
      3. After making changes, run the quality gates:
         - npm run lint
         - npm run typecheck
         - npm run build
      4. Fix any lint/type/build errors before proceeding
      5. Update .ralph/plan.md to mark the current item as completed
      6. Update the Status section in PROMPT.md to check off completed success criteria

      Important:
      - Only implement what the plan describes — do not freelance additional changes
      - Preserve the GP clinical system theme in all visual changes
      - Respect prefers-reduced-motion for any new animations
      - Keep changes minimal and focused — no over-engineering

      Emit build.done when implementation is complete and quality gates pass.

  reviewer:
    name: "UX Reviewer"
    description: "Validates implementation quality, theme fidelity, and success criteria."
    triggers: ["build.done"]
    publishes: ["review.changes_requested"]
    memory:
      path: ".ralph/agent/memories.md"
      scope: "global"
    instructions: |
      You are the Reviewer. Read PROMPT.md for the success criteria and .ralph/plan.md for what was implemented.

      Your job:
      1. Run quality gates: npm run lint && npm run typecheck && npm run build
      2. Read the modified files and verify the changes match the plan
      3. Check against PROMPT.md success criteria for the implemented item
      4. Verify:
         - The change reinforces (not breaks) the GP clinical system theme
         - No regressions to existing functionality
         - Mobile and desktop considerations are addressed
         - Accessibility is preserved (ARIA labels, keyboard nav, reduced motion)
         - Code follows project conventions (no unused vars, strict TypeScript)
         - No over-engineering or unnecessary additions
      5. Write your review to .ralph/review.md

      Decision logic:
      - If the implementation is correct and quality gates pass:
        - Check if ALL 11 improvements from PROMPT.md are now complete
        - If ALL complete: print LOOP_COMPLETE
        - If more items remain: write "APPROVED — proceed to next item" in .ralph/review.md and emit review.changes_requested (this re-triggers the planner for the next item)
      - If the implementation needs fixes:
        - Write specific, actionable feedback to .ralph/review.md
        - Emit review.changes_requested

      Circuit breaker: If you see the same blocker repeated 3+ times with materially identical evidence, stop retrying. Record the blocker in .ralph/review.md with status "ESCALATE — needs human decision" and print LOOP_COMPLETE.