mirror-mind 0.0.1 → 0.32.1

package/plugins/mirror-mind/skills/mm-consolidate/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: "mm:consolidate"
+description: Scans memories for recurring patterns and proposes consolidation (merge, identity update, or shadow candidate)
+user-invocable: true
+---
+
+# mm-consolidate
+
+Consolidation as integration — the operation that promotes raw extracted memories into
+structural identity content (CV7.E4.S3).
+
+Memories accumulate over time. Patterns repeat. The same insight lands in five conversations
+as five isolated memories, none of which reaches the identity layer where it could actually
+change how the mirror responds. Consolidation is the bridge. This skill surfaces those
+clusters, proposes a structural move, and waits for explicit acknowledgment before writing
+anything.
+
+**Promotion mechanism: manual-by-acknowledgment.** The scan is automatic; the promotion is not.
+Every proposal must be reviewed and accepted (or rejected) before it changes the database.
+This is intentional — identity updates are meaningful acts.
+
+---
+
+## Usage
+
+```
+/mm:consolidate [--journey <slug>] [--layer <layer>] [--limit <n>]
+/mm:consolidate apply <proposal_id>
+/mm:consolidate reject <proposal_id>
+/mm:consolidate list [--status pending|accepted|rejected]
+```
+
+---
+
+## 1. Scan for proposals
+
+> The scan answers from TypeScript against the live provider (CV22.DS8.TS2). Each cluster is one model call bounded by the extraction timeout (`MEMORY_LLM_TIMEOUT_EXTRACTION`, 60 s) with bounded retries, and every successful call leaves a priced `llm_calls` row before its proposal is parsed. A call that fails is logged by class (`outcome=transport_failed kind=…`) in `front-door.log` beside the database.
+
+```bash
+mirror consolidate scan \
+  [--journey <slug>] \
+  [--layer <layer>] \
+  [--limit 5] \
+  [--threshold 0.75]
+```
+
+This clusters semantically similar memories and calls the LLM to propose one of:
+- **merge**: distill a redundant cluster into one sharper memory
+- **identity_update**: encode a persistent pattern into an identity layer (ego/behavior, etc.)
+- **shadow_candidate**: mark a tension/avoidance cluster for the mm-shadow pass
+
+Each proposal is printed and stored with `status='pending'`.
+
+**Default filters:** no journey or layer filter (all memories). Threshold 0.75. Limit 5 proposals.
+
+---
+
+## 2. Present each proposal to the user
+
+For each proposal, show:
+- The source memories (title, type, date)
+- The proposed action and target (if identity_update: which layer/key)
+- The rationale
+- The proposed content
+
+Ask: **accept as-is / edit / reject?**
+
+---
+
+## 3. Apply or reject
+
+**Accept as-is:**
+```bash
+mirror consolidate apply <proposal_id>
+```
+
+**Accept with edited content:**
+```bash
+mirror consolidate apply <proposal_id> \
+  --content "User-revised version of the proposed content"
+```
+
+**Reject:**
+```bash
+mirror consolidate reject <proposal_id>
+```
+
+What happens on acceptance:
+- **merge**: creates a merged memory; source memories advance to `integrated`
+- **identity_update**: appends to the identity layer; source memories advance to `acknowledged`
+- **shadow_candidate**: source memories advance to `candidate` for the next mm-shadow pass
+
+Rejected proposals leave source memories unchanged.
+
+---
+
+## 4. List consolidation history
+
+```bash
+mirror consolidate list [--status pending|accepted|rejected] [--limit 20]
+```
+
+---
+
+## Notes
+
+- The skill uses the same model as extraction (Gemini Flash via OpenRouter). LLM calls are
+  logged to `llm_calls` when `MEMORY_LOG_LLM_CALLS=1`.
+- Proposal IDs can be abbreviated to their first 8 characters.
+- Memories with `readiness_state='integrated'` are excluded from clustering.
+- Run with `--threshold 0.65` to surface more (and looser) clusters; raise to `0.85` for tighter ones.
+- For shadow-specific work, use `mm-shadow` (CV7.E4.S4) after candidates are established.

package/plugins/mirror-mind/skills/mm-consult/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: "mm:consult"
+description: Asks other LLMs through OpenRouter with Mirror context
+user-invocable: true
+---
+
+# Consult
+
+Sends prompts with Mirror identity context to other models through OpenRouter.
+
+## Syntax
+
+```
+/mm:consult <family> [tier] ["question"]
+/mm:consult credits
+```
+
+- **family:** `gemini`, `grok`, `deepseek`, `openai`, `claude`, `llama`, or a direct model ID such as `google/gemini-2.5-pro`
+- **tier:** `lite` (default), `mid`, `flagship`
+- **question present:** send it directly
+- **question missing:** synthesize the current conversation and create the prompt
+
+## Flow
+
+> The model call answers from TypeScript, bounded by the extraction timeout (`MEMORY_LLM_TIMEOUT_EXTRACTION`, 60 s) with bounded retries. (The 10-minute ceiling CR072 added applied only to the Python engine, which is gone.)
+
+### Explicit Question
+
+Analyze the message to determine persona and journey using the same Mirror routing.
+
+```bash
+mirror consult FAMILY TIER "QUESTION" \
+  [--persona PERSONA] [--journey JOURNEY] [--org]
+```
+
+**Examples:**
+- `/mm:consult gemini lite "draft an opening for this article"` -> `mirror consult gemini lite "draft an opening for this article" --persona writer`
+- `/mm:consult deepseek "is this design overengineered?"` -> `mirror consult deepseek "is this design overengineered?" --persona engineer`
+
+The script prints the response, cost, and balance. Always show the complete response to the user without summarizing or omitting it. Any Claude comments come after the full response.
+
+### No Question
+
+When the user omits the question, they want a second opinion on the current conversation. Synthesize only Mirror Mode content: reflection, strategy, and content. Ignore Builder Mode content such as code, debugging, and project architecture.
+
+1. Synthesize the context into a self-contained prompt: topic, goal, relevant journey/attachments/references, what was discussed or decided, and what the user is asking now.
+2. Formulate a clear request for the external LLM.
+3. Send it as an ask:
+
+```bash
+mirror consult FAMILY TIER "SYNTHESIZED_PROMPT" \
+  [--persona PERSONA] [--journey JOURNEY] [--org]
+```
+
+The synthesized prompt must be self-contained. The external LLM has no access to the conversation, so include concrete details instead of vague references like "as discussed."
+
+Example prompt:
+
+```
+I am preparing episode 5 of the Reflexo series, about leadership and complexity.
+The episode covers [key script points]. I have already suggested topics A, B, and C.
+
+Suggest 3 alternative article topics for software leaders, keeping depth without academicism.
+```
+
+## Credits
+
+```bash
+mirror consult credits
+```
+
+Shows OpenRouter usage and remaining balance.
+
+## Available Families And Tiers
+
+| Family | Lite | Mid | Flagship |
+|---------|------|-----|----------|
+| gemini | gemini-2.5-flash-lite | gemini-2.5-flash | gemini-2.5-pro |
+| grok | grok-3-mini | grok-3 | grok-4.1-fast |
+| deepseek | deepseek-chat | deepseek-v3.2 | deepseek-r1 |
+| openai | gpt-5.4-nano | gpt-5.4-mini | gpt-5.4 |
+| claude | haiku-4.5 | sonnet-4.6 | opus-4.6 |
+| llama | llama-3.3-70b-instruct | llama-4-scout | llama-4-maverick |

package/plugins/mirror-mind/skills/mm-conversations/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: "mm:conversations"
+description: Lists recent conversations from the memory database
+user-invocable: true
+---
+
+# Conversations
+
+When receiving `/mm:conversations`, run:
+
+```bash
+mirror conversations [--limit N] [--journey ID] [--persona ID]
+```
+
+If `$ARGUMENTS` contains a filter such as a journey slug, use it as `--journey`.
+
+Present the result to the user. Mention that `/mm:recall <id>` loads a conversation.

package/plugins/mirror-mind/skills/mm-discard/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: "mm:discard"
+description: Discards the current runtime conversation from the Mirror database before quitting
+user-invocable: true
+---
+
+# Discard Current Conversation
+
+Use when the user wants to quit a test session without keeping the current
+conversation in the Mirror database.
+
+Natural language examples:
+
+```text
+quit and discard this conversation
+close without saving this conversation
+exit and drop this conversation
+```
+
+## 1. Discard Current Conversation
+
+Run:
+
+```bash
+mirror conversation-logger discard-current --interface claude_code
+```
+
+The command deletes the current conversation and marks the runtime session so the
+assistant confirmation is not logged and transcript backfill skips it at session
+end.
+
+## 2. Tell the User to Quit
+
+After the command succeeds, answer briefly:
+
+```text
+Current conversation discarded from the database. You can safely exit the session now.
+```
+
+Do not call `mirror log` for this skill.

package/plugins/mirror-mind/skills/mm-explore/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: "mm:explore"
+description: Activates Explorer Mode for a journey and loads exploratory context
+user-invocable: true
+---
+
+# Explorer Mode
+
+Activates Explorer Mode for a specific journey. Explorer Mode is a Mirror-native
+lens for uncertainty before construction.
+
+Explorer Mode is active and supports durable exploration, story thickening,
+attractors, experiment proposals, and Builder handoff.
+
+## Usage
+
+```text
+/mm:explore <journey-slug>
+```
+
+Natural-language equivalents should be treated as the product interface:
+
+```text
+enter explorer mode for this journey
+open exploration for <journey-slug>
+```
+
+## 1. Activate Explorer Mode
+
+```bash
+mirror explore load <slug>
+```
+
+The command:
+
+- activates `△ Explorer Mode` for the journey;
+- renders the Mode Transition Surface (`△ EXPLORER MODE ACTIVE`);
+- sets the journey as sticky context;
+- loads Mirror identity and journey context;
+- resumes the active durable Exploratory Story when one exists;
+- renders `△ EXPLORATORY STORY RESUMED` when resuming;
+- prints Explorer Mode guidance with the active Explorer capability boundary.
+
+## 1.1 Required Surface Rendering
+
+The `explore load` output includes the conversational transition surface. Render
+that surface visibly to the user before continuing with exploratory work. Do not
+recreate it from scratch unless the command failed to render it; copy the
+rendered surface from the command output.
+
+After any `mirror explore story ...` command that returns a
+Mirror surface, paste the returned surface as the first visible block in the
+response. Do not summarize, interpret, or paraphrase before rendering it.
+
+Some Explorer story commands wrap required product surfaces with machine-readable
+contract markers:
+
+```text
+[[MIRROR_REQUIRED_SURFACE_BEGIN:<surface-id>]]
+...
+[[MIRROR_REQUIRED_SURFACE_END:<surface-id>]]
+```
+
+When markers are present, render the marked `Mirror` surface content first and do
+not render the marker lines themselves. The markers are a runtime contract, not
+user-facing product copy.
+
+For `story open`, `story thicken`, `story snapshot`, `story attractors`, `story
+experiment`, `story list`, `story archive`, and `story handoff`, the returned
+`△ ...` surface is the primary response. Render it before commentary. Commentary
+may follow only after the surface is visible.
+
+## 2. Work In Explorer Mode
+
+Explorer Mode is active and supports durable exploration, story thickening,
+attractors, experiment proposals, and Builder handoff.
+
+Explorer preserves uncertainty. Builder executes commitment.
+
+While Explorer Mode is active:
+
+- Treat new substantive material as part of the current Exploratory Story unless the user asks for a clear operational action.
+- Preserve tensions, hypotheses, corrections, and emerging story shape.
+- When an Exploratory Story begins, open it with:
+
+```bash
+mirror explore story open <slug> --story "..." --summary "..." --last-card "..."
+```
+
+- Before calling `story thicken`, classify the change as either `narrative/substantive` or `local/refinement`.
+
+- When material substantively changes the accumulated Exploratory Story, thicken it with:
+
+```bash
+mirror explore story thicken <slug> --story "..." --summary "..." --last-card "..." --changed "..."
+```
+
+Use `story thicken` for:
+
+- new or changed attractor;
+- new or changed exploratory hypothesis;
+- new or changed ritual, voice, scope, or product concept;
+- changed experiment or promotion boundary;
+- meaningful correction to the narrative arc.
+
+Do not use `story thicken` for local refinements:
+
+- icon choice;
+- microcopy;
+- wording polish;
+- visual label changes;
+- surface formatting;
+- small naming adjustments that do not change the story;
+- conversational elaboration of an already captured idea.
+
+For local refinements, continue the conversation without updating the story. If uncertain, ask the user whether to preserve the change in the Exploratory Story.
+
+- When the user asks for the attractor, or when a strong directional pull should be proposed visibly, render attractors with:
+
+```bash
+mirror explore story attractors <slug> --attractor "..." --description "..." --status proposed
+```
+
+- When the user corrects an attractor, replace it with the corrected attractor using the same command. Do not accumulate hidden competing interpretations.
+- When the user asks what small experiment tests the attractor, render an experiment proposal with:
+
+```bash
+mirror explore story experiment <slug> --title "..." --description "..." --status proposed
+```
+
+- When the user asks what is currently being explored, render a snapshot with:
+
+```bash
+mirror explore story snapshot <slug>
+```
+
+- When the user asks to see explorations for the active journey, render durable story visibility with:
+
+```bash
+mirror explore story list <slug>
+```
+
+- When the user asks to archive or close the active exploration without promoting it, archive the active story with:
+
+```bash
+mirror explore story archive <slug>
+```
+
+- Render the story surface returned by those commands visibly to the user.
+- Do not promote to Builder or Delivery without explicit user confirmation.
+
+## 2.1 Operational Boundary
+
+Explorer Mode must not directly execute clear operational mutation requests.
+When the user asks to edit files, apply a procedure to documents, create code,
+run implementation commands, mutate roadmap/docs/code, or otherwise change
+project state, do not call Explorer story commands and do not mutate files.
+
+Instead, name the boundary visibly and ask whether to switch to Builder Mode for
+the same journey. Use this response shape:
+
+```text
+△ EXPLORER → BUILDER BOUNDARY
+
+This is operational Builder work, not exploratory thickening. Explorer preserves uncertainty; Builder executes commitment. I can switch to Builder Mode for <slug> and do this there.
+```
+
+Only after the user confirms the switch should Mirror activate Builder Mode with:
+
+```bash
+mirror build load <slug>
+```
+
+Local refinements to the exploration itself, such as microcopy discussion,
+labels, wording, icons, or formatting, remain conversational unless the user
+explicitly asks to preserve them in the Exploratory Story.
+
+## 3. Deactivation
+
+The user should use natural language:
+
+```text
+exit explorer mode
+return to normal mode
+```
+
+Mirror should then call the contained Explorer operation:
+
+```bash
+mirror explore deactivate
+```
+
+Render the deactivation confirmation visibly to the user. Deactivation leaves the
+explicit Explorer lens and returns to Mirror Mode when journey context remains
+active. It does not clear sticky journey context or promote the exploration to
+Builder. Rendering and clearing the status bar are internal effects, not
+user-facing operations.
+
+## 4. Promotion Boundary
+
+When the user says:
+
+```text
+promote this exploration to construction
+promote to builder
+is this ready to become Builder?
+```
+
+Do not switch to Builder silently. First produce a transfer document set and
+render the handoff proposal. If the user asks to include source conversations,
+confirm which conversations should be included before adding raw source evidence.
+When the user names the current or recent conversation rather than an id, inspect
+recent journey conversations with `mirror conversations --journey
+<slug> --limit 5`, show the candidate source evidence, and ask for confirmation.
+Use `--source-conversation <conversation-id>` for reviewed source evidence. Use
+`--include-full-conversation` only after explicit confirmation that raw
+conversation evidence should be written with privacy obfuscation.
+
+```bash
+mirror explore story handoff <slug> --title "..." --summary "..." --editorial-synthesis "..." --source-conversation "<conversation-id>:origin conversation" --include-full-conversation
+```
+
+Render `△ BUILDER HANDOFF PROPOSED` visibly, including the generated document
+paths under `docs/project/explorations/<exploratory-story-slug>/` when available:
+
+```text
+index.md
+exploratory-story.md
+handoff-info.md
+product-design-proposal.md
+full-conversation.md        # only after explicit confirmation
+```
+
+Ask for explicit confirmation. Only after the user confirms should Mirror call:
+
+```bash
+mirror explore story promote <slug>
+```
+
+Promotion activates Builder Mode through the normal Builder load path. If the
+user does not confirm, remain in Explorer Mode and continue thickening the story.

package/plugins/mirror-mind/skills/mm-help/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: "mm:help"
+description: Shows available Mirror Mind commands and how to use them
+user-invocable: true
+---
+
+# Help
+
+Show the user the available commands in this format:
+
+## Available Commands
+
+### Mirror Mode
+
+| Command | What it does |
+|---------|-----------|
+| `/mm:mirror` | Activates Mirror Mode manually |
+| | `--persona ID` - specific persona |
+| | `--journey ID` - journey context |
+| | `--query "terms"` - relevant attachment search |
+| | `--org` - include organization identity |
+| `/mm:consult <family> "question"` | Asks another LLM with Mirror context |
+| | Families: `gemini`, `grok`, `deepseek`, `openai`, `claude`, `llama`, or direct model ID |
+| | `[tier]` — lite (default), mid, flagship |
+| | `--persona`, `--journey`, `--query`, `--org` |
+| `/mm:consult <family>` | Sends the current conversation to another model |
+| `/mm:consult credits` | Shows OpenRouter balance |
+
+### Journeys
+
+| Command | What it does |
+|---------|-----------|
+| `/mm:journeys` | Lists journeys with status and current stage |
+| `/mm:journey [id]` | Shows detailed status for one journey or all journeys |
+| | If the journey has `sync_file`, reads from the external file |
+
+### Memories And Journal
+
+| Command | What it does |
+|---------|-----------|
+| `/mm:memories` | Lists recorded memories |
+| | `--type TYPE` — decision, insight, idea, journal, tension, learning, pattern, commitment, reflection |
+| | `--layer LAYER` — self, ego, shadow |
+| | `--journey ID` - filter by journey |
+| | `--search "text"` - semantic search |
+| | `--limit N` - maximum results (default: 20) |
+| `/mm:journal "text"` | Records a personal journal entry |
+| | `--journey ID` - associate with a journey |
+
+### Tasks
+
+| Command | What it does |
+|---------|-----------|
+| `/mm:tasks` | Lists open tasks |
+| | `--journey SLUG` - filter by journey |
+| | `--status STATUS` — todo, doing, done, blocked |
+| | `--all` - include completed tasks |
+| `/mm:tasks add "title"` | Creates a task |
+| | `--journey SLUG`, `--due YYYY-MM-DD`, `--stage STAGE` |
+| `/mm:tasks done ID` | Marks a task as completed |
+| `/mm:tasks doing ID` | Marks a task as in progress |
+| `/mm:tasks block ID` | Marks a task as blocked |
+| `/mm:tasks delete ID` | Removes a task |
+| `/mm:tasks import [slug]` | Imports pending tasks from journey paths |
+| `/mm:tasks sync [slug]` | Syncs tasks from an external file |
+| `/mm:tasks sync-config SLUG /path` | Configures the reference file for sync |
+
+### Weekly Planning
+
+| Command | What it does |
+|---------|-----------|
+| `/mm:week` | Shows the current week view |
+| `/mm:week "free text"` | Ingests a weekly plan and asks confirmation before saving |
+
+### Conversations And Logging
+
+| Command | What it does |
+|---------|-----------|
+| `/mm:save [slug]` | Saves the latest turn as Markdown in the conversation exports directory |
+| | `--full` - save the full conversation |
+| `/mm:conversations` | Lists recent conversations |
+| | `--limit N`, `--journey ID`, `--persona ID` |
+| `/mm:recall ID` | Loads a previous conversation into context |
+| | `--limit N` - maximum messages (default: 50) |
+| `/mm:new` | Starts a new conversation |
+| `/mm:mute` | Toggles conversation logging |
+
+### System
+
+| Command | What it does |
+|---------|-----------|
+| `/mm:backup` | Backs up the memory database |
+| `/mm:seed` | Seeds identity files from the active user home into the database |
+| `/mm:release-notes [latest|vX.Y.Z]` | Shows Mirror Mind release notes |
+| `/mm:help` | Shows this list |
+
+## Operating Modes
+
+Mirror has two automatically activated modes:
+
+- **Mirror Mode**: personal, work, strategy, writing, mentoring
+- **Builder Mode**: code, architecture, bugs, development
+
+When uncertain, ask which mode to use.

package/plugins/mirror-mind/skills/mm-identity/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: "mm:identity"
+description: Read and update identity directly in the database
+user-invocable: true
+---
+
+# Identity
+
+After the initial seed, the database is the source of truth for identity.
+Use these commands to inspect and edit identity directly — no YAML files needed.
+
+## Usage
+
+```
+/mm:identity list [--layer LAYER]
+/mm:identity get <layer> <key>
+/mm:identity set <layer> <key> --content "..."
+/mm:identity edit <layer> <key>
+```
+
+---
+
+## Subcommands
+
+### list
+
+List all identity entries currently stored in the database.
+
+```bash
+mirror identity list [--layer LAYER] [--mirror-home PATH]
+```
+
+**Examples:**
+- `mirror identity list` — all entries
+- `mirror identity list --layer ego` — only ego layer
+
+Layers: `self`, `ego`, `user`, `organization`, `persona`, `journey`, `journey_path`
+
+---
+
+### get
+
+Print the full content of one identity entry.
+
+```bash
+mirror identity get <layer> <key> [--mirror-home PATH]
+```
+
+**Examples:**
+- `mirror identity get ego behavior`
+- `mirror identity get self soul`
+- `mirror identity get persona engineer`
+
+---
+
+### set
+
+Update identity content directly in the database.
+
+```bash
+mirror identity set <layer> <key> --content "..." [--mirror-home PATH]
+```
+
+If `--content` is omitted, content is read from stdin.
+
+A new `journey` or `persona` key must be kebab-case: lowercase letters, digits,
+and single hyphens, up to 80 characters, such as `product-launch`. Agents put
+these keys into commands, so `set` and `edit` refuse any other new key and name
+one that would work. A key created before this rule keeps working.
+
+**Examples:**
+- `mirror identity set ego behavior --content "Be direct."`
+- `cat new-soul.md | mirror identity set self soul`
+
+---
+
+### edit
+
+Open the current content in `$EDITOR`, edit it, and save back to the database on close.
+
+```bash
+mirror identity edit <layer> <key> [--mirror-home PATH]
+```
+
+**Examples:**
+- `mirror identity edit ego behavior`
+- `mirror identity edit self soul`
+- `mirror identity edit persona engineer`
+
+If no changes are detected, nothing is written. If the file is left empty, the edit is aborted.
+
+---
+
+## When receiving `/mm:identity [subcommand] [args]`
+
+Run the corresponding command above and present the output to the user.