/ CSPEC_NATIVE_ARCHITECTURE.md
CSPEC_NATIVE_ARCHITECTURE.md
1 # CSPEC-Native Orchestrator Architecture 2 3 ## Core Principle 4 5 **All machine-to-machine communication uses `.cspec` files exclusively.** 6 7 Human-readable documentation (`.md`) is a derived artifact, generated by the Documentation worker from cspec sources. Humans never edit `.md` directly — they either edit cspec or provide natural language that gets converted to cspec. 8 9 ``` 10 ┌─────────────────────────────────────────────────────────────────────────────┐ 11 │ CSPEC FLOW │ 12 ├─────────────────────────────────────────────────────────────────────────────┤ 13 │ │ 14 │ Human Input ──► Orchestrator ──► Task.cspec ──► Worker │ 15 │ │ │ │ 16 │ │ ▼ │ 17 │ │ Result.cspec │ 18 │ │ │ │ 19 │ │ ┌───────────────────────────────┘ │ 20 │ │ ▼ │ 21 │ │ ┌──────────────┐ │ 22 │ │ │ Docs Worker │ │ 23 │ │ │ │ │ 24 │ │ │ cspec → .md │ │ 25 │ │ └──────────────┘ │ 26 │ │ │ │ 27 │ ▼ ▼ │ 28 │ Orchestrator UI Human-readable docs │ 29 │ (only human (derived, never │ 30 │ touchpoint) edited directly) │ 31 │ │ 32 └─────────────────────────────────────────────────────────────────────────────┘ 33 ``` 34 35 ## Repository Layout 36 37 ``` 38 C:\Users\MarcoAniballi\Radicle\ 39 ├── alpha-delta-context/ # Documentation & specs (cspec source of truth) 40 │ ├── project/ 41 │ │ ├── architecture/ 42 │ │ │ ├── machine/ # *.cspec files (SOURCE) 43 │ │ │ └── human/ # *.md files (DERIVED) 44 │ │ ├── implementation/ 45 │ │ │ └── machine/ # status.cspec, blockers.cspec, etc. 46 │ │ └── planning/ # *.cspec planning files 47 │ ├── infra/ 48 │ │ ├── machine/ # ci-*.cspec files 49 │ │ │ └── commands/ # Command template cspecs 50 │ │ └── human/ # Derived .md guides 51 │ ├── sessions/ # Session context cspecs 52 │ └── navigation_index.md # Navigation (derived from index.cspec) 53 │ 54 ├── alpha-delta-protocol/ # Main codebase 55 │ ├── crates/ 56 │ │ ├── alpha-chain/ 57 │ │ ├── delta-exchange/ 58 │ │ └── common/ 59 │ └── .forgejo/workflows/ 60 │ 61 ├── alpha-delta-orchestrator/ # This orchestrator system 62 │ ├── orchestrator.py 63 │ ├── cspec/ # Orchestrator's own cspec definitions 64 │ │ ├── task-schema.cspec # Task definition schema 65 │ │ ├── result-schema.cspec # Result definition schema 66 │ │ └── worker-state.cspec # Worker state schema 67 │ ├── workers/ # Worker working directories 68 │ ├── queues/ # Message queues (cspec files) 69 │ │ ├── pending/ 70 │ │ ├── active/ 71 │ │ └── completed/ 72 │ └── logs/ 73 │ 74 └── alpha-delta-node/ # Node implementation (future) 75 ``` 76 77 ## CSPEC Schemas for Orchestration 78 79 ### Task Schema (`task-schema.cspec`) 80 81 ```cspec 82 SCHEMA task_v1 { 83 meta { 84 id: string # Unique task identifier 85 created: iso8601 # Creation timestamp 86 priority: enum[critical|high|normal|low] 87 role: enum[planner|executor-alpha|executor-delta|executor-infra|docs] 88 } 89 90 context { 91 load: string[] # cspec files to load (paths relative to context repo) 92 session: string? # Previous session cspec to resume 93 } 94 95 task { 96 title: string 97 objective: string # What success looks like 98 constraints: string[] 99 acceptance: string[] # Acceptance criteria 100 } 101 102 refs { 103 spec_sections: string[] # e.g., ["alpha_chain.cspec#validator_registration"] 104 depends_on: string[] # Task IDs this depends on 105 blocks: string[] # Task IDs this blocks 106 } 107 } 108 ``` 109 110 ### Result Schema (`result-schema.cspec`) 111 112 ```cspec 113 SCHEMA result_v1 { 114 meta { 115 task_id: string 116 worker: string 117 started: iso8601 118 completed: iso8601 119 status: enum[success|partial|blocked|failed] 120 } 121 122 output { 123 summary: string 124 files_created: string[] 125 files_modified: string[] 126 commits: string[] # Commit SHAs 127 branch: string? 128 } 129 130 artifacts { 131 cspec_outputs: string[] # Generated cspec files 132 code_paths: string[] # Code files created/modified 133 } 134 135 follow_up { 136 new_tasks: task_v1[] # Spawned subtasks 137 blockers: blocker_v1[] # Blockers encountered 138 questions: question_v1[] # Questions for human 139 } 140 141 context_update { 142 session_file: string # Session cspec to save 143 status_updates: string[] # Updates to status.cspec 144 } 145 } 146 ``` 147 148 ### Question Schema (for human escalation) 149 150 ```cspec 151 SCHEMA question_v1 { 152 meta { 153 id: string 154 worker: string 155 task_id: string 156 created: iso8601 157 priority: enum[blocking|important|fyi] 158 } 159 160 question { 161 summary: string # One-line summary 162 context: string # Background 163 detail: string # Full question 164 options: option_v1[]? # Suggested options if applicable 165 } 166 167 response { 168 answered: iso8601? 169 answer: string? 170 decision: string? # Selected option if applicable 171 } 172 } 173 174 SCHEMA option_v1 { 175 id: string 176 description: string 177 implications: string[] 178 } 179 ``` 180 181 ## Worker Communication Protocol 182 183 ### 1. Task Assignment 184 185 Orchestrator creates task cspec in worker's inbox: 186 187 ``` 188 alpha-delta-orchestrator/ 189 └── workers/ 190 └── executor-alpha/ 191 └── inbox/ 192 └── task_20260105_143022_impl_validator.cspec 193 ``` 194 195 ### 2. Worker Reads Task 196 197 Worker loads: 198 1. `types.cspec` (ALWAYS FIRST) 199 2. Files specified in `task.context.load[]` 200 3. Session file if `task.context.session` specified 201 4. The task cspec itself 202 203 ### 3. Worker Executes 204 205 Worker works autonomously, following cspec references. 206 207 ### 4. Worker Outputs Result 208 209 Worker creates result cspec: 210 211 ``` 212 alpha-delta-orchestrator/ 213 └── workers/ 214 └── executor-alpha/ 215 └── outbox/ 216 └── result_20260105_143022_impl_validator.cspec 217 ``` 218 219 ### 5. Orchestrator Processes Result 220 221 - Moves result to `queues/completed/` 222 - If `follow_up.questions[]` → routes to human queue 223 - If `follow_up.new_tasks[]` → creates new task cspecs 224 - Updates `status.cspec` with `context_update.status_updates[]` 225 - Saves session for resumption 226 227 ## Documentation Worker Special Role 228 229 The docs worker has a unique responsibility: **converting cspec to human-readable markdown**. 230 231 ### Trigger Conditions 232 233 1. Any cspec in `project/architecture/machine/` changes 234 2. New result cspec contains `artifacts.cspec_outputs[]` 235 3. Manual request for documentation refresh 236 237 ### Process 238 239 ```cspec 240 TASK docs_sync { 241 context { 242 load: ["types.cspec", "index.cspec"] 243 } 244 245 task { 246 objective: "Synchronize human-readable docs with cspec sources" 247 248 steps: [ 249 "1. Identify changed cspec files", 250 "2. For each changed cspec:", 251 " - Parse cspec structure", 252 " - Generate corresponding .md in human/ directory", 253 " - Preserve existing prose where cspec unchanged", 254 "3. Update navigation_index.md", 255 "4. Commit changes to alpha-delta-context" 256 ] 257 } 258 } 259 ``` 260 261 ### Transformation Rules 262 263 | CSPEC Element | Markdown Output | 264 |---------------|-----------------| 265 | `SCHEMA` | Section with field table | 266 | `ENUM` | Bulleted list with descriptions | 267 | `COMPONENT` | H2 section with subsections | 268 | `FLOW` | Mermaid diagram | 269 | `REFS` | Hyperlinks to other docs | 270 | Comments `#` | Prose paragraphs | 271 272 ## Orchestrator UI (Human Interface) 273 274 The orchestrator UI is the **only** place humans interact directly: 275 276 ``` 277 ╔═══════════════════════════════════════════════════════════════════════════╗ 278 ║ Alpha/Delta Development Orchestrator ║ 279 ╠═══════════════════════════════════════════════════════════════════════════╣ 280 ║ ║ 281 ║ Workers ║ 282 ║ ┌──────────────┬───────────┬──────────────────────────────┬────────────┐ ║ 283 ║ │ Worker │ Status │ Current Task │ Completed │ ║ 284 ║ ├──────────────┼───────────┼──────────────────────────────┼────────────┤ ║ 285 ║ │ planner │ working │ Q1 roadmap planning │ 5 │ ║ 286 ║ │ exec-alpha │ working │ validator registration │ 12 │ ║ 287 ║ │ exec-delta │ idle │ — │ 8 │ ║ 288 ║ │ exec-infra │ blocked │ CI pipeline optimization │ 3 │ ║ 289 ║ │ docs │ working │ Sync alpha_chain.cspec → .md │ 24 │ ║ 290 ║ └──────────────┴───────────┴──────────────────────────────┴────────────┘ ║ 291 ║ ║ 292 ║ Queue: 7 pending │ 2 active │ 38 completed │ 1 blocked ║ 293 ║ ║ 294 ║ ⚠️ Questions Pending (1): ║ 295 ║ ┌────────────────────────────────────────────────────────────────────────┐║ 296 ║ │ [exec-infra] BLOCKING │║ 297 ║ │ Should validator earn-in use linear or exponential vesting? │║ 298 ║ │ │║ 299 ║ │ Options: │║ 300 ║ │ 1. Linear (simpler, predictable) │║ 301 ║ │ 2. Exponential (rewards long-term) │║ 302 ║ │ 3. Cliff + linear (commitment signal) │║ 303 ║ │ │║ 304 ║ │ > [Enter 1-3 or type custom response]: _ │║ 305 ║ └────────────────────────────────────────────────────────────────────────┘║ 306 ║ ║ 307 ║ Commands: [a]dd task [s]tatus [l]ogs [q]uestions [h]elp [x]exit ║ 308 ╚═══════════════════════════════════════════════════════════════════════════╝ 309 ``` 310 311 ## File Paths (Windows) 312 313 ```python 314 # orchestrator.py configuration for Windows 315 316 from pathlib import Path 317 318 class WindowsConfig: 319 # Base path 320 RADICLE_ROOT = Path(r"C:\Users\MarcoAniballi\Radicle") 321 322 # Repositories 323 CONTEXT_REPO = RADICLE_ROOT / "alpha-delta-context" 324 PROTOCOL_REPO = RADICLE_ROOT / "alpha-delta-protocol" 325 ORCHESTRATOR_ROOT = RADICLE_ROOT / "alpha-delta-orchestrator" 326 327 # CSPEC locations (context repo) 328 CSPEC_TYPES = CONTEXT_REPO / "project/architecture/machine/types.cspec" 329 CSPEC_INDEX = CONTEXT_REPO / "project/architecture/machine/index.cspec" 330 CSPEC_STATUS = CONTEXT_REPO / "project/implementation/machine/status.cspec" 331 CSPEC_SESSIONS = CONTEXT_REPO / "sessions" 332 333 # Orchestrator internal 334 WORKER_DIR = ORCHESTRATOR_ROOT / "workers" 335 QUEUE_DIR = ORCHESTRATOR_ROOT / "queues" 336 LOG_DIR = ORCHESTRATOR_ROOT / "logs" 337 ``` 338 339 ## Worker Startup Protocol 340 341 Each worker, on startup: 342 343 ```python 344 # Pseudocode for worker initialization 345 346 def worker_startup(role: str): 347 # 1. Always load types first 348 context = load_cspec(CSPEC_TYPES) 349 350 # 2. Check for pending task 351 task_file = find_newest_file(WORKER_DIR / role / "inbox" / "*.cspec") 352 353 if task_file: 354 task = parse_cspec(task_file) 355 356 # 3. Load task-specified context 357 for cspec_path in task.context.load: 358 context.merge(load_cspec(CONTEXT_REPO / cspec_path)) 359 360 # 4. Load session if resuming 361 if task.context.session: 362 context.merge(load_cspec(CSPEC_SESSIONS / task.context.session)) 363 364 # 5. Execute task 365 result = execute_task(task, context) 366 367 # 6. Write result cspec 368 write_cspec(WORKER_DIR / role / "outbox" / f"result_{task.meta.id}.cspec", result) 369 370 # 7. Archive task 371 move(task_file, WORKER_DIR / role / "archive" / task_file.name) 372 else: 373 # No task - enter idle state 374 wait_for_task() 375 ``` 376 377 ## Benefits of CSPEC-Native Design 378 379 1. **Token Efficiency**: CSPEC is ~3-5x more compact than prose 380 2. **Parseable**: Workers can programmatically extract what they need 381 3. **Diffable**: Changes are clearly visible in version control 382 4. **Consistent**: Schema enforcement prevents ambiguity 383 5. **Resumable**: Session cspecs capture exact state for continuation 384 6. **Auditable**: Complete history of decisions in structured format 385 386 ## Migration Path 387 388 1. Current prose docs remain as reference 389 2. New work produces cspec first 390 3. Docs worker generates/updates markdown 391 4. Eventually, all source-of-truth is cspec