Sequence Diagram · Agentic Software Engineering

Spec-to-Merge Multi-Agent Coding Workflow

A multi-agent software-delivery sequence where a lead coding agent decomposes work across isolated specialist agents, integrates their outputs, runs independent review and CI, and hands a validated pull request back to an engineer for merge.

Open presentation

A new local copy, ready to customize. No signup required.

Modern coding agents can progress concurrently on bounded independent tasks. A lead agent retrieves repository context, agrees shared contracts and file ownership, and coordinates isolated API, UI and test worktrees. It then integrates their outputs into one candidate revision before independent code and security reviewers inspect the actual diff. Deterministic CI validates that same revision. Findings return to the smallest responsible scope for up to two targeted remediation cycles, followed by integration and revalidation; unresolved risk escalates to the engineer. Agents prepare a review-ready pull request only when required gates pass. The human engineer reviews and decides whether to merge. This workflow does not grant unlimited autonomous change authority or include automatic production deployment.

Technologies: Coding Agents, Git Worktrees, Source Control, CI/CD, Pull Requests, Automated Testing
Tags: Multi-Agent Coding, Coding Agents, Agentic Engineering, Software Delivery, Parallel Agents, Code Review, Security Review, CI/CD, Human-in-the-Loop, Git Worktrees, AI Engineering

How the flow works

An engineer provides a feature request, constraints and acceptance criteria.
The lead coding agent inspects repository context and decomposes the change into bounded workstreams.
API, UI and test agents work in parallel using isolated scopes/worktrees.
The lead agent integrates the completed work into one candidate change.
Independent code-review and security-review agents inspect the integrated candidate while CI runs deterministic validation.
Failed checks trigger targeted remediation and revalidation.
When all gates pass, the lead agent prepares a review-ready pull request.
The engineer reviews and decides whether to merge.

Why parallel agents help

Independent workstreams can progress concurrently.
Specialist contexts stay smaller and more focused.
Tests can be authored independently from implementation.
Review can be separated from implementation bias.
Large tasks can be decomposed without forcing one agent to retain the entire working context.

Where parallelism becomes dangerous

Independent review matters

The implementing agent's explanation is not enough. Independent reviewers inspect the actual integrated diff and repository state, checking code correctness, architectural boundaries, regression risk, security impact and unnecessary scope. Code and security reviewers have responsibilities separate from the implementation agents. Review evidence applies to the inspected revision; a later patch requires revalidation.

Deterministic gates still matter

Linting.
Type checking.
Unit and integration tests.
Build verification.
Security and dependency checks.
Repository policy checks.
These deterministic checks should not be replaced simply by another model saying “looks good.”

Bounded remediation

Route each finding to the smallest responsible scope instead of restarting the whole swarm. The illustrated API specialist stands for the responsible owner; UI or test findings should go to their respective agents. Patch in isolation, run focused checks, reintegrate, then revalidate code review, security review and CI against the updated candidate. Stop when all gates pass, cap remediation at two iterations, and escalate unresolved risk to a human. The merge gate stays closed until the required evidence passes.

Ideas for your remix

Add a database migration agent.
Add a documentation agent.
Replace API/UI agents with domain-specific agents.
Add an architecture-review agent.
Add performance testing.
Add staging deployment/canary validation.
Add release-management approval.
Model incident-driven hotfix delivery.
Adapt the flow to large-scale modernization or legacy migration.
Replace generic Git/CI systems with GitHub, GitLab, Azure DevOps, or another platform.

Architecture source

aal sequence "0.1" dictionary "0.1.0"

interaction SpecToMerge "Spec-to-Merge Multi-Agent Coding Workflow" {
    participant Engineer "Engineer" {
        type actor
        description "Human engineer who provides the change objective, reviews the final pull request and retains merge authority."
        technology "Human"
        icon "/deployment-icons/generic/person.svg"
    }
    participant WorkItem "Work Item / Issue Tracker" {
        type system
        description "Source of the engineering request, acceptance criteria, constraints and business context."
        technology "Issue / Work Management"
        icon "/deployment-icons/generic/application.svg"
    }
    participant Lead "Lead Coding Agent" {
        type service
        description "Coordinates planning, bounded task decomposition, agent assignment, integration, review routing and remediation."
        technology "Coding Agent Runtime"
        icon "/deployment-icons/generic/component.svg"
    }
    participant Context "Repository Context Service" {
        type service
        description "Provides repository instructions, architecture context, relevant files, dependency information and change scope."
        technology "Repository / Context Retrieval"
        icon "/deployment-icons/generic/data.svg"
    }
    participant ApiAgent "API Agent" {
        type service
        description "Implements server-side/API changes within an assigned bounded scope."
        technology "Coding Agent"
        icon "/deployment-icons/generic/integration.svg"
    }
    participant UiAgent "UI Agent" {
        type service
        description "Implements frontend/UI changes within an assigned bounded scope."
        technology "Coding Agent"
        icon "/deployment-icons/generic/application.svg"
    }
    participant TestAgent "Test Agent" {
        type service
        description "Builds or updates tests independently against the expected behavior and acceptance criteria."
        technology "Testing Agent"
        icon "/deployment-icons/generic/component.svg"
    }
    participant CodeReviewer "Code Reviewer Agent" {
        type service
        description "Independently reviews correctness, architecture boundaries, maintainability, regression risk, repository conventions and unnecessary scope."
        technology "Review Agent"
        icon "/deployment-icons/generic/component.svg"
    }
    participant SecurityReviewer "Security Reviewer Agent" {
        type service
        description "Independently reviews authentication, authorization, secrets, injection risk, dependencies and privilege boundaries."
        technology "Security Review Agent"
        icon "/deployment-icons/generic/component.svg"
    }
    participant Git "Git / Worktree Service" {
        type system
        description "Provides isolated working trees/branches and preserves separation between parallel agent workstreams."
        technology "Git / Worktrees"
        icon "/deployment-icons/generic/compute.svg"
    }
    participant CI "CI Pipeline" {
        type service
        description "Runs deterministic validation such as linting, type checking, tests, build and security checks."
        technology "CI/CD"
        icon "/deployment-icons/generic/compute.svg"
    }
    participant MergeGate "Pull Request / Merge Gate" {
        type system
        description "Collects the integrated candidate change, review evidence and CI status for human approval and merge."
        technology "Source Control / Pull Request"
        icon "/deployment-icons/generic/application.svg"
    }
    group HumanControl "Human Control" {
        participants [Engineer, WorkItem]
        type "Human & Work Control"
        icon "glyph/app-window"
    }
    group Orchestration "Agent Orchestration" {
        participants [Lead, Context]
        type "Agent Orchestration"
        icon "glyph/group"
    }
    group EngineeringAgents "Parallel Engineering Agents" {
        participants [ApiAgent, UiAgent, TestAgent]
        type "Parallel Engineering"
        icon "technology/codex"
    }
    group Quality "Independent Quality" {
        participants [CodeReviewer, SecurityReviewer]
        type "Independent Quality"
        icon "brand/claudecode"
    }
    group Platform "Engineering Platform" {
        participants [Git, CI, MergeGate]
        type "Engineering Platform"
        icon "brand/git"
    }
    sequence Delivery "Deliver Feature with Parallel Coding Agents" {
        participants [Engineer, WorkItem, Lead, Context, CodeReviewer, SecurityReviewer, Git, CI, MergeGate]
        message L1_Request Engineer -> WorkItem sync "Define feature and acceptance criteria"
        message L1_Assign Engineer -> Lead async "Deliver scoped feature" {
            protocol "Agent task"
        }
        activate L1_Planning Lead
        message L1_ReadIssue Lead -> WorkItem sync "Read intent, constraints and acceptance criteria"
        message L1_Context Lead -> Context sync "Inspect repository instructions and architecture" {
            protocol "Repository API"
        }
        message L1_Decompose Lead -> Lead sync "Bound scopes and agree shared contracts"
        deactivate L1_Planned L1_Planning
        message L1_Implement Lead -> Git sync "Execute implementation plan" {
            detail Implementation
            description "Coordinate API, UI and independently authored tests in separate worktrees. Agree shared interfaces and file ownership before parallel edits."
        }
        activate L1_Integration Lead
        message L1_Integrate Lead -> Git sync "Integrate candidate change" {
            protocol "Git"
            description "Assemble one candidate commit; resolve cross-workstream conflicts and contract compatibility before review."
        }
        note L1_IntegrationNote over [Lead, Git] "Integration is deliberate; parallel outputs are not assumed compatible."
        deactivate L1_Integrated L1_Integration
        message L1_Validate Lead -> CI sync "Validate integrated change" {
            detail Validation
            description "Independent reviewers and deterministic CI inspect the same integrated revision; bounded remediation is owned by the quality failure path."
        }
        fragment L1_QualityGate alt "Quality outcome" {
            branch L1_Ready "reviews and CI pass" {
                message L1_CreatePr Lead -> MergeGate sync "Create review-ready pull request" {
                    protocol "Pull Request"
                    description "Attach candidate commit, review evidence and passing CI status. Agents do not merge."
                }
                message L1_Present MergeGate -> Engineer async "Present validated change"
                fragment L1_HumanDecision alt "Human merge decision" {
                    branch L1_Approved "approved" {
                        message L1_Merge Engineer -> MergeGate sync "Approve and merge" {
                            protocol "Pull Request"
                        }
                    }
                    branch L1_Changes "needs changes" {
                        message L1_Feedback Engineer -> Lead async "Human review feedback" {
                            description "Return to a newly bounded task with explicit human direction; do not merge this candidate."
                        }
                    }
                }
            }
            branch L1_Blocked "finding or CI failure remains" {
                message L1_Escalate Lead -> Engineer async "Escalate unresolved risk; hold merge"
                note L1_Hold over [Engineer, Lead] "No review-ready PR or merge while required gates remain unresolved."
            }
        }
        note L1_Authority over [Engineer, MergeGate] "Agents prepare and validate the change; the engineer retains authority over what ships."
    }
    sequence Implementation "Parallel Implementation" {
        participants [Lead, Context, ApiAgent, UiAgent, TestAgent, Git]
        note L2_ScopeNote over [Lead, ApiAgent, UiAgent, TestAgent] "Parallelize independent work; coordinate shared files and contracts explicitly."
        fragment L2_ParallelWork par "Isolated engineering workstreams" {
            branch L2_ApiBranch "API implementation" {
                message L2_ApiWorktree Lead -> Git sync "Create isolated API worktree" {
                    protocol "Git"
                    description "Distinct API branch/worktree with assigned file ownership; shared contracts require coordination."
                }
                message L2_ApiAssign Lead -> ApiAgent async "Assign API scope + acceptance criteria" {
                    protocol "Agent task"
                }
                activate L2_ApiActive ApiAgent
                message L2_ApiContext ApiAgent -> Context sync "Read relevant backend context" {
                    protocol "Repository API"
                }
                message L2_ApiImplement ApiAgent -> Git sync "Implement API changes" {
                    protocol "Git"
                }
                message L2_ApiCheck ApiAgent -> ApiAgent sync "Run focused checks"
                message L2_ApiResult ApiAgent -> Lead return "Return implementation result" {
                    description "Return isolated branch/commit, changed files, checks and any contract conflicts. Lead integrates before final quality review."
                }
                deactivate L2_ApiDone L2_ApiActive
            }
            branch L2_UiBranch "UI implementation" {
                message L2_UiWorktree Lead -> Git sync "Create isolated UI worktree" {
                    protocol "Git"
                    description "Distinct UI branch/worktree with assigned file ownership; shared contracts require coordination."
                }
                message L2_UiAssign Lead -> UiAgent async "Assign UI scope + acceptance criteria" {
                    protocol "Agent task"
                }
                activate L2_UiActive UiAgent
                message L2_UiContext UiAgent -> Context sync "Read relevant frontend context" {
                    protocol "Repository API"
                }
                message L2_UiImplement UiAgent -> Git sync "Implement UI changes" {
                    protocol "Git"
                }
                message L2_UiCheck UiAgent -> UiAgent sync "Run focused checks"
                message L2_UiResult UiAgent -> Lead return "Return implementation result" {
                    description "Return isolated branch/commit, changed files, checks and any contract conflicts. Lead integrates before final quality review."
                }
                deactivate L2_UiDone L2_UiActive
            }
            branch L2_TestBranch "independent tests" {
                message L2_TestWorktree Lead -> Git sync "Create isolated test worktree" {
                    protocol "Git"
                    description "Distinct test branch/worktree with assigned file ownership; shared contracts require coordination."
                }
                message L2_TestAssign Lead -> TestAgent async "Assign behavior + acceptance criteria" {
                    protocol "Agent task"
                }
                activate L2_TestActive TestAgent
                message L2_TestContext TestAgent -> Context sync "Inspect contracts and existing tests" {
                    protocol "Repository API"
                }
                message L2_TestImplement TestAgent -> Git sync "Add/update tests" {
                    protocol "Git"
                }
                message L2_TestCheck TestAgent -> TestAgent sync "Run targeted test suite"
                message L2_TestResult TestAgent -> Lead return "Return test result" {
                    description "Return isolated branch/commit, changed files, checks and any contract conflicts. Lead integrates before final quality review."
                }
                deactivate L2_TestDone L2_TestActive
            }
        }
    }
    sequence Validation "Independent Quality Validation" {
        participants [Lead, CodeReviewer, SecurityReviewer, Git, CI]
        note Q_Revision over [Lead, Git, CI] "Reviewers and CI inspect one integrated candidate revision; CI is deterministic."
        fragment Q_Parallel par "Independent quality checks" {
            branch Q_CodeBranch "code review" {
                message Q_CodeAssign Lead -> CodeReviewer async "Review integrated candidate" {
                    protocol "Agent task"
                }
                message Q_CodeInspect CodeReviewer -> Git sync "Inspect diff and affected architecture" {
                    protocol "Git"
                    description "Check correctness, architecture boundaries, maintainability, regression risk, repository conventions and unnecessary scope."
                }
                message Q_CodeResult CodeReviewer -> Lead return "Return code findings"
            }
            branch Q_SecurityBranch "security review" {
                message Q_SecurityAssign Lead -> SecurityReviewer async "Review security impact" {
                    protocol "Agent task"
                }
                message Q_SecurityInspect SecurityReviewer -> Git sync "Inspect auth, secrets, inputs, dependencies" {
                    protocol "Git"
                }
                message Q_SecurityResult SecurityReviewer -> Lead return "Return security findings"
            }
            branch Q_CiBranch "deterministic CI" {
                message Q_CiAssign Lead -> CI sync "Run validation" {
                    protocol "CI API"
                }
                activate Q_CiActive CI
                message Q_CiCheckout CI -> Git sync "Checkout integrated candidate" {
                    protocol "Git"
                }
                message Q_CiChecks CI -> CI sync "Lint · typecheck · test · build · security checks"
                message Q_CiResult CI -> Lead return "Return gate result"
                deactivate Q_CiDone Q_CiActive
            }
        }
        fragment Q_Outcome alt "Assess review and CI evidence" {
            branch Q_Passed "reviews and CI pass" {
                message Q_AllPass Lead -> Lead sync "Record passing gate evidence"
            }
            branch Q_Failed "finding or CI failure" {
                message Q_Remediation Lead -> Git sync "Assign targeted remediation" {
                    detail Remediation
                    description "Route specific findings to the smallest responsible specialist scope. API Agent is the example; substitute UI/Test ownership when appropriate."
                }
                message Q_RecheckOutcome Lead -> Lead sync "Record revalidated pass or unresolved risk"
            }
        }
    }
    sequence Remediation "Targeted Remediation" {
        participants [Engineer, Lead, Context, ApiAgent, CodeReviewer, SecurityReviewer, Git, CI]
        note R_Routing over [Lead, ApiAgent] "API Agent illustrates the responsible specialist; route UI/test findings to their owners."
        fragment R_FindingSource alt "Specific actionable finding" {
            branch R_ReviewerFinding "review finding" {
                message R_ReviewFinding CodeReviewer -> Lead return "Return specific review finding" {
                    description "Code reviewer shown; security findings originate from the independent Security Reviewer."
                }
            }
            branch R_CiFinding "CI failure" {
                message R_CiFindingMessage CI -> Lead return "Return failing check and evidence"
            }
        }
        fragment R_Loop loop "Up to 2 remediation iterations" {
            branch R_Attempt "finding unresolved and attempts < 2" {
                message R_Identify Lead -> Lead sync "Identify smallest responsible scope"
                message R_Assign Lead -> ApiAgent async "Assign targeted remediation only" {
                    protocol "Agent task"
                }
                activate R_SpecialistActive ApiAgent
                message R_Context ApiAgent -> Context sync "Inspect affected context" {
                    protocol "Repository API"
                }
                message R_Patch ApiAgent -> Git sync "Patch isolated responsible scope" {
                    protocol "Git"
                }
                message R_Focused ApiAgent -> ApiAgent sync "Run focused checks"
                message R_PatchResult ApiAgent -> Lead return "Return patch and check evidence"
                deactivate R_SpecialistDone R_SpecialistActive
                activate R_Integrating Lead
                message R_Reintegrate Lead -> Git sync "Reintegrate targeted patch" {
                    protocol "Git"
                }
                deactivate R_Integrated R_Integrating
                fragment R_Revalidation par "Revalidate updated integrated revision" {
                    branch R_CodeRevalidation "independent code review" {
                        message R_CodeRequest Lead -> CodeReviewer async "Recheck affected diff and regressions"
                        message R_CodeRead CodeReviewer -> Git sync "Inspect updated integrated diff" {
                            protocol "Git"
                        }
                        message R_CodeResult CodeReviewer -> Lead return "Return updated code gate"
                    }
                    branch R_SecurityRevalidation "independent security review" {
                        message R_SecurityRequest Lead -> SecurityReviewer async "Recheck security impact"
                        message R_SecurityRead SecurityReviewer -> Git sync "Inspect updated security boundaries" {
                            protocol "Git"
                        }
                        message R_SecurityResult SecurityReviewer -> Lead return "Return updated security gate"
                    }
                    branch R_CiRevalidation "deterministic CI" {
                        message R_CiRequest Lead -> CI sync "Revalidate updated candidate" {
                            protocol "CI API"
                        }
                        activate R_CiActive CI
                        message R_CiCheckout CI -> Git sync "Checkout updated integrated revision" {
                            protocol "Git"
                        }
                        message R_CiChecks CI -> CI sync "Run deterministic validation suite"
                        message R_CiResult CI -> Lead return "Return updated CI gate"
                        deactivate R_CiDone R_CiActive
                    }
                }
            }
        }
        fragment R_Stop break "Escalate unresolved delivery risk" {
            branch R_Limit "retry limit reached / unresolved risk" {
                message R_Escalate Lead -> Engineer async "Escalate findings; stop autonomous remediation"
                note R_HoldMerge over [Engineer, Lead] "Hold merge. Further work requires an explicit human decision."
            }
        }
        message R_Validated Lead -> Lead sync "Record all gates passing" {
            description "Reached only on the non-breaking path after code review, security review and deterministic CI all pass for the current revision."
        }
    }
}