Workflow Packs

Workflow packs are distributable bundles of YAML workflows, prompt files, and scripts that can be installed from GitHub Releases. They enable sharing reusable workflow collections across projects and teams.

Overview#

A workflow pack contains:

• Workflows — YAML workflow definitions (.yaml files)
• Prompts — Prompt files referenced by workflows
• Scripts — Script files referenced by workflows
• Manifest — manifest.yaml describing the pack metadata and contents

Packs are installed via awf workflow install and executed via awf run pack/workflow namespace syntax.

Quick Start#

# Install a workflow pack
awf workflow install myorg/awf-workflow-speckit

# List installed packs
awf workflow list

# Run a workflow from the pack
awf run speckit/specify --input file=main.go

# View pack details
awf workflow info speckit

# Update to latest version
awf workflow update speckit

Searching for Packs#

Discover available workflow packs on GitHub:

# Browse all packs (tagged with awf-workflow topic)
awf workflow search

# Search by keyword
awf workflow search speckit

# JSON output for scripting
awf workflow search --output=json

Results show the repository name, star count, and description. Set GITHUB_TOKEN for higher API rate limits.

Installing Packs#

Install packs from GitHub Releases:

# Install latest version
awf workflow install myorg/awf-workflow-speckit

# Install specific version
awf workflow install myorg/awf-workflow-speckit@1.2.0

# Install with version constraint
awf workflow install myorg/awf-workflow-speckit --version ">=1.0.0 <2.0.0"

# Install globally (available to all projects)
awf workflow install myorg/awf-workflow-speckit --global

# Force reinstall
awf workflow install myorg/awf-workflow-speckit --force

AWF downloads the release archive, verifies the SHA-256 checksum, validates the manifest (including AWF version compatibility), and installs atomically.

Installation Locations#

Local packs are project-specific. Global packs are available to all projects.

Plugin Dependencies#

If a pack declares plugin dependencies in its manifest, non-blocking warnings are emitted during installation:

Warning: pack requires plugin "jira" (>=1.0.0) — install with: awf plugin install <owner>/jira

The pack installs regardless of missing plugins. Install required plugins separately with awf plugin install.

Listing Packs#

View all installed packs:

awf workflow list

This discovers packs from local and global directories, deduplicating by name (local takes precedence over global). A (local) pseudo-entry appears when .awf/workflows/ contains local workflow files.

Viewing Pack Details#

Inspect an installed pack:

awf workflow info speckit

Displays:

• Pack name, version, description, author, license
• List of available workflows
• Plugin dependency warnings with install commands
• Embedded README content (if present)

Updating Packs#

Update a pack to the latest release from its source repository:

# Update a specific pack
awf workflow update speckit

# Update all installed packs
awf workflow update --all

The update checks state.json for the source repository, queries GitHub Releases for newer versions, and performs an atomic replacement. User overrides in .awf/prompts/<pack>/ and .awf/scripts/<pack>/ are preserved.

Removing Packs#

Remove an installed pack:

awf workflow remove speckit

This removes the pack directory and all its contents. The command searches local then global directories.

Running Pack Workflows#

Pack workflows use pack/workflow namespace syntax:

# Run a workflow from an installed pack
awf run speckit/specify --input file=main.go

# Dry-run to preview
awf run speckit/specify --dry-run

# Interactive mode
awf run speckit/specify --interactive

Local workflows (without a / separator) are unaffected.

Resource Resolution Order#

Pack workflows resolve prompts and scripts using a 3-tier hierarchy:

1. .awf/prompts/<pack>/... — user override (highest priority)
2. .awf/workflow-packs/<pack>/prompts/... — pack embedded
3. ~/.config/awf/prompts/... — global XDG (lowest priority)

This allows customizing pack behavior without modifying pack files directly.

Pack Workflows in awf list#

The awf list command includes pack workflows alongside local and global workflows:

awf list

Pack workflows appear with pack/workflow namespace prefix and pack source label. The awf list and awf workflow list commands show the same packs and versions.

Manifest Format#

Pack authors create a manifest.yaml at the pack root:

name: speckit
version: "1.0.0"
description: "Specification-driven development workflows"
author: "Your Name"
license: "MIT"
awf_version: ">=0.5.0"
workflows:
  - specify
  - implement
  - review
plugins:
  jira: ">=1.0.0"

Manifest Fields#

Pack Directory Structure#

awf-workflow-speckit/
├── manifest.yaml          # Pack metadata
├── README.md              # Optional documentation
├── workflows/
│   ├── specify.yaml       # Workflow definitions
│   └── implement.yaml
├── prompts/
│   └── system.md          # Prompt files
└── scripts/
    └── setup.sh           # Script files

Distributing Packs via GitHub Releases#

Pack authors publish .tar.gz archives to GitHub Releases. Workflow packs are platform-independent (no OS/architecture suffix needed).

Release Assets#

Each release must include:

• A .tar.gz archive (e.g., awf-workflow-speckit_1.0.0.tar.gz)
• A checksums.txt file with SHA-256 hashes

GoReleaser Configuration#

project_name: awf-workflow-speckit

archives:
  - format: tar.gz
    name_template: "{{ .ProjectName }}_{{ .Version }}"
    files:
      - manifest.yaml
      - README.md
      - workflows/*
      - prompts/*
      - scripts/*

checksum:
  name_template: checksums.txt
  algorithm: sha256

release:
  github:
    owner: your-org
    name: awf-workflow-speckit

Authentication#

AWF uses the same authentication chain as plugin installation:

1. GITHUB_TOKEN environment variable
2. gh auth token output
3. Unauthenticated requests (lower rate limits)

See Also#

• Commands — CLI command reference for all workflow subcommands
• Plugins — Plugin system documentation
• Workflow Syntax — YAML workflow definition reference