prr-kit 1.0.0

package/src/prr/workflows/1-discover/select-pr/steps/step-03-select.md

@@ -0,0 +1,127 @@
+---
+name: "step-03-select"
+description: "User selects PR/MR by number (primary) or branch names (fallback)"
+nextStepFile: "./step-04-load-diff.md"
+---
+
+# Step 3: Select PR / MR
+
+**Progress: Step 3 of 5** — Selecting review target
+
+## STEP GOAL
+
+User picks a PR/MR by number — base and head are resolved automatically from the platform.
+Fall back to explicit head + base branch selection if no platform is configured.
+
+## Sequence of Instructions
+
+### 1. Present Selection Prompt
+
+**If `pr_list_available = true`** (platform PR/MR list was shown):
+
+```
+🎯 Select a PR/MR to review:
+
+  Enter PR/MR number (e.g., 44)
+  Or type a branch name directly (e.g., feature/my-feature)
+```
+
+**HALT — wait for user to respond.**
+
+**If `pr_list_available = false`** (no platform / branch list only):
+
+Display EXACTLY:
+```
+🎯 Head branch (the branch to review)?
+
+   You can:
+     • Enter a number from the list  (e.g., 1)
+     • Type the branch name directly  (e.g., feature/my-feature)
+```
+
+**HALT — wait for head branch response.**
+
+Then display EXACTLY:
+```
+🎯 Base branch (what to diff against)?
+
+   You can:
+     • Press Enter to use the default  [main]
+     • Type the branch name directly   (e.g., develop)
+```
+
+**HALT — wait for base branch response.**
+If user presses Enter without typing, detect `origin/main` or `origin/master`.
+
+Set `selected_branch` = head input, `base_branch` = base input, `pr_number` = empty.
+Set `diff_range` = `{base_branch}...{selected_branch}`.
+Skip directly to step 4.
+
+### 2. Parse Input and Resolve Base/Head (Platform flow only)
+
+*Applies only when `pr_list_available = true`.*
+
+#### Case A: User enters a PR/MR number (e.g., `44` or `#44`)
+
+Run the appropriate command to fetch metadata:
+
+**GitHub:**
+```bash
+gh pr view {number} --repo {platform_repo} \
+  --json number,title,headRefName,baseRefName,author,body,headRefOid
+```
+Extract: `headRefName` → `selected_branch`, `baseRefName` → `base_branch`, `headRefOid` → `pr_head_sha`.
+
+**GitLab:**
+```bash
+glab mr view {number} --repo {platform_repo} --output json
+```
+Extract: `source_branch` → `selected_branch`, `target_branch` → `base_branch`.
+Get head SHA: `git -C {target_repo} rev-parse origin/{selected_branch}` → `pr_head_sha`.
+
+**Azure DevOps:**
+```bash
+az repos pr show --id {number} --output json
+```
+Extract: `sourceRefName` (strip `refs/heads/`) → `selected_branch`, `targetRefName` → `base_branch`.
+
+**Bitbucket:**
+```bash
+curl https://api.bitbucket.org/2.0/repositories/{platform_repo}/pullrequests/{number}
+```
+Extract: `source.branch.name` → `selected_branch`, `destination.branch.name` → `base_branch`.
+
+Set: `pr_number` = number, `pr_title` = title, `pr_author` = author.
+
+Display confirmation:
+```
+✓ PR #{pr_number} selected
+  Title:  {pr_title}
+  Head:   {selected_branch}
+  Base:   {base_branch}  ← from platform definition
+```
+
+#### Case B: User enters a number from the branch list (e.g., `2`)
+
+Map to branch at that position from step 2.
+Set `selected_branch` = that branch. Set `pr_number` = empty.
+Detect `base_branch`: check `origin/main` → `origin/master` → ask user.
+
+#### Case C: User enters a branch name directly (e.g., `feature/my-feature`)
+
+Set `selected_branch` = provided name (add `origin/` if missing). Set `pr_number` = empty.
+Try to find a matching PR/MR on the platform and use its base branch. If not found, detect base same as Case B.
+
+### 3. Store Selection
+
+Store for subsequent steps:
+- `selected_branch`, `base_branch`, `diff_range` = `{base_branch}...{selected_branch}`
+- `pr_number`, `pr_title`, `pr_author`, `pr_body`
+- `pr_head_sha` (or `git -C {target_repo} rev-parse origin/{selected_branch}` if not set)
+- `active_platform` = `{platform}` or `{detected_platform}`
+
+### 4. Update Frontmatter and Load Next Step
+
+Add `step-03-select` to `stepsCompleted`.
+
+Read fully and follow: `{nextStepFile}`

package/src/prr/workflows/1-discover/select-pr/steps/step-04-load-diff.md

@@ -0,0 +1,79 @@
+---
+name: "step-04-load-diff"
+description: "Load the full diff using platform CLI or git"
+nextStepFile: "./step-05-confirm.md"
+---
+
+# Step 4: Load PR Diff
+
+**Progress: Step 4 of 5** — Loading diff and commit history
+
+## STEP GOAL
+
+Load the complete diff. Use the platform's native diff command when available
+(matches exactly what reviewers see on the platform). Fall back to `git diff` otherwise.
+
+## Sequence of Instructions
+
+### 1. Load Commit Log
+
+```bash
+git -C {target_repo} log --oneline {diff_range}
+```
+
+Store as `commit_log`. Count → `commit_count`.
+
+### 2. Load Diff
+
+Use the first available method:
+
+**GitHub** (if `active_platform = github` and `pr_number` is set):
+```bash
+gh pr diff {pr_number} --repo {platform_repo}
+```
+
+**GitLab** (if `active_platform = gitlab` and `pr_number` is set):
+```bash
+glab mr diff {pr_number} --repo {platform_repo}
+```
+
+**Azure DevOps** (if `active_platform = azure` and `pr_number` is set):
+```bash
+az repos pr show --id {pr_number} --output json
+# then use git diff with the extracted base/head SHAs
+git -C {target_repo} diff {base_branch}...{selected_branch}
+```
+
+**Bitbucket / None / fallback** (any other case):
+```bash
+git -C {target_repo} diff {diff_range}
+```
+
+### 3. Load File Change Summary
+
+```bash
+git -C {target_repo} diff --stat {diff_range}
+```
+
+Store as `diff_stats`. Extract `files_changed_count`, `files_changed` list, `lines_added`, `lines_removed`.
+
+### 4. Assess Size and Set Strategy
+
+- **< 300 lines**: `diff_strategy = 'full'` ✅
+- **300–1000 lines**: `diff_strategy = 'chunked'` 📋
+- **> 1000 lines**: `diff_strategy = 'chunked'` ⚠️ warn user
+
+```
+📊 Diff loaded:
+  Platform: {active_platform}
+  Commits:  {commit_count}
+  Files:    {files_changed_count}
+  Lines:    +{lines_added} / -{lines_removed}
+  Strategy: {diff_strategy}
+```
+
+### 5. Update Frontmatter and Load Next Step
+
+Add `step-04-load-diff` to `stepsCompleted`.
+
+Read fully and follow: `{nextStepFile}`

package/src/prr/workflows/1-discover/select-pr/steps/step-05-confirm.md

@@ -0,0 +1,76 @@
+---
+name: "step-05-confirm"
+description: "Show PR scope summary and confirm before proceeding to review"
+contextOutputFile: "{review_output}/current-pr-context.yaml"
+---
+
+# Step 5: Confirm Scope
+
+**Progress: Step 5 of 5** — Confirming review scope
+
+## STEP GOAL
+
+Show a clear summary of what will be reviewed, write PR context to file, and confirm the user wants to proceed.
+
+## Sequence of Instructions
+
+### 1. Display Scope Summary
+
+Present a clear summary:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📋 PR Review Scope
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Target:  {selected_branch}
+  Base:    {base_branch}
+  PR #:    {pr_number}  (if applicable)
+  Title:   {pr_title}  (if available)
+
+📊 Diff Statistics:
+  Commits: {commit_count}
+  Files:   {files_changed_count}
+{diff_stats}
+
+⚠️  Review Strategy: {diff_strategy}
+  (chunked = reviews will process file by file for accuracy)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Recommended reviews for this PR:
+  [DP] Describe PR — understand changes before reviewing
+  [GR] General Review — always recommended
+  [SR] Security Review — if auth/API/user data touched
+  [PR] Performance Review — if DB/async/frontend affected
+  [AR] Architecture Review — if new patterns/structure added
+```
+
+### 2. Write PR Context File
+
+Write `{contextOutputFile}` with:
+
+```yaml
+pr:
+  target_branch: "{selected_branch}"
+  base_branch: "{base_branch}"
+  pr_number: "{pr_number}"
+  pr_title: "{pr_title}"
+  diff_stats: |
+    {diff_stats}
+  commit_count: {commit_count}
+  files_changed:
+    {files_changed_list}
+  diff_strategy: "{diff_strategy}"
+  date: "{date}"
+review:
+  completed: []
+  findings: []
+```
+
+### 3. Ask for Confirmation
+
+```
+✅ Ready to review. Which review would you like to run first?
+   (Enter a command from the menu, or type 'DP' to start with Describe PR)
+```
+
+**HALT — wait for user response.** The workflow is complete. User returns to the agent menu.

package/src/prr/workflows/1-discover/select-pr/workflow.md

@@ -0,0 +1,36 @@
+---
+name: select-pr
+description: "Fetch latest from remote, list branches/PRs, select target for review, load diff and confirm scope"
+main_config: "{project-root}/_prr/prr/config.yaml"
+nextStep: "./steps/step-01-fetch.md"
+---
+
+# Select PR Workflow
+
+**Goal:** Clarify exactly which PR/branch to review by fetching latest from remote, listing available branches, letting the user select, loading the diff, and confirming scope before any review begins.
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** with sequential orchestration:
+
+- Step 01: `git fetch` to ensure latest state from remote
+- Step 02: List branches sorted by recency, show commit summary
+- Step 03: User selects branch, PR number, or enters commit range
+- Step 04: Load full diff and commit log for selected PR
+- Step 05: Show scope summary (files changed, lines +/-), confirm before proceeding
+
+**Rules (NO EXCEPTIONS):**
+- 🛑 NEVER start reviewing without completing this workflow first
+- 📖 Read entire step file before executing
+- ⏸️ ALWAYS halt at user selection points — never auto-select
+- 💾 Write PR context to `{review_output}/current-pr-context.yaml` after confirmation
+
+## INITIALIZATION
+
+Load config from `{main_config}` and resolve:
+- `project_name`, `target_repo`, `user_name`, `communication_language`
+- `review_output`, `github_repo`, `date` (system-generated)
+
+## EXECUTION
+
+Read fully and follow: `{nextStep}`

package/src/prr/workflows/2-analyze/describe-pr/steps/step-01-load-context.md

@@ -0,0 +1,37 @@
+---
+name: "step-01-load-context"
+description: "Load PR context and diff for analysis"
+nextStepFile: "./step-02-classify.md"
+---
+
+# Step 1: Load PR Context
+
+## STEP GOAL
+
+Load the PR context file and the actual code diff for analysis.
+
+## Sequence of Instructions
+
+### 1. Load PR Context
+
+Read `{review_output}/current-pr-context.yaml`.
+
+If file not found:
+```
+❌ No PR selected yet. Please run [SP] Select PR first.
+```
+Stop workflow.
+
+### 2. Load the Diff
+
+Run `git diff {base_branch}...{target_branch}` in `{target_repo}`.
+
+Also run `git log --oneline {base_branch}...{target_branch}` for commit messages.
+
+### 3. Load Commit Messages
+
+Commit messages often reveal the intent of the PR — critical for understanding why changes were made.
+
+### 4. Update and Load Next Step
+
+Add `step-01-load-context` to `stepsCompleted`. Load: `{nextStepFile}`

package/src/prr/workflows/2-analyze/describe-pr/steps/step-02-classify.md

@@ -0,0 +1,50 @@
+---
+name: "step-02-classify"
+description: "Classify PR type and determine review recommendations"
+nextStepFile: "./step-03-walkthrough.md"
+---
+
+# Step 2: Classify PR
+
+## STEP GOAL
+
+Analyze the diff and commit messages to classify the PR type and generate review recommendations.
+
+## Sequence of Instructions
+
+### 1. Classify PR Type
+
+Analyze the diff to determine the PRIMARY type (pick the best match):
+
+| Type | Indicators |
+|------|-----------|
+| `bugfix` | Fix in logic, error handling, condition fix |
+| `feature` | New files, new functions, new UI components |
+| `refactor` | Same behavior, restructured code, renamed variables |
+| `performance` | Caching, query optimization, async improvements |
+| `security` | Auth changes, input validation, dependency updates |
+| `test` | Only test file changes |
+| `docs` | Only documentation/comment changes |
+| `config` | Config files, env, CI/CD changes |
+| `chore` | Dependency updates, tooling, build changes |
+
+### 2. Assess Risk Level
+
+Based on PR type and what was changed:
+- **🔴 High Risk**: Auth changes, payment logic, user data handling, security-critical paths
+- **🟡 Medium Risk**: Core business logic, API changes, database schema
+- **🟢 Low Risk**: UI tweaks, docs, test additions, minor refactors
+
+### 3. Generate Review Recommendations
+
+Based on classification, recommend specific reviews:
+- bugfix → GR (general) + SR (if security-related)
+- feature → GR + AR (architecture) + PR (if DB/async)
+- security → SR (mandatory) + GR
+- performance → PR + GR
+- refactor → AR + GR
+- All high-risk PRs → SR mandatory
+
+### 4. Load Next Step
+
+Add `step-02-classify` to `stepsCompleted`. Load: `{nextStepFile}`

package/src/prr/workflows/2-analyze/describe-pr/steps/step-03-walkthrough.md

@@ -0,0 +1,41 @@
+---
+name: "step-03-walkthrough"
+description: "Generate file-by-file walkthrough explaining what changed and why"
+nextStepFile: "./step-04-output.md"
+---
+
+# Step 3: File-by-File Walkthrough
+
+## STEP GOAL
+
+Generate a concise walkthrough of each changed file — what changed, why it changed (based on diff + commit context), and what reviewers should pay attention to.
+
+## Sequence of Instructions
+
+### 1. Group Files by Purpose
+
+Group changed files logically:
+- **Backend** (controllers, services, models, routes, middleware)
+- **Frontend** (components, views, stores, utils)
+- **Config/Infrastructure** (docker, env, CI, package.json)
+- **Tests**
+- **Docs**
+
+### 2. For Each Changed File, Generate Summary
+
+For each file (or group of related files), describe:
+- **What changed**: 1-2 sentences on the actual change
+- **Why** (inferred from commit messages and context): 1 sentence
+- **Review focus**: what should reviewers specifically look at
+
+Format:
+```
+📄 backend/controllers/authController.js (+45 -12)
+   What: Added JWT refresh token endpoint and token blacklisting logic
+   Why:  Fixes security issue where expired tokens could still be used
+   Focus: Check token validation logic and blacklist cleanup mechanism
+```
+
+### 3. Load Next Step
+
+Add `step-03-walkthrough` to `stepsCompleted`. Load: `{nextStepFile}`

package/src/prr/workflows/2-analyze/describe-pr/steps/step-04-output.md

@@ -0,0 +1,50 @@
+---
+name: "step-04-output"
+description: "Write PR description to file and display summary"
+outputFile: "{review_output}/pr-description-{date}.md"
+templateFile: "../templates/pr-description.template.md"
+---
+
+# Step 4: Output PR Description
+
+## STEP GOAL
+
+Compile all analysis into a structured PR description file and display summary to the reviewer.
+
+## Sequence of Instructions
+
+### 1. Generate PR Description
+
+Using the template at `{templateFile}`, generate the PR description with:
+- PR metadata (branch, base, PR number if applicable)
+- PR type and risk level
+- Executive summary (3-5 bullet points of key changes)
+- File-by-file walkthrough
+- Recommended reviews with rationale
+
+### 2. Write to File
+
+Write to `{outputFile}` (replace {date} with actual date: YYYY-MM-DD).
+
+### 3. Update PR Context
+
+Update `{review_output}/current-pr-context.yaml`:
+- Add `description_generated: true`
+- Add `pr_type: "{classified_type}"`
+- Add `risk_level: "{risk_level}"`
+
+### 4. Display Summary
+
+Show the user:
+```
+✅ PR Description generated: {outputFile}
+
+PR Type: {type} | Risk: {risk_level}
+Summary:
+{executive_summary_bullets}
+
+Recommended next steps:
+{recommended_reviews}
+```
+
+Workflow complete. Return to agent menu.

package/src/prr/workflows/2-analyze/describe-pr/templates/pr-description.template.md

@@ -0,0 +1,51 @@
+---
+pr_branch: "{{target_branch}}"
+base_branch: "{{base_branch}}"
+pr_number: "{{pr_number}}"
+pr_type: "{{pr_type}}"
+risk_level: "{{risk_level}}"
+date: "{{date}}"
+generated_by: "prr-describe-pr"
+stepsCompleted: []
+---
+
+# PR Review: {{pr_title}}
+
+**Branch:** `{{target_branch}}` → `{{base_branch}}`
+{{#if pr_number}}**PR #{{pr_number}}** | {{/if}}**Type:** {{pr_type}} | **Risk:** {{risk_level}} | **Date:** {{date}}
+
+---
+
+## Executive Summary
+
+{{executive_summary}}
+
+---
+
+## PR Statistics
+
+- **Commits:** {{commit_count}}
+- **Files Changed:** {{files_changed_count}}
+- **Lines:** +{{lines_added}} / -{{lines_removed}}
+
+### Changed Files Overview
+
+```
+{{diff_stats}}
+```
+
+---
+
+## File-by-File Walkthrough
+
+{{walkthrough}}
+
+---
+
+## Recommended Reviews
+
+{{recommended_reviews}}
+
+---
+
+*Generated by PR Review Framework*

package/src/prr/workflows/2-analyze/describe-pr/workflow.md

@@ -0,0 +1,28 @@
+---
+name: describe-pr
+description: "Auto-generate PR type classification, executive summary, and file-by-file walkthrough"
+main_config: "{project-root}/_prr/prr/config.yaml"
+nextStep: "./steps/step-01-load-context.md"
+---
+
+# Describe PR Workflow
+
+**Goal:** Generate a structured PR description — type classification, executive summary, and file-by-file walkthrough — to give reviewers full context before diving into detailed review.
+
+## WORKFLOW ARCHITECTURE
+
+4-step sequential process:
+1. Load PR context (from select-pr output)
+2. Classify PR type (bugfix/feature/refactor/docs/test/chore)
+3. Generate file-by-file walkthrough (what changed and why)
+4. Output structured PR description to file
+
+## INITIALIZATION
+
+Load config from `{main_config}`.
+Load PR context from `{review_output}/current-pr-context.yaml`.
+If context file does not exist, instruct user to run [SP] Select PR first.
+
+## EXECUTION
+
+Read fully and follow: `{nextStep}`

package/src/prr/workflows/3-review/architecture-review/checklist.md

@@ -0,0 +1,22 @@
+---
+title: "Architecture Review Completion Checklist"
+validation-target: "Architecture review output file"
+---
+
+# Architecture Review Checklist
+
+## Coverage
+- [ ] Layer/separation of concerns checked
+- [ ] Coupling and module dependencies reviewed
+- [ ] Consistency with existing codebase patterns assessed
+- [ ] SOLID violations checked (only real ones, not theoretical)
+
+## Finding Quality
+- [ ] Every finding references the EXISTING pattern that should be followed
+- [ ] Over-engineering suggestions are avoided (consistency > theoretical purity)
+- [ ] Every finding has: file path + what pattern was violated
+- [ ] Justification provided for why the finding matters (not just "violates SOLID")
+
+## Output
+- [ ] Findings written to `{review_output}/architecture-review-{date}.md`
+- [ ] PR context updated with `architecture-review` in completed list

package/src/prr/workflows/3-review/architecture-review/instructions.xml

@@ -0,0 +1,68 @@
+<workflow>
+  <critical>Workflow engine rules: {project-root}/_prr/core/tasks/workflow.xml</critical>
+  <critical>Communicate all responses in {communication_language}</critical>
+  <critical>Consistency with EXISTING codebase patterns is paramount — avoid over-engineering or introducing new patterns without strong justification</critical>
+  <critical>Always consider: would a new team member understand where this code belongs and why?</critical>
+
+  <step n="1" goal="Load PR context and understand the codebase structure">
+    <check if="{pr_context} does not exist">
+      <output>❌ No PR selected. Please run [SP] Select PR first.</output>
+      <stop/>
+    </check>
+    <action>Read {pr_context} and load git diff</action>
+    <action>Also examine surrounding non-changed files to understand existing patterns</action>
+    <output>🏗️ Starting Architecture Review
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Focus: Layer violations | Coupling | SOLID | Codebase consistency
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━</output>
+  </step>
+
+  <step n="2" goal="Check layer/separation of concerns violations">
+    <check-list id="layers">
+      <item>Business logic in controllers/routes (should be in services)</item>
+      <item>Database queries in wrong layer (direct DB access from controller bypassing service)</item>
+      <item>Presentation logic in backend (HTML generation in services)</item>
+      <item>Infrastructure concerns mixed with domain logic</item>
+      <item>Each function/class: does it have a single clear responsibility?</item>
+    </check-list>
+  </step>
+
+  <step n="3" goal="Check coupling and cohesion">
+    <check-list id="coupling">
+      <item>Tight coupling: does this change force changes in many unrelated files?</item>
+      <item>New module dependencies: are new imports appropriate? circular dependencies introduced?</item>
+      <item>Interface design: are public APIs (function signatures, REST endpoints) clean and stable?</item>
+      <item>Shared mutable state: global state introduced or modified across modules?</item>
+    </check-list>
+  </step>
+
+  <step n="4" goal="Check consistency with existing codebase patterns">
+    <check-list id="consistency">
+      <item>Naming conventions: matches existing naming style (camelCase vs snake_case, etc.)?</item>
+      <item>File/folder structure: new files placed where convention dictates?</item>
+      <item>Error handling pattern: matches how errors are handled elsewhere in the codebase?</item>
+      <item>API response format: matches existing response structure?</item>
+      <item>New patterns: is a new pattern introduced? Is it justified and documented?</item>
+    </check-list>
+  </step>
+
+  <step n="5" goal="SOLID principles (only flag real violations, not theoretical ones)">
+    <check-list id="solid">
+      <item>SRP: class/module doing more than one thing AND causing maintenance problems?</item>
+      <item>OCP: existing code modified instead of extended (when extension was clearly better)?</item>
+      <item>LSP: subclass behavior violates parent contract?</item>
+      <item>ISP: interface forces implementors to depend on methods they don't use?</item>
+      <item>DIP: high-level module depends directly on low-level implementation (not abstraction)?</item>
+    </check-list>
+    <note>Only flag SOLID violations when they cause REAL maintainability or extensibility problems — not theoretical purity</note>
+  </step>
+
+  <step n="6" goal="Compile and write findings">
+    <action>Group findings: Layer Violations | Coupling Issues | Consistency Problems | SOLID Violations</action>
+    <action>For each finding: reference the EXISTING pattern that should be followed instead</action>
+    <action>Write findings to {output_file}</action>
+    <action>Update {pr_context}: add 'architecture-review' to completed list</action>
+    <output>🏗️ Architecture review complete.
+Run [RR] Generate Report to compile all findings.</output>
+  </step>
+</workflow>