Authoring plans
PlanQ uses a closed, EDN-shaped data language. It is data, not executable Clojure. If you use an unknown field or unsupported syntax, the CLI will point it out.
Text values and line breaks
Write text directly, for example :task Database Migration or :description Migration: verify replicas. Bare text must be the last declaration on its line. If syntax/text-field-line-final appears, move the following field to the next line or quote the text. Quoted compact maps are still accepted.
Formatting removes unnecessary quotes but preserves "123" names, "API//SDK", and "Discuss :start fields". Bare // starts a comment. Format-on-save does not repair invalid layouts: migrate old compact bare inputs with a compatible older formatter or add line breaks before upgrading. Use a supporting PlanQ version consistently in your editor and CI; see the release notes for the minimum version and the DSL reference.
Minimal plan
{
:id release
:version 1.0
:title "Release plan"
:items []
}planq init release.plan --id release --name "Release plan" creates this shape. planq format release.plan materializes omitted IDs and applies the canonical field order.
Tasks and milestones
{
:id release
:version 1.0
:title "Release plan"
:items [
{
:id implementation
:task Implementation
:start 2026-10-01
:end 2026-10-05
}
{
:id verification
:task Verification
:start 2026-10-06
:end 2026-10-07
:after [@implementation]
}
{
:id ready
:milestone "Release ready"
:date 2026-10-07
:after [@verification]
}
]
}Dates are absolute ISO dates (YYYY-MM-DD) and include both endpoints. A leaf task must provide both :start and :end, or neither. PlanQ does not store relative expressions such as today or +3d.
Dependencies
:after is an ordered vector of explicit @id references. It represents a finish-to-start constraint. A successor task must start after its predecessor ends; a milestone may occur on the predecessor's end date.
PlanQ checks for missing, duplicate, self-referencing, cyclic, and date-conflicting dependencies. It does not automatically reschedule work in the current release.
Summary tasks
A task containing :items is a summary task. Its visible date range is rolled up from scheduled terminal descendants. Summary :start, :end, and :to fields do not constrain children.
Comments and descriptions
Use // for line comments. Single-line descriptions can be quoted. A backtick-delimited block is available only for :description. Comments remain in source but do not enter IR.
Validate before committing
planq validate release.plan
planq format --check release.planRun planq format release.plan when you want to write the formatted source back to the file. Just review the Git diff as you would with any code change.
See the complete Plan DSL Reference.