Skip to content

feat(brief): require crewmates to read project instructions first - #1906

Open
jericho1050 wants to merge 1 commit into
kunchenguid:mainfrom
jericho1050:fm/fm-brief-require-project-memory
Open

feat(brief): require crewmates to read project instructions first#1906
jericho1050 wants to merge 1 commit into
kunchenguid:mainfrom
jericho1050:fm/fm-brief-require-project-memory

Conversation

@jericho1050

Copy link
Copy Markdown

Problem

bin/fm-brief.sh mentions AGENTS.md/CLAUDE.md eleven times, and every one of them is about writing project memory at the end of a task.
Nothing in the scaffold tells a worker to read the project's own instructions before starting.

That gap has already cost review cycles: shipped code violated documented project conventions because the worker never opened the project's CLAUDE.md.
Those files carry rules no diff teaches - banned commands, required tooling, logging and redaction rules that exist to keep credentials and PII out of logs.
Until now the instruction only reached a worker when firstmate remembered to type it into a brief by hand.

Change

The same short imperative block is added to both setup sections, so it is part of the scaffold contract rather than per-brief discipline:

  • Ship briefs get it after the worktree-isolation assertion and before the branch step, phrased "Before your first edit", routing conflicts to the status file.
  • Scout briefs get it at the end of the setup section, phrased "Before your first edit or command", routing conflicts to the report, since a scout has no status-file decision loop in the same way.

Both keep the clause that no task is too small to read them, which is the point of the change: the failure mode is a worker deciding a one-line fix does not warrant it.

The existing "# Project memory" section is untouched - it is about writing project memory and is correct as it stands.

Verification

  • bash -n bin/fm-brief.sh passes.
  • tests/fm-brief.test.sh passes in full (all cases ok).
  • Scaffolded throwaway briefs for all three ship modes plus a scout into a temporary data/state root, then diffed each against a brief generated by the pre-change script. The only differences are the new block and the task-id substitutions: the worktree-isolation assertion, the rules block, the project-memory section, and every delivery-mode definition of done render byte-identical.
  • Confirmed the rendered output keeps its backticks and leaks no literal backslashes, so the heredoc escaping survived.
  • ShellCheck is not installed in this environment - bin/fm-lint.sh reports "ShellCheck not found; install ShellCheck 0.11.0 for CI parity" and exits without linting. That check is unverified locally and is left to CI; the change is prose inside an existing heredoc and adds no shell syntax.

Scope note

The task was scoped to bin/fm-brief.sh only, so no test was added to tests/fm-brief.test.sh asserting the new block.
Worth a follow-up if this instruction should be regression-pinned like the project-memory wording already is.

Every existing AGENTS.md/CLAUDE.md mention in the scaffold is about
writing project memory at the end of a task; nothing told a worker to
read the project's own instructions at the start. Shipped work has
violated documented conventions (banned commands, logging and redaction
rules) because the worker never opened them.

Add the same short imperative block to both the ship and scout setup
sections, before the first edit and before the branch step, including
the clause that no task is too small to read them. Conflicts route to
the status file for a ship task and to the report for a scout, matching
each variant's existing reporting channel.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant