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

description	allowed-tools
Implement a task from the workflow	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

# 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:

// 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

'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:

interface SongCardProps {
  id: string;
  title: string;
  artistName: string;  // WRONG!
}

✅ CORRECT - Use typed object props from design:

import type { SongCardProps } from '@/types/component-props';
// Props are: { song: Song, showArtist?: boolean, showAlbum?: boolean }

API Routes (Next.js App Router)

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:

model [ModelName] {
  // Fields from design_document.yml data_models section
  // Match: name, type, constraints
}

Post-Implementation Validation

After implementing, run validation:

# 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:

   cat .workflow/versions/v001/contexts/component_song_card.yml
   

2. Check generated types:

   cat types/component-props.ts | grep -A 10 "SongCardProps"
   

3. Implement matching design:

   '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:

   python3 skills/guardrail-orchestrator/scripts/workflow_manager.py validate
   

Checklist Reference Update

After successful implementation, mark the item as checked:

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