paqad-ai 0.0.5 → 0.1.0

package/README.md

@@ -1,92 +1,105 @@
 # paqad-ai
 
-`paqad-ai` is a documentation-first AI agency framework for Laravel and Flutter workflows. It scaffolds project rules, documentation, registries, health checks, and agent-facing entry files so teams can run a consistent workflow across Claude Code, Codex CLI, Gemini CLI, and Junie.
+🚀 `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.
 
-## About paqad-ai
+## ✨ What It Solves
 
-Modern AI-assisted delivery breaks down when every repository invents its own prompts, rules, and folder conventions. `paqad-ai` standardizes that layer by generating framework-owned project artifacts that keep implementation, documentation, and verification aligned.
+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.
 
-The framework is designed to help teams:
+With `paqad-ai`, a repo can:
 
-- onboard projects into a repeatable AI workflow
-- keep project rules and architecture guidance visible to coding agents
-- generate structured documentation scaffolds instead of ad hoc notes
-- wire in stack-aware MCP defaults for supported environments
-- run health checks and refresh framework-managed artifacts safely
+- 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
+## 🧩 Supported Adapters
 
-`paqad-ai` currently supports:
+| 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` |
 
-- Claude Code
-- Codex CLI
-- Gemini CLI
-- Junie for JetBrains IDEs and Junie CLI
+## 🛠️ Installation
 
-Junie support is intentionally limited to the documented repo-managed surface:
+### Prerequisites
 
-- `.junie/AGENTS.md`
-- `.junie/mcp/mcp.json`
+| Requirement | Version                     |
+| ----------- | --------------------------- |
+| Node.js     | `25+`                       |
+| pnpm        | `10+` for local development |
 
-## Installation
-
-Install globally:
+### Install globally
 
 ```bash
 npm install -g paqad-ai
 ```
 
-Or run it directly with `npx`:
+### Or run with `npx`
 
 ```bash
 npx paqad-ai install
 ```
 
-## Quick Start
+## ⚡ Quick Start
 
-Bootstrap the framework into an existing project:
+### 1. Onboard a repository
 
 ```bash
 paqad-ai onboard --project-root .
 ```
 
-Run framework health checks:
+### 2. Check project health
 
 ```bash
 paqad-ai doctor --project-root .
 ```
 
-Refresh framework-managed artifacts:
+### 3. Refresh framework-managed artifacts
 
 ```bash
 paqad-ai update --project-root .
 ```
 
-## What paqad-ai Generates
+## 📦 What `paqad-ai` Generates
+
+Depending on detected capabilities, stack packs, and selected providers, `paqad-ai` can generate:
 
-Depending on the detected stack and selected options, `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
 
-- adapter entry files such as `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, and `.junie/AGENTS.md`
-- project profile and onboarding metadata under `.agency/`
-- project rules under `docs/rules/`
-- module scaffolds and registries under `docs/`
-- design-system and architecture guidance
-- stack-aware MCP configuration for supported adapters
-- runnable project health-check scripts
+## 🧠 Documentation Workflow
 
-## Documentation Workflow
+There is no standalone `document` command.
 
-`paqad-ai` no longer exposes a 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:
 
-Documentation creation is handled through the framework workflow after onboarding. The active agent can receive a request such as "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`
 
-- start from the onboarded project state in `.agency/`
-- re-check the real application from `composer.json`, `package.json`, and stack manifests
-- update the effective stack context if the live application disagrees with stored onboarding metadata
-- create canonical docs step by step
-- keep `.agency/doc-progress.json` as the canonical progress ledger
+## ✅ Quality Gates
 
-## Command Reference
+Local and CI verification use the same command:
+
+```bash
+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`
 
@@ -108,32 +121,83 @@ Behavior:
 
 ### `onboard`
 
-Runs full project onboarding and generates the framework-managed scaffold.
+Runs full project onboarding and generates the lean framework-managed baseline.
 
 ```bash
 paqad-ai onboard --project-root .
 ```
 
-Examples:
+### 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
 
 ```bash
-paqad-ai onboard --project-root . --domain coding --stack laravel --capability boost
-paqad-ai onboard --project-root . --domain coding --stack flutter
+# 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:
+### Options
 
 - `--project-root <path>`: target project directory. Defaults to the current working directory.
-- `--domain <domain>`: force the target domain. Current values are `coding` and `content`.
-- `--stack <stack>`: force the target stack. Current values are `laravel`, `flutter`, and `short-video`.
-- `--capability <capability...>`: add one or more capabilities such as `boost`.
-
-Behavior:
+- `--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
-- resolves rules, agents, skills, MCP configs, templates, and scripts
-- generates adapter entry files including Junie support
-- writes `.agency/project-profile.yaml`, `.agency/onboarding-manifest.json`, and related framework artifacts
+- 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`
 
@@ -149,7 +213,7 @@ Options:
 
 Behavior:
 
-- validates framework artifacts, profile schema, docs scaffold, indexes, scripts, hooks, adapter config, MCP config, and other generated assets
+- 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`
 
@@ -177,7 +241,7 @@ Options:
 Behavior:
 
 - refreshes design-system docs when enabled
-- refreshes stack introspection snapshots when enabled
+- refreshes stack introspection snapshots and `docs/instructions/stack/**` when enabled
 - when no specific refresh flags are passed, both refresh paths run
 
 ### `update`
@@ -197,11 +261,51 @@ 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, skipped files, and new scripts
+- 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.
 
-## Development
+## 🌟 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:
 
@@ -224,10 +328,10 @@ pnpm run lint
 pnpm run build
 ```
 
-## Contributing
+## 🤝 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
+## 📄 License
 
 `paqad-ai` is open-sourced software licensed under the [MIT license](LICENSE).