#Project structure

An agent-bundle project is an ordinary Node package with one extra file at the root and a conventional src/ tree. Nothing here is mandatory: conventions fill the config in when it is silent, and config always wins when both describe the same thing.

#The layout

my-plugin/
├── agent-bundle.config.ts     # project identity, targets, and policy
├── package.json               # authoritative release version and package identity
├── assets/                    # static files copied byte-for-byte into every artifact
└── src/
    ├── skills/<name>/SKILL.md # one Skill per directory, with its own resources
    ├── commands/*.md          # host slash-command documents
    ├── rules/*.mdc            # host rule documents
    ├── hooks/*.ts             # lifecycle hook handlers referenced from config
    ├── mcp/<server-id>.ts     # a handwritten stdio MCP server entry
    ├── mcp/<server>/          # or a generated server, one module per route
    │   ├── tools/*.tsx
    │   ├── resources/*.tsx
    │   ├── prompts/*.tsx
    │   ├── apps/*.tsx         # browser MCP Apps compiled to self-contained HTML
    │   └── layout.tsx         # optional per-server layout around this server's routes
    ├── scripts/<name>.ts      # artifact scripts (.tsx renders through the Agent renderer)
    ├── cli.ts                 # a single package bin
    ├── cli/**/*.ts            # or a routed CLI, where nesting is the command path
    ├── index.ts               # the library entry
    ├── layout.tsx             # optional shared layout around every rendered route
    ├── state.ts               # project state definition
    └── providers/<name>.ts    # request-context providers

#What each root means

Route and package entry conventions match .ts and .tsx files exactly; the state convention is specifically src/state.ts. Discovered entries carry provenance.kind: 'conventional' in the normalized model, so agent-bundle inspect tells you whether a file was picked up by convention or claimed by config.

#Config versus conventions

The config holds what no single file can own — project identity, target selection, and policy:

import { 
const defineConfig: (config: AgentBundleConfig | ConfigFactory) => AgentBundleConfig | ConfigFactorydefineConfig } from 'agent-bundle/config';

export default 
function defineConfig(config: AgentBundleConfig | ConfigFactory): AgentBundleConfig | ConfigFactorydefineConfig({
  
AgentBundleConfig.plugin: AgentBundlePluginConfigplugin: { 
AgentBundlePluginConfig.description?: string | undefineddescription: 'Evidence-backed project tools.', 
AgentBundlePluginConfig.name: stringname: 'my-plugin' },
  
AgentBundleConfig.targets?: string[] | undefinedtargets: ['portable', 'codex', 'claude'],
});

Add an explicit declaration only when you need something the convention cannot express — a different path, a target restriction, or an opt-out:

import { 
const defineConfig: (config: AgentBundleConfig | ConfigFactory) => AgentBundleConfig | ConfigFactorydefineConfig } from 'agent-bundle/config';

export default 
function defineConfig(config: AgentBundleConfig | ConfigFactory): AgentBundleConfig | ConfigFactorydefineConfig({
  
AgentBundleConfig.plugin: AgentBundlePluginConfigplugin: { 
AgentBundlePluginConfig.description?: string | undefineddescription: 'Evidence-backed project tools.', 
AgentBundlePluginConfig.name: stringname: 'my-plugin' },
  
AgentBundleConfig.scripts?: Readonly<Record<string, AgentBundleScriptInput>> | undefinedscripts: {
    // Restricted to one target, so it cannot ride the convention.
    'detect-risk': { 
AgentBundleScriptEntry.entry: stringentry: './src/scripts/detect-risk.ts', 
AgentBundleScriptEntry.targets?: readonly string[] | undefinedtargets: ['portable'] },
  },
  
AgentBundleConfig.targets?: string[] | undefinedtargets: ['portable', 'codex', 'claude'],
});

Source validation reports informational nudges — never errors — when a project shows a pre-convention pattern: AB4730 for a self-connecting stdio entry that a default-exported factory would upgrade to the framework lifecycle shell, and AB4731 / AB4732 / AB4733 when src/cli.ts, src/index.ts, or src/mcp/<server-id>.ts exists but explicit configuration shadows it. The bin: false and lib: false opt-outs stay silent.

#Where output lands

agent-bundle build writes two independent things.

#Host artifacts

One directory per selected target under the artifact root. The CLI defaults that root to artifact/, so it never collides with the package build below; output.distPath or --output moves it:

artifact/
├── agent-bundle.manifest.json # every emitted file with its SHA-256
└── plugin/                    # targets: ['plugin'] — one multi-host bundle
    ├── .claude-plugin/
    ├── .codex-plugin/
    ├── .cursor-plugin/
    ├── bin/<plugin-name>.mjs      # the routed CLI, when src/cli/** exists
    ├── skills/
    ├── hooks/
    ├── mcp/
    ├── scripts/
    ├── assets/
    ├── AGENTS.md
    └── INSTALL.md

Per-host layouts are available as the claude, codex, cursor, and portable targets. agent-bundle.manifest.json sits at the artifact root beside the target directories and records every emitted file with its SHA-256, so artifact validation is content-addressed rather than a guess.

output.distPath moves the artifact root; it never changes the framework-owned layout inside each target. Precedence is the CLI --output, then output.distPath, then the default — artifact for agent-bundle build, which also emits the package build, and dist for the programmatic build() without packageOutputs. Values must be non-empty, project-root-contained relative POSIX paths.

#The npm package build

When the project declares bin/lib — or provides them by convention — the same build also writes the node-consumable package build under dist/:

dist/
├── bin/<name>.js              # self-executing ESM, shebang, executable bit
├── <stem>.js                  # the library entry
└── **/*.d.ts                  # declarations, when lib.dts is on

dist is a mandatory-ignored directory: package outputs never enter project source snapshots or Skill and asset discovery. The two outputs must not overlap: pointing output.distPath or --output at dist on a project with package entries is AB4706. The default already keeps them apart, and spelling it out is harmless:

import { 
const defineConfig: (config: AgentBundleConfig | ConfigFactory) => AgentBundleConfig | ConfigFactorydefineConfig } from 'agent-bundle/config';

export default 
function defineConfig(config: AgentBundleConfig | ConfigFactory): AgentBundleConfig | ConfigFactorydefineConfig({
  
AgentBundleConfig.output?: AgentBundleOutputConfig | undefinedoutput: { 
AgentBundleOutputConfig.distPath?: string | undefined
The artifact output directory of agent-bundle build, relative to the
project root. Defaults to dist. The per-invocation CLI --output flag
still wins, but remains subject to the same project-root containment
check; absolute and external output paths are unsupported.distPath: 'artifact' },
  
AgentBundleConfig.plugin: AgentBundlePluginConfigplugin: { 
AgentBundlePluginConfig.description?: string | undefineddescription: 'A CLI plus a plugin.', 
AgentBundlePluginConfig.name: stringname: 'my-plugin' },
  
AgentBundleConfig.targets?: string[] | undefinedtargets: ['portable', 'claude'],
});

#Next steps

• Configuration model — the full config surface.
• Skills, Hooks, MCP servers and Apps — one page per surface.
• Scripts and assets and Package entries — the rest of the build output.