code-quality

Claude Code plugins for ResRequest development, providing code quality tools, automated reviews, and documentation generation for VILT stack projects.

What's Included

Documentation Plugin

Automated feature documentation generator for PM and support team workflows:

`/generate-feature-docs` - Generate Feature Documentation

• •Powered by feature-documenter agent for comprehensive documentation
• •Automatically generates two files:

- [branch-name]_Technical-Documentation.md - For developers - [branch-name]_User-Guide.md - For support team

• •Analyzes git changes to extract routes, migrations, models, policies
• •Documents permissions and authorization rules
• •Includes limitations and access restrictions
• •Troubleshooting guide with common errors and solutions
• •Uses UK English throughout (authorisation, behaviour, etc.)
• •Perfect for PM workflow - run before creating merge requests

Code Quality Plugin

Complete code quality solution powered by specialized agents:

`/code-review` - Automated Review

• •Powered by vilt-reviewer agent for VILT stack best practices
• •Vue 3: Composition API, component structure, TypeScript
• •Inertia.js: Proper usage patterns, form handling, avoiding axios
• •Laravel: RESTful routes, validation, Eloquent, security, coding standards
• •Tailwind CSS: Utility-first approach, responsive design
• •Translation Detection: Flags hardcoded user-facing strings
• •Code Cleanliness: Detects debugging code and unnecessary comments
• •Code Duplication: Detects duplicate methods and recommends trait extraction
• •Generates detailed CODE_REVIEW.md file

`/code-fix` - Automated Fixes

• •Powered by code-fixer agent for safe, interactive code fixes
• •Applies fixes from CODE_REVIEW.md one at a time with user permission
• •Priority-based fixing: CRITICAL → IMPORTANT → SUGGESTION
• •Shows before/after for each fix
• •Updates CODE_REVIEW.md with progress tracking (strikes through completed items)
• •Prompts to re-run /code-review after fixes for verification
• •Never auto-commits changes
• •Generates FIXES_APPLIED.md summary

Installation

1. Add the ResRequest Marketplace

Option A: From GitLab via SSH (Recommended for teams)

/plugin marketplace add [email protected]:resrequest/resrequest-plugins.git

Note: Requires SSH key configured with GitLab. See GitLab SSH Keys if you need to set this up.

Option B: Local development

If you've cloned the repository locally, add it from your local path:

# macOS/Linux
/plugin marketplace add ~/path/to/resrequest-plugins

# Windows
/plugin marketplace add C:\path\to\resrequest-plugins

# Or use absolute path from anywhere
/plugin marketplace add /absolute/path/to/resrequest-plugins

2. Install Plugins

Install Documentation Plugin:

/plugin install documentation@resrequest

Install Code Quality Plugin:

/plugin install code-quality@resrequest

Or install both:

/plugin install documentation@resrequest code-quality@resrequest

3. Verify Installation

/plugin list

You should see documentation and code-quality in the installed plugins list.

Usage

Generating Feature Documentation

When your feature branch is complete, generate documentation for developers and support team:

/generate-feature-docs

This will:

1. Extract current branch name (removes feature/ prefix)
2. Analyze all changes in the branch (committed + uncommitted)
3. Generate [branch-name]_Technical-Documentation.md with:

- Routes, controllers, models, migrations - Authorization rules and policies - Database changes and configuration - Testing considerations and deployment notes - Known limitations

1. Generate [branch-name]_User-Guide.md with:

- Plain language explanation of features - Step-by-step usage instructions - Permissions and access restrictions - Troubleshooting common issues - Error messages and meanings

1. Use UK English throughout

When to use:

• •Before creating a merge request
• •When feature is complete and ready for review
• •To document changes for PM and support team

Example output:

✅ Feature documentation generated!

📄 Files created:
- user-management_Technical-Documentation.md (for developers)
- user-management_User-Guide.md (for support team)

📊 Summary:
- Routes documented: 5
- Controllers: 2
- Models: 1
- Migrations: 2
- Vue pages/components: 3

Running a Code Review

Simply run the slash command:

/code-review

This will:

1. Analyze all changes in your current branch (committed + uncommitted)
2. Review code against VILT best practices and Laravel coding standards
3. Flag hardcoded strings that should be translated
4. Check for axios usage (should use Inertia instead)
5. Detect debugging code (dd(), console.log(), etc.)
6. Identify unnecessary comments that should be self-documenting code
7. Identify security concerns and code quality issues
8. Generate a detailed `CODE_REVIEW.md` file with all findings

You can optionally specify a base branch: /code-review main or specific files: /code-review main app/Http/Controllers/UserController.php

The review will be saved to CODE_REVIEW.md in your project root with a detailed report you can reference, share, or attach to merge requests.

Applying Fixes Automatically

After running /code-review, use /code-fix to automatically apply the suggested fixes:

/code-fix

This will:

1. Read the CODE_REVIEW.md file
2. Fix issues one at a time in priority order ([CRITICAL] → [IMPORTANT] → [SUGGESTION])
3. Show you each issue with current code and proposed fix
4. Ask permission before applying each fix
5. Track what was fixed and generate a FIXES_APPLIED.md summary
6. Never auto-commit - you review changes in your editor first

Filter options:

/code-fix --critical-only              # Only fix critical issues
/code-fix --important-only             # Only fix important issues
/code-fix app/Http/Controllers/        # Only fix issues in specific file/directory

Example interaction:

[Issue 1/12] [CRITICAL] app/Http/Controllers/UserController.php:45
Issue Type: Security - Missing authorization check

Current code:
  public function destroy(User $user) {
      $user->delete();
  }

Proposed fix:
  public function destroy(User $user) {
      $this->authorize('delete', $user);
      $user->delete();
  }

Apply this fix? [Yes/No/Skip all CRITICAL/Stop]
→ Yes
✅ Fixed!

What happens after each fix:

• •The fix is applied to your code
• •CODE_REVIEW.md is automatically updated with progress tracking:

- Fixed items are struck through with ✅ - "Next Steps" checklist is updated - Timestamp added showing when fixes were applied

• •Progress is tracked in FIXES_APPLIED.md

After all fixes:

• •You'll get a summary and detailed FIXES_APPLIED.md file
• •CODE_REVIEW.md becomes a living document showing what's done and what's left
• •You'll be prompted: "Would you like to re-run /code-review to verify fixes?"

- Choose "Yes" to immediately verify all fixes worked - Choose "No" to run it manually later - Choose "After tests" for helpful workflow reminders

What the Review Checks

VILT Best Practices

• •Vue 3 Composition API patterns
• •Inertia.js usage (no axios!)
• •Laravel conventions and security
• •Tailwind CSS utility-first approach

Translation Requirements

• •Hardcoded button labels
• •Form labels and placeholders
• •Error and success messages
• •Modal titles and content
• •Any user-facing text

Code Quality

• •Component structure and organization
• •Proper validation and error handling
• •Security vulnerabilities (XSS, SQL injection, auth)
• •Performance issues (N+1 queries)
• •Debugging code detection (dd(), dump(), console.log())
• •Unnecessary comments (prefers self-documenting code)
• •Code duplication detection (duplicate methods across files)
• •Trait extraction recommendations (DRY principle violations)
• •Laravel coding standards compliance

Example Output

After running /code-review, you'll see a terminal summary and a detailed CODE_REVIEW.md file will be created:

Terminal:

✅ Code review complete!

📄 Review saved to: CODE_REVIEW.md

Summary:
- Files reviewed: 5
- [CRITICAL]: 2 issues
- [IMPORTANT]: 3 issues
- [SUGGESTION]: 1 issue

⚠️ Action required: Fix 2 critical issues before merge

Open CODE_REVIEW.md for detailed findings and fixes.

CODE_REVIEW.md:

# Code Review Report

**Date**: 2025-01-15 14:30
**Branch**: feature/user-management
**Base Branch**: main
**Files Reviewed**: 5 files

## File: `app/Http/Controllers/UserController.php`

### Line 45: [CRITICAL] Missing Authorization
**Issue Type**: Security
**Problem**: No authorization check before deleting user
**Why it matters**: Security vulnerability - any authenticated user can delete other users
**Fix**:
\`\`\`php
public function destroy(User $user)
{
    $this->authorize('delete', $user);
    $user->delete();
    return redirect()->route('users.index');
}
\`\`\`

## File: `resources/js/Pages/Dashboard.vue`

### Line 23: [IMPORTANT] Improper Inertia Usage
**Issue Type**: Inertia
**Problem**: Using axios to fetch data instead of Inertia
**Why it matters**: Should use Inertia for all data fetching in VILT stack
**Fix**:
Pass data as props from Laravel controller instead of client-side fetching

Customizing the Plugin

Editing Review Criteria

The review behavior is defined in the specialized agent:

code-quality/
├── agents/vilt-reviewer.md        # Agent with detailed review instructions
└── commands/code-review.md        # Command that delegates to agent

To customize:

1. Edit code-quality/agents/vilt-reviewer.md to adjust review criteria and agent behavior
2. Edit code-quality/commands/code-review.md to change how the command invokes the agent
3. Changes take effect immediately (no reinstall needed)
4. Commit and push changes to share with team

The agent-based architecture provides:

• •Separate context window for reviews (doesn't clutter main conversation)
• •More detailed system prompts with VILT expertise
• •Reusable across multiple ResRequest projects

Adding New Checks

Edit agents/vilt-reviewer.md and add your criteria to the relevant section. For example:

### 8. Custom Business Rules
- Check for proper error logging
- Verify API rate limiting on public endpoints
- Ensure all database queries use indexes
- Validate ResRequest-specific naming conventions

Development Workflow

Testing Changes Locally

1. Make edits to plugin files
2. Reinstall the plugin:

``bash /plugin uninstall code-quality /plugin install code-quality@resrequest ``

1. Test with /code-review

Publishing Updates

1. Update version in code-quality/.claude-plugin/plugin.json
2. Update version in .claude-plugin/marketplace.json
3. Commit and push to GitLab
4. Team members will be notified of updates

Marketplace Structure

resrequest-plugins/
├── .claude-plugin/
│   └── marketplace.json           # Marketplace definition
├── documentation/                 # Documentation plugin
│   ├── .claude-plugin/
│   │   └── plugin.json           # Plugin metadata
│   ├── agents/
│   │   └── feature-documenter.md # Feature documentation agent
│   └── commands/
│       └── generate-feature-docs.md # Documentation command
├── code-quality/                  # Code quality plugin
│   ├── .claude-plugin/
│   │   └── plugin.json           # Plugin metadata
│   ├── agents/
│   │   ├── vilt-reviewer.md      # Specialized VILT review agent
│   │   └── code-fixer.md         # Automated code fixer agent
│   └── commands/
│       ├── code-review.md        # Review command (delegates to vilt-reviewer)
│       └── code-fix.md           # Fix command (delegates to code-fixer)
├── PLUGIN_ROADMAP.md              # Future plugin recommendations
└── README.md                      # This file

Adding More Plugins

To add a new plugin to this marketplace:

1. Create a new directory (e.g., deployment-helper/)
2. Add .claude-plugin/plugin.json with metadata
3. Add commands, skills, or hooks as needed
4. Register it in .claude-plugin/marketplace.json:

{
  "plugins": [
    {
      "name": "code-quality",
      "version": "2.0.0",
      "source": { "type": "path", "path": "./code-quality" }
    },
    {
      "name": "deployment-helper",
      "version": "1.0.0",
      "source": { "type": "path", "path": "./deployment-helper" }
    }
  ]
}

Tips

For Best Results

• •Run /generate-feature-docs when feature is complete (before merge request)
• •Run /code-review before creating pull requests
• •Address Critical issues first, then Important ones
• •Use the review to learn VILT patterns
• •Customize plugins as you discover team-specific patterns

Working with Generated Documentation

• •Technical Documentation and User Guide files are created in project root
• •Review and add screenshots to User Guide before sharing
• •Attach both files to merge requests for team context
• •Share User Guide with support team for training
• •Archive docs: mv *_Technical-Documentation.md docs/features/

Working with CODE_REVIEW.md and FIXES_APPLIED.md

• •CODE_REVIEW.md is created/overwritten each time you run /code-review
• •FIXES_APPLIED.md is created each time you run /code-fix
• •Add to .gitignore to avoid committing review files:

`` CODE_REVIEW.md FIXES_APPLIED.md *_Technical-Documentation.md *_User-Guide.md ``

• •Or commit them to track review history and fixes over time
• •Archive reviews: mv CODE_REVIEW.md reviews/review-2025-01-15.md
• •Attach CODE_REVIEW.md to merge requests for reviewer context
• •Use FIXES_APPLIED.md to document what was auto-fixed vs manually fixed

Common Customizations

• •Add project-specific translation patterns
• •Include custom validation rules
• •Add business logic checks
• •Integrate with your testing standards

Support

For issues or suggestions:

1. Check agents/vilt-reviewer.md to understand the review logic
2. Edit the agent file to customize review criteria and behavior
3. Edit commands/code-review.md to change how the command invokes the agent
4. Share improvements with the team via GitLab

Version History

Documentation Plugin

1.0.0 - Initial release

• •/generate-feature-docs command for automated feature documentation
• •Generates Technical Documentation for developers
• •Generates User Guide for support team
• •Analyzes git changes: routes, controllers, models, migrations, policies
• •Documents permissions, authorization rules, and access restrictions
• •Includes limitations and troubleshooting sections
• •Uses UK English throughout
• •Powered by feature-documenter agent

Code Quality Plugin

2.2.0 - Code duplication detection and trait extraction recommendations

• •Detects duplicate methods across multiple files
• •Recommends trait extraction for DRY principle violations
• •Actively searches for identical methods in Mail classes, Controllers, Services, Models
• •Provides complete trait implementation example in CODE_REVIEW.md
• •Flags when 2+ files have identical/similar method implementations
• •Priority: [IMPORTANT] - prevents maintenance burden and inconsistency
• •Example: Detects 6 mail classes with identical sanitizeCommentContent() method
• •Recommends creating trait in app/Traits/ directory
• •Addresses real code review findings from team

2.1.0 - Progress tracking and verification workflow

• •/code-fix now updates CODE_REVIEW.md with progress tracking
• •Fixed items are struck through with ✅ checkmarks
• •"Next Steps" checklist automatically updated as fixes applied
• •Timestamp added showing when fixes were last applied
• •Interactive prompt to re-run /code-review after fixes
• •Three verification options: "Yes" (run now), "No" (skip), "After tests" (workflow reminder)
• •CODE_REVIEW.md becomes a living document showing real-time progress
• •Enhanced "Actions Required Before Merge" checklist with specific file paths

2.0.0 - Renamed to code-quality (BREAKING CHANGE)

• •Plugin renamed from code-review to code-quality to better reflect complete solution
• •Now includes both review (/code-review) and fix (/code-fix) capabilities
• •Migration: Uninstall old plugin and install new one:

- /plugin uninstall code-review - /plugin install code-quality@resrequest

• •All features from 1.3.0 retained, only the plugin name changed

1.3.0 - Automated code fixes

• •New /code-fix command powered by code-fixer agent
• •Automatically applies fixes from CODE_REVIEW.md
• •Interactive: asks permission for each fix
• •Priority-based: fixes CRITICAL → IMPORTANT → SUGGESTION
• •Safe: never auto-commits changes
• •Generates FIXES_APPLIED.md summary
• •Filter options: --critical-only, --important-only, by file path

1.2.1 - Markdown file output

• •Reviews are now saved to CODE_REVIEW.md in project root
• •Terminal shows concise summary with file location
• •Detailed findings in persistent markdown file
• •Easy to share, attach to MRs, or track over time

1.2.0 - Agent-based architecture

• •Converted to specialized vilt-reviewer agent for enhanced expertise
• •Separate context window prevents cluttering main conversation
• •More detailed system prompts with comprehensive VILT patterns
• •Agent reusable across multiple ResRequest projects
• •Improved customization through agent configuration

1.1.0 - Enhanced review capabilities

• •Added debugging code detection (dd(), console.log(), etc.)
• •Added unnecessary comment detection for self-documenting code
• •Explicit branch-only scope (reviews committed + uncommitted changes)
• •Laravel coding standards integration
• •Support for base branch and file path arguments

1.0.0 - Initial release

• •VILT stack code review
• •Translation string detection
• •Inertia usage validation
• •Security and quality checks