# Specification-First Development
# Spec Writer → Critic → Implementer → Verifier → Committer, looping per acceptance criterion
#
# Usage: /ralph spec-driven Build a rate limiter

event_loop:
  starting_event: "spec.start"
  completion_promise: "LOOP_COMPLETE"
  max_iterations: 50
  max_runtime_seconds: 10800

hats:
  spec_writer:
    name: "📋 Spec Writer"
    description: "Creates precise, unambiguous specifications with examples."
    triggers: ["spec.start", "spec.rejected"]
    publishes: ["spec.ready"]
    default_publishes: "spec.ready"
    instructions: |
      ## SPEC WRITER MODE

      Create a precise, unambiguous specification.

      Include:
      - **Summary**: One sentence describing what this does
      - **Acceptance Criteria**: Given-When-Then format (be exhaustive), numbered
      - **Input/Output Examples**: Concrete values
      - **Edge Cases**: Error conditions and unusual inputs
      - **Non-functional Requirements**: Performance, security
      - **Out of Scope**: What this does NOT do

      Write the spec so someone who hasn't seen the original task
      could implement it correctly from the spec alone.

      Also write a numbered task checklist to the scratchpad, one task per
      acceptance criterion or logical group:

      ```
      ## Tasks
      - [ ] 1. Implement [first acceptance criterion]
      - [ ] 2. Implement [second acceptance criterion]
      - [ ] 3. Handle edge case: [description]
      ```

  spec_reviewer:
    name: "🔎 Spec Critic"
    description: "Reviews spec for completeness. Could someone implement from this alone?"
    triggers: ["spec.ready"]
    publishes: ["spec.approved", "spec.rejected"]
    default_publishes: "spec.approved"
    instructions: |
      ## SPEC CRITIC MODE

      Review the spec for completeness and clarity.

      Checklist:
      - [ ] Could a new team member implement this from the spec alone?
      - [ ] Are all acceptance criteria testable?
      - [ ] Are edge cases covered?
      - [ ] Are error conditions specified?
      - [ ] Are there ambiguous terms that need definition?

      Be pragmatic. Don't reject for minor issues. Only reject for:
      - Fundamental ambiguity leading to wrong implementation
      - Missing critical requirements

      After 1 rejection, approve with notes rather than rejecting again.

  implementer:
    name: "⚙️ Implementer"
    description: "Implements ONE task from the scratchpad. No creative interpretation."
    triggers: ["spec.approved", "spec.violated", "tasks.next"]
    publishes: ["implementation.done"]
    default_publishes: "implementation.done"
    instructions: |
      ## IMPLEMENTER MODE — ONE TASK ONLY

      Read the scratchpad. Find the NEXT unchecked task (`- [ ]`).
      Implement ONLY that single task against the spec.

      ### Process

      1. **READ SCRATCHPAD** — Find the next `- [ ]` task
      2. **EXPLORE** — Read the spec thoroughly, search codebase for similar code
      3. **TEST** — Write failing tests first for this task's acceptance criteria
      4. **IMPLEMENT** — Write minimal code to make tests pass
      5. **VERIFY** — Run all tests, confirm criteria met
      6. **UPDATE SCRATCHPAD** — Add notes about what you did

      ### If Triggered by spec.violated
      Fix the specific violations identified by the verifier.
      Do NOT move to the next task — fix the current one.

      ### DON'T
      - ❌ Implement more than ONE task per turn
      - ❌ Add features not in the spec
      - ❌ Creatively interpret ambiguous requirements
      - ❌ Skip writing tests first

  verifier:
    name: "✅ Spec Verifier"
    description: "Verifies implementation matches spec exactly."
    triggers: ["implementation.done"]
    publishes: ["verification.passed", "spec.violated"]
    default_publishes: "verification.passed"
    instructions: |
      ## SPEC VERIFIER MODE

      Verify the current task's implementation matches the spec exactly.

      Go through the relevant acceptance criteria:
      1. Run the test for each criterion
      2. Manually verify with the examples from the spec
      3. Check edge case handling

      If ALL criteria pass: publish verification.passed.
      If violations found: publish spec.violated with specific details.

      ### DON'T
      - ❌ Skip running tests yourself
      - ❌ Approve with known violations

  committer:
    name: "📦 Committer"
    description: "Commits the current task. Routes back to implementer if more tasks remain."
    triggers: ["verification.passed"]
    publishes: ["tasks.next", "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>

         <body — what and why>
         ```
      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.next`
        (this sends the loop back to the Implementer 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
      - ❌ Push to remote
      - ❌ Publish tasks.done if unchecked tasks remain