faysilalshareef/sdd-lifecycle

SDD Lifecycle — Specification-Driven Development

Core Principles

• Features progress through defined phases: Plan -> Spec -> Implement -> Review -> Ship
• Each phase produces artifacts stored in .dotnet-ai-kit/features/{NNN}/
• Specification is written before implementation (design-first)
• Cross-service features coordinate via dependency chains
• Status tracking enables handoffs between sessions and team members

Key Patterns

Phase Definitions

Phase 1: PLAN
  Input:  User requirement or feature request
  Output: Feature brief with scope, affected services, acceptance criteria
  Status: planned

Phase 2: SPEC
  Input:  Feature brief
  Output: Technical specification with:
    - Event data types and aggregate changes
    - Query entity projections
    - API endpoint definitions
    - UI wireframe descriptions
  Status: specified

Phase 3: IMPLEMENT
  Input:  Technical specification
  Output: Working code across affected services
  Status: implementing -> implemented

Phase 4: REVIEW
  Input:  Implemented code
  Output: Review feedback, CodeRabbit analysis
  Status: reviewing -> approved

Phase 5: SHIP
  Input:  Approved code
  Output: Deployed to target environment
  Status: shipped

Feature Directory Structure

.dotnet-ai-kit/
  features/
    001-order-creation/
      brief.md              # Phase 1: scope and requirements
      spec.md               # Phase 2: technical specification
      status.json           # Current phase and metadata
      implementation-log.md # Phase 3: what was done
      review-notes.md       # Phase 4: review feedback
    002-order-export/
      brief.md
      spec.md
      status.json

status.json Format

{
  "featureId": "001",
  "name": "order-creation",
  "phase": "implementing",
  "createdAt": "2025-03-15T10:00:00Z",
  "updatedAt": "2025-03-16T14:30:00Z",
  "affectedServices": [
    "{domain}-command",
    "{domain}-query",
    "{domain}-gateway"
  ],
  "dependencies": [],
  "assignedAgent": "command-architect"
}

Microservice Feature Flow

1. Plan: Identify affected services (command, query, processor, gateway, CP)
2. Spec: Define events, queries, endpoints per service
3. Implement: Start with command side (events), then query, then gateway
4. Review: Review each service, verify cross-service integration
5. Ship: Deploy in dependency order (command first, then query, then gateway)

Generic .NET Feature Flow

1. Plan: Identify affected layers (domain, application, infrastructure, API)
2. Spec: Define entities, commands/queries, endpoints
3. Implement: Start with domain, then application, then infrastructure
4. Review: Review full vertical slice
5. Ship: Single deployment

Anti-Patterns

| Anti-Pattern | Correct Approach | |---|---| | Implementing without spec | Always write spec before code | | Skipping review phase | Every feature gets reviewed | | Not tracking status | Update status.json at each transition | | Single massive feature | Break into small, deployable increments |

Detect Existing Patterns

# Find feature directory
find . -path "*/.dotnet-ai-kit/features/*" -name "status.json"

# Check current feature status
cat .dotnet-ai-kit/features/*/status.json 2>/dev/null

# Find existing specs
find . -path "*/.dotnet-ai-kit/features/*/spec.md"

Adding to Existing Project

1. Check for .dotnet-ai-kit/features/ directory structure
2. Follow existing feature numbering — sequential NNN format
3. Match spec template from existing features
4. Update status.json when transitioning phases
5. For multi-repo features, coordinate across service repositories

Related rules

This skill depends on the always-on tool-calls convention rule:

• ${CLAUDE_PLUGIN_ROOT}/rules/conventions/tool-calls.md

The rule is loaded into context whenever this skill is active (FR-011 universal whitelist).