# Workflow Between swe_architect and swe_developer Nodes in LangGraph

> Discover the swe_architect and swe_developer workflow uniting research and execution in LangGraph. Learn how an ImplementationPlan drives file creation and diff application.

- Repository: [LangTalks/swe-agent](https://github.com/langtalks/swe-agent)
- Tags: internals
- Published: 2026-03-05

---

**The `swe_architect` node researches the problem and produces an `ImplementationPlan`, then passes it via shared state to the `swe_developer` node, which executes the plan by creating files and applying diffs in a linear LangGraph pipeline.**

The **swe-agent** repository implements a sophisticated software engineering agent using **LangGraph** to orchestrate a two-phase workflow. The system separates architectural research from code implementation by splitting responsibilities across two primary nodes—`swe_architect` and `swe_developer`—that communicate through a shared `AgentState`. This architecture enables a research-first approach where the architect validates hypotheses before the developer writes any code.

## Top-Level Graph Orchestration

The entry point for the entire agent workflow resides in **[`agent/graph.py`](https://github.com/langtalks/swe-agent/blob/main/agent/graph.py)**, which defines a minimal orchestration layer connecting the two specialized sub-graphs. The top-level graph contains exactly three edges that enforce a strict sequential execution:

```python

# agent/graph.py

graph_builder.add_edge(START, "swe_architect")            # Kick off research phase

graph_builder.add_edge("swe_architect", "swe_developer")  # Hand off to implementation

graph_builder.add_edge("swe_developer", END)              # Terminate when done

```

This linear topology ensures that control flows unidirectionally from the architect to the developer without any loops or conditional branches at the top level. The `swe_architect` node actually encapsulates a complete sub-graph defined in [`agent/architect/graph.py`](https://github.com/langtalks/swe-agent/blob/main/agent/architect/graph.py), while `swe_developer` wraps the implementation logic found in [`agent/developer/graph.py`](https://github.com/langtalks/swe-agent/blob/main/agent/developer/graph.py).

## How the Architect Sub-Graph Produces the Implementation Plan

The architect sub-graph handles the **research phase** through a sophisticated internal workflow defined in **[`agent/architect/graph.py`](https://github.com/langtalks/swe-agent/blob/main/agent/architect/graph.py)**. This sub-graph executes multiple research iterations before finalizing its output:

- **`come_up_with_research_next_step`** – Determines what information to gather next
- **`conduct_research`** – Executes tool calls to explore the codebase
- **`check_research_step`** – Validates the findings from each iteration
- **`extract_implementation_plan`** – Compiles the research into a structured `ImplementationPlan`

The critical hand-off occurs when the `extract_implementation_plan` node writes to the shared state and terminates the sub-graph:

```python

# agent/architect/graph.py

workflow.add_edge("extract_implementation_plan", END)

```

When this sub-graph returns, the compiled `implementation_plan` object resides in the shared `AgentState`, making it immediately available to the next node in the top-level graph.

## How the Developer Sub-Graph Consumes the Plan

Once the top-level graph transitions from `swe_architect` to `swe_developer`, control enters the implementation phase defined in **[`agent/developer/graph.py`](https://github.com/langtalks/swe-agent/blob/main/agent/developer/graph.py)**. The developer sub-graph begins by preparing the environment and loading the architectural blueprint:

```python

# agent/developer/graph.py

workflow.add_edge(START, "start_implementing")
workflow.add_edge("start_implementing", "prepare_for_implementation")

```

The **`prepare_for_implementation`** node retrieves the `implementation_plan` from state, then passes it to **`get_clear_implementation_plan_for_atomic_task`**, which breaks the plan into discrete, executable tasks. The developer iterates through these atomic tasks using a conditional edge that checks completion status:

```python
workflow.add_conditional_edges(
    "proceed_to_next_atomic_task",
    is_implementation_complete,
    {"continue": "prepare_for_implementation", END: END}
)

```

During execution, the developer may invoke **`research_tool_node`** for clarifications, but primarily focuses on **`creating_diffs_for_task`** to modify files according to the architect's specifications.

## Data Flow and Shared State

Both sub-graphs operate on the same **AgentState** model, enabling seamless data transfer without explicit serialization. The workflow relies on two key state fields:

- **`implementation_research_scratchpad`** – Populated exclusively by the architect during research iterations; contains intermediate hypotheses and validation results
- **`implementation_plan`** – Produced by the architect's `extract_implementation_plan` node and consumed by the developer's `prepare_for_implementation` node

Because LangGraph maintains state persistence across node boundaries, the developer receives the complete research context and structured plan automatically when the architect sub-graph terminates.

## Complete Execution Flow

The complete workflow follows this deterministic path:

```

START
  ↓
swe_architect  (agent/architect/graph.py)
  ├── Research iteration loop
  ├── Validation checks
  └── Extract implementation_plan
  ↓
swe_developer  (agent/developer/graph.py)
  ├── Load implementation_plan
  ├── Iterate atomic tasks
  ├── Create diffs / new files
  └── Verify completion
  ↓
END

```

This architecture enforces a **separation of concerns** where the architect cannot modify files and the developer cannot alter the plan, reducing the risk of speculative coding without proper research.

## Practical Code Examples

### Running the Complete Agent

To execute the full workflow between architect and developer nodes:

```python
from agent.graph import swe_agent, AgentState

# Initialize state with empty plan

initial_state = AgentState(
    implementation_research_scratchpad=[],
    implementation_plan=None,
)

# Execute through both nodes automatically

result = swe_agent.invoke(initial_state)

print("Completed plan:", result.get("implementation_plan"))
print("Files modified:", result.get("file_changes", []))

```

This invocation triggers the sequential execution: first the entire architect sub-graph populates the `implementation_plan`, then the developer sub-graph consumes it to modify the codebase.

### Visualizing the Node Connections

For debugging the hand-off between nodes:

```python
from langgraph.debug import visualize

# Display the three-layer graph structure

visualize(swe_agent)

```

The visualization reveals the top-level linear flow connecting `swe_architect` to `swe_developer`, alongside the internal complexity of each sub-graph.

## Summary

- **Linear orchestration**: The top-level graph in [`agent/graph.py`](https://github.com/langtalks/swe-agent/blob/main/agent/graph.py) enforces a strict `START` → `swe_architect` → `swe_developer` → `END` sequence with no conditional logic
- **Sub-graph encapsulation**: Each primary node wraps a complex internal graph—architect handles research, developer handles implementation
- **State-based hand-off**: The architect produces an `implementation_plan` written to shared `AgentState`, which the developer reads via `prepare_for_implementation`
- **Research-first pipeline**: The workflow prevents code generation until the architect validates the approach through iterative research steps
- **Atomic task execution**: The developer breaks the architectural plan into discrete units, looping through `proceed_to_next_atomic_task` until completion

## Frequently Asked Questions

### What triggers the transition from swe_architect to swe_developer?

The transition occurs automatically when the architect sub-graph reaches its local `END` node after `extract_implementation_plan` completes. The top-level edge definition `graph_builder.add_edge("swe_architect", "swe_developer")` in [`agent/graph.py`](https://github.com/langtalks/swe-agent/blob/main/agent/graph.py) ensures the developer node receives control immediately upon the architect's completion.

### Can the developer modify the implementation plan created by the architect?

No, the developer sub-graph treats the `implementation_plan` as read-only input. While the developer can append to the `implementation_research_scratchpad` during tool calls, the core plan structure produced by the architect remains immutable during the implementation phase, ensuring architectural consistency.

### How does the developer handle incomplete or unclear plans?

The developer sub-graph includes the `get_clear_implementation_plan_for_atomic_task` node specifically to resolve ambiguities. If the plan lacks detail for a specific atomic task, this node can invoke `research_tool_node` to query the codebase or documentation before proceeding with file modifications, effectively creating a feedback loop within the implementation phase without returning to the architect.

### What happens if the developer fails to implement a task?

The conditional edge `is_implementation_complete` in [`agent/developer/graph.py`](https://github.com/langtalks/swe-agent/blob/main/agent/developer/graph.py) evaluates whether the current atomic task succeeded. If implementation fails, the sub-graph can loop back to `prepare_for_implementation` for retry logic, or if unrecoverable errors occur, the node terminates the entire agent run via the `END` path, returning the current state for debugging.