672bdacc8d
This update corrects misleading performance and cost claims in the documentation: CORRECTED CLAIMS: - Performance: Changed from "40-50% faster" to "20-30% faster" (honest observation) - Token Cost: Changed from "60-70% savings" to "1.9-2.0x more expensive" (actual cost) - Parallelism: Clarified "concurrent requests" vs "true parallel execution" - Architecture: Updated from "parallel" to "concurrent" throughout NEW DOCUMENTATION: - REALITY.md: Honest assessment and reality vs. marketing - ARCHITECTURE.md: Technical details on concurrent vs. parallel execution - TOKEN-USAGE.md: Detailed token cost breakdown and optimization strategies UPDATED FILES: - master-orchestrator.md: Accurate performance, cost, and when-to-use guidance - README.md: Updated architecture overview and trade-offs KEY INSIGHTS: - Concurrent agent architecture IS valuable but for different reasons: * Main thread context is clean (20-30% of single-agent size) * 4 independent expert perspectives (genuine value) * API rate limiting affects actual speed (20-30% typical) * Cost is 1.9-2.0x tokens vs. single agent analysis - Best for enterprise quality-critical work, NOT cost-efficient projects - Includes decision matrix and cost optimization strategies This update maintains technical accuracy while preserving the genuine benefits of multi-perspective analysis and context isolation that make the system valuable.
386 lines
11 KiB
Markdown
386 lines
11 KiB
Markdown
# Claude Skills Repository
|
|
|
|
A collection of professional, production-ready Claude AI skills for developers.
|
|
|
|
## Architecture Overview
|
|
|
|
The Master Workflow system uses a **concurrent agent architecture** with specialized sub-agents:
|
|
|
|
```
|
|
Master Orchestrator
|
|
├─ Stage 1: Git Preparation (Sequential)
|
|
├─ Concurrent Execution (4 agents submitted simultaneously):
|
|
│ ├─ Code Review Agent (Stage 2)
|
|
│ ├─ Architecture Audit Agent (Stage 3)
|
|
│ ├─ Security & Compliance Agent (Stage 4)
|
|
│ └─ Multi-Perspective Agent (Stage 5)
|
|
├─ Stage 6: Synthesis & Prioritization (Sequential)
|
|
└─ Stages 7-9: Interactive Resolution & Push (Sequential)
|
|
```
|
|
|
|
**Key Characteristics:**
|
|
- Concurrent request submission (not true parallel execution)
|
|
- Main thread context is clean (20-30% of single-agent size)
|
|
- Total token cost is higher (1.9-2.0x more expensive)
|
|
- 4 independent expert perspectives
|
|
- Execution time: 20-30% faster than single agent
|
|
- Best for: Enterprise quality-critical reviews
|
|
- See [REALITY.md](REALITY.md), [ARCHITECTURE.md](ARCHITECTURE.md), [TOKEN-USAGE.md](TOKEN-USAGE.md) for honest details
|
|
|
|
---
|
|
|
|
## Skills
|
|
|
|
### Master Workflow Orchestrator (v2.0.0)
|
|
|
|
**High-Performance Parallel Code Quality Pipeline**
|
|
|
|
The main orchestrator that coordinates 4 specialized sub-agents running in parallel.
|
|
|
|
**Features:**
|
|
- ✅ Code review automation
|
|
- ✅ Security compliance validation (OWASP Top 10)
|
|
- ✅ Architecture & quality audit (6 dimensions)
|
|
- ✅ Multi-perspective PR review (6 stakeholder angles)
|
|
- ✅ Interactive issue resolution
|
|
- ✅ Safe git operations with quality gates
|
|
- ✅ Language-agnostic (Python, JavaScript, Dart, Go, Rust, Java, etc.)
|
|
- ✅ Framework-independent
|
|
- ✅ Works on any project type
|
|
|
|
**Activation Phrases:**
|
|
- `@master`
|
|
- "complete workflow"
|
|
- "finish session"
|
|
- "full pipeline"
|
|
- "wrap up and push"
|
|
- And more...
|
|
|
|
**Usage:**
|
|
```
|
|
@master
|
|
```
|
|
|
|
**Time Estimate:** 31-42 minutes (full pipeline with concurrent execution) or 10-15 minutes (quick mode)
|
|
|
|
**Concurrent Sub-Agents:**
|
|
- **Code Review Agent** - Stage 2: Code quality, readability, secrets detection (~15K tokens)
|
|
- **Architecture Audit Agent** - Stage 3: Design patterns, coupling, technical debt (6 dimensions) (~18K tokens)
|
|
- **Security & Compliance Agent** - Stage 4: OWASP Top 10, vulnerabilities, compliance (~16K tokens)
|
|
- **Multi-Perspective Agent** - Stage 5: 6 stakeholder perspectives (Product, Dev, QA, Security, DevOps, Design) (~13K tokens)
|
|
- **Total Token Cost:** ~68K tokens (1.9-2.0x vs. single agent)
|
|
|
|
**Recommended For:**
|
|
- Enterprise quality-critical code
|
|
- Security-critical changes
|
|
- Release preparation
|
|
- Code ready to merge with high scrutiny
|
|
- Complex architectural changes requiring multiple expert reviews
|
|
- Regulatory compliance requirements
|
|
- Team reviews needing Product/Dev/QA/Security/DevOps input
|
|
- **NOT for:** Cost-sensitive projects, simple changes, frequent rapid reviews
|
|
|
|
**Trade-offs:**
|
|
- Execution: 20-30% faster than single agent (not 40-50%)
|
|
- Cost: 2x tokens vs. single comprehensive review
|
|
- Value: 4 independent expert perspectives
|
|
|
|
**Included:**
|
|
- 9-stage quality assurance pipeline
|
|
- Automated code review
|
|
- Security and compliance checks
|
|
- Architecture audit
|
|
- Multi-perspective feedback
|
|
- Issue resolution assistance
|
|
- Safe push to origin
|
|
|
|
## Repository Structure
|
|
|
|
```
|
|
.
|
|
├── README.md # This file
|
|
├── master-orchestrator.md # Main orchestrator (v2.0 parallel)
|
|
├── code-review-agent.md # Stage 2 sub-agent (parallel)
|
|
├── architecture-audit-agent.md # Stage 3 sub-agent (parallel)
|
|
├── security-compliance-agent.md # Stage 4 sub-agent (parallel)
|
|
├── multi-perspective-agent.md # Stage 5 sub-agent (parallel)
|
|
├── master-workflow.md # Legacy single-agent version (v1.0)
|
|
├── LICENSE # MIT License
|
|
├── CONTRIBUTING.md # Contribution guidelines
|
|
└── .gitignore # Git ignore patterns
|
|
```
|
|
|
|
**Files Breakdown:**
|
|
- **1 Orchestrator:** Coordinates execution
|
|
- **4 Sub-Agents:** Specialized parallel analysis
|
|
- **Documentation:** Installation, contributing, license
|
|
- **Legacy:** v1.0 single-agent skill (for reference)
|
|
|
|
## Quick Start
|
|
|
|
1. Copy the skill file to your Claude Code skills directory:
|
|
```bash
|
|
cp master-workflow.md ~/.claude/skills/
|
|
```
|
|
|
|
2. In Claude Code, invoke with:
|
|
```
|
|
@master
|
|
```
|
|
|
|
3. Follow the 9-stage pipeline to completion
|
|
|
|
## Installation
|
|
|
|
### Option 1: Install All Skills (Recommended - Parallel Architecture)
|
|
|
|
**Copy all skill files:**
|
|
```bash
|
|
git clone https://git.openharbor.io/svrnty/claude-skills.git
|
|
cp claude-skills/master-orchestrator.md ~/.claude/skills/
|
|
cp claude-skills/code-review-agent.md ~/.claude/skills/
|
|
cp claude-skills/architecture-audit-agent.md ~/.claude/skills/
|
|
cp claude-skills/security-compliance-agent.md ~/.claude/skills/
|
|
cp claude-skills/multi-perspective-agent.md ~/.claude/skills/
|
|
```
|
|
|
|
**Or one command:**
|
|
```bash
|
|
cp claude-skills/*.md ~/.claude/skills/
|
|
```
|
|
|
|
### Option 2: Install Orchestrator Only (if agents already installed)
|
|
```bash
|
|
cp master-orchestrator.md ~/.claude/skills/
|
|
```
|
|
|
|
### Option 3: Use Legacy Single-Agent Version
|
|
```bash
|
|
# If you prefer the v1.0 sequential architecture
|
|
cp master-workflow.md ~/.claude/skills/
|
|
```
|
|
|
|
## Requirements
|
|
|
|
- Claude Code (latest version)
|
|
- Git repository initialized
|
|
- Not on main/master/trunk/production branch
|
|
- Upstream tracking configured
|
|
|
|
## Compatibility
|
|
|
|
**Languages:** Python, JavaScript/TypeScript, Dart, Go, Rust, Java, C/C++, Ruby, PHP, and any other language
|
|
|
|
**Frameworks:** Language and framework-agnostic
|
|
|
|
**Project Types:**
|
|
- Backend services
|
|
- Frontend applications
|
|
- Full-stack projects
|
|
- Mobile apps
|
|
- Desktop applications
|
|
- CLI tools
|
|
- Data science projects
|
|
- DevOps/Infrastructure
|
|
- Monorepos
|
|
- Microservices
|
|
|
|
**Platforms:** Any platform with Git support (GitHub, GitLab, Gitea, self-hosted)
|
|
|
|
## Features
|
|
|
|
### Stage 1: Git Status & Preparation
|
|
- Verify repository state
|
|
- Check branch safety
|
|
- Confirm readiness
|
|
|
|
### Stage 2: Code Review
|
|
- Recent changes analysis
|
|
- Code quality assessment
|
|
- Security issue detection
|
|
- Readability check
|
|
|
|
### Stage 3: Architecture Audit
|
|
- 6-dimensional analysis (Architecture, Quality, Security, Performance, Testing, Maintainability)
|
|
- Design pattern evaluation
|
|
- Technical debt assessment
|
|
- Coupling analysis
|
|
|
|
### Stage 4: Security & Compliance
|
|
- OWASP Top 10 validation
|
|
- Enterprise security controls
|
|
- Dependency vulnerability scanning
|
|
- Secrets detection
|
|
|
|
### Stage 5: Multi-Perspective Review
|
|
- Product Manager perspective
|
|
- Developer perspective
|
|
- QA Engineer perspective
|
|
- Security Engineer perspective
|
|
- DevOps perspective
|
|
- UI/UX Designer perspective
|
|
|
|
### Stage 6: Synthesis & Prioritization
|
|
- Consolidate all findings
|
|
- Create action plan
|
|
- Estimate remediation effort
|
|
- Identify quick wins
|
|
|
|
### Stage 7: Issue Resolution
|
|
- Interactive issue fixing
|
|
- Targeted assistance
|
|
- Re-validation
|
|
|
|
### Stage 8: Pre-Push Verification
|
|
- Final safety checks
|
|
- Branch confirmation
|
|
- Remote verification
|
|
|
|
### Stage 9: Safe Git Push
|
|
- Automated commit
|
|
- Quality summary
|
|
- Secure push to origin
|
|
|
|
## Usage Modes
|
|
|
|
### Full Pipeline (Default)
|
|
```
|
|
@master
|
|
```
|
|
Executes all 9 stages (35-60 minutes)
|
|
|
|
### Quick Review
|
|
```
|
|
@master --quick
|
|
```
|
|
Stages 1-2 only (10-15 minutes)
|
|
|
|
### Security-Focused
|
|
```
|
|
@master --security
|
|
```
|
|
Prioritizes Stages 4-5
|
|
|
|
### Review Only
|
|
```
|
|
@master --review-only
|
|
```
|
|
All stages except push
|
|
|
|
### Force Mode
|
|
```
|
|
@master --force
|
|
```
|
|
Skip blockers and push (use with caution)
|
|
|
|
## Language Support
|
|
|
|
Tested and optimized for:
|
|
|
|
**Popular Languages:**
|
|
- Python (Django, FastAPI, Flask, async)
|
|
- JavaScript/TypeScript (React, Vue, Node, NestJS)
|
|
- Dart (Flutter, web, desktop)
|
|
- Go (microservices, CLI)
|
|
- Rust (systems, web, embedded)
|
|
- Java (Spring Boot, Android)
|
|
- Ruby (Rails, Sinatra)
|
|
- PHP (Laravel, Symfony)
|
|
|
|
**And supports any other language...**
|
|
|
|
## Performance
|
|
|
|
**Stage Breakdown:**
|
|
- Stage 1 (Git Prep): 2-3 minutes
|
|
- Stages 2-5 (Concurrent agents): 20-25 minutes (concurrent, not sequential)
|
|
- Stage 6 (Synthesis): 3-5 minutes
|
|
- Stage 7 (Issue Resolution): Variable
|
|
- Stage 8 (Verification): 2-3 minutes
|
|
- Stage 9 (Push): 2-3 minutes
|
|
|
|
**Total:** 31-42 minutes for full pipeline (20-30% improvement over single agent sequential)
|
|
|
|
**Note:** Actual improvement depends on API queue depth and rate limits. See [ARCHITECTURE.md](ARCHITECTURE.md) for details on concurrent vs. parallel execution.
|
|
|
|
## Safety Features
|
|
|
|
- ✅ Branch protection (prevents main/master pushes)
|
|
- ✅ Quality gates (blocks push if critical issues)
|
|
- ✅ Secret detection (finds exposed API keys)
|
|
- ✅ Confirmation gates (requires explicit approval)
|
|
- ✅ Re-validation (after fixes)
|
|
- ✅ Rollback-friendly (clean commit history)
|
|
|
|
## Contributing
|
|
|
|
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on:
|
|
- Bug reports
|
|
- Feature requests
|
|
- Improvements
|
|
- Language-specific enhancements
|
|
|
|
## License
|
|
|
|
[See LICENSE file](LICENSE)
|
|
|
|
## Support
|
|
|
|
For issues or questions:
|
|
1. Check the skill documentation
|
|
2. Review the 9-stage pipeline guide
|
|
3. Create an issue in the repository
|
|
|
|
## Roadmap
|
|
|
|
Future enhancements planned:
|
|
- [ ] Language-specific linting integration
|
|
- [ ] Framework-specific best practices
|
|
- [ ] CI/CD pipeline integration
|
|
- [ ] Custom rule sets
|
|
- [ ] Multi-language projects support
|
|
- [ ] Docker-based analysis
|
|
- [ ] Pre-commit hook integration
|
|
|
|
## Changelog
|
|
|
|
### v2.1.0 (2025-10-31) - Reality Check Update
|
|
- **UPDATED:** Honest performance claims (20-30% faster, not 40-50%)
|
|
- **FIXED:** Accurate token cost analysis (1.9-2.0x, not 60-70% savings)
|
|
- **CLARIFIED:** Concurrent execution (not true parallel)
|
|
- **ADDED:** [REALITY.md](REALITY.md) - Honest assessment
|
|
- **ADDED:** [ARCHITECTURE.md](ARCHITECTURE.md) - Technical details on concurrent vs. parallel
|
|
- **ADDED:** [TOKEN-USAGE.md](TOKEN-USAGE.md) - Detailed cost breakdown
|
|
- **UPDATED:** When-to-use guidance (enterprise vs. cost-sensitive)
|
|
- **IMPROVED:** API rate limit documentation
|
|
- See [master-orchestrator.md](master-orchestrator.md) for detailed v2.1 changes
|
|
|
|
### v2.0.0 (2024-10-31)
|
|
- Concurrent sub-agent architecture (4 agents submitted simultaneously)
|
|
- Master Orchestrator for coordination
|
|
- Code Review Agent (Stage 2) - Code quality specialist
|
|
- Architecture Audit Agent (Stage 3) - Design & patterns specialist
|
|
- Security & Compliance Agent (Stage 4) - Security specialist
|
|
- Multi-Perspective Agent (Stage 5) - Stakeholder feedback
|
|
- Execution time: 20-30% faster than single agent
|
|
- Context: Main thread is clean (20-30% size of single agent)
|
|
- Cost: 1.9-2.0x tokens vs. single agent
|
|
- Better accuracy through specialization
|
|
- More maintainable modular architecture
|
|
|
|
### v1.0.0 (2024-10-31)
|
|
- Initial single-agent release
|
|
- 9-stage sequential pipeline
|
|
- Universal language support
|
|
- **Note:** Superseded by v2.0.0 concurrent architecture for enterprise use
|
|
|
|
## Author
|
|
|
|
Svrnty Development Team
|
|
|
|
---
|
|
|
|
**Status:** Production Ready
|
|
**Marketplace Compatible:** Yes
|
|
**Universal:** Works with any language, framework, project type
|