Composite YAML Plans

Split a plan across YAML files with !include. The tag can replace any YAML value: a mapping, list, or scalar. Paths resolve relative to the file containing the directive, including within nested includes. Quoted paths support spaces. Included files must have a .yaml or .yml suffix.

# plan.yaml
project: FY27 Plan
summary: !include prose/summary.yaml
execution:
  milestones: !include milestones.yaml
  description: !include prose/overview.yaml
  activities:
    - !include activities/solver.yaml
    - !include activities/runtime.yaml
  tasks:
    - !include tasks/solver.yaml
    - !include tasks/runtime.yaml

An activity file contains a mapping:

# activities/solver.yaml
id: solver
label: Solver Development
description: Develop and validate solver capabilities.

A task file can contain a list, inserted into the surrounding list in order:

# tasks/solver.yaml
- id: SOLVER_UPDATE
  label: Update solver
  activity: solver
  description: !include ../prose/solver-description.yaml
  status: ongoing
  funding: !include ../budgets/solver.yaml

The prose file contains a YAML scalar, while funding contains a mapping:

# prose/solver-description.yaml
>-
  Develop the solver and validate its integration.
# budgets/solver.yaml
fy27: 100K
fy28: 150K

Expansion rules

  • In a mapping value, the include is replaced by the included value.

  • In a list, an included list is spliced into its surrounding list in order. An included mapping or scalar becomes one item. Ordinary nested lists remain nested.

  • A whole file can consist of a single !include directive.

  • Includes may be nested, and files may be included more than once. Include cycles, including cycles through symbolic links, are errors.

  • Includes are supported in value positions, not mapping keys. There are no implicit mapping merges or overrides. Normal plan validation runs after expansion; defaults and multipart tasks work across included task lists.

  • YAML anchors and aliases remain local to each file. Recursive aliases are rejected. Custom Python tags and included Python files are unsupported.

Read commands expand composite YAML into a temporary standalone snapshot before loading the plan, and remove that snapshot automatically. Diagnostics retain original filenames and lines for included task, milestone, and activity mappings; included scalar fields may identify the containing mapping or include site. Python plan files and general configuration files do not support !include.

Write a standalone composite

planner composite plan.yaml expanded.yaml
# With TUXFAN_PLANNER_DATA_FILE set:
planner composite expanded.yaml

Output is required. This command writes expanded YAML without applying task defaults, normalizing model fields, or expanding multipart tasks. It checks include structure and file access but does not require a valid task schema; use planner validate expanded.yaml to validate the resulting plan. Inputs without includes also work.

Output contains expanded data, not original comments, formatting, or include directives. Existing output is replaced atomically only after successful expansion. Output must not overwrite the root input or any included file, including through symbolic or hard links.

Source editing

format formats the main file and every recursively included YAML source once, preserving include directives and file boundaries. Each formatter runs from its source’s directory, using normal configuration discovery (including ancestor directories). Source encoding and line endings are retained. The complete include graph is checked before tools run; missing or invalid includes and cycles are errors. All formatted results must preserve YAML structure, values, and include references before any source is saved. Changed files receive numbered backups and atomic replacement individually; saving the complete set is not one atomic transaction, so later write failures can leave earlier files formatted.

spell-check follows nested includes and reviews original source prose once per field in one interactive session. Field context crosses include boundaries, so scalar descriptions and lists of manager names are reviewed, while IDs, references, include paths, and enum fields remain protected. Text shared between prose and structural contexts is skipped with a manual-review message. The include graph is checked before tools run. Corrections are staged across all files, summarized by source, and saved only after one final confirmation; cancellation during review discards all corrections and dictionary additions.

The session selects one personal dictionary: explicit --personal wins, otherwise discovery starts at the main plan’s directory and uses the nearest .planner-words.pws in that directory or an ancestor, falling back to Aspell’s usual personal dictionary. Included files do not select separate dictionaries. Ignore-all and dictionary additions apply throughout the session. Additions are saved only after the final confirmation. Each changed source receives a numbered backup and atomic replacement. Saving all sources and the dictionary is not a single atomic transaction; later failures report files already saved.

Migrating plan organization

planner composite old.yaml nested.yaml --nested expands includes and writes collections under execution and resourcing without changing task definitions, references, defaults, or multipart structure. The output is a standalone file; original sources are untouched. Without --nested, authored organization is retained. To keep includes, instead move tasks/milestones/deliverables include entries under execution and project dependencies/risks/prose under resourcing. Included list fragments need no extra wrapper.