{"owner":"microsoft","repo":"SkillOpt","hasSkills":true,"totalSkillsCount":24,"totalTokensCount":28949,"categories":["marketplace","plugin-manifest","anthropic-skill"],"hasMcp":false,"mcpConfig":null,"found":[".cursor-plugin/marketplace.json","plugins/README.md","plugins/claude-code/.claude-plugin/marketplace.json","plugins/claude-code/.claude-plugin/plugin.json","plugins/claude-code/README.md","plugins/claude-code/skills/skillopt-sleep/SKILL.md","plugins/codex/README.md","plugins/codex/skills/skillopt-sleep/SKILL.md","plugins/copilot/README.md","plugins/copilot/skillopt/README.md","plugins/cursor/.cursor-plugin/plugin.json","plugins/cursor/README.md","plugins/cursor/skills/skillopt-sleep/SKILL.md","plugins/devin/README.md","plugins/dsh/README.md","plugins/dsh/skills/skillopt-sleep/SKILL.md","plugins/openclaw/README.md","plugins/openclaw/SKILL.md","skillopt/envs/alfworld/skills/initial.md","skillopt/envs/docvqa/skills/initial.md","skillopt/envs/livemathematicianbench/skills/initial.md","skillopt/envs/officeqa/skills/initial.md","skillopt/envs/searchqa/skills/initial.md","skillopt/envs/spreadsheetbench/skills/initial.md"],"skills":{".cursor-plugin/marketplace.json":"{\n  \"name\": \"skillopt\",\n  \"owner\": {\n    \"name\": \"Yifan Yang\",\n    \"email\": \"yifanyang@microsoft.com\"\n  },\n  \"metadata\": {\n    \"description\": \"Official SkillOpt plugins for usage-driven, validation-gated agent improvement.\"\n  },\n  \"plugins\": [\n    {\n      \"name\": \"skillopt-sleep\",\n      \"source\": \"plugins/cursor\",\n      \"description\": \"Review recent Cursor sessions, replay recurring work, and stage validation-gated improvements to a Cursor skill for explicit adoption.\"\n    }\n  ]\n}\n","plugins/README.md":"# SkillOpt-Sleep integrations\n\n**SkillOpt-Sleep** reviews recent agent sessions, mines recurring tasks, replays\nthem, and proposes bounded updates to memory and skills. A held-out validation\ngate decides whether a proposal is worth staging, and nothing live changes until\nthe user explicitly adopts it.\n\nThe shared engine lives in [`skillopt_sleep/`](../skillopt_sleep) and has no\nruntime dependency on the paper's `skillopt/` experiment package.\n\n## Available integrations\n\nSix integrations wrap the shared `skillopt_sleep` CLI. OpenClaw is a separate\nreference adaptation with its own backend and setup assumptions.\n\n| Platform | Folder | Mechanism | Status |\n|---|---|---|---|\n| **Claude Code** | [`claude-code/`](claude-code) | marketplace plugin, commands, skill, and hooks | installable shared-engine integration |\n| **Codex** | [`codex/`](codex) | user-level skill and shared runner | installable shared-engine integration |\n| **Cursor** | [`cursor/`](cursor) | native command and skill, project skill target, and shared runner | installable shared-engine integration |\n| **GitHub Copilot** | [`copilot/`](copilot) | MCP server exposing seven `sleep_*` tools | shared-engine MCP integration |\n| **Devin** | [`devin/`](devin) | MCP server plus Devin transcript conversion | shared-engine MCP integration |\n| **DeepSeek Harness** | [`dsh/`](dsh) | Cordis plugin: 7 native `skillopt_*` tools, skill, bundle patch layer | installable shared-engine integration |\n| **OpenClaw** | [`openclaw/`](openclaw) | custom DeepSeek/Ollama wrapper | independent reference adaptation; review and adapt before use |\n\n## Install\n\nClone the repository first unless an installed `skillopt-sleep` CLI is sufficient\nfor your workflow.\n\n| Platform | Install | Then |\n|---|---|---|\n| **Claude Code** | from the repository root, `/plugin marketplace add ./plugins/claude-code`, then `/plugin install skillopt-sleep@skillopt-sleep` | `/skillopt-sleep status` |\n| **Codex** | `bash plugins/codex/install.sh` | ask Codex to use the `skillopt-sleep` skill |\n| **Cursor** | `bash plugins/cursor/install.sh` (macOS/Linux) or `powershell -File plugins/cursor/install.ps1` (Windows) | `/skillopt-sleep status` |\n| **Copilot** | register `plugins/copilot/mcp_server.py` using its example MCP config | ask Copilot to run `sleep_status` |\n| **Devin** | register `plugins/devin/mcp_server.py` using its example MCP config | ask Devin to run `sleep_status` |\n| **DeepSeek Harness** | add `dsh-skillopt` to the profile's bundles, or patch it in — from a DSH source checkout: `pnpm dsh web --patch ./plugins/dsh/cordis.patch.yml`; with global dsh: `dsh web --patch ./plugins/dsh/cordis.patch.yml` | ask the agent to use `skillopt_status` |\n| **OpenClaw** | follow and adapt [`openclaw/README.md`](openclaw/README.md) | validate paths, credentials, and tasks locally |\n\nPython 3.10 or newer is required. Real CLI backends also require the selected\nagent CLI to be installed and authenticated.\n\nThe shared [`run-sleep.sh`](run-sleep.sh) supports both source checkouts and\ninstalled packages. If it cannot find the repository, it tries the\n`skillopt-sleep` executable on `PATH` (including `uv tool`/`pipx` installs), then\nan importable `skillopt_sleep` module. Install with `uv tool install skillopt` or\n`pip install skillopt` when using that fallback.\n\n> **Version note.** This integration reference tracks `main`. PyPI 0.2.0\n> supports the base Sleep CLI, while Cursor source/backend/plugin support,\n> Pi source/backend support, handoff, Sleep support for non-Azure\n> OpenAI-compatible endpoints, OpenCode Sleep source/backend support, and\n> `--preferences`, multi-skill fan-out, and reviewed subset adoption require a\n> source checkout from `main` until the next release.\n\n## One sleep cycle\n\n```text\nharvest supported local sessions → mine recurring tasks → replay tasks\n  → reflect and propose bounded edits → validate on held-out real tasks\n  → stage proposal → (you) review and adopt\n```\n\nThe default backend is `mock`: it makes no provider calls and is useful for\nchecking plumbing. A real backend is required for model-driven mining and genuine\noptimization.\n\n## Data boundary\n\n- Harvesting is local and read-only. The `mock` and `handoff` backends make no\n  network calls; handoff writes prompts for separate, user-controlled completion.\n- A real backend sends mining, replay, judging, and reflection prompts derived\n  from truncated transcript excerpts and tasks to the selected provider.\n- The Cursor source reads local user/assistant message text, explicit turn\n  errors, and tool names from `~/.cursor/projects/*/agent-transcripts`; it does\n  not retain tool arguments, tool outputs, or other record types. Known\n  secret-shaped strings are redacted, but this is defense in depth rather than\n  a guarantee that outbound prompts are secret-free.\n- The Cursor backend sends prompts through the installed, authenticated\n  `cursor-agent` CLI. Ordinary calls use read-only Ask mode in a new empty\n  temporary workspace with project file access denied. Cursor tasks containing\n  `tool_called` validation fail before Agent mode starts; use another backend for\n  those tasks. Cursor and the model provider selected by Cursor can receive the\n  resulting prompt content.\n- The Pi backend sends prompts through the installed, authenticated Pi CLI to\n  the provider configured by the user. It disables tools, skills, context files,\n  extensions, prompt templates, themes, and session writes for these calls, but\n  retains the user's Pi authentication and model configuration. Pi's offline\n  startup mode prevents configured npm/git package installation, package\n  updates, and model-catalog refresh; it does not prevent the selected provider\n  call. These controls are not a guarantee of permanent or complete isolation.\n- The Pi source retains user/assistant text, tool names, and lexical feedback\n  found in user text. It excludes thinking, tool arguments, tool outputs, images,\n  and unrelated metadata. The absolute project `cwd` from the session header is\n  retained for scope filtering and may appear in miner prompts sent to a real\n  backend and its provider. Known secret-shaped strings in retained message text\n  are redacted only as defense in depth.\n- The core `opencode` source reads local OpenCode SQLite history without the\n  CLI, authentication, or provider access. See\n  [the CLI reference](../docs/reference/cli.md#opencode-source-and-backend) for\n  its retained-data boundary.\n- The core `opencode` backend uses the installed OpenCode CLI. Plain calls\n  disable project configuration, model-initiated tool invocation, external\n  plugins, and configured MCP servers. Tool-aware replay requires explicit\n  opt-in. It exposes only temporary synthetic tools with randomized names and\n  fixed results, then verifies which tools OpenCode actually invoked. See the\n  [CLI reference](../docs/reference/cli.md#opencode-source-and-backend) for\n  history and isolation details. A native OpenCode plugin or command is not\n  included.\n- Outbound prompts are not currently guaranteed to be free of secrets. Do not\n  use a third-party provider on sensitive transcripts without reviewing the data\n  source and the provider's retention policy.\n- For a reviewable workflow, export tasks first, inspect and redact the JSON, set\n  its top-level `\"reviewed\"` field to `true`, and then use the task file with a\n  real backend:\n\n  ```bash\n  python -m skillopt_sleep harvest --project \"$(pwd)\" --output reviewed-tasks.json\n  python -m skillopt_sleep dry-run --project \"$(pwd)\" --backend codex \\\n    --tasks-file reviewed-tasks.json --progress\n  ```\n\n  Real backends reject task files that are still marked unreviewed.\n\nFor the separate API-key and Azure managed-identity transport boundaries, see\n[OpenAI-compatible endpoints](../docs/sleep/openai-compatible-endpoints.md).\n\n## Supported CLI surface\n\nActions:\n\n| Action | Behavior |\n|---|---|\n| `status` | show state and the latest staged proposal |\n| `dry-run` | harvest, mine, replay, and report; stage nothing |\n| `run` | run the full cycle and stage a proposal |\n| `adopt` | apply the latest staged proposal, with backups |\n| `harvest` | inspect or export mined tasks |\n| `schedule` / `unschedule` | install or remove the managed nightly cron entry |\n\nCommon implemented flags include:\n\n| Flag | Default | Purpose |\n|---|---|---|\n| `--backend mock\\|claude\\|codex\\|cursor\\|copilot\\|pi\\|opencode\\|handoff\\|azure_openai` | `mock` | select who performs model calls |\n| `--model NAME` | backend default | select a backend-specific model |\n| `--source claude\\|codex\\|copilot\\|cursor\\|pi\\|opencode\\|auto` | `claude` | select the transcript source; `auto` retains Codex-then-Claude precedence and does not select Copilot, Cursor, Pi, or OpenCode |\n| `--cursor-home PATH` | `~/.cursor` | override the Cursor transcript home |\n| `--cursor-path PATH` | auto-detect `cursor-agent` | select the Cursor Agent CLI executable |\n| `--pi-home PATH` | `~/.pi` | select the parent directory containing `agent/sessions` |\n| `--pi-path PATH` | auto-detect `pi` | select the Pi coding-agent CLI executable |\n| `--opencode-path PATH` | `SKILLOPT_SLEEP_OPENCODE_PATH`, then `opencode` on `PATH`/`PATHEXT` | select the OpenCode CLI executable |\n| `--opencode-db PATH` | `OPENCODE_DB`, `%LOCALAPPDATA%`/`%APPDATA%` (Windows), or `${XDG_DATA_HOME:-~/.local/share}/opencode/opencode.db` | select the OpenCode SQLite history database |\n| `--opencode-tool-replay` | off | enable OpenCode tool-aware replay for `tool_called` checks in rule judges |\n| `--project PATH` | current directory | select the project and invoked harvest scope |\n| `--scope invoked\\|all` | `invoked` | limit transcript harvesting |\n| `--target-skill-path PATH` | managed skill | select a specific `SKILL.md` to stage/adopt |\n| `--tasks-file PATH` | none | replay a reviewed task file instead of harvesting |\n| `--max-sessions N` / `--max-tasks N` | unset → `3 × tasks` / `40` tasks | bound harvested work; these are not hard token or wall-clock budgets |\n| `--edit-budget N` | `4` | cap bounded edits per cycle |\n| `--preferences \"...\"` | empty | add house rules to the reflection prior |\n| `--progress` | off | print phase progress to stderr |\n| `--auto-adopt` | off | adopt an accepted proposal without a separate command |\n| `--json` | off | emit machine-readable output where supported |\n\nThe nightly CLI does **not** currently expose `--gate`, `--rollouts-k`,\n`--optimizer-model`, `--target-model`, `--budget-tokens`, or `--budget-minutes`.\nDo not pass experiment-harness flags to the main CLI.\n\nFor the Cursor backend, `--project` also selects target files, state, and the\nstaging location, but it does not make that directory the Cursor Agent execution\nworkspace. The target skill is inserted as prompt text rather than invoked as a\nnative skill. Real-backend `dry-run` performs the same mining and replay model\ncalls while suppressing staging, adoption, and persisted state changes. The\ncurrent Sleep cycle does not implement fresh-worktree replay; a `replay: mock`\nreport label describes prompt replay and is independent of `--backend mock`.\n\n### Preferences\n\n`--preferences` is the main user-facing steering knob:\n\n```bash\npython -m skillopt_sleep run --backend codex --project \"$(pwd)\" \\\n  --preferences \"Prefer pytest. Keep commit subjects imperative and concise.\"\n```\n\nPreferences guide reflection but remain subject to the validation gate.\n\n### Pi source and backend\n\nPi transcript harvesting is explicit: `--source pi` reads session JSONL files\nbelow `~/.pi/agent/sessions`; use `--pi-home` to select the parent directory\nthat contains `agent/sessions`. This source does not require the Pi CLI or\nprovider authentication. It retains user/assistant text, tool names, and lexical\nfeedback found in user text, while excluding thinking, tool arguments, tool\noutputs, images, and unrelated metadata. The absolute project `cwd` from the\nsession header is retained for scope filtering and may appear in miner prompts\nsent to a real backend and its provider. Known secret-shaped strings in retained\nmessage text are redacted as defense in depth, not as a guarantee. `--source auto` keeps Codex-then-Claude\nprecedence and does not select Pi.\n\nThe source and backend are independent. `--backend pi` uses a locally installed,\nauthenticated Pi CLI to make real model-provider calls for mining, replay,\njudging, and reflection. Select another executable with `--pi-path` and a model\nwith `--model`:\n\n```bash\npython -m skillopt_sleep run --project \"$(pwd)\" \\\n  --source pi --backend pi --pi-path /absolute/path/to/pi \\\n  --model provider/model --max-sessions 5 --max-tasks 3 --progress\n```\n\nPi calls disable tools, skills, context files, extensions, prompt templates,\nthemes, and session writes. They still use the user's Pi authentication and\nmodel configuration. Pi's offline startup mode also prevents configured npm/git\npackage installation, package updates, and model-catalog refresh; it does not\nprevent the selected provider call. This is bounded invocation setup rather\nthan permanent or complete isolation. Transcript-derived prompts reach the\nprovider configured in Pi; review that provider's data-retention and privacy\npolicy before using sensitive sessions.\n\nThe managed scheduler stores the selected backend but does not persist\n`--source`, `--pi-home`, `--pi-path`, or `--model`. Before scheduling Pi, set\n`transcript_source`, `pi_home`, `pi_path`, and `model` in\n`~/.skillopt-sleep/config.json`; prefer an absolute `pi_path` and verify that the\nscheduled account is authenticated.\n\n### Cursor source and backend\n\nCursor transcript harvesting is explicit: use `--source cursor` rather than\n`--source auto`. Invoked-project scope uses Cursor's recorded workspace path,\nwith the sanitized storage directory as a fallback; `--scope all` scans every\nCursor workspace under `~/.cursor/projects`. The model-driven backend requires\nan installed, authenticated `cursor-agent`; use `--cursor-path`,\n`SKILLOPT_SLEEP_CURSOR_PATH`, or the `cursor_path` config key when it is not on\n`PATH`, and use `--model` or `SKILLOPT_SLEEP_CURSOR_MODEL` to choose a model.\n\nTarget the project skill explicitly so accepted learning becomes visible to\nCursor without changing the plugin's own workflow skill:\n\n```bash\npython -m skillopt_sleep run --project \"$(pwd)\" \\\n  --source cursor --backend cursor \\\n  --target-skill-path .cursor/skills/skillopt-sleep-learned/SKILL.md \\\n  --max-sessions 5 --max-tasks 3 --progress\n```\n\n### Advanced config\n\nThe JSON/YAML config under `~/.skillopt-sleep/` supports additional engine keys,\nincluding `gate_mode`, `gate_metric`, `gate_no_regression`, `dream_rollouts`,\n`dream_factor`, `recall_k`, `evolve_memory`, and `evolve_skill`. These are config\nkeys, not aliases for the unsupported CLI flags listed above. Shipping defaults\nare conservative: `gate_mode=\"on\"`, `gate_no_regression=false`,\n`dream_rollouts=1`, `dream_factor=0`, and `recall_k=0`.\n\nThe managed `schedule` command stores only the project, backend, time, and\noptional auto-adopt setting. It does not copy `--source`, `--cursor-home`,\n`--cursor-path`, `--model`, or `--target-skill-path` into the scheduled command.\nFor a Cursor schedule, set `transcript_source`, `cursor_home`, `cursor_path`,\n`model`, and `target_skill_path` in `~/.skillopt-sleep/config.json` first. Keep\nthe target project-relative, use an absolute CLI path because cron and Task\nScheduler may have a minimal `PATH`, and confirm that `cursor-agent` is\nauthenticated for the account that runs the job.\n\n### Handoff backend\n\n`--backend handoff` keeps model subprocesses out of the engine. It writes pending\nmodel calls to `.skillopt-sleep-handoff/PROMPTS.md` and `pending.json`, exits with\ncode 3, and resumes after answers are placed in `answers/<id>.md`:\n\n```bash\npython -m skillopt_sleep run --backend handoff --project \"$(pwd)\"\n# answer each prompt in a fresh context, then run the same command again\n```\n\nAnswering held-out prompts from a context that has already seen their references\ncontaminates the validation gate. Claude Code's `/skillopt-sleep-handoff` command\nautomates the loop with isolated fresh-context subagents.\n\n## Validation\n\nThe deterministic no-provider check exercises consolidation and the gate:\n\n```bash\npython -m skillopt_sleep.experiments.run_experiment \\\n  --persona researcher --assert-improves\n```\n\nReal-model benchmark results and their limitations are documented in\n[`docs/sleep/RESULTS.md`](../docs/sleep/RESULTS.md). The benchmark recipes are not\nthe shipping CLI defaults.\n\n## Safety summary\n\n- Session harvesting is read-only.\n- `mock` and `handoff` make no network calls.\n- `run` stages proposals; `adopt` is the normal live-change boundary.\n- Adoption backs up existing target files.\n- `--max-sessions` and `--max-tasks` bound work. `max_tokens_per_night` in the\n  config file (default `400000`) stops a night from starting new steps once its\n  token count reaches the budget, but a started step finishes, so it is not a\n  hard cap. There is no elapsed-time budget.\n- Treat real-backend transcript excerpts as data shared with the selected\n  provider.\n","plugins/claude-code/.claude-plugin/marketplace.json":"{\n  \"$schema\": \"https://anthropic.com/claude-code/marketplace.schema.json\",\n  \"name\": \"skillopt-sleep\",\n  \"description\": \"SkillOpt-Sleep: give your local Claude agent a nightly sleep cycle that reviews past sessions and consolidates validated memory + skills.\",\n  \"owner\": {\n    \"name\": \"Yifan Yang\",\n    \"email\": \"yifanyang@microsoft.com\"\n  },\n  \"plugins\": [\n    {\n      \"name\": \"skillopt-sleep\",\n      \"description\": \"Nightly offline self-evolution: harvest your past Claude Code sessions, replay recurring tasks on your own API budget, and consolidate what the agent learns into validated CLAUDE.md memory and SKILL.md skills, behind a held-out gate, staged for your review. Synthesizes SkillOpt (validation-gated skill optimization), Claude Dreams (offline memory consolidation), and agent sleep/consolidation.\",\n      \"author\": {\n        \"name\": \"Yifan Yang\"\n      },\n      \"category\": \"productivity\",\n      \"source\": {\n        \"source\": \"git-subdir\",\n        \"url\": \"https://github.com/microsoft/SkillOpt.git\",\n        \"path\": \"plugins/claude-code\",\n        \"ref\": \"main\"\n      },\n      \"homepage\": \"https://github.com/microsoft/SkillOpt\"\n    }\n  ]\n}\n","plugins/claude-code/.claude-plugin/plugin.json":"{\n  \"name\": \"skillopt-sleep\",\n  \"description\": \"Give your local Claude agent a nightly 'sleep cycle': it reviews your past sessions offline, replays recurring tasks on your own API budget, and consolidates what it learns into validated memory (CLAUDE.md) and skills (SKILL.md) so it gets better the more you use it. Synthesizes SkillOpt (validation-gated skill optimization), Claude Dreams (offline memory consolidation), and agent sleep/consolidation.\",\n  \"version\": \"0.1.0\",\n  \"author\": {\n    \"name\": \"Yifan Yang\",\n    \"email\": \"yifanyang@microsoft.com\"\n  },\n  \"homepage\": \"https://github.com/microsoft/SkillOpt\",\n  \"repository\": \"https://github.com/microsoft/SkillOpt\",\n  \"license\": \"MIT\",\n  \"keywords\": [\n    \"skillopt\",\n    \"self-improvement\",\n    \"memory-consolidation\",\n    \"dreams\",\n    \"sleep\",\n    \"skills\",\n    \"continual-learning\",\n    \"offline-optimization\"\n  ]\n}\n","plugins/claude-code/README.md":"# SkillOpt-Sleep (Claude Code plugin)\n\n> Give your local Claude agent a **sleep cycle**. Every night it reviews your\n> past sessions offline, replays your recurring tasks on your own API budget,\n> and consolidates what it learns into **validated** memory (`CLAUDE.md`) and\n> skills (`SKILL.md`). Your agent gets better the more you use it — no\n> model-weight training.\n\nSkillOpt-Sleep is the **deployment-time** companion to\n[SkillOpt](https://github.com/microsoft/SkillOpt). SkillOpt trains a skill\noffline on a benchmark; SkillOpt-Sleep applies the same discipline to *your own\ndaily usage*: bounded text edits, accepted only through a held-out validation\ngate, with rejected candidates recorded in the cycle report for review.\n\nIt synthesizes three ideas:\n\n| Idea | Contribution |\n|---|---|\n| **SkillOpt** | skill/memory = trainable text; bounded add/delete/replace edits; **held-out gate** keeps only changes that help. |\n| **Claude Dreams** | offline consolidation over past sessions; input never mutated; output **reviewed then adopted**. |\n| **Agent sleep** | periodic offline replay turns short-term episodes into long-term skill. |\n\n## What it does (one \"night\")\n\n```\nharvest ~/.claude transcripts → mine recurring tasks → replay offline\n   → consolidate (reflect → bounded edit → GATE) → stage proposal → (you) adopt\n```\n\nNothing live is modified until **you** run `/skillopt-sleep adopt` (the Dreams \"review,\nthen adopt or discard\" contract). Every adopt backs up the prior file first.\n\n## Install\n\n**Requirements:** Python ≥ 3.10. A real CLI backend additionally requires its\ncorresponding `claude` or `codex` executable on `PATH` and authenticated.\n\n```bash\n# 1) get the code (the plugin ships inside the SkillOpt repo)\ngit clone https://github.com/microsoft/SkillOpt.git\ncd SkillOpt\n\n# 2) add the plugin to Claude Code as a local marketplace\n/plugin marketplace add ./plugins/claude-code\n/plugin install skillopt-sleep@skillopt-sleep\n\n# 3) verify\n/skillopt-sleep status\n```\n\nThe plugin's bundled runner (`scripts/sleep.sh`) auto-selects a Python ≥ 3.10\ninterpreter and calls the `skillopt_sleep` engine. A source checkout needs no\n`pip install`. If the marketplace cache does not contain a usable source tree,\nthe shared runner falls back first to a `skillopt-sleep` executable on `PATH`\n(including `uv tool`/`pipx` installs), then to an importable Python module. Use\n`uv tool install skillopt` or `pip install skillopt` for that fallback.\n\n> **Version note.** This page tracks `main`. PyPI 0.2.0 provides the base Sleep\n> CLI, but handoff mode, `--preferences`, multi-skill fan-out, and reviewed\n> subset adoption require a source checkout from `main` until the next release.\n\n## Quick start\n\n```bash\n# from inside any project you use with Claude Code:\n/skillopt-sleep dry-run     # preview what it would learn; no changes staged\n/skillopt-sleep run         # full cycle: stages a reviewed proposal (still no live edits)\n/skillopt-sleep status      # see history + the latest staged proposal\n/skillopt-sleep adopt --legacy       # apply the reviewed managed proposal\n# Fan-out nights instead use: adopt --skill NAME (repeatable) or --all-skills\n\n/skillopt-sleep-handoff run # same cycle, but THIS session answers the model calls\n                            # (no claude -p subprocess, no API key — subscription-friendly)\n```\n\nOr call the engine directly (Python ≥ 3.10):\n\n```bash\npython -m skillopt_sleep run --project \"$(pwd)\" --scope invoked --backend mock\npython -m skillopt_sleep run --project \"$(pwd)\" --backend claude   # real lift via Claude\npython -m skillopt_sleep run --project \"$(pwd)\" --backend codex    # real lift via Codex\n```\n\nDefault backend is **`mock`** — deterministic, no API spend — so you can try the\nplumbing for free. Switch to `--backend claude` or `--backend codex` for\nmodel-driven mining and optimization on your own budget; an accepted gain is\ntask- and model-dependent, not guaranteed.\n\n### Data boundary for real backends\n\nHarvesting `~/.claude` is local and read-only, and the `mock` backend makes no\nprovider calls. A real backend sends truncated transcript excerpts and derived\ntasks to the selected provider for mining, replay, judging, and reflection.\nOutbound prompts are not currently guaranteed to be secret-free. Review your\nsession data and provider policy before using a real backend on a sensitive\nproject; the [shared integration guide](../README.md#data-boundary) describes a\nreviewed task-file workflow.\n\n### Sessions you did not type\n\nHarvest keeps your prompts and drops machine-written transcripts. Three\nenvironment variables extend what counts as machine-written, for the sessions\nClaude Code gives no other tell:\n\n| Variable | Effect |\n|---|---|\n| `SKILLOPT_SLEEP_AGENT_MARKERS` | Comma-separated markers; a session whose **first** prompt contains one is dropped entire. |\n| `SKILLOPT_SLEEP_NEG_FEEDBACK` / `SKILLOPT_SLEEP_POS_FEEDBACK` | Extra comma-separated phrases, in any language, that count as you rejecting or approving the previous answer. |\n\nThe case they exist for is a local hook that summarises the previous session on\na timer. Its runs are single-turn, they are frequent enough to fill\n`--max-sessions` and starve the night of your real sessions, and in the desktop\napp they carry `entrypoint: \"claude-desktop\"` like interactive ones — so neither\n`entrypoint` nor a replay marker identifies them. Quote the hook's first line:\n\n```bash\nexport SKILLOPT_SLEEP_AGENT_MARKERS=\"Below is a conversation log from a coding session\"\n```\n\nA template you cannot quote is covered only after you opt in: a single-turn\nsession sharing its first 120 characters of prompt with three others in the same\nharvest window is dropped before the session cap is applied once\n`SKILLOPT_SLEEP_REPEAT_MIN_SESSIONS` is set (default `0`, off; `3` is the usual\nchoice). Recurrence is not proof of who wrote a prompt — three human requests\nagainst one long shared checklist look the same — so the default keeps every\nsession and `--max-sessions` still bounds how many transcripts are read. A\nsession with a follow-up user turn is never matched, and neither is a prompt\nshorter than the prefix — your own one-shot requests repeat entirely rather than\nsharing a long boilerplate header.\n\n`/skillopt-sleep harvest` and the progress line of a `run` / `dry-run` report\nwhat was dropped, so a thin night is explainable:\n`harvest done: sessions=120 (skipped: 297 repeated-template sessions, 2 past the session cap)`.\nFull reference: [the sleep guide](../../docs/sleep/README.md#harvest-filters-environment).\n\n### Handoff mode (session answers the model calls)\n\n`--backend handoff` runs the cycle without any model subprocess: the engine\nexecutes the deterministic stages and writes every model call it needs to\n`.skillopt-sleep-handoff/PROMPTS.md` + `pending.json` (exit code 3). You (or\nthe `/skillopt-sleep-handoff` command, which automates the loop with isolated\nfresh-context subagents) write each raw answer to `answers/<id>.md` and re-run\nthe same command; it resumes from the answers and either finishes or stages\nthe next batch. Typically 3–6 rounds per night.\n\n```bash\npython -m skillopt_sleep run --backend handoff --project \"$(pwd)\"\n# ... answer .skillopt-sleep-handoff/PROMPTS.md into answers/<id>.md ...\npython -m skillopt_sleep run --backend handoff --project \"$(pwd)\"   # resume\n```\n\nAnswer every prompt in a **fresh context** — a session that has already seen\nthe mined tasks and their references would contaminate the held-out gate.\nDetails: [the plugins README](../README.md#handoff-backend).\n\n## Does it actually improve? (real models, public benchmark)\n\nSkillOpt-Sleep is validated against [gbrain-evals](https://github.com/garrytan/gbrain-evals)'\npublic `skillopt-v1` suite — the same benchmark gbrain scores its own skill\noptimizer against. We take a deliberately **deficient** skill and run one sleep\nnight; held-out scoring is done by a local rule judge (no judge-API, no way to\ngrade its own homework).\n\n| Backend | Seed | Held-out before → after | Nights |\n|---|---|---|---|\n| **Claude (Haiku 4.5)** | brief-writer | **0.00 → 1.00** | 1 |\n| **Codex** | brief-writer | **0.00 → 1.00** | 2 |\n\nBoth took a brief-writer with no risks section / no confidence level and, within\n1–2 nights, proposed gated edits that lifted the held-out score to perfect —\ninto the protected `LEARNED` block, nothing else touched. The Codex 2-night\ntrace even shows the optimizer **diagnosing its own residual failure** and\nadding a meta-rule to fix it. See the recorded results and limitations in\n[`docs/sleep/RESULTS.md`](../../docs/sleep/RESULTS.md).\n\nReproduce:\n\n```bash\ngit clone https://github.com/garrytan/gbrain-evals /tmp/gbrain-evals\npython -m skillopt_sleep.experiments.run_gbrain --backend claude --model haiku \\\n  --seeds brief-writer --data-root /tmp/gbrain-evals/eval/data/skillopt-v1 \\\n  --nights 1 --limit-replay 3 --limit-holdout 3\npython -m skillopt_sleep.experiments.run_gbrain --backend codex \\\n  --seeds brief-writer --data-root /tmp/gbrain-evals/eval/data/skillopt-v1 \\\n  --nights 1 --limit-replay 3 --limit-holdout 3\n```\n\n## Deterministic proof (no API, no keys)\n\n```bash\npython -m skillopt_sleep.experiments.run_experiment --persona researcher --assert-improves\npython -m skillopt_sleep.experiments.run_experiment --persona programmer  --assert-improves\n```\n\nEach prints the held-out score rising from baseline toward 1.0 as the gate\naccepts the general rules your tasks need, and confirms the gate **rejects** an\ninjected harmful edit. Context for the measured experiments is in\n[`docs/sleep/RESULTS.md`](../../docs/sleep/RESULTS.md).\n\n## Schedule it nightly\n\n```bash\n/skillopt-sleep schedule --hour 3 --minute 17\n/skillopt-sleep unschedule\n```\n\nThe built-in scheduler creates a managed cron entry and logs under the project.\nThe scheduled run stages proposals unless `--auto-adopt` is explicitly selected.\n\n## Safety\n\n- **Read-only** harvest of `~/.claude`. `mock` replay has no side effects.\n- Proposals are **staged**, never auto-applied (unless you opt in with `--auto-adopt`).\n- Every adopt writes a backup under the staging dir's `backup/`.\n- `--max-sessions` and `--max-tasks` bound work. `max_tokens_per_night` in\n  `~/.skillopt-sleep/config.json` stops a night from starting new steps once its\n  token count reaches the budget; a started step finishes, so it is not a hard\n  cap, and there is no wall-clock budget.\n- Real backends share truncated session/task content with the selected provider;\n  do not assume outbound prompts have been fully redacted.\n\n## Status\n\nThe engine, deterministic experiment, Claude/Codex CLI backends, handoff mode,\nand staged adoption flow are implemented. Advanced experiment-harness flags are\nnot automatically available on the nightly CLI; see the\n[shared integration reference](../README.md#supported-cli-surface).\n","plugins/claude-code/skills/skillopt-sleep/SKILL.md":"---\nname: skillopt-sleep\ndescription: \"Use when the user wants their Claude agent to self-improve from past usage, asks about a nightly/offline 'sleep' or 'dream' cycle, memory/skill consolidation, or says things like 'make my agent better the more I use it', 'review my past sessions', 'learn my preferences', 'consolidate what you learned', 'run the sleep cycle', or wants to schedule background self-optimization. Drives the skillopt_sleep engine: harvest past sessions -> mine recurring tasks -> replay through a selected backend -> consolidate validated CLAUDE.md/SKILL.md behind a held-out gate.\"\n---\n\n# SkillOpt-Sleep: usage-driven self-evolution for a local Claude agent\n\nSkillOpt-Sleep gives the user's agent a **sleep cycle**. On demand or on a\nnightly schedule, it reviews real past Claude Code sessions, re-runs recurring\ntasks through the selected backend, and consolidates what it\nlearns into **memory** (`CLAUDE.md`) and **skills** (`SKILL.md`). With the\ndefault validation gate enabled, it keeps only changes that improve a held-out\nscore. Live files change only through explicit adoption or a user-requested\n`--auto-adopt`. It aims to improve this user's recurring work, while making\neach accepted proposal measurable on the run's held-out tasks,\nwith no model-weight training. It is the deployment-time analogue of training:\nshort-term experience → long-term competence.\n\nIt synthesizes three ideas:\n- **SkillOpt** — the skill/memory doc is trainable text; bounded add/delete/replace\n  edits; accepted only through a held-out gate; rejected edits are recorded in\n  the run report for review.\n- **Claude Dreams** — consolidation that reads past sessions and proposes changes\n  inside protected learned blocks; the input is never mutated, and output is\n  reviewed before adoption.\n- **Agent sleep** — periodic background replay turns episodes into durable skill.\n\n## When to use this skill\n\nTrigger when the user wants any of:\n- \"make my agent learn from how I use it\" / \"get better the more I use it\" / \"remember my preferences across sessions\"\n- a nightly/scheduled or on-demand **offline self-improvement / dream / sleep** run\n- to **review past sessions/trajectories** and distill recurring tasks\n- to **consolidate** feedback into `CLAUDE.md` or a managed skill\n- to **schedule** the cycle (cron) or **adopt** a staged proposal\n\n## The cycle (six stages)\n\n1. **Harvest** — read `~/.claude/projects/*/<session>.jsonl` + `~/.claude/history.jsonl` (READ-ONLY) → session digests.\n2. **Mine** — digests → `TaskRecord`s (recurring intents + outcome labels + checkable refs where possible).\n3. **Replay** — re-run tasks through the selected backend under the *current*\n   skill+memory → (hard, soft) scores.\n4. **Consolidate** — reflect on failures → propose bounded edits → **gate** on a held-out slice; with the default gate enabled, accept only if it strictly improves.\n5. **Stage** — write the accepted `proposed_CLAUDE.md` and/or\n   `proposed_SKILL.md`, plus `report.md`, `report.json`, `manifest.json`, and\n   `diagnostics.json` into `<project>/.skillopt-sleep/staging/<timestamp>/`.\n   **Nothing live changes.** A rejected run still has a report but no proposed\n   live-file replacement.\n6. **Adopt** — explicit (or opt-in auto): copy staged files over live ones, backing up first.\n\n## How to drive it\n\nPrefer the `/skillopt-sleep` command. Under the hood it calls the bundled runner:\n\n```bash\n\"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh\" status                       # what's happened\n\"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh\" dry-run --project \"$(pwd)\"    # no-staging preview\n\"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh\" run --project \"$(pwd)\"        # full cycle, stages a proposal\n\"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh\" adopt --project \"$(pwd)\"      # apply staged proposal (with backup)\n```\n\n- Default backend is `mock` (deterministic, **no API spend**) — good for trying the plumbing.\n- Add `--backend claude` or `--backend codex` to spend the user's real budget\n  for model-driven optimization. A held-out gain is run-specific evidence, not\n  a guarantee of broader improvement; results depend on the tasks, model, and\n  checks.\n- Scope defaults to the invoked project; `--scope all` harvests every Claude\n  project into the current run's configured targets.\n- A real backend sends truncated transcript/task content to its provider. See\n  the data-boundary rules below before using one with sensitive sessions.\n\n### Scheduling\n\n```bash\n\"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh\" schedule --project \"$(pwd)\" --hour 3 --minute 17\n\"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh\" unschedule --project \"$(pwd)\"\n```\n\nInstalls a nightly cron entry. `unschedule --all` removes every managed entry.\n\n## Common CLI flags\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `--project PATH` | cwd | Project directory to evolve |\n| `--scope all\\|invoked` | invoked | Harvest scope |\n| `--backend mock\\|claude\\|codex\\|copilot\\|handoff\\|azure_openai` | mock | Backend (mock = no provider calls) |\n| `--model NAME` | backend default | Override the model used for replay |\n| `--source claude\\|codex\\|auto` | claude | Transcript source |\n| `--lookback-hours N` | 72 | Harvest window |\n| `--max-sessions N` | derived | Cap harvested sessions; defaults to 3 × max tasks (120 with current defaults) |\n| `--max-tasks N` | 40 | Cap mined tasks |\n| `--target-skill-path PATH` | `~/.claude/skills/skillopt-sleep-learned/SKILL.md` | Explicit SKILL.md to evolve |\n| `--tasks-file PATH` | — | Reviewed TaskRecord JSON (skip harvest) |\n| `--progress` | off | Print phase progress to stderr |\n| `--auto-adopt` | off | Auto-adopt if gate passes |\n| `--edit-budget N` | 4 | Max bounded edits per night |\n| `--preferences TEXT` | empty | Add house rules to the optimizer's reflection prior |\n| `--json` | off | Machine-readable JSON output |\n\nThe CLI also has source/runtime path overrides (`--claude-home`, `--codex-home`,\nand `--codex-path`) and action-specific flags. Use\n`python -m skillopt_sleep <action> --help` as the authoritative surface.\n\n## Config keys (`~/.skillopt-sleep/config.json`)\n\nBeyond the CLI flags, advanced behavior is controlled via config:\n\n- **`preferences`** — free-text house rules injected into the optimizer's reflect step (e.g. \"Always use async/await\", \"Answers in `\\boxed{}`\").\n- **`gate_mode`** — `on` (default, validation-gated) or `off` (greedy, accept all edits).\n- **`gate_metric`** — `hard`, `soft`, or `mixed` (default). Controls how the held-out gate scores.\n- **`gate_no_regression`** — `false` by default. Set to `true` to reject a candidate when any validation task's configured gate score decreases.\n- **`dream_rollouts`** — >1 enables multi-rollout contrastive reflection per task.\n- **`recall_k`** — >0 recalls K similar past tasks into the dream (long-term memory).\n- **`evolve_memory`** / **`evolve_skill`** — independently toggle CLAUDE.md vs SKILL.md consolidation.\n\n## Memory consolidation\n\nThe sleep cycle can consolidate both:\n- **SKILL.md** — the managed skill file (bounded edits: add/delete/replace)\n- **CLAUDE.md** — the project memory (same bounded edits)\n\nWith the default gate enabled, both are evaluated by the same held-out score.\nSet `evolve_memory: false` to consolidate only skills, or `evolve_skill: false`\nfor only memory.\n\n## Hard rules\n\n- **Never** hand-edit the user's `CLAUDE.md` / `SKILL.md` as part of this skill.\n  Let the engine's explicit `adopt` or user-requested `--auto-adopt` path apply\n  the staging manifest and back up existing live files first.\n- Harvest is read-only. `mock` replay has no side effects.\n- Real backends send truncated transcript excerpts and derived tasks to the\n  selected provider for mining, replay, judging, and reflection. The Claude\n  transcript path is not guaranteed to remove every secret before those calls.\n  Review provider policy and session contents first. For sensitive data, use\n  `mock` or run `harvest --output <file>`, inspect/redact the JSON, set\n  `\"reviewed\": true`, and replay it with `--tasks-file`; real backends refuse an\n  unreviewed task file.\n- Always show the user the **held-out baseline → candidate** score and the\n  exact proposed edits before suggesting adoption. Evidence before adoption.\n- If asked to demonstrate the mechanism without provider calls, run\n  `python -m skillopt_sleep.experiments.run_experiment --persona researcher --json`\n  — a deterministic synthetic demo of held-out lift and gate rejection. It\n  validates the mechanism, not effectiveness on the user's own tasks.\n\n## Validate / demo\n\n```bash\n# deterministic synthetic demo (no API): score rises and the gate blocks a regression\npython -m skillopt_sleep.experiments.run_experiment --persona researcher --assert-improves\npython -m skillopt_sleep.experiments.run_experiment --persona programmer  --assert-improves\n```\n\nSee the [SkillOpt-Sleep documentation](https://github.com/microsoft/SkillOpt/tree/main/docs/sleep)\nfor recorded results, limitations, and the supported integration surface.\n","plugins/codex/README.md":"# SkillOpt-Sleep — Codex integration\n\nGive your **Codex** agent a nightly **sleep cycle**: it reviews past sessions\noffline, replays your recurring tasks on your own Codex budget, and consolidates\nwhat it learns into validated memory + skills behind a held-out gate. Same engine\nas the Claude Code plugin (`skillopt_sleep`), wrapped for Codex.\n\n> **Verified on Codex:** on the public\n> [gbrain-evals](https://github.com/garrytan/gbrain-evals) `skillopt-v1`\n> benchmark, a deliberately deficient skill goes **0.00 → 1.00** on a held-out\n> set with the Codex backend (incl. the tool-use seed via a real tool loop).\n> See the recorded results and limitations in\n> [`docs/sleep/RESULTS.md`](../../docs/sleep/RESULTS.md).\n\n## What Codex supports (and what we use)\n\nCodex (`@openai/codex`) extends via **`AGENTS.md`** instructions, **skills** at\n`~/.agents/skills/<name>/SKILL.md`, and plugins that can distribute skills.\nCustom prompts are deprecated in Codex, so this integration is skill-first: the\ninstalled `skillopt-sleep` skill contains the launch commands and operating\nrules. The shared runner remains a plain shell entrypoint that the skill calls.\n\n## Install\n\nOn Linux/macOS:\n```bash\ngit clone https://github.com/microsoft/SkillOpt.git\ncd SkillOpt\nbash plugins/codex/install.sh          # installs the skill\nexport SKILLOPT_SLEEP_REPO=\"$(pwd)\"    # so the runner is found from anywhere\n```\n\nOn Windows (PowerShell):\n```powershell\ngit clone <repo-url> SkillOpt-Sleep\ncd SkillOpt-Sleep\npowershell -File plugins/codex/install.ps1\n[System.Environment]::SetEnvironmentVariable(\"SKILLOPT_SLEEP_REPO\", \"$(pwd)\", \"User\")\n```\n\nIf a previous install created `~/.codex/prompts/sleep.md`, the installer moves\nthat deprecated prompt aside with a `.skillopt-legacy*.bak` suffix.\n\nRequires Python ≥ 3.10 and the `codex` CLI on PATH.\n\n## Use\n\nMention `$skillopt-sleep` where Codex supports explicit skill mentions, or ask\nCodex in natural language:\n\n```text\nUse the skillopt-sleep skill to run status for this project.\nUse the skillopt-sleep skill to run a dry-run for this project.\nUse the skillopt-sleep skill to run the full cycle for this project with the Codex backend.\nUse the skillopt-sleep skill to inspect status, then adopt the reviewed managed\nproposal or an explicit pending skill subset.\n```\n\nOr call the engine directly:\n\n```bash\npython -m skillopt_sleep dry-run --project \"$(pwd)\" --source codex --backend mock\npython -m skillopt_sleep run --project \"$(pwd)\" --source codex --backend codex \\\n  --max-sessions 5 --max-tasks 3 --progress\npython -m skillopt_sleep run --project \"$(pwd)\" --source codex --backend codex \\\n  --target-skill-path .agents/skills/example/SKILL.md \\\n  --max-sessions 5 --max-tasks 3 --progress\n```\n\n`--source codex` reads Codex Desktop archived sessions from\n`~/.codex/archived_sessions`. Use `--codex-home /path/to/.codex` to point at a\ndifferent Codex home, or `--source auto` to try Codex archives first and fall\nback to Claude Code transcripts. Default backend is `mock` (no API spend).\n`--backend codex` uses your Codex budget for model-driven optimization; an\naccepted gain is task-dependent, not guaranteed. Bound live runs\nwith `--max-sessions` and `--max-tasks`; add `--progress` because Codex-backed\nmining, replay, and reflection can be slow and otherwise quiet. Use\n`--target-skill-path` to stage/adopt into a repo-scoped Codex skill such as\n`.agents/skills/<name>/SKILL.md`; target runs over-sample mined tasks and\nprefer tasks that match the target skill's path, headings, and content. The\nimplemented main-CLI flags work the same across the shared integrations, and\n`--preferences \"...\"` is available for house rules. Advanced keys such as\n`gate_mode`, `gate_no_regression`, `dream_rollouts`, and `recall_k` belong in the Sleep config; the\nnightly CLI does not expose `--gate`, `--rollouts-k`, token/time-budget, or\noptimizer/target-split flags. See the\n[shared CLI reference](../README.md#supported-cli-surface).\n\nFor privacy-sensitive projects, split the run into reviewable steps:\n\n```bash\npython -m skillopt_sleep harvest --project \"$(pwd)\" --source codex \\\n  --target-skill-path .agents/skills/example/SKILL.md \\\n  --max-sessions 5 --max-tasks 3 \\\n  --output reviewed-tasks.json\n\npython -m skillopt_sleep dry-run --project \"$(pwd)\" --backend codex \\\n  --tasks-file reviewed-tasks.json --progress --json\n```\n\nInspect/redact the JSON and set `\"reviewed\": true` before using a real backend.\n`--tasks-file` skips archive harvest/mining and replays only the reviewed JSON\ntasks; real backends refuse task files still marked `\"reviewed\": false`.\n\nThis review step matters even though the Codex transcript converter removes\nknown secret-shaped strings: pattern-based redaction is not a guarantee. A real\nbackend sends truncated transcript/task content to the selected provider, while\n`--backend mock` makes no provider calls.\n\n## Notes / status\n\n- Codex's `exec` runs shell, so the real-tool-loop replay (e.g. the\n  `tool_called: search` benchmark seed) works natively.\n- This integration no longer installs a `.codex/prompts` slash command. Skills\n  are the reusable Codex workflow surface; mention `skillopt-sleep` explicitly\n  or ask for a sleep/dream/offline self-improvement run and Codex can load the\n  skill.\n","plugins/codex/skills/skillopt-sleep/SKILL.md":"---\nname: skillopt-sleep\ndescription: \"Use when the user wants Codex to self-improve from past usage, asks about a nightly/offline 'sleep' or 'dream' cycle, wants Codex to review past sessions, learn preferences, consolidate memory/skills, run dry-run/run/adopt/status for SkillOpt-Sleep, or schedule background self-optimization. Drives the skillopt_sleep engine: harvest past sessions -> mine recurring tasks -> replay through a selected backend -> consolidate validated memory + skills behind a held-out gate.\"\n---\n\n# SkillOpt-Sleep: usage-driven self-evolution for a local Codex agent\n\nSkillOpt-Sleep gives the user's Codex agent a sleep cycle. On demand or on a\nnightly schedule, it reviews past local sessions, re-runs recurring tasks\nthrough the selected backend, and proposes changes to a configured skill and to\nthe project's `CLAUDE.md`. With the default validation gate enabled, it keeps\nonly changes that improve a held-out score. Live files change only through\nexplicit adoption or a user-requested `--auto-adopt`. There is no model-weight\ntraining.\n\nThe current shared engine does **not** write `AGENTS.md`. For a Codex-visible\nresult, always select a Codex skill explicitly with `--target-skill-path` (for\nexample `.agents/skills/<name>/SKILL.md`). If project `CLAUDE.md` is not a\ndesired secondary target, set `\"evolve_memory\": false` in\n`~/.skillopt-sleep/config.json` before running.\n\n## When to use\n\nTrigger when the user wants any of:\n\n- Codex to learn from past sessions or get better the more they use it;\n- a nightly/scheduled or on-demand sleep/dream/offline self-improvement run;\n- to review past sessions and distill recurring tasks;\n- to consolidate feedback into memory or managed skills;\n- to run `status`, `harvest`, `dry-run`, `run`, or `adopt` for SkillOpt-Sleep.\n\n## The cycle\n\n1. **Harvest** - read local session transcripts according to the engine\n   configuration and normalize them into session digests.\n2. **Mine** - turn digests into recurring `TaskRecord`s with outcomes and\n   checkable references where possible.\n3. **Replay** - re-run mined tasks through the selected backend under the\n   current skill and memory.\n4. **Consolidate** - reflect on failures and propose bounded edits.\n5. **Gate** - with the default gate enabled, accept edits only when the held-out\n   validation score improves.\n6. **Stage** - write the proposal under\n   `<project>/.skillopt-sleep/staging/<date>/`; nothing live changes.\n7. **Adopt** - explicitly, or through user-requested auto-adopt, copy staged\n   files over live files with backups for existing targets.\n\n## How to drive it\n\nInvoke the bundled runner via shell (Codex `exec` has shell access). The runner\nfinds the engine and a Python >= 3.10 automatically.\n\n```bash\n# point at the repo if it isn't auto-detected from CWD:\nexport SKILLOPT_SLEEP_REPO=/path/to/SkillOpt\nTARGET_SKILL=.agents/skills/example/SKILL.md\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" status --project \"$(pwd)\"\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" harvest --project \"$(pwd)\" \\\n  --source codex --target-skill-path \"$TARGET_SKILL\"\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" dry-run --project \"$(pwd)\" \\\n  --source codex --target-skill-path \"$TARGET_SKILL\" --backend mock\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" run --project \"$(pwd)\" \\\n  --source codex --target-skill-path \"$TARGET_SKILL\" --backend codex \\\n  --max-sessions 5 --max-tasks 3 --progress\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" status --project \"$(pwd)\"\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" adopt --project \"$(pwd)\" --legacy\n```\n\nFor a fan-out night, select reviewed proposals with repeatable\n`--skill NAME` or `--all-skills`; do not treat bare adopt as “adopt everything.”\n\nOn Windows (CMD / PowerShell):\n```cmd\n:: CMD\nset SKILLOPT_SLEEP_REPO=C:\\path\\to\\SkillOpt-Sleep\n\"%SKILLOPT_SLEEP_REPO%\\plugins\\run-sleep.cmd\" status --project \"%CD%\"\n```\n```powershell\n# PowerShell\n$env:SKILLOPT_SLEEP_REPO = \"C:\\path\\to\\SkillOpt-Sleep\"\npowershell -File \"$env:SKILLOPT_SLEEP_REPO\\plugins\\run-sleep.ps1\" status --project \"$(pwd)\"\n```\n\nActions are `status`, `harvest`, `dry-run`, `run`, `adopt`, `schedule`, and `unschedule`.\n\n- Default backend is `mock`, which is deterministic and spends no API budget.\n- `--backend codex` uses the user's Codex budget for model-driven optimization.\n  An accepted held-out gain is run-specific evidence, not a guarantee of\n  broader improvement; results depend on the tasks, model, and checks.\n- `--source codex` reads Codex Desktop archived sessions from `~/.codex/archived_sessions`;\n  use `--codex-home /path/to/.codex` if the archive lives elsewhere.\n- `--target-skill-path` is required for a Codex skill target. Without it, the\n  shared default is a Claude-managed skill under `~/.claude/skills/`, not an\n  `.agents` skill.\n- Keep `dry-run --backend mock` as the first smoke check unless the user\n  explicitly asked for a real optimization run.\n\n### Scheduling\n\n```bash\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" schedule --project \"$(pwd)\" \\\n  --backend codex --hour 3 --minute 17\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" unschedule --project \"$(pwd)\"\n```\n\nThe scheduler persists the project, backend, time, and optional auto-adopt flag;\nit does not persist `--source` or `--target-skill-path` from this command. Before\nscheduling a Codex-targeted run, set `\"transcript_source\": \"codex\"` and an\nabsolute `\"target_skill_path\"` in `~/.skillopt-sleep/config.json`. On systems\nwithout `crontab`, `schedule` prints a line for manual installation.\n`unschedule --all` removes every managed entry.\n\n### All backends\n\n- `--backend mock` — deterministic, no API spend (default)\n- `--backend claude` — uses the Claude CLI\n- `--backend codex` — uses the Codex CLI\n- `--backend copilot` — uses the GitHub Copilot CLI\n- `--backend handoff` — emits prompt/answer files for an interactive session\n- `--backend azure_openai` — uses the configured Azure OpenAI endpoint\n\n### Additional flags\n\n| Flag | Description |\n|------|-------------|\n| `--auto-adopt` | Auto-adopt if the gate passes (default: stage only) |\n| `--edit-budget N` | Max bounded edits per night (default: 4) |\n| `--lookback-hours N` | Harvest window in hours (default: 72) |\n| `--json` | Machine-readable JSON output |\n\n### Config keys (`~/.skillopt-sleep/config.json`)\n\n- **`preferences`** — free-text house rules for the optimizer\n- **`gate_mode`** — `on` (validation-gated, default) or `off` (greedy)\n- **`gate_metric`** — `hard` | `soft` | `mixed` (default)\n- **`gate_no_regression`** — `false` by default; set it to `true` to reject a candidate when any validation task's gate score decreases\n- **`dream_rollouts`** — >1 for multi-rollout contrastive reflection\n- **`recall_k`** — >0 recalls similar past tasks from the archive\n\n### Memory consolidation\n\nThe shared sleep cycle consolidates project **memory** (`CLAUDE.md`) and the\nselected **skill** (`SKILL.md`) by default. It does not update `AGENTS.md`.\nEach target is independently toggleable through `evolve_memory` /\n`evolve_skill`, and both are gated by the same held-out validation score.\n\n## Steps\n\n1. Run the requested action; capture stdout.\n2. For `dry-run` and `run`, report the held-out baseline -> candidate score,\n   gate action, task count, session count, and exact proposed edits.\n3. If a staging directory is printed, read `report.md` before summarizing.\n4. `run` stages by default; if `--auto-adopt` was explicitly supplied, report\n   the paths it updated instead of claiming nothing changed.\n5. Offer adoption only after the user has reviewed a still-staged proposal.\n6. Never hand-edit the configured `CLAUDE.md` or target skill as a substitute\n   for the engine's adopt path; adoption is the safety boundary and backs up\n   existing targets first.\n\n## Hard rules\n\n- Harvest is read-only. Do not edit archived sessions or raw transcripts.\n- Codex transcript harvesting removes known secret-shaped strings, developer\n  instructions, and raw tool payloads, but pattern-based redaction is not a\n  guarantee. A real backend still sends truncated transcript/task content to\n  its provider. Review sensitive sessions and provider policy first; prefer a\n  reviewed `--tasks-file` workflow when the data boundary matters.\n- Keep raw secrets, credentials, private user data, and transcript contents out\n  of messages, logs, generated artifacts, and commits.\n- Show validation evidence before recommending adoption.\n- Treat generated edits as proposals, not as source of truth.\n- Do not rely on deprecated custom prompts or `/sleep` slash commands for this\n  Codex integration. This skill is the entrypoint.\n\n## Validate\n\n```bash\npython -m skillopt_sleep dry-run --project \"$(pwd)\" --source codex \\\n  --target-skill-path .agents/skills/example/SKILL.md --backend mock --json\npython -m skillopt_sleep.experiments.run_gbrain --backend codex \\\n  --seeds brief-writer --data-root /path/to/gbrain-evals/eval/data/skillopt-v1 \\\n  --nights 2 --limit-replay 3 --limit-holdout 3\n```\n\nIn the recorded `brief-writer` gbrain run, the deliberately deficient fixture\nwent 0.00 -> 1.00 on that run's held-out set. Treat this as reproducible\nbenchmark evidence for that configuration, not a guarantee for other skills,\ntasks, or models; see the\n[recorded results](https://github.com/microsoft/SkillOpt/blob/main/docs/sleep/RESULTS.md)\nfor context and limitations.\n","plugins/copilot/README.md":"# SkillOpt-Sleep — GitHub Copilot integration\n\nGive **Copilot** (CLI or VS Code) a nightly **sleep cycle** via a tiny **MCP\nserver** that exposes the `skillopt_sleep` engine as tools. MCP is GitHub's\nsupported way to extend Copilot, so this works across Copilot CLI, VS Code, and\nother MCP clients with the same server.\n\n## What's here\n\n| File | Purpose |\n|---|---|\n| `mcp_server.py` | stdlib-only MCP (stdio) server exposing `sleep_*` tools |\n| `mcp-config.example.json` | drop-in MCP server config |\n| `copilot-instructions.snippet.md` | paste into `.github/copilot-instructions.md` |\n\n## Install\n\nRequires Python ≥ 3.10. No third-party packages — the server is pure stdlib.\n\n1. **Register the MCP server.** Add the server to your Copilot MCP config\n   (Copilot CLI: `~/.copilot/mcp-config.json`; VS Code: your MCP settings).\n   Use `mcp-config.example.json` as a template — set `SKILLOPT_SLEEP_REPO` to\n   this repo's path:\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"skillopt-sleep\": {\n         \"command\": \"python3\",\n        \"args\": [\"/abs/path/SkillOpt/plugins/copilot/mcp_server.py\"],\n        \"env\": { \"SKILLOPT_SLEEP_REPO\": \"/abs/path/SkillOpt\" }\n       }\n     }\n   }\n   ```\n\n2. **(Optional) Tell Copilot about it.** Append\n   `copilot-instructions.snippet.md` to your repo's\n   `.github/copilot-instructions.md` so Copilot reaches for the tools when the\n   user asks to \"run the sleep cycle\".\n\n## Use\n\nAsk Copilot things like *\"run the sleep cycle\"*, *\"what did the last sleep\npropose?\"*, *\"adopt the staged sleep proposal\"*. The server exposes seven MCP\ntools: `sleep_status`, `sleep_dry_run`, `sleep_run`, `sleep_adopt`,\n`sleep_harvest`, `sleep_schedule`, and `sleep_unschedule`.\n\nEach tool takes optional `project`, `backend`\n(`mock`/`claude`/`codex`/`copilot`/`handoff`), and `scope` arguments. For\n`sleep_adopt`, first inspect `sleep_status`, then use the adoption controls that\nmatch the reviewed staging manifest:\n\n- `staging` — exact staging directory to adopt instead of the latest night\n- `skills` — array of skill names to adopt; each is passed as one repeated\n  `--skill` argument without shell interpolation\n- `all_skills` — adopt every staged per-skill proposal\n- `legacy` — adopt only the legacy managed `SKILL.md`/`CLAUDE.md` pair\n\nChoose one selection mode (`skills`, `all_skills`, or `legacy`) and do not\ncombine them. A bare `sleep_adopt` remains compatible with legacy-only staging;\nfan-out staging requires an explicit selection.\n\nTool results preserve the engine's `exit_code` in `structuredContent`.\nOrdinary nonzero exits set `isError: true`; exit 3 is the expected\n`handoff_pending` state and is not an MCP tool error. With `json: true`, text\ncontent is the engine's parseable JSON stdout, while diagnostics remain\nseparate in `structuredContent`.\n\nDefault backend is `mock` (no API spend). The `copilot` backend drives the\nGitHub Copilot CLI (`copilot -p ... --output-format json`) and requires the\n`copilot` CLI to be installed and authenticated.\n\nHarvesting is local and read-only, and the default `mock` backend makes no\nprovider calls. A real backend sends truncated transcript excerpts and derived\ntasks to the selected provider. Outbound prompts are not currently guaranteed\nto be secret-free; review sensitive data and provider policy first. See the\n[shared data-boundary guidance](../README.md#data-boundary).\n\nFor speed, the `copilot` backend runs each call against an isolated\n`COPILOT_HOME` with built-in MCP servers and custom instructions disabled, so\nyour user MCP servers (including this project's own) are not spawned per call\n(~5x faster). Override with `SKILLOPT_SLEEP_COPILOT_HOME=<dir>`, pick a model\nwith `SKILLOPT_SLEEP_COPILOT_MODEL`, or set `SKILLOPT_SLEEP_COPILOT_FULL_ENV=1`\nto use your real Copilot environment instead.\n\n## Verify the server directly (no Copilot needed)\n\n```bash\nprintf '%s\\n' \\\n  '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{}}' \\\n  '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\"}' \\\n  | SKILLOPT_SLEEP_REPO=\"$(pwd)\" python3 plugins/copilot/mcp_server.py\n```\nYou should see the server info and all seven `sleep_*` tools.\n\n## Notes / status\n\n- MCP is the stable, official Copilot extension surface, so this is the most\n  portable shared-engine integration (one server → CLI + IDE).\n- The MCP schema exposes the main CLI's implemented controls, including task and\n  session caps, target-skill selection, scheduling, and staged adoption. It does\n  not add experiment-only gate, rollout, token/time-budget, or optimizer/target\n  split flags. See the [shared CLI reference](../README.md#supported-cli-surface).\n","plugins/copilot/skillopt/README.md":"# SkillOpt — GitHub Copilot integration\r\n\r\nGive **Copilot** (CLI or VS Code) direct access to the **SkillOpt** research\r\nengine via a tiny **MCP server**. MCP is GitHub's supported way to extend\r\nCopilot, so this works across Copilot CLI, VS Code, and other MCP clients with\r\nthe same server.\r\n\r\nSkillOpt is **validation-gated, text-space skill optimization**: it reflects on\r\nrollouts, makes bounded edits to a skill, and keeps a change only if it improves\r\na held-out validation set. This plugin exposes the repo's training and eval\r\nentry points (`scripts/train.py`, `scripts/eval_only.py`) as Copilot tools.\r\n\r\n> This is the companion to the **SkillOpt-Sleep** plugin (`../mcp_server.py`,\r\n> `sleep_*` tools). Sleep evolves a *local coding agent* from your past\r\n> sessions; this server drives the *research* training/eval loops on the\r\n> benchmark configs in [`../../../configs`](../../../configs).\r\n\r\n## What's here\r\n\r\n| File | Purpose |\r\n|---|---|\r\n| `mcp_server.py` | stdlib-only MCP (stdio) server exposing `skillopt_*` tools |\r\n| `mcp-config.example.json` | drop-in MCP server config |\r\n| `copilot-instructions.snippet.md` | paste into `.github/copilot-instructions.md` |\r\n\r\n## Install\r\n\r\nRequires Python ≥ 3.10. The MCP server itself is pure stdlib, but the tools it\r\nlaunches need SkillOpt's runtime deps — install the package first:\r\n\r\n```bash\r\npip install -e .   # or: pip install -r requirements.txt\r\n```\r\n\r\n1. **Register the MCP server.** Add the server to your Copilot MCP config\r\n   (Copilot CLI: `~/.copilot/mcp-config.json`; VS Code: your MCP settings).\r\n   Use `mcp-config.example.json` as a template — set `SKILLOPT_REPO` to this\r\n   repo's path:\r\n\r\n   ```json\r\n   {\r\n     \"mcpServers\": {\r\n       \"skillopt\": {\r\n         \"command\": \"python3\",\r\n         \"args\": [\"/abs/path/SkillOpt/plugins/copilot/skillopt/mcp_server.py\"],\r\n         \"env\": { \"SKILLOPT_REPO\": \"/abs/path/SkillOpt\" }\r\n       }\r\n     }\r\n   }\r\n   ```\r\n\r\n2. **(Optional) Tell Copilot about it.** Append\r\n   `copilot-instructions.snippet.md` to your repo's\r\n   `.github/copilot-instructions.md` so Copilot reaches for the tools when the\r\n   user asks to \"optimize a skill\" or \"train on a benchmark\".\r\n\r\n## Use\r\n\r\nAsk Copilot things like *\"what configs can I run?\"*, *\"optimize the searchqa\r\nskill\"*, or *\"evaluate this skill on the dataset\"*. Copilot calls the MCP tools:\r\n`skillopt_list_configs`, `skillopt_train`, `skillopt_eval`.\r\n\r\n| Tool | Required args | Notes |\r\n|---|---|---|\r\n| `skillopt_list_configs` | — | Lists `configs/**/*.yaml` you can pass as `config`. |\r\n| `skillopt_train` | `config` | Runs a reflective optimization loop. Long-running; spends budget. |\r\n| `skillopt_eval` | `config`, `skill` | Evaluates one skill markdown file; no training. |\r\n\r\nCommon optional args (both train and eval): `env`, `backend`,\n`optimizer_model`, `target_model`, `out_root`, `cfg_options` (space-separated\n`section.key=value` YAML overrides), and `extra_args` (raw passthrough flags\nfor the underlying script). `skillopt_train` also accepts `num_epochs`,\n`batch_size`, `seed`, and `use_gate`. `use_gate` defaults to `true`; setting it\nto `false` still records validation scores but force-accepts every candidate,\nwhich changes the optimization semantics.\n\nThe MCP schema's `backend` argument follows the underlying script's\n`--backend` choices. Role-specific and generic OpenAI-compatible backends can\nbe selected through config or `extra_args` (for example,\n`--optimizer_backend openai_compatible --target_backend openai_compatible`);\nsee the repository's [backend guide](../../../docs/guide/new-backend.md) for\nthe required environment variables.\n\r\nRuns can be very long. The server's subprocess timeout defaults to 6 hours;\r\noverride it with the `SKILLOPT_RUN_TIMEOUT` environment variable (seconds).\r\n\r\n## Verify the server directly (no Copilot needed)\r\n\r\n```bash\r\nprintf '%s\\n' \\\r\n  '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{}}' \\\r\n  '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\"}' \\\r\n  '{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"skillopt_list_configs\",\"arguments\":{}}}' \\\r\n  | SKILLOPT_REPO=\"$(pwd)\" python3 plugins/copilot/skillopt/mcp_server.py\r\n```\r\n\r\nYou should see the server info, the three `skillopt_*` tools, and the list of\r\nbenchmark configs.\r\n\r\n## Notes / status\r\n\r\n- MCP is the stable, official Copilot extension surface, so this is portable\r\n  across Copilot CLI and IDE from one server.\r\n- `skillopt_list_configs` is filesystem-only and safe to call anytime;\r\n  `skillopt_train` / `skillopt_eval` shell out to the repo scripts and require\r\n  the SkillOpt runtime deps (and, for real backends, model credentials — see\r\n  [`../../../.env.example`](../../../.env.example)).\r\n","plugins/cursor/.cursor-plugin/plugin.json":"{\n  \"name\": \"skillopt-sleep\",\n  \"displayName\": \"SkillOpt-Sleep\",\n  \"version\": \"0.1.0\",\n  \"description\": \"Review recent Cursor sessions, replay recurring work, and stage validation-gated improvements to a Cursor skill for explicit adoption.\",\n  \"author\": {\n    \"name\": \"Yifan Yang\",\n    \"email\": \"yifanyang@microsoft.com\"\n  },\n  \"homepage\": \"https://github.com/microsoft/SkillOpt\",\n  \"repository\": \"https://github.com/microsoft/SkillOpt\",\n  \"license\": \"MIT\",\n  \"keywords\": [\n    \"skillopt\",\n    \"cursor\",\n    \"self-improvement\",\n    \"memory-consolidation\",\n    \"sleep\",\n    \"skills\",\n    \"offline-optimization\"\n  ],\n  \"category\": \"developer-tools\",\n  \"tags\": [\n    \"automation\",\n    \"memory\",\n    \"transcripts\"\n  ],\n  \"commands\": \"./commands/\",\n  \"skills\": \"./skills/\"\n}\n","plugins/cursor/README.md":"# SkillOpt-Sleep - Cursor integration\n\nGive Cursor an on-demand or explicitly scheduled sleep cycle: review recent\nlocal Cursor sessions, replay recurring tasks through a selected backend, and\nstage validation-gated improvements to a project Cursor skill. Nothing runs at\nsession end, and nothing live changes until the user adopts an accepted staged\nproposal (unless they explicitly request `--auto-adopt`).\n\nThis package is a native Cursor plugin containing a command and an agent skill.\nIt does not install hooks or an MCP server.\n\n## Requirements\n\n- Cursor with plugin and agent-skill support.\n- Python 3.10 or newer.\n- Either a SkillOpt source checkout or an installed `skillopt-sleep` command.\n- For `--backend cursor`, an installed and authenticated Cursor Agent CLI\n  (`cursor-agent`). The default `mock` backend needs no provider login or spend.\n\nThe plugin and transcript harvester work on native Windows. Cursor documents\nthe Agent CLI for Windows through WSL; run provider-backed `--backend cursor`\ninside WSL unless a native `cursor-agent` is available in your environment.\n\n## Install the local plugin\n\nClone the repository, then run the installer for your platform.\n\nmacOS or Linux:\n\n```bash\ngit clone https://github.com/microsoft/SkillOpt.git\ncd SkillOpt\nbash plugins/cursor/install.sh\nexport SKILLOPT_SLEEP_REPO=\"$(pwd)\"\n```\n\nWindows PowerShell:\n\n```powershell\ngit clone https://github.com/microsoft/SkillOpt.git\nSet-Location SkillOpt\npowershell -File plugins/cursor/install.ps1\n[System.Environment]::SetEnvironmentVariable(\"SKILLOPT_SLEEP_REPO\", \"$(pwd)\", \"User\")\n```\n\nThe installer copies the plugin to\n`~/.cursor/plugins/local/skillopt-sleep` (or\n`%USERPROFILE%\\.cursor\\plugins\\local\\skillopt-sleep`). Quit and reopen Cursor\nafter changing user environment variables, then confirm that **SkillOpt-Sleep**\nappears in Settings > Plugins under Installed.\n\nThe plugin and engine have separate installation boundaries. The copied plugin\nteaches Cursor how to operate SkillOpt-Sleep; the engine still runs from the\nsource checkout through `plugins/run-sleep.sh` / `plugins/run-sleep.ps1`, or\nfrom an installed command:\n\n```bash\nuv tool install skillopt\n# or: python -m pip install skillopt\n```\n\nUse a release that includes Cursor source/backend support when choosing the\ninstalled-command route. The source-checkout route uses the implementation in\nthe checkout directly.\n\n## Use from Cursor\n\nRun the native command, for example:\n\n```text\n/skillopt-sleep status\n/skillopt-sleep dry-run --backend mock --max-sessions 5 --max-tasks 3\n/skillopt-sleep run --backend cursor --max-sessions 5 --max-tasks 3 --progress\n/skillopt-sleep adopt --legacy\n```\n\nFor fan-out proposals, inspect `status` and use repeatable `--skill NAME` or\n`--all-skills`. Bare adopt deliberately refuses a night containing fan-out rows.\n\nThe `skillopt-sleep` agent skill remains independently available if a Cursor\nversion does not surface plugin commands.\n\nThe native command's default Cursor-visible target is:\n\n```text\n.cursor/skills/skillopt-sleep-learned/SKILL.md\n```\n\nUse `--target-skill-path` with that value on harvest, dry-run, and run commands.\nWithout an explicit target, the shared engine defaults to a Claude-managed\nskill, which Cursor does not load as a project skill.\n\n### Source-checkout commands\n\nmacOS or Linux:\n\n```bash\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" status --project \"$(pwd)\"\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" dry-run \\\n  --project \"$(pwd)\" --source cursor --backend mock \\\n  --target-skill-path .cursor/skills/skillopt-sleep-learned/SKILL.md\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" run \\\n  --project \"$(pwd)\" --source cursor --backend cursor \\\n  --target-skill-path .cursor/skills/skillopt-sleep-learned/SKILL.md \\\n  --max-sessions 5 --max-tasks 3 --progress\n```\n\nWindows PowerShell:\n\n```powershell\npowershell -File \"$env:SKILLOPT_SLEEP_REPO\\plugins\\run-sleep.ps1\" status --project \"$(pwd)\"\npowershell -File \"$env:SKILLOPT_SLEEP_REPO\\plugins\\run-sleep.ps1\" dry-run `\n  --project \"$(pwd)\" --source cursor --backend mock `\n  --target-skill-path .cursor/skills/skillopt-sleep-learned/SKILL.md\npowershell -File \"$env:SKILLOPT_SLEEP_REPO\\plugins\\run-sleep.ps1\" run `\n  --project \"$(pwd)\" --source cursor --backend cursor `\n  --target-skill-path .cursor/skills/skillopt-sleep-learned/SKILL.md `\n  --max-sessions 5 --max-tasks 3 --progress\n```\n\n### Installed-command equivalents\n\n```bash\nskillopt-sleep status --project \"$(pwd)\"\nskillopt-sleep dry-run --project \"$(pwd)\" --source cursor --backend mock \\\n  --target-skill-path .cursor/skills/skillopt-sleep-learned/SKILL.md\nskillopt-sleep run --project \"$(pwd)\" --source cursor --backend cursor \\\n  --target-skill-path .cursor/skills/skillopt-sleep-learned/SKILL.md \\\n  --max-sessions 5 --max-tasks 3 --progress\nskillopt-sleep status --project \"$(pwd)\"\nskillopt-sleep adopt --project \"$(pwd)\" --legacy\n```\n\n`--source cursor` reads local JSONL transcripts below\n`~/.cursor/projects/<workspace>/agent-transcripts/`. Use\n`--cursor-home /path/to/.cursor` for a different Cursor home. Invoked scope\nselects the current workspace; `--scope all` includes every Cursor workspace.\nThe source converter retains user/assistant text, tool names, and explicit turn\nerrors, but excludes raw tool arguments and outputs.\n\nThe first harvest uses a 72-hour lookback by default. Use\n`--lookback-hours N` to choose a wider initial window, or\n`--lookback-hours 0` to consider all available history while still respecting\n`--max-sessions`. A successful `run`, including one that mines no tasks,\nrecords a new harvest checkpoint. Later runs use that checkpoint instead of\nthe initial lookback. Use `harvest` or `dry-run` to inspect session and task\ncounts before the first stateful run; neither action advances the checkpoint.\n\n`--backend cursor` invokes the authenticated Cursor Agent CLI. Use\n`--cursor-path /path/to/cursor-agent` or `SKILLOPT_SLEEP_CURSOR_PATH` if it is\nnot on PATH, and `--model` or `SKILLOPT_SLEEP_CURSOR_MODEL` to override its\nmodel. Check available identifiers with `cursor-agent --list-models` and verify\nthe billed variant in Cursor's usage reporting when cost matters. The child\nprocess receives only an explicit runtime/authentication/locale/proxy/CA\nenvironment allowlist; unrelated cloud and model-provider credentials are not\nforwarded.\n\n## What Cursor replay evaluates\n\nSkillOpt reads the target skill and inserts its text into mined task prompts. It\ndoes not invoke that file as a native Cursor skill or execute commands described\nby the skill. All ordinary Cursor model calls, including mining, replay,\njudging, and reflection, run in a new empty temporary workspace in read-only Ask\nmode. File reads, file writes, and MCP tools are denied. `--project` selects the\ntranscript scope, target files, state, and staging location; it does not make the\nproject the Cursor Agent execution workspace.\n\nCursor tool-aware replay is temporarily disabled pending live Cursor\npermission-boundary validation. Tasks containing a `tool_called` check fail\nnonzero before Agent mode starts. The failed replay does not add a cache entry,\nstage, adopt, persist state, or advance the harvest checkpoint. Use another\nbackend for those tasks.\n\nThis replay is useful for textual procedures, response conventions, and output\nformats. It is not an end-to-end evaluation of skills that depend on repository\ninspection, real CLIs, browsers, running services, or filesystem changes. There\nis currently no Cursor option that enables a fresh project worktree or real\nproject tools. The `replay: mock` report label refers to the prompt-replay mode,\nnot to the selected model backend.\n\nThe shared engine also supports `mock`, `claude`, `codex`, `copilot`,\n`handoff`, and `azure_openai` backends. Cursor is the native model-driven\nchoice for this integration; `mock` remains the no-provider default.\n\n## Review sensitive data before provider calls\n\nHarvesting is local and read-only, and `--backend mock` makes no provider calls.\nKnown secret-shaped strings are redacted from harvested Cursor content, and raw\ntool payloads are excluded, but pattern-based redaction is not a guarantee.\nA real backend sends truncated transcript excerpts and derived tasks to that\nbackend's provider for mining, replay, judging, and reflection.\n\nBoth `run` and `dry-run` perform those real-backend calls; `dry-run` prevents\nstaging but does not prevent provider spend. `--max-sessions` and `--max-tasks`\nbound harvested work, not provider calls, tokens, elapsed time, or money. One\ntask can require several attempt, judge, and reflection calls. Start with small\nlimits and review the provider's usage reporting before increasing them.\n\nFor sensitive work, split the flow at the review boundary:\n\n```bash\nskillopt-sleep harvest --project \"$(pwd)\" --source cursor \\\n  --target-skill-path .cursor/skills/skillopt-sleep-learned/SKILL.md \\\n  --max-sessions 5 --max-tasks 3 --output reviewed-tasks.json\n\nskillopt-sleep dry-run --project \"$(pwd)\" --backend cursor \\\n  --tasks-file reviewed-tasks.json --progress --json\n```\n\nInspect and redact the JSON, then set its top-level `\"reviewed\"` field to\n`true`. Real backends reject task files that remain unreviewed. Keep raw\ntranscripts, credentials, and task files out of commits.\n\n## Scheduling\n\nRuns remain user-triggered unless the user explicitly schedules them. Before\nscheduling, put the Cursor source and target in\n`~/.skillopt-sleep/config.json`, because the scheduler persists the project,\nbackend, time, and optional auto-adopt flag, but not command-line source or\ntarget overrides:\n\n```json\n{\n  \"transcript_source\": \"cursor\",\n  \"target_skill_path\": \".cursor/skills/skillopt-sleep-learned/SKILL.md\",\n  \"cursor_home\": \"/absolute/path/to/.cursor\",\n  \"backend\": \"cursor\"\n}\n```\n\nThen schedule or remove the managed entry:\n\n```bash\nskillopt-sleep schedule --project \"$(pwd)\" --backend cursor --hour 3 --minute 17\nskillopt-sleep unschedule --project \"$(pwd)\"\n```\n\nOn Unix this uses cron; on Windows it uses Task Scheduler. Scheduled runs stage\nproposals for later review by default. Do not add `--auto-adopt` unless the user\nhas explicitly chosen unattended adoption.\n\n## Adoption and memory\n\n`run` stages accepted proposals under\n`<project>/.skillopt-sleep/staging/<timestamp>/`. Read the staged `report.md`\nand show the held-out baseline-to-candidate score plus exact edits before\nrunning `adopt`. Adoption backs up an existing target before replacing it.\n\nThe shared engine may also propose project `CLAUDE.md` memory updates; existing\nmemory behavior is unchanged. To restrict a Cursor setup to the explicit Cursor\nskill, set `\"evolve_memory\": false` in `~/.skillopt-sleep/config.json`.\n\nThere is deliberately no session-end hook or automatic plugin execution.\n","plugins/cursor/skills/skillopt-sleep/SKILL.md":"---\nname: skillopt-sleep\ndescription: \"Use when the user wants Cursor to learn from recent local sessions, asks for an offline sleep or dream cycle, wants to consolidate recurring work into a Cursor skill, or requests SkillOpt-Sleep status, harvest, dry-run, run, scheduling, review, or adoption. Drives the validation-gated skillopt_sleep engine with Cursor transcripts and the optional Cursor Agent CLI backend.\"\n---\n\n# SkillOpt-Sleep for Cursor\n\nSkillOpt-Sleep reviews recent local Cursor sessions, mines recurring tasks,\nreplays those tasks, and proposes bounded improvements to a project Cursor\nskill. With the default gate enabled, a proposal is accepted only when it\nimproves the held-out score. A normal run stages the proposal for review;\nnothing live changes until explicit adoption. There is no model-weight training.\n\nThis plugin has no session-end hook and no MCP server. Run the cycle only when\nthe user asks, or install a schedule only when the user explicitly requests one.\n\n## Cursor target\n\nAlways use this project-relative target for Cursor-visible learning:\n\n```text\n.cursor/skills/skillopt-sleep-learned/SKILL.md\n```\n\nPass it through `--target-skill-path` on `harvest`, `dry-run`, and `run`.\nWithout an explicit target, the shared engine uses a Claude-managed skill under\n`~/.claude/skills`, which is not the intended Cursor project skill.\n\nThe shared engine can also evolve project `CLAUDE.md`. If that secondary memory\ntarget is unwanted, set `\"evolve_memory\": false` in\n`~/.skillopt-sleep/config.json` before running.\n\n## Choose the runner\n\nUse one of these supported command paths consistently:\n\n1. Source checkout on macOS/Linux:\n   `bash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" <action> ...`\n2. Source checkout on Windows:\n   `powershell -File \"$env:SKILLOPT_SLEEP_REPO\\plugins\\run-sleep.ps1\" <action> ...`\n3. Installed engine on any platform:\n   `skillopt-sleep <action> ...`\n\nIf `SKILLOPT_SLEEP_REPO` is not set and `skillopt-sleep` is unavailable, stop\nand explain that the engine must be installed or a SkillOpt checkout must be\nselected. Do not substitute a hand-written edit for the engine workflow.\n\n## Core workflow\n\n1. **Harvest** local Cursor JSONL transcripts read-only.\n2. **Mine** recurring, checkable task records from session digests.\n3. **Replay** tasks under the current skill and memory through the selected\n   backend.\n4. **Reflect** on failures and propose bounded edits.\n5. **Gate** the candidate on held-out real tasks.\n6. **Stage** accepted proposals under\n   `<project>/.skillopt-sleep/staging/<timestamp>/`.\n7. **Adopt** only after review, backing up existing live targets first.\n\n## Commands\n\nUse the installed-command form below, or replace `skillopt-sleep` with the\nplatform-specific source runner described above.\n\n```bash\nTARGET_SKILL=.cursor/skills/skillopt-sleep-learned/SKILL.md\n\n# Inspect current state and the latest staged proposal.\nskillopt-sleep status --project \"$(pwd)\"\n\n# Inspect mined tasks without provider spend.\nskillopt-sleep harvest --project \"$(pwd)\" --source cursor \\\n  --target-skill-path \"$TARGET_SKILL\" --max-sessions 5 --max-tasks 3\n\n# First smoke check: deterministic and no provider calls.\nskillopt-sleep dry-run --project \"$(pwd)\" --source cursor --backend mock \\\n  --target-skill-path \"$TARGET_SKILL\" --max-sessions 5 --max-tasks 3 --json\n\n# Model-driven optimization through the authenticated Cursor Agent CLI.\nskillopt-sleep run --project \"$(pwd)\" --source cursor --backend cursor \\\n  --target-skill-path \"$TARGET_SKILL\" \\\n  --max-sessions 5 --max-tasks 3 --progress\n\n# Inspect selections, then apply the reviewed managed proposal.\nskillopt-sleep status --project \"$(pwd)\"\nskillopt-sleep adopt --project \"$(pwd)\" --legacy\n```\n\nFor fan-out proposals, use repeatable `--skill NAME` or `--all-skills` after\nreview. Bare adopt deliberately refuses a night containing fan-out rows.\n\nActions are `status`, `harvest`, `dry-run`, `run`, `adopt`, `schedule`, and\n`unschedule`.\n\n- Default backend is `mock`, which is deterministic and makes no provider calls.\n- `--backend cursor` uses the user's authenticated Cursor Agent CLI budget for\n  model-driven mining, replay, judging, and reflection.\n- `--source cursor` reads\n  `~/.cursor/projects/<workspace>/agent-transcripts/*/*.jsonl`.\n- `--cursor-home PATH` overrides the Cursor home used for harvesting.\n- `--scope invoked` selects the current workspace; `--scope all` includes every\n  Cursor workspace.\n- `--cursor-path PATH` or `SKILLOPT_SLEEP_CURSOR_PATH` selects a non-default\n  `cursor-agent` executable.\n- `--model NAME` or `SKILLOPT_SLEEP_CURSOR_MODEL` overrides the Cursor model.\n- Check model identifiers with `cursor-agent --list-models`; when cost matters,\n  verify the billed variant in Cursor's usage reporting.\n- Keep live runs bounded with `--max-sessions`, `--max-tasks`, and `--progress`.\n- A held-out gain is evidence for that run, not a promise of general improvement.\n\nThe first harvest uses a 72-hour lookback. Use `--lookback-hours N` for a wider\ninitial window or `--lookback-hours 0` for all available history. A stateful\n`run`, including a no-task run, records a harvest checkpoint; later runs use the\ncheckpoint rather than the initial lookback. Inspect counts with `harvest` or\n`dry-run` before the first real run because those actions do not advance state.\n\nAvailable backends are:\n\n- `mock` - deterministic, with no provider calls (default);\n- `cursor` - the authenticated Cursor Agent CLI;\n- `claude` - the authenticated Claude CLI;\n- `codex` - the authenticated Codex CLI;\n- `copilot` - the authenticated GitHub Copilot CLI;\n- `handoff` - prompt/answer files for an interactive agent session;\n- `azure_openai` - the configured Azure OpenAI endpoint.\n\nSkillOpt reads the target skill and inserts its text into replay prompts; it does\nnot invoke the file as a native Cursor skill. Ordinary Cursor backend calls run\nin a new empty temporary workspace in read-only Ask mode. File reads, file\nwrites, and MCP tools are denied. `--project` controls harvesting, target files,\nstate, and staging; it is not the Cursor Agent execution workspace.\n\nCursor tool-aware replay is temporarily disabled pending live Cursor\npermission-boundary validation. A task containing a `tool_called` check fails\nnonzero before Agent mode starts. The failed replay does not add a cache entry,\nstage, adopt, persist state, or advance the harvest checkpoint. Use another\nbackend for those tasks. Do not claim that repository- or tool-dependent\nbehavior was validated. The current engine does not implement a fresh-worktree\nreplay for Cursor.\n\nA real-backend `dry-run` still makes provider calls; it only suppresses staging.\nSession and task limits are workload bounds, not hard limits on calls, tokens,\ntime, or money. Start with small limits.\n\n## Reviewable data path\n\nCursor harvesting retains user/assistant text, tool names, and explicit turn\nerrors while excluding raw tool arguments, tool outputs, and non-message\nrecords. Known secret-shaped strings are redacted, but pattern-based redaction\ncannot guarantee that a transcript is safe to send to a provider.\n\nFor sensitive sessions, export tasks before any real-backend replay:\n\n```bash\nTARGET_SKILL=.cursor/skills/skillopt-sleep-learned/SKILL.md\nskillopt-sleep harvest --project \"$(pwd)\" --source cursor \\\n  --target-skill-path \"$TARGET_SKILL\" \\\n  --max-sessions 5 --max-tasks 3 --output reviewed-tasks.json\n```\n\nInspect and redact the file, then set its top-level `\"reviewed\"` field to\n`true`. Only then run:\n\n```bash\nskillopt-sleep dry-run --project \"$(pwd)\" --backend cursor \\\n  --tasks-file reviewed-tasks.json --progress --json\n```\n\nReal backends reject task files that remain unreviewed. Never include raw\ntranscripts, credentials, secrets, or sensitive task content in messages,\ncommits, or generated summaries.\n\n`gate_no_regression` is a config-only safeguard in\n`~/.skillopt-sleep/config.json`. It defaults to `false`; set it to `true` to\nreject a candidate when any validation task's configured gate score decreases.\n\n## Scheduling\n\nScheduling is opt-in. The scheduler persists project, backend, time, and the\noptional auto-adopt flag, but not `--source`, Cursor path/home/model overrides,\nor `--target-skill-path`. Before scheduling a Cursor cycle, set at least these values in\n`~/.skillopt-sleep/config.json`:\n\n```json\n{\n  \"transcript_source\": \"cursor\",\n  \"target_skill_path\": \".cursor/skills/skillopt-sleep-learned/SKILL.md\",\n  \"backend\": \"cursor\"\n}\n```\n\nThen run:\n\n```bash\nskillopt-sleep schedule --project \"$(pwd)\" --backend cursor --hour 3 --minute 17\nskillopt-sleep unschedule --project \"$(pwd)\"\n```\n\nThe scheduler uses cron on Unix and Task Scheduler on Windows. Scheduled runs\nstage proposals by default. Use `--auto-adopt` only when the user has explicitly\nrequested unattended adoption.\n\n## Report results\n\nFor `dry-run` and `run`, report:\n\n- session and task counts;\n- held-out baseline and candidate scores;\n- gate action and accepted/rejected edit counts;\n- exact proposed edits;\n- staging directory, when one was created.\n\nRead staged `report.md` before summarizing a run. Offer adoption only after the\nuser reviews an accepted proposal that is still staged. Never claim broad\nimprovement from one run.\n\n## Hard rules\n\n- Harvest is read-only. Never edit Cursor transcript files.\n- Never hand-edit the target skill or `CLAUDE.md` as a substitute for adoption.\n- Do not run a real backend on sensitive content without confirming its data\n  boundary or using the reviewed-task workflow.\n- Do not add a session-end hook or imply that installing this plugin schedules\n  anything.\n- Show validation evidence before recommending adoption.\n- Treat generated edits as proposals, not as source of truth.\n","plugins/devin/README.md":"# SkillOpt-Sleep — Devin integration\n\nGive **Devin** (Cognition) a nightly **sleep cycle** via a tiny **MCP server**\nthat exposes the `skillopt_sleep` engine as tools. MCP is Devin's supported way\nto add custom tooling, so this works in Devin's CLI and IDE.\n\nDevin doesn't write transcripts in the format the engine consumes, so this\nplugin adds a **Devin-specific harvester** that converts every locally available\nsource into the Claude Code-compatible JSONL the engine reads.\n\n## What's here\n\n| File | Purpose |\n|---|---|\n| `mcp_server.py` | stdlib-only MCP (stdio) server exposing `sleep_*` tools |\n| `harvest_devin.py` | converts Devin ATIF-v1.7 transcripts + agentmemory + `.devin/skills` into JSONL, with `taskKey` + outcome envelopes |\n| `judge.py` | reference judge for the deferred/judge branch of the validation gate |\n| `mcp-config.example.json` | drop-in MCP server config |\n| `install.sh` | copies hooks + rules into a project's `.devin/` and prints the MCP registration command |\n| `devin-rules.snippet.md` | copied to `.devin/rules/skillopt-sleep.md` by `install.sh` |\n| `hooks/hooks.v1.json` | SessionEnd hook config — installed/merged at `.devin/hooks.v1.json` by `install.sh` |\n| `hooks/on-session-end.sh` | best-effort activity marker script (called by the hook) |\n\n## What it harvests\n\n| Source | Where |\n|---|---|\n| Devin transcripts (ATIF-v1.7) | `~/.local/share/devin/cli/transcripts/*.json` |\n| agentmemory | `~/.agentmemory/standalone.json` |\n| Skill files | `.devin/skills/*/SKILL.md` |\n\nWorkspaces are auto-detected from `~/.config/Devin/User/workspaceStorage/*/workspace.json`.\nThe adapter performs no post-adoption copy. The core engine applies a reviewed\nproposal directly to its selected target and owns backup/rollback behavior.\n\n## Install\n\nRequires Python ≥ 3.10. No third-party packages — the server is pure stdlib.\n\n1. **Install hooks + rules into your project.** From the repo root:\n\n   ```bash\n   bash plugins/devin/install.sh /path/to/your/project\n   ```\n\n   This copies the SessionEnd hook and rules snippet into the project's\n   `.devin/` directory and prints the MCP registration command. The hook is\n   on by default — it logs a cheap activity marker for local inspection or\n   external automation when each session ends. The current engine harvests by\n   transcript timestamps and does not consume this marker directly. The hook\n   is non-blocking and spends no API budget. Re-run the script to update; the\n   installer preserves existing hooks and does not duplicate its own entry.\n\n2. **Register the MCP server.** Use `mcp-config.example.json` as a template, or\n   run the command printed by `install.sh`:\n\n   ```bash\n   devin mcp add skillopt-sleep \\\n     --env \"SKILLOPT_DEVIN_CLAUDE_HOME=$HOME/.skillopt-sleep-devin\" \\\n     -- python3 /abs/path/to/SkillOpt/plugins/devin/mcp_server.py\n   ```\n\n3. Ask Devin: *\"run the sleep cycle\"*, *\"what did the last sleep propose?\"*, *\"adopt it\"*.\n\n## Tools\n\n| Tool | What it does |\n|---|---|\n| `sleep_status` | nights run so far + latest staged proposal |\n| `sleep_dry_run` | preview cycle — no staging; a real backend still makes provider calls |\n| `sleep_run` | full cycle; stages a proposal for review |\n| `sleep_adopt` | apply a reviewed legacy or per-skill proposal (with backup) |\n| `sleep_harvest` | debug: list the recurring tasks mined |\n| `sleep_schedule` | install a nightly cron entry (`--hour` / `--minute`) |\n| `sleep_unschedule` | remove the nightly cron entry |\n\nBefore `sleep_adopt`, inspect `sleep_status` and use the controls that match the\nreviewed staging manifest:\n\n- `staging` — exact staging directory to adopt instead of the latest night\n- `skills` — array of skill names to adopt; each is forwarded as one repeated\n  `--skill` argument without shell interpolation\n- `all_skills` — adopt every staged per-skill proposal\n- `legacy` — adopt only the legacy managed `SKILL.md`/`CLAUDE.md` pair\n\nChoose one selection mode (`skills`, `all_skills`, or `legacy`) and do not\ncombine them. A bare call remains compatible with legacy-only staging; fan-out\nstaging requires an explicit selection. To operate on a specific Devin skill,\npass its `SKILL.md` as `target_skill_path`; the adapter never performs a second\ncopy after the core engine returns.\n\nTool results preserve the engine's `exit_code` in `structuredContent`.\nOrdinary nonzero exits set `isError: true`; exit 3 is the expected\n`handoff_pending` state and is not an MCP tool error. With `json: true`, text\ncontent is the engine's parseable JSON stdout, while harvest and engine\ndiagnostics remain separate in `structuredContent`.\n\nDefault backend is `mock` (no API spend); the `claude`, `codex`, and `copilot`\nbackends use the corresponding authenticated CLI and budget. The `handoff`\nbackend runs the cycle with no model subprocess or API key — the engine writes\npending model calls to `.skillopt-sleep-handoff/PROMPTS.md` + `pending.json`\n(exit code 3) and resumes after answers are placed in `answers/<id>.md`; re-run\n`sleep_run` with the same arguments to resume. The seven tools call the same\n`python -m skillopt_sleep` actions as the other shared-engine integrations.\n\n## Data boundary\n\nThe Devin harvester reads local ATIF transcripts, agentmemory, and skill files\nand converts them into the engine's session format. The `mock` backend keeps\nthat workflow local. A real backend sends truncated excerpts and derived tasks\nto the selected provider for mining, replay, judging, and reflection. The\nconversion step is not a guarantee that outbound prompts contain no secrets;\nreview sensitive sources and provider policy before enabling a real backend.\nSee the [shared data-boundary guidance](../README.md#data-boundary) and\n[implemented CLI reference](../README.md#supported-cli-surface).\n","plugins/dsh/README.md":"# SkillOpt-Sleep — DeepSeek Harness (dsh) integration\n\nGive your **DeepSeek Harness** agent a nightly **sleep cycle**: it reviews past\nsessions offline, replays your recurring tasks on your own API budget, and\nconsolidates what it learns into validated skills behind a held-out gate. Same\nengine as the Claude Code / Codex / Cursor integrations\n([skillopt_sleep](https://github.com/microsoft/SkillOpt)), wired into dsh's\nplugin system as native tools plus a bundled skill.\n\nDeepSeek Harness is the \"everything is a plugin\" agent framework\n([deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness)).\nPlugins are TypeScript modules exporting an `apply(ctx)` function that register\ncapabilities (tools, services, events, settings) on the Cordis context.\n\n## Why a sleep cycle?\n\nSkills improve when an agent re-examines its own sessions — not just when you\nhand-tune a prompt. The sleep cycle turns your everyday usage into a nightly,\nvalidation-gated skill-improvement loop: harvest what you actually did, replay\nthe recurring tasks on your own API budget, and keep only the changes that pass\na held-out gate. It's the same engine as the Claude Code / Codex / Cursor\nintegrations, wired into dsh as native tools plus a bundled skill.\n\n## What this integration adds\n\n| Component | Purpose |\n|---|---|\n| `src/index.js` | dsh plugin entry: registers 7 `skillopt_*` tools + Schemastery config |\n| `cordis.patch.yml` | bundle patch layer — drop `dsh-skillopt` into any profile's bundles |\n| `skills/skillopt-sleep/SKILL.md` | agent skill: when to use the tools, operating rules, data-boundary rules |\n| `scripts/sleep.py` | bootstrap/self-check runner (same command shape the tools use) |\n| `package.json` | npm package metadata (bundle manifest) |\n\n## Tools\n\n| Tool | skillopt_sleep action | Behavior |\n|---|---|---|\n| `skillopt_status` | `status` | state, engine availability, latest staged proposal & report |\n| `skillopt_dry_run` | `dry-run` | full preview (harvest+mine+replay), stages nothing |\n| `skillopt_run` | `run` | full cycle, stages a proposal (live files unchanged) |\n| `skillopt_adopt` | `adopt` | apply latest staged proposal (with backup) — the live-change boundary |\n| `skillopt_harvest` | `harvest` | read-only show/export of mined tasks |\n| `skillopt_schedule` / `skillopt_unschedule` | `schedule` / `unschedule` | install/remove the nightly cron entry |\n\n## Prerequisites\n\n- DeepSeek Harness (dsh) installed — dsh 0.1.x and 0.2.x are supported\n  (`@deepseek-ai/dsh-tools` 0.1.1-rc.2, 0.2.0-rc.2)\n- Python 3.10+ with the SkillOpt-Sleep engine:\n\n```bash\npip install skillopt          # or use this source checkout\n```\n\n## Install\n\n### As a bundle in a profile\n\nAdd `dsh-skillopt` to the profile's bundles, or in the profile `cordis.patch.yml`:\n\n```yaml\n- insert:\n    - id: skillopt\n      name: './src/index.js'\n      config:\n        backend: mock          # or codex / claude / cursor / pi / opencode / handoff …\n        project: /path/to/project\n        preferences: 'Always use async/await'\n```\n\n### Local patch overlay (dev)\n\nRun from a DeepSeek Harness **source checkout** (the official dev workflow,\n`pnpm` resolves the workspace `dsh` bin):\n\n```bash\npnpm dsh web --patch ./plugins/dsh/cordis.patch.yml\n```\n\nIf `dsh` is installed **globally** (npm install -g), use it directly:\n\n```bash\ndsh web --patch ./plugins/dsh/cordis.patch.yml\n```\n\nEither way the patch inserts the `skillopt` plugin row into the profile; then\nask the agent: \"Use skillopt_status to check the sleep cycle state.\"\n\n## Config keys\n\n| Key | Default | Purpose |\n|---|---|---|\n| `pythonCmd` | `python` | Python interpreter for the engine |\n| `module` | — (bootstrap) | engine Python module override (`python -m <module>`) |\n| `engineScript` | — (scripts/sleep.py) | engine bootstrap script override |\n| `project` | — | default project directory |\n| `scope` | — | harvest scope: `all` \\| `invoked` |\n| `backend` | — | `mock\\|claude\\|codex\\|copilot\\|cursor\\|pi\\|opencode\\|handoff\\|azure_openai` |\n| `source` | — | `claude\\|codex\\|copilot\\|cursor\\|pi\\|opencode\\|auto` |\n| `model` | — | backend model override |\n| `maxTasks` / `maxSessions` | — | mine/harvest caps |\n| `editBudget` | — | bounded edits per cycle |\n| `preferences` | — | house rules for the reflection prior |\n| `jsonOutput` | `false` | machine-readable JSON output |\n| `autoAdopt` | `false` | OPERATOR-ONLY: auto-adopt a passed proposal without asking |\n| `unscheduleAll` | `false` | OPERATOR-ONLY: allow `skillopt_unschedule` to remove every managed entry |\n| `timeoutMs` | `600000` | per-call engine timeout in milliseconds |\n\nAdvanced engine keys (`gate_mode`, `gate_metric`, `gate_no_regression`,\n`dream_rollouts`, `recall_k`, `evolve_memory`/`evolve_skill`) go in\n`~/.skillopt-sleep/config.json` — the same file shared by all integrations.\n\n## Data boundary\n\n- Harvest is read-only; `mock`/`handoff` make no network calls.\n- `run` stages proposals; `adopt` is the normal live-change boundary and backs up first.\n- Real backends send truncated transcript excerpts and derived tasks to the\n  selected provider. For sensitive sessions, export tasks first (`skillopt_harvest`\n  with `output=`), redact, set `\"reviewed\": true`, then replay — real backends\n  refuse unreviewed task files.\n- Outbound prompts are not guaranteed secret-free; review source & provider policy.\n\n## Validate (no API spend)\n\n```bash\npython -m skillopt_sleep.experiments.run_experiment --persona researcher --assert-improves\n```\n\nSee the [SkillOpt-Sleep documentation](../../docs/sleep/README.md) for recorded\nresults, limitations, and the supported integration surface.\n","plugins/dsh/skills/skillopt-sleep/SKILL.md":"---\nname: skillopt-sleep\ndescription: \"Use when the user wants the dsh agent to self-improve from past usage, asks about a nightly/offline 'sleep' or 'dream' cycle, skill/memory consolidation, or says things like 'make my agent better the more I use it', 'review my past sessions', 'learn my preferences', 'consolidate what you learned', 'run the sleep cycle', or wants to schedule background self-optimization. Drives the skillopt_sleep engine through the skillopt_* tools: harvest past sessions -> mine recurring tasks -> replay via a selected backend -> consolidate validated skills behind a held-out gate.\"\n---\n\n# SkillOpt-Sleep: usage-driven self-evolution for the dsh agent\n\nSkillOpt-Sleep is Microsoft's [SkillOpt](https://github.com/microsoft/SkillOpt)\ndeployment-time companion engine: it reviews your past sessions (harvest), mines\nrecurring tasks (mine), replays them through a selected backend (replay), and\nconsolidates what it learns into skill documents behind a **held-out validation\ngate** (consolidate).\n\nThis skill drives the engine through the 7 `skillopt_*` tools exposed by the\ndsh-skillopt plugin. The default `mock` backend makes no model calls, which is\nuseful for verifying the plumbing; a real backend consumes your API budget.\n\n## When to use\n\n- \"make my agent better the more I use it\" / \"learn my preferences across sessions\"\n- a one-off **offline self-evolution / sleep / dream** run (immediate or scheduled)\n- review past sessions/trajectories and distill recurring tasks\n- consolidate feedback into `AGENTS.md` / `SKILL.md` / managed skills\n- schedule (cron) the cycle, or adopt a staged proposal\n\n## The cycle (six stages)\n\n1. **Harvest** — read-only scan of supported local session records → digests\n2. **Mine** — digests → recurring task records (intent + outcome labels + checkable refs)\n3. **Replay** — re-run tasks under the current skill+memory with the selected backend → (hard, soft) scores\n4. **Consolidate** — reflect on failures → propose bounded edits → **validation gate** on a held-out slice (default: accept only on strict improvement)\n5. **Stage** — write accepted proposals to `<project>/.skillopt-sleep/staging/<timestamp>/`. **Live files are unchanged.** A rejected run still has a report but no proposal files.\n6. **Adopt** — explicit (or operator-configured `--auto-adopt`) copies staged files over live ones, backing up first.\n\n## Driving it\n\nPrefer the tools over hand-editing files:\n\n| Tool | Behavior |\n|---|---|\n| `skillopt_status` | state, engine availability, latest staged proposal & report |\n| `skillopt_dry_run` | full preview (harvest+mine+replay), stages nothing |\n| `skillopt_run` | full cycle, stages a proposal (live files unchanged by default) |\n| `skillopt_adopt` | apply latest staged proposal (with backup) — the live-change boundary |\n| `skillopt_harvest` | read-only show/export of mined tasks |\n| `skillopt_schedule` / `skillopt_unschedule` | install/remove the nightly cron entry for this project |\n\nTypical flow:\n\n```text\n# 1. check state (default mock backend, zero cost)\nskillopt_status\n\n# 2. preview the cycle\nskillopt_dry_run project=<dir> source=<claude|codex|…>\n\n# 3. real run (consumes the selected backend's API budget)\nskillopt_run project=<dir> backend=<codex|claude|…> preferences=\"Prefer pytest; keep commits imperative.\"\n\n# 4. review the report, then adopt\nskillopt_adopt project=<dir>\n\n# 5. schedule nightly at 03:17\nskillopt_schedule project=<dir> hour=3 minute=17 backend=<codex>\n```\n\n## Parameters\n\n| Parameter | Default | Meaning |\n|---|---|---|\n| `project` | config or cwd | project directory to evolve |\n| `backend` | `mock` | `mock\\|claude\\|codex\\|copilot\\|cursor\\|pi\\|opencode\\|handoff\\|azure_openai` (mock = no model calls) |\n| `source` | config | transcript source: `claude\\|codex\\|copilot\\|cursor\\|pi\\|opencode\\|auto` |\n| `model` | backend default | replay model override |\n| `maxTasks` | 40 | mined-task cap |\n| `preferences` | empty | house rules for the reflection prior (e.g. \"always use async/await\") |\n\n## Configuration (cordis.yml / bundle patch)\n\n```yaml\n- insert:\n    - id: skillopt\n      name: './src/index.js'\n      config:\n        backend: codex\n        project: /path/to/project\n        preferences: 'Always use async/await'\n        # auto-adopt is OPERATOR-ONLY — the model cannot set it\n        autoAdopt: false\n```\n\nAdvanced engine keys go in `~/.skillopt-sleep/config.json`:\n`gate_mode` (on/off), `gate_metric` (hard/soft/mixed), `gate_no_regression`,\n`dream_rollouts`, `recall_k`, `evolve_memory` / `evolve_skill`.\n\n## Hard rules\n\n- **Never** hand-edit `AGENTS.md` / `SKILL.md` around `skillopt_adopt`; let the\n  engine's explicit adopt (or operator-configured `--auto-adopt`) apply the\n  staging manifest, backing up live files first.\n- Harvest is read-only; `mock` replay has no side effects.\n- Real backends send truncated transcript excerpts and derived tasks to the\n  selected provider for mining/replay/judging/reflection. For sensitive\n  sessions, export tasks first (`skillopt_harvest output=<file>`), redact, set\n  the top-level `\"reviewed\"` to `true`, then replay with `--tasks-file`; real\n  backends refuse unreviewed task files.\n- Show the user the **held-out baseline → candidate** score and the exact\n  proposed edits before suggesting adoption. Evidence before adoption.\n\n## Validate / demo (no API spend)\n\n```bash\npip install skillopt\npython -m skillopt_sleep.experiments.run_experiment --persona researcher --assert-improves\n```\n\nDeterministic synthetic demo: the score rises and the gate blocks a regression.\nIt validates the mechanism, not effectiveness on your own tasks.\n\nSee the [SkillOpt-Sleep docs](https://github.com/microsoft/SkillOpt/tree/main/docs/sleep)\nfor recorded results and limitations.\n","plugins/openclaw/README.md":"# OpenClaw reference adaptation for SkillOpt-Sleep\n\nThis directory is a contributed reference for connecting\n[SkillOpt-Sleep](https://github.com/microsoft/SkillOpt) to\n[OpenClaw](https://github.com/openclaw/openclaw) with a custom DeepSeek/Ollama\nbackend.\n\n> **Reference status.** This is not one of the shared, plug-and-play\n> `skillopt_sleep` wrappers. Several scripts and the sample config contain\n> environment-specific absolute paths and assumptions from the original setup,\n> and the contributed wrapper has unresolved Python 3.10 syntax and backend\n> factory-signature gaps. The current checkout is not directly runnable; treat\n> it as porting source material, not an installation.\n\n## Included components\n\n| File | Purpose |\n|---|---|\n| `run_sleep.py` | custom cycle entry point |\n| `skillopt_sleep_openclaw.py` | DeepSeek Chat Completions backend plus local Ollama embeddings |\n| `run_sleep_cron.sh` | category-oriented cron wrapper |\n| `slash_sleep.py` | experimental `/sleep` command helper |\n| `config.json` | example engine configuration |\n| `SKILL.md` | OpenClaw skill manifest |\n| `tests/*.json` | example task sets for research, DevOps, and wiki workflows |\n\nThe adaptation imports the shared engine but registers its own backend and\nmaintains its own wrapper behavior. Changes to the shared CLI documentation do\nnot automatically make every option available through these custom scripts.\n\n## Intended cycle\n\n```text\nharvest supported session data or load a task file\n  → replay with the current skill\n  → propose bounded edits\n  → validate the candidate on held-out tasks\n  → stage a proposal for operator review\n```\n\nThe intended safety boundary is manual adoption: review the generated report and\nstaged files before changing a live skill.\n\n## Adapt before use\n\n1. Clone SkillOpt into a location you control:\n\n   ```bash\n   git clone https://github.com/microsoft/SkillOpt.git\n   cd SkillOpt/plugins/openclaw\n   ```\n\n2. Inspect and replace the sample absolute paths in `run_sleep.py`,\n   `slash_sleep.py`, `run_sleep_cron.sh`, and `config.json`. Confirm the engine\n   checkout, OpenClaw workspace, state directory, skill directory, and task-file\n   paths all point to isolated test locations.\n\n3. Review `config.json`. In particular, do not assume that values such as\n   `replay_mode` are enforced by this custom wrapper merely because they appear\n   in the example config. `max_tokens_per_night` is applied by the shared cycle,\n   but it is measured with the wrapper backend's rough `tokens_used()` estimate\n   (a quarter of the attempt prompt length plus 200 per attempt, 600 per rubric\n   judge call, and a third of the reflect prompt plus 1500 per reflect call), so\n   it is not a billing limit.\n\n4. Supply credentials through your normal secret-management mechanism. Do not\n   commit a DeepSeek key or place it in a world-readable file.\n\n5. Resolve every known porting gap listed in [`SKILL.md`](SKILL.md), add\n   isolated tests for your adapted backend, and verify that `--help` imports\n   cleanly on Python 3.10+. Only then start with a dry run and one reviewed\n   task file. The target command should be shaped like:\n\n   ```bash\n   cd /path/to/SkillOpt/plugins/openclaw\n   python3 run_sleep.py --config /path/to/reviewed-config.json \\\n     --tasks tests/research-cron-tasks.json --dry-run\n   ```\n\n6. Inspect the report, paths, network destinations, and proposed edits before\n   considering a non-dry run or scheduling.\n\n## Data boundary\n\nThe custom `openclaw-deepseek` backend sends task, skill, response, rubric, and\nreflection content to the configured DeepSeek endpoint. Its embedding helper can\nsend truncated text to the configured local Ollama service. Do not assume these\noutbound prompts have been fully redacted; inspect transcript/task inputs and the\nprovider's retention policy before using real data.\n\nUse HTTPS for a remote DeepSeek-compatible endpoint. Keep any plaintext Ollama\nendpoint on a trusted loopback interface. For a network-free engine smoke test,\nuse the shared SkillOpt-Sleep CLI with `--backend mock` rather than assuming this\ncustom wrapper is isolated.\n\n## Scheduling\n\n`run_sleep_cron.sh` and the scheduling helpers are examples, not portable\ninstallers. Adapt their paths, create log directories, verify their environment,\nand run the exact command manually before adding a cron entry. Scheduled runs\nmust preserve the same manual-adoption and credential boundaries as interactive\nruns.\n\n## Validation scope\n\nThe bundled JSON files are example held-out task sets, not a universal OpenClaw\nbenchmark. Provider cost and quality depend on the selected model, task content,\nnumber of calls, and pricing at run time; this reference does not promise a fixed\nnightly cost. Validate the adapted workflow in an isolated workspace before\nusing it on live skills.\n\nFor the supported shared-engine CLI and its current flags, see the\n[integration reference](../README.md#supported-cli-surface). For measured\nSkillOpt-Sleep results and limitations, see\n[`docs/sleep/RESULTS.md`](../../docs/sleep/RESULTS.md).\n\n## License\n\nMIT, consistent with SkillOpt core.\n","plugins/openclaw/SKILL.md":"---\nname: skillopt-sleep\ndescription: Reference-only OpenClaw adaptation of SkillOpt-Sleep. Use it to study or port the contributed DeepSeek wrapper, not as a ready-to-run installation.\n---\n\n# SkillOpt-Sleep OpenClaw reference adaptation\n\nThis directory is a contributed **reference**, not a supported, plug-and-play\nOpenClaw integration. It illustrates one way to connect the shared\n`skillopt_sleep` cycle to a custom DeepSeek Chat Completions backend and a set of\nenvironment-specific task fixtures.\n\nDo not run or schedule the files unchanged. Several scripts and the sample\nconfiguration preserve assumptions from the contributor's original machine,\nand parts of the wrapper have not yet been ported to the current shared-engine\ninterfaces. Start with the directory's [README.md](README.md), which is the\nauthoritative status and adaptation guide.\n\n## What is included\n\n- `skillopt_sleep_openclaw.py` — a contributed DeepSeek backend prototype. It\n  also contains an Ollama embedding helper, but that helper is not wired into\n  the current shared sleep cycle.\n- `run_sleep.py` — a custom cycle wrapper with environment-specific paths and a\n  backend-registration shim.\n- `slash_sleep.py` — an experimental command helper written for an older\n  staging-manifest shape.\n- `run_sleep_cron.sh` — a machine-specific category runner, not a portable cron\n  installer.\n- `config.json` — a sample configuration, not a set of guaranteed or enforced\n  runtime limits.\n- `tests/*.json` — example task fixtures from one environment, not a universal\n  OpenClaw benchmark.\n\n## Known porting gaps\n\nBefore treating this as an integration, a maintainer must at least:\n\n1. Replace every absolute workspace, repository, state, skill, log, and task\n   path with explicit user configuration.\n2. Update the custom backend factory to the current `get_backend` call contract,\n   including the project directory, and update its backend methods and edit\n   records to the current protocol.\n3. Replace the experimental adoption logic with the current staging manifest\n   and `skillopt_sleep.staging.adopt` behavior. Current staging artifacts use\n   `proposed_SKILL.md` / `proposed_CLAUDE.md`, `manifest.json`, and report files;\n   they do not expose the old `manifest.proposed_skill` field.\n4. Decide how real OpenClaw transcripts are converted into a supported session\n   format. Pointing `claude_home` at an arbitrary agent directory does not by\n   itself make its files Claude Code-compatible JSONL.\n5. Build scheduling around the adapted wrapper. The shared scheduler launches\n   the shared CLI; it does not automatically preserve this custom backend or\n   its category task-file flow.\n6. Add isolated end-to-end tests for dry-run, accepted/rejected gates, staging,\n   adoption and backup, credential failure, and scheduled execution.\n\nUntil those gaps are resolved, use the supported shared\n`python -m skillopt_sleep` CLI with `--backend mock` to test SkillOpt-Sleep itself,\nand treat this directory only as source material for a future OpenClaw port.\n\n## Shared-engine features are not wrapper features\n\nAt this revision the supported shared CLI backends are `mock`, `claude`,\n`codex`, `copilot`, `handoff`, and `azure_openai`; the\n[plugin integration reference](../README.md#supported-cli-surface) is the\nauthoritative list. The shared engine can consolidate a selected skill and\nproject `CLAUDE.md` memory (controlled by `evolve_skill` and `evolve_memory`),\nand its `schedule` / `unschedule` actions manage shared-engine cron entries.\nThose capabilities do **not** make the custom OpenClaw wrapper portable: the\nshared scheduler will not invoke the prototype backend or its category\nfixtures. Use the shared documentation for those features, not this reference\nSKILL.\n\n## Data and credential boundary\n\nThe prototype DeepSeek backend sends task, skill, memory, response, rubric, and\nreflection content to its configured Chat Completions endpoint. Its source also\ncontains a helper that can send text to an Ollama service if a future port wires\nthat helper into the cycle. Neither path should be assumed to remove every\nsecret or private detail.\n\nBefore any port is tested with real data:\n\n- use isolated, synthetic or explicitly reviewed task files;\n- replace sample business names, personal references, URLs, and machine paths;\n- load credentials through the operator's secret-management mechanism;\n- verify TLS and retention policy for every remote endpoint; and\n- inspect all staged artifacts before adoption.\n\nThe bundled fixtures are examples only. Their scores and any old cost estimates\ndo not establish effectiveness, safety, or a stable nightly price for another\nOpenClaw deployment.\n\n## Further information\n\n- [OpenClaw README](README.md) — current reference status and adaptation checklist\n- [plugin integration reference](../README.md) — supported shared-engine CLI\n  surface and data boundary\n- [SkillOpt-Sleep documentation](../../docs/sleep/README.md) — concepts,\n  results, and limitations\n\nContributions that turn this reference into a portable integration should add\ntests and update all three documents together.\n","skillopt/envs/alfworld/skills/initial.md":"# ALFWorld Embodied Agent Skill\n\n## Overview\nThis skill guides agents operating in the ALFWorld text-based embodied environment.\nThe agent must complete household tasks by navigating rooms, interacting with objects,\nand using appliances. Actions must be chosen from the admissible action list provided\nat each step.\n\n**Output format**: Always output `<think>...</think>` for reasoning, then `<action>...</action>` for the chosen action.\n\n---\n\n## Task Types\n\n| Type | Goal | Key Steps |\n|------|------|-----------|\n| Pick & Place | Put object X in/on receptacle Y | Find X -> take X -> go to Y -> put X in/on Y |\n| Pick Two & Place | Put two instances of X in/on Y | Find X1 -> take -> place -> find X2 -> take -> place |\n| Examine in Light | Examine object X under desklamp | Find X -> take X -> find desklamp -> use desklamp |\n| Clean & Place | Clean object X and put in/on Y | Find X -> take X -> go to sink -> clean X -> go to Y -> put X |\n| Heat & Place | Heat object X and put in/on Y | Find X -> take X -> go to microwave -> heat X -> go to Y -> put X |\n| Cool & Place | Cool object X and put in/on Y | Find X -> take X -> go to fridge -> cool X -> go to Y -> put X |\n\n---\n\n## General Principles\n\n1. **Decompose the task**: Parse the goal into ordered sub-goals (locate, acquire, transform, deliver). Complete each before moving to the next.\n2. **Systematic exploration**: Search each surface and container exactly once before revisiting. Open closed containers (drawers, cabinets, fridge) before judging them empty.\n3. **Grab immediately**: When a required object is visible and reachable, take it right away before moving elsewhere.\n4. **Transform before placing**: If the task requires cleaning, heating, or cooling, perform the state change at the appropriate appliance before heading to the final destination.\n5. **Direct delivery**: Once holding the transformed (or untransformed) goal object, navigate straight to the target receptacle and place it.\n6. **Track progress**: Maintain an internal count of how many objects still need to be found and placed. Only stop searching when the count reaches zero.\n7. **Avoid loops**: Never repeat the same action more than twice in a row. If stuck, move to a different unexplored location.\n8. **Only choose admissible actions**: Always pick an action from the admissible action list. Do not invent actions.\n\n---\n\n## Common Mistakes to Avoid\n\n- **Revisiting searched locations**: Keep track of which surfaces/containers have been checked; do not re-examine them.\n- **Ignoring visible objects**: If the target object appears in the observation, pick it up immediately.\n- **Skipping state changes**: Do not place an object at the destination without first cleaning/heating/cooling it when required.\n- **Premature termination**: Do not stop the episode until all goal conditions are verified as met.\n- **Action loops**: Repeatedly toggling or examining the same object wastes steps. Move on to new locations instead.\n","skillopt/envs/docvqa/skills/initial.md":"# DocVQA Skill\n\n## Visual Evidence Discipline\n- Read the document carefully before answering.\n- Prefer the smallest exact text span that answers the question.\n- When several nearby strings look similar, choose the one whose surrounding labels or layout best match the question.\n\n## Exact Answer Discipline\n- Copy names, numbers, and dates exactly from the document whenever possible.\n- Prefer direct extraction over paraphrase.\n- Before finalizing, compare the answer against nearby alternatives and keep the best-supported exact span.\n","skillopt/envs/livemathematicianbench/skills/initial.md":"# Live Mathematical MCQ Heuristics\n\n## Option Comparison\n- Compare all options before committing. The correct choice is often the strongest statement justified by the question, while nearby distractors are weaker, overstrong, or miss an equality case.\n- Track exact quantifiers such as \"there exists\", \"for every\", \"if and only if\", and \"exactly when\".\n\n## Theorem-Level Precision\n- Check whether an option weakens the conclusion by dropping a characterization, equality clause, or full equivalence.\n- Check whether an option overstates the theorem by upgrading regularity, removing scale restrictions, or changing an existential statement into a universal one.\n\n## Hypotheses\n- Verify the hypotheses and domain carefully. Distractors often keep the theorem shape but alter the required assumptions.\n- Pay close attention to equality cases, extremal conditions, and whether a result applies to the full family or only a restricted subfamily.\n\n## Final Answer\n- Output the final answer as the single option label only.\n","skillopt/envs/officeqa/skills/initial.md":"# OfficeQA Skill\n\n## Retrieval Discipline\n- Start by narrowing to the most likely candidate file before reading long passages.\n- Prefer targeted search terms that name the exact entity, period, measure, or table concept from the question.\n- After a promising match, read only a small surrounding span and verify it matches the requested year, basis, and unit.\n\n## Evidence Discipline\n- Extract the exact value from the retrieved text before doing any arithmetic.\n- Keep track of each operand's period, unit, and semantic role so nearby proxy values are not mixed in.\n- If the question asks for a transformed or derived quantity, compute only after confirming every operand.\n\n## Final Answer Discipline\n- Return the final answer only after one last consistency check against the retrieved evidence.\n- Copy the final answer from a checked value, not from an unverified intermediate guess.\n","skillopt/envs/searchqa/skills/initial.md":"# Question Answering Skill\n\n(No learned rules yet. Rules will be added through the reflection process.)\n","skillopt/envs/spreadsheetbench/skills/initial.md":"# Spreadsheet Manipulation Skill (xlsx)\n\n## Overview\nThis skill guides agents in manipulating Excel (.xlsx) spreadsheets using Python.\n\n**Primary libraries**: `openpyxl` (structure-preserving read/write), `pandas` (data transformation).\nNever use any other third-party libraries.\n\n---\n\n## Common Workflow\n\n1. **Explore** the input file: list sheets, inspect headers, check dimensions.\n2. **Write `solution.py`** with `INPUT_PATH` and `OUTPUT_PATH` defined at the top.\n3. **Execute** `python solution.py` and verify the output file was created.\n4. **Confirm** the target cells/range contain the expected values.\n\n---\n\n## Library Selection\n\n| Use case | Library |\n|----------|---------|\n| Preserve formulas, formatting, named ranges | `openpyxl` |\n| Bulk data transformation, aggregation, sorting | `pandas` → write back with `openpyxl` |\n| Simple cell read/write | `openpyxl` |\n\n**Warning**: `pandas.to_excel()` silently destroys existing formulas and named ranges.\nWhen writing back to a spreadsheet that contains formulas, always use `openpyxl.save()`.\n\n---\n\n## solution.py Template\n\n```python\nimport openpyxl\nimport pandas as pd\n\nINPUT_PATH  = \"...\"   # set to the actual input path\nOUTPUT_PATH = \"...\"   # set to the actual output path\n\nwb = openpyxl.load_workbook(INPUT_PATH)\nws = wb.active  # or wb[\"SheetName\"]\n\n# --- perform manipulation ---\n\nwb.save(OUTPUT_PATH)\n```\n\n---\n\n## Output Requirements\n\n- Save the result to `OUTPUT_PATH`.\n- Do not hardcode row counts or column letters — iterate over actual rows in the workbook.\n- Preserve sheets and cells not mentioned in the instruction.\n"},"files":{".cursor-plugin/marketplace.json":"{\n  \"name\": \"skillopt\",\n  \"owner\": {\n    \"name\": \"Yifan Yang\",\n    \"email\": \"yifanyang@microsoft.com\"\n  },\n  \"metadata\": {\n    \"description\": \"Official SkillOpt plugins for usage-driven, validation-gated agent improvement.\"\n  },\n  \"plugins\": [\n    {\n      \"name\": \"skillopt-sleep\",\n      \"source\": \"plugins/cursor\",\n      \"description\": \"Review recent Cursor sessions, replay recurring work, and stage validation-gated improvements to a Cursor skill for explicit adoption.\"\n    }\n  ]\n}\n","plugins/README.md":"# SkillOpt-Sleep integrations\n\n**SkillOpt-Sleep** reviews recent agent sessions, mines recurring tasks, replays\nthem, and proposes bounded updates to memory and skills. A held-out validation\ngate decides whether a proposal is worth staging, and nothing live changes until\nthe user explicitly adopts it.\n\nThe shared engine lives in [`skillopt_sleep/`](../skillopt_sleep) and has no\nruntime dependency on the paper's `skillopt/` experiment package.\n\n## Available integrations\n\nSix integrations wrap the shared `skillopt_sleep` CLI. OpenClaw is a separate\nreference adaptation with its own backend and setup assumptions.\n\n| Platform | Folder | Mechanism | Status |\n|---|---|---|---|\n| **Claude Code** | [`claude-code/`](claude-code) | marketplace plugin, commands, skill, and hooks | installable shared-engine integration |\n| **Codex** | [`codex/`](codex) | user-level skill and shared runner | installable shared-engine integration |\n| **Cursor** | [`cursor/`](cursor) | native command and skill, project skill target, and shared runner | installable shared-engine integration |\n| **GitHub Copilot** | [`copilot/`](copilot) | MCP server exposing seven `sleep_*` tools | shared-engine MCP integration |\n| **Devin** | [`devin/`](devin) | MCP server plus Devin transcript conversion | shared-engine MCP integration |\n| **DeepSeek Harness** | [`dsh/`](dsh) | Cordis plugin: 7 native `skillopt_*` tools, skill, bundle patch layer | installable shared-engine integration |\n| **OpenClaw** | [`openclaw/`](openclaw) | custom DeepSeek/Ollama wrapper | independent reference adaptation; review and adapt before use |\n\n## Install\n\nClone the repository first unless an installed `skillopt-sleep` CLI is sufficient\nfor your workflow.\n\n| Platform | Install | Then |\n|---|---|---|\n| **Claude Code** | from the repository root, `/plugin marketplace add ./plugins/claude-code`, then `/plugin install skillopt-sleep@skillopt-sleep` | `/skillopt-sleep status` |\n| **Codex** | `bash plugins/codex/install.sh` | ask Codex to use the `skillopt-sleep` skill |\n| **Cursor** | `bash plugins/cursor/install.sh` (macOS/Linux) or `powershell -File plugins/cursor/install.ps1` (Windows) | `/skillopt-sleep status` |\n| **Copilot** | register `plugins/copilot/mcp_server.py` using its example MCP config | ask Copilot to run `sleep_status` |\n| **Devin** | register `plugins/devin/mcp_server.py` using its example MCP config | ask Devin to run `sleep_status` |\n| **DeepSeek Harness** | add `dsh-skillopt` to the profile's bundles, or patch it in — from a DSH source checkout: `pnpm dsh web --patch ./plugins/dsh/cordis.patch.yml`; with global dsh: `dsh web --patch ./plugins/dsh/cordis.patch.yml` | ask the agent to use `skillopt_status` |\n| **OpenClaw** | follow and adapt [`openclaw/README.md`](openclaw/README.md) | validate paths, credentials, and tasks locally |\n\nPython 3.10 or newer is required. Real CLI backends also require the selected\nagent CLI to be installed and authenticated.\n\nThe shared [`run-sleep.sh`](run-sleep.sh) supports both source checkouts and\ninstalled packages. If it cannot find the repository, it tries the\n`skillopt-sleep` executable on `PATH` (including `uv tool`/`pipx` installs), then\nan importable `skillopt_sleep` module. Install with `uv tool install skillopt` or\n`pip install skillopt` when using that fallback.\n\n> **Version note.** This integration reference tracks `main`. PyPI 0.2.0\n> supports the base Sleep CLI, while Cursor source/backend/plugin support,\n> Pi source/backend support, handoff, Sleep support for non-Azure\n> OpenAI-compatible endpoints, OpenCode Sleep source/backend support, and\n> `--preferences`, multi-skill fan-out, and reviewed subset adoption require a\n> source checkout from `main` until the next release.\n\n## One sleep cycle\n\n```text\nharvest supported local sessions → mine recurring tasks → replay tasks\n  → reflect and propose bounded edits → validate on held-out real tasks\n  → stage proposal → (you) review and adopt\n```\n\nThe default backend is `mock`: it makes no provider calls and is useful for\nchecking plumbing. A real backend is required for model-driven mining and genuine\noptimization.\n\n## Data boundary\n\n- Harvesting is local and read-only. The `mock` and `handoff` backends make no\n  network calls; handoff writes prompts for separate, user-controlled completion.\n- A real backend sends mining, replay, judging, and reflection prompts derived\n  from truncated transcript excerpts and tasks to the selected provider.\n- The Cursor source reads local user/assistant message text, explicit turn\n  errors, and tool names from `~/.cursor/projects/*/agent-transcripts`; it does\n  not retain tool arguments, tool outputs, or other record types. Known\n  secret-shaped strings are redacted, but this is defense in depth rather than\n  a guarantee that outbound prompts are secret-free.\n- The Cursor backend sends prompts through the installed, authenticated\n  `cursor-agent` CLI. Ordinary calls use read-only Ask mode in a new empty\n  temporary workspace with project file access denied. Cursor tasks containing\n  `tool_called` validation fail before Agent mode starts; use another backend for\n  those tasks. Cursor and the model provider selected by Cursor can receive the\n  resulting prompt content.\n- The Pi backend sends prompts through the installed, authenticated Pi CLI to\n  the provider configured by the user. It disables tools, skills, context files,\n  extensions, prompt templates, themes, and session writes for these calls, but\n  retains the user's Pi authentication and model configuration. Pi's offline\n  startup mode prevents configured npm/git package installation, package\n  updates, and model-catalog refresh; it does not prevent the selected provider\n  call. These controls are not a guarantee of permanent or complete isolation.\n- The Pi source retains user/assistant text, tool names, and lexical feedback\n  found in user text. It excludes thinking, tool arguments, tool outputs, images,\n  and unrelated metadata. The absolute project `cwd` from the session header is\n  retained for scope filtering and may appear in miner prompts sent to a real\n  backend and its provider. Known secret-shaped strings in retained message text\n  are redacted only as defense in depth.\n- The core `opencode` source reads local OpenCode SQLite history without the\n  CLI, authentication, or provider access. See\n  [the CLI reference](../docs/reference/cli.md#opencode-source-and-backend) for\n  its retained-data boundary.\n- The core `opencode` backend uses the installed OpenCode CLI. Plain calls\n  disable project configuration, model-initiated tool invocation, external\n  plugins, and configured MCP servers. Tool-aware replay requires explicit\n  opt-in. It exposes only temporary synthetic tools with randomized names and\n  fixed results, then verifies which tools OpenCode actually invoked. See the\n  [CLI reference](../docs/reference/cli.md#opencode-source-and-backend) for\n  history and isolation details. A native OpenCode plugin or command is not\n  included.\n- Outbound prompts are not currently guaranteed to be free of secrets. Do not\n  use a third-party provider on sensitive transcripts without reviewing the data\n  source and the provider's retention policy.\n- For a reviewable workflow, export tasks first, inspect and redact the JSON, set\n  its top-level `\"reviewed\"` field to `true`, and then use the task file with a\n  real backend:\n\n  ```bash\n  python -m skillopt_sleep harvest --project \"$(pwd)\" --output reviewed-tasks.json\n  python -m skillopt_sleep dry-run --project \"$(pwd)\" --backend codex \\\n    --tasks-file reviewed-tasks.json --progress\n  ```\n\n  Real backends reject task files that are still marked unreviewed.\n\nFor the separate API-key and Azure managed-identity transport boundaries, see\n[OpenAI-compatible endpoints](../docs/sleep/openai-compatible-endpoints.md).\n\n## Supported CLI surface\n\nActions:\n\n| Action | Behavior |\n|---|---|\n| `status` | show state and the latest staged proposal |\n| `dry-run` | harvest, mine, replay, and report; stage nothing |\n| `run` | run the full cycle and stage a proposal |\n| `adopt` | apply the latest staged proposal, with backups |\n| `harvest` | inspect or export mined tasks |\n| `schedule` / `unschedule` | install or remove the managed nightly cron entry |\n\nCommon implemented flags include:\n\n| Flag | Default | Purpose |\n|---|---|---|\n| `--backend mock\\|claude\\|codex\\|cursor\\|copilot\\|pi\\|opencode\\|handoff\\|azure_openai` | `mock` | select who performs model calls |\n| `--model NAME` | backend default | select a backend-specific model |\n| `--source claude\\|codex\\|copilot\\|cursor\\|pi\\|opencode\\|auto` | `claude` | select the transcript source; `auto` retains Codex-then-Claude precedence and does not select Copilot, Cursor, Pi, or OpenCode |\n| `--cursor-home PATH` | `~/.cursor` | override the Cursor transcript home |\n| `--cursor-path PATH` | auto-detect `cursor-agent` | select the Cursor Agent CLI executable |\n| `--pi-home PATH` | `~/.pi` | select the parent directory containing `agent/sessions` |\n| `--pi-path PATH` | auto-detect `pi` | select the Pi coding-agent CLI executable |\n| `--opencode-path PATH` | `SKILLOPT_SLEEP_OPENCODE_PATH`, then `opencode` on `PATH`/`PATHEXT` | select the OpenCode CLI executable |\n| `--opencode-db PATH` | `OPENCODE_DB`, `%LOCALAPPDATA%`/`%APPDATA%` (Windows), or `${XDG_DATA_HOME:-~/.local/share}/opencode/opencode.db` | select the OpenCode SQLite history database |\n| `--opencode-tool-replay` | off | enable OpenCode tool-aware replay for `tool_called` checks in rule judges |\n| `--project PATH` | current directory | select the project and invoked harvest scope |\n| `--scope invoked\\|all` | `invoked` | limit transcript harvesting |\n| `--target-skill-path PATH` | managed skill | select a specific `SKILL.md` to stage/adopt |\n| `--tasks-file PATH` | none | replay a reviewed task file instead of harvesting |\n| `--max-sessions N` / `--max-tasks N` | unset → `3 × tasks` / `40` tasks | bound harvested work; these are not hard token or wall-clock budgets |\n| `--edit-budget N` | `4` | cap bounded edits per cycle |\n| `--preferences \"...\"` | empty | add house rules to the reflection prior |\n| `--progress` | off | print phase progress to stderr |\n| `--auto-adopt` | off | adopt an accepted proposal without a separate command |\n| `--json` | off | emit machine-readable output where supported |\n\nThe nightly CLI does **not** currently expose `--gate`, `--rollouts-k`,\n`--optimizer-model`, `--target-model`, `--budget-tokens`, or `--budget-minutes`.\nDo not pass experiment-harness flags to the main CLI.\n\nFor the Cursor backend, `--project` also selects target files, state, and the\nstaging location, but it does not make that directory the Cursor Agent execution\nworkspace. The target skill is inserted as prompt text rather than invoked as a\nnative skill. Real-backend `dry-run` performs the same mining and replay model\ncalls while suppressing staging, adoption, and persisted state changes. The\ncurrent Sleep cycle does not implement fresh-worktree replay; a `replay: mock`\nreport label describes prompt replay and is independent of `--backend mock`.\n\n### Preferences\n\n`--preferences` is the main user-facing steering knob:\n\n```bash\npython -m skillopt_sleep run --backend codex --project \"$(pwd)\" \\\n  --preferences \"Prefer pytest. Keep commit subjects imperative and concise.\"\n```\n\nPreferences guide reflection but remain subject to the validation gate.\n\n### Pi source and backend\n\nPi transcript harvesting is explicit: `--source pi` reads session JSONL files\nbelow `~/.pi/agent/sessions`; use `--pi-home` to select the parent directory\nthat contains `agent/sessions`. This source does not require the Pi CLI or\nprovider authentication. It retains user/assistant text, tool names, and lexical\nfeedback found in user text, while excluding thinking, tool arguments, tool\noutputs, images, and unrelated metadata. The absolute project `cwd` from the\nsession header is retained for scope filtering and may appear in miner prompts\nsent to a real backend and its provider. Known secret-shaped strings in retained\nmessage text are redacted as defense in depth, not as a guarantee. `--source auto` keeps Codex-then-Claude\nprecedence and does not select Pi.\n\nThe source and backend are independent. `--backend pi` uses a locally installed,\nauthenticated Pi CLI to make real model-provider calls for mining, replay,\njudging, and reflection. Select another executable with `--pi-path` and a model\nwith `--model`:\n\n```bash\npython -m skillopt_sleep run --project \"$(pwd)\" \\\n  --source pi --backend pi --pi-path /absolute/path/to/pi \\\n  --model provider/model --max-sessions 5 --max-tasks 3 --progress\n```\n\nPi calls disable tools, skills, context files, extensions, prompt templates,\nthemes, and session writes. They still use the user's Pi authentication and\nmodel configuration. Pi's offline startup mode also prevents configured npm/git\npackage installation, package updates, and model-catalog refresh; it does not\nprevent the selected provider call. This is bounded invocation setup rather\nthan permanent or complete isolation. Transcript-derived prompts reach the\nprovider configured in Pi; review that provider's data-retention and privacy\npolicy before using sensitive sessions.\n\nThe managed scheduler stores the selected backend but does not persist\n`--source`, `--pi-home`, `--pi-path`, or `--model`. Before scheduling Pi, set\n`transcript_source`, `pi_home`, `pi_path`, and `model` in\n`~/.skillopt-sleep/config.json`; prefer an absolute `pi_path` and verify that the\nscheduled account is authenticated.\n\n### Cursor source and backend\n\nCursor transcript harvesting is explicit: use `--source cursor` rather than\n`--source auto`. Invoked-project scope uses Cursor's recorded workspace path,\nwith the sanitized storage directory as a fallback; `--scope all` scans every\nCursor workspace under `~/.cursor/projects`. The model-driven backend requires\nan installed, authenticated `cursor-agent`; use `--cursor-path`,\n`SKILLOPT_SLEEP_CURSOR_PATH`, or the `cursor_path` config key when it is not on\n`PATH`, and use `--model` or `SKILLOPT_SLEEP_CURSOR_MODEL` to choose a model.\n\nTarget the project skill explicitly so accepted learning becomes visible to\nCursor without changing the plugin's own workflow skill:\n\n```bash\npython -m skillopt_sleep run --project \"$(pwd)\" \\\n  --source cursor --backend cursor \\\n  --target-skill-path .cursor/skills/skillopt-sleep-learned/SKILL.md \\\n  --max-sessions 5 --max-tasks 3 --progress\n```\n\n### Advanced config\n\nThe JSON/YAML config under `~/.skillopt-sleep/` supports additional engine keys,\nincluding `gate_mode`, `gate_metric`, `gate_no_regression`, `dream_rollouts`,\n`dream_factor`, `recall_k`, `evolve_memory`, and `evolve_skill`. These are config\nkeys, not aliases for the unsupported CLI flags listed above. Shipping defaults\nare conservative: `gate_mode=\"on\"`, `gate_no_regression=false`,\n`dream_rollouts=1`, `dream_factor=0`, and `recall_k=0`.\n\nThe managed `schedule` command stores only the project, backend, time, and\noptional auto-adopt setting. It does not copy `--source`, `--cursor-home`,\n`--cursor-path`, `--model`, or `--target-skill-path` into the scheduled command.\nFor a Cursor schedule, set `transcript_source`, `cursor_home`, `cursor_path`,\n`model`, and `target_skill_path` in `~/.skillopt-sleep/config.json` first. Keep\nthe target project-relative, use an absolute CLI path because cron and Task\nScheduler may have a minimal `PATH`, and confirm that `cursor-agent` is\nauthenticated for the account that runs the job.\n\n### Handoff backend\n\n`--backend handoff` keeps model subprocesses out of the engine. It writes pending\nmodel calls to `.skillopt-sleep-handoff/PROMPTS.md` and `pending.json`, exits with\ncode 3, and resumes after answers are placed in `answers/<id>.md`:\n\n```bash\npython -m skillopt_sleep run --backend handoff --project \"$(pwd)\"\n# answer each prompt in a fresh context, then run the same command again\n```\n\nAnswering held-out prompts from a context that has already seen their references\ncontaminates the validation gate. Claude Code's `/skillopt-sleep-handoff` command\nautomates the loop with isolated fresh-context subagents.\n\n## Validation\n\nThe deterministic no-provider check exercises consolidation and the gate:\n\n```bash\npython -m skillopt_sleep.experiments.run_experiment \\\n  --persona researcher --assert-improves\n```\n\nReal-model benchmark results and their limitations are documented in\n[`docs/sleep/RESULTS.md`](../docs/sleep/RESULTS.md). The benchmark recipes are not\nthe shipping CLI defaults.\n\n## Safety summary\n\n- Session harvesting is read-only.\n- `mock` and `handoff` make no network calls.\n- `run` stages proposals; `adopt` is the normal live-change boundary.\n- Adoption backs up existing target files.\n- `--max-sessions` and `--max-tasks` bound work. `max_tokens_per_night` in the\n  config file (default `400000`) stops a night from starting new steps once its\n  token count reaches the budget, but a started step finishes, so it is not a\n  hard cap. There is no elapsed-time budget.\n- Treat real-backend transcript excerpts as data shared with the selected\n  provider.\n","plugins/claude-code/.claude-plugin/marketplace.json":"{\n  \"$schema\": \"https://anthropic.com/claude-code/marketplace.schema.json\",\n  \"name\": \"skillopt-sleep\",\n  \"description\": \"SkillOpt-Sleep: give your local Claude agent a nightly sleep cycle that reviews past sessions and consolidates validated memory + skills.\",\n  \"owner\": {\n    \"name\": \"Yifan Yang\",\n    \"email\": \"yifanyang@microsoft.com\"\n  },\n  \"plugins\": [\n    {\n      \"name\": \"skillopt-sleep\",\n      \"description\": \"Nightly offline self-evolution: harvest your past Claude Code sessions, replay recurring tasks on your own API budget, and consolidate what the agent learns into validated CLAUDE.md memory and SKILL.md skills, behind a held-out gate, staged for your review. Synthesizes SkillOpt (validation-gated skill optimization), Claude Dreams (offline memory consolidation), and agent sleep/consolidation.\",\n      \"author\": {\n        \"name\": \"Yifan Yang\"\n      },\n      \"category\": \"productivity\",\n      \"source\": {\n        \"source\": \"git-subdir\",\n        \"url\": \"https://github.com/microsoft/SkillOpt.git\",\n        \"path\": \"plugins/claude-code\",\n        \"ref\": \"main\"\n      },\n      \"homepage\": \"https://github.com/microsoft/SkillOpt\"\n    }\n  ]\n}\n","plugins/claude-code/.claude-plugin/plugin.json":"{\n  \"name\": \"skillopt-sleep\",\n  \"description\": \"Give your local Claude agent a nightly 'sleep cycle': it reviews your past sessions offline, replays recurring tasks on your own API budget, and consolidates what it learns into validated memory (CLAUDE.md) and skills (SKILL.md) so it gets better the more you use it. Synthesizes SkillOpt (validation-gated skill optimization), Claude Dreams (offline memory consolidation), and agent sleep/consolidation.\",\n  \"version\": \"0.1.0\",\n  \"author\": {\n    \"name\": \"Yifan Yang\",\n    \"email\": \"yifanyang@microsoft.com\"\n  },\n  \"homepage\": \"https://github.com/microsoft/SkillOpt\",\n  \"repository\": \"https://github.com/microsoft/SkillOpt\",\n  \"license\": \"MIT\",\n  \"keywords\": [\n    \"skillopt\",\n    \"self-improvement\",\n    \"memory-consolidation\",\n    \"dreams\",\n    \"sleep\",\n    \"skills\",\n    \"continual-learning\",\n    \"offline-optimization\"\n  ]\n}\n","plugins/claude-code/README.md":"# SkillOpt-Sleep (Claude Code plugin)\n\n> Give your local Claude agent a **sleep cycle**. Every night it reviews your\n> past sessions offline, replays your recurring tasks on your own API budget,\n> and consolidates what it learns into **validated** memory (`CLAUDE.md`) and\n> skills (`SKILL.md`). Your agent gets better the more you use it — no\n> model-weight training.\n\nSkillOpt-Sleep is the **deployment-time** companion to\n[SkillOpt](https://github.com/microsoft/SkillOpt). SkillOpt trains a skill\noffline on a benchmark; SkillOpt-Sleep applies the same discipline to *your own\ndaily usage*: bounded text edits, accepted only through a held-out validation\ngate, with rejected candidates recorded in the cycle report for review.\n\nIt synthesizes three ideas:\n\n| Idea | Contribution |\n|---|---|\n| **SkillOpt** | skill/memory = trainable text; bounded add/delete/replace edits; **held-out gate** keeps only changes that help. |\n| **Claude Dreams** | offline consolidation over past sessions; input never mutated; output **reviewed then adopted**. |\n| **Agent sleep** | periodic offline replay turns short-term episodes into long-term skill. |\n\n## What it does (one \"night\")\n\n```\nharvest ~/.claude transcripts → mine recurring tasks → replay offline\n   → consolidate (reflect → bounded edit → GATE) → stage proposal → (you) adopt\n```\n\nNothing live is modified until **you** run `/skillopt-sleep adopt` (the Dreams \"review,\nthen adopt or discard\" contract). Every adopt backs up the prior file first.\n\n## Install\n\n**Requirements:** Python ≥ 3.10. A real CLI backend additionally requires its\ncorresponding `claude` or `codex` executable on `PATH` and authenticated.\n\n```bash\n# 1) get the code (the plugin ships inside the SkillOpt repo)\ngit clone https://github.com/microsoft/SkillOpt.git\ncd SkillOpt\n\n# 2) add the plugin to Claude Code as a local marketplace\n/plugin marketplace add ./plugins/claude-code\n/plugin install skillopt-sleep@skillopt-sleep\n\n# 3) verify\n/skillopt-sleep status\n```\n\nThe plugin's bundled runner (`scripts/sleep.sh`) auto-selects a Python ≥ 3.10\ninterpreter and calls the `skillopt_sleep` engine. A source checkout needs no\n`pip install`. If the marketplace cache does not contain a usable source tree,\nthe shared runner falls back first to a `skillopt-sleep` executable on `PATH`\n(including `uv tool`/`pipx` installs), then to an importable Python module. Use\n`uv tool install skillopt` or `pip install skillopt` for that fallback.\n\n> **Version note.** This page tracks `main`. PyPI 0.2.0 provides the base Sleep\n> CLI, but handoff mode, `--preferences`, multi-skill fan-out, and reviewed\n> subset adoption require a source checkout from `main` until the next release.\n\n## Quick start\n\n```bash\n# from inside any project you use with Claude Code:\n/skillopt-sleep dry-run     # preview what it would learn; no changes staged\n/skillopt-sleep run         # full cycle: stages a reviewed proposal (still no live edits)\n/skillopt-sleep status      # see history + the latest staged proposal\n/skillopt-sleep adopt --legacy       # apply the reviewed managed proposal\n# Fan-out nights instead use: adopt --skill NAME (repeatable) or --all-skills\n\n/skillopt-sleep-handoff run # same cycle, but THIS session answers the model calls\n                            # (no claude -p subprocess, no API key — subscription-friendly)\n```\n\nOr call the engine directly (Python ≥ 3.10):\n\n```bash\npython -m skillopt_sleep run --project \"$(pwd)\" --scope invoked --backend mock\npython -m skillopt_sleep run --project \"$(pwd)\" --backend claude   # real lift via Claude\npython -m skillopt_sleep run --project \"$(pwd)\" --backend codex    # real lift via Codex\n```\n\nDefault backend is **`mock`** — deterministic, no API spend — so you can try the\nplumbing for free. Switch to `--backend claude` or `--backend codex` for\nmodel-driven mining and optimization on your own budget; an accepted gain is\ntask- and model-dependent, not guaranteed.\n\n### Data boundary for real backends\n\nHarvesting `~/.claude` is local and read-only, and the `mock` backend makes no\nprovider calls. A real backend sends truncated transcript excerpts and derived\ntasks to the selected provider for mining, replay, judging, and reflection.\nOutbound prompts are not currently guaranteed to be secret-free. Review your\nsession data and provider policy before using a real backend on a sensitive\nproject; the [shared integration guide](../README.md#data-boundary) describes a\nreviewed task-file workflow.\n\n### Sessions you did not type\n\nHarvest keeps your prompts and drops machine-written transcripts. Three\nenvironment variables extend what counts as machine-written, for the sessions\nClaude Code gives no other tell:\n\n| Variable | Effect |\n|---|---|\n| `SKILLOPT_SLEEP_AGENT_MARKERS` | Comma-separated markers; a session whose **first** prompt contains one is dropped entire. |\n| `SKILLOPT_SLEEP_NEG_FEEDBACK` / `SKILLOPT_SLEEP_POS_FEEDBACK` | Extra comma-separated phrases, in any language, that count as you rejecting or approving the previous answer. |\n\nThe case they exist for is a local hook that summarises the previous session on\na timer. Its runs are single-turn, they are frequent enough to fill\n`--max-sessions` and starve the night of your real sessions, and in the desktop\napp they carry `entrypoint: \"claude-desktop\"` like interactive ones — so neither\n`entrypoint` nor a replay marker identifies them. Quote the hook's first line:\n\n```bash\nexport SKILLOPT_SLEEP_AGENT_MARKERS=\"Below is a conversation log from a coding session\"\n```\n\nA template you cannot quote is covered only after you opt in: a single-turn\nsession sharing its first 120 characters of prompt with three others in the same\nharvest window is dropped before the session cap is applied once\n`SKILLOPT_SLEEP_REPEAT_MIN_SESSIONS` is set (default `0`, off; `3` is the usual\nchoice). Recurrence is not proof of who wrote a prompt — three human requests\nagainst one long shared checklist look the same — so the default keeps every\nsession and `--max-sessions` still bounds how many transcripts are read. A\nsession with a follow-up user turn is never matched, and neither is a prompt\nshorter than the prefix — your own one-shot requests repeat entirely rather than\nsharing a long boilerplate header.\n\n`/skillopt-sleep harvest` and the progress line of a `run` / `dry-run` report\nwhat was dropped, so a thin night is explainable:\n`harvest done: sessions=120 (skipped: 297 repeated-template sessions, 2 past the session cap)`.\nFull reference: [the sleep guide](../../docs/sleep/README.md#harvest-filters-environment).\n\n### Handoff mode (session answers the model calls)\n\n`--backend handoff` runs the cycle without any model subprocess: the engine\nexecutes the deterministic stages and writes every model call it needs to\n`.skillopt-sleep-handoff/PROMPTS.md` + `pending.json` (exit code 3). You (or\nthe `/skillopt-sleep-handoff` command, which automates the loop with isolated\nfresh-context subagents) write each raw answer to `answers/<id>.md` and re-run\nthe same command; it resumes from the answers and either finishes or stages\nthe next batch. Typically 3–6 rounds per night.\n\n```bash\npython -m skillopt_sleep run --backend handoff --project \"$(pwd)\"\n# ... answer .skillopt-sleep-handoff/PROMPTS.md into answers/<id>.md ...\npython -m skillopt_sleep run --backend handoff --project \"$(pwd)\"   # resume\n```\n\nAnswer every prompt in a **fresh context** — a session that has already seen\nthe mined tasks and their references would contaminate the held-out gate.\nDetails: [the plugins README](../README.md#handoff-backend).\n\n## Does it actually improve? (real models, public benchmark)\n\nSkillOpt-Sleep is validated against [gbrain-evals](https://github.com/garrytan/gbrain-evals)'\npublic `skillopt-v1` suite — the same benchmark gbrain scores its own skill\noptimizer against. We take a deliberately **deficient** skill and run one sleep\nnight; held-out scoring is done by a local rule judge (no judge-API, no way to\ngrade its own homework).\n\n| Backend | Seed | Held-out before → after | Nights |\n|---|---|---|---|\n| **Claude (Haiku 4.5)** | brief-writer | **0.00 → 1.00** | 1 |\n| **Codex** | brief-writer | **0.00 → 1.00** | 2 |\n\nBoth took a brief-writer with no risks section / no confidence level and, within\n1–2 nights, proposed gated edits that lifted the held-out score to perfect —\ninto the protected `LEARNED` block, nothing else touched. The Codex 2-night\ntrace even shows the optimizer **diagnosing its own residual failure** and\nadding a meta-rule to fix it. See the recorded results and limitations in\n[`docs/sleep/RESULTS.md`](../../docs/sleep/RESULTS.md).\n\nReproduce:\n\n```bash\ngit clone https://github.com/garrytan/gbrain-evals /tmp/gbrain-evals\npython -m skillopt_sleep.experiments.run_gbrain --backend claude --model haiku \\\n  --seeds brief-writer --data-root /tmp/gbrain-evals/eval/data/skillopt-v1 \\\n  --nights 1 --limit-replay 3 --limit-holdout 3\npython -m skillopt_sleep.experiments.run_gbrain --backend codex \\\n  --seeds brief-writer --data-root /tmp/gbrain-evals/eval/data/skillopt-v1 \\\n  --nights 1 --limit-replay 3 --limit-holdout 3\n```\n\n## Deterministic proof (no API, no keys)\n\n```bash\npython -m skillopt_sleep.experiments.run_experiment --persona researcher --assert-improves\npython -m skillopt_sleep.experiments.run_experiment --persona programmer  --assert-improves\n```\n\nEach prints the held-out score rising from baseline toward 1.0 as the gate\naccepts the general rules your tasks need, and confirms the gate **rejects** an\ninjected harmful edit. Context for the measured experiments is in\n[`docs/sleep/RESULTS.md`](../../docs/sleep/RESULTS.md).\n\n## Schedule it nightly\n\n```bash\n/skillopt-sleep schedule --hour 3 --minute 17\n/skillopt-sleep unschedule\n```\n\nThe built-in scheduler creates a managed cron entry and logs under the project.\nThe scheduled run stages proposals unless `--auto-adopt` is explicitly selected.\n\n## Safety\n\n- **Read-only** harvest of `~/.claude`. `mock` replay has no side effects.\n- Proposals are **staged**, never auto-applied (unless you opt in with `--auto-adopt`).\n- Every adopt writes a backup under the staging dir's `backup/`.\n- `--max-sessions` and `--max-tasks` bound work. `max_tokens_per_night` in\n  `~/.skillopt-sleep/config.json` stops a night from starting new steps once its\n  token count reaches the budget; a started step finishes, so it is not a hard\n  cap, and there is no wall-clock budget.\n- Real backends share truncated session/task content with the selected provider;\n  do not assume outbound prompts have been fully redacted.\n\n## Status\n\nThe engine, deterministic experiment, Claude/Codex CLI backends, handoff mode,\nand staged adoption flow are implemented. Advanced experiment-harness flags are\nnot automatically available on the nightly CLI; see the\n[shared integration reference](../README.md#supported-cli-surface).\n","plugins/claude-code/skills/skillopt-sleep/SKILL.md":"---\nname: skillopt-sleep\ndescription: \"Use when the user wants their Claude agent to self-improve from past usage, asks about a nightly/offline 'sleep' or 'dream' cycle, memory/skill consolidation, or says things like 'make my agent better the more I use it', 'review my past sessions', 'learn my preferences', 'consolidate what you learned', 'run the sleep cycle', or wants to schedule background self-optimization. Drives the skillopt_sleep engine: harvest past sessions -> mine recurring tasks -> replay through a selected backend -> consolidate validated CLAUDE.md/SKILL.md behind a held-out gate.\"\n---\n\n# SkillOpt-Sleep: usage-driven self-evolution for a local Claude agent\n\nSkillOpt-Sleep gives the user's agent a **sleep cycle**. On demand or on a\nnightly schedule, it reviews real past Claude Code sessions, re-runs recurring\ntasks through the selected backend, and consolidates what it\nlearns into **memory** (`CLAUDE.md`) and **skills** (`SKILL.md`). With the\ndefault validation gate enabled, it keeps only changes that improve a held-out\nscore. Live files change only through explicit adoption or a user-requested\n`--auto-adopt`. It aims to improve this user's recurring work, while making\neach accepted proposal measurable on the run's held-out tasks,\nwith no model-weight training. It is the deployment-time analogue of training:\nshort-term experience → long-term competence.\n\nIt synthesizes three ideas:\n- **SkillOpt** — the skill/memory doc is trainable text; bounded add/delete/replace\n  edits; accepted only through a held-out gate; rejected edits are recorded in\n  the run report for review.\n- **Claude Dreams** — consolidation that reads past sessions and proposes changes\n  inside protected learned blocks; the input is never mutated, and output is\n  reviewed before adoption.\n- **Agent sleep** — periodic background replay turns episodes into durable skill.\n\n## When to use this skill\n\nTrigger when the user wants any of:\n- \"make my agent learn from how I use it\" / \"get better the more I use it\" / \"remember my preferences across sessions\"\n- a nightly/scheduled or on-demand **offline self-improvement / dream / sleep** run\n- to **review past sessions/trajectories** and distill recurring tasks\n- to **consolidate** feedback into `CLAUDE.md` or a managed skill\n- to **schedule** the cycle (cron) or **adopt** a staged proposal\n\n## The cycle (six stages)\n\n1. **Harvest** — read `~/.claude/projects/*/<session>.jsonl` + `~/.claude/history.jsonl` (READ-ONLY) → session digests.\n2. **Mine** — digests → `TaskRecord`s (recurring intents + outcome labels + checkable refs where possible).\n3. **Replay** — re-run tasks through the selected backend under the *current*\n   skill+memory → (hard, soft) scores.\n4. **Consolidate** — reflect on failures → propose bounded edits → **gate** on a held-out slice; with the default gate enabled, accept only if it strictly improves.\n5. **Stage** — write the accepted `proposed_CLAUDE.md` and/or\n   `proposed_SKILL.md`, plus `report.md`, `report.json`, `manifest.json`, and\n   `diagnostics.json` into `<project>/.skillopt-sleep/staging/<timestamp>/`.\n   **Nothing live changes.** A rejected run still has a report but no proposed\n   live-file replacement.\n6. **Adopt** — explicit (or opt-in auto): copy staged files over live ones, backing up first.\n\n## How to drive it\n\nPrefer the `/skillopt-sleep` command. Under the hood it calls the bundled runner:\n\n```bash\n\"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh\" status                       # what's happened\n\"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh\" dry-run --project \"$(pwd)\"    # no-staging preview\n\"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh\" run --project \"$(pwd)\"        # full cycle, stages a proposal\n\"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh\" adopt --project \"$(pwd)\"      # apply staged proposal (with backup)\n```\n\n- Default backend is `mock` (deterministic, **no API spend**) — good for trying the plumbing.\n- Add `--backend claude` or `--backend codex` to spend the user's real budget\n  for model-driven optimization. A held-out gain is run-specific evidence, not\n  a guarantee of broader improvement; results depend on the tasks, model, and\n  checks.\n- Scope defaults to the invoked project; `--scope all` harvests every Claude\n  project into the current run's configured targets.\n- A real backend sends truncated transcript/task content to its provider. See\n  the data-boundary rules below before using one with sensitive sessions.\n\n### Scheduling\n\n```bash\n\"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh\" schedule --project \"$(pwd)\" --hour 3 --minute 17\n\"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh\" unschedule --project \"$(pwd)\"\n```\n\nInstalls a nightly cron entry. `unschedule --all` removes every managed entry.\n\n## Common CLI flags\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `--project PATH` | cwd | Project directory to evolve |\n| `--scope all\\|invoked` | invoked | Harvest scope |\n| `--backend mock\\|claude\\|codex\\|copilot\\|handoff\\|azure_openai` | mock | Backend (mock = no provider calls) |\n| `--model NAME` | backend default | Override the model used for replay |\n| `--source claude\\|codex\\|auto` | claude | Transcript source |\n| `--lookback-hours N` | 72 | Harvest window |\n| `--max-sessions N` | derived | Cap harvested sessions; defaults to 3 × max tasks (120 with current defaults) |\n| `--max-tasks N` | 40 | Cap mined tasks |\n| `--target-skill-path PATH` | `~/.claude/skills/skillopt-sleep-learned/SKILL.md` | Explicit SKILL.md to evolve |\n| `--tasks-file PATH` | — | Reviewed TaskRecord JSON (skip harvest) |\n| `--progress` | off | Print phase progress to stderr |\n| `--auto-adopt` | off | Auto-adopt if gate passes |\n| `--edit-budget N` | 4 | Max bounded edits per night |\n| `--preferences TEXT` | empty | Add house rules to the optimizer's reflection prior |\n| `--json` | off | Machine-readable JSON output |\n\nThe CLI also has source/runtime path overrides (`--claude-home`, `--codex-home`,\nand `--codex-path`) and action-specific flags. Use\n`python -m skillopt_sleep <action> --help` as the authoritative surface.\n\n## Config keys (`~/.skillopt-sleep/config.json`)\n\nBeyond the CLI flags, advanced behavior is controlled via config:\n\n- **`preferences`** — free-text house rules injected into the optimizer's reflect step (e.g. \"Always use async/await\", \"Answers in `\\boxed{}`\").\n- **`gate_mode`** — `on` (default, validation-gated) or `off` (greedy, accept all edits).\n- **`gate_metric`** — `hard`, `soft`, or `mixed` (default). Controls how the held-out gate scores.\n- **`gate_no_regression`** — `false` by default. Set to `true` to reject a candidate when any validation task's configured gate score decreases.\n- **`dream_rollouts`** — >1 enables multi-rollout contrastive reflection per task.\n- **`recall_k`** — >0 recalls K similar past tasks into the dream (long-term memory).\n- **`evolve_memory`** / **`evolve_skill`** — independently toggle CLAUDE.md vs SKILL.md consolidation.\n\n## Memory consolidation\n\nThe sleep cycle can consolidate both:\n- **SKILL.md** — the managed skill file (bounded edits: add/delete/replace)\n- **CLAUDE.md** — the project memory (same bounded edits)\n\nWith the default gate enabled, both are evaluated by the same held-out score.\nSet `evolve_memory: false` to consolidate only skills, or `evolve_skill: false`\nfor only memory.\n\n## Hard rules\n\n- **Never** hand-edit the user's `CLAUDE.md` / `SKILL.md` as part of this skill.\n  Let the engine's explicit `adopt` or user-requested `--auto-adopt` path apply\n  the staging manifest and back up existing live files first.\n- Harvest is read-only. `mock` replay has no side effects.\n- Real backends send truncated transcript excerpts and derived tasks to the\n  selected provider for mining, replay, judging, and reflection. The Claude\n  transcript path is not guaranteed to remove every secret before those calls.\n  Review provider policy and session contents first. For sensitive data, use\n  `mock` or run `harvest --output <file>`, inspect/redact the JSON, set\n  `\"reviewed\": true`, and replay it with `--tasks-file`; real backends refuse an\n  unreviewed task file.\n- Always show the user the **held-out baseline → candidate** score and the\n  exact proposed edits before suggesting adoption. Evidence before adoption.\n- If asked to demonstrate the mechanism without provider calls, run\n  `python -m skillopt_sleep.experiments.run_experiment --persona researcher --json`\n  — a deterministic synthetic demo of held-out lift and gate rejection. It\n  validates the mechanism, not effectiveness on the user's own tasks.\n\n## Validate / demo\n\n```bash\n# deterministic synthetic demo (no API): score rises and the gate blocks a regression\npython -m skillopt_sleep.experiments.run_experiment --persona researcher --assert-improves\npython -m skillopt_sleep.experiments.run_experiment --persona programmer  --assert-improves\n```\n\nSee the [SkillOpt-Sleep documentation](https://github.com/microsoft/SkillOpt/tree/main/docs/sleep)\nfor recorded results, limitations, and the supported integration surface.\n","plugins/codex/README.md":"# SkillOpt-Sleep — Codex integration\n\nGive your **Codex** agent a nightly **sleep cycle**: it reviews past sessions\noffline, replays your recurring tasks on your own Codex budget, and consolidates\nwhat it learns into validated memory + skills behind a held-out gate. Same engine\nas the Claude Code plugin (`skillopt_sleep`), wrapped for Codex.\n\n> **Verified on Codex:** on the public\n> [gbrain-evals](https://github.com/garrytan/gbrain-evals) `skillopt-v1`\n> benchmark, a deliberately deficient skill goes **0.00 → 1.00** on a held-out\n> set with the Codex backend (incl. the tool-use seed via a real tool loop).\n> See the recorded results and limitations in\n> [`docs/sleep/RESULTS.md`](../../docs/sleep/RESULTS.md).\n\n## What Codex supports (and what we use)\n\nCodex (`@openai/codex`) extends via **`AGENTS.md`** instructions, **skills** at\n`~/.agents/skills/<name>/SKILL.md`, and plugins that can distribute skills.\nCustom prompts are deprecated in Codex, so this integration is skill-first: the\ninstalled `skillopt-sleep` skill contains the launch commands and operating\nrules. The shared runner remains a plain shell entrypoint that the skill calls.\n\n## Install\n\nOn Linux/macOS:\n```bash\ngit clone https://github.com/microsoft/SkillOpt.git\ncd SkillOpt\nbash plugins/codex/install.sh          # installs the skill\nexport SKILLOPT_SLEEP_REPO=\"$(pwd)\"    # so the runner is found from anywhere\n```\n\nOn Windows (PowerShell):\n```powershell\ngit clone <repo-url> SkillOpt-Sleep\ncd SkillOpt-Sleep\npowershell -File plugins/codex/install.ps1\n[System.Environment]::SetEnvironmentVariable(\"SKILLOPT_SLEEP_REPO\", \"$(pwd)\", \"User\")\n```\n\nIf a previous install created `~/.codex/prompts/sleep.md`, the installer moves\nthat deprecated prompt aside with a `.skillopt-legacy*.bak` suffix.\n\nRequires Python ≥ 3.10 and the `codex` CLI on PATH.\n\n## Use\n\nMention `$skillopt-sleep` where Codex supports explicit skill mentions, or ask\nCodex in natural language:\n\n```text\nUse the skillopt-sleep skill to run status for this project.\nUse the skillopt-sleep skill to run a dry-run for this project.\nUse the skillopt-sleep skill to run the full cycle for this project with the Codex backend.\nUse the skillopt-sleep skill to inspect status, then adopt the reviewed managed\nproposal or an explicit pending skill subset.\n```\n\nOr call the engine directly:\n\n```bash\npython -m skillopt_sleep dry-run --project \"$(pwd)\" --source codex --backend mock\npython -m skillopt_sleep run --project \"$(pwd)\" --source codex --backend codex \\\n  --max-sessions 5 --max-tasks 3 --progress\npython -m skillopt_sleep run --project \"$(pwd)\" --source codex --backend codex \\\n  --target-skill-path .agents/skills/example/SKILL.md \\\n  --max-sessions 5 --max-tasks 3 --progress\n```\n\n`--source codex` reads Codex Desktop archived sessions from\n`~/.codex/archived_sessions`. Use `--codex-home /path/to/.codex` to point at a\ndifferent Codex home, or `--source auto` to try Codex archives first and fall\nback to Claude Code transcripts. Default backend is `mock` (no API spend).\n`--backend codex` uses your Codex budget for model-driven optimization; an\naccepted gain is task-dependent, not guaranteed. Bound live runs\nwith `--max-sessions` and `--max-tasks`; add `--progress` because Codex-backed\nmining, replay, and reflection can be slow and otherwise quiet. Use\n`--target-skill-path` to stage/adopt into a repo-scoped Codex skill such as\n`.agents/skills/<name>/SKILL.md`; target runs over-sample mined tasks and\nprefer tasks that match the target skill's path, headings, and content. The\nimplemented main-CLI flags work the same across the shared integrations, and\n`--preferences \"...\"` is available for house rules. Advanced keys such as\n`gate_mode`, `gate_no_regression`, `dream_rollouts`, and `recall_k` belong in the Sleep config; the\nnightly CLI does not expose `--gate`, `--rollouts-k`, token/time-budget, or\noptimizer/target-split flags. See the\n[shared CLI reference](../README.md#supported-cli-surface).\n\nFor privacy-sensitive projects, split the run into reviewable steps:\n\n```bash\npython -m skillopt_sleep harvest --project \"$(pwd)\" --source codex \\\n  --target-skill-path .agents/skills/example/SKILL.md \\\n  --max-sessions 5 --max-tasks 3 \\\n  --output reviewed-tasks.json\n\npython -m skillopt_sleep dry-run --project \"$(pwd)\" --backend codex \\\n  --tasks-file reviewed-tasks.json --progress --json\n```\n\nInspect/redact the JSON and set `\"reviewed\": true` before using a real backend.\n`--tasks-file` skips archive harvest/mining and replays only the reviewed JSON\ntasks; real backends refuse task files still marked `\"reviewed\": false`.\n\nThis review step matters even though the Codex transcript converter removes\nknown secret-shaped strings: pattern-based redaction is not a guarantee. A real\nbackend sends truncated transcript/task content to the selected provider, while\n`--backend mock` makes no provider calls.\n\n## Notes / status\n\n- Codex's `exec` runs shell, so the real-tool-loop replay (e.g. the\n  `tool_called: search` benchmark seed) works natively.\n- This integration no longer installs a `.codex/prompts` slash command. Skills\n  are the reusable Codex workflow surface; mention `skillopt-sleep` explicitly\n  or ask for a sleep/dream/offline self-improvement run and Codex can load the\n  skill.\n","plugins/codex/skills/skillopt-sleep/SKILL.md":"---\nname: skillopt-sleep\ndescription: \"Use when the user wants Codex to self-improve from past usage, asks about a nightly/offline 'sleep' or 'dream' cycle, wants Codex to review past sessions, learn preferences, consolidate memory/skills, run dry-run/run/adopt/status for SkillOpt-Sleep, or schedule background self-optimization. Drives the skillopt_sleep engine: harvest past sessions -> mine recurring tasks -> replay through a selected backend -> consolidate validated memory + skills behind a held-out gate.\"\n---\n\n# SkillOpt-Sleep: usage-driven self-evolution for a local Codex agent\n\nSkillOpt-Sleep gives the user's Codex agent a sleep cycle. On demand or on a\nnightly schedule, it reviews past local sessions, re-runs recurring tasks\nthrough the selected backend, and proposes changes to a configured skill and to\nthe project's `CLAUDE.md`. With the default validation gate enabled, it keeps\nonly changes that improve a held-out score. Live files change only through\nexplicit adoption or a user-requested `--auto-adopt`. There is no model-weight\ntraining.\n\nThe current shared engine does **not** write `AGENTS.md`. For a Codex-visible\nresult, always select a Codex skill explicitly with `--target-skill-path` (for\nexample `.agents/skills/<name>/SKILL.md`). If project `CLAUDE.md` is not a\ndesired secondary target, set `\"evolve_memory\": false` in\n`~/.skillopt-sleep/config.json` before running.\n\n## When to use\n\nTrigger when the user wants any of:\n\n- Codex to learn from past sessions or get better the more they use it;\n- a nightly/scheduled or on-demand sleep/dream/offline self-improvement run;\n- to review past sessions and distill recurring tasks;\n- to consolidate feedback into memory or managed skills;\n- to run `status`, `harvest`, `dry-run`, `run`, or `adopt` for SkillOpt-Sleep.\n\n## The cycle\n\n1. **Harvest** - read local session transcripts according to the engine\n   configuration and normalize them into session digests.\n2. **Mine** - turn digests into recurring `TaskRecord`s with outcomes and\n   checkable references where possible.\n3. **Replay** - re-run mined tasks through the selected backend under the\n   current skill and memory.\n4. **Consolidate** - reflect on failures and propose bounded edits.\n5. **Gate** - with the default gate enabled, accept edits only when the held-out\n   validation score improves.\n6. **Stage** - write the proposal under\n   `<project>/.skillopt-sleep/staging/<date>/`; nothing live changes.\n7. **Adopt** - explicitly, or through user-requested auto-adopt, copy staged\n   files over live files with backups for existing targets.\n\n## How to drive it\n\nInvoke the bundled runner via shell (Codex `exec` has shell access). The runner\nfinds the engine and a Python >= 3.10 automatically.\n\n```bash\n# point at the repo if it isn't auto-detected from CWD:\nexport SKILLOPT_SLEEP_REPO=/path/to/SkillOpt\nTARGET_SKILL=.agents/skills/example/SKILL.md\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" status --project \"$(pwd)\"\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" harvest --project \"$(pwd)\" \\\n  --source codex --target-skill-path \"$TARGET_SKILL\"\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" dry-run --project \"$(pwd)\" \\\n  --source codex --target-skill-path \"$TARGET_SKILL\" --backend mock\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" run --project \"$(pwd)\" \\\n  --source codex --target-skill-path \"$TARGET_SKILL\" --backend codex \\\n  --max-sessions 5 --max-tasks 3 --progress\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" status --project \"$(pwd)\"\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" adopt --project \"$(pwd)\" --legacy\n```\n\nFor a fan-out night, select reviewed proposals with repeatable\n`--skill NAME` or `--all-skills`; do not treat bare adopt as “adopt everything.”\n\nOn Windows (CMD / PowerShell):\n```cmd\n:: CMD\nset SKILLOPT_SLEEP_REPO=C:\\path\\to\\SkillOpt-Sleep\n\"%SKILLOPT_SLEEP_REPO%\\plugins\\run-sleep.cmd\" status --project \"%CD%\"\n```\n```powershell\n# PowerShell\n$env:SKILLOPT_SLEEP_REPO = \"C:\\path\\to\\SkillOpt-Sleep\"\npowershell -File \"$env:SKILLOPT_SLEEP_REPO\\plugins\\run-sleep.ps1\" status --project \"$(pwd)\"\n```\n\nActions are `status`, `harvest`, `dry-run`, `run`, `adopt`, `schedule`, and `unschedule`.\n\n- Default backend is `mock`, which is deterministic and spends no API budget.\n- `--backend codex` uses the user's Codex budget for model-driven optimization.\n  An accepted held-out gain is run-specific evidence, not a guarantee of\n  broader improvement; results depend on the tasks, model, and checks.\n- `--source codex` reads Codex Desktop archived sessions from `~/.codex/archived_sessions`;\n  use `--codex-home /path/to/.codex` if the archive lives elsewhere.\n- `--target-skill-path` is required for a Codex skill target. Without it, the\n  shared default is a Claude-managed skill under `~/.claude/skills/`, not an\n  `.agents` skill.\n- Keep `dry-run --backend mock` as the first smoke check unless the user\n  explicitly asked for a real optimization run.\n\n### Scheduling\n\n```bash\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" schedule --project \"$(pwd)\" \\\n  --backend codex --hour 3 --minute 17\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" unschedule --project \"$(pwd)\"\n```\n\nThe scheduler persists the project, backend, time, and optional auto-adopt flag;\nit does not persist `--source` or `--target-skill-path` from this command. Before\nscheduling a Codex-targeted run, set `\"transcript_source\": \"codex\"` and an\nabsolute `\"target_skill_path\"` in `~/.skillopt-sleep/config.json`. On systems\nwithout `crontab`, `schedule` prints a line for manual installation.\n`unschedule --all` removes every managed entry.\n\n### All backends\n\n- `--backend mock` — deterministic, no API spend (default)\n- `--backend claude` — uses the Claude CLI\n- `--backend codex` — uses the Codex CLI\n- `--backend copilot` — uses the GitHub Copilot CLI\n- `--backend handoff` — emits prompt/answer files for an interactive session\n- `--backend azure_openai` — uses the configured Azure OpenAI endpoint\n\n### Additional flags\n\n| Flag | Description |\n|------|-------------|\n| `--auto-adopt` | Auto-adopt if the gate passes (default: stage only) |\n| `--edit-budget N` | Max bounded edits per night (default: 4) |\n| `--lookback-hours N` | Harvest window in hours (default: 72) |\n| `--json` | Machine-readable JSON output |\n\n### Config keys (`~/.skillopt-sleep/config.json`)\n\n- **`preferences`** — free-text house rules for the optimizer\n- **`gate_mode`** — `on` (validation-gated, default) or `off` (greedy)\n- **`gate_metric`** — `hard` | `soft` | `mixed` (default)\n- **`gate_no_regression`** — `false` by default; set it to `true` to reject a candidate when any validation task's gate score decreases\n- **`dream_rollouts`** — >1 for multi-rollout contrastive reflection\n- **`recall_k`** — >0 recalls similar past tasks from the archive\n\n### Memory consolidation\n\nThe shared sleep cycle consolidates project **memory** (`CLAUDE.md`) and the\nselected **skill** (`SKILL.md`) by default. It does not update `AGENTS.md`.\nEach target is independently toggleable through `evolve_memory` /\n`evolve_skill`, and both are gated by the same held-out validation score.\n\n## Steps\n\n1. Run the requested action; capture stdout.\n2. For `dry-run` and `run`, report the held-out baseline -> candidate score,\n   gate action, task count, session count, and exact proposed edits.\n3. If a staging directory is printed, read `report.md` before summarizing.\n4. `run` stages by default; if `--auto-adopt` was explicitly supplied, report\n   the paths it updated instead of claiming nothing changed.\n5. Offer adoption only after the user has reviewed a still-staged proposal.\n6. Never hand-edit the configured `CLAUDE.md` or target skill as a substitute\n   for the engine's adopt path; adoption is the safety boundary and backs up\n   existing targets first.\n\n## Hard rules\n\n- Harvest is read-only. Do not edit archived sessions or raw transcripts.\n- Codex transcript harvesting removes known secret-shaped strings, developer\n  instructions, and raw tool payloads, but pattern-based redaction is not a\n  guarantee. A real backend still sends truncated transcript/task content to\n  its provider. Review sensitive sessions and provider policy first; prefer a\n  reviewed `--tasks-file` workflow when the data boundary matters.\n- Keep raw secrets, credentials, private user data, and transcript contents out\n  of messages, logs, generated artifacts, and commits.\n- Show validation evidence before recommending adoption.\n- Treat generated edits as proposals, not as source of truth.\n- Do not rely on deprecated custom prompts or `/sleep` slash commands for this\n  Codex integration. This skill is the entrypoint.\n\n## Validate\n\n```bash\npython -m skillopt_sleep dry-run --project \"$(pwd)\" --source codex \\\n  --target-skill-path .agents/skills/example/SKILL.md --backend mock --json\npython -m skillopt_sleep.experiments.run_gbrain --backend codex \\\n  --seeds brief-writer --data-root /path/to/gbrain-evals/eval/data/skillopt-v1 \\\n  --nights 2 --limit-replay 3 --limit-holdout 3\n```\n\nIn the recorded `brief-writer` gbrain run, the deliberately deficient fixture\nwent 0.00 -> 1.00 on that run's held-out set. Treat this as reproducible\nbenchmark evidence for that configuration, not a guarantee for other skills,\ntasks, or models; see the\n[recorded results](https://github.com/microsoft/SkillOpt/blob/main/docs/sleep/RESULTS.md)\nfor context and limitations.\n","plugins/copilot/README.md":"# SkillOpt-Sleep — GitHub Copilot integration\n\nGive **Copilot** (CLI or VS Code) a nightly **sleep cycle** via a tiny **MCP\nserver** that exposes the `skillopt_sleep` engine as tools. MCP is GitHub's\nsupported way to extend Copilot, so this works across Copilot CLI, VS Code, and\nother MCP clients with the same server.\n\n## What's here\n\n| File | Purpose |\n|---|---|\n| `mcp_server.py` | stdlib-only MCP (stdio) server exposing `sleep_*` tools |\n| `mcp-config.example.json` | drop-in MCP server config |\n| `copilot-instructions.snippet.md` | paste into `.github/copilot-instructions.md` |\n\n## Install\n\nRequires Python ≥ 3.10. No third-party packages — the server is pure stdlib.\n\n1. **Register the MCP server.** Add the server to your Copilot MCP config\n   (Copilot CLI: `~/.copilot/mcp-config.json`; VS Code: your MCP settings).\n   Use `mcp-config.example.json` as a template — set `SKILLOPT_SLEEP_REPO` to\n   this repo's path:\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"skillopt-sleep\": {\n         \"command\": \"python3\",\n        \"args\": [\"/abs/path/SkillOpt/plugins/copilot/mcp_server.py\"],\n        \"env\": { \"SKILLOPT_SLEEP_REPO\": \"/abs/path/SkillOpt\" }\n       }\n     }\n   }\n   ```\n\n2. **(Optional) Tell Copilot about it.** Append\n   `copilot-instructions.snippet.md` to your repo's\n   `.github/copilot-instructions.md` so Copilot reaches for the tools when the\n   user asks to \"run the sleep cycle\".\n\n## Use\n\nAsk Copilot things like *\"run the sleep cycle\"*, *\"what did the last sleep\npropose?\"*, *\"adopt the staged sleep proposal\"*. The server exposes seven MCP\ntools: `sleep_status`, `sleep_dry_run`, `sleep_run`, `sleep_adopt`,\n`sleep_harvest`, `sleep_schedule`, and `sleep_unschedule`.\n\nEach tool takes optional `project`, `backend`\n(`mock`/`claude`/`codex`/`copilot`/`handoff`), and `scope` arguments. For\n`sleep_adopt`, first inspect `sleep_status`, then use the adoption controls that\nmatch the reviewed staging manifest:\n\n- `staging` — exact staging directory to adopt instead of the latest night\n- `skills` — array of skill names to adopt; each is passed as one repeated\n  `--skill` argument without shell interpolation\n- `all_skills` — adopt every staged per-skill proposal\n- `legacy` — adopt only the legacy managed `SKILL.md`/`CLAUDE.md` pair\n\nChoose one selection mode (`skills`, `all_skills`, or `legacy`) and do not\ncombine them. A bare `sleep_adopt` remains compatible with legacy-only staging;\nfan-out staging requires an explicit selection.\n\nTool results preserve the engine's `exit_code` in `structuredContent`.\nOrdinary nonzero exits set `isError: true`; exit 3 is the expected\n`handoff_pending` state and is not an MCP tool error. With `json: true`, text\ncontent is the engine's parseable JSON stdout, while diagnostics remain\nseparate in `structuredContent`.\n\nDefault backend is `mock` (no API spend). The `copilot` backend drives the\nGitHub Copilot CLI (`copilot -p ... --output-format json`) and requires the\n`copilot` CLI to be installed and authenticated.\n\nHarvesting is local and read-only, and the default `mock` backend makes no\nprovider calls. A real backend sends truncated transcript excerpts and derived\ntasks to the selected provider. Outbound prompts are not currently guaranteed\nto be secret-free; review sensitive data and provider policy first. See the\n[shared data-boundary guidance](../README.md#data-boundary).\n\nFor speed, the `copilot` backend runs each call against an isolated\n`COPILOT_HOME` with built-in MCP servers and custom instructions disabled, so\nyour user MCP servers (including this project's own) are not spawned per call\n(~5x faster). Override with `SKILLOPT_SLEEP_COPILOT_HOME=<dir>`, pick a model\nwith `SKILLOPT_SLEEP_COPILOT_MODEL`, or set `SKILLOPT_SLEEP_COPILOT_FULL_ENV=1`\nto use your real Copilot environment instead.\n\n## Verify the server directly (no Copilot needed)\n\n```bash\nprintf '%s\\n' \\\n  '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{}}' \\\n  '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\"}' \\\n  | SKILLOPT_SLEEP_REPO=\"$(pwd)\" python3 plugins/copilot/mcp_server.py\n```\nYou should see the server info and all seven `sleep_*` tools.\n\n## Notes / status\n\n- MCP is the stable, official Copilot extension surface, so this is the most\n  portable shared-engine integration (one server → CLI + IDE).\n- The MCP schema exposes the main CLI's implemented controls, including task and\n  session caps, target-skill selection, scheduling, and staged adoption. It does\n  not add experiment-only gate, rollout, token/time-budget, or optimizer/target\n  split flags. See the [shared CLI reference](../README.md#supported-cli-surface).\n","plugins/copilot/skillopt/README.md":"# SkillOpt — GitHub Copilot integration\r\n\r\nGive **Copilot** (CLI or VS Code) direct access to the **SkillOpt** research\r\nengine via a tiny **MCP server**. MCP is GitHub's supported way to extend\r\nCopilot, so this works across Copilot CLI, VS Code, and other MCP clients with\r\nthe same server.\r\n\r\nSkillOpt is **validation-gated, text-space skill optimization**: it reflects on\r\nrollouts, makes bounded edits to a skill, and keeps a change only if it improves\r\na held-out validation set. This plugin exposes the repo's training and eval\r\nentry points (`scripts/train.py`, `scripts/eval_only.py`) as Copilot tools.\r\n\r\n> This is the companion to the **SkillOpt-Sleep** plugin (`../mcp_server.py`,\r\n> `sleep_*` tools). Sleep evolves a *local coding agent* from your past\r\n> sessions; this server drives the *research* training/eval loops on the\r\n> benchmark configs in [`../../../configs`](../../../configs).\r\n\r\n## What's here\r\n\r\n| File | Purpose |\r\n|---|---|\r\n| `mcp_server.py` | stdlib-only MCP (stdio) server exposing `skillopt_*` tools |\r\n| `mcp-config.example.json` | drop-in MCP server config |\r\n| `copilot-instructions.snippet.md` | paste into `.github/copilot-instructions.md` |\r\n\r\n## Install\r\n\r\nRequires Python ≥ 3.10. The MCP server itself is pure stdlib, but the tools it\r\nlaunches need SkillOpt's runtime deps — install the package first:\r\n\r\n```bash\r\npip install -e .   # or: pip install -r requirements.txt\r\n```\r\n\r\n1. **Register the MCP server.** Add the server to your Copilot MCP config\r\n   (Copilot CLI: `~/.copilot/mcp-config.json`; VS Code: your MCP settings).\r\n   Use `mcp-config.example.json` as a template — set `SKILLOPT_REPO` to this\r\n   repo's path:\r\n\r\n   ```json\r\n   {\r\n     \"mcpServers\": {\r\n       \"skillopt\": {\r\n         \"command\": \"python3\",\r\n         \"args\": [\"/abs/path/SkillOpt/plugins/copilot/skillopt/mcp_server.py\"],\r\n         \"env\": { \"SKILLOPT_REPO\": \"/abs/path/SkillOpt\" }\r\n       }\r\n     }\r\n   }\r\n   ```\r\n\r\n2. **(Optional) Tell Copilot about it.** Append\r\n   `copilot-instructions.snippet.md` to your repo's\r\n   `.github/copilot-instructions.md` so Copilot reaches for the tools when the\r\n   user asks to \"optimize a skill\" or \"train on a benchmark\".\r\n\r\n## Use\r\n\r\nAsk Copilot things like *\"what configs can I run?\"*, *\"optimize the searchqa\r\nskill\"*, or *\"evaluate this skill on the dataset\"*. Copilot calls the MCP tools:\r\n`skillopt_list_configs`, `skillopt_train`, `skillopt_eval`.\r\n\r\n| Tool | Required args | Notes |\r\n|---|---|---|\r\n| `skillopt_list_configs` | — | Lists `configs/**/*.yaml` you can pass as `config`. |\r\n| `skillopt_train` | `config` | Runs a reflective optimization loop. Long-running; spends budget. |\r\n| `skillopt_eval` | `config`, `skill` | Evaluates one skill markdown file; no training. |\r\n\r\nCommon optional args (both train and eval): `env`, `backend`,\n`optimizer_model`, `target_model`, `out_root`, `cfg_options` (space-separated\n`section.key=value` YAML overrides), and `extra_args` (raw passthrough flags\nfor the underlying script). `skillopt_train` also accepts `num_epochs`,\n`batch_size`, `seed`, and `use_gate`. `use_gate` defaults to `true`; setting it\nto `false` still records validation scores but force-accepts every candidate,\nwhich changes the optimization semantics.\n\nThe MCP schema's `backend` argument follows the underlying script's\n`--backend` choices. Role-specific and generic OpenAI-compatible backends can\nbe selected through config or `extra_args` (for example,\n`--optimizer_backend openai_compatible --target_backend openai_compatible`);\nsee the repository's [backend guide](../../../docs/guide/new-backend.md) for\nthe required environment variables.\n\r\nRuns can be very long. The server's subprocess timeout defaults to 6 hours;\r\noverride it with the `SKILLOPT_RUN_TIMEOUT` environment variable (seconds).\r\n\r\n## Verify the server directly (no Copilot needed)\r\n\r\n```bash\r\nprintf '%s\\n' \\\r\n  '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{}}' \\\r\n  '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\"}' \\\r\n  '{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"skillopt_list_configs\",\"arguments\":{}}}' \\\r\n  | SKILLOPT_REPO=\"$(pwd)\" python3 plugins/copilot/skillopt/mcp_server.py\r\n```\r\n\r\nYou should see the server info, the three `skillopt_*` tools, and the list of\r\nbenchmark configs.\r\n\r\n## Notes / status\r\n\r\n- MCP is the stable, official Copilot extension surface, so this is portable\r\n  across Copilot CLI and IDE from one server.\r\n- `skillopt_list_configs` is filesystem-only and safe to call anytime;\r\n  `skillopt_train` / `skillopt_eval` shell out to the repo scripts and require\r\n  the SkillOpt runtime deps (and, for real backends, model credentials — see\r\n  [`../../../.env.example`](../../../.env.example)).\r\n","plugins/cursor/.cursor-plugin/plugin.json":"{\n  \"name\": \"skillopt-sleep\",\n  \"displayName\": \"SkillOpt-Sleep\",\n  \"version\": \"0.1.0\",\n  \"description\": \"Review recent Cursor sessions, replay recurring work, and stage validation-gated improvements to a Cursor skill for explicit adoption.\",\n  \"author\": {\n    \"name\": \"Yifan Yang\",\n    \"email\": \"yifanyang@microsoft.com\"\n  },\n  \"homepage\": \"https://github.com/microsoft/SkillOpt\",\n  \"repository\": \"https://github.com/microsoft/SkillOpt\",\n  \"license\": \"MIT\",\n  \"keywords\": [\n    \"skillopt\",\n    \"cursor\",\n    \"self-improvement\",\n    \"memory-consolidation\",\n    \"sleep\",\n    \"skills\",\n    \"offline-optimization\"\n  ],\n  \"category\": \"developer-tools\",\n  \"tags\": [\n    \"automation\",\n    \"memory\",\n    \"transcripts\"\n  ],\n  \"commands\": \"./commands/\",\n  \"skills\": \"./skills/\"\n}\n","plugins/cursor/README.md":"# SkillOpt-Sleep - Cursor integration\n\nGive Cursor an on-demand or explicitly scheduled sleep cycle: review recent\nlocal Cursor sessions, replay recurring tasks through a selected backend, and\nstage validation-gated improvements to a project Cursor skill. Nothing runs at\nsession end, and nothing live changes until the user adopts an accepted staged\nproposal (unless they explicitly request `--auto-adopt`).\n\nThis package is a native Cursor plugin containing a command and an agent skill.\nIt does not install hooks or an MCP server.\n\n## Requirements\n\n- Cursor with plugin and agent-skill support.\n- Python 3.10 or newer.\n- Either a SkillOpt source checkout or an installed `skillopt-sleep` command.\n- For `--backend cursor`, an installed and authenticated Cursor Agent CLI\n  (`cursor-agent`). The default `mock` backend needs no provider login or spend.\n\nThe plugin and transcript harvester work on native Windows. Cursor documents\nthe Agent CLI for Windows through WSL; run provider-backed `--backend cursor`\ninside WSL unless a native `cursor-agent` is available in your environment.\n\n## Install the local plugin\n\nClone the repository, then run the installer for your platform.\n\nmacOS or Linux:\n\n```bash\ngit clone https://github.com/microsoft/SkillOpt.git\ncd SkillOpt\nbash plugins/cursor/install.sh\nexport SKILLOPT_SLEEP_REPO=\"$(pwd)\"\n```\n\nWindows PowerShell:\n\n```powershell\ngit clone https://github.com/microsoft/SkillOpt.git\nSet-Location SkillOpt\npowershell -File plugins/cursor/install.ps1\n[System.Environment]::SetEnvironmentVariable(\"SKILLOPT_SLEEP_REPO\", \"$(pwd)\", \"User\")\n```\n\nThe installer copies the plugin to\n`~/.cursor/plugins/local/skillopt-sleep` (or\n`%USERPROFILE%\\.cursor\\plugins\\local\\skillopt-sleep`). Quit and reopen Cursor\nafter changing user environment variables, then confirm that **SkillOpt-Sleep**\nappears in Settings > Plugins under Installed.\n\nThe plugin and engine have separate installation boundaries. The copied plugin\nteaches Cursor how to operate SkillOpt-Sleep; the engine still runs from the\nsource checkout through `plugins/run-sleep.sh` / `plugins/run-sleep.ps1`, or\nfrom an installed command:\n\n```bash\nuv tool install skillopt\n# or: python -m pip install skillopt\n```\n\nUse a release that includes Cursor source/backend support when choosing the\ninstalled-command route. The source-checkout route uses the implementation in\nthe checkout directly.\n\n## Use from Cursor\n\nRun the native command, for example:\n\n```text\n/skillopt-sleep status\n/skillopt-sleep dry-run --backend mock --max-sessions 5 --max-tasks 3\n/skillopt-sleep run --backend cursor --max-sessions 5 --max-tasks 3 --progress\n/skillopt-sleep adopt --legacy\n```\n\nFor fan-out proposals, inspect `status` and use repeatable `--skill NAME` or\n`--all-skills`. Bare adopt deliberately refuses a night containing fan-out rows.\n\nThe `skillopt-sleep` agent skill remains independently available if a Cursor\nversion does not surface plugin commands.\n\nThe native command's default Cursor-visible target is:\n\n```text\n.cursor/skills/skillopt-sleep-learned/SKILL.md\n```\n\nUse `--target-skill-path` with that value on harvest, dry-run, and run commands.\nWithout an explicit target, the shared engine defaults to a Claude-managed\nskill, which Cursor does not load as a project skill.\n\n### Source-checkout commands\n\nmacOS or Linux:\n\n```bash\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" status --project \"$(pwd)\"\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" dry-run \\\n  --project \"$(pwd)\" --source cursor --backend mock \\\n  --target-skill-path .cursor/skills/skillopt-sleep-learned/SKILL.md\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" run \\\n  --project \"$(pwd)\" --source cursor --backend cursor \\\n  --target-skill-path .cursor/skills/skillopt-sleep-learned/SKILL.md \\\n  --max-sessions 5 --max-tasks 3 --progress\n```\n\nWindows PowerShell:\n\n```powershell\npowershell -File \"$env:SKILLOPT_SLEEP_REPO\\plugins\\run-sleep.ps1\" status --project \"$(pwd)\"\npowershell -File \"$env:SKILLOPT_SLEEP_REPO\\plugins\\run-sleep.ps1\" dry-run `\n  --project \"$(pwd)\" --source cursor --backend mock `\n  --target-skill-path .cursor/skills/skillopt-sleep-learned/SKILL.md\npowershell -File \"$env:SKILLOPT_SLEEP_REPO\\plugins\\run-sleep.ps1\" run `\n  --project \"$(pwd)\" --source cursor --backend cursor `\n  --target-skill-path .cursor/skills/skillopt-sleep-learned/SKILL.md `\n  --max-sessions 5 --max-tasks 3 --progress\n```\n\n### Installed-command equivalents\n\n```bash\nskillopt-sleep status --project \"$(pwd)\"\nskillopt-sleep dry-run --project \"$(pwd)\" --source cursor --backend mock \\\n  --target-skill-path .cursor/skills/skillopt-sleep-learned/SKILL.md\nskillopt-sleep run --project \"$(pwd)\" --source cursor --backend cursor \\\n  --target-skill-path .cursor/skills/skillopt-sleep-learned/SKILL.md \\\n  --max-sessions 5 --max-tasks 3 --progress\nskillopt-sleep status --project \"$(pwd)\"\nskillopt-sleep adopt --project \"$(pwd)\" --legacy\n```\n\n`--source cursor` reads local JSONL transcripts below\n`~/.cursor/projects/<workspace>/agent-transcripts/`. Use\n`--cursor-home /path/to/.cursor` for a different Cursor home. Invoked scope\nselects the current workspace; `--scope all` includes every Cursor workspace.\nThe source converter retains user/assistant text, tool names, and explicit turn\nerrors, but excludes raw tool arguments and outputs.\n\nThe first harvest uses a 72-hour lookback by default. Use\n`--lookback-hours N` to choose a wider initial window, or\n`--lookback-hours 0` to consider all available history while still respecting\n`--max-sessions`. A successful `run`, including one that mines no tasks,\nrecords a new harvest checkpoint. Later runs use that checkpoint instead of\nthe initial lookback. Use `harvest` or `dry-run` to inspect session and task\ncounts before the first stateful run; neither action advances the checkpoint.\n\n`--backend cursor` invokes the authenticated Cursor Agent CLI. Use\n`--cursor-path /path/to/cursor-agent` or `SKILLOPT_SLEEP_CURSOR_PATH` if it is\nnot on PATH, and `--model` or `SKILLOPT_SLEEP_CURSOR_MODEL` to override its\nmodel. Check available identifiers with `cursor-agent --list-models` and verify\nthe billed variant in Cursor's usage reporting when cost matters. The child\nprocess receives only an explicit runtime/authentication/locale/proxy/CA\nenvironment allowlist; unrelated cloud and model-provider credentials are not\nforwarded.\n\n## What Cursor replay evaluates\n\nSkillOpt reads the target skill and inserts its text into mined task prompts. It\ndoes not invoke that file as a native Cursor skill or execute commands described\nby the skill. All ordinary Cursor model calls, including mining, replay,\njudging, and reflection, run in a new empty temporary workspace in read-only Ask\nmode. File reads, file writes, and MCP tools are denied. `--project` selects the\ntranscript scope, target files, state, and staging location; it does not make the\nproject the Cursor Agent execution workspace.\n\nCursor tool-aware replay is temporarily disabled pending live Cursor\npermission-boundary validation. Tasks containing a `tool_called` check fail\nnonzero before Agent mode starts. The failed replay does not add a cache entry,\nstage, adopt, persist state, or advance the harvest checkpoint. Use another\nbackend for those tasks.\n\nThis replay is useful for textual procedures, response conventions, and output\nformats. It is not an end-to-end evaluation of skills that depend on repository\ninspection, real CLIs, browsers, running services, or filesystem changes. There\nis currently no Cursor option that enables a fresh project worktree or real\nproject tools. The `replay: mock` report label refers to the prompt-replay mode,\nnot to the selected model backend.\n\nThe shared engine also supports `mock`, `claude`, `codex`, `copilot`,\n`handoff`, and `azure_openai` backends. Cursor is the native model-driven\nchoice for this integration; `mock` remains the no-provider default.\n\n## Review sensitive data before provider calls\n\nHarvesting is local and read-only, and `--backend mock` makes no provider calls.\nKnown secret-shaped strings are redacted from harvested Cursor content, and raw\ntool payloads are excluded, but pattern-based redaction is not a guarantee.\nA real backend sends truncated transcript excerpts and derived tasks to that\nbackend's provider for mining, replay, judging, and reflection.\n\nBoth `run` and `dry-run` perform those real-backend calls; `dry-run` prevents\nstaging but does not prevent provider spend. `--max-sessions` and `--max-tasks`\nbound harvested work, not provider calls, tokens, elapsed time, or money. One\ntask can require several attempt, judge, and reflection calls. Start with small\nlimits and review the provider's usage reporting before increasing them.\n\nFor sensitive work, split the flow at the review boundary:\n\n```bash\nskillopt-sleep harvest --project \"$(pwd)\" --source cursor \\\n  --target-skill-path .cursor/skills/skillopt-sleep-learned/SKILL.md \\\n  --max-sessions 5 --max-tasks 3 --output reviewed-tasks.json\n\nskillopt-sleep dry-run --project \"$(pwd)\" --backend cursor \\\n  --tasks-file reviewed-tasks.json --progress --json\n```\n\nInspect and redact the JSON, then set its top-level `\"reviewed\"` field to\n`true`. Real backends reject task files that remain unreviewed. Keep raw\ntranscripts, credentials, and task files out of commits.\n\n## Scheduling\n\nRuns remain user-triggered unless the user explicitly schedules them. Before\nscheduling, put the Cursor source and target in\n`~/.skillopt-sleep/config.json`, because the scheduler persists the project,\nbackend, time, and optional auto-adopt flag, but not command-line source or\ntarget overrides:\n\n```json\n{\n  \"transcript_source\": \"cursor\",\n  \"target_skill_path\": \".cursor/skills/skillopt-sleep-learned/SKILL.md\",\n  \"cursor_home\": \"/absolute/path/to/.cursor\",\n  \"backend\": \"cursor\"\n}\n```\n\nThen schedule or remove the managed entry:\n\n```bash\nskillopt-sleep schedule --project \"$(pwd)\" --backend cursor --hour 3 --minute 17\nskillopt-sleep unschedule --project \"$(pwd)\"\n```\n\nOn Unix this uses cron; on Windows it uses Task Scheduler. Scheduled runs stage\nproposals for later review by default. Do not add `--auto-adopt` unless the user\nhas explicitly chosen unattended adoption.\n\n## Adoption and memory\n\n`run` stages accepted proposals under\n`<project>/.skillopt-sleep/staging/<timestamp>/`. Read the staged `report.md`\nand show the held-out baseline-to-candidate score plus exact edits before\nrunning `adopt`. Adoption backs up an existing target before replacing it.\n\nThe shared engine may also propose project `CLAUDE.md` memory updates; existing\nmemory behavior is unchanged. To restrict a Cursor setup to the explicit Cursor\nskill, set `\"evolve_memory\": false` in `~/.skillopt-sleep/config.json`.\n\nThere is deliberately no session-end hook or automatic plugin execution.\n","plugins/cursor/skills/skillopt-sleep/SKILL.md":"---\nname: skillopt-sleep\ndescription: \"Use when the user wants Cursor to learn from recent local sessions, asks for an offline sleep or dream cycle, wants to consolidate recurring work into a Cursor skill, or requests SkillOpt-Sleep status, harvest, dry-run, run, scheduling, review, or adoption. Drives the validation-gated skillopt_sleep engine with Cursor transcripts and the optional Cursor Agent CLI backend.\"\n---\n\n# SkillOpt-Sleep for Cursor\n\nSkillOpt-Sleep reviews recent local Cursor sessions, mines recurring tasks,\nreplays those tasks, and proposes bounded improvements to a project Cursor\nskill. With the default gate enabled, a proposal is accepted only when it\nimproves the held-out score. A normal run stages the proposal for review;\nnothing live changes until explicit adoption. There is no model-weight training.\n\nThis plugin has no session-end hook and no MCP server. Run the cycle only when\nthe user asks, or install a schedule only when the user explicitly requests one.\n\n## Cursor target\n\nAlways use this project-relative target for Cursor-visible learning:\n\n```text\n.cursor/skills/skillopt-sleep-learned/SKILL.md\n```\n\nPass it through `--target-skill-path` on `harvest`, `dry-run`, and `run`.\nWithout an explicit target, the shared engine uses a Claude-managed skill under\n`~/.claude/skills`, which is not the intended Cursor project skill.\n\nThe shared engine can also evolve project `CLAUDE.md`. If that secondary memory\ntarget is unwanted, set `\"evolve_memory\": false` in\n`~/.skillopt-sleep/config.json` before running.\n\n## Choose the runner\n\nUse one of these supported command paths consistently:\n\n1. Source checkout on macOS/Linux:\n   `bash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" <action> ...`\n2. Source checkout on Windows:\n   `powershell -File \"$env:SKILLOPT_SLEEP_REPO\\plugins\\run-sleep.ps1\" <action> ...`\n3. Installed engine on any platform:\n   `skillopt-sleep <action> ...`\n\nIf `SKILLOPT_SLEEP_REPO` is not set and `skillopt-sleep` is unavailable, stop\nand explain that the engine must be installed or a SkillOpt checkout must be\nselected. Do not substitute a hand-written edit for the engine workflow.\n\n## Core workflow\n\n1. **Harvest** local Cursor JSONL transcripts read-only.\n2. **Mine** recurring, checkable task records from session digests.\n3. **Replay** tasks under the current skill and memory through the selected\n   backend.\n4. **Reflect** on failures and propose bounded edits.\n5. **Gate** the candidate on held-out real tasks.\n6. **Stage** accepted proposals under\n   `<project>/.skillopt-sleep/staging/<timestamp>/`.\n7. **Adopt** only after review, backing up existing live targets first.\n\n## Commands\n\nUse the installed-command form below, or replace `skillopt-sleep` with the\nplatform-specific source runner described above.\n\n```bash\nTARGET_SKILL=.cursor/skills/skillopt-sleep-learned/SKILL.md\n\n# Inspect current state and the latest staged proposal.\nskillopt-sleep status --project \"$(pwd)\"\n\n# Inspect mined tasks without provider spend.\nskillopt-sleep harvest --project \"$(pwd)\" --source cursor \\\n  --target-skill-path \"$TARGET_SKILL\" --max-sessions 5 --max-tasks 3\n\n# First smoke check: deterministic and no provider calls.\nskillopt-sleep dry-run --project \"$(pwd)\" --source cursor --backend mock \\\n  --target-skill-path \"$TARGET_SKILL\" --max-sessions 5 --max-tasks 3 --json\n\n# Model-driven optimization through the authenticated Cursor Agent CLI.\nskillopt-sleep run --project \"$(pwd)\" --source cursor --backend cursor \\\n  --target-skill-path \"$TARGET_SKILL\" \\\n  --max-sessions 5 --max-tasks 3 --progress\n\n# Inspect selections, then apply the reviewed managed proposal.\nskillopt-sleep status --project \"$(pwd)\"\nskillopt-sleep adopt --project \"$(pwd)\" --legacy\n```\n\nFor fan-out proposals, use repeatable `--skill NAME` or `--all-skills` after\nreview. Bare adopt deliberately refuses a night containing fan-out rows.\n\nActions are `status`, `harvest`, `dry-run`, `run`, `adopt`, `schedule`, and\n`unschedule`.\n\n- Default backend is `mock`, which is deterministic and makes no provider calls.\n- `--backend cursor` uses the user's authenticated Cursor Agent CLI budget for\n  model-driven mining, replay, judging, and reflection.\n- `--source cursor` reads\n  `~/.cursor/projects/<workspace>/agent-transcripts/*/*.jsonl`.\n- `--cursor-home PATH` overrides the Cursor home used for harvesting.\n- `--scope invoked` selects the current workspace; `--scope all` includes every\n  Cursor workspace.\n- `--cursor-path PATH` or `SKILLOPT_SLEEP_CURSOR_PATH` selects a non-default\n  `cursor-agent` executable.\n- `--model NAME` or `SKILLOPT_SLEEP_CURSOR_MODEL` overrides the Cursor model.\n- Check model identifiers with `cursor-agent --list-models`; when cost matters,\n  verify the billed variant in Cursor's usage reporting.\n- Keep live runs bounded with `--max-sessions`, `--max-tasks`, and `--progress`.\n- A held-out gain is evidence for that run, not a promise of general improvement.\n\nThe first harvest uses a 72-hour lookback. Use `--lookback-hours N` for a wider\ninitial window or `--lookback-hours 0` for all available history. A stateful\n`run`, including a no-task run, records a harvest checkpoint; later runs use the\ncheckpoint rather than the initial lookback. Inspect counts with `harvest` or\n`dry-run` before the first real run because those actions do not advance state.\n\nAvailable backends are:\n\n- `mock` - deterministic, with no provider calls (default);\n- `cursor` - the authenticated Cursor Agent CLI;\n- `claude` - the authenticated Claude CLI;\n- `codex` - the authenticated Codex CLI;\n- `copilot` - the authenticated GitHub Copilot CLI;\n- `handoff` - prompt/answer files for an interactive agent session;\n- `azure_openai` - the configured Azure OpenAI endpoint.\n\nSkillOpt reads the target skill and inserts its text into replay prompts; it does\nnot invoke the file as a native Cursor skill. Ordinary Cursor backend calls run\nin a new empty temporary workspace in read-only Ask mode. File reads, file\nwrites, and MCP tools are denied. `--project` controls harvesting, target files,\nstate, and staging; it is not the Cursor Agent execution workspace.\n\nCursor tool-aware replay is temporarily disabled pending live Cursor\npermission-boundary validation. A task containing a `tool_called` check fails\nnonzero before Agent mode starts. The failed replay does not add a cache entry,\nstage, adopt, persist state, or advance the harvest checkpoint. Use another\nbackend for those tasks. Do not claim that repository- or tool-dependent\nbehavior was validated. The current engine does not implement a fresh-worktree\nreplay for Cursor.\n\nA real-backend `dry-run` still makes provider calls; it only suppresses staging.\nSession and task limits are workload bounds, not hard limits on calls, tokens,\ntime, or money. Start with small limits.\n\n## Reviewable data path\n\nCursor harvesting retains user/assistant text, tool names, and explicit turn\nerrors while excluding raw tool arguments, tool outputs, and non-message\nrecords. Known secret-shaped strings are redacted, but pattern-based redaction\ncannot guarantee that a transcript is safe to send to a provider.\n\nFor sensitive sessions, export tasks before any real-backend replay:\n\n```bash\nTARGET_SKILL=.cursor/skills/skillopt-sleep-learned/SKILL.md\nskillopt-sleep harvest --project \"$(pwd)\" --source cursor \\\n  --target-skill-path \"$TARGET_SKILL\" \\\n  --max-sessions 5 --max-tasks 3 --output reviewed-tasks.json\n```\n\nInspect and redact the file, then set its top-level `\"reviewed\"` field to\n`true`. Only then run:\n\n```bash\nskillopt-sleep dry-run --project \"$(pwd)\" --backend cursor \\\n  --tasks-file reviewed-tasks.json --progress --json\n```\n\nReal backends reject task files that remain unreviewed. Never include raw\ntranscripts, credentials, secrets, or sensitive task content in messages,\ncommits, or generated summaries.\n\n`gate_no_regression` is a config-only safeguard in\n`~/.skillopt-sleep/config.json`. It defaults to `false`; set it to `true` to\nreject a candidate when any validation task's configured gate score decreases.\n\n## Scheduling\n\nScheduling is opt-in. The scheduler persists project, backend, time, and the\noptional auto-adopt flag, but not `--source`, Cursor path/home/model overrides,\nor `--target-skill-path`. Before scheduling a Cursor cycle, set at least these values in\n`~/.skillopt-sleep/config.json`:\n\n```json\n{\n  \"transcript_source\": \"cursor\",\n  \"target_skill_path\": \".cursor/skills/skillopt-sleep-learned/SKILL.md\",\n  \"backend\": \"cursor\"\n}\n```\n\nThen run:\n\n```bash\nskillopt-sleep schedule --project \"$(pwd)\" --backend cursor --hour 3 --minute 17\nskillopt-sleep unschedule --project \"$(pwd)\"\n```\n\nThe scheduler uses cron on Unix and Task Scheduler on Windows. Scheduled runs\nstage proposals by default. Use `--auto-adopt` only when the user has explicitly\nrequested unattended adoption.\n\n## Report results\n\nFor `dry-run` and `run`, report:\n\n- session and task counts;\n- held-out baseline and candidate scores;\n- gate action and accepted/rejected edit counts;\n- exact proposed edits;\n- staging directory, when one was created.\n\nRead staged `report.md` before summarizing a run. Offer adoption only after the\nuser reviews an accepted proposal that is still staged. Never claim broad\nimprovement from one run.\n\n## Hard rules\n\n- Harvest is read-only. Never edit Cursor transcript files.\n- Never hand-edit the target skill or `CLAUDE.md` as a substitute for adoption.\n- Do not run a real backend on sensitive content without confirming its data\n  boundary or using the reviewed-task workflow.\n- Do not add a session-end hook or imply that installing this plugin schedules\n  anything.\n- Show validation evidence before recommending adoption.\n- Treat generated edits as proposals, not as source of truth.\n","plugins/devin/README.md":"# SkillOpt-Sleep — Devin integration\n\nGive **Devin** (Cognition) a nightly **sleep cycle** via a tiny **MCP server**\nthat exposes the `skillopt_sleep` engine as tools. MCP is Devin's supported way\nto add custom tooling, so this works in Devin's CLI and IDE.\n\nDevin doesn't write transcripts in the format the engine consumes, so this\nplugin adds a **Devin-specific harvester** that converts every locally available\nsource into the Claude Code-compatible JSONL the engine reads.\n\n## What's here\n\n| File | Purpose |\n|---|---|\n| `mcp_server.py` | stdlib-only MCP (stdio) server exposing `sleep_*` tools |\n| `harvest_devin.py` | converts Devin ATIF-v1.7 transcripts + agentmemory + `.devin/skills` into JSONL, with `taskKey` + outcome envelopes |\n| `judge.py` | reference judge for the deferred/judge branch of the validation gate |\n| `mcp-config.example.json` | drop-in MCP server config |\n| `install.sh` | copies hooks + rules into a project's `.devin/` and prints the MCP registration command |\n| `devin-rules.snippet.md` | copied to `.devin/rules/skillopt-sleep.md` by `install.sh` |\n| `hooks/hooks.v1.json` | SessionEnd hook config — installed/merged at `.devin/hooks.v1.json` by `install.sh` |\n| `hooks/on-session-end.sh` | best-effort activity marker script (called by the hook) |\n\n## What it harvests\n\n| Source | Where |\n|---|---|\n| Devin transcripts (ATIF-v1.7) | `~/.local/share/devin/cli/transcripts/*.json` |\n| agentmemory | `~/.agentmemory/standalone.json` |\n| Skill files | `.devin/skills/*/SKILL.md` |\n\nWorkspaces are auto-detected from `~/.config/Devin/User/workspaceStorage/*/workspace.json`.\nThe adapter performs no post-adoption copy. The core engine applies a reviewed\nproposal directly to its selected target and owns backup/rollback behavior.\n\n## Install\n\nRequires Python ≥ 3.10. No third-party packages — the server is pure stdlib.\n\n1. **Install hooks + rules into your project.** From the repo root:\n\n   ```bash\n   bash plugins/devin/install.sh /path/to/your/project\n   ```\n\n   This copies the SessionEnd hook and rules snippet into the project's\n   `.devin/` directory and prints the MCP registration command. The hook is\n   on by default — it logs a cheap activity marker for local inspection or\n   external automation when each session ends. The current engine harvests by\n   transcript timestamps and does not consume this marker directly. The hook\n   is non-blocking and spends no API budget. Re-run the script to update; the\n   installer preserves existing hooks and does not duplicate its own entry.\n\n2. **Register the MCP server.** Use `mcp-config.example.json` as a template, or\n   run the command printed by `install.sh`:\n\n   ```bash\n   devin mcp add skillopt-sleep \\\n     --env \"SKILLOPT_DEVIN_CLAUDE_HOME=$HOME/.skillopt-sleep-devin\" \\\n     -- python3 /abs/path/to/SkillOpt/plugins/devin/mcp_server.py\n   ```\n\n3. Ask Devin: *\"run the sleep cycle\"*, *\"what did the last sleep propose?\"*, *\"adopt it\"*.\n\n## Tools\n\n| Tool | What it does |\n|---|---|\n| `sleep_status` | nights run so far + latest staged proposal |\n| `sleep_dry_run` | preview cycle — no staging; a real backend still makes provider calls |\n| `sleep_run` | full cycle; stages a proposal for review |\n| `sleep_adopt` | apply a reviewed legacy or per-skill proposal (with backup) |\n| `sleep_harvest` | debug: list the recurring tasks mined |\n| `sleep_schedule` | install a nightly cron entry (`--hour` / `--minute`) |\n| `sleep_unschedule` | remove the nightly cron entry |\n\nBefore `sleep_adopt`, inspect `sleep_status` and use the controls that match the\nreviewed staging manifest:\n\n- `staging` — exact staging directory to adopt instead of the latest night\n- `skills` — array of skill names to adopt; each is forwarded as one repeated\n  `--skill` argument without shell interpolation\n- `all_skills` — adopt every staged per-skill proposal\n- `legacy` — adopt only the legacy managed `SKILL.md`/`CLAUDE.md` pair\n\nChoose one selection mode (`skills`, `all_skills`, or `legacy`) and do not\ncombine them. A bare call remains compatible with legacy-only staging; fan-out\nstaging requires an explicit selection. To operate on a specific Devin skill,\npass its `SKILL.md` as `target_skill_path`; the adapter never performs a second\ncopy after the core engine returns.\n\nTool results preserve the engine's `exit_code` in `structuredContent`.\nOrdinary nonzero exits set `isError: true`; exit 3 is the expected\n`handoff_pending` state and is not an MCP tool error. With `json: true`, text\ncontent is the engine's parseable JSON stdout, while harvest and engine\ndiagnostics remain separate in `structuredContent`.\n\nDefault backend is `mock` (no API spend); the `claude`, `codex`, and `copilot`\nbackends use the corresponding authenticated CLI and budget. The `handoff`\nbackend runs the cycle with no model subprocess or API key — the engine writes\npending model calls to `.skillopt-sleep-handoff/PROMPTS.md` + `pending.json`\n(exit code 3) and resumes after answers are placed in `answers/<id>.md`; re-run\n`sleep_run` with the same arguments to resume. The seven tools call the same\n`python -m skillopt_sleep` actions as the other shared-engine integrations.\n\n## Data boundary\n\nThe Devin harvester reads local ATIF transcripts, agentmemory, and skill files\nand converts them into the engine's session format. The `mock` backend keeps\nthat workflow local. A real backend sends truncated excerpts and derived tasks\nto the selected provider for mining, replay, judging, and reflection. The\nconversion step is not a guarantee that outbound prompts contain no secrets;\nreview sensitive sources and provider policy before enabling a real backend.\nSee the [shared data-boundary guidance](../README.md#data-boundary) and\n[implemented CLI reference](../README.md#supported-cli-surface).\n","plugins/dsh/README.md":"# SkillOpt-Sleep — DeepSeek Harness (dsh) integration\n\nGive your **DeepSeek Harness** agent a nightly **sleep cycle**: it reviews past\nsessions offline, replays your recurring tasks on your own API budget, and\nconsolidates what it learns into validated skills behind a held-out gate. Same\nengine as the Claude Code / Codex / Cursor integrations\n([skillopt_sleep](https://github.com/microsoft/SkillOpt)), wired into dsh's\nplugin system as native tools plus a bundled skill.\n\nDeepSeek Harness is the \"everything is a plugin\" agent framework\n([deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness)).\nPlugins are TypeScript modules exporting an `apply(ctx)` function that register\ncapabilities (tools, services, events, settings) on the Cordis context.\n\n## Why a sleep cycle?\n\nSkills improve when an agent re-examines its own sessions — not just when you\nhand-tune a prompt. The sleep cycle turns your everyday usage into a nightly,\nvalidation-gated skill-improvement loop: harvest what you actually did, replay\nthe recurring tasks on your own API budget, and keep only the changes that pass\na held-out gate. It's the same engine as the Claude Code / Codex / Cursor\nintegrations, wired into dsh as native tools plus a bundled skill.\n\n## What this integration adds\n\n| Component | Purpose |\n|---|---|\n| `src/index.js` | dsh plugin entry: registers 7 `skillopt_*` tools + Schemastery config |\n| `cordis.patch.yml` | bundle patch layer — drop `dsh-skillopt` into any profile's bundles |\n| `skills/skillopt-sleep/SKILL.md` | agent skill: when to use the tools, operating rules, data-boundary rules |\n| `scripts/sleep.py` | bootstrap/self-check runner (same command shape the tools use) |\n| `package.json` | npm package metadata (bundle manifest) |\n\n## Tools\n\n| Tool | skillopt_sleep action | Behavior |\n|---|---|---|\n| `skillopt_status` | `status` | state, engine availability, latest staged proposal & report |\n| `skillopt_dry_run` | `dry-run` | full preview (harvest+mine+replay), stages nothing |\n| `skillopt_run` | `run` | full cycle, stages a proposal (live files unchanged) |\n| `skillopt_adopt` | `adopt` | apply latest staged proposal (with backup) — the live-change boundary |\n| `skillopt_harvest` | `harvest` | read-only show/export of mined tasks |\n| `skillopt_schedule` / `skillopt_unschedule` | `schedule` / `unschedule` | install/remove the nightly cron entry |\n\n## Prerequisites\n\n- DeepSeek Harness (dsh) installed — dsh 0.1.x and 0.2.x are supported\n  (`@deepseek-ai/dsh-tools` 0.1.1-rc.2, 0.2.0-rc.2)\n- Python 3.10+ with the SkillOpt-Sleep engine:\n\n```bash\npip install skillopt          # or use this source checkout\n```\n\n## Install\n\n### As a bundle in a profile\n\nAdd `dsh-skillopt` to the profile's bundles, or in the profile `cordis.patch.yml`:\n\n```yaml\n- insert:\n    - id: skillopt\n      name: './src/index.js'\n      config:\n        backend: mock          # or codex / claude / cursor / pi / opencode / handoff …\n        project: /path/to/project\n        preferences: 'Always use async/await'\n```\n\n### Local patch overlay (dev)\n\nRun from a DeepSeek Harness **source checkout** (the official dev workflow,\n`pnpm` resolves the workspace `dsh` bin):\n\n```bash\npnpm dsh web --patch ./plugins/dsh/cordis.patch.yml\n```\n\nIf `dsh` is installed **globally** (npm install -g), use it directly:\n\n```bash\ndsh web --patch ./plugins/dsh/cordis.patch.yml\n```\n\nEither way the patch inserts the `skillopt` plugin row into the profile; then\nask the agent: \"Use skillopt_status to check the sleep cycle state.\"\n\n## Config keys\n\n| Key | Default | Purpose |\n|---|---|---|\n| `pythonCmd` | `python` | Python interpreter for the engine |\n| `module` | — (bootstrap) | engine Python module override (`python -m <module>`) |\n| `engineScript` | — (scripts/sleep.py) | engine bootstrap script override |\n| `project` | — | default project directory |\n| `scope` | — | harvest scope: `all` \\| `invoked` |\n| `backend` | — | `mock\\|claude\\|codex\\|copilot\\|cursor\\|pi\\|opencode\\|handoff\\|azure_openai` |\n| `source` | — | `claude\\|codex\\|copilot\\|cursor\\|pi\\|opencode\\|auto` |\n| `model` | — | backend model override |\n| `maxTasks` / `maxSessions` | — | mine/harvest caps |\n| `editBudget` | — | bounded edits per cycle |\n| `preferences` | — | house rules for the reflection prior |\n| `jsonOutput` | `false` | machine-readable JSON output |\n| `autoAdopt` | `false` | OPERATOR-ONLY: auto-adopt a passed proposal without asking |\n| `unscheduleAll` | `false` | OPERATOR-ONLY: allow `skillopt_unschedule` to remove every managed entry |\n| `timeoutMs` | `600000` | per-call engine timeout in milliseconds |\n\nAdvanced engine keys (`gate_mode`, `gate_metric`, `gate_no_regression`,\n`dream_rollouts`, `recall_k`, `evolve_memory`/`evolve_skill`) go in\n`~/.skillopt-sleep/config.json` — the same file shared by all integrations.\n\n## Data boundary\n\n- Harvest is read-only; `mock`/`handoff` make no network calls.\n- `run` stages proposals; `adopt` is the normal live-change boundary and backs up first.\n- Real backends send truncated transcript excerpts and derived tasks to the\n  selected provider. For sensitive sessions, export tasks first (`skillopt_harvest`\n  with `output=`), redact, set `\"reviewed\": true`, then replay — real backends\n  refuse unreviewed task files.\n- Outbound prompts are not guaranteed secret-free; review source & provider policy.\n\n## Validate (no API spend)\n\n```bash\npython -m skillopt_sleep.experiments.run_experiment --persona researcher --assert-improves\n```\n\nSee the [SkillOpt-Sleep documentation](../../docs/sleep/README.md) for recorded\nresults, limitations, and the supported integration surface.\n","plugins/dsh/skills/skillopt-sleep/SKILL.md":"---\nname: skillopt-sleep\ndescription: \"Use when the user wants the dsh agent to self-improve from past usage, asks about a nightly/offline 'sleep' or 'dream' cycle, skill/memory consolidation, or says things like 'make my agent better the more I use it', 'review my past sessions', 'learn my preferences', 'consolidate what you learned', 'run the sleep cycle', or wants to schedule background self-optimization. Drives the skillopt_sleep engine through the skillopt_* tools: harvest past sessions -> mine recurring tasks -> replay via a selected backend -> consolidate validated skills behind a held-out gate.\"\n---\n\n# SkillOpt-Sleep: usage-driven self-evolution for the dsh agent\n\nSkillOpt-Sleep is Microsoft's [SkillOpt](https://github.com/microsoft/SkillOpt)\ndeployment-time companion engine: it reviews your past sessions (harvest), mines\nrecurring tasks (mine), replays them through a selected backend (replay), and\nconsolidates what it learns into skill documents behind a **held-out validation\ngate** (consolidate).\n\nThis skill drives the engine through the 7 `skillopt_*` tools exposed by the\ndsh-skillopt plugin. The default `mock` backend makes no model calls, which is\nuseful for verifying the plumbing; a real backend consumes your API budget.\n\n## When to use\n\n- \"make my agent better the more I use it\" / \"learn my preferences across sessions\"\n- a one-off **offline self-evolution / sleep / dream** run (immediate or scheduled)\n- review past sessions/trajectories and distill recurring tasks\n- consolidate feedback into `AGENTS.md` / `SKILL.md` / managed skills\n- schedule (cron) the cycle, or adopt a staged proposal\n\n## The cycle (six stages)\n\n1. **Harvest** — read-only scan of supported local session records → digests\n2. **Mine** — digests → recurring task records (intent + outcome labels + checkable refs)\n3. **Replay** — re-run tasks under the current skill+memory with the selected backend → (hard, soft) scores\n4. **Consolidate** — reflect on failures → propose bounded edits → **validation gate** on a held-out slice (default: accept only on strict improvement)\n5. **Stage** — write accepted proposals to `<project>/.skillopt-sleep/staging/<timestamp>/`. **Live files are unchanged.** A rejected run still has a report but no proposal files.\n6. **Adopt** — explicit (or operator-configured `--auto-adopt`) copies staged files over live ones, backing up first.\n\n## Driving it\n\nPrefer the tools over hand-editing files:\n\n| Tool | Behavior |\n|---|---|\n| `skillopt_status` | state, engine availability, latest staged proposal & report |\n| `skillopt_dry_run` | full preview (harvest+mine+replay), stages nothing |\n| `skillopt_run` | full cycle, stages a proposal (live files unchanged by default) |\n| `skillopt_adopt` | apply latest staged proposal (with backup) — the live-change boundary |\n| `skillopt_harvest` | read-only show/export of mined tasks |\n| `skillopt_schedule` / `skillopt_unschedule` | install/remove the nightly cron entry for this project |\n\nTypical flow:\n\n```text\n# 1. check state (default mock backend, zero cost)\nskillopt_status\n\n# 2. preview the cycle\nskillopt_dry_run project=<dir> source=<claude|codex|…>\n\n# 3. real run (consumes the selected backend's API budget)\nskillopt_run project=<dir> backend=<codex|claude|…> preferences=\"Prefer pytest; keep commits imperative.\"\n\n# 4. review the report, then adopt\nskillopt_adopt project=<dir>\n\n# 5. schedule nightly at 03:17\nskillopt_schedule project=<dir> hour=3 minute=17 backend=<codex>\n```\n\n## Parameters\n\n| Parameter | Default | Meaning |\n|---|---|---|\n| `project` | config or cwd | project directory to evolve |\n| `backend` | `mock` | `mock\\|claude\\|codex\\|copilot\\|cursor\\|pi\\|opencode\\|handoff\\|azure_openai` (mock = no model calls) |\n| `source` | config | transcript source: `claude\\|codex\\|copilot\\|cursor\\|pi\\|opencode\\|auto` |\n| `model` | backend default | replay model override |\n| `maxTasks` | 40 | mined-task cap |\n| `preferences` | empty | house rules for the reflection prior (e.g. \"always use async/await\") |\n\n## Configuration (cordis.yml / bundle patch)\n\n```yaml\n- insert:\n    - id: skillopt\n      name: './src/index.js'\n      config:\n        backend: codex\n        project: /path/to/project\n        preferences: 'Always use async/await'\n        # auto-adopt is OPERATOR-ONLY — the model cannot set it\n        autoAdopt: false\n```\n\nAdvanced engine keys go in `~/.skillopt-sleep/config.json`:\n`gate_mode` (on/off), `gate_metric` (hard/soft/mixed), `gate_no_regression`,\n`dream_rollouts`, `recall_k`, `evolve_memory` / `evolve_skill`.\n\n## Hard rules\n\n- **Never** hand-edit `AGENTS.md` / `SKILL.md` around `skillopt_adopt`; let the\n  engine's explicit adopt (or operator-configured `--auto-adopt`) apply the\n  staging manifest, backing up live files first.\n- Harvest is read-only; `mock` replay has no side effects.\n- Real backends send truncated transcript excerpts and derived tasks to the\n  selected provider for mining/replay/judging/reflection. For sensitive\n  sessions, export tasks first (`skillopt_harvest output=<file>`), redact, set\n  the top-level `\"reviewed\"` to `true`, then replay with `--tasks-file`; real\n  backends refuse unreviewed task files.\n- Show the user the **held-out baseline → candidate** score and the exact\n  proposed edits before suggesting adoption. Evidence before adoption.\n\n## Validate / demo (no API spend)\n\n```bash\npip install skillopt\npython -m skillopt_sleep.experiments.run_experiment --persona researcher --assert-improves\n```\n\nDeterministic synthetic demo: the score rises and the gate blocks a regression.\nIt validates the mechanism, not effectiveness on your own tasks.\n\nSee the [SkillOpt-Sleep docs](https://github.com/microsoft/SkillOpt/tree/main/docs/sleep)\nfor recorded results and limitations.\n","plugins/openclaw/README.md":"# OpenClaw reference adaptation for SkillOpt-Sleep\n\nThis directory is a contributed reference for connecting\n[SkillOpt-Sleep](https://github.com/microsoft/SkillOpt) to\n[OpenClaw](https://github.com/openclaw/openclaw) with a custom DeepSeek/Ollama\nbackend.\n\n> **Reference status.** This is not one of the shared, plug-and-play\n> `skillopt_sleep` wrappers. Several scripts and the sample config contain\n> environment-specific absolute paths and assumptions from the original setup,\n> and the contributed wrapper has unresolved Python 3.10 syntax and backend\n> factory-signature gaps. The current checkout is not directly runnable; treat\n> it as porting source material, not an installation.\n\n## Included components\n\n| File | Purpose |\n|---|---|\n| `run_sleep.py` | custom cycle entry point |\n| `skillopt_sleep_openclaw.py` | DeepSeek Chat Completions backend plus local Ollama embeddings |\n| `run_sleep_cron.sh` | category-oriented cron wrapper |\n| `slash_sleep.py` | experimental `/sleep` command helper |\n| `config.json` | example engine configuration |\n| `SKILL.md` | OpenClaw skill manifest |\n| `tests/*.json` | example task sets for research, DevOps, and wiki workflows |\n\nThe adaptation imports the shared engine but registers its own backend and\nmaintains its own wrapper behavior. Changes to the shared CLI documentation do\nnot automatically make every option available through these custom scripts.\n\n## Intended cycle\n\n```text\nharvest supported session data or load a task file\n  → replay with the current skill\n  → propose bounded edits\n  → validate the candidate on held-out tasks\n  → stage a proposal for operator review\n```\n\nThe intended safety boundary is manual adoption: review the generated report and\nstaged files before changing a live skill.\n\n## Adapt before use\n\n1. Clone SkillOpt into a location you control:\n\n   ```bash\n   git clone https://github.com/microsoft/SkillOpt.git\n   cd SkillOpt/plugins/openclaw\n   ```\n\n2. Inspect and replace the sample absolute paths in `run_sleep.py`,\n   `slash_sleep.py`, `run_sleep_cron.sh`, and `config.json`. Confirm the engine\n   checkout, OpenClaw workspace, state directory, skill directory, and task-file\n   paths all point to isolated test locations.\n\n3. Review `config.json`. In particular, do not assume that values such as\n   `replay_mode` are enforced by this custom wrapper merely because they appear\n   in the example config. `max_tokens_per_night` is applied by the shared cycle,\n   but it is measured with the wrapper backend's rough `tokens_used()` estimate\n   (a quarter of the attempt prompt length plus 200 per attempt, 600 per rubric\n   judge call, and a third of the reflect prompt plus 1500 per reflect call), so\n   it is not a billing limit.\n\n4. Supply credentials through your normal secret-management mechanism. Do not\n   commit a DeepSeek key or place it in a world-readable file.\n\n5. Resolve every known porting gap listed in [`SKILL.md`](SKILL.md), add\n   isolated tests for your adapted backend, and verify that `--help` imports\n   cleanly on Python 3.10+. Only then start with a dry run and one reviewed\n   task file. The target command should be shaped like:\n\n   ```bash\n   cd /path/to/SkillOpt/plugins/openclaw\n   python3 run_sleep.py --config /path/to/reviewed-config.json \\\n     --tasks tests/research-cron-tasks.json --dry-run\n   ```\n\n6. Inspect the report, paths, network destinations, and proposed edits before\n   considering a non-dry run or scheduling.\n\n## Data boundary\n\nThe custom `openclaw-deepseek` backend sends task, skill, response, rubric, and\nreflection content to the configured DeepSeek endpoint. Its embedding helper can\nsend truncated text to the configured local Ollama service. Do not assume these\noutbound prompts have been fully redacted; inspect transcript/task inputs and the\nprovider's retention policy before using real data.\n\nUse HTTPS for a remote DeepSeek-compatible endpoint. Keep any plaintext Ollama\nendpoint on a trusted loopback interface. For a network-free engine smoke test,\nuse the shared SkillOpt-Sleep CLI with `--backend mock` rather than assuming this\ncustom wrapper is isolated.\n\n## Scheduling\n\n`run_sleep_cron.sh` and the scheduling helpers are examples, not portable\ninstallers. Adapt their paths, create log directories, verify their environment,\nand run the exact command manually before adding a cron entry. Scheduled runs\nmust preserve the same manual-adoption and credential boundaries as interactive\nruns.\n\n## Validation scope\n\nThe bundled JSON files are example held-out task sets, not a universal OpenClaw\nbenchmark. Provider cost and quality depend on the selected model, task content,\nnumber of calls, and pricing at run time; this reference does not promise a fixed\nnightly cost. Validate the adapted workflow in an isolated workspace before\nusing it on live skills.\n\nFor the supported shared-engine CLI and its current flags, see the\n[integration reference](../README.md#supported-cli-surface). For measured\nSkillOpt-Sleep results and limitations, see\n[`docs/sleep/RESULTS.md`](../../docs/sleep/RESULTS.md).\n\n## License\n\nMIT, consistent with SkillOpt core.\n","plugins/openclaw/SKILL.md":"---\nname: skillopt-sleep\ndescription: Reference-only OpenClaw adaptation of SkillOpt-Sleep. Use it to study or port the contributed DeepSeek wrapper, not as a ready-to-run installation.\n---\n\n# SkillOpt-Sleep OpenClaw reference adaptation\n\nThis directory is a contributed **reference**, not a supported, plug-and-play\nOpenClaw integration. It illustrates one way to connect the shared\n`skillopt_sleep` cycle to a custom DeepSeek Chat Completions backend and a set of\nenvironment-specific task fixtures.\n\nDo not run or schedule the files unchanged. Several scripts and the sample\nconfiguration preserve assumptions from the contributor's original machine,\nand parts of the wrapper have not yet been ported to the current shared-engine\ninterfaces. Start with the directory's [README.md](README.md), which is the\nauthoritative status and adaptation guide.\n\n## What is included\n\n- `skillopt_sleep_openclaw.py` — a contributed DeepSeek backend prototype. It\n  also contains an Ollama embedding helper, but that helper is not wired into\n  the current shared sleep cycle.\n- `run_sleep.py` — a custom cycle wrapper with environment-specific paths and a\n  backend-registration shim.\n- `slash_sleep.py` — an experimental command helper written for an older\n  staging-manifest shape.\n- `run_sleep_cron.sh` — a machine-specific category runner, not a portable cron\n  installer.\n- `config.json` — a sample configuration, not a set of guaranteed or enforced\n  runtime limits.\n- `tests/*.json` — example task fixtures from one environment, not a universal\n  OpenClaw benchmark.\n\n## Known porting gaps\n\nBefore treating this as an integration, a maintainer must at least:\n\n1. Replace every absolute workspace, repository, state, skill, log, and task\n   path with explicit user configuration.\n2. Update the custom backend factory to the current `get_backend` call contract,\n   including the project directory, and update its backend methods and edit\n   records to the current protocol.\n3. Replace the experimental adoption logic with the current staging manifest\n   and `skillopt_sleep.staging.adopt` behavior. Current staging artifacts use\n   `proposed_SKILL.md` / `proposed_CLAUDE.md`, `manifest.json`, and report files;\n   they do not expose the old `manifest.proposed_skill` field.\n4. Decide how real OpenClaw transcripts are converted into a supported session\n   format. Pointing `claude_home` at an arbitrary agent directory does not by\n   itself make its files Claude Code-compatible JSONL.\n5. Build scheduling around the adapted wrapper. The shared scheduler launches\n   the shared CLI; it does not automatically preserve this custom backend or\n   its category task-file flow.\n6. Add isolated end-to-end tests for dry-run, accepted/rejected gates, staging,\n   adoption and backup, credential failure, and scheduled execution.\n\nUntil those gaps are resolved, use the supported shared\n`python -m skillopt_sleep` CLI with `--backend mock` to test SkillOpt-Sleep itself,\nand treat this directory only as source material for a future OpenClaw port.\n\n## Shared-engine features are not wrapper features\n\nAt this revision the supported shared CLI backends are `mock`, `claude`,\n`codex`, `copilot`, `handoff`, and `azure_openai`; the\n[plugin integration reference](../README.md#supported-cli-surface) is the\nauthoritative list. The shared engine can consolidate a selected skill and\nproject `CLAUDE.md` memory (controlled by `evolve_skill` and `evolve_memory`),\nand its `schedule` / `unschedule` actions manage shared-engine cron entries.\nThose capabilities do **not** make the custom OpenClaw wrapper portable: the\nshared scheduler will not invoke the prototype backend or its category\nfixtures. Use the shared documentation for those features, not this reference\nSKILL.\n\n## Data and credential boundary\n\nThe prototype DeepSeek backend sends task, skill, memory, response, rubric, and\nreflection content to its configured Chat Completions endpoint. Its source also\ncontains a helper that can send text to an Ollama service if a future port wires\nthat helper into the cycle. Neither path should be assumed to remove every\nsecret or private detail.\n\nBefore any port is tested with real data:\n\n- use isolated, synthetic or explicitly reviewed task files;\n- replace sample business names, personal references, URLs, and machine paths;\n- load credentials through the operator's secret-management mechanism;\n- verify TLS and retention policy for every remote endpoint; and\n- inspect all staged artifacts before adoption.\n\nThe bundled fixtures are examples only. Their scores and any old cost estimates\ndo not establish effectiveness, safety, or a stable nightly price for another\nOpenClaw deployment.\n\n## Further information\n\n- [OpenClaw README](README.md) — current reference status and adaptation checklist\n- [plugin integration reference](../README.md) — supported shared-engine CLI\n  surface and data boundary\n- [SkillOpt-Sleep documentation](../../docs/sleep/README.md) — concepts,\n  results, and limitations\n\nContributions that turn this reference into a portable integration should add\ntests and update all three documents together.\n","skillopt/envs/alfworld/skills/initial.md":"# ALFWorld Embodied Agent Skill\n\n## Overview\nThis skill guides agents operating in the ALFWorld text-based embodied environment.\nThe agent must complete household tasks by navigating rooms, interacting with objects,\nand using appliances. Actions must be chosen from the admissible action list provided\nat each step.\n\n**Output format**: Always output `<think>...</think>` for reasoning, then `<action>...</action>` for the chosen action.\n\n---\n\n## Task Types\n\n| Type | Goal | Key Steps |\n|------|------|-----------|\n| Pick & Place | Put object X in/on receptacle Y | Find X -> take X -> go to Y -> put X in/on Y |\n| Pick Two & Place | Put two instances of X in/on Y | Find X1 -> take -> place -> find X2 -> take -> place |\n| Examine in Light | Examine object X under desklamp | Find X -> take X -> find desklamp -> use desklamp |\n| Clean & Place | Clean object X and put in/on Y | Find X -> take X -> go to sink -> clean X -> go to Y -> put X |\n| Heat & Place | Heat object X and put in/on Y | Find X -> take X -> go to microwave -> heat X -> go to Y -> put X |\n| Cool & Place | Cool object X and put in/on Y | Find X -> take X -> go to fridge -> cool X -> go to Y -> put X |\n\n---\n\n## General Principles\n\n1. **Decompose the task**: Parse the goal into ordered sub-goals (locate, acquire, transform, deliver). Complete each before moving to the next.\n2. **Systematic exploration**: Search each surface and container exactly once before revisiting. Open closed containers (drawers, cabinets, fridge) before judging them empty.\n3. **Grab immediately**: When a required object is visible and reachable, take it right away before moving elsewhere.\n4. **Transform before placing**: If the task requires cleaning, heating, or cooling, perform the state change at the appropriate appliance before heading to the final destination.\n5. **Direct delivery**: Once holding the transformed (or untransformed) goal object, navigate straight to the target receptacle and place it.\n6. **Track progress**: Maintain an internal count of how many objects still need to be found and placed. Only stop searching when the count reaches zero.\n7. **Avoid loops**: Never repeat the same action more than twice in a row. If stuck, move to a different unexplored location.\n8. **Only choose admissible actions**: Always pick an action from the admissible action list. Do not invent actions.\n\n---\n\n## Common Mistakes to Avoid\n\n- **Revisiting searched locations**: Keep track of which surfaces/containers have been checked; do not re-examine them.\n- **Ignoring visible objects**: If the target object appears in the observation, pick it up immediately.\n- **Skipping state changes**: Do not place an object at the destination without first cleaning/heating/cooling it when required.\n- **Premature termination**: Do not stop the episode until all goal conditions are verified as met.\n- **Action loops**: Repeatedly toggling or examining the same object wastes steps. Move on to new locations instead.\n","skillopt/envs/docvqa/skills/initial.md":"# DocVQA Skill\n\n## Visual Evidence Discipline\n- Read the document carefully before answering.\n- Prefer the smallest exact text span that answers the question.\n- When several nearby strings look similar, choose the one whose surrounding labels or layout best match the question.\n\n## Exact Answer Discipline\n- Copy names, numbers, and dates exactly from the document whenever possible.\n- Prefer direct extraction over paraphrase.\n- Before finalizing, compare the answer against nearby alternatives and keep the best-supported exact span.\n","skillopt/envs/livemathematicianbench/skills/initial.md":"# Live Mathematical MCQ Heuristics\n\n## Option Comparison\n- Compare all options before committing. The correct choice is often the strongest statement justified by the question, while nearby distractors are weaker, overstrong, or miss an equality case.\n- Track exact quantifiers such as \"there exists\", \"for every\", \"if and only if\", and \"exactly when\".\n\n## Theorem-Level Precision\n- Check whether an option weakens the conclusion by dropping a characterization, equality clause, or full equivalence.\n- Check whether an option overstates the theorem by upgrading regularity, removing scale restrictions, or changing an existential statement into a universal one.\n\n## Hypotheses\n- Verify the hypotheses and domain carefully. Distractors often keep the theorem shape but alter the required assumptions.\n- Pay close attention to equality cases, extremal conditions, and whether a result applies to the full family or only a restricted subfamily.\n\n## Final Answer\n- Output the final answer as the single option label only.\n","skillopt/envs/officeqa/skills/initial.md":"# OfficeQA Skill\n\n## Retrieval Discipline\n- Start by narrowing to the most likely candidate file before reading long passages.\n- Prefer targeted search terms that name the exact entity, period, measure, or table concept from the question.\n- After a promising match, read only a small surrounding span and verify it matches the requested year, basis, and unit.\n\n## Evidence Discipline\n- Extract the exact value from the retrieved text before doing any arithmetic.\n- Keep track of each operand's period, unit, and semantic role so nearby proxy values are not mixed in.\n- If the question asks for a transformed or derived quantity, compute only after confirming every operand.\n\n## Final Answer Discipline\n- Return the final answer only after one last consistency check against the retrieved evidence.\n- Copy the final answer from a checked value, not from an unverified intermediate guess.\n","skillopt/envs/searchqa/skills/initial.md":"# Question Answering Skill\n\n(No learned rules yet. Rules will be added through the reflection process.)\n","skillopt/envs/spreadsheetbench/skills/initial.md":"# Spreadsheet Manipulation Skill (xlsx)\n\n## Overview\nThis skill guides agents in manipulating Excel (.xlsx) spreadsheets using Python.\n\n**Primary libraries**: `openpyxl` (structure-preserving read/write), `pandas` (data transformation).\nNever use any other third-party libraries.\n\n---\n\n## Common Workflow\n\n1. **Explore** the input file: list sheets, inspect headers, check dimensions.\n2. **Write `solution.py`** with `INPUT_PATH` and `OUTPUT_PATH` defined at the top.\n3. **Execute** `python solution.py` and verify the output file was created.\n4. **Confirm** the target cells/range contain the expected values.\n\n---\n\n## Library Selection\n\n| Use case | Library |\n|----------|---------|\n| Preserve formulas, formatting, named ranges | `openpyxl` |\n| Bulk data transformation, aggregation, sorting | `pandas` → write back with `openpyxl` |\n| Simple cell read/write | `openpyxl` |\n\n**Warning**: `pandas.to_excel()` silently destroys existing formulas and named ranges.\nWhen writing back to a spreadsheet that contains formulas, always use `openpyxl.save()`.\n\n---\n\n## solution.py Template\n\n```python\nimport openpyxl\nimport pandas as pd\n\nINPUT_PATH  = \"...\"   # set to the actual input path\nOUTPUT_PATH = \"...\"   # set to the actual output path\n\nwb = openpyxl.load_workbook(INPUT_PATH)\nws = wb.active  # or wb[\"SheetName\"]\n\n# --- perform manipulation ---\n\nwb.save(OUTPUT_PATH)\n```\n\n---\n\n## Output Requirements\n\n- Save the result to `OUTPUT_PATH`.\n- Do not hardcode row counts or column letters — iterate over actual rows in the workbook.\n- Preserve sheets and cells not mentioned in the instruction.\n"},"items":[{"name":"SKILL.md","path":"plugins/claude-code/skills/skillopt-sleep/SKILL.md","rawUrl":"https://raw.githubusercontent.com/microsoft/SkillOpt/HEAD/plugins/claude-code/skills/skillopt-sleep/SKILL.md","title":"skillopt-sleep","category":"anthropic-skill","format":"markdown","content":"---\nname: skillopt-sleep\ndescription: \"Use when the user wants their Claude agent to self-improve from past usage, asks about a nightly/offline 'sleep' or 'dream' cycle, memory/skill consolidation, or says things like 'make my agent better the more I use it', 'review my past sessions', 'learn my preferences', 'consolidate what you learned', 'run the sleep cycle', or wants to schedule background self-optimization. Drives the skillopt_sleep engine: harvest past sessions -> mine recurring tasks -> replay through a selected backend -> consolidate validated CLAUDE.md/SKILL.md behind a held-out gate.\"\n---\n\n# SkillOpt-Sleep: usage-driven self-evolution for a local Claude agent\n\nSkillOpt-Sleep gives the user's agent a **sleep cycle**. On demand or on a\nnightly schedule, it reviews real past Claude Code sessions, re-runs recurring\ntasks through the selected backend, and consolidates what it\nlearns into **memory** (`CLAUDE.md`) and **skills** (`SKILL.md`). With the\ndefault validation gate enabled, it keeps only changes that improve a held-out\nscore. Live files change only through explicit adoption or a user-requested\n`--auto-adopt`. It aims to improve this user's recurring work, while making\neach accepted proposal measurable on the run's held-out tasks,\nwith no model-weight training. It is the deployment-time analogue of training:\nshort-term experience → long-term competence.\n\nIt synthesizes three ideas:\n- **SkillOpt** — the skill/memory doc is trainable text; bounded add/delete/replace\n  edits; accepted only through a held-out gate; rejected edits are recorded in\n  the run report for review.\n- **Claude Dreams** — consolidation that reads past sessions and proposes changes\n  inside protected learned blocks; the input is never mutated, and output is\n  reviewed before adoption.\n- **Agent sleep** — periodic background replay turns episodes into durable skill.\n\n## When to use this skill\n\nTrigger when the user wants any of:\n- \"make my agent learn from how I use it\" / \"get better the more I use it\" / \"remember my preferences across sessions\"\n- a nightly/scheduled or on-demand **offline self-improvement / dream / sleep** run\n- to **review past sessions/trajectories** and distill recurring tasks\n- to **consolidate** feedback into `CLAUDE.md` or a managed skill\n- to **schedule** the cycle (cron) or **adopt** a staged proposal\n\n## The cycle (six stages)\n\n1. **Harvest** — read `~/.claude/projects/*/<session>.jsonl` + `~/.claude/history.jsonl` (READ-ONLY) → session digests.\n2. **Mine** — digests → `TaskRecord`s (recurring intents + outcome labels + checkable refs where possible).\n3. **Replay** — re-run tasks through the selected backend under the *current*\n   skill+memory → (hard, soft) scores.\n4. **Consolidate** — reflect on failures → propose bounded edits → **gate** on a held-out slice; with the default gate enabled, accept only if it strictly improves.\n5. **Stage** — write the accepted `proposed_CLAUDE.md` and/or\n   `proposed_SKILL.md`, plus `report.md`, `report.json`, `manifest.json`, and\n   `diagnostics.json` into `<project>/.skillopt-sleep/staging/<timestamp>/`.\n   **Nothing live changes.** A rejected run still has a report but no proposed\n   live-file replacement.\n6. **Adopt** — explicit (or opt-in auto): copy staged files over live ones, backing up first.\n\n## How to drive it\n\nPrefer the `/skillopt-sleep` command. Under the hood it calls the bundled runner:\n\n```bash\n\"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh\" status                       # what's happened\n\"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh\" dry-run --project \"$(pwd)\"    # no-staging preview\n\"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh\" run --project \"$(pwd)\"        # full cycle, stages a proposal\n\"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh\" adopt --project \"$(pwd)\"      # apply staged proposal (with backup)\n```\n\n- Default backend is `mock` (deterministic, **no API spend**) — good for trying the plumbing.\n- Add `--backend claude` or `--backend codex` to spend the user's real budget\n  for model-driven optimization. A held-out gain is run-specific evidence, not\n  a guarantee of broader improvement; results depend on the tasks, model, and\n  checks.\n- Scope defaults to the invoked project; `--scope all` harvests every Claude\n  project into the current run's configured targets.\n- A real backend sends truncated transcript/task content to its provider. See\n  the data-boundary rules below before using one with sensitive sessions.\n\n### Scheduling\n\n```bash\n\"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh\" schedule --project \"$(pwd)\" --hour 3 --minute 17\n\"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh\" unschedule --project \"$(pwd)\"\n```\n\nInstalls a nightly cron entry. `unschedule --all` removes every managed entry.\n\n## Common CLI flags\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `--project PATH` | cwd | Project directory to evolve |\n| `--scope all\\|invoked` | invoked | Harvest scope |\n| `--backend mock\\|claude\\|codex\\|copilot\\|handoff\\|azure_openai` | mock | Backend (mock = no provider calls) |\n| `--model NAME` | backend default | Override the model used for replay |\n| `--source claude\\|codex\\|auto` | claude | Transcript source |\n| `--lookback-hours N` | 72 | Harvest window |\n| `--max-sessions N` | derived | Cap harvested sessions; defaults to 3 × max tasks (120 with current defaults) |\n| `--max-tasks N` | 40 | Cap mined tasks |\n| `--target-skill-path PATH` | `~/.claude/skills/skillopt-sleep-learned/SKILL.md` | Explicit SKILL.md to evolve |\n| `--tasks-file PATH` | — | Reviewed TaskRecord JSON (skip harvest) |\n| `--progress` | off | Print phase progress to stderr |\n| `--auto-adopt` | off | Auto-adopt if gate passes |\n| `--edit-budget N` | 4 | Max bounded edits per night |\n| `--preferences TEXT` | empty | Add house rules to the optimizer's reflection prior |\n| `--json` | off | Machine-readable JSON output |\n\nThe CLI also has source/runtime path overrides (`--claude-home`, `--codex-home`,\nand `--codex-path`) and action-specific flags. Use\n`python -m skillopt_sleep <action> --help` as the authoritative surface.\n\n## Config keys (`~/.skillopt-sleep/config.json`)\n\nBeyond the CLI flags, advanced behavior is controlled via config:\n\n- **`preferences`** — free-text house rules injected into the optimizer's reflect step (e.g. \"Always use async/await\", \"Answers in `\\boxed{}`\").\n- **`gate_mode`** — `on` (default, validation-gated) or `off` (greedy, accept all edits).\n- **`gate_metric`** — `hard`, `soft`, or `mixed` (default). Controls how the held-out gate scores.\n- **`gate_no_regression`** — `false` by default. Set to `true` to reject a candidate when any validation task's configured gate score decreases.\n- **`dream_rollouts`** — >1 enables multi-rollout contrastive reflection per task.\n- **`recall_k`** — >0 recalls K similar past tasks into the dream (long-term memory).\n- **`evolve_memory`** / **`evolve_skill`** — independently toggle CLAUDE.md vs SKILL.md consolidation.\n\n## Memory consolidation\n\nThe sleep cycle can consolidate both:\n- **SKILL.md** — the managed skill file (bounded edits: add/delete/replace)\n- **CLAUDE.md** — the project memory (same bounded edits)\n\nWith the default gate enabled, both are evaluated by the same held-out score.\nSet `evolve_memory: false` to consolidate only skills, or `evolve_skill: false`\nfor only memory.\n\n## Hard rules\n\n- **Never** hand-edit the user's `CLAUDE.md` / `SKILL.md` as part of this skill.\n  Let the engine's explicit `adopt` or user-requested `--auto-adopt` path apply\n  the staging manifest and back up existing live files first.\n- Harvest is read-only. `mock` replay has no side effects.\n- Real backends send truncated transcript excerpts and derived tasks to the\n  selected provider for mining, replay, judging, and reflection. The Claude\n  transcript path is not guaranteed to remove every secret before those calls.\n  Review provider policy and session contents first. For sensitive data, use\n  `mock` or run `harvest --output <file>`, inspect/redact the JSON, set\n  `\"reviewed\": true`, and replay it with `--tasks-file`; real backends refuse an\n  unreviewed task file.\n- Always show the user the **held-out baseline → candidate** score and the\n  exact proposed edits before suggesting adoption. Evidence before adoption.\n- If asked to demonstrate the mechanism without provider calls, run\n  `python -m skillopt_sleep.experiments.run_experiment --persona researcher --json`\n  — a deterministic synthetic demo of held-out lift and gate rejection. It\n  validates the mechanism, not effectiveness on the user's own tasks.\n\n## Validate / demo\n\n```bash\n# deterministic synthetic demo (no API): score rises and the gate blocks a regression\npython -m skillopt_sleep.experiments.run_experiment --persona researcher --assert-improves\npython -m skillopt_sleep.experiments.run_experiment --persona programmer  --assert-improves\n```\n\nSee the [SkillOpt-Sleep documentation](https://github.com/microsoft/SkillOpt/tree/main/docs/sleep)\nfor recorded results, limitations, and the supported integration surface.\n","frontmatter":{"name":"skillopt-sleep","description":"Use when the user wants their Claude agent to self-improve from past usage, asks about a nightly/offline 'sleep' or 'dream' cycle, memory/skill consolidation, or says things like 'make my agent better the more I use it', 'review my past sessions', 'learn my preferences', 'consolidate what you learned', 'run the sleep cycle', or wants to schedule background self-optimization. Drives the skillopt_sleep engine: harvest past sessions -> mine recurring tasks -> replay through a selected backend -> consolidate validated CLAUDE.md/SKILL.md behind a held-out gate."},"isInternal":false,"tokens":2218,"sizeBytes":9054},{"name":"SKILL.md","path":"plugins/codex/skills/skillopt-sleep/SKILL.md","rawUrl":"https://raw.githubusercontent.com/microsoft/SkillOpt/HEAD/plugins/codex/skills/skillopt-sleep/SKILL.md","title":"skillopt-sleep","category":"anthropic-skill","format":"markdown","content":"---\nname: skillopt-sleep\ndescription: \"Use when the user wants Codex to self-improve from past usage, asks about a nightly/offline 'sleep' or 'dream' cycle, wants Codex to review past sessions, learn preferences, consolidate memory/skills, run dry-run/run/adopt/status for SkillOpt-Sleep, or schedule background self-optimization. Drives the skillopt_sleep engine: harvest past sessions -> mine recurring tasks -> replay through a selected backend -> consolidate validated memory + skills behind a held-out gate.\"\n---\n\n# SkillOpt-Sleep: usage-driven self-evolution for a local Codex agent\n\nSkillOpt-Sleep gives the user's Codex agent a sleep cycle. On demand or on a\nnightly schedule, it reviews past local sessions, re-runs recurring tasks\nthrough the selected backend, and proposes changes to a configured skill and to\nthe project's `CLAUDE.md`. With the default validation gate enabled, it keeps\nonly changes that improve a held-out score. Live files change only through\nexplicit adoption or a user-requested `--auto-adopt`. There is no model-weight\ntraining.\n\nThe current shared engine does **not** write `AGENTS.md`. For a Codex-visible\nresult, always select a Codex skill explicitly with `--target-skill-path` (for\nexample `.agents/skills/<name>/SKILL.md`). If project `CLAUDE.md` is not a\ndesired secondary target, set `\"evolve_memory\": false` in\n`~/.skillopt-sleep/config.json` before running.\n\n## When to use\n\nTrigger when the user wants any of:\n\n- Codex to learn from past sessions or get better the more they use it;\n- a nightly/scheduled or on-demand sleep/dream/offline self-improvement run;\n- to review past sessions and distill recurring tasks;\n- to consolidate feedback into memory or managed skills;\n- to run `status`, `harvest`, `dry-run`, `run`, or `adopt` for SkillOpt-Sleep.\n\n## The cycle\n\n1. **Harvest** - read local session transcripts according to the engine\n   configuration and normalize them into session digests.\n2. **Mine** - turn digests into recurring `TaskRecord`s with outcomes and\n   checkable references where possible.\n3. **Replay** - re-run mined tasks through the selected backend under the\n   current skill and memory.\n4. **Consolidate** - reflect on failures and propose bounded edits.\n5. **Gate** - with the default gate enabled, accept edits only when the held-out\n   validation score improves.\n6. **Stage** - write the proposal under\n   `<project>/.skillopt-sleep/staging/<date>/`; nothing live changes.\n7. **Adopt** - explicitly, or through user-requested auto-adopt, copy staged\n   files over live files with backups for existing targets.\n\n## How to drive it\n\nInvoke the bundled runner via shell (Codex `exec` has shell access). The runner\nfinds the engine and a Python >= 3.10 automatically.\n\n```bash\n# point at the repo if it isn't auto-detected from CWD:\nexport SKILLOPT_SLEEP_REPO=/path/to/SkillOpt\nTARGET_SKILL=.agents/skills/example/SKILL.md\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" status --project \"$(pwd)\"\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" harvest --project \"$(pwd)\" \\\n  --source codex --target-skill-path \"$TARGET_SKILL\"\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" dry-run --project \"$(pwd)\" \\\n  --source codex --target-skill-path \"$TARGET_SKILL\" --backend mock\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" run --project \"$(pwd)\" \\\n  --source codex --target-skill-path \"$TARGET_SKILL\" --backend codex \\\n  --max-sessions 5 --max-tasks 3 --progress\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" status --project \"$(pwd)\"\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" adopt --project \"$(pwd)\" --legacy\n```\n\nFor a fan-out night, select reviewed proposals with repeatable\n`--skill NAME` or `--all-skills`; do not treat bare adopt as “adopt everything.”\n\nOn Windows (CMD / PowerShell):\n```cmd\n:: CMD\nset SKILLOPT_SLEEP_REPO=C:\\path\\to\\SkillOpt-Sleep\n\"%SKILLOPT_SLEEP_REPO%\\plugins\\run-sleep.cmd\" status --project \"%CD%\"\n```\n```powershell\n# PowerShell\n$env:SKILLOPT_SLEEP_REPO = \"C:\\path\\to\\SkillOpt-Sleep\"\npowershell -File \"$env:SKILLOPT_SLEEP_REPO\\plugins\\run-sleep.ps1\" status --project \"$(pwd)\"\n```\n\nActions are `status`, `harvest`, `dry-run`, `run`, `adopt`, `schedule`, and `unschedule`.\n\n- Default backend is `mock`, which is deterministic and spends no API budget.\n- `--backend codex` uses the user's Codex budget for model-driven optimization.\n  An accepted held-out gain is run-specific evidence, not a guarantee of\n  broader improvement; results depend on the tasks, model, and checks.\n- `--source codex` reads Codex Desktop archived sessions from `~/.codex/archived_sessions`;\n  use `--codex-home /path/to/.codex` if the archive lives elsewhere.\n- `--target-skill-path` is required for a Codex skill target. Without it, the\n  shared default is a Claude-managed skill under `~/.claude/skills/`, not an\n  `.agents` skill.\n- Keep `dry-run --backend mock` as the first smoke check unless the user\n  explicitly asked for a real optimization run.\n\n### Scheduling\n\n```bash\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" schedule --project \"$(pwd)\" \\\n  --backend codex --hour 3 --minute 17\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" unschedule --project \"$(pwd)\"\n```\n\nThe scheduler persists the project, backend, time, and optional auto-adopt flag;\nit does not persist `--source` or `--target-skill-path` from this command. Before\nscheduling a Codex-targeted run, set `\"transcript_source\": \"codex\"` and an\nabsolute `\"target_skill_path\"` in `~/.skillopt-sleep/config.json`. On systems\nwithout `crontab`, `schedule` prints a line for manual installation.\n`unschedule --all` removes every managed entry.\n\n### All backends\n\n- `--backend mock` — deterministic, no API spend (default)\n- `--backend claude` — uses the Claude CLI\n- `--backend codex` — uses the Codex CLI\n- `--backend copilot` — uses the GitHub Copilot CLI\n- `--backend handoff` — emits prompt/answer files for an interactive session\n- `--backend azure_openai` — uses the configured Azure OpenAI endpoint\n\n### Additional flags\n\n| Flag | Description |\n|------|-------------|\n| `--auto-adopt` | Auto-adopt if the gate passes (default: stage only) |\n| `--edit-budget N` | Max bounded edits per night (default: 4) |\n| `--lookback-hours N` | Harvest window in hours (default: 72) |\n| `--json` | Machine-readable JSON output |\n\n### Config keys (`~/.skillopt-sleep/config.json`)\n\n- **`preferences`** — free-text house rules for the optimizer\n- **`gate_mode`** — `on` (validation-gated, default) or `off` (greedy)\n- **`gate_metric`** — `hard` | `soft` | `mixed` (default)\n- **`gate_no_regression`** — `false` by default; set it to `true` to reject a candidate when any validation task's gate score decreases\n- **`dream_rollouts`** — >1 for multi-rollout contrastive reflection\n- **`recall_k`** — >0 recalls similar past tasks from the archive\n\n### Memory consolidation\n\nThe shared sleep cycle consolidates project **memory** (`CLAUDE.md`) and the\nselected **skill** (`SKILL.md`) by default. It does not update `AGENTS.md`.\nEach target is independently toggleable through `evolve_memory` /\n`evolve_skill`, and both are gated by the same held-out validation score.\n\n## Steps\n\n1. Run the requested action; capture stdout.\n2. For `dry-run` and `run`, report the held-out baseline -> candidate score,\n   gate action, task count, session count, and exact proposed edits.\n3. If a staging directory is printed, read `report.md` before summarizing.\n4. `run` stages by default; if `--auto-adopt` was explicitly supplied, report\n   the paths it updated instead of claiming nothing changed.\n5. Offer adoption only after the user has reviewed a still-staged proposal.\n6. Never hand-edit the configured `CLAUDE.md` or target skill as a substitute\n   for the engine's adopt path; adoption is the safety boundary and backs up\n   existing targets first.\n\n## Hard rules\n\n- Harvest is read-only. Do not edit archived sessions or raw transcripts.\n- Codex transcript harvesting removes known secret-shaped strings, developer\n  instructions, and raw tool payloads, but pattern-based redaction is not a\n  guarantee. A real backend still sends truncated transcript/task content to\n  its provider. Review sensitive sessions and provider policy first; prefer a\n  reviewed `--tasks-file` workflow when the data boundary matters.\n- Keep raw secrets, credentials, private user data, and transcript contents out\n  of messages, logs, generated artifacts, and commits.\n- Show validation evidence before recommending adoption.\n- Treat generated edits as proposals, not as source of truth.\n- Do not rely on deprecated custom prompts or `/sleep` slash commands for this\n  Codex integration. This skill is the entrypoint.\n\n## Validate\n\n```bash\npython -m skillopt_sleep dry-run --project \"$(pwd)\" --source codex \\\n  --target-skill-path .agents/skills/example/SKILL.md --backend mock --json\npython -m skillopt_sleep.experiments.run_gbrain --backend codex \\\n  --seeds brief-writer --data-root /path/to/gbrain-evals/eval/data/skillopt-v1 \\\n  --nights 2 --limit-replay 3 --limit-holdout 3\n```\n\nIn the recorded `brief-writer` gbrain run, the deliberately deficient fixture\nwent 0.00 -> 1.00 on that run's held-out set. Treat this as reproducible\nbenchmark evidence for that configuration, not a guarantee for other skills,\ntasks, or models; see the\n[recorded results](https://github.com/microsoft/SkillOpt/blob/main/docs/sleep/RESULTS.md)\nfor context and limitations.\n","frontmatter":{"name":"skillopt-sleep","description":"Use when the user wants Codex to self-improve from past usage, asks about a nightly/offline 'sleep' or 'dream' cycle, wants Codex to review past sessions, learn preferences, consolidate memory/skills, run dry-run/run/adopt/status for SkillOpt-Sleep, or schedule background self-optimization. Drives the skillopt_sleep engine: harvest past sessions -> mine recurring tasks -> replay through a selected backend -> consolidate validated memory + skills behind a held-out gate."},"isInternal":false,"tokens":2354,"sizeBytes":9402},{"name":"SKILL.md","path":"plugins/cursor/skills/skillopt-sleep/SKILL.md","rawUrl":"https://raw.githubusercontent.com/microsoft/SkillOpt/HEAD/plugins/cursor/skills/skillopt-sleep/SKILL.md","title":"skillopt-sleep","category":"anthropic-skill","format":"markdown","content":"---\nname: skillopt-sleep\ndescription: \"Use when the user wants Cursor to learn from recent local sessions, asks for an offline sleep or dream cycle, wants to consolidate recurring work into a Cursor skill, or requests SkillOpt-Sleep status, harvest, dry-run, run, scheduling, review, or adoption. Drives the validation-gated skillopt_sleep engine with Cursor transcripts and the optional Cursor Agent CLI backend.\"\n---\n\n# SkillOpt-Sleep for Cursor\n\nSkillOpt-Sleep reviews recent local Cursor sessions, mines recurring tasks,\nreplays those tasks, and proposes bounded improvements to a project Cursor\nskill. With the default gate enabled, a proposal is accepted only when it\nimproves the held-out score. A normal run stages the proposal for review;\nnothing live changes until explicit adoption. There is no model-weight training.\n\nThis plugin has no session-end hook and no MCP server. Run the cycle only when\nthe user asks, or install a schedule only when the user explicitly requests one.\n\n## Cursor target\n\nAlways use this project-relative target for Cursor-visible learning:\n\n```text\n.cursor/skills/skillopt-sleep-learned/SKILL.md\n```\n\nPass it through `--target-skill-path` on `harvest`, `dry-run`, and `run`.\nWithout an explicit target, the shared engine uses a Claude-managed skill under\n`~/.claude/skills`, which is not the intended Cursor project skill.\n\nThe shared engine can also evolve project `CLAUDE.md`. If that secondary memory\ntarget is unwanted, set `\"evolve_memory\": false` in\n`~/.skillopt-sleep/config.json` before running.\n\n## Choose the runner\n\nUse one of these supported command paths consistently:\n\n1. Source checkout on macOS/Linux:\n   `bash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" <action> ...`\n2. Source checkout on Windows:\n   `powershell -File \"$env:SKILLOPT_SLEEP_REPO\\plugins\\run-sleep.ps1\" <action> ...`\n3. Installed engine on any platform:\n   `skillopt-sleep <action> ...`\n\nIf `SKILLOPT_SLEEP_REPO` is not set and `skillopt-sleep` is unavailable, stop\nand explain that the engine must be installed or a SkillOpt checkout must be\nselected. Do not substitute a hand-written edit for the engine workflow.\n\n## Core workflow\n\n1. **Harvest** local Cursor JSONL transcripts read-only.\n2. **Mine** recurring, checkable task records from session digests.\n3. **Replay** tasks under the current skill and memory through the selected\n   backend.\n4. **Reflect** on failures and propose bounded edits.\n5. **Gate** the candidate on held-out real tasks.\n6. **Stage** accepted proposals under\n   `<project>/.skillopt-sleep/staging/<timestamp>/`.\n7. **Adopt** only after review, backing up existing live targets first.\n\n## Commands\n\nUse the installed-command form below, or replace `skillopt-sleep` with the\nplatform-specific source runner described above.\n\n```bash\nTARGET_SKILL=.cursor/skills/skillopt-sleep-learned/SKILL.md\n\n# Inspect current state and the latest staged proposal.\nskillopt-sleep status --project \"$(pwd)\"\n\n# Inspect mined tasks without provider spend.\nskillopt-sleep harvest --project \"$(pwd)\" --source cursor \\\n  --target-skill-path \"$TARGET_SKILL\" --max-sessions 5 --max-tasks 3\n\n# First smoke check: deterministic and no provider calls.\nskillopt-sleep dry-run --project \"$(pwd)\" --source cursor --backend mock \\\n  --target-skill-path \"$TARGET_SKILL\" --max-sessions 5 --max-tasks 3 --json\n\n# Model-driven optimization through the authenticated Cursor Agent CLI.\nskillopt-sleep run --project \"$(pwd)\" --source cursor --backend cursor \\\n  --target-skill-path \"$TARGET_SKILL\" \\\n  --max-sessions 5 --max-tasks 3 --progress\n\n# Inspect selections, then apply the reviewed managed proposal.\nskillopt-sleep status --project \"$(pwd)\"\nskillopt-sleep adopt --project \"$(pwd)\" --legacy\n```\n\nFor fan-out proposals, use repeatable `--skill NAME` or `--all-skills` after\nreview. Bare adopt deliberately refuses a night containing fan-out rows.\n\nActions are `status`, `harvest`, `dry-run`, `run`, `adopt`, `schedule`, and\n`unschedule`.\n\n- Default backend is `mock`, which is deterministic and makes no provider calls.\n- `--backend cursor` uses the user's authenticated Cursor Agent CLI budget for\n  model-driven mining, replay, judging, and reflection.\n- `--source cursor` reads\n  `~/.cursor/projects/<workspace>/agent-transcripts/*/*.jsonl`.\n- `--cursor-home PATH` overrides the Cursor home used for harvesting.\n- `--scope invoked` selects the current workspace; `--scope all` includes every\n  Cursor workspace.\n- `--cursor-path PATH` or `SKILLOPT_SLEEP_CURSOR_PATH` selects a non-default\n  `cursor-agent` executable.\n- `--model NAME` or `SKILLOPT_SLEEP_CURSOR_MODEL` overrides the Cursor model.\n- Check model identifiers with `cursor-agent --list-models`; when cost matters,\n  verify the billed variant in Cursor's usage reporting.\n- Keep live runs bounded with `--max-sessions`, `--max-tasks`, and `--progress`.\n- A held-out gain is evidence for that run, not a promise of general improvement.\n\nThe first harvest uses a 72-hour lookback. Use `--lookback-hours N` for a wider\ninitial window or `--lookback-hours 0` for all available history. A stateful\n`run`, including a no-task run, records a harvest checkpoint; later runs use the\ncheckpoint rather than the initial lookback. Inspect counts with `harvest` or\n`dry-run` before the first real run because those actions do not advance state.\n\nAvailable backends are:\n\n- `mock` - deterministic, with no provider calls (default);\n- `cursor` - the authenticated Cursor Agent CLI;\n- `claude` - the authenticated Claude CLI;\n- `codex` - the authenticated Codex CLI;\n- `copilot` - the authenticated GitHub Copilot CLI;\n- `handoff` - prompt/answer files for an interactive agent session;\n- `azure_openai` - the configured Azure OpenAI endpoint.\n\nSkillOpt reads the target skill and inserts its text into replay prompts; it does\nnot invoke the file as a native Cursor skill. Ordinary Cursor backend calls run\nin a new empty temporary workspace in read-only Ask mode. File reads, file\nwrites, and MCP tools are denied. `--project` controls harvesting, target files,\nstate, and staging; it is not the Cursor Agent execution workspace.\n\nCursor tool-aware replay is temporarily disabled pending live Cursor\npermission-boundary validation. A task containing a `tool_called` check fails\nnonzero before Agent mode starts. The failed replay does not add a cache entry,\nstage, adopt, persist state, or advance the harvest checkpoint. Use another\nbackend for those tasks. Do not claim that repository- or tool-dependent\nbehavior was validated. The current engine does not implement a fresh-worktree\nreplay for Cursor.\n\nA real-backend `dry-run` still makes provider calls; it only suppresses staging.\nSession and task limits are workload bounds, not hard limits on calls, tokens,\ntime, or money. Start with small limits.\n\n## Reviewable data path\n\nCursor harvesting retains user/assistant text, tool names, and explicit turn\nerrors while excluding raw tool arguments, tool outputs, and non-message\nrecords. Known secret-shaped strings are redacted, but pattern-based redaction\ncannot guarantee that a transcript is safe to send to a provider.\n\nFor sensitive sessions, export tasks before any real-backend replay:\n\n```bash\nTARGET_SKILL=.cursor/skills/skillopt-sleep-learned/SKILL.md\nskillopt-sleep harvest --project \"$(pwd)\" --source cursor \\\n  --target-skill-path \"$TARGET_SKILL\" \\\n  --max-sessions 5 --max-tasks 3 --output reviewed-tasks.json\n```\n\nInspect and redact the file, then set its top-level `\"reviewed\"` field to\n`true`. Only then run:\n\n```bash\nskillopt-sleep dry-run --project \"$(pwd)\" --backend cursor \\\n  --tasks-file reviewed-tasks.json --progress --json\n```\n\nReal backends reject task files that remain unreviewed. Never include raw\ntranscripts, credentials, secrets, or sensitive task content in messages,\ncommits, or generated summaries.\n\n`gate_no_regression` is a config-only safeguard in\n`~/.skillopt-sleep/config.json`. It defaults to `false`; set it to `true` to\nreject a candidate when any validation task's configured gate score decreases.\n\n## Scheduling\n\nScheduling is opt-in. The scheduler persists project, backend, time, and the\noptional auto-adopt flag, but not `--source`, Cursor path/home/model overrides,\nor `--target-skill-path`. Before scheduling a Cursor cycle, set at least these values in\n`~/.skillopt-sleep/config.json`:\n\n```json\n{\n  \"transcript_source\": \"cursor\",\n  \"target_skill_path\": \".cursor/skills/skillopt-sleep-learned/SKILL.md\",\n  \"backend\": \"cursor\"\n}\n```\n\nThen run:\n\n```bash\nskillopt-sleep schedule --project \"$(pwd)\" --backend cursor --hour 3 --minute 17\nskillopt-sleep unschedule --project \"$(pwd)\"\n```\n\nThe scheduler uses cron on Unix and Task Scheduler on Windows. Scheduled runs\nstage proposals by default. Use `--auto-adopt` only when the user has explicitly\nrequested unattended adoption.\n\n## Report results\n\nFor `dry-run` and `run`, report:\n\n- session and task counts;\n- held-out baseline and candidate scores;\n- gate action and accepted/rejected edit counts;\n- exact proposed edits;\n- staging directory, when one was created.\n\nRead staged `report.md` before summarizing a run. Offer adoption only after the\nuser reviews an accepted proposal that is still staged. Never claim broad\nimprovement from one run.\n\n## Hard rules\n\n- Harvest is read-only. Never edit Cursor transcript files.\n- Never hand-edit the target skill or `CLAUDE.md` as a substitute for adoption.\n- Do not run a real backend on sensitive content without confirming its data\n  boundary or using the reviewed-task workflow.\n- Do not add a session-end hook or imply that installing this plugin schedules\n  anything.\n- Show validation evidence before recommending adoption.\n- Treat generated edits as proposals, not as source of truth.\n","frontmatter":{"name":"skillopt-sleep","description":"Use when the user wants Cursor to learn from recent local sessions, asks for an offline sleep or dream cycle, wants to consolidate recurring work into a Cursor skill, or requests SkillOpt-Sleep status, harvest, dry-run, run, scheduling, review, or adoption. Drives the validation-gated skillopt_sleep engine with Cursor transcripts and the optional Cursor Agent CLI backend."},"isInternal":false,"tokens":2284,"sizeBytes":9709},{"name":"SKILL.md","path":"plugins/dsh/skills/skillopt-sleep/SKILL.md","rawUrl":"https://raw.githubusercontent.com/microsoft/SkillOpt/HEAD/plugins/dsh/skills/skillopt-sleep/SKILL.md","title":"skillopt-sleep","category":"anthropic-skill","format":"markdown","content":"---\nname: skillopt-sleep\ndescription: \"Use when the user wants the dsh agent to self-improve from past usage, asks about a nightly/offline 'sleep' or 'dream' cycle, skill/memory consolidation, or says things like 'make my agent better the more I use it', 'review my past sessions', 'learn my preferences', 'consolidate what you learned', 'run the sleep cycle', or wants to schedule background self-optimization. Drives the skillopt_sleep engine through the skillopt_* tools: harvest past sessions -> mine recurring tasks -> replay via a selected backend -> consolidate validated skills behind a held-out gate.\"\n---\n\n# SkillOpt-Sleep: usage-driven self-evolution for the dsh agent\n\nSkillOpt-Sleep is Microsoft's [SkillOpt](https://github.com/microsoft/SkillOpt)\ndeployment-time companion engine: it reviews your past sessions (harvest), mines\nrecurring tasks (mine), replays them through a selected backend (replay), and\nconsolidates what it learns into skill documents behind a **held-out validation\ngate** (consolidate).\n\nThis skill drives the engine through the 7 `skillopt_*` tools exposed by the\ndsh-skillopt plugin. The default `mock` backend makes no model calls, which is\nuseful for verifying the plumbing; a real backend consumes your API budget.\n\n## When to use\n\n- \"make my agent better the more I use it\" / \"learn my preferences across sessions\"\n- a one-off **offline self-evolution / sleep / dream** run (immediate or scheduled)\n- review past sessions/trajectories and distill recurring tasks\n- consolidate feedback into `AGENTS.md` / `SKILL.md` / managed skills\n- schedule (cron) the cycle, or adopt a staged proposal\n\n## The cycle (six stages)\n\n1. **Harvest** — read-only scan of supported local session records → digests\n2. **Mine** — digests → recurring task records (intent + outcome labels + checkable refs)\n3. **Replay** — re-run tasks under the current skill+memory with the selected backend → (hard, soft) scores\n4. **Consolidate** — reflect on failures → propose bounded edits → **validation gate** on a held-out slice (default: accept only on strict improvement)\n5. **Stage** — write accepted proposals to `<project>/.skillopt-sleep/staging/<timestamp>/`. **Live files are unchanged.** A rejected run still has a report but no proposal files.\n6. **Adopt** — explicit (or operator-configured `--auto-adopt`) copies staged files over live ones, backing up first.\n\n## Driving it\n\nPrefer the tools over hand-editing files:\n\n| Tool | Behavior |\n|---|---|\n| `skillopt_status` | state, engine availability, latest staged proposal & report |\n| `skillopt_dry_run` | full preview (harvest+mine+replay), stages nothing |\n| `skillopt_run` | full cycle, stages a proposal (live files unchanged by default) |\n| `skillopt_adopt` | apply latest staged proposal (with backup) — the live-change boundary |\n| `skillopt_harvest` | read-only show/export of mined tasks |\n| `skillopt_schedule` / `skillopt_unschedule` | install/remove the nightly cron entry for this project |\n\nTypical flow:\n\n```text\n# 1. check state (default mock backend, zero cost)\nskillopt_status\n\n# 2. preview the cycle\nskillopt_dry_run project=<dir> source=<claude|codex|…>\n\n# 3. real run (consumes the selected backend's API budget)\nskillopt_run project=<dir> backend=<codex|claude|…> preferences=\"Prefer pytest; keep commits imperative.\"\n\n# 4. review the report, then adopt\nskillopt_adopt project=<dir>\n\n# 5. schedule nightly at 03:17\nskillopt_schedule project=<dir> hour=3 minute=17 backend=<codex>\n```\n\n## Parameters\n\n| Parameter | Default | Meaning |\n|---|---|---|\n| `project` | config or cwd | project directory to evolve |\n| `backend` | `mock` | `mock\\|claude\\|codex\\|copilot\\|cursor\\|pi\\|opencode\\|handoff\\|azure_openai` (mock = no model calls) |\n| `source` | config | transcript source: `claude\\|codex\\|copilot\\|cursor\\|pi\\|opencode\\|auto` |\n| `model` | backend default | replay model override |\n| `maxTasks` | 40 | mined-task cap |\n| `preferences` | empty | house rules for the reflection prior (e.g. \"always use async/await\") |\n\n## Configuration (cordis.yml / bundle patch)\n\n```yaml\n- insert:\n    - id: skillopt\n      name: './src/index.js'\n      config:\n        backend: codex\n        project: /path/to/project\n        preferences: 'Always use async/await'\n        # auto-adopt is OPERATOR-ONLY — the model cannot set it\n        autoAdopt: false\n```\n\nAdvanced engine keys go in `~/.skillopt-sleep/config.json`:\n`gate_mode` (on/off), `gate_metric` (hard/soft/mixed), `gate_no_regression`,\n`dream_rollouts`, `recall_k`, `evolve_memory` / `evolve_skill`.\n\n## Hard rules\n\n- **Never** hand-edit `AGENTS.md` / `SKILL.md` around `skillopt_adopt`; let the\n  engine's explicit adopt (or operator-configured `--auto-adopt`) apply the\n  staging manifest, backing up live files first.\n- Harvest is read-only; `mock` replay has no side effects.\n- Real backends send truncated transcript excerpts and derived tasks to the\n  selected provider for mining/replay/judging/reflection. For sensitive\n  sessions, export tasks first (`skillopt_harvest output=<file>`), redact, set\n  the top-level `\"reviewed\"` to `true`, then replay with `--tasks-file`; real\n  backends refuse unreviewed task files.\n- Show the user the **held-out baseline → candidate** score and the exact\n  proposed edits before suggesting adoption. Evidence before adoption.\n\n## Validate / demo (no API spend)\n\n```bash\npip install skillopt\npython -m skillopt_sleep.experiments.run_experiment --persona researcher --assert-improves\n```\n\nDeterministic synthetic demo: the score rises and the gate blocks a regression.\nIt validates the mechanism, not effectiveness on your own tasks.\n\nSee the [SkillOpt-Sleep docs](https://github.com/microsoft/SkillOpt/tree/main/docs/sleep)\nfor recorded results and limitations.\n","frontmatter":{"name":"skillopt-sleep","description":"Use when the user wants the dsh agent to self-improve from past usage, asks about a nightly/offline 'sleep' or 'dream' cycle, skill/memory consolidation, or says things like 'make my agent better the more I use it', 'review my past sessions', 'learn my preferences', 'consolidate what you learned', 'run the sleep cycle', or wants to schedule background self-optimization. Drives the skillopt_sleep engine through the skillopt_* tools: harvest past sessions -> mine recurring tasks -> replay via a selected backend -> consolidate validated skills behind a held-out gate."},"isInternal":false,"tokens":1472,"sizeBytes":5775},{"name":"SKILL.md","path":"plugins/openclaw/SKILL.md","rawUrl":"https://raw.githubusercontent.com/microsoft/SkillOpt/HEAD/plugins/openclaw/SKILL.md","title":"skillopt-sleep","category":"anthropic-skill","format":"markdown","content":"---\nname: skillopt-sleep\ndescription: Reference-only OpenClaw adaptation of SkillOpt-Sleep. Use it to study or port the contributed DeepSeek wrapper, not as a ready-to-run installation.\n---\n\n# SkillOpt-Sleep OpenClaw reference adaptation\n\nThis directory is a contributed **reference**, not a supported, plug-and-play\nOpenClaw integration. It illustrates one way to connect the shared\n`skillopt_sleep` cycle to a custom DeepSeek Chat Completions backend and a set of\nenvironment-specific task fixtures.\n\nDo not run or schedule the files unchanged. Several scripts and the sample\nconfiguration preserve assumptions from the contributor's original machine,\nand parts of the wrapper have not yet been ported to the current shared-engine\ninterfaces. Start with the directory's [README.md](README.md), which is the\nauthoritative status and adaptation guide.\n\n## What is included\n\n- `skillopt_sleep_openclaw.py` — a contributed DeepSeek backend prototype. It\n  also contains an Ollama embedding helper, but that helper is not wired into\n  the current shared sleep cycle.\n- `run_sleep.py` — a custom cycle wrapper with environment-specific paths and a\n  backend-registration shim.\n- `slash_sleep.py` — an experimental command helper written for an older\n  staging-manifest shape.\n- `run_sleep_cron.sh` — a machine-specific category runner, not a portable cron\n  installer.\n- `config.json` — a sample configuration, not a set of guaranteed or enforced\n  runtime limits.\n- `tests/*.json` — example task fixtures from one environment, not a universal\n  OpenClaw benchmark.\n\n## Known porting gaps\n\nBefore treating this as an integration, a maintainer must at least:\n\n1. Replace every absolute workspace, repository, state, skill, log, and task\n   path with explicit user configuration.\n2. Update the custom backend factory to the current `get_backend` call contract,\n   including the project directory, and update its backend methods and edit\n   records to the current protocol.\n3. Replace the experimental adoption logic with the current staging manifest\n   and `skillopt_sleep.staging.adopt` behavior. Current staging artifacts use\n   `proposed_SKILL.md` / `proposed_CLAUDE.md`, `manifest.json`, and report files;\n   they do not expose the old `manifest.proposed_skill` field.\n4. Decide how real OpenClaw transcripts are converted into a supported session\n   format. Pointing `claude_home` at an arbitrary agent directory does not by\n   itself make its files Claude Code-compatible JSONL.\n5. Build scheduling around the adapted wrapper. The shared scheduler launches\n   the shared CLI; it does not automatically preserve this custom backend or\n   its category task-file flow.\n6. Add isolated end-to-end tests for dry-run, accepted/rejected gates, staging,\n   adoption and backup, credential failure, and scheduled execution.\n\nUntil those gaps are resolved, use the supported shared\n`python -m skillopt_sleep` CLI with `--backend mock` to test SkillOpt-Sleep itself,\nand treat this directory only as source material for a future OpenClaw port.\n\n## Shared-engine features are not wrapper features\n\nAt this revision the supported shared CLI backends are `mock`, `claude`,\n`codex`, `copilot`, `handoff`, and `azure_openai`; the\n[plugin integration reference](../README.md#supported-cli-surface) is the\nauthoritative list. The shared engine can consolidate a selected skill and\nproject `CLAUDE.md` memory (controlled by `evolve_skill` and `evolve_memory`),\nand its `schedule` / `unschedule` actions manage shared-engine cron entries.\nThose capabilities do **not** make the custom OpenClaw wrapper portable: the\nshared scheduler will not invoke the prototype backend or its category\nfixtures. Use the shared documentation for those features, not this reference\nSKILL.\n\n## Data and credential boundary\n\nThe prototype DeepSeek backend sends task, skill, memory, response, rubric, and\nreflection content to its configured Chat Completions endpoint. Its source also\ncontains a helper that can send text to an Ollama service if a future port wires\nthat helper into the cycle. Neither path should be assumed to remove every\nsecret or private detail.\n\nBefore any port is tested with real data:\n\n- use isolated, synthetic or explicitly reviewed task files;\n- replace sample business names, personal references, URLs, and machine paths;\n- load credentials through the operator's secret-management mechanism;\n- verify TLS and retention policy for every remote endpoint; and\n- inspect all staged artifacts before adoption.\n\nThe bundled fixtures are examples only. Their scores and any old cost estimates\ndo not establish effectiveness, safety, or a stable nightly price for another\nOpenClaw deployment.\n\n## Further information\n\n- [OpenClaw README](README.md) — current reference status and adaptation checklist\n- [plugin integration reference](../README.md) — supported shared-engine CLI\n  surface and data boundary\n- [SkillOpt-Sleep documentation](../../docs/sleep/README.md) — concepts,\n  results, and limitations\n\nContributions that turn this reference into a portable integration should add\ntests and update all three documents together.\n","frontmatter":{"name":"skillopt-sleep","description":"Reference-only OpenClaw adaptation of SkillOpt-Sleep. Use it to study or port the contributed DeepSeek wrapper, not as a ready-to-run installation."},"isInternal":false,"tokens":1096,"sizeBytes":5133},{"name":"initial.md","path":"skillopt/envs/alfworld/skills/initial.md","rawUrl":"https://raw.githubusercontent.com/microsoft/SkillOpt/HEAD/skillopt/envs/alfworld/skills/initial.md","title":"Skills Skill","category":"anthropic-skill","format":"markdown","content":"# ALFWorld Embodied Agent Skill\n\n## Overview\nThis skill guides agents operating in the ALFWorld text-based embodied environment.\nThe agent must complete household tasks by navigating rooms, interacting with objects,\nand using appliances. Actions must be chosen from the admissible action list provided\nat each step.\n\n**Output format**: Always output `<think>...</think>` for reasoning, then `<action>...</action>` for the chosen action.\n\n---\n\n## Task Types\n\n| Type | Goal | Key Steps |\n|------|------|-----------|\n| Pick & Place | Put object X in/on receptacle Y | Find X -> take X -> go to Y -> put X in/on Y |\n| Pick Two & Place | Put two instances of X in/on Y | Find X1 -> take -> place -> find X2 -> take -> place |\n| Examine in Light | Examine object X under desklamp | Find X -> take X -> find desklamp -> use desklamp |\n| Clean & Place | Clean object X and put in/on Y | Find X -> take X -> go to sink -> clean X -> go to Y -> put X |\n| Heat & Place | Heat object X and put in/on Y | Find X -> take X -> go to microwave -> heat X -> go to Y -> put X |\n| Cool & Place | Cool object X and put in/on Y | Find X -> take X -> go to fridge -> cool X -> go to Y -> put X |\n\n---\n\n## General Principles\n\n1. **Decompose the task**: Parse the goal into ordered sub-goals (locate, acquire, transform, deliver). Complete each before moving to the next.\n2. **Systematic exploration**: Search each surface and container exactly once before revisiting. Open closed containers (drawers, cabinets, fridge) before judging them empty.\n3. **Grab immediately**: When a required object is visible and reachable, take it right away before moving elsewhere.\n4. **Transform before placing**: If the task requires cleaning, heating, or cooling, perform the state change at the appropriate appliance before heading to the final destination.\n5. **Direct delivery**: Once holding the transformed (or untransformed) goal object, navigate straight to the target receptacle and place it.\n6. **Track progress**: Maintain an internal count of how many objects still need to be found and placed. Only stop searching when the count reaches zero.\n7. **Avoid loops**: Never repeat the same action more than twice in a row. If stuck, move to a different unexplored location.\n8. **Only choose admissible actions**: Always pick an action from the admissible action list. Do not invent actions.\n\n---\n\n## Common Mistakes to Avoid\n\n- **Revisiting searched locations**: Keep track of which surfaces/containers have been checked; do not re-examine them.\n- **Ignoring visible objects**: If the target object appears in the observation, pick it up immediately.\n- **Skipping state changes**: Do not place an object at the destination without first cleaning/heating/cooling it when required.\n- **Premature termination**: Do not stop the episode until all goal conditions are verified as met.\n- **Action loops**: Repeatedly toggling or examining the same object wastes steps. Move on to new locations instead.\n","isInternal":false,"tokens":672,"sizeBytes":2966},{"name":"initial.md","path":"skillopt/envs/docvqa/skills/initial.md","rawUrl":"https://raw.githubusercontent.com/microsoft/SkillOpt/HEAD/skillopt/envs/docvqa/skills/initial.md","title":"Skills Skill","category":"anthropic-skill","format":"markdown","content":"# DocVQA Skill\n\n## Visual Evidence Discipline\n- Read the document carefully before answering.\n- Prefer the smallest exact text span that answers the question.\n- When several nearby strings look similar, choose the one whose surrounding labels or layout best match the question.\n\n## Exact Answer Discipline\n- Copy names, numbers, and dates exactly from the document whenever possible.\n- Prefer direct extraction over paraphrase.\n- Before finalizing, compare the answer against nearby alternatives and keep the best-supported exact span.\n","isInternal":false,"tokens":99,"sizeBytes":536},{"name":"initial.md","path":"skillopt/envs/livemathematicianbench/skills/initial.md","rawUrl":"https://raw.githubusercontent.com/microsoft/SkillOpt/HEAD/skillopt/envs/livemathematicianbench/skills/initial.md","title":"Skills Skill","category":"anthropic-skill","format":"markdown","content":"# Live Mathematical MCQ Heuristics\n\n## Option Comparison\n- Compare all options before committing. The correct choice is often the strongest statement justified by the question, while nearby distractors are weaker, overstrong, or miss an equality case.\n- Track exact quantifiers such as \"there exists\", \"for every\", \"if and only if\", and \"exactly when\".\n\n## Theorem-Level Precision\n- Check whether an option weakens the conclusion by dropping a characterization, equality clause, or full equivalence.\n- Check whether an option overstates the theorem by upgrading regularity, removing scale restrictions, or changing an existential statement into a universal one.\n\n## Hypotheses\n- Verify the hypotheses and domain carefully. Distractors often keep the theorem shape but alter the required assumptions.\n- Pay close attention to equality cases, extremal conditions, and whether a result applies to the full family or only a restricted subfamily.\n\n## Final Answer\n- Output the final answer as the single option label only.\n","isInternal":false,"tokens":202,"sizeBytes":1018},{"name":"initial.md","path":"skillopt/envs/officeqa/skills/initial.md","rawUrl":"https://raw.githubusercontent.com/microsoft/SkillOpt/HEAD/skillopt/envs/officeqa/skills/initial.md","title":"Skills Skill","category":"anthropic-skill","format":"markdown","content":"# OfficeQA Skill\n\n## Retrieval Discipline\n- Start by narrowing to the most likely candidate file before reading long passages.\n- Prefer targeted search terms that name the exact entity, period, measure, or table concept from the question.\n- After a promising match, read only a small surrounding span and verify it matches the requested year, basis, and unit.\n\n## Evidence Discipline\n- Extract the exact value from the retrieved text before doing any arithmetic.\n- Keep track of each operand's period, unit, and semantic role so nearby proxy values are not mixed in.\n- If the question asks for a transformed or derived quantity, compute only after confirming every operand.\n\n## Final Answer Discipline\n- Return the final answer only after one last consistency check against the retrieved evidence.\n- Copy the final answer from a checked value, not from an unverified intermediate guess.\n","isInternal":false,"tokens":171,"sizeBytes":887},{"name":"initial.md","path":"skillopt/envs/searchqa/skills/initial.md","rawUrl":"https://raw.githubusercontent.com/microsoft/SkillOpt/HEAD/skillopt/envs/searchqa/skills/initial.md","title":"Skills Skill","category":"anthropic-skill","format":"markdown","content":"# Question Answering Skill\n\n(No learned rules yet. Rules will be added through the reflection process.)\n","isInternal":false,"tokens":21,"sizeBytes":104},{"name":"initial.md","path":"skillopt/envs/spreadsheetbench/skills/initial.md","rawUrl":"https://raw.githubusercontent.com/microsoft/SkillOpt/HEAD/skillopt/envs/spreadsheetbench/skills/initial.md","title":"Skills Skill","category":"anthropic-skill","format":"markdown","content":"# Spreadsheet Manipulation Skill (xlsx)\n\n## Overview\nThis skill guides agents in manipulating Excel (.xlsx) spreadsheets using Python.\n\n**Primary libraries**: `openpyxl` (structure-preserving read/write), `pandas` (data transformation).\nNever use any other third-party libraries.\n\n---\n\n## Common Workflow\n\n1. **Explore** the input file: list sheets, inspect headers, check dimensions.\n2. **Write `solution.py`** with `INPUT_PATH` and `OUTPUT_PATH` defined at the top.\n3. **Execute** `python solution.py` and verify the output file was created.\n4. **Confirm** the target cells/range contain the expected values.\n\n---\n\n## Library Selection\n\n| Use case | Library |\n|----------|---------|\n| Preserve formulas, formatting, named ranges | `openpyxl` |\n| Bulk data transformation, aggregation, sorting | `pandas` → write back with `openpyxl` |\n| Simple cell read/write | `openpyxl` |\n\n**Warning**: `pandas.to_excel()` silently destroys existing formulas and named ranges.\nWhen writing back to a spreadsheet that contains formulas, always use `openpyxl.save()`.\n\n---\n\n## solution.py Template\n\n```python\nimport openpyxl\nimport pandas as pd\n\nINPUT_PATH  = \"...\"   # set to the actual input path\nOUTPUT_PATH = \"...\"   # set to the actual output path\n\nwb = openpyxl.load_workbook(INPUT_PATH)\nws = wb.active  # or wb[\"SheetName\"]\n\n# --- perform manipulation ---\n\nwb.save(OUTPUT_PATH)\n```\n\n---\n\n## Output Requirements\n\n- Save the result to `OUTPUT_PATH`.\n- Do not hardcode row counts or column letters — iterate over actual rows in the workbook.\n- Preserve sheets and cells not mentioned in the instruction.\n","isInternal":false,"tokens":369,"sizeBytes":1598},{"name":"marketplace.json","path":".cursor-plugin/marketplace.json","rawUrl":"https://raw.githubusercontent.com/microsoft/SkillOpt/HEAD/.cursor-plugin/marketplace.json","title":"skillopt","category":"marketplace","format":"json","content":"{\n  \"name\": \"skillopt\",\n  \"owner\": {\n    \"name\": \"Yifan Yang\",\n    \"email\": \"yifanyang@microsoft.com\"\n  },\n  \"metadata\": {\n    \"description\": \"Official SkillOpt plugins for usage-driven, validation-gated agent improvement.\"\n  },\n  \"plugins\": [\n    {\n      \"name\": \"skillopt-sleep\",\n      \"source\": \"plugins/cursor\",\n      \"description\": \"Review recent Cursor sessions, replay recurring work, and stage validation-gated improvements to a Cursor skill for explicit adoption.\"\n    }\n  ]\n}\n","frontmatter":{"name":"skillopt","owner":{"name":"Yifan Yang","email":"yifanyang@microsoft.com"},"metadata":{"description":"Official SkillOpt plugins for usage-driven, validation-gated agent improvement."},"plugins":[{"name":"skillopt-sleep","source":"plugins/cursor","description":"Review recent Cursor sessions, replay recurring work, and stage validation-gated improvements to a Cursor skill for explicit adoption."}]},"isInternal":false,"tokens":126,"sizeBytes":486},{"name":"marketplace.json","path":"plugins/claude-code/.claude-plugin/marketplace.json","rawUrl":"https://raw.githubusercontent.com/microsoft/SkillOpt/HEAD/plugins/claude-code/.claude-plugin/marketplace.json","title":"skillopt-sleep","category":"marketplace","format":"json","content":"{\n  \"$schema\": \"https://anthropic.com/claude-code/marketplace.schema.json\",\n  \"name\": \"skillopt-sleep\",\n  \"description\": \"SkillOpt-Sleep: give your local Claude agent a nightly sleep cycle that reviews past sessions and consolidates validated memory + skills.\",\n  \"owner\": {\n    \"name\": \"Yifan Yang\",\n    \"email\": \"yifanyang@microsoft.com\"\n  },\n  \"plugins\": [\n    {\n      \"name\": \"skillopt-sleep\",\n      \"description\": \"Nightly offline self-evolution: harvest your past Claude Code sessions, replay recurring tasks on your own API budget, and consolidate what the agent learns into validated CLAUDE.md memory and SKILL.md skills, behind a held-out gate, staged for your review. Synthesizes SkillOpt (validation-gated skill optimization), Claude Dreams (offline memory consolidation), and agent sleep/consolidation.\",\n      \"author\": {\n        \"name\": \"Yifan Yang\"\n      },\n      \"category\": \"productivity\",\n      \"source\": {\n        \"source\": \"git-subdir\",\n        \"url\": \"https://github.com/microsoft/SkillOpt.git\",\n        \"path\": \"plugins/claude-code\",\n        \"ref\": \"main\"\n      },\n      \"homepage\": \"https://github.com/microsoft/SkillOpt\"\n    }\n  ]\n}\n","frontmatter":{"$schema":"https://anthropic.com/claude-code/marketplace.schema.json","name":"skillopt-sleep","description":"SkillOpt-Sleep: give your local Claude agent a nightly sleep cycle that reviews past sessions and consolidates validated memory + skills.","owner":{"name":"Yifan Yang","email":"yifanyang@microsoft.com"},"plugins":[{"name":"skillopt-sleep","description":"Nightly offline self-evolution: harvest your past Claude Code sessions, replay recurring tasks on your own API budget, and consolidate what the agent learns into validated CLAUDE.md memory and SKILL.md skills, behind a held-out gate, staged for your review. Synthesizes SkillOpt (validation-gated skill optimization), Claude Dreams (offline memory consolidation), and agent sleep/consolidation.","author":{"name":"Yifan Yang"},"category":"productivity","source":{"source":"git-subdir","url":"https://github.com/microsoft/SkillOpt.git","path":"plugins/claude-code","ref":"main"},"homepage":"https://github.com/microsoft/SkillOpt"}]},"isInternal":false,"tokens":291,"sizeBytes":1157},{"name":"plugin.json","path":"plugins/claude-code/.claude-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/microsoft/SkillOpt/HEAD/plugins/claude-code/.claude-plugin/plugin.json","title":"skillopt-sleep","category":"plugin-manifest","format":"json","content":"{\n  \"name\": \"skillopt-sleep\",\n  \"description\": \"Give your local Claude agent a nightly 'sleep cycle': it reviews your past sessions offline, replays recurring tasks on your own API budget, and consolidates what it learns into validated memory (CLAUDE.md) and skills (SKILL.md) so it gets better the more you use it. Synthesizes SkillOpt (validation-gated skill optimization), Claude Dreams (offline memory consolidation), and agent sleep/consolidation.\",\n  \"version\": \"0.1.0\",\n  \"author\": {\n    \"name\": \"Yifan Yang\",\n    \"email\": \"yifanyang@microsoft.com\"\n  },\n  \"homepage\": \"https://github.com/microsoft/SkillOpt\",\n  \"repository\": \"https://github.com/microsoft/SkillOpt\",\n  \"license\": \"MIT\",\n  \"keywords\": [\n    \"skillopt\",\n    \"self-improvement\",\n    \"memory-consolidation\",\n    \"dreams\",\n    \"sleep\",\n    \"skills\",\n    \"continual-learning\",\n    \"offline-optimization\"\n  ]\n}\n","frontmatter":{"name":"skillopt-sleep","description":"Give your local Claude agent a nightly 'sleep cycle': it reviews your past sessions offline, replays recurring tasks on your own API budget, and consolidates what it learns into validated memory (CLAUDE.md) and skills (SKILL.md) so it gets better the more you use it. Synthesizes SkillOpt (validation-gated skill optimization), Claude Dreams (offline memory consolidation), and agent sleep/consolidation.","version":"0.1.0","author":{"name":"Yifan Yang","email":"yifanyang@microsoft.com"},"homepage":"https://github.com/microsoft/SkillOpt","repository":"https://github.com/microsoft/SkillOpt","license":"MIT","keywords":["skillopt","self-improvement","memory-consolidation","dreams","sleep","skills","continual-learning","offline-optimization"]},"isInternal":false,"tokens":236,"sizeBytes":877},{"name":"README.md","path":"plugins/claude-code/README.md","rawUrl":"https://raw.githubusercontent.com/microsoft/SkillOpt/HEAD/plugins/claude-code/README.md","title":"claude-code Documentation","category":"plugin-manifest","format":"markdown","content":"# SkillOpt-Sleep (Claude Code plugin)\n\n> Give your local Claude agent a **sleep cycle**. Every night it reviews your\n> past sessions offline, replays your recurring tasks on your own API budget,\n> and consolidates what it learns into **validated** memory (`CLAUDE.md`) and\n> skills (`SKILL.md`). Your agent gets better the more you use it — no\n> model-weight training.\n\nSkillOpt-Sleep is the **deployment-time** companion to\n[SkillOpt](https://github.com/microsoft/SkillOpt). SkillOpt trains a skill\noffline on a benchmark; SkillOpt-Sleep applies the same discipline to *your own\ndaily usage*: bounded text edits, accepted only through a held-out validation\ngate, with rejected candidates recorded in the cycle report for review.\n\nIt synthesizes three ideas:\n\n| Idea | Contribution |\n|---|---|\n| **SkillOpt** | skill/memory = trainable text; bounded add/delete/replace edits; **held-out gate** keeps only changes that help. |\n| **Claude Dreams** | offline consolidation over past sessions; input never mutated; output **reviewed then adopted**. |\n| **Agent sleep** | periodic offline replay turns short-term episodes into long-term skill. |\n\n## What it does (one \"night\")\n\n```\nharvest ~/.claude transcripts → mine recurring tasks → replay offline\n   → consolidate (reflect → bounded edit → GATE) → stage proposal → (you) adopt\n```\n\nNothing live is modified until **you** run `/skillopt-sleep adopt` (the Dreams \"review,\nthen adopt or discard\" contract). Every adopt backs up the prior file first.\n\n## Install\n\n**Requirements:** Python ≥ 3.10. A real CLI backend additionally requires its\ncorresponding `claude` or `codex` executable on `PATH` and authenticated.\n\n```bash\n# 1) get the code (the plugin ships inside the SkillOpt repo)\ngit clone https://github.com/microsoft/SkillOpt.git\ncd SkillOpt\n\n# 2) add the plugin to Claude Code as a local marketplace\n/plugin marketplace add ./plugins/claude-code\n/plugin install skillopt-sleep@skillopt-sleep\n\n# 3) verify\n/skillopt-sleep status\n```\n\nThe plugin's bundled runner (`scripts/sleep.sh`) auto-selects a Python ≥ 3.10\ninterpreter and calls the `skillopt_sleep` engine. A source checkout needs no\n`pip install`. If the marketplace cache does not contain a usable source tree,\nthe shared runner falls back first to a `skillopt-sleep` executable on `PATH`\n(including `uv tool`/`pipx` installs), then to an importable Python module. Use\n`uv tool install skillopt` or `pip install skillopt` for that fallback.\n\n> **Version note.** This page tracks `main`. PyPI 0.2.0 provides the base Sleep\n> CLI, but handoff mode, `--preferences`, multi-skill fan-out, and reviewed\n> subset adoption require a source checkout from `main` until the next release.\n\n## Quick start\n\n```bash\n# from inside any project you use with Claude Code:\n/skillopt-sleep dry-run     # preview what it would learn; no changes staged\n/skillopt-sleep run         # full cycle: stages a reviewed proposal (still no live edits)\n/skillopt-sleep status      # see history + the latest staged proposal\n/skillopt-sleep adopt --legacy       # apply the reviewed managed proposal\n# Fan-out nights instead use: adopt --skill NAME (repeatable) or --all-skills\n\n/skillopt-sleep-handoff run # same cycle, but THIS session answers the model calls\n                            # (no claude -p subprocess, no API key — subscription-friendly)\n```\n\nOr call the engine directly (Python ≥ 3.10):\n\n```bash\npython -m skillopt_sleep run --project \"$(pwd)\" --scope invoked --backend mock\npython -m skillopt_sleep run --project \"$(pwd)\" --backend claude   # real lift via Claude\npython -m skillopt_sleep run --project \"$(pwd)\" --backend codex    # real lift via Codex\n```\n\nDefault backend is **`mock`** — deterministic, no API spend — so you can try the\nplumbing for free. Switch to `--backend claude` or `--backend codex` for\nmodel-driven mining and optimization on your own budget; an accepted gain is\ntask- and model-dependent, not guaranteed.\n\n### Data boundary for real backends\n\nHarvesting `~/.claude` is local and read-only, and the `mock` backend makes no\nprovider calls. A real backend sends truncated transcript excerpts and derived\ntasks to the selected provider for mining, replay, judging, and reflection.\nOutbound prompts are not currently guaranteed to be secret-free. Review your\nsession data and provider policy before using a real backend on a sensitive\nproject; the [shared integration guide](../README.md#data-boundary) describes a\nreviewed task-file workflow.\n\n### Sessions you did not type\n\nHarvest keeps your prompts and drops machine-written transcripts. Three\nenvironment variables extend what counts as machine-written, for the sessions\nClaude Code gives no other tell:\n\n| Variable | Effect |\n|---|---|\n| `SKILLOPT_SLEEP_AGENT_MARKERS` | Comma-separated markers; a session whose **first** prompt contains one is dropped entire. |\n| `SKILLOPT_SLEEP_NEG_FEEDBACK` / `SKILLOPT_SLEEP_POS_FEEDBACK` | Extra comma-separated phrases, in any language, that count as you rejecting or approving the previous answer. |\n\nThe case they exist for is a local hook that summarises the previous session on\na timer. Its runs are single-turn, they are frequent enough to fill\n`--max-sessions` and starve the night of your real sessions, and in the desktop\napp they carry `entrypoint: \"claude-desktop\"` like interactive ones — so neither\n`entrypoint` nor a replay marker identifies them. Quote the hook's first line:\n\n```bash\nexport SKILLOPT_SLEEP_AGENT_MARKERS=\"Below is a conversation log from a coding session\"\n```\n\nA template you cannot quote is covered only after you opt in: a single-turn\nsession sharing its first 120 characters of prompt with three others in the same\nharvest window is dropped before the session cap is applied once\n`SKILLOPT_SLEEP_REPEAT_MIN_SESSIONS` is set (default `0`, off; `3` is the usual\nchoice). Recurrence is not proof of who wrote a prompt — three human requests\nagainst one long shared checklist look the same — so the default keeps every\nsession and `--max-sessions` still bounds how many transcripts are read. A\nsession with a follow-up user turn is never matched, and neither is a prompt\nshorter than the prefix — your own one-shot requests repeat entirely rather than\nsharing a long boilerplate header.\n\n`/skillopt-sleep harvest` and the progress line of a `run` / `dry-run` report\nwhat was dropped, so a thin night is explainable:\n`harvest done: sessions=120 (skipped: 297 repeated-template sessions, 2 past the session cap)`.\nFull reference: [the sleep guide](../../docs/sleep/README.md#harvest-filters-environment).\n\n### Handoff mode (session answers the model calls)\n\n`--backend handoff` runs the cycle without any model subprocess: the engine\nexecutes the deterministic stages and writes every model call it needs to\n`.skillopt-sleep-handoff/PROMPTS.md` + `pending.json` (exit code 3). You (or\nthe `/skillopt-sleep-handoff` command, which automates the loop with isolated\nfresh-context subagents) write each raw answer to `answers/<id>.md` and re-run\nthe same command; it resumes from the answers and either finishes or stages\nthe next batch. Typically 3–6 rounds per night.\n\n```bash\npython -m skillopt_sleep run --backend handoff --project \"$(pwd)\"\n# ... answer .skillopt-sleep-handoff/PROMPTS.md into answers/<id>.md ...\npython -m skillopt_sleep run --backend handoff --project \"$(pwd)\"   # resume\n```\n\nAnswer every prompt in a **fresh context** — a session that has already seen\nthe mined tasks and their references would contaminate the held-out gate.\nDetails: [the plugins README](../README.md#handoff-backend).\n\n## Does it actually improve? (real models, public benchmark)\n\nSkillOpt-Sleep is validated against [gbrain-evals](https://github.com/garrytan/gbrain-evals)'\npublic `skillopt-v1` suite — the same benchmark gbrain scores its own skill\noptimizer against. We take a deliberately **deficient** skill and run one sleep\nnight; held-out scoring is done by a local rule judge (no judge-API, no way to\ngrade its own homework).\n\n| Backend | Seed | Held-out before → after | Nights |\n|---|---|---|---|\n| **Claude (Haiku 4.5)** | brief-writer | **0.00 → 1.00** | 1 |\n| **Codex** | brief-writer | **0.00 → 1.00** | 2 |\n\nBoth took a brief-writer with no risks section / no confidence level and, within\n1–2 nights, proposed gated edits that lifted the held-out score to perfect —\ninto the protected `LEARNED` block, nothing else touched. The Codex 2-night\ntrace even shows the optimizer **diagnosing its own residual failure** and\nadding a meta-rule to fix it. See the recorded results and limitations in\n[`docs/sleep/RESULTS.md`](../../docs/sleep/RESULTS.md).\n\nReproduce:\n\n```bash\ngit clone https://github.com/garrytan/gbrain-evals /tmp/gbrain-evals\npython -m skillopt_sleep.experiments.run_gbrain --backend claude --model haiku \\\n  --seeds brief-writer --data-root /tmp/gbrain-evals/eval/data/skillopt-v1 \\\n  --nights 1 --limit-replay 3 --limit-holdout 3\npython -m skillopt_sleep.experiments.run_gbrain --backend codex \\\n  --seeds brief-writer --data-root /tmp/gbrain-evals/eval/data/skillopt-v1 \\\n  --nights 1 --limit-replay 3 --limit-holdout 3\n```\n\n## Deterministic proof (no API, no keys)\n\n```bash\npython -m skillopt_sleep.experiments.run_experiment --persona researcher --assert-improves\npython -m skillopt_sleep.experiments.run_experiment --persona programmer  --assert-improves\n```\n\nEach prints the held-out score rising from baseline toward 1.0 as the gate\naccepts the general rules your tasks need, and confirms the gate **rejects** an\ninjected harmful edit. Context for the measured experiments is in\n[`docs/sleep/RESULTS.md`](../../docs/sleep/RESULTS.md).\n\n## Schedule it nightly\n\n```bash\n/skillopt-sleep schedule --hour 3 --minute 17\n/skillopt-sleep unschedule\n```\n\nThe built-in scheduler creates a managed cron entry and logs under the project.\nThe scheduled run stages proposals unless `--auto-adopt` is explicitly selected.\n\n## Safety\n\n- **Read-only** harvest of `~/.claude`. `mock` replay has no side effects.\n- Proposals are **staged**, never auto-applied (unless you opt in with `--auto-adopt`).\n- Every adopt writes a backup under the staging dir's `backup/`.\n- `--max-sessions` and `--max-tasks` bound work. `max_tokens_per_night` in\n  `~/.skillopt-sleep/config.json` stops a night from starting new steps once its\n  token count reaches the budget; a started step finishes, so it is not a hard\n  cap, and there is no wall-clock budget.\n- Real backends share truncated session/task content with the selected provider;\n  do not assume outbound prompts have been fully redacted.\n\n## Status\n\nThe engine, deterministic experiment, Claude/Codex CLI backends, handoff mode,\nand staged adoption flow are implemented. Advanced experiment-harness flags are\nnot automatically available on the nightly CLI; see the\n[shared integration reference](../README.md#supported-cli-surface).\n","isInternal":false,"tokens":2680,"sizeBytes":10882},{"name":"README.md","path":"plugins/codex/README.md","rawUrl":"https://raw.githubusercontent.com/microsoft/SkillOpt/HEAD/plugins/codex/README.md","title":"codex Documentation","category":"plugin-manifest","format":"markdown","content":"# SkillOpt-Sleep — Codex integration\n\nGive your **Codex** agent a nightly **sleep cycle**: it reviews past sessions\noffline, replays your recurring tasks on your own Codex budget, and consolidates\nwhat it learns into validated memory + skills behind a held-out gate. Same engine\nas the Claude Code plugin (`skillopt_sleep`), wrapped for Codex.\n\n> **Verified on Codex:** on the public\n> [gbrain-evals](https://github.com/garrytan/gbrain-evals) `skillopt-v1`\n> benchmark, a deliberately deficient skill goes **0.00 → 1.00** on a held-out\n> set with the Codex backend (incl. the tool-use seed via a real tool loop).\n> See the recorded results and limitations in\n> [`docs/sleep/RESULTS.md`](../../docs/sleep/RESULTS.md).\n\n## What Codex supports (and what we use)\n\nCodex (`@openai/codex`) extends via **`AGENTS.md`** instructions, **skills** at\n`~/.agents/skills/<name>/SKILL.md`, and plugins that can distribute skills.\nCustom prompts are deprecated in Codex, so this integration is skill-first: the\ninstalled `skillopt-sleep` skill contains the launch commands and operating\nrules. The shared runner remains a plain shell entrypoint that the skill calls.\n\n## Install\n\nOn Linux/macOS:\n```bash\ngit clone https://github.com/microsoft/SkillOpt.git\ncd SkillOpt\nbash plugins/codex/install.sh          # installs the skill\nexport SKILLOPT_SLEEP_REPO=\"$(pwd)\"    # so the runner is found from anywhere\n```\n\nOn Windows (PowerShell):\n```powershell\ngit clone <repo-url> SkillOpt-Sleep\ncd SkillOpt-Sleep\npowershell -File plugins/codex/install.ps1\n[System.Environment]::SetEnvironmentVariable(\"SKILLOPT_SLEEP_REPO\", \"$(pwd)\", \"User\")\n```\n\nIf a previous install created `~/.codex/prompts/sleep.md`, the installer moves\nthat deprecated prompt aside with a `.skillopt-legacy*.bak` suffix.\n\nRequires Python ≥ 3.10 and the `codex` CLI on PATH.\n\n## Use\n\nMention `$skillopt-sleep` where Codex supports explicit skill mentions, or ask\nCodex in natural language:\n\n```text\nUse the skillopt-sleep skill to run status for this project.\nUse the skillopt-sleep skill to run a dry-run for this project.\nUse the skillopt-sleep skill to run the full cycle for this project with the Codex backend.\nUse the skillopt-sleep skill to inspect status, then adopt the reviewed managed\nproposal or an explicit pending skill subset.\n```\n\nOr call the engine directly:\n\n```bash\npython -m skillopt_sleep dry-run --project \"$(pwd)\" --source codex --backend mock\npython -m skillopt_sleep run --project \"$(pwd)\" --source codex --backend codex \\\n  --max-sessions 5 --max-tasks 3 --progress\npython -m skillopt_sleep run --project \"$(pwd)\" --source codex --backend codex \\\n  --target-skill-path .agents/skills/example/SKILL.md \\\n  --max-sessions 5 --max-tasks 3 --progress\n```\n\n`--source codex` reads Codex Desktop archived sessions from\n`~/.codex/archived_sessions`. Use `--codex-home /path/to/.codex` to point at a\ndifferent Codex home, or `--source auto` to try Codex archives first and fall\nback to Claude Code transcripts. Default backend is `mock` (no API spend).\n`--backend codex` uses your Codex budget for model-driven optimization; an\naccepted gain is task-dependent, not guaranteed. Bound live runs\nwith `--max-sessions` and `--max-tasks`; add `--progress` because Codex-backed\nmining, replay, and reflection can be slow and otherwise quiet. Use\n`--target-skill-path` to stage/adopt into a repo-scoped Codex skill such as\n`.agents/skills/<name>/SKILL.md`; target runs over-sample mined tasks and\nprefer tasks that match the target skill's path, headings, and content. The\nimplemented main-CLI flags work the same across the shared integrations, and\n`--preferences \"...\"` is available for house rules. Advanced keys such as\n`gate_mode`, `gate_no_regression`, `dream_rollouts`, and `recall_k` belong in the Sleep config; the\nnightly CLI does not expose `--gate`, `--rollouts-k`, token/time-budget, or\noptimizer/target-split flags. See the\n[shared CLI reference](../README.md#supported-cli-surface).\n\nFor privacy-sensitive projects, split the run into reviewable steps:\n\n```bash\npython -m skillopt_sleep harvest --project \"$(pwd)\" --source codex \\\n  --target-skill-path .agents/skills/example/SKILL.md \\\n  --max-sessions 5 --max-tasks 3 \\\n  --output reviewed-tasks.json\n\npython -m skillopt_sleep dry-run --project \"$(pwd)\" --backend codex \\\n  --tasks-file reviewed-tasks.json --progress --json\n```\n\nInspect/redact the JSON and set `\"reviewed\": true` before using a real backend.\n`--tasks-file` skips archive harvest/mining and replays only the reviewed JSON\ntasks; real backends refuse task files still marked `\"reviewed\": false`.\n\nThis review step matters even though the Codex transcript converter removes\nknown secret-shaped strings: pattern-based redaction is not a guarantee. A real\nbackend sends truncated transcript/task content to the selected provider, while\n`--backend mock` makes no provider calls.\n\n## Notes / status\n\n- Codex's `exec` runs shell, so the real-tool-loop replay (e.g. the\n  `tool_called: search` benchmark seed) works natively.\n- This integration no longer installs a `.codex/prompts` slash command. Skills\n  are the reusable Codex workflow surface; mention `skillopt-sleep` explicitly\n  or ask for a sleep/dream/offline self-improvement run and Codex can load the\n  skill.\n","isInternal":false,"tokens":1334,"sizeBytes":5262},{"name":"README.md","path":"plugins/copilot/README.md","rawUrl":"https://raw.githubusercontent.com/microsoft/SkillOpt/HEAD/plugins/copilot/README.md","title":"copilot Documentation","category":"plugin-manifest","format":"markdown","content":"# SkillOpt-Sleep — GitHub Copilot integration\n\nGive **Copilot** (CLI or VS Code) a nightly **sleep cycle** via a tiny **MCP\nserver** that exposes the `skillopt_sleep` engine as tools. MCP is GitHub's\nsupported way to extend Copilot, so this works across Copilot CLI, VS Code, and\nother MCP clients with the same server.\n\n## What's here\n\n| File | Purpose |\n|---|---|\n| `mcp_server.py` | stdlib-only MCP (stdio) server exposing `sleep_*` tools |\n| `mcp-config.example.json` | drop-in MCP server config |\n| `copilot-instructions.snippet.md` | paste into `.github/copilot-instructions.md` |\n\n## Install\n\nRequires Python ≥ 3.10. No third-party packages — the server is pure stdlib.\n\n1. **Register the MCP server.** Add the server to your Copilot MCP config\n   (Copilot CLI: `~/.copilot/mcp-config.json`; VS Code: your MCP settings).\n   Use `mcp-config.example.json` as a template — set `SKILLOPT_SLEEP_REPO` to\n   this repo's path:\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"skillopt-sleep\": {\n         \"command\": \"python3\",\n        \"args\": [\"/abs/path/SkillOpt/plugins/copilot/mcp_server.py\"],\n        \"env\": { \"SKILLOPT_SLEEP_REPO\": \"/abs/path/SkillOpt\" }\n       }\n     }\n   }\n   ```\n\n2. **(Optional) Tell Copilot about it.** Append\n   `copilot-instructions.snippet.md` to your repo's\n   `.github/copilot-instructions.md` so Copilot reaches for the tools when the\n   user asks to \"run the sleep cycle\".\n\n## Use\n\nAsk Copilot things like *\"run the sleep cycle\"*, *\"what did the last sleep\npropose?\"*, *\"adopt the staged sleep proposal\"*. The server exposes seven MCP\ntools: `sleep_status`, `sleep_dry_run`, `sleep_run`, `sleep_adopt`,\n`sleep_harvest`, `sleep_schedule`, and `sleep_unschedule`.\n\nEach tool takes optional `project`, `backend`\n(`mock`/`claude`/`codex`/`copilot`/`handoff`), and `scope` arguments. For\n`sleep_adopt`, first inspect `sleep_status`, then use the adoption controls that\nmatch the reviewed staging manifest:\n\n- `staging` — exact staging directory to adopt instead of the latest night\n- `skills` — array of skill names to adopt; each is passed as one repeated\n  `--skill` argument without shell interpolation\n- `all_skills` — adopt every staged per-skill proposal\n- `legacy` — adopt only the legacy managed `SKILL.md`/`CLAUDE.md` pair\n\nChoose one selection mode (`skills`, `all_skills`, or `legacy`) and do not\ncombine them. A bare `sleep_adopt` remains compatible with legacy-only staging;\nfan-out staging requires an explicit selection.\n\nTool results preserve the engine's `exit_code` in `structuredContent`.\nOrdinary nonzero exits set `isError: true`; exit 3 is the expected\n`handoff_pending` state and is not an MCP tool error. With `json: true`, text\ncontent is the engine's parseable JSON stdout, while diagnostics remain\nseparate in `structuredContent`.\n\nDefault backend is `mock` (no API spend). The `copilot` backend drives the\nGitHub Copilot CLI (`copilot -p ... --output-format json`) and requires the\n`copilot` CLI to be installed and authenticated.\n\nHarvesting is local and read-only, and the default `mock` backend makes no\nprovider calls. A real backend sends truncated transcript excerpts and derived\ntasks to the selected provider. Outbound prompts are not currently guaranteed\nto be secret-free; review sensitive data and provider policy first. See the\n[shared data-boundary guidance](../README.md#data-boundary).\n\nFor speed, the `copilot` backend runs each call against an isolated\n`COPILOT_HOME` with built-in MCP servers and custom instructions disabled, so\nyour user MCP servers (including this project's own) are not spawned per call\n(~5x faster). Override with `SKILLOPT_SLEEP_COPILOT_HOME=<dir>`, pick a model\nwith `SKILLOPT_SLEEP_COPILOT_MODEL`, or set `SKILLOPT_SLEEP_COPILOT_FULL_ENV=1`\nto use your real Copilot environment instead.\n\n## Verify the server directly (no Copilot needed)\n\n```bash\nprintf '%s\\n' \\\n  '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{}}' \\\n  '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\"}' \\\n  | SKILLOPT_SLEEP_REPO=\"$(pwd)\" python3 plugins/copilot/mcp_server.py\n```\nYou should see the server info and all seven `sleep_*` tools.\n\n## Notes / status\n\n- MCP is the stable, official Copilot extension surface, so this is the most\n  portable shared-engine integration (one server → CLI + IDE).\n- The MCP schema exposes the main CLI's implemented controls, including task and\n  session caps, target-skill selection, scheduling, and staged adoption. It does\n  not add experiment-only gate, rollout, token/time-budget, or optimizer/target\n  split flags. See the [shared CLI reference](../README.md#supported-cli-surface).\n","isInternal":false,"tokens":1180,"sizeBytes":4617},{"name":"README.md","path":"plugins/copilot/skillopt/README.md","rawUrl":"https://raw.githubusercontent.com/microsoft/SkillOpt/HEAD/plugins/copilot/skillopt/README.md","title":"skillopt Documentation","category":"plugin-manifest","format":"markdown","content":"# SkillOpt — GitHub Copilot integration\r\n\r\nGive **Copilot** (CLI or VS Code) direct access to the **SkillOpt** research\r\nengine via a tiny **MCP server**. MCP is GitHub's supported way to extend\r\nCopilot, so this works across Copilot CLI, VS Code, and other MCP clients with\r\nthe same server.\r\n\r\nSkillOpt is **validation-gated, text-space skill optimization**: it reflects on\r\nrollouts, makes bounded edits to a skill, and keeps a change only if it improves\r\na held-out validation set. This plugin exposes the repo's training and eval\r\nentry points (`scripts/train.py`, `scripts/eval_only.py`) as Copilot tools.\r\n\r\n> This is the companion to the **SkillOpt-Sleep** plugin (`../mcp_server.py`,\r\n> `sleep_*` tools). Sleep evolves a *local coding agent* from your past\r\n> sessions; this server drives the *research* training/eval loops on the\r\n> benchmark configs in [`../../../configs`](../../../configs).\r\n\r\n## What's here\r\n\r\n| File | Purpose |\r\n|---|---|\r\n| `mcp_server.py` | stdlib-only MCP (stdio) server exposing `skillopt_*` tools |\r\n| `mcp-config.example.json` | drop-in MCP server config |\r\n| `copilot-instructions.snippet.md` | paste into `.github/copilot-instructions.md` |\r\n\r\n## Install\r\n\r\nRequires Python ≥ 3.10. The MCP server itself is pure stdlib, but the tools it\r\nlaunches need SkillOpt's runtime deps — install the package first:\r\n\r\n```bash\r\npip install -e .   # or: pip install -r requirements.txt\r\n```\r\n\r\n1. **Register the MCP server.** Add the server to your Copilot MCP config\r\n   (Copilot CLI: `~/.copilot/mcp-config.json`; VS Code: your MCP settings).\r\n   Use `mcp-config.example.json` as a template — set `SKILLOPT_REPO` to this\r\n   repo's path:\r\n\r\n   ```json\r\n   {\r\n     \"mcpServers\": {\r\n       \"skillopt\": {\r\n         \"command\": \"python3\",\r\n         \"args\": [\"/abs/path/SkillOpt/plugins/copilot/skillopt/mcp_server.py\"],\r\n         \"env\": { \"SKILLOPT_REPO\": \"/abs/path/SkillOpt\" }\r\n       }\r\n     }\r\n   }\r\n   ```\r\n\r\n2. **(Optional) Tell Copilot about it.** Append\r\n   `copilot-instructions.snippet.md` to your repo's\r\n   `.github/copilot-instructions.md` so Copilot reaches for the tools when the\r\n   user asks to \"optimize a skill\" or \"train on a benchmark\".\r\n\r\n## Use\r\n\r\nAsk Copilot things like *\"what configs can I run?\"*, *\"optimize the searchqa\r\nskill\"*, or *\"evaluate this skill on the dataset\"*. Copilot calls the MCP tools:\r\n`skillopt_list_configs`, `skillopt_train`, `skillopt_eval`.\r\n\r\n| Tool | Required args | Notes |\r\n|---|---|---|\r\n| `skillopt_list_configs` | — | Lists `configs/**/*.yaml` you can pass as `config`. |\r\n| `skillopt_train` | `config` | Runs a reflective optimization loop. Long-running; spends budget. |\r\n| `skillopt_eval` | `config`, `skill` | Evaluates one skill markdown file; no training. |\r\n\r\nCommon optional args (both train and eval): `env`, `backend`,\n`optimizer_model`, `target_model`, `out_root`, `cfg_options` (space-separated\n`section.key=value` YAML overrides), and `extra_args` (raw passthrough flags\nfor the underlying script). `skillopt_train` also accepts `num_epochs`,\n`batch_size`, `seed`, and `use_gate`. `use_gate` defaults to `true`; setting it\nto `false` still records validation scores but force-accepts every candidate,\nwhich changes the optimization semantics.\n\nThe MCP schema's `backend` argument follows the underlying script's\n`--backend` choices. Role-specific and generic OpenAI-compatible backends can\nbe selected through config or `extra_args` (for example,\n`--optimizer_backend openai_compatible --target_backend openai_compatible`);\nsee the repository's [backend guide](../../../docs/guide/new-backend.md) for\nthe required environment variables.\n\r\nRuns can be very long. The server's subprocess timeout defaults to 6 hours;\r\noverride it with the `SKILLOPT_RUN_TIMEOUT` environment variable (seconds).\r\n\r\n## Verify the server directly (no Copilot needed)\r\n\r\n```bash\r\nprintf '%s\\n' \\\r\n  '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{}}' \\\r\n  '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\"}' \\\r\n  '{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"skillopt_list_configs\",\"arguments\":{}}}' \\\r\n  | SKILLOPT_REPO=\"$(pwd)\" python3 plugins/copilot/skillopt/mcp_server.py\r\n```\r\n\r\nYou should see the server info, the three `skillopt_*` tools, and the list of\r\nbenchmark configs.\r\n\r\n## Notes / status\r\n\r\n- MCP is the stable, official Copilot extension surface, so this is portable\r\n  across Copilot CLI and IDE from one server.\r\n- `skillopt_list_configs` is filesystem-only and safe to call anytime;\r\n  `skillopt_train` / `skillopt_eval` shell out to the repo scripts and require\r\n  the SkillOpt runtime deps (and, for real backends, model credentials — see\r\n  [`../../../.env.example`](../../../.env.example)).\r\n","isInternal":false,"tokens":1209,"sizeBytes":4726},{"name":"plugin.json","path":"plugins/cursor/.cursor-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/microsoft/SkillOpt/HEAD/plugins/cursor/.cursor-plugin/plugin.json","title":"skillopt-sleep","category":"plugin-manifest","format":"json","content":"{\n  \"name\": \"skillopt-sleep\",\n  \"displayName\": \"SkillOpt-Sleep\",\n  \"version\": \"0.1.0\",\n  \"description\": \"Review recent Cursor sessions, replay recurring work, and stage validation-gated improvements to a Cursor skill for explicit adoption.\",\n  \"author\": {\n    \"name\": \"Yifan Yang\",\n    \"email\": \"yifanyang@microsoft.com\"\n  },\n  \"homepage\": \"https://github.com/microsoft/SkillOpt\",\n  \"repository\": \"https://github.com/microsoft/SkillOpt\",\n  \"license\": \"MIT\",\n  \"keywords\": [\n    \"skillopt\",\n    \"cursor\",\n    \"self-improvement\",\n    \"memory-consolidation\",\n    \"sleep\",\n    \"skills\",\n    \"offline-optimization\"\n  ],\n  \"category\": \"developer-tools\",\n  \"tags\": [\n    \"automation\",\n    \"memory\",\n    \"transcripts\"\n  ],\n  \"commands\": \"./commands/\",\n  \"skills\": \"./skills/\"\n}\n","frontmatter":{"name":"skillopt-sleep","displayName":"SkillOpt-Sleep","version":"0.1.0","description":"Review recent Cursor sessions, replay recurring work, and stage validation-gated improvements to a Cursor skill for explicit adoption.","author":{"name":"Yifan Yang","email":"yifanyang@microsoft.com"},"homepage":"https://github.com/microsoft/SkillOpt","repository":"https://github.com/microsoft/SkillOpt","license":"MIT","keywords":["skillopt","cursor","self-improvement","memory-consolidation","sleep","skills","offline-optimization"],"category":"developer-tools","tags":["automation","memory","transcripts"],"commands":"./commands/","skills":"./skills/"},"isInternal":false,"tokens":217,"sizeBytes":770},{"name":"README.md","path":"plugins/cursor/README.md","rawUrl":"https://raw.githubusercontent.com/microsoft/SkillOpt/HEAD/plugins/cursor/README.md","title":"cursor Documentation","category":"plugin-manifest","format":"markdown","content":"# SkillOpt-Sleep - Cursor integration\n\nGive Cursor an on-demand or explicitly scheduled sleep cycle: review recent\nlocal Cursor sessions, replay recurring tasks through a selected backend, and\nstage validation-gated improvements to a project Cursor skill. Nothing runs at\nsession end, and nothing live changes until the user adopts an accepted staged\nproposal (unless they explicitly request `--auto-adopt`).\n\nThis package is a native Cursor plugin containing a command and an agent skill.\nIt does not install hooks or an MCP server.\n\n## Requirements\n\n- Cursor with plugin and agent-skill support.\n- Python 3.10 or newer.\n- Either a SkillOpt source checkout or an installed `skillopt-sleep` command.\n- For `--backend cursor`, an installed and authenticated Cursor Agent CLI\n  (`cursor-agent`). The default `mock` backend needs no provider login or spend.\n\nThe plugin and transcript harvester work on native Windows. Cursor documents\nthe Agent CLI for Windows through WSL; run provider-backed `--backend cursor`\ninside WSL unless a native `cursor-agent` is available in your environment.\n\n## Install the local plugin\n\nClone the repository, then run the installer for your platform.\n\nmacOS or Linux:\n\n```bash\ngit clone https://github.com/microsoft/SkillOpt.git\ncd SkillOpt\nbash plugins/cursor/install.sh\nexport SKILLOPT_SLEEP_REPO=\"$(pwd)\"\n```\n\nWindows PowerShell:\n\n```powershell\ngit clone https://github.com/microsoft/SkillOpt.git\nSet-Location SkillOpt\npowershell -File plugins/cursor/install.ps1\n[System.Environment]::SetEnvironmentVariable(\"SKILLOPT_SLEEP_REPO\", \"$(pwd)\", \"User\")\n```\n\nThe installer copies the plugin to\n`~/.cursor/plugins/local/skillopt-sleep` (or\n`%USERPROFILE%\\.cursor\\plugins\\local\\skillopt-sleep`). Quit and reopen Cursor\nafter changing user environment variables, then confirm that **SkillOpt-Sleep**\nappears in Settings > Plugins under Installed.\n\nThe plugin and engine have separate installation boundaries. The copied plugin\nteaches Cursor how to operate SkillOpt-Sleep; the engine still runs from the\nsource checkout through `plugins/run-sleep.sh` / `plugins/run-sleep.ps1`, or\nfrom an installed command:\n\n```bash\nuv tool install skillopt\n# or: python -m pip install skillopt\n```\n\nUse a release that includes Cursor source/backend support when choosing the\ninstalled-command route. The source-checkout route uses the implementation in\nthe checkout directly.\n\n## Use from Cursor\n\nRun the native command, for example:\n\n```text\n/skillopt-sleep status\n/skillopt-sleep dry-run --backend mock --max-sessions 5 --max-tasks 3\n/skillopt-sleep run --backend cursor --max-sessions 5 --max-tasks 3 --progress\n/skillopt-sleep adopt --legacy\n```\n\nFor fan-out proposals, inspect `status` and use repeatable `--skill NAME` or\n`--all-skills`. Bare adopt deliberately refuses a night containing fan-out rows.\n\nThe `skillopt-sleep` agent skill remains independently available if a Cursor\nversion does not surface plugin commands.\n\nThe native command's default Cursor-visible target is:\n\n```text\n.cursor/skills/skillopt-sleep-learned/SKILL.md\n```\n\nUse `--target-skill-path` with that value on harvest, dry-run, and run commands.\nWithout an explicit target, the shared engine defaults to a Claude-managed\nskill, which Cursor does not load as a project skill.\n\n### Source-checkout commands\n\nmacOS or Linux:\n\n```bash\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" status --project \"$(pwd)\"\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" dry-run \\\n  --project \"$(pwd)\" --source cursor --backend mock \\\n  --target-skill-path .cursor/skills/skillopt-sleep-learned/SKILL.md\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" run \\\n  --project \"$(pwd)\" --source cursor --backend cursor \\\n  --target-skill-path .cursor/skills/skillopt-sleep-learned/SKILL.md \\\n  --max-sessions 5 --max-tasks 3 --progress\n```\n\nWindows PowerShell:\n\n```powershell\npowershell -File \"$env:SKILLOPT_SLEEP_REPO\\plugins\\run-sleep.ps1\" status --project \"$(pwd)\"\npowershell -File \"$env:SKILLOPT_SLEEP_REPO\\plugins\\run-sleep.ps1\" dry-run `\n  --project \"$(pwd)\" --source cursor --backend mock `\n  --target-skill-path .cursor/skills/skillopt-sleep-learned/SKILL.md\npowershell -File \"$env:SKILLOPT_SLEEP_REPO\\plugins\\run-sleep.ps1\" run `\n  --project \"$(pwd)\" --source cursor --backend cursor `\n  --target-skill-path .cursor/skills/skillopt-sleep-learned/SKILL.md `\n  --max-sessions 5 --max-tasks 3 --progress\n```\n\n### Installed-command equivalents\n\n```bash\nskillopt-sleep status --project \"$(pwd)\"\nskillopt-sleep dry-run --project \"$(pwd)\" --source cursor --backend mock \\\n  --target-skill-path .cursor/skills/skillopt-sleep-learned/SKILL.md\nskillopt-sleep run --project \"$(pwd)\" --source cursor --backend cursor \\\n  --target-skill-path .cursor/skills/skillopt-sleep-learned/SKILL.md \\\n  --max-sessions 5 --max-tasks 3 --progress\nskillopt-sleep status --project \"$(pwd)\"\nskillopt-sleep adopt --project \"$(pwd)\" --legacy\n```\n\n`--source cursor` reads local JSONL transcripts below\n`~/.cursor/projects/<workspace>/agent-transcripts/`. Use\n`--cursor-home /path/to/.cursor` for a different Cursor home. Invoked scope\nselects the current workspace; `--scope all` includes every Cursor workspace.\nThe source converter retains user/assistant text, tool names, and explicit turn\nerrors, but excludes raw tool arguments and outputs.\n\nThe first harvest uses a 72-hour lookback by default. Use\n`--lookback-hours N` to choose a wider initial window, or\n`--lookback-hours 0` to consider all available history while still respecting\n`--max-sessions`. A successful `run`, including one that mines no tasks,\nrecords a new harvest checkpoint. Later runs use that checkpoint instead of\nthe initial lookback. Use `harvest` or `dry-run` to inspect session and task\ncounts before the first stateful run; neither action advances the checkpoint.\n\n`--backend cursor` invokes the authenticated Cursor Agent CLI. Use\n`--cursor-path /path/to/cursor-agent` or `SKILLOPT_SLEEP_CURSOR_PATH` if it is\nnot on PATH, and `--model` or `SKILLOPT_SLEEP_CURSOR_MODEL` to override its\nmodel. Check available identifiers with `cursor-agent --list-models` and verify\nthe billed variant in Cursor's usage reporting when cost matters. The child\nprocess receives only an explicit runtime/authentication/locale/proxy/CA\nenvironment allowlist; unrelated cloud and model-provider credentials are not\nforwarded.\n\n## What Cursor replay evaluates\n\nSkillOpt reads the target skill and inserts its text into mined task prompts. It\ndoes not invoke that file as a native Cursor skill or execute commands described\nby the skill. All ordinary Cursor model calls, including mining, replay,\njudging, and reflection, run in a new empty temporary workspace in read-only Ask\nmode. File reads, file writes, and MCP tools are denied. `--project` selects the\ntranscript scope, target files, state, and staging location; it does not make the\nproject the Cursor Agent execution workspace.\n\nCursor tool-aware replay is temporarily disabled pending live Cursor\npermission-boundary validation. Tasks containing a `tool_called` check fail\nnonzero before Agent mode starts. The failed replay does not add a cache entry,\nstage, adopt, persist state, or advance the harvest checkpoint. Use another\nbackend for those tasks.\n\nThis replay is useful for textual procedures, response conventions, and output\nformats. It is not an end-to-end evaluation of skills that depend on repository\ninspection, real CLIs, browsers, running services, or filesystem changes. There\nis currently no Cursor option that enables a fresh project worktree or real\nproject tools. The `replay: mock` report label refers to the prompt-replay mode,\nnot to the selected model backend.\n\nThe shared engine also supports `mock`, `claude`, `codex`, `copilot`,\n`handoff`, and `azure_openai` backends. Cursor is the native model-driven\nchoice for this integration; `mock` remains the no-provider default.\n\n## Review sensitive data before provider calls\n\nHarvesting is local and read-only, and `--backend mock` makes no provider calls.\nKnown secret-shaped strings are redacted from harvested Cursor content, and raw\ntool payloads are excluded, but pattern-based redaction is not a guarantee.\nA real backend sends truncated transcript excerpts and derived tasks to that\nbackend's provider for mining, replay, judging, and reflection.\n\nBoth `run` and `dry-run` perform those real-backend calls; `dry-run` prevents\nstaging but does not prevent provider spend. `--max-sessions` and `--max-tasks`\nbound harvested work, not provider calls, tokens, elapsed time, or money. One\ntask can require several attempt, judge, and reflection calls. Start with small\nlimits and review the provider's usage reporting before increasing them.\n\nFor sensitive work, split the flow at the review boundary:\n\n```bash\nskillopt-sleep harvest --project \"$(pwd)\" --source cursor \\\n  --target-skill-path .cursor/skills/skillopt-sleep-learned/SKILL.md \\\n  --max-sessions 5 --max-tasks 3 --output reviewed-tasks.json\n\nskillopt-sleep dry-run --project \"$(pwd)\" --backend cursor \\\n  --tasks-file reviewed-tasks.json --progress --json\n```\n\nInspect and redact the JSON, then set its top-level `\"reviewed\"` field to\n`true`. Real backends reject task files that remain unreviewed. Keep raw\ntranscripts, credentials, and task files out of commits.\n\n## Scheduling\n\nRuns remain user-triggered unless the user explicitly schedules them. Before\nscheduling, put the Cursor source and target in\n`~/.skillopt-sleep/config.json`, because the scheduler persists the project,\nbackend, time, and optional auto-adopt flag, but not command-line source or\ntarget overrides:\n\n```json\n{\n  \"transcript_source\": \"cursor\",\n  \"target_skill_path\": \".cursor/skills/skillopt-sleep-learned/SKILL.md\",\n  \"cursor_home\": \"/absolute/path/to/.cursor\",\n  \"backend\": \"cursor\"\n}\n```\n\nThen schedule or remove the managed entry:\n\n```bash\nskillopt-sleep schedule --project \"$(pwd)\" --backend cursor --hour 3 --minute 17\nskillopt-sleep unschedule --project \"$(pwd)\"\n```\n\nOn Unix this uses cron; on Windows it uses Task Scheduler. Scheduled runs stage\nproposals for later review by default. Do not add `--auto-adopt` unless the user\nhas explicitly chosen unattended adoption.\n\n## Adoption and memory\n\n`run` stages accepted proposals under\n`<project>/.skillopt-sleep/staging/<timestamp>/`. Read the staged `report.md`\nand show the held-out baseline-to-candidate score plus exact edits before\nrunning `adopt`. Adoption backs up an existing target before replacing it.\n\nThe shared engine may also propose project `CLAUDE.md` memory updates; existing\nmemory behavior is unchanged. To restrict a Cursor setup to the explicit Cursor\nskill, set `\"evolve_memory\": false` in `~/.skillopt-sleep/config.json`.\n\nThere is deliberately no session-end hook or automatic plugin execution.\n","isInternal":false,"tokens":2561,"sizeBytes":10756},{"name":"README.md","path":"plugins/devin/README.md","rawUrl":"https://raw.githubusercontent.com/microsoft/SkillOpt/HEAD/plugins/devin/README.md","title":"devin Documentation","category":"plugin-manifest","format":"markdown","content":"# SkillOpt-Sleep — Devin integration\n\nGive **Devin** (Cognition) a nightly **sleep cycle** via a tiny **MCP server**\nthat exposes the `skillopt_sleep` engine as tools. MCP is Devin's supported way\nto add custom tooling, so this works in Devin's CLI and IDE.\n\nDevin doesn't write transcripts in the format the engine consumes, so this\nplugin adds a **Devin-specific harvester** that converts every locally available\nsource into the Claude Code-compatible JSONL the engine reads.\n\n## What's here\n\n| File | Purpose |\n|---|---|\n| `mcp_server.py` | stdlib-only MCP (stdio) server exposing `sleep_*` tools |\n| `harvest_devin.py` | converts Devin ATIF-v1.7 transcripts + agentmemory + `.devin/skills` into JSONL, with `taskKey` + outcome envelopes |\n| `judge.py` | reference judge for the deferred/judge branch of the validation gate |\n| `mcp-config.example.json` | drop-in MCP server config |\n| `install.sh` | copies hooks + rules into a project's `.devin/` and prints the MCP registration command |\n| `devin-rules.snippet.md` | copied to `.devin/rules/skillopt-sleep.md` by `install.sh` |\n| `hooks/hooks.v1.json` | SessionEnd hook config — installed/merged at `.devin/hooks.v1.json` by `install.sh` |\n| `hooks/on-session-end.sh` | best-effort activity marker script (called by the hook) |\n\n## What it harvests\n\n| Source | Where |\n|---|---|\n| Devin transcripts (ATIF-v1.7) | `~/.local/share/devin/cli/transcripts/*.json` |\n| agentmemory | `~/.agentmemory/standalone.json` |\n| Skill files | `.devin/skills/*/SKILL.md` |\n\nWorkspaces are auto-detected from `~/.config/Devin/User/workspaceStorage/*/workspace.json`.\nThe adapter performs no post-adoption copy. The core engine applies a reviewed\nproposal directly to its selected target and owns backup/rollback behavior.\n\n## Install\n\nRequires Python ≥ 3.10. No third-party packages — the server is pure stdlib.\n\n1. **Install hooks + rules into your project.** From the repo root:\n\n   ```bash\n   bash plugins/devin/install.sh /path/to/your/project\n   ```\n\n   This copies the SessionEnd hook and rules snippet into the project's\n   `.devin/` directory and prints the MCP registration command. The hook is\n   on by default — it logs a cheap activity marker for local inspection or\n   external automation when each session ends. The current engine harvests by\n   transcript timestamps and does not consume this marker directly. The hook\n   is non-blocking and spends no API budget. Re-run the script to update; the\n   installer preserves existing hooks and does not duplicate its own entry.\n\n2. **Register the MCP server.** Use `mcp-config.example.json` as a template, or\n   run the command printed by `install.sh`:\n\n   ```bash\n   devin mcp add skillopt-sleep \\\n     --env \"SKILLOPT_DEVIN_CLAUDE_HOME=$HOME/.skillopt-sleep-devin\" \\\n     -- python3 /abs/path/to/SkillOpt/plugins/devin/mcp_server.py\n   ```\n\n3. Ask Devin: *\"run the sleep cycle\"*, *\"what did the last sleep propose?\"*, *\"adopt it\"*.\n\n## Tools\n\n| Tool | What it does |\n|---|---|\n| `sleep_status` | nights run so far + latest staged proposal |\n| `sleep_dry_run` | preview cycle — no staging; a real backend still makes provider calls |\n| `sleep_run` | full cycle; stages a proposal for review |\n| `sleep_adopt` | apply a reviewed legacy or per-skill proposal (with backup) |\n| `sleep_harvest` | debug: list the recurring tasks mined |\n| `sleep_schedule` | install a nightly cron entry (`--hour` / `--minute`) |\n| `sleep_unschedule` | remove the nightly cron entry |\n\nBefore `sleep_adopt`, inspect `sleep_status` and use the controls that match the\nreviewed staging manifest:\n\n- `staging` — exact staging directory to adopt instead of the latest night\n- `skills` — array of skill names to adopt; each is forwarded as one repeated\n  `--skill` argument without shell interpolation\n- `all_skills` — adopt every staged per-skill proposal\n- `legacy` — adopt only the legacy managed `SKILL.md`/`CLAUDE.md` pair\n\nChoose one selection mode (`skills`, `all_skills`, or `legacy`) and do not\ncombine them. A bare call remains compatible with legacy-only staging; fan-out\nstaging requires an explicit selection. To operate on a specific Devin skill,\npass its `SKILL.md` as `target_skill_path`; the adapter never performs a second\ncopy after the core engine returns.\n\nTool results preserve the engine's `exit_code` in `structuredContent`.\nOrdinary nonzero exits set `isError: true`; exit 3 is the expected\n`handoff_pending` state and is not an MCP tool error. With `json: true`, text\ncontent is the engine's parseable JSON stdout, while harvest and engine\ndiagnostics remain separate in `structuredContent`.\n\nDefault backend is `mock` (no API spend); the `claude`, `codex`, and `copilot`\nbackends use the corresponding authenticated CLI and budget. The `handoff`\nbackend runs the cycle with no model subprocess or API key — the engine writes\npending model calls to `.skillopt-sleep-handoff/PROMPTS.md` + `pending.json`\n(exit code 3) and resumes after answers are placed in `answers/<id>.md`; re-run\n`sleep_run` with the same arguments to resume. The seven tools call the same\n`python -m skillopt_sleep` actions as the other shared-engine integrations.\n\n## Data boundary\n\nThe Devin harvester reads local ATIF transcripts, agentmemory, and skill files\nand converts them into the engine's session format. The `mock` backend keeps\nthat workflow local. A real backend sends truncated excerpts and derived tasks\nto the selected provider for mining, replay, judging, and reflection. The\nconversion step is not a guarantee that outbound prompts contain no secrets;\nreview sensitive sources and provider policy before enabling a real backend.\nSee the [shared data-boundary guidance](../README.md#data-boundary) and\n[implemented CLI reference](../README.md#supported-cli-surface).\n","isInternal":false,"tokens":1416,"sizeBytes":5777},{"name":"README.md","path":"plugins/dsh/README.md","rawUrl":"https://raw.githubusercontent.com/microsoft/SkillOpt/HEAD/plugins/dsh/README.md","title":"dsh Documentation","category":"plugin-manifest","format":"markdown","content":"# SkillOpt-Sleep — DeepSeek Harness (dsh) integration\n\nGive your **DeepSeek Harness** agent a nightly **sleep cycle**: it reviews past\nsessions offline, replays your recurring tasks on your own API budget, and\nconsolidates what it learns into validated skills behind a held-out gate. Same\nengine as the Claude Code / Codex / Cursor integrations\n([skillopt_sleep](https://github.com/microsoft/SkillOpt)), wired into dsh's\nplugin system as native tools plus a bundled skill.\n\nDeepSeek Harness is the \"everything is a plugin\" agent framework\n([deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness)).\nPlugins are TypeScript modules exporting an `apply(ctx)` function that register\ncapabilities (tools, services, events, settings) on the Cordis context.\n\n## Why a sleep cycle?\n\nSkills improve when an agent re-examines its own sessions — not just when you\nhand-tune a prompt. The sleep cycle turns your everyday usage into a nightly,\nvalidation-gated skill-improvement loop: harvest what you actually did, replay\nthe recurring tasks on your own API budget, and keep only the changes that pass\na held-out gate. It's the same engine as the Claude Code / Codex / Cursor\nintegrations, wired into dsh as native tools plus a bundled skill.\n\n## What this integration adds\n\n| Component | Purpose |\n|---|---|\n| `src/index.js` | dsh plugin entry: registers 7 `skillopt_*` tools + Schemastery config |\n| `cordis.patch.yml` | bundle patch layer — drop `dsh-skillopt` into any profile's bundles |\n| `skills/skillopt-sleep/SKILL.md` | agent skill: when to use the tools, operating rules, data-boundary rules |\n| `scripts/sleep.py` | bootstrap/self-check runner (same command shape the tools use) |\n| `package.json` | npm package metadata (bundle manifest) |\n\n## Tools\n\n| Tool | skillopt_sleep action | Behavior |\n|---|---|---|\n| `skillopt_status` | `status` | state, engine availability, latest staged proposal & report |\n| `skillopt_dry_run` | `dry-run` | full preview (harvest+mine+replay), stages nothing |\n| `skillopt_run` | `run` | full cycle, stages a proposal (live files unchanged) |\n| `skillopt_adopt` | `adopt` | apply latest staged proposal (with backup) — the live-change boundary |\n| `skillopt_harvest` | `harvest` | read-only show/export of mined tasks |\n| `skillopt_schedule` / `skillopt_unschedule` | `schedule` / `unschedule` | install/remove the nightly cron entry |\n\n## Prerequisites\n\n- DeepSeek Harness (dsh) installed — dsh 0.1.x and 0.2.x are supported\n  (`@deepseek-ai/dsh-tools` 0.1.1-rc.2, 0.2.0-rc.2)\n- Python 3.10+ with the SkillOpt-Sleep engine:\n\n```bash\npip install skillopt          # or use this source checkout\n```\n\n## Install\n\n### As a bundle in a profile\n\nAdd `dsh-skillopt` to the profile's bundles, or in the profile `cordis.patch.yml`:\n\n```yaml\n- insert:\n    - id: skillopt\n      name: './src/index.js'\n      config:\n        backend: mock          # or codex / claude / cursor / pi / opencode / handoff …\n        project: /path/to/project\n        preferences: 'Always use async/await'\n```\n\n### Local patch overlay (dev)\n\nRun from a DeepSeek Harness **source checkout** (the official dev workflow,\n`pnpm` resolves the workspace `dsh` bin):\n\n```bash\npnpm dsh web --patch ./plugins/dsh/cordis.patch.yml\n```\n\nIf `dsh` is installed **globally** (npm install -g), use it directly:\n\n```bash\ndsh web --patch ./plugins/dsh/cordis.patch.yml\n```\n\nEither way the patch inserts the `skillopt` plugin row into the profile; then\nask the agent: \"Use skillopt_status to check the sleep cycle state.\"\n\n## Config keys\n\n| Key | Default | Purpose |\n|---|---|---|\n| `pythonCmd` | `python` | Python interpreter for the engine |\n| `module` | — (bootstrap) | engine Python module override (`python -m <module>`) |\n| `engineScript` | — (scripts/sleep.py) | engine bootstrap script override |\n| `project` | — | default project directory |\n| `scope` | — | harvest scope: `all` \\| `invoked` |\n| `backend` | — | `mock\\|claude\\|codex\\|copilot\\|cursor\\|pi\\|opencode\\|handoff\\|azure_openai` |\n| `source` | — | `claude\\|codex\\|copilot\\|cursor\\|pi\\|opencode\\|auto` |\n| `model` | — | backend model override |\n| `maxTasks` / `maxSessions` | — | mine/harvest caps |\n| `editBudget` | — | bounded edits per cycle |\n| `preferences` | — | house rules for the reflection prior |\n| `jsonOutput` | `false` | machine-readable JSON output |\n| `autoAdopt` | `false` | OPERATOR-ONLY: auto-adopt a passed proposal without asking |\n| `unscheduleAll` | `false` | OPERATOR-ONLY: allow `skillopt_unschedule` to remove every managed entry |\n| `timeoutMs` | `600000` | per-call engine timeout in milliseconds |\n\nAdvanced engine keys (`gate_mode`, `gate_metric`, `gate_no_regression`,\n`dream_rollouts`, `recall_k`, `evolve_memory`/`evolve_skill`) go in\n`~/.skillopt-sleep/config.json` — the same file shared by all integrations.\n\n## Data boundary\n\n- Harvest is read-only; `mock`/`handoff` make no network calls.\n- `run` stages proposals; `adopt` is the normal live-change boundary and backs up first.\n- Real backends send truncated transcript excerpts and derived tasks to the\n  selected provider. For sensitive sessions, export tasks first (`skillopt_harvest`\n  with `output=`), redact, set `\"reviewed\": true`, then replay — real backends\n  refuse unreviewed task files.\n- Outbound prompts are not guaranteed secret-free; review source & provider policy.\n\n## Validate (no API spend)\n\n```bash\npython -m skillopt_sleep.experiments.run_experiment --persona researcher --assert-improves\n```\n\nSee the [SkillOpt-Sleep documentation](../../docs/sleep/README.md) for recorded\nresults, limitations, and the supported integration surface.\n","isInternal":false,"tokens":1514,"sizeBytes":5652},{"name":"README.md","path":"plugins/openclaw/README.md","rawUrl":"https://raw.githubusercontent.com/microsoft/SkillOpt/HEAD/plugins/openclaw/README.md","title":"openclaw Documentation","category":"plugin-manifest","format":"markdown","content":"# OpenClaw reference adaptation for SkillOpt-Sleep\n\nThis directory is a contributed reference for connecting\n[SkillOpt-Sleep](https://github.com/microsoft/SkillOpt) to\n[OpenClaw](https://github.com/openclaw/openclaw) with a custom DeepSeek/Ollama\nbackend.\n\n> **Reference status.** This is not one of the shared, plug-and-play\n> `skillopt_sleep` wrappers. Several scripts and the sample config contain\n> environment-specific absolute paths and assumptions from the original setup,\n> and the contributed wrapper has unresolved Python 3.10 syntax and backend\n> factory-signature gaps. The current checkout is not directly runnable; treat\n> it as porting source material, not an installation.\n\n## Included components\n\n| File | Purpose |\n|---|---|\n| `run_sleep.py` | custom cycle entry point |\n| `skillopt_sleep_openclaw.py` | DeepSeek Chat Completions backend plus local Ollama embeddings |\n| `run_sleep_cron.sh` | category-oriented cron wrapper |\n| `slash_sleep.py` | experimental `/sleep` command helper |\n| `config.json` | example engine configuration |\n| `SKILL.md` | OpenClaw skill manifest |\n| `tests/*.json` | example task sets for research, DevOps, and wiki workflows |\n\nThe adaptation imports the shared engine but registers its own backend and\nmaintains its own wrapper behavior. Changes to the shared CLI documentation do\nnot automatically make every option available through these custom scripts.\n\n## Intended cycle\n\n```text\nharvest supported session data or load a task file\n  → replay with the current skill\n  → propose bounded edits\n  → validate the candidate on held-out tasks\n  → stage a proposal for operator review\n```\n\nThe intended safety boundary is manual adoption: review the generated report and\nstaged files before changing a live skill.\n\n## Adapt before use\n\n1. Clone SkillOpt into a location you control:\n\n   ```bash\n   git clone https://github.com/microsoft/SkillOpt.git\n   cd SkillOpt/plugins/openclaw\n   ```\n\n2. Inspect and replace the sample absolute paths in `run_sleep.py`,\n   `slash_sleep.py`, `run_sleep_cron.sh`, and `config.json`. Confirm the engine\n   checkout, OpenClaw workspace, state directory, skill directory, and task-file\n   paths all point to isolated test locations.\n\n3. Review `config.json`. In particular, do not assume that values such as\n   `replay_mode` are enforced by this custom wrapper merely because they appear\n   in the example config. `max_tokens_per_night` is applied by the shared cycle,\n   but it is measured with the wrapper backend's rough `tokens_used()` estimate\n   (a quarter of the attempt prompt length plus 200 per attempt, 600 per rubric\n   judge call, and a third of the reflect prompt plus 1500 per reflect call), so\n   it is not a billing limit.\n\n4. Supply credentials through your normal secret-management mechanism. Do not\n   commit a DeepSeek key or place it in a world-readable file.\n\n5. Resolve every known porting gap listed in [`SKILL.md`](SKILL.md), add\n   isolated tests for your adapted backend, and verify that `--help` imports\n   cleanly on Python 3.10+. Only then start with a dry run and one reviewed\n   task file. The target command should be shaped like:\n\n   ```bash\n   cd /path/to/SkillOpt/plugins/openclaw\n   python3 run_sleep.py --config /path/to/reviewed-config.json \\\n     --tasks tests/research-cron-tasks.json --dry-run\n   ```\n\n6. Inspect the report, paths, network destinations, and proposed edits before\n   considering a non-dry run or scheduling.\n\n## Data boundary\n\nThe custom `openclaw-deepseek` backend sends task, skill, response, rubric, and\nreflection content to the configured DeepSeek endpoint. Its embedding helper can\nsend truncated text to the configured local Ollama service. Do not assume these\noutbound prompts have been fully redacted; inspect transcript/task inputs and the\nprovider's retention policy before using real data.\n\nUse HTTPS for a remote DeepSeek-compatible endpoint. Keep any plaintext Ollama\nendpoint on a trusted loopback interface. For a network-free engine smoke test,\nuse the shared SkillOpt-Sleep CLI with `--backend mock` rather than assuming this\ncustom wrapper is isolated.\n\n## Scheduling\n\n`run_sleep_cron.sh` and the scheduling helpers are examples, not portable\ninstallers. Adapt their paths, create log directories, verify their environment,\nand run the exact command manually before adding a cron entry. Scheduled runs\nmust preserve the same manual-adoption and credential boundaries as interactive\nruns.\n\n## Validation scope\n\nThe bundled JSON files are example held-out task sets, not a universal OpenClaw\nbenchmark. Provider cost and quality depend on the selected model, task content,\nnumber of calls, and pricing at run time; this reference does not promise a fixed\nnightly cost. Validate the adapted workflow in an isolated workspace before\nusing it on live skills.\n\nFor the supported shared-engine CLI and its current flags, see the\n[integration reference](../README.md#supported-cli-surface). For measured\nSkillOpt-Sleep results and limitations, see\n[`docs/sleep/RESULTS.md`](../../docs/sleep/RESULTS.md).\n\n## License\n\nMIT, consistent with SkillOpt core.\n","isInternal":false,"tokens":1155,"sizeBytes":5109},{"name":"README.md","path":"plugins/README.md","rawUrl":"https://raw.githubusercontent.com/microsoft/SkillOpt/HEAD/plugins/README.md","title":"plugins Documentation","category":"plugin-manifest","format":"markdown","content":"# SkillOpt-Sleep integrations\n\n**SkillOpt-Sleep** reviews recent agent sessions, mines recurring tasks, replays\nthem, and proposes bounded updates to memory and skills. A held-out validation\ngate decides whether a proposal is worth staging, and nothing live changes until\nthe user explicitly adopts it.\n\nThe shared engine lives in [`skillopt_sleep/`](../skillopt_sleep) and has no\nruntime dependency on the paper's `skillopt/` experiment package.\n\n## Available integrations\n\nSix integrations wrap the shared `skillopt_sleep` CLI. OpenClaw is a separate\nreference adaptation with its own backend and setup assumptions.\n\n| Platform | Folder | Mechanism | Status |\n|---|---|---|---|\n| **Claude Code** | [`claude-code/`](claude-code) | marketplace plugin, commands, skill, and hooks | installable shared-engine integration |\n| **Codex** | [`codex/`](codex) | user-level skill and shared runner | installable shared-engine integration |\n| **Cursor** | [`cursor/`](cursor) | native command and skill, project skill target, and shared runner | installable shared-engine integration |\n| **GitHub Copilot** | [`copilot/`](copilot) | MCP server exposing seven `sleep_*` tools | shared-engine MCP integration |\n| **Devin** | [`devin/`](devin) | MCP server plus Devin transcript conversion | shared-engine MCP integration |\n| **DeepSeek Harness** | [`dsh/`](dsh) | Cordis plugin: 7 native `skillopt_*` tools, skill, bundle patch layer | installable shared-engine integration |\n| **OpenClaw** | [`openclaw/`](openclaw) | custom DeepSeek/Ollama wrapper | independent reference adaptation; review and adapt before use |\n\n## Install\n\nClone the repository first unless an installed `skillopt-sleep` CLI is sufficient\nfor your workflow.\n\n| Platform | Install | Then |\n|---|---|---|\n| **Claude Code** | from the repository root, `/plugin marketplace add ./plugins/claude-code`, then `/plugin install skillopt-sleep@skillopt-sleep` | `/skillopt-sleep status` |\n| **Codex** | `bash plugins/codex/install.sh` | ask Codex to use the `skillopt-sleep` skill |\n| **Cursor** | `bash plugins/cursor/install.sh` (macOS/Linux) or `powershell -File plugins/cursor/install.ps1` (Windows) | `/skillopt-sleep status` |\n| **Copilot** | register `plugins/copilot/mcp_server.py` using its example MCP config | ask Copilot to run `sleep_status` |\n| **Devin** | register `plugins/devin/mcp_server.py` using its example MCP config | ask Devin to run `sleep_status` |\n| **DeepSeek Harness** | add `dsh-skillopt` to the profile's bundles, or patch it in — from a DSH source checkout: `pnpm dsh web --patch ./plugins/dsh/cordis.patch.yml`; with global dsh: `dsh web --patch ./plugins/dsh/cordis.patch.yml` | ask the agent to use `skillopt_status` |\n| **OpenClaw** | follow and adapt [`openclaw/README.md`](openclaw/README.md) | validate paths, credentials, and tasks locally |\n\nPython 3.10 or newer is required. Real CLI backends also require the selected\nagent CLI to be installed and authenticated.\n\nThe shared [`run-sleep.sh`](run-sleep.sh) supports both source checkouts and\ninstalled packages. If it cannot find the repository, it tries the\n`skillopt-sleep` executable on `PATH` (including `uv tool`/`pipx` installs), then\nan importable `skillopt_sleep` module. Install with `uv tool install skillopt` or\n`pip install skillopt` when using that fallback.\n\n> **Version note.** This integration reference tracks `main`. PyPI 0.2.0\n> supports the base Sleep CLI, while Cursor source/backend/plugin support,\n> Pi source/backend support, handoff, Sleep support for non-Azure\n> OpenAI-compatible endpoints, OpenCode Sleep source/backend support, and\n> `--preferences`, multi-skill fan-out, and reviewed subset adoption require a\n> source checkout from `main` until the next release.\n\n## One sleep cycle\n\n```text\nharvest supported local sessions → mine recurring tasks → replay tasks\n  → reflect and propose bounded edits → validate on held-out real tasks\n  → stage proposal → (you) review and adopt\n```\n\nThe default backend is `mock`: it makes no provider calls and is useful for\nchecking plumbing. A real backend is required for model-driven mining and genuine\noptimization.\n\n## Data boundary\n\n- Harvesting is local and read-only. The `mock` and `handoff` backends make no\n  network calls; handoff writes prompts for separate, user-controlled completion.\n- A real backend sends mining, replay, judging, and reflection prompts derived\n  from truncated transcript excerpts and tasks to the selected provider.\n- The Cursor source reads local user/assistant message text, explicit turn\n  errors, and tool names from `~/.cursor/projects/*/agent-transcripts`; it does\n  not retain tool arguments, tool outputs, or other record types. Known\n  secret-shaped strings are redacted, but this is defense in depth rather than\n  a guarantee that outbound prompts are secret-free.\n- The Cursor backend sends prompts through the installed, authenticated\n  `cursor-agent` CLI. Ordinary calls use read-only Ask mode in a new empty\n  temporary workspace with project file access denied. Cursor tasks containing\n  `tool_called` validation fail before Agent mode starts; use another backend for\n  those tasks. Cursor and the model provider selected by Cursor can receive the\n  resulting prompt content.\n- The Pi backend sends prompts through the installed, authenticated Pi CLI to\n  the provider configured by the user. It disables tools, skills, context files,\n  extensions, prompt templates, themes, and session writes for these calls, but\n  retains the user's Pi authentication and model configuration. Pi's offline\n  startup mode prevents configured npm/git package installation, package\n  updates, and model-catalog refresh; it does not prevent the selected provider\n  call. These controls are not a guarantee of permanent or complete isolation.\n- The Pi source retains user/assistant text, tool names, and lexical feedback\n  found in user text. It excludes thinking, tool arguments, tool outputs, images,\n  and unrelated metadata. The absolute project `cwd` from the session header is\n  retained for scope filtering and may appear in miner prompts sent to a real\n  backend and its provider. Known secret-shaped strings in retained message text\n  are redacted only as defense in depth.\n- The core `opencode` source reads local OpenCode SQLite history without the\n  CLI, authentication, or provider access. See\n  [the CLI reference](../docs/reference/cli.md#opencode-source-and-backend) for\n  its retained-data boundary.\n- The core `opencode` backend uses the installed OpenCode CLI. Plain calls\n  disable project configuration, model-initiated tool invocation, external\n  plugins, and configured MCP servers. Tool-aware replay requires explicit\n  opt-in. It exposes only temporary synthetic tools with randomized names and\n  fixed results, then verifies which tools OpenCode actually invoked. See the\n  [CLI reference](../docs/reference/cli.md#opencode-source-and-backend) for\n  history and isolation details. A native OpenCode plugin or command is not\n  included.\n- Outbound prompts are not currently guaranteed to be free of secrets. Do not\n  use a third-party provider on sensitive transcripts without reviewing the data\n  source and the provider's retention policy.\n- For a reviewable workflow, export tasks first, inspect and redact the JSON, set\n  its top-level `\"reviewed\"` field to `true`, and then use the task file with a\n  real backend:\n\n  ```bash\n  python -m skillopt_sleep harvest --project \"$(pwd)\" --output reviewed-tasks.json\n  python -m skillopt_sleep dry-run --project \"$(pwd)\" --backend codex \\\n    --tasks-file reviewed-tasks.json --progress\n  ```\n\n  Real backends reject task files that are still marked unreviewed.\n\nFor the separate API-key and Azure managed-identity transport boundaries, see\n[OpenAI-compatible endpoints](../docs/sleep/openai-compatible-endpoints.md).\n\n## Supported CLI surface\n\nActions:\n\n| Action | Behavior |\n|---|---|\n| `status` | show state and the latest staged proposal |\n| `dry-run` | harvest, mine, replay, and report; stage nothing |\n| `run` | run the full cycle and stage a proposal |\n| `adopt` | apply the latest staged proposal, with backups |\n| `harvest` | inspect or export mined tasks |\n| `schedule` / `unschedule` | install or remove the managed nightly cron entry |\n\nCommon implemented flags include:\n\n| Flag | Default | Purpose |\n|---|---|---|\n| `--backend mock\\|claude\\|codex\\|cursor\\|copilot\\|pi\\|opencode\\|handoff\\|azure_openai` | `mock` | select who performs model calls |\n| `--model NAME` | backend default | select a backend-specific model |\n| `--source claude\\|codex\\|copilot\\|cursor\\|pi\\|opencode\\|auto` | `claude` | select the transcript source; `auto` retains Codex-then-Claude precedence and does not select Copilot, Cursor, Pi, or OpenCode |\n| `--cursor-home PATH` | `~/.cursor` | override the Cursor transcript home |\n| `--cursor-path PATH` | auto-detect `cursor-agent` | select the Cursor Agent CLI executable |\n| `--pi-home PATH` | `~/.pi` | select the parent directory containing `agent/sessions` |\n| `--pi-path PATH` | auto-detect `pi` | select the Pi coding-agent CLI executable |\n| `--opencode-path PATH` | `SKILLOPT_SLEEP_OPENCODE_PATH`, then `opencode` on `PATH`/`PATHEXT` | select the OpenCode CLI executable |\n| `--opencode-db PATH` | `OPENCODE_DB`, `%LOCALAPPDATA%`/`%APPDATA%` (Windows), or `${XDG_DATA_HOME:-~/.local/share}/opencode/opencode.db` | select the OpenCode SQLite history database |\n| `--opencode-tool-replay` | off | enable OpenCode tool-aware replay for `tool_called` checks in rule judges |\n| `--project PATH` | current directory | select the project and invoked harvest scope |\n| `--scope invoked\\|all` | `invoked` | limit transcript harvesting |\n| `--target-skill-path PATH` | managed skill | select a specific `SKILL.md` to stage/adopt |\n| `--tasks-file PATH` | none | replay a reviewed task file instead of harvesting |\n| `--max-sessions N` / `--max-tasks N` | unset → `3 × tasks` / `40` tasks | bound harvested work; these are not hard token or wall-clock budgets |\n| `--edit-budget N` | `4` | cap bounded edits per cycle |\n| `--preferences \"...\"` | empty | add house rules to the reflection prior |\n| `--progress` | off | print phase progress to stderr |\n| `--auto-adopt` | off | adopt an accepted proposal without a separate command |\n| `--json` | off | emit machine-readable output where supported |\n\nThe nightly CLI does **not** currently expose `--gate`, `--rollouts-k`,\n`--optimizer-model`, `--target-model`, `--budget-tokens`, or `--budget-minutes`.\nDo not pass experiment-harness flags to the main CLI.\n\nFor the Cursor backend, `--project` also selects target files, state, and the\nstaging location, but it does not make that directory the Cursor Agent execution\nworkspace. The target skill is inserted as prompt text rather than invoked as a\nnative skill. Real-backend `dry-run` performs the same mining and replay model\ncalls while suppressing staging, adoption, and persisted state changes. The\ncurrent Sleep cycle does not implement fresh-worktree replay; a `replay: mock`\nreport label describes prompt replay and is independent of `--backend mock`.\n\n### Preferences\n\n`--preferences` is the main user-facing steering knob:\n\n```bash\npython -m skillopt_sleep run --backend codex --project \"$(pwd)\" \\\n  --preferences \"Prefer pytest. Keep commit subjects imperative and concise.\"\n```\n\nPreferences guide reflection but remain subject to the validation gate.\n\n### Pi source and backend\n\nPi transcript harvesting is explicit: `--source pi` reads session JSONL files\nbelow `~/.pi/agent/sessions`; use `--pi-home` to select the parent directory\nthat contains `agent/sessions`. This source does not require the Pi CLI or\nprovider authentication. It retains user/assistant text, tool names, and lexical\nfeedback found in user text, while excluding thinking, tool arguments, tool\noutputs, images, and unrelated metadata. The absolute project `cwd` from the\nsession header is retained for scope filtering and may appear in miner prompts\nsent to a real backend and its provider. Known secret-shaped strings in retained\nmessage text are redacted as defense in depth, not as a guarantee. `--source auto` keeps Codex-then-Claude\nprecedence and does not select Pi.\n\nThe source and backend are independent. `--backend pi` uses a locally installed,\nauthenticated Pi CLI to make real model-provider calls for mining, replay,\njudging, and reflection. Select another executable with `--pi-path` and a model\nwith `--model`:\n\n```bash\npython -m skillopt_sleep run --project \"$(pwd)\" \\\n  --source pi --backend pi --pi-path /absolute/path/to/pi \\\n  --model provider/model --max-sessions 5 --max-tasks 3 --progress\n```\n\nPi calls disable tools, skills, context files, extensions, prompt templates,\nthemes, and session writes. They still use the user's Pi authentication and\nmodel configuration. Pi's offline startup mode also prevents configured npm/git\npackage installation, package updates, and model-catalog refresh; it does not\nprevent the selected provider call. This is bounded invocation setup rather\nthan permanent or complete isolation. Transcript-derived prompts reach the\nprovider configured in Pi; review that provider's data-retention and privacy\npolicy before using sensitive sessions.\n\nThe managed scheduler stores the selected backend but does not persist\n`--source`, `--pi-home`, `--pi-path`, or `--model`. Before scheduling Pi, set\n`transcript_source`, `pi_home`, `pi_path`, and `model` in\n`~/.skillopt-sleep/config.json`; prefer an absolute `pi_path` and verify that the\nscheduled account is authenticated.\n\n### Cursor source and backend\n\nCursor transcript harvesting is explicit: use `--source cursor` rather than\n`--source auto`. Invoked-project scope uses Cursor's recorded workspace path,\nwith the sanitized storage directory as a fallback; `--scope all` scans every\nCursor workspace under `~/.cursor/projects`. The model-driven backend requires\nan installed, authenticated `cursor-agent`; use `--cursor-path`,\n`SKILLOPT_SLEEP_CURSOR_PATH`, or the `cursor_path` config key when it is not on\n`PATH`, and use `--model` or `SKILLOPT_SLEEP_CURSOR_MODEL` to choose a model.\n\nTarget the project skill explicitly so accepted learning becomes visible to\nCursor without changing the plugin's own workflow skill:\n\n```bash\npython -m skillopt_sleep run --project \"$(pwd)\" \\\n  --source cursor --backend cursor \\\n  --target-skill-path .cursor/skills/skillopt-sleep-learned/SKILL.md \\\n  --max-sessions 5 --max-tasks 3 --progress\n```\n\n### Advanced config\n\nThe JSON/YAML config under `~/.skillopt-sleep/` supports additional engine keys,\nincluding `gate_mode`, `gate_metric`, `gate_no_regression`, `dream_rollouts`,\n`dream_factor`, `recall_k`, `evolve_memory`, and `evolve_skill`. These are config\nkeys, not aliases for the unsupported CLI flags listed above. Shipping defaults\nare conservative: `gate_mode=\"on\"`, `gate_no_regression=false`,\n`dream_rollouts=1`, `dream_factor=0`, and `recall_k=0`.\n\nThe managed `schedule` command stores only the project, backend, time, and\noptional auto-adopt setting. It does not copy `--source`, `--cursor-home`,\n`--cursor-path`, `--model`, or `--target-skill-path` into the scheduled command.\nFor a Cursor schedule, set `transcript_source`, `cursor_home`, `cursor_path`,\n`model`, and `target_skill_path` in `~/.skillopt-sleep/config.json` first. Keep\nthe target project-relative, use an absolute CLI path because cron and Task\nScheduler may have a minimal `PATH`, and confirm that `cursor-agent` is\nauthenticated for the account that runs the job.\n\n### Handoff backend\n\n`--backend handoff` keeps model subprocesses out of the engine. It writes pending\nmodel calls to `.skillopt-sleep-handoff/PROMPTS.md` and `pending.json`, exits with\ncode 3, and resumes after answers are placed in `answers/<id>.md`:\n\n```bash\npython -m skillopt_sleep run --backend handoff --project \"$(pwd)\"\n# answer each prompt in a fresh context, then run the same command again\n```\n\nAnswering held-out prompts from a context that has already seen their references\ncontaminates the validation gate. Claude Code's `/skillopt-sleep-handoff` command\nautomates the loop with isolated fresh-context subagents.\n\n## Validation\n\nThe deterministic no-provider check exercises consolidation and the gate:\n\n```bash\npython -m skillopt_sleep.experiments.run_experiment \\\n  --persona researcher --assert-improves\n```\n\nReal-model benchmark results and their limitations are documented in\n[`docs/sleep/RESULTS.md`](../docs/sleep/RESULTS.md). The benchmark recipes are not\nthe shipping CLI defaults.\n\n## Safety summary\n\n- Session harvesting is read-only.\n- `mock` and `handoff` make no network calls.\n- `run` stages proposals; `adopt` is the normal live-change boundary.\n- Adoption backs up existing target files.\n- `--max-sessions` and `--max-tasks` bound work. `max_tokens_per_night` in the\n  config file (default `400000`) stops a night from starting new steps once its\n  token count reaches the budget, but a started step finishes, so it is not a\n  hard cap. There is no elapsed-time budget.\n- Treat real-backend transcript excerpts as data shared with the selected\n  provider.\n","isInternal":false,"tokens":4072,"sizeBytes":17122}],"systemPromptSnippet":"<yakaai_skills repo=\"microsoft/SkillOpt\">\n<!-- File: plugins/claude-code/skills/skillopt-sleep/SKILL.md (Tokens: ~2218 | Category: anthropic-skill) -->\n---\nname: skillopt-sleep\ndescription: \"Use when the user wants their Claude agent to self-improve from past usage, asks about a nightly/offline 'sleep' or 'dream' cycle, memory/skill consolidation, or says things like 'make my agent better the more I use it', 'review my past sessions', 'learn my preferences', 'consolidate what you learned', 'run the sleep cycle', or wants to schedule background self-optimization. Drives the skillopt_sleep engine: harvest past sessions -> mine recurring tasks -> replay through a selected backend -> consolidate validated CLAUDE.md/SKILL.md behind a held-out gate.\"\n---\n\n# SkillOpt-Sleep: usage-driven self-evolution for a local Claude agent\n\nSkillOpt-Sleep gives the user's agent a **sleep cycle**. On demand or on a\nnightly schedule, it reviews real past Claude Code sessions, re-runs recurring\ntasks through the selected backend, and consolidates what it\nlearns into **memory** (`CLAUDE.md`) and **skills** (`SKILL.md`). With the\ndefault validation gate enabled, it keeps only changes that improve a held-out\nscore. Live files change only through explicit adoption or a user-requested\n`--auto-adopt`. It aims to improve this user's recurring work, while making\neach accepted proposal measurable on the run's held-out tasks,\nwith no model-weight training. It is the deployment-time analogue of training:\nshort-term experience → long-term competence.\n\nIt synthesizes three ideas:\n- **SkillOpt** — the skill/memory doc is trainable text; bounded add/delete/replace\n  edits; accepted only through a held-out gate; rejected edits are recorded in\n  the run report for review.\n- **Claude Dreams** — consolidation that reads past sessions and proposes changes\n  inside protected learned blocks; the input is never mutated, and output is\n  reviewed before adoption.\n- **Agent sleep** — periodic background replay turns episodes into durable skill.\n\n## When to use this skill\n\nTrigger when the user wants any of:\n- \"make my agent learn from how I use it\" / \"get better the more I use it\" / \"remember my preferences across sessions\"\n- a nightly/scheduled or on-demand **offline self-improvement / dream / sleep** run\n- to **review past sessions/trajectories** and distill recurring tasks\n- to **consolidate** feedback into `CLAUDE.md` or a managed skill\n- to **schedule** the cycle (cron) or **adopt** a staged proposal\n\n## The cycle (six stages)\n\n1. **Harvest** — read `~/.claude/projects/*/<session>.jsonl` + `~/.claude/history.jsonl` (READ-ONLY) → session digests.\n2. **Mine** — digests → `TaskRecord`s (recurring intents + outcome labels + checkable refs where possible).\n3. **Replay** — re-run tasks through the selected backend under the *current*\n   skill+memory → (hard, soft) scores.\n4. **Consolidate** — reflect on failures → propose bounded edits → **gate** on a held-out slice; with the default gate enabled, accept only if it strictly improves.\n5. **Stage** — write the accepted `proposed_CLAUDE.md` and/or\n   `proposed_SKILL.md`, plus `report.md`, `report.json`, `manifest.json`, and\n   `diagnostics.json` into `<project>/.skillopt-sleep/staging/<timestamp>/`.\n   **Nothing live changes.** A rejected run still has a report but no proposed\n   live-file replacement.\n6. **Adopt** — explicit (or opt-in auto): copy staged files over live ones, backing up first.\n\n## How to drive it\n\nPrefer the `/skillopt-sleep` command. Under the hood it calls the bundled runner:\n\n```bash\n\"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh\" status                       # what's happened\n\"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh\" dry-run --project \"$(pwd)\"    # no-staging preview\n\"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh\" run --project \"$(pwd)\"        # full cycle, stages a proposal\n\"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh\" adopt --project \"$(pwd)\"      # apply staged proposal (with backup)\n```\n\n- Default backend is `mock` (deterministic, **no API spend**) — good for trying the plumbing.\n- Add `--backend claude` or `--backend codex` to spend the user's real budget\n  for model-driven optimization. A held-out gain is run-specific evidence, not\n  a guarantee of broader improvement; results depend on the tasks, model, and\n  checks.\n- Scope defaults to the invoked project; `--scope all` harvests every Claude\n  project into the current run's configured targets.\n- A real backend sends truncated transcript/task content to its provider. See\n  the data-boundary rules below before using one with sensitive sessions.\n\n### Scheduling\n\n```bash\n\"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh\" schedule --project \"$(pwd)\" --hour 3 --minute 17\n\"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh\" unschedule --project \"$(pwd)\"\n```\n\nInstalls a nightly cron entry. `unschedule --all` removes every managed entry.\n\n## Common CLI flags\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `--project PATH` | cwd | Project directory to evolve |\n| `--scope all\\|invoked` | invoked | Harvest scope |\n| `--backend mock\\|claude\\|codex\\|copilot\\|handoff\\|azure_openai` | mock | Backend (mock = no provider calls) |\n| `--model NAME` | backend default | Override the model used for replay |\n| `--source claude\\|codex\\|auto` | claude | Transcript source |\n| `--lookback-hours N` | 72 | Harvest window |\n| `--max-sessions N` | derived | Cap harvested sessions; defaults to 3 × max tasks (120 with current defaults) |\n| `--max-tasks N` | 40 | Cap mined tasks |\n| `--target-skill-path PATH` | `~/.claude/skills/skillopt-sleep-learned/SKILL.md` | Explicit SKILL.md to evolve |\n| `--tasks-file PATH` | — | Reviewed TaskRecord JSON (skip harvest) |\n| `--progress` | off | Print phase progress to stderr |\n| `--auto-adopt` | off | Auto-adopt if gate passes |\n| `--edit-budget N` | 4 | Max bounded edits per night |\n| `--preferences TEXT` | empty | Add house rules to the optimizer's reflection prior |\n| `--json` | off | Machine-readable JSON output |\n\nThe CLI also has source/runtime path overrides (`--claude-home`, `--codex-home`,\nand `--codex-path`) and action-specific flags. Use\n`python -m skillopt_sleep <action> --help` as the authoritative surface.\n\n## Config keys (`~/.skillopt-sleep/config.json`)\n\nBeyond the CLI flags, advanced behavior is controlled via config:\n\n- **`preferences`** — free-text house rules injected into the optimizer's reflect step (e.g. \"Always use async/await\", \"Answers in `\\boxed{}`\").\n- **`gate_mode`** — `on` (default, validation-gated) or `off` (greedy, accept all edits).\n- **`gate_metric`** — `hard`, `soft`, or `mixed` (default). Controls how the held-out gate scores.\n- **`gate_no_regression`** — `false` by default. Set to `true` to reject a candidate when any validation task's configured gate score decreases.\n- **`dream_rollouts`** — >1 enables multi-rollout contrastive reflection per task.\n- **`recall_k`** — >0 recalls K similar past tasks into the dream (long-term memory).\n- **`evolve_memory`** / **`evolve_skill`** — independently toggle CLAUDE.md vs SKILL.md consolidation.\n\n## Memory consolidation\n\nThe sleep cycle can consolidate both:\n- **SKILL.md** — the managed skill file (bounded edits: add/delete/replace)\n- **CLAUDE.md** — the project memory (same bounded edits)\n\nWith the default gate enabled, both are evaluated by the same held-out score.\nSet `evolve_memory: false` to consolidate only skills, or `evolve_skill: false`\nfor only memory.\n\n## Hard rules\n\n- **Never** hand-edit the user's `CLAUDE.md` / `SKILL.md` as part of this skill.\n  Let the engine's explicit `adopt` or user-requested `--auto-adopt` path apply\n  the staging manifest and back up existing live files first.\n- Harvest is read-only. `mock` replay has no side effects.\n- Real backends send truncated transcript excerpts and derived tasks to the\n  selected provider for mining, replay, judging, and reflection. The Claude\n  transcript path is not guaranteed to remove every secret before those calls.\n  Review provider policy and session contents first. For sensitive data, use\n  `mock` or run `harvest --output <file>`, inspect/redact the JSON, set\n  `\"reviewed\": true`, and replay it with `--tasks-file`; real backends refuse an\n  unreviewed task file.\n- Always show the user the **held-out baseline → candidate** score and the\n  exact proposed edits before suggesting adoption. Evidence before adoption.\n- If asked to demonstrate the mechanism without provider calls, run\n  `python -m skillopt_sleep.experiments.run_experiment --persona researcher --json`\n  — a deterministic synthetic demo of held-out lift and gate rejection. It\n  validates the mechanism, not effectiveness on the user's own tasks.\n\n## Validate / demo\n\n```bash\n# deterministic synthetic demo (no API): score rises and the gate blocks a regression\npython -m skillopt_sleep.experiments.run_experiment --persona researcher --assert-improves\npython -m skillopt_sleep.experiments.run_experiment --persona programmer  --assert-improves\n```\n\nSee the [SkillOpt-Sleep documentation](https://github.com/microsoft/SkillOpt/tree/main/docs/sleep)\nfor recorded results, limitations, and the supported integration surface.\n\n<!-- File: plugins/codex/skills/skillopt-sleep/SKILL.md (Tokens: ~2354 | Category: anthropic-skill) -->\n---\nname: skillopt-sleep\ndescription: \"Use when the user wants Codex to self-improve from past usage, asks about a nightly/offline 'sleep' or 'dream' cycle, wants Codex to review past sessions, learn preferences, consolidate memory/skills, run dry-run/run/adopt/status for SkillOpt-Sleep, or schedule background self-optimization. Drives the skillopt_sleep engine: harvest past sessions -> mine recurring tasks -> replay through a selected backend -> consolidate validated memory + skills behind a held-out gate.\"\n---\n\n# SkillOpt-Sleep: usage-driven self-evolution for a local Codex agent\n\nSkillOpt-Sleep gives the user's Codex agent a sleep cycle. On demand or on a\nnightly schedule, it reviews past local sessions, re-runs recurring tasks\nthrough the selected backend, and proposes changes to a configured skill and to\nthe project's `CLAUDE.md`. With the default validation gate enabled, it keeps\nonly changes that improve a held-out score. Live files change only through\nexplicit adoption or a user-requested `--auto-adopt`. There is no model-weight\ntraining.\n\nThe current shared engine does **not** write `AGENTS.md`. For a Codex-visible\nresult, always select a Codex skill explicitly with `--target-skill-path` (for\nexample `.agents/skills/<name>/SKILL.md`). If project `CLAUDE.md` is not a\ndesired secondary target, set `\"evolve_memory\": false` in\n`~/.skillopt-sleep/config.json` before running.\n\n## When to use\n\nTrigger when the user wants any of:\n\n- Codex to learn from past sessions or get better the more they use it;\n- a nightly/scheduled or on-demand sleep/dream/offline self-improvement run;\n- to review past sessions and distill recurring tasks;\n- to consolidate feedback into memory or managed skills;\n- to run `status`, `harvest`, `dry-run`, `run`, or `adopt` for SkillOpt-Sleep.\n\n## The cycle\n\n1. **Harvest** - read local session transcripts according to the engine\n   configuration and normalize them into session digests.\n2. **Mine** - turn digests into recurring `TaskRecord`s with outcomes and\n   checkable references where possible.\n3. **Replay** - re-run mined tasks through the selected backend under the\n   current skill and memory.\n4. **Consolidate** - reflect on failures and propose bounded edits.\n5. **Gate** - with the default gate enabled, accept edits only when the held-out\n   validation score improves.\n6. **Stage** - write the proposal under\n   `<project>/.skillopt-sleep/staging/<date>/`; nothing live changes.\n7. **Adopt** - explicitly, or through user-requested auto-adopt, copy staged\n   files over live files with backups for existing targets.\n\n## How to drive it\n\nInvoke the bundled runner via shell (Codex `exec` has shell access). The runner\nfinds the engine and a Python >= 3.10 automatically.\n\n```bash\n# point at the repo if it isn't auto-detected from CWD:\nexport SKILLOPT_SLEEP_REPO=/path/to/SkillOpt\nTARGET_SKILL=.agents/skills/example/SKILL.md\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" status --project \"$(pwd)\"\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" harvest --project \"$(pwd)\" \\\n  --source codex --target-skill-path \"$TARGET_SKILL\"\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" dry-run --project \"$(pwd)\" \\\n  --source codex --target-skill-path \"$TARGET_SKILL\" --backend mock\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" run --project \"$(pwd)\" \\\n  --source codex --target-skill-path \"$TARGET_SKILL\" --backend codex \\\n  --max-sessions 5 --max-tasks 3 --progress\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" status --project \"$(pwd)\"\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" adopt --project \"$(pwd)\" --legacy\n```\n\nFor a fan-out night, select reviewed proposals with repeatable\n`--skill NAME` or `--all-skills`; do not treat bare adopt as “adopt everything.”\n\nOn Windows (CMD / PowerShell):\n```cmd\n:: CMD\nset SKILLOPT_SLEEP_REPO=C:\\path\\to\\SkillOpt-Sleep\n\"%SKILLOPT_SLEEP_REPO%\\plugins\\run-sleep.cmd\" status --project \"%CD%\"\n```\n```powershell\n# PowerShell\n$env:SKILLOPT_SLEEP_REPO = \"C:\\path\\to\\SkillOpt-Sleep\"\npowershell -File \"$env:SKILLOPT_SLEEP_REPO\\plugins\\run-sleep.ps1\" status --project \"$(pwd)\"\n```\n\nActions are `status`, `harvest`, `dry-run`, `run`, `adopt`, `schedule`, and `unschedule`.\n\n- Default backend is `mock`, which is deterministic and spends no API budget.\n- `--backend codex` uses the user's Codex budget for model-driven optimization.\n  An accepted held-out gain is run-specific evidence, not a guarantee of\n  broader improvement; results depend on the tasks, model, and checks.\n- `--source codex` reads Codex Desktop archived sessions from `~/.codex/archived_sessions`;\n  use `--codex-home /path/to/.codex` if the archive lives elsewhere.\n- `--target-skill-path` is required for a Codex skill target. Without it, the\n  shared default is a Claude-managed skill under `~/.claude/skills/`, not an\n  `.agents` skill.\n- Keep `dry-run --backend mock` as the first smoke check unless the user\n  explicitly asked for a real optimization run.\n\n### Scheduling\n\n```bash\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" schedule --project \"$(pwd)\" \\\n  --backend codex --hour 3 --minute 17\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" unschedule --project \"$(pwd)\"\n```\n\nThe scheduler persists the project, backend, time, and optional auto-adopt flag;\nit does not persist `--source` or `--target-skill-path` from this command. Before\nscheduling a Codex-targeted run, set `\"transcript_source\": \"codex\"` and an\nabsolute `\"target_skill_path\"` in `~/.skillopt-sleep/config.json`. On systems\nwithout `crontab`, `schedule` prints a line for manual installation.\n`unschedule --all` removes every managed entry.\n\n### All backends\n\n- `--backend mock` — deterministic, no API spend (default)\n- `--backend claude` — uses the Claude CLI\n- `--backend codex` — uses the Codex CLI\n- `--backend copilot` — uses the GitHub Copilot CLI\n- `--backend handoff` — emits prompt/answer files for an interactive session\n- `--backend azure_openai` — uses the configured Azure OpenAI endpoint\n\n### Additional flags\n\n| Flag | Description |\n|------|-------------|\n| `--auto-adopt` | Auto-adopt if the gate passes (default: stage only) |\n| `--edit-budget N` | Max bounded edits per night (default: 4) |\n| `--lookback-hours N` | Harvest window in hours (default: 72) |\n| `--json` | Machine-readable JSON output |\n\n### Config keys (`~/.skillopt-sleep/config.json`)\n\n- **`preferences`** — free-text house rules for the optimizer\n- **`gate_mode`** — `on` (validation-gated, default) or `off` (greedy)\n- **`gate_metric`** — `hard` | `soft` | `mixed` (default)\n- **`gate_no_regression`** — `false` by default; set it to `true` to reject a candidate when any validation task's gate score decreases\n- **`dream_rollouts`** — >1 for multi-rollout contrastive reflection\n- **`recall_k`** — >0 recalls similar past tasks from the archive\n\n### Memory consolidation\n\nThe shared sleep cycle consolidates project **memory** (`CLAUDE.md`) and the\nselected **skill** (`SKILL.md`) by default. It does not update `AGENTS.md`.\nEach target is independently toggleable through `evolve_memory` /\n`evolve_skill`, and both are gated by the same held-out validation score.\n\n## Steps\n\n1. Run the requested action; capture stdout.\n2. For `dry-run` and `run`, report the held-out baseline -> candidate score,\n   gate action, task count, session count, and exact proposed edits.\n3. If a staging directory is printed, read `report.md` before summarizing.\n4. `run` stages by default; if `--auto-adopt` was explicitly supplied, report\n   the paths it updated instead of claiming nothing changed.\n5. Offer adoption only after the user has reviewed a still-staged proposal.\n6. Never hand-edit the configured `CLAUDE.md` or target skill as a substitute\n   for the engine's adopt path; adoption is the safety boundary and backs up\n   existing targets first.\n\n## Hard rules\n\n- Harvest is read-only. Do not edit archived sessions or raw transcripts.\n- Codex transcript harvesting removes known secret-shaped strings, developer\n  instructions, and raw tool payloads, but pattern-based redaction is not a\n  guarantee. A real backend still sends truncated transcript/task content to\n  its provider. Review sensitive sessions and provider policy first; prefer a\n  reviewed `--tasks-file` workflow when the data boundary matters.\n- Keep raw secrets, credentials, private user data, and transcript contents out\n  of messages, logs, generated artifacts, and commits.\n- Show validation evidence before recommending adoption.\n- Treat generated edits as proposals, not as source of truth.\n- Do not rely on deprecated custom prompts or `/sleep` slash commands for this\n  Codex integration. This skill is the entrypoint.\n\n## Validate\n\n```bash\npython -m skillopt_sleep dry-run --project \"$(pwd)\" --source codex \\\n  --target-skill-path .agents/skills/example/SKILL.md --backend mock --json\npython -m skillopt_sleep.experiments.run_gbrain --backend codex \\\n  --seeds brief-writer --data-root /path/to/gbrain-evals/eval/data/skillopt-v1 \\\n  --nights 2 --limit-replay 3 --limit-holdout 3\n```\n\nIn the recorded `brief-writer` gbrain run, the deliberately deficient fixture\nwent 0.00 -> 1.00 on that run's held-out set. Treat this as reproducible\nbenchmark evidence for that configuration, not a guarantee for other skills,\ntasks, or models; see the\n[recorded results](https://github.com/microsoft/SkillOpt/blob/main/docs/sleep/RESULTS.md)\nfor context and limitations.\n\n<!-- File: plugins/cursor/skills/skillopt-sleep/SKILL.md (Tokens: ~2284 | Category: anthropic-skill) -->\n---\nname: skillopt-sleep\ndescription: \"Use when the user wants Cursor to learn from recent local sessions, asks for an offline sleep or dream cycle, wants to consolidate recurring work into a Cursor skill, or requests SkillOpt-Sleep status, harvest, dry-run, run, scheduling, review, or adoption. Drives the validation-gated skillopt_sleep engine with Cursor transcripts and the optional Cursor Agent CLI backend.\"\n---\n\n# SkillOpt-Sleep for Cursor\n\nSkillOpt-Sleep reviews recent local Cursor sessions, mines recurring tasks,\nreplays those tasks, and proposes bounded improvements to a project Cursor\nskill. With the default gate enabled, a proposal is accepted only when it\nimproves the held-out score. A normal run stages the proposal for review;\nnothing live changes until explicit adoption. There is no model-weight training.\n\nThis plugin has no session-end hook and no MCP server. Run the cycle only when\nthe user asks, or install a schedule only when the user explicitly requests one.\n\n## Cursor target\n\nAlways use this project-relative target for Cursor-visible learning:\n\n```text\n.cursor/skills/skillopt-sleep-learned/SKILL.md\n```\n\nPass it through `--target-skill-path` on `harvest`, `dry-run`, and `run`.\nWithout an explicit target, the shared engine uses a Claude-managed skill under\n`~/.claude/skills`, which is not the intended Cursor project skill.\n\nThe shared engine can also evolve project `CLAUDE.md`. If that secondary memory\ntarget is unwanted, set `\"evolve_memory\": false` in\n`~/.skillopt-sleep/config.json` before running.\n\n## Choose the runner\n\nUse one of these supported command paths consistently:\n\n1. Source checkout on macOS/Linux:\n   `bash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" <action> ...`\n2. Source checkout on Windows:\n   `powershell -File \"$env:SKILLOPT_SLEEP_REPO\\plugins\\run-sleep.ps1\" <action> ...`\n3. Installed engine on any platform:\n   `skillopt-sleep <action> ...`\n\nIf `SKILLOPT_SLEEP_REPO` is not set and `skillopt-sleep` is unavailable, stop\nand explain that the engine must be installed or a SkillOpt checkout must be\nselected. Do not substitute a hand-written edit for the engine workflow.\n\n## Core workflow\n\n1. **Harvest** local Cursor JSONL transcripts read-only.\n2. **Mine** recurring, checkable task records from session digests.\n3. **Replay** tasks under the current skill and memory through the selected\n   backend.\n4. **Reflect** on failures and propose bounded edits.\n5. **Gate** the candidate on held-out real tasks.\n6. **Stage** accepted proposals under\n   `<project>/.skillopt-sleep/staging/<timestamp>/`.\n7. **Adopt** only after review, backing up existing live targets first.\n\n## Commands\n\nUse the installed-command form below, or replace `skillopt-sleep` with the\nplatform-specific source runner described above.\n\n```bash\nTARGET_SKILL=.cursor/skills/skillopt-sleep-learned/SKILL.md\n\n# Inspect current state and the latest staged proposal.\nskillopt-sleep status --project \"$(pwd)\"\n\n# Inspect mined tasks without provider spend.\nskillopt-sleep harvest --project \"$(pwd)\" --source cursor \\\n  --target-skill-path \"$TARGET_SKILL\" --max-sessions 5 --max-tasks 3\n\n# First smoke check: deterministic and no provider calls.\nskillopt-sleep dry-run --project \"$(pwd)\" --source cursor --backend mock \\\n  --target-skill-path \"$TARGET_SKILL\" --max-sessions 5 --max-tasks 3 --json\n\n# Model-driven optimization through the authenticated Cursor Agent CLI.\nskillopt-sleep run --project \"$(pwd)\" --source cursor --backend cursor \\\n  --target-skill-path \"$TARGET_SKILL\" \\\n  --max-sessions 5 --max-tasks 3 --progress\n\n# Inspect selections, then apply the reviewed managed proposal.\nskillopt-sleep status --project \"$(pwd)\"\nskillopt-sleep adopt --project \"$(pwd)\" --legacy\n```\n\nFor fan-out proposals, use repeatable `--skill NAME` or `--all-skills` after\nreview. Bare adopt deliberately refuses a night containing fan-out rows.\n\nActions are `status`, `harvest`, `dry-run`, `run`, `adopt`, `schedule`, and\n`unschedule`.\n\n- Default backend is `mock`, which is deterministic and makes no provider calls.\n- `--backend cursor` uses the user's authenticated Cursor Agent CLI budget for\n  model-driven mining, replay, judging, and reflection.\n- `--source cursor` reads\n  `~/.cursor/projects/<workspace>/agent-transcripts/*/*.jsonl`.\n- `--cursor-home PATH` overrides the Cursor home used for harvesting.\n- `--scope invoked` selects the current workspace; `--scope all` includes every\n  Cursor workspace.\n- `--cursor-path PATH` or `SKILLOPT_SLEEP_CURSOR_PATH` selects a non-default\n  `cursor-agent` executable.\n- `--model NAME` or `SKILLOPT_SLEEP_CURSOR_MODEL` overrides the Cursor model.\n- Check model identifiers with `cursor-agent --list-models`; when cost matters,\n  verify the billed variant in Cursor's usage reporting.\n- Keep live runs bounded with `--max-sessions`, `--max-tasks`, and `--progress`.\n- A held-out gain is evidence for that run, not a promise of general improvement.\n\nThe first harvest uses a 72-hour lookback. Use `--lookback-hours N` for a wider\ninitial window or `--lookback-hours 0` for all available history. A stateful\n`run`, including a no-task run, records a harvest checkpoint; later runs use the\ncheckpoint rather than the initial lookback. Inspect counts with `harvest` or\n`dry-run` before the first real run because those actions do not advance state.\n\nAvailable backends are:\n\n- `mock` - deterministic, with no provider calls (default);\n- `cursor` - the authenticated Cursor Agent CLI;\n- `claude` - the authenticated Claude CLI;\n- `codex` - the authenticated Codex CLI;\n- `copilot` - the authenticated GitHub Copilot CLI;\n- `handoff` - prompt/answer files for an interactive agent session;\n- `azure_openai` - the configured Azure OpenAI endpoint.\n\nSkillOpt reads the target skill and inserts its text into replay prompts; it does\nnot invoke the file as a native Cursor skill. Ordinary Cursor backend calls run\nin a new empty temporary workspace in read-only Ask mode. File reads, file\nwrites, and MCP tools are denied. `--project` controls harvesting, target files,\nstate, and staging; it is not the Cursor Agent execution workspace.\n\nCursor tool-aware replay is temporarily disabled pending live Cursor\npermission-boundary validation. A task containing a `tool_called` check fails\nnonzero before Agent mode starts. The failed replay does not add a cache entry,\nstage, adopt, persist state, or advance the harvest checkpoint. Use another\nbackend for those tasks. Do not claim that repository- or tool-dependent\nbehavior was validated. The current engine does not implement a fresh-worktree\nreplay for Cursor.\n\nA real-backend `dry-run` still makes provider calls; it only suppresses staging.\nSession and task limits are workload bounds, not hard limits on calls, tokens,\ntime, or money. Start with small limits.\n\n## Reviewable data path\n\nCursor harvesting retains user/assistant text, tool names, and explicit turn\nerrors while excluding raw tool arguments, tool outputs, and non-message\nrecords. Known secret-shaped strings are redacted, but pattern-based redaction\ncannot guarantee that a transcript is safe to send to a provider.\n\nFor sensitive sessions, export tasks before any real-backend replay:\n\n```bash\nTARGET_SKILL=.cursor/skills/skillopt-sleep-learned/SKILL.md\nskillopt-sleep harvest --project \"$(pwd)\" --source cursor \\\n  --target-skill-path \"$TARGET_SKILL\" \\\n  --max-sessions 5 --max-tasks 3 --output reviewed-tasks.json\n```\n\nInspect and redact the file, then set its top-level `\"reviewed\"` field to\n`true`. Only then run:\n\n```bash\nskillopt-sleep dry-run --project \"$(pwd)\" --backend cursor \\\n  --tasks-file reviewed-tasks.json --progress --json\n```\n\nReal backends reject task files that remain unreviewed. Never include raw\ntranscripts, credentials, secrets, or sensitive task content in messages,\ncommits, or generated summaries.\n\n`gate_no_regression` is a config-only safeguard in\n`~/.skillopt-sleep/config.json`. It defaults to `false`; set it to `true` to\nreject a candidate when any validation task's configured gate score decreases.\n\n## Scheduling\n\nScheduling is opt-in. The scheduler persists project, backend, time, and the\noptional auto-adopt flag, but not `--source`, Cursor path/home/model overrides,\nor `--target-skill-path`. Before scheduling a Cursor cycle, set at least these values in\n`~/.skillopt-sleep/config.json`:\n\n```json\n{\n  \"transcript_source\": \"cursor\",\n  \"target_skill_path\": \".cursor/skills/skillopt-sleep-learned/SKILL.md\",\n  \"backend\": \"cursor\"\n}\n```\n\nThen run:\n\n```bash\nskillopt-sleep schedule --project \"$(pwd)\" --backend cursor --hour 3 --minute 17\nskillopt-sleep unschedule --project \"$(pwd)\"\n```\n\nThe scheduler uses cron on Unix and Task Scheduler on Windows. Scheduled runs\nstage proposals by default. Use `--auto-adopt` only when the user has explicitly\nrequested unattended adoption.\n\n## Report results\n\nFor `dry-run` and `run`, report:\n\n- session and task counts;\n- held-out baseline and candidate scores;\n- gate action and accepted/rejected edit counts;\n- exact proposed edits;\n- staging directory, when one was created.\n\nRead staged `report.md` before summarizing a run. Offer adoption only after the\nuser reviews an accepted proposal that is still staged. Never claim broad\nimprovement from one run.\n\n## Hard rules\n\n- Harvest is read-only. Never edit Cursor transcript files.\n- Never hand-edit the target skill or `CLAUDE.md` as a substitute for adoption.\n- Do not run a real backend on sensitive content without confirming its data\n  boundary or using the reviewed-task workflow.\n- Do not add a session-end hook or imply that installing this plugin schedules\n  anything.\n- Show validation evidence before recommending adoption.\n- Treat generated edits as proposals, not as source of truth.\n\n<!-- File: plugins/dsh/skills/skillopt-sleep/SKILL.md (Tokens: ~1472 | Category: anthropic-skill) -->\n---\nname: skillopt-sleep\ndescription: \"Use when the user wants the dsh agent to self-improve from past usage, asks about a nightly/offline 'sleep' or 'dream' cycle, skill/memory consolidation, or says things like 'make my agent better the more I use it', 'review my past sessions', 'learn my preferences', 'consolidate what you learned', 'run the sleep cycle', or wants to schedule background self-optimization. Drives the skillopt_sleep engine through the skillopt_* tools: harvest past sessions -> mine recurring tasks -> replay via a selected backend -> consolidate validated skills behind a held-out gate.\"\n---\n\n# SkillOpt-Sleep: usage-driven self-evolution for the dsh agent\n\nSkillOpt-Sleep is Microsoft's [SkillOpt](https://github.com/microsoft/SkillOpt)\ndeployment-time companion engine: it reviews your past sessions (harvest), mines\nrecurring tasks (mine), replays them through a selected backend (replay), and\nconsolidates what it learns into skill documents behind a **held-out validation\ngate** (consolidate).\n\nThis skill drives the engine through the 7 `skillopt_*` tools exposed by the\ndsh-skillopt plugin. The default `mock` backend makes no model calls, which is\nuseful for verifying the plumbing; a real backend consumes your API budget.\n\n## When to use\n\n- \"make my agent better the more I use it\" / \"learn my preferences across sessions\"\n- a one-off **offline self-evolution / sleep / dream** run (immediate or scheduled)\n- review past sessions/trajectories and distill recurring tasks\n- consolidate feedback into `AGENTS.md` / `SKILL.md` / managed skills\n- schedule (cron) the cycle, or adopt a staged proposal\n\n## The cycle (six stages)\n\n1. **Harvest** — read-only scan of supported local session records → digests\n2. **Mine** — digests → recurring task records (intent + outcome labels + checkable refs)\n3. **Replay** — re-run tasks under the current skill+memory with the selected backend → (hard, soft) scores\n4. **Consolidate** — reflect on failures → propose bounded edits → **validation gate** on a held-out slice (default: accept only on strict improvement)\n5. **Stage** — write accepted proposals to `<project>/.skillopt-sleep/staging/<timestamp>/`. **Live files are unchanged.** A rejected run still has a report but no proposal files.\n6. **Adopt** — explicit (or operator-configured `--auto-adopt`) copies staged files over live ones, backing up first.\n\n## Driving it\n\nPrefer the tools over hand-editing files:\n\n| Tool | Behavior |\n|---|---|\n| `skillopt_status` | state, engine availability, latest staged proposal & report |\n| `skillopt_dry_run` | full preview (harvest+mine+replay), stages nothing |\n| `skillopt_run` | full cycle, stages a proposal (live files unchanged by default) |\n| `skillopt_adopt` | apply latest staged proposal (with backup) — the live-change boundary |\n| `skillopt_harvest` | read-only show/export of mined tasks |\n| `skillopt_schedule` / `skillopt_unschedule` | install/remove the nightly cron entry for this project |\n\nTypical flow:\n\n```text\n# 1. check state (default mock backend, zero cost)\nskillopt_status\n\n# 2. preview the cycle\nskillopt_dry_run project=<dir> source=<claude|codex|…>\n\n# 3. real run (consumes the selected backend's API budget)\nskillopt_run project=<dir> backend=<codex|claude|…> preferences=\"Prefer pytest; keep commits imperative.\"\n\n# 4. review the report, then adopt\nskillopt_adopt project=<dir>\n\n# 5. schedule nightly at 03:17\nskillopt_schedule project=<dir> hour=3 minute=17 backend=<codex>\n```\n\n## Parameters\n\n| Parameter | Default | Meaning |\n|---|---|---|\n| `project` | config or cwd | project directory to evolve |\n| `backend` | `mock` | `mock\\|claude\\|codex\\|copilot\\|cursor\\|pi\\|opencode\\|handoff\\|azure_openai` (mock = no model calls) |\n| `source` | config | transcript source: `claude\\|codex\\|copilot\\|cursor\\|pi\\|opencode\\|auto` |\n| `model` | backend default | replay model override |\n| `maxTasks` | 40 | mined-task cap |\n| `preferences` | empty | house rules for the reflection prior (e.g. \"always use async/await\") |\n\n## Configuration (cordis.yml / bundle patch)\n\n```yaml\n- insert:\n    - id: skillopt\n      name: './src/index.js'\n      config:\n        backend: codex\n        project: /path/to/project\n        preferences: 'Always use async/await'\n        # auto-adopt is OPERATOR-ONLY — the model cannot set it\n        autoAdopt: false\n```\n\nAdvanced engine keys go in `~/.skillopt-sleep/config.json`:\n`gate_mode` (on/off), `gate_metric` (hard/soft/mixed), `gate_no_regression`,\n`dream_rollouts`, `recall_k`, `evolve_memory` / `evolve_skill`.\n\n## Hard rules\n\n- **Never** hand-edit `AGENTS.md` / `SKILL.md` around `skillopt_adopt`; let the\n  engine's explicit adopt (or operator-configured `--auto-adopt`) apply the\n  staging manifest, backing up live files first.\n- Harvest is read-only; `mock` replay has no side effects.\n- Real backends send truncated transcript excerpts and derived tasks to the\n  selected provider for mining/replay/judging/reflection. For sensitive\n  sessions, export tasks first (`skillopt_harvest output=<file>`), redact, set\n  the top-level `\"reviewed\"` to `true`, then replay with `--tasks-file`; real\n  backends refuse unreviewed task files.\n- Show the user the **held-out baseline → candidate** score and the exact\n  proposed edits before suggesting adoption. Evidence before adoption.\n\n## Validate / demo (no API spend)\n\n```bash\npip install skillopt\npython -m skillopt_sleep.experiments.run_experiment --persona researcher --assert-improves\n```\n\nDeterministic synthetic demo: the score rises and the gate blocks a regression.\nIt validates the mechanism, not effectiveness on your own tasks.\n\nSee the [SkillOpt-Sleep docs](https://github.com/microsoft/SkillOpt/tree/main/docs/sleep)\nfor recorded results and limitations.\n\n<!-- File: plugins/openclaw/SKILL.md (Tokens: ~1096 | Category: anthropic-skill) -->\n---\nname: skillopt-sleep\ndescription: Reference-only OpenClaw adaptation of SkillOpt-Sleep. Use it to study or port the contributed DeepSeek wrapper, not as a ready-to-run installation.\n---\n\n# SkillOpt-Sleep OpenClaw reference adaptation\n\nThis directory is a contributed **reference**, not a supported, plug-and-play\nOpenClaw integration. It illustrates one way to connect the shared\n`skillopt_sleep` cycle to a custom DeepSeek Chat Completions backend and a set of\nenvironment-specific task fixtures.\n\nDo not run or schedule the files unchanged. Several scripts and the sample\nconfiguration preserve assumptions from the contributor's original machine,\nand parts of the wrapper have not yet been ported to the current shared-engine\ninterfaces. Start with the directory's [README.md](README.md), which is the\nauthoritative status and adaptation guide.\n\n## What is included\n\n- `skillopt_sleep_openclaw.py` — a contributed DeepSeek backend prototype. It\n  also contains an Ollama embedding helper, but that helper is not wired into\n  the current shared sleep cycle.\n- `run_sleep.py` — a custom cycle wrapper with environment-specific paths and a\n  backend-registration shim.\n- `slash_sleep.py` — an experimental command helper written for an older\n  staging-manifest shape.\n- `run_sleep_cron.sh` — a machine-specific category runner, not a portable cron\n  installer.\n- `config.json` — a sample configuration, not a set of guaranteed or enforced\n  runtime limits.\n- `tests/*.json` — example task fixtures from one environment, not a universal\n  OpenClaw benchmark.\n\n## Known porting gaps\n\nBefore treating this as an integration, a maintainer must at least:\n\n1. Replace every absolute workspace, repository, state, skill, log, and task\n   path with explicit user configuration.\n2. Update the custom backend factory to the current `get_backend` call contract,\n   including the project directory, and update its backend methods and edit\n   records to the current protocol.\n3. Replace the experimental adoption logic with the current staging manifest\n   and `skillopt_sleep.staging.adopt` behavior. Current staging artifacts use\n   `proposed_SKILL.md` / `proposed_CLAUDE.md`, `manifest.json`, and report files;\n   they do not expose the old `manifest.proposed_skill` field.\n4. Decide how real OpenClaw transcripts are converted into a supported session\n   format. Pointing `claude_home` at an arbitrary agent directory does not by\n   itself make its files Claude Code-compatible JSONL.\n5. Build scheduling around the adapted wrapper. The shared scheduler launches\n   the shared CLI; it does not automatically preserve this custom backend or\n   its category task-file flow.\n6. Add isolated end-to-end tests for dry-run, accepted/rejected gates, staging,\n   adoption and backup, credential failure, and scheduled execution.\n\nUntil those gaps are resolved, use the supported shared\n`python -m skillopt_sleep` CLI with `--backend mock` to test SkillOpt-Sleep itself,\nand treat this directory only as source material for a future OpenClaw port.\n\n## Shared-engine features are not wrapper features\n\nAt this revision the supported shared CLI backends are `mock`, `claude`,\n`codex`, `copilot`, `handoff`, and `azure_openai`; the\n[plugin integration reference](../README.md#supported-cli-surface) is the\nauthoritative list. The shared engine can consolidate a selected skill and\nproject `CLAUDE.md` memory (controlled by `evolve_skill` and `evolve_memory`),\nand its `schedule` / `unschedule` actions manage shared-engine cron entries.\nThose capabilities do **not** make the custom OpenClaw wrapper portable: the\nshared scheduler will not invoke the prototype backend or its category\nfixtures. Use the shared documentation for those features, not this reference\nSKILL.\n\n## Data and credential boundary\n\nThe prototype DeepSeek backend sends task, skill, memory, response, rubric, and\nreflection content to its configured Chat Completions endpoint. Its source also\ncontains a helper that can send text to an Ollama service if a future port wires\nthat helper into the cycle. Neither path should be assumed to remove every\nsecret or private detail.\n\nBefore any port is tested with real data:\n\n- use isolated, synthetic or explicitly reviewed task files;\n- replace sample business names, personal references, URLs, and machine paths;\n- load credentials through the operator's secret-management mechanism;\n- verify TLS and retention policy for every remote endpoint; and\n- inspect all staged artifacts before adoption.\n\nThe bundled fixtures are examples only. Their scores and any old cost estimates\ndo not establish effectiveness, safety, or a stable nightly price for another\nOpenClaw deployment.\n\n## Further information\n\n- [OpenClaw README](README.md) — current reference status and adaptation checklist\n- [plugin integration reference](../README.md) — supported shared-engine CLI\n  surface and data boundary\n- [SkillOpt-Sleep documentation](../../docs/sleep/README.md) — concepts,\n  results, and limitations\n\nContributions that turn this reference into a portable integration should add\ntests and update all three documents together.\n\n<!-- File: skillopt/envs/alfworld/skills/initial.md (Tokens: ~672 | Category: anthropic-skill) -->\n# ALFWorld Embodied Agent Skill\n\n## Overview\nThis skill guides agents operating in the ALFWorld text-based embodied environment.\nThe agent must complete household tasks by navigating rooms, interacting with objects,\nand using appliances. Actions must be chosen from the admissible action list provided\nat each step.\n\n**Output format**: Always output `<think>...</think>` for reasoning, then `<action>...</action>` for the chosen action.\n\n---\n\n## Task Types\n\n| Type | Goal | Key Steps |\n|------|------|-----------|\n| Pick & Place | Put object X in/on receptacle Y | Find X -> take X -> go to Y -> put X in/on Y |\n| Pick Two & Place | Put two instances of X in/on Y | Find X1 -> take -> place -> find X2 -> take -> place |\n| Examine in Light | Examine object X under desklamp | Find X -> take X -> find desklamp -> use desklamp |\n| Clean & Place | Clean object X and put in/on Y | Find X -> take X -> go to sink -> clean X -> go to Y -> put X |\n| Heat & Place | Heat object X and put in/on Y | Find X -> take X -> go to microwave -> heat X -> go to Y -> put X |\n| Cool & Place | Cool object X and put in/on Y | Find X -> take X -> go to fridge -> cool X -> go to Y -> put X |\n\n---\n\n## General Principles\n\n1. **Decompose the task**: Parse the goal into ordered sub-goals (locate, acquire, transform, deliver). Complete each before moving to the next.\n2. **Systematic exploration**: Search each surface and container exactly once before revisiting. Open closed containers (drawers, cabinets, fridge) before judging them empty.\n3. **Grab immediately**: When a required object is visible and reachable, take it right away before moving elsewhere.\n4. **Transform before placing**: If the task requires cleaning, heating, or cooling, perform the state change at the appropriate appliance before heading to the final destination.\n5. **Direct delivery**: Once holding the transformed (or untransformed) goal object, navigate straight to the target receptacle and place it.\n6. **Track progress**: Maintain an internal count of how many objects still need to be found and placed. Only stop searching when the count reaches zero.\n7. **Avoid loops**: Never repeat the same action more than twice in a row. If stuck, move to a different unexplored location.\n8. **Only choose admissible actions**: Always pick an action from the admissible action list. Do not invent actions.\n\n---\n\n## Common Mistakes to Avoid\n\n- **Revisiting searched locations**: Keep track of which surfaces/containers have been checked; do not re-examine them.\n- **Ignoring visible objects**: If the target object appears in the observation, pick it up immediately.\n- **Skipping state changes**: Do not place an object at the destination without first cleaning/heating/cooling it when required.\n- **Premature termination**: Do not stop the episode until all goal conditions are verified as met.\n- **Action loops**: Repeatedly toggling or examining the same object wastes steps. Move on to new locations instead.\n\n<!-- File: skillopt/envs/docvqa/skills/initial.md (Tokens: ~99 | Category: anthropic-skill) -->\n# DocVQA Skill\n\n## Visual Evidence Discipline\n- Read the document carefully before answering.\n- Prefer the smallest exact text span that answers the question.\n- When several nearby strings look similar, choose the one whose surrounding labels or layout best match the question.\n\n## Exact Answer Discipline\n- Copy names, numbers, and dates exactly from the document whenever possible.\n- Prefer direct extraction over paraphrase.\n- Before finalizing, compare the answer against nearby alternatives and keep the best-supported exact span.\n\n<!-- File: skillopt/envs/livemathematicianbench/skills/initial.md (Tokens: ~202 | Category: anthropic-skill) -->\n# Live Mathematical MCQ Heuristics\n\n## Option Comparison\n- Compare all options before committing. The correct choice is often the strongest statement justified by the question, while nearby distractors are weaker, overstrong, or miss an equality case.\n- Track exact quantifiers such as \"there exists\", \"for every\", \"if and only if\", and \"exactly when\".\n\n## Theorem-Level Precision\n- Check whether an option weakens the conclusion by dropping a characterization, equality clause, or full equivalence.\n- Check whether an option overstates the theorem by upgrading regularity, removing scale restrictions, or changing an existential statement into a universal one.\n\n## Hypotheses\n- Verify the hypotheses and domain carefully. Distractors often keep the theorem shape but alter the required assumptions.\n- Pay close attention to equality cases, extremal conditions, and whether a result applies to the full family or only a restricted subfamily.\n\n## Final Answer\n- Output the final answer as the single option label only.\n\n<!-- File: skillopt/envs/officeqa/skills/initial.md (Tokens: ~171 | Category: anthropic-skill) -->\n# OfficeQA Skill\n\n## Retrieval Discipline\n- Start by narrowing to the most likely candidate file before reading long passages.\n- Prefer targeted search terms that name the exact entity, period, measure, or table concept from the question.\n- After a promising match, read only a small surrounding span and verify it matches the requested year, basis, and unit.\n\n## Evidence Discipline\n- Extract the exact value from the retrieved text before doing any arithmetic.\n- Keep track of each operand's period, unit, and semantic role so nearby proxy values are not mixed in.\n- If the question asks for a transformed or derived quantity, compute only after confirming every operand.\n\n## Final Answer Discipline\n- Return the final answer only after one last consistency check against the retrieved evidence.\n- Copy the final answer from a checked value, not from an unverified intermediate guess.\n\n<!-- File: skillopt/envs/searchqa/skills/initial.md (Tokens: ~21 | Category: anthropic-skill) -->\n# Question Answering Skill\n\n(No learned rules yet. Rules will be added through the reflection process.)\n\n<!-- File: skillopt/envs/spreadsheetbench/skills/initial.md (Tokens: ~369 | Category: anthropic-skill) -->\n# Spreadsheet Manipulation Skill (xlsx)\n\n## Overview\nThis skill guides agents in manipulating Excel (.xlsx) spreadsheets using Python.\n\n**Primary libraries**: `openpyxl` (structure-preserving read/write), `pandas` (data transformation).\nNever use any other third-party libraries.\n\n---\n\n## Common Workflow\n\n1. **Explore** the input file: list sheets, inspect headers, check dimensions.\n2. **Write `solution.py`** with `INPUT_PATH` and `OUTPUT_PATH` defined at the top.\n3. **Execute** `python solution.py` and verify the output file was created.\n4. **Confirm** the target cells/range contain the expected values.\n\n---\n\n## Library Selection\n\n| Use case | Library |\n|----------|---------|\n| Preserve formulas, formatting, named ranges | `openpyxl` |\n| Bulk data transformation, aggregation, sorting | `pandas` → write back with `openpyxl` |\n| Simple cell read/write | `openpyxl` |\n\n**Warning**: `pandas.to_excel()` silently destroys existing formulas and named ranges.\nWhen writing back to a spreadsheet that contains formulas, always use `openpyxl.save()`.\n\n---\n\n## solution.py Template\n\n```python\nimport openpyxl\nimport pandas as pd\n\nINPUT_PATH  = \"...\"   # set to the actual input path\nOUTPUT_PATH = \"...\"   # set to the actual output path\n\nwb = openpyxl.load_workbook(INPUT_PATH)\nws = wb.active  # or wb[\"SheetName\"]\n\n# --- perform manipulation ---\n\nwb.save(OUTPUT_PATH)\n```\n\n---\n\n## Output Requirements\n\n- Save the result to `OUTPUT_PATH`.\n- Do not hardcode row counts or column letters — iterate over actual rows in the workbook.\n- Preserve sheets and cells not mentioned in the instruction.\n\n<!-- File: .cursor-plugin/marketplace.json (Tokens: ~126 | Category: marketplace) -->\n{\n  \"name\": \"skillopt\",\n  \"owner\": {\n    \"name\": \"Yifan Yang\",\n    \"email\": \"yifanyang@microsoft.com\"\n  },\n  \"metadata\": {\n    \"description\": \"Official SkillOpt plugins for usage-driven, validation-gated agent improvement.\"\n  },\n  \"plugins\": [\n    {\n      \"name\": \"skillopt-sleep\",\n      \"source\": \"plugins/cursor\",\n      \"description\": \"Review recent Cursor sessions, replay recurring work, and stage validation-gated improvements to a Cursor skill for explicit adoption.\"\n    }\n  ]\n}\n\n<!-- File: plugins/claude-code/.claude-plugin/marketplace.json (Tokens: ~291 | Category: marketplace) -->\n{\n  \"$schema\": \"https://anthropic.com/claude-code/marketplace.schema.json\",\n  \"name\": \"skillopt-sleep\",\n  \"description\": \"SkillOpt-Sleep: give your local Claude agent a nightly sleep cycle that reviews past sessions and consolidates validated memory + skills.\",\n  \"owner\": {\n    \"name\": \"Yifan Yang\",\n    \"email\": \"yifanyang@microsoft.com\"\n  },\n  \"plugins\": [\n    {\n      \"name\": \"skillopt-sleep\",\n      \"description\": \"Nightly offline self-evolution: harvest your past Claude Code sessions, replay recurring tasks on your own API budget, and consolidate what the agent learns into validated CLAUDE.md memory and SKILL.md skills, behind a held-out gate, staged for your review. Synthesizes SkillOpt (validation-gated skill optimization), Claude Dreams (offline memory consolidation), and agent sleep/consolidation.\",\n      \"author\": {\n        \"name\": \"Yifan Yang\"\n      },\n      \"category\": \"productivity\",\n      \"source\": {\n        \"source\": \"git-subdir\",\n        \"url\": \"https://github.com/microsoft/SkillOpt.git\",\n        \"path\": \"plugins/claude-code\",\n        \"ref\": \"main\"\n      },\n      \"homepage\": \"https://github.com/microsoft/SkillOpt\"\n    }\n  ]\n}\n\n<!-- File: plugins/claude-code/.claude-plugin/plugin.json (Tokens: ~236 | Category: plugin-manifest) -->\n{\n  \"name\": \"skillopt-sleep\",\n  \"description\": \"Give your local Claude agent a nightly 'sleep cycle': it reviews your past sessions offline, replays recurring tasks on your own API budget, and consolidates what it learns into validated memory (CLAUDE.md) and skills (SKILL.md) so it gets better the more you use it. Synthesizes SkillOpt (validation-gated skill optimization), Claude Dreams (offline memory consolidation), and agent sleep/consolidation.\",\n  \"version\": \"0.1.0\",\n  \"author\": {\n    \"name\": \"Yifan Yang\",\n    \"email\": \"yifanyang@microsoft.com\"\n  },\n  \"homepage\": \"https://github.com/microsoft/SkillOpt\",\n  \"repository\": \"https://github.com/microsoft/SkillOpt\",\n  \"license\": \"MIT\",\n  \"keywords\": [\n    \"skillopt\",\n    \"self-improvement\",\n    \"memory-consolidation\",\n    \"dreams\",\n    \"sleep\",\n    \"skills\",\n    \"continual-learning\",\n    \"offline-optimization\"\n  ]\n}\n\n<!-- File: plugins/claude-code/README.md (Tokens: ~2680 | Category: plugin-manifest) -->\n# SkillOpt-Sleep (Claude Code plugin)\n\n> Give your local Claude agent a **sleep cycle**. Every night it reviews your\n> past sessions offline, replays your recurring tasks on your own API budget,\n> and consolidates what it learns into **validated** memory (`CLAUDE.md`) and\n> skills (`SKILL.md`). Your agent gets better the more you use it — no\n> model-weight training.\n\nSkillOpt-Sleep is the **deployment-time** companion to\n[SkillOpt](https://github.com/microsoft/SkillOpt). SkillOpt trains a skill\noffline on a benchmark; SkillOpt-Sleep applies the same discipline to *your own\ndaily usage*: bounded text edits, accepted only through a held-out validation\ngate, with rejected candidates recorded in the cycle report for review.\n\nIt synthesizes three ideas:\n\n| Idea | Contribution |\n|---|---|\n| **SkillOpt** | skill/memory = trainable text; bounded add/delete/replace edits; **held-out gate** keeps only changes that help. |\n| **Claude Dreams** | offline consolidation over past sessions; input never mutated; output **reviewed then adopted**. |\n| **Agent sleep** | periodic offline replay turns short-term episodes into long-term skill. |\n\n## What it does (one \"night\")\n\n```\nharvest ~/.claude transcripts → mine recurring tasks → replay offline\n   → consolidate (reflect → bounded edit → GATE) → stage proposal → (you) adopt\n```\n\nNothing live is modified until **you** run `/skillopt-sleep adopt` (the Dreams \"review,\nthen adopt or discard\" contract). Every adopt backs up the prior file first.\n\n## Install\n\n**Requirements:** Python ≥ 3.10. A real CLI backend additionally requires its\ncorresponding `claude` or `codex` executable on `PATH` and authenticated.\n\n```bash\n# 1) get the code (the plugin ships inside the SkillOpt repo)\ngit clone https://github.com/microsoft/SkillOpt.git\ncd SkillOpt\n\n# 2) add the plugin to Claude Code as a local marketplace\n/plugin marketplace add ./plugins/claude-code\n/plugin install skillopt-sleep@skillopt-sleep\n\n# 3) verify\n/skillopt-sleep status\n```\n\nThe plugin's bundled runner (`scripts/sleep.sh`) auto-selects a Python ≥ 3.10\ninterpreter and calls the `skillopt_sleep` engine. A source checkout needs no\n`pip install`. If the marketplace cache does not contain a usable source tree,\nthe shared runner falls back first to a `skillopt-sleep` executable on `PATH`\n(including `uv tool`/`pipx` installs), then to an importable Python module. Use\n`uv tool install skillopt` or `pip install skillopt` for that fallback.\n\n> **Version note.** This page tracks `main`. PyPI 0.2.0 provides the base Sleep\n> CLI, but handoff mode, `--preferences`, multi-skill fan-out, and reviewed\n> subset adoption require a source checkout from `main` until the next release.\n\n## Quick start\n\n```bash\n# from inside any project you use with Claude Code:\n/skillopt-sleep dry-run     # preview what it would learn; no changes staged\n/skillopt-sleep run         # full cycle: stages a reviewed proposal (still no live edits)\n/skillopt-sleep status      # see history + the latest staged proposal\n/skillopt-sleep adopt --legacy       # apply the reviewed managed proposal\n# Fan-out nights instead use: adopt --skill NAME (repeatable) or --all-skills\n\n/skillopt-sleep-handoff run # same cycle, but THIS session answers the model calls\n                            # (no claude -p subprocess, no API key — subscription-friendly)\n```\n\nOr call the engine directly (Python ≥ 3.10):\n\n```bash\npython -m skillopt_sleep run --project \"$(pwd)\" --scope invoked --backend mock\npython -m skillopt_sleep run --project \"$(pwd)\" --backend claude   # real lift via Claude\npython -m skillopt_sleep run --project \"$(pwd)\" --backend codex    # real lift via Codex\n```\n\nDefault backend is **`mock`** — deterministic, no API spend — so you can try the\nplumbing for free. Switch to `--backend claude` or `--backend codex` for\nmodel-driven mining and optimization on your own budget; an accepted gain is\ntask- and model-dependent, not guaranteed.\n\n### Data boundary for real backends\n\nHarvesting `~/.claude` is local and read-only, and the `mock` backend makes no\nprovider calls. A real backend sends truncated transcript excerpts and derived\ntasks to the selected provider for mining, replay, judging, and reflection.\nOutbound prompts are not currently guaranteed to be secret-free. Review your\nsession data and provider policy before using a real backend on a sensitive\nproject; the [shared integration guide](../README.md#data-boundary) describes a\nreviewed task-file workflow.\n\n### Sessions you did not type\n\nHarvest keeps your prompts and drops machine-written transcripts. Three\nenvironment variables extend what counts as machine-written, for the sessions\nClaude Code gives no other tell:\n\n| Variable | Effect |\n|---|---|\n| `SKILLOPT_SLEEP_AGENT_MARKERS` | Comma-separated markers; a session whose **first** prompt contains one is dropped entire. |\n| `SKILLOPT_SLEEP_NEG_FEEDBACK` / `SKILLOPT_SLEEP_POS_FEEDBACK` | Extra comma-separated phrases, in any language, that count as you rejecting or approving the previous answer. |\n\nThe case they exist for is a local hook that summarises the previous session on\na timer. Its runs are single-turn, they are frequent enough to fill\n`--max-sessions` and starve the night of your real sessions, and in the desktop\napp they carry `entrypoint: \"claude-desktop\"` like interactive ones — so neither\n`entrypoint` nor a replay marker identifies them. Quote the hook's first line:\n\n```bash\nexport SKILLOPT_SLEEP_AGENT_MARKERS=\"Below is a conversation log from a coding session\"\n```\n\nA template you cannot quote is covered only after you opt in: a single-turn\nsession sharing its first 120 characters of prompt with three others in the same\nharvest window is dropped before the session cap is applied once\n`SKILLOPT_SLEEP_REPEAT_MIN_SESSIONS` is set (default `0`, off; `3` is the usual\nchoice). Recurrence is not proof of who wrote a prompt — three human requests\nagainst one long shared checklist look the same — so the default keeps every\nsession and `--max-sessions` still bounds how many transcripts are read. A\nsession with a follow-up user turn is never matched, and neither is a prompt\nshorter than the prefix — your own one-shot requests repeat entirely rather than\nsharing a long boilerplate header.\n\n`/skillopt-sleep harvest` and the progress line of a `run` / `dry-run` report\nwhat was dropped, so a thin night is explainable:\n`harvest done: sessions=120 (skipped: 297 repeated-template sessions, 2 past the session cap)`.\nFull reference: [the sleep guide](../../docs/sleep/README.md#harvest-filters-environment).\n\n### Handoff mode (session answers the model calls)\n\n`--backend handoff` runs the cycle without any model subprocess: the engine\nexecutes the deterministic stages and writes every model call it needs to\n`.skillopt-sleep-handoff/PROMPTS.md` + `pending.json` (exit code 3). You (or\nthe `/skillopt-sleep-handoff` command, which automates the loop with isolated\nfresh-context subagents) write each raw answer to `answers/<id>.md` and re-run\nthe same command; it resumes from the answers and either finishes or stages\nthe next batch. Typically 3–6 rounds per night.\n\n```bash\npython -m skillopt_sleep run --backend handoff --project \"$(pwd)\"\n# ... answer .skillopt-sleep-handoff/PROMPTS.md into answers/<id>.md ...\npython -m skillopt_sleep run --backend handoff --project \"$(pwd)\"   # resume\n```\n\nAnswer every prompt in a **fresh context** — a session that has already seen\nthe mined tasks and their references would contaminate the held-out gate.\nDetails: [the plugins README](../README.md#handoff-backend).\n\n## Does it actually improve? (real models, public benchmark)\n\nSkillOpt-Sleep is validated against [gbrain-evals](https://github.com/garrytan/gbrain-evals)'\npublic `skillopt-v1` suite — the same benchmark gbrain scores its own skill\noptimizer against. We take a deliberately **deficient** skill and run one sleep\nnight; held-out scoring is done by a local rule judge (no judge-API, no way to\ngrade its own homework).\n\n| Backend | Seed | Held-out before → after | Nights |\n|---|---|---|---|\n| **Claude (Haiku 4.5)** | brief-writer | **0.00 → 1.00** | 1 |\n| **Codex** | brief-writer | **0.00 → 1.00** | 2 |\n\nBoth took a brief-writer with no risks section / no confidence level and, within\n1–2 nights, proposed gated edits that lifted the held-out score to perfect —\ninto the protected `LEARNED` block, nothing else touched. The Codex 2-night\ntrace even shows the optimizer **diagnosing its own residual failure** and\nadding a meta-rule to fix it. See the recorded results and limitations in\n[`docs/sleep/RESULTS.md`](../../docs/sleep/RESULTS.md).\n\nReproduce:\n\n```bash\ngit clone https://github.com/garrytan/gbrain-evals /tmp/gbrain-evals\npython -m skillopt_sleep.experiments.run_gbrain --backend claude --model haiku \\\n  --seeds brief-writer --data-root /tmp/gbrain-evals/eval/data/skillopt-v1 \\\n  --nights 1 --limit-replay 3 --limit-holdout 3\npython -m skillopt_sleep.experiments.run_gbrain --backend codex \\\n  --seeds brief-writer --data-root /tmp/gbrain-evals/eval/data/skillopt-v1 \\\n  --nights 1 --limit-replay 3 --limit-holdout 3\n```\n\n## Deterministic proof (no API, no keys)\n\n```bash\npython -m skillopt_sleep.experiments.run_experiment --persona researcher --assert-improves\npython -m skillopt_sleep.experiments.run_experiment --persona programmer  --assert-improves\n```\n\nEach prints the held-out score rising from baseline toward 1.0 as the gate\naccepts the general rules your tasks need, and confirms the gate **rejects** an\ninjected harmful edit. Context for the measured experiments is in\n[`docs/sleep/RESULTS.md`](../../docs/sleep/RESULTS.md).\n\n## Schedule it nightly\n\n```bash\n/skillopt-sleep schedule --hour 3 --minute 17\n/skillopt-sleep unschedule\n```\n\nThe built-in scheduler creates a managed cron entry and logs under the project.\nThe scheduled run stages proposals unless `--auto-adopt` is explicitly selected.\n\n## Safety\n\n- **Read-only** harvest of `~/.claude`. `mock` replay has no side effects.\n- Proposals are **staged**, never auto-applied (unless you opt in with `--auto-adopt`).\n- Every adopt writes a backup under the staging dir's `backup/`.\n- `--max-sessions` and `--max-tasks` bound work. `max_tokens_per_night` in\n  `~/.skillopt-sleep/config.json` stops a night from starting new steps once its\n  token count reaches the budget; a started step finishes, so it is not a hard\n  cap, and there is no wall-clock budget.\n- Real backends share truncated session/task content with the selected provider;\n  do not assume outbound prompts have been fully redacted.\n\n## Status\n\nThe engine, deterministic experiment, Claude/Codex CLI backends, handoff mode,\nand staged adoption flow are implemented. Advanced experiment-harness flags are\nnot automatically available on the nightly CLI; see the\n[shared integration reference](../README.md#supported-cli-surface).\n\n<!-- File: plugins/codex/README.md (Tokens: ~1334 | Category: plugin-manifest) -->\n# SkillOpt-Sleep — Codex integration\n\nGive your **Codex** agent a nightly **sleep cycle**: it reviews past sessions\noffline, replays your recurring tasks on your own Codex budget, and consolidates\nwhat it learns into validated memory + skills behind a held-out gate. Same engine\nas the Claude Code plugin (`skillopt_sleep`), wrapped for Codex.\n\n> **Verified on Codex:** on the public\n> [gbrain-evals](https://github.com/garrytan/gbrain-evals) `skillopt-v1`\n> benchmark, a deliberately deficient skill goes **0.00 → 1.00** on a held-out\n> set with the Codex backend (incl. the tool-use seed via a real tool loop).\n> See the recorded results and limitations in\n> [`docs/sleep/RESULTS.md`](../../docs/sleep/RESULTS.md).\n\n## What Codex supports (and what we use)\n\nCodex (`@openai/codex`) extends via **`AGENTS.md`** instructions, **skills** at\n`~/.agents/skills/<name>/SKILL.md`, and plugins that can distribute skills.\nCustom prompts are deprecated in Codex, so this integration is skill-first: the\ninstalled `skillopt-sleep` skill contains the launch commands and operating\nrules. The shared runner remains a plain shell entrypoint that the skill calls.\n\n## Install\n\nOn Linux/macOS:\n```bash\ngit clone https://github.com/microsoft/SkillOpt.git\ncd SkillOpt\nbash plugins/codex/install.sh          # installs the skill\nexport SKILLOPT_SLEEP_REPO=\"$(pwd)\"    # so the runner is found from anywhere\n```\n\nOn Windows (PowerShell):\n```powershell\ngit clone <repo-url> SkillOpt-Sleep\ncd SkillOpt-Sleep\npowershell -File plugins/codex/install.ps1\n[System.Environment]::SetEnvironmentVariable(\"SKILLOPT_SLEEP_REPO\", \"$(pwd)\", \"User\")\n```\n\nIf a previous install created `~/.codex/prompts/sleep.md`, the installer moves\nthat deprecated prompt aside with a `.skillopt-legacy*.bak` suffix.\n\nRequires Python ≥ 3.10 and the `codex` CLI on PATH.\n\n## Use\n\nMention `$skillopt-sleep` where Codex supports explicit skill mentions, or ask\nCodex in natural language:\n\n```text\nUse the skillopt-sleep skill to run status for this project.\nUse the skillopt-sleep skill to run a dry-run for this project.\nUse the skillopt-sleep skill to run the full cycle for this project with the Codex backend.\nUse the skillopt-sleep skill to inspect status, then adopt the reviewed managed\nproposal or an explicit pending skill subset.\n```\n\nOr call the engine directly:\n\n```bash\npython -m skillopt_sleep dry-run --project \"$(pwd)\" --source codex --backend mock\npython -m skillopt_sleep run --project \"$(pwd)\" --source codex --backend codex \\\n  --max-sessions 5 --max-tasks 3 --progress\npython -m skillopt_sleep run --project \"$(pwd)\" --source codex --backend codex \\\n  --target-skill-path .agents/skills/example/SKILL.md \\\n  --max-sessions 5 --max-tasks 3 --progress\n```\n\n`--source codex` reads Codex Desktop archived sessions from\n`~/.codex/archived_sessions`. Use `--codex-home /path/to/.codex` to point at a\ndifferent Codex home, or `--source auto` to try Codex archives first and fall\nback to Claude Code transcripts. Default backend is `mock` (no API spend).\n`--backend codex` uses your Codex budget for model-driven optimization; an\naccepted gain is task-dependent, not guaranteed. Bound live runs\nwith `--max-sessions` and `--max-tasks`; add `--progress` because Codex-backed\nmining, replay, and reflection can be slow and otherwise quiet. Use\n`--target-skill-path` to stage/adopt into a repo-scoped Codex skill such as\n`.agents/skills/<name>/SKILL.md`; target runs over-sample mined tasks and\nprefer tasks that match the target skill's path, headings, and content. The\nimplemented main-CLI flags work the same across the shared integrations, and\n`--preferences \"...\"` is available for house rules. Advanced keys such as\n`gate_mode`, `gate_no_regression`, `dream_rollouts`, and `recall_k` belong in the Sleep config; the\nnightly CLI does not expose `--gate`, `--rollouts-k`, token/time-budget, or\noptimizer/target-split flags. See the\n[shared CLI reference](../README.md#supported-cli-surface).\n\nFor privacy-sensitive projects, split the run into reviewable steps:\n\n```bash\npython -m skillopt_sleep harvest --project \"$(pwd)\" --source codex \\\n  --target-skill-path .agents/skills/example/SKILL.md \\\n  --max-sessions 5 --max-tasks 3 \\\n  --output reviewed-tasks.json\n\npython -m skillopt_sleep dry-run --project \"$(pwd)\" --backend codex \\\n  --tasks-file reviewed-tasks.json --progress --json\n```\n\nInspect/redact the JSON and set `\"reviewed\": true` before using a real backend.\n`--tasks-file` skips archive harvest/mining and replays only the reviewed JSON\ntasks; real backends refuse task files still marked `\"reviewed\": false`.\n\nThis review step matters even though the Codex transcript converter removes\nknown secret-shaped strings: pattern-based redaction is not a guarantee. A real\nbackend sends truncated transcript/task content to the selected provider, while\n`--backend mock` makes no provider calls.\n\n## Notes / status\n\n- Codex's `exec` runs shell, so the real-tool-loop replay (e.g. the\n  `tool_called: search` benchmark seed) works natively.\n- This integration no longer installs a `.codex/prompts` slash command. Skills\n  are the reusable Codex workflow surface; mention `skillopt-sleep` explicitly\n  or ask for a sleep/dream/offline self-improvement run and Codex can load the\n  skill.\n\n<!-- File: plugins/copilot/README.md (Tokens: ~1180 | Category: plugin-manifest) -->\n# SkillOpt-Sleep — GitHub Copilot integration\n\nGive **Copilot** (CLI or VS Code) a nightly **sleep cycle** via a tiny **MCP\nserver** that exposes the `skillopt_sleep` engine as tools. MCP is GitHub's\nsupported way to extend Copilot, so this works across Copilot CLI, VS Code, and\nother MCP clients with the same server.\n\n## What's here\n\n| File | Purpose |\n|---|---|\n| `mcp_server.py` | stdlib-only MCP (stdio) server exposing `sleep_*` tools |\n| `mcp-config.example.json` | drop-in MCP server config |\n| `copilot-instructions.snippet.md` | paste into `.github/copilot-instructions.md` |\n\n## Install\n\nRequires Python ≥ 3.10. No third-party packages — the server is pure stdlib.\n\n1. **Register the MCP server.** Add the server to your Copilot MCP config\n   (Copilot CLI: `~/.copilot/mcp-config.json`; VS Code: your MCP settings).\n   Use `mcp-config.example.json` as a template — set `SKILLOPT_SLEEP_REPO` to\n   this repo's path:\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"skillopt-sleep\": {\n         \"command\": \"python3\",\n        \"args\": [\"/abs/path/SkillOpt/plugins/copilot/mcp_server.py\"],\n        \"env\": { \"SKILLOPT_SLEEP_REPO\": \"/abs/path/SkillOpt\" }\n       }\n     }\n   }\n   ```\n\n2. **(Optional) Tell Copilot about it.** Append\n   `copilot-instructions.snippet.md` to your repo's\n   `.github/copilot-instructions.md` so Copilot reaches for the tools when the\n   user asks to \"run the sleep cycle\".\n\n## Use\n\nAsk Copilot things like *\"run the sleep cycle\"*, *\"what did the last sleep\npropose?\"*, *\"adopt the staged sleep proposal\"*. The server exposes seven MCP\ntools: `sleep_status`, `sleep_dry_run`, `sleep_run`, `sleep_adopt`,\n`sleep_harvest`, `sleep_schedule`, and `sleep_unschedule`.\n\nEach tool takes optional `project`, `backend`\n(`mock`/`claude`/`codex`/`copilot`/`handoff`), and `scope` arguments. For\n`sleep_adopt`, first inspect `sleep_status`, then use the adoption controls that\nmatch the reviewed staging manifest:\n\n- `staging` — exact staging directory to adopt instead of the latest night\n- `skills` — array of skill names to adopt; each is passed as one repeated\n  `--skill` argument without shell interpolation\n- `all_skills` — adopt every staged per-skill proposal\n- `legacy` — adopt only the legacy managed `SKILL.md`/`CLAUDE.md` pair\n\nChoose one selection mode (`skills`, `all_skills`, or `legacy`) and do not\ncombine them. A bare `sleep_adopt` remains compatible with legacy-only staging;\nfan-out staging requires an explicit selection.\n\nTool results preserve the engine's `exit_code` in `structuredContent`.\nOrdinary nonzero exits set `isError: true`; exit 3 is the expected\n`handoff_pending` state and is not an MCP tool error. With `json: true`, text\ncontent is the engine's parseable JSON stdout, while diagnostics remain\nseparate in `structuredContent`.\n\nDefault backend is `mock` (no API spend). The `copilot` backend drives the\nGitHub Copilot CLI (`copilot -p ... --output-format json`) and requires the\n`copilot` CLI to be installed and authenticated.\n\nHarvesting is local and read-only, and the default `mock` backend makes no\nprovider calls. A real backend sends truncated transcript excerpts and derived\ntasks to the selected provider. Outbound prompts are not currently guaranteed\nto be secret-free; review sensitive data and provider policy first. See the\n[shared data-boundary guidance](../README.md#data-boundary).\n\nFor speed, the `copilot` backend runs each call against an isolated\n`COPILOT_HOME` with built-in MCP servers and custom instructions disabled, so\nyour user MCP servers (including this project's own) are not spawned per call\n(~5x faster). Override with `SKILLOPT_SLEEP_COPILOT_HOME=<dir>`, pick a model\nwith `SKILLOPT_SLEEP_COPILOT_MODEL`, or set `SKILLOPT_SLEEP_COPILOT_FULL_ENV=1`\nto use your real Copilot environment instead.\n\n## Verify the server directly (no Copilot needed)\n\n```bash\nprintf '%s\\n' \\\n  '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{}}' \\\n  '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\"}' \\\n  | SKILLOPT_SLEEP_REPO=\"$(pwd)\" python3 plugins/copilot/mcp_server.py\n```\nYou should see the server info and all seven `sleep_*` tools.\n\n## Notes / status\n\n- MCP is the stable, official Copilot extension surface, so this is the most\n  portable shared-engine integration (one server → CLI + IDE).\n- The MCP schema exposes the main CLI's implemented controls, including task and\n  session caps, target-skill selection, scheduling, and staged adoption. It does\n  not add experiment-only gate, rollout, token/time-budget, or optimizer/target\n  split flags. See the [shared CLI reference](../README.md#supported-cli-surface).\n\n<!-- File: plugins/copilot/skillopt/README.md (Tokens: ~1209 | Category: plugin-manifest) -->\n# SkillOpt — GitHub Copilot integration\r\n\r\nGive **Copilot** (CLI or VS Code) direct access to the **SkillOpt** research\r\nengine via a tiny **MCP server**. MCP is GitHub's supported way to extend\r\nCopilot, so this works across Copilot CLI, VS Code, and other MCP clients with\r\nthe same server.\r\n\r\nSkillOpt is **validation-gated, text-space skill optimization**: it reflects on\r\nrollouts, makes bounded edits to a skill, and keeps a change only if it improves\r\na held-out validation set. This plugin exposes the repo's training and eval\r\nentry points (`scripts/train.py`, `scripts/eval_only.py`) as Copilot tools.\r\n\r\n> This is the companion to the **SkillOpt-Sleep** plugin (`../mcp_server.py`,\r\n> `sleep_*` tools). Sleep evolves a *local coding agent* from your past\r\n> sessions; this server drives the *research* training/eval loops on the\r\n> benchmark configs in [`../../../configs`](../../../configs).\r\n\r\n## What's here\r\n\r\n| File | Purpose |\r\n|---|---|\r\n| `mcp_server.py` | stdlib-only MCP (stdio) server exposing `skillopt_*` tools |\r\n| `mcp-config.example.json` | drop-in MCP server config |\r\n| `copilot-instructions.snippet.md` | paste into `.github/copilot-instructions.md` |\r\n\r\n## Install\r\n\r\nRequires Python ≥ 3.10. The MCP server itself is pure stdlib, but the tools it\r\nlaunches need SkillOpt's runtime deps — install the package first:\r\n\r\n```bash\r\npip install -e .   # or: pip install -r requirements.txt\r\n```\r\n\r\n1. **Register the MCP server.** Add the server to your Copilot MCP config\r\n   (Copilot CLI: `~/.copilot/mcp-config.json`; VS Code: your MCP settings).\r\n   Use `mcp-config.example.json` as a template — set `SKILLOPT_REPO` to this\r\n   repo's path:\r\n\r\n   ```json\r\n   {\r\n     \"mcpServers\": {\r\n       \"skillopt\": {\r\n         \"command\": \"python3\",\r\n         \"args\": [\"/abs/path/SkillOpt/plugins/copilot/skillopt/mcp_server.py\"],\r\n         \"env\": { \"SKILLOPT_REPO\": \"/abs/path/SkillOpt\" }\r\n       }\r\n     }\r\n   }\r\n   ```\r\n\r\n2. **(Optional) Tell Copilot about it.** Append\r\n   `copilot-instructions.snippet.md` to your repo's\r\n   `.github/copilot-instructions.md` so Copilot reaches for the tools when the\r\n   user asks to \"optimize a skill\" or \"train on a benchmark\".\r\n\r\n## Use\r\n\r\nAsk Copilot things like *\"what configs can I run?\"*, *\"optimize the searchqa\r\nskill\"*, or *\"evaluate this skill on the dataset\"*. Copilot calls the MCP tools:\r\n`skillopt_list_configs`, `skillopt_train`, `skillopt_eval`.\r\n\r\n| Tool | Required args | Notes |\r\n|---|---|---|\r\n| `skillopt_list_configs` | — | Lists `configs/**/*.yaml` you can pass as `config`. |\r\n| `skillopt_train` | `config` | Runs a reflective optimization loop. Long-running; spends budget. |\r\n| `skillopt_eval` | `config`, `skill` | Evaluates one skill markdown file; no training. |\r\n\r\nCommon optional args (both train and eval): `env`, `backend`,\n`optimizer_model`, `target_model`, `out_root`, `cfg_options` (space-separated\n`section.key=value` YAML overrides), and `extra_args` (raw passthrough flags\nfor the underlying script). `skillopt_train` also accepts `num_epochs`,\n`batch_size`, `seed`, and `use_gate`. `use_gate` defaults to `true`; setting it\nto `false` still records validation scores but force-accepts every candidate,\nwhich changes the optimization semantics.\n\nThe MCP schema's `backend` argument follows the underlying script's\n`--backend` choices. Role-specific and generic OpenAI-compatible backends can\nbe selected through config or `extra_args` (for example,\n`--optimizer_backend openai_compatible --target_backend openai_compatible`);\nsee the repository's [backend guide](../../../docs/guide/new-backend.md) for\nthe required environment variables.\n\r\nRuns can be very long. The server's subprocess timeout defaults to 6 hours;\r\noverride it with the `SKILLOPT_RUN_TIMEOUT` environment variable (seconds).\r\n\r\n## Verify the server directly (no Copilot needed)\r\n\r\n```bash\r\nprintf '%s\\n' \\\r\n  '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{}}' \\\r\n  '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\"}' \\\r\n  '{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"skillopt_list_configs\",\"arguments\":{}}}' \\\r\n  | SKILLOPT_REPO=\"$(pwd)\" python3 plugins/copilot/skillopt/mcp_server.py\r\n```\r\n\r\nYou should see the server info, the three `skillopt_*` tools, and the list of\r\nbenchmark configs.\r\n\r\n## Notes / status\r\n\r\n- MCP is the stable, official Copilot extension surface, so this is portable\r\n  across Copilot CLI and IDE from one server.\r\n- `skillopt_list_configs` is filesystem-only and safe to call anytime;\r\n  `skillopt_train` / `skillopt_eval` shell out to the repo scripts and require\r\n  the SkillOpt runtime deps (and, for real backends, model credentials — see\r\n  [`../../../.env.example`](../../../.env.example)).\n\n<!-- File: plugins/cursor/.cursor-plugin/plugin.json (Tokens: ~217 | Category: plugin-manifest) -->\n{\n  \"name\": \"skillopt-sleep\",\n  \"displayName\": \"SkillOpt-Sleep\",\n  \"version\": \"0.1.0\",\n  \"description\": \"Review recent Cursor sessions, replay recurring work, and stage validation-gated improvements to a Cursor skill for explicit adoption.\",\n  \"author\": {\n    \"name\": \"Yifan Yang\",\n    \"email\": \"yifanyang@microsoft.com\"\n  },\n  \"homepage\": \"https://github.com/microsoft/SkillOpt\",\n  \"repository\": \"https://github.com/microsoft/SkillOpt\",\n  \"license\": \"MIT\",\n  \"keywords\": [\n    \"skillopt\",\n    \"cursor\",\n    \"self-improvement\",\n    \"memory-consolidation\",\n    \"sleep\",\n    \"skills\",\n    \"offline-optimization\"\n  ],\n  \"category\": \"developer-tools\",\n  \"tags\": [\n    \"automation\",\n    \"memory\",\n    \"transcripts\"\n  ],\n  \"commands\": \"./commands/\",\n  \"skills\": \"./skills/\"\n}\n\n<!-- File: plugins/cursor/README.md (Tokens: ~2561 | Category: plugin-manifest) -->\n# SkillOpt-Sleep - Cursor integration\n\nGive Cursor an on-demand or explicitly scheduled sleep cycle: review recent\nlocal Cursor sessions, replay recurring tasks through a selected backend, and\nstage validation-gated improvements to a project Cursor skill. Nothing runs at\nsession end, and nothing live changes until the user adopts an accepted staged\nproposal (unless they explicitly request `--auto-adopt`).\n\nThis package is a native Cursor plugin containing a command and an agent skill.\nIt does not install hooks or an MCP server.\n\n## Requirements\n\n- Cursor with plugin and agent-skill support.\n- Python 3.10 or newer.\n- Either a SkillOpt source checkout or an installed `skillopt-sleep` command.\n- For `--backend cursor`, an installed and authenticated Cursor Agent CLI\n  (`cursor-agent`). The default `mock` backend needs no provider login or spend.\n\nThe plugin and transcript harvester work on native Windows. Cursor documents\nthe Agent CLI for Windows through WSL; run provider-backed `--backend cursor`\ninside WSL unless a native `cursor-agent` is available in your environment.\n\n## Install the local plugin\n\nClone the repository, then run the installer for your platform.\n\nmacOS or Linux:\n\n```bash\ngit clone https://github.com/microsoft/SkillOpt.git\ncd SkillOpt\nbash plugins/cursor/install.sh\nexport SKILLOPT_SLEEP_REPO=\"$(pwd)\"\n```\n\nWindows PowerShell:\n\n```powershell\ngit clone https://github.com/microsoft/SkillOpt.git\nSet-Location SkillOpt\npowershell -File plugins/cursor/install.ps1\n[System.Environment]::SetEnvironmentVariable(\"SKILLOPT_SLEEP_REPO\", \"$(pwd)\", \"User\")\n```\n\nThe installer copies the plugin to\n`~/.cursor/plugins/local/skillopt-sleep` (or\n`%USERPROFILE%\\.cursor\\plugins\\local\\skillopt-sleep`). Quit and reopen Cursor\nafter changing user environment variables, then confirm that **SkillOpt-Sleep**\nappears in Settings > Plugins under Installed.\n\nThe plugin and engine have separate installation boundaries. The copied plugin\nteaches Cursor how to operate SkillOpt-Sleep; the engine still runs from the\nsource checkout through `plugins/run-sleep.sh` / `plugins/run-sleep.ps1`, or\nfrom an installed command:\n\n```bash\nuv tool install skillopt\n# or: python -m pip install skillopt\n```\n\nUse a release that includes Cursor source/backend support when choosing the\ninstalled-command route. The source-checkout route uses the implementation in\nthe checkout directly.\n\n## Use from Cursor\n\nRun the native command, for example:\n\n```text\n/skillopt-sleep status\n/skillopt-sleep dry-run --backend mock --max-sessions 5 --max-tasks 3\n/skillopt-sleep run --backend cursor --max-sessions 5 --max-tasks 3 --progress\n/skillopt-sleep adopt --legacy\n```\n\nFor fan-out proposals, inspect `status` and use repeatable `--skill NAME` or\n`--all-skills`. Bare adopt deliberately refuses a night containing fan-out rows.\n\nThe `skillopt-sleep` agent skill remains independently available if a Cursor\nversion does not surface plugin commands.\n\nThe native command's default Cursor-visible target is:\n\n```text\n.cursor/skills/skillopt-sleep-learned/SKILL.md\n```\n\nUse `--target-skill-path` with that value on harvest, dry-run, and run commands.\nWithout an explicit target, the shared engine defaults to a Claude-managed\nskill, which Cursor does not load as a project skill.\n\n### Source-checkout commands\n\nmacOS or Linux:\n\n```bash\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" status --project \"$(pwd)\"\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" dry-run \\\n  --project \"$(pwd)\" --source cursor --backend mock \\\n  --target-skill-path .cursor/skills/skillopt-sleep-learned/SKILL.md\nbash \"$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh\" run \\\n  --project \"$(pwd)\" --source cursor --backend cursor \\\n  --target-skill-path .cursor/skills/skillopt-sleep-learned/SKILL.md \\\n  --max-sessions 5 --max-tasks 3 --progress\n```\n\nWindows PowerShell:\n\n```powershell\npowershell -File \"$env:SKILLOPT_SLEEP_REPO\\plugins\\run-sleep.ps1\" status --project \"$(pwd)\"\npowershell -File \"$env:SKILLOPT_SLEEP_REPO\\plugins\\run-sleep.ps1\" dry-run `\n  --project \"$(pwd)\" --source cursor --backend mock `\n  --target-skill-path .cursor/skills/skillopt-sleep-learned/SKILL.md\npowershell -File \"$env:SKILLOPT_SLEEP_REPO\\plugins\\run-sleep.ps1\" run `\n  --project \"$(pwd)\" --source cursor --backend cursor `\n  --target-skill-path .cursor/skills/skillopt-sleep-learned/SKILL.md `\n  --max-sessions 5 --max-tasks 3 --progress\n```\n\n### Installed-command equivalents\n\n```bash\nskillopt-sleep status --project \"$(pwd)\"\nskillopt-sleep dry-run --project \"$(pwd)\" --source cursor --backend mock \\\n  --target-skill-path .cursor/skills/skillopt-sleep-learned/SKILL.md\nskillopt-sleep run --project \"$(pwd)\" --source cursor --backend cursor \\\n  --target-skill-path .cursor/skills/skillopt-sleep-learned/SKILL.md \\\n  --max-sessions 5 --max-tasks 3 --progress\nskillopt-sleep status --project \"$(pwd)\"\nskillopt-sleep adopt --project \"$(pwd)\" --legacy\n```\n\n`--source cursor` reads local JSONL transcripts below\n`~/.cursor/projects/<workspace>/agent-transcripts/`. Use\n`--cursor-home /path/to/.cursor` for a different Cursor home. Invoked scope\nselects the current workspace; `--scope all` includes every Cursor workspace.\nThe source converter retains user/assistant text, tool names, and explicit turn\nerrors, but excludes raw tool arguments and outputs.\n\nThe first harvest uses a 72-hour lookback by default. Use\n`--lookback-hours N` to choose a wider initial window, or\n`--lookback-hours 0` to consider all available history while still respecting\n`--max-sessions`. A successful `run`, including one that mines no tasks,\nrecords a new harvest checkpoint. Later runs use that checkpoint instead of\nthe initial lookback. Use `harvest` or `dry-run` to inspect session and task\ncounts before the first stateful run; neither action advances the checkpoint.\n\n`--backend cursor` invokes the authenticated Cursor Agent CLI. Use\n`--cursor-path /path/to/cursor-agent` or `SKILLOPT_SLEEP_CURSOR_PATH` if it is\nnot on PATH, and `--model` or `SKILLOPT_SLEEP_CURSOR_MODEL` to override its\nmodel. Check available identifiers with `cursor-agent --list-models` and verify\nthe billed variant in Cursor's usage reporting when cost matters. The child\nprocess receives only an explicit runtime/authentication/locale/proxy/CA\nenvironment allowlist; unrelated cloud and model-provider credentials are not\nforwarded.\n\n## What Cursor replay evaluates\n\nSkillOpt reads the target skill and inserts its text into mined task prompts. It\ndoes not invoke that file as a native Cursor skill or execute commands described\nby the skill. All ordinary Cursor model calls, including mining, replay,\njudging, and reflection, run in a new empty temporary workspace in read-only Ask\nmode. File reads, file writes, and MCP tools are denied. `--project` selects the\ntranscript scope, target files, state, and staging location; it does not make the\nproject the Cursor Agent execution workspace.\n\nCursor tool-aware replay is temporarily disabled pending live Cursor\npermission-boundary validation. Tasks containing a `tool_called` check fail\nnonzero before Agent mode starts. The failed replay does not add a cache entry,\nstage, adopt, persist state, or advance the harvest checkpoint. Use another\nbackend for those tasks.\n\nThis replay is useful for textual procedures, response conventions, and output\nformats. It is not an end-to-end evaluation of skills that depend on repository\ninspection, real CLIs, browsers, running services, or filesystem changes. There\nis currently no Cursor option that enables a fresh project worktree or real\nproject tools. The `replay: mock` report label refers to the prompt-replay mode,\nnot to the selected model backend.\n\nThe shared engine also supports `mock`, `claude`, `codex`, `copilot`,\n`handoff`, and `azure_openai` backends. Cursor is the native model-driven\nchoice for this integration; `mock` remains the no-provider default.\n\n## Review sensitive data before provider calls\n\nHarvesting is local and read-only, and `--backend mock` makes no provider calls.\nKnown secret-shaped strings are redacted from harvested Cursor content, and raw\ntool payloads are excluded, but pattern-based redaction is not a guarantee.\nA real backend sends truncated transcript excerpts and derived tasks to that\nbackend's provider for mining, replay, judging, and reflection.\n\nBoth `run` and `dry-run` perform those real-backend calls; `dry-run` prevents\nstaging but does not prevent provider spend. `--max-sessions` and `--max-tasks`\nbound harvested work, not provider calls, tokens, elapsed time, or money. One\ntask can require several attempt, judge, and reflection calls. Start with small\nlimits and review the provider's usage reporting before increasing them.\n\nFor sensitive work, split the flow at the review boundary:\n\n```bash\nskillopt-sleep harvest --project \"$(pwd)\" --source cursor \\\n  --target-skill-path .cursor/skills/skillopt-sleep-learned/SKILL.md \\\n  --max-sessions 5 --max-tasks 3 --output reviewed-tasks.json\n\nskillopt-sleep dry-run --project \"$(pwd)\" --backend cursor \\\n  --tasks-file reviewed-tasks.json --progress --json\n```\n\nInspect and redact the JSON, then set its top-level `\"reviewed\"` field to\n`true`. Real backends reject task files that remain unreviewed. Keep raw\ntranscripts, credentials, and task files out of commits.\n\n## Scheduling\n\nRuns remain user-triggered unless the user explicitly schedules them. Before\nscheduling, put the Cursor source and target in\n`~/.skillopt-sleep/config.json`, because the scheduler persists the project,\nbackend, time, and optional auto-adopt flag, but not command-line source or\ntarget overrides:\n\n```json\n{\n  \"transcript_source\": \"cursor\",\n  \"target_skill_path\": \".cursor/skills/skillopt-sleep-learned/SKILL.md\",\n  \"cursor_home\": \"/absolute/path/to/.cursor\",\n  \"backend\": \"cursor\"\n}\n```\n\nThen schedule or remove the managed entry:\n\n```bash\nskillopt-sleep schedule --project \"$(pwd)\" --backend cursor --hour 3 --minute 17\nskillopt-sleep unschedule --project \"$(pwd)\"\n```\n\nOn Unix this uses cron; on Windows it uses Task Scheduler. Scheduled runs stage\nproposals for later review by default. Do not add `--auto-adopt` unless the user\nhas explicitly chosen unattended adoption.\n\n## Adoption and memory\n\n`run` stages accepted proposals under\n`<project>/.skillopt-sleep/staging/<timestamp>/`. Read the staged `report.md`\nand show the held-out baseline-to-candidate score plus exact edits before\nrunning `adopt`. Adoption backs up an existing target before replacing it.\n\nThe shared engine may also propose project `CLAUDE.md` memory updates; existing\nmemory behavior is unchanged. To restrict a Cursor setup to the explicit Cursor\nskill, set `\"evolve_memory\": false` in `~/.skillopt-sleep/config.json`.\n\nThere is deliberately no session-end hook or automatic plugin execution.\n\n<!-- File: plugins/devin/README.md (Tokens: ~1416 | Category: plugin-manifest) -->\n# SkillOpt-Sleep — Devin integration\n\nGive **Devin** (Cognition) a nightly **sleep cycle** via a tiny **MCP server**\nthat exposes the `skillopt_sleep` engine as tools. MCP is Devin's supported way\nto add custom tooling, so this works in Devin's CLI and IDE.\n\nDevin doesn't write transcripts in the format the engine consumes, so this\nplugin adds a **Devin-specific harvester** that converts every locally available\nsource into the Claude Code-compatible JSONL the engine reads.\n\n## What's here\n\n| File | Purpose |\n|---|---|\n| `mcp_server.py` | stdlib-only MCP (stdio) server exposing `sleep_*` tools |\n| `harvest_devin.py` | converts Devin ATIF-v1.7 transcripts + agentmemory + `.devin/skills` into JSONL, with `taskKey` + outcome envelopes |\n| `judge.py` | reference judge for the deferred/judge branch of the validation gate |\n| `mcp-config.example.json` | drop-in MCP server config |\n| `install.sh` | copies hooks + rules into a project's `.devin/` and prints the MCP registration command |\n| `devin-rules.snippet.md` | copied to `.devin/rules/skillopt-sleep.md` by `install.sh` |\n| `hooks/hooks.v1.json` | SessionEnd hook config — installed/merged at `.devin/hooks.v1.json` by `install.sh` |\n| `hooks/on-session-end.sh` | best-effort activity marker script (called by the hook) |\n\n## What it harvests\n\n| Source | Where |\n|---|---|\n| Devin transcripts (ATIF-v1.7) | `~/.local/share/devin/cli/transcripts/*.json` |\n| agentmemory | `~/.agentmemory/standalone.json` |\n| Skill files | `.devin/skills/*/SKILL.md` |\n\nWorkspaces are auto-detected from `~/.config/Devin/User/workspaceStorage/*/workspace.json`.\nThe adapter performs no post-adoption copy. The core engine applies a reviewed\nproposal directly to its selected target and owns backup/rollback behavior.\n\n## Install\n\nRequires Python ≥ 3.10. No third-party packages — the server is pure stdlib.\n\n1. **Install hooks + rules into your project.** From the repo root:\n\n   ```bash\n   bash plugins/devin/install.sh /path/to/your/project\n   ```\n\n   This copies the SessionEnd hook and rules snippet into the project's\n   `.devin/` directory and prints the MCP registration command. The hook is\n   on by default — it logs a cheap activity marker for local inspection or\n   external automation when each session ends. The current engine harvests by\n   transcript timestamps and does not consume this marker directly. The hook\n   is non-blocking and spends no API budget. Re-run the script to update; the\n   installer preserves existing hooks and does not duplicate its own entry.\n\n2. **Register the MCP server.** Use `mcp-config.example.json` as a template, or\n   run the command printed by `install.sh`:\n\n   ```bash\n   devin mcp add skillopt-sleep \\\n     --env \"SKILLOPT_DEVIN_CLAUDE_HOME=$HOME/.skillopt-sleep-devin\" \\\n     -- python3 /abs/path/to/SkillOpt/plugins/devin/mcp_server.py\n   ```\n\n3. Ask Devin: *\"run the sleep cycle\"*, *\"what did the last sleep propose?\"*, *\"adopt it\"*.\n\n## Tools\n\n| Tool | What it does |\n|---|---|\n| `sleep_status` | nights run so far + latest staged proposal |\n| `sleep_dry_run` | preview cycle — no staging; a real backend still makes provider calls |\n| `sleep_run` | full cycle; stages a proposal for review |\n| `sleep_adopt` | apply a reviewed legacy or per-skill proposal (with backup) |\n| `sleep_harvest` | debug: list the recurring tasks mined |\n| `sleep_schedule` | install a nightly cron entry (`--hour` / `--minute`) |\n| `sleep_unschedule` | remove the nightly cron entry |\n\nBefore `sleep_adopt`, inspect `sleep_status` and use the controls that match the\nreviewed staging manifest:\n\n- `staging` — exact staging directory to adopt instead of the latest night\n- `skills` — array of skill names to adopt; each is forwarded as one repeated\n  `--skill` argument without shell interpolation\n- `all_skills` — adopt every staged per-skill proposal\n- `legacy` — adopt only the legacy managed `SKILL.md`/`CLAUDE.md` pair\n\nChoose one selection mode (`skills`, `all_skills`, or `legacy`) and do not\ncombine them. A bare call remains compatible with legacy-only staging; fan-out\nstaging requires an explicit selection. To operate on a specific Devin skill,\npass its `SKILL.md` as `target_skill_path`; the adapter never performs a second\ncopy after the core engine returns.\n\nTool results preserve the engine's `exit_code` in `structuredContent`.\nOrdinary nonzero exits set `isError: true`; exit 3 is the expected\n`handoff_pending` state and is not an MCP tool error. With `json: true`, text\ncontent is the engine's parseable JSON stdout, while harvest and engine\ndiagnostics remain separate in `structuredContent`.\n\nDefault backend is `mock` (no API spend); the `claude`, `codex`, and `copilot`\nbackends use the corresponding authenticated CLI and budget. The `handoff`\nbackend runs the cycle with no model subprocess or API key — the engine writes\npending model calls to `.skillopt-sleep-handoff/PROMPTS.md` + `pending.json`\n(exit code 3) and resumes after answers are placed in `answers/<id>.md`; re-run\n`sleep_run` with the same arguments to resume. The seven tools call the same\n`python -m skillopt_sleep` actions as the other shared-engine integrations.\n\n## Data boundary\n\nThe Devin harvester reads local ATIF transcripts, agentmemory, and skill files\nand converts them into the engine's session format. The `mock` backend keeps\nthat workflow local. A real backend sends truncated excerpts and derived tasks\nto the selected provider for mining, replay, judging, and reflection. The\nconversion step is not a guarantee that outbound prompts contain no secrets;\nreview sensitive sources and provider policy before enabling a real backend.\nSee the [shared data-boundary guidance](../README.md#data-boundary) and\n[implemented CLI reference](../README.md#supported-cli-surface).\n\n<!-- File: plugins/dsh/README.md (Tokens: ~1514 | Category: plugin-manifest) -->\n# SkillOpt-Sleep — DeepSeek Harness (dsh) integration\n\nGive your **DeepSeek Harness** agent a nightly **sleep cycle**: it reviews past\nsessions offline, replays your recurring tasks on your own API budget, and\nconsolidates what it learns into validated skills behind a held-out gate. Same\nengine as the Claude Code / Codex / Cursor integrations\n([skillopt_sleep](https://github.com/microsoft/SkillOpt)), wired into dsh's\nplugin system as native tools plus a bundled skill.\n\nDeepSeek Harness is the \"everything is a plugin\" agent framework\n([deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness)).\nPlugins are TypeScript modules exporting an `apply(ctx)` function that register\ncapabilities (tools, services, events, settings) on the Cordis context.\n\n## Why a sleep cycle?\n\nSkills improve when an agent re-examines its own sessions — not just when you\nhand-tune a prompt. The sleep cycle turns your everyday usage into a nightly,\nvalidation-gated skill-improvement loop: harvest what you actually did, replay\nthe recurring tasks on your own API budget, and keep only the changes that pass\na held-out gate. It's the same engine as the Claude Code / Codex / Cursor\nintegrations, wired into dsh as native tools plus a bundled skill.\n\n## What this integration adds\n\n| Component | Purpose |\n|---|---|\n| `src/index.js` | dsh plugin entry: registers 7 `skillopt_*` tools + Schemastery config |\n| `cordis.patch.yml` | bundle patch layer — drop `dsh-skillopt` into any profile's bundles |\n| `skills/skillopt-sleep/SKILL.md` | agent skill: when to use the tools, operating rules, data-boundary rules |\n| `scripts/sleep.py` | bootstrap/self-check runner (same command shape the tools use) |\n| `package.json` | npm package metadata (bundle manifest) |\n\n## Tools\n\n| Tool | skillopt_sleep action | Behavior |\n|---|---|---|\n| `skillopt_status` | `status` | state, engine availability, latest staged proposal & report |\n| `skillopt_dry_run` | `dry-run` | full preview (harvest+mine+replay), stages nothing |\n| `skillopt_run` | `run` | full cycle, stages a proposal (live files unchanged) |\n| `skillopt_adopt` | `adopt` | apply latest staged proposal (with backup) — the live-change boundary |\n| `skillopt_harvest` | `harvest` | read-only show/export of mined tasks |\n| `skillopt_schedule` / `skillopt_unschedule` | `schedule` / `unschedule` | install/remove the nightly cron entry |\n\n## Prerequisites\n\n- DeepSeek Harness (dsh) installed — dsh 0.1.x and 0.2.x are supported\n  (`@deepseek-ai/dsh-tools` 0.1.1-rc.2, 0.2.0-rc.2)\n- Python 3.10+ with the SkillOpt-Sleep engine:\n\n```bash\npip install skillopt          # or use this source checkout\n```\n\n## Install\n\n### As a bundle in a profile\n\nAdd `dsh-skillopt` to the profile's bundles, or in the profile `cordis.patch.yml`:\n\n```yaml\n- insert:\n    - id: skillopt\n      name: './src/index.js'\n      config:\n        backend: mock          # or codex / claude / cursor / pi / opencode / handoff …\n        project: /path/to/project\n        preferences: 'Always use async/await'\n```\n\n### Local patch overlay (dev)\n\nRun from a DeepSeek Harness **source checkout** (the official dev workflow,\n`pnpm` resolves the workspace `dsh` bin):\n\n```bash\npnpm dsh web --patch ./plugins/dsh/cordis.patch.yml\n```\n\nIf `dsh` is installed **globally** (npm install -g), use it directly:\n\n```bash\ndsh web --patch ./plugins/dsh/cordis.patch.yml\n```\n\nEither way the patch inserts the `skillopt` plugin row into the profile; then\nask the agent: \"Use skillopt_status to check the sleep cycle state.\"\n\n## Config keys\n\n| Key | Default | Purpose |\n|---|---|---|\n| `pythonCmd` | `python` | Python interpreter for the engine |\n| `module` | — (bootstrap) | engine Python module override (`python -m <module>`) |\n| `engineScript` | — (scripts/sleep.py) | engine bootstrap script override |\n| `project` | — | default project directory |\n| `scope` | — | harvest scope: `all` \\| `invoked` |\n| `backend` | — | `mock\\|claude\\|codex\\|copilot\\|cursor\\|pi\\|opencode\\|handoff\\|azure_openai` |\n| `source` | — | `claude\\|codex\\|copilot\\|cursor\\|pi\\|opencode\\|auto` |\n| `model` | — | backend model override |\n| `maxTasks` / `maxSessions` | — | mine/harvest caps |\n| `editBudget` | — | bounded edits per cycle |\n| `preferences` | — | house rules for the reflection prior |\n| `jsonOutput` | `false` | machine-readable JSON output |\n| `autoAdopt` | `false` | OPERATOR-ONLY: auto-adopt a passed proposal without asking |\n| `unscheduleAll` | `false` | OPERATOR-ONLY: allow `skillopt_unschedule` to remove every managed entry |\n| `timeoutMs` | `600000` | per-call engine timeout in milliseconds |\n\nAdvanced engine keys (`gate_mode`, `gate_metric`, `gate_no_regression`,\n`dream_rollouts`, `recall_k`, `evolve_memory`/`evolve_skill`) go in\n`~/.skillopt-sleep/config.json` — the same file shared by all integrations.\n\n## Data boundary\n\n- Harvest is read-only; `mock`/`handoff` make no network calls.\n- `run` stages proposals; `adopt` is the normal live-change boundary and backs up first.\n- Real backends send truncated transcript excerpts and derived tasks to the\n  selected provider. For sensitive sessions, export tasks first (`skillopt_harvest`\n  with `output=`), redact, set `\"reviewed\": true`, then replay — real backends\n  refuse unreviewed task files.\n- Outbound prompts are not guaranteed secret-free; review source & provider policy.\n\n## Validate (no API spend)\n\n```bash\npython -m skillopt_sleep.experiments.run_experiment --persona researcher --assert-improves\n```\n\nSee the [SkillOpt-Sleep documentation](../../docs/sleep/README.md) for recorded\nresults, limitations, and the supported integration surface.\n\n<!-- File: plugins/openclaw/README.md (Tokens: ~1155 | Category: plugin-manifest) -->\n# OpenClaw reference adaptation for SkillOpt-Sleep\n\nThis directory is a contributed reference for connecting\n[SkillOpt-Sleep](https://github.com/microsoft/SkillOpt) to\n[OpenClaw](https://github.com/openclaw/openclaw) with a custom DeepSeek/Ollama\nbackend.\n\n> **Reference status.** This is not one of the shared, plug-and-play\n> `skillopt_sleep` wrappers. Several scripts and the sample config contain\n> environment-specific absolute paths and assumptions from the original setup,\n> and the contributed wrapper has unresolved Python 3.10 syntax and backend\n> factory-signature gaps. The current checkout is not directly runnable; treat\n> it as porting source material, not an installation.\n\n## Included components\n\n| File | Purpose |\n|---|---|\n| `run_sleep.py` | custom cycle entry point |\n| `skillopt_sleep_openclaw.py` | DeepSeek Chat Completions backend plus local Ollama embeddings |\n| `run_sleep_cron.sh` | category-oriented cron wrapper |\n| `slash_sleep.py` | experimental `/sleep` command helper |\n| `config.json` | example engine configuration |\n| `SKILL.md` | OpenClaw skill manifest |\n| `tests/*.json` | example task sets for research, DevOps, and wiki workflows |\n\nThe adaptation imports the shared engine but registers its own backend and\nmaintains its own wrapper behavior. Changes to the shared CLI documentation do\nnot automatically make every option available through these custom scripts.\n\n## Intended cycle\n\n```text\nharvest supported session data or load a task file\n  → replay with the current skill\n  → propose bounded edits\n  → validate the candidate on held-out tasks\n  → stage a proposal for operator review\n```\n\nThe intended safety boundary is manual adoption: review the generated report and\nstaged files before changing a live skill.\n\n## Adapt before use\n\n1. Clone SkillOpt into a location you control:\n\n   ```bash\n   git clone https://github.com/microsoft/SkillOpt.git\n   cd SkillOpt/plugins/openclaw\n   ```\n\n2. Inspect and replace the sample absolute paths in `run_sleep.py`,\n   `slash_sleep.py`, `run_sleep_cron.sh`, and `config.json`. Confirm the engine\n   checkout, OpenClaw workspace, state directory, skill directory, and task-file\n   paths all point to isolated test locations.\n\n3. Review `config.json`. In particular, do not assume that values such as\n   `replay_mode` are enforced by this custom wrapper merely because they appear\n   in the example config. `max_tokens_per_night` is applied by the shared cycle,\n   but it is measured with the wrapper backend's rough `tokens_used()` estimate\n   (a quarter of the attempt prompt length plus 200 per attempt, 600 per rubric\n   judge call, and a third of the reflect prompt plus 1500 per reflect call), so\n   it is not a billing limit.\n\n4. Supply credentials through your normal secret-management mechanism. Do not\n   commit a DeepSeek key or place it in a world-readable file.\n\n5. Resolve every known porting gap listed in [`SKILL.md`](SKILL.md), add\n   isolated tests for your adapted backend, and verify that `--help` imports\n   cleanly on Python 3.10+. Only then start with a dry run and one reviewed\n   task file. The target command should be shaped like:\n\n   ```bash\n   cd /path/to/SkillOpt/plugins/openclaw\n   python3 run_sleep.py --config /path/to/reviewed-config.json \\\n     --tasks tests/research-cron-tasks.json --dry-run\n   ```\n\n6. Inspect the report, paths, network destinations, and proposed edits before\n   considering a non-dry run or scheduling.\n\n## Data boundary\n\nThe custom `openclaw-deepseek` backend sends task, skill, response, rubric, and\nreflection content to the configured DeepSeek endpoint. Its embedding helper can\nsend truncated text to the configured local Ollama service. Do not assume these\noutbound prompts have been fully redacted; inspect transcript/task inputs and the\nprovider's retention policy before using real data.\n\nUse HTTPS for a remote DeepSeek-compatible endpoint. Keep any plaintext Ollama\nendpoint on a trusted loopback interface. For a network-free engine smoke test,\nuse the shared SkillOpt-Sleep CLI with `--backend mock` rather than assuming this\ncustom wrapper is isolated.\n\n## Scheduling\n\n`run_sleep_cron.sh` and the scheduling helpers are examples, not portable\ninstallers. Adapt their paths, create log directories, verify their environment,\nand run the exact command manually before adding a cron entry. Scheduled runs\nmust preserve the same manual-adoption and credential boundaries as interactive\nruns.\n\n## Validation scope\n\nThe bundled JSON files are example held-out task sets, not a universal OpenClaw\nbenchmark. Provider cost and quality depend on the selected model, task content,\nnumber of calls, and pricing at run time; this reference does not promise a fixed\nnightly cost. Validate the adapted workflow in an isolated workspace before\nusing it on live skills.\n\nFor the supported shared-engine CLI and its current flags, see the\n[integration reference](../README.md#supported-cli-surface). For measured\nSkillOpt-Sleep results and limitations, see\n[`docs/sleep/RESULTS.md`](../../docs/sleep/RESULTS.md).\n\n## License\n\nMIT, consistent with SkillOpt core.\n\n<!-- File: plugins/README.md (Tokens: ~4072 | Category: plugin-manifest) -->\n# SkillOpt-Sleep integrations\n\n**SkillOpt-Sleep** reviews recent agent sessions, mines recurring tasks, replays\nthem, and proposes bounded updates to memory and skills. A held-out validation\ngate decides whether a proposal is worth staging, and nothing live changes until\nthe user explicitly adopts it.\n\nThe shared engine lives in [`skillopt_sleep/`](../skillopt_sleep) and has no\nruntime dependency on the paper's `skillopt/` experiment package.\n\n## Available integrations\n\nSix integrations wrap the shared `skillopt_sleep` CLI. OpenClaw is a separate\nreference adaptation with its own backend and setup assumptions.\n\n| Platform | Folder | Mechanism | Status |\n|---|---|---|---|\n| **Claude Code** | [`claude-code/`](claude-code) | marketplace plugin, commands, skill, and hooks | installable shared-engine integration |\n| **Codex** | [`codex/`](codex) | user-level skill and shared runner | installable shared-engine integration |\n| **Cursor** | [`cursor/`](cursor) | native command and skill, project skill target, and shared runner | installable shared-engine integration |\n| **GitHub Copilot** | [`copilot/`](copilot) | MCP server exposing seven `sleep_*` tools | shared-engine MCP integration |\n| **Devin** | [`devin/`](devin) | MCP server plus Devin transcript conversion | shared-engine MCP integration |\n| **DeepSeek Harness** | [`dsh/`](dsh) | Cordis plugin: 7 native `skillopt_*` tools, skill, bundle patch layer | installable shared-engine integration |\n| **OpenClaw** | [`openclaw/`](openclaw) | custom DeepSeek/Ollama wrapper | independent reference adaptation; review and adapt before use |\n\n## Install\n\nClone the repository first unless an installed `skillopt-sleep` CLI is sufficient\nfor your workflow.\n\n| Platform | Install | Then |\n|---|---|---|\n| **Claude Code** | from the repository root, `/plugin marketplace add ./plugins/claude-code`, then `/plugin install skillopt-sleep@skillopt-sleep` | `/skillopt-sleep status` |\n| **Codex** | `bash plugins/codex/install.sh` | ask Codex to use the `skillopt-sleep` skill |\n| **Cursor** | `bash plugins/cursor/install.sh` (macOS/Linux) or `powershell -File plugins/cursor/install.ps1` (Windows) | `/skillopt-sleep status` |\n| **Copilot** | register `plugins/copilot/mcp_server.py` using its example MCP config | ask Copilot to run `sleep_status` |\n| **Devin** | register `plugins/devin/mcp_server.py` using its example MCP config | ask Devin to run `sleep_status` |\n| **DeepSeek Harness** | add `dsh-skillopt` to the profile's bundles, or patch it in — from a DSH source checkout: `pnpm dsh web --patch ./plugins/dsh/cordis.patch.yml`; with global dsh: `dsh web --patch ./plugins/dsh/cordis.patch.yml` | ask the agent to use `skillopt_status` |\n| **OpenClaw** | follow and adapt [`openclaw/README.md`](openclaw/README.md) | validate paths, credentials, and tasks locally |\n\nPython 3.10 or newer is required. Real CLI backends also require the selected\nagent CLI to be installed and authenticated.\n\nThe shared [`run-sleep.sh`](run-sleep.sh) supports both source checkouts and\ninstalled packages. If it cannot find the repository, it tries the\n`skillopt-sleep` executable on `PATH` (including `uv tool`/`pipx` installs), then\nan importable `skillopt_sleep` module. Install with `uv tool install skillopt` or\n`pip install skillopt` when using that fallback.\n\n> **Version note.** This integration reference tracks `main`. PyPI 0.2.0\n> supports the base Sleep CLI, while Cursor source/backend/plugin support,\n> Pi source/backend support, handoff, Sleep support for non-Azure\n> OpenAI-compatible endpoints, OpenCode Sleep source/backend support, and\n> `--preferences`, multi-skill fan-out, and reviewed subset adoption require a\n> source checkout from `main` until the next release.\n\n## One sleep cycle\n\n```text\nharvest supported local sessions → mine recurring tasks → replay tasks\n  → reflect and propose bounded edits → validate on held-out real tasks\n  → stage proposal → (you) review and adopt\n```\n\nThe default backend is `mock`: it makes no provider calls and is useful for\nchecking plumbing. A real backend is required for model-driven mining and genuine\noptimization.\n\n## Data boundary\n\n- Harvesting is local and read-only. The `mock` and `handoff` backends make no\n  network calls; handoff writes prompts for separate, user-controlled completion.\n- A real backend sends mining, replay, judging, and reflection prompts derived\n  from truncated transcript excerpts and tasks to the selected provider.\n- The Cursor source reads local user/assistant message text, explicit turn\n  errors, and tool names from `~/.cursor/projects/*/agent-transcripts`; it does\n  not retain tool arguments, tool outputs, or other record types. Known\n  secret-shaped strings are redacted, but this is defense in depth rather than\n  a guarantee that outbound prompts are secret-free.\n- The Cursor backend sends prompts through the installed, authenticated\n  `cursor-agent` CLI. Ordinary calls use read-only Ask mode in a new empty\n  temporary workspace with project file access denied. Cursor tasks containing\n  `tool_called` validation fail before Agent mode starts; use another backend for\n  those tasks. Cursor and the model provider selected by Cursor can receive the\n  resulting prompt content.\n- The Pi backend sends prompts through the installed, authenticated Pi CLI to\n  the provider configured by the user. It disables tools, skills, context files,\n  extensions, prompt templates, themes, and session writes for these calls, but\n  retains the user's Pi authentication and model configuration. Pi's offline\n  startup mode prevents configured npm/git package installation, package\n  updates, and model-catalog refresh; it does not prevent the selected provider\n  call. These controls are not a guarantee of permanent or complete isolation.\n- The Pi source retains user/assistant text, tool names, and lexical feedback\n  found in user text. It excludes thinking, tool arguments, tool outputs, images,\n  and unrelated metadata. The absolute project `cwd` from the session header is\n  retained for scope filtering and may appear in miner prompts sent to a real\n  backend and its provider. Known secret-shaped strings in retained message text\n  are redacted only as defense in depth.\n- The core `opencode` source reads local OpenCode SQLite history without the\n  CLI, authentication, or provider access. See\n  [the CLI reference](../docs/reference/cli.md#opencode-source-and-backend) for\n  its retained-data boundary.\n- The core `opencode` backend uses the installed OpenCode CLI. Plain calls\n  disable project configuration, model-initiated tool invocation, external\n  plugins, and configured MCP servers. Tool-aware replay requires explicit\n  opt-in. It exposes only temporary synthetic tools with randomized names and\n  fixed results, then verifies which tools OpenCode actually invoked. See the\n  [CLI reference](../docs/reference/cli.md#opencode-source-and-backend) for\n  history and isolation details. A native OpenCode plugin or command is not\n  included.\n- Outbound prompts are not currently guaranteed to be free of secrets. Do not\n  use a third-party provider on sensitive transcripts without reviewing the data\n  source and the provider's retention policy.\n- For a reviewable workflow, export tasks first, inspect and redact the JSON, set\n  its top-level `\"reviewed\"` field to `true`, and then use the task file with a\n  real backend:\n\n  ```bash\n  python -m skillopt_sleep harvest --project \"$(pwd)\" --output reviewed-tasks.json\n  python -m skillopt_sleep dry-run --project \"$(pwd)\" --backend codex \\\n    --tasks-file reviewed-tasks.json --progress\n  ```\n\n  Real backends reject task files that are still marked unreviewed.\n\nFor the separate API-key and Azure managed-identity transport boundaries, see\n[OpenAI-compatible endpoints](../docs/sleep/openai-compatible-endpoints.md).\n\n## Supported CLI surface\n\nActions:\n\n| Action | Behavior |\n|---|---|\n| `status` | show state and the latest staged proposal |\n| `dry-run` | harvest, mine, replay, and report; stage nothing |\n| `run` | run the full cycle and stage a proposal |\n| `adopt` | apply the latest staged proposal, with backups |\n| `harvest` | inspect or export mined tasks |\n| `schedule` / `unschedule` | install or remove the managed nightly cron entry |\n\nCommon implemented flags include:\n\n| Flag | Default | Purpose |\n|---|---|---|\n| `--backend mock\\|claude\\|codex\\|cursor\\|copilot\\|pi\\|opencode\\|handoff\\|azure_openai` | `mock` | select who performs model calls |\n| `--model NAME` | backend default | select a backend-specific model |\n| `--source claude\\|codex\\|copilot\\|cursor\\|pi\\|opencode\\|auto` | `claude` | select the transcript source; `auto` retains Codex-then-Claude precedence and does not select Copilot, Cursor, Pi, or OpenCode |\n| `--cursor-home PATH` | `~/.cursor` | override the Cursor transcript home |\n| `--cursor-path PATH` | auto-detect `cursor-agent` | select the Cursor Agent CLI executable |\n| `--pi-home PATH` | `~/.pi` | select the parent directory containing `agent/sessions` |\n| `--pi-path PATH` | auto-detect `pi` | select the Pi coding-agent CLI executable |\n| `--opencode-path PATH` | `SKILLOPT_SLEEP_OPENCODE_PATH`, then `opencode` on `PATH`/`PATHEXT` | select the OpenCode CLI executable |\n| `--opencode-db PATH` | `OPENCODE_DB`, `%LOCALAPPDATA%`/`%APPDATA%` (Windows), or `${XDG_DATA_HOME:-~/.local/share}/opencode/opencode.db` | select the OpenCode SQLite history database |\n| `--opencode-tool-replay` | off | enable OpenCode tool-aware replay for `tool_called` checks in rule judges |\n| `--project PATH` | current directory | select the project and invoked harvest scope |\n| `--scope invoked\\|all` | `invoked` | limit transcript harvesting |\n| `--target-skill-path PATH` | managed skill | select a specific `SKILL.md` to stage/adopt |\n| `--tasks-file PATH` | none | replay a reviewed task file instead of harvesting |\n| `--max-sessions N` / `--max-tasks N` | unset → `3 × tasks` / `40` tasks | bound harvested work; these are not hard token or wall-clock budgets |\n| `--edit-budget N` | `4` | cap bounded edits per cycle |\n| `--preferences \"...\"` | empty | add house rules to the reflection prior |\n| `--progress` | off | print phase progress to stderr |\n| `--auto-adopt` | off | adopt an accepted proposal without a separate command |\n| `--json` | off | emit machine-readable output where supported |\n\nThe nightly CLI does **not** currently expose `--gate`, `--rollouts-k`,\n`--optimizer-model`, `--target-model`, `--budget-tokens`, or `--budget-minutes`.\nDo not pass experiment-harness flags to the main CLI.\n\nFor the Cursor backend, `--project` also selects target files, state, and the\nstaging location, but it does not make that directory the Cursor Agent execution\nworkspace. The target skill is inserted as prompt text rather than invoked as a\nnative skill. Real-backend `dry-run` performs the same mining and replay model\ncalls while suppressing staging, adoption, and persisted state changes. The\ncurrent Sleep cycle does not implement fresh-worktree replay; a `replay: mock`\nreport label describes prompt replay and is independent of `--backend mock`.\n\n### Preferences\n\n`--preferences` is the main user-facing steering knob:\n\n```bash\npython -m skillopt_sleep run --backend codex --project \"$(pwd)\" \\\n  --preferences \"Prefer pytest. Keep commit subjects imperative and concise.\"\n```\n\nPreferences guide reflection but remain subject to the validation gate.\n\n### Pi source and backend\n\nPi transcript harvesting is explicit: `--source pi` reads session JSONL files\nbelow `~/.pi/agent/sessions`; use `--pi-home` to select the parent directory\nthat contains `agent/sessions`. This source does not require the Pi CLI or\nprovider authentication. It retains user/assistant text, tool names, and lexical\nfeedback found in user text, while excluding thinking, tool arguments, tool\noutputs, images, and unrelated metadata. The absolute project `cwd` from the\nsession header is retained for scope filtering and may appear in miner prompts\nsent to a real backend and its provider. Known secret-shaped strings in retained\nmessage text are redacted as defense in depth, not as a guarantee. `--source auto` keeps Codex-then-Claude\nprecedence and does not select Pi.\n\nThe source and backend are independent. `--backend pi` uses a locally installed,\nauthenticated Pi CLI to make real model-provider calls for mining, replay,\njudging, and reflection. Select another executable with `--pi-path` and a model\nwith `--model`:\n\n```bash\npython -m skillopt_sleep run --project \"$(pwd)\" \\\n  --source pi --backend pi --pi-path /absolute/path/to/pi \\\n  --model provider/model --max-sessions 5 --max-tasks 3 --progress\n```\n\nPi calls disable tools, skills, context files, extensions, prompt templates,\nthemes, and session writes. They still use the user's Pi authentication and\nmodel configuration. Pi's offline startup mode also prevents configured npm/git\npackage installation, package updates, and model-catalog refresh; it does not\nprevent the selected provider call. This is bounded invocation setup rather\nthan permanent or complete isolation. Transcript-derived prompts reach the\nprovider configured in Pi; review that provider's data-retention and privacy\npolicy before using sensitive sessions.\n\nThe managed scheduler stores the selected backend but does not persist\n`--source`, `--pi-home`, `--pi-path`, or `--model`. Before scheduling Pi, set\n`transcript_source`, `pi_home`, `pi_path`, and `model` in\n`~/.skillopt-sleep/config.json`; prefer an absolute `pi_path` and verify that the\nscheduled account is authenticated.\n\n### Cursor source and backend\n\nCursor transcript harvesting is explicit: use `--source cursor` rather than\n`--source auto`. Invoked-project scope uses Cursor's recorded workspace path,\nwith the sanitized storage directory as a fallback; `--scope all` scans every\nCursor workspace under `~/.cursor/projects`. The model-driven backend requires\nan installed, authenticated `cursor-agent`; use `--cursor-path`,\n`SKILLOPT_SLEEP_CURSOR_PATH`, or the `cursor_path` config key when it is not on\n`PATH`, and use `--model` or `SKILLOPT_SLEEP_CURSOR_MODEL` to choose a model.\n\nTarget the project skill explicitly so accepted learning becomes visible to\nCursor without changing the plugin's own workflow skill:\n\n```bash\npython -m skillopt_sleep run --project \"$(pwd)\" \\\n  --source cursor --backend cursor \\\n  --target-skill-path .cursor/skills/skillopt-sleep-learned/SKILL.md \\\n  --max-sessions 5 --max-tasks 3 --progress\n```\n\n### Advanced config\n\nThe JSON/YAML config under `~/.skillopt-sleep/` supports additional engine keys,\nincluding `gate_mode`, `gate_metric`, `gate_no_regression`, `dream_rollouts`,\n`dream_factor`, `recall_k`, `evolve_memory`, and `evolve_skill`. These are config\nkeys, not aliases for the unsupported CLI flags listed above. Shipping defaults\nare conservative: `gate_mode=\"on\"`, `gate_no_regression=false`,\n`dream_rollouts=1`, `dream_factor=0`, and `recall_k=0`.\n\nThe managed `schedule` command stores only the project, backend, time, and\noptional auto-adopt setting. It does not copy `--source`, `--cursor-home`,\n`--cursor-path`, `--model`, or `--target-skill-path` into the scheduled command.\nFor a Cursor schedule, set `transcript_source`, `cursor_home`, `cursor_path`,\n`model`, and `target_skill_path` in `~/.skillopt-sleep/config.json` first. Keep\nthe target project-relative, use an absolute CLI path because cron and Task\nScheduler may have a minimal `PATH`, and confirm that `cursor-agent` is\nauthenticated for the account that runs the job.\n\n### Handoff backend\n\n`--backend handoff` keeps model subprocesses out of the engine. It writes pending\nmodel calls to `.skillopt-sleep-handoff/PROMPTS.md` and `pending.json`, exits with\ncode 3, and resumes after answers are placed in `answers/<id>.md`:\n\n```bash\npython -m skillopt_sleep run --backend handoff --project \"$(pwd)\"\n# answer each prompt in a fresh context, then run the same command again\n```\n\nAnswering held-out prompts from a context that has already seen their references\ncontaminates the validation gate. Claude Code's `/skillopt-sleep-handoff` command\nautomates the loop with isolated fresh-context subagents.\n\n## Validation\n\nThe deterministic no-provider check exercises consolidation and the gate:\n\n```bash\npython -m skillopt_sleep.experiments.run_experiment \\\n  --persona researcher --assert-improves\n```\n\nReal-model benchmark results and their limitations are documented in\n[`docs/sleep/RESULTS.md`](../docs/sleep/RESULTS.md). The benchmark recipes are not\nthe shipping CLI defaults.\n\n## Safety summary\n\n- Session harvesting is read-only.\n- `mock` and `handoff` make no network calls.\n- `run` stages proposals; `adopt` is the normal live-change boundary.\n- Adoption backs up existing target files.\n- `--max-sessions` and `--max-tasks` bound work. `max_tokens_per_night` in the\n  config file (default `400000`) stops a night from starting new steps once its\n  token count reaches the budget, but a started step finishes, so it is not a\n  hard cap. There is no elapsed-time budget.\n- Treat real-backend transcript excerpts as data shared with the selected\n  provider.\n</yakaai_skills>"}