prr-kit 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 mrquangthai278
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,226 @@
+# PR Review Framework
+
+<p align="center">
+  <img src="docs/assets/banner.svg" alt="PR Review Framework" width="100%"/>
+</p>
+
+> AI-driven Pull Request code review — structured, multi-perspective, actionable.
+
+Module system, agent YAML, step-file workflows, CLI installer with full IDE integration.
+
+## Quick Start
+
+```bash
+# Install into your repo (interactive — recommended)
+npx pr-review install
+
+# Or run directly
+node tools/cli/prr-cli.js install --directory /path/to/repo
+
+# Silent install with defaults (edit config.yaml afterward)
+node tools/cli/prr-cli.js install --directory /path/to/repo --modules prr --tools claude-code --yes
+```
+
+Then open your IDE in the installed project and use `/prr-master` to start.
+
+## How It Works
+
+```
+  Your IDE (Claude Code / Cursor / Windsurf / ...)
+       │
+       │  /prr-master  or  /prr-quick
+       ▼
+  ┌─────────────────────────────────────────────────┐
+  │              PRR Master Agent                   │
+  │   reads _prr/ · routes to workflows             │
+  └────────────┬────────────────────────────────────┘
+               │
+       ┌───────▼────────┐
+       │  select-pr      │  git fetch · list PRs via platform CLI
+       │  (Step-file)    │  user selects PR/MR by number or branch
+       └───────┬────────┘
+               │  diff loaded into AI context
+       ┌───────▼────────┐
+       │  describe-pr   │  classify type · file-by-file walkthrough
+       └───────┬────────┘
+               │
+       ┌───────▼────────────────────────────────┐
+       │  Review agents (parallel or sequential) │
+       │  GR · SR · PR · AR                     │
+       │  each reads instructions.xml            │
+       │  outputs structured findings            │
+       └───────┬────────────────────────────────┘
+               │
+       ┌───────▼────────┐
+       │  generate-report│  compile findings · sort by severity
+       │                 │  write .md to _prr-output/reviews/
+       └───────┬────────┘
+               │
+       ┌───────▼────────┐
+       │  post-comments  │  post inline comments via platform CLI
+       │  (optional)     │  GitHub · GitLab · Azure · Bitbucket
+       └────────────────┘
+```
+
+The framework installs into your project as a `_prr/` folder. Agents and workflows are Markdown/YAML files that your AI IDE reads and executes — no server, no background process, no API keys required beyond your IDE's AI.
+
+## Configuration
+
+After install, edit `_prr/prr/config.yaml` in your project:
+
+```yaml
+user_name: YourName
+communication_language: English
+target_repo: .                        # path to the git repo to review (. = current dir)
+github_repo: "owner/repo"            # GitHub repo for gh pr list / inline comments
+output_folder: _prr-output
+review_output: /abs/path/_prr-output/reviews
+```
+
+> `github_repo` is required for `gh pr list`, `gh pr diff`, and posting inline GitHub comments.
+> Leave empty to use local branch selection only.
+
+## Platform Support
+
+| Feature | None / Local | GitHub | GitLab | Azure DevOps | Bitbucket |
+|---------|:---:|:---:|:---:|:---:|:---:|
+| Core review (diff analysis) | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Auto-detect platform from remote URL | — | ✅ | ✅ | ✅ | ✅ |
+| List open PRs/MRs | ❌ | ✅ `gh` | ✅ `glab` | ✅ `az` | ✅ `bb` |
+| Select PR by number (auto base/head) | ❌ | ✅ | ✅ | ✅ | ✅ |
+| Load diff via platform CLI | ❌ | ✅ `gh pr diff` | ✅ `glab mr diff` | ⚠️ git fallback | ⚠️ git fallback |
+| Post inline code comments | ❌ | ✅ Reviews API | ✅ MR discussions | ✅ PR threads | ✅ REST API |
+| Post summary review | ❌ | ✅ | ✅ | ✅ | ✅ |
+| Review verdict (approve / request changes) | ❌ | ✅ | ✅ | ✅ | ❌ |
+| Required CLI | — | `gh` | `glab` | `az` + extension | `bb` / curl |
+
+> **None / Local mode**: all review analysis runs locally via `git diff` — no platform CLI required. Findings are saved to `_prr-output/reviews/` only.
+
+## Review Workflow
+
+### Quick mode — one command, full pipeline
+
+```
+/prr-quick    or    /prr-master → QR
+```
+
+Runs automatically: **select PR → describe → all 4 reviews → generate report**
+Only pauses once to ask which PR/branch to review.
+
+### Manual mode — step by step
+
+| Code | Command | Description |
+|------|---------|-------------|
+| `CP` | Collect Project Context | Scan ESLint/tsconfig/docs, extract coding rules, capture domain knowledge — **run once per project** |
+| `SP` | Select PR | Fetch latest → list open PRs (via `gh`) or branches → select head + base → load diff |
+| `DP` | Describe PR | Classify PR type, generate summary, file-by-file walkthrough |
+| `GR` | General Review | Logic, naming, readability, DRY, best practices |
+| `SR` | Security Review | OWASP Top 10, secrets, auth, rate limits, injection |
+| `PR` | Performance Review | N+1 queries, memory leaks, async patterns, caching |
+| `AR` | Architecture Review | SOLID, layers, coupling, consistency with codebase |
+| `IC` | Improve Code | Concrete BEFORE/AFTER code suggestions |
+| `AK` | Ask Code | Q&A about specific changes in this PR |
+| `RR` | Generate Report | Compile all findings → Markdown report in `_prr-output/reviews/` |
+| `PC` | Post Comments | Post inline code comments to GitHub PR via `gh` Reviews API |
+| `PM` | Party Mode 🎉 | All 4 reviewers in one collaborative session |
+| `HH` | Help | Show this guide |
+
+### Selecting a PR (SP step)
+
+**With `github_repo` configured** — lists open GitHub PRs:
+```
+#45  "Add OAuth2 login"      feature/oauth → main    @alice  3h ago
+#44  "Fix memory leak"       fix/memory    → main    @bob    1d ago
+```
+Enter PR number → base and head resolved automatically from GitHub.
+
+**Without `github_repo`** — asks explicitly for both branches:
+```
+🎯 Head branch (the branch to review)?
+   • Enter a number from the list  (e.g., 1)
+   • Type the branch name directly  (e.g., feature/my-feature)
+
+🎯 Base branch (what to diff against)?
+   • Press Enter for default [main]
+   • Type the branch name directly  (e.g., develop)
+```
+
+## Review Agents
+
+| Agent | Slash Command | Speciality |
+|-------|--------------|------------|
+| PRR Master | `/prr-master` | Orchestrator — routes all workflows |
+| Alex | `/general-reviewer` | Code quality, logic, naming, DRY |
+| Sam | `/security-reviewer` | OWASP Top 10, secrets, auth |
+| Petra | `/performance-reviewer` | N+1 queries, memory leaks, async |
+| Arch | `/architecture-reviewer` | SOLID, layers, coupling, consistency |
+
+Each reviewer agent can also be invoked directly and has its own menu.
+
+## Severity Levels
+
+All findings use a standard format:
+
+- 🔴 **[BLOCKER]** — Must fix before merge
+- 🟡 **[WARNING]** — Should fix (with explanation)
+- 🟢 **[SUGGESTION]** — Nice-to-have improvement
+- 📌 **[QUESTION]** — Needs clarification from author
+
+## Inline GitHub Comments
+
+When `[PC] Post Comments` is run with `github_repo` configured, it uses the GitHub Reviews API to post findings as **inline code comments** on the exact file and line — the same experience as a human reviewer on GitHub.
+
+Requires `gh` CLI authenticated: `gh auth login`
+
+## Supported IDEs
+
+- **Claude Code** (preferred)
+- **Cursor** (preferred)
+- **Windsurf** (preferred)
+- Cline, Roo, Gemini CLI, Kiro
+
+## Requirements
+
+- Node.js 18+
+- Git
+- `gh` CLI — required for `gh pr list`, `gh pr diff`, and posting inline GitHub comments
+
+## Development
+
+```bash
+npm install
+npm test
+```
+
+## Project Structure
+
+```
+main-project/
+├── src/
+│   ├── core/          # Master agent, tasks, party-mode workflow
+│   └── prr/
+│       ├── agents/    # 4 specialist reviewer agents
+│       └── workflows/
+│           ├── 0-setup/     # [CP] Collect Project Context
+│           ├── 1-discover/  # [SP] Select PR
+│           ├── 2-analyze/   # [DP] Describe PR
+│           ├── 3-review/    # [GR] [SR] [PR] [AR] Reviews
+│           ├── 4-improve/   # [IC] Improve Code
+│           ├── 5-ask/       # [AK] Ask Code
+│           ├── 6-report/    # [RR] Generate Report, [PC] Post Comments
+│           └── quick/       # [QR] Full pipeline in one command
+├── tools/
+│   └── cli/           # CLI installer + IDE handlers
+├── test/              # Schema + component tests
+└── docs/              # Documentation
+```
+
+---
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on adding workflows, reviewer agents, IDE integrations, and more.
+
+## License
+
+[MIT](LICENSE) © mrquangthai278

package/docs/assets/banner.svg

@@ -0,0 +1,179 @@
+<svg width="1200" height="300" viewBox="0 0 1200 300" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <!-- Background gradient -->
+    <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#0d1117"/>
+      <stop offset="100%" style="stop-color:#161b22"/>
+    </linearGradient>
+
+    <!-- Accent gradient (purple → blue) -->
+    <linearGradient id="accent" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" style="stop-color:#a855f7"/>
+      <stop offset="100%" style="stop-color:#3b82f6"/>
+    </linearGradient>
+
+    <!-- Glow filter for accent line -->
+    <filter id="glow" x="-20%" y="-200%" width="140%" height="500%">
+      <feGaussianBlur stdDeviation="4" result="blur"/>
+      <feMerge>
+        <feMergeNode in="blur"/>
+        <feMergeNode in="SourceGraphic"/>
+      </feMerge>
+    </filter>
+
+    <!-- Subtle grid pattern -->
+    <pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse">
+      <path d="M 40 0 L 0 0 0 40" fill="none" stroke="#ffffff" stroke-width="0.3" opacity="0.04"/>
+    </pattern>
+
+    <!-- Corner dot pattern -->
+    <pattern id="dots" width="20" height="20" patternUnits="userSpaceOnUse">
+      <circle cx="1" cy="1" r="1" fill="#ffffff" opacity="0.06"/>
+    </pattern>
+  </defs>
+
+  <!-- Background -->
+  <rect width="1200" height="300" fill="url(#bg)"/>
+
+  <!-- Grid overlay -->
+  <rect width="1200" height="300" fill="url(#grid)"/>
+
+  <!-- Dot pattern on right side -->
+  <rect x="800" y="0" width="400" height="300" fill="url(#dots)"/>
+
+  <!-- Decorative circles (blurred, background) -->
+  <circle cx="980" cy="80" r="120" fill="#a855f7" opacity="0.06"/>
+  <circle cx="1100" cy="220" r="80" fill="#3b82f6" opacity="0.06"/>
+  <circle cx="150" cy="240" r="100" fill="#a855f7" opacity="0.04"/>
+
+  <!-- Top accent line -->
+  <rect x="0" y="0" width="1200" height="3" fill="url(#accent)" filter="url(#glow)"/>
+
+  <!-- Left vertical accent bar -->
+  <rect x="64" y="60" width="3" height="180" fill="url(#accent)" opacity="0.8" filter="url(#glow)"/>
+
+  <!-- Icon area: magnifying glass SVG path -->
+  <g transform="translate(100, 110)">
+    <circle cx="28" cy="28" r="26" fill="none" stroke="url(#accent)" stroke-width="3" opacity="0.9"/>
+    <circle cx="28" cy="28" r="18" fill="none" stroke="url(#accent)" stroke-width="1.5" opacity="0.3"/>
+    <line x1="47" y1="47" x2="62" y2="62" stroke="url(#accent)" stroke-width="4" stroke-linecap="round" opacity="0.9"/>
+    <!-- Code lines inside glass -->
+    <line x1="18" y1="23" x2="38" y2="23" stroke="#a855f7" stroke-width="2" stroke-linecap="round" opacity="0.6"/>
+    <line x1="18" y1="30" x2="32" y2="30" stroke="#3b82f6" stroke-width="2" stroke-linecap="round" opacity="0.6"/>
+    <line x1="18" y1="37" x2="36" y2="37" stroke="#a855f7" stroke-width="2" stroke-linecap="round" opacity="0.4"/>
+  </g>
+
+  <!-- Main title -->
+  <text x="190" y="145" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif"
+        font-size="52" font-weight="700" letter-spacing="-1" fill="#ffffff">
+    PR Review Framework
+  </text>
+
+  <!-- Accent underline under title -->
+  <rect x="190" y="157" width="420" height="2" fill="url(#accent)" opacity="0.5" rx="1"/>
+
+  <!-- Subtitle -->
+  <text x="192" y="192" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif"
+        font-size="20" font-weight="400" fill="#8b949e" letter-spacing="0.3">
+    AI-driven Pull Request review — structured, multi-perspective, actionable
+  </text>
+
+  <!-- Badges row -->
+  <!-- Badge 1: Claude Code -->
+  <g transform="translate(192, 218)">
+    <rect width="112" height="26" rx="13" fill="#21262d" stroke="#30363d" stroke-width="1"/>
+    <circle cx="18" cy="13" r="5" fill="#a855f7" opacity="0.9"/>
+    <text x="30" y="17.5" font-family="monospace" font-size="11" fill="#8b949e">Claude Code</text>
+  </g>
+
+  <!-- Badge 2: Cursor -->
+  <g transform="translate(314, 218)">
+    <rect width="74" height="26" rx="13" fill="#21262d" stroke="#30363d" stroke-width="1"/>
+    <circle cx="18" cy="13" r="5" fill="#3b82f6" opacity="0.9"/>
+    <text x="30" y="17.5" font-family="monospace" font-size="11" fill="#8b949e">Cursor</text>
+  </g>
+
+  <!-- Badge 3: Windsurf -->
+  <g transform="translate(398, 218)">
+    <rect width="86" height="26" rx="13" fill="#21262d" stroke="#30363d" stroke-width="1"/>
+    <circle cx="18" cy="13" r="5" fill="#06b6d4" opacity="0.9"/>
+    <text x="30" y="17.5" font-family="monospace" font-size="11" fill="#8b949e">Windsurf</text>
+  </g>
+
+  <!-- Badge 4: Node.js -->
+  <g transform="translate(494, 218)">
+    <rect width="90" height="26" rx="13" fill="#21262d" stroke="#30363d" stroke-width="1"/>
+    <circle cx="18" cy="13" r="5" fill="#22c55e" opacity="0.9"/>
+    <text x="30" y="17.5" font-family="monospace" font-size="11" fill="#8b949e">Node 18+</text>
+  </g>
+
+  <!-- Right side: review flow diagram -->
+  <g transform="translate(820, 55)" opacity="0.85">
+    <!-- Flow boxes -->
+    <!-- SP -->
+    <rect x="0" y="0" width="80" height="30" rx="6" fill="#21262d" stroke="#30363d" stroke-width="1"/>
+    <text x="40" y="20" text-anchor="middle" font-family="monospace" font-size="12" fill="#a855f7" font-weight="600">SP</text>
+
+    <!-- Arrow -->
+    <line x1="80" y1="15" x2="110" y2="15" stroke="#30363d" stroke-width="1.5" marker-end="url(#arr)"/>
+
+    <!-- DP -->
+    <rect x="110" y="0" width="80" height="30" rx="6" fill="#21262d" stroke="#30363d" stroke-width="1"/>
+    <text x="150" y="20" text-anchor="middle" font-family="monospace" font-size="12" fill="#3b82f6" font-weight="600">DP</text>
+
+    <!-- Row 2: review types -->
+    <!-- Vertical line down from DP -->
+    <line x1="150" y1="30" x2="150" y2="55" stroke="#30363d" stroke-width="1.5"/>
+    <!-- Horizontal line -->
+    <line x1="30" y1="55" x2="270" y2="55" stroke="#30363d" stroke-width="1.5"/>
+
+    <!-- GR -->
+    <line x1="30" y1="55" x2="30" y2="75" stroke="#30363d" stroke-width="1.5"/>
+    <rect x="-10" y="75" width="80" height="28" rx="6" fill="#21262d" stroke="#a855f7" stroke-width="1" opacity="0.8"/>
+    <text x="30" y="93" text-anchor="middle" font-family="monospace" font-size="11" fill="#a855f7">GR</text>
+
+    <!-- SR -->
+    <line x1="110" y1="55" x2="110" y2="75" stroke="#30363d" stroke-width="1.5"/>
+    <rect x="70" y="75" width="80" height="28" rx="6" fill="#21262d" stroke="#ef4444" stroke-width="1" opacity="0.8"/>
+    <text x="110" y="93" text-anchor="middle" font-family="monospace" font-size="11" fill="#ef4444">SR</text>
+
+    <!-- PR -->
+    <line x1="190" y1="55" x2="190" y2="75" stroke="#30363d" stroke-width="1.5"/>
+    <rect x="150" y="75" width="80" height="28" rx="6" fill="#21262d" stroke="#f59e0b" stroke-width="1" opacity="0.8"/>
+    <text x="190" y="93" text-anchor="middle" font-family="monospace" font-size="11" fill="#f59e0b">PR</text>
+
+    <!-- AR -->
+    <line x1="270" y1="55" x2="270" y2="75" stroke="#30363d" stroke-width="1.5"/>
+    <rect x="230" y="75" width="80" height="28" rx="6" fill="#21262d" stroke="#06b6d4" stroke-width="1" opacity="0.8"/>
+    <text x="270" y="93" text-anchor="middle" font-family="monospace" font-size="11" fill="#06b6d4">AR</text>
+
+    <!-- Converge line -->
+    <line x1="30" y1="103" x2="30" y2="130" stroke="#30363d" stroke-width="1.5"/>
+    <line x1="110" y1="103" x2="110" y2="130" stroke="#30363d" stroke-width="1.5"/>
+    <line x1="190" y1="103" x2="190" y2="130" stroke="#30363d" stroke-width="1.5"/>
+    <line x1="270" y1="103" x2="270" y2="130" stroke="#30363d" stroke-width="1.5"/>
+    <line x1="30" y1="130" x2="270" y2="130" stroke="#30363d" stroke-width="1.5"/>
+    <line x1="150" y1="130" x2="150" y2="150" stroke="#30363d" stroke-width="1.5"/>
+
+    <!-- RR -->
+    <rect x="110" y="150" width="80" height="30" rx="6" fill="#21262d" stroke="#22c55e" stroke-width="1"/>
+    <text x="150" y="170" text-anchor="middle" font-family="monospace" font-size="12" fill="#22c55e" font-weight="600">RR</text>
+
+    <!-- Arrow to PC -->
+    <line x1="190" y1="165" x2="220" y2="165" stroke="#30363d" stroke-width="1.5"/>
+
+    <!-- PC -->
+    <rect x="220" y="150" width="80" height="30" rx="6" fill="#21262d" stroke="#8b949e" stroke-width="1"/>
+    <text x="260" y="170" text-anchor="middle" font-family="monospace" font-size="12" fill="#8b949e" font-weight="600">PC</text>
+
+    <!-- Labels -->
+    <text x="40" y="-10" font-family="monospace" font-size="10" fill="#484f58">Select PR</text>
+    <text x="115" y="-10" font-family="monospace" font-size="10" fill="#484f58">Describe</text>
+    <text x="0" y="118" font-family="monospace" font-size="9" fill="#484f58">Reviews</text>
+    <text x="110" y="200" font-family="monospace" font-size="10" fill="#484f58">Report</text>
+    <text x="225" y="200" font-family="monospace" font-size="10" fill="#484f58">GitHub</text>
+  </g>
+
+  <!-- Bottom accent line -->
+  <rect x="0" y="297" width="1200" height="3" fill="url(#accent)" opacity="0.4"/>
+</svg>

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "prr-kit",
+  "version": "1.0.0",
+  "description": "AI-driven Pull Request Review Framework — structured agent workflows for thorough, consistent code review",
+  "main": "tools/cli/prr-cli.js",
+  "bin": {
+    "prr-kit": "tools/prr-npx-wrapper.js",
+    "pr-review": "tools/prr-npx-wrapper.js"
+  },
+  "scripts": {
+    "prr:install": "node tools/cli/prr-cli.js install",
+    "prr:uninstall": "node tools/cli/prr-cli.js uninstall",
+    "prr:status": "node tools/cli/prr-cli.js status",
+    "test": "node test/test-agent-schema.js && node test/test-installation-components.js",
+    "test:schemas": "node test/test-agent-schema.js",
+    "test:install": "node test/test-installation-components.js",
+    "lint": "eslint . --ext .js,.cjs,.mjs --max-warnings=0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "src/",
+    "tools/",
+    "docs/assets/"
+  ],
+  "keywords": [
+    "code-review",
+    "pull-request",
+    "ai",
+    "agent",
+    "workflow",
+    "claude",
+    "cursor",
+    "windsurf",
+    "github",
+    "gitlab"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mrquangthai278/prr-kit.git"
+  },
+  "homepage": "https://github.com/mrquangthai278/prr-kit#readme",
+  "bugs": {
+    "url": "https://github.com/mrquangthai278/prr-kit/issues"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@clack/prompts": "^0.10.0",
+    "chalk": "^4.1.2",
+    "commander": "^14.0.0",
+    "csv-parse": "^6.1.0",
+    "fs-extra": "^11.3.0",
+    "glob": "^11.0.3",
+    "yaml": "^2.7.0"
+  },
+  "devDependencies": {
+    "eslint": "^9.0.0"
+  }
+}

package/src/core/agents/prr-master.agent.yaml

@@ -0,0 +1,80 @@
+agent:
+  metadata:
+    id: "_prr/core/agents/prr-master.md"
+    name: "PRR Master"
+    title: "PR Review Master Orchestrator"
+    icon: "🔍"
+    capabilities: "PR discovery, review orchestration, report generation, workflow routing, git operations"
+    hasSidecar: false
+
+  persona:
+    role: "Master PR Review Orchestrator and Workflow Router"
+    identity: "Experienced technical lead with 15+ years in code review. Expert in routing review requests to the right specialist, ensuring no important aspects are missed. Knows when a quick look suffices vs when a deep review is needed."
+    communication_style: "Direct and systematic. Always starts by confirming which PR/branch is being reviewed. Guides the team through a structured process. Summarizes what has been reviewed and what remains."
+    principles: |
+      - ALWAYS fetch latest from remote before any review operation to ensure up-to-date state
+      - ALWAYS clarify which PR/branch to review before starting any analysis
+      - Suggest the right combination of reviews based on PR type and size
+      - For security-sensitive changes: always recommend security review
+      - For performance-critical code: always recommend performance review
+      - Keep track of which reviews have been completed in the session
+
+  critical_actions:
+    - "Run [CP] Collect Project Context ONCE before the first review of a new project"
+    - "Run [SP] Select PR FIRST before any review — never review without knowing the exact branch/diff"
+    - "After Select PR, suggest running [DP] Describe PR to understand scope before diving into review"
+    - "Track completed reviews and remind user of remaining uncompleted review types"
+    - "For PRs touching auth, API keys, or user data: always suggest [SR] Security Review"
+
+  menu:
+    - trigger: "QR or fuzzy match on quick"
+      exec: "{project-root}/_prr/prr/workflows/quick/workflow.md"
+      description: "[QR] Quick Review: Full pipeline in one command — select branch → describe → all reviews → report"
+
+    - trigger: "CP or fuzzy match on collect-project-context"
+      exec: "{project-root}/_prr/prr/workflows/0-setup/collect-project-context/workflow.md"
+      description: "[CP] Collect Project Context: Scan configs, extract rules, ask domain — run once per project"
+
+    - trigger: "SP or fuzzy match on select-pr"
+      exec: "{project-root}/_prr/prr/workflows/1-discover/select-pr/workflow.md"
+      description: "[SP] Select PR: git fetch + list branches + select PR to review"
+
+    - trigger: "DP or fuzzy match on describe-pr"
+      exec: "{project-root}/_prr/prr/workflows/2-analyze/describe-pr/workflow.md"
+      description: "[DP] Describe PR: Auto-generate PR type, summary, file-by-file walkthrough"
+
+    - trigger: "GR or fuzzy match on general-review"
+      workflow: "{project-root}/_prr/prr/workflows/3-review/general-review/workflow.yaml"
+      description: "[GR] General Review: Logic, naming, readability, best practices"
+
+    - trigger: "SR or fuzzy match on security-review"
+      workflow: "{project-root}/_prr/prr/workflows/3-review/security-review/workflow.yaml"
+      description: "[SR] Security Review: OWASP top 10, injection, auth, API key exposure"
+
+    - trigger: "PR or fuzzy match on performance-review"
+      workflow: "{project-root}/_prr/prr/workflows/3-review/performance-review/workflow.yaml"
+      description: "[PR] Performance Review: N+1 queries, memory leaks, async patterns, bundle size"
+
+    - trigger: "AR or fuzzy match on architecture-review"
+      workflow: "{project-root}/_prr/prr/workflows/3-review/architecture-review/workflow.yaml"
+      description: "[AR] Architecture Review: SOLID, layering, coupling, consistency with codebase"
+
+    - trigger: "IC or fuzzy match on improve-code"
+      workflow: "{project-root}/_prr/prr/workflows/4-improve/improve-code/workflow.yaml"
+      description: "[IC] Improve Code: Concrete inline code suggestions with before/after fixes"
+
+    - trigger: "AK or fuzzy match on ask-code"
+      exec: "{project-root}/_prr/prr/workflows/5-ask/ask-code/workflow.md"
+      description: "[AK] Ask: Interactive Q&A about specific code changes in this PR"
+
+    - trigger: "RR or fuzzy match on generate-report"
+      exec: "{project-root}/_prr/prr/workflows/6-report/generate-report/workflow.md"
+      description: "[RR] Generate Report: Compile all findings into a Markdown review report"
+
+    - trigger: "PC or fuzzy match on post-comments"
+      exec: "{project-root}/_prr/prr/workflows/6-report/post-comments/workflow.md"
+      description: "[PC] Post Comments: Post inline review comments to GitHub/GitLab/Azure/Bitbucket PR"
+
+    - trigger: "HH or fuzzy match on help"
+      exec: "{project-root}/_prr/core/tasks/help.md"
+      description: "[HH] Help: Show review workflow guide and available commands"

package/src/core/module.yaml

@@ -0,0 +1,19 @@
+code: core
+name: "PR Review Core Module"
+header: "PR Review Core Configuration"
+subheader: "Configure the core settings for your PR Review installation.\nThese settings will be used across all modules and agents."
+
+user_name:
+  prompt: "What should reviewers call you? (Use your name or a team name)"
+  default: "Reviewer"
+  result: "{value}"
+
+communication_language:
+  prompt: "What language should agents use when chatting with you?"
+  default: "English"
+  result: "{value}"
+
+output_folder:
+  prompt: "Where should output files be saved?"
+  default: "_prr-output"
+  result: "{project-root}/{value}"

package/src/core/tasks/help.md

@@ -0,0 +1,37 @@
+# PR Review Help
+
+## What to do next
+
+Use `/prr-help` anytime for guidance on what to do.
+
+### Typical Review Flow
+
+**First time on a new project (run once):**
+0. **[CP] Collect Project Context** — Scan configs, extract coding rules, capture domain knowledge
+
+**Per PR — Quick mode (1 command):**
+- **[QR] Quick Review** — Full pipeline: select branch → describe → all 4 reviews → report → optional GitHub post
+
+**Per PR — Manual mode (step by step):**
+1. **[SP] Select PR** — Fetch latest, list branches, choose what to review
+2. **[DP] Describe PR** — Auto-generate PR type, summary, file-by-file walkthrough
+3. **[GR/SR/PR/AR] Review** — Run one or more specialized reviews
+4. **[IC] Improve Code** — Get concrete code suggestions with inline fixes
+5. **[AK] Ask** — Ask specific questions about the code changes
+6. **[RR] Generate Report** — Compile all findings into a Markdown report
+7. **[PC] Post Comments** — Post inline review comments to GitHub / GitLab / Azure DevOps / Bitbucket
+
+### Available Reviewer Agents
+
+- **PRR Master** 🔍 — Orchestrator, routes to all workflows
+- **General Reviewer** 👁️ — Logic, naming, readability, best practices
+- **Security Reviewer** 🔒 — OWASP, injection, auth, API key exposure
+- **Performance Reviewer** ⚡ — N+1 queries, memory leaks, async patterns
+- **Architecture Reviewer** 🏗️ — SOLID, layering, coupling, consistency
+
+### Finding Severity Levels
+
+- 🔴 **[BLOCKER]** — Must fix before merge
+- 🟡 **[WARNING]** — Should fix, with explanation
+- 🟢 **[SUGGESTION]** — Nice-to-have improvement
+- 📌 **[QUESTION]** — Needs clarification from author

package/src/core/tasks/workflow.xml

@@ -0,0 +1,22 @@
+<workflow-engine>
+  <rules>
+    <rule>NEVER load multiple step files simultaneously — one at a time only</rule>
+    <rule>ALWAYS read entire step/workflow file before taking any action</rule>
+    <rule>NEVER skip steps or optimize the sequence</rule>
+    <rule>ALWAYS update frontmatter state when writing output</rule>
+    <rule>ALWAYS halt at decision points and wait for user input</rule>
+    <rule>ALWAYS load config variables before starting any workflow</rule>
+  </rules>
+
+  <variable-resolution>
+    <pattern>{config_source}:variable_name</pattern>
+    <action>Read the YAML file at config_source path, extract the named key value</action>
+  </variable-resolution>
+
+  <step-file-protocol>
+    <load>Read the complete step file</load>
+    <execute>Follow ALL numbered sections in order</execute>
+    <state>Update frontmatter stepsCompleted array</state>
+    <next>Load next step file only when explicitly directed</next>
+  </step-file-protocol>
+</workflow-engine>