# Getting Started with Handoff

Welcome to Handoff! This guide will help you set up and start using Handoff to create persistent AI collaboration in your projects.

## What is Handoff?

Handoff is an AI collaboration framework that creates a persistent knowledge base for your projects. Instead of re-explaining your codebase to AI assistants every time, Handoff maintains institutional memory that enables consistent, intelligent collaboration.

## Quick Setup

### 1. Install Handoff

```bash
# Install globally
npm install -g handoff

# Or use directly with npx (quick start)
npx handoff-ai start
```

### 2. Initialize in Your Project

```bash
cd your-project
handoff init
```

This creates a `.project` folder with:
- Configuration files for AI interaction preferences
- Structured workflows (EPICs) for different tasks
- Templates for documenting assumptions and decisions

### 3. Configure Your Preferences

```bash
handoff config
```

Choose your:
- **Engagement Level**: How much you want to collaborate vs. let AI work autonomously
- **Expertise Level**: Your technical background (affects how AI explains things)
- **Review Frequency**: How often you want to approve AI decisions

### 4. Start Collaborating

Tell any AI assistant:
```
"Check my .project folder and help me implement user authentication using medium-engagement mode"
```

The AI will automatically understand your project structure, follow your established patterns, and work at your preferred collaboration level.

## Understanding Engagement Levels

### 🤝 High Engagement (Collaborative)
- **Best for**: Complex features, learning, critical systems
- **Process**: Detailed discussions, step-by-step reviews, collaborative decision-making
- **Time**: Higher time investment, maximum control

### 🎯 Medium Engagement (Guided)
- **Best for**: Standard features, busy schedules, established patterns
- **Process**: AI proposes approaches, you approve key decisions
- **Time**: Moderate time investment, good balance of control and efficiency

### 🚀 Auto-Pilot (Autonomous)
- **Best for**: Simple tasks, tight deadlines, well-defined requirements
- **Process**: AI handles everything, documents all assumptions for later review
- **Time**: Minimal time investment, maximum efficiency

## Core Concepts

### EPICs (Structured Workflows)
Handoff includes pre-built workflows for common development tasks:

- **Collaborative Documentation**: Generate comprehensive project docs
- **Feature Implementation**: Build new features following established patterns
- **Codebase Improvement**: Refactor, test, and enhance existing code
- **Codebase Exploration**: Understand unfamiliar codebases

### Assumption Tracking
When you're not available to provide input, AI documents its assumptions in `.project/assumptions.md`. You can review and correct these later, ensuring consistency across sessions.

### Persistent Knowledge
All decisions, patterns, and architectural choices are preserved in your `.project` folder, creating institutional memory that survives team changes and project handoffs.

## Your First Handoff Session

1. **Initialize Handoff** in your project
2. **Configure your preferences** with `handoff config`
3. **Choose a task** you want AI help with
4. **Tell your AI assistant**: "Use the collaborative documentation EPIC to help me document this codebase"
5. **Follow the structured workflow** - AI will guide you through the process

## Example Workflows

### Documenting a New Project
```
You: "Use medium-engagement mode to document this React project"
AI: "I see you're using React with TypeScript and Tailwind. I'll analyze your component structure and create documentation following your established patterns. Should I focus on the component architecture first?"
```

### Implementing a Feature
```
You: "Help me add user authentication using auto-pilot mode"
AI: "Based on your existing patterns, I'll implement JWT-based auth with your current error handling approach. I'm documenting all decisions in assumptions.md for your review."
```

### Exploring Unknown Code
```
You: "Use the codebase exploration EPIC to help me understand this legacy system"
AI: "I'll systematically analyze this codebase and create documentation. Starting with the overall architecture, then diving into specific components..."
```

## New Features (v0.1.2)

### 🧪 Smart Testing Guidelines
Handoff now includes built-in testing guidelines that prevent common issues:

```
✅ AI will use: yarn test:ci, npm run test:run, yarn build
❌ AI avoids: yarn test, npm start, yarn dev (these hang or need browser control)
```

**For browser testing**, AI is guided to use automated tools like Playwright or Cypress instead of trying to manually test in browsers.

### 📝 Automatic Documentation Sync
Every EPIC workflow now includes a final documentation sync phase that ensures:
- Project documentation stays current with code changes
- New patterns and decisions are preserved
- Knowledge is ready for the next developer or AI session

**Example Documentation Sync:**
```
AI: "I've completed the feature implementation. Now I'm updating the documentation:
- ✅ Updated API docs for new endpoints
- ✅ Added new component patterns to architecture docs  
- ✅ Updated golden paths for the new user flow
- ✅ Logged implementation decisions in assumptions
Ready for PR review!"
```

## Best Practices

### For Teams
- **Standardize engagement levels** across team members
- **Review assumptions regularly** to maintain consistency
- **Update configurations** as project complexity changes
- **Use Handoff for onboarding** new team members
- **Leverage documentation sync** to keep knowledge current across feature branches

### For Solo Developers
- **Start with medium-engagement** to find your preferred balance
- **Use auto-pilot for routine tasks** to save time
- **Switch to high-engagement for learning** new concepts
- **Review assumptions periodically** to catch any misunderstandings
- **Trust the documentation sync** to maintain project knowledge

### For AI Collaboration
- **Be specific about engagement levels** when starting tasks
- **Reference existing patterns** by mentioning similar implementations
- **Ask AI to explain its reasoning** when decisions seem unclear
- **Update your configuration** as you learn what works best
- **Let AI handle testing commands** - it knows which ones to avoid

## Troubleshooting

### AI Doesn't Understand My Project
- Check that `.project/ai-quick-start.md` has accurate project information
- Update your project description and current focus
- Add specific architectural constraints to your configuration

### AI Makes Wrong Assumptions
- Review `.project/assumptions.md` and correct any errors
- Update your engagement level to get more input opportunities
- Add specific guidance to your configuration file

### Inconsistent AI Behavior
- Ensure all team members are using the same Handoff configuration
- Check that assumptions are being documented and reviewed
- Consider using higher engagement levels for critical decisions

## Next Steps

- [Configuration Options](configuration.md) - Detailed configuration guide
- [Available EPICs](epics.md) - All structured workflows
- [Integration Examples](examples.md) - Real-world usage examples
- [CLI Reference](cli.md) - Complete command reference

## Getting Help

- **GitHub Issues**: Report bugs or request features
- **Discussions**: Ask questions and share experiences
- **Examples**: Check out real projects using Handoff

Welcome to more efficient AI collaboration! 🚀