NexFlow: Defining AI developer teams with YAML manifests

NexFlow proposes describing AI-assisted developer teams not through agent behavior alone, but through how the team itself is specified before anything runs. Project identity, roles, permissions, context sources, and memory scopes are captured explicitly in YAML manifest files that can live in a repository, pass through code review, and be validated against JSON Schemas—replacing dependence on hidden prompts and unwritten team conventions. Files such as project.yaml, agents.yaml, permissions.yaml, capabilities.yaml, context.yaml, and memory.yaml turn decisions that would otherwise be implicit into reviewable artifacts.

A central design choice is the separation between capabilities.yaml and permissions.yaml: a capability defines that an action exists, while permissions determine who may use it, whether it's denied, or whether it requires human approval. This means technical access to a tool does not imply authorization to use it—guarding against the common mistake of conflating tool access with permission.

The minimal-team example shows a single human maintainer paired with a documentation agent under conservative autonomy settings, while the software-team example presents a more realistic setup with implementation, QA, human reviewer, and documentation agents, complete with explicit approval gates for code review and dependency changes. tasks.yaml, workflow.yaml, and handoffs.yaml model how work is broken into stages and how responsibility transfers between participants, since real risk often emerges at the boundaries between actions rather than within a single action.

For engineering teams integrating AI agents into production workflows, this manifest-based approach turns permission and approval review into a concrete, auditable exercise. Team design shifts from vague claims like 'we have a smart coding agent' to explicitly written roles, capabilities, and boundaries.