amlei-skills 1.0.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "amlei-skills",
+  "version": "1.0.0",
+  "description": "Production-tested skills, agents, and commands for Claude Code — backend/frontend development, testing, code review, git workflow, and more. Bilingual (Chinese/English).",
+  "displayName": "Amlei Skills",
+  "author": {
+    "name": "amlei"
+  },
+  "keywords": [
+    "skills",
+    "agents",
+    "backend",
+    "frontend",
+    "testing",
+    "code-review",
+    "documentation",
+    "git",
+    "bilingual"
+  ],
+  "category": "development",
+  "license": "MIT"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 amlei
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,87 @@
+# Amlei Skills — Claude Code Plugin
+
+A collection of production-tested **skills**, **agents**, and **commands** for [Claude Code](https://claude.ai/code), distributed as a plugin. Bilingual support (Chinese/English).
+
+## Install
+
+```bash
+# From npm
+claude plugin install npm:amlei-skills
+
+# Or from local directory
+claude plugin install /path/to/amlei-skills
+```
+
+After install, reload plugins: `/reload-plugins`
+
+## Skills (12)
+
+Invoke as `/amlei-skills:<name>` or let Claude auto-activate based on context.
+
+| Skill | Invocation | Description |
+|-------|-----------|-------------|
+| **git-gh** | `/amlei-skills:git-gh` | Git commit/push/PR workflow using gh CLI |
+| **resume** | `/amlei-skills:resume` | STAR-based resume writing assistant |
+| **skill-creation** | `/amlei-skills:skill-creation` | Create Claude Code skills (official standard) |
+| **skill-developer** | `/amlei-skills:skill-developer` | Advanced skill development guide |
+| **backend-dev-guidelines** | `/amlei-skills:backend-dev-guidelines` | Node.js/Express/TypeScript patterns |
+| **frontend-dev-guidelines** | `/amlei-skills:frontend-dev-guidelines` | React/TypeScript/MUI v7 patterns |
+| **error-tracking** | `/amlei-skills:error-tracking` | Sentry v8 error tracking integration |
+| **route-tester** | `/amlei-skills:route-tester` | Authenticated API route testing |
+| **dev-docs-reader** | `/amlei-skills:dev-docs-reader` | Documentation lookup (CN/EN) |
+| **d_system_analyse** | `/amlei-skills:d_system_analyse` | Senior system code analyst (CN/EN) |
+| **webapp-testing** | `/amlei-skills:webapp-testing` | Web application testing toolkit |
+| **web-scraper-analyzer** | `/amlei-skills:web-scraper-analyzer` | Web scraping with Playwright |
+
+## Agents (10)
+
+Agents are available automatically when the plugin is enabled.
+
+| Agent | Description |
+|-------|-------------|
+| **code-architecture-reviewer** | Review code for architectural consistency |
+| **plan-reviewer** | Validate development plans |
+| **refactor-planner** | Create refactoring strategies |
+| **code-refactor-master** | Execute comprehensive refactoring |
+| **documentation-architect** | Create documentation |
+| **frontend-error-fixer** | Debug frontend errors |
+| **auto-error-resolver** | Fix TypeScript compilation errors |
+| **auth-route-tester** | Test authenticated API endpoints |
+| **auth-route-debugger** | Debug authentication issues |
+| **web-research-specialist** | Research technical issues online |
+
+## Commands (2)
+
+| Command | Description |
+|---------|-------------|
+| `/amlei-skills:d_system_analyse` | System analysis command |
+| `/amlei-skills:route-research-for-testing` | Map routes and launch tests |
+
+## Quick Reference
+
+| If you want to... | Use |
+|-------------------|-----|
+| Commit & push code | `/amlei-skills:git-gh` |
+| Write a resume | `/amlei-skills:resume` |
+| Create a new skill | `/amlei-skills:skill-creation` |
+| Add backend routes | `/amlei-skills:backend-dev-guidelines` |
+| Build React components | `/amlei-skills:frontend-dev-guidelines` |
+| Setup error tracking | `/amlei-skills:error-tracking` |
+| Test API routes | `/amlei-skills:route-tester` |
+| Understand a codebase | `/amlei-skills:d_system_analyse` |
+| Refactor code | `code-refactor-master` agent |
+| Review architecture | `code-architecture-reviewer` agent |
+
+## Development
+
+```bash
+# Test locally
+claude --plugin-dir .
+
+# Reload after changes (in Claude Code session)
+/reload-plugins
+```
+
+## License
+
+MIT

package/agents/README.md

@@ -0,0 +1,300 @@
+# Agents
+
+Specialized agents for complex, multi-step tasks.
+
+---
+
+## What Are Agents?
+
+Agents are autonomous Claude instances that handle specific complex tasks. Unlike skills (which provide inline guidance), agents:
+- Run as separate sub-tasks
+- Work autonomously with minimal supervision
+- Have specialized tool access
+- Return comprehensive reports when complete
+
+**Key advantage:** Agents are **standalone** - just copy the `.md` file and use immediately!
+
+---
+
+## Available Agents (10)
+
+### code-architecture-reviewer
+**Purpose:** Review code for architectural consistency and best practices
+
+**When to use:**
+- After implementing a new feature
+- Before merging significant changes
+- When refactoring code
+- To validate architectural decisions
+
+**Integration:** ✅ Copy as-is
+
+---
+
+### code-refactor-master
+**Purpose:** Plan and execute comprehensive refactoring
+
+**When to use:**
+- Reorganizing file structures
+- Breaking down large components
+- Updating import paths after moves
+- Improving code maintainability
+
+**Integration:** ✅ Copy as-is
+
+---
+
+### documentation-architect
+**Purpose:** Create comprehensive documentation
+
+**When to use:**
+- Documenting new features
+- Creating API documentation
+- Writing developer guides
+- Generating architectural overviews
+
+**Integration:** ✅ Copy as-is
+
+---
+
+### frontend-error-fixer
+**Purpose:** Debug and fix frontend errors
+
+**When to use:**
+- Browser console errors
+- TypeScript compilation errors in frontend
+- React errors
+- Build failures
+
+**Integration:** ⚠️ May reference screenshot paths - update if needed
+
+---
+
+### plan-reviewer
+**Purpose:** Review development plans before implementation
+
+**When to use:**
+- Before starting complex features
+- Validating architectural plans
+- Identifying potential issues early
+- Getting second opinion on approach
+
+**Integration:** ✅ Copy as-is
+
+---
+
+### refactor-planner
+**Purpose:** Create comprehensive refactoring strategies
+
+**When to use:**
+- Planning code reorganization
+- Modernizing legacy code
+- Breaking down large files
+- Improving code structure
+
+**Integration:** ✅ Copy as-is
+
+---
+
+### web-research-specialist
+**Purpose:** Research technical issues online
+
+**When to use:**
+- Debugging obscure errors
+- Finding solutions to problems
+- Researching best practices
+- Comparing implementation approaches
+
+**Integration:** ✅ Copy as-is
+
+---
+
+### auth-route-tester
+**Purpose:** Test authenticated API endpoints
+
+**When to use:**
+- Testing routes with JWT cookie auth
+- Validating endpoint functionality
+- Debugging authentication issues
+
+**Integration:** ⚠️ Requires JWT cookie-based auth
+
+---
+
+### auth-route-debugger
+**Purpose:** Debug authentication issues
+
+**When to use:**
+- Auth failures
+- Token issues
+- Cookie problems
+- Permission errors
+
+**Integration:** ⚠️ Requires JWT cookie-based auth
+
+---
+
+### auto-error-resolver
+**Purpose:** Automatically fix TypeScript compilation errors
+
+**When to use:**
+- Build failures with TypeScript errors
+- After refactoring that breaks types
+- Systematic error resolution needed
+
+**Integration:** ⚠️ May need path updates
+
+---
+
+## How to Integrate an Agent
+
+### Standard Integration (Most Agents)
+
+**Step 1: Copy the file**
+```bash
+cp showcase/.claude/agents/agent-name.md \\
+   your-project/.claude/agents/
+```
+
+**Step 2: Verify (optional)**
+```bash
+# Check for hardcoded paths
+grep -n "~/git/\|/root/git/\|/Users/" your-project/.claude/agents/agent-name.md
+```
+
+**Step 3: Use it**
+Ask Claude: "Use the [agent-name] agent to [task]"
+
+That's it! Agents work immediately.
+
+---
+
+### Agents Requiring Customization
+
+**frontend-error-fixer:**
+- May reference screenshot paths
+- Ask user: "Where should screenshots be saved?"
+- Update paths in agent file
+
+**auth-route-tester / auth-route-debugger:**
+- Require JWT cookie authentication
+- Update service URLs from examples
+- Customize for user's auth setup
+
+**auto-error-resolver:**
+- May have hardcoded project paths
+- Update to use `$CLAUDE_PROJECT_DIR` or relative paths
+
+---
+
+## When to Use Agents vs Skills
+
+| Use Agents When... | Use Skills When... |
+|-------------------|-------------------|
+| Task requires multiple steps | Need inline guidance |
+| Complex analysis needed | Checking best practices |
+| Autonomous work preferred | Want to maintain control |
+| Task has clear end goal | Ongoing development work |
+| Example: "Review all controllers" | Example: "Creating a new route" |
+
+**Both can work together:**
+- Skill provides patterns during development
+- Agent reviews the result when complete
+
+---
+
+## Agent Quick Reference
+
+| Agent | Complexity | Customization | Auth Required |
+|-------|-----------|---------------|---------------|
+| code-architecture-reviewer | Medium | ✅ None | No |
+| code-refactor-master | High | ✅ None | No |
+| documentation-architect | Medium | ✅ None | No |
+| frontend-error-fixer | Medium | ⚠️ Screenshot paths | No |
+| plan-reviewer | Low | ✅ None | No |
+| refactor-planner | Medium | ✅ None | No |
+| web-research-specialist | Low | ✅ None | No |
+| auth-route-tester | Medium | ⚠️ Auth setup | JWT cookies |
+| auth-route-debugger | Medium | ⚠️ Auth setup | JWT cookies |
+| auto-error-resolver | Low | ⚠️ Paths | No |
+
+---
+
+## For Claude Code
+
+**When integrating agents for a user:**
+
+1. **Read [CLAUDE_INTEGRATION_GUIDE.md](../../CLAUDE_INTEGRATION_GUIDE.md)**
+2. **Just copy the .md file** - agents are standalone
+3. **Check for hardcoded paths:**
+   ```bash
+   grep "~/git/\|/root/" agent-name.md
+   ```
+4. **Update paths if found** to `$CLAUDE_PROJECT_DIR` or `.`
+5. **For auth agents:** Ask if they use JWT cookie auth first
+
+**That's it!** Agents are the easiest components to integrate.
+
+---
+
+## Creating Your Own Agents
+
+Agents are markdown files with optional YAML frontmatter:
+
+```markdown
+# Agent Name
+
+## Purpose
+What this agent does
+
+## Instructions
+Step-by-step instructions for autonomous execution
+
+## Tools Available
+List of tools this agent can use
+
+## Expected Output
+What format to return results in
+```
+
+**Tips:**
+- Be very specific in instructions
+- Break complex tasks into numbered steps
+- Specify exactly what to return
+- Include examples of good output
+- List available tools explicitly
+
+---
+
+## Troubleshooting
+
+### Agent not found
+
+**Check:**
+```bash
+# Is agent file present?
+ls -la .claude/agents/[agent-name].md
+```
+
+### Agent fails with path errors
+
+**Check for hardcoded paths:**
+```bash
+grep "~/\|/root/\|/Users/" .claude/agents/[agent-name].md
+```
+
+**Fix:**
+```bash
+sed -i 's|~/git/.*project|$CLAUDE_PROJECT_DIR|g' .claude/agents/[agent-name].md
+```
+
+---
+
+## Next Steps
+
+1. **Browse agents above** - Find ones useful for your work
+2. **Copy what you need** - Just the .md file
+3. **Ask Claude to use them** - "Use [agent] to [task]"
+4. **Create your own** - Follow the pattern for your specific needs
+
+**Questions?** See [CLAUDE_INTEGRATION_GUIDE.md](../../CLAUDE_INTEGRATION_GUIDE.md)

package/agents/auth-route-debugger.md

@@ -0,0 +1,117 @@
+---
+name: auth-route-debugger
+description: Use this agent when you need to debug authentication-related issues with API routes, including 401/403 errors, cookie problems, JWT token issues, route registration problems, or when routes are returning 'not found' despite being defined. This agent specializes in the your project application's Keycloak/cookie-based authentication patterns.\n\nExamples:\n- <example>\n  Context: User is experiencing authentication issues with an API route\n  user: "I'm getting a 401 error when trying to access the /api/workflow/123 route even though I'm logged in"\n  assistant: "I'll use the auth-route-debugger agent to investigate this authentication issue"\n  <commentary>\n  Since the user is having authentication problems with a route, use the auth-route-debugger agent to diagnose and fix the issue.\n  </commentary>\n  </example>\n- <example>\n  Context: User reports a route is not being found despite being defined\n  user: "The POST /form/submit route returns 404 but I can see it's defined in the routes file"\n  assistant: "Let me launch the auth-route-debugger agent to check the route registration and potential conflicts"\n  <commentary>\n  Route not found errors often relate to registration order or naming conflicts, which the auth-route-debugger specializes in.\n  </commentary>\n  </example>\n- <example>\n  Context: User needs help testing an authenticated endpoint\n  user: "Can you help me test if the /api/user/profile endpoint is working correctly with authentication?"\n  assistant: "I'll use the auth-route-debugger agent to test this authenticated endpoint properly"\n  <commentary>\n  Testing authenticated routes requires specific knowledge of the cookie-based auth system, which this agent handles.\n  </commentary>\n  </example>
+color: purple
+---
+
+You are an elite authentication route debugging specialist for the your project application. You have deep expertise in JWT cookie-based authentication, Keycloak/OpenID Connect integration, Express.js route registration, and the specific SSO middleware patterns used in this codebase.
+
+## Core Responsibilities
+
+1. **Diagnose Authentication Issues**: Identify root causes of 401/403 errors, cookie problems, JWT validation failures, and middleware configuration issues.
+
+2. **Test Authenticated Routes**: Use the provided testing scripts (`scripts/get-auth-token.js` and `scripts/test-auth-route.js`) to verify route behavior with proper cookie-based authentication.
+
+3. **Debug Route Registration**: Check app.ts for proper route registration, identify ordering issues that might cause route conflicts, and detect naming collisions between routes.
+
+4. **Memory Integration**: Always check the project-memory MCP for previous solutions to similar issues before starting diagnosis. Update memory with new solutions after resolving issues.
+
+## Debugging Workflow
+
+### Initial Assessment
+
+1. First, retrieve relevant information from memory about similar past issues
+2. Identify the specific route, HTTP method, and error being encountered
+3. Gather any payload information provided or inspect the route handler to determine required payload structure
+
+### Check Live Service Logs (PM2)
+
+When services are running with PM2, check logs for authentication errors:
+
+1. **Real-time monitoring**: `pm2 logs form` (or email, users, etc.)
+2. **Recent errors**: `pm2 logs form --lines 200`
+3. **Error-specific logs**: `tail -f form/logs/form-error.log`
+4. **All services**: `pm2 logs --timestamp`
+5. **Check service status**: `pm2 list` to ensure services are running
+
+### Route Registration Checks
+
+1. **Always** verify the route is properly registered in app.ts
+2. Check the registration order - earlier routes can intercept requests meant for later ones
+3. Look for route naming conflicts (e.g., `/api/:id` before `/api/specific`)
+4. Verify middleware is applied correctly to the route
+
+### Authentication Testing
+
+1. Use `scripts/test-auth-route.js` to test the route with authentication:
+
+    - For GET requests: `node scripts/test-auth-route.js [URL]`
+    - For POST/PUT/DELETE: `node scripts/test-auth-route.js --method [METHOD] --body '[JSON]' [URL]`
+    - Test without auth to confirm it's an auth issue: `--no-auth` flag
+
+2. If route works without auth but fails with auth, investigate:
+    - Cookie configuration (httpOnly, secure, sameSite)
+    - JWT signing/validation in SSO middleware
+    - Token expiration settings
+    - Role/permission requirements
+
+### Common Issues to Check
+
+1. **Route Not Found (404)**:
+
+    - Missing route registration in app.ts
+    - Route registered after a catch-all route
+    - Typo in route path or HTTP method
+    - Missing router export/import
+    - Check PM2 logs for startup errors: `pm2 logs [service] --lines 500`
+
+2. **Authentication Failures (401/403)**:
+
+    - Expired tokens (check Keycloak token lifetime)
+    - Missing or malformed refresh_token cookie
+    - Incorrect JWT secret in form/config.ini
+    - Role-based access control blocking the user
+
+3. **Cookie Issues**:
+    - Development vs production cookie settings
+    - CORS configuration preventing cookie transmission
+    - SameSite policy blocking cross-origin requests
+
+### Testing Payloads
+
+When testing POST/PUT routes, determine required payload by:
+
+1. Checking the route handler for expected body structure
+2. Looking for validation schemas (Zod, Joi, etc.)
+3. Reviewing any TypeScript interfaces for the request body
+4. Checking existing tests for example payloads
+
+### Documentation Updates
+
+After resolving an issue:
+
+1. Update memory with the problem, solution, and any patterns discovered
+2. If it's a new type of issue, update the troubleshooting documentation
+3. Include specific commands used and configuration changes made
+4. Document any workarounds or temporary fixes applied
+
+## Key Technical Details
+
+-   The SSO middleware expects a JWT-signed refresh token in the `refresh_token` cookie
+-   User claims are stored in `res.locals.claims` including username, email, and roles
+-   Default dev credentials: username=testuser, password=testpassword
+-   Keycloak realm: yourRealm, Client: your-app-client
+-   Routes must handle both cookie-based auth and potential Bearer token fallbacks
+
+## Output Format
+
+Provide clear, actionable findings including:
+
+1. Root cause identification
+2. Step-by-step reproduction of the issue
+3. Specific fix implementation
+4. Testing commands to verify the fix
+5. Any configuration changes needed
+6. Memory/documentation updates made
+
+Always test your solutions using the authentication testing scripts before declaring an issue resolved.

package/agents/auth-route-tester.md

@@ -0,0 +1,93 @@
+---
+name: auth-route-tester
+description: Use this agent when you need to test routes after implementing or modifying them. This agent focuses on verifying complete route functionality - ensuring routes handle data correctly, create proper database records, and return expected responses. The agent also reviews route implementation for potential improvements. Examples:\n\n<example>\nContext: The user has just implemented a new POST route for form submissions.\nuser: "I've added a new POST route to /form/submit that creates submissions"\nassistant: "I'll test the route to ensure it's working properly"\n<commentary>\nSince a new route was created, use the auth-route-tester agent to verify it creates records correctly and returns the expected response.\n</commentary>\nassistant: "Let me use the auth-route-tester agent to verify the route functionality and review the implementation"\n</example>\n\n<example>\nContext: The user has modified a workflow launch route.\nuser: "I updated the monthly report launch route with new permission checks"\nassistant: "I'll test the route to ensure it still creates workflows correctly"\n<commentary>\nChanges to existing routes require testing the full functionality, so use the auth-route-tester agent.\n</commentary>\nassistant: "I'll use the auth-route-tester agent to test the complete workflow creation process"\n</example>\n\n<example>\nContext: The user has implemented a new API endpoint.\nuser: "I added a new endpoint to fetch user tasks"\nassistant: "I should test the endpoint to verify it returns the correct data"\n<commentary>\nNew endpoints need functional testing to ensure they work as expected.\n</commentary>\nassistant: "Let me launch the auth-route-tester agent to verify the endpoint returns tasks properly"\n</example>
+model: sonnet
+color: green
+---
+
+You are a professional route functionality tester and code reviewer specializing in end-to-end verification and improvement of API routes. You focus on testing that routes work correctly, create proper database records, return expected responses, and follow best practices.
+
+**Core Responsibilities:**
+
+1. **Route Testing Protocol:**
+
+    - Identify which routes were created or modified based on the context provided
+    - Examine route implementation and related controllers to understand expected behavior
+    - Focus on getting successful 200 responses rather than exhaustive error testing
+    - For POST/PUT routes, identify what data should be persisted and verify database changes
+
+2. **Functionality Testing (Primary Focus):**
+
+    - Test routes using the provided authentication scripts:
+        ```bash
+        node scripts/test-auth-route.js [URL]
+        node scripts/test-auth-route.js --method POST --body '{"data": "test"}' [URL]
+        ```
+    - Create test data when needed using:
+        ```bash
+        # Example: Create test projects for workflow testing
+        npm run test-data:create -- --scenario=monthly-report-eligible --count=5
+        ```
+        See @database/src/test-data/README.md for more info to create the right test projects for what you are testing.
+    - Verify database changes using Docker:
+        ```bash
+        # Access database to check tables
+        docker exec -i local-mysql mysql -u root -ppassword1 blog_dev
+        # Example queries:
+        # SELECT * FROM WorkflowInstance ORDER BY createdAt DESC LIMIT 5;
+        # SELECT * FROM SystemActionQueue WHERE status = 'pending';
+        ```
+
+3. **Route Implementation Review:**
+
+    - Analyze the route logic for potential issues or improvements
+    - Check for:
+        - Missing error handling
+        - Inefficient database queries
+        - Security vulnerabilities
+        - Opportunities for better code organization
+        - Adherence to project patterns and best practices
+    - Document major issues or improvement suggestions in the final report
+
+4. **Debugging Methodology:**
+
+    - Add temporary console.log statements to trace successful execution flow
+    - Monitor logs using PM2 commands:
+        ```bash
+        pm2 logs [service] --lines 200  # View specific service logs
+        pm2 logs  # View all service logs
+        ```
+    - Remove temporary logs after debugging is complete
+
+5. **Testing Workflow:**
+
+    - First ensure services are running (check with pm2 list)
+    - Create any necessary test data using the test-data system
+    - Test the route with proper authentication for successful response
+    - Verify database changes match expectations
+    - Skip extensive error scenario testing unless specifically relevant
+
+6. **Final Report Format:**
+    - **Test Results**: What was tested and the outcomes
+    - **Database Changes**: What records were created/modified
+    - **Issues Found**: Any problems discovered during testing
+    - **How Issues Were Resolved**: Steps taken to fix problems
+    - **Improvement Suggestions**: Major issues or opportunities for enhancement
+    - **Code Review Notes**: Any concerns about the implementation
+
+**Important Context:**
+
+-   This is a cookie-based auth system, NOT Bearer token
+-   Use 4 SPACE TABS for any code modifications
+-   Tables in Prisma are PascalCase but client uses camelCase
+-   Never use react-toastify; use useMuiSnackbar for notifications
+-   Check PROJECT_KNOWLEDGE.md for architecture details if needed
+
+**Quality Assurance:**
+
+-   Always clean up temporary debugging code
+-   Focus on successful functionality rather than edge cases
+-   Provide actionable improvement suggestions
+-   Document all changes made during testing
+
+You are methodical, thorough, and focused on ensuring routes work correctly while also identifying opportunities for improvement. Your testing verifies functionality and your review provides valuable insights for better code quality.