oh-my-opencode-serverlocal 0.1.0

package/src/skills/deepwork/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: deepwork
+description: High-cost orchestrator workflow for large, high-risk, multi-phase coding efforts with meaningful dependencies and review gates. Do not activate for routine multi-file changes.
+---
+
+# Deepwork
+
+Deepwork is an orchestrator workflow for heavy coding sessions. Use it only
+when the work is clearly large or high-risk: multiple dependent phases,
+cross-cutting architectural change, unsafe-to-partially-ship migration, or
+sustained coordination across several specialist lanes.
+
+Do not infer Deepwork merely because a task touches multiple files. Do not use
+it for trivial edits, quick docs changes, simple bug fixes, or routine bounded
+features.
+
+## Core Contract
+
+When deepwork is active, the orchestrator must manage the work as a scheduler,
+not as the default implementation worker.
+
+Required behavior:
+
+- before planning, delegation, or creating a deepwork state file, inspect the
+  existing `.gitignore` and `.ignore`; add only missing entries, without
+  duplicates, so `.gitignore` contains `.slim/deepwork/` and `.ignore` contains
+  `!.slim/deepwork/` and `!.slim/deepwork/**`;
+- keep OpenCode todos aligned with the active deepwork phase;
+- create and maintain a local markdown progress file under `.slim/deepwork/`;
+- write valuable research findings into that file as confirmed research context
+  when they are received and reconciled;
+- draft a plan before implementation;
+- ask `@oracle` to review the plan and revise it until acceptable;
+- create a phased implementation/delegation plan;
+- before oracle reviews, add relevant confirmed research findings and file
+  references to the deepwork file so oracle can review the plan or phase from
+  accepted context instead of redoing discovery;
+- ask `@oracle` to review that implementation plan before execution;
+- after oracle review and before each implementation phase, decide the execution
+  path: what can run in parallel, what must be sequential, which specialists to
+  delegate to, and whether to split the same agent into multiple bounded lanes;
+- after each phase, validate, update the deepwork file, prepare the plan file
+  for oracle review and ask `@oracle` to review the phase result, fix
+  actionable issues, then continue;
+- when a phase includes `@designer`, preserve designer intent across later
+  phases. Use `@fixer` only for mechanical follow-up that does not alter the
+  UI/UX;
+- finish with final validation and a concise summary.
+
+## Designer Handoff Guardrail
+
+When a deepwork phase includes `@designer`, treat the delivered UI/UX as
+accepted design intent for later phases. Record any important design decisions in
+the deepwork file before continuing.
+
+After designer work:
+
+- preserve layout, rhythm, hierarchy, motion, spacing, color, affordances,
+  responsiveness, and component feel;
+- review and improve user-facing copy with grounded, normal wording, but do not
+  change visual structure or interaction intent;
+- route follow-up visual, responsive, motion, hierarchy, polish, or
+  component-feel changes back to `@designer`;
+- use `@fixer` only for bounded mechanical follow-up that preserves the design
+  exactly, such as wiring, tests, type fixes, or non-visual behavior changes;
+- if design intent must change, record why in the deepwork file before changing
+  it.
+
+## Deepwork File
+
+Create a task-specific file such as:
+
+```text
+.slim/deepwork/<short-task-slug>.md
+```
+
+Before creating this file—and before planning or delegation—inspect the existing
+`.gitignore` and `.ignore`. Add only missing entries and do not add duplicates:
+
+```gitignore
+# .gitignore
+.slim/deepwork/
+```
+
+```gitignore
+# .ignore
+!.slim/deepwork/
+!.slim/deepwork/**
+```
+
+These rules keep deepwork state git-local while allowing OpenCode to read it.
+
+Do not follow a rigid template. Choose whatever markdown structure best fits the
+work. The file only needs to remain useful as persistent session state and should
+capture, as applicable:
+
+- current goal and understanding;
+- researched, factual context from `@librarian` to avoid oracle doing its own
+  research;
+- plan drafts and oracle review notes;
+- implementation phases and status;
+- validation results;
+- unresolved questions, blockers, and follow-ups.
+
+Update this file after major decisions, valuable specialist research, reviews,
+phase completions, validation results, and scope changes.
+When `@librarian` docs, code reads, or external references produce useful
+information, reconcile the result and record the accepted findings here so later
+planning and reviews share the same context instead of rediscovering it.
+Don't put actual contents of local files, reference them by path only.
+
+## Scheduler Discipline
+
+Use the scheduler model throughout:
+
+- follow Orchestrator delegations rules
+- record task/session IDs and ownership boundaries;
+- wait for hook-driven background completion before consuming background results;
+- avoid blocking Orchestrator lane while background jobs run; if no independent
+  work remains, stop briefly and let the completion event resume the workflow;
+- do not advance to the next phase while relevant jobs are running or terminal
+  results are unreconciled.

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/oh-my-opencode-slim/SKILL.md

@@ -0,0 +1,326 @@
+---
+name: oh-my-opencode-slim
+description: Configure and improve oh-my-opencode-slim for the current user. Use when users want to tune agents, models, prompts, custom agents, skills, MCPs, presets, or plugin behavior. Also use when recurring workflow friction suggests a safe config or prompt improvement.
+---
+
+# oh-my-opencode-slim Configuration Skill
+
+You help users configure, customize, and safely improve their
+oh-my-opencode-slim setup.
+
+The goal is not just to answer configuration questions. When useful, help the
+user make their agent system better for future runs: tune models, adjust
+agent prompts, add focused custom agents, enable or restrict tools, and document
+restart requirements.
+
+## When to Use
+
+Use this skill when the user asks about or is likely to benefit from changes to:
+
+- `~/.config/opencode/oh-my-opencode-slim.json` or `.jsonc`
+- `.opencode/` or `~/.config/opencode/` plugin/agent configuration
+- agent models, variants, presets, or provider routing
+- orchestrator delegation behavior or specialist-agent prompts
+- custom agents under `agents.<name>`
+- custom agent `prompt` and `orchestratorPrompt` blocks
+- skills, MCP permissions, tool access, or disabled agents
+- background orchestration, session reuse, multiplexer panes, or deepwork
+- recurring workflow friction that could be fixed by a prompt/config change
+
+Also use it proactively, with restraint, when a session reveals a repeatable
+improvement opportunity. Example: if the user repeatedly asks the same agent to
+follow a project-specific rule, suggest adding that rule to a prompt or config.
+
+## What Is Possible
+
+oh-my-opencode-slim is configured through a plugin config file, usually:
+
+```text
+~/.config/opencode/oh-my-opencode-slim.json
+```
+
+or:
+
+```text
+~/.config/opencode/oh-my-opencode-slim.jsonc
+```
+
+Concrete files agents should know:
+
+| Path | Use |
+|---|---|
+| `~/.config/opencode/opencode.json` | OpenCode core config: plugin registration and providers |
+| `~/.config/opencode/oh-my-opencode-slim.jsonc` | User plugin config with comments/trailing commas; takes precedence over `.json` |
+| `~/.config/opencode/oh-my-opencode-slim.json` | User plugin config generated by installer |
+| `<project>/.opencode/oh-my-opencode-slim.json` | Project-local plugin overrides checked before user config |
+| `~/.config/opencode/oh-my-opencode-slim/{agent}.md` | Full prompt replacement for a built-in agent |
+| `~/.config/opencode/oh-my-opencode-slim/{agent}_append.md` | Append-only prompt tuning for a built-in agent |
+| `~/.config/opencode/oh-my-opencode-slim/{preset}/{agent}.md` | Preset-specific full prompt replacement |
+| `~/.config/opencode/oh-my-opencode-slim/{preset}/{agent}_append.md` | Preset-specific append-only prompt tuning |
+| `~/.config/opencode/skills/<skill-name>/SKILL.md` | Installed skill prompt payload |
+
+Built-in agent prompt file names are exact agent names:
+
+- `orchestrator.md` / `orchestrator_append.md`
+- `oracle.md` / `oracle_append.md`
+- `librarian.md` / `librarian_append.md`
+- `explorer.md` / `explorer_append.md`
+- `designer.md` / `designer_append.md`
+- `fixer.md` / `fixer_append.md`
+- `observer.md` / `observer_append.md`
+- `council.md` / `council_append.md`
+
+Prefer `{agent}_append.md` for small behavior tuning. Use `{agent}.md` only when
+the user intentionally wants to replace the bundled prompt entirely.
+
+Prompt override lookup order:
+
+1. If a `preset` is active, check
+   `~/.config/opencode/oh-my-opencode-slim/{preset}/` first.
+2. Fall back to `~/.config/opencode/oh-my-opencode-slim/`.
+3. If both `{agent}.md` and `{agent}_append.md` exist, the replacement prompt is
+   loaded first and the append file is added after it.
+4. If no prompt files exist, the built-in prompt from the plugin package is used.
+
+Common customizations:
+
+- **Switch presets**: choose which generated or custom preset is active.
+- **Tune models**: assign different models/variants per agent.
+- **Limit costs**: use cheaper models for `explorer`, `librarian`, and `fixer`.
+- **Improve quality**: use stronger models for `orchestrator`, `oracle`, or
+  design-heavy `designer` work.
+- **Control skills**: set `skills` per agent with `['*']`, explicit names, or
+  exclusions like `['*', '!codemap']`.
+- **Control MCPs**: set `mcps` per agent with the same allow/exclude style.
+- **Enable optional agents**: remove agents from `disabled_agents` and configure
+  an appropriate model, such as a vision-capable `observer`.
+- **Add custom agents**: define focused specialists under `agents.<name>`.
+- **Tune prompts**: override or extend an agent's prompt for local workflow
+  preferences.
+- **Guide delegation**: add `orchestratorPrompt` for custom agents so the
+  Orchestrator knows when to call them and when not to.
+
+Important schema boundary:
+
+- Built-in agents (`orchestrator`, `oracle`, `librarian`, `explorer`,
+  `designer`, `fixer`, `observer`, `council`) can set models, variants, skills,
+  MCPs, options, and display names in config.
+- Built-in agent `prompt` and `orchestratorPrompt` fields are **not** supported
+  in `oh-my-opencode-slim.json[c]`; use markdown prompt override files instead.
+- Unknown keys under top-level `agents` are custom agents. Custom agents may use
+  `prompt` and `orchestratorPrompt` directly in config.
+
+## Config Shapes
+
+### Tune a built-in agent model/skills/MCPs
+
+Edit the active preset under `presets.<preset>.<agent>`:
+
+```jsonc
+{
+  "preset": "openai",
+  "presets": {
+    "openai": {
+      "orchestrator": {
+        "model": "openai/gpt-5.6-terra",
+        "variant": "high",
+        "skills": ["*"],
+        "mcps": ["*", "!context7"]
+      },
+      "librarian": {
+        "model": "openai/gpt-5.6-luna",
+        "variant": "low",
+        "skills": [],
+        "mcps": ["websearch", "context7", "gh_grep"]
+      }
+    }
+  }
+}
+```
+
+### Append instructions to a built-in prompt
+
+Create, for example:
+
+```text
+~/.config/opencode/oh-my-opencode-slim/orchestrator_append.md
+```
+
+or for only the `openai` preset:
+
+```text
+~/.config/opencode/oh-my-opencode-slim/openai/orchestrator_append.md
+```
+
+Example content:
+
+```markdown
+## Local Orchestrator Preference
+
+- Before spawning parallel writer agents, identify non-overlapping file ownership.
+- If file ownership overlaps, ask the user or serialize the work.
+```
+
+### Replace a built-in prompt entirely
+
+Create:
+
+```text
+~/.config/opencode/oh-my-opencode-slim/orchestrator.md
+```
+
+Use this rarely. Full replacements must restate all essential plugin behavior,
+because they replace the bundled prompt.
+
+## Safe Improvement Rules
+
+Configuration changes affect future agent behavior, so treat them as user-owned.
+
+1. **Ask before changing config or prompts.**
+   - Explain the proposed improvement briefly.
+   - State which file would change.
+   - Ask for confirmation unless the user explicitly requested the exact edit.
+2. **Prefer narrow changes.**
+   - Do not rewrite large prompts when a small rule solves the problem.
+   - Do not add custom agents for one-off tasks.
+3. **Preserve existing user settings.**
+   - Merge with current config rather than regenerating from scratch.
+   - Keep comments and formatting where practical for JSONC files.
+4. **Avoid hidden behavior changes.**
+   - Mention cost, permissions, or delegation changes before applying them.
+   - Be explicit if a model/provider change may increase spend.
+5. **Tell the user about restart requirements.**
+   - OpenCode may need a restart for config, prompt, agent, skill, MCP, or plugin
+     changes to take effect.
+   - Phrase it as: "This should apply on the next OpenCode run; restart OpenCode
+     if you need it immediately."
+
+## Configuration Workflow
+
+When making or proposing changes:
+
+1. **Inspect current setup**
+   - Read the existing oh-my-opencode-slim config file.
+   - Identify active `preset` and relevant agent blocks.
+   - Check whether the user has local project `.opencode/` overrides.
+2. **Decide the smallest useful change**
+   - Model/preset tuning for performance, quality, or cost.
+   - Prompt tuning for recurring behavior.
+   - Custom agent when a repeatable specialty deserves a separate lane.
+   - Skill/MCP permission change when access is too broad or too narrow.
+3. **Ask for confirmation**
+   - Show a concise proposal.
+   - Include the target file path.
+4. **Apply the edit carefully**
+   - Preserve unrelated settings.
+   - Prefer JSONC-compatible output if editing a JSONC file.
+   - Keep agent names and skill/MCP names exact.
+5. **Validate**
+   - Ensure the file remains parseable.
+   - Run available config checks if the repository provides them.
+6. **Explain activation**
+   - Tell the user whether the change applies immediately or on next OpenCode
+     run/restart.
+
+## Custom Agent Pattern
+
+Custom agents work best when they are narrow, repeatable, and easy for the
+Orchestrator to route.
+
+Use this shape as a starting point:
+
+```jsonc
+{
+  "agents": {
+    "api-reviewer": {
+      "model": "openai/gpt-5.6",
+      "variant": "high",
+      "prompt": "You review API design, compatibility, error semantics, and migration risk. Return concise findings with file references.",
+      "orchestratorPrompt": "Delegate to @api-reviewer for API contract changes, public SDK changes, backwards-compatibility questions, or migration-risk review. Do not use it for routine implementation.",
+      "skills": [],
+      "mcps": []
+    }
+  }
+}
+```
+
+Good custom agents have:
+
+- a specific job;
+- clear trigger conditions in `orchestratorPrompt`;
+- explicit non-use conditions;
+- only the skills and MCPs they actually need;
+- a model appropriate to the task's judgment/cost needs.
+
+Avoid custom agents that duplicate existing specialists:
+
+- codebase scouting → `explorer`
+- external docs/research → `librarian`
+- architecture/debugging/review → `oracle`
+- UI/UX polish → `designer`
+- scoped mechanical implementation → `fixer`
+
+## Prompt Tuning Pattern
+
+Prompt edits are best for recurring behavior that should happen across many
+sessions.
+
+Good reasons to tune a prompt:
+
+- The Orchestrator repeatedly delegates too much or too little for this user's
+  workflow.
+- A specialist repeatedly misses a project-specific convention.
+- The user wants a stable communication or verification style.
+- The team has a recurring review checklist or deployment rule.
+
+Poor reasons to tune a prompt:
+
+- A one-off task failed once.
+- The current problem can be solved by normal instruction in this session.
+- The change would make the agent worse for general use.
+
+When suggesting a prompt improvement, say:
+
+```text
+I noticed this is recurring. I can add a small rule to <agent/config path> so
+future runs handle it automatically. Want me to make that config change?
+```
+
+## Examples
+
+### Make Orchestrator more conservative with background writers
+
+Proposal:
+
+```text
+I can add a narrow Orchestrator prompt rule to avoid parallel writer agents in
+the same directory unless their file ownership is explicit. Target:
+~/.config/opencode/oh-my-opencode-slim/orchestrator_append.md. Apply it?
+```
+
+### Add a project-specific reviewer
+
+Proposal:
+
+```text
+This looks repeatable enough for a custom read-only reviewer agent. I can add
+`api-reviewer` with no skills or MCPs and an `orchestratorPrompt` that routes
+public API changes to it. Apply to your oh-my-opencode-slim config?
+```
+
+### Warn about restart
+
+After editing:
+
+```text
+Updated the config. This should apply on the next OpenCode run; restart
+OpenCode if you need it immediately.
+```
+
+## Final Checklist
+
+- [ ] Did the user confirm config/prompt edits, unless explicitly requested?
+- [ ] Did the edit preserve existing settings?
+- [ ] Is the active preset still valid?
+- [ ] Are skill/MCP/tool permissions intentional and minimal?
+- [ ] Did you mention OpenCode restart/next-run behavior?