Paqad stack packs: what they are and what they control

What a stack pack is

A stack pack is a small folder that describes one framework, or one kind of project, to Paqad. Its main file is pack.yaml, a settings file written in YAML (plain text laid out as names and values). Next to it sit folders of rule files written in Markdown.

Paqad uses the packs that match your project to decide which framework rules to hand your AI coding tool, what to write into your stack documentation, how to read your test results, which files matter for a security review, and which MCP servers to list for your tools. MCP servers are helper programs an AI tool can call; they are explained on MCP servers and Paqad.

You do not have to do anything with packs for a normal setup. When you run paqad-ai onboard, Paqad detects your frameworks and picks the matching built-in packs for you.

When you need to think about packs

You want to see which packs are active in a project: run paqad-ai packs list.
Your team wants a built-in framework handled differently, for example a different test command or extra folders left out of the code search index: you can override that pack (see Creating a custom stack pack).
You are checking why a rule, test runner or MCP entry appears: the pack is usually where it came from.

Framework packs and archetype packs

There are two kinds of pack, set by the tier field:

Framework packs (the default, tier: framework) describe a framework such as Laravel, React or Django.
Archetype packs (tier: archetype) describe a project shape rather than a framework. The built-in ones cover Node.js command-line tools, libraries and long-running services that do not use a recognised framework.

The full list is on Built-in stack packs.

What is inside a pack

Every pack.yaml must contain name, display_name, ecosystem, version, description, maintainer and detection. The file is checked against a fixed schema (a formal description of which fields are allowed), and any field the schema does not know is an error. This is a shortened excerpt of the built-in Laravel pack:

name: laravel
display_name: Laravel
ecosystem: php
version: 1.0.0
description: Built-in Laravel coding stack pack
maintainer: paqad-ai
detection:
  manifests:
    - file: composer.json
      packages:
        - laravel/framework
traits:
  - name: boost
    display_name: Boost
    detect_package: laravel/boost
    description: Laravel application uses Laravel Boost
mcp_defaults:
  - name: laravel-boost
    when: when_trait
    trait: boost
test_runners:
  - runner_id: pest
    structured_format: junit-xml
    default_command: php artisan test
    output_source: file
    output_path_pattern: .paqad/test-results/pest.xml
docs:
  conventions_template: rules/conventions/guide.md

A trait is an add-on library the pack knows about, such as Tailwind or Pest. Built-in packs can carry extra rules that apply only when a trait is present, in capabilities/<trait>/rules/ inside the pack folder.

Which pack settings Paqad acts on in 1.91.1

Field	What Paqad uses it for
`name`, `display_name`, `description`, `tier`	Shown by `paqad-ai packs list` and used as headings in the generated `docs/instructions/stack/frameworks.md`. Framework packs are tried before archetype packs during detection.
`detection`, `traits`	Used by stack detection. Each matching rule counts as a signal for this pack, and the pack's traits are checked the same way. See Stack detection.
`docs.conventions_template`	The file it points to is copied into the "Pack Conventions" section of `docs/instructions/stack/frameworks.md`.
`mcp_defaults`	Which MCP servers are listed for this stack. See MCP servers added for your stack.
`test_runners`	How to run the tests and read their structured results. `paqad-ai doctor` warns when the active packs declare none.
`ast.file_extensions`, `rag`	Which files the code search index includes or skips. See RAG overview.
`pentest.file_check_map`	Which security review checks apply to which file paths.
`module_health`	Where source code lives, for the module map and module health reports.
`visual_evidence.frontend_globs`	Which changed files count as front-end work, so screenshot evidence is asked for.

The rule files in a built-in pack's rules/ folder reach your project through the rule resolver, which combines base rules, capability rules, pack rules and trait rules in a fixed order. That order is explained on Resolution order.

What a script checks and what the AI decides

Loading packs is a deterministic machine check: a script reads each pack.yaml, validates it against the schema and a set of extra checks, and sets aside any pack that fails, with a warning. The rules a pack contributes are then given to your AI tool as instructions. Whether the AI follows them, and how strictly that is enforced, depends on the host tool and how it is configured. See How it works.

Commands for working with packs

paqad-ai packs list shows the packs in effect and where each came from.
paqad-ai packs create <name> scaffolds a new pack folder.
paqad-ai packs validate <path> checks a pack folder.
paqad-ai packs install <source> and paqad-ai packs remove <name> add or remove a global or project pack.

Every option is listed on the packs command reference.

What stack packs are