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

671
commands/analyze/dependencies.md Normal file
View File

@@ -0,0 +1,671 @@
---
name: analyze:dependencies
description: Scan dependencies for CVE vulnerabilities across 11 package managers with fix recommendations
delegates-to: autonomous-agent:orchestrator
---
# Dependency Vulnerability Scanner
Comprehensive dependency vulnerability scanning across 11 package managers and ecosystems, with CVE database integration and automated fix recommendations.
## Usage
```bash
/analyze:dependencies [PATH] [OPTIONS]
```
**Examples**:
```bash
/analyze:dependencies # Scan current project
/analyze:dependencies backend/ # Scan specific directory
/analyze:dependencies --critical-only # Show only critical vulnerabilities
/analyze:dependencies --with-fixes # Include upgrade recommendations
```
## Supported Ecosystems
### Python (pip, pipenv, poetry)
**Tools**: pip-audit, safety
**Manifests**: requirements.txt, Pipfile, pyproject.toml, poetry.lock
### JavaScript/Node.js (npm, yarn, pnpm)
**Tools**: npm audit, yarn audit, pnpm audit
**Manifests**: package.json, package-lock.json, yarn.lock, pnpm-lock.yaml
### Ruby (bundler)
**Tools**: bundle-audit
**Manifests**: Gemfile, Gemfile.lock
### PHP (composer)
**Tools**: local-php-security-checker
**Manifests**: composer.json, composer.lock
### Go (go modules)
**Tools**: govulncheck
**Manifests**: go.mod, go.sum
### Rust (cargo)
**Tools**: cargo-audit
**Manifests**: Cargo.toml, Cargo.lock
### Java (maven, gradle)
**Tools**: dependency-check
**Manifests**: pom.xml, build.gradle, build.gradle.kts
### .NET (nuget)
**Tools**: dotnet list package --vulnerable
**Manifests**: packages.config, *.csproj
## How It Works
### 1. Ecosystem Detection
Automatically detects package managers:
```
Detecting Ecosystems...
✅ Python (requirements.txt)
✅ JavaScript (package.json, yarn.lock)
✅ Go (go.mod)
```
### 2. Vulnerability Scanning
Runs appropriate scanners for each ecosystem:
```
Scanning Dependencies...
[████████████] Python (pip-audit) - 2.3s
[████████████] npm (npm audit) - 4.1s
[████████████] Go (govulncheck) - 1.8s
Results:
✅ Python: 5 vulnerabilities (2 critical)
✅ npm: 12 vulnerabilities (0 critical)
✅ Go: 0 vulnerabilities
```
### 3. Result Aggregation
Deduplicates and synthesizes results:
```
Aggregating Results...
- Total Vulnerabilities: 15 unique
- Duplicates Removed: 2
- Vulnerable Dependencies: 12/187
```
### 4. Risk Assessment
```
Risk Score (0-100) =
Critical × 25 +
High × 15 +
Medium × 8 +
Low × 3 +
Info × 1
Example:
- Critical: 2 -> 50 points
- High: 3 -> 45 points
- Medium: 7 -> 56 points
- Low: 3 -> 9 points
---
-----------------------
Total: 160 (capped at 100)
Risk Score: 100/100 (EXTREME)
```
**Risk Levels**:
- 70-100: Extreme/High Risk
- 40-69: Medium Risk
- 0-39: Low Risk
## Output Format
### Terminal Output (Tier 1: Concise Summary)
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
DEPENDENCY VULNERABILITY SCAN COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎯 Risk Score: 78/100 (HIGH RISK)
📊 Overview
Total Vulnerabilities: 15
Vulnerable Dependencies: 12/187 (6.4%)
Ecosystems: Python, npm, Go
🚨 Vulnerabilities by Severity
🔴 Critical: 2
🟠 High: 3
🟡 Medium: 7
🔵 Low: 3
⚪ Info: 0
📦 By Ecosystem
Python: 5 vulnerabilities
npm: 10 vulnerabilities
Go: 0 vulnerabilities
[WARN]️ Top 3 Vulnerable Packages
1. requests (Python) - 2 vulnerabilities
2. axios (npm) - 3 vulnerabilities
3. lodash (npm) - 2 vulnerabilities
🔴 Critical Vulnerabilities (2)
1. CVE-2023-12345 - requests 2.25.1
SQL injection vulnerability
Fix: Upgrade to 2.31.0+
2. CVE-2023-67890 - axios 0.21.1
Server-side request forgery
Fix: Upgrade to 1.6.0+
📄 Detailed Report: .data/reports/dependency-scan-2025-01-15.md
⏱️ Scan completed in 8.2s
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
### File Report (Tier 2: Comprehensive)
Saved to `.data/reports/dependency-scan-{DATE}.md`:
```markdown
# Dependency Vulnerability Scan Report
**Generated**: 2025-01-15 16:45:23
**Project**: /project
**Risk Score**: 78/100 (HIGH RISK)
---
## Executive Summary
**Total Vulnerabilities**: 15 unique
**Vulnerable Dependencies**: 12 out of 187 total (6.4%)
**Ecosystems Scanned**: Python, npm, Go
**Scan Duration**: 8.2s
**Risk Assessment**: HIGH RISK
- Immediate action required for 2 critical vulnerabilities
- 3 high-severity issues should be addressed soon
- 7 medium-severity issues for next sprint
- 3 low-severity issues can be deferred
---
## Vulnerabilities by Severity
| Severity | Count | Percentage |
|----------|-------|-----------|
| 🔴 Critical | 2 | 13.3% |
| 🟠 High | 3 | 20.0% |
| 🟡 Medium | 7 | 46.7% |
| 🔵 Low | 3 | 20.0% |
| ⚪ Info | 0 | 0.0% |
---
## Vulnerabilities by Ecosystem
### Python (5 vulnerabilities)
- **Critical**: 1
- **High**: 1
- **Medium**: 2
- **Low**: 1
### npm (10 vulnerabilities)
- **Critical**: 1
- **High**: 2
- **Medium**: 5
- **Low**: 2
### Go (0 vulnerabilities)
- No vulnerabilities detected
---
## Top 10 Vulnerable Packages
| Package | Ecosystem | Vulnerabilities | Severity |
|---------|-----------|----------------|----------|
| axios | npm | 3 | 1 Critical, 2 Medium |
| requests | Python | 2 | 1 Critical, 1 High |
| lodash | npm | 2 | 2 Medium |
| urllib3 | Python | 2 | 1 High, 1 Low |
| ws | npm | 1 | 1 High |
| express | npm | 1 | 1 Medium |
| jinja2 | Python | 1 | 1 Medium |
| moment | npm | 1 | 1 Low |
| pyyaml | Python | 1 | 1 Low |
| react-dom | npm | 1 | 1 Medium |
---
## Critical Vulnerabilities (IMMEDIATE ACTION REQUIRED)
### CVE-2023-12345: SQL Injection in requests
**Package**: requests (Python)
**Installed Version**: 2.25.1
**Severity**: 🔴 CRITICAL
**CVSS Score**: 9.8
**Description**:
SQL injection vulnerability in the `requests` library allows remote attackers to execute arbitrary SQL commands via crafted HTTP requests.
**Impact**:
- Database compromise
- Data exfiltration
- Unauthorized access
**CWE**: CWE-89 (SQL Injection)
**Fixed Versions**: 2.31.0, 2.32.0+
**Remediation**:
```bash
# Python (pip)
pip install --upgrade requests>=2.31.0
# Python (poetry)
poetry update requests
```
**References**:
- https://nvd.nist.gov/vuln/detail/CVE-2023-12345
- https://github.com/psf/requests/security/advisories/GHSA-xxxx
---
### CVE-2023-67890: SSRF in axios
**Package**: axios (npm)
**Installed Version**: 0.21.1
**Severity**: 🔴 CRITICAL
**CVSS Score**: 9.1
**Description**:
Server-side request forgery (SSRF) vulnerability allows attackers to make the server perform requests to arbitrary destinations.
**Impact**:
- Internal network scanning
- Access to internal services
- Data exfiltration from internal endpoints
**CWE**: CWE-918 (SSRF)
**Fixed Versions**: 1.6.0+
**Remediation**:
```bash
# npm
npm install axios@latest
# yarn
yarn upgrade axios@latest
```
**References**:
- https://nvd.nist.gov/vuln/detail/CVE-2023-67890
- https://github.com/axios/axios/security/advisories/GHSA-yyyy
---
## High Severity Vulnerabilities
### CVE-2023-11111: XSS in urllib3
**Package**: urllib3 (Python)
**Installed Version**: 1.26.5
**Severity**: 🟠 HIGH
**CVSS Score**: 7.5
**Description**:
Cross-site scripting vulnerability in URL parsing logic.
**Fixed Versions**: 1.26.18+, 2.0.7+
**Remediation**:
```bash
pip install --upgrade urllib3>=1.26.18
```
---
### CVE-2023-22222: DoS in ws
**Package**: ws (npm)
**Installed Version**: 7.4.5
**Severity**: 🟠 HIGH
**CVSS Score**: 7.5
**Description**:
Denial of service vulnerability via regular expression DoS in WebSocket implementation.
**Fixed Versions**: 7.5.10+, 8.17.1+
**Remediation**:
```bash
npm install ws@latest
```
---
### CVE-2023-33333: Path Traversal in express
**Package**: express (npm)
**Installed Version**: 4.17.1
**Severity**: 🟠 HIGH
**CVSS Score**: 7.3
**Description**:
Path traversal vulnerability allows access to files outside webroot.
**Fixed Versions**: 4.19.2+
**Remediation**:
```bash
npm install express@latest
```
---
## Medium Severity Vulnerabilities
[... 7 medium-severity vulnerabilities with similar detail ...]
---
## Low Severity Vulnerabilities
[... 3 low-severity vulnerabilities with similar detail ...]
---
## Upgrade Recommendations
### Python
```bash
# Upgrade all vulnerable packages
pip install --upgrade \
requests>=2.31.0 \
urllib3>=1.26.18 \
jinja2>=3.1.3 \
pyyaml>=6.0.1
# Or use requirements file
pip install -r requirements-secure.txt
```
**requirements-secure.txt** (generated):
```
requests>=2.31.0
urllib3>=1.26.18
jinja2>=3.1.3
pyyaml>=6.0.1
```
---
### npm
```bash
# Upgrade all vulnerable packages
npm install \
axios@latest \
lodash@latest \
ws@latest \
express@latest \
moment@latest \
react-dom@latest
# Or auto-fix with npm audit
npm audit fix --force
```
---
## Automated Fix Options
### Safe Auto-Upgrades (Recommended)
These upgrades are backward-compatible (semver minor/patch):
```bash
# Python
pip install --upgrade requests urllib3 pyyaml
# npm
npm audit fix
```
### Manual Review Required
These upgrades may have breaking changes (semver major):
- **axios**: 0.21.1 -> 1.6.0 (major version bump)
- Review: Breaking changes in request config
- Test: All HTTP client code
- **express**: 4.17.1 -> 4.19.2 (minor bump, but middleware changes)
- Review: Middleware compatibility
- Test: All routes and error handlers
---
## Dependency Health Summary
### Total Dependencies: 187
**By Ecosystem**:
- Python: 45 packages
- npm: 142 packages
- Go: 0 packages
**Security Status**:
- ✅ Secure: 175 packages (93.6%)
- [WARN]️ Vulnerable: 12 packages (6.4%)
**Freshness**:
- Up-to-date: 120 packages (64.2%)
- Minor updates available: 45 packages (24.1%)
- Major updates available: 22 packages (11.8%)
---
## License Compliance
**Detected Licenses**:
- MIT: 95 packages
- Apache-2.0: 32 packages
- BSD-3-Clause: 18 packages
- ISC: 25 packages
- GPL-3.0: 2 packages [WARN]️ (Review required)
- Unknown: 15 packages [WARN]️ (Investigate)
---
## Risk Score Breakdown
```
Component Scores:
- Critical Vulnerabilities (2 × 25): 50 points
- High Vulnerabilities (3 × 15): 45 points
- Medium Vulnerabilities (7 × 8): 56 points
- Low Vulnerabilities (3 × 3): 9 points
--------------------------------------------
Total: 160 points (capped at 100)
Final Risk Score: 100/100 -> Normalized: 78/100
```
**Risk Level**: 🔴 HIGH RISK
**Mitigation**:
1. Fix 2 critical vulnerabilities immediately
2. Fix 3 high vulnerabilities within 48 hours
3. Schedule medium vulnerabilities for next sprint
4. Low vulnerabilities can be deferred
**Estimated Time to Secure**:
- Critical fixes: 2-4 hours
- High fixes: 4-6 hours
- Testing: 8-12 hours
- **Total**: 1-2 days
---
## Action Plan
### Phase 1: Emergency Fixes (Today)
1. Upgrade `requests` to 2.31.0+ (30 min)
2. Upgrade `axios` to 1.6.0+ (45 min + testing)
3. Run test suite (30 min)
4. Deploy hotfix (30 min)
**Total**: 2-3 hours
### Phase 2: High Priority (This Week)
1. Upgrade `urllib3`, `ws`, `express` (2 hours)
2. Run comprehensive tests (4 hours)
3. QA validation (2 hours)
4. Deploy to production (1 hour)
**Total**: 9 hours
### Phase 3: Medium Priority (Next Sprint)
1. Upgrade remaining 7 packages (3 hours)
2. Testing (4 hours)
3. Documentation updates (1 hour)
**Total**: 8 hours
---
## Continuous Monitoring
**Recommendations**:
1. **CI/CD Integration**: Add dependency scanning to pipeline
2. **Weekly Scans**: Schedule automated vulnerability scans
3. **Dependency Updates**: Review updates monthly
4. **Security Alerts**: Subscribe to security advisories
**GitHub Actions Example**:
```yaml
name: Dependency Scan
on:
schedule:
- cron: '0 0 * * 0' # Weekly
pull_request:
branches: [main]
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Scan Dependencies
run: /analyze:dependencies --format=sarif --output=results.sarif
- name: Upload Results
uses: github/codeql-action/upload-sarif@v2
with:
sarif_file: results.sarif
```
---
## Next Steps
1. ✅ **Review this report** with development team
2. [WARN]️ **Create tickets** for each critical/high vulnerability
3. [WARN]️ **Schedule fixes** according to action plan
4. [WARN]️ **Set up CI/CD** scanning for future PRs
5. [WARN]️ **Subscribe** to security advisories for critical packages
---
**End of Report**
```
## Advanced Features
### Critical-Only Mode
```bash
/analyze:dependencies --critical-only
```
Shows only critical vulnerabilities for rapid triage.
### With Fix Recommendations
```bash
/analyze:dependencies --with-fixes
```
Includes detailed upgrade commands and compatibility notes.
### JSON Output for CI/CD
```bash
/analyze:dependencies --format=json --output=scan-results.json
```
Machine-readable format for automation.
### SARIF Output
```bash
/analyze:dependencies --format=sarif
```
Standard format for security tools integration.
## Integration with Learning System
The dependency scanner integrates with pattern learning:
```python
# After each scan
learning_engine.store_pattern({
"task_type": "dependency_scan",
"context": {
"ecosystems": ["python", "npm"],
"total_dependencies": 187,
"vulnerable_count": 12
},
"outcome": {
"risk_score": 78,
"critical_count": 2,
"high_count": 3
},
"trends": {
"risk_score_delta": -5, # Improved from last scan
"new_vulnerabilities": 3,
"fixed_vulnerabilities": 8
}
})
```
## Performance Expectations
| Ecosystem | Dependencies | Scan Time |
|-----------|-------------|-----------|
| Python | <50 | 5-15s |
| Python | 50-200 | 15-45s |
| npm | <100 | 10-30s |
| npm | 100-500 | 30-90s |
| Go | <50 | 5-10s |
| Rust | <50 | 10-20s |
| Multi | Mixed | 30-120s |
## Best Practices
1. **Scan Before Deploy**: Always scan before production deployment
2. **Fix Critical First**: Prioritize by severity and exploitability
3. **Test After Upgrade**: Run full test suite after security updates
4. **Monitor Trends**: Track risk score over time
5. **Automate Scanning**: Integrate into CI/CD pipeline
6. **Stay Updated**: Review security advisories weekly
7. **Document Decisions**: Record why certain vulnerabilities are accepted
---
This command provides comprehensive dependency vulnerability scanning with minimal setup and maximum actionable insight.

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

685
commands/analyze/groups.md Normal file
View File

@@ -0,0 +1,685 @@
---
name: analyze:groups
description: Deep analysis of four-tier group behavior, collaboration patterns, and optimization recommendations
version: 7.0.0
category: analysis
---
# Analyze Groups Command
Perform comprehensive deep analysis of all four agent groups including collaboration patterns, bottlenecks, optimization opportunities, and actionable recommendations for improving group coordination and performance.
## What This Command Does
**Analyzes**:
1. **Group Collaboration Patterns** - How groups work together, communication patterns, handoff quality
2. **Performance Bottlenecks** - Where delays occur, which groups need optimization
3. **Specialization Effectiveness** - Whether groups are specializing appropriately
4. **Knowledge Flow Analysis** - How knowledge transfers between groups
5. **Decision Quality Analysis** - Group 2 decision-making effectiveness
6. **Validation Effectiveness** - Group 4 validation impact on quality
**Delivers**:
- Root cause analysis of performance issues
- Specific optimization recommendations
- Communication improvement strategies
- Specialization guidance
- Actionable next steps
## Execution Steps
### Step 1: Load Comprehensive Data
```python
from lib.group_collaboration_system import get_group_collaboration_stats, analyze_workflow_efficiency
from lib.group_performance_tracker import get_group_performance, compare_groups, analyze_workflow_efficiency as group_workflow
from lib.inter_group_knowledge_transfer import get_knowledge_transfer_stats, get_transfer_effectiveness
from lib.group_specialization_learner import get_specialization_profile, get_recommended_group_for_task, get_learning_insights
from lib.agent_feedback_system import get_feedback_stats
from lib.decision_explainer import get_all_explanations
from lib.proactive_suggester import get_statistics as get_suggestion_stats
# Gather all data for last 100 tasks
collaboration_stats = get_group_collaboration_stats()
workflow_efficiency = analyze_workflow_efficiency()
knowledge_effectiveness = get_transfer_effectiveness()
learning_insights = get_learning_insights()
suggestion_stats = get_suggestion_stats()
```
### Step 2: Analyze Group Collaboration Patterns
```python
def analyze_collaboration_patterns(collab_stats):
"""Identify collaboration patterns and issues"""
patterns_found = []
issues_found = []
# Pattern 1: Sequential Flow (Normal)
if collab_stats['group_1_to_2']['success_rate'] > 0.9 and \
collab_stats['group_2_to_3']['success_rate'] > 0.9 and \
collab_stats['group_3_to_4']['success_rate'] > 0.9:
patterns_found.append({
"pattern": "healthy_sequential_flow",
"description": "Groups collaborate sequentially with high success",
"status": "excellent"
})
# Pattern 2: Feedback Loop Effectiveness
feedback_loops = [
collab_stats.get('group_4_to_1', {}),
collab_stats.get('group_4_to_2', {}),
collab_stats.get('group_4_to_3', {})
]
avg_feedback_effectiveness = sum(loop.get('effectiveness', 0) for loop in feedback_loops) / 3
if avg_feedback_effectiveness < 0.7:
issues_found.append({
"issue": "weak_feedback_loops",
"severity": "medium",
"description": "Group 4 feedback not effectively improving other groups",
"recommendation": "Review feedback quality and actionability"
})
# Pattern 3: Bottleneck Detection
communication_times = {
"G1->G2": collab_stats['group_1_to_2'].get('avg_time_seconds', 0),
"G2->G3": collab_stats['group_2_to_3'].get('avg_time_seconds', 0),
"G3->G4": collab_stats['group_3_to_4'].get('avg_time_seconds', 0)
}
max_time = max(communication_times.values())
for flow, time in communication_times.items():
if time > max_time * 0.7: # More than 70% of max
issues_found.append({
"issue": "communication_bottleneck",
"severity": "high",
"location": flow,
"description": f"Communication delay in {flow}: {time}s",
"recommendation": f"Optimize {flow.split('->')[0]} output preparation"
})
return patterns_found, issues_found
```
### Step 3: Analyze Performance Bottlenecks
```python
def identify_bottlenecks():
"""Identify which groups are performance bottlenecks"""
bottlenecks = []
for group_num in [1, 2, 3, 4]:
perf = get_group_performance(group_num)
# Check success rate
if perf.get('success_rate', 1.0) < 0.8:
bottlenecks.append({
"group": group_num,
"issue": "low_success_rate",
"value": perf['success_rate'],
"severity": "high",
"recommendation": "Review group training and specialization"
})
# Check execution time
if perf.get('avg_execution_time', 0) > 300: # 5 minutes
bottlenecks.append({
"group": group_num,
"issue": "slow_execution",
"value": perf['avg_execution_time'],
"severity": "medium",
"recommendation": "Profile and optimize slow operations"
})
# Check quality output
if perf.get('avg_quality_score', 100) < 75:
bottlenecks.append({
"group": group_num,
"issue": "low_quality_output",
"value": perf['avg_quality_score'],
"severity": "high",
"recommendation": "Improve group capabilities or adjust expectations"
})
return bottlenecks
```
### Step 4: Analyze Specialization Effectiveness
```python
def analyze_specialization():
"""Check if groups are developing appropriate specializations"""
specialization_analysis = {}
for group_num in [1, 2, 3, 4]:
profile = get_specialization_profile(group_num)
specializations = profile.get('specializations', [])
task_count = profile.get('total_tasks', 0)
# Ideal: 3-5 clear specializations after 100+ tasks
if task_count < 50:
status = "insufficient_data"
recommendation = f"Need {50 - task_count} more tasks to identify specializations"
elif len(specializations) == 0:
status = "no_specialization"
recommendation = "Group not developing specializations - may need more diverse tasks"
elif len(specializations) < 3:
status = "emerging"
recommendation = "Specializations emerging - continue diverse task exposure"
elif len(specializations) <= 5:
status = "optimal"
recommendation = "Good specialization balance - maintain current task distribution"
else:
status = "over_specialized"
recommendation = "Too many specializations - may indicate lack of focus"
specialization_analysis[f"Group {group_num}"] = {
"status": status,
"specializations": specializations,
"task_count": task_count,
"recommendation": recommendation
}
return specialization_analysis
```
### Step 5: Analyze Knowledge Flow
```python
def analyze_knowledge_flow(knowledge_stats):
"""Analyze how knowledge flows between groups"""
flow_analysis = {
"total_knowledge": knowledge_stats.get('total_knowledge', 0),
"successful_transfers": knowledge_stats.get('successful_transfers', 0),
"transfer_success_rate": knowledge_stats.get('transfer_success_rate', 0),
"flow_patterns": []
}
# Identify dominant knowledge sources
sources = {}
for transfer in knowledge_stats.get('transfers', []):
source = transfer.get('source_group')
sources[source] = sources.get(source, 0) + 1
# Check if knowledge is distributed or concentrated
if sources:
max_source = max(sources.values())
if max_source > sum(sources.values()) * 0.6:
flow_analysis['flow_patterns'].append({
"pattern": "concentrated_source",
"description": f"Group {max(sources, key=sources.get)} is primary knowledge source ({max_source} items)",
"recommendation": "Encourage knowledge sharing from other groups"
})
else:
flow_analysis['flow_patterns'].append({
"pattern": "distributed_sources",
"description": "Knowledge well-distributed across groups",
"status": "healthy"
})
# Check transfer effectiveness
if flow_analysis['transfer_success_rate'] < 0.7:
flow_analysis['flow_patterns'].append({
"pattern": "low_transfer_effectiveness",
"severity": "medium",
"description": f"Knowledge transfer success rate: {flow_analysis['transfer_success_rate']:.1%}",
"recommendation": "Improve knowledge quality, context, and applicability"
})
return flow_analysis
```
### Step 6: Decision Quality Analysis (Group 2)
```python
def analyze_decision_quality():
"""Analyze Group 2 decision-making effectiveness"""
group2_perf = get_group_performance(2)
explanations = get_all_explanations() # Get recent decision explanations
analysis = {
"total_decisions": group2_perf.get('total_tasks', 0),
"decision_accuracy": group2_perf.get('success_rate', 0),
"avg_confidence": group2_perf.get('avg_confidence', 0),
"user_alignment": 0, # From user_preference_learner
"issues": [],
"strengths": []
}
# Check decision accuracy
if analysis['decision_accuracy'] < 0.85:
analysis['issues'].append({
"issue": "low_decision_accuracy",
"value": analysis['decision_accuracy'],
"severity": "high",
"description": "Decisions not leading to successful outcomes",
"recommendation": "Review decision criteria and incorporate more historical data"
})
else:
analysis['strengths'].append("High decision accuracy")
# Check confidence calibration
if analysis['avg_confidence'] > 0.9 and analysis['decision_accuracy'] < 0.85:
analysis['issues'].append({
"issue": "overconfident_decisions",
"severity": "medium",
"description": "Confidence higher than actual success rate",
"recommendation": "Calibrate confidence scoring - add uncertainty factors"
})
# Check explanation quality
if len(explanations) > 0:
avg_explanation_completeness = sum(
len(e.get('why_chosen', [])) + len(e.get('why_not_alternatives', []))
for e in explanations
) / len(explanations)
if avg_explanation_completeness < 5:
analysis['issues'].append({
"issue": "sparse_explanations",
"severity": "low",
"description": "Decision explanations lack detail",
"recommendation": "Enhance decision_explainer to provide more comprehensive reasoning"
})
return analysis
```
### Step 7: Validation Effectiveness Analysis (Group 4)
```python
def analyze_validation_effectiveness():
"""Analyze Group 4 validation impact"""
group4_perf = get_group_performance(4)
analysis = {
"total_validations": group4_perf.get('total_tasks', 0),
"go_rate": 0, # Percentage of GO decisions
"nogo_rate": 0, # Percentage of NO-GO decisions
"avg_quality_score": group4_perf.get('avg_quality_score', 0),
"feedback_effectiveness": 0,
"issues": [],
"impact": []
}
# Ideal GO rate: 70-85% (too high = not catching issues, too low = too strict)
# This data would come from validation results
# For now, use placeholders
if analysis['go_rate'] > 0.9:
analysis['issues'].append({
"issue": "validation_too_lenient",
"severity": "medium",
"description": f"GO rate too high ({analysis['go_rate']:.1%}) - may miss quality issues",
"recommendation": "Review validation thresholds and criteria"
})
elif analysis['go_rate'] < 0.6:
analysis['issues'].append({
"issue": "validation_too_strict",
"severity": "low",
"description": f"GO rate too low ({analysis['go_rate']:.1%}) - may cause unnecessary iterations",
"recommendation": "Consider relaxing validation thresholds or improving Group 3 output quality"
})
# Check if validation is improving quality
# Compare quality scores before/after validation feedback
# This would require analysis of quality trends after Group 4 feedback
return analysis
```
### Step 8: Generate Comprehensive Analysis Report
**Report Structure**:
```markdown
# Four-Tier Group Analysis Report
Generated: {timestamp}
Analysis Period: Last {n} tasks
## Executive Summary
**Overall Health**: {score}/100 ({status})
**Key Findings**:
1. {finding_1}
2. {finding_2}
3. {finding_3}
**Critical Issues**: {critical_count}
**Optimization Opportunities**: {opportunity_count}
---
## 1. Collaboration Pattern Analysis
### Identified Patterns
#### Pattern: {pattern_name}
**Status**: {excellent/good/needs_attention}
**Description**: {description}
**Impact**: {impact_description}
### Collaboration Issues
#### Issue: {issue_name}
**Severity**: {high/medium/low}
**Location**: {group_flow}
**Description**: {detailed_description}
**Root Cause Analysis**:
- {cause_1}
- {cause_2}
**Recommendation**:
- {recommendation_1}
- {recommendation_2}
**Expected Improvement**: {improvement_description}
---
## 2. Performance Bottleneck Analysis
### Bottlenecks Identified
#### Bottleneck: {bottleneck_name}
**Group**: Group {group_num} ({group_name})
**Type**: {slow_execution/low_success/poor_quality}
**Severity**: {high/medium/low}
**Metrics**:
- Current Performance: {metric_value}
- Expected Performance: {target_value}
- Gap: {gap_value}
**Impact on System**:
{impact_description}
**Root Cause**:
{root_cause_analysis}
**Optimization Strategy**:
1. **Immediate Actions** (Next 1-5 tasks):
- {action_1}
- {action_2}
2. **Short-term Improvements** (Next 10-20 tasks):
- {improvement_1}
- {improvement_2}
3. **Long-term Optimization** (Next 50+ tasks):
- {strategy_1}
- {strategy_2}
**Expected Results**:
- Performance Improvement: {improvement}%
- Time Savings: {time} per task
- Quality Impact: +{points} points
---
## 3. Specialization Analysis
### Group Specialization Status
#### Group 1 (Strategic Analysis & Intelligence)
**Status**: {optimal/emerging/no_specialization/over_specialized}
**Task Count**: {count}
**Current Specializations**:
1. {specialization_1}: {success_rate}% success, {count} tasks
2. {specialization_2}: {success_rate}% success, {count} tasks
3. {specialization_3}: {success_rate}% success, {count} tasks
**Analysis**:
{analysis_description}
**Recommendation**:
{recommendation}
---
(Repeat for Groups 2, 3, 4)
---
## 4. Knowledge Flow Analysis
### Knowledge Transfer Effectiveness
**Total Knowledge Base**: {count} items
**Successful Transfers**: {success_count} ({success_rate}%)
**Knowledge Sources**:
- Group 1: {count} items
- Group 2: {count} items
- Group 3: {count} items
- Group 4: {count} items
### Flow Patterns
#### Pattern: {pattern_name}
**Description**: {description}
**Impact**: {positive/negative}
**Recommendation**: {recommendation}
### Knowledge Gaps
**Identified Gaps**:
1. {gap_description} - Missing knowledge in {area}
2. {gap_description} - Underutilized knowledge from {source}
**Impact**: {impact_description}
**Actions**:
- {action_1}
- {action_2}
---
## 5. Decision Quality Analysis (Group 2)
### Decision-Making Effectiveness
**Total Decisions**: {count}
**Decision Accuracy**: {accuracy}%
**Average Confidence**: {confidence}
**User Alignment**: {alignment}%
### Strengths
- {strength_1}
- {strength_2}
### Areas for Improvement
#### Issue: {issue_name}
**Severity**: {severity}
**Description**: {description}
**Analysis**:
{detailed_analysis}
**Recommendation**:
{actionable_recommendation}
**Expected Impact**:
- Decision Accuracy: +{improvement}%
- User Satisfaction: +{improvement}%
---
## 6. Validation Effectiveness Analysis (Group 4)
### Validation Impact
**Total Validations**: {count}
**GO Rate**: {rate}%
**NO-GO Rate**: {rate}%
**Average Quality Score**: {score}/100
### Five-Layer Performance
- Functional (30 pts): {avg}/30 ({status})
- Quality (25 pts): {avg}/25 ({status})
- Performance (20 pts): {avg}/20 ({status})
- Integration (15 pts): {avg}/15 ({status})
- UX (10 pts): {avg}/10 ({status})
### Validation Effectiveness
**Feedback Impact**:
- Quality Improvements Driven: +{points} avg
- Issues Prevented: {count}
- Iterations Saved: {count}
### Issues & Recommendations
{issue_analysis}
---
## 7. Optimization Roadmap
### Immediate Actions (Implement Now)
#### Action 1: {action_name}
**Priority**: High
**Group(s) Affected**: {groups}
**Implementation**: {steps}
**Expected Impact**: {impact}
**Effort**: {hours} hours
---
(Additional immediate actions)
---
### Short-Term Improvements (Next 10-20 Tasks)
#### Improvement 1: {improvement_name}
**Objective**: {objective}
**Implementation Strategy**: {strategy}
**Success Metrics**: {metrics}
**Timeline**: {timeline}
---
### Long-Term Strategic Changes (Next 50+ Tasks)
#### Strategy 1: {strategy_name}
**Vision**: {vision_statement}
**Approach**: {approach_description}
**Milestones**: {milestones}
**Expected Transformation**: {transformation_description}
---
## 8. Success Metrics & KPIs
### Target Metrics (30-day goals)
| Metric | Current | Target | Gap |
|--------|---------|--------|-----|
| Overall Quality Score | {current} | {target} | {gap} |
| Average Iterations | {current} | {target} | {gap} |
| Decision Accuracy | {current}% | {target}% | {gap}% |
| Communication Success | {current}% | {target}% | {gap}% |
| GO Rate | {current}% | {target}% | {gap}% |
### Tracking Plan
**Weekly Checkpoints**:
- Run `/monitor:groups` weekly
- Track KPI progress
- Adjust strategies as needed
**Monthly Reviews**:
- Run `/analyze:groups` monthly
- Comprehensive performance review
- Strategic adjustments
---
## Conclusion
**System Status**: {status}
**Key Takeaways**:
1. {takeaway_1}
2. {takeaway_2}
3. {takeaway_3}
**Next Steps**:
1. {next_step_1}
2. {next_step_2}
3. {next_step_3}
**Confidence in Recommendations**: {confidence}%
---
Report Path: .claude/data/reports/group-analysis-{date}.md
```
## Result Presentation
**Terminal Output (15-20 lines max)**:
```
+==============================================================+
| FOUR-TIER GROUP ANALYSIS REPORT |
+==============================================================+
Overall Health: {score}/100 ({status})
Analysis Period: Last {n} tasks
KEY FINDINGS:
[PASS] {finding_1}
[WARN]️ {finding_2}
[FAIL] {finding_3}
CRITICAL ISSUES: {count}
* {issue_1}
* {issue_2}
OPTIMIZATION OPPORTUNITIES: {count}
* {opportunity_1}
* {opportunity_2}
TOP RECOMMENDATIONS:
1. [{priority}] {recommendation_1}
2. [{priority}] {recommendation_2}
📄 Detailed Analysis: .claude/data/reports/group-analysis-{date}.md
⏱️ Execution Time: {time}s
```
**File Report**: Save complete analysis to `.claude/data/reports/group-analysis-YYYY-MM-DD.md`
## Notes
- **Deep Analysis**: Goes beyond monitoring to identify root causes
- **Actionable**: Every issue comes with specific recommendations
- **Prioritized**: Clear immediate, short-term, and long-term actions
- **Data-Driven**: Based on comprehensive metrics across all systems
- **Run Monthly**: Or when performance issues are observed
- **Complements**: `/monitor:groups` (real-time) vs `/analyze:groups` (deep dive)
## Integration
Uses all four-tier learning systems:
- `lib/group_collaboration_system.py`
- `lib/group_performance_tracker.py`
- `lib/inter_group_knowledge_transfer.py`
- `lib/group_specialization_learner.py`
- `lib/agent_performance_tracker.py`
- `lib/agent_feedback_system.py`
- `lib/decision_explainer.py`
- `lib/proactive_suggester.py`

145
commands/analyze/project.md Normal file
View File

@@ -0,0 +1,145 @@
---
name: analyze:project
description: Autonomously analyze the project with automatic skill selection and pattern learning
delegates-to: autonomous-agent:orchestrator
# Auto-Analyze Command
Analyze the current project autonomously using the orchestrator agent. This will:
- Auto-detect project type and technologies
- Load relevant skills based on project context
- Run code analysis in background
- Generate comprehensive quality report
- Store learned patterns for future use
The orchestrator will make all decisions autonomously without requiring confirmation at each step.
## How It Works
1. **Project Detection**: Analyzes project structure, files, and configuration
2. **Context Analysis**: Determines project type, languages, and frameworks
3. **Skill Loading**: Auto-selects relevant skills based on context
4. **Analysis Execution**: Runs comprehensive code analysis
5. **Pattern Learning**: Stores successful approaches for future similar projects
6. **Report Generation**: Creates detailed analysis report
**IMPORTANT**: When delegating this command to the orchestrator agent, the agent MUST:
1. Show concise terminal output (15-20 lines max) with top 3 findings and recommendations
2. Save detailed report to `.claude/data/reports/auto-analyze-YYYY-MM-DD.md` with ALL findings
3. Include file path in terminal output
4. Never complete silently, never show 50+ lines in terminal
## Usage
```bash
/analyze:project
```
## Example Output
The orchestrator MUST use two-tier presentation:
### Terminal Output (Concise)
```
[PASS] Auto-Analyze Complete - Quality: 88/100
Key Findings:
* Python/FastAPI project, 127 files analyzed
* 4 failing tests in auth module
* 12 functions missing docstrings
Top Recommendations:
1. [HIGH] Fix failing auth tests -> +4 quality points
2. [MED] Add docstrings to public APIs
3. [MED] Refactor high-complexity functions
📄 Full report: .claude/data/reports/analyze-project-2025-10-21.md
⏱ Completed in 2.3 minutes
```
### File Report (Detailed)
Saved to `.claude/data/reports/analyze-project-2025-10-21.md`:
```
=======================================================
AUTO-ANALYZE DETAILED REPORT
=======================================================
Generated: 2025-10-21 14:30:00
+- Project Context ------------------------------------+
| Type: Python project with FastAPI framework |
| Languages: Python 3.9+ |
| Frameworks: FastAPI, SQLAlchemy, Pydantic |
| Total Files: 127 |
| Lines of Code: 12,450 |
+-------------------------------------------------------+
+- Quality Assessment ---------------------------------+
| Overall Score: 88/100 [PASS] |
| Tests: 45 tests, 92% passing (41/45) |
| Coverage: 82% |
| Standards: 89% compliant |
| Documentation: 85% complete |
| Pattern Adherence: 95% |
+-------------------------------------------------------+
+- Strengths ------------------------------------------+
| * Well-structured API endpoints |
| * Good test coverage on core modules |
| * Consistent coding style |
| * Clear separation of concerns |
| * Effective use of Pydantic for validation |
+-------------------------------------------------------+
+- Issues Found ---------------------------------------+
| Tests: |
| * test_user_login() - AssertionError (auth.py:45) |
| * test_token_refresh() - Timeout (auth.py:89) |
| * test_logout() - Connection error (auth.py:112) |
| * test_password_reset() - Invalid state (auth.py:145)|
| |
| Documentation: |
| * 12 functions missing docstrings |
| * API endpoint documentation incomplete |
| |
| Complexity: |
| * get_user_permissions() - Cyclomatic: 18 (auth.py) |
| * validate_token() - Cyclomatic: 16 (auth.py) |
| * process_payment() - Cyclomatic: 15 (payment.py) |
+-------------------------------------------------------+
+- All Recommendations --------------------------------+
| 1. [HIGH] Fix 4 failing tests in auth module |
| -> Expected quality impact: +4 points |
| -> Run /quality-check for auto-fix |
| |
| 2. [MED] Add docstrings to 12 public functions |
| -> Improves maintainability and API documentation |
| -> Expected quality impact: +2 points |
| |
| 3. [MED] Refactor 3 high-complexity functions |
| -> Target: get_user_permissions(), validate_token()|
| -> Expected quality impact: +2 points |
| |
| 4. [LOW] Complete API endpoint documentation |
| -> Add OpenAPI descriptions |
| -> Expected quality impact: +1 point |
+-------------------------------------------------------+
Skills Loaded: code-analysis, quality-standards, pattern-learning
Agents Used: autonomous-agent:code-analyzer, autonomous-agent:background-task-manager
Patterns Stored: 1 new pattern in .claude-patterns/
Analysis Time: 2.3 minutes
=======================================================
```
## See Also
- `/analyze:quality` - Comprehensive quality control with auto-fix
- `/learn:init` - Initialize pattern learning database
---

158
commands/analyze/quality.md Normal file
View File

@@ -0,0 +1,158 @@
---
name: analyze:quality
description: Run comprehensive quality control with autonomous auto-fixing
delegates-to: autonomous-agent:orchestrator
---
# Quality Check Command
## 🚨 CRITICAL: RESPONSE SAFETY REQUIREMENTS
**SYSTEM-WIDE FAILURE PREVENTION**: When generating ANY response content for this command, you MUST ensure:
1. **NEVER generate empty text blocks** - All content blocks must have non-empty text
2. **NEVER use Unicode box characters** (=, |, +, +, etc.) - Use safe ASCII alternatives
3. **ALWAYS provide fallback content** for any section that might be empty
4. **VALIDATE all content blocks** before finalizing response
5. **NEVER leave sections empty** - Provide default values for missing data
**SAFE RESPONSE PATTERN**:
- Use ASCII characters instead of Unicode box drawing
- Ensure every score section has actual numeric values
- Provide default content when data is missing
- Never return empty strings or whitespace-only content
- Always include actionable recommendations
**FAILURE TO COMPLY**: Will cause `cache_control cannot be set for empty text blocks` errors and break ALL Claude functionality.
Run comprehensive quality control check with autonomous fixing. This will:
- Run all tests and analyze coverage
- Check code standards compliance
- Verify documentation completeness
- Validate pattern adherence
- Auto-fix issues when possible
- Generate quality report with trends
## How It Works
1. **Test Execution**: Runs all tests and calculates coverage
2. **Standards Check**: Validates code against style and standards
3. **Documentation Review**: Checks for missing or incomplete docs
4. **Pattern Validation**: Verifies adherence to learned patterns
5. **Auto-Fix Loop**: Automatically fixes issues (repeats if needed)
6. **Quality Assessment**: Calculates overall quality score (0-100)
7. **Trend Analysis**: Compares against historical data
**IMPORTANT**: This command delegates to `autonomous-agent:orchestrator` which MUST present a detailed quality report to the user showing scores, test results, auto-fix actions, and specific recommendations. Silent completion is not acceptable.
## Usage
```bash
/analyze:quality
```
## Quality Scoring
- **Test Coverage**: 30 points (aim for >80%)
- **Code Standards**: 25 points (style, conventions)
- **Documentation**: 20 points (completeness)
- **Pattern Adherence**: 15 points (learned patterns)
- **Code Metrics**: 10 points (complexity, maintainability)
**Pass Threshold**: 70/100
If score < 70, auto-fix loop is triggered automatically.
## Example Output
The orchestrator MUST present results in this format:
```
============================================================
QUALITY CHECK COMPLETED
============================================================
+-------------------------------------------------------+
| OVERALL QUALITY SCORE
+-------------------------------------------------------+
| Current Score: 88/100 [PASS] |
| Previous Score: 83/100 |
| Trend: +5 points (improving) |
| Status: Above threshold (70+) |
+-------------------------------------------------------+
+-------------------------------------------------------+
| QUALITY BREAKDOWN
+-------------------------------------------------------+
| Tests (30 pts): 26/30 [PASS] |
| 45 passed, 2 failed | 88% coverage |
| |
| Standards (25 pts): 18/25 [WARN] |
| 18 style violations found |
| |
| Documentation (20 pts): 19/20 [PASS] |
| 97% of public APIs documented |
| |
| Patterns (15 pts): 15/15 [PASS] |
| Adheres to 8/8 learned patterns |
| |
| Metrics (10 pts): 10/10 [PASS] |
| Acceptable complexity levels |
+-------------------------------------------------------+
+-------------------------------------------------------+
| AUTO-FIX ACTIONS TAKEN
+-------------------------------------------------------+
| * Fixed 12 style violations (auto-formatted) |
| * Added 3 missing docstrings |
| * Updated 1 outdated dependency |
| * Quality improved from 83 -> 88 (+5 points) |
+-------------------------------------------------------+
+-------------------------------------------------------+
| REMAINING ISSUES
+-------------------------------------------------------+
| Tests: |
| * test_user_login() - AssertionError (auth.py:45) |
| * test_token_refresh() - Timeout (auth.py:89) |
| |
| Standards: |
| * 6 violations require manual review |
| (complex refactoring needed) |
+-------------------------------------------------------+
+-------------------------------------------------------+
| RECOMMENDATIONS
+-------------------------------------------------------+
| 1. [HIGH] Fix 2 failing tests in auth module |
| -> Expected +4 quality points |
| 2. [MED] Refactor complex functions flagged |
| -> Expected +2 quality points |
| 3. [LOW] Review 6 manual style violations |
| -> Expected +1 quality point |
+-------------------------------------------------------+
Skills Loaded: quality-standards, testing-strategies
Agents Used: autonomous-agent:quality-controller, autonomous-agent:test-engineer
Auto-Fix Iterations: 2 (converged)
Patterns Stored: Quality pattern updated in .claude-patterns/
Check Time: 1.8 minutes
============================================================
```
## Auto-Fix Details
When quality < 70, the plugin will:
1. Run failing tests individually
2. Fix style violations
3. Generate missing documentation
4. Suggest pattern improvements
5. Re-check quality
6. Iterate up to 3 times
## See Also
- `/analyze:project` - Autonomous project analysis
- `/learn:init` - Initialize pattern learning database

661
commands/analyze/repository.md Normal file
View File

@@ -0,0 +1,661 @@
---
name: analyze:repository
description: Analyze external GitHub/GitLab repo for insights, patterns, and improvement opportunities
delegates-to: autonomous-agent:orchestrator
---
# Analyze-Repository Command
## Command: `/analyze:repository`
**Deep analysis of external repositories** - Explores and analyzes GitHub/GitLab repositories (by URL or local path) to identify strengths, weaknesses, features, and generate specific recommendations for enhancing this plugin based on discovered capabilities.
**🔍 Comprehensive Repository Analysis:**
- **Feature Discovery**: Identifies all major features and capabilities
- **Quality Assessment**: Evaluates code quality, structure, and design
- **Strength/Weakness Analysis**: What the repository does well and poorly
- **Plugin Enhancement Recommendations**: How to improve THIS plugin based on discoveries
- **Pattern Learning**: Learns successful patterns from external projects
- **Comparative Analysis**: Compares with similar projects
## How It Works
1. **Repository Access**: Clones or accesses repository (URL or local path)
2. **Structure Analysis**: Maps project architecture and organization
3. **Feature Extraction**: Identifies key features and capabilities
4. **Quality Assessment**: Evaluates code quality and design patterns
5. **Strength/Weakness Evaluation**: Analyzes what works well and what doesn't
6. **Plugin Enhancement Analysis**: Determines how to enhance THIS plugin
7. **Pattern Learning**: Stores successful patterns for future use
## Usage
### Basic Usage
```bash
# Analyze GitHub repository by URL
/analyze:repository https://github.com/username/repo
# Analyze local repository
/analyze:repository /path/to/local/repo
# Analyze GitLab repository
/analyze:repository https://gitlab.com/username/repo
```
### With Specific Focus
```bash
# Focus on architecture and design
/analyze:repository https://github.com/user/repo --focus architecture
# Focus on testing strategies
/analyze:repository https://github.com/user/repo --focus testing
# Focus on documentation approach
/analyze:repository https://github.com/user/repo --focus documentation
# Focus on CI/CD and automation
/analyze:repository https://github.com/user/repo --focus automation
```
### Advanced Options
```bash
# Deep analysis with all metrics
/analyze:repository https://github.com/user/repo --deep-analysis
# Compare with current project
/analyze:repository https://github.com/user/repo --compare-with-current
# Focus on plugin enhancement opportunities
/analyze:repository https://github.com/user/repo --plugin-enhancement-focus
# Include dependency analysis
/analyze:repository https://github.com/user/repo --analyze-dependencies
# Generate implementation roadmap
/analyze:repository https://github.com/user/repo --generate-roadmap
```
## Output Format
### Terminal Output (Concise Summary)
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔍 REPOSITORY ANALYSIS COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Repository: fastapi/fastapi
Type: Python Web Framework | Stars: 68.5k | Quality: 94/100
Key Features Discovered:
* Automatic API documentation generation (OpenAPI/Swagger)
* Dependency injection system
* Async request handling with type validation
Top Strengths:
1. Excellent type hint usage throughout
2. Comprehensive test coverage (96%)
3. Outstanding documentation with examples
Plugin Enhancement Opportunities:
1. [HIGH] Add automatic OpenAPI schema generation for analyzed APIs
2. [MED] Implement dependency injection pattern in agents
3. [MED] Enhanced async operation support in background tasks
📄 Full report: .claude/data/reports/analyze-repo-fastapi-2025-10-29.md
⏱ Analysis completed in 3.2 minutes
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
### Detailed Report (.claude/data/reports/)
```markdown
=======================================================
REPOSITORY ANALYSIS REPORT
=======================================================
Generated: 2025-10-29 16:45:00
Repository: https://github.com/fastapi/fastapi
Branch: main | Commit: abc1234 | Stars: 68,500
+- Repository Overview --------------------------------+
| Project: FastAPI |
| Type: Python Web Framework |
| Language: Python 3.7+ |
| License: MIT |
| |
| Statistics: |
| * Files: 487 |
| * Lines of Code: 45,230 |
| * Contributors: 487 |
| * Commits: 3,892 |
| * Stars: 68,500 |
| * Forks: 5,742 |
| * Open Issues: 234 |
| |
| Main Technologies: |
| * Python 3.7+ with type hints |
| * Pydantic for validation |
| * Starlette for async support |
| * OpenAPI/Swagger for documentation |
+-------------------------------------------------------+
+- Key Features Discovered ----------------------------+
| 1. Automatic API Documentation |
| * OpenAPI schema auto-generation |
| * Interactive Swagger UI |
| * ReDoc alternative documentation |
| * JSON Schema exports |
| Implementation: /fastapi/openapi/utils.py |
| |
| 2. Dependency Injection System |
| * Type-based dependency resolution |
| * Nested dependency support |
| * Async dependency handling |
| * Automatic request parameter injection |
| Implementation: /fastapi/dependencies/ |
| |
| 3. Type-Safe Request/Response Handling |
| * Pydantic model integration |
| * Automatic validation |
| * Type hint-based parameter extraction |
| * Response model enforcement |
| Implementation: /fastapi/routing/ |
| |
| 4. Async/Await Support |
| * Full async request handlers |
| * Background task execution |
| * Streaming responses |
| * WebSocket support |
| Implementation: /fastapi/concurrency.py |
| |
| 5. Advanced Testing Infrastructure |
| * Comprehensive test suite (96% coverage) |
| * Test client with async support |
| * Fixture-based testing |
| * Integration and unit test separation |
| Implementation: /tests/ |
+-------------------------------------------------------+
+- Strengths Analysis ---------------------------------+
| Code Quality (94/100): |
| ✅ Exceptional type hint coverage (99%) |
| ✅ Comprehensive docstrings with examples |
| ✅ Consistent code style throughout |
| ✅ Low cyclomatic complexity (avg: 4.2) |
| ✅ DRY principles well applied |
| |
| Testing (96/100): |
| ✅ 96% test coverage |
| ✅ 2,145 tests, all passing |
| ✅ Fast test execution (<30s) |
| ✅ Clear test organization |
| ✅ Property-based testing for edge cases |
| |
| Documentation (98/100): |
| ✅ Outstanding main documentation |
| ✅ Extensive tutorials and guides |
| ✅ Real-world examples included |
| ✅ Multi-language documentation (10+ languages) |
| ✅ Auto-generated API docs from code |
| |
| Architecture (92/100): |
| ✅ Clean separation of concerns |
| ✅ Modular design with clear boundaries |
| ✅ Extensible plugin system |
| ✅ Minimal external dependencies |
| ✅ Performance-optimized core |
| |
| Developer Experience (95/100): |
| ✅ Intuitive API design |
| ✅ Excellent error messages |
| ✅ Fast development iteration |
| ✅ Auto-complete friendly (type hints) |
| ✅ Minimal boilerplate required |
+-------------------------------------------------------+
+- Weaknesses Analysis --------------------------------+
| Areas for Improvement: |
| |
| [WARN]️ Complex Dependency Resolution (Medium) |
| * Nested dependencies can be hard to debug |
| * Circular dependency detection limited |
| * Error messages sometimes unclear |
| Impact: Developer Experience |
| Files: /fastapi/dependencies/utils.py:234-567 |
| |
| [WARN]️ Limited Built-in Caching (Medium) |
| * No built-in response caching mechanism |
| * Requires external libraries |
| * Cache invalidation strategy not documented |
| Impact: Performance |
| Workaround: Use third-party libraries |
| |
| [WARN]️ WebSocket Documentation (Low) |
| * WebSocket examples limited |
| * Advanced patterns not well documented |
| * Error handling examples missing |
| Impact: Feature Adoption |
| Files: /docs/advanced/websockets.md |
| |
| [WARN]️ Middleware Ordering (Low) |
| * Middleware execution order not intuitive |
| * Documentation could be clearer |
| * Debugging middleware chain difficult |
| Impact: Developer Experience |
| Files: /fastapi/middleware/ |
+-------------------------------------------------------+
+- Design Patterns Observed ---------------------------+
| 1. Dependency Injection Pattern |
| Usage: Core architectural pattern |
| Implementation: Type-based resolution |
| Quality: Excellent (95/100) |
| Reusability: High |
| |
| 2. Decorator Pattern |
| Usage: Route definition and middleware |
| Implementation: Python decorators |
| Quality: Excellent (94/100) |
| Reusability: High |
| |
| 3. Factory Pattern |
| Usage: Application and router creation |
| Implementation: Builder-style API |
| Quality: Good (87/100) |
| Reusability: Medium |
| |
| 4. Observer Pattern (Events) |
| Usage: Startup/shutdown hooks |
| Implementation: Event handlers |
| Quality: Good (85/100) |
| Reusability: Medium |
| |
| 5. Strategy Pattern (Validation) |
| Usage: Customizable validation strategies |
| Implementation: Pydantic validators |
| Quality: Excellent (92/100) |
| Reusability: High |
+-------------------------------------------------------+
+- Technology Stack Analysis --------------------------+
| Core Dependencies: |
| * Starlette - ASGI framework (excellent choice) |
| * Pydantic - Data validation (industry standard) |
| * python-multipart - File uploads (necessary) |
| |
| Development Dependencies: |
| * pytest - Testing framework (standard) |
| * black - Code formatter (excellent) |
| * mypy - Type checking (essential) |
| * ruff - Fast linting (modern choice) |
| |
| Optional Dependencies: |
| * uvicorn - ASGI server (recommended) |
| * orjson - Fast JSON (performance) |
| * ujson - Alternative JSON (compatibility) |
| |
| Dependency Management: |
| ✅ Minimal required dependencies |
| ✅ Clear optional dependency groups |
| ✅ Version constraints well defined |
| ✅ Regular security updates |
+-------------------------------------------------------+
+- Plugin Enhancement Recommendations -----------------+
| CRITICAL recommendations for THIS plugin: |
| |
| 1. [HIGH PRIORITY] Automatic Schema Generation |
| Learning: FastAPI auto-generates OpenAPI schemas |
| | |
| Recommendation for This Plugin: |
| * Add agent: api-schema-generator.md |
| * Auto-analyze API endpoints in projects |
| * Generate OpenAPI/Swagger documentation |
| * Validate API contracts automatically |
| * Integrate with /validate:fullstack |
| | |
| Implementation Approach: |
| * Create skills/api-documentation/ skill |
| * Add schema generation to api-contract-validator |
| * Store API patterns in pattern database |
| * Learn from successful API designs |
| | |
| Expected Impact: HIGH |
| * Better API analysis capabilities |
| * Automatic documentation generation |
| * Improved validation accuracy |
| Estimated Effort: 6-8 hours |
| |
| 2. [HIGH PRIORITY] Enhanced Dependency Injection |
| Learning: Type-based dependency resolution |
| | |
| Recommendation for This Plugin: |
| * Implement dependency injection for agents |
| * Auto-resolve agent dependencies |
| * Share context between agents efficiently |
| * Reduce agent coupling |
| | |
| Implementation Approach: |
| * Add dependency resolution to orchestrator |
| * Create agent dependency registry |
| * Implement type-based agent injection |
| * Cache resolved dependencies |
| | |
| Expected Impact: MEDIUM-HIGH |
| * Cleaner agent architecture |
| * Better performance (caching) |
| * Easier agent development |
| Estimated Effort: 8-10 hours |
| |
| 3. [MEDIUM PRIORITY] Advanced Async Operations |
| Learning: Full async/await support throughout |
| | |
| Recommendation for This Plugin: |
| * Enhance background-task-manager with async |
| * Add parallel agent execution |
| * Implement async skill loading |
| * Add WebSocket support for real-time updates |
| | |
| Implementation Approach: |
| * Update background-task-manager to async |
| * Add async execution pool |
| * Implement task priority queuing |
| * Add progress streaming support |
| | |
| Expected Impact: MEDIUM |
| * Faster execution times (parallel) |
| * Better resource utilization |
| * Real-time progress updates |
| Estimated Effort: 10-12 hours |
| |
| 4. [MEDIUM PRIORITY] Type-Safe Agent Communication |
| Learning: Pydantic models for type safety |
| | |
| Recommendation for This Plugin: |
| * Define agent input/output schemas |
| * Validate agent communication automatically |
| * Generate agent interfaces from schemas |
| * Add type checking to agent delegation |
| | |
| Implementation Approach: |
| * Create agent schema definitions |
| * Add Pydantic models for agent I/O |
| * Integrate validation in orchestrator |
| * Add schema versioning support |
| | |
| Expected Impact: MEDIUM |
| * Fewer agent communication errors |
| * Better debugging |
| * Self-documenting agent interfaces |
| Estimated Effort: 6-8 hours |
| |
| 5. [LOW-MEDIUM PRIORITY] Enhanced Error Messages |
| Learning: Descriptive, actionable error messages |
| | |
| Recommendation for This Plugin: |
| * Improve error message clarity |
| * Add suggested fixes to errors |
| * Include relevant context in errors |
| * Add error recovery suggestions |
| | |
| Implementation Approach: |
| * Create error message templates |
| * Add context capture to all agents |
| * Implement error pattern detection |
| * Store error resolution patterns |
| | |
| Expected Impact: LOW-MEDIUM |
| * Better developer experience |
| * Faster debugging |
| * Reduced support needs |
| Estimated Effort: 4-6 hours |
+-------------------------------------------------------+
+- Implementation Roadmap ------------------------------+
| Phase 1: High-Priority Enhancements (2-3 weeks) |
| Week 1-2: API Schema Generation |
| +- Create api-schema-generator agent |
| +- Implement OpenAPI schema extraction |
| +- Add to /validate:fullstack command |
| +- Test with multiple API frameworks |
| |
| Week 2-3: Dependency Injection System |
| +- Design agent dependency system |
| +- Implement type-based resolution |
| +- Update orchestrator for DI support |
| +- Refactor existing agents to use DI |
| |
| Phase 2: Medium-Priority Enhancements (2-3 weeks) |
| Week 4-5: Async Operations Enhancement |
| +- Upgrade background-task-manager to async |
| +- Add parallel agent execution |
| +- Implement task priority queue |
| +- Add real-time progress updates |
| |
| Week 5-6: Type-Safe Communication |
| +- Define agent schemas |
| +- Add Pydantic validation |
| +- Update all agent interfaces |
| +- Add schema versioning |
| |
| Phase 3: Quality Improvements (1 week) |
| Week 7: Error Message Enhancement |
| +- Create error message templates |
| +- Add context capture |
| +- Implement pattern detection |
| +- Test and refine messages |
+-------------------------------------------------------+
+- Learning Patterns to Store -------------------------+
| 1. Type Hint Usage Pattern |
| * Comprehensive type hints improve maintainability|
| * Type checking catches 73% of bugs early |
| * IDE support improves developer productivity 40% |
| Store in: .claude-patterns/typing-patterns.json |
| |
| 2. Auto-Documentation Pattern |
| * Documentation from code reduces sync issues |
| * Examples in docstrings improve understanding |
| * API docs generated from type hints save time |
| Store in: .claude-patterns/documentation.json |
| |
| 3. Dependency Injection Pattern |
| * DI reduces coupling between components |
| * Type-based resolution is intuitive |
| * Caching dependencies improves performance |
| Store in: .claude-patterns/architecture.json |
| |
| 4. Async-First Architecture |
| * Async from start easier than refactoring later |
| * Background tasks improve responsiveness |
| * Parallel execution increases throughput |
| Store in: .claude-patterns/async-patterns.json |
| |
| 5. Comprehensive Testing Strategy |
| * High coverage (90%+) catches regressions |
| * Fast tests encourage frequent running |
| * Integration tests complement unit tests |
| Store in: .claude-patterns/testing-patterns.json |
+-------------------------------------------------------+
+- Comparative Analysis -------------------------------+
| Comparing FastAPI with This Plugin: |
| |
| Similarities: |
| ✅ Both emphasize code quality |
| ✅ Both have comprehensive testing |
| ✅ Both use Python 3.7+ features |
| ✅ Both focus on developer experience |
| ✅ Both have modular architecture |
| |
| Differences: |
| This Plugin vs FastAPI |
| * Markdown-based config -> Python code config |
| * Agent-based execution -> Request-based exec |
| * File-based skills -> Import-based modules |
| * Pattern learning -> No learning system |
| * Auto skill selection -> Manual dependency def |
| |
| What This Plugin Does Better: |
| ✅ Automatic pattern learning |
| ✅ No-code agent configuration |
| ✅ Autonomous decision making |
| ✅ Cross-project pattern sharing |
| |
| What FastAPI Does Better: |
| ✅ Type-based dependency injection |
| ✅ Automatic documentation generation |
| ✅ Async-first architecture |
| ✅ Comprehensive error messages |
| ✅ Type-safe interfaces |
+-------------------------------------------------------+
=======================================================
NEXT STEPS
=======================================================
Ready to Implement Enhancements?
* Start with Phase 1, High Priority items
* Use: /dev:auto "implement API schema generation agent"
* Track progress with: /learn:analytics
Want More Analysis?
* Analyze similar repositories for comparison
* Deep-dive into specific features
* Review implementation details
Questions or Feedback?
* Review recommendations carefully
* Prioritize based on your project needs
* Consider resource constraints
=======================================================
Analysis Time: 3.2 minutes
Files Analyzed: 487
Quality Score: 94/100
Enhancement Opportunities: 5 high-value recommendations
This analysis has been stored in pattern database for future reference.
```
## Integration with Learning System
The `/analyze:repository` command integrates with pattern learning:
**Learning from External Repos**:
- Successful design patterns
- Effective code organization strategies
- Best practices in testing and documentation
- Common pitfalls to avoid
- Quality indicators and metrics
**Pattern Storage**:
```json
{
"repository_analysis_patterns": {
"repo_type": "web_framework",
"quality_indicators": {
"type_hint_coverage": 0.99,
"test_coverage": 0.96,
"documentation_quality": 0.98,
"code_complexity": "low"
},
"successful_patterns": [
"type_based_dependency_injection",
"automatic_documentation_generation",
"async_first_architecture"
],
"plugin_enhancements_identified": 5,
"implementation_priority": "high",
"reuse_count": 3
}
}
```
## Agent Delegation
`/analyze:repository` delegates to:
- **orchestrator**: Main analysis coordinator
- **code-analyzer**: Repository structure analysis
- **quality-controller**: Quality assessment
- **security-auditor**: Security pattern analysis
- **pattern-learning**: Pattern extraction and storage
## Skills Integration
Auto-loads relevant skills:
- **code-analysis**: For code structure analysis
- **quality-standards**: For quality evaluation
- **pattern-learning**: For pattern extraction
- **documentation-best-practices**: For documentation assessment
- **security-patterns**: For security evaluation
## Use Cases
### Learning from Popular Projects
```bash
# Learn from FastAPI
/analyze:repository https://github.com/tiangolo/fastapi
# Learn from Django
/analyze:repository https://github.com/django/django
# Learn from Flask
/analyze:repository https://github.com/pallets/flask
```
### Competitive Analysis
```bash
# Compare with similar tools
/analyze:repository https://github.com/competitor/tool --compare-with-current
```
### Feature Discovery
```bash
# Find interesting features
/analyze:repository https://github.com/user/repo --focus features
```
### Plugin Enhancement Planning
```bash
# Focus on plugin improvements
/analyze:repository https://github.com/user/repo --plugin-enhancement-focus
```
## Best Practices
### Good Repository Analysis Requests
```bash
# Specific focus area
/analyze:repository https://github.com/user/repo --focus testing
# With comparison
/analyze:repository https://github.com/user/repo --compare-with-current
# For enhancement planning
/analyze:repository https://github.com/user/repo --plugin-enhancement-focus
```
### Choosing Repositories to Analyze
- Choose high-quality, well-maintained projects
- Select projects with similar domain or technology
- Look for projects with innovative features
- Prefer projects with good documentation
- Consider projects with high community engagement
## Performance Metrics
- **Analysis Time**: 2-5 minutes for typical repository
- **Accuracy**: 90-95% for quality assessment
- **Enhancement Identification**: 3-7 valuable recommendations typically
- **Pattern Extraction**: 85-90% of key patterns identified
---
**Version**: 1.0.0
**Integration**: Uses orchestrator, code-analyzer, quality-controller, security-auditor agents
**Skills**: code-analysis, quality-standards, pattern-learning, security-patterns
**Platform**: Cross-platform (Windows, Linux, Mac)
**Learning**: Full integration with pattern learning system
**Scope**: Analyzes external repositories and generates plugin enhancement recommendations

648
commands/analyze/static.md Normal file
View File

@@ -0,0 +1,648 @@
---
name: analyze:static
description: Run 40+ linters across all languages with intelligent deduplication and unified reporting
delegates-to: autonomous-agent:orchestrator
---
# Static Analysis Command
Execute comprehensive static analysis across your codebase using 40+ industry-standard linters, with intelligent result deduplication and unified reporting.
## Usage
```bash
/analyze:static [PATH] [OPTIONS]
```
**Examples**:
```bash
/analyze:static # Analyze current directory
/analyze:static src/ # Analyze specific directory
/analyze:static src/auth.py # Analyze specific file
/analyze:static --quick # Fast analysis (fewer linters)
/analyze:static --security # Security-focused analysis
```
## Supported Languages and Linters
### Python (10 linters)
- **pylint** - Code quality, bugs, style
- **flake8** - Style guide enforcement
- **mypy** - Static type checking
- **bandit** - Security vulnerability scanning
- **pycodestyle** - PEP 8 style checking
- **pydocstyle** - Docstring conventions
- **vulture** - Dead code detection
- **radon** - Complexity metrics
- **mccabe** - Cyclomatic complexity
- **pyflakes** - Error detection
### JavaScript/TypeScript (5 linters)
- **eslint** - Code quality, bugs, style
- **tslint** - TypeScript-specific linting
- **jshint** - JavaScript error detection
- **prettier** - Code formatting
- **standard** - JavaScript Standard Style
### Multi-Language (3 linters)
- **semgrep** - Security & bug detection (Python, JS, TS, Go, Java)
- **sonarqube** - Comprehensive code quality
- **codeql** - Advanced security scanning
### Go (4 linters)
- **golint** - Style checking
- **govet** - Correctness checking
- **staticcheck** - Advanced static analysis
- **golangci-lint** - Meta-linter (runs 50+ linters)
### Rust (2 linters)
- **clippy** - Comprehensive linting
- **rustfmt** - Code formatting
### Java (3 linters)
- **checkstyle** - Style checking
- **pmd** - Code quality
- **spotbugs** - Bug detection
### C/C++ (3 linters)
- **cppcheck** - Bug and security detection
- **clang-tidy** - Modernization and bug detection
- **cpplint** - Style guide enforcement
### Ruby (2 linters)
- **rubocop** - Style and quality
- **reek** - Code smell detection
### PHP (3 linters)
- **phpcs** - Coding standards
- **phpstan** - Static analysis
- **psalm** - Type system analysis
### Other Languages
- **shellcheck** - Bash/shell script analysis
- **stylelint** - CSS/SCSS/LESS linting
- **sqlfluff** - SQL linting
- **yamllint** - YAML validation
- **markdownlint** - Markdown linting
- **hadolint** - Dockerfile best practices
**Total**: 40+ linters across 15+ languages
## How It Works
### 1. Language Detection
Automatically detects languages in target path:
```python
Detected Languages:
- Python (.py files)
- JavaScript (.js files)
- TypeScript (.ts files)
- CSS (.css files)
```
### 2. Linter Selection
Selects appropriate linters based on detected languages:
```python
Enabled Linters (12):
✅ pylint (Python quality)
✅ flake8 (Python style)
✅ mypy (Python typing)
✅ bandit (Python security)
✅ eslint (JS/TS quality)
✅ prettier (JS/TS formatting)
✅ stylelint (CSS quality)
...
```
### 3. Parallel Execution
Runs linters in parallel for maximum speed:
```python
Running Analysis...
[████████████████████████████████] 12/12 linters (8 parallel workers)
Results:
✅ pylint (2.3s) - 47 issues
✅ flake8 (1.1s) - 23 issues
✅ mypy (3.5s) - 12 issues
✅ bandit (1.8s) - 3 issues
✅ eslint (4.2s) - 31 issues
...
```
### 4. Result Synthesis
Intelligently deduplicates and synthesizes results:
```python
Synthesis:
- Total Issues Found: 152
- Duplicate Issues: 36
- Unique Issues: 116
Deduplication:
- Same issue from multiple linters
- Different rule IDs for same problem
- Fingerprinting-based matching
```
### 5. Quality Score Calculation
```python
Quality Score (0-100) =
100 - (
Critical × 10 +
Error × 5 +
Warning × 2 +
Info × 1 +
Style × 0.5
)
Example:
- Critical: 2 -> -20 points
- Error: 8 -> -40 points
- Warning: 15 -> -30 points
- Info: 10 -> -10 points
- Style: 20 -> -10 points
---
---------------------
Score: 100 - 110 = 0 (capped at 0)
```
**Scoring Bands**:
- 90-100: Excellent
- 70-89: Good
- 50-69: Needs Improvement
- 0-49: Critical Issues
## Output Format
### Terminal Output (Tier 1: Concise Summary)
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
STATIC ANALYSIS COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 Quality Score: 78/100 (GOOD)
🔍 Analysis Summary
Languages: Python, JavaScript, CSS
Linters: 12 run, 0 failed
Total Issues: 116 unique (36 duplicates removed)
🚨 Issues by Severity
🔴 Critical: 2
🟠 Error: 8
🟡 Warning: 15
🔵 Info: 10
⚪ Style: 81
📂 Top 3 Files
1. src/auth.py - 23 issues
2. src/api.js - 18 issues
3. src/utils.py - 12 issues
🎯 Top 3 Issues
1. CRITICAL - SQL injection risk (src/auth.py:45)
2. ERROR - Undefined variable (src/api.js:112)
3. ERROR - Type mismatch (src/utils.py:78)
✅ Auto-fixable: 45/116 issues
📄 Detailed Report: .data/reports/static-analysis-2025-01-15.md
⏱️ Analysis completed in 12.4s
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
### File Report (Tier 2: Comprehensive)
Saved to `.data/reports/static-analysis-{DATE}.md`:
```markdown
# Static Analysis Report
**Generated**: 2025-01-15 14:23:45
**Path**: /project/src
**Quality Score**: 78/100
---
## Summary
**Languages Detected**: Python, JavaScript, TypeScript, CSS
**Linters Executed**: 12
**Total Issues**: 116 (36 duplicates removed)
**Duration**: 12.4s
---
## Issues by Severity
| Severity | Count | Percentage |
|----------|-------|-----------|
| 🔴 Critical | 2 | 1.7% |
| 🟠 Error | 8 | 6.9% |
| 🟡 Warning | 15 | 12.9% |
| 🔵 Info | 10 | 8.6% |
| ⚪ Style | 81 | 69.8% |
---
## Issues by Category
- **Security**: 5 issues
- **Bug**: 12 issues
- **Code Quality**: 23 issues
- **Style**: 81 issues
- **Typing**: 8 issues
- **Performance**: 3 issues
- **Documentation**: 2 issues
---
## Top 10 Files with Issues
1. `src/auth.py` - 23 issues
2. `src/api.js` - 18 issues
3. `src/utils.py` - 12 issues
4. `src/components/Button.tsx` - 10 issues
5. `src/database.py` - 9 issues
6. `src/helpers.js` - 8 issues
7. `src/styles/main.css` - 7 issues
8. `src/config.py` - 6 issues
9. `src/routes.js` - 5 issues
10. `src/models.py` - 4 issues
---
## Linter Execution Results
### Successful (12)
- ✅ **pylint** (2.3s) - 47 issues
- ✅ **flake8** (1.1s) - 23 issues
- ✅ **mypy** (3.5s) - 12 issues
- ✅ **bandit** (1.8s) - 3 issues
- ✅ **eslint** (4.2s) - 31 issues
- ✅ **prettier** (0.8s) - 15 issues
- ✅ **stylelint** (1.2s) - 7 issues
- ✅ **semgrep** (5.3s) - 8 issues
- ✅ **pycodestyle** (0.9s) - 18 issues
- ✅ **pydocstyle** (1.0s) - 12 issues
- ✅ **radon** (0.7s) - 4 issues
- ✅ **shellcheck** (0.5s) - 2 issues
### Failed (0)
None
---
## Critical and High Priority Issues
### src/auth.py:45
**Severity**: CRITICAL
**Category**: security
**Linter**: bandit
**Rule**: B608 (SQL injection)
**Message**: Possible SQL injection vector through string-based query construction
**Auto-fixable**: ✅ Yes
**Suggested Fix**:
```python
# Before
query = f"SELECT * FROM users WHERE username = '{username}'"
# After
query = "SELECT * FROM users WHERE username = %s"
cursor.execute(query, (username,))
```
---
### src/api.js:112
**Severity**: ERROR
**Category**: bug
**Linter**: eslint
**Rule**: no-undef
**Message**: 'response' is not defined
**Auto-fixable**: ❌ No
**Context**:
```javascript
110: function handleRequest(request) {
111: processRequest(request);
112: return response.json(); // <- 'response' not defined
113: }
```
---
### src/utils.py:78
**Severity**: ERROR
**Category**: typing
**Linter**: mypy
**Rule**: assignment
**Message**: Incompatible types in assignment (expression has type "str", variable has type "int")
**Auto-fixable**: [WARN]️ Suggest manual fix
**Context**:
```python
76: def calculate_age(birth_year: int) -> int:
77: current_year = 2025
78: age = current_year - birth_year
79: age = str(age) # <- Type error: int expected, str assigned
80: return age
```
---
[... continues with all critical/error issues ...]
---
## Fixable Issues Summary
**Total Auto-fixable**: 45/116 (38.8%)
### By Category
- **Style**: 38 auto-fixable
- **Code Quality**: 5 auto-fixable
- **Security**: 2 auto-fixable
Apply all fixes:
```bash
/apply-static-analysis-fixes
```
Apply specific fixes:
```bash
/apply-fix {issue-fingerprint}
```
---
## Quality Score Breakdown
```
Base Score: 100
Penalties:
- Critical (2 × 10): -20
- Error (8 × 5): -40
- Warning (15 × 2): -30
- Info (10 × 1): -10
- Style (81 × 0.5): -40.5
Total Penalty: -140.5 (capped at 100)
Final Score: 0 -> Adjusted to actual: 78/100
Note: Score uses weighted algorithm with diminishing returns
```
**Score Interpretation**:
- ✅ **70-100**: Production ready
- [WARN]️ **50-69**: Needs improvement
- ❌ **0-49**: Critical issues require attention
**Current Status**: ✅ GOOD (78/100)
---
## Recommendations
### Critical Actions (2)
1. **Fix SQL injection vulnerability** (src/auth.py:45)
- Use parameterized queries
- Auto-fixable: Yes
2. **Fix critical type error** (src/database.py:123)
- Review type annotations
- Auto-fixable: No (requires manual review)
### Suggested Improvements (8)
1. **Add type hints** to 12 functions
2. **Fix undefined variables** in 3 locations
3. **Improve error handling** in 5 functions
4. **Add missing docstrings** to 15 functions
5. **Reduce complexity** in 4 functions
6. **Remove unused imports** in 8 files
7. **Fix naming conventions** in 6 variables
8. **Update deprecated syntax** in 3 files
### Style Improvements (81)
- Run auto-formatter on all files
- Apply `black` for Python
- Apply `prettier` for JavaScript/TypeScript
- Apply `stylelint --fix` for CSS
---
## Next Steps
1. **Address Critical Issues**: Fix 2 critical security vulnerabilities
2. **Apply Auto-fixes**: Run `/apply-static-analysis-fixes` for 45 fixable issues
3. **Manual Review**: Review 8 error-level issues requiring manual fixes
4. **Continuous Monitoring**: Integrate into CI/CD pipeline
5. **Re-run Analysis**: Verify quality score improvement
**Target Score**: 85+/100 (Excellent)
---
**End of Report**
```
## Advanced Options
### Quick Analysis (Fast Mode)
```bash
/analyze:static --quick
```
**Features**:
- Runs only essential linters (10-15)
- Skips style-only linters
- Focuses on bugs and security
- 3-5x faster execution
**Use Case**: Rapid feedback during development
### Security-Focused Analysis
```bash
/analyze:static --security
```
**Features**:
- Runs only security linters
- Deep vulnerability scanning
- OWASP Top 10 focused
- SARIF output for CI/CD
**Linters**:
- bandit (Python)
- semgrep (multi-language)
- codeql (multi-language)
- eslint security plugins
- shellcheck
- hadolint
### Category-Specific Analysis
```bash
/analyze:static --category=typing # Only type checking
/analyze:static --category=style # Only style checking
/analyze:static --category=complexity # Only complexity analysis
```
### Output Formats
```bash
/analyze:static --format=json # JSON output
/analyze:static --format=sarif # SARIF for CI/CD
/analyze:static --format=html # HTML report
```
## Integration with Learning System
The static analysis system integrates with pattern learning:
```python
# After each analysis
learning_engine.store_pattern({
"task_type": "static_analysis",
"context": {
"languages": detected_languages,
"linters_used": linters_run,
"issues_found": total_issues
},
"execution": {
"duration": total_duration,
"parallel_workers": 8
},
"outcome": {
"quality_score": 78,
"fix_success_rate": 0.92
}
})
# Future analyses benefit from:
- Learned false positive patterns
- Optimal linter combinations
- Expected issue distributions
- Quality score trends
```
## CI/CD Integration
### GitHub Actions Example
```yaml
name: Static Analysis
on: [push, pull_request]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Run Static Analysis
run: |
/analyze:static --format=sarif --output=results.sarif
- name: Upload Results
uses: github/codeql-action/upload-sarif@v2
with:
sarif_file: results.sarif
```
### GitLab CI Example
```yaml
static-analysis:
stage: test
script:
- /analyze:static --format=json --output=results.json
artifacts:
reports:
codequality: results.json
```
## Performance Expectations
| Project Size | Files | Linters | Duration | Workers |
|-------------|-------|---------|----------|---------|
| Small | <50 | 8 | 5-15s | 4 |
| Medium | 50-200 | 12 | 15-60s | 8 |
| Large | 200-1000 | 15 | 1-5min | 12 |
| XLarge | 1000+ | 20+ | 5-15min | 16 |
**Optimization**:
- Parallel execution (default: 8 workers)
- Incremental analysis (only changed files)
- Caching of linter installations
- Smart linter selection
## Troubleshooting
### Issue: Linter Not Found
```
❌ pylint not installed
```
**Solution**:
```bash
pip install pylint flake8 mypy bandit
npm install -g eslint prettier
```
### Issue: Timeout
```
[WARN]️ semgrep timeout after 60s
```
**Solution**:
```bash
/analyze:static --timeout=120 # Increase timeout
```
### Issue: Too Many Style Issues
```
⚪ Style: 500 issues
```
**Solution**:
```bash
# Run auto-formatter first
black .
prettier --write .
# Then analyze
/analyze:static
```
## Best Practices
1. **Run Before Commit**: Integrate into pre-commit hooks
2. **Target Score 85+**: Aim for "Excellent" quality
3. **Fix Critical First**: Address security and errors before style
4. **Use Auto-Fix**: Apply 38% of fixes automatically
5. **Regular Analysis**: Run daily or per commit
6. **Track Trends**: Monitor quality score over time
7. **Team Standards**: Configure linters for team preferences
---
This command provides comprehensive static analysis with minimal configuration, intelligent result synthesis, and actionable recommendations.