# Factory Droids

A system for orchestrating AI droids to handle complex coding tasks through specialized roles.

## Overview

Factory Droids uses `droid exec` to run AI agents non-interactively, each specializing in different aspects of software development.

## Available Commands

```bash
droid exec --help              # Show exec command options (includes model list)
droid --help                   # Show all droid commands
droid exec --model custom:Kimi-K2.5 --list-tools  # List available tools for a model
```

> **Tip:** Run `droid exec --help` to see all available models including BYOK custom models.

## Quick Start

```bash
# Read-only analysis (default)
droid exec --model custom:Kimi-K2.5 "analyze the codebase structure"

# With file input
droid exec --model custom:Kimi-K2.5 -f prompt.txt

# With specific model
droid exec --model custom:Kimi-K2.5 "explore the project"

# Low autonomy - safe file operations
droid exec --model custom:Kimi-K2.5 --auto low "add JSDoc comments"

# Medium autonomy - development tasks
droid exec --model custom:Kimi-K2.5 --auto medium "install deps and run tests"

# High autonomy - production operations
droid exec --model custom:Kimi-K2.5 --auto high "fix, test, commit and push"
```

## Available Models (BYOK)

| Model ID                          | Name                 | Reasoning |
|-----------------------------------|----------------------|-----------|
| `custom:Kimi-K2.5`                | Kimi K2.5            | Yes       |
| `custom:Opus-4.6`                 | Opus 4.6             | Yes       |
| `custom:Gpt-5.3-Codex`            | Gpt 5.3 Codex        | Yes       |
| `custom:Gpt-5.2`                  | Gpt 5.2              | Yes       |

## Droid Roles

| Droid      | Model                         | Purpose                               | Auto Level |
|------------|-------------------------------|---------------------------------------|------------|
| Explorer   | `custom:Kimi-K2.5`            | Code exploration and research         | high       |
| Spec       | `custom:Gpt-5.2`              | Planning and specification generation | high       |
| Coder      | `custom:Gpt-5.3-Codex`        | Large code generation                 | high       |
| Coder-lite | `custom:Kimi-K2.5`            | Small code generation and fixes       | high       |
| Quality    | `custom:Kimi-K2.5`            | Formatting, linting, type checking    | high       |
| Reviewer   | `custom:Opus-4.6`             | Code review and bug finding           | high       |
| Runner     | `custom:Kimi-K2.5`            | Build, test, and execution            | high       |

## Workflow

1. **Start** with `custom:Kimi-K2.5` as the driver and entrypoint
2. **Make** a todo list
3. **Explore** - Launch multiple explorer droids with `custom:Kimi-K2.5` in parallel
4. **Spec** - Evaluate context with spec droid using `custom:Gpt-5.2`
5. **Confirm** spec with user
6. **Code** - Use `custom:Gpt-5.3-Codex` for large code gen, `custom:Kimi-K2.5` for small
7. **Quality** - Run quality check droid with `custom:Kimi-K2.5 --auto high`
8. **Review** - Run review droid with `custom:Opus-4.6 --auto high`
9. **Run** - Run build/test droid with `custom:Kimi-K2.5 --auto high`
10. **Summarize** - Provide final summary

## Autonomy Levels

| Level   | Flag           | Description                                           |
|---------|----------------|-------------------------------------------------------|
| Default | (none)         | Read-only - safest for reviewing planned changes      |
| Low     | `--auto low`   | Basic file operations, no system changes              |
| Medium  | `--auto medium`| Development ops - install packages, build, git local  |
| High    | `--auto high`  | Production ops - git push, deploy, migrations         |
| Unsafe  | `--skip-permissions-unsafe` | Bypass all checks - DANGEROUS!         |

## Command Options

```
Usage: droid exec [options] [prompt]

Arguments:
  prompt                      The prompt to execute

Options:
  -o, --output-format <format>    Output format (default: "text")
  --input-format <format>         Input format: stream-json for multi-turn
  -f, --file <path>               Read prompt from file
  --auto <level>                  Autonomy level: low|medium|high
  --skip-permissions-unsafe       Skip ALL permission checks (unsafe)
  -s, --session-id <id>           Existing session to continue
  -m, --model <id>                Model ID (default: claude-opus-4-5-20251101)
  -r, --reasoning-effort <level>  Reasoning effort (model-specific)
  --enabled-tools <ids>           Enable specific tools
  --disabled-tools <ids>          Disable specific tools
  --cwd <path>                    Working directory path
  --log-group-id <id>             Log group ID for filtering logs
  --list-tools                    List available tools and exit
  -h, --help                      Display help
```

## Authentication

Create API key: https://app.factory.ai/settings/api-keys

```bash
export FACTORY_API_KEY=fk-... && droid exec --model custom:Kimi-K2.5 "fix the bug"
```

## Examples

```bash
# Analysis (read-only)
droid exec --model custom:Kimi-K2.5 "Review the codebase for security vulnerabilities"

# Documentation
droid exec --model custom:Kimi-K2.5 --auto low "add JSDoc comments to all functions"
droid exec --model custom:Kimi-K2.5 --auto low "fix typos in README.md"

# Development
droid exec --model custom:Kimi-K2.5 --auto medium "install deps, run tests, fix issues"
droid exec --model custom:Kimi-K2.5 --auto medium "update packages and resolve conflicts"

# Production
droid exec --model custom:Kimi-K2.5 --auto high "fix bug, test, commit, and push to main"
droid exec --model custom:Kimi-K2.5 --auto high "deploy to staging after running tests"

# Continue session
droid exec -s <session-id> --model custom:Kimi-K2.5 "continue previous task"
```