docs: comprehensive SDK-First mode documentation (init, migrate, build)

Summary

The SDK-First mode documentation needs a comprehensive update to cover the full lifecycle: initialization, authoring, building, and migration. Current docs are spread across multiple files with gaps in the init-to-SDK and migrate-to-SDK paths.

What Needs Documenting

1. SDK-First Init Path (depends on #249)

How to start a new project in SDK-First mode (squad init --sdk)
What gets generated and why
Relationship between squad.config.ts (source of truth) and .squad/ (generated output)

2. Migration Path (depends on #250)

How to convert an existing markdown-only squad to SDK-First
squad migrate --to sdk workflow
What changes, what's preserved, how to validate

3. Builder API Reference

All 8 builder functions with full type signatures and examples
defineSquad, defineTeam, defineAgent, defineRouting, defineCeremony, defineHooks, defineCasting, defineTelemetry
Common patterns and gotchas

4. Build Pipeline

squad build command in detail
squad build --check for CI validation
Protected files (never overwritten)
Config discovery order (squad/index.ts, squad.config.ts, squad.config.js)

5. Decision Tree

When to use which mode:

New project, wants type safety -> squad init --sdk
Existing squad, wants to upgrade -> squad migrate --to sdk
Simple project, markdown is fine -> squad init (default)

Files to Update

docs/sdk-first-mode.md - main SDK-First guide (already 705 lines, needs restructuring)
docs/reference/sdk.md - API reference
docs/reference/config.md - currently outdated, references old defineConfig()
docs/get-started/migration.md - add SDK migration path
README.md - add SDK-First quick start section

Acceptance Criteria

Complete init-to-SDK documentation path
Complete migrate-to-SDK documentation path
Builder API reference with all 8 functions documented
Build pipeline documentation (squad build, --check, --dry-run)
Decision tree: which mode to choose
docs/reference/config.md updated to current builder syntax
All code examples are tested/verified

Deferred from v0.8.21. Blocked by #249 (init --sdk) and #250 (migrate command) for full coverage.

📋 Assigned to McManus (DevRel)

Issue: #251 — docs: comprehensive SDK-First mode documentation (init, migrate, build)

McManus will pick this up in the next Copilot session.

For Copilot coding agent: If enabled, this issue will be worked automatically.
Otherwise, start a Copilot session and say:
McManus, work on issue #251

🏗️ Squad Triage — Keaton (Lead)

Issue: #251 — docs: comprehensive SDK-First mode documentation (init, migrate, build)
Assigned to: Hockney (Tester)
Reason: Issue relates to testing/quality work

@copilot evaluation: No strong capability match — routed to squad member.

Team roster:

Keaton (Lead) → label: squad:keaton
Verbal (Prompt Engineer) → label: squad:verbal
Fenster (Core Dev) → label: squad:fenster
Hockney (Tester) → label: squad:hockney
McManus (DevRel) → label: squad:mcmanus
Kujan (SDK Expert) → label: squad:kujan
Edie (TypeScript Engineer) → label: squad:edie
Kobayashi (Git & Release) → label: squad:kobayashi
Fortier (Node.js Runtime) → label: squad:fortier
Rabin (Distribution) → label: squad:rabin
Baer (Security) → label: squad:baer
Redfoot (Graphic Designer) → label: squad:redfoot
Strausz (VS Code Extension) → label: squad:strausz
Saul (Aspire & Observability) → label: squad:saul
Kovash (REPL & Interactive Shell) → label: squad:kovash
Marquez (CLI UX Designer) → label: squad:marquez
Cheritto (TUI Engineer) → label: squad:cheritto
Breedan (E2E Test Engineer) → label: squad:breedan
Nate (Accessibility Reviewer) → label: squad:nate
Waingro (Product Dogfooder) → label: squad:waingro
Ralph (Work Monitor) → label: squad:ralph
@copilot (Coding Agent) → label: squad:copilot

To reassign, remove the current squad:* label and add the correct one.

✅ Implemented in commit 412ce58 on dev.

What shipped:

\docs/sdk-first-mode.md\ expanded with: decision tree (markdown vs SDK vs migrate), init --sdk section, migration guide, defineSkill() reference
\docs/reference/config.md\ updated from old defineConfig() to new defineSquad() builder syntax
All code examples verified against actual builder types

Coverage:

Init-to-SDK path documented ✅
Migrate-to-SDK path documented ✅
Builder API reference (all 9 builders including defineSkill) ✅
Decision tree: which mode to choose ✅
Config reference updated to current syntax ✅

— McManus 📝

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…

Navigation Menu

Repository navigation

docs: comprehensive SDK-First mode documentation (init, migrate, build) #251

Summary

What Needs Documenting

1. SDK-First Init Path (depends on #249)

2. Migration Path (depends on #250)

3. Builder API Reference

4. Build Pipeline

5. Decision Tree

Files to Update

Acceptance Criteria

📋 Assigned to McManus (DevRel)

🏗️ Squad Triage — Keaton (Lead)

@copilot evaluation: No strong capability match — routed to squad member.

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

docs: comprehensive SDK-First mode documentation (init, migrate, build) #251

Description

Summary

What Needs Documenting

1. SDK-First Init Path (depends on #249)

2. Migration Path (depends on #250)

3. Builder API Reference

4. Build Pipeline

5. Decision Tree

Files to Update

Acceptance Criteria

Activity

github-actions commented on Mar 7, 2026

📋 Assigned to McManus (DevRel)

github-actions commented on Mar 7, 2026

🏗️ Squad Triage — Keaton (Lead)

@copilot evaluation: No strong capability match — routed to squad member.

bradygaster commented on Mar 7, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions