# Workflows

> There is no single way to use Foundry. What changes from project to project is how you get your task list. After that the loop is the same: Foundry runs…

Source: https://bifrost5.com/foundry/docs/workflows/

# Workflows

Information

Let your own AI tool take work from Foundry with you approving, or turn a rough idea into a checked task list.

[See editions](/foundry/docs/editions)

There is no single way to use Foundry. What changes from project to project is how you get your task list. After that the loop is the same: Foundry runs each task, checks the result with your tests, and saves its state.

## Greenfield: a new project

You start from a goal, not from code. Pick whichever fits how you like to work:

- **Starter code first**: put a boilerplate in `sandbox/

/`, set the goal, enqueue tasks that build on it.

- **Tasks by hand**: write a short task file yourself. Best for small, well-understood builds.

- **Spec first, with your own AI tool**: ask Claude Code, Cursor or Gemini to turn a written spec into a task file, read it, then enqueue it. You review the plan before anything runs.

- **Let a manager tool run it**: your AI tool queues the tasks, watches the run and unblocks it, while Foundry's workers do the coding. Details below.

## Brownfield: an existing project

You start from code that already works and must keep working. A typical case is redoing the UI of an older project while reusing the components you already have.

- Place the repository in `sandbox/

/` and let Foundry work on its own branch.

- Write small tasks, one to three files each. Name the existing components and helpers a task must reuse, so the agent extends your code instead of inventing new parts.

- Give every task a `test_command` from your existing suite, plus the `affects_files` it may change. Foundry keeps parallel tasks from touching the same file.

- Review the branch and merge it through your normal pull request process.

## The spec-driven cycle

For larger work, repeat one short cycle per feature. Your own AI tool helps at the two ends. Foundry owns the middle.

- **Specify**: write what the feature must do and how you will know it works.

- **Break down**: split it into small tasks with a test command each, and order them with `depends_on`.

- **Run**: enqueue and start. Foundry dispatches, validates and retries.

- **Check**: watch the dashboard, answer anything Foundry escalates.

- **Ship**: review the result, merge, then start the next cycle.

Production-Grade includes a planning companion for steps 1 and 2. It takes a rough idea through a few clarifying questions to an outline, and then to a checked, ready-to-run task list that you review before anything starts.

## Using your AI tool as the manager

Foundry stays the supervisor. It owns the queue, the worker pool and the checks. Its workers do the coding, and each one can run on a different provider: Claude Code, Cursor, Gemini, Copilot or a local model. Use as many as you like.

On top of that you can put one more AI tool as the manager. It does not do the tasks. It runs the supervisor for you, the way you would yourself, so Foundry gets the work and your tool watches over it. Your tool is the orchestrator and Foundry is what it orchestrates.

Foundry comes with a command-line tool, helper scripts and a local HTTP API behind the dashboard. Anything that can run a shell command can use them, so your manager tool can:

- **Plan and queue**: turn a plan into small, checked tasks and queue them in one step.

- **Watch**: get told when something finishes or needs you, instead of staring at a dashboard.

- **Steer**: pause, resume, cancel or roll back a run with one action.

- **Unblock**: when a task gets stuck, fix it by hand or have the workers retry. Everything waiting on it moves on.

- **Ship**: every change gets its own branch, passes automated checks, and merges through a pull request.

- **Publish**: go from a finished build to a live page that has passed a quality check.

The API needs a sign-in, so keep it on your own machine or network. You can also step in yourself at any time from the dashboard.

Production-Grade adds a second way in. An MCP bridge lets your own tool work as one of the workers, taking the next task on its own branch and asking you first when it is unsure, while Foundry stays the supervisor.

## CLI commands

The [UI Dashboard](/foundry/docs/ui-dashboard) is the recommended way to operate Foundry. The CLI does the same for automation and power users.

```
# Init state
npm run cli -- init-state --execution-mode AUTO --goal "Build a simple REST API"

# Set goal per project
npm run cli -- set-goal \
  --description "Your goal description" \
  --project-id my-project

# Enqueue tasks
npm run cli -- enqueue \
  --redis-host localhost --redis-port 6499 \
  --state-key supervisor:state --queue-name tasks --queue-db 2 \
  --task-file tasks/tasks.json

# Start loop
npm run cli -- start \
  --redis-host localhost --redis-port 6499 \
  --state-key supervisor:state --queue-name tasks --queue-db 2
```

## Monitor & Control

- **Status**: `npm run cli -- status...` (same Redis/queue flags)

- **Metrics**: `npm run cli -- metrics...` for performance data

- **Halt**: `npm run cli -- halt... --reason "Operator intervention"`

- **Resume**: `npm run cli -- resume...`

- **Logs**: `tail -f sandbox//audit.log.jsonl`