This repository contains a comprehensive multi-agent orchestration system for Claude Code that transforms it into a workflow-aware development environment with specialized agents, automated quality gates, and intelligent coordination patterns.
-
Clone this repository to your Claude Code configuration directory:
git clone https://github.com/bwads001/claude-code-agents.git ~/.claude -
Make hooks executable:
chmod +x ~/.claude/hooks/*.py
-
Start using specialized workflows:
claude # Your alias should include --dangerously-skip-permissions /output-style execution # Switch to implementation mode "Implement user authentication using the backend-database-engineer"
# Copy project template
cp ~/.claude/CLAUDE_template.md ./CLAUDE.md
# Customize the template (replace [PLACEHOLDERS] and complete TODOs)
# Create ai-docs/ directory structure
# Start development with specialized agentsWhile platforms like Augment Code use ML-driven vector search to automatically discover context at scale, we take a deliberately different approach: explicit, human-guided context management through specialized agents and documentation.
Traditional Claude Code usage suffers from context pollution and workflow inefficiency:
- Main thread cluttered with lint errors, log files, and repetitive tasks
- Agent prompts bloated with quality gate instructions and tool usage patterns
- Cognitive load scattered across orchestration, implementation, and validation
- Knowledge fragmented across conversations without persistent context
- Manual context building - forgetting to include crucial codebase docs and patterns
- Auto-compression context loss - vital information disappears when context limits hit
- Inconsistent code patterns - agents can't follow established conventions without manual prompting
# Traditional approach - context pollution
❌ "Let me run lint, check types, create component, test it, commit..."
# Agentic approach - pure orchestration
✅ "I'll use frontend-ui-specialist → code-quality-reviewer → git-workflow-specialist"- No repetitive rules - agents focus purely on their expertise
- Context injection hooks give agents "cheat codes" with automatic project context
- Quality automation hooks remove lint/typecheck cruft from agent definitions
- Knowledge persistence through ai-docs/ system across conversations
# Research Mode: Pure discovery, no implementation pressure
# Planning Mode: Requirements focus, no rushed decisions
# Execution Mode: Implementation focus, plans already decidedProblem Solved: No more manual context assembly or forgotten references
Agents automatically receive:
- Project structure - complete codebase layout without manual discovery
- Available ai-docs listing - "here are your architectural guides, library patterns, etc."
- Git context - current branch, recent changes, workflow state
- Domain-specific focus - backend agents get DB patterns, frontend gets component guides
- Established patterns - automatically injected from ai-docs/ based on task type
Before (Manual Context Building):
# You manually include in every prompt:
❌ "Here's the project structure: [paste], here are our DB patterns: [paste],
here's our component style: [paste], follow these lint rules: [paste]..."After (Automatic Context Injection):
# Hook automatically provides context:
✅ Agent receives: "📁 Project structure, 📚 Available guides:
drizzle-patterns.md, component-architecture.md, 🌿 Branch: feature/auth"| Principle | Traditional Claude | Agentic Orchestration |
|---|---|---|
| Clear | Mixed concerns, scattered focus | Dedicated specialists, pure domains |
| Concise | Bloated prompts with repeated rules | Automated context injection |
| Complete | Manual discovery each conversation | Persistent knowledge base |
| Consistent | Ad-hoc quality checks | Automated hooks and standards |
Problem Solved: Vital context survives conversation length limits
| Issue | Traditional Approach | Agentic Solution |
|---|---|---|
| Context Loss | Auto-compression drops your codebase docs | ai-docs/ referenced by filename, re-injected per agent |
| Pattern Drift | Agents forget established patterns mid-conversation | Hooks re-inject patterns automatically each invocation |
| Reference Forgetting | You forget to include DB schema in backend tasks | Context injection hook provides relevant ai-docs automatically |
| Consistency Decay | Code style drifts as conversation continues | Fresh context injection prevents pattern degradation |
Key Innovation: Instead of cramming context into prompts, references to ai-docs/ are injected, keeping conversations lightweight while preserving access to comprehensive knowledge.
- 60% fewer tokens - no repeated quality gate instructions or manual context
- 80% less discovery time - automated context injection with established patterns
- Zero lint noise - quality automation handles mundane checks
- 100% pattern consistency - hooks re-inject standards automatically per agent
- Zero context loss - ai-docs/ references survive compression, can be re-read on demand
This system implements a three-layer orchestration architecture:
Location: output-styles/
Purpose: Set workflow-specific orchestration patterns
- Research Mode: Discovery and learning focus
- Planning Mode: Requirements and design focus
- Execution Mode: Implementation and delivery focus
Location: agents/CLAUDE.md
Purpose: Agent delegation patterns that work across all projects
- Mandatory agent delegation rules
- Quality gate coordination
- Agent selection guidance
Location: Project root CLAUDE.md
Purpose: Tech stack, business domain, and project-specific patterns
- Technology stack configuration
- Business requirements and compliance
- Project-specific quality commands and workflows
Location: agents/
Each agent is an expert in specific domains:
| Agent | Purpose | Use When |
|---|---|---|
| project-manager | Planning docs, workflow orchestration | Start/end of features, planning lifecycle |
| backend-database-engineer | Database, APIs, server logic | Any backend work - don't do server work yourself |
| frontend-ui-specialist | UI components, styling, design | Any frontend work - don't create components yourself |
| feature-architect-planner | Complex feature planning | Breaking down large features, architecture decisions |
| code-quality-reviewer | Manual QA, integration testing | Quality gates - automated tools handled by hooks |
| documentation-specialist | Research, library guides, ai-docs | Library research, knowledge management |
| git-workflow-specialist | Git operations, branches, commits | Any git work - don't handle git yourself |
| file-refactor-organizer | Code organization, large files | Files >300 lines, structure improvements |
Reference: agents/README.md for complete agent documentation
Location: hooks/
Automated quality gates that run invisibly during development:
| Hook | Trigger | Purpose |
|---|---|---|
| agent-context-injection | Before agent runs | Auto-inject project context and ai-docs |
| agent-performance-monitor | Before agent runs | Track usage patterns, suggest optimizations |
| agent-result-validator | After agent completes | Validate text responses meet quality standards |
| file-content-validator | After code edits | Prevent debugging cruft and compatibility bloat |
Benefits:
- No manual quality checks - hooks handle lint/typecheck automatically
- Anti-bloat protection - blocks "backwards compatible" and debugging remnants
- Consistent standards - same quality gates across all work
- Agent optimization - performance monitoring and suggestions
Reference: hooks/README.md for complete hook system documentation
Location: ai-docs/
Structured documentation that agents can automatically discover and use:
| Directory | Purpose | When Agents Use |
|---|---|---|
| architecture/ | System design patterns | Before architectural decisions |
| business-context/ | Domain requirements | Understanding business needs |
| guides/ | Implementation patterns | Implementing features, integrations |
| library-guides/ | Third-party integrations | Adding dependencies, using libraries |
| planning/ | Active development plans | Planning workflow coordination |
| troubleshooting/ | Known issues, solutions | Debugging, problem-solving |
Agent Integration:
- Context injection hook automatically lists available ai-docs for agents
- documentation-specialist maintains and creates knowledge base content
- All agents check ai-docs before implementation to follow established patterns
Reference: ai-docs/README.md for complete documentation system guide
# 1. Research Phase: Understand the domain
/output-style research
"Help me understand authentication patterns in Next.js applications"
# 2. Planning Phase: Design the solution
/output-style planning
"Design a comprehensive user authentication system with role-based access"
# 3. Execution Phase: Build the feature
/output-style execution
"Implement the authentication system from the planning documents"# Execution mode automatically coordinates multiple specialists:
"Build a user dashboard with analytics"
# Behind the scenes:
# 1. project-manager: Moves plan from backlog → active
# 2. backend-database-engineer: Creates analytics queries and API endpoints
# 3. frontend-ui-specialist: Builds dashboard components and charts
# 4. code-quality-reviewer: Validates UX and runs integration tests
# 5. git-workflow-specialist: Handles commits, branches, and PR creation
# 6. project-manager: Moves plan to completed, coordinates human handoff- Output Styles Guide - Workflow orchestration modes
- Agent System Guide - Specialized agent usage and patterns
- Hook System Guide - Quality automation and monitoring
- AI Documentation Guide - Knowledge management system
- Universal Orchestration - Core agent delegation rules
- Advanced Patterns (Conceptual) - Future possibilities with headless mode
- Context Management Comparison - How we compare to Augment Code's approach
- Keep main thread pure - orchestration only, zero implementation details
- Let hooks handle repetitive tasks - no manual lint/typecheck in conversations
- Use agents for all specialized work - backend, frontend, git, quality, documentation
- Switch output styles intentionally - research → planning → execution workflow
- Trust the delegation rules - agents are experts with automatic context injection
- Batch related tasks - frontend + backend + quality for complete features
- Review agent reports for integration guidance and next steps
- Update ai-docs when agents discover new patterns or solutions
| Mode | When to Use | Main Thread Focus | Agent Behavior |
|---|---|---|---|
| Research | Unknown domain, new tech | Ask questions, gather info | Deep exploration, documentation creation |
| Planning | Feature design, architecture | Requirements, acceptance criteria | Comprehensive planning, trade-off analysis |
| Execution | Implementation ready | Orchestrate specialists | Follow plans, coordinate delivery |
- Main branch: Stable, production-ready configurations
- Issues: Bug reports, feature requests, and improvements
- Pull requests: Contributions following established patterns
- BTCEnoch: Read-only collaborator for review and feedback
- Community contributions welcome through GitHub issues and PRs
- Documentation improvements especially appreciated for public usage
This system transforms Claude Code from a coding assistant into a comprehensive development orchestration platform that combines specialized expertise, automated quality gates, and intelligent workflow coordination to create more effective development experiences.
Get started: Copy this configuration to your ~/.claude/ directory and begin experiencing the power of coordinated multi-agent development.