proffesor-for-testing__agentic-qe/docs/implementation/CI-005-007-fleet-integration.md

# Fleet Integration with Code Intelligence
**Tasks: CI-005, CI-006, CI-007**

## Summary

Integrated code intelligence auto-scan with fleet initialization wizard to check for existing knowledge graph index before spawning agents.

## Implementation

### 1. Fleet Integration Module (`/v3/src/init/fleet-integration.ts`)

Created `FleetInitEnhancer` class that:
- Checks for code intelligence index before fleet initialization
- Prompts users to run scan if index is missing (interactive mode only)
- Supports `--skip-code-scan` flag to bypass check entirely
- Provides status information for fleet agents about code intelligence availability

**Key Methods:**
- `checkCodeIntelligence()` - Main integration point, returns whether to proceed
- `runCodeIntelligenceScan()` - Reuses init wizard's scan logic
- `getStatusForAgents()` - Returns code intelligence status for agent context
- `hasCodeIntelligenceIndex()` - Checks memory.db for code-intelligence:kg entries

**Integration Patterns:**
```typescript
// Non-interactive mode with skip flag
const result = await integrateCodeIntelligence(projectRoot, {
  skipCodeScan: true,
  nonInteractive: true
});

// Interactive mode with prompt
const result = await integrateCodeIntelligence(projectRoot, {
  nonInteractive: false  // Will prompt if index missing
});
```

### 2. CLI Integration (`/v3/src/cli/index.ts`)

Added code intelligence check to `fleet init` command:

```typescript
// New --skip-code-scan flag
.option('--skip-code-scan', 'Skip code intelligence index check')

// Check runs before wizard
const ciResult = await integrateCodeIntelligence(process.cwd(), {
  skipCodeScan: options.skipCodeScan,
  nonInteractive: !options.wizard
});

// Exit if user wants to run scan first
if (!ciResult.shouldProceed) {
  // Guide user to run: aqe code-intelligence index
  return;
}
```

**Execution Modes:**

| Mode | Behavior |
|------|----------|
| `aqe fleet init` | Check index, continue without prompting |
| `aqe fleet init --wizard` | Check index, prompt if missing, offer to scan |
| `aqe fleet init --skip-code-scan` | Skip check entirely, proceed directly |
| Non-existent index (wizard) | Prompt user to scan, exit if accepted |
| Existing index | Proceed with info message about entry count |

### 3. Unit Tests (`/v3/tests/unit/init/fleet-integration.test.ts`)

Created comprehensive test suite:
- Constructor and factory function tests
- Integration flow with existing index
- Integration flow with missing index (interactive/non-interactive)
- Skip flag behavior
- Error handling (database errors, import errors)
- Status methods for agents

**Test Coverage:** 29 tests covering all integration paths

## User Experience

### With Existing Index
```
🧠 Code Intelligence Check

✓ Code intelligence index found (150 entries)

🚀 Fleet Initialization Wizard
...
```

### Missing Index (Interactive)
```
🧠 Code Intelligence Check

⚠ No code intelligence index found
Building a knowledge graph improves agent accuracy by 80%
This is a one-time operation and can be run later with:
  aqe code-intelligence index

Run code intelligence scan now? [Y/n]: y

Please run the code intelligence scan first:
  aqe code-intelligence index

Then re-run fleet init when ready.
```

### Skip Flag
```
🧠 Code Intelligence Check

Code intelligence scan skipped (--skip-code-scan flag)

Fleet Configuration
...
```

## Design Decisions

1. **Non-blocking Integration**: Fleet init continues even if index is missing (except when user explicitly requests scan)

2. **Reuse Existing Logic**: `FleetInitEnhancer` calls `InitOrchestrator.checkCodeIntelligenceIndex()` and scan logic to avoid duplication

3. **Clear User Guidance**: When index is missing, provide exact command to run (`aqe code-intelligence index`)

4. **Skip Flag Support**: Allow advanced users to bypass check for automated/CI scenarios

5. **Interactive vs Non-Interactive**: Only prompt in wizard mode (`--wizard` flag), otherwise just log status

## Integration with Init Wizard

The fleet integration reuses the existing code intelligence scanning logic from `init-wizard.ts`:
- Same database check (`code-intelligence:kg` namespace)
- Same KnowledgeGraphService indexing
- Consistent behavior across `aqe init` and `aqe fleet init`

## Files Modified

1. `/v3/src/init/fleet-integration.ts` - New module
2. `/v3/src/init/index.ts` - Export new types and functions
3. `/v3/src/cli/index.ts` - Integrate into fleet init command
4. `/v3/tests/unit/init/fleet-integration.test.ts` - New test suite

## Next Steps

- CI-008: Update CLI help documentation for --skip-code-scan flag
- Integration testing with actual fleet initialization
- Performance testing with large codebases (>10k files)

## Quality Metrics

- **Lines of Code**: ~450 (implementation + tests)
- **Test Coverage**: 29 unit tests
- **Integration Points**: 2 (fleet init command, init wizard)
- **User-Facing Flags**: 1 (`--skip-code-scan`)