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
- Why tuxfan-planner?
- Installation
- Quick start
- Basic commands
- Your first plan
- Plan structure and fields
- Viewing and filtering
- Importing Word plans
- Exporting
- Advanced plan authoring
- Configuration and optional tools
- Troubleshooting and further documentation
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 activity 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 (or planner help COMMAND) for arguments and examples, or see the
CLI reference. Each command and scoped list view starts with a
one-line explanation, followed by copyable examples, short notes, related
commands, and a manual reference. Detailed rules live in the
CLI, configuration, and
export references.
The legacy tuxfan-planner command remains available as an alias.
Help also follows command/topic paths:
planner help # top-level help
planner help fields # same as planner fields --help
planner fields help task # fields help; task is a validated mapping type
planner help list tasks # same as planner list tasks --help
planner list help tasks
planner list tasks help
help may appear once along a command/topic path. Positional choices such as
fields task, config init, and completion bash show their parent command's
help. Unknown topics report an error with the nearest relevant help. Help uses
the same colors and pager as --help, without loading plans or initializing
configuration. Bash, zsh, and fish complete help topics. Use ./help or
list -- help to pass a literal filename named help; option values named
help remain ordinary values. Help aliases do not apply after filenames or
other unrestricted arguments.
Run planner --help to see the current package version and the current values
of all planner environment variables alongside the command help.
Use planner --version or planner -v to print only the version number and exit.
Your first plan
Save this as tasks.yaml. It defines one pending task with a two-month duration:
project: Aircraft Development
execution:
tasks:
- id: DraftDesign
category: development
priority: capability
label: Draft aircraft design
description: Produce the initial airframe design.
start: M1Q1FY27
expected: 2
status: pending
risk:
- type: schedule
level: low
mitigation: Review progress weekly.
planner validate tasks.yaml
planner list tasks.yaml
Export configuration follows the same nesting: export.elements.execution
contains activities, tasks, milestones, and deliverables;
export.elements.resourcing contains project dependencies, stakeholders, users,
risks, and the generated task table. Their declaration order supplies the default
export placement. export.structure optionally overrides placement. Existing
flat selections remain accepted; defining the same field in both locations is
an error. planner fields config prints the canonical nested configuration.
execution contains description, activities, tasks, milestones, and
deliverables. resourcing contains project dependencies, stakeholders,
users, and risks. Fiscal coverage and project budgets stay at the top level.
Existing flat plans remain readable; defining the same field in both locations
is an error. planner fields plan prints the nested starter. To migrate to a
separate standalone file, run planner composite old.yaml nested.yaml --nested;
this expands includes. Included list fragments need no wrapper when their
include directives move under the appropriate container.
id identifies the task for dependency references; label is its display name.
activity links tasks to the corresponding entry in execution.activities. 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}:
monthis1to3within the quarterquarteris1to4yearis a 2-digit fiscal year, for exampleFY26
Fiscal years begin on October 1:
Q1= October through DecemberQ2= January through MarchQ3= April through JuneQ4= July through September
Examples:
M1Q1FY26= October 2025M2Q3FY26= May 2026M3Q4FY26= September 2026
Duration and completion
Task dates use start plus either expected (months) or end (a fiscal period). For example:
start: M3Q4FY26
expected: 2
An equivalent input is:
start: M3Q4FY26
end: M1Q1FY27
The endpoints count inclusively. If both expected and end are supplied,
they must agree; end cannot precede start. Parts may replace inherited duration
with an end or inherited end with a duration. The existing funding-driven timing
for ongoing tasks remains unchanged. Use line: [start, end] in task formatting
to show effective dates for either input form.
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:
pendingplanningactiveongoingblockedunfundedcompleteclosed
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:
portfolios: ordered portfolios or parent programs. Accepts a scalar, a YAML list, or a Markdown list block (the formerportfoliokey is rejected).project: high-level project name.managers: list of manager names.pocs: list of point-of-contact names.summary: high-level plan summary.background: optional project background prose; selected by the ASC v4 profile.fiscal_range_beginandfiscal_range_end: optional fiscal year range covered by the plan, for example27through31.execution: a mapping with optionaldescriptionprose and anactivitieslist. Each activity requiresid,label, anddescription; tasks link withactivity: ID. Legacy names and flat-list execution input are rejected.
Project dependencies and risks
Project dependencies define commitments with id, label, type
(internal or external), description, and a fiscal promised date.
Their optional risks list references project-level risk IDs of any of the
five predefined risk types. Task dependencies can mix task IDs and commitment
IDs. IDs in that shared namespace must be unambiguous, including multipart aliases.
Project risks require id, label, type, level, and mitigation, with an
optional description. Inline task risk entries keep their existing structure
and remain private; dependencies cannot reference them.
dependencies:
- id: TEST_HARDWARE
label: Test hardware arrival
type: external
description: Hardware required for integration tests.
promised: M1Q2FY27
risks: [DELIVERY_DELAY]
risks:
- id: DELIVERY_DELAY
label: Delivery delay
type: schedule
level: high
description: Hardware may arrive late.
mitigation: Reserve capacity and identify alternatives.
Use planner list dependencies plan.yaml, planner list risks plan.yaml,
planner fields dependency, and planner fields project-risk to inspect or
create records. planner avail dependencies.type lists commitment types.
Project commitments remain unconfirmed; their promised dates do not automatically
unblock pending tasks. Starts before a promised month warn without changing dates.
export.elements.risks produces a consolidated section with project risks and
all inline task risks, retaining severity colors and task ownership. It supports
ordered line: instructions, field styles, heading controls, and spacing.
tasks.risk independently controls risk details beneath tasks. See the
export formatting reference for an example.
The old request_dependencies and external_risks prose keys are rejected.
Migrate their content into definitions after reviewing missing dates and risk
attributes. Import preserves older Word prose in the summary for review.
Planning placeholders
Use status: planning to add a task before its schedule, priority, and risks
are known. Only five task fields are required:
tasks:
- id: FUTURE_DESIGN
category: development
priority: capability
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 is unassigned and risks default to an empty list. A start or duration
may be supplied individually, but timing remains Unscheduled until both start
and either expected or end 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. Activity, timing, priority, and risk are optional;
supplied values are validated. Without start and either expected or end, 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 activity 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. priority and risk are optional for every task.
Planning timing (start with expected or end) is optional for closed tasks, planning placeholders,
ongoing tasks, and complete
tasks with a completed period:
category: required ID from configurationtask_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 single site ID; restricted by configurationsiteswhen supplied.bnr: optional single budget and reporting ID; restricted by configurationbnrswhen supplied.type: optional built-in task type ID, or a list such as[labor, contract]; allowed values arelabor,contract,equipment,services, andnonlabor.tags: optional comma-separated string or list of task tags. Omitted or null values mean no tags.activity: optional ID of an activity underexecution.activities. Linked tasks use that activity'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 inM{month}Q{quarter}FY{year}format, wheremonthis1to3within the quarter.expected: positive whole number of months for the task duration; required unlessendis supplied or the task status permits omitted timing. The end month is computed fromstart, counting the start month as month one.end: alternative inclusive end period withstart. If bothendandexpectedare supplied, they must agree.completed: optional fiscal period string for work that is already complete. A task withstatus: completeandcompletedmay omit planning-only fields:startandexpected. A complete task withoutcompletedstill 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: optional single configuredtask_prioritiesID. Omitted/null/empty text means unassigned. Lists, unknown IDs, and legacy urgency values are rejected.status: required string status. Allowed values arepending,planning,active,ongoing,blocked,unfunded,complete, andclosed. Useunfundedfor work awaiting funding.dependencies: optional list of task ids. Omitted or null values mean no dependencies. Each supplied dependency must reference another taskid.risk: optional risk entry or list of risk entries. Omit it or userisk: []for no risks; null is rejected. Each entry requirestype,level, andmitigation, and may includedescription. Types aretechnical,schedule,operational,external, andperformance(trimmed and normalized to lowercase);levelmust below,medium,high, orextreme. Useplanner avail risk.typeto list types.funding: sole budget input, supporting typed amounts and staff labor allocations (see Staff funding), or an optional mapping of fiscal year to funding level, for examplefy27: 50K. A task is treated as unfunded for fiscal years not present in this mapping. For tasks other thanongoing, a warning is issued when a funding year falls outside the fiscal years covered by the task'sstartand 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, release, software, dataset,
model, service, training, demonstration, assessment, design, or
hardware (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.
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
priority: capability
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
A plan can be a raw task list or a mapping with execution.tasks. Existing top-level tasks collections remain readable for compatibility, including the flat examples below. The mapping form can also include plan-level metadata such as portfolios, project, managers, pocs, summary, fiscal_range_begin, fiscal_range_end, and execution.
portfolios: 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:
description: >
Overall execution context for the plan.
activities:
- 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
priority: capability
label: Draft architecture
bnr: EXAMPLE-001
site: Example Works
type: labor
tags:
- architecture
activity: deliverable_a
description: Produce the first architecture draft.
start: M1Q3FY26
expected: 2
milestones: [Design]
status: complete
dependencies: []
risk:
- type: technical
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
priority: capability
label: Build parser
description: Load task definitions from YAML and Python files.
start: M2Q3FY26
expected: 1
milestones: [Implementation]
status: pending
dependencies:
- DraftArchitecture
risk:
- type: technical
level: medium
mitigation: Add schema validation tests for both YAML and Python task sources.
- id: MultiYearDelivery
category: development
priority: capability
label: Multi-year delivery
site: Example Works
parts:
- id: A
category: development
priority: capability
label: First phase
funding: {fy27: 50K}
description: Complete the first phase.
start: M1Q1FY27
expected: 6
milestones: [Phase_A]
status: active
dependencies: []
risk:
- type: schedule
level: low
mitigation: Review progress monthly.
- id: B
category: development
priority: capability
label: Second phase
funding: {fy28: 100K}
description: Complete the second phase.
start: M1Q3FY27
expected: 18
milestones: [Phase_B]
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, fiscal coverage, execution narratives (including empty
sections), milestone and deliverable definitions, and numbered tasks with
category labels, planning attributes, notes, risks, and work item details.
Unreferenced definitions remain visible. planner list does the same when
TUXFAN_PLANNER_DATA_FILE supplies the input. Terminal Markdown, colors,
prose wrapping at the configured width (80 by default), multipart grouping, and automatic paging apply.
Export content selection and layout settings 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:
portfolios, project, managers, pocs, summary, background,
fiscal_range_begin, fiscal_range_end, fiscal_years, fiscal_current, planned_value,
calculated actual_value, execution,
milestones, deliverables, tasks, dependencies, stakeholders,
users, and risks. Each has its own help.
For example, planner list summary plan.yaml prints only the summary;
planner list execution plan.yaml prints the execution description and all activities.
Missing metadata displays None; names retain their order.
The execution fields are description and activities.
The compatibility views activities, workitems, risks, and plan remain
available with their existing behavior. With TUXFAN_PLANNER_DATA_FILE 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 activity, including empty activities, 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 description/activities, and relationship summaries |
In planner list plan, activity definitions use Activity A: label [ID] 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, activities, 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, wrapping at the configured width (80 by default), 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 the configured width (80 visible columns by default), 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.
In descriptions containing bullet lists, source line breaks within prose paragraphs
and indented bullet continuations reflow to the available width. Blank lines and
nested bullets are preserved, so YAML |- blocks can use readable source wrapping.
If a parent or task heading would exceed the configured width (80 visible columns by default), 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 80, including indented dividers between parts.
Description text in terminal list views uses canary (#ffff99), including nested
descriptions, field projections, and configured lines. Explicit configured colors
override this default. Closed/unfunded headings and status fields keep their muted colors, and
layout.context_colors: false disables this semantic coloring.
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 Funded Total: line at the bottom shows every year in thousands of dollars, including $0K years. Linked activity headings also show their activity descriptions. Activity/task descriptions and notes wrap at 80 terminal columns, accounting for wide characters, combining marks, and styling. Main sections have bold muted cyan headings framed by muted orange double rules; indented subsections use bold muted cyan headings and thin gray rules. Activity headings use muted cyan and record titles use cyan, with lighter gray separators between items. Complete plans group child sections under Execution and Resourcing, and configured lists preserve their declared order. Field-only projections remain compact. 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_DATA_FILE. 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 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,
activity 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 activities=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, activities, tags, milestones, and deliverables; singular names
also work. Activities match an activity name, activity 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 activities=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
planner fields config > new-config.yaml
Types are config, plan, task, workitem, risk, project-risk, dependency,
milestone, deliverable, execution, and activity; plural names tasks, workitems,
project-risks, risks, dependencies, milestones, deliverables, and activities
are also accepted, as is execution.activities. risk describes a private task risk;
risks describes a project risk definition. 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.
fields config prints a complete configuration template using packaged defaults,
with bare entries for enabled export content and explicit false for disabled fields,
including the complete nested export.elements tree, optional task ID
allowlists, and table layout examples. Export sections follow their declaration
order. The command ignores --config and does not read or initialize user configuration, so it
works even when that file is missing or invalid. Other template types use the
active configuration for vocabulary examples.
Task site and bnr examples honor configured allowlists; omitted allowlists
leave those IDs unrestricted. Task type accepts one built-in ID or a list of
IDs: labor, contract, equipment, services, nonlabor.
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
planner avail risk.type
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 highlights copyable IDs and choices in bold magenta, and explicit
table_entry values in cyan. Labels and descriptions stay plain. Coloring is
automatic in compatible terminals; redirection, NO_COLOR, or TERM=dumb
produces plain text. The configured pager retains colors. Output wraps at 80
visible columns. Each priority/category ID is on its own line with indented
label, description, and optional table_entry details; blank lines separate
records. Other fields retain one choice per line.
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, level means risk levels, and risk.type
lists the five predefined risk types.
Risk levels print in severity order: low, medium, high, extreme.
Priority choices print configured IDs, labels, and descriptions in declaration order.
Task statuses are alphabetical with closed last; work item statuses print open, then closed.
avail accepts status, priority, level, deliverables.type,
deliverables.status, category, site, bnr, and type.
site and bnr print IDs from configured task allowlists; an omitted allowlist
has no predefined options and produces an error. type always lists the five
built-in task types.
deliverables.type prints all supported output types listed above. Other qualified
field names are available with show; use it to discover free-form values.
Summary and dependency schedules
groups tasks by activity 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
planner validate proposal.yaml
Import reads the visible content of a document structured like a planner Word
export: project metadata, activity definitions, 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 activity definitions 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.
The output filename is optional: planner import plans/proposal.docx writes
plans/proposal.yaml beside the source. Supply an output filename to override
this default. Relative paths use 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. Missing task IDs are generated from their
labels: Engine Model Development becomes ENGINE_MODEL, for example. IDs use
uppercase ASCII words separated by underscores, drop common connectors and
routine terms such as development and improvements, and shorten preparation
to PREP. Qualifiers are retained without a fixed word limit. Duplicate or
conflicting IDs receive _2, _3, etc., in document order, reserving recovered
explicit IDs and project dependency IDs. Multipart tasks use the new parent ID
with their existing local part IDs. A label without usable ASCII words falls
back to TASK; numeric labels receive a TASK_ prefix. Recovered explicit task
IDs are preserved, and recovered relationships use the resulting IDs.
Word exports may omit original IDs, multipart structure, task milestone links,
dependencies, dates, priorities, and some statuses. Missing forecast timing is inferred from positive fiscal-year funding:
start defaults to M1Q1 of the first year with a positive amount, and end to
M3Q4 of the last such year. Existing start/end dates and durations are preserved.
These provisional bounds cover intervening funding gaps; review notices in the
report and YAML identify inferred fields. Allocation parts use their own effective
funding. Zero, missing, or placeholder amounts do not establish dates, and an
annual breakdown cannot be recovered from a total alone.
Tasks retain recovered statuses, including unfunded, when required timing is
available. Missing statuses and tasks without recoverable required timing use
planning; closed markers are preserved. Ongoing tasks keep their funding-driven
timing, and completion dates are never inferred. 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. 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
Select the ASC version 6 output contract in your configuration:
export:
standard: asc-v6
header: 'CUI // EXAMPLE'
layout:
spacing: normal
headings:
underline: false
task_table:
orientation: landscape
fiscal_years: [FY28, FY29, FY30, FY31, FY32, FY33]
For ASC v4, use export: {standard: asc-v4} with elements and layout
omitted to apply its defaults: normal spacing, underlined headings, portrait
funding tables, and v4 section/column order. An optional plan background
field appears after the summary. The v4 table uses Site, BNR, Funded/Unfunded
Status, Type, Tags, and annual amounts with units; priority/category columns
and totals are optional additions. Existing explicit selections/layout settings
still override profile defaults. Omitting standard continues to select
legacy; existing user configuration files are not rewritten.
Keep separate rules in export.standards.asc-v4 and export.standards.asc-v6,
each containing optional header, elements, and layout settings. The active
export.standard selects its block. Built-in profile defaults are overridden
by shared export settings, then by that block. Layout mappings merge; selections
and ordered lists replace. An omitted selection inherits shared settings;
elements: null restores profile defaults. All blocks are validated, including
inactive ones. planner fields config shows an example; see the
export options reference for full merge rules.
Override the configured standard for a single export:
planner export data/tasks.yaml plan-v4.docx --standard asc-v4
--standard accepts legacy, asc-v4, and asc-v6 and selects the matching
configured rules without changing the file. Without it, export.standard
remains the default. It applies to Word, PDF, SVG, and PowerPoint output.
Use the same override when validating the plan and its configuration:
planner validate data/tasks.yaml --standard asc-v4
Validation resolves the selected rules and checks all configuration blocks, including inactive ones, without generating output or modifying the config.
ASC v6 restores section headings, defaults to underlined headings and landscape
Word/PDF table pages, and uses the new funding-table columns. The example
disables underlining for other deliverables. Header and footer use the same
literal marking; an empty string removes both. Omitting standard preserves
legacy output. Existing elements selections still apply; omit elements and
column layout to use the complete ASC defaults. planner fields config shows
configuration examples.
export.layout.spacing accepts normal (the ASC v4 default, using reference
document spacing) or tight (the legacy/ASC v6 default). Word/PDF normal paragraphs
use 8-point gaps, while tables stay single-spaced. SVG and PowerPoint adapt their
paragraph spacing and layout accordingly.
After portrait tables, the following paragraph receives an 8-point gap in
normal mode or 4 points in tight mode, preserving existing spacers and breaks.
Plans may add prose fields dependencies, stakeholders, users, and
risks; milestones may add reporting_level: L1 or L2. Import an older
Word draft with planner import old.docx updated.yaml --update asc-v6 to request
migration and receive review notices for missing information. Imported drafts
record their output version in comments; choose the same export standard in
configuration when exporting them.
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 use an empty
marking by default. Set export.header to add matching centered, bold headers
and footers. Word repeats them on every page; PowerPoint
includes them on every slide.
Selecting exported elements
export.elements in the general configuration is the single content-selection
mechanism for Word, PDF, SVG, and PowerPoint. Use true for an entire branch,
false to disable it, and a mapping to select children. A bare entry such as
milestones: means milestones: true, including nested fields and table columns. Omitted children are
disabled; omitted/null elements enables everything. The packaged default
lists every supported field explicitly and disables notes. Sections follow
declaration order; selection does not change validation, numbering, schedules,
or funding totals.
export:
elements:
project: true
summary: true
execution:
tasks:
number: true
label: true
category: true
description: true
note: false
site: true
funding: true
risk:
type: true
level: true
description: true
mitigation: false
resourcing:
task_table:
columns:
number: true
site: true
funding: true
fiscal_funding: true
totals: true
Task fields select narrative content independently of table columns. An enabled
column remains available when its narrative field is omitted or false. task_table: false removes the Word/PDF summary table. Risk and
mitigation appear within each owning task; there is no separate mitigation
section. Nested selections also work for work items, activity definitions,
milestones, and deliverables. Generated task fields include number, end,
duration, state, and funding_status. fiscal_years takes precedence over the individual
fiscal-range endpoints when all are selected.
Table totals accept the same children as list.elements.totals:
totals:
activity: true # table subtotals default to bottom; top/bottom also accepted
bnr: true
unfunded: false # true adds a separate Unfunded Total
Place this under export.elements.task_table to include the overall total and
selected subtotals. Regular totals exclude unfunded budgets; unfunded: true
adds an Unfunded Total: row immediately before Funded Total: with the
same formatting as activity and B&R subtotals. It previously included unfunded
amounts in regular totals. Bare totals: or totals: true shows only the overall total;
false, {}, or all-false children disables it. The previous sibling settings
totals_activity, totals_bnr, and totals_unfunded remain supported with
boolean/bare totals, but cannot be mixed with a totals mapping.
Task priorities appear in task narratives and in the priority table column,
which reads each task independently and preserves assignment order. export-gantt and terminal listing remain
independent of these controls. See Export Options
for the complete selection and layout reference.
Summary prose supports quoted italics across source-wrapped lines, including summaries with bullet lists:
summary: |-
Our purpose is *"Explore robust methods,
connect models, and improve future experiments."*
The plan provides:
- A clear baseline.
Quotes need no escaping inside a literal YAML block. Word/PDF keeps each
summary line break, including blank lines, and retains emphasis across lines.
Use >/>- instead of |/|- to fold source wrapping into paragraphs.
Parent-only task exports
To show each multipart parent once while retaining standalone tasks, add:
export:
layout:
multipart: parents
The default is multipart: expanded. This setting applies to Word/PDF task
narratives and tables, SVG cards, and PowerPoint task slides, and supports
per-standard overrides. Parent entries use the authored parent label,
description, note, risks, and work items; missing parent prose stays empty.
Child prose is omitted from the task entries. Common classifications and status
are retained; differences display as Mixed. Dates cover the children's overall
calendar span when all parts have timing; otherwise the entry indicates partial
or unspecified timing. The span can include gaps and is not summed effort.
Funding totals, subtotals, budget comparisons, dependency checks, and readiness continue to use the original parts. Shared parent budgets still count once. References to hidden children use their parent's displayed number; sibling-only references are omitted from that parent's entry. Standalone tasks stay visible. A parent spanning activities appears in its first declared part's activity, with a warning; activity/B&R subtotals keep their original assignments.
Separately selected relationship/risk sections keep their original detail.
Gantt charts and terminal lists retain their current behavior. Summary exports
are lossy: Mixed values and omitted child fields may require manual review
before importing a summary document as a task plan.
Task narrative layout
All four export formats place the task's existing number, label, and status
first, then Category: and Priority: with their configured labels, followed by the description
and optional italic notes. For example, within an activity in Word/PDF:
1. Design the wing [UNFUNDED]
Category: Development
Produce and review the initial wing design.
Note: Coordinate with the structures team.
The Category: prefix is bold; the category display label is normal text,
without an appended ID. This emphasis is fixed even inside styled lines;
an explicit heading: false hides the prefix. Category appears when elements.tasks.category is enabled, 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. Rendered children are indented one
level below their parent: task fields beneath tasks, and risk/work-item fields
beneath their individual headings. Wrapped lines preserve this hierarchy in
Word/PDF, SVG, and PowerPoint. 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 resolves displayed category labels against the active configuration. Missing or ambiguous labels receive a reported review placeholder. Older documents with appended category IDs remain supported. 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. Enable export.elements.execution.tasks.note in the configuration 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 and its border color reflects risk. 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 nested export selection, table labels, and alignment
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, portfolios,
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 descriptions 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. The nested content selection and
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 orange, 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 the configured width (80 by default). Existing colors, including muted amber unfunded entries,
are preserved. Other CLI commands and export-gantt retain their original text.
Notes in task narratives require
export.elements.tasks.note: true to appear.
Terminal list configuration
An optional list: section selects terminal content and formatting independently
of export:. If absent, existing list behavior is preserved. The syntax shares
bare entries, booleans, nested selections, section ordering, repeated line:
instructions, and per-field bold/italic/color settings:
list:
elements:
project:
milestones:
- line: [id, label]
bold: true
- required_tasks:
tasks:
- line: [id, label, status]
bold: true
- description:
- risk:
mitigation:
deliverables:
Omitted children in mappings are excluded; bare/true branches include their
available fields. Omitted/null elements includes the full document. Terminal
views also expose their existing relationship fields, such as milestone
required_tasks, and calculated task fields such as end, state, and
funding_status. Deliverables expose an additional assessment text field.
task_table and export layout controls are not accepted under list.
planner fields config includes a commented example; adding it is optional.
An explicit kind requests that kind even if configured selection omits it; its configured formatting applies when present. Explicit positional fields use the existing projection layout and override configured selection/formatting. Filters still restrict objects, while calculations and numbering use the complete plan. Bare elements inherit their normal terminal layout, grouping, and colors even when other elements have custom instructions. Field-only mappings retain the standard scoped field rendering. Custom lines inherit semantic label/ID/status colors and closed/unfunded shading; standalone fields keep normal label colors, indentation, and relationship bullets. Explicit style overrides take precedence. Existing color controls, NO_COLOR, wrapping at the configured width (80 by default), links and paging apply.
planner list plan.yaml --ignore-config
planner list tasks plan.yaml --ignore-config --only status=planning
--ignore-config bypasses list presentation and shows complete records within
the requested scope. Explicit fields and filters still apply. Category and
priority vocabularies and task allowlists remain active for validation and label
lookup. Invalid list presentation is bypassed too; other configuration validation
still runs. Combining --config with --ignore-config is an error, in any position.
The option is available only for list, including scoped kinds. Without a list
section or the bypass option, existing compact/full list layouts are unchanged.
Export options
The configuration export section accepts elements for content and layout
for presentation. planner fields config prints the complete nested example.
Column styles never enable content:
export:
elements:
tasks:
number: true
site: true
task_table:
columns:
number: true
site: true
layout:
task_table:
columns:
- attribute: number
alignment: left
- attribute: site
label: Institution
alignment: left
columns can select any supported task field, including formerly fixed task
numbering, independently of task narrative selections. fiscal_funding expands
fiscal-year columns without requiring narrative funding. totals controls the funding totals row. Tables with no effective
columns and their headings are omitted. Layout controls column order, labels,
and left/center/right alignment; fiscal-year columns remain last.
The generated funding_status attribute is false only for tasks with
status: unfunded, and true otherwise, regardless of their fiscal funding
amounts. Exports display Funded or Unfunded. Enable elements.task_table.columns.funding_status to add the column;
elements.tasks.funding_status independently enables narrative output. Packaged
defaults leave both disabled. It is a computed value, not a plan input field.
Completed fiscal table cells are green when task status is selected; their
completion year appears only when elements.tasks.completed is also enabled.
Section order follows the declaration order in export.elements, with the
project title/PowerPoint cover fixed first. elements.task_table is independent
of elements.tasks and controls the Word/PDF summary table. The former
elements.tasks.table location remains accepted for existing configurations.
Word/PDF summary tables reserve space for each column's longest word, including
BNR codes and Unfunded, plus bold headers and cell padding. Multiword text can
wrap between words. If estimated widths cannot fit the page, export warns;
use landscape orientation or fewer columns. Font size and page margins stay fixed.
Cell left/right margins are 2.7 pt per side, or 3 pt for merged activity/parent rows.
Set independent font sizes in points under export.layout:
layout:
font_size: 12
task_table:
font_size: 10
Word/PDF body and table defaults are 12 pt and 10 pt respectively. Half-point
sizes such as 10.5 are supported. The body setting also controls SVG and
PowerPoint text and reflow; omitting it retains their native sizes. Display
titles and header/footer markings retain their existing sizes. Table sizing
uses the chosen table font; the table setting is independent of the body size.
Task exports can use an ordered list with repeated line: instructions:
Within a task line, {field: number, format: short} prints a bare displayed
number such as A.1.1. Omit format or use full to retain Task A.1.1.
This preserves the existing numbering scheme and is separate from id, the
stable identifier in the plan. The same syntax works in configured terminal
task lines; table numbering is unchanged.
export:
elements:
milestones:
tasks:
- line:
- field: number
format: short
- id
- field: label
italic: true
- field: status
bold: false
color: auto
bold: true
- description:
- line: [category, priority]
color: gray
- risk:
type:
level:
mitigation:
deliverables:
task_table:
columns:
number:
funding_status:
Only listed content appears, in instruction order. - id inside a line prints
the task ID; it is shorthand for - field: id. Standalone field instructions
retain their existing rendering. Field styles override line defaults;
bold: false and italic: false disable inherited emphasis. Colors accept named
colors, quoted hex values, auto for semantic coloring, and default for normal
text. Long lines wrap to fit. Structured/list fields retain separate rendering.
The previous mapping with tasks.line or tasks.lines is accepted for
compatibility. Bare tasks: retains the default layout. planner fields config
includes the new syntax as a commented replacement for the default task mapping.
See the export-options reference for supported fields and validation rules.
Add heading: true or heading: false beside a standalone field instruction
to show or hide its label. Standalone labels are enabled by default; this example
keeps the task description prefix and hides the category prefix:
tasks:
- line: [number, label, status]
- description:
heading: true
- category:
heading: false
Put this under export.elements or list.elements. Grouped lines also accept
heading as a line-wide default, overridden by individual field mappings such
as {field: start, heading: true}. For structured standalone fields such as
risk, the switch controls the parent heading and all selected child labels.
Omitting it enables standalone field labels, including Description:;
grouped lines retain their existing defaults. Section/item titles, table headers,
and heading underlining have separate behavior.
Milestones and deliverables accept the same ordered interface:
milestones:
- line: [id, label]
bold: true
- description:
- line: [deadline]
- deliverables:
deliverables:
- line: [id, label, status]
bold: true
- description:
- line: [type, ready, required_by]
- producers:
Put this under export.elements. Relationship lists (deliverables on a
milestone and producers on a deliverable) remain standalone instructions.
Scalar fields, including calculated dates, can share a line. Existing bare
entries and field mappings retain their output. planner fields config includes
commented examples for tasks, milestones, and deliverables.
The retired --include-note, include_note, task_table_columns, and
task_table_attributes controls are rejected in the CLI/general configuration.
Move note selection to elements.tasks.note, column selection to
elements.task_table.columns, and column styles to layout.task_table.columns.
Replace old top-level element lists with mappings of names to booleans.
Project-year budgets use two optional top-level inputs:
fiscal_current: FY27
planned_value: $100K
fiscal_current is a declared two-digit reporting year, independent of today's date and
plan coverage. planned_value requires it and accepts funding amount syntax;
amounts display in dollar-prefixed thousands. Zero is valid. The read-only
actual_value value sums funded task funding for that year across the complete project
(every status except unfunded, complete, and closed), with authoritative multipart parent budgets once,
so it shows funded over- or underspending. potential_value adds unfunded tasks, still excludes complete and closed tasks, and is
always neutral black. Both measure assigned funding, not expenditures. The amount is green below the planned value,
black at it, and red above it, with exact decimal comparison. Without a planned
budget it is neutral black; without a current year it is unavailable.
Use planner list actual_value plan.yaml or planner show plan.yaml potential_value to inspect
them. fiscal_current, planned_value, actual_value, and potential_value are independent export.elements and
list.elements selectors; default exports include populated values before
Execution. List filters do not change the project total. Word import recovers
budget inputs and recomputes Actual Value from recovered funding; hidden allocations
or original parent budgets require review. Author only fiscal_current and
planned_value; the actual_value input key is rejected. planner fields plan and
planner fields config include examples.
Advanced plan authoring
Adding and removing entries
planner add task plan.yaml
planner add milestone plan.yaml --destination milestones.yaml
planner add task plan.yaml --parent BUILD_WING
planner add workitem plan.yaml --owner BUILD_WING
planner remove BUILD_WING plan.yaml
planner remove BUILD_WING plan.yaml --remove-references --write
add TYPE opens an active-configuration template in TUXFAN_PLANNER_EDITOR,
falling back to EDITOR. Supported types are task, activity, milestone,
deliverable, dependency, project-risk, and workitem. Edit the mapping and
exit the editor; planner validates the complete candidate plan before saving.
Invalid additions can be reopened or cancelled, retaining the recovery buffer.
An unchanged template adds nothing. Optional task risk/work-item examples stay
commented out. --parent adds a part to an existing multipart parent;
--owner is required for work-item references.
For a composite plan, a numbered menu offers compatible source collections and
creation of a new included YAML file. Use --destination PATH to choose without
a prompt; it is required for composite additions with noninteractive input/output.
Relative destination paths use the plan's directory. New files need an existing
parent directory and a .yaml/.yml suffix; existing unrelated files cannot be
overwritten. Adding to a single-entry include converts that file into a list.
New-file creation and include updates are validated together and roll back on a
handled write failure. A raw task-list plan only supports adding tasks; use a
mapping plan for other definition types.
remove ID uses the same exact ID, --kind, and --owner rules as edit and
rename. Incoming references block removal and list their owners. Add
--remove-references to clear those references, including task dependency
edges, activity assignments, milestone/deliverable references, and project
dependency risk references. Owner tasks remain in the plan. Normal validation
warnings, such as a required deliverable losing its only producer, still apply.
Removal previews changes and asks for confirmation in a terminal, defaulting to
No. --write applies without prompting; noninteractive/redirected output stays
preview-only otherwise. A parent removal includes its parts; to remove the last
part, remove the parent. References to a multipart parent retain dependencies on
surviving parts when one part is removed. Removing an inherited work item from
one part creates a local override, leaving siblings unchanged. Shared included
owner collections are isolated when necessary to preserve other owners.
Empty included lists stay as []; removing a single-entry include detaches its
directive and retains the orphan file. Neither command deletes source files.
YAML and literal Python collections are supported. Computed Python collections
and affected YAML anchors or merged collection containers must first be made
explicit. As with rename, scope is the loaded plan and its includes; saves use
full-plan validation, concurrency checks, numbered backups for existing files,
per-file atomic writes and handled-failure rollback. Forced termination can
require backup recovery. Default plan and input-directory settings apply.
Editing the configuration
Run planner config edit (alias: planner edit config) to edit the active general configuration, or
planner edit config --config PATH for a specific file. The editor uses
TUXFAN_PLANNER_EDITOR, falling back to EDITOR. Planner opens the complete
file, validates the edited configuration, and saves atomically with a numbered
backup. Invalid edits can be reopened or cancelled; failed buffers are retained.
You can repair an invalid existing configuration. No plan file is required.
Editing one entry
Set an editor command, then select an entry by its exact ID.
EDITOR is used when TUXFAN_PLANNER_EDITOR is unset or empty:
export TUXFAN_PLANNER_EDITOR='vim'
planner edit BUILD_WING plan.yaml
planner edit RELEASE_GATE --kind milestone
Omit the file when TUXFAN_PLANNER_DATA_FILE supplies it. Relative input files
honor TUXFAN_PLANNER_DATA_DIRECTORY. GUI editors must wait for the buffer to
close, for example TUXFAN_PLANNER_EDITOR='code --wait'.
The editor opens a temporary YAML mapping containing the authored entry.
Supported kinds are task, activity, milestone, deliverable, dependency,
project-risk, and workitem. Multipart parts use expanded IDs such as
BUILD_WING_LEFT; inherited fields remain inherited. Use --kind when IDs
overlap, and --owner TASK_ID to select a repeated work-item reference in its
authored task. Elements without IDs cannot be selected. edit keeps IDs fixed;
use rename below to change IDs and update references.
On editor exit, planner validates the replacement within the complete plan.
Invalid edits can be reopened or cancelled. A successful edit updates only the
selected entry in its original source, including included YAML files, creates
a numbered .bak backup, and saves atomically. Changes to any input file while
editing prevent saving. Unchanged buffers create no backup; failed or cancelled
edits retain the buffer at the printed temporary path.
YAML comments and formatting outside the entry remain unchanged. YAML entries containing anchors, aliases, or merge keys must first be made explicit. Python plans support uniquely located literal dictionary entries, edited through YAML; surrounding Python code is preserved, while the replacement dictionary is written as a Python literal. Computed entries are rejected before opening the editor. The command parses editor arguments without running a shell.
Renaming IDs
planner rename BUILD_WING DESIGN_WING plan.yaml
planner rename BUILD_WING DESIGN_WING plan.yaml --write
planner rename RELEASE_GATE FINAL_GATE --kind milestone --write
The default is a validated preview showing the source values and files that
would change, then prompts Apply this rename? [y/N]: in an interactive
terminal. Only y or yes applies it; Enter declines. --write applies it
with numbered backups without prompting. Redirected or noninteractive
input/output remains preview-only without --write. Default files,
configured input directories, --kind, and work-item --owner selection follow
the same rules as edit.
Only semantic references are rewritten: task dependencies, activity links, milestone/deliverable references, and project dependency risk references. Labels, descriptions, comments, and other prose stay unchanged. Work-item renames change the selected owner's authored reference, without contacting the server or changing other owners' entries.
A parent task rename updates its expanded part IDs, including parts authored
with an explicit parent prefix. A part rename accepts either a local new ID
(C) or its expanded form (PARENT_C), preserves its authored local/prefixed
style, and updates sibling and external dependencies. Collisions and dependency
alias changes that would redirect existing relationships are rejected.
Scope is the loaded plan and its recursive includes. Other independent plans and configuration vocabulary IDs are outside that scope. YAML scalar edits preserve surrounding text and quotes; affected anchors/aliases/merge values or computed Python references must first be made explicit. Literal Python IDs and references are supported without rewriting surrounding code.
All replacements are prepared and the complete plan is validated before saving. Sources are checked for concurrent changes. Each changed file is saved atomically with a backup; a handled failure rolls back previously written files. Rollback never overwrites a subsequent concurrent change: the command instead reports the files requiring manual recovery and the retained backups. A forced process termination can also require recovery from these backups.
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:
tasks:
- defaults:
site: Example Works
bnr: EXAMPLE-001
type: labor
- id: MAINTENANCE
category: development
priority: capability
label: Tool maintenance
description: Maintain the planning tool.
status: ongoing
funding: {fy27: 50K}
Default 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.
priority may also be set in defaults; a task/part can replace it or clear it with null/empty text.
Without defaults, site, bnr, type, and priority 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 is unassigned; 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 activity, 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:
project: FY27 Plan
summary: !include prose/summary.yaml
milestones: !include milestones.yaml
execution:
activities:
- !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_DATA_FILE 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 = {
"portfolios": "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": {
"description": "Overall execution context for the plan.",
"activities": [
{
"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"],
"activity": "deliverable_a",
"description": "Produce the first architecture draft.",
"start": "M1Q3FY26",
"expected": 2,
"milestones": ["Design"],
"priority": "capability",
"status": "complete",
"dependencies": [],
"risk": [
{
"type": "technical",
"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
task_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:
elements:
project: true
tasks:
label: true
category: true
description: true
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 task-priority vocabulary entries 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.
Tasks optionally specify one priority: capability ID from task_priorities.
Omitted/null/empty text means unassigned. IDs are trimmed and matched exactly;
lists, mappings, and unknown IDs are errors. Defaults and parent/part inheritance
apply; an explicit ID replaces the inherited value and null/empty text clears it.
Every task requires one configured category, which cannot be cleared.
Use planner list tasks FILE priority and --only priority=capability.
show tasks.priority, avail priority, and field templates retain canonical IDs.
Terminal task displays (including projections, detail, schedule, and configured
lines) show configured category and priority labels followed by canonical IDs
in brackets, such as Essential delivery [DELIVER]. The bracketed suffix is
light cyan when colors are enabled. Export task narratives use configured labels.
Both vocabularies accept optional table_entry values for export tables:
- id: INVEST
label: Research and investment
table_entry: Cat 3
description: Explore future capabilities.
Table cells use table_entry when supplied, otherwise the canonical ID unchanged.
For priorities, id: ASC_1 with table_entry: ASC 1 explicitly selects that
table spelling. Automatic CAT/ASC conversions are removed. Table labels must be
non-empty strings, unique within their vocabulary, and cannot match another
entry's canonical ID. avail category and avail priority show explicit table
labels; plans, filters, show, and generated task/plan templates use IDs.
Optional sites and bnrs sections restrict task site and bnr. Entries need only an id, for example:
sites:
- id: Workshop One
- id: Workshop Two
bnrs:
- id: EXAMPLE-001
Each task may select one scalar ID per field, and different tasks may select
different IDs. Values are trimmed and matched case-sensitively after defaults
and multipart inheritance. Missing/null/empty task values remain allowed;
lists and mappings are rejected. Omit a configuration section to leave the
field unrestricted; an empty list permits only empty task values. Exports show
the IDs in the selected optional attribute columns. planner avail site,
planner avail bnr, and planner avail type show active IDs. Generated task
and plan templates use those choices. Task type accepts one built-in ID or a
list of IDs: labor, contract, equipment, services, nonlabor. Configuration types
is no longer accepted; remove that section from existing configurations. See
General Configuration
for the full configuration reference.
Migration: add a non-empty label to every vocabulary entry in existing configurations. Labels are display names; plans continue to reference IDs. Use a complete configuration containing config_version, the two vocabulary sections,
and export settings beneath export:. Select it with --config PATH.
Migrate older YAML plans and configuration explicitly:
planner migrate-priorities FY27 --config configs/asc.yaml
planner migrate-priorities FY27 --config configs/asc.yaml --write
The first command previews affected files. The second saves numbered backups,
renames the vocabulary to task_priorities, moves project assignments into task
list defaults, converts singleton task lists to scalar priority, and updates
presentation selections/table columns. Multiple IDs and legacy urgency values
require an explicit choice; the migration stops before writing any files. Includes and
comments are preserved. Conflicting assignments stop before writing. Review
unrelated schema errors separately. For Python input, move priorities into task
records manually. Word import recovers per-task priorities; missing assignments
stay empty, and legacy document-wide assignments produce a migration notice.
Environment variables
TUXFAN_PLANNER_EDITOR selects the editor executable and arguments for
planner add and planner edit. If unset or empty, EDITOR supplies the command. GUI editors
must wait for editing to finish; for example, use code --wait.
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_DATA_FILE, 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_DATA_FILE=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_DATA_FILE=tasks.yaml
planner validate
Relative input filenames use the configured directory first, including a relative
TUXFAN_PLANNER_DATA_FILE. 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_DATA_FILE 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_DATA_FILE:
planner format tasks.yaml
planner format tasks.py
planner format
YAML (.yaml/.yml) uses planner's built-in style and needs no external
tool: mappings indent two spaces, sequences sit two spaces in, long plain or
quoted prose becomes a folded > block, multi-line text and text with lists
becomes a literal | block, and runs of blank lines collapse to one. Authored
block scalars, comments, tags, anchors and explicit nulls are kept, and
formatting is idempotent.
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.
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_DATA_FILE
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 the configured max_width (80 by default),
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 the configured max_width (80 by default).
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, and task site/type/tags. Schema keys, IDs/references, fiscal periods, status/priority/risk-level/risk-type 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, activity definitions, 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
Pip installations include the complete HTML guide for offline reading:
planner docs
planner docs --path
planner docs opens the installed guide in your default browser. --path
prints the location of index.html without opening a browser. The guide includes
local pages, search, styles and assets. These commands need no plan or
configuration file, and Sphinx is not a runtime requirement.
Editable source checkouts use an existing HTML build in docs/_build/html or
.cmake-build/docs/html. See the developer guide for build
commands. The [docs] extra installs the tools for building from source; ordinary
wheel installations already contain the built guide.
The repository's Documentation workflow in .github/workflows/docs.yml also
publishes the guide to gh-pages. Website hosting is optional for installed users.
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.
Task field headings in terminal list output use consistent bold emphasis; values retain their normal text and semantic colors. Risks repeat an unnumbered Risk heading for each entry, including configured and scoped list views.
Terminal Risk headers use severity colors: green for low, yellow for medium, orange for high, and red for extreme. Headers remain bold and unnumbered; risk values keep normal text and their existing colors. Color controls still apply.
portfolios, managers, and pocs share ordered-list formatting. A single
value prints beside a bold heading with a bold value; multiple values print
beneath a bold heading as normal, indented bullets. Empty collections are
omitted from document exports. Explicit terminal queries still show None.
Values can use YAML sequences, scalar text, or Markdown lists with -, *,
or + in literal (|) or folded (>) blocks. Commas and slashes remain text:
portfolios:
- Flight Research
- Aircraft Systems
managers: Program Lead
pocs: >
- Engineering Lead
- Research Lead
In export and list configuration, layout.context_colors: false disables
automatic status, risk, and budget colors (including table completion
shading). Explicit field colors and fixed heading/link styles remain available;
terminal --color and NO_COLOR still control ANSI output. Set metadata styles
independently of content selection:
export:
layout:
context_colors: true
metadata:
portfolios:
heading: true
heading_bold: true
bold: false
The same layout settings are supported under list. All three metadata fields
accept these boolean controls. Omit bold to use the single/multiple-value rule.
ASC profiles preserve their required metadata labels. Activity headings include
the letter and label, such as Activity A: Aircraft Systems; task numbering
remains unchanged. Automatic fiscal funding summaries use Funding Totals in
Word, SVG, and PowerPoint when fiscal metadata and task funding are selected.
Execution descriptions support the same heading control in export and list configuration. Use ordered instructions when customizing the heading:
export:
elements:
execution:
- description:
heading: false
- activities:
Omit heading or set it to true to show the description heading. Keep the
activities entry to include activity definitions. The standard's top-level
Execution heading is independent. The same syntax works under list.elements;
existing mapping selections remain supported.
For a concise mapping, use description: {heading: false} under execution,
with a sibling activities: entry if activity definitions should be included.
This form also works under both export and list elements.
Export spacing can be customized per element while inheriting the document's
default. Both selection mappings and ordered instructions support normal and
tight:
export:
layout:
spacing: normal
elements:
tasks:
- spacing: tight
- line: [number, label, status]
- description:
milestones:
spacing: tight
deliverables:
spacing: normal
A spacing-only entry keeps the element's default content. Explicit field
selections retain their usual omission rules. Execution and its description and
activities, summary/background, resourcing prose, portfolios, managers, POCs and
contacts also support overrides. Omitted spacing inherits the nearest parent
or document setting. Task-table cells and terminal list spacing remain
independent. planner fields config includes more examples.
Generated task and activity heading numbers use a colon before the label,
including multipart children: Task A.1.1: Child label. Custom
line: [number, label, status] instructions and short number formats use the same
rule. Number-only table cells retain the number alone, and Word import still
accepts older period-separated headings.
Use planner list tasks plan.yaml --parents to collapse multipart tasks to
one parent summary while keeping standalone tasks. planner list plan.yaml --parents also works for a full planning document. Filters apply to original
parts first; summaries show only matching parts and mark partial selections
(e.g. [partial selection: 1/3 parts]). Mixed values are indicated, and
funding totals and readiness retain their source-task rules. The flag also
works with positional fields, configured lists and --ignore-config. It is
independent of export.layout.multipart and applies only to task list views.
Task funding in list output uses dollar-prefixed values such as $50K, colored
green when terminal colors are enabled. Field-selected and configured lists use
the same convention; closed and unfunded tasks retain their muted colors.
Activity funding summaries also display dollar-prefixed green amounts, including activities nested within execution and plan views.
Terminal color overrides
Set optional terminal.colors entries in your general configuration:
terminal:
colors:
description: "#FFFF99"
id: "#800080"
status:
planning: "#FF8700"
Run planner avail colors for all attributes, default/effective hex values, and
colored hex values. Use --color always to force colors or --color never for
plain output. Quote hex values; default selects the terminal's normal foreground.
Omitted entries retain existing colors. Standard ANSI defaults depend on your
terminal theme; displayed hex defaults are conventional equivalents.
Explicit configured field colors take precedence. Export colors are unchanged.
See configuration details.
Print the complete effective palette as config-ready YAML with
planner fields colors, optionally using --config PATH. Paste the emitted
terminal.colors mapping into your config. Unset colors use conventional hex
equivalents of the ANSI defaults; supplied hex values use fixed RGB colors.
Maximum text width
Set a top-level width in the general configuration:
max_width: 100
The default is 80; values must be integers of at least 40. The setting controls terminal wrapping/rules, help, discovery, totals, spellcheck suggestions, and source formatting widths, including generated YAML and Python formatting. Authored literal YAML blocks and values remain protected. Document and slide layout dimensions keep their existing settings. See configuration details.
Staff funding
Existing annual funding remains supported. Alternatively, use typed funding:
funding:
contract:
FY27: 500K
nonlabor:
FY27: 100K
labor:
FY27:
- id: STAFF_A
percent: 10
Set rates_file: rates.yaml in configuration, or override it with
TUXFAN_PLANNER_RATES_FILE. Config paths are relative to the config file;
environment paths are relative to the working directory. The rates file is:
rates:
- id: STANDARD
amount: $300K
staff:
- id: STAFF_A
rate: STANDARD
fte: 40%
Rates are annual full-time costs. A task's
percentage is a share of the staff member's available FTE: 10% of 40% at $300K
is $12K/year. Omitted fte means 100%. Both percentages accept 40 or 40%.
The default labor_costing: annual keeps staff funding independent of task
duration. Opt into labor_costing: duration to cost only scheduled months; explicit start/duration or start/end is required,
and ongoing tasks cannot use staff allocations in this mode. Monetary amounts
are never prorated. Staff costs round to cents before totaling.
Rate amounts and staff rate assignments also accept effective fiscal-month histories:
rates:
- id: STANDARD
amount:
M1Q1FY27: $250K # October 2026
M1Q2FY27: $260K # January 2027
- id: SENIOR
amount: $300K
staff:
- id: STAFF_A
rate:
M1Q1FY27: STANDARD
M1Q3FY27: SENIOR # Promotion in April 2027
fte:
default: 40%
FY27: 50%
Each effective value carries forward until replaced. A missing earlier rate
or assignment is an error. FTE accepts whole-year percentages or
monthly mappings using M1Q1FY27 through M3Q4FY27; omitted months in an
explicit monthly year default to 0%, including when an FTE default is set.
An empty year mapping such as FY27: {} means zero availability for that year. Without an FTE default, a missing year is an error. Monthly costs
use that month's availability, assignment, and annual rate, then round once
per staff/code/year. Combined code FTE above 100% is an error; overlapping task
demand above availability produces a warning.
Complete and closed tasks remain visible for progress context but show excluded funding. They do not contribute to totals, actual/potential values, cost or staff demand. Complete tasks skip funding validation, including missing rates and obsolete funding references; closed tasks retain it. A shared parent budget counts once while any current part remains. Coverage cannot use a budget whose owning tasks are all complete or closed.
Inspect staff subscription by code with:
planner list staff plan.yaml --year FY27
planner list staff plan.yaml --year FY27 --monthly --details
planner list staff plan.yaml --month M1Q1FY27 --staff STAFF_A
planner list staff plan.yaml --year FY27 --include-unfunded --format csv > staff.csv
Staff sections and code/period separators follow normal list output. Configure
its numeric colors with terminal.colors.subscription (available, used,
remaining, ratio_low, ratio_critical, ratio, proposed,
overcommitted, unknown); identifiers and
headings use the shared list palette. CSV stays plain.
Allocation includes its labor cost in parentheses for the displayed months,
using effective rates and promotions. The report puts each metric on its own line: Allocation, Subscribed,
and Available. Percentages measure full-time effort. Summary Available
is unused capacity actually configured in the rates file, with an uncoded
fallback treated as an alternative pool, not additional capacity. Annual
figures are monthly averages, with overcommitted periods retained.
Staff labels from the rates catalog appear with their IDs and determine sort
order; unlabeled staff use their IDs. Unused catalog staff/codes remain visible. Subscribed means assigned effort
in this plan. --include-unfunded adds separate proposed demand;
complete/closed work is excluded and parent/covered budgets are not counted
twice. Repeat --staff or --code to filter rows; person totals retain every
code. CSV always has one staff/code/month row. See the
funding reference for formulas and incomplete-input behavior.
planner list tasks plan.yaml funding displays the breakdown. Existing exports
use resolved annual totals; Word imports recover coarse funding from totals.
See Funding and Staff Costs for validation, multipart and
merge/split behavior. See rates.yaml for scalar values
and rates-timing.yaml for histories and monthly FTE.
Rate entries may also include optional descriptive metadata:
rates:
- id: STANDARD
amount: $300K
category: Research Staff
band: "$50,000 - $69,999"
staff: []
category and band retain source-table information as non-empty text. Salary
bands remain descriptive; amount supplies the full-time annual cost.
Staff entries can group code allocations under one person:
staff:
- id: STAFF_A
rate: STANDARD
codes:
- id: DEMO_CORE_0000
fte: 40%
- id: DEMO_SUPP_0000
fte: 20%
Each code inherits the person's rate or supplies its own rate override.
Task labor entries still use id, code, and percent to select an allocation.
Existing flat coded entries and uncoded entries remain supported. See
Funding and Staff Costs for selection and validation rules.
Task cost in list output
planner list tasks plan.yaml cost
cost shows amounts per fiscal year, grouped by funding type. Staff and covered
allocations put staff IDs, source/share attribution, and codes on separate
indented lines beneath each fiscal-year amount. Matching years
collapse to one amount per year with differing years shown as exceptions; years
are never summed together. Coverage without a share shows Share unspecified.
Amounts round to whole K with halves up ($130.8572K displays as $131K),
using exact values for grouping and retaining calculation precision. Standard
terminal colors apply, including closed/unfunded task colors. Coarse funding
appears as Unclassified; missing inputs show Incomplete while known annual
components remain visible. Financial ownership and totals are unchanged.
To include it in an existing configured list:
list:
elements:
tasks:
id: true
label: true
cost: true
It is a computed list field; do not add cost to a task's authored data.
Validation and exports remain strict. See Funding and Staff Costs.
Activities can supply an optional code for labor funding. Task code overrides
that default, and individual labor entries can override it again. Existing
activities without codes remain valid. See funding examples.
Typed funding supports fiscal_range as an annual default across the plan's
fiscal years, for example contract: {fiscal_range: 100K}. Labor can put its
staff allocation list under fiscal_range. Explicit fiscal-year entries override
that default for the matching type/year. See funding examples.
Funding can be included in another task's budget with covered_by. Add optional
share: 25% to attribute part of the source allocation without counting its
money twice. Whole types and individual staff are supported per fiscal year or
fiscal_range. See the coverage example
and funding reference.
Use range within typed funding to repeat an entry over the task's inclusive
start/end or start/expected span, for example contract: {range: 100K}.
Explicit fiscal years override it. fiscal_range continues to use plan years;
choose one default per type. Annual/duration costing rules remain in effect,
and ongoing tasks use explicit years or fiscal_range. See the
funding reference for staff, coverage and incomplete-date cases.
Rate-file allocation codes use XXXX_XXXX_XXXX: three groups of four uppercase
ASCII letters or digits, separated by underscores (for example DEMO_CORE_0000).
This applies to flat code and grouped codes[].id. Use underscores rather than
dots; quote entirely numeric codes. Staff entries can still omit codes.
A funded multipart child's labor entry may use {id: STAFF_A, share: 20%} to
attribute part of that staff member's parent allocation without repeating
covered_by. Whole types also support a share-only annual entry. Explicit
child-to-parent coverage works as well; parent totals still count once and child
shares combine with external claims under the 100% limit.
Use share: remainder to attribute the percentage left after other numeric
shares for that source/type/year/staff/code allocation. A single child explicitly
referencing its parent without a share receives an implicit remainder. Multiple
overlapping remainder recipients require clarification through numeric shares.
Children without allocations automatically divide remaining parent funding;
external coverage without shares remains unspecified.
Whole-type remainders cannot mix with staff-specific claims; individual staff
remainders can deduct whole-type numeric shares. Resolution uses the complete
plan before filtering, and output labels inferred remainders. Financial totals
remain source-owned. See the funding reference.
Multipart children can omit funding entirely. After numeric shares and any
authored remainder recipient, planner divides remaining parent funding equally
among children without an allocation for each type/year/staff/code. For a $100K
parent allocation with one child claiming 20%, two unallocated children each get
$40K. Explicit zero counts as an allocation. Inference uses the full sibling set
before filtering, displays implicit remainder, and preserves source files,
schedules, and parent-owned financial totals. See the
funding examples.
Customize cost share/remainder explanations with terminal.colors.funding_share
in config.yaml. Its default is canary "#FFFF99", matching the description
default; staff/source IDs and codes retain their ID color.
All funding amounts in terminal and document output round to whole thousands with halves up, including annual totals, subtotals, project budgets, staff details and covered amounts. Calculations, comparisons and source/model values retain precision; totals round only after exact aggregation. Two $0.6K allocations each display as $1K, and their $1.2K total also displays as $1K.
Collapsed parent tasks list all distinct child categories instead of Mixed.
List output retains each category's label and ID; export narratives use labels.
Table cells put each category code on its own line using the column alignment.
Categories are deduplicated in authored part order; source task categories remain
single IDs. See export options.
Metadata
Release files for tuxfan-planner 0.2.83
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tuxfan_planner-0.2.83.tar.gz | 1.3 MB | Without provenance | Details for tuxfan_planner-0.2.83.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tuxfan_planner-0.2.83-py3-none-any.whl | Python 3 | none | any | Details for tuxfan_planner-0.2.83-py3-none-any.whl |
Total release size: 2.1 MB
Release files / tuxfan_planner-0.2.83.tar.gz
| Download URL | tuxfan_planner-0.2.83.tar.gz |
|---|---|
| Size | 1.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b094c9020f604cef11b89ee73d9dd4b02f7d228cd9e106ac89d5f9196fa120e6
|
|
BLAKE2b-256 checksum How to use checksums |
133cb367944b3d8cb60e6a7930fa8514581f43c09e9cd1903720c89f286720b9
|
| 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.83-py3-none-any.whl
| Download URL | tuxfan_planner-0.2.83-py3-none-any.whl |
|---|---|
| Size | 803.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
023dc911ad3b96e298e01121000942ad643bdb8dc76162ea1ecad8c404840ba1
|
|
BLAKE2b-256 checksum How to use checksums |
f68f39a91b3b0c53e93baf915e8a208c50ea4d46b60ddd3a7c5434ec46ed0e37
|
| 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.83
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.