PAC Create Instant

Instantly scaffold a Product as Code epic with YAML definition, directory layout, and index registration following the PAC v0.1.0 specification.

When to Use This Command

Run this command when...

• You want to quickly create a PAC epic without interactive prompts by passing all details as arguments
• You need to scaffold an epic YAML file with metadata fields and immediately start adding tickets
• You are automating epic creation as part of a script or CI pipeline that provisions project structure
• You want to create the epic directory under .pac/epics/ and update the PAC index in a single operation
• You prefer a fast, non-interactive workflow for creating product epics during planning sessions

Quick Start

Copy
# .claude/commands/pac-create-instant.yaml
name: PAC Create Instant
description: Instantly create a PAC epic with one command
inputs:
  - name: name
    description: "Epic name (required)"
  - name: owner
    description: "Epic owner"
    default: ""

Copy
# Quick creation with just a name
claude "pac-create-instant 'Search Feature'"

# Full specification in one shot
claude "pac-create-instant --name 'Notification System' --owner 'Alex' --description 'Push and email notifications' --scope 'mobile and web'"

Output:
  [validate] PAC directory found at .pac/
  [id] Generated: epic-notification-system
  [yaml] Created .pac/epics/epic-notification-system/epic.yaml
  [index] Registered in .pac/index.yaml
  [branch] Created: pac/epic-notification-system
  Done. 1 epic created in 0.8s

Core Concepts

Concept	Description
Instant Mode	No interactive prompts; missing optional fields use defaults from pac.config.yaml
ID Convention	Epic names are converted to epic-[kebab-case] format for consistent file naming
YAML Schema	Follows PAC v0.1.0: id, name, created timestamp, owner, and spec (description, scope, success criteria)
Index Update	Automatically registers the new epic in .pac/index.yaml for discovery
Branch Creation	Creates a pac/<epic-id> git branch when inside a git repository

Instant Epic Pipeline:
  Input ──> Validate ──> Generate ID ──> Write YAML ──> Create Dir
                                                           │
              ┌────────────────────────────────────────────┘
              ▼
         Update Index ──> Create Branch ──> Output Summary

Configuration

Parameter	Type	Default	Description
name	string	required	Epic name, used to generate the kebab-case ID
description	string	""	What this epic accomplishes and why it matters
owner	string	pac.config default	Person accountable for epic completion
scope	string	""	Boundaries of what the epic includes and excludes
skip_branch	boolean	false	Skip git branch creation for the epic

Best Practices

1. Batch-create during planning -- Use the instant mode in a loop or script to create multiple epics during sprint planning, then go back and add tickets to each one.
2. Provide scope at creation time -- The scope field prevents ambiguity later. Even a one-sentence scope like "backend API only" saves hours of misaligned work.
3. Use consistent naming conventions -- Agree on naming patterns like "Feature: X" or "Initiative: Y" so that generated IDs are predictable and sortable.
4. Skip branches for planning-only epics -- Use --skip-branch for epics that are still in planning and do not yet have implementation work to isolate.
5. Review the index after bulk creation -- After creating several epics, open .pac/index.yaml to verify the order and ensure no duplicate IDs were generated.

Common Issues

1. PAC directory not initialized -- The .pac/ directory must exist before creating epics. Run pac-configure to set up the required structure and configuration files.
2. Name collision produces duplicate ID -- Two different names can produce the same kebab-case ID (e.g., "User Auth" and "user-auth"). Check existing epics with ls .pac/epics/ before creating.
3. Git branch already exists -- If a pac/<epic-id> branch already exists from a previous attempt, the command will fail on branch creation. Delete the stale branch with git branch -d pac/<epic-id> or use --skip-branch.