Workflow Between swe_architect and swe_developer Nodes in LangGraph

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, 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:

# 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, while swe_developer wraps the implementation logic found in 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. 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:

# 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. The developer sub-graph begins by preparing the environment and loading the architectural blueprint:

# 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:

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:

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:

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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}