How to Create Custom Squads for Non-Development Domains in aios-core

Create custom AIOS Squads for any business domain by defining domain-specific agents and tasks in a structured manifest, then generate the squad using the Squad Generator CLI or Node.js API.

AIOS Squads are self-contained packages that extend far beyond software development into any operational domain. Whether you are building automation for marketing campaigns, financial analysis, or HR onboarding, this guide shows you how to create custom Squads for non-development domains using the aios-core framework.

Understanding AIOS Squad Architecture

A Squad is organized into five distinct layers that separate configuration from implementation. When you create custom Squads for non-development domains, you populate these layers with domain-specific assets:

Layer	Purpose	Location
Manifest	Declares name, version, AIOS compatibility, and component inventory	./squads/<my-squad>/squad.yaml
Config	Domain standards and inheritance rules	./squads/<my-squad>/config/ or docs/framework/
Agents	Persona definitions encoding domain expertise	./squads/<my-squad>/agents/*.md
Tasks	Task-first workflows exposing business logic	./squads/<my-squad>/tasks/*.md
Optional	Workflows, templates, tools, scripts, data	Adjacent directories

Three Ways to Create Custom Squads

The aios-core framework provides three distinct paths for creating custom Squads, depending on your starting point and domain complexity.

Guided Design Path

Use this approach when you have existing domain documentation—such as PRDs, strategy documents, or process specifications—and want AI-assisted recommendations for agent and task structure.

The *design-squad command analyzes your documentation and produces a .squad-design.yaml blueprint. You then instantiate the Squad with *create-squad <name> --from-design.

Direct Creation Path

Choose this method when you already know the specific agents and tasks your domain requires. This path bypasses the design phase and generates the directory structure immediately.

Use *create-squad <name> [--template <type>] with built-in templates such as basic, etl, or agent-only. After creation, use *extend-squad to incrementally add components.

Blueprint-Driven Path

This advanced approach uses a custom design file produced by the Squad Designer or an external process. Specify the blueprint explicitly with *create-squad <name> --from-design <.squad-design.yaml>.

Defining Domain-Specific Components

To create custom Squads for non-development domains, you must encode business expertise into Agents and operational workflows into Tasks.

Creating Specialized Agents

Agents are Markdown files that define personas with domain knowledge. For a marketing domain, you might create agents/marketing-strategist.md containing:

• Campaign goal definitions
• KPI measurement methodologies
• Channel-specific tactics
• Brand voice guidelines

Building Business Logic Tasks

Tasks expose the Squad's functionality through task-first workflows. A finance Squad might include tasks/generate-budget-report.md that:

1. Accepts fiscal period parameters
2. Invokes the finance-analyst agent
3. Aggregates data according to domain rules
4. Returns a structured report

Configuration Inheritance for Enterprise Standards

When creating custom Squads for non-development domains, you can enforce organization-wide standards through configuration inheritance.

If your project maintains central standards in docs/framework/ (such as CODING-STANDARDS.md or communication protocols), set --config-mode extend during Squad creation.

The SquadGenerator class in .aios-core/development/scripts/squad/squad-generator.js detects these project configurations via detectProjectConfigs and references them in the manifest rather than duplicating files. This keeps your Squad lightweight while maintaining alignment with central policy.

Validating Your Custom Squad

Before deploying a Squad for production use in non-development domains, validate its structure and compliance.

Run *validate-squad <name> from the CLI, or programmatically invoke the SquadValidator class from .aios-core/development/scripts/squad/squad-validator.js.

Validation checks include:

• Manifest schema compliance against squad-schema.json
• Directory structure presence
• Task format compliance with TASK-FORMAT-SPEC-V1
• Agent definition completeness

Distributing Squads Across Domains

Once validated, distribute your custom Squad through three channels:

• Local: Retain in ./squads/ for private project use
• Public: Execute *publish-squad to submit to the aios-squads GitHub repository
• Marketplace: Run *sync-squad-synkra to publish via the Synkra API

The Squad Loader (.aios-core/development/scripts/squad/squad-loader.js) can consume Squads from any source, enabling reuse across unrelated AIOS projects regardless of domain.

Code Examples

CLI: Guided Design for a Marketing Squad

# Activate the squad-creator agent

@squad-creator

# Design from existing marketing documentation

*design-squad --docs ./docs/marketing/strategy.md

# Review the generated .squad-design.yaml, then instantiate

*create-squad marketing-squad --from-design

CLI: Direct Creation with Custom Template

@squad-creator
*create-squad finance-squad --template agent-only

Add a task manually:

*extend-squad finance-squad --add task \
  --name generate-budget-report \
  --agent finance-analyst

Programmatic Creation (Node.js)

const { SquadGenerator } = require('./.aios-core/development/scripts/squad/squad-generator');

const gen = new SquadGenerator();

(async () => {
  const result = await gen.generate({
    name: 'finance-squad',
    description: 'Budgeting & financial analysis tools',
    template: 'agent-only',
    configMode: 'extend',
    includeAgent: true,
    includeTask: false,
    projectRoot: process.cwd(),
  });

  console.log('Squad created at:', result.path);
  console.log('Files written:', result.files);
})();

Programmatic Validation

const { SquadValidator } = require('./.aios-core/development/scripts/squad/squad-validator');

(async () => {
  const validator = new SquadValidator({ strict: true });
  const { valid, errors, warnings } = await validator.validate('./squads/finance-squad');

  if (!valid) {
    console.error('Squad invalid:', errors);
    process.exit(1);
  }
  console.log('Squad is valid! Warnings:', warnings);
})();

Key Implementation Files

• .aios-core/development/agents/squad-creator.md – Agent definition and command reference for squad creation
• .aios-core/development/scripts/squad/squad-generator.js – Core generator with isValidSquadName, generateSquadYaml, and detectProjectConfigs functions
• .aios-core/development/scripts/squad/squad-validator.js – Schema and compliance validation logic
• .aios-core/development/scripts/squad/squad-loader.js – Cross-project squad consumption and loading
• docs/guides/squads-guide.md – Comprehensive human-readable guide
• docs/examples/squads/basic-squad/squad.yaml – Minimal reference manifest

Summary

• AIOS Squads use a five-layer architecture separating manifest, config, agents, tasks, and optional components to encapsulate domain logic.
• Create custom Squads for non-development domains using three paths: guided design (*design-squad), direct creation (*create-squad), or blueprint-driven generation (--from-design).
• Encode domain expertise through specialized agent personas in ./squads/<name>/agents/ and operational workflows in ./squads/<name>/tasks/.
• Enforce enterprise standards by setting --config-mode extend to inherit configurations from docs/framework/ rather than duplicating standards.
• Validate Squads programmatically via SquadValidator or CLI *validate-squad before distribution through local, GitHub, or Synkra marketplace channels.

Frequently Asked Questions

Can I create a Squad for any business domain, not just software development?

Yes. AIOS Squads are domain-agnostic packages designed to encapsulate any operational expertise. Whether you need marketing campaign management, financial forecasting, HR onboarding workflows, or legal document review, you create custom Squads by defining domain-specific agents (personas with specialized knowledge) and tasks (workflows that execute business logic). The architecture in squad.yaml supports any domain through its flexible component structure.

How do I validate my custom Squad before deploying it to production?

Run the *validate-squad <name> CLI command or programmatically invoke the SquadValidator class from .aios-core/development/scripts/squad/squad-validator.js. The validator checks manifest schema compliance against squad-schema.json, verifies directory structure presence, ensures TASK-FORMAT-SPEC-V1 compliance for every task file, and confirms agent definition completeness. Set strict: true in the validator options to fail on warnings that might indicate domain logic inconsistencies.

What is the difference between guided design and blueprint-driven Squad creation?

Guided design (*design-squad) is an interactive process where you provide domain documentation—such as PRDs, strategy papers, or process specifications—and the AI analyzes these inputs to recommend agent personas and task structures, outputting a .squad-design.yaml file. Blueprint-driven creation (*create-squad --from-design) assumes you already have a design file (whether AI-generated or hand-crafted) and skips the recommendation phase, proceeding directly to directory generation and manifest creation via the SquadGenerator class.

Can enterprise coding standards be enforced across all Squads in my organization?

Yes. When creating a Squad, set --config-mode extend (the default in many templates). This triggers the detectProjectConfigs function in .aios-core/development/scripts/squad/squad-generator.js to scan your project's docs/framework/ directory for organization-wide standards such as CODING-STANDARDS.md or communication protocols. Rather than copying these files into the Squad directory, the generator references them in squad.yaml, ensuring all domain-specific Squads remain synchronized with central policy updates while keeping the packages lightweight.

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