How to Organize Pack Files

Structure and manage your pack files for maintainability and scalability.

Goal

Create a clear, maintainable organization system for your pack files that scales with your project.

Prerequisites

packc installed
Understanding of your project structure
Multiple pack files or environments

Organization Strategies

Strategy 1: By Environment

Separate packs by deployment environment:

packs/
├── dev/
│   ├── app.pack.json
│   └── admin.pack.json
├── staging/
│   ├── app.pack.json
│   └── admin.pack.json
└── prod/
    ├── app.pack.json
    └── admin.pack.json

Setup:

# Create structure
mkdir -p packs/{dev,staging,prod}

# Compile for each environment
packc compile --config config/arena.dev.yaml \
  --output packs/dev/app.pack.json --id app-dev

packc compile --config config/arena.staging.yaml \
  --output packs/staging/app.pack.json --id app-staging

packc compile --config config/arena.prod.yaml \
  --output packs/prod/app.pack.json --id app-prod

Strategy 2: By Feature

Organize by application feature or module:

packs/
├── customer-support/
│   ├── chat.pack.json
│   └── email.pack.json
├── sales/
│   ├── leads.pack.json
│   └── opportunities.pack.json
└── marketing/
    ├── campaigns.pack.json
    └── analytics.pack.json

Setup:

# Create feature directories
mkdir -p packs/{customer-support,sales,marketing}

# Compile feature packs
packc compile --config config/customer-support/arena.yaml \
  --output packs/customer-support/chat.pack.json --id cs-chat

packc compile --config config/sales/arena.yaml \
  --output packs/sales/leads.pack.json --id sales-leads

Strategy 3: By Version

Version control your packs:

packs/
├── v1.0.0/
│   └── app.pack.json
├── v1.1.0/
│   └── app.pack.json
├── v1.2.0/
│   └── app.pack.json
└── latest -> v1.2.0/

Setup:

VERSION="1.2.0"

# Create version directory
mkdir -p "packs/v${VERSION}"

# Compile to versioned location
packc compile --config arena.yaml \
  --output "packs/v${VERSION}/app.pack.json" --id "app-v${VERSION}"

# Update latest symlink
ln -sf "v${VERSION}" packs/latest

Strategy 4: Hybrid Organization

Combine strategies for complex projects:

packs/
├── dev/
│   ├── customer-support/
│   │   └── v1.0.0/
│   │       └── app.pack.json
│   └── sales/
│       └── v1.0.0/
│           └── app.pack.json
├── staging/
│   ├── customer-support/
│   │   └── v1.0.0/
│   │       └── app.pack.json
│   └── sales/
│       └── v1.0.0/
│           └── app.pack.json
└── prod/
    ├── customer-support/
    │   └── v1.0.0/
    │       └── app.pack.json
    └── sales/
        └── v1.0.0/
            └── app.pack.json

Naming Conventions

Pack File Names

Use descriptive, consistent names:

# Good naming
customer-support.pack.json
sales-leads-v1.pack.json
marketing-campaigns-prod.pack.json

# Avoid
pack1.json
temp.pack.json
test.json

Pack IDs

Match IDs to purpose and environment:

# Development
--id customer-support-dev

# Staging
--id customer-support-staging

# Production
--id customer-support-prod

# Versioned
--id customer-support-v1.2.0

Build Scripts

Environment-Based Build

#!/bin/bash
# scripts/build-packs.sh

set -e

ENVIRONMENTS=("dev" "staging" "prod")

for env in "${ENVIRONMENTS[@]}"; do
  echo "Building packs for $env..."
  
  mkdir -p "packs/$env"
  
  packc compile \
    --config "config/arena.$env.yaml" \
    --output "packs/$env/app.pack.json" \
    --id "app-$env"
  
  packc validate "packs/$env/app.pack.json"
done

echo "✓ All packs built successfully"

Feature-Based Build

#!/bin/bash
# scripts/build-features.sh

set -e

FEATURES=("customer-support" "sales" "marketing")

for feature in "${FEATURES[@]}"; do
  echo "Building $feature packs..."
  
  mkdir -p "packs/$feature"
  
  for config in "config/$feature"/*.yaml; do
    name=$(basename "$config" .yaml)
    
    packc compile \
      --config "$config" \
      --output "packs/$feature/$name.pack.json" \
      --id "$feature-$name"
  done
done

echo "✓ All feature packs built"

Versioned Build

#!/bin/bash
# scripts/build-versioned.sh

set -e

VERSION="${1:-$(date +%Y%m%d)}"

echo "Building version: $VERSION"

mkdir -p "packs/v$VERSION"

packc compile \
  --config arena.yaml \
  --output "packs/v$VERSION/app.pack.json" \
  --id "app-v$VERSION"

# Update latest
ln -sf "v$VERSION" packs/latest

echo "✓ Version $VERSION built"
echo "Latest points to: $(readlink packs/latest)"

Makefile Organization

# Variables
VERSION ?= $(shell date +%Y%m%d)
ENVIRONMENTS := dev staging prod
FEATURES := customer-support sales marketing

.PHONY: build-all
build-all: build-by-env build-by-feature build-versioned

# Build by environment
.PHONY: build-by-env
build-by-env:
	@for env in $(ENVIRONMENTS); do \
		mkdir -p packs/$$env; \
		packc compile --config config/arena.$$env.yaml \
		  --output packs/$$env/app.pack.json --id app-$$env; \
	done

# Build by feature
.PHONY: build-by-feature
build-by-feature:
	@for feature in $(FEATURES); do \
		mkdir -p packs/$$feature; \
		packc compile --config config/$$feature/arena.yaml \
		  --output packs/$$feature/app.pack.json --id $$feature-app; \
	done

# Build versioned
.PHONY: build-versioned
build-versioned:
	@mkdir -p packs/v$(VERSION)
	@packc compile --config arena.yaml \
	  --output packs/v$(VERSION)/app.pack.json --id app-v$(VERSION)
	@ln -sf v$(VERSION) packs/latest

# Clean
.PHONY: clean
clean:
	rm -rf packs/

.PHONY: clean-env
clean-env:
	rm -rf packs/$(ENV)/

# Validate
.PHONY: validate-all
validate-all:
	@find packs -name '*.pack.json' -exec packc validate {} \;

Configuration Organization

Mirror your pack organization in configs:

config/
├── dev/
│   └── arena.yaml
├── staging/
│   └── arena.yaml
├── prod/
│   └── arena.yaml
└── features/
    ├── customer-support/
    │   └── arena.yaml
    ├── sales/
    │   └── arena.yaml
    └── marketing/
        └── arena.yaml

Metadata Files

Track pack information:

# Create pack inventory
cat > packs/inventory.json <<EOF
{
  "environments": {
    "dev": {
      "packs": ["app.pack.json"],
      "last_build": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
    },
    "prod": {
      "packs": ["app.pack.json"],
      "last_build": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
    }
  }
}
EOF

Git Configuration

.gitignore

# Ignore compiled packs in development
packs/dev/*.pack.json
packs/staging/*.pack.json

# Keep production packs in version control
# (Comment out the line below to track prod packs)
packs/prod/*.pack.json

# Ignore temporary builds
packs/tmp/
packs/*.tmp.json

# Keep directory structure
!packs/dev/.gitkeep
!packs/staging/.gitkeep
!packs/prod/.gitkeep

Track Pack Metadata

# Create .gitkeep files
touch packs/{dev,staging,prod}/.gitkeep

# Create README
cat > packs/README.md <<EOF
# Prompt Packs

This directory contains compiled prompt packs organized by environment.

## Structure

- \`dev/\` - Development packs
- \`staging/\` - Staging packs  
- \`prod/\` - Production packs

## Building

Run \`make build-all\` to compile all packs.

See [build instructions](../docs/packc/how-to/compile-packs) for details.
EOF

git add packs/.gitkeep packs/README.md

Best Practices

1. Consistent Directory Structure

project/
├── config/          # Source configurations
│   ├── dev/
│   ├── staging/
│   └── prod/
├── packs/           # Compiled packs
│   ├── dev/
│   ├── staging/
│   └── prod/
└── prompts/         # Source prompts
    ├── customer-support/
    ├── sales/
    └── marketing/

2. Document Organization

Create a pack organization guide:

# Pack Organization Guide

## Directory Structure

- `packs/dev/` - Development builds
- `packs/staging/` - QA/testing builds
- `packs/prod/` - Production releases

## Naming Conventions

- Use kebab-case: `customer-support.pack.json`
- Include version: `app-v1.2.0.pack.json`
- Add environment suffix: `app-prod.pack.json`

## Build Process

1. Update prompt configurations
2. Run `make build-by-env`
3. Validate with `make validate-all`
4. Commit to version control

3. Automate Organization

#!/bin/bash
# scripts/organize-packs.sh

# Create structure
mkdir -p packs/{dev,staging,prod}/{customer-support,sales,marketing}

# Build into organized structure
for env in dev staging prod; do
  for feature in customer-support sales marketing; do
    packc compile \
      --config "config/$env/$feature/arena.yaml" \
      --output "packs/$env/$feature/app.pack.json" \
      --id "$feature-$env"
  done
done

4. Version Control Strategy

Choose what to track:

Option A: Track all packs

# Track everything
!packs/**/*.pack.json

Option B: Track only production

# Ignore dev/staging
packs/dev/
packs/staging/

# Keep production
!packs/prod/**/*.pack.json

Option C: Track none (build in CI)

# Ignore all packs
packs/**/*.pack.json

# Keep structure
!packs/**/.gitkeep

5. Cleanup Old Versions

#!/bin/bash
# scripts/cleanup-old-packs.sh

KEEP_VERSIONS=3

cd packs

# Remove old versioned packs, keep latest N
ls -dt v* | tail -n +$((KEEP_VERSIONS + 1)) | xargs rm -rf

echo "Kept latest $KEEP_VERSIONS versions"

Next Steps

CI/CD Integration - Automate pack builds
Validate Packs - Quality assurance
Pack Management Tutorial

How to Organize Pack Files

Goal

Prerequisites

Organization Strategies

Strategy 1: By Environment

Strategy 2: By Feature

Strategy 3: By Version

Strategy 4: Hybrid Organization

Naming Conventions

Pack File Names

Pack IDs

Build Scripts

Environment-Based Build

Feature-Based Build

Versioned Build

Makefile Organization

Configuration Organization

Metadata Files

Git Configuration

.gitignore

Track Pack Metadata

Best Practices

1. Consistent Directory Structure

2. Document Organization

3. Automate Organization

4. Version Control Strategy

5. Cleanup Old Versions

Next Steps

See Also