Firstmate Hard Rules and Project Boundary Restrictions

Firstmate hard rules are immutable safety contracts defined in 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 (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 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 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 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 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 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 (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 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 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
• README.md
• CONTRIBUTING.md
• .tasks.toml
• .github/workflows/
• bin/
• .agents/skills/
• skills/

These constraints are detailed in 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.

# ❌ 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"

)

# ❌ 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	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	Defines the schema for private configuration (config/), including the crew-harness and backend overrides that influence where Firstmate can act.
bin/fm-spawn.sh	Central script that launches workers; enforces the isolated worktree requirement and validates project boundary compliance.
bin/fm-send.sh	Gate-kept communication channel; guarantees crewmates never address the captain directly (hard rule 4).
data/ (e.g., captain.md, 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 (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 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 lines 34‑36) stipulates that crewmates never address the captain; all worker communication must flow through Firstmate via the bin/fm-send.sh gate-keeping mechanism.

Which files must go through the no-mistakes pipeline?

Changes to shared tracked material—including AGENTS.md, README.md, CONTRIBUTING.md, .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 lines 41‑45).

Where are the hard rules prioritized in the source code?

The hard rules are listed and prioritized in 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.

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