aba-bundle-starter

A template repo for agent bundles — soft configuration for ABA and other Claude-based agents (Claude Code, Codex, OpenClaw, …). Clone this template to create your institution, lab, or personal bundle.

gh repo create my-lab/aba-bundle --template kharchenkolab/aba-bundle-starter --private

Open the clone in your editor, fill in AGENTS.md + a few rules/*.md + maybe a skill or two, push, and point ABA at it:

export ABA_LAB_BUNDLE=/path/to/your/checkout

That's it. The agent now reads your bundle.

---

Inert by default

A fresh clone of this template contributes nothing to the agent's runtime behavior. AGENTS.md is empty; the template lives in AGENTS.md.example. Every example rule/skill lives in an examples/ subdir the loader doesn't walk, and settings.* are .example-suffixed. You opt in to each piece by copying a .example file (or moving content out of examples/) into its active name. See AUTHORING.md for the activation pattern + composition rules.

This means a lab can gh repo create --template ... and start authoring incrementally, with zero risk that the unedited template quietly shifts agent behavior in production.

What's a bundle?

A bundle is a directory the agent reads at startup to learn how to behave in your environment. It's separate from the agent's code so you can edit prose, not Python, when you want the agent to change its mind. ABA layers several bundles in a fixed precedence (broadest → narrowest):

system  →  institution  →  lab/group  →  user
                                          ↑
                                       narrowest wins on conflicts

This repo is a template for ANY of those layers — the structure is the same; what differs is where you mount it.

Anatomy

.
├── AGENTS.md                 EMPTY by default (canonical policy file)
├── AGENTS.md.example         Templated policy with sample sections; cp to AGENTS.md to activate
├── CLAUDE.md                 @AGENTS.md bridge (resolves to empty until you fill AGENTS.md)
├── AUTHORING.md              Human-only authoring guide (not read by the loader)
├── README.md                 This file
├── rules/
│   ├── required/.gitkeep     Empty; required rules go here
│   └── examples/             Example rules (loader does NOT walk here)
│       └── EXAMPLE_topic.md
├── skills/
│   └── examples/             Example skills (loader does NOT walk here)
│       ├── EXAMPLE_skill/SKILL.md
│       └── flat-example.md
├── commands/.gitkeep         Claude Code slash commands (ABA ignores)
├── hooks/.gitkeep            Claude Code hooks (ABA ignores)
├── settings.json.example     Rename to settings.json to activate
├── settings.yaml.example     Rename to settings.yaml to activate
├── .claude -> .              Self-symlink so .claude/skills/* resolves to ./skills/*
├── setup.sh                  Optional: adds .openclaw → ., .codex → . cross-agent symlinks
└── tests/validate.sh         Smoke validator (checks inertness + frontmatter)

Activation pattern

Everything is in an examples/ subdir or .example suffix. To activate a piece of content, copy it out:

# Activate the canonical policy file (recommended starting point)
cp AGENTS.md.example AGENTS.md
# edit AGENTS.md — fill in conventions, domain context, reminders

# Activate a rule
cp rules/examples/EXAMPLE_topic.md rules/figure_style.md
# edit, commit, push

# Activate the folder skill
cp -r skills/examples/EXAMPLE_skill skills/my-recipe
# rename + edit SKILL.md, commit, push

# Activate the flat skill
cp skills/examples/flat-example.md skills/my-quick-recipe.md

# Activate settings
cp settings.yaml.example settings.yaml
cp settings.json.example settings.json

After each activation, validate with ./tests/validate.sh and bounce the ABA backend (or python -m core.bundle.cli inspect --reload).

Full composition rules, override semantics, and field reference: see AUTHORING.md.

Verifying inertness

The smoke validator (tests/validate.sh) checks that:

1. AGENTS.md exists and is empty (or has only whitespace).
2. CLAUDE.md is the @AGENTS.md bridge.
3. No top-level rules/*.md (i.e. no active overrideable rules).
4. No top-level skills/*.md and no skills/<folder>/SKILL.md.
5. Active settings files (settings.{json,yaml} without .example) are absent OR parse cleanly.
6. Example content is present under rules/examples/ and skills/examples/.
7. .claude self-symlink resolves correctly.

You can also confirm inertness against the actual ABA loader:

ABA_LAB_BUNDLE=$PWD ABA_GROUP=test python -m core.bundle.cli inspect

The output should show lab scope present, but policy: N scope(s) for N = (system + any other you've actively populated), NOT increased by this bundle.

Cross-agent symlinks

.claude → . ships pre-committed. To also expose this bundle to OpenClaw and Codex, run:

./setup.sh

This adds .openclaw → . and .codex → . symlinks.

Further reading

• Authoring guide: AUTHORING.md
• ABA bundle spec: misc/bundle.md
• Layering algorithm: misc/bundle_layering.md
• agentskills.io standard: https://agentskills.io