agent-cli-dev

# Parallel Development with agent-cli dev

This skill teaches you how to spawn parallel AI coding agents in isolated git worktrees using the `agent-cli dev` command.

## Installation

If `agent-cli` is not available, install it first:

```bash
# Install globally
uv tool install agent-cli

# Or run directly without installing
uvx agent-cli dev new <branch-name> --agent --prompt "..."
```

## When to spawn parallel agents

Spawn separate agents when:
- Multiple independent features/tasks can be worked on in parallel
- Tasks benefit from isolation (separate branches, no conflicts)
- Large refactoring that can be split by module/component
- Test-driven development (one agent for tests, one for implementation)

Do NOT spawn when:
- Tasks are small and sequential
- Tasks have tight dependencies requiring constant coordination
- The overhead of context switching exceeds the benefit

## Core command

For short prompts:
```bash
agent-cli dev new <branch-name> --agent --prompt "Fix the login bug"
```

For longer prompts (recommended for multi-line or complex instructions):
```bash
agent-cli dev new <branch-name> --agent --prompt-file path/to/prompt.md
```

This creates:
1. A new git worktree with its own branch
2. Runs project setup (installs dependencies)
3. Saves your prompt to `.claude/TASK.md` in the worktree (for reference)
4. Opens a new terminal tab with an AI coding agent
5. Passes your prompt to the agent

**Important**: Use `--prompt-file` for prompts longer than a single line. The `--prompt` option passes text through the shell, which can cause issues with special characters (exclamation marks, dollar signs, backticks, quotes) in ZSH and other shells. Using `--prompt-file` avoids all shell quoting issues.

## Writing effective prompts for spawned agents

Spawned agents work in isolation, so prompts must be **self-contained**. Include:

1. **Clear task description**: What to implement/fix/refactor
2. **Relevant context**: File locations, patterns to follow, constrai