|
| 1 | +# Development Plan: responsible-vibe (feat/opencode-enable-disable branch) |
| 2 | + |
| 3 | +*Generated on 2026-03-31 by Vibe Feature MCP* |
| 4 | +*Workflow: [epcc](https://mrsimpson.github.io/responsible-vibe-mcp/workflows/epcc)* |
| 5 | + |
| 6 | +## Goal |
| 7 | +Add a mechanism to completely disable the OpenCode workflows plugin per-agent, as if it was never registered. This allows agents to operate without workflow enforcement while other agents use workflows normally. |
| 8 | + |
| 9 | +## Key Decisions |
| 10 | +- **Plugin Disabling vs Feature Disabling**: Requirement is to disable the entire plugin (as if unregistered), not disable per-agent |
| 11 | +- **No Persistence**: Do NOT persist enable/disable state across sessions. Each session starts fresh. |
| 12 | +- **Multiple Control Inputs**: |
| 13 | + 1. **Environment Variable** (startup): `WORKFLOWS=on|off` at application start |
| 14 | + 2. **User Command** (runtime): `/{workflow|wf} {on|off}` during session |
| 15 | +- **User Command Interface**: Plugin intercepts via `command.execute.before` hook. User defines `/workflow` or `/wf` command in `.opencode/commands/workflow.md` |
| 16 | +- **Stateful During Session**: Global enable/disable flag set at startup by env var, can be toggled by user command during session |
| 17 | +- **Simplified Scope**: Single on/off state for entire plugin (not per-agent). Global disable means workflows disabled for all agents. |
| 18 | + |
| 19 | +## Notes |
| 20 | +- Plugins cannot register custom commands directly - they intercept via `command.execute.before` hook |
| 21 | +- The `command.execute.before` hook receives command name and can modify `output.parts` to inject response |
| 22 | +- No `.vibe/workflows-config.json` file needed - state is in-memory during session |
| 23 | +- Env var `WORKFLOWS=on|off` checked at plugin initialization to set initial state |
| 24 | +- Runtime command `/workflow on|off` or `/wf on|off` toggles the in-memory state |
| 25 | + |
| 26 | +## Explore |
| 27 | +<!-- beads-phase-id: responsible-vibe-21.1 --> |
| 28 | +### ✅ Completed |
| 29 | +- Researched OpenCode plugin lifecycle and agent context availability |
| 30 | +- Evaluated implementation approaches (runtime check vs config file) |
| 31 | +- Determined plugin can use `command.execute.before` hook to intercept `/workflows` commands |
| 32 | +- Clarified that this is a user command, not an LLM tool |
| 33 | + |
| 34 | +### Entrance Criteria for Plan Phase |
| 35 | +- ✅ Requirements understood: Complete plugin disable per-agent via user command |
| 36 | +- ✅ Architecture decided: Runtime check in plugin hooks + command.execute.before interceptor |
| 37 | +- ✅ Implementation approach clear: Config file + agent name checking |
| 38 | + |
| 39 | +## Plan |
| 40 | +<!-- beads-phase-id: responsible-vibe-21.2 --> |
| 41 | + |
| 42 | +### Implementation Specification |
| 43 | + |
| 44 | +#### 1. Global State Variable |
| 45 | +```typescript |
| 46 | +let workflowsEnabled = true; // Set by env var at startup, toggleable at runtime |
| 47 | +``` |
| 48 | + |
| 49 | +#### 2. Initialization |
| 50 | +Read `WORKFLOWS` env var at plugin startup: |
| 51 | +```typescript |
| 52 | +const envWorkflows = process.env.WORKFLOWS?.toLowerCase(); |
| 53 | +workflowsEnabled = envWorkflows === 'off' ? false : true; // default: on |
| 54 | +logger.info('Workflows initialized', { workflowsEnabled }); |
| 55 | +``` |
| 56 | + |
| 57 | +#### 3. User Command Definition |
| 58 | +File: `.opencode/commands/workflow.md` (template provided by plugin or user creates it) |
| 59 | +```markdown |
| 60 | +--- |
| 61 | +description: Enable/disable workflows for this session |
| 62 | +--- |
| 63 | +Toggle workflows: /workflow on or /workflow off or /wf on or /wf off |
| 64 | +``` |
| 65 | + |
| 66 | +#### 4. Command Interceptor Hook |
| 67 | +Implement `command.execute.before` hook: |
| 68 | +```typescript |
| 69 | +'command.execute.before': async (input, output) => { |
| 70 | + const cmd = input.command.toLowerCase(); |
| 71 | + const args = input.arguments?.toLowerCase().trim() || ''; |
| 72 | + |
| 73 | + if (cmd === 'workflow' || cmd === 'wf') { |
| 74 | + if (args === 'on') { |
| 75 | + workflowsEnabled = true; |
| 76 | + output.parts.push({ |
| 77 | + type: 'text', |
| 78 | + text: 'Workflows enabled for this session.' |
| 79 | + }); |
| 80 | + } else if (args === 'off') { |
| 81 | + workflowsEnabled = false; |
| 82 | + output.parts.push({ |
| 83 | + type: 'text', |
| 84 | + text: 'Workflows disabled for this session. Plugin will not inject instructions or enforce file restrictions.' |
| 85 | + }); |
| 86 | + } else { |
| 87 | + output.parts.push({ |
| 88 | + type: 'text', |
| 89 | + text: `Usage: /workflow on|off or /wf on|off\nCurrent state: ${workflowsEnabled ? 'enabled' : 'disabled'}` |
| 90 | + }); |
| 91 | + } |
| 92 | + logger.info('Workflows toggled', { workflowsEnabled, agent: input.sessionID }); |
| 93 | + } |
| 94 | +} |
| 95 | +``` |
| 96 | + |
| 97 | +#### 5. Hook Modifications |
| 98 | +Add check at start of these hooks: |
| 99 | +```typescript |
| 100 | +if (!workflowsEnabled) { |
| 101 | + logger.debug('Workflows disabled, skipping hook', { hookName }); |
| 102 | + return; |
| 103 | +} |
| 104 | +// ... existing logic |
| 105 | +``` |
| 106 | + |
| 107 | +Hooks to modify: |
| 108 | +- `chat.message` - Skip instruction injection |
| 109 | +- `tool.execute.before` - Skip file restriction checks |
| 110 | +- `experimental.session.compacting` - Skip compaction guidance |
| 111 | + |
| 112 | +#### 6. No Persistence Needed |
| 113 | +- ✅ No `.vibe/workflows-config.json` file |
| 114 | +- ✅ State lives in `workflowsEnabled` variable |
| 115 | +- ✅ Resets to env var value on next session |
| 116 | + |
| 117 | +### ✅ Completed |
| 118 | +- Simplified API: `/{workflow|wf} {on|off}` instead of complex enable/disable/status |
| 119 | +- Env var support at startup: `WORKFLOWS=on|off` |
| 120 | +- No persistence: in-memory state only |
| 121 | +- Helper functions not needed |
| 122 | + |
| 123 | +### Entrance Criteria for Code Phase |
| 124 | +- ✅ Implementation fully specified inline |
| 125 | +- ✅ API finalized: `/workflow on|off` and `/wf on|off` (command.execute.before hook intercepts) |
| 126 | +- ✅ Env var handling specified: `WORKFLOWS=on|off` at startup |
| 127 | +- ✅ No persistent state, pure in-memory toggle |
| 128 | + |
| 129 | +## Code |
| 130 | +<!-- beads-phase-id: responsible-vibe-21.3 --> |
| 131 | + |
| 132 | +### ✅ Completed Implementation |
| 133 | +1. **Global State**: Added `workflowsEnabled` variable, initialized from `WORKFLOWS` env var (default: true) |
| 134 | +2. **Command Interceptor Hook**: Implemented `command.execute.before` to handle `/workflow` and `/wf` commands with on/off arguments |
| 135 | +3. **Hook Modifications**: Added `if (!workflowsEnabled) return;` checks at start of: |
| 136 | + - `chat.message` - Skips instruction injection when disabled |
| 137 | + - `tool.execute.before` - Skips file restriction checks when disabled |
| 138 | + - `experimental.session.compacting` - Skips compaction guidance when disabled |
| 139 | +4. **Command Template**: Created `.opencode/commands/workflow.md` with usage documentation |
| 140 | + |
| 141 | +### ✅ Testing & Verification |
| 142 | +- ✅ Full project build succeeds (npm run build) |
| 143 | +- ✅ All 276 existing tests pass with no regressions |
| 144 | +- ✅ Code follows existing plugin patterns and conventions |
| 145 | +- ✅ Environment variable handling tested during initialization |
| 146 | +- ✅ No TypeScript compilation errors |
| 147 | + |
| 148 | +### Entrance Criteria for Commit Phase |
| 149 | +- ✅ All tests passing |
| 150 | +- ✅ Code follows existing plugin patterns |
| 151 | +- ✅ No regressions in other hooks |
| 152 | +- ✅ Build successful |
| 153 | + |
| 154 | +## Commit |
| 155 | +<!-- beads-phase-id: responsible-vibe-21.4 --> |
| 156 | + |
| 157 | +### ✅ STEP 1: Code Cleanup |
| 158 | +- ✅ Verified no debug output: No console.log, debugger, or temporary statements |
| 159 | +- ✅ No TODO/FIXME comments: All development markers removed |
| 160 | +- ✅ No commented-out code: Implementation is clean |
| 161 | +- ✅ Code follows patterns: Consistent with existing plugin hooks |
| 162 | + |
| 163 | +### ✅ STEP 2: Documentation Review |
| 164 | +- ✅ Long-term memory docs reviewed: `.vibe/docs/plugin-architecture-design.md` covers general plugin system |
| 165 | +- ✅ Plan file documents feature: `.vibe/development-plan-feat-opencode-enable-disable.md` contains complete feature spec |
| 166 | +- ✅ Command template documented: `.opencode/commands/workflow.md` includes usage and examples |
| 167 | +- ✅ Implementation matches documentation: All specs in plan file are implemented |
| 168 | + |
| 169 | +### ✅ STEP 3: Final Validation |
| 170 | +- ✅ All tests passing: 377 tests across all packages (full test suite run) |
| 171 | +- ✅ Build successful: npm run build completes without errors |
| 172 | +- ✅ No regressions: All tests remain green |
| 173 | +- ✅ Commit verified: Created with proper message and signatures |
| 174 | + |
| 175 | +### Summary of Changes |
| 176 | +**Files Modified:** |
| 177 | +- `packages/opencode-plugin/src/plugin.ts` - Added workflowsEnabled state, hooks, command interceptor |
| 178 | + |
| 179 | +**Files Created:** |
| 180 | +- `.opencode/commands/workflow.md` - Command template for users |
| 181 | +- `.vibe/development-plan-feat-opencode-enable-disable.md` - This plan file |
| 182 | + |
| 183 | +**Features Added:** |
| 184 | +1. Environment variable support: `WORKFLOWS=on|off` at startup |
| 185 | +2. User command support: `/workflow on|off` or `/wf on|off` during session |
| 186 | +3. Global enable/disable flag with runtime toggle capability |
| 187 | +4. All plugin hooks respect the enabled state |
| 188 | +5. Backward compatible: Workflows enabled by default |
| 189 | +6. No persistence: In-memory state resets on session restart |
| 190 | + |
| 191 | +--- |
| 192 | + |
| 193 | +## 🎯 Feature Complete |
| 194 | + |
| 195 | +Users can now disable the OpenCode workflows plugin in two ways: |
| 196 | + |
| 197 | +### Option 1: Environment Variable (Startup) |
| 198 | +```bash |
| 199 | +WORKFLOWS=off opencode |
| 200 | +``` |
| 201 | + |
| 202 | +### Option 2: User Command (Runtime) |
| 203 | +``` |
| 204 | +/workflow off # Disable workflows |
| 205 | +/workflow on # Enable workflows |
| 206 | +/wf off # Shorthand disable |
| 207 | +/wf on # Shorthand enable |
| 208 | +``` |
| 209 | + |
| 210 | +When disabled, the plugin behaves as if it was never registered - no instructions injected, no file restrictions enforced. |
| 211 | + |
| 212 | + |
| 213 | + |
| 214 | +--- |
| 215 | +*This plan is maintained by the LLM and uses beads CLI for task management. Tool responses provide guidance on which bd commands to use for task management.* |
0 commit comments