# Workflow Versioning Schema # Links workflow sessions with task sessions and operations # ============================================================================ # WORKFLOW SESSION (Top Level) # ============================================================================ workflow_session: # Unique version identifier version: string # v001, v002, v003... # Feature being implemented feature: string # Session metadata session_id: string # workflow_ parent_version: string | null # If this is a continuation/fix # Status status: pending | in_progress | completed | failed | rolled_back # Timestamps started_at: timestamp completed_at: timestamp | null # Approval records approvals: design: status: pending | approved | rejected approved_by: string | null approved_at: timestamp | null rejection_reason: string | null implementation: status: pending | approved | rejected approved_by: string | null approved_at: timestamp | null rejection_reason: string | null # Linked task sessions task_sessions: [task_session_id] # Aggregate summary summary: total_tasks: integer tasks_completed: integer entities_created: integer entities_updated: integer entities_deleted: integer files_created: integer files_updated: integer files_deleted: integer # ============================================================================ # TASK SESSION (Per Task) # ============================================================================ task_session: # Unique identifier session_id: string # tasksession__ # Link to parent workflow workflow_version: string # v001 # Task reference task_id: string task_type: create | update | delete | refactor | test # Agent info agent: frontend | backend | reviewer | architect # Timestamps started_at: timestamp completed_at: timestamp | null duration_ms: integer | null # Status status: pending | in_progress | review | approved | completed | failed | blocked # Operations performed in this session operations: [operation] # Review link (if reviewed) review_session: review_session | null # Error tracking errors: [error_record] # Retry info attempt_number: integer # 1, 2, 3... previous_attempts: [session_id] # ============================================================================ # OPERATION (Atomic Change) # ============================================================================ operation: # Unique operation ID id: string # op__ # Operation type type: CREATE | UPDATE | DELETE | RENAME | MOVE # Target target_type: file | entity | task | manifest target_id: string # entity_id or file path target_path: string | null # file path if applicable # Change details changes: before: string | null # Previous state/content hash after: string | null # New state/content hash diff_summary: string # Human-readable summary # Timestamp performed_at: timestamp # Reversibility reversible: boolean rollback_data: object | null # Data needed to reverse # ============================================================================ # REVIEW SESSION # ============================================================================ review_session: session_id: string # review__ # Links task_session_id: string workflow_version: string # Reviewer reviewer: string # "reviewer" agent or user # Timing started_at: timestamp completed_at: timestamp # Decision decision: approved | rejected | needs_changes # Checks performed checks: file_exists: pass | fail | skip manifest_compliance: pass | fail | skip code_quality: pass | fail | skip lint: pass | fail | skip build: pass | fail | skip tests: pass | fail | skip # Feedback notes: string issues_found: [string] suggestions: [string] # ============================================================================ # ERROR RECORD # ============================================================================ error_record: timestamp: timestamp phase: string # Which step failed error_type: string message: string stack_trace: string | null resolved: boolean resolution: string | null # ============================================================================ # VERSION INDEX (Quick Lookup) # ============================================================================ version_index: versions: - version: v001 feature: "User authentication" status: completed started_at: timestamp completed_at: timestamp tasks_count: 8 operations_count: 15 - version: v002 feature: "Task filters" status: in_progress started_at: timestamp completed_at: null tasks_count: 5 operations_count: 7 latest_version: v002 total_versions: 2 # ============================================================================ # TASK SESSION DIRECTORY STRUCTURE # ============================================================================ task_session_directory: description: "Each task session has its own directory with full context" path_pattern: ".workflow/versions/{version}/task_sessions/{task_id}/" files: session.yml: description: "Task session metadata (existing schema)" schema: task_session task.yml: description: "Snapshot of task definition at execution time" fields: id: string type: create | update | delete | refactor | test title: string agent: frontend | backend | reviewer | architect status_at_snapshot: string entity_ids: [string] file_paths: [string] dependencies: [string] description: string acceptance_criteria: [string] snapshotted_at: timestamp source_path: string operations.log: description: "Chronological audit trail of all operations" format: text entry_pattern: "[{timestamp}] {operation_type} {target_type}: {target_id} ({path})" # ============================================================================ # EXAMPLE: Complete Workflow Session # ============================================================================ example_workflow_session: version: v001 feature: "User authentication with OAuth" session_id: workflow_20250116_143022 parent_version: null status: completed started_at: "2025-01-16T14:30:22Z" completed_at: "2025-01-16T15:45:00Z" approvals: design: status: approved approved_by: user approved_at: "2025-01-16T14:45:00Z" rejection_reason: null implementation: status: approved approved_by: user approved_at: "2025-01-16T15:40:00Z" rejection_reason: null task_sessions: - tasksession_task_create_LoginPage_20250116_144501 - tasksession_task_create_AuthAPI_20250116_145001 - tasksession_task_update_Header_20250116_150001 summary: total_tasks: 3 tasks_completed: 3 entities_created: 2 entities_updated: 1 entities_deleted: 0 files_created: 3 files_updated: 2 files_deleted: 0 example_task_session: session_id: tasksession_task_create_LoginPage_20250116_144501 workflow_version: v001 task_id: task_create_LoginPage task_type: create agent: frontend started_at: "2025-01-16T14:45:01Z" completed_at: "2025-01-16T14:55:00Z" duration_ms: 599000 status: completed operations: - id: op_20250116_144502_001 type: CREATE target_type: file target_id: page_login target_path: app/login/page.tsx changes: before: null after: "sha256:abc123..." diff_summary: "Created login page with email/password form" performed_at: "2025-01-16T14:45:02Z" reversible: true rollback_data: action: delete_file path: app/login/page.tsx - id: op_20250116_144503_002 type: UPDATE target_type: manifest target_id: project_manifest target_path: project_manifest.json changes: before: "sha256:def456..." after: "sha256:ghi789..." diff_summary: "Added page_login entity, set status to IMPLEMENTED" performed_at: "2025-01-16T14:45:03Z" reversible: true rollback_data: action: restore_content content_hash: "sha256:def456..." review_session: session_id: review_task_create_LoginPage_20250116_145501 task_session_id: tasksession_task_create_LoginPage_20250116_144501 workflow_version: v001 reviewer: reviewer started_at: "2025-01-16T14:55:01Z" completed_at: "2025-01-16T14:58:00Z" decision: approved checks: file_exists: pass manifest_compliance: pass code_quality: pass lint: pass build: pass tests: skip notes: "Login page implementation matches manifest spec" issues_found: [] suggestions: - "Consider adding loading state for form submission" errors: [] attempt_number: 1 previous_attempts: []