skillopt-sleep

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.

SkillOpt-Sleep for Cursor

SkillOpt-Sleep reviews recent local Cursor sessions, mines recurring tasks, replays those tasks, and proposes bounded improvements to a project Cursor skill. With the default gate enabled, a proposal is accepted only when it improves the held-out score. A normal run stages the proposal for review; nothing live changes until explicit adoption. There is no model-weight training.

This plugin has no session-end hook and no MCP server. Run the cycle only when the user asks, or install a schedule only when the user explicitly requests one.

Cursor target

Always use this project-relative target for Cursor-visible learning:

.cursor/skills/skillopt-sleep-learned/SKILL.md

Pass it through --target-skill-path on harvest, dry-run, and run. Without an explicit target, the shared engine uses a Claude-managed skill under ~/.claude/skills, which is not the intended Cursor project skill.

The shared engine can also evolve project CLAUDE.md. If that secondary memory target is unwanted, set "evolve_memory": false in ~/.skillopt-sleep/config.json before running.

Choose the runner

Use one of these supported command paths consistently:

1. Source checkout on macOS/Linux: bash "$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh" <action> ...
2. Source checkout on Windows: powershell -File "$env:SKILLOPT_SLEEP_REPO\plugins\run-sleep.ps1" <action> ...
3. Installed engine on any platform: skillopt-sleep <action> ...

If SKILLOPT_SLEEP_REPO is not set and skillopt-sleep is unavailable, stop and explain that the engine must be installed or a SkillOpt checkout must be selected. Do not substitute a hand-written edit for the engine workflow.

Core workflow

1. Harvest local Cursor JSONL transcripts read-only.
2. Mine recurring, checkable task records from session digests.
3. Replay tasks under the current skill and memory through the selected backend.
4. Reflect on failures and propose bounded edits.
5. Gate the candidate on held-out real tasks.
6. Stage accepted proposals under <project>/.skillopt-sleep/staging/<timestamp>/.
7. Adopt only after review, backing up existing live targets first.

Commands

Use the installed-command form below, or replace skillopt-sleep with the platform-specific source runner described above.

TARGET_SKILL=.cursor/skills/skillopt-sleep-learned/SKILL.md

# Inspect current state and the latest staged proposal.
skillopt-sleep status --project "$(pwd)"

# Inspect mined tasks without provider spend.
skillopt-sleep harvest --project "$(pwd)" --source cursor \
  --target-skill-path "$TARGET_SKILL" --max-sessions 5 --max-tasks 3

# First smoke check: deterministic and no provider calls.
skillopt-sleep dry-run --project "$(pwd)" --source cursor --backend mock \
  --target-skill-path "$TARGET_SKILL" --max-sessions 5 --max-tasks 3 --json

# Model-driven optimization through the authenticated Cursor Agent CLI.
skillopt-sleep run --project "$(pwd)" --source cursor --backend cursor \
  --target-skill-path "$TARGET_SKILL" \
  --max-sessions 5 --max-tasks 3 --progress

# Inspect selections, then apply the reviewed managed proposal.
skillopt-sleep status --project "$(pwd)"
skillopt-sleep adopt --project "$(pwd)" --legacy

For fan-out proposals, use repeatable --skill NAME or --all-skills after review. Bare adopt deliberately refuses a night containing fan-out rows.

Actions are status, harvest, dry-run, run, adopt, schedule, and unschedule.

• Default backend is mock, which is deterministic and makes no provider calls.
• --backend cursor uses the user's authenticated Cursor Agent CLI budget for model-driven mining, replay, judging, and reflection.
• --source cursor reads ~/.cursor/projects/<workspace>/agent-transcripts/*/*.jsonl.
• --cursor-home PATH overrides the Cursor home used for harvesting.
• --scope invoked selects the current workspace; --scope all includes every Cursor workspace.
• --cursor-path PATH or SKILLOPT_SLEEP_CURSOR_PATH selects a non-default cursor-agent executable.
• --model NAME or SKILLOPT_SLEEP_CURSOR_MODEL overrides the Cursor model.
• Check model identifiers with cursor-agent --list-models; when cost matters, verify the billed variant in Cursor's usage reporting.
• Keep live runs bounded with --max-sessions, --max-tasks, and --progress.
• A held-out gain is evidence for that run, not a promise of general improvement.

The first harvest uses a 72-hour lookback. Use --lookback-hours N for a wider initial window or --lookback-hours 0 for all available history. A stateful run, including a no-task run, records a harvest checkpoint; later runs use the checkpoint rather than the initial lookback. Inspect counts with harvest or dry-run before the first real run because those actions do not advance state.

Available backends are:

• mock - deterministic, with no provider calls (default);
• cursor - the authenticated Cursor Agent CLI;
• claude - the authenticated Claude CLI;
• codex - the authenticated Codex CLI;
• copilot - the authenticated GitHub Copilot CLI;
• handoff - prompt/answer files for an interactive agent session;
• azure_openai - the configured Azure OpenAI endpoint.

SkillOpt reads the target skill and inserts its text into replay prompts; it does not invoke the file as a native Cursor skill. Ordinary Cursor backend calls run in a new empty temporary workspace in read-only Ask mode. File reads, file writes, and MCP tools are denied. --project controls harvesting, target files, state, and staging; it is not the Cursor Agent execution workspace.

Cursor tool-aware replay is temporarily disabled pending live Cursor permission-boundary validation. A task containing a tool_called check fails nonzero before Agent mode starts. The failed replay does not add a cache entry, stage, adopt, persist state, or advance the harvest checkpoint. Use another backend for those tasks. Do not claim that repository- or tool-dependent behavior was validated. The current engine does not implement a fresh-worktree replay for Cursor.

A real-backend dry-run still makes provider calls; it only suppresses staging. Session and task limits are workload bounds, not hard limits on calls, tokens, time, or money. Start with small limits.

Reviewable data path

Cursor harvesting retains user/assistant text, tool names, and explicit turn errors while excluding raw tool arguments, tool outputs, and non-message records. Known secret-shaped strings are redacted, but pattern-based redaction cannot guarantee that a transcript is safe to send to a provider.

For sensitive sessions, export tasks before any real-backend replay:

TARGET_SKILL=.cursor/skills/skillopt-sleep-learned/SKILL.md
skillopt-sleep harvest --project "$(pwd)" --source cursor \
  --target-skill-path "$TARGET_SKILL" \
  --max-sessions 5 --max-tasks 3 --output reviewed-tasks.json

Inspect and redact the file, then set its top-level "reviewed" field to true. Only then run:

skillopt-sleep dry-run --project "$(pwd)" --backend cursor \
  --tasks-file reviewed-tasks.json --progress --json

Real backends reject task files that remain unreviewed. Never include raw transcripts, credentials, secrets, or sensitive task content in messages, commits, or generated summaries.

gate_no_regression is a config-only safeguard in ~/.skillopt-sleep/config.json. It defaults to false; set it to true to reject a candidate when any validation task's configured gate score decreases.

Scheduling

Scheduling is opt-in. The scheduler persists project, backend, time, and the optional auto-adopt flag, but not --source, Cursor path/home/model overrides, or --target-skill-path. Before scheduling a Cursor cycle, set at least these values in ~/.skillopt-sleep/config.json:

{
  "transcript_source": "cursor",
  "target_skill_path": ".cursor/skills/skillopt-sleep-learned/SKILL.md",
  "backend": "cursor"
}

Then run:

skillopt-sleep schedule --project "$(pwd)" --backend cursor --hour 3 --minute 17
skillopt-sleep unschedule --project "$(pwd)"

The scheduler uses cron on Unix and Task Scheduler on Windows. Scheduled runs stage proposals by default. Use --auto-adopt only when the user has explicitly requested unattended adoption.

Report results

For dry-run and run, report:

• session and task counts;
• held-out baseline and candidate scores;
• gate action and accepted/rejected edit counts;
• exact proposed edits;
• staging directory, when one was created.

Read staged report.md before summarizing a run. Offer adoption only after the user reviews an accepted proposal that is still staged. Never claim broad improvement from one run.

Hard rules

• Harvest is read-only. Never edit Cursor transcript files.
• Never hand-edit the target skill or CLAUDE.md as a substitute for adoption.
• Do not run a real backend on sensitive content without confirming its data boundary or using the reviewed-task workflow.
• Do not add a session-end hook or imply that installing this plugin schedules anything.
• Show validation evidence before recommending adoption.
• Treat generated edits as proposals, not as source of truth.