Dev-E Execution Flow¶

From Dev-E's perspective, the world is simple: messages arrive on a queue, you do the work, you create a PR. If feedback comes, you fix it.

First Assignment — New Issue¶

flowchart TD
    A[Message arrives on Valkey stream] --> B[Read assignment]
    B --> C[Clear KEDA signal]
    C --> D[Create execution log]
    D --> E[Refresh GitHub token]
    E --> F[Spawn Claude CLI]

    F --> G[Turn 1: Read issue on GitHub]
    G --> H[Turn 2: Clone repo + create branch]
    H --> I[Turn 3: Read existing code]
    I --> J[Turn 4-N: Implement changes]
    J --> K{Tests pass?}
    K -->|No| L[Turn N+1: Fix tests]
    L --> K
    K -->|Yes| M[Turn N+2: git commit + push]
    M --> N[Turn N+3: gh pr create]
    N --> O[CLI exits with JSON result]

    O --> P[Stream consumer captures:<br/>cost, turns, tokens, session_id]
    P --> Q[Save session_id to Valkey<br/>key: session:repo#issue<br/>TTL: 7 days]
    Q --> R[Update execution log]
    R --> S[ACK message from stream]
    S --> T[Wait for next message...]

    style A fill:#38bdf8
    style N fill:#4ade80
    style Q fill:#fbbf24

What is a "Turn"?¶

Each turn is one round-trip with the AI model:

flowchart LR
    A[Claude thinks] --> B[Decides action]
    B --> C[Calls a tool<br/>Read file / Edit / Bash / etc.]
    C --> D[Gets tool result]
    D --> E[Next turn]

    style A fill:#a78bfa
    style C fill:#38bdf8

Example for a simple README change (10-14 turns):

Turn	What happens	Tool used
1	Read the GitHub issue	Bash: `gh issue view 123`
2	Clone the repo	Bash: `git clone ...`
3	Create feature branch	Bash: `git checkout -b feat/...`
4	Read existing README	Read: `README.md`
5	Read CLAUDE.md for conventions	Read: `CLAUDE.md`
6	Read AGENTS.md for workflow	Read: `AGENTS.md`
7	Edit the file	Edit: `README.md`
8	Verify the edit	Read: `README.md`
9	Stage and commit	Bash: `git add && git commit`
10	Push	Bash: `git push -u origin HEAD`
11	Create PR	Bash: `gh pr create --body "Closes #123"`
12	Verify PR created	Bash: `gh pr view`

More complex tasks use more turns. A feature implementation might take 30-50 turns. Each turn costs tokens (input + output). Total cost = sum of all turns.

Second Assignment — Changes Requested¶

When Review-E requests changes, a new message arrives on the same stream. Dev-E gets the review feedback as the assignment body.

flowchart TD
    A[Message arrives: changes_requested] --> B[Read assignment with review feedback]
    B --> C[Check Valkey for session_id<br/>key: session:repo#issue]

    C -->|Session found| D[Resume CLI with --resume session_id]
    C -->|No session / stale| E[Start fresh CLI]

    D --> F[Turn 1: Read review comments]
    E --> F
    F --> G[Turn 2: Clone repo + checkout existing branch]
    G --> H[Turn 3-N: Fix the issues]
    H --> I[Turn N+1: git commit + push]
    I --> J[CLI exits]

    J --> K[Save new session_id to Valkey]
    K --> L[ACK message]
    L --> M[Wait for next message...]

    style A fill:#f87171
    style D fill:#fbbf24
    style K fill:#fbbf24

Session Resumption¶

The session_id lets Claude CLI resume its conversation context — it remembers what it did last time. This means:

With session: "I already know this repo, the branch, what I changed. Let me read the review and fix it." (~5 turns)
Without session: "Let me clone the repo, read the code, understand the PR, read the review, fix it." (~15 turns)

Sessions are stored in Valkey with a 7-day TTL. They're cleared when: - The pod restarts (session file on disk is lost) - The --resume flag fails (stale session → cleared and retried fresh) - TTL expires (7 days)

Important: KEDA scales pods to zero between assignments. Session files are on the pod's ephemeral disk and are lost. The session_id in Valkey points to a file that no longer exists. The retry logic handles this:

flowchart TD
    A[Try --resume session_id] -->|CLI exits 1| B[Session file not found]
    B --> C[Clear session from Valkey]
    C --> D[Wait 60s if auth error]
    D --> E[Retry fresh without --resume]
    E --> F[Works — new session_id saved]

    style B fill:#f87171
    style F fill:#4ade80

Error Handling¶

flowchart TD
    A[CLI returns] --> B{is_error?}

    B -->|No| C[Extract cost, turns, tokens]
    C --> D[Save session + ACK]

    B -->|Yes| E{Error type?}
    E -->|Invalid API key| F[Wait 60s]
    F --> G[Retry fresh]
    E -->|Stale session| H[Clear session]
    H --> G
    E -->|Other| I[Log failure]
    I --> J[Don't ACK — retry later]

    G --> K{Retry succeeds?}
    K -->|Yes| C
    K -->|No| J

    style D fill:#4ade80
    style J fill:#f87171
    style F fill:#fbbf24

What Dev-E Doesn't Know¶

Dev-E is a pure worker. It doesn't know about:

Conductor-E — just a queue it reads from
Review-E — just feedback that arrives as a new message
KEDA — doesn't know it gets scaled up/down
MergeGate — doesn't know about merge conditions
Other agents — doesn't coordinate with anyone

It reads a message, does the work, creates a PR, saves its session. That's it.