Repository navigation
feat: standalone squad migrate command for SDK-First conversion #250
Description
Summary
Users with existing markdown-only squads (.squad/ directory with team.md, routing.md, agent charters) have no tooling to convert to the SDK-First authoring model. The only migration that exists is squad upgrade --migrate-directory which renames .ai-team/ to .squad/ but doesn't touch the config format.
Proposed Behavior
squad migrate # interactive: detects current state, proposes migration squad migrate --to sdk # explicit: convert markdown-only to SDK-First squad migrate --to markdown # reverse: strip TS config, keep markdown as source of truth squad migrate --dry-run # preview what would change
squad migrate --to sdk flow:
- Read existing .squad/team.md, .squad/routing.md, .squad/agents/*/charter.md
- Parse team roster, routing rules, agent definitions, casting config
- Generate squad.config.ts with defineSquad() builder syntax that reproduces the current state
- Validate: run squad build --check to confirm generated markdown matches existing
- Output: Migration complete. Your squad.config.ts is the new source of truth.
What gets migrated:
| Source | Target |
|---|---|
| .squad/team.md roster | defineTeam({ members: [...] }) |
| .squad/agents/*/charter.md | defineAgent({ name, role, ... }) per agent |
| .squad/routing.md rules | defineRouting({ rules: [...] }) |
| .squad/ceremonies.md | defineCeremony() entries |
| .squad/casting/policy.json | defineCasting() block |
What is preserved (NOT migrated):
- decisions.md - append-only, stays as-is
- agents/*/history.md - personal knowledge, stays as-is
- orchestration-log/, log/ - append-only archives
Subsumes
- The existing squad upgrade --migrate-directory (.ai-team/ to .squad/) should become squad migrate --from ai-team
- Issue Future: Formal \squad migrate\ command (informed by PR #199) #231 (community feedback requesting formal migrate command)
Files to Change
- New: packages/squad-cli/src/cli/commands/migrate.ts
- New: packages/squad-sdk/src/config/migrate.ts (parsing + generation logic)
- packages/squad-cli/src/cli/cli-entry.ts - wire the command
- packages/squad-cli/src/cli/commands/migrate-directory.ts - refactor into new migrate command
- Docs: docs/sdk-first-mode.md - add migration section
Acceptance Criteria
- squad migrate --to sdk generates valid squad.config.ts from existing markdown
- squad build --check passes after migration (round-trip fidelity)
- squad migrate --dry-run shows preview without writing
- squad migrate --from ai-team replaces upgrade --migrate-directory
- Preserves decisions, history, and logs untouched
- Tests cover: fresh markdown to SDK, ai-team to squad, already-SDK (no-op)
- Documentation updated
Deferred from v0.8.21 to avoid release risk. Related: #249 (init --sdk), #231 (original community request).
Activity
github-actions commentedon Mar 7, 2026
📋 Assigned to Fenster (Core Dev)
Issue: #250 — feat: standalone squad migrate command for SDK-First conversion
Fenster will pick this up in the next Copilot session.
github-actions commentedon Mar 7, 2026
🏗️ Squad Triage — Keaton (Lead)
Issue: #250 — feat: standalone squad migrate command for SDK-First conversion
Assigned to: Hockney (Tester)
Reason: Issue relates to testing/quality work
@copilot evaluation: No strong capability match — routed to squad member.
Team roster:
squad:keatonsquad:verbalsquad:fenstersquad:hockneysquad:mcmanussquad:kujansquad:ediesquad:kobayashisquad:fortiersquad:rabinsquad:baersquad:redfootsquad:strauszsquad:saulsquad:kovashsquad:marquezsquad:cherittosquad:breedansquad:natesquad:waingrosquad:ralphsquad:copilotbradygaster commentedon Mar 7, 2026
✅ Implemented in commit 412ce58 on dev.
What shipped:
Files changed:
Tests: 13 new tests in \ est/migrate.test.ts\ covering all 3 migration paths + dry-run. All 3768 tests passing.
— Edie 👩💻
feat: SDK-first squads (#249, #250, #255) + docs (#251)
docs(ai-team): SDK-First implementation completed
feat: memory management + cross-platform terminal (github#249, github…