---
title: How products are authored
---

# How products are authored

> _Most engineers should build Nexus products by writing validated files, not by editing framework internals._

The authoring model is intentionally narrow. Fresh graduates and most engineers should express product intent through files. Staff engineers and platform owners maintain the runtime internals.

## The authored files

| File | What it declares |
|---|---|
| `NEXUS.md` | Pack identity, purpose, outputs, and high-level rules |
| `AGENTS.md` | Agents, their roles, model ids, tools, and structured output schemas |
| `SKILLS.md` | Reusable instruction fragments and constraints |
| `TEAMS.md` | Reusable multi-agent teams, coordination rules, and artifact output contracts |
| `WORKFLOWS.md` | Ordered or conditional flows across validated agents, teams, or workflows |
| `TOOLS.md` | Requested capability access through Pinax |
| `EVALS.md` | Eval fixtures, thresholds, and required checks |
## What all us should do

- Describe the product and its bounded job.
- Choose from approved model ids.
- Request governed capabilities through `TOOLS.md`.
- Define structured outputs.
- Add eval fixtures and expectations.

## What all of should not do

- Write workflow-local Python hooks.
- Call LiteLLM directly.
- Decide auth or token strategy inside the pack.
- Construct source URLs, artifact ids, or lineage links in model text.
- Create raw shell tools by default.
- Treat tool declarations as self-approved access grants.

## Why the pack is strict

The pack grammar is constrained so product definitions remain reviewable, validated, and distinct from runtime implementation code.

## Database-backed authored definitions

Nexus also supports database-backed authored definitions for clinicians and platform template flows.

| Source | Who uses it | Storage | Runtime path |
|---|---|---|---|
| File-authored pack | Engineers | Version-controlled files | Loaded directly by `n1r.core` |
| Database-authored definition | Platform, clinic, or clinician owners | DocumentDB | Normalized by `n1r.core` into the same runtime model |
Clinicians should not edit framework internals. They should edit only the constrained authoring surface for their own agents.