agentleFS
eclipse-enclaveeclipse-enclave/enclave/AGENTS.md

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.

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
  1. Distinctive:

    Read README.md before making user-facing changes.

    line 3
  2. Very specific:

    Keep packages under internal/ focused and avoid unnecessary coupling.

    line 10
  3. Distinctive:

    Avoid hype, filler, and unrelated refactors.

    line 15
  4. Distinctive:

    Prefer clear names over explanatory comments.

    line 16
  5. Distinctive:

    Prefer structured CLI output over Docker labels or human-readable output for integration contracts.

    line 23
  6. Very specific:

    Run make lint-changed for fast feedback while iterating.

    line 31
  7. Very specific:

    Before committing, run make build, make test, and make lint.

    line 32
  8. Very specific:

    Run make generate after changing internal/config/options_def.go or tool-extension Go code.

    line 34
  9. Distinctive:

    All technically feasible first-party source and configuration files must carry the Eclipse-style MIT header used in this repository:

    line 39
  10. Very specific:

    Run make check-license-headers after adding or moving files.

    line 52
  11. Very specific:

    Use Conventional Commits: type: short imperative summary.

    line 56
  12. Distinctive:

    Write a single-line subject.

    line 60
  13. Very specific:

    When the user explicitly requests a WIP commit, prefix the subject with wip: .

    line 62
  14. Distinctive:

    Do not push, publish releases, or modify remote issues/PRs unless the maintainer explicitly requests it.

    line 64
  15. Very specific:

    Do not edit CHANGELOG.md in a PR, except the release-prep PR.

    line 66
  16. Very specific:

    When reviewing, a missing CHANGELOG.md entry is not a finding.

    line 68
  17. Distinctive:

    Keep documentation concise and aimed at experienced developers.

    line 72
  18. Distinctive:

    Document user-visible flags and behavior changes.

    line 75
  19. Very specific:

    Update docs/ARCHITECTURE.md and docs/README.md when repository layout changes.

    line 77
  20. Very specific:

    Update docs/ARCHITECTURE.md, this file, and relevant extension docs when profile, template, patch, or runtime-asset organization changes.

    line 78
  21. Very specific:

    Update docs/cli-reference.md, docs/configuration.md, and docs/DEV.md when CLI flags or option definitions change.

    line 79
  22. Very specific:

    Update the documentation index in extensions/tools/*/skills/enclave-help/SKILL.md when docs pages are added, renamed, or removed.

    line 80
  23. Very specific:

    Start with docs/extensions/README.md (architecture), docs/extensions/spec-reference.md (spec.yaml fields), and …

    line 84

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

Agent Instructions

Read README.md before making user-facing changes.

Architecture

  • See docs/ARCHITECTURE.md for the architecture, repository layout, and container assets.
  • Flow: CLI args → profile loading → image/bundle build check → store/auth/network setup → selected backend (docker by default, experimental qemu for 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 --json and the shared add/update/remove result envelope (both schemaVersion: "1"; see docs/extensions/json-output.md), enclave config --json (schemaVersion: "1", kind: "config"), and enclave network print --json (schemaVersion: "1", kind: "network-policy"). docs/integration.md documents all JSON contracts.
  • Session provenance (options in enclave ps --json) is contract; the enclave.options label that stores it is not. Recorded options follow AffectsSession in internal/config/options_def.go and 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-consumers says what it relies on.

Build and Test

  • Build with make build (or go build ./cmd/enclave); run tests with make 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-changed for fast feedback while iterating.
  • Before committing, run make build, make test, and make lint.
  • Documentation-only changes under docs/ do not require those checks.
  • Run make generate after changing internal/config/options_def.go or tool-extension Go code. Generated files are checked in: rebuild and commit them.
  • For dependency, toolchain, image, or GitHub Actions updates, run make check-versions and 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-headers after 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.md maps 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.md and docs/README.md when 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, and docs/DEV.md when CLI flags or option definitions change.
  • Update the documentation index in extensions/tools/*/skills/enclave-help/SKILL.md when docs pages are added, renamed, or removed.

Extensions

  • Start with docs/extensions/README.md (architecture), docs/extensions/spec-reference.md (spec.yaml fields), and docs/extensions/adding-a-tool.md / adding-a-feature.md (step-by-step guides). Every tool or feature extension must include a README.md.
  • Core ships six tools (Claude Code, Codex, Copilot, Theia with theia-next, OpenCode, Pi). New tools go to eclipse-enclave/enclave-extensions; see CONTRIBUTING.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 under extensions/tools/<tool>/templates/ and are baked into the image.
  • Memory scope, disable arguments, and preserved runtime state are declared with sandbox.memoryScope, sandbox.noMemoryArgs, and sandbox.statePaths; see Agent Memory.
  • User-side overrides, patches, and skills (paths and precedence) are documented in docs/tool-config.md.
  • Provenance (.enclave-source.json) and commands/ in an installed extension are excluded from the build context and image hash. See docs/extensions/installing.md.
  • Every kind may ship commands/host/<name> executables, which run on the host as enclave <name> verbs. The capability summary reports them in its first row, the update diff repeats the warning, and the hostCommands field carries them in list --json and the add/update/remove result envelope. Keep all of those accurate when touching that code. Anything under commands/ other than host/ is a validation warning. See docs/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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.