Quick PAC Create Epic

Create a new Product as Code epic with full YAML metadata, directory structure, and optional git branch following the PAC v0.1.0 specification.

When to Use This Command

Run this command when...

• You are starting a new feature or initiative and need a formal epic definition in your PAC structure
• You want to generate a properly formatted epic YAML file with required fields like scope, success criteria, and dependencies
• You need to create the epic directory, update the PAC index, and optionally create a dedicated git branch in one step
• You have completed PAC configuration and are ready to break your project into trackable epics
• You want to interactively fill in epic details when arguments are not provided on the command line

Quick Start

Copy
# .claude/commands/quick-pac-create-epic.yaml
name: Quick PAC Create Epic
description: Create a new epic with YAML metadata and directory structure
inputs:
  - name: name
    description: "Epic name"
  - name: description
    description: "Epic description"
    default: ""

Copy
# Create an epic with a name
claude "quick-pac-create-epic --name 'User Authentication'"

# Create with full details
claude "quick-pac-create-epic --name 'Payment Integration' --description 'Stripe payment flow' --owner 'Jane' --scope 'checkout'"

Output:
  [validate] PAC configuration found
  [generate] Epic ID: epic-payment-integration
  [create] Created .pac/epics/epic-payment-integration/epic.yaml
  [index] Updated .pac/index.yaml
  [branch] Created branch: pac/epic-payment-integration
  Done. Epic ready. Next: pac-create-ticket --epic epic-payment-integration

Core Concepts

Concept	Description
Epic ID Generation	Automatically converts the epic name to kebab-case with epic- prefix
YAML Specification	Follows PAC v0.1.0 with required fields: id, name, created, owner, spec
Spec Section	Contains description, scope, success criteria, constraints, and dependencies
Directory Structure	Each epic gets its own folder under .pac/epics/ for related artifacts
Branch Integration	Optionally creates a pac/<epic-id> git branch for isolated development

Epic Creation Flow:
  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
  │ Validate PAC │───>│ Generate ID  │───>│ Create YAML  │
  └──────────────┘    └──────────────┘    └──────┬───────┘
                                                 │
                                          ┌──────▼───────┐
                                          │ Create Dir   │
                                          └──────┬───────┘
                                                 │
                                   ┌─────────────┼─────────────┐
                                   │             │             │
                              ┌────▼───┐   ┌────▼────┐  ┌────▼─────┐
                              │ Index  │   │ Branch  │  │ Summary  │
                              └────────┘   └─────────┘  └──────────┘

Configuration

Parameter	Type	Default	Description
name	string	required	Human-readable epic name (converted to kebab-case ID)
description	string	""	Detailed description of the epic's purpose and goals
owner	string	config default	Person responsible for the epic's delivery
scope	string	""	Boundary definition for what is included and excluded
branch	boolean	true	Whether to create a dedicated git branch for this epic

Best Practices

1. Use descriptive epic names -- The name becomes the kebab-case ID and branch name. "User Authentication" is better than "Auth" because it produces a clear ID epic-user-authentication that is searchable and self-documenting.
2. Define success criteria upfront -- Fill in the success criteria field during creation rather than later. This establishes a definition of done that guides ticket creation and prevents scope creep.
3. Set constraints and dependencies -- Explicitly listing what the epic depends on and what constraints apply helps the team plan work order and avoid blockers.
4. Create the git branch -- Using the auto-created pac/ branch keeps epic work isolated and makes it easy to see all commits related to a product initiative.
5. Follow up with tickets immediately -- An epic without tickets is just a plan. Run pac-create-ticket --epic <id> right after to break the work into actionable items.

Common Issues

1. PAC not configured -- The command requires .pac/pac.config.yaml to exist. Run pac-configure first to initialize the project structure before creating epics.
2. Duplicate epic ID -- If an epic with the same kebab-case ID already exists, the command will refuse to overwrite. Choose a different name or remove the existing epic directory first.
3. Missing required fields in interactive mode -- When no arguments are provided, the command prompts interactively. Ensure you provide at least the epic name, as all other fields have sensible defaults.