Gemmaclaw enhancements are code-owned instructions, setup behavior, or benchmark harness guards that improve Gemma-powered agents beyond upstream OpenClaw defaults. They are registered in one place so setup, runtime injection, tests, benchmarks, and documentation all agree on what is active.
gemmaclaw setup enables the default enhancement set for normal users unless they opt out. The selected ids are persisted in .gemmaclaw-enhancements.json and injected as generated Gemmaclaw runtime context beside workspace AGENTS.md. Enhancements are not copied into user-maintained agent instructions.
gemmaclaw setup --enhancements default
gemmaclaw setup --enhancements all
gemmaclaw setup --enhancements none
gemmaclaw setup --no-enhancements
gemmaclaw setup --enhancements external_delivery_receipt_verification
gemmaclaw setup --enhancements external_delivery_receipt_verification,commitment_followthrough_loopAgent benchmarks default to none so published scorecards measure the raw model and runtime baseline. Use --gemmaclaw-enhancements default, all, or a named id only when intentionally measuring an enhancement. Result notes and PRs should state the selection so enhanced and unenhanced runs are never mixed silently.
# Raw baseline, default behavior for benchmark runs
pnpm benchmark agent --task scheduled_media_delivery_verification --gemmaclaw-enhancements none
# Enhanced comparison
pnpm benchmark agent --task scheduled_media_delivery_verification --gemmaclaw-enhancements defaultThe registry lives in src/gemmaclaw/gemmaclaw_instructions.ts. Each enhancement has a stable id, title, category, description, docs path, default state, and generated instruction text. The prompt body for each enhancement lives in its own file under src/gemmaclaw/enhancements/, so each behavior can be referenced directly. Setup selection is persisted by the provisioning flow, and runtime bootstrap renders the selected sections into the generated gemmaclaw_instructions.ts context.
Injected prompt files stay intentionally concise for local-model contexts. The richer explanation lives here: diagrams, example conversations, and benchmark links.
| Surface | Location | Purpose |
|---|---|---|
| Registry | src/gemmaclaw/gemmaclaw_instructions.ts | Defines ids, docs, default state, and generated instruction text. |
| Prompt files | src/gemmaclaw/enhancements/ | Stores one prompt source file per enhancement for direct references and reviews. |
| Setup selection | gemmaclaw setup --enhancements | Chooses what normal agents receive and records it in .gemmaclaw-enhancements.json. |
| Benchmark selection | pnpm benchmark agent --gemmaclaw-enhancements | Opts benchmarks into enhancements only when intentionally comparing enhanced behavior. |
| Setup persistence | src/gemmaclaw/provision/bootstrap-profiles.ts | Persists the selected enhancement ids during setup. |
| Runtime injection | src/agents/bootstrap-files.ts | Adds generated Gemmaclaw context next to workspace instructions. |
Every registered enhancement should have a stable deep link, a concrete defect example, and a benchmark or fixture guard.
external_delivery_receipt_verification: verifies external delivery receipts before claiming messages, media, email, calendar mutations, or scheduled sends completed.commitment_followthrough_loop: prevents empty background-work promises and requires scheduler command invocation proof before claiming repair.Status: default enabled for normal Gemmaclaw setup. Benchmark default: disabled unless selected explicitly.
This enhancement tells agents not to claim an external delivery succeeded until they verify the real provider response, send receipt, durable log, or benchmark mock receipt. It covers messages, media files, email, calendar mutations, webhooks, scheduled sends, and similar side effects.
Defect pattern: an agent produces a local artifact or scheduler config, then claims the user-visible delivery happened even though the provider receipt is missing or failed.
Before: the agent generates latest-audio.mp3, writes a plausible scheduler file, and says the clips were sent. The active scheduler or Telegram/email/webhook receipt is never verified, so the user may see nothing.
After: the agent checks the active scheduler surface and the real provider or harness receipt before claiming delivery. In the benchmark fixture, success requires a Telegram mock receipt with ok: true and a non-empty message_id; otherwise the agent must say delivery is unverified.
User: Schedule the audio clip and send it to my Telegram tomorrow morning.
Before: "Done, I scheduled it and sent the clip." Problem: only latest-audio.mp3 and a copied scheduler file exist. No active scheduler proof, no Telegram receipt.
After: "The audio file is ready, but delivery is not verified yet. I found the active scheduler and triggered the mock send, but the receipt is missing a message_id, so I am not going to claim it was sent."
| Item | Value |
|---|---|
| Enhancement id | external_delivery_receipt_verification |
| Benchmark guard | scheduled_media_delivery_verification |
| Prompt registry | src/gemmaclaw/gemmaclaw_instructions.ts |
| Prompt source | src/gemmaclaw/enhancements/external_delivery_receipt_verification.ts |
| Docs source | docs/gemmaclaw/enhancements.md |
Status: default enabled for normal Gemmaclaw setup. Benchmark default: disabled unless selected explicitly.
This enhancement tells agents not to say they are "on it", "will fix it", or "will follow up" unless they finish the work inline and verify it before replying, or create and verify a durable Gemmaclaw-native follow-up. Local follow-up mechanisms can include scheduler entries, local work records, or Gemmaclaw subagent/session mechanisms available in that installation. Multi-step commitments also require a local work loop with a plan, subtasks, observable acceptance criteria, evidence, next action, an idle trigger for resuming pending work when no owner/subagent/session is active, and a QA/read-back check.
For scheduler repair, the enhancement requires checking both the active scheduler surface and the scheduled command target. Agents must verify file existence, ownership, executable permissions or explicit interpreter use, shebang/interpreter validity, working directory, and environment before claiming the job is fixed.
Defect pattern: an agent promises background repair, then the session ends without a real repair, scheduled wake-up, local task record, or subagent/session continuation. For schedulers, a second defect is claiming success after editing the schedule while the command target remains non-invocable.
Before: the agent replies "I'll get it sorted", edits a cron-like file, and leaves the command as scripts/send_daily_status.sh even though the script is not executable by the scheduled runtime. The next run fails with Permission denied.
After: the agent creates state/local-agent-work/daily-status-repair-loop.json, tracks subtasks such as inspect_active_scheduler, verify_command_invocation, repair_or_create_followup, and qa_readback, records active_owner, defines an idle_trigger for resuming pending work when no owner/subagent/session is active, then either completes and verifies the repair inline or creates and reads back a durable local follow-up before replying. In the benchmark fixture, the target script is intentionally non-executable, so the expected inline repair uses bash scripts/send_daily_status.sh or proves direct execution is valid, then records command_invocation_verified: true and a passing QA check.
User: Yesterday's daily status job did not run. Can you fix it?
Before: "I'm on it, I'll get it sorted." Problem: the agent edits a scheduler-like file but never proves it is active. The command still points at a non-executable script, so the next run fails.
After: "I found the active scheduler, changed the command to use bash scripts/send_daily_status.sh, ran a safe invocation check, re-read the scheduler state, and wrote the repair loop with QA evidence. The daily status scheduler is fixed and command invocation is verified."
| Item | Value |
|---|---|
| Enhancement id | commitment_followthrough_loop |
| Benchmark guard | commitment_followthrough_verification, long_horizon_20_step_followthrough |
| Prompt registry | src/gemmaclaw/gemmaclaw_instructions.ts |
| Prompt source | src/gemmaclaw/enhancements/commitment_followthrough_loop.ts |
| Benchmark task | src/gemmaclaw/benchmark/agent-tasks.ts |
| Harness fixture | scripts/benchmark/seed-mock-gog.py |
| Docs source | docs/gemmaclaw/enhancements.md |
--gemmaclaw-enhancements none and once with the intended enhancement selection when measuring improvement.