project-standalo-sonic-cloud/.claude/commands/guardrail/workflow.md

---
description: Orchestrate the full implementation workflow
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Task
---

# Workflow Orchestrator

Command: "$ARGUMENTS"

## Workflow Phases

```
INITIALIZING → DESIGNING → AWAITING_DESIGN_APPROVAL → DESIGN_APPROVED
     ↓                                                       ↓
   [create]                                           [generate-types]
                                                            ↓
                                                      IMPLEMENTING
                                                            ↓
                                                    [validate --checklist]
                                                            ↓
                                                       REVIEWING
                                                            ↓
                                                    SECURITY_REVIEW
                                                            ↓
                                                 AWAITING_IMPL_APPROVAL
                                                            ↓
                                                      COMPLETED
```

## Commands

### Start New Workflow
```bash
/guardrail:workflow start "feature description"
```

### Check Status
```bash
/guardrail:workflow status
```

### Generate Types (after design approval)
```bash
/guardrail:workflow generate-types
```

### Implement Task
```bash
/guardrail:workflow implement <task_id>
# or implement all Layer 1 tasks:
/guardrail:workflow implement --layer 1
```

### Validate
```bash
/guardrail:workflow validate
```

### View Checklist
```bash
/guardrail:workflow checklist
```

---

## Execution Flow

### Phase: DESIGN_APPROVED → IMPLEMENTING

When design is approved, ALWAYS run these steps first:

1. **Generate TypeScript types from design:**
   ```bash
   python3 skills/guardrail-orchestrator/scripts/workflow_manager.py generate-types --output-dir types
   ```

2. **Transition to IMPLEMENTING:**
   ```bash
   python3 skills/guardrail-orchestrator/scripts/workflow_manager.py transition IMPLEMENTING
   ```

3. **View dependency graph to understand task order:**
   ```bash
   cat .workflow/versions/v001/dependency_graph.yml
   ```

### Phase: IMPLEMENTING

For each task (respecting dependency layers):

1. **Read task context:**
   ```bash
   cat .workflow/versions/v001/contexts/<entity_id>.yml
   ```

2. **Read generated types:**
   ```bash
   cat types/component-props.ts  # For components
   cat types/types.ts            # For models
   cat types/api-types.ts        # For APIs
   ```

3. **Implement following the design EXACTLY**
   - Import types from `@/types`
   - Use typed props (not flat props)
   - Implement all events
   - Match field names exactly

4. **Update task status:**
   ```bash
   python3 skills/guardrail-orchestrator/scripts/workflow_manager.py task <task_id> completed
   ```

5. **Run validation after each layer:**
   ```bash
   python3 skills/guardrail-orchestrator/scripts/workflow_manager.py validate --checklist
   ```

### Phase: REVIEWING

1. **Run full validation:**
   ```bash
   python3 skills/guardrail-orchestrator/scripts/workflow_manager.py validate --checklist
   ```

2. **Fix any remaining issues**

3. **Run type check:**
   ```bash
   npx tsc --noEmit
   ```

4. **Run linter:**
   ```bash
   npm run lint
   ```

5. **Transition to security review:**
   ```bash
   python3 skills/guardrail-orchestrator/scripts/workflow_manager.py transition SECURITY_REVIEW
   ```

---

## Implementation Rules (MANDATORY)

### Rule 1: Always Import Generated Types

```typescript
// ✅ CORRECT
import type { SongCardProps } from '@/types/component-props';
import type { Song } from '@/types';

// ❌ WRONG - defining own interface
interface SongCardProps {
  id: string;
  title: string;
}
```

### Rule 2: Use Object Props, Not Flat Props

```typescript
// ✅ CORRECT - design says: song: Song
function SongCard({ song, showArtist }: SongCardProps) {
  return <div>{song.title} by {song.artist?.name}</div>;
}

// ❌ WRONG - flattening the Song object
function SongCard({ id, title, artistName }: SongCardProps) {
  return <div>{title} by {artistName}</div>;
}
```

### Rule 3: Implement ALL Events from Design

```typescript
// Design specifies: onPlay, onAddToPlaylist
// ✅ CORRECT - both events implemented
function SongCard({ song, onPlay, onAddToPlaylist }: SongCardProps) {
  return (
    <div>
      <button onClick={() => onPlay?.({ songId: song.id })}>Play</button>
      <button onClick={() => onAddToPlaylist?.({ songId: song.id })}>Add</button>
    </div>
  );
}
```

### Rule 4: Match Prisma Schema to Design

```prisma
// Design says: role enum with values [musician, listener, label]
model User {
  role    UserRole  // ✅ Use enum
}

enum UserRole {
  musician
  listener
  label
}
```

### Rule 5: Validate After Each Implementation

```bash
# After implementing, always validate
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py validate

# Mark task complete only if validation passes
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py task <task_id> completed
```

---

## Quick Reference

| Phase | Action | Command |
|-------|--------|---------|
| Start | Create workflow | `version_manager.py create "feature"` |
| Design | Validate design | `validate_design.py` |
| Approved | Generate types | `workflow_manager.py generate-types` |
| Implement | Start task | Read context → Import types → Code |
| Validate | Check impl | `workflow_manager.py validate --checklist` |
| Review | Fix issues | Check errors → Fix → Re-validate |
| Complete | Archive | `workflow_manager.py transition COMPLETED` |