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

description	allowed-tools
Orchestrate the full implementation workflow	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

/guardrail:workflow start "feature description"

Check Status

/guardrail:workflow status

Generate Types (after design approval)

/guardrail:workflow generate-types

Implement Task

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

Validate

/guardrail:workflow validate

View Checklist

/guardrail:workflow checklist

---

Execution Flow

Phase: DESIGN_APPROVED → IMPLEMENTING

When design is approved, ALWAYS run these steps first:

1. Generate TypeScript types from design:

   python3 skills/guardrail-orchestrator/scripts/workflow_manager.py generate-types --output-dir types
   

2. Transition to IMPLEMENTING:

   python3 skills/guardrail-orchestrator/scripts/workflow_manager.py transition IMPLEMENTING
   

3. View dependency graph to understand task order:

   cat .workflow/versions/v001/dependency_graph.yml
   

Phase: IMPLEMENTING

For each task (respecting dependency layers):

1. Read task context:

   cat .workflow/versions/v001/contexts/<entity_id>.yml
   

2. Read generated types:

   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:

   python3 skills/guardrail-orchestrator/scripts/workflow_manager.py task <task_id> completed
   

5. Run validation after each layer:

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

Phase: REVIEWING

1. Run full validation:

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

2. Fix any remaining issues

3. Run type check:

   npx tsc --noEmit
   

4. Run linter:

   npm run lint
   

5. Transition to security review:

   python3 skills/guardrail-orchestrator/scripts/workflow_manager.py transition SECURITY_REVIEW
   

---

Implementation Rules (MANDATORY)

Rule 1: Always Import Generated Types

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

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

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

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

# 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