Skip to main content

Project Planner

A small planning system that lets you define project plans and tasks in YAML or Python. Validate plans, inspect funding and dependencies, and export documents, diagrams, presentation slides, and fiscal-month Gantt charts.

Why tuxfan-planner?

  • Keep plans easy to review. Author readable YAML or Python files, track changes in Git, and review plan updates alongside your code.
  • Catch planning problems early. Validate task references and dependency cycles, and get warnings about late or unknown milestone and deliverable timing, with source locations that help you find the cause.
  • Plan around fiscal years. Track funding by fiscal year, schedule ongoing work across funded years, and total multipart budgets without double counting.
  • Connect tasks to outcomes. Link work to execution narratives, deliverables, and milestones, and keep GitLab work item and merge request references with the tasks they support.
  • Find the view you need. Filter tasks, activities, milestones, deliverables, work items, and risks without editing the underlying plan or losing full-plan readiness information.
  • Organize larger plans. Reuse YAML fragments with includes, inherit shared task metadata, and merge or split multipart tasks as the plan evolves.
  • Publish from one source. Generate Word documents, SVG diagrams, editable PowerPoint plan slides and Gantt charts, and PDFs through Microsoft Word. Apply your own PowerPoint presentation or template for consistent branding.

Repository: git@re-git.lanl.gov:tpp/planner.git

Release notes: NEWS.md.

Installation

Use Python 3.11 or newer.

Install from PyPI

If you only want to use the planner, create and activate a virtual environment and install the published package. No repository checkout is needed:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install tuxfan-planner
planner --help

This installs the planner and its required Python dependencies. Activate .venv again when starting a new shell. To get started with your own plan, follow Your first plan below.

Install from source

For development or to use a local checkout, run these commands from the repository root:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
planner --help

The editable installation uses the source in this checkout. CMake installation and development setup are described in DEVELOPER.md.

Quick start

From the repository root, validate the fictional example plan, list its tasks, and export a Word document:

planner validate data/tasks.yaml
planner list data/tasks.yaml
planner export data/tasks.yaml /tmp/plan.docx --config planner/examples/config.yaml

The output file is written to /tmp/plan.docx. For other outputs, see Exporting.

data/tasks.yaml is the canonical fictional jet-airplane development fixture. data/composite.yaml includes the same plan. Their values are invented; use them instead of private plans for future development. See the fixture guide for coverage and examples.

Contents

Basic commands

Command Purpose
validate Check a plan and report validation statistics.
list Show the full terminal planning document.
list KIND Show a selected top-level plan element; compatibility object views remain available.
list-detail Show full task details.
show Print unique values used by one field in a plan.
avail Print predefined schema options for one field, without a plan.
fields Print a copyable YAML template for a mapping type.
summary Show counts by execution section and milestone, plus funding totals.
schedule Show tasks in dependency order and their readiness.
export Write a Word (.docx), SVG (.svg), PDF (.pdf), or PowerPoint (.pptx) plan.
import Import a planner-style Word document into a YAML draft.
export-gantt Write an SVG or PowerPoint (.pptx) Gantt chart.
composite Expand YAML includes into a standalone file.
merge Merge standalone YAML tasks into a multipart task.
split Split a multipart YAML task into standalone tasks.
format Format a YAML or Python plan with an optional external formatter.
spell-check Review prose interactively with Aspell.
completion Generate a shell completion script.

Run planner COMMAND --help for arguments and examples, or see the CLI reference.

The legacy tuxfan-planner command remains available as an alias. Run planner --help to see the current package version and the current values of all planner environment variables alongside the command help.

Your first plan

Save this as tasks.yaml. It defines one pending task with a two-month duration:

priorities: [capability]
project: Aircraft Development
tasks:
  - id: DraftDesign
    category: development
    label: Draft aircraft design
    description: Produce the initial airframe design.
    start: M1Q1FY27
    expected: 2
    priority: high
    status: pending
    risk:
      - type: schedule
        level: low
        mitigation: Review progress weekly.
planner validate tasks.yaml
planner list tasks.yaml

id identifies the task for dependency references; label is its display name. execution_section links tasks to the corresponding entry in execution.sections. Tasks without a link appear under Unassigned. The top-level project names the overall plan. start is a fiscal period, and expected counts months including the start month. This task runs from October through November 2026. priority, status, and risk describe the planned work. Ongoing and completed tasks have exceptions to the planning field requirements, explained below.

Fiscal period values

start and completed must use M{month}Q{quarter}FY{year}:

  • month is 1 to 3 within the quarter
  • quarter is 1 to 4
  • year is a 2-digit fiscal year, for example FY26

Fiscal years begin on October 1:

  • Q1 = October through December
  • Q2 = January through March
  • Q3 = April through June
  • Q4 = July through September

Examples:

  • M1Q1FY26 = October 2025
  • M2Q3FY26 = May 2026
  • M3Q4FY26 = September 2026

Duration and completion

Task dates use start plus expected. For example:

start: M3Q4FY26
expected: 2

This task spans M3Q4FY26 through M1Q1FY27. A duration of 1 stays in the start month. Compact completed tasks may omit both scheduling fields; they use completed as the start and a one-month duration.

Status values

Use one of:

  • pending
  • planning
  • active
  • ongoing
  • blocked
  • unfunded
  • complete
  • closed

Plan structure and fields

A plan can be a raw task list or a mapping containing tasks and optional plan metadata. Start with the mapping form shown above.

Plan metadata

A plan can include optional top-level project metadata:

  • portfolio: portfolio or parent program name.
  • project: high-level project name.
  • managers: list of manager names.
  • pocs: list of point-of-contact names.
  • summary: high-level plan summary.
  • fiscal_range_begin and fiscal_range_end: optional fiscal year range covered by the plan, for example 27 through 31.
  • execution: execution metadata. It can be a mapping with overview text and sections, where each section has label, description, and an optional stable id for task links. The older flat list of sections is still accepted.

Planning placeholders

Use status: planning to add a task before its schedule, priority, and risks are known. Only five task fields are required:

priorities: [capability]
tasks:
  - id: FUTURE_DESIGN
    category: development
    label: Future design work
    description: Scope and deliverables to be developed.
    status: planning

Add optional fields as the plan develops. Supplied values are validated normally; omitted priority defaults to low and risks to an empty list. A start or duration may be supplied individually, but timing remains Unscheduled until both start and expected exist. Unknown duration displays as Unspecified. With both fields, normal month-based timing applies, including a provisional Gantt bar. Undated placeholders sort after dated tasks.

Funding estimates contribute to totals without creating dates or full-year bars (as they do for ongoing). Dependencies are allowed, but planning tasks do not satisfy dependencies and always show PLANNING in the schedule. Lists and exports retain placeholders; Word narratives mark them [PLANNING]. Changing to an execution status enforces its usual required fields.

Closed tasks are marked [CLOSED] in gray in Word narratives. Closed tasks require only id, label, description, category, and status: closed and display CLOSED in schedules. Execution section, timing, priority, and risk are optional; supplied values are validated. Without both start and expected, timing remains Unscheduled and no Gantt bar is drawn. They use gray styling; unfunded tasks use muted amber. Valid choices from planner avail status and generated templates list closed last.

YAML plan and export-option files reject duplicate explicit keys with source locations. Explicit entries may still override values inherited through << merges.

Task fields

Tasks use only execution_section for grouping and funding for budgets. The optional Funding export column calculates the sum of a task's fiscal-year amounts; parent budgets retain the existing count-once rule in plan totals. Top-level project remains the overall plan title. Every unknown key is an error at its source location, including task/part keys, nested metadata, and export options. There are no special diagnostics or compatibility aliases for removed fields.

Each task supports these fields. start, expected, priority, and risk are optional for closed tasks, planning placeholders, ongoing tasks, and complete tasks with a completed period:

  • category: required ID from configuration task_categories; parts inherit their parent category unless overridden.
  • id: required non-empty string task id (quote numeric IDs). Must contain only letters, numbers, or underscores, with no spaces.
  • label: required non-empty string display name for the task.
  • site: optional site or institution label.
  • bnr: optional budget and reporting identifier.
  • type: optional task type label.
  • tags: optional comma-separated string or list of task tags. Omitted or null values mean no tags.
  • execution_section: optional ID of a section under execution.sections. Linked tasks use that section's label and position for activity headings and task numbers in exports. An unknown ID is rejected.
  • description: required non-empty string describing the task.
  • note: optional string with additional task information. Unrecognized keys are rejected uniformly.
  • workitems: optional GitLab work item or merge request references; see Work item references.
  • start: required fiscal period string in M{month}Q{quarter}FY{year} format, where month is 1 to 3 within the quarter.
  • expected: required positive whole number of months for the task duration. The end month is computed from start, counting the start month as month one.
  • completed: optional fiscal period string for work that is already complete. A task with status: complete and completed may omit planning-only fields: start, expected, priority, and risk. A complete task without completed still requires these fields.
  • milestones: optional list of milestone IDs, for example [Design, Implementation]. Every ID must match a top-level milestone definition. Omitted/null values or an empty list mean no milestones.
  • priority: required string priority label such as low, medium, high, or urgent.
  • status: required string status. Allowed values are pending, planning, active, ongoing, blocked, unfunded, complete, and closed. Use unfunded for work awaiting funding.
  • dependencies: optional list of task ids. Omitted or null values mean no dependencies. Each supplied dependency must reference another task id.
  • risk: required risk entry or list of risk entries. Each entry has type, level, and mitigation, and may include description; level must be low, medium, high, or extreme.
  • funding: sole budget input, an optional mapping of fiscal year to funding level, for example fy27: 50K. A task is treated as unfunded for fiscal years not present in this mapping. For tasks other than ongoing, a warning is issued when a funding year falls outside the fiscal years covered by the task's start and calculated end month.

Omitted dependencies and tags are empty collections internally. Outputs that need a value display None, including dependency fields in list-detail and schedule, SVG dependency text, and an explicitly selected Tags table column. The concise list output continues to omit empty Dependencies lines.

Milestones

Define milestones at the top level with id, label, description, and a fiscal deadline. deliverables is an optional list of IDs referencing top-level deliverable definitions. Omitted/null/empty lists mean no references. IDs must be unique and use letters, numbers, and underscores. Tasks can omit milestones; every supplied ID must be defined, including links inherited by multipart tasks. Task files without milestone references need no section. Milestone deadlines do not change task durations or dependency scheduling.

Summary counts include a task under each of its milestones. Duplicate task milestone IDs are counted once. CLI metadata and Word output include milestone definitions; plan SVG headers summarize milestone labels and deadlines. Word and SVG exports display milestone labels without IDs.

Deliverables and deadline checks

Define outputs in a top-level deliverables list. Each entry requires id, label, description, and type. IDs use letters, numbers, and underscores; types are paper, document, presentation, or release (trimmed and normalized to lowercase). A document is material such as internal documentation that does not require submission, unlike a paper intended for submission. It can be marked complete directly; no submitted step is required. Additional types are added in code, not through plan configuration.

priorities: [capability]
deliverables:
  - id: RESULTS
    label: Results paper
    description: Reviewed manuscript describing the results.
    type: paper
milestones:
  - id: REVIEW
    label: Program review
    description: Results available for review.
    deadline: M3Q2FY27
    deliverables: [RESULTS]
tasks:
  - id: WRITE
    category: development
    label: Prepare manuscript
    description: Analyze and write up the results.
    status: planning
    start: M1Q2FY27
    expected: 3
    deliverables: [RESULTS]

A task's optional deliverables list identifies its outputs. Every task referencing a required output is a required producer. References are trimmed and deduplicated; omitted/null/empty means none. Multipart parts inherit the list and may replace or clear it. All task and milestone references must resolve.

For a required deliverable, readiness is the latest finish of all its producers. Its required-by date is the earliest deadline of milestones requiring it. Each task must finish by every milestone it cites and every milestone requiring one of its required outputs. Completion in the deadline month is allowed. These constraints produce warnings; they never move tasks, add duration/funding, or change dependency readiness.

Explicit completed dates on complete tasks supply actual timing; other finish dates are forecasts. An undated or closed producer keeps output readiness unknown. Ongoing task forecasts use the final funded month; use a separate dated task when an output is due before ongoing work ends. A required output without producers also produces a warning. All producers being complete means inferred complete, not submission or acceptance. Separate draft and final outputs if milestones require different versions.

Deliverables accept an optional status:

Status Meaning Effect
required Committed output; default when omitted All producer and deadline checks apply
planning Output is still being planned Defer assessment through this output
blocked Required output has an obstacle Retain all producer and deadline checks
submitted Delivered for review; awaiting acceptance Remain outstanding and retain all producer and deadline checks
complete Output has been delivered and considered fulfilled Satisfy its requirement independently of producer states
closed Output is no longer required Remove its requirement while retaining the record

Status values are trimmed and normalized to lowercase; explicit null/empty or unknown statuses are invalid. Planning and closed outputs do not acquire a readiness or required-by date. Producer references remain visible for history. Filtering and summary relationship counts retain these historical links; they do not indicate outstanding obligations. Direct task-to-milestone requirements, task dependencies, and requirements through other outputs still apply. Structural validation (including all references and required definition fields) always applies, regardless of status.

A complete deliverable may record an actual completion period:

  - id: RESULTS
    label: Results paper
    description: Reviewed manuscript describing the results.
    type: paper
    status: complete
    completed: M3Q2FY27

completed requires explicit status: complete and a valid fiscal period. Completion after a milestone deadline produces a historical timing warning; completion during that month is allowed. Without completed, the output still satisfies its requirement and displays "completion date unknown", without borrowing a producer's forecast or issuing missing-producer/timing warnings. Producer completion can still yield inferred complete for a required output, but never changes its stored status. Marking an output complete does not complete its producer tasks. Blocked and submitted outputs retain the same producer and deadline constraints as required outputs. Completed producers do not imply that a blocked output is unblocked or a submitted output is accepted; their explicit states remain authoritative. complete means delivered and considered fulfilled, including acceptance when that is required. completed remains exclusive to complete; no submission date is recorded in this version.

validate counts definitions and warnings; list-detail, summary, and plan exports show outputs and derived timing. list ... deliverables, show ... deliverables.type, show ... deliverables.status, fields deliverable, avail deliverables.type, and avail deliverables.status help inspect and author them. --only deliverables=ID also accepts a label; milestone filters and summary counts include indirectly linked producers. Filtered detail output retains readiness computed from all producers.

Migration: milestone deliverables formerly contained prose. Move each item into a top-level definition and replace milestone text with its ID. Unknown references are errors; legacy prose is not silently accepted.

Work item references

workitems: optional mapping or list of mappings, each requiring id as a GitLab project-path reference such as aircraft/design#42 or aircraft/design!69. The path must include a namespace and project (nested subgroups are accepted), using ASCII letters, digits, underscores, dots, and hyphens, with each segment starting with a letter or digit. A positive decimal item number follows # (work item) or ! (merge request). Surrounding whitespace is trimmed. IDs are server-relative references, not URLs; no server or item-existence lookup is performed. Explicit type is rejected; the Python API derives WorkItem.type as workitem or mr.

Each entry also accepts status: open (the default when omitted) or closed, trimmed and normalized to lowercase. Explicit null or other statuses are rejected. CLI and configured exports display the status.

Optional assignees accepts a list of non-empty moniker strings, trimmed with case and order preserved. Omitted, null, or empty lists mean no assignees. CLI and configured exports display assigned monikers.

Optional label is a display name, trimmed with omitted/null values becoming empty strings; non-string values are rejected. Labels appear before work item identifiers in CLI and configured exports and support inline Markdown in Word/SVG.

Optional description is prose text, trimmed with omitted/null values becoming empty strings. Descriptions appear with the reference in CLI output and configured exports, where the task-description inline Markdown subset is supported.

Omitted, null, or empty lists mean no references. Multipart parts inherit the parent's references unless they replace or clear them. References appear in list-detail and schedule attributes; select workitems in export options for a Word column or SVG card attributes.

For example, a task can reference a merge request and an issue:

workitems:
  - id: aircraft/design!59
    label: Solver update
    status: closed
    assignees: [designer_one, designer_two]
    description: Review solver changes.
  - id: aircraft/assembly#12
    status: open

YAML format

Top-level can be either a list of tasks or a mapping with a tasks key. The mapping form can also include plan-level metadata such as portfolio, project, managers, pocs, summary, fiscal_range_begin, fiscal_range_end, and execution.

priorities: [capability]
portfolio: Advanced Simulation and Computing
project: Task-Parallel Project
managers:
  - Alice Example
pocs:
  - Casey Example, PI
summary: >
  High-level planning context for the task collection.
fiscal_range_begin: 27
fiscal_range_end: 29
execution:
  overview: >
    Overall execution context for the plan.
  sections:
    - id: deliverable_a
      label: Deliverable A
      description: >
        Narrative execution detail for this deliverable.

deliverables:
  - id: ARCHITECTURE
    label: Architecture document
    description: Reviewed architecture document.
    type: paper
  - id: PARSER
    label: Parser
    description: Released parser implementation.
    type: release
milestones:
  - id: Design
    label: Design
    description: Complete the architecture draft.
    deadline: M2Q3FY26
    deliverables: [ARCHITECTURE]
  - id: Implementation
    label: Implementation
    description: Deliver the task parser.
    deadline: M2Q3FY26
    deliverables: [PARSER]
  - id: Phase_A
    label: Phase A
    description: Complete the first phase.
    deadline: M3Q2FY27
    deliverables: []
  - id: Phase_B
    label: Phase B
    description: Complete the second phase.
    deadline: M3Q4FY28
    deliverables: []

tasks:
  - id: DraftArchitecture
    category: development
    label: Draft architecture
    bnr: EXAMPLE-001
    site: Example Works
    type: labor
    tags:
      - architecture
    execution_section: deliverable_a
    description: Produce the first architecture draft.
    start: M1Q3FY26
    expected: 2
    milestones: [Design]
    priority: high
    status: complete
    dependencies: []
    risk:
      - type: scope
        level: medium
        description: Integration requirements may change during implementation.
        mitigation: Review the architecture with stakeholders before implementation starts.
    funding:
      fy27: 50K
      fy29: 100K

  - id: BuildParser
    category: development
    label: Build parser
    description: Load task definitions from YAML and Python files.
    start: M2Q3FY26
    expected: 1
    milestones: [Implementation]
    priority: high
    status: pending
    dependencies:
      - DraftArchitecture
    risk:
      - type: integration
        level: medium
        mitigation: Add schema validation tests for both YAML and Python task sources.

  - id: MultiYearDelivery
    category: development
    label: Multi-year delivery
    site: Example Works
    parts:
      - id: A
        category: development
        label: First phase
        funding: {fy27: 50K}
        description: Complete the first phase.
        start: M1Q1FY27
        expected: 6
        milestones: [Phase_A]
        priority: high
        status: active
        dependencies: []
        risk:
          - type: schedule
            level: low
            mitigation: Review progress monthly.
      - id: B
        category: development
        label: Second phase
        funding: {fy28: 100K}
        description: Complete the second phase.
        start: M1Q3FY27
        expected: 18
        milestones: [Phase_B]
        priority: medium
        status: pending
        dependencies:
          - A
        risk:
          - type: technical
            level: medium
            mitigation: Keep integration tests current.

Viewing and filtering

Use list for an activity-based view, list-detail for all task fields, summary for counts and funding, and schedule for dependency readiness.

planner list-detail data/tasks.yaml
planner summary data/tasks.yaml
planner schedule data/tasks.yaml

Choose what to list

planner list plan.yaml displays the full terminal planning document: project metadata and priorities, fiscal coverage, execution narratives (including empty sections), milestone and deliverable definitions, and numbered tasks with category labels/IDs, planning attributes, notes, risks, and work item details. Unreferenced definitions remain visible. planner list does the same when TUXFAN_PLANNER_DATAFILE supplies the input. Terminal Markdown, colors, 80-column prose wrapping, multipart grouping, and automatic paging apply.

Export settings (elements, optional columns, and include_note) do not limit list output. Use planner list plan.yaml summary tasks or other existing field selections to project information, and --only to filter tasks and their related definitions. Readiness and numbering retain full-plan context; referenced tasks may still appear in definition relationships. No matching tasks produces the existing notice and zero funding totals.

Use planner list tasks plan.yaml for the original compact task-only view. planner list plan plan.yaml retains the scoped metadata/relationship summary.

Use planner list KIND [task_file] [FIELD ...] to select the objects to display. The primary kinds match the top-level names accepted by export.elements: portfolio, project, priorities, managers, pocs, summary, fiscal_range_begin, fiscal_range_end, fiscal_years, execution, milestones, deliverables, and tasks. Each has its own help. For example, planner list summary plan.yaml prints only the summary; planner list execution plan.yaml prints the overview and all sections. Missing metadata displays None; priorities and names retain their order. The execution fields are overview and sections.

The compatibility views activities, workitems, risks, and plan remain available with their existing behavior. With TUXFAN_PLANNER_DATAFILE configured, omit task_file. Kind names take precedence over default-input field projections; put the filename first to combine projections, such as planner list plan.yaml project summary tasks. Prefix reserved-kind filenames with ./.

Kind Default contents
tasks Existing activity-grouped task listing
milestones Definitions, deadlines, outputs, associated tasks, direct links, and current required tasks
deliverables Definitions, lifecycle status, producers, readiness, and required-by dates
activities Every execution section, including empty sections, with tasks, counts, and funding; Unassigned appears when needed
workitems Unique reference IDs with owners and every conflicting metadata variant
risks Each risk entry with severity, mitigation, and owning task
plan Plan metadata, execution overview/sections, and relationship summaries

In planner list plan, execution sections use 1: Section label headings in declaration order, with ID: and Description: indented beneath each heading. The same layout applies when selecting the execution field.

planner list tasks data/tasks.yaml
planner list deliverables data/tasks.yaml --only type=document
planner list deliverables data/tasks.yaml label status ready required_by
planner list milestones data/tasks.yaml --only deliverables=NEEDS
planner list activities data/tasks.yaml label task_count funding
planner list workitems data/tasks.yaml --only status=open
planner list risks data/tasks.yaml --only level=high
planner list plan data/tasks.yaml
planner list deliverables --help

Fields are scoped to the requested kind: list tasks ... status selects task status only; list workitems ... status selects reference status. Identity headings remain visible. Field names are exact, and each kind's help lists its choices. Additional fields are tasks, direct_tasks, producer_tasks, and required_tasks for milestones; producers, ready, and required_by for deliverables; tasks, task_count, and funding for activities; tasks and derived type (workitem/mr) for workitems; and tasks for risks. These view fields do not extend the input schema or the show command.

Filters apply directly to the requested objects, so unreferenced definitions and empty activities remain visible. Target a native field such as id, label, type, status, or level, or related tasks, activities, sections, tags, milestones, deliverables, or workitems. Relationship targets accept IDs or labels (workitems use their IDs). Singular aliases work, and producers/producer aliases tasks. Use TARGET=VALUE to match whole values or TARGET~VALUE for literal substring matching within that target. Bare values match substrings across all searchable fields. Matching ignores case and trims whitespace. Comma-separated values are OR alternatives; repeated flags are AND requirements. For example:

planner list deliverables data/tasks.yaml --only type=document,paper --only status=complete
planner list deliverables data/tasks.yaml --only tasks=PURPOSE
planner list milestones data/tasks.yaml --only direct_tasks=PURPOSE
planner list tasks data/tasks.yaml --only 'id~HARD'
planner list tasks data/tasks.yaml --only 'id~HARD,SOFT' --only status=active
planner list deliverables data/tasks.yaml --only 'label~report'

id~HARD matches HARD_DEVELOPMENT, HARD_SUPPORT, and SOFTWARE_HARDENING. Matching is literal, with no regular expressions or globs; the first = or ~ separates target and value, and later operators are literal characters in the value. =~ is not a separate operator: label=~draft matches the exact label ~draft. These substring selectors apply to explicit list KIND commands; legacy list [task_file] and list-detail retain their existing filters.

For tasks, --only id=ASSEMBLY selects every expanded part of multipart parent ASSEMBLY; --only id=ASSEMBLY_A selects only that expanded task. Standalone IDs still match exactly. Exact comparisons ignore case, but do not match prefixes or local part IDs. id~TEXT searches both expanded and parent IDs for a substring. Parent selectors can be combined with other filters, for example:

planner list tasks data/tasks.yaml --only id=AIRFRAME --only tags=build

Readiness always uses every producer in the full plan. Activity funding uses all its tasks, counts multipart parent budgets once per activity, and includes configured zero-funded years; years are inferred from funding if none are configured. Milestone tasks retains historical links, direct_tasks shows direct links, producer_tasks shows tasks required through outputs, and required_tasks reflects current lifecycle requirements. Filtering does not change those values.

Shared workitem IDs appear once. Identical metadata merges owners; conflicting labels, descriptions, statuses, or assignees remain in owner-labeled variants. Repeated filters must match one variant. A selected reference still displays all variants, so conflicts remain visible. Risks remain separate entries under their owning tasks. All views share Markdown, links, 80-column wrapping, colors, NO_COLOR, and automatic paging. IDs in identity headings and reference fields use bold standard magenta so they stand out from labels and prose. Closed task entries stay gray; unfunded task entries use muted amber, with bold IDs. Plain and redirected automatic output remain uncolored; --color always can explicitly enable the highlighting.

Task relationship lists use parent:child for multipart references, for example, Baseline Design [AIRFRAME:BASELINE]. This applies to milestone task lists, deliverable producers, activity tasks, workitem owners, risks, and plan task summaries. Task labels use normal cyan; IDs retain their magenta styling. The colon form is for display: YAML, dependencies, and exact selectors still use expanded IDs such as AIRFRAME_BASELINE. Underscores within the parent or child ID are preserved. Normal grouped task headings retain local part IDs. Task relationship fields put each task on its own indented, hyphen-bulleted line, including when selecting fields explicitly:

Tasks:
  - Baseline Design [AIRFRAME:BASELINE]
  - Advanced Design [AIRFRAME:ADVANCED]

This also applies to direct tasks, producer tasks, required tasks, and deliverable producers. Each reference wraps at 80 visible columns, and empty lists display None.

planner list plan.yaml and planner list plan.yaml FIELD ... preserve the legacy task view, including its cross-context field selection and task filters. With a default input, reserved kind names now select object views: planner list deliverables lists definitions. Use planner list plan.yaml deliverables for the legacy container projection. If a filename equals a kind, qualify it as ./tasks, etc. The following task-list and filtering details describe the legacy shorthand; list tasks without fields retains its task layout.

List output and ordering

Normal list output identifies each multipart group with an unnumbered parent heading, such as Airframe Development [AIRFRAME]. Its parts are indented beneath it, with their descriptions and details one level deeper. Filtering retains the parent heading for matching parts. Part numbers and dependency references stay the same. Field-selected output keeps its existing layout. Child headings show the part ID exactly as written in the source, for example, Task A.1: Baseline Design [BASELINE] beneath Airframe Development [AIRFRAME]. Standalone headings show the task ID. Dependencies and selectors still use expanded child IDs such as AIRFRAME_BASELINE; local IDs are not selector aliases. Task heading labels use normal cyan, retaining explicit Markdown emphasis. IDs use the shared ID colors, with closed task IDs gray and unfunded task IDs muted amber. If a parent or task heading would exceed 80 visible columns, its bracketed ID moves to a separate line indented two spaces further. Long labels and IDs wrap within that limit, with Unicode widths and color codes accounted for. All divider lines end at column 82, including indented dividers between parts.

The explicit list tasks FILE view prints tasks in Word activity and task-number order with each task's description, a Note: line when present, numbered dependencies when present, status, and a single funding line for identified fiscal years (for example, Funding: $500K (FY27), $250K (FY28)). For configured fiscal years, a Total Funding: line at the bottom shows every year in thousands of dollars, including $0K years. Linked activity headings also show their execution section descriptions. Activity/task descriptions and notes wrap at 80 terminal columns, accounting for wide characters, combining marks, and styling. A gray block line separates tasks within an activity. Darker gray double rules align with activity headings before each activity and between its description and first task. It uses color when stdout is a compatible terminal, with dollar amounts in light green, statuses by state, and the entire entry for an unfunded task in muted amber and a closed task in gray; --color always or --color never overrides automatic detection. NO_COLOR disables automatic color. Accepts a task file or uses TUXFAN_PLANNER_DATAFILE. Use field names such as label, status, or assignees to specialize output with nested context; combine them with --only to filter tasks first. label alone gives the compact label outline with work item ID fallback. Field selection omits funding totals.

list-detail prints full task details in calculated end-month order, including start/end fiscal periods and duration. Compatible terminals use cyan headings and task labels, blue field labels, subdued magenta IDs, status colors, and severity colors for priority and risk. Funding totals are green. Closed task blocks stay gray; unfunded task blocks use muted amber, with matching bold IDs. Use --color auto, --color always, or --color never; NO_COLOR, TERM=dumb, and redirection disable automatic color. Colorization preserves the existing text and layout, including literal Markdown, and works with automatic paging.

Paging long terminal output

Configure a pager once to keep colors without piping each command:

export TUXFAN_PLANNER_PAGER='less -R'
planner list

Long output opens in the pager automatically when both input and output are terminals. Short output stays direct. Planner detects colors before opening the pager, so --color always is unnecessary. NO_COLOR and --color never still control styling. Redirecting or piping output bypasses automatic paging; TERM=dumb also bypasses it. Unset the variable or set it to an empty value to disable paging.

Paging applies to list, list-detail, summary, schedule, show, avail, fields, and stdout help. Warnings/errors stay on stderr; validation output, completion scripts, editing prompts, and export/transform messages stay direct. The pager value is an executable plus arguments, with quoted paths supported, and runs without a shell. If it cannot start, planner prints the output directly. Output height accounts for wrapped lines and ignores ANSI color sequences.

Filter list output

Run planner list --help or planner list-detail --help for built-in filtering examples, or see the CLI reference for detailed matching and funding rules.

Use --only with list or list-detail to select tasks by activity, execution-section ID, tag, or milestone ID/label:

planner list tasks.yaml --only tags="Tag1, Tag2"
planner list-detail tasks.yaml --only milestones="Flight Deliverables"
planner list tasks.yaml --only sections=Aircraft --only tags=gpu
planner list tasks.yaml label --only tags=gpu
planner list tasks.yaml --only "aircraft, gpu"

Use list FIELD to specialize output by any supported field identifier, such as label, status, assignees, or mitigation. Replace FIELD with the exact input field name. Combine field names to display several fields. Nested selections retain the activity, task, and item context needed to identify their values. Container names such as workitems show their complete contents. Combine field selection with --only to filter tasks before displaying the requested information. Run planner list --help for supported field names. Shared names apply at each supported level: status selects task and work item statuses. type selects task and risk types; work item types are inferred and are not selectable input fields.

planner list tasks.yaml status assignees --only tags=gpu
planner list tasks.yaml risk mitigation
planner list tasks.yaml workitems

label alone retains the compact activity/task/work item outline, with two spaces per level and work item IDs when labels are absent. Field names are exact canonical input names (including underscores), without abbreviations, aliases, or computed properties. Input composition directives such as defaults and parts are expanded during loading, rather than exposed as selectable fields.

--only still filters tasks before rendering; work item labels/IDs and task labels are not additional filter fields. Selected tasks keep their work items; filtered metadata retains only associated milestone definitions and execution sections. Selected output omits unrelated details, separator rules, generated numbering, and funding totals. Empty requested fields display None; branches without a matching field are omitted. See the CLI reference for the full supported field list and contextual output examples.

A target= prefix limits matching to that field. Supported targets are activities, sections, tags, milestones, and deliverables; singular names also work. Activities match an activity name, section ID, or generated label such as Activity B. Milestones match IDs or display labels. Targeted values match complete field values, so tags=gpu does not match gpu-kernels.

Without a target, bare text matches substrings across all supported fields: --only "aircraft" can match a milestone ID, its label, a project, or a tag that contains aircraft. Matching ignores case and trims whitespace. Comma-separated values within one flag are alternatives; repeated --only flags must all match. For example, --only sections=Aircraft --only tags=gpu requires both the project and the tag. Quote values containing spaces.

Only matching tasks and their associated activities are listed. With list --only, activity headings show only IDs and labels, omitting activity descriptions. Dependencies are shown as references but do not pull other tasks into the view. Activity letters, task numbers, and dependency numbers stay consistent with the full plan. No matches produces a message and zero totals for configured years. Unknown targets and empty value lists are usage errors.

Fiscal-year totals use the matching tasks. If a multipart parent has funding, its full budget contributes once when any part matches, even when several parts match or the parts specify their own funding. If the parent has no funding, only matching parts' amounts contribute. list-detail also limits its activity metadata and funding totals to the selection. Filtering does not change exports.

Discover field values and valid options

Field selectors use positional names throughout: list tasks.yaml label status, show tasks.yaml tags, avail status, and fields task. The former --FIELD selectors are no longer accepted. With a configured default data file, use list label status or show tags. Options such as --only and --color retain their usual syntax.

Use fields to see a mapping's supported keys and copy an example into a plan:

planner fields task
planner fields risk
planner fields workitems
planner fields plan > new-plan.yaml

Types are plan, task, workitem, risk, milestone, deliverable, execution, and section; plural names tasks, workitems, milestones, deliverables, and sections are also accepted, as is execution.sections. Output is plain YAML with example values and comments listing fixed choices. Nested fields are expanded. Examples are starter values, not schema defaults. Optional completion and alternative fiscal-year fields are commented out. Individual mapping templates need the containing key or list and appropriate indentation when pasted; fields plan produces a complete plan. No input file is needed.

Print the tags used in a plan, or inspect the schema's allowed statuses:

planner show tasks.yaml tags
planner show tasks.yaml site
planner show tasks.yaml workitems.assignees
planner avail status
planner avail priority
planner avail level

Both commands require exactly one field name. Values print one per line; avail status adds explanatory group headings. show removes exact duplicates, skips empty values, and sorts alphabetically while preserving spelling and case. It accepts scalar fields and lists of scalars, including tags, dependencies, milestone references, and assignees. Unqualified fields collect values from every applicable context; use qualified names such as tasks.status or workitems.status to limit the context. Structured containers such as risk, workitems, and funding are not selectable. Includes and multipart inheritance follow normal plan loading. No values means no output. The usual input environment variables apply.

avail needs no data file. status prints separate labeled groups explaining the options for a task's status and a work item entry's status; priority means task priorities, and level means risk levels. Risk levels print in severity order: low, medium, high, extreme. Priorities print in order: low, medium, high, urgent. Task statuses are alphabetical with closed last; work item statuses print open, then closed. Only status, priority, level, deliverables.type, and deliverables.status are accepted by avail. deliverables.type prints paper, document, presentation, release. Other qualified field names are available with show; use it to discover free-form values.

Summary and dependency schedules

groups tasks by execution section and milestone and prints funding totals when task funding is present.

prints tasks in dependency order and marks them as READY, BLOCKED, ACTIVE, ONGOING, or COMPLETE.

Importing Word plans

planner import proposal.docx proposal.yaml
planner validate proposal.yaml

Import reads the visible content of a document structured like a planner Word export: project metadata, execution sections, task narratives, milestones, deliverables, risks, and available table attributes and annual funding. It generates stable IDs and reconnects deliverable references by their labels. Top-level YAML fields and execution sections retain their first-appearance order in the document. Blank lines and labeled comment dividers separate top-level YAML fields. One blank line separates list entries with an id field at every nesting level, including tasks, milestones, deliverables, execution sections, and work items. Task entries follow document order in the generated YAML; later CLI views and exports use the planner's normal task sorting rules.

Both filenames are required and relative to the current directory; planner environment overrides do not apply. The output must be a new .yaml or .yml file. The source is unchanged, and output is validated before publication.

The result is a draft for review. Word exports omit original IDs, multipart structure, task milestone links, dependencies, dates, priorities, and some statuses. Tasks default to planning without invented schedules; closed markers are preserved. Completed tasks require a full completion period to remain complete: the normal export retains only a year, so these become planning tasks with a review warning. Missing annual funding cannot be reconstructed from a total. Review comments are included in the YAML, and the command prints warnings with document block and table-row locations. Ambiguous deliverable references, unrecognized task structure, and validation errors prevent output.

If the document uses custom table headers, pass the options used for export:

planner import proposal.docx proposal.yaml --config config.yaml

Unrecognized columns are reported in review comments. A work item cell with multiple references is retained in the task note when its boundaries are ambiguous. The importer supports bold, italic, and hyperlinks in narrative prose; page layout and arbitrary Word formatting are not part of the YAML model.

Exporting

The output filename selects the format. All commands use the general YAML configuration described under Configuration. Export settings live in its export section. Gantt exports use configuration for plan validation but do not apply task-table settings.

# Planner initializes the default user configuration automatically on first use.
planner export data/tasks.yaml /tmp/plan.docx
planner export data/tasks.yaml /tmp/plan.svg
planner export-gantt data/tasks.yaml /tmp/gantt.svg
planner export-gantt data/tasks.yaml /tmp/gantt.pptx

Plan SVG and Gantt SVG/PowerPoint use pale amber (#E8D5A8) for unfunded tasks and light gray (#D1D5DB) for closed tasks. Terminal unfunded entries use ANSI color 137 (#AF875F), a subdued ochre.

All Word, PDF, plan SVG/PowerPoint, and Gantt SVG/PowerPoint exports include centered, bold CUI//SP-BDGT headers and footers. Word repeats them on every page; PowerPoint includes them on every slide.

Selecting exported elements

Use export.elements in the general configuration to select top-level plan fields for Word, PDF, SVG, and PowerPoint output:

export:
  elements: [project, priorities, summary, execution, milestones, deliverables, tasks]
  include_note: false

Omit elements, or set it to null, to include all elements. An empty list [] produces the generic document shell and export markings. Entries must be unique, case-sensitive top-level field names:

portfolio, project, priorities, managers, pocs, summary, fiscal_range_begin, fiscal_range_end, fiscal_years, execution, milestones, deliverables, and tasks.

The list selects content; each format retains its established section order. execution includes its overview and sections. tasks includes task narratives, Word/PDF scheduling and summary tables, and risk mitigation. Omitted metadata is removed from covers and headings; a generic title is used when project is excluded. SVG includes the selected metadata/narratives above its task cards.

Selecting fiscal_years displays the normalized fiscal-year coverage, including coverage supplied through a range. If it is excluded, selected fiscal_range_begin/fiscal_range_end values display individually when the plan defines a range. Task dates, funding, numbering, and readiness still use the full validated plan. References inside selected sections retain their context even when their standalone definitions are excluded. A partial Word export may lack the definitions needed to import it as a complete standalone plan.

export-gantt retains its existing behavior and does not use export.elements.

Project priorities use the configured display labels followed by [id] in all four formats. The first entry appears as Primary Priority: label [id]; remaining entries appear in order on separate indented lines under Auxiliary Priorities:. That heading is omitted when there are no auxiliary priorities. Word import resolves the appended IDs even when labels change or repeat. Older label-only documents resolve labels when each matches exactly one configured entry; ambiguous or missing references produce a review notice and a placeholder priority.

Task narrative layout

All four export formats place the task's existing number, label, and status first, then the configured category label and ID, followed by the description and optional italic notes. For example, within an activity in Word/PDF:

1. Design the wing [UNFUNDED]
Category: Development [development]
Produce and review the initial wing design.
Note: Coordinate with the structures team.

The Category: prefix is bold; the category display label is italic without bold, and its ID remains plain. Category always appears in the narrative, independently of selected table columns. Optional category columns remain available in the Word/PDF summary; SVG cards and PowerPoint task bodies avoid repeating the category as an attribute. Word/PDF preserve their complete/planning/closed markers and also mark unfunded tasks. SVG retains its task ordinal and schedule state; PowerPoint retains its generated task number, stored status, and schedule state in the heading. Notes follow the description when enabled. SVG cards expand for complete wrapped content; PowerPoint continues long tasks at the existing font size. Word keeps each heading and category with the following description.

Word import uses the category ID, so repeated or renamed display labels do not change identity. Older documents lacking category information still receive a review placeholder. An imported UNFUNDED marker is reported and converted to a planning draft because the narrative does not provide its required planning fields; review funding and timing before restoring that status.

Word, SVG, and PDF plans

writes a Word plan for a .docx output path or a graphical plan for .svg. SVG plan export warns about empty or duplicate generated element IDs (including dependency-marker conflicts), identifies affected tasks, and still writes the output with unchanged IDs. Add --include-note or set include_note: true in export options to show an italic Note: line after each task description. Use the configuration export section selected by --config PATH to control optional task attributes in both formats. The Word document includes a schedule and a detailed task table, starting on a new page with its section headings. When fiscal years are configured, the table includes one column per year with each task's funding level or a blank cell, plus a final total row. The SVG uses the same activity letters and task numbers as Word, and shows fiscal-year funding totals, completion years, and numbered dependencies. Its fill color reflects status, border color reflects risk, and an accent bar reflects priority. Both formats keep multipart task parts adjacent. Custom column labels also apply to PowerPoint plan attributes; table alignment applies to Word/PDF.

PDF export generates the same Word document and asks Microsoft Word to save it as PDF, preserving Word's page layout, page breaks, tables, headers, and footers. It requires Microsoft Word installed and activated on macOS or Windows; macOS may prompt for permission to automate Word. On macOS, conversion files are staged inside Word's own sandbox so Word does not need access to each export folder. Planner copies the finished PDF to the requested destination and removes the temporary files. On Windows, conversion files are staged beside the output. Word stays open after conversion. The same export options, custom table columns, alignment, and --include-note apply to Word and PDF. Pagination depends on the installed Word version and fonts, just as when saving a PDF directly from Word. Conversion failures report an error without replacing an existing output PDF. Linux users can export .docx and save it as PDF in Word on a supported system.

planner export data/tasks.yaml /tmp/plan.pdf --config planner/examples/config.yaml

PowerPoint plans and templates

A .pptx output starts with a title slide showing the project name, portfolio, managers, points of contact, and fiscal years. Managers and contacts retain input order and appear one name per indented line beneath their headings; commas inside a name are preserved. Fiscal years stay on one line when possible. Each activity, milestone, deliverable, and task starts on its own slide; different items are never combined. Project and execution overviews and fiscal funding totals have separate slides. Task slides include descriptions, schedules, dependencies, risks, and selected attributes. Text boxes expand within the slide's margins and reclaim excess title space to keep titles and names on single lines where possible. Long titles wrap onto additional lines instead of being shortened with ellipses; continuation slides reserve the same title space. Title font sizes stay fixed. Body text uses a consistent size across the deck, without shrinking or enlarging individual items. Long entries split across continuation slides for the same item. Prose reflows across the available text width rather than retaining YAML source line wrapping; blank lines preserve paragraph breaks. Task, milestone, and deliverable descriptions are separated from their following fields by a blank line. Task numbering and multipart grouping follow the other plan exports. --include-note and the configured task attributes/custom labels apply; table alignment is specific to Word/PDF. PowerPoint status values and risk labels use the Word export colors: complete is green, planning is blue-gray, closed is gray, and risks follow severity. Inline bold, italic, and links are retained. PowerPoint does not need to be installed to generate these slides.

planner export data/tasks.yaml /tmp/plan.pptx --config planner/examples/config.yaml
export TUXFAN_PLANNER_TEMPLATE_DIRECTORY="$PWD/templates"
planner export data/tasks.yaml /tmp/branded-plan.pptx --config planner/examples/config.yaml

Use --template custom.potx (or an absolute .potx/.pptx path) to select a specific template for .pptx output. It bypasses template search; a missing or invalid file is an error.

Without --template, Planner searches TUXFAN_PLANNER_TEMPLATE_DIRECTORY first, then the current directory. In each directory, it tries template.pptx before template.potx. An empty variable is unset. Relative directories resolve from the current directory; ~ is expanded. If neither directory contains a template, Planner uses its built-in design. A configured directory must exist. An existing invalid or unreadable template is an error, rather than silently falling back. This setting applies to export plan slides; export-gantt keeps its existing chart layout.

An existing .pptx presentation is a valid design source. Planner retains its slide size, masters, layouts, theme, and master/layout graphics, and replaces its slides with the plan. It selects a spacious title/body layout by geometry, including layouts whose title is a text placeholder. If none fits, it adds text boxes over a simple layout. Graphics placed only on example slides are not carried over; put reusable branding on the slide master or layout. Fixed text and dates on masters/layouts remain as provided, so remove stale sample dates when preparing your template. The original template file is unchanged, and output cannot overwrite it.

PowerPoint's native template format is .potx, which Planner also accepts as template.potx. To create one, open a presentation, use View > Slide Master to prepare the theme, branding, and a title/content layout, then select File > Save As (or Save as Template on Mac) and choose PowerPoint Template (.potx). Save it as template.potx in the configured directory. Do not just rename a .pptx file to .potx; use PowerPoint's format selection. See Microsoft's template instructions.

Gantt charts

writes a fiscal-month Gantt chart as .svg or .pptx, selected by the output file extension. For ordinary tasks, bars span start through the end month calculated from expected. Ongoing tasks instead have separate full-year bars for each year with positive funding. By default, the axis covers the configured fiscal year range exactly; tasks outside it are omitted and overlapping bars are clipped. Without configured fiscal years, it covers task and completion dates. Optional inclusive --from and --through bounds override the corresponding axis endpoints and accept a fiscal year such as FY26 or an exact period such as M1Q1FY26; a fiscal year expands to its first or last month as appropriate. Rows follow execution activity order; each task row keeps its number and label on one line when they fit, otherwise wraps the label at a word boundary within the two-line cell. Arrows leave the dependency bar's right edge and enter the dependent bar's left edge, routing around overlaps without bending farther right than either bar requires; they connect bars within each activity, and PowerPoint draws an arrow when both bars appear on the same slide. Status colors and completion markers identify progress. The SVG is a vector image; the PowerPoint file uses editable native shapes and splits activities into slides of up to ten tasks, with additional slides for timelines longer than five fiscal years. Copy the desired slide into an existing presentation. Gantt exports do not use task table export options.

planner export-gantt data/tasks.yaml /tmp/fy27-fy28.svg --from FY27 --through FY28
planner export-gantt data/tasks.yaml /tmp/partial.pptx --from M1Q1FY27 --through M3Q2FY28

Inline formatting in exports

Word (.docx) and plan SVG (.svg) exports support a small inline Markdown subset in displayed text fields, including labels, descriptions, summaries, notes, milestone text, and optional table values:

description: "Deliver the **prototype**, review *performance*, and see [the report](https://example.com/report)."
note: 'Use __bold__ or _italic_ text; escape markers as \*literal asterisks\*.'

Use **bold** or __bold__, *italic* or _italic_, and [link text](https://example.com). Bold and italics can be combined or nested. Links accept http, https, and mailto URLs and remain clickable when text wraps. Backslash escapes make marker characters literal; use single-quoted YAML strings for these escapes, or double the backslash inside double-quoted YAML. Unmatched markers and unsupported link targets remain literal text. Underscores inside words and identifiers remain literal.

This is inline formatting only; headings, lists, images, code, and HTML markup are not interpreted. Source values keep their original text. The list command also interprets this subset in activity and task labels and descriptions, using terminal bold/italic styles when color is enabled. Links display as label (URL). Plain output removes formatting markers and retains link destinations; descriptions wrap at 80 visible characters. Existing colors, including muted amber unfunded entries, are preserved. Other CLI commands and export-gantt retain their original text. Notes in exports still require --include-note or include_note: true to appear.

Export options

Export settings live beneath export: in the general YAML configuration. The YAML snippets below are contents of that section, not complete configuration files. The supported settings are elements, task_table_attributes, task_table_columns, and include_note. The first two control the optional task attribute columns included in the Word export summary table and the attributes shown on SVG task cards. Custom labels also apply to PowerPoint plan attributes; table alignment applies to Word/PDF. The .docx table always starts with an unlabeled column containing generated task numbers; it does not include a Project column. An Activity A, Activity B, etc. row precedes each activity's tasks, which appear in numeric task order. When tasks link to execution sections, the activity row includes the section label and its letter follows section order (for example, Activity B: Specialization Work with Task B.1). Unlinked tasks appear together under Unassigned. Each activity label occupies one left-aligned cell spanning the table. The column header repeats only when the table continues onto another page; Activity rows appear at their normal group transitions. All table cells center their content vertically. Fiscal-year columns are added automatically when plan fiscal years are configured, with a final Total Funding row that counts parent budgets once when present, otherwise summing included part amounts. For completed tasks, those columns become one green-filled cell labeled with the completion year (for example, Completed FY26) when a completed period is available, or Completed otherwise; the other cells remain black on white. The optional task metadata columns are limited to the attributes listed here. Word task descriptions do not append parenthesized attributes or funding details.

Set export.include_note: true in the configuration, or pass --include-note to export, to show italic notes, including the Note: label, after task descriptions. Task note lines are hidden by default. Select note as a table attribute when you also want a Note column in the Word summary table.

In the Word risk mitigation section, the bold risk label is green for low, yellow for medium, orange for high, and deep red for extreme. Mitigation text remains black.

Top-level Word section labels, including Tasks:, are bold and underlined.

Supported attribute names:

  • category
  • bnr
  • funding
  • note
  • workitems
  • site
  • type
  • tags

Simple YAML:

task_table_attributes:
  - site
  - bnr
  - tags

Shorthand YAML with custom labels:

task_table_attributes:
  - bnr: BNR
  - tags: Keywords

Recommended explicit YAML when you need labels or alignment:

task_table_columns:
  - attribute: bnr
    label: BNR
  - attribute: tags
    label: Keywords

Supported column alignment values:

  • left
  • center
  • right

alignment is optional and defaults to center.

Example CLI usage:

planner export planner/examples/tasks.yaml /tmp/plan.docx --config planner/examples/config.yaml

Advanced plan authoring

These features help organize larger plans and represent recurring or multipart work.

Task defaults

One optional defaults entry inside the tasks list sets site, bnr, and type for every task that omits them:

priorities: [capability]
tasks:
  - defaults:
      site: Example Works
      bnr: EXAMPLE-001
      type: labor

  - id: MAINTENANCE
    category: development
    label: Tool maintenance
    description: Maintain the planning tool.
    status: ongoing
    funding: {fy27: 50K}

The three values must be indented beneath defaults. Only one defaults entry is allowed, and it applies to all tasks regardless of its position. Explicit task values override defaults; explicit null or empty values clear a default. Multipart parents inherit defaults, and part values override parent values. Without defaults, site, bnr, and type remain optional. This also works in raw YAML lists and Python PLAN/TASKS lists. See planner/examples/task-defaults.yaml.

Ongoing tasks and funding

For status: ongoing, start, expected, priority, and risk are optional (dependencies and tags are optional for every task). Scheduling uses every fiscal year with positive numeric funding for its full twelve months, even when start/duration fields are supplied. Supplied optional fields are still validated. Omitted priority defaults to low; dependencies and risks default to empty lists.

id: Maintenance
label: Tool maintenance
project: Planning System
description: Maintain the planning tool.
status: ongoing
funding:
  fy27: 50K
  fy28: 0K
  fy29: 50K

This task spans all of FY27 and FY29, with no bar in FY28. Ongoing work has one Gantt bar per funded year; gaps are preserved. Its duration is twelve months per funded year. Without positive funding, it remains in lists and schedules but has no Gantt bar. Ongoing tasks without funded years sort after dated tasks.

Multipart tasks

A task can also be a multi-part task by using parts instead of the per-task schedule fields on the parent. Parent fields such as execution_section, site, bnr, note, type and tags are inherited by each part, while each part provides its own id, label, description, start, expected, priority, status, dependencies, and risk. Funding can be specified on the parent or on individual parts. Part ids are expanded as {parent_id}_{part_id}. Dependencies inside a multi-part task can reference sibling part ids, and dependencies from other tasks can reference the parent id to depend on all expanded parts. A parent-level budget contributes once to fiscal-year totals whenever any of its parts is included. Without a parent budget, totals sum the included parts only. Parts inherit parent funding unless they specify their own; explicit part funding controls their displayed amounts and ongoing time spans, while totals use the parent budget when present. In exports, parts in the same activity stay together at the position of their first part encountered in end-date order. Parts are ordered by end date, with ties retaining declaration order in the parent's parts list. The list command uses the same ordering, including list label. Dependency-aware schedules still respect dependencies.

Merging and splitting tasks

Use merge and split to restructure YAML tasks without changing the input file. Both accept a complete plan mapping or an incomplete task-list fragment, including a file that another plan includes. Supply the input filename and a new .yaml or .yml output filename explicitly:

planner merge tasks.yaml DraftDesign BuildPrototype --id Airframe --label "Airframe work" --output merged.yaml
planner split merged.yaml Airframe --output split.yaml

Merge accepts at least two standalone task IDs defined in the input file. It puts the parent at the earliest selected task's position and preserves source declaration order for the parts, regardless of command-line ID order. Identical shared fields may move to the parent; differing values and funding stay on the parts. Expanded IDs usually change (for example, DraftDesign becomes Airframe_DraftDesign), and the command prints the ID mapping and rewrites dependencies in the supplied file. Dependencies between the merged parts retain short sibling IDs, such as DraftDesign. References from other tasks use expanded IDs such as Airframe_DraftDesign.

Split replaces a parent with its parts in declaration order, materializes inherited parent fields, retains expanded IDs, and replaces local dependencies on the parent with dependencies on all resulting tasks. If the parent has a funding field, choose a policy explicitly:

planner split tasks.yaml Airframe --funding parts --output split.yaml
planner split tasks.yaml Airframe --funding equal --output allocated.yaml

parts preserves each part's effective funding, including inherited amounts; totals can increase when the original parent budget counted only once. equal replaces part funding with equal shares of the parent budget, allocating any remaining cents to the first parts in declaration order. Both commands report local funding totals before and after where available.

Comments, quoted strings, block scalars, UTF-8 BOMs, and line-ending conventions are retained where possible; YAML indentation may be normalized. Existing outputs cannot be overwritten. !include directives stay external, with relative paths adjusted if the output moves to another directory. Select tasks in the file that defines them; included files are never edited. Python input is not supported.

These commands check supplied task fields, visible ID collisions, and local dependency cycles. They permit external dependencies and missing required fields that may come from the containing plan. Review the ID mapping, update references in other files, and run planner validate on the assembled plan after replacing the fragment. Successful transformation means a structurally valid fragment, not a fully validated standalone plan.

YAML includes and composite plans

YAML plans can be split across files with !include at any value position:

priorities: [capability]
project: FY27 Plan
summary: !include prose/summary.yaml
milestones: !include milestones.yaml
execution:
  sections:
    - !include activities/solver.yaml
tasks:
  - !include tasks/solver.yaml
  - !include tasks/runtime.yaml

An included file contains the YAML value expected at that position: a mapping, list, or scalar. In a list, included lists are spliced in place; mappings and scalars become one item. Nested paths resolve relative to their containing file. Cycles and missing files are errors. Includes are value-only, with no implicit mapping merges; normal task validation follows expansion. Python plans and general configuration files do not support includes.

Read commands load a temporary expanded snapshot and clean it up automatically. Write a standalone copy with:

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

The output argument is required. Output preserves data and ordering, including defaults and multipart definitions, but not comments or formatting. It is written atomically after expansion, without requiring task-schema validation, and cannot overwrite any input file. format formats the main YAML file and all recursively included files in place, preserving include directives. spell-check reviews prose across the main file and included sources in one session, with one final save confirmation. See composite documentation for field-level examples and details.

Python format

Define PLAN or plan in a .py file for metadata plus tasks. The legacy TASKS or tasks list still works.

PLAN = {
    "priorities": ["capability", "safety"],
    "portfolio": "Advanced Simulation and Computing",
    "project": "Task-Parallel Project",
    "managers": ["Alice Example"],
    "pocs": ["Casey Example, PI"],
    "summary": "High-level planning context for the task collection.",
    "fiscal_range_begin": 27,
    "fiscal_range_end": 29,
    "execution": {
        "overview": "Overall execution context for the plan.",
        "sections": [
            {
                "id": "deliverable_a",
                "label": "Deliverable A",
                "description": "Narrative execution detail for this deliverable.",
            }
        ],
    },
    "deliverables": [
        {"id": "ARCHITECTURE", "label": "Architecture document",
         "description": "Reviewed architecture document.", "type": "paper"},
    ],
    "milestones": [
        {
            "id": "Design",
            "label": "Design",
            "description": "Complete the architecture draft.",
            "deadline": "M2Q3FY26",
            "deliverables": ["ARCHITECTURE"],
        }
    ],
    "tasks": [
        {
            "id": "DraftArchitecture",
            "category": "development",
            "label": "Draft architecture",
            "bnr": "EXAMPLE-001",
            "site": "Example Works",
            "type": "labor",
            "tags": ["architecture"],
            "execution_section": "deliverable_a",
            "description": "Produce the first architecture draft.",
            "start": "M1Q3FY26",
            "expected": 2,
            "milestones": ["Design"],
            "priority": "high",
            "status": "complete",
            "dependencies": [],
            "risk": [
                {
                    "type": "scope",
                    "level": "medium",
                    "mitigation": "Review the architecture with stakeholders before implementation starts.",
                }
            ],
            "funding": {"fy27": "50K", "fy29": "100K"},
        }
    ],
}

Configuration and optional tools

The general YAML configuration controls classification vocabularies and exports. Environment variables provide input defaults. Formatting, spell checking, and shell completion are optional conveniences.

User configuration

The package ships a default configuration and copies it on first use to ~/.config/tuxfan-planner/config.yaml, or $XDG_CONFIG_HOME/tuxfan-planner/config.yaml when XDG_CONFIG_HOME is set to an absolute directory. Edit this user copy to customize the planner. Package upgrades never overwrite it. Initialize it explicitly with planner config init; that command refuses to overwrite an existing file.

All operational commands require a valid configuration. --config PATH selects an alternate file and can appear before or after the command. Relative paths resolve from the current directory. An explicitly selected missing file, or an existing invalid/unreadable file, is an error; there is no silent fallback. Help and shell-completion generation do not initialize configuration.

config_version: 1
project_priorities:
  - id: capability
    label: Capability
    description: Deliver new or improved capabilities.
  - id: safety
    label: Safety
    description: Reduce safety risks.
task_categories:
  - id: development
    label: Development
    description: Develop and demonstrate capabilities.
export:
  task_table_columns:
    - attribute: category
      label: Category
  include_note: false

Each vocabulary is a non-empty list of entries with unique id values and non-empty label and description strings. IDs contain ASCII letters, digits, or underscores. Matching is case-sensitive after trimming surrounding whitespace. The shipped project priorities are safety, capability, and efficiency; task categories are research, development, and operations. Configuration files are complete documents: vocabulary lists are not merged with defaults. export: {} selects the existing default export settings.

Plan mappings require priorities: [capability, safety]; order expresses importance and the first entry is the primary priority. Duplicate or unknown IDs are errors. Every effective task requires category: development. Multipart parts inherit the parent's category unless overridden; null/empty values are invalid. Raw task lists have no project priorities, but still require categories. Task priority remains the separate low/medium/high/urgent field. Use planner avail priorities and planner avail category to see active IDs, labels, and descriptions; planner fields plan uses the active vocabulary in its examples.

Migration: add a non-empty label to every vocabulary entry in existing configurations. Labels are display names; plans continue to reference IDs. Then move the entire old export-options mapping beneath export: in a complete configuration, add the two vocabulary sections and config_version, and replace --export-options with --config. The retired TUXFAN_PLANNER_EXPORT_OPTIONS environment variable is ignored. Add priorities to existing plan mappings and categories to tasks or multipart parents. Word imports recover exported classifications when available; otherwise they use the first configured values as placeholders with explicit review comments.

Environment variables

TUXFAN_PLANNER_TEMPLATE_DIRECTORY selects the first directory searched for template.pptx or template.potx when exporting a PowerPoint plan. See PowerPoint plans and templates.

If you set TUXFAN_PLANNER_DATAFILE, the CLI uses that file by default:

An empty value behaves as unset. Supply an explicit input filename in that case; omitting it produces the normal usage error (exit status 2).

export TUXFAN_PLANNER_DATAFILE=planner/examples/tasks.yaml
# Planner initializes the default user configuration automatically on first use.
planner validate
planner list
planner list-detail
planner export /tmp/plan.docx
planner export /tmp/plan.svg
planner export-gantt /tmp/gantt.pptx

Set TUXFAN_PLANNER_DATA_DIRECTORY to work with multiple files by filename:

export TUXFAN_PLANNER_DATA_DIRECTORY="$PWD/data"
planner validate tasks.yaml
planner list composite.yaml label
planner export tasks.yaml /tmp/airplane.docx
export TUXFAN_PLANNER_DATAFILE=tasks.yaml
planner validate

Relative input filenames use the configured directory first, including a relative TUXFAN_PLANNER_DATAFILE. If the file is missing there, the same relative filename is tried in the current directory. Existing invalid or unreadable inputs do not trigger fallback. Absolute inputs bypass the setting. Output and export-options paths are unchanged, and includes remain relative to their containing files. The directory must exist; an empty value acts as unset. Setting the directory alone does not choose a default file.

Shell completion

The CLI can print completion scripts for bash, zsh, and fish:

planner completion bash
planner completion zsh
planner completion fish

For a one-session bash setup:

source <(planner completion bash)

To load completion automatically whenever you activate the Python virtual environment where Planner is installed, run once using that environment's planner:

planner completion install

Reactivate the environment afterward. This adds hooks to its existing bin/activate (Bash/Zsh) and bin/activate.fish scripts, retaining .bak backups. Repeating the command updates the hooks without duplicating them. Zsh initializes its completion system if needed. Installation requires a Python virtual environment and does not edit shell startup files. Rerun the command if the environment is recreated. Completion definitions remain in the shell after deactivation. CMake's default install-editable target runs this setup automatically.

The generated completion supports the basic planner subcommands, the tuxfan-planner alias, file path completion for task and output arguments, and --config for export commands. It also completes list/list-detail --only, list field names such as label and assignees, and list --color values, plus spell-check --lang and --personal.

Bash, Zsh, and Fish also suggest .yaml and .yml input files from TUXFAN_PLANNER_DATA_DIRECTORY, alongside normal local filename completion. Suggestions use relative filenames, support spaces and nested directories, and read the setting at completion time without loading or validating plans. For example, with the directory configured, planner list milestones pla<TAB> can complete plan.yaml there. Missing, unreadable, or unset directories add no suggestions. Absolute paths use normal filename completion.

Data-directory suggestions apply only to plan input positions, including the first input to merge and split. Output paths, configuration files, personal dictionaries, field names after an input, and option values keep their normal completion behavior. For export, export-gantt, and composite, when TUXFAN_PLANNER_DATAFILE supplies the input, the first filename is treated as an output and receives no data-directory suggestions.

After updating planner, reactivate the environment (or reload its completion script) to refresh the rules in your current shell. Running planner completion install alone updates activation hooks, not rules already loaded in the current shell.

Formatting data files

Format a single data file in place, or use TUXFAN_PLANNER_DATAFILE:

planner format tasks.yaml
planner format tasks.py
planner format

YAML (.yaml/.yml) uses Google's yamlfmt, installed separately from pip:

brew install yamlfmt
# Alternatively, with Go installed:
go install github.com/google/yamlfmt/cmd/yamlfmt@latest

Python (.py) uses Black from the same Python environment as planner:

python -m pip install 'tuxfan-planner[format]'
# In a checkout:
python -m pip install -e '.[format]'

An explicit path overrides the environment value. YAML formatting follows all !include directives recursively and formats each distinct source once, retaining the directives and separate files. Paths resolve relative to the file containing each include. Python formatting operates on one file and never executes it. The formatter runs from each source's parent directory and uses its normal configuration discovery: a .yamlfmt in a common parent directory can cover all files beneath it, with nearer configurations taking precedence. YAML comments, quotes, anchors, and block strings are handled by yamlfmt. Source encoding and line-ending convention are retained. YAML structure and values are checked before saving. Missing/invalid includes, cycles, and formatter failures stop the operation before any source or backup is written. All results are prepared and checked before saving begins; full task-schema validation is not required.

Changed files receive a numbered .bak backup and are replaced atomically. Saves are atomic per file, not across the complete set; a write failure after saving begins may leave some files formatted and others unchanged. Already formatted files are left alone. Missing formatter dependencies produce an installation error; other commands remain available. This CLI command formats data files; CMake's format target formats the planner source code.

Interactive spell checking

spell-check requires the Aspell executable and a language dictionary. These are system dependencies, installed separately from pip:

brew install aspell                    # macOS / Homebrew
sudo apt install aspell aspell-en       # Debian / Ubuntu

Check availability with aspell --version and aspell dicts. The default language is en_US; select another installed dictionary with --lang.

planner spell-check tasks.yaml
planner spell-check                     # uses TUXFAN_PLANNER_DATAFILE
planner spell-check tasks.yaml --lang en_GB
planner spell-check tasks.yaml --personal /path/to/project-words.pws

The terminal prompts show the filename, field, line, context, and numbered suggestions. On color-capable terminals, the exact occurrence under review is highlighted in bold red in the context. Other occurrences remain unhighlighted; NO_COLOR, TERM=dumb, and redirected output keep the context plain. Suggestions use as many columns as fit the terminal, up to 80 columns wide, with numbering increasing down each column. All suggestions remain available and selectable by their original number; narrow terminals use fewer columns, and long suggestions wrap. The fallback width is 80 columns. With an English dictionary, valid numeric ordinals such as 2nd, 30th, and 111th do not trigger suffix warnings. Standalone suffixes, malformed ordinals such as 22th, and embedded alphanumeric strings remain subject to Aspell's normal checks. Other dictionary languages are unaffected. Choose a suggestion number, r for a manual replacement, i to ignore once, a to ignore that spelling for the session, d to add it to the personal dictionary, or q to cancel. At the end, review the change summary and answer the save prompt. The default answer discards changes. Quitting, Ctrl-C, or end-of-input before saving discards staged corrections and dictionary additions. Interactive terminal input is required.

Composite YAML plans are supported: includes are checked before Aspell starts, then prose is reviewed in the original files, retaining field context across includes. This includes scalar or list fragments such as description: !include description.yaml and managers: !include managers.yaml. Each original source string is reviewed once, even when included repeatedly. Include paths are never spell-checked or changed. Shared text used as both prose and structural data is skipped with a manual-review message. Ignore-all and dictionary additions apply throughout the session. All corrections are staged before any source is saved; the final summary groups corrections by file. Python remains a one-file review.

Spelling checks cover prose: plan/project names, managers/contacts, summaries, execution narratives, task and milestone labels/descriptions, notes, deliverable labels/descriptions, risk descriptions/mitigations/types, and task site/type/tags. Schema keys, IDs/references, fiscal periods, status/priority/risk-level values, funding, and Markdown link destinations are skipped. Original source strings are checked once, including inherited multipart text and YAML aliases. Aliases or Python literals shared with structural fields require manual review. Notes are checked regardless of export visibility. Files need valid syntax but do not need to pass task validation.

Accepted corrections preserve source comments, quoting, block styles, indentation, line endings, and encoding. Saving creates a .bak backup (.bak.1, .bak.2, etc. if earlier backups exist) and atomically replaces the source after syntax and protected-value checks. Every source and any explicit or discovered personal dictionary are checked for concurrent changes before saving begins. Saves are atomic per source, not across all files or the dictionary; a later failure reports sources already saved. Symbolic links used by includes are preserved by editing their resolved targets; use the resolved target when invoking spell-check on a symbolic link directly. Python inputs are inspected without execution. Ordinary and triple-quoted literal strings can be edited; computed values, raw strings, and concatenated literals receive manual-review messages. Escaped spellings that cannot be replaced without changing syntax also require manual editing. Dictionary additions are saved only after the final prompt. Other planner commands work without Aspell.

Project word lists

To share accepted project terms, put an Aspell personal dictionary named .planner-words.pws in the data file's directory or an ancestor directory:

personal_ws-1.1 en 3 utf-8
FleCSI
FleCSolve
Kokkos

The header specifies the base language, word count (a hint), and encoding; subsequent lines contain one word each. Use en in English word-list headers; --lang en_US or --lang en_GB selects the installed spelling variant.

An explicit --personal PATH wins; relative explicit paths resolve from the current working directory. Otherwise, the nearest .planner-words.pws from the main input's directory upward is used. With no project dictionary, Aspell uses its usual personal dictionary. A discovered file must be readable and valid; an invalid nearer file is an error rather than a fallback to an ancestor. The selected dictionary is loaded before correction prompts and reported at startup. Explicit dictionary paths may name a new file, created only when confirmed additions are saved.

For composite plans, selection starts from the main input file, and that one dictionary applies to every included file. Dictionaries beside included files do not override it. The d action stages additions to the selected dictionary; it does not modify the file until the final confirmation. Selecting a project dictionary replaces Aspell's usual personal dictionary for that invocation; the installed language dictionary remains active.

Troubleshooting and further documentation

Ill-formed commands print an error and the relevant help text to stderr, then exit with status 2. Use planner COMMAND --help to check accepted arguments.

Input-file warnings and errors show filename:line when available. Funding warnings identify the funding entry; task validation errors identify the task block. Line numbers also cover literal Python inputs and YAML/Python syntax errors. Computed Python task entries may only have a filename.

Validation

checks required fields, invalid status values, invalid fiscal periods or non-positive/non-integer expected durations, invalid ids, duplicate ids, missing dependencies, and dependency cycles. Prints PASS/FAIL and statistics instead of plan metadata: activities (using list/export grouping), expanded tasks, milestone and deliverable definitions, execution sections, configured fiscal years, work item references per task, and emitted warnings. Warnings appear on stderr with source locations and terminal styling and are also counted; failures retain error diagnostics on stderr.

Migrating older plans

For existing task files, rename expected duration or expected_duration to expected and remove the task deadline field. Milestone definitions still use deadline.

Replace the former task milestone field with a milestones list. Legacy milestone names must become IDs with top-level definitions.

The former list --labels flag has been replaced by list label.

Documentation

Sphinx documentation lives in docs/. See the developer setup and checks for the current dependency and HTML build commands.

The repository's Documentation workflow is defined in .github/workflows/docs.yml. It builds the Sphinx output and publishes it to the gh-pages branch.

Updating the virtual environment

Follow the CMake workflow or the direct dependency commands in the developer guide to update the root .venv and check the result.

After configuring CMake, the default build performs an editable install:

cmake -S . -B build
cmake --build build
# Equivalently, from inside build/:
cmake --build . --target install-editable

The target uses the absolute source directory, so it works from any build location. Dependency upgrades and development checks remain explicit targets.

Metadata

Release files for tuxfan-planner 0.2.39

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tuxfan-planner 0.2.39
File Size Uploaded Provenance Actions
tuxfan_planner-0.2.39.tar.gz 341.5 kB Without provenance Details for tuxfan_planner-0.2.39.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tuxfan-planner 0.2.39
File Interpreter ABI Platform Actions
tuxfan_planner-0.2.39-py3-none-any.whl Python 3 none any Details for tuxfan_planner-0.2.39-py3-none-any.whl

Total release size: 506.2 kB

Release files / tuxfan_planner-0.2.39.tar.gz

Download URL tuxfan_planner-0.2.39.tar.gz
Size 341.5 kB
Tags Source
SHA-256 checksum
How to use checksums
7ede03e8fc584e4ad6780233e440ff60052813a7700fc220b5f36bcfe26430bf
BLAKE2b-256 checksum
How to use checksums
131872c71b5a1d0c352f7c64d701b09e3a0eeed3dddcf0094fcca56ec7f1c73b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.2

Release files / tuxfan_planner-0.2.39-py3-none-any.whl

Download URL tuxfan_planner-0.2.39-py3-none-any.whl
Size 164.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1f988cc3b2c5277ae5ab32aa986a40b69f05759563990ba1afa19771fbf75d4f
BLAKE2b-256 checksum
How to use checksums
059c0d95cbf39d1cf78faf29030b61e4eeb9a59a10771d83f677de97ef388d91
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.2

Security for tuxfan-planner 0.2.39

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.39 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page