/pac-validate

Validate PAC Structure

Validate Product as Code project structure and files for specification compliance

Instructions

1. **Initial Environment Check**

• Verify `.pac/` directory exists
• Check for PAC configuration file at `.pac/pac.config.yaml`
• Parse arguments: `$ARGUMENTS`
• Determine validation scope (single file, directory, or entire project)

2. **Configuration Validation**

• Load and validate `.pac/pac.config.yaml`:
• Check `apiVersion` format (must be semantic version)
• Verify `kind` is "Configuration"
• Validate required metadata fields
• Check defaults section has valid values
• Report any missing or invalid configuration

3. **Directory Structure Validation**

• Verify required directories exist:
• `.pac/epics/` - Epic definitions
• `.pac/tickets/` - Ticket definitions
• `.pac/templates/` - Templates (optional but recommended)
• Check file permissions are correct
• Ensure no orphaned files outside expected structure

4. **Epic File Validation**

• For each file in `.pac/epics/`:
• Verify YAML syntax is valid
• Check `apiVersion: productascode.org/v0.1.0`
• Verify `kind: Epic`
• Validate required metadata fields:
• `id` (must be unique)
• `name` (non-empty string)
• `created` (valid timestamp)
• `owner` (non-empty string)
• Validate spec section:
• `description` exists
• `success_criteria` has at least one item
• `tickets` array is properly formatted
• Track all epic IDs for cross-reference validation

5. **Ticket File Validation**

• For each file in `.pac/tickets/`:
• Verify YAML syntax is valid
• Check `apiVersion: productascode.org/v0.1.0`
• Verify `kind: Ticket`
• Validate required metadata:
• `id` (unique across all tickets)
• `name` (non-empty string)
• `epic` (must reference valid epic ID)
• `created` (valid timestamp)
• `assignee` (if specified)
• Validate spec fields:
• `type` is one of: feature, bug, task, spike
• `status` is one of: backlog, in-progress, review, done, cancelled
• `priority` is one of: low, medium, high, critical
• `acceptance_criteria` has at least one item
• `tasks` array is properly formatted

6. **Cross-Reference Validation**

• Verify all ticket epic references point to existing epics
• Check that epic ticket lists match actual ticket files
• Validate ticket dependencies reference existing tickets
• Ensure no circular dependencies exist
• Verify unique IDs across all entities

7. **Data Integrity Checks**

• Validate timestamp formats (ISO 8601)
• Check that updated timestamps are >= created timestamps
• Verify status transitions make sense (no done tickets in backlog epics)
• Validate priority and effort estimates are consistent

8. **Template Validation**

• If templates exist in `.pac/templates/`:
• Verify they follow PAC specification
• Check they include all required fields
• Ensure placeholder values are clearly marked

9. **Generate Validation Report**

• Create detailed report with:

     PAC Validation Report
     ====================
     
     Configuration: [VALID/INVALID]
     - Issues found: [count]
     
     Structure: [VALID/INVALID]
     - Epics found: [count]
     - Tickets found: [count]
     - Orphaned files: [count]
     
     Epic Validation:
     - Valid epics: [count]
     - Invalid epics: [list with reasons]
     
     Ticket Validation:
     - Valid tickets: [count]
     - Invalid tickets: [list with reasons]
     
     Cross-Reference Issues:
     - Missing epic references: [list]
     - Orphaned tickets: [list]
     - Invalid dependencies: [list]
     
     Recommendations:
     - [Specific fixes needed]

10. **Auto-Fix Options**

• If `--fix` flag provided:
• Add missing required fields with placeholder values
• Fix formatting issues (indentation, quotes)
• Update epic ticket lists to match actual tickets
• Create backup before making changes
• Show what would be fixed without `--fix` flag

11. **Git Integration**

• If `--pre-commit` flag:
• Only validate files staged for commit
• Exit with appropriate code for git hook
• Provide concise output suitable for CLI

12. **Summary and Exit Codes**

• Exit code 0: All validations passed
• Exit code 1: Validation errors found
• Exit code 2: Configuration errors
• Display summary:
• Total files validated
• Issues found and fixed (if applicable)
• Next steps for remaining issues

Arguments

• `--file <path>`: Validate specific file only
• `--epic <epic-id>`: Validate specific epic and its tickets
• `--fix`: Automatically fix common issues
• `--pre-commit`: Run in pre-commit mode (concise output)
• `--verbose`: Show detailed validation information
• `--quiet`: Only show errors, no success messages

Example Usage

/project:pac-validate
/project:pac-validate --fix
/project:pac-validate --file .pac/epics/epic-auth.yaml
/project:pac-validate --epic epic-payment --verbose
/project:pac-validate --pre-commit