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

---
description: Implement a task from the workflow
allowed-tools: Read, Write, Edit, Bash, Glob, Grep
---

# Implement Task

Implement the task: "$ARGUMENTS"

## ⚠️ CRITICAL: WORKFLOW COMPLIANCE

You MUST follow the design document exactly. All implementations must match the specifications.

## Pre-Implementation Checklist

Before writing ANY code, complete these steps:

### 1. Load Workflow Context

```bash
# Check workflow status
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py status

# Verify we're in IMPLEMENTING phase
```

### 2. Find Task Context

Read the task file and context for the entity you're implementing:

```
.workflow/versions/v001/tasks/task_create_<entity_id>.yml
.workflow/versions/v001/contexts/<entity_id>.yml
```

### 3. Load Generated Types (MANDATORY)

**ALWAYS** import and use the generated types:

```typescript
// For components - import from generated types
import type { SongCardProps } from '@/types/component-props';
import type { Song, Album, Artist } from '@/types';

// For APIs - import request/response types
import type { GetSongResponse } from '@/types/api-types';
```

### 4. Read Design Specification

The context file contains the EXACT specification you must follow:
- `target.definition.props` - Component props (use these EXACTLY)
- `target.definition.events` - Event handlers (implement ALL)
- `target.definition.fields` - Model fields (match EXACTLY)
- `acceptance` - Acceptance criteria to satisfy

## Implementation Rules

### Components

```tsx
'use client'

// STEP 1: Import generated types (REQUIRED)
import type { [ComponentName]Props } from '@/types/component-props';
import type { Song, Album, Artist } from '@/types';

// STEP 2: Use the imported interface (DO NOT redefine props)
export function [ComponentName]({
  // Destructure props matching the design spec EXACTLY
}: [ComponentName]Props) {

  // STEP 3: Implement all events from the design

  return (
    // JSX implementation
  );
}
```

**❌ WRONG - Do not flatten object props:**
```tsx
interface SongCardProps {
  id: string;
  title: string;
  artistName: string;  // WRONG!
}
```

**✅ CORRECT - Use typed object props from design:**
```tsx
import type { SongCardProps } from '@/types/component-props';
// Props are: { song: Song, showArtist?: boolean, showAlbum?: boolean }
```

### API Routes (Next.js App Router)

```typescript
import { NextRequest, NextResponse } from 'next/server';
import type { [EndpointName]Request, [EndpointName]Response } from '@/types/api-types';

export async function [METHOD](request: NextRequest) {
  // Implement according to design spec
  // - Validate request body against schema
  // - Return response matching schema
}
```

### Prisma Models

Match the design document field names and types exactly:
```prisma
model [ModelName] {
  // Fields from design_document.yml data_models section
  // Match: name, type, constraints
}
```

## Post-Implementation Validation

After implementing, run validation:

```bash
# Type check
npx tsc --noEmit

# Run implementation validator
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py validate

# Update task status
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py task <task_id> completed
```

## Example: Implementing SongCard

1. **Read context:**
   ```bash
   cat .workflow/versions/v001/contexts/component_song_card.yml
   ```

2. **Check generated types:**
   ```bash
   cat types/component-props.ts | grep -A 10 "SongCardProps"
   ```

3. **Implement matching design:**
   ```tsx
   'use client'

   import type { SongCardProps } from '@/types/component-props';
   import type { Song } from '@/types';

   export function SongCard({
     song,           // Song object, not flat props!
     showArtist = true,
     showAlbum = false,
     onPlay,
     onAddToPlaylist
   }: SongCardProps) {
     return (
       <div onClick={() => onPlay?.({ songId: song.id })}>
         <img src={song.coverArtUrl} alt={song.title} />
         <h3>{song.title}</h3>
         {showArtist && <p>{song.artist?.name}</p>}
         {showAlbum && <p>{song.album?.title}</p>}
       </div>
     );
   }
   ```

4. **Validate:**
   ```bash
   python3 skills/guardrail-orchestrator/scripts/workflow_manager.py validate
   ```

## Checklist Reference Update

After successful implementation, mark the item as checked:

```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py checklist check \
  --item component_song_card \
  --reference "components/SongCard.tsx:1-50"
```