Skip to content
Docs
Artificial Intelligence
Coding Agents
Multi-agent and CI/CD

Multi-agent, CI/CD and spec-driven 🤖

So far we have discussed one agent at a time: one task, one session, one result. But real projects do not work that way. They need multiple agents working in parallel, pipelines that automate quality, and a specification that outlives the code. This guide is the next level: how to orchestrate multiple agents, integrate them into CI/CD, and use the specification as the guiding contract.

Code dies. The specification does not. Agents that work from a clear specification produce code that can be regenerated. Agents that work from a vague prompt produce code that can only be rewritten.

Multi-agent delegation 🤝

Pattern: Writer/Reviewer

The simplest and most effective pattern. One agent writes the code (session A), another reviews it in a separate context (session B).

Why it works:

  • The reviewer agent lacks the writer’s context → sees code like a human reviewer would
  • No confirmation bias: the agent that wrote the code cannot “see” its own errors
  • The reviewer’s context window is clean

How to implement it:

    sequenceDiagram
    participant D as Developer
    participant A1 as Writer Agent
    participant A2 as Reviewer Agent

    D->>A1: Task: implement [feature]
    A1->>A1: Plans and writes code
    A1->>D: Delivers the diff
    D->>A2: Task: review this diff
    A2->>A2: Analyzes security, patterns, coherence
    A2->>D: Report with findings
    D->>D: Validates and merges

Sequential specialized sub-agents

The primary agent (Lead Agent) divides the problem and delegates sub-tasks to isolated sub-agents.

Practical example:

  1. Exploratory phase: Explore sub-agent in read-only mode → explores the repository and produces a map
  2. Implementation phase: Lead Agent receives the map → writes the code
  3. Verification phase: Scout sub-agent runs tests and produces a report

Key rule: every sub-agent operates in a scoped and isolated context. It must never load the entire repository into the context window.

Isolated parallel execution

The task is divided into independent modules handled by sub-agents executed in parallel on separate Git worktrees or isolated containers.

When it pays off:

  • Independent modules without cross-dependencies
  • Generating test suites for isolated modules
  • Simultaneous refactoring of separate components

When it does NOT pay off:

  • Tightly coupled modules → merge conflicts
  • Tasks requiring unified contextual vision
  • Operations on interdependent files

Delegation pays off for large-scale but disconnected tasks. For coupled modules, parallel delegation is worse than a single agent.

Asynchronous agents and CI/CD 🔄

Flow: issue → PR

Cloud agents can be assigned issues and work in the background:

  1. Assignment: developer assigns issue to cloud agent
  2. Execution: agent clones the repo, analyzes context, implements
  3. Self-evaluation: agent runs build, lint, tests before notifying
  4. Delivery: agent opens a PR with architectural summary
  5. Human review: developer reviews and merges

CI/CD pipeline integration

Agents are invoked in non-interactive mode within workflows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

name: Agentic Quality Check
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  agent-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install
      - name: Agent Security & Quality Check
        run: |
          opencode run "Analyze failed tests or linter violations in the PR. Apply fixes, run tests, commit if green." --auto

Automated use cases:

  • Automatic fix of vulnerabilities reported by linters
  • Automatic dependency updates
  • Technical documentation update at every commit
  • Test snapshot regeneration

Spec-driven development 📋

The Specify → Clarify → Plan → Implement cycle

The specification is the contract that outlives the code. The workflow is:

    flowchart LR
    A[Specify 📝] --> B[Clarify 💬]
    B --> C[Plan 📐]
    C --> D[Implement ⚙️]
    D --> E[Verify ✅]
    E --> |New cycle| A

Phase 1 — Specification (Human) The engineer writes SPEC.md with requirements, interfaces, constraints, acceptance criteria.

Phase 2 — Clarification (Agent + Human) The agent analyzes the specification and asks questions about ambiguities, edge cases, inconsistencies. → Human checkpoint 1: the developer responds and refines the specification.

Phase 3 — Planning (Agent) The agent transforms the approved specification into an executive document (PLANS.md): sequence of files to create, modify, remove. → Human checkpoint 2: the user reviews and validates the plan. No code before explicit approval.

Phase 4 — Decomposition (Agent) The agent divides the plan into atomic, sequential, independently testable sub-tasks.

Phase 5 — Implementation (Agent + CI) The agent executes one task at a time, runs tests after every change, applies fixes. → Human checkpoint 3: final code review and merge.

The value of the specification

The specification is not a preliminary document. It is the living contract of the project. Code generated from a clear specification can be regenerated. Code generated from a vague prompt can only be rewritten.

What to put in SPEC.md:

  • Functional requirements (what the system must do)
  • API interfaces (endpoints, signatures, schemas)
  • Security constraints
  • Acceptance criteria (tests that must pass)
  • Explicit scope (what the system does NOT do)

Anti-patterns 🚫

  • Delegation without isolation — multiple sub-agents on the same file = conflicts. Every sub-agent operates on independent modules.
  • Spec-driven without human control — checkpoints are not optional. Without them, the agent drifts from the architecture.
  • Agentic CI/CD without rollback — every automatic fix must be undoable. Never delegate production deployments or migrations.
  • Sub-agents with too much context — a sub-agent loading the entire repository is not a sub-agent: it is a slow agent.
  • “Build everything” with one prompt — delegation works for atomic tasks, not for “build a complete system.”

Acceptance criteria 📏

Criterion Requirement Validation
Isolation Every sub-agent operates on scoped context No merge conflicts between sub-agents
Specification Every implementation starts from approved SPEC.md Verify spec → code traceability
Human control Checkpoints at every critical phase Approval logs
Rollback Every CI/CD fix undoable Git revert possible
Tests Green suite after every increment CI pipeline green

Series references 📚

Last updated on