sub-agent-workflow-quickstart.md

🚀 Claude Sub-Agent Workflows: 1-2-3 Quick Start

This guide shows how to leverage Claude sub-agents through the command workflows system for powerful multi-agent development in CODITECT v4.

📋 Prerequisites

1. Claude Code installed and running
2. Sub-agent repositories cloned in ~/.claude/:

   cd ~/.claude
   git submodule add https://github.com/wshobson/agents.git agents-reference
   git submodule add https://github.com/wshobson/commands.git commands-reference

🎯 1-2-3 Quick Start

1️⃣ Choose Your Workflow Type

For Complex Features → Use Workflows (multi-agent orchestration):

/workflows:feature-development implement user authentication with OAuth2

For Specific Tasks → Use Tools (single-purpose):

/tools:api-scaffold create REST endpoints for user management

2️⃣ Understand the Flow

When you invoke a workflow, Claude:

1. Analyzes your requirements
2. Delegates to specialized sub-agents via Task tool
3. Coordinates responses between agents
4. Delivers integrated solution

3️⃣ Execute and Monitor

# Start with CODI monitoring active
./.codi/scripts/codi-log-ai.sh "ORCHESTRATOR: Starting OAuth2 workflow" "WORKFLOW_START"

# Invoke the workflow
/workflows:feature-development OAuth2 authentication with JWT tokens

# Monitor progress in logs
tail -f .codi/logs/codi-ps.log | grep -E "TASK|COMPLETE"

📚 Common Workflow Examples

Example 1: Complete Feature Development

Scenario: Build a shopping cart feature with payment integration

# Traditional development approach
/workflows:feature-development shopping cart with Stripe payment integration

# What happens behind the scenes:
# 1. backend-architect designs API endpoints and data model
# 2. frontend-developer creates React components using API design
# 3. test-automator writes comprehensive test suite
# 4. deployment-engineer prepares production deployment

Example 2: Test-Driven Development

Scenario: Build order validation logic using TDD

# TDD approach - complete cycle
/workflows:tdd-cycle order validation with inventory checks

# Or manual TDD steps for more control:
/tools:tdd-red create failing tests for order validation
/tools:tdd-green implement minimal code to pass tests
/tools:tdd-refactor optimize validation logic

Example 3: Smart Problem Solving

Scenario: Debug production performance issues

# Let the system analyze and fix intelligently
/workflows:smart-fix high memory usage in worker processes

# The workflow will:
# 1. Analyze the problem type
# 2. Select appropriate specialist agents
# 3. Coordinate debugging and fixes
# 4. Validate the solution

Example 4: Security Hardening

Scenario: Implement security best practices

# Complete security review and hardening
/workflows:security-hardening implement zero-trust architecture

# Individual security tools:
/tools:security-scan OWASP Top 10 vulnerabilities
/tools:compliance-check GDPR data handling
/tools:deps-audit check for vulnerable dependencies

🔧 Tool-Specific Examples

API Development

# Scaffold complete CRUD API
/tools:api-scaffold user management with RBAC

# Generate mock API for testing
/tools:api-mock REST endpoints for testing frontend

Database Operations

# Create migration strategy
/tools:db-migrate PostgreSQL schema changes with zero downtime

# Build data pipeline
/tools:data-pipeline ETL from MySQL to BigQuery

DevOps & Infrastructure

# Optimize containers
/tools:docker-optimize reduce image size for production

# Generate Kubernetes configs
/tools:k8s-manifest microservices with autoscaling

# Setup monitoring
/tools:monitor-setup Prometheus and Grafana dashboards

Testing & Quality

# Generate test harness
/tools:test-harness comprehensive test suite for API

# Analyze technical debt
/tools:tech-debt assess codebase quality and risks

# Refactor code
/tools:refactor-clean remove code smells and optimize

🏗️ Advanced Workflow Composition

Sequential Pipeline

# Build complete feature pipeline
/workflows:feature-development notification system
/tools:security-scan notification implementation
/workflows:performance-optimization notification delivery
/tools:docker-optimize notification service
/tools:k8s-manifest deploy notification service

Parallel Execution

# Run independent analyses simultaneously
/tools:deps-audit security vulnerabilities
/tools:tech-debt code quality assessment
/tools:security-scan OWASP compliance
/tools:accessibility-audit WCAG compliance

Context Preservation

# Save context for multi-session work
/tools:context-save architecture decisions and configs

# Later, restore context
/tools:context-restore continue from saved state

🎨 CODITECT Integration Patterns

With CODI Monitoring

# Log workflow initiation
./.codi/scripts/codi-log-ai.sh "$SESSION_ID: Starting feature workflow" "WORKFLOW_START"

# Execute workflow
/workflows:feature-development $FEATURE_DESCRIPTION

# Log completion
./.codi/scripts/codi-log-ai.sh "$SESSION_ID: Workflow complete" "WORKFLOW_COMPLETE"

With File Claims

# Check for conflicts before starting
grep "FILE_CLAIM" .codi/logs/codi-ps.log | tail -10

# Claim files for your workflow
./.codi/scripts/codi-log-ai.sh "$SESSION_ID: Claiming src/api/* for workflow" "FILE_CLAIM"

# Execute workflow with confidence
/workflows:feature-development API enhancements

With Quality Gates

# Run workflow with quality checks
/workflows:full-review validate implementation against ADRs

# The review will check:
# - Architecture compliance
# - Security standards
# - Performance requirements
# - Code quality metrics

📊 Workflow vs Tool Decision Guide

Use Workflows When	Use Tools When
Building complete features	Performing specific tasks
Need multi-domain expertise	Single domain sufficient
Problem requires analysis	Solution is well-defined
Want automated coordination	Need manual control

🚨 Common Pitfalls & Solutions

Pitfall 1: Insufficient Context

# ❌ Too vague
/workflows:feature-development add search

# ✅ Detailed context
/workflows:feature-development elasticsearch full-text search with filters, facets, and autocomplete

Pitfall 2: Wrong Tool Selection

# ❌ Using tool for complex feature
/tools:api-scaffold complete e-commerce platform

# ✅ Using workflow for orchestration
/workflows:full-stack-feature e-commerce platform with cart, checkout, inventory

Pitfall 3: Missing Prerequisites

# ❌ Jumping to deployment
/tools:k8s-manifest deploy feature

# ✅ Complete pipeline
/workflows:feature-development implement feature
/tools:test-harness verify implementation
/tools:docker-optimize containerize
/tools:k8s-manifest deploy to production

🎯 Best Practices

1. Start with Workflows for new features - let orchestration handle complexity
2. Provide Rich Context - include tech stack, constraints, requirements
3. Chain Commands Logically - build → test → optimize → deploy
4. Monitor Progress - use CODI logs to track agent activities
5. Save Context - use context-save/restore for long projects

🔄 Example: Complete Feature Cycle

# 1. Initialize session
export SESSION_ID="ORCHESTRATOR-FEATURE-DEV"
./.codi/scripts/codi-log-ai.sh "$SESSION_ID: Starting user auth feature" "SESSION_START"

# 2. Design and implement
/workflows:feature-development JWT-based authentication with refresh tokens

# 3. Security review
/tools:security-scan authentication implementation

# 4. Performance optimization
/workflows:performance-optimization optimize auth token validation

# 5. Prepare deployment
/tools:docker-optimize auth service container
/tools:k8s-manifest auth service with horizontal scaling
/tools:monitor-setup auth service metrics and alerts

# 6. Document completion
./.codi/scripts/codi-log-ai.sh "$SESSION_ID: Auth feature complete and deployed" "FEATURE_COMPLETE"

📝 Quick Reference Card

Essential Workflows

• feature-development - Complete feature implementation
• smart-fix - Intelligent problem resolution
• tdd-cycle - Test-driven development
• full-review - Comprehensive code review
• performance-optimization - System optimization

Essential Tools

• api-scaffold - Generate APIs
• test-harness - Create tests
• security-scan - Security audit
• docker-optimize - Container optimization
• k8s-manifest - Kubernetes configs

CODI Integration

• Always start monitoring first
• Log workflow activities
• Check file claims
• Coordinate with other sessions

---

Remember: Workflows orchestrate multiple agents for complex tasks, while tools provide focused utilities. Choose based on your needs and let Claude's sub-agents handle the expertise!