Spec-Driven Development (SDD)

Summary

Spec-Driven Development (SDD) is fundamentally about capturing intent and using it to generate outputs through Agentic work. Today, context needed to execute work is scattered across issues, comments, design files, code, and people’s heads. Agents that try to act on a work item without structured input produce inconsistent results because they lack the why, how, and what.

SDD solves this by introducing a structured planning layer on GitLab work items. An Agent plan is collaboratively built by humans and AI agents, enriched with project context, and then consumed downstream by execution agents (Duo Developer) and validation agents (Duo Review).

We are building this feature with the mindset that any work done should work for Agents and Human both. In practice what this means is that SDD is a way of working, and we are seeing this rise in popularity with Agents. But the underlying concept is very human: documentation-centric way of developping, accelerated with Agents.

For product context see the parent epic and wiki.

End-to-end flow

flowchart LR
    subgraph context["1 · Context Gathering"]
        Memory[Memory]
        DL[Decision log]
    end

    subgraph generation["2 · Plan Generation"]
        IB[Interactive builder] -->|produces| WP[Agent plan widget]
        WP -->|evaluated by| Score[Readiness Score]
    end

    subgraph validation["3 · Plan Validation"]
        DD[Duo Developer] -->|produces| MR[Merge Request]
        DR[Duo Review] -->|validates MR against plan| MR
    end

    WI[Work item] -->|user opens| IB
    Memory -->|injected into prompt| IB
    DL -->|fed as context| IB
    WP -->|read by| DD
    WP -->|read by| DR
    WI ---|Work item ↔ MR link| MR

Three layers to build

The architecture breaks down into three layers. Each layer has its own problems to solve and its own set of subpages with detailed designs.

1. Context Gathering

Before a plan can be generated, the agent needs context: project conventions, past decisions, architectural patterns, related work items, and team preferences. The challenge is figuring out where to store these layers of context, how to keep them current, and how to inject the right slices at the right time.

2. Plan Generation

The Agent plan is the central artifact. Users talk with agents through the Interactive builder to iteratively shape a plan that captures the Why, How, What, and a clear list of pending questions and steps. Plans get refined over time and multiple stakeholders can contribute, so we need versioning, an auditing trail, and a lightweight review flow.

3. Plan Validation

Once a plan is approved, it needs to carry weight. Downstream agents read the plan, execute against it, and validate that the resulting merge request matches the stated intent. This requires a strong link between work items and MRs.

Decisions

Constraints

• Agent sessions are single-user (async collaboration only through work item comments)
• Work item approvals do not exist on the platform
• MR-to-work-item link is the only bridge for Duo Review to access the plan
• IDE interactive builder out of scope for v1
• Long-lived Spec storage unresolved

Timeline

Release stages: Core team (now) -> Internal preview (2026-05-30) -> Customer preview (TBD) -> GA (TBD).

Links

• Parent Epic
• Wiki SSoT
• AI Panel architecture
• Design Issue
• Engineering Spike
• Workshop notes

View page source - Edit this page - please contribute.