Paqad works in two places. The paqad-ai command runs scripts on your machine that prepare and check the project. Inside your AI tool, Paqad's instructions and, where the tool allows it, hooks guide and check the AI while it works. This page follows both in order. For a shorter overview, see the How it works page.

Onboarding, part 1: detect the stack

When you run paqad-ai onboard, a script reads the manifest and lock files in your project, for example package.json with pnpm-lock.yaml, or composer.json with composer.lock. It records the installed packages and their versions, matches them against the detection rules in each built-in pack (a folder that describes one framework), and notes traits such as Tailwind, Docker or Pest. No AI model is involved, so the same files always give the same result. Stack detection has the details.

Onboarding, part 2: collect the rules and settings that apply

Next, a step called the resolver gathers the material that fits your project from the framework's files, in layers: general material first, then the content, coding and security rule sets, then material for your stack and its traits. When two layers ship a file with the same name, the more specific one wins. Resolution order lists the layers.

Onboarding, part 3: write the files

Paqad then writes:

the rules into docs/instructions/rules/, where your project owns and can edit them;
an entry file for each AI tool you chose, such as CLAUDE.md or AGENTS.md, plus its MCP settings and, for Claude Code, Codex CLI and Gemini CLI, its hook settings;
the project profile .paqad/project-profile.yaml and the team settings files in .paqad/configs/;
a pointer, .paqad/framework-path.txt, that leads to the installed framework at ~/.paqad-ai/current.

Onboarding can be run again. Files the project owns, such as the copied rules and existing entry files, are not overwritten. Files Paqad manages, such as MCP and hook settings, are regenerated. The Quick start lists every file.

In your AI tool: how a session loads Paqad

From here on, the work happens in your AI tool, and the AI follows written instructions:

The tool reads its entry file. Paqad's entry file tells the AI to open .paqad/framework-path.txt and load the framework file it points to, AGENT-BOOTSTRAP.md.
The bootstrap checks one thing: is Paqad switched on for this project? The paqad_enable setting and the PAQAD_DISABLED environment variable control this. If Paqad is off, the AI works as a normal assistant.
If Paqad is on, the AI loads AGENT-ROUTER.md. This tells it to sort each message into one of eleven workflows, such as feature development, a project question, documentation, or a security test, and to load only what that workflow needs.
For a code change, the feature-development workflow runs its stages in order: planning, specification, development, review, checks, and documentation sync, with an optional ticket intake at the start and delivery at the end.

Routing a message and writing plans, specifications and reviews are AI judgement. Paqad cannot guarantee that an AI follows instructions; that is what the hooks and checks below are for.

What checks the AI, and in which tools

Hooks are small programs an AI tool runs at fixed moments. Paqad installs them only where the tool supports them:

Tool	Before an edit	When the AI finishes a turn
Claude Code	Can block the edit, for example until the framework has been loaded or while a decision is waiting for you	Records evidence and runs the completion check
Codex CLI	Same as Claude Code, for edits made through its patch tool, after you approve the hooks with `/hooks`	Same as Claude Code
Gemini CLI	Nothing	Records evidence and runs the check without blocking
All other supported tools	Nothing	Nothing; the AI is asked to run Paqad's commands itself

Hooks only run if your tool is configured to run them. See the adapters overview for each tool.

Checks that are scripts, not AI

Several parts of Paqad give the same answer every time for the same files, whatever the AI claims:

paqad-ai checks run runs your project's format, test and build commands and decides pass or fail from their exit codes and parsed test results (see Structured test output).
paqad-ai doctor checks that Paqad's own files and settings are present and valid (see Diagnosing problems with doctor).
Detection compares your current packages with the last recorded snapshot and reports changes (see Drift detection).

Keeping it current over time

When your project changes, targeted commands bring Paqad's files back in line: paqad-ai refresh --stack after dependency changes, paqad-ai update after a new Paqad version, and the create documentation workflow for the written documentation. Keeping Paqad's files current explains which to use when.

How Paqad works