# How to Implement Custom Agent Teams in aios-core: Complete Developer Guide > Implement custom agent teams in aios-core easily. Define agents workflows and quality gates via YAML bundle files in .aios-core/agent-teams/. Load your automation pipeline seamlessly. - Repository: [SynkraAI/aios-core](https://github.com/synkraai/aios-core) - Tags: how-to-guide - Published: 2026-02-16 --- **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`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/.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: ```yaml # .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: ```bash 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: ```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 ``` ### 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: ```yaml 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: ```bash npm run install # or aios install ``` Once installed, reference the team in any story YAML file using the `team` key: ```yaml team: team-dev-ops ``` When you execute `aios start `, 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`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/development/agent-teams/team-dev-ops.yaml): ```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: ```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`](https://github.com/SynkraAI/aios-core/blob/main/ci-pipeline.yaml) and [`deploy-safety.yaml`](https://github.com/SynkraAI/aios-core/blob/main/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: ```bash $ 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`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/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.