Everything you need to install Paqad, set it up in a project and use it from day to day. Each topic has its own page and says which release it was checked against.
Where to start
New to Paqad? Read the introduction, then follow the quick start on one of your own projects.
Installing on a team machine? The installation guide covers requirements and the global install.
Choosing an AI tool?AI tool adapters explains what Paqad can and cannot enforce in each one.
Looking up a command? Start at onboard in the CLI reference.
These pages were rewritten and checked against paqad-ai 1.91.1 in September 2026. If you followed an old link such as paqad.ai/docs#installation, you have been taken to that topic's new page. If a link did not match a topic, use the list below.
Paqad is an open-source framework that detects your stack, writes shared instructions for your AI coding tools, and adds checks that run locally. How strictly it can enforce anything depends on the tool you use.
Install Node.js 22 or later, run npm install -g paqad-ai, and check it with paqad-ai --version. Nothing changes in a project until you run paqad-ai onboard there.
Run paqad-ai onboard in your project folder, pick your AI tools and confirm the detected stack. Then prompt your AI tool with create documentation, run paqad-ai doctor, and commit what git shows.
Core concepts
How Paqad reads a project and decides which rules apply.
Onboarding is a script that detects your stack, collects matching rules and writes files. In your AI tool, the entry file loads Paqad's instructions; hooks in Claude Code, Codex CLI and Gemini CLI add automatic checks.
The profile .paqad/project-profile.yaml records project facts: capabilities, detected stack and commands. Framework settings live in .paqad/configs/.config.* files, .paqad/.config and PAQAD_* variables; paqad-ai config effective shows what applies.
Stack detection is a script that reads manifest and lock files in nine ecosystems, matches them against each pack's detection rules, and records frameworks, traits and versions. No AI model is involved. Re-run it with paqad-ai refresh --stack.
The resolver picks framework files in seven layers, from base to security. For rules and skills a later layer's file replaces an earlier one with the same path. Selected rules are copied into docs/instructions/rules, where your project owns them.
CLI reference
The paqad-ai commands, their options and what they change.
Run paqad-ai onboard once in a project's root folder. It detects your stack, asks which AI tools you use, and writes each tool's entry file plus Paqad's rules and settings. Teammates use paqad-ai join instead.
paqad-ai doctor runs read-only, scripted checks on a project's Paqad files and prints a JSON report. Each check passes, warns or fails with a suggested fix. It exits with 1 only when a check fails.
paqad-ai compliance reads a Markdown feature spec, lists each requirement as an obligation, and scans your tests for references to those obligations. It is a text-matching script: it shows which requirements have tests, not whether the tests are right.
paqad-ai refresh rebuilds only the targets you name with flags, such as --stack or --rules. paqad-ai update syncs a project's framework files with the installed Paqad version; it does not install a new version.
paqad-ai packs manages stack packs, the folders that tell Paqad how to recognise and work with a stack. Packs come from three places (built-in, global, project), and the project copy wins when names clash.
paqad-ai patterns lists, prunes and exports the pattern library in ~/.paqad/patterns/, a store of past problems and working solutions shared by all projects on your machine. It does not add patterns.
paqad-ai capabilities shows or changes which rule sets a project uses: content (always on), coding (you choose), and security (follows coding). Changing them only edits the profile; run refresh --rules to rebuild rules.
paqad-ai rag builds and manages an optional search index of your project so relevant code can be placed in front of the AI. It is off by default, can run fully on your machine, and adds nothing when off.
In paqad-ai 1.91.1 the project graph is the Graph view of paqad-ai dashboard. paqad-ai graph still opens it, but it is a hidden, deprecated shortcut, and the old --threshold option and port 5371 are gone.
Stack packs
Ready-made rules and checks for the frameworks a project uses.
A stack pack is a folder with a pack.yaml file that describes one framework or project shape to Paqad. Onboarding picks matching built-in packs for you; you only need to touch packs to inspect or override them.
paqad-ai 1.91.1 ships 22 built-in packs: 19 framework packs, from Angular to Vue, and 3 archetype packs for Node.js command-line tools, libraries and services. Onboarding selects the ones that match your project.
In 1.91.1 a custom pack only takes effect when its name matches a built-in pack, and then it replaces that pack.yaml. Scaffold with paqad-ai packs create, check with packs validate, install with packs install.
Paqad reads built-in packs, then global packs in ~/.paqad/packs/, then project packs in .paqad/packs/. For packs with the same name, the last valid one replaces the others completely. Rule files and MCP defaults follow different rules.
AI tool adapters
What Paqad sets up in each AI coding tool, and how much it can enforce there.
Paqad has eleven adapters. On Claude Code and Codex CLI its hooks can block edits and check the result; on Gemini CLI it records at the end; on every other tool it only gives the AI instructions, which nothing forces it to follow.
Claude Code is one of two tools where Paqad can block certain edits before they happen and check the change when the AI finishes. Onboarding writes CLAUDE.md and adds Paqad hooks to .claude/settings.json.
In Cursor, Paqad is advisory. Onboarding writes a rule file, .cursor/rules/paqad.mdc, that tells the AI how to load your rules, but no Paqad program runs and nothing stops the AI ignoring it.
For GitHub Copilot, Paqad is advisory. Onboarding writes .github/copilot-instructions.md pointing the AI at your rules and workflows, but nothing makes Copilot follow it and no Paqad program runs.
In Windsurf, Paqad is advisory. Onboarding writes .windsurfrules telling Cascade how to load your rules and workflows, but no Paqad program runs and nothing stops the AI ignoring the file.
For Continue, Paqad is advisory. Onboarding writes one rule file, .continue/rules/paqad.md, telling the AI how to load your rules, but no Paqad program runs and nothing stops the AI ignoring it.
Codex CLI gets the same enforcement as Claude Code: Paqad hooks can block certain changes and check the result at the end of each turn. You must approve the hooks in Codex with /hooks before they run.
With Gemini CLI, Paqad records stage evidence and a verification result when the AI finishes each turn. It cannot block edits and shows no verdict in the chat; the result is only in the ledger.
For Google Antigravity, Paqad is advisory. Onboarding writes ANTIGRAVITY.md with instructions for the AI. It also writes .antigravity/hooks.json, but that is only a list; Antigravity never runs it.
For Junie, Paqad is advisory: onboarding writes .junie/AGENTS.md, but nothing makes Junie follow it. In a JetBrains IDE, only the Claude Code plugin runs Paqad hooks that can block edits.
For Aider, Paqad is advisory. Onboarding writes CONVENTIONS.md, which Aider only reads when you name it, and by default turns off Aider’s commit attribution in .aider.conf.yml. Nothing makes Aider follow the rules.
Workflow engine
How a request is routed and carried through defined stages.
Every message is routed to one of eleven outcomes. Code changes follow eight stages in a fixed order, scripts check and record each stage, the AI does the work, and you answer decision pauses. Enforcement strength depends on your AI tool.
feature-development.yaml tunes each built-in stage with reading lists, instructions, strictness, escalation and check commands. Your entries are appended to paqad's defaults and strictness can only tighten. Custom workflow templates exist but only run through the programmatic engine.
The AI picks a route by intent while, on Claude Code and Codex CLI, a script records the route and a lane. Lanes follow fixed rules on complexity and risk; sensitive modules and unknown lanes are always held to full.
On graduated and full lanes, Claude Code and Codex CLI run each mandatory stage in its own subagent while the main chat coordinates. Separately, 25 role files give the AI narrow points of view, and eleven of them can act as spec experts.
Context and search
How Paqad finds the right project knowledge for a task.
Paqad uses scripts to decide which rules and project facts go into the AI's working memory for each request, prepares them in a small context file, and injects it on hosts with a prompt hook. Retrieval is an optional extra.
Retrieval is an optional, off-by-default search over your project. It indexes eligible files locally, finds a few relevant passages per request, and adds them to the AI's context as hints. The default embedding model runs on your machine.
Adaptive depth is a script rule that picks one of three search widths for each retrieval: none, standard (rag_top_n, default 20) or deep (three times that). In 1.91.1 the background refresh picks depth from how many modules the change touches.
Reranking is a second sorting pass that reads the query and each passage together. The code exists in paqad-ai 1.91.1 with local, Cohere and passthrough backends, but it is off by default and no supported setting switches it on.
In paqad-ai 1.91.1 you narrow retrieval by editing .paqad/rag.ignore.yaml, which decides what gets indexed. Delivery to the AI is fixed to documentation passages, and the metadata filter component is not used on the live path.
Action routing suggests workflows by matching workflow-name keywords against retrieved passages, and every suggestion needs your approval. In paqad-ai 1.91.1 it is off, cannot be switched on through settings, and no command or hook calls it.
Questions about your project go to the project-question workflow, where the AI checks docs first, then code, and changes nothing. A separate structured answer builder with grounding labels and citations ships as a library API; in 1.91.1 nothing calls it automatically.
Security
Security workflows and guardrails, and the limits of what they show.
Paqad's security review runs when you ask for it. It reviews code, runs helper scripts and writes a playbook of test commands for you to run against a local copy. It is a self-review, not proof of security, and it blocks nothing.
The pentest workflow is a resumable, WSTG-structured self-review your AI tool runs on request. The AI reviews code in a fixed order, helper scripts gather evidence, and it writes a report with stable finding IDs plus a playbook for you to run. Findings block nothing.
Paqad's security skills reference OWASP WSTG test IDs, the OWASP Top 10 2025 and the API Security Top 10 2023 so the review looks in known places. The mapping shows where the review looks. It is not proof of security or compliance.
Paqad's guardrails are hook scripts. On Claude Code and Codex CLI they can block file edits until conditions are met and verify at turn end; other tools get instructions only. Shell commands, commits and migrations are not guarded, and the escalation settings are not read.
Patterns library
Recording and reusing solutions that worked in a project.
The pattern library is a per-machine store of past solutions in ~/.paqad/patterns/, shared by all your projects and never committed. In 1.91.1 you can list, prune and export it, but nothing adds patterns automatically.
In 1.91.1 nothing records patterns: there is no patterns record command and no end-of-task prompt. A PatternRecorder class exists in the package's JavaScript interface for developers, and patterns export is the only way to share.
Each pattern scores 0.25 for framework match, 0.35 for keyword match and 0.40 for semantic similarity when RAG is on, minus 0.15 if older than 180 days. Scores under 0.3 are dropped and the top 3 kept. No command calls this in 1.91.1.
Health and maintenance
Diagnosing problems and keeping generated files current.
paqad-ai doctor is a read-only script that checks Paqad's files and settings and prints a JSON report with a suggested fix per problem. It exits with 1 only when a check fails; some warnings are normal on a new project.
paqad-ai checks run reads your test runner's output in a declared format, such as TAP, JUnit XML or Jest JSON, and turns it into one fixed-shape record. Verification checks fail on failed tests and report inconclusive when output could not be read.
Choose the command by what changed: refresh --stack for dependencies, update for a new Paqad version, refresh --rules for rule copies, refresh --providers for entry files, and create documentation for written docs. A plain refresh does nothing.
Paqad compares your current packages with the last stack snapshot, your rules with their compiled copy, and your module map with your source folders. Each comparison is a script; results go to .paqad files or doctor, and you decide what to update.
MCP integration
Connecting AI tools to extra capabilities through the Model Context Protocol.
MCP (Model Context Protocol) lets an AI tool call helper programs called MCP servers. Paqad writes a list of recommended servers for your stack into a JSON file per host tool. It never installs, starts or contacts a server, and sends no data.
Paqad knows eight MCP server names. It lists figma for every detected framework and database-inspector for Laravel and Flutter; packs add the rest. There are no file, git or shell servers. Change the list in the mcp section of the project profile.
Each stack pack can name MCP servers in mcp_defaults, always or only when a trait such as Tailwind or Prisma is detected. This page lists the result for all 22 built-in packs. Paqad writes names only and sends nothing.
Continuity comes from the change's evidence bundle and per-session routing state, not from a summary document. On Claude Code and Codex CLI a new session links to the single unfinished change on its branch; otherwise run paqad-ai resume --feature.
Skills are written procedures in SKILL.md folders inside the framework install; the AI runs them when a stage or workflow names them. A result cache exists for cacheable skills, but in 1.91.1 ordinary sessions rarely use it and nothing needs warming.
Planning is the first mandatory stage. The AI writes a plan with a required reuse section, paqad-ai plan compile checks it and stores plan.json in the evidence bundle, and on Claude Code and Codex CLI code edits stay blocked until that record exists.
The AI writes a JSON plan template; paqad-ai plan compile validates it, adds identity and a content hash, and stores plan.json in the evidence bundle. The reuse section is required. Acceptance criteria now live in the frozen spec.
After planning, the AI writes a spec (by hand or through the optional spec pipeline), paqad-ai spec freeze checks it and stores specification.json, and paqad-ai rules load records the applicable rules. Hook-capable tools block code edits until these records exist.
A deterministic classifier in the prompt hook labels each request in three stages: read the request and project, fill in complexity and risk from keyword rules, then adjust from module health and defect history. No AI model is called.
Each module gets a local JSON health profile with coverage, defect count, stability and change rate. A fixed rule turns these into a tier, and a fragile module raises the risk of any request that touches it. All of it is computed by scripts.
