prr-kit 1.0.0

package/src/prr/workflows/0-setup/collect-project-context/steps/step-02-extract-rules.md

@@ -0,0 +1,131 @@
+---
+name: "step-02-extract-rules"
+description: "Extract and summarize actionable coding rules from the scanned files"
+nextStepFile: "./step-03-ask-context.md"
+---
+
+# Step 2: Extract Coding Rules
+
+## Sequence of Instructions
+
+### 1. Extract ESLint Rules (if found)
+
+From the ESLint config, extract rules that are set to `"error"` or `2` (hard rules) and `"warn"` or `1` (soft rules).
+
+Focus on rules with reviewer relevance:
+- `no-unused-vars`, `no-console`, `no-debugger` → code quality
+- `eqeqeq`, `no-implicit-coercion` → logic correctness
+- `import/order`, `import/no-cycle` → architecture
+- Any custom plugin rules (e.g. `vue/`, `react/`, `@typescript-eslint/`)
+- `security/` plugin rules if present
+
+Build a concise rule summary:
+```
+ESLint hard rules: no-unused-vars, eqeqeq, @typescript-eslint/no-explicit-any
+ESLint soft rules: no-console, prefer-const
+Vue-specific: vue/no-unused-components, vue/component-name-in-template-casing
+```
+
+### 2. Extract TypeScript Strictness (if found)
+
+From `tsconfig.json`, note:
+- `strict: true/false`
+- `noImplicitAny`, `strictNullChecks`, `noUnusedLocals`
+- `paths` aliases (e.g. `@/` → `src/`) — important for import review
+
+### 3. Extract Naming Conventions
+
+From all scanned files, build a naming conventions map:
+
+| Thing | Convention | Example | Source |
+|-------|-----------|---------|--------|
+| Vue components | PascalCase | `UserCard.vue` | CONTRIBUTING.md |
+| Composables | camelCase + `use` prefix | `useAuth.js` | CONTRIBUTING.md |
+| Constants | UPPER_SNAKE_CASE | `MAX_RETRIES` | eslint rule |
+| API endpoints | kebab-case | `/api/user-profile` | ARCHITECTURE.md |
+| DB tables | snake_case | `user_sessions` | schema files |
+| Test files | `*.spec.ts` or `*.test.ts` | `auth.spec.ts` | vitest config |
+
+If a convention is NOT documented, infer from existing files:
+```bash
+# Check actual naming in the repo (sample 10 files per type)
+ls {target_repo}/src/components/*.vue 2>/dev/null | head -10
+ls {target_repo}/src/composables/*.{js,ts} 2>/dev/null | head -10
+ls {target_repo}/src/services/*.{js,ts} 2>/dev/null | head -10
+```
+
+Note inferred conventions separately from documented ones.
+
+### 4. Extract Architecture Patterns
+
+From architecture docs and code structure, identify:
+
+**Layer structure** (which layer calls which):
+```
+e.g.: routes → controllers → services → repositories → DB
+e.g.: pages → composables → stores → API client → backend
+```
+
+**Prohibited cross-layer calls** (if documented):
+- "Services must not import from controllers"
+- "Components must not call API directly — use stores"
+- "Business logic must not live in route handlers"
+
+**Established patterns to follow:**
+- Error handling pattern (try/catch in service? global handler? Result type?)
+- API response format (does the project have a standard `{ data, error, meta }` wrapper?)
+- Auth check pattern (middleware? decorator? manual in each handler?)
+- Logging pattern (which logger, log levels, structured vs string)
+
+**Scan for pattern evidence:**
+```bash
+# Check how existing API endpoints handle errors
+grep -r "catch" {target_repo}/src --include="*.{js,ts}" -l | head -5
+# Check existing service layer pattern
+ls {target_repo}/src/services/ 2>/dev/null | head -10
+```
+
+### 5. Extract Test Conventions
+
+From test config and existing test files:
+- Test file location pattern (`__tests__/` vs `*.spec.ts` co-located vs `test/`)
+- What is expected to be tested (unit? integration? e2e?)
+- Test utilities used (custom render wrappers, fixture factories, etc.)
+- Coverage threshold if configured
+
+### 6. Compile Extracted Rules Summary
+
+Build a structured in-memory summary to pass to step-03:
+
+```yaml
+linting:
+  hard_errors:
+    - "no-unused-vars"
+    - "eqeqeq"
+  soft_warnings:
+    - "no-console"
+  typescript_strict: true
+
+naming:
+  documented:
+    - { thing: "Vue components", convention: "PascalCase", example: "UserCard.vue" }
+  inferred:
+    - { thing: "service files", convention: "camelCase", example: "authService.js" }
+
+architecture:
+  layer_order: "routes → services → repositories"
+  prohibited:
+    - "No business logic in route handlers"
+  patterns:
+    error_handling: "try/catch in services, global error middleware in app.js"
+    api_format: "{ data, error } wrapper"
+
+testing:
+  framework: "vitest"
+  file_pattern: "*.spec.ts"
+  location: "co-located with source files"
+```
+
+### 7. Load Next Step
+
+Add `step-02-extract-rules` to `stepsCompleted`. Load: `{nextStepFile}`

package/src/prr/workflows/0-setup/collect-project-context/steps/step-03-ask-context.md

@@ -0,0 +1,194 @@
+---
+name: "step-03-ask-context"
+description: "Ask user for domain knowledge and architectural context that cannot be inferred from files"
+nextStepFile: "./step-04-save-context.md"
+---
+
+# Step 3: Ask for Domain & Architecture Context
+
+## Sequence of Instructions
+
+### 1. Present Scan Summary
+
+Show what was auto-discovered and what is still unknown:
+
+```
+📋 Auto-discovered context:
+   ✅ Stack: {detected_stack}
+   ✅ Linting: {n} hard rules, {n} soft rules
+   ✅ Naming conventions: {n} documented, {n} inferred
+   ✅ Architecture layers: {layer_order or "not documented"}
+   ✅ Test framework: {framework or "not found"}
+
+❓ Still need from you ({n} questions):
+```
+
+### 2. Ask Domain Questions
+
+Ask these questions **one group at a time**. Wait for answer before continuing.
+
+---
+
+**Group A: Business Domain**
+
+```
+What does this project do? (1-3 sentences about the business domain)
+
+Examples:
+  "E-commerce platform for B2B wholesale orders"
+  "Internal HR system for leave requests and payroll"
+  "SaaS analytics dashboard for marketing teams"
+
+Your answer:
+```
+
+Halt and wait for answer.
+
+Then ask:
+
+```
+What are the key domain entities? (the main "things" the system manages)
+
+Examples: User, Order, Product, Invoice, Report, Campaign, Shift, etc.
+
+Your answer (comma-separated):
+```
+
+Halt and wait.
+
+Then ask:
+
+```
+Are there any domain-specific rules that code must enforce?
+(business rules reviewers should verify, not just code quality)
+
+Examples:
+  "An Order cannot transition from SHIPPED back to PENDING"
+  "A User must have at least one Role"
+  "Discount cannot exceed 50% without manager approval flag"
+  "All monetary values must be stored as integers (cents), never floats"
+
+Your answer (or press Enter to skip):
+```
+
+Halt and wait.
+
+---
+
+**Group B: Review Priorities**
+
+```
+What should reviewers focus on MOST for this project?
+(select all that apply, or describe your priorities)
+
+  1. Security — auth, injection, data exposure
+  2. Performance — this is a high-traffic system
+  3. Data integrity — DB transactions, consistency
+  4. Test coverage — we require tests for all new code
+  5. API contracts — breaking changes are critical
+  6. Accessibility — frontend a11y matters
+  7. Error handling — we need detailed error context
+
+Your answer (numbers or description):
+```
+
+Halt and wait.
+
+Then ask:
+
+```
+What should reviewers IGNORE or deprioritize?
+(things that are intentional, handled elsewhere, or not worth flagging)
+
+Examples:
+  "console.log is allowed in development, we strip in CI"
+  "We intentionally use callbacks in legacy modules, don't flag them"
+  "Test files don't need JSDoc"
+  "We allow 'any' in migration scripts"
+
+Your answer (or press Enter to skip):
+```
+
+Halt and wait.
+
+---
+
+**Group C: Architecture Context** (only ask if architecture docs were NOT found in step-01)
+
+```
+How is the codebase organized? What are the main layers/modules?
+
+Examples:
+  "Vue 3 frontend (src/), Node/Express API (api/), shared types (shared/)"
+  "Monorepo: apps/web, apps/api, packages/ui, packages/utils"
+  "MVC: routes/, controllers/, services/, models/"
+  "Feature-based: src/features/{feature}/{components,hooks,api}/"
+
+Your answer:
+```
+
+Halt and wait.
+
+Then ask:
+
+```
+Are there any known anti-patterns or tech debt areas reviewers should know about?
+(so they don't waste time flagging known issues)
+
+Examples:
+  "auth module is legacy, will be rewritten — don't review deeply"
+  "UserController is a God class — we know, it's being split"
+  "Some old files still use callbacks — that's expected"
+
+Your answer (or press Enter to skip):
+```
+
+Halt and wait.
+
+---
+
+**Group D: PR-specific guidelines**
+
+```
+Any specific rules for what needs review before merging?
+
+Examples:
+  "All PRs touching /api/payments must have security review"
+  "DB migration files require architecture review"
+  "Changes to auth/* always need two approvals"
+  "Frontend PRs need accessibility check"
+
+Your answer (or press Enter to skip):
+```
+
+Halt and wait.
+
+### 3. Confirm Collected Context
+
+Display a summary of all answers received:
+
+```
+✅ Context collected:
+
+Domain: {domain_description}
+Key entities: {entities}
+Business rules: {rules or "none specified"}
+
+Review priorities: {priorities}
+Ignore list: {ignore_list or "none"}
+
+Architecture: {architecture_description}
+Known debt: {debt_notes or "none"}
+PR-specific rules: {pr_rules or "none"}
+
+Is this correct? [Y] Save  [E] Edit  [S] Skip remaining
+```
+
+Halt and wait for confirmation.
+
+If `[E]` → ask which group to re-answer, then re-ask that group.
+If `[S]` → proceed with what's collected so far.
+
+### 4. Load Next Step
+
+Add `step-03-ask-context` to `stepsCompleted`. Load: `{nextStepFile}`

package/src/prr/workflows/0-setup/collect-project-context/steps/step-04-save-context.md

@@ -0,0 +1,161 @@
+---
+name: "step-04-save-context"
+description: "Save complete project context to YAML file for use by all review workflows"
+---
+
+# Step 4: Save Project Context
+
+## Sequence of Instructions
+
+### 1. Assemble Complete Context Document
+
+Combine everything from steps 01-03 into a single structured YAML:
+
+```yaml
+# PR Review — Project Context
+# Generated: {date}
+# Project: {project_name}
+# Repo: {target_repo}
+
+meta:
+  generated_date: "{date}"
+  generated_by: "{user_name}"
+  project_name: "{project_name}"
+  schema_version: "1"
+
+stack:
+  frontend: "{detected_frontend}"          # vue3 / react / angular / none
+  backend: "{detected_backend}"            # express / nestjs / django / none
+  language: "{primary_language}"           # typescript / javascript / python / java
+  orm: "{orm_or_none}"
+  test_runner: "{test_framework}"
+  state_management: "{state_lib_or_none}"
+  build_tool: "{vite_or_webpack_etc}"
+
+coding_standards:
+  enforced_rules:                          # from ESLint/linting configs
+    - "{rule_name}: {description}"
+  soft_warnings:
+    - "{rule_name}: {description}"
+  typescript:
+    strict: {true|false}
+    no_implicit_any: {true|false}
+    strict_null_checks: {true|false}
+
+naming_conventions:
+  documented:
+    - thing: "{what}"
+      convention: "{PascalCase|camelCase|snake_case|kebab-case|UPPER_SNAKE}"
+      example: "{example}"
+  inferred:
+    - thing: "{what}"
+      convention: "{convention}"
+      example: "{example}"
+      note: "inferred from existing files, not documented"
+
+architecture:
+  description: "{architecture_description}"
+  layer_order: "{layer → layer → layer}"
+  prohibited:
+    - "{cross-layer violation that must not happen}"
+  established_patterns:
+    error_handling: "{description}"
+    api_response_format: "{description or null}"
+    auth_pattern: "{description or null}"
+    logging: "{description or null}"
+  known_debt:
+    - "{known issue to deprioritize in reviews}"
+
+testing:
+  framework: "{vitest|jest|pytest|none}"
+  file_pattern: "{*.spec.ts|*.test.ts|test_*.py}"
+  location: "{co-located|__tests__|test/ folder}"
+  coverage_threshold: "{percentage or null}"
+  what_requires_tests: "{all new code|only services|only utils|none documented}"
+
+domain:
+  description: "{business domain description}"
+  key_entities:
+    - "{Entity}"
+  business_rules:
+    - "{rule that code must enforce}"
+  terminology:
+    - term: "{domain term}"
+      meaning: "{what it means in this project}"
+
+review_guidelines:
+  priorities:
+    - "{what to focus on most}"
+  ignore_list:
+    - "{what to NOT flag — intentional or known}"
+  pr_specific_rules:
+    - "{when to require which review type}"
+```
+
+### 2. Write to File
+
+Write the assembled YAML to:
+```
+{review_output}/project-context.yaml
+```
+
+### 3. Write Human-Readable Summary
+
+Also write a compact summary at:
+```
+{review_output}/project-context-summary.md
+```
+
+Content:
+```markdown
+# Project Context: {project_name}
+
+**Stack:** {frontend} + {backend} ({language})
+**Generated:** {date} by {user_name}
+
+## Key Rules for Reviewers
+
+### Must Follow (enforced by linting)
+{enforced_rules as bullet list}
+
+### Architecture Rules
+- Layer order: {layer_order}
+{prohibited as bullet list}
+
+### Naming Conventions
+{naming table}
+
+### Business Rules
+{business_rules as bullet list}
+
+### Review Priorities
+{priorities as bullet list}
+
+### Do NOT Flag
+{ignore_list as bullet list}
+```
+
+### 4. Display Completion
+
+```
+✅ Project Context Saved!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📄 Context file:   {review_output}/project-context.yaml
+📋 Summary:        {review_output}/project-context-summary.md
+
+What was captured:
+  🏗️  Stack: {stack_summary}
+  📏  Linting rules: {n} hard, {n} soft
+  🔤  Naming conventions: {n} documented, {n} inferred
+  🏢  Architecture layers: {layer_order}
+  📖  Business rules: {n}
+  🎯  Review priorities: {n}
+  🚫  Ignore list: {n} items
+
+All review workflows will now load this context automatically.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Next step: Run [SP] Select PR to begin reviewing.
+```
+
+**Workflow complete.** Return to agent menu.

package/src/prr/workflows/0-setup/collect-project-context/workflow.md

@@ -0,0 +1,58 @@
+---
+name: collect-project-context
+description: "Collect project coding standards, conventions, architecture rules, and business context — stored once and used by all review workflows"
+main_config: "{project-root}/_prr/prr/config.yaml"
+nextStep: "./steps/step-01-scan-configs.md"
+output_file: "{review_output}/project-context.yaml"
+---
+
+# Collect Project Context Workflow
+
+**Goal:** Build a reusable knowledge base about THIS project — its coding standards, architecture patterns, business domain, and team conventions. All review workflows load this context so findings are accurate and relevant to the project, not just generic best practices.
+
+## WHY THIS MATTERS
+
+Without project context, AI reviewers will:
+- Flag code that intentionally follows project conventions
+- Miss violations of domain-specific rules
+- Suggest patterns that contradict what the team has established
+- Not understand business logic to assess correctness
+
+With project context, reviewers know:
+- What rules are enforced (ESLint, Prettier, custom linting)
+- What architecture patterns the team follows
+- What the business domain is and key domain terms
+- What to prioritize vs ignore for this specific codebase
+
+## WHEN TO RUN
+
+- **First time** before any review in a new project
+- **Re-run** when project conventions change significantly
+- Output is saved to `{review_output}/project-context.yaml` and reused across all PRs
+
+## WORKFLOW ARCHITECTURE
+
+4-step process:
+1. Scan repo for config files and standards documents
+2. Extract coding rules from linting/formatting configs
+3. Ask user for domain and architecture context
+4. Save complete project context to YAML file
+
+## INITIALIZATION
+
+Load config from `{main_config}`.
+Check if `{review_output}/project-context.yaml` already exists.
+
+If it exists, ask:
+```
+📋 Project context already exists (created: {existing_date}).
+  [U] Update — re-scan and update context
+  [K] Keep — use existing context, skip this workflow
+  [R] Replace — start fresh
+```
+
+Halt and wait for user choice before proceeding.
+
+## EXECUTION
+
+Read fully and follow: `{nextStep}`

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

@@ -0,0 +1,68 @@
+---
+name: "step-01-fetch"
+description: "Detect platform and run git fetch to ensure latest remote state"
+nextStepFile: "./step-02-list-branches.md"
+---
+
+# Step 1: Detect Platform and Fetch Latest
+
+**Progress: Step 1 of 5** — Detecting platform and ensuring up-to-date remote state
+
+## MANDATORY EXECUTION RULES
+
+- 🛑 ALWAYS fetch before listing — stale branch info leads to wrong reviews
+- 📖 Read this entire file before taking any action
+- ✅ Communicate in `{communication_language}`
+
+## Sequence of Instructions
+
+### 1. Detect Platform
+
+If `{platform}` is `auto` or empty, detect from the git remote URL:
+
+```bash
+git -C {target_repo} remote get-url origin
+```
+
+Map remote URL to platform:
+
+| Remote URL pattern | Platform |
+|-------------------|----------|
+| `github.com` | `github` |
+| `gitlab.com` or self-hosted GitLab | `gitlab` |
+| `dev.azure.com` or `visualstudio.com` | `azure` |
+| `bitbucket.org` | `bitbucket` |
+| No remote / local only | `none` |
+
+Set `{detected_platform}` = detected value.
+
+Also extract `{detected_platform_repo}` from the URL if `{platform_repo}` is empty:
+- GitHub/GitLab/Bitbucket: extract `owner/repo` (strip `.git` suffix)
+- Azure DevOps: extract `org/project/repo` from `dev.azure.com/{org}/{project}/_git/{repo}`
+
+Display:
+```
+🔍 Platform detected: {detected_platform}
+   Remote: {platform_repo or detected_platform_repo}
+```
+
+If platform cannot be detected, set `{detected_platform}` = `none` and continue.
+
+### 2. Fetch Latest from Remote
+
+```bash
+git -C {target_repo} fetch origin --prune
+```
+
+**If fetch succeeds:** Show `✓ Fetched latest from remote` and proceed.
+
+**If fetch fails:**
+- Show the error message
+- Ask user: Retry / Continue with local state / Cancel
+- Wait for response before proceeding
+
+### 3. Update Frontmatter and Load Next Step
+
+Add `step-01-fetch` to `stepsCompleted`. Store `detected_platform` and `detected_platform_repo` for use in subsequent steps.
+
+Read fully and follow: `{nextStepFile}`

package/src/prr/workflows/1-discover/select-pr/steps/step-02-list-branches.md

@@ -0,0 +1,95 @@
+---
+name: "step-02-list-prs"
+description: "List open PRs/MRs via platform CLI (primary) and recent branches (secondary)"
+nextStepFile: "./step-03-select.md"
+---
+
+# Step 2: List Open PRs and Branches
+
+**Progress: Step 2 of 5** — Listing available PRs/MRs and branches
+
+## STEP GOAL
+
+Show open PRs/MRs from the configured platform as the **primary** selection list.
+Always show recent branches as secondary. Fall back to branch-only if no platform configured.
+
+Use `{platform}` (or `{detected_platform}` from step 1 if platform = auto).
+
+## Sequence of Instructions
+
+### 1. List Open PRs/MRs (Primary)
+
+Run the appropriate command based on platform:
+
+**GitHub** (`platform = github`, requires `gh` CLI):
+```bash
+gh pr list --repo {platform_repo} --state open \
+  --json number,title,headRefName,baseRefName,author,createdAt,isDraft \
+  --limit 20
+```
+
+**GitLab** (`platform = gitlab`, requires `glab` CLI):
+```bash
+glab mr list --repo {platform_repo} --state opened \
+  --output json
+```
+Fields to use: `iid` (MR number), `title`, `source_branch`, `target_branch`, `author.username`, `created_at`, `draft`.
+
+**Azure DevOps** (`platform = azure`, requires `az` CLI with `azure-devops` extension):
+```bash
+az repos pr list --repository {repo} --project {project} --org {org_url} \
+  --status active --output json
+```
+Where `{platform_repo}` format is `org/project/repo` → extract accordingly.
+Fields: `pullRequestId`, `title`, `sourceRefName`, `targetRefName`, `createdBy.displayName`, `creationDate`.
+
+**Bitbucket** (`platform = bitbucket`, requires `bb` CLI or `curl`):
+```bash
+bb prs list --repo {platform_repo} --state OPEN
+```
+Or via API: `curl https://api.bitbucket.org/2.0/repositories/{platform_repo}/pullrequests?state=OPEN`
+Fields: `id`, `title`, `source.branch.name`, `destination.branch.name`, `author.display_name`.
+
+**None / local** (`platform = none` or no platform configured): skip to step 2.
+
+If the command **succeeds and returns PRs/MRs**, display them as the main list:
+
+```
+🔗 Open PRs on {platform_repo}:  ({platform})
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  #45  [DRAFT] "Add OAuth2 login"           feature/oauth    → main     @alice  3h ago
+  #44  "Fix memory leak in dashboard"       fix/memory-leak  → main     @bob    1d ago
+  #43  "Refactor API layer"                 refactor/api     → develop  @carol  2d ago
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Set `pr_list_available = true`. Store the PR/MR list for step 3.
+
+If the command **fails or returns empty**, set `pr_list_available = false`.
+
+### 2. List Recent Branches (Always shown as secondary / fallback)
+
+```bash
+git -C {target_repo} branch -r --sort=-committerdate \
+  --format="%(refname:short) | %(objectname:short) | %(committerdate:relative) | %(contents:subject)" \
+  | head -15
+```
+
+Display as secondary reference (or primary if `pr_list_available = false`):
+```
+🌿 Recent branches (newest first):
+  1. origin/feature/oauth       (abc1234) — 3 hours ago — "Add OAuth2 login"
+  2. origin/fix/memory-leak     (def5678) — 1 day ago  — "Fix memory leak"
+  ...
+```
+
+If `pr_list_available = false`, add note:
+```
+⚠️  Platform PR list unavailable — select by branch name instead.
+```
+
+### 3. Update Frontmatter and Load Next Step
+
+Add `step-02-list-prs` to `stepsCompleted`.
+
+Read fully and follow: `{nextStepFile}`