From 263b3c3bb2d4dd7c438e7f24e196da6ab4922fc1 Mon Sep 17 00:00:00 2001
From: edgar <edgarpavlovsky@users.noreply.github.com>
Date: Wed, 21 Jan 2026 18:43:10 -0700
Subject: [PATCH] Reorient Fireteam from library-first to CLI-first

- Fix prog="fireteam" in CLI help text
- Default --project-dir to current directory (was required)
- Rewrite README with CLI-first framing, library usage as secondary
- Update all docs to use CLI examples instead of library examples
- Update installation instructions to use pipx/uv tool install

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 README.md                        | 265 ++++++++++++++-----------------
 docs/README.md                   |  25 ++-
 docs/cli-runner.md               | 140 +++++++---------
 docs/concepts/complexity.md      |  49 +++---
 docs/concepts/execution-modes.md |  69 ++------
 docs/introduction.md             |  45 +++---
 docs/quickstart.md               | 210 +++++++++++-------------
 src/runner.py                    |  30 ++--
 8 files changed, 353 insertions(+), 480 deletions(-)

diff --git a/README.md b/README.md
index 6be901f..47fadf6 100644
--- a/README.md
+++ b/README.md
@@ -1,208 +1,177 @@
 # Fireteam
 
-Adaptive task execution using Claude Code CLI with complexity-based routing and loop-until-complete behavior.
-
-## Overview
-
-Fireteam estimates task complexity and routes to the appropriate execution strategy:
-
-| Complexity | Mode | Behavior |
-|------------|------|----------|
-| TRIVIAL | SINGLE_TURN | Direct execution, single pass |
-| SIMPLE | SINGLE_TURN | Direct execution, single pass |
-| MODERATE | MODERATE | Execute -> review loop until >95% complete |
-| COMPLEX | FULL | Plan once, then execute -> 3 parallel reviews loop until 2/3 say >95% |
+Autonomous task execution with Claude. Give it a goal, let it run until complete.
 
 ## Installation
 
 ```bash
-uv add fireteam
+# Install as a CLI tool
+pipx install fireteam
+# or
+uv tool install fireteam
 ```
 
-Requires Python 3.12+ and Claude Code CLI installed.
+Requires Python 3.12+ and [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed.
 
-## Usage
+## Quick Start
 
-### Basic Usage
+1. Create a `PROMPT.md` file in your project:
 
-```python
-from fireteam import execute
+```markdown
+# Task
 
-result = await execute(
-    project_dir="/path/to/project",
-    goal="Fix the bug in auth.py",
-    context="Error logs: NullPointerException at line 42",
-)
+Fix the authentication bug where users can't log in after password reset.
 
-if result.success:
-    print(f"Completed in {result.iterations} iterations")
-    print(f"Completion: {result.completion_percentage}%")
-else:
-    print(f"Failed: {result.error}")
+## Context
+
+@src/auth.py
+@tests/test_auth.py
 ```
 
-### Specify Execution Mode
+2. Run Fireteam:
 
-```python
-from fireteam import execute, ExecutionMode
+```bash
+# Start a background session (tmux)
+fireteam start
 
-# Force full mode with planning and parallel reviews
-# Loops infinitely until complete (default)
-result = await execute(
-    project_dir="/path/to/project",
-    goal="Refactor the authentication module",
-    mode=ExecutionMode.FULL,
-)
+# Or run in foreground
+fireteam run
+```
 
-# Or limit iterations if needed
-result = await execute(
-    project_dir="/path/to/project",
-    goal="Refactor the authentication module",
-    mode=ExecutionMode.FULL,
-    max_iterations=10,  # Stop after 10 iterations if not complete
-)
+3. Monitor progress:
+
+```bash
+# List running sessions
+fireteam list
+
+# Attach to watch live
+fireteam attach fireteam-myproject
+
+# View logs
+fireteam logs fireteam-myproject
 ```
 
-### Complexity Estimation
+## How It Works
 
-```python
-from fireteam import estimate_complexity, ComplexityLevel
+Fireteam estimates task complexity and routes to the appropriate execution strategy:
 
-# Quick estimation (no codebase access)
-complexity = await estimate_complexity(
-    goal="Add logging to the auth module",
-    context="Existing logging in other modules uses Python logging",
-)
+| Complexity | Mode | Behavior |
+|------------|------|----------|
+| TRIVIAL | SINGLE_TURN | Direct execution, single pass |
+| SIMPLE | SINGLE_TURN | Direct execution, single pass |
+| MODERATE | MODERATE | Execute → review loop until ≥95% complete |
+| COMPLEX | FULL | Plan once, then execute → 3 parallel reviews until 2/3 say ≥95% |
 
-# Accurate estimation with codebase exploration
-# Claude uses Glob, Grep, Read to understand the project
-complexity = await estimate_complexity(
-    goal="Refactor the authentication system",
-    project_dir="/path/to/project",
-)
+It loops until the task is complete—no babysitting required.
 
-print(f"Estimated complexity: {complexity}")
-# ComplexityLevel.MODERATE -> routes to MODERATE mode
-```
+## CLI Reference
 
-## Execution Modes
+### `fireteam start`
 
-### SINGLE_TURN
-For trivial and simple tasks. Single CLI call, no review loop.
+Start a background session in tmux:
 
-### MODERATE
-For moderate tasks requiring validation:
-```
-while not complete:
-    execute()
-    completion = review()
-    if completion >= 95%:
-        complete = True
+```bash
+fireteam start                           # Use PROMPT.md in current directory
+fireteam start -p /path/to/project       # Specify project directory
+fireteam start -f task.md                # Use specific goal file
+fireteam start -g "Fix the bug"          # Pass goal as string
+fireteam start -m full                   # Force execution mode
+fireteam start --max-iterations 10       # Limit iterations
 ```
-Loops **indefinitely** until a single reviewer says >95% complete. Set `max_iterations` to limit.
 
-### FULL
-For complex tasks requiring planning and consensus:
-```
-plan()  # Once at start
-while not complete:
-    execute()
-    reviews = run_3_parallel_reviewers()
-    if 2 of 3 say >= 95%:
-        complete = True
+### `fireteam run`
+
+Run in foreground (blocking):
+
+```bash
+fireteam run                             # Use PROMPT.md in current directory
+fireteam run -p /path/to/project         # Specify project directory
 ```
-Plans once, then loops **indefinitely** until majority (2/3) consensus. Set `max_iterations` to limit.
 
-## API Reference
+### `fireteam list`
 
-### `execute()`
+List all running Fireteam sessions.
 
-```python
-async def execute(
-    project_dir: str | Path,
-    goal: str,
-    context: str = "",
-    mode: ExecutionMode | None = None,  # Auto-detect if None
-    max_iterations: int | None = None,  # None = infinite (default)
-) -> ExecutionResult
-```
+### `fireteam attach <session>`
 
-### `ExecutionResult`
+Attach to a running session to watch progress. Detach with `Ctrl+B D`.
 
-```python
-@dataclass
-class ExecutionResult:
-    success: bool
-    mode: ExecutionMode
-    output: str | None = None
-    error: str | None = None
-    completion_percentage: int = 0
-    iterations: int = 0
-    metadata: dict = field(default_factory=dict)
+### `fireteam logs <session>`
+
+View session logs:
+
+```bash
+fireteam logs fireteam-myproject         # Last 50 lines
+fireteam logs fireteam-myproject -n 200  # Last 200 lines
 ```
 
-### `estimate_complexity()`
+### `fireteam kill <session>`
 
-```python
-async def estimate_complexity(
-    goal: str,
-    context: str = "",
-    project_dir: str | Path | None = None,  # Enables codebase exploration
-) -> ComplexityLevel
+Terminate a running session.
+
+## PROMPT.md Format
+
+Fireteam auto-detects `PROMPT.md` (or `fireteam.prompt.md`, `prompt.md`) in your project directory. Use `@` syntax to include files:
+
+```markdown
+# Task
+
+Refactor the authentication system to use JWT tokens.
+
+## Current Implementation
+
+@src/auth/
+@src/middleware/auth.py
+
+## Requirements
+
+- Replace session-based auth with JWT
+- Add refresh token support
+- Update all tests
+
+## Additional Context
+
+@docs/auth-spec.md
 ```
 
+Include patterns:
+- `@path/to/file.py` - Single file
+- `@path/to/directory/` - All files in directory
+- `@src/**/*.py` - Glob pattern
+
 ## Configuration
 
 Environment variables:
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `FIRETEAM_MAX_ITERATIONS` | (none) | Max loop iterations. Unset = infinite. |
+| `FIRETEAM_MAX_ITERATIONS` | unlimited | Max loop iterations |
 | `FIRETEAM_LOG_LEVEL` | INFO | Logging verbosity |
 
-## Project Structure
+## Library Usage
 
-```
-fireteam/
-├── .claude-plugin/
-│   └── plugin.json      # Claude Code plugin manifest
-├── commands/
-│   └── fireteam.md      # /fireteam command definition
-├── hooks/
-│   └── hooks.json       # Claude Code hooks configuration
-├── src/
-│   ├── __init__.py      # Public API exports
-│   ├── api.py           # Core execute() function
-│   ├── models.py        # Data models (ExecutionMode, ExecutionResult, etc.)
-│   ├── loops.py         # Loop implementations (moderate_loop, full_loop)
-│   ├── claude_cli.py    # Claude Code CLI wrapper
-│   ├── complexity.py    # Complexity estimation
-│   ├── circuit_breaker.py # Stuck loop detection
-│   ├── rate_limiter.py  # API call budget management
-│   ├── runner.py        # tmux-based autonomous execution
-│   ├── prompt.py        # PROMPT.md parsing with file includes
-│   ├── config.py        # Configuration
-│   ├── claude_hooks/    # Claude Code hook handlers
-│   └── prompts/
-│       ├── __init__.py  # Prompt loader
-│       ├── builder.py   # Prompt building with feedback injection
-│       ├── executor.md  # Executor agent prompt
-│       ├── reviewer.md  # Reviewer agent prompt
-│       ├── planner.md   # Planner agent prompt
-│       └── complexity.md # Complexity estimation prompt
-├── tests/
-└── pyproject.toml
+Fireteam can also be used as a Python library:
+
+```python
+from fireteam import execute
+
+result = await execute(
+    project_dir="/path/to/project",
+    goal="Fix the authentication bug",
+)
+
+if result.success:
+    print(f"Completed in {result.iterations} iterations")
 ```
 
+See [docs/](./docs/) for full API documentation.
+
 ## Development
 
 ```bash
-# Clone and install dev dependencies
 git clone https://github.com/darkresearch/fireteam
 cd fireteam
 uv sync --extra dev
-
-# Run tests
 uv run pytest tests/ -v
 ```
 
diff --git a/docs/README.md b/docs/README.md
index 10d1f77..e39e256 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,32 +1,31 @@
 # Fireteam Documentation
 
-Fireteam is a Python library for adaptive task execution using Claude. It automatically estimates task complexity and selects the appropriate execution strategy.
+Fireteam is a CLI tool for autonomous task execution using Claude. Give it a goal, let it run until complete.
 
 ## Contents
 
 - [Introduction](./introduction.md) - Overview and key concepts
 - [Quickstart](./quickstart.md) - Get started in 5 minutes
+- [CLI Reference](./cli-runner.md) - Command-line interface
 - [Concepts](./concepts/) - Deep dives into core concepts
   - [Complexity Estimation](./concepts/complexity.md)
   - [Execution Modes](./concepts/execution-modes.md)
-- [API Reference](./api/) - Full API documentation
+- [API Reference](./api/) - Python library documentation
   - [execute()](./api/execute.md)
   - [estimate_complexity()](./api/estimate-complexity.md)
   - [Types](./api/types.md)
-- [CLI Runner](./cli-runner.md) - tmux-based autonomous execution
 
 ## Quick Example
 
-```python
-from fireteam import execute
+```bash
+# Create a PROMPT.md with your task
+fireteam start
+```
 
-result = await execute(
-    project_dir="/path/to/project",
-    goal="Fix the authentication bug",
-)
+Or run in foreground:
 
-if result.success:
-    print(f"Completed: {result.completion_percentage}%")
+```bash
+fireteam run
 ```
 
 ## Execution Modes
@@ -35,5 +34,5 @@ if result.success:
 |------------|------|----------|
 | TRIVIAL | SINGLE_TURN | Direct execution, single pass |
 | SIMPLE | SINGLE_TURN | Direct execution, single pass |
-| MODERATE | MODERATE | Execute → review loop until >95% complete |
-| COMPLEX | FULL | Plan once, then execute → 3 parallel reviews until 2/3 say >95% |
+| MODERATE | MODERATE | Execute → review loop until ≥95% complete |
+| COMPLEX | FULL | Plan once, then execute → 3 parallel reviews until 2/3 say ≥95% |
diff --git a/docs/cli-runner.md b/docs/cli-runner.md
index 4986558..b5432b5 100644
--- a/docs/cli-runner.md
+++ b/docs/cli-runner.md
@@ -1,6 +1,6 @@
-# CLI Runner
+# CLI Reference
 
-Fireteam includes a tmux-based runner for long-running autonomous tasks. This allows you to start a task, detach, and come back later to check on progress.
+Fireteam includes a tmux-based runner for autonomous task execution. Start a task, detach, and come back later to check on progress.
 
 ## Requirements
 
@@ -12,24 +12,36 @@ Fireteam includes a tmux-based runner for long-running autonomous tasks. This al
 ### Start a Session
 
 ```bash
-python -m fireteam.runner start \
-    --project-dir /path/to/project \
-    --goal "Complete the feature implementation"
+fireteam start                           # Use PROMPT.md in current directory
+fireteam start -p /path/to/project       # Specify project directory
+fireteam start -f task.md                # Use specific goal file
+fireteam start -g "Fix the bug"          # Pass goal as string
+fireteam start -m full                   # Force execution mode
+fireteam start --max-iterations 10       # Limit iterations
 ```
 
 Options:
-- `--project-dir` - Project directory (required)
-- `--goal` - Task goal string
-- `--goal-file` - Path to PROMPT.md file (alternative to --goal)
-- `--mode` - Execution mode: single_turn, moderate, full (optional)
-- `--context` - Additional context (optional)
-- `--max-iterations` - Maximum iterations (optional)
-- `--session-name` - Custom session name (optional)
+- `-p, --project-dir` - Project directory (default: current directory)
+- `-g, --goal` - Task goal string
+- `-f, --goal-file` - Path to PROMPT.md file (default: auto-detect)
+- `-m, --mode` - Execution mode: single_turn, moderate, full
+- `-c, --context` - Additional context
+- `--max-iterations` - Maximum iterations
+- `-s, --session-name` - Custom session name
+
+### Run in Foreground
+
+```bash
+fireteam run                             # Use PROMPT.md in current directory
+fireteam run -p /path/to/project         # Specify project directory
+```
+
+Runs in the foreground without tmux. Useful for debugging or short tasks.
 
 ### List Sessions
 
 ```bash
-python -m fireteam.runner list
+fireteam list
 ```
 
 Shows all running Fireteam sessions with their status.
@@ -37,7 +49,7 @@ Shows all running Fireteam sessions with their status.
 ### Attach to a Session
 
 ```bash
-python -m fireteam.runner attach fireteam-myproject
+fireteam attach fireteam-myproject
 ```
 
 Attaches to a running session to watch progress in real-time. Press `Ctrl+B D` to detach.
@@ -45,39 +57,24 @@ Attaches to a running session to watch progress in real-time. Press `Ctrl+B D` t
 ### View Logs
 
 ```bash
-python -m fireteam.runner logs fireteam-myproject
-
-# Show more lines
-python -m fireteam.runner logs fireteam-myproject -n 200
-
-# Follow (like tail -f)
-python -m fireteam.runner logs fireteam-myproject -f
+fireteam logs fireteam-myproject         # Last 50 lines
+fireteam logs fireteam-myproject -n 200  # Last 200 lines
 ```
 
 ### Kill a Session
 
 ```bash
-python -m fireteam.runner kill fireteam-myproject
+fireteam kill fireteam-myproject
 ```
 
 Terminates a running session.
 
-### Run Directly (Blocking)
-
-```bash
-python -m fireteam.runner run \
-    --project-dir /path/to/project \
-    --goal "Fix the bug"
-```
-
-Runs in the foreground without tmux. Useful for debugging or short tasks.
-
 ## Session Names
 
 By default, session names are generated from the project directory:
 - `/path/to/myproject` → `fireteam-myproject`
 
-You can specify a custom name with `--session-name`.
+You can specify a custom name with `-s` or `--session-name`.
 
 ## Log Files
 
@@ -90,44 +87,20 @@ Logs are stored in `~/.fireteam/logs/` with timestamps:
 
 Session state is stored in `~/.fireteam/`:
 ```
-~/.fireteam/fireteam-myproject.json   # Session info
-~/.fireteam/fireteam-myproject_prompt.md  # Resolved prompt
+~/.fireteam/fireteam-myproject.json      # Session info
+~/.fireteam/fireteam-myproject_prompt.md # Resolved prompt
 ```
 
 ## Example Workflow
 
 ```bash
-# Start a long-running task
-python -m fireteam.runner start \
-    --project-dir ~/projects/myapp \
-    --goal-file PROMPT.md \
-    --mode full
-
-# Check on it later
-python -m fireteam.runner list
-
-# Watch progress
-python -m fireteam.runner attach fireteam-myapp
-
-# Detach with Ctrl+B D
-
-# Check final logs
-python -m fireteam.runner logs fireteam-myapp
-
-# Clean up
-python -m fireteam.runner kill fireteam-myapp
-```
-
-## Using with PROMPT.md
-
-Create a `PROMPT.md` file with your task and file includes:
-
-```markdown
+# Create your PROMPT.md
+cat > PROMPT.md << 'EOF'
 # Task
 
 Refactor the authentication system to use JWT tokens.
 
-## Current Implementation
+## Context
 
 @src/auth/
 @src/middleware/auth.py
@@ -135,38 +108,31 @@ Refactor the authentication system to use JWT tokens.
 ## Requirements
 
 - Replace session-based auth with JWT
-- Maintain backward compatibility for 1 week
 - Add refresh token support
 - Update all tests
-```
+EOF
 
-Then start:
+# Start the task
+fireteam start -m full
 
-```bash
-python -m fireteam.runner start \
-    --project-dir ~/projects/myapp \
-    --goal-file PROMPT.md
-```
+# Check on it later
+fireteam list
 
-## Programmatic Usage
+# Watch progress
+fireteam attach fireteam-myproject
 
-You can also use the runner functions from Python:
+# Detach with Ctrl+B D
 
-```python
-from fireteam import start_session, list_sessions, attach_session, kill_session
+# Check final logs
+fireteam logs fireteam-myproject
 
-# Start a session
-info = start_session(
-    project_dir="/path/to/project",
-    goal="Complete the feature",
-    mode=ExecutionMode.FULL,
-)
-print(f"Started: {info.session_name}")
+# Clean up
+fireteam kill fireteam-myproject
+```
 
-# List sessions
-for session in list_sessions():
-    print(f"{session.session_name}: {session.status}")
+## Environment Variables
 
-# Kill a session
-kill_session("fireteam-myproject")
-```
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `FIRETEAM_MAX_ITERATIONS` | unlimited | Max loop iterations |
+| `FIRETEAM_LOG_LEVEL` | INFO | Logging verbosity |
diff --git a/docs/concepts/complexity.md b/docs/concepts/complexity.md
index 19e5cec..82f7868 100644
--- a/docs/concepts/complexity.md
+++ b/docs/concepts/complexity.md
@@ -13,22 +13,19 @@ Fireteam automatically estimates task complexity to select the appropriate execu
 
 ## How It Works
 
-When you call `execute()` without specifying a mode, Fireteam:
+When you run `fireteam start` or `fireteam run` without specifying a mode, Fireteam:
 
 1. Sends your goal and context to Claude
 2. Claude analyzes the scope using read-only tools (Glob, Grep, Read)
 3. Returns a complexity level based on the analysis
 4. Fireteam maps the complexity to an execution mode
 
-```python
-from fireteam import estimate_complexity
+```bash
+# Let Fireteam auto-detect complexity
+fireteam start
 
-complexity = await estimate_complexity(
-    goal="Add user authentication",
-    context="Using FastAPI with existing User model",
-    project_dir="/path/to/project",  # Optional: enables codebase exploration
-)
-# Returns: ComplexityLevel.MODERATE
+# Force a specific mode
+fireteam start -m full
 ```
 
 ## Complexity to Mode Mapping
@@ -74,30 +71,26 @@ complexity = await estimate_complexity(
 
 You can bypass complexity estimation by specifying the mode directly:
 
-```python
-from fireteam import execute, ExecutionMode
-
+```bash
 # Force FULL mode for thorough execution
-result = await execute(
-    project_dir="/path/to/project",
-    goal="Add simple logging",
-    mode=ExecutionMode.FULL,  # Override complexity estimation
-)
+fireteam start -m full
+
+# Force SINGLE_TURN for quick execution
+fireteam start -m single_turn
 ```
 
 ## Codebase Exploration
 
-When `project_dir` is provided to `estimate_complexity()`, Claude can explore the codebase using read-only tools to make a more accurate estimate:
+Fireteam explores the codebase using read-only tools to make accurate complexity estimates. Providing relevant files in your PROMPT.md helps with this:
+
+```markdown
+# Task
 
-```python
-# Quick estimation (no codebase access)
-complexity = await estimate_complexity(
-    goal="Add logging to the auth module",
-)
+Add logging to the auth module.
 
-# Accurate estimation (with codebase exploration)
-complexity = await estimate_complexity(
-    goal="Add logging to the auth module",
-    project_dir="/path/to/project",
-)
+## Context
+
+@src/auth/
 ```
+
+The included files give Claude context for a more accurate complexity assessment.
diff --git a/docs/concepts/execution-modes.md b/docs/concepts/execution-modes.md
index 6b1a82e..693b6c1 100644
--- a/docs/concepts/execution-modes.md
+++ b/docs/concepts/execution-modes.md
@@ -20,14 +20,8 @@ FULL         →  Plan → Execute → 3 Reviews → loop until 2/3 say ≥95%
 - No review phase
 - Fastest execution
 
-```python
-from fireteam import execute, ExecutionMode
-
-result = await execute(
-    project_dir="/path/to/project",
-    goal="Fix the typo in README.md",
-    mode=ExecutionMode.SINGLE_TURN,
-)
+```bash
+fireteam run -m single_turn
 ```
 
 ## MODERATE Mode
@@ -40,16 +34,8 @@ result = await execute(
 - Loops until reviewer says ≥95% complete
 - Feedback from reviews flows to next iteration
 
-```python
-result = await execute(
-    project_dir="/path/to/project",
-    goal="Refactor the user service",
-    mode=ExecutionMode.MODERATE,
-)
-
-# Result includes review info
-print(result.completion_percentage)  # e.g., 96
-print(result.iterations)             # Number of execute→review cycles
+```bash
+fireteam run -m moderate
 ```
 
 ## FULL Mode
@@ -62,16 +48,8 @@ print(result.iterations)             # Number of execute→review cycles
 3. **Review Phase**: 3 parallel reviewers assess completion
 4. **Loop**: Continue until 2 of 3 reviewers say ≥95% complete
 
-```python
-result = await execute(
-    project_dir="/path/to/project",
-    goal="Redesign the authentication system",
-    mode=ExecutionMode.FULL,
-)
-
-# Result includes all phases
-print(result.metadata.get("plan"))  # Implementation plan
-print(result.completion_percentage)  # Should be ≥95%
+```bash
+fireteam start -m full
 ```
 
 ### Why 3 Parallel Reviewers?
@@ -97,49 +75,28 @@ This respects Claude's judgment - if the executor believes more work is needed,
 
 Let Fireteam choose based on complexity estimation:
 
-```python
-result = await execute(
-    project_dir="/path/to/project",
-    goal="Your task here",
-    # mode not specified - auto-detect
-)
-
-print(f"Used mode: {result.mode}")
+```bash
+fireteam start  # Mode auto-detected from task complexity
 ```
 
 ### Manual Override
 
 Force a specific mode:
 
-```python
+```bash
 # Be thorough with a simple task
-result = await execute(
-    project_dir="/path/to/project",
-    goal="Add a comment",
-    mode=ExecutionMode.FULL,
-)
+fireteam start -m full
 
 # Be quick with a moderate task
-result = await execute(
-    project_dir="/path/to/project",
-    goal="Refactor module",
-    mode=ExecutionMode.SINGLE_TURN,
-)
+fireteam start -m single_turn
 ```
 
 ## Iteration Limits
 
 By default, MODERATE and FULL modes loop indefinitely until completion. Set a limit:
 
-```python
-result = await execute(
-    project_dir="/path/to/project",
-    goal="Complex refactoring",
-    max_iterations=10,  # Stop after 10 iterations
-)
-
-if not result.success and result.iterations >= 10:
-    print("Hit iteration limit before completion")
+```bash
+fireteam start --max-iterations 10
 ```
 
 ## Tool Access by Phase
diff --git a/docs/introduction.md b/docs/introduction.md
index 8add412..a2624b5 100644
--- a/docs/introduction.md
+++ b/docs/introduction.md
@@ -1,35 +1,44 @@
 # Introduction
 
-Fireteam is a Python library for adaptive task execution using Claude Code CLI. It automatically estimates task complexity and selects the appropriate execution strategy, running tasks to completion with built-in review loops.
+Fireteam is a CLI tool for autonomous task execution using Claude. Give it a goal, let it run until complete. It automatically estimates task complexity and selects the appropriate execution strategy, looping until reviewers confirm completion.
 
 ## Key Features
 
-- **Adaptive Execution** - Automatically estimates task complexity and selects the best execution mode
+- **Autonomous Execution** - Define a task in PROMPT.md, run `fireteam start`, and walk away
+- **Adaptive Complexity** - Automatically estimates task complexity and selects the best execution mode
 - **Multi-Phase Workflow** - Plan, execute, and review phases for complex tasks
 - **Loop Until Complete** - Continues iterating until reviewers confirm completion (≥95%)
 - **Parallel Reviews** - Complex tasks get 3 parallel reviewers with majority consensus
-- **Simple API** - One function to execute any task: `execute()`
+- **Background Sessions** - Uses tmux for detached execution with live monitoring
 
 ## How It Works
 
-When you call `execute()`, Fireteam:
+When you run `fireteam start` or `fireteam run`:
 
-1. **Estimates complexity** - Analyzes the goal to determine if it's trivial, simple, moderate, or complex
-2. **Selects execution mode** - Maps complexity to the appropriate execution strategy
-3. **Executes the task** - Runs the appropriate phases (plan, execute, review)
-4. **Loops until complete** - For moderate/complex tasks, iterates until completion threshold is met
-5. **Returns results** - Provides success status, output, and completion percentage
+1. **Reads your PROMPT.md** - Loads the task goal and any included files
+2. **Estimates complexity** - Analyzes the goal to determine if it's trivial, simple, moderate, or complex
+3. **Selects execution mode** - Maps complexity to the appropriate execution strategy
+4. **Executes the task** - Runs the appropriate phases (plan, execute, review)
+5. **Loops until complete** - For moderate/complex tasks, iterates until completion threshold is met
 
-```python
-from fireteam import execute
+```bash
+# Create your PROMPT.md
+cat > PROMPT.md << 'EOF'
+# Task
 
-result = await execute(
-    project_dir="/path/to/project",
-    goal="Fix the authentication bug",
-)
+Fix the authentication bug where users can't log in after password reset.
 
-print(f"Success: {result.success}")
-print(f"Completion: {result.completion_percentage}%")
+## Context
+
+@src/auth.py
+@tests/test_auth.py
+EOF
+
+# Start autonomous execution
+fireteam start
+
+# Monitor progress
+fireteam logs fireteam-myproject
 ```
 
 ## Execution Modes
@@ -61,5 +70,5 @@ Fireteam wraps the Claude Code CLI, piggybacking on your existing Claude Code se
 ## Next Steps
 
 - [Quickstart](./quickstart.md) - Get started in 5 minutes
+- [CLI Reference](./cli-runner.md) - Full command documentation
 - [Execution Modes](./concepts/execution-modes.md) - Learn about the different strategies
-- [API Reference](./api/execute.md) - Full API documentation
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 6e90c5c..69ca5f0 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -4,181 +4,161 @@ Get started with Fireteam in 5 minutes.
 
 ## Installation
 
-Install Fireteam using uv or pip:
-
 ```bash
-uv add fireteam
+# Install as a CLI tool
+pipx install fireteam
 # or
-pip install fireteam
+uv tool install fireteam
 ```
 
 **Requirements:**
 - Python 3.12+
-- Claude Code CLI installed
+- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed
 
 ## Basic Usage
 
-### Execute a Task
+### 1. Create a PROMPT.md
 
-The simplest way to use Fireteam is with the `execute()` function:
+In your project directory, create a `PROMPT.md` file:
 
-```python
-import asyncio
-from fireteam import execute
+```markdown
+# Task
 
-async def main():
-    result = await execute(
-        project_dir="/path/to/your/project",
-        goal="Fix the bug in auth.py where users can't log in",
-    )
+Fix the bug in auth.py where users can't log in.
 
-    if result.success:
-        print(f"Task completed!")
-        print(f"Output: {result.output}")
-        print(f"Completion: {result.completion_percentage}%")
-    else:
-        print(f"Task failed: {result.error}")
+## Context
 
-asyncio.run(main())
+@src/auth.py
+@tests/test_auth.py
+
+## Requirements
+
+- Users should be able to log in after password reset
+- All existing tests must pass
 ```
 
-### Add Context
+### 2. Start Fireteam
 
-Provide additional context to help Claude understand the task:
+```bash
+# Start a background session (tmux)
+fireteam start
 
-```python
-result = await execute(
-    project_dir="/path/to/project",
-    goal="Fix the authentication bug",
-    context="""
-    Error logs show:
-    - NullPointerException at auth.py:42
-    - Users report login failures after password reset
-    """,
-)
+# Or run in foreground
+fireteam run
 ```
 
-### Specify Execution Mode
+### 3. Monitor Progress
 
-Force a specific execution mode instead of auto-detection:
+```bash
+# List running sessions
+fireteam list
 
-```python
-from fireteam import execute, ExecutionMode
+# Attach to watch live
+fireteam attach fireteam-myproject
 
+# View logs
+fireteam logs fireteam-myproject
+```
+
+## CLI Options
+
+### Specify a Goal Directly
+
+```bash
+fireteam start -g "Fix the authentication bug"
+```
+
+### Use a Different Project Directory
+
+```bash
+fireteam start -p /path/to/project
+```
+
+### Force an Execution Mode
+
+```bash
 # Use full plan+execute+review cycle for complex tasks
-result = await execute(
-    project_dir="/path/to/project",
-    goal="Refactor the entire authentication module",
-    mode=ExecutionMode.FULL,
-)
+fireteam start -m full
 
 # Use single-turn for trivial tasks
-result = await execute(
-    project_dir="/path/to/project",
-    goal="Add a comment explaining the login function",
-    mode=ExecutionMode.SINGLE_TURN,
-)
+fireteam start -m single_turn
 ```
 
 ### Limit Iterations
 
-By default, Fireteam loops until completion. Set a maximum:
-
-```python
-result = await execute(
-    project_dir="/path/to/project",
-    goal="Refactor the user service",
-    max_iterations=10,  # Stop after 10 iterations if not complete
-)
+```bash
+fireteam start --max-iterations 10
 ```
 
-## Using PROMPT.md Files
+## PROMPT.md Format
 
-Instead of passing a goal string, you can use a PROMPT.md file with inline file includes:
+Use `@` syntax to include files in your prompt:
 
 ```markdown
 # Task
 
-Fix the authentication bug.
+Refactor the authentication system to use JWT tokens.
 
-## Context
+## Current Implementation
 
-@src/auth.py
-@tests/test_auth.py
+@src/auth/
+@src/middleware/auth.py
 
 ## Requirements
 
-- Users should be able to log in after password reset
-- All existing tests must pass
-```
+- Replace session-based auth with JWT
+- Add refresh token support
+- Update all tests
 
-Then execute:
+## Additional Context
 
-```python
-result = await execute(
-    project_dir="/path/to/project",
-    goal_file="PROMPT.md",  # or auto-detected if present
-)
+@docs/auth-spec.md
 ```
 
-## Complexity Estimation
-
-Use `estimate_complexity()` to understand how Fireteam will handle a task:
+Include patterns:
+- `@path/to/file.py` - Single file
+- `@path/to/directory/` - All files in directory
+- `@src/**/*.py` - Glob pattern
 
-```python
-from fireteam import estimate_complexity, ComplexityLevel
+## Complexity Estimation
 
-complexity = await estimate_complexity(
-    goal="Add user authentication with OAuth",
-    context="Using FastAPI and existing user model",
-)
+Fireteam automatically estimates task complexity:
 
-print(f"Complexity: {complexity}")
-# ComplexityLevel.MODERATE
-```
+| Complexity | Mode | Behavior |
+|------------|------|----------|
+| TRIVIAL | SINGLE_TURN | Direct execution, single pass |
+| SIMPLE | SINGLE_TURN | Direct execution, single pass |
+| MODERATE | MODERATE | Execute → review loop until ≥95% complete |
+| COMPLEX | FULL | Plan once, then execute → 3 parallel reviews until 2/3 say ≥95% |
 
-## Understanding Results
+## Library Usage
 
-The `ExecutionResult` contains:
+Fireteam can also be used as a Python library:
 
 ```python
-result = await execute(project_dir=".", goal="Fix bug")
-
-# Check success
-if result.success:
-    print(result.output)              # Execution output
-    print(result.completion_percentage)  # 0-100
-    print(result.iterations)          # Number of iterations
-    print(result.metadata)            # Additional info
-else:
-    print(result.error)               # Error message
-
-# Always available
-print(result.mode)  # ExecutionMode used
-```
-
-## CLI Runner
-
-For long-running autonomous tasks, use the tmux-based runner:
-
-```bash
-# Start a background session
-python -m fireteam.runner start --project-dir /path/to/project --goal "Complete the feature"
+import asyncio
+from fireteam import execute
 
-# List running sessions
-python -m fireteam.runner list
+async def main():
+    result = await execute(
+        project_dir="/path/to/your/project",
+        goal="Fix the bug in auth.py where users can't log in",
+    )
 
-# Attach to watch progress
-python -m fireteam.runner attach fireteam-myproject
+    if result.success:
+        print(f"Task completed!")
+        print(f"Output: {result.output}")
+        print(f"Completion: {result.completion_percentage}%")
+    else:
+        print(f"Task failed: {result.error}")
 
-# View logs
-python -m fireteam.runner logs fireteam-myproject
+asyncio.run(main())
 ```
 
-See [CLI Runner](./cli-runner.md) for more details.
+See [API Reference](./api/execute.md) for full library documentation.
 
 ## Next Steps
 
+- [CLI Reference](./cli-runner.md) - Full command documentation
 - [Execution Modes](./concepts/execution-modes.md) - Learn about the different execution strategies
 - [Complexity Estimation](./concepts/complexity.md) - Understand how tasks are classified
-- [API Reference](./api/execute.md) - Full API documentation
diff --git a/src/runner.py b/src/runner.py
index 26f3122..f18b614 100644
--- a/src/runner.py
+++ b/src/runner.py
@@ -352,31 +352,31 @@ def main() -> None:
     import argparse
 
     parser = argparse.ArgumentParser(
-        description="Fireteam autonomous execution runner",
-        prog="python -m fireteam.runner",
+        description="Fireteam - autonomous task execution with Claude",
+        prog="fireteam",
     )
 
     subparsers = parser.add_subparsers(dest="command", help="Commands")
 
     # Start command
-    start_parser = subparsers.add_parser("start", help="Start a new autonomous session")
-    start_parser.add_argument("--project-dir", "-p", required=True, help="Project directory")
+    start_parser = subparsers.add_parser("start", help="Start a new autonomous session in tmux")
+    start_parser.add_argument("--project-dir", "-p", default=".", help="Project directory (default: current)")
     start_parser.add_argument("--goal", "-g", help="Task goal (string)")
-    start_parser.add_argument("--goal-file", "-f", help="Path to goal file (PROMPT.md style)")
+    start_parser.add_argument("--goal-file", "-f", help="Path to goal file (default: auto-detect PROMPT.md)")
     start_parser.add_argument("--edit", "-e", action="store_true", help="Open editor to write goal")
-    start_parser.add_argument("--mode", "-m", choices=["single_turn", "moderate", "full"], help="Execution mode")
+    start_parser.add_argument("--mode", "-m", choices=["single_turn", "moderate", "full"], help="Execution mode (default: auto-detect)")
     start_parser.add_argument("--context", "-c", default="", help="Additional context")
-    start_parser.add_argument("--max-iterations", type=int, help="Max iterations")
+    start_parser.add_argument("--max-iterations", type=int, help="Max iterations (default: unlimited)")
     start_parser.add_argument("--session-name", "-s", help="Custom session name")
 
-    # Run command (called from within tmux)
-    run_parser = subparsers.add_parser("run", help="Run autonomous execution (called from tmux)")
-    run_parser.add_argument("--project-dir", "-p", required=True, help="Project directory")
+    # Run command (foreground execution, also used internally by tmux)
+    run_parser = subparsers.add_parser("run", help="Run autonomous execution in foreground")
+    run_parser.add_argument("--project-dir", "-p", default=".", help="Project directory (default: current)")
     run_parser.add_argument("--goal", "-g", help="Task goal (string)")
-    run_parser.add_argument("--goal-file", "-f", help="Path to goal file (PROMPT.md style)")
-    run_parser.add_argument("--mode", "-m", choices=["single_turn", "moderate", "full"], help="Execution mode")
+    run_parser.add_argument("--goal-file", "-f", help="Path to goal file (default: auto-detect PROMPT.md)")
+    run_parser.add_argument("--mode", "-m", choices=["single_turn", "moderate", "full"], help="Execution mode (default: auto-detect)")
     run_parser.add_argument("--context", "-c", default="", help="Additional context")
-    run_parser.add_argument("--max-iterations", type=int, help="Max iterations")
+    run_parser.add_argument("--max-iterations", type=int, help="Max iterations (default: unlimited)")
 
     # List command
     subparsers.add_parser("list", help="List running sessions")
@@ -410,8 +410,8 @@ def main() -> None:
             )
             print(f"Started session: {info.session_name}")
             print(f"Log file: {info.log_file}")
-            print(f"\nTo attach: python -m fireteam.runner attach {info.session_name}")
-            print(f"To view logs: python -m fireteam.runner logs {info.session_name}")
+            print(f"\nTo attach: fireteam attach {info.session_name}")
+            print(f"To view logs: fireteam logs {info.session_name}")
         except ValueError as e:
             print(f"Error: {e}")
             sys.exit(1)