Core concepts

Plan

A Plan is one UTF-8 .plan document with a stable ID, DSL version, title, and ordered work items. The file is author intent and belongs in Git.

Work item

A work item is either a task, a milestone, or an include site. Tasks may be leaf tasks with dates or summary tasks with nested items. Milestones are zero-duration events. Dependencies use explicit @id references.

Entry

An entry is a Plan selected for independent validation and display. A project manifest can declare multiple ordered entries. Each entry receives its own diagnostics, generation, and most recent valid result.

Include

An include mounts another complete .plan file beneath an entry. Include paths are explicit, relative, and constrained to the project source root. PlanQ never scans a directory to guess includes or entries.

Manifest

plan.manifest.json is the versioned, ordered entry list for a project. Running planq project validate checks the manifest and every declared entry.

Project resources

resources.plan is the human-maintained local resource source. An optional resources.lock.json is a generated, reviewed snapshot of online resources. All entries in one project share their strict union. Private connection state stays under .plan/ and is not committed.

IR

The intermediate representation (IR) is a normalized, versioned, deterministic result produced after parsing and validation. It contains explicit defaults and resolved references for read-only consumers. Do not edit or commit IR as a replacement for .plan source.

Diagnostic

A diagnostic has a stable namespaced code, severity, source range, reason, and usually a fix direction. Errors block a valid IR; warnings preserve validity. Consumers should use the structured fields instead of parsing display text.

Skill

The plan-gantt Agent Skill is a project-scoped authoring client installed at .agents/skills/plan-gantt/. It uses the same CLI parser, validation, and formatter as a human author. It cannot bypass validation or mark a plan executable. Codex discovers this canonical path directly; Claude Code and TRAE use project-local forwarders that explicitly load the same canonical SKILL.md. Other agents receive no native-discovery guarantee and must use the explicit handoff path.

Source and generated-result boundary

Only an explicit planq format command writes canonical .plan source. Validation, normalization, local preview, editor diagnostics, and the hosted workbench are read-only. GitHub sync reads a commit and never writes a plan back to the repository.