Skip to content

feat: worktree awareness, Scribe auto-commit, and decision consolidation - #1

Merged
bradygaster merged 6 commits into
bradygaster:mainfrom
amolchanov:worktree-awareness-and-scribe-commit
Feb 7, 2026
Merged

feat: worktree awareness, Scribe auto-commit, and decision consolidation#1
bradygaster merged 6 commits into
bradygaster:mainfrom
amolchanov:worktree-awareness-and-scribe-commit

Conversation

@amolchanov

Copy link
Copy Markdown
Contributor

Summary

Adds worktree support and Scribe improvements so that Squad works correctly in multi-worktree setups.

Changes

Worktree Awareness (squad.agent.md)

  • Two strategies: worktree-local (branch-isolated state, recommended for concurrent work) and main-checkout (shared state, single-session only)
  • Auto-detection: checks if .ai-team/\ exists in current worktree; falls back to main checkout if not
  • Coordinator resolves team root once and passes \TEAM_ROOT\ into every spawn prompt — agents never discover it themselves

Scribe Auto-Commit (squad.agent.md, scribe-charter.md)

  • Scribe commits .ai-team/\ changes after every session with a detailed \docs(ai-team):\ conventional commit message
  • Itemizes: session logged, decisions merged, cross-agent updates propagated

Decision Consolidation (squad.agent.md, scribe-charter.md)

  • After merging inbox, Scribe deduplicates decisions.md:
    • Exact duplicates (same heading) → keep first
    • Overlapping decisions (same topic, different authors/dates) → consolidate into a single (consolidated)\ block with merged rationale

Merge-safe append-only files (squad.agent.md, index.js)

  • .gitattributes\ \merge=union\ rules for decisions.md, history.md, log/, orchestration-log/
  • \index.js\ auto-creates these rules during
    px squad\ install

Template updates (charter.md, scribe-charter.md)

  • Both templates include worktree awareness guidance and reference \TEAM_ROOT\

Files changed

  • .github/agents/squad.agent.md\ — main agent instructions
  • \index.js\ — install script (.gitattributes setup)
  • \ emplates/charter.md\ — agent charter template
  • \ emplates/scribe-charter.md\ — Scribe charter template

- Add Worktree Awareness section with two strategies (worktree-local, main-checkout)
- Coordinator resolves team root and passes TEAM_ROOT to all spawn prompts
- Scribe commits .ai-team/ changes with detailed conventional commit messages
- Scribe deduplicates and consolidates overlapping decisions after merge
- Add .gitattributes merge=union rules for append-only .ai-team/ files (docs + index.js)
- Update charter.md and scribe-charter.md templates with worktree and commit guidance
- Add Ceremonies section to squad.agent.md with facilitator pattern
- Ceremonies are configurable per squad via .ai-team/ceremonies.json
- Support auto and manual triggers (before/after work batches)
- Facilitator spawns participants as sub-tasks, synthesizes summary
- Two default ceremonies: Design Review (before) and Retrospective (after)
- Add ceremonies.json template and auto-copy in index.js
- Add ceremony signals to routing table
- Add ceremonies.json to Source of Truth hierarchy
- Instruct facilitator to keep ceremonies fast and focused
- Participants provide domain-specific concerns, interface needs, and blockers only
- Goal: minimize iterations by surfacing problems before independent work begins
- Explicitly prohibit rehashing known context — ask for delta feedback only
Root cause: git -C with Windows paths and multiline git commit -m
with backtick-n both fail silently in PowerShell.

Fix:
- Use cd into team root instead of git -C
- Write commit message to temp file, commit with git commit -F
- Add verification step: git log --oneline -1 after commit
After a ceremony completes, skip auto-triggered ceremony checks for the
next step. Prevents back-to-back ceremonies (e.g., before-ceremony
completing then immediately triggering an after-ceremony check).
Cooldown resets after one batch of work completes without a ceremony.
Consistent with rest of .ai-team/ which is all markdown.
No programmatic consumer needs structured JSON — the Coordinator
parses ceremonies.md as natural language like every other config file.
@bradygaster

bradygaster commented Feb 7, 2026

Copy link
Copy Markdown
Owner

thank you for the pull request @amolchanov! you're the first! i do have one question - and this is more a behavioral nitpick - I am currently working with Squad on two projects; one of them i've explicitly .gitignored the Squad-related stuff for reasons but, the intent of the product is, obviously, for the team to be a part of the repo. So, in spirit i agree with you but i can imagine there are some scenarios in which a user might want to keep their code separate from their Squad and do the same sort of thing I've done. In that case, would your tweak be a no-op or would it try to "un-ignore" the files? If you could do a few tests of that scenario, I do think that would be a valid concern for some users. I'd suggest making Scribe (I guess it was a matter of time before someone referenced Scribe in first person) decide intelligently on that commit behavior if the user has explicitly added the team files to the ignore list. Scribe should probably just see that and presume that's a step they can avoid.

Aside from that, I'm eager to take the contribution - just curious if you'd mind testing that one odd edge case. Should Scribe be aggressive and force-unignore the files? I'd want us to be a little careful. At the same time, if users - or you - think I should lean in hard that "the squad is a part of your repo and grows with it," I could take it as constructive product owner feedback. ;)


### Worktree Awareness

Squad and all spawned agents may be running inside a **git worktree** rather than the main checkout. All `.ai-team/` paths (charters, history, decisions, logs) MUST be resolved relative to a known **team root**, never assumed from CWD.

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is hot. Thank you! I'd been wondering how to bring worktrees to Squad. This is so great.

@bradygaster

Copy link
Copy Markdown
Owner

Never mind my concern - I see why this is an all-or-nothing and it is absolutely the right direction. Merged!

@bradygaster
bradygaster merged commit 9b62931 into bradygaster:main Feb 7, 2026
@amolchanov

amolchanov commented Feb 8, 2026 via email

Copy link
Copy Markdown
Contributor Author

bradygaster pushed a commit that referenced this pull request Mar 22, 2026
* test: TDD contract tests for autonomous-pipeline core split

Add 31 tests defining the behavioral contract for the planned
autonomous-pipeline-core module (PRD Recommendation #1). Tests cover:

- Task→tier assignment via selectResponseTier with DEMO_CONFIG
- CostTracker per-agent accumulation across multiple agents/tasks
- Agent state transitions (idle→working→idle→done lifecycle)
- selectResponseTier routing properties (tier, modelTier, maxAgents, timeout)
- Task queue creation, role coverage, and findNextTask assignment logic
- simulateCost model contract (complexity→tokens→cost scaling)
- Core pipeline wiring without telemetry/dashboard/OTel dependencies

All 31 tests pass against current code. After the refactor splits
core logic from telemetry+dashboard, these same assertions verify
the extracted module preserves identical behavior.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* samples: standardize READMEs, naming, and add template

- Standardize all 9 package.json names to @squad-samples/* format (Rec #3)
- Rewrite root samples/README.md as public-facing index with learning path (Rec #9)
- Standardize all 9 per-sample READMEs to consistent template (Rec #8)
- Apply Microsoft Writing Style Guide across all sample documentation
- Add SAMPLE-README-TEMPLATE.md for future sample authors
- Add 31 TDD tests for autonomous-pipeline core split (Rec #1 prep)

17 files modified, 1 new file. All markdownlint and cspell checks pass.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
bradygaster added a commit that referenced this pull request Mar 22, 2026
- Merged 9 inbox decisions → decisions.md (personal squad impl plan, economy mode design/governance, persistent model preference, user directives, template sync, ESM fix)
- Deleted inbox files (merge complete)
- Updated agent histories: Flight (personal squad plan), EECOM (economy mode), Procedures (governance proposals)
- Appended team updates to agent contexts

Fleet Status:
- Flight: Personal squad design validated, 19-task plan across 4 PRs (MVP = PR #1+3)
- EECOM: Economy mode complete (34 tests), PR #504 open
- Procedures: Economy + consult-mode governance drafted, PR #503 open
- Directives: #464 rate limit UX (soft dep #500), #502 bug P1 next-up, triage includes discussions

Ready for execution: EECOM Phase 1, Procedures Phase 3 (concurrent).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
bradygaster added a commit that referenced this pull request Mar 22, 2026
* feat: economy mode skill, governance proposals for #500 and #344

- Add .squad/skills/economy-mode/SKILL.md: Layer 3 cost modifier
  - Economy table shifts code tasks to gpt-4.1/gpt-5-mini, arch to sonnet
  - Activation: session phrase, config.json economyMode:true, or --economy flag
  - Layer 0/1/2 (user intent) always overrides economy mode
  - 💰 indicator in spawn acknowledgments
  - Confidence: low (first implementation)

- Add .squad/decisions/inbox/procedures-economy-mode-governance.md
  - Draft additions to squad.agent.md for Flight review
  - Economy mode paragraph after Layer 0, updated table, 💰 convention
  - Valid models catalog audit findings (claude-sonnet-4.6 missing, etc.)

- Add .squad/decisions/inbox/procedures-personal-squad-governance.md
  - Five gap analysis: Init Mode, consult mode detection, TEAM_ROOT semantics,
    charter templates, missing consult-mode skill
  - Proposed CONSULT_MODE spawn signal and 🧳 acknowledgment format
  - Proposed new consult-mode skill (post-governance-approval)

- Update procedures history.md with learnings

Closes #500
References #344

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* feat: economy mode for cost-conscious model selection (#500)

Add economy mode that shifts model selection to cheaper alternatives
at Layer 3 (task-aware auto) and Layer 4 (default). Explicit user
preferences at Layers 0-2 are never overridden.

SDK changes:
- Add ECONOMY_MODEL_MAP and applyEconomyMode() to config/models.ts
- Add readEconomyMode() / writeEconomyMode() for config.json persistence
- Update resolveModel() in config/models.ts with economyMode option
- Update resolveModel() in agents/model-selector.ts with economyMode option

CLI changes:
- Add 'squad economy [on|off]' command for persistent toggle
- Add --economy global flag for session-level activation (SQUAD_ECONOMY_MODE=1)

Tests:
- 34 new tests in test/economy-mode.test.ts (all passing)

Economy model table:
  claude-opus-4.6   -> claude-sonnet-4.5 (architecture/review)
  claude-sonnet-4.6 -> gpt-4.1           (code writing)
  claude-haiku-4.5  -> gpt-4.1           (docs/mechanical)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Scribe: Wave 1 decisions merged (#329/#344/#500)

- Merged 9 inbox decisions → decisions.md (personal squad impl plan, economy mode design/governance, persistent model preference, user directives, template sync, ESM fix)
- Deleted inbox files (merge complete)
- Updated agent histories: Flight (personal squad plan), EECOM (economy mode), Procedures (governance proposals)
- Appended team updates to agent contexts

Fleet Status:
- Flight: Personal squad design validated, 19-task plan across 4 PRs (MVP = PR #1+3)
- EECOM: Economy mode complete (34 tests), PR #504 open
- Procedures: Economy + consult-mode governance drafted, PR #503 open
- Directives: #464 rate limit UX (soft dep #500), #502 bug P1 next-up, triage includes discussions

Ready for execution: EECOM Phase 1, Procedures Phase 3 (concurrent).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: hard-fail on Node <22.5.0 with clear message (#502)

node:sqlite (required by the Copilot SDK for session storage) was added
in Node 22.5.0. Previously Squad only warned and continued, leading to
cryptic ERR_UNKNOWN_BUILTIN_MODULE crashes later.

Changes:
- cli-entry.ts: replace soft warn+continue with hard process.exit(1) and
  a clear upgrade message when Node <22.5.0 is detected at startup.
  Remove now-redundant checkNodeSqlite() function and its call site.
- doctor.ts: add checkNodeVersion() check to squad doctor diagnostics
  so users can detect the version gap proactively.
- package.json (root, squad-cli, squad-sdk): correct engines field from
  >=20 to >=22.5.0, enabling npm/npx to warn at install time.
- test/cli/doctor.test.ts: add 5 tests for checkNodeVersion pass/fail
  paths; update check-count assertion.

Closes #502

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
bradygaster added a commit that referenced this pull request Mar 22, 2026
- Add 'squad personal init/list/add/remove' subcommands
- Add 'squad cast' to show merged session cast
- Add --team-root CLI flag for explicit team root override
- Register commands in cli-entry.ts with help text

PR #2 of #508 implementation plan.
Depends on: squad/508-sdk-foundation (PR #1)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
bradygaster added a commit that referenced this pull request Mar 23, 2026
* feat(sdk): add personal squad resolution and ambient discovery (#508)

- Add personalDir to ResolvedSquadPaths
- Add resolvePersonalSquadDir() with SQUAD_NO_PERSONAL kill switch
- Add PersonalAgentMeta/PersonalAgentManifest types
- Add resolvePersonalAgents() for personal agent discovery
- Add mergeSessionCast() to merge personal into project cast
- Add ensureSquadPathTriple() for triple-root path validation
- Export all new functions and types

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* feat(cli): add personal squad commands and cast display (#508)

- Add 'squad personal init/list/add/remove' subcommands
- Add 'squad cast' to show merged session cast
- Add --team-root CLI flag for explicit team root override
- Register commands in cli-entry.ts with help text

PR #2 of #508 implementation plan.
Depends on: squad/508-sdk-foundation (PR #1)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
bradygaster pushed a commit that referenced this pull request Mar 23, 2026
- Add preflight job scanning all packages for file: references and
  validating semver versions before any publish work begins
- Add npm pack --dry-run validation step to smoke-test job
- Disable ghost publish-npm.yml workflow via GitHub API
- Add purpose documentation to ci-rerun.yml
- Fix YAML parse issue: quote step names containing 'file:' colon
- Pipeline chain: preflight → smoke-test → publish-sdk → publish-cli

This is the #1 gate that would have prevented the v0.9.1 incident.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
joniba pushed a commit to joniba/squad that referenced this pull request Mar 26, 2026
- Write orchestration log: 2026-03-22T17-30-gandalf.md (Teams watchdog decomposition outcome)
- Write session log: 2026-03-22T17-30-teams-watchdog-decomp.md (brief session summary)
- Merge 3 decision inbox files into decisions.md (copilot CLI directive, scripting philosophy, watchdog architecture)
- Delete inbox files after merge
- Update gandalf/history.md with Teams watchdog learnings

Issues bradygaster#1-bradygaster#6 created on jbenami_microsoft/ms-pa for 6-step watchdog pipeline.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
joniba pushed a commit to joniba/squad that referenced this pull request Mar 26, 2026
- Elrond: Skills scan of tamirdresher/squad-skills (20 plugins)
  * Identified 3 directly relevant: teams-monitor, news-broadcasting, secrets-management
  * Documented full inventory with P0/P1 prioritization
  * Key insight: WorkIQ poll-based, well-suited for daily batch design

- Bilbo: Comprehensive plugin catalog
  * Created docs/squad-skills-catalog.md (25.2 KB, 21 plugins)
  * Mapped to Teams watchdog Issues bradygaster#1-bradygaster#6
  * Organized by skill domain, implementation order

- Scribe: Decision management
  * Merged .squad/decisions/inbox → decisions.md
  * Wrote orchestration logs for Elrond, Bilbo
  * Wrote session log for skills scan

Teams watchdog design constraints confirmed: rate-limit WorkIQ to 1 query/agent cycle.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
joniba pushed a commit to joniba/squad that referenced this pull request Mar 26, 2026
Adds probe-messages.ps1 that fetches recent Teams messages using
copilot -p with the workiq-ask_work_iq MCP tool. Configurable
time window via -Hours parameter. Output is plain text to stdout.

Key finding: copilot -p requires --allow-tool='workiq' for
non-interactive MCP tool consent.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
akubly pushed a commit to akubly/squad that referenced this pull request May 14, 2026
…alidation, test gaps

Close all four FIDO blocking gaps and fold Flight + RETRO nits:

FIDO Gap bradygaster#1 — Consult setup-mode success path:
  Add test exercising the guarded consult setup path going GREEN from a
  registered consumer repo with a personal squad available. Asserts
  config.json written and .git/info/exclude updated.

FIDO Gap bradygaster#2 — .gitignore non-mutation:
  Extend consult (x2) and link failure tests to assert .gitignore and
  .git/info/exclude are not written when the resolver guard fires.

FIDO Gap bradygaster#3 — Deferred (see decision drop):
  URL-without-clone-destination, clone failure, host-verify are not
  present in the current implementation and have no prior behavior to
  preserve. Deferred to the piece that introduces those features.

FIDO Gap bradygaster#4 — Dead resolved variable:
  - consult and link dispatch: remove dead named variable, use inline
    boolean guard (gate-only semantics; runners are self-contained).
  - assign dispatch: store guard result and thread it into RunAssignOpts
    via new resolved field so guard and runner share context.
  - Runner falls back to internal resolve for direct (non-CLI) callers.
  - Threading proven by asserting resolved.path appears in output.

Flight nit — Guard harmonization:
  All three commands now use dispatch-level guards in cli-entry.ts.
  Inline boolean check for commands whose runners need no resolved data;
  threaded struct for assign where the runner uses resolved.callsign
  and resolved.path. resolveSquadV2 alias in cli-entry.ts unchanged
  (required to distinguish from legacy sdk.resolveSquad call pattern).

RETRO nit — Path validation:
  Add path.isAbsolute() and ..-segment checks on opts.cwd and opts.home
  in runAssignToCopilot before any file-write path uses them.
  Validate --home at CLI dispatch boundary as well.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
akubly pushed a commit to akubly/squad that referenced this pull request May 14, 2026
…ns + cross-agent updates

Sims successfully addressed all 4 blocking FIDO gaps + Flight/RETRO nits in piece 08b revision cycle:
- Gap bradygaster#1: Consult setup-mode success test added
- Gap bradygaster#2: .gitignore non-mutation assertions added
- Gap bradygaster#3: URL/clone/host-verify deferred to future work (documented rationale)
- Gap bradygaster#4: Dead resolved variable threaded to assign runner

Test results: 31 GREEN (17 legacy-resolver-migration + 14 consult); Build CLEAN; Scrub gate baseline unchanged.

Decisions merged: Sims 08b revision decision from inbox to canonical decisions.md.

Cross-agent updates:
- EECOM: Lockout cycle closed
- FIDO: Gap closure confirmed
- Flight: Guard location nits folded into revision
- RETRO: All hardening candidates applied

Logs written:
- .squad/orchestration-log/2026-05-14T16-12-01-sims.md
- .squad/log/2026-05-14T16-12-01-piece-08b-sims-revision.md

Phase C ready: Squash pending.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
tamirdresher pushed a commit that referenced this pull request Jun 9, 2026
Five fixes applied based on the tamresearch1 squad's content review (Picard,
Q, Crusher, Troi, Guinan, Geordi, Paris, Neelix):

1. Slide 13 (classify spotlight) — corrected the classifier truth. The
   (CI|PR|build) regex sits in BOTH FORBIDDEN_PATTERNS AND the TRANSIENT
   heuristic; FORBIDDEN scan wins, so TRANSIENT branch is unreachable for
   those inputs (only fires via explicit --class). Removed incorrect
   "CI build always passes → TRANSIENT" example. Verified live against
   LocalMemoryStore.classify() on 2026-06-09. (Q's #1 ❌ FAIL finding.)

2. Slide 1 — changed "Co-creator of Squad" to "Contributor & maintainer"
   to avoid attribution risk noted by Q and Crusher (upstream creator is
   Brady Gaster per the tamresearch1 decisions.md).

3. Slide 16 — "ADC Squad runner demo" generalized to "External Squad-using
   project demo" (Crusher: unexplained acronym could read as internal
   codename in public talk).

4. Slide 4 — "dozens of changesets" expanded to "97 changesets across CLI
   and SDK (50 SDK + 71 CLI, deduplicated)" per CHANGELOG.md line 9
   (Q: underquoting invites skepticism).

5. NEW slide 62 (page 61) — "The three questions, answered in human terms"
   closing synthesis that answers slide 02's opening questions in plain
   language. Bottom line: "your team doesn't lose context to keep the repo
   clean — it gets both." Addresses Troi/Guinan/Picard's structural
   feedback: the deck showed the mechanism honestly but was missing the
   relief.

Plus: workflow stage 4 slide updated to note the FORBIDDEN/TRANSIENT regex
overlap explicitly in the code comment block.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@github-actions

github-actions Bot commented Jun 12, 2026

Copy link
Copy Markdown
Contributor

🛫 PR Readiness Check

ℹ️ This comment updates on each push. Last checked: commit 82109ba

PR Scope: 🔧 Infrastructure

⚠️ 3 item(s) to address before review

Status Check Details
Single commit 6 commits — consider squashing before review
Not in draft Ready for review
Branch up to date Up to date with dev
Copilot review No Copilot review yet — it may still be processing
Changeset present No source files changed — changeset not required
Scope clean No .squad/ or docs/proposals/ files
No merge conflicts Merge status unknown — GitHub is still computing
Copilot threads resolved No Copilot review threads
CI passing 1 check(s) still running

Files Changed (5 files, +365 −5)

File +/−
.github/agents/squad.agent.md +246 −3
index.js +30 −0
templates/ceremonies.md +41 −0
templates/charter.md +2 −0
templates/scribe-charter.md +46 −2

Total: +365 −5


This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.

bradygaster added a commit that referenced this pull request Jun 23, 2026
…oard (#1373)

* docs: add SWE-bench Lite technical report (198/300 = 66.0%)

* fix: reconcile timeout numbers, add Limitations section, link public data repo

Addresses Brady's review:
- Clarify 31 timeouts total (20 no-patch + 11 partial-patch errors)
- Remove wording inconsistency between Key Parameters and Error Analysis
- Add Limitations & Attribution section (model vs orchestration)
- Link to public tamirdresher/squad-swe-bench for full reproduction

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Brady Gaster <41929050+bradygaster@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants