lossless-claw AGENTS.md

Repository Instructions

Principles

• Lossless means lossless. Do not delete, purge, truncate, or otherwise discard persisted user data unless the user has explicitly invoked a command or approved an action whose purpose is to remove that data.
• Automatic maintenance, bootstrap, repair, migration, compaction, cleanup, or rotation code must preserve user data. If continuity is uncertain, prefer degraded coverage, stale markers, warnings, or follow-up repair work over destructive recovery.
• Backups are not a substitute for this rule. The live system must not rely on being able to restore user data after an automatic delete.

PR Review And Merge

• Before merging a PR, check whether it changes user-facing behavior or should appear in npm release notes.
• If yes, make sure a maintainer adds a .changeset/*.md file before merge or immediately after in a follow-up PR.
• Do not expect external contributors to know or run the Changesets workflow.
• Use the smallest appropriate bump:
  • patch: fixes, compatibility work, docs-visible behavior changes
  • minor: new features or notable new behavior
  • major: breaking changes
• Treat a PR as not release-ready until the changeset question has been answered.

Release Notes Source Of Truth

• Follow RELEASING.md for the repo's full Changesets and publish workflow.

OpenClaw Host Compatibility

• When a change introduces or depends on a newer OpenClaw plugin API, runtime capability, config policy, manifest field, command behavior, or host integration contract, verify the first stable OpenClaw release that supports it before coding or publishing. Distinguish beta tags from stable releases.
• Update every compatibility declaration in the same change:
  • package.json peerDependencies.openclaw
  • package.json openclaw.compat.pluginApi
  • package.json openclaw.compat.minGatewayVersion
  • package.json openclaw.compat.tested
  • package.json openclaw.build.openclawVersion
  • package-lock.json
• Do not add an OpenClaw upper bound such as <2026.x.0 unless a specific known incompatibility requires it.
• Preserve peerDependenciesMeta.openclaw.optional when it exists; tightening the supported host version does not mean the package must install OpenClaw directly.
• Refresh package-lock.json with npm install --package-lock-only after changing OpenClaw peer or compatibility metadata, then verify npm ci --package-lock-only --ignore-scripts so CI will not fail on stale lock metadata.
• Add or update a regression test that asserts the required OpenClaw version metadata and, when relevant, the runtime capability gate or error path.
• Update user-facing documentation in the same change. At minimum, document the minimum OpenClaw version, why it is required, and the fallback path for users who cannot upgrade yet.
• Add a Changeset for any package compatibility change. Use patch for compatibility metadata fixes unless the change is breaking for currently supported users in a way that warrants a larger bump.