# Task Factory

Task Factory is a queue-first work orchestrator for AI coding agents, built on **[Pi](https://github.com/badlogic/pi-mono/tree/main)**.

## Philosophy

Task Factory is designed around one idea: **the human is the bottleneck**.

Instead of juggling many half-finished agent runs, you stage work in a queue and let the system sequence the work in order. Task factory's goal is to maximize your throughput, reduce context switching, and automate the completion of the task. 

You're left with creating the idea and checking the output.

![Task-level execution context and review](docs/screenshots/task_view.png)

![Idea backlog and queue sequencing](docs/screenshots/idea_backlog.png)

## Workflow 

Task Factory has a fairly opinionated workflow. Tasks progress through stages:

- **Backlog**: Tasks are staged in the backlog as an agent is run to generate a plan. You can review the plan before marking it as ready, or drag it directly to Executing if it already has acceptance criteria (skips the Ready phase).
- **Ready**: Once a task is ready for execution, place it in the ready queue, or let it Auto Promote from the backlog.
- **Executing**: Tasks are executed one at a time by default (but that number is configurable). Optional pre-planning, pre-execution, and post-execution skills run around planning/implementation, and skills are now assignable in any lane. Starter skills include `checkpoint`, `code-review`, and `update-docs` (default post-execution order). New Task supports reusable model profiles (planning+execution model/thinking presets) for one-click model selection, including ordered planning/execution fallback model chains that auto-fail over on retryable provider instability (e.g., rate limits and 5xx errors). Default profile selection can be set from Global Settings and per-workspace Task Defaults (precedence: explicit form state → workspace default profile → global default profile → manual model defaults). Queue automation includes a provider/model-aware execution circuit breaker for repeated `rate_limit`/`quota`/`auth` failures, with cooldown + manual resume. Task/runtime modules can also emit daemon notifications through a gateway layer with allowlisted routing to Telegram/Discord.
- **Completed**: Once in completed state, you can review the task before archiving it.

This keeps agent output aligned to your review capacity and prevents overproduction.

## YOLO by default

Task Factory runs with Pi-style **YOLO mode** behavior (no permission popups/approval gates). Agents can execute tools and shell commands with your local user permissions.

> ⚠️ **Security warning:** Task Factory currently has **no sandbox boundary**. Only run it on trusted repositories and in environments you control.

## Foreman

The foreman is a special agent scoped to a workspace that helps you plan tasks and can ideate with you.

The foreman can:
- Help you ideate and then break the task down that you can add to your queue.
- Generate artifacts (web pages) to help give you a visual guide, design mockups, etc.
- Show a workspace pipeline dashboard (funnel, rework, throughput, and cycle/lead-time summaries) in the Foreman workspace pane when no artifact is open.

If you need help coming up with ideas or using Task Factory, ask the Foreman.

## Installation

### Option A: npm global install

```bash
npm install -g task-factory
```

Run it:

```bash
task-factory
```

### Option B: run from source

```bash
git clone https://github.com/patleeman/task-factory.git
cd task-factory
npm install
```

## Running from source

### Production build

```bash
npm run build
npm start
```

Open `http://127.0.0.1:3000`.

### Development mode

```bash
npm run dev
```

This starts shared, server, and client in watch/dev mode.

## Useful CLI options

```bash
task-factory --help
task-factory --version
task-factory --no-open
PORT=8080 HOST=127.0.0.1 task-factory
HOST=0.0.0.0 task-factory  # Expose on your network (explicit opt-in)
```

### CLI automation flags (agent/non-interactive use)

```bash
# Read CLI capabilities/version as stable JSON
task-factory capabilities --compact

# Skip interactive confirmation on destructive commands
task-factory workspace delete <id> --yes     # or --force
task-factory task delete <task-id> --yes     # or --force

# Emit machine-readable JSON instead of table/text output
task-factory workspace list --json           # or --output json
task-factory workspace show <id> --json
task-factory task list --json
task-factory task show <task-id> --json
task-factory stats --json

# Create/update tasks from spec files and agent-facing fields
task-factory task create --workspace <id> --title "Implement feature" --file ./spec.md
task-factory task update <task-id> --file ./spec.md --acceptance-criteria "A,B" --plan-goal "Ship" --plan-steps "Step 1,Step 2"
```

## Quality checks

```bash
npm run check:deadcode
npm run check:release
```

## Documentation

- [Documentation index](docs/README.md)
- [Getting Started](docs/getting-started.md)
- [CLI Reference](docs/cli-reference.md)
- [CLI Migration Guide](docs/cli-migration.md)
- [Workflow and Queue](docs/workflow-and-queue.md)
- [System Architecture](docs/system-architecture.md)
- [Runtime Flows](docs/runtime-flows.md)
- [State Contract](docs/state-contract.md)
- [REST API Reference](docs/api-rest-reference.md)
- [WebSocket Event Reference](docs/api-websocket-events.md)
- [Operations Security Posture](docs/operations-security-posture.md)
- [Contribution Commands](docs/contribution-commands.md)
- [Contribution: Extensions and Skills](docs/contribution-extensions-skills.md)
- [Notifications (Daemon → Gateway)](docs/notifications.md)

## Feature gallery

Provider setup supports all providers [pi supports](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/providers.md)

![Provider setup and login](docs/screenshots/provider_login.png)

The agent can ask you questions using a multiple choice Q&A widget.
The Q&A panel now recovers reliably after returning to a workspace, and closes immediately on successful submit/abort (without waiting for follow-up realtime events).

![Question/answer flow in planning](docs/screenshots/qa.png)

The foreman can generate visual artifacts 

![Artifacts generated during planning](docs/screenshots/artifacts.png)

Customize skills 

![Customizable execution skills](docs/screenshots/customizable_skills.png)

Then run those skills before or after tasks

![Task skill sequencing](docs/screenshots/task_skill_sequencing.png)

Attach sketches via embedded excalidraw

![Embedded Excalidraw for visual intent](docs/screenshots/embedded_excalidraw.png)

Tasks are archived and can be restored. Archived tasks contain all metadata including the full conversation

![Task archive and history](docs/screenshots/task_archive.png)

After tasks are completed, a summary is generated to give you a quick overview over the completed work

![Task completion summary and criteria review](docs/screenshots/task_completion_summary.png)

Track token usage and statistics on a per-task basis

![Task statistics and metrics](docs/screenshots/task_stats.png)

Global voice dictation with a keyboard shortcut using the browser's Web Speech API

![Voice dictation support](docs/screenshots/voice_dictation.png)

## License

MIT