rdev/docs/plans/sdlc-orchestration-breakdown.md

# SDLC Orchestration System - Implementation Breakdown

**Spec:** `docs/specs/sdlc-orchestration-system.md`
**Goal:** Build an enterprise-grade SDLC system where every action is deterministic, API-observable, and artifact-producing.

## Executive Summary

This breakdown covers 8 weeks of implementation:
- **Weeks 1-2:** Foundation (SDLC CLI tool + git structure)
- **Weeks 3-4:** rdev API Surface (state, features, artifacts, classifier)
- **Weeks 5-6:** Command Integration (update skeleton commands to use SDLC)
- **Week 7:** Execution & Orchestration (Claude task execution via API)
- **Week 8:** Polish & Documentation (full workflow validation, docs)

---

## Week 1: SDLC CLI Foundation

**Goal:** Build the `sdlc` CLI tool with core state management commands.

### Deliverables

| File | Action | Description |
|------|--------|-------------|
| `cmd/sdlc/main.go` | CREATE | CLI entry point with cobra |
| `cmd/sdlc/cmd/root.go` | CREATE | Root command, config loading |
| `cmd/sdlc/cmd/init.go` | CREATE | `sdlc init` - create .sdlc/ structure |
| `cmd/sdlc/cmd/state.go` | CREATE | `sdlc state` - show current state |
| `cmd/sdlc/cmd/config.go` | CREATE | `sdlc config` - manage config |
| `internal/sdlc/state.go` | CREATE | State struct, Load/Save functions |
| `internal/sdlc/config.go` | CREATE | Config struct, validation |
| `internal/sdlc/paths.go` | CREATE | Path constants and helpers |

### Implementation Details

#### `cmd/sdlc/main.go`
```go
package main

import "github.com/orchard9/rdev/cmd/sdlc/cmd"

func main() {
    cmd.Execute()
}
```

#### `internal/sdlc/state.go`
```go
type State struct {
    Version int                `yaml:"version"`
    Project ProjectState       `yaml:"project"`
    ActiveWork ActiveWork      `yaml:"active_work"`
    Blocked []BlockedItem      `yaml:"blocked"`
    LastUpdated time.Time      `yaml:"last_updated"`
    LastAction string          `yaml:"last_action"`
    LastActor string           `yaml:"last_actor"`
    History []HistoryEntry     `yaml:"history"`
}

func LoadState(root string) (*State, error)
func (s *State) Save(root string) error
func (s *State) RecordAction(action, feature, actor string)
```

### Commands Implemented

```bash
sdlc init                    # Create .sdlc/ structure with templates
sdlc state                   # Show current state
sdlc config set <key> <val>  # Update config
sdlc config show             # Display config
```

### Tests

- `cmd/sdlc/cmd/init_test.go` - Verify directory structure created
- `internal/sdlc/state_test.go` - State load/save round-trip

### Exit Criteria

- [ ] `sdlc init` creates valid `.sdlc/` structure
- [ ] `sdlc state` reads and displays state.yaml
- [ ] `sdlc config` reads/writes config.yaml
- [ ] Unit tests pass

---

## Week 2: Feature & Artifact Management

**Goal:** Complete SDLC CLI with feature lifecycle and artifact management.

### Deliverables

| File | Action | Description |
|------|--------|-------------|
| `cmd/sdlc/cmd/feature.go` | CREATE | `sdlc feature` subcommands |
| `cmd/sdlc/cmd/artifact.go` | CREATE | `sdlc artifact` subcommands |
| `cmd/sdlc/cmd/task.go` | CREATE | `sdlc task` subcommands |
| `cmd/sdlc/cmd/branch.go` | CREATE | `sdlc branch` subcommands |
| `internal/sdlc/feature.go` | CREATE | Feature struct, manifest I/O |
| `internal/sdlc/artifact.go` | CREATE | Artifact types, status tracking |
| `internal/sdlc/task.go` | CREATE | Task parsing from tasks.md |
| `internal/sdlc/manifest.go` | CREATE | Manifest YAML operations |

### Implementation Details

#### `internal/sdlc/feature.go`
```go
type Feature struct {
    Slug         string                    `yaml:"slug"`
    Title        string                    `yaml:"title"`
    Created      time.Time                 `yaml:"created"`
    Branch       string                    `yaml:"branch"`
    RoadmapRef   string                    `yaml:"roadmap_ref"`
    Phase        FeaturePhase              `yaml:"phase"`
    PhaseHistory []PhaseTransition         `yaml:"phase_history"`
    Artifacts    map[ArtifactType]*Artifact `yaml:"artifacts"`
    Blockers     []string                  `yaml:"blockers"`
    Dependencies Dependencies              `yaml:"dependencies"`
}

type FeaturePhase string
const (
    PhaseDraft          FeaturePhase = "draft"
    PhaseSpecified      FeaturePhase = "specified"
    PhasePlanned        FeaturePhase = "planned"
    PhaseReady          FeaturePhase = "ready"
    PhaseImplementation FeaturePhase = "implementation"
    PhaseReview         FeaturePhase = "review"
    PhaseAudit          FeaturePhase = "audit"
    PhaseQA             FeaturePhase = "qa"
    PhaseMerge          FeaturePhase = "merge"
    PhaseReleased       FeaturePhase = "released"
)

func (f *Feature) CanTransitionTo(phase FeaturePhase) error
func (f *Feature) Transition(phase FeaturePhase) error
```

### Commands Implemented

```bash
sdlc feature create <slug>             # Create new feature
sdlc feature list                      # List all features
sdlc feature show <slug>               # Show feature details
sdlc feature status <slug>             # Show phase + progress
sdlc feature transition <slug> <phase> # Manual transition
sdlc feature block <slug> <reason>     # Add blocker
sdlc feature unblock <slug>            # Remove blocker

sdlc artifact create <feature> <type>  # Create artifact file
sdlc artifact approve <feature> <type> # Mark approved
sdlc artifact reject <feature> <type>  # Mark rejected
sdlc artifact status <feature>         # Show all statuses

sdlc task list <feature>               # List tasks
sdlc task start <feature> <id>         # Mark in-progress
sdlc task complete <feature> <id>      # Mark complete
sdlc task add <feature> <title>        # Add new task

sdlc branch create <feature>           # Create feature branch
sdlc branch status <feature>           # Show branch state
```

### Tests

- `internal/sdlc/feature_test.go` - Phase transitions, validation
- `internal/sdlc/artifact_test.go` - Status tracking
- `cmd/sdlc/cmd/feature_test.go` - CLI integration

### Exit Criteria

- [ ] Can create feature and see it in list
- [ ] Can transition feature through phases
- [ ] Artifact status tracked in manifest
- [ ] Task status parsed from tasks.md markdown
- [ ] Branch creation via `git checkout -b`

---

## Week 3: Classifier Engine

**Goal:** Build the deterministic classifier that evaluates state and returns next action.

### Deliverables

| File | Action | Description |
|------|--------|-------------|
| `cmd/sdlc/cmd/next.go` | CREATE | `sdlc next` command |
| `internal/sdlc/classifier/classifier.go` | CREATE | Main classifier engine |
| `internal/sdlc/classifier/rules.go` | CREATE | Built-in classification rules |
| `internal/sdlc/classifier/types.go` | CREATE | Classification result types |
| `internal/sdlc/classifier/context.go` | CREATE | Context builder for commands |

### Implementation Details

#### `internal/sdlc/classifier/classifier.go`
```go
type Classifier struct {
    rules []Rule
}

type Rule struct {
    ID          string
    Priority    int
    Condition   func(*EvalContext) bool
    Action      ActionType
    Message     string
    NextCommand string
    OutputPath  string
    TransitionTo FeaturePhase
}

type Classification struct {
    Timestamp      time.Time
    Context        ClassificationContext
    Evaluation     Evaluation
    Decision       Decision
    CommandContext map[string]any
}

func (c *Classifier) Classify(state *State, feature *Feature) (*Classification, error)
```

#### Rule Evaluation
```go
// Rules evaluated in priority order, first match wins
var DefaultRules = []Rule{
    // BLOCKERS (priority 1000)
    {ID: "blocked-dependency", Priority: 1000, ...},

    // DRAFT → SPECIFIED (priority 200)
    {ID: "needs-spec", Priority: 200, ...},
    {ID: "spec-needs-approval", Priority: 201, ...},
    {ID: "spec-approved", Priority: 202, ...},

    // SPECIFIED → PLANNED (priority 300)
    {ID: "needs-design", Priority: 300, ...},
    // ...
}
```

### Commands Implemented

```bash
sdlc next                    # Classify global state
sdlc next --for <feature>    # Classify specific feature
sdlc next --execute          # Classify and execute
sdlc next --json             # Output as JSON for API
```

### Output Format

```
┌─────────────────────────────────────────────────────────────────┐
│ SDLC Classifier Result                                          │
├─────────────────────────────────────────────────────────────────┤
│ Feature: auth                                                   │
│ Current Phase: implementation                                   │
│ Tasks: 5/8 complete, 1 in-progress, 2 pending                   │
├─────────────────────────────────────────────────────────────────┤
│ NEXT ACTION: IMPLEMENT_TASK                                     │
│                                                                 │
│ Command: /implement-task auth task-004                          │
│ Output: .sdlc/features/auth/tasks.md (updated)                  │
└─────────────────────────────────────────────────────────────────┘
```

### Tests

- `internal/sdlc/classifier/classifier_test.go` - Rule matching
- `internal/sdlc/classifier/rules_test.go` - Each rule condition
- Integration test: Full feature lifecycle classification

### Exit Criteria

- [ ] Classifier returns correct action for each phase
- [ ] Blocked items identified with resolution path
- [ ] `--json` output matches API format
- [ ] `--execute` triggers appropriate command

---

## Week 4: rdev API Surface (Part 1)

**Goal:** Add SDLC API endpoints to rdev for state, features, and artifacts.

### Deliverables

| File | Action | Description |
|------|--------|-------------|
| `internal/domain/sdlc.go` | CREATE | SDLC domain types |
| `internal/port/sdlc.go` | CREATE | SDLC repository interface |
| `internal/service/sdlc_service.go` | CREATE | SDLC business logic |
| `internal/handlers/sdlc.go` | CREATE | HTTP handlers |
| `internal/handlers/sdlc_features.go` | CREATE | Feature endpoints |
| `internal/handlers/sdlc_artifacts.go` | CREATE | Artifact endpoints |
| `cmd/rdev-api/main.go` | MODIFY | Wire SDLC handlers |

### API Endpoints

```
GET  /projects/{project}/sdlc/state
GET  /projects/{project}/sdlc/features
POST /projects/{project}/sdlc/features
GET  /projects/{project}/sdlc/features/{slug}
POST /projects/{project}/sdlc/features/{slug}/transition

GET  /projects/{project}/sdlc/features/{slug}/artifacts/{type}
POST /projects/{project}/sdlc/features/{slug}/artifacts/{type}
POST /projects/{project}/sdlc/features/{slug}/artifacts/{type}/approve
POST /projects/{project}/sdlc/features/{slug}/artifacts/{type}/reject
```

### Implementation Details

#### `internal/service/sdlc_service.go`
```go
type SDLCService struct {
    gitOps     port.PodGitOperations
    classifier *classifier.Classifier
    logger     *slog.Logger
}

func (s *SDLCService) GetState(ctx context.Context, project string) (*domain.SDLCState, error) {
    // Read .sdlc/state.yaml from project pod
    content, err := s.gitOps.ReadFile(ctx, project, ".sdlc/state.yaml")
    // Parse and return
}

func (s *SDLCService) CreateFeature(ctx context.Context, project string, req CreateFeatureRequest) (*domain.Feature, error) {
    // Create .sdlc/features/{slug}/ directory structure
    // Write manifest.yaml
    // Update state.yaml
    // Commit changes
}
```

### Handler Pattern

```go
func (h *SDLCHandler) GetState(w http.ResponseWriter, r *http.Request) {
    ctx, cancel := context.WithTimeout(r.Context(), TimeoutStandard)
    defer cancel()

    projectID := chi.URLParam(r, "id")

    state, err := h.sdlcService.GetState(ctx, projectID)
    if err != nil {
        if errors.Is(err, domain.ErrNotFound) {
            api.WriteNotFound(w, "SDLC not initialized for project")
            return
        }
        h.logger.Error("get sdlc state", "project", projectID, "error", err)
        api.WriteInternalError(w, "failed to get SDLC state")
        return
    }

    api.WriteSuccess(w, state)
}
```

### Tests

- `internal/handlers/sdlc_test.go` - Handler tests
- `internal/service/sdlc_service_test.go` - Service tests

### Exit Criteria

- [ ] `GET /projects/{id}/sdlc/state` returns state
- [ ] `POST /projects/{id}/sdlc/features` creates feature
- [ ] Artifact CRUD works
- [ ] All endpoints require auth

---

## Week 5: rdev API Surface (Part 2) - Classifier & Execution

**Goal:** Add classifier, blocker resolution, and execution endpoints.

### Deliverables

| File | Action | Description |
|------|--------|-------------|
| `internal/handlers/sdlc_classifier.go` | CREATE | Classifier endpoints |
| `internal/handlers/sdlc_execution.go` | CREATE | Execution endpoints |
| `internal/handlers/sdlc_resolution.go` | CREATE | Blocker resolution |
| `internal/service/sdlc_executor.go` | CREATE | Command execution service |

### API Endpoints

```
GET  /projects/{project}/sdlc/next
GET  /projects/{project}/sdlc/next?feature={slug}
GET  /projects/{project}/sdlc/blocked
POST /projects/{project}/sdlc/resolve
POST /projects/{project}/sdlc/execute
POST /projects/{project}/sdlc/commit
```

### Implementation Details

#### `/sdlc/next` Response
```json
{
  "classification": {
    "rule_id": "implement-next-task",
    "action": "IMPLEMENT_TASK",
    "feature": "auth",
    "task_id": "task-004"
  },
  "instruction": {
    "summary": "Implement JWT token validation",
    "command": "/implement-task auth task-004",
    "output_path": ".sdlc/features/auth/tasks.md",
    "context": {
      "task_spec": "...",
      "patterns_required": ["error-handling"],
      "related_files": ["internal/auth/jwt.go"]
    }
  },
  "execute_url": "/projects/my-project/sdlc/execute",
  "can_auto_execute": true
}
```

#### `/sdlc/execute` Flow
```go
func (s *SDLCService) Execute(ctx context.Context, project string, req ExecuteRequest) (*ExecuteResult, error) {
    // 1. Validate action matches current classification
    classification, err := s.Classify(ctx, project, req.Feature)
    if classification.Decision.Action != req.Action {
        return nil, domain.ErrInvalidAction
    }

    // 2. Execute the command via Claude
    result, err := s.executor.ExecuteCommand(ctx, project, classification.Decision.Command)

    // 3. Verify output exists
    if !s.fileExists(ctx, project, classification.Decision.OutputPath) {
        return nil, domain.ErrOutputMissing
    }

    // 4. Update state
    s.state.RecordAction(req.Action, req.Feature, "api")

    // 5. Auto-commit if requested
    if req.AutoCommit {
        s.gitOps.Commit(ctx, project, generateCommitMessage(req))
    }

    return &ExecuteResult{...}, nil
}
```

### Blocker Resolution Flow

```
GET /sdlc/blocked returns:
{
  "blocked": [{
    "type": "feature",
    "slug": "auth",
    "rule_id": "design-decision-needed",
    "blocked_reason": "Design decision required",
    "resolution": {
      "action": "ANSWER_QUESTION",
      "question": "Which auth provider?",
      "options": ["jwt", "oauth", "session"],
      "resolve_url": "/projects/my-project/sdlc/resolve"
    }
  }]
}

POST /sdlc/resolve with:
{
  "feature": "auth",
  "resolution_type": "ANSWER_QUESTION",
  "question_id": "auth-provider",
  "answer": "jwt",
  "rationale": "Stateless, works well with microservices"
}
```

### Tests

- `internal/handlers/sdlc_classifier_test.go`
- `internal/handlers/sdlc_execution_test.go`
- Integration test: Full blocker resolution flow

### Exit Criteria

- [ ] `/sdlc/next` returns correct classification
- [ ] `/sdlc/blocked` shows all blocked items
- [ ] `/sdlc/resolve` updates artifacts and unblocks
- [ ] `/sdlc/execute` runs commands and verifies output

---

## Week 6: Skeleton Command Integration

**Goal:** Update skeleton template commands to use SDLC tool and produce deterministic outputs.

### Deliverables

| File | Action | Description |
|------|--------|-------------|
| `.../skeleton/.claude/commands/spec-feature.md` | CREATE | Create specification |
| `.../skeleton/.claude/commands/design-feature.md` | CREATE | Create design doc |
| `.../skeleton/.claude/commands/breakdown-feature.md` | CREATE | Create task breakdown |
| `.../skeleton/.claude/commands/create-qa-plan.md` | CREATE | Create QA plan |
| `.../skeleton/.claude/commands/implement-task.md` | CREATE | Implement single task |
| `.../skeleton/.claude/commands/review-feature.md` | CREATE | Review feature code |
| `.../skeleton/.claude/commands/audit-feature.md` | CREATE | Audit feature |
| `.../skeleton/.claude/commands/run-qa.md` | CREATE | Run QA verification |
| `.../skeleton/.claude/commands/next.md` | MODIFY | Integrate with classifier |
| `.../skeleton/.claude/commands/deliver.md` | CREATE | Full feature delivery |

### Command Pattern

Each command MUST:
1. Read context from SDLC structure
2. Produce a concrete artifact
3. Write artifact to the correct location
4. Update manifest/state via `sdlc` CLI
5. Return structured output

#### `/spec-feature` Template
```markdown
---
description: Create a feature specification document
argument-hint: <feature-slug>
allowed-tools: Bash, Read, Write, Edit, AskUserQuestion
---

Create specification for feature: $ARGUMENTS

## Instructions

### 1. Validate Feature Exists
```bash
sdlc feature show $ARGUMENTS
```
If not found, create it first with `sdlc feature create $ARGUMENTS`.

### 2. Gather Requirements
Use AskUserQuestion to understand:
- What problem does this solve?
- Who are the users?
- What are the acceptance criteria?

### 3. Write Specification
Write to `.sdlc/features/{slug}/spec.md` using template:

```markdown
---
feature: {slug}
version: 1
status: draft
---

# Feature: {Title}

## Overview
[2-3 sentence summary]

## Problem Statement
[What problem does this solve?]

## User Stories
- As a [user], I want to [action] so that [benefit]

## Acceptance Criteria
- [ ] AC1: ...

## Non-Functional Requirements
[Performance, security, availability]

## Out of Scope
[What this feature does NOT include]

## Dependencies
[Other features, patterns, infrastructure]

## Open Questions
[Must be empty before approval]
```

### 4. Update SDLC State
```bash
sdlc artifact create $ARGUMENTS spec
```

### 5. Output Summary
```markdown
## Created: spec.md

**Feature:** {slug}
**Path:** `.sdlc/features/{slug}/spec.md`
**Status:** draft

### Next Steps
Run `sdlc next --for {slug}` to see required action (approval needed).
```
```

#### `/implement-task` Template
```markdown
---
description: Implement a specific task from the task breakdown
argument-hint: <feature-slug> <task-id>
allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Task
---

Implement task $ARGUMENTS

## Instructions

### 1. Load Task Context
```bash
sdlc task show {feature} {task-id}
```

### 2. Load Feature Context
Read:
- `.sdlc/features/{feature}/spec.md` - Requirements
- `.sdlc/features/{feature}/design.md` - Architecture
- `.sdlc/features/{feature}/tasks.md` - Full task list

### 3. Mark Task In-Progress
```bash
sdlc task start {feature} {task-id}
```

### 4. Implement
Follow the task specification. Ensure:
- Code follows required patterns
- Tests included
- No tech debt introduced

### 5. Update Task Status
```bash
sdlc task complete {feature} {task-id}
```

### 6. Output Summary
```markdown
## Completed: {task-id}

**Feature:** {feature}
**Task:** {task-title}
**Files Modified:**
- {list of files}

**Tests Added:**
- {list of tests}

### Task Progress
{completed}/{total} tasks complete

### Next Steps
Run `sdlc next --for {feature}` to continue.
```
```

### Exit Criteria

- [ ] Each command produces artifact at documented location
- [ ] Each command updates SDLC state
- [ ] Each command has structured output format
- [ ] `/next` integrates with `sdlc next` CLI
- [ ] `/deliver` orchestrates full delivery flow

---

## Week 7: Git Integration & Branch Management

**Goal:** Complete git operations for branch lifecycle and merge flow.

### Deliverables

| File | Action | Description |
|------|--------|-------------|
| `internal/handlers/sdlc_branches.go` | CREATE | Branch endpoints |
| `internal/handlers/sdlc_merge.go` | CREATE | Merge endpoint |
| `internal/service/sdlc_git.go` | CREATE | Git operations service |
| `cmd/sdlc/cmd/merge.go` | CREATE | `sdlc merge` command |
| `.../skeleton/.claude/commands/merge-feature.md` | CREATE | Merge command |

### API Endpoints

```
POST /projects/{project}/sdlc/branches
GET  /projects/{project}/sdlc/branches/{branch}
POST /projects/{project}/sdlc/branches/{branch}/sync
POST /projects/{project}/sdlc/merge
```

### Implementation Details

#### Branch Creation
```go
func (s *SDLCService) CreateBranch(ctx context.Context, project, feature string) (*BranchInfo, error) {
    // 1. Verify feature is in 'planned' phase
    f, err := s.GetFeature(ctx, project, feature)
    if f.Phase != PhasePlanned {
        return nil, domain.ErrInvalidPhase
    }

    // 2. Create branch
    branchName := fmt.Sprintf("feature/%s", feature)
    err = s.gitOps.CreateBranch(ctx, project, branchName, "main")

    // 3. Track branch in .sdlc/branches/{branch}.yaml
    s.writeBranchManifest(ctx, project, branchName, feature)

    // 4. Update feature manifest
    f.Branch = branchName
    s.SaveFeature(ctx, project, f)

    // 5. Transition to 'ready'
    s.TransitionFeature(ctx, project, feature, PhaseReady)

    return &BranchInfo{Name: branchName, Feature: feature}, nil
}
```

#### Merge Flow
```go
func (s *SDLCService) Merge(ctx context.Context, project string, req MergeRequest) (*MergeResult, error) {
    // 1. Verify feature completed all gates
    f, err := s.GetFeature(ctx, project, req.Feature)
    if f.Phase != PhaseMerge {
        return nil, domain.ErrNotReadyToMerge
    }

    // Gates checklist
    gates := []string{"review_passed", "audit_passed", "qa_passed"}
    for _, gate := range gates {
        if !f.GatePassed(gate) {
            return nil, fmt.Errorf("gate not passed: %s", gate)
        }
    }

    // 2. Merge branch
    switch req.Strategy {
    case "squash":
        err = s.gitOps.SquashMerge(ctx, project, f.Branch, "main")
    case "merge":
        err = s.gitOps.Merge(ctx, project, f.Branch, "main")
    }

    // 3. Delete branch if requested
    if req.DeleteBranch {
        s.gitOps.DeleteBranch(ctx, project, f.Branch)
    }

    // 4. Transition to 'released'
    s.TransitionFeature(ctx, project, req.Feature, PhaseReleased)

    // 5. Archive feature
    s.ArchiveFeature(ctx, project, req.Feature)

    return &MergeResult{...}, nil
}
```

### CLI Commands

```bash
sdlc branch create <feature>   # Create feature branch
sdlc branch status <feature>   # Show branch state + checklist
sdlc branch sync <feature>     # Rebase on main
sdlc merge <feature>           # Merge feature to main
sdlc archive <feature>         # Move to .sdlc/archives/
```

### Tests

- `internal/handlers/sdlc_branches_test.go`
- `internal/handlers/sdlc_merge_test.go`
- Integration: Full feature lifecycle with branch

### Exit Criteria

- [ ] Branch created for feature in 'planned' phase
- [ ] Branch status shows merge checklist
- [ ] Sync rebases on main
- [ ] Merge validates all gates
- [ ] Archive moves feature to archives/

---

## Week 8: Polish, Documentation & Validation

**Goal:** Complete documentation, validate full workflow, and polish UX.

### Deliverables

| File | Action | Description |
|------|--------|-------------|
| `docs/guides/sdlc/getting-started.md` | CREATE | Quick start guide |
| `docs/guides/sdlc/cli-reference.md` | CREATE | Full CLI docs |
| `docs/guides/sdlc/api-reference.md` | CREATE | API docs |
| `docs/guides/sdlc/command-catalog.md` | CREATE | Claude command docs |
| `.claude/guides/services/sdlc.md` | CREATE | Guide entry point |
| `CLAUDE.md` | MODIFY | Add SDLC guide link |
| `cookbooks/scripts/sdlc-test.sh` | CREATE | E2E validation script |

### Validation Scenarios

#### Scenario 1: Full Feature Delivery
```bash
# Initialize SDLC
sdlc init

# Create feature
sdlc feature create user-auth

# Run through full lifecycle via API
curl -X POST $API/projects/test/sdlc/features/user-auth/execute \
  -d '{"action": "CREATE_SPEC"}'

# Keep running until complete
while true; do
  NEXT=$(curl $API/projects/test/sdlc/next?feature=user-auth)
  if [ "$NEXT.action" == "IDLE" ]; then break; fi
  curl -X POST $API/projects/test/sdlc/execute -d "$NEXT"
done
```

#### Scenario 2: Blocker Resolution
```bash
# Get blocked items
BLOCKED=$(curl $API/projects/test/sdlc/blocked)

# Resolve design decision
curl -X POST $API/projects/test/sdlc/resolve \
  -d '{"feature": "user-auth", "answer": "jwt"}'

# Verify unblocked
curl $API/projects/test/sdlc/next?feature=user-auth
```

#### Scenario 3: Claude Command Integration
```bash
# In Claude Code session
/spec-feature user-auth
# → Creates .sdlc/features/user-auth/spec.md

/next
# → Shows next action (await approval)

# User approves
sdlc artifact approve user-auth spec

/next
# → Shows CREATE_DESIGN action

/design-feature user-auth
# → Creates design.md

# Continue through full delivery...
```

### Documentation Structure

```
docs/guides/sdlc/
├── getting-started.md    # 5-min quickstart
├── concepts.md           # State machine, classifier, artifacts
├── cli-reference.md      # Full sdlc CLI docs
├── api-reference.md      # Full API docs with examples
├── command-catalog.md    # All Claude commands
├── patterns.md           # Pattern management
└── troubleshooting.md    # Common issues
```

### Exit Criteria

- [ ] E2E test script runs full feature delivery
- [ ] All documentation complete
- [ ] CLAUDE.md updated with guide link
- [ ] `sdlc` CLI has `--help` for all commands
- [ ] API returns helpful error messages
- [ ] Blocker resolution flow works end-to-end

---

## Risk Mitigation

### Risk: Complex Git Operations
**Mitigation:** Use existing `PodGitOperations` adapter, add integration tests with real git repos.

### Risk: Classifier Rule Complexity
**Mitigation:** Start with feature lifecycle rules only, add pattern rules in follow-up.

### Risk: State Corruption
**Mitigation:** All state changes go through `sdlc` CLI which validates, add recovery command.

### Risk: Command Output Verification
**Mitigation:** Each command has explicit output path, executor verifies file exists.

---

## Dependencies

| Dependency | Required For | Status |
|------------|--------------|--------|
| `PodGitOperations` | Git operations in pods | ✓ Exists |
| `cobra` CLI framework | `sdlc` CLI | Add to go.mod |
| Project pod executor | Command execution | ✓ Exists |
| YAML parsing | State/manifest | ✓ `gopkg.in/yaml.v3` |

---

## Follow-Up Work (Post-MVP)

1. **Pattern Management** - Full pattern lifecycle (elevate, examples, violations)
2. **Roadmap Management** - Version roadmaps, milestones
3. **Audit System** - Codebase-wide audits
4. **Metrics Dashboard** - Cycle time, velocity tracking
5. **SSE Streaming** - Real-time execution status
6. **Rollback Support** - Phase rollback with cleanup
7. **Custom Rules** - Project-specific classifier rules
8. **CI Integration** - Auto-trigger SDLC actions from Woodpecker