@wpro-eng/opencode-config 1.0.0

package/README.md

@@ -0,0 +1,366 @@
+# @wpro-eng/opencode-config
+
+Wpromote's proprietary OpenCode plugin that keeps team developers' configurations in lockstep. This repo contains both the plugin code AND the team's shared skills, agents, commands, plugins, instructions, and MCP configs.
+
+## How It Works
+
+When installed, this plugin:
+
+1. **Syncs** this repository to your local machine (clone once, fetch on startup)
+2. **Installs** team skills, plugins, and MCPs via symlinks to your OpenCode config
+3. **Injects** team agents, commands, and instructions into OpenCode's runtime config
+4. **Respects** your local overrides and explicit disables
+
+### Priority Order
+
+1. **Your local configs** — always win
+2. **Team configs** — fill in the gaps
+
+## Installation
+
+### 1. Add to your OpenCode config
+
+In `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "plugin": ["@wpro-eng/opencode-config"]
+}
+```
+
+### 2. Install the plugin
+
+```bash
+# From npm (when published)
+npm install -g @wpro-eng/opencode-config
+
+# Or link locally for development
+cd /path/to/opencode-config
+bun install
+bun run build
+npm link
+```
+
+### 3. Restart OpenCode
+
+The plugin will automatically sync on startup.
+
+## Configuration
+
+Create `~/.config/opencode/wpromote.json` or `~/.config/opencode/wpromote.jsonc` (same for project-level `.opencode/`):
+
+```json
+{
+  "disable": ["skill:example", "agent:verbose-debugger"],
+  "ref": "v1.0.0",
+  "installMethod": "link"
+}
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `disable` | `string[]` | `[]` | Assets to disable (see below) |
+| `ref` | `string` | `"main"` | Git ref to sync (branch, tag, or SHA) |
+| `installMethod` | `"link"` \| `"copy"` | `"link"` | How to install skills/plugins/MCPs |
+| `dryRun` | `boolean` | `false` | Preview changes without installing |
+| `orchestration` | `object` | defaults | Runtime orchestration controls, limits, and fallback policy |
+
+### Orchestration Runtime Configuration
+
+```json
+{
+  "orchestration": {
+    "providerMode": "copilot",
+    "limits": {
+      "maxConcurrent": 3,
+      "maxRetries": 2,
+      "maxIterations": 25,
+      "retryBackoffMs": 1500,
+      "taskTimeoutMs": 120000
+    },
+    "runtimeFallback": {
+      "enabled": true,
+      "retryOnErrors": [400, 401, 403, 408, 429, 500, 502, 503, 504, 529],
+      "maxFallbackAttempts": 2,
+      "cooldownSeconds": 30,
+      "timeoutSeconds": 30,
+      "notifyOnFallback": true,
+      "providerOrder": ["copilot", "native"]
+    },
+    "hooks": {
+      "disabled": ["activity-feed"],
+      "telemetry": true
+    },
+    "notifications": {
+      "enabled": true,
+      "maxItems": 100
+    },
+    "categories": {
+      "routing": {
+        "quick": "native"
+      },
+      "maxConcurrent": {
+        "quick": 1
+      }
+    },
+    "recovery": {
+      "autoResumeOnStart": true
+    },
+    "tmux": {
+      "enabled": false,
+      "layout": "main-vertical",
+      "mainPaneSize": 60,
+      "mainPaneMinWidth": 120,
+      "agentPaneMinWidth": 40,
+      "sessionPrefix": "wpo"
+    }
+  }
+}
+```
+
+Tmux support is optional and only active when `orchestration.tmux.enabled` is `true` and OpenCode is running inside a tmux session. When enabled, task launches can attach a live pane, queue attachment when pane capacity is full, and auto-clean up panes when tasks complete, fail, stop, or parent sessions end.
+
+Category policies are optional. Use `orchestration.categories.routing` to override provider mode per task category (for example, `quick` -> `native`) and `orchestration.categories.maxConcurrent` to cap active tasks per category.
+
+Recovery policies are optional. `orchestration.recovery.autoResumeOnStart` controls whether queued/running/retrying task records from prior sessions are automatically restored into `queued` state on startup.
+
+### Dry-Run Mode
+
+Preview what the plugin would do without making any changes:
+
+```json
+// ~/.config/opencode/wpromote.json
+{
+  "dryRun": true
+}
+```
+
+Or set the environment variable:
+```bash
+WPROMOTE_DRY_RUN=1 opencode
+```
+
+In dry-run mode, the plugin will:
+- Sync the team repository (to see what's available)
+- Log what skills, plugins, and MCPs would be installed or removed
+- Log what agents, commands, and instructions would be injected
+- Log what assets would be skipped due to conflicts or disables
+- **Make no actual file changes**
+
+This is useful for:
+- Testing configuration changes before applying them
+- Debugging why certain assets aren't appearing
+- Understanding what the plugin does on your system
+
+### Using a Specific Git Ref
+
+By default, the plugin syncs from the `main` branch. To pin to a specific version for stability:
+
+```json
+{
+  "ref": "v1.2.0"
+}
+```
+
+> **Note**: Configuration changes (including changes to `wpromote.json` / `wpromote.jsonc`) take effect on restart. After modifying your config, restart OpenCode to apply the changes.
+
+By default, the plugin syncs from the `main` branch. To pin to a specific version for stability:
+
+```json
+// ~/.config/opencode/wpromote.json
+{
+  "ref": "v1.2.3"   // Use a tagged release
+}
+```
+
+Or use a feature branch for testing:
+```json
+{
+  "ref": "feature/new-skills"
+}
+```
+
+This is useful when:
+- You want stability and don't want automatic updates
+- You're testing unreleased team configurations
+- You need to roll back to a known-good version
+
+
+### Disable Syntax
+
+```json
+{
+  "disable": [
+    "skill:verbose-logger",     // Disable specific skill
+    "agent:heavy-model",        // Disable specific agent
+    "command:dangerous-cmd",    // Disable specific command
+    "plugin:auto-formatter",    // Disable specific plugin
+    "instruction:old-guide",    // Disable specific instruction
+    "mcp:expensive-api",        // Disable specific MCP
+    "deprecated-thing"          // Disable across ALL types (bare name)
+  ]
+}
+```
+
+## Overriding Team Configs
+
+The plugin respects local configurations. Your local settings always take precedence over team defaults.
+
+### Override Priority
+
+```
+1. Your local OpenCode config (opencode.json)     ← Highest priority
+2. Explicit disable list (wpromote.json)
+3. Local skill directories (~/.config/opencode/skill/<name>/)
+4. Team configuration from this repo               ← Lowest priority
+```
+
+### By Asset Type
+
+| Asset Type | How to Override | How to Disable |
+|------------|-----------------|----------------|
+| **Skill** | Create `~/.config/opencode/skill/<name>/SKILL.md` | `"skill:<name>"` in disable list |
+| **Agent** | Add to `opencode.json`: `{ "agents": { "<name>": {...} } }` | `"agent:<name>"` in disable list |
+| **Command** | Add to `opencode.json`: `{ "commands": { "<name>": {...} } }` | `"command:<name>"` in disable list |
+| **Plugin** | Disable team plugin, add your own to plugins directory | `"plugin:<name>"` in disable list |
+| **Instruction** | Cannot override (only append). Disable and add your own. | `"instruction:<name>"` in disable list |
+| **MCP** | Add to `opencode.json` MCP config section | `"mcp:<name>"` in disable list |
+
+### Examples
+
+**Override a team agent with different settings:**
+```json
+// ~/.config/opencode/opencode.json
+{
+  "agents": {
+    "team-agent": {
+      "model": "claude-sonnet-4-20250514",
+      "temperature": 0.5
+    }
+  }
+}
+```
+
+**Disable multiple team assets:**
+```json
+// ~/.config/opencode/wpromote.json
+{
+  "disable": [
+    "skill:verbose-logger",
+    "agent:heavy-model",
+    "instruction:old-conventions"
+  ]
+}
+```
+
+**Override a skill with your own version:**
+```bash
+# Create your local skill directory
+mkdir -p ~/.config/opencode/skill/my-skill
+
+# Add your SKILL.md
+cat > ~/.config/opencode/skill/my-skill/SKILL.md << 'EOF'
+---
+name: my-skill
+description: My customized version
+---
+Your custom skill content here...
+EOF
+```
+
+**Completely disable a skill you don't use:**
+```json
+// ~/.config/opencode/wpromote.json
+{
+  "disable": ["skill:unused-skill"]
+}
+```
+
+## What's Included
+
+### Skills (`skill/`)
+Reusable skill files that agents can load. Each skill is a directory containing `SKILL.md` with YAML frontmatter.
+
+### Agents (`agent/`)
+Pre-configured agent definitions with model, temperature, and system prompts.
+
+### Commands (`command/`)
+Slash commands available to all team members.
+
+### Plugins (`plugin/`)
+OpenCode hook plugins for team-wide automation.
+
+### Instructions (`instruction/`)
+Markdown files automatically appended to agent context (like AGENTS.md).
+
+### MCPs (`mcp/`)
+Model Context Protocol server configurations.
+
+Current team MCP configs include:
+- `chrome-devtools` (`https://www.npmjs.com/package/chrome-devtools-mcp` via `npx`)
+- `context7` (`https://mcp.context7.com/mcp`)
+- `exa` (`https://mcp.exa.ai/mcp`)
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Build
+bun run build
+
+# Run tests
+bun test
+
+# Type check
+bun run typecheck
+
+# Link for local testing
+npm link
+```
+
+## Adding New Configs
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to add new skills, agents, commands, and more.
+
+## Version Pinning
+
+By default, the plugin tracks the `main` branch. For stability, pin to a release:
+
+```json
+{
+  "ref": "v1.0.0"
+}
+```
+
+Check the [releases](https://github.com/wpromote/opencode-config/releases) for available versions.
+
+## Cache Location
+
+Synced repository: `~/.cache/opencode/wpromote-config/repos/`
+
+Installed assets:
+- Skills: `~/.config/opencode/skill/_plugins/opencode-config/`
+- Plugins: `~/.config/opencode/plugins/_remote_opencode-config_*.ts`
+- MCPs: `~/.config/opencode/mcp/_plugins/opencode-config/`
+
+## Troubleshooting
+
+Quick fixes for common issues:
+
+| Issue | Solution |
+|-------|----------|
+| Sync not working | Check log: `~/.cache/opencode/wpromote-config/plugin.log` |
+| SSH key issues | Run `ssh -T git@github.com` to verify access |
+| Stale configs | Delete cache: `rm -rf ~/.cache/opencode/wpromote-config` |
+| Asset not appearing | Check disable list in `wpromote.json` |
+| Override not working | Verify exact name match (case-sensitive) |
+
+For detailed troubleshooting, see **[TROUBLESHOOTING.md](./TROUBLESHOOTING.md)**.
+
+## License
+
+Proprietary - Wpromote Internal Use Only