YAML manifests for AI developer teams

Most conversations about AI agents start with behavior.

The agent writes code, opens a pull request, updates a ticket, stores memory, calls an MCP server, or moves a task through a workflow. At least, that is usually where the discussion begins.

The behavior matters.

But there is a layer before behavior that is easy to skip: how the team itself is described before anything runs.

That description has to answer practical questions about participants, roles, allowed actions, approval points, context sources, memory scopes, and handoffs between implementation, validation, review, and documentation.

If these things are not described explicitly, an AI-assisted system may still work.

It will simply depend on hidden prompts, local conventions, product-specific settings, and human memory.

NexFlow takes a different approach: describe an AI developer team through a set of YAML manifests.

Not because YAML is special by itself.

But because YAML can live in a repository, be read by humans, go through code review, and be validated against JSON Schemas.

What a manifest set is

A NexFlow manifest set is a group of YAML files that describe a project and its team together.

Most files start with shared fields:

specVersion: "0.1"
kind: AgentSet
metadata:
  project: example-project

specVersion says which version of the specification the file follows. kind says what the manifest describes. metadata connects the file to a project and gives people additional context.

In the current draft model, the core set looks like this:

• project.yaml - Project identity, maintainers, policies, and manifest locations.
• agents.yaml - Humans, agents, roles, responsibilities, skills, capabilities, permissions, context access, and memory access.
• agent-definitions.yaml - Versioned behavioral definitions that assemble model, prompt, retrieval, permission, context, memory, autonomy, and extension references.
• workflow.yaml - Work stages, steps, dependencies, approval points, and events.
• tasks.yaml - Tasks, owners, participants, dependencies, artifacts, and acceptance criteria.
• handoffs.yaml - Transfers of responsibility between participants.
• permissions.yaml - Rules that allow, deny, or require approval for capabilities.
• capabilities.yaml - Capabilities, risk levels, categories, and audit guidance.
• context.yaml - Context sources, source types, access modes, classification, and refresh rules.
• memory.yaml - Memory scopes, retention, ownership, visibility, sensitivity, and consumers.
• providers.yaml - Provider-neutral model classes and provider selection constraints.
• model-profiles.yaml - Provider-neutral model selection profiles and review expectations.
• prompt-sets.yaml - Versioned prompt material and safety review status.
• retrieval-profiles.yaml - Retrieval expectations for declared context sources.
• events.yaml - Event names, expected data, retention, and audit requirements.
• extensions.yaml - Integration namespaces, lifecycle state, and required capabilities.

At first glance, that may look like a lot of files.

But the goal is not to make configuration look impressive.

The goal is to stop hiding different questions inside one prompt, one agent profile, or one product settings page.

The smallest useful team

The examples/minimal-team directory shows the smallest useful NexFlow shape: one human maintainer and one agent that helps with documentation.

The project policy is conservative:

defaultAutonomy: ask_before_changes
policies:
  requireReview: true
  secretHandling: Raw secrets are never stored in manifests.
  networkAccess: Disabled unless a task explicitly requests approval.
  destructiveActions: Human approval required.

Even this small example already says a lot.

The documentation agent is not described as a magical autonomous employee. It prepares documentation changes for maintainer review. It can read declared context and draft a change. But that does not mean it has broad authority over the project or access to arbitrary actions.

In agents.yaml, its responsibilities, capabilities, permissions, context, memory, and autonomy level are explicit:

- 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

For review, this is much more useful than a promise that the agent is smart.

You can see the boundaries in which it is expected to work.

Capabilities and permissions are separate

One of the key NexFlow patterns is the separation between capabilities.yaml and permissions.yaml.

A capability describes which action exists at all.

A permission decides who may use that action, whether it is denied, or whether it requires approval.

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

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

But the existence of that capability does not allow an agent to modify files.

Authorization appears in 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 distinction matters.

If an action is technically available, that does not mean every participant may perform it. For an AI developer team, this boundary protects against a common mistake: treating tool access as permission.

A software team example

The examples/software-team directory is closer to a normal engineering workflow. It includes an implementation agent, a QA agent, a human reviewer, and a documentation agent.

The project describes approval gates:

approvalGates:
  - id: code_review
    description: Reviewer approval required before merge.
    requiredApprovers:
      - reviewer
  - id: dependency_approval
    description: Maintainer approval required before installing dependencies.
    requiredApprovers:
      - reviewer

The implementation agent is described around limited changes, and its actions still go through permission rules. The QA agent is described around validation evidence. The reviewer remains the human authority for approval and acceptance. The documentation agent updates user-facing materials after review.

That is much clearer than saying: "we have a coding agent."

The manifests separate roles:

• implementation prepares changes;
• QA collects validation evidence;
• the reviewer makes decisions;
• the documentation agent updates materials.

And they separately describe actions:

• reading the repository;
• modifying files;
• creating branches;
• running commands;
• creating pull requests;
• approving changes;
• updating documentation.

When a team is described this way, review becomes concrete.

You can open the manifests and ask: should execute_command require approval? Should create_pull_request belong to the reviewer? Is memory scoped too broadly? Is context access narrow enough?

Tasks and handoffs

Agents are not enough.

A team also needs a model of work.

In tasks.yaml, you can describe units of work: implementing a feature, testing, review, or documentation updates. Each task can have an owner, participants, dependencies, artifacts, required capabilities, and acceptance criteria.

workflow.yaml connects tasks into stages, for example:

implementation -> validation -> review -> documentation

handoffs.yaml shows how responsibility moves between participants.

That is important because real risk often appears not inside a single action, but at the boundary between actions: who handed over the task, what counts as done, which artifacts must be attached, and who accepts the next step.

Context and memory are not hidden in the prompt

The manifests also make context sources and memory rules visible.

Context answers the question: where may an agent get information from?

That may include repositories, documentation, issues, notes, knowledge bases, web sources, or MCP servers. A source should have a type, access mode, classification, freshness expectations, and limits.

Memory answers a different question: what may the system keep after the task is finished?

Memory may be ephemeral, task-scoped, project-scoped, team-scoped, user-scoped, or organization-scoped. The wider the memory scope, the more careful the write rules should be.

If these boundaries are not described, an agent may look useful, but the team will not understand which information it used or what remained in the system afterward.

This is a specification, not a runtime

It is important not to confuse manifests with execution.

YAML files do not run agents by themselves. They do not isolate credentials. They do not enforce permissions. They do not create provider integrations.

NexFlow currently describes the language, schemas, examples, and rules that future tools could use to say honestly what they support.

But a specification is useful before a runtime exists.

It lets a team see the work model in advance: who participates, which actions exist, what is allowed, where a human is required, which sources may be read, which memory is acceptable, and which events should be auditable.

That does not make an AI developer team magical.

It makes it reviewable.