# Ralph loop (https://github.com/snarktank/ralph) — each agent runs in a fresh
# session with clean context. Memory persists via git history and progress files.
id: feature-dev
name: Feature Development Workflow
version: 5
description: |
  Story-based execution pipeline. Planner decomposes tasks into user stories.
  Setup prepares the environment and establishes baseline.
  Developer implements each story (with tests) in a fresh session. Verifier checks each story.
  Then integration/E2E testing, PR creation, and code review.

cron:
  interval_ms: 120000  # 2 minute polling (default era 5 min)

agents:
  - id: planner
    name: Planner
    role: analysis
    description: Decomposes tasks into ordered user stories.
    model: opus  # Use Opus for strategic planning
    workspace:
      baseDir: agents/planner
      files:
        AGENTS.md: agents/planner/AGENTS.md
        SOUL.md: agents/planner/SOUL.md
        IDENTITY.md: agents/planner/IDENTITY.md

  - id: setup
    name: Setup
    role: coding
    description: Prepares environment, creates branch, establishes baseline.
    workspace:
      baseDir: agents/setup
      files:
        AGENTS.md: ../../agents/shared/setup/AGENTS.md
        SOUL.md: ../../agents/shared/setup/SOUL.md
        IDENTITY.md: ../../agents/shared/setup/IDENTITY.md

  - id: developer
    name: Developer
    role: coding
    description: Implements features, writes tests, creates PRs.
    workspace:
      baseDir: agents/developer
      files:
        AGENTS.md: agents/developer/AGENTS.md
        SOUL.md: agents/developer/SOUL.md
        IDENTITY.md: agents/developer/IDENTITY.md

  - id: verifier
    name: Verifier
    role: verification
    description: Quick sanity check - did developer actually do the work?
    workspace:
      baseDir: agents/verifier
      files:
        AGENTS.md: ../../agents/shared/verifier/AGENTS.md
        SOUL.md: ../../agents/shared/verifier/SOUL.md
        IDENTITY.md: ../../agents/shared/verifier/IDENTITY.md

  - id: tester
    name: Tester
    role: testing
    description: Integration and E2E testing after all stories are implemented.
    workspace:
      baseDir: agents/tester
      files:
        AGENTS.md: agents/tester/AGENTS.md
        SOUL.md: agents/tester/SOUL.md
        IDENTITY.md: agents/tester/IDENTITY.md

  - id: reviewer
    name: Reviewer
    role: analysis
    description: Reviews PRs, requests changes or approves.
    workspace:
      baseDir: agents/reviewer
      files:
        AGENTS.md: agents/reviewer/AGENTS.md
        SOUL.md: agents/reviewer/SOUL.md
        IDENTITY.md: agents/reviewer/IDENTITY.md

steps:
  - id: plan
    agent: planner
    input: |
      Decompose the following task into ordered user stories for autonomous execution.

      TASK:
      {{task}}

      Instructions:
      1. Explore the codebase to understand the stack, conventions, and patterns
      2. Break the task into small user stories (max 20)
      3. Order by dependency: schema/DB first, backend, frontend, integration
      4. Each story must fit in one developer session (one context window)
      5. Every acceptance criterion must be mechanically verifiable
      6. Always include "Typecheck passes" as the last criterion in every story
      7. Every story MUST include test criteria — "Tests for [feature] pass"
      8. The developer is expected to write tests as part of each story

      Reply with:
      STATUS: done
      REPO: /path/to/repo
      BRANCH: feature-branch-name
      STORIES_JSON: [ ... array of story objects ... ]
    expects: "STATUS: done"
    max_retries: 2
    on_fail:
      escalate_to: human

  - id: setup
    agent: setup
    input: |
      Prepare the development environment for this feature.

      TASK:
      {{task}}

      REPO: {{repo}}
      BRANCH: {{branch}}

      Instructions:
      1. cd into the repo
      2. Create the feature branch (git checkout -b {{branch}})
      3. Read package.json, CI config, test config to understand the build/test setup
      4. Run the build to establish a baseline
      5. Run the tests to establish a baseline
      6. Report what you found

      Reply with:
      STATUS: done
      BUILD_CMD: <build command>
      TEST_CMD: <test command>
      CI_NOTES: <brief CI notes>
      BASELINE: <baseline status>
    expects: "STATUS: done"
    max_retries: 2
    on_fail:
      escalate_to: human

  - id: implement
    agent: developer
    type: loop
    loop:
      over: stories
      completion: all_done
      fresh_session: true
      verify_each: true
      verify_step: verify
    input: |
      Implement the following user story. You are working on ONE story in a fresh session.

      TASK (overall):
      {{task}}

      REPO: {{repo}}
      BRANCH: {{branch}}
      BUILD_CMD: {{build_cmd}}
      TEST_CMD: {{test_cmd}}

      CURRENT STORY:
      {{current_story}}

      COMPLETED STORIES:
      {{completed_stories}}

      STORIES REMAINING: {{stories_remaining}}

      VERIFY FEEDBACK (if retrying):
      {{verify_feedback}}

      PROGRESS LOG:
      {{progress}}

      Instructions:
      1. Read progress.txt — especially the Codebase Patterns section
      2. Pull latest on the branch
      3. Implement this story only
      4. Write tests for this story's functionality
      5. Run typecheck / build
      6. Run tests to confirm they pass
      7. Commit: feat: {{current_story_id}} - {{current_story_title}}
      8. Append to progress.txt
      9. Update Codebase Patterns if you found reusable patterns

      Reply with:
      STATUS: done
      CHANGES: what you implemented
      TESTS: what tests you wrote
    expects: "STATUS: done"
    max_retries: 2
    on_fail:
      escalate_to: human

  - id: verify
    agent: verifier
    input: |
      Verify the developer's work on this story.

      TASK (overall):
      {{task}}

      REPO: {{repo}}
      BRANCH: {{branch}}
      CHANGES: {{changes}}
      TEST_CMD: {{test_cmd}}

      CURRENT STORY:
      {{current_story}}

      PROGRESS LOG:
      {{progress}}

      Check:
      1. Code exists (not just TODOs or placeholders)
      2. Each acceptance criterion for the story is met
      3. Tests were written for this story's functionality
      4. Tests pass (run {{test_cmd}})
      5. No obvious incomplete work
      6. Typecheck passes

      Reply with:
      STATUS: done
      VERIFIED: What you confirmed

      Or if incomplete:
      STATUS: retry
      ISSUES:
      - What's missing or incomplete
    expects: "STATUS: done"
    on_fail:
      retry_step: implement
      max_retries: 2
      on_exhausted:
        escalate_to: human

  - id: test
    agent: tester
    input: |
      Integration and E2E testing of the implementation.

      TASK:
      {{task}}

      REPO: {{repo}}
      BRANCH: {{branch}}
      CHANGES: {{changes}}
      BUILD_CMD: {{build_cmd}}
      TEST_CMD: {{test_cmd}}

      PROGRESS LOG:
      {{progress}}

      Your job (integration/E2E testing — unit tests were already written per-story):
      1. Run the full test suite ({{test_cmd}}) to confirm everything passes together
      2. Look for integration issues between stories
      3. If this is a UI feature, use agent-browser to test it end-to-end
      4. Check cross-cutting concerns: error handling, edge cases across features
      5. Verify the overall feature works as a cohesive whole

      Reply with:
      STATUS: done
      RESULTS: What you tested and the outcomes

      Or if issues found:
      STATUS: retry
      FAILURES:
      - Specific test failures or bugs found
    expects: "STATUS: done"
    on_fail:
      retry_step: implement
      max_retries: 2
      on_exhausted:
        escalate_to: human

  - id: pr
    agent: developer
    input: |
      Create a pull request for your changes.

      TASK:
      {{task}}

      REPO: {{repo}}
      BRANCH: {{branch}}
      CHANGES: {{changes}}
      RESULTS: {{results}}

      PROGRESS LOG:
      {{progress}}

      Create a PR with:
      - Clear title summarizing the change
      - Description explaining what and why
      - Reference to what was tested

      Use: gh pr create

      Reply with:
      STATUS: done
      PR: URL to the pull request
    expects: "STATUS: done"
    on_fail:
      escalate_to: human

  - id: review
    agent: reviewer
    input: |
      Review the pull request.

      PR: {{pr}}
      TASK: {{task}}
      CHANGES: {{changes}}

      PROGRESS LOG:
      {{progress}}

      Review for:
      - Code quality and clarity
      - Potential bugs or issues
      - Test coverage
      - Follows project conventions

      Use: gh pr view, gh pr diff

      If changes needed, add comments to the PR explaining what needs to change.

      Reply with:
      STATUS: done
      DECISION: approved

      Or if changes needed:
      STATUS: retry
      DECISION: changes_requested
      FEEDBACK:
      - What needs to change
    expects: "STATUS: done"
    on_fail:
      retry_step: implement
      max_retries: 3
      on_exhausted:
        escalate_to: human