# Configuration Guide

Configure AI Flow Kit for your team's specific needs.

## Configuration Levels

### 1. Global Config (`~/.claude/ai-flow-kit.json`)

User-level settings, applied to all projects.

```json
{
  "defaultModel": "claude-opus-4-6",
  "globalSkills": ["investigate-bug"],
  "cacheContexts": true,
  "contextCachePath": "~/.claude/ai-flow-kit/context-cache"
}
```

### 2. Project Config (`.aiflowrc.json`)

Team-level settings, applied to this project. **Recommended to commit to git.**

```json
{
  "team": "engineering-team",
  "description": "Configuration for engineering team projects",
  
  "adapters": ["jira", "google-sheets"],
  "frameworks": ["laravel"],
  "customSkills": ["investigate-bug", "impact-analysis"],
  
  "defaultModel": "claude-opus-4-6",
  "autoDetectTasks": true,
  "strictMode": false,
  
  "contextTemplate": "standard",
  "prompting": {
    "language": "english",
    "detail": "comprehensive"
  },
  
  "mcp": {
    "timeout": 30000,
    "retries": 3,
    "fallback": "manual"
  },
  
  "validation": {
    "enabled": true,
    "ruleSet": "default"
  }
}
```

### 3. Local State (`.aiflow/state.json`)

Auto-generated, not recommended to edit manually.

```json
{
  "current_version": "1.0.0",
  "current_context": "JIRA-123",
  "installed_adapters": ["jira"],
  "last_update": "2024-04-03T10:00:00Z"
}
```

## Configuration Options

### Team Settings

```json
{
  "team": "my-team",
  "description": "Team name and description"
}
```

### Adapter Configuration

```json
{
  "adapters": ["jira", "backlog", "google-sheets"],
  
  "mcp": {
    "timeout": 30000,              // MCP call timeout in ms
    "retries": 3,                  // Retry failed calls
    "fallback": "manual"           // Use manual entry if MCP fails
  },
  
  "jira": {
    "domain": "your-company",      // For auto-construction
    "project": "DEFAULT"           // Default project
  },
  
  "backlog": {
    "spaceKey": "your-space"
  }
}
```

### Framework Configuration

```json
{
  "frameworks": ["laravel", "nextjs"],
  "defaultFramework": "laravel",
  
  "laravel": {
    "phpVersion": "8.3",
    "testFramework": "pest"
  },
  
  "nextjs": {
    "reactVersion": "18",
    "styleFramework": "tailwind"
  }
}
```

### Skills Configuration

```json
{
  "customSkills": ["investigate-bug", "impact-analysis"],
  
  "skillConfig": {
    "investigate-bug": {
      "traceDepth": "full",
      "includeGitBlame": true,
      "suggestSolutions": true
    },
    
    "impact-analysis": {
      "analyzeDeepDependencies": true,
      "suggestTests": true
    }
  }
}
```

### AI Model Configuration

```json
{
  "defaultModel": "claude-opus-4-6",
  
  "modelFallback": [
    "claude-opus-4-6",
    "claude-sonnet-4-6",
    "claude-haiku-4-5"
  ],
  
  "modelConfig": {
    "temperature": 0.7,
    "maxTokens": 8000,
    "topP": 1.0
  }
}
```

### Task Detection Configuration

```json
{
  "autoDetectTasks": true,
  
  "detection": {
    "confidence_threshold": 0.8,    // Minimum confidence to auto-detect
    "fallback": "ask",              // "ask" or "generic"
    "debug": false                  // Log detection reasoning
  },
  
  "taskTypes": {
    "bug-fix": {
      "keywords": ["bug", "error", "broken", "crash"],
      "icon": "🐛"
    },
    
    "feature": {
      "keywords": ["add", "create", "build", "new"],
      "icon": "✨"
    },
    
    "refactor": {
      "keywords": ["improve", "optimize", "refactor"],
      "icon": "♻️"
    },
    
    "investigation": {
      "keywords": ["analyze", "investigate", "understand"],
      "icon": "🔍"
    }
  }
}
```

### Context Configuration

```json
{
  "contextTemplate": "standard",   // "standard", "minimal", "comprehensive"
  
  "context": {
    "includeGitHistory": true,
    "includeFileTree": true,
    "maxFileSize": 1000000,        // 1MB max per file
    "cacheContexts": true,
    "cacheTTL": 86400              // 24 hours
  }
}
```

### Prompting Configuration

```json
{
  "prompting": {
    "language": "english",         // "english", "vietnamese", etc
    "detail": "comprehensive",     // "minimal", "standard", "comprehensive"
    "examples": true,              // Include code examples
    "bestPractices": true,         // Include team best practices
    "warningLevel": "medium"       // "low", "medium", "high"
  }
}
```

### Validation Configuration

```json
{
  "validation": {
    "enabled": true,
    "ruleSet": "default",          // or "strict", "custom"
    "autoFix": false,
    "reportLevel": "warning"       // "warning" or "error"
  },
  
  "validationRules": {
    "codeStyle": true,
    "naming": true,
    "performance": true,
    "security": true,
    "testing": false
  }
}
```

### Memory Configuration

```json
{
  "memory": {
    "enabled": true,
    "autoLoadRelevant": true,
    "maxMemorySize": 1000000,
    "persistPath": ".aiflow/memory"
  }
}
```

### Strict Mode

When `"strictMode": true`, AI Flow Kit will:
- Require explicit confirmation for risky changes
- Enforce all validation rules
- Require full test coverage
- Enforce strict code standards

```json
{
  "strictMode": true,
  
  "strictModeRules": {
    "requireTests": true,
    "requireDocumentation": true,
    "requireReview": false,
    "autoCommit": false
  }
}
```

## Example Configurations

### Startup Configuration (Minimal)
```json
{
  "team": "startup",
  "adapters": ["google-sheets"],
  "frameworks": ["nextjs"],
  "autoDetectTasks": true,
  "strictMode": false
}
```

### Enterprise Configuration (Strict)
```json
{
  "team": "enterprise-backend",
  "adapters": ["jira", "google-sheets"],
  "frameworks": ["laravel"],
  "customSkills": ["investigate-bug", "impact-analysis", "generate-spec"],
  
  "defaultModel": "claude-opus-4-6",
  "autoDetectTasks": true,
  "strictMode": true,
  
  "validation": {
    "enabled": true,
    "ruleSet": "strict"
  },
  
  "strictModeRules": {
    "requireTests": true,
    "requireDocumentation": true,
    "requireReview": true,
    "autoCommit": false
  }
}
```

### API/Backend Configuration
```json
{
  "team": "api-team",
  "frameworks": ["laravel"],
  "customSkills": ["investigate-bug", "impact-analysis"],
  
  "prompting": {
    "detail": "comprehensive"
  },
  
  "validationRules": {
    "security": true,
    "performance": true,
    "testing": true
  }
}
```

### Frontend Configuration
```json
{
  "team": "frontend-team",
  "frameworks": ["nextjs"],
  
  "prompting": {
    "examples": true
  },
  
  "validationRules": {
    "performance": true,
    "accessibility": true,
    "styling": true
  }
}
```

## Overriding Configuration

Priority order (highest to lowest):
1. **Environment variables** — `AIFLOW_*`
2. **Local flags** — `aiflow prompt --model claude-opus-4-6`
3. **Project config** — `.aiflowrc.json`
4. **Global config** — `~/.claude/ai-flow-kit.json`
5. **Defaults** — Built-in defaults

### Environment Variables

```bash
# Override model
export AIFLOW_MODEL=claude-opus-4-6

# Override adapters
export AIFLOW_ADAPTERS=jira,google-sheets

# Enable debug
export AIFLOW_DEBUG=true

# Custom context path
export AIFLOW_CONTEXT_PATH=/custom/path
```

## Tips

1. **Commit `.aiflowrc.json`** — Makes it easy to onboard new team members
2. **Don't commit global config** — It's user-specific
3. **Use environment variables for secrets** — MCP credentials should be in env
4. **Version your config** — If you make significant changes, increment version
5. **Test config** — Run `aiflow doctor` to validate

## Troubleshooting

**Q: Changes not taking effect?**
```bash
# Check current config
aiflow doctor

# Reload config
aiflow update
```

**Q: Unsure what config to use?**
```bash
# Create recommended config for your stack
aiflow init --framework laravel --adapter jira
```

---

See [Architecture Guide](./architecture.md) for how configuration is used.