paqad-ai

🚀 paqad-ai is a documentation-first AI workflow framework for capability-driven repositories. It scaffolds project rules, stack-aware docs, MCP configuration, health checks, and agent entry files so teams can work consistently across Claude Code, Codex CLI, Gemini CLI, and Junie.

✨ What It Solves

Modern AI-assisted delivery breaks down when every repository invents its own prompts, rules, and folder structure. paqad-ai standardizes that layer by generating framework-managed artifacts that keep implementation, documentation, and verification aligned.

With paqad-ai, a repo can:

• onboard into a repeatable AI workflow
• keep architecture and rules visible to coding agents
• generate structured documentation instead of ad hoc notes
• wire stack-aware MCP defaults into supported adapters
• run health and refresh flows safely over framework-managed artifacts

🧩 Supported Adapters

| Adapter | Status | Notes | | ----------- | ------------ | ------------------------------------------------------- | | Claude Code | ✅ Supported | Generates CLAUDE.md plus MCP config | | Codex CLI | ✅ Supported | Generates AGENTS.md plus MCP config | | Gemini CLI | ✅ Supported | Generates GEMINI.md plus MCP config | | Junie | ✅ Supported | Limited to .junie/AGENTS.md and .junie/mcp/mcp.json |

🛠️ Installation

Prerequisites

| Requirement | Version | | ----------- | --------------------------- | | Node.js | 25+ | | pnpm | 10+ for local development |

Install globally

npm install -g paqad-ai

Or run with npx

npx paqad-ai install

⚡ Quick Start

1. Onboard a repository

paqad-ai onboard --project-root .

2. Check project health

paqad-ai doctor --project-root .

3. Refresh framework-managed artifacts

paqad-ai update --project-root .

📦 What paqad-ai Generates

Depending on detected capabilities, stack packs, and selected providers, paqad-ai can generate:

• provider entry files such as CLAUDE.md, AGENTS.md, GEMINI.md, and .junie/AGENTS.md
• framework-managed state under .paqad/
• copied instruction bundles under docs/instructions/rules/ and docs/instructions/tools/
• stack snapshot docs under docs/instructions/stack/
• architecture and module documentation under docs/instructions/ and docs/modules/
• adapter-specific MCP configuration

🧠 Documentation Workflow

There is no standalone document command.

After onboarding, documentation is created through the framework workflow. An active agent can receive a request like create documentation, and the workflow will:

1. start from the onboarded project state in .paqad/
2. re-check the live app from manifests, lockfiles, and stack signals
3. update effective stack context if reality differs from stored onboarding data
4. generate stack, architecture, and design-system docs first
5. generate the remaining global instruction docs
6. generate module docs, including business.md and technical.md
7. track progress in .paqad/doc-progress.json

✅ Quality Gates

Local and CI verification use the same command:

pnpm run ci

This runs typecheck, lint, formatting checks, test coverage, and build validation. Coverage thresholds are currently enforced at 80% for statements, lines, and functions, and 85% for branches.

📚 Command Reference

install

Bootstraps the framework into a project and writes framework metadata.

paqad-ai install --project-root .

Options:

• --project-root <path>: target project directory. Defaults to the current working directory.

Behavior:

• creates the framework home directory if needed
• writes framework version metadata for the target project
• prints a JSON result with framework_home, project_root, and version

onboard

Runs full project onboarding and generates the lean framework-managed baseline.

paqad-ai onboard --project-root .

Interactive flow

When run without flags in an interactive terminal, onboard prompts for:

1. Providers — multi-select: Codex, Claude Code, Gemini, Junie (one or more required).
2. Manifest-driven stack scan — composer.json, package.json, lockfiles, and supported config files are scanned first.
3. Stack confirmation checkpoint — the detected effective stack profile is shown and must be confirmed before onboarding continues in interactive mode.
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.

Examples

# Laravel with React and Tailwind, Claude Code only
paqad-ai onboard --project-root . --stack laravel --capability react tailwind --providers claude-code

# Flutter with all providers
paqad-ai onboard --project-root . --stack flutter

# Next.js with Tailwind
paqad-ai onboard --project-root . --stack react --capability next tailwind

# Plain Laravel
paqad-ai onboard --project-root . --stack laravel

Options

• --project-root <path>: target project directory. Defaults to the current working directory.
• --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.
• --capability <capability...>: fallback/manual trait override — inertia, react, vue, tailwind, boost, next, remix, vite-spa, gatsby, nuxt, quasar, docker, compose, sail, pest, phpunit.
• --providers <provider...>: one or more providers — codex-cli, claude-code, gemini-cli, junie.

Stack capability matrix

| Stack | Capabilities | | ----------- | ------------------------------------------------- | | Laravel | inertia, react, vue, tailwind, boost | | Flutter | docker, compose | | React | next, remix, vite-spa, gatsby, tailwind | | Vue | nuxt, vite-spa, quasar, tailwind | | Django | docker, compose | | FastAPI | docker, compose | | Rails | docker, compose | | Spring Boot | docker, compose | | Express | docker, compose | | Angular | docker, compose | | Svelte | docker, compose | | Astro | docker, compose | | Go Web | docker, compose | | Rust Web | docker, compose |

Notes

• react and vue are mutually exclusive. Select only one frontend framework.
• Standalone React and Vue projects are supported directly; Laravel continues to use react and vue as capabilities when paired with backend-driven frontend code.
• Empty or content-only repositories onboard without a domain prompt and persist active_capabilities: [content].
• 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.
• Laravel testing commands now detect Pest and PHPUnit from Composer dependencies and write the matching defaults into the generated project profile.
• Docker, Docker Compose, and Laravel Sail are detected as environment traits and mirrored into .paqad/stack-snapshot.json.
• If no --providers flag is passed in a non-interactive context, files for all four providers are generated.
• Onboarding is idempotent: running it twice with the same selections produces the same output.

Behavior

• runs project detection
• in interactive mode, shows the effective detected stack profile and asks for confirmation before generation continues
• resolves rules, tool references, and MCP configs from the detected stack profile plus any fallback/manual overrides
• generates provider-specific entry files only for the selected providers
• copies rules into docs/instructions/rules/**
• copies stack tool/reference guides into docs/instructions/tools/<stack>/**
• writes .paqad/project-profile.yaml, .paqad/onboarding-manifest.json, .paqad/stack-snapshot.json, .paqad/stack-drift.json, and related framework artifacts

doctor

Runs framework health checks and prints a machine-readable report.

paqad-ai doctor --project-root .

Options:

• --project-root <path>: target project directory. Defaults to the current working directory.

Behavior:

• validates framework artifacts, profile schema, copied instruction bundles, adapter config, MCP config, and post-documentation outputs when present
• prints a JSON health report
• exits with code 1 when overall status is fail, otherwise 0

refresh

Refreshes derived framework artifacts without running full onboarding.

paqad-ai refresh --project-root .

Examples:

paqad-ai refresh --project-root . --design-system
paqad-ai refresh --project-root . --stack

Options:

• --project-root <path>: target project directory. Defaults to the current working directory.
• --design-system: refresh design-system markdown from design tokens.
• --stack: refresh the cached stack snapshot.

Behavior:

• refreshes design-system docs when enabled
• refreshes stack introspection snapshots and docs/instructions/stack/** when enabled
• when no specific refresh flags are passed, both refresh paths run

update

Regenerates framework-managed artifacts for an already onboarded project.

paqad-ai update --project-root .

Options:

• --project-root <path>: target project directory. Defaults to the current working directory.

Behavior:

• reads the existing project profile and onboarding manifest
• regenerates framework-owned artifacts in a temporary workspace
• updates auto-managed files in the target project
• prints a JSON report with regenerated files and skipped files

Use update when the package version changes or when framework-managed scaffolding needs to be refreshed without re-running project setup decisions.

🌟 Feature Overview

| Feature | What it does | | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 14 built-in coding packs | Ships first-party packs for laravel, flutter, react, vue, django, fastapi, rails, spring-boot, express, angular, svelte, astro, go-web, and rust-web. | | Multi-provider support | Generates repo-managed output for Claude Code, Codex CLI, Gemini CLI, and Junie from the same framework state. | | Capability-first onboarding | Starts every repo with content, activates coding and security from matched packs or explicit capability changes. | | Stack Pack architecture | Uses pack.yaml manifests to drive detection, resolver behavior, MCP defaults, pentest mappings, and stack docs. | | Thin provider entry files | Generates concise AGENTS.md, CLAUDE.md, GEMINI.md, and .junie/AGENTS.md files that point to project-owned docs. | | Project-owned instruction bundles | Copies rules and stack references into docs/instructions/** so the repo owns the operational guidance. | | Stack snapshot docs | Writes human-readable stack docs under docs/instructions/stack/** from detected manifests and lockfiles. | | Documentation workflow | Builds architecture docs, design-system docs, and module docs from the real project state after onboarding. | | Capability management CLI | Supports capabilities list, available, add, and remove with canonical capability normalization. | | Health checks | Verifies framework artifacts, copied instructions, adapter output, MCP config, and documentation completeness. | | Refresh and update flows | Regenerates framework-managed artifacts and records stack/capability drift without forcing a full re-onboard. | | MCP integration | Enables stack-aware MCP defaults for supported adapters and pack-specific environments. | | Pentest workflows | Ships canonical pentest and pentest-retest workflows with saved reports and resumable state. | | Semantic context loader | Builds chunk indexes and load statistics so agents can pull targeted context instead of scanning whole repos. | | Predictive skill cache | Tracks transition probabilities and cache metrics to prewarm likely skills between workflow steps. | | Context budget optimizer | Enforces context budgets and records token savings from summarization and eviction. | | Context deduplication | Replaces duplicate resolved artifacts with references and records dedup savings per session. | | Smart handoff compression | Writes structured handoff artifacts and compression stats for resumable multi-step workflows. | | Workflow engine | Runs canonical workflows plus user-defined docs/instructions/workflows/*.yaml templates with resumable state. | | Pack management CLI | Supports packs list, install, remove, validate, and create for built-in, global, and project pack workflows. |

🔄 Workflow Overview

| Workflow | Trigger | What it does | | ------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | Onboarding | paqad-ai onboard | Detects the repo, confirms stack/capabilities, generates provider files, rules, references, MCP config, and framework metadata. | | Health check | paqad-ai doctor | Verifies framework artifacts, copied instruction bundles, adapter output, MCP config, and documentation completeness. | | Refresh | paqad-ai refresh | Rebuilds stack/design-system derived artifacts and updates stack snapshot docs without full re-onboarding. | | Update | paqad-ai update | Regenerates framework-managed files for an already onboarded project after package or framework changes. | | 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. | | Pentest | Workflow request pentest | Runs the canonical pentest workflow and writes timestamped markdown and JSON reports plus resumable run state. | | Pentest retest | Workflow request pentest-retest | Rechecks a prior pentest report, preserves finding IDs, and writes retest artifacts under docs/pentest/retests/. | | Capability management | paqad-ai capabilities ... | Lists, adds, removes, and inspects active capabilities for the current project. | | Pack management | paqad-ai packs ... | Lists, installs, validates, removes, and scaffolds stack packs for built-in, global, or project use. | | Custom workflow templates | docs/instructions/workflows/*.yaml | Lets teams define resumable user-owned workflows that run through the workflow engine. |

🔧 Development

Install dependencies:

pnpm install

Run the full project checks:

pnpm run ci

Useful local commands:

pnpm run test
pnpm run typecheck
pnpm run lint
pnpm run build

🤝 Contributing

Contributions that improve framework reliability, adapter support, documentation quality, or stack coverage are welcome. Keep changes aligned with the framework’s documentation-first approach and ensure generated artifacts, validation logic, and tests remain consistent.

📄 License

paqad-ai is open-sourced software licensed under the MIT license.