/ schemas.cspec
schemas.cspec
1 # Orchestrator CSPEC Schemas 2 # These define the structure for all orchestrator communication 3 4 # ============================================================================= 5 # META TYPES 6 # ============================================================================= 7 8 TYPE iso8601 = string # ISO 8601 datetime format 9 10 ENUM priority { 11 critical = 1 # Blocks other work, immediate attention 12 high = 2 # Important, should be next 13 normal = 3 # Standard priority 14 low = 4 # Nice to have, when idle 15 } 16 17 ENUM worker_role { 18 planner # Analyzes architecture, creates task cspecs 19 executor-alpha # Implements ALPHA chain features 20 executor-delta # Implements DELTA exchange features 21 executor-infra # CI/CD, tooling, infrastructure 22 docs # Converts cspec → markdown, maintains docs 23 } 24 25 ENUM task_status { 26 pending # In queue, not yet assigned 27 assigned # Assigned to worker, not started 28 active # Worker is executing 29 blocked # Waiting for human input or dependency 30 completed # Successfully finished 31 failed # Failed with error 32 } 33 34 ENUM result_status { 35 success # Task completed fully 36 partial # Some objectives met, others remain 37 blocked # Cannot proceed without input 38 failed # Task failed with error 39 } 40 41 ENUM question_priority { 42 blocking # Cannot proceed without answer 43 important # Affects approach but can continue 44 fyi # Informational, no response required 45 } 46 47 # ============================================================================= 48 # TASK SCHEMA 49 # ============================================================================= 50 51 SCHEMA task_v1 { 52 # Metadata 53 meta { 54 id: string # Unique: task_YYYYMMDD_HHMMSS_shortname 55 created: iso8601 56 priority: priority 57 role: worker_role # Which worker type should handle 58 parent_id: string? # Parent task if this is a subtask 59 } 60 61 # Context loading instructions 62 context { 63 # Paths relative to alpha-delta-context/ 64 # Worker loads these in order after types.cspec 65 load: [ 66 "project/architecture/machine/index.cspec", 67 # ... additional cspec files 68 ] 69 70 # Session file to resume (in sessions/) 71 session: string? # e.g., "session_20260105_alpha_validator.cspec" 72 } 73 74 # Task definition 75 task { 76 title: string # Short descriptive title 77 objective: string # What success looks like 78 79 # Detailed instructions (optional, for complex tasks) 80 steps: string[]? 81 82 # Constraints to respect 83 constraints: [ 84 # e.g., "Must maintain backward compatibility" 85 # e.g., "Follow existing patterns in alpha-chain/src/validator.rs" 86 ] 87 88 # Measurable acceptance criteria 89 acceptance: [ 90 # e.g., "Validators can register with minimum stake" 91 # e.g., "Unit tests pass with >80% coverage" 92 ] 93 } 94 95 # References to specs and dependencies 96 refs { 97 # Spec sections this task implements 98 # Format: "filename.cspec#section_name" 99 spec_sections: [ 100 # e.g., "alpha_chain.cspec#validator_registration" 101 ] 102 103 # Task IDs this depends on (must complete first) 104 depends_on: string[] 105 106 # Task IDs that depend on this 107 blocks: string[] 108 } 109 } 110 111 # ============================================================================= 112 # RESULT SCHEMA 113 # ============================================================================= 114 115 SCHEMA result_v1 { 116 # Metadata 117 meta { 118 task_id: string # ID of completed task 119 worker: string # Worker name that executed 120 started: iso8601 121 completed: iso8601 122 status: result_status 123 } 124 125 # What was produced 126 output { 127 summary: string # Brief description of what was done 128 129 # Files in alpha-delta-protocol/ 130 files_created: string[] 131 files_modified: string[] 132 133 # Git info 134 commits: string[] # Commit SHAs 135 branch: string? # Feature branch name 136 } 137 138 # Artifacts produced 139 artifacts { 140 # New cspec files created (in alpha-delta-context/) 141 cspec_outputs: string[] 142 143 # Code paths affected (in alpha-delta-protocol/) 144 code_paths: string[] 145 146 # Test results 147 tests_passed: int? 148 tests_failed: int? 149 coverage: float? # 0.0-1.0 150 } 151 152 # Follow-up items 153 follow_up { 154 # New tasks spawned by this work 155 new_tasks: task_v1[] 156 157 # Blockers encountered 158 blockers: blocker_v1[] 159 160 # Questions needing human input 161 questions: question_v1[] 162 } 163 164 # State to preserve 165 context_update { 166 # Session cspec to save for resumption 167 session_file: string 168 169 # Lines to add to status.cspec 170 status_updates: string[] 171 172 # Decisions made (for decisions.cspec) 173 decisions: decision_v1[] 174 } 175 } 176 177 # ============================================================================= 178 # QUESTION SCHEMA (Human Escalation) 179 # ============================================================================= 180 181 SCHEMA question_v1 { 182 meta { 183 id: string # q_YYYYMMDD_HHMMSS_shortname 184 worker: string 185 task_id: string 186 created: iso8601 187 priority: question_priority 188 } 189 190 question { 191 summary: string # One-line for UI display 192 context: string # Background information 193 detail: string # Full question text 194 195 # Suggested options (if applicable) 196 options: option_v1[]? 197 } 198 199 # Filled in when human responds 200 response { 201 answered: iso8601? 202 answer: string? 203 selected_option: string? # Option ID if chose from list 204 } 205 } 206 207 SCHEMA option_v1 { 208 id: string # e.g., "opt_1", "opt_linear" 209 label: string # Short label 210 description: string # Full description 211 implications: string[] # What this choice means 212 } 213 214 # ============================================================================= 215 # BLOCKER SCHEMA 216 # ============================================================================= 217 218 SCHEMA blocker_v1 { 219 id: string # blk_YYYYMMDD_HHMMSS_shortname 220 severity: enum[hard|soft] # hard = cannot proceed, soft = can work around 221 222 blocker { 223 title: string 224 description: string 225 226 # What's needed to unblock 227 resolution: string 228 229 # Who/what can resolve 230 owner: enum[human|planner|executor|external] 231 } 232 233 # Resolution tracking 234 status { 235 state: enum[active|resolved|wontfix] 236 resolved_at: iso8601? 237 resolution_notes: string? 238 } 239 } 240 241 # ============================================================================= 242 # DECISION SCHEMA 243 # ============================================================================= 244 245 SCHEMA decision_v1 { 246 id: string # dec_YYYYMMDD_shortname 247 date: iso8601 248 249 decision { 250 title: string 251 context: string # Why this decision was needed 252 options_considered: string[] 253 chosen: string 254 rationale: string 255 } 256 257 impact { 258 affected_components: string[] 259 spec_updates: string[] # cspec files to update 260 } 261 } 262 263 # ============================================================================= 264 # SESSION SCHEMA (Context Preservation) 265 # ============================================================================= 266 267 SCHEMA session_v1 { 268 meta { 269 id: string # session_YYYYMMDD_HHMMSS_topic 270 worker: string 271 created: iso8601 272 last_updated: iso8601 273 } 274 275 # What was being worked on 276 context { 277 task_id: string 278 objective: string 279 280 # Files that were open/relevant 281 active_files: string[] 282 283 # Key decisions made in session 284 session_decisions: string[] 285 } 286 287 # State to resume 288 state { 289 # Current progress 290 completed_steps: string[] 291 remaining_steps: string[] 292 293 # Working memory 294 notes: string[] 295 296 # Uncommitted changes description 297 pending_changes: string? 298 } 299 300 # How to resume 301 resume { 302 instruction: string # What to do next 303 context_load: string[] # Additional cspecs to load 304 } 305 } 306 307 # ============================================================================= 308 # WORKER STATE SCHEMA 309 # ============================================================================= 310 311 SCHEMA worker_state_v1 { 312 worker { 313 name: string 314 role: worker_role 315 status: enum[idle|working|blocked|stopped] 316 pid: int? 317 session_name: string # tmux session name 318 } 319 320 current { 321 task_id: string? 322 started: iso8601? 323 last_heartbeat: iso8601? 324 } 325 326 stats { 327 tasks_completed: int 328 tasks_failed: int 329 total_time_working: int # seconds 330 } 331 } 332 333 # ============================================================================= 334 # ORCHESTRATOR STATE SCHEMA 335 # ============================================================================= 336 337 SCHEMA orchestrator_state_v1 { 338 meta { 339 started: iso8601 340 last_updated: iso8601 341 } 342 343 workers: worker_state_v1[] 344 345 queues { 346 pending: int 347 active: int 348 completed: int 349 blocked: int 350 } 351 352 pending_questions: int 353 }