feat: integrate Matt Pocock engineering skills into worker brief contract

.agents/skills/matt-pocock-integration/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: matt-pocock-integration
+description: >-
+  Agent-only routing for combining FirstMate with Matt Pocock's engineering skills.
+  Use when the captain invokes one of those workflows, before translating it into FirstMate work, and before choosing a worker's required skills or agreed testing seams.
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# Matt Pocock skills integration
+
+FirstMate owns the operating system of the work: captain interaction, authority, task classification, worker allocation, isolation, tracker mutation, supervision, delivery, and merge decisions.
+Matt Pocock skills supply engineering methods inside that system.
+When the two prescribe the same concern, keep FirstMate's lifecycle and use the upstream skill only for method.
+For a captain-facing upstream workflow, load its installed skill and apply its interviewing, modeling, or writing method subject to the translations below.
+
+## Translate workflows
+
+| Upstream workflow | FirstMate route |
+|---|---|
+| `grill-me`, `grill-with-docs` | Keep the interview and decisions in the firstmate chat while delegating project investigation to scouts and approved repository changes to ships. |
+| `wayfinder` | Keep the captain-facing decision map with firstmate while using scouts for research or prototypes, publishing planning artifacts through the project's approved path, and requiring separate implementation authorization. |
+| `to-spec`, `to-tickets` | Preserve their planning output and dependency semantics because publishing a spec or tickets does not authorize implementation, while authorized tickets become ordinary FirstMate tasks. |
+| `research`, `prototype`, `diagnosing-bugs` | Dispatch a scout when a separate evidence artifact is needed, retain the scout's report as durable evidence, and promote it only after implementation is authorized. |
+| `implement` | Convert the accepted spec or tickets into ship tasks instead of invoking the upstream workflow inside a worker, where its delegation and final review steps would create a second lifecycle. |
+| `code-review` | Use only when the captain explicitly requests a standalone review deliverable, dispatching it as dedicated review work rather than stacking it on a no-mistakes delivery. |
+| `setup-matt-pocock-skills` | Treat setup as an explicit per-project change that inspects first, obtains the required project decisions, and ships the approved configuration through that project's delivery path. |
+
+If another upstream skill creates subagents, mutates the issue tracker, opens a PR, or owns final review, route those actions through the corresponding FirstMate scout, ship, tracker, or delivery contract instead of running a nested workflow.
+
+## Choose worker methods
+
+Name upstream skills by exact ID in the worker's `## Required skills` subsection.
+Reference the installed skill rather than copying its procedure into the instructions.
+
+Use this starting map, then narrow it to what the task actually needs:
+
+| Work shape | Method skills |
+|---|---|
+| Bug or regression | `diagnosing-bugs`, then `tdd` when an executable regression seam exists |
+| Feature behavior | `tdd` |
+| New or changed interface | `codebase-design`, plus `tdd` when executable behavior changes |
+| Domain terminology or decisions | `domain-modeling` |
+| Agent-consumed instructions | `writing-for-agents` |
+
+Orchestration skills such as `wayfinder`, `research`, and `implement`, and final-review skills such as `code-review`, do not belong in a worker's required-method list.
+The selected delivery contract remains the only final review owner, including no-mistakes when that mode is selected.
+
+## Record the engineering contract
+
+Before dispatch, fill every current ship or scout instruction scaffold as follows:
+
+1. `## Required skills` lists each exact method skill ID as a bullet, or contains only `None - <reason>.` when no upstream method applies.
+2. `## Agreed testing seams` lists the public interfaces already made explicit or agreed with the captain, or `None - <reason>.` when no executable test is appropriate.
+3. The Firstmate specification names relevant `CONTEXT.md` files and ADRs when they exist, without copying their contents.
+
+Do not silently replace a missing required skill with generic advice.
+If no eligible worker can load it, report that blocker and ask whether to install the skill pack or revise the method.
+Load `harness-adapters` before sending any harness-specific skill invocation to a live worker.
+
+## Completion
+
+The worker uses required skills during investigation and implementation, then follows only the existing Definition of done.
+Planning and investigation findings are evidence, not implementation authority.
+No upstream skill changes FirstMate's communication, approval, merge, or cleanup rules.

.pi/extensions/fm-branch-supervision.ts

@@ -2061,6 +2061,39 @@ ${context.command}
     return shell;
   };
 
+  // Pi 0.99.0's stock call fallback now renders the tool's args beside the
+  // bold title (a muted collapsed preview) or as an indented per-arg block
+  // (expanded). The package does not export that formatter, so mirror its
+  // exact output here: calm-off rendering must be byte-identical to stock.
+  const STOCK_COLLAPSED_ARGS_CHARS = 100;
+  const stockToolCallComponent = (
+    name: string,
+    args: unknown,
+    theme: Parameters<NonNullable<ToolDefinition["renderCall"]>>[1],
+    expanded: boolean,
+  ): Text => {
+    const header = theme.fg("toolTitle", theme.bold(name));
+    if (args === null || args === undefined) return new Text(header, 0, 0);
+    const entries: [string, unknown][] =
+      typeof args === "object" && !Array.isArray(args)
+        ? Object.entries(args as Record<string, unknown>)
+        : [["args", args]];
+    if (entries.length === 0) return new Text(header, 0, 0);
+    if (expanded) {
+      const lines = entries.map(([key, value]) => {
+        const text = typeof value === "string" ? value : JSON.stringify(value, null, 2) ?? String(value);
+        return `  ${key}: ${text.replace(/\t/g, "   ").replace(/\r/g, "").split("\n").join("\n    ")}`;
+      });
+      return new Text(`${header}\n${theme.fg("muted", lines.join("\n"))}`, 0, 0);
+    }
+    const pairs = entries.map(([key, value]) => `${key}=${JSON.stringify(value) ?? String(value)}`).join(" ");
+    const preview =
+      pairs.length > STOCK_COLLAPSED_ARGS_CHARS
+        ? `${pairs.slice(0, STOCK_COLLAPSED_ARGS_CHARS - 3)}...`
+        : pairs;
+    return new Text(`${header} ${theme.fg("muted", preview)}`, 0, 0);
+  };
+
   registerFirstmateTool(pi, {
     name: "fm_branch_outcomes",
     label: "Read supervision branch outcomes",
@@ -2071,11 +2104,11 @@ ${context.command}
       recent: Type.Optional(Type.Number({ description: "How many most-recent outcomes to read (default 20)" })),
     }),
     renderShell: "self",
-    renderCall: (_args, theme, context) => {
+    renderCall: (args, theme, context) => {
       if (calmPresentation.stockExportRendering) throw new Error("Use Pi stock export rendering");
       if (calmHides("assistant-tool-call")) return new Container();
       const shellState = context.state as OutcomesToolShellState;
-      shellState.call = new Text(theme.fg("toolTitle", theme.bold("fm_branch_outcomes")), 0, 0);
+      shellState.call = stockToolCallComponent("fm_branch_outcomes", args, theme, context.expanded);
       return refreshOutcomesToolShell(shellState, theme, context);
     },
     renderResult: (result, options, theme, context) => {
@@ -2133,11 +2166,11 @@ ${context.command}
       through: Type.Number({ description: "The highest outcome sequence number this conversation has processed" }),
     }),
     renderShell: "self",
-    renderCall: (_args, theme, context) => {
+    renderCall: (args, theme, context) => {
       if (calmPresentation.stockExportRendering) throw new Error("Use Pi stock export rendering");
       if (calmHides("assistant-tool-call")) return new Container();
       const shellState = context.state as OutcomesToolShellState;
-      shellState.call = new Text(theme.fg("toolTitle", theme.bold("fm_branch_processed")), 0, 0);
+      shellState.call = stockToolCallComponent("fm_branch_processed", args, theme, context.expanded);
       return refreshOutcomesToolShell(shellState, theme, context);
     },
     renderResult: (result, _options, theme, context) => {

AGENTS.md

@@ -543,6 +543,7 @@ Preserve durable structured identifiers, dependencies, and completion artifact l
 Use its scaffold as the contract, then fill `## Captain's intent` (`{TASK}`) with the captain's own ask and any boundary the captain stated, plus the context needed to read it, including the substance of any report, decision, or PR the ask refers to; never widen the ask there into a general goal or an enumerated coverage list, because the reviewer treats that subsection as acceptance criteria.
 Fill `## Firstmate spec` (`{FIRSTMATE_SPEC}`) with only the build instructions that ask requires, naming what stays out of scope when the ask is narrow; a generalization, consistency sweep, or extra hardening the captain did not ask for is follow-up work to note, not scope to add.
 `bin/fm-dod-lib.sh` owns intent authoring without added speaker labels or direct address, its provenance markers, what a no-mistakes worker may pass as `--intent`, and the string's self-sufficiency rule.
+`matt-pocock-integration` owns the task-specific required-skill and agreed-testing-seam fields plus the precedence between external engineering methods and FirstMate's lifecycle.
 Keep additions task-specific rather than repeating lifecycle instructions, and alter generated sections only when the task genuinely differs from the standard shape.
 
 Every ship brief must retain the worktree-isolation assertion and stop if launched in the primary checkout.
@@ -581,6 +582,7 @@ These skills are not captain-invocable; load them only at their precise triggers
 - `fmx-respond` - load on an `x-mention <request_id>` `check:` wake to handle the mention, on an `x-mode-error ...` `check:` wake to report the Relay configuration blocker, on a `public-followup ...` `check:` wake or a startup-surfaced public commitment, and on any milestone or terminal wake for a Relay-linked task before posting its completion follow-up; relevant only when Relay is on.
 - `firstmate-codexapp` - load before coordinating a visible Codex Desktop thread, evaluating a Codex App backend request, or reconciling Codex Desktop host-tool smoke evidence for Firstmate work.
 - `firstmate-coding-guidelines` - load before changing firstmate's shared, tracked material, as defined by section 1's list, whether editing directly or briefing a crewmate for a firstmate-repo task.
+- `matt-pocock-integration` - load when the captain invokes a Matt Pocock workflow, before translating one into FirstMate work, and before selecting a ship or scout's required skills or agreed testing seams.
 
 ## 14. Relay
 

README.md

@@ -45,6 +45,7 @@ Launching a supported harness inside it for your primary session instantiates yo
 - **A visible crew** - every crewmate works in its own tmux window, Herdr tab, or experimental zellij tab, cmux workspace, or Orca terminal you can watch or type into; the first mate reconciles.
 - **Disposable worktrees** - each task runs in a clean [treehouse](https://github.com/kunchenguid/treehouse) git worktree, or an Orca-managed worktree when `backend=orca`, so parallel work on one repo never collides.
 - **Two task shapes** - ship tasks deliver authorized changes; scout tasks leave standalone investigation reports when the intake contract warrants separate research.
+- **Composable engineering methods** - optional Matt Pocock skills can supply diagnosis, TDD, module-design, and domain-modeling methods while FirstMate keeps orchestration and delivery ownership.
 - **Explicit project modes** - each project ships via `no-mistakes`, `direct-PR`, or `local-only`, with an optional `+yolo` merge-autonomy flag.
 - **Optional secondmates** - opt in to persistent second mates that run from isolated firstmate homes with their own `FM_HOME`, state, projects, and session lock, either locally or as a whole home on an SSH-reachable host, with guarded updates and recovery that never turns an unavailable remote route into a local replacement.
 - **Event-driven, zero-token supervision** - a bash watcher sleeps on the fleet and wakes the first mate only when something needs you; verified primary harnesses also get a turn-end backstop that blocks or follows up on a blind stop when work is under way and supervision is not live.
@@ -214,6 +215,7 @@ Firstmate's skills live in two separate places with different audiences:
 
 - [docs/architecture.md](docs/architecture.md) - maintainer architecture for the crew, supervision, worktrees, secondmates, and project modes.
 - [docs/configuration.md](docs/configuration.md) - environment variables, `FM_HOME`, runtime backend selection, optional Relay and its X and Discord setup steps, trusted external process-event adapter setup, the files you set, and harness support.
+- [docs/matt-pocock-skills.md](docs/matt-pocock-skills.md) - install and use Matt Pocock's engineering skills without creating a second orchestration or review lifecycle.
 - [docs/extension-bindings.md](docs/extension-bindings.md) - maintainer architecture for the narrow trusted external `process-event-adapter/1` package, binding, handshake, and evidence boundary.
 - [docs/remote-secondmates.md](docs/remote-secondmates.md) - current setup, routing, transfer, recovery, and safety behavior for whole-home remote second mates.
 - [docs/calm.md](docs/calm.md) - current `/calm` behavior on Pi and Claude Code and its supported presentation limits.

bin/fm-brief.sh

@@ -8,8 +8,11 @@
 # report, decision, or PR the ask refers to, without added speaker labels or
 # direct address) and `{FIRSTMATE_SPEC}`
 # under `## Firstmate spec` (build instructions, which are never the captain's
-# intent). bin/fm-dod-lib.sh owns the no-mistakes `--intent` contract those
-# subsections feed; bin/fm-spawn.sh refuses leftover placeholders and a
+# intent). Their `# Engineering method` section has two more task-specific fill
+# sites: `{REQUIRED_SKILLS}` names the method skills the worker must load, and
+# `{TESTING_SEAMS}` names the agreed public test seams or gives the reason none
+# applies. bin/fm-dod-lib.sh owns the no-mistakes `--intent` contract those
+# Task subsections feed; bin/fm-spawn.sh refuses leftover placeholders and a
 # `## Captain's intent` line opening with a Captain label or address. Secondmate
 # charters still use a single `{TASK}` charter fill. Firstmate may adjust other
 # sections when the task genuinely deviates (e.g. working an existing external
@@ -358,6 +361,32 @@ IFS= read -r -d '' TASK_SECTION <<'EOF' || true
 EOF
 TASK_SECTION=${TASK_SECTION%$'\n'}
 
+IFS= read -r -d '' ENGINEERING_SECTION <<'EOF' || true
+# Engineering method
+Fill each task-specific subsection with one bullet per item, or write `None - <reason>.`
+
+## Required skills
+{REQUIRED_SKILLS}
+
+## Agreed testing seams
+{TESTING_SEAMS}
+
+## Execution
+Each required-skill bullet is an exact skill ID unless the subsection contains only `None - <reason>.`
+Load every named skill before using its method.
+If a named skill is unavailable, report the missing skill as a blocker and stop.
+Testing seams are the agreed public interfaces where behavior will be tested.
+Write tests only at these seams.
+For a bug, reproduce the end-user path first and observe the regression test fail before the fix.
+When tests apply, work in vertical red-green slices rather than writing every test or every implementation change in one horizontal batch.
+
+## Ownership
+FirstMate's selected delivery path is the only final review owner.
+Use the required skills for engineering method while keeping orchestration, worker allocation, tracker mutation, review, PR, CI, and merge authority with FirstMate and this brief's Definition of done.
+Do not invoke `code-review`, `implement`, `research`, `wayfinder`, or another workflow that delegates work or starts a second delivery path.
+EOF
+ENGINEERING_SECTION=${ENGINEERING_SECTION%$'\n'}
+
 if [ "$KIND" = scout ]; then
 if "$SCRIPT_DIR/fm-bootstrap.sh" lavish-compatible >/dev/null 2>&1; then
   LAVISH_LINE='If your deliverable is a visual artifact the captain will review and iterate on, you may host the Lavish review loop yourself (poll, revise, re-serve, staying alive) instead of handing it back to firstmate.'
@@ -369,6 +398,8 @@ You are a crewmate: an autonomous worker agent managed by firstmate. Work on you
 
 $TASK_SECTION
 
+$ENGINEERING_SECTION
+
 $HERDR_SECTION
 
 # Setup
@@ -424,7 +455,7 @@ Before reporting done, read and follow \`$FM_ROOT/.agents/skills/captain-hold-li
 When the report is complete, append \`done: {one-line conclusion}\` to the status file and stop.
 If your findings reveal work that should ship (e.g. you reproduced a bug and the fix is clear), say so in the report; firstmate may promote this task in place, and you would then receive mode-specific ship instructions as a follow-up message.
 EOF
-echo "scaffolded: $BRIEF (scout; replace {TASK} and {FIRSTMATE_SPEC})"
+echo "scaffolded: $BRIEF (scout; replace {TASK}, {FIRSTMATE_SPEC}, {REQUIRED_SKILLS}, and {TESTING_SEAMS})"
 exit 0
 fi
 
@@ -453,6 +484,8 @@ You are a crewmate: an autonomous worker agent managed by firstmate. Work on you
 
 $TASK_SECTION
 
+$ENGINEERING_SECTION
+
 $HERDR_SECTION
 
 # Setup
@@ -514,4 +547,4 @@ Keep it proportionate: skip \`AGENTS.md\` edits for trivial tasks that produced
 
 $DOD
 EOF
-echo "scaffolded: $BRIEF (ship, mode=$MODE; replace {TASK} and {FIRSTMATE_SPEC})"
+echo "scaffolded: $BRIEF (ship, mode=$MODE; replace {TASK}, {FIRSTMATE_SPEC}, {REQUIRED_SKILLS}, and {TESTING_SEAMS})"