AGENTS.md

Rama main · réplica de lectura del repositorio original.

# Sjel agent bootstrap

Load the `sjel` skill (`Packs/harness/skills/sjel/SKILL.md`) for any Sjel operation or repository
change. It routes to the rules for placement, documentation, verification, data boundaries, and
commits. For operations, run `sjel help` or `sjel search <task>` before you browse files.

Shared documentation and planning rules live in [CONTRIBUTING.md](CONTRIBUTING.md#documentation).
Keep this file as the bootstrap. Link to the owning rule instead of duplicating it here.
Every harness reads this file, Claude Code included. Do not add a `CLAUDE.md` beside it.

Before editing:

1. Run `git status --short --branch` and `tools/doctor`.
2. Derive capabilities, ports, health, and open work from Sjel tools, the area plan in
   `docs/plans/`, and live metadata. Do not trust remembered prose.

Always:

- Until `PLAN.md` is done, every change goes straight to `main` from the primary checkout: no
  worktrees, no work-package PRs. They start when the plan is done, independently of release tags. Rules:
  `Packs/harness/skills/sjel/references/on-changes.md`.
- Other agent sessions edit the primary checkout at the same time. Never stash, revert, or overwrite
  their changes. Touch and stage only the files of your task.
- Keep private values, machine state, and secrets in the overlay or the OS keychain. Never
  generate, expose, or change a secret without explicit authorization.
- Never name an employer's internal systems in Sjel: model proxies and providers, internal
  hosts and registries, project codes, repository paths, or the work overlay's packs and
  extensions. Sjel is public. Such code and config live in the work overlay, and Sjel reads any
  needed value from overlay config at run time. Keep the terms themselves out of Sjel too: they
  belong in the overlay's `config/publication-markers.txt`, which the pre-commit hook
  (`tools/githooks/pre-commit`) and `tools/doctor` check against the Git index. Public
  open-source references, such as an upstream on GitHub, are not internal.
- Write every tracked document in a neutral open-source register, never as a conversation with
  an assistant. Rules: `Packs/harness/skills/sjel/references/on-documentation.md` (Register).
- Keep comments and config comments short: no dates, measurements, decisions or history. The
  commit message carries them. Rules: `Packs/harness/skills/sjel/references/on-documentation.md`.
- Use Sjel tooling first (`sjel`, `tools/`, capability routes). When a task needs a custom script,
  a manual workaround, or a raw command that the tooling does not cover, do one of two things.
  Build it into the tooling in the same change, or add an entry to
  [`docs/plans/tooling.md`](docs/plans/tooling.md) in its format. Do not leave the script only in
  `/tmp` or in the session.
- Write a durable rule or decision into the repository: code, the skill that owns it, the area
  plan in `docs/plans/`, or this file. Never into agent memory. The tracked `.claude/settings.json`
  sets `autoMemoryEnabled: false`. Machine-specific settings go in `.claude/settings.local.json`.
- Use only owned and maintained skills and harness plugins; adapt upstream material instead of
  installing it wholesale. Rules: [owned agent components](CONTRIBUTING.md#owned-agent-components).
- Reassess repeated routine approvals and wasteful delegation before continuing. Use narrow
  permissions and agents only when they pay for their overhead. Rules:
  [proportionate approvals and delegation](CONTRIBUTING.md#proportionate-approvals-and-delegation).
- Format replies for low cognitive load, per the `attention-control` skill: the result and its
  verification first, numbered chunks, exact counts and paths, and manual steps in their own
  block with a time estimate.

## Working through the plan

[`PLAN.md`](PLAN.md) orders the work by priority. Each area has one plan in
[`docs/plans/`](docs/plans/) with its state, specs and done-when checks. Rules:
`Packs/harness/skills/sjel/references/on-documentation.md` (Plans).

1. Take work from the highest priority in `PLAN.md` that no other session holds. Read its area
   plan before you edit code.
2. Build to the spec. If the spec is wrong or missing a decision, stop and ask. Do not decide a
   product question in code.
3. In the same change, update the area plan: shrink shipped work to one line with its commit,
   record what is still open, and state each check that did not run.
4. A tooling gap you hit goes to [`docs/plans/tooling.md`](docs/plans/tooling.md) (see Always).

A rule the Mac and the phone share goes into a capability or `apps/gpui/core`.