ai-sprint/README.md

AI-powered sprint management and SDLC tracking with automatic IDE integration

# AI Sprint

AI-powered sprint management and SDLC tracking with automatic IDE integration. Features intelligent session tracking, test reporting, and seamless BizOps Portal synchronization for Claude, Cursor, VS Code, and more.

## ✨ Features

- **🔍 IDE Auto-Detection**: Automatically detects Claude Code, Cursor, Windsurf, VS Code
- **⚡ Zero Configuration**: One command setup with intelligent defaults
- **📝 Hybrid Integration**: Use both MCP tools and IDE commands (Claude Code)
- **📊 Real-time Tracking**: Session files, git commits, test results
- **🔄 Live Synchronization**: Automatic Portal updates as you work
- **📈 Sprint Management**: Comprehensive sprint planning and tracking

## 🚀 Quick Start

### Automatic Setup (Recommended)

```bash
# Install globally
npm install -g ai-sprint

# Run setup in your project directory
ai-sprint setup
```

The setup will:
1. Detect your IDE(s) automatically
2. Configure MCP integration
3. Generate command files (for Claude Code)
4. Set up project tracking

### Manual Installation

```bash
npm install ai-sprint
```

Then add to your IDE configuration:

#### Claude Code
```json
{
  "mcpServers": {
    "ai-sprint": {
      "command": "npx",
      "args": ["ai-sprint"],
      "env": {
        "AUTO_CONFIGURE": "true",
        "IDE_TYPE": "claude"
      }
    }
  }
}
```

#### Cursor
```json
{
  "mcpServers": {
    "ai-sprint": {
      "command": "npx",
      "args": ["ai-sprint"],
      "env": {
        "AUTO_CONFIGURE": "true",
        "IDE_TYPE": "cursor"
      }
    }
  }
}
```

## 📱 IDE-Specific Features

### Claude Code
Claude Code users get both **commands** and **MCP tools**:

#### Commands (in `.claude/commands/`)
- `/session-start [type] [name]` - Start a new development session
- `/session-update [checkpoint] [notes]` - Update session progress
- `/session-end` - Complete session with metrics
- `/sprint-create [type] [name] [duration]` - Create new sprint
- `/test-report [type] [passed] [failed]` - Submit test results

#### MCP Tools
- `configure` - Set up project tracking
- `sync_sessions` - Sync all sessions to Portal
- `sync_git_history` - Sync git commits
- `submit_test_results` - Report test results
- `watch` - Start file monitoring

### Other IDEs
Use MCP tools directly through your IDE's interface.

## 🛠️ Usage

### 1. Configure the Tracker

```typescript
// Configure for your project
await configure({
  projectId: "your-project-uuid",
  projectPath: "/path/to/your/project",
  apiEndpoint: "https://portal.unblockd.com",
  apiKey: "optional-api-key",
  watchPatterns: ["sessions/*.md", "docs/sprint-*.md"]
});
```

### 2. Sync Sessions

```typescript
// Sync all session files
await sync_sessions();
```

### 3. Sync Git History

```typescript
// Sync git commits
await sync_git_history({
  branch: "main",
  since: "2024-01-01"
});
```

### 4. Submit Test Results

```typescript
// Submit test run results
await submit_test_results({
  sessionId: "session-uuid",
  testType: "unit",
  passed: 245,
  failed: 3,
  skipped: 12,
  coverage: 87.5,
  duration: 12340
});
```

### 5. Start Watching

```typescript
// Start watching for file changes
await watch();
```

## Session File Format

The tracker expects session files to follow this naming convention:
```
sessions/YYYY-MM-DD-HHMM-[type]-[descriptive-name].md
```

Where type is one of:
- `feature` - Feature development
- `bug` - Bug fixes
- `maintenance` - Maintenance tasks
- `research` - Research and investigation
- `emergency` - Emergency fixes

### Example Session File

```markdown
# Feature: Add User Authentication

## Goals
- Implement secure user authentication
- Add role-based access control
- Create login/logout UI

## Acceptance Criteria
- Users can register with email/password
- Users can login and logout
- Sessions persist across page refreshes
- Unauthorized users are redirected to login

## Test Results
- Passed: 45
- Failed: 0
- Skipped: 3
- Coverage: 92.3%

## Performance Metrics
- API Response Time: 120ms
- Page Load Time: 450ms
- Component Render Time: 35ms
```

## API Integration

The MCP server sends data to these BizOps Portal endpoints:

- `POST /api/sdlc/sessions` - Create/update sessions
- `POST /api/sdlc/git-sync` - Sync git commits
- `POST /api/sdlc/test-runs` - Submit test results
- `POST /api/sdlc/sprints` - Update sprint data

## 🔧 CLI Commands

### Setup and Configuration
```bash
# Interactive setup
ai-sprint setup

# Non-interactive setup with options
ai-sprint setup --project-id <uuid> --endpoint <url> --api-key <key> --no-interactive

# Show current configuration
ai-sprint info

# Test API connection
ai-sprint test-connection
```

### Server Management
```bash
# Start the MCP server manually
ai-sprint start

# Start with debug logging
ai-sprint start --debug
```

## 🏗️ Development

```bash
# Clone the repository
git clone https://github.com/unblockd/ai-sprint
cd ai-sprint

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev
```

### Project Structure
```
├── bin/                    # CLI executables
│   ├── ai-sprint       # Main CLI
│   └── ai-sprint-setup # Setup wizard
├── src/                   # Source code
│   ├── index.ts          # MCP server
│   ├── ide-detector.ts   # IDE detection logic
│   └── configurator.ts   # Auto-configuration
├── dist/                 # Compiled output
└── package.json         # Package configuration
```

## 🔐 Environment Variables

- `BIZOPS_API_ENDPOINT` - Portal API endpoint
- `BIZOPS_API_KEY` - API authentication key
- `PROJECT_ID` - Override project ID
- `IDE_TYPE` - Force specific IDE type
- `AUTO_CONFIGURE` - Enable auto-configuration
- `DEBUG` - Enable debug logging

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

## 📄 License

MIT - See LICENSE file for details

## 🔗 Links

- [BizOps Portal](https://portal.unblockd.com)
- [MCP Documentation](https://modelcontextprotocol.io)
- [Issue Tracker](https://github.com/unblockd/ai-sprint/issues)