personal-projects/leo-claude-mktplace
Template
0
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(clarity-assist): extract skills from commands

Browse Source 
Extract shared knowledge from clarify.md and quick-clarify.md into
reusable skill files:
- 4d-methodology.md: Core 4-phase clarification process
- nd-accommodations.md: Neurodivergent-friendly question patterns
- clarification-techniques.md: Anti-patterns and question templates
- escalation-patterns.md: Mode switching guidelines

Commands slimmed from 149/96 lines to 44/49 lines respectively.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Leo Miranda
2026-01-30 17:23:40 -05:00
parent 747a2b15e5
commit 5bf1271347
18 changed files with 1067 additions and 1141 deletions
Download Patch File Download Diff File Expand all files Collapse all files

135
plugins/clarity-assist/commands/clarify.md
View File

@@ -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.

89
plugins/clarity-assist/commands/quick-clarify.md
View File

@@ -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?"
```

76
plugins/clarity-assist/skills/4d-methodology.md Normal file
View File

@@ -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]
```

86
plugins/clarity-assist/skills/clarification-techniques.md Normal file
View File

@@ -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)"
```

57
plugins/clarity-assist/skills/escalation-patterns.md Normal file
View File

@@ -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

74
plugins/clarity-assist/skills/nd-accommodations.md Normal file
View File

@@ -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?"
```

282
plugins/pr-review/commands/initial-setup.md
View File

@@ -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=<USER_PROVIDED_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/<detected-org>/<detected-repo>"
```
| HTTP Code | Action |
|-----------|--------|
| **200** | Auto-fill - "Verified: <org>/<repo> 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 '<detected-org>' 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 '<detected-repo-name>' 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=<ORG_NAME>" >> .env
echo "GITEA_REPO=<REPO_NAME>" >> .env
```
If `.env` doesn't exist:
```bash
cat > .env << 'EOF'
# Project Configuration
GITEA_ORG=<ORG_NAME>
GITEA_REPO=<REPO_NAME>
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 <PR_NUMBER>` to review a pull request
- Run `/pr-summary <PR_NUMBER>` for a quick summary
- Run `/pr-findings <PR_NUMBER>` to list actionable findings
---
Test API connection, display completion summary, remind to restart session
## Available Commands After Setup
| Command | Description |
|---------|-------------|
| `/pr-review <number>` | Full multi-agent PR review with confidence scoring |
| `/pr-summary <number>` | Quick PR summary |
| `/pr-findings <number>` | List findings with severity and line numbers |
- `/pr-review <number>` - Full multi-agent review
- `/pr-summary <number>` - Quick summary
- `/pr-findings <number>` - List findings

160
plugins/pr-review/commands/pr-diff.md
View File

@@ -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 <pr-number> [--repo owner/repo] [--context <lines>]
/pr-diff <pr-number> [--repo owner/repo] [--context <n>] [--no-comments] [--file <pattern>]
```
### Options
## Workflow
```
--repo <owner/repo> Override repository (default: from .env)
--context <n> Lines of context around changes (default: 3)
--no-comments Show diff without comment annotations
--file <pattern> 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 |

146
plugins/pr-review/commands/pr-findings.md
View File

@@ -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 <pr-number> [filters]
/pr-findings <pr-number> [--category <cat>] [--severity <sev>] [--confidence <min>] [--file <pattern>] [--compact] [--json]
```
### Filters
```
--category <cat> Filter by category (security, performance, maintainability, tests)
--severity <sev> Filter by severity (critical, major, minor, suggestion)
--confidence <min> Minimum confidence score (0.0-1.0)
--file <pattern> 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

144
plugins/pr-review/commands/pr-review.md
View File

@@ -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 <pr-number> [--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` |

104
plugins/pr-review/commands/pr-summary.md
View File

@@ -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 <pr-number> [--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

151
plugins/pr-review/commands/project-init.md
View File

@@ -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/<detected-org>/<detected-repo>"
```
| HTTP Code | Action |
|-----------|--------|
| **200** | Auto-fill - "Verified: <org>/<repo> 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 '<detected-org>' 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 '<detected-repo-name>' 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=<ORG_NAME>" >> .env
echo "GITEA_REPO=<REPO_NAME>" >> .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: <ORG_NAME> ║
║ Repository: <REPO_NAME> ║
║ Config file: ./.env ║
╚══════════════════════════════════════════════════════════════╝
Ready to review PRs:
• /pr-review <number> - Full multi-agent review
• /pr-summary <number> - Quick summary
• /pr-findings <number> - List findings
```
- `/pr-review <number>` - Full review
- `/pr-summary <number>` - Quick summary
- `/pr-findings <number>` - List findings

107
plugins/pr-review/commands/project-sync.md
View File

@@ -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/<NEW_ORG>/<NEW_REPO>"
```
| 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=<NEW_ORG>/' .env
sed -i 's/^GITEA_REPO=.*/GITEA_REPO=<NEW_REPO>/' .env
```
---
## Step 7: Confirm Success
```
╔══════════════════════════════════════════════════════════════╗
║ CONFIGURATION UPDATED ║
╠══════════════════════════════════════════════════════════════╣
║ Organization: <NEW_ORG> ║
║ Repository: <NEW_REPO> ║
╚══════════════════════════════════════════════════════════════╝
```
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`

80
plugins/pr-review/skills/mcp-tools-reference.md Normal file
View File

@@ -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 |

200
plugins/pr-review/skills/output-formats.md Normal file
View File

@@ -0,0 +1,200 @@
# Output Formats
## Visual Header
All commands display this header:
```
+----------------------------------------------------------------------+
| PR-REVIEW [Command Name] |
+----------------------------------------------------------------------+
```
## Review Report Format
```
===================================================
PR Review Report: #<number>
===================================================
Summary:
Files changed: <n>
Lines: +<added> / -<removed>
Agents consulted: <list>
Findings: <total>
Critical: <n>
Major: <n>
Minor: <n>
Suggestions: <n>
---------------------------------------------------
CRITICAL FINDINGS
---------------------------------------------------
[<ID>] <Title> (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
===================================================
```

135
plugins/pr-review/skills/pr-analysis.md Normal file
View File

@@ -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

78
plugins/pr-review/skills/review-workflow.md Normal file
View File

@@ -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

104
plugins/pr-review/skills/setup-workflow.md Normal file
View File

@@ -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
```