# Workflows

Polyscope is built around a simple, repeatable workflow: **one workspace per feature or fix**. This keeps work isolated, easy to review, and safe to ship.

## The Core Loop

The recommended workflow in Polyscope follows this pattern:

1. **Create a workspace** — Press **⌘K** and type **new** to select a repository and spin up an isolated clone as new workspace
2. **Work on one thing** — Give the agent a focused task: a single feature, bug fix, or refactor
3. **Review and ship** — Check the diff (optionally use [Review](/docs/digging-deeper/review) for a dedicated review agent), then merge directly or create a pull request
4. **Delete the workspace** — Clean up and move on to the next task

Repeat this for every piece of work. Each workspace is disposable — treat them like branches you create, use, and throw away.

<!-- ![Polyscope workflow](/images/docs/TODO.png) -->

## Why One Workspace Per Task

Keeping each workspace focused on a single task has several advantages:

- **Clean diffs** — Every workspace produces a focused set of changes that's easy to review
- **No interference** — Agents in different workspaces can't step on each other's toes
- **Parallel work** — Run multiple workspaces at the same time for independent tasks
- **Easy rollback** — If something goes wrong, delete the workspace and start fresh

Avoid cramming multiple unrelated changes into one workspace. If a task naturally splits into independent parts, use separate workspaces.

## Setup and Shutdown Scripts

The key to a fluent workflow is automating workspace setup and teardown. Define scripts in `polyscope.json` so every new workspace is ready to go immediately:

```json
{
  "scripts": {
    "setup": "npm ci && npm run build",
    "archive": "herd unlink"
  }
}
```

- **`setup`** — Runs automatically after a workspace is created. Install dependencies, build assets, run migrations, link services — whatever your project needs.
- **`archive`** — Runs before a workspace is deleted. Unlink services, clean up external resources.

### Example: Laravel with Herd

[Laravel](https://laravel.com/) and [Laravel Herd](https://herd.laravel.com/) are a perfect combination for AI-driven web application development and provide you with a robust foundation, even if you're new to Laravel.

```json
{
  "scripts": {
    "setup": ["herd link", "herd secure"],
    "archive": ["herd unsecure", "herd unlink"]
  },
  "preview": {
    "url": "https://{{folder}}.test"
  }
}
```

This registers each workspace as a Herd site with HTTPS, and gives it a live preview URL. See [Laravel Herd](/docs/integrations/laravel-herd) for more details.

### Example: Node.js

```json
{
  "scripts": {
    "setup": "npm install && npm run build",
    "archive": "rm -rf dist"
  },
  "preview": {
    "url": "http://localhost:3000"
  }
}
```

## When to Use Multiple Workspaces

Create separate workspaces when you have:

- **Independent tasks** — A bug fix and a feature that don't overlap
- **Exploratory work** — Try different approaches in parallel and keep the best one
- **Large refactors** — Split into smaller, focused chunks
- **Review + build** — Have one agent review code while another builds a feature

If tasks depend on each other's output, complete the first before starting the next, or use [linked workspaces](/docs/digging-deeper/linking-workspaces) so agents can coordinate.

## Tips

- **Start small** — When working on a new codebase, give the agent smaller tasks first to build confidence in its understanding
- **Review before merging** — Always check the diff (**&#8984;D**) before shipping
- **Use plan mode** for complex changes — Have the agent propose a plan before coding