Repository navigation
Conversation
Contributor
🛫 PR Readiness Check
PR Scope: 📦🔧 Mixed (product + infrastructure)
|
| Status | Check | Details |
|---|---|---|
| ❌ | Single commit | 3 commits — consider squashing before review |
| ✅ | Not in draft | Ready for review |
| ✅ | Branch up to date | Up to date with dev |
| ❌ | Copilot review | No Copilot review yet — it may still be processing |
| ✅ | Changeset present | Changeset file found |
| ✅ | Scope clean | No .squad/ or docs/proposals/ files |
| ✅ | No merge conflicts | No merge conflicts |
| ✅ | Copilot threads resolved | 1 active Copilot thread(s) resolved (1 outdated skipped) |
| ❌ | CI passing | 9 check(s) still running |
Files Changed (82 files, +332 −347)
| File | +/− |
|---|---|
.changeset/scribe-single-definition.md |
+6 −0 |
.github/agents/squad.agent.md |
+4 −5 |
.squad-templates/README.md |
+1 −1 |
.squad-templates/after-agent-reference.md |
+15 −44 |
.squad-templates/ceremony-reference.md |
+2 −1 |
.squad-templates/model-selection-reference.md |
+2 −2 |
.squad-templates/routing.md |
+1 −1 |
.squad-templates/scribe-charter.md |
+1 −1 |
.squad-templates/skills/agent-collaboration/SKILL.md |
+1 −1 |
.squad-templates/skills/coordinator-init-mode/SKILL.md |
+2 −2 |
.squad-templates/skills/coordinator-source-of-truth/SKILL.md |
+4 −4 |
.squad-templates/skills/e2e-template-testing/SKILL.md |
+1 −1 |
.squad-templates/skills/gh-auth-isolation/SKILL.md |
+1 −1 |
.squad-templates/skills/init-mode/SKILL.md |
+2 −2 |
.squad-templates/skills/retro-enforcement/SKILL.md |
+1 −1 |
.squad-templates/skills/secret-handling/SKILL.md |
+9 −7 |
.squad-templates/spawn-reference.md |
+4 −4 |
.squad-templates/squad.agent.md |
+4 −5 |
.squad-templates/worktree-reference.md |
+2 −2 |
docs/src/content/docs/concepts/architecture.md |
+1 −1 |
docs/src/content/docs/concepts/what-is-squad.md |
+1 −1 |
docs/src/content/docs/features/memory.md |
+6 −4 |
docs/src/content/docs/get-started/first-session.md |
+2 −2 |
docs/src/content/docs/reference/glossary.md |
+1 −1 |
packages/squad-cli/src/cli/commands/watch/capabilities/decision-hygiene.ts |
+4 −3 |
packages/squad-cli/templates/README.md |
+1 −1 |
packages/squad-cli/templates/after-agent-reference.md |
+15 −44 |
packages/squad-cli/templates/ceremony-reference.md |
+2 −1 |
packages/squad-cli/templates/model-selection-reference.md |
+2 −2 |
packages/squad-cli/templates/routing.md |
+1 −1 |
packages/squad-cli/templates/scribe-charter.md |
+1 −1 |
packages/squad-cli/templates/skills/agent-collaboration/SKILL.md |
+1 −1 |
packages/squad-cli/templates/skills/coordinator-init-mode/SKILL.md |
+2 −2 |
packages/squad-cli/templates/skills/coordinator-source-of-truth/SKILL.md |
+4 −4 |
packages/squad-cli/templates/skills/e2e-template-testing/SKILL.md |
+1 −1 |
packages/squad-cli/templates/skills/gh-auth-isolation/SKILL.md |
+1 −1 |
packages/squad-cli/templates/skills/init-mode/SKILL.md |
+2 −2 |
packages/squad-cli/templates/skills/retro-enforcement/SKILL.md |
+1 −1 |
packages/squad-cli/templates/skills/secret-handling/SKILL.md |
+9 −7 |
packages/squad-cli/templates/spawn-reference.md |
+4 −4 |
packages/squad-cli/templates/squad.agent.md.template |
+4 −5 |
packages/squad-cli/templates/worktree-reference.md |
+2 −2 |
packages/squad-sdk/src/client/adapters/coordinator.ts |
+1 −1 |
packages/squad-sdk/templates/README.md |
+1 −1 |
packages/squad-sdk/templates/after-agent-reference.md |
+15 −44 |
packages/squad-sdk/templates/ceremony-reference.md |
+2 −1 |
packages/squad-sdk/templates/model-selection-reference.md |
+2 −2 |
packages/squad-sdk/templates/routing.md |
+1 −1 |
packages/squad-sdk/templates/scribe-charter.md |
+1 −1 |
packages/squad-sdk/templates/skills/agent-collaboration/SKILL.md |
+1 −1 |
| ... | +32 more files |
Total: +332 −347
This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.
Contributor
🏗️ Architectural Review
Automated architectural review — informational only. |
Contributor
🔴 Impact Analysis — PR #2322Risk tier: 🔴 CRITICAL 📊 Summary
🎯 Risk Factors
📦 Modules Affectedci-workflows (1 file)
docs (5 files)
root (20 files)
squad-cli (18 files)
squad-sdk (18 files)
templates (17 files)
tests (3 files)
This report is generated automatically for every PR. See #733 for details. |
joslat
force-pushed
the
joslat/2321-scribe-single-definition
branch
from
October 25, 2026 18:47
de47157 to
bfbd312
Compare
This was referenced Oct 25, 2026
Contributor
Author
|
Heads-up on overlap with #1969: both change what Scribe does, in opposite directions. #1969 adds a "Session Init — Scribe Bootstrap" to The Which way do you want Scribe to go? If the bootstrap stays, I can adjust this PR so the bootstrap only processes the decision inbox, or rebase on top of #1969 once it lands. |
Collaborator
|
Thanks Jose, I really like unifying Scribe around one definition and the guard test in est/ci/scribe-template.test.ts is great. One thing we want to sort out before merging is the squad cost dependency you flagged in the PR description: getCurrentSessionCutoff in packages/squad-cli/src/cli/commands/cost.ts:249 currently keys off the newest .squad/log/*.md file to find the current session start, so once every prompt surface stops asking Scribe for session logs, plain squad cost loses its session boundary. Also note that emplates/scribe-charter.md:26 still mentions a session log under canonical artifacts, and compressHistory in packages/squad-cli/src/cli/core/nap.ts:243 does not yet have the git-ignored destination check that decisions-archive.md has. How would you like to handle the squad cost cutoff? We can either keep one Scribe definition that still writes the brief session log, or update squad cost to derive the session boundary from the usage ledger instead. |
Contributor
Author
|
Thanks Tamir. I'd go with the usage ledger. A Scribe session log isn't a reliable boundary even if we keep it:
Concretely: the shell already has a session id ( It touches the SDK and CLI, so I'd open it as its own issue and PR and land it before this one. On the other two:
Does that work for you? |
This was referenced Oct 26, 2026
Closed
Contributor
Author
|
The Next I'll push the |
joslat
force-pushed
the
joslat/2321-scribe-single-definition
branch
from
October 26, 2026 17:48
bfbd312 to
2331cfa
Compare
Contributor
Author
|
Hey Tamir, thanks a lot for going through the whole batch so quickly, and for the kind words. Really appreciated! Quick status from my side:
And yes, happy to keep going! 🙂 |
This was referenced Oct 26, 2026
Closed
Contributor
|
👋 Friendly nudge — this PR has had no activity for 7 days. What needs attention:
If this PR is abandoned, please close it. If it's blocked on something external, leave a comment so the team knows. |
Since github#2030 Scribe's charter says it only merges accepted decisions, and the coordinator's inline Scribe template matches it. Other shipped surfaces still gave Scribe the old broad job: the after-agent reference (archive hard gate, session and orchestration logs, cross-agent history appends, history summarization), the host coordinator digest, the decision-hygiene watch prompt, the spawn reference (skill extraction), routing, ceremony and model-selection references, several skills and docs. Align all of them with the charter, make the after-agent Scribe prompt identical to the inline template, point size hygiene at `squad nap`, and add cross-surface guard tests so retired duties can't come back. The charter's "Exclusive canonical artifacts" paragraph no longer names a session log or a retrospective as something Scribe creates (all copies, including the gh-aw builtin and its manifest digest). Closes github#2321
joslat
force-pushed
the
joslat/2321-scribe-single-definition
branch
from
November 10, 2026 18:53
2331cfa to
32b6ec6
Compare
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Writer restrictions block retrospective facilitators from completing the required logging gate, while shipped references retain forbidden Scribe commit duties that the test guard misses.
2 open issues
What changed in this PR
This PR aligns Scribe’s prompts and core documentation with the decision-merging role established in #2030, addressing the template portion of D5 in #2392.
Changes:
- Removes retired logging, archival, and cross-agent history duties from prompts and mirrored templates.
- Assigns ceremony decision recording to facilitators through
squad_decide, with size maintenance delegated tosquad nap. - Adds consistency guards, updates five documentation pages, and refreshes the workflow charter checksum.
| File | Description |
|---|---|
| workflows/squad-workflows.manifest.json | Updates the builtin charter checksum. |
| workflows/shared/builtins/scribe-charter.md | Removes retired artifact examples. |
| test/clients.test.ts | Updates host digest expectations. |
| test/ci/scribe-template.test.ts | Adds Scribe consistency guards. |
| templates/squad.agent.md.template | Aligns coordinator and ceremony instructions. |
| templates/spawn-reference.md | Removes unsupported Scribe fallback duties. |
| templates/skills/retro-enforcement/SKILL.md | Assigns retrospectives to non-Scribe facilitators. |
| templates/skills/init-mode/SKILL.md | Narrows Scribe’s initialization description. |
| templates/skills/coordinator-source-of-truth/SKILL.md | Revises history and log ownership. |
| templates/skills/coordinator-init-mode/SKILL.md | Updates Scribe’s roster and charter descriptions. |
| templates/skills/agent-collaboration/SKILL.md | Routes shared decisions through squad_decide. |
| templates/scribe-charter.md | Removes retired artifact examples. |
| templates/routing.md | Limits Scribe dispatch to pending decisions. |
| templates/README.md | Marks orchestration logging as legacy. |
| templates/model-selection-reference.md | Describes Scribe as a decision merger. |
| templates/ceremony-reference.md | Assigns decision recording to facilitators. |
| templates/after-agent-reference.md | Aligns the post-work Scribe prompt. |
| packages/squad-sdk/templates/squad.agent.md.template | Mirrors coordinator instruction changes. |
| packages/squad-sdk/templates/spawn-reference.md | Mirrors post-work responsibility changes. |
| packages/squad-sdk/templates/skills/retro-enforcement/SKILL.md | Mirrors non-Scribe facilitator assignment. |
| packages/squad-sdk/templates/skills/init-mode/SKILL.md | Mirrors the narrowed Scribe description. |
| packages/squad-sdk/templates/skills/coordinator-source-of-truth/SKILL.md | Mirrors revised artifact ownership. |
| packages/squad-sdk/templates/skills/coordinator-init-mode/SKILL.md | Mirrors initialization description changes. |
| packages/squad-sdk/templates/skills/agent-collaboration/SKILL.md | Mirrors shared-decision guidance. |
| packages/squad-sdk/templates/scribe-charter.md | Mirrors charter example cleanup. |
| packages/squad-sdk/templates/routing.md | Mirrors conditional Scribe dispatch. |
| packages/squad-sdk/templates/README.md | Mirrors legacy logging designation. |
| packages/squad-sdk/templates/model-selection-reference.md | Mirrors decision-merging labels. |
| packages/squad-sdk/templates/ceremony-reference.md | Mirrors facilitator recording instructions. |
| packages/squad-sdk/templates/after-agent-reference.md | Mirrors the aligned post-work prompt. |
| packages/squad-sdk/src/client/adapters/coordinator.ts | Narrows the host digest’s Scribe duties. |
| packages/squad-cli/templates/squad.agent.md.template | Mirrors coordinator instruction changes. |
| packages/squad-cli/templates/spawn-reference.md | Mirrors post-work responsibility changes. |
| packages/squad-cli/templates/skills/retro-enforcement/SKILL.md | Mirrors non-Scribe facilitator assignment. |
| packages/squad-cli/templates/skills/init-mode/SKILL.md | Mirrors the narrowed Scribe description. |
| packages/squad-cli/templates/skills/coordinator-source-of-truth/SKILL.md | Mirrors revised artifact ownership. |
| packages/squad-cli/templates/skills/coordinator-init-mode/SKILL.md | Mirrors initialization description changes. |
| packages/squad-cli/templates/skills/agent-collaboration/SKILL.md | Mirrors shared-decision guidance. |
| packages/squad-cli/templates/scribe-charter.md | Mirrors charter example cleanup. |
| packages/squad-cli/templates/routing.md | Mirrors conditional Scribe dispatch. |
| packages/squad-cli/templates/README.md | Mirrors legacy logging designation. |
| packages/squad-cli/templates/model-selection-reference.md | Mirrors decision-merging labels. |
| packages/squad-cli/templates/ceremony-reference.md | Mirrors facilitator recording instructions. |
| packages/squad-cli/templates/after-agent-reference.md | Mirrors the aligned post-work prompt. |
| packages/squad-cli/src/cli/commands/watch/capabilities/decision-hygiene.ts | Defers to the charter and removes archival instructions. |
| docs/src/content/docs/reference/glossary.md | Updates Scribe’s definition. |
| docs/src/content/docs/get-started/first-session.md | Removes session-logging claims. |
| docs/src/content/docs/features/memory.md | Explains decision merging and manual archival. |
| docs/src/content/docs/concepts/what-is-squad.md | Describes Scribe’s bounded role. |
| docs/src/content/docs/concepts/architecture.md | Clarifies Scribe’s architectural responsibilities. |
| .squad-templates/squad.agent.md | Aligns canonical coordinator instructions. |
| .squad-templates/spawn-reference.md | Removes unsupported Scribe fallback duties. |
| .squad-templates/skills/retro-enforcement/SKILL.md | Excludes Scribe from retrospective facilitation. |
| .squad-templates/skills/init-mode/SKILL.md | Narrows Scribe’s initialization description. |
| .squad-templates/skills/coordinator-source-of-truth/SKILL.md | Revises canonical artifact ownership. |
| .squad-templates/skills/coordinator-init-mode/SKILL.md | Updates canonical initialization descriptions. |
| .squad-templates/skills/agent-collaboration/SKILL.md | Replaces cross-agent history ownership guidance. |
| .squad-templates/scribe-charter.md | Removes retired artifact examples. |
| .squad-templates/routing.md | Makes Scribe dispatch decision-driven. |
| .squad-templates/README.md | Marks orchestration logging as legacy. |
| .squad-templates/model-selection-reference.md | Updates Scribe’s role labels. |
| .squad-templates/ceremony-reference.md | Assigns decision recording to facilitators. |
| .squad-templates/after-agent-reference.md | Matches the inline Scribe prompt. |
| .github/agents/squad.agent.md | Updates the repository coordinator instructions. |
| .changeset/scribe-single-definition.md | Records CLI and SDK patch-release changes. |
Review effort: Balanced (auto)
…or write the retro log Follow-up from review: - secret-handling, worktree-reference, gh-auth-isolation and e2e-template-testing still had Scribe commit .squad/ changes, which its charter forbids. The pre-commit secret validation now applies to whoever commits .squad/ changes, and the worktree notes say the changes are committed with the work (runtime state tools persist mutable state on non-local backends). - retro-enforcement waits for the retro facilitator (never Scribe) to write .squad/log/, but the source-of-truth writer table did not allow it. The facilitator is now listed for retro logs. - the Scribe guard rejects the retired commit phrases and checks the facilitator can write the retro log.
…changes The projection guard (github#2438) pins every file squad init + upgrade writes. This PR changes five of them on purpose: squad.agent.md and the agent-collaboration, coordinator-init-mode, coordinator-source-of-truth and secret-handling skills.
Contributor
Author
|
Hi @tamirdresher, quick status on this one: it's rebased on the new Since #2321 was folded into Brady's ADR #2392 as D5, I asked him there whether the remaining docs pages should go into this PR or a small follow-up (comment). So I'm waiting on his answer before touching the scope. Otherwise it's ready from my side. Thanks! |
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Scribe now has one definition: its charter. #2030 narrowed Scribe in the charter and in the coordinator's inline Scribe Spawn Template, so it only merges accepted durable decisions. This PR brings the prompt surfaces #2030 didn't touch into line with that, and adds a guard test so the old duties can't come back. Those surfaces are the after-agent reference, the host coordinator digest, the decision-hygiene watch prompt, the spawn, routing, ceremony and model-selection references, a few skills and the templates README. It also updates the five main docs pages that describe Scribe.
Why
Closes #2321. #2321 is now tracked as decision D5 ("one Scribe definition") of the ADR #2392, and this PR implements D5 for the templates, the host digest, the watch prompt and the core docs.
#2030 removed the archive "hard gate", the session and orchestration logs, the cross-agent history appends and the history summarization from the inline Scribe template. But
after-agent-reference.mdstill had its own broad Scribe prompt with all of them; it was last edited before #2030, in #1792. The host digest and the watch prompt asked for logs and archival too. So what Scribe did depended on which text the model read.How
Prompt surfaces, all of which drive behavior:
after-agent-reference.md: its Scribe prompt is now byte-identical to the inline Scribe Spawn Template, plus a note that size hygiene issquad nap.coordinator.ts(host digest, item 11): Scribe only merges decisions; no logs, no history edits, no archiving.decision-hygiene.ts: the watch prompt points Scribe at its charter and drops the archiving instructions.squad.agent.md: drops the "Scribe — logging session" example and "Scribe log". Before-ceremonies no longer spawn Scribe "to record".ceremony-reference.md: the facilitator now records each decision withsquad_decide, and rule 6 no longer spawns Scribe at ceremony start. This is the one place where something new is asked of an agent. Without it, ceremony decisions would stay in the summary and never reach the inbox, since Scribe no longer records them.spawn-reference.md: "skill extraction is handled by Scribe" is gone (no Scribe definition ever did it). The low-context rule still says "skip post-work entirely"; only the false "Scribe handles it independently" was replaced.routing.md: Scribe runs when accepted decisions need merging, matching Recast repository with descriptive Squad specialists #2030's inline wording.retro-enforcementskill: the retro facilitator is never Scribe.scribe-charter.md: the "Exclusive canonical artifacts" paragraph no longer names a retrospective or a session log as something Scribe creates; a claim marker is the example now. The change is in all four template copies and the gh-aw builtin (workflows/shared/builtins/scribe-charter.md), with itssha256updated inworkflows/squad-workflows.manifest.json.model-selection-reference.md, the other skills and the templates README: labels and ownership rows only.Everything else:
concepts/architecture.md,concepts/what-is-squad.md,features/memory.md,get-started/first-session.md,reference/glossary.md.test/clients.test.tsmatches the new digest wording.test/ci/scribe-template.test.tsadds guard tests. Every.squad-templates/file is scanned for 15 retired Scribe phrases, the after-agent Scribe prompt must equal the inline one, the charter's exclusive-artifacts paragraph can't name a session log or retrospective, and the gh-aw builtin charter must match the template.templates/,.squad-templates/,packages/squad-cli/templates/,packages/squad-sdk/templates/,.github/agents/), which is why there are 65 files. The unique sources are 15 templates (the charter has a fifth copy as the gh-aw builtin), 2 code files, 5 docs pages, 2 tests, 1 changeset and the gh-aw manifest.Review follow-up (80b694e):
secret-handling,worktree-reference,gh-auth-isolationande2e-template-testingno longer have Scribe commit.squad/changes, which the charter forbids. Pre-commit secret validation now applies to whoever commits.squad/changes.retro-enforcementwaits for.Effects to expect
decisions.mdandhistory.mdgrow until someone runssquad nap. The old prompt "hard gate" was the only automatic trigger and didn't hold reliably. If you'd like it to stay automatic, I can add a coordinator hint to suggestsquad nappast 20 KB.squad costuses the newest.squad/log/*.mdas the "current session" start (getCurrentSessionCutoff), so with no session logs plainsquad costreports every recorded turn. That's already what happens on hosts that follow Recast repository with descriptive Squad specialists #2030's inline template. Keying the session on the usage ledger instead would fix it; that's a separate change.decisions.mdthrough the inbox like any other decision.Not in this PR
The rest of the docs. D5's test in ADR: Squad memory and state model (API boundary, history.md, archive policy, Scribe) #2392 also scans docs. These pages still describe the old Scribe:
guide.md,tour-first-session.md,reference/cli.md, andscenarios/new-project,existing-repo,mid-project,monorepoandsolo-dev;scenarios/disaster-recovery.md,scenarios/large-codebase.md,reference/compaction-recovery.md,reference/result-persistence.md,features/tiered-memory.md,features/reflect.mdandtips-and-tricks.md;reference/host-feature-matrix.md.The walkthroughs need rewriting, not one-line fixes. I'd send them as a follow-up docs PR, with a docs scan added to
ci/scribe-template, or add them here if you'd rather have D5 in one PR.The role label "Session Logger" in
packages/squad-cli/src/cli/core/team-md.ts:120. The Scribe row it labels is filtered out of rosters.Refreshing an existing
.squad/agents/scribe/charter.mdonsquad upgrade.Related: #1268, #1823.
.changeset/scribe-single-definition.md)PR Readiness Checklist
Branch & Commit
dev(notmain)dev(675c9e9, rebased 2026-11-10 after the move togithub/squad; clean rebase)Build & Test
npm run buildpassesnpm testpasses (all tests green). Test summary from my Windows machine, since this touches more than 20 files:ci/scribe-template,clients,template-sync,coordinator,init-upgrade-parity,feature-parityandsquad-agent-rosterpass, with 719 passed and 35 expected fails. The gh-aw suites fail the same way on plaindevon Windows (same counts), and the full integrity check needs the gh-aw compiler, so I checked the manifest directly: all 22 runtime and skill digests match the committed files. CI is the real check.After the rebase onto 675c9e9: the 40 test files that mention Scribe or templates give 1,195 passed and 1 failed. The failure is
charter-spec, which compares LF fixtures with my CRLF checkout and reads no file this PR touches. All 21 manifest digests match the committed blobs. On the tree without the fix (currentdev), theci/scribe-templateguard fails 5 of its 11 tests, so it's red first, as ADR: Squad memory and state model (API boundary, history.md, archive policy, Scribe) #2392 asks.npm run lintpasses (type check clean)npm run lint:eslintpasses on the changed code filesChangeset
@bradygaster/squad-clipatch,@bradygaster/squad-sdkpatch)Docs
Exports
Breaking Changes
None in code. Behavior changes are listed under "Effects to expect".
Waivers
None.