RonanCodes/skills/dream

Dream

The factory's nightly self-maintenance. During the day we pile up GitHub issues, wiki edits, new and half-finished skills, notes. Things drift: issues lose their cross-links, docs go stale, a skill that should exist doesn't, a dead one lingers. Dream is the agent that, while Ronan sleeps, walks all of it and makes safe, reversible improvements, then hands him a morning report he can act on in one tap.

It's a member of the local factory (see ~/Dev/ronan-skills/skills/ralph/SKILL.md for the shared artefact conventions). It is explicitly a long unattended run, so the Pushover/Telegram firing rule applies (it pings at the end).

The non-negotiable safety contract

Dream runs unattended, so it is bounded by hard rules. Bake these into every action:

1. Never delete. No rm, no git push --force, no closing issues as "won't fix", no dropping tables/columns, no removing files. Archiving is the strongest removal allowed (see below).
2. Never contact anyone external. No emails, calls, SMS, WhatsApp, no posting to public channels, no messaging teammates/clients, no outbound API that reaches a third party. The ONLY outbound is the morning report to Ronan himself (Telegram + Pushover + local HTML). "Contact people" = external parties, not the owner's own notifications.
3. Everything is reversible and logged. Every change is either a git commit (so git revert / the diff is the undo) or a GitHub issue edit/comment (logged in the issue's history; also record the prior text in the report). Repos are committed (ronan-skills, wiki vaults), so a bad night is always recoverable.
4. Archive ≠ delete, and must be one-command reversible. To retire a skill: move it to archive/<name>/ (or add archived: true + archived-reason: to its frontmatter) in a commit. The report prints the exact un-archive command. Never actually remove it.
5. Bounded. Stop after --max-changes (default 20) distinct changes; if there's more, list the rest as proposals in the report rather than doing them. No runaway churn.
6. Propose, don't impose, for anything irreversible-ish. New skills and archives are fine (reversible); anything that can't be cleanly reverted goes in the report as a proposal for Ronan, not an action.

What it reviews (the sweep)

Point it at the factory with --repos (default: ronan-skills, the LLM-wiki vault(s), and any project repo flagged for dreaming). For each:

• GitHub issues — run /ro:backlog-audit logic: cross-link (parent/blocks/enables), refine priorities, flag dupes/orphans/blocked-by-closed, refresh the canonical backlog map. Fix obviously-stale issue bodies.
• The skills themselves (ronan-skills/skills/*) — find gaps (a process we keep doing by hand that has no skill → draft one), stale instructions (a skill referencing a renamed file/flag), and dead skills (superseded/unused → propose archive). Cross-check against recent commits and notes for "we should have a skill for X".
• LLM wiki — stale pages, decisions captured in chat/issues but not in the wiki (route durable knowledge to /ro:wiki-curator), broken [[links]].
• Notes / memory — reconcile auto-memory and CLAUDE.md against what actually shipped; flag contradictions.

Use sub-agents (Agent) for the heavy reading so the main dream context stays lean; the dream orchestrates and decides.

Actions it MAY take (all reversible)

• Edit/cross-link/relabel GitHub issues; post the backlog map; comment. (Never close/delete.)
• Edit skill files to fix stale references; add new skill files; archive dead ones (move + commit).
• Edit wiki pages / add new ones via /ro:wiki-curator; fix [[links]].
• Commit + push to ronan-skills and wiki vaults (committed repos = safe). Use the repo's commit convention (emoji conventional, no Co-Authored-By; respect commitlint overrides). For project repos: open a PR, never push to main.

The morning dream report

Storage (decided)

• Markdown, committed: ronan-skills/dreams/reports/YYYY-MM-DD-HHMM.md. Committed = durable, tracked, auditable across the whole factory. This is the source of truth.
• HTML, generated + launched, gitignored: same basename .html next to it, built from the markdown, opened on the Mac so it's on screen when Ronan wakes. It's a derived artefact (gitignore dreams/reports/*.html).
• Durable knowledge the dream surfaced (not the run log) goes to the wiki via /ro:wiki-curator; the report itself lives in dreams/.
• Per-project dreams may also drop a copy in that project's gitignored .dreams/, but the canonical archive is ronan-skills/dreams/.

Report content (every change is auditable)

A header (date, repos swept, counts: changed / added / archived / proposed) then one card per change, each with:

• What changed + why, in one line.
• A direct link: the PR URL, the issue URL, or the commit URL (gh/remote) so it's one click to inspect.
• The prior state (old issue text / the file path + commit before) so the undo is obvious.
• A checkbox ("undo this") + a notes textarea.
• For archives: the exact un-archive command.

Interactivity (self-contained HTML, no CDN — strict CSP, per the no-remote-artifact rule)

• Checkboxes + notes persist in localStorage.
• A "Copy undo prompt" button assembles a ready-to-paste prompt for a fresh Claude session from the checked items: it lists each change with its commit/issue + the precise reversal (git revert <sha>, gh issue edit … --body-file <prior>, un-archive git mv), plus any notes Ronan typed. He checks what to roll back, clicks Copy, pastes into a new session, done.
• Inline lucide SVGs only, no emojis in the HTML chrome.

A starter generator lives at scripts/render-report.sh (markdown + an actions JSON → the interactive HTML). Keep the actions list as structured JSON during the run so the HTML is deterministic.

Notifications (to Ronan only)

At the end: open the HTML locally, then fire both /ro:pushover and /ro:telegram with a one-line summary (changed/added/archived/proposed counts) and --url file://<the-html> so the phone notification deep-links to the report. Message shape: state + counts + "review + copy-undo-prompt in the report."

Cron (optional, Ronan sets it up)

Dream is meant to fire ~3am nightly. Wire it with /schedule (cloud routine) or a local launchd/cron calling claude -p "/ro:dream". --no-cron skips any cron interaction. Don't install a cron silently; offer it and let Ronan confirm. A scheduled headless run may lack interactively-authed MCP servers, degrade gracefully.

Run shape

1. Resolve --repos; for each, fan out reader sub-agents (issues / skills / wiki / notes).
2. Collect candidate changes; classify reversible-action vs propose-only; cap at --max-changes.
3. Apply reversible actions (commits / PRs / issue edits), recording each into the actions JSON with its link + prior state.
4. Write the markdown report → render the HTML → open it.
5. Fire Pushover + Telegram with the deep link.
6. --dry-run: do the sweep + write the report of what it WOULD do, change nothing.

Guardrails recap

Never delete · never contact external parties · cap changes · archive reversibly · everything committed/logged · propose anything not cleanly undoable · the only outbound is the morning report to Ronan.