# Task Shepherd AI Agent

AI agent service for automated project analysis and task processing with Claude integration.

## Installation

### Option 1: Using npx (Recommended)
```bash
# No installation needed - always uses latest version
npx @task-shepherd/agent init
npx @task-shepherd/agent start
```

### Option 2: Global Install
```bash
# Install globally for permanent CLI access
npm install -g @task-shepherd/agent

# Then use directly
task-shepherd-agent init
task-shepherd-agent start
```

**Note:** `npx` is recommended as it ensures you're always using the latest version without managing global installations.

## Quick Start

### 1. Initialize Agent
```bash
task-shepherd-agent init
```

This interactive wizard will guide you through:
- Configuring your Task Shepherd organization connection
- Setting up your Claude API key
- Selecting your agent identity strategy
- Configuring ports and service settings
- Setting agent capabilities

**Before running init, you'll need:**
- **Organization ID**: From your Task Shepherd organization settings
- **API URL**: Your organization's GraphQL endpoint (e.g., `https://your-org.api.taskshepherd.com/graphql`)
- **API Key**: Generated from Task Shepherd dashboard → Settings → API Keys
- **Claude API Key**: From Anthropic Console → API Keys (starts with `sk-ant-api03-`)

### 2. Register Workspaces

After initialization, register the projects you want the agent to work on:

```bash
# Register current directory as a workspace
task-shepherd-agent workspace register

# Or register a specific directory
task-shepherd-agent workspace register --path /path/to/your/project

# Or scan common development directories automatically
task-shepherd-agent workspace scan-common

# View registered workspaces
task-shepherd-agent workspace list
```

### 3. Start Agent Service
```bash
task-shepherd-agent start
```

The agent will:
- Connect to your Task Shepherd instance
- Sync registered workspaces with the backend
- Begin polling for assigned work
- Provide analytics dashboard at http://localhost:8548

### Alternative: Environment Variables (Single Organization Only)

You can also configure the agent using environment variables for **single organization** deployments:

```bash
# Set your Task Shepherd API connection
export TASK_SHEPHERD_API_URL="https://your-org.api.taskshepherd.com/graphql"
export TASK_SHEPHERD_API_KEY="tks_your_api_key_here"

# Set your Claude API key
export CLAUDE_API_KEY="sk-ant-api03-your_claude_key_here"

# Optional: Customize ports
export PORT=8547
export WEB_PORT=8548
```

**⚠️ Note:** Environment variables only support single organization mode. For multi-organization support, use the init wizard and config file approach.

### Managing Multiple Organizations

The agent supports working with multiple Task Shepherd organizations simultaneously. After initialization:

**To add additional organizations:**

1. Edit the config file at `~/.task-shepherd-agent/config.json`
2. Add organizations to the `organizations` array:

```json
{
  "agentId": "your-agent-id",
  "organizations": [
    {
      "id": "org-1-id",
      "name": "Organization 1",
      "apiUrl": "https://org1.api.taskshepherd.com/graphql",
      "apiKey": "tks_org1_key",
      "enabled": true
    },
    {
      "id": "org-2-id",
      "name": "Organization 2",
      "apiUrl": "https://org2.api.taskshepherd.com/graphql",
      "apiKey": "tks_org2_key",
      "enabled": true
    }
  ]
}
```

3. Restart the agent: `task-shepherd-agent start`

The agent will poll all enabled organizations for work and process tasks from any of them.

## Features

### 🤖 **AI-Powered Analysis**
- Comprehensive project reviews with scoring
- Development plan generation
- Story implementation guidance
- Code quality assessment

### 📊 **Analytics Dashboard**
- Real-time performance metrics
- Token usage tracking and cost monitoring
- Success rate analytics
- Worker performance comparisons

### ⚡ **Efficient Processing**
- Lightweight in-memory queue system
- Configurable concurrency limits
- Automatic retry for failed jobs
- Real-time progress tracking

### 🔧 **Workspace Management**
- Automatic workspace discovery
- Multi-technology support (React, Node.js, Python, etc.)
- Dynamic service registration
- Flexible configuration options

## Configuration

### Environment Variables

```bash
# Required: Task Shepherd API
TASK_SHEPHERD_API_URL="https://api.taskshepherd.com/graphql"
TASK_SHEPHERD_API_KEY="tks_your_api_key"

# Required: AI Provider
CLAUDE_API_KEY="sk-ant-api03-your_key"

# Optional: Service Configuration
PORT=8547                    # Agent API port
WEB_PORT=8548               # Dashboard port
MAX_CONCURRENT_JOBS=3       # Concurrent processing limit
TOKEN_RATE_LIMIT=10000      # Daily token limit
```

### Workspace Registration

Register workspaces for the agent to process:

```bash
# Register current directory
task-shepherd-agent workspace register

# Register specific directory
task-shepherd-agent workspace register --path /path/to/project

# Scan common development directories
task-shepherd-agent workspace scan-common

# List registered workspaces
task-shepherd-agent workspace list
```

## CLI Commands

**Note:** Replace `task-shepherd-agent` with `npx @task-shepherd/agent` if using npx.

### Agent Management
```bash
task-shepherd-agent init                    # Initialize agent
task-shepherd-agent start                   # Start agent service
task-shepherd-agent status                  # Check agent status
task-shepherd-agent stop                    # Stop agent service
```

### Workspace Management
```bash
task-shepherd-agent workspace register     # Register workspace
task-shepherd-agent workspace list         # List workspaces
task-shepherd-agent workspace sync         # Sync with backend
task-shepherd-agent workspace validate     # Validate configuration
```

### Analysis Operations
```bash
task-shepherd-agent analysis start --type project_review
task-shepherd-agent analysis status --job <job-id>
task-shepherd-agent analysis list
```

## API Endpoints

When running, the agent provides these endpoints:

### Analysis Operations
```bash
# Create analysis job
POST http://localhost:8547/api/analysis
{
  "project": {
    "id": "project-123",
    "name": "My Project"
  },
  "analysisType": "project_review",
  "workspacePath": "/path/to/project"
}

# Get job status
GET http://localhost:8547/api/analysis/{jobId}

# List active jobs
GET http://localhost:8547/api/analysis
```

### Health Monitoring
```bash
# Health check
GET http://localhost:8547/api/health

# Usage statistics
GET http://localhost:8547/api/usage/stats

# Rate limits
GET http://localhost:8547/api/usage/rate-limit
```

## Analytics Dashboard

Access the web dashboard at http://localhost:8548 for:

- **Real-time Metrics**: Active jobs, queue status, success rates
- **Performance Analytics**: Completion times, throughput analysis
- **Cost Monitoring**: Token usage, API costs, efficiency metrics
- **Historical Data**: Trends, patterns, optimization insights

## Supported Analysis Types

### Project Review
Comprehensive analysis including:
- Code quality assessment
- Architecture evaluation
- Security considerations
- Performance recommendations
- Technical debt identification

### Development Plan
Strategic implementation guidance:
- Feature breakdown and prioritization
- Timeline estimation
- Risk assessment
- Resource requirements
- Technology recommendations

### Story Implementation
Detailed implementation guidance:
- Technical approach recommendations
- Code examples and patterns
- Testing strategies
- Integration considerations

## Workspace Support

The agent automatically detects and supports:

### Frontend Technologies
- React, Vue, Angular, Svelte
- TypeScript, JavaScript
- CSS frameworks (Tailwind, Bootstrap)
- Build tools (Vite, Webpack, Parcel)

### Backend Technologies
- Node.js, Python, Java, Go, Rust
- Express, FastAPI, Spring Boot
- GraphQL, REST APIs
- Database integrations

### Infrastructure
- Docker and containerization
- CI/CD pipelines
- Cloud platforms (AWS, Azure, GCP)
- Monitoring and logging

## Production Deployment

### Docker Deployment
```dockerfile
FROM node:18-alpine
RUN npm install -g @task-shepherd/agent
EXPOSE 8547 8548
CMD ["task-shepherd-agent", "start"]
```

### Environment Configuration
```bash
# Production settings
NODE_ENV=production
TASK_SHEPHERD_API_URL="https://api.taskshepherd.com/graphql"
CLAUDE_API_KEY="your-production-key"
MAX_CONCURRENT_JOBS=5
TOKEN_RATE_LIMIT=50000
```

### Health Monitoring
```bash
# Health check endpoint for load balancers
curl http://localhost:8547/api/health

# Readiness check
curl http://localhost:8547/api/ready
```

## Troubleshooting

### Connection Issues
```bash
# Test Task Shepherd API connection
curl -H "x-api-key: $TASK_SHEPHERD_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"query": "query { __typename }"}' \
     $TASK_SHEPHERD_API_URL
```

### Agent Issues
```bash
# Check agent status
task-shepherd-agent status

# Validate workspace configuration
task-shepherd-agent workspace validate

# View agent logs
tail -f ~/.task-shepherd-agent/logs/agent.log
```

### Common Solutions
- **API Key Invalid**: Verify API key in Task Shepherd dashboard
- **Claude API Issues**: Check Claude API key and quotas
- **Workspace Not Found**: Re-register workspace with correct path
- **Port Conflicts**: Change PORT environment variable

## API Key Management

Get your API keys from:
1. **Task Shepherd API Key**: Your Task Shepherd instance dashboard → Settings → API Keys
2. **Claude API Key**: Anthropic Console → API Keys

Set environment variables or use a `.env` file:
```bash
TASK_SHEPHERD_API_KEY="tks_..."
CLAUDE_API_KEY="sk-ant-api03-..."
```

## License

Proprietary software - see LICENSE.md for usage terms.

## Support

- Check agent status: `task-shepherd-agent status`
- View logs: `~/.task-shepherd-agent/logs/`
- Health check: http://localhost:8547/api/health