How to Implement Custom Agent Teams in aios-core: Complete Developer Guide

You implement custom agent teams by creating YAML bundle files in the .aios-core/development/agent-teams/ directory, defining agents, workflows, and quality gates, then referencing the team identifier in your story files to automatically load the configured automation pipeline.

The SynkraAI/aios-core framework organizes AI agents into reusable teams that enforce specific quality gates and automation workflows. When you implement custom agent teams, you create modular YAML specifications that the installer discovers automatically and the CLI activates during story execution.

Understanding the Agent Team Architecture

Canonical Directory Location

Agent teams reside in the .aios-core/development/agent-teams/ directory. While the logical name agent-teams can resolve to a top-level folder, the canonical location is under development/ to align with the framework's structure (e.g., development/agents/, development/skills/).

According to the source code in packages/installer/src/installer/aios-core-installer.js, the installer maps the logical path agent-teams to development/agent-teams during the resolution phase.

How the Installer Discovers Teams

The framework uses the .aios-core/install-manifest.yaml to track team definitions. The installer reads every *.yaml file under the resolved agent-teams folder and registers the team in the internal registry:

# .aios-core/install-manifest.yaml (excerpt)

- path: development/agent-teams/team-all.yaml
- path: development/agent-teams/team-fullstack.yaml
- path: development/agent-teams/team-qa-focused.yaml

When you run npm run install or aios install, the new team becomes available immediately without manual registry updates.

Structure of a Custom Agent Team YAML

A team bundle is a single YAML file containing several top-level sections. The framework validates these sections during the setup phase.

Core Sections

• bundle: Human-readable metadata including name, icon, and description.
• agents: List of agent identifiers (e.g., dev, qa, github-devops) that belong to the team.
• workflows: Paths relative to .aios-core/workflows/ that the team executes automatically.
• tasks: Paths relative to .aios-core/tasks/ for ad-hoc invocations.
• purpose: Free-form text describing the team's objective.
• when_to_use: Bullet list of specific lifecycle moments (e.g., "Before marking stories Ready for Review").

Quality Gates and Integrations

• quality_gates: Structured checks for pre_commit, pre_pr, pre_merge, and pre_deployment. Each gate specifies the trigger, agent, checks (commands), and threshold (pass criteria).
• coderabbit_integration: Optional configuration for CodeRabbit scans (e.g., enabled: true).

Step-by-Step Guide to Implement Custom Agent Teams

Step 1: Create the Team Definition File

Navigate to .aios-core/development/agent-teams/ and create a new YAML file. Use a descriptive prefix like team- followed by your team purpose:

touch .aios-core/development/agent-teams/team-dev-ops.yaml

Step 2: Define Agents and Workflows

Edit the YAML file to include the bundle metadata and list the agents your team requires. Reference existing workflow files from the .aios-core/workflows/ directory:

bundle:
  name: Team DevOps
  icon: 🚀
  description: Automates CI/CD pipelines and deployment safety checks.

agents:
  - github-devops
  - devops

workflows:
  - ci-pipeline.yaml
  - deploy-safety.yaml

Step 3: Configure Quality Gates

Add the quality_gates section to enforce automated checks at specific lifecycle points. Define the triggering agent, the commands to run, and the success threshold:

quality_gates:
  pre_pr:
    trigger: Before creating PR
    agent: github-devops
    checks:
      - coderabbit --prompt-only --base main
      - npm run lint
      - npm test
    threshold: 0 CRITICAL, lint PASS, tests PASS

Step 4: Register and Activate the Team

Save the file and run the installer to register the team in the framework's internal registry:

npm run install

# or

aios install

Once installed, reference the team in any story YAML file using the team key:

team: team-dev-ops

When you execute aios start <story-name>, the CLI automatically loads the associated agents, executes the defined workflows, and injects the quality gate checks into the story lifecycle.

Practical Code Examples

Minimal DevOps Team Configuration

This complete example demonstrates a production-ready team bundle located at .aios-core/development/agent-teams/team-dev-ops.yaml:

bundle:
  name: Team DevOps
  icon: 🚀
  description: Automates CI/CD pipelines and deployment safety checks.

agents:
  - github-devops
  - devops

workflows:
  - ci-pipeline.yaml
  - deploy-safety.yaml

tasks:
  - infra-provision.md

purpose: |
  Provides end-to-end automation for continuous integration, delivery,
  and post-deployment validation.

when_to_use:
  - After a story reaches "Ready for Review"
  - During PR creation
  - Before production deployment

quality_gates:
  pre_pr:
    trigger: Before creating PR
    agent: github-devops
    checks:
      - coderabbit --prompt-only --base main
      - npm run lint
      - npm test
    threshold: 0 CRITICAL, lint PASS, tests PASS

Referencing Teams in Story Files

To activate a team for a specific story, add the team key to the story YAML:

# .aios-core/stories/feature-login.yaml

title: "Login UI"
team: team-dev-ops          # matches the file name without the .yaml extension

steps:
  - description: "Implement login page"
    owner: dev
    status: pending

When you run aios start feature-login, the CLI will:

1. Load the github-devops and devops agents.
2. Execute ci-pipeline.yaml and deploy-safety.yaml at the appropriate gates.
3. Enforce the pre_pr quality gate defined in the team.

Verifying Team Registration via CLI

After installation, confirm your team is available:

$ aios teams list
Available agent teams:
 • team-all
 • team-fullstack
 • team-ide-minimal
 • team-no-ui
 • team-qa-focused
 • team-dev-ops   ← your custom team

The teams list command reads the registry built by the installer, which scans the agent-teams directory defined in packages/installer/src/installer/aios-core-installer.js.

Summary

• Location matters: Place custom team YAML files in .aios-core/development/agent-teams/ to align with the framework's canonical structure.
• Installer automation: The aios-core-installer.js maps the logical path agent-teams to the development directory and auto-discovers new YAML files during npm run install.
• Required structure: Every team needs a bundle section (metadata) and agents list; optionally include workflows, tasks, quality_gates, and coderabbit_integration.
• Activation: Reference the team filename (without extension) in story YAML files using the team key, then run aios start to load agents and enforce gates automatically.

Frequently Asked Questions

What is the difference between .aios-core/agent-teams/ and .aios-core/development/agent-teams/?

The canonical location is .aios-core/development/agent-teams/. According to the installer logic in packages/installer/src/installer/aios-core-installer.js, the logical name agent-teams resolves to the development/agent-teams subdirectory. While creating a top-level agent-teams folder may work due to path aliasing, placing files under development/ ensures compatibility with the framework's directory conventions and documentation references.

Can I reference multiple agent teams in a single story?

No, the story YAML specification supports a single team key per story. When you declare team: team-name, the CLI loads that specific team's agents, workflows, and quality gates into the story lifecycle. If you need capabilities from multiple teams, you should create a composite team YAML that includes the union of agents and workflows from both teams, or refactor your teams to be more inclusive.

How do quality gates enforce checks automatically?

Quality gates defined in the quality_gates section (such as pre_pr, pre_merge, or pre_deployment) specify a trigger condition, an agent responsible for execution, and a list of checks (shell commands or scripts). When the story reaches the corresponding lifecycle phase—for example, before creating a PR—the CLI invokes the specified agent to run the checks. The threshold field defines pass criteria (e.g., "0 CRITICAL, lint PASS"), and the story cannot proceed until these criteria are met.

Is CodeRabbit integration mandatory for custom agent teams?

No, the coderabbit_integration section is optional. You can create fully functional custom teams without enabling CodeRabbit scans. When present, this section typically contains an enabled: true flag and optional configuration parameters that trigger CodeRabbit analysis during quality gate execution. Teams focused on local development or internal tooling may omit this section entirely while still leveraging all other framework features like custom workflows and agent orchestration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}