986 lines
47 KiB
Markdown
986 lines
47 KiB
Markdown
# 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`.
|