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.

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.plan

Run 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.