# Firstmate Delivery Modes: no-mistakes, direct-PR, and local-only Explained

> Understand Firstmate delivery modes: no-mistakes, direct-PR, and local-only. Choose the right mode for your CI validation, pull requests, or local development workflow.

- Repository: [Kun Chen/firstmate](https://github.com/kunchenguid/firstmate)
- Tags: deep-dive
- Published: 2026-08-13

---

**Firstmate supports three delivery modes—`no-mistakes`, `direct-PR`, and `local-only`—that determine whether code changes undergo full CI validation, skip directly to a pull request, or remain local until manually merged.**

The open-source `kunchenguid/firstmate` repository automates development workflows through these configurable **firstmate delivery modes**. Each mode defines a distinct path from local development to merged code, balancing automation, safety, and speed according to project requirements.

## Architectural Overview of Delivery Modes

The delivery architecture is formally defined in [[`docs/architecture.md`](https://github.com/kunchenguid/firstmate/blob/main/docs/architecture.md)](docs/architecture.md), specifically within lines 81-84 under the *Two task shapes* section. This documentation establishes that every ship task follows one of three explicit paths based on the project's configured mode. The authoritative contract binding these modes to the workflow execution appears in [[`AGENTS.md`](https://github.com/kunchenguid/firstmate/blob/main/AGENTS.md)](AGENTS.md) lines 14-18, which specifies how workers interpret the *Selected delivery path* during task processing.

According to the source, these modes represent distinct risk profiles: full automation with validation, semi-automated PR creation, and fully local workflows requiring manual intervention.

## The Three Firstmate Delivery Modes

Each mode serves a specific operational need, from production-grade CI gating to rapid local iteration.

### no-mistakes Mode (Full CI-Gated Pipeline)

The **`no-mistakes`** mode implements the most rigorous delivery path. When a worker operates in this mode, it executes the complete validation pipeline: creating a branch, opening a pull request, and monitoring continuous integration checks. Firstmate waits for the CI status to turn green before reporting success.

As implemented in [[`bin/fm-pr-merge.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-pr-merge.sh)](bin/fm-pr-merge.sh), this mode ensures that `done: PR <url> checks green` only appears after all automated checks pass. The captain (or automated `yolo` setting) may then proceed with the merge. This is the default mode for product-facing work where quality gates are non-negotiable.

**Example workflow:**

```sh

# (inside a Firstmate session)

> fix the login race condition in project‑xyz

# Firstmate spawns a worker, opens a PR, runs CI, and finally reports:

#   PR ready for review, captain: https://github.com/me/xyz/pull/42 (checks green)

```

### direct-PR Mode (Immediate Pull Request Creation)

The **`direct-PR`** mode streamlines the process by opening a pull request immediately without executing the no-mistakes validation pipeline. The worker pushes the branch to the remote and creates the PR, then reports `done: PR <url>` instantly.

This mode utilizes the same [[`bin/fm-pr-merge.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-pr-merge.sh)](bin/fm-pr-merge.sh) script but bypasses the CI-gating logic described in the architecture. It is ideal for internal tooling, documentation updates, or release-only changes where the overhead of full validation provides minimal benefit. The captain retains full control over when to merge, but receives no automated quality signal from Firstmate.

**Example workflow:**

```sh

# Set the project mode explicitly (once in data/projects.md)

myproject  direct-PR

# Now issue a change

> add a quick script to project‑myproject

# Firstmate opens a PR and reports immediately:

#   PR ready for review, captain: https://github.com/me/myproject/pull/7

```

### local-only Mode (Local Fast-Forward Merge)

The **`local-only`** mode keeps all operations on the local machine. The worker creates a clean, ready branch but never pushes to a remote or opens a pull request. Instead, Firstmate maintains the branch locally and performs a guarded fast-forward merge after captain approval.

This workflow relies on [[`bin/fm-merge-local.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-merge-local.sh)](bin/fm-merge-local.sh) to execute the merge safely. When the captain issues the merge command, Firstmate validates the branch state and fast-forwards the main branch without remote interaction. This mode suits projects without remote origins, sensitive local configurations, or workflows preferring direct Git operations over PR-based review.

**Example workflow:**

```sh

# Ensure the project is marked local-only

mylocalproj  local-only

# Issue a change

> bump the version in mylocalproj

# Firstmate finishes with a ready branch and reports:

#   ready‑branch my‑local‑proj‑v2.0 (awaiting merge)

# When the captain approves:

> merge it

# Firstmate runs the guarded fast‑forward merge:

bin/fm-merge-local.sh <task‑id>

```

## Configuring Delivery Modes in Your Project

Project-specific delivery modes are defined in [`data/projects.md`](https://github.com/kunchenguid/firstmate/blob/main/data/projects.md), where each project entry specifies its preferred mode. For example:

```markdown
myproject  direct-PR
mylocalproj  local-only
product-api  no-mistakes

```

The [[`docs/configuration.md`](https://github.com/kunchenguid/firstmate/blob/main/docs/configuration.md)](docs/configuration.md) file (lines 80-81) explains how **secondmates** (auxiliary workers) handle these configurations. Notably, secondmates only process `no-mistakes` and `direct-PR` modes; `local-only` tasks remain exclusively with the main Firstmate instance to ensure local state integrity.

## Core Implementation Files

Understanding the delivery modes requires familiarity with these key source files:

| File | Purpose |
|------|---------|
| [[`docs/architecture.md`](https://github.com/kunchenguid/firstmate/blob/main/docs/architecture.md)](docs/architecture.md) | Defines the three delivery paths in the *Two task shapes* section (lines 81-84) |
| [[`README.md`](https://github.com/kunchenguid/firstmate/blob/main/README.md)](README.md) | Provides the concise *Explicit project modes* reference (lines 48-49) |
| [[`AGENTS.md`](https://github.com/kunchenguid/firstmate/blob/main/AGENTS.md)](AGENTS.md) | Contains the contractual specification for delivery path selection (lines 14-18) |
| [[`docs/configuration.md`](https://github.com/kunchenguid/firstmate/blob/main/docs/configuration.md)](docs/configuration.md) | Documents secondmate routing logic and mode inheritance (lines 80-81) |
| [[`bin/fm-pr-merge.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-pr-merge.sh)](bin/fm-pr-merge.sh) | Handles PR creation and merging for `no-mistakes` and `direct-PR` modes |
| [[`bin/fm-merge-local.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-merge-local.sh)](bin/fm-merge-local.sh) | Executes guarded fast-forward merges for `local-only` mode |

## Summary

- **Firstmate delivery modes** control how changes progress from local branches to merged code.
- **`no-mistakes`** enforces full CI validation before reporting success, suitable for production code.
- **`direct-PR`** creates pull requests immediately without pipeline execution, optimizing for low-risk changes.
- **`local-only`** bypasses remotes entirely, using local fast-forward merges via [[`bin/fm-merge-local.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-merge-local.sh)](bin/fm-merge-local.sh).
- Configuration occurs in [`data/projects.md`](https://github.com/kunchenguid/firstmate/blob/main/data/projects.md), with behavioral contracts defined in [[`AGENTS.md`](https://github.com/kunchenguid/firstmate/blob/main/AGENTS.md)](AGENTS.md) and [[`docs/architecture.md`](https://github.com/kunchenguid/firstmate/blob/main/docs/architecture.md)](docs/architecture.md).

## Frequently Asked Questions

### What is the default delivery mode if I do not specify one in my project configuration?

Firstmate defaults to **`no-mistakes`** mode when no explicit mode is declared in [`data/projects.md`](https://github.com/kunchenguid/firstmate/blob/main/data/projects.md). This ensures maximum safety by requiring full CI validation before any merge can proceed, aligning with the project's philosophy of preventing broken code from reaching main branches.

### Can I switch delivery modes for a single task without changing my project's default?

Yes, you can override the project-wide setting at intake by specifying the mode explicitly in your command. Firstmate parses this override before spawning the worker, allowing one-off `direct-PR` submissions for urgent fixes even when your project normally requires `no-mistakes` validation.

### Why does the local-only mode not support secondmates?

The **`local-only`** mode restricts operations to the local filesystem and Git repository without remote pushes. Because secondmates are designed to handle remote PR interactions and distributed task queues, they cannot process local-only workflows. This limitation is documented in [[`docs/configuration.md`](https://github.com/kunchenguid/firstmate/blob/main/docs/configuration.md)](docs/configuration.md) lines 80-81 to prevent state synchronization issues between distributed agents and local Git state.

### How does the no-mistakes mode handle CI failures?

When operating in **`no-mistakes`** mode, Firstmate monitors the pull request's CI status continuously. If checks fail, the worker reports the failure and awaits captain instructions. The task remains open until the CI turns green or the captain explicitly aborts, ensuring that no code merges with failing tests according to the workflow defined in [[`AGENTS.md`](https://github.com/kunchenguid/firstmate/blob/main/AGENTS.md)](AGENTS.md).