From 76b9515cbeb8f99b9b674ef3479bd81e128852b4 Mon Sep 17 00:00:00 2001 From: brady gaster Date: Sun, 30 Aug 2026 09:48:27 -0700 Subject: [PATCH 1/6] =?UTF-8?q?docs:=20add=20.squad/templates/README.md=20?= =?UTF-8?q?=E2=80=94=20runtime=20inputs=20vs=20bootstrap=20templates?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a README.md template that ships with squad init to explain which files under .squad/templates/ are runtime inputs (coordinator reads them on-demand) vs bootstrap templates (used once to seed agent files). Register it in the TEMPLATE_MANIFEST so it lands in every generated project and is kept current by squad upgrade. Also drop a copy of the README into this repo's .squad/templates/ directly. Closes #1494 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .changeset/1494-templates-readme.md | 5 ++ .squad/templates/README.md | 82 +++++++++++++++++++ packages/squad-cli/src/cli/core/templates.ts | 8 ++ .../squad-cli/templates/templates-readme.md | 82 +++++++++++++++++++ 4 files changed, 177 insertions(+) create mode 100644 .changeset/1494-templates-readme.md create mode 100644 .squad/templates/README.md create mode 100644 packages/squad-cli/templates/templates-readme.md diff --git a/.changeset/1494-templates-readme.md b/.changeset/1494-templates-readme.md new file mode 100644 index 000000000..7cb20dc23 --- /dev/null +++ b/.changeset/1494-templates-readme.md @@ -0,0 +1,5 @@ +--- +"@bradygaster/squad-cli": patch +--- + +Add `.squad/templates/README.md` to init output explaining which files are runtime inputs vs bootstrap templates, and register the source template in the manifest. Closes #1494. diff --git a/.squad/templates/README.md b/.squad/templates/README.md new file mode 100644 index 000000000..7f6bebba2 --- /dev/null +++ b/.squad/templates/README.md @@ -0,0 +1,82 @@ +# `.squad/templates/` — What Lives Here and Why + +This directory is **read at runtime** by the Squad coordinator and agents. Do not delete files +from it — doing so breaks coordinator behavior that depends on lazy-loading these references. + +If you want to customize coordinator behavior, edit the relevant file here. On `squad upgrade`, +files marked squad-owned are overwritten; user-customizable overrides are preserved. + +--- + +## File Categories + +### Coordinator on-demand references +Loaded lazily by the coordinator when a matching situation arises (e.g. when running a +ceremony, spawning with worktree isolation, or building the session init checklist). The +coordinator's system prompt says "On-demand reference: Read `.squad/templates/`" for each +of these — they are NOT loaded on every turn. + +| File | Read by | Situation | +|------|---------|-----------| +| `after-agent-reference.md` | Coordinator | Collecting results after agent work | +| `casting-reference.md` | Coordinator | Init Mode or adding/recasting team members | +| `ceremony-reference.md` | Coordinator | Running team ceremonies | +| `client-compatibility-reference.md` | Coordinator | CLI / VS Code / App platform differences | +| `constraint-tracking.md` | Coordinator | Tracking budget constraints in a session | +| `copilot-agent.md` | Coordinator | Adding @copilot as a team member | +| `human-members.md` | Coordinator | Adding a human to the team roster | +| `issue-lifecycle.md` | Coordinator | GitHub Issues Mode — issue → PR → merge flow | +| `mcp-config.md` | Coordinator | MCP server integration details | +| `model-selection-reference.md` | Coordinator | Per-agent model and reasoning-effort selection | +| `multi-agent-format.md` | Coordinator | Assembling multi-agent artifact output | +| `orchestration-log.md` | Scribe | Writing per-agent orchestration log entries | +| `plugin-marketplace.md` | Coordinator | Plugin marketplace discovery and install flow | +| `prd-intake.md` | Coordinator | PRD Mode — ingesting a spec for decomposition | +| `ralph-reference.md` | Coordinator | Ralph work-monitor lifecycle and board format | +| `raw-agent-output.md` | Coordinator | Raw agent output appendix format | +| `session-init-reference.md` | Coordinator | Procedures run at every session start | +| `spawn-reference.md` | Coordinator | Full agent spawn template and Ghost Protocol | +| `worktree-reference.md` | Coordinator | Worktree strategies, lifecycle, and pre-spawn setup | + +### Agent bootstrap templates +Used **once** by `squad init` or when `squad upgrade` / coordinator code creates a new agent. +After the agent's own files are seeded, these templates are not read again at runtime. + +| File | Used to seed | +|------|-------------| +| `charter.md` | New agent `charter.md` when a team member is added | +| `copilot-instructions.md` | `.github/copilot-instructions.md` for the repo | +| `fact-checker-charter.md` | `agents/fact-checker/charter.md` | +| `fact-checker-policy.md` | `agents/fact-checker/policy.md` (Fact Checker methodology) | +| `history.md` | New agent `history.md` when a team member is added | +| `Rai-charter.md` | `agents/Rai/charter.md` | +| `rai-policy.md` | `agents/Rai/policy.md` (RAI check taxonomy) | +| `roster.md` | Roster entry format guidance for `team.md` | +| `run-output.md` | Standard run output format for agent responses | +| `scribe-charter.md` | `agents/scribe/charter.md` | +| `skill.md` | Skeleton for new skill files under `.github/skills/` | + +--- + +## Invariant + +Nothing should be added to `.squad/templates/` without also being registered in the CLI's +`TEMPLATE_MANIFEST` (`packages/squad-cli/src/cli/core/templates.ts`) as **either**: + +1. A **runtime input** (coordinator reads it by path) — include the reader and situation in + the on-demand table above. +2. A **bootstrap template** (used once to seed a generated file) — include the target in the + bootstrap table above. + +If a file in this directory is neither, it is a stale copy and safe to remove. See #1436 for +the cleanup tracker. + +--- + +## Historical note — `workflows/` and `skills/` subtrees + +Earlier Squad versions copied `.github/workflows/` and `.github/skills/` content into +`.squad/templates/workflows/` and `.squad/templates/skills/` as well. Those copies were never +read at runtime — they were stale duplicates. The `TEMPLATE_MANIFEST` now routes workflows +directly to `.github/workflows/` and skills directly to `.github/skills/`. If your project +still has these subdirectories under `.squad/templates/`, they are safe to delete. See #1436. diff --git a/packages/squad-cli/src/cli/core/templates.ts b/packages/squad-cli/src/cli/core/templates.ts index 621cf86f6..734b3efb9 100644 --- a/packages/squad-cli/src/cli/core/templates.ts +++ b/packages/squad-cli/src/cli/core/templates.ts @@ -334,6 +334,14 @@ export const TEMPLATE_MANIFEST: TemplateFile[] = [ overwriteOnUpgrade: true, description: 'Session init reference — coordinator procedures run at session start', }, + // Templates directory README (squad-owned) — explains which files are runtime inputs + // vs bootstrap templates so contributors and users don't accidentally delete load-bearing files. + { + source: 'templates-readme.md', + destination: 'templates/README.md', + overwriteOnUpgrade: true, + description: 'Templates directory guide — runtime inputs vs bootstrap templates', + }, // Workflows (squad-owned, overwrite on upgrade) { diff --git a/packages/squad-cli/templates/templates-readme.md b/packages/squad-cli/templates/templates-readme.md new file mode 100644 index 000000000..7f6bebba2 --- /dev/null +++ b/packages/squad-cli/templates/templates-readme.md @@ -0,0 +1,82 @@ +# `.squad/templates/` — What Lives Here and Why + +This directory is **read at runtime** by the Squad coordinator and agents. Do not delete files +from it — doing so breaks coordinator behavior that depends on lazy-loading these references. + +If you want to customize coordinator behavior, edit the relevant file here. On `squad upgrade`, +files marked squad-owned are overwritten; user-customizable overrides are preserved. + +--- + +## File Categories + +### Coordinator on-demand references +Loaded lazily by the coordinator when a matching situation arises (e.g. when running a +ceremony, spawning with worktree isolation, or building the session init checklist). The +coordinator's system prompt says "On-demand reference: Read `.squad/templates/`" for each +of these — they are NOT loaded on every turn. + +| File | Read by | Situation | +|------|---------|-----------| +| `after-agent-reference.md` | Coordinator | Collecting results after agent work | +| `casting-reference.md` | Coordinator | Init Mode or adding/recasting team members | +| `ceremony-reference.md` | Coordinator | Running team ceremonies | +| `client-compatibility-reference.md` | Coordinator | CLI / VS Code / App platform differences | +| `constraint-tracking.md` | Coordinator | Tracking budget constraints in a session | +| `copilot-agent.md` | Coordinator | Adding @copilot as a team member | +| `human-members.md` | Coordinator | Adding a human to the team roster | +| `issue-lifecycle.md` | Coordinator | GitHub Issues Mode — issue → PR → merge flow | +| `mcp-config.md` | Coordinator | MCP server integration details | +| `model-selection-reference.md` | Coordinator | Per-agent model and reasoning-effort selection | +| `multi-agent-format.md` | Coordinator | Assembling multi-agent artifact output | +| `orchestration-log.md` | Scribe | Writing per-agent orchestration log entries | +| `plugin-marketplace.md` | Coordinator | Plugin marketplace discovery and install flow | +| `prd-intake.md` | Coordinator | PRD Mode — ingesting a spec for decomposition | +| `ralph-reference.md` | Coordinator | Ralph work-monitor lifecycle and board format | +| `raw-agent-output.md` | Coordinator | Raw agent output appendix format | +| `session-init-reference.md` | Coordinator | Procedures run at every session start | +| `spawn-reference.md` | Coordinator | Full agent spawn template and Ghost Protocol | +| `worktree-reference.md` | Coordinator | Worktree strategies, lifecycle, and pre-spawn setup | + +### Agent bootstrap templates +Used **once** by `squad init` or when `squad upgrade` / coordinator code creates a new agent. +After the agent's own files are seeded, these templates are not read again at runtime. + +| File | Used to seed | +|------|-------------| +| `charter.md` | New agent `charter.md` when a team member is added | +| `copilot-instructions.md` | `.github/copilot-instructions.md` for the repo | +| `fact-checker-charter.md` | `agents/fact-checker/charter.md` | +| `fact-checker-policy.md` | `agents/fact-checker/policy.md` (Fact Checker methodology) | +| `history.md` | New agent `history.md` when a team member is added | +| `Rai-charter.md` | `agents/Rai/charter.md` | +| `rai-policy.md` | `agents/Rai/policy.md` (RAI check taxonomy) | +| `roster.md` | Roster entry format guidance for `team.md` | +| `run-output.md` | Standard run output format for agent responses | +| `scribe-charter.md` | `agents/scribe/charter.md` | +| `skill.md` | Skeleton for new skill files under `.github/skills/` | + +--- + +## Invariant + +Nothing should be added to `.squad/templates/` without also being registered in the CLI's +`TEMPLATE_MANIFEST` (`packages/squad-cli/src/cli/core/templates.ts`) as **either**: + +1. A **runtime input** (coordinator reads it by path) — include the reader and situation in + the on-demand table above. +2. A **bootstrap template** (used once to seed a generated file) — include the target in the + bootstrap table above. + +If a file in this directory is neither, it is a stale copy and safe to remove. See #1436 for +the cleanup tracker. + +--- + +## Historical note — `workflows/` and `skills/` subtrees + +Earlier Squad versions copied `.github/workflows/` and `.github/skills/` content into +`.squad/templates/workflows/` and `.squad/templates/skills/` as well. Those copies were never +read at runtime — they were stale duplicates. The `TEMPLATE_MANIFEST` now routes workflows +directly to `.github/workflows/` and skills directly to `.github/skills/`. If your project +still has these subdirectories under `.squad/templates/`, they are safe to delete. See #1436. From b03a58b01b177ee926f83f08fd86e8b6fe9252a2 Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Tue, 1 Sep 2026 08:38:43 -0700 Subject: [PATCH 2/6] fix(templates): make templates README reach squad init output MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Copilot review on #1949 found that registering `templates-readme.md` in TEMPLATE_MANIFEST does not put the README into `squad init` output. Verified: `squad init` seeds `.squad/templates/` with a verbatim recursive copy of the SDK templates directory (`copyRecursiveSync(getSDKTemplatesDir(), ...)` in packages/squad-sdk/src/config/init.ts), so a file only reaches new projects if it lives in that directory under its final name. The README existed only as `packages/squad-cli/templates/templates-readme.md`, so new projects got nothing. Promote the file to the canonical source `.squad-templates/README.md` and let scripts/sync-templates.mjs mirror it to templates/, packages/squad-cli/templates/ and packages/squad-sdk/templates/. Manifest source becomes `README.md` so the canonical name already matches the destination name. Verified `getSDKTemplatesDir()` resolves to packages/squad-sdk/templates and that README.md is now present there — the exact path init copies from. Also correct the bootstrap table: the charter template on disk is `rai-charter.md` (lowercase), not `Rai-charter.md`. Pin the routing in test/template-routing.test.ts. Mirror sync is already covered by test/template-sync.test.ts, which enumerates `.squad-templates/` dynamically. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 0515ad5d-4c5b-48bb-92a6-4e1296594cab --- .../README.md | 2 +- .squad/templates/README.md | 2 +- packages/squad-cli/src/cli/core/templates.ts | 5 +- packages/squad-cli/templates/README.md | 82 +++++++++++++++++++ packages/squad-sdk/templates/README.md | 82 +++++++++++++++++++ templates/README.md | 82 +++++++++++++++++++ test/template-routing.test.ts | 1 + 7 files changed, 253 insertions(+), 3 deletions(-) rename packages/squad-cli/templates/templates-readme.md => .squad-templates/README.md (98%) create mode 100644 packages/squad-cli/templates/README.md create mode 100644 packages/squad-sdk/templates/README.md create mode 100644 templates/README.md diff --git a/packages/squad-cli/templates/templates-readme.md b/.squad-templates/README.md similarity index 98% rename from packages/squad-cli/templates/templates-readme.md rename to .squad-templates/README.md index 7f6bebba2..310f686f2 100644 --- a/packages/squad-cli/templates/templates-readme.md +++ b/.squad-templates/README.md @@ -49,7 +49,7 @@ After the agent's own files are seeded, these templates are not read again at ru | `fact-checker-charter.md` | `agents/fact-checker/charter.md` | | `fact-checker-policy.md` | `agents/fact-checker/policy.md` (Fact Checker methodology) | | `history.md` | New agent `history.md` when a team member is added | -| `Rai-charter.md` | `agents/Rai/charter.md` | +| `rai-charter.md` | `agents/Rai/charter.md` | | `rai-policy.md` | `agents/Rai/policy.md` (RAI check taxonomy) | | `roster.md` | Roster entry format guidance for `team.md` | | `run-output.md` | Standard run output format for agent responses | diff --git a/.squad/templates/README.md b/.squad/templates/README.md index 7f6bebba2..310f686f2 100644 --- a/.squad/templates/README.md +++ b/.squad/templates/README.md @@ -49,7 +49,7 @@ After the agent's own files are seeded, these templates are not read again at ru | `fact-checker-charter.md` | `agents/fact-checker/charter.md` | | `fact-checker-policy.md` | `agents/fact-checker/policy.md` (Fact Checker methodology) | | `history.md` | New agent `history.md` when a team member is added | -| `Rai-charter.md` | `agents/Rai/charter.md` | +| `rai-charter.md` | `agents/Rai/charter.md` | | `rai-policy.md` | `agents/Rai/policy.md` (RAI check taxonomy) | | `roster.md` | Roster entry format guidance for `team.md` | | `run-output.md` | Standard run output format for agent responses | diff --git a/packages/squad-cli/src/cli/core/templates.ts b/packages/squad-cli/src/cli/core/templates.ts index 734b3efb9..469698a60 100644 --- a/packages/squad-cli/src/cli/core/templates.ts +++ b/packages/squad-cli/src/cli/core/templates.ts @@ -336,8 +336,11 @@ export const TEMPLATE_MANIFEST: TemplateFile[] = [ }, // Templates directory README (squad-owned) — explains which files are runtime inputs // vs bootstrap templates so contributors and users don't accidentally delete load-bearing files. + // Source is `README.md` (not a renamed variant) because `squad init` seeds `.squad/templates/` + // with a verbatim recursive copy of the SDK templates directory — the file only reaches new + // projects if its canonical name already matches the destination name. { - source: 'templates-readme.md', + source: 'README.md', destination: 'templates/README.md', overwriteOnUpgrade: true, description: 'Templates directory guide — runtime inputs vs bootstrap templates', diff --git a/packages/squad-cli/templates/README.md b/packages/squad-cli/templates/README.md new file mode 100644 index 000000000..310f686f2 --- /dev/null +++ b/packages/squad-cli/templates/README.md @@ -0,0 +1,82 @@ +# `.squad/templates/` — What Lives Here and Why + +This directory is **read at runtime** by the Squad coordinator and agents. Do not delete files +from it — doing so breaks coordinator behavior that depends on lazy-loading these references. + +If you want to customize coordinator behavior, edit the relevant file here. On `squad upgrade`, +files marked squad-owned are overwritten; user-customizable overrides are preserved. + +--- + +## File Categories + +### Coordinator on-demand references +Loaded lazily by the coordinator when a matching situation arises (e.g. when running a +ceremony, spawning with worktree isolation, or building the session init checklist). The +coordinator's system prompt says "On-demand reference: Read `.squad/templates/`" for each +of these — they are NOT loaded on every turn. + +| File | Read by | Situation | +|------|---------|-----------| +| `after-agent-reference.md` | Coordinator | Collecting results after agent work | +| `casting-reference.md` | Coordinator | Init Mode or adding/recasting team members | +| `ceremony-reference.md` | Coordinator | Running team ceremonies | +| `client-compatibility-reference.md` | Coordinator | CLI / VS Code / App platform differences | +| `constraint-tracking.md` | Coordinator | Tracking budget constraints in a session | +| `copilot-agent.md` | Coordinator | Adding @copilot as a team member | +| `human-members.md` | Coordinator | Adding a human to the team roster | +| `issue-lifecycle.md` | Coordinator | GitHub Issues Mode — issue → PR → merge flow | +| `mcp-config.md` | Coordinator | MCP server integration details | +| `model-selection-reference.md` | Coordinator | Per-agent model and reasoning-effort selection | +| `multi-agent-format.md` | Coordinator | Assembling multi-agent artifact output | +| `orchestration-log.md` | Scribe | Writing per-agent orchestration log entries | +| `plugin-marketplace.md` | Coordinator | Plugin marketplace discovery and install flow | +| `prd-intake.md` | Coordinator | PRD Mode — ingesting a spec for decomposition | +| `ralph-reference.md` | Coordinator | Ralph work-monitor lifecycle and board format | +| `raw-agent-output.md` | Coordinator | Raw agent output appendix format | +| `session-init-reference.md` | Coordinator | Procedures run at every session start | +| `spawn-reference.md` | Coordinator | Full agent spawn template and Ghost Protocol | +| `worktree-reference.md` | Coordinator | Worktree strategies, lifecycle, and pre-spawn setup | + +### Agent bootstrap templates +Used **once** by `squad init` or when `squad upgrade` / coordinator code creates a new agent. +After the agent's own files are seeded, these templates are not read again at runtime. + +| File | Used to seed | +|------|-------------| +| `charter.md` | New agent `charter.md` when a team member is added | +| `copilot-instructions.md` | `.github/copilot-instructions.md` for the repo | +| `fact-checker-charter.md` | `agents/fact-checker/charter.md` | +| `fact-checker-policy.md` | `agents/fact-checker/policy.md` (Fact Checker methodology) | +| `history.md` | New agent `history.md` when a team member is added | +| `rai-charter.md` | `agents/Rai/charter.md` | +| `rai-policy.md` | `agents/Rai/policy.md` (RAI check taxonomy) | +| `roster.md` | Roster entry format guidance for `team.md` | +| `run-output.md` | Standard run output format for agent responses | +| `scribe-charter.md` | `agents/scribe/charter.md` | +| `skill.md` | Skeleton for new skill files under `.github/skills/` | + +--- + +## Invariant + +Nothing should be added to `.squad/templates/` without also being registered in the CLI's +`TEMPLATE_MANIFEST` (`packages/squad-cli/src/cli/core/templates.ts`) as **either**: + +1. A **runtime input** (coordinator reads it by path) — include the reader and situation in + the on-demand table above. +2. A **bootstrap template** (used once to seed a generated file) — include the target in the + bootstrap table above. + +If a file in this directory is neither, it is a stale copy and safe to remove. See #1436 for +the cleanup tracker. + +--- + +## Historical note — `workflows/` and `skills/` subtrees + +Earlier Squad versions copied `.github/workflows/` and `.github/skills/` content into +`.squad/templates/workflows/` and `.squad/templates/skills/` as well. Those copies were never +read at runtime — they were stale duplicates. The `TEMPLATE_MANIFEST` now routes workflows +directly to `.github/workflows/` and skills directly to `.github/skills/`. If your project +still has these subdirectories under `.squad/templates/`, they are safe to delete. See #1436. diff --git a/packages/squad-sdk/templates/README.md b/packages/squad-sdk/templates/README.md new file mode 100644 index 000000000..310f686f2 --- /dev/null +++ b/packages/squad-sdk/templates/README.md @@ -0,0 +1,82 @@ +# `.squad/templates/` — What Lives Here and Why + +This directory is **read at runtime** by the Squad coordinator and agents. Do not delete files +from it — doing so breaks coordinator behavior that depends on lazy-loading these references. + +If you want to customize coordinator behavior, edit the relevant file here. On `squad upgrade`, +files marked squad-owned are overwritten; user-customizable overrides are preserved. + +--- + +## File Categories + +### Coordinator on-demand references +Loaded lazily by the coordinator when a matching situation arises (e.g. when running a +ceremony, spawning with worktree isolation, or building the session init checklist). The +coordinator's system prompt says "On-demand reference: Read `.squad/templates/`" for each +of these — they are NOT loaded on every turn. + +| File | Read by | Situation | +|------|---------|-----------| +| `after-agent-reference.md` | Coordinator | Collecting results after agent work | +| `casting-reference.md` | Coordinator | Init Mode or adding/recasting team members | +| `ceremony-reference.md` | Coordinator | Running team ceremonies | +| `client-compatibility-reference.md` | Coordinator | CLI / VS Code / App platform differences | +| `constraint-tracking.md` | Coordinator | Tracking budget constraints in a session | +| `copilot-agent.md` | Coordinator | Adding @copilot as a team member | +| `human-members.md` | Coordinator | Adding a human to the team roster | +| `issue-lifecycle.md` | Coordinator | GitHub Issues Mode — issue → PR → merge flow | +| `mcp-config.md` | Coordinator | MCP server integration details | +| `model-selection-reference.md` | Coordinator | Per-agent model and reasoning-effort selection | +| `multi-agent-format.md` | Coordinator | Assembling multi-agent artifact output | +| `orchestration-log.md` | Scribe | Writing per-agent orchestration log entries | +| `plugin-marketplace.md` | Coordinator | Plugin marketplace discovery and install flow | +| `prd-intake.md` | Coordinator | PRD Mode — ingesting a spec for decomposition | +| `ralph-reference.md` | Coordinator | Ralph work-monitor lifecycle and board format | +| `raw-agent-output.md` | Coordinator | Raw agent output appendix format | +| `session-init-reference.md` | Coordinator | Procedures run at every session start | +| `spawn-reference.md` | Coordinator | Full agent spawn template and Ghost Protocol | +| `worktree-reference.md` | Coordinator | Worktree strategies, lifecycle, and pre-spawn setup | + +### Agent bootstrap templates +Used **once** by `squad init` or when `squad upgrade` / coordinator code creates a new agent. +After the agent's own files are seeded, these templates are not read again at runtime. + +| File | Used to seed | +|------|-------------| +| `charter.md` | New agent `charter.md` when a team member is added | +| `copilot-instructions.md` | `.github/copilot-instructions.md` for the repo | +| `fact-checker-charter.md` | `agents/fact-checker/charter.md` | +| `fact-checker-policy.md` | `agents/fact-checker/policy.md` (Fact Checker methodology) | +| `history.md` | New agent `history.md` when a team member is added | +| `rai-charter.md` | `agents/Rai/charter.md` | +| `rai-policy.md` | `agents/Rai/policy.md` (RAI check taxonomy) | +| `roster.md` | Roster entry format guidance for `team.md` | +| `run-output.md` | Standard run output format for agent responses | +| `scribe-charter.md` | `agents/scribe/charter.md` | +| `skill.md` | Skeleton for new skill files under `.github/skills/` | + +--- + +## Invariant + +Nothing should be added to `.squad/templates/` without also being registered in the CLI's +`TEMPLATE_MANIFEST` (`packages/squad-cli/src/cli/core/templates.ts`) as **either**: + +1. A **runtime input** (coordinator reads it by path) — include the reader and situation in + the on-demand table above. +2. A **bootstrap template** (used once to seed a generated file) — include the target in the + bootstrap table above. + +If a file in this directory is neither, it is a stale copy and safe to remove. See #1436 for +the cleanup tracker. + +--- + +## Historical note — `workflows/` and `skills/` subtrees + +Earlier Squad versions copied `.github/workflows/` and `.github/skills/` content into +`.squad/templates/workflows/` and `.squad/templates/skills/` as well. Those copies were never +read at runtime — they were stale duplicates. The `TEMPLATE_MANIFEST` now routes workflows +directly to `.github/workflows/` and skills directly to `.github/skills/`. If your project +still has these subdirectories under `.squad/templates/`, they are safe to delete. See #1436. diff --git a/templates/README.md b/templates/README.md new file mode 100644 index 000000000..310f686f2 --- /dev/null +++ b/templates/README.md @@ -0,0 +1,82 @@ +# `.squad/templates/` — What Lives Here and Why + +This directory is **read at runtime** by the Squad coordinator and agents. Do not delete files +from it — doing so breaks coordinator behavior that depends on lazy-loading these references. + +If you want to customize coordinator behavior, edit the relevant file here. On `squad upgrade`, +files marked squad-owned are overwritten; user-customizable overrides are preserved. + +--- + +## File Categories + +### Coordinator on-demand references +Loaded lazily by the coordinator when a matching situation arises (e.g. when running a +ceremony, spawning with worktree isolation, or building the session init checklist). The +coordinator's system prompt says "On-demand reference: Read `.squad/templates/`" for each +of these — they are NOT loaded on every turn. + +| File | Read by | Situation | +|------|---------|-----------| +| `after-agent-reference.md` | Coordinator | Collecting results after agent work | +| `casting-reference.md` | Coordinator | Init Mode or adding/recasting team members | +| `ceremony-reference.md` | Coordinator | Running team ceremonies | +| `client-compatibility-reference.md` | Coordinator | CLI / VS Code / App platform differences | +| `constraint-tracking.md` | Coordinator | Tracking budget constraints in a session | +| `copilot-agent.md` | Coordinator | Adding @copilot as a team member | +| `human-members.md` | Coordinator | Adding a human to the team roster | +| `issue-lifecycle.md` | Coordinator | GitHub Issues Mode — issue → PR → merge flow | +| `mcp-config.md` | Coordinator | MCP server integration details | +| `model-selection-reference.md` | Coordinator | Per-agent model and reasoning-effort selection | +| `multi-agent-format.md` | Coordinator | Assembling multi-agent artifact output | +| `orchestration-log.md` | Scribe | Writing per-agent orchestration log entries | +| `plugin-marketplace.md` | Coordinator | Plugin marketplace discovery and install flow | +| `prd-intake.md` | Coordinator | PRD Mode — ingesting a spec for decomposition | +| `ralph-reference.md` | Coordinator | Ralph work-monitor lifecycle and board format | +| `raw-agent-output.md` | Coordinator | Raw agent output appendix format | +| `session-init-reference.md` | Coordinator | Procedures run at every session start | +| `spawn-reference.md` | Coordinator | Full agent spawn template and Ghost Protocol | +| `worktree-reference.md` | Coordinator | Worktree strategies, lifecycle, and pre-spawn setup | + +### Agent bootstrap templates +Used **once** by `squad init` or when `squad upgrade` / coordinator code creates a new agent. +After the agent's own files are seeded, these templates are not read again at runtime. + +| File | Used to seed | +|------|-------------| +| `charter.md` | New agent `charter.md` when a team member is added | +| `copilot-instructions.md` | `.github/copilot-instructions.md` for the repo | +| `fact-checker-charter.md` | `agents/fact-checker/charter.md` | +| `fact-checker-policy.md` | `agents/fact-checker/policy.md` (Fact Checker methodology) | +| `history.md` | New agent `history.md` when a team member is added | +| `rai-charter.md` | `agents/Rai/charter.md` | +| `rai-policy.md` | `agents/Rai/policy.md` (RAI check taxonomy) | +| `roster.md` | Roster entry format guidance for `team.md` | +| `run-output.md` | Standard run output format for agent responses | +| `scribe-charter.md` | `agents/scribe/charter.md` | +| `skill.md` | Skeleton for new skill files under `.github/skills/` | + +--- + +## Invariant + +Nothing should be added to `.squad/templates/` without also being registered in the CLI's +`TEMPLATE_MANIFEST` (`packages/squad-cli/src/cli/core/templates.ts`) as **either**: + +1. A **runtime input** (coordinator reads it by path) — include the reader and situation in + the on-demand table above. +2. A **bootstrap template** (used once to seed a generated file) — include the target in the + bootstrap table above. + +If a file in this directory is neither, it is a stale copy and safe to remove. See #1436 for +the cleanup tracker. + +--- + +## Historical note — `workflows/` and `skills/` subtrees + +Earlier Squad versions copied `.github/workflows/` and `.github/skills/` content into +`.squad/templates/workflows/` and `.squad/templates/skills/` as well. Those copies were never +read at runtime — they were stale duplicates. The `TEMPLATE_MANIFEST` now routes workflows +directly to `.github/workflows/` and skills directly to `.github/skills/`. If your project +still has these subdirectories under `.squad/templates/`, they are safe to delete. See #1436. diff --git a/test/template-routing.test.ts b/test/template-routing.test.ts index d51affdf8..092dfceca 100644 --- a/test/template-routing.test.ts +++ b/test/template-routing.test.ts @@ -61,6 +61,7 @@ describe('TEMPLATE_MANIFEST routing (iter-5: no doc dumping into .squad/ root)', 'Rai-charter.md': 'templates/Rai-charter.md', 'fact-checker-charter.md': 'templates/fact-checker-charter.md', 'rai-policy.md': 'templates/rai-policy.md', + 'README.md': 'templates/README.md', }; for (const [source, dest] of Object.entries(expected)) { From 3a8905399797bcf8b931188b48794f64ebfdaadc Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Tue, 1 Sep 2026 08:58:38 -0700 Subject: [PATCH 3/6] docs(templates): document all .squad/templates subtrees Copilot review flagged that the README omitted every subtree that ships under .squad/templates/, while the Invariant said anything unlisted is "a stale copy and safe to remove". Verified the risk is real: - squad init copies this directory recursively (copyRecursiveSync, init.ts:1481), so casting/, identity/, scripts/, skills/ and workflows/ all ship into every new project. - .squad/templates/casting/ is read at runtime by Init Mode to allocate custom-universe names, so deleting it breaks casting. - .squad/templates/scripts/ and workflows/ are documented copy-sources in shipped docs (state-backends, ci-cd-integration). Add a Subtrees table classifying all five, scope the Invariant to top-level files so absence from the two tables no longer implies a subtree is stale, and correct the historical note: it told users the workflows/ and skills/ subtrees were "safe to delete", which contradicts the docs that instruct copying from workflows/ and would delete the source the manifest installs skills from. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 0515ad5d-4c5b-48bb-92a6-4e1296594cab --- .squad-templates/README.md | 39 +++++++++++++++++++------- .squad/templates/README.md | 39 +++++++++++++++++++------- packages/squad-cli/templates/README.md | 39 +++++++++++++++++++------- packages/squad-sdk/templates/README.md | 39 +++++++++++++++++++------- templates/README.md | 39 +++++++++++++++++++------- 5 files changed, 145 insertions(+), 50 deletions(-) diff --git a/.squad-templates/README.md b/.squad-templates/README.md index 310f686f2..d6b857fe4 100644 --- a/.squad-templates/README.md +++ b/.squad-templates/README.md @@ -56,27 +56,46 @@ After the agent's own files are seeded, these templates are not read again at ru | `scribe-charter.md` | `agents/scribe/charter.md` | | `skill.md` | Skeleton for new skill files under `.github/skills/` | +### Subtrees + +`squad init` copies this directory **recursively**, so every subtree below ships into +`.squad/templates/` in a new project. None of them are stale, and none should be deleted +wholesale — each has a distinct consumer. + +| Subtree | Kind | Consumer | +|---------|------|----------| +| `casting/` | Runtime input | Init Mode reads this **directory** to allocate character names for a custom universe (`.copilot/skills/init-mode/SKILL.md`). Deleting it breaks custom-universe casting. | +| `identity/` | Bootstrap template | Seeds `.squad/identity/now.md` and `wisdom.md`. Registered in `TEMPLATE_MANIFEST` under `identity/`. | +| `scripts/` | User copy-source | Documented for users to copy from — `cp -r .squad/templates/scripts/notes/ scripts/notes/` (see the state-backends doc). | +| `skills/` | Bootstrap template | Source for skills the `TEMPLATE_MANIFEST` installs **to `.github/skills/`** (destinations are `../.github/skills/...`). The installed copy under `.github/skills/` is what agents load. | +| `workflows/` | User copy-source | Documented for users to copy from — `cp .squad/templates/workflows/*.yml .github/workflows/` (see the CI/CD integration doc). | + --- ## Invariant -Nothing should be added to `.squad/templates/` without also being registered in the CLI's -`TEMPLATE_MANIFEST` (`packages/squad-cli/src/cli/core/templates.ts`) as **either**: +Nothing should be added to the **top level** of `.squad/templates/` without also being +registered in the CLI's `TEMPLATE_MANIFEST` (`packages/squad-cli/src/cli/core/templates.ts`) +as **either**: 1. A **runtime input** (coordinator reads it by path) — include the reader and situation in the on-demand table above. 2. A **bootstrap template** (used once to seed a generated file) — include the target in the bootstrap table above. -If a file in this directory is neither, it is a stale copy and safe to remove. See #1436 for -the cleanup tracker. +If a **top-level file** is neither, it is a stale copy and safe to remove. See #1436 for the +cleanup tracker. + +This rule does **not** extend to the subtrees above: each is accounted for in the subtree +table, and absence from the two top-level tables does not make a subtree stale. New subtrees +must be added to the subtree table. --- -## Historical note — `workflows/` and `skills/` subtrees +## Historical note — `skills/` subtree -Earlier Squad versions copied `.github/workflows/` and `.github/skills/` content into -`.squad/templates/workflows/` and `.squad/templates/skills/` as well. Those copies were never -read at runtime — they were stale duplicates. The `TEMPLATE_MANIFEST` now routes workflows -directly to `.github/workflows/` and skills directly to `.github/skills/`. If your project -still has these subdirectories under `.squad/templates/`, they are safe to delete. See #1436. +Earlier Squad versions copied `.github/skills/` content into `.squad/templates/skills/` and +agents were expected to load it from there. That is no longer how it works: the +`TEMPLATE_MANIFEST` installs skills **to `.github/skills/`**, and that installed copy is the +one agents load. The `skills/` subtree here remains the *source* for that install, so it must +not be deleted from this directory. See #1436. diff --git a/.squad/templates/README.md b/.squad/templates/README.md index 310f686f2..d6b857fe4 100644 --- a/.squad/templates/README.md +++ b/.squad/templates/README.md @@ -56,27 +56,46 @@ After the agent's own files are seeded, these templates are not read again at ru | `scribe-charter.md` | `agents/scribe/charter.md` | | `skill.md` | Skeleton for new skill files under `.github/skills/` | +### Subtrees + +`squad init` copies this directory **recursively**, so every subtree below ships into +`.squad/templates/` in a new project. None of them are stale, and none should be deleted +wholesale — each has a distinct consumer. + +| Subtree | Kind | Consumer | +|---------|------|----------| +| `casting/` | Runtime input | Init Mode reads this **directory** to allocate character names for a custom universe (`.copilot/skills/init-mode/SKILL.md`). Deleting it breaks custom-universe casting. | +| `identity/` | Bootstrap template | Seeds `.squad/identity/now.md` and `wisdom.md`. Registered in `TEMPLATE_MANIFEST` under `identity/`. | +| `scripts/` | User copy-source | Documented for users to copy from — `cp -r .squad/templates/scripts/notes/ scripts/notes/` (see the state-backends doc). | +| `skills/` | Bootstrap template | Source for skills the `TEMPLATE_MANIFEST` installs **to `.github/skills/`** (destinations are `../.github/skills/...`). The installed copy under `.github/skills/` is what agents load. | +| `workflows/` | User copy-source | Documented for users to copy from — `cp .squad/templates/workflows/*.yml .github/workflows/` (see the CI/CD integration doc). | + --- ## Invariant -Nothing should be added to `.squad/templates/` without also being registered in the CLI's -`TEMPLATE_MANIFEST` (`packages/squad-cli/src/cli/core/templates.ts`) as **either**: +Nothing should be added to the **top level** of `.squad/templates/` without also being +registered in the CLI's `TEMPLATE_MANIFEST` (`packages/squad-cli/src/cli/core/templates.ts`) +as **either**: 1. A **runtime input** (coordinator reads it by path) — include the reader and situation in the on-demand table above. 2. A **bootstrap template** (used once to seed a generated file) — include the target in the bootstrap table above. -If a file in this directory is neither, it is a stale copy and safe to remove. See #1436 for -the cleanup tracker. +If a **top-level file** is neither, it is a stale copy and safe to remove. See #1436 for the +cleanup tracker. + +This rule does **not** extend to the subtrees above: each is accounted for in the subtree +table, and absence from the two top-level tables does not make a subtree stale. New subtrees +must be added to the subtree table. --- -## Historical note — `workflows/` and `skills/` subtrees +## Historical note — `skills/` subtree -Earlier Squad versions copied `.github/workflows/` and `.github/skills/` content into -`.squad/templates/workflows/` and `.squad/templates/skills/` as well. Those copies were never -read at runtime — they were stale duplicates. The `TEMPLATE_MANIFEST` now routes workflows -directly to `.github/workflows/` and skills directly to `.github/skills/`. If your project -still has these subdirectories under `.squad/templates/`, they are safe to delete. See #1436. +Earlier Squad versions copied `.github/skills/` content into `.squad/templates/skills/` and +agents were expected to load it from there. That is no longer how it works: the +`TEMPLATE_MANIFEST` installs skills **to `.github/skills/`**, and that installed copy is the +one agents load. The `skills/` subtree here remains the *source* for that install, so it must +not be deleted from this directory. See #1436. diff --git a/packages/squad-cli/templates/README.md b/packages/squad-cli/templates/README.md index 310f686f2..d6b857fe4 100644 --- a/packages/squad-cli/templates/README.md +++ b/packages/squad-cli/templates/README.md @@ -56,27 +56,46 @@ After the agent's own files are seeded, these templates are not read again at ru | `scribe-charter.md` | `agents/scribe/charter.md` | | `skill.md` | Skeleton for new skill files under `.github/skills/` | +### Subtrees + +`squad init` copies this directory **recursively**, so every subtree below ships into +`.squad/templates/` in a new project. None of them are stale, and none should be deleted +wholesale — each has a distinct consumer. + +| Subtree | Kind | Consumer | +|---------|------|----------| +| `casting/` | Runtime input | Init Mode reads this **directory** to allocate character names for a custom universe (`.copilot/skills/init-mode/SKILL.md`). Deleting it breaks custom-universe casting. | +| `identity/` | Bootstrap template | Seeds `.squad/identity/now.md` and `wisdom.md`. Registered in `TEMPLATE_MANIFEST` under `identity/`. | +| `scripts/` | User copy-source | Documented for users to copy from — `cp -r .squad/templates/scripts/notes/ scripts/notes/` (see the state-backends doc). | +| `skills/` | Bootstrap template | Source for skills the `TEMPLATE_MANIFEST` installs **to `.github/skills/`** (destinations are `../.github/skills/...`). The installed copy under `.github/skills/` is what agents load. | +| `workflows/` | User copy-source | Documented for users to copy from — `cp .squad/templates/workflows/*.yml .github/workflows/` (see the CI/CD integration doc). | + --- ## Invariant -Nothing should be added to `.squad/templates/` without also being registered in the CLI's -`TEMPLATE_MANIFEST` (`packages/squad-cli/src/cli/core/templates.ts`) as **either**: +Nothing should be added to the **top level** of `.squad/templates/` without also being +registered in the CLI's `TEMPLATE_MANIFEST` (`packages/squad-cli/src/cli/core/templates.ts`) +as **either**: 1. A **runtime input** (coordinator reads it by path) — include the reader and situation in the on-demand table above. 2. A **bootstrap template** (used once to seed a generated file) — include the target in the bootstrap table above. -If a file in this directory is neither, it is a stale copy and safe to remove. See #1436 for -the cleanup tracker. +If a **top-level file** is neither, it is a stale copy and safe to remove. See #1436 for the +cleanup tracker. + +This rule does **not** extend to the subtrees above: each is accounted for in the subtree +table, and absence from the two top-level tables does not make a subtree stale. New subtrees +must be added to the subtree table. --- -## Historical note — `workflows/` and `skills/` subtrees +## Historical note — `skills/` subtree -Earlier Squad versions copied `.github/workflows/` and `.github/skills/` content into -`.squad/templates/workflows/` and `.squad/templates/skills/` as well. Those copies were never -read at runtime — they were stale duplicates. The `TEMPLATE_MANIFEST` now routes workflows -directly to `.github/workflows/` and skills directly to `.github/skills/`. If your project -still has these subdirectories under `.squad/templates/`, they are safe to delete. See #1436. +Earlier Squad versions copied `.github/skills/` content into `.squad/templates/skills/` and +agents were expected to load it from there. That is no longer how it works: the +`TEMPLATE_MANIFEST` installs skills **to `.github/skills/`**, and that installed copy is the +one agents load. The `skills/` subtree here remains the *source* for that install, so it must +not be deleted from this directory. See #1436. diff --git a/packages/squad-sdk/templates/README.md b/packages/squad-sdk/templates/README.md index 310f686f2..d6b857fe4 100644 --- a/packages/squad-sdk/templates/README.md +++ b/packages/squad-sdk/templates/README.md @@ -56,27 +56,46 @@ After the agent's own files are seeded, these templates are not read again at ru | `scribe-charter.md` | `agents/scribe/charter.md` | | `skill.md` | Skeleton for new skill files under `.github/skills/` | +### Subtrees + +`squad init` copies this directory **recursively**, so every subtree below ships into +`.squad/templates/` in a new project. None of them are stale, and none should be deleted +wholesale — each has a distinct consumer. + +| Subtree | Kind | Consumer | +|---------|------|----------| +| `casting/` | Runtime input | Init Mode reads this **directory** to allocate character names for a custom universe (`.copilot/skills/init-mode/SKILL.md`). Deleting it breaks custom-universe casting. | +| `identity/` | Bootstrap template | Seeds `.squad/identity/now.md` and `wisdom.md`. Registered in `TEMPLATE_MANIFEST` under `identity/`. | +| `scripts/` | User copy-source | Documented for users to copy from — `cp -r .squad/templates/scripts/notes/ scripts/notes/` (see the state-backends doc). | +| `skills/` | Bootstrap template | Source for skills the `TEMPLATE_MANIFEST` installs **to `.github/skills/`** (destinations are `../.github/skills/...`). The installed copy under `.github/skills/` is what agents load. | +| `workflows/` | User copy-source | Documented for users to copy from — `cp .squad/templates/workflows/*.yml .github/workflows/` (see the CI/CD integration doc). | + --- ## Invariant -Nothing should be added to `.squad/templates/` without also being registered in the CLI's -`TEMPLATE_MANIFEST` (`packages/squad-cli/src/cli/core/templates.ts`) as **either**: +Nothing should be added to the **top level** of `.squad/templates/` without also being +registered in the CLI's `TEMPLATE_MANIFEST` (`packages/squad-cli/src/cli/core/templates.ts`) +as **either**: 1. A **runtime input** (coordinator reads it by path) — include the reader and situation in the on-demand table above. 2. A **bootstrap template** (used once to seed a generated file) — include the target in the bootstrap table above. -If a file in this directory is neither, it is a stale copy and safe to remove. See #1436 for -the cleanup tracker. +If a **top-level file** is neither, it is a stale copy and safe to remove. See #1436 for the +cleanup tracker. + +This rule does **not** extend to the subtrees above: each is accounted for in the subtree +table, and absence from the two top-level tables does not make a subtree stale. New subtrees +must be added to the subtree table. --- -## Historical note — `workflows/` and `skills/` subtrees +## Historical note — `skills/` subtree -Earlier Squad versions copied `.github/workflows/` and `.github/skills/` content into -`.squad/templates/workflows/` and `.squad/templates/skills/` as well. Those copies were never -read at runtime — they were stale duplicates. The `TEMPLATE_MANIFEST` now routes workflows -directly to `.github/workflows/` and skills directly to `.github/skills/`. If your project -still has these subdirectories under `.squad/templates/`, they are safe to delete. See #1436. +Earlier Squad versions copied `.github/skills/` content into `.squad/templates/skills/` and +agents were expected to load it from there. That is no longer how it works: the +`TEMPLATE_MANIFEST` installs skills **to `.github/skills/`**, and that installed copy is the +one agents load. The `skills/` subtree here remains the *source* for that install, so it must +not be deleted from this directory. See #1436. diff --git a/templates/README.md b/templates/README.md index 310f686f2..d6b857fe4 100644 --- a/templates/README.md +++ b/templates/README.md @@ -56,27 +56,46 @@ After the agent's own files are seeded, these templates are not read again at ru | `scribe-charter.md` | `agents/scribe/charter.md` | | `skill.md` | Skeleton for new skill files under `.github/skills/` | +### Subtrees + +`squad init` copies this directory **recursively**, so every subtree below ships into +`.squad/templates/` in a new project. None of them are stale, and none should be deleted +wholesale — each has a distinct consumer. + +| Subtree | Kind | Consumer | +|---------|------|----------| +| `casting/` | Runtime input | Init Mode reads this **directory** to allocate character names for a custom universe (`.copilot/skills/init-mode/SKILL.md`). Deleting it breaks custom-universe casting. | +| `identity/` | Bootstrap template | Seeds `.squad/identity/now.md` and `wisdom.md`. Registered in `TEMPLATE_MANIFEST` under `identity/`. | +| `scripts/` | User copy-source | Documented for users to copy from — `cp -r .squad/templates/scripts/notes/ scripts/notes/` (see the state-backends doc). | +| `skills/` | Bootstrap template | Source for skills the `TEMPLATE_MANIFEST` installs **to `.github/skills/`** (destinations are `../.github/skills/...`). The installed copy under `.github/skills/` is what agents load. | +| `workflows/` | User copy-source | Documented for users to copy from — `cp .squad/templates/workflows/*.yml .github/workflows/` (see the CI/CD integration doc). | + --- ## Invariant -Nothing should be added to `.squad/templates/` without also being registered in the CLI's -`TEMPLATE_MANIFEST` (`packages/squad-cli/src/cli/core/templates.ts`) as **either**: +Nothing should be added to the **top level** of `.squad/templates/` without also being +registered in the CLI's `TEMPLATE_MANIFEST` (`packages/squad-cli/src/cli/core/templates.ts`) +as **either**: 1. A **runtime input** (coordinator reads it by path) — include the reader and situation in the on-demand table above. 2. A **bootstrap template** (used once to seed a generated file) — include the target in the bootstrap table above. -If a file in this directory is neither, it is a stale copy and safe to remove. See #1436 for -the cleanup tracker. +If a **top-level file** is neither, it is a stale copy and safe to remove. See #1436 for the +cleanup tracker. + +This rule does **not** extend to the subtrees above: each is accounted for in the subtree +table, and absence from the two top-level tables does not make a subtree stale. New subtrees +must be added to the subtree table. --- -## Historical note — `workflows/` and `skills/` subtrees +## Historical note — `skills/` subtree -Earlier Squad versions copied `.github/workflows/` and `.github/skills/` content into -`.squad/templates/workflows/` and `.squad/templates/skills/` as well. Those copies were never -read at runtime — they were stale duplicates. The `TEMPLATE_MANIFEST` now routes workflows -directly to `.github/workflows/` and skills directly to `.github/skills/`. If your project -still has these subdirectories under `.squad/templates/`, they are safe to delete. See #1436. +Earlier Squad versions copied `.github/skills/` content into `.squad/templates/skills/` and +agents were expected to load it from there. That is no longer how it works: the +`TEMPLATE_MANIFEST` installs skills **to `.github/skills/`**, and that installed copy is the +one agents load. The `skills/` subtree here remains the *source* for that install, so it must +not be deleted from this directory. See #1436. From a182d59039898b206d0dc2f24286e52de6af9cdc Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Tue, 1 Sep 2026 09:15:34 -0700 Subject: [PATCH 4/6] docs(templates): make the Invariant fail safe for unclassified files Second round of Copilot review found my subtree fix was incomplete: the same "not in a table => stale and safe to remove" hazard still applied to top-level files. Audited every top-level file against both tables and TEMPLATE_MANIFEST. Ten are in neither table and unregistered -- including notes-protocol.md, which the state-backends doc tells users to copy into .squad/. The tables are not a complete inventory, so "safe to remove" was an unsafe default. - Absence from the tables now means unclassified, not stale; removal requires positive evidence nothing reads or copies the file. - notes-protocol.md named explicitly as the worked example. - Registration is stated as expected for new files rather than as a property all current files have, which they do not. Also corrected the casting/ row: it cited .copilot/skills/init-mode, a legacy path users do not get after squad init. No shipped template references the casting/ directory, so the row now describes the data and points at casting-reference.md instead of a path that would mislead. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 0515ad5d-4c5b-48bb-92a6-4e1296594cab --- .squad-templates/README.md | 18 ++++++++++++------ .squad/templates/README.md | 18 ++++++++++++------ packages/squad-cli/templates/README.md | 18 ++++++++++++------ packages/squad-sdk/templates/README.md | 18 ++++++++++++------ templates/README.md | 18 ++++++++++++------ 5 files changed, 60 insertions(+), 30 deletions(-) diff --git a/.squad-templates/README.md b/.squad-templates/README.md index d6b857fe4..587c1ef1e 100644 --- a/.squad-templates/README.md +++ b/.squad-templates/README.md @@ -64,7 +64,7 @@ wholesale — each has a distinct consumer. | Subtree | Kind | Consumer | |---------|------|----------| -| `casting/` | Runtime input | Init Mode reads this **directory** to allocate character names for a custom universe (`.copilot/skills/init-mode/SKILL.md`). Deleting it breaks custom-universe casting. | +| `casting/` | Runtime input | Custom-universe character lists, read during Init Mode casting when a user names a universe that has no built-in list. See `casting-reference.md` for the casting algorithm. Deleting it removes those name pools. | | `identity/` | Bootstrap template | Seeds `.squad/identity/now.md` and `wisdom.md`. Registered in `TEMPLATE_MANIFEST` under `identity/`. | | `scripts/` | User copy-source | Documented for users to copy from — `cp -r .squad/templates/scripts/notes/ scripts/notes/` (see the state-backends doc). | | `skills/` | Bootstrap template | Source for skills the `TEMPLATE_MANIFEST` installs **to `.github/skills/`** (destinations are `../.github/skills/...`). The installed copy under `.github/skills/` is what agents load. | @@ -74,17 +74,23 @@ wholesale — each has a distinct consumer. ## Invariant -Nothing should be added to the **top level** of `.squad/templates/` without also being -registered in the CLI's `TEMPLATE_MANIFEST` (`packages/squad-cli/src/cli/core/templates.ts`) -as **either**: +Anything added to the **top level** of `.squad/templates/` should be classified as **either**: 1. A **runtime input** (coordinator reads it by path) — include the reader and situation in the on-demand table above. 2. A **bootstrap template** (used once to seed a generated file) — include the target in the bootstrap table above. -If a **top-level file** is neither, it is a stale copy and safe to remove. See #1436 for the -cleanup tracker. +New top-level files should also be registered in the CLI's `TEMPLATE_MANIFEST` +(`packages/squad-cli/src/cli/core/templates.ts`) so `squad upgrade` can maintain them. + +**Absence from these tables means unclassified, not stale.** Do not treat it as license to +delete. The tables above are not yet a complete inventory of what ships here, and several +top-level files are consumed in ways neither table records — `notes-protocol.md`, for +example, is not in either table and is not manifest-registered, yet the state-backends doc +tells users to `cp .squad/templates/notes-protocol.md .squad/notes-protocol.md`. Removing a +file requires positive evidence that nothing reads or copies it; classify first, and only +then remove. See #1436 for the cleanup tracker. This rule does **not** extend to the subtrees above: each is accounted for in the subtree table, and absence from the two top-level tables does not make a subtree stale. New subtrees diff --git a/.squad/templates/README.md b/.squad/templates/README.md index d6b857fe4..587c1ef1e 100644 --- a/.squad/templates/README.md +++ b/.squad/templates/README.md @@ -64,7 +64,7 @@ wholesale — each has a distinct consumer. | Subtree | Kind | Consumer | |---------|------|----------| -| `casting/` | Runtime input | Init Mode reads this **directory** to allocate character names for a custom universe (`.copilot/skills/init-mode/SKILL.md`). Deleting it breaks custom-universe casting. | +| `casting/` | Runtime input | Custom-universe character lists, read during Init Mode casting when a user names a universe that has no built-in list. See `casting-reference.md` for the casting algorithm. Deleting it removes those name pools. | | `identity/` | Bootstrap template | Seeds `.squad/identity/now.md` and `wisdom.md`. Registered in `TEMPLATE_MANIFEST` under `identity/`. | | `scripts/` | User copy-source | Documented for users to copy from — `cp -r .squad/templates/scripts/notes/ scripts/notes/` (see the state-backends doc). | | `skills/` | Bootstrap template | Source for skills the `TEMPLATE_MANIFEST` installs **to `.github/skills/`** (destinations are `../.github/skills/...`). The installed copy under `.github/skills/` is what agents load. | @@ -74,17 +74,23 @@ wholesale — each has a distinct consumer. ## Invariant -Nothing should be added to the **top level** of `.squad/templates/` without also being -registered in the CLI's `TEMPLATE_MANIFEST` (`packages/squad-cli/src/cli/core/templates.ts`) -as **either**: +Anything added to the **top level** of `.squad/templates/` should be classified as **either**: 1. A **runtime input** (coordinator reads it by path) — include the reader and situation in the on-demand table above. 2. A **bootstrap template** (used once to seed a generated file) — include the target in the bootstrap table above. -If a **top-level file** is neither, it is a stale copy and safe to remove. See #1436 for the -cleanup tracker. +New top-level files should also be registered in the CLI's `TEMPLATE_MANIFEST` +(`packages/squad-cli/src/cli/core/templates.ts`) so `squad upgrade` can maintain them. + +**Absence from these tables means unclassified, not stale.** Do not treat it as license to +delete. The tables above are not yet a complete inventory of what ships here, and several +top-level files are consumed in ways neither table records — `notes-protocol.md`, for +example, is not in either table and is not manifest-registered, yet the state-backends doc +tells users to `cp .squad/templates/notes-protocol.md .squad/notes-protocol.md`. Removing a +file requires positive evidence that nothing reads or copies it; classify first, and only +then remove. See #1436 for the cleanup tracker. This rule does **not** extend to the subtrees above: each is accounted for in the subtree table, and absence from the two top-level tables does not make a subtree stale. New subtrees diff --git a/packages/squad-cli/templates/README.md b/packages/squad-cli/templates/README.md index d6b857fe4..587c1ef1e 100644 --- a/packages/squad-cli/templates/README.md +++ b/packages/squad-cli/templates/README.md @@ -64,7 +64,7 @@ wholesale — each has a distinct consumer. | Subtree | Kind | Consumer | |---------|------|----------| -| `casting/` | Runtime input | Init Mode reads this **directory** to allocate character names for a custom universe (`.copilot/skills/init-mode/SKILL.md`). Deleting it breaks custom-universe casting. | +| `casting/` | Runtime input | Custom-universe character lists, read during Init Mode casting when a user names a universe that has no built-in list. See `casting-reference.md` for the casting algorithm. Deleting it removes those name pools. | | `identity/` | Bootstrap template | Seeds `.squad/identity/now.md` and `wisdom.md`. Registered in `TEMPLATE_MANIFEST` under `identity/`. | | `scripts/` | User copy-source | Documented for users to copy from — `cp -r .squad/templates/scripts/notes/ scripts/notes/` (see the state-backends doc). | | `skills/` | Bootstrap template | Source for skills the `TEMPLATE_MANIFEST` installs **to `.github/skills/`** (destinations are `../.github/skills/...`). The installed copy under `.github/skills/` is what agents load. | @@ -74,17 +74,23 @@ wholesale — each has a distinct consumer. ## Invariant -Nothing should be added to the **top level** of `.squad/templates/` without also being -registered in the CLI's `TEMPLATE_MANIFEST` (`packages/squad-cli/src/cli/core/templates.ts`) -as **either**: +Anything added to the **top level** of `.squad/templates/` should be classified as **either**: 1. A **runtime input** (coordinator reads it by path) — include the reader and situation in the on-demand table above. 2. A **bootstrap template** (used once to seed a generated file) — include the target in the bootstrap table above. -If a **top-level file** is neither, it is a stale copy and safe to remove. See #1436 for the -cleanup tracker. +New top-level files should also be registered in the CLI's `TEMPLATE_MANIFEST` +(`packages/squad-cli/src/cli/core/templates.ts`) so `squad upgrade` can maintain them. + +**Absence from these tables means unclassified, not stale.** Do not treat it as license to +delete. The tables above are not yet a complete inventory of what ships here, and several +top-level files are consumed in ways neither table records — `notes-protocol.md`, for +example, is not in either table and is not manifest-registered, yet the state-backends doc +tells users to `cp .squad/templates/notes-protocol.md .squad/notes-protocol.md`. Removing a +file requires positive evidence that nothing reads or copies it; classify first, and only +then remove. See #1436 for the cleanup tracker. This rule does **not** extend to the subtrees above: each is accounted for in the subtree table, and absence from the two top-level tables does not make a subtree stale. New subtrees diff --git a/packages/squad-sdk/templates/README.md b/packages/squad-sdk/templates/README.md index d6b857fe4..587c1ef1e 100644 --- a/packages/squad-sdk/templates/README.md +++ b/packages/squad-sdk/templates/README.md @@ -64,7 +64,7 @@ wholesale — each has a distinct consumer. | Subtree | Kind | Consumer | |---------|------|----------| -| `casting/` | Runtime input | Init Mode reads this **directory** to allocate character names for a custom universe (`.copilot/skills/init-mode/SKILL.md`). Deleting it breaks custom-universe casting. | +| `casting/` | Runtime input | Custom-universe character lists, read during Init Mode casting when a user names a universe that has no built-in list. See `casting-reference.md` for the casting algorithm. Deleting it removes those name pools. | | `identity/` | Bootstrap template | Seeds `.squad/identity/now.md` and `wisdom.md`. Registered in `TEMPLATE_MANIFEST` under `identity/`. | | `scripts/` | User copy-source | Documented for users to copy from — `cp -r .squad/templates/scripts/notes/ scripts/notes/` (see the state-backends doc). | | `skills/` | Bootstrap template | Source for skills the `TEMPLATE_MANIFEST` installs **to `.github/skills/`** (destinations are `../.github/skills/...`). The installed copy under `.github/skills/` is what agents load. | @@ -74,17 +74,23 @@ wholesale — each has a distinct consumer. ## Invariant -Nothing should be added to the **top level** of `.squad/templates/` without also being -registered in the CLI's `TEMPLATE_MANIFEST` (`packages/squad-cli/src/cli/core/templates.ts`) -as **either**: +Anything added to the **top level** of `.squad/templates/` should be classified as **either**: 1. A **runtime input** (coordinator reads it by path) — include the reader and situation in the on-demand table above. 2. A **bootstrap template** (used once to seed a generated file) — include the target in the bootstrap table above. -If a **top-level file** is neither, it is a stale copy and safe to remove. See #1436 for the -cleanup tracker. +New top-level files should also be registered in the CLI's `TEMPLATE_MANIFEST` +(`packages/squad-cli/src/cli/core/templates.ts`) so `squad upgrade` can maintain them. + +**Absence from these tables means unclassified, not stale.** Do not treat it as license to +delete. The tables above are not yet a complete inventory of what ships here, and several +top-level files are consumed in ways neither table records — `notes-protocol.md`, for +example, is not in either table and is not manifest-registered, yet the state-backends doc +tells users to `cp .squad/templates/notes-protocol.md .squad/notes-protocol.md`. Removing a +file requires positive evidence that nothing reads or copies it; classify first, and only +then remove. See #1436 for the cleanup tracker. This rule does **not** extend to the subtrees above: each is accounted for in the subtree table, and absence from the two top-level tables does not make a subtree stale. New subtrees diff --git a/templates/README.md b/templates/README.md index d6b857fe4..587c1ef1e 100644 --- a/templates/README.md +++ b/templates/README.md @@ -64,7 +64,7 @@ wholesale — each has a distinct consumer. | Subtree | Kind | Consumer | |---------|------|----------| -| `casting/` | Runtime input | Init Mode reads this **directory** to allocate character names for a custom universe (`.copilot/skills/init-mode/SKILL.md`). Deleting it breaks custom-universe casting. | +| `casting/` | Runtime input | Custom-universe character lists, read during Init Mode casting when a user names a universe that has no built-in list. See `casting-reference.md` for the casting algorithm. Deleting it removes those name pools. | | `identity/` | Bootstrap template | Seeds `.squad/identity/now.md` and `wisdom.md`. Registered in `TEMPLATE_MANIFEST` under `identity/`. | | `scripts/` | User copy-source | Documented for users to copy from — `cp -r .squad/templates/scripts/notes/ scripts/notes/` (see the state-backends doc). | | `skills/` | Bootstrap template | Source for skills the `TEMPLATE_MANIFEST` installs **to `.github/skills/`** (destinations are `../.github/skills/...`). The installed copy under `.github/skills/` is what agents load. | @@ -74,17 +74,23 @@ wholesale — each has a distinct consumer. ## Invariant -Nothing should be added to the **top level** of `.squad/templates/` without also being -registered in the CLI's `TEMPLATE_MANIFEST` (`packages/squad-cli/src/cli/core/templates.ts`) -as **either**: +Anything added to the **top level** of `.squad/templates/` should be classified as **either**: 1. A **runtime input** (coordinator reads it by path) — include the reader and situation in the on-demand table above. 2. A **bootstrap template** (used once to seed a generated file) — include the target in the bootstrap table above. -If a **top-level file** is neither, it is a stale copy and safe to remove. See #1436 for the -cleanup tracker. +New top-level files should also be registered in the CLI's `TEMPLATE_MANIFEST` +(`packages/squad-cli/src/cli/core/templates.ts`) so `squad upgrade` can maintain them. + +**Absence from these tables means unclassified, not stale.** Do not treat it as license to +delete. The tables above are not yet a complete inventory of what ships here, and several +top-level files are consumed in ways neither table records — `notes-protocol.md`, for +example, is not in either table and is not manifest-registered, yet the state-backends doc +tells users to `cp .squad/templates/notes-protocol.md .squad/notes-protocol.md`. Removing a +file requires positive evidence that nothing reads or copies it; classify first, and only +then remove. See #1436 for the cleanup tracker. This rule does **not** extend to the subtrees above: each is accounted for in the subtree table, and absence from the two top-level tables does not make a subtree stale. New subtrees From 09ec183cabcd6205f567511f3da3311d5b2a6f15 Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Tue, 1 Sep 2026 09:27:42 -0700 Subject: [PATCH 5/6] docs(templates): classify README.md, which broke its own Invariant Copilot review noted the README was the one top-level file its own rule left unaccounted for. Now that absence from the tables means "unclassified" and requires classification, that is a real self-contradiction rather than a cosmetic gap. It fits neither table -- it is not a runtime input and seeds nothing -- so it is classified explicitly instead of being forced into one: it ships as the directory's own documentation via the same recursive copy, and is manifest-registered so squad upgrade maintains it. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 0515ad5d-4c5b-48bb-92a6-4e1296594cab --- .squad-templates/README.md | 9 +++++++-- .squad/templates/README.md | 9 +++++++-- packages/squad-cli/templates/README.md | 9 +++++++-- packages/squad-sdk/templates/README.md | 9 +++++++-- templates/README.md | 9 +++++++-- 5 files changed, 35 insertions(+), 10 deletions(-) diff --git a/.squad-templates/README.md b/.squad-templates/README.md index 587c1ef1e..bc343dc0c 100644 --- a/.squad-templates/README.md +++ b/.squad-templates/README.md @@ -45,8 +45,7 @@ After the agent's own files are seeded, these templates are not read again at ru | File | Used to seed | |------|-------------| | `charter.md` | New agent `charter.md` when a team member is added | -| `copilot-instructions.md` | `.github/copilot-instructions.md` for the repo | -| `fact-checker-charter.md` | `agents/fact-checker/charter.md` | +| `copilot-instructions.md` | `.github/copilot-instructions.md` for the repo || `fact-checker-charter.md` | `agents/fact-checker/charter.md` | | `fact-checker-policy.md` | `agents/fact-checker/policy.md` (Fact Checker methodology) | | `history.md` | New agent `history.md` when a team member is added | | `rai-charter.md` | `agents/Rai/charter.md` | @@ -56,6 +55,12 @@ After the agent's own files are seeded, these templates are not read again at ru | `scribe-charter.md` | `agents/scribe/charter.md` | | `skill.md` | Skeleton for new skill files under `.github/skills/` | +`README.md` — this file — is the one top-level entry in neither table above. It is not a +runtime input and seeds nothing; it ships as this directory's own documentation, arriving in +a project through the same recursive copy, and is registered in `TEMPLATE_MANIFEST` so +`squad upgrade` keeps it current. Classified here rather than left unlisted, since the +Invariant below requires every top-level file to be accounted for. + ### Subtrees `squad init` copies this directory **recursively**, so every subtree below ships into diff --git a/.squad/templates/README.md b/.squad/templates/README.md index 587c1ef1e..bc343dc0c 100644 --- a/.squad/templates/README.md +++ b/.squad/templates/README.md @@ -45,8 +45,7 @@ After the agent's own files are seeded, these templates are not read again at ru | File | Used to seed | |------|-------------| | `charter.md` | New agent `charter.md` when a team member is added | -| `copilot-instructions.md` | `.github/copilot-instructions.md` for the repo | -| `fact-checker-charter.md` | `agents/fact-checker/charter.md` | +| `copilot-instructions.md` | `.github/copilot-instructions.md` for the repo || `fact-checker-charter.md` | `agents/fact-checker/charter.md` | | `fact-checker-policy.md` | `agents/fact-checker/policy.md` (Fact Checker methodology) | | `history.md` | New agent `history.md` when a team member is added | | `rai-charter.md` | `agents/Rai/charter.md` | @@ -56,6 +55,12 @@ After the agent's own files are seeded, these templates are not read again at ru | `scribe-charter.md` | `agents/scribe/charter.md` | | `skill.md` | Skeleton for new skill files under `.github/skills/` | +`README.md` — this file — is the one top-level entry in neither table above. It is not a +runtime input and seeds nothing; it ships as this directory's own documentation, arriving in +a project through the same recursive copy, and is registered in `TEMPLATE_MANIFEST` so +`squad upgrade` keeps it current. Classified here rather than left unlisted, since the +Invariant below requires every top-level file to be accounted for. + ### Subtrees `squad init` copies this directory **recursively**, so every subtree below ships into diff --git a/packages/squad-cli/templates/README.md b/packages/squad-cli/templates/README.md index 587c1ef1e..bc343dc0c 100644 --- a/packages/squad-cli/templates/README.md +++ b/packages/squad-cli/templates/README.md @@ -45,8 +45,7 @@ After the agent's own files are seeded, these templates are not read again at ru | File | Used to seed | |------|-------------| | `charter.md` | New agent `charter.md` when a team member is added | -| `copilot-instructions.md` | `.github/copilot-instructions.md` for the repo | -| `fact-checker-charter.md` | `agents/fact-checker/charter.md` | +| `copilot-instructions.md` | `.github/copilot-instructions.md` for the repo || `fact-checker-charter.md` | `agents/fact-checker/charter.md` | | `fact-checker-policy.md` | `agents/fact-checker/policy.md` (Fact Checker methodology) | | `history.md` | New agent `history.md` when a team member is added | | `rai-charter.md` | `agents/Rai/charter.md` | @@ -56,6 +55,12 @@ After the agent's own files are seeded, these templates are not read again at ru | `scribe-charter.md` | `agents/scribe/charter.md` | | `skill.md` | Skeleton for new skill files under `.github/skills/` | +`README.md` — this file — is the one top-level entry in neither table above. It is not a +runtime input and seeds nothing; it ships as this directory's own documentation, arriving in +a project through the same recursive copy, and is registered in `TEMPLATE_MANIFEST` so +`squad upgrade` keeps it current. Classified here rather than left unlisted, since the +Invariant below requires every top-level file to be accounted for. + ### Subtrees `squad init` copies this directory **recursively**, so every subtree below ships into diff --git a/packages/squad-sdk/templates/README.md b/packages/squad-sdk/templates/README.md index 587c1ef1e..bc343dc0c 100644 --- a/packages/squad-sdk/templates/README.md +++ b/packages/squad-sdk/templates/README.md @@ -45,8 +45,7 @@ After the agent's own files are seeded, these templates are not read again at ru | File | Used to seed | |------|-------------| | `charter.md` | New agent `charter.md` when a team member is added | -| `copilot-instructions.md` | `.github/copilot-instructions.md` for the repo | -| `fact-checker-charter.md` | `agents/fact-checker/charter.md` | +| `copilot-instructions.md` | `.github/copilot-instructions.md` for the repo || `fact-checker-charter.md` | `agents/fact-checker/charter.md` | | `fact-checker-policy.md` | `agents/fact-checker/policy.md` (Fact Checker methodology) | | `history.md` | New agent `history.md` when a team member is added | | `rai-charter.md` | `agents/Rai/charter.md` | @@ -56,6 +55,12 @@ After the agent's own files are seeded, these templates are not read again at ru | `scribe-charter.md` | `agents/scribe/charter.md` | | `skill.md` | Skeleton for new skill files under `.github/skills/` | +`README.md` — this file — is the one top-level entry in neither table above. It is not a +runtime input and seeds nothing; it ships as this directory's own documentation, arriving in +a project through the same recursive copy, and is registered in `TEMPLATE_MANIFEST` so +`squad upgrade` keeps it current. Classified here rather than left unlisted, since the +Invariant below requires every top-level file to be accounted for. + ### Subtrees `squad init` copies this directory **recursively**, so every subtree below ships into diff --git a/templates/README.md b/templates/README.md index 587c1ef1e..bc343dc0c 100644 --- a/templates/README.md +++ b/templates/README.md @@ -45,8 +45,7 @@ After the agent's own files are seeded, these templates are not read again at ru | File | Used to seed | |------|-------------| | `charter.md` | New agent `charter.md` when a team member is added | -| `copilot-instructions.md` | `.github/copilot-instructions.md` for the repo | -| `fact-checker-charter.md` | `agents/fact-checker/charter.md` | +| `copilot-instructions.md` | `.github/copilot-instructions.md` for the repo || `fact-checker-charter.md` | `agents/fact-checker/charter.md` | | `fact-checker-policy.md` | `agents/fact-checker/policy.md` (Fact Checker methodology) | | `history.md` | New agent `history.md` when a team member is added | | `rai-charter.md` | `agents/Rai/charter.md` | @@ -56,6 +55,12 @@ After the agent's own files are seeded, these templates are not read again at ru | `scribe-charter.md` | `agents/scribe/charter.md` | | `skill.md` | Skeleton for new skill files under `.github/skills/` | +`README.md` — this file — is the one top-level entry in neither table above. It is not a +runtime input and seeds nothing; it ships as this directory's own documentation, arriving in +a project through the same recursive copy, and is registered in `TEMPLATE_MANIFEST` so +`squad upgrade` keeps it current. Classified here rather than left unlisted, since the +Invariant below requires every top-level file to be accounted for. + ### Subtrees `squad init` copies this directory **recursively**, so every subtree below ships into From 4e6639cc8e2ebbd047a0c4be14a8a5576177cbab Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Tue, 1 Sep 2026 09:36:04 -0700 Subject: [PATCH 6/6] fix(templates): repair merged table row and correct casting/ claim Two Copilot findings: 1. The copilot-instructions.md and fact-checker-charter.md rows were concatenated onto one line, breaking the bootstrap table. Introduced by a stray edit in the previous commit; the table now renders again. 2. The casting/ row claimed the directory is read during Init Mode casting. Nothing shipped references it, which is the whole reason #1972 exists -- so the row asserted a consumer this PR had already established does not exist, and contradicted its own description. Reclassified as shipped data with no known consumer, still explicitly not-safe-to-delete pending #1972. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 0515ad5d-4c5b-48bb-92a6-4e1296594cab --- .squad-templates/README.md | 5 +++-- .squad/templates/README.md | 5 +++-- packages/squad-cli/templates/README.md | 5 +++-- packages/squad-sdk/templates/README.md | 5 +++-- templates/README.md | 5 +++-- 5 files changed, 15 insertions(+), 10 deletions(-) diff --git a/.squad-templates/README.md b/.squad-templates/README.md index bc343dc0c..f1a5430bf 100644 --- a/.squad-templates/README.md +++ b/.squad-templates/README.md @@ -45,7 +45,8 @@ After the agent's own files are seeded, these templates are not read again at ru | File | Used to seed | |------|-------------| | `charter.md` | New agent `charter.md` when a team member is added | -| `copilot-instructions.md` | `.github/copilot-instructions.md` for the repo || `fact-checker-charter.md` | `agents/fact-checker/charter.md` | +| `copilot-instructions.md` | `.github/copilot-instructions.md` for the repo | +| `fact-checker-charter.md` | `agents/fact-checker/charter.md` | | `fact-checker-policy.md` | `agents/fact-checker/policy.md` (Fact Checker methodology) | | `history.md` | New agent `history.md` when a team member is added | | `rai-charter.md` | `agents/Rai/charter.md` | @@ -69,7 +70,7 @@ wholesale — each has a distinct consumer. | Subtree | Kind | Consumer | |---------|------|----------| -| `casting/` | Runtime input | Custom-universe character lists, read during Init Mode casting when a user names a universe that has no built-in list. See `casting-reference.md` for the casting algorithm. Deleting it removes those name pools. | +| `casting/` | Shipped data, no known consumer | Custom-universe character lists. No shipped template or skill references this directory, so nothing is known to read it at runtime — see #1972, which decides whether a consumer was lost or the directory is vestigial. Treat as unclassified: do not delete pending that outcome. `casting-reference.md` documents the casting algorithm itself. | | `identity/` | Bootstrap template | Seeds `.squad/identity/now.md` and `wisdom.md`. Registered in `TEMPLATE_MANIFEST` under `identity/`. | | `scripts/` | User copy-source | Documented for users to copy from — `cp -r .squad/templates/scripts/notes/ scripts/notes/` (see the state-backends doc). | | `skills/` | Bootstrap template | Source for skills the `TEMPLATE_MANIFEST` installs **to `.github/skills/`** (destinations are `../.github/skills/...`). The installed copy under `.github/skills/` is what agents load. | diff --git a/.squad/templates/README.md b/.squad/templates/README.md index bc343dc0c..f1a5430bf 100644 --- a/.squad/templates/README.md +++ b/.squad/templates/README.md @@ -45,7 +45,8 @@ After the agent's own files are seeded, these templates are not read again at ru | File | Used to seed | |------|-------------| | `charter.md` | New agent `charter.md` when a team member is added | -| `copilot-instructions.md` | `.github/copilot-instructions.md` for the repo || `fact-checker-charter.md` | `agents/fact-checker/charter.md` | +| `copilot-instructions.md` | `.github/copilot-instructions.md` for the repo | +| `fact-checker-charter.md` | `agents/fact-checker/charter.md` | | `fact-checker-policy.md` | `agents/fact-checker/policy.md` (Fact Checker methodology) | | `history.md` | New agent `history.md` when a team member is added | | `rai-charter.md` | `agents/Rai/charter.md` | @@ -69,7 +70,7 @@ wholesale — each has a distinct consumer. | Subtree | Kind | Consumer | |---------|------|----------| -| `casting/` | Runtime input | Custom-universe character lists, read during Init Mode casting when a user names a universe that has no built-in list. See `casting-reference.md` for the casting algorithm. Deleting it removes those name pools. | +| `casting/` | Shipped data, no known consumer | Custom-universe character lists. No shipped template or skill references this directory, so nothing is known to read it at runtime — see #1972, which decides whether a consumer was lost or the directory is vestigial. Treat as unclassified: do not delete pending that outcome. `casting-reference.md` documents the casting algorithm itself. | | `identity/` | Bootstrap template | Seeds `.squad/identity/now.md` and `wisdom.md`. Registered in `TEMPLATE_MANIFEST` under `identity/`. | | `scripts/` | User copy-source | Documented for users to copy from — `cp -r .squad/templates/scripts/notes/ scripts/notes/` (see the state-backends doc). | | `skills/` | Bootstrap template | Source for skills the `TEMPLATE_MANIFEST` installs **to `.github/skills/`** (destinations are `../.github/skills/...`). The installed copy under `.github/skills/` is what agents load. | diff --git a/packages/squad-cli/templates/README.md b/packages/squad-cli/templates/README.md index bc343dc0c..f1a5430bf 100644 --- a/packages/squad-cli/templates/README.md +++ b/packages/squad-cli/templates/README.md @@ -45,7 +45,8 @@ After the agent's own files are seeded, these templates are not read again at ru | File | Used to seed | |------|-------------| | `charter.md` | New agent `charter.md` when a team member is added | -| `copilot-instructions.md` | `.github/copilot-instructions.md` for the repo || `fact-checker-charter.md` | `agents/fact-checker/charter.md` | +| `copilot-instructions.md` | `.github/copilot-instructions.md` for the repo | +| `fact-checker-charter.md` | `agents/fact-checker/charter.md` | | `fact-checker-policy.md` | `agents/fact-checker/policy.md` (Fact Checker methodology) | | `history.md` | New agent `history.md` when a team member is added | | `rai-charter.md` | `agents/Rai/charter.md` | @@ -69,7 +70,7 @@ wholesale — each has a distinct consumer. | Subtree | Kind | Consumer | |---------|------|----------| -| `casting/` | Runtime input | Custom-universe character lists, read during Init Mode casting when a user names a universe that has no built-in list. See `casting-reference.md` for the casting algorithm. Deleting it removes those name pools. | +| `casting/` | Shipped data, no known consumer | Custom-universe character lists. No shipped template or skill references this directory, so nothing is known to read it at runtime — see #1972, which decides whether a consumer was lost or the directory is vestigial. Treat as unclassified: do not delete pending that outcome. `casting-reference.md` documents the casting algorithm itself. | | `identity/` | Bootstrap template | Seeds `.squad/identity/now.md` and `wisdom.md`. Registered in `TEMPLATE_MANIFEST` under `identity/`. | | `scripts/` | User copy-source | Documented for users to copy from — `cp -r .squad/templates/scripts/notes/ scripts/notes/` (see the state-backends doc). | | `skills/` | Bootstrap template | Source for skills the `TEMPLATE_MANIFEST` installs **to `.github/skills/`** (destinations are `../.github/skills/...`). The installed copy under `.github/skills/` is what agents load. | diff --git a/packages/squad-sdk/templates/README.md b/packages/squad-sdk/templates/README.md index bc343dc0c..f1a5430bf 100644 --- a/packages/squad-sdk/templates/README.md +++ b/packages/squad-sdk/templates/README.md @@ -45,7 +45,8 @@ After the agent's own files are seeded, these templates are not read again at ru | File | Used to seed | |------|-------------| | `charter.md` | New agent `charter.md` when a team member is added | -| `copilot-instructions.md` | `.github/copilot-instructions.md` for the repo || `fact-checker-charter.md` | `agents/fact-checker/charter.md` | +| `copilot-instructions.md` | `.github/copilot-instructions.md` for the repo | +| `fact-checker-charter.md` | `agents/fact-checker/charter.md` | | `fact-checker-policy.md` | `agents/fact-checker/policy.md` (Fact Checker methodology) | | `history.md` | New agent `history.md` when a team member is added | | `rai-charter.md` | `agents/Rai/charter.md` | @@ -69,7 +70,7 @@ wholesale — each has a distinct consumer. | Subtree | Kind | Consumer | |---------|------|----------| -| `casting/` | Runtime input | Custom-universe character lists, read during Init Mode casting when a user names a universe that has no built-in list. See `casting-reference.md` for the casting algorithm. Deleting it removes those name pools. | +| `casting/` | Shipped data, no known consumer | Custom-universe character lists. No shipped template or skill references this directory, so nothing is known to read it at runtime — see #1972, which decides whether a consumer was lost or the directory is vestigial. Treat as unclassified: do not delete pending that outcome. `casting-reference.md` documents the casting algorithm itself. | | `identity/` | Bootstrap template | Seeds `.squad/identity/now.md` and `wisdom.md`. Registered in `TEMPLATE_MANIFEST` under `identity/`. | | `scripts/` | User copy-source | Documented for users to copy from — `cp -r .squad/templates/scripts/notes/ scripts/notes/` (see the state-backends doc). | | `skills/` | Bootstrap template | Source for skills the `TEMPLATE_MANIFEST` installs **to `.github/skills/`** (destinations are `../.github/skills/...`). The installed copy under `.github/skills/` is what agents load. | diff --git a/templates/README.md b/templates/README.md index bc343dc0c..f1a5430bf 100644 --- a/templates/README.md +++ b/templates/README.md @@ -45,7 +45,8 @@ After the agent's own files are seeded, these templates are not read again at ru | File | Used to seed | |------|-------------| | `charter.md` | New agent `charter.md` when a team member is added | -| `copilot-instructions.md` | `.github/copilot-instructions.md` for the repo || `fact-checker-charter.md` | `agents/fact-checker/charter.md` | +| `copilot-instructions.md` | `.github/copilot-instructions.md` for the repo | +| `fact-checker-charter.md` | `agents/fact-checker/charter.md` | | `fact-checker-policy.md` | `agents/fact-checker/policy.md` (Fact Checker methodology) | | `history.md` | New agent `history.md` when a team member is added | | `rai-charter.md` | `agents/Rai/charter.md` | @@ -69,7 +70,7 @@ wholesale — each has a distinct consumer. | Subtree | Kind | Consumer | |---------|------|----------| -| `casting/` | Runtime input | Custom-universe character lists, read during Init Mode casting when a user names a universe that has no built-in list. See `casting-reference.md` for the casting algorithm. Deleting it removes those name pools. | +| `casting/` | Shipped data, no known consumer | Custom-universe character lists. No shipped template or skill references this directory, so nothing is known to read it at runtime — see #1972, which decides whether a consumer was lost or the directory is vestigial. Treat as unclassified: do not delete pending that outcome. `casting-reference.md` documents the casting algorithm itself. | | `identity/` | Bootstrap template | Seeds `.squad/identity/now.md` and `wisdom.md`. Registered in `TEMPLATE_MANIFEST` under `identity/`. | | `scripts/` | User copy-source | Documented for users to copy from — `cp -r .squad/templates/scripts/notes/ scripts/notes/` (see the state-backends doc). | | `skills/` | Bootstrap template | Source for skills the `TEMPLATE_MANIFEST` installs **to `.github/skills/`** (destinations are `../.github/skills/...`). The installed copy under `.github/skills/` is what agents load. |