Your first voyage

A guided first session. Register a project, choose its delivery posture, dispatch a ship task and a scout, watch the crew, answer a decision, merge, and clean up.

This page walks through a realistic first session, from an empty home to a merged PR. The chat lines are illustrative: the first mate words things its own way. Every command, file and state named here is real.

Step 1 — Let it set up its toolchain#

On a fresh home the digest usually contains MISSING: lines. The first mate lists each tool with what it is for, then asks once for consent:

Captain, before I can dispatch anything I need a few tools: no-mistakes (validation
pipeline), gh-axi, chrome-devtools-axi, tasks-axi, quota-axi and treehouse.
Shall I install them?
> yes

The rule is "detect, then consent, then install". Nothing is installed silently, and no work is dispatched until the tools and GitHub auth check out. NEEDS_GH_AUTH means you must run gh auth login yourself; it is interactive.

Step 2 — Add a project and choose its posture#

> add my repo github.com/you/xyz

The first mate loads the project-management skill and clones the repo into projects/xyz. Then it asks how that project should ship. This is a real decision, so think about it:

You can add +yolo so the first mate merges green, in-scope work without asking you. It is off by default and you must grant it explicitly. It still never merges red, and it never merges anything destructive or security-sensitive.

The result is one line in data/projects.md, for example:

- xyz [no-mistakes] - web app for xyz (added 2026-09-26)

A fuller entry might read [no-mistakes +yolo branch=kun/]. An unregistered project always falls back to no-mistakes with yolo off, and the first mate tells you about the gap.

Step 3 — Ask for two things at once#

> in xyz: fix the flaky login test, and separately figure out why the
  dashboard is slow — I want a report before anyone changes code for that

The first mate classifies each request:

• "fix the flaky login test" becomes a ship task in the project's mode.
• "figure out why ... report before anyone changes code" becomes a scout task. You asked for knowledge, not a change.

For each task it:

1. Writes a brief with bin/fm-brief.sh. The brief has a ## Captain's intent section, which is your words verbatim and never widened, and a ## Firstmate spec section with the build instructions.
2. Resolves which harness, model and effort to use (its default, or your dispatch profiles).
3. Spawns the worker with bin/fm-spawn.sh. It gets a fresh treehouse worktree and a new tmux window fm-<id> (or a Herdr tab).
4. Confirms the worker has started on the brief, clearing any harness trust dialog, and tells you it's under way.

Step 4 — Get on with your day#

While the crew works, the first mate is not spending tokens. A bash watcher (bin/fm-watch.sh) polls every 15s and wakes it only when:

• a worker writes a captain-relevant status (done:, needs-decision:, blocked:, failed:),
• a pane goes stale (idle 240s without proof it is working),
• a PR merge poll, custom check, or Relay mention fires,
• or the heartbeat backstop fires (every 600s, backing off to 7200s).

Keep chatting with it about other things meanwhile. If you're leaving, type /afk, or /quiet if you're staying but want fewer pings. See Daily commands.

Step 5 — A decision reaches you#

Suppose the no-mistakes review flags that the fix changes the login retry behaviour. The worker cannot answer that finding itself. It reports needs-decision. The first mate loads ask-user-authority and does one of two things:

• If the finding is unambiguous (a bug, or restoring already-accepted behaviour), it decides itself and steers the worker.
• If the finding would expand the contract, is a product or architecture call, keeps recurring, or is destructive, it asks you, in one self-contained message:

Captain, one decision on the login-test fix:
- Accepted: make the flaky test deterministic.
- Proposed by review: also change retry backoff from 3 to 5 attempts.
- Smallest option: fix the test only; leave retries alone.
- If yes: slower failure path for real users; if no: the test fix still ships.
I recommend no — keep this PR to the test.
> no, test only

It sends your answer back to the worker with bin/fm-send.sh --resolve-key. If a question is still open when you walk away, it becomes a held backlog item that /bearings lists under Captain's Call until you answer. See Decisions & captain holds.

Step 6 — PR ready, merge it#

When the no-mistakes pipeline and CI are green, the worker reports done: PR <url> checks green. The first mate does not trust that claim on its own:

• fm-crew-state.sh checks that the commit is reachable outside the disposable worktree. If it isn't, the task is reported blocked, not done.
• fm-pr-check.sh records the PR and refuses drafts.

PR ready for review, captain: https://github.com/you/xyz/pull/42
(fix flaky login test - risk: low - CI green)
> merge it

"merge it" is your explicit word. The first mate runs bin/fm-pr-merge.sh. That script re-reads the PR live (open, not a draft, mergeable, no conflicts, every required check green at the current head), merges with --match-head-commit, and confirms the merge actually landed.

Step 7 — Cleanup and the report#

• After landing, bin/fm-teardown.sh returns the worktree to the pool, closes the window, and marks the backlog item Done. It refuses to tear down anything unlanded.
• The scout finishes with data/<id>/report.md. The first mate relays the findings as outcomes and asks whether to act. If you say "fix it", it runs bin/fm-promote.sh, which turns the same scout into a ship task in place, with its context intact.

Step 8 — Tomorrow morning#

> /bearings

You get a four-section digest: Captain's Call (needs you), Recently Landed, Underway, and Charted Next. /ahoy recaps everything since your last message and walks you through any open decisions, one at a time.

Before you reset a long session, run /stow. It saves what the session learned about you and your fleet into data/captain.md and data/learnings.md, so the next session starts smarter.

What you just exercised#