zhongwei/gh-bejranonda-llm-autonomous-agent-plugin-for-claude
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:00:50 +08:00
commit c5931553a6
106 changed files with 49995 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

543
commands/analyze/explain.md Normal file
View File

@@ -0,0 +1,543 @@
---
name: analyze:explain
description: Explain and analyze task, event, or code without making modifications - read-only review
delegates-to: autonomous-agent:orchestrator
---
# Analyze-Explain Command
## Command: `/analyze:explain`
**Read-only analysis and explanation** - Reviews and explains tasks, events, code, or issues without making any modifications. Perfect for understanding what needs to be done before committing to changes.
**🔍 Pure Analysis Mode:**
- **Zero Modifications**: Absolutely no code changes, no fixes, no commits
- **Comprehensive Explanation**: Detailed breakdown of what, why, and how
- **Impact Analysis**: What would change if task were implemented
- **Risk Assessment**: Potential issues and concerns
- **Recommendation Generation**: Suggested approaches without implementation
- **Learning Integration**: Learns from analysis patterns
## How It Works
1. **Task Understanding**: Analyzes the request or code in detail
2. **Context Gathering**: Examines relevant code, files, and dependencies
3. **Impact Assessment**: Identifies what would be affected by changes
4. **Risk Analysis**: Evaluates potential problems and edge cases
5. **Approach Recommendation**: Suggests optimal implementation strategies
6. **Pattern Learning**: Stores analysis patterns for future reference
## Usage
### Basic Usage
```bash
# Explain a feature request
/analyze:explain "add user authentication with JWT"
# Explain existing code or issue
/analyze:explain "why is the login endpoint failing"
# Explain error or bug
/analyze:explain "investigate memory leak in data processing"
# Explain architectural decision
/analyze:explain "should we use microservices or monolith for this project"
```
### With Context
```bash
# Explain with specific file context
/analyze:explain "how does authentication work in auth/login.py"
# Explain with repository URL
/analyze:explain "analyze authentication approach in https://github.com/user/repo"
# Explain test failures
/analyze:explain "why are these 5 tests failing in test_auth.py"
# Explain performance issue
/analyze:explain "what's causing slow response times in API endpoints"
```
### Advanced Options
```bash
# Detailed technical explanation
/analyze:explain "explain JWT implementation" --detail-level technical
# High-level overview
/analyze:explain "explain authentication system" --detail-level overview
# Include code examples in explanation
/analyze:explain "how to implement caching" --include-examples
# Compare multiple approaches
/analyze:explain "Redis vs Memcached for caching" --compare-approaches
```
## Output Format
### Terminal Output (Concise Summary)
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔍 ANALYSIS COMPLETE - READ-ONLY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Task: "add user authentication with JWT"
Complexity: Medium | Estimated Time: 3-4 hours | Risk Level: Medium
Key Findings:
* No existing authentication system detected
* 8 endpoints would need protection
* JWT library not in dependencies
Critical Considerations:
1. Token storage strategy (localStorage vs httpOnly cookies)
2. Refresh token implementation required
3. Password hashing strategy needed
Recommended Approach:
1. Install python-jose and passlib
2. Implement token generation/validation
3. Add authentication middleware
📄 Full analysis: .claude/data/reports/explain-auth-jwt-2025-10-29.md
⏱ Analysis completed in 45 seconds
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Next Steps:
* Review full analysis report
* Use /dev:auto "add JWT auth" to implement
* Use /analyze:quality to validate after implementation
```
### Detailed Report (.claude/data/reports/)
```markdown
=======================================================
TASK ANALYSIS REPORT - READ-ONLY
=======================================================
Generated: 2025-10-29 16:30:00
Task: "add user authentication with JWT"
Status: ANALYSIS ONLY - NO MODIFICATIONS MADE
+- Task Understanding ---------------------------------+
| Request: Implement JWT-based authentication system |
| |
| Requirements Breakdown: |
| 1. User registration endpoint |
| 2. Login endpoint with JWT token generation |
| 3. Token validation middleware |
| 4. Token refresh mechanism |
| 5. Logout functionality (token invalidation) |
| 6. Protected route implementation |
| |
| Technical Components: |
| * JWT token generation and validation |
| * Password hashing (bcrypt/argon2) |
| * Token storage strategy |
| * Middleware for route protection |
| * Refresh token rotation |
+-------------------------------------------------------+
+- Current State Analysis -----------------------------+
| Project Type: FastAPI/Flask application |
| Current Auth: None detected |
| |
| Affected Files (would be modified): |
| * main.py - Add auth middleware |
| * models.py - Add User model |
| * routes/auth.py - New file for auth endpoints |
| * utils/security.py - New file for JWT/hashing |
| * requirements.txt - Add dependencies |
| |
| Protected Endpoints (would need auth): |
| * POST /api/users/profile |
| * GET /api/users/me |
| * PUT /api/users/update |
| * DELETE /api/users/delete |
| * GET /api/admin/* |
| * [3 more endpoints] |
+-------------------------------------------------------+
+- Implementation Impact ------------------------------+
| Estimated Changes: |
| * Files Created: 4 new files |
| * Files Modified: 6 existing files |
| * Lines Added: ~450-600 lines |
| * Dependencies: 3 new packages |
| |
| Breaking Changes: |
| * All protected endpoints require auth header |
| * Clients must implement token storage |
| * Login flow changes for existing users |
| |
| Database Changes: |
| * New 'users' table required |
| * New 'refresh_tokens' table required |
| * Migration scripts needed |
+-------------------------------------------------------+
+- Risk Assessment ------------------------------------+
| Security Risks: |
| * [HIGH] Token storage vulnerabilities |
| * [HIGH] Password hashing strength |
| * [MED] Token expiration strategy |
| * [MED] Refresh token rotation |
| * [LOW] CORS configuration for auth |
| |
| Technical Risks: |
| * [MED] Breaking existing API clients |
| * [MED] Token validation performance impact |
| * [LOW] Database migration complexity |
| |
| Operational Risks: |
| * [MED] User migration to new auth system |
| * [LOW] Monitoring and logging requirements |
+-------------------------------------------------------+
+- Recommended Approaches -----------------------------+
| Approach 1: Standard JWT (Recommended) |
| +- Pros: |
| | * Industry standard |
| | * Well-tested libraries available |
| | * Good documentation |
| | * Stateless authentication |
| +- Cons: |
| | * Token revocation complexity |
| | * Larger token size |
| +- Libraries: |
| | * python-jose[cryptography] |
| | * passlib[bcrypt] |
| | * python-multipart |
| +- Estimated Time: 3-4 hours |
| +- Complexity: Medium |
| |
| Approach 2: JWT + Redis for Token Blacklist |
| +- Pros: |
| | * Token revocation support |
| | * Better security |
| | * Session management |
| +- Cons: |
| | * Additional infrastructure (Redis) |
| | * More complex setup |
| | * Stateful authentication |
| +- Estimated Time: 5-6 hours |
| +- Complexity: Medium-High |
| |
| Approach 3: OAuth2 with JWT |
| +- Pros: |
| | * OAuth2 standard compliance |
| | * Third-party provider support |
| | * Flexible scope management |
| +- Cons: |
| | * More complex implementation |
| | * Requires additional setup |
| +- Estimated Time: 6-8 hours |
| +- Complexity: High |
+-------------------------------------------------------+
+- Implementation Steps (if you proceed) --------------+
| Phase 1: Setup & Dependencies (30 min) |
| 1. Install required packages |
| 2. Configure environment variables |
| 3. Set up database models |
| |
| Phase 2: Core Auth Logic (90 min) |
| 4. Implement password hashing utilities |
| 5. Create JWT token generation |
| 6. Implement token validation |
| 7. Add refresh token mechanism |
| |
| Phase 3: Endpoints (60 min) |
| 8. Create registration endpoint |
| 9. Create login endpoint |
| 10. Create token refresh endpoint |
| 11. Create logout endpoint |
| |
| Phase 4: Middleware & Protection (45 min) |
| 12. Implement authentication middleware |
| 13. Protect existing endpoints |
| 14. Add role-based access control (optional) |
| |
| Phase 5: Testing & Documentation (45 min) |
| 15. Write unit tests |
| 16. Write integration tests |
| 17. Update API documentation |
| 18. Add usage examples |
+-------------------------------------------------------+
+- Code Examples (Reference Only) ---------------------+
| Token Generation Example: |
| |
| ```python |
| from jose import jwt |
| from datetime import datetime, timedelta |
| |
| def create_access_token(data: dict): |
| to_encode = data.copy() |
| expire = datetime.utcnow() + timedelta(minutes=15)|
| to_encode.update({"exp": expire}) |
| return jwt.encode(to_encode, SECRET_KEY, ALGO) |
| ``` |
| |
| Middleware Example: |
| |
| ```python |
| from fastapi import Depends, HTTPException |
| |
| async def get_current_user(token: str = Depends(...)):|
| try: |
| payload = jwt.decode(token, SECRET_KEY, ALGO)|
| return payload.get("sub") |
| except JWTError: |
| raise HTTPException(401, "Invalid token") |
| ``` |
+-------------------------------------------------------+
+- Configuration Requirements -------------------------+
| Environment Variables Needed: |
| * SECRET_KEY - JWT signing key (strong random) |
| * ALGORITHM - "HS256" (default) or "RS256" |
| * ACCESS_TOKEN_EXPIRE_MINUTES - 15-30 recommended |
| * REFRESH_TOKEN_EXPIRE_DAYS - 7-30 recommended |
| |
| Database Schema: |
| * users table: id, username, email, password_hash |
| * refresh_tokens table: token, user_id, expires_at |
+-------------------------------------------------------+
+- Testing Strategy -----------------------------------+
| Unit Tests Required: |
| * Token generation with valid data |
| * Token validation with valid/invalid tokens |
| * Password hashing and verification |
| * Token expiration handling |
| |
| Integration Tests Required: |
| * User registration flow |
| * Login and token retrieval |
| * Protected endpoint access with valid token |
| * Protected endpoint rejection without token |
| * Token refresh flow |
| * Logout and token invalidation |
+-------------------------------------------------------+
+- Pattern Learning Insights --------------------------+
| Similar Tasks Found: 3 previous auth implementations |
| |
| Common Success Patterns: |
| * Using python-jose over PyJWT (92% success rate) |
| * Implementing refresh tokens from start (87%) |
| * Using httpOnly cookies for tokens (84%) |
| |
| Common Pitfalls to Avoid: |
| * Weak SECRET_KEY generation (found in 23% of cases) |
| * Missing token expiration (found in 18% of cases) |
| * No refresh token rotation (found in 31% of cases) |
| |
| Learned Optimizations: |
| * Cache token validation results (15% faster) |
| * Use background tasks for token cleanup |
| * Implement rate limiting on auth endpoints |
+-------------------------------------------------------+
+- Recommendations Summary ----------------------------+
| 1. [RECOMMENDED] Use Approach 1 (Standard JWT) |
| - Best balance of simplicity and security |
| - Well-documented and tested |
| - 3-4 hour implementation time |
| |
| 2. Add refresh token mechanism from start |
| - Prevents need for later refactoring |
| - Better user experience |
| |
| 3. Use httpOnly cookies instead of localStorage |
| - More secure against XSS attacks |
| - Industry best practice |
| |
| 4. Implement rate limiting on auth endpoints |
| - Prevents brute force attacks |
| - Add from the start |
| |
| 5. Write comprehensive tests |
| - Auth is security-critical |
| - 90%+ coverage recommended |
+-------------------------------------------------------+
=======================================================
NEXT STEPS
=======================================================
Ready to Implement?
* Use: /dev:auto "add JWT authentication with refresh tokens"
* Review: Read this report carefully first
* Prepare: Backup database before migration
Need More Analysis?
* Security review: /validate:security
* Architecture review: /analyze:project
* Compare with existing repos: /analyze:repository <url>
Questions or Concerns?
* Review pattern learning insights above
* Check similar implementations in patterns database
* Consult team for security-critical decisions
=======================================================
Analysis Time: 45 seconds
Pattern Matches: 3 similar tasks
Confidence Level: High (92%)
Recommendation Strength: Strong
NO MODIFICATIONS WERE MADE TO ANY FILES
This is a read-only analysis report.
```
## Integration with Learning System
The `/analyze:explain` command integrates with pattern learning:
**Learning from Analysis**:
- Common task patterns and requirements
- Effective explanation structures
- Risk assessment accuracy
- Recommendation quality
- User follow-through rates
**Pattern Storage**:
```json
{
"explain_patterns": {
"task_type": "authentication_jwt",
"analysis_approach": {
"breakdown_depth": "detailed",
"risk_assessment": "comprehensive",
"approaches_compared": 3,
"code_examples_included": true
},
"outcome": {
"user_implemented": true,
"implementation_success": true,
"analysis_accuracy": 0.95,
"time_estimate_accuracy": 0.88
},
"reuse_count": 8,
"effectiveness_score": 0.92
}
}
```
## Agent Delegation
`/analyze:explain` delegates to:
- **orchestrator**: Main analysis coordinator
- **code-analyzer**: Code structure and impact analysis
- **security-auditor**: Security risk assessment
- **pattern-learning**: Similar task pattern matching
## Skills Integration
Auto-loads relevant skills:
- **code-analysis**: For code understanding
- **pattern-learning**: For similar task identification
- **security-patterns**: For security considerations
- **documentation-best-practices**: For clear explanations
## Use Cases
### Before Implementation
```bash
# Understand requirements before coding
/analyze:explain "implement real-time notifications"
# Review the analysis
# Then implement: /dev:auto "implement real-time notifications"
```
### Understanding Existing Code
```bash
# Understand how something works
/analyze:explain "how does the caching system work in cache.py"
```
### Troubleshooting
```bash
# Understand what's wrong before fixing
/analyze:explain "why is the API returning 500 errors"
# Review the analysis
# Then fix: /dev:auto "fix API 500 errors"
```
### Decision Making
```bash
# Compare approaches
/analyze:explain "should we use GraphQL or REST for the new API"
```
### Learning
```bash
# Learn from external repositories
/analyze:explain "how does authentication work in https://github.com/fastapi/fastapi"
```
## Best Practices
### Good Explain Requests
```bash
# Specific and focused
/analyze:explain "explain JWT token refresh mechanism in auth/token.py"
# Clear context provided
/analyze:explain "why are tests failing after adding authentication"
# Decision-oriented
/analyze:explain "compare WebSocket vs Server-Sent Events for real-time updates"
```
### Poor Explain Requests
```bash
# Too vague
/analyze:explain "explain the code"
# Too broad
/analyze:explain "explain everything about the project"
# Not analysis-focused
/analyze:explain "fix all bugs" # Use /dev:auto instead
```
## Output Options
### Detail Levels
- **overview**: High-level summary (default)
- **technical**: Detailed technical analysis
- **comparison**: Compare multiple approaches
- **security**: Focus on security considerations
### Include Examples
```bash
# With code examples
/analyze:explain "JWT implementation" --include-examples
# Without code examples (faster)
/analyze:explain "JWT implementation" --no-examples
```
## Performance Metrics
- **Analysis Time**: 30-90 seconds typically
- **Accuracy**: 90-95% for requirement understanding
- **Time Estimates**: ±20% accuracy
- **Risk Identification**: 85-90% of critical risks identified
---
**Version**: 1.0.0
**Integration**: Uses orchestrator, code-analyzer, security-auditor agents
**Skills**: code-analysis, pattern-learning, security-patterns
**Platform**: Cross-platform (Windows, Linux, Mac)
**Learning**: Full integration with pattern learning system
**Mode**: READ-ONLY - No modifications ever made