Skip to content

Plan DSL reference ​

PlanQ DSL v1 is a UTF-8, EDN-shaped data language with one root map. It is not standard EDN and is never evaluated.

Syntax ​

FormPurpose
{ ... }Map for a Plan, work item, assignment, or resource object
[ ... ]Ordered vector
:fieldField name
plain-valueUnquoted scalar when unambiguous
"quoted value"Escaped single-line scalar
Backtick blockMultiline :description or availability :reason
// commentLine comment; omitted from IR
@item-idExplicit work-item or person reference

Commas outside tokens are optional separators. Commas inside bare text are literal content, including trailing commas, and canonical formatting preserves them. Parenthesized expressions, sets, reader macros, tagged literals, and interpolation are unsupported.

IDs, names, and dates ​

IDs match [a-z][a-z0-9]*(?:-[a-z0-9]+)* and are unique in their namespace. Plan, task, and milestone IDs are global within an entry include closure. Person keys use a separate project-resource namespace.

Dates are absolute ISO calendar dates in YYYY-MM-DD form. PlanQ never stores relative expressions such as today or +3d. An optional root :now YYYY-MM-DD stores a fixed, versioned planning baseline. It is not the runtime clock or task progress, and validation or normalization does not use it to generate dates or consume effort.

Names are non-empty single-line values. Internal spaces do not require quotes. Quote values containing structural delimiters, escapes, //, leading/trailing whitespace, or a whitespace-prefixed field sequence such as :start. Numeric names and roles (for example "123") keep their quotes.

Bare multiword text ​

:title, :task, :milestone, person :name/:role, :description, and availability :reason accept bare multiword text. Every bare value, including a single word, ends at a line break, }, ], //, or horizontal whitespace followed by : and a field-shaped token. Unknown or incomplete ASCII field spellings are not swallowed. Ordinary colons in ratio 1:2 or Migration: verify replicas remain content. Use quotes for "Discuss :start fields".

plan
{:id a :task Database Migration}
{:id b :task "Database Migration" :state done}

Bare text cannot be followed by another field or a new container on the same line: this produces syntax/text-field-line-final. Move the later content to the next line or quote the text. Earlier fields and fields after quoted values remain allowed; formatting always produces block layout. Matching consecutive closing delimiters are allowed. Trailing spaces/tabs are trivia; internal tabs and newlines require quotes or, for multiline descriptions/reasons, backticks.

API//SDK means the value API followed by the comment SDK, not a literal name. Use "API//SDK" to preserve the full text. /, @, #, parentheses, and ordinary colons are literal text, never executable reader forms. Values starting with a comma or colon must be quoted. :task :state done is a syntax error, not a task named :state done; use :task ":state done" for that literal name.

This is a source-breaking evolution within DSL v1; IR and Schema versions do not change. Before upgrading, format old compact bare-text inputs with a compatible older PlanQ or add line breaks/quotes manually. The new formatter and editor format-on-save do not repair rejected layouts. Keep CLI, editor tooling, and CI on a supporting version; the release notes identify the first supported release. An identical dslVersion does not guarantee source compatibility across releases.

Plan and work-item fields ​

NodeRequiredOptional
Plan rootnone:id, :version, :title, :description, :now, :items
Leaf task:task:id, :description, :start, :end, :effort, :deadline, :state, :after, :to
Summary task:task, :items:id, :description, :start, :end, :deadline, :after, :to
Milestone:milestone:id, :description, :date, :state, :after
Include:include:after, :deadline
Assignment map:person, :loadnone

The current DSL version is 1.0. Missing root :id, :version, and :title may be derived from a valid source path and are materialized by formatting. Unknown and duplicate fields are errors.

Scheduling rules ​

  • A leaf task supplies both :start and :end, or neither.
  • An unscheduled leaf may declare total work as :effort <N>pd, where N is positive with at most four decimal places and pd means person-day.
  • :effort and explicit :start/:end are mutually exclusive. Summary tasks, milestones, and other nodes cannot declare effort.
  • wd, d, h, min, zero, negative values, and more than four decimal places are unsupported.
  • Both dates are inclusive; equal dates represent one day.
  • :deadline is an inclusive hard deadline.
  • A milestone is a zero-duration event with optional :date.
  • Summary dates roll up from terminal descendants.
  • :after is an ordered vector of explicit @id finish-to-start dependencies.
  • A successor task starts after a predecessor finishes; a successor milestone may share the predecessor's finish date.

Effort does not make a task scheduled and never implies start or end dates. PlanQ validates constraints but does not automatically schedule work.

Includes ​

An include path is relative to the including file, uses /, ends in lowercase .plan, and remains inside the source root. The entry closure is limited to:

LimitValue
Include depth32
Files per entry256
Bytes per file2 MiB
Bytes per closure32 MiB

Included files may reference their own descendants, but cannot reference an includer, a sibling branch, or an entity outside the closure.

Resources ​

Ordinary .plan files cannot declare calendars or people. Those belong in project-root resources.plan, whose closed field set is:

NodeRequiredOptional
Resource document:version:calendar, :people
Calendarnone:workdays, :holidays
Person:name:id, :role, :leave, :overtime
Leave range:start, :endnone
Overtime map:date:capacity

Assignments reference a stable @person-key. Multiple assignments may use {:person @alice :load 0.5}. Each load and capacity is greater than zero and at most 1.0.

Effort is total person-days. Assignment load is that task's fixed daily demand on a person, while person capacity is the total daily supply shared by all tasks. A 3pd task with one assignee at load 0.5 would require six executable days when a future scheduler is used. Leave, overtime, work schedules, load, and capacity never rewrite source effort. PlanQ currently stores these constraints without calculating the span.

Formatting and versions ​

planq format operates on source syntax, not generated IR. It uses two-space indentation, stable field order, LF line endings, minimal safe quoting, and a single final newline. Reformatting canonical input is byte-idempotent.

DSL, IR, diagnostics, CLI envelope, and Bridge protocol versions evolve independently. Consumers must read each explicit version rather than infer one from another.

See Authoring Plans and Project Files.

PlanQ documentation