# Firstmate Hard Rules and Project Boundary Restrictions

> Understand Firstmate hard rules and project boundary restrictions. Learn how Firstmate prevents unauthorized project writes, PR merges, and protects private data.

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

---

**Firstmate hard rules are immutable safety contracts defined in [`AGENTS.md`](https://github.com/kunchenguid/firstmate/blob/main/AGENTS.md) that prevent the AI from writing to projects, merging PRs without explicit captain approval, or discarding unlanded work, while project boundary restrictions enforce read-only access to the `projects/` directory and git-ignored paths for private captain-specific data.**

The `kunchenguid/firstmate` repository implements a strict governance model through hard-coded safety contracts. These **firstmate hard rules and project boundary restrictions** ensure that the AI automation layer can orchestrate workers and inspect code without ever exceeding the captain's authority over state changes.

## The Five Immutable Hard Rules in AGENTS.md

The safety contracts are enumerated in [`AGENTS.md`](https://github.com/kunchenguid/firstmate/blob/main/AGENTS.md) (lines 21‑30) and ordered by priority. Each rule represents an absolute constraint that cannot be overridden by configuration.

### 1. Never Write to a Project

Firstmate must not edit, commit, or run any state-changing command inside the `projects/` tree or any cloned worktree. The only permissible mutations occur through guarded initialization, fleet-sync, second-mate sync, self-update, or a **concrete captain-approved operation** that receives explicit authorization at the moment of request. This rule is documented in [`AGENTS.md`](https://github.com/kunchenguid/firstmate/blob/main/AGENTS.md) lines 21‑27.

### 2. Never Merge a PR Without the Captain’s Explicit Word

Even when a project’s *yolo* posture permits routine merges, Firstmate will only execute a merge after the captain provides a direct instruction. See [`AGENTS.md`](https://github.com/kunchenguid/firstmate/blob/main/AGENTS.md) lines 28‑29 for the specific constraint.

### 3. Never Tear Down Unlanded Work

Uncommitted changes must never be discarded automatically. A teardown is only permitted after the crew’s *scout* report exists and the shared decision-hold gate has been satisfied. This protection appears in [`AGENTS.md`](https://github.com/kunchenguid/firstmate/blob/main/AGENTS.md) lines 30‑33.

### 4. Crewmates Never Address the Captain

All communication from workers (crewmates) flows exclusively through Firstmate, ensuring a single, audited channel. Direct crew-to-captain interaction is prohibited according to [`AGENTS.md`](https://github.com/kunchenguid/firstmate/blob/main/AGENTS.md) lines 34‑36.

### 5. Report Outcomes Faithfully

If a task fails, Firstmate must state the failure plainly with supporting evidence. This transparency requirement is defined in [`AGENTS.md`](https://github.com/kunchenguid/firstmate/blob/main/AGENTS.md) lines 37‑38.

## Project Boundary Restrictions and Directory Isolation

The repository enforces physical and logical boundaries through directory permissions and git-ignore patterns defined in [`AGENTS.md`](https://github.com/kunchenguid/firstmate/blob/main/AGENTS.md) (lines 40‑45 and 54‑55).

### The projects/ Directory Is Read-Only

The `projects/` directory contains cloned repositories that Firstmate may only *inspect*. Any mutation must proceed through the hard-rule exception described in Rule 1. According to [`AGENTS.md`](https://github.com/kunchenguid/firstmate/blob/main/AGENTS.md) lines 54‑55, this path is *read-only except under hard rule 1’s concrete captain-approved project operation exception*.

### Private Data and Git-Ignored Paths

Private, captain-specific data lives outside the repository in `.env`, `data/`, `state/`, `config/`, `projects/`, and `.no-mistakes/`. These paths are **git-ignored** and remain untouched unless the captain explicitly authorizes an operation involving them, as specified in [`AGENTS.md`](https://github.com/kunchenguid/firstmate/blob/main/AGENTS.md) lines 40‑45.

### Shared Tracked Material and the No-Mistakes Pipeline

All changes to shared tracked material must traverse the **no-mistakes pipeline**—a guarded PR-based workflow—unless a captain-approved exception exists. This category includes:
- [`AGENTS.md`](https://github.com/kunchenguid/firstmate/blob/main/AGENTS.md)
- [`README.md`](https://github.com/kunchenguid/firstmate/blob/main/README.md)
- [`CONTRIBUTING.md`](https://github.com/kunchenguid/firstmate/blob/main/CONTRIBUTING.md)
- [`.tasks.toml`](https://github.com/kunchenguid/firstmate/blob/main/.tasks.toml)
- `.github/workflows/`
- `bin/`
- `.agents/skills/`
- `skills/`

These constraints are detailed in [`AGENTS.md`](https://github.com/kunchenguid/firstmate/blob/main/AGENTS.md) lines 41‑45.

## Code Examples: Requesting Captain Approval vs. Blocked Operations

Attempting to mutate project state without explicit approval fails by design. The following examples demonstrate blocked requests versus proper captain-authorized workflows.

```python

# ❌ Attempting to edit a file inside a cloned project will be blocked

# (Firstmate would reject the request unless the captain explicitly approves)

# Example pseudo-command that Firstmate would refuse:

firstmate.edit("projects/example-repo/src/main.py", new_content)

# ✅ Proper way – ask the captain for a concrete operation

firstmate.request(
    action="edit",
    target="projects/example-repo/src/main.py",
    reason="Fix typo in logging message",
    captain_approval=True   # captain must explicitly say "yes"

)

```

```bash

# ❌ Directly running a git commit inside a cloned project from a crewmate

bin/fm-send.sh "git commit -am 'auto-fix'"   # will be ignored; crew-mate cannot speak to captain

# ✅ Using Firstmate’s approved workflow (creates a PR via the no-mistakes pipeline)

bin/fm-spawn.sh --project example-repo --mode ship \
    --brief "$(cat <<'EOF'
Task: Fix typo in src/main.py
Acceptance: Unit tests pass, PR merged
EOF
)"

```

## Key Files That Enforce Safety Contracts

| File | Enforcement Role |
|------|------------------|
| **[`AGENTS.md`](https://github.com/kunchenguid/firstmate/blob/main/AGENTS.md)** | Contains the hard-rule list, layout description, and the immutable contract that Firstmate must obey (lines 21‑38, 40‑45, 54‑55). |
| **[`docs/configuration.md`](https://github.com/kunchenguid/firstmate/blob/main/docs/configuration.md)** | Defines the schema for private configuration (`config/`), including the *crew-harness* and *backend* overrides that influence where Firstmate can act. |
| **[`bin/fm-spawn.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-spawn.sh)** | Central script that launches workers; enforces the *isolated worktree* requirement and validates project boundary compliance. |
| **[`bin/fm-send.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-send.sh)** | Gate-kept communication channel; guarantees crewmates never address the captain directly (hard rule 4). |
| **`data/`** (e.g., [`captain.md`](https://github.com/kunchenguid/firstmate/blob/main/captain.md), [`projects.md`](https://github.com/kunchenguid/firstmate/blob/main/projects.md)) | Stores captain-specific preferences and the registry of cloned projects; kept private and git-ignored. |
| **`projects/`** | Contains cloned repositories; read-only for Firstmate except under a captain-approved exception. |

## Summary

- **Firstmate hard rules** are immutable constraints defined in [`AGENTS.md`](https://github.com/kunchenguid/firstmate/blob/main/AGENTS.md) (lines 21‑30) that prioritize safety over convenience.
- **Rule 1** establishes that the `projects/` directory is read-only; any write operation requires a **concrete captain-approved operation**.
- **Rule 2** mandates explicit captain approval for every merge, overriding any *yolo* posture settings.
- **Rule 3** protects unlanded work from automatic teardown until scout reports and decision-hold gates are satisfied.
- **Rule 4** enforces a single communication channel where crewmates never address the captain directly.
- **Rule 5** requires faithful reporting of all outcomes, including failures.
- **Project boundary restrictions** isolate private data (`.env`, `data/`, `state/`, `config/`, `.no-mistakes/`) and mandate the **no-mistakes pipeline** for changes to shared tracked material.

## Frequently Asked Questions

### Can Firstmate ever edit files inside the projects/ directory?

Yes, but only under the specific **concrete captain-approved operation** exception defined in hard rule 1 ([`AGENTS.md`](https://github.com/kunchenguid/firstmate/blob/main/AGENTS.md) lines 21‑27). Standard automated editing is blocked; the captain must explicitly authorize the specific operation at the moment of request.

### What happens if a crewmate tries to communicate directly with the captain?

The communication is ignored. Hard rule 4 ([`AGENTS.md`](https://github.com/kunchenguid/firstmate/blob/main/AGENTS.md) lines 34‑36) stipulates that **crewmates never address the captain**; all worker communication must flow through Firstmate via the [`bin/fm-send.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-send.sh) gate-keeping mechanism.

### Which files must go through the no-mistakes pipeline?

Changes to shared tracked material—including [`AGENTS.md`](https://github.com/kunchenguid/firstmate/blob/main/AGENTS.md), [`README.md`](https://github.com/kunchenguid/firstmate/blob/main/README.md), [`CONTRIBUTING.md`](https://github.com/kunchenguid/firstmate/blob/main/CONTRIBUTING.md), [`.tasks.toml`](https://github.com/kunchenguid/firstmate/blob/main/.tasks.toml), `.github/workflows/`, `bin/`, `.agents/skills/`, and `skills/`—must use the PR-based no-mistakes pipeline unless a captain-approved exception exists ([`AGENTS.md`](https://github.com/kunchenguid/firstmate/blob/main/AGENTS.md) lines 41‑45).

### Where are the hard rules prioritized in the source code?

The hard rules are listed and prioritized in **[`AGENTS.md`](https://github.com/kunchenguid/firstmate/blob/main/AGENTS.md) lines 21‑30**, with each subsequent rule occupying specific line ranges (e.g., lines 21‑27 for Rule 1, lines 28‑29 for Rule 2) within the kunchenguid/firstmate repository.