dream

name	dream
description	Mine generalizable feedback patterns from recent coding-agent sessions via the agent-dreamer CLI and triage them one by one into context improvements for AGENTS.md, CLAUDE.md, project rules, or skills. Use when you want to reflect on recent work and extract preferences worth persisting across sessions.
license	CC-BY-4.0
metadata	{"tags":["productivity","reflection","autonomous"],"version":"5.1.0","author":"whistler"}

Dream — Session Feedback Mining

Use this skill when the user wants to reflect on recent work and extract patterns worth persisting. The goal is surfacing what is operative but unstated — preferences and redirections that should shape future agent behavior, but haven't been written down yet.

This skill ships no code. It is instructions plus CLI calls to agent-dreamer; all deterministic extraction, validation, identity, scope, and ledger I/O live in the package. LLM judgment (classify, canonicalize, per- pattern triage, file edits) runs on the hosting agent.

Trigger

/dream or "review my recent feedback" or "what should we learn from the last few sessions"

Optional: /dream --days 14 — pass --days N to dreamer exchanges and dreamer signals list.

Process

Mining uses the package CLI for all deterministic work; the agent owns the LLM steps (classify, canonicalize) and the triage conversation:

1. dreamer init
2. dreamer exchanges --new-only --json > snapshot file
3. agent classifies new exchanges → SignalRecord JSON (signals only, no empty records)
4. dreamer signals add <file> --processed <snapshot>[:<start>:<end>]
5. dreamer signals list --min-confidence 3 --json
6. agent canonicalizes patterns → PatternInput JSON (evidence by item_id)
7. dreamer patterns add <file>
8. triage each new pattern one by one → dreamer patterns mark <id> approved|monitor|rejected
9. apply approved patterns → dreamer patterns mark <id> applied --file PATH

Step 0 — Preflight

which dreamer

If missing, install the package:

pipx install agent-dreamer

Then bootstrap cass and the search index in one deterministic step:

dreamer init

dreamer init installs cass-search via pipx if cass is not on PATH, then runs cass index if the index is empty, incomplete, or older than 24 hours. It prints the resolved state paths when done. Re-run it any time; it is idempotent and safe to call even when everything is already fresh (--force forces a re-index).

Read package version and confirm state paths:

dreamer status --json

• version — if later CLI commands fail with unknown subcommands or flags, offer pipx upgrade agent-dreamer.
• state_paths — note where signals.json, patterns.json, and ledger.json live (default ~/.dreamer/; override with DREAMER_PATTERNS_PATH).

Do not embed SQL, Python extraction scripts, or direct reads of cass storage in this skill. Extraction is always dreamer exchanges.

Step 1 — Mine new exchanges

Pull exchanges not yet classified (the package tracks what has been processed in classified.json, so --new-only is the freshness check — no mtime comparisons needed) and save the snapshot to a file; Step 2 references it by index range:

dreamer exchanges --new-only --json > /tmp/dream_exchanges.json
# optional window: dreamer exchanges --days 14 --new-only --json > /tmp/dream_exchanges.json

Report count and the date window to the user. If count is 0, there is nothing new to mine: skip classification and go to Step 4 (there may still be untriaged patterns from prior runs — this also covers the case where a headless dreamer run --yes --json already mined before this session).

If count is large (> 50), prefer cheap-model subagents for classification (Step 2) and mention the batch plan before proceeding.

Step 2 — Classify signals (agent LLM)

For each exchange in the snapshot, decide whether the user's follow-up reveals a signal worth persisting. Produce SignalRecord JSON — a JSON array written to a temp file (e.g. /tmp/dream_signals.json).

SignalRecord shape — one object per exchange that has at least one signal. Do not emit records with an empty signals: [] array, and do not emit workspace_path (the package fills it from the cass DB). Exchanges with no signal are tracked via --processed below, not via placeholder records:

[
  {
    "conversation_id": "<from exchange>",
    "message_id": "<from exchange>",
    "signals": [
      {
        "signal_text": "<concrete, evidence-tied description>",
        "confidence": 4
      }
    ]
  }
]

Flag an exchange when the follow-up shows one of:

• Failure pattern — wrong approach, broken output, misread intent, ignored convention. Capture what failed and what the user expected instead.
• Repeated behaviour — an instruction the user shouldn't have to keep typing: tool choices, setup steps, workflow rituals, structure reminders.
• User frustration — curt or irritated replies, "again", "I already said", abandoning or undoing the agent's work. Capture the unmet expectation, not the frustration itself.
• Standing preference — style, naming, structure, or communication taste stated even when nothing went wrong.
• Confirmed approach — explicit approval of a non-obvious choice.

Do not flag one-off task instructions. confidence is 1–5: how sure you are this is a real, durable signal likely to recur (5 = unambiguous, 1 = weak hunch). Signals below 3 are still worth recording, but the package excludes them from canonicalization.

Classification rules:

• 20 or fewer exchanges: classify inline.
• More than 20: split into batches and classify in parallel via Haiku-class subagents. Use judgment for batch size and count — there is no fixed formula. Prefer fewer, larger batches (keep parallel subagents in the single digits to low teens even at high volume), but keep each batch small enough that a subagent reads every exchange carefully rather than skimming.
• Give each batch a contiguous index range of the exchanges array in /tmp/dream_exchanges.json (e.g. batch 2 = exchanges 100–199) so its coverage can be recorded by range.

Persist each batch's validated records and mark its range processed in one call (all-or-nothing — if any record fails validation, nothing is written and the error lists every failing record so you can fix them in one pass and re-submit):

dreamer signals add /tmp/dream_signals_batch2.json --processed /tmp/dream_exchanges.json:100:200

The range is a Python-style slice (start inclusive, end exclusive) into the snapshot's exchanges array. The package expands it to exchange ids and records them in classified.json, so zero-signal exchanges are never re-classified — without listing ids or writing empty records. Omit the range (--processed /tmp/dream_exchanges.json) to mark the whole file; a batch with zero hits still needs the call — pass a signals file containing [].

Step 3 — Canonicalize patterns (agent LLM)

Load the numbered signal items for canonicalization (the package pre-filters low-confidence signals with --min-confidence):

dreamer signals list --min-confidence 3 --json
# optional window: dreamer signals list --days 14 --min-confidence 3 --json

Work from the items array: each item has a stable item_id plus its signal_text. Group items by underlying cause (not surface wording). Only promote a group to a pattern if it spans ≥ 2 distinct conversations. Word each instruction to prevent the problem going forward, not to describe what went wrong.

Produce PatternInput JSON — a JSON array written to a temp file (e.g. /tmp/dream_patterns.json). Reference evidence by item_id; do not transcribe conversation ids, message ids, signal text, or workspace paths — the package expands the ids, verifies them against the signal cache, and computes distinct_conversation_count itself:

[
  {
    "title": "<short specific name>",
    "suggested_instruction": "<rule to add to agent context>",
    "rationale": "<why this is real and actionable>",
    "evidence_item_ids": [0, 4, 17]
  }
]

Persist validated patterns (also all-or-nothing — hallucinated item ids, evidence not in the signal cache, or patterns spanning fewer than 2 distinct conversations are all rejected with per-pattern errors; the package computes id, scope, and projects, and reconciles the ledger):

dreamer patterns add /tmp/dream_patterns.json

Step 4 — Inventory context files

Before triaging, glob the current working directory:

• AGENTS.md
• CLAUDE.md
• CLAUDE.local.md
• .claude/rules/
• .claude/skills/
• .agents/skills/
• .cursor/rules/
• GEMINI.md
• docs/

Read files that exist. Destination selection follows the policy below.

Destination policy

Two judgments decide where a pattern lands. Make both explicitly in the triage pitch.

1. Project or global? The package computes scope mechanically: evidence spanning ≥ 2 distinct projects → global, else project. Treat that as a prior, not a verdict. Judge from the content whether the instruction is inherently universal (communication style, workflow rituals, tool choices) or bound to a stack or codebase (naming in one repo, a framework convention). A rule seen in two Python repos may still be project-shaped; a rule seen mostly in one repo may clearly be a universal preference. When content and computed scope disagree, follow the content and note the override in the pitch.

2. Generic or harness-specific? Would any coding agent benefit (generic), or does it concern one harness's features — Claude Code hooks, a Cursor setting, a Codex behavior (harness-specific)? Generic rules go in shared AGENTS.md-style files; harness-specific rules go in that harness's own file.

Destinations by quadrant:

• Project + generic → repo-root AGENTS.md (read natively by Codex, Cursor, Gemini CLI, and most other harnesses — it is the cross-tool standard at project level). Claude Code does not read AGENTS.md; bridge with an import, never a copy: ensure CLAUDE.md contains the line @AGENTS.md (create a CLAUDE.md holding just that line if the file is missing). Never write the same rule into both files.
• Project + harness-specific → that harness's project file: CLAUDE.md (below the import line), .claude/rules/, .cursor/rules/, GEMINI.md.
• Global + generic → ~/.agents/AGENTS.md. There is no cross-agent global AGENTS.md standard — each harness reads only its own global file (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, ~/.gemini/GEMINI.md) — so keep one canonical file next to ~/.agents/skills/ (the existing cross-agent source of truth) and wire each installed harness to it once, on first global apply:
  • ~/.claude/CLAUDE.md → add the import line @~/.agents/AGENTS.md
  • ~/.gemini/GEMINI.md → add the import line @~/.agents/AGENTS.md (use an absolute path if ~ does not resolve)
  • ~/.codex/AGENTS.md → no import syntax; append the directive Read and follow ~/.agents/AGENTS.md. once
  • Only wire harnesses whose config directory exists. Prefer import/directive lines over symlinks: the per-harness files carry harness-specific content of their own, and a symlink forces all-or-nothing.
• Global + harness-specific → that harness's global file directly. Global skills go to ~/.agents/skills/ (never ~/.claude/skills/, which is symlinks into it).

Step 5 — Triage new patterns one by one

Load the cwd-filtered worklist (rejected excluded by default):

dreamer patterns list --project "$PWD" --json

Each pattern includes ledger status, deterministic id, scope, and projects. Focus this step on patterns with status new — applied, verified, and regressed patterns don't need triage.

For each new pattern, present it on its own — evidence, proposed context change, and destination — then ask before moving to the next one. This keeps the plan from turning into a wall of text the user has to hold in their head all at once, and lets an early "reject" stop you from over-thinking patterns that were never going to survive review.

Check the relevant destination file (from Step 4) before claiming coverage status — do not say something is missing without reading the file first.

Format per pattern:

### <title> (`<id>`)
> <suggested_instruction>
>
> Why: <rationale>
> Scope: <global|project> · <N> conversations [· overriding computed scope because <reason>]
> Applies to: all agents | <harness> only
> Evidence: "<quote>" / "<quote>"
> Destination: `<file path>` — <section>
> Coverage: NEW | ALREADY COVERED | PARTIALLY COVERED

Then offer, as one grouped in-chat question (≤4 options):

• Approve — ready to apply this session (or next): dreamer patterns mark <id> approved
• Monitor — plausible but thin evidence; keep accumulating and re-pitch later without re-litigating it now: dreamer patterns mark <id> monitor
• Reject — not a valid pattern; never re-pitched: dreamer patterns mark <id> rejected
• Adjust — talk through a wording or destination change, then edit before marking: dreamer patterns update <id> --instruction "<revised text>" (also accepts --title / --rationale), followed by approved

Record the decision immediately after each pattern — do not batch decisions into one big set of instructions at the end. If the ledger has the decision, the user can stop and resume the loop at any point without re-answering already-triaged patterns.

Large backlog (first run, many new patterns): one-by-one chat triage doesn't scale past ~6-8 patterns. Hand off to the dashboard instead:

dreamer serve          # opens /feedback with status badges + bulk Approve/Monitor/Reject

Tell the user: "I've opened the Dreamer dashboard. Use the checkboxes plus the bulk bar, or the per-pattern buttons, to Approve, Monitor, or Reject each pattern. Tell me done when you've finished triage and I'll continue from the ledger."

When they say done, re-enter the loop with dreamer patterns list --json (which honors ledger state) and proceed to Step 6 for any approved patterns. Do not re-pitch rejected patterns; leave monitor patterns for a future run.

Step 6 — Apply approved patterns

For each pattern marked approved this session that the user wants applied now:

1. Read the target file
2. Find the section where it fits; weave into existing content rather than creating a new section for a single bullet
3. Edit the file
4. Record the applied edit in the ledger:

dreamer patterns mark <id> applied --file PATH
# optional after commit: dreamer patterns mark <id> applied --file PATH --commit SHA

Destination comes from the triage pitch, per the Destination policy in Step 4. Bridge edits (adding an @AGENTS.md import to CLAUDE.md, wiring ~/.agents/AGENTS.md into installed harnesses) happen here too, the first time a pattern lands in a shared file.

Do not duplicate. If a pattern already exists in near-identical form, skip the edit and say so.

Report one line per file changed.

What to look for

Patterns often appear as:

• Failure corrections — the agent got it wrong the same way more than once
• Repeated instructions — the user keeps typing the same tool choice, setup step, or workflow reminder across sessions
• Frustration markers — "again", "I already said", curt replies, undone agent work
• Simplification requests — "why so many X?", "can we consolidate?"
• Rename requests — a name doesn't carry the right meaning
• Redirect mid-task — user stops a direction and pivots
• Repeated clarifying questions — the docs aren't pre-answering them
• Approval of a non-obvious choice — confirmed approaches matter as much as corrections

Scope

Dream is about persistent behavioral change. Don't capture:

• One-off task details or ephemeral state
• Patterns already present in the destination file
• Vague observations without concrete evidence
• Signals that appear in only one conversation
• Harness-generated noise (interruption markers, cancellation plumbing)

Maintainer dry-run

Use an isolated state directory to verify the CLI contract without touching production ~/.dreamer/:

export DREAMER_PATTERNS_PATH=/tmp/dreamer-test/patterns.json
mkdir -p /tmp/dreamer-test

# 1. Preflight
dreamer init
dreamer status --json

# 2. Exchanges (requires cass indexed on the machine)
dreamer exchanges --new-only --json | head

# 3. Add fixture signals (two conversations — patterns need ≥ 2)
cat > /tmp/dreamer-test/incoming_signals.json <<'EOF'
[
  {
    "conversation_id": "1",
    "message_id": "10",
    "workspace_path": "/tmp/project-a",
    "signals": [
      {
        "signal_text": "Run verification before claiming completion.",
        "confidence": 4
      }
    ]
  },
  {
    "conversation_id": "2",
    "message_id": "20",
    "workspace_path": "/tmp/project-a",
    "signals": [
      {
        "signal_text": "You said it was done but tests were not run.",
        "confidence": 4
      }
    ]
  }
]
EOF
dreamer signals add /tmp/dreamer-test/incoming_signals.json
dreamer signals list --min-confidence 3 --json   # note the item_id values

# 4. Add fixture patterns by item_id (evidence expansion, conversation count,
#    ids, and scope all computed by the package)
cat > /tmp/dreamer-test/incoming_patterns.json <<'EOF'
[
  {
    "title": "Verify before completion",
    "suggested_instruction": "Run verification before claiming the task is done.",
    "rationale": "Repeated correction across sessions.",
    "evidence_item_ids": [0, 1]
  }
]
EOF
dreamer patterns add /tmp/dreamer-test/incoming_patterns.json

# 5. Query, triage, apply
dreamer patterns list --project /tmp/project-a --json
dreamer patterns mark <id-from-output> approved
dreamer patterns mark <id-from-output> applied --file AGENTS.md

# 6. Confirm the skill doc ships no embedded extraction logic (no inline SQL,
#    Python scripts, or direct cass storage reads).
# 7. Confirm all public CLI seams are documented in skills/dream/SKILL.md

Run the package test suite after skill changes:

uv run pytest