Generated Files

Reference for all files generated by the actor export pipeline during nexus pull.

When you run nexus pull, the CLI generates configuration files from the canonical actor registry in the Nexus backend. These files are workspace artifacts -- they are generated, not source-controlled.

Overview

The export pipeline produces the following files:

File	Location	Purpose
`AGENTS.md`	`.nexus/AGENTS.md`	Agent policy document with actor role definitions, skills, and directives
`actors.json`	`.nexus/actors.json`	Machine-readable actor registry for the project
`*.md` (per actor)	`.nexus/actors/<slug>.md`	Individual actor profile documents
`opencode.json`	Repository root	OpenCode agent/subagent configuration (if adapter is enabled)

All files under .nexus/ are automatically excluded from Git. The opencode.json at the repository root may be committed depending on your project conventions.

AGENTS.md

The AGENTS.md file is the primary agent policy document. In actor-based mode, it contains:

---
type: agent-policy
scope: repo
project: PROJECT-NAME
project_id: <uuid>
status: active
source: nexus-platform
---

# ACTIVE AGENTS

- agent-id (PRIMARY)

# AGENT ROLE DEFINITION

## agent-id (PRIMARY)
Role: <primary actor title>

You are responsible for:
- <domain 1>
- <domain 2>
- ...

### Assigned Skills

#### Skill Name (`command-slug`)
<skill description>

<details>
<summary>Skill instructions</summary>
<full skill content>
</details>

The AGENTS.md format includes:

YAML frontmatter with project metadata
Active agents list with primary marker
Role definition derived from the primary actor's identity
Assigned skills with full instruction content (expanded in details blocks)
Project directives materialized from the project's directive set
Confidentiality rules derived from the project and customer classification

actors.json

The actors.json file contains a machine-readable representation of all actors assigned to the project:

{
  "version": 1,
  "project_id": "<uuid>",
  "actors": [
    {
      "slug": "security-architect",
      "display_name": "Security Architect",
      "title": "Senior Security Architect",
      "mode": "primary",
      "domains": ["security", "infrastructure", "compliance"],
      "permission_profile": "builder",
      "route_alias": "premium-security-reasoning",
      "recommended_skills": ["nexus-init", "nexus-sec-scan", "nexus-code-review"],
      "recommended_plugins": ["nexus-compaction-plus", "nexus-cost-control"]
    },
    {
      "slug": "backend-engineer",
      "display_name": "Backend Engineer",
      "title": "Backend Development Engineer",
      "mode": "subagent",
      "domains": ["backend", "databases", "api-design"],
      "permission_profile": "builder",
      "route_alias": "zen-balanced",
      "recommended_skills": ["nexus-init", "nexus-code-review", "nexus-deploy-check"],
      "recommended_plugins": ["nexus-compaction-plus"]
    }
  ]
}

This file is consumed by automation tools and CI/CD pipelines that need structured access to the project's actor configuration.

Actor profile files

Each assigned actor gets an individual markdown profile file at .nexus/actors/<slug>.md:

---
slug: security-architect
display_name: Security Architect
title: Senior Security Architect
mode: primary
permission_profile: builder
route_alias: premium-security-reasoning
domains:
  - security
  - infrastructure
  - compliance
---

# Security Architect

Senior Security Architect specializing in security, infrastructure,
and compliance.

## Working Style

Methodical approach with structured output. Prioritizes security
considerations in all reviews and implementations.

## Expertise

- OWASP Top 10 auditing
- Infrastructure security hardening
- Compliance framework alignment (SOC 2, ISO 27001)
- Threat modeling and risk assessment

## Operational Rules

- Always run security scan before deployment
- Flag any credential exposure immediately
- Require ADR for security-relevant architectural changes

These files provide human-readable actor context that agents can reference during sessions.

opencode.json

When the OpenCode adapter is enabled as an export target, nexus pull generates or updates opencode.json with actor entries:

{
  "agents": {
    "security-architect": {
      "model": "anthropic/claude-opus-4-8",
      "name": "Security Architect",
      "description": "Senior Security Architect specializing in security, infrastructure, and compliance.",
      "permissions": {
        "edit": true,
        "bash": true,
        "mcp": true
      }
    },
    "backend-engineer": {
      "model": "zen-provider/balanced-model",
      "name": "Backend Engineer",
      "description": "Backend Development Engineer specializing in backend, databases, and API design.",
      "type": "subagent",
      "permissions": {
        "edit": true,
        "bash": true,
        "mcp": true
      }
    }
  }
}

Key mappings:

Actor field	opencode.json field	Notes
`mode: primary`	Top-level agent	The main agent entry
`mode: subagent`	`"type": "subagent"`	Accessible via @mention
`route_alias`	`model`	Resolved to `provider/model` at export time
`permission_profile`	`permissions`	Mapped to OpenCode's permission model

If the permission profile cannot be mapped to OpenCode's permission model, the adapter rejects the export rather than silently downgrading. This prevents actors from accidentally gaining more permissions than intended.

Generation pipeline

The export pipeline follows these steps:

Fetch actors -- retrieve all actors assigned to the project from the Nexus backend
Resolve routes -- look up each actor's route alias in the Model Route catalog, resolve to provider/model
Validate -- check for retired routes (fail), deprecated routes (warn), permission mapping gaps (reject)
Generate AGENTS.md -- assemble the agent policy document from actor profiles, skills, directives
Generate actors.json -- serialize the actor registry to JSON
Generate actor profiles -- write individual markdown files per actor
Run adapters -- for each enabled export target (e.g., OpenCode), generate the runtime config file
Write files -- write all generated files to the workspace

The pipeline is deterministic -- the same actor configuration always produces the same output files.