paqad-ai 0.1.6 β 0.1.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +351 -251
- package/dist/cli/index.js +1 -1
- package/dist/cli/index.js.map +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,352 +1,452 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
1
|
+
```
|
|
2
|
+
βββββββ ββββββ βββββββ ββββββ βββββββ
|
|
3
|
+
βββββββββββββββββββββββββββββββββββββββββ
|
|
4
|
+
βββββββββββββββββββ ββββββββββββββ βββ
|
|
5
|
+
βββββββ βββββββββββββ ββββββββββββββ βββ
|
|
6
|
+
βββ βββ βββββββββββββββ βββββββββββ
|
|
7
|
+
βββ βββ βββ βββββββ βββ ββββββββββ
|
|
8
|
+
```
|
|
6
9
|
|
|
7
|
-
|
|
10
|
+
**AI agents that think before they type.** paqad-ai reads your codebase, detects your stack, and generates everything your AI coding agents need to actually understand your project β docs, rules, security checks, MCP configs, and structured workflows. One command. No configuration.
|
|
8
11
|
|
|
9
|
-
|
|
12
|
+
[](https://npmjs.com/package/paqad-ai) [](./LICENSE)
|
|
10
13
|
|
|
11
|
-
|
|
12
|
-
- keep architecture and rules visible to coding agents
|
|
13
|
-
- generate structured documentation instead of ad hoc notes
|
|
14
|
-
- wire stack-aware MCP defaults into supported adapters
|
|
15
|
-
- run health and refresh flows safely over framework-managed artifacts
|
|
14
|
+
---
|
|
16
15
|
|
|
17
|
-
##
|
|
16
|
+
## The problem
|
|
18
17
|
|
|
19
|
-
|
|
20
|
-
| -------------- | ------------ | ------------------------------------------------------------------ |
|
|
21
|
-
| Claude Code | β
Supported | Generates `CLAUDE.md` plus MCP config |
|
|
22
|
-
| Codex CLI | β
Supported | Generates `AGENTS.md` plus MCP config |
|
|
23
|
-
| Gemini CLI | β
Supported | Generates `GEMINI.md` plus MCP config |
|
|
24
|
-
| Junie | β
Supported | Limited to `.junie/AGENTS.md` and `.junie/mcp/mcp.json` |
|
|
25
|
-
| Cursor | β
Supported | Generates `.cursor/rules/paqad.mdc` plus MCP, skills, and agents |
|
|
26
|
-
| GitHub Copilot | β
Supported | Generates `.github/copilot-instructions.md` and `.vscode/mcp.json` |
|
|
27
|
-
| Windsurf | β
Supported | Generates `.windsurfrules` plus MCP, skills, and agents |
|
|
28
|
-
| Continue | β
Supported | Generates `.continue/rules/paqad.md` plus MCP and prompts |
|
|
29
|
-
| Aider | β
Supported | Config-only β generates `CONVENTIONS.md` |
|
|
18
|
+
You install an AI coding agent. You ask it to help with your Laravel + React project. It doesn't know your folder structure, conventions, test runner, or which version of anything you're running.
|
|
30
19
|
|
|
31
|
-
|
|
20
|
+
So you spend an hour writing `CLAUDE.md` by hand. Then you do it again for Cursor. And again for Copilot. And again when your stack changes.
|
|
32
21
|
|
|
33
|
-
|
|
22
|
+
**paqad-ai does all of this automatically β for 9 agents at once.**
|
|
34
23
|
|
|
35
|
-
|
|
36
|
-
| ----------- | --------------------------- |
|
|
37
|
-
| Node.js | `25+` |
|
|
38
|
-
| pnpm | `10+` for local development |
|
|
24
|
+
---
|
|
39
25
|
|
|
40
|
-
|
|
26
|
+
## Get started
|
|
41
27
|
|
|
42
28
|
```bash
|
|
43
29
|
npm install -g paqad-ai
|
|
30
|
+
cd your-project
|
|
31
|
+
paqad-ai onboard
|
|
44
32
|
```
|
|
45
33
|
|
|
46
|
-
|
|
34
|
+
paqad-ai reads your lockfiles, detects your stack, asks you to confirm, and generates everything:
|
|
47
35
|
|
|
48
|
-
```
|
|
49
|
-
|
|
36
|
+
```
|
|
37
|
+
β Detected: laravel + react (inertia, tailwind, pest, docker)
|
|
38
|
+
β Generated: CLAUDE.md, AGENTS.md, GEMINI.md, .cursor/rules/paqad.mdc
|
|
39
|
+
β Generated: .github/copilot-instructions.md, .windsurfrules
|
|
40
|
+
β Generated: docs/instructions/stack/* (6 files)
|
|
41
|
+
β Generated: docs/instructions/rules/*
|
|
42
|
+
β Configured: MCP servers (figma, laravel-boost, tailwind-mcp)
|
|
43
|
+
|
|
44
|
+
Ready. Your AI agents now understand your project.
|
|
50
45
|
```
|
|
51
46
|
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
### 1. Onboard a repository
|
|
47
|
+
Or run with `npx` without installing:
|
|
55
48
|
|
|
56
49
|
```bash
|
|
57
|
-
paqad-ai onboard
|
|
50
|
+
npx paqad-ai onboard
|
|
58
51
|
```
|
|
59
52
|
|
|
60
|
-
|
|
53
|
+
---
|
|
61
54
|
|
|
62
|
-
|
|
63
|
-
paqad-ai doctor --project-root .
|
|
64
|
-
```
|
|
55
|
+
## 9 supported agents
|
|
65
56
|
|
|
66
|
-
|
|
57
|
+
One onboarding. Every major AI coding agent. Thin entry files that all point to the same shared instruction bundles:
|
|
67
58
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
59
|
+
| Agent | What it generates |
|
|
60
|
+
| ------------------ | ------------------------------------------------------ |
|
|
61
|
+
| **Claude Code** | `CLAUDE.md` + MCP config |
|
|
62
|
+
| **Codex CLI** | `AGENTS.md` + MCP config |
|
|
63
|
+
| **Gemini CLI** | `GEMINI.md` + MCP config |
|
|
64
|
+
| **Junie** | `.junie/AGENTS.md` + `.junie/mcp/mcp.json` |
|
|
65
|
+
| **Cursor** | `.cursor/rules/paqad.mdc` + MCP, skills, agents |
|
|
66
|
+
| **GitHub Copilot** | `.github/copilot-instructions.md` + `.vscode/mcp.json` |
|
|
67
|
+
| **Windsurf** | `.windsurfrules` + MCP, skills, agents |
|
|
68
|
+
| **Continue** | `.continue/rules/paqad.md` + MCP, prompts |
|
|
69
|
+
| **Aider** | `CONVENTIONS.md` (config-only) |
|
|
71
70
|
|
|
72
|
-
|
|
71
|
+
Pick one or pick all β `paqad-ai onboard` lets you multi-select. If no `--providers` flag is passed, onboarding defaults to `claude-code`.
|
|
73
72
|
|
|
74
|
-
|
|
73
|
+
---
|
|
75
74
|
|
|
76
|
-
|
|
77
|
-
- framework-managed state under `.paqad/`
|
|
78
|
-
- copied instruction bundles under `docs/instructions/rules/` and `docs/instructions/tools/`
|
|
79
|
-
- stack snapshot docs under `docs/instructions/stack/`
|
|
80
|
-
- architecture and module documentation under `docs/instructions/` and `docs/modules/`
|
|
81
|
-
- adapter-specific MCP configuration
|
|
75
|
+
## 17 built-in Stack Packs
|
|
82
76
|
|
|
83
|
-
|
|
77
|
+
paqad-ai parses **26 manifest and lockfile formats** across 9 ecosystems. It doesn't ask what stack you use β it reads your lockfiles to figure it out.
|
|
84
78
|
|
|
85
|
-
|
|
79
|
+
**14 framework packs:**
|
|
86
80
|
|
|
87
|
-
|
|
81
|
+
`laravel` Β· `react` Β· `vue` Β· `flutter` Β· `django` Β· `fastapi` Β· `rails` Β· `spring-boot` Β· `express` Β· `angular` Β· `svelte` Β· `astro` Β· `go-web` Β· `rust-web`
|
|
88
82
|
|
|
89
|
-
|
|
90
|
-
2. re-check the live app from manifests, lockfiles, and stack signals
|
|
91
|
-
3. update effective stack context if reality differs from stored onboarding data
|
|
92
|
-
4. generate stack, architecture, and design-system docs first
|
|
93
|
-
5. generate the remaining global instruction docs
|
|
94
|
-
6. generate module docs, including `business.md` and `technical.md`
|
|
95
|
-
7. track progress in `.paqad/doc-progress.json`
|
|
83
|
+
**3 archetype packs** (fallback for Node projects that don't match a framework):
|
|
96
84
|
|
|
97
|
-
|
|
85
|
+
`node-cli` Β· `node-library` Β· `node-service`
|
|
98
86
|
|
|
99
|
-
|
|
87
|
+
Each pack is a declarative `pack.yaml` that drives detection, documentation, MCP configuration, security mappings, and more. Don't see your framework? [Author your own pack](./docs/framework/authoring-stack-packs.md).
|
|
100
88
|
|
|
101
|
-
|
|
89
|
+
**What it reads:**
|
|
102
90
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
91
|
+
| Ecosystem | Manifests & lockfiles |
|
|
92
|
+
| ---------- | ----------------------------------------------------------------------------------------- |
|
|
93
|
+
| **Node** | `package.json`, `package-lock.json`, `pnpm-lock.yaml` |
|
|
94
|
+
| **PHP** | `composer.json`, `composer.lock` |
|
|
95
|
+
| **Python** | `requirements.txt`, `pyproject.toml`, `Pipfile`, `Pipfile.lock`, `poetry.lock`, `uv.lock` |
|
|
96
|
+
| **Ruby** | `Gemfile`, `Gemfile.lock` |
|
|
97
|
+
| **JVM** | `build.gradle`, `build.gradle.kts`, `pom.xml`, `gradle.lockfile` |
|
|
98
|
+
| **Go** | `go.mod`, `go.sum` |
|
|
99
|
+
| **Rust** | `Cargo.toml`, `Cargo.lock` |
|
|
100
|
+
| **Dart** | `pubspec.yaml`, `pubspec.lock` |
|
|
106
101
|
|
|
107
|
-
|
|
102
|
+
Lockfiles always win over manifest constraints. Traits like `inertia`, `tailwind`, `pest`, `docker`, and `sail` are detected automatically from packages and config files.
|
|
108
103
|
|
|
109
|
-
|
|
104
|
+
**Stack + capability matrix:**
|
|
110
105
|
|
|
111
|
-
|
|
106
|
+
| Stack | Available traits |
|
|
107
|
+
| --------------- | ------------------------------------------------- |
|
|
108
|
+
| **Laravel** | `inertia`, `react`, `vue`, `tailwind`, `boost` |
|
|
109
|
+
| **React** | `next`, `remix`, `vite-spa`, `gatsby`, `tailwind` |
|
|
110
|
+
| **Vue** | `nuxt`, `vite-spa`, `quasar`, `tailwind` |
|
|
111
|
+
| **Flutter** | `docker`, `compose` |
|
|
112
|
+
| **Django** | `docker`, `compose` |
|
|
113
|
+
| **FastAPI** | `docker`, `compose` |
|
|
114
|
+
| **Rails** | `docker`, `compose` |
|
|
115
|
+
| **Spring Boot** | `docker`, `compose` |
|
|
116
|
+
| **Express** | `docker`, `compose` |
|
|
117
|
+
| **Angular** | `docker`, `compose` |
|
|
118
|
+
| **Svelte** | `docker`, `compose` |
|
|
119
|
+
| **Astro** | `docker`, `compose` |
|
|
120
|
+
| **Go Web** | `docker`, `compose` |
|
|
121
|
+
| **Rust Web** | `docker`, `compose` |
|
|
112
122
|
|
|
113
|
-
|
|
123
|
+
Laravel also detects `pest`, `phpunit`, `sail`, `docker`, and `compose` automatically. Environment traits like Docker and Compose are detected across all stacks.
|
|
114
124
|
|
|
115
|
-
|
|
116
|
-
paqad-ai install --project-root .
|
|
117
|
-
```
|
|
125
|
+
---
|
|
118
126
|
|
|
119
|
-
|
|
127
|
+
## What you get after onboarding
|
|
120
128
|
|
|
121
|
-
-
|
|
129
|
+
paqad-ai isn't just a setup tool. Here's the full feature set:
|
|
122
130
|
|
|
123
|
-
|
|
131
|
+
### Documentation as a first-class output
|
|
124
132
|
|
|
125
|
-
|
|
126
|
-
- writes framework version metadata for the target project
|
|
127
|
-
- prints a JSON result with `framework_home`, `project_root`, and `version`
|
|
133
|
+
Docs aren't an afterthought β they're a primary framework output. There's no standalone `document` command. Instead, ask any connected agent to `create documentation` and the workflow:
|
|
128
134
|
|
|
129
|
-
|
|
135
|
+
1. Re-reads your live app state from manifests and lockfiles
|
|
136
|
+
2. Syncs if reality differs from stored onboarding data
|
|
137
|
+
3. Generates stack docs, architecture docs, design-system docs
|
|
138
|
+
4. Generates module docs β `business.md` + `technical.md` per feature
|
|
139
|
+
5. Tracks progress in `.paqad/doc-progress.json`
|
|
130
140
|
|
|
131
|
-
|
|
141
|
+
**Differential refresh** β when files change, only stale docs are regenerated.
|
|
132
142
|
|
|
133
|
-
|
|
134
|
-
|
|
143
|
+
### Security β "Break locally first"
|
|
144
|
+
|
|
145
|
+
A resumable 5-step pentest workflow with **12 security skills** and full OWASP coverage:
|
|
146
|
+
|
|
147
|
+
| Standard | Coverage |
|
|
148
|
+
| --------------------------- | ------------ |
|
|
149
|
+
| **OWASP Top 10 2025** | A01βA10 β |
|
|
150
|
+
| **OWASP API Security 2023** | API1βAPI10 β |
|
|
151
|
+
|
|
152
|
+
**The 12 skills:**
|
|
153
|
+
|
|
154
|
+
| Skill | What it checks |
|
|
155
|
+
| ----------------------------- | --------------------------------------------------------------------------------------- |
|
|
156
|
+
| `dependency-advisory-triage` | Supply chain: typosquatting, dependency confusion, abandoned packages, transitive risk |
|
|
157
|
+
| `permission-boundary-review` | BOLA, function-level auth, mass assignment, resource consumption |
|
|
158
|
+
| `business-logic-abuse-review` | Race conditions, workflow bypass, financial manipulation, GraphQL abuse |
|
|
159
|
+
| `runtime-surface-probing` | Headers, CORS, error disclosure, open redirects, sensitive files, SSRF, TLS |
|
|
160
|
+
| `stride-threat-model` | Systematic STRIDE enumeration per module and surface type |
|
|
161
|
+
| `input-validation-review` | SSRF, IDOR, injection (SQL, template, command), file upload, prototype pollution, ReDoS |
|
|
162
|
+
| `auth-mechanism-review` | JWT flaws, session fixation, OAuth/OIDC, brute-force, MFA bypass |
|
|
163
|
+
| `cryptographic-review` | Encryption at rest/transit, key management, password hashing, weak PRNG |
|
|
164
|
+
| `logging-monitoring-review` | Audit trail gaps, log injection, alerting coverage |
|
|
165
|
+
| `rate-limiting-review` | Missing throttling per framework, DoS surfaces |
|
|
166
|
+
| `finding-normalizer` | Stable PT-XXXX IDs across retests |
|
|
167
|
+
| `retest-verification` | Finding replay against fresh evidence |
|
|
168
|
+
|
|
169
|
+
**Local attack playbook** β generates `curl` commands to prove findings locally. Never auto-executes.
|
|
170
|
+
|
|
171
|
+
**Incremental mode** β only re-scans changed files. Full scan staleness warning after 14 days.
|
|
172
|
+
|
|
173
|
+
### Context intelligence
|
|
174
|
+
|
|
175
|
+
Your AI agent has a limited context window. paqad-ai makes every token count:
|
|
176
|
+
|
|
177
|
+
| System | What it does |
|
|
178
|
+
| -------------------- | -------------------------------------------------------------------------------------------- |
|
|
179
|
+
| **Semantic loader** | Chunks files at AST boundaries, scores by 5-signal relevance, packs into 40/45/15% budget |
|
|
180
|
+
| **Budget optimizer** | 4 graduated tiers (green β yellow β amber β red), auto eviction + summarization |
|
|
181
|
+
| **Deduplication** | Identical artifacts from multiple paths β one-line reference pointers |
|
|
182
|
+
| **Turn summarizer** | Old turns β structured extracts (decisions, files, blockers, next steps). No LLM, pure regex |
|
|
183
|
+
| **Stream truncator** | Per-tier output limits (fast: 2K, medium: 5K, reasoning: 15K) with sentence-boundary cuts |
|
|
184
|
+
|
|
185
|
+
### Smart session handoff
|
|
186
|
+
|
|
187
|
+
Structured v2 handoff captures active task, decisions, files, blockers, and next steps. **70β85% smaller** than raw dumps. Both JSON and Markdown.
|
|
188
|
+
|
|
189
|
+
### Predictive skill cache
|
|
190
|
+
|
|
191
|
+
Learns skill execution sequences. Pre-warms cache when `P(next | current) β₯ 0.7`. Disabled by default β transition data accumulates passively.
|
|
192
|
+
|
|
193
|
+
### Custom workflows
|
|
194
|
+
|
|
195
|
+
```yaml
|
|
196
|
+
# docs/instructions/workflows/feature-with-review.yaml
|
|
197
|
+
name: feature-with-review
|
|
198
|
+
triggers:
|
|
199
|
+
workflow: [feature]
|
|
200
|
+
complexity: [medium, high]
|
|
201
|
+
steps:
|
|
202
|
+
- skill: scope-check
|
|
203
|
+
- skill: spec-diff
|
|
204
|
+
condition: { complexity: [medium, high] }
|
|
205
|
+
- parallel:
|
|
206
|
+
- skill: implementation
|
|
207
|
+
- skill: test-writer
|
|
208
|
+
- skill: adversarial-review
|
|
209
|
+
condition: { risk: [medium, high] }
|
|
210
|
+
- skill: diff-doc-sync
|
|
135
211
|
```
|
|
136
212
|
|
|
137
|
-
|
|
213
|
+
Conditional steps, parallel execution, failure handling (`abort` / `skip` / `retry`), resumable runs.
|
|
138
214
|
|
|
139
|
-
|
|
215
|
+
### Cross-project pattern library
|
|
140
216
|
|
|
141
|
-
|
|
142
|
-
2. **Manifest-driven stack scan** β `composer.json`, `package.json`, lockfiles, and supported config files are scanned first.
|
|
143
|
-
3. **Stack confirmation checkpoint** β the detected effective stack profile is shown and must be confirmed before onboarding continues in interactive mode.
|
|
144
|
-
4. **Fallback stack details** β only shown when detection is missing, ambiguous, or the user chooses to revise. Laravel asks for Inertia, Frontend (None / React.js / Vue.js), Tailwind, Boost, plus Docker/Compose. React asks for app type, Tailwind, and Docker/Compose. Vue asks for app type, Tailwind, and Docker/Compose. Other coding stacks ask for Docker/Compose when supported.
|
|
217
|
+
Verified solutions stored globally at `~/.paqad/patterns/`. Scored by framework overlap + keyword match, staleness penalty after 180 days.
|
|
145
218
|
|
|
146
|
-
|
|
219
|
+
---
|
|
147
220
|
|
|
148
|
-
|
|
149
|
-
# Laravel with React and Tailwind, Claude Code only
|
|
150
|
-
paqad-ai onboard --project-root . --stack laravel --capability react tailwind --providers claude-code
|
|
221
|
+
## The capability model
|
|
151
222
|
|
|
152
|
-
|
|
153
|
-
|
|
223
|
+
| Capability | What it enables | When it activates |
|
|
224
|
+
| ---------- | --------------------------------------------------------------- | --------------------------- |
|
|
225
|
+
| `content` | Writing rules, content skills, doc workflows | Always on |
|
|
226
|
+
| `coding` | Stack detection, resolver, MCP config, implementation workflows | When a pack matches |
|
|
227
|
+
| `security` | 12 security skills, pentest workflow, finding tracking | Automatically with `coding` |
|
|
154
228
|
|
|
155
|
-
|
|
156
|
-
paqad-ai onboard --project-root . --stack react --capability next tailwind
|
|
229
|
+
No framework match? Content-only setup. Node projects without a framework match get archetype packs (`node-cli`, `node-library`, `node-service`) with full `coding` + `security`.
|
|
157
230
|
|
|
158
|
-
|
|
159
|
-
paqad-ai onboard --project-root . --stack laravel
|
|
231
|
+
---
|
|
160
232
|
|
|
161
|
-
|
|
162
|
-
paqad-ai onboard --project-root . --stack laravel --providers cursor
|
|
233
|
+
## CLI reference
|
|
163
234
|
|
|
164
|
-
|
|
165
|
-
|
|
235
|
+
### `paqad-ai install`
|
|
236
|
+
|
|
237
|
+
Bootstraps the framework into a project and writes framework metadata.
|
|
238
|
+
|
|
239
|
+
```bash
|
|
240
|
+
paqad-ai install --project-root .
|
|
166
241
|
```
|
|
167
242
|
|
|
168
|
-
###
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
- `--stack <stack>`: fallback/manual override for the target stack. Values: `laravel`, `flutter`, `react`, `vue`, `django`, `fastapi`, `rails`, `spring-boot`, `express`, `angular`, `svelte`, `astro`, `go-web`, `rust-web`, `short-video`.
|
|
172
|
-
- `--capability <capability...>`: fallback/manual trait override β `inertia`, `react`, `vue`, `tailwind`, `boost`, `next`, `remix`, `vite-spa`, `gatsby`, `nuxt`, `quasar`, `docker`, `compose`, `sail`, `pest`, `phpunit`.
|
|
173
|
-
- `--providers <provider...>`: one or more providers β `codex-cli`, `claude-code`, `gemini-cli`, `junie`, `cursor`, `github-copilot`, `windsurf`, `continue`, `aider`.
|
|
174
|
-
|
|
175
|
-
### Stack capability matrix
|
|
176
|
-
|
|
177
|
-
| Stack | Capabilities |
|
|
178
|
-
| ----------- | ------------------------------------------------- |
|
|
179
|
-
| Laravel | `inertia`, `react`, `vue`, `tailwind`, `boost` |
|
|
180
|
-
| Flutter | `docker`, `compose` |
|
|
181
|
-
| React | `next`, `remix`, `vite-spa`, `gatsby`, `tailwind` |
|
|
182
|
-
| Vue | `nuxt`, `vite-spa`, `quasar`, `tailwind` |
|
|
183
|
-
| Django | `docker`, `compose` |
|
|
184
|
-
| FastAPI | `docker`, `compose` |
|
|
185
|
-
| Rails | `docker`, `compose` |
|
|
186
|
-
| Spring Boot | `docker`, `compose` |
|
|
187
|
-
| Express | `docker`, `compose` |
|
|
188
|
-
| Angular | `docker`, `compose` |
|
|
189
|
-
| Svelte | `docker`, `compose` |
|
|
190
|
-
| Astro | `docker`, `compose` |
|
|
191
|
-
| Go Web | `docker`, `compose` |
|
|
192
|
-
| Rust Web | `docker`, `compose` |
|
|
193
|
-
|
|
194
|
-
### Notes
|
|
195
|
-
|
|
196
|
-
- `react` and `vue` are mutually exclusive. Select only one frontend framework.
|
|
197
|
-
- Standalone React and Vue projects are supported directly; Laravel continues to use `react` and `vue` as capabilities when paired with backend-driven frontend code.
|
|
198
|
-
- Node.js CLI tools, libraries, and services that don't match a framework pack are detected via archetype packs (`node-cli`, `node-library`, `node-service`) and onboard with `coding` and `security` capabilities.
|
|
199
|
-
- Empty or content-only repositories onboard without a domain prompt and persist `active_capabilities: [content]`.
|
|
200
|
-
- Standalone React/Vue onboarding copies the selected sub-stack rule bundle, so `next`, `remix`, `vite-spa`, `gatsby`, `nuxt`, and `quasar` each bring their own project rules when selected.
|
|
201
|
-
- Laravel testing commands now detect Pest and PHPUnit from Composer dependencies and write the matching defaults into the generated project profile.
|
|
202
|
-
- Docker, Docker Compose, and Laravel Sail are detected as environment traits and mirrored into `.paqad/stack-snapshot.json`.
|
|
203
|
-
- If no `--providers` flag is passed, onboarding defaults to `claude-code` unless a caller explicitly supplies adapters programmatically.
|
|
204
|
-
- Onboarding is idempotent: running it twice with the same selections produces the same output.
|
|
205
|
-
|
|
206
|
-
### Behavior
|
|
207
|
-
|
|
208
|
-
- runs project detection
|
|
209
|
-
- in interactive mode, shows the effective detected stack profile and asks for confirmation before generation continues
|
|
210
|
-
- resolves rules, tool references, and MCP configs from the detected stack profile plus any fallback/manual overrides
|
|
211
|
-
- generates provider-specific entry files only for the selected providers
|
|
212
|
-
- copies rules into `docs/instructions/rules/**`
|
|
213
|
-
- copies stack tool/reference guides into `docs/instructions/tools/<stack>/**`
|
|
214
|
-
- writes `.paqad/project-profile.yaml`, `.paqad/onboarding-manifest.json`, `.paqad/stack-snapshot.json`, `.paqad/stack-drift.json`, and related framework artifacts
|
|
215
|
-
|
|
216
|
-
### `doctor`
|
|
217
|
-
|
|
218
|
-
Runs framework health checks and prints a machine-readable report.
|
|
243
|
+
### `paqad-ai onboard`
|
|
244
|
+
|
|
245
|
+
Full project onboarding. The main command.
|
|
219
246
|
|
|
220
247
|
```bash
|
|
221
|
-
|
|
248
|
+
# Interactive β prompts for providers, confirms detected stack
|
|
249
|
+
paqad-ai onboard
|
|
250
|
+
|
|
251
|
+
# Explicit stack and providers
|
|
252
|
+
paqad-ai onboard --stack laravel --capability react tailwind --providers claude-code cursor
|
|
253
|
+
|
|
254
|
+
# Flutter with all providers
|
|
255
|
+
paqad-ai onboard --stack flutter
|
|
256
|
+
|
|
257
|
+
# Next.js with Tailwind
|
|
258
|
+
paqad-ai onboard --stack react --capability next tailwind
|
|
259
|
+
|
|
260
|
+
# GitHub Copilot only
|
|
261
|
+
paqad-ai onboard --providers github-copilot
|
|
262
|
+
|
|
263
|
+
# Windsurf + Continue
|
|
264
|
+
paqad-ai onboard --providers windsurf continue
|
|
222
265
|
```
|
|
223
266
|
|
|
224
|
-
Options
|
|
267
|
+
**Options:**
|
|
268
|
+
|
|
269
|
+
| Flag | What it does |
|
|
270
|
+
| -------------------------- | -------------------------------------------------------- |
|
|
271
|
+
| `--project-root <path>` | Target directory (default: `.`) |
|
|
272
|
+
| `--stack <stack>` | Manual framework override |
|
|
273
|
+
| `--capability <traits...>` | Manual trait overrides (e.g., `inertia tailwind docker`) |
|
|
274
|
+
| `--providers <agents...>` | Which agents to generate for |
|
|
225
275
|
|
|
226
|
-
|
|
276
|
+
**Available `--stack` values:** `laravel`, `flutter`, `react`, `vue`, `django`, `fastapi`, `rails`, `spring-boot`, `express`, `angular`, `svelte`, `astro`, `go-web`, `rust-web`, `short-video`
|
|
227
277
|
|
|
228
|
-
|
|
278
|
+
**Available `--providers`:** `claude-code`, `codex-cli`, `gemini-cli`, `junie`, `cursor`, `github-copilot`, `windsurf`, `continue`, `aider`
|
|
229
279
|
|
|
230
|
-
|
|
231
|
-
- prints a JSON health report
|
|
232
|
-
- exits with code `1` when overall status is `fail`, otherwise `0`
|
|
280
|
+
**Notes:**
|
|
233
281
|
|
|
234
|
-
|
|
282
|
+
- `react` and `vue` are mutually exclusive β pick one
|
|
283
|
+
- Standalone React/Vue brings sub-stack rule bundles (`next`, `remix`, `nuxt`, etc.)
|
|
284
|
+
- Laravel auto-detects Pest vs PHPUnit from Composer dependencies
|
|
285
|
+
- Empty or content-only repos onboard as `active_capabilities: [content]`
|
|
286
|
+
- Onboarding is idempotent β running it twice produces the same output
|
|
287
|
+
- Default provider is `claude-code` if none specified
|
|
235
288
|
|
|
236
|
-
|
|
289
|
+
### `paqad-ai doctor`
|
|
290
|
+
|
|
291
|
+
Health checks. Validates framework artifacts, profile schema, instruction bundles, adapter config, MCP config, and doc completeness.
|
|
237
292
|
|
|
238
293
|
```bash
|
|
239
|
-
paqad-ai
|
|
294
|
+
paqad-ai doctor
|
|
240
295
|
```
|
|
241
296
|
|
|
242
|
-
|
|
297
|
+
Exits `1` on failure, `0` on pass.
|
|
298
|
+
|
|
299
|
+
### `paqad-ai refresh`
|
|
300
|
+
|
|
301
|
+
Re-detects stack and regenerates derived artifacts without full re-onboarding.
|
|
243
302
|
|
|
244
303
|
```bash
|
|
245
|
-
paqad-ai refresh
|
|
246
|
-
paqad-ai refresh --
|
|
304
|
+
paqad-ai refresh # Both stack + design system
|
|
305
|
+
paqad-ai refresh --stack # Stack snapshot + stack docs only
|
|
306
|
+
paqad-ai refresh --design-system # Design system docs only
|
|
247
307
|
```
|
|
248
308
|
|
|
249
|
-
|
|
309
|
+
### `paqad-ai update`
|
|
250
310
|
|
|
251
|
-
|
|
252
|
-
- `--design-system`: refresh design-system markdown from design tokens.
|
|
253
|
-
- `--stack`: refresh the cached stack snapshot.
|
|
311
|
+
Regenerates framework-managed files after a package version change. Preserves your onboarding decisions.
|
|
254
312
|
|
|
255
|
-
|
|
313
|
+
```bash
|
|
314
|
+
paqad-ai update
|
|
315
|
+
```
|
|
256
316
|
|
|
257
|
-
|
|
258
|
-
- refreshes stack introspection snapshots and `docs/instructions/stack/**` when enabled
|
|
259
|
-
- when no specific refresh flags are passed, both refresh paths run
|
|
317
|
+
### `paqad-ai capabilities`
|
|
260
318
|
|
|
261
|
-
|
|
319
|
+
```bash
|
|
320
|
+
paqad-ai capabilities list # What's active
|
|
321
|
+
paqad-ai capabilities available # What's available
|
|
322
|
+
paqad-ai capabilities add coding # Activate coding + security
|
|
323
|
+
paqad-ai capabilities remove coding # Deactivate coding + security
|
|
324
|
+
```
|
|
262
325
|
|
|
263
|
-
|
|
326
|
+
Rules: `content` can't be removed. Removing `coding` also removes `security`. Adding `coding` auto-adds `security`.
|
|
327
|
+
|
|
328
|
+
### `paqad-ai packs`
|
|
264
329
|
|
|
265
330
|
```bash
|
|
266
|
-
paqad-ai
|
|
331
|
+
paqad-ai packs list # Show effective packs + sources
|
|
332
|
+
paqad-ai packs list --json # Machine-readable with override state
|
|
333
|
+
paqad-ai packs install <source> # Local path, git URL, or registry name
|
|
334
|
+
paqad-ai packs install <source> --scope project --project-root .
|
|
335
|
+
paqad-ai packs remove <name> # Remove overrides only (can't remove built-ins)
|
|
336
|
+
paqad-ai packs validate <path> # Validate a pack before installing
|
|
337
|
+
paqad-ai packs create <name> # Scaffold a new pack
|
|
267
338
|
```
|
|
268
339
|
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
- `--project-root <path>`: target project directory. Defaults to the current working directory.
|
|
272
|
-
|
|
273
|
-
Behavior:
|
|
274
|
-
|
|
275
|
-
- reads the existing project profile and onboarding manifest
|
|
276
|
-
- regenerates framework-owned artifacts in a temporary workspace
|
|
277
|
-
- updates auto-managed files in the target project
|
|
278
|
-
- prints a JSON report with regenerated files and skipped files
|
|
279
|
-
|
|
280
|
-
Use `update` when the package version changes or when framework-managed scaffolding needs to be refreshed without re-running project setup decisions.
|
|
281
|
-
|
|
282
|
-
## π Feature Overview
|
|
283
|
-
|
|
284
|
-
| Feature | What it does |
|
|
285
|
-
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
286
|
-
| 17 built-in stack packs | Ships 14 framework packs (`laravel`, `flutter`, `react`, `vue`, `django`, `fastapi`, `rails`, `spring-boot`, `express`, `angular`, `svelte`, `astro`, `go-web`, `rust-web`) plus 3 archetype packs (`node-cli`, `node-library`, `node-service`) for projects that don't match a framework. |
|
|
287
|
-
| Multi-provider support | Generates repo-managed output for Claude Code, Codex CLI, Gemini CLI, Junie, Cursor, GitHub Copilot, Windsurf, Continue, and Aider from the same framework state. |
|
|
288
|
-
| Capability-first onboarding | Starts every repo with `content`, activates `coding` and `security` from matched packs or explicit capability changes. |
|
|
289
|
-
| Two-phase stack detection | Framework packs are evaluated first; archetype packs (`node-cli`, `node-library`, `node-service`) activate as a fallback for CLI tools, libraries, and raw services. |
|
|
290
|
-
| Stack Pack architecture | Uses `pack.yaml` manifests to drive detection, resolver behavior, MCP defaults, pentest mappings, and stack docs. Supports `tier: archetype` for fallback detection. |
|
|
291
|
-
| Thin provider entry files | Generates concise `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.junie/AGENTS.md`, `.cursor/rules/paqad.mdc`, `.github/copilot-instructions.md`, `.windsurfrules`, `.continue/rules/paqad.md`, and `CONVENTIONS.md` files that point to project-owned docs. |
|
|
292
|
-
| Project-owned instruction bundles | Copies rules and stack references into `docs/instructions/**` so the repo owns the operational guidance. |
|
|
293
|
-
| Stack snapshot docs | Writes human-readable stack docs under `docs/instructions/stack/**` from detected manifests and lockfiles. |
|
|
294
|
-
| Documentation workflow | Builds architecture docs, design-system docs, and module docs from the real project state after onboarding. |
|
|
295
|
-
| Capability management CLI | Supports `capabilities list`, `available`, `add`, and `remove` with canonical capability normalization. |
|
|
296
|
-
| Health checks | Verifies framework artifacts, copied instructions, adapter output, MCP config, and documentation completeness. |
|
|
297
|
-
| Refresh and update flows | Regenerates framework-managed artifacts and records stack/capability drift without forcing a full re-onboard. |
|
|
298
|
-
| MCP integration | Enables stack-aware MCP defaults for supported adapters and pack-specific environments. |
|
|
299
|
-
| Pentest workflows | Ships canonical `pentest` and `pentest-retest` workflows with saved reports and resumable state. |
|
|
300
|
-
| Semantic context loader | Builds chunk indexes and load statistics so agents can pull targeted context instead of scanning whole repos. |
|
|
301
|
-
| Predictive skill cache | Tracks transition probabilities and cache metrics to prewarm likely skills between workflow steps. |
|
|
302
|
-
| Context budget optimizer | Enforces context budgets and records token savings from summarization and eviction. |
|
|
303
|
-
| Context deduplication | Replaces duplicate resolved artifacts with references and records dedup savings per session. |
|
|
304
|
-
| Smart handoff compression | Writes structured handoff artifacts and compression stats for resumable multi-step workflows. |
|
|
305
|
-
| Workflow engine | Runs canonical workflows plus user-defined `docs/instructions/workflows/*.yaml` templates with resumable state. |
|
|
306
|
-
| Pack management CLI | Supports `packs list`, `install`, `remove`, `validate`, and `create` for built-in, global, and project pack workflows. |
|
|
307
|
-
|
|
308
|
-
## π Workflow Overview
|
|
309
|
-
|
|
310
|
-
| Workflow | Trigger | What it does |
|
|
311
|
-
| ------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
|
|
312
|
-
| Onboarding | `paqad-ai onboard` | Detects the repo, confirms stack/capabilities, generates provider files, rules, references, MCP config, and framework metadata. |
|
|
313
|
-
| Health check | `paqad-ai doctor` | Verifies framework artifacts, copied instruction bundles, adapter output, MCP config, and documentation completeness. |
|
|
314
|
-
| Refresh | `paqad-ai refresh` | Rebuilds stack/design-system derived artifacts and updates stack snapshot docs without full re-onboarding. |
|
|
315
|
-
| Update | `paqad-ai update` | Regenerates framework-managed files for an already onboarded project after package or framework changes. |
|
|
316
|
-
| Documentation workflow | Agent request such as `create documentation` | Re-reads the real app state and generates stack docs, architecture docs, design-system docs, and module docs. |
|
|
317
|
-
| Pentest | Workflow request `pentest` | Runs the canonical pentest workflow and writes timestamped markdown and JSON reports plus resumable run state. |
|
|
318
|
-
| Pentest retest | Workflow request `pentest-retest` | Rechecks a prior pentest report, preserves finding IDs, and writes retest artifacts under `docs/pentest/retests/`. |
|
|
319
|
-
| Capability management | `paqad-ai capabilities ...` | Lists, adds, removes, and inspects active capabilities for the current project. |
|
|
320
|
-
| Pack management | `paqad-ai packs ...` | Lists, installs, validates, removes, and scaffolds stack packs for built-in, global, or project use. |
|
|
321
|
-
| Custom workflow templates | `docs/instructions/workflows/*.yaml` | Lets teams define resumable user-owned workflows that run through the workflow engine. |
|
|
322
|
-
|
|
323
|
-
## π§ Development
|
|
324
|
-
|
|
325
|
-
Install dependencies:
|
|
340
|
+
### Security workflows
|
|
326
341
|
|
|
327
342
|
```bash
|
|
328
|
-
|
|
343
|
+
paqad-ai pentest # Full scan
|
|
344
|
+
paqad-ai pentest --incremental # Only changed files
|
|
345
|
+
paqad-ai pentest-retest --source <report> # Re-check prior findings
|
|
329
346
|
```
|
|
330
347
|
|
|
331
|
-
|
|
348
|
+
### Pattern library
|
|
332
349
|
|
|
333
350
|
```bash
|
|
334
|
-
|
|
351
|
+
paqad-ai patterns list [--domain <d>] [--framework <f>] [--category <c>]
|
|
352
|
+
paqad-ai patterns prune [--older-than <days>]
|
|
353
|
+
paqad-ai patterns export <output> [--format json|markdown]
|
|
335
354
|
```
|
|
336
355
|
|
|
337
|
-
|
|
356
|
+
---
|
|
357
|
+
|
|
358
|
+
## What it generates
|
|
359
|
+
|
|
360
|
+
```
|
|
361
|
+
your-project/
|
|
362
|
+
βββ CLAUDE.md # β docs/instructions/
|
|
363
|
+
βββ AGENTS.md # β docs/instructions/
|
|
364
|
+
βββ GEMINI.md # β docs/instructions/
|
|
365
|
+
βββ CONVENTIONS.md # Aider
|
|
366
|
+
βββ .junie/AGENTS.md # β docs/instructions/
|
|
367
|
+
βββ .cursor/rules/paqad.mdc # + MCP, skills, agents
|
|
368
|
+
βββ .github/copilot-instructions.md # + .vscode/mcp.json
|
|
369
|
+
βββ .windsurfrules # + MCP, skills, agents
|
|
370
|
+
βββ .continue/rules/paqad.md # + MCP, prompts
|
|
371
|
+
β
|
|
372
|
+
βββ docs/
|
|
373
|
+
β βββ instructions/
|
|
374
|
+
β β βββ stack/ # Auto-generated stack docs
|
|
375
|
+
β β β βββ overview.md
|
|
376
|
+
β β β βββ frameworks.md
|
|
377
|
+
β β β βββ dependencies.md
|
|
378
|
+
β β β βββ tooling.md
|
|
379
|
+
β β β βββ version-rules.md
|
|
380
|
+
β β β βββ drift-report.md
|
|
381
|
+
β β βββ rules/ # Conventions, writing style
|
|
382
|
+
β β βββ tools/ # Stack-specific tool guides
|
|
383
|
+
β β βββ workflows/ # Your custom YAML templates
|
|
384
|
+
β βββ modules/ # Per-feature business + technical docs
|
|
385
|
+
β βββ pentest/ # Security reports + retests
|
|
386
|
+
β
|
|
387
|
+
βββ .paqad/ # Framework metadata (machine-managed)
|
|
388
|
+
βββ project-profile.yaml
|
|
389
|
+
βββ stack-snapshot.json
|
|
390
|
+
βββ stack-drift.json
|
|
391
|
+
βββ onboarding-manifest.json
|
|
392
|
+
βββ doc-progress.json
|
|
393
|
+
βββ pentest/runs/
|
|
394
|
+
βββ session/ # Handoff, budget, dedup stats
|
|
395
|
+
βββ context/ # Chunk index, load stats
|
|
396
|
+
βββ cache/ # Transition log, metrics
|
|
397
|
+
βββ workflows/ # Custom workflow run state
|
|
398
|
+
```
|
|
399
|
+
|
|
400
|
+
Entry files stay thin. Knowledge lives in shared instruction bundles that all 9 agents read.
|
|
401
|
+
|
|
402
|
+
---
|
|
403
|
+
|
|
404
|
+
## Workflow overview
|
|
405
|
+
|
|
406
|
+
| Workflow | How to trigger | What happens |
|
|
407
|
+
| -------------------- | -------------------------------------- | --------------------------------------------------------- |
|
|
408
|
+
| **Onboarding** | `paqad-ai onboard` | Detect stack β confirm β generate everything |
|
|
409
|
+
| **Health check** | `paqad-ai doctor` | Validate artifacts, config, docs |
|
|
410
|
+
| **Refresh** | `paqad-ai refresh` | Re-detect stack, update derived docs |
|
|
411
|
+
| **Update** | `paqad-ai update` | Regenerate framework files after version bump |
|
|
412
|
+
| **Documentation** | Ask agent: _"create documentation"_ | Stack β architecture β design system β modules |
|
|
413
|
+
| **Pentest** | Ask agent: _"run pentest"_ | 5-step scan β findings β report |
|
|
414
|
+
| **Retest** | Ask agent: _"retest pentest"_ | Replay findings β fixed / still-open / needs-verification |
|
|
415
|
+
| **Capabilities** | `paqad-ai capabilities add/remove` | Toggle content / coding / security |
|
|
416
|
+
| **Pack management** | `paqad-ai packs install/remove` | Install, validate, scaffold stack packs |
|
|
417
|
+
| **Custom workflows** | YAML at `docs/instructions/workflows/` | Your own resumable skill sequences |
|
|
418
|
+
|
|
419
|
+
---
|
|
420
|
+
|
|
421
|
+
## Requirements
|
|
422
|
+
|
|
423
|
+
| Requirement | Version |
|
|
424
|
+
| ----------- | ----------------------------- |
|
|
425
|
+
| **Node.js** | `β₯ 25` (pinned via `.nvmrc`) |
|
|
426
|
+
| **pnpm** | `10+` (for local development) |
|
|
427
|
+
|
|
428
|
+
---
|
|
429
|
+
|
|
430
|
+
## Development
|
|
338
431
|
|
|
339
432
|
```bash
|
|
340
|
-
pnpm
|
|
341
|
-
pnpm run typecheck
|
|
342
|
-
pnpm run lint
|
|
343
|
-
pnpm run build
|
|
433
|
+
pnpm install
|
|
434
|
+
pnpm run ci # typecheck β lint β format β test (80%+ coverage) β build
|
|
344
435
|
```
|
|
345
436
|
|
|
346
|
-
|
|
437
|
+
```bash
|
|
438
|
+
pnpm run test # Tests only
|
|
439
|
+
pnpm run typecheck # TypeScript checks
|
|
440
|
+
pnpm run lint # ESLint
|
|
441
|
+
pnpm run build # Production build
|
|
442
|
+
```
|
|
443
|
+
|
|
444
|
+
---
|
|
445
|
+
|
|
446
|
+
## Contributing
|
|
347
447
|
|
|
348
|
-
|
|
448
|
+
Coming soon
|
|
349
449
|
|
|
350
|
-
|
|
450
|
+
---
|
|
351
451
|
|
|
352
|
-
|
|
452
|
+
MIT License Β· [npm](https://npmjs.com/package/paqad-ai) Β· [Docs](./docs/framework/specifications.md)
|