Effort input format¶

Agents write a JSON file; scripts/validate-effort.mjs checks Fibonacci constraints; scripts/summarize-effort.mjs reads it and prints totals. The LLM assigns Fibonacci points and status per item — the scripts do all arithmetic.

Status enums follow plan-status.yaml (JSON column). Scale definitions: effort-scales.yaml (ai_fibonacci).

Top-level shape¶

{
  "plan": "auth-migration",
  "steps": [ ... ],
  "groups": [ ... ]
}

Field	Required	Purpose
`plan`	yes	Short plan identifier (used in output).
`steps`	yes*	Leaf work items with granular progress.
`groups`	no	Phase or plan rollups sized independently of step sums.

* Provide at least one of steps or groups. Most plans use both.

Step object¶

{
  "id": "A.5",
  "label": "Remove Auth0",
  "effort": 5,
  "status": "in_progress",
  "effort_remaining": 1,
  "group": "phase-a",
  "notes": "Package removed; naming/test cleanup remains"
}

Field	Required	Values
`id`	yes	Stable step id (e.g. `A.5`, `B.1`).
`label`	yes	Human-readable step title.
`effort`	yes	Fibonacci: `1`, `2`, `3`, `5`, `8`, or `13`.
`status`	yes	`done`, `in_progress`, `not_started`, or `blocked`.
`effort_remaining`	no	Fibonacci, ≤ `effort`. Only for `in_progress`. Defaults to full `effort`.
`group`	no	Links step to a `groups[].id` for reporting.
`notes`	no	Free text; ignored by the script.

Group object (rollup)¶

{
  "id": "phase-a",
  "label": "Phase A — Schema and parity",
  "effort": 8,
  "status": "in_progress",
  "notes": "Exit criteria not yet met on staging"
}

Rollup effort is sized by judgement (see scale.md), not computed from child steps.

Status → completed effort (deterministic)¶

Status	Completed	Remaining
`done`	full `effort`	`0`
`not_started`	`0`	full `effort`
`blocked`	`0`	full `effort`
`in_progress`	`effort - effort_remaining`	`effort_remaining` (default: full `effort`)