API Reference¶

This section contains the complete API documentation for plan-view, generated from source code docstrings.

Module Overview¶

plan_view¶

The main package for plan-view.

pv-tool: Pretty print plan.json for AI agent task tracking.

plan_view.cli¶

Command-line interface module.

CLI for viewing and editing plan.json files.

plan_view.cli.bold(text)[source]¶

Apply bold ANSI formatting to text.

Parameters:: text (str)
Return type:: str

plan_view.cli.dim(text)[source]¶

Apply dim ANSI formatting to text.

Parameters:: text (str)
Return type:: str

plan_view.cli.green(text)[source]¶

Apply green ANSI color to text.

Parameters:: text (str)
Return type:: str

plan_view.cli.bold_cyan(text)[source]¶

Apply bold cyan ANSI formatting to text.

Parameters:: text (str)
Return type:: str

plan_view.cli.bold_yellow(text)[source]¶

Apply bold yellow ANSI formatting to text.

Parameters:: text (str)
Return type:: str

plan_view.cli.now_iso()[source]¶

Return current UTC time in ISO 8601 format.

Return type:: str

plan_view.cli.load_plan(path, *, auto_migrate=False)[source]¶

Load and parse plan.json, ensuring special phases exist.

Parameters:

path (Path) – Path to the plan.json file.
auto_migrate (bool) – If True, save the plan after adding missing special phases.

Return type:

dict | None

plan_view.cli.save_plan(path, plan)[source]¶

Save plan.json with updated timestamp.

Parameters:

path (Path)
plan (dict)

Return type:

None

plan_view.cli.load_schema()[source]¶

Load the bundled JSON schema.

Return type:: dict

plan_view.cli.recalculate_progress(plan)[source]¶

Recalculate all progress fields.

Parameters:: plan (dict)
Return type:: None

plan_view.cli.get_current_phase(plan)[source]¶

Find the current in_progress or first pending phase (skips special phases).

Parameters:: plan (dict)
Return type:: dict | None

plan_view.cli.get_next_task(plan)[source]¶

Find the next actionable task with all dependencies met (skips special phases).

Parameters:: plan (dict)
Return type:: tuple[dict, dict] | None

plan_view.cli.find_task(plan, task_id)[source]¶

Find a task by ID (exact or prefix match), return (phase, task) or None.

Parameters:

plan (dict)
task_id (str)

Return type:

tuple[dict, dict] | None

plan_view.cli.find_phase(plan, phase_id)[source]¶

Find a phase by ID.

Parameters:

plan (dict)
phase_id (str)

Return type:

dict | None

plan_view.cli.task_to_dict(phase, task)[source]¶

Convert a task to a JSON-serializable dict.

Parameters:

phase (dict)
task (dict)

Return type:

dict

plan_view.cli.cmd_overview(plan, *, as_json=False)[source]¶

Display full plan overview with all phases and tasks.

Parameters:

plan (dict)
as_json (bool)

Return type:

None

plan_view.cli.cmd_current(plan, *, as_json=False)[source]¶

Display completed phases summary, current phase, and next task.

Parameters:

plan (dict)
as_json (bool)

Return type:

None

plan_view.cli.cmd_next(plan, *, as_json=False)[source]¶

Display the next task to work on.

Parameters:

plan (dict)
as_json (bool)

Return type:

None

plan_view.cli.cmd_phase(plan, *, as_json=False)[source]¶

Display current phase details with all tasks and dependencies.

Parameters:

plan (dict)
as_json (bool)

Return type:

None

plan_view.cli.cmd_get(plan, task_id, *, as_json=False)[source]¶

Display a specific task or phase by ID.

Parameters:

plan (dict)
task_id (str)
as_json (bool)

Return type:

None

plan_view.cli.cmd_last(plan, count=5, *, as_json=False)[source]¶

Display recently completed tasks.

Parameters:

plan (dict)
count (int | None)
as_json (bool)

Return type:

None

plan_view.cli.cmd_summary(plan, *, as_json=False)[source]¶

Display summary of plan progress.

Parameters:

plan (dict)
as_json (bool)

Return type:

None

plan_view.cli.cmd_bugs(plan, *, as_json=False)[source]¶

Display bugs phase with all tasks.

Parameters:

plan (dict)
as_json (bool)

Return type:

None

plan_view.cli.cmd_deferred(plan, *, as_json=False)[source]¶

Display deferred phase with all tasks.

Parameters:

plan (dict)
as_json (bool)

Return type:

None

plan_view.cli.cmd_validate(plan, path, *, as_json=False)[source]¶

Validate plan against JSON schema.

Parameters:

plan (dict)
path (Path)
as_json (bool)

Return type:

None

plan_view.cli.cmd_init(args)[source]¶

Create a new plan.json.

Parameters:: args (Namespace)
Return type:: None

plan_view.cli.cmd_add_phase(plan, args)[source]¶

Add a new phase.

Parameters:

plan (dict)
args (Namespace)

Return type:

None

plan_view.cli.cmd_add_task(plan, args)[source]¶

Add a new task to a phase.

Parameters:

plan (dict)
args (Namespace)

Return type:

None

plan_view.cli.cmd_set(plan, args)[source]¶

Set a task field.

Parameters:

plan (dict)
args (Namespace)

Return type:

None

plan_view.cli.cmd_done(args)[source]¶

Mark task as completed.

Parameters:: args (Namespace)
Return type:: None

plan_view.cli.cmd_start(args)[source]¶

Mark task as in_progress.

Parameters:: args (Namespace)
Return type:: None

plan_view.cli.cmd_block(args)[source]¶

Mark task as blocked.

Parameters:: args (Namespace)
Return type:: None

plan_view.cli.cmd_skip(args)[source]¶

Mark task as skipped.

Parameters:: args (Namespace)
Return type:: None

plan_view.cli.cmd_defer(plan, args)[source]¶

Move task to deferred phase, or create a new deferred task if input is not an existing task ID.

Parameters:

plan (dict)
args (Namespace)

Return type:

None

plan_view.cli.cmd_bug(plan, args)[source]¶

Move task to bugs phase, or create a new bug if input is not an existing task ID.

Parameters:

plan (dict)
args (Namespace)

Return type:

None

plan_view.cli.cmd_rm(plan, args)[source]¶

Remove a phase or task.

Parameters:

plan (dict)
args (Namespace)

Return type:

None

plan_view.cli.main()[source]¶

CLI entry point for pv command.

Return type:: None