📚 AI 工程与智能体教程站

English

简体中文

English

简体中文

Chapter 16 · Capstone 1: Building a Personal Dev Fleet ​

Chapter goals: Build and run through the first complete FirstMate fleet链路 from scratch — install prerequisites, launch the firstmate, complete a scout research task and a ship delivery task, and experience the "talk to one agent, ship with a crew" workflow firsthand.

16.1 Capstone Blueprint and Acceptance Criteria ​

This chapter is anend-to-end minimal closed loop: you (captain) talk only to the firstmate; it spawns crewmates (crewmate) that work in isolated git worktrees; finally it delivers a PR or investigation report back to you.

text
You issue a request
   │
   ▼
firstmate (sole liaison)
   │  Checks toolchain → clones project to projects/ → spawns crewmate
   ▼
crewmate (autonomous agent in a tmux window)
   │  Works in a treehouse worktree
   ├── scout: produces data/<id>/report.md investigation report
   └── ship: pushes branch → opens PR → waits for your merge authorization

After completing this chapter, you should be able to check off this acceptance list:

  • [ ] firstmate loaded AGENTS.md in a supported harness and addresses you as captain;
  • [ ] a scout task produced a persisted investigation report;
  • [ ] a ship task produced a real PR;
  • [ ] merge happened only after you explicitly said so.

16.2 Prerequisites: Four-Piece Check ​

Per the official Quick Start, running firstmate requires three categories of prerequisites. Confirm each in the terminal:

bash
# 1) Git and GitHub CLI, with GitHub auth completed
git --version
gh --version
gh auth status        # If not authenticated: gh auth login and follow the wizard

# 2) Session backend: tmux is the reference default backend
tmux -V               # If error: brew install tmux or sudo apt install tmux

# 3) Any one co-primary harness (pick one of three)
claude --version      # Claude Code
pi --version          # Pi
grok --version        # Grok CLI

Three官方 notes to remember:

  1. Pick one of the three co-primaries: Claude Code, Grok, and Pi are equal co-primary recommendations. Codex and OpenCode are also validated but have more harness-related tradeoffs.
  2. --trust is needed only once per clone: Grok requires --trust to加载 project hooks and the turn-end guard (or authorize inside the session with /hooks-trust); Pi approves the project trust prompt on first launch, letting .pi/extensions/*.ts auto-load.
  3. Ask before installing: firstmate self-checks the toolchain on startup; when tools are missing, itasks for your consent before installing — it never自作主张 modifies your machine.

16.3 Clone the Repo and Take First Sail ​

FirstMate has no App to install: the cloned repo itself is the distro. Enter the directory and launch any co-primary harness — AGENTS.md takes over:

bash
gh auth login                                   # If you haven't already
git clone https://github.com/kunchenguid/firstmate
cd firstmate

claude        # Or pi, or grok --trust

The first message after launch should use the official greeting to verify identity loaded:

text
> ahoy! are you the first mate?

What you should see: the reply includes an address to "captain" (this is the AGENTS.md强制要求), with a touch of nautical seasoning but clear technical content. If it自称 a different role or does not address captain, the project instructions were not loaded — the most common cause is launching the harness in the wrong directory.

16.4 Prepare a Practice Project ​

ship/scout tasks both需要 a real GitHub project as the靶子. Prepare a small repo you own (or fork an开源小工具), with minimal requirements:

  • At least one reproducible小 bug or one明确待办 issue;
  • A repo you own (so the PR flow can completefully).

No need to克隆 to local beforehand — firstmate will clone the project into its own projects/ directory and keep that目录read-only; allactual modifications happen in the crewmate's isolated worktree. This边界 comes from Hard Rule 1 (Never write to a project): the firstmate itself does not写 your project; changes are made by the crewmate.

16.5 First Scout Task: Read-Only Research ​

A scout taskproduces no code changes, never pushes; the deliverable is a persisted独立 investigation report. Issue in natural language:

text
> dispatch a scout to research the myname/tiny-api repo:
> list the directory structure, entry files, test organization,
> and point out where error handling is weakest. Report only; do not change anything.

What you should see:

  1. firstmate restates the task要点 and spawns a crewmate (a new tmux window appears);
  2. After the crewmate completes, the report lands at data/<task-id>/report.md, along with a decision inventory (事项清单 for you to decide);
  3. firstmate relays the结论摘要 to you, rather than making youread the raw output yourself.

You can直接验证 the artifact persisted:

bash
cat data/<task-id>/report.md

16.6 First Ship Task: Deliver a PR ​

Now for a ship task — this time the crewmate will改 code and开 a PR:

text
> fix the flaky login test in myname/tiny-api and open a PR

What you should see:

  1. firstmate determines the task形态 is ship, selects the project mode (direct-PR for this练习项目), writes the brief, and spawns a crewmate;
  2. The crewmate works in anisolated worktree; you can观察 with tmux list-windows -t firstmate;
  3. After completion, a PR is opened; firstmate reports the PR URL and risk level;
  4. Merge does not happen automatically — you must explicitly say "merge it" (Hard Rule 2).
text
> alright merge it

Only after this explicit word does the firstmate执行 the merge.

16.7 Chapter Summary ​

  • FirstMate is an agent distro: clone the repo, launch a harness, and AGENTS.md takes over;
  • Prerequisites: git + gh + tmux + one co-primary harness;
  • Two task shapes: scout (report only, never push) and ship (changes code, opens PR);
  • Worktree隔离: each crewmate works in an independent clean worktree;
  • Hard Rule 2: merge requires the captain's explicit word — no automatic merges.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. What is FirstMate?

2. What are the three co-primary harnesses?

3. What happens when you say "alright merge it" to the firstmate?

4. Why does the firstmate not clone projects to your local machine?

🛠️ Hands-On Exercises ​

  1. Complete steps 16.2–16.6 on your machine: install prerequisites, clone firstmate, launch with your chosen harness, and跑 through one scout task and one ship task.
  2. Verify the acceptance checklist: AGENTS.md loaded, scout report persisted, real PR opened, merge required explicit captain word.
  3. Deliberately say "merge it" without a prior PR report; observe the firstmate's response and verify it refuses to merge without context.

Fleet launched. Next, Capstone 2: Multi-Project Parallel Delivery Pipeline.