refactor: major codebase cleanup - BDD comments, file splitting, bug fixes (#1350)

* style(tests): normalize BDD comments from '// #given' to '// given'

- Replace 4,668 Python-style BDD comments across 107 test files
- Patterns changed: // #given -> // given, // #when -> // when, // #then -> // then
- Also handles no-space variants: //#given -> // given

* fix(rules-injector): prefer output.metadata.filePath over output.title

- Extract file path resolution to dedicated output-path.ts module
- Prefer metadata.filePath which contains actual file path
- Fall back to output.title only when metadata unavailable
- Fixes issue where rules weren't injected when tool output title was a label

* feat(slashcommand): add optional user_message parameter

- Add user_message optional parameter for command arguments
- Model can now call: command='publish' user_message='patch'
- Improves error messages with clearer format guidance
- Helps LLMs understand correct parameter usage

* feat(hooks): restore compaction-context-injector hook

- Restore hook deleted in cbbc7bd0 for session compaction context
- Injects 7 mandatory sections: User Requests, Final Goal, Work Completed,
  Remaining Tasks, Active Working Context, MUST NOT Do, Agent Verification State
- Re-register in hooks/index.ts and main plugin entry

* refactor(background-agent): split manager.ts into focused modules

- Extract constants.ts for TTL values and internal types (52 lines)
- Extract state.ts for TaskStateManager class (204 lines)
- Extract spawner.ts for task creation logic (244 lines)
- Extract result-handler.ts for completion handling (265 lines)
- Reduce manager.ts from 1377 to 755 lines (45% reduction)
- Maintain backward compatible exports

* refactor(agents): split prometheus-prompt.ts into subdirectory

- Move 1196-line prometheus-prompt.ts to prometheus/ subdirectory
- Organize prompt sections into separate files for maintainability
- Update agents/index.ts exports

* refactor(delegate-task): split tools.ts into focused modules

- Extract categories.ts for category definitions and routing
- Extract executor.ts for task execution logic
- Extract helpers.ts for utility functions
- Extract prompt-builder.ts for prompt construction
- Reduce tools.ts complexity with cleaner separation of concerns

* refactor(builtin-skills): split skills.ts into individual skill files

- Move each skill to dedicated file in skills/ subdirectory
- Create barrel export for backward compatibility
- Improve maintainability with focused skill modules

* chore: update import paths and lockfile

- Update prometheus import path after refactor
- Update bun.lock

* fix(tests): complete BDD comment normalization

- Fix remaining #when/#then patterns missed by initial sed
- Affected: state.test.ts, events.test.ts

---------

Co-authored-by: justsisyphus <justsisyphus@users.noreply.github.com>

src/plugin-handlers/config-handler.test.ts

@@ -107,7 +107,7 @@ afterEach(() => {
 
 describe("Plan agent demote behavior", () => {
   test("plan agent should be demoted to subagent mode when replacePlan is true", async () => {
-    // #given
+    // given
     const pluginConfig: OhMyOpenCodeConfig = {
       sisyphus_agent: {
         planner_enabled: true,
@@ -133,10 +133,10 @@ describe("Plan agent demote behavior", () => {
       },
     })
 
-    // #when
+    // when
     await handler(config)
 
-    // #then
+    // then
     const agents = config.agent as Record<string, { mode?: string; name?: string }>
     expect(agents.plan).toBeDefined()
     expect(agents.plan.mode).toBe("subagent")
@@ -144,7 +144,7 @@ describe("Plan agent demote behavior", () => {
   })
 
   test("prometheus should have mode 'all' to be callable via delegate_task", async () => {
-    // #given
+    // given
     const pluginConfig: OhMyOpenCodeConfig = {
       sisyphus_agent: {
         planner_enabled: true,
@@ -163,10 +163,10 @@ describe("Plan agent demote behavior", () => {
       },
     })
 
-    // #when
+    // when
     await handler(config)
 
-    // #then
+    // then
     const agents = config.agent as Record<string, { mode?: string }>
     expect(agents.prometheus).toBeDefined()
     expect(agents.prometheus.mode).toBe("all")
@@ -175,32 +175,32 @@ describe("Plan agent demote behavior", () => {
 
 describe("Prometheus category config resolution", () => {
   test("resolves ultrabrain category config", () => {
-    // #given
+    // given
     const categoryName = "ultrabrain"
 
-    // #when
+    // when
     const config = resolveCategoryConfig(categoryName)
 
-    // #then
+    // then
     expect(config).toBeDefined()
     expect(config?.model).toBe("openai/gpt-5.2-codex")
     expect(config?.variant).toBe("xhigh")
   })
 
   test("resolves visual-engineering category config", () => {
-    // #given
+    // given
     const categoryName = "visual-engineering"
 
-    // #when
+    // when
     const config = resolveCategoryConfig(categoryName)
 
-    // #then
+    // then
     expect(config).toBeDefined()
     expect(config?.model).toBe("google/gemini-3-pro")
   })
 
   test("user categories override default categories", () => {
-    // #given
+    // given
     const categoryName = "ultrabrain"
     const userCategories: Record<string, CategoryConfig> = {
       ultrabrain: {
@@ -209,28 +209,28 @@ describe("Prometheus category config resolution", () => {
       },
     }
 
-    // #when
+    // when
     const config = resolveCategoryConfig(categoryName, userCategories)
 
-    // #then
+    // then
     expect(config).toBeDefined()
     expect(config?.model).toBe("google/antigravity-claude-opus-4-5-thinking")
     expect(config?.temperature).toBe(0.1)
   })
 
   test("returns undefined for unknown category", () => {
-    // #given
+    // given
     const categoryName = "nonexistent-category"
 
-    // #when
+    // when
     const config = resolveCategoryConfig(categoryName)
 
-    // #then
+    // then
     expect(config).toBeUndefined()
   })
 
   test("falls back to default when user category has no entry", () => {
-    // #given
+    // given
     const categoryName = "ultrabrain"
     const userCategories: Record<string, CategoryConfig> = {
       "visual-engineering": {
@@ -238,17 +238,17 @@ describe("Prometheus category config resolution", () => {
       },
     }
 
-    // #when
+    // when
     const config = resolveCategoryConfig(categoryName, userCategories)
 
-    // #then - falls back to DEFAULT_CATEGORIES
+    // then - falls back to DEFAULT_CATEGORIES
     expect(config).toBeDefined()
     expect(config?.model).toBe("openai/gpt-5.2-codex")
     expect(config?.variant).toBe("xhigh")
   })
 
   test("preserves all category properties (temperature, top_p, tools, etc.)", () => {
-    // #given
+    // given
     const categoryName = "custom-category"
     const userCategories: Record<string, CategoryConfig> = {
       "custom-category": {
@@ -260,10 +260,10 @@ describe("Prometheus category config resolution", () => {
       },
     }
 
-    // #when
+    // when
     const config = resolveCategoryConfig(categoryName, userCategories)
 
-    // #then
+    // then
     expect(config).toBeDefined()
     expect(config?.model).toBe("test/model")
     expect(config?.temperature).toBe(0.5)
@@ -275,7 +275,7 @@ describe("Prometheus category config resolution", () => {
 
 describe("Prometheus direct override priority over category", () => {
   test("direct reasoningEffort takes priority over category reasoningEffort", async () => {
-    // #given - category has reasoningEffort=xhigh, direct override says "low"
+    // given - category has reasoningEffort=xhigh, direct override says "low"
     const pluginConfig: OhMyOpenCodeConfig = {
       sisyphus_agent: {
         planner_enabled: true,
@@ -306,17 +306,17 @@ describe("Prometheus direct override priority over category", () => {
       },
     })
 
-    // #when
+    // when
     await handler(config)
 
-    // #then - direct override's reasoningEffort wins
+    // then - direct override's reasoningEffort wins
     const agents = config.agent as Record<string, { reasoningEffort?: string }>
     expect(agents.prometheus).toBeDefined()
     expect(agents.prometheus.reasoningEffort).toBe("low")
   })
 
   test("category reasoningEffort applied when no direct override", async () => {
-    // #given - category has reasoningEffort but no direct override
+    // given - category has reasoningEffort but no direct override
     const pluginConfig: OhMyOpenCodeConfig = {
       sisyphus_agent: {
         planner_enabled: true,
@@ -346,17 +346,17 @@ describe("Prometheus direct override priority over category", () => {
       },
     })
 
-    // #when
+    // when
     await handler(config)
 
-    // #then - category's reasoningEffort is applied
+    // then - category's reasoningEffort is applied
     const agents = config.agent as Record<string, { reasoningEffort?: string }>
     expect(agents.prometheus).toBeDefined()
     expect(agents.prometheus.reasoningEffort).toBe("high")
   })
 
   test("direct temperature takes priority over category temperature", async () => {
-    // #given
+    // given
     const pluginConfig: OhMyOpenCodeConfig = {
       sisyphus_agent: {
         planner_enabled: true,
@@ -387,10 +387,10 @@ describe("Prometheus direct override priority over category", () => {
       },
     })
 
-    // #when
+    // when
     await handler(config)
 
-    // #then - direct temperature wins over category
+    // then - direct temperature wins over category
     const agents = config.agent as Record<string, { temperature?: number }>
     expect(agents.prometheus).toBeDefined()
     expect(agents.prometheus.temperature).toBe(0.1)
@@ -399,7 +399,7 @@ describe("Prometheus direct override priority over category", () => {
 
 describe("Deadlock prevention - fetchAvailableModels must not receive client", () => {
   test("fetchAvailableModels should be called with undefined client to prevent deadlock during plugin init", async () => {
-    // #given - This test ensures we don't regress on issue #1301
+    // given - This test ensures we don't regress on issue #1301
     // Passing client to fetchAvailableModels during config handler causes deadlock:
     // - Plugin init waits for server response (client.provider.list())
     // - Server waits for plugin init to complete before handling requests
@@ -427,10 +427,10 @@ describe("Deadlock prevention - fetchAvailableModels must not receive client", (
       },
     })
 
-    // #when
+    // when
     await handler(config)
 
-    // #then - fetchAvailableModels must be called with undefined as first argument (no client)
+    // then - fetchAvailableModels must be called with undefined as first argument (no client)
     // This prevents the deadlock described in issue #1301
     expect(fetchSpy).toHaveBeenCalled()
     const firstCallArgs = fetchSpy.mock.calls[0]

src/plugin-handlers/config-handler.ts

@@ -30,7 +30,7 @@ import { getOpenCodeConfigPaths } from "../shared/opencode-config-dir";
 import { migrateAgentConfig } from "../shared/permission-compat";
 import { AGENT_NAME_MAP } from "../shared/migration";
 import { AGENT_MODEL_REQUIREMENTS } from "../shared/model-requirements";
-import { PROMETHEUS_SYSTEM_PROMPT, PROMETHEUS_PERMISSION } from "../agents/prometheus-prompt";
+import { PROMETHEUS_SYSTEM_PROMPT, PROMETHEUS_PERMISSION } from "../agents/prometheus";
 import { DEFAULT_CATEGORIES } from "../tools/delegate-task/constants";
 import type { ModelCacheState } from "../plugin-state";
 import type { CategoryConfig } from "../config/schema";