# Guardrail Workflow System - Architecture Documentation

**Generated**: 2025-12-18
**Version**: 1.0.0

---

## Table of Contents

1. [System Overview](#system-overview)
2. [Architecture Diagram](#architecture-diagram)
3. [Phase State Machine](#phase-state-machine)
4. [Core Scripts Reference](#core-scripts-reference)
5. [Hook System](#hook-system)
6. [Agent Integration](#agent-integration)
7. [Recent Enhancements](#recent-enhancements)
8. [Implementation Guide](#implementation-guide)

---

## System Overview

The Guardrail Workflow System enforces a design-first development methodology through **hook-based interception** and **phase-based state management**. AI agents cannot bypass the workflow because all file operations are intercepted and validated before execution.

### Key Design Principles

| Principle | Implementation |
|-----------|----------------|
| **Design Before Code** | Hooks block implementation file writes until design is approved |
| **State Machine Enforcement** | All transitions validated through `workflow_manager.py` |
| **Parallel Execution** | Backend and frontend teams work simultaneously on separate layers |
| **Type Safety** | Generated TypeScript types ensure frontend-backend alignment |
| **Contract Validation** | API contracts validated to prevent integration issues |

### System Components

```
┌─────────────────────────────────────────────────────────────┐
│                    GUARDRAIL WORKFLOW SYSTEM                 │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌───────────────┐   ┌────────────────┐   ┌─────────────┐ │
│  │ Hook System   │   │ State Machine  │   │   Scripts   │ │
│  │ (settings.json│──▶│ (session.yml)  │◀──│ (Python)    │ │
│  └───────────────┘   └────────────────┘   └─────────────┘ │
│         │                     │                    │        │
│         ▼                     ▼                    ▼        │
│  ┌───────────────┐   ┌────────────────┐   ┌─────────────┐ │
│  │ Tool Matchers │   │ Phase Guards   │   │ Validators  │ │
│  │ (Write/Edit)  │   │ (Transitions)  │   │ (Design)    │ │
│  └───────────────┘   └────────────────┘   └─────────────┘ │
│         │                     │                    │        │
│         └─────────────────────┴────────────────────┘        │
│                              │                              │
│                              ▼                              │
│                    ┌────────────────┐                       │
│                    │ Version Manager│                       │
│                    │ (.workflow/)   │                       │
│                    └────────────────┘                       │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

---

## Architecture Diagram

### Complete System Flow

```
╔═══════════════════════════════════════════════════════════════════════╗
║                    WORKFLOW EXECUTION ARCHITECTURE                     ║
╠═══════════════════════════════════════════════════════════════════════╣
║                                                                       ║
║  USER COMMAND: /workflow:spawn "add authentication"                  ║
║       │                                                               ║
║       ▼                                                               ║
║  ┌──────────────────────────────────────────────────────────┐        ║
║  │ PHASE 1: INITIALIZE                                      │        ║
║  │  • Parse arguments (--auto, --full-auto)                 │        ║
║  │  • Verify prerequisites (project_manifest.json)          │        ║
║  │  • version_manager.py create → vXXX                      │        ║
║  │  • workflow_manager.py transition DESIGNING              │        ║
║  └──────────────────────────────────────────────────────────┘        ║
║       │                                                               ║
║       ▼                                                               ║
║  ┌──────────────────────────────────────────────────────────┐        ║
║  │ PHASE 2: DESIGNING                                       │        ║
║  │  • Spawn: system-architect agent (Task tool)             │        ║
║  │  • Generate: design_document.yml                         │        ║
║  │  • Run: validate_design.py                               │        ║
║  │    ├─▶ dependency_graph.yml (layered execution)          │        ║
║  │    ├─▶ contexts/*.yml (entity snapshots)                 │        ║
║  │    └─▶ tasks/*.yml (implementation tasks)                │        ║
║  │  • Run: generate_api_contract.py                         │        ║
║  │    ├─▶ contracts/api_contract.yml                        │        ║
║  │    └─▶ app/types/api.ts (shared types)                   │        ║
║  │  • transition → AWAITING_DESIGN_APPROVAL                 │        ║
║  └──────────────────────────────────────────────────────────┘        ║
║       │                                                               ║
║       ▼                                                               ║
║  ┌──────────────────────────────────────────────────────────┐        ║
║  │ GATE 1: DESIGN APPROVAL                                  │        ║
║  │  IF --auto: workflow_manager.py approve design           │        ║
║  │  IF manual: Wait for /workflow:approve                   │        ║
║  │  • transition → DESIGN_APPROVED                          │        ║
║  └──────────────────────────────────────────────────────────┘        ║
║       │                                                               ║
║       ▼                                                               ║
║  ┌──────────────────────────────────────────────────────────┐        ║
║  │ PHASE 3.5: TYPE GENERATION (MANDATORY)                   │        ║
║  │  • Run: generate_types.py                                │        ║
║  │    ├─▶ types/types.ts (model interfaces)                 │        ║
║  │    ├─▶ types/component-props.ts (component props)        │        ║
║  │    ├─▶ types/api-types.ts (request/response types)       │        ║
║  │    └─▶ types/index.ts (re-exports)                       │        ║
║  │  • Generate: IMPLEMENTATION_CONTEXT.md                   │        ║
║  │  • transition → IMPLEMENTING                             │        ║
║  └──────────────────────────────────────────────────────────┘        ║
║       │                                                               ║
║       ▼                                                               ║
║  ┌──────────────────────────────────────────────────────────┐        ║
║  │ PHASE 4: IMPLEMENTING (PARALLEL TEAMS)                   │        ║
║  │                                                           │        ║
║  │  ┌──────────────────┐     ┌────────────────────┐         │        ║
║  │  │ BACKEND TEAM     │     │ FRONTEND TEAM      │         │        ║
║  │  │ (backend-arch)   │ ||  │ (frontend-arch)    │         │        ║
║  │  │                  │     │                    │         │        ║
║  │  │ Layer 1: Models  │     │ Layer 3: Comp     │         │        ║
║  │  │ Layer 2: APIs    │     │ Layer 3: Pages    │         │        ║
║  │  │                  │     │                    │         │        ║
║  │  │ Export:          │     │ Import:            │         │        ║
║  │  │ /api/* routes    │──▶──│ app/types/api      │         │        ║
║  │  └──────────────────┘     └────────────────────┘         │        ║
║  │                                                           │        ║
║  │  SHARED CONTRACT: app/types/api.ts                       │        ║
║  │                                                           │        ║
║  │  • Both agents read: IMPLEMENTATION_CONTEXT.md           │        ║
║  │  • Both agents use: Generated types from types/*         │        ║
║  │  • Hook validation: validate_write.py checks paths       │        ║
║  │  • Run: workflow_manager.py validate --checklist         │        ║
║  │  • Run: validate_against_contract.py                     │        ║
║  │  • transition → REVIEWING                                │        ║
║  └──────────────────────────────────────────────────────────┘        ║
║       │                                                               ║
║       ▼                                                               ║
║  ┌──────────────────────────────────────────────────────────┐        ║
║  │ PHASE 5: REVIEWING                                       │        ║
║  │  • Run: npm run build (MUST pass)                        │        ║
║  │  • Check: All task files exist                           │        ║
║  │  • Run: visualize_implementation.py                      │        ║
║  │  IF --auto: Auto-approve if build passes                 │        ║
║  │  IF manual: Spawn quality-engineer agent                 │        ║
║  │  • transition → SECURITY_REVIEW                          │        ║
║  └──────────────────────────────────────────────────────────┘        ║
║       │                                                               ║
║       ▼                                                               ║
║  ┌──────────────────────────────────────────────────────────┐        ║
║  │ PHASE 5.5: SECURITY_REVIEW (NEW)                         │        ║
║  │  • Run: security_scan.py --severity HIGH                 │        ║
║  │  • Run: validate_against_contract.py                     │        ║
║  │  • Run: validate_api_contract.py                         │        ║
║  │  IF CRITICAL issues: transition → IMPLEMENTING           │        ║
║  │  IF PASS: transition → AWAITING_IMPL_APPROVAL            │        ║
║  └──────────────────────────────────────────────────────────┘        ║
║       │                                                               ║
║       ▼                                                               ║
║  ┌──────────────────────────────────────────────────────────┐        ║
║  │ GATE 2: IMPLEMENTATION APPROVAL                          │        ║
║  │  IF --auto: workflow_manager.py approve implementation   │        ║
║  │  IF manual: Wait for /workflow:approve                   │        ║
║  │  • transition → COMPLETING                               │        ║
║  └──────────────────────────────────────────────────────────┘        ║
║       │                                                               ║
║       ▼                                                               ║
║  ┌──────────────────────────────────────────────────────────┐        ║
║  │ PHASE 7: COMPLETING                                      │        ║
║  │  • Update: All task statuses → completed                 │        ║
║  │  • Update: Manifest statuses → IMPLEMENTED               │        ║
║  │  • Run: version_manager.py complete                      │        ║
║  │  • Display: Final report                                 │        ║
║  │  • State: COMPLETED                                      │        ║
║  └──────────────────────────────────────────────────────────┘        ║
║                                                                       ║
╚═══════════════════════════════════════════════════════════════════════╝
```

---

## Phase State Machine

### State Diagram

```
                    ┌─────────────────┐
                    │  INITIALIZING   │
                    └────────┬────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │    DESIGNING    │
                    └────────┬────────┘
                             │
                             ▼
              ┌──────────────────────────────┐
              │ AWAITING_DESIGN_APPROVAL     │
              └──────┬──────────────┬────────┘
                     │              │
           ┌─────────▼──────┐       ▼────────────┐
           │ DESIGN_APPROVED│   │DESIGN_REJECTED│
           └─────────┬──────┘   └────────┬───────┘
                     │                   │
                     ▼                   │
        ┌────────────────────┐           │
        │ (Type Generation)  │           │
        └────────┬───────────┘           │
                 │                       │
                 ▼                       │
        ┌─────────────────┐              │
        │  IMPLEMENTING   │◀─────────────┘
        └────────┬────────┘
                 │
                 ▼
        ┌─────────────────┐
        │    REVIEWING    │
        └────────┬────────┘
                 │
                 ▼
        ┌─────────────────┐
        │ SECURITY_REVIEW │
        └────┬──────────┬─┘
             │          │
             │          └──────────────┐
             ▼                         │
   ┌────────────────────────┐          │
   │AWAITING_IMPL_APPROVAL  │          │
   └────┬──────────┬────────┘          │
        │          │                   │
        │          └──────┐            │
        ▼                 ▼            │
┌───────────────┐  ┌──────────────┐   │
│ IMPL_APPROVED │  │IMPL_REJECTED │───┘
└───────┬───────┘  └──────────────┘
        │
        ▼
┌───────────────┐
│  COMPLETING   │
└───────┬───────┘
        │
        ▼
┌───────────────┐
│   COMPLETED   │
└───────────────┘
```

### State Transition Table

| From State | To States | Trigger | Script |
|-----------|----------|---------|---------|
| INITIALIZING | DESIGNING | Version created | version_manager.py create |
| DESIGNING | AWAITING_DESIGN_APPROVAL | Design validated | validate_design.py |
| AWAITING_DESIGN_APPROVAL | DESIGN_APPROVED | User approval | workflow_manager.py approve |
| AWAITING_DESIGN_APPROVAL | DESIGN_REJECTED | User rejection | workflow_manager.py reject |
| DESIGN_REJECTED | DESIGNING | Restart design | workflow_manager.py transition |
| DESIGN_APPROVED | IMPLEMENTING | Types generated | generate_types.py |
| IMPLEMENTING | REVIEWING | Implementation complete | Both agents finish |
| REVIEWING | SECURITY_REVIEW | Build passes | npm run build |
| SECURITY_REVIEW | AWAITING_IMPL_APPROVAL | Security passes | security_scan.py |
| SECURITY_REVIEW | IMPLEMENTING | Critical issues | security_scan.py exit 2 |
| AWAITING_IMPL_APPROVAL | IMPL_APPROVED | User approval | workflow_manager.py approve |
| AWAITING_IMPL_APPROVAL | IMPL_REJECTED | User rejection | workflow_manager.py reject |
| IMPL_REJECTED | IMPLEMENTING | Restart impl | workflow_manager.py transition |
| IMPL_APPROVED | COMPLETING | Gate passed | workflow_manager.py transition |
| COMPLETING | COMPLETED | Version complete | version_manager.py complete |

---

## Core Scripts Reference

### Script Responsibility Matrix

| Script | Primary Function | Phase | Exit Codes |
|--------|------------------|-------|------------|
| `workflow_manager.py` | State machine management | All | 0=success, 1=error |
| `version_manager.py` | Version lifecycle | INIT, COMPLETE | 0=success, 1=error |
| `generate_types.py` | TypeScript generation | DESIGN_APPROVED | 0=success, 1=error |
| `validate_design.py` | Design validation + graph | DESIGNING | 0=valid, 1=invalid |
| `validate_workflow.py` | Hook-based phase guards | All | 0=allow, 1=block |
| `validate_write.py` | Manifest path validation | IMPLEMENTING | 0=allow, 1=block |
| `validate_bash.py` | Shell command blocking | All | 0=allow, 1=block |
| `validate_api_contract.py` | API contract validation | SECURITY_REVIEW | 0=pass, 1=fail |
| `generate_api_contract.py` | API contract generation | DESIGNING | 0=success, 1=error |
| `security_scan.py` | Security vulnerability scan | SECURITY_REVIEW | 0=pass, 1=warn, 2=critical |
| `post_write.py` | Auto-update manifest status | Post-write hook | 0=success |

### workflow_manager.py

**Purpose**: Core state machine management, validation, checkpoints.

**Commands**:
```bash
# State queries
workflow_manager.py status                    # Show current state
workflow_manager.py exists                    # Check if workflow active (0=yes, 1=no)

# State transitions
workflow_manager.py transition <PHASE>        # Transition to phase
workflow_manager.py approve <gate>            # Approve gate (design|implementation)
workflow_manager.py reject <gate> "reason"    # Reject gate

# Progress tracking
workflow_manager.py progress --tasks-created 5 --tasks-impl 3
workflow_manager.py task <task_id> <status>   # Update task status

# Validation (NEW)
workflow_manager.py validate --checklist      # Validate impl vs design

# Checkpoints (for long operations)
workflow_manager.py checkpoint save -d "desc" # Save checkpoint
workflow_manager.py checkpoint list           # List checkpoints
workflow_manager.py checkpoint restore        # Restore last checkpoint
```

**State File**: `.workflow/versions/vXXX/session.yml`

**Key Features** (Recent):
- **Validation Checklist**: `validate --checklist` verifies:
  - Components import from `@/types/component-props`
  - Components use object props (not flat)
  - All events from design are implemented
  - API routes exist with correct HTTP methods
  - Prisma models match design fields

### version_manager.py

**Purpose**: Manage version lifecycle (create, activate, complete).

**Commands**:
```bash
version_manager.py create "feature description"  # Create new version
version_manager.py activate <version_id>         # Switch active version
version_manager.py complete                      # Mark version complete
version_manager.py list                          # List all versions
version_manager.py status                        # Show active version
```

**Key Features** (Recent):
- **Dynamic Version Paths**: Automatically determines active version from `.workflow/current.yml`
- All scripts use dynamic version lookup instead of hardcoded paths

### generate_types.py

**Purpose**: Generate TypeScript types from `design_document.yml`.

**Commands**:
```bash
generate_types.py design_document.yml --output-dir types
```

**Generated Files**:
- `types/types.ts` - Model interfaces
- `types/component-props.ts` - Component prop interfaces with typed objects
- `types/api-types.ts` - Request/response types
- `types/index.ts` - Re-exports all types

**Key Features** (NEW - Recently Added):
- **Object Props**: Component props use typed objects (e.g., `song: Song`) instead of flat props
- **Event Payloads**: Generates event payload types for component events
- **API Types**: Request/response interfaces for all endpoints
- **Index Re-exports**: Single import point for all types

**Type Mapping**:
| Design Type | TypeScript Type |
|-------------|-----------------|
| string | string |
| integer | number |
| boolean | boolean |
| datetime | string (ISO) |
| enum | 'value1' \| 'value2' |
| json | Record<string, unknown> |

### validate_design.py

**Purpose**: Validate design document structure and generate artifacts.

**Commands**:
```bash
validate_design.py design_document.yml --output-dir .workflow/versions/vXXX
```

**Validation Checks**:
1. **Model Validation**: Primary keys, field types, enum values, relation targets
2. **API Validation**: HTTP methods, request bodies, responses, model dependencies
3. **Page Validation**: Routes, data needs, component references
4. **Component Validation**: Props, events, API usage, child components
5. **Circular Dependencies**: Detects circular references in dependency graph

**Generated Artifacts**:
- `dependency_graph.yml` - Layered execution order (Layer 1: Models, Layer 2: APIs, Layer 3: UI)
- `contexts/<entity_id>.yml` - Per-entity context snapshots with full definitions
- `tasks/task_<entity_id>.yml` - Implementation tasks with dependencies

**Dependency Layers**:
```
Layer 1 (Data Layer):    model_* (no dependencies, parallel execution)
Layer 2 (API Layer):     api_* (depends on models, parallel execution)
Layer 3 (UI Layer):      component_*, page_* (depends on APIs, parallel execution)
```

### validate_workflow.py

**Purpose**: Hook-based phase validation to block unauthorized operations.

**Hook Integration**:
```json
{
  "PreToolUse": [
    {
      "matcher": "Write",
      "hooks": [
        {
          "command": "python3 validate_workflow.py --operation write --file \"$TOOL_INPUT_FILE_PATH\""
        }
      ]
    }
  ]
}
```

**Phase Restrictions**:
| Phase | Write/Edit | Task Agents | Allowed Files |
|-------|-----------|-------------|---------------|
| NO_WORKFLOW | ✅ Any | ✅ Any | Any |
| DESIGNING | ⛔ Blocked | system-architect only | manifest, .workflow/, tasks/*.yml |
| IMPLEMENTING | ✅ Allowed | backend/frontend only | Files in task file_paths |
| REVIEWING | ⛔ Blocked | quality-engineer only | None (read-only) |
| SECURITY_REVIEW | ⛔ Blocked | security-engineer only | None (read-only) |

**Error Output**:
```
⛔ WORKFLOW VIOLATION: Cannot write implementation files during DESIGNING

Current Phase: DESIGNING
File: app/components/Button.tsx

During DESIGNING phase, only these files can be modified:
  - project_manifest.json
  - .workflow/versions/vXXX/tasks/*.yml

Complete design and get approval before implementing.
```

### validate_api_contract.py (NEW)

**Purpose**: Validate frontend-backend API contract alignment.

**Commands**:
```bash
validate_api_contract.py --project-dir .
```

**Validation Checks**:
1. **Frontend API Calls**: Detects `fetch()`, `axios`, `useSWR` patterns
2. **Backend Routes**: Validates `app/api/*/route.ts` exports, `pages/api/*.ts`
3. **Method Matching**: GET calls → GET endpoints, POST → POST, etc.
4. **Body Alignment**: POST/PUT with body, GET without body
5. **Unused Routes**: Warns about backend routes not called by frontend

**Exit Codes**:
- 0: All frontend calls matched to backend routes
- 1: Unmatched calls found (blocks security review)

### generate_api_contract.py (NEW)

**Purpose**: Generate API contract from design document.

**Commands**:
```bash
generate_api_contract.py design_document.yml --output-dir .workflow/versions/vXXX
```

**Generated Files**:
- `contracts/api_contract.yml` - Strict API type definitions
- `app/types/api.ts` - Shared TypeScript interfaces

**Contract Ensures**:
- Backend implements all specified endpoints
- Frontend imports from shared types
- Types not recreated locally

---

## Hook System

### Hook Configuration

Hooks are defined in `.claude/settings.json` and intercept tool usage at specific points.

### Hook Lifecycle

```
┌───────────────────────────────────────────────────────────┐
│                    HOOK EXECUTION FLOW                     │
├───────────────────────────────────────────────────────────┤
│                                                           │
│  AI attempts: Write tool                                 │
│       │                                                   │
│       ▼                                                   │
│  ┌────────────────────┐                                  │
│  │ PreToolUse Hook    │                                  │
│  │ (INTERCEPT)        │                                  │
│  └────────┬───────────┘                                  │
│           │                                               │
│           ├─▶ validate_workflow.py --operation write     │
│           │   └─▶ Check phase state                      │
│           │       └─▶ Exit 0 (allow) OR 1 (block)        │
│           │                                               │
│           └─▶ validate_write.py --manifest ... --file    │
│               └─▶ Check path in manifest                 │
│                   └─▶ Exit 0 (allow) OR 1 (block)        │
│                                                           │
│       IF ALL EXIT 0:                                      │
│       ▼                                                   │
│  ┌────────────────────┐                                  │
│  │ Tool Executes      │                                  │
│  │ (FILE WRITTEN)     │                                  │
│  └────────┬───────────┘                                  │
│           │                                               │
│           ▼                                               │
│  ┌────────────────────┐                                  │
│  │ PostToolUse Hook   │                                  │
│  │ (FINALIZE)         │                                  │
│  └────────┬───────────┘                                  │
│           │                                               │
│           └─▶ post_write.py --manifest ... --file        │
│               └─▶ Auto-update entity status              │
│                   └─▶ PENDING → IMPLEMENTED              │
│                                                           │
└───────────────────────────────────────────────────────────┘
```

### Matcher Patterns

| Matcher | Tools Intercepted | Purpose |
|---------|------------------|---------|
| `Bash` | Bash tool | Block file-writing shell commands |
| `Write` | Write tool | Phase and path validation |
| `Edit` | Edit tool | Phase and path validation |
| `MultiEdit` | MultiEdit tool | Phase and path validation |
| `Task` | Task tool (agents) | Agent type restrictions |
| `mcp__serena__*` | Serena MCP writes | All Serena file operations |
| `mcp__morphllm__*` | Morphllm MCP edits | All Morphllm operations |
| `mcp__filesystem__*` | Filesystem MCP | All filesystem writes |

### Hook Configuration Example

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/validate_workflow.py\" --operation write --file \"$TOOL_INPUT_FILE_PATH\""
          },
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/validate_write.py\" --manifest \"$CLAUDE_PROJECT_DIR/project_manifest.json\" --file \"$TOOL_INPUT_FILE_PATH\""
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/post_write.py\" --manifest \"$CLAUDE_PROJECT_DIR/project_manifest.json\" --file \"$TOOL_INPUT_FILE_PATH\""
          }
        ]
      }
    ]
  }
}
```

---

## Agent Integration

### Agent Roles

| Agent | Type | Phase | Purpose |
|-------|------|-------|---------|
| `system-architect` | Design | DESIGNING | Create design document, define entities |
| `backend-architect` | Implementation | IMPLEMENTING | Implement models and APIs (Layer 1+2) |
| `frontend-architect` | Implementation | IMPLEMENTING | Implement components and pages (Layer 3) |
| `quality-engineer` | Review | REVIEWING | Review implementation quality |
| `security-engineer` | Security | SECURITY_REVIEW | Security audit and vulnerability scan |

### Agent Team Structure (Parallel)

```
┌──────────────────────────────────────────────────────────────┐
│              PARALLEL TEAM EXECUTION MODEL                    │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│   ┌─────────────────────┐       ┌───────────────────────┐   │
│   │  BACKEND TEAM       │       │  FRONTEND TEAM        │   │
│   │  (backend-arch)     │  ||   │  (frontend-arch)      │   │
│   ├─────────────────────┤       ├───────────────────────┤   │
│   │                     │       │                       │   │
│   │ Layer 1: Models     │       │ Layer 3: Components   │   │
│   │   📦 model_user     │       │   🧩 component_button │   │
│   │   📦 model_post     │       │   🧩 component_card   │   │
│   │                     │       │                       │   │
│   │ Layer 2: APIs       │       │ Layer 3: Pages        │   │
│   │   🔌 api_get_users  │       │   📄 page_home        │   │
│   │   🔌 api_create_post│       │   📄 page_profile     │   │
│   │                     │       │                       │   │
│   │ Outputs:            │       │ Inputs:               │   │
│   │ • prisma/schema     │──▶────│ • import from @/types │   │
│   │ • app/api/*         │       │ • fetch('/api/*')     │   │
│   │ • Export types      │       │ • Use typed objects   │   │
│   │                     │       │                       │   │
│   └─────────────────────┘       └───────────────────────┘   │
│                                                              │
│   SHARED CONTRACT: app/types/api.ts                          │
│   CONTEXT: .workflow/versions/vXXX/IMPLEMENTATION_CONTEXT.md │
│                                                              │
└──────────────────────────────────────────────────────────────┘
```

### Agent Task Distribution

```
┌───────────────────────────────────────────────────────────┐
│              DEPENDENCY-BASED TASK ROUTING                 │
├───────────────────────────────────────────────────────────┤
│                                                           │
│  dependency_graph.yml                                     │
│  ├─ Layer 1 (models):    → backend-architect             │
│  ├─ Layer 2 (apis):      → backend-architect             │
│  └─ Layer 3 (ui):        → frontend-architect            │
│                                                           │
│  tasks/task_model_user.yml                                │
│    agent: backend                                         │
│    depends_on: []           ← No dependencies, start now  │
│                                                           │
│  tasks/task_api_get_users.yml                             │
│    agent: backend                                         │
│    depends_on: [model_user] ← Wait for Layer 1           │
│                                                           │
│  tasks/task_page_users.yml                                │
│    agent: frontend                                        │
│    depends_on: [api_get_users, component_card]           │
│                             ← Wait for Layer 2 + deps     │
│                                                           │
└───────────────────────────────────────────────────────────┘
```

### Agent Context Files

Each agent receives:

1. **IMPLEMENTATION_CONTEXT.md**: Generated rules and type definitions
2. **Task File** (`.workflow/versions/vXXX/tasks/task_*.yml`): Specific task definition
3. **Context File** (`.workflow/versions/vXXX/contexts/<entity_id>.yml`): Full entity context
4. **Generated Types** (`types/*.ts`): TypeScript interfaces to use

**Context File Structure**:
```yaml
task_id: task_create_component_button
entity_id: component_button
workflow_version: v003

target:
  type: component
  definition:
    id: component_button
    name: Button
    props: [...]
    events: [...]

related:
  models: []
  apis: []
  components: []

dependencies:
  entity_ids: [api_create_post]
  definitions: [...]

files:
  to_create:
    - app/components/Button.tsx

acceptance:
  - criterion: Component renders without errors
    verification: Import and render in test
```

---

## Recent Enhancements

### 1. Type Generation Script (generate_types.py)

**Added**: December 2024
**Purpose**: Automatic TypeScript type generation from design documents.

**Key Features**:
- **Model Interfaces**: Converts data models to TypeScript interfaces
- **Component Props**: Generates typed props with object structures
- **API Types**: Request/response interfaces for all endpoints
- **Event Payloads**: Typed event handler parameters

**Impact**: Eliminates type mismatches between frontend and backend.

### 2. Validation Checklist (workflow_manager.py validate --checklist)

**Added**: December 2024
**Purpose**: Verify implementation matches design specifications.

**Checks**:
```bash
workflow_manager.py validate --checklist
```

Output:
```
╔══════════════════════════════════════════════════════════╗
║           IMPLEMENTATION VALIDATION CHECKLIST            ║
╠══════════════════════════════════════════════════════════╣
║  Components checked: 5                                   ║
║  APIs checked:       8                                   ║
║  Models checked:     3                                   ║
╠══════════════════════════════════════════════════════════╣
║  PASSED (25)                                             ║
╠──────────────────────────────────────────────────────────╣
║  ✅ component_song_card: Props imported from @/types     ║
║  ✅ component_song_card: Object prop 'song' used         ║
║  ✅ component_song_card: Event 'onPlay' implemented      ║
╠══════════════════════════════════════════════════════════╣
║  ERRORS (2)                                              ║
╠──────────────────────────────────────────────────────────╣
║  ❌ component_player: Event 'onSeek' not implemented     ║
║  ❌ api_get_songs: Route file not found                  ║
╚══════════════════════════════════════════════════════════╝
```

**Impact**: Catches implementation deviations before review phase.

### 3. Dynamic Version Path Resolution

**Added**: December 2024
**Purpose**: Scripts automatically find active version from `.workflow/current.yml`.

**Before** (Hardcoded):
```bash
python3 generate_types.py .workflow/versions/v003/design/design_document.yml
```

**After** (Dynamic):
```bash
python3 generate_types.py  # Automatically finds v003 from current.yml
```

**Impact**: Simplifies commands, eliminates version path errors.

### 4. Heredoc Fix for Git Commits

**Added**: December 2024
**Purpose**: Proper heredoc formatting for multi-line commit messages.

**Before** (Broken):
```bash
git commit -m "Multi-line message
with Co-Authored-By"  # Breaks on newlines
```

**After** (Fixed):
```bash
git commit -m "$(cat <<'EOF'
Multi-line message

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"
```

**Impact**: Git operations work reliably with multi-line messages.

### 5. API Contract Validation

**Added**: December 2024
**Purpose**: Ensure frontend-backend API alignment.

**Scripts**:
- `generate_api_contract.py`: Generate contract from design
- `validate_against_contract.py`: Verify backend implements contract
- `validate_api_contract.py`: Verify frontend calls match backend

**Impact**: Prevents integration issues between teams.

---

## Implementation Guide

### For New Projects

1. **Initialize Workflow System**:
```bash
# Copy templates to project
cp -r templates/.claude .claude
cp -r templates/skills skills
cp templates/CLAUDE.md .

# Initialize manifest
/guardrail:init my-project
```

2. **Start First Feature**:
```bash
/workflow:spawn --auto "add user authentication"
```

3. **Workflow Executes**:
- Design phase: system-architect creates design
- Type generation: TypeScript types generated
- Implementation: Backend and frontend teams work in parallel
- Review: Build validation, security scan
- Complete: Version marked complete

### For Existing Projects

1. **Analyze Codebase**:
```bash
/guardrail:analyze
```

2. **Start Workflow from Analysis**:
```bash
/workflow:spawn --auto "add new feature"
```

### For Template Development

1. **Create New Skill**:
```bash
mkdir -p skills/my-skill/{agents,schemas,scripts}
touch skills/my-skill/skill.yml
```

2. **Define Agent**:
```yaml
# agents/my-agent.yml
name: my-agent
role: My Agent Role
allowed_tools: [Read, Write]
responsibilities:
  - Do this
  - Do that
```

3. **Create Command**:
```markdown
---
description: My command description
allowed-tools: Read, Write, Task
---

# My Command

[Implementation phases...]
```

4. **Test**:
```bash
/my-namespace:my-command
```

---

## FAQ

### Why hooks instead of instructions?

**Hooks are enforced** - AI cannot bypass them. Instructions can be ignored or forgotten.

### What happens if I try to write files in the wrong phase?

The hook intercepts the operation and returns an error. The file is never written.

### Can I disable hooks for testing?

Yes, remove the hook from `.claude/settings.json`. But this defeats the guardrail purpose.

### How do I add validation to a new tool?

Add a matcher to `.claude/settings.json`:
```json
{
  "matcher": "NewTool",
  "hooks": [
    {
      "command": "python3 validate_workflow.py --operation write --input \"$TOOL_INPUT\""
    }
  ]
}
```

### Where are workflow states stored?

- Active version pointer: `.workflow/current.yml`
- Version registry: `.workflow/index.yml`
- Session state: `.workflow/versions/vXXX/session.yml`

### How do I extend the state machine?

1. Add new phase to `PHASES` list in `workflow_manager.py`
2. Define valid transitions in `VALID_TRANSITIONS`
3. Update `validate_workflow.py` phase restrictions
4. Update commands to use new phase

---

## Appendix: File Locations

### Configuration Files
```
.claude/settings.json              # Hook configuration
project_manifest.json              # Entity registry
.workflow/current.yml              # Active version pointer
.workflow/index.yml                # Version registry
```

### Version Files
```
.workflow/versions/vXXX/
├── session.yml                    # Workflow state
├── design/
│   └── design_document.yml        # Design specification
├── dependency_graph.yml           # Execution layers
├── contracts/
│   └── api_contract.yml           # API contract
├── contexts/
│   └── <entity_id>.yml            # Entity contexts
└── tasks/
    └── task_<entity_id>.yml       # Implementation tasks
```

### Generated Types
```
types/
├── types.ts                       # Model interfaces
├── component-props.ts             # Component prop types
├── api-types.ts                   # Request/response types
└── index.ts                       # Re-exports
```

### Scripts
```
skills/guardrail-orchestrator/scripts/
├── workflow_manager.py            # State machine
├── version_manager.py             # Version lifecycle
├── generate_types.py              # TypeScript generation
├── validate_design.py             # Design validation
├── validate_workflow.py           # Hook validation
├── validate_write.py              # Path validation
├── validate_bash.py               # Shell blocking
├── validate_api_contract.py       # API validation
├── generate_api_contract.py       # Contract generation
├── security_scan.py               # Security audit
└── post_write.py                  # Auto-update status
```

---

**End of Documentation**

For questions or issues, see `/workflow:status` and `CLAUDE.md`.