Skip to content

Agent Pipeline Swimlane Diagram — Plan

Motivation

The current docs/agent.html uses the layered node-edge style from arch.html. That style suits static architecture (components in columns, data flowing between them), but the nightly agent is a conditional, looping process. The layered diagram loses the decision branches ("if tests fail → fix and skip to Stage 4"), the session loop, the 06:00 KST time gate, and the orchestrator-spawns-sub-agent hierarchy. A swimlane flowchart expresses all of these naturally and makes the pipeline readable at a glance.

Scope

In scope: - A generic self-contained swimlane flowchart HTML engine (dark GitHub theme, SVG-rendered) with support for: horizontal lanes (actors), rectangular process nodes, diamond decision nodes, loop-back arrows, and a time-gate/interrupt annotation - An agent pipeline flowchart (docs/agent-flow.html) built on that engine, covering the full 4-stage pipeline, 06:00 KST gate, session loop, and 7 specialist sub-agents - MkDocs nav entry ("Agent Flow") wired via iframe wrapper (docs/agent-flow.md)

Out of scope: - Replacing arch.html or the existing layered engine - Updating the /diagram command to support swimlane mode (separate task if needed) - Automated generation — this is hand-authored data, not code-extracted

Approach

Task 1 — Design the swimlane data model

Define const data for the swimlane engine. Proposed shape:

const data = {
  title: "Nightly Agent Pipeline",
  subtitle: "4-stage orchestrator loop · 06:00 KST cutoff",

  lanes: [
    { id: "launcher",      label: "Launcher",      color: "#22d3ee" },
    { id: "orchestrator",  label: "Orchestrator",  color: "#fbbf24" },
    { id: "specialists",   label: "Sub-Agents",    color: "#a78bfa" },
    { id: "git",           label: "Git / Artifacts", color: "#34d399" },
  ],

  nodes: [
    // process node
    { id: "start",   lane: "launcher",     type: "process",  label: "start-agent.ps1",    subtitle: "reads agent-prompt.md" },
    // decision node
    { id: "tests_ok", lane: "orchestrator", type: "decision", label: "tests pass?" },
    // terminal node
    { id: "stop",    lane: "launcher",     type: "terminal", label: "Stop (06:00 KST)" },
  ],

  edges: [
    { from: "start",    to: "time_gate",  label: "" },
    { from: "tests_ok", to: "stage1_fix", label: "no",  branch: "left"  },
    { from: "tests_ok", to: "stage2",     label: "yes", branch: "right" },
    // loop-back edge
    { from: "pause",    to: "time_gate",  label: "3 min pause", loop: true },
  ],
}

Nodes flow top-to-bottom within each lane. Decision diamonds have two outgoing edges (branch: "left" and branch: "right"). Loop edges curve back with a labeled arc.

Task 2 — Build the swimlane HTML engine

Create docs/agent-flow.html as a fully self-contained file (~600 lines):

  • SVG canvas with lane headers as column headers at the top
  • Nodes rendered as rectangles (process), diamonds (decision), or rounded pills (terminal)
  • Edges as straight or curved SVG paths with arrowheads; loop edges use a wide bezier
  • A sidebar panel showing a plain-English description for the currently hovered node
  • Dark GitHub theme (--bg: #0d1117) matching arch.html
  • Mobile-friendly: lanes collapse to a vertical stack below 768px

Reference docs/arch.html for the CSS variables and sidebar HTML structure.

Task 3 — Author the agent pipeline data

Populate const data with the full pipeline. Key nodes to include:

Lane Nodes
Launcher start-agent.ps1, 3-min pause loop, 06:00 KST gate (terminal)
Orchestrator read BACKLOG, Stage 1 (bug triage), Stage 2 (code review), Stage 3 (feature dev), Stage 4 (QA), Update Main, pre-delegation plan step
Specialists debugger, data-engineer, ml-analyst, frontend-engineer, devops-engineer, security-reviewer, test-engineer
Git / Artifacts main branch commit, agent/feat-* branch, BACKLOG.md update, agent-log.md, agent-log.html rebuild

Key decision nodes: - "tests pass?" → yes: check backlog bugs / no: spawn specialist - "backlog bug?" → yes: fix + Stage 4 / no: Stage 2 - "unreviewed branches?" → yes: review / no: Stage 3 - "06:00 KST?" → yes: stop / no: continue

Task 4 — Wire into MkDocs

  1. Add docs/agent-flow.md (iframe wrapper, same pattern as docs/diagram.md)
  2. Add nav entry to mkdocs.yml: ```yaml
  3. Agent Pipeline: agent-flow.md ```
  4. Keep docs/agent-diagram.md (layered view) under a separate nav entry or remove it — decision deferred until the swimlane is complete

Open Questions

(resolved)

  • Specialists: 7 individual nodes in the Sub-Agents lane — one per specialist.
  • Layered diagram: drop docs/agent.html and docs/agent-diagram.md when the swimlane is complete. Remove the "Agent Pipeline" nav entry from mkdocs.yml and replace it with "Agent Flow" pointing to the new docs/agent-flow.md wrapper.

Status

draft