AH
Ali Hasan
← Back to Agentic AI Architecture
Graph Compiler Task Breakdown Role: Technical Lead

split-plan

Deterministic Plan-to-GitHub Issue Graph Compiler

$ invoke_subagent('split-plan')
Trigger Scenarios (When Needed)
  • ✓ When converting an implementation plan (docs/plan/plan.md) into actionable GitHub issues.
  • ✓ When structuring project development into parallel, dependency-aware execution layers.
  • ✓ When decomposing complex engineering epics into small, verifiable sub-tasks (< 2 hours each).
  • ✓ When publishing structured issue tracking graphs to GitHub via automated CLI scripts.
Activation & Guardrails

Trigger: Activated when the user requests converting an implementation plan into trackable GitHub issues or a dependency DAG.

Execution Rules:
• Must verify docs/plan/plan.md exists before execution.
• Smart task grouping: coalesces related micro-tasks and splits issues exceeding 300 words.
• Generates domain-aware sub-tasks with UI specs, Mermaid ERDs, or API method contracts.
• Validates that the generated issue graph is strictly acyclic (DAG).
Example Prompt: "Convert docs/plan/plan.md into GitHub issues."
Technical Architecture & Data Contracts
Execution Pattern

Deterministic Graph Compiler & Topological DAG Leveling

Context Budget

Reads plan.md, generates individual issue files in docs/plan/issues/.

State Management

Outputs issues-graph.json containing nodes, edges, subtasks, and topological layers.

Input Contracts
docs/plan/plan.md (Master Plan) docs/plan/plan-graph.json (Optional Task Dependencies)
Output Contracts
docs/plan/issues/issue-[NNN].md (Granular Issue Files) docs/plan/issues/issues-graph.json (Topological DAG) docs/plan/issues/index.md (Summary Index with Mermaid DAG)
Bundled Scripts & Reference Resources

Automation Scripts

push_issues.py Python 3

Automates traversing issues-graph.json in topological layer order, publishing issues via GitHub CLI (gh), and writing back remote issue URLs and IDs.

scripts/push_issues.py

Reference Specifications (`references/`)

grouping-rules.md Grouping Heuristic

Rules for coalescing related tasks and splitting oversized descriptions into focused issues.

issue-template.md Issue Specification

Standardized GitHub issue schema containing intent, inputs, outputs, criteria, and test strategy.

sub-task-rules.md Decomposition Standard

Domain-specific sub-task generation rules covering UI/UX, database migrations, and APIs.

graph-structure.md Schema Specification

JSON schema for issues-graph.json and topological sorting algorithms.

index-template.md Index Template

Template for summary index table and visual Mermaid issue dependency chart.

Executive Overview

A high-level implementation plan without granular decomposition is prone to ambiguity. When autonomous agents or engineering teams attempt to execute oversized tasks, they frequently encounter deadlocks, missing contract definitions, or circular blockers.

split-plan is a deterministic graph compiler that translates architecture plans into an executable, acyclic GitHub Issue Dependency Graph (DAG).

4-Phase Compilation Pipeline

docs/plan/plan.md
       ↓
[Phase 1: Parsing]      --> Extracts Architecture, Tech Stack, and Task Matrix
       ↓
[Phase 2: Smart Group]  --> Coalesces micro-tasks, splits oversized tasks (>300 words)
       ↓
[Phase 3: Sub-Tasks]    --> Decomposes each issue into domain-aware specifications
       ↓
[Phase 4: DAG & Output] --> Computes topological layers and outputs issues-graph.json

1. Smart Grouping Heuristics

  • Coalescing: Tightly coupled operations (e.g., creating a TypeORM entity + database migration) are combined into a single cohesive issue.
  • Splitting: Any issue description exceeding 300 words or containing more than 5 distinct acceptance criteria is split into focused prerequisite issues.

2. Domain-Aware Sub-Task Decomposition

Every issue contains ordered, atomic sub-tasks sized for < 2 hours of work:

  • UI/UX Issues: Sub-tasks provide layout specs, component hierarchies, and trigger image generation tools to draft mockups for developer sign-off.
  • Database Issues: Sub-tasks define entity schemas, foreign keys, indexes, and generate Mermaid ERD diagrams for validation.
  • API Issues: Sub-tasks explicitly define HTTP verbs, endpoints, request/response DTOs, and RFC 9457 error contracts.

Topological Layering for Multi-Agent Execution

split-plan groups all generated issues into execution layers:

  • Layer 0 (Root Nodes): Issues with zero prerequisites (e.g., Docker environment, database connection module). These can be implemented concurrently by independent subagents.
  • Layer 1 (Direct Dependents): Issues depending strictly on Layer 0 components.
  • Layer N (Terminal Nodes): End-to-end integration tests, final builds, and deployment verification.
{
  "layers": [
    ["issue-001", "issue-002"],
    ["issue-003", "issue-004"],
    ["issue-005"]
  ]
}

Automation Script: push_issues.py

split-plan includes a dedicated Python automation utility:

  • Location: scripts/push_issues.py
  • Execution: python3 ~/.gemini/config/skills/split_plan/scripts/push_issues.py [owner/repo]
  • Mechanism: Authenticates against gh auth status, reads issues-graph.json, creates GitHub issues sequentially in topological order, and populates dependent issue descriptions with live Markdown links to their prerequisite GitHub issues.