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

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](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](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](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:

# (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](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:

# 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](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:

# 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, where each project entry specifies its preferred mode. For example:

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

The [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](docs/architecture.md)	Defines the three delivery paths in the Two task shapes section (lines 81-84)
[README.md](README.md)	Provides the concise Explicit project modes reference (lines 48-49)
[AGENTS.md](AGENTS.md)	Contains the contractual specification for delivery path selection (lines 14-18)
[docs/configuration.md](docs/configuration.md)	Documents secondmate routing logic and mode inheritance (lines 80-81)
[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](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](bin/fm-merge-local.sh).
• Configuration occurs in data/projects.md, with behavioral contracts defined in [AGENTS.md](AGENTS.md) and [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. 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](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](AGENTS.md).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}