diff --git a/plugins/clarity-assist/commands/clarify.md b/plugins/clarity-assist/commands/clarify.md index 3069b36..4a6e084 100644 --- a/plugins/clarity-assist/commands/clarify.md +++ b/plugins/clarity-assist/commands/clarify.md @@ -5,9 +5,9 @@ When executing this command, display the plugin header: ``` -┌──────────────────────────────────────────────────────────────────┐ -│ 💬 CLARITY-ASSIST · Prompt Optimization │ -└──────────────────────────────────────────────────────────────────┘ ++----------------------------------------------------------------------+ +| CLARITY-ASSIST - Prompt Optimization | ++----------------------------------------------------------------------+ ``` Then proceed with the workflow. @@ -23,127 +23,22 @@ Transform vague, incomplete, or ambiguous requests into clear, actionable specif - Tasks requiring significant context gathering - When user seems uncertain about what they want -## 4-D Methodology +## Skills to Load -### Phase 1: Deconstruct +Load these skills before proceeding: -Break down the user's request into components: +- `skills/4d-methodology.md` - Core 4-phase process (Deconstruct, Diagnose, Develop, Deliver) +- `skills/nd-accommodations.md` - ND-friendly question patterns +- `skills/clarification-techniques.md` - Anti-patterns and question templates +- `skills/escalation-patterns.md` - When to adjust approach -1. **Extract explicit requirements** - What was directly stated -2. **Identify implicit assumptions** - What seems assumed but not stated -3. **Note ambiguities** - Points that could go multiple ways -4. **List dependencies** - External factors that might affect implementation +## Workflow -### Phase 2: Diagnose - -Analyze gaps and potential issues: - -1. **Missing information** - What do we need to know? -2. **Conflicting requirements** - Do any stated goals contradict? -3. **Scope boundaries** - What's in/out of scope? -4. **Technical constraints** - Platform, language, architecture limits - -### Phase 3: Develop - -Gather clarifications through structured questioning: - -**ND-Friendly Question Rules:** -- Present 2-4 concrete options (never open-ended alone) -- Include "Other" for custom responses -- Ask 1-2 questions at a time maximum -- Provide brief context for why you're asking -- Check for conflicts with previous answers - -**Example Format:** -``` -To help me understand the scope better: - -**How should errors be handled?** -1. Silent logging (user sees nothing) -2. Toast notifications (brief, dismissible) -3. Modal dialogs (requires user action) -4. Other - -[Context: This affects both UX and how much error-handling code we need] -``` - -### Phase 4: Deliver - -Produce the refined specification: - -```markdown -## Clarified Request - -### Summary -[1-2 sentence description of what will be built] - -### Scope -**In Scope:** -- [Item 1] -- [Item 2] - -**Out of Scope:** -- [Item 1] - -### Requirements - -| # | Requirement | Priority | Notes | -|---|-------------|----------|-------| -| 1 | ... | Must | ... | -| 2 | ... | Should | ... | - -### Assumptions -- [Assumption made based on conversation] - -### Open Questions -- [Any remaining ambiguities, if any] -``` - -## Conflict Detection - -Before each question, review previous answers for conflicts: - -``` -[Internal check] -Previous: User said "keep it simple" -Current question about: Adding configuration options -Potential conflict: More options = more complexity -→ Acknowledge: "Earlier you mentioned keeping it simple. With that in mind..." -``` - -## Escalation Protocol - -If the request is particularly messy or the user seems overwhelmed: - -1. Acknowledge the complexity -2. Offer to start with just ONE aspect -3. Build incrementally - -``` -"This touches a lot of areas. Rather than tackle everything at once, -let's start with [most critical piece]. Once that's clear, we can -add the other parts. Sound good?" -``` - -## Example Interaction - -**User:** Make the app faster - -**Clarify Response:** - -``` -Let me help clarify what kind of performance improvements you're looking for. - -**What type of slowness are you experiencing?** -1. Initial page load takes too long -2. Interactions feel sluggish (clicking, typing) -3. API calls are slow -4. All of the above -5. Other - -[I'm asking because each has very different solutions] -``` +1. **Deconstruct** - Break down request into components +2. **Diagnose** - Identify gaps and conflicts +3. **Develop** - Gather clarifications via structured questions +4. **Deliver** - Present refined specification ## Output Format -After gathering all necessary information, use the Deliver phase format to present the clarified specification for user confirmation. +Use the Deliver phase template from `skills/4d-methodology.md` to present the clarified specification for user confirmation. diff --git a/plugins/clarity-assist/commands/quick-clarify.md b/plugins/clarity-assist/commands/quick-clarify.md index 9f331b8..ca0f7e5 100644 --- a/plugins/clarity-assist/commands/quick-clarify.md +++ b/plugins/clarity-assist/commands/quick-clarify.md @@ -5,9 +5,9 @@ When executing this command, display the plugin header: ``` -┌──────────────────────────────────────────────────────────────────┐ -│ 💬 CLARITY-ASSIST · Quick Clarify │ -└──────────────────────────────────────────────────────────────────┘ ++----------------------------------------------------------------------+ +| CLARITY-ASSIST - Quick Clarify | ++----------------------------------------------------------------------+ ``` Then proceed with the workflow. @@ -23,74 +23,27 @@ Single-pass clarification for requests that are mostly clear but need minor disa - Follow-up to an already-clarified request - Simple feature additions or bug fixes -## Process +## Skills to Load -### Step 1: Echo Understanding +- `skills/nd-accommodations.md` - ND-friendly question patterns +- `skills/clarification-techniques.md` - Echo and micro-summary techniques +- `skills/escalation-patterns.md` - When to escalate to full /clarify -Restate what you understood in a single sentence: +## Workflow -``` -"I understand you want [X] that does [Y]." -``` - -### Step 2: Quick Disambiguation - -If needed, ask ONE multiple-choice question: - -``` -**Just to confirm:** Should this [A] or [B]? -1. [Option A with brief description] -2. [Option B with brief description] -3. Both -4. Neither / Other approach -``` - -### Step 3: Proceed or Confirm - -If confident (>90%), proceed with a brief confirmation: - -``` -"Got it. I'll implement [X with chosen option]. Starting now." -``` - -If less confident, offer a micro-summary: - -``` -"Quick summary before I start: -- [Key point 1] -- [Key point 2] -- [Assumption made] - -Proceed? (Or clarify anything)" -``` - -## Example Interaction - -**User:** Add a delete button to the user list - -**Quick-Clarify Response:** - -``` -I'll add a delete button to each row in the user list. - -**Should deletion require confirmation?** -1. Yes - show confirmation dialog (Recommended) -2. No - delete immediately -3. Soft delete - mark as deleted but keep data - -[Asking because accidental deletions can be problematic] -``` - -## Escalation to Full /clarify - -If quick-clarify reveals complexity: - -``` -"This is more involved than it first appeared - there are -several decisions to make. Want me to switch to a more -thorough clarification process? (Just say 'yes' or 'clarify')" -``` +1. **Echo Understanding** - Restate in a single sentence +2. **Quick Disambiguation** - Ask ONE multiple-choice question if needed +3. **Proceed or Confirm** - Start work or offer micro-summary ## Output Format -For quick-clarify, no formal specification document is needed. Just proceed with the task after brief confirmation, documenting assumptions inline with the work. +No formal specification document needed. Proceed after brief confirmation, documenting assumptions inline with the work. + +## Escalation + +If complexity emerges, offer to switch to full `/clarify`: + +``` +"This is more involved than it first appeared. Want me to switch +to a more thorough clarification process?" +``` diff --git a/plugins/clarity-assist/skills/4d-methodology.md b/plugins/clarity-assist/skills/4d-methodology.md new file mode 100644 index 0000000..0b34bcc --- /dev/null +++ b/plugins/clarity-assist/skills/4d-methodology.md @@ -0,0 +1,76 @@ +# 4-D Methodology for Prompt Clarification + +The 4-D methodology transforms vague requests into actionable specifications. + +## Phase 1: Deconstruct + +Break down the user's request into components: + +1. **Extract explicit requirements** - What was directly stated +2. **Identify implicit assumptions** - What seems assumed but not stated +3. **Note ambiguities** - Points that could go multiple ways +4. **List dependencies** - External factors that might affect implementation + +## Phase 2: Diagnose + +Analyze gaps and potential issues: + +1. **Missing information** - What do we need to know? +2. **Conflicting requirements** - Do any stated goals contradict? +3. **Scope boundaries** - What is in/out of scope? +4. **Technical constraints** - Platform, language, architecture limits + +## Phase 3: Develop + +Gather clarifications through structured questioning: + +- Present 2-4 concrete options (never open-ended alone) +- Include "Other" for custom responses +- Ask 1-2 questions at a time maximum +- Provide brief context for why you are asking +- Check for conflicts with previous answers + +**Example Format:** +``` +To help me understand the scope better: + +**How should errors be handled?** +1. Silent logging (user sees nothing) +2. Toast notifications (brief, dismissible) +3. Modal dialogs (requires user action) +4. Other + +[Context: This affects both UX and how much error-handling code we need] +``` + +## Phase 4: Deliver + +Produce the refined specification: + +```markdown +## Clarified Request + +### Summary +[1-2 sentence description of what will be built] + +### Scope +**In Scope:** +- [Item 1] +- [Item 2] + +**Out of Scope:** +- [Item 1] + +### Requirements + +| # | Requirement | Priority | Notes | +|---|-------------|----------|-------| +| 1 | ... | Must | ... | +| 2 | ... | Should | ... | + +### Assumptions +- [Assumption made based on conversation] + +### Open Questions +- [Any remaining ambiguities, if any] +``` diff --git a/plugins/clarity-assist/skills/clarification-techniques.md b/plugins/clarity-assist/skills/clarification-techniques.md new file mode 100644 index 0000000..011a5e3 --- /dev/null +++ b/plugins/clarity-assist/skills/clarification-techniques.md @@ -0,0 +1,86 @@ +# Clarification Techniques + +Structured approaches for disambiguating user requests. + +## Anti-Patterns to Detect + +### Vague Requests +**Triggers:** "improve", "fix", "update", "change", "better", "faster", "cleaner" + +**Response:** Ask for specific metrics or outcomes + +### Scope Creep Signals +**Triggers:** "while you're at it", "also", "might as well", "and another thing" + +**Response:** Acknowledge, then isolate: "I'll note that for after the main task" + +### Assumption Gaps +**Triggers:** References to "the" thing (which thing?), "it" (what?), "there" (where?) + +**Response:** Echo back specific understanding + +### Conflicting Requirements +**Triggers:** "Simple but comprehensive", "Fast but thorough", "Minimal but complete" + +**Response:** Prioritize: "Which matters more: simplicity or completeness?" + +## Question Templates + +### For Unclear Purpose +``` +**What problem does this solve?** +1. [Specific problem A] +2. [Specific problem B] +3. Combination +4. Different problem: ____ +``` + +### For Missing Scope +``` +**What should this include?** +- [ ] Feature A +- [ ] Feature B +- [ ] Feature C +- [ ] Other: ____ +``` + +### For Ambiguous Behavior +``` +**When [trigger event], what should happen?** +1. [Behavior option A] +2. [Behavior option B] +3. Nothing (ignore) +4. Depends on: ____ +``` + +### For Technical Decisions +``` +**Implementation approach:** +1. [Approach A] - pros: X, cons: Y +2. [Approach B] - pros: X, cons: Y +3. Let me decide based on codebase +4. Need more info about: ____ +``` + +## Echo Understanding Technique + +Before diving into questions, restate understanding: + +``` +"I understand you want [X] that does [Y]." +``` + +This validates comprehension and gives user a chance to correct early. + +## Micro-Summary Technique + +For quick confirmations before proceeding: + +``` +"Quick summary before I start: +- [Key point 1] +- [Key point 2] +- [Assumption made] + +Proceed? (Or clarify anything)" +``` diff --git a/plugins/clarity-assist/skills/escalation-patterns.md b/plugins/clarity-assist/skills/escalation-patterns.md new file mode 100644 index 0000000..eba07ab --- /dev/null +++ b/plugins/clarity-assist/skills/escalation-patterns.md @@ -0,0 +1,57 @@ +# Escalation Patterns + +Guidelines for when to escalate between clarification modes. + +## Quick-Clarify to Full Clarify + +Escalate when quick-clarify reveals unexpected complexity: + +``` +"This is more involved than it first appeared - there are +several decisions to make. Want me to switch to a more +thorough clarification process? (Just say 'yes' or 'clarify')" +``` + +### Triggers for Escalation + +- Multiple ambiguities discovered during quick pass +- User's answer reveals hidden dependencies +- Scope expands beyond original understanding +- Technical constraints emerge that need discussion +- Conflicting requirements surface + +## Full Clarify to Incremental + +When user is overwhelmed by full 4-D process: + +``` +"This touches a lot of areas. Rather than tackle everything at once, +let's start with [most critical piece]. Once that's clear, we can +add the other parts. Sound good?" +``` + +### Signs of Overwhelm + +- Long pauses or hesitation +- "I don't know" responses +- Requesting breaks +- Contradicting earlier answers +- Expressing frustration + +## Choosing Initial Mode + +### Use /quick-clarify When + +- Request is fairly clear, just one or two ambiguities +- User is in a hurry +- Follow-up to an already-clarified request +- Simple feature additions or bug fixes +- Confidence is high (>90%) + +### Use /clarify When + +- Complex multi-step requests +- Requirements with multiple possible interpretations +- Tasks requiring significant context gathering +- User seems uncertain about what they want +- First time working on this feature/area diff --git a/plugins/clarity-assist/skills/nd-accommodations.md b/plugins/clarity-assist/skills/nd-accommodations.md new file mode 100644 index 0000000..594636e --- /dev/null +++ b/plugins/clarity-assist/skills/nd-accommodations.md @@ -0,0 +1,74 @@ +# Neurodivergent-Friendly Accommodations + +Guidelines for making clarification interactions accessible and comfortable for neurodivergent users. + +## Core Principles + +### Reduce Cognitive Load +- Maximum 4 options per question +- Always include "Other" escape hatch +- Provide examples, not just descriptions +- Use numbered lists for easy reference + +### Support Working Memory +- Summarize frequently +- Reference earlier decisions explicitly +- Do not assume user remembers context from many turns ago +- Echo back understanding before proceeding + +### Allow Processing Time +- Do not rapid-fire questions +- Validate answers before moving on +- Offer to revisit or change earlier answers +- One question block at a time + +### Manage Overwhelm +- Offer to break into smaller sessions +- Prioritize must-haves vs nice-to-haves +- Provide "good enough for now" options +- Acknowledge complexity openly + +## Question Formatting Rules + +**Always do:** +``` +**How should errors be handled?** +1. Silent logging (user sees nothing) +2. Toast notifications (brief, dismissible) +3. Modal dialogs (requires user action) +4. Other + +[Context: This affects both UX and error-handling complexity] +``` + +**Never do:** +``` +How do you want to handle errors? There are many approaches... +``` + +## Conflict Acknowledgment + +Before asking about something that might conflict with a previous answer: + +``` +[Internal check] +Previous: User said "keep it simple" +Current question about: Adding configuration options +Potential conflict: More options = more complexity +``` + +Then acknowledge: "Earlier you mentioned keeping it simple. With that in mind..." + +## Escalation for Overwhelm + +If the request is particularly complex or user seems overwhelmed: + +1. Acknowledge the complexity openly +2. Offer to start with just ONE aspect +3. Build incrementally + +``` +"This touches a lot of areas. Rather than tackle everything at once, +let's start with [most critical piece]. Once that's clear, we can +add the other parts. Sound good?" +``` diff --git a/plugins/pr-review/commands/initial-setup.md b/plugins/pr-review/commands/initial-setup.md index 32dc619..375b1ef 100644 --- a/plugins/pr-review/commands/initial-setup.md +++ b/plugins/pr-review/commands/initial-setup.md @@ -1,285 +1,45 @@ --- -description: Interactive setup wizard for pr-review plugin - configures Gitea MCP and project settings +description: Interactive setup wizard for pr-review plugin --- # PR Review Setup Wizard ## Visual Output -When executing this command, display the plugin header: +Display header: `PR-REVIEW - Setup Wizard` -``` -┌──────────────────────────────────────────────────────────────────┐ -│ 🔍 PR-REVIEW · Setup Wizard │ -└──────────────────────────────────────────────────────────────────┘ -``` +## Skills to Load -Then proceed with the setup. - -This command sets up the pr-review plugin. It shares the Gitea MCP server with projman, so if you've already run `/initial-setup` for projman, most of the work is done. +- skills/setup-workflow.md +- skills/mcp-tools-reference.md +- skills/output-formats.md ## Important Context -- **This command uses Bash, Read, Write, and AskUserQuestion tools** - NOT MCP tools -- **MCP tools won't work until after setup + session restart** -- **Shares Gitea MCP server with projman plugin** +- Uses Bash, Read, Write, AskUserQuestion - NOT MCP tools +- MCP tools won't work until after setup + session restart +- Shares Gitea MCP server with projman plugin ---- +## Workflow -## Phase 1: Check Existing Setup +### Phase 1: Check Existing Setup -### Step 1.1: Check if Gitea MCP is Already Configured +Check `~/.config/claude/gitea.env`. If valid, skip to Phase 3. -First, check if the system configuration already exists (from projman or previous setup): +### Phase 2: System Setup (if needed) -```bash -cat ~/.config/claude/gitea.env 2>/dev/null || echo "FILE_NOT_FOUND" -``` +Execute `skills/setup-workflow.md`: verify Python, create gitea.env, prompt for token -**If file exists with valid values (no placeholders):** -- Skip to Phase 3 (Project Configuration) -- Inform user: "Gitea configuration found. Skipping system setup." +### Phase 3: Project Configuration -**If file doesn't exist or has placeholders:** -- Continue to Phase 2 +Execute `skills/setup-workflow.md`: auto-detect org/repo, validate via API, create .env -### Step 1.2: Check if projman is Installed +### Phase 4: Validation -Check if projman plugin exists (they share MCP server): - -```bash -find ~/.claude ~/.config/claude -name "projman" -type d 2>/dev/null | head -1 -``` - -**If projman exists:** -- Suggest: "The projman plugin is installed and shares the same Gitea MCP server. Consider running `/initial-setup` from projman for the full setup wizard." - -Use AskUserQuestion: -- Question: "How would you like to proceed with setup?" -- Header: "Setup" -- Options: - - "Continue with pr-review setup (Recommended if not using projman)" - - "I'll use projman's /initial-setup instead" - -**If user chooses projman setup:** End here with instructions to run projman's setup. - ---- - -## Phase 2: System Setup (if needed) - -This is a condensed version focusing on what pr-review needs. - -### Step 2.1: Python and MCP Server - -Check Python version: -```bash -python3 --version -``` - -If below 3.10, stop and inform user. - -Locate and set up the MCP server: -```bash -find ~/.claude ~/.config/claude -name "mcp_server" -path "*gitea*" 2>/dev/null | head -5 -``` - -If venv doesn't exist, create it: -```bash -cd /path/to/mcp-servers/gitea && python3 -m venv .venv && source .venv/bin/activate && pip install --upgrade pip && pip install -r requirements.txt && deactivate -``` - -### Step 2.2: Gitea Configuration - -Create config directory: -```bash -mkdir -p ~/.config/claude -``` - -Use AskUserQuestion: -- Question: "What is your Gitea server URL?" -- Header: "Gitea URL" -- Options: - - "https://gitea.hotserv.cloud" - - "Other (I'll provide the URL)" - -Create configuration file (credentials only, org is per-project): -```bash -cat > ~/.config/claude/gitea.env << 'EOF' -# Gitea API Configuration -# Generated by pr-review /initial-setup -# Note: GITEA_ORG is configured per-project in .env - -GITEA_API_URL= -GITEA_API_TOKEN=PASTE_YOUR_TOKEN_HERE -EOF -chmod 600 ~/.config/claude/gitea.env -``` - -### Step 2.3: Token Instructions - -Display these instructions: - ---- - -**Action Required: Add Your Gitea API Token** - -I've created `~/.config/claude/gitea.env` but you need to add your API token manually. - -**Steps:** -1. Open: `nano ~/.config/claude/gitea.env` -2. Generate token in Gitea: Settings → Applications → Generate New Token - - Permissions needed: `repo`, `read:org`, `read:user` -3. Replace `PASTE_YOUR_TOKEN_HERE` with your token -4. Save the file - ---- - -Use AskUserQuestion: -- Question: "Have you added your Gitea token?" -- Header: "Token" -- Options: - - "Yes, I've added the token" - - "Skip for now" - ---- - -## Phase 3: Project Configuration - -### Step 3.1: Check Current Directory - -```bash -pwd && git rev-parse --show-toplevel 2>/dev/null || echo "NOT_A_GIT_REPO" -``` - -### Step 3.2: Check Existing Project Config - -```bash -cat .env 2>/dev/null | grep GITEA_REPO || echo "NOT_FOUND" -``` - -If `GITEA_REPO` is already set, skip to Phase 4. - -### Step 3.3: Detect Organization and Repository - -Extract organization: -```bash -git remote get-url origin 2>/dev/null | sed 's/.*[:/]\([^/]*\)\/[^/]*$/\1/' -``` - -Extract repository: -```bash -git remote get-url origin 2>/dev/null | sed 's/.*[:/]\([^/]*\)\.git$/\1/' | sed 's/.*\/\([^/]*\)$/\1/' -``` - -### Step 3.4: Validate Repository via Gitea API - -```bash -source ~/.config/claude/gitea.env -curl -s -o /dev/null -w "%{http_code}" -H "Authorization: token $GITEA_API_TOKEN" "$GITEA_API_URL/repos//" -``` - -| HTTP Code | Action | -|-----------|--------| -| **200** | Auto-fill - "Verified: / exists" - skip to Step 3.7 | -| **404** | Not found - proceed to Step 3.5 | -| **401/403** | Permission issue - warn, proceed to Step 3.5 | - -### Step 3.5: Confirm Organization (only if validation failed) - -Use AskUserQuestion: -- Question: "Repository not found. Is '' the correct organization?" -- Header: "Organization" -- Options: - - "Yes, that's correct" - - "No, let me specify" - -### Step 3.6: Confirm Repository (only if validation failed) - -Use AskUserQuestion: -- Question: "Is '' the correct repository?" -- Header: "Repository" -- Options: - - "Yes, that's correct" - - "No, let me specify" - -**After corrections, re-validate via API (Step 3.4).** - -### Step 3.7: Create/Update Project Config - -If `.env` exists, append: -```bash -echo "GITEA_ORG=" >> .env -echo "GITEA_REPO=" >> .env -``` - -If `.env` doesn't exist: -```bash -cat > .env << 'EOF' -# Project Configuration -GITEA_ORG= -GITEA_REPO= -EOF -``` - -### Step 3.5: PR Review Settings (Optional) - -Use AskUserQuestion: -- Question: "Do you want to configure PR review settings?" -- Header: "Settings" -- Options: - - "Use defaults (Recommended)" - - "Let me customize" - -If customize, ask about: -- `PR_REVIEW_CONFIDENCE_THRESHOLD` (default: 0.5) -- `PR_REVIEW_AUTO_SUBMIT` (default: false) - ---- - -## Phase 4: Validation and Next Steps - -### Step 4.1: Test Configuration (if token was added) - -```bash -source ~/.config/claude/gitea.env && curl -s -o /dev/null -w "%{http_code}" -H "Authorization: token $GITEA_API_TOKEN" "$GITEA_API_URL/user" -``` - -Report result: -- 200: Success -- 401: Invalid token -- Other: Connection issue - -### Step 4.2: Summary - -``` -╔════════════════════════════════════════════════════════════╗ -║ PR-REVIEW SETUP COMPLETE ║ -╠════════════════════════════════════════════════════════════╣ -║ MCP Server (Gitea): ✓ Ready ║ -║ System Config: ✓ ~/.config/claude/gitea.env ║ -║ Project Config: ✓ ./.env ║ -╚════════════════════════════════════════════════════════════╝ -``` - -### Step 4.3: Session Restart Notice - ---- - -**⚠️ Session Restart Required** - -Restart your Claude Code session for MCP tools to become available. - -**After restart, you can:** -- Run `/pr-review ` to review a pull request -- Run `/pr-summary ` for a quick summary -- Run `/pr-findings ` to list actionable findings - ---- +Test API connection, display completion summary, remind to restart session ## Available Commands After Setup -| Command | Description | -|---------|-------------| -| `/pr-review ` | Full multi-agent PR review with confidence scoring | -| `/pr-summary ` | Quick PR summary | -| `/pr-findings ` | List findings with severity and line numbers | +- `/pr-review ` - Full multi-agent review +- `/pr-summary ` - Quick summary +- `/pr-findings ` - List findings diff --git a/plugins/pr-review/commands/pr-diff.md b/plugins/pr-review/commands/pr-diff.md index 52ab643..ea28529 100644 --- a/plugins/pr-review/commands/pr-diff.md +++ b/plugins/pr-review/commands/pr-diff.md @@ -2,165 +2,47 @@ ## Visual Output -When executing this command, display the plugin header: +Display header: `PR-REVIEW - Diff Viewer` -``` -┌──────────────────────────────────────────────────────────────────┐ -│ 🔍 PR-REVIEW · Diff Viewer │ -└──────────────────────────────────────────────────────────────────┘ -``` +## Skills to Load -Then proceed with the diff display. - -## Purpose - -Display the PR diff with inline annotations from review comments, making it easy to see what feedback has been given alongside the code changes. +- skills/mcp-tools-reference.md +- skills/pr-analysis.md +- skills/output-formats.md ## Usage ``` -/pr-diff [--repo owner/repo] [--context ] +/pr-diff [--repo owner/repo] [--context ] [--no-comments] [--file ] ``` -### Options +## Workflow -``` ---repo Override repository (default: from .env) ---context Lines of context around changes (default: 3) ---no-comments Show diff without comment annotations ---file Filter to specific files (glob pattern) -``` +### Step 1: Fetch Data -## Behavior - -### Step 1: Fetch PR Data - -Using Gitea MCP tools: -1. `get_pr_diff` - Unified diff of all changes -2. `get_pr_comments` - All review comments on the PR +Load MCP tools, then: `get_pr_diff`, `get_pr_comments` ### Step 2: Parse and Annotate -Parse the diff and overlay comments at their respective file/line positions: +Execute `skills/pr-analysis.md` Annotated Diff Display: +- Overlay comments at file/line positions +- Show commenter, timestamp, replies +- Mark resolved vs open -``` -═══════════════════════════════════════════════════ -PR #123 Diff - Add user authentication -═══════════════════════════════════════════════════ +### Step 3: Display -Branch: feat/user-auth → development -Files: 12 changed (+234 / -45) - -─────────────────────────────────────────────────── -src/api/users.ts (+85 / -12) -─────────────────────────────────────────────────── - -@@ -42,6 +42,15 @@ export async function getUser(id: string) { - 42 │ const db = getDatabase(); - 43 │ - 44 │- const user = db.query("SELECT * FROM users WHERE id = " + id); - │ ┌───────────────────────────────────────────────────────────── - │ │ COMMENT by @reviewer (2h ago): - │ │ This is a SQL injection vulnerability. Use parameterized - │ │ queries instead: `db.query("SELECT * FROM users WHERE id = ?", [id])` - │ └───────────────────────────────────────────────────────────── - 45 │+ const query = "SELECT * FROM users WHERE id = ?"; - 46 │+ const user = db.query(query, [id]); - 47 │ - 48 │ if (!user) { - 49 │ throw new NotFoundError("User not found"); - 50 │ } - -@@ -78,3 +87,12 @@ export async function updateUser(id: string, data: UserInput) { - 87 │+ // Validate input before update - 88 │+ validateUserInput(data); - 89 │+ - 90 │+ const result = db.query( - 91 │+ "UPDATE users SET name = ?, email = ? WHERE id = ?", - 92 │+ [data.name, data.email, id] - 93 │+ ); - │ ┌───────────────────────────────────────────────────────────── - │ │ COMMENT by @maintainer (1h ago): - │ │ Good use of parameterized query here! - │ │ - │ │ REPLY by @author (30m ago): - │ │ Thanks! Applied the same pattern throughout. - │ └───────────────────────────────────────────────────────────── - -─────────────────────────────────────────────────── -src/components/LoginForm.tsx (+65 / -0) [NEW FILE] -─────────────────────────────────────────────────── - -@@ -0,0 +1,65 @@ - 1 │+import React, { useState } from 'react'; - 2 │+import { useAuth } from '../context/AuthContext'; - 3 │+ - 4 │+export function LoginForm() { - 5 │+ const [email, setEmail] = useState(''); - 6 │+ const [password, setPassword] = useState(''); - 7 │+ const { login } = useAuth(); - -... (remaining diff content) - -═══════════════════════════════════════════════════ -Comment Summary: 5 comments, 2 resolved -═══════════════════════════════════════════════════ -``` - -### Step 3: Filter by Confidence (Optional) - -If `PR_REVIEW_CONFIDENCE_THRESHOLD` is set, also annotate with high-confidence findings from previous reviews: - -``` - 44 │- const user = db.query("SELECT * FROM users WHERE id = " + id); - │ ┌─── REVIEW FINDING (0.95 HIGH) ───────────────────────────── - │ │ [SEC-001] SQL Injection Vulnerability - │ │ Use parameterized queries to prevent injection attacks. - │ └───────────────────────────────────────────────────────────── - │ ┌─── COMMENT by @reviewer ──────────────────────────────────── - │ │ This is a SQL injection vulnerability... - │ └───────────────────────────────────────────────────────────── -``` - -## Output Formats - -### Default (Annotated Diff) - -Full diff with inline comments as shown above. - -### Plain (--no-comments) - -``` -/pr-diff 123 --no-comments - -# Standard unified diff output without annotations -``` - -### File Filter (--file) - -``` -/pr-diff 123 --file "src/api/*" - -# Shows diff only for files matching pattern -``` +Use annotated diff format from `skills/output-formats.md` ## Use Cases -- **Review preparation**: See the full context of changes with existing feedback -- **Followup work**: Understand what was commented on and where -- **Discussion context**: View threaded conversations alongside the code -- **Progress tracking**: See which comments have been resolved - -## Configuration - -| Variable | Default | Description | -|----------|---------|-------------| -| `PR_REVIEW_CONFIDENCE_THRESHOLD` | `0.7` | Minimum confidence for showing review findings | +- Review preparation with existing feedback +- Followup work - see what was commented +- Progress tracking on resolved comments ## Related Commands | Command | Purpose | |---------|---------| -| `/pr-summary` | Quick overview without diff | -| `/pr-review` | Full multi-agent review | -| `/pr-findings` | Filter review findings by category | +| `/pr-summary` | Quick overview | +| `/pr-review` | Full review | +| `/pr-findings` | Filter findings | diff --git a/plugins/pr-review/commands/pr-findings.md b/plugins/pr-review/commands/pr-findings.md index 00f9b9f..50ae9f1 100644 --- a/plugins/pr-review/commands/pr-findings.md +++ b/plugins/pr-review/commands/pr-findings.md @@ -2,148 +2,44 @@ ## Visual Output -When executing this command, display the plugin header: +Display header: `PR-REVIEW - Findings` -``` -┌──────────────────────────────────────────────────────────────────┐ -│ 🔍 PR-REVIEW · Findings │ -└──────────────────────────────────────────────────────────────────┘ -``` +## Skills to Load -Then proceed with the findings display. - -## Purpose - -List and filter findings from a previous PR review by category, severity, or confidence level. +- skills/mcp-tools-reference.md +- skills/review-patterns/confidence-scoring.md +- skills/output-formats.md ## Usage ``` -/pr-findings [filters] +/pr-findings [--category ] [--severity ] [--confidence ] [--file ] [--compact] [--json] ``` -### Filters - -``` ---category Filter by category (security, performance, maintainability, tests) ---severity Filter by severity (critical, major, minor, suggestion) ---confidence Minimum confidence score (0.0-1.0) ---file Filter by file path pattern -``` - -## Examples - -``` -# Show only security findings -/pr-findings 123 --category security - -# Show critical and major issues only -/pr-findings 123 --severity critical,major - -# Show high-confidence findings only -/pr-findings 123 --confidence 0.8 - -# Show findings in specific files -/pr-findings 123 --file src/api/* -``` - -## Behavior +## Workflow ### Without Previous Review -If no review exists for this PR: - -``` -No review found for PR #123. - -Would you like to: -1. Run full /pr-review now -2. Run quick /pr-summary -3. Cancel -``` +Prompt: "No review found. Run /pr-review, /pr-summary, or cancel?" ### With Previous Review -Display filtered findings: - -``` -═══════════════════════════════════════════════════ -PR #123 Findings (filtered: security) -═══════════════════════════════════════════════════ - -Showing 3 of 8 total findings - -─────────────────────────────────────────────────── - -[SEC-001] SQL Injection Vulnerability -Confidence: 0.95 (HIGH) | Severity: Critical -File: src/api/users.ts:45 - -The query uses string interpolation without parameterization. - -Fix: Use parameterized queries. - -─────────────────────────────────────────────────── - -[SEC-002] Missing Input Validation -Confidence: 0.88 (MEDIUM) | Severity: Major -File: src/api/auth.ts:23 - -User input is passed directly to database without validation. - -Fix: Add input validation middleware. - -─────────────────────────────────────────────────── - -[SEC-003] Sensitive Data in Logs -Confidence: 0.72 (MEDIUM) | Severity: Minor -File: src/utils/logger.ts:15 - -Password field may be logged in debug mode. - -Fix: Sanitize sensitive fields before logging. - -═══════════════════════════════════════════════════ -``` +1. Load findings from previous review +2. Apply filters (category, severity, confidence, file) +3. Display using format from `skills/output-formats.md` ## Output Formats -### Default (Detailed) +Reference `skills/output-formats.md`: +- **Detailed** (default) - Full finding +- **Compact** (`--compact`) - Single line +- **JSON** (`--json`) - Structured data -Full finding details with descriptions and fixes. - -### Compact (--compact) +## Examples +```bash +/pr-findings 123 --category security +/pr-findings 123 --severity critical,major +/pr-findings 123 --confidence 0.8 +/pr-findings 123 --file src/api/* ``` -SEC-001 | Critical | 0.95 | src/api/users.ts:45 | SQL Injection -SEC-002 | Major | 0.88 | src/api/auth.ts:23 | Missing Validation -SEC-003 | Minor | 0.72 | src/utils/logger.ts | Sensitive Logs -``` - -### JSON (--json) - -```json -{ - "pr": 123, - "findings": [ - { - "id": "SEC-001", - "category": "security", - "severity": "critical", - "confidence": 0.95, - "file": "src/api/users.ts", - "line": 45, - "title": "SQL Injection Vulnerability", - "description": "...", - "fix": "..." - } - ] -} -``` - -## Use Cases - -- Focus on specific issue types -- Track resolution of findings -- Export findings for tracking -- Quick reference during fixes diff --git a/plugins/pr-review/commands/pr-review.md b/plugins/pr-review/commands/pr-review.md index e6ae203..cfec27c 100644 --- a/plugins/pr-review/commands/pr-review.md +++ b/plugins/pr-review/commands/pr-review.md @@ -2,19 +2,14 @@ ## Visual Output -When executing this command, display the plugin header: +Display header: `PR-REVIEW - Full Review` -``` -┌──────────────────────────────────────────────────────────────────┐ -│ 🔍 PR-REVIEW · Full Review │ -└──────────────────────────────────────────────────────────────────┘ -``` +## Skills to Load -Then proceed with the review. - -## Purpose - -Conduct a comprehensive pull request review using specialized agents for security, performance, maintainability, and test coverage. +- skills/mcp-tools-reference.md +- skills/review-workflow.md +- skills/review-patterns/confidence-scoring.md +- skills/output-formats.md ## Usage @@ -22,132 +17,37 @@ Conduct a comprehensive pull request review using specialized agents for securit /pr-review [--repo owner/repo] ``` -## Behavior +## Workflow ### Step 1: Fetch PR Data -Using Gitea MCP tools: -1. `get_pull_request` - PR metadata -2. `get_pr_diff` - Code changes -3. `get_pr_comments` - Existing discussion +Load MCP tools, then: `get_pull_request`, `get_pr_diff`, `get_pr_comments` ### Step 2: Dispatch to Agents -The coordinator dispatches review tasks to specialized agents: +Execute `skills/review-workflow.md` - dispatch to Security, Performance, Maintainability, Test agents -``` -PR Review: #123 - Add user authentication -═══════════════════════════════════════════════════ +### Step 3: Aggregate and Filter -Dispatching to review agents: -├─ Security Reviewer → analyzing... -├─ Performance Analyst → analyzing... -├─ Maintainability Auditor → analyzing... -└─ Test Validator → analyzing... -``` +Apply confidence threshold (default: 0.7). See `skills/review-patterns/confidence-scoring.md` -### Step 3: Aggregate Findings +### Step 4: Generate Report -Collect findings from all agents, each with: -- Category (security, performance, maintainability, tests) -- Severity (critical, major, minor, suggestion) -- Confidence score (0.0 - 1.0) -- File and line reference -- Description -- Suggested fix (if applicable) +Use format from `skills/output-formats.md`. Group by severity: critical > major > minor > suggestion -### Step 4: Filter by Confidence +### Step 5: Determine Verdict -Filter findings based on `PR_REVIEW_CONFIDENCE_THRESHOLD` (default: 0.7): - -| Confidence | Label | Description | -|------------|-------|-------------| -| 0.9 - 1.0 | HIGH | Definite issue, must address | -| 0.7 - 0.89 | MEDIUM | Likely issue, should address | -| 0.5 - 0.69 | LOW | Possible concern, consider addressing | -| < threshold | (filtered) | Below configured threshold | - -**Note:** With the default threshold of 0.7, only MEDIUM and HIGH confidence findings are shown. Adjust `PR_REVIEW_CONFIDENCE_THRESHOLD` to include more or fewer findings. - -### Step 5: Generate Report - -``` -═══════════════════════════════════════════════════ -PR Review Report: #123 -═══════════════════════════════════════════════════ - -Summary: - Files changed: 12 - Lines added: 234 - Lines removed: 45 - -Findings: 8 total - 🔴 Critical: 1 - 🟠 Major: 2 - 🟡 Minor: 3 - 💡 Suggestions: 2 - -─────────────────────────────────────────────────── -CRITICAL FINDINGS -─────────────────────────────────────────────────── - -[SEC-001] SQL Injection Vulnerability (Confidence: 0.95) -File: src/api/users.ts:45 -Category: Security - -The query uses string interpolation without parameterization: -```ts -const query = `SELECT * FROM users WHERE id = ${userId}`; -``` - -Suggested fix: -```ts -const query = 'SELECT * FROM users WHERE id = ?'; -db.query(query, [userId]); -``` - -─────────────────────────────────────────────────── -MAJOR FINDINGS -─────────────────────────────────────────────────── - -[PERF-001] N+1 Query Pattern (Confidence: 0.82) -... - -─────────────────────────────────────────────────── -VERDICT -─────────────────────────────────────────────────── - -❌ REQUEST_CHANGES - -This PR has 1 critical security issue that must be addressed -before merging. See SEC-001 above. - -─────────────────────────────────────────────────── -``` +- Any critical or 2+ major: REQUEST_CHANGES +- Only minor/suggestions: COMMENT +- No significant findings: APPROVE ### Step 6: Submit Review (Optional) -``` -Submit this review to Gitea? -1. Yes, with REQUEST_CHANGES -2. Yes, as COMMENT only -3. No, just show me the report -``` - -If yes, use `create_pr_review` MCP tool. - -## Output - -Full review report with: -- Summary statistics -- Findings grouped by severity -- Code snippets with context -- Suggested fixes -- Overall verdict +Ask user to submit as REQUEST_CHANGES, COMMENT, or skip. Use `create_pr_review` MCP tool. ## Configuration -| Variable | Default | Description | -|----------|---------|-------------| -| `PR_REVIEW_CONFIDENCE_THRESHOLD` | `0.7` | Minimum confidence to report (0.0-1.0) | -| `PR_REVIEW_AUTO_SUBMIT` | `false` | Auto-submit to Gitea | +| Variable | Default | +|----------|---------| +| `PR_REVIEW_CONFIDENCE_THRESHOLD` | `0.7` | +| `PR_REVIEW_AUTO_SUBMIT` | `false` | diff --git a/plugins/pr-review/commands/pr-summary.md b/plugins/pr-review/commands/pr-summary.md index 02eaa6e..5a4cb3d 100644 --- a/plugins/pr-review/commands/pr-summary.md +++ b/plugins/pr-review/commands/pr-summary.md @@ -2,19 +2,13 @@ ## Visual Output -When executing this command, display the plugin header: +Display header: `PR-REVIEW - Quick Summary` -``` -┌──────────────────────────────────────────────────────────────────┐ -│ 🔍 PR-REVIEW · Quick Summary │ -└──────────────────────────────────────────────────────────────────┘ -``` +## Skills to Load -Then proceed with the summary. - -## Purpose - -Generate a quick summary of PR changes without conducting a full multi-agent review. +- skills/mcp-tools-reference.md +- skills/pr-analysis.md +- skills/output-formats.md ## Usage @@ -22,94 +16,26 @@ Generate a quick summary of PR changes without conducting a full multi-agent rev /pr-summary [--repo owner/repo] ``` -## Behavior +## Workflow ### Step 1: Fetch PR Data -Using Gitea MCP tools: -1. `get_pull_request` - PR metadata -2. `get_pr_diff` - Code changes +Load MCP tools, then: `get_pull_request`, `get_pr_diff` ### Step 2: Analyze Changes -Quick analysis of: -- Files modified -- Types of changes (features, fixes, refactoring) -- Scope and impact +Execute `skills/pr-analysis.md`: +- Categorize changes (feature, fix, refactor) +- Calculate statistics +- Identify key files +- Assess scope and risk ### Step 3: Generate Summary -``` -═══════════════════════════════════════════════════ -PR Summary: #123 - Add user authentication -═══════════════════════════════════════════════════ - -Author: @johndoe -Branch: feat/user-auth → development -Status: Open (ready for review) - -─────────────────────────────────────────────────── -CHANGES OVERVIEW -─────────────────────────────────────────────────── - -Files: 12 changed - + 8 new files - ~ 3 modified files - - 1 deleted file - -Lines: +234 / -45 (net +189) - -─────────────────────────────────────────────────── -WHAT THIS PR DOES -─────────────────────────────────────────────────── - -This PR adds user authentication functionality: - -1. **New API endpoints** - - POST /api/auth/login - - POST /api/auth/register - - POST /api/auth/logout - -2. **Frontend components** - - LoginForm component - - RegisterForm component - - Auth context provider - -3. **Database changes** - - New users table - - Sessions table - -─────────────────────────────────────────────────── -KEY FILES -─────────────────────────────────────────────────── - -• src/api/auth/login.ts (+85) - Login endpoint -• src/api/auth/register.ts (+120) - Registration -• src/components/LoginForm.tsx (+65) - Login UI -• src/db/migrations/001_users.sql (+45) - Schema - -─────────────────────────────────────────────────── -QUICK ASSESSMENT -─────────────────────────────────────────────────── - -Scope: Medium (authentication feature) -Risk: Medium (new security-sensitive code) -Recommendation: Full /pr-review suggested - -═══════════════════════════════════════════════════ -``` - -## Output - -Summary report with: -- PR metadata -- Change statistics -- Plain-language description of changes -- Key files list -- Quick risk assessment +Use summary format from `skills/output-formats.md` ## When to Use -- Get quick overview before full review +- Quick overview before full review - Triage multiple PRs -- Understand PR scope +- Decide if /pr-review is needed diff --git a/plugins/pr-review/commands/project-init.md b/plugins/pr-review/commands/project-init.md index d5d0885..3a285aa 100644 --- a/plugins/pr-review/commands/project-init.md +++ b/plugins/pr-review/commands/project-init.md @@ -1,148 +1,45 @@ --- -description: Quick project setup - configures only project-level settings for PR review +description: Quick project setup - configures only project-level settings --- # Project Initialization (PR Review) ## Visual Output -When executing this command, display the plugin header: +Display header: `PR-REVIEW - Project Setup` -``` -┌──────────────────────────────────────────────────────────────────┐ -│ 🔍 PR-REVIEW · Project Setup │ -└──────────────────────────────────────────────────────────────────┘ -``` +## Skills to Load -Then proceed with the setup. +- skills/setup-workflow.md +- skills/output-formats.md -Fast setup for a new project when system-level configuration is already complete. +## Purpose -**Use this when:** -- You've already run `/initial-setup` on this machine -- You're starting work on a new project/repository -- You just need to configure this project for PR reviews +Fast setup when system-level config already exists. ---- +**Use when:** Already ran `/initial-setup`, starting new project -## Pre-Flight Check +## Workflow -### Step 1: Verify System Configuration +### Pre-Flight Check -```bash -cat ~/.config/claude/gitea.env 2>/dev/null | grep -v "^#" | grep -v "PASTE_YOUR" | grep "GITEA_API_TOKEN=" && echo "SYSTEM_OK" || echo "SYSTEM_MISSING" -``` +Verify `~/.config/claude/gitea.env` exists. If missing: redirect to `/initial-setup` -**If SYSTEM_MISSING:** +### Project Setup ---- +Execute `skills/setup-workflow.md`: +1. Verify git repo +2. Check existing .env +3. Auto-detect org/repo from git remote +4. Validate via Gitea API +5. Create/update .env -**System configuration not found.** +### Complete -Please run `/initial-setup` first to configure Gitea credentials. +Display project configured format from `skills/output-formats.md` ---- +## Ready Commands -**If SYSTEM_OK:** Continue. - ---- - -## Project Setup - -### Step 2: Verify Current Directory - -```bash -pwd && git rev-parse --show-toplevel 2>/dev/null || echo "NOT_A_GIT_REPO" -``` - -### Step 3: Check Existing Configuration - -```bash -cat .env 2>/dev/null | grep "GITEA_REPO=" || echo "NOT_CONFIGURED" -``` - -If already configured, ask if user wants to keep or reconfigure. - -### Step 4: Detect Organization and Repository - -Extract organization: -```bash -git remote get-url origin 2>/dev/null | sed 's/.*[:/]\([^/]*\)\/[^/]*$/\1/' -``` - -Extract repository: -```bash -git remote get-url origin 2>/dev/null | sed 's/.*[:/]\([^/]*\)\.git$/\1/' | sed 's/.*\/\([^/]*\)$/\1/' -``` - -### Step 5: Validate Repository via Gitea API - -```bash -source ~/.config/claude/gitea.env -curl -s -o /dev/null -w "%{http_code}" -H "Authorization: token $GITEA_API_TOKEN" "$GITEA_API_URL/repos//" -``` - -| HTTP Code | Action | -|-----------|--------| -| **200** | Auto-fill - "Verified: / exists" - skip to Step 8 | -| **404** | Not found - proceed to Step 6 | -| **401/403** | Permission issue - warn, proceed to Step 6 | - -### Step 6: Confirm Organization (only if validation failed) - -Use AskUserQuestion: -- Question: "Repository not found. Is '' the correct organization?" -- Header: "Organization" -- Options: - - "Yes, that's correct" - - "No, let me specify" - -### Step 7: Confirm Repository (only if validation failed) - -Use AskUserQuestion: -- Question: "Is '' the correct repository?" -- Header: "Repository" -- Options: - - "Yes, that's correct" - - "No, let me specify" - -**After corrections, re-validate via API (Step 5).** - -### Step 8: Create/Update .env - -```bash -echo "GITEA_ORG=" >> .env -echo "GITEA_REPO=" >> .env -``` - -### Step 9: Optional PR Review Settings - -Use AskUserQuestion: -- Question: "Configure PR review settings?" -- Header: "Settings" -- Options: - - "Use defaults (Recommended)" - - "Customize settings" - -If customize: -- `PR_REVIEW_CONFIDENCE_THRESHOLD` (default: 0.5) -- `PR_REVIEW_AUTO_SUBMIT` (default: false) - ---- - -## Complete - -``` -╔══════════════════════════════════════════════════════════════╗ -║ PROJECT CONFIGURED ║ -╠══════════════════════════════════════════════════════════════╣ -║ Organization: ║ -║ Repository: ║ -║ Config file: ./.env ║ -╚══════════════════════════════════════════════════════════════╝ - -Ready to review PRs: -• /pr-review - Full multi-agent review -• /pr-summary - Quick summary -• /pr-findings - List findings -``` +- `/pr-review ` - Full review +- `/pr-summary ` - Quick summary +- `/pr-findings ` - List findings diff --git a/plugins/pr-review/commands/project-sync.md b/plugins/pr-review/commands/project-sync.md index caa30f8..1e49d00 100644 --- a/plugins/pr-review/commands/project-sync.md +++ b/plugins/pr-review/commands/project-sync.md @@ -1,105 +1,32 @@ --- -description: Sync project configuration with current git remote - use after changing repository location +description: Sync project configuration with current git remote --- # Project Sync (PR Review) ## Visual Output -When executing this command, display the plugin header: +Display header: `PR-REVIEW - Project Sync` -``` -┌──────────────────────────────────────────────────────────────────┐ -│ 🔍 PR-REVIEW · Project Sync │ -└──────────────────────────────────────────────────────────────────┘ -``` +## Skills to Load -Then proceed with the synchronization. +- skills/setup-workflow.md +- skills/output-formats.md -Updates project configuration when the git remote URL has changed. +## Purpose -**Use this when:** -- Repository was moved to a different organization -- Repository was renamed -- Git remote URL changed -- SessionStart hook detected a mismatch +Updates config when git remote URL changed. ---- +**Use when:** Repo moved/renamed, SessionStart detected mismatch -## Step 1: Verify System Configuration +## Workflow -```bash -cat ~/.config/claude/gitea.env 2>/dev/null | grep -v "^#" | grep -v "PASTE_YOUR" | grep "GITEA_API_TOKEN=" && echo "SYSTEM_OK" || echo "SYSTEM_MISSING" -``` +Execute `skills/setup-workflow.md` Sync Workflow: -**If SYSTEM_MISSING:** Run `/initial-setup` first. - ---- - -## Step 2: Read Current .env - -```bash -cat .env 2>/dev/null -``` - -Extract `GITEA_ORG` and `GITEA_REPO` values. - -**If missing:** Redirect to `/project-init`. - ---- - -## Step 3: Detect Git Remote - -```bash -git remote get-url origin 2>/dev/null -``` - -Extract organization and repository from URL. - ---- - -## Step 4: Compare Values - -| Scenario | Action | -|----------|--------| -| **Match** | "Configuration in sync" - exit | -| **Mismatch** | Show diff, proceed to validation | - ---- - -## Step 5: Validate via Gitea API - -```bash -source ~/.config/claude/gitea.env -curl -s -o /dev/null -w "%{http_code}" -H "Authorization: token $GITEA_API_TOKEN" "$GITEA_API_URL/repos//" -``` - -| Code | Action | -|------|--------| -| **200** | Verified - proceed to update | -| **404** | Not found - ask to confirm | -| **401/403** | Permission issue - warn | - ---- - -## Step 6: Confirm and Update - -Use AskUserQuestion to confirm, then update .env: - -```bash -sed -i 's/^GITEA_ORG=.*/GITEA_ORG=/' .env -sed -i 's/^GITEA_REPO=.*/GITEA_REPO=/' .env -``` - ---- - -## Step 7: Confirm Success - -``` -╔══════════════════════════════════════════════════════════════╗ -║ CONFIGURATION UPDATED ║ -╠══════════════════════════════════════════════════════════════╣ -║ Organization: ║ -║ Repository: ║ -╚══════════════════════════════════════════════════════════════╝ -``` +1. Verify system config exists +2. Read current .env values +3. Detect org/repo from git remote +4. Compare - if match, exit; if mismatch, continue +5. Validate new values via API +6. Update .env with sed +7. Display confirmation from `skills/output-formats.md` diff --git a/plugins/pr-review/skills/mcp-tools-reference.md b/plugins/pr-review/skills/mcp-tools-reference.md new file mode 100644 index 0000000..a9f9ddf --- /dev/null +++ b/plugins/pr-review/skills/mcp-tools-reference.md @@ -0,0 +1,80 @@ +# MCP Tools Reference - Gitea PR Operations + +## Available Tools + +Use `ToolSearch` to load these tools before use. + +### Pull Request Tools + +| Tool | Purpose | +|------|---------| +| `mcp__gitea__list_pull_requests` | List PRs (open, closed, all) | +| `mcp__gitea__get_pull_request` | Get PR metadata, status, labels | +| `mcp__gitea__get_pr_diff` | Get unified diff of changes | +| `mcp__gitea__get_pr_comments` | Get review comments and discussions | +| `mcp__gitea__create_pr_review` | Submit review (approve, comment, request changes) | +| `mcp__gitea__add_pr_comment` | Add single comment to PR | +| `mcp__gitea__create_pull_request` | Create new PR | + +### Supporting Tools + +| Tool | Purpose | +|------|---------| +| `mcp__gitea__get_issue` | Get linked issue details | +| `mcp__gitea__get_labels` | Get available labels | +| `mcp__gitea__validate_repo_org` | Validate repository exists | + +## Loading Tools + +Before using MCP tools, load them: + +``` +Use ToolSearch with query: "+gitea pull_request" +``` + +## Common Operations + +### Fetch PR for Review + +``` +1. get_pull_request(pr_number) -> metadata +2. get_pr_diff(pr_number) -> code changes +3. get_pr_comments(pr_number) -> existing feedback +``` + +### Submit Review + +``` +create_pr_review: + pr_number: number + body: string (review summary) + event: "APPROVE" | "COMMENT" | "REQUEST_CHANGES" + comments: [{path, line, body}] (optional inline comments) +``` + +### Add Comment + +``` +add_pr_comment: + pr_number: number + body: string +``` + +## Environment Variables + +Required in `.env`: +- `GITEA_ORG` - Organization/owner name +- `GITEA_REPO` - Repository name + +Required in `~/.config/claude/gitea.env`: +- `GITEA_API_URL` - Gitea server URL +- `GITEA_API_TOKEN` - API token with repo permissions + +## Error Handling + +| Error | Cause | Resolution | +|-------|-------|------------| +| Tool not found | MCP not loaded | Run ToolSearch first | +| 401 Unauthorized | Invalid/expired token | Regenerate token | +| 404 Not Found | Wrong org/repo or PR doesn't exist | Check .env settings | +| 403 Forbidden | Insufficient permissions | Check token scopes | diff --git a/plugins/pr-review/skills/output-formats.md b/plugins/pr-review/skills/output-formats.md new file mode 100644 index 0000000..c363f9b --- /dev/null +++ b/plugins/pr-review/skills/output-formats.md @@ -0,0 +1,200 @@ +# Output Formats + +## Visual Header + +All commands display this header: + +``` ++----------------------------------------------------------------------+ +| PR-REVIEW [Command Name] | ++----------------------------------------------------------------------+ +``` + +## Review Report Format + +``` +=================================================== +PR Review Report: # +=================================================== + +Summary: + Files changed: + Lines: + / - + Agents consulted: + +Findings: + Critical: + Major: + Minor: + Suggestions: + +--------------------------------------------------- +CRITICAL FINDINGS +--------------------------------------------------- + +[] (Confidence: <score>) +File: <path>:<line> +Category: <category> + +<Description> + +Suggested fix: +<code block> + +--------------------------------------------------- +VERDICT: <APPROVE|COMMENT|REQUEST_CHANGES> +--------------------------------------------------- + +<Justification> +``` + +## Summary Format + +``` +=================================================== +PR Summary: #<number> - <title> +=================================================== + +Author: @<username> +Branch: <head> -> <base> +Status: <status> + +--------------------------------------------------- +CHANGES OVERVIEW +--------------------------------------------------- + +Files: <n> changed + + <n> new files + ~ <n> modified files + - <n> deleted files + +Lines: +<added> / -<removed> (net +<diff>) + +--------------------------------------------------- +WHAT THIS PR DOES +--------------------------------------------------- + +<Plain-language description> + +--------------------------------------------------- +KEY FILES +--------------------------------------------------- + +* <path> (+<lines>) - <description> + +--------------------------------------------------- +QUICK ASSESSMENT +--------------------------------------------------- + +Scope: <Small|Medium|Large> +Risk: <Low|Medium|High> +Recommendation: <action> +=================================================== +``` + +## Findings List Format + +### Detailed (default) + +``` +=================================================== +PR #<number> Findings (filtered: <filter>) +=================================================== + +Showing <n> of <total> findings + +--------------------------------------------------- + +[<ID>] <Title> +Confidence: <score> (<label>) | Severity: <level> +File: <path>:<line> + +<Description> + +Fix: <suggestion> + +--------------------------------------------------- +``` + +### Compact (--compact) + +``` +<ID> | <Severity> | <Confidence> | <File>:<Line> | <Title> +``` + +### JSON (--json) + +```json +{ + "pr": <number>, + "findings": [ + { + "id": "<ID>", + "category": "<category>", + "severity": "<severity>", + "confidence": <score>, + "file": "<path>", + "line": <number>, + "title": "<title>", + "description": "<description>", + "fix": "<suggestion>" + } + ] +} +``` + +## Setup Complete Format + +``` ++============================================================+ +| PR-REVIEW SETUP COMPLETE | ++============================================================+ +| MCP Server (Gitea): Ready | +| System Config: ~/.config/claude/gitea.env | +| Project Config: ./.env | ++============================================================+ +``` + +## Project Configured Format + +``` ++============================================================+ +| PROJECT CONFIGURED | ++============================================================+ +| Organization: <org> | +| Repository: <repo> | +| Config file: ./.env | ++============================================================+ + +Ready to review PRs: +- /pr-review <number> Full multi-agent review +- /pr-summary <number> Quick summary +- /pr-findings <number> List findings +``` + +## Annotated Diff Format + +``` +=================================================== +PR #<number> Diff - <title> +=================================================== + +Branch: <head> -> <base> +Files: <n> changed (+<added> / -<removed>) + +--------------------------------------------------- +<file> (+<added> / -<removed>) +--------------------------------------------------- + +@@ -<old>,<ctx> +<new>,<ctx> @@ <context> + <line> | existing code + <line> |- removed code + | +--- COMMENT by @<user> (<time>) --- + | | <comment text> + | +----------------------------------- + <line> |+ added code + +=================================================== +Comment Summary: <n> comments, <n> resolved +=================================================== +``` diff --git a/plugins/pr-review/skills/pr-analysis.md b/plugins/pr-review/skills/pr-analysis.md new file mode 100644 index 0000000..abacebf --- /dev/null +++ b/plugins/pr-review/skills/pr-analysis.md @@ -0,0 +1,135 @@ +# PR Analysis Patterns + +## Data Collection + +### Step 1: Fetch PR Metadata + +``` +get_pull_request(pr_number) returns: +- title, description +- author, assignees +- base/head branches +- status (open, closed, merged) +- labels, milestone +- created_at, updated_at +``` + +### Step 2: Get Code Changes + +``` +get_pr_diff(pr_number) returns: +- Unified diff format +- File paths with +/- indicators +- Hunk headers with line numbers +``` + +### Step 3: Get Existing Feedback + +``` +get_pr_comments(pr_number) returns: +- Review comments with file/line +- General comments +- Author, timestamp +- Thread context (replies) +``` + +## Change Analysis + +### Categorize Changes + +| Pattern | Category | +|---------|----------| +| New files only | Feature addition | +| Modified test files | Test updates | +| Modified + deleted | Refactoring | +| Single file fix | Bug fix | +| Config/docs only | Infrastructure | + +### Calculate Statistics + +- Files changed count +- Lines added/removed +- Net change (+added - removed) +- New vs modified vs deleted files + +### Identify Key Files + +Priority order: +1. Security-sensitive (`auth`, `crypto`, `sql`) +2. API endpoints +3. Database migrations +4. Core business logic +5. Utilities and helpers +6. Tests +7. Documentation + +## Risk Assessment + +### Scope Assessment + +| Files Changed | Lines Changed | Scope | +|---------------|---------------|-------| +| 1-3 | < 50 | Small | +| 4-10 | 50-200 | Medium | +| 10+ | 200+ | Large | + +### Risk Indicators + +| Indicator | Risk Level | +|-----------|------------| +| Security-sensitive files | High | +| Database migrations | High | +| API changes | Medium | +| New dependencies | Medium | +| Test-only changes | Low | +| Docs-only changes | Low | + +## Summary Generation + +### Quick Summary Template + +``` +This PR [adds|updates|fixes|removes] [feature/component]: + +1. **[Category 1]** + - Change description + +2. **[Category 2]** + - Change description + +Key files: +- path/to/important/file.ts (+lines) +``` + +### Assessment Template + +``` +Scope: [Small|Medium|Large] +Risk: [Low|Medium|High] +Recommendation: [/pr-review suggested | Looks good to merge] +``` + +## Annotated Diff Display + +### Format + +``` +File: src/api/users.ts (+85 / -12) +---------------------------------------- + +@@ -42,6 +42,15 @@ function description + 42 | existing line + 43 | + 44 |- removed line + | [COMMENT by @user (time ago)] + | Comment text here + 45 |+ added line + 46 |+ another added line +``` + +### Comment Overlay + +Position comments at their file/line locations: +- Show commenter username and time +- Include reply threads +- Mark resolved vs open diff --git a/plugins/pr-review/skills/review-workflow.md b/plugins/pr-review/skills/review-workflow.md new file mode 100644 index 0000000..2f0d9fe --- /dev/null +++ b/plugins/pr-review/skills/review-workflow.md @@ -0,0 +1,78 @@ +# Multi-Agent Review Workflow + +## Overview + +PR reviews use specialized agents that analyze different aspects of code changes. The coordinator dispatches to relevant agents and aggregates findings. + +## Agent Roles + +| Agent | Focus Area | File Patterns | +|-------|------------|---------------| +| **Security Reviewer** | Vulnerabilities, auth, injection | `*.ts`, `*.js`, `*.sql`, `*.py` | +| **Performance Analyst** | N+1, inefficient algorithms, memory | `*.ts`, `*.js`, `*.py`, `*.go` | +| **Maintainability Auditor** | Complexity, readability, DRY | All code files | +| **Test Validator** | Coverage, edge cases, assertions | `*.test.*`, `*_test.*`, `*_spec.*` | + +## Dispatch Logic + +1. **Analyze changed files** - Identify file types and patterns +2. **Select agents** - Match files to relevant agents +3. **Parallel dispatch** - Send review tasks to agents +4. **Collect findings** - Aggregate results from all agents +5. **Filter by confidence** - Apply threshold (default: 0.7) +6. **Generate report** - Structure findings by severity + +### Skip Patterns + +Don't dispatch agents for: +- `*.md`, `*.txt` - Documentation only +- `*.json` (config) - Unless security-sensitive +- Generated files - `*.min.js`, `*.d.ts`, etc. + +## Finding Structure + +Each finding includes: + +``` +{ + id: "SEC-001", + category: "security" | "performance" | "maintainability" | "tests", + severity: "critical" | "major" | "minor" | "suggestion", + confidence: 0.0 - 1.0, + file: "src/api/users.ts", + line: 45, + title: "SQL Injection Vulnerability", + description: "Detailed explanation...", + fix: "Suggested code fix..." (optional) +} +``` + +## Verdict Logic + +| Condition | Verdict | +|-----------|---------| +| Any critical finding | REQUEST_CHANGES | +| 2+ major findings | REQUEST_CHANGES | +| Only minor/suggestions | COMMENT | +| No significant findings | APPROVE | + +## Confidence Thresholds + +Reference: `skills/review-patterns/confidence-scoring.md` + +| Range | Label | Action | +|-------|-------|--------| +| 0.9 - 1.0 | HIGH | Must address | +| 0.7 - 0.89 | MEDIUM | Should address | +| 0.5 - 0.69 | LOW | Consider addressing | +| < threshold | Filtered | Not shown | + +Default threshold: 0.7 (MEDIUM and above) + +## Aggregation Rules + +When multiple agents find the same issue: +1. Keep highest confidence score +2. Merge descriptions +3. Use most severe category +4. Deduplicate fixes diff --git a/plugins/pr-review/skills/setup-workflow.md b/plugins/pr-review/skills/setup-workflow.md new file mode 100644 index 0000000..b4b262d --- /dev/null +++ b/plugins/pr-review/skills/setup-workflow.md @@ -0,0 +1,104 @@ +# Setup Workflow + +## Configuration Hierarchy + +| Level | Location | Contents | +|-------|----------|----------| +| System | `~/.config/claude/gitea.env` | API URL, token (shared across projects) | +| Project | `.env` in project root | Org, repo name (per project) | + +## System Configuration + +### Check Existing + +```bash +cat ~/.config/claude/gitea.env 2>/dev/null | grep -v "^#" | grep "GITEA_API_TOKEN=" && echo "OK" || echo "MISSING" +``` + +### Create New + +```bash +mkdir -p ~/.config/claude +cat > ~/.config/claude/gitea.env << 'EOF' +# Gitea API Configuration +GITEA_API_URL=https://your-gitea-server.com +GITEA_API_TOKEN=PASTE_YOUR_TOKEN_HERE +EOF +chmod 600 ~/.config/claude/gitea.env +``` + +### Token Generation + +1. Gitea: Settings > Applications > Generate New Token +2. Required scopes: `repo`, `read:org`, `read:user` + +## Project Configuration + +### Auto-Detect from Git Remote + +Extract organization: +```bash +git remote get-url origin 2>/dev/null | sed 's/.*[:/]\([^/]*\)\/[^/]*$/\1/' +``` + +Extract repository: +```bash +git remote get-url origin 2>/dev/null | sed 's/.*[:/]\([^/]*\)\.git$/\1/' | sed 's/.*\/\([^/]*\)$/\1/' +``` + +### Validate via API + +```bash +source ~/.config/claude/gitea.env +curl -s -o /dev/null -w "%{http_code}" -H "Authorization: token $GITEA_API_TOKEN" "$GITEA_API_URL/repos/<org>/<repo>" +``` + +| Code | Meaning | +|------|---------| +| 200 | Repository verified | +| 404 | Not found - check org/repo names | +| 401/403 | Auth issue - check token | + +### Create/Update .env + +```bash +# New file +cat > .env << EOF +GITEA_ORG=<org> +GITEA_REPO=<repo> +EOF + +# Or append to existing +echo "GITEA_ORG=<org>" >> .env +echo "GITEA_REPO=<repo>" >> .env +``` + +## PR Review Settings (Optional) + +| Variable | Default | Description | +|----------|---------|-------------| +| `PR_REVIEW_CONFIDENCE_THRESHOLD` | `0.7` | Minimum confidence to report | +| `PR_REVIEW_AUTO_SUBMIT` | `false` | Auto-submit reviews to Gitea | + +## Sync Workflow + +When git remote changes: + +1. Detect new org/repo from git remote +2. Compare with .env values +3. Validate new values via API +4. Update .env with sed: + +```bash +sed -i 's/^GITEA_ORG=.*/GITEA_ORG=<new_org>/' .env +sed -i 's/^GITEA_REPO=.*/GITEA_REPO=<new_repo>/' .env +``` + +## Shared with projman + +The Gitea MCP server is shared with the projman plugin. If projman is already configured, system-level setup can be skipped. + +Check for projman: +```bash +find ~/.claude ~/.config/claude -name "projman" -type d 2>/dev/null | head -1 +```