plan-view 1.0.0

Pretty print plan.json for task tracking

pv - Plan Viewer

Pretty print and edit plan.json for task tracking.

Installation

# Global install with uv
uv tool install git+https://github.com/JacobCoffee/pv

# Or from local checkout
make install
# or: uv tool install . --force --reinstall --python 3.14

Usage

View Commands

pv                  # Full plan overview
pv c, current       # Completed summary + current phase + next task
pv n, next          # Show next pending/in-progress task
pv p, phase         # Current phase with all tasks + dependencies
pv g, get ID        # Show a specific task by ID
pv l, last          # Show recently completed tasks
pv v, validate      # Validate plan.json against schema
pv h, help          # Show help

Edit Commands

pv init "Project Name"                    # Create new plan.json
pv add-phase "Auth" --desc "User auth"    # Add a phase
pv add-task 1 "Create model" --agent X    # Add task to phase 1
pv start 1.1.1                            # Mark task in_progress
pv done 1.1.1                             # Mark task completed
pv set 1.1.1 status blocked               # Set any status
pv set 1.1.1 agent python-backend-engineer
pv rm task 1.1.1                          # Remove a task
pv rm phase 2                             # Remove a phase

Options

pv -f other.json current    # Use different file
pv current --json           # Output as JSON (all view commands)
pv --json current           # Same thing
pv last -n 10               # Show last 10 completed tasks
pv init "Name" --force      # Overwrite existing plan.json

Example

$ pv init "My App"
✅ Created plan.json for 'My App'

$ pv add-phase "Setup" --desc "Project setup"
✅ Added Phase 0: Setup

$ pv add-task 0 "Initialize repo" --agent github-git-expert
✅ Added [0.1.1] Initialize repo

$ pv done 0.1.1
✅ [0.1.1] status → completed

$ pv c
📋 My App v1.0.0
Progress: 100% (1/1 tasks)

✅ Phase 0: Setup (100%)

$ pv g 0.1.1 --json
{
  "id": "0.1.1",
  "title": "Initialize repo",
  "status": "completed",
  ...
}

Features

• Auto-calculates progress percentages
• Updates phase status based on task completion
• Tracks started_at and completed_at timestamps
• Validates against plan.json schema
• JSON output for all view commands (--json)

License

MIT