Why AI developer teams need explicit YAML manifests for clarity

AI agents today can write code, open pull requests, or update tickets—behaviors that usually dominate the conversation. Yet the layer beneath that behavior—the team itself—often remains unexamined. How do participants interact? What actions are allowed? Where do approvals occur? What context can agents access? NexFlow tackles these questions by describing an AI developer team through structured YAML manifests rather than buried prompts or product settings.

NexFlow’s approach isn’t about YAML’s syntax; it’s about making team definitions version-controlled, reviewable, and machine-validatable. These manifests live in a repository, pass through code review, and adhere to JSON Schemas—ensuring consistency and transparency across projects.

How a NexFlow manifest set works

A NexFlow manifest set consists of multiple YAML files that collectively describe a project and its AI developer team. Each file follows a consistent structure with shared fields like specVersion, kind, and metadata to connect the manifest to a specific project and provide context.

The core manifest set includes:

• project.yaml – Defines project identity, maintainers, policies, and locations of other manifests.
• agents.yaml – Lists humans, agents, roles, responsibilities, skills, permissions, context access, and memory access.
• agent-definitions.yaml – Versioned behavioral definitions that combine model selection, prompts, retrieval, permissions, context, memory, autonomy, and extensions.
• workflow.yaml – Outlines work stages, steps, dependencies, approval points, and events.
• tasks.yaml – Specifies tasks, owners, participants, dependencies, artifacts, and acceptance criteria.
• handoffs.yaml – Documents responsibility transfers between participants.
• permissions.yaml – Establishes rules to allow, deny, or require approval for capabilities.
• capabilities.yaml – Describes capabilities, risk levels, categories, and audit guidance.
• context.yaml – Details context sources, access modes, classification, and refresh rules.
• memory.yaml – Defines memory scopes, retention, ownership, visibility, and sensitivity.
• providers.yaml – Specifies provider-neutral model classes and selection constraints.
• model-profiles.yaml – Outlines provider-neutral model selection profiles and review expectations.
• prompt-sets.yaml – Contains versioned prompt material and safety status.
• retrieval-profiles.yaml – Sets retrieval expectations for declared context sources.
• events.yaml – Lists event names, data requirements, retention, and audit needs.
• extensions.yaml – Defines integration namespaces, lifecycle states, and required capabilities.

While the number of files may seem extensive, the goal isn’t complexity—it’s eliminating hidden assumptions. Instead of embedding team structure in a single prompt or agent profile, NexFlow makes every decision explicit and reviewable.

A minimal AI developer team example

The examples/minimal-team directory offers a straightforward illustration: a single human maintainer and one agent tasked with drafting documentation updates. The project policy is conservative, emphasizing control and review:

project.yaml
specVersion: "0.1"
kind: AgentSet
metadata:
  project: minimal-docs
  maintainers:
    - human-maintainer
policies:
  defaultAutonomy: ask_before_changes
  requireReview: true
  secretHandling: "Raw secrets are never stored in manifests."
  networkAccess: "Disabled unless a task explicitly requests approval."
  destructiveActions: "Human approval required."

In this setup, the documentation agent doesn’t operate as a fully autonomous entity. It drafts documentation changes but prepares them for maintainer review. Its responsibilities, permissions, and boundaries are explicitly defined in agents.yaml:

agents.yaml
- id: docs-agent
  displayName: Docs Agent
  role: technical_writer
  description: "Drafts documentation updates for maintainer review."
  permissions:
    - docs_write_with_review
  capabilities:
    - read_repository
    - modify_documentation
    - read_context
  contextAccess:
    - repository
    - docs
  memoryAccess:
    - ephemeral
    - task
  autonomyLevel: ask_before_changes

This clarity transforms vague assurances like "the agent is smart" into concrete expectations about where and how it operates.

Separating capabilities from permissions

NexFlow enforces a critical distinction: capabilities define what actions exist, while permissions determine who can use them, whether approval is required, or if access is denied. This separation prevents a common pitfall—assuming that tool access equals permission.

For example, modify_documentation might be a medium-risk capability:

capabilities.yaml
- id: modify_documentation
  description: "Modify documentation files."
  risk: medium
  category: repository
  requiresApprovalByDefault: true
  auditRecommended: true

But having the capability doesn’t grant an agent access. That control lives in permissions.yaml:

permissions.yaml
- id: docs_write_with_review
  description: "Docs agent may draft documentation changes after review."
  subjects:
    - docs-agent
  capabilities:
    - read_repository
    - read_context
    - modify_documentation
  effect: approval_required
  approvalGate: human_review
  conditions:
    - "Documentation changes only."

This structure ensures that even when actions are technically feasible, they remain subject to deliberate oversight.

Scaling to real-world software teams

The examples/software-team directory provides a more realistic engineering workflow, including roles like developers, reviewers, and QA agents. Tasks follow defined stages: implementation, validation, review, and documentation. Each step includes approval gates, context access rules, and memory scopes tailored to the team’s needs.

By formalizing these processes, NexFlow enables AI agents to operate not as black boxes but as transparent, accountable members of the team—bound by the same rules as their human counterparts.

As AI integration deepens in software development, clarity in team definition will become as essential as code itself. NexFlow’s YAML manifests don’t just describe AI agents—they redefine the foundation of collaborative AI development.