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/shared/permission-compat.test.ts

@@ -9,44 +9,44 @@ import {
 describe("permission-compat", () => {
   describe("createAgentToolRestrictions", () => {
     test("returns permission format with deny values", () => {
-      // #given tools to restrict
-      // #when creating restrictions
+      // given tools to restrict
+      // when creating restrictions
       const result = createAgentToolRestrictions(["write", "edit"])
 
-      // #then returns permission format
+      // then returns permission format
       expect(result).toEqual({
         permission: { write: "deny", edit: "deny" },
       })
     })
 
     test("returns empty permission for empty array", () => {
-      // #given empty tools array
-      // #when creating restrictions
+      // given empty tools array
+      // when creating restrictions
       const result = createAgentToolRestrictions([])
 
-      // #then returns empty permission
+      // then returns empty permission
       expect(result).toEqual({ permission: {} })
     })
   })
 
   describe("createAgentToolAllowlist", () => {
     test("returns wildcard deny with explicit allow", () => {
-      // #given tools to allow
-      // #when creating allowlist
+      // given tools to allow
+      // when creating allowlist
       const result = createAgentToolAllowlist(["read"])
 
-      // #then returns wildcard deny with read allow
+      // then returns wildcard deny with read allow
       expect(result).toEqual({
         permission: { "*": "deny", read: "allow" },
       })
     })
 
     test("returns wildcard deny with multiple allows", () => {
-      // #given multiple tools to allow
-      // #when creating allowlist
+      // given multiple tools to allow
+      // when creating allowlist
       const result = createAgentToolAllowlist(["read", "glob"])
 
-      // #then returns wildcard deny with both allows
+      // then returns wildcard deny with both allows
       expect(result).toEqual({
         permission: { "*": "deny", read: "allow", glob: "allow" },
       })
@@ -55,13 +55,13 @@ describe("permission-compat", () => {
 
   describe("migrateToolsToPermission", () => {
     test("converts boolean tools to permission values", () => {
-      // #given tools config
+      // given tools config
       const tools = { write: false, edit: true, bash: false }
 
-      // #when migrating
+      // when migrating
       const result = migrateToolsToPermission(tools)
 
-      // #then converts correctly
+      // then converts correctly
       expect(result).toEqual({
         write: "deny",
         edit: "allow",
@@ -72,23 +72,23 @@ describe("permission-compat", () => {
 
   describe("migrateAgentConfig", () => {
     test("migrates tools to permission", () => {
-      // #given config with tools
+      // given config with tools
       const config = {
         model: "test",
         tools: { write: false, edit: false },
       }
 
-      // #when migrating
+      // when migrating
       const result = migrateAgentConfig(config)
 
-      // #then converts to permission
+      // then converts to permission
       expect(result.tools).toBeUndefined()
       expect(result.permission).toEqual({ write: "deny", edit: "deny" })
       expect(result.model).toBe("test")
     })
 
     test("preserves other config fields", () => {
-      // #given config with other fields
+      // given config with other fields
       const config = {
         model: "test",
         temperature: 0.5,
@@ -96,38 +96,38 @@ describe("permission-compat", () => {
         tools: { write: false },
       }
 
-      // #when migrating
+      // when migrating
       const result = migrateAgentConfig(config)
 
-      // #then preserves other fields
+      // then preserves other fields
       expect(result.model).toBe("test")
       expect(result.temperature).toBe(0.5)
       expect(result.prompt).toBe("hello")
     })
 
     test("merges existing permission with migrated tools", () => {
-      // #given config with both tools and permission
+      // given config with both tools and permission
       const config = {
         tools: { write: false },
         permission: { bash: "deny" as const },
       }
 
-      // #when migrating
+      // when migrating
       const result = migrateAgentConfig(config)
 
-      // #then merges permission (existing takes precedence)
+      // then merges permission (existing takes precedence)
       expect(result.tools).toBeUndefined()
       expect(result.permission).toEqual({ write: "deny", bash: "deny" })
     })
 
     test("returns unchanged config if no tools", () => {
-      // #given config without tools
+      // given config without tools
       const config = { model: "test", permission: { edit: "deny" as const } }
 
-      // #when migrating
+      // when migrating
       const result = migrateAgentConfig(config)
 
-      // #then returns unchanged
+      // then returns unchanged
       expect(result).toEqual(config)
     })
   })