/pac-create-epic

Create PAC Epic

Create a new epic following the Product as Code specification with guided workflow

Instructions

1. **Validate PAC Configuration**

• Check if `.pac/` directory exists
• Verify PAC configuration file exists at `.pac/pac.config.yaml`
• If not configured, suggest running `/project:pac-configure` first
• Parse arguments: `$ARGUMENTS`

2. **Epic Information Gathering**

• If arguments provided, parse:
• `--name <name>`: Epic name
• `--description <desc>`: Epic description
• `--owner <owner>`: Epic owner
• `--scope <scope>`: Scope definition
• For missing information, prompt user interactively:
• Epic ID (suggest format: epic-[kebab-case-name])
• Epic name (human-readable)
• Epic owner (default from config if available)
• Epic description (multi-line)
• Scope definition (what's included/excluded)
• Success criteria (at least 2-3 items)

3. **Generate Epic ID**

• If not provided, generate from epic name:
• Convert to lowercase
• Replace spaces with hyphens
• Remove special characters
• Prefix with "epic-"
• Validate uniqueness against existing epics

4. **Create Epic Structure**

• Generate epic YAML following PAC v0.1.0 specification:

     apiVersion: productascode.org/v0.1.0
     kind: Epic
     metadata:
       id: "[generated-epic-id]"
       name: "[Epic Name]"
       created: "[current-timestamp]"
       updated: "[current-timestamp]"
       owner: "[owner-email-or-name]"
       labels:
         status: "active"
         priority: "medium"
     spec:
       description: |
         [Multi-line description]
       
       scope: |
         [Scope definition]
       
       success_criteria:
         - [Criterion 1]
         - [Criterion 2]
         - [Criterion 3]
       
       constraints:
         - [Any constraints or limitations]
       
       dependencies:
         - [Dependencies on other epics/systems]
       
       tickets: []  # Will be populated as tickets are created

5. **Validate Epic Content**

• Check all required fields are present
• Validate apiVersion matches specification
• Ensure metadata has required identifiers
• Verify success criteria has at least one item
• Check YAML syntax is valid

6. **Save Epic File**

• Determine filename: `.pac/epics/[epic-id].yaml`
• Check if file already exists
• If exists, ask user to confirm overwrite
• Write epic content to file
• Set appropriate file permissions

7. **Create Epic Directory Structure**

• Create `.pac/epics/[epic-id]/` directory for epic-specific docs
• Add `.pac/epics/[epic-id]/README.md` with epic overview
• Create `.pac/epics/[epic-id]/tickets/` for future ticket links

8. **Update PAC Index**

• If `.pac/index.yaml` exists, add epic entry:

     epics:
       - id: "[epic-id]"
         name: "[Epic Name]"
         status: "active"
         created: "[timestamp]"
         ticket_count: 0

9. **Git Integration**

• If in git repository:
• Add new epic file to git
• Create branch `pac/[epic-id]` for epic work
• Prepare commit message:

       feat(pac): add epic [epic-id]
       
       - Epic: [Epic Name]
       - Owner: [Owner]
       - Success Criteria: [count] items defined

10. **Generate Epic Summary**

• Display created epic details:
• Epic ID and location
• Success criteria summary
• Next steps for creating tickets
• Show helpful commands:
• Create ticket: `/project:pac-create-ticket --epic [epic-id]`
• View epic: `cat .pac/epics/[epic-id].yaml`
• Validate: `.pac/scripts/validate.sh .pac/epics/[epic-id].yaml`

Arguments

• `--name <name>`: Epic name (required if not interactive)
• `--description <description>`: Epic description
• `--owner <owner>`: Epic owner email or name
• `--scope <scope>`: Scope definition
• `--success-criteria <criteria>`: Comma-separated success criteria
• `--priority <priority>`: Priority level (low/medium/high/critical)
• `--no-git`: Skip git integration

Example Usage

/project:pac-create-epic
/project:pac-create-epic --name "User Authentication System"
/project:pac-create-epic --name "Payment Integration" --owner "john@example.com" --priority high