@task-shepherd/agent 1.0.2

package/README.md

@@ -0,0 +1,297 @@
+# Task Shepherd AI Agent
+
+AI agent service for automated project analysis and task processing with Claude integration.
+
+## Installation
+
+```bash
+npm install -g @task-shepherd/agent
+```
+
+## Quick Start
+
+### 1. Initialize Agent
+```bash
+task-shepherd-agent init
+```
+
+### 2. Configure API Connection
+```bash
+# Set your Task Shepherd API connection
+export TASK_SHEPHERD_API_URL="https://your-instance.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"
+```
+
+### 3. Start Agent Service
+```bash
+task-shepherd-agent start
+```
+
+The agent will:
+- Connect to your Task Shepherd instance
+- Register available workspaces
+- Begin processing assigned work
+- Provide analytics dashboard at http://localhost:8548
+
+## 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
+
+### 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