Primary agents

The primary.* fields shape the normal selectable primary agents: alpha, architect, developer, and orchestrator. They affect how the agents present themselves and what extra user or project rules they receive.

These fields do not configure model routing. Use Model routing for that.

Defaults

Identity and persona

{
  "primary": {
    "identity": "neutral",
    "persona": "professional",
    "useRoleName": false
  }
}

Allowed values:

• identity: "neutral" or "jarvis".
• persona: "professional" or "mythic".
• useRoleName: true or false.

Keep useRoleName: false unless you explicitly want display names to change with persona. Stable names are easier for habits, scripts, and documentation.

Output icons

{
  "primary": {
    "outputIcons": "emoji"
  }
}

Allowed values:

• "emoji" — readable icon blocks in modern terminals.
• "nerdfont" — compact glyphs for Nerd Font terminals.
• false — plain text output without icon framing.

User traits

primary.userTraits describes how agents should communicate with you. It is usually global because it follows the user across projects.

Object form is best when keys carry meaning:

{
  "primary": {
    "userTraits": {
      "seniority": "Experienced engineer; prefer direct trade-offs over basic explanations.",
      "language": "Conversation in the user's language; code, comments, and documentation in English."
    }
  }
}

Array form is useful for short independent notes:

{
  "primary": {
    "userTraits": ["Prefers concise answers first.", "Works primarily in a Linux terminal."]
  }
}

Do not invent traits just because they look helpful. They should reflect real user preferences.

User requirements

primary.userRequirements are user-wide rules. They are honored only from global squad.json.

{
  "primary": {
    "userRequirements": [
      "Challenge risky assumptions before implementing changes.",
      "Prefer the smallest correct solution over broad rewrites."
    ]
  }
}

For larger rule sets, use sections:

{
  "primary": {
    "userRequirements": {
      "communication": ["Be direct and practical.", "Call out uncertainty explicitly."],
      "security": ["Warn before destructive operations.", "Never ignore hardcoded credentials."]
    }
  }
}

Project requirements

primary.projectRequirements are repository-specific rules. They are honored only from project .opencode/squad.json files.

{
  "primary": {
    "projectRequirements": [
      "Use bun commands instead of npm commands.",
      "Run `bun run check` before reporting implementation work as complete."
    ]
  }
}

Use this field for framework conventions, test commands, architecture constraints, language rules, and other requirements that should travel with the repository.