agent-onboard

agent-onboard

CLI for onboarding and managing target repositories.

agent-onboard creates a small machine-readable and human-readable control surface inside a target repo. In the current 0.0.x line, that surface is a convention/spec plus a reference CLI generator. It is not a sandbox, filesystem wrapper, CI policy engine, or runtime enforcement layer.

The generated files are intended to be read by agents, wrappers, CI hooks, or future runtimes that choose to honor the declared boundaries.

Install

For the 0.0.x line, install with ~0.0.5 so target repos can receive later 0.0.x updates without crossing the 0.1.0 boundary:

npm install --save-dev agent-onboard@~0.0.5

Run without installing:

npx agent-onboard status

Minimal target init

Preview the files that would be created:

npx agent-onboard init --dry-run

Write the minimal target state:

npx agent-onboard init --write

init --write refuses to overwrite existing non-identical files. To intentionally replace existing target-state files:

npx agent-onboard init --write --force

Agent instructions preview

Preview the canonical agent instruction file:

npx agent-onboard agents --preview

Write it to the target repo:

npx agent-onboard agents --write

agents --write writes only:

AGENTS.md

It refuses to overwrite an existing non-identical AGENTS.md unless --force is passed:

npx agent-onboard agents --write --force

Commands

npx agent-onboard status
npx agent-onboard init --dry-run
npx agent-onboard init --write
npx agent-onboard agents --preview
npx agent-onboard agents --write
npx agent-onboard guard --plan
npx agent-onboard guard --check-boundary
npx agent-onboard target-config --schema
npx agent-onboard target-config --template
npx agent-onboard target-config --validate-template
npx agent-onboard target-config --validate [agent-onboard.target.json]
npx agent-onboard target bootstrap --dry-run
npx agent-onboard target bootstrap --write
npx agent-onboard target-instance takeover --dry-run
npx agent-onboard target-instance takeover --write

After install, these command names are available:

agent-onboard status
aob status
create-agent-onboard status

Files written

Dry-run and preview commands write nothing.

init --write writes the complete minimal public target state:

agent-onboard.target.json
.agent-onboard/project.json
.agent-onboard/work-items.json

agents --write writes the public agent instruction surface:

AGENTS.md

The older explicit subcommands remain available:

target bootstrap --write writes:

agent-onboard.target.json

target-instance takeover --write writes:

.agent-onboard/project.json
.agent-onboard/work-items.json

Boundary guard seed

agent-onboard guard --check-boundary is the first narrow public enforcement seed. It reads agent-onboard.target.json from the current target repo root and exits non-zero when that declaration is not the default read-only dry-run boundary.

It passes only when the target config keeps:

requested_mode: target_dry_run
authority_level: L1_read_only_preview
writes_allowed: false
managed_project_commands_allowed: 0
create_agent_onboard_runtime_state: false
install_dependencies: false
run_build_test_deploy: false
publish_or_push: false

Run it before dependency installs, build/test/deploy commands, publish/push operations, or broad write operations:

npx agent-onboard guard --check-boundary

This guard does not sandbox other tools and does not wrap shell commands. It only evaluates the declared boundary and fails closed when the target config is missing, invalid, or permissive.

What the boundary files mean

agent-onboard.target.json declares the target repo's intended operating boundaries, including write policy, dependency-install policy, build/test/deploy policy, publish/push policy, and managed surfaces.

AGENTS.md gives agents a human-readable read order, default forbidden actions, dry-run-first operating mode, and reporting discipline.

In the current 0.0.x line, these fields and instructions are declarative. They do not block other tools by themselves. A separate agent runtime, wrapper, CI hook, or future agent-onboard component must read the files and enforce the declared policy.

The generated config intentionally starts at:

requested_mode: target_dry_run
authority_level: L1_read_only_preview
writes_allowed: false

Passing --write to this CLI only allows this CLI to write the requested public surface files. It does not raise the generated target authority level.

Validation

target-config --schema prints the embedded target config schema.

target-config --template prints the embedded target config template.

target-config --validate-template validates the embedded target config template against that schema and returns non-zero if the template is invalid.

target-config --validate [file] validates an existing target config file. When no file is provided, it validates agent-onboard.target.json in the current directory.

Safety boundaries of this CLI

This version does not:

• install dependencies;
• run builds, tests, deploys, publishes, or pushes;
• modify source files except the requested generated public surface files;
• write files unless --write is passed;
• overwrite existing non-identical target-state or agent-instruction files unless --force is passed;
• enforce filesystem, network, shell, Git, or package-manager policy for other tools.

File meanings

agent-onboard.target.json is the target repo config and boundary declaration.

.agent-onboard/project.json is the runtime identity of the target repo.

.agent-onboard/work-items.json is the initial empty work-item ledger.

AGENTS.md is the human-readable agent instruction surface for the target repo.

Version line

0.0.1 is the first public package version.

0.0.2 adds public repository hygiene and npm/GitHub metadata while staying below the 0.1.0 boundary.

0.0.3 adds the public target config/init surface: top-level init, target config template printing, target config file validation, and default overwrite protection.

0.0.4 adds the public agent instructions / AGENTS.md preview surface with guarded write support.

0.0.5 adds the public boundary guard enforcement seed: guard --plan and guard --check-boundary.

License

Apache-2.0. Copyright 2026 Glogos.