claude-skills/README.md

# 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