Repository navigation
Conversation
🛫 PR Readiness Check
PR Scope: 📦🔧 Mixed (product + infrastructure)
|
| Status | Check | Details |
|---|---|---|
| ✅ | Single commit | 1 commit — clean history |
| ✅ | 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 | No Copilot review threads |
| ❌ | CI passing | 9 check(s) failing: sdk-exports-validation, docs-quality, Policy Gates, samples-build, test, Changeset Drift, changes, Shebang EOL, gh-aw strict compile |
Files Changed (65 files, +257 −298)
| 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/init-mode/SKILL.md |
+2 −2 |
.squad-templates/skills/retro-enforcement/SKILL.md |
+1 −1 |
.squad-templates/spawn-reference.md |
+4 −4 |
.squad-templates/squad.agent.md |
+4 −5 |
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/init-mode/SKILL.md |
+2 −2 |
packages/squad-cli/templates/skills/retro-enforcement/SKILL.md |
+1 −1 |
packages/squad-cli/templates/spawn-reference.md |
+4 −4 |
packages/squad-cli/templates/squad.agent.md.template |
+4 −5 |
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 |
packages/squad-sdk/templates/skills/coordinator-init-mode/SKILL.md |
+2 −2 |
packages/squad-sdk/templates/skills/coordinator-source-of-truth/SKILL.md |
+4 −4 |
packages/squad-sdk/templates/skills/init-mode/SKILL.md |
+2 −2 |
packages/squad-sdk/templates/skills/retro-enforcement/SKILL.md |
+1 −1 |
packages/squad-sdk/templates/spawn-reference.md |
+4 −4 |
packages/squad-sdk/templates/squad.agent.md.template |
+4 −5 |
templates/README.md |
+1 −1 |
templates/after-agent-reference.md |
+15 −44 |
| ... | +15 more files |
Total: +257 −298
This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.
🏗️ Architectural Review
Automated architectural review — informational only. |
🔴 Impact Analysis — PR #2322Risk tier: 🔴 CRITICAL 📊 Summary
🎯 Risk Factors
📦 Modules Affectedci-workflows (1 file)
docs (5 files)
root (16 files)
squad-cli (14 files)
squad-sdk (14 files)
templates (13 files)
tests (2 files)
This report is generated automatically for every PR. See #733 for details. |
de47157 to
bfbd312
Compare
|
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. |
|
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. |
|
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? |
|
The Next I'll push the |
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
bfbd312 to
2331cfa
Compare
|
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! 🙂 |
|
👋 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. |
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
#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.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
scenarios/disaster-recovery.md,scenarios/large-codebase.md,reference/compaction-recovery.md,features/reflect.md,tips-and-tricks.md, and the Scribe row title inreference/host-feature-matrix.md. They're user-facing walkthroughs that need rewriting, not one-line fixes, so I'd send them as a separate docs PR.packages/squad-cli/src/cli/core/team-md.ts:120. The Scribe row it labels is filtered out of rosters..squad/agents/scribe/charter.mdonsquad upgrade.Related: #1268, #1823.
.changeset/scribe-single-definition.md)PR Readiness Checklist
Branch & Commit
dev(notmain)dev(c3f54c2)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.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.