AGENTS.md ยท diff
git:20260827.6d45f4a to git:20260827.1488e91
3 added, 3 removed. Audit A to A.
# Context OS
This repository is the durable source of truth for personal, project, and session
context. Keep provider-neutral state here and host-specific behavior in its adapter.
## Session lifecycle
- First-time onboarding: use `$setup`.
- Begin work: use `$start`.
- Save a mid-session checkpoint: use `$update`.
- Close a session: use `$end`.
Invoke these workflows explicitly with the form documented by the host adapter;
this is guidance, not a host-enforced gate. The `$context-setup`, `$context-start`,
`$context-update`, and `$context-end` compatibility names remain supported.
## Lifecycle kernel
- `bash scripts/contextos.sh start` is the read-only continuity inventory.
- Setup, update, and end use `propose` then exact-digest `apply`; never edit
lifecycle state directly.
- Present every proposal diff. Apply only after explicit approval of that exact
proposal and report its receipt.
- Run `bash scripts/contextos.sh doctor` when discovery, runtime setup, a lock, or
copied skills may be stale.
## Context routing
- Read `ROUTING.md` before loading task-specific context.
- Treat `TODO.md` as the backlog and `state/current.md` as top-of-mind context.
- Keep each fact in one canonical file and link to it elsewhere.
- Load only what the current task needs. Identity and session data may be sensitive.
## Safety
- Follow `docs/safety-contract.md` before any external write, publish,
destructive action, credential change, or permission expansion.
- Show proposed context changes before broad or destructive rewrites.
- Never commit or push without explicit approval.
- Optional integrations stay disabled until chosen and configured; see
`references/integrations.md` for data and side-effect boundaries.
## Portability boundary
- `.agents/skills/` contains portable workflow cores.
- `.claude/` contains Claude Code commands, hooks, settings, and memory adapters.
- `.codex/hooks.json` maps Codex events to the same read-only policy checks.
- `adapters/hermes/` documents optional Hermes hooks and skill installation.
- `adapters/openclaw/` documents experimental skills-first OpenClaw support.
- `adapters/cursor/` documents separate experimental Cursor IDE and CLI support.
- `adapters/devin/` documents experimental Devin cloud-session and Review support.
- Runtime manifests under `runtimes/` declare support instead of implying parity.
- Kernel proposal/apply is the enforcement boundary on every host; hooks are
defense in depth and host-local memory is never shared automatically.
## Hermes Agent
- Hermes loads `AGENTS.md` as project context.
- Expose `.agents/skills/` as an external skill directory, or install the four
short aliases and all four `context-*` cores together. Copied skills must be
refreshed after source changes.
- Invoke `/setup`, `/start`, `/update`, and `/end` explicitly.
- Keep Hermes `MEMORY.md` and `USER.md` separate from repository state. See
`docs/memory-across-agents.md`.
- - Hermes hooks are optional defense in depth; kernel enforcement does not depend on them.
+ - `.claude/hooks/` does not run in Hermes; its hooks are optional defense in depth.
## OpenClaw
- Keep OpenClaw's private workspace and native memory outside this repository.
- Copy all four short lifecycle aliases and all four `context-*` cores into the
private workspace's `.agents/skills/`; refresh copied skills after changes.
- Run OpenClaw from the repository directory so root `AGENTS.md` is included,
then invoke `/skill setup`, `/skill start`, `/skill update`, or `/skill end`.
- This adapter installs no hook or plugin; skill allowlists do not replace
execution authorization. See `adapters/openclaw/README.md`.
## Cursor
- Open the repository as the IDE workspace or start the Agent CLI from its root;
both discover `AGENTS.md` and `.agents/skills/` natively.
- Invoke `/context-setup`, `/context-start`, `/context-update`, and
`/context-end` explicitly; Cursor CLI reserves `/update` for self-updates.
- Keep `.cursor/rules` non-overlapping with this file because Cursor does not
document their conflict order. IDE and CLI permissions remain separate.
- Cursor CLI also reads the removable root `CLAUDE.md` when present. Treat its
short lifecycle commands as Claude adapters, not Cursor invocations.
- This adapter ships no hook or memory bridge; see `adapters/cursor/README.md`.
## Devin
- Cloud sessions use `@skills:context-setup`, `@skills:context-start`,
`@skills:context-update`, and `@skills:context-end`; automatic skill discovery
- remains possible, while exact-digest approval still gates repository writes.
+ remains possible. Digests prevent proposal substitution, not automated approval.
- Review sends code externally and is not a lifecycle host. Account state is not
locally configured or verified; see `adapters/devin/README.md`.
## Validation
Run `bash scripts/validate-all.sh --workspace` for workspace changes. Product
- contributors and CI run the strict form after product changes.
+ contributors and CI run it without `--workspace` after product changes.