What resolution means
Paqad ships many rule files, skills and settings, but only some fit your project. Resolution is the step during onboarding that picks the ones that apply, based on your active capabilities, the stack packs that matched, and the traits detected. The part of Paqad that does it is called the resolver. It is a script: the same profile always gives the same selection.
Knowing the order helps you predict which rule files end up in docs/instructions/rules/, and why a file you expected might be missing.
The layers, from general to specific
The resolver reads folders inside the installed framework (~/.paqad-ai/current) in this order. Later layers are more specific.
| Order | Folder in the framework | Used when |
|---|---|---|
| 1 | base/ | Always |
| 2 | capabilities/content/ | Always (content is always on) |
| 3 | capabilities/coding/ | coding is active |
| 4 | capabilities/coding/stacks/_shared/ | coding is active |
| 5 | capabilities/coding/stacks/<pack>/ | For each matched stack pack, in a fixed order (for example laravel before react) |
| 6 | capabilities/coding/stacks/<pack>/capabilities/<trait>/ | For each detected trait of each pack, such as inertia or tailwind |
| 7 | capabilities/security/ | security is active (always together with coding) |
Inside each layer the resolver looks in a subfolder for each kind of material: rules, skills, agents, checklists, mcp, and benchmarks/patterns and benchmarks/anti-patterns. Hooks and templates are not layered; they always come from the framework's own hooks and templates folders.
What happens when two layers ship the same file
It depends on the kind of material:
- Rules, skills, agents, hooks and templates: files are matched by their path inside the layer's folder. If two layers both have, say,
testing/guide.md, only the file from the later layer is kept. - Checklists, patterns, anti-patterns and MCP server settings: nothing is replaced. Files from every layer are kept.
Files are compared by path only, not by content or by any rule ID inside them. If your project matches two stack packs that both ship a rule with the same path (Laravel and React, for example, both have conventions/guide.md), only the later pack's version is kept.
Where the selected rules land in your project
Onboarding copies each selected rule file into docs/instructions/rules/, keeping track of where it came from:
| Framework source | Copied to |
|---|---|
base/rules/testing.md | docs/instructions/rules/_shared/testing.md |
capabilities/coding/rules/code-quality.md | docs/instructions/rules/coding/code-quality.md |
capabilities/coding/stacks/laravel/rules/testing/guide.md | docs/instructions/rules/coding/stacks/laravel/testing.md |
A file named guide.md is renamed after its folder, as in the last row. Rules are the only resolved material copied into docs/instructions/. Each tool's MCP file gets the MCP servers suggested for your stack and records which MCP setting files the resolver selected.
After copying, your project's copy is what counts
There is no separate "project override" layer in the resolver. Instead, once the rules are copied, your project owns them: you can edit or delete them, and running paqad-ai onboard or paqad-ai update again does not overwrite a rule file that already exists. Framework settings (as opposed to rules) are changed in .paqad/configs/ and .paqad/.config; see Project profile.
To take in rule changes from a newer Paqad version, or after your capabilities or stack change, use the rules refresh:
# show what would be deleted and written, change nothing
paqad-ai refresh --rules
# delete the generated rule files and write fresh copies
paqad-ai refresh --rules --force--force deletes every file in docs/instructions/rules/ except module-map.yml and rule-script-map.yml, including rules you edited or wrote yourself. Commit first, then use git diff to bring back your own changes.
Stack-specific sections inside skills
Skill files (instructions for a specific task the AI can load) can hold text that only applies to one framework, wrapped like this:
<!-- if:laravel -->
Run Artisan commands through php artisan.
<!-- endif -->When a skill is loaded for your project, blocks for frameworks you do not use are removed. The name after if: must be a single word of letters, digits or underscores, so hyphenated names such as go-web do not match. This applies to skills only, not to the copied rule files.
Packs you add yourself
The layers above come from the packs shipped with Paqad. Packs you install globally or in the project affect detection; how they add material is covered in Pack precedence.