How to Manage Agent Dependencies Specified in YAML Headers in aios-core

AIOS agents declare required artefacts in a dependencies section within the YAML header, which the framework validates through a wizard and resolves at runtime via a directed-acyclic graph built by the registry loader.

Managing agent dependencies specified in YAML headers in aios-core ensures that workflows, tasks, templates, and scripts are available before an agent activates. The framework validates these declarations during development through the wizard and orchestrates their loading at runtime through the core registry system in .aios-core/core/registry-loader.js.

Structure of the Dependencies Header

The dependencies section in an agent YAML file supports six optional categories. Each category lists artefacts required by the agent:

dependencies:
  workflows:
    - myagent-build-ui.yaml
    - myagent-deploy.yaml
  tasks:
    - myagent-generate-docs.md
    - myagent-run-tests.md
  templates:
    - myagent-report-tmpl.yaml
  checklists:
    - myagent-release-checklist.md
  data:
    - myagent-data.json
  scripts:
    - myagent-setup.js
  tools:
    - myagent-cli-tool.yaml

Naming Conventions

AIOS enforces strict naming rules to distinguish between agent-specific and shared artefacts.

Agent-specific artefacts must prefix with the agent's id as defined in the YAML header. According to .aios-core/product/templates/agent-template.yaml lines 9-15, all dependencies specific to an agent must follow this naming convention.

Shared artefacts live in the global namespace and must not use the agent prefix. These are stored in shared folders such as tasks/ or scripts/. See .aios-core/product/templates/agent-template.yaml lines 24-27 for the distinction between local and shared namespaces.

Declaring Dependencies in Agent YAML Files

A complete agent definition combines the header with persona and command definitions. Below is a real-world example from docs/guides/squad-examples/simple-agent.yaml:

# myagent.yaml – Documentation Assistant

agent:
  name: "Docs-Helper"
  id:   "myagent"
  title: "Documentation Assistant"
  icon: "📚"

persona:
  role:   "Technical Writer"
  style:  "concise"
  focus:  "API docs, READMEs"

commands:
  - help: "Show available commands"
  - generate-readme: "Create a README from source"
  - document-api:   "Generate API reference"

dependencies:
  workflows:
    - myagent-readme-generator.yaml
    - myagent-api-documenter.yaml
  tasks:
    - myagent-validate-docs.md
  scripts:
    - myagent-cleanup.js

Notice that all local artefacts use the myagent- prefix, adhering to the naming convention enforced by the validation layer in tests/unit/wizard/validation/dependency-validator.test.js.

Validating and Updating Dependencies with the Wizard

The AIOS wizard validates dependency declarations before runtime. Follow this workflow when adding or updating dependencies:

1. Create the artefact using the appropriate naming convention (prefixed for local, unprefixed for shared).

2. Open the agent YAML and add the reference under the correct sub-key (workflows, tasks, scripts, etc.).

3. Run the wizard using npm run sync:ide or aios wizard. The wizard performs three critical checks:

   • Verifies the file exists on disk.
   • Confirms the path resides inside permitted folders (.aios-core/development/...).
   • Updates the entity-registry (.aios-core/data/entity-registry.yaml) so the orchestrator recognizes the new relationship.

4. Commit the new files and the updated agent YAML to version control.

The validation logic that enforces these rules is implemented in tests/unit/wizard/validation/dependency-validator.test.js, which guards against missing files, naming violations, and incorrect categorization.

Runtime Resolution and Execution

When an agent activates, the core orchestration layer resolves dependencies through a directed-acyclic graph (DAG). The process operates in four stages:

Parse YAML – The agent-loader.js reads the header and extracts the dependencies object:

// core/orchestration/agent-loader.js (excerpt)
const { dependencies } = yaml.load(agentYaml);
if (dependencies?.workflows) {
  dependencies.workflows.forEach(wf => loadWorkflow(wf));
}

Build Graph – The registry-loader.js constructs a DAG to ensure artefacts load in the correct order, resolving "used-by" links and lazy-loading shared resources as defined in agent-config-requirements.yaml.

Lazy-Load Resources – Shared sections are loaded on-demand according to the global lazy-loading strategy specified in .aios-core/data/agent-config-requirements.yaml.

Execute – The workflow-executor.js runs the required workflows and tasks in dependency order.

If resolution fails due to a missing file or circular reference, the orchestrator aborts and emits a clear error identifying the offending artefact.

Common Pitfalls and Solutions

Issue	Symptom	Solution
Wrong prefix	Validation error: "Dependency not found in shared namespace"	Remove the agent prefix and place the file under tasks/ or other shared folders.
Circular dependency	Orchestrator throws "Dependency cycle detected"	Collapse the cycle by moving common steps to a shared script or checklist.
Missing file	Wizard prints "Missing …"	Add the file to the repository or remove the entry from the agent YAML.
Incorrect category	Runtime loads the artefact as the wrong type and fails to parse	Move the entry to the correct sub-key (e.g., workflows instead of tasks).

The wizard's unit tests in tests/unit/wizard/validation/dependency-validator.test.js protect against all of these scenarios during the development phase.

Quick Reference Code Snippets

Minimal dependency block (single workflow):

dependencies:
  workflows:
    - myagent-main.yaml

Adding a shared script:

dependencies:
  scripts:
    - cleanup-temp-files.js   # shared – no myagent- prefix

Programmatic lookup (core implementation):

// core/orchestration/agent-loader.js (excerpt)
const { dependencies } = yaml.load(agentYaml);
if (dependencies?.workflows) {
  dependencies.workflows.forEach(wf => loadWorkflow(wf));
}

Summary

• Declare dependencies in the YAML header under the dependencies key, using sub-keys for workflows, tasks, templates, checklists, data, scripts, and tools.
• Follow naming conventions – prefix agent-specific artefacts with the agent id; leave shared artefacts unprefixed.
• Validate changes by running the wizard (npm run sync:ide or aios wizard), which checks file existence, paths, and updates .aios-core/data/entity-registry.yaml.
• Runtime resolution occurs through registry-loader.js, which builds a DAG to load artefacts in the correct order, with lazy-loading governed by agent-config-requirements.yaml.

Frequently Asked Questions

What happens if I forget to prefix an agent-specific dependency?

The wizard validation will fail with an error indicating the dependency was not found in the shared namespace. According to tests/unit/wizard/validation/dependency-validator.test.js, the system checks that agent-specific artefacts use the correct id prefix. To fix this, either add the agent prefix to the filename or move the file to a shared folder and remove the prefix from the reference.

Can an agent depend on artefacts from another agent?

Yes, but only on shared artefacts that reside in the global namespace. As defined in .aios-core/product/templates/agent-template.yaml lines 24-27, shared artefacts do not use an agent prefix and can be referenced by any agent. Agent-specific artefacts (with prefixes) are private to that agent and cannot be referenced by others to maintain encapsulation.

How does the runtime handle circular dependencies between workflows?

The orchestrator detects cycles during the graph construction phase in registry-loader.js. If workflow A depends on task B, which in turn references workflow A, the system throws a "Dependency cycle detected" error and aborts activation. To resolve this, refactor common steps into a shared script or checklist that both workflows can reference without creating a circular reference.

What is the difference between the validation stage and runtime resolution?

Validation occurs during development when you run the wizard (npm run sync:ide), which executes the checks in tests/unit/wizard/validation/dependency-validator.test.js to verify file existence, naming conventions, and path permissions. Runtime resolution happens when the agent activates, where core/orchestration/agent-loader.js parses the YAML and registry-loader.js builds the dependency graph to load artefacts in the correct order.

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