Repository Planning Graph (RPG)

• Repository Planning Graph (RPG) is a unified, graph-based representation that encodes repository functionalities and file structures into a coherent blueprint.
• It enables scalable, interpretable codebase generation by mapping high-level capabilities to detailed implementation artifacts through layered graph semantics.
• It supports debugging, navigation, and targeted revisions by using explicit ordering and data-flow edges to manage complex dependencies.

A Repository Planning Graph (RPG) is a persistent, unified graph-based representation designed for scalable and interpretable codebase generation. It encodes functional and implementation-level planning—including capabilities, file structures, data-flow, and specific functions—within a connected blueprint, replacing the ambiguity of natural language with explicit structure. RPG provides a substrate on which software agents and LLMs can realize coherent, long-horizon planning and synthesis of software repositories, enabling stepwise refinement from broad specification to executable artifacts (Luo et al., 19 Sep 2025).

1. Theoretical Foundations and Motivation

RPG formalizes repository construction as a graph planning task, confronting a core bottleneck: LLMs excel at generating functions or files, but struggle to generate entire repositories due to the scale, complexity, and dependency structure involved (Luo et al., 19 Sep 2025). Free-form natural language planning—common in code generation workflows—is ill-suited for capturing cross-module dependencies, file layouts, and execution order, often yielding ambiguous or incomplete specifications. RPG addresses these deficits by representing both abstract capabilities and detailed implementation artifacts as graph nodes, with directed edges enforcing the topological and data-flow ordering required for correct, reproducible repository synthesis.

A defining principle is the persistence and reusability of the graph: RPG “remembers” explicit planning decisions, progressively refines them, and serves as both a design blueprint and navigation map during code generation, debugging, and localization. This concept synthesizes prior work on plan graphs in software engineering (Bairi et al., 2023), proposal-to-implementation graph transformations, and planning-based synthesis frameworks in repository-level code generation.

2. Graph Structure and Semantics

The RPG comprises a layered, heterogeneous graph whose nodes and edges are organized as follows:

• Nodes:
  • Root nodes correspond to major repository capabilities or functional categories (e.g., “algorithm”, “evaluation”, “data loader”).
  • Intermediate nodes represent concrete modules, files, or classes associated with each capability.
  • Leaf nodes define specific functions, classes, or interfaces.
• Edges:
  • Solid black lines encode hierarchical “contains” relations, mapping capabilities to modules, modules to files, etc.
  • Black arrows represent inter-module data-flows, specifying how the output of one component feeds into another.
  • Dashed gray arrows enforce intra-module file ordering or dependency constraints, ensuring correct local execution semantics.

This graph-based semantic encoding allows RPG to model both global execution semantics (e.g., end-to-end data-processing flows) and fine-grained local sequencing (e.g., file layout, function invocation order). The topological ordering specified by the graph is critical for scalable code generation, as it allows downstream LLMs or code agents to traverse and synthesize artifacts consistently, respecting interdependencies and modularity.

3. RPG-Driven Repository Generation: The ZeroRepo Framework

ZeroRepo is an instantiation of RPG-driven repository generation. Its process unfolds in three stages (Luo et al., 19 Sep 2025):

1. Proposal-Level Planning:
   • High-level user specification or prompt is mapped to a “functionality graph” using an ontology of ~1.5M software capabilities (“Feature Tree”).
   • An explore–exploit strategy is used to retrieve, refine, and regroup relevant capability nodes into cohesive modules, forming the initial RPG skeleton.
2. Implementation-Level Refinement:
   • The graph is augmented to encode file structures, including folder layouts, file hierarchy, and interconnections.
   • Data-flow edges are added, mapping module outputs and inputs, producing the complete RPG that captures both capability coverage and implementation detail.
3. Graph-Guided Code Generation and Validation:
   • Code is generated in topological order outlined by the RPG, traversing from root capabilities through modules and down to leaf functions.
   • At each node (typically corresponding to a function or class), test-driven development (TDD) is employed. Tests (unit or integration) derived from the graph or user input validate the artifact; on test failure, graph-guided localization provides precise revision targets.
   • This produces repositories that scale near-linearly in functionality, support modular composition, and enable sophisticated iterative refinement.

The test validation and graph-guided editing mechanism ensure reliability and coherence during repository synthesis, utilizing the RPG’s explicit structure to achieve targeted modifications.

4. Benchmarks, Empirical Results, and Scaling Behavior

RPG and ZeroRepo were evaluated on RepoCraft, a benchmark aggregating six real-world repositories (including scikit-learn, pandas, sympy, statsmodels, requests, django), totaling 1,052 tasks (Luo et al., 19 Sep 2025). Key empirical findings include:

• Repository Size: ZeroRepo generates repositories averaging nearly 36K lines of code (~3.9× larger than Claude Code, ~64× larger than typical baselines).
• Functional Coverage: Achieves 81.5% coverage over intended capability categories, reflecting near-complete mapping of specification to implementation.
• Test Pass Rate: Attains a 69.7% pass rate on integrated/adapted tests—outperforming Claude Code by +27.3 and +35.8 percentage points on coverage and validation, respectively.
• Scaling: RPG enables near-linear scaling of planning sophistication, allowing increasingly complex codebases to be handled without exponential planning overhead.

These results indicate that RPG-driven planning not only enhances the scale and reliability of repository generation, but also enables more precise coverage and functional integration compared to prior approaches dependent on natural language or list-based planning.

5. Role in Agent Localization, Debugging, and Repository Navigation

RPG’s explicit mapping of functionalities, artifacts, and dependencies improves agent localization—the process by which code synthesis agents identify relevant modules for debugging, extension, or maintenance (Luo et al., 19 Sep 2025). The graph’s interpretable structure supports:

• Debugging: Directed edges map error propagation routes; test nodes link directly to implementation targets, enabling agents to localize and revise problematic components.
• Navigation: High-level nodes serve as entry points for traversal, with edges delineating module-to-file-to-function routes, improving navigation efficiency for both automated agents and human collaborators.
• Modification: Fine-grained ordering and data-flow edges facilitate targeted refinements—agents can isolate, replace, or extend functionality by updating corresponding graph segments.

This property substantially accelerates repository-level automation, error localization, and collaborative agent workflows.

6. Broader Impacts, Limitations, and Prospective Developments

RPG establishes a robust and interpretable foundation for scalable codebase synthesis. By replacing informal specification documents with explicit, modular blueprints, RPG reduces ambiguity, mitigates planning error, and supports systematic, modular development (Luo et al., 19 Sep 2025). Plausible implications include:

• Accelerated agent-driven repository generation for standard and bespoke software projects.
• Enhanced collaborative engineering, where new practices treat RPGs as living design artifacts alongside documentation.
• Facilitated adaptation across programming ecosystems, owing to the language-agnostic, capability-centric segmentation of the RPG model.

Limitations arise mainly from:

• Reliance on accurate mapping from high-level intent to functional nodes—misclassification early in the planning process may propagate errors downstream; thus, quality of initial capability extraction is critical.
• Requirement for comprehensive Feature Trees and ontologies for domain-specific planning; resource-intensive to maintain and expand.
• The scaling behavior, while empirically near-linear, may depend on specific implementation optimizations and graph traversal algorithms.

Future research may investigate improved automatic mapping between user intent and graph construction, enhanced ontology coverage, dynamic updating of RPGs as codebases evolve, and integration with more advanced data-flow analysis or agent collaboration frameworks.

7. Relationship to Related Graph-Based Planning Concepts

RPG draws on and extends graph-based methodologies that have shown prominence in repository-level automation and planning, including:

• Plan graphs for code editing and refactoring (Bairi et al., 2023), which inform the dynamic updating and change propagation aspects of RPG nodes and edges.
• Repository-level code graphs (Ouyang et al., 3 Oct 2024) and hierarchical code graphs (Wang et al., 7 Sep 2025), which focus on low-level structural context and dependency mapping.
• Code context graphs for retrieval and completion (Liu et al., 11 Jun 2024), which provide subgraph extraction methods relevant for local planning and artifact generation.

A key distinction is RPG’s explicit unification of proposal and implementation levels within a persistent blueprint, supporting scalable, topologically ordered planning and refinement from functional requirements to syntactic code artifacts.

---

In summary, the Repository Planning Graph (RPG) is a foundational, persistent, and interpretable representation for unifying all aspects of repository-level planning and generation. Its layered graph structure enables scalable, reliable, and incrementally verifiable codebase synthesis, supports agent localization and collaborative workflows, and markedly improves coverage and correctness in benchmark evaluations. RPG thus defines a new standard for planning-driven automation and modular software generation in contemporary AI-guided development practices (Luo et al., 19 Sep 2025).