a-teams/docs/USAGE-GUIDE.md

a-teams by Worksona - worksona agents and agentic teams in claude.ai. Enterprise-grade multi-agent workflow system with 60+ specialized agents, comprehensive template system, and advanced orchestration capabilities for business, technical, and research ta

# a-teams - Complete Usage Guide

**worksona agents and agentic teams in claude.ai**

A comprehensive guide to using a-teams for enterprise-grade AI agent orchestration and workflow automation.

## Table of Contents

1. [Quick Start](#quick-start)
2. [Installation](#installation)
3. [Core Concepts](#core-concepts)
4. [Basic Usage](#basic-usage)
5. [Workflow Management](#workflow-management)
6. [Agent Operations](#agent-operations)
7. [Advanced Features](#advanced-features)
8. [Configuration](#configuration)
9. [Templates & Customization](#templates--customization)
10. [Troubleshooting](#troubleshooting)
11. [Examples](#examples)

## Quick Start

### Installation
```bash
# Install globally via npm
npm install -g a-teams

# Verify installation
a-teams --version
```

### Initialize Your Project
```bash
# Initialize a-teams in your project
a-teams init

# This creates:
# - ~/.a-teams/ configuration directory
# - Default configuration files
# - Local workflow cache
# - Agent metadata storage
```

### Your First Workflow
```bash
# List available workflows
a-teams workflow --list

# Run a simple development workflow
a-teams workflow --template fullstack-development \
  --project_name "MyApp" \
  --tech_stack.frontend "React" \
  --tech_stack.backend "Node.js"
```

## Installation

### Prerequisites
- **Node.js**: Version 16.0.0 or higher
- **npm**: Version 8.0.0 or higher
- **Operating System**: macOS, Linux, or Windows

### Global Installation
```bash
# Install globally (recommended)
npm install -g a-teams

# Verify installation
a-teams --version
a-teams --help
```

### Local Installation
```bash
# Install in project
npm install a-teams

# Use with npx
npx a-teams --help
```

### Post-Installation Setup
```bash
# Initialize configuration
a-teams init

# Test installation
a-teams list
a-teams workflow --list
```

## Core Concepts

### Agents
**Agents** are specialized AI entities designed for specific tasks:
- **Software Engineering**: API development, code review, testing
- **Business Strategy**: Analysis, planning, market research
- **Infrastructure**: Cloud architecture, DevOps, security
- **Research**: Academic analysis, market intelligence, competitive research
- **AI/ML**: Model development, MLOps, data science

### Workflows
**Workflows** orchestrate multiple agents to complete complex tasks:
- **Sequential Execution**: Agents run in defined order
- **Parallel Processing**: Multiple agents work simultaneously
- **Dependency Management**: Agents can depend on outputs from others
- **Error Handling**: Robust error handling and recovery

### Templates
**Templates** ensure consistent, professional output:
- **Input Validation**: Structured input requirements
- **Output Formatting**: Standardized deliverable formats
- **Quality Standards**: Built-in quality checks
- **Customization**: Extensible and configurable

## Basic Usage

### Command Structure
```bash
a-teams <command> [options] [arguments]
```

### Core Commands

#### Project Initialization
```bash
# Initialize a-teams in current directory
a-teams init

# Initialize with specific options
a-teams init --respect-context-forge --no-merge
```

#### Agent Management
```bash
# List all available agents
a-teams list

# List agents by category
a-teams list --category software-engineering

# Show agent details
a-teams info <agent-name>

# Install agents locally
a-teams install --agent api-developer
a-teams install --all
```

#### Workflow Operations
```bash
# List available workflows
a-teams workflow --list

# Run a workflow interactively
a-teams workflow

# Run specific workflow
a-teams workflow --template <template-name>

# Check workflow status
a-teams workflow --status <workflow-id>
```

## Workflow Management

### Available Workflows

#### 1. Full-Stack Development
```bash
a-teams workflow --template fullstack-development \
  --project_name "EcommerceApp" \
  --tech_stack.frontend "React" \
  --tech_stack.backend "Node.js" \
  --tech_stack.database "PostgreSQL" \
  --features.auth "true" \
  --features.payments "stripe"
```

**Agents Used**: Project Planner, Frontend Developer, API Developer, Database Admin, Test Automator

**Deliverables**:
- Project architecture documentation
- Frontend component structure
- RESTful API implementation
- Database schema and migrations
- Comprehensive test suite
- Deployment configuration

#### 2. Elite Research Workflows

**Standard Research**:
```bash
a-teams workflow --template elite-research-standard \
  --research_topic "AI Market Trends 2024" \
  --scope "market" \
  --depth_level "standard" \
  --target_audience "executives"
```

**Deep Research**:
```bash
a-teams workflow --template elite-research-deep \
  --research_topic "Quantum Computing Applications" \
  --scope "academic" \
  --depth_requirements "exhaustive" \
  --expert_consultation "true"
```

**Agents Used**: Research Coordinator, Academic Analyst, Market Researcher, Strategy Consultant

#### 3. Cloud Infrastructure
```bash
a-teams workflow --template cloud-infrastructure \
  --provider "AWS" \
  --environment "production" \
  --auto_scaling "enabled" \
  --monitoring "comprehensive" \
  --security_level "enterprise"
```

**Agents Used**: Cloud Architect, DevOps Engineer, Security Auditor, Performance Engineer

#### 4. Business Strategy & Analysis
```bash
a-teams workflow --template consultancy-agents \
  --analysis_type "competitive" \
  --market_focus "fintech" \
  --deliverable_type "strategic_recommendations"
```

**Agents Used**: Business Analyst, Strategy Consultant, Market Researcher, Competitive Analyst

### Workflow Configuration

#### Input Parameters
Workflows accept structured input parameters:

```yaml
# Example workflow input
project_name: "MyApp"
tech_stack:
  frontend: "React"
  backend: "Node.js"
  database: "PostgreSQL"
features:
  authentication: true
  payments: "stripe"
  analytics: true
```

#### Output Generation
Workflows generate multiple output formats:
- **Markdown**: Documentation and reports
- **HTML**: Presentations and web content
- **JSON**: Structured data and configurations
- **YAML**: Configuration files
- **Code**: Infrastructure as Code (Terraform, etc.)

## Agent Operations

### Agent Categories

#### Software Engineering
```bash
# Available agents
a-teams list --category software-engineering

# Key agents:
# - api-developer: RESTful API design and implementation
# - code-reviewer: Code quality and security review
# - frontend-developer: Modern web development
# - mobile-developer: iOS and Android development
# - test-automator: Automated testing strategies
```

#### Elite Research
```bash
# Research agents
a-teams list --category elite-research

# Key agents:
# - research-coordinator: Project management and workflow orchestration
# - academic-analyst: Academic research and citation standards
# - market-researcher: Market analysis and competitive intelligence
# - deep-miner: Comprehensive data mining and analysis
```

#### Cloud Infrastructure
```bash
# Infrastructure agents
a-teams list --category cloud-infrastructure

# Key agents:
# - cloud-architect: Enterprise cloud architecture
# - devops-engineer: CI/CD and automation
# - terraform-specialist: Infrastructure as Code
# - security-auditor: Security compliance and auditing
```

### Agent Configuration

#### Metadata Structure
Each agent has associated metadata:
```json
{
  "name": "api-developer",
  "category": "software-engineering",
  "description": "RESTful API design and implementation specialist",
  "version": "1.0.0",
  "capabilities": [
    "REST API design",
    "OpenAPI documentation",
    "Node.js implementation",
    "Authentication systems"
  ],
  "dependencies": [],
  "tags": ["api", "backend", "rest", "nodejs"]
}
```

## Advanced Features

### Template Validation
```bash
# Validate all templates
a-teams validate-all

# Validate specific template
a-teams validate-templates --template api-docs.md

# Generate test suites
a-teams template-tests

# Performance testing
a-teams template-performance
```

### Custom Workflows
```bash
# Create custom workflow specification
a-teams workflow --create custom-workflow.yaml

# Example custom workflow:
```

```yaml
metadata:
  name: "custom-api-development"
  category: "development"
  description: "Custom API development workflow"
  
inputs:
  required_parameters:
    - name: "api_name"
      type: "string"
      description: "Name of the API"
    - name: "endpoints"
      type: "array"
      description: "List of API endpoints"

execution:
  required_agents:
    - "api-developer"
    - "code-reviewer"
    - "test-automator"
```

### Memory and Context Management
```bash
# View workflow memory
a-teams memory --show

# Clear workflow cache
a-teams memory --clear

# Export workflow results
a-teams export --format json --output results.json
```

## Configuration

### Global Configuration
Location: `~/.a-teams/config.json`

```json
{
  "version": "2.1.0",
  "installation_date": "2024-01-01T00:00:00.000Z",
  "default_workflow_path": "~/.a-teams/workflows",
  "agent_cache_path": "~/.a-teams/agents",
  "settings": {
    "auto_update_check": true,
    "verbose_logging": false,
    "default_output_format": "markdown",
    "max_concurrent_agents": 5,
    "timeout_minutes": 30
  }
}
```

### Project Configuration
Location: `./.a-teams/project.json`

```json
{
  "project_name": "MyProject",
  "preferred_agents": [
    "api-developer",
    "frontend-developer"
  ],
  "workflow_defaults": {
    "tech_stack": {
      "frontend": "React",
      "backend": "Node.js"
    }
  },
  "output_preferences": {
    "format": "markdown",
    "include_metadata": true
  }
}
```

### Environment Variables
```bash
# Override default paths
export A_TEAMS_CONFIG_PATH="./custom-config"
export A_TEAMS_CACHE_PATH="./custom-cache"

# Debug mode
export A_TEAMS_DEBUG=true

# Custom registry
export A_TEAMS_REGISTRY="https://custom-registry.com"
```

## Templates & Customization

### Template Structure
Templates use Handlebars syntax with custom helpers:

```handlebars
# {{project_name}} API Documentation

## Overview
{{description}}

## Endpoints
{{#each endpoints}}
### {{method}} {{path}}
{{description}}

**Parameters:**
{{#each parameters}}
- `{{name}}` ({{type}}): {{description}}
{{/each}}
{{/each}}

## Generated on {{formatDate date "YYYY-MM-DD"}}
```

### Custom Helpers
Available Handlebars helpers:

```javascript
// Date formatting
{{formatDate date "YYYY-MM-DD"}}
{{timestamp}}

// String manipulation
{{capitalize string}}
{{slugify string}}
{{truncate string 100}}

// Conditionals
{{#ifEquals value "expected"}}...{{/ifEquals}}
{{#if condition}}...{{/if}}

// Arrays and objects
{{#each array}}...{{/each}}
{{join array ", "}}
{{length array}}
```

### Creating Custom Templates
```bash
# Template location
mkdir -p workflows/templates/custom/

# Create template file
cat > workflows/templates/custom/my-template.md << 'EOF'
# {{title}}

Generated by: {{agent_name}}
Date: {{formatDate date}}

## Content
{{content}}
EOF
```

## Troubleshooting

### Common Issues

#### Installation Problems
```bash
# Clear npm cache
npm cache clean --force

# Reinstall with verbose output
npm install -g a-teams --verbose

# Check Node.js version
node --version  # Should be 16.0.0+
```

#### Permission Issues
```bash
# macOS/Linux: Fix permissions
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) ~/.a-teams

# Windows: Run as Administrator
# Right-click Command Prompt → "Run as Administrator"
```

#### Workflow Failures
```bash
# Debug mode
A_TEAMS_DEBUG=true a-teams workflow --template <template>

# Check logs
cat ~/.a-teams/logs/latest.log

# Validate templates
a-teams validate-all
```

#### Agent Not Found
```bash
# Refresh agent cache
a-teams install --refresh

# List available agents
a-teams list --all

# Check agent exists
a-teams info <agent-name>
```

### Debug Commands
```bash
# System information
a-teams --version
a-teams info --system

# Configuration check
a-teams config --show
a-teams config --validate

# Cache management
a-teams cache --clear
a-teams cache --rebuild
```

### Getting Help
```bash
# General help
a-teams --help

# Command-specific help
a-teams workflow --help
a-teams list --help

# Verbose output
a-teams --verbose <command>
```

## Examples

### Example 1: E-commerce Development
```bash
# Complete e-commerce application
a-teams workflow --template fullstack-development \
  --project_name "ShopApp" \
  --tech_stack.frontend "React" \
  --tech_stack.backend "Node.js" \
  --tech_stack.database "PostgreSQL" \
  --features.auth "firebase" \
  --features.payments "stripe" \
  --features.analytics "google"

# Outputs:
# - Project architecture documentation
# - React component library
# - Node.js API with authentication
# - PostgreSQL database schema
# - Payment integration code
# - Analytics tracking setup
# - Deployment configuration
```

### Example 2: Market Research Project
```bash
# Comprehensive market analysis
a-teams workflow --template elite-research-standard \
  --research_topic "SaaS Market Trends 2024" \
  --scope "market" \
  --depth_level "comprehensive" \
  --target_audience "investors" \
  --budget_range "enterprise"

# Outputs:
# - Executive summary (5-10 pages)
# - Detailed market analysis (20-30 pages)
# - Competitive landscape report
# - Industry trend analysis
# - Investment recommendations
# - Data validation report
```

### Example 3: Cloud Infrastructure Setup
```bash
# Production AWS infrastructure
a-teams workflow --template cloud-infrastructure \
  --provider "AWS" \
  --environment "production" \
  --auto_scaling "enabled" \
  --load_balancer "application" \
  --database "rds_postgresql" \
  --monitoring "cloudwatch_prometheus" \
  --security_level "enterprise"

# Outputs:
# - Terraform infrastructure code
# - CloudFormation templates
# - Monitoring configuration (Prometheus/Grafana)
# - Security group configurations
# - Auto-scaling policies
# - Deployment scripts
# - Operations runbook
```

### Example 4: AI/ML Pipeline Development
```bash
# Machine learning project setup
a-teams workflow --template programming-languages \
  --language "python" \
  --project_type "ml_pipeline" \
  --ml_framework "tensorflow" \
  --deployment_target "kubernetes" \
  --data_sources "postgresql,s3"

# Outputs:
# - Python project structure
# - ML pipeline code (training, inference)
# - Docker containers
# - Kubernetes deployment manifests
# - Data pipeline configuration
# - Model versioning setup
# - Monitoring and logging
```

### Example 5: Security Assessment
```bash
# Comprehensive security audit
a-teams workflow --template security-operations \
  --assessment_type "comprehensive" \
  --target_systems "web_app,api,database" \
  --compliance_frameworks "sox,gdpr" \
  --penetration_testing "true"

# Outputs:
# - Security assessment report
# - Vulnerability analysis
# - Compliance checklist
# - Remediation recommendations
# - Security policy templates
# - Incident response procedures
```

## Advanced Workflows

### Multi-Stage Development Pipeline
```bash
# Stage 1: Planning and Architecture
a-teams workflow --template software-architecture \
  --project_type "microservices" \
  --scalability_requirements "high" \
  --team_size "10-15"

# Stage 2: Implementation
a-teams workflow --template fullstack-development \
  --architecture_input "stage1_output.json"

# Stage 3: Quality Assurance
a-teams workflow --template quality-assurance \
  --code_base "./src" \
  --test_coverage_target "90"

# Stage 4: Deployment
a-teams workflow --template devops-automation \
  --deployment_strategy "blue_green" \
  --monitoring_level "comprehensive"
```

### Research and Business Intelligence
```bash
# Market Intelligence Pipeline
a-teams workflow --template elite-research-deep \
  --research_topic "Fintech Innovation Trends" \
  --scope "comprehensive" \
  --expert_consultation "true" \
  --competitive_analysis "true"

# Business Strategy Development
a-teams workflow --template consultancy-agents \
  --strategy_type "market_entry" \
  --target_market "europe" \
  --timeline "12_months"

# Executive Presentation
a-teams workflow --template business-intelligence \
  --presentation_type "board_meeting" \
  --audience "executives" \
  --format "interactive"
```

---

## Support and Community

- **GitHub Repository**: https://github.com/worksona/a-teams
- **npm Package**: https://www.npmjs.com/package/a-teams
- **Documentation**: Complete guides in `/docs` folder
- **Issues**: Report bugs and feature requests on GitHub
- **Discussions**: Community discussions and Q&A

## License

MIT License - see LICENSE file for details.

---

**a-teams by Worksona** - Empowering teams with intelligent AI automation.