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/tools/slashcommand/tools.test.ts

@@ -30,21 +30,21 @@ function createMockSkill(name: string, description = ""): LoadedSkill {
 
 describe("slashcommand tool - synchronous description", () => {
   it("includes available_skills immediately when commands and skills are pre-provided", () => {
-    // #given
+    // given
     const commands = [createMockCommand("commit", "Create a git commit")]
     const skills = [createMockSkill("playwright", "Browser automation via Playwright MCP")]
 
-    // #when
+    // when
     const tool = createSlashcommandTool({ commands, skills })
 
-    // #then
+    // then
     expect(tool.description).toContain("<available_skills>")
     expect(tool.description).toContain("commit")
     expect(tool.description).toContain("playwright")
   })
 
   it("includes all pre-provided commands and skills in description immediately", () => {
-    // #given
+    // given
     const commands = [
       createMockCommand("commit", "Git commit"),
       createMockCommand("plan", "Create plan"),
@@ -55,10 +55,10 @@ describe("slashcommand tool - synchronous description", () => {
       createMockSkill("git-master", "Git operations"),
     ]
 
-    // #when
+    // when
     const tool = createSlashcommandTool({ commands, skills })
 
-    // #then
+    // then
     expect(tool.description).toContain("commit")
     expect(tool.description).toContain("plan")
     expect(tool.description).toContain("playwright")
@@ -67,10 +67,23 @@ describe("slashcommand tool - synchronous description", () => {
   })
 
   it("shows prefix-only description when both commands and skills are empty", () => {
-    // #given / #when
+    // given / #when
     const tool = createSlashcommandTool({ commands: [], skills: [] })
 
-    // #then - even with no items, description should be built synchronously (not just prefix)
+    // then - even with no items, description should be built synchronously (not just prefix)
     expect(tool.description).toContain("Load a skill")
   })
+
+  it("includes user_message parameter documentation in description", () => {
+    // given
+    const commands = [createMockCommand("publish", "Publish package")]
+    const skills: LoadedSkill[] = []
+
+    // when
+    const tool = createSlashcommandTool({ commands, skills })
+
+    // then
+    expect(tool.description).toContain("user_message")
+    expect(tool.description).toContain("command='publish' user_message='patch'")
+  })
 })

src/tools/slashcommand/tools.ts

@@ -100,7 +100,7 @@ function skillToCommandInfo(skill: LoadedSkill): CommandInfo {
   }
 }
 
-async function formatLoadedCommand(cmd: CommandInfo): Promise<string> {
+async function formatLoadedCommand(cmd: CommandInfo, userMessage?: string): Promise<string> {
   const sections: string[] = []
 
   sections.push(`# /${cmd.name} Command\n`)
@@ -113,6 +113,10 @@ async function formatLoadedCommand(cmd: CommandInfo): Promise<string> {
     sections.push(`**Usage**: /${cmd.name} ${cmd.metadata.argumentHint}\n`)
   }
 
+  if (userMessage) {
+    sections.push(`**Arguments**: ${userMessage}\n`)
+  }
+
   if (cmd.metadata.model) {
     sections.push(`**Model**: ${cmd.metadata.model}\n`)
   }
@@ -137,7 +141,14 @@ async function formatLoadedCommand(cmd: CommandInfo): Promise<string> {
   const commandDir = cmd.path ? dirname(cmd.path) : process.cwd()
   const withFileRefs = await resolveFileReferencesInText(content, commandDir)
   const resolvedContent = await resolveCommandsInText(withFileRefs)
-  sections.push(resolvedContent.trim())
+  
+  // Substitute user_message into content if provided
+  let finalContent = resolvedContent.trim()
+  if (userMessage) {
+    finalContent = finalContent.replace(/\$\{user_message\}/g, userMessage)
+  }
+  
+  sections.push(finalContent)
 
   return sections.join("\n")
 }
@@ -160,10 +171,15 @@ function formatCommandList(items: CommandInfo[]): string {
   return lines.join("\n")
 }
 
-const TOOL_DESCRIPTION_PREFIX = `Load a skill to get detailed instructions for a specific task.
+const TOOL_DESCRIPTION_PREFIX = `Load a skill or execute a command to get detailed instructions for a specific task.
 
-Skills provide specialized knowledge and step-by-step guidance.
-Use this when a task matches an available skill's description.
+Skills and commands provide specialized knowledge and step-by-step guidance.
+Use this when a task matches an available skill's or command's description.
+
+**How to use:**
+- Call with command name only: command='publish'
+- Call with command and arguments: command='publish' user_message='patch'
+- The tool will return detailed instructions for the command with your arguments substituted.
 `
 
 function buildDescriptionFromItems(items: CommandInfo[]): string {
@@ -226,7 +242,13 @@ export function createSlashcommandTool(options: SlashcommandToolOptions = {}): T
       command: tool.schema
         .string()
         .describe(
-          "The slash command to execute (without the leading slash). E.g., 'commit', 'plan', 'execute'."
+          "The slash command name (without leading slash). E.g., 'publish', 'commit', 'plan'"
+        ),
+      user_message: tool.schema
+        .string()
+        .optional()
+        .describe(
+          "Optional arguments or context to pass to the command. E.g., for '/publish patch', command='publish' user_message='patch'"
         ),
     },
 
@@ -244,7 +266,7 @@ export function createSlashcommandTool(options: SlashcommandToolOptions = {}): T
       )
 
       if (exactMatch) {
-        return await formatLoadedCommand(exactMatch)
+        return await formatLoadedCommand(exactMatch, args.user_message)
       }
 
       const partialMatches = allItems.filter((cmd) =>
@@ -254,7 +276,7 @@ export function createSlashcommandTool(options: SlashcommandToolOptions = {}): T
       if (partialMatches.length > 0) {
         const matchList = partialMatches.map((cmd) => `/${cmd.name}`).join(", ")
         return (
-          `No exact match for "/${cmdName}\". Did you mean: ${matchList}?\n\n` +
+          `No exact match for "/${cmdName}". Did you mean: ${matchList}?\n\n` +
           formatCommandList(allItems)
         )
       }