Cross-Agent Project Bootstrap

A small, project-agnostic bootstrap for giving AI coding agents the same instructions and shared, version-controlled Memory.

Install it as a global CLI, or clone this repository. One initialization prompt prepares the project for all supported agents.

Install

npm i -g agent-ready-bootstrap

Requires Node.js 18+.

Add the bootstrap to a project

cd /path/to/project
arb init

Existing bootstrap files are skipped. To overwrite them:

arb init --force

You can also pass a target directory:

arb init /path/to/project
arb init --force /path/to/project

Review the copied files and manually merge any instruction files that were already present, then ask the agent:

Read and execute init.prompt.

For an existing project, the agent discovers facts from source, configuration, tests, and CI. It initializes only the AI bootstrap files and does not modify product code or install dependencies.

Start a new project

Create an empty repository, apply the bootstrap, then initialize with an agent:

mkdir my-project && cd my-project
git init
arb init

Or clone this repository as the new project root:

git clone <BOOTSTRAP_URL> my-project
cd my-project

Open the repository root in your AI coding agent and send exactly:

Read and execute init.prompt.

Because the repository has no product yet, the agent starts a short guided interview instead of stopping. It asks about the product, users, first journey, product type, constraints, required capabilities, quality bar, and smallest useful milestone.

Short answers are enough. For any question, you may answer:

I don't know

or:

recommend

The agent then explains the decision, recommends one sensible option, and offers at most two alternatives with short tradeoffs. If you do not yet have a project idea, it proposes three small ideas.

After discovery, the agent shows a project brief and scaffold plan. It waits for your confirmation before creating product files or installing anything. After confirmation, it creates the smallest approved project, verifies what it can, and initializes AGENTS.md and memory.md.

If you decline the plan or want planning only, no product files are created and the bootstrap remains uninitialized.

Example:

Agent: What kind of product do you want to build?
You: A small task tracker for my team.

Agent: Do you have a preferred stack?
You: I don't know. Recommend one.

Agent: [explains one recommendation and up to two alternatives]

The interview and confirmation are intentionally interactive. Do not expect a single prompt to make unreviewed product and technology choices.

CLI reference

arb init [--force] [targetDir]
arb --help
arb --version

arb init copies only the AI bootstrap files listed in the file map below. It does not copy README.md, package.json, or other package tooling.

Initialization behavior

| Repository state | What init.prompt does | | --- | --- | | Empty or bootstrap-only | Interviews you, recommends missing choices, asks for confirmation, scaffolds the approved first milestone, then initializes AI files | | Existing project | Inspects repository evidence and initializes only AI files |

In both modes, uncertain choices remain visible as assumptions until you approve them. The agent must not invent commands, deploy, create paid resources, or connect external services during initialization.

Shared Memory

memory.md is the only shared cross-session Memory file.

Every supported entry point either loads it directly or gives an always-on instruction to read it. At the beginning of a session, the agent reads AGENTS.md, reads memory.md, and verifies relevant Memory claims against the current repository.

Memory is updated only when work creates durable information:

• a material project-state change;
• a durable technical decision;
• a reusable verified discovery; or
• a handoff for unfinished work.

It is not a chat transcript. It must never contain secrets, credentials, personal data, raw logs, guesses, or machine-specific temporary paths.

The Current state section is updated in place. Detailed handoffs are kept newest first and limited to ten entries, so Memory remains concise and consistent.

Automatic agent support

| Agent | Automatically discovered entry point | | --- | --- | | OpenAI Codex | AGENTS.md | | Cursor Agent and Cursor CLI | AGENTS.md and .cursor/rules/project.mdc | | Claude Code CLI | CLAUDE.md imports AGENTS.md and memory.md | | Gemini CLI | GEMINI.md imports AGENTS.md and memory.md | | Google Antigravity | .agents/rules/project.md imports both canonical files | | Windsurf Cascade | root AGENTS.md and .windsurf/rules/project.md | | GitHub Copilot | root AGENTS.md and .github/copilot-instructions.md | | Devin | root AGENTS.md |

There is no universal instruction filename implemented by every AI product. This repository therefore uses AGENTS.md as the canonical cross-agent contract and adds thin native entry points for agents that provide one.

Automatic discovery still depends on opening the repository root, leaving custom instructions enabled, and granting any file-import approval requested by the agent.

Official references:

• OpenAI Codex AGENTS.md
• Cursor Rules and AGENTS.md
• Claude Code CLAUDE.md and imports
• Gemini CLI GEMINI.md and imports
• Google Antigravity workspace rules
• Windsurf rules, AGENTS.md, and Memory
• GitHub Copilot repository instructions
• Devin AGENTS.md

File map

.
├── package.json
├── bin/arb.js
├── AGENTS.md
├── memory.md
├── CLAUDE.md
├── GEMINI.md
├── init.prompt
├── README.md
├── .agents/rules/project.md
├── .cursor/rules/project.mdc
├── .windsurf/rules/project.md
└── .github/copilot-instructions.md

AGENTS.md stores stable instructions. memory.md stores changing cross-session state. Native adapter files remain thin to prevent conflicting copies of project knowledge. arb init applies the bootstrap files above, except package.json, bin/arb.js, and README.md.

After initialization

Review the AI bootstrap changes:

git diff -- AGENTS.md memory.md CLAUDE.md GEMINI.md \
  .agents/rules/project.md \
  .cursor/rules/project.mdc \
  .windsurf/rules/project.md \
  .github/copilot-instructions.md

Confirm initialization completed:

rg 'UNINITIALIZED|TODO\(init\)' \
  AGENTS.md memory.md

The command should produce no output. Commit the initialized files together with the real project so future agent sessions receive the same instructions and Memory.

Ongoing use

Start a new session normally. No initialization prompt is needed after AGENTS.md and memory.md say INITIALIZED.

For a coding task, provide the desired outcome, scope, acceptance criteria, and verification expectations. The repository files provide the stable project context and recent shared state automatically.

If project commands, architecture, or working agreements change, update AGENTS.md. If current state, a durable decision, or a handoff changes, update memory.md according to its protocol.