Chapter 8 · Crewmate Delegation: Ship Tasks and Scout Tasks

Chapter goals: Understand FirstMate's two task shapes — ship tasks delivering changes and scout tasks producing knowledge — master the intake阶段's task dispatchcontract and delegation mechanism.

8.1 DesignMotivation for Two Task Shapes

When you tell the firstmate "fix this flaky test" vs "investigate why the login endpoint is slow", these are两种完全不同的请求: the former expects code to be changed and shipped; the latter expects a credible investigation conclusion. Mixing them in one task shape leads to two failures — the code that should change doesn't; the code that shouldn't change gets乱改.

FirstMate therefore built two task shapes into the任务层 (officially called "Two task shapes"):

ship task   changes the project; ships per project mode (no-mistakes / direct-PR / local-only)
scout task  produces an独立 investigation report; never pushes

This distinction is written in the架构文档; the "when to dispatch a scout"判断规则 is owned by the intake and authority contract in AGENTS.md. We拆解 each below.

8.2 Ship Tasks: Delivering Authorized Changes

The ship task's goal is authorized project changes, ultimately delivered as a PR, an approved local merge, or whichever project mode defines. Its complete生命周期:

captain request → firstmate intake (determine task shape and delivery mode)
              → fm-brief.sh writes the task brief
              → fm-spawn.sh启动 crewmate in a clean worktree
              → crewmate实施 + verify per mode
              → PR / approved local merge
              → teardown清理 worktree

Note the Hard Rule 1 division of labor: the firstmate itself does not write project code — it only reads projects/, writes the guarded backlog/briefs/state; the ones actually touching项目 files are the crewmates it spawns and supervises.

8.3 Scout Tasks: Producing Knowledge, Not Changes

Scout tasks适用 for investigation, diagnosis, planning, reproduction, or auditing work. Their deliverable is an独立 report:

data/<id>/report.md     ← the scout's唯一正式交付物; retained after teardown

The close-out flow after the report is complete (the scout branch in the architecture diagram):

report.md complete → decision inventory (unresolved decisions清单) → relay findings (relaying discoveries to captain) → teardown

Two关键安全设计:

1. Scout worktrees are declared as scratch (草稿区). Per Hard Rule 3, they are only discardable after the reportexists AND the shared unresolved-decision completion gatepasses;
2. Diagnostic conclusions are not authorization to change code. AGENTS.md明确写道: "A diagnostic request, report, recommendation, or implementation-ready finding is evidence, not authorization to change code." — a scout finding a bug does not等于 permission to fix it on the side; fixes必须走新的 ship authorization.

8.4 Intake Contract: When to Dispatch a Scout

Not every question warrants opening a scout. The判断规则 in AGENTS.md is克制:

Only dispatch a scout when任一满足:
① The captain explicitly requests an独立的知识 or design deliverable;
② Unresolved uncertainty would materially改变 "whether to build" or "what to build".

Two反浪费 constraints同时成立:

• If现有证据 already能 answer an信息性问题, the firstmate应直接转达答案, not发起 a "design-only scout";
• It isnever allowed to一方面给出 a "good-enough方案", while simultaneously launching a设计调研 that isn't expected to改变 that plan — this is纯粹的 token浪费.

When the实现意图 is unclear, the正确姿势 is to answer first, and if needed ask the captain a简洁的实现澄清问题 — not dispatch speculative design work.

8.5 Delegation Mechanism: Worktree Gate and Concurrency Rules

Spawn is not随便启动一个进程. fm-spawn.sh has两道硬门禁:

Gate 1: The task path must be a真实的 git worktree root,
        and must be distinct from the project主 checkout.
        Otherwise refuses to start.

Gate 2: base-freshness — before each new ship/scout launches,
        the clean task worktree must first对齐 origin default branch's fetched tip.
        Baseline unsafe or unverifiable → spawn停止.

Gate 2 ensures each crewmate starts从最新基线, preventing并行工作建立在过期代码上.

Regarding concurrency, AGENTS.md's rules are同样明确:

Default: as long as each change is independently implementable and independently verifiable,
         and the chosen delivery path can reconcile普通 rebase/conflicts,
         dispatch immediately in parallel; no concurrency上限.

Serial: only when there are真实 semantic dependencies, shared mutable external state,
        or incompatible concurrent migrations等具体不安全条件.
        — "will edit the same file" alone is not a reason to wait.

Additionally, the ship task's delivery mode and yolo merge posture are locked at intake: passed explicitly to the brief, explicitly to spawn and any scout — commands refuse to guess the值 they consume.

8.6 Escalation Principle: Only Escalate Real Decisions

Once the fleet is运转, the captain's greatest fear is being淹没 in例行 notifications. FirstMate's escalation原则:

The firstmate escalates only真正的决策 to the captain;
routine notifications are handledby the bash watcher自行 (zero-token supervision, see Chapter 11).

Paired with the crewmate通信纪律 (Hard Rule 4: crewmates never directly对话 the captain; all通信 flows through the firstmate), this forms a干净的指挥链:

captain ⇄ firstmate ⇄ each crewmate (各自的 session endpoint)

If the captain直接在某个 crewmate window插话, that intervention is treated as authoritative, but is reconciled at the next supervision review — ensuring状态最终一致.

8.7 Chapter Summary

• FirstMate has只有两种任务形态: ship delivers authorized changes; scout delivers data/<id>/report.md知识报告 and never pushes;
• Scout reports are保留 after teardown; their worktree is scratch, discardable only after the report exists and the shared unresolved-decision gatepasses;
• The intake contractuses scout克制ly: only when the captain explicitly requests an独立知识/设计 deliverable, or when unresolved uncertainty会实质改变建什么 — existing evidence that可直接回答 is forwarded直接;
• Spawn has两道硬门禁: a真实且异于主checkout的 worktree root + base-freshness对齐 origin default branch tip;
• Independently implementable changesdispatch立即 in parallel with no concurrency上限; only真 semantic dependencies force serial; the delivery mode is locked at intake and passed显式; commands refuse to guess.

🧪 随堂测验

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

1. What is the scout task's正式交付物?

2. Per Hard Rule 3, when can a scout's worktree be discarded?

3. Which scenario warrants dispatching a scout task?

4. What does the fm-spawn.sh base-freshness gate require?

🛠️ Hands-On Exercises

1. Classify the following requests as ship or scout, and写出理由 using the 8.4 intake contract: (a) "check why CI has been slow recently"; (b) "add dark mode to the settings page"; (c) "evaluate whether Redis or Memcached better fits our cache layer — the conclusion会影响架构选型". Which one is the "existing evidence可直接回答,不应派 scout"反例 candidate? Explain your判断依据.
2. Manually simulate the base-freshness gate: create a test仓库 where the主 checkout has a worktree落后于 origin/main (or simulate an过期 tip with git update-ref); observe fm-spawn.sh's refusal behavior; then fetch the worktree to latest and重试;对比 the two results and record the metadata差异.
3. Design a three-task parallel delegation方案: on the same repository, simultaneously "fix the flaky test", "补 API docs", and "upgrade dependencies minor version". Check each task against the 8.5 concurrency rules for "independently implementable + independently verifiable + delivery path can reconcile conflicts"; if any task must be串行, point out the具体不安全条件 (note: "editing the same file" alone does not count as a reason).

Delegation understood. Next, Worktree Isolation and Parallel Delivery.