Skip to content

feat: add squad splitting best practices documentation#973

Open
selena-vapi wants to merge 1 commit intoVapiAI:mainfrom
selena-vapi:tasker/DEVREL-551-squad-splitting-best-practices
Open

feat: add squad splitting best practices documentation#973
selena-vapi wants to merge 1 commit intoVapiAI:mainfrom
selena-vapi:tasker/DEVREL-551-squad-splitting-best-practices

Conversation

@selena-vapi
Copy link

Description

  • Add new documentation page fern/squads/splitting-best-practices.mdx with comprehensive best practices for designing and configuring multi-assistant squads
  • Add navigation entry in fern/docs.yml positioned between "Handoff tool" and "Examples" in the Squads section
  • Content covers: when to use squads vs single assistants, identifying functional boundaries, architecture patterns (hub-and-spoke, linear pipeline, language router), handoff configuration with model-specific patterns, context engineering options, variable extraction, system prompt best practices with template, all four transfer modes, configuration tips (assistant overrides, tools:append, member overrides, silent transfers), seven common pitfalls with remediation, and card links to all existing squad example pages
  • All 5 JSON code blocks validated as syntactically correct; all internal cross-reference links verified against existing files
  • 374 lines of MDX content + 3 lines YAML change = 377 total lines (within 500-line limit)
  • Closes DEVREL-551

Testing Steps

  • Run the app locally using fern docs dev or navigate to preview deployment
  • Ensure that the changed pages and code snippets work
  • Navigate to the Squads section and confirm "Splitting best practices" appears between "Handoff tool" and "Examples"
  • Verify all internal links on the new page resolve correctly (links to /squads, /squads/handoff, /squads/silent-handoffs, /squads/examples/*, /api-reference/squads/create)
  • Verify anchor links to handoff.mdx sections work (#multiple-destinations, #variable-extraction, #system-prompt-best-practices)

Create a comprehensive guide at fern/squads/splitting-best-practices.mdx
covering when and how to split assistants into squads. Includes decision
criteria, architecture patterns (hub-and-spoke, linear pipeline, language
router), handoff configuration, system prompt design, transfer modes,
configuration tips, common pitfalls, and links to real-world examples.

Add navigation entry in docs.yml between "Handoff tool" and "Examples".

Closes DEVREL-551

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant