After a 2.5 hour session you accidentally close your coding agent terminal mid session. The output is there, the commits are there, but something important is gone.
That synergy that you spent hours to build up.
You reopen the console and hope you two can start over, but it feels like now you are strangers. The agent is now "Somebody that you used to know."
No, this is not an intro of a light love novel, it's the usual experience with coding agents. Coding agents are stateless by design so each and every new session is a new beginning.
The resume illusion
Some agents have --resume functionality. Claude Code has it. Codex has it. Gemini CLI has it. It's useful, but it has limitations.
--resume only replays the conversation log. It doesn't restore the loaded and curated mental model - the understanding of your project's topology, constraints, and current state that the agent built up over those 2.5 hours.
Resume gives you only the transcript. Not the understanding.
Two primitives I already had
Over the last few weeks I wrote about two separate ideas:
In The backbone.yml Pattern, I introduced a YAML manifest that maps your project's topology - agents, directories, configs, schemas. Information. The agent reads it once and knows where everything is. No more exploration tax.
In Mermaid for Workflows, I showed how flowcharts give agents reliable step-by-step processes to follow. Process. Structured syntax that sticks out in a context window full of prose, backed by research showing agents follow flowcharts more reliably than natural language.
Backbone tells the agent what exists. Workflows tell the agent how to operate.
But I was using them separately. I'd tell Claude "read the backbone" at session start, then invoke workflows as needed. Manual orchestration. Every session, same ritual.
Why am I doing this separately? Isn't context just Information + Process ?
Read the map. Follow the process. Produce a working mental model. Every session, one command.
That's /bootstrap.
What /bootstrap does
One command. Two modes.
First run (no backbone exists): scans the project, detects agents and structure, generates a backbone.yml, then synthesizes a context report.
Every subsequent run (backbone exists): reads the backbone, maps agents, loads constraints, checks project state, and produces a mental model.
Both modes use the diagram + prose combo from the mermaid post - flowcharts for the branching, prose for the reasoning behind each step.
The output looks like this:
Bootstrap complete.
Project: my-app v1.2.0 (branch: feature/auth)
Agents: claude (CLAUDE.md), copilot (.github/copilot-instructions.md)
Structure: src/, tests/, docs/, config/
Navigation:
Agent config → backbone.agents.{agent}
Project dirs → backbone.paths.{key}
Schemas → backbone.schemas.{name}
Operations:
Build → npm run build
Test → npm test
Deploy → ./scripts/deploy.sh
Constraints:
- Never modify config/production.yml directly
- Always run tests before committing
State: v1.2.0, 3 unreleased changes (auth module)
After this, the agent knows where things are, how to operate, what's off limits, and what's in progress. No exploration. No guessing.
Seed mode: the smart first run
Most bootstrapping tools drop a blank template and say "fill this in." That's 0% useful on day one.
/bootstrap scans first, generates second. It detects agents across the ecosystem:
| Pattern | Agent |
|---|---|
CLAUDE.md |
Claude |
AGENTS.md |
Codex |
.github/copilot-instructions.md |
Copilot |
.cursorrules |
Cursor |
.windsurfrules |
Windsurf |
.clinerules |
Cline |
.aider* |
Aider |
.continue/config.json |
Continue |
It maps directories, finds configs, detects build/test workflows from package.json, Makefile, CI configs. The generated backbone is 70-80% correct from the scan alone.
The remaining 20% - semantic connections, domain concepts - gets marked with # TODO: refine so you know exactly where to invest review time. Verified topology. Flagged guesses. One command.
The skill structure
I built this as an Agent Skill - the open standard for packaging reusable instructions across agents:
bootstrap/
SKILL.md # Entry point - frontmatter + instructions
workflows/
seed.md # Scan + generate (mermaid flowchart)
bootstrap.md # Read + synthesize (mermaid flowchart)
templates/
backbone.yml # Starter backbone shape
See the two primitives? The templates/backbone.yml is the information layer from the backbone post. The workflows/*.md files are the process layer from the mermaid post - complete with flowcharts, key decisions, and edge cases.
/bootstrap is their love child. One skill that reads both primitives and turns them into a loaded context.
Cross-agent by design
The SKILL.md format is an open standard created by Anthropic and now adopted by OpenAI, Google, Cursor, and others. A skill authored once works across 30+ agents - the format is filesystem-based, not API-dependent.
Drop the bootstrap/ folder into .claude/skills/ for Claude Code, .agents/skills/ for Codex CLI, or wherever your agent looks. Same skill, same result.
This matters because the bootstrap concept isn't Claude-specific. Every coding agent is stateless. Every agent benefits from a loaded mental model at session start. The problem is universal, so the solution should be too.
What changes after bootstrap
Before bootstrap, every session starts with the agent exploring. After bootstrap, every session starts with the agent understanding.
-
No more
find/ls/greploops to discover what the backbone already maps - No more wrong assumptions about where configs live
-
No more repeated corrections - "no, the tests are in
spec/, nottests/" - No more context poisoning from exploration artifacts cluttering the window
The agent reads the backbone, follows the workflow, synthesizes the context, and starts working. Every session. In seconds.
The progression
Looking back at this series, the progression is clear:
In the capability levels post - what maturity looks like for instruction files.
In the backbone.yml post - give the agent a map (information).
In the mermaid post - give the agent reliable processes (workflows).
Now - combine both into a single command that loads a mental model.
Map + Process = Understanding. That's the whole idea.
Try it
The bootstrap skill will be published as a cross-agent compatible Agent Skill in the Reporails skills repo this week.
In the meantime, the pattern works even without the skill:
- Create a
backbone.ymlmapping your project (template here) - Add a workflow with a mermaid flowchart for session initialization (approach here)
- Start every session with: "Load the backbone, follow the bootstrap workflow, and tell me what you understand"
That's manual bootstrap. The skill just makes it /bootstrap.
Don't start a session. Bootstrap it.
This post is part of the Reporails series. Previous: Mermaid for Workflows.
Top comments (0)