# Getting Started with AI Flow Kit

This guide walks you through setting up AI Flow Kit for your first project.

## Prerequisites

- Node.js 14+ installed
- Claude Code installed (with access to Claude)
- A project you want to work on
- Optional: Jira, Backlog, or Google Sheets account (for pulling task context)

## Step 1: Install AI Flow Kit

### Global Installation (Recommended for teams)
```bash
npm install -g @relipa/ai-flow-kit
aiflow --version
```

### Local Installation
```bash
cd your-project
npm install @relipa/ai-flow-kit
npx aiflow --version
```

## Step 2: Initialize Your Project

Navigate to your project directory and run:

```bash
aiflow init
```

This will:
- Create `.claude/skills/` — AI skills for your team
- Create `.rules/` — Team coding standards
- Create `.aiflow/` — Internal configuration
- Prompt you to set framework (optional)

### With Framework & Adapter

```bash
# Full setup with framework and project management tool
aiflow init --framework laravel --adapter jira
```

**Available frameworks:**
- `laravel` — PHP/Laravel projects
- `nextjs` — Next.js (React) projects
- `vue-nuxt` — Vue/Nuxt projects

**Available adapters:**
- `jira` — Atlassian Jira
- `backlog` — Nulab Backlog
- `google-sheets` — Google Sheets for task tracking

## Step 3: Verify Setup

Check that everything is configured correctly:

```bash
aiflow doctor
```

Expected output:
```
Running health check for AI Flow Kit...

✓ .claude/skills exists
✓ .rules exists
✓ CLAUDE.md exists
✓ Version tracking active (v1.0.0)

✨ Everything looks healthy! You are ready to fly.
```

## Step 4: Your First Task

Let's walk through a complete workflow.

### Example: Fix a Bug

**1. Load the bug context:**
```bash
# From Jira
aiflow use JIRA-2024-123

# From Backlog
aiflow use BACKLOG-456

# Or just create context manually
aiflow use --manual
```

This pulls:
- Bug description
- Reproduction steps
- Acceptance criteria
- Related files/links

> [!TIP]
> **Fast Mode** is now the default. AI Flow Kit will prioritize speed and minimal Q&A so you can start coding in < 5 mins. Use `--full` if you need deep analysis.

**2. Generate a prompt:**
```bash
aiflow prompt bug-fix
```

This creates a prompt template with:
- Your bug context
- Team coding rules
- Investigation workflow
- Example solutions

**3. Use in Claude Code:**
- Copy the generated prompt
- Open Claude Code
- Paste the prompt
- Claude will auto-detect it's a bug fix and run the `investigate-bug` skill
- Follow along as Claude traces through your code

**4. After Claude fixes it:**
```bash
# Verify the fix doesn't break anything
npm test

# Review changes
git diff

# Commit when satisfied
git add .
git commit -m "fix: [JIRA-2024-123] Resolve payment processing issue"
```

## Configuration

Create `.aiflowrc.json` in your project root (optional):

```json
{
  "team": "my-team",
  "adapters": ["jira"],
  "frameworks": ["laravel"],
  "customSkills": ["investigate-bug", "impact-analysis"],
  "defaultModel": "claude-opus-4-6",
  "autoDetectTasks": true,
  "strictMode": false
}
```

See [Configuration Guide](./configuration.md) for all options.

## Next Steps

- 📖 [Read workflow examples](./workflows/)
- ⚙️ [Configure adapters](./configuration.md)
- 🎯 [Understand available tasks](./cli-reference.md)
- 🔧 [Customize for your team](./architecture.md)

## Common Tasks

### Load context from a ticket
```bash
aiflow use JIRA-123
# or
aiflow use BACKLOG-456
# or create manually
aiflow use --manual
```

### Generate a prompt for different task types
```bash
aiflow prompt bug-fix        # For fixing bugs
aiflow prompt feature        # For building features
aiflow prompt investigation  # For analyzing code
aiflow prompt refactor       # For improving code
aiflow prompt impact         # For assessing changes
```

### Update to latest version
```bash
aiflow update
# Will download latest skills and templates
```

### Switch between versions
```bash
aiflow use 1.0.0  # Use specific version
```

### Check project setup
```bash
aiflow doctor
```

## Troubleshooting

### "aiflow command not found"
```bash
# If installed globally
npm install -g @relipa/ai-flow-kit

# If installed locally
npx aiflow --version
```

### "Cannot load context from Jira"
```bash
# Verify credentials
echo $JIRA_API_TOKEN
echo $JIRA_EMAIL
echo $JIRA_DOMAIN

# Check health
aiflow doctor
```

### "CLAUDE.md not found"
```bash
# Regenerate it
aiflow init
# or with specific framework
aiflow init --framework laravel
```

See [Troubleshooting Guide](./troubleshooting.md) for more help.

## Tips for Success

1. **Use task context** — Always pull from tickets when possible. It helps Claude understand requirements.

2. **Follow the prompt template** — The generated prompt includes best practices and examples. Don't skip sections.

3. **Commit frequently** — After Claude makes changes, review and commit. Makes it easier to review and rollback.

4. **Use the right task type** — Picking the correct task type helps Claude use the right workflow.

5. **Customize rules** — Add team-specific rules in `custom/rules/`. Claude will follow them.

6. **Share with team** — Once setup, other developers just need to run `aiflow update`.

## Getting Help

- 📖 [Full Documentation](../README.md)
- 💬 [Ask a question](../issues)
- 🤝 [See how others use it](../discussions)

---

**Ready to supercharge your development?** Run `aiflow init` and start with your first task! 🚀