Skip to content

Commit de47157

Browse files
committed
fix(templates): give Scribe one definition
Since #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. Closes #2321
1 parent 9d7dff8 commit de47157

59 files changed

Lines changed: 237 additions & 292 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
"@bradygaster/squad-cli": patch
3+
"@bradygaster/squad-sdk": patch
4+
---
5+
6+
Give Scribe one definition. Every prompt surface (coordinator after-agent reference, host coordinator digest, routing template, spawn reference, ceremony reference, model-selection reference, built-in skills, the templates README and the watch decision-hygiene prompt) now matches the bounded Scribe charter: Scribe merges accepted durable decisions only. Session logs, orchestration logs, cross-agent history appends and archival are no longer requested from Scribe; size hygiene is `squad nap`.

‎.github/agents/squad.agent.md‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -125,7 +125,7 @@ requirements remain in `.github/PR_REQUIREMENTS.md`.
125125

126126
**If you wrote code, generated artifacts, or produced domain work without dispatching to an agent, you violated this rule. The coordinator ROUTES — it does not BUILD. No exceptions.**
127127

128-
**On every session start:** Run `git config user.name` to identify the current user, and **resolve the team root** (see Worktree Awareness). Store the team root — all `.squad/` paths must be resolved relative to it. Resolve `CURRENT_DATETIME` once from the `<current_datetime>` value in your system context. Sanity-check that it is a real ISO-like timestamp, not placeholder text, with a plausible year and timezone (`Z` or an offset). If the system value is missing or implausible, run a local date command and use that result instead (`date +"%Y-%m-%dT%H:%M:%S%z"` on macOS/Linux, or `Get-Date -Format o` in PowerShell). Pass the team root and the resolved literal current datetime into every spawn prompt as `TEAM_ROOT` and `CURRENT_DATETIME` respectively. Never pass placeholder text for `CURRENT_DATETIME`. Pass the current user's name into every agent spawn prompt and Scribe log so the team always knows who requested the work. Check `.squad/identity/now.md` if it exists — it tells you what the team was last focused on. Update it if the focus has shifted.
128+
**On every session start:** Run `git config user.name` to identify the current user, and **resolve the team root** (see Worktree Awareness). Store the team root — all `.squad/` paths must be resolved relative to it. Resolve `CURRENT_DATETIME` once from the `<current_datetime>` value in your system context. Sanity-check that it is a real ISO-like timestamp, not placeholder text, with a plausible year and timezone (`Z` or an offset). If the system value is missing or implausible, run a local date command and use that result instead (`date +"%Y-%m-%dT%H:%M:%S%z"` on macOS/Linux, or `Get-Date -Format o` in PowerShell). Pass the team root and the resolved literal current datetime into every spawn prompt as `TEAM_ROOT` and `CURRENT_DATETIME` respectively. Never pass placeholder text for `CURRENT_DATETIME`. Pass the current user's name into every agent spawn prompt so the team always knows who requested the work. Check `.squad/identity/now.md` if it exists — it tells you what the team was last focused on. Update it if the focus has shifted.
129129

130130
**Resolve state backend:** Read `.squad/config.json` (at the resolved TEAM_ROOT) and check the `stateBackend` field. Valid values: `"local"` (default), `"orphan"`, `"two-layer"`. Legacy alias: `"worktree"` maps to `"local"`. Deprecated: `"git-notes"` maps to `"two-layer"` with a deprecation warning. Store as `STATE_BACKEND` and pass it into every spawn prompt. This determines how agents read and write mutable state (history, decisions, logs). Static config (charters, team.md, routing.md) always lives on disk regardless of backend. The `"two-layer"` option combines git-notes (commit-scoped annotations) with orphan branch (permanent state) — see the blog post for the full architecture.
131131

@@ -199,7 +199,6 @@ For each squad member with assigned issues, note them in the session context. Wh
199199
```
200200
🔧 Runtime Engineer — error handling in index.js
201201
🧪 Quality Engineer — writing test cases
202-
📋 Scribe — logging session
203202
```
204203

205204
The acknowledgment goes in the same response as the `task` tool calls — text first, then tool calls. Keep it to 1-2 sentences plus the table. Don't narrate the plan; just show who's working on what.
@@ -235,7 +234,7 @@ When spawning agents, include the role emoji in the `description` parameter to m
235234
- `name: "lead"`, `description: "🏗️ Lead: Reviewing architecture proposal"`
236235
- `name: "runtime-engineer"`, `description: "🔧 Runtime Engineer: Refactoring auth module"`
237236
- `name: "quality-engineer"`, `description: "🧪 Quality Engineer: Writing test cases"`
238-
- `name: "scribe"`, `description: "📋 Scribe: Log session & merge decisions"`
237+
- `name: "scribe"`, `description: "📋 Scribe: Merge durable decisions"`
239238

240239
The `name` parameter generates the human-readable agent ID shown in the tasks panel — it MUST be the agent's lowercase cast name (e.g., `"runtime-engineer"`, `"quality-engineer"`). Without it, the platform shows generic slugs like "general-purpose-task" instead of the cast name. The emoji in `description` makes task spawn notifications visually consistent with the launch table shown to users.
241240

@@ -633,7 +632,7 @@ when needed, and present compact outcomes. Spawn Scribe only when durable decisi
633632
merging. Keep the same accountable owner for follow-up work unless a new independently deliverable
634633
outcome requires rerouting.
635634
636-
**On-demand reference:** Read `.squad/templates/after-agent-reference.md` for the full silent-success rules, Scribe spawn template, and follow-up sequence.
635+
**On-demand reference:** Read `.squad/templates/after-agent-reference.md` for the full silent-success rules and follow-up sequence. Its Scribe spawn prompt is identical to the Scribe Spawn Template above; Scribe's duties come only from its charter.
637636
638637
### Ceremonies
639638
@@ -645,7 +644,7 @@ Ceremonies are structured team meetings where agents align before or after work.
645644
1. Before spawning a work batch, check `.squad/ceremonies.md` for auto-triggered `before` ceremonies matching the current task condition.
646645
2. After a batch completes, check for `after` ceremonies. Manual ceremonies run only when the user asks.
647646
3. Spawn the facilitator (sync) using the template in the reference file. Facilitator spawns participants as sub-tasks.
648-
4. For `before`: include ceremony summary in work batch spawn prompts. Spawn Scribe (background) to record.
647+
4. For `before`: include ceremony summary in work batch spawn prompts. The facilitator records ceremony decisions with `squad_decide`; Scribe merges them later like any other inbox entry.
649648
5. **Ceremony cooldown:** Skip auto-triggered checks for the immediately following step.
650649
6. Show: `📋 {CeremonyName} completed — facilitated by {Lead}. Decisions: {count} | Action items: {count}.`
651650

‎.squad-templates/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ of these — they are NOT loaded on every turn.
2929
| `mcp-config.md` | Coordinator | MCP server integration details |
3030
| `model-selection-reference.md` | Coordinator | Per-agent model and reasoning-effort selection |
3131
| `multi-agent-format.md` | Coordinator | Assembling multi-agent artifact output |
32-
| `orchestration-log.md` | Scribe | Writing per-agent orchestration log entries |
32+
| `orchestration-log.md` | Legacy (no default writer; not Scribe) | Format of per-agent orchestration log entries |
3333
| `plugin-marketplace.md` | Coordinator | Plugin marketplace discovery and install flow |
3434
| `prd-intake.md` | Coordinator | PRD Mode — ingesting a spec for decomposition |
3535
| `ralph-reference.md` | Coordinator | Ralph work-monitor lifecycle and board format |

‎.squad-templates/after-agent-reference.md‎

Lines changed: 15 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,9 @@
77
(2) "Server Error Retry Loop" — context overflow after fan-out. Mitigated by lean
88
post-work turn + Scribe delegation + compact result presentation. -->
99

10-
**⚡ Keep the post-work turn LEAN.** Coordinator's job: (1) present compact results, (2) spawn Scribe. That's ALL. No orchestration logs, no decision consolidation, no heavy file I/O.
10+
**⚡ Keep the post-work turn LEAN.** Coordinator's job: (1) present compact results, (2) spawn Scribe only when accepted durable decisions need merging. That's ALL. No session or orchestration logs, no decision consolidation, no heavy file I/O.
1111

12-
**⚡ Context budget rule:** After collecting results from 3+ agents, use compact format (agent + 1-line outcome). Full details go in orchestration log via Scribe.
12+
**⚡ Context budget rule:** After collecting results from 3+ agents, use compact format (agent + 1-line outcome). Do not paste full agent output. Durable outcomes belong in decisions (`squad_decide`); each agent appends its own learnings to its own `history.md`.
1313

1414
After each batch of agent work:
1515

@@ -22,63 +22,34 @@ After each batch of agent work:
2222

2323
3. **Show compact results:** `{emoji} {Name} — {1-line summary of what they did}`
2424

25-
4. **Spawn Scribe** (background, never wait). Only if agents ran or inbox has files:
25+
4. **Spawn Scribe** (background, never wait) only when `decisions/inbox` holds accepted durable decisions to merge. Scribe's duties come only from its charter (`.squad/agents/scribe/charter.md`). The prompt below must stay identical to the **Scribe Spawn Template** in `squad.agent.md`:
2626

2727
```
2828
agent_type: "general-purpose"
2929
model: "claude-haiku-4.5"
3030
mode: "background"
3131
name: "scribe"
32-
description: "📋 Scribe: Log session & merge decisions"
32+
description: "📋 Scribe: Merge durable decisions"
3333
prompt: |
3434
You are the Scribe. Read .squad/agents/scribe/charter.md.
3535
TEAM ROOT: {team_root}
3636
CURRENT_DATETIME: <resolved CURRENT_DATETIME literal>
3737
STATE_BACKEND: {state_backend}
3838
39-
SPAWN MANIFEST: {spawn_manifest}
40-
4139
Tasks (in order):
42-
0. PRE-CHECK: Run `squad_state_health` when available. If state tools are unavailable,
43-
stop without mutating files or git state.
44-
0b. PRE-CHECK: Read `decisions.md` and list `decisions/inbox` with state tools.
45-
Record measurements.
46-
1. DECISIONS ARCHIVE [HARD GATE]: If decisions.md >= 20480 bytes, archive entries older than 30 days NOW. If >= 51200 bytes, archive entries older than 7 days. Do not skip this step. Follow the ARCHIVAL SAFETY RULES below — they are not optional.
47-
2. DECISION INBOX: Use `squad_state_list` and `squad_state_read` on `decisions/inbox`,
48-
merge entries into `decisions.md` with `squad_state_write`, delete processed inbox
49-
entries with `squad_state_delete`, and deduplicate. Before splicing an inbox body
50-
beneath an `###` entry, DEMOTE its headings so its shallowest heading lands at
51-
`####` (`##` -> `####`). Preserve relative structure. Never emit an `##` under an `###`.
52-
3. ORCHESTRATION LOG: Write `orchestration-log/{timestamp}-{agent}.md` with `squad_state_write` per agent. Use ISO 8601 UTC timestamp. Replace `:` with `-` in `{timestamp}` so filenames are valid on all platforms (e.g. `2026-06-02T21-15-30Z`).
53-
4. SESSION LOG: Write `log/{timestamp}-{topic}.md` with `squad_state_write`. Brief. Use ISO 8601 UTC timestamp. Replace `:` with `-` in `{timestamp}` so filenames are valid on all platforms.
54-
5. CROSS-AGENT: Append team updates to affected agents' `agents/{agent}/history.md` with `squad_state_append`.
55-
6. HISTORY SUMMARIZATION [HARD GATE]: If any history.md >= 15360 bytes (15KB), summarize now. The ARCHIVAL SAFETY RULES apply here too — summarization moves content out of a file exactly like decision archival does.
56-
7. HEALTH REPORT: Report ENTRY COUNTS, never file sizes: `N removed from source / N added to destination` for every archival, plus inbox count processed and history files summarized. Write with `squad_state_write` or `squad_state_append`.
57-
58-
ARCHIVAL SAFETY RULES (apply to every operation that moves content out of a file):
59-
A. DESTINATION MUST BE TRACKED. Before writing, run `git ls-files --error-unmatch <destination>`.
60-
Exit 0 -> proceed. Non-zero -> redirect to an existing tracked archive file, or ABORT with a
61-
clear error. `.squad/` is git-excluded in many checkouts: already-tracked files still commit,
62-
but NEW files silently never do. Moving content into an untracked destination is a DELETION,
63-
not an archive. Never create a new timestamped archive file and assume it will commit.
64-
B. APPEND FIRST, VERIFY, THEN DELETE. Append to the destination. Re-read the destination and
65-
confirm every moved heading is literally present AND the entry count grew by exactly the
66-
number moved. Only then remove from the source. If the append cannot be verified, DO NOT
67-
trim — leave the source intact and report the failure. Losing history is far worse than
68-
leaving a file over its size gate.
69-
C. COUNT ENTRIES, NOT BYTES. File size is not a valid integrity signal: a merge and an archive
70-
in the same pass move size in opposite directions, so a size delta proves nothing.
71-
D. NEVER REPORT A GATE OUTCOME YOU DID NOT MEASURE. "No archival required" must come from an
72-
actual measurement. A gate that reports without measuring is worse than no gate.
73-
E. If a state tool cannot perform these checks, STOP and report rather than proceeding with an
74-
unverified move.
75-
76-
Runtime state tools own persistence. Never switch branches, push note refs, reset
77-
`.squad/`, or commit mutable squad state from this prompt.
78-
79-
Never speak to user. ⚠️ End with plain text summary after all tool calls.
40+
0. PRE-CHECK: Run `squad_state_health` when available. If state tools are unavailable, stop without mutating files or git state.
41+
0b. PRE-CHECK: Read `decisions.md` and list `decisions/inbox` with state tools. Record measurements.
42+
1. DECISION INBOX: Use `squad_state_list` and `squad_state_read` on `decisions/inbox`, merge accepted durable decisions into `decisions.md` with `squad_state_write`, delete processed inbox entries with `squad_state_delete`, and deduplicate. Before splicing an inbox body beneath an `###` entry, DEMOTE its headings so its shallowest heading lands at `####` (`##` -> `####`). Preserve relative structure. Never emit an `##` under an `###`.
43+
2. VERIFY: Re-read `decisions.md` and confirm every merged entry is present before deleting its inbox source.
44+
3. GIT COMMIT: Do not commit mutable squad state. If non-state repo files changed, report them for coordinator handling.
45+
46+
Runtime state tools own persistence. Never switch branches, push note refs, reset `.squad/`, or commit mutable squad state from this prompt.
47+
48+
Never speak to user. End with plain text summary after all tool calls.
8049
```
8150

51+
Scribe does not write session logs, orchestration logs or other agents' `history.md`, and it does not archive. Size hygiene (archiving old decisions, compressing large histories, pruning old logs) is the `squad nap` CLI command, not a Scribe task.
52+
8253
5. **Immediately assess:** Does anything trigger follow-up work? Launch it NOW.
8354

8455
6. **Ralph check:** If Ralph is active (see Ralph — Work Monitor), after chaining any follow-up work, IMMEDIATELY run Ralph's work-check cycle (Step 1). Do NOT stop. Do NOT wait for user input. Ralph keeps the pipeline moving until the board is clear.

‎.squad-templates/ceremony-reference.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ TASK CONTEXT:
7373
- `all-relevant` → agents routed to the current task
7474
- `all-involved` → agents that participated in the completed batch
7575
- Named agents → spawn only those specific agents
76-
6. **Scribe integration:** Spawn Scribe (background) at ceremony start to record decisions and action items.
76+
6. **Scribe integration:** The facilitator records ceremony decisions with `squad_decide`. Scribe merges them afterwards like any other inbox entry; do not spawn Scribe at ceremony start.
7777
7. **Output format:**
7878
```
7979
📋 {CeremonyName} completed — facilitated by {Facilitator}.

‎.squad-templates/model-selection-reference.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,7 @@ Quality-sensitive work that is not code (architecture, research, verification, r
7070
| Copilot SDK Expert | Standard | Technical analysis that often touches code | Deep research → premium |
7171
| Designer / Visual | Premium | Vision-capable model required | — (never downgrade — vision is non-negotiable) |
7272
| DevRel / Writer | Standard | Language-heavy work benefits from a stronger model | Economy profile → fast |
73-
| Scribe / Logger | Fast | Mechanical file ops | — (never bump Scribe) |
73+
| Scribe | Fast | Mechanical decision merging | — (never bump Scribe) |
7474
| Git / Release | Fast | Mechanical ops — changelogs, tags, version bumps | — (never bump mechanical ops) |
7575

7676
**Task complexity adjustments** (apply at most ONE — no cascading):
@@ -119,7 +119,7 @@ Every spawn acknowledgment names the resolved model, its source and a short rati
119119
120120
🔧 Runtime Engineer ({model} · session) — refactoring auth module — session model inherited by this spawn
121121
🎨 Experience Engineer ({model} · task-auto) — designing color system — visual task needs vision → premium tier
122-
📋 Scribe ({model} · task-auto) — logging session — mechanical task → fast tier
122+
📋 Scribe ({model} · task-auto) — merging decisions — mechanical task → fast tier
123123
⚡ Lead ({model} · config) — reviewing proposal — agentModelOverrides.lead in .squad/config.json
124124
📝 Docs Engineer ({model} · fallback) — updating docs — charter model unavailable; next in fast chain
125125
```

‎.squad-templates/routing.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ here only when their agent names also exist in the casting registry.
2727
## Rules
2828

2929
1. **Eager by default** — spawn all agents who could usefully start work, including anticipatory downstream work.
30-
2. **Scribe always runs** after substantial work, always as `mode: "background"`. Never blocks.
30+
2. **Scribe runs only when accepted durable decisions need merging**, always as `mode: "background"`. Never blocks.
3131
3. **Quick facts → coordinator answers directly.** Don't spawn an agent for "what port does the server run on?"
3232
4. **When two agents could handle it**, pick the one whose domain is the primary concern.
3333
5. **"Team, ..." → fan-out.** Spawn all relevant agents in parallel as `mode: "background"`.

‎.squad-templates/skills/agent-collaboration/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,5 +38,5 @@ If you have reviewer authority and reject work: the original author is locked ou
3838
## Anti-Patterns
3939
- Don't read all agent charters — you only need your own context + decisions.md
4040
- Don't write directly to `.squad/decisions.md` — always use the inbox drop-box
41-
- Don't modify other agents' history.md files — that's Scribe's job
41+
- Don't modify other agents' history.md files — record team-relevant facts with `squad_decide` instead
4242
- Don't assume CWD is the repo root — always use TEAM ROOT

0 commit comments

Comments
 (0)