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/features/claude-code-session-state/state.test.ts

@@ -11,124 +11,124 @@ import {
 
 describe("claude-code-session-state", () => {
   beforeEach(() => {
-    // #given - clean state before each test
+    // given - clean state before each test
     _resetForTesting()
   })
 
   afterEach(() => {
-    // #then - cleanup after each test to prevent pollution
+    // then - cleanup after each test to prevent pollution
     _resetForTesting()
   })
 
   describe("setSessionAgent", () => {
     test("should store agent for session", () => {
-      // #given
+      // given
       const sessionID = "test-session-1"
       const agent = "Prometheus (Planner)"
 
-      // #when
+      // when
       setSessionAgent(sessionID, agent)
 
-      // #then
+      // then
       expect(getSessionAgent(sessionID)).toBe(agent)
     })
 
     test("should NOT overwrite existing agent (first-write wins)", () => {
-      // #given
+      // given
       const sessionID = "test-session-1"
       setSessionAgent(sessionID, "Prometheus (Planner)")
 
-      // #when - try to overwrite
+      // when - try to overwrite
       setSessionAgent(sessionID, "sisyphus")
 
-      // #then - first agent preserved
+      // then - first agent preserved
       expect(getSessionAgent(sessionID)).toBe("Prometheus (Planner)")
     })
 
     test("should return undefined for unknown session", () => {
-      // #given - no session set
+      // given - no session set
 
-      // #when / #then
+      // when / then
       expect(getSessionAgent("unknown-session")).toBeUndefined()
     })
   })
 
   describe("updateSessionAgent", () => {
     test("should overwrite existing agent", () => {
-      // #given
+      // given
       const sessionID = "test-session-1"
       setSessionAgent(sessionID, "Prometheus (Planner)")
 
-      // #when - force update
+      // when - force update
       updateSessionAgent(sessionID, "sisyphus")
 
-      // #then
+      // then
       expect(getSessionAgent(sessionID)).toBe("sisyphus")
     })
   })
 
   describe("clearSessionAgent", () => {
     test("should remove agent from session", () => {
-      // #given
+      // given
       const sessionID = "test-session-1"
       setSessionAgent(sessionID, "Prometheus (Planner)")
       expect(getSessionAgent(sessionID)).toBe("Prometheus (Planner)")
 
-      // #when
+      // when
       clearSessionAgent(sessionID)
 
-      // #then
+      // then
       expect(getSessionAgent(sessionID)).toBeUndefined()
     })
   })
 
   describe("mainSessionID", () => {
     test("should store and retrieve main session ID", () => {
-      // #given
+      // given
       const mainID = "main-session-123"
 
-      // #when
+      // when
       setMainSession(mainID)
 
-      // #then
+      // then
       expect(getMainSessionID()).toBe(mainID)
     })
 
     test("should return undefined when not set", () => {
-      // #given - explicit reset to ensure clean state (parallel test isolation)
+      // given - explicit reset to ensure clean state (parallel test isolation)
       _resetForTesting()
-      // #then
+      // then
       expect(getMainSessionID()).toBeUndefined()
     })
   })
 
   describe("prometheus-md-only integration scenario", () => {
     test("should correctly identify Prometheus agent for permission checks", () => {
-      // #given - Prometheus session
+      // given - Prometheus session
       const sessionID = "test-prometheus-session"
       const prometheusAgent = "Prometheus (Planner)"
 
-      // #when - agent is set (simulating chat.message hook)
+      // when - agent is set (simulating chat.message hook)
       setSessionAgent(sessionID, prometheusAgent)
 
-      // #then - getSessionAgent returns correct agent for prometheus-md-only hook
+      // then - getSessionAgent returns correct agent for prometheus-md-only hook
       const agent = getSessionAgent(sessionID)
       expect(agent).toBe("Prometheus (Planner)")
       expect(["Prometheus (Planner)"].includes(agent!)).toBe(true)
     })
 
     test("should return undefined when agent not set (bug scenario)", () => {
-      // #given - session exists but no agent set (the bug)
+      // given - session exists but no agent set (the bug)
       const sessionID = "test-prometheus-session"
 
-      // #when / #then - this is the bug: agent is undefined
+      // when / then - this is the bug: agent is undefined
       expect(getSessionAgent(sessionID)).toBeUndefined()
     })
   })
 
   describe("issue #893: custom agent switch reset", () => {
     test("should preserve custom agent when default agent is sent on subsequent messages", () => {
-      // #given - user switches to custom agent "MyCustomAgent"
+      // given - user switches to custom agent "MyCustomAgent"
       const sessionID = "test-session-custom"
       const customAgent = "MyCustomAgent"
       const defaultAgent = "sisyphus"
@@ -137,27 +137,27 @@ describe("claude-code-session-state", () => {
       setSessionAgent(sessionID, customAgent)
       expect(getSessionAgent(sessionID)).toBe(customAgent)
 
-      // #when - first message after switch sends default agent
+      // when - first message after switch sends default agent
       // This simulates the bug: input.agent = "Sisyphus" on first message
       // Using setSessionAgent (first-write wins) should preserve custom agent
       setSessionAgent(sessionID, defaultAgent)
 
-      // #then - custom agent should be preserved, NOT overwritten
+      // then - custom agent should be preserved, NOT overwritten
       expect(getSessionAgent(sessionID)).toBe(customAgent)
     })
 
     test("should allow explicit agent update via updateSessionAgent", () => {
-      // #given - custom agent is set
+      // given - custom agent is set
       const sessionID = "test-session-explicit"
       const customAgent = "MyCustomAgent"
       const newAgent = "AnotherAgent"
 
       setSessionAgent(sessionID, customAgent)
 
-      // #when - explicit update (user intentionally switches)
+      // when - explicit update (user intentionally switches)
       updateSessionAgent(sessionID, newAgent)
 
-      // #then - should be updated
+      // then - should be updated
       expect(getSessionAgent(sessionID)).toBe(newAgent)
     })
   })