enclave
AGENTS.md80 starsChanged 17 days agoMITView on GitHub
Read README.md before making user-facing changes. Use Conventional Commits: type: short imperative summary. Allowed types: feat, fix, docs, `r
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository2 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- dependency-updatesSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
23 rules. About 0 are common, 9 are distinctive, and 14 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
14
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 3
Read README.md before making user-facing changes.
- Very specific: line 10
Keep packages under internal/ focused and avoid unnecessary coupling.
- Distinctive: line 15
Avoid hype, filler, and unrelated refactors.
- Distinctive: line 16
Prefer clear names over explanatory comments.
- Distinctive: line 23
Prefer structured CLI output over Docker labels or human-readable output for integration contracts.
- Very specific: line 31
Run make lint-changed for fast feedback while iterating.
- Very specific: line 32
Before committing, run make build, make test, and make lint.
- Very specific: line 34
Run make generate after changing internal/config/options_def.go or tool-extension Go code.
- Distinctive: line 39
All technically feasible first-party source and configuration files must carry the Eclipse-style MIT header used in this repository:
- Very specific: line 52
Run make check-license-headers after adding or moving files.
- Very specific: line 56
Use Conventional Commits: type: short imperative summary.
- Distinctive: line 60
Write a single-line subject.
- Very specific: line 62
When the user explicitly requests a WIP commit, prefix the subject with wip: .
- Distinctive: line 64
Do not push, publish releases, or modify remote issues/PRs unless the maintainer explicitly requests it.
- Very specific: line 66
Do not edit CHANGELOG.md in a PR, except the release-prep PR.
- Very specific: line 68
When reviewing, a missing CHANGELOG.md entry is not a finding.
- Distinctive: line 72
Keep documentation concise and aimed at experienced developers.
- Distinctive: line 75
Document user-visible flags and behavior changes.
- Very specific: line 77
Update docs/ARCHITECTURE.md and docs/README.md when repository layout changes.
- Very specific: line 78
Update docs/ARCHITECTURE.md, this file, and relevant extension docs when profile, template, patch, or runtime-asset organization changes.
- Very specific: line 79
Update docs/cli-reference.md, docs/configuration.md, and docs/DEV.md when CLI flags or option definitions change.
- Very specific: line 80
Update the documentation index in extensions/tools/*/skills/enclave-help/SKILL.md when docs pages are added, renamed, or removed.
- Very specific: line 84
Start with docs/extensions/README.md (architecture), docs/extensions/spec-reference.md (spec.yaml fields), and …
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Agent Instructions
Read README.md before making user-facing changes.
Architecture
- See
docs/ARCHITECTURE.mdfor the architecture, repository layout, and container assets. - Flow: CLI args → profile loading → image/bundle build check → store/auth/network setup → selected backend (
dockerby default, experimentalqemufor a narrow path). - Key packages (all under
internal/):app(orchestration),runtime(container execution, mounts, auth injection),gateway(network-isolation sidecar),network(policy loading and dnsmasq config generation),config(profile and path resolution),model(shared types). - Keep packages under
internal/focused and avoid unnecessary coupling.
Collaboration
- Be direct and critical when needed; flag unclear requirements before coding.
- Avoid hype, filler, and unrelated refactors.
- Prefer clear names over explanatory comments; comment only non-obvious behavior.
- Work is tracked via GitHub Issues.
External Integrations
- Treat CLI JSON schemas, background-run output, lifecycle commands, and container naming as integration contracts for external consumers; coordinate breaking changes. This includes
enclave tools|features|commands list --jsonand the sharedadd/update/removeresult envelope (bothschemaVersion: "1"; seedocs/extensions/json-output.md),enclave config --json(schemaVersion: "1",kind: "config"), andenclave network print --json(schemaVersion: "1",kind: "network-policy").docs/integration.mddocuments all JSON contracts. - Session provenance (
optionsinenclave ps --json) is contract; theenclave.optionslabel that stores it is not. Recorded options followAffectsSessionininternal/config/options_def.goand must never carry secret values. - Prefer structured CLI output over Docker labels or human-readable output for integration contracts.
- HomeShell (
eclipse-enclave/homeshell) is a known consumer;docs/integration.md#known-consumerssays what it relies on.
Build and Test
- Build with
make build(orgo build ./cmd/enclave); run tests withmake test. - The version comes from release tags via
scripts/version.sh; never hardcode one. See Versions. - Format modified Go files with
gofmt -w. - Run
make lint-changedfor fast feedback while iterating. - Before committing, run
make build,make test, andmake lint. - Documentation-only changes under
docs/do not require those checks. - Run
make generateafter changinginternal/config/options_def.goor tool-extension Go code. Generated files are checked in: rebuild and commit them. - For dependency, toolchain, image, or GitHub Actions updates, run
make check-versionsand follow.agents/skills/dependency-updates/SKILL.md; minimum versions (Go, Docker, buildx, git) may not exceed what the supported Debian and Ubuntu LTS releases ship.
License Headers
- All technically feasible first-party source and configuration files must carry the Eclipse-style MIT header used in this repository:
Copyright (C) <year> <copyright holder> and others. This program and the accompanying materials are made available under the terms of the MIT License, which is available in the project root. SPDX-License-Identifier: MIT - Preserve existing copyright years and owners. New files use their initial creation year and the actual legal copyright holder; do not guess ownership.
- Files created by splitting, refactoring, or generating existing content inherit the source header. Update generators so regenerated files retain the header.
- YAML files under
.github/do not require headers. - Headers are not required for Markdown, JSON, lock/sum files, test fixtures, rendered SVGs, images, PDFs, binaries, or imported third-party content.
- Run
make check-license-headersafter adding or moving files.
Git
Use Conventional Commits: type: short imperative summary.
Allowed types: feat, fix, docs, refactor, test, chore, build, ci, perf, revert.
Write a single-line subject; add a body only when it conveys something the subject cannot (non-obvious motivation, trade-offs, or context).
When the user explicitly requests a WIP commit, prefix the subject with wip: .
Do not push, publish releases, or modify remote issues/PRs unless the maintainer explicitly requests it.
Do not edit CHANGELOG.md in a PR, except the release-prep PR. Describe user-visible changes in the changelog block of the PR description, or write none there, as the pull request checklist explains.
When reviewing, a missing CHANGELOG.md entry is not a finding. These are: an empty or missing changelog block, a user-visible change marked none, a note not written in the user's terms, and a Breaking changes checkbox that disagrees with the Breaking: items.
Documentation
- Keep documentation concise and aimed at experienced developers. Lead with common tasks, put reference tables next, and keep edge cases after the main flow.
- Give each fact one canonical page and link to it from elsewhere;
docs/README.mdmaps topics to pages. - Wrap Markdown prose at 80 columns. Use sentence-case headings; avoid em dashes, bold-label paragraphs, and filler.
- Document user-visible flags and behavior changes.
- Diagrams are Mermaid code blocks embedded in the docs; update them together with the behavior they document.
- Update
docs/ARCHITECTURE.mdanddocs/README.mdwhen repository layout changes. - Update
docs/ARCHITECTURE.md, this file, and relevant extension docs when profile, template, patch, or runtime-asset organization changes. - Update
docs/cli-reference.md,docs/configuration.md, anddocs/DEV.mdwhen CLI flags or option definitions change. - Update the documentation index in
extensions/tools/*/skills/enclave-help/SKILL.mdwhen docs pages are added, renamed, or removed.
Extensions
- Start with
docs/extensions/README.md(architecture),docs/extensions/spec-reference.md(spec.yamlfields), anddocs/extensions/adding-a-tool.md/adding-a-feature.md(step-by-step guides). Every tool or feature extension must include aREADME.md. - Core ships six tools (Claude Code, Codex, Copilot, Theia with
theia-next, OpenCode, Pi). New tools go toeclipse-enclave/enclave-extensions; seeCONTRIBUTING.md. - Kinds: tools (
kind: sandbox,extensions/tools/<tool>/), features (kind: mixin,extensions/features/<feature>/), and command extensions (kind: command, user root only, host commands only). Tool settings templates live underextensions/tools/<tool>/templates/and are baked into the image. - Memory scope, disable arguments, and preserved runtime state are declared with
sandbox.memoryScope,sandbox.noMemoryArgs, andsandbox.statePaths; see Agent Memory. - User-side overrides, patches, and skills (paths and precedence) are documented in
docs/tool-config.md. - Provenance (
.enclave-source.json) andcommands/in an installed extension are excluded from the build context and image hash. Seedocs/extensions/installing.md. - Every kind may ship
commands/host/<name>executables, which run on the host asenclave <name>verbs. The capability summary reports them in its first row, the update diff repeats the warning, and thehostCommandsfield carries them inlist --jsonand theadd/update/removeresult envelope. Keep all of those accurate when touching that code. Anything undercommands/other thanhost/is a validation warning. Seedocs/commands.md.
Host Data
Enclave uses the XDG base directories on Linux and other Unixes and the Apple layout on macOS (XDG_* overrides are ignored there); root resolution lives in internal/config/host_roots.go. Per-project config and state are keyed by project hash and kept outside the worktree. Per-project agent memory is agent-writable and never shared between projects or agents. The full path table is in Host directories; store details are in docs/runtime/stores.md.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

