Spike: host-neutral canonical coordinator (ADR-003 option B), opt-in experiment

Open
#2,488 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
8/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
typescript
Domain
cli, devtools

Research direction

This is an architecture experiment, not a first task. Start by reading ADR-003 (#2486) and the scenarios in #2487, then the existing Copilot projection of .github/agents/squad.agent.md and the .squad/ state paths that squad_state_read and teamRoot resolve. Done means a findings comment on this issue, plus an ADR-003 update if the recommendation changes.

Written by the indexing model from the issue text.

Description

Part of epic #2438 (Phase 7). This is option B of ADR-003 (#2486) as a bounded experiment, not a shipping commitment (team summary on #2469). Option C (#2487) is the 2.0 path and goes ahead independently. This spike doesn't block it, and it doesn't ship.

Question to answer

Would a host-neutral canonical coordinator in the workspace, with Copilot's .github/agents/squad.agent.md generated from it like every other host's projection, measurably improve correctness or maintainability enough to justify migrating existing repositories? A cleaner directory layout alone doesn't count.

Rules for the spike

  • Only disposable workspaces that explicitly opt in, for example behind an experimental flag or an environment switch that squad init never sets by default.
  • No default installer migration, and no migration of live teams' repositories.
  • A fixed budget, agreed before starting: suggested 3 days. When it runs out, report what was learned, even if the prototype is incomplete.
  • The branch is not merged to dev as shipping behavior. Findings come back as a comment here, and as an ADR-003 update if they change the recommendation.

What to build

  • A neutral coordinator source in the workspace. Settle open question 2 of ADR-003: inside .squad/, served by squad_state_read and following teamRoot, or outside it.
  • Copilot and Claude projections generated from it. Copilot's file has to carry what today's file does: the version stamp, the team-capabilities block squad cast writes (#1608), and the customization backup (#1052).

What to test

Reuse the behavioral scenarios from #2487, then add:

  • fresh workspaces, and customized legacy workspaces (an edited squad.agent.md)
  • monorepos (the Copilot file at the git root, .squad/ in a subfolder), and remote teamRoot
  • repeatable upgrades: running squad upgrade twice gives no diff
  • customizations preserved, with clear precedence between user edits, project policy and defaults
  • rollback restores the original bytes (harness-adapters §13)
  • no Copilot regression: the snapshot guard, and a Copilot run of the same scenarios

Report back with

  • Did the scenario results improve over C? Count the defects B avoids that C doesn't.
  • Maintainability: how much code and how many tests the single source removes or adds, compared with C.
  • Migration risk: what breaks for customized, monorepo and remote workspaces, and how it's detected and recovered.
  • A recommendation: ship B later, revise it, or drop it.

🤖 Generated with Claude Code

Dominant language
TypeScript
Stars
3.4k
Forks
516
Avg merge
1d 15h
Merged PRs (30d)
116

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from github/squad

All issues in github/squad

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.