4-Phase Coding Pipeline

Overview

Rune's execution model is a 4-phase sequential pipeline. Phases 2 and 3 run as parallel swarms; phases 1 and 4 run single-agent. Within each phase, a generate-execute-reflect loop iterates until tests pass or max attempts are reached. Each phase is driven by a Jinja2 template, optionally enhanced by a hypernetwork-generated LoRA adapter.

For swarm orchestration details, see Swarm Architecture. For adapter storage, see Adapter Storage.

Pipeline Architecture

flowchart LR
    Task([Task]) --> P1[Phase 1: DECOMPOSE\nsingle agent]
    P1 --> P2[Phase 2: PLAN\nparallel swarm]
    P2 --> P3[Phase 3: CODE\nparallel swarm + retries]
    P3 --> P4[Phase 4: INTEGRATE\nsingle agent]
    P4 --> Done([Integrated Code\n+ Adapters])

Phase Details

Phase 1: DECOMPOSE (single agent)

Field Description
Template decompose.j2 (trajectory), prompt_decompose.j2 (prompt)
Input Project specification
Output List of subtasks
Adapter decompose_adapter (if available)

Breaks a project specification into discrete subtasks. Runs once with the base model (+ optional adapter).

Phase 2: PLAN (parallel swarm)

Field Description
Template plan.j2 (trajectory), prompt_plan.j2 (prompt)
Input Project spec + one subtask per agent
Output Architecture plan per subtask
Adapter plan_adapter (if available)

Each subtask is assigned to a swarm agent. All agents run in parallel. Each produces an architecture plan for its subtask.

Phase 3: CODE (parallel swarm + retries)

Field Description
Template code.j2 (first attempt), code_retry.j2 (retries)
Input Subtask + plan + prior code skeleton
Output Working code per subtask
Adapter code_adapter (if available), refreshed via H() between iterations

The retry template (code_retry.j2) includes error summaries and attempt history. Between iterations, the hypernetwork H() can generate a fresh adapter from the accumulated trajectory. This is the primary phase where the recursive loop operates.

Phase 4: INTEGRATE (single agent)

Field Description
Template integrate.j2 (trajectory), prompt_integrate.j2 (prompt)
Input Project spec + all code outputs from Phase 3
Output Final integrated codebase
Adapter integrate_adapter (if available)

Merges all subtask code outputs into a coherent final codebase.

Per-Phase Iteration

Each phase runs up to N iterations (configurable per phase via environment variables):

Variable Scope
RUNE_MAX_PHASE_ITERATIONS Global default for all phases
RUNE_MAX_ITERATIONS_DECOMPOSE Phase 1 override
RUNE_MAX_ITERATIONS_PLAN Phase 2 override
RUNE_MAX_ITERATIONS_CODE Phase 3 override
RUNE_MAX_ITERATIONS_INTEGRATE Phase 4 override

CLI flag --max-phase-iterations overrides the global env var. Hardcoded fallback is 5.

Within each iteration: 1. Render the Jinja2 trajectory template with current state 2. Optionally generate/refresh adapter via hypernetwork H() 3. Run inference (base model + adapter) to produce output 4. Execute output in sandbox, evaluate results 5. Score fitness; if passing or max iterations reached, stop

Template System

All phase instructions flow through Jinja2 templates in libs/shared/src/shared/templates/:

Template Phase Purpose
decompose.j2 1 Trajectory context for decomposition
prompt_decompose.j2 1 Model prompt for decomposition
plan.j2 2 Trajectory context for planning
prompt_plan.j2 2 Model prompt for planning
code.j2 3 Trajectory context for first code attempt
code_retry.j2 3 Trajectory context for retry (includes errors, history)
prompt_code.j2 3 Model prompt for code generation
integrate.j2 4 Trajectory context for integration
prompt_integrate.j2 4 Model prompt for integration

Templates are rendered via shared.template_loader.render_trajectory() and render_prompt().

Sandbox

Code execution uses shared.sandbox.SubprocessBackend — a subprocess-based sandbox with configurable timeout. The sandbox runs agent-generated code in isolation and captures stdout, stderr, and exit code.

Trajectory Schema

The trajectory flowing through the pipeline maps to CodingSession from shared.rune_models:

Field Type Description
session_id str Unique session identifier
task_description str Human-readable task description
task_type str Task category (e.g. 'bug-fix', 'feature-impl')
adapter_refs list[AdapterRef] Adapters loaded during this session
attempt_count int Number of generate-execute-reflect cycles
outcome str or None 'success', 'exhausted', or None if in progress

Integration Points

  • Adapter Registry (Adapter Storage): Queried at phase start for adapter selection; written to after adapter generation
  • Inference Providers (libs/inference): TransformersProvider, LlamaCppProvider, OllamaProvider, or VLLMProvider — selected via factory
  • Sandbox (shared.sandbox.SubprocessBackend): Executes generated code
  • Hypernetwork (model_training.hypernetwork.DocToLoraHypernetwork): Generates adapters from trajectories
  • Swarm (scripts/swarm.py): Orchestrates parallel execution of Phases 2 and 3