Easy PAC Executor

Execute Product as Code workflows end-to-end, running validation, status updates, and reporting across all epics and tickets in your PAC project.

When to Use This Command

Run this command when...

• You want to run a batch operation across all PAC epics and tickets, such as validation or status reports
• You need to generate a project-wide progress report from your .pac/ directory structure
• You want to validate all YAML files against the PAC v0.1.0 specification in one sweep
• You are preparing for a sprint review and need aggregated metrics across all epics
• You need to clean up stale tickets, detect orphaned files, or reconcile the PAC index with actual content

Quick Start

Copy
# .claude/commands/easy-pac-executor.yaml
name: Easy PAC Executor
description: Execute batch PAC workflows across epics and tickets
inputs:
  - name: action
    description: "validate, report, cleanup, or sync"
    default: "report"

Copy
# Generate a full project report
claude "easy-pac-executor report"

# Validate all PAC YAML files
claude "easy-pac-executor validate"

# Clean up orphaned tickets and stale branches
claude "easy-pac-executor cleanup"

Output:
  [scan] Found 4 epics, 23 tickets
  [validate] 23/23 tickets valid
  [report] Epic progress:
    epic-user-auth:     ████████░░ 80% (4/5 done)
    epic-payments:      ████░░░░░░ 40% (2/5 done)
    epic-notifications: ██░░░░░░░░ 20% (1/5 done)
    epic-search:        ░░░░░░░░░░  0% (0/8 done)
  Done. Report saved to .pac/reports/2026-03-15.md

Core Concepts

Concept	Description
Batch Operations	Processes all epics and tickets in a single pass rather than one at a time
YAML Validation	Checks every YAML file against PAC v0.1.0 required fields and valid values
Progress Aggregation	Rolls up ticket statuses into per-epic and project-wide completion percentages
Index Reconciliation	Compares .pac/index.yaml against actual files to find orphans and missing entries
Report Generation	Produces markdown reports with progress bars, metrics, and action items

Executor Pipeline:
  ┌────────┐    ┌──────────┐    ┌──────────┐    ┌────────┐
  │  Scan  │───>│ Validate │───>│ Compute  │───>│ Report │
  │  Files │    │  YAML    │    │ Metrics  │    │ Output │
  └────────┘    └──────────┘    └──────────┘    └────────┘
       │                                             │
       └── .pac/epics/**/*.yaml              .pac/reports/

Configuration

Parameter	Type	Default	Description
action	string	"report"	Workflow to execute: validate, report, cleanup, or sync
epic	string	all	Restrict execution to a specific epic ID
output	string	".pac/reports/"	Directory for generated report files
fix	boolean	false	Auto-fix validation issues when possible (missing timestamps, etc.)
format	string	"markdown"	Report format: markdown, json, or terminal

Best Practices

1. Run validation before every sprint review -- Catching malformed YAML and missing fields before the review prevents embarrassing gaps in project tracking.
2. Schedule cleanup monthly -- Orphaned tickets and stale branches accumulate over time. A monthly cleanup keeps the PAC directory manageable and the index accurate.
3. Use JSON format for automation -- When piping PAC data into dashboards or CI pipelines, use --format json for structured output that tools can parse without regex.
4. Filter by epic for focused reports -- In large projects, generating a report for a single epic is faster and produces more actionable output than a full project scan.
5. Commit generated reports -- Storing reports in .pac/reports/ and committing them creates a historical record of project progress that survives branch merges.

Common Issues

1. No .pac/ directory found -- The executor requires an initialized PAC project. Run pac-configure first to create the required directory structure and configuration.
2. Validation errors on legacy tickets -- Tickets created before PAC v0.1.0 may lack required fields. Use --fix to auto-populate missing timestamps and default values.
3. Report directory not writable -- If .pac/reports/ does not exist, the command will attempt to create it. Ensure you have write permissions in the repository root directory.