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 --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 "analyze the codebase structure"

# With file input
droid exec -f prompt.txt

# With specific model
droid exec --model custom:kimi-k2.5 "explore the project"

# Low autonomy - safe file operations
droid exec --auto low "add JSDoc comments"

# Medium autonomy - development tasks
droid exec --auto medium "install deps and run tests"

# High autonomy - production operations
droid exec --auto high "fix, test, commit and push"

Available Models (BYOK)

Model ID	Name	Reasoning
custom:kimi-k2.5	Kimi K2.5	Yes
custom:claude-opus-4.6	Claude 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:claude-opus-4-6	Code review and bug finding	high
Runner	custom:kimi-k2.5	Build, test, and execution	high

Workflow

1. Start with a good instruction follower (custom:kimi-k2.5 or custom:gpt-5.3-codex)
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:claude-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 "fix the bug"

Examples

# Analysis (read-only)
droid exec "Review the codebase for security vulnerabilities"

# Documentation
droid exec --auto low "add JSDoc comments to all functions"
droid exec --auto low "fix typos in README.md"

# Development
droid exec --auto medium "install deps, run tests, fix issues"
droid exec --auto medium "update packages and resolve conflicts"

# Production
droid exec --auto high "fix bug, test, commit, and push to main"
droid exec --auto high "deploy to staging after running tests"

# Continue session
droid exec -s <session-id> "continue previous task"