Chapter 14 · Secondmate: Persistent Deputy and Isolated Charter

Chapter goals: Understand the positioning and isolation model of the secondmate (第二副手), learn to configure its launch via config/secondmate-harness, and master the key boundary "secondmates do not spawn secondmates."

14.1 Why a Second Mate Is Needed

As the fleet scale grows, a common问题浮现: all crewmates are dispatched from the主 home; as task types多起来, the main firstmate's supervision面 gets broader and broader — frontend fixes, backend audits, and doc patrols混 in the same backlog and同一套 state.

FirstMate's solution is not to introduce a new architecture, but to copy the existing architecture:

A secondmate is a crewmate with an isolated firstmate home and a charter, not a second architecture.

In other words, the secondmate本质上仍然是一个 ordinary direct report（普通直接下属）— it接受 the主 firstmate's routing and supervision just like a普通 crewmate; the difference is that it runs in anisolated, persistent firstmate home and carries a charter（章程）defining its responsibility域.

The收益 of this design:

• 职责域划分: each secondmate only accepts work within its charter scope; routing is by work nature, not by clone清单;
• 状态隔离:各自 backlog, state, projects互不干扰;
• 可长期存在: the secondmate is a persistent entity; idle queues are健康态; no need to销毁 when not in use.

14.2 Isolated FM_HOME: One Home per Secondmate

AGENTS.md has a明确约定 for this:

Each secondmate has a persistent isolated FM_HOME, including its own state, backlog, projects, and session lock.

Recalling the layout knowledge from Chapter 5: FM_HOME selects a instance-private data/, state/, config/, projects/. For the secondmate, this means:

Main home (PRIMARY)
├── FM_HOME=~/firstmate-home-main
│   ├── data/backlog.md          # Main backlog: only records work items
│   ├── data/secondmates.md      # Secondmate routing table
│   ├── state/                   # Main home runtime records
│   └── projects/                # Main home project clones
└── Registered secondmate
    └── FM_HOME=~/firstmate-home-infra   # Completely independent second home
        ├── data/backlog.md      # Its own backlog queue
        ├── state/               # Its own runtime records + session lock
        ├── config/              # Its own local运营配置
        └── projects/            # Projects cloned in its own home

Key points to展开:

1. Independent session locks: each home has its own会话锁; the two homes' bootstrap流程互不竞争;
2. Backlog分账: work routed to a secondmate is recorded in that secondmate home's own backlog, not the主 backlog;
3. Projects各自克隆: whatever projects the secondmate home needs are cloned in its own home; the main home's projects/ is invisible to it.

data/secondmates.md is the主 home's local and remote secondmate routing table (本地与远程 secondmate 路由表), maintained by the secondmate seed辅助脚本, recording each registered secondmate's位置信息.

14.3 Charter: The Written Boundary of Responsibility域

Each secondmate carries a charter brief. In the data/ layout you can see its存放形式:

data/
├── <id>/brief.md    # per-task crewmate brief,
│                    # or per-secondmate charter brief when kind=secondmate

The charter answers the question: "What class of work does this secondmate负责?" The routing rule the主 firstmate follows is:

Route by the nature of the work against each registered secondmate scope.

即按工作的性质对照各 secondmate 的注册范围来路由, not by which repo happens to be registered under whom. If no suitable secondmate scope can承接 a piece of work, use the主 home to handle it, or讨论创建 a new secondmate.

Two additional routing纪律 worth remembering:

• Work matching a scope is默认 sent to the corresponding secondmate, unless it is blocked or the captain explicitly redirects;
• Do not翻 the secondmate's chat window — marked路由 replies return via status or文档指针.

14.4 Launch Config: config/secondmate-harness

The主 home uses config/secondmate-harness to specify which harness启动 the secondmate agent:

# config/secondmate-harness (LOCAL, gitignored)
# Format: <harness> [<model>] [<effort>], three segments on one line

# Example: launch secondmate with Claude Code
claude

# Example: specify model and effort
pi sonnet medium

The fallback order is the key记忆点 of this chapter:

Does config/secondmate-harness exist and有效?
 ├─ Yes → Use it to启动 SECONDMATE
 └─ No (missing or value is default)
      └─ Fallback to config/crew-harness
           └─ Further fallback to the harness the firstmate itself is using

Note the分工 with config/crew-harness:

File	Controls	Inheritance behavior
config/crew-harness	Crewmates dispatched by this home	Inherited as the literal file: the具体的 primary adapter value also controls the secondmate home's own crewmates
config/crew-dispatch.json	Per-task harness/model/effort selection rules	Inherited by secondmate homes
config/secondmate-harness	How the PRIMARY启动s the SECONDMATE	NOT inherited into secondmate homes

The inheritance semantics of crew-harness is特殊——it is "inherited as the literal file": if the主 home writes claude, then the secondmate home also uses claude when dispatching its own crewmates. But secondmate-harness belongs only to the primary side.

14.5 Key Boundary: Secondmates Do Not Spawn Secondmates

This is the most important安全设计 in the entire secondmate体系:

The primary's own setting; NOT inherited into secondmate homes (secondmates do not spawn secondmates).

Why designed this way? Because once secondmates are allowed to create their own secondmates, the fleet would form a tree structure of任意 depth, bringing三类问题:

1. 监督链失控: the主 firstmate's recovery protocol explicitly写着 "Do not reconstruct or supervise a secondmate's child tree from the main home" — the主 home does not跨层 rebuild or supervise子树. Beyond two layers, the确定性 of故障恢复 cannot be guaranteed;
2. 责任稀释: Hard Rule 4 requires所有沟通经由 firstmate 汇报给 captain; the more中间层, the worse the信息保真度;
3. 资源不可控: nested spawning would let the agent count growexponentially.

So FirstMate严格限制 the层级 to two generations: captain → firstmate → {crewmate, secondmate}, and the secondmate can only have普通 crewmates under it:

you (the captain)
 └── firstmate (main home, PRIMARY)
      ├── crewmate × N        ← decided by config/crew-harness / crew-dispatch.json
      └── secondmate × M      ← decided by config/secondmate-harness
           └── its own crewmate × K (controlled by the inherited crew-harness)
                (stop here; no third-generation secondmate allowed)

14.6 secondmate-provisioning: The Supply Flow Overview

Create, provision, validate, launch, hand off backlog, recover, push inherited materials, retire a secondmate home, and edit data/secondmates.md — all these operations are负责 by the internal skill secondmate-provisioning (covered in Chapter 13's .agents/skills/ agent-only skill system). As the captain, you only需要知道 the flow skeleton:

1.提出需求     "I want to set up a dedicated secondmate for a长期维护的基础设施项目"
2.加载技能     The firstmate loads secondmate-provisioning
3.创建home     Establish an独立 FM_HOME; write the charter brief
4.注册路由     Update the data/secondmates.md routing table
5.继承材料     Sync inherited config per allowlist (e.g., crew-harness, crew-dispatch.json)
6.校验启动     After validation passes, launch per secondmate-harness
7.日常路由     Work within scope自动 routed to that home; replies return via status/docs
8.退役         Only executed when the captain or主 firstmate明确 decides,
               and only when that home has no进行中工作

Two补充纪律:

• A secondmate is idle by default and acts only on work routed by the main firstmate. The secondmate不会自找活干;
• Persistent entities do not enter the backlog. AGENTS.md明确: "It tracks work items only, never agents; persistent secondmates never appear as backlog items." The secondmate is recorded in the registry and runtime state, never managed as a积压工作项.

14.7 When to Introduce a Secondmate

Introducing a secondmate has成本 (one more home to维护, one more charter to写), so it only pays off in these场景:

• 职责域长期稳定: e.g., a基础设施 monorepo that需要持续巡检, or a fixed内容生产流水线;
• 状态需要硬隔离: the主 home backlog已混杂多个领域, and you want each领域's任务队列,学习记录 (learnings), and captain preferences managed分开;
• 并行规模超出单 home舒适区: multiple长期项目推进 simultaneously, each needing an独立 session lock and projects clone.

Conversely,偶发的并行需求用普通 crewmate就够了——worktree 隔离 (Chapter 9) already guarantees互不冲突.

14.8 Chapter Summary

• Secondmate = a crewmate with an isolated persistent firstmate home and a charter; not a second architecture;
• Each secondmate has its own FM_HOME (state, backlog, projects, session lock) — completely隔离 from the主 home;
• Charter answers "what work class does this secondmate负责"; routing is by工作性质, not by repo registration;
• config/secondmate-harness controls how the primary启动s the secondmate; NOT inherited into secondmate homes;
• Key boundary: secondmates do not spawn secondmates — the层级 is严格 limited to two generations;
• Introduce a secondmate only when职责域长期稳定,状态需要硬隔离, or并行规模超出单 home舒适区.

🧪 随堂测验

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

1. What is a secondmate in FirstMate?

2. What is the key boundary of the secondmate system?

3. How is routing to a secondmate determined?

4. When is it worth introducing a secondmate?

🛠️ Hands-On Exercises

1. Register a secondmate for a long-term infrastructure project; verify the独立 FM_HOME is created with its own state, backlog, and projects.
2. Dispatch a task that matches the secondmate's charter scope; verify the work is routed to the secondmate home and the reply returns via status.
3. Attempt to have the secondmate spawn its own secondmate; verify the system拒绝 and the层级 remains at two generations.

Secondmate understood. Next, Remote fleet, Relay, and the ops toolbelt.