1  # Component Implementation Plan Schema v1.1.0
  2  # Defines the structure for all .plan.cspec files
  3  # Planning workers MUST generate plans that validate against this schema
  4  
  5  schema_version: 1.1.0
  6  created: 2026-01-07
  7  updated: 2026-01-07
  8  
  9  # === REQUIRED SECTIONS ===
 10  required:
 11    - plan_metadata
 12    - wave_context
 13    - phases
 14    - parallel_workstreams  # NEW: Tests, CI, docs alongside implementation
 15    - interface_commitments
 16    - repository_targets
 17    - changelog
 18  
 19  # === PLAN METADATA ===
 20  plan_metadata:
 21    component_id:
 22      type: string
 23      pattern: "^[A-Z]{1,2}[0-9]{2,3}$"
 24      required: true
 25    component_ref:
 26      type: string
 27      description: "Relative path to .component.cspec file"
 28      required: true
 29    plan_version:
 30      type: semver
 31      required: true
 32    plan_status:
 33      type: enum
 34      values: [draft, review, approved, in_progress, blocked, complete]
 35      required: true
 36    created:
 37      type: date
 38      required: true
 39    updated:
 40      type: date
 41      required: true
 42  
 43  # === WAVE CONTEXT ===
 44  wave_context:
 45    topological_level:
 46      type: integer
 47      min: 0
 48      max: 10
 49      required: true
 50      description: "From dependency-graph.cspec (0=root)"
 51    is_root:
 52      type: boolean
 53      required: true
 54    upstream_components:
 55      type: array
 56      items: string
 57      required: true
 58    downstream_components:
 59      type: array
 60      items: string
 61      required: true
 62    critical_path:
 63      type: boolean
 64      required: false
 65    cascade_group:
 66      type: string
 67      required: false
 68  
 69  # === PHASES ===
 70  phases:
 71    type: array
 72    min_items: 1
 73    required: true
 74    items:
 75      phase_id:
 76        type: string
 77        pattern: "^phase_[0-9]+$"
 78        required: true
 79      name:
 80        type: string
 81        required: true
 82      status:
 83        type: enum
 84        values: [pending, in_progress, blocked, complete, skipped]
 85        default: pending
 86  
 87      # Blocking dependencies
 88      blocked_by:
 89        type: array
 90        required: false
 91        items:
 92          dependency_ref:
 93            type: string
 94            pattern: "^[A-Z]{1,2}[0-9]{2,3}\\.(phase_[0-9]+|interface_[a-z_]+|complete)$"
 95            required: true
 96          reason:
 97            type: string
 98            required: true
 99          wait_for:
100            type: enum
101            values: [started, complete, interface_stable]
102            default: complete
103  
104      # Tasks
105      tasks:
106        type: array
107        min_items: 1
108        required: true
109        items:
110          task_id:
111            type: string
112            pattern: "^[A-Z]{1,2}[0-9]{2,3}-T[0-9]{3}$"
113            required: true
114          name:
115            type: string
116            required: true
117          description:
118            type: string
119            required: false
120          target_files:
121            type: array
122            items:
123              path:
124                type: string
125                required: true
126              action:
127                type: enum
128                values: [create, modify, delete]
129                required: true
130          estimate:
131            type: object
132            properties:
133              effort:
134                type: enum
135                values: [trivial, small, medium, large, xlarge]
136              confidence:
137                type: enum
138                values: [high, medium, low]
139          risk:
140            type: object
141            properties:
142              level:
143                type: enum
144                values: [low, medium, high, critical]
145              factors:
146                type: array
147                items: string
148  
149      # Deliverables
150      deliverables:
151        type: array
152        min_items: 1
153        required: true
154        items:
155          deliverable_id:
156            type: string
157            pattern: "^[A-Z]{1,2}[0-9]{2,3}-D[0-9]{3}$"
158            required: true
159          name:
160            type: string
161            required: true
162          type:
163            type: enum
164            values: [code, interface, documentation, test, config]
165            required: true
166          verification:
167            type: string
168            required: true
169  
170      # Test requirements
171      test_requirements:
172        type: object
173        required: false
174        properties:
175          unit:
176            type: array
177            items:
178              test_id: string
179              description: string
180          integration:
181            type: array
182            items:
183              test_id: string
184              description: string
185              dependencies: array
186  
187      # Success criteria
188      success_criteria:
189        type: array
190        min_items: 1
191        required: true
192        items: string
193  
194      estimated_duration:
195        type: string
196        pattern: "^[0-9]+[hdw]$"
197        required: false
198  
199  # === PARALLEL WORKSTREAMS ===
200  # These workstreams run IN PARALLEL with implementation phases (not after)
201  # Workers MUST address these alongside each phase's tasks
202  parallel_workstreams:
203  
204    # 1. TESTING - Tests written alongside implementation, not after
205    testing:
206      type: object
207      required: true
208      properties:
209        strategy:
210          type: enum
211          values: [tdd, test_alongside, test_after]
212          required: true
213          default: test_alongside
214          description: "test_alongside REQUIRED - tests written in same PR as code"
215  
216        coverage_targets:
217          type: object
218          required: true
219          properties:
220            unit_minimum:
221              type: integer
222              min: 60
223              max: 100
224              default: 80
225              description: "Minimum unit test coverage percentage"
226            integration_required:
227              type: boolean
228              default: true
229              description: "Integration tests required for each phase"
230  
231        per_phase_requirements:
232          type: array
233          required: true
234          description: "Test requirements that must be satisfied per phase"
235          items:
236            phase_ref:
237              type: string
238              pattern: "^phase_[0-9]+$"
239            unit_tests:
240              type: array
241              items: string
242              description: "Unit tests to add in this phase"
243            integration_tests:
244              type: array
245              items: string
246              description: "Integration tests to add in this phase"
247            test_files:
248              type: array
249              items:
250                path: string
251                action: {create, modify}
252              description: "Test files created/modified in this phase"
253  
254        ci_test_gates:
255          type: array
256          required: true
257          description: "CI checks that must pass before merge"
258          items:
259            gate_id: string
260            command: string
261            required: boolean
262  
263    # 2. CI WORKFLOWS - Updated alongside repo changes
264    ci_workflows:
265      type: object
266      required: true
267      properties:
268        affected_workflows:
269          type: array
270          required: true
271          description: "CI workflow files that may need updates"
272          items:
273            workflow_file:
274              type: string
275              description: ".forgejo/workflows/*.yml file path"
276            repo:
277              type: string
278              description: "Repository containing the workflow"
279            triggers:
280              type: array
281              items: string
282              description: "Phases that may trigger workflow updates"
283  
284        per_phase_ci_tasks:
285          type: array
286          required: false
287          description: "CI tasks per phase (if workflow changes needed)"
288          items:
289            phase_ref:
290              type: string
291              pattern: "^phase_[0-9]+$"
292            workflow_changes:
293              type: array
294              items:
295                file: string
296                change_type: {add_job, modify_job, add_step, modify_step, add_artifact}
297                description: string
298  
299        required_ci_checks:
300          type: array
301          required: true
302          description: "CI checks that must exist and pass"
303          items:
304            check_name: string
305            check_type: {build, test, lint, security, bench}
306            blocking: boolean
307  
308    # 3. DOCUMENTATION - cspec and changelog updates for future workers
309    documentation:
310      type: object
311      required: true
312      properties:
313        cspec_update_policy:
314          type: enum
315          values: [on_interface_change, on_any_change, manual]
316          required: true
317          default: on_interface_change
318          description: "When to update component cspec files"
319  
320        component_cspec_updates:
321          type: array
322          required: true
323          description: "Component cspec files to update as implementation proceeds"
324          items:
325            cspec_file:
326              type: string
327              description: "Path to .component.cspec file"
328            update_triggers:
329              type: array
330              items:
331                phase_ref: string
332                fields_to_update: array
333                description: string
334  
335        session_logging:
336          type: object
337          required: true
338          properties:
339            required:
340              type: boolean
341              default: true
342            log_location:
343              type: string
344              default: "sessions/"
345            log_format:
346              type: enum
347              values: [cspec, markdown]
348              default: cspec
349            log_triggers:
350              type: array
351              items: string
352              description: "Events requiring session log entries"
353              default: [phase_complete, blocker_encountered, interface_change, major_decision]
354  
355        changelog_policy:
356          type: object
357          required: true
358          properties:
359            update_frequency:
360              type: enum
361              values: [per_phase, per_task, per_pr]
362              default: per_phase
363            required_fields:
364              type: array
365              items: string
366              default: [version, date, type, description, affected_interfaces]
367  
368        human_doc_derivation:
369          type: object
370          required: false
371          description: "Hints for generating human docs from cspec"
372          properties:
373            target_human_doc:
374              type: string
375              description: "Path to human-readable doc to regenerate"
376            regenerate_triggers:
377              type: array
378              items: string
379              description: "Phases that should trigger human doc regeneration"
380  
381  # === INTERFACE COMMITMENTS ===
382  interface_commitments:
383    provides:
384      type: array
385      required: true
386      items:
387        interface_id:
388          type: string
389          pattern: "^interface_[a-z_]+$"
390          required: true
391        name:
392          type: string
393          required: true
394        stability:
395          type: enum
396          values: [experimental, unstable, stable, frozen]
397          required: true
398        available_from:
399          type: string
400          pattern: "^phase_[0-9]+$"
401          required: true
402        stable_from:
403          type: string
404          pattern: "^phase_[0-9]+$"
405          required: false
406        consumers:
407          type: array
408          items: string
409          required: false
410  
411    requires:
412      type: array
413      required: false
414      items:
415        interface_ref:
416          type: string
417          pattern: "^[A-Z]{1,2}[0-9]{2,3}\\.interface_[a-z_]+$"
418          required: true
419        minimum_stability:
420          type: enum
421          values: [experimental, unstable, stable]
422          default: stable
423        required_from:
424          type: string
425          pattern: "^phase_[0-9]+$"
426          required: true
427  
428  # === REPOSITORY TARGETS ===
429  repository_targets:
430    primary_repo:
431      type: object
432      required: true
433      properties:
434        name:
435          type: string
436          required: true
437          description: "adnet, alphavm, deltavm, alphaos, deltaos, ac-dc, etc."
438        branch_strategy:
439          type: enum
440          values: [feature_branch, develop, main_direct]
441          default: feature_branch
442  
443    file_manifest:
444      type: array
445      required: true
446      items:
447        path:
448          type: string
449          required: true
450        action:
451          type: enum
452          values: [create, modify, delete]
453          required: true
454        purpose:
455          type: string
456          required: true
457        phase:
458          type: string
459          pattern: "^phase_[0-9]+$"
460          required: true
461  
462    secondary_repos:
463      type: array
464      required: false
465      items:
466        name: string
467        files: array
468        reason: string
469  
470  # === COMPLEXITY ASSESSMENT ===
471  complexity_assessment:
472    overall_complexity:
473      type: enum
474      values: [trivial, low, medium, high, very_high]
475      required: true
476  
477    risk_summary:
478      type: array
479      required: false
480      items:
481        risk_id:
482          type: string
483          pattern: "^RISK-[0-9]{3}$"
484        description: string
485        likelihood:
486          type: enum
487          values: [low, medium, high]
488        impact:
489          type: enum
490          values: [low, medium, high, critical]
491        mitigation: string
492  
493  # === DEPENDENCIES SUMMARY ===
494  dependencies_summary:
495    blocks:
496      type: array
497      items: string
498      description: "Component IDs this plan blocks"
499    blocked_by:
500      type: array
501      items: string
502      description: "Component IDs blocking this plan"
503    parallel_candidates:
504      type: array
505      items: string
506      description: "Components that can execute in parallel"
507  
508  # === CHANGELOG ===
509  changelog:
510    type: array
511    required: true
512    items:
513      version: semver
514      date: date
515      type:
516        type: enum
517        values: [initial, revision, status_update, approval]
518      description: string