SDD Flow Simulation

This article simulates a complete Specification-Driven Development (SDD) flow through dialogue, demonstrating how to use Claude Code + OpenSpec framework for end-to-end collaboration from requirements to delivery.

Participants

Role	Responsibility	Primary Tools
PM	Requirements definition, acceptance criteria	OpenSpec proposal
UX	User experience design, interaction specs	Figma + Figma Make + Claude Code
BE	API design, backend implementation review	OpenAPI + Claude Code
FE	Frontend implementation review, component integration	Claude Code + Design System
ADM	Flow orchestration, quality gates, cross-role coordination	OpenSpec + Claude Code
Agent	Spec generation, code implementation	Claude Code
QA	Test strategy, acceptance testing	Test framework + Claude Code

Note: ADM (Agentic Development Master) is the evolution of the traditional Scrum Master role. In the SDD workflow, ADM focuses on orchestrating AI-human collaboration, ensuring spec quality, and facilitating cross-functional coordination.

Scenario

Feature Request: Add a "Product Wishlist" feature to an e-commerce platform, allowing users to save products and view their wishlist on their profile page.

Phase 1: Requirement Seed (PM)

Context

PM receives the business requirement from stakeholders and creates a requirement seed document. The seed should be written by the PM based on actual feedback, not auto-generated by AI.

PM (Alice): collects user feedback and writes the seed document

"Based on user feedback from support tickets and surveys, I've drafted a requirement seed for the wishlist feature."

markdown

<!-- requirements/product-wishlist.md -->
---
title: Product Wishlist Feature
author: PM-Alice
created: 2026-04-15
status: seed
---

# Product Wishlist Feature

## Business Context
Users have requested the ability to save products they're interested in for future purchase decisions. This was the #3 most requested feature in our Q1 user survey (1,247 votes).

### Problem Statement
- Users often make purchase decisions after multiple visits but cannot track previously viewed products
- Support tickets show ~200 monthly inquiries about "how to find products I viewed before"
- Competitive analysis: All major competitors already offer this feature

### Expected Benefits
- Increase return visits: Estimated 15% increase in returning users
- Improve conversion rate: Wishlist users convert 2.3x higher than average
- Reduce support burden: Decrease related tickets by ~80%

## Target Users
- Primary: Registered members with purchase intent who need time to decide
- Secondary: Browsing users collecting interesting products

## User Scenarios

### Scenario 1: Adding to Wishlist
User Amy is browsing and sees shoes she likes but wants to wait until payday. She clicks the heart button to add to wishlist and sees "Added to wishlist" confirmation.

### Scenario 2: Viewing Wishlist
Two weeks later, Amy logs in and clicks "My Wishlist" in her profile. She sees the shoes she saved and notices the price dropped from $2,800 to $2,380. She decides to buy immediately.

### Scenario 3: Unauthenticated User
Visitor Bob wants to add a product to wishlist. After clicking the heart, he sees a login prompt. After successful login, the product is automatically added to his wishlist.

### Scenario 4: Product Unavailable
User Carol views her wishlist and sees a product marked "No longer available". She can choose to remove it or keep it for reference.

## Business Rules
- Maximum wishlist items per user: 500 products
- Wishlist is private data, not publicly visible
- Unavailable products remain in wishlist for 90 days, then auto-removed
- Price drop notification: Email sent when price drops >10% (requires user notification settings enabled)

## Acceptance Criteria
- [ ] Unauthenticated users redirected to login, product auto-added after login
- [ ] Authenticated users can instantly add/remove from wishlist
- [ ] Wishlist page supports paginated loading (20 items per page)
- [ ] Unavailable products visually distinguished in wishlist
- [ ] Display price comparison: when added vs. current price
- [ ] Empty wishlist shows guidance message

## Out of Scope (Not in This Release)
- Wishlist sharing functionality
- Wishlist categories/folders
- Multiple wishlists
- Push notifications for price drops (Email only)

PM (Alice): "I've submitted this seed for team review before we proceed to refinement."

Key Point

The seed document should be written by humans based on actual stakeholder feedback, not auto-generated by AI from a brief prompt. AI tends to hallucinate "complete" feature sets that weren't requested. PM owns the requirement definition.

Phase 1 Artifacts:

Artifact	Location	Owner
Requirement seed document	`requirements/product-wishlist.md`	PM

Phase 2: Seed Review Meeting (ADM + All Team Members)

Context

Before the refinement meeting, ADM convenes all team members for a seed review meeting (in-person or online). This ensures everyone understands the scope and can raise concerns face-to-face.

ADM (Frank): opens the seed review meeting

"Team, let's begin the seed review for the wishlist feature. Please share your thoughts on:
Clarity of requirements
Missing acceptance criteria
Potential technical concerns
Scope appropriateness"

BE (Bob):

"The requirement mentions 'price changes' - do we need real-time price tracking or just show current price vs. price when added?"

FE (Carol):

"For 'instantly add/remove' - should we clarify this means optimistic updates on the UI?"

UX (Diana):

"Empty state is not mentioned. What should users see when their wishlist is empty?"

QA (Eve):

"Edge case: what happens when a wishlisted product is deleted from the catalog entirely?"

ADM (Frank): raises relationship with existing features

"Wait, we need to confirm something. The system already has a 'Product Favorites' feature. What's the relationship between this wishlist and favorites?"

PM (Alice):

"Good question. 'Product Favorites' is the legacy feature - just a simple favorites list. This wishlist has advanced features like price tracking and price drop alerts."

BE (Bob):

"Then we need to decide: extend the existing favorites feature, or build a new wishlist service? If the latter, what do we do with the old favorites feature?"

ADM (Frank):

"This might be out of scope for this requirement. Alice, we need to clarify this in the proposal. Options are:
Extend existing favorites feature with new capabilities
Build new service, keep old favorites feature
Build new service, gradually deprecate old favorites with migration path"

PM (Alice):

"I'm inclined toward option 3. But I need to confirm the deprecation timeline with the product team. I'll add this decision point to the seed."

ADM (Frank): summarizes meeting findings

"Good catches, team. Alice, please update the seed based on today's discussion, especially the relationship with existing favorites feature. I'll note these as discussion items for refinement."

PM (Alice): updates the seed based on meeting feedback

markdown

<!-- requirements/product-wishlist.md (updated after review) -->
---
title: Product Wishlist Feature
author: PM-Alice
created: 2026-04-15
status: seed
reviewed: 2026-04-16
---

# Product Wishlist Feature

## Business Context
Users have requested the ability to save products they're interested in for future purchase decisions. This was the #3 most requested feature in our Q1 user survey (1,247 votes).

### Problem Statement
- Users often make purchase decisions after multiple visits but cannot track previously viewed products
- Support tickets show ~200 monthly inquiries about "how to find products I viewed before"
- Competitive analysis: All major competitors already offer this feature

### Expected Benefits
- Increase return visits: Estimated 15% increase in returning users
- Improve conversion rate: Wishlist users convert 2.3x higher than average
- Reduce support burden: Decrease related tickets by ~80%

## Target Users
- Primary: Registered members with purchase intent who need time to decide
- Secondary: Browsing users collecting interesting products

## User Scenarios

### Scenario 1: Adding to Wishlist
User Amy is browsing and sees shoes she likes but wants to wait until payday. She clicks the heart button to add to wishlist and sees "Added to wishlist" confirmation.

### Scenario 2: Viewing Wishlist with Price Drop
Two weeks later, Amy logs in and clicks "My Wishlist" in her profile. She sees the shoes she saved and notices the price dropped from $2,800 to $2,380. She decides to buy immediately.

### Scenario 3: Unauthenticated User
Visitor Bob wants to add a product to wishlist. After clicking the heart, he sees a login prompt. After successful login, the product is automatically added to his wishlist.

### Scenario 4: Product Unavailable
User Carol views her wishlist and sees a product marked "No longer available". She can choose to remove it or keep it for reference.

### Scenario 5: Product Completely Deleted
User David has a product in his wishlist that was completely deleted by the seller. The system automatically removes it and shows notification on next login: "1 item in your wishlist is no longer available".

## Business Rules
- Maximum wishlist items per user: 500 products
- Wishlist is private data, not publicly visible
- Unavailable products remain in wishlist for 90 days, then auto-removed
- Completely deleted products immediately removed with user notification
- Price drop notification: Email sent when price drops >10% (requires user notification settings enabled)

## Acceptance Criteria
- [ ] Unauthenticated users redirected to login, product auto-added after login
- [ ] Authenticated users can instantly add/remove from wishlist (optimistic UI update)
- [ ] Wishlist page supports paginated loading (20 items per page)
- [ ] Unavailable products visually distinguished in wishlist
- [ ] Display price comparison: when added vs. current price
- [ ] Deleted products removed from wishlist with notification
- [ ] Empty wishlist shows guidance message

## Relationship with Existing Features
- Existing feature: Product Favorites (simple list, no price tracking)
- Decision: Build new wishlist service, gradually deprecate old favorites
- Migration plan: Pending product team confirmation on deprecation timeline

## Out of Scope (Not in This Release)
- Wishlist sharing functionality
- Wishlist categories/folders
- Multiple wishlists
- Push notifications for price drops (Email only)

## Open Questions (for refinement)
- Empty state design details
- Price notification frequency limits
- Legacy favorites migration path and timeline

Key Point

The seed review meeting before refinement catches ambiguities and edge cases early. Each role brings their perspective: BE asks about data, FE asks about interaction, UX asks about states, QA asks about edge cases. ADM ensures the team considers relationship with existing features, avoiding feature overlap or missing deprecation plans. Synchronous meetings allow real-time discussion and clarification, making them more efficient than async comments.

Phase 2 Artifacts:

Artifact	Location	Owner
Updated seed document	`requirements/product-wishlist.md`	PM

Phase 3: Proposal Generation & Review (PM + ADM + Team)

Context

After the seed review, PM uses the seed as input for /openspec:proposal to have Agent generate a formal proposal. The team then reviews the Agent's output together.

3.1 PM Generates Proposal

PM (Alice): opens Claude Code

bash

claude "Based on requirements/product-wishlist.md seed document,
use /openspec:proposal to generate a formal proposal"

Agent: generates proposal draft

markdown

<!-- openspec/changes/wishlist-feature/proposal.md -->
---
id: wishlist-feature
title: Product Wishlist Feature
status: draft
owner: PM-Alice
created: 2026-04-16
---

# Product Wishlist Feature

## Overview
Add product wishlist functionality to the e-commerce platform, allowing users to save products they're interested in.

## Change Scope

### Backend Changes
| File | Change Type | Description |
|------|-------------|-------------|
| `services/wishlist/` | New | Wishlist microservice |
| `api/wishlist.yaml` | New | API specification |

### Frontend Changes
| File | Change Type | Description |
|------|-------------|-------------|
| `components/WishlistButton/` | New | Wishlist button component |
| `pages/wishlist/` | New | Wishlist page |

## Acceptance Criteria
(Inherited from seed document)

3.2 Team Line-by-Line Proposal Review

ADM (Frank): opens proposal review meeting, projects proposal content

"Team, Agent has generated a proposal draft based on the seed. We'll review it line by line and have Agent make changes in real-time."

ADM (Frank): "Let's start with the 'Overview' section..."

PM (Alice):

"The overview is too brief. We should add business value justification."

ADM (Frank): asks Agent to modify in real-time

bash

claude "Update the proposal overview section, add business value:
This is the #3 most requested feature from Q1 survey, expected to improve user engagement and conversion rates"

Agent: updates proposal in real-time

ADM (Frank): "Good, let's move to 'Change Scope'..."

BE (Bob):

"Backend changes should use a separate wishlist microservice to avoid coupling with the product service. Please have Agent add this architectural decision."

ADM (Frank): asks Agent to modify in real-time

bash

claude "Update the backend changes in scope section,
explain the separate microservice architecture and add architectural decision notes"

FE (Carol):

"Frontend changes are missing the optimistic update technical requirement."

UX (Diana):

"I have a question: what animation pattern should we use for the wishlist?"

ADM (Frank): "Good question. Carol and Diana, your thoughts?"

FE (Carol): "I suggest following our existing 'add to cart' interaction pattern for consistency."

ADM (Frank): "There's one more important topic: handling the legacy favorites feature."

BE (Bob):

"If we're deprecating the old favorites feature, we need to add to the proposal: data migration plan, API compatibility strategy, deprecation timeline."

PM (Alice):

"I've confirmed with the product team - they agree to deprecate the old feature in 6 months. We need to maintain both systems in parallel during this period."

FE (Carol):

"Frontend needs to add migration prompts to guide users from old favorites to the new wishlist. This might be out of scope for this requirement."

ADM (Frank): "Good, that's an out-of-scope change. We'll record it as a follow-up task, but the proposal needs to note the dependency."

ADM (Frank): consolidates modification requests

bash

claude "Update the proposal:
1. Add optimistic update technical requirement to frontend changes
2. Add Technical Decisions section with:
   - BE: Separate microservice architecture
   - FE: Optimistic update pattern
   - UX: Follow add-to-cart animation pattern
3. Add Scope Confirmation section:
   - MVP excludes: Wishlist categories, sharing wishlists
   - MVP includes: Add/remove, list view, price drop alerts
4. Add Relationship with Existing Features section:
   - Legacy feature: Product Favorites (to be deprecated in 6 months)
   - Data migration: Auto-import old favorites to new wishlist
   - Out-of-scope follow-up tasks: Migration prompt UI, legacy API deprecation notice"

Agent: updates all specifications

ADM (Frank): "Proposal update complete. Everyone please confirm the final version... If no issues, Diana and Bob please have your specs ready by end of week."

Key Point

Line-by-line review allows the team to identify issues and have Agent fix them in real-time. Review must confirm relationship with existing features: whether to extend, deprecate, or identify out-of-scope dependent changes. These decisions should be recorded in the proposal, with out-of-scope tasks recorded as follow-up work.

Phase 3 Artifacts:

Artifact	Location	Owner
OpenSpec proposal	`openspec/changes/wishlist-feature/proposal.md`	PM + Agent

Phase 4: API First Design (BE + Agent + Team Review)

Context

API First design flow. Based on the OpenSpec proposal from Phase 3, BE follows API design principles to have Agent generate an OpenAPI document, then submits it to the API management platform (Git-based) for team review.

4.1 BE Generates API Spec

BE (Bob): opens Claude Code

"Based on the requirements in the proposal, I need to design the wishlist API."

bash

claude "Based on openspec/changes/wishlist-feature/proposal.md,
following our API design principles (RESTful, consistent naming, pagination standards)
create an OpenAPI 3.0 spec with:
- GET /wishlist (paginated)
- POST /wishlist (add product)
- DELETE /wishlist/{productId} (remove product)
Include WishlistItem schema with price drop indicator."

Agent: generates OpenAPI spec

yaml

# specs/api/wishlist-api.yaml
openapi: 3.0.3
info:
  title: Wishlist API
  version: 1.0.0
  description: Product Wishlist API

paths:
  /api/v1/wishlist:
    get:
      summary: Get wishlist
      operationId: getWishlist
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WishlistResponse'

    post:
      summary: Add to wishlist
      operationId: addToWishlist
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - productId
              properties:
                productId:
                  type: string
      responses:
        '201':
          description: Added successfully

  /api/v1/wishlist/{productId}:
    delete:
      summary: Remove from wishlist
      operationId: removeFromWishlist
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Removed successfully

components:
  schemas:
    WishlistResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/WishlistItem'
        pagination:
          $ref: '#/components/schemas/Pagination'

    WishlistItem:
      type: object
      properties:
        productId:
          type: string
        productName:
          type: string
        imageUrl:
          type: string
        currentPrice:
          type: number
        originalPrice:
          type: number
        priceDropped:
          type: boolean
        isAvailable:
          type: boolean
        addedAt:
          type: string
          format: date-time

4.2 Submit to API Management Platform

BE (Bob): submits API spec to Git-based API management platform

bash

git add specs/api/wishlist-api.yaml
git commit -m "feat(api): add wishlist API specification"
git push origin feature/wishlist-api

BE (Bob): "API spec submitted. ADM, please schedule a review meeting."

4.3 Team Line-by-Line API Spec Review

ADM (Frank): opens API review meeting (in-person or online), projects API spec

"Team, including Alice, let's review the wishlist API spec line by line. We'll have Agent make changes in real-time as we find issues."

ADM (Frank): "Let's start with the GET /wishlist endpoint..."

PM (Alice):

"Pagination parameters look good. But I want to confirm, where will the deleted product notification mechanism be handled?"

BE (Bob):

"Deleted product notifications will be handled via event-driven architecture, outside this API scope. I'll have Agent add a note in the API docs."

ADM (Frank): asks Agent to modify in real-time

bash

claude "Add a note to wishlist-api.yaml's info.description:
Deleted product notifications are handled via event-driven architecture, outside this API scope"

ADM (Frank): "Moving on to WishlistItem schema..."

FE (Carol):

"The priceDropped boolean is useful. But the addedAt field needs explicit format documentation as ISO 8601."

ADM (Frank): asks Agent to modify in real-time

bash

claude "Update the WishlistItem schema's addedAt field,
add example showing ISO 8601 format"

QA (Eve):

"Missing error response schemas, which will affect test design."

ADM (Frank): asks Agent to modify in real-time

bash

claude "Add ErrorResponse schema and define
400, 401, 404, 500 error responses for all endpoints"

Agent: updates all specifications

UX (Diana):

"The API can support empty state and paginated loading UI requirements. No issues from my side."

ADM (Frank): "API spec update complete. Everyone confirm the final version..."

BE (Bob): confirms and merges

bash

git commit -m "feat(api): finalize wishlist API after review"
git push && gh pr merge --squash

Key Point

Line-by-line API spec review allows the team to identify issues and have Agent fix them in real-time. PM ensures API meets business requirements, FE ensures response formats are usable, QA ensures error handling is complete. All modifications are completed during the meeting, avoiding back-and-forth iterations.

Phase 4 Artifacts:

Artifact	Location	Owner
OpenAPI specification	`specs/api/wishlist-api.yaml`	BE + Agent

Phase 5: UX Design (UX + Agent)

Context

With the API contract finalized, UX designs the user experience and creates detailed interaction specifications that will guide AI implementation and human review.

5.1 UX Designs Wireframes

UX (Diana): designs the wishlist feature UI

"Based on the API spec and proposal requirements, I need to design:
Wishlist button on product cards (heart icon)
Wishlist page on profile (grid layout)
Empty state screen"

Diana: after completing wireframe design, documents interaction specs

5.2 UX Annotates Acceptance Criteria

UX (Diana): opens Claude Code

"Based on my wireframes and the finalized API spec, I need to create interaction specs with acceptance criteria."

bash

claude "Create a UX interaction spec for the wishlist button and grid components.
Reference specs/api/wishlist-api.yaml for response formats.
Include Given/When/Then scenarios for:
- Adding to wishlist (authenticated)
- Adding to wishlist (unauthenticated)
- Removing from wishlist"

Agent: generates interaction spec

markdown

<!-- specs/ux/wishlist-interaction.md -->
---
title: Wishlist Interaction Spec
type: ux-spec
api-ref: specs/api/wishlist-api.yaml
components:
  - WishlistButton
  - WishlistGrid
  - EmptyState
---

# Wishlist Interaction Spec

## Wishlist Button Interaction

### State Definitions
| State | Visual | Behavior |
|-------|--------|----------|
| Not saved | Outline heart | Fill animation on click |
| Saved | Filled heart (red) | Shrink-fade animation on click |
| Loading | Heart + spinner | Click disabled |

### Acceptance Criteria (Given/When/Then)

**Scenario: User adds product to wishlist**
- Given: User is authenticated and product is not in wishlist
- When: User clicks wishlist button
- Then: Button immediately shows saved state (optimistic update)
- And: "Added to wishlist" toast appears
- And: Background call to POST /api/v1/wishlist

**Scenario: Unauthenticated user tries to save**
- Given: User is not authenticated
- When: User clicks wishlist button
- Then: Login modal appears
- And: After successful login, product is automatically saved

UX (Diana): "Good. Let me review this spec against my wireframes... The state definitions match and API reference is correct. I'll commit this to the repo."

Key Point

UX specs reference the finalized API spec, ensuring frontend interactions align with backend contracts. The Given/When/Then format makes it machine-parseable and directly usable for test generation.

Phase 5 Artifacts:

Artifact	Location	Owner
Wireframes / Design files	Figma	UX
UX interaction spec	`specs/ux/wishlist-interaction.md`	UX + Agent

Phase 6: Implementation (Agent + FE/BE Review)

Context

With approved proposal, the Agent implements code based on specifications. Human reviewers (BE/FE) verify conformance to specs and best practices.

6.1 Backend Implementation

ADM (Frank): "Bob, the proposal is approved. Please guide the Agent for backend implementation."

BE (Bob): opens Claude Code

bash

claude "Based on openspec/changes/wishlist-feature/proposal.md
implement backend API using /openspec:apply"

Agent: generates backend implementation

typescript

// services/wishlist/wishlist.service.ts
import { Injectable } from '@nestjs/common';
import { WishlistRepository } from './wishlist.repository';

@Injectable()
export class WishlistService {
  constructor(private readonly repository: WishlistRepository) {}

  async getWishlist(userId: string, page: number, limit: number) {
    const items = await this.repository.findByUserId(userId, {
      skip: (page - 1) * limit,
      take: limit,
    });

    const total = await this.repository.countByUserId(userId);

    return {
      items: items.map(this.toWishlistItem),
      pagination: {
        page,
        limit,
        total,
        totalPages: Math.ceil(total / limit),
      },
    };
  }

  async addToWishlist(userId: string, productId: string) {
    const existing = await this.repository.findOne(userId, productId);
    if (existing) {
      return existing;
    }
    return this.repository.create({ userId, productId });
  }

  async removeFromWishlist(userId: string, productId: string) {
    await this.repository.delete(userId, productId);
  }
}

6.2 BE Review

BE (Bob): reviews Agent's generated code

"Let me look at the WishlistService implementation... getWishlist has correct pagination logic, addToWishlist handles duplicate additions. However, I notice there's no caching strategy, which could cause performance issues under high traffic."

BE (Bob): "Core implementation conforms to API spec. I'll open a follow-up task for caching optimization. Approved for merge."

6.3 Frontend Implementation

ADM (Frank): "Carol, backend is ready. Please guide the Agent for frontend implementation."

FE (Carol): opens Claude Code

bash

claude "Based on specs/ux/wishlist-interaction.md
implement frontend components using design system Button and Card components"

Agent: generates frontend implementation

tsx

// components/WishlistButton/WishlistButton.tsx
import { useState, useCallback } from 'react';
import { Heart } from 'lucide-react';
import { Button } from '@/components/ui/button';
import { useWishlist } from '@/hooks/useWishlist';
import { useAuth } from '@/hooks/useAuth';
import { cn } from '@/lib/utils';

interface WishlistButtonProps {
  productId: string;
  className?: string;
}

export function WishlistButton({ productId, className }: WishlistButtonProps) {
  const { isAuthenticated, openLoginModal } = useAuth();
  const { isInWishlist, toggle, isLoading } = useWishlist(productId);
  const [isAnimating, setIsAnimating] = useState(false);

  const handleClick = useCallback(async () => {
    if (!isAuthenticated) {
      openLoginModal({ onSuccess: () => toggle() });
      return;
    }

    setIsAnimating(true);
    await toggle();
    setTimeout(() => setIsAnimating(false), 300);
  }, [isAuthenticated, toggle, openLoginModal]);

  return (
    <Button
      variant="ghost"
      size="icon"
      onClick={handleClick}
      disabled={isLoading}
      className={cn(
        'transition-transform',
        isAnimating && 'scale-125',
        className
      )}
      aria-label={isInWishlist ? 'Remove from wishlist' : 'Add to wishlist'}
    >
      <Heart
        className={cn(
          'h-5 w-5 transition-colors',
          isInWishlist ? 'fill-red-500 text-red-500' : 'text-gray-400'
        )}
      />
    </Button>
  );
}

6.4 FE Review

FE (Carol): reviews code against UX spec

"WishlistButton's state toggle logic is correct, optimistic updates are implemented. aria-label is included for accessibility. However, I notice there's no error state handling when API fails, which affects user experience."

FE (Carol): "Core interactions conform to UX spec. I'll ask Agent to add error handling, then we can merge."

Key Point

Human review is essential. The Agent generates code quickly, but humans verify correctness against specs and catch edge cases the Agent might miss.

Phase 6 Artifacts:

Artifact	Location	Owner
Backend code	`services/wishlist/`	Agent + BE
Frontend code	`components/WishlistButton/`	Agent + FE

Phase 7: Testing (QA + Agent)

Context

QA generates test cases from the specification and executes them. The Given/When/Then format in UX specs maps directly to test scenarios.

7.1 QA Requests Agent to Generate Tests

ADM (Frank): "Eve, implementation is complete. Please generate and run the E2E tests."

QA (Eve): opens Claude Code

bash

claude "Based on proposal.md and wishlist-interaction.md
generate E2E test cases"

Agent: generates test cases

typescript

// tests/e2e/wishlist.spec.ts
import { test, expect } from '@playwright/test';

test.describe('Product Wishlist Feature', () => {
  test.beforeEach(async ({ page }) => {
    await page.goto('/products/test-product-1');
  });

  test('authenticated user can add product to wishlist', async ({ page }) => {
    // Given: User is authenticated
    await page.evaluate(() => {
      localStorage.setItem('token', 'test-token');
    });
    await page.reload();

    // When: Click wishlist button
    const wishlistBtn = page.getByLabel('Add to wishlist');
    await wishlistBtn.click();

    // Then: Button shows saved state
    await expect(wishlistBtn).toHaveAttribute('aria-label', 'Remove from wishlist');

    // And: Success toast appears
    await expect(page.getByText('Added to wishlist')).toBeVisible();
  });

  test('unauthenticated user sees login modal on wishlist click', async ({ page }) => {
    // Given: User is not authenticated
    await page.evaluate(() => {
      localStorage.removeItem('token');
    });

    // When: Click wishlist button
    await page.getByLabel('Add to wishlist').click();

    // Then: Login modal appears
    await expect(page.getByRole('dialog')).toBeVisible();
    await expect(page.getByText('Please log in')).toBeVisible();
  });

  test('wishlist shows price drop indicator', async ({ page }) => {
    // Given: User has wishlisted product with price drop
    await page.goto('/wishlist');

    // Then: Price drop label is visible
    await expect(page.getByText('Price dropped')).toBeVisible();
  });
});

7.2 QA Executes Tests

QA (Eve): "Running the E2E tests..."

bash

npx playwright test tests/e2e/wishlist.spec.ts

# Results
Running 3 tests using 1 worker
  ✓ authenticated user can add product to wishlist (1.2s)
  ✓ unauthenticated user sees login modal on wishlist click (0.8s)
  ✓ wishlist shows price drop indicator (0.9s)

3 passed (3.5s)

QA (Eve): "All tests pass. The feature meets the acceptance criteria."

ADM (Frank): "Excellent. Let's proceed to deployment."

Key Point

Tests are generated from specs, ensuring they verify the actual requirements. The Given/When/Then format creates a direct traceability from requirement to test.

Phase 7 Artifacts:

Artifact	Location	Owner
E2E test cases	`tests/e2e/wishlist.spec.ts`	Agent + QA
Test reports	CI/CD System	QA

Phase 8: Archive (PM + ADM + Agent)

Context

After successful deployment, the proposal is archived. This updates the single source of truth and creates an audit trail.

8.1 PM Requests Archive

PM (Alice): "The feature is live and verified in production. Time to archive."

bash

claude "Wishlist feature passed all tests and deployed,
use /openspec:archive to archive this change"

8.2 Agent Executes Archive

Agent: executes archive flow

bash

# Agent executes archive flow
1. Update proposal status to archived
2. Merge specs into specs/ directory
3. Update CHANGELOG.md
4. Create git tag

markdown

<!-- openspec/changes/wishlist-feature/proposal.md -->
---
status: archived
archived_at: 2026-04-26
deployed_version: v2.3.0
---

ADM (Frank): "Archive complete. Great work, team. The wishlist feature is now part of our production specs."

Phase 8 Artifacts:

Artifact	Location	Owner
Archived proposal	`openspec/archive/wishlist-feature/`	Agent
Merged specifications	`specs/` directory	Agent
CHANGELOG update	`CHANGELOG.md`	Agent

Complete Artifact List

Phase	Artifact	Location	Owner
1	Requirement seed document	`requirements/`	PM
2	Updated seed document	`requirements/`	PM
3	OpenSpec proposal	`openspec/changes/`	PM + Agent
4	OpenAPI specification	`specs/api/`	BE + Agent
5	Wireframes / Design files	Figma	UX
5	UX interaction spec	`specs/ux/`	UX + Agent
6	Backend code	`services/`	Agent + BE
6	Frontend code	`components/`	Agent + FE
7	E2E test cases	`tests/e2e/`	Agent + QA
8	Archived proposal	`openspec/archive/`	Agent
8	Merged specifications	`specs/`	Agent

Flow Summary

Role of Agentic Development Master (ADM)

The ADM serves as the conductor of the SDD orchestra:

Traditional Scrum Master	Agentic Development Master
Facilitates ceremonies	Orchestrates AI-human collaboration
Removes blockers	Ensures spec quality and completeness
Tracks velocity	Monitors AI output quality gates
Coaches team on Scrum	Guides team on context engineering
Shields team from interruptions	Coordinates cross-role handoffs

Workflow Framework - Complete workflow documentation
Feature Development Flow - Detailed feature development process
One-Year Plan - Organizational adoption plan

Workflow Framework

Guiding Principles

Governance

Culture

Execution

SDD Flow Simulation

Participants

Scenario

Phase 1: Requirement Seed (PM)

Phase 2: Seed Review Meeting (ADM + All Team Members)

Phase 3: Proposal Generation & Review (PM + ADM + Team)

3.1 PM Generates Proposal

3.2 Team Line-by-Line Proposal Review

Phase 4: API First Design (BE + Agent + Team Review)

4.1 BE Generates API Spec

4.2 Submit to API Management Platform

4.3 Team Line-by-Line API Spec Review

Phase 5: UX Design (UX + Agent)

5.1 UX Designs Wireframes

5.2 UX Annotates Acceptance Criteria

Phase 6: Implementation (Agent + FE/BE Review)

6.1 Backend Implementation

6.2 BE Review

6.3 Frontend Implementation

6.4 FE Review

Phase 7: Testing (QA + Agent)

7.1 QA Requests Agent to Generate Tests

7.2 QA Executes Tests

Phase 8: Archive (PM + ADM + Agent)

8.1 PM Requests Archive

8.2 Agent Executes Archive

Complete Artifact List

Flow Summary

Role of Agentic Development Master (ADM)

SDD Flow Simulation ​

Participants ​

Scenario ​

Phase 1: Requirement Seed (PM) ​

Phase 2: Seed Review Meeting (ADM + All Team Members) ​

Phase 3: Proposal Generation & Review (PM + ADM + Team) ​

3.1 PM Generates Proposal ​

3.2 Team Line-by-Line Proposal Review ​

Phase 4: API First Design (BE + Agent + Team Review) ​

4.1 BE Generates API Spec ​

4.2 Submit to API Management Platform ​

4.3 Team Line-by-Line API Spec Review ​

Phase 5: UX Design (UX + Agent) ​

5.1 UX Designs Wireframes ​

5.2 UX Annotates Acceptance Criteria ​

Phase 6: Implementation (Agent + FE/BE Review) ​

6.1 Backend Implementation ​

6.2 BE Review ​

6.3 Frontend Implementation ​

6.4 FE Review ​

Phase 7: Testing (QA + Agent) ​

7.1 QA Requests Agent to Generate Tests ​

7.2 QA Executes Tests ​

Phase 8: Archive (PM + ADM + Agent) ​

8.1 PM Requests Archive ​

8.2 Agent Executes Archive ​

Complete Artifact List ​

Flow Summary ​

Role of Agentic Development Master (ADM) ​

Related Documents ​

SDD Flow Simulation

Participants

Scenario

Phase 1: Requirement Seed (PM)

Phase 2: Seed Review Meeting (ADM + All Team Members)

Phase 3: Proposal Generation & Review (PM + ADM + Team)

3.1 PM Generates Proposal

3.2 Team Line-by-Line Proposal Review

Phase 4: API First Design (BE + Agent + Team Review)

4.1 BE Generates API Spec

4.2 Submit to API Management Platform

4.3 Team Line-by-Line API Spec Review

Phase 5: UX Design (UX + Agent)

5.1 UX Designs Wireframes

5.2 UX Annotates Acceptance Criteria

Phase 6: Implementation (Agent + FE/BE Review)

6.1 Backend Implementation

6.2 BE Review

6.3 Frontend Implementation

6.4 FE Review

Phase 7: Testing (QA + Agent)

7.1 QA Requests Agent to Generate Tests

7.2 QA Executes Tests

Phase 8: Archive (PM + ADM + Agent)

8.1 PM Requests Archive

8.2 Agent Executes Archive

Complete Artifact List

Flow Summary

Role of Agentic Development Master (ADM)

Related Documents