prr-kit 1.0.0

package/src/prr/workflows/6-report/generate-report/steps/step-02-organize.md

@@ -0,0 +1,38 @@
+---
+name: "step-02-organize"
+description: "Organize findings by severity and category for the report"
+nextStepFile: "./step-03-write.md"
+---
+
+# Step 2: Organize Findings
+
+## Sequence of Instructions
+
+### 1. Sort by Severity
+
+Order: 🔴 Blockers/Critical → 🟡 Warnings/High → 🟡 Medium → 🟢 Suggestions/Low → 📌 Questions
+
+### 2. Group by Category
+
+Within each severity level, group by review category:
+- 🔒 Security
+- ⚡ Performance
+- 🏗️ Architecture
+- 👁️ General Quality
+- 💡 Improvements
+
+### 3. Create Executive Summary
+
+Write 3-5 bullet points summarizing the overall review:
+- Overall quality assessment (1 sentence)
+- Highest priority issues to address
+- Positive findings (good practices found)
+- Recommendation: approved / needs changes / request changes
+
+### 4. Identify Files with Multiple Issues
+
+List files that have 3+ findings — these may need more significant rework.
+
+### 5. Load Next Step
+
+Add `step-02-organize` to `stepsCompleted`. Load: `{nextStepFile}`

package/src/prr/workflows/6-report/generate-report/steps/step-03-write.md

@@ -0,0 +1,44 @@
+---
+name: "step-03-write"
+description: "Write the final review report to file"
+outputFile: "{review_output}/review-report-{pr_branch}-{date}.md"
+templateFile: "../templates/review-report.template.md"
+---
+
+# Step 3: Write Report
+
+## Sequence of Instructions
+
+### 1. Generate Report
+
+Using `{templateFile}`, write the complete review report to `{outputFile}`.
+
+The report includes:
+- PR metadata and review summary
+- Executive summary with overall verdict
+- All findings organized by severity and category
+- Files with multiple issues highlighted
+- Recommended actions (must-fix vs nice-to-have)
+
+### 2. Display Completion
+
+```
+✅ Review Report Generated!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📄 File: {outputFile}
+
+Summary:
+  🔴 Blockers: {blocker_count}
+  🟡 Warnings: {warning_count}
+  🟢 Suggestions: {suggestion_count}
+  📌 Questions: {question_count}
+
+Verdict: {verdict}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Next steps:
+  [PC] Post Comments — post these findings to GitHub PR
+  or share the report file directly with the PR author
+```
+
+**Workflow complete.** Return to agent menu.

package/src/prr/workflows/6-report/generate-report/templates/review-report.template.md

@@ -0,0 +1,78 @@
+---
+pr_branch: "{{target_branch}}"
+base_branch: "{{base_branch}}"
+pr_number: "{{pr_number}}"
+date: "{{date}}"
+verdict: "{{verdict}}"
+reviews_completed:
+{{reviews_completed_list}}
+stepsCompleted: []
+---
+
+# Code Review Report: {{pr_title}}
+
+**PR:** `{{target_branch}}` → `{{base_branch}}`
+{{#if pr_number}}**GitHub PR #{{pr_number}}** | {{/if}}**Date:** {{date}} | **Reviewer:** {{user_name}}
+
+---
+
+## Executive Summary
+
+{{executive_summary}}
+
+**Verdict:** {{verdict}}
+
+| Category | 🔴 Blockers | 🟡 Warnings | 🟢 Suggestions |
+|----------|------------|------------|----------------|
+| 🔒 Security | {{security_blockers}} | {{security_warnings}} | {{security_suggestions}} |
+| ⚡ Performance | {{perf_blockers}} | {{perf_warnings}} | {{perf_suggestions}} |
+| 🏗️ Architecture | {{arch_blockers}} | {{arch_warnings}} | {{arch_suggestions}} |
+| 👁️ General | {{general_blockers}} | {{general_warnings}} | {{general_suggestions}} |
+| **Total** | **{{total_blockers}}** | **{{total_warnings}}** | **{{total_suggestions}}** |
+
+---
+
+## 🔴 Blockers — Must Fix Before Merge
+
+{{blockers_section}}
+
+---
+
+## 🟡 Warnings — Should Fix
+
+{{warnings_section}}
+
+---
+
+## 🟢 Suggestions — Nice to Have
+
+{{suggestions_section}}
+
+---
+
+## 📌 Questions for Author
+
+{{questions_section}}
+
+---
+
+## 💡 Code Improvement Suggestions
+
+{{improvements_section}}
+
+---
+
+## Files with Multiple Issues
+
+{{files_with_issues}}
+
+---
+
+## ✅ Positive Observations
+
+{{positive_observations}}
+
+---
+
+*Generated by PR Review Framework*
+*Reviews completed: {{reviews_completed}}*

package/src/prr/workflows/6-report/generate-report/workflow.md

@@ -0,0 +1,26 @@
+---
+name: generate-report
+description: "Compile all review findings into a structured Markdown review report"
+main_config: "{project-root}/_prr/prr/config.yaml"
+nextStep: "./steps/step-01-collect.md"
+---
+
+# Generate Report Workflow
+
+**Goal:** Collect all findings from completed review workflows and compile them into a single, well-structured Markdown review report.
+
+## WORKFLOW ARCHITECTURE
+
+3-step process:
+1. Collect findings from all completed review output files
+2. Organize by severity (🔴 → 🟡 → 🟢) and category
+3. Write final report using the review report template
+
+## INITIALIZATION
+
+Load config from `{main_config}`.
+Load PR context from `{review_output}/current-pr-context.yaml`.
+
+## EXECUTION
+
+Read fully and follow: `{nextStep}`

package/src/prr/workflows/6-report/post-comments/steps/step-01-format.md

@@ -0,0 +1,166 @@
+---
+name: "step-01-format"
+description: "Parse findings and build platform-specific comment payload"
+nextStepFile: "./step-02-post.md"
+---
+
+# Step 1: Build Comment Payload
+
+## Sequence of Instructions
+
+### 1. Check Prerequisites
+
+Verify `{review_output}/current-pr-context.yaml` exists and contains:
+- `pr_number` — if missing, show: `❌ No PR number found. Run [SP] Select PR first.`
+- `target_branch`, `base_branch`
+
+Verify platform CLI is available:
+
+| Platform | Check command | Error message |
+|----------|--------------|---------------|
+| github | `gh auth status` | `❌ Run: gh auth login` |
+| gitlab | `glab auth status` | `❌ Run: glab auth login` |
+| azure | `az account show` | `❌ Run: az login && az devops configure` |
+| bitbucket | check env `BB_TOKEN` or `~/.config/bb` | `❌ Set Bitbucket credentials` |
+| none | — | show: `ℹ️ No platform configured — findings saved to report only.` then stop |
+
+### 2. Get Head Commit SHA
+
+**GitHub / GitLab / Bitbucket:**
+```bash
+git -C {target_repo} rev-parse origin/{selected_branch}
+```
+Or use `{pr_head_sha}` if already stored from select-pr step.
+
+**Azure DevOps:**
+```bash
+az repos pr show --id {pr_number} --query lastMergeSourceCommit.commitId -o tsv
+```
+
+Store as `{commit_sha}`.
+
+### 3. Load Review Report
+
+Find the latest report in `{review_output}/review-*.md`.
+Sort by modification time, take the most recent.
+
+### 4. Parse All Findings
+
+Scan the report and extract every finding:
+- `severity`: 🔴 Blocker / 🟡 Warning / 🟢 Suggestion / 📌 Question
+- `category`: security / performance / architecture / general
+- `file_path`: relative path (e.g. `src/auth/login.js`) — null if not specified
+- `line_number`: integer — null if not specified
+- `description`: the issue text
+- `suggested_fix`: fix/suggestion text
+
+**Classify:**
+- **Inline candidates**: `file_path` and `line_number` both present
+- **Fallback findings**: no file or line reference
+
+Limit inline comments to 30 max: include all 🔴 Blockers first, then 🟡 Warnings, then 🟢 Suggestions. Move overflow to fallback.
+
+### 5. Format Comment Bodies
+
+**🔴 Blocker:**
+```
+🔴 **[BLOCKER]** {emoji} {description}
+**Risk:** {what could go wrong}
+**Fix:** {suggested_fix}
+```
+
+**🟡 Warning:**
+```
+🟡 **[WARNING]** {emoji} {description}
+**Why it matters:** {explanation}
+**Suggestion:** {suggested_fix}
+```
+
+**🟢 Suggestion:**
+```
+🟢 **[SUGGESTION]** {description}
+{suggested_fix}
+```
+
+Category emojis: 🔒 security · ⚡ performance · 🏗️ architecture · 👁️ general
+
+### 6. Build Summary Body
+
+```markdown
+## 🔍 AI Code Review
+
+**PR:** `{selected_branch}` → `{base_branch}` | **Date:** {date} | **Reviewer:** {user_name}
+
+**Verdict:** {verdict}
+
+| Category | 🔴 | 🟡 | 🟢 |
+|----------|----|----|----|
+| 🔒 Security | {n} | {n} | {n} |
+| ⚡ Performance | {n} | {n} | {n} |
+| 🏗️ Architecture | {n} | {n} | {n} |
+| 👁️ General | {n} | {n} | {n} |
+
+### Executive Summary
+{bullets}
+
+{fallback_findings_section}
+
+---
+*{inline_count} inline comments on code lines*
+```
+
+Verdict logic: any 🔴 → `REQUEST_CHANGES` / only 🟡 → `COMMENT` / none → `APPROVE`
+
+### 7. Build Platform Payload
+
+**GitHub** — single JSON file for Reviews API:
+```json
+{
+  "commit_id": "{commit_sha}",
+  "body": "{summary_body}",
+  "event": "REQUEST_CHANGES|COMMENT|APPROVE",
+  "comments": [
+    { "path": "{file_path}", "line": {line_number}, "side": "RIGHT", "body": "{body}" }
+  ]
+}
+```
+Write to `{review_output}/.prr-payload.json`.
+
+**GitLab** — separate JSON per inline comment:
+```json
+{ "body": "{body}", "position": { "base_sha": "{base_sha}", "head_sha": "{commit_sha}",
+  "start_sha": "{base_sha}", "position_type": "text",
+  "new_path": "{file_path}", "new_line": {line_number} } }
+```
+Write each as `{review_output}/.prr-payload-{n}.json`. Write summary as `.prr-summary.md`.
+
+**Azure DevOps** — thread per inline comment:
+```json
+{ "comments": [{ "parentCommentId": 0, "content": "{body}", "commentType": 1 }],
+  "threadContext": { "filePath": "{file_path}",
+    "rightFileStart": { "line": {line_number}, "offset": 1 },
+    "rightFileEnd": { "line": {line_number}, "offset": 1 } },
+  "status": "active" }
+```
+Write each as `{review_output}/.prr-thread-{n}.json`.
+
+**Bitbucket** — inline comment per finding:
+```json
+{ "content": { "raw": "{body}" },
+  "inline": { "to": {line_number}, "path": "{file_path}" } }
+```
+Write each as `{review_output}/.prr-bb-{n}.json`.
+
+### 8. Display Preview
+
+```
+📋 Payload ready:
+  Platform:          {active_platform}
+  Inline comments:   {inline_count}
+  Fallback comments: {fallback_count}
+  Verdict:           {event}
+```
+
+### 9. Load Next Step
+
+Add `step-01-format` to `stepsCompleted`. Load: `{nextStepFile}`

package/src/prr/workflows/6-report/post-comments/steps/step-02-post.md

@@ -0,0 +1,97 @@
+---
+name: "step-02-post"
+description: "Post comments via platform CLI/API, verify, clean up"
+---
+
+# Step 2: Post to Platform
+
+## Sequence of Instructions
+
+### 1. Post Based on Platform
+
+**GitHub:**
+```bash
+gh api repos/{platform_repo}/pulls/{pr_number}/reviews \
+  --method POST \
+  --header "Accept: application/vnd.github+json" \
+  --input {review_output}/.prr-payload.json
+```
+
+Handle 422 (line not in diff): remove the offending inline comment from payload, add to summary body, retry.
+
+**GitLab:**
+```bash
+# Post summary as MR note
+glab mr note {pr_number} --repo {platform_repo} --message "$(cat {review_output}/.prr-summary.md)"
+
+# Post each inline comment
+for payload in {review_output}/.prr-payload-*.json; do
+  glab api projects/{encoded_repo}/merge_requests/{pr_number}/discussions \
+    --method POST --input "$payload"
+done
+```
+Where `{encoded_repo}` = `{platform_repo}` with `/` replaced by `%2F`.
+
+**Azure DevOps:**
+```bash
+# Post summary as PR comment
+az repos pr comment add --id {pr_number} --comment "$(cat {review_output}/.prr-summary.md)"
+
+# Post each inline thread
+for payload in {review_output}/.prr-thread-*.json; do
+  az repos pr thread create --id {pr_number} \
+    --template-file "$payload"
+done
+```
+
+**Bitbucket:**
+```bash
+# Post summary
+curl -s -X POST \
+  "https://api.bitbucket.org/2.0/repositories/{platform_repo}/pullrequests/{pr_number}/comments" \
+  -H "Authorization: Bearer {BB_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d "{\"content\": {\"raw\": \"$(cat {review_output}/.prr-summary.md)\"}}"
+
+# Post each inline comment
+for payload in {review_output}/.prr-bb-*.json; do
+  curl -s -X POST \
+    "https://api.bitbucket.org/2.0/repositories/{platform_repo}/pullrequests/{pr_number}/comments" \
+    -H "Authorization: Bearer {BB_TOKEN}" \
+    -H "Content-Type: application/json" \
+    -d "@$payload"
+done
+```
+
+### 2. Verify
+
+Confirm the post was successful by checking for a `200` or `201` response.
+
+**GitHub:** `gh pr view {pr_number} --repo {platform_repo} --json reviews --jq '.reviews[-1].state'`
+**GitLab:** `glab mr view {pr_number} --repo {platform_repo} --output json | jq '.user_notes_count'`
+**Azure:** `az repos pr thread list --id {pr_number} --query "length(@)"`
+**Bitbucket:** check response `id` field from the post
+
+### 3. Clean Up Temp Files
+
+```bash
+rm -f {review_output}/.prr-payload*.json \
+       {review_output}/.prr-summary.md \
+       {review_output}/.prr-thread-*.json \
+       {review_output}/.prr-bb-*.json
+```
+
+### 4. Display Completion
+
+```
+✅ Review Posted!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Platform:  {active_platform}
+  PR/MR #:   {pr_number}
+  Inline:    {inline_count} comments on code lines
+  Verdict:   {verdict_label}
+  Link:      {pr_url}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Workflow complete.** Return to agent menu.

package/src/prr/workflows/6-report/post-comments/workflow.md

@@ -0,0 +1,45 @@
+---
+name: post-comments
+description: "Post review findings as inline comments on the PR/MR via platform CLI"
+main_config: "{project-root}/_prr/prr/config.yaml"
+nextStep: "./steps/step-01-format.md"
+---
+
+# Post Comments Workflow
+
+**Goal:** Post review findings as **inline comments on the exact code lines** of the PR/MR, plus a formal summary — using the appropriate platform CLI.
+
+## SUPPORTED PLATFORMS
+
+| Platform | Tool | Inline Comments | Summary Review |
+|----------|------|----------------|----------------|
+| GitHub | `gh api` | ✅ GitHub Reviews API | ✅ |
+| GitLab | `glab` / GitLab API | ✅ MR note threads | ✅ |
+| Azure DevOps | `az devops` | ✅ PR thread comments | ✅ |
+| Bitbucket | Bitbucket REST API | ✅ inline comments | ✅ |
+| None / local | — | ❌ not available | saves to file |
+
+## WORKFLOW ARCHITECTURE
+
+2-step process:
+1. Parse findings → extract file/line → build platform-specific payload
+2. Post via platform CLI/API → verify → clean up
+
+## PREREQUISITES
+
+Depends on `{active_platform}`:
+- **GitHub**: `gh` CLI authenticated — `gh auth status`
+- **GitLab**: `glab` CLI authenticated — `glab auth status`
+- **Azure DevOps**: `az` CLI with `azure-devops` extension — `az devops configure`
+- **Bitbucket**: Bitbucket App Password set in `~/.config/bb` or env vars
+- **None**: no prerequisites — saves report only
+
+## INITIALIZATION
+
+Load config from `{main_config}`.
+Load PR context from `{review_output}/current-pr-context.yaml`.
+Use `{active_platform}` (or detect from `{platform}` config).
+
+## EXECUTION
+
+Read fully and follow: `{nextStep}`