Repository Instructions

Workspaces can define general agent guidance in their own AGENTS.md. Repositories can also own instructions in their root directory. During bootstrap, ElasticClaw scans cloned workspace repositories for supported instruction files and writes a generated index named REPO_INSTRUCTIONS.md.

The generated index references repository-owned files instead of copying their contents. This keeps repository policy in the repository and avoids overwriting files maintained by the project.

ElasticClaw currently detects these files at the root of each cloned repository:

workspace/
|-- AGENTS.md
|-- REPO_INSTRUCTIONS.md
\-- my-app/
    |-- AGENTS.md
    |-- CLAUDE.md
    \-- package.json

When one or more supported files are found, ElasticClaw creates REPO_INSTRUCTIONS.md in the workspace root. The file lists each repository and the instruction files that apply inside it.

# Repository Instructions

ElasticClaw detected repository-owned agent instruction files. Read the relevant files before making changes in that repository.

## my-app

- `my-app/AGENTS.md`
- `my-app/CLAUDE.md`

ElasticClaw also ensures the workspace-level AGENTS.md points agents to the generated index. If the workspace already has an AGENTS.md, ElasticClaw appends the repository instruction section once. It does not overwrite existing workspace instructions.

## Repository Instructions

If `REPO_INSTRUCTIONS.md` exists, read it before working inside any cloned repository. It lists repository-owned instruction files such as `AGENTS.md`, `CLAUDE.md`, and `GEMINI.md`.

Put repository-specific rules in the repository root when they should travel with that codebase. Use workspace instructions for shared runtime policy, tool usage, and organization-wide preferences.

# my-app/AGENTS.md

Before changing code in this repository:

- Run npm test before opening a PR.
- Keep database migrations backward compatible.
- Do not edit generated files under src/generated/.
- Prefer existing service helpers over new HTTP clients.

# .elasticclaw/workspaces/product/elasticclaw-config.yaml
schema_version: v1
name: product

repositories:
  - repo: acme/my-app
    permissions: write
  - repo: acme/shared-lib
    permissions: read

provider: daytona

For managed providers, ElasticClaw waits until bootstrap has cloned repositories, configured credentials, discovered repository instructions, and marked the environment ready before waking the agent. This avoids the agent starting work before instruction files are available.

Repository instruction discovery is best-effort. If discovery fails after repositories are cloned, ElasticClaw logs a warning and lets the agent continue. The repository files are still present; only the generated index may be missing.