Agent onboarding and bootstrap

Every new agent begins with a context problem. It needs enough information to act correctly, but reading the entire workspace is slow, noisy, and expensive. A bootstrap path solves this with progressive disclosure.

The bootstrap path

A new workspace session follows a predictable reading order:

1. Bootstrap instructions — how the workspace is organized and how agents are expected to operate.
2. Workspace README — the overall model, conventions, and shared boundaries.
3. Current goals — the small set of priorities that matter now.
4. Project index — which projects exist and which one owns the task.
5. Project brief — the selected project’s purpose, state, constraints, and missing context.
6. Project README — setup and implementation guidance when code work is required.
7. Tasks, decisions, and landmarks — deeper context loaded only when relevant.

Bootstrap
    ↓
Workspace orientation
    ↓
Current priorities
    ↓
Selected project
    ↓
Task-specific context

The ordering moves from cheap and general to detailed and specific. It prevents an agent from exploring deeply before it knows which project and goal matter.

What BOOTSTRAP.md should do

The bootstrap file is a signpost, not an encyclopedia. It should state:

• the minimum reading order;
• the project-folder convention;
• important safety and editing rules;
• where durable decisions and task state belong;
• how to find reusable workspace procedures;
• what to do when project ownership or scope is unclear.

If the bootstrap file contains every project detail, every session pays to read information it does not need. Changing project facts also makes the supposedly stable entry point unreliable.

Idempotent onboarding

Bootstrap should be safe to repeat. Running it again means rereading current orientation and reporting what changed—not creating duplicate files, rewriting indexes, or generating another onboarding report inside the workspace.

This matters because agents may resume after a long pause, context compaction, or work by another collaborator. The same path should restore their footing without special knowledge of the previous conversation.

Saving tokens without starving context

Reducing token use does not mean withholding essential information. It means paying for detail only when detail becomes relevant.

• Keep workspace goals short and current.
• Make the project index descriptive enough to route the task.
• Keep project briefs concise and link outward to deeper records.
• Search for specific concepts before opening entire directories.
• Read task and decision logs selectively.
• Use landmarks for expensive, localized context.
• Avoid pasting generated summaries when the canonical file is already available.

The objective is not the smallest possible prompt. It is the smallest reliable path to correct action.

A successful onboarding report

After bootstrapping, the agent should be able to state briefly:

• which workspace and project it identified;
• which orientation files it read;
• the current goal or nearest priority;
• the likely next task;
• any missing information that genuinely blocks work.

If the response becomes a full workspace audit, the onboarding path is doing too much.