You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit de47157
Browse filesBrowse the repository at this point in the historyBrowse files
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
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`.
Copy file name to clipboardExpand all lines: .github/agents/squad.agent.md
+4-5Lines changed: 4 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -125,7 +125,7 @@ requirements remain in `.github/PR_REQUIREMENTS.md`.
125
125
126
126
**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.**
127
127
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.
129
129
130
130
**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.
131
131
@@ -199,7 +199,6 @@ For each squad member with assigned issues, note them in the session context. Wh
199
199
```
200
200
🔧 Runtime Engineer — error handling in index.js
201
201
🧪 Quality Engineer — writing test cases
202
-
📋 Scribe — logging session
203
202
```
204
203
205
204
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
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.
241
240
@@ -633,7 +632,7 @@ when needed, and present compact outcomes. Spawn Scribe only when durable decisi
633
632
merging. Keep the same accountable owner for follow-up work unless a new independently deliverable
634
633
outcome requires rerouting.
635
634
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 rulesand follow-up sequence. Its Scribe spawn prompt is identical to the Scribe Spawn Template above; Scribe's duties come only from its charter.
637
636
638
637
### Ceremonies
639
638
@@ -645,7 +644,7 @@ Ceremonies are structured team meetings where agents align before or after work.
645
644
1. Before spawning a work batch, check `.squad/ceremonies.md` for auto-triggered `before` ceremonies matching the current task condition.
646
645
2. After a batch completes, check for `after` ceremonies. Manual ceremonies run only when the user asks.
647
646
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.
649
648
5. **Ceremony cooldown:** Skip auto-triggered checks for the immediately following step.
Copy file name to clipboardExpand all lines: .squad-templates/after-agent-reference.md
+15-44Lines changed: 15 additions & 44 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,9 +7,9 @@
7
7
(2) "Server Error Retry Loop" — context overflow after fan-out. Mitigated by lean
8
8
post-work turn + Scribe delegation + compact result presentation. -->
9
9
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.
11
11
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`.
13
13
14
14
After each batch of agent work:
15
15
@@ -22,63 +22,34 @@ After each batch of agent work:
22
22
23
23
3.**Show compact results:**`{emoji} {Name} — {1-line summary of what they did}`
24
24
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`:
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.
80
49
```
81
50
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
+
82
53
5.**Immediately assess:** Does anything trigger follow-up work? Launch it NOW.
83
54
84
55
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.
Copy file name to clipboardExpand all lines: .squad-templates/ceremony-reference.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -73,7 +73,7 @@ TASK CONTEXT:
73
73
-`all-relevant` → agents routed to the current task
74
74
-`all-involved` → agents that participated in the completed batch
75
75
- 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.
77
77
7.**Output format:**
78
78
```
79
79
📋 {CeremonyName} completed — facilitated by {Facilitator}.
0 commit comments