droid_rules/DROIDS.md

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

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

# 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

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

Examples

# 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"