diff --git a/AGENTS.md b/AGENTS.md index 149894ad849..4d1776254d8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -520,8 +520,8 @@ Preserve durable structured identifiers, dependencies, and completion artifact l ## 11. Crewmate briefs `bin/fm-brief.sh` and its help own scaffold syntax, generated variants, status protocol, delivery-mode definitions of done, and exact safety mechanics. -Use its scaffold as the contract, then fill `## Captain's intent` (`{TASK}`) with the captain's own ask plus only the context needed to read it, and fill `## Firstmate spec` (`{FIRSTMATE_SPEC}`) with Firstmate's build instructions. -`bin/fm-dod-lib.sh` owns what a no-mistakes worker may pass as `--intent`. +Use its scaffold as the contract, then fill `## Captain's intent` (`{TASK}`) with the captain's own ask plus the context needed to read it, including the substance of any report, decision, or PR the ask refers to, and fill `## Firstmate spec` (`{FIRSTMATE_SPEC}`) with Firstmate's build instructions. +`bin/fm-dod-lib.sh` owns what a no-mistakes worker may pass as `--intent` and its rule that the string must be self-sufficient. 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. diff --git a/bin/fm-brief.sh b/bin/fm-brief.sh index 3a80a701678..3a557f5ea01 100755 --- a/bin/fm-brief.sh +++ b/bin/fm-brief.sh @@ -4,7 +4,8 @@ # For ordinary tasks, the standard Setup/Rules/Definition-of-done contract is # filled in. Ship and scout `# Task` sections have two subsections Firstmate # fills before dispatch: `{TASK}` under `## Captain's intent` (the captain's -# own ask plus only the context needed to read it) and `{FIRSTMATE_SPEC}` +# own ask plus the context needed to read it, including the substance of any +# report, decision, or PR the ask refers to) 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. Secondmate diff --git a/bin/fm-dod-lib.sh b/bin/fm-dod-lib.sh index d7d0f3ccc6e..557bcf981a9 100755 --- a/bin/fm-dod-lib.sh +++ b/bin/fm-dod-lib.sh @@ -12,10 +12,14 @@ # line that bin/fm-spawn.sh checks a ship brief against. # This file is the one owner of the no-mistakes `--intent` contract: only the # brief's `## Captain's intent` subsection plus later captain words, never -# `## Firstmate spec` and never the worker's own tradeoffs. bin/fm-brief.sh -# scaffolds those two `# Task` subsections; bin/fm-spawn.sh and bin/fm-promote.sh -# refuse leftover `{TASK}` / `{FIRSTMATE_SPEC}` placeholders through the helpers -# below. Other mentions of `--intent` point here rather than restating the rule. +# `## Firstmate spec` and never the worker's own tradeoffs. +# The string passed must be self-sufficient - it plus the codebase reconstructs +# roughly the same specification - so a report, decision, or PR the intent +# refers to is written into it as substance, never left as a pointer. +# bin/fm-brief.sh scaffolds those two `# Task` subsections; bin/fm-spawn.sh and +# bin/fm-promote.sh refuse leftover `{TASK}` / `{FIRSTMATE_SPEC}` placeholders +# through the helpers below. Other mentions of `--intent` point here rather than +# restating the rule. # Every heredoc here stays outside a command substitution: `VAR=$(cat <