packs: list, install and create stack packs

paqad-ai packs manages stack packs. A stack pack is a folder with a pack.yaml file (its manifest, a small file that names the pack and describes how to recognise the stack) plus stack-specific material such as coding conventions. Paqad ships built-in packs for common stacks, and you can add your own.

Use these commands to see which packs are in effect, add a pack your team maintains, or start a new one.

Where packs come from

Paqad looks for packs in three places. When the same pack name exists in more than one, the later place in this list wins:

1. built-in: shipped with paqad-ai.
2. global: ~/.paqad/packs/ on your machine, shared by all your projects. Set PAQAD_GLOBAL_PACKS_ROOT to use another folder.
3. project: .paqad/packs/ inside the project.

A pack that fails validation is skipped with a warning rather than loaded. For how overrides combine in detail, see pack precedence.

List packs

paqad-ai packs list [--json] [--project-root <path>]

Prints one line per pack in effect, showing where it comes from, its tier (framework or archetype), its display name, whether an override is active, and whether your project uses it:

[built-in] laravel (framework) — Laravel	override=false	matched=true

Add --json for the same data as JSON, including every place a pack was found (available_sources).

Install a pack

paqad-ai packs install <source> [--scope global|project] [--project-root <path>]

The source can be:

• A local folder, for example ./packs/my-stack. It must contain pack.yaml, or exactly one subfolder that does.
• A git URL (https://, ssh://, git@, file://, or anything ending in .git). Paqad makes a shallow clone, so git must be installed.
• A bare pack name, for example rails-internal. This only works when PAQAD_PACK_REGISTRY_URL points at your team's git host; Paqad then clones <registry-url>/<name>.git.

The pack is validated before and after it is copied. The default scope is global; use --scope project to install into .paqad/packs/ so the pack travels with the repository. Installing again replaces the earlier copy. The command prints the pack's name, source and install folder as JSON.

Remove a pack

paqad-ai packs remove <name> [--scope global|project] [--project-root <path>]

Deletes an installed pack from the chosen scope (default global). Built-in packs cannot be removed; if you try, Paqad tells you to remove the global or project override instead.

Validate a pack

paqad-ai packs validate <path>

Checks the manifest and the files it references in the folder you name. If the pack is valid, it prints its name and any warnings as JSON. If not, the command fails and lists the problems. Validation is a scripted schema check.

Create a new pack

paqad-ai packs create <name> [--destination <path>] [--ecosystem node] [--tier framework|archetype]

Writes a minimal, valid starting point in <destination>/<name>/ (the destination defaults to the current folder):

• pack.yaml with the name, a display name, version 1.0.0, detection by a package in package.json, and a pnpm toolchain.
• rules/conventions.md with a heading for your conventions.

It does not install the pack. Edit the files, run packs validate, then packs install. The archetype tier produces a template for recognising a kind of project by a manifest field rather than a single package. Custom packs explains the manifest fields.

When changes take effect

Paqad reads packs from all three places each time a command needs stack information, so there is no separate reload step. A pack applies to your project when its name matches one of the frameworks in the project's stack profile. To regenerate the stack notes with a newly installed pack, run paqad-ai refresh --stack; see refresh and update.