47 KiB
47 KiB
Guardrail Workflow System - Architecture Documentation
Generated: 2025-12-18 Version: 1.0.0
Table of Contents
- System Overview
- Architecture Diagram
- Phase State Machine
- Core Scripts Reference
- Hook System
- Agent Integration
- Recent Enhancements
- 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:
# 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 --checklistverifies:- 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
- Components import from
version_manager.py
Purpose: Manage version lifecycle (create, activate, complete).
Commands:
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:
generate_types.py design_document.yml --output-dir types
Generated Files:
types/types.ts- Model interfacestypes/component-props.ts- Component prop interfaces with typed objectstypes/api-types.ts- Request/response typestypes/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:
validate_design.py design_document.yml --output-dir .workflow/versions/vXXX
Validation Checks:
- Model Validation: Primary keys, field types, enum values, relation targets
- API Validation: HTTP methods, request bodies, responses, model dependencies
- Page Validation: Routes, data needs, component references
- Component Validation: Props, events, API usage, child components
- 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 definitionstasks/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:
{
"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:
validate_api_contract.py --project-dir .
Validation Checks:
- Frontend API Calls: Detects
fetch(),axios,useSWRpatterns - Backend Routes: Validates
app/api/*/route.tsexports,pages/api/*.ts - Method Matching: GET calls → GET endpoints, POST → POST, etc.
- Body Alignment: POST/PUT with body, GET without body
- 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:
generate_api_contract.py design_document.yml --output-dir .workflow/versions/vXXX
Generated Files:
contracts/api_contract.yml- Strict API type definitionsapp/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
{
"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:
- IMPLEMENTATION_CONTEXT.md: Generated rules and type definitions
- Task File (
.workflow/versions/vXXX/tasks/task_*.yml): Specific task definition - Context File (
.workflow/versions/vXXX/contexts/<entity_id>.yml): Full entity context - Generated Types (
types/*.ts): TypeScript interfaces to use
Context File Structure:
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:
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):
python3 generate_types.py .workflow/versions/v003/design/design_document.yml
After (Dynamic):
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):
git commit -m "Multi-line message
with Co-Authored-By" # Breaks on newlines
After (Fixed):
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 designvalidate_against_contract.py: Verify backend implements contractvalidate_api_contract.py: Verify frontend calls match backend
Impact: Prevents integration issues between teams.
Implementation Guide
For New Projects
- Initialize Workflow System:
# Copy templates to project
cp -r templates/.claude .claude
cp -r templates/skills skills
cp templates/CLAUDE.md .
# Initialize manifest
/guardrail:init my-project
- Start First Feature:
/workflow:spawn --auto "add user authentication"
- 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
- Analyze Codebase:
/guardrail:analyze
- Start Workflow from Analysis:
/workflow:spawn --auto "add new feature"
For Template Development
- Create New Skill:
mkdir -p skills/my-skill/{agents,schemas,scripts}
touch skills/my-skill/skill.yml
- Define Agent:
# agents/my-agent.yml
name: my-agent
role: My Agent Role
allowed_tools: [Read, Write]
responsibilities:
- Do this
- Do that
- Create Command:
---
description: My command description
allowed-tools: Read, Write, Task
---
# My Command
[Implementation phases...]
- Test:
/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:
{
"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?
- Add new phase to
PHASESlist inworkflow_manager.py - Define valid transitions in
VALID_TRANSITIONS - Update
validate_workflow.pyphase restrictions - 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.