Before you start
You need Node.js 22 or later and the paqad-ai command (see Installation). Commit or stash any work in progress first, so you can review exactly what onboarding adds with git status and git diff.
Step 1: run onboarding in your project folder
Open a terminal in the top folder of your project, the one that holds package.json, composer.json, go.mod or a similar file, and run:
cd your-project
paqad-ai onboardOnboarding reads your project, asks you a few questions, and then writes files. It needs no account and no API key.
Step 2: pick the AI tools you use
The first question is which AI tools to set up. Move with the arrow keys, press space to tick or untick, and press Enter. Codex, Claude Code, Gemini and Junie are ticked by default; untick any you do not use. You must keep at least one.
Each tool gets a short entry file that points to the same shared instructions. What else a tool gets depends on what that tool supports:
| Tool | --providers value | Entry file | MCP settings file | Paqad hooks |
|---|---|---|---|---|
| Claude Code | claude-code | CLAUDE.md | .claude/settings.mcp.json | In .claude/settings.json: before edits and at end of turn |
| Codex CLI | codex-cli | AGENTS.md | .codex/mcp.json | In .codex/hooks.json: before patch edits and at end of turn, once approved with /hooks |
| Gemini CLI | gemini-cli | GEMINI.md | .gemini/mcp.json | In .gemini/settings.json: end of turn only, records without blocking |
| Google Antigravity | antigravity | ANTIGRAVITY.md | .antigravity/mcp.json | None |
| Junie | junie | .junie/AGENTS.md | .junie/mcp/mcp.json | None |
| Cursor | cursor | .cursor/rules/paqad.mdc | .cursor/mcp.json | None |
| GitHub Copilot | github-copilot | .github/copilot-instructions.md | .vscode/mcp.json | None |
| Windsurf | windsurf | .windsurfrules | .windsurf/mcp.json | None |
| Continue | continue | .continue/rules/paqad.md | .continue/mcp.json | None |
| Aider | aider | CONVENTIONS.md | None | None |
| JetBrains AI Assistant | aiassistant | .aiassistant/rules/guidelines.md | None | None |
"None" under hooks means Paqad cannot stop or record anything automatically in that tool; the AI is only asked to follow the workflow. Whether a tool reads the MCP file from the path shown depends on the tool and its settings; each adapter page covers this.
Step 3: confirm the stack Paqad found
Paqad reads your manifest and lock files and shows a summary: the main stack, frameworks, extra traits such as Tailwind or Docker, package managers, and the files it used as evidence. Choose Continue, Revise selections to answer the questions again, or Abort onboarding.
If detection is not confident, Paqad asks you to choose the stack from a list and asks a few follow-up questions (for example, whether a Laravel project uses Inertia or Pest). If it finds no code framework at all, it sets the project up for writing and content work only. Stack detection explains how this works.
Step 4: decide on the optional search index
When the files are written you see an ONBOARDING COMPLETE panel. For code projects, Paqad then offers to build a local search index (RAG) so the AI gets relevant snippets of your code and documents. The highlighted answer is yes. If you accept, you choose how to build it:
- On my machine: downloads a small local embedding model (the prompt says about 80 MB) into
~/.paqad/models. No account needed. - OpenAI or Voyage AI: uses your own API key for that service.
Choose No, skip for now if you are unsure. Onboarding is already complete at this point, and a failed index build leaves RAG switched off rather than undoing anything. You can start it later with paqad-ai rag init --provider local.
What onboarding wrote into your project
| Path | What it is | In git? |
|---|---|---|
| Entry files and tool folders | One entry file per chosen tool, its MCP settings file, and small settings files for tools that use them | Yes, except hook files (below) |
.claude/settings.json, .codex/hooks.json, .gemini/settings.json | Hook settings. They contain full paths on your machine, so a nested .gitignore in each tool folder keeps them out of git | No |
docs/instructions/rules/ | Rules for your capabilities and stack, copied from Paqad. Your project owns them from now on | Yes |
docs/instructions/tools/<stack>/ | Tool guides for your stack (code projects) | Yes |
docs/instructions/workflows/ | feature-development.yaml and delivery-policy.yaml, the editable workflow settings | Yes |
.paqad/project-profile.yaml | Facts about the project: stack, capabilities, commands (see Project profile) | Yes |
.paqad/configs/ and .paqad/.config.example | Team settings files with every option listed and commented out at its default | Yes |
.paqad/framework-path.txt | The pointer the entry files follow to the installed framework | Yes |
.paqad/onboarding-manifest.json | The list of files onboarding generated and whether each may be updated automatically | Yes |
.paqad/detection-report.json, stack-snapshot.json, stack-drift.json | What detection found, and changes since the last run | No (per machine) |
.paqad/decisions/ | Storage for decision records | Partly |
.git/hooks/ | Small post-commit and post-merge hooks that link commits to Paqad's change records | No (git never tracks these) |
Onboarding does not write your stack overview, architecture notes or design-system documents. Those come from the documentation workflow in the next step.
Running paqad-ai onboard again is safe. It keeps your settings, does not overwrite the copied rules or existing entry files, and if you already had your own CLAUDE.md or AGENTS.md, it adds a clearly marked Paqad block and keeps your text.
Step 5: finish the setup inside your AI tool
- Codex CLI only: open Codex in the project, run
/hooks, and approve Paqad's hooks. Codex ignores project hooks until you trust them, and onboarding cannot do this for you. - Every tool: send your AI tool the prompt
create documentation. The AI then writes the documents underdocs/instructions/that onboarding left out, plus a module map for you to review. After reviewing the map, you can promptcreate module documentation. This step is AI work, so read what it writes.
Step 6: run the health check
paqad-ai doctordoctor prints a JSON report of named checks, each marked pass, warning or fail, with a suggested fix. It exits with code 1 only when something fails. On a fresh project some warnings are normal; for example "Indexes are current" warns until the documentation workflow has run. Diagnosing problems with doctor explains the common findings.
Step 7: review and commit
Look through git status and git diff, then commit. Paqad's .paqad/.gitignore already keeps per-machine files out, so what git shows is what the team should share.
Setting up a teammate's machine
When a teammate clones a project that is already onboarded, they should not run onboard again. After installing paqad-ai, they run:
paqad-ai joinjoin sets up the per-machine parts (the framework link, hook settings, detection files and, if the team uses it, the local search index) without changing any tracked file.
Running onboarding without questions
You can pass the answers as options. When you give the tools, the stack and its traits, onboarding skips the stack questions:
paqad-ai onboard --providers claude-code codex-cli --stack react --capability tailwindHere --capability means stack traits such as tailwind, inertia or docker, not the content, coding and security rule sets. In an interactive terminal the search-index question may still appear. When there is no interactive terminal (for example in CI), nothing is asked, only Claude Code is set up unless you pass --providers, and the search index stays off. All options are in the onboard reference.