# Autopilot

Autopilot lets you describe a high-level goal and have Polyscope break it into user stories, then execute each one sequentially — with progress tracking, crash recovery, and drag-and-drop reordering.

![Autopilot controls bar](/images/docs/autopilot-stories.png)

## How It Works

Autopilot operates in two phases:

1. **Story Generation** — You describe what you want to build, and an AI model analyzes your codebase to break the goal into a sequence of user stories (US-001, US-002, etc.), each with a title, description, and acceptance criteria.
2. **Sequential Execution** — Each story is executed one at a time in a fresh agent session. As stories complete, the agent records what it learned, so subsequent stories build on prior context.

## Starting Autopilot

Open the Autopilot dialog from the workspace toolbar or use the command palette (**⌘K**) and search for "Autopilot".

![Autopilot goal dialog](/images/docs/autopilot-prompt.png)

In the dialog you can:

- **Describe your goal** — Write a high-level description of what you want to build
- **Select a model** — Choose which AI model generates and executes the stories
- **Set max iterations** — Limit how many stories are executed before Autopilot pauses (default: 25)
- **Link workspaces** — Optionally reference other workspaces for additional context

Once you submit, the model analyzes your codebase and generates the story list.

## Approving Plans

When the agent proposes a plan, you can approve it to continue execution. The plan approval dialog offers two options:

- **Approve** — Continue with the current agent session and context intact.
- **Clear context & Approve** — Start a fresh agent session with only the approved plan. This is useful when the conversation has accumulated a lot of context and you want the agent to start clean with a clear directive.

## Managing Stories

After story generation, you can review and edit the plan before execution begins.

![Autopilot story editor](/images/docs/autopilot-stories-details.png)

### Editing Stories

Each story includes a title, description, and acceptance criteria. You can:

- **Edit** any story's title, description, or acceptance criteria inline
- **Reorder** stories by dragging and dropping
- **Add** new stories to fill in gaps
- **Delete** stories that aren't needed

While Autopilot is running, you can still edit or reorder **pending** stories. Stories that are already in progress or completed are locked.

### Story Statuses

| Status | Meaning |
|---|---|
| **Pending** | Not yet started — can be edited, reordered, or deleted |
| **In Progress** | Currently being executed by the agent |
| **Completed** | Finished successfully |
| **Failed** | The agent encountered an error |

## Running Autopilot

Click **Play** to start execution. Autopilot processes stories in order, one at a time.

The controls bar shows:

- The **current story** being executed (e.g., "US-003: Add validation logic")
- A **progress counter** (e.g., "3/8 completed")
- **Play**, **Pause**, and **Stop** buttons

### Pausing and Resuming

Click **Pause** to stop after the current story finishes. This is useful when you want to review progress, edit upcoming stories, or make manual changes before continuing.

Click **Play** again to resume from where you left off.

### Stopping

Click **Stop** to halt execution immediately. Any in-progress story will be reset to pending, so you can restart or adjust the plan.

## Progress Tracking

As each story completes, the agent records what it did and what it learned in a progress file (`.context/progress.md`). Each subsequent story reads this file so it has full context of prior work — no duplicated effort or conflicting changes.

## Crash Recovery

If Polyscope is interrupted while Autopilot is running (e.g., app restart, system crash), the in-progress story is reset to pending and Autopilot enters a **paused** state. You can review the state and resume when ready — no work is lost.

## Tips

- **Start with a clear, specific goal.** The more precise your description, the better the generated stories will be.
- **Review the story list before running.** It's faster to reorder or edit stories upfront than to redo work later.
- **Use linked workspaces** to give the model additional context when your goal spans multiple repositories or depends on patterns in another project.
- **Pause periodically** on large plans to verify the agent is on track before it continues.