Skip to content

refactor(agents): regroup the base prompt into its final sections - #3809

Draft
gilgtm wants to merge 1 commit into
gil/prompt-sections-2b-codex-session-modelfrom
gil/prompt-sections-3a-final-map
Draft

gilgtm wants to merge 1 commit into
gil/prompt-sections-2b-codex-session-modelfrom
gil/prompt-sections-3a-final-map

Conversation

@gilgtm

@gilgtm gilgtm commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Summary

The base prompt's sections are regrouped into their final map: 22 sections, one topic each, each under a heading of its own. Sentences move between sections; none changes its meaning.

Why

The interim sections followed the old file's headings, so one topic was spread over several of them: the progress rules were in three places and the trust rules in four. A section that the owner or a plugin can replace must hold its whole topic, and a section that is always on must be complete without the others.

What changed

  • sections/index.ts holds the final map and marks each section: always on, picked by the host (Workspace Layout, Working location, Session Model), configurable by the owner, replaceable by a plugin.
  • Trust collects the rules about what is data and who outranks whom, with the paragraph about escaped JSON.
  • Threading, Audience and Progress take over the posting conventions. Publishing, Routing, Waiting, Etiquette, Commit identity and Product help become sections of their own.
  • The worktree rule leaves the repositories row for a Working location section, which keeps the two sentences of the rule and the sentence about an existing local checkout. The row keeps its sentence about reading code in an existing local checkout.
  • The core of the bare-acknowledgement rule moves to the always-on Audience section, with two sentences that say what an acknowledgement is, so the rule holds when Etiquette is off.
  • product-help.md is the single source of the product help line.

Tests

  • The byte-identity fixtures give way to one snapshot of the whole session prompt per harness, scope and folder variant (sections/snapshots/). The snapshot diff in this PR is the review surface for the moved sentences.
  • New compose.test.ts cases: each always-on section is printed once and in order for every combination of facts; every section is under a heading of its own; each section has an ID and a title of its own; no default text names a section that can be off or replaced; the section IDs, their order and their marks are pinned in one table.

Validation

Native run planned for this PR: a packaged app with a local relay, one Claude Code agent and one Codex agent get the regrouped prompt and answer a mention, a thread reply and a tool task as before. The recording and the result will be added here.

FOUNDATION changes

None.

Notes for reviewers

Known limits

None known.

Review

Agent review, round 1: no blocking findings.

  • Fixed: the Working location text said "in a new worktree" for all work, which changed the rule's meaning. It now keeps the original sentences.
  • Fixed: src/buzz-mcp/AGENTS.md named three of the posting sections; it now names the current ones.
  • Fixed: a test pins the section IDs, order and marks, so a change to the map is a visible diff.

Agent review, round 2: no findings. Simplify pass: one redundant test line removed.

Stack

Part 4 of 12. Merge order, bottom first: #3806 → #3807 → #3808 → #3809 → #3810 → #3811 → #3812 → #3813 → #3814 → #3815 → #3816 → #3831. Each part ships alone: the app works and the prompt is coherent after each one.

This PR is a draft. The first agent review round is done (see Review). A second round and the native validation are in progress, and their results will be added to this description.

The interim sections followed the old file's headings, so one topic was
spread over several of them. The progress rules were in three places and
the trust rules in four.

Each topic is now one section under a heading of its own, in the final
map: 22 sections, each marked as locked, picked by the host, or
replaceable by the owner or a plugin. Sentences move; none changes
meaning. Trust collects the rules about what is data and who outranks
whom. Threading, Audience and Progress take over the posting conventions.
The worktree rule leaves the REPOS row for a Working location section.

A locked section must be complete on its own, so the core of the
bare-acknowledgement rule moves to the locked Audience section, with two
sentences that say what an acknowledgement is. A test keeps a default
text from naming a section that can be off or replaced.

The byte-identical fixtures give way to one snapshot of the whole session
prompt per harness, scope and folder variant.

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
Signed-off-by: Gil Birman <gil@squareup.com>

This branch has not been deployed

No deployments
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