Plan JSON Schema

Plan JSON Schema

Plans are stored as plain JSON files in .clido/plans/<id>.json within the working directory.

Top-level structure

{
  "meta": { ... },
  "tasks": [ ... ]
}

meta object

Field	Type	Description
id	string	Unique plan ID, e.g. plan-a1b2c3d4. Generated automatically.
goal	string	The original user prompt that triggered this plan.
created_at	string	ISO 8601 timestamp, e.g. 2026-03-22T10:00:00Z.

tasks array

Each element is a task node:

Field	Type	Default	Description
id	string	—	Unique task ID within this plan (e.g. t1, t2).
description	string	—	Human-readable task description.
depends_on	array of string	[]	IDs of tasks that must complete before this one starts.
complexity	string	"low"	Estimated complexity: "low", "medium", or "high".
skip	boolean	false	If true, execution skips this task.
notes	string	""	Optional free-text notes for the agent.
status	string	"pending"	Execution status (see below).
tools	array of string | null	null	Optional hint: tool names expected to be used for this task.

status values

Value	Meaning
pending	Not yet started.
running	Currently executing.
done	Completed successfully.
failed	Execution failed.
skipped	Skipped (either skip: true or skipped due to failed dependency).

complexity values

Value	Meaning
low	Simple, single-step task (e.g. read a file, edit one line).
medium	Multi-step task affecting a few files.
high	Complex task requiring significant reasoning or many file changes.

Full example

{
  "meta": {
    "id": "plan-a1b2c3d4",
    "goal": "Refactor auth module to use JWT",
    "created_at": "2026-03-22T10:00:00Z"
  },
  "tasks": [
    {
      "id": "t1",
      "description": "Read existing auth module and identify patterns",
      "depends_on": [],
      "complexity": "low",
      "skip": false,
      "notes": "",
      "status": "pending",
      "tools": ["Read", "Glob", "Grep"]
    },
    {
      "id": "t2",
      "description": "Add jwt crate to Cargo.toml",
      "depends_on": ["t1"],
      "complexity": "low",
      "skip": false,
      "notes": "",
      "status": "pending",
      "tools": ["Edit"]
    },
    {
      "id": "t3",
      "description": "Implement JWT token generation and validation",
      "depends_on": ["t2"],
      "complexity": "high",
      "skip": false,
      "notes": "Use HS256, expiry = 24h",
      "status": "pending",
      "tools": ["Read", "Edit", "Write"]
    }
  ]
}

Notes

• The depends_on graph must be a DAG (directed acyclic graph). Plans with cycles are rejected.
• When clido plan run <id> executes a saved plan, tasks with status: "done" or status: "skipped" are skipped automatically.
• Plans are generated by the LLM in a flat format ({goal, tasks}) and wrapped with a meta object on first save. Both formats are accepted by clido-planner’s parser.
• Files are stored at <workdir>/.clido/plans/<id>.json.

See also

• Plan Mode guide — interactive editor, flags, and slash commands
• Key Bindings — plan editor keyboard shortcuts
• Flags — --plan, --plan-dry-run, --plan-no-edit