oh-my-opencode-slim 2.0.4 → 2.1.0

package/src/skills/codemap.md

@@ -2,48 +2,75 @@
 
 ## Responsibility
 
-- Own metadata-driven OpenCode custom skills shipped with this package.
-- Maintain the skill contract artifacts (`SKILL.md`, `README.md`, per-skill helper files) that are copied into
-  `${configDir}/skills` at install time.
-- Preserve a canonical registry boundary: runtime code consumes skill definitions as data, not as executable
-  plugin dependencies.
+- Owns metadata-driven OpenCode custom skills shipped with this package
+- Maintains the skill contract artifacts (`SKILL.md`, `README.md`, per-skill helper files) that are copied into `${configDir}/skills` at install time
+- Preserves a canonical registry boundary: runtime code consumes skill definitions as data, not as executable plugin dependencies
+- Skills are partitioned into orchestrator-only workflows and general-purpose skills for broad reuse
 
 ## Design
 
-- `CUSTOM_SKILLS` in `src/cli/custom-skills.ts` is the authoritative skill manifest for bundled
-  skills; each entry maps folder name + `sourcePath` to an install-time consumer.
-- `install.ts` runs `installCustomSkill()` which recursively copies bundled skill
-  directories into the OpenCode skills directory.
-- This directory is partitioned by skill:
-  - `src/skills/codemap/` (command-style repository mapping skill)
-  - `src/skills/clonedeps/` (workflow skill for dependency source mirroring)
-  - `src/skills/simplify/` (readability/refactor guidance skill)
-  - `src/skills/deepwork/` (orchestrator-only workflow for heavy coding sessions)
-  - `src/skills/reflect/` (orchestrator-only workflow for learning from repeated work and suggesting reusable improvements)
-  - `src/skills/worktrees/` (orchestrator-only workflow for safe Git worktree lanes)
-  - `src/skills/oh-my-opencode-slim/` (orchestrator-only plugin configuration and self-improvement guidance)
-- Files are considered static runtime payload. No plugin TS module in `src/` imports these files directly; they
-  are loaded by OpenCode via filesystem installation.
+### Skill Registry
+
+- `CUSTOM_SKILLS` in `src/cli/custom-skills.ts` is the authoritative skill manifest for bundled skills
+- Each entry maps folder name + `sourcePath` to an install-time consumer
+- Skills are categorized by purpose and access scope:
+
+| Skill | Type | Purpose |
+|-------|------|-------|
+| `codemap/` | General-purpose | Repository mapping and codebase documentation skill |
+| `clonedeps/` | General-purpose | Workflow skill for dependency source mirroring and inspection |
+| `simplify/` | General-purpose | Readability and maintainability guidance skill |
+| `deepwork/` | Orchestrator-only | Heavy coding sessions, multi-phase implementation, and risky refactors |
+| `reflect/` | Orchestrator-only | Learning from repeated work and suggesting reusable improvements |
+| `worktrees/` | Orchestrator-only | Safe Git worktree lanes for parallel, risky, or isolated work |
+| `oh-my-opencode-slim/` | Orchestrator-only | Plugin configuration and self-improvement guidance |
+
+### Installation Pipeline
+
+- `install.ts` runs `installCustomSkill()` which recursively copies bundled skill directories into the OpenCode skills directory
+- During plugin release, the `files` whitelist in `package.json` must include `src/skills` so `src/skills/**` survive `npm pack`
+- OpenCode plugin startup discovers these installed folders and reads each `SKILL.md` as a prompt-level contract
+
+### Runtime Consumption
+
+- Files are considered static runtime payload
+- No plugin TS module in `src/` imports these files directly
+- They are loaded by OpenCode via filesystem installation at runtime
 
 ## Flow
 
-- `bun run install` delegates to `src/cli/install.ts`, where `installCustomSkills` gates copying of
-  each `CUSTOM_SKILLS` entry.
-- `installCustomSkill()` computes `packageRoot`, validates `sourcePath`, then performs a recursive
-  directory copy via `copyDirRecursive()`.
-- During plugin release, the `files` whitelist in `package.json` must include `src/skills` so
-  `src/skills/**` survive `npm pack`.
-- OpenCode plugin startup discovers these installed folders and reads each `SKILL.md` as a prompt-level contract.
+1. **Skill Discovery**: `src/cli/custom-skills.ts` defines `CUSTOM_SKILLS` array with skill metadata
+2. **Installation**: `bun run install` delegates to `src/cli/install.ts`, where `installCustomSkills()` gates copying of each `CUSTOM_SKILLS` entry
+3. **Validation**: `installCustomSkill()` computes `packageRoot`, validates `sourcePath`, then performs a recursive directory copy via `copyDirRecursive()`
+4. **Distribution**: During plugin release, `package.json` `files` whitelist ensures `src/skills/**` are included in the published tarball
+5. **Runtime Discovery**: OpenCode plugin startup discovers installed skill folders and reads each `SKILL.md` as a prompt-level contract
 
 ## Integration
 
-- `src/cli/custom-skills.ts`: source-of-truth registry consumed by installer and permission helpers.
-- `src/cli/skills.ts:getSkillPermissionsForAgent()` auto-populates permission rules for
-  bundled skills when agent policy is derived from built-in recommendations.
-- `verify-release-artifact.ts` enforces artifact completeness by asserting key
-  bundled skill payloads such as `src/skills/simplify/SKILL.md`,
-  `src/skills/codemap/SKILL.md`, `src/skills/clonedeps/SKILL.md`, and
-  `src/skills/deepwork/SKILL.md`, `src/skills/reflect/SKILL.md`,
-  `src/skills/worktrees/SKILL.md`, plus `src/skills/oh-my-opencode-slim/SKILL.md`,
-  are present in the tarball.
-- `package.json` scripts (`verify:release`, `build`) rely on these assets to ensure install-time skill availability.
+### Build & Release Dependencies
+
+- `src/cli/custom-skills.ts`: Source-of-truth registry consumed by installer and permission helpers
+- `src/cli/install.ts`: Contains `installCustomSkills()` and `installCustomSkill()` functions
+- `verify-release-artifact.ts`: Enforces artifact completeness by asserting key bundled skill payloads are present in the tarball:
+  - `src/skills/simplify/SKILL.md`
+  - `src/skills/codemap/SKILL.md`
+  - `src/skills/clonedeps/SKILL.md`
+  - `src/skills/deepwork/SKILL.md`
+  - `src/skills/reflect/SKILL.md`
+  - `src/skills/worktrees/SKILL.md`
+  - `src/skills/oh-my-opencode-slim/SKILL.md`
+- `package.json` scripts (`verify:release`, `build`) rely on these assets to ensure install-time skill availability
+
+### Permission System
+
+- `src/cli/skills.ts:getSkillPermissionsForAgent()` auto-populates permission rules for bundled skills when agent policy is derived from built-in recommendations
+- Bundled skills are treated as data payloads with explicit permission boundaries defined in the skill manifests
+
+### Skill Contracts
+
+Each skill directory contains:
+- `SKILL.md`: Skill contract defining name, description, and usage contract
+- `README.md`: Documentation and examples for the skill
+- Optional helper files and subdirectories for skill-specific functionality
+
+These artifacts are copied verbatim to the OpenCode skills directory during installation and serve as the skill's interface definition.

package/src/skills/loop-engineering/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: loop-engineering
+description: Loop engineering runtime Grill + Monitor
+---
+
+# Loop Engineering Skill
+
+## Grill (orchestrator interview)
+
+1. Goal: "What are you trying to accomplish?"
+2. Success criteria: "Describe how we know the loop succeeded."
+3. Success type: choose from `test`, `build`, `lint`, `command`, `fileExists`, `oracle`, `observer`, `manual`. For CLI steps provide `successCommand`; for file detection provide `successPath`.
+4. Execute agent: fixer / designer / explorer / librarian
+5. Verify agent: oracle / observer / test
+6. Max attempts (default 3)
+7. Optional context files: which files or directories should be read before execution?
+
+## Loop Monitor
+
+- Listen to callbacks:
+  - `onLoopComplete(loopID, success)` → report final outcome
+  - `onEscalated(loopID, reason)` → escalate to human
+  - `onManualReview(loopID, reason)` → prompt human to approve/fail and call `resolveManualReview(loopID, passed, reason)`
+- Show current state and attempt count on each callback
+- For manual verification, present the failure reason before asking for pass/fail
+- If human forces cancellation, call `cancel(loopID)` through the orchestrator
+
+## Notes
+- Manual verification is the minimal on-ramp (autoresearch pattern). It pauses the loop until `resolveManualReview` is called. Do not auto-resolve.
+- BackgroundJobBoard signals (totalErrors, timeoutCount) are already baked into the runtime.

package/src/skills/reflect/SKILL.md

@@ -17,6 +17,7 @@ The goal is to identify real repeated friction and suggest practical improvement
 Use Reflect when the user asks to:
 
 - run `/reflect` or `/reflect <focus>`;
+- run `/reflect --sessions` for session archaeology;
 - learn from recent sessions or repeated workflows;
 - find work they keep doing manually;
 - improve their oh-my-opencode-slim setup based on actual usage using oh-my-opencode-slim skill;
@@ -26,6 +27,136 @@ Use Reflect when the user asks to:
 Do not use Reflect for ordinary implementation work, one-off debugging, broad
 architecture review, or speculative agent creation without workflow evidence.
 
+## Session Mode
+
+When the user includes `--sessions` in their reflect command, shift to session
+archaeology: analyze historical OpenCode sessions across all repos to find
+repeated patterns, friction, and improvement opportunities.
+
+### Session Discovery
+
+1. **Load recent sessions** - Query the SQLite database directly:
+   ```bash
+   bun -e "import Database from 'bun:sqlite'; const db = new Database('/home/mhenke/.local/share/opencode/opencode.db'); console.log(db.query('SELECT id, directory, title, agent, model, time_created, cost, tokens_input, tokens_output FROM session ORDER BY time_created DESC LIMIT 50').all())"
+   ```
+   Adjust `LIMIT 50` to `--last N` if specified.
+
+   **Session table columns:** `id, directory, title, agent, model, time_created, cost, tokens_input, tokens_output`
+
+2. **Load session messages** - For each session ID, query the message table:
+   ```bash
+   bun -e "import Database from 'bun:sqlite'; const db = new Database('/home/mhenke/.local/share/opencode/opencode.db'); console.log(db.query('SELECT data FROM message WHERE session_id = ?').all('ses_14de9c68effegtZtlATm42wnz7'))"
+   ```
+
+   **Message table columns:** `id, session_id, time_created, time_updated, data` (data is JSON with role, agent, model, summary, etc.)
+
+### Per-Session Analysis
+
+For each session, analyze and produce a structured summary:
+
+```json
+{
+  "session": "ses_14de9c68effegtZtlATm42wnz7",
+  "project": "/home/user/Projects/oh-my-opencode-slim",
+  "timestamp": "2026-06-10T15:08:45.427Z",
+  "goal": "Fix CI failure",
+  "success": true,
+  "frictions": [
+    "Repeated grep to find test file",
+    "Three failed test runs before passing"
+  ],
+  "recommendations": [
+    "Create /test-ci command"
+  ],
+  "duration_minutes": 18,
+  "models_used": ["opencode/mimo-v2.5-free"],
+  "agents_used": ["orchestrator", "fixer", "explorer"],
+  "tools_used": ["Read", "Edit", "Bash"],
+  "confidence": 0.85
+}
+```
+
+**Confidence scoring:**
+- 0.9-1.0: Clear success/failure, obvious patterns
+- 0.7-0.9: Likely outcome, patterns inferred from tool usage
+- 0.5-0.7: Uncertain outcome, limited evidence
+- <0.5: Skip or mark as "needs more evidence"
+
+### Storage and Caching
+
+Store session summaries in `~/.config/opencode/oh-my-opencode-slim/reflections/sessions/`.
+
+**Cache logic:**
+1. Check if `<session-id>.json` exists in reflections directory
+2. If yes, load it (saves tokens)
+3. If no, analyze session and save summary
+4. Aggregate across all summaries for final report
+
+### Aggregation
+
+After analyzing all sessions, aggregate findings:
+
+1. **Group by theme** - sessions with similar frictions cluster together
+2. **Count frequency** - "42/50 sessions had repeated grep before editing"
+3. **Rank by impact** - prioritize recommendations that appear most often
+4. **Filter noise** - skip one-off issues, focus on repeated patterns
+5. **Cross-reference** - see if patterns correlate with specific models, agents, or repos
+
+**Scope categories:**
+- **Global** - applies to all repos (pattern seen in >50% of repos)
+- **Cross-repo** - applies to specific repos where pattern appears
+- **Project-specific** - only relevant to one repo
+
+### Output Format
+
+Return a compact report with scope and confidence:
+
+```text
+Session Reflection Report
+Analyzing 50 most recent sessions across 8 repos.
+
+Repos analyzed:
+- <repo> (<N> sessions)
+- ... (M more)
+
+Findings
+- <pattern>: N/50 sessions across M repos.
+  - Scope: global | cross-repo (<repos>) | project-specific (<repo>)
+  - Confidence: 0.95
+  - Impact: High | Medium | Low
+
+Recommended changes
+- <asset>: <purpose>
+  - Scope: global | cross-repo (<repos>) | project-specific (<repo>)
+  - Confidence: 0.97
+  - Estimated time saved: High | Medium | Low
+
+Skipped
+- <candidate>: why not worth packaging now.
+  - Scope: <reason>
+  - Confidence: <score>
+
+Needs more evidence
+- <candidate>: what would make it actionable.
+  - Current scope: <what we've seen>
+  - Required scope: <what would confirm>
+```
+
+### Error Handling
+
+**Log file issues:**
+- Log doesn't exist → "No OpenCode log found at <path>. Run OpenCode in at least one repo first."
+- Log is empty → "OpenCode log is empty. No sessions to analyze."
+
+**Session loading issues:**
+- Session ID not loadable → Skip with warning: "Session <id> could not be loaded, skipping."
+- Session has no messages → Skip: "Session <id> has no messages."
+
+**Recovery pattern:**
+- Log the failure
+- Continue with remaining sessions
+- Report failures at end: "3 sessions skipped due to load errors"
+
 ## Core Contract
 
 Reflect must be conservative and evidence-driven.
@@ -66,6 +197,8 @@ Reflect can be triggered directly:
 ```text
 /reflect
 /reflect release workflow and checks
+/reflect --sessions
+/reflect --sessions --last 100
 ```
 
 With no arguments, review recent work broadly. With arguments, focus the review

package/src/skills/release-smoke-test/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: release-smoke-test
+description: Test an oh-my-opencode-slim release candidate or bugfix before publishing. Use when validating a packed plugin artifact, release branch, crash fix, OpenCode runtime compatibility, or model-specific smoke test such as OpenCode 1.17.11 message transform regressions.
+---
+
+# Release Smoke Test
+
+Use this skill to validate an `oh-my-opencode-slim` release candidate before
+public npm publish. Test the packed artifact, not `@latest` and not the source
+tree.
+
+## Core Workflow
+
+1. Start from the release-prep branch or commit.
+2. Build and pack the candidate.
+3. Install the tarball into a throwaway app.
+4. Create an isolated OpenCode config pointing at the installed
+   `node_modules/oh-my-opencode-slim/dist/index.js`.
+5. Run `opencode debug config` and verify `plugin_origins` contains only the
+   intended plugin when doing an isolation smoke.
+6. Run non-pure `opencode run --print-logs --log-level DEBUG`.
+7. Search isolated logs for the original crash signature.
+8. Record exact artifact, model, OpenCode version, command shape, result, and
+   limitations on the release issue or PR.
+
+## Pack Candidate
+
+Use a temp directory so release validation never depends on the local package
+cache.
+
+```bash
+SMOKE=/tmp/oh-my-opencode-slim-release-smoke
+rm -rf "$SMOKE"
+mkdir -p "$SMOKE/pkg" "$SMOKE/app" "$SMOKE/home" "$SMOKE/xdg/opencode" "$SMOKE/run"
+
+bun run build
+npm pack --pack-destination "$SMOKE/pkg"
+```
+
+Install the tarball:
+
+```bash
+cd "$SMOKE/app"
+bun init -y
+bun add "$SMOKE/pkg"/oh-my-opencode-slim-*.tgz
+node -p "require('./node_modules/oh-my-opencode-slim/package.json').version"
+```
+
+## Isolated Config
+
+Write the minimal OpenCode config:
+
+```bash
+cat > "$SMOKE/xdg/opencode/opencode.json" <<EOF
+{
+  "model": "opencode/deepseek-v4-flash-free",
+  "plugin": [
+    "file://$SMOKE/app/node_modules/oh-my-opencode-slim/dist/index.js"
+  ],
+  "agent": {
+    "orchestrator": {
+      "model": "opencode/deepseek-v4-flash-free"
+    }
+  }
+}
+EOF
+```
+
+Use `env -i` for the cleanest smoke. This strips host `OPENCODE_*`, `ORCA_*`,
+and project overlay variables that can silently add plugins or provider aliases.
+
+```bash
+env -i PATH="$PATH" HOME="$SMOKE/home" XDG_CONFIG_HOME="$SMOKE/xdg" \
+  opencode debug config
+```
+
+Confirm:
+
+- `plugin_origins` has exactly one entry.
+- That entry points to the temp app's packed `dist/index.js`.
+- The model is the one intended for the smoke.
+
+If OpenCode needs provider aliases from the host environment, run a second
+non-isolated model-specific smoke and clearly label it as weaker isolation.
+
+## Runtime Smoke
+
+Run the actual prompt with timeout:
+
+```bash
+env -i PATH="$PATH" HOME="$SMOKE/home" XDG_CONFIG_HOME="$SMOKE/xdg" \
+  timeout 120 \
+  opencode run --print-logs --log-level DEBUG "Say OK only."
+```
+
+Expected result:
+
+```text
+OK
+```
+
+Search logs for the bug signature. For the OpenCode 1.17.11 malformed-message
+crash, use:
+
+```bash
+rg "message\\.info\\.role|undefined is not an object|Cannot read properties of undefined|TypeError" \
+  "$SMOKE/home/.local/share/opencode/log" -n 2>/dev/null || true
+```
+
+No matches should appear.
+
+## OpenAI / Host-Provider Smoke
+
+If the fully isolated environment cannot resolve OpenAI provider aliases, run a
+separate host-provider smoke while keeping the plugin path pointed at the
+tarball install.
+
+```bash
+mkdir -p "$SMOKE/config"
+cat > "$SMOKE/config/opencode.json" <<EOF
+{
+  "model": "openai/gpt-5.5-fast",
+  "plugin": [
+    "file://$SMOKE/app/node_modules/oh-my-opencode-slim/dist/index.js"
+  ],
+  "agent": {
+    "orchestrator": {
+      "model": "openai/gpt-5.5-fast"
+    }
+  }
+}
+EOF
+
+OPENCODE_CONFIG_DIR="$SMOKE/config" \
+  timeout 120 \
+  opencode run --print-logs --log-level DEBUG "Say OK only."
+```
+
+Report this as a host-provider smoke because existing project, user, or Orca
+OpenCode config may still merge in. Use `opencode debug config` to disclose
+what else loaded.
+
+## Reporting Template
+
+```markdown
+## Release-candidate smoke validation
+
+- Commit under test:
+- Tarball:
+- Installed package version:
+- OpenCode version:
+- Config isolation: sanitized `env -i` / host-provider
+- Plugin origin:
+- Model:
+- Command:
+- Result:
+- Crash signature search:
+- Limitations:
+```

package/src/skills/simplify/SKILL.md

@@ -7,7 +7,7 @@ description: Simplifies code for clarity without changing behavior. Use for read
 
 ## Overview
 
-Simplify code by reducing complexity while preserving exact behavior. The goal is not fewer lines — it's code that is easier to read, understand, modify, and debug. Every simplification must pass a simple test: "Would a new team member understand this faster than the original?"
+Simplify code by reducing complexity while preserving exact behavior. The goal is not fewer lines - it's code that is easier to read, understand, modify, and debug. Every simplification must pass a simple test: "Would a new team member understand this faster than the original?"
 
 ## When to Use
 
@@ -20,16 +20,16 @@ Simplify code by reducing complexity while preserving exact behavior. The goal i
 
 **When NOT to use:**
 
-- Code is already clean and readable — don't simplify for the sake of it
-- You don't understand what the code does yet — comprehend before you simplify
+- Code is already clean and readable - don't simplify for the sake of it
+- You don't understand what the code does yet - comprehend before you simplify
 - The code is performance-critical and the "simpler" version would be measurably slower
-- You're about to rewrite the module entirely — simplifying throwaway code wastes effort
+- You're about to rewrite the module entirely - simplifying throwaway code wastes effort
 
 ## The Five Principles
 
 ### 1. Preserve Behavior Exactly
 
-Don't change what the code does — only how it expresses it. All inputs, outputs, side effects, error behavior, and edge cases must remain identical. If you're not sure a simplification preserves behavior, don't make it.
+Don't change what the code does - only how it expresses it. All inputs, outputs, side effects, error behavior, and edge cases must remain identical. If you're not sure a simplification preserves behavior, don't make it.
 
 Before every change, ask:
 
@@ -48,7 +48,7 @@ Before simplifying:
 2. Study how neighboring code handles similar patterns
 3. Match the project's style for imports, naming, function style, error handling, and type annotations
 
-Simplification that breaks project consistency is not simplification — it's churn.
+Simplification that breaks project consistency is not simplification - it's churn.
 
 ### 3. Prefer Clarity Over Cleverness